AI 任务账本（task-ledger）

> 版本说明：本文件与平台展示的 version 是对外版本序列（1.0.0 起）。
> 内部迭代版本为 v4.8.0，完整演进历史见 CHANGELOG.md。

怎么叫出这个技能

三种方式，任一种都能触发：

• 直接点名：说「用 task-ledger」或「/task-ledger」
• 说一句触发原话（不用记技能名）：
• "帮我把这件事整体梳理一下，列个清单"
• "这个需求有好几条线，先拆解再动手"
• "报一下现在进度到哪了" / "对照验收标准查一遍"
• 自动触发：需求预计超过 3 个步骤、含多条并列任务线，或任务深度未知时自动启用

一步能完成的小事不用叫它（见「何时跳过」）。

一次完整使用长什么样（迷你案例）

用户说："帮我把 Q3 的市场复盘做完，要做成 PPT。"

1. 摊开 → 拆成 3 条主线：A 数据收集（3 项）、B 分析结论（4 项）、C 页面制作（3 项），外加 1 项横切（统一口径）。每项带一句话简介和验收标准，渲染基线看板请你确认范围
2. 执行 + 记账 → 做一项勾一项，账本实时更新；做到 B2 发现还缺竞品数据 → 先入账标"新增"，问你要不要加（不擅自扩范围）
3. 看板常驻 → 浏览器打开 dashboard.html，每 2 秒自动刷新；关掉对话、关掉面板都不影响
4. 验收 → 逐条对照最终需求集，输出四态清单：已完成 / 已关闭 / 本次不做 / 未完成

你全程只需要做三件事：确认范围、回答"这个衍生活要不要加"、最后验收。

核心原则

任务活在清单里，不活在注意力里。 注意力（无论人还是模型）天生深度优先：顺着眼前一条线越钻越深，其他线就掉出视野。本技能用外部账本（任务清单）对抗这种隧道视野。

账本是活的：开工时不需要知道任务树有几层——初拆只拆可见层，深层在执行中滚动生长出来，长出来的每一条都必须先入账再决定。进度是可见的：账本放在用户看得见的地方，固定时机渲染进度看板，不靠"快好了"这种口头汇报。

账本以"任务载体"文件形态存在，不依赖对话存活。 对话中的看板只是快照，真正的账本是工作区里的一对实体文件（详见下节）。对话滚动、看板被关、会话中断，都不影响账本——它活在自己的文件里，随时可重新打开、随时可恢复执行。

任务载体机制（账本的物理形态）

任务账本不是对话里的临时画面，而是工作区中的实体文件，结构固定：

<工作区>/.task-ledger/
├── ledger.json      ← 唯一权威数据源（任务集元信息 + 主线分组 + 任务条目 + 状态 + 时间戳）
└── dashboard.html   ← 渲染载体（读 ledger.json 自动渲染，每 2 秒自动刷新）

四条核心纪律：

1. 数据只写文件，不写对话。 一切状态变更（完成 / 开始 / 新增 / 暂停 / 关闭 / 验收结论）只更新 ledger.json 的对应字段；对话回复不再承载账本状态。ledger.json 是账实一致性的唯一判据。
2. 写前先读，改后写回。 每次向 ledger.json 写入前，先读取当前最新文件再改——对话快照、会话记忆都可能过期（跨会话恢复、载体被外部改动后尤其危险），禁止基于过期内容整体覆盖写，否则会丢账实。
3. 页面自己活着。 有条件时启动本地静态服务（如 python -m http.server 8765 --directory .task-ledger）指向 .task-ledger/，把 dashboard.html 打开给用户常驻（预览面板 / 浏览器标签页）——页面每 2 秒自动读取 ledger.json 刷新，关掉对话也照常显示，改数据即时反映。无服务能力时以 file:// 打开（离线模式，需手动刷新；加载失败时页面显示空看板与警告，不显示任何示例数据），或降级为对话快照模式（见第四步）。
4. 会话可恢复。 新会话中用户说"继续 / 接着做 / 上次那个任务"→ 先读 .task-ledger/ledger.json，恢复全部任务状态后接着执行，不重头拆解。

