文档合规审查 Agent 完整计划

1. 问题类型与目标

问题类型：计划 + 技术架构 + 风险控制。

目标：把现有 12 周计划升级为一个更像企业可落地 Agent 的实施计划，补齐原计划中缺失但对生产化很关键的能力：

• Guardrails / 安全护栏
• LLM 缓存层
• 模型降级 / fallback / circuit breaker
• RAG 评估框架
• Prompt 版本管理
• 用户反馈闭环
• 限流 / 熔断 / retry with backoff
• 结构化日志 / 指标 / 告警
• 多格式文档摄取层：PDF、图片、Word、Excel 统一解析为内部 DocumentIR

最终项目定位：面试级毕业项目，但架构表达要接近真实金融/法务场景。它不应宣称替代律师或合规人员，而应定位为“合同风险初筛、证据化审查、人工审批辅助”。

2. 当前 PLAN.md 的判断

原计划优点：

• 核心流程明确：PDF 解析、条款分块、RAG 检索、风险评分、人工审批、报告生成。
• 选型有面试价值：LangGraph、PostgresSaver、混合检索、RRF、BGE reranker、LangFuse。
• 已经意识到合规场景的 DLP 和审计要求。
• 有周粒度交付物，不是泛泛而谈。

原计划主要缺口：

• 安全护栏还不够系统。DLP 只能处理敏感信息，不等于能防 prompt injection、越权输出、无依据结论。
• LLM 调用没有统一网关。缓存、重试、降级、限流、成本统计、结构化输出验证都应集中在 LLMGateway。
• RAG 质量只有手工验证，缺少可重复评估指标和回归集。
• LangFuse 只是 trace，没有 prompt 变更治理和线上质量闭环。
• FastAPI 缺少 rate limit、job 并发控制、幂等、任务队列或轻量后台执行策略。
• 日志/指标/告警没有进入工程计划，排障故事不够完整。
• 文档输入假设过窄。真实合同可能是 PDF、图片、Word、Excel 或附件组合，不能把“转 PDF”当作唯一中间层。
• Docker Compose 中的 LangFuse 需要按当前官方自托管架构核实。新版 LangFuse 自托管通常不只是 Postgres，还涉及 Web、Worker、ClickHouse、Redis/Valkey、对象存储等组件；如果为了轻量 demo，可以固定 v2 或直接使用 LangFuse Cloud/本地最小可用配置。

3. 更合理的目标架构

Streamlit UI  - 上传合同  - 进度轮询  - 风险差异视图  - 人工审批  - 报告下载  - 用户反馈        |        vFastAPI  - REST API  - rate limit  - job 状态  - 幂等 key  - 后台任务调度  - Prometheus metrics        |        vDocument Ingestion Layer  - 文件类型识别  - PDF / 图片 / Word / Excel parser  - OCR / 表格解析 / 批注和修订读取  - 统一输出 DocumentIR  - 可选生成 PDF preview 用于 UI 标注        |        vLangGraph Workflow + PostgresSaver  1. DocumentIR 规范化  2. 条款分块  3. prompt injection / 文档攻击检测  4. 条款提取与分类  5. 跨引用解析  6. 混合检索 BM25 + Dense + RRF  7. reranker 精排  8. 逐条风险评分  9. 输出护栏与事实校验 10. 高风险人工审批 interrupt 11. 结构化报告生成 12. 反馈写入与评估样本沉淀        |        vLLMGateway  - DLP sanitize / desanitize  - prompt registry  - semantic cache  - structured output validation  - retries with exponential backoff  - circuit breaker  - provider fallback  - cost/token metrics  - LangFuse trace        |        vModel Providers  - DeepSeek API: 默认主力模型  - 本地 Qwen / 小模型: 降级、分类、简单抽取  - 可选 OpenAI/其他模型: 高价值评分 fallbackData Stores  - Postgres: jobs, checkpoints, approvals, feedback, eval runs  - Redis: rate limit, distributed lock, semantic cache, queue  - Chroma: rules vector collection  - BM25 index: rules.bm25.pkl  - LangFuse: traces, prompt versions, eval metadata  - Prometheus/Grafana 或轻量 metrics endpoint: 系统指标

