Gas Town Mol Mall 设计：为公式打造的可发现、可共享、可验证的注册中心

Gas Town Mol Mall 设计：为公式打造的可发现、可共享、可验证的注册中心

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown

本文解读 Mol Mall 设计文档 及其配套的 Formula Resolution 架构，阐述 Gas Town 如何将本地公式（formula）扩展为类 npm / Terraform Registry 的公式市场。文中将区分"当前已实现"（Phase 1 本地公式）与"规划愿景"（Phase 2-5 注册表、发布、联邦）两层内容，并结合仓库源码（如 internal/formula/embed.go、internal/cmd/formula.go）说明现有实现与未来目标的对应关系。

设计前提：这是一份愿景文档，不是已上线功能

在深入技术细节之前，必须先明确文档状态。docs/design/mol-mall-design.md开头明确标注：

Status: Vision document— Phase 1 (local formulas) exists. Phases 2-5 (registry, publishing, federation) are not implemented.

这意味着：

• Phase 1（本地公式 + 三层解析）已经在仓库中实现，证据见 internal/formula/embed.go 中的ResolveFormulaContent与ProvisionFormulas，以及gt formula list / show / run / create等命令（internal/cmd/formula.go）；
• Phase 2-5（导出/导入、公共注册表、企业私有注册表、HOP 联邦）属于设计蓝图，其中出现的gt formula install / publish / upgrade / login、hop://URI、锁文件.lock.json等均为目标形态，仓库中尚无对应实现。

阅读本文时请带着这层"现状 vs 愿景"的区分，这既是理解该设计文档的正确姿势，也是评估 Gas Town 公式体系演进路线图的起点。

愿景：把公式变成可流通的"商品"

Mol Mall 的核心一句话是：Gas Town 公式的市场（marketplace for Gas Town formulas）。设计文档用两个类比锚定定位：

• Think npm for molecules—— 像 npm 分发 JavaScript 包一样分发 Gas Town 的分子（molecule）工作流；
• Terraform Registry for workflows—— 像 Terraform Registry 沉淀基础设施模块一样沉淀工作流模板。

文档中的一句话愿景颇具画面感：

"Cook a formula, sling it to a polecat, the witness watches, refinery merges." What if you could browse a mall of formulas, install one, and immediately have your polecats executing world-class workflows?

翻译成可操作的场景：一个运维团队把"code review""security audit""deploy to K8s"这类工作流写成公式，发布到 Mol Mall，其他安装者一条命令装好，本地的 polecat（执行代理）立刻开始按这套世界级工作流干活。

网络效应（Network Effect）

设计文档给出了公式分发背后的增长逻辑：一个设计良好的公式每多一个采纳者，就产生三重正向收益——

1. 更多代理在执行被验证过的工作流（more agents executing proven workflows）；
2. 产生更多结构化、可追踪的工作产出（more structured, trackable work output）；
3. 更好的能力路由（better capability routing）—— 在某个公式上有成功执行记录的代理，会被优先分派同类工作。

这正是后面"能力标签 + 代理问责"两节的设计动机：没有能力标签，就无法做语义化检索；没有执行记录，就无法做基于战绩的路由。

架构：三类注册表

Mol Mall 的架构蓝图将注册表划分为三个层次：

PUBLIC REGISTRY (molmall.gastown.io) ├── Community formulas (MIT licensed) ├── Official Gas Town formulas (blessed) ├── Verified publisher formulas └── Open contribution model PRIVATE REGISTRY (self-hosted) ├── Organization-specific formulas ├── Proprietary workflows ├── Internal deployment patterns └── Enterprise compliance formulas FEDERATED REGISTRY (HOP future) ├── Cross-organization discovery ├── Skill-based search ├── Attribution chain tracking └── hop:// URI resolution

