waywaywayway/deepseek-harness-lazy-capability

deepseek-harness-lazy-capability

LiangShen Lazy / 梁神按需模式 — 默认最小 · 按需申请 · 最小授权 · 永不 dump 完整 registry

一个实验性的 DeepSeek Harness agent preset。

English README

起点：这个项目是从哪来的

这个项目是在 梁神模式（LiangShen） 原作者的工作基础上继续做的实验。

原梁神模式最重要的启发，是先把 DeepSeek V4 Pro 放进一个非常干净的 Minimal 环境，
只保留最基础的工具（持久 bash + str_replace_editor，46 字符 persona，无 runtime
context、无 workspace 指令、无 Skill catalog），再在后续阶段恢复 Harness 能力。
这个 Clean bootstrap 不是概念，是原作者已经实现并跑通的东西。

我在实际使用中发现：模型一旦晋级、把完整插件 registry、Skill、runtime context 和大量
tool/context 恢复回来，行为轨迹又会发生明显变化。

所以我沿着梁神模式的思路继续做了一步：

不再"一次晋级恢复全部工具"，而是改成"默认极简，需要什么能力才临时开放什么，用完自动收回"。

也就是说，这不是要替代梁神模式，而是从梁神模式的 Minimal bootstrap 思路延伸出来的一种
Lazy Capability / 按需工具实验。

原梁神模式：                        本项目：
Minimal                            Minimal
→ 检测锚点                          → 需要 Browser？
→ promotion 晋升                    → 只开 Browser
→ run_code + 完整 registry          → 用完收回
→ runtime context / Skill 全回来     → 回到 Minimal

区别不在于"第一个请求很小"——梁神模式已经做到了——而在于第一百个请求依然很小。

致谢 / Acknowledgements

本项目基于 梁神模式（LiangShen Mode） 的 Minimal bootstrap 思路继续实验。

梁神模式的原作者首先实现并验证了：在 DeepSeek Harness 中，可以在会话初期压缩
system / context 和 tool surface，使 V4 Pro 先工作在接近官方 Minimal 的环境中，
再恢复完整 Harness 能力。

本项目的核心改动，是保留这一 Minimal-by-default 思路，但取消一次性 Full Harness
promotion，改为 capability-on-demand：需要什么工具才开放什么工具，使用完成后重新收紧。

感谢梁神模式原作者提供的实现和实验基础。没有原项目的 Minimal bootstrap，
这个实验不会这么快出现。

本项目部分实现直接派生自原 LiangShen 项目的代码（capability-broker.mjs 中约 11%
的有效代码行与其 tool-bootstrap.mjs 相同：按会话隔离机制、两个 hook 的过滤骨架、
persona section 常量、配置辅助函数；agent.cordis.yml 为其组合的改编）。
具体版权与许可证信息见 NOTICE，逐行来源审计见 PROVENANCE.md。

上游链条：dsh-anchored-standard（MIT）
与 DeepSeek Harness 内置 minimal / standard preset（MIT）。

这是社区 preset，不是 DeepSeek 官方项目，与 DeepSeek 无从属或背书关系；
仓库名的 deepseek-harness- 前缀只说明它挂在什么上面。

状态：v0.1.0-beta，实验性。 功能已用真实会话验证（见实测结果），
但它挂在 DSH 的内部 hook 上，Harness 升级可能改变这些接口。请锁定 DSH 版本，
升级后重新跑一遍验证。当前实现已作为实验基线冻结，在拿到真实 A/B 数据前不再加功能。
行为轨迹与 raw session 的实验记录见 EXPERIMENTS.md。

它做什么

会话从 4 个工具的最小面开始：基础 shell（macOS/Linux 是 bash，Windows 是 pwsh）、str_replace_editor、request_capability、release_capability。模型自己判断任务需要额外能力时，
向唯一的 broker 申请一个具名能力，只拿到那一类能力的工具，不再使用后自动收回。

为什么不用"一个超级工具"

常见的偷懒做法是把所有插件塞进一个 run_code 式的工具后面。那只是换皮的完整 Harness：
模型照样够得到一切，schema 预算只是搬进了生成的 SDK。本 preset 绝不这么做——
未授予的能力不在 wire 上，也不可调用。

环境要求

| | |
|---|---|
| DeepSeek Harness | 0.1.0-rc.6（开发与验证所用版本） |
| Node.js | ≥ 22.19（以你的 DSH 构建要求为准） |
| 验证路径 | Web profile 的 preset 路径 |
| 插件 | 不要求额外第三方插件。部分 optional capability 只有宿主 registry 实际存在对应工具时才能使用；解析不到的能力会被拒绝。 |

