aapastech/claude-skill-session-backlog

Aapastech 会话待办事项：再也不丢失任务

长时间的会话和多任务提示常常导致人工智能助手丢失工作。早期的请求在后续深入某个细节时被遗忘。该技能通过一个存储在用户自己计算机上的待办事项列表解决了这个问题。对话记忆不是事实的来源，待办事项列表才是。不在列表中的任务不存在，而列表中的任务只有被标记为“完成”或“放弃”才算结束。

它可以与任何能够在用户计算机上运行shell命令或调用MCP工具的人工智能助手或代理一起使用。在该计算机上的每次会话，无论使用什么工具或模型，都共享同一个待办事项列表。

隐私规则： 任务数据保留在执行工作的设备上。切勿将待办事项列表复制到云服务、托管页面、连接器或共享文档。如果无法访问用户设备，请改用离线模式（第9节）。

1. 查找待办事项列表并运行引擎

如果你的工具列表中有 backlog_* 工具（MCP服务器，第11节），请使用它们。它们与以下命令一一对应，并为你处理文件夹、编码和升级。跳过本节其余部分。

否则，待办事项列表是一个包含 bl.py（引擎）、config.json、tasks/（每个任务一个JSON文件）、sessions/、board.html 和 BOARD.md 的文件夹。按以下顺序查找：

1. 用户在其偏好、记忆或项目指令中告知你的位置。
2. BACKLOG_DIR 环境变量（如果已设置）。
3. ~/Documents/Aapastech-Backlog（默认位置）。
4. ~/Documents/Claude-Backlog（v3之前的文件夹名称；如果用户的任务在那里，则继续使用）。

运行它。 在本文件中，bl <command> 是简写。始终输入完整命令；切勿将其存储到shell变量中（$BL … 在zsh（macOS默认shell）中会失败）。

Shell	命令
macOS / Linux (bash, zsh)	python3 ~/Documents/Aapastech-Backlog/bl.py <command> …
Windows PowerShell	py -3 "$HOME\Documents\Aapastech-Backlog\bl.py" <command> …（如果 py 不存在，请尝试 python）
Windows cmd	py -3 "%USERPROFILE%\Documents\Aapastech-Backlog\bl.py" <command> …
Windows 上的 Git Bash	py -3 ~/Documents/Aapastech-Backlog/bl.py <command> …

bl where 打印正在使用的文件夹和引擎版本。在Windows上，Documents 经常被移动到OneDrive（%USERPROFILE%\OneDrive\Documents）。如果 ~\Documents 不存在，请在那里查找，并提供设置 BACKLOG_DIR 的建议，以便每个会话都能找到同一个文件夹。

Python。 引擎需要Python 3.8+，且无需其他依赖。

• macOS：在新Mac上首次调用 python3 可能会弹出Apple的“安装命令行开发者工具”对话框。告知用户这是预期行为，可以安全接受，或者从python.org安装Python。
• Windows：通常未安装Python。如果 py -3 和 python 都失败，要求用户从python.org安装Python 3，并勾选“Add python.exe to PATH”，或者使用 winget install Python.Python.3.12。不要回退到其他任何方式。

2. 在设备上首次运行（引导）

如果待办事项列表尚不存在：

1. 创建文件夹 ~/Documents/Aapastech-Backlog（或用户选择的位置）。
2. 将本技能文件夹中的 scripts/bl.py 复制到其中。这是一个仅使用标准库的Python文件，内嵌了看板。
3. 向用户提一个简短问题：等待用户的任务应显示什么名称，以及他们的工作涉及哪些领域（3-8个领域，例如客户、产品、管理、个人）。根据你对他们的了解建议一些领域。然后运行： bl init --owner "<名称>" --areas "领域1,领域2,…,个人,AI操作" 如果他们想要自己的看板名称，请添加 --title "<看板标题>"（默认“Aapastech Backlog”）。
4. 告知他们看板的位置：file://…/Aapastech-Backlog/board.html。提供打开看板的选项（bl board --open），并建议他们固定该标签页。
5. 建议他们使该技能始终启用，例如在其助手的个人偏好或指令文件中添加：“在每次会话开始时以及任何包含工作内容的任务之前，始终加载session-backlog技能。”

升级： 如果 bl version 打印的版本低于本技能 scripts/bl.py 中的版本（查找 VERSION = "…"），则将新的 bl.py 复制到旧文件上。任务数据和配置保持不变。

3. 会话身份（每次会话一次）

选择一个稳定的会话ID，并在每次调用中重复使用：

• 如果你的平台为会话提供了URL或ID，请使用它，并将URL作为 --url 传入。
• 否则：<平台>-<YYYYMMDD-HHMM>，使用会话开始时间，例如 desktop-20261018-1652、code-20261018-0910、api-20261018-1200、sched-20261019-0600。

