Ghostchars

ghostchars

查找并删除文本和文档中的不可见 Unicode 字符及机器写作标点。所有操作均在本机运行：无需联网、无遥测、无需账户，且零运行时依赖。

npx ghostchars clean -i notes.md          # clean a file in place, atomically
cat draft.md | npx ghostchars inspect     # what is hiding: line:col, codepoint, name
npx ghostchars check --bar text           # the gate: exit 1 if the tree is dirty
npx ghostchars report draft.md            # habits that make a draft read as machine written
npx ghostchars clean -i essay.docx        # documents too: .docx, .odt, .html

需要 Node 22 或更高版本。整个软件包由一个启动器和三个捆绑组件组成：CLI、文档读取器和 MCP 服务。除非指定文档或启动服务，否则只会加载第一个组件。

命令

clean 从标准输入或指定文件读取内容，将清理后的文本写入标准输出；使用 -i 时则原地改写各文件。使用 --check 时不写入任何内容，如果存在需要更改的内容则以状态码 1 退出。

inspect 列出每个可疑字符及其行号、列号、码点、Unicode 名称，以及会对其执行操作的标志。它不会更改任何内容，发现问题时以状态码 1 退出。

report 衡量会让草稿读起来像机器写作的特征：句子长度一致性、套话式过渡语、提示词、破折号密度、三分列举、模棱两可的措辞，以及缺少具体细节。它不是检测器，也不会输出概率。

check 按照设定标准检查整个目录树，并打印所有可能被更改的文件及准确字符位置。此命令适用于 CI 和 pre-commit 钩子。在 ghostchars.json 中配置检查范围和固定项。

mcp 在标准输入和标准输出上运行 Model Context Protocol 服务，让 Agent 可以将 clean_text、inspect_text、style_report 和 check_paths 作为工具调用，而不必通过 shell 执行命令。

help 打印命令列表，help <command> 打印指定命令的标志，help --json 则将完整接口打印为一份机器可读文档。 version 打印版本号。

标志

这 13 个清理开关的拼写和含义与 Python 参考 CLI 完全一致，因为它们底层使用的是同一套引擎。

标志	功能	不设为默认值的原因
（默认）	零宽空格、词连接符、字节顺序标记、软连字符、不可见数学运算符、双向覆盖符、游离标签字符、非字符、保留的默认可忽略码点，以及所有其他格式控制字符
-a、--aggressive	即使粘合字符承担重要作用，也将其移除	会破坏 emoji 序列、波斯语、印度语系文字和地区旗帜
-s、--spaces	将不换行空格和其他特殊空格替换为普通空格
-n、--newlines	将 CRLF、CR、NEL、LS 和 PS 替换为普通换行符	会更改换行符
--bidi	移除双向标记和隔离符，即使它们紧邻从右向左书写的文本	会破坏混合希伯来语和阿拉伯语文本
--controls	移除 C0 和 C1 控制字符，但保留制表符和换行符
--pua	移除专用区字符	会破坏图标字体字形
--punct	将 em dash、en dash、弯引号、省略号和减号替换为 ASCII 字符	这是排版问题，不是隐藏内容
--confusables	仅在混合文字系统的词语中，将外形相似的西里尔字母和希腊字母替换为拉丁字母	会改写字母；是否启用应审慎考虑
--nfc、--nfkc	在执行其他操作之前进行 Unicode 规范化	NFKC 会改写字母且不可逆
--gutters	移除终端在行首绘制的引用竖线（U+258C 至 U+258F、U+2502、U+2503）及其后的一个空格，同时保留缩进和框线表格行	目录树或绘制的方框也可能以相同的竖线开头
--trailing	移除每行末尾的空格和制表符	Markdown 硬换行
--collapse	将行内连续两个或更多空格替换为一个
--max	启用以上所有选项，但不包括 --nfc；--nfkc 会取代它

默认清理会根据上下文进行判断。它会移除两个拉丁字母之间的零宽连字符，但会保留家庭 emoji 或波斯语词语中的零宽连字符。它会移除游离标签字符，因为这类字符可用于将文本偷偷夹带到消息中；但会保留完整的地区旗帜。它会移除英文文本中的从左向右标记，但会保留希伯来语旁边的标记。-a 会关闭这种判断。

选项只能启用，不能关闭，因为参考 CLI 也不支持关闭选项。

三档规则

规则档是一组命名选项，让用户或 Agent 只需选择一个词，而不用设置 13 个布尔选项。

