LingSpark · 灵光
给 AI 代理写的中文文档，装一道"编译器"。
让 Claude Code、Codex 这类代理写需求文档、技术方案、汇报材料时，它每写完一个文件，lingspark 就自动检查一遍：数字前后对不上、说"三点"只列了两点、引用了不存在的章节、空话套话、指代不明……发现问题就退回去让代理改，改完才算交稿。
状态：v0.1 预览版。确定性检查和 Claude Code 接入已在真实环境使用；其余代理按官方文档适配、尚未实测。见现状。
English summary
结束之前，lingspark 在 docs/退货流程优化.md 中还有 2 个问题需要处理：
1. 第 3 行 [D111] 正文说「有三点」，但下面的列表有 2 项。建议：把数字改成实际的项数，或者补齐列表。
2. 第 9 行 [S204] 这段主要是空话套话，读者得不到具体信息。建议：写清楚具体做什么、做到什么程度、怎么衡量。
为什么需要它
让模型"写完自己检查一遍"并不可靠：写的和查的是同一个模型、同一段上下文，它很容易认可自己刚写的东西。lingspark 把检查放到代理外面，而且把"这段写得好不好"这种开放问题，拆成大量可以设门槛、可以重复的封闭问题：
- 确定性检查（不调用任何模型，毫秒级）：数值前后不一致、计数不符、悬空引用、占位符残留、必备章节缺失……
- 语义检查（逐段问模型"是/否"）：这段有没有指代不明的代词？有没有用"因此"引出一个前面找不到依据的结论？——每个问题都有明确的判断标准、反例清单和置信度门槛，模型把握不够时不报。
这个思路受 TypeSafe AI 的 Jev 启发：不让模型写评语，只让它回答带概率的封闭问题。
它怎么接进代理
lingspark 以 hook 的形式挂在代理上，代理不需要"记得"调用它：
- 代理每写完一个文件 → lingspark 跑快速检查，把错误告诉代理（不打断它）。
- 代理准备结束这一轮回答 → lingspark 跑完整检查（含语义检查）。还有错误就拦住，要求先改。
同一个问题只提醒一次；代理认为是误报时，要向用户说明理由，不能自己加注释绕过。所有环节出错时一律放行：lingspark 自己坏了，绝不会卡住你的代理。
| 代理 | 支持程度 |
|---|
| Claude Code、Codex、Cursor、WorkBuddy | ✅ 支持，一键接入。Codex 需要在 Codex 里用 /hooks 信任一次 |
只支持这四个。其他代理（Qoder、CodeBuddy、Trae 等）不会被自动接入。
安装
目前支持 Apple 芯片（M 系列）的 Mac。从 Releases 下载：
| 文件 |
|---|
| 客户端（推荐） | lingspark-…-mac-arm64.dmg，下载约 25MB，拖进"应用程序"即可 |
| 命令行版 | lingspark-macos-arm64，不需要另外装 Node |
Mac 客户端没有自带浏览器内核，窗口用的是系统自带的网页组件，所以装好只占约 100MB，其中绝大部分是
检查程序自己的运行环境。
预览版还没有做代码签名，第一次打开会提示"Apple 无法验证"：点"完成"（不要点"移到废纸篓"），然后到"系统设置 → 隐私与安全性"，在"安全性"一栏点"仍要打开"并输入开机密码。macOS 15 起右键 →"打开"已经不能跳过这一步。命令行版可以执行 xattr -d com.apple.quarantine ./lingspark-macos-arm64。
也可以从源码构建（需要 Node 22+ 和 pnpm 9）：
pnpm install && pnpm run build:sea # 命令行版：packages/cli/sea/lingspark
pnpm --filter @lingspark/desktop dist # Mac 客户端（要装 Xcode 命令行工具）：packages/desktop/release/
快速开始
图文版的完整步骤和演示视频见 使用指南网站。
下载后，两种方式任选一种，都是一步配好：自动找到你电脑上装过的代理并把检查接进去。之后代理写的每一篇
Markdown 文档都会被检查，不用选文件夹。
方式一：客户端。打开 LingSpark：
- 打开首页的开关
- 按提示重新打开你的代理（Codex 还要在里面输入
/hooks 信任一次）
方式二：一条命令。在项目文件夹里运行：
./lingspark setup
配好之后新开一个代理会话（代理只在会话开始时读取设置），照常让它写文档就行。
也可以让代理帮你装，把下面这段话发给它：
帮我安装 lingspark：从 https://github.com/rytesdd/lingspark/releases 下载适合我电脑的版本，然后在当前项目里运行 lingspark setup，把输出告诉我。
随时可以用 lingspark doctor 自检，用 lingspark check <文件> 手动检查一篇文档。
- 只装某一个代理：
lingspark install --agent claude-code（--dry-run 只看改动不写入；原配置会先备份）
- 代理写出的 Markdown 文档都会检查，不用选文件夹；代理自己的记忆、计划和指令文件（
CLAUDE.md、AGENTS.md、.claude/、.codex/、.cursor/ 等）除外。
- 想只查某些目录、或者给文档分类型，在项目里放一个
.lingspark/config.yaml：
# .lingspark/config.yaml
version: 1
include: ["docs/**/*.md"] # 默认是全部 Markdown
doc_types:
"docs/prd/**": prd # 需求文档会检查必备章节
"docs/design/**": tech-design
- install 和 setup 都会把 lingspark 复制到数据目录，hook 运行的是那一份，所以之后移动或删除下载的文件都不影响。
语义检查：谁来审
空话、指代不明、两篇文档说法矛盾这类问题，要读懂意思才判断得了。默认的做法是对话内自审：Agent 一轮结束时，LingSpark 把审稿标准（每条规则的是非题和"哪些不算"）发给正在写文档的这个 Agent，它自己审一遍，有把握的直接改，拿不准的问你，最后交一份简短的结果。不用登录，不用另装模型，四家代理装上就能用。
代价是审的人就是写的人。想要更客观，可以改成在后台另起一个模型来审（auto：谁写谁审，另起一个同款 Agent；或指定下表里的某一个）。在用户级配置里改：
用户级配置位置：~/Library/Application Support/lingspark/config.yaml
judge:
backend: session # 默认：对话内自审
| backend | 说明 | 需要 |
|---|
session | 对话内自审（默认） | 不需要任何东西 |
auto | 后台另起一个同款 Agent 审：Codex 写的由 Codex 审，Claude Code 写的由 Claude Code 审 | 那个 Agent 的命令行能在后台登录使用；Codex 直接可用 |
codex-cli | 借用本机已登录的 Codex（ChatGPT 订阅即可） | Codex 命令行，或 macOS 上的 ChatGPT 桌面版 |
agent-cli | 借用本机已登录的 Claude Code | 在终端里登录过的 claude 命令行 |
anthropic | Claude API，默认 Claude Haiku 4.5 | ANTHROPIC_API_KEY |
openai-compatible | 任何兼容 OpenAI 的接口，包括国产模型和本机的 Ollama | judge.endpoint、judge.model，远程接口需要 OPENAI_API_KEY 或 OPENROUTER_API_KEY |
typesafe | Jev API | TYPESAFE_API_KEY |
API key 也可以放在数据目录的 credentials.yaml 里。后台借用本机代理的方式比较慢（每个问题十几到几十秒），所以只在代理结束一轮时跑，写文件时不跑；问过的段落会缓存，不重复问。
评测不同模型：每条语义规则都带有正反例，可以横向比较：
./lingspark eval --backend codex-cli --backend anthropic:claude-sonnet-5
隐私
- 只读代理写出的文档。代理写了哪个 Markdown 文件就检查哪个，不会去扫你电脑上的其他文件；代理自己的记忆和指令文件不读。跨文档比对也只在同一次会话写的文档之间进行。
- 确定性检查完全在本机。只有语义检查会把段落发给你选定的模型服务。
- 出站记录：每次发出的请求都记在数据目录的
logs/outbound.jsonl，只记哈希和字节数，不记正文和 key。
- 离线模式：
offline: true 时，只有本机地址（如 Ollama）能被调用，其余一律在发出前拦下。
- 项目配置不能改请求发往哪里：
judge.endpoint 和 judge.command 只认用户级配置。这样克隆一个不可信的仓库，也不会把你的文档和 key 发到它指定的地方。
lingspark mine 会读取代理的会话记录来挖掘你的修改意见，只在你手动运行时才读。
规则
| 编号 | 规则 | 级别 | 方式 |
|---|
| D101 | 数值不一致 | error | 确定性 |
| D102 | 术语不一致 | warning | 确定性 |
| D103 | 悬空引用 | error | 确定性 |
| D104 | 必备章节缺失 | error | 确定性 |
| D105 | 标题层级跳跃 | warning | 确定性 |
| D106 | 中英文标点混用 | warning | 确定性 |
| D108 | 占位符残留 | error | 确定性 |
| D109 | 重复段落 | warning | 确定性 |
| D110 | 空章节 | warning | 确定性 |
| D111 | 计数不符 | error | 确定性 |
| S201 | 指代不明 | warning | 语义 |
| S202 | 句子成分残缺导致歧义 | warning | 语义 |
| S203 | 翻译腔、欧化句式 | warning | 语义 |
| S204 | 空话套话 | warning | 语义 |
| S205 | 段落内自相矛盾 | error | 语义 |
| S206 | 主语或话题中途偷换 | warning | 语义 |
| S207 | 结论没有依据 | warning | 语义 |
| S208 | AI 腔修辞 | info | 语义 |
| S209 | 章节内容与标题不符 | warning | 语义 |
规则都是 YAML（packages/rules-builtin/rules/），每条带至少 5 个正例和 5 个"看起来像但其实不是"的反例，这些例子同时是自动测试。语义规则上线的门槛是：反例零误报、正例召回不低于 60%，达不到的只以影子规则运行。
个别地方不想被检查时，可以用注释关掉：<!-- lingspark-disable-next-line D101 -->；整篇文档关掉，在 frontmatter 里写 lingspark: false。
现状
已完成：确定性检查、语义检查、五种模型后端、缓存与离线模式、Claude Code / Codex / Cursor / WorkBuddy 的 hook 安装与自检、对话内自审、Mac 客户端、模型横向评测、会话记录挖掘（Claude Code）。
还没做：
- 周报与自动回测：从你的修改意见里总结出候选规则，回测后交你审核上线
- 自动更新、macOS 签名与公证、Intel Mac 与 Windows 版
欢迎提 issue 和 PR，尤其是：你在真实文档里遇到的误报（附一段脱敏后的原文）、新代理的 hook 接入实测。
开发
pnpm install
pnpm run ci # lint + typecheck + test
pnpm run build:sea # 单文件程序
DECISIONS.md 记录了主要的设计决策和理由。语义规则的测试回放的是 packages/rules-builtin/fixtures/replay/ 里录好的模型回答，CI 不联网；改了语义规则后用 lingspark eval --record 重录。
致谢
许可证
Apache License 2.0。可以免费使用、修改、商用；再分发本软件或基于它的作品时，须按协议第 4 条保留 NOTICE 里的署名。
English summary
LingSpark (灵光, "a flash of inspiration") is a linter for Chinese Markdown documents written by AI coding agents (Claude Code, Codex, Cursor and WorkBuddy). It installs as an agent hook (lingspark setup, or double-click it for a setup page): after the agent writes a document, lingspark checks it and, if there are errors, blocks the agent from finishing its turn until they are fixed.
- Deterministic rules (no model calls): inconsistent numbers, "three points" followed by a two-item list, dangling references, leftover placeholders, missing required sections, and more.
- Semantic rules: each paragraph is judged with closed yes/no questions (ambiguous pronouns, empty buzzwords, conclusions without support, content not matching its heading), with explicit criteria, counter-examples and a confidence threshold. Pluggable backends: your signed-in Codex or Claude Code CLI, the Claude API, any OpenAI-compatible endpoint (including local Ollama), or Jev.
- Checks what the agent writes, nothing else: every Markdown file an agent writes, wherever it is, minus the agent's own memory and instruction files; cross-document checks compare the documents written in the same session. A project can narrow the scope with
.lingspark/config.yaml.
- Fail-open everywhere, offline mode, and an outbound log that records hashes and sizes only.
Status: v0.1 preview. User-facing messages are in Chinese. Licensed under Apache 2.0; redistributions must keep the attribution in NOTICE.
