派活儿 · 你出想法，我出能直接派发的任务书

三个角色：出想法的人（用户）拍板；拆书人（你，当前 agent）调研、写书、验收；执行面（干活的）拿书独立跑完——可以是当前会话主循环直接做，也可以是派生的子 agent，还可以是定时 / 调度任务。执行面一字不差地执行、把书当唯一真理——写错的事实 100% 被执行，全文不许有「来找我」（除非是写进受阻清单的待裁决项）。

> 任务书本身与宿主无关。落地机制按场景选：
> 1. 轻量 / 连续任务：建成任务清单，主循环边拆边做、实时更新状态——最通用的用法。
> 2. 要隔离 / 并行的重活：把整份任务书作为 prompt 交给子 agent 独立跑；子 agent 拿书独立跑，回来交报告。
> 3. 要定期重复：把任务书核心落成定时 / 调度任务。
>
> 不同宿主提供的任务管理、子 agent 派发、调度能力各不相同，任务书内容保持通用，落地时映射到宿主对应能力即可。

流程

0 预筛（这活配不配写书）。 不是每个想法都值得一份任务书。先快速判断：
- 单步操作、改名 / 改文案 / 查个事实 → 直接做或建 1–3 条任务，不写书。
- 涉及文件操作、外部发送、配置修改、删数据等不可逆操作 → 强制走完整流程（含下面的方案审核闸门）。
- 多步骤、跨领域、高不确定、失败代价高 → 写书。
- 已有成熟解法（记忆 / 历史里有对应流程）→ 直接执行，不重复规划。
- 拿不准 → 写书。多一次规划比少一次好，但别为杀鸡配牛刀。

写书前先收敛需求（别拿含糊想法直接进分解）。 一句话想法常藏着没说出口的假设。动笔前先逼出三样：目标能不能落成数字、约束有没有点名（而不是「做个好用的」）、默认假设列没列（标「猜的」）。三样不齐就先问（见提问轮）或补调研，别跳过——含糊需求直接分解，只会产出一份「看起来对、跑起来全错」的书。执行中途用户改了需求／加了约束：定位最早被推翻的那一节，从那节起重做，已验证且仍成立的产物保留，不从头返工。

1 调研。自己能查的一律不问。有代码库就实测：命令真的存在吗、基线数字多少、文档和实际差多少（README 写的命令不存在、lint 是 echo 占位的假绿灯、没被 import 的文件从覆盖率报告里消失——都是真坑）。行业知识能联网就查，查不到标「假设，未验证」。摸不到环境就把自测写成任务 0。善用宿主提供的检索 / 读取 / 执行工具实测，别凭记忆编。

2 提问，一轮 ≤5 个。只问查不到且会改变任务书的：方向取舍、验收裁量、风险偏好、时间盒；每个给 2–4 个选项加推荐。要拆多份并行必须在这轮问。用户在场就等答复；用户不在场（比如异步 / 自动化场景）就按默认走、标「猜的」、写进书里「我替你拍的板」一节——沉默替你拍板是越权，摆到明面是尽职。

3 写书（规则见下节）。

4 交付。最终回复只有三样，过程噪音（调研表格、中途更正、分析过程）一概不带：
- 一句用法：说明任务书落到哪——「已建成 N 条任务，主循环直接开干」或「下面整段作为子 agent 的 prompt 派发」或「已落成定时任务，按计划跑」。
- 任务书本体（代码块或任务列表），整块可复制 / 可派发。
- 一句收尾：「跑完回来说一声，我来验收，给你 5 行内的人话报告。」

一个目标、一次交付。不许拆成第二条任务书、不许让用户存文件、不许发明开工命令。

5 验收，是拆书人的活。明卷（验收命令 / 判定）在书里，执行面自己盯；暗卷——2–3 条执行面看不见的抽查——自留在会话侧，不进书。用户回来喊一声，你亲自复跑明卷＋暗卷，给结构化回执（见下）。执行面不能自己批卷。摸不到执行环境（纯调研型）时验收退化为「你亲验结论＋随机抽一条复现」。

退出码（写进交付回执开头，三选一）：
- DONE —— 两条硬指标全过，无遗留。
- DONE_WITH_CONCERNS —— 干完了，但有未决问题（如审核 3 轮未过已降级、某子任务受阻）。列出具体问题。
- BLOCKED —— 中止。写明原因、已尝试的恢复、建议下一步。