载体缺失/损坏恢复：若 .task-ledger/ledger.json 被删、损坏或无法解析——不要重头拆解，先从最近的对话快照 / 会话记忆恢复全部任务状态，重建 ledger.json 与 dashboard.html（模板复制即用），向用户说明后继续执行；实在无快照可依才重新摊开。

生命周期：ledger.json 创建于第一步确认后；任务集验收通过、用户确认关闭后使命结束，文件保留在工作区作为归档（用户可自行删除），对话中的快照停止出现。

何时启用 / 何时跳过

满足任一信号即启用：

• 需求含并列结构："和、并且、同时、还要"，或多个交付物、多个对象
• 出现"整体 / 全面 / 完善 / 梳理 / 统一 / 优化"这类词——通常藏着多条线
• 预计执行步骤超过 3 步，或需要跨多轮工具调用
• 任务深度未知、执行中大概率冒出衍生问题（本技能的主场之一）
• 用户明确要求"先拆解 / 列清单 / 把控全局 / 报进度 / 对照验收"

直接跳过（不要过度仪式化）：

• 单一动作、一步能完成的请求（改个错字、查一个事实、解释一个概念）
• 纯问答、纯查询、闲聊
• 拿不准时：建一个 3-5 项的轻量清单即可，不必走全套流程

执行中退出：若任务进行中发现本技能过重（误启用、任务实际变简单），可向用户说明后降级——载体保留为归档，改为轻量清单或直接执行，不硬撑全套仪式。

非目标与边界（本技能不做什么）

• 不评判任务内容的质量：验收标准由用户定，agent 只对照执行、不替用户下"算不算好"的结论
• 不做任务优先级自动排序：顺序由用户意图与执行中的确认决定，agent 不擅自重排
• 不保证多 agent / 多会话并发写 ledger.json 的一致性：同一任务集同一时刻应由同一执行者维护；并发场景需另行约定写锁或错峰
• 不负责载体文件的备份：.task-ledger/ 由工作区管理，用户可自行删除 / 归档；agent 只在检测到缺失时按恢复规则重建
• 不覆盖单一动作的简单任务（见"何时跳过"）

第一步：摊开（穷举拆解，先确认范围）

1. 把需求拆成任务树：主线（2-5 条）→ 每条主线的子任务。1-2 层深度即可，看不见的底层不硬猜——深度未知是常态，账本会在执行中滚动生长，完整性靠"先入账"纪律兜底，不靠开工前的预测。
2. 拆解粒度铁律：叶子任务穷举，禁止归纳。 归纳只允许发生在主线（分组）层；叶子层每条任务必须是一个可独立执行、可独立验收的动作，禁止把多个动作或多个对象合并成一条"帽子任务"。自查方法：任务描述里出现"和 / 、 / 以及"连接的多个动作或对象、或验收标准写不出单一"算完"信号，就说明这条其实是好几条，必须拆开。反例：「完善内容部分」（一个帽子扣着好几件事）；正例：「补充竞品背景」「重构第二章论点」「替换落地案例」——三个动作，三条任务。
3. 每项任务的完整条目 = 标题（动词 + 对象）+ 一句话简介 + 验收标准：简介说明这项做什么、产出什么（让用户确认清单时不用猜）；验收标准写"做到什么算完"。正例：标题「补充竞品背景」· 简介「选 3 家主要竞品各整理一段，供论点二引用」· 验收「3 家各一段，含定价和目标用户」；反例：「了解竞品」（无简介、无完成判据）。
4. 专门扫一遍横切活：不属于任何单条线、但要等几条线都做完才冒出来的事（统一口径、对齐格式、交叉一致性、整体串联检查）。这类活最容易漏，必须显式入账。
5. 用任务管理工具（TaskCreate 等）建立清单，同时创建任务载体：在工作区建 .task-ledger/ 目录，把清单结构化写入 ledger.json（格式见 references/ledger.example.json），并放置 dashboard.html 渲染载体（模板见 references/dashboard.html，复制即用）；有本地服务能力时启动静态服务并打开载体页面（见"任务载体机制"）。然后渲染基线看板向用户请求确认。确认的对象是"范围与主线"，不是最终任务清单——清单本来就会长。未经确认不动手；用户明确说"不用确认直接做"时可跳过确认，但载体与清单仍必须建立并展示。

