Add the optional intentgate decorator over agent-intent with pass-through and fail-closed tests

Details (original message): Add the optional intentgate decorator over agent-intent with pass-through and fail-closed tests.
2026-09-29 15:58:35 +00:00
parent cc8a6a7702
commit 5e489ab2cb
11 changed files with 263 additions and 2 deletions
@@ -0,0 +1,23 @@
+# Agent-Native 接入 agent-intent 意图闸门（可选装饰器）
+
+对应设计：Agent-Intent 仓 `docs/records/2026-09-29-decoupling-and-llm-layering.md`（第三节 b，决策 D7 选仓内装饰器）。
+形态：`adapters/intentgate.Wrap(next, recognizer, snapshot, handler) exec.Backend`——Execute 前对 `req.Prompt` 做一次确定性识别，守卫/命中/预期命中分支交宿主 Handler 解释（合成结果语义由宿主定义），Ambiguous/Fallback 或 Handler 放弃时原样透传；识别系统错误 fail-closed。
+
+## 依赖与解耦边界
+
+- 本包是本仓唯一 import `agent-intent` 的位置；contract/exec/runtime/adapters/native 零感知（`GOWORK=off go list -deps ./contract ./exec ./runtime ./adapters/native` 不含 agent-intent）。
+- T0 行为解耦：未 Wrap（或任一组件为 nil，直接返回原后端）与 Wrap 了零意图快照，行为与原后端一致（`TestZeroSpecSnapshotPassthroughIdentical` 逐字节对比）。
+- 回退程序：删 `adapters/intentgate/` + go.mod 两行 + submodule + `.gitmodules` 条目 + 一致性脚本一行。
+
+## 验证证据（2026-09-29，go test ./... 全绿，intentgate 含 -race）
+
+| 用例 | 外挂意图 | 输入（Prompt） | 识别结果 | 期望 | 结果 |
+|---|---|---|---|---|---|
+| TestZeroSpecSnapshotPassthroughIdentical | 无（零 spec 快照） | `帮我改一下系统网关地址` | Fallback（快照为空） | 与裸 stub 后端结果逐字节一致，Handler 不触发 | 通过 |
+| TestGuardHitInterceptsWithoutModel | guard.config_change（includes: 系统配置/网关；risk=high） | `帮我改一下系统网关地址` | GuardHit，top=guard.config_change | Handler 收到 GuardHit；返回拒绝合成结果；**模型后端零调用** | 通过 |
+| TestFallbackPassesThroughToBackend | 同上 | `写一份周报` | Fallback | 透传原后端，Handler 不触发，后端恰好调用 1 次 | 通过 |
+| TestHandlerDeclineFallsBackToBackend | 同上 | `帮我改一下系统网关地址` | GuardHit（Handler 放弃） | 回退透传原后端 | 通过 |
+| TestNilComponentsReturnNext | n/a | n/a | n/a | 任一组件为 nil → Wrap 返回原后端 | 通过 |
+| TestRecognizeErrorFailsClosed | MaxInputLen=8 快照 | 超长输入 | 识别错误 sys.invalid_argument | fail-closed 返回错误，后端零调用 | 通过 |
+
+命令：`GOWORK=off go vet ./... && GOWORK=off go test -count=1 ./...`；`GOWORK=off go test -count=1 -race ./adapters/intentgate/`；`scripts/submodule-consistency.sh`。