• 公共注册表：面向社区开放，默认 MIT 许可，官方公式（blessed）与其他发布者的验证公式共存；
• 私有注册表：组织自托管，承载专有工作流、内部部署模式与企业合规公式，是 Phase 4 企业特性的落点；
• 联邦注册表：基于 HOP（Highway Operations Protocol）实现跨组织发现，是 Phase 5 的远期形态。

值得注意的是，这个"公共/私有/联邦"三层结构，与仓库中已实现的三层本地解析结构（rig > town > system）形成了清晰的呼应：本地解析解决"公式从哪来"，注册表体系解决"公式如何传播"。二者通过 docs/design/formula-resolution.md 中"Mol Mall ready"的设计目标衔接起来。

URI Scheme：用 hop:// 标识一个公式

为了让公式在任意注册表之间可引用，Mol Mall 设计了基于 HOP 的 URI 方案：

hop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0 └──────────────────┘ └──────────────┘ └───┘ registry host formula name version # Short forms mol-polecat-work # Default registry, latest version mol-polecat-work@4 # Major version mol-polecat-work@4.0.0 # Exact version @acme/mol-deploy # Scoped to publisher hop://acme.corp/formulas/mol-deploy # Full HOP URI

设计要点：

版本粒度语义与 docs/design/formula-resolution.md 中规划的本地版本解析（bd cook mol-polecat-work@4、@4.0.0、@latest）保持一致 —— 本地与远端共用同一套"名称 + 版本"心智模型，这是设计上刻意为之的一致性。

Registry API：OpenAPI 风格的端点规划

设计文档为注册表服务器规划了完整的 HTTP API（尚未实现），核心端点如下：

GET /formulas # List all formulas Query: - q: string # Search query - capabilities: string[] # Filter by capability tags - author: string # Filter by author - limit: int - offset: int Response: formulas: - name: mol-polecat-work version: 4.0.0 description: "Full polecat work lifecycle..." author: steve@gastown.io downloads: 12543 capabilities: [go, testing, code-review] GET /formulas/{name} # Get formula metadata Response: name: mol-polecat-work versions: [4.0.0, 3.2.1, 3.2.0, ...] latest: 4.0.0 author: steve@gastown.io repository: https://github.com/steveyegge/gastown license: MIT capabilities: primary: [go, testing] secondary: [git, code-review] stats: downloads: 12543 stars: 234 used_by: 89 # towns using this formula GET /formulas/{name}/{version} # Get specific version Response: name: mol-polecat-work version: 4.0.0 checksum: sha256:abc123... signature: <optional PGP signature> content: <base64 or URL to .formula.toml> changelog: "Added self-cleaning model..." published_at: 2026-01-10T00:00:00Z POST /formulas # Publish formula (authenticated) Body: name: mol-my-workflow version: 1.0.0 content: <formula TOML> changelog: "Initial release" Auth: Bearer token (linked to HOP identity) GET /formulas/{name}/{version}/download # Download formula content Response: raw .formula.toml content

接口设计透露出三个关键决策：

1. 版本不可变：GET /formulas/{name}/{version}返回checksum（sha256）与可选 PGPsignature，与锁文件、安装流程中的"校验和验证"环节配套，保证下载内容与发布内容一致；
2. 能力标签进入查询面：GET /formulas支持capabilities过滤，说明能力标签不只是元数据装饰，而是检索的一等公民，为"按能力找公式"提供接口基础；
3. 统计信息驱动排名：downloads / stars / used_by三项指标构成排序依据，对应信任等级中的"更高搜索排名"。

Formula Package 格式：从单文件到 Bundle

Mol Mall 的公式包有两种形态，与当前仓库中的公式文件格式天然衔接。

简单形态：单个 .formula.toml 文件

大多数公式就是一个 TOML 文件。目标安装命令与落点：

gt formula install mol-polecat-code-review # Downloads mol-polecat-code-review.formula.toml to ~/gt/.beads/formulas/

注意目标落点~/gt/.beads/formulas/—— 这正是 docs/design/formula-resolution.md 中定义的Tier 2（town 级）目录。设计意图非常明确：从 Mol Mall 安装的公式落在 town 层，从而在不改动项目仓库的前提下覆盖系统内置版本，同时被同一用户的所有项目共享。

