yindf/taskfold

给你的编程智能体，近乎无限的上下文

English ·
Releases ·
更新日志

让长时间的 AI 编程会话保持快速、便宜、可读：完成的工作被折叠成一条短摘要，完整原始内容随时一条命令取回。

面向 DeepSeek Harness（DSH）。

当前支持的最新 dsh 版本：0.1.7-rc.1。 dsh 的 rc 版本在本分支（master）支持；dsh 的 alpha 版本在 alpha 分支支持。

快速开始

按你 dsh 构建所在的通道选安装命令——每条都取该通道上最新验证过的 Release（见支持的 dsh 版本）：

alpha 通道 —— 默认分支（alpha）
dsh plugin --profile web add "github:yindf/taskfold#alpha"

rc 通道 —— master 分支（引号不能省：# 在 sh 里是注释）
dsh plugin --profile web add "github:yindf/taskfold#master"

两条命令均可直接复制使用：web 就是 DSH Web GUI 所用的 profile——如果你用别的 profile，换成你的名字即可。

两个分支各自的 README 记录自己通道的「支持的 dsh 版本」——alpha 通道的最新记录在 alpha 分支的 README 上。

npm 上也有 dsh-taskfold——预构建包，免去 dsh 的 allowBuilds 构建授权——但 npm 副本可能落后于通道分支。

重启 dsh——该 profile 下的每个会话都拥有这些工具。之后智能体用命名任务包住自己的工作：

task_begin("修复登录 bug")   … 干活 …   task_end("修复登录 bug")

整段来回就此折叠成一条带标题的摘要，fold_recall 随时能读回原始内容。

它解决什么问题

长会话会被自己的历史淹没：每个请求都在重发几小时前就完成的工作——旧的工具输出、调试日志、失败的尝试。成本越滚越高，模型注意力被稀释，上下文窗口迟早被塞满。

taskfold 用“好笔记本”的方式解决：干活前，智能体先用 task_begin("修复登录 bug") 开一个任务；做完后 task_end 关闭任务，同时把整段来回替换成一条带标题的短摘要：

之前：  [800 条原始调试消息……]
之后：  「修复登录 bug」— 摘要：试了什么、为什么失败、改了什么、
用户拍板了什么。（约一屏）

会话保持可读，每个请求都更便宜，模型带走的是经验而不是流水账。

什么都不丢。 每次折叠都会把原始消息原样存成文件，fold_recall({ fold: N }) 随时能重新生成。先折叠、后查阅——像合上一本随时能翻开的书记。

与 dsh 内置压缩的关系

同一个目标，不同的时机——两者可以叠加。

- dsh 内置压缩是自动的、由压力驱动的。 它在窗口快满时触发，按 token 压力选出一段区间替换成摘要；原始事件仍留在会话日志里，只是被 shadow 掉，而不是删除。
- taskfold 是显式的、按任务划分的。 每完成一个任务就顺手折叠一次，摘要是趁那一段还在上下文里时写下的——天然准确——而且带标题，会话始终可导航。
- 因为你折叠得早，窗口很少被塞满。 下面实测会话的峰值是 20.7% 而不是 59.5%，于是压力压缩要么更晚触发、要么根本不触发；真触发时，需要总结的东西也更少。
- 每一次折叠都可寻址。 fold_recall({ fold: N }) 取回的是原始消息，不是二手摘要。

原理（通俗版）

- 命名任务。 智能体开工前开任务、完工后关任务。开启状态跨重启不丢；关闭按嵌套顺序（内层先关）；关闭失败不会破坏任何状态——重试即可。
- 折叠 = 关闭 + 总结，一次调用完成。 摘要在原始内容还在上下文里时一次性写好，所以准确——不是“摘要的摘要”。
- 摘要保留要紧的东西。 总结指令明确要求保留用户的关键决策与反馈（措辞重要处原文照录）、踩过的坑和为什么失败、改了什么、最终结果。
- 温和护栏。 智能体忘记纪律时，上下文里会出现一条简短提示。提示是事件而非状态：只在条件出现或措辞变化时发布一条；条件解除后什么都不发（模型已经照做了，不需要再被告知）；没有包装标签、没有取代声明、也没有过期通知——流程健康时零噪音。
- 对缓存友好。 折叠只改写历史中段；稳定前缀（系统提示词、工具、更早的上下文）保持缓存命中。