规则档	选项	适用场景
default	无	仅处理不可见字符。没有正当理由需要它们
text	-s --punct	处理任何供人阅读的内容。自己的文字应使用此档
max	--max 中的 12 项	处理所有内容，包括易混淆字符和 NFKC。会造成信息损失

选项的解析顺序固定，因此结果始终可预测：

1. 初始时关闭所有选项，
2. 应用 --bar，
3. 如果指定了 --max，则应用它，
4. 应用每个显式标志，这些标志只能开启选项。

因此，--bar text --collapse 等同于 -s --punct --collapse，而 --bar max --punct 仍然只是 max。

max 会折叠外形相似的西里尔字母和希腊字母，并应用会改写字母的 NFKC。不要用它处理非自己编写的文本。它根本不会作为检查规则档提供：请参阅下文的 check。

文档

clean 和 inspect 会根据扩展名识别文档，并以结构化方式处理。

扩展名	处理方式	额外标志
.docx	解压软件包，清理每个文本节点，然后重新打包	--metadata、--rsids
.odt	通过 ODF 部件进行相同处理	--metadata
.html、.htm	仅处理文本节点。标签、属性、脚本和样式不受影响
其他	纯文本

--as text 会强制将任何路径按纯文本处理，这也是 Python 参考 CLI 对 .html 文件的处理方式。

如果没有 -i，清理后的文档会写入原文件所在目录中的 <name>.clean<ext>，或写入通过 -o 指定的路径。

对文档运行 inspect 时，会先输出拼接后的文档文本的字符报告，然后报告文本周围隐藏的内容：隐藏文本段、白底白字和极小的文本段、修订记录、评论、不同 rsid 编辑会话 ID 的数量、元数据字段、宏和媒体。--metadata 会清空创作信息字段并删除自定义属性；--rsids 会移除编辑会话指纹。

隐藏文本段、评论和修订记录只会报告，不会删除。删除它们会改变文档，这应由人来决定。

此处不支持：PDF、图像、.pptx、.xlsx、.rtf、.doc、.epub 和 .pages。check 完全不会打开文档。

检查

ghostchars check [--bar default|text] [option flags]
                 [--config <path>] [--no-config]
                 [--git|--no-git] [--max-bytes N] [--limit N]
                 [--fix] [--json] [--verbose] [paths...]

--bar 只接受 default 和 text。有意不提供 max 级别：max 会启用针对目标文字和符号、而非排版的混淆字符检查和 NFKC 规范化；而会谴责正当西里尔文、希腊文和表情符号内容的检查级别，会被安装它的人删掉。默认级别设为 default，理由也相同：排版属于团队风格，必须由用户主动选择。

不指定路径参数时，check 会通过 git ls-files 查找文件，因此会遵循仓库现有的相同忽略规则，同时也能找到新建但尚未添加的文件。在仓库之外，或使用 --no-git 时，它会改为遍历目录树，并跳过 node_modules、构建输出、虚拟环境，以及名称以点开头的所有目录；但编码 Agent 读取指令的目录除外（.cursor、.github、.claude、.agents、.windsurf、.devin、.gemini、.codex、.clinerules、.continue、.kiro、.roo）。无论是否指定路径，--git 都会将不可用的 git 视为硬错误，这样 CI 就不会在不同容器之间悄然切换策略。路径参数始终通过遍历来查找，而不是在 git 中查找，因此 --git <paths> 表示断言 git 可用，并报告 "discovery": "walk"。结果按路径排序，因此输出不会受目录顺序影响。无法打开遍历目录时，会在 stderr 输出错误并以状态码 2 退出，绝不会静默跳过。

如果文件扩展名属于已知二进制类型、文件大小超过 --max-bytes（默认 2 MiB）、前 8192 字节中有任何一个是 NUL，或者文件不是有效的 UTF-8，则会静默跳过该文件，不会导致运行失败。命令行中指定的文件则不同：你已断言它是文本，因此这两项内容检查都不再适用，由严格解码来判定；解码失败会报错并以状态码 2 退出。

即使从其他位置运行，check <dir> 也会查找 <dir> 自身的 ghostchars.json：如果工作目录旁没有配置文件，搜索会从你指定的每个路径向上进行，并在该路径的仓库根目录处停止。由两个不同配置文件管理的两个路径会导致错误，因为一次运行只有一个根目录，而且 pin 是相对于该根目录编写的。--verbose 会显示使用了哪个配置文件。

ghostchars.json

将其放在目录树根目录，或通过 --config 指定。