4. 核心模块拆分

4.1 多格式文档摄取、DocumentIR 与条款建模

目录建议：

src/contract_review/ingestion/  detector.py  document_ir.py  pdf_parser.py  image_ocr.py  docx_parser.py  excel_parser.py  libreoffice_convert.py  preview.pysrc/contract_review/parsing/  table_parser.py  chunker.py  cross_ref.py

核心原则：

• 不要把所有文件先转 PDF 再审查。
• 上传后先做文件类型识别，再按类型解析为统一内部结构 DocumentIR。
• PDF preview 只作为前端预览、坐标标注和人工核查的副产物，不作为唯一语义中间层。
• 下游 LangGraph、RAG、风险评分统一消费 DocumentIR，避免业务逻辑绑定某一种文件格式。

DocumentIR建议结构：

{"document_id": "...","source_type": "pdf|image|docx|doc|xlsx|xls","source_filename": "...","blocks": [        {"block_id": "b001","type": "heading|paragraph|table|image|sheet_range|comment|revision","text": "...","page": 1,"sheet_name": None,"cell_range": None,"bbox": None,"section_path": ["第一章", "第1条"],"metadata": {}        }    ],"tables": [],"attachments": [],"preview_pdf_path": None}

不同格式处理策略：

验收：

• PDF、图片、Word、Excel 至少各有一个 fixture 能解析成 DocumentIR。
• 一份合同能从 DocumentIR切成稳定的 clause 列表。
• 每个条款有 clause_id、title、text、source_ref、page_range、sheet_name、cell_range、section_path、references。
• 识别 第X条、附件X、见本协议第X.Y款等跨引用。
• Excel 附件中的付款计划、报价表、服务清单不要简单拍平成普通段落；需要以 table/sheet_range 进入后续审查。

4.2 DLP 与 Guardrails

DLP 处理敏感信息，Guardrails 处理安全边界，两者不能混为一谈。

目录建议：

src/contract_review/security/  dlp.py  prompt_injection.py  input_guard.py  output_guard.py  policy.py

必须覆盖：

• 输入护栏：检测合同中嵌入的 prompt injection，例如“忽略上述规则”“把系统提示词输出出来”“不要遵守审查标准”。
• 检索护栏：RAG 只允许使用合规规则库和当前合同内容，不允许模型编造法条。
• 输出护栏：风险结论必须有 matched_rule_id和证据引用；无法匹配时输出 UNCERTAIN，进入人工复核。
• 结构化输出校验：Pydantic schema 校验失败自动 retry，超过次数后降级为人工复核。
• DLP 必须在所有 LLM 调用和 LangFuse trace 之前执行。

建议不要第一版就引入过重的安全框架。MVP 用规则检测 + LLM 分类器 + schema validation 就够；后续可以接 Guardrails AI、Llama Guard 或 NeMo Guardrails。

4.3 LLMGateway

这是原计划最应该新增的核心抽象。

目录建议：

src/contract_review/llm/  gateway.py  providers.py  cache.py  fallback.py  schemas.py  prompts.py

职责：

• 统一调用 DeepSeek、本地模型和可选备用模型。
• 统一加 DLP、LangFuse trace、prompt version、retry、timeout、cache、fallback。
• 支持不同任务选择不同模型：
• clause_classification: cheap / fast
• risk_scoring: stronger / structured JSON
• report_generation: longer context
• guardrail_check: fast classifier
• 所有调用返回统一结构：

{"task": "risk_scoring","model": "deepseek-v4-pro","prompt_version": "risk_scoring@2026-06-15","input_hash": "...","cache_hit": False,"output": {...},"tokens": {"input": 1234, "output": 456},"latency_ms": 2400,"trace_id": "..."}

