humanize

人性化处理

应用上一次 review-ai-writing 运行结果中的修复，并自动分类为安全修复或风险修复。

用法

/beagle-docs:humanize [--dry-run] [--all] [--category <name>]

标志：

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

说明

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"

3. 加载审查结果

检查是否存在审查文件：

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

如果文件不存在：

• 如果设置了 --all 标志：先运行 /beagle-docs:review-ai-writing --all
• 否则：报错："No review results found. Run /beagle-docs:review-ai-writing first."

如果文件存在，验证其时效性：

# 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

如果结果已过时，提示："Review results are stale. Re-run review? (y/n)"

4. 加载技能

Skill(skill: "beagle-docs:humanize")

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 - 删除反问句

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

• promotional_language - 改写并补充具体信息
• formulaic_structure - 重组章节
• synonym_cycling - 统一术语
• commit_inflation - 改写提交范围
• tautological_docstring - 改写或删除文档字符串
• exhaustive_enumeration - 精简参数说明
• this_noun_verbs - 改写文档字符串的表达方式
• ai_vocabulary_low - 降低词汇聚集密度
• apologetic_error - 改写错误消息

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

示例

# Preview all fixes without applying
/beagle-docs:humanize --dry-run

# Fix only vocabulary issues
/beagle-docs:humanize --category vocabulary

# Full codebase scan and fix
/beagle-docs:humanize --all

# Preview filler fixes only
/beagle-docs:humanize --category filler --dry-run

规则

• 始终先加载 beagle-docs:humanize 技能
• 未暂存更改或工作目录不干净时，绝不修改文件
• 按行号从后往前应用安全修复，避免偏移
• 绝不自动修复 Git 相关事项（提交、PR）——将其报告出来，供人工处理
• 在确认修改完成前，验证每个修改过的文件
• 验证失败的文件要还原
• 显示摘要前，先写入 JSON 报告
• 仅在全部成功后清理 JSON 报告

参考材料

让开发者文本更自然

修正文档、文档字符串、提交消息、PR 描述和代码注释中由 AI 生成的写作模式。优先删除，而非改写——对填充内容来说，最好的修复就是删掉。

核心原则

1. 先删，再改写。 大多数 AI 写作模式都是冗余内容。删除它们能让文本更好。
2. 用简单的词。 将“利用”换成“使用”，将“促进”换成“帮助”，将“实现”换成“添加”。
3. 句子要简短。 拆分复合句。每句话只表达一个意思。
4. 保留原意。 只改变表达方式，绝不改变原文含义。
5. 符合文体。 提交消息要简洁。README 要自然随和。API 文档要精准。
6. 不要矫枉过正。 稍显正式的句子也没问题。只修正明显带有 AI 写作痕迹的模式。

按类别划分的修正策略

内容模式

类型	策略	风险
宣传性语言	将最高级表述替换为具体内容	需要审核
模糊的权威性表述	删除该说法或添加引用	安全
模板化结构	删除开头或结尾的套话	需要审核
生硬的开场白	删除开场白，直接切入要点	安全

修改前：

In today's rapidly evolving software landscape, authentication is a crucial
component that plays a pivotal role in securing modern applications.

修改后：

This guide covers authentication setup for the API.

词汇模式

类型	策略	风险
明显带有 AI 痕迹的词	直接替换词语	安全
不明显的词语堆砌	减少使用频率，保留 1-2 个	需要审核
回避系动词	自然地使用“是”	安全
修辞手法	删除问题，直接陈述事实	安全
同义词轮换	选用一个词并保持一致	需要审核
提交消息夸大其词	根据实际改动范围重写	需要审核

词语替换参考：

AI 常用词	替换词
利用	使用
借助（表示“使用”时）	使用
深入探讨	查看、探索、检查
促进	帮助、实现、让
努力	尝试、工作、努力
借助	使用
范式	方法、模型、模式
尽管	虽然
此外	也、并且
而且	也、并且
稳健（非技术语境）	可靠、扎实、强大
无缝	顺畅、容易
尖端	现代、最新、新
关键	重要、关键
提升	改进
赋能	让、使能够
彻底变革	改变、改进
释放	释放、使能够
协同效应	（删除——很少有实际含义）
踏上	开始、着手

修改前：

