G1-G5 固化Codex自然语言协作规则

2026-05-09 10:03:17 +08:00
@@ -1,6 +1,6 @@
 ---
 name: hyb-oa-delivery
-description: "Use for hyb-oa project delivery tasks: planning with Issue CSV, implementing Fastify/Prisma or React/Vite changes, refining PC/mobile/WeCom UI, reimbursement/invoice/OCR/attachment work, trial-run troubleshooting, automated/visual verification, and Chinese batch commits."
+description: "Use for hyb-oa project delivery tasks: natural-language triage, planning with Issue CSV, implementing Fastify/Prisma or React/Vite changes, refining PC/mobile/WeCom UI, reimbursement/invoice/OCR/attachment work, trial-run troubleshooting, automated/visual verification, and Chinese batch commits."
 ---

 # hyb-oa Delivery
@@ -17,6 +17,18 @@ Read only what is relevant:
 - For local/WeCom/public trial-run, OCR runtime, Caddy, or DB drift work, read `docs/trialrun-runbook.md` and `references/trialrun.md`.
 - For how this skill should evolve, read `docs/agent-development-practices.md`.

+## Natural-Language Triage
+
+Users may assign work with a plain paragraph. Before asking follow-up questions, classify the request into defect, feature, acceptance feedback, plan, review, QA, deployment, design, or product-flow optimization.
+
+Default behavior:
+
+1. Extract intent, target surface, constraints, approval state, and next action.
+2. Check existing assets before declaring a blocker: `issues/`, `docs/`, `artifacts/`, `output/`, scripts, Playwright tests, runbooks, and prior trial-run evidence.
+3. Ask only when required by `AGENTS.md` or safety: missing approval for non-trivial coding, destructive data work, production config, secrets/accounts, conflicting goals, or unclear high-risk acceptance.
+4. Treat a plain "确认" as approval for the immediately preceding explicit plan or Issue CSV, unless multiple candidates exist.
+5. If the user asks whether a problem is real, verify first with automation, code inspection, public checks, or visual evidence before proposing broad changes.
+
 ## Delivery Loop

 1. Check `git status --short`; do not revert unrelated user changes.
@@ -1,4 +1,4 @@
 interface:
  display_name: "hyb-oa交付"
-  short_description: "按hyb-oa执行合同、设计基线和试运行规则推进交付"
-  default_prompt: "继续推进hyb-oa需求，先读取Issue CSV和项目事实源，尽量用自动化与视觉验证。"
+  short_description: "按hyb-oa自然语言派工、Issue合同和试运行规则推进交付"
+  default_prompt: "继续推进hyb-oa需求，先自动拆解自然语言输入，读取Issue CSV和项目事实源，尽量用自动化与视觉验证。"
@@ -4,7 +4,10 @@

 ## 来源

+- 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
 - Anthropic Building Effective Agents: https://www.anthropic.com/engineering/building-effective-agents
@@ -81,6 +84,91 @@ AGENTS.md 只放硬约束和入口，不复制长规则。

 commit message 使用中文并引用 Issue ID，例如 `R121/A1-A3 沉淀交付事实源`。

+### 8. 自然语言派工是默认入口
+
+用户不需要按固定提示词派工。可以只发一段自然语言，例如“企业微信里这个页面还是PC布局，先核查并规划后续修复”。agent 必须主动拆解：
+
+- 意图：缺陷、需求、验收反馈、计划、审查、测试、部署、设计或产品流程优化。
+- 对象：页面、接口、业务流程、数据、部署环境、文档或自动化。
+- 约束：是否要求先规划、是否已授权实施、是否涉及公网、企业微信、真实账号或真实数据。
+- 下一步：核查、建 Issue CSV、给方案等确认、实施、验证、提交、部署。
+
+当用户说“确认”时，默认表示批准上一条明确方案或 Issue CSV 进入下一阶段。若上下文中存在多个候选方案，agent 才需要反问确认对象。
+
+### 9. 少反问，先查已有资产
+
+agent 在声明 blocker 前，必须先查项目内已有资产：
+
+- `issues/*.csv`、`docs/`、`.agents/skills/hyb-oa-delivery/` 和 `AGENTS.md`。
+- 已有测试脚本、Playwright 用例、回归脚本、试运行报告和覆盖矩阵。
+- `artifacts/`、`output/`、手工复核证据、测试样本和历史日志。
+- 环境变量示例、部署 runbook、可用的公网健康检查和本地启动脚本。
+
+只有在这些线索不足以安全推进时，才把问题抛回给用户。不能因为没有第一时间看到账号、样本、脚本或历史结论，就直接要求用户重复提供。
+
+### 10. 何时必须反问或暂停
+
+以下情况必须暂停确认：
+
+- 非微小代码改动还没有方案批准，或没有 Issue CSV 执行合同。
+- 需要删除或重置数据、处理迁移漂移、修改生产配置、重启远程服务。
+- 需要使用、重置或暴露真实账号密码、密钥、令牌、客户数据。
+- 用户目标互相冲突，且无法通过现有文档和代码推断优先级。
+- 验收标准无法推断，且错误实现会造成明显返工或数据风险。
+
+除此之外，agent 应优先用合理假设继续推进，并在输出中明确假设和验证结果。
+
+### 11. Codex 的项目角色用法
+
+同一个 agent 可以按任务临时切换工作视角，但输出必须落到可审计交付物：
+
+- 产品经理：把一段话拆成业务流程、优先级、Issue CSV、验收标准和下一步建议。
+- 需求分析：补齐边界条件、角色权限、异常状态、国内同类系统常见处理方式。
+- 开发：按 Issue 实施后端、前端、脚本或文档变更，并执行对应验证。
+- 审查：默认先报风险、行为回归、权限泄漏、状态机问题和漏测项。
+- QA：用接口回归、Playwright、视觉截图、真机/公网 smoke 和人工步骤复核。
+- 设计师：对齐 `docs/product-design-rules.md`、公司官网视觉和国内 OA 操作习惯。
+- 用户代理：模拟普通员工、审批人、财务、管理员在 PC、手机、企业微信里的真实路径。
+
+不需要用户显式写“请扮演某角色”。agent 应根据语义自动选择角色；若任务跨多个角色，先给执行顺序和交接物。
+
+### 12. 可选短模板
+
+模板不是强制要求，只用于减少歧义：
+
+```text
+缺陷：我看到的问题是... 期望是... 请先核查/直接修复，完成后告诉我是否已部署。
+需求：我想实现... 影响页面/角色是... 先规划并等我确认/确认后直接实施。
+测试：请覆盖... 流程，包含PC/手机/企业微信/公网/视觉检查。
+审查：请 review 最近改动，重点看权限、状态机、数据、体验和漏测。
+产品优化：请参考国内类似系统，判断当前流程是否合理，并给出可执行建议。
+```
+
+如果用户只写普通段落，agent 仍按第 8 条自动识别，不要求用户补模板。
+
+### 13. 可自动化的工作
+
+适合自动化或半自动化固化的任务：
+
+- 每轮 Issue CSV 校验、状态回填检查和未完成项扫描。
+- 后端 syntax、Prisma validate、核心回归脚本。
+- 前端 typecheck、build、关键页面 Playwright 和视觉截图。
+- 公网 `/ready`、企业微信配置、资源版本、核心文案和 live smoke。
+- 业务流程巡检：报销、发票、请假、审批、票据、附件上传、异步任务终态。
+- 设计规则巡检：PC 页面误入移动端、原生英文上传控件、内部码值、UUID 主展示、按钮和底部导航异常。
+
+不适合完全自动化的任务要保留人工验收入口，例如真实企业微信登录、真实账号安全操作、生产数据处理、财务制度决策。
+
+### 14. 完成口径
+
+开发类任务完成时，agent 必须说明：
+
+- 改了什么，关联哪些 Issue ID。
+- 验证了什么，哪些命令或路径通过。
+- 是否提交 commit，commit hash 是什么。
+- 面向用户可测试的改动是否已经部署；未部署时不能说“可以去企业微信测试”。
+- 哪些风险或后续工作仍未完成。
+
 ## 何时更新本文件

 当连续两轮以上重复提醒同一类 agent 行为，或者同一类遗漏导致返工时，先判断：
@@ -0,0 +1,9 @@
+ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
+F1,OCR定向任务与调度提速,"上传或重新识别后立即投递单张OCR任务，周期tick只作为兜底；修正pg-boss OCR singleton导致的慢触发风险。","1) 上传后无需等待长周期tick即可处理；2) 定向任务可按invoiceId处理；3) 周期扫描仍保留兜底；4) 不把OCR同步塞进上传HTTP请求。","业务流程：票据中心上传真实/模拟发票->后台OCR立即处理->票据状态变化；步骤：后端单测覆盖入队、定向处理、周期兜底；本地mock OCR上传后状态在预期时间内变化。","node|prisma|pg-boss",TODO,TODO,TODO,"server/src/routes/invoicePool.js|server/src/jobs/pgBossJobs.js|server/src/jobs/ocrJob.js|server/tests","[]","不改腾讯密钥；如定向任务异常，可回退周期tick。"
+F2,OCR完成事件与前端自动刷新,"OCR完成后发布票据更新事件，前端事件优先刷新票据详情、列表、PC报销详情和移动报销详情；SSE失败时回退自适应轮询。","1) 票据中心无需手动刷新；2) PC/移动报销详情无需手动刷新；3) 企业微信WebView下SSE失败不阻断；4) 事件只触发refetch，不直接渲染敏感payload。","业务流程：上传发票->OCR完成->页面自动变化；步骤：Playwright模拟SSE成功、SSE断开、轮询兜底。","react|playwright|sse",TODO,TODO,TODO,"server/src|client/src/hooks|client/src/pages|client/tests/e2e","[""F1""]","先用SSE，WebSocket暂不引入；保留轮询兜底。"
+F3,OCR状态文案与重复票据体验,"把重复票据从识别失败中拆出，展示已识别字段和下一步动作。","1) 重复票显示“已识别但重复”，不再泛化为OCR失败；2) 展示发票号码、销售方、金额、日期；3) 普通用户不见原始码值；4) 财务仍可走判重例外。","业务流程：重复发票上传->识别字段展示->重复原因明确；步骤：真实PDF重复样本和mock重复样本Playwright断言。","react|playwright",TODO,TODO,TODO,"client/src/pages|client/src/lib/invoiceOcr.ts|client/tests/e2e","[""F1"",""F2""]","不放宽判重规则，只修正用户解释和下一步动作。"
+F4,PC报销详情慢OCR自动添加,"PC报销详情取消60秒后要求用户刷新，改为持续自动刷新并在available后自动添加。","1) 65秒慢OCR完成后PC报销详情自动绑定发票；2) 移动端体验保持一致；3) 超长等待展示“系统仍在自动刷新”；4) 用户可继续操作其他区域。","业务流程：PC报销草稿->上传发票->慢OCR->自动添加；步骤：mock OCR延迟65秒Playwright。","playwright|react",TODO,TODO,TODO,"client/src/pages/ReimbursementDetailPage.tsx|client/src/pages/MobileReimbursementDetailPage.tsx|client/tests/e2e","[""F2""]","解决“识别中没变化、没有反馈”的核心体验。"
+F5,公网真实OCR与pending卡住扫描,"把真实PDF OCR smoke和pending OCR卡住扫描变成发布后固定证据。","1) 公网真实OCR输出耗时、终态、字段、重复原因；2) 可列出超过2/5/10分钟pending票据；3) 报告不泄露票据图片和密钥。","业务流程：发布后OCR健康检查；步骤：node scripts/qa/check-pending-ocr.mjs；PLAYWRIGHT_OCR_LIVE_FILE=<pdf> E2E_BASE_URL=https://oa.hyinda.com npx playwright test live-invoice-ocr.spec.ts。","node|playwright|curl",TODO,TODO,TODO,"scripts/qa|client/tests/e2e/manual|docs/trialrun-runbook.md","[""F1"",""F2"",""F3""]","真实企业微信登录由人工已验，不作为本项阻塞。"
+F6,项目级异步UX审计,"扫描并审计类似OCR的异步流程：验真、支付批次、ERP同步、导入、审批、离线队列、附件上传。","形成异步UX问题清单：是否有进度、是否自动更新、是否有终态、失败原因、重试入口、用户下一步；高风险项进入后续Issue。","业务流程：全项目异步体验审计；步骤：读取路由、页面、任务脚本和E2E；输出docs/trialrun/async-ux-audit.csv。","manual|node|playwright",TODO,TODO,TODO,"docs/trialrun/async-ux-audit.csv|client/src|server/src/jobs|scripts/qa","[]","只审计和规划，不顺手改业务代码。"
+F7,异步体验规则固化,"把OCR和项目级异步体验规则固化到产品规则、报销票据规则、试运行runbook和项目skill。","1) 文档明确异步任务体验契约；2) OCR/验真/支付/ERP/导入统一规则；3) hyb-oa-delivery skill加入检查项；4) 后续交付必须引用这些规则。","业务流程：交付规范治理；步骤：更新docs/reimbursement-invoice-rules.md、docs/product-design-rules.md、docs/trialrun-runbook.md、docs/agent-development-practices.md、.agents/skills/hyb-oa-delivery/SKILL.md并验证skill。","docs|manual",TODO,TODO,TODO,"docs/reimbursement-invoice-rules.md|docs/product-design-rules.md|docs/trialrun-runbook.md|docs/agent-development-practices.md|.agents/skills/hyb-oa-delivery/SKILL.md","[""F6""]","规则包括：事件优先、轮询兜底、终态反馈、失败原因、下一步动作、码值隐藏、部署后真实证据。"
+F8,回归部署与公网复核,"完成F1-F7后执行完整回归、提交、部署和公网复核。","project-wide gate通过；部署成功；/ready正常；公网OCR smoke有结果；Issue状态回填DONE；明确可去企业微信/公网测试。","业务流程：交付闭环；步骤：prisma validate、client typecheck/build、project-wide release gate、deploy/trialrun/deploy.sh、/ready、wecom config、public bundle scan、live OCR。","bash|npm|curl|playwright|git",TODO,TODO,TODO,"issues|client|server|scripts|docs|deploy","[""F1"",""F2"",""F3"",""F4"",""F5"",""F6"",""F7""]","面向用户可测改动必须部署后再通知测试。"
@@ -0,0 +1,6 @@
+ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
+G1,自然语言派工规则合同,"把本轮对话暴露的协作问题转成Issue CSV：用户可用普通段落派工，agent负责自动识别意图、拆任务、少反问、先查已有资产。","Issue CSV存在且字段完整；范围限定为协作文档和项目skill；不实施OCR业务代码。","业务流程：用户自然语言派工->agent生成执行合同->按合同更新文档；步骤：运行CSV validator。","python|manual",DONE,DONE,DONE,"issues/2026-05-09_09-55-45-codex-collaboration-rules.csv","[]","当前已存在OCR计划CSV但本轮不执行业务改动。"
+G2,Codex协作实践补充,"结合OpenAI官方Codex资料和本项目复盘，更新agent开发实践文档，明确自然语言输入、确认边界、Issue拆解、已有资产优先、部署可测口径。","docs/agent-development-practices.md包含可执行的自然语言协作规则；能区分何时自动推进、何时必须反问；说明用户无需固定提示词。","业务流程：普通需求段落->agent识别类型->形成计划或执行；步骤：人工审阅文档段落并运行git diff --check。","docs|web|manual",DONE,DONE,DONE,"docs/agent-development-practices.md","[""G1""]","资料源限定为OpenAI官方页面和本项目对话复盘。"
+G3,项目交付skill更新,"更新hyb-oa-delivery skill，把自然语言派工、自动查找已有样本/账号/脚本、视觉/公网验证、完成后部署口径沉淀为每轮交付检查项。","SKILL.md包含简明检查项；不复制长文档；skill quick_validate通过。","业务流程：后续hyb-oa交付->skill触发->按新检查项执行；步骤：运行skill quick_validate。","skill-creator|python",DONE,DONE,DONE,".agents/skills/hyb-oa-delivery/SKILL.md|.agents/skills/hyb-oa-delivery/agents/openai.yaml","[""G2""]","保持skill精简，详细解释放docs。"
+G4,协作模板与角色用法固化,"补充面向用户和agent的协作模板：缺陷、需求、测试、审查、设计、PM规划、部署验收；明确无需强制模板但模板可减少歧义。","文档包含短模板和自动识别映射；覆盖开发、审查、测试、需求、项目经理、设计师、用户代理等用法。","业务流程：用户随手描述问题或选择模板->agent按类型处理；步骤：人工审阅并运行git diff --check。","docs|manual",DONE,DONE,DONE,"docs/agent-development-practices.md","[""G2""]","模板是可选辅助，不要求用户严格填写。"
+G5,验证提交,"验证本轮CSV、文档和skill更新，并以中文commit提交。","CSV validator、skill quick_validate、git diff --check均通过；Issue状态回填DONE；生成中文commit且引用G1-G5。","业务流程：协作规则变更->验证->提交；步骤：python validate_issues_csv.py issues/2026-05-09_09-55-45-codex-collaboration-rules.csv；python quick_validate.py .agents/skills/hyb-oa-delivery；git diff --check；git commit。","python|git",DONE,DONE,DONE,"issues|docs|.agents/skills/hyb-oa-delivery/SKILL.md","[""G1"",""G2"",""G3"",""G4""]","文档类变更无需部署；最终说明未触发公网发布。"