mcpField
P
plain-language

plain-language

github.com/ggwicz文档处理81 次安装
代码仓库

关于 plain-language

plain-language 是一项只读文档审查技能，依据 pl-01 至 pl-33 规则检查项目文本，并在单一计划文档中给出经核验的改写建议。它区分可验证问题与主观意见，不会修改被审查文件。

主要功能

  1. 01按规则目录审查文本
  2. 02区分可验证问题与意见
  3. 03核对引用并验证改写
  4. 04仅生成单一计划文档
  5. 05只读审查，不改源文件

适用场景

  1. 01审查项目文档的可读性
  2. 02为文本问题整理改写建议
  3. 03核验审查发现的出处
  4. 04分阶段处理大量文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ggwicz/skills --skill plain-language

安装后在 Claude Code 中输入/plain-language确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
active-voice-guide.md
adversarial-review-prompt.md
before-and-after-examples.md
final-plan-format.md
rules-quick-ref.md
severity-rubric.md
word-substitutions.md

详细介绍

根据 pl-01..pl-33 规则目录审查项目文本，并生成一份包含经核实的改写建议的问题清单文档。此技能以只读方式审查文件：只提供建议，不会编辑文件。状态文件仅用于你自己的续接工作，不供人工审阅。

在宿主的待办工具中镜像以下四个阶段，让用户看到进度。

不可妥协的要求（请先阅读）

  • 绝不修改已审查的文件。 问题清单和改写建议只能写入计划文档。
  • 仅在明确调用时运行。 只有用户调用 /plain-language 时才运行此技能，绝不自动启用。
  • 为每项发现分类为 FALSIFIABLE（引用特定行上的确切文本，可通过 Grep 确认）或 OPINION（关于语气、受众适配度、歧义的判断，取决于具体解读）。
  • 将每条 FALSIFIABLE 引用与所引用文件进行 Grep 核验，确认后才能将其纳入草稿。未匹配 → 丢弃该发现，并计为一条已丢弃的幻觉。
  • 只生成一个输出文件。 汇总计划是面向用户的唯一产物；运行结束时的回复只能指出该文件的路径，绝不能提及状态文件或中间细节。

范围

  • 审查： .md、.mdx、.markdown、.txt、.rst、.adoc、.org、.wiki 文件中的文本；UI 字符串；错误消息。
  • 跳过： 围栏代码块和反引号中的代码、变量名、导入语句、配置值、URL、文件路径。
  • 保留技术术语： 只有在存在不损失准确性的更简单替代说法时，才标记术语。
  • 排除： 点目录、node_modules/、vendor/、dist/、build/、coverage/、__pycache__/、target/、venv/，以及 .gitignore 中列出的所有内容。
  • 绝不扫描技能自身所在的目录。 始终从用户的项目根目录开始工作。单独调用 /plain-language 时，审查项目根目录下所有符合范围的文本；仅当项目根目录不明确，或用户指定的文件不存在时才询问。
  • 通俗语言检查关注可读性，不检查文档/代码的准确性——文档与代码的偏差检测不在范围内。

状态文件

工作状态存放于 .agents/local/state/plain-language-YYYY-MM-DD.md（今天的日期）。该文件已加入 Git 忽略列表，绝不向用户展示，也绝不提交。

开始时：

  1. 如果 .agents/local/state/ 不存在，则创建它。
  2. 使用 Glob 搜索 .agents/local/state/plain-language-*.md。如果最新文件中有未勾选的项目，则从该文件续接。如果今天的文件已存在且已完成，则创建 ...-YYYY-MM-DD-2.md（依此类推，接着使用 -3 等）。否则创建今天的文件。删除该文件即可强制重新运行。

格式 — 按批次分组的 Markdown 复选清单：

# Plain Language — 2026-07-17

## Batch 1
- [ ] README.md
- [ ] docs/setup.md

## Batch 2
- [ ] docs/api.md

## Findings draft
- [pl-09] Use active voice — docs/setup.md:42 — sev:high — grep:`is initialized by` — "The database is initialized by the setup script" → "The setup script initializes the database"

只有编排器可以写入此文件——勾选项目，并在工作者返回结果时将其发现追加到 ## Findings draft 下；工作者不得改动该文件。阶段 3 审查的正是状态文件中的草稿，因此续接的运行会保留已有发现。

阶段 1 — 发现（机械操作，不使用子代理）

使用 Glob 或内联 shell 列表程序枚举范围内的文本文件——优先使用 rg --files；如果工具不可用，则依次回退到 fd --type f，再到普通的 find . -type f——并应用范围排除规则。将文件分成每批 3–5 个文件，并把复选清单写入状态文件。不要停下来总结——直接进入阶段 2。

第 2 阶段 — 审查（按批次并行）

