From 0d10c9adfee1dde65d5a2084c24a20cf4c62412e Mon Sep 17 00:00:00 2001 From: weichen Date: Sat, 12 Sep 2026 16:51:58 +0000 Subject: [PATCH] =?UTF-8?q?docs(ops):=20=E5=BB=BA=E7=AB=8B=E9=80=9A?= =?UTF-8?q?=E7=94=A8=20AGENTS=20=E6=89=8B=E5=86=8C=E4=B8=8E=E6=9C=AC?= =?UTF-8?q?=E4=BB=93=20PROJECT/CLAUDE=20=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- .cursor/rules/agent-collaboration-docs.mdc | 24 +++ .cursor/rules/git-secrets-autonomy.mdc | 24 +++ .doc/ops/CURRENT.md | 38 ++++ .doc/ops/README.md | 24 +++ .../2026-09-13-codex-audit-p0-remediation.md | 50 +++++ .../2026-09-12-codex-reaudit-summary.md | 30 +++ .../2026-09-13-codex-audit-p0-remediation.md | 44 ++++ .doc/ops/templates/checklist.md | 20 ++ .doc/ops/templates/handoff.md | 41 ++++ .doc/ops/templates/long-term-task.md | 20 ++ .doc/ops/templates/research-note.md | 26 +++ .doc/ops/templates/short-term-task.md | 40 ++++ AGENTS.md | 199 ++++++++++++++++++ CLAUDE.md | 9 + PROJECT.md | 129 ++++++++++++ 15 files changed, 718 insertions(+) create mode 100644 .cursor/rules/agent-collaboration-docs.mdc create mode 100644 .cursor/rules/git-secrets-autonomy.mdc create mode 100644 .doc/ops/CURRENT.md create mode 100644 .doc/ops/README.md create mode 100644 .doc/ops/checklists/2026-09-13-codex-audit-p0-remediation.md create mode 100644 .doc/ops/research/2026-09-12-codex-reaudit-summary.md create mode 100644 .doc/ops/short-term/2026-09-13-codex-audit-p0-remediation.md create mode 100644 .doc/ops/templates/checklist.md create mode 100644 .doc/ops/templates/handoff.md create mode 100644 .doc/ops/templates/long-term-task.md create mode 100644 .doc/ops/templates/research-note.md create mode 100644 .doc/ops/templates/short-term-task.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 PROJECT.md diff --git a/.cursor/rules/agent-collaboration-docs.mdc b/.cursor/rules/agent-collaboration-docs.mdc new file mode 100644 index 00000000..279d0adf --- /dev/null +++ b/.cursor/rules/agent-collaboration-docs.mdc @@ -0,0 +1,24 @@ +--- +description: 强制 Agent 文档同步与 ops 协作纪律；详情见 AGENTS.md +alwaysApply: true +--- + +# Agent 文档同步（强制） + +完整规范见 [AGENTS.md](../../AGENTS.md) 与 [PROJECT.md](../../PROJECT.md)。 + +## 开场必读 + +1. `AGENTS.md` → `PROJECT.md` → `.doc/ops/CURRENT.md` → 相关 short-term / handoff + +## 红线 + +- 任何任务/调研/审计/修复/运维：**开始前**建或更新 `.doc/ops/short-term/` 或 `long-term/`（复制 templates） +- **禁止**只改代码、真相只留在聊天 +- 里程碑更新 `CURRENT.md`；会话结束写 `handoffs/` +- 验收报告进 `.doc/test-reports/` 并回链 checklist +- 文档与代码同批或紧随 `docs(...)` 提交 + +## 状态 + +`planned | in_progress | blocked | done | cancelled` diff --git a/.cursor/rules/git-secrets-autonomy.mdc b/.cursor/rules/git-secrets-autonomy.mdc new file mode 100644 index 00000000..f2c4ed43 --- /dev/null +++ b/.cursor/rules/git-secrets-autonomy.mdc @@ -0,0 +1,24 @@ +--- +description: Git push 凭证自主读取；禁止向用户索要 token；详情见 AGENTS.md §8 +alwaysApply: true +--- + +# Git Secrets 自主（禁止索要） + +完整规范见 [AGENTS.md](../../AGENTS.md) §8 与 [PROJECT.md](../../PROJECT.md) §7。 + +## 本仓约定 + +- 凭证：`${HOME}/.secrets/gitea` +- 字段：`- ACCESS_TOKEN=`、`- URL_PREFIX=` +- 推送：优先 `./scripts/git-push-dev.sh ` + +## 禁止 + +- 向用户索要或要求粘贴 token +- 在聊天/文档/commit 中展示 secret +- 写入 git config 或提交到仓库 + +## 缺失时 + +在 `.doc/ops` 记 blocker（路径 + 缺字段），提示用户本机补齐后重试；**仍不索要内容**。 diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md new file mode 100644 index 00000000..44d5464f --- /dev/null +++ b/.doc/ops/CURRENT.md @@ -0,0 +1,38 @@ +# 当前焦点 + +**更新**: 2026-09-13 +**production_ready**: no（Codex 2026-09-12 再审计） + +## 焦点 + +Codex 审计 P0 → 门禁 → 环境 → 文档对齐（Wave 0–D） + +## 阻塞项（P0） + +1. 任务/SSE 项目鉴权不完整 +2. `users_id_seq` 冷启动冲突 +3. Go test / go vet 不通过 +4. dev lifecycle 脏数据未修复 +5. test 镜像陈旧 / main 未部署 + +## 下一步 + +1. ~~Wave 0: AGENTS/PROJECT/ops~~ → 进行中 +2. Wave A: 授权 + 00025 迁移 + lifecycle SQL +3. Wave B: Go 门禁修复 +4. Wave C: test/main 环境 +5. Wave D: gap-matrix + superseded + test-report + +## 活跃条目 + +| 类型 | 路径 | +|------|------| +| 短期任务 | [short-term/2026-09-13-codex-audit-p0-remediation.md](./short-term/2026-09-13-codex-audit-p0-remediation.md) | +| Checklist | [checklists/2026-09-13-codex-audit-p0-remediation.md](./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) | + +## SSOT + +- 发布缺口: [gap-matrix](../2026-09-12-remediation-gap-matrix.md) +- Agent 手册: [AGENTS.md](../../AGENTS.md) +- 本仓地图: [PROJECT.md](../../PROJECT.md) diff --git a/.doc/ops/README.md b/.doc/ops/README.md new file mode 100644 index 00000000..7ee08f40 --- /dev/null +++ b/.doc/ops/README.md @@ -0,0 +1,24 @@ +# 活协作区（.doc/ops） + +Agent 会话级协作文档，与 Git 跟踪的审计/设计文档分离。 + +## 用法 + +1. 会话开始读 [CURRENT.md](./CURRENT.md) +2. 新任务复制 [templates/](./templates/) 到对应目录 +3. 完成或切换 Agent 时写 [handoffs/](./handoffs/) + +## 状态 + +- **current**：进行中条目 + CURRENT.md +- **historical**：已完成条目保留，标 `done` 或移入归档 + +## 与 SSOT 关系 + +| 类型 | 位置 | +|------|------| +| 协作焦点 | 本目录 CURRENT | +| 发布/审计缺口 | [gap-matrix](../2026-09-12-remediation-gap-matrix.md) | +| 验收报告 | [test-reports](../test-reports/) | + +通用纪律见仓库根 [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 new file mode 100644 index 00000000..0fe947b6 --- /dev/null +++ b/.doc/ops/checklists/2026-09-13-codex-audit-p0-remediation.md @@ -0,0 +1,50 @@ +--- +title: "Codex 审计 P0 整改 Checklist" +status: in_progress +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 +- [x] .cursor/rules agent-collaboration + git-secrets +- [x] .doc/ops templates + CURRENT + +## Wave A — P0 + +- [ ] AUTH: `/tasks/run` + `/tasks/run/stream` 非成员 403 零副作用 +- [ ] DB: 00025 setval 冷启动无 users_pkey +- [ ] DATA: lifecycle SQL 执行证据 +- [ ] DATA: test 污染工作流退休 + +## Wave B — Go 门禁 + +- [ ] go vet ./... PASS +- [ ] go test -short ./... PASS +- [ ] AdvisorBrief 多意图回归 +- [ ] V0.5 断言 5 产物 +- [ ] Chat 语义记忆稳定 +- [ ] KB integration 显式门禁 +- [ ] health schema 实时读 + +## Wave C — 环境 + +- [ ] test 镜像/schema 对齐 +- [ ] dev 二进制对齐 HEAD +- [ ] main 冒烟或 gap 记 blocker +- [ ] .env 权限 600 / HTTP 超时（若改） + +## Wave D — 文档 + +- [ ] gap-matrix 更新 Codex 项 +- [ ] AUDIT-INDEX superseded 指向 +- [ ] quick-ref 断链修复 +- [ ] test-report 归档 + +## 完成定义 + +- [ ] 全部勾选且有证据链接 diff --git a/.doc/ops/research/2026-09-12-codex-reaudit-summary.md b/.doc/ops/research/2026-09-12-codex-reaudit-summary.md new file mode 100644 index 00000000..4dc2dc65 --- /dev/null +++ b/.doc/ops/research/2026-09-12-codex-reaudit-summary.md @@ -0,0 +1,30 @@ +--- +title: "Codex 2026-09-12 再审计摘要" +created: 2026-09-13 +status: done +confidence: high +--- + +# 调研：Codex 2026-09-12 再审计 + +## 结论 + +系统功能已达 RC 级，但**不具备生产发布条件**。主因：授权链缺口、冷启动 DB 缺陷、Go 门禁失败、环境/文档漂移。 + +## 证据 + +| 项 | 说明 | +|----|------| +| P0-1 | sse.go:287 / handlers.go:187 任务入口缺项目成员鉴权 | +| P0-2 | 00011 seed 未 setval users_id_seq → test duplicate key | +| P0-3 | main 未运行；test 旧镜像 stub | +| P0-4 | 47 completed 实例对应 active 项目 | +| 门禁 | go test/vet 失败；BizDev brief、V0.5 3vs5、chat memory、embedding 401 | + +## 开放问题 + +- gap-matrix「核心 PASS」与再审计冲突 → Wave D 对齐 + +## 建议动作 + +按 short-term 任务 Wave A–D 顺序执行。 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 new file mode 100644 index 00000000..f45271b1 --- /dev/null +++ b/.doc/ops/short-term/2026-09-13-codex-audit-p0-remediation.md @@ -0,0 +1,44 @@ +--- +title: "Codex 审计 P0 整改" +status: in_progress +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. [ ] Wave A1: handleRunTask + SSE 鉴权 + 负例测试 +3. [ ] Wave A2: goose 00025 +4. [ ] Wave A3: lifecycle SQL + test 工作流退休 +5. [ ] Wave B: AdvisorBrief / V0.5 / chat memory / kb gate / health +6. [ ] Wave C: 环境一致性 +7. [ ] 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/templates/checklist.md b/.doc/ops/templates/checklist.md new file mode 100644 index 00000000..f43a8f44 --- /dev/null +++ b/.doc/ops/templates/checklist.md @@ -0,0 +1,20 @@ +--- +title: "" +status: in_progress +created: YYYY-MM-DD +updated: YYYY-MM-DD +related_task: "" +--- + +# + +## Wave / 阶段 + +### 阶段名 + +- [ ] 项 1 — 证据： +- [ ] 项 2 — 证据： + +## 完成定义 + +- [ ] 全部勾选且有证据链接 diff --git a/.doc/ops/templates/handoff.md b/.doc/ops/templates/handoff.md new file mode 100644 index 00000000..ca475420 --- /dev/null +++ b/.doc/ops/templates/handoff.md @@ -0,0 +1,41 @@ +--- +title: "<交接标题>" +created: YYYY-MM-DD +from: agent +to: next-agent +status: open +--- + +# 交接：<标题> + +## 目标（下一位 Agent 应完成什么） + +## 已完成 + +- + +## 未完成 + +- + +## 关键文件 + +| 路径 | 说明 | +|------|------| +| | | + +## 如何验证 + +```bash +# 命令 +``` + +## 风险 / Blocker + +- + +## 相关链接 + +- CURRENT: [CURRENT.md](../CURRENT.md) +- Task: +- Checklist: diff --git a/.doc/ops/templates/long-term-task.md b/.doc/ops/templates/long-term-task.md new file mode 100644 index 00000000..bfc8a2e6 --- /dev/null +++ b/.doc/ops/templates/long-term-task.md @@ -0,0 +1,20 @@ +--- +title: "<长期任务标题>" +status: planned +created: YYYY-MM-DD +updated: YYYY-MM-DD +--- + +# <长期任务标题> + +## 动机 + +## 成功标准 + +## 依赖 + +## 暂不启动原因 + +（若 status 为 planned） + +## 相关链接 diff --git a/.doc/ops/templates/research-note.md b/.doc/ops/templates/research-note.md new file mode 100644 index 00000000..c1290d31 --- /dev/null +++ b/.doc/ops/templates/research-note.md @@ -0,0 +1,26 @@ +--- +title: "<调研标题>" +created: YYYY-MM-DD +status: done +confidence: high +--- + +# 调研：<标题> + +## 结论 + +（1–3 句） + +## 证据 + +| 项 | 路径/命令 | 结果 | +|----|-----------|------| +| | | | + +## 开放问题 + +- + +## 建议动作 + +- diff --git a/.doc/ops/templates/short-term-task.md b/.doc/ops/templates/short-term-task.md new file mode 100644 index 00000000..b24ee85a --- /dev/null +++ b/.doc/ops/templates/short-term-task.md @@ -0,0 +1,40 @@ +--- +title: "<任务标题>" +status: planned +created: YYYY-MM-DD +updated: YYYY-MM-DD +owner: agent +--- + +# <任务标题> + +## 目标 + +（一句话可验证目标） + +## 范围 + +- + +## 非目标 + +- + +## 步骤 + +1. [ ] +2. [ ] + +## 验收标准 + +- [ ] + +## 相关链接 + +- Checklist: +- Handoff: +- Test report: + +## 证据 / 备注 + +（命令输出、commit、文件路径） diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..74b14f8a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,199 @@ +# Agent 工作手册（通用） + +> 本文件与具体业务仓库无关，可整文件复用到其他项目。 +> **本仓库差异化约定见 [PROJECT.md](./PROJECT.md)。** + +--- + +## 1. 目的与适用范围 + +- 适用于在本仓库工作的所有编码 Agent（Cursor、Claude Code、Codex 等）。 +- **聊天记录易失**；Git 与活文档区才是可协作、可审计的真相来源。 +- 任何任务、调研、审计、修复、运维操作均须同步落盘，禁止「只改代码 / 只留在对话」。 + +--- + +## 2. 启动协议（Session Bootstrap） + +每次会话开始，按顺序阅读： + +1. **本文件** `AGENTS.md`（通用工作方式） +2. **[PROJECT.md](./PROJECT.md)**（本仓库地图与约定） +3. **`.doc/ops/CURRENT.md`**（当前焦点、阻塞、下一步） +4. 相关 **short-term 任务** / **handoff**（若存在） +5. 发布/审计类任务：再读 PROJECT 指向的 gap-matrix 等 SSOT + +**未读完不得开始改代码**（紧急热修除外，事后必须在 24h 内补文档）。 + +--- + +## 3. 文档同步红线（强制） + +| 时机 | 必须动作 | +|------|----------| +| 任务开始 | 在 `short-term/` 或 `long-term/` 新建或更新条目（复制 templates） | +| 里程碑 | 更新任务文 `status` 与 `CURRENT.md` | +| 调研/审计 | 写入 `research/` 或任务文「证据」段 | +| 验收 | 写 test-report（路径见 PROJECT），回链到 checklist | +| 会话结束/切换 Agent | 写或更新 `handoffs/` | +| 提交 | 文档变更与代码同批或紧随 `docs(...)` 提交 | + +**状态字段**：`planned | in_progress | blocked | done | cancelled` + +**current vs historical**：完成项标 `done` 或移入归档；不删除证据。 + +--- + +## 4. 活文档区约定 + +默认路径：`.doc/ops/`（可由 PROJECT 覆盖） + +```text +.doc/ops/ + README.md # 本区用法 + CURRENT.md # 一页纸：当前焦点（会话必读） + short-term/ # 本迭代可关闭的任务 + long-term/ # 跨迭代 backlog + checklists/ # 可勾选验收清单 + handoffs/ # 会话交接 + research/ # 调研笔记实例 + templates/ # 新建条目时复制 +``` + +**命名**：`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` 中用相对链接引用 + +--- + +## 6. 多 Agent 协作 + +- **单一焦点**：`CURRENT.md` 只列 1–3 个当前焦点 +- **并行任务**：在 CURRENT 列出 owner/agent 标识与互斥资源（分支、文件、环境） +- **不覆盖**：不覆盖他人未合并工作区；发现冲突先写 handoff/blocker +- **交接优先**：口头转述不可代替 handoff 文件 + +--- + +## 7. Git 与提交 + +- 遵循 **Conventional Commits**：`feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `ci` +- **原子提交**：一个逻辑变更一批；便于 review 与回滚 +- **用户未要求**：不擅自 push、不 force push 保护分支 +- **用户已要求 push/同步远端**：必须自主完成，不得把「请你去点推送」推回用户 +- **禁止**：在 `git config` 写入 token；硬重置/强推/删库仅在用户明确授权时 + +--- + +## 8. 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**） + +### 禁止 + +- 向用户索要 token 或要求粘贴凭证 +- 在聊天、文档、commit message 中展示 secret +- 把 token 写入仓库或 `.env` 并提交 + +### 缺失时 + +- 在 ops 任务/handoff 记录 **blocker**：文件路径 + 缺字段名 +- 提示用户在本机补齐该文件后重试 +- **仍不索要 secret 内容** + +--- + +## 9. 安全与合规红线 + +- 不提交 `.env`、密钥、凭证、生产数据倾倒 +- 不做未授权访问或攻击性利用（本地修复与加固除外） +- 破坏性命令（`git reset --hard`、`push --force`、DROP DATABASE）仅在用户明确授权时 +- XSS/注入等修复优先于功能扩展 + +--- + +## 10. 计划 / 实现 / 验证 + +1. **大改动**：先对齐计划或 short-term 范围；范围外记 long-term +2. **实现**：按 PROJECT 测试命令验证；失败信息写入任务/报告 +3. **完成定义**：写进 checklist；勾选须有证据链接（非口头「已完成」） + +--- + +## 11. 沟通 + +- 对用户：**简洁、中文**（若 PROJECT 未另规定） +- 不复述长篇规则；指向文件路径 +- 需要决策时 **一次只问 1–2 个关键问题** +- 长输出先给结论，再展开细节 + +--- + +## 12. 模板索引 + +新建任何 ops 条目前，先复制对应模板： + +| 类型 | 模板路径 | +|------|----------| +| 短期任务 | `.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` | + +--- + +**本仓库差异化约定见 [PROJECT.md](./PROJECT.md)。** diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..eb386745 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,9 @@ +# Claude Code 入口 + +请先完整阅读并遵守 [AGENTS.md](./AGENTS.md)（通用 Agent 工作手册）。 + +再阅读 [PROJECT.md](./PROJECT.md)（本仓库地图与约定）。 + +然后阅读 [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) 获取当前任务焦点。 + +勿向用户索要 Git token；按 AGENTS.md 自行从本机 `${HOME}/.secrets/` 路径读取。 diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 00000000..166be5a0 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,129 @@ +# Agent-System 项目地图 + +> 通用 Agent 工作方式见 [AGENTS.md](./AGENTS.md)。 +> Claude Code 入口见 [CLAUDE.md](./CLAUDE.md)。 + +--- + +## 1. 产品一句话 + +面向企业与团队的多用户工作流与对话智能体平台：RAG 知识库、PI Agent 执行、项目治理、阶段门禁、文档审批、任务持久化与 SSE 流式交互。 + +--- + +## 2. 主要目录 + +| 路径 | 说明 | +|------|------| +| `cmd/` | 服务入口 | +| `internal/` | Go 业务逻辑（server、coordinator、bizdev、chat、projectinstance 等） | +| `web/` | React + Vite 前端 | +| `deploy/postgres/goose/` | PostgreSQL 迁移（Goose） | +| `configs/` | Agent 与提示词配置 | +| `templates/` | 工作流文档模板 | +| `.doc/` | 架构、审计、整改文档 | +| `.doc/ops/` | **活协作区**（CURRENT、任务、checklist、handoff） | +| `.doc/test-reports/` | 测试/验收报告（归档） | +| `data/dev|test|main/` | 各环境对话与工作区（隔离） | +| `scripts/` | 运维与推送脚本 | + +--- + +## 3. 技术栈 + +- **后端**：Go HTTP API（~110 路由） +- **前端**：React + Vite +- **数据库**：PostgreSQL + pgvector（Goose 迁移） +- **智能体**：PI Agent Runner（真实 / stub） +- **工作流**：main、product_manager、test_manager 三套正式定义 + +--- + +## 4. Git 三分支与三环境 + +详见 [.cursor/rules/git-workflow-and-environments.mdc](./.cursor/rules/git-workflow-and-environments.mdc)。 + +| 环境 | 分支 | Compose | HTTP | DB 端口 | 数据路径 | +|------|------|---------|------|---------|----------| +| 开发 | dev | agent-dev | 8080 | 5433 | data/dev | +| 测试 | test | agent-test | 8081 | 5434 | data/test | +| 生产 | main | agent-main | 8000 | 5435 | data/main | +| 共享 KB | 跨环境 | agent-infra | - | 5432 | data/shared/kb | + +**红线**：知识库共享；对话与业务 DB **严格隔离**，禁止跨环境读写。 + +--- + +## 5. 文档地图（SSOT） + +| 用途 | 路径 | +|------|------| +| 协作会话 / 当前焦点 | [.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/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) | + +--- + +## 6. 常用命令 + +```bash +# 环境 +./scripts/env-service.sh shared start +./scripts/env-service.sh dev start +./scripts/env-service.sh all status + +# Go 质量门禁（默认） +go vet ./... +go test -short ./... + +# PG 集成（需 TEST_DATABASE_URL） +TEST_DATABASE_URL=postgres://... go test ./internal/server/... -run 'TestE2E_WorkflowGovernance' + +# 真实 PI E2E（显式开关） +RUN_PI_E2E=1 RUNNER_AUTH_TOKEN=... go test ./... -run 'PI' + +# 前端 +cd web && npm test && npm run build + +# 数据库迁移 +# 见 deploy/postgres/goose/ +``` + +--- + +## 7. Git 推送（自主，勿索要 token） + +- **脚本**：[`scripts/git-push-dev.sh`](./scripts/git-push-dev.sh) +- **凭证文件**：`${HOME}/.secrets/gitea` +- **字段**： + ```text + - ACCESS_TOKEN= + - URL_PREFIX= + ``` +- **用法**：`./scripts/git-push-dev.sh dev`（或 test/main 分支名） + +--- + +## 8. 测试与验收铁律 + +- 开发可用 stub；**交付前验收**必须真实 PI Agent + MiniMax-M3 全链路 +- 报告必须归档至 `.doc/test-reports/`，遵循 test-reports-standard +- 禁止 stub 输出冒充最终验收数据 + +--- + +## 9. 当前焦点（动态） + +见 **[.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md)** 与： + +- 短期任务：`.doc/ops/short-term/2026-09-13-codex-audit-p0-remediation.md` +- Checklist：`.doc/ops/checklists/2026-09-13-codex-audit-p0-remediation.md` + +--- + +## 10. 语言与提交 + +- 对用户：**简体中文** +- 提交：Conventional Commits；在 `dev` 上渐进式分批提交