复杂形态：Formula Bundle

需要附带脚本、模板、配置的公式打包为 bundle 目录：

mol-deploy-k8s.formula.bundle/ ├── formula.toml # Main formula ├── templates/ │ ├── deployment.yaml.tmpl │ └── service.yaml.tmpl ├── scripts/ │ └── healthcheck.sh └── README.md

Bundle 以 tarball 分发：

# Bundles are tarballs mol-deploy-k8s-1.0.0.bundle.tar.gz

安装后解压到独立目录：

gt formula install mol-deploy-k8s # Extracts to ~/gt/.beads/formulas/mol-deploy-k8s/ # formula.toml is at mol-deploy-k8s/formula.toml

这一设计为仓库中internal/formula/formulas/下的现有公式（如 mol-polecat-work.formula.toml、code-review.formula.toml）预留了"需要附带文件"的升级路径 —— 当前这些公式都是单文件内联所有步骤说明，而 bundle 形态允许公式携带渲染模板与辅助脚本。

安装流程：解析 → 下载 → 校验 → 落盘

基础安装

设计文档描绘的目标交互（Phase 3 之后）：

$ gt formula install mol-polecat-code-review Resolving mol-polecat-code-review... Registry: molmall.gastown.io Version: 1.2.0 (latest) Author: steve@gastown.io Skills: code-review, security Downloading... ████████████████████ 100% Verifying checksum... ✓ Installed to: ~/gt/.beads/formulas/mol-polecat-code-review.formula.toml

流程五步：解析（解析注册表与版本）→ 展示元信息 → 下载 → 校验 checksum → 写入 town 层公式目录。

版本固定（Version Pinning）

$ gt formula install mol-polecat-work@4.0.0 Installing mol-polecat-work@4.0.0 (pinned)... ✓ Installed $ gt formula list --installed mol-polecat-work 4.0.0 [pinned] mol-polecat-code-review 1.2.0 [latest]

--installed视角只展示 town 层已安装的公式，并用[pinned]/[latest]标注固定策略。

升级流程（Upgrade Flow）

$ gt formula upgrade mol-polecat-code-review Checking for updates... Current: 1.2.0 Latest: 1.3.0 Changelog for 1.3.0: - Added security focus option - Improved test coverage step Upgrade? [y/N] y Downloading... ✓ Installed: mol-polecat-code-review@1.3.0

升级前先展示 changelog，并要求显式确认（默认[y/N]），防止静默破坏性更新。

锁文件（Lock File）

与 npm 的package-lock.json类似，Mol Mall 规划了~/gt/.beads/formulas/.lock.json：

{ "version": 1, "formulas": { "mol-polecat-work": { "version": "4.0.0", "pinned": true, "checksum": "sha256:abc123...", "installed_at": "2026-01-10T00:00:00Z", "source": "hop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0" }, "mol-polecat-code-review": { "version": "1.3.0", "pinned": false, "checksum": "sha256:def456...", "installed_at": "2026-01-10T12:00:00Z", "source": "hop://molmall.gastown.io/formulas/mol-polecat-code-review@1.3.0" } } }

源码对照：锁文件的字段设计（版本、checksum、安装时间、来源 URI）与仓库中已实现的.installed.json高度同构。在 internal/formula/embed.go 中，InstalledRecord记录了filename -> sha256的映射，并配套实现了：

• ProvisionFormulas—— 安装时把内嵌公式部署到.beads/formulas/，已存在的文件跳过（不覆盖用户定制）；
• CheckFormulaHealth—— 依据"内嵌哈希 vs 安装记录哈希 vs 磁盘当前哈希"三者关系，把公式状态归类为ok / outdated / modified / missing / new / untracked / error；
• UpdateFormulas—— 只更新outdated、missing、untracked状态的公式，跳过用户修改过的（modified）。

