Imported from glaxry/meeting_pro (AGENTS.md). Install upstream with npx skills add glaxry/meeting_pro. Copyright stays with the author.

AGENTS.md

本文件是 AI 编码 agent（Codex / Claude Code / Cursor 等）在本仓库工作的持久约束。开工前必读，每个任务都适用。 工具适配：Codex 读 AGENTS.md；若用 Claude Code 把本文件复制/软链为 CLAUDE.md；若用 Cursor 复制到 .cursor/rules/。内容一致。

1. 项目是什么

Quorum 是一个会议记忆型多智能体系统。它对每条会议决策/待办/风险做证据接地的确定性验证，跨会议追踪承诺与决策演化，并主动检测决策漂移。

一句话工程主线（贯穿全仓库）：

LLM 负责提出候选（propose），确定性验证层拥有最终裁决权（adjudicate）。记忆层负责跨时间一致性。

架构是双轨：实时链路（事件驱动、低延迟、只出候选）+ 离线链路（阶段化、确定性验证、出可信事实）。详见 docs/design.md。

2. 黄金规则（Golden Rules · 不可违反）★

违反以下任意一条都是 bug，即使"看起来能跑"。这些规则优先于任何"更简单/更聪明"的实现冲动。

1. 确定性验证拥有裁决权。 verdict（VERIFIED/REJECTED/NEEDS_REVIEW）只能由 verification/engine.py 通过 Validation DSL 规则确定性地产生。严禁用 LLM 调用决定 verdict。 LLM / NLI 只能产出"信号"（如 faithfulness score），写入 faithfulness_scores，不得写 verdict 或决定是否放行。
2. Contract-first / Schema-first。 任何数据形状（Pydantic 模型、DB 列、KG 节点/边、事件 payload）的新增或修改，必须先改 docs/data_contract.md；任何新增 Agent 或改变 Agent 读写字段，必须先改 docs/agent_protocol.md 的字段所有权矩阵。先改契约，后写代码。
3. 证据账本只追加（append-only）。 ledger_entries 只允许 INSERT，禁止 UPDATE / DELETE。状态变化用"新行 + KG 边"表达（如承诺状态变化、决策被取代）。
4. 一切 VERIFIED 必须接地。 每个 verdict=VERIFIED 的 LedgerEntry 必须有 ≥1 个 EvidenceSpan；每个 EvidenceSpan.quote 必须是其 segment 文本的子串（INV-2）。接地校验是确定性的字符串检查，不是 LLM 判断。
5. 黑板单写者。 MeetingState 每个字段只有一个 Agent 可写（见 docs/agent_protocol.md §4 矩阵）。并发 fan-out 的 Agent 各写各的字段，禁止共享可变字段并发写。
6. Agent 间禁止自然语言传话。 Agent 之间只交换 docs/data_contract.md 定义的结构化对象。
7. 高风险/外部操作必过 HITL。 tool_executor 在没有对应 human_confirmation(accepted=true) 事件时绝不执行任何外部写入（Notion/Jira/Issue）。所有外部写入记录可回滚日志。
8. 数据不变量 INV-1~9 恒成立（见 docs/data_contract.md §6），且每条都有对应测试。
9. 置信门控。 confidence < 阈值 的 artifact 不得为 VERIFIED（INV-7）；进入长期记忆的条目必须有 source_meeting_id（INV-6）。
10. Verifier 不可降级跳过。 抽取类 Agent 失败可隔离降级（记入 failed_agents，不中止会议）；但 Verifier 失败时宁可整体告警，绝不"无验证放行"。

3. 仓库结构（代码放哪）

backend/app/
  orchestration/   # LangGraph supervisor + 阶段编排 phases/
  agents/          # 每个 Agent 一个文件，对应 agent_protocol.md 契约卡
  verification/    # engine.py + dsl.py + rules.yaml  ← 脊柱，确定性
  ledger/          # evidence_ledger.py（append-only, 内容哈希寻址）
  memory/          # raw_log/episodic/semantic_kg/procedural/preference/governance
  retrieval/       # hnsw_index.py (pybind11) + 混合检索
  scheduler/       # event_bus.py(Redis Stream) + router.py + policy.py(scoring)
  audio/           # vad/asr/diarization/chunker
  outputs/         # minutes/tracker/decision_log/attention/brief
  schemas/         # Pydantic 模型（data_contract.md 的代码实现）
  api/ db/
  eval/            # metrics + bootstrap_ci + ablation
