humanize-beagle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Humanize

文本人性化处理

Apply fixes from a previous

review-ai-writing

run with automatic safe/risky classification.

应用此前

review-ai-writing

运行结果中的修复内容，并自动区分安全/高风险修复类别。

Usage

使用方法

text

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

Flags:

```
--dry-run
```
- Show what would be fixed without changing files
```
--all
```
- Fix entire codebase (runs review with --all first)

--category <name>

- Only fix specific category:

content|vocabulary|formatting|communication|filler|code_docs

text

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

标志说明：

```
--dry-run
```
- 显示将要修复的内容但不修改文件
```
--all
```
- 修复整个代码库（先以--all参数运行review）

--category <name>

- 仅修复特定类别：

content|vocabulary|formatting|communication|filler|code_docs

Instructions

操作步骤

1. Parse Arguments

1. 解析参数

Extract flags from

$ARGUMENTS

```
--dry-run
```
- Preview mode only
```
--all
```
- Full codebase scan
```
--category <name>
```
- Filter to specific category

从

$ARGUMENTS

中提取标志：

```
--dry-run
```
- 仅预览模式
```
--all
```
- 全代码库扫描
```
--category <name>
```
- 过滤到特定类别

2. Pre-flight Safety Checks

2. 预执行安全检查

bash

undefined

bash

undefined

Check for uncommitted changes

检查未提交的更改

git status --porcelain


If working directory is dirty, warn:
```text
Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.

Create stash if dirty:

bash

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

git status --porcelain


若工作目录存在未提交内容，发出警告：
```text
警告：您有未提交的更改。继续前将创建git暂存。如需恢复请运行`git stash pop`。

若目录未清理，创建暂存：

bash

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

3. Load Review Results

3. 加载评审结果

Check for existing review file:

bash

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

If file missing:

--all

flag: Run

/beagle-docs:review-ai-writing --all

first

Otherwise: Fail with: "No review results found. Run
```
/beagle-docs:review-ai-writing
```
first."

If file exists, validate freshness:

bash

undefined

检查是否存在已有的评审文件：

bash

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

若文件缺失：

若使用

--all

标志：先运行

/beagle-docs:review-ai-writing --all

否则：报错提示："未找到评审结果，请先运行
```
/beagle-docs:review-ai-writing
```
。"

若文件存在，验证时效性：

bash

undefined

Get stored git HEAD from JSON

从JSON中获取存储的git HEAD

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


If stale, prompt: "Review results are stale. Re-run review? (y/n)"

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

if [ "$stored_head" != "$current_head" ]; then echo "警告：评审在提交版本$stored_head时运行，但当前HEAD已更新为$current_head" fi


若评审结果已过期，提示："评审结果已过期，是否重新运行评审？(y/n)"

4. Load Reference Material

4. 加载参考资料

Read the appropriate reference files based on the findings being fixed:

Read

references/vocabulary-swaps.md

when applying

ai_vocabulary_high

ai_vocabulary_low

fixes

Read
```
references/fix-strategies.md
```
for strategy details and before/after examples for any category
Read
```
references/developer-voice.md
```
for tone/register guidance when rewriting prose

Only load what you need — if fixing only vocabulary, skip the voice guide.

根据待修复的问题类型读取对应参考文件：

修复

ai_vocabulary_high

或

ai_vocabulary_low

问题时，读取

references/vocabulary-swaps.md

修复任意类别问题时，读取
```
references/fix-strategies.md
```
获取策略细节及前后示例
改写文本时，读取
```
references/developer-voice.md
```
获取语调/语体指导

仅加载所需资料——若仅修复词汇问题，可跳过语体指南。

5. Filter Findings

5. 筛选问题

--category

is set, filter findings to that category only.

Partition remaining findings by

fix_safety

Safe Fixes (auto-apply):

```
chat_leak
```
- Delete conversational artifacts
```
cutoff_disclaimer
```
- Delete knowledge cutoff references
```
filler_phrase
```
- Delete filler phrases
```
heading_restatement
```
- Delete restating first sentence
```
emoji_decoration
```
- Remove emoji from technical text
```
boldface_overuse
```
- Remove excessive bold formatting
```
ai_vocabulary_high
```
- Swap high-signal AI words
```
narrating_obvious
```
- Delete obvious code comments
```
synthetic_opener
```
- Delete "In today's..." openers
```
sycophantic_tone
```
- Delete or neutralize praise
```
vague_authority
```
- Delete unattributed claims
```
excessive_hedging
```
- Remove qualifiers
```
generic_conclusion
```
- Delete summary padding
```
copula_avoidance
```
- Use "is/are" naturally
```
rhetorical_device
```
- Delete rhetorical questions
```
em_dash_overuse
```
- Replace formulaic em dashes with commas, parentheses, or colons
```
thematic_break
```
- Remove horizontal rules before headings
```
title_case_heading
```
- Convert AI title-case headings to sentence case
```
curly_quotes
```
- Normalize curly quotes/apostrophes to straight
```
negative_parallelism
```
- Delete "Not just X, but also Y" filler constructions
```
challenges_and_prospects
```
- Delete "Despite its... faces challenges..." formulaic wrappers

