企业官网建设流程全解析

PR Review Policy

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

Do NOT post review comments directly to GitHub viagh pr review. Instead, report your findings back in the conversation as a structured summary.

Code Style

Always runnpm run lint --fixbefore committing. Follow existing patterns in the codebase.

在 `gt prime` 输出中的呈现由 [internal/cmd/prime_output.go](https://link.gitcode.com/i/dd64daba68aa8aa983ce53de65be5266) 的 `outputRoleDirectives(ctx RoleContext, w io.Writer, explainEnabled bool)` 完成：根据 town/rig 文件存在情况，分别输出 `## Town Directives`、`## Rig Directives` 或 `## Town & Rig Directives` 三种头部，随后紧跟正文内容。在 `--explain` 模式下，还会输出 `[EXPLAIN]` 形式的来源注解（town/rig 路径）。[internal/cmd/prime_output_test.go](https://link.gitcode.com/i/68d08842209929297f0b87176a4294c4) 中的测试验证了关键行为：**没有指令文件时不输出任何可见内容（包括头部）**，避免污染 prime 输出。 ## 四、第二层：公式覆盖层（Formula Overlays） ### 4.1 文件布局 覆盖层是「CSS 风格的步骤修改」：在公式解析之后、prime 渲染之前，对公式的步骤进行定点修改：

~/gt/formula-overlays/ .toml # Town 级 ~/gt/ /formula-overlays/ .toml # Rig 级（完全优先）

其中 `<formula>` 是公式名（如 `mol-polecat-work`），文件名必须与公式名一致（含 `.toml` 后缀）。 ### 4.2 优先级：完全替换而非合并 与指令的「拼接」不同，**Rig 级覆盖层完全替换 Town 级覆盖层（不合并）**：只要 rig 覆盖层存在，town 覆盖层就被彻底忽略。这样设计的目的是防止不同层级的步骤修改被不可预测地合并，产生混乱的叠加效果。 [internal/formula/overlay.go](https://link.gitcode.com/i/ae70318b79116ce9f9c71f84882f02ad) 中的 `LoadFormulaOverlay(formulaName, townRoot, rigName) (*FormulaOverlay, error)` 精确实现了这一语义： 1. 先尝试 rig 路径 `<townRoot>/<rigName>/formula-overlays/<formulaName>.toml`，若存在则**直接返回，不再看 town**； 2. 回退读取 town 路径 `<townRoot>/formula-overlays/<formulaName>.toml`； 3. 两者都不存在则返回 `nil`（无错误）。 [internal/formula/overlay_test.go](https://link.gitcode.com/i/37ae739d379f5626968a226d558c177f) 的 `TestLoadFormulaOverlay_RigLevel` 证实了 rig 级覆盖层可独立加载生效，而 `TestLoadFormulaOverlay_NoFiles` 证实无文件时返回 `nil` 且不报错。 ### 4.3 TOML 格式与三种覆盖模式 覆盖层使用 TOML，核心是 `[[step-overrides]]` 数组： ```toml [[step-overrides]] step_id = "submit-review" mode = "replace" description = """ Report your review findings back to the conversation instead of posting to GitHub. Format as a structured summary with grade and findings.""" [[step-overrides]] step_id = "build" mode = "append" description = """ Also run integration tests: npm run test:integration""" [[step-overrides]] step_id = "deprecated-step" mode = "skip"

三种模式及其对description的要求：

对应源码中 internal/formula/overlay.go 定义的OverrideMode常量（ModeReplace/ModeAppend/ModeSkip）与StepOverride结构体（字段step_id、mode、description），以及 internal/formula/overlay.go 中ApplyOverlays(f *Formula, overlay *FormulaOverlay) []string的实现逻辑：

• replace：f.Steps[idx].Description = so.Description，整段替换；
• append：f.Steps[idx].Description += "\n" + so.Description，追加到原描述末尾；
• skip：从步骤切片中移除该步骤，并处理依赖继承（见下节）。

4.4 Skip 模式的依赖处理：保持公式 DAG 完整

跳过步骤时，一个关键问题是依赖它的后续步骤会失去前置依赖。覆盖层采用「依赖继承」策略：当步骤 B 依赖步骤 A、而 A 被跳过时，B 自动继承 A 原本的needs（依赖项），从而保持公式 DAG 的完整性。

从源码看，skip 分支先将被移除步骤的removedID与removedNeeds记下，从切片中删除该步骤后，遍历剩余步骤，把needs中引用removedID的位置替换为removedNeeds（按位置展开插入），保证依赖链不中断。

4.5 覆盖层的加载与校验规则

覆盖层的加载与校验集中在 internal/formula/overlay.go 的loadOverlayFile中，遵循以下规则：

• step_id是每条 override 的必填字段，缺失即报错；
• mode必须是replace、append、skip三者之一，非法值报错（错误信息会明确指出invalid mode）；
• TOML 解析失败（malformed）在加载时即返回错误；
• step_id与公式任何步骤都不匹配时不报错，而是生成警告（stale override），并在ApplyOverlays中以overlay references unknown step "X" (stale override)的警告列表形式返回。

这些警告最终由 internal/cmd/prime_molecule.go 的applyFormulaOverlays()捕获并通过style.PrintWarning输出，同时在--explain模式下打印Formula overlay: applying N override(s) for <formula> (rig=<rig>)及每条step_id/mode明细。

4.6 覆盖层作用于哪个渲染管线

覆盖层在「公式解析之后、渲染之前」应用。以showFormulaStepsFull()（internal/cmd/prime_molecule.go）为例，调用链为：

resolveFormulaForRendering() → formula.ResolveFormulaContent() # 解析公式内容（含 town/rig 公式解析） → formula.Parse() # 解析为 Formula 结构 → applyFormulaOverlays() # ★ 在此应用覆盖层 → buildFormulaVarMap() # 构建变量映射

Formula与Step的结构定义在 internal/formula/types.go 与 internal/formula/types.go：Step包含id、title、description、needs、target（可选gt sling目标，默认公式目标 rig）、parallel、interactive、acceptance等字段。覆盖层主要修改的是description与needs，其余字段保持不变。

五、CLI 命令

说明：CLI 命令正在 gt-3kg.5 中补充，下述接口反映的是规划中的设计，具体以对应版本发布为准。

指令（Directive）命令

gt directive show <role> [--rig <rig>] # 显示当前生效指令及来源 gt directive edit <role> [--rig <rig>] # 在编辑器中打开（文件不存在则创建） gt directive list # 列出所有指令文件

覆盖层（Overlay）命令

gt formula overlay show <formula> [--rig <rig>] # 显示当前生效覆盖层及来源 gt formula overlay edit <formula> [--rig <rig>] # 在编辑器中打开（文件不存在则创建） gt formula overlay list # 列出所有覆盖层文件

edit命令遵循gt hooks override的先例：目录和文件不存在时自动创建。show命令则显示解析后的内容并附来源注解（town 级还是 rig 级），配合gt prime --explain可以完整掌握当前生效的定制内容及其出处。

六、gt doctor 集成：覆盖层健康检查与自动修复

覆盖层最大的风险是公式升级后步骤 ID 失效（stale override）。gt doctor提供了专门的overlay-health检查：

gt doctor # 运行所有检查，包括 overlay health

检查逻辑实现在 internal/doctor/overlay_health_check.go 的OverlayHealthCheck.Run中：

1. 扫描所有 town 级（<townRoot>/formula-overlays/）与 rig 级（依据<townRoot>/mayor/rigs.json枚举 rig，再扫描各 rig 的formula-overlays/目录）的.toml覆盖层文件；
2. 解析每个覆盖层，并通过formula.GetEmbeddedFormulaContent(formulaName)加载二进制内嵌的对应公式，解析后取f.GetAllIDs()建立合法 step ID 集合；
3. 校验每个step_id是否存在于当前公式版本中，不存在的标记为 stale；
4. 分级汇报：
   • OK：N overlay(s) healthy，或无文件时no overlay files found；
   • Warning：发现 stale step ID（可自动修复）；
   • Error：存在 malformed TOML（需手动修复）。

自动修复：gt doctor --fix

gt doctor --fix # 移除过期的 step-override 条目

Fix方法（internal/doctor/overlay_health_check.go）的行为：

• 仅处理「解析成功且含 stale ID」的文件；
• 过滤掉引用不存在 step ID 的 override 条目，其余保留并重新编码回 TOML写盘；
• 若某个文件的所有 override 全部 stale，则整个文件被删除；
• malformed TOML 文件一律不触碰（必须手动修复，FixHint会提示）。

这套「警告 + 自动清理」的闭环，把公式步骤 ID 非稳定 API 的运维负担降到了最低：升级gt后跑一次gt doctor --fix即可让覆盖层与新版公式重新对齐。

七、实战示例：PR Review 覆盖层（触发该功能的核心用例）

这是促成该功能诞生的动机场景，完整走一遍：

7.1 问题

mol-polecat-work公式中有一个名为submit-review的步骤，指示 polecat 使用gh pr review --comment把评审结果发布到 GitHub。在 gastown rig 中，操作员希望 polecat 改为在会话中汇报发现。

7.2 解决步骤

Step 1：创建 rig 级公式覆盖层。

mkdir -p ~/gt/gastown/formula-overlays

创建~/gt/gastown/formula-overlays/mol-polecat-work.toml：

[[step-overrides]] step_id = "submit-review" mode = "replace" description = """ Report your review findings back to the conversation. Format as: ## Review: <file or component> **Grade:** A-F **Findings:** - CRITICAL: ... - MAJOR: ... - MINOR: ... Do NOT post comments to GitHub via gh pr review."""

Step 2：用 gt doctor 验证。

gt doctor # ✓ overlay-health: 1 overlay(s) healthy

Step 3：用 gt prime 测试。

gt prime --explain # Shows: "Formula overlay: applying 1 override(s) for mol-polecat-work (rig=gastown)"

完成以上三步后，gastown rig 中任何运行mol-polecat-work的 polecat 看到的将是替换后的步骤描述，而非原始的「post to GitHub」指令。仓库中 docs/contrib-harnesses/polecat-pr-flow/mol-polecat-work.toml 与 docs/contrib-harnesses/polecat-pr-flow/polecat.md 提供了可直接复制改写的完整示例。

7.3 公式变更后怎么办？

如果未来gt版本把submit-review改名为post-results，覆盖层的step_id就会变成 stale。下次运行gt doctor时：

⚠ overlay-health: stale step IDs in gastown/formula-overlays/mol-polecat-work.toml: - step_id "submit-review" not found in formula mol-polecat-work

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