拆解示例——「帮我把这份方案再完善一下」（注意叶子层的穷举粒度与逐项简介）：

• A 内容逻辑线
• A1 补充竞品背景 —— 选 3 家竞品各整理一段，含定价与目标用户（供论点二引用）
• A2 重构第二章论点 —— 按"问题-方案-收益"重排，删除重复论证
• A3 替换落地案例 —— 用 1 个真实同行业案例替换现有虚构示例
• B 数据支撑线
• B1 收集近三年市场规模数据 —— 逐年一个数字，注明出处
• B2 制作市场趋势图 —— 用 B1 数据出折线图，嵌入第一章
• C 呈现格式线
• C1 统一术语口径 —— 同一概念全文只用一个叫法
• C2 压缩篇幅至 15 页内 —— 删冗余段落但不删论点
• D 横切：整体串联 —— 各线收口后通读一遍，检查逻辑衔接与口径一致

第二步：滚动记账（账本生长规则）

执行中发现新子任务、衍生问题、新信息带来的活，一律先入账再决定，按体量分流：

1. 入账：写清标题 + 一句话简介 + 验收标准 + 来源（"衍生自 B2"），状态标"新增"。粒度同样走铁律：一个动作一条，禁止把一次发现的好几件事归纳成一条入账。入账即上板——新任务必须写入 ledger.json 的 added 区（＋状态 + 来源注记），并出现在下一个回合的对话快照上；"入了内部账本但用户看不到"即违纪。
2. 判体量，分流：
   - 小活（一两步能完、不改变交付范围）→ 入账即做或排队，下次进度汇报带上
   - 大活（多步、扩大交付范围、新增一条主线）→ 入账标"待确认"，暂停该分支，先问用户做不做，得到答复再动。提问必须附足够上下文（同"卡住处理"三件套）：① 这是什么活、为什么冒出来；② 做了会带来什么（扩了哪些范围）；③ 不做会怎样、有没有替代做法。禁止只丢一句"要不要加 XX"让用户盲答
3. 禁止顺手默默做掉，也禁止默默丢掉——账实必须一致。

其他入账场景同样适用：用户中途插入新需求 → 先入账并入账本结构，不另起炉灶；某项做不了或不需要做 → 标记状态并记录原因，不静默跳过。

用户中途介入（打断 / 改方向 / 口头授权）——摘要：插新需求 → 先入账、不打断当前项；改方向 → 立即重排清单，暂停项标 ⏸ 并记原因；口头授权 → 视为确认，立即继续；说「不用做了」→ 标 ✕ 已关闭并记原因（关闭 ≠ 失败，不进缺口、不拖累进度）。只有用户有权关闭任务，agent 觉得没必要只能提建议等确认。

> 完整规则（暂停与关闭的区别、授权边界、横切活时效）见 references/edge-cases.md。

第三步：执行（勾一项，看一眼）

铁律：下一项任务从清单里挑，不从惯性里挑。

• 每完成一项：立即标记完成（TaskUpdate），不攒批；记账闭环 = 内部标记 + 写入 ledger.json + 对话快照可见——只勾内部账本、载体不更新，不算完成记账（见第四步）。然后扫一眼全清单，问"还有哪条线没动"，再决定下一项
• 同一条线连续执行不超过 2 项，就回全局挑下一项（防钻死一条线）
• 每个执行回合结束时，本回合发生的一切状态变更必须写入 ledger.json，并体现在回合末尾的对话快照上（见第四步）
• 卡住处理（缺信息 / 等外部条件）：某项任务缺少用户提供的信息（文件、账号、决策、确认）或依赖外部条件时，停止该分支，明示三件事——需要什么、为什么需要、用户给与不给各是什么走向（"等您提供 X 后继续；若给不了，我建议改为 Y"）。禁止硬猜、禁止闷头重试、禁止标记完成冒充做完了。卡住项在看板上标"⏸ 待用户输入"，不占用"进行中"。若该分支的价值存疑，可一并给出关闭建议（"若您判断这块没必要，我可以直接关闭"），但关闭与否由用户定
• 横切活时效：横切项（统一口径、整体串联等）在最后一条主线收口后的第一个回合必须开始执行，不得无限期推后
• 环境中没有任务管理工具时，降级为在回复中维护 markdown 任务清单（每次变更后重贴当前全量状态），纪律不变

