hyb-oa/docs/Agent开发交付实践.md

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 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/

本项目采用的原则

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 视觉巡检要求：优先进入 docs/产品设计规则.md 和相关 QA 脚本。
• 报销、发票、企业微信等高频业务入口：优先进入对应业务规约和 .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. 视觉和业务同时验收

本项目是面向 10 人以下国内科技公司的轻 OA，不只看功能能否跑通，也要看：

• PC 和手机能力是否一致。
• 企业微信入口是否保持登录态和移动布局。
• 页面是否符合 www.hyinda.com 的品牌气质。
• 文案是否符合国内 OA 习惯。
• 是否出现 PC 表格误入手机、黑色大块导航、按钮样式不一致、文字截断、弹窗自动弹键盘等明显问题。

DG8 之后，页面视觉和布局治理只有一个主 UI 参考：飞书工作台/飞书审批。外部最佳实践只沉淀原则，不复制竞品交互或文案；参考钉钉、泛微、每刻、合思、企业微信、Ant Design、WeUI 等公开资料时，必须先按 docs/产品设计规则.md 的主参考层级抽象为本项目自己的事实源：

• PC 端：以飞书式工作台和审批列表的信息层级为主，保留表格、筛选、详情分区、批量处理和管理配置。
• 移动端：以飞书式轻任务和审批/进度入口为主，结合企业微信消息驱动、卡片列表、一级底部导航、深层 Push 页和吸底主操作。
• 审批：待办聚合、明确状态、可追溯、可催办、超时提醒和效率统计。AP6 v1 已提供催办、待办摘要和超时提醒 job；后续审批/通知/催办开发必须先核对统一审批中心规约，复用既有接口、审计和通知语义，不另造平行链路。
• 企业微信：入口、身份、个人应用消息和 deeplink，不替代 OA 正式审批。

DG9 之后，页面任务必须先按 docs/产品设计规则.md 的 A/B/C 页面分层选样板，再开始设计或编码：

• A 类核心流程先对齐审批中心、移动审批/进度、报销详情、首页和通知样板。
• B 类业务运营按 A 类样板迁移，但不得顺手新增移动采购创建、恢复冻结差旅主线或改变财务/OCR/项目接口。
• C 类管理配置保持中后台高密度布局；只在授权管理或审计场景展示必要内部编号。
• PC 页面优先复用 WorkspaceHeader、指标条、FilterBar、主表格和分页；移动页面优先复用移动槽位、mobile-list-card、mobile-field-row 和吸底操作。

可自动化的体验检查先自动化，例如 Playwright PC、移动、企业微信 UA 和 DOM 指标；真实企业微信登录、手机应用消息到达、真实通知权限和财务制度决策必须保留人工确认记录。

移动页治理必须收敛到同一套事实源和组件体系：

• 改移动页面前先读 docs/产品设计规则.md，确认是否属于底部一级 Tab、首页图标宫格、卡片列表、深层 Push 页、顶部返回、吸底主操作或安全区问题。
• 新移动页默认纳入统一响应式 token 和跨视口视觉矩阵，覆盖 320、360、375、390、393、414、430px；不得只按某一台手机打补丁。
• 专用 /mobile 路由默认使用统一移动槽位、mobile-card、移动列表卡片和吸底操作；不得把桌面 card-std p-4 作为手机主容器，也不得为单个页面自造另一套间距、卡片或图标布局。
• 角色差异采用“同框架、按角色裁剪内容和动作”：员工、审批人、财务、管理员、负责人看到不同入口和动作，但不创建互不一致的角色专属移动 UI。
• 信息展示必须先去重再上屏：首页只保留一处待办/进度摘要，通知只作为事件流并直达业务详情，底部角标只表达数量；同一卡片或同一行只展示一次业务编号和一次状态标签。
• 审批入口默认承载“待我审批”和“我发起的进度”两种视角；普通员工不能看到不可点或无权限的审批入口，审批人/财务/负责人只能看到服务端允许的动作。
• 真机验证暂停时记录为 PAUSED；自动化通过不能替代代表性真机确认，也不能关闭仍待人工确认的移动阻断。当前 ME6-3 已由三台代表设备反馈关闭，后续新增真机问题必须另建 Issue 跟踪。

截至 R7EP/OPS8 收口，RI6 报销票据体验、LP6 请假采购体验、ME6 自动化/部署收口、QG6 QA 治理、MIF7/MIF7T 移动整改与真机反馈、带凭据 live smoke/OCR 复检、R7/OPS7/DOC7 草案材料、R7EP 自动门禁和 OPS8 远端只读状态检查均已完成；ME6-3 已关闭。后续可进入 R7E 人工确认环节，但不得把文档草案或自动门禁通过当成真实 R7 已启动，也不得把未来新增真机问题用自动化伪造成关闭。R7 真实执行必须保持 R7E-* 为 TODO，直到用户确认最终人员、角色、窗口、回滚联系人、问题登记负责人、每日收口节奏和暂停/回滚决策人。

文档治理采用 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 和人工步骤复核。
• 设计师：对齐 docs/产品设计规则.md、公司官网视觉和国内 OA 操作习惯。
• 用户代理：模拟普通员工、审批人、财务、管理员在 PC、手机、企业微信里的真实路径。

不需要用户显式写“请扮演某角色”。agent 应根据语义自动选择角色；若任务跨多个角色，先给执行顺序和交接物。

12. 可选短模板

模板不是强制要求，只用于减少歧义：

缺陷：我看到的问题是... 期望是... 请先核查/直接修复，完成后告诉我是否已部署。
需求：我想实现... 影响页面/角色是... 先规划并等我确认/确认后直接实施。
测试：请覆盖... 流程，包含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。