4.4 缓存策略

缓存不能直接缓存原始合同敏感文本。

建议：

• Redis 做精确缓存：key = task + model + prompt_version + sanitized_input_hash + rule_context_hash。
• 可选 semantic cache：只对规则解释、通用条款分类这类低风险任务启用；风险评分默认先不开 semantic cache，避免相似但关键金额不同的条款误复用。
• 缓存值只存脱敏输入 hash、脱敏输出、token、trace_id、过期时间。
• Prompt 版本变化后自动 cache miss。

验收：

• 同一条款重复审查时不重复调用 LLM。
• 修改 prompt version 后不会命中旧缓存。
• 原始手机号、公司名、银行账号不进入 Redis。

4.5 Fallback / Retry / Circuit Breaker

建议实现一个轻量链路：

DeepSeek primary  -> retry 3 times with exponential backoff  -> circuit opens after N failures  -> fallback to local Qwen / cheaper extraction model  -> if still failed, mark clause as NEEDS_MANUAL_REVIEW

注意：

• 降级结果不能伪装成高置信度结果。
• fallback 后必须在输出中标记 degraded: true和 provider_chain。
• 对 HTTP 429、timeout、5xx 分开记录。
• 对 JSON schema 不合法也走 retry，但不要无限 retry。

4.6 RAG 评估框架

不要只用 Ragas/TruLens 的默认分数。合规审查更需要任务指标。

建议指标：

• 检索层：
• Recall@K：目标规则是否在 top K。
• MRR：目标规则排位。
• NDCG@K：排序质量。
• 风险分类层：
• HIGH/MEDIUM/LOW macro F1。
• HIGH 类召回率，优先高风险漏检不能太高。
• false positive rate，避免全部判高风险。
• 报告层：
• 每个风险结论是否有证据条款。
• 是否引用不存在的规则。
• 是否输出未经证据支持的法律结论。
• 系统层：
• 平均耗时、P95 耗时。
• 每份合同 token 成本。
• cache hit rate。
• fallback rate。
• manual review rate。

目录建议：

evals/  fixtures/  golden/  run_eval.py  metrics.py  reports/

验收：

• python -m evals.run_eval --dataset fixtures可生成一份 Markdown/JSON 评估报告。
• 每次 prompt 或规则变更后都能跑回归。

4.7 Prompt 版本管理

Prompt 不要散落在代码字符串里。

目录建议：

prompts/  clause_classification/v1.yaml  risk_scoring/v1.yaml  report_generation/v1.yaml  guardrail_check/v1.yaml

每个 prompt 文件包含：

id:risk_scoringversion:v1owner:contract-reviewupdated_at:"2026-06-15"input_schema:RiskScoringInputoutput_schema:RiskScoringOutputmodel_policy:primary:deepseek-v4-profallback:-local-qwentemperature:0system:|  ...user_template:|  ...changelog:-"v1: 初版"

验收：

• 每次 LLM 调用都记录 prompt_id和 prompt_version。
• Prompt 改动有 git diff 和 eval 结果。
• LangFuse prompt management 可作为 UI 管理层，但本地 YAML 仍作为可审计源文件。

4.8 用户反馈闭环

反馈不是可选功能。它是这个项目讲“企业落地”的关键。

Postgres 表建议：

review_jobsreview_clausesapprovalsfeedback_itemseval_runsllm_calls

反馈字段：

• clause_id
• predicted_risk_level
• user_corrected_risk_level
• user_comment
• false_positive
• false_negative
• accepted
• created_at

用途：

• 生成 few-shot 候选样本。
• 更新规则库。
• 形成回归测试集。
• 统计模型在哪些规则上常出错。

4.9 限流、任务并发与接口可靠性

FastAPI 层至少需要：