安装

Linux / macOS：

bash
git clone https://github.com/waywaywayway/deepseek-harness-lazy-capability.git
cp -R deepseek-harness-lazy-capability/presets/lazy-capability \
"${DSH_HOME:-$HOME/.dsh}/.agent-presets/"

Windows PowerShell：
powershell
git clone https://github.com/waywaywayway/deepseek-harness-lazy-capability.git
$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $HOME '.dsh' }
$dest = Join-Path $dshHome '.agent-presets'
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item -Recurse -Force '.\deepseek-harness-lazy-capability\presets\lazy-capability' $dest
这就是全部安装步骤——复制一个 preset 目录；不需要额外安装第三方 npm 包，也不需要修改 profile。
DSH 的 preset 发现不做缓存，所以正在运行的实例也能立刻看到，不用重启：
新建会话 → 预设选择器 → 梁神按需模式 (LiangShen Lazy)。

要让它成为新会话默认，在 $DSH_HOME/settings.yaml 加：
yaml
agent-presets:
default: lazy-capability

卸载
bash
rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets/lazy-capability"

没有别的引用点。其它 preset、插件、Skill、provider、密钥和正在跑的会话都不受影响
（每个会话锁定在自己创建时组合的 preset）。

工作原理

四个 DSH 公开 API，不 fork、不 vendor 任何 Harness 源码：

| Hook | 作用 |
|---|---|
| system-prompt/assemble | 把工具表过滤成 base + 已授权能力；清空 runtime contexts；section 只留 persona |
| agent/pre-step | 丢弃全部注入型 pre-step 消息，只放行 kind: user，以及已授权能力声明的消息类型 |
| session/event | 监听 step/end / turn/end 让授权过期 |
| ctx.tools.guard(...) | 执行层拦截：拒绝执行当前会话未授权的任何工具 |

guard 很关键：藏 schema 是呈现，不是权限。对已锁工具的幻觉调用、重放调用会在 registry
层被拒，并告诉模型去申请对应能力。

授权状态存在以 session 对象为键的 WeakMap 里，所以同进程的两个会话互不可见
（已实测）。

授权时长

| scope | 何时收回 |
|---|---|
| one_step（默认） | 第一个“结束时没调用过该能力”的 step |
| current_task | 本轮 turn 结束 |
| session | 只能由 release_capability 释放 |

one_step 不等于“一次调用”：只要该 step 用到了它就继续保留，所以多步浏览流程不会被打断；
模型不再用它之后一个空闲 step 就收回。模型也可以用 release_capability 提前交还。

配置

全部在 agent.cordis.yml 的 capability-broker 行里。
yaml
- id: capability-broker
name: ./capability-broker.mjs
config:
永久底座；基础 shell 随平台切换
baseTools: !!js "process.platform === 'win32' ? ['pwsh', 'str_replace_editor'] : ['bash', 'str_replace_editor']"
brokerTool: request_capability
releaseTool: release_capability
messageSources: [user]                  # 永远放行的消息类型
defaultScope: one_step
logPath: ~/.dsh/logs/lazy-capability/broker.jsonl   # 可选审计日志，默认关闭
logRegistrySnapshot: true
capabilities:
browser:
description: Drive the browser bridge to read live web pages.
prefixes: [browser_]                # 显式命名空间，不是通配符
skill:
tools: [skill, skill_manage]        # 显式工具名
messageSources: [skill-catalog]     # 该能力才打开的消息类型

能力只能通过显式工具名和/或显式命名空间前缀映射。以下配置插件会直接拒绝加载：

- 能力 id 为 、all、full、everything、admin、any、root、registry、
run_code、run_code_full_registry
- 任何映射到 run_code 的条目
- 含  或短于 3 个字符的前缀
- 映射不到任何工具的能力

宿主没装对应插件的能力会解析出 0 个工具，申请时返回 Capability unavailable: ，
会话保持最小面。插件启动失败也不会 fallback 到完整 registry。

增加一个能力

先在 agent.cordis.yml 挂上插件行（让工具存在），再加一条 capabilities: 映射。
MCP 服务已由 dsh-mcp-client 按 mcp____ 命名，所以每个批准的
服务一条前缀：
yaml
mcp:example:
description: The approved example MCP server.
prefixes: ['mcp__example__']

实测结果

