Github：GitHub - Leterhong/docguard-skill · GitHub

魔搭Skills：Skill 详情 - 云效工具 - docguard-skill

摘要

先说一个让我挺较劲的事。现在大家一聊 AI 审合同、AI 读标书，默认动作都是把文件啪一下传到某个云端大模型那头，等着它吐结论。可企业合同、招标文件、技术方案这些玩意，哪能随便出门。

所以我就想，能不能让这件事彻底发生在自己机器上。这就是 DocGuard AI。它用 Client/Server 架构交付，服务只绑 127.0.0.1，接 Qoder、WorkBuddy、TRAE Work 这类生产力级 Agent 工具来调用，覆盖合同风险审查、招标文件分析、技术方案审查、企业知识问答、文档对比这五个场景。但我觉得最值得说的不是跑得起来，是它有两套命。

1. 企业文档这件事，麻烦在哪

企业每天要嚼大量合同、招标文件、技术方案和内部知识文档。传统的搞法，要么人肉通读，要么调云端大模型一把梭。前者费人，后者费钱还费心，因为文件真就出了门。

1. 数据合规这条红线，越是正规企业越不敢碰。合同里甲方乙方谁是谁、标书里多少钱、技术方案里有没有硬编码密码，这些一旦上传，就等于把家底亮给了别人。
2. 但纯本地又有个老问题，没大模型就啥也干不了。很多号称本地部署的方案，真到 inference 那一步还是偷偷回调云端，等于白本地。
3. 所以我做 DocGuard AI 的念头很简单，就是把这一摊能力，全收拢到一台 AI PC 上。模型真在本地跑，文件真不出机，审查、检索、报告一件不少。

它不追求一个万能黑盒，而是把确定性能干的事先用规则钉死，再把大模型当成锦上添花的增强层。这个次序很关键，后面你会看到为什么。

2. 整体长什么样

DocGuard AI 是「Agent 工具 → Skill → 本地服务层」三层结构，整层绑在 127.0.0.1 上。Agent 工具通过 HTTP 在我们约定的端口上调 Skill 暴露的能力，Skill 再去戳本地服务层干脏活累活。

图 1，DocGuard AI 系统架构全景。左边是生产力级 Agent 工具，Qoder、WorkBuddy、TRAE Work 这些。中间是 Skill 适配层，把工具的语言翻译成本地服务能懂的请求。右边才是真正干活的本地服务，OCR、解析、Embedding、规则引擎、本地大模型全在这。

有几个架构上的决定，我想单独拎出来说，因为它们是后面所有论证的地基。

• 服务只听 localhost。config 里 local_only 默认就是 True，绑 127.0.0.1，外网根本摸不进来，这是不出机的第一道闸。
• 大模型走子进程桥接。主服务跑在自己的 venv 里，哪怕没装 OpenVINO，也能通过桥接拉起一个装好 openvino-genai 的 Python 子进程，用行协议要推理。宿主环境脏一点也无所谓。
• 规则引擎和哈希嵌入是兜底底盘。没有大模型、没有语义模型，这条路径照样能把审查、检索、报告做出来。它不是备胎，是主路之一。

3. 一份文档进来，到出结果要经过几步

一次文档分析从头到尾的链路是这样，所有环节都在 localhost 完成。解析拿到文字，分类认出它是合同还是标书还是技术方案，切片后做 Embedding 进 FAISS 向量库，规则引擎先扫一遍风险，大模型在场的话再 enrich 一层，最后汇总成结构化结果。

图 2，八阶段分析流水线。解析、切片、分类、Embedding、向量库、规则引擎、LLM 增强、汇总。注意规则引擎在 LLM 之前，意思是即使最后一步的大模型挂了，前面六步的结论依然站得住。

五大功能怎么落到底层服务，我列一张表说清楚。合同审查、标书分析、技术方案审查、知识问答、文档对比，各自的入口 Tool 和核心服务都在表里。

功能	入口 Tool	核心服务
合同风险审查	analyze_document	文档解析 + 规则引擎 + 报告生成
招标文件分析	analyze_document --type tender	要求抽取 + 能力匹配 + 风险定位
技术方案审查	analyze_document --type technical	章节核查 + 安全/性能风险
企业知识问答（RAG）	search_document	切片 + Embedding + FAISS 检索
文档对比	compare_document	双文档差异比对