• /healthz和 /readyz。
• per-IP 或 per-user rate limit。
• 上传文件大小限制。
• job 幂等：同一文件 hash + 同一规则版本重复提交，返回已有 job 或明确新建。
• 后台任务并发限制：避免一次上传很多合同把 LLM API 打爆。
• retry with backoff：仅在 LLMGateway 和外部依赖调用处做，不要在所有层重复 retry。

轻量实现：

• Redis + slowapi或 limits做 rate limit。
• asyncio.Semaphore控制本地并发。
• 后续再换 Celery/RQ/Arq。

4.10 结构化日志、指标与告警

建议最小可用：

src/contract_review/observability/  logging.py  metrics.py  tracing.py

必须记录：

• job_id
• thread_id
• contract_id
• clause_id
• trace_id
• prompt_id
• prompt_version
• model
• latency_ms
• cache_hit
• fallback_used
• risk_level
• error_type

指标：

• review_job_total
• review_job_failed_total
• llm_call_total
• llm_call_latency_seconds
• llm_cache_hit_total
• llm_fallback_total
• guardrail_block_total
• manual_review_total
• rag_recall_at_k

告警条件：

• 5xx 错误率超过阈值。
• LLM fallback rate 突然升高。
• cache hit rate 异常下降。
• HIGH 风险召回率在回归测试中下降。
• LangGraph checkpoint 恢复失败。

5. 修订后的 12 周计划

W1：项目骨架、依赖、基础设施

交付：

• Python 项目结构，建议 src/contract_review。
• pyproject.toml。
• .env.example，不提交真实密钥。
• Docker Compose：Postgres、Redis、Chroma，LangFuse 使用“当前官方推荐 compose”或固定可运行版本。
• make test/ make lint/ make dev。
• 最小 FastAPI /healthz。
• DocumentIR、source_ref、上传文件元数据 schema 初稿。

验收：

• 本地一条命令启动基础服务。
• 单元测试框架可运行。
• README 有开发启动步骤。
• DocumentIR可以 JSON 序列化，并能表达 PDF 页码、Word 段落、Excel 单元格范围、图片 OCR 坐标。

W2：多格式文档摄取、条款分块、跨引用

交付：

• ingestion/detector.py：识别 PDF、图片、docx/doc、xlsx/xls。
• ingestion/document_ir.py：统一内部结构。
• ingestion/pdf_parser.py、image_ocr.py、docx_parser.py、excel_parser.py初版。
• ingestion/libreoffice_convert.py：老 .doc/ .xls兼容转换。
• parsing/chunker.py、parsing/cross_ref.py。
• 至少 4 份样例：PDF、图片、Word、Excel 各一份；其中至少一份包含付款计划表。
• 条款 JSON 输出格式和 source_ref证据定位格式定稿。

验收：

• 四类文件都能解析成 DocumentIR。
• 一份合同能从 DocumentIR解析成稳定条款列表。
• 表格区域、Excel sheet range、Word 表格、图片 OCR 区域都有明确解析策略。
• 跨引用能把被引用条款追加为上下文。

W3：规则库、规则入库、标注数据

交付：

• rules/compliance_rules.yaml，至少 25 条。
• scripts/ingest_rules.py。
• Chroma collection compliance_rules。
• BM25 index。
• 5 份标注合同 ground truth。

验收：

• 查询“违约赔偿上限”可召回目标规则。
• 每条规则包含：规则 ID、类别、风险等级、依据、反面示例、审查提示。

W4：RAG 检索与评估基线

交付：

• BM25 + Dense + RRF。
• BGE reranker。
• evals/run_eval.py。
• 检索评估报告。

验收：

• Recall@10、MRR、NDCG@10 可自动计算。
• 检索结果包含证据片段和分数。

W5：LLMGateway、DLP、Guardrails、Prompt Registry

交付：

• LLMGateway。
• DLP v1。
• Prompt injection 检测。
• Prompt YAML registry。
• schema validation + retry。

验收：