也就是说，当前仓库已经用.installed.json实现了"记录安装来源哈希、检测漂移、保护用户定制"的本地等价物；Mol Mall 的.lock.json是这一机制的远端注册表扩展版（额外增加pinned标记与sourceURI）。

发布流程：从登录到信任等级

首次初始化

$ gt formula publish --init Setting up Mol Mall publishing... 1. Create account at https://molmall.gastown.io/signup 2. Generate API token at https://molmall.gastown.io/settings/tokens 3. Run: gt formula login $ gt formula login Token: ******** Logged in as: steve@gastown.io

认证模型为Bearer token 绑定 HOP 身份（与前面 Registry API 的Auth: Bearer token呼应），token 与发布者身份绑定，是后续信任等级的基础。

发布前的 Pre-flight 检查

$ gt formula publish mol-polecat-work Publishing mol-polecat-work... Pre-flight checks: ✓ formula.toml is valid ✓ Version 4.0.0 not yet published ✓ Required fields present (name, version, description) ✓ Skills declared Publish to molmall.gastown.io? [y/N] y Uploading... ✓ Published: hop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0 View at: https://molmall.gastown.io/formulas/mol-polecat-work

四项 pre-flight 检查中，"formula.toml is valid"在本地已有对应实现 —— 仓库的 internal/formula/parser.go 实现了完整的 TOML 解析与校验：Parse会先inferType（根据内容推断公式类型），再调用Validate检查必填字段、类型合法性、步骤/腿 ID 唯一性、needs引用有效性以及循环依赖检测（checkCycles/checkDependencyCycles）。发布流程中"✓ formula.toml is valid"这步，落地时可以直接复用这套校验器。

信任等级（Verification Levels）

设计文档为公式定义了四级信任体系：

UNVERIFIED (default) Anyone can publish Basic validation only Displayed with ⚠️ warning VERIFIED PUBLISHER Publisher identity confirmed Displayed with ✓ checkmark Higher search ranking OFFICIAL Maintained by Gas Town team Displayed with 🏛️ badge Included in embedded defaults AUDITED Security review completed Displayed with 🔒 badge Required for enterprise registries

四个等级与安全设计的关键点：

源码对照：OFFICIAL 等级"Included in embedded defaults"与当前实现完全吻合 —— 仓库中internal/formula/formulas/下的 40+ 个公式正是通过//go:embed formulas/*.formula.toml（见 internal/formula/embed.go）编译进二进制，作为"官方内置默认"，且会在gt install时由ProvisionFormulas部署到.beads/formulas/。可以说，"OFFICIAL = 内嵌默认"这一信任等级在 Phase 1 就已经落地，其余等级属于注册表上线后的扩展。

Capability Tagging：能力标签驱动的路由

公式能力声明

设计文档给出的能力声明 TOML 结构：

[formula.capabilities] # What capabilities does this formula exercise? Used for agent routing. primary = ["go", "testing", "code-review"] secondary = ["git", "ci-cd"] # Capability weights (optional, for fine-grained routing) [formula.capabilities.weights] go = 0.3 # 30% of formula work is Go testing = 0.4 # 40% is testing code-review = 0.3 # 30% is code review

• primary/secondary：主/次能力标签，用于检索过滤；
• weights（可选）：能力权重，声明公式工作在各能力上的分布，为细粒度路由（如"这个公式的 Go 工作占比 30%"）提供依据。

同一结构也出现在 docs/design/formula-resolution.md 的"Extended Format (Mol Mall Ready)"公式头部定义中，说明能力标签是公式 schema 的正式组成部分，而非临时字段。

基于能力的搜索

$ gt formula search --capabilities="security,go" Formulas matching capabilities: security, go mol-security-audit v2.1.0 ⭐ 4.8 📥 8,234 Capabilities: security, go, code-review "Comprehensive security audit workflow" mol-dependency-scan v1.0.0 ⭐ 4.2 📥 3,102 Capabilities: security, go, supply-chain "Scan Go dependencies for vulnerabilities"