回执结构固定四段：阶段 / 已完成 / 未完成 / 下一步，别自由发挥。验收命令可批量执行：taskbook_tool.py validate-report <回执> --fitness <Plan Object> 从 Plan Object 的 acceptance 字段逐条执行验收命令，输出 pass/fail 报告，适合接入 CI——退出码非 0 即门禁拦截。

6 经验沉淀。验收回执后，回顾本次执行：有没有新经验？有 → 写入 self-improving-agent 技能的 LEARNINGS.md（如已安装该技能）；无 → 跳过，不强求。经验类型：新死规矩、新防作弊姿势、新验收命令模板、新默认假设。用 taskbook_tool.py harvest <回执文件> 从回执中提取候选经验，输出结构化列表供人工审阅——不自动写入，你看过再决定记不记。

方案审核闸门（执行前，不是事后）

只做事后验收不够——方向错了还猛跑是常见事故。对不可逆 / 高代价任务，加一道执行前方案审核，提前拦住。

• 何时开：涉及删数据、改权限、外部发送、付费、长程多阶段——任一命中就开；纯读 / 单步可跳过。
• 审什么：目标数字对不对、白名单地界有没有漏、死规矩有没有和验收打架、验收命令是不是真能跑（你亲手跑过）。
• 封驳轮次：审核不通过最多打回 3 轮；第 3 轮还不过 → 降级执行（照当前方案跑，但回执里明写「未经审核通过，请用户自验」），不无限循环。用户的时间比完美的规划贵。
• 落地：用户在场 → 把方案先给用户过一眼再执行（一句话确认即可）；异步 / 自动化场景 → 走上面的自审清单，封顶 3 轮。

写书规则

任务书六节的结构规格与探索型改法见 references/anatomy.md——它规定每节写什么，措辞和详略由你贴合任务判断。

字符预算 ≠ 4000 硬上限。部分宿主的历史 artifact 有 4000 字符限制；多数宿主派发给子 agent 没有这个硬限，但 prompt 必须自包含——子 agent 看不到本会话上下文。原则：花在「不查就会踩的坑」上，不写执行面打开仓库一眼能看到的事实；砍调研过程、重复规矩、背景故事。压不进就是活太大——拆成独立几件，一次给一件（或并行派发多份）。长任务（>3000 字 / >8 任务 / 多 agent 并行）用三文件分离（spec.md / design.md / tasks.md），三文件共享同一个 Plan Object，详见 references/anatomy.md 的「长任务变体：三文件分离」一节。短任务仍用单文件六节。

先分型：动笔前能写出验收命令的是执行型，全套照走。用户要答案本身（调研、选型、该不该做 X）的是探索型——硬指标只会收到凑数的答案，改四处见 anatomy.md。

三分用户的话：目标升华成数字；手段当假设检验（说「加 Redis」要的是「变快」，与事实不符就目标进正文、手段写进「我替你拍的板」）；约束放大成有名有姓的禁区。

富规格优先：仓库里已有的规格性文件——测试套件、schema、验收脚本、设计稿——直接写路径当规格，别用散文复述；「测试名本身就是业务要求」就是这一条。调研的一部分，就是找出哪个文件是规格。

验收用 EARS 记号法：验收条件建议用 EARS 句式（WHEN ... THEN THE system SHALL ...），从「看起来对」变成「可机器判定」。格式与示例见 references/anatomy.md 的 EARS 一节。

法与情报分家：「不许」是法，违反即不合格，每条溯源到一次实测或一次用户裁决；「建议」是情报，执行面有更好的路可以走、在进度记录里记一句为什么。把情报写成法，是替执行面做它临场更懂的决定。

自治度先定（写进书里）：full-auto（全程不等用户，适合异步／自动化）、checkpoint（关键节点停一下等确认，适合不可逆）、manual（每步等指令，适合探索型）。默认 checkpoint；异步／定时任务默认 full-auto，并在「我替你拍的板」写清「全程不等你」。