{
  "version": 1,
  "surfaces": [
    {
      "id": "invisibles",
      "bar": "default",
      "include": ["**/*"],
      "exclude": ["vendor/**"]
    },
    {
      "id": "prose",
      "bar": "text",
      "include": ["**/*.md", "src/messages/*.ts"],
      "decodeEscapes": true,
      "pins": { "docs/glyphs.md": 12 }
    }
  ],
  "maxBytes": 2097152
}

surface 指定一个级别（或一个 options 列表，二者只能选其一）、覆盖范围内的 glob，以及它的 pins。不匹配任何 surface 的文件完全不会接受检查。排除规则优先于所有其他规则，包括你明确指定的路径。未知键会导致错误，并列出已知键，因此 pins 中的拼写错误绝不会被静默忽略。

glob 子集包括：** 表示任意数量的路径段，* 表示单个路径段中的任意数量字符，? 表示一个字符。不支持花括号和字符类。

decodeEscapes 会在检查文件之前，将 \uXXXX 和 \u{XXXX} 转换为它们表示的字符。对于字符串供人阅读的源文件，启用此选项；其他地方都应关闭：码点表中充满了用于匹配字符而非实际输出字符的转义序列。

Pins

pin 表示文件会按预期恰好变更 N 个字符。它会双向强制执行。

pin 值	检测结果	结果
无	0	通过，不显示信息
无	大于 0 的 N	FAIL changed，列出每个字符
N	N	通过
N	M，且 M 不等于 N	FAIL pin-mismatch：变更了 M 个字符，但 pin 恰好设为 N 个
大于 0 的 N	0	FAIL pin-stale：已标记为有意包含问题，但现在没有任何变更。取消 pin。

最后一行最容易被忘记。它能捕获有人悄悄修复文件后已经过时的 pin。

输出

docs/post.md: the text bar would change this file:
  docs/post.md:1:26 U+2014 EM DASH
      Ghostchars is a text tool<EM DASH>it finds what a reader cannot see.
  docs/post.md:2:43 U+200B ZERO WIDTH SPACE
      There is a zero<ZWSP>width space in this one.

ghostchars: 1 file would change, 3 scanned

这两个占位符表示实际字符。本文件本身符合 text 标准，因此会指出一个码位，而不是直接输出该字符。

每个违规字符输出一行 path:line:col U+XXXX NAME，每个不同的行号只输出一次对应的源代码行。退出码为 1。全部通过时，输出一行：ghostchars: 3 files pass the text bar。--verbose 还会列出通过检查的文件。

在 CI 中

npx -y ghostchars check --bar text

这就是全部步骤。在 CI 中绝不要传入 --fix。--fix 会就地清理未通过检查的文件，然后重新检查，这样一来，无人查看更改内容，失败的构建就会变成成功的构建。它还会跳过已固定的文件并列出这些文件，因为修复其中任何一个都会使其固定失效。

本地运行 --fix 后，请重新查看所有存在破折号问题的文件。清理工具会把两个词之间的 em dash 转成空格、连字符和空格，这样处理是正确的，但读起来不太自然。这些位置正是 JSON 输出中 rewriteSites 列出的位置。

--sarif 会将同一次运行的结果打印为 SARIF 2.1.0 日志：每个违规字符和每个固定失败各对应一条结果，包含其行号、列号和源代码行。GitHub code scanning 会在拉取请求中以内联形式显示这些结果：

- run: npx -y ghostchars check --bar text --sarif > ghostchars.sarif || true
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ghostchars.sarif

这里使用 || true，是因为退出码 1 表示发现问题，而上传步骤才会将其转换为注释。如果作业还必须失败，请另外保留一个普通的 check 步骤。--sarif 和 --json 是同一标准输出的两种格式，因此该命令不允许同时使用两者。

作为 pre-commit hook

integrations/pre-commit/pre-commit-config.yaml 是可粘贴到 .pre-commit-config.yaml 的代码块。它是一个 repo: local hook，使用 language: node，因此该框架会将固定版本的 npm 包安装到自己的环境中，不会克隆任何仓库。它会检查暂存的文本文件，并且与 CI 步骤一样，绝不会传入 --fix。

退出码

code	含义	来源
0	完成，无需报告	所有命令
1	发现问题、存在待更改内容或门禁失败	inspect、clean --check、check、report --fail-on
2	无法按要求完成运行：用法错误、文件无法读取或不是 UTF-8、配置有误、文档损坏、Node 版本低于 22	所有命令
3	内部错误，属于 ghostchars 中的 bug	所有命令

