review-ai-writing

审查 AI 写作

检测开发者文本产物中由 AI 生成的写作模式；如果 Agent 支持，可按产物组并行处理。

用法

调用 review-ai-writing 技能，可选标志：review-ai-writing [--all] [--category <name>] [path]。

标志：

• --all - 扫描整个代码库（默认：从 main 分支获取已更改文件）
• --category <name> - 仅检查特定类别：content|vocabulary|formatting|communication|filler|code_docs
• 路径：目标目录（默认：当前工作目录）

说明

1. 解析参数

从 $ARGUMENTS 中提取标志：

• --all - 扫描整个代码库
• --category <name> - 筛选特定类别
• 路径 - 目标目录

2. 加载技能

报告发现结果前，加载 review-verification-protocol 技能。AI 写作模式目录位于该文件的参考资料部分以及 references/*.md 文件中——请阅读你要检查的类别。

3. 确定范围

# Default: changed files from main
git diff --name-only $(git merge-base HEAD main)..HEAD

# If --all flag: scan all text artifacts
find . -type f \( -name "*.md" -o -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.swift" -o -name "*.kt" -o -name "*.ex" -o -name "*.exs" \) ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" ! -path "*/__pycache__/*" ! -path "*/dist/*" ! -path "*/build/*"

如果未找到文件，则退出并显示："没有可扫描的文件。请检查你的分支是否有更改，或使用 --all。"

4. 检查是否已有 LLM 产物审查结果

# Check if llm-artifacts review exists to avoid double-flagging
if [ -f .beagle/llm-artifacts-review.json ]; then
  echo "Found existing llm-artifacts review — will skip overlapping findings"
fi

如果存在 .beagle/llm-artifacts-review.json，则解析其中已有的发现结果。合并时，跳过文件:行号和模式类型都与现有 LLM 产物发现结果匹配的条目（具体为 verbose_comment 和 over_documentation 类型）。

5. 按类型分类文件

将文件划分为三组：

组	文件类型	要检查的模式
散文	*.md	全部 6 个类别
代码文档	*.py、*.ts、*.tsx、*.js、*.jsx、*.go、*.rs、*.java、*.rb、*.swift、*.kt、*.ex、*.exs	vocabulary、communication、filler、code_docs
Git	提交消息、PR 描述	content、vocabulary、communication、filler

对于 Git 产物，收集最近的提交：

# Commits on current branch not in main
git log --format="%H %s" $(git merge-base HEAD main)..HEAD

6. 扫描各产物组

下方共有三组产物（散文、代码文档、Git）。如果 Agent 支持子 Agent 且项目总数 >= 4，则为每个范围内的组分派一个子 Agent 并行处理（最多 3 个）；否则，按顺序自行执行相同的组说明——两种方式的输出相同。如果设置了 --category，则仅处理匹配的类别。每个子 Agent（或顺序处理步骤）都要先阅读本技能的参考资料以及相关的 references/*.md 模式，再进行扫描。

第 1 组：散文

范围： 仅 Markdown 文件 检查： 全部 6 个模式类别 说明：

1. 阅读每个 Markdown 文件
2. 扫描所有模式类别
3. 应用本技能中的误报检查
4. 按结构化格式返回发现结果

第 2 组：代码文档

范围： 源代码文件 检查： vocabulary、communication、filler、code_docs 类别 说明：

1. 从每个文件中提取文档字符串和注释
2. 扫描适用的模式类别
3. 跳过代码本身——仅检查注释和文档字符串中的文本
4. 按结构化格式返回发现结果

第 3 组：Git

范围： 提交消息和 PR 描述 检查： content、vocabulary、communication、filler 类别 说明：

1. 阅读分支中的提交消息
2. 如果当前处于 PR 分支，通过 gh pr view --json body 读取 PR 描述
3. 扫描适用的模式类别
4. 使用合成路径：git:commit:<sha>，行号为 0；git:pr:<number>，行号为 0
5. 按结构化格式返回发现结果

7. 合并发现结果

等待所有子 Agent 完成，然后：

1. 将所有发现结果合并为一个列表
2. 删除重复项（文件:行号和类型相同）
3. 删除与 .beagle/llm-artifacts-review.json 重叠的发现结果
4. 分配唯一 ID（1、2、3……）
5. 按类别分组显示

8. 编写 JSON 报告

如果 .beagle 目录不存在，则创建它：

mkdir -p .beagle

将发现写入 .beagle/ai-writing-review.json：

{
  "version": "1.0.0",
  "created_at": "2025-01-15T10:30:00Z",
  "git_head": "abc1234",
  "scope": "changed",
  "files_scanned": 12,
  "commits_scanned": 5,
  "findings": [
    {
      "id": 1,
      "category": "vocabulary",
      "type": "ai_vocabulary_high",
      "file": "README.md",
      "line": 15,
      "original_text": "This library leverages cutting-edge algorithms to facilitate seamless data processing.",
      "description": "High-signal AI vocabulary: leverage, cutting-edge, facilitate, seamless",
      "suggestion": "This library uses streaming algorithms for fast data processing.",
      "risk": "Low",
      "fix_safety": "Safe",
      "fix_action": "rewrite"
    },
    {
      "id": 2,
      "category": "code_docs",
      "type": "tautological_docstring",
      "file": "src/auth.py",
      "line": 42,
      "original_text": "\"\"\"Get the user by ID.\"\"\"",
      "description": "Docstring restates function name get_user_by_id without adding value",
      "suggestion": "\"\"\"Raises UserNotFound if ID doesn't exist.\"\"\"",
      "risk": "Medium",
      "fix_safety": "Needs review",
      "fix_action": "rewrite"
    },
    {
      "id": 3,
      "category": "communication",
      "type": "chat_leak",
      "file": "git:commit:abc1234",
      "line": 0,
      "original_text": "Certainly! Here's the updated authentication flow",
      "description": "Chat leak in commit message: starts with 'Certainly! Here's'",
      "suggestion": "Update authentication flow",
      "risk": "Low",
      "fix_safety": "Safe",
      "fix_action": "rewrite"
    }
  ],
  "summary": {
    "total": 3,
    "by_category": {
      "vocabulary": 1,
      "code_docs": 1,
      "communication": 1
    },
    "by_risk": {
      "Low": 2,
      "Medium": 1
    },
    "by_fix_safety": {
      "Safe": 2,
      "Needs review": 1
    }
  }
}

9. 显示摘要

## AI Writing Review

**Scope:** Changed files from main
**Files scanned:** 12 | **Commits scanned:** 5

### Findings by Category

#### Vocabulary (1 issue)

1. [README.md:15] **AI vocabulary** (Low, Safe)
   - High-signal AI vocabulary: leverage, cutting-edge, facilitate, seamless
   - Suggestion: Rewrite with simple words

#### Code Docs (1 issue)

2. [src/auth.py:42] **Tautological docstring** (Medium, Needs review)
   - Docstring restates function name without adding value
   - Suggestion: Add meaningful information or delete

#### Communication (1 issue)

3. [git:commit:abc1234:0] **Chat leak** (Low, Safe)
   - Commit message starts with "Certainly! Here's"
   - Suggestion: Rewrite as imperative commit message

### Summary Table

| Category | Safe | Needs Review | Total |
|----------|------|--------------|-------|
| Vocabulary | 1 | 0 | 1 |
| Code Docs | 0 | 1 | 1 |
| Communication | 1 | 0 | 1 |
| **Total** | **2** | **1** | **3** |

### Next Steps

- Invoke the humanize-beagle skill to apply fixes
- Invoke the humanize-beagle skill with --dry-run to preview changes first
- Review the JSON report at `.beagle/ai-writing-review.json`

10. 验证

完成前，以下所有检查都必须通过（客观检查）：

1. JSON 文件存在且可解析：.beagle/ai-writing-review.json 存在，或者你在 Gate 1 处退出且未进行扫描（此时不需要 JSON）。
2. **JSON 有效性：**如果文件存在，则 python3 -c "import json; json.load(open('.beagle/ai-writing-review.json'))" 的退出码为 0。
3. **子 Agent 成功：**如果你派发了子 Agent，则每个子 Agent 都已返回，且没有工具或运行时错误（派发失败时，不要将最终 JSON 报告写成已完成状态）。
4. **已获取 Git HEAD：**如果 JSON 存在，git_head 必须与 git rev-parse HEAD 的结果一致（非空字符串）。
5. **没有重复标记：**如果 .beagle/llm-artifacts-review.json 存在，则对于 §4 中的跳过规则，不得有任何发现与其中的文件:行号及重叠类型重复。

# Verify JSON is valid (when file exists)
python3 -c "import json; json.load(open('.beagle/ai-writing-review.json'))" 2>/dev/null && echo "Valid JSON" || echo "Invalid JSON"

如果任何检查失败，请报告错误并停止。

每项发现的输出格式

[FILE:LINE] ISSUE_TITLE
- Category: content | vocabulary | formatting | communication | filler | code_docs
- Type: specific_pattern_name
- Original: "the problematic text"
- Suggestion: "the improved text" or "delete"
- Risk: Low | Medium
- Fix Safety: Safe | Needs review

规则

• 始终先阅读此技能的模式目录，并加载 review-verification-protocol
• 如果 Agent 支持子 Agent，且待扫描项不少于 4 项，则按制品组并行处理；否则按顺序扫描
• 每项发现都必须包含文件:行号引用（Git 制品使用合成路径）
• 不要标记技能中列出的误报
• 不要重复 .beagle/llm-artifacts-review.json 中的发现
• 如有需要，创建 .beagle 目录
• 显示摘要前先写入 JSON 报告

阶段关卡（按顺序满足通过条件）

只有在通过条件已根据制品（路径、退出码、可解析输出）得到满足后，才能继续；不能仅凭内部“我已检查”的说法。

1. 参数 → 范围

   • 通过条件：你可以列出将要扫描的具体路径（或 git:commit:<sha> / git:pr:<n>）。如果集合为空，则输出“没有要扫描的文件……”消息，且不要创建 .beagle/ai-writing-review.json。

2. 范围 → 执行

   • **通过条件：**Prose、Code docs 以及 Git（若在范围内）均已获得子 Agent 的完整输出，或已通过等效的内联工作完成；每项发现都包含相同的结构化字段。

3. 整合 → 写入

   • **通过条件：**已移除重复项（相同文件:行号和类型）；如果 .beagle/llm-artifacts-review.json 存在，则按照 §4 跳过与其重叠的发现；git_head 与 git rev-parse HEAD 的输出一致（非空）。

4. JSON → 摘要

   • 通过条件：python3 -c "import json; json.load(open('.beagle/ai-writing-review.json'))" 的退出码为 0。

5. 发现 → 验证协议

   • **通过条件：**对于每个报告的问题，你都能引用所依据的段落或函数，以证明标记有据可依（参见 review-verification-protocol）。

参考资料

开发者文本中的 AI 写作检测

检测开发者制品中具有 AI 生成文本特征的模式。这些模式会降低可信度、增加噪声并模糊含义。

模式类别

类别	参考资料	关键信号
内容	references/content-patterns.md	宣传性语言、模糊权威、公式化结构、合成式开场白
词汇	references/vocabulary-patterns.md	AI 词汇层级、系词回避、修辞手法、同义词轮换、提交记录夸大
格式	references/formatting-patterns.md	过度使用粗体、表情符号装饰、标题重复概述内容
沟通	references/communication-patterns.md	聊天内容泄漏、截断免责声明、谄媚语气、道歉式错误
填充内容	references/filler-patterns.md	填充短语、过度保留措辞、泛泛的结论
代码文档	references/code-docs-patterns.md	同义反复的文档字符串、叙述显而易见的代码、“This 名词 动词”句式、穷举式列举

范围

扫描以下类型的产物：

产物	文件模式	备注
Markdown 文档	*.md	README、指南、变更日志
文档字符串	*.py、*.ts、*.js、*.go、*.swift、*.rs、*.java、*.kt、*.rb、*.ex	特定语言的文档字符串格式
代码注释	与文档字符串相同	行内注释和块注释
提交消息	git log 输出	使用合成路径 git:commit:<sha>
PR 描述	GitHub PR 正文	使用合成路径 git:pr:<number>

不要扫描的内容

• 生成的代码（锁定文件、编译输出、供应商目录）
• 第三方内容（复制的许可证文本、随附的文档）
• 代码本身（变量名、以编程方式使用的字符串字面量）
• 测试样例和模拟数据

检测规则

高置信度信号（始终标记）

以下模式是 AI 生成文本的强烈迹象：

1. 聊天式措辞泄漏 — “Certainly!”、“I'd be happy to”、“Great question!”、“Here's”作为句首
2. 过时信息免责声明 — “As of my last update”、“I cannot guarantee”
3. 高信号 AI 词汇 — delve、utilize（表示“使用”）、whilst、harnessing、paradigm、synergy
4. 文档字符串中的“This noun verbs”结构 — “This function calculates”、“This method returns”
5. 生硬的开场白 — “In today's fast-paced”、“In the world of”
6. 谄媚式代码注释 — “Excellent approach!”、“Great implementation!”

中置信度信号（结合上下文标记）

当 2 个或以上信号同时出现，或某种模式反复出现时，予以标记：

1. 低信号 AI 词汇聚集 — 单个章节中出现低信号词汇列表中的 3 个或以上词语
2. 公式化结构 — README 章节采用刻板的引言—正文—结论结构
3. 标题复述 — 标题后的第一句话复述标题
4. 过度使用模糊措辞 — “might potentially”、“could possibly”、“it seems like it may”
5. 同义词轮换 — 在同一章节中用不同名称指代同一概念
6. 过度使用粗体 — 超过 30% 的句子包含粗体文本

低置信度信号（仅记录）

提及但不要将其标记为问题：

1. 技术文档中的表情符号 — 可能是有意采用的项目风格
2. 填充语句 — 人类写作中也常见
3. 通用结论 — 可能适用于总结章节
4. 提交信息膨胀 — 有些团队偏好描述性提交信息

误报警告

不要将以下内容标记为 AI 生成：

模式	合理原因
安全文档中的“Ensure”	安全要求中的标准术语
测试覆盖率讨论中的“Comprehensive”	准确的技术描述
API 参考文档中的正式语气	参考资料应采用的语体
金融或商业领域代码中的“Leverage”	领域特定含义，不是 AI 填充词
CLI 帮助文本中的粗体格式	标准惯例
RFC/ADR 中结构化的引言段落	此类文档的预期格式
Python __init__.py 中的“This module provides”	符合 Python 习惯的模块文档字符串
博文中的反问句	适用于非正式内容

集成

与 review-verification-protocol 配合使用

报告任何发现前：

1. 阅读相关上下文（完整段落或函数）
2. 确认该模式具有 AI 特征，而不只是正式写作风格
3. 检查项目是否已有符合该模式的惯例
4. 确认建议能提升清晰度，且不改变原意

与 llm-artifacts-detection 配合使用

代码层面的模式（同义反复的文档字符串、显而易见的注释）与 llm-artifacts-detection 的风格标准存在重叠。加载这两项技能时：

• review-ai-writing 关注写作风格（读起来如何）
• llm-artifacts-detection 关注代码产物（是否根本不该存在）
• 如果存在 .beagle/llm-artifacts-review.json，则跳过其中已记录的问题

输出格式

按以下格式报告每个问题：

[FILE:LINE] ISSUE_TITLE
- Category: content | vocabulary | formatting | communication | filler | code_docs
- Type: specific_pattern_name
- Original: "the problematic text"
- Suggestion: "the improved text" or "delete"
- Risk: Low | Medium
- Fix Safety: Safe | Needs review

风险级别

• 低 — 填充语、显而易见的注释、表情符号。移除后可提高清晰度，且不改变含义。
• 中 — 词汇替换、结构调整、重写文档字符串。如果处理不当，可能改变含义。

修复安全性

• 安全 — 机械式替换或删除。无需判断。
• 需要审核 — 重写需要理解上下文。应由人工确认替换内容保留了原意。