Pin Development Guidelines and add the project entry documents.
The guidelines submodule records the reviewed commit so project rules stay discoverable without copying them into this repository. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
weichen
@@ -0,0 +1,58 @@
|
||||
# 接入开发规范、迁移依赖布局并接通错误码与日志
|
||||
|
||||
状态：已批准范围（实现进行中）；owner：weichen；主任务：本仓接入提交。
|
||||
授权与交付终点：挂载规范、把 Agent-Native 迁到 `deps/`、接入错误码信封与日志。不改产品角色模板，不部署共享服务。
|
||||
并行基线：Agent-Squad `main` @ `6a10c4272f6fec7dc86e0c47bf5b95cde0db21d5`，其 Agent-Native gitlink 为 `49e6dd1e0fc65de7f259f21d2f63c56e5b165a48`。日期 2026-09-29。
|
||||
|
||||
## 问题与证据
|
||||
|
||||
本仓 HTTP 层 `writeErr` 只返回 `{"error":"<文本>"}`，没有稳定码，也没有 `X-Trace-Id`。错误码库的 `docs/agent-squad-mapping.md` 已给出映射，但消费方尚未使用。Agent-Native 子模块放在仓库根，和自身包目录混在一起；若 Agent-Native 再引入错误码库与日志库，会形成嵌套副本。
|
||||
|
||||
## 目标与边界
|
||||
|
||||
- 规范、Agent-Native、错误码库、日志库都放在 `deps/`，版本由本仓 gitlink 固定。
|
||||
- HTTP 错误改为错误码库信封；步骤失败外层为 `squad.step_failed`，Unwrap 保留 `agent.*` 根因。
|
||||
- 组合根日志带 `trace_id` 与 `run_id`。事件可带 `code`。
|
||||
- 非目标：不改事件名；不把日志库导入错误码库；不在本仓编译时使用 Agent-Native 内部的 `replace`。
|
||||
|
||||
## 选择与实施
|
||||
|
||||
磁盘上允许嵌套副本，编译只使用本仓 `go.mod` 的 `replace`。`scripts/submodule-consistency.sh` 比较本仓 `deps/error-code-system` 与 `deps/agent-native/deps/error-code-system`（日志库同理）的 gitlink，不一致则失败。
|
||||
|
||||
1. 挂载规范并写入口。
|
||||
2. `git mv Agent-Native deps/agent-native`，挂载两个基础库，更新 replace。
|
||||
3. 改 server/cli/store 与测试。
|
||||
4. `GOWORK=off go test` 与一致性脚本。
|
||||
|
||||
## 兼容、迁移与恢复
|
||||
|
||||
已有克隆在路径迁移后需要：
|
||||
|
||||
```bash
|
||||
git submodule sync --recursive
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
旧的根目录 `Agent-Native` 工作区若残留，应删除后再初始化，避免和 `deps/agent-native` 并存两份未跟踪副本。HTTP 客户端若只解析 `{"error":"文本"}` 需要改为读取 `error.code` 与 `error.reason`。
|
||||
|
||||
回退使用普通提交恢复旧 gitlink 与旧 `writeErr`。无数据库迁移。父仓在新组合测试通过前继续固定旧组合。
|
||||
|
||||
## 验收
|
||||
|
||||
| 需求/验收条件 | 负责模块/契约或不变量 | 验证方法/用例 | 实际结果/证据 |
|
||||
|---|---|---|---|
|
||||
| 依赖都在 deps/ 且 SHA 一致 | .gitmodules / 一致性脚本 | `scripts/submodule-consistency.sh` | 计划阶段待执行 |
|
||||
| HTTP 错误为规范码信封 | server | server 与 conformance 测试 | 计划阶段待执行 |
|
||||
| trace_id 出现在响应头 | httpx.Trace | 新增验收 | 计划阶段待执行 |
|
||||
| 既有 HITL 与离线链路仍通过 | conformance | `GOWORK=off go test -count=1 ./...` | 计划阶段待执行 |
|
||||
|
||||
| 用户/系统条件 | 检查层级与方法 | 预期结果 | 必需环境/授权 |
|
||||
|---|---|---|---|
|
||||
| 未知 backend | API/引擎测试 | `squad.unknown_backend`，不回落 stub | 无 |
|
||||
| HITL 挂起 | conformance | 挂起后 respond 可续跑 | 无 |
|
||||
| 缺子模块 | 不初始化 submodule 就构建 | 构建失败，不静默跳过 | 无 |
|
||||
| 全新递归 clone | clone 后测试 | 三层子模块物化且测试通过 | Gitea SSH |
|
||||
|
||||
## 决策与剩余项
|
||||
|
||||
升级顺序：基础库先更新，Agent-Native 再更新其 deps gitlink，最后本仓一个提交同时推进 Agent-Native 与两个基础库的 gitlink，并跑一致性脚本。验证证据实现后另写记录。
|
||||
Reference in New Issue
Block a user