续跑机制：默认用宿主的任务 / 进度管理工具（或简单的进度文件）当进度看板（天然跨步骤可见）；跨会话长活可用 PROGRESS.md / BLOCKED.md 文件兜底（用户项目有 git 时也能用分支 / PR 纪律）。长活 / 多 Agent 任务，额外维护一份结构化 Plan Object（JSON）当状态快照：任务清单 + 每项状态（todo / in_progress / done / blocked / skipped）+ 关键证据路径 + depends_on 依赖边，在阶段切换点自动落盘（如 .taskbook/plan-object.json），中断后直接读快照续跑，比散文稳。该 JSON 的生成与校验用配套脚本（scripts/taskbook_tool.py 的 init-plan / validate-plan），不要手写 JSON。轻量任务用任务清单即可，不必上 Plan Object。断点续跑：接手先看任务清单 / 进度文件 / Plan Object，别重做。Plan Object 可用 taskbook_tool.py health-check 做健康检查（检测 stale / 孤儿 / 死锁 / 无进度 / 单点阻塞）。

防它五种死法：
1. 作弊达标（最重要）：说「让测试绿」，最省力的是加 .skip、放松断言、mock 被测对象、删测试、|| true——不是它坏，是目标函数写错。对策：基线不可退（测试数／覆盖率 ≥ 基线、skipped 0）、点名禁止具体姿势、判卷标准冻结、暗卷自留。若「测试要绿」与「实现不许改」冲突而代码真有 bug：点破并给方法（characterization test：锁当前行为＋标 KNOWN DEFECT），否则它必偷改实现
2. 幻觉命令：它（或子 agent）会平静地编造命令再甩锅环境——书里每条命令你必须亲手跑过（检索 / 执行工具实测），摸不到就写进任务 0 让它查实
3. 失忆：进度写任务清单 / PROGRESS.md / Plan Object，接手先看别重做；任务 0 过后先写 ≤10 行开工回执（理解的目标／顺序／最大风险）再动工；单任务一个会话内做得完
4. 一条道走到黑：任务 0 兼前提核验，量出的数字对不上就停；同一验收连败 3 次换项；结果比基线差就回滚如实报告——「没做成但说清了」合格，「做了但更糟」不合格。子 agent 挂了别无脑重试——先按下文 L1–L4 分层，再决定重试还是回炉重写
5. 静默事故：坏了不发信号的（假绿灯、失效报警器）配反向验证——亲手制造一次失败证明会响，贴输出。判据：问「这里坏了谁会知道」，答「没人」就要

多 Agent 并行（扇出规模 + 工具预算 + 失败分类）

每份书带同一段「全局」（整体干什么、谁管哪段、接缝在哪——接缝没人接是头号事故）。地界错开，共享写入点（lockfile 等）指定唯一归属。A 的证据经过 B 的战场只列存疑不动，B 每次 rebase 后重跑取证。建设与删除不给同一个 agent。写明「合并排队变慢是新常态，不要自行协调、不要改 CI」。落地：在同一轮里派发多个子 agent（具体机制取决于宿主），prompt 各自带「全局」段。

扇出规模表（拆几个，先看这个）——别上来就铺满一屏 agent：

串行优先：只有确认无共享写入、无因果依赖的才并行扇出；并行有协调成本＋取证互斥，能串行绝不并行。

子 Agent 工具预算（防原地打转烧钱）——派发子 agent 时显式给工具调用轮次上限（约等于宿主的 max_turns 之类预算参数）：简单任务 ≤10，标准 ≤25（默认），大特性可放宽至 40，封顶。超出即杀。预算写进任务书：「本子任务工具预算上限 X 轮，超限即停并如实回报，别硬撑。」不让子 agent 在死胡同里空转烧预算。预算不只是轮次，还要记 token 消耗：Plan Object 每个 task 带 budget_tokens / actual_tokens 字段，子 agent 回报时附 actual_tokens；主 agent 汇总各子 agent 的实际消耗与预算对比，超预算的标注。用 taskbook_tool.py cost-report <plan.json> 一键出汇总报告。

失败先按 L1-L4 分层，再决定重试还是回炉——子 agent 挂了别无脑重试（那是一条道走到黑的变体）：

• L1 平台：宿主运行时 / 工具故障（沙箱崩、工具超时、权限弹窗）→ 换调用姿势 / 重试 / 换工具。
• L2 编排：任务书本身写错（依赖声明错、地界重叠、验收命令跑不通、扇出错）→ 回炉重写任务书那一节，别让子 agent 瞎扛。
• L3 技能：被调用的子技能缺陷（SKILL 写错、依赖缺失）→ 换技能或降级方案，必要时人工接管。
• L4 外部：网络 / API / 第三方 / 凭证（连不上、限流、401）→ 检查凭证 / 重试 / 退化处理，上报用户。

