butler

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

启动时按以下顺序读取配置与规范：

门控 — pypinyin 检查：CJK wiki 必须先确认已安装 pypinyin（python3 -c "import pypinyin"），否则 butler 循环中创建中文页面时 page_bucket.py 会抛出 ImportError。缺失则提示用户安装并中止。

第一步：读取项目配置

local/config.md              ← 基础配置（WIKI_LANG、PORT、MEMEX_ROOT 等）
local/gene/_context.md       ← 本 wiki 专属执行上下文（若存在则读取）
local/butler/                ← butler 专属扩展（如目录存在）
  chapter-map.md             ← PN 章节映射表（各 wiki 专属）
  [其他扩展文件]

第二步：读取完整规范（W 层 skill）

从 local/config.md 中读取 MEMEX_ROOT，然后依次读取：

$MEMEX_ROOT/skills/SKILL_W0_Butler管家总则.md       — 角色、不变量、十步闭环、队列架构
$MEMEX_ROOT/skills/SKILL_W1_Butler探索队列.md  — 队列选取与发现策略
$MEMEX_ROOT/skills/SKILL_W2_Butler基因表达.md    — 基因执行框架（动作目录、WU 计费）
$MEMEX_ROOT/skills/SKILL_W3_Butler质量标准.md    — 质量评级（stub→premium）
$MEMEX_ROOT/skills/SKILL_W4_Butler评估检验.md  — 自评三问、accept/fail/skip
$MEMEX_ROOT/skills/SKILL_W5_Butler反思自改.md  — W5 反思触发与自改流程
$MEMEX_ROOT/skills/SKILL_W6_Butler标注规范.md — PN 标注格式
$MEMEX_ROOT/skills/SKILL_W7_引文真实性核验.md    — blockquote 核验
$MEMEX_ROOT/skills/SKILL_W9_Butler图式反思.md — W9 图式反思
$MEMEX_ROOT/skills/SKILL_W10_Butler内务整理.md   — 内务调度与健康指标

第三步：确认基因路径

基因发现优先级（W2 执行时）：

1. local/gene/ — 本 wiki 独有的扩展基因（优先级最高）
2. $MEMEX_ROOT/skills/gene/local/ — 本 wiki 对共享基因的覆盖
3. $MEMEX_ROOT/skills/gene/ — 共享基因库

配置读取完毕后，执行 W0 十步闭环，永续运行。

基因表达日志要求

每轮 butler 循环对页面执行基因时，必须留下日志，规则如下：

每轮范围

每轮只选取 一个基因，对 一组页面（至少 5 页，由 skills/butler/SKILL.md 步骤 5 的 batch_n = ceil(1000 / WU) 公式确定，最小下限 5）执行处理。

日志位置与命名

日志写入 logs/gene-express/，文件名格式参照 BIOS spec pilot phase 约定：

YYYY-MM-DD-R{N}-{GENE}-{target}-{detail}.md

占位符	说明
YYYY-MM-DD	执行当天日期
R{N}	本 wiki 的全局基因轮次计数器（整数，自 1 递增，存于 logs/gene-express/.round 或 logs/butler/round_counter.txt）
{GENE}	基因代码，如 CHK6、ENR3、SCN27
{target}	目标页面 slug 或类型名（多页时用类型名或简短描述）
{detail}	可选后缀，表示子轮次或结果，如 r1、pass、blocked、skip

示例：

• 2026-05-20-R1-CHK6-alan-turing-pass.md
• 2026-05-20-R2-ENR3-concept-r1.md
• 2026-05-20-R3-SCN27-person-r1.md

日志内容（最小结构）

---
round: {N}
date: YYYY-MM-DD
gene: {GENE}
pages: [slug1, slug2, ...]
result: pass | blocked | skip | partial
---

## 执行摘要

（一段话：做了什么、对哪些页面、主要发现）

## 页面处理记录

| 页面 | 操作 | 结果 | 备注 |
|------|------|------|------|
| slug | ...  | pass | ...  |

## 遗留问题

（若有：待后续轮次处理的问题或 defer 条目）

轮次计数器

每次写新日志前 R += 1。计数器优先读取 logs/butler/round_counter.txt（与 W0 共用）；若该文件不存在，在 logs/gene-express/.round 中维护独立计数。

---

--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 续跑（上下文将满）"})
   • 主动结束当前会话；下次唤醒时从 logs/butler/round_counter.txt + queue.md 状态继续，无缝接续

   状态全部已经持久化在 logs/butler/（round_counter、queue、actions 等）， 唤醒后从第一步重新启动即可。

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

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

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

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