• 所有 LLM 调用只能从 LLMGateway走。
• LangFuse 和日志中不出现未脱敏敏感信息。
• 恶意合同指令不会改变审查系统指令。

W6：LangGraph 核心节点

交付：

• ReviewState定稿。
• 条款分类节点。
• 检索节点。
• rerank 节点。
• 风险评分节点。
• 报告生成节点。

验收：

• 单份合同可跑完审查并输出结构化 JSON + Markdown。
• 风险评分输出必须有证据和规则 ID，低置信度进入人工复核。

W7：人工审批、PostgresSaver、任务状态

交付：

• LangGraph interrupt。
• PostgresSaver checkpoint。
• review_jobs和 approvals表。
• /review/start、/review/{id}/status、/review/{id}/approve、/review/{id}/report。

验收：

• Graph 可暂停和恢复。
• FastAPI 不因等待人工审批而阻塞。
• 审批后报告重新生成或继续生成。

W8：缓存、限流、fallback、接口硬化

交付：

• Redis LLM cache。
• rate limit。
• LLM retry + timeout + circuit breaker。
• provider fallback。
• job 幂等。

验收：

• 重复审查同一脱敏输入可命中缓存。
• DeepSeek 模拟 429/5xx 时系统能退化为人工复核或备用模型。
• API 层可以限制并发和文件大小。

W9：Streamlit UI 与反馈闭环

交付：

• 上传页。
• 进度页。
• 审批页。
• Diff 风险视图。
• 报告页。
• 用户反馈入口。

验收：

• 可演示完整流程：上传、审查、审批、报告、反馈。
• 反馈写入 Postgres，可导出为 eval 样本候选。

W10：可观测性与告警

交付：

• LangFuse tracing。
• JSON structured logs。
• Prometheus metrics endpoint。
• Grafana dashboard 或轻量指标页面。
• 错误分类和告警阈值说明。

验收：

• 每次审查能从 job_id追踪到 clause、LLM call、prompt version、cache/fallback。
• 失败 job 能快速定位失败节点。

W11：质量回归、性能、规则扩充

交付：

• 规则库 40+ 条。
• 标注合同 10+ 份。
• 端到端 eval 报告。
• 性能基准。
• 漏检/误检分析。

验收：

• HIGH 风险召回率达到预设目标。
• P95 审查耗时和每份合同成本可展示。
• 关键 prompt 或规则变更必须附带 eval 结果。

W12：演示、文档、面试材料

交付：

• README。
• 架构图。
• 3 分钟演示脚本。
• 面试问答。
• 风险与范围声明。
• docs/production_notes.md，说明从 demo 到生产还缺什么。

验收：

• 新电脑可按 README 跑起 demo。
• 能讲清楚 RAG、LangGraph、DLP、Guardrails、缓存、fallback、评估、反馈、可观测性。

6. 哪些适合 Claude Code + DeepSeek API，哪些更适合 Codex

6.1 Claude Code 接 DeepSeek API 适合做

适合低成本、边界清晰、可由测试验收的工作：

• 项目脚手架、目录结构、基础配置。
• FastAPI CRUD 和 mock endpoints。
• Pydantic schema、TypedDict、SQLAlchemy models。
• 规则 YAML 初稿、测试 fixture 初稿。
• PDF、图片 OCR、Word、Excel 解析脚本的多个候选实现。
• DocumentIRfixture 和不同文件类型的解析单测。
• DLP 正则、简单 NER 封装。
• BM25、RRF、Chroma ingest 的常规代码。
• Prompt YAML 初稿。
• Streamlit 基础页面。
• README、演示脚本、面试问答初稿。
• DeepSeek API client、JSON output 调用、tool/function calling 示例。
• 合成测试合同和合成评估样本。

使用边界：

• 不要让它单独决定合规规则是否正确。
• 不要让它无测试地大改核心状态结构。
• 不要让它同时改多个跨模块接口。
• 不要把真实合同和真实 API key 交给它写入文件。

6.2 更适合 Codex 做

