Agent-Native/docs/records/2026-09-29-guidelines-and-observability.md

接入开发规范并为执行契约对齐错误码与日志

状态：已批准范围（实现进行中）；owner：weichen；主任务：本仓接入提交。 授权与交付终点：在 Agent-Native 内挂载规范子模块、补齐项目入口，并把执行错误与日志接到 Error-Code-System / Logging-System。不改 Gitea 权限，不发布制品。 并行基线：Agent-Native main @ 49e6dd1e0fc65de7f259f21d2f63c56e5b165a48；Development-Guidelines 26b562d2e34fbc560711296a309c91c74ffc55b1；Error-Code-System b67696d393e7abfbdd16fdde1064c07f5ecd2f72；Logging-System 7f5972007bdcb6047ce7f95ee891f53e0af9d136。日期 2026-09-29。

问题与证据

四个基础库此前没有统一的项目入口，也没有把 Development-Guidelines 固定进父仓。Agent-Native 的 contract.ErrorCode 仍是短字符串（如 canceled），与错误码库的 agent.* 规范码只在映射文档中对应，调用方无法从错误值直接得到规范码。runtime 没有可替换的结构化日志，失败只能靠返回值。

经验检索：规范库与两个基础库均为新仓，无已验证经验条目。

目标与边界

• 规范以 deps/development-guidelines 的 gitlink 为版本权威。
• contract.ErrorCode 的取值改为 agent.*；contract.Error 提供 ErrorCode() / ErrorFields()，使日志库能识别错误且 contract 不导入错误码模块。
• pitransport 对外错误码同步为规范码；CANCELLED 并入 agent.canceled，MISSING_TARGET 并入 agent.missing_deliverable。
• runtime 与 native adapter 接受可选 *logsys.Logger，nil 时使用空日志器。
• 非目标：不改 Squad 编排；不把本仓变成错误码目录的第二权威；不自动跟踪子模块上游分支。

选择与实施

子模块统一放 deps/，与后续各仓布局一致。错误码常量改值而不是在调用点拼接前缀，避免两套字符串长期并存。contract 只增加鸭子方法，不 import error-code-system，保持该包零外部依赖。

1. 挂载 deps/development-guidelines 并提交入口文档。
2. 挂载 deps/error-code-system、deps/logging-system，go.mod 用相对 replace。
3. 修改 contract 与 adapters/pitransport 的错误码取值，补日志钩子与 scripts/submodule-consistency.sh。
4. 仓库根 go test 作为本模块出口。

兼容、迁移与恢复

错误码取值变更对按旧字符串比较的调用方是破坏性变更。错误码库已把旧值登记为别名，Registry.Resolve 仍可解析旧字符串。agent-system-multi 若硬编码旧码，需在其自己的消费提交里跟进；本仓 gitlink 未进主仓组合之前不影响主仓构建。

回退：父仓 PR 恢复旧 gitlink 与旧常量值。无数据库迁移。暂停条件：go test 失败或子模块 SHA 无法从批准远端获取。

验收

需求/验收条件	负责模块/契约或不变量	验证方法/用例	实际结果/证据
规范入口可发现且版本固定	根 AGENTS.md / gitlink	git submodule status；打开相对链接	计划阶段待执行
contract 错误码为 agent.* 且鸭子方法可被日志识别	contract.Error	go test ./contract/...	计划阶段待执行
pitransport 历史码映射到规范码	adapters/pitransport	go test ./adapters/pitransport/...	计划阶段待执行
可选日志器为 nil 时行为不变	runtime / adapters/native	go test ./runtime/... ./adapters/native/...	计划阶段待执行

用户/系统条件	检查层级与方法	预期结果	必需环境/授权
全新 clone 后可测试	git clone --recurse-submodules 后 go test	通过	能访问 Gitea SSH
旧错误字符串仍可被错误码库解析	错误码库别名测试（该库既有用例）	别名回到规范码	Error-Code-System 源码
未知结果与缺能力	contract/conformance 既有用例	不降级、不回落 Stub	无
无日志器的既有调用	runtime/native 既有测试	保持通过	Go 1.27

决策与剩余项

多级副本由各父仓 gitlink 锁定；Agent-Squad 构建时只采用 Agent-Squad 自己的 replace。一致性脚本在本仓接入两个基础库后启用。验证证据在实现完成后写入同目录的验证记录，不把本方案改称已完成。