humanize-beagle

人性化处理

基于之前一次 review-ai-writing 运行的结果，应用修复并自动分类安全和风险较高的改动。此技能以 docs-style 中的写作原则为基础。

用法

使用可选标志调用 humanize-beagle 技能：humanize-beagle [--dry-run] [--all] [--category <name>]。

标志：

• --dry-run - 显示将要进行的修复，但不更改文件
• --all - 修复整个代码库（先使用 --all 运行审查）
• --category <name> - 只修复特定类别：content|vocabulary|formatting|communication|filler|code_docs

说明

强制门槛

只有在每项 PASS 均成立时，才能继续执行具有破坏性或依赖证据的步骤（须提供命令和产物作为依据，不能只说“我检查过了”）：

1. G1 — 可以编辑文件 — PASS：git status --porcelain 的输出为空，或者git stash push -u -m "beagle-docs: pre-humanize backup" 执行成功，退出码为 0。
2. G2 — 审查输入是真实 JSON 且结构符合预期 — PASS：.beagle/ai-writing-review.json 存在，并且文件可解析为 JSON，且包含 git_head 键和一个数组类型的 findings 值（可以为空）。使用步骤 3 中的 jq -e 命令，或在 Python 中执行相同检查。如果此检查失败，停止并报告解析/验证错误，不要应用修复。
3. G3 — 重写前先查看参考资料 — **PASS：**对于要编辑的每项发现，步骤 4 要求的对应类别/类型的 references/*.md 文件均已在本次会话中阅读，然后才能更改文本。
4. G4 — 逐文件验证 — **PASS：**每个已修改文件均通过步骤 8 中针对其类型的检查；否则对该文件运行 git checkout -- "$file"，且不得在摘要中将其列为已通过。
5. G5 — 仅在全部成功时删除审查文件 — **PASS：**只有当所有保留且未因验证失败而还原的文件均满足 G4 时，才运行 rm .beagle/ai-writing-review.json（与步骤 10 保持一致）。

1. 解析参数

从 $ARGUMENTS 中提取标志：

• --dry-run - 仅预览模式
• --all - 扫描整个代码库
• --category <name> - 筛选特定类别

2. 执行前安全检查

# Check for uncommitted changes
git status --porcelain

如果工作目录有未提交更改，发出警告：

Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.

如果有未提交更改，则创建 stash：

git stash push -u -m "beagle-docs: pre-humanize backup"

**G1 PASS：**工作树原本干净，或 stash 命令退出码为 0。

3. 加载审查结果

检查是否存在现有审查文件：

cat .beagle/ai-writing-review.json 2>/dev/null

如果文件不存在：

• 如果设置了 --all 标志：先调用 review-ai-writing 技能并传入 --all
• 否则：失败并提示：“未找到审查结果。请先调用 review-ai-writing 技能。”

如果文件存在，验证 JSON 和新鲜度（G2）：

# Required shape: parseable JSON with git_head and findings array (may be empty)
jq -e 'has("git_head") and ((.findings // []) | type == "array")' .beagle/ai-writing-review.json >/dev/null 2>&1 \
  || { echo "Invalid or incompatible ai-writing-review.json"; exit 1; }

# Get stored git HEAD from JSON
stored_head=$(jq -r '.git_head' .beagle/ai-writing-review.json)
current_head=$(git rev-parse HEAD)

if [ "$stored_head" != "$current_head" ]; then
  echo "Warning: Review was run at commit $stored_head, but HEAD is now $current_head"
fi

如果结果已过期，提示：“审查结果已过期。是否重新运行审查？（y/n）”

4. 加载参考资料

根据要修复的发现，阅读相应的参考文件：

• 应用 ai_vocabulary_high 或 ai_vocabulary_low 修复时，阅读 references/vocabulary-swaps.md
• 对于任何类别的修复，阅读 references/fix-strategies.md，了解策略详情和修改前后的示例
• 重写文本时，阅读 references/developer-voice.md，了解语气和语体指导

只加载所需内容——如果只修复词汇，可跳过语气指南。

5. 筛选发现

如果设置了 --category，则只筛选该类别的发现。

按 fix_safety 对剩余发现进行分类：

安全修复（自动应用）：

• chat_leak - 删除对话痕迹
• cutoff_disclaimer - 删除知识截止时间声明
• filler_phrase - 删除填充短语
• heading_restatement - 删除对首句的重复表述
• emoji_decoration - 移除技术文本中的表情符号
• boldface_overuse - 移除过度使用的粗体格式
• ai_vocabulary_high - 替换辨识度高的 AI 用语
• narrating_obvious - 删除显而易见的代码注释
• synthetic_opener - 删除“In today's...”式开场白
• sycophantic_tone - 删除或弱化奉承语气
• vague_authority - 删除未注明出处的说法
• excessive_hedging - 移除限定语
• generic_conclusion - 删除冗余总结
• copula_avoidance - 自然使用“is/are”
• rhetorical_device - 删除反问句
• em_dash_overuse - 将程式化的破折号替换为逗号、括号或冒号
• thematic_break - 删除标题前的水平分隔线
• title_case_heading - 将 AI 式标题大小写转换为句子式大小写
• curly_quotes - 将弯引号和弯撇号统一为直引号和直撇号
• negative_parallelism - 删除“Not just X, but also Y”式填充结构
• challenges_and_prospects - 删除“尽管……仍面临挑战……”式程式化套话

需要审核的修复（需确认）：

• promotional_language - 改写为具体表述
• formulaic_structure - 重组章节
• synonym_cycling - 统一术语
• commit_inflation - 重写提交范围
• tautological_docstring - 重写或删除文档字符串
• exhaustive_enumeration - 精简参数文档
• this_noun_verbs - 改写文档字符串的语态
• ai_vocabulary_low - 降低词语聚集密度
• apologetic_error - 重写错误消息
• rule_of_three - 精简用于填充内容、营造全面感的三项列表
• inline_header_list - 重组带粗体行内标题的纵向列表
• unnecessary_table - 将小型表格转换为正文
• regression_to_mean - 恢复被模糊赞誉取代的具体事实

6. 应用安全修复

如果使用了 --dry-run：

## Safe Fixes (would apply automatically)

| # | File | Line | Type | Action |
|---|------|------|------|--------|
| 1 | README.md | 3 | synthetic_opener | Delete "In today's rapidly evolving..." |
| 2 | src/auth.py | 15 | narrating_obvious | Delete "# Check if user exists" |
| 3 | README.md | 42 | ai_vocabulary_high | Replace "utilize" with "use" |
...

否则，按文件分组应用修复，以尽量减少文件 I/O：

1. 按文件排序，然后按行号降序排序（避免偏移漂移）
2. 对每个文件，按行号逆序应用所有安全修复
3. 对于 Git 产物（git:commit:*、git:pr:*），跳过——这些无法自动修复。报告它们以便手动处理。

7. 处理需要审核的修复

如果使用了 --dry-run，列出这些修复：

## Needs Review Fixes (would prompt interactively)

| # | File | Line | Type | Original | Suggested |
|---|------|------|------|----------|-----------|
| 4 | README.md | 8 | promotional_language | "powerful, enterprise-grade solution" | "authentication library" |
...

否则，针对每项修复进行交互式提示：

[README.md:8] Promotional language: "powerful, enterprise-grade solution"
Suggested: "authentication library"
(y)es / (n)o / (e)dit / (s)kip all:

记录用户的选择：

• y - 按建议应用此修复
• n - 跳过此修复
• e - 用户提供自定义替换内容
• s - 跳过所有剩余的交互式修复

8. 验证结果

对每个已修改的 Markdown 文件，验证其基本有效性：

# Check for broken markdown (unclosed code blocks, broken links)
# Simple check: matching ``` pairs
grep -c '```' "$file" | awk '{print ($1 % 2 == 0) ? "OK" : "WARNING: odd number of code fences"}'

对已修改的源文件，检查语法是否仍然有效：

Python：

python3 -c "import ast; ast.parse(open('$file').read())"

TypeScript/JavaScript：

npx -y acorn --ecma2020 "$file" > /dev/null 2>&1

如果任何文件未通过验证，则还原该文件：

git checkout -- "$file"
echo "Reverted $file due to validation failure"

9. 报告结果

## Humanize Summary

### Applied Fixes
- [x] README.md:3 - Deleted synthetic opener
- [x] README.md:42 - Replaced "utilize" with "use"
- [x] src/auth.py:15 - Deleted obvious comment

### Interactive Fixes
- [x] README.md:8 - Rewrote promotional language (user approved)
- [ ] docs/guide.md:22 - Skipped by user

### Skipped (Git Artifacts)
- [ ] git:commit:abc1234 - Chat leak in commit message (amend manually)

### Validation
- README.md: OK
- src/auth.py: OK

### Diff Summary

git diff --stat

10. 清理

成功完成时（所有验证均通过）：

rm .beagle/ai-writing-review.json

如果任何验证失败，则保留该文件并报告：

Review file preserved at .beagle/ai-writing-review.json
Fix issues and re-run, or restore with: git stash pop

核心原则

1. 先删减，再改写。 大多数 AI 写作模式都是冗词。删掉它们能让文本更好。
2. 用简单的词。 把“utilize”换成“use”，把“facilitate”换成“help”，把“implement”换成“add”。
3. 句子要简短。 拆分复合句。每句话只表达一个意思。
4. 保留原意。 绝不改变文本表达的内容，只改变表达方式。
5. 匹配语体。 提交信息要简洁。README 要自然易读。API 文档要准确。阅读 references/developer-voice.md，了解完整的语体指南。
6. 不要矫枉过正。 稍显正式的句子也没问题。只修正明显像 AI 生成的模式。
7. 理解回归均值。 大模型会生成统计上最可能的内容。具体、少见的事实会被替换成笼统、积极的描述。让文本更自然时，要恢复具体信息——用具体细节替换空泛的赞美。
8. 评估词汇密度，而非单个词。 AI 常用词汇会同时出现。一两个词可能只是巧合；聚集出现 3 个以上，就很可能是 AI 写作的明显特征。

示例

使用带标志的 humanize-beagle 技能：

• --dry-run — 预览所有修正，不应用更改
• --category vocabulary — 只修正词汇问题
• --all — 扫描并修正整个代码库
• --category filler --dry-run — 只预览冗词修正

规则

• 应用修正前，始终先加载参考资料（第 4 步）；每项发现都要满足 G3
• 工作区必须干净或已成功暂存更改，否则绝不修改文件（G1）
• 按行号倒序应用安全修正，避免行偏移
• 绝不自动修正 Git 产物（提交、PR）——将其报告出来，留待手动处理
• 将每个已修改文件视为完成前，都要进行验证（G4）
• 还原未通过验证的文件
• 只有在所有要保留的文件都通过第 8 步验证后，才能将第 9 步摘要标为“完成”
• 只有在全部成功后，才删除 .beagle/ai-writing-review.json（G5）；如果验证中途失败，保留该文件并按第 10 步处理