4. 我拿什么机器跑的

所有实测都在同一台 Windows AI PC 上跑的。先把运行环境和依赖钉死，后面所有的结论都以它为基准，不漂。

实测 1，环境确认。Windows 11、Python 3.13、AMD64。CPU 是这台机器自带的，没有独显也没有 NPU 加速，所以下面的所有数字你都可以当成「最朴素条件下的底线」，你的机器只会更快。

实测 1，环境确认。Windows 11、Python 3.13.14、AMD64，CPU 推理，无 GPU 无 NPU 加速。这是刻意选的最朴素基线，方便你复现。

这里有个细节我特意强调一下，因为它恰恰是后面论证的命门。DocGuard 的主服务虚拟环境，我是故意不装 OpenVINO 的。

• OpenVINO 运行时，装在另一个独立 venv 里，路径是 F:/Production AI Skills/.openvino/venv/dataanalysis。
• 本地模型，Qwen2.5-7B-Instruct-int4-ov，INT4 OpenVINO IR，约 4.4GB，也在那个独立 venv 能触达的目录里。

所以本文要论证的那个前提就立在这儿。DocGuard 最硬的底气，是哪怕在主环境没大模型、只有哈希嵌入加规则引擎这种最简条件下，Skill 也能真把事干成，这是它的兜底命门。而你往下看会发现，我实际跑 5.1 到 5.5 时，本机那个本地大模型是在线的，llm_used 全是 true，规则引擎打底、本地大模型增强，一起上的。

5. 五个场景，一个个真跑给你们看

下面每一个场景，都是本机真跑的。截图我保留了原始终端样子，提示符、命令、真实输出一字不删，结论和输出严丝合缝，不信你照抄命令自己验。

5.1 规则引擎单元测试，无模型纯逻辑

规则引擎是这套东西的确定性内核，不依赖任何模型。我直接拿单元测试去轰三类样例文档，合同、招标、技术方案，看它到底扫不扫得出来。

规则引擎本身就是个不靠任何训练黑盒的确定性内核，纯靠我把法律条款里那些坑，一条条写成正则钉死在代码里。也正是因为它不依赖模型，所以大模型在不在场都不影响它先出证据。下面就是它对着样例文档跑出来的真实输出，这次本机大模型也在线，llm_used 是 true，但每一条风险都还是规则引擎先钉死的。

实测 2，规则引擎对三类样例的实时输出。合同命中 8 条风险，4 高 4 中。招标抽取 9 项要求并给出能力匹配度。技术方案扫出安全与性能风险，并标记缺失章节。全是真实返回，没有任何我编的结论。

把输出拎出来说几点。第一，每一条风险都带 evidence，也就是它在原文里命中了哪段，不是黑盒拍脑袋。第二，缺失必备条款它直接报 High，比如合同里没写付款节点。第三，规则引擎本身就是能脱离大模型独立产出报告的（这是降级兜底），而这次实测本机大模型也在线，llm_used 是 true，两者结论互相印证、不打架。

• 合同引擎有 11 条硬编码规则，付款不明确、违约责任不对等、空白待填项这些都直接 High。
• 招标引擎会抽资质、业绩、财务、保证金这些要求，再反过来查你缺了哪几条必备流程节点。
• 技术方案引擎查八类必备章节，顺手扫硬编码密码、明文 HTTP、SQL 拼接、eval 这些危险信号。

5.2 端到端 API 合同审查，上传加分析

走一遍完整的 REST API，从上传到分析到结构化输出，把 Client/Server 这条链路真跑通。这一步验的是工程闭环，不是模型智商。

先 curl 一下 /api/health，看服务活没活，local_only 是不是 True。然后再上传样例、再分析。整条链路都在 127.0.0.1 内完成，文件根本没机会出门。

实测 3，调用 /api/upload 上传合同样例，再调 /api/analyze 拿回结构化结果。返回里 doc_type 是 contract，overall_risk_level 是 High，风险按 Low、Medium、High 分级。

