/contract-copilot

Contract Copilot 开发复盘：一个律师把「审查合同」教给 AI 的八个月

写作说明：本文基于 contract-copilot skill 的 Git 提交历史、CHANGELOG.md 与 DECISIONS.md 整理，还原 v1.0.0（2026-01）到 v1.6.3（2026-08）的真实演进脉络，记录其中的关键取舍与思考。

一、起点：为什么一个律师要写代码

contract-copilot 最初的形态，是一个很朴素的诉求：律师每天都要审查大量中文商业合同，能不能让 AI 把「识别风险 → 给出修改 → 落地成 Word」这条链路一次做干净。

作者杨卫薪律师给自己的定位很克制——不追求让 AI 代替律师做最终签署意见，而是做「律师复核前的结构化整理」。这个边界意识贯穿了项目全程：skill 的能力是「把风险定位、修改动作、推荐措辞和交付文档一次整理清楚」，而不是「给出笼统建议」。

DEC-001 记录了第一个核心决策（2026-01-15）：

采用「文档操作脚本 + AI 分析」分工模式——脚本负责 DOCX 精确编辑（批注/修订），AI 负责分析与建议输出。

这个决策是整条工程线的地基。它回答了一个很关键的问题：分析和落地要不要耦合？ 答案是不耦合。AI 天生擅长理解和表达，但让 AI 直接靠复制粘贴去改 Word 会带来大量格式错误；反过来，脚本能做精确的 OOXML 编辑，却不能判断「这条条款为什么有风险」。把两者分开，让各自做擅长的事，是这个项目始终没有动摇过的分工原则。

二、内容层：知识体系是怎么长出来的

2.1 固定 12 类合同，不盲目扩目录

项目一开始就面临一个诱惑：合同类型那么多，是不是类别越多越好？

DEC-003（2026-02-09）做出了一个反直觉的决定：固定 12 类，不做目录扩容。

当前痛点是覆盖深度不均，而非类别数量不足。

这个判断很有律师的职业直觉——审查质量的短板从来不在「种类不够全」，而在「每一种够不够深」。后续的演进证明这个决定是对的：项目把精力从「横向铺类别」转向「纵向做深度」，陆续用「全量映射清单 + 高频缺口单列」（DEC-009）、「高争议 + 高频 + 高程序性」的补齐优先级（DEC-010）来在 12 类的框架内把覆盖做满。

最终收敛为固定的 12 类：买卖、租赁、服务、知识产权、担保、借贷与赠与、互联网协议、婚姻家事、劳动用工、房地产、建设工程、公司投资。

2.2 一套可以反复打磨的方法论：分层四步审查

在内容层，项目沉淀出的核心方法论是「分层四步审查框架」：

• 宏观层：交易结构、主体资格、标的合法性、程序闭环
• 中观层：合同形式是否匹配阶段、主合同与附件是否冲突
• 微观层：核心条款齐全性、权利义务平衡性、违约解除可执行性

以及配套的风险分级（P0 / P1 / P2）、结论三档（可签 / 有条件可签 / 不建议签）。

值得注意的细节在 DEC-004：这个框架特意用「中性命名」表达，规避外部专有命名的显式引用。同时 DEC-005 定下一条合规红线——不在技能文档中标注外部资料的具体出处。对一个可能公开分发的开源 skill 来说，这两条从一开始就设好了版权与分发的安全边界。

2.3 最纠结的部分：references 目录结构

如果回看 DECISIONS.md，会发现一个很有意思的现象：项目花在「合同知识放哪、怎么组织」上的决策反复，几乎和写知识本身一样多。

从 DEC-018 到 DEC-032，references 目录经历了至少五轮结构调整：

1. 先是「四层入口 + 专题路由索引」（DEC-018）
2. 然后取消横向专项议题体系，回归「三层入口 + 主文件」（DEC-019）
3. 再把 12 类目录下沉到 合同类型/（DEC-020）
4. 接着把合同主文件移出 references，直接放技能根目录（DEC-023）
5. 又放回 references 根层，让起草与审查共用同一套 reference（DEC-024）
6. 最后收敛为「入口文件 + contract-types」的轻量结构（DEC-032）

这种反复说明了一个真实的问题：知识体系的组织方式，本质是对「这份知识到底服务什么」的重新理解。 项目最初以为自己在做一个「合同库」，后来意识到自己在做一个「审查入口」——「references 根层应首先强调『怎么审』，而不是『有哪些合同』」（DEC-020）。这个认知转变，才是目录不断重构背后的真正动力。

