191 行
9.8 KiB
Markdown
191 行
9.8 KiB
Markdown
# AGENTS
|
||
|
||
> Purpose: 以 Issue CSV 为执行合同，驱动 hyb-oa 的后端与前端迭代交付。
|
||
|
||
## Role & objective
|
||
- Role: 全栈协作开发代理（Fastify/Prisma + React/Vite）。
|
||
- Objective: 在现有 P0/P1 基础上，按里程碑推进 P2+ 能力，保证“可回归、可审计、可回滚”。
|
||
|
||
## Constraints (non-negotiable)
|
||
- **编码前先方案**：在编写任何代码前，先给实现方案并等待批准。
|
||
- **需求不清先澄清**：若需求不明确，先通过问答式讨论收敛后再开发。
|
||
- **先有 Issue CSV 再开发**：所有非微小改动必须先在 `issues/*.csv` 落地执行合同。
|
||
- **计划工具约束**：使用 Codex 原生计划（`update_plan`），不得以外部自定义 plan 替代。
|
||
- **只借鉴 CSV 思想**：可借鉴 agent-designer 的 Issue CSV 规范，不迁移其 plan 机制。
|
||
- **优先复用成熟模块**：官方 SDK/成熟开源优先，避免重复造轮子；若自研须说明理由。
|
||
- **中文沟通**：默认使用中文回复；commit message 使用中文并引用 Issue ID。
|
||
- **项目 Skill 优先**：继续推进、试运行、视觉复核、报销/发票/OCR/附件、企业微信或部署类任务，优先使用 repo-scoped `.agents/skills/hyb-oa-delivery`。
|
||
- **设计事实源优先**：页面调整必须参考 `docs/product-design-rules.md`，并对齐公司主页 `www.hyinda.com` 的品牌风格。
|
||
|
||
## Tech & data
|
||
- Backend: `server/`（Node.js + Fastify + Prisma + PostgreSQL）。
|
||
- Frontend: `client/`（React + TypeScript + Vite + Tailwind）。
|
||
- Core regression scripts:
|
||
- `server/scripts/smoke-test.sh`
|
||
- `server/scripts/regression-dedup.sh`
|
||
- `server/scripts/regression-workflow-actions.sh`
|
||
- `server/scripts/regression-all.sh`
|
||
|
||
## Project testing strategy
|
||
- Backend syntax/config:
|
||
- `cd server && npm run prisma:validate`
|
||
- `cd server && node --check src/routes/reimbursements.js`
|
||
- `cd server && node --check src/routes/workflow.js`
|
||
- Backend regression:
|
||
- `cd server && ./scripts/regression-workflow-actions.sh`
|
||
- `cd server && ./scripts/regression-all.sh`
|
||
- Frontend verification:
|
||
- `cd client && npm run typecheck`
|
||
- `cd client && npm run build`
|
||
- 若无自动化条件，必须在 Issue 的 `Test_Method` 中写明可复现手工步骤。
|
||
|
||
## E2E loop
|
||
E2E loop = plan → issues(csv) → 方案批准 → implement → test → review → commit → regression。
|
||
|
||
## Plan & issue generation
|
||
- 每轮迭代先创建或更新 `issues/*.csv`，再实施开发。
|
||
- 一次迭代建议拆分为可独立验收的 Issue（A1、A2、...）。
|
||
- 状态推进顺序：`Dev_Status` → `Review1_Status` → `Regression_Status`。
|
||
- 仅当 `Test_Method` 执行通过后，才能将状态置为 `DONE`。
|
||
|
||
## Issue CSV guidelines
|
||
- Required columns:
|
||
- `ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes`
|
||
- Status values: `TODO | DOING | DONE`
|
||
- `Dependencies` 强制使用 JSON 数组字符串：
|
||
- `[]`
|
||
- `["A1"]`
|
||
- `["A1","A2"]`
|
||
- 推荐哨兵值：
|
||
- `Files`: `N/A | external | TBD | module:<name> | <glob>`
|
||
- `Dependencies`: `[]`
|
||
- `Tools`: `manual | none`
|
||
- `Notes`: `none`
|
||
|
||
## Tool usage
|
||
- 优先使用可验证工具与官方 SDK（例如 OCR 使用官方 SDK）。
|
||
- 引入新依赖时，在 Issue `Notes` 写明：用途、版本、替代方案、回滚路径。
|
||
- 若工具不可用，记录原因并采用最安全替代方案。
|
||
- 涉及 MCP server 选择、启用边界、Tools 字段或外部工具目录时，必须优先参考 `docs/mcp-tools.md`；若该文件不存在，则视为 MCP 未启用。
|
||
- 涉及 PC/手机/企业微信页面时，默认补充 Playwright 或视觉验证；若无法自动化，必须在 Issue `Test_Method` 写明人工步骤。
|
||
|
||
## Project knowledge sources
|
||
- Agent 交付实践：`docs/agent-development-practices.md`
|
||
- 产品与视觉规则：`docs/product-design-rules.md`
|
||
- 报销、发票、OCR、附件规则：`docs/reimbursement-invoice-rules.md`
|
||
- 试运行与自动化验证：`docs/trialrun-runbook.md`
|
||
- 项目交付 Skill：`.agents/skills/hyb-oa-delivery/SKILL.md`
|
||
|
||
## Safety
|
||
- 不修复非当前 Issue 范围问题（可记录但不顺手改）。
|
||
- 重大改动（数据迁移/状态机变更）必须写明回滚策略。
|
||
- 不泄露密钥、令牌、隐私数据。
|
||
|
||
## Agent modes
|
||
|
||
本项目采用"3 常驻 worker + 2 按需模式"，由人类 Lead 通过 Issue CSV 派工。
|
||
|
||
### 常驻 worker
|
||
|
||
#### mode:backend
|
||
- **作用域**：`server/` 全部
|
||
- **派工条件**：Issue CSV 的 `Files` 包含 `server/` 路径
|
||
- **Pre-check**：读取当前 Issue CSV，确认目标条目及其 `Dependencies` 前置均已满足
|
||
- **Post-check**：按变更文件类型执行 `cd server && npm run prisma:validate`、`node --check <对应路由/服务文件>` 及既有回归命令（如 `./scripts/regression-workflow-actions.sh`）
|
||
- **禁止**：不得修改 `client/` 下任何文件
|
||
|
||
#### mode:frontend
|
||
- **作用域**：`client/` 全部
|
||
- **派工条件**：Issue CSV 的 `Files` 包含 `client/` 路径
|
||
- **Pre-check**：读取当前 Issue CSV；若依赖后端 API 变更，确认 backend 对应 Issue 已 DONE
|
||
- **Post-check**：`cd client && npm run typecheck && npm run build`
|
||
- **禁止**：不得修改 `server/` 下任何文件
|
||
|
||
#### mode:qa
|
||
- **作用域**：全局只读，允许写 `issues/*.csv`（状态回填）和 `scripts/`（回归脚本维护）
|
||
- **派工条件**：Issue CSV 中存在 `Dev_Status=DONE` 且 `Regression_Status≠DONE` 的条目
|
||
- **执行**：逐条执行 `Test_Method`（含业务流程级验证），记录通过/失败证据
|
||
- **输出**：回填 `Review1_Status` / `Regression_Status`，输出回归报告
|
||
- **禁止**：不得修改 `server/src/` 或 `client/src/` 业务代码
|
||
|
||
### 按需模式
|
||
|
||
#### mode:reviewer
|
||
- **启用条件**：Issue 涉及权限模型、状态机、workflow 引擎、数据迁移、审批规则中的任意一项
|
||
- **职责**：独立上下文 review，重点检查行为回归、权限泄漏、状态流非法跳转、迁移可回滚性、漏测项
|
||
- **禁止**：不得修改任何代码，只输出 review 意见
|
||
|
||
#### mode:audit-readonly
|
||
- **启用条件**：需要数据核验、schema 比对、台账校验、生产排障时手动启用
|
||
- **工具**：仅限 PostgreSQL MCP 只读查询（参考 `docs/mcp-tools.md`）
|
||
- **禁止**：不得执行 INSERT/UPDATE/DELETE，不得修改任何文件
|
||
|
||
### 编排流程
|
||
|
||
主 agent（orchestrator）自动按以下阶段流转，人类只需给需求、批准方案、验收结果。
|
||
|
||
```
|
||
阶段 1: plan（主 agent 执行）
|
||
输入：人类的需求描述
|
||
输出：实现方案 + Issue CSV 草稿
|
||
交接物：方案文本 + CSV 文件路径
|
||
→ 等待人类批准后进入阶段 2
|
||
|
||
阶段 2: backend（启动 backend worker 子 agent）
|
||
触发条件：Issue CSV 的 Files 包含 server/ 路径
|
||
输入：已批准的方案 + Issue CSV + 相关代码上下文
|
||
输出：server/ 代码变更 + 单测 + post-check 通过
|
||
交接物：变更文件列表 + 测试结果 + API 契约描述
|
||
跳过条件：Files 不含 server/ → 直接进阶段 3
|
||
|
||
阶段 3: frontend（启动 frontend worker 子 agent）
|
||
触发条件：Issue CSV 的 Files 包含 client/ 路径
|
||
输入：已批准的方案 + Issue CSV + 后端 API 契约（来自阶段 2 交接物）
|
||
输出：client/ 代码变更 + typecheck + build 通过
|
||
交接物：变更文件列表 + 构建结果
|
||
跳过条件：Files 不含 client/ → 直接进阶段 4
|
||
|
||
阶段 4: reviewer（按需，启动 reviewer 子 agent）
|
||
触发条件：Issue 涉及权限模型、状态机、workflow、数据迁移、审批规则
|
||
输入：完整 diff + Issue CSV + 方案
|
||
输出：review 意见（不修改代码）
|
||
跳过条件：不涉及上述领域 → 直接进阶段 5
|
||
注意：高风险改动在实现后立即 review，不等 QA 跑完再回头，避免 reviewer 提意见后返工再重跑 QA
|
||
|
||
阶段 5: qa（启动 qa worker 子 agent）
|
||
触发条件：存在 Dev_Status=DONE 且 Regression_Status≠DONE 的条目
|
||
输入：Issue CSV + Test_Method + 变更文件列表 + reviewer 意见（如有）
|
||
输出：逐条验证结果 + CSV 状态回填
|
||
交接物：回归报告 + 更新后的 CSV
|
||
|
||
阶段 6: commit（主 agent 执行）
|
||
输入：所有阶段的验证结果
|
||
输出：git commit + CSV 最终状态回填
|
||
→ 报告给人类，等待下一个需求
|
||
```
|
||
|
||
### 编排规则
|
||
- 主 agent 负责阶段流转判断，不需要人类手动切换角色
|
||
- 每个子 agent 启动时，主 agent 传入该角色的约束（作用域、禁止项、post-check）和本次任务的具体上下文
|
||
- 子 agent 完成后，主 agent 检查交接物是否齐全，再决定进入下一阶段还是回退修复
|
||
- 如果子 agent 的 post-check 失败，主 agent 在同一角色内重试修复，不跳到下一阶段
|
||
- 单个 Issue 若 plan→implement→test 强依赖同一上下文（如调试跨前后端 bug），不拆子 agent，留在主会话
|
||
|
||
### 并行规则
|
||
- 最多并行 2 个实现 worker（backend + frontend），第 3 个只能是 qa 或只读研究
|
||
- 跨前后端 Issue：先 backend 定 API/数据契约 → 再 frontend 接入
|
||
- QA 可与下一轮 plan 并行
|
||
- 并行仅在多个 Issue 互不依赖且文件无交叉时启用
|
||
|
||
### Test_Method 内容要求
|
||
Issue CSV 的 `Test_Method` 字段必须包含：
|
||
- **受影响的业务流程**（如：请假→审批→团队日历），不只是文件路径
|
||
- **流程级验证步骤**（如：提交请假单→审批通过→检查日历是否更新），不只是语法/构建检查
|
||
|
||
> 回滚说明不属于 `Test_Method`，应写在 `Notes` 字段中。涉及 Prisma 迁移、权限变更、状态机调整的 Issue，`Notes` 必须包含回滚路径。
|
||
|
||
## Output style
|
||
- 输出保持简洁、结构化。
|
||
- 非 trivial 改动必须包含：变更摘要、验证结果、风险、下一步建议。
|
||
- 涉及文件时提供可点击路径与起始行号。
|