Needs Review Fixes (require confirmation):

```
promotional_language
```
- Rewrite with specifics
```
formulaic_structure
```
- Restructure sections
```
synonym_cycling
```
- Pick consistent term
```
commit_inflation
```
- Rewrite commit scope
```
tautological_docstring
```
- Rewrite or delete docstring
```
exhaustive_enumeration
```
- Trim parameter docs
```
this_noun_verbs
```
- Rewrite docstring voice
```
ai_vocabulary_low
```
- Reduce cluster density
```
apologetic_error
```
- Rewrite error message
```
rule_of_three
```
- Simplify three-item lists used as filler comprehensiveness
```
inline_header_list
```
- Restructure boldfaced inline-header vertical lists
```
unnecessary_table
```
- Convert small tables to prose
```
regression_to_mean
```
- Restore specific facts replaced by vague praise

若设置了

--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
```
- 删除“Despite its... faces challenges...”这类模板式套话

需人工确认的修复（需交互确认）：

```
promotional_language
```
- 改写为具体表述
```
formulaic_structure
```
- 重构章节结构
```
synonym_cycling
```
- 选用统一术语
```
commit_inflation
```
- 改写提交范围
```
tautological_docstring
```
- 改写或删除文档字符串
```
exhaustive_enumeration
```
- 精简参数文档
```
this_noun_verbs
```
- 改写文档字符串语体
```
ai_vocabulary_low
```
- 降低AI词汇密度
```
apologetic_error
```
- 改写错误提示信息
```
rule_of_three
```
- 简化用作冗余填充的三项列表
```
inline_header_list
```
- 重构加粗行内标题的垂直列表
```
unnecessary_table
```
- 将小型表格转换为文本
```
regression_to_mean
```
- 恢复被模糊赞美替代的具体事实

6. Apply Safe Fixes

6. 应用安全修复

--dry-run

markdown

undefined

若使用

--dry-run

：

markdown

undefined

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"
...


Otherwise, apply fixes grouped by file to minimize file I/O:

1. Sort findings by file, then by line number (descending, to avoid offset drift)
2. For each file, apply all safe fixes in reverse line order
3. For git artifacts (`git:commit:*`, `git:pr:*`), skip — these can't be auto-fixed. Report them for manual attention.

序号	文件	行号	类型	操作
1	README.md	3	synthetic_opener	删除“In today's rapidly evolving...”
2	src/auth.py	15	narrating_obvious	删除“# Check if user exists”
3	README.md	42	ai_vocabulary_high	将“utilize”替换为“use”
...


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

1. 按文件名排序问题，再按行号降序排列（避免行偏移问题）
2. 对每个文件，按行号逆序应用所有安全修复
3. 对于git artifacts（`git:commit:*`, `git:pr:*`），跳过——无法自动修复，需人工处理并提示。

7. Handle Needs Review Fixes

7. 处理需人工确认的修复

--dry-run

, list them:

markdown

undefined

若使用

--dry-run

，列出如下内容：

markdown

undefined

Needs Review Fixes (would prompt interactively)

需人工确认的修复（将交互式提示）

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


Otherwise, for each fix, prompt interactively:

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

Track user choices:

```
y
```
- Apply this fix as suggested
```
n
```
- Skip this fix
```
e
```
- User provides custom replacement
```
s
```
- Skip all remaining interactive fixes

序号	文件	行号	类型	原文	建议修改
4	README.md	8	promotional_language	"powerful, enterprise-grade solution"	"authentication library"
...


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

```text
[README.md:8] 推广性表述: "powerful, enterprise-grade solution"
建议修改: "authentication library"
(y)确认 / (n)跳过 / (e)编辑 / (s)跳过全部:

记录用户选择：

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

8. Validate Results

8. 验证结果

For each modified markdown file, verify basic validity:

bash

undefined

对每个修改后的markdown文件，验证基本有效性：

bash

undefined

Check for broken markdown (unclosed code blocks, broken links)

检查markdown是否存在错误（未闭合代码块、无效链接）

Simple check: matching ``` pairs

简单检查：```是否成对出现

grep -c '```' "$file" | awk '{print ($1 % 2 == 0) ? "OK" : "WARNING: odd number of code fences"}'


For modified source files, check syntax is still valid:

**Python:**
```bash
python3 -c "import ast; ast.parse(open('$file').read())"

TypeScript/JavaScript:

bash

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

If validation fails for any file, revert that file:

bash

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

grep -c '```' "$file" | awk '{print ($1 % 2 == 0) ? "OK" : "WARNING: odd number of code fences"}'


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