省了多少（实测）

一次真实会话——411 个模型步、26 次折叠——数字直接读自 harness 自己的用量记录：

| | 不折叠 | 用 taskfold |
| --- | --- | --- |
| 提示 token 总量 | 142,654,308 | 52,127,098（−63.5%） |
| 单次请求最大体积 | 594,909 | 206,896（−65%） |
| 峰值上下文窗口占用 | 59.5% | 20.7% |

机制：折叠把 441,100 token 的已完成工作移出表层。这些历史本来会在之后每个请求里被重发一遍，累计下来就是 90,527,210 token 从未发出。生成那 26 条摘要本身花了 3,550,270 token（相当于节省量的 3.9%，且其中大部分是缓存读取）；单次折叠最多一次性移走 40,422 token。

这些被省下的 token 大多是缓存读取而非全新输入——单价更低，但依然计费、依然占窗口。会话再长一些，这就成了「还在窗口内」和「已经塞满」的区别。

一次会话、一种任务形态——你的数字会不同；关键是机制：完成的工作离开表层，稳定前缀持续命中，模型带走经验而不是流水账。

它添加了什么

四个智能体工具（加上上述提醒机制）：

| 工具 | 一句话 |
| --- | --- |
| task_begin({ name }) | 开一个命名任务。 |
| task_end({ name }) | 关闭它，并把整段折叠成一条带标题的摘要。 |
| list_folds | 列出全部折叠（编号、大小、标题）。 |
| fold_recall({ fold }) | 按需取回任意折叠的原始内容。 |

在 Web GUI 中，当前打开的 task 栈还会以常驻 dock 显示在输入框上方（和 todo 面板一样）：外层任务在前、最内层高亮，附带 folding/pending 计数——直接读会话的 taskMarks 投影，不追加任何事件。

其他安装方式

每个 Release 都附带预构建的 dsh-taskfold-.tgz。插件市场会优先提供该资产（或 npm 包）而不是源码构建命令，同时也免去 dsh 的 allowBuilds 构建授权——见最新 Release。

支持的 dsh 版本

- rc 通道 —— 支持到 0.1.7-rc.1（2026-09-24 在 0.35.2 上实测——本版把 alpha 通道截至 v0.35.1 的全部功能线字节级合并进 master：git diff  HEAD -- plugins test 为空。离线测试套件——14 个套件、196 个测试、0 失败；针对本分支的 fold-engine 副本与真实 rc.1 包跑宿主 API 探针——引擎类导出、ScopedEngine 继承真实 rc.1 基类、BlockAssembler，以及端到端折叠路径（带宿主头去重的前缀锚定信封、只有一个 system 消息、带行号的围栏 span 索引、用量透传）——12/12，含本轮并入的 0.1.6-alpha.2 接缝适配（recover-loop waterfall、routed-config spread）；以及在运行中的 0.1.7-rc.1 宿主上活体折叠——6/6 次折叠通过 verify-cache --since-restart（前缀缓存命中 93.9–96.3%），由挂载副本产出，其 plugins 文件哈希匹配 alpha 的 v0.34.7 发布提交——即本版合并进来的同一份功能代码的活体运行。0.1.7-rc.1 背后的宿主跳变逐字节审计与客户端契约扫描维持 0.34.8 CHANGELOG 条目的记录。一条 dist-tag 备注：0.1.7-rc.1 走 next 发布而 latest 仍解析到 0.1.5-rc.3，裸 npx @deepseek-ai/dsh web 跑的还是 rc.3——只有 @0.1.7-rc.1（或 @next）能拿到新构建）。dsh、dsh-compaction-basic、dsh-llm 三者版本锁步发布，一个数字覆盖全部耦合面。
- alpha 通道 —— 请用 #alpha 安装（dsh plugin --profile web add "github:yindf/taskfold#alpha"，即 alpha 分支）；alpha 构建的支持版本记录在 alpha 分支的 README。
- 上界：未测试、未强制。 dsh 尚未向插件提供宿主版本协商机制，不兼容的宿主不会被自动拒绝——在不兼容的 dsh 上，折叠会降级（任务照常关闭、不折叠），不会损坏数据。每次 dsh 升级后，请复核本节并按实测结果更新。
- 可选钩子：agent/turn-stopping —— 0.26.0 起归档排干还会在回合结束时运行，让回合末交付的折叠赶在 provider 前缀缓存还热时执行。没有该钩子的宿主保持原来的纯 pre-step 语义（折叠照常发生，只是晚一个回合）；注册语句整体包裹，钩子缺失不会破坏 apply()。