在一台组合后 registry 共 51 个工具的参考机上，通过读取真实会话日志的
request/header 事件测得（不是看 UI）。systemChars 是组装后的 system prompt，
headerBytes 是整个序列化请求头（system + 全部 tool schema）。

| 会话状态 | wire 上的工具 | systemChars | headerBytes |
|---|---|---|---|
| 默认（每一步） | 4 — bash（Windows 为 pwsh）、str_replace_editor、request_capability、release_capability | 46 | ~4.8 KB |
| 授权 web_search | 5 | 46 | ~5.1 KB |
| 授权 vision | 5（vision_toolkit_activate） | 46 | ~5.2 KB |
| vision 激活后 | 16（动态注册的 10 个 vision_） | 46 | ~17.9 KB |
| 授权 skill | 6（skill、skill_manage） | 46 | ~6.7 KB |
| 授权 browser | 15（11 个 browser_） | 46 | ~10.3 KB |
| 释放 / 自动收回后 | 4 | 46 | ~4.8 KB |

这些会话里观察到：

- 十步编码会话（读仓库 → 检查 → 跑测试 → 改代码 → 重跑）10/10 个请求都在四工具面上，
因为确实不需要额外能力，模型一次都没申请。
- 模型自主申请。 给它一个需要查实时文档的任务，它自己申请了 browser；
发现浏览器桥没连上后主动释放，改申请 web_search。
- 自动收紧确实触发。 web_search 在用完后的一个空闲 step 被自动收回。
- 动态注册能被正确归属。 激活 vision 工具箱会在运行时注册 10 个新工具，
vision_ 前缀映射无需改配置就把它们归到了 vision。
- system prompt 从不膨胀。 所有状态都是 46 字符——不存在 46 → 59,096 的晋升突变。
- 零注入。 已验证会话中每条 user/message 的 source.kind 都是 user：
没有 runtime context 快照、没有 workspace 指令、没有插件公告、没有 skill catalog。
- 未知能力被拒绝。 让它申请 "database" 能力，broker 返回 Capability unavailable，
会话保持最小面。
- guard 拦住了越权调用。 指示模型不申请就直接调用 skill，它照做了，registry 原样拒绝：
Error: skill is locked. This session is minimal by default; call request_capability for the capability that provides it.
- 双会话隔离。 A 会话以 scope: session 持有 browser（15 工具）期间，
同进程的 B 会话跑完整任务全程 4 工具；之后 A 仍然持有它的 15 个。

用 tools/ 里的脚本可复现。

它不是安全沙箱

本 preset 减少的是模型看得见、调得动的工具与上下文面，仅此而已。Capability Broker 不是安全边界。
bash 能访问什么取决于底层 DSH sandbox / 宿主执行策略；网络是否可用也取决于宿主环境。
需要安全边界请用 DSH 自己的 sandbox 与审批策略——两者互补，不是替代。

已知限制

- 默认不挂载：plan mode、goal、todo、jobs、workflow，以及
read/write/edit/grep/glob 文件工具。bash 加编辑器已经覆盖它们，
而挂不上的工具也就无法被申请。需要的话自己包一个能力挂上去。
- skill catalog 不会到达。 dsh-tool-skill 只在 turn 入口按可见性发目录，
回合中途授权赶不上这个窗口。实际用法是模型按精确名加载 skill，名字用 shell 自己找。
当前 DSH API 不支持"只返回相关的单个 Skill"。
- 走 pre-step 注入通道的内容一律被丢弃，除非某个已授权能力声明了它的消息类型。
这是本 preset 的目的，但只靠这条通道说话的插件会显得没反应。
- @deepseek-ai/dsh-headless 不会 mount agent preset。 它创建 agent 时不加入任何
preset，所以 headless 会话看到的是 host 平面的工具而不是本 preset。
做基准测试必须在 setup 里调 agentPresets.mount(agentCtx, id)——
tools/verify-runner.mjs 里就是那四行。
- 改了 preset 需要重启。 发现是实时的，但一个 preset 的常驻挂载一旦组合就会在
进程生命周期内复用。

兼容性

验证环境：DSH 0.1.0-rc.6、macOS、Node 26、DeepSeek deepseek-v4-pro。
所用 hook（system-prompt/assemble、agent/pre-step、session/event、
ctx.tools.register、ctx.tools.guard）都是公开插件 API，但没有跨版本兼容承诺。
DSH 升级后请重跑 tools/，确认默认面仍是四个工具。

许可证

Apache License 2.0，见 LICENSE。选择它是为了与所派生的梁神模式 preset 一致。