优先级严格适用，并会在多个输入间累积：3 高于 2，2 高于 1，1 高于 0。即使另一个文件存在问题，只要有一个文件解码失败，退出码就会是 2。

退出码为 3 时会输出一行；如果环境中设置了 GHOSTCHARS_DEBUG=1，还会输出堆栈跟踪。这样 Agent 可以区分“传错了标志”和“工具出故障了”，因为两者需要采取不同的后续操作。

标准输出遇到 EPIPE 时会静默以退出码 0 结束，因此 ghostchars inspect big.md | head 的行为与其他命令一致。

JSON 输出

clean、inspect 和 check 上的 --json 会向 stdout 精确打印一个 JSON 对象，不会输出多行流。以下四条规则均面向机器读取：ok 和 exitCode 既会出现在负载中，也会体现在进程状态中；计数位于列表之前，因此即使读取内容被截断，也仍能看到判定结果；达到上限时始终会设置 findingsTruncated 和 findingsTotal；键名使用 camelCase。

这三个命令开头都包含相同的五个标识字段，因此读取方无需查看其他内容，就能判断当前读取的是什么。

{
 "tool": "ghostchars",
 "version": "1.0.2",
 "command": "clean",
 "ok": true,
 "exitCode": 0
}

clean 和 inspect 后续会包含 bar、解析后的 options 列表、汇总所有输入的 summary，以及每个输入各一项的 results。clean 的结果包含 changed、各自的 summary、以码点为单位的 charsDelta、完整清理后文本（使用 -i 时替换为 written: true），以及 rewriteSites。inspect 的结果包含 clean、total、summary、byKind 汇总，然后是 findings；每项均包含 line、col、index、cp、u、name、kind、flag、action，且仅在发生替换时包含 replacement。

rewriteSites 是值得关注的字段。 它会精确列出短横线位于两个非空格字符之间的位置，也就是 --punct 会替换普通连字符的位置。这些句子应当重写，而不是直接接受。弯引号、省略号和不换行空格都能正确处理，且不会列出。

check 的后续内容有所不同，因为门禁没有单一的 bar：它包含 root、discovery、config、surfaces 数组（其中每个 surface 都带有各自的 bar、选项和计数），然后是 filesScanned、filesSkipped、filesFailing、包含 status 和 hits 的 failures，以及最多列出 50 项的 skipped 列表，同时包含 skippedTruncated 和 skippedTotal。

唯一的例外是：report --json 没有封装对象，键名使用 snake_case。 该输出与 Python 参考报告逐字节一致，包括将整数值的浮点数打印为 12.0 的方式，因此任一实现生成的负载都能与另一实现的输出干净地进行差异比较。只有一个结果时，会解封为裸报告对象；其他结果数量则会生成 {label: report} 映射。判断依据是 RESULTS 的数量，而不是文件参数的数量，因此即使传入两个文件且其中一个无法读取，仍会打印裸对象。

为 Agent 安装

只需 CLI 即可：任何能运行 shell 命令的 Agent 都可以运行 npx -y ghostchars check --bar text。以下文件让它无需每次都被要求执行。它们随软件包一起发布，因此全局安装后可从 $(npm root -g)/ghostchars/integrations/ 复制，本地安装后则可从 node_modules/ghostchars/integrations/ 复制。 integrations/README.md 中包含各工具对应的复制命令。

钩子。 integrations/hooks/ 是一个 Claude Code PostToolUse 钩子，会将 Agent 写入或编辑的每个文件置于文本栏限制之内，并将检查结果作为反馈返回，让模型在同一轮中修正问题。它绝不会重写文件。将脚本复制到 .claude/hooks/，并将设置片段合并到 .claude/settings.json。

技能。 integrations/skills/ghostchars/ 是一个目录，其中包含 SKILL.md 和两个参考文件。将它复制到 .claude/skills/ghostchars/ 和 .agents/skills/ghostchars/，或者复制到其中一个目录，再为另一个目录创建符号链接。只需复制一次，即可支持 Claude Code、Codex、Cursor、带 Copilot 的 VS Code 和 Gemini CLI。这是这里最有价值的文件：它会告诉 Agent 何时运行工具，更重要的是，如何处理每一种检查结果。

