尧图网站建设 
PR Review Policy【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastownDo NOT post review comments directly to GitHub viagh pr review. Instead, report your findings back in the conversation as a structured summary.Code StyleAlways 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的要求模式效果description是否必需replace完全替换步骤描述是append在现有步骤描述后追加文本换行分隔是skip从公式中移除该步骤否对应源码中 internal/formula/overlay.go 定义的OverrideMode常量ModeReplace/ModeAppend/ModeSkip与StepOverride结构体字段step_id、mode、description以及 internal/formula/overlay.go 中ApplyOverlays(f *Formula, overlay *FormulaOverlay) []string的实现逻辑replacef.Steps[idx].Description so.Description整段替换appendf.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 modeTOML 解析失败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 (rigrig)及每条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.goStep包含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中扫描所有 town 级townRoot/formula-overlays/与 rig 级依据townRoot/mayor/rigs.json枚举 rig再扫描各 rig 的formula-overlays/目录的.toml覆盖层文件解析每个覆盖层并通过formula.GetEmbeddedFormulaContent(formulaName)加载二进制内嵌的对应公式解析后取f.GetAllIDs()建立合法 step ID 集合校验每个step_id是否存在于当前公式版本中不存在的标记为 stale分级汇报OKN overlay(s) healthy或无文件时no overlay files foundWarning发现 stale step ID可自动修复Error存在 malformed TOML需手动修复。自动修复gt doctor --fixgt 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) healthyStep 3用 gt prime 测试。gt prime --explain # Shows: Formula overlay: applying 1 override(s) for mol-polecat-work (riggastown)完成以上三步后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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PR Review Policy
PR Review Policy【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastownDo NOT post review comments directly to GitHub viagh pr review. Instead, report your findings back in the conversation as a structured summary.Code StyleAlways 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的要求模式效果description是否必需replace完全替换步骤描述是append在现有步骤描述后追加文本换行分隔是skip从公式中移除该步骤否对应源码中 internal/formula/overlay.go 定义的OverrideMode常量ModeReplace/ModeAppend/ModeSkip与StepOverride结构体字段step_id、mode、description以及 internal/formula/overlay.go 中ApplyOverlays(f *Formula, overlay *FormulaOverlay) []string的实现逻辑replacef.Steps[idx].Description so.Description整段替换appendf.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 modeTOML 解析失败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 (rigrig)及每条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.goStep包含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中扫描所有 town 级townRoot/formula-overlays/与 rig 级依据townRoot/mayor/rigs.json枚举 rig再扫描各 rig 的formula-overlays/目录的.toml覆盖层文件解析每个覆盖层并通过formula.GetEmbeddedFormulaContent(formulaName)加载二进制内嵌的对应公式解析后取f.GetAllIDs()建立合法 step ID 集合校验每个step_id是否存在于当前公式版本中不存在的标记为 stale分级汇报OKN overlay(s) healthy或无文件时no overlay files foundWarning发现 stale step ID可自动修复Error存在 malformed TOML需手动修复。自动修复gt doctor --fixgt 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) healthyStep 3用 gt prime 测试。gt prime --explain # Shows: Formula overlay: applying 1 override(s) for mol-polecat-work (riggastown)完成以上三步后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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考