每个未勾选的批次派遣一个工作子 Agent，最多并发 5 个；每轮的所有 Agent 调用都放在同一条消息中，以便并行运行。批次数超过上限时，分多轮派遣。工作 Agent 使用宿主提供的低成本模型别名（例如 model: haiku——绝不指定固定版本）。工作 Agent 从用户的项目根目录运行，因此在派遣前，需将任务说明中的每个 references/… 路径展开为该技能目录下的绝对路径。

向每个工作 Agent 说明：“你是一名通俗语言审查员，负责将 pl-* 规则目录应用于一批文本文件。你会标记违规并提出经过验证的改写；绝不修改源文件。” 每个工作 Agent：

  1. 加载 references/rules-quick-ref.md（pl-01..pl-33 目录）和 references/severity-rubric.md（高／中／低级别定义）。按需加载：评判措辞时加载 references/word-substitutions.md；出现被动语态时加载 references/active-voice-guide.md；改写需要调整结构而非替换词语时加载 references/before-and-after-examples.md。
  2. 阅读其批次文件——在一轮中发出该批次所需的 Read/Grep 调用，而不是逐个文件处理。
  3. 对每条违规分类为 FALSIFIABLE 或 OPINION；对于 FALSIFIABLE，使用针对所引文件的精确模式运行 Grep——未匹配则删除该发现，并统计删除数量。
  4. 在行内验证每条改写：必须解决所标记的规则，不引入新的违规，保持技术准确性，并符合上下文语境。如果工作 Agent 无法验证改写，则以 [Manual review required — unverified rewrite] 替代改写，不得猜测。
  5. 根据分级标准指定严重程度，并以精简的 Markdown 项目符号返回发现，每条占一行，同时附上删除的幻觉数量。

规则目录和分级标准由工作 Agent 阅读——协调 Agent 不加载它们。

发现格式（OPINION 发现省略 grep:）：

- [pl-09] Use active voice — docs/setup.md:42 — sev:high — grep:`is initialized by` — "The database is initialized by the setup script" → "The setup script initializes the database"
- [pl-14] Use contractions — docs/faq.md:12 — sev:low — "It is not necessary to restart" → "You don't need to restart"

每条规则违规对应一条发现，且必须包含行号。没有发现的文件仍计入已审查文件总数。

协调 Agent 将每个工作 Agent 的发现附加到草稿中（按文件分组，并按行号排序），并勾选该批次的复选框。工作 Agent 失败时，记录失败情况，并重新派遣该批次一次；若再次失败，则将该批次标记为 [x] (skipped — worker failed) 并继续。

第 3 阶段 — 对抗性审查（单轮）

使用宿主的默认模型，派遣一个审查子 Agent，并提供完整的发现草稿和仓库读取权限。其提示词为 references/adversarial-review-prompt.md。审查员会自行重新运行所引用的 grep，删除虚构的引用，质疑误报和严重程度夸大，验证改写，并标记遗漏的发现，返回 KEEP/REVISE/DROP 判定列表。

将判定应用到草稿：删除 DROP 项，应用 REVISE 项，并纳入新增的发现。审查深度 = 1——不进行第二轮，也不重新审查修正内容。

第 4 阶段 — 报告

使用经过审查的发现，根据模板编写汇总计划：references/final-plan-format.md（现在加载，不要提前加载）。路径解析：

  1. 仓库根目录存在 docs/ → docs/YYYY-MM-DD-plain-language-plan.md。
  2. 否则 → 在仓库根目录使用 YYYY-MM-DD-plain-language-plan.md。

YYYY-MM-DD 为 date +%Y-%m-%d——计划日期与状态文件日期的区别仅在于计划始终全新编写，不会恢复先前计划。仍标记为 [Manual review required — ...] 的发现应放入计划的 <manual_review> 附录中，绝不能放入 <changes> 部分。回复用户时只写明该路径，不要写其他内容。

需要避免的失败模式

  • 不要标记代码围栏、行内反引号、URL 或文件路径中的文本，即使它看起来像普通文本。
  • 不要标记精确的领域术语、必须原样保留的受监管语言或专有名称。
  • 不要将两项规则违规合并为一条发现，也不要在缺少行号的情况下报告发现。
  • 不要让工作线程发出未经验证的 FALSIFIABLE 发现——grep 门禁针对每条发现，而非每个文件。
  • 不要将未经验证的改写偷偷加入计划的变更列表——哨兵会将其转交人工审核。
  • 不要向用户透露状态文件、批次结构或子代理详情。

完成

当状态文件中的所有复选框都已勾选且计划文件已写入时，本次运行即告完成。回复计划文件的路径。不要提交，不要修改已审核的文件，也不要删除状态文件。

评论

支持 Markdown