docs/              # design.md / evaluation.md / data_contract.md / agent_protocol.md
tests/             # 与 backend 结构镜像；INV-* 与 DSL 规则有专门测试

新文件按此结构放置。不要在 verification/ 里引入 LLM 调用（脊柱必须确定性）。

4. 环境与命令

# 安装（任一）
pip install -e .          # 或 uv sync
# 起依赖
docker compose up -d      # PostgreSQL + Redis
# 数据库迁移
alembic upgrade head
# 运行
uvicorn app.main:app --reload
# 测试 / 质量门（提交前必须全过）
pytest -q
ruff check . && ruff format --check .
mypy app

声明"完成"前必须本地跑通 pytest、ruff、mypy。

5. 编码约定

• Python 3.11+；全量 type hints；数据模型一律 Pydantic v2（schemas/ 是 data_contract.md 的代码映射）。
• 命名：函数/变量 snake_case，类 PascalCase，枚举值全大写；ID 规则严格按 data_contract.md §0.1（entry_id = 内容哈希）。
• I/O 密集处用 async；LLM/外部调用包超时与重试（见 agent_protocol.md §6）。
• 不写裸 except:；用结构化日志（可观测字段见 agent_protocol.md §9）。
• 不引入未在 docs/ 选型表中的重依赖；如确需，先在 PR 说明并更新文档。
• 保持改动聚焦当前任务，不顺手重构无关代码。

6. 测试要求

• 每个模块随附测试；测试结构镜像 backend/app/。
• INV-1~9 每条都要有专门测试（tests/test_invariants.py）。
• Validation DSL 每条规则要有单元测试（正例 + 反例 → 期望三态）。
• 验证器元评测脚手架：Verifier 输出可被 eval/ 统计为混淆矩阵（见 docs/evaluation.md §1）。
• 新增 Agent 要有"契约卡一致性"测试：只写它被授权的字段、产物满足后置条件。
• 优先确定性单测；LLM 相关用打桩（stub）或录制回放，避免测试依赖真实模型。

7. 工作流（How to work）

1. 先读文档：动手前读对应 docs/（数据→data_contract.md，Agent→agent_protocol.md，整体→design.md，评测→evaluation.md）。
2. 数据/契约改动前置：要改数据形状或 Agent 字段，先更新对应契约文档，再写代码。
3. 小步可审：每个任务产出小而聚焦的 diff；不要一次性铺开整个系统。
4. 写测试：实现与测试同 PR；INV 与 DSL 规则必测。
5. 冲突上报：若设计文档与现有代码冲突，显式指出并询问，不要静默偏离契约。
6. 完成前自检 Definition of Done（§9）。

8. 反模式（绝对不要做）

• ❌ 用 LLM 调用产生 verdict 或决定是否放行（破坏脊柱）。
• ❌ 在 verification/ 里 import LLM 客户端。
• ❌ UPDATE/DELETE ledger_entries（破坏 append-only）。
• ❌ 静默新增/改字段而不更新 data_contract.md。
• ❌ 让两个 Agent 写同一个黑板字段。
• ❌ Agent 间用拼接的自然语言字符串传递结构化信息。
• ❌ tool_executor 在无 HITL 确认时执行外部写入。
• ❌ 超出当前阶段范围的过度工程（如 MVP 阶段上 Neo4j/k8s）。
• ❌ 把 evidence.quote 的"是否接地"交给 LLM 判断（必须是子串校验）。

9. Definition of Done（每个任务收尾自检）

• 符合全部黄金规则（§2），未触发任何反模式（§8）。
• 涉及的数据形状/Agent 字段改动已先更新对应契约文档。
• 新增/改动代码有测试；相关 INV 与 DSL 规则有专门测试。
• pytest / ruff / mypy 全过。
• 改动聚焦当前任务，无无关重构。
• 对外行为变化已在 PR 描述说明；与文档不一致处已显式标注。

10. 参考文档