任务栈 Ray1270/dsh-task-stack

@ray1270/dsh-task-stack

给 DeepSeek Harness Agent 用的可持久化任务栈：Agent 显式调用三个工具来 push / pop / 查看自己的多步任务焦点，状态以纯文本 JSON 落在会话工作区里。

- 跨上下文压缩存活 —— 状态在磁盘上，压缩掉对话也不丢
- 跨会话恢复可找回 —— 同一 sessionId + cwd 重新挂载即读回同一份文件
- 零自动注入 —— 不写系统提示词、不注入上下文，Agent 不主动调用就一个 token 都不花

focus_task("给 CLI 加 JSON 导入命令")
└─ 遇到需要单独完成的多步目标 → focus_task("顺便把导入的错误提示改掉") └─ focus_complete("错误提示已改，附带单测") ← 栈顶回到 "给 CLI 加 JSON 导入命令"，重新变 active
focus_complete("导入命令已加，冒烟测试通过")

三个工具

模型看到的描述都按「什么时候该用 / 什么时候不该用 / 返回什么」写。

focus_task(description)

把一行任务描述压到栈顶；原先 active 的任务自动变 paused。返回新的栈深度与栈顶任务。

- 该用：用户要的东西需要好几步才能交付，尤其是一个请求里有多个可分离目标时。推你最外层要对用户负责的那个目标，不是你自己计划的每一步。
- 不该用：单轮问答；栈顶任务内部的例行步骤；复述用户消息。
- 栈到达 maxStackDepth 时拒绝并说明原因，不抛异常。

focus_complete(conclusion)

弹出栈顶任务，记下一行结论，下面那个任务重新变 active。返回被关闭的任务、重新激活的任务、剩余深度。

- 该用：栈顶任务的多步工作完成、产物已经落地时，且在写最终答复之前调用——这样之后即使发生上下文压缩，也能看到已关闭的结论。
- 不该用：放弃、暂停、改名。目标变了应该改述栈顶任务，而不是把它挂着。
- 空栈时拒绝并提示：说明这次工作根本没 push 过任务。

read_focus()

以 markdown 返回完整栈（active + paused）与最近若干条已完成记录。

- 该用：上下文压缩之后、恢复会话时、用户问「你现在在做什么」时、决定该 push 还是 complete 之前。
- 不该用：每一步之后都调。你自己近几轮还看得到焦点时就别花 token。
- 因为本插件不注入提示词，这是唯一能看到任务栈的办法。

/focus 斜杠命令（人用，不花模型 token）

除了三个工具，插件还注册一个 /focus 命令，直接作用于当前会话的任务栈——排查问题或手工收尾时不用消耗一轮对话。

| 输入 | 作用 |
| /focus | 打印任务栈（active/paused 标注 + 深度）与最近历史 |
| /focus done <结论> | 关闭栈顶任务并把结论写进 history，等价于一次 focus_complete |
| /focus clear | 清空整个栈，每个被清的任务都会记入 history（结论为 cleared via /focus），不会静默丢失 |

/focus clear 是幂等的：空栈时回一句"已经是空的"，不算错误。/focus done 空栈时会明确告诉你栈是空的——那是"没 push 过任务"的信号，而不是需要重试。

安装

方式 A：作为 profile bundle 安装（常规使用）

从 npm 安装（推荐）
dsh plugin --profile desktop add @ray1270/dsh-task-stack

或者克隆仓库后按本地目录安装（适合要改源码时）
git clone https://github.com/Ray1270/dsh-task-stack.git
cd dsh-task-stack
dsh plugin --profile desktop add $pwd

dsh plugin add 会把包装进 profile 的 node_modules 并把它登记进该 profile package.json 的 dsh.profile.bundles。profile 应用本包自带的 cordis.patch.yml，其中的加载行 name: @ray1270/dsh-task-stack 就从 profile 的 node_modules 解析。重启 DSH Desktop 后新会话即可直接让模型调用这三个工具、使用 /focus。

若不想走包管理器安装，也可以手工两步（等价）。在克隆出来的仓库根目录里执行：

1) 建 junction，让 profile 能按包名解析到这个目录 $plugin = (Get-Location).Path $link = "$env:DSH_HOME\profiles\desktop\node_modules\@ray1270\dsh-task-stack" New-Item -ItemType Directory -Force -Path (Split-Path $link) | Out-Null cmd /c mklink /J "$link" "$plugin"

2) 编辑 $env:DSH_HOME\profiles\desktop\package.json，在 dsh.profile.bundles 数组里加一项 "@ray1270/dsh-task-stack" 不要写 "dependencies": { "@ray1270/dsh-task-stack": "link:...." }：profile 在 C: 而插件在 D:，path.resolve 到盘根就停，多少个 .. 都跨不了盘，一条解析不了的 link: 会让以后的 pnpm install 直接失败。Bundle 靠 profile node_modules 里的 junction 解析，不需要依赖项。

