From a8d26683920837cd4ac92c0053b538a12cfcb98a Mon Sep 17 00:00:00 2001 From: weichen Date: Tue, 29 Sep 2026 14:20:37 +0000 Subject: [PATCH] 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 --- .gitmodules | 3 + AGENTS.md | 29 ++++++++++ PROJECT.md | 53 +++++++++++++++++ deps/development-guidelines | 1 + ...2026-09-29-guidelines-and-observability.md | 58 +++++++++++++++++++ policy/guidelines-adoption.md | 41 +++++++++++++ 6 files changed, 185 insertions(+) create mode 100644 AGENTS.md create mode 100644 PROJECT.md create mode 160000 deps/development-guidelines create mode 100644 docs/records/2026-09-29-guidelines-and-observability.md create mode 100644 policy/guidelines-adoption.md diff --git a/.gitmodules b/.gitmodules index 61b0084..c53df3e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,6 @@ [submodule "Agent-Native"] path = Agent-Native url = ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git +[submodule "deps/development-guidelines"] + path = deps/development-guidelines + url = ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Development-Guidelines.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b0b9550 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# 项目工作入口 + +本项目采纳的通用规则：[核心规则](deps/development-guidelines/core/baseline.md)。 +采纳范围、生效状态及项目差异：[采纳记录](policy/guidelines-adoption.md)。 +项目事实、测试和环境入口：[PROJECT.md](PROJECT.md)。 + +- 启动：阅读以上短入口；只加载本次任务触发的专题。 +- 普通交付：[交付流程](deps/development-guidelines/workflows/delivery.md)。 +- 并行开发/正式测试/审核/合入：[共同基线与同步节点](deps/development-guidelines/standards/collaboration.md)，必须确认并实际同步最新权威目标。 +- Bug/异常：[系统性排障](deps/development-guidelines/workflows/debugging.md)。 +- 会话结束/换机器/换客户端/换执行者：[会话、执行者与机器交接](deps/development-guidelines/workflows/handoff.md)，状态写入任务主记录，不依赖本地会话历史。 +- 测试与验收：[验证标准](deps/development-guidelines/standards/verification.md)。 +- 模块/接口：[模块契约](deps/development-guidelines/standards/module-contracts.md)。 +- 功能设计/跨模块变更：[设计与验证](deps/development-guidelines/workflows/design-verification.md)，按增量明确验收、独立测试及故障范围。 +- 错误与过程事件：[可观测性](deps/development-guidelines/standards/observability.md)。 +- 拆仓与 submodule：[多仓库与固定版本组合](deps/development-guidelines/standards/multi-repo.md)。 +- 其他专题：按 [任务索引](deps/development-guidelines/README.md) 选择。 + +项目补充硬边界： + +- 本库只做编排与任务拆解，不实现 Agent。智能体执行只来自 Agent-Native 或调用方注册的后端。 +- 未知 backend fail-closed，禁止静默回落 stub。 +- 磁盘上的运行状态是恢复权威；HTTP 错误使用稳定规范码和 `X-Trace-Id`，不以自由文本作为唯一错误合同。 +- 依赖仓版本以本仓 gitlink 为准。构建时只认本仓 `go.mod` 的 `replace`；嵌套子模块里的 `replace` 不参与本仓编译。 + +任务权威：Gitea 仓库 `weichen/Agent-Squad` 的 Issue 与 Pull Request。 +规范性文档目录与过程记录位置：`policy/` 放项目规则；`docs/records/` 为过程记录豁免目录。项目规范与过程记录不进通用规范库。 +默认集成基线和提交身份：`main`；测试命令带 `GOWORK=off`。提交身份沿用本机 git 作者。 +共享环境/发布入口及授权：无共享运行环境。权威远端 `ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git`。HTTP 开发入口默认 `:8090`，不含密钥。 diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..38d9de6 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,53 @@ +# Agent-Squad 项目事实 + +工作规则见 [AGENTS.md](AGENTS.md)。此文件维护本项目事实，不复制通用规范。 + +## 仓库与操作 + +- 目标/产品边界：通用智能体小队编排底座。角色、蓝图、规划、执行引擎、黑板、HITL 与 HTTP/CLI 组合根。不含预设医疗器械角色或任务模板。不实现 Agent。 +- 源码、资产、文档、机器契约位置：Go 模块路径 `agent-squad`。包为 `squad`、`store`、`server`、`cli`、`textextract`、`conformance`。人类文档在根 `README.md`、`policy/`；过程记录在 `docs/records/`。对外 HTTP 错误合同以错误码库信封为准。 +- 权威远端、集成基线、受保护分支：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git`，集成基线 `main`。 +- 并行共同基线记录位置、合入通知/主动检查方式：Gitea Issue/PR。跨仓共同起点是本仓提交加上它锁定的 Agent-Native、错误码库、日志库与规范库 SHA。 +- 发布线与批准版本/实际制品查询入口：无独立制品库。可执行文件由 `go build` 从固定 gitlink 组合产出。 +- 提交/审核/合并/发布身份与权限：仓库所有者 weichen。 +- 任务唯一来源：Gitea `weichen/Agent-Squad` 的 Issue 与 Pull Request。 +- 规范性文档目录：`policy/`。 +- 过程文档仓/目录：`docs/records/`（项目内豁免，见采纳记录）。 +- 交接记录位置：随任务主记录；需要落盘的交接放入 `docs/records/`。 +- 凭证查找入口及所需字段：LLM 使用环境变量 `AGENT_SQUAD_LLM_BASE_URL`、`AGENT_SQUAD_LLM_API_KEY`、`AGENT_SQUAD_LLM_MODEL`。日志采集 token 使用日志库自己的配置。文档与仓库不记录这些值。 + +## 依赖组合 + +| 逻辑 ID | 当前路径 | 接入后的路径 | 角色 | +|---|---|---|---| +| agent-native | `Agent-Native` | `deps/agent-native` | build-required | +| development-guidelines | `deps/development-guidelines` | 同左 | development-only | +| error-code-system | 尚未挂载 | `deps/error-code-system` | build-required | +| logging-system | 尚未挂载 | `deps/logging-system` | build-required | + +`go.mod` 目前为 `replace agent-native => ./Agent-Native`。迁移到 `deps/` 后改为相对 `deps/` 的 replace，并在同一次提交更新本表。 + +克隆： + +```bash +git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git +# 已克隆时：git submodule update --init --recursive +``` + +## 验证命令 + +| 影响 | 工作目录与真实命令/CI | 前提与不覆盖范围 | +|---|---|---| +| 文档 | 人工核对入口与相对链接 | 不证明运行时行为 | +| 模块/接口 | 仓库根：`GOWORK=off go vet ./... && GOWORK=off go test -count=1 ./...` | 需要已初始化的 Agent-Native 子模块；默认 stub，不调用真实模型 | +| 数据/权限/恢复 | conformance 与 store 测试覆盖运行落盘、HITL 恢复 | 无共享数据库 | +| UI/执行后端 | `GOWORK=off go test -count=1 ./server/... ./conformance/...` | 不覆盖浏览器；SSE 由测试客户端验证 | + +## 环境与数据 + +| 环境/实例 ID | 只读查询入口 | 授权写入入口 | DB/存储归属 | 恢复入口 | +|---|---|---|---|---| +| 本地开发 | `go test` 与 CLI `runs inspect` | CLI / `POST /v1/runs` 写入调用方指定数据目录 | 运行目录 `/runs//`，无共享 DB | 进程重启后 `POST /v1/runs/{id}/resume`，磁盘为权威 | + +共享项及 ACL：无。部署、迁移、发布的审批依据与负责角色：库本身不部署；`agent-squad serve` 仅作本地组合根，合并进 `main` 由仓库所有者批准。 +实际制品/配置/schema 的查询方法：以当前 `main` 的 `squad` 模型与 HTTP 路由为准。 diff --git a/deps/development-guidelines b/deps/development-guidelines new file mode 160000 index 0000000..26b562d --- /dev/null +++ b/deps/development-guidelines @@ -0,0 +1 @@ +Subproject commit 26b562d2e34fbc560711296a309c91c74ffc55b1 diff --git a/docs/records/2026-09-29-guidelines-and-observability.md b/docs/records/2026-09-29-guidelines-and-observability.md new file mode 100644 index 0000000..a030afc --- /dev/null +++ b/docs/records/2026-09-29-guidelines-and-observability.md @@ -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，并跑一致性脚本。验证证据实现后另写记录。 diff --git a/policy/guidelines-adoption.md b/policy/guidelines-adoption.md new file mode 100644 index 0000000..114d657 --- /dev/null +++ b/policy/guidelines-adoption.md @@ -0,0 +1,41 @@ +# 通用规范采纳记录 + +- 项目/负责人：Agent-Squad / 仓库所有者 weichen +- 状态：active +- 规范位置：`deps/development-guidelines` +- 规范性文档目录：`policy/` +- 过程文档位置：`docs/records/`（项目内固定目录豁免。个人维护的编排库，任务主记录仍在 Gitea Issue/PR。过程记录不进规范库，也不写成与 Issue 平行的第二状态。） +- 版本权威：父仓 gitlink；可读标签：无（内容版本 `0.1.0-draft.6`，提交 `26b562d2e34fbc560711296a309c91c74ffc55b1`） +- 批准/生效依据：本仓接入提交 +- 替代范围和迁移说明：本仓此前没有根 `AGENTS.md`。Agent-Native 子模块将从仓库根迁到 `deps/agent-native`，迁移说明见 `docs/records/2026-09-29-guidelines-and-observability.md`。 + +| 规范/工作流 | 适用条件与范围 | 采纳或不适用理由 | 执行方式/证据 | +|---|---|---|---| +| core/baseline.md | 日常工作 | 编排库对外有失败关闭语义 | manual | +| workflows/delivery.md、debugging.md、handoff.md | 交付、排障与交接 | 跨仓组合需要可交接记录 | manual | +| standards/collaboration.md | 并行共同起点与组合升级 | 父仓 gitlink 锁定 Agent-Native 与基础库 | manual | +| standards/verification.md | 验证与结论 | `GOWORK=off go test` | manual；命令见 PROJECT.md | +| workflows/design-verification.md、standards/testability.md、standards/failure-containment.md | 规划、执行、HITL | conformance 覆盖公开 API | manual | +| standards/module-contracts.md | squad 与 agent-native 边界 | 依赖方向只允许 squad → agent-native | manual | +| standards/observability.md | HTTP 信封、trace、事件 | 接入错误码库与日志库 | manual | +| standards/agent-execution.md | 角色绑定的执行后端 | 本库不实现 Agent | manual | +| standards/multi-repo.md | 多级 submodule | 本仓 replace 是编译时的唯一依赖解析 | manual | +| standards/data-reliability.md | 运行目录、HITL 恢复、幂等回应 | 磁盘为权威 | manual | +| standards/security.md | bash 权限挂起、脱敏 | 事件落盘沿用现有脱敏；凭证走环境变量 | manual | +| standards/configuration.md | HITL 模式、规划器、日志配置 | 环境变量与 CLI 标志 | manual | +| standards/documentation.md | 三层文档 | `policy/` 与 `docs/records/` | manual | +| standards/release-operations.md | 独立发布流水线 | 当前无制品仓库 | 不适用 | +| workflows/automation.md | serve 内 15s wakeup sweep | 有界、可手动触发；不另建定时系统 | manual | + +## 项目差异 + +| 原规则/章节 | 项目采用方式 | 原因与风险 | 负责人/复查条件 | +|---|---|---|---| +| documentation.md 过程仓默认独立仓库 | 过程记录放 `docs/records/` | 同 Agent-Native：避免个人项目再维护一个过程仓。风险是证据与代码同库 | 多人协作或对外发布时复查 | +| multi-repo.md 组件说明不手写第二套 SHA | PROJECT.md 只写路径与角色，SHA 以 `git submodule status` 为准 | 手抄 SHA 会与 gitlink 漂移 | 每次依赖升级核对脚本 | + +## 本次升级或首次接入验证 + +- `deps/development-guidelines` 固定 `26b562d2e34fbc560711296a309c91c74ffc55b1`。 +- 执行方式为 manual。 +- 回退该规范挂载时，同时确认 Agent-Native 子模块路径是否已迁移；只还原规范 gitlink 不会把 `deps/agent-native` 移回根目录。