wangsli
729d90576f
更新Trellis适配、任务归属与归档失败恢复，精简技能入口和知识读取规则。 保留权限、证据、事务及独立复核合同；纳入对应任务及已完成复核记录。 仅本地提交，不启用新平台适配，不推送或部署。
219 行
14 KiB
Markdown
219 行
14 KiB
Markdown
# Agent 开发与交付实践
|
||
|
||
本文是 hyb-oa 使用 AI agent 协作开发的项目级事实源。目标不是追求复杂编排，而是把高频、易出错、需要验证的流程固定下来，让后续交付可复现、可审计、可回滚。
|
||
|
||
## 来源
|
||
|
||
- OpenAI How OpenAI uses Codex: https://openai.com/business/guides-and-resources/how-openai-uses-codex/
|
||
- OpenAI Codex AGENTS.md: https://developers.openai.com/codex/guides/agents-md
|
||
- OpenAI Codex Skills: https://developers.openai.com/codex/skills/
|
||
- OpenAI GPT-6 Astra skills/prompt 精简指南：https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra
|
||
- OpenAI Codex Automations: https://openai.com/academy/codex-automations/
|
||
- OpenAI Agents 文档: https://platform.openai.com/docs/guides/agents
|
||
- OpenAI Evals 文档: https://platform.openai.com/docs/guides/evals
|
||
- Trellis: https://github.com/mindfold-ai/trellis
|
||
- Anthropic Building Effective Agents: https://www.anthropic.com/engineering/building-effective-agents
|
||
- Google Agent Development Kit 文档: https://google.github.io/adk-docs/
|
||
|
||
## 本项目采用的原则
|
||
|
||
### 上下文使用（2026-09-19）
|
||
|
||
当前采用 GPT-6 时，仍以项目合同决定权限和完成标准；模型能力提升不代替业务验收或独立复核。按官方指南采用渐进读取：技能描述只说明准确触发范围，正文作为短入口，详细步骤和经验按需查阅。
|
||
|
||
- 当前任务不明时先用 `task.py current --source`，需要更广会话状态才运行完整 `get_context.py`。续办先读当前要求、最新状态与未完项；不默认加载全部历史任务或原始会话。
|
||
- 大 spec 先查目录/标题，再读通用规则、相关完整场景和必要引用；跨层时扩展。已加载且未变化的内容不重复读取。入口见 `.trellis/spec/hyb-oa/index.md`。
|
||
- 稳定经验更新原归属章节；当次测试数量、时间、候选资格及失败记录留在任务/证据。避免每次复盘追加一份同义模板，不为精简删除历史原件。
|
||
- 已批准范围连续实施到约定验证完成；变更范围、风险或验收才重新确认。按变更选择测试，未变输入可复用已有结果；生产操作和提交/归档继续单独授权。
|
||
- 技能目录总字节不等于默认注入量，文本缩短不等于已测 token 节省。新会话加载、模型实际选技和端到端表现需分别验证；不据静态检查宣称已生效。
|
||
|
||
### 0. TRELLIS2 后以官方 Trellis task 为执行合同
|
||
|
||
TRELLIS2 起，hyb-oa 的后续非微小开发默认从 `.trellis/tasks/` 进入，由 task 目录本身承载需求、计划、实施、检查和复盘。
|
||
|
||
Trellis 的定位是“开发执行合同和上下文组织层”，不是业务事实源替代品：
|
||
|
||
- Trellis task：承载本轮需求 PRD、范围边界、验收、测试计划、上下文和复盘。
|
||
- Trellis spec：沉淀稳定开发规则和高频工程边界。
|
||
- Issue CSV：历史审计材料或特殊外部交付导出格式，不作为新任务前置合同。
|
||
- `docs/`：仍是业务事实源、产品体验事实、操作手册和证据入口。
|
||
- `AGENTS.md`：只保留 Trellis-first 入口和不可违反硬约束。
|
||
|
||
每个非微小 Trellis task 必须有 `prd.md`；复杂流程、API、迁移、权限、部署或治理变更补 `design.md` 或 `implement.md`；`.trellis/workspace/` 默认作为本地个人日志，不提交。提交前必须运行 `node scripts/qa/check-trellis-governance.mjs`。
|
||
|
||
### 1. 先简单、后编排
|
||
|
||
默认由主 agent 在当前上下文内完成计划、实现、验证和提交。只有当任务能明确拆分、文件写入范围互不冲突、并且并行能实质缩短关键路径时，才使用子 agent。
|
||
|
||
不为了“多 agent”而多 agent。复杂编排的收益必须超过上下文丢失、沟通成本和合并风险。
|
||
|
||
### 2. Trellis task 是执行合同
|
||
|
||
所有非微小改动先进入 `.trellis/tasks/<task>/`，再实施。task 必须写清：
|
||
|
||
- 业务流程级影响，不只写文件路径。
|
||
- 验收标准，不只写“完成开发”。
|
||
- 可执行验证命令或可复现手工步骤。
|
||
- 数据迁移、权限、状态机、审批规则的回滚策略。
|
||
|
||
历史 `issues/*.csv` 不删除、不批量回写；需要表格化审计时，可以从 Trellis task 摘要导出，而不是重新维护一套并行合同。
|
||
|
||
### 3. Trellis spec 固化操作流程
|
||
|
||
TRELLIS2 后，项目不再维护独立的交付 Skill。每轮固定流程、验证顺序和高频边界应按稳定程度分别落到 `.trellis/workflow.md`、`.trellis/spec/hyb-oa/`、当前 Trellis task 或 `docs/`：
|
||
|
||
- 每轮交付固定流程：优先进入 `.trellis/workflow.md` 或 `.trellis/spec/hyb-oa/project-governance.md`。
|
||
- 试运行和验证顺序：优先进入 `docs/试运行与自动化验证手册.md` 或对应 Trellis task。
|
||
- Playwright 视觉巡检要求：优先进入相关 QA 脚本和当前 Trellis task；视觉裁决使用 `frontend-design`。
|
||
- 报销、发票、企业微信等高频业务入口：优先进入对应业务规约和 `.trellis/spec/hyb-oa/` 领域 spec。
|
||
|
||
详细业务规则放在 `docs/`，稳定开发规则沉淀到 `.trellis/spec/`，当前任务上下文由 `.trellis/tasks/<task>/prd.md`、`implement.jsonl` 和 `check.jsonl` 串联。
|
||
|
||
### 4. 文档保存事实源
|
||
|
||
项目事实源应随仓库版本管理，DCL7 之后采用中文优先和物理精简：
|
||
|
||
- 文档入口：`docs/文档索引.md`
|
||
- 文档状态矩阵：`docs/文档事实源状态矩阵.md`
|
||
- 产品体验事实源：`docs/产品设计规则.md`
|
||
- 报销发票规则：`docs/报销发票附件规则.md`
|
||
- 试运行手册：`docs/试运行与自动化验证手册.md`
|
||
- Agent 交付实践：`docs/Agent开发交付实践.md`
|
||
|
||
AGENTS.md 只放 Trellis-first 入口和硬约束，不复制长规则。
|
||
|
||
### 5. 工具调用必须可验证
|
||
|
||
优先使用确定性命令和项目已有脚本：
|
||
|
||
- 后端：`npm run prisma:validate`、`node --check`、相关 Vitest、回归脚本。
|
||
- 前端：`npm run typecheck`、`npm run build`。
|
||
- 视觉：Playwright PC、mobile、WeCom UA 截图和 DOM 指标。
|
||
- 文档/流程：Trellis governance check、docs registry check、`git diff --check`。
|
||
|
||
验证失败时先定位是代码问题、测试桩问题、环境问题还是数据问题。数据库迁移漂移、生产配置、远程服务变更属于高风险操作，必须暂停确认。
|
||
|
||
### 6. 前端体验和业务同时验收
|
||
|
||
前端页面不只看功能能否跑通，也要同时看视觉、交互、信息语义和真实业务路径。治理口径固定如下：
|
||
|
||
- `frontend-design` 是视觉与交互设计裁决来源；项目文档不再重复维护颜色、字体、圆角、卡片、竞品参考层级或页面美术规则。
|
||
- `docs/产品设计规则.md` 只用于判断业务体验事实：目标用户、PC/移动/企微职责、页面分层、信息语义、OA/企微主办边界和验收边界。
|
||
- 审批、报销、采购、合同、项目、企业微信、OCR、附件等领域问题，先读对应业务规约，不在前端设计规则里重复定义。
|
||
- 可自动化的体验检查先自动化，例如 Playwright PC、移动、企业微信 UA 和 DOM 指标；真实企业微信登录、手机应用消息到达、真实通知权限和财务制度决策必须保留人工确认记录。
|
||
- 真机验证暂缓时记录为 `PAUSED`；自动化通过不能替代代表性真机确认，也不能关闭仍待人工确认的移动阻断。
|
||
- 面向用户可测试的页面改动，必须在部署和公网检查通过后再告知用户可测。
|
||
|
||
文档治理采用 DCL7 后的中文优先和物理精简策略：
|
||
|
||
- 先读 `docs/文档索引.md` 和 `docs/文档事实源状态矩阵.md` 判断文档用途。
|
||
- 当前事实源、操作手册和用户可读文档默认使用中文文件名；技术生态或脚本强引用的英文名可以保留，但必须在索引中说明。
|
||
- 已确认不用的历史文档从当前树物理删除，不放 `docs/archive/`；需要时通过 git 历史恢复。
|
||
- 不回写旧 Issue CSV 快照；旧 Issue 中的历史路径保留审计语义。
|
||
- 历史矩阵、旧 runbook 或旧 trialrun 记录若与当前 Trellis task、当前 PRD 或模块规约冲突，以当前 Trellis task 和当前模块规约为准。
|
||
- R7/OPS7/DOC7 草案不代表真实 R7 已启动；MIF7/MIF7T 已收口，后续移动体验问题应进入新的 UX8 或专项 Issue。
|
||
|
||
### 7. 提交要小批次、中文、可回滚
|
||
|
||
一次需求可以有多个 commit，但每个 commit 应该能说明一个清晰主题：
|
||
|
||
- 计划和文档。
|
||
- 后端规则和接口。
|
||
- 前端体验。
|
||
- 测试和视觉验证。
|
||
|
||
commit message 使用中文并引用 Trellis task 名称或任务 ID，例如 `trellis2-official-task-contract 采用官方 Trellis 执行合同`。
|
||
|
||
### 8. 自然语言派工是默认入口
|
||
|
||
用户不需要按固定提示词派工。可以只发一段自然语言，例如“企业微信里这个页面还是PC布局，先核查并规划后续修复”。agent 必须主动拆解：
|
||
|
||
- 意图：缺陷、需求、验收反馈、计划、审查、测试、部署、设计或产品流程优化。
|
||
- 对象：页面、接口、业务流程、数据、部署环境、文档或自动化。
|
||
- 约束：是否要求先规划、是否已授权实施、是否涉及公网、企业微信、真实账号或真实数据。
|
||
- 下一步：核查、建 Trellis task、给方案等确认、实施、验证、提交、部署。
|
||
|
||
当用户说“确认”时，默认表示批准上一条明确方案或 Trellis task 进入下一阶段。若上下文中存在多个候选方案，agent 才需要反问确认对象。
|
||
|
||
### 9. 少反问，先查已有资产
|
||
|
||
agent 在声明 blocker 前，必须先查项目内已有资产：
|
||
|
||
- `issues/*.csv`、`docs/`、`.trellis/spec/hyb-oa/`、当前 Trellis task 和 `AGENTS.md`。
|
||
- 已有测试脚本、Playwright 用例、回归脚本、试运行报告和覆盖矩阵。
|
||
- `artifacts/`、`output/`、手工复核证据、测试样本和历史日志。
|
||
- 环境变量示例、部署 runbook、可用的公网健康检查和本地启动脚本。
|
||
|
||
只有在这些线索不足以安全推进时，才把问题抛回给用户。不能因为没有第一时间看到账号、样本、脚本或历史结论，就直接要求用户重复提供。
|
||
|
||
### 10. 何时必须反问或暂停
|
||
|
||
以下情况必须暂停确认：
|
||
|
||
- 非微小代码改动还没有方案批准，或没有 Trellis task 执行合同。
|
||
- 需要删除或重置数据、处理迁移漂移、修改生产配置、重启远程服务。
|
||
- 需要使用、重置或暴露真实账号密码、密钥、令牌、客户数据。
|
||
- 用户目标互相冲突，且无法通过现有文档和代码推断优先级。
|
||
- 验收标准无法推断，且错误实现会造成明显返工或数据风险。
|
||
|
||
除此之外，agent 应优先用合理假设继续推进，并在输出中明确假设和验证结果。
|
||
|
||
### 11. Codex 的项目角色用法
|
||
|
||
同一个 agent 可以按任务临时切换工作视角，但输出必须落到可审计交付物：
|
||
|
||
- 产品经理：把一段话拆成业务流程、优先级、Trellis task、验收标准和下一步建议。
|
||
- 需求分析：补齐边界条件、角色权限、异常状态、国内同类系统常见处理方式。
|
||
- 开发：按 Issue 实施后端、前端、脚本或文档变更，并执行对应验证。
|
||
- 审查：默认先报风险、行为回归、权限泄漏、状态机问题和漏测项。
|
||
- QA：用接口回归、Playwright、视觉截图、真机/公网 smoke 和人工步骤复核。
|
||
- 设计师：使用 `frontend-design` 做视觉和交互判断，并对照 `docs/产品设计规则.md` 的业务体验事实。
|
||
- 用户代理：模拟普通员工、审批人、财务、管理员在 PC、手机、企业微信里的真实路径。
|
||
|
||
不需要用户显式写“请扮演某角色”。agent 应根据语义自动选择角色；若任务跨多个角色，先给执行顺序和交接物。
|
||
|
||
### 12. 可选短模板
|
||
|
||
模板不是强制要求，只用于减少歧义：
|
||
|
||
```text
|
||
缺陷：我看到的问题是... 期望是... 请先核查/直接修复，完成后告诉我是否已部署。
|
||
需求：我想实现... 影响页面/角色是... 先规划并等我确认/确认后直接实施。
|
||
测试：请覆盖... 流程，包含PC/手机/企业微信/公网/视觉检查。
|
||
审查：请 review 最近改动，重点看权限、状态机、数据、体验和漏测。
|
||
产品优化：请参考国内类似系统，判断当前流程是否合理，并给出可执行建议。
|
||
```
|
||
|
||
如果用户只写普通段落，agent 仍按第 8 条自动识别，不要求用户补模板。
|
||
|
||
### 13. 可自动化的工作
|
||
|
||
适合自动化或半自动化固化的任务：
|
||
|
||
- 每轮 Trellis task 合同校验、上下文检查和未完成项扫描。
|
||
- 后端 syntax、Prisma validate、核心回归脚本。
|
||
- 前端 typecheck、build、关键页面 Playwright 和视觉截图。
|
||
- 公网 `/ready`、企业微信配置、资源版本、核心文案和 live smoke。
|
||
- 业务流程巡检：报销、发票、请假、审批、票据、附件上传、异步任务终态。
|
||
- 前端体验巡检：PC 页面误入移动端、原生英文上传控件、内部码值、UUID 主展示、按钮和底部导航异常。
|
||
|
||
不适合完全自动化的任务要保留人工验收入口，例如真实企业微信登录、真实账号安全操作、生产数据处理、财务制度决策。
|
||
|
||
### 14. 完成口径
|
||
|
||
开发类任务完成时，agent 必须说明：
|
||
|
||
- 改了什么，关联哪个 Trellis task。
|
||
- 验证了什么，哪些命令或路径通过。
|
||
- 是否提交 commit，commit hash 是什么。
|
||
- 面向用户可测试的改动是否已经部署；未部署时不能说“可以去企业微信测试”。
|
||
- 哪些风险或后续工作仍未完成。
|
||
|
||
## 何时更新本文件
|
||
|
||
当连续两轮以上重复提醒同一类 agent 行为，或者同一类遗漏导致返工时，先判断：
|
||
|
||
- 是项目事实源：更新 `docs/`。
|
||
- 是每轮操作流程：更新 `.trellis/workflow.md`、`.trellis/spec/hyb-oa/` 或当前 Trellis task。
|
||
- 是不可违反硬规则：更新 `AGENTS.md`。
|