几个关键字段我挑出来念一遍，都是真实返回。llm_used 是 true，说明这趟本机大模型也参与了 enrich，但每条风险依旧带规则引擎的 evidence，结论可独立复核。risk_count_by_level 告诉你高中低各几条，比一句含糊的「有风险」有用得多。

• doc_type 自动识别成 contract，分类这一步没靠人填。
• overall_risk_level 给到 High，因为命中了多条高危规则。
• risk_count_by_level 把风险按等级拆开，方便你先盯最要命的那几条。
• 风险清单里每条都带 category、level、issue、evidence、suggestion，拿去直接改合同都行。

5.3 企业知识问答，RAG 检索

RAG 这条路是文档切片、本地 Embedding、FAISS 向量库、检索增强问答。企业知识问答靠的就是它，问合同里某条条款、问标书里某个要求，它去库里捞最相关的原文回来。

这里有个很妙的点。Embedding 这一步，即便你没装任何语义模型，它也会自动切到 hashing-fallback，用确定性哈希把中文切词落进向量。所以 RAG 在最朴素的条件下也不会崩，只是检索从语义级退回到词级。

实测 4，以「这个合同的付款周期是多少、总金额是多少」发起检索。返回带 chunk_id 和 score 的原文片段，命中了合同金额和付款约定那几条。

检索出来的结果，后面可以接本地 LLM 去生成带引用的回答。这次实测我顺手看了最朴素的样子——检索这一步本身不依赖任何云端、也不依赖大模型，是本地 FAISS 干的活；而接上本地大模型生成答案时，llm_used 同样是 true，只是把检索结果讲得更顺。

5.4 中文 PDF 解析路径

真实企业文档大半是 PDF。我用一份本地生成的中文测试 PDF 走完整流程，看它能不能把中文吃进去、把风险吐出来。

生成 PDF 用了 fpdf2，指定了 simhei 中文字体，否则中文会是乱码方块。这一步本身也顺手验证了中文编码链路没断。

实测 5，生成中文 PDF（17506 字节）并审查。识别出文档类型，命中付款、保密、违约这些条款的风险，证明 PDF 解析到风险输出的链路在本地是通的。

这一节实际上把三条本地链路都验了，PDF 解析（pdfplumber、pypdf）、中文编码、规则引擎审查。三者串起来，才是一条能用的中文文档审查流水线。

5.5 Agent 工具调用，WorkBuddy 基线

作为生产力级 Agent 工具的接入基线，我直接调 Skill 暴露的命令行工具，模拟 WorkBuddy 那种「给路径加给类型」的最朴素调用方式。

analyze_document.py 和 search_document.py 这两个 CLI，就是 Agent 工具实际会戳的入口。它们在服务器外面独立跑，只跟本地服务说话。

实测 6：以 python tools/analyze_document.py --file examples/tender_sample.md --type tender 触发招标分析。输出完整 JSON：识别 9 项招标要求（REQ-001…REQ-009）、能力匹配度 0.0%、整体风险 High、风险分布 {Low:0, Medium:0, High:1}、llm_used=false。这证明 Skill 能被 Agent 工具以「给路径 + 给类型」的方式稳定调用，并产出可被 Agent 进一步消费的结构化结果。这正是赛事要求的「可被生产力级 Agent 工具作为基线验证」的能力。

这恰恰证明了一件事，Skill 能被 Agent 工具用「给路径加给类型」这种最朴素的方式稳定调用，不用 Agent 懂任何内部实现。这才是生产力级接入该有的样子。

5.6 本地大模型真实推理验证，OpenVINO GenAI 加 Qwen2.5-7B INT4 加 CPU

5.1 到 5.5 展示的，是本机大模型在线时跑出来的实测，llm_used 全是 true——规则引擎先打底、本地大模型再增强，一起上。但上面那些测试重点在验工程链路和规则覆盖，没把「本地大模型推理这条链路本身」单独拎出来验。这一节就补这一刀，把 OpenVINO 子进程、权重加载、确定性生成这条真·端侧推理链路，单独跑给你看。