维护者须知

- 目录：plugins/（两个挂载行 compact-region.mjs 与 compact-stats.mjs，及其共享纯模块 events.mjs、task-marks.mjs、fold-instruction.mjs、fold-engine.mjs、fold-drain.mjs、lifecycle-nudges.mjs、lifecycle-injection.mjs、span-preview.mjs，以及浏览器半部：task-stack-ui.mjs——dock 的唯一事实源，由 scripts/build-client.mjs 生成到 taskfold-client.mjs）、scripts/release.mjs、scripts/verify-cache.mjs 与 scripts/build-client.mjs、test/（npm test）、assets/（README banner、仓库设置里上传的社交预览图，以及 screenshots.json 列出的商店截图）、docs/（docs/README.md 索引，以及 docs/design/ 设计笔记与 docs/adr/ 决策记录——有意不随 npm 包发布）、CHANGELOG.md。
- 发版：node scripts/release.mjs draft → 审阅 CHANGELOG 条目 → node scripts/release.mjs release（CHANGELOG 是版本唯一事实源）。通道分支（0.34.6 起）：master 只承载 rc 通道发版——它停留在最新的已验证 rc 版本；alpha 通道发版在 alpha 分支上进行，其提交与 tag 承载 alpha 验证过的工作（在 alpha 分支上跑 draft/release；脚本推送当前分支与 tag）。若本次发版改变了支持的 dsh 版本范围，发版前先更新两份 README（README.md + README.zh.md）的“支持的 dsh 版本”一节——release 脚本会提醒。每个分支只记录本分支构建的实测：本通道一条最新验证版本（被取代的条目删掉），另一通道只放一条指向对方分支 README 的链接——绝不抄版本号。
- 折叠缓存校验是流程的一部分。 每次 dsh 升级后——以及任何触及折叠信封的发版前——对一份 live 会话日志跑 node scripts/verify-cache.mjs --since-restart，并把数字记进 CHANGELOG 条目。若某次折叠的摘要调用重新付费了它的 span——判据是 uncached − span > --tail-budget（tail 为正）——脚本以非零码退出，这正是前缀信封不再匹配宿主摘要输入的 signature。离线测试只能钉住结构前提（只有一个 system 消息、严格前缀）；真实缓存命中只能由 live 日志给出。
- 设计决策与历史见 CHANGELOG.md，以及仓库内的 docs/（索引见 docs/README.md；docs/design/ 设计笔记与 docs/adr/ 决策记录随仓库走，不随 npm 包发布）。

如果它帮你省下了 token

点一个 star 能让更多 dsh 用户找到它——在这个生态里，插件就是靠这个被发现的。你自己会话里的实测数字，欢迎贴到 Discussions。

许可

MIT。基于 DeepSeek Harness（@deepseek-ai/*，MIT）公开包开发。