weichen/Agent-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ops): 建立通用 AGENTS 手册与本仓 PROJECT/CLAUDE 入口

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
weichen
2026-09-13 02:50:23 +00:00
co-authored by Cursor
parent 185c42fc94
commit 0d10c9adfe
15 changed files with 718 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/rules/agent-collaboration-docs.mdc
+24
View File
@@ -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`
.cursor/rules/git-secrets-autonomy.mdc
+24
View File
@@ -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 <branch>`
## 禁止
- 向用户索要或要求粘贴 token
- 在聊天/文档/commit 中展示 secret
- 写入 git config 或提交到仓库
## 缺失时
在 `.doc/ops` 记 blocker（路径 + 缺字段），提示用户本机补齐后重试；**仍不索要内容**。
.doc/ops/CURRENT.md
+38
View File
@@ -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)
.doc/ops/README.md
+24
View File
@@ -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)。
.doc/ops/checklists/2026-09-13-codex-audit-p0-remediation.md
+50
View File
@@ -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 归档
## 完成定义
- [ ] 全部勾选且有证据链接
.doc/ops/research/2026-09-12-codex-reaudit-summary.md
+30
View File
@@ -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 顺序执行。
.doc/ops/short-term/2026-09-13-codex-audit-p0-remediation.md
+44
View File
@@ -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)
.doc/ops/templates/checklist.md
+20
View File
@@ -0,0 +1,20 @@
---
title: "<Checklist 标题>"
status: in_progress
created: YYYY-MM-DD
updated: YYYY-MM-DD
related_task: ""
---
# <Checklist 标题>
## Wave / 阶段
### 阶段名
- [ ] 项 1 — 证据：
- [ ] 项 2 — 证据：
## 完成定义
- [ ] 全部勾选且有证据链接
.doc/ops/templates/handoff.md
+41
View File
@@ -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:
.doc/ops/templates/long-term-task.md
+20
View File
@@ -0,0 +1,20 @@
---
title: "<长期任务标题>"
status: planned
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
# <长期任务标题>
## 动机
## 成功标准
## 依赖
## 暂不启动原因
（若 status 为 planned）
## 相关链接
.doc/ops/templates/research-note.md
+26
View File
@@ -0,0 +1,26 @@
---
title: "<调研标题>"
created: YYYY-MM-DD
status: done
confidence: high
---
# 调研：<标题>
## 结论
（1–3 句）
## 证据
| 项 | 路径/命令 | 结果 |
|----|-----------|------|
| | | |
## 开放问题
-
## 建议动作
-
.doc/ops/templates/short-term-task.md
+40
View File
@@ -0,0 +1,40 @@
---
title: "<任务标题>"
status: planned
created: YYYY-MM-DD
updated: YYYY-MM-DD
owner: agent
---
# <任务标题>
## 目标
（一句话可验证目标）
## 范围
-
## 非目标
-
## 步骤
1. [ ]
2. [ ]
## 验收标准
- [ ]
## 相关链接
- Checklist:
- Handoff:
- Test report:
## 证据 / 备注
（命令输出、commit、文件路径）
AGENTS.md
+199
View File
@@ -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-<slug>.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=<token>
- URL_PREFIX=<host-without-scheme>
```
### 执行方式
- 优先调用本仓封装脚本（若存在）
- 或自行读取 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)。**
CLAUDE.md
+9
View File
@@ -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/` 路径读取。
PROJECT.md
+129
View File
@@ -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=<token>
- URL_PREFIX=<host>
```
- **用法**：`./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` 上渐进式分批提交