Butler

/butler — Wiki 管家

授权声明

此 skill 明确授权，覆盖 CLAUDE.md 通用限制：

• ✅ 永续循环，无需逐轮确认
• ✅ 每 17 轮自动 git commit + git push（通过 /wiki skill）
• ✅ git add docs/wiki/pages/<单个文件>

工作目录与实例

见 skills/butler/local/config.md。

启动参数

--auto 模式

触发条件：参数含 --auto。在普通永续 loop 之上覆盖两条暂停保护：

1. 忽略「连续 5 轮 fail」保护 原本连续 5 轮 fail 会立即中止 loop。--auto 下 fail 也继续下一轮， 不因短期质量波动中断。但 fail 仍记账（W3 normal），fail 模式会进 discover_by_broken_link 自纠正路径。

2. 上下文边界自续（ScheduleWakeup） 当本轮 release_round 之后判断剩余上下文 ≤ 10k token 时：

   • 完成当前轮 W3 记账 + release 锁（不留死锁）
   • 调用 ScheduleWakeup({delaySeconds: 60, prompt: "/butler --auto", reason: "butler --auto 续跑（上下文将满）"})
   • 主动结束当前会话；下次唤醒时从 round_counter.txt + queue.md 状态继续

   状态全部已经持久化在 wiki/logs/butler/（round_counter、queue、actions 等），唤醒后从步骤 1 重新启动即可无缝接续。

仍然有效的中止条件（即使在 --auto 模式下）：

• 用户在新消息中明示「停止/pause」→ 立即中止，不再 schedule
• claim_round.py 返回 DUPLICATE/RACE → 立即停止（避免双实例打架）
• 致命错误（脚本崩溃、git 不可用等）→ 报告后退出，不 schedule

一句话：--auto 让 butler 在「质量小波动」和「上下文边界」两类原本会 触发暂停的情况下继续跑，其他保护机制不变。

启动流程

步骤 1 · 读取状态
──────────────────────────────────
cat wiki/logs/butler/round_counter.txt
cat wiki/logs/butler/queue.md
cat wiki/logs/butler/housekeeping_queue.md
tail -10 wiki/logs/butler/actions.jsonl

python3 wiki/scripts/butler/claim_round.py --check-only --instance INSTANCE_NAME
→ stdout "DUPLICATE" → 立即停止
→ exit 0 → 继续

步骤 2 · 读规范（每次启动必读）
──────────────────────────────────
CLAUDE.md（本项目规则）
skills/butler/local/config.md（本项目路径、实例、项目专属覆盖规则）

步骤 3 · 上下文检查
──────────────────────────────────
距上次 W5 > 50 轮 → 立即执行 W5 反思

◆ 以下步骤 4–9 构成永续循环 ◆

步骤 4 · 周期任务检查（在领锁之前）
──────────────────────────────────
round % 29 == 0  → W5 反思
round % 17 == 0  → /wiki 发布
round % 11 == 0  → D1 discover + H10 housekeeping-scan
round % 13 == 0  → H20 wikilink-pass --since HEAD
round % 37 == 0  → H17 coverage-scan
round % 37 == 19 → H18 stub-triage

步骤 5 · 候选准备（在领锁之前完成）
──────────────────────────────────
a. 确定本轮动作类型
b. batch_n = max(ceil(1000 / WU), 5)  # 至少 5 页，禁止一轮一页
c. 从队列取候选，用 corpus_search.py 验证（命中 ≥ 2 条）
d. 候选不足时用 discover_by_broken_link.py 补充
e. 准备 batch_n × 1.5 个缓冲池

步骤 6 · 领取轮次锁 + 注册页面
──────────────────────────────────
ROUND=$(python3 wiki/scripts/butler/claim_round.py --instance INSTANCE_NAME)
for SLUG in <全部候选>:
    python3 wiki/scripts/butler/lock_manager.py set-page --round $ROUND --page SLUG
    python3 wiki/scripts/butler/lock_manager.py check-page --page SLUG --round $ROUND

步骤 7 · 执行基因（W2）
──────────────────────────────────
⚠️ 禁止直接 Write/Edit docs/wiki/pages/ 下的词条文件
   必须通过 add_page.py / edit_page.py 脚本
⚠️ 只读参考页（见 local/config.md）不得修改
⚠️ **散文质量强制规范**：所有内容生成必须遵守 `ref/spec/prose-quality.md`
   — 每段 prose 最多 1 个 `——` 且不超过 200 字，违规会被 edit_page.py 硬拦截（退出码 7/8）

for each SLUG:
    执行（动作定义见 `cat "$(bash "$MEMEX_ROOT/wiki/scripts/gene_lookup.sh" <action>)"`）→ W4 评估 → accept/fail/skip
    accept → git add site/wiki/pages/SLUG.md
    consec_fail ≥ 3 → 退出循环
    total_wu ≥ 1000 → 退出循环

步骤 8 · 记账 + 释放锁
──────────────────────────────────
python3 wiki/scripts/butler/record_action.py \
    --round $ROUND --instance INSTANCE_NAME \
    --type <type> --page "<slug列表>" \
    --result accept \
    --desc "<action>×<N>页，<WU>WU" \
    --reflect "<本轮观察>"

# 队列标记：对本轮每个成功页面独立判断
#   该页在 queue.md 中有记录 → complete_task.py --page SLUG --date $(date +%Y-%m-%d)
#   该页来自 discover_by_broken_link（queue.md 中无对应行）→ 跳过 complete_task.py
python3 wiki/scripts/butler/release_round.py $ROUND

步骤 9 → 回到步骤 4（永续）

关键规则

WU 成本表

自定义基因见 skills/gene/ 目录。

页面质量层级

项目专属的质量门槛覆盖规则见 local/config.md。

每轮输出格式

[R12] create-page×5 | <slug1>/<slug2>/… | accept×5 fail×0 | 500WU

[R17] /wiki-publish + D1-discover + H10-scan | — | accept | commit abc1234
[R29] W5-reflect | — | — | 模式：人物页质量偏低；建议加强 enrich

暂停条件

可用工具

详细规范参考

W0–W9 总则路径见 skills/butler/local/config.md。