# Agent-Intent v0.1.0 实现与验证记录

对应设计方案：[2026-09-29-agent-intent-design.md](2026-09-29-agent-intent-design.md)（决策 D1–D7 按推荐执行，经用户批准）。
范围：P0–P3 全部完成；P4（消费方接入 PR）按方案另立任务，不在本仓。

## 交付内容

- `intent` 核心包：spec 定义与校验（id 分段格式、正则/槽位/数量上限）、RegistryBuilder / Registry / 不可变 Snapshot（atomic.Pointer 原子替换）、JSON overlay 加载合并（新增/覆盖需版本递增/禁用/保护域拒绝/未知字段拒绝）、四级漏斗识别器（guard → expectation → rules → adjudicate）、槽位抽取（必填缺失记录于 `MissingRequiredSlots`）、`Snapshot.Explain` 裁决轨迹、`Snapshot.Conflicts` 共享词条诊断、`RuleSegmenter` 规则分句、`Classifier` / `ExpectationProvider` 扩展接口、错误码鸭子方法 + logsys 可选注入。
- `conformance`：消费方行为验收套件（分支/Top/槽位断言 + 确定性 + 并发冒烟）。
- `catalogcheck`：`intent.*` / 复用的 `sys.invalid_argument` 常量与错误码库目录逐个相等。
- `cmd/intentctl`：`lint`（校验 + 冲突报告 + 来源清单）、`explain`（分支/候选/槽位/两阶段轨迹）、`eval`（评测集跑批，退出码承载失败）。
- `examples`：守卫 Go 内置（保护域）+ 业务 JSON embed 的端到端示例。
- 测试：spec 校验表测、loader 合并语义与来源定位、registry 快照/Reload 保留旧快照、识别器全分支（守卫短路、挂起预期、模式加成、歧义、分类器成败、必填槽位缺失、大小写折叠、空输入、超长输入、nil 快照）、确定性深比较、`-race` 并发识别 + Reload、评测集回归。

## 与方案的偏差

1. **执行顺序**：P1（Error-Code-System 上游 `intent` 域）先于 P0 完成，使本仓首个提交直接 pin ECS 新提交 `28fa06ea`，避免一次 pin 漂移。ECS 变更为追加式（新域 3 码 + 目录 JSON + 映射文档），不影响既有消费方。
2. **id 格式**：实现采用点分段 `^[a-z][a-z0-9_-]{0,63}$`（首段=domain），支持多级记忆名（`demo.run.status_query`）；方案原文的单段记忆名正则不含层级，属笔误级修正。
3. **计分舍入**：得分固定四位小数舍入，避免浮点噪声进入结果与 margin 比较（方案未规定，实现补齐并写入 README）。
4. **intentctl eval 的守卫用例**：CLI 只加载 JSON 配置，宿主 Go 内置守卫的用例只能在宿主测试/conformance 中验证（README 已说明）。模块自带评测集的 guard 用例由 Go 测试路径覆盖。
5. **Result 顶层 Slots**：方案便捷字段未实现，槽位在 `Top.Slots`；语义等价，避免双份状态。

## 验证证据

| 验收条件（方案验收表） | 结果 |
|---|---|
| 同输入+同快照→同结果（含 Explain） | 通过：`TestRecognizeDeterministic` 深比较 |
| guard 保护域不可被 overlay 禁用/覆盖 | 通过：`TestBuildFSProtectedDomain`（两种尝试均 `intent.spec_protected`） |
| 配置错误定位到字段与来源 | 通过：`TestValidateSpecRejections`、`TestLoadOverlaysUnknownField`、`TestBuildFSOverrideMustIncreaseVersion`（fields 含 file/source/field） |
| 合并语义（新增/覆盖/禁用/版本递增/位置保持） | 通过：`TestBuildFSMergeSemantics`、`TestLoadOverlaysFileOrder` |
| 无匹配=Fallback 非错误 | 通过：`TestRecognizeExcludedTermFallsBack`、`TestRecognizeEmptyInputFallsBack` |
| Reload 失败保留旧快照；并发识别不受影响 | 通过：`TestReloadSwapsAndKeepsOldOnFailure`、`TestConcurrentRecognizeAndReload`（-race） |
| 硬负例语料（否定写+只读、排除词、近义混淆） | 通过：`TestEvalCorpus`（10 用例，含 `negated_write_readonly`） |
| 错误码与上游 intent 域逐个相等 | 通过：`catalogcheck.TestIntentCodesAlignWithCatalog` |
| 零第三方依赖 | 通过：`go list -m all` 仅 `error-code-system` / `logging-system`（本地 replace） |
| 消费方可按生态范式接入 | 通过：`examples.TestEndToEnd`（embed 配置 → 守卫/匹配/槽位/元数据/诊断） |
| intentctl 只读诊断 | 通过：`cmd/intentctl` 三个命令单测 + 手工冒烟（lint/explain/eval 输出见会话） |

## 命令与结果（2026-09-29，本机 go1.27.1 linux/amd64）

```bash
GOWORK=off go vet ./...                  # 通过，无输出
GOWORK=off go test -count=1 ./...        # ok：catalogcheck / cmd/intentctl / conformance / examples / intent
GOWORK=off go test -count=1 -race ./...  # 同上，全部 ok
GOWORK=off go list -m all                # agent-intent + 两个生态子模块
scripts/submodule-consistency.sh         # 见提交时输出（三个 ok）
```

## 组合与回退

- 本仓 pin：development-guidelines `26b562d2`、error-code-system `28fa06ea`（含 intent 域）、logging-system `2c5716fd`；与 Agent-Squad / Agent-Native 当前组合一致（ECS 为追加式前进）。
- 消费方回退：普通 PR 恢复旧 gitlink 即回退本模块；ECS 的 `intent` 域为纯追加，回退本仓不需要回退 ECS。