第四步：进度看板（载体持续显示 + 对话快照跟脚）

要点三条：

1. 载体层是主体：dashboard.html 常驻浏览器，每 2 秒读 ledger.json 刷新，关掉对话、关掉面板都不受影响
2. 快照层是辅助：每个执行回合末尾必须在回复末尾附最新快照，内容与 ledger.json 完全一致——回合末尾无看板 = 本回合记账未完成
3. 看板活到任务集验收为止：被关闭 / 滚出视野不改变纪律，下一回合照常重渲染（重渲染本身就是续命）

必含要素：总进度（完成 / 有效总数，已关闭项不计入）、逐项状态（✓ 完成 / ▸ 进行中 / ○ 待办 / ＋ 新增 / ⏸ 暂停 / ✕ 已关闭）、「进行中」全清单至多一项、任务总数 >12 项时折叠已完成与已关闭、分线小计、状态分布。

四类特别版：基线版（初拆确认后）· 决策版（大活待确认）· 终版（验收时）· 随问随出（用户问进度立即渲染）。

> 完整细则（渲染方式、生命周期判定、纯文本环境降级）见 references/board-spec.md。

第五步：验收（对照最终确认的需求集逐条查）

收尾时拿用户最终确认的需求集（= 最初原话 + 中途明确确认过的全部增补项，即整张账本的最新版）逐条对照，输出验收报告：

1. 全局结论先行：共几条主线、各线状态、总进度
2. 逐项四态标注：已完成（附关键产出）/ 已关闭（用户主动终止，附原因，不属于缺口、不触发回炉） / 本次不做（附原因）/ 未完成（附原因和补救建议）——中途新增、被用户暂缓或关闭的项同样逐条过，不得以"不在最初需求里"为由跳过
3. 存在未完成项时，回到第三步补做，直到验收通过或用户明确喊停
4. 验收通过后：把验收结论写入 ledger.json（status 改为"已验收"），载体终版作为关闭确认；经用户确认后载体使命结束，.task-ledger/ 文件保留为归档

常见问题（FAQ）

• 看板打不开 / 显示"无法读取 ledger.json"？ 本地静态服务没启动。在工作区执行 python -m http.server 8765 --directory .task-ledger，浏览器打开 http://127.0.0.1:8765/dashboard.html。服务没起时页面只显示空看板和警告，绝不用示例数据冒充真实进度。
• 端口 8765 被占用？ 换个端口即可，启动命令与访问地址同步改（如 8767）。
• 离线能看吗？ 能。用 file:// 直接打开 dashboard.html 是离线模式，显示打开那一刻的快照，需手动刷新看最新状态。
• 看板模板要自己复制吗？ 建载体时复制一次即可：cp 技能目录/references/dashboard.html .task-ledger/dashboard.html（Windows 用 copy）。之后只改 ledger.json，页面自动刷新，不要反复重写页面文件。
• 多人 / 多会话同时改同一个账本会怎样？ 不保证并发写一致性——同一任务集同一时刻应由同一执行者维护；多人协作请各用各的工作区。
• 和 execution-coach 一起用会冲突吗？ 不会。目录独立（.task-ledger/ 与 .execution-coach/）、端口独立（8765 / 8766），互不读写。分工：agent 自己执行的任务走 task-ledger，你亲自做的任务走 execution-coach。
• 某条任务不想做了？ 说"这条不用做了"→ 标 ✕ 已关闭并记原因，从进度分母剔除，不算失败；说"先不做"→ 标 ⏸ 暂停，随时可恢复。
• 账本能保存多久？ 任务集验收后 .task-ledger/ 保留在工作区作为归档，不自动删除，想清理直接删目录。
• 简单任务要不要用？ 一步能完成的不要用（改个错字、查个事实）。拿不准就建 3-5 项轻量清单，不必走全套。

翻车自检