始终生效的规则块。 integrations/rules/ 中包含可粘贴到 AGENTS.md、CLAUDE.md 和 GEMINI.md 的简短内容块，以及适用于 Cursor、Windsurf 和 Copilot 的现成规则文件。技能按需加载，而这些规则始终处于上下文中。Windsurf 不支持技能，因此它的规则文件就是完整的集成方案。

MCP 服务。 integrations/mcp/ 中包含每种宿主对应的配置片段。添加后，Agent 将获得四个只读工具（clean_text、inspect_text、style_report、check_paths），且输入和输出均经过类型定义；对于偏好使用结构化工具的宿主，这样可以省去一次 shell 调用和一次 JSON 解析。第五个工具 clean_files 会写入磁盘，且仅在使用 --allow-write 时注册。

三种方式任选一种，也可以全部采用。它们互不冲突。

与 Python 参考 CLI 的差异

黄金测试夹具会对所有文本夹具和所有选项组合逐字节验证 clean 和 inspect，并对 report --json 验证其精确字节。以下都是刻意设计的差异，测试会逐一验证。

行为	Python	ghostchars
长选项缩写，--punc 代替 --punct	接受	未知标志，退出码为 2，并指出最接近的已知标志
解析错误时的用法文本	argparse 换行后的文本块	单行提示、建议，以及指向 help --json 的指引
文件缺失或无法读取	回溯信息，退出码为 1	{path}: no such file or directory，退出码为 2
原位写入	截断并写入	临时文件、fsync、复制权限模式、解析符号链接后重命名
clean 中的 .html 和 .htm	作为纯文本清理，包含标记语言	按结构清理；--as text 可恢复旧行为
无法识别的扩展名	报错 unsupported type	纯文本
report 的人类可读输出	使用间隔号和短横线分隔	ASCII，使用 , 和 to。report 的字节一致性由 --json 保证
对无法读取的文件运行 report	打印异常，始终退出 0	打印消息，退出码为 2
内部错误	回溯信息，退出码为 1	单行错误，退出码为 3；设置 GHOSTCHARS_DEBUG=1 时输出堆栈
stdout 遇到 SIGPIPE	输出消息，退出码为 120	静默退出，退出码为 0
使用 --nfc 或 --nfkc 时的发现项	使用独立代码路径，绝不交叉引用	clean --json 会扫描原始文本中的发现项，因此规范化后的字符可能显示为 found-not-targeted。清理后的文本才是最终依据
Unicode 数据库未命名的码位对应的 NAME 列	<unnamed>	如果 C0 或 C1 控制字符有标准别名，则显示其别名（BELL、NEXT LINE）；否则显示 U+XXXX

最后一行与表格中的其他行方向相反：这是本工具输出多于参考实现，而非少于参考实现的唯一之处。Unicode 字符数据库中命名的每个码位在此处的名称都完全相同，包括易混淆字母；一项测试会双向比较全部 1508 个有名称的易混淆字符与 unicodedata，因此缺少名称或名称错误都会导致失败。

这里新增、Python 中没有对应功能的内容：--bar、--json、--stdin-name、--as、--limit、--fail-on、--fix、整个 check 命令，以及 mcp 服务。

关于原子写入，有两点值得注意：实际写入会更改文件的 inode，因此指向它的硬链接会失效；如果写入过程中崩溃，原文件旁会留下 .ghostchars-*.tmp 文件，而不会截断原文件。如果文件内容无需更改，就绝不会以写入方式打开，因此其修改时间和 inode 都会原样保留。

此工具无法做到的事

• 统计水印，例如 SynthID-Text 或 KGW。它们存在于词语选择中，而非字符中。只有改写才能触及它们。
• 文体检测。 词汇、节奏和结构。report 会衡量其中一些相同的习惯，以便你进行编辑，但它不是检测器：它不会输出概率或分数，也绝不会判断文本是否由 AI 生成。
• **PDF、图像、.pptx、.xlsx、.rtf、.doc、.epub、.pages 和 Google Docs。EXIF、XMP 和 C2PA 需要使用其他工具。
• 删除隐藏在文本周围的内容。 隐藏片段、评论和修订记录只会报告，不会删除。
• check 以外的转义序列。 如果源文件中的 U+2014 EM DASH 写作反斜杠 u 转义序列，除非 ghostchars.json 表面启用了 decodeEscapes，否则将无法识别；对于提取本工具无法解析的编程语言中的字符串字面量，也没有相应功能。
• 在 check 或通过 MCP 处理文档。 遍历代码库的门禁不会打开 zip 归档。
• 任何网络操作。 此软件包不包含网络代码，也不包含遥测功能。