butler

name	butler
description	启动 Wiki 管家永续 loop。两队列系统（content/housekeeping）。每轮：W1队列选任务→W2执行→W3自评→记账，无需用户逐轮确认。每11轮discover+housekeeping-scan，每17轮自动/wiki发布，每29轮W5反思，每37轮H17覆盖扫描。带 --auto 参数时忽略 fail 暂停 + 上下文将满时 ScheduleWakeup 自续。项目路径见 local/config.md。

/butler — Wiki 管家

授权声明

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

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

工作目录与实例

见 skills/butler/local/config.md。

启动参数

参数	默认	说明
--focus create	all	只领取 create 类任务
--focus enrich	all	只领取 enrich 类任务
--focus housekeeping	all	只领取内务任务
--focus publish	all	只执行发布任务
--focus discover	all	只做发现任务
--focus all	all	领取任意类型任务
--instance NAME	见 local/config.md	实例标识符
--auto	off	自动续跑模式（详见下节）

--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（永续）

关键规则

#	规则	违反后果
R1	claim_round.py 在步骤 6，所有写操作之前	幽灵轮次、计数器漂移
R2	release_round.py 在步骤 8 末尾，即使 fail/skip 也必须释放	死锁，阻塞下一轮
R3	候选准备在领锁之前全部完成	持锁期间搜索，锁时长膨胀
R4	页面写入必须通过 add_page.py / edit_page.py	直接 Write/Edit 触发 hook 双重计数
R5	内容必须来自 corpus_search.py 可检索到的段落	捏造引文，内容失真
R6	claim_round.py 返回 RACE → 立即停止	轮次竞争，数据覆盖
R7	只读参考页（见 local/config.md）不得修改	破坏原始章节参考
R8	正确去除 【】 括号 — corpus_search.py 结果中的 【词条】 是搜索匹配标记，必须用 词条 替换 【词条】（保留关键词本身），禁止用空字符串替换。两种错误模式必须避免：模式A（丢字）：原文"神经网络"、搜索"网络" → 返回"神经【网络】" → 若删除【网络】得"神经"（错误！应为"神经网络"）；模式B（空wikilink）：原文已有[[词条]] → 返回[[【词条】]] → 若将【词条】替换为[[词条]]得[[[[词条]]]]（错误！应只去除【】保留[[词条]]）	内容错误或渲染破损

WU 成本表

行动	WU	说明
create-page	100	创建完整新页面（≥400字 + ≥2节）
create-stub	40	创建 stub 页面（基本信息）
enrich-section	50	增加新章节
enrich-quality	30	提升质量档位
fix-links	10	修复断链
wikilink-pass	50	批量添加内部链接
discover	50	发现待建实体
housekeeping-scan	200	全局维护扫描

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

页面质量层级

层级	标签	特征
0	stub	只有 frontmatter + 1-2 句话
1	basic	≥100字 + ≥1节
2	standard	≥400字 + ≥2节 + 有 wikilink + 含原文引用
3	featured	≥800字 + ≥3节 + 交叉链接完整
4	premium	featured + 多角度解读 + 参考文献

项目专属的质量门槛覆盖规则见 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

暂停条件

条件	默认（无 --auto）	--auto 模式
用户说"停止"/"pause"	立即停止	立即停止
连续 5 轮 fail	停止	继续（fail 也跑下轮）
上下文将满（剩 ~10k token）	停止	ScheduleWakeup 续跑
claim_round 返回 RACE/DUPLICATE	停止	停止（不 schedule）
致命错误（脚本崩溃 / git 不可用）	停止	停止（不 schedule）

可用工具

工具	用法
corpus_search.py	python3 wiki/scripts/butler/corpus_search.py "关键词" --max 15
claim_round.py	ROUND=$(python3 wiki/scripts/butler/claim_round.py --instance NAME)
release_round.py	python3 wiki/scripts/butler/release_round.py $ROUND
lock_manager.py	set-page / check-page / status / cleanup
discover_by_broken_link.py	python3 wiki/scripts/butler/discover_by_broken_link.py --top 30
record_action.py	--round 必须是整数
complete_task.py	--page SLUG --date YYYY-MM-DD
add_page.py	新建页面（通过脚本，禁止直接 Write）
edit_page.py	编辑页面（保护已有节，Append-Only）
bulk_wikilink.py	全量/增量添加 wikilink

详细规范参考

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