搜索同时展示星级评分（⭐）与下载量（📥），与 Registry API 中的stats字段对应。

代理问责（Agent Accountability）

当 polecat 完成一个公式时，执行记录被追踪：

Polecat: beads/amber Formula: mol-polecat-code-review@1.3.0 Completed: 2026-01-10T15:30:00Z Capabilities exercised: - code-review (primary) - security (secondary) - go (secondary)

这份执行记录支撑三个能力：

1. Routing—— 有成功战绩的代理优先承接同类工作（回扣愿景中的"better capability routing"）；
2. Debugging—— 精确追溯"哪个代理、何时、做了什么"；
3. Quality metrics—— 按代理与公式统计成功率，反哺公式迭代与代理评估。

私有注册表：企业落地形态

客户端多注册表配置

企业可以配置多个注册表并按优先级回退：

# ~/.gtconfig.yaml registries: - name: acme url: https://molmall.acme.corp auth: token priority: 1 # Check first - name: public url: https://molmall.gastown.io auth: none priority: 2 # Fallback

priority语义明确：企业内网注册表优先，公共注册表兜底。这与本地三层解析"最具体者优先"（rig > town > system）的哲学一脉相承 ——先查最近的、最可信的来源，再逐级回退。

自托管注册表

设计文档给出了 Docker 部署形态：

# Docker deployment docker run -d \ -p 8080:8080 \ -v /data/formulas:/formulas \ -e AUTH_PROVIDER=oidc \ gastown/molmall-registry:latest # Configuration MOLMALL_STORAGE=s3://bucket/formulas MOLMALL_AUTH=oidc MOLMALL_OIDC_ISSUER=https://auth.acme.corp

关键环境变量：

"企业合规公式 + OIDC 认证 + 审计日志"共同构成 Phase 4 Enterprise Features 的完整图景。

联邦（Federation）：通过 HOP 实现跨组织共享

跨注册表发现

$ gt formula search "deploy kubernetes" --federated Searching across federated registries... molmall.gastown.io: mol-deploy-k8s v3.0.0 🏛️ Official molmall.acme.corp: @acme/mol-deploy-k8s v2.1.0 ✓ Verified molmall.bigco.io: @bigco/k8s-workflow v1.0.0 ⚠️ Unverified

联邦搜索把多个注册表的结果聚合展示，每个结果都附带其信任等级标记（🏛️ Official / ✓ Verified / ⚠️ Unverified），让使用者在"更多选择"与"可信度甄别"之间获得显式信息。

HOP URI 解析流程

# Full HOP URI gt formula install hop://molmall.acme.corp/formulas/@acme/mol-deploy@2.1.0 # Resolution via HOP (Highway Operations Protocol) 1. Parse hop:// URI 2. Resolve registry endpoint (DNS/HOP discovery) 3. Authenticate (if required) 4. Download formula 5. Verify checksum/signature 6. Install to town-level

六步解析流程中，"Install to town-level"再次确认：无论公式来自哪个注册表，最终落点都是 town 层~/gt/.beads/formulas/，与 docs/design/formula-resolution.md 的 Tier 2 定义完全一致。

实施阶段路线图（Phase 1-5）

设计文档给出了清晰的五阶段演进路径，结合源码可确认每阶段的现状：

Phase 1：本地命令（Now，已实现）

详情见 Formula Resolution 架构文档。仓库证据：

• 三层解析：ResolveFormulaContent（internal/formula/embed.go）严格按rig > town > embedded顺序查找*.formula.toml；
• 内嵌系统层：//go:embed formulas/*.formula.toml把 40+ 个公式编译进二进制（internal/formula/embed.go）；
• 安装时部署：ProvisionFormulas在gt install时创建.beads/formulas/并写入内嵌公式，同时生成.installed.json记录哈希（internal/formula/embed.go）；
• 健康管理：CheckFormulaHealth/UpdateFormulas实现公式漂移检测与安全更新（internal/formula/embed.go）；
• 命令面：gt formula list / show / run / create已落地（internal/cmd/formula.go），其中gt formula run支持--pr、--rig、--dry-run、--agent、--set等参数。

