Add AGENTS.md

AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md · QVerisFlow
+
+> 本文件是所有 coding agent（含 Codex）在本仓库工作的**常驻操作契约**，每次任务全程生效。
+> 你的成功标准是：每一次改动都让系统更可信，且不弄坏任何既有能力——不是改得多。
+
+## 0. 项目一句话
+QVerisFlow 是一个 LangGraph/AutoGen 风格的 **agent-workflow 平台**（Python），当前约 55–65% 成熟度。
+强项：agent 执行 + 工具调用 + workflow 可视化/自然语言构建。
+弱项：确定性编排、默认审计链路、执行恢复、闭环反馈落地。
+
+## 1. 七条铁律（违反任意一条 = 立即停下）
+1. 现状未摸清、计划未获批准前，**禁止改业务代码**。
+2. 一次只做一个已批准子任务，**禁止顺手改无关代码**；越界发现写进 `DEFERRED.md`。
+3. **禁止大爆炸重写**；用 strangler-fig 渐进替换，旧路径在新路径验证通过前不删、不破坏。
+4. **复用优先**：新增函数/类/模块/依赖前先全仓搜索；每个新抽象要在 PR 里回答"为何不能复用现有"。
+5. **红–绿交付**：先写失败测试（或对遗留补特征测试）再让其通过；验证不过 = 没完成。
+6. 禁止降低可观测性/审计、禁止吞异常（no silent `except`）、禁止在 async loop 里做阻塞调用。
+7. 语义不确定（尤其编排：condition gating / 并行 / 循环 / HITL / 恢复）→ **停下来问，不要猜着改**。
+
+## 2. 五阶段门（不可跳过）
+Phase 0 现状基线 →[门A 人工确认]→ Phase 1 计划DAG →[门B 人工批准]→ Phase 2 按批次执行 ⇄ Phase 3 验证 →[门C 批次全绿]→ Phase 4 汇报 → 下一批
+- 门 A / B 是人工门：无确认不得推进。
+- 门 C 是机器门：批次内全绿 + 回归 invariant 无损 + 集成冒烟通过，才算交付。
+
+## 3. 单子任务协议（每次改动都走这 8 步）
+1 复述目标+invariant → 2 补特征测试锁旧行为 → 3 写失败的新测试 → 4 最小改动转绿（复用优先）
+→ 5 跑验证门 → 6 staff 视角自审 diff → 7 碰执行路径就同步审计埋点 → 8 一个聚焦 PR + 更新计划 + 记 DEFERRED。
+
+## 4. Definition of Done（全部满足才算"交付"）
+- [ ] 环境可复现、`pytest` 全量可跑
+- [ ] lint + 类型检查 clean
+- [ ] 新行为有测试、被改遗留行为有特征测试，全绿
+- [ ] 关键路径覆盖：condition 分支 / parallel join / loop exit / HITL resume / cancel-retry-timeout / DB 持久化 / trace 持久化 / 重启恢复
+- [ ] 审计链未断（能从一次执行回放出完整 trace）
+- [ ] diff 过下方品味清单自审
+- [ ] 活文档已更新
+
+## 5. 代码品味（反屎山）
+**做**：复用优先/DRY（rule of three）；单一职责 + 清晰缝合；确定性内核 / IO 在边缘；
+显式状态机（统一 `success`/`completed` 口径为一个枚举）；执行幂等可恢复；结构化错误带上下文上抛。
+**禁**：god object / copy-paste / 泄漏抽象 / 为"将来"硬造的空抽象；
+N+1、该流式却整段 buffer、async 里阻塞、无界并发；一个 PR 混多目的；
+默默改公共接口 / DB schema / 状态语义而不在 PR 显式标注 + 给迁移。
+
+## 6. 命令（Phase 0 内发现并填好，之后即为唯一权威）
+- 安装：`<TODO 填>`
+- Lint：`<TODO>`   类型检查：`<TODO>`
+- 测试（全量）：`<TODO —— 先让 pytest 跑起来，这是头号阻塞>`
+- 启动 / 冒烟：`<TODO>`
+> 跑不起来测试，就不要往下走。
+
+## 7. 活文档（持续维护，PR 同步更新）
+`docs/ARCH_BASELINE.md`（现状）· `docs/UPGRADE_PLAN.md`（DAG + 进度）· `DEFERRED.md`（越界发现）· `docs/decisions/`（ADR：关键架构决策与权衡）。
+
+## 8. 项目锚点
+- 头号阻塞：让 `pytest` 跑起来。
+- 最高杠杆一对：**统一执行持久化路径 + 修正编排语义**（排前两批）。
+- 顺序红线：执行统一 + 审计接通**之前**，不碰反馈闭环(35%) 与企业级治理(RBAC/多租户/P2)。
+- 死代码决断：`_execute_tool_node` 存在但 `NodeType` 无 `TOOL` → 要么正式接入 + 测试，要么删，不许留着误导。
+
+## 9. Git 卫生
+- 一个 PR 一个目的，commit 聚焦、可回滚、信息里带子任务 id。
+- 不在 commit / PR 里加任何 AI/Claude/Codex 署名或 "Generated by" 脚注。