weichen
f3d000f6a6
Details (original message): Add the optional intent gate port with the squadintent adapter, CLI wiring, and pin cascade.
3.4 KiB
3.4 KiB
Agent-Squad 接入 agent-intent 意图闸门（可选能力）
对应设计：Agent-Intent 仓 docs/records/2026-09-29-decoupling-and-llm-layering.md（第三节 a，决策 D1/D2/D4/D5 按推荐执行）。跨仓总测试报告：Agent-Intent 仓 docs/records/2026-09-29-squad-native-integration-report.md。
形态与边界
squad/intent.go：IntentGate窄端口 +IntentDecision（Reject / BlueprintKey / nil=透传），Options.IntentGate，Run()入口一次裁决（澄清续跑不重复过闸；显式 TaskKey 优先）。约 60 行，零外部依赖。squadintent/：全仓唯一 import agent-intent 处。New无来源返回 nil 闸门（= 未启用）；分支映射 GuardHit→Reject、Matched+metadata.blueprint→蓝图定向、其余→nil；识别错误 fail-closed。- cli：
--intent-rootflag +AGENT_SQUAD_INTENT_ROOTenv（run/serve）；配置非法 fail-closed 拒绝启动。 - 错误码：守卫拒绝
squad.intent_refused；意图定向的蓝图缺失squad.blueprint_not_found（复用）。 - 运行审计：
state.json记录intent_id/intent_blueprint，task_key与planning_mode随定向变化。
解耦证明
- 结构：
GOWORK=off go list -deps ./squad ./server ./store不含 agent-intent（0 命中）。 - 零配置等价：
squad.TestIntentGateNilDecisionKeepsOriginalPath（闸门恒不干预 ⇒ 与无闸门引擎结果一致）；squadintent.TestNewWithEmptyOverlayActsAsDisabled（来源存在但零内容 ⇒ Decide 恒 nil）；squadintent.TestEngineWithoutGateKeepsOriginalBehavior。 - 等价回归：既有
conformance全链路套件在本次改动后原样通过。 - 一致性：
scripts/submodule-consistency.sh扩展为对deps/agent-native与deps/agent-intent两处嵌套副本的 8 项比对，全部 ok。
验证证据（2026-09-29，go vet/test/-race 全绿）
| 层 | 用例 | 期望与结果 |
|---|---|---|
| 引擎 | TestIntentGateBlueprintRouting | 无闸门=自主规划；有闸门=定向到模板步骤 b_intent ✅ |
| 引擎 | TestIntentGateRejectFailsWithStableCode | RunFailed + squad.intent_refused ✅ |
| 引擎 | TestIntentGateUnknownBlueprintFailsClosed | RunFailed + squad.blueprint_not_found ✅ |
| 引擎 | TestIntentGateErrorFailsClosed | 闸门错误 ⇒ 失败运行 ✅ |
| 引擎 | TestIntentGateExplicitTaskKeyBypassesGate | TaskKey 时闸门零调用 ✅ |
| 适配器 | TestDecideGuardHitRejectsWithGuidance / RouteToBlueprint / AmbiguousFallbackPassThrough / ExplicitTaskKeyWins / NewWithoutSourcesNil / EmptyOverlayDisabled / BadConfigFailClosed | 全通过 ✅ |
| 集成 | TestEngineEndToEndWithAdapterGate | 识别→决策→蓝图→规划→脚本后端执行→质检完成；守卫输入拒绝 ✅（-race 同过） |
E2E（真实 CLI，输出摘录见总报告）：同一守卫文本，外挂意图→squad.intent_refused 拒绝；无意图→自主规划跑完。同一不含关键词的目标，外挂意图→1 步模板计划（intent_id/intent_blueprint 落盘）；无意图→4 步自主计划。
回退程序
删 squadintent/、squad/intent.go、cli 接线（assemble 的 intentRoot 参数与闸门构造、run/serve 的 flag、usage 两行）、go.mod 的 agent-intent require/replace、.gitmodules 条目与 submodule、一致性脚本两段。squad 引擎除 Options 一个可选字段与 Run() 入口一个 nil 可跳过的块外无其他改动。