与此相关的还有一条颇具远见的边界设计：从 DEC-027 开始，项目建立了 internal-notes/ 内部台账，用来维护「来源材料吸收进度」和「去风险判断」，但这些内容绝不进入对外文档。对一个公开分发的 skill 来说，「内部可追踪」和「对外不暴露」同时成立，是一个非常成熟的工程+合规思维。

2.4 从「只审查」到「也能起草」

另一个认知升级发生在起草能力上。项目最初是纯审查定位，后来用户明确要求补强起草。

这里的思考轨迹同样一波三折：

• 先是让映射清单「既做审查分流、又做起草路由」（DEC-028）
• 再用「起草路由卡」把映射清单前移为起草编排层（DEC-031）
• 同时守住一个底线：起草与审查共用同一套 reference，不另起炉灶（DEC-024、DEC-028 反复强调）

「起草和审查本质上用的是同一套交易结构、条款骨架和风险控制逻辑」——这个判断避免了平行维护两套资料带来的口径分叉，是内容层最划算的架构决策之一。

三、工程层：把「能改 Word」打磨到「像人改的」

如果说内容层解决的是「AI 懂不懂合同」，工程层解决的则是「AI 改出来的 Word 能不能直接用」。这一块是项目后期（2026-03 下旬）最密集发力的地方，也最能体现作者对细节的偏执。

3.1 从「批注为主」到「改文优先」

早期版本偏保守，倾向输出批注提示，把「真正改文」的负担留给用户。DEC-038 是一个体验拐点：

仅输出批注虽然安全，但对多数用户并不省力，且会把「最后谁来真正改文」的负担重新推回人手里。

于是默认策略从「偏批注」切到 revise-first（改文优先）：只要审查项有明确改文载荷，就优先直接修订；只有涉及谈判取舍、事实待确认时才退回批注。 这背后是对用户真实需求的判断——律师要的是「能直接用的修订结果 + 关键改动的解释」，而不是自己在多种模式间切换。

3.2 最打动人的细节：时间线拟真

合同审查这个场景有个很特殊的要求：Word 里的批注作者和时间戳是「对外可见的元数据」，会暴露自动化痕迹。

这个项目在「拟真」上花了极大的心思，演进脉络清晰可见：

• DEC-034：审查人配置持久化，同一轮审查的批注按 5-10 分钟错峰
• DEC-039：时间线只能从命令执行时点向后顺延——修正了「客户中午给合同，Word 却显示上午已审完」的穿帮
• DEC-042：w:date 改用本机本地时区写入，而不是一律 UTC——否则客户 Word 里会显示成美国时间
• DEC-047：改为两层错峰——同一意见内部每个修订/批注批次顺延 1-2 分钟，意见之间保持 5-10 分钟

这种对「审阅视图观感」的极致追求，在 DEC-044 / DEC-045 达到顶峰：最小差异修订。真实样张里一个「只改一个短语却显示整条被重写」的问题，逼着项目把修订引擎从「整段替换」进化到「run 内局部修订 → 段落内片段修订 → 多段 diff 拆分」，把平均删除块从 53 字压到 6 字、插入块从 69 字压到 9 字。

「用户对『大段重写感』的敏感点，主要来自一个条款里多处变化被粗暴压成一个中段。」——这句话是一个做过大量合同的人才会有的洞察。

3.3 交付物体例：从「系统日志」到「律师意见书」

另一个重大的体验跃迁是对外报告体例的两次收敛：

1. DEC-037：把「执行状态、定位质量」等技术字段从客户报告移除，只留内部日志——「对外报告首先服务『快速理解合同和风险结论』，而不是暴露脚本执行过程」。
2. DEC-040 / DEC-043：从「风险清单式报告」升级为「审查意见书」——「致：收件方」开篇、合同概况、综合审查意见、逐项意见（原条款 / 建议修改 / 法律依据）、声明。

这个转变的驱动力来自外部 benchmark 和真实样张对比：客户真正要的是一份「意见书 + 修订版」的组合，而不是更多内部结构说明。 项目守住了自己「去技术化」的审查逻辑，但呈现方式向律师的真实出件习惯靠拢。

配套的还有版式打磨：吸收成熟法律文书的视觉参数（深蓝标题、仿宋正文、浅底元信息卡、棕色标签高亮、页脚页码，DEC-041），再收紧成紧凑正式件（DEC-046）——「23 页过长、表格和行距过松」是用户的真实痛点。