Phase 2：手动共享

• Formula export/import：
  • gt formula export mol-polecat-work > mol-polecat-work.formula.toml
  • gt formula import < mol-polecat-work.formula.toml
• Lock file 格式（上文.lock.json）

Phase 3：公共注册表

• molmall.gastown.io 上线；
• gt formula install（从注册表安装）；
• gt formula publish流程；
• 基础搜索与浏览。

Phase 4：企业特性

• 私有注册表支持；
• 认证集成（OIDC / Bearer token）；
• 信任等级（UNVERIFIED → AUDITED）；
• 审计日志。

Phase 5：联邦（HOP）

• 能力标签进入 schema；
• 联邦协议（Highway Operations Protocol）；
• 跨注册表搜索；
• 代理执行追踪（问责）。

当前实现的"公式"本体：为 Mol Mall 打下的地基

要理解 Mol Mall 的落点，需要先理解它分发的东西 —— 公式。仓库的 internal/formula/types.go 定义了四种公式类型：

以 mol-polecat-work.formula.toml 为例，它是标准的 workflow 公式：定义issue / base_branch / setup_command / typecheck_command / test_command / lint_command / build_command七个变量，编排load-context → branch-setup → implement → commit-changes → self-review → build-check → pre-verify → submit-and-exit八个步骤，每个步骤带明确的 exit criteria。这种"变量 + 步骤 + 验收标准"的结构，正是 Mol Mall 公式包content: <formula TOML>字段要承载的载荷—— 注册表本身不关心公式内部逻辑，只负责把这份 TOML 可靠地分发、校验并记录出处。

同时，internal/formula/parser.go 的校验器（必填字段、唯一 ID、needs引用、循环依赖检测、拓扑排序、ReadySteps就绪计算）构成了"pre-flight 检查中 formula.toml is valid"的直接实现基础，也为 Mol Mall 的POST /formulas服务端验证提供了可移植的校验逻辑。

小结

Mol Mall 是一份架构完整、落地分期的愿景文档：它用"三类注册表 + HOP URI + 五级 API + 四级信任 + 能力标签 + 锁文件"勾勒出一个类 npm 的 Gas Town 公式市场，同时通过"Install to town-level"的设计，把远端分发体系与仓库中已实现的三层本地解析（docs/design/formula-resolution.md、internal/formula/embed.go）无缝衔接。

对读者最有价值的三点认识：

1. 现状边界清晰：Phase 1（本地公式、三层解析、内嵌默认、健康检查）已在仓库落地；Phase 2-5（导出导入、公共/私有注册表、HOP 联邦）仍是设计蓝图，文中的gt formula install/publish/upgrade与hop://为规划形态；
2. 设计一致性：无论是本地解析（rig > town > system）还是远端注册表（private > public > federated），贯穿始终的原则是"就近、可信优先，逐级回退"；
3. 升级路径平滑：当前.installed.json与规划中的.lock.json同构，现有解析器/校验器可直接服务注册表 API，公式本体的 TOML 结构无需改变即可进入市场流通。

相关文档

• Mol Mall Design —— 本文解读的设计文档本体
• Formula Resolution —— 已实现的三层本地解析架构（rig > town > system）
• Molecules —— 公式（Formula）→ Proto → Mol 的完整生命周期（cook, pour, squash）
• 公式解析器与校验器 —— TOML 解析、类型推断、依赖校验与拓扑排序
• 公式类型定义 —— convoy / workflow / expansion / aspect 四种公式结构
• 公式内嵌与部署实现 —— 三层解析、安装时部署、健康检查与更新
• 内置公式集 —— 40+ 个官方内嵌公式（OFFICIAL 等级的现实形态）
• gt formula 命令实现 —— 当前已实现的 list / show / run / create

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown