hyb-oa/AGENTS.md

AGENTS

Purpose: 以 Trellis 为主流程，保留 Issue CSV 审计合同和 hyb-oa 业务事实源。

Trellis-first 入口

• 开始任何非微小开发、审查、测试或文档治理任务前，先读 .trellis/workflow.md。
• Trellis task 是后续需求拆解、上下文组织、执行复盘的主入口；每个 task 必须绑定 issues/*.csv 中的 Issue ID。
• issues/*.csv 仍是可审计执行合同；Trellis 不替代 Issue CSV 状态、验收、回滚和 commit 追踪。
• docs/ 仍是业务事实源；Trellis spec 只沉淀开发流程和高频工程规则。

不可违反约束

• 编码前先方案：非微小改动必须先给实现方案并等待批准。
• 先有 Issue CSV 再开发：非微小改动必须先落 issues/*.csv。
• 计划工具约束：使用 Codex 原生 update_plan 做执行清单，不用外部自定义 plan 替代。
• 项目 Skill 优先：hyb-oa 交付、试运行、视觉复核、报销/OCR/附件、企业微信或部署类任务继续使用 .agents/skills/hyb-oa-delivery，再按 Trellis task/spec 组织上下文。
• 中文沟通；commit message 使用中文并引用 Issue ID。
• 不泄露密码、token、Secret、真实票据、合同正文、银行资料、完整账号、完整本地路径或原始 payload。
• 不轻易新建文档；优先更新现有事实源、模块规约、操作手册、证据文档或连续 Issue CSV。
• 页面调整必须参考 docs/产品设计规则.md，并对齐公司主页 www.hyinda.com 的品牌风格。
• 面向用户可测试的改动，只有部署与公网检查通过后才能告知用户可以测试。

当前项目事实源

• 文档入口与状态：docs/文档索引.md、docs/文档事实源状态矩阵.md
• Agent/Trellis 交付实践：docs/Agent开发交付实践.md
• 产品与视觉规则：docs/产品设计规则.md
• 报销、发票、OCR、附件规则：docs/报销发票附件规则.md
• 试运行与自动化验证：docs/试运行与自动化验证手册.md
• 项目交付 Skill：.agents/skills/hyb-oa-delivery/SKILL.md
• Trellis workflow：.trellis/workflow.md
• Trellis project specs：.trellis/spec/hyb-oa/

技术栈与验证

• Backend: server/（Node.js + Fastify + Prisma + PostgreSQL）。
• Frontend: client/（React + TypeScript + Vite + Tailwind）。
• 核心后端验证：cd server && npm run prisma:validate，必要时运行相关 node --check、Vitest 和回归脚本。
• 核心前端验证：cd client && npm run typecheck && npm run build。
• 文档/流程验证：validate_issues_csv.py、node scripts/qa/check-process-contract.mjs --baseline --json、node scripts/qa/audit-docs.mjs --check-registry、node scripts/qa/check-trellis-governance.mjs、git diff --check。

Trellis 使用边界

• .trellis/workspace/ 为本地个人日志，默认不提交；需要沉淀的经验应脱敏后写入 .trellis/spec/、docs/ 或 Issue CSV。
• .trellis/config.yaml 固定 session_auto_commit: false；Trellis 不得自动提交。
• 当前仅启用 Codex 适配；不把 Cursor/Claude/其他平台迁移作为本轮默认范围。
• Codex hooks 文件可以存在，但只有用户级配置和 /hooks 审核启用后才生效；本项目不把 hook 自动注入作为验收前提。

编排规则

• 默认按 Trellis workflow 执行：task/prd -> Issue CSV -> implement -> check -> spec/docs update -> commit -> finish。
• 涉及权限模型、状态机、workflow、数据迁移、审批规则时，实施后必须启动只读 review，不让 reviewer 改代码。
• 公网部署、生产配置、真实数据写入、数据库重置、企业微信写入和真实付款必须另行获得明确批准。
• 若 Trellis 规则与业务文档冲突：最新 Issue CSV > 当前模块规约/PRD > docs/产品设计规则.md 和业务规约 > Trellis spec > 历史证据。