diff --git a/.cursor/rules/agent-collaboration-docs.mdc b/.cursor/rules/agent-collaboration-docs.mdc index 279d0adf..35758745 100644 --- a/.cursor/rules/agent-collaboration-docs.mdc +++ b/.cursor/rules/agent-collaboration-docs.mdc @@ -9,15 +9,16 @@ alwaysApply: true ## 开场必读 -1. `AGENTS.md` → `PROJECT.md` → `.doc/ops/CURRENT.md` → 相关 short-term / handoff +1. `AGENTS.md` → `PROJECT.md` → `.doc/README.md` → `.doc/ops/CURRENT.md` → `FEATURE-MATRIX` → short-term / handoff ## 红线 -- 任何任务/调研/审计/修复/运维：**开始前**建或更新 `.doc/ops/short-term/` 或 `long-term/`（复制 templates） -- **禁止**只改代码、真相只留在聊天 -- 里程碑更新 `CURRENT.md`；会话结束写 `handoffs/` -- 验收报告进 `.doc/test-reports/` 并回链 checklist -- 文档与代码同批或紧随 `docs(...)` 提交 +- 任务开始前：short-term/long-term + CURRENT 并行认领（mutex） +- 合 dev + 容器测：占用 CURRENT 集成槽位；他人 queue 等待 +- 多 Agent 并行：worktree（`.worktrees/`）；禁止 worktree 内 env-service start +- 禁止只改代码；done 任务 → `archive/ops/` +- 验收报告 → `.doc/test-reports/`；运行产物 → `test-reports/assets/` +- 禁止在 `.doc/` 根或 `docs/` 随意新建文档 ## 状态 diff --git a/.cursor/rules/test-reports-standard.mdc b/.cursor/rules/test-reports-standard.mdc index 3d23706c..8eb00670 100644 --- a/.cursor/rules/test-reports-standard.mdc +++ b/.cursor/rules/test-reports-standard.mdc @@ -13,7 +13,7 @@ alwaysApply: true - **统一目录**：所有测试报告必须统一存放于 `.doc/test-reports/` 目录下。 - **命名规范**：遵循 `YYYY-MM-DD-<模块/功能/版本>-test-report.md` 命名格式。 - 例如：`.doc/test-reports/2026-09-07-three-branch-intent-framework-test-report.md` - - 例如：`.doc/test-reports/2026-09-07-bizdev-workflow-integration-test-report.md` +- **证据附件**：运行产物（json/jsonl、workspace 快照、截图）放 `.doc/test-reports/assets//`，**不得**与 `*-test-report.md` 混放在同一层级目录。 --- @@ -58,7 +58,7 @@ alwaysApply: true 1. **真实 Agent 交付铁律（红线）**： - **开发实现阶段**：可以快速使用 `stub` 验证状态机、协议分流、数据落盘与逻辑契约，加速反馈； - - **交付前验收与测试报告生成**：**必须切回真实环境与真实 Agent（`pi-agent` + 实际运行的 `MiniMax-M3` 容器）进行全链路端到端实测**； + - **交付前验收与测试报告生成**：**必须切回真实环境与真实 Agent（`pi-agent` + 实际运行的 `MiniMax-M2.7-highspeed` 容器）进行全链路端到端实测**； - **严禁**使用 stub 的测试输出作为最终交付报告的验收数据。 2. **严禁散落存放**：测试报告统一归档至 `.doc/test-reports/` 目录下，禁止散落在根目录或临时沙箱中。 3. **真实控制台取样**：测试报告中的输入、输出、耗时与判定必须取自实际环境运行的真实控制台输出与日志。 diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index 05326424..8f7c46d7 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -5,13 +5,27 @@ ## 焦点 -1. **已修复**：dev pi-agent provider 误为 `cc-switch-kimi-for-coding` → 已对齐 `.env` 的 `minimax` + `MiniMax-M2.7-highspeed`（见 short-term） -2. Codex 审计 P0 整改 **Wave 0–D 已全部完成**；main 本地冒烟已通过 - -## 剩余（非 P0） - 1. **CI**: `TEST_DATABASE_URL` + 真实 PI E2E 实录 -2. **BACKLOG**: session cookie / bundle 拆分 / 容量治理 +2. **前端**: 版本冲突刷新、终止 preview 人工抽检 +3. **BACKLOG**: session cookie / bundle 拆分 / 容量治理（见 [backlog](../backlog/chat-agent-p6-backlog.md)） + +## 并行认领 + +| owner | task | branch | worktree | mutex | status | +|-------|------|--------|----------|-------|--------| +| — | — | — | — | — | — | + +> 新任务开始前登记。同一 `mutex` 同时仅一个 `in_progress`。 + +## 集成槽位 + +| holder | phase | since | scope | queue | +|--------|-------|-------|-------|-------| +| idle | - | - | - | - | + +**phase**: `idle` | `merging` | `smoke` | `e2e` + +> 合入 `dev` + 共享容器验证必须串行。详见 [AGENTS.md](../../AGENTS.md) §6.3。 ## 环境快照 @@ -19,12 +33,14 @@ |------|------|--------|------| | dev | 8080 | 25 | healthy | | test | 8081 | 25 | healthy | -| main | 8000 | 25 | healthy（本地冒烟） | +| main | 8000 | 25 | healthy（app + runner + DB） | ## SSOT | 类型 | 路径 | |------|------| -| 发布缺口 | [gap-matrix](../2026-09-12-remediation-gap-matrix.md) | -| 测试报告 | [test-report](../test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md) | +| 文档总地图 | [../README.md](../README.md) | +| 模块完成度 | [FEATURE-MATRIX](../status/FEATURE-MATRIX.md) | +| 发布缺口 | [gap-matrix](../remediation/gap-matrix.md) | +| 测试报告 | [test-reports/](../test-reports/) | | Agent 手册 | [AGENTS.md](../../AGENTS.md) | diff --git a/.doc/ops/README.md b/.doc/ops/README.md index 7ee08f40..5dceaaca 100644 --- a/.doc/ops/README.md +++ b/.doc/ops/README.md @@ -1,24 +1,25 @@ # 活协作区（.doc/ops） -Agent 会话级协作文档，与 Git 跟踪的审计/设计文档分离。 +Agent 会话级协作文档。完整 taxonomy 见 [../README.md](../README.md)。 ## 用法 -1. 会话开始读 [CURRENT.md](./CURRENT.md) +1. 会话开始读 [CURRENT.md](./CURRENT.md)（含并行认领 + 集成槽位） 2. 新任务复制 [templates/](./templates/) 到对应目录 -3. 完成或切换 Agent 时写 [handoffs/](./handoffs/) +3. 结束按 [session-close-checklist.md](./templates/session-close-checklist.md)；换人写 [handoffs/](./handoffs/) ## 状态 -- **current**：进行中条目 + CURRENT.md -- **historical**：已完成条目保留，标 `done` 或移入归档 +- **current**：进行中 + CURRENT.md +- **historical**：标 `done` 并移入 [../archive/ops/](../archive/ops/) -## 与 SSOT 关系 +## SSOT 关系 -| 类型 | 位置 | +| 类型 | 路径 | |------|------| -| 协作焦点 | 本目录 CURRENT | -| 发布/审计缺口 | [gap-matrix](../2026-09-12-remediation-gap-matrix.md) | +| 协作焦点 | CURRENT | +| 模块完成度 | [FEATURE-MATRIX](../status/FEATURE-MATRIX.md) | +| 发布缺口 | [gap-matrix](../remediation/gap-matrix.md) | | 验收报告 | [test-reports](../test-reports/) | -通用纪律见仓库根 [AGENTS.md](../../AGENTS.md)。 +通用纪律见 [AGENTS.md](../../AGENTS.md)。 diff --git a/.doc/ops/checklists/2026-09-13-codex-audit-p0-remediation.md b/.doc/ops/checklists/2026-09-13-codex-audit-p0-remediation.md deleted file mode 100644 index 2def7995..00000000 --- a/.doc/ops/checklists/2026-09-13-codex-audit-p0-remediation.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Codex 审计 P0 整改 Checklist" -status: done -created: 2026-09-13 -updated: 2026-09-13 -related_task: short-term/2026-09-13-codex-audit-p0-remediation.md ---- - -# Codex 审计 P0 整改 Checklist - -## Wave 0 — Agent 文档 - -- [x] AGENTS.md / PROJECT.md / CLAUDE.md — commit 31fe607 -- [x] .cursor/rules — agent-collaboration + git-secrets -- [x] .doc/ops templates + CURRENT - -## Wave A — P0 - -- [x] AUTH tasks/run + stream — commit d82021e；`task_run_authz_pg_test.go` -- [x] DB 00025 — commit b13ced6；dev/test setval -- [x] DATA lifecycle — dev UPDATE 47 → 0 -- [x] DATA test wf — UPDATE 5 retired - -## Wave B — Go 门禁 - -- [x] go vet ./... PASS — commit 91985a2 -- [x] go test -short ./... PASS -- [x] AdvisorBrief / V0.5 / chat / kb / health / asset - -## Wave C — 环境 - -- [x] test rebuild schema 25 — health 8081 -- [x] dev docker app schema 25 — health 8080 -- [x] main 冒烟 — health/ready 8000 schema 25；restart 恢复 -- [x] HTTP 超时 + env status 只读 — commit 505c419 -- [x] .env.dev/.env.test chmod 600 - -## Wave D — 文档 - -- [x] gap-matrix Codex 项 -- [x] AUDIT-INDEX + superseded 横幅 -- [x] quick-ref 断链修复 -- [x] [test-report](../test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md) - -## 完成定义 - -- [x] P0/门禁项已闭环（main 除外，已记 OPEN） diff --git a/.doc/ops/handoffs/2026-09-13-container-env-configuration.md b/.doc/ops/handoffs/2026-09-13-container-env-configuration.md new file mode 100644 index 00000000..c071c378 --- /dev/null +++ b/.doc/ops/handoffs/2026-09-13-container-env-configuration.md @@ -0,0 +1,54 @@ +--- +title: "容器与 env 配置审计补密钥交接" +created: 2026-09-13 +from: codex +to: next-agent +status: done +--- + +# 交接：容器与 env 配置审计补密钥 + +## 目标（下一位 Agent 应完成什么） + +记录已完成的数据库密码轮换、容器重建与最终健康验证。 + +## 已完成 + +- 根 `.env` 与环境差异文件已分层，容器所需配置已透传。 +- 失效字段、重复项目名与 23GB 构建上下文问题已清理。 +- dev/test app + pi-agent 均已重建并健康；镜像实构建和 Go short 全量测试通过。 +- 用户已补齐两个密码；现有 PostgreSQL 用户已同步轮换。 +- shared/dev/test/main 均 healthy，三个 app ready 通过；独立 TCP/SCRAM 登录与 `SELECT 1` 通过。 + +## 未完成 + +- 无。 + +## 关键文件 + +| 路径 | 说明 | +|------|------| +| `.env` | 公共配置与共享 KB 密码（gitignored） | +| `configs/.env.main` | main 环境差异与 main DB 密码（gitignored） | +| `scripts/env-service.sh` | 根配置 + 环境差异分层加载 | +| `docker-compose.*.yml` | 必填校验和 app/runner 注入 | + +## 如何验证 + +```bash +docker compose -f docker-compose.shared.yml --env-file .env config -q +docker compose -f docker-compose.main.yml --env-file .env --env-file configs/.env.main config -q +go test -short ./... +./scripts/env-service.sh all status +curl -fsS http://127.0.0.1:8000/api/v1/ready +``` + +## 风险 / Blocker + +- 共享 KB 密码低于建议的 16 字符；建议后续维护窗口再次轮换。 + +## 相关链接 + +- CURRENT: [CURRENT.md](../CURRENT.md) +- Task: [audit-container-env-configuration](../short-term/2026-09-13-audit-container-env-configuration.md) +- Test report: [container-env-configuration-test-report](../../test-reports/2026-09-13-container-env-configuration-test-report.md) diff --git a/.doc/ops/research/2026-09-13-container-env-configuration-audit.md b/.doc/ops/research/2026-09-13-container-env-configuration-audit.md new file mode 100644 index 00000000..3338c708 --- /dev/null +++ b/.doc/ops/research/2026-09-13-container-env-configuration-audit.md @@ -0,0 +1,33 @@ +--- +title: "容器构建与环境变量配置链审计" +created: 2026-09-13 +status: done +confidence: high +--- + +# 调研：容器构建与环境变量配置链 + +## 结论 + +原配置链不完整：`env-service.sh` 未读取根 `.env`，app 容器未透传多项已配置能力，test/main 仍选择 `stub`，且 `COMPOSE_PROJECT_NAME` 会导致共享环境串到 dev。上述配置链均已修复。另发现的共享 KB 与 main 业务库示例弱密码也已由用户补值、在现有 PostgreSQL volume 内同步轮换并完成 TCP/SCRAM 复验。 + +## 证据 + +| 项 | 路径/命令 | 结果 | +|----|-----------|------| +| 根配置分层 | `scripts/env-service.sh` | `.env` 公共配置先加载，`configs/.env.` 后加载并只覆盖差异 | +| app 透传 | `docker-compose.{dev,test,main}.yml` | Agent 超时/并发、Embedding/Reranker、认证、CORS、缓存、意图开关均注入 | +| 真实 Agent | `configs/.env.{test,main}(.example)` | `AGENT_BACKEND=pi-agent`，main runner 端口补为 18867 | +| 串环境 | `./scripts/env-service.sh all status` | 删除 `COMPOSE_PROJECT_NAME` 后 shared 正确显示 `agent-infra` / `shuimu-kb-shared` | +| 构建上下文 | Docker build 输出、`.dockerignore` | `.regulations` 23GB 已排除；上下文从中止时 17.1GB 降至 12.7MB | +| 失效字段 | 全仓 `rg` | 移除 `EMBEDDING_PROVIDER`、`RERANKER_PROVIDER`、`ADMIN_TOKEN`、`ALLOW_INSECURE_ADMIN`、`AUX_FILE_DSN`、`KB_DATA_DIR` 与单 Key Tavily 透传 | +| 配置加载 | `internal/config/config.go` | 环境变量现在能覆盖 timeout、Cursor/Pi bridge 与检索模型；生产占位密码纳入拒绝列表 | +| secret 权限 | `stat -c '%a %n' ...` | 四个实际 env 文件均为 600 | + +## 开放问题 + +- 共享 KB 密码低于建议的 16 字符；当前不是已知示例值且已生效，建议后续维护窗口换成长随机值。 + +## 建议动作 + +- 后续轮换仍应保持两个数据库密码不同，并优先使用至少 16 字符的高强度随机值。 diff --git a/.doc/ops/research/2026-09-13-doc-inventory.md b/.doc/ops/research/2026-09-13-doc-inventory.md new file mode 100644 index 00000000..4f32f582 --- /dev/null +++ b/.doc/ops/research/2026-09-13-doc-inventory.md @@ -0,0 +1,38 @@ +--- +title: "全仓文档盘点" +status: done +created: 2026-09-13 +updated: 2026-09-13 +--- + +# 全仓文档盘点（2026-09-13） + +## 摘要 + +| 分类 | 路径 | 动作 | +|------|------|------| +| 审计/分析 | `.doc/audit/` | 自根目录迁入 | +| 整改方案 | `.doc/remediation/` | 自根目录迁入；gap-matrix SSOT | +| 活协作 | `.doc/ops/` | 保留；done → `archive/ops/` | +| 完成度 | `.doc/status/FEATURE-MATRIX.md` | 新建 | +| 历史设计 | `.doc/archive/design/superpowers/` | 自 `docs/superpowers/` 迁入 | +| 参考长文 | `.doc/archive/reference/` | workflow 规则归档 | +| 测试报告 | `.doc/test-reports/` | 主报告保留；workspace → `assets/` | +| 架构 | `.doc/system-design/` | 保留；修索引 | +| 遗留 stub | `.doc/` 根 15 stub | 跳转新路径 | +| 遗留 stub | `docs/superpowers/`、`docs/workflow/` | 跳转 archive / PROJECT | +| 产品模板 | `templates/docs/` | **不迁移** | +| Agent prompt | `configs/agents/` | **不迁移** | + +## 合法文档区（整理后） + +见 [AGENTS.md](../../AGENTS.md) §4 与 [.doc/README.md](../../README.md)。 + +## 禁止随意新建 + +- `.doc/` 根目录大包（仅 stub 例外） +- `docs/` 新子目录（仅 stub README） + +## 证据 + +整理执行 commit 见本任务 short-term 证据段。 diff --git a/.doc/ops/short-term/2026-09-13-codex-audit-p0-remediation.md b/.doc/ops/short-term/2026-09-13-codex-audit-p0-remediation.md deleted file mode 100644 index a2bb4d8b..00000000 --- a/.doc/ops/short-term/2026-09-13-codex-audit-p0-remediation.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Codex 审计 P0 整改" -status: done -created: 2026-09-13 -updated: 2026-09-13 -owner: agent ---- - -# Codex 审计 P0 整改 - -## 目标 - -闭环 Codex 2026-09-12 再审计 P0/门禁/环境项，并完成文档 SSOT 对齐。 - -## 范围 - -- Wave A: 任务鉴权、00025 序列、lifecycle 脏数据 -- Wave B: Go vet + short 全绿 -- Wave C: test 重建、main 冒烟 -- Wave D: gap-matrix、superseded、test-report - -## 非目标 - -- session cookie 重构 -- bundle 拆分 / 23GB 容量治理 - -## 步骤 - -1. [x] Wave 0: AGENTS.md / PROJECT.md / CLAUDE.md / ops / rules -2. [x] Wave A1: handleRunTask + SSE 鉴权 + 负例测试 -3. [x] Wave A2: goose 00025 -4. [x] Wave A3: lifecycle SQL + test 工作流退休 -5. [x] Wave B: AdvisorBrief / V0.5 / chat memory / kb gate / health -6. [x] Wave C: 环境一致性（main OPEN） -7. [x] Wave D: 文档对齐 - -## 验收标准 - -见 [checklist](../checklists/2026-09-13-codex-audit-p0-remediation.md) - -## 相关链接 - -- 调研: [research/2026-09-12-codex-reaudit-summary.md](../research/2026-09-12-codex-reaudit-summary.md) -- Gap matrix: [../../2026-09-12-remediation-gap-matrix.md](../../2026-09-12-remediation-gap-matrix.md) diff --git a/.doc/ops/short-term/2026-09-13-fix-piagent-provider-minimax.md b/.doc/ops/short-term/2026-09-13-fix-piagent-provider-minimax.md deleted file mode 100644 index fd492f8b..00000000 --- a/.doc/ops/short-term/2026-09-13-fix-piagent-provider-minimax.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "修复 pi-agent Unknown provider cc-switch-kimi-for-coding" -status: done -created: 2026-09-13 -updated: 2026-09-13 -owner: agent ---- - -# 修复 pi-agent Unknown provider cc-switch-kimi-for-coding - -## 目标 - -任务 `run_1789263149536199173` / workspace `intake_1789263149571817685` 因错误 provider 中断；恢复为与根 `.env` 一致的 `minimax` + `MiniMax-M2.7-highspeed`。 - -## 范围 - -- 修正 `internal/config/config.go` 错误默认值 -- 同步 `configs/.env.dev` 与 compose 注入（不编造新密钥/新 endpoint） -- 对齐根 `.env` 中 `PI_AGENT_MODEL` 与 `MINIMAX_MODEL_ID` -- 重启 / 重建 dev 的 app / pi-agent 使配置生效 - -## 非目标 - -- 不改动 test/main 环境密钥 -- 不擅自更换 API endpoint / API key -- 不在本任务内重跑完整业务长任务（修复后由用户 continue/restart） - -## 步骤 - -1. [x] 根因定位：Go 默认 `cc-switch-kimi-for-coding`；app 容器无 `PI_AGENT_*` 覆盖 -2. [x] 修正代码默认值与 `.env` / `.env.dev` / compose -3. [x] force-recreate + rebuild；health 已显示 `MiniMax-M2.7-highspeed` -4. [x] 提交 `8f3aa0f` - -## 验收标准 - -- [x] `shuimu-pi-agent-dev` health 显示 `MiniMax-M2.7-highspeed` -- [x] app 进程生效 `PI_AGENT_PROVIDER=minimax`、`PI_AGENT_MODEL=MiniMax-M2.7-highspeed` -- [x] 配置链不再默认 `cc-switch-kimi-for-coding`（业务 continue/restart 由用户触发验证） - -## 相关链接 - -- 失败 workspace: `data/dev/workspaces/bizdev/intake_1789263149571817685` -- 根配置: `.env`（`MINIMAX_MODEL_ID=MiniMax-M2.7-highspeed`） - -## 证据 / 备注 - -- upstream: `step step_01_organize failed: Error: Unknown provider "cc-switch-kimi-for-coding"` -- blame: `abd0893e` 将默认从 anthropic 误改为 kimi -- 验证：`curl :18865/health` → `model_id=MiniMax-M2.7-highspeed`；app env 含 `PI_AGENT_PROVIDER=minimax` diff --git a/.doc/ops/templates/audit-note.md b/.doc/ops/templates/audit-note.md new file mode 100644 index 00000000..ef2adeef --- /dev/null +++ b/.doc/ops/templates/audit-note.md @@ -0,0 +1,33 @@ +--- +title: "<审计/分析标题>" +status: planned +created: YYYY-MM-DD +updated: YYYY-MM-DD +severity: medium +--- + +# <审计/分析标题> + +## 现象 + +（可观测症状） + +## 根因分析 + +（证据路径、代码引用） + +## 严重度 + +`critical` | `high` | `medium` | `low` + +## 关联整改 + +- Remediation: + +## 证据 + +（命令输出、日志、文件路径） + +## 开放问题 + +- diff --git a/.doc/ops/templates/feature-matrix-row.md b/.doc/ops/templates/feature-matrix-row.md new file mode 100644 index 00000000..886dc951 --- /dev/null +++ b/.doc/ops/templates/feature-matrix-row.md @@ -0,0 +1 @@ +| <模块名> | <能力描述> | planned | （设计/代码/test-report 链接） | （缺口） | `` | diff --git a/.doc/ops/templates/handoff.md b/.doc/ops/templates/handoff.md index ca475420..48d0bad8 100644 --- a/.doc/ops/templates/handoff.md +++ b/.doc/ops/templates/handoff.md @@ -18,6 +18,17 @@ status: open - +## 认领 / 槽位状态 + +| 项 | 值 | +|----|-----| +| mutex 已释放 | yes / no | +| 集成槽位 holder | idle / 需接管 | +| branch | | +| worktree | | + +> 若 mutex 未释放，下一位须先在 CURRENT 认领或写 blocker。 + ## 关键文件 | 路径 | 说明 | diff --git a/.doc/ops/templates/remediation-plan.md b/.doc/ops/templates/remediation-plan.md new file mode 100644 index 00000000..845b547b --- /dev/null +++ b/.doc/ops/templates/remediation-plan.md @@ -0,0 +1,32 @@ +--- +title: "<整改方案标题>" +status: planned +created: YYYY-MM-DD +updated: YYYY-MM-DD +--- + +# <整改方案标题> + +## 背景 + +（链到 audit/ 分析文档） + +## 目标 + +（可验证的整改结果） + +## 分波次计划 + +| 波次 | 内容 | 验收 | +|------|------|------| +| Wave 0 | | | + +## 验收标准 + +- [ ] + +## 相关链接 + +- Audit: +- Short-term: +- gap-matrix 行: diff --git a/.doc/ops/templates/session-close-checklist.md b/.doc/ops/templates/session-close-checklist.md new file mode 100644 index 00000000..7fe12942 --- /dev/null +++ b/.doc/ops/templates/session-close-checklist.md @@ -0,0 +1,27 @@ +# 会话结束清单 + +任务完成或切换 Agent 前逐项勾选： + +## 认领与集成 + +- [ ] CURRENT「并行认领」行 status 已更新（done 或移除） +- [ ] 若曾占集成槽位：smoke 已完成，holder=idle，queue 已通知 +- [ ] mutex 无遗留 in_progress（除明确 handoff 交接项） + +## 代码与分支 + +- [ ] 非 trivial 改动已 merge `--no-ff` 到 dev（或 handoff 说明未 merge 原因） +- [ ] 无未 push 的 dev 关键提交（若用户要求同步远端） + +## 文档 + +- [ ] [FEATURE-MATRIX.md](../../status/FEATURE-MATRIX.md) 已更新（若模块状态变） +- [ ] [gap-matrix.md](../../remediation/gap-matrix.md) 已更新（若 blocker 变） +- [ ] 任务 frontmatter status=done +- [ ] done 任务已 `git mv` 到 [archive/ops/](../../archive/ops/) +- [ ] [CURRENT.md](../CURRENT.md) 焦点 1–3 条已刷新 +- [ ] 若换人：已写 [handoffs/](../handoffs/) + +## 提交 + +- [ ] 文档与代码同批或紧随 `docs(...)` 提交 diff --git a/.doc/ops/templates/short-term-task.md b/.doc/ops/templates/short-term-task.md index b24ee85a..ac16f3ce 100644 --- a/.doc/ops/templates/short-term-task.md +++ b/.doc/ops/templates/short-term-task.md @@ -4,6 +4,9 @@ status: planned created: YYYY-MM-DD updated: YYYY-MM-DD owner: agent +branch: feature/ +worktree: "-" +mutex: --- # <任务标题> diff --git a/.doc/system-design/README.md b/.doc/system-design/README.md index 370f0af0..da71ad6c 100644 --- a/.doc/system-design/README.md +++ b/.doc/system-design/README.md @@ -11,7 +11,7 @@ | 项 | 链接 | |-----|------| -| 主报告 | [intention-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md](intention-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md) | +| 主报告 | [intent-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md](intent-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md) | | 中间分析 | [.tmp/intent-recognition/](../.tmp/intent-recognition/) | | 一句话总结 | 纯规则 + 四级漏斗 + 三分支消解的 L1 协作对话层 | @@ -121,8 +121,13 @@ │ └── 01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md ├── agent-squad/ │ └── 02-智能体小队编排-设计-思路-架构-实现-难点-解决方案-亮点与优势.md -└── multi-turn-dialogue/ - └── 03-多轮对话优化-设计-架构-实现-难点-解决方案-亮点与优势.md +├── multi-turn-dialogue/ +│ └── 03-多轮对话优化-设计-架构-实现-难点-解决方案-亮点与优势.md +└── project-workflow/ + ├── 03-项目多工作流与智能产品经理-测试经理工作流-设计方案.md + ├── 04-项目多工作流与智能产品经理-测试经理工作流-实施计划.md + ├── 05-Phase0-基线确认与契约冻结.md + └── 06-Phase7-全链路验收与发布基线.md .tmp/ ← 中间分析文件 ├── intent-recognition/ @@ -147,3 +152,4 @@ - 架构总览：[.doc/system-design/architecture-design.md](../architecture-design.md)（已有的项目骨架设计文档） - 测试报告：[.doc/test-reports/](../test-reports/)（多轮多角色端到端测试报告） +- 历史功能设计：[.doc/archive/design/superpowers/](../archive/design/superpowers/) diff --git a/AGENTS.md b/AGENTS.md index 74b14f8a..8bfdada6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ ## 1. 目的与适用范围 -- 适用于在本仓库工作的所有编码 Agent（Cursor、Claude Code、Codex 等）。 +- 适用于在本仓库工作的所有编码 Agent（Cursor、Claude Code、Codex、Kimi、Antigravity 等）。 - **聊天记录易失**；Git 与活文档区才是可协作、可审计的真相来源。 - 任何任务、调研、审计、修复、运维操作均须同步落盘，禁止「只改代码 / 只留在对话」。 @@ -17,11 +17,13 @@ 每次会话开始，按顺序阅读： -1. **本文件** `AGENTS.md`（通用工作方式） +1. **本文件** `AGENTS.md` 2. **[PROJECT.md](./PROJECT.md)**（本仓库地图与约定） -3. **`.doc/ops/CURRENT.md`**（当前焦点、阻塞、下一步） -4. 相关 **short-term 任务** / **handoff**（若存在） -5. 发布/审计类任务：再读 PROJECT 指向的 gap-matrix 等 SSOT +3. **[`.doc/README.md`](./.doc/README.md)**（文档 taxonomy） +4. **[`.doc/ops/CURRENT.md`](./.doc/ops/CURRENT.md)**（焦点、并行认领、集成槽位） +5. **[`.doc/status/FEATURE-MATRIX.md`](./.doc/status/FEATURE-MATRIX.md)**（模块完成度） +6. 相关 **short-term** / **handoff** / **audit** / **remediation** +7. 发布/审计类任务：[`remediation/gap-matrix.md`](./.doc/remediation/gap-matrix.md) **未读完不得开始改代码**（紧急热修除外，事后必须在 24h 内补文档）。 @@ -32,167 +34,212 @@ | 时机 | 必须动作 | |------|----------| | 任务开始 | 在 `short-term/` 或 `long-term/` 新建或更新条目（复制 templates） | -| 里程碑 | 更新任务文 `status` 与 `CURRENT.md` | -| 调研/审计 | 写入 `research/` 或任务文「证据」段 | -| 验收 | 写 test-report（路径见 PROJECT），回链到 checklist | -| 会话结束/切换 Agent | 写或更新 `handoffs/` | +| 认领 | 在 CURRENT「并行认领」表登记 owner / branch / mutex | +| 合 dev + 容器测 | 占用 CURRENT「集成槽位」；他人排队 | +| 里程碑 | 更新任务文 `status`、FEATURE-MATRIX、CURRENT | +| 调研/审计 | 写入 `audit/` 或 `ops/research/` | +| 整改方案 | 写入 `remediation/` | +| 验收 | 写 test-report（路径见 PROJECT），回链 checklist | +| 会话结束/切换 Agent | 按 [session-close-checklist](./.doc/ops/templates/session-close-checklist.md) | | 提交 | 文档变更与代码同批或紧随 `docs(...)` 提交 | **状态字段**：`planned | in_progress | blocked | done | cancelled` -**current vs historical**：完成项标 `done` 或移入归档；不删除证据。 +**current vs historical**：完成项标 `done` 并移入 `archive/`；不删除证据。 --- -## 4. 活文档区约定 +## 4. 文档 taxonomy -默认路径：`.doc/ops/`（可由 PROJECT 覆盖） +默认路径：`.doc/`（详见 [`.doc/README.md`](./.doc/README.md)） ```text -.doc/ops/ - README.md # 本区用法 - CURRENT.md # 一页纸：当前焦点（会话必读） - short-term/ # 本迭代可关闭的任务 - long-term/ # 跨迭代 backlog - checklists/ # 可勾选验收清单 - handoffs/ # 会话交接 - research/ # 调研笔记实例 - templates/ # 新建条目时复制 +.doc/ + README.md # 总地图 + status/ # FEATURE-MATRIX（模块完成度 SSOT） + audit/ # 问题发现与分析 + remediation/ # 整改方案；gap-matrix（发布 blocker） + archive/ # 历史（只增不删） + ops/ # 活协作：CURRENT、short-term、handoffs… + system-design/ # 模块架构深读 + adr/ | backlog/ | test-reports/ | test-fixtures/ ``` +**红线**：禁止在 `.doc/` 根或 `docs/` 随意新建项目文档；新文档必须落入 taxonomy。 + **命名**：`YYYY-MM-DD-.md` --- ## 5. 文档类型与何时使用 -### 短期任务（short-term） - -- **何时**：本迭代可关闭的具体工作 -- **必含**：目标、范围、非目标、步骤、验收标准、相关链接 -- **模板**：`.doc/ops/templates/short-term-task.md` - -### 长期任务（long-term） - -- **何时**：跨迭代 backlog、架构债、未排期改进 -- **必含**：动机、成功标准、依赖、暂不启动原因 -- **模板**：`.doc/ops/templates/long-term-task.md` - -### Checklist（checklists） - -- **何时**：可勾选验收；与短任务 1:1 或 1:N -- **必含**：每项 `[ ]` / `[x]` + 证据链接（commit、报告、命令输出） -- **模板**：`.doc/ops/templates/checklist.md` - -### 调研笔记（research） - -- **何时**：只读调查、审计复核、根因分析 -- **必含**：结论、证据路径、开放问题、置信度 -- **模板**：`.doc/ops/templates/research-note.md` - -### 交接（handoffs） - -- **何时**：会话结束、切换 Agent、长时间阻塞 -- **必含**：目标、已完成、未完成、关键文件、如何验证、风险 -- **模板**：`.doc/ops/templates/handoff.md` - -### 报告（test-reports） - -- 路径由 **PROJECT.md** 指定（本仓为 `.doc/test-reports/`） -- **原则**：真实控制台/日志取样；禁止 stub 冒充最终验收 -- 在任务文与 `CURRENT.md` 中用相对链接引用 +| 类型 | 路径 | 模板 | +|------|------|------| +| 问题/分析 | `audit/` | [audit-note.md](./.doc/ops/templates/audit-note.md) | +| 整改方案 | `remediation/` | [remediation-plan.md](./.doc/ops/templates/remediation-plan.md) | +| 短期任务 | `ops/short-term/` | [short-term-task.md](./.doc/ops/templates/short-term-task.md) | +| 长期 backlog | `ops/long-term/` | [long-term-task.md](./.doc/ops/templates/long-term-task.md) | +| Checklist | `ops/checklists/` | [checklist.md](./.doc/ops/templates/checklist.md) | +| 交接 | `ops/handoffs/` | [handoff.md](./.doc/ops/templates/handoff.md) | +| 调研 | `ops/research/` | [research-note.md](./.doc/ops/templates/research-note.md) | +| 模块完成度 | `status/FEATURE-MATRIX.md` | [feature-matrix-row.md](./.doc/ops/templates/feature-matrix-row.md) | +| 验收报告 | `.doc/test-reports/` | 见 test-reports-standard | +| 历史 | `archive/**` | 关闭后迁入 | --- ## 6. 多 Agent 协作 -- **单一焦点**：`CURRENT.md` 只列 1–3 个当前焦点 -- **并行任务**：在 CURRENT 列出 owner/agent 标识与互斥资源（分支、文件、环境） -- **不覆盖**：不覆盖他人未合并工作区；发现冲突先写 handoff/blocker +### 6.1 并行认领（编码阶段） + +任务开始前在 CURRENT「并行认领」表登记： + +| 字段 | 说明 | +|------|------| +| owner | 工具 + 标识 | +| task | short-term 文件名 | +| branch | `feature/*` 或 `fix/*` | +| worktree | 路径或 `-` | +| mutex | 模块名（见 FEATURE-MATRIX） | +| status | `in_progress` / `blocked` / `done` | + +**同一 mutex 同时仅一个 `in_progress`**。冲突 → 写 handoff blocker，禁止覆盖他人未合并改动。 + +### 6.2 分支与 Worktree + +- 非 trivial 改动必须独立分支，禁止多人直推同一 dev 工作区抢改。 +- **多 Agent 并行时强制 worktree**：`.worktrees//`（已 gitignore） +- 脚本：`./scripts/agent-worktree.sh create|list|remove` + +| Worktree 允许 | Worktree 禁止 | +|---------------|---------------| +| 编码、`go test -short ./...` | `env-service.sh * start/stop/restart` | +| 连主仓已起服务 `:8080` | 各 worktree 各起 docker | + +### 6.3 集成槽位（合入 dev + 容器验证） + +> **编码与 worktree 单测可并行；合入 dev + 共享容器验证必须串行。** + +Agent A 占槽 merge + 冒烟期间，Agent B **不得** merge dev 或动共享 docker；B 可继续 worktree 编码，并写入 queue 等待。 + +CURRENT「集成槽位」：`holder` | `phase`（idle/merging/smoke/e2e）| `since` | `scope` | `queue` + +**释放**：冒烟 PASS（或 FAIL+handoff）+ 文档同步 + holder=idle。长 E2E 优先 smoke 释放，E2E 结果后补报告。 + +**默认冒烟（holder 在主仓执行）**： + +```bash +go vet ./... +go test -short ./... +./scripts/env-service.sh dev restart +curl -sf http://127.0.0.1:8080/health +``` + +### 6.4 共享文档 + +`CURRENT.md` / `FEATURE-MATRIX.md` 由认领方或合并者更新；冲突时保留双方认领行再收敛。 + +### 6.5 协作纪律 + +- **单一焦点**：CURRENT 只列 1–3 个焦点 +- **不覆盖**：发现冲突先 handoff/blocker - **交接优先**：口头转述不可代替 handoff 文件 --- -## 7. Git 与提交 +## 7. 文档生命周期 + +```text +audit（问题）→ remediation（方案）→ ops/short-term（任务） + → test-reports（验收）→ archive/（关闭证据） +``` + +会话结束：[session-close-checklist.md](./.doc/ops/templates/session-close-checklist.md) + +--- + +## 8. Git 与提交 - 遵循 **Conventional Commits**：`feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `ci` -- **原子提交**：一个逻辑变更一批；便于 review 与回滚 -- **用户未要求**：不擅自 push、不 force push 保护分支 -- **用户已要求 push/同步远端**：必须自主完成，不得把「请你去点推送」推回用户 +- **原子提交**：一个逻辑变更一批 +- merge 回 dev 用 `--no-ff` +- **用户未要求**：不擅自 push +- **用户已要求 push/同步远端**：必须自主完成 - **禁止**：在 `git config` 写入 token；硬重置/强推/删库仅在用户明确授权时 --- -## 8. Secrets 与远端推送（自主，禁止索要） +## 9. Secrets 与远端推送（自主，禁止索要） ### 查找顺序 -1. `${HOME}/.secrets/` 下与远端相关的文件（如 `gitea`、`github`） -2. 本仓 **PROJECT.md** 与 **push 脚本**（如 `scripts/git-push-dev.sh`）中的字段说明 - -### 常见字段（格式因宿主而异） - -```text -- ACCESS_TOKEN= -- URL_PREFIX= -``` - -### 执行方式 - -- 优先调用本仓封装脚本（若存在） -- 或自行读取 secrets 文件构造 push URL（**不写入 git config**） +1. `${HOME}/.secrets/`（如 `gitea`） +2. **PROJECT.md** 与 **push 脚本**（`scripts/git-push-dev.sh`） ### 禁止 -- 向用户索要 token 或要求粘贴凭证 -- 在聊天、文档、commit message 中展示 secret +- 向用户索要 token +- 在聊天/文档/commit 中展示 secret - 把 token 写入仓库或 `.env` 并提交 ### 缺失时 -- 在 ops 任务/handoff 记录 **blocker**：文件路径 + 缺字段名 -- 提示用户在本机补齐该文件后重试 -- **仍不索要 secret 内容** +在 ops/handoff 记 blocker（路径 + 缺字段）；**仍不索要 secret 内容**。 --- -## 9. 安全与合规红线 +## 10. 安全与合规红线 - 不提交 `.env`、密钥、凭证、生产数据倾倒 -- 不做未授权访问或攻击性利用（本地修复与加固除外） -- 破坏性命令（`git reset --hard`、`push --force`、DROP DATABASE）仅在用户明确授权时 +- 破坏性命令仅在用户明确授权时 - XSS/注入等修复优先于功能扩展 --- -## 10. 计划 / 实现 / 验证 +## 11. 计划 / 实现 / 验证 -1. **大改动**：先对齐计划或 short-term 范围；范围外记 long-term -2. **实现**：按 PROJECT 测试命令验证；失败信息写入任务/报告 -3. **完成定义**：写进 checklist；勾选须有证据链接（非口头「已完成」） +1. **大改动**：先 short-term 范围；范围外记 long-term +2. **实现**：按 PROJECT 测试命令验证 +3. **完成定义**：checklist 勾选须有证据链接 --- -## 11. 沟通 +## 12. 沟通 -- 对用户：**简洁、中文**（若 PROJECT 未另规定） -- 不复述长篇规则；指向文件路径 +- 对用户：**简洁、中文** +- 指向文件路径，不复述长篇规则 - 需要决策时 **一次只问 1–2 个关键问题** -- 长输出先给结论，再展开细节 --- -## 12. 模板索引 +## 13. 工具入口（薄转发） -新建任何 ops 条目前，先复制对应模板： +| 工具 | 入口 | +|------|------| +| Cursor | `.cursor/rules/*` + 本文件 | +| Claude Code | [CLAUDE.md](./CLAUDE.md) | +| Codex | [CODEX.md](./CODEX.md) | +| Gemini | [GEMINI.md](./GEMINI.md) | +| Antigravity | [ANTIGRAVITY.md](./ANTIGRAVITY.md) | +| Kimi | [KIMI.md](./KIMI.md) | -| 类型 | 模板路径 | -|------|----------| +均转发至本文件启动链。 + +--- + +## 14. 模板索引 + +| 类型 | 路径 | +|------|------| | 短期任务 | `.doc/ops/templates/short-term-task.md` | | 长期任务 | `.doc/ops/templates/long-term-task.md` | | Checklist | `.doc/ops/templates/checklist.md` | | 交接 | `.doc/ops/templates/handoff.md` | | 调研 | `.doc/ops/templates/research-note.md` | +| 审计笔记 | `.doc/ops/templates/audit-note.md` | +| 整改方案 | `.doc/ops/templates/remediation-plan.md` | +| 完成度行 | `.doc/ops/templates/feature-matrix-row.md` | +| 会话结束 | `.doc/ops/templates/session-close-checklist.md` | --- diff --git a/ANTIGRAVITY.md b/ANTIGRAVITY.md new file mode 100644 index 00000000..7a14766d --- /dev/null +++ b/ANTIGRAVITY.md @@ -0,0 +1,9 @@ +# Antigravity 入口 + +请先完整阅读并遵守 [AGENTS.md](./AGENTS.md)（通用 Agent 工作手册）。 + +再阅读 [PROJECT.md](./PROJECT.md)（本仓库地图与约定）。 + +然后阅读 [.doc/README.md](./.doc/README.md) 与 [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) 获取文档 taxonomy 与当前焦点。 + +勿向用户索要 Git token；按 AGENTS.md 自行从本机 `${HOME}/.secrets/` 路径读取。 diff --git a/CLAUDE.md b/CLAUDE.md index eb386745..d0ee9512 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,6 +4,6 @@ 再阅读 [PROJECT.md](./PROJECT.md)（本仓库地图与约定）。 -然后阅读 [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) 获取当前任务焦点。 +然后阅读 [.doc/README.md](./.doc/README.md) 与 [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) 获取文档 taxonomy 与当前焦点。 勿向用户索要 Git token；按 AGENTS.md 自行从本机 `${HOME}/.secrets/` 路径读取。 diff --git a/CODEX.md b/CODEX.md new file mode 100644 index 00000000..2a6fa50f --- /dev/null +++ b/CODEX.md @@ -0,0 +1,9 @@ +# Codex 入口 + +请先完整阅读并遵守 [AGENTS.md](./AGENTS.md)（通用 Agent 工作手册）。 + +再阅读 [PROJECT.md](./PROJECT.md)（本仓库地图与约定）。 + +然后阅读 [.doc/README.md](./.doc/README.md) 与 [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) 获取文档 taxonomy 与当前焦点。 + +勿向用户索要 Git token；按 AGENTS.md 自行从本机 `${HOME}/.secrets/` 路径读取。 diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..0f71fd32 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,9 @@ +# Gemini 入口 + +请先完整阅读并遵守 [AGENTS.md](./AGENTS.md)（通用 Agent 工作手册）。 + +再阅读 [PROJECT.md](./PROJECT.md)（本仓库地图与约定）。 + +然后阅读 [.doc/README.md](./.doc/README.md) 与 [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) 获取文档 taxonomy 与当前焦点。 + +勿向用户索要 Git token；按 AGENTS.md 自行从本机 `${HOME}/.secrets/` 路径读取。 diff --git a/KIMI.md b/KIMI.md new file mode 100644 index 00000000..a478bcff --- /dev/null +++ b/KIMI.md @@ -0,0 +1,9 @@ +# Kimi Code 入口 + +请先完整阅读并遵守 [AGENTS.md](./AGENTS.md)（通用 Agent 工作手册）。 + +再阅读 [PROJECT.md](./PROJECT.md)（本仓库地图与约定）。 + +然后阅读 [.doc/README.md](./.doc/README.md) 与 [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) 获取文档 taxonomy 与当前焦点。 + +勿向用户索要 Git token；按 AGENTS.md 自行从本机 `${HOME}/.secrets/` 路径读取。 diff --git a/PROJECT.md b/PROJECT.md index a9391728..88b4e005 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -58,10 +58,13 @@ | 用途 | 路径 | |------|------| +| 文档总地图 | [.doc/README.md](./.doc/README.md) | | 协作会话 / 当前焦点 | [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) | -| 发布/审计缺口状态 | [.doc/2026-09-12-remediation-gap-matrix.md](./.doc/2026-09-12-remediation-gap-matrix.md) | +| 模块完成度 | [.doc/status/FEATURE-MATRIX.md](./.doc/status/FEATURE-MATRIX.md) | +| 发布/审计缺口 | [.doc/remediation/gap-matrix.md](./.doc/remediation/gap-matrix.md) | +| 问题分析 | [.doc/audit/INDEX.md](./.doc/audit/INDEX.md) | +| 整改方案 | [.doc/remediation/INDEX.md](./.doc/remediation/INDEX.md) | | 测试报告归档 | [.doc/test-reports/](./.doc/test-reports/) | -| 历史审计索引 | [.doc/2026-09-12-AUDIT-INDEX.md](./.doc/2026-09-12-AUDIT-INDEX.md) | | 测试报告规范 | [.cursor/rules/test-reports-standard.mdc](./.cursor/rules/test-reports-standard.mdc) | --- @@ -108,7 +111,7 @@ cd web && npm test && npm run build ## 8. 测试与验收铁律 -- 开发可用 stub；**交付前验收**必须真实 PI Agent + MiniMax-M3 全链路 +- 开发可用 stub；**交付前验收**必须真实 PI Agent + MiniMax-M2.7-highspeed 全链路 - 报告必须归档至 `.doc/test-reports/`，遵循 test-reports-standard - 禁止 stub 输出冒充最终验收数据 @@ -118,7 +121,8 @@ cd web && npm test && npm run build 见 **[.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md)**。 -- 发布缺口 SSOT：[gap-matrix](./.doc/2026-09-12-remediation-gap-matrix.md) +- 发布缺口 SSOT：[gap-matrix](./.doc/remediation/gap-matrix.md) +- 模块完成度：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md) - 最新测试报告：[2026-09-13-codex-audit-p0-remediation-test-report.md](./.doc/test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md) - **剩余 blocker**: CI 真实 PI E2E + 前端人工抽检（main 本地冒烟已通过） diff --git a/README.md b/README.md index b3965c3d..332380fd 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ 本项目是一个面向企业与团队的高可用对话智能体（Chat Agent）系统，结合了知识库检索增强（RAG）、自动化 Agent 执行能力与安全审计机制。 +> **Agent / 协作者必读**：[AGENTS.md](./AGENTS.md) → [PROJECT.md](./PROJECT.md) → [.doc/README.md](./.doc/README.md) → [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) + --- ## 一、 仓库三分支结构说明 @@ -14,7 +16,7 @@ | **`test`** | **测试分支** | **准生产实测分支**。当 `dev` 积累了一定功能阶段后合并至此，建立发布候选节点（`rc-vX.Y.Z`），进行真实环境部署与长期集成测试与运维检验。 | | **`main`** | **主分支** | **生产发布分支**。严禁直接提交。仅在 `test` 分支经过真实运维和测试验证达到发布标准后，将对应节点合并回 `main` 并打正式版本 Tag（`vX.Y.Z`）。 | -完整的分支流转模型、热修复流程与提交规范请参阅：[docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md](docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md)。 +完整的分支流转模型、热修复流程与提交规范请参阅：[PROJECT.md](./PROJECT.md) §4（SSOT）。 --- diff --git a/scripts/agent-worktree.sh b/scripts/agent-worktree.sh new file mode 100755 index 00000000..3e6195a2 --- /dev/null +++ b/scripts/agent-worktree.sh @@ -0,0 +1,76 @@ +#!/usr/bin/env bash +# Agent worktree helper — parallel coding only; do NOT start docker from worktrees. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +WORKTREES="${ROOT}/.worktrees" + +usage() { + cat < # git worktree add .worktrees/ -b + $0 list # git worktree list + $0 remove # remove worktree and optionally delete branch + +示例: + $0 create feature/my-task + $0 list + $0 remove feature/my-task +EOF + exit 1 +} + +ensure_ignored() { + if git -C "${ROOT}" check-ignore -q .worktrees/. 2>/dev/null; then + : + else + echo "[错误] .worktrees/ 未在 .gitignore 中，请先添加。" >&2 + exit 1 + fi + mkdir -p "${WORKTREES}" +} + +slug_from_branch() { + echo "$1" | tr '/' '-' +} + +cmd="${1:-}" +case "${cmd}" in + create) + [[ $# -eq 2 ]] || usage + branch="$2" + ensure_ignored + slug="$(slug_from_branch "${branch}")" + path="${WORKTREES}/${slug}" + if [[ -d "${path}" ]]; then + echo "[错误] 已存在: ${path}" >&2 + exit 1 + fi + git -C "${ROOT}" worktree add "${path}" -b "${branch}" + echo "Worktree: ${path} (branch ${branch})" + echo "禁止在此目录运行 env-service.sh start/stop/restart" + ;; + list) + git -C "${ROOT}" worktree list + ;; + remove) + [[ $# -ge 2 && $# -le 3 ]] || usage + branch="$2" + delete_branch="${3:-}" + slug="$(slug_from_branch "${branch}")" + path="${WORKTREES}/${slug}" + if [[ ! -d "${path}" ]]; then + echo "[错误] 不存在: ${path}" >&2 + exit 1 + fi + git -C "${ROOT}" worktree remove "${path}" --force + if [[ "${delete_branch}" == "--delete-branch" ]]; then + git -C "${ROOT}" branch -D "${branch}" 2>/dev/null || true + fi + echo "已移除 worktree ${path}" + ;; + *) + usage + ;; +esac