bl session --id <SID> --label "<平台> · <主要主题>" --surface code|desktop|cloud|api|scheduled [--url <链接>]

这将打印该会话的开放任务以及其他会话中的未声明或过时任务。用一行提及逾期或等待用户的任务。不要转储整个列表。

4. 轮次循环（每个包含工作的轮次）

A. 首先重新读取。 在第一个轮次之后的每个轮次开始时，运行 bl open --session <SID>。当提示是对一个子任务的深入探讨时，尤其要这样做。这一步是为了防止其他工作被遗忘。切勿跳过。

B. 工作前捕获。 在开始任何工作之前，每个新的请求都会被批量捕获。这包括诸如“还有...”、“提醒我...”、“稍后...”、“别忘了...”之类的旁白。将批次写入一个JSON文件（使用你的文件写入工具），然后传递文件路径。文件适用于所有shell；通过 echo 传输JSON在Windows shell中会失败，并且会破坏非ASCII文本。

[
 {"title":"重新设计定价页面","area":"产品","eta":"1h","priority":"P1",
  "source":"提示 16:52: 重做定价页面","next":"拉取当前副本",
  "children":[{"title":"审核当前副本","eta":"10m"},
              {"title":"起草2个布局","eta":"30m"},
              {"title":"发布选定布局","eta":"20m"}]},
 {"title":"回复供应商","area":"行政","eta":"15m","status":"waiting_user","next":"用户需确认数量"}
]

bl batch --session <SID> <path-to-file.json>（将文件放在你的临时文件夹中，而不是用户的项目中）。

用一行紧凑的内容回放捕获结果，以便用户纠正：

已捕获：T-0042 定价页面 (1h) → T-0043 审核 (10m), T-0044 布局 (30m), T-0045 发布 (20m)；T-0046 供应商回复 (等待您)。

首先检查 bl list，并更新现有任务而不是创建重复任务。添加 "parent":"T-0042"（或在 bl add 中添加 --parent T-0042）以将子任务放在现有任务下。

C. 声明，然后工作。 在开始每个任务之前，运行 bl claim <ID> --session <SID> [--eta 20m]。如果因为另一个活跃会话拥有该任务而拒绝声明，则保持原样。声明是锁定的，因此两个会话永远无法同时赢得一个任务。尽可能并行工作。协调会话为其子代理更新待办事项列表，将每个子代理的任务ID传递给它。

D. 随时更新。 bl update <ID> --session <SID> --log "决策 / 发现" [--next "…"] [--output <路径或链接>] [--status blocked|waiting_user|ready]

• 用用户自己的话记录用户的决策。
• 你生成的每个文件或链接都放在 --output 中。
• 等待用户意味着 --status waiting_user --next "<你确切需要的内容>"。

E. 诚实地关闭。 仅在验证结果后，运行 bl done <ID> --session <SID> --log "已交付 …" --output …。如果父任务的子任务仍处于打开状态，则父任务无法关闭。要放弃任务，运行 bl drop <ID> --session <SID> --reason "…"。切勿删除任何内容。

F. 页脚。 每个涉及工作的回复都以 bl footer --session <SID> [--exclude <刚报告的IDs>] 的一行输出结束。

5. 领域

每个顶层任务都会从 config.json 中获得一个领域（bl areas 列出它们）。子任务继承其父任务的领域。选择最接近的匹配。仅当新的持续工作明显出现时，才添加新领域（bl areas --add "名称"），并在执行时提及。bl areas --rename 旧名称 新名称 可在配置和每个任务上重命名领域。

6. ETA（预计时间）（每个任务都有一个）

• ETA 是助手完成任务的墙钟时间，假设并行工作。通常是5-60分钟，有时是几小时，很少是几天。格式：10m、45m、2h、1h30m、1d。
• 包括验证结果的时间。
• 倒计时从声明或创建时开始。看板会将逾期任务标记为红色。
• 当你将超时时，立即重新估算：--eta 1h --eta-reason "…"。切勿让任务悄然逾期。
• 对于 waiting_user 任务，ETA 是用户回复后完成任务所需的时间。

7. 跨会话规则

• 当会话持续更新任务时，声明保持活跃状态。超过24小时未触碰则变为过时，任何会话都可以接管（接管会被记录）。
• 未经用户同意，切勿对活跃声明使用 --force。
• 在长时间工作结束前，为每个已声明任务留下一个 --next，以便新会话可以冷启动处理。使用 --status ready --log "已释放：<状态>" 释放未完成的工作。
• 对于“什么打开着”、“我们在哪里”或“另一个会话做了什么”等问题，请从 bl list（--all、--area X、--session Y）中回答，而不是从对话记忆中。
• 待办事项列表属于一台设备。其他设备或云端的会话只能通过指向该设备的链接来使用它。
• 如果命令提示任务繁忙，说明另一个会话正在即时写入。稍后重试一次。