重试打在正确的层：L1 / L4 可重试；L2 必须重写任务书；L3 换技能。绝不让子 agent 把所有失败都当 L4 硬重试。

上下文保护（子 agent 别把全文甩回主 agent）。 每份书交给子 agent 时明确：子 agent 把证据／产出落本地文件，回报只给状态摘要＋文件路径指针，严禁把完整输出回填主 agent——主 agent 上下文是稀缺资源，子 agent 全文回填会撑爆它、稀释真正的决策信号。主 agent 只汇总状态，按需读文件取证。

任务依赖边＋不轮询。 Plan Object 里给任务加 depends_on 边（依赖谁先完成）；派发时按依赖拓扑串行／并行，别一股脑齐发。等子 agent 完成用「阻塞等待完成」而非轮询——轮询既烧预算又容易卡死。

执行中途用户打断：三级处理。 用户半路插话不稀奇，别一打断就从头返工：① 局部修正（改措辞／补约束／修 bug）→ 直接改对应任务，其余照跑；② 需求变更（加新目标／改方向）→ 按上面的需求收敛规则，定位最早失效节从重做；③ 推翻重做（方向错了）→ 已验证仍成立的产物保留，其余清空重规划。原则「能局部不动全局」。

角色定义（可选）。 多 Agent 并行时，用 taskbook_tool.py init-roles 生成角色定义模板（.taskbook/roles.yaml），定义每个角色的专长、做事方法、工具预算。扇出时用 fanout <scale> --roles .taskbook/roles.yaml 输出角色分配建议——哪个 agent 担哪个角色、各自的 expertise／approach／budget。角色与扇出规模表配合使用：规模表定人数，角色定义定每人干什么。简单任务不用角色，直接扇出即可。

Blocked Resolver（特殊角色）。 当健康检查发现 ≥1 个 blocked 任务时，可派发一个专门的 Blocked Resolver agent。职责：分析 blocked 原因 → 确定 L1-L4 哪层 → 给恢复建议 → 能自行恢复的就恢复。预算：≤15 轮（比标准少，清淤不该太久）。地界：只读 + 更新 BLOCKED 清单和 Plan Object 状态，不改业务代码。用 fanout <scale> --blocked-resolver <plan.json> 检查是否需要派发；health-check 的 needs_resolver 字段也会标明。

循环检测（防子 agent 无限扯皮）。 子 agent 之间交互时，相同状态 / 相同错误的连续出现 ≥3 次 → 判定为循环。循环判定后：中断当前子 agent，按 L2（编排错误）处理 → 回炉重写任务书相关段落。预防：子 agent 工具预算本身就是循环的硬上限；循环检测是软上限，在预算烧完前拦住。用 taskbook_tool.py detect-loop <日志文件> 检测——输入子 agent 的工具调用日志（JSON 数组或 JSONL，每条含 action + result_hash），连续重复 ≥3 次自动告警并退出码=1。

配套脚本（无需 AI 解读的死规范已固化）

文档里那些纯结构化、不需要 AI 灵活解读的规范——Plan Object 字段与依赖边、退出码三态、回执四段、复杂度预筛规则、扇出规模、审核封驳轮次、白名单地界——已经固化成零依赖脚本 scripts/taskbook_tool.py（仅 Python 标准库，任何宿主可用）。对应环节直接调用脚本生成 / 校验，不要自己重新解读格式（每次重新解读既不稳定又费 token）。校验类命令失败退出码非 0，可接 CI / 自动化判定。

单文件不拆分（设计约束）。 taskbook_tool.py 保持单文件，不拆成多模块。理由：① 零依赖是核心卖点，单文件 = 零安装成本，任何宿主直接 python taskbook_tool.py 即用；② 拆分引入 import 路径管理，在子 agent / CI / 定时任务等异构环境反而增加故障面；③ 当前行数（~1500 行）在可维护范围内，新增子命令只需加函数 + 注册到 argparse，不触发拆分阈值。如未来行数超过 3000 且有明确的模块边界，再评估拆分。

子命令：

