01
把《党政机关公文格式》国标变成可执行代码：gongwen-kit 让公文出稿当场过三道机检
垂直行业工具
Agent Skill
GB/T 9704-2012
本地离线
首版 2026-10-13
24★ / 5 Fork
一句话结论：把“公文版式国标”从人力经验变成机器规则，写稿人只管内容、数字对不对得上交给机检——这是党政机关与央国企最刚性的场景里，第一份开源可复现的实现。
01｜案例是什么？
gongwen-kit 是一个 Node.js 工具包（同时是一个 Agent Skill）。它做三件事：生成——按 GB/T 9704—2012《党政机关公文格式》产出标准 Word 公文（通知、报告、请示、函、纪要、管理办法、条例），包含红头、发文字号、签发人、版记、附件页等全部构件；机检——每份稿子写盘后自动跑三道机器检查（体例 / 数字自洽 / 文风），哪一道不过就非零退出，不算出稿；修复——手写的、旧模板出的、别人发来的 .docx 也能整份修，版式直接改、体例改动写成 Word 修订痕迹逐条接受或拒绝、数字问题只插批注不替人改数。整个过程完全在本机跑，安装后不联网。
02｜为什么今天值得关注？
- 为什么是现在：2026-10-13 首次开源，当天 8 次提交、连出 v0.2.1 → v0.3.1 四个版本（GitHub 提交与 Release 时间戳已逐条核对），说明不是“一次性 Demo”，而是一天内被真实使用反馈推着迭代。
- 以前为什么不容易做：公文工具长期卡在两处——版心、红头、双线这类尺寸“看着差不多”，但差 0.5mm 就不符合国标且没人能证明；改别人的稿子只能靠人工重排，无法把改动变成可审计的修订痕迹。这两件事都要落到 OOXML 层面才有解。
- 为什么现在变得容易：①
docx / jszip / sax 这类库已能精确控制 Word 底层结构；② Agent Skill 形态成熟，工具可以挂进 Claude Code / OpenCode / Codex 等宿主，由模型负责“写内容”、代码负责“量尺寸”；③ 涉密与内网合规让“本地离线”从加分项变成硬门槛，而本项目的定位正是“文件进文件出、不联网”。
03｜案例的前世今生
前世。GB/T 9704—2012 是 2012 年发布的国家标准，配套依据还包括《党政机关公文处理工作条例》（中办发〔2012〕14 号）以及 GB/T 15834（标点）、GB/T 15835（数字用法）等。十几年来，公文排版的主流解法是“WPS/Word 模板 + 人力校对”：模板解决版式，错字与体例靠人一页页看；数字对不对得上（正文说“以下三点”只列了两点、表格合计与分项不符、同一指标多处取值不一致）几乎全靠经验。
发展。过去几年，大厂与开源项目在“按国标排版”和“查错别字”上都有投入——作者自己在 README 里承认“有的版式比本仓全”，并附了一张横向对比图（标注来源为各厂商官网与公开资料、2026-10-13 核对、厂商口径）。这条赛道的缺口不在版式，而在跨段落的“数字自洽”检查和把修改变成可审计的修订痕迹。
今生。2026-10-13，作者 imhuhe 把仓库首版开源（MIT），并在同一天把这两件事都做进了仓库：checks/check-num.js 做数字自洽（分段求和、比率行列不加总、跨表同一指标、正文列举条数），lib/fix/revisions.js 把体例修正写成 Word 修订。关键尺寸不再是“目测”，而是用渲染后量测脚本出数：版头标志上缘距版心 35.05 mm（标准 35）、信函双线长 170.01 mm（标准 170）——量测脚本与全部校准值都写在 docs/版式.md。
下一步可能怎么发展（以下为分析 / 推演，非事实）：① 接入内网或本地部署模型，让“起草 + 排版 + 机检”整条链不出网，这是涉密单位唯一能接受的形式；② 机检报告落盘成合规凭据、对接 OA 流转审批；③ 从“单机工具”变成“部门级文书质量门禁”。
04｜原始资料
05｜作者是谁？
GitHub 账号 imhuhe，个人资料显示昵称/姓名栏为“黄河 HUANGHE”，自述“从事投融资和产业项目，正在构建个人 AI 体系”，博客 mrhuanghe.com；账号注册于 2020-04-23，公开仓库 6 个，Followers 0（截至 2026-10-14）。提交署名出现 huanghe。这更像产业侧从业者自建工具并开源，而非职业开源开发者或大厂团队。
不猜的部分：其具体单位、职务、是否有团队协作，仓库与个人资料都未说明，本报告不作推断。仓库当前公开信息中，贡献者数量、CI 运行结果均可在仓库自行核对。
06｜解决了什么真实问题？
从用户需求出发，而不是从 AI 技术出发——三类人每天被同一件事消耗：
- 机关与事业单位的文书岗：一份通知退回来，往往不是内容不行，而是版心、层次序数、发文字号括号用错（该用〔〕写成【】）、成文日期编了虚位（“05 月 08 日”应为“5 月 8 日”）。改一处就要重排一遍。
- 央国企的部门写稿人：日常最多的是非红头的企业内部报告、请示、工作方案。这类文书没有现成模板，格式全靠“前人留下的稿子”抄，抄错就一错一片。
- 所有需要“数字对得上”的人：正文写“以下三个方面”，后面只列了两点；表格合计与分项对不上；同一指标在正文与表格取值不一致。这类错人力最容易漏，也最容易被上级一眼抓住。
再加一条隐性刚需：涉密材料不能上传到云端工具。本项目的“本机运行、安装后不联网”直接命中了这条边界。
07｜完整技术栈
| 运行时 | Node.js ≥ 18（CI 覆盖 Node 18 / 20 / 22 × Windows / macOS） |
| 依赖 | docx ^9.7.1、jszip ^3.10.1、sax ^1.6.0（仅这三个生产依赖） |
| 语言 | JavaScript（仓库主语言），另有 Python 量测/复检脚本 |
| 可选依赖 | Python + pymupdf（仅用于导出 PDF 后核字体与版面） |
| 模型 | 本工具本身不调用任何模型；由宿主 Agent 决定“起草正文”时用哪个模型（README 明确：内容去哪由你用的模型决定） |
| 框架 / API | 无 Web 框架、无外部 API、无 MCP（纯文件进出） |
| 数据库 | 无。全部为本地文件（.docx / .json / .tsv） |
| 数据文件 | data/style-words.tsv（文风词表）、data/yixingci.tsv（异形词表，依据 GF 1001-2001） |
| 部署 | 无需部署；git clone + npm install 即用；作为 Skill 时软链到 ~/.claude/skills/ 或 ~/.codex/skills/ |
| 字体 | 标题与发文机关标志默认“方正小标宋简体”，需自行安装（未安装有替代方案，见 docs/字体.md） |
08｜完整 Workflow
入口 A · 起稿：node tools/new-doc.js --form wen --out 稿子.js（行文体）或 --form zhang（条文体/办法条例）
↓
写正文：只调构件——letterhead、title、zhusong、p、h1～h4、table、luokuan、fujian、fuzhu、fujianPage、banji；不手拼 docx 元素（这一步可由 Agent 完成）
↓
出稿：node 稿子.js → 写盘成 .docx
↓
自动三道机检：体例（GB/T 9704 版心、层次序数、日期与发文字号、全半角）→ 数字自洽（表格合计/百分比构成/跨表同一指标/正文列举条数）→ 文风（异形词、中文里的半角标点、套话空词）
↓
闸门：任一道不过 → 非零退出，不算出稿；「提示」档问题不拦稿，由人核对
↓
交付：.docx 给用户；需要 PDF 时在 Word 里导出，可选跑 tools/check-pdf.py 核字体与版面
↓
入口 B · 修复现成文件：node tools/fix-doc.js 某文件.docx → 输出 某文件-修订.docx（原文件不动）→ 在 Word「审阅」里逐条接受/拒绝修订，批注单独看
09｜它到底是怎么实现的？
- “版式可证明”靠量测，不靠目测。
tools/measure-banji.py、measure-letterhead.py、measure-xinhan.py 在 Word 渲染出 PDF 后测量实际尺寸，把校准值写进 docs/版式.md；遇到字体回退（没装方正小标宋）时脚本拒绝出数，避免用错基准。
- 修复分三档，是刻意设计的安全边界。
lib/fix/ 下 ooxml.js / runs.js / layout.js / revisions.js / comments.js / text-rules.js 各管一层：版式直接改；体例与规范层文风写成修订痕迹；数字与需要判断的项只插批注。“全部拒绝修订，正文逐字等于原文”——作者把可逆性写成了硬约束。
- 机检用“双向标本”防误报。每条规则都配一份“必错的标本”做负对照（规则报不出来测试就失败），靠标签匹配、可能误报的规则只提示不拦稿，另有“必过的标本”防误报。这是工程质量意识，而不是堆规则。
- 内容判断交给人。README 明确边界：不做内容与政治表述校对，不做 OFD、印章图像、流转审批。数字一律不自动改——“合计错还是分项错，工具判断不了”。
核心技术取舍：它选择了“文件进文件出”而不是“服务端处理”。代价是不能做协同与流程，收益是涉密材料不出本机。在中国政务/央企场景，这个取舍几乎是唯一的正确答案。
10｜手把手复现
以下 Step 1–4、Step 6 为公司 README 公开步骤的整理；Step 5、Step 7 为本文的复现建议，并非作者原始步骤。
# Step 1（作者原文）：克隆并安装
git clone https://github.com/imhuhe/gongwen-kit.git && cd gongwen-kit
npm install
# Step 2（作者原文）：一键验证——生成七份样张，每份跑完三道机检；再跑全部必错/必过标本
npm test
# 产物在 samples/word/，用 Word 打开即可
# Step 3（作者原文）：起一份自己的稿子
node tools/new-doc.js --form wen --out 我的稿子.js # 行文体；条文体用 --form zhang
# Step 4（作者原文）：编辑 我的稿子.js（照 templates/complete.js 调构件），然后出稿
node 我的稿子.js # 写盘后自动跑三道机检，全绿才算过
# Step 5（本文复现建议）：拿一份本单位的真实旧稿试“修复”
node tools/fix-doc.js 旧通知.docx # 输出 旧通知-修订.docx，原文件不动
# 用 Word 打开 → 审阅 → 逐条接受/拒绝，观察批注里标出的数字问题
# Step 6（作者原文）：只体检不改（把机检当 CI 用）
node checks/check-doc.js 某文件.docx --strict # 体例
node checks/check-num.js 某文件.docx --strict # 数字自洽
node checks/check-style.js 某文件.docx --strict # 文风
# Step 7（本文复现建议）：把机检接进目录级批量流程
# 遍历某目录下所有 .docx → 逐个跑三条 --strict → 汇总成 CSV 报告（谁不过、过什么）
# 这是把它从“个人工具”变成“部门质量门禁”的最小一步
11｜Prompt / Code / Config
作者公开了完整的 SKILL.md（含要素速查与构件用法）、模板源码与机检脚本。以下为原文提取（SKILL.md 摘要）：
# 公文要素速查（GB/T 9704—2012）—— 摘自 SKILL.md
- 要素顺序：版头（份号／密级／紧急程度／发文机关标志／发文字号／签发人／红色分隔线）
→ 标题 → 主送机关 → 正文 → 附件说明 → 发文机关署名和成文日期 → 附注 → 版记
- 层次序数四层，h1～h4 自动编号：一、／（一）／1.／（1）
- 成文日期用阿拉伯数字标全；月、日不编虚位（10 月 5 日，不是 05）
- 发文字号：机关代字〔年份〕序号号；顺序号不加「第」字、不编虚位
- 主送机关顶格、末尾全角冒号；正文每段左空二字
- 结尾用语：请示用「妥否，请批示」，报告用「特此报告」
- 勿手拼 docx 元素、不写 new Paragraph；所有构件的用法一页看全：templates/complete.js
配置方面没有环境变量、没有 API Key——这是它最“反常”也最讨喜的地方。作为 Skill 使用时只需一次软链：
ln -s "$(pwd)" ~/.claude/skills/gongwen-kit # Claude Code
# Codex 换成 ~/.codex/skills（作者标注：未实测）
12｜踩坑
仓库 GitHub Issues 为 0 条（截至 2026-10-14 核对），因此这里的坑来自作者自己的提交信息与文档，不是社区反馈。
- 字体问题最容易翻车。标题与发文机关标志默认方正小标宋简体，需自行安装；样张 PDF 是在“没装该字体”的机器上出的，用 Songti SC Black 代替。回退字体时量测脚本会拒绝出数——如果你打算自己改版式，先解决字体，否则量不出可信的尺寸。
- 首行缩进是连锁反应。v0.3.1 专门修了这个问题：默认样式加首行缩进后，主送机关、居中/右对齐段落、表格、文本框、红头都需要补“首行不缩进”。自己改样式时会撞到同一堵墙。
- 不要把“提示”当“报错”。数字机检分拦截项与提示项；提示项（如正文取值对照）在“不同主语、不同口径”时属于正常，不必为了消提示改写原文。
- 量版式前先读 docs/版式.md。作者的原文提醒：校准值与坑都在那里。
13｜中国用户能不能直接做？
| 国内访问 | 代码托管在 GitHub，视网络条件；项目本身不需要访问任何外部服务，拿到代码后完全离线运行 |
| 注册 | 不需要注册任何账号；不需要 API Key |
| 成本 | 0 元（不含让 AI 起草时的模型费用）。无云服务、无按次计费 |
| 技术门槛 | 🟡 有一定门槛需要 Node ≥ 18、会用命令行与 npm install；想完全合规出红头还需自装方正小标宋简体 |
| 数据合规 | 本机运行、安装后不联网，排版与机检不调用任何服务；只有“让 AI 起草正文”那一步的内容会发给所选模型服务商（作者已在 README 明确提示涉密材料应自写或接内网/本地模型） |
14｜国产替代方案
| 原方案定位 | 本身就是国产方案：GB/T 9704 国标 + 本地运行 + MIT 开源，不存在“要替代谁”的问题 |
| 模型侧（起草正文） | 作者未点名任何模型，仅说明“内容去哪由你用的模型决定”。因此模型侧可换成 DeepSeek / Qwen / GLM / Kimi / 豆包（或内网部署的模型）——属理论可行、需自测，不是作者已验证的兼容清单 |
| 宿主侧 | 已验证：Claude Code、OpenCode（作者写明“读同一个目录约定”）；作者标注未实测：Codex（~/.codex/skills）。WorkBuddy 等支持本地 Skill 目录的宿主理论上可同样接入（本文判断，未实测） |
| 同类替代 | 市面若有版式更全的商业/开源公文工具，可作为互补；本项目 README 自己承认这一点，并强调增量在“数字自洽”与“修订痕迹” |
15｜中国企业可以怎么用？
- 场景 1｜党政机关 / 事业单位的文书岗：把
check-doc.js --strict 当“发文前最后一道闸”，退稿率直接下降。对一批历史公文跑一遍，能一次性摸清本单位最常犯的体例错。
- 场景 2｜央国企集团与三级单位：集团统一
templates/ 与文风词表，下属单位出稿必过机检——这是“公文质量门禁”的低成本实现，且完全不涉及数据出网。
- 场景 3｜所有有内控制度的单位：用
fix-doc.js 批量修复旧模板产出的存量文件，改动以修订痕迹留痕，可以当作修改审计凭据——这一点在需要通过内审、外审的场景里价值很高。
16｜中国消费者可以怎么用？
- 备考公考 / 事业单位的考生：用
npm test 生成七份标准样张当“国标范本”对照练习；自己写的练手稿跑一次机检，比对着参考答案更清楚错在哪。
- 单位里的秘书 / 行政 / 办公室人员：把别人发来的通知、报告拖进
fix-doc.js，先修格式再报领导，省掉来回返工。
- 做公文写作内容的人：机检输出的错误类型（异形词、半角标点、序数错、数字不自洽）本身就是最好的选题库——每一条规则都能做成一条短视频。
17｜如何变成一个赚钱的项目？
- 产品化：把它包成“部署在内网的公文排版+机检服务”，前端只留上传框——目标客户是绝不能上云的单位。核心难点不是技术，而是涉密资质与交付合规。
- 服务化：面向集团单位做“公文版式规范化 + 存量文件批量修复”项目制交付，按单位/按文件量计费。
- 咨询化：帮助企业梳理“哪些环节该机检、哪些必须人判”，并把这套判断固化成规则文件——咨询的产物是可运行的规则，不是 PPT。
- 培训化：“公文格式 + AI 工具实操”是本项目最自然的课程形态（见第 21 节），面向机关、国企办公室、行政岗，需求极其稳定。
- 内容化：“公文退稿的 10 个高频错误”“〔〕和【】到底怎么用”这类内容天然有流量，且可以用本工具当场演示。
- 行业化：同一套方法可迁移到高校/科研院所申报材料、律所函件、医疗行政材料（见第 20 节）。
18｜变现路径
| 路径 A · 内网工具 | 客户：党政机关、央国企、涉密单位 产品/服务：私有化部署的公文生成与机检服务 收费方式：项目制 / 年度服务费 难度：高（需资质与合规交付） |
| 路径 B · 规范改造服务 | 客户：集团总部办公室、下属单位 产品/服务：公文版式规范化 + 存量文件批量修复 收费方式：按单位 / 按文件量 难度：中 |
| 路径 C · 培训 | 客户：机关与国企办公室、行政人员、公考考生 产品/服务：半天工作坊 / 线上课 收费方式：按人 / 按场 难度：低 |
| 路径 D · 咨询 | 客户：有内控与审计要求的单位 产品/服务：公文质量门禁方案设计 + 规则固化为机检 收费方式：项目制 难度：中高 |
| 路径 E · 内容/IP | 客户：公考人群、行政从业者 产品/服务：公众号/短视频/社群/工具导航页 收费方式：广告、课程、社群 难度：低 |
必须区分：本项目没有公开任何已验证的收入或付费客户。以上全部为基于案例结构推导的潜在商业模式，不是已实现的商业结果。
19｜如果我是一个中国独立开发者｜7 天 MVP
- Day 1：跑通
npm test，把七份样张生成出来，逐个打开对着国标看一遍——先确认你信得过它的输出。
- Day 2：拿本单位/熟人单位的真实模板，改成
templates/ 里的一个新模板，出稿过机检。
- Day 3：接国产模型（如 DeepSeek / Qwen 兼容端点）负责“起草正文”，代码负责“排版 + 机检”，打通一句话到一份稿。
- Day 4：写批量脚本：目录里所有 .docx → 三条
--strict 机检 → 汇总 CSV 报告。
- Day 5：做“修复演示”：准备 3 份典型烂稿（旧模板、手写、别人发来的），跑
fix-doc.js，看修订痕迹是否可逐条接受/拒绝。
- Day 6：录一条 3 分钟 Demo：从一句话需求 → 出稿 → 机检全绿 → Word 里看修订。视频就是你的销售材料。
- Day 7：找 2 家单位免费试用（一个机关、一个国企），只要他们给你 3 个真实文件 + 一句反馈，你的报价依据就有了。
提醒：本案例最大的商业风险不是技术，而是客户属性——政务与涉密客户对供应商资质有硬要求。个人开发者更现实的切口是“培训 + 规范改造服务”，而不是直接卖内网系统。
20｜如何迁移到其他行业
① 高校 / 科研院所申报材料、评审意见、管理制度文件的格式规范化；机检可以直接对应“材料形式审查”清单。
② 律所 / 会计师事务所函件、法律意见书、审计报告的形式合规自查；修订痕迹留档正好对应执业留痕要求。
③ 医疗行政 / 等级评审医院规章制度、评审材料的体例统一与数字自洽检查（“应当”条数与实际条目对不上是评审高频失分点）。
21｜培训课程设计
| 课程名称 | 《AI 公文实战：让国标帮你排版，让机检帮你查数》 |
| 适合人群 | 机关/事业单位文书岗、国企办公室行政、集团总部文秘、公考备考者 |
| 建议时长 | 30 分钟 Demo / 60 分钟 Workshop / 半天（3 小时）实战课 |
| 30 分钟 Demo | 一句话 → 出一份合规通知 → 现场故意改错（把〔〕写成【】、写“05 月 08 日”）→ 看机检精准报错。全场只需要演示“机检能报出来”这一件事。 |
| 60 分钟 Workshop | 学员自带电脑，安装 Node，跑 npm test 生成样张；再用自己的真实稿子跑一次 fix-doc.js，在 Word 审阅里逐个接受/拒绝修订。 |
| 半天课程 | 上午：GB/T 9704 关键条款（版头、发文字号、序数四层、成文日期、版记）+ 机检三档；下午：搭自己的模板 + 批量机检脚本 + 小组互评真实稿子。 |
| 课程目标 | 学员最终能够：① 独立生成一份合规公文；② 用机检自查并解释每一类错；③ 把本单位模板固化进工具。 |
| 现场 Demo | “退稿率实验”：取 5 份真实历史稿，跑机检，统计命中率——用真实数据开场，比讲功能有说服力。 |
| 学员练习 | 每人带 2 份自己的稿子：一份用于生成训练，一份用于修复训练。 |
| 课后作业 | 用本工具把本单位一份存量公文规范化，并提交机检报告截图。 |
| 企业迁移 | 企业版课程：把“公文质量门禁”接进现有 OA / 发文流程，输出一份可执行的规则清单。 |
22｜培训师点评
真正值得教的不是工具，是它的设计判断：把行业规则（国标）翻译成可执行、可验证、可回滚的代码；用“证据”代替“感觉”；不碰需要人负责的判断。这三条方法，换成施工规范、财务制度、医疗病案，一样成立。
23｜最终判断
说明：以上为案例属性描述，不是“最佳案例排名”。
02
阿里把浏览器做成 AI 的本地工作台：轻舟 qz-browser-agent 开源，自带模型、数据不出本机、还能通过 MCP 把浏览器借给别的 Agent
大厂开源 · 浏览器 Agent
Chrome 扩展（MV3）
Apache-2.0
本地优先 · BYO Model
MCP Bridge
首开源 2026-10-12 · v0.1.0
40★ / 8 Fork
一句话结论：浏览器正在从“人看网页的窗口”变成“Agent 干活的执行层”；阿里用一份 Apache-2.0 的开源扩展给出了国内大厂的第一份完整答卷——本地登录态 + 你自己的模型 + 可复用 Skill。
01｜案例是什么？
轻舟（qz，qingzhou）是阿里巴巴开源的 Chrome 扩展（Manifest V3），把浏览器变成 AI 可操作的“研究工作台”。它能：看 DOM 或截图操作页面、填表单、跨标签页协作、并行跑子任务并在执行中随时打断或补上下文；把表格、媒体、网页内容抽成本地结构化数据集，在侧边栏里预览、编辑、导出；用 Skill 在目标网页里跑 JavaScript（可打包指令、脚本、工具、自定义界面，甚至按站点自动启用）；模型自己选（任何支持工具调用、协议兼容的服务商，含本地模型服务）；可选 MCP Bridge 把浏览器工具与任务控制开放给外部 Agent。所有会话、Skill、采集数据都存在浏览器本地。
02｜为什么今天值得关注？
- 为什么是现在：仓库 2026-10-12 首次开源（初始提交 09:54:22 UTC），同日发布 v0.1.0（11:40:11 UTC）；10-13、10-14 连续提交（依赖与安全扫描修复、CI 跨平台加固、测试夹具加固）。这不是“挂了半年突然被发现”，而是两周内的新事件。
- 最近发生了什么变化：模型侧，“OpenAI 兼容 / Anthropic Messages + tool calling”已成事实标准，接自家模型变得极其便宜；浏览器侧，Chrome 的扩展权限与 CDP（
chrome.debugger）足以支撑“真操作页面”而不是“点截图”；合规侧，企业对“浏览器自动化但登录态与数据不上云”的要求越来越硬。
- 以前为什么不容易做：云端 Browser Agent 的通用做法是把浏览器托管在服务器上——数据出网、登录态托管、按次计费，且遇到验证码/复杂交互容易栽。本地做又缺三样：能真操作页面的权限通道、能落地的结构化数据层、能被外部 Agent 复用的接口。
- 为什么现在变得容易：轻舟把这三样一次补齐——CDP 页面操作、本地 Data 表、MCP Bridge。并且它是扩展形态：不用 Docker、不用一台服务器、不需要把账号交给第三方。
03｜案例的前世今生
前世。“让模型点网页”这件事最早由 Python 侧跑通（Playwright / browser-use 一类）：无头浏览器 + 截图或可访问性树 → 模型决定动作。它能跑，但对普通用户不友好：要装环境、登录态难维护、数据在服务器上。
发展。随后出现两个分叉：一是协议化——把浏览器能力做成 MCP 工具，让任意 Agent 调用（Claude 侧 DevTools MCP 是代表）；二是本地化——把 Agent 放进用户自己的浏览器里，复用已登录的会话，模型由用户自带。轻舟明确站在第二个分叉上，并且把第一个分叉也接了进来（MCP Bridge）。
今生。2026-10-12，阿里把轻舟以 Apache-2.0 开源，仓库挂在 alibaba 组织下，附带少见的完整文档矩阵：docs/architecture.md（运行时映射与任务生命周期）、docs/benchmarks.md（基准与可视化回归方法）、docs/permissions.md（19 项权限逐条说明用途）、docs/providers.md（如何加模型服务商）、AGENTS.md（开发规则）。代码量约 14MB（JS 6.3MB / TS 5.7MB / Python 1.46MB，1821 个文件），MCP Bridge 是独立 Python 服务。
关联信号（非同一项目，勿混淆）：同期阿里云在云栖大会上联合英特尔发布“Agentic Browser”——把 Chromium 的 Blink/V8 面向 Agent 场景裁剪调优、以预编译 SDK 交付、跑在弹性基础设施上，支持一次拉起上百个浏览器实例，并提出“首次用 Agent 推理、跑通后沉淀为可复用 RPA 流程”的成本思路；官方口径称单实例内存最多降约三成、单任务成本可降百倍量级（该量化口径为厂商自述，第三方分析明确提示需真实业务压测验证）。轻舟与 Agentic Browser 是两个不同的东西（一个在本地端侧，一个在云侧集群），但指向同一判断：浏览器是 Agent 的执行层。
下一步可能怎么发展（以下为分析 / 推演，非事实）：① 能力包与 Skill 生态长起来，出现“行业 Skill 包”（招投标、比价、情报）；② 企业版：内网私有模型 + 私有 Skill + 权限策略；③ 端云协同：本地轻舟做“人机协作与登录态”，云侧做规模化并发。
04｜原始资料
05｜作者是谁？
主体：阿里巴巴（GitHub 组织 alibaba），仓库以 Apache-2.0 开源。该组织同期还有 open-code-review（46,966★）、spring-ai-alibaba（11,008★）等活跃仓库，说明这是组织级正式发布，不是个人马甲。
提交者：截至 2026-10-14，仓库贡献者列表只有一位——helei-qz，8 次提交；提交署名同时出现「何磊」与「Lei He」（同一人，中英文提交环境不同）。
不猜的部分：团队规模、项目立项背景、以及轻舟与阿里云 Agentic Browser 的组织关系，公开资料均未说明，本报告不作推断。若把“唯一提交者”当成“唯一作者”会低估阿里内部协作的可能性——这两件事无法从公开数据区分。
06｜解决了什么真实问题？
从企业与个人的实际工作出发：
- “网页上的活”没有 API 可调。绝大多数网站（供应商报价页、政府公开信息、电商后台、行业名录）只做人看的界面。企业要做竞品监控、价格采集、信息汇总，只能靠人一页页复制。
- 买 RPA 太贵也太脆。传统 RPA 靠写死的选择器，页面一改就崩；维护成本比人工还高。
- 用云端 Browser Agent 心不安。数据出网、登录态托管在别人服务器上、按次计费——这三条在多数中国企业里过不了安全评审。
- 最痛的一步其实在“落地”。很多工具能把信息“看到”，但抽出来的结果留在对话里或截图里，不能编辑、不能导出、不能给下一道工序用。轻舟把抽取结果直接放进本地 Data 表，这一步才是真正省人的地方。
07｜完整技术栈
| 形态 | Chrome 扩展，Manifest V3 |
| 运行时分区 | Background service worker（任务状态与持久化）/ Side Panel（呈现）/ Content script（隔离世界读写页面 DOM）/ Offscreen + Sandbox（DOM 相关工作与隔离 Worker）/ 本地服务（MCP Bridge） |
| 页面操作 | 通过 chrome.debugger（CDP）操作页面、截图、检查请求、打印 PDF；scripting 注入内容脚本 |
| 模型 | 自带（BYO Model）：支持具备工具调用能力、协议兼容的服务商，含本地模型服务；文档与代码中的服务 ID 保留了 alibaba-cn（对应国内服务「百炼」）与 moonshotai（对应国内 Kimi 服务）的稳定性约定；另有 provider-codex 实现（自带 Responses 适配器与 OAuth 设备登录） |
| 协议 | OpenAI Chat Completions 兼容 / Anthropic Messages / 自定义 endpoint |
| 扩展机制 | Skill（在目标网页跑 JS，可按站点启用）+ TypeScript 能力包（新增 Agent 工具、面板视图、设置页、模型服务商） |
| MCP | 可选 MCP Bridge：独立 Python 服务（qz-browser-agent-mcp-bridge），支持 Streamable HTTP 与 stdio；Bearer 认证 + 配对 token；仅绑定 loopback；对自定义路由校验 Host/Origin，只对合法 Chrome 扩展来源返回精确 CORS origin |
| 存储 | 浏览器内本地存储（storage + unlimitedStorage）：会话、Skill、采集数据集；无外部数据库 |
| 部署 | 下载 release ZIP → chrome://extensions 开发者模式 → 加载已解压扩展；或源码构建（Node 24 LTS + npm ci + npm run build）；不需要 Docker，不需要云服务器 |
| 测试 | TS 类型检查 + 自动化测试与覆盖率（npm run verify）；视觉/交互基准（锚点漂移 ≤1px、稳定暂停期 ≤0.5px、截图差异预算 0.1% 等健康门槛）；MCP Bridge 侧 pytest |
08｜完整 Workflow
入口：用户在侧边栏下任务（例：“打开 example.com，把页面主标题提取到一张表格中”）／或外部 MCP 客户端经 Bridge 触发
↓
Background API：解析并关联请求（提交时按 clientMessageId 去重，重试复用已受理消息）
↓
Session 命令队列 / 监督器：每个 Session 串行；启动一次 run 或把消息排队；初始会话写入成功后才回执
↓
Agent host：装载仓库、模型/工具服务与写租约（一次 run 捕获其语言、工具目录与运行配置）
↓
Agent 取上下文：输入、页面内容、文件内容、Skill/MCP 资源（经共用安全检查）
↓
模型网关：按会话配置选服务商与模型（含限速治理与恢复策略）
↓
工具运行时：页面工具（DOM / 截图 / 表单 / 跨标签页）→ CDP / Content / Chrome 服务
↓
完整轮次提交：打断（steering）只在完整轮次边界进入；排队的后续消息按 FIFO 启新 run
↓
事件投影 → 侧边栏渲染：Agent 事件流入运行时与对话投影；agent_end 触发资源清理与终端持久化
↓
输出：本地 Data 表（可预览 / 编辑 / 导出）、文件与 Artifacts、对话记录
09｜它到底是怎么实现的？
- “页面操作”与“任务编排”是分开的两层。Background 拥有任务状态与持久化、Side Panel 只负责呈现，两者通过显式协议通信；工具处理函数跑在后台 service worker，可把动作或脚本执行委派给活动标签页。好处是：页面崩了、标签页关了，任务状态还在。
- “写租约 + 每 Session 串行”解决并发乱写。命令进入监督器的按 Session 队列，一次 run 拿到写租约才允许提交——这是并发正确性的工程解法，也是多数玩具级 Agent 缺的东西。
- 用 CDP 而不是纯截图。走
chrome.debugger 能操作页面、截图、检查请求、打印 PDF，比“截屏+猜坐标”稳定得多。
- 抽取结果必须“落得下来”。表格、媒体、页面内容进入本地集合，可在侧边栏预览、编辑、导出——把“一次性问答”变成“可复用的数据资产”。
- MCP Bridge 是双向的、且默认最小暴露。只绑定 loopback、Bearer + 配对 token、校验 Host/Origin、扩展端拒绝 HTTP 重定向并在配对撤销后丢弃迟到的轮询命令。设计取向很明确：不为了便利牺牲边界。
- 权限面是显式的。
docs/permissions.md 逐条列出 19 项权限的用途与主要调用方（含 debugger、<all_urls>、history、bookmarks）——这在开源扩展里并不常见，是给企业安全评审看的。
最关键的一处取舍：坚持“本地优先 + 自带模型”意味着放弃了开箱即用——用户必须自己准备模型服务与 Key。换来的东西很值钱：数据不出本机、登录态不出浏览器、成本由自己的模型决定。
10｜手把手复现
以下 Step 1–4 为官方 README 公开步骤的整理；Step 5–6 为源码构建与 MCP Bridge 的官方文档步骤；Step 7 为本文的复现建议，并非作者原始步骤。
# Step 1（官方）：下载最新 release 的 ZIP 安装包
# https://github.com/alibaba/qz-browser-agent/releases/latest
# Step 2（官方）：解压，然后打开 chrome://extensions，启用「开发者模式」
# Step 3（官方）：点「加载已解压的扩展程序」，选择解压出的 qz-browser-agent-extension 文件夹
# Step 4（官方，最简路径）：从扩展工具栏打开「轻舟」侧边栏
# → 设置里选服务商、填凭证（自定义接口还要填 URL 与协议）
# → 选模型并保存
# → 试一句：打开 example.com，把页面的主标题提取到一张表格中。
# Step 5（官方）：从源码构建（需要 Node.js 24 LTS + npm）
npm ci
npm run build
# 然后按 Step 3 加载 dist/extension/ 作为扩展目录
# Step 6（官方）：起 MCP Bridge，让外部 Agent 用你的浏览器
# 先生成一个随机 token（如 openssl rand -hex 32），两边填同一个值
QINGZHOU_MCP_BRIDGE_TOKEN="<random-pairing-token>" \
uv run --project services/mcp-bridge \
--index https://pypi.org/simple \
--default-index https://pypi.org/simple \
--locked \
qz-browser-agent-mcp-bridge --transport streamable-http --print-snippet
# 在 MCP 客户端里配置：
# [mcp_servers.qz-browser-agent]
# url = "http://127.0.0.1:18765/mcp"
# bearer_token_env_var = "QINGZHOU_MCP_BRIDGE_TOKEN"
# 把 --print-snippet 打印的配对片段贴进扩展 DevTools 控制台完成配对
# Step 7（本文复现建议）：做一个「同一个站点的可复用 Skill」
# ① 选一个你每天都要看的页面（例：某行业名录 / 招投标公告列表）
# ② 让 Agent 跑一次抽取，确认结果进入本地 Data 表、能导出
# ③ 把这次的操作沉淀成站点 Skill，之后同站点自动启用
# ④ 用 MCP Bridge 让外部 Agent 定时触发，或改用加 alarms 权限的定时任务
# ⑤ 一周后统计：省下多少人工、抽出来的表能不能直接给下游用
11｜Prompt / Code / Config
官方示例 Prompt（README.zh-CN 原文提取）：
打开 example.com，把页面的主标题提取到一张表格中。
扩展如何被“扩展”——能力包入口是官方文档给出的最小契约（原文提取）：
// src/capabilities/<your-feature>/index.ts
export { default as tools } from "./tools.js"; // Agent 工具
export { default as renderers } from "./renderers.js"; // 工具结果视图
// 构建时会自动发现这些声明。Tool handler 跑在后台 service worker，
// 可把操作或脚本执行委派给活动标签页；Renderer 在侧边栏挂载可交互结果卡片。
模型服务商接入的三档粒度（docs/providers.md 原文要点）：① 沿用已有协议的服务 → 只贡献一个 presets 映射；② 已有服务需要额外行为 → 贡献显式 override: true 的 preset；③ 新的请求或流式协议 → 实现 ProviderAdapter 并贡献 providers 映射。
需说明：上述 Prompt 与代码片段均为作者公开内容；本报告未虚构任何作者未给出的配置。轻舟的 docs/providers.md 特别提示：能力包 API 仍属实验性，兼容性约定见 CONTRIBUTING 的扩展契约。
12｜踩坑
仓库 Issues 为 0 条（截至 2026-10-14 核对），所以下面这些坑来自官方文档与第三方独立分析，而非社区反馈：
- Node 版本是硬门槛。构建需要 Node.js 24 LTS。第三方独立审计明确指出：其环境里是 Node 22 而非要求的 24，因此没能跑完整的 JS 测试套件；同时区分了“文件数量”和“通过的断言数”——不要把仓库的规模当成质量证明。
- 是开发者模式加载，不是商店安装。这意味着扩展会随 Chrome 更新/策略变化而需要重新加载；企业统一分发需要自行打包策略。
- 权限面很宽，安全评审会问。包含
debugger、<all_urls>、history、bookmarks、unlimitedStorage、desktopCapture 等 19 项。文档把用途写清楚了，但“写清楚”不等于“被接受”——企业落地前务必先过一遍 docs/permissions.md。
- 没有公开的对比基准结论。第三方分析的原话值得引用：当前 commit 无法支撑任何关于抽取准确率、Agent 成功率或速度优势的主张；
docs/benchmarks.md 自陈给的是“协议与工具”，不是已公布的结果。所以任何“比 X 快 N 倍”的说法都不该从这份仓库里读出来。
- 能力包 API 仍标为实验性：深度定制（尤其涉及 provider 与工具注册）要做好跟随上游变化的准备。
- MCP Bridge 的 token 管理要小心。官方提醒：token 只放本地配置、从共享日志里打码；换 token 必须重新配对。
13｜中国用户能不能直接做？
| 国内访问 | 仓库与 Release 在 GitHub，视网络条件；扩展本体与 MCP Bridge 都在本机运行，装好之后不依赖境外服务 |
| 模型 | 自带模型：任何支持工具调用、协议兼容的服务商。代码中保留了国内服务（alibaba-cn「百炼」、moonshotai「Kimi」）的稳定服务 ID 与凭证去向约定。具体哪些国内模型已端到端跑通，仓库未给出实测清单——属“官方支持 + 待自测” |
| 注册 | 不需要注册第三方账号；需要自行准备所选模型服务商的 API Key |
| 成本 | 软件 0 元（Apache-2.0）；成本主要在模型 token，具体价格由所选服务商决定，本报告不代为估算 |
| 技术门槛 | 🟡 有一定门槛装扩展本身很简单（点四下）；要做 Skill / 能力包 / MCP Bridge 则需要前端与 Python 基础 |
| 合规优势 | 会话、Skill、采集数据都存在浏览器本地；不把登录态交给第三方服务器。这是否满足你所在单位的要求，需要结合实际数据分级判断 |
14｜国产替代方案
这个案例的位置比较特殊：它本身就是“国产替代”的供给方。所以这里反过来看“它能替代谁 / 谁替代它”。
| 它可替代 | 云端无头浏览器类 Browser Agent（数据出网、登录态托管的那类）——结构性替代（同目标、不同形态），但官方未发布任何对比数据，不构成性能优于的结论 |
| 模型侧替换 | 原方案允许自带任意兼容模型。切换为 DeepSeek / Qwen / GLM / Kimi / 豆包：属理论可行、需自测；代码中明确保留国内的 alibaba-cn、moonshotai 服务 ID 与凭证去向约定，可作为“官方支持国内服务”的证据 |
| 规模化替代 | 需要一次跑几十上百个并发任务时，端侧扩展并不合适——那是云侧浏览器集群（如阿里云 Agentic Browser 方向）的场域。两者是互补而非互斥 |
| 工具链替代 | 如果诉求只是“自动化操作网页”而不需要 Agent 推理，传统 RPA（含国产 RPA 厂商）在稳定性上仍有优势；轻舟的加法是“不确定性交给模型”，代价是引入了模型的不确定性 |
15｜中国企业可以怎么用？
- 场景 1｜电商 / 零售的竞品与价格巡检：把每日要看的几个竞品页面做成站点 Skill，一条指令抽成表，导出 CSV 交给运营。数据留本地，不必上传第三方。注意：抓取他人网站需自行遵守目标站条款与法律边界，本报告不提供规避手段。
- 场景 2｜市场 / 投研的信息作业：把一次完整的“搜 → 打开 → 抽 → 存 → 引用”流程沉淀成一个可复用 Skill，每周复用，把重复劳动从“每次重做”变成“跑一次”。
- 场景 3｜企业 IT 与运营：把内部系统里没有 API 的重复网页操作（报表下载、批量录入、单据核对）交给会话式 Agent，模型可指向内网部署的服务，数据不出内网。
- 场景 4（合规留痕）：用 MCP Bridge 让外部 Agent 触发浏览器任务，把“谁触发了什么、抽了什么”留在固定流程里，比人工复制粘贴更可审计。
16｜中国消费者可以怎么用？
- 把长网页 / 复杂表格抽成结构化数据：学生整理文献表格、求职者整理招聘信息、装修比价——抽出来直接编辑导出，不用在截图和笔记之间来回倒。
- 跨标签页批量整理信息：“把这 8 个页面的关键字段各抽一行合成一张表”，一次交给它做完。
- 把自己常做的网页操作做成 Skill：每天要查的几个站点，做成站点 Skill 自动启用——这是“个人自动化”的最低成本入口。
17｜如何变成一个赚钱的项目？
- 产品化：不做通用工具，做垂直 Skill 包——例如“招投标信息每日雷达”“跨境电商竞品 Listing 巡检”“区域政策与补贴信息跟踪”。用户买的是现成的表，不是浏览器扩展。
- 服务化：企业浏览器自动化实施交付——调研流程 → 写 Skill → 接模型 → 部署 → 培训使用方；按项目收费，后续收维护费。
- 咨询化：“哪些网页流程值得自动化、哪些不该碰”的判断本身值钱（含合规边界与反爬风险的判断），交付物是流程清单 + 可运行 Skill。
- 培训化：“浏览器 Agent 自动化实战”——从装扩展到写出第一个行业 Skill，半天可讲完，学员当场能跑出自己的表。
- 内容化：browser agent 系列教程天然有热度（“让 AI 替你点网页”），可以做成公众号/B站/短视频系列，用真实任务做演示。
- 行业化：同一套 Skill 方法复制到招投标、跨境、金融合规、地产、招聘（见第 20 节）。
18｜变现路径
| 路径 A · 垂直 Skill 包 | 客户：电商运营、外贸、投研、招投标岗 产品/服务：行业专用抽取/巡检 Skill 包 收费方式：买断 / 订阅 / 按数据量 难度：中 |
| 路径 B · 实施服务 | 客户：有大量无 API 网页流程的企业 产品/服务：流程调研 + Skill 开发 + 部署 + 培训 收费方式：项目制 + 维护费 难度：中高 |
| 路径 C · 培训 / Workshop | 客户：企业数字化部门、独立开发者 产品/服务：浏览器 Agent 实战课 收费方式：按人 / 按场 难度：低 |
| 路径 D · 咨询 | 客户：要立项 AI 自动化的企业 产品/服务：自动化机会盘点 + 合规边界评估 收费方式：按天 / 项目制 难度：中 |
| 路径 E · 内容 / IP | 客户：AI 从业者、自动化爱好者 产品/服务：教程 / 社群 / 模板库 收费方式：课程、会员 难度：低 |
必须区分：v0.1.0 项目没有公开任何商业化案例、付费客户或收入数据。以上全部为基于案例结构推导的潜在商业模式，不代表已经验证的商业成功。另需重点提示：用浏览器自动化采集第三方网站数据，需自行遵守目标网站条款与相关法律，本报告不提供任何规避技术保护措施的方法。
19｜如果我是一个中国独立开发者｜7 天 MVP
- Day 1：装扩展（下载 ZIP → 开发者模式 → 加载），接一个国内模型（百炼 / DeepSeek 等兼容端点）的 Key，跑通官方那句 prompt，确认能抽出表。
- Day 2：选一个你熟悉的行业站点（招投标 / 政策 / 行业名录），写第一个站点 Skill，把列表页抽成表。
- Day 3：补“闭环”：定时触发 + 导出 CSV / 落到本地文件，让它可以无人值守跑一次。
- Day 4：接 MCP Bridge，让外部 Agent（Claude Code / Codex 等）能调你的浏览器任务——这一步是后面卖“服务”的技术基础。
- Day 5：把 Skill 打包成“行业雷达包”（固定字段、固定输出格式、加一页说明），做成可交付物。
- Day 6：录 3 分钟 Demo：输入一句话 → 出表 → 导出。视频标题直接写客户关心的结果，不写技术。
- Day 7：找 3 个目标行业的人免费跑一周，只收一句话反馈和一个问题：“如果它每月多给你 10 小时，你愿意付多少？”
风险提示：① 目标站点的反爬与条款边界，必须逐站确认，不要默认“能抓就抓”；② v0.1.0 的 API 稳定性有限，深度定制的代码要准备跟随上游演进而改；③ 不要承诺“一定能赚钱”，本报告只描述可能路径。
20｜如何迁移到其他行业
① 招投标 / 资质信息监测各地公告分散在不同平台、无统一 API；做成站点 Skill 后每日抽表，是典型的“时间换钱”场景。
② 跨境电商选品与 Listing 巡检竞品页、评论、价格、库存的结构化跟踪；抽出的表可直接进选品流程。
③ 金融 / 合规公开信息采集留档公告、监管信息按固定字段留痕，配合导出与本地存储形成可审计链路。
21｜培训课程设计
| 课程名称 | 《浏览器 Agent 实战：把你的网页重复劳动交给 AI（轻舟 qz 上手 + Skill 开发）》 |
| 适合人群 | 企业 IT / 数字化部门、运营与市场岗、独立开发者、对自动化感兴趣的产品经理 |
| 建议时长 | 30 分钟 Demo / 60 分钟 Workshop / 半天（3 小时）实战课 |
| 30 分钟 Demo | 现场装扩展 → 接一个国内模型 → 一句“把这张页面的表格抽出来” → 导出 CSV。全程只演示一件事：不用写代码也能拿到结构化数据。 |
| 60 分钟 Workshop | 学员各自选一个自己每天要看的页面，在讲师指导下做成站点 Skill，跑通一次并导出。 |
| 半天课程 | 上午：浏览器 Agent 的工作原理（DOM vs 截图、CDP、为什么本地优先）；下午：Skill 开发 + 能力包入门 + MCP Bridge 让外部 Agent 调用 + 合规边界讨论。 |
| 课程目标 | 学员最终能够：① 独立完成安装与模型配置；② 写出一个站点 Skill 并导出数据；③ 讲清楚本地优先方案与本地上云方案的取舍。 |
| 现场 Demo | “人工 vs Agent 计时赛”：同一个抽取任务，学员手工做一遍，Agent 做一遍，当场对比耗时。 |
| 学员练习 | 把“自己每周花 1 小时以上的网页重复操作”写成一句话需求，课堂做出来。 |
| 课后作业 | 交付一个可复用的站点 Skill + 一段 1 分钟录屏说明它省了什么。 |
| 企业迁移 | 企业版：盘点内部无 API 的网页流程，输出自动化机会清单 + 3 个可落地 Skill + 权限与合规评估。 |
22｜培训师点评
值得教的不是“让 AI 点网页”，而是三层工程判断：什么该交给模型（不确定性）、什么必须写死（并发与状态）、什么绝不能替用户决定（对外部网站的合规边界）。能讲清这三层，学员做出来的才是能上生产的东西。
23｜最终判断
说明：以上为案例属性描述，不是“最佳案例排名”。项目处于 v0.1.0，能力包 API 被作者标为实验性，落地前请按第 12 节的坑逐条评估。