60 lines
7.3 KiB
Markdown
60 lines
7.3 KiB
Markdown
# 通用规范采纳记录
|
||
|
||
- 项目/负责人：Agent-Squad / weichen
|
||
- 状态：active
|
||
- 规范位置：`deps/development-guidelines`
|
||
- 规范性文档目录：`policy/`
|
||
- 过程文档位置：任务卡在 `.task/`（`.task/feature-governance-adoption.md`）；任务主记录在 Gitea PR 中维护。既有过程记录仍按项目内固定目录豁免留在 `docs/records/`。过程记录不进规范库，也不写成与 Issue/PR 平行的第二状态。
|
||
- 版本权威：本仓 gitlink deps/development-guidelines @ 2688fd2be6a5（完整 `2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb`，内容版本 `0.1.0-draft.12`，无已发布标签）
|
||
- 批准/生效依据：`feature/governance-adoption PR（Agent-Squad）`
|
||
- 替代范围和迁移说明：本次替代 2026-09-29 采纳的固定版本 `26b562d2e34f`（内容版本 `0.1.0-draft.6`），规则条目按 `0.1.0-draft.12` 重新核对。新增 `AGENT-EXECUTION.md` 执行路由、`deps/development-manager` gitlink（`bd3a7de57a3a`）、`scripts/dm`、`scripts/agent-exec`、`scripts/task`、`scripts/hooks/pre-commit`、`.gitea/workflows/governance.yml` 与任务卡模板。不改业务代码，不改既有 `.gitea/workflows/ci.yml`。此前迁移说明见 `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/merge-queue.md | 多个就绪任务的最终同步、CI、Review 与合入调度 | 多个 agent 单元并行开发，合入须串行同步；协调者为仓库所有者 | manual |
|
||
| standards/verification.md | 验证与结论 | `GOWORK=off go test` | manual；命令见 PROJECT.md（含 `scripts/agent-exec validate --repo .`、`scripts/dm governance check --repo .`） |
|
||
| 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 CLI 执行路由、会话隔离与受控集成 | 凡允许 AI 协助工程变更必须采纳；路由配置见 AGENT-EXECUTION.md；本库不实现 Agent | 执行方式：AGENT-EXECUTION.md + scripts/agent-exec（validate / admit）；证据：`governance check + 正负例（.task/feature-governance-adoption.md）` |
|
||
| standards/tool-adaptation.md | 为具体工具创建规则与钩子 | 本次引入 `scripts/hooks/pre-commit`（启用由 host/人执行，`core.hooksPath`） | manual；启用后以本仓 pre-commit 检查为证据 |
|
||
| 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：避免个人项目再维护一个过程仓。风险是过程记录与代码同库 | 多人协作或对外发布时复查 |
|
||
| documentation.md 过程仓默认独立仓库 | 任务卡与交付证据放 `.task/`（模板 `.task/templates/task-card.md`） | 任务状态仍只认 Gitea Issue/PR，`.task/` 不写成平行状态；风险是任务卡与代码同库 | 多人协作或对外发布时复查 |
|
||
| multi-repo.md 组件说明不手写第二套 SHA | PROJECT.md 只写路径与角色，SHA 以 `git submodule status` 为准 | 手抄 SHA 会与 gitlink 漂移 | 每次依赖升级核对脚本 |
|
||
|
||
## 本次升级或首次接入验证
|
||
|
||
- `deps/development-guidelines` 固定 `2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb`（内容版本 `0.1.0-draft.12`）；`deps/development-manager` 固定 `bd3a7de57a3a9e1a4495b94c5fa5c08d71e7be8c`。
|
||
- 工程 Agent 执行：`AGENT-EXECUTION.md` 为唯一路由权威；AI 实施单元只经 `scripts/agent-exec run` 执行，并经 `scripts/agent-exec apply` 集成。`scripts/agent-exec` 与 `scripts/task` 只是转调 `scripts/dm` 的薄入口。
|
||
- 登记为 active 的前置证据：一次成功执行正例（有效 `completed` 收据经 transport/admission 集成）；缺配置、无效终态收据、越权路径、未知副作用四类负例均被拒绝或 fail-stop。证据按 `.task/feature-governance-adoption.md` 记录。
|
||
- 入口核验：`scripts/dm governance check --repo .` 与 `scripts/agent-exec validate --repo .`（PROJECT.md「验证」节）。CI 由 `.gitea/workflows/governance.yml` 执行；既有 `ci.yml` 未改。
|
||
- 回退该规范挂载时，恢复上一已批准 gitlink `26b562d2e34f`，并同时还原本次新增的治理脚本与 `governance.yml`；如已启用 `core.hooksPath`，需一并关闭。只还原规范 gitlink 不会把 `deps/agent-native` 移回根目录。
|
||
|
||
### 2026-09-29 追加：agent-intent 可选意图闸门
|
||
|
||
- 新增 `deps/agent-intent`（固定 `55780ae2cce4ae98d8b0557b8234af8833a7c522`）；`deps/error-code-system` 前进到 `dbeed2f1b67eb417ce089e7033a228578fbbeb03`（`squad.intent_refused`，追加式）；`deps/agent-native` 前进到 `c659dc17d5086a8128999011994fc2dbe73419d3`（其仓内新增 intentgate 装饰器）。
|
||
- 依赖边界新增：唯 `squadintent` 与 cli 组合根可 import agent-intent；`squad`/`server`/`store` 不感知意图；未配置意图时引擎行为与原实现一致。
|
||
- 接入与验证记录见 [docs/records/2026-09-29-intent-gate-adoption.md](../docs/records/2026-09-29-intent-gate-adoption.md)；跨仓测试报告见 Agent-Intent 仓 docs/records。
|
||
- 回退：删 `squadintent/` 与 cli 接线、go.mod 两行、submodule 与 `.gitmodules` 条目、一致性脚本对应段；可将 agent-native 回退到 `cc8a6a7`（其 intentgate 为可选包，不回退亦可编译）。
|
||
|
||
### 2026-09-29 追加（二）：目录驱动的编排
|
||
|
||
- `deps/agent-intent` 前进到 `3674dc4bfd0b49191d21f0afab4002381e41a429`（槽位约束与能力目录，E2/E4）；`deps/agent-native` 前进到 `292142ac1a8b125488794e9374faee2cb1c8c579`（pin 同步）。
|
||
- 新增能力目录（`squad.IntentCatalog` 数据视图）与系统功能步（`StepSpec.IntentID` + `IntentRunner`）；核心包仍零 import agent-intent。
|
||
- 接入与验证记录见 [docs/records/2026-09-29-catalog-driven-orchestration.md](../docs/records/2026-09-29-catalog-driven-orchestration.md)。
|