Agent-Intent/docs/records/2026-09-29-implementation-verification.md

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

对应设计方案：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）

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。