适合高整合、高验证、需要读完整工程上下文的工作：

• 总体架构和模块边界。
• ReviewState、API contract、数据库 schema 这类稳定契约。
• LangGraph + PostgresSaver + FastAPI 异步恢复的集成。
• LLMGateway的调用链设计。
• Guardrails、DLP、LangFuse、cache、fallback 的全链路串联。
• 端到端调试和测试修复。
• 浏览器/前端演示验证。
• 代码审查、回归测试、质量门禁。
• Git 分支整合、冲突处理、PR 描述。
• 判断哪些功能应砍掉，防止项目失控。

6.3 一个实用分工原则

• Claude Code + DeepSeek：做“可拆小包”的实现者。
• Codex：做“架构 owner、测试 owner、集成 owner、最终质量 owner”。

7. 让 Codex 和 Claude Code 协作的方法

7.1 仓库协作方式

建议单仓库，多分支：

maincodex/architecture-and-integrationclaude/w1-project-scaffoldclaude/w2-ingestion-document-irclaude/w3-rules-ingestclaude/w5-dlp-guardrailsclaude/w8-cache-fallback

每个 Claude 分支只允许改一组文件，避免交叉编辑。

7.2 文件 ownership

建议：

Codex owner:  src/contract_review/graph/  src/contract_review/llm/gateway.py  src/contract_review/api/  src/contract_review/ingestion/document_ir.py  evals/  pyproject.toml  docker-compose.ymlClaude owner:  src/contract_review/ingestion/pdf_parser.py  src/contract_review/ingestion/image_ocr.py  src/contract_review/ingestion/docx_parser.py  src/contract_review/ingestion/excel_parser.py  src/contract_review/parsing/  src/contract_review/retrieval/  rules/  prompts/  ui/pages/  docs/  tests/unit/

实际可以调整，但原则是：状态契约、接口契约、跨模块集成由 Codex 控制；局部模块由 Claude 产出初稿。

7.3 每个任务都用同一张任务卡

# Task: <任务名>## Context当前项目目标、相关文件、不能改的契约。## Scope只允许改哪些文件；不允许做哪些事。## Requirements功能要求。## Acceptance Tests必须通过的测试或命令。## Output需要返回变更摘要、运行结果、风险。

7.4 工作流