**Python:**
```bash
python3 -c "import ast; ast.parse(open('$file').read())"

TypeScript/JavaScript:

bash

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

若任意文件验证失败，回滚该文件：

bash

git checkout -- "$file"
echo "因验证失败，已回滚$file"

9. Report Results

9. 生成结果报告

markdown

undefined

markdown

undefined

Humanize Summary

文本人性化处理总结

Applied Fixes

已应用修复

README.md:3 - Deleted synthetic opener
README.md:42 - Replaced "utilize" with "use"
src/auth.py:15 - Deleted obvious comment

README.md:3 - 删除模板式开头
README.md:42 - 将"utilize"替换为"use"
src/auth.py:15 - 删除冗余注释

Interactive Fixes

交互式修复

README.md:8 - Rewrote promotional language (user approved)
docs/guide.md:22 - Skipped by user

README.md:8 - 改写推广性表述（用户已确认）
docs/guide.md:22 - 用户已跳过

Skipped (Git Artifacts)

已跳过（Git Artifacts）

git:commit:abc1234 - Chat leak in commit message (amend manually)

git:commit:abc1234 - 提交信息中存在对话痕迹（需手动修改）

Validation

验证结果

README.md: OK
src/auth.py: OK

README.md: 正常
src/auth.py: 正常

Diff Summary

差异摘要


```bash
git diff --stat


```bash
git diff --stat

10. Cleanup

10. 清理工作

On successful completion (all validations pass):

bash

rm .beagle/ai-writing-review.json

If any validation fails, keep the file and report:

text

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

若所有验证通过，执行清理：

bash

rm .beagle/ai-writing-review.json

若存在验证失败，保留文件并提示：

text

评审文件已保留在.beagle/ai-writing-review.json
修复问题后重新运行，或使用git stash pop恢复

Core Principles

核心原则

Delete first, rewrite second. Most AI patterns are padding. Removing them improves the text.
Use simple words. Replace "utilize" with "use", "facilitate" with "help", "implement" with "add".
Keep sentences short. Break compound sentences. One idea per sentence.
Preserve meaning. Never change what the text says, only how it says it.
Match the register. Commit messages are terse. READMEs are conversational. API docs are precise. Read
```
references/developer-voice.md
```
for the full register guide.
Don't overcorrect. A slightly formal sentence is fine. Only fix patterns that read as obviously AI-generated.
Understand regression to the mean. LLMs produce the most statistically likely output. Specific, unusual facts get replaced with generic, positive descriptions. When humanizing, restore specificity — replace vague praise with concrete details.
Score density, not individual words. AI vocabulary words co-occur. One or two may be coincidental; a cluster of 3+ is a strong AI tell.

先删除，再改写。多数AI生成内容为冗余填充，删除后文本质量会提升。
使用简单词汇。将"utilize"替换为"use"，"facilitate"替换为"help"，"implement"替换为"add"。
保持短句。拆分复合句，每句表达一个核心观点。
保留原意。绝不修改文本的核心信息，仅调整表述方式。
匹配语体。提交信息需简洁，README需口语化，API文档需精准。详见
```
references/developer-voice.md
```
中的完整语体指南。
不过度修正。略带正式的表述无需修改，仅修复明显AI生成的模式化内容。
理解均值回归。大语言模型会生成统计概率最高的内容，特定、独特的事实会被模糊的正面描述替代。人性化处理时需恢复具体性——用具体细节替代模糊赞美。
关注词汇密度而非单个词汇。AI词汇常集中出现，1-2个可能是巧合，3个及以上则大概率为AI生成内容。

Example

示例

bash

undefined

bash

undefined

Preview all fixes without applying

预览所有修复但不应用

/beagle-docs:humanize-beagle --dry-run

Fix only vocabulary issues

仅修复词汇问题

/beagle-docs:humanize-beagle --category vocabulary

Full codebase scan and fix

全代码库扫描并修复

/beagle-docs:humanize-beagle --all

Preview filler fixes only

仅预览冗余内容修复

/beagle-docs:humanize-beagle --category filler --dry-run

undefined

/beagle-docs:humanize-beagle --category filler --dry-run

undefined

Rules

规则

Always load reference material before applying fixes (step 4)
Never modify files without a stash or clean working directory
Apply safe fixes in reverse line order to avoid offset drift
Never auto-fix git artifacts (commits, PRs) — report them for manual action
Validate every modified file before considering it done
Revert files that fail validation
Write JSON report before displaying summary
Clean up JSON report only on full success

应用修复前必须加载参考资料（步骤4）
未创建暂存或工作目录未清理时，绝不修改文件
按行号逆序应用安全修复以避免行偏移
绝不自动修复git artifacts（提交、PR）——需提示人工处理
所有修改后的文件必须经过验证才算完成
验证失败的文件需回滚
显示总结前需生成JSON报告
仅在完全成功时清理JSON报告