• init-plan --out .taskbook/plan-object.json —— 生成 Plan Object 模板（含状态枚举 / 依赖边示例 / token 预算字段 / acceptance 验收命令）。
• validate-plan <path> —— 校验：状态枚举合法、depends_on 引用存在、依赖无环、budget_tokens / actual_tokens 为非负整数、acceptance 为字符串数组（均可选）。
• validate-report -|<file> [--fitness <plan.json>] —— 校验交付回执含退出码三态之一 + 四段（阶段 / 已完成 / 未完成 / 下一步）；加 --fitness 从 Plan Object 提取各任务 acceptance 验收命令逐条执行，输出 pass/fail 报告，失败退出码=1，适合接入 CI 门禁。
• screen [--irreversible|--single-step|--multi-step|--has-existing-solution|--unsure] —— 复杂度预筛，输出 direct / brief / full。
• fanout <simple|standard|medium|high> [--roles <path>] [--blocked-resolver [plan.json]] —— 并行扇出规模查表（1 / 2–3 / 3–5 / 5–10，封顶 20）；加 --roles 输出角色分配建议；加 --blocked-resolver 检查 Plan Object 是否有 blocked 任务，有则建议增加 1 个 Blocked Resolver agent（≤15 轮）。
• audit-gate --round N [--pass] —— 方案审核闸门封驳状态机（封顶 3 轮，第 3 轮降级）。
• whitelist --allow <路径...> --op <路径> --mode write|read|create —— 白名单地界校验，写 / 新建越界返回 BLOCKED。
• checklist —— 打印机器可查的自检清单（对齐发出前自检里可程序化部分）。
• health-check <path> [--stale-days N] —— Plan Object 健康检查（stale / 孤儿 / 死锁 / 无进度 / 单点阻塞 / needs_resolver），发现问题退出码=1。
• init-roles --out .taskbook/roles.yaml —— 生成角色定义模板（YAML），定义各角色专长／方法／预算，配合 fanout --roles 使用。
• visualize <path> --out dashboard.html —— 生成单文件 HTML 看板（依赖图 + 状态统计 + 受阻高亮 + 进度时间线 + 健康度 + token 预算 vs 实际条形图），零依赖内联 CSS/SVG，浏览器直接打开。
• harvest <path> —— 从交付回执提取候选经验（受阻模式 / 未解决问题 / 可复用验收命令），输出 JSON 列表供人工审阅，不自动写入。
• cost-report <path> —— 从 Plan Object 汇总所有任务的 token 预算/实际/差值，超预算任务高亮标注。
• detect-loop <path> —— 检测子 agent 工具调用日志中的循环（JSON/JSONL，连续重复 ≥3 次告警），发现循环退出码=1。

语言

全书大白话，用户一遍读懂：标题直陈功能；术语首次出现括号给半句人话；内部概念名（如「暗卷」「探索型」「封驳」）不出现在书里。语气跟随宿主当前激活的 tone（默认实在直接，可切毒舌吐槽）；每句话要么改变执行面行为，要么删掉。需要梗彩包时读 references/style.md。

发出前自检

1. 任务体量合适？一次交付、不拆第二条？
2. 预筛做过？不可逆任务走了方案审核闸门？
3. 选型对吗（任务清单 / 子 agent / 定时任务）？命令亲手跑过？没问的都写进「我替你拍的板」带默认值？
4. 验收全是命令 / 可判？防作弊、反向验证、三道止损、进度 / 受阻机制齐？
5. 全文无「来找我」？大白话？语气贴合当前 tone？
6. 交付三样齐、无过程噪音？暗卷自留没进书？
7. 退出码（DONE / DONE_WITH_CONCERNS / BLOCKED）用对？长活 Plan Object 有落盘？
8. 多 agent：全局段齐、地界不重叠、取证不互相作废？扇出规模合理（对照规模表）、子 agent 预算封顶、失败先 L1-L4 分类？上下文保护（子 agent 落盘＋只回状态）、依赖边＋不轮询写了？
9. 需求收敛过？目标数字／约束点名／假设列清，含糊没直接进分解？自治度（full-auto / checkpoint / manual）声明了？
10. 中断三级（局部修正／需求变更／推翻重做）规则在书里？中途改需求能从最早失效节续做？
11. 经验沉淀已评估（有则记入 LEARNINGS.md，无则跳过）？可复用的验收命令模板已记入参考？