3.4 从「能用」到「可信」：安全与完整性的补课

项目末期的重心从「体验」转向「安全与可信」。这同样来自真实场景的压迫：合同文件来自邮件、IM、交易对方，不能把 DOCX 当作可信输入。

• DEC-061：交付前由独立完整性 verifier 阻断——「报告生成脚本自身『运行成功』不等于报告合格」，缺失法律依据、报告字段塌缩都会在写出正式产物前失败。
• DEC-062：不可信 DOCX 先全量预检 + 公开 OOXML 插入白名单——拒绝 Zip Slip 路径逃逸、符号链接，用 defusedxml + 命名空间白名单防止 XML 注入。
• Task-020：把 external evaluation 识别的 7 个「executed-fail」行为缺陷固化成一整套回归测试集，从 xfail 转为必过。

这条线反映了一个成熟判断：当自动化产物要对外交付时，「部分失败却被误判为全部成功」比「有失败」更危险（DEC-033）。用非零退出码、完整性门禁、回归基线来保证「能感知失败、不静默吞错」，是这个项目信任度的地基。

四、贯穿全程的三条方法论

4.1 「分析与操作分离」是永恒的底座

从 DEC-001 到 DEC-062，唯一没变过的是分工模式：AI 负责判断和表达，脚本负责精确执行，中间用 review-plan.json 作为结构化契约解耦（DEC-007、DEC-015）。这个契约让「分析」和「文档编辑」可以独立复用、复核、重跑，也让整套工程始终是「可测试、可回滚」的。

4.2 克制：不扩张，反复收敛

这个项目贯穿始终的是「克制」：

• 合同类型固定 12 类，不扩（DEC-003）
• 起草能力复用审查 reference，不平行造一套（DEC-024）
• 对外只交付「修订批注一体版」，不让用户在多种模式间切换（DEC-043）
• 报告体例从「技术清单」收敛到「意见书」（DEC-040）

每一次「克制」背后都有一个判断：新增复杂度的收益，抵不过口径分叉的代价。

4.3 用真实场景校准，而不是靠想象

几乎每个关键转折点都源于「真实样张 / 外部 benchmark / 用户反馈」的校准：

• 时间线穿帮 → 修正起点与时区
• 大段重写感 → 最小差异修订
• 报告像系统日志 → 意见书体例
• 23 页过长 → 紧凑版式

这是一个律师用「自己对专业交付物的洁癖」反复校准 AI 产品的过程。 很多体验细节，是只有真做这行的人才会在意的。

五、现在的样子与还在路上的事

截至 v1.6.3（2026-08-13），contract-copilot 已经是一个自包含、可打包、可公开分发的成熟 skill：

• 内容：固定 12 类合同 + 四层 references 结构（框架 / 路由 / 优先条款 / 修订策略）+ 起草工作台
• 工程：OOXML 直出的批注 / 修订 / 意见书，本地审查人配置，拟真时间线，安全加固与完整性门禁
• 交付：修订批注一体版 DOCX + 致函式审查意见书，过程文件内部归档

TASKS.md 里仍躺着十几条 DRAFT 待办，方向包括：

• 继续把 priority-clauses.md 细化到 12 类
• 按目录补齐房地产 / 建设工程 / 公司投资的起草模块
• 补强「方法层」资料（交易结构、程序要求、类型选择）
• 进一步降低 references 与来源材料的同构度
• 在真实 Windows + WPS 环境做冒烟验证

六、一句话总结

contract-copilot 的八个月，是一个专业律师把自己脑子里「怎么审一份合同」的隐性知识，逐步拆解、显性化、工程化、并反复用真实交付标准校准的过程。

它的核心资产不是某个模型或某个脚本，而是三样东西：

1. 一套经得起推敲的审查方法论（分层四步 + 风险分级 + 结论口径）；
2. 一套把 AI 判断落成专业 Word 交付物的工程链（计划契约 + OOXML 直改 + 拟真元数据 + 完整性门禁）；
3. 一条贯穿始终的克制原则（不扩类型、不分叉口径、不暴露内部、不静默吞错）。

它证明了一件事：当一个人既懂专业、又愿意把专业拆成规则和机器能执行的动作时，AI 能成为真正可用的专业助手——而不是只会给建议的聊天机器人。