feat: Leverage robust caching paradigm to facilitate seamless data retrieval

修改后：

feat: add response caching for faster reads

格式模式

类型	策略	风险
过度使用粗体	移除非关键术语的粗体	安全
装饰性表情符号	从技术内容中移除表情符号	安全
标题内容重述	删除重复说明的句子	安全

修改前：

## Error Handling

**Error handling** is a **critical** aspect of building **reliable** applications.
The `handleError` function **catches** and **processes** all **runtime errors**.

修改后：

## Error Handling

The `handleError` function catches runtime errors and logs them with context.

沟通模式

类型	策略	风险
聊天内容泄漏	完全删除	安全
戛然而止的免责声明	完全删除	安全
讨好语气	删除或改为中性表达	安全
道歉式错误提示	改写为直接的错误消息	需要审核

修改前：

# Great implementation! This elegantly handles the edge case.
# As of my last update, this API endpoint supports JSON.

修改后：

# Handles the re-entrant edge case from issue #42.
# This endpoint accepts JSON.

填充内容模式

类型	策略	风险
填充短语	删除该短语	安全
过度保留	移除限定词，直接陈述	安全
泛泛的结论	删除结论段落	安全

修改前：

It's worth noting that the configuration file might potentially need to be
updated. Going forward, this could possibly affect performance.

修改后：

Update the configuration file. This affects performance.

代码文档模式

类型	策略	风险
同义反复的文档字符串	删除或补充实际信息	需要审核
叙述显而易见的代码	删除注释	安全
“这个名词做了什么”	改写为主动、直接的表达	安全
穷举式列举	只保留不明显的参数	需要审核

修改前：

def get_user(user_id: int) -> User:
    """Get a user.

    This method retrieves a user from the database by their ID.

    Args:
        user_id: The ID of the user to get.

    Returns:
        User: The user object.

    Raises:
        ValueError: If the user ID is invalid.
    """
    return db.query(User).get(user_id)

修改后：

def get_user(user_id: int) -> User:
    """Raises UserNotFound if ID doesn't exist in the database."""
    return db.query(User).get(user_id)

开发者表达指南

优秀的开发者文风应当：

• 通俗但准确。 像向同事解释那样写，但要确保细节准确。
• 直接。 清楚表达观点。说“使用 X”，而不是“你可以考虑使用 X”。
• 适当简洁。 提交消息和代码注释应当简短。不要添油加醋。
• 具体。 用具体细节、数字或示例替代模糊的说法。
• 保持一致。 选定一个术语并始终使用，不要来回换用同义词。

文体指南

文档类型	语气	长度	示例
提交消息	简洁、祈使	50-72 个字符	fix: prevent nil panic in auth middleware
代码注释	简短，解释原因	1-2 行	// retry once — transient DNS failures are common in k8s
文档字符串	准确、有价值	补充名称未说明的信息	"""Raises ConnectionError after 3 retries."""
PR 描述	结构清晰、客观	背景 + 更改内容 + 测试方法	使用项目符号，而非段落
README	通俗、便于浏览	尽可能简短	先说明它的作用，再介绍用法
错误消息	可操作、具体	发生了什么 + 应该怎么做	Config file not found at ~/.app/config.yml. Run 'app init' to create one.

应用修复

安全修复（自动应用）

这些修复是机械性的，无需人工审核即可应用：

• 删除聊天痕迹（“当然！”“好问题！”）
• 删除过时免责声明（“截至我上次更新时”）
• 删除填充语（“值得注意的是”）
• 删除重复标题内容的句子
• 从技术文档中移除表情符号
• 减少过度使用的粗体格式
• 将生硬、空洞的 AI 词汇替换为自然表达（utilize → use）
• 删除“正如我们所见”/“让我们来看一下”
• 删除叙述显而易见内容的注释

需要审核的修复（交互式）

这些修复需要人工确认替换内容保留了原意：

• 改写宣传性语言（可能需要领域知识）
• 修正同义词来回切换的问题（需要选定合适的术语）
• 改写同义反复的文档字符串（需要判断哪些内容值得记录）
• 精简穷举式参数文档（需要判断哪些参数并不明显）
• 改写提交消息（需要判断范围）
• 重构程式化章节（可能会改变文档流程）
• 修正带有歉意的错误消息（措辞会影响用户体验）