本地编码智能体在处理长周期任务时，通常依赖松散的 STATUS.md 维护约定。这种做法容易导致状态脱节、文件结构混乱，甚至因为频繁读取文件而浪费 Token。dsh-local-long-horizon 插件将这一过程转化为由宿主管理的结构化 Vault，并提供经过验证的 Agent 工具，确保任务状态在 DeepSeek Harness Web UI 中可见且可维护。
核心功能¶
该插件提供以下核心能力：
- 宿主管理状态：状态存储在宿主侧，而非依赖 Agent 自行维护文件。
- 结构化 Vault：数据存储在 JSON 格式的 Vault 中，
STATUS.md是其单向投影。 - 工具验证：提供一系列经过验证的 Agent 工具，用于读写状态。
- 注入文件：提供一个极小的注入文件用于断点续记。
- UI 集成：在右栏提供“Long horizon”面板，并在 Composer dock 提供芯片显示。
- Agent 工具集：包含初始化、获取、设置下一步、设置进行中、完成、阻塞/解锁、开关控制等工具。
安装与启用¶
安装插件需要使用 DeepSeek Harness 的 Web Profile。
1、在终端执行以下命令安装插件：
dsh plugin --profile web add dsh-local-long-horizon
2、安装完成后，重启 dsh web 服务以加载插件。重启后，刷新浏览器页面即可看到新功能。
典型用法¶
启用后，Agent 可以通过工具链接管任务状态。
1、初始化：使用 status_init 启用长周期追踪。
2、设置下一步：使用 status_set_next 替换 Next 列表中的项目（数量限制为 0-3）。
3、设置进行中：使用 status_set_inflight 标记当前正在执行的任务，必须提供非空的 summary。
4、标记完成：使用 status_mark_done 记录已完成的任务，推荐附带 verify 字段。
5、维护 AGENTS.md：在项目根目录保留一个 AGENTS.md 文件作为“胶水”，DSH 会将其注入到 Agent 指令中，指导 Agent 读取注入文件并使用状态工具。
Agent 工具列表¶
| 工具名 | 功能 |
|---|---|
status_init |
创建或刷新 Vault，开启长周期追踪 |
status_get |
获取完整的结构化记录 |
status_set_next |
替换 Next 列表（最多 3 项） |
status_set_inflight |
设置当前进行中的任务 |
status_clear_inflight |
清除进行中的任务 |
status_set_phase |
设置短周期的阶段标签 |
status_mark_done |
标记任务完成（可附带 verify 和 rotateNext） |
status_block / status_unblock |
标记或取消阻塞状态 |
status_set_enabled |
开启或关闭长周期追踪 |
status_ping |
探测 Host 健康状态 |
注意事项与架构¶
系统要求¶
- Node.js：必须安装 Node.js >= 20。
- DSH 版本：已验证兼容 DeepSeek Harness
0.1.7-rc.2。
限制与约束¶
- Next 限制：Next 列表最多只能容纳 3 个项目，第四个会被拒绝。
- In-flight 要求：设置进行中任务时，
summary字段不能为空。 - Done 记录：标记完成时，
verify字段是推荐的，缺失时仅会警告。 - 开关控制：当追踪功能关闭时，所有会修改状态的工具都会拒绝执行，注入文件会冻结为单行
DISABLED。 - 同步提示：仅在面板中显示同步提示（如 git 分支变化），Dock 芯片不显示。
数据流向¶
- Vault：数据源是
~/.dsh/storages/dsh-local-long-horizon/<taskId>.json。 - 注入文件：智能体实际读取的绑定状态文件为
<cwd>/.dsh/task-status-inject.md。 - Markdown：
<cwd>/STATUS.md是根据 Vault 内容生成的，每次变更都会被覆盖。 - 无文件依赖：插件没有对宿主文件系统的读取依赖，通过 DSH 提供的
ctx.tools服务注册工具。
总结¶
dsh-local-long-horizon 通过将状态管理从 Agent 的“软约定”转变为宿主的“硬结构”，解决了长周期任务中的状态追踪问题。配合 DeepSeek Harness 的 Web UI，它为开发者提供了一个可视化的任务看板和可靠的状态回写机制。