切过去不用改任何业务代码。analysis_engine 在 use_llm 为真且本地模型可用时，自动调用 LLMService，后者通过 LocalLLMBridge 拉起子进程要推理。业务层根本不知道背后换了引擎。

模型只在子进程启动时加载一次，约几秒，4.4GB 权重常驻内存，后面请求复用，不会每次重新加载。法律审查追求确定性，所以生成时 do_sample 设成 False，同样的条款进来，结论稳定可复现。

子进程通信走 JSONL 行协议，请求是 system、user、max_new_tokens，响应是 ok 加 text。简单到甚至能用手敲，没有任何花哨依赖。

两处输出都是 Qwen2.5-7B 在 CPU 上真刀真枪生成的，不是我编的演示。下面两张截图也是本机运行服务的真实像素。

一张是 /api/providers 的返回，backend 是 openvino-genai，available 是 true，local_only 是 true。另一张是 /api/analyze 带 use_llm=true，返回 llm_used 是 true，说明这次结论真有大模型参与。

真实截图，/api/providers 返回 backend openvino-genai、available true、active true、local_only true。这是本地推理后端真在线的铁证。

真实截图，/api/analyze 带 use_llm=true 返回 llm_used true，summary 由本地 Qwen2.5 生成。证明降级路径之外，真·本地大模型这条路也通了。

把 5.1 到 5.6 串起来看，你就明白我为什么较真了。降级基线能干活，真模型来了更强，两条路文档都不出机，这才是完整的本地审查故事。

6. 风险都长啥样

把三类样例在规则引擎下的真实命中，汇总成一张分布图。横轴是文档类型，纵轴是高中低风险的条。

三类文档实测风险分布，本地规则引擎输出。合同 4 高 4 中，招标 1 高，技术方案若干安全性能风险。这张图不是装饰，是规则覆盖度的量化证据。

分布和第 5.1 节逐项输出完全对得上，可以当成规则引擎覆盖度的量化证据。你要质疑哪条，回 5.1 看它的 evidence 就行。

7. 什么时候才允许出机，以及怎么不出事

DocGuard AI 默认是本地优先，但通过受控的端云协同，能把摘要和问答能力再往上抬一抬。关键是这个协同是可选的、脱敏的、不替代本地审查的。

端云协同架构。安全总闸画在最前面，本地审查始终是第一道，云端只在你显式开启且数据脱敏后才参与。

安全上的约束，我归纳成四点。这四点不是写在文档里的口号，是代码里默认就锁死的。

1. 服务只绑 127.0.0.1，外网摸不进来，这是不出机的第一道闸。
2. 日志对手机号、身份证、邮箱、银行卡号自动脱敏，排查问题也不会把敏感信息写死在盘上。
3. 用户文件按用户隔离，不同人的文档不会串到同一个沙箱里。
4. 端云协同只以脱敏摘要级别调用，绝不把原文整篇丢出去，而且不替代本地审查的结论。

这也顺手回答了一个常被问的问题，用户怎么切到云端模型。在 config 里把 local_only 设成 False 并启用 cloud provider 即可，但默认是关的，得你主动开才出机。

8. 最后说两句

DocGuard AI 用了一种挺克制的工程方式，把企业文档智能审查这件通常得靠云端大模型的事，收拢回了一台 AI PC。模型真在本地跑，文件真不出机，审查、检索、报告一件不少。

• 它最让我踏实的一点，是两条命。没大模型时，规则引擎加哈希嵌入加 FAISS 照样能把活干成，结论带证据可复核。
• 有大模型时，它自己切到本地 Qwen2.5 推理，文档还是不出机，只是摘要和问答更顺。
• 所有实测都来自这台机器的真实终端，命令和日志全摊开给你，照着附录能一模一样复现，不靠我的嘴。
• 端云协同是可选的、脱敏的、不替代本地的，默认关着，得你主动开才出机。
• 对那些既要 AI 能力、又不能让数据出域的企业场景，DocGuard AI 给了一个能落地、能复现、能审计的答案。

说到底，本地部署不该是口号。它得在没模型时也能干活，有模型时也不出门，每一句结论都拿得出证据。这件事，我在这台机器上真做出来了，也欢迎你来验。