方式 B：免安装的临时 overlay（开发调试）

注意 --patch 属于启动器：必须写在 profile 名之前
dsh --profile web --patch ".\dev.patch.yml" --no-open

dev.patch.yml 用 name: ./lib/index.js，由加载器改写成 patch 文件旁边的 file:// URL，因此不需要安装、不需要 node_modules 解析。cordis.patch.yml 用的裸包名只在包已安装（或可被 node_modules 解析）时才有效。

两个坑：
- dsh web --patch x.yml 是错的（web 子命令不认识 --patch），要写 dsh --profile web --patch x.yml。
- patch 行里的相对目录（name: ./）也不行：Node 对目录 URL 抛 ERR_UNSUPPORTED_DIR_IMPORT，且 file: 说明符不走 exports。

HTTP 快照端点（Web 侧栏数据面）

在 Web 组合（dsh --profile web）里，插件会额外注册一个只读端点，供 GUI 面板读取任务栈：

GET /api/dsh-task-stack/snapshot?sessionId=<id>&cwd=<绝对路径>

返回：

{
"sessionId": "session-…", "cwd": "D:\\…", "depth": 2,
"top": { "id": "task-…", "description": "…", "status": "active", "createdAt": "…" },
"stack": [ /* 最深在前，栈顶在最后 / ],
"history": [ / 最旧在前 / ],
"warnings": []
}

行为约定：

| 情况 | 响应 |
| 正常 | 200 + JSON，cache-control: no-store |
| 未认证（无浏览器 cookie）/ Host 不在信任范围 | 401 / 403 |
| 组合里没有 connection 服务（无法鉴权） | 503，失败关闭而不是无鉴权放行 |
| 缺 sessionId、cwd 非绝对路径 | 400 |
| 非 GET/HEAD | 405 + Allow |
| 会话没有状态文件 | 200，depth: 0 的空栈（不是 404） |

三点实现说明：

- 它不继承栅栏。 raw WebServer 路由不吃 connection 的鉴权，所以端点自己调 connection.requestRejection(req)——与第一方 API 同一道 Host/Origin + 浏览器 cookie 校验。这条路径实测过：带 cookie 200、匿名 401。
- 只读。 端点只暴露 getSnapshot；关闭任务仍走 focus_complete 或 /focus。写入面需要单独的安全设计，不在本版本内。
- 可选激活。 webServer / connection 都不写进 inject（终端与 headless 组合没有它们，硬依赖会让插件整个 pending），而是用 ctx.inject(['webServer'], …) 等服务出现后再注册；connection 在每次请求时解析——两者都 inject: [webRuntime]，激活顺序不定，捕获一次会把 undefined 存下来（这个 bug 我踩过，表现为端点一直 503）。

手动验证（宿主起来后）：

1) 用启动时打印的 URL 换浏览器 cookie（303 + Set-Cookie） curl.exe -i "http://127.0.0.1:3080/?token=<token>"

2) 带 cookie 请求快照 curl.exe "http://127.0.0.1:3080/api/dsh-task-stack/snapshot?sessionId=<id>&cwd=D%3A%5Cpath" -H "Cookie: dsh-auth-…=…"

3) 不带 cookie 必须被拒 curl.exe -i "http://127.0.0.1:3080/api/dsh-task-stack/snapshot?sessionId=<id>"

配置

在 profile patch 层的该行 config: 下配置，全部可选；Cordis 会在插件启动之前校验，越界直接拒绝加载该插件并在启动日志里指出字段（不会静默夹紧成另一个策略）。

| 字段 | 默认 | 约束 | 含义 |
| stateDir | .dsh/task-stack | 非空、相对路径 | 状态文件目录，相对会话工作区 |
| maxStackDepth | 20 | 整数 ≥ 1 | 栈上最多同时开着的任务数；超过则 focus_task 拒绝 |
| historyLimit | 100 | 整数 ≥ 1 | history 最多保留多少条完成记录，从最旧的开始裁剪 |
| statePruneDays | 0 | 整数 ≥ 0（0 = 不清理） | 插件加载时删除超过这么多天没写过的会话状态文件 |

- insert:
- id: @ray1270/dsh-task-stack
name: @ray1270/dsh-task-stack
config:
stateDir: .dsh/task-stack
maxStackDepth: 20
historyLimit: 100
statePruneDays: 30 # 可选：清掉一个月没动过的会话

statePruneDays 是尽力而为的维护动作，以 process.cwd() 为工作区、在插件加载后异步执行，只删 stateDir 里直接存放的 .json：

- 文件的 mtime 就是它最后一次写入时间；
- 目录不存在、没有任何文件要删 → 静默跳过，不是错误；
- 崩在写入中途留下的 .tmp 不删（留给人工注意）；
- 每个删除都走同一把 per-file 锁，不会和正在进行的 read-modify-write 交错；
- 清理慢或失败只写一行日志，绝不影响插件激活。

状态文件

路径：<session-cwd>/<stateDir>/<sessionId>.json，一个会话一个文件，同工作区的不同会话互不干扰。

{
"version": 1,
"sessionId": "session-087e04a2-f613-413f-ab38-e3a3ff2f1e75",
"stack": [
{
"id": "task-35e0216c-75cc-472c-8e89-1fbbc05b1ac9",
"description": "给 CLI 加 JSON 导入命令", "createdAt": "2026-10-01T07:24:46.200Z", "status": "active" } ],
"history": [
{
"id": "task-c28dd757-3568-4ccb-a3b7-0ea05b81bccb",
"description": "重写导入的错误提示", "conclusion": "错误提示已改，附带单测", "createdAt": "2026-10-01T07:24:46.208Z", "completedAt": "2026-10-01T07:24:46.214Z" } ] }

- stack 里恰好只有一个 status: "active"（栈顶）；读到的文件若有多个 active，会被就地修复
- 写入是原子的：先写 <file>.<pid>.<n>.tmp → fsync → rename 覆盖，读者只会看到完整的旧文档或新文档，崩溃也不会留半截 JSON
- 同一文件的读写用 per-file 异步锁（promise 链）串行化，不同文件互不阻塞
- 文件缺失按空栈处理（不算警告）；读失败 / JSON 坏 / 版本不符 / 会话不符 / 帧结构坏 → 退化成空栈或丢弃坏帧，附一条 warnings 且从不抛异常

开发与验证

在克隆出来的仓库根目录里执行
pnpm typecheck # tsc strict（含 noUncheckedIndexedAccess / exactOptionalPropertyTypes）
pnpm build # tsc + 产物自检
pnpm test # 69 项：store 22 + tools 18 + config 12 + commands 13 + lifecycle 4 + demo
pnpm demo # 真实 ToolRuntime 里把三个工具与 /focus 跑一遍，打印 markdown 与落盘文件
pnpm probe # 无宿主装载：真 Cordis Context + 注册面断言 + 全生命周期实跑

| 脚本 | 覆盖 |
| scripts/test-store.mjs | 路径解析、文档结构、push/pop 语义、栈满/空栈、history 裁剪、200 并发压测无丢失无 .tmp 残留、坏 JSON/坏版本/坏帧/串会话降级、prune 阈值与边界、clearStack 幂等 |
| scripts/test-tools.mjs | 三个 defineTool 契约、参数校验（空串/错类型/缺参）、无 agent 报错、渲染 markdown、拒绝路径的渲染、history 裁剪对模型可见 |
| scripts/test-config.mjs | Config schema 默认值/越界拒绝/JSON schema、自定义 stateDir/maxStackDepth/historyLimit 端到端生效、手写坏文件不崩、statePruneDays 真的在加载时清理（子进程换 cwd 测） |
| scripts/test-commands.mjs | /focus 的三种输入与全部拒绝路径、命令与工具共用同一份状态、坏文件降级为 warning |
| scripts/test-lifecycle.mjs | 用真实 ToolRuntime + 真实子 fiber：加载→卸载→重载无残留、无 "already registered"、store 可重建 |
| scripts/demo.mjs | 可读演示：真 registry 上跑完整生命周期与 /focus，打印模型侧 markdown 与状态文件 |
| scripts/probe-load.mjs | 真实 Cordis Context 里 apply，断言三个工具 + /focus 都注册，并实跑一次完整生命周期 |

宿主侧的 loader 集成由工作区根目录的 ../loader-harness.mjs 验证（走真 @deepseek-ai/cordis-plugin-loader，四种模式：裸名/相对/坏锚点/非法配置）。

发布

0) 本地全绿（prepublishOnly 也会再跑一遍 build + test）
pnpm build && pnpm test

1) 登录（首次）
npm login

2) 预览包里到底装了什么，并让发布闸门跑一遍（不发布）
npm pack --dry-run

3) 发布bash
npm publish --access public # scope 包首次发布必须显式 --access public

要点：

- 发布闸门挂在 prepack 上（pack 与 publish 都会触发），由 scripts/release-check.mjs 用纯 Node 顺序跑 10 步：typecheck → build → check-build → probe → 五套测试 → demo。它不调用任何包管理器，所以不会被 PATH 上那个会写 crashpad 日志并异常退出的 pnpm 干扰；任一步失败会以自己的输出退出，npm publish 会如实报出真正的原因。
- 想单独跑闸门：node scripts/release-check.mjs；
- files 只包含 lib、两份 patch、README.md——src 与 scripts 不进包（lib 由闸门里的 build 步骤保证是最新的）；
- 包名与 cordis.patch.yml 里的加载行 name 必须一致，否则 profile 装了也解析不到。工作区根目录的 rename-package.mjs 会一次性同步所有出现位置并校验（含 YAML 引号，以及"目录名必须保持裸名"的断言）；
- 版本按 semver：修 bug 走 patch，新增工具/命令走 minor，改配置语义走 major；
- 首次发布后别人这样装：dsh plugin --profile <名称> add @ray1270/dsh-task-stack。

兼容性

- DSH：0.2.0-rc.2（开发与验证所用版本）
- 依赖：@deepseek-ai/cordis ^4.0.2、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-commands、@deepseek-ai/schemastery ^3.18.2（均为 peerDependencies，由宿主在运行时提供）
- 不注册任何 prompt section、不做自动注入

项目结构

dsh-task-stack/
├── package.json # dsh.bundle 声明；peerDependencies 声明宿主依赖 ├── cordis.patch.yml # bundle 加载行（包名，随安装生效） ├── dev.patch.yml # 免安装 overlay（./lib/index.js，随 --patch 生效） ├── tsconfig.json ├── LICENSE # MIT ├── .github/workflows/ci.yml # 每次 push 跑同一个发布闸门 ├── src/ │ ├── index.ts # 插件入口：name / inject / Config / apply │ ├── tools.ts # 三个 defineTool：描述、schema、渲染、执行 │ ├── commands.ts # /focus 斜杠命令 │ ├── store.ts # 路径解析 + 原子写入 + per-file 锁 + 容错读取 │ └── types.ts # 共享类型与默认值 └── scripts/ ├── release-check.mjs # 发布闸门：10 步顺序执行（CI 与 prepack 共用） ├── test-store.mjs # 状态层 22 项 ├── test-tools.mjs # 工具层 18 项 ├── test-config.mjs # 配置与边界 12 项 ├── test-commands.mjs # /focus 13 项 ├── test-lifecycle.mjs # 真实 ToolRuntime 卸载/重载 4 项 ├── probe-load.mjs # 无宿主装载 + 全生命周期实跑 ├── demo.mjs # 可读演示 ├── check-build.mjs # 构建产物自检 └── publish-release.mjs # tag → 发布（可本地干跑）

发布流程

推一个 v tag 就会自动发布到 npm 并建 GitHub Release（.github/workflows/release.yml）： powershell

1) 升版本（改 package.json 的 version），确认闸门全绿

pnpm release-check

2) 提交并推 tag —— 这一步触发自动化，之后无需手工操作

git commit -am "chore: release 0.3.0"
git tag -a v0.3.0 -m "v0.3.0"
git push && git push origin v0.3.0

自动化做四件事：装依赖 → node scripts/publish-release.mjs --tag $GITHUB_REF_NAME（内部跑 npm publish，其 prepack 就是那套发布闸门）→ 产出 tarball → 建 Release 并附上该 tarball。

需要一次配置：在仓库 Settings → Secrets and variables → Actions 加一个 NPM_TOKEN（npm 的 Automation 或 Publish token，且必须勾选 Bypass 2FA；fine-grained token 目前还不能发布）。

三种 ref 的三种行为

脚本按 ref 判断意图，因为 workflow_dispatch 拿到的 GITHUB_REF_NAME 是分支名而不是 tag：

| 触发 | ref | 行为 |
| 推 v0.3.0 tag | v0.3.0 | 校验 tag == package.json 版本 → 发布 |
| Actions 页面手动 Run workflow | main | 校验模式：报告凭据状态、不发布、成功结束 |
| 普通分支 push | 分支名 | 同上（CI 工作流才是分支上的主验证） |

推真实 tag 但与 package.json 版本不符时仍然直接失败——用错版本号发布会污染 npm，那是事故而不是可以抹平的小事。

两个刻意的设计，都是被事故逼出来的

- tag 必须与 package.json 的版本一致，否则失败。
- 已发布过的版本视为成功，而不是报错。因为「registry 已记录版本、客户端却收到失败响应」会让这个版本号永久不可用（0.2.0 就是这么丢的：重试同一个版本号只会得到 409）——所以重试必须能收敛。

可以本地干跑看 CI 会做什么： powershell
node scripts/publish-release.mjs --dry-run # 只决策，不发布
node scripts/publish-release.mjs --tag main # 校验模式（等同手动触发）

许可

MIT