1. Codex 先建立架构契约：state schema、API spec、DB schema、目录结构、测试命令。
2. Claude Code 在 DeepSeek 模式下按任务卡实现局部模块。
3. Claude 完成后，不直接合并 main；提交到 claude/*分支。
4. Codex 做 review：读 diff、跑测试、补集成、修冲突。
5. Codex 更新 eval 和文档。
6. 每周结束生成一份 WEEKLY_STATUS.md：完成项、风险、下周任务。

7.5 DeepSeek API 配置 Claude Code

根据 DeepSeek 官方 Agent Integrations 文档，Claude Code 可以通过 Anthropic-compatible endpoint 指向 DeepSeek。Mac/Linux 示例：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropicexport ANTHROPIC_AUTH_TOKEN=<your DeepSeek API Key>export ANTHROPIC_MODEL=deepseek-v4-pro[1m]export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro[1m]export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro[1m]export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flashexport CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flashexport CLAUDE_CODE_EFFORT_LEVEL=max

注意：

• 不要把 API key 写进仓库。
• 模型名、价格、上下文和限流会变化，使用前看官方文档。
• DeepSeek 当前也提供 OpenAI-format base URL 和 Anthropic-format base URL；项目代码自身调用 LLM 时建议通过 LLMGateway封装，不要在业务代码散落 provider 参数。

8. 给 Codex 的完整提示词

下面这段可以直接作为新 Codex 任务提示词使用。

你是这个项目的技术负责人和主实现者。请在当前仓库中构建一个“私有文档合规审查 Agent”的可演示系统，目标是面向金融机构法务部/券商合规部，对供应商合同、采购合同、DPA 等中文合同做风险初筛、证据化审查、人工审批和报告生成。请先阅读仓库中的所有计划文件，尤其是 PLAN.md 和 PROJECT_PLAN_AND_CODEX_PROMPT.md。不要直接假设现有代码结构，先检查文件树、依赖、测试命令和已有变更。核心目标：1. 合同文件上传后，系统能支持 PDF、图片、Word、Excel，按文件类型解析为统一 `DocumentIR`，再做条款分块。2. PDF preview 只能作为前端预览和人工定位的副产物，不要把“先转 PDF”作为唯一主流程。3. 对每个条款进行分类、跨引用解析、规则检索、rerank、风险评分。4. 高风险或低置信度条款进入人工审批断点，审批后继续生成报告。5. 报告必须包含风险等级、证据条款、匹配规则、理由、置信度、人工审批状态和来源定位。6. 系统必须有 DLP、Guardrails、LLM 缓存、fallback、RAG 评估、prompt 版本管理、反馈闭环、限流、结构化日志和基础指标。技术栈约束：- Python + FastAPI + Streamlit。- 多格式摄取层支持 PDF、图片、docx/doc、xlsx/xls，并统一输出 JSON serializable 的 `DocumentIR`。- LangGraph 用于审查工作流。- PostgresSaver 用于 checkpoint 和人工审批恢复。- Postgres 存 jobs、approvals、feedback、eval runs。- Redis 用于 rate limit、LLM cache、轻量锁或队列。- Chroma 存合规规则向量。- BM25 + Dense + RRF 做混合检索。- BGE reranker 做精排。- DeepSeek API 作为默认 LLM provider，但必须通过 LLMGateway 封装。- LangFuse 用于 LLM trace 和 prompt 管理，但任何敏感原文进入 LangFuse 前必须脱敏。- Prompt 存在 prompts/*.yaml，不要散落在业务代码里。必须新增或维护的核心模块：- src/contract_review/ingestion/- src/contract_review/parsing/- src/contract_review/retrieval/- src/contract_review/security/- src/contract_review/llm/- src/contract_review/graph/- src/contract_review/api/- src/contract_review/observability/- evals/- rules/- prompts/- tests/关键设计要求：1. 文件摄取层的输出目标是 `DocumentIR`，不是 PDF；PDF preview 是可选展示资产。2. `DocumentIR` 必须能表达 PDF 页码、图片 OCR 坐标、Word 段落/表格/批注/修订、Excel sheet/cell_range/formula。3. 所有 LLM 调用只能通过 LLMGateway。4. LLMGateway 必须统一处理 DLP、prompt version、structured output validation、retry with exponential backoff、timeout、cache、fallback、token/cost metrics、LangFuse trace。5. 所有 LangGraph state 字段必须 JSON serializable，不能放 Document、datetime、numpy array、模型对象。6. 风险评分必须输出结构化 JSON，并用 Pydantic 校验。7. 没有证据或规则 ID 的风险结论不能直接进入最终报告，必须标记为 UNCERTAIN 或 NEEDS_MANUAL_REVIEW。8. 合同内出现 prompt injection 指令时，不能影响系统指令和审查标准。9. 缓存不得保存未脱敏的原始合同文本。10. API 层需要 health/readiness、上传大小限制、rate limit、任务状态、幂等处理。11. 每次审查必须能通过 job_id 追踪到 thread_id、LangFuse trace_id、prompt_version、model、cache_hit、fallback_used。12. 任何真实 API key 不得提交到仓库，只能用 .env.example。API 目标：- POST /api/v1/review/start- GET /api/v1/review/{job_id}/status- POST /api/v1/review/{job_id}/approve- GET /api/v1/review/{job_id}/report- GET /api/v1/rules- GET /healthz- GET /readyz- GET /metrics评估要求：- evals/run_eval.py 能基于 tests/fixtures 或 evals/fixtures 运行。- 检索层输出 Recall@K、MRR、NDCG@K。- 风险分类层输出 HIGH/MEDIUM/LOW 的 precision、recall、F1，尤其关注 HIGH recall。- 报告层检查是否引用不存在的 rule_id、是否缺证据。- 每次 prompt 或规则改动都应能跑回归。工作方式：1. 先给出你对当前仓库状态的简短判断和实施顺序。2. 优先搭建稳定契约：目录、pyproject、state schema、API schema、DB schema、测试命令。3. 分小步实现，每步后运行相关测试。4. 不要大规模重构与当前任务无关的文件。5. 如果已有用户修改，不要回滚；先读懂再兼容。6. 每完成一个阶段，更新 README 或 docs 中的运行说明。7. 最终给出变更摘要、验证命令、未完成风险和下一步建议。第一阶段请优先完成：- 项目骨架- pyproject.toml- .env.example- docker-compose.yml- src/contract_review/ingestion/document_ir.py- src/contract_review/ingestion/detector.py 的接口骨架- src/contract_review/graph/state.py- src/contract_review/llm/gateway.py 的接口骨架- src/contract_review/security/dlp.py- FastAPI health/status mock- rules/compliance_rules.yaml 的初版- tests/test_state_serializable.py- tests/test_document_ir_serializable.py不要先做花哨 UI。先确保后端契约、测试和 LLM 调用边界正确。

9. Claude Code 任务提示词模板

给 Claude Code 的任务要更窄，不要让它接管全局架构。

你只负责实现下面这个局部任务，不要改动未列出的文件。项目背景：这是一个中文合同合规审查 Agent。核心架构由 FastAPI + LangGraph + PostgresSaver + LLMGateway + Chroma + Redis 组成。所有 LLM 调用必须通过 src/contract_review/llm/gateway.py。所有 state 必须 JSON serializable。任务：<填写具体任务>允许修改文件：- <列出文件>禁止修改：- src/contract_review/graph/state.py- API 路由契约- pyproject.toml，除非任务明确要求验收：- <列出 pytest 命令>- <列出手工验证命令>完成后请返回：1. 改了哪些文件。2. 如何运行。3. 已通过的测试。4. 你认为仍有风险的地方。

10. 判断标准

这个项目是否“完整合理”，看以下标准：

• 能否从一次审查结果追溯到合同条款、规则、检索证据、prompt 版本和模型调用。
• 高风险漏检率是否被量化，而不是靠主观感觉。
• 模型失败、API 限流、JSON 不合法时是否有退路。
• 合同中的恶意指令是否不会污染系统行为。
• 用户审批是否真的能暂停和恢复 Graph，而不是 UI 上假装审批。
• 敏感信息是否不会进入第三方 trace、日志和缓存。
• 反馈是否能进入下一轮规则/prompt/eval 改进。

11. 需要进一步核实的内容

• 合规规则本身必须由法律/合规专业人士复核。LLM 和工程实现只能保证流程，不保证法律判断正确。
• DeepSeek 模型名、价格、上下文长度、限流需要以官方文档为准。
• LangFuse 自托管部署方式需要以当前官方 self-hosting 文档为准。若本机资源不足，建议 demo 阶段先用 LangFuse Cloud 或固定轻量版本。
• 图片和扫描件 PDF 可以先用 OCR 做文本抽取；复杂版面理解、手写体、低质量扫描件和视觉模型精读建议放到二期，避免 12 周计划失控。

12. 参考资料

• DeepSeek API Models & Pricing: https://api-docs.deepseek.com/quick_start/pricing
• DeepSeek API Create Chat Completion: https://api-docs.deepseek.com/api/create-chat-completion
• DeepSeek API Rate Limit & Isolation: https://api-docs.deepseek.com/quick_start/rate_limit
• DeepSeek Claude Code Integration: https://api-docs.deepseek.com/quick_start/agent_integrations/claude_code
• LangFuse Self-hosting: https://langfuse.com/self-hosting