8. 何时跳过捕获

仅对在同一个回复中完全回答的一次性问题跳过捕获。捕获所有其他内容：任何有可交付成果的内容、任何跨越多个轮次的内容，以及任何推迟的内容。如有疑问，请捕获它。

9. 离线模式（无法访问用户设备）

1. 如果你的平台有任务列表，则将任务镜像到该列表中；否则，镜像到回复中的检查清单。
2. 将每个预期的 bl.py 操作排成一列，每行一个JSON对象，保存在临时空间（切勿在用户项目中）的 backlog-pending.jsonl 中：{"cmd":"add","args":{…},"at":"<iso>"}。
3. 一次性告知用户：“您的计算机无法访问，因此待办事项更新已排队，将在恢复连接时同步。”
4. 每个轮次重试连接设备。一旦可访问，按顺序重放队列并运行 bl open。
5. 如果在同步前会话结束，最后一次回复必须完整列出未同步的任务。

10. 看板

board.html 在每次写入时重新生成，并每30秒自动刷新一次。它显示：

• 按领域划分的泳道，包含列：待办 / 进行中 / 阻塞 / 等待<所有者> / 完成
• 每张卡片上的ETA和倒计时，逾期任务标记为红色
• 哪个会话创建、处理并完成了每个任务
• 可点击查看完整日志和输出

BOARD.md 是文本形式的相同看板。

当用户要求查看时（“显示我的待办事项”、“打开看板”、“有什么打开着？”）：

• 在持有待办事项列表的计算机上，运行 bl board --open 以在默认浏览器中打开。
• 如果无法访问该计算机上的浏览器（例如手机聊天），则粘贴来自 bl list 的简短摘要，按领域分组，并优先显示逾期和等待用户的任务。
• 看板是一个本地文件。永远不会被发布、上传或分享。

11. 平台说明

• MCP客户端（任何AI助手或代理框架）。 scripts/backlog_mcp.py 是一个通过stdio暴露 backlog_session、backlog_open、backlog_add、backlog_claim、backlog_update、backlog_done、backlog_drop、backlog_list、backlog_show、backlog_footer、backlog_board、backlog_init 和 backlog_where 的标准库MCP服务器。使用命令 python3（Windows py，参数 -3 <路径>）和参数 <backlog_mcp.py 的路径> 注册它，可选地使用环境变量 BACKLOG_DIR。它运行相同的 bl.py，因此shell和MCP路由共享同一个待办事项列表。
• API驱动的代理。 通过API调用的模型本身无法访问用户的文件。开发者在拥有待办事项列表的机器上运行MCP服务器（或在其自有工具后面的 bl.py），并将这些工具提供给模型。托管代码沙箱是临时的，因此其中的待办事项列表会在沙箱结束时丢失；不要将其保留在那里。
• 链接到用户计算机的Claude桌面/云/手机会话（设备工具，例如 device_bash、device_request_folder_access、device_commit_files；如果它们是延迟加载的，请通过工具搜索加载它们）。待办事项列表文件夹或其父目录（例如 ~/Documents）必须是已连接的文件夹；如果不是，请使用 device_request_folder_access 请求一次，原因填写“为了在此计算机上保留您的任务待办事项”。然后通过 device_bash 使用连接路径运行命令（例如 python3 $HOME/mnt/Documents/Aapastech-Backlog/bl.py …）。要通过桥接安装 bl.py，暂存文件并将其提交到设备（device_commit_files）。
• Claude Code / Codex / Cursor / 其他编码代理 直接在其shell中运行引擎，如第1节中的表格所示。

命令参考

bl init    [--owner NAME] [--areas "A,B,C"] [--title T]       首次设置 / 更改所有者、领域或看板标题
bl version                                                    引擎版本
bl where                                                      待办事项文件夹、引擎版本、看板链接
bl areas   [--add NAME …] [--rename OLD NEW]                  列出 / 添加 / 重命名领域
bl session --id SID --label L --surface S [--url U]           注册会话；打印开放任务
bl open    --session SID                                      此会话的开放任务 + 未声明任务
bl batch   --session SID file.json|-                          批量添加许多（嵌套的"children"表示子任务）
bl add     --session SID --title T --area A --eta 20m [--parent ID] [--status S] [--next N] [--priority P1]
bl claim   ID --session SID [--eta 20m] [--force]
bl update  ID --session SID [--status S] [--eta E --eta-reason R] [--next N] [--log L] [--output O] [--area A] [--title T]
bl done    ID --session SID [--log L] [--output O] [--force]
bl drop    ID --session SID --reason R
bl list    [--all] [--area A] [--session SID] [--json]
bl show    ID
bl footer  --session SID [--exclude ID1,ID2]
bl board   [--open]
bl upgrade [--path /path/to/new/bl.py]

[翻译自英文，为保持与原文一致，命令和代码块未翻译]