出现以下任一情况即已偏离本纪律，立即纠正：

> 本清单是活文档：每次任务集验收后回看一遍；若发现清单未覆盖的翻车场景，立即记入技能包目录的 CHANGELOG.md「回流记录」区块（格式：日期 | 来源 | 症状 | 修入版本，修复前标「待回流」），修复时再把对应症状补进本清单并更新版本记录——翻车案例是技能进化的原料，CHANGELOG.md 是回流的对账载体，只口头承诺不落账 = 回流流失。

• 拆解后未确认就开跑
• 初拆硬要猜完所有层才敢动手——只拆可见层，先跑起来
• 清单里出现"帽子任务"（一条塞多个动作/对象，是被归纳过的）——拆开重列，一个动作一条
• 任务缺一句话简介，用户看清单得靠猜——补齐简介再交确认
• 顺着第一条线钻到底，长时间未回看清单
• 新发现的活儿顺手做了但没入账；或默默丢掉
• 大活不问用户就擅自扩范围——入账标"待确认"，先问再做
• 任务状态攒批更新、进度失真——完成即勾
• 完成任务后看板没刷新，用户看到的还是旧状态——跟脚更新是硬要求，回合末尾必附最新看板
• 看板被关闭/滚出视野后就不再出现——看板活到任务集验收完成为止，被关过不改变纪律，每回合重渲染即续命
• 新任务入了内部账本，看板上却不出现——入账即上板，账实必须对用户可见
• 任务状态只存在对话/内部工具里，没写进 ledger.json——载体是唯一权威数据源，先写文件再谈展示
• 会话重开不读 .task-ledger/ledger.json 就重头拆解——先读载体恢复全部状态再继续执行
• 载体创建后数据变了页面不更新——每次变更必须写 ledger.json，页面自动刷新，不要重画页面文件
• 用户问进度只答"快好了"——出看板，给数字
• 用户中途改方向 / 换优先级，仍按旧清单闷头跑——立即重排清单，暂停项标 ⏸ 保原因
• 用户说"这条不用做了"却仍标记完成或继续执行——用户关闭 → 标 ✕ 已关闭并记原因，立即停止该分支
• agent 擅自把任务标关闭（或默默放弃）——只有用户有权关闭；agent 觉得没必要 → 提出建议等用户确认
• 已关闭项在验收时被当成未完成回炉——closed 归入"已关闭"类目，不属于缺口
• 任务卡在缺信息 / 等外部条件时硬猜、硬编或假装完成——停止该分支，明示需要什么、为什么、选项是什么
• 收尾验收只对最初原话、漏掉中途确认过的增补项——对照最终确认的需求集逐条查
• 收尾凭感觉交差，没有对照用户原话逐条验收
• 简单任务也强行走全套仪式
• 载体文件（ledger.json）缺失/损坏后重头拆解——先从最近快照/记忆恢复全部状态，重建载体再继续
• 大活问用户只丢一句"要不要加 XX"没给上下文——附三件套：是什么、做了影响什么、不做会怎样
• 翻车案例只口头说"下版修"，没写进 CHANGELOG.md 回流记录——回流必须有对账载体，落账才算数

到期复审

技能纪律会随模型行为与执行环境漂移，长期不复审 = 带病服役。复审状态的载体是技能包目录的 CHANGELOG.md 顶部「复审状态」区块（lastReviewed + reviewCycle，默认 90 天）。

• 触发检查：任务集验收后的回看环节（翻车自检）顺带核对——距 lastReviewed 超过一个周期时，在当次回复末尾附一句提示："本技能复审已到期（上次 YYYY-MM-DD），建议做一次轻量复审"，由用户决定是否现在做
• 轻量复审（一次过，不展开重审）：① 过一遍「翻车自检」清单，确认各条纪律仍与当前模型行为匹配；② 过一遍 CHANGELOG.md 回流记录，确认无「待回流」积压；③ 发现失效条款或积压 → 登记回流、建议升级版本；④ 完成后更新 CHANGELOG.md 的 lastReviewed 日期
• 边界：复审只是提示与登记，不阻塞当前任务执行；复审展开与技能文件修改由用户发起或确认，agent 不擅自大改