zzzmmmnn/dsh-openkapsel

dsh-openkapsel

CI
Listed on dsh-plugin.org

面向 DeepSeek Harness 的 OpenKapsel 工作区桥接。它将远程
OpenKapsel 工作区转换为模型可见的工具：提供以 /w/ 结尾的只读工作区
URL 及其匹配的控制令牌，智能体即可列出/读取/写入文件、运行 Shell 任务，并调用其他 OpenKapsel REST
接口。在捆绑的仅远程预设中，模型没有主机文件系统或主机 Shell 工具。

该桥接复用了工作区发布的 openkapsel-rest 技能的 Python
辅助脚本（openkapsel_http.py 和 openkapsel_config.py），并将其内置在
skill/ 下。每个 kapsel_ 工具都通过
harness 主机 Shell 服务调用这两个固定脚本之一。模型无法选择脚本，也无法将该
服务用作 Shell 工具。身份验证、上下文归属
（plan_id/taskname/message）、REST 错误解码和凭据续期
均由维护中的技能代码负责。每个辅助子进程都会收到一个
显式的 DSH workspace-write 策略，该策略以该智能体的私有状态
目录为根；执行器还控制任何平台临时目录的访问。

兼容性与权限

| 领域 | 要求与范围 |
|---|---|
| DSH | 已使用 DSH 0.1.2-rc.1、web 配置文件以及捆绑的 OpenKapsel Remote 预设进行测试。该预设的 persona 字段已针对 DSH 0.1.5-rc.2 更新；更新后已确认现有会话的命令选择器可正常工作。其他配置文件未经验证。 |
| Node.js | 包声明 >=18；测试矩阵覆盖 Node.js 22 和 24。请使用你的 DSH 安装所支持的版本；本项目的 CI 未覆盖 Node.js 18。 |
| Python | 主机 PATH 中需有 Python 3.10+：Windows 上为 python，macOS/Linux 上为 python3。测试矩阵覆盖 3.10 和 3.14。 |
| 主机平台 | macOS/Linux 使用 DSH 的 Bash 执行器；Windows 使用 DSH 的 PowerShell 执行器，不使用 Bash。GitHub 安装和主机启动已在 macOS 上验证。Windows 安装及实际插件使用已由用户测试确认（2026-09-09）。Linux/Windows 自动化测试已在 CI 中配置。 |
| 外部服务 | 需要可访问的、由用户选择的 OpenKapsel Server 及其工作区 URL/控制令牌。请求及其提供的文件内容或命令会发送到该服务器。 |
| 本地访问 | 通过 DSH 的 Shell 服务运行固定的 Python 辅助脚本，并将会话凭据写入 $DSH_HOME/state/dsh-openkapsel（默认 ~/.dsh/state/dsh-openkapsel）。面向模型的主机文件/Shell 工具和 run_code 被拒绝。 |
| 凭据 | 将读取 URL 和控制令牌存储在用户的 DSH 状态目录下。Unix 使用 0600 文件和 0700 目录；Windows 依赖所属用户目录的 ACL（chmod 在那里不强制执行 Unix 权限）。自动续期可能会替换已存储的凭据。 |
| 远程权限 | 可以在远程令牌的授权范围内读取、修改和运行 Shell 命令。类型化工具只是便利手段；服务器对通用 REST 调用同样强制执行授权。 |
| DSH 策略 | read-only 拒绝远程变更和 Shell；一次性批准可以授权重试。workspace-write 和 danger-full-access 都仍受远程令牌约束。 |
| 许可证 | MIT。这是一个社区插件，不是 DeepSeek 官方产品。 |

为什么内部传输仍使用 Python

已安装的 Cordis 包可以用 Node 实现传输。此桥接保留 Python，是因为现有辅助程序已经负责续期、认证、错误解码和 Context 合并。复用它们可以避免第二套协议实现，以免随着 OpenKapsel 演进产生偏差。这不会授予模型本地 Shell：脚本路径是插件拥有的常量，参数以 JSON 形式通过 stdin 传递给固定的 Python 引导程序。

在 Windows 上需要 PATH 中有 python，在 macOS/Linux 上需要 python3。

布局

index.js                宿主侧 Cordis 插件和类型化远程工具
bundle.js               仅安装预设的配置文件引导程序
cordis.patch.yml        DSH 包入口点（无全局工具防护）
preset-install.js       共享的、更新安全的预设安装程序
skill/openkapsel-rest/  内置的 REST 技能和固定的 Python 辅助程序
preset/kapsel/          在 DSH 模式选择器中显示的仅远程代理预设
bin/install-preset.js   将预设安装到 DSH 用户预设根目录
cordis.example.yml      带注释的桥接行
tests/                  工具目录和远程隔离测试

安装

从 GitHub 安装到 DSH web 配置文件：

dsh plugin --profile web add github:zzzmmmnn/dsh-openkapsel

无需手动符号链接或本地源代码检出。DSH 将该包作为配置文件依赖进行管理。其 dsh.bundle 补丁会在配置文件启动时加载一个轻量级引导程序。该引导程序会安装 OpenKapsel Remote 预设；它不会注册工具、启用仅远程防护或更改默认预设。只有在你选择 OpenKapsel Remote 时，工具和防护才会加载。

未改动的包管理预设会在启动时自动更新。现有的相同手动安装会被采用。本地修改过的预设会被保留并报告，而不是被覆盖。要显式替换某个预设：

dsh plugin --profile web exec dsh-openkapsel-install-preset --force

目标为 $DSH_HOME/.agent-presets/kapsel，当 DSH_HOME 未设置时为 ~/.dsh/.agent-presets/kapsel。重启 DSH。之后新会话可以在随附模式旁选择 OpenKapsel Remote。现有非空
会话保留其原始预设。通过 kapsel_config 提供你的 OpenKapsel Workspace URL 和匹配的控制令牌，以连接远程工作区。

不带 --force 的安装命令仍可用于手动设置。
移除该软件包不会删除已复制的预设或会话凭据。
卸载后，如果没有其他配置文件使用 $DSH_HOME/.agent-presets/kapsel，请将其删除。预设根目录由使用相同 DSH_HOME 的配置文件共享。

版本 0.7.1 将捆绑预设的 persona 字段从 text 改为 prefix，这是 DSH 0.1.5-rc.2 所要求的。旧字段可能会导致现有的 OpenKapsel 会话在 DSH 升级后无法挂载。更新插件后重启 DSH，以便引导程序可以刷新未改动过的已安装预设；如果你自定义了该预设，仅当你打算替换自己的更改时，才使用上面的 --force 安装命令。

版本 0.7.0 的打包捆绑包已在 macOS 上安装到全新的临时 DSH 配置文件中：配置文件组合、Web Host 启动和自动预设创建均通过，且未更改默认的 standard 预设。新的引导程序还具有自动化的安装、更新、自定义保留和隔离测试。

较早的 GitHub 安装和配置文件作用域安装程序已在本地验证；安装的软件包通过了其测试，并且 DSH Web Host 在 macOS 上成功启动。Windows 安装和实际插件使用也已在 2026-09-09 由用户测试确认。在 Windows 上，请从 PowerShell 运行这些相同的命令；确保 python --version 解析为 Python 3.10 或更高版本。不需要 Bash。

仅远程预设

在 DSH 预设选择器中选择 OpenKapsel Remote：

不要将 dsh-openkapsel 添加到 standard 或 minimal：两者都会暴露主机本地工具。捆绑预设有意省略了主机 Bash/PowerShell、文件系统/搜索/编辑器、作业控制、本地 AGENTS.md 发现和本地技能发现。它仅保留 OpenKapsel 桥接以及 skill、ask_user_question 和 todo_write。

该插件还安装了一个故障关闭工具防护。因此，意外组合未声明或本地工具会导致执行被拒绝，即使未来的预设编辑使该工具对模型可见。DSH 的可选 run_code 呈现传输被拒绝。仅远程模式显式选择原生工具，因此模型编写的代码不会通过主机代码运行时执行。

DSH 沙箱模式映射

桥接会为每次工具调用从 ctx.sandboxPolicy 解析当前策略：

| DSH 模式 | 远程 OpenKapsel 行为 |
|---|---|
| read-only | 允许配置、状态、Discovery、文件系统读取以及通用 GET/HEAD；拒绝远程变更和 Shell 执行 |
| workspace-write | 允许 OpenKapsel 令牌授予的每一项能力 |
| danger-full-access | 与 workspace-write 相同的桥接行为；它绝不会扩大 OpenKapsel 令牌 |

被拒绝的变更可以通过一次调用审批请求进行重试：

{
"sandbox_permissions": "workspace-write",
"justification": "Update the requested remote configuration file once."
}

该插件在联系远程变更端点之前，会将请求委托给 DSH 的审批服务。审批不会改变会话的持久沙箱模式。拒绝、取消、缺少审批通道、字段格式错误以及非扩大权限的请求，均会以失败关闭方式处理。

捆绑预设中的桥接条目为：

- id: tool-kapsel
name: 'dsh-openkapsel'
config:
taskname: dsh
enforceRemoteOnly: true

dsh-openkapsel 会使用宿主机的 shell、tools、skills 和 sandboxPolicy 服务，但不发布任何服务。请将其挂载到专用代理预设中，而非全局挂载。

用法

1. kapsel_config(workspace_url, control_token) 会将凭据存储在此 DSH 会话的私有插件状态中，然后选择或创建一个活动根 Plan 用于变更归属。重新运行它可以切换工作区或轮换凭据。
2. 在执行非平凡操作之前，先通过 skill("openkapsel-rest") 加载权威的 REST 参考。
3. 通过远程工具进行操作：

| 工具 | 用途 |
|---|---|
| kapsel_config / kapsel_status | 配置或检查活动工作区 |
| kapsel_plan_update | 通过结构化汇报更新、重新指定父级、取消或完成一个 Plan |
| kapsel_fs_list / kapsel_fs_read / kapsel_fs_stat | 读取侧文件系统 |
| kapsel_fs_write / kapsel_fs_replace | 远程文本写入/编辑 |
| kapsel_shell_exec / kapsel_task_output | 在服务器或映射客户端上运行 Shell 任务并轮询其输出 |
| kapsel_mappings | 列出映射的客户端目录、在线状态以及公布的执行/RPC 能力 |
| kapsel_archive | 浏览 ZIP/tar 归档文件，或在不提取的情况下读取有界成员；映射的归档文件使用客户端 RPC |
| kapsel_rpc | 统一的动态映射 RPC 入口：检查每个操作的 schema、write 和 execution；同步操作直接返回，任务操作返回持久的客户端任务 ID；写入操作使用 DSH 审批 + Plan/Context，并且需要可写映射 |
| kapsel_fs_copy / kapsel_fs_move / kapsel_transfer | 在工作区与客户端存储之间复制或移动，然后检查/取消/恢复异步传输 |
| kapsel_recycle | 列出、恢复或显式清除所选存储根中的项目 |
| kapsel_client_task | 列出/启动旧版客户端 Shell 任务，并检查/中断/终止由 kapsel_rpc/kapsel_shell_exec 返回的统一客户端任务 ID；RPC 任务不接受 stdin |
| kapsel_http | Context、Memory、共享、预览、计划以及其他 REST 接口 |
对于客户端映射，首先调用 kapsel_mappings 并检查客户端报告的平台和沙箱模式。kapsel_client_task 接受一个 argv 数组和一个相对于客户端导出目录的 cwd；它不使用服务器 Shell。客户端任务输出以 base64 形式返回，并带有 next_offset 游标。未沙箱化的客户端任务具有该客户端的操作系统账户权限。变更操作使用与现有写入工具相同的 DSH 审批和 OpenKapsel Plan 归属。捆绑技能的 references/mappings.md 详细说明了 REST 响应和失败状态。

kapsel_shell_exec 接受 target: "auto"（默认）、"server" 或
"client"。当 cwd 位于某个已连接客户端的映射内时，Auto 会选择该客户端
（例如 laptop/project），否则选择服务器。缺失/被拒绝的客户端会失败，而不会回退到服务器。客户端需要 OpenKapsel 1.60.0+ 以及一个已启用的可写执行映射。其自身的操作系统、沙箱和限制适用；
服务器 /env 设置不会被注入。返回的任务 ID 可与
kapsel_task_output 以及通过 kapsel_http 使用的标准 /tasks 控制一起使用。
客户端 stdout/stderr 合并到 stdout 中；客户端 stdin 块最多为 16 KiB。当需要字面客户端 argv 时，请使用 kapsel_client_task。

kapsel_http.json 始终是一个 JSON 对象。端点字段应放在其中，
而不是放在其旁边。上下文管理端点会被特殊处理，因为
它们的 plan_id 字段描述的是 Context 图，而不是普通的
操作归属；对于 Plan 更改，请优先使用 kapsel_plan_update。

每个 DSH agent 通过 agent.id 单独作为键。凭据位于
$DSH_HOME/state/dsh-openkapsel//.openkapsel.env；活动 Plan 和
taskname 值保存在一个以 agent 为键的 WeakMap 中。本地项目 cwd 不
用于凭据或远程工作区选择。一个绝对的 stateDir
插件选项可以替换默认的私有状态根目录。

对于已记录的变更，taskname 按以下顺序解析：当前工具调用，
然后选定的活动 Plan/session 值，然后由
kapsel_config 设置的值，然后是插件的预设配置，最后是 dsh。
空值和仅含空白字符的值不会抑制此回退。当省略 plan_id 时，活动
Plan 会自动选择；在 Host 重启后选择已持久化的 Plan 也会恢复该 Plan 的 taskname。缺失或为空的 message 会收到一个简短的默认操作消息。

安全说明

类型化工具是便捷包装器，而不是额外的权限边界。
kapsel_http 暴露所选凭据可用的 REST 接口；
远程服务器强制执行端点、路径和能力授权。DSH
只读模式还会拒绝变更型 HTTP 方法和 Shell 执行。
这假定 GET/HEAD 端点遵守读取语义；项目应用程序
路由实现自己的行为和授权。

当前 DSH Shell 服务接受命令字符串，而不是 argv 数组。
桥接通过标准输入将辅助路径和参数以 ASCII JSON 形式发送给固定的 Python 引导程序。模型输入永远不会进入 Host Shell 命令文本。NUL 参数会被拒绝。生成的测试通过 Unix 上的 Bash 以及 Windows 上的 PowerShell 7/Windows PowerShell 5.1 对引号、换行符、替换、反斜杠、空字符串和 Unicode 进行往返测试。辅助程序保留其 DSH 沙箱策略，其退出码通过 PowerShell 传播。

版本 0.5.0 将包、安装程序命令和默认状态目录重命名为 dsh-openkapsel。升级后请重新安装预设并再次初始化凭据。若要复用现有的私有状态目录，请显式将 stateDir 配置为该目录。工具名称（kapsel_）和 kapsel 预设 ID 保持不变。

开发检查

运行 npm ci 和 npm test。GitHub Actions 在 Linux 和 Windows 上检查 Node.js 22/24 与 Python 3.10/3.14，包括辅助参数往返测试和远程权限测试。

运维说明

- 控制令牌仅存储在会话私有的凭据文件中，Unix 模式为 0600（Windows 使用继承的目录 ACL）。令牌及其主机私有路径都不会在工具结果中返回。
- 工作区 URL 中的读取令牌是只读的；控制令牌可解锁写入、Shell、Context、Memory 和共享功能。
- 每次变更都归属于一个带有 taskname 和 message 的活动 Plan。
- 令牌仅发送到工作区源或文档化的传输路径，绝不发送到预览或公开共享 URL。
- 面向模型的守卫仅允许 kapsel_、skill、ask_user_question 和 todo_write。

验证

npm test

测试断言捆绑预设不包含本地 Shell/文件系统提供程序，并针对独立的 HTTP 工作区运行两个模拟的 DSH 代理。集成测试验证每个远程工作区仅接收自己的写入，本地哨兵保持不变，且凭据仅存在于私有状态根目录下。

只读 RPC 工具

版本 0.9.0 新增了 kapsel_git（status/diff/diff_stat/log/show/ls_files）、kapsel_fs_read_many、kapsel_fs_manifest 和 kapsel_fs_search。此契约需要支持 RPC 插件任务的 OpenKapsel（提交 95392b5 或更高版本）。Git 读取操作独立于 Shell/客户端执行权限，并使用有界的净化快照。Git 的 add、commit、restore 和 checkout 被声明为 write=true, execution=task；Archive 的 create 和 extract 使用相同的持久任务模型。kapsel_rpc 是唯一的动态映射 RPC 入口点：kapsel_mappings 发布每个族的描述以及每个操作的 description、JSON input_schema、布尔值 write 和 execution（sync 或 task）。任务操作会立即返回统一的 client.. ID；使用 kapsel_task_output 轮询它，或使用 kapsel_client_task 检查/控制它。该任务在提供程序
客户端进程保持存活时的断开/重连。绝不要重放不确定的写入任务启动；而应重连并查询/列出返回的或候选的任务 ID。write=true 仍然使用 DSH 审批加上 OpenKapsel Plan/Context，并要求映射在管理上可写。kapsel_archive 仍然是用于本地或已映射归档的读取预览便捷工具；Archive 的创建/解压使用 kapsel_rpc。

通用 HTTP 工具将 POST fs/read_many 和 fs/manifest 识别为只读。对于 mappings//rpc//，它会查询实时操作的 write 元数据：读取绕过变更审批，而写入使用审批和 Plan 归属。Archive 预览使用 GET archive/list 和 archive/read。其他 POST 操作保留其现有的防护。查询值可以是数组以发送重复参数，例如 include: [".py", "*.js"] 或 file: ["a", "b"]。随附的 REST 技能与主 OpenKapsel 项目保持同步。映射 RPC 回复默认使用 90 秒的服务器截止时间；捆绑的 HTTP 辅助程序等待 120 秒，而 DSH 辅助进程预算为 130 秒，因此包装器通常不会在服务器之前超时。

客户端重连与可移植文本

捆绑的 REST 参考跟踪 OpenKapsel 1.60.1。重连持久化需要客户端 1.58.0+；显式文本编解码器和字面换行处理需要服务器 1.59.0+ 以及用于直接映射 RPC 的客户端文件 API v3。

网络断开不会停止正在运行的客户端进程中的任务。重连并列出/查询原始任务 ID 以获取输出和退出状态，包括离线完成的任务，或发送 stdin/interrupt/kill。截止时间在离线时继续。未收集的结果保留在有界的客户端内存中；注册表限制为 max_tasks + 4。通过已完成输出进行读取会将结果标记为已收集；已收集的结果有一小时/四条记录的保留期，并且可能因容量而更早被逐出。客户端进程重启不会恢复任务。不要自动重放响应已丢失的启动。

文本 API 默认使用 UTF-8，而不使用主机区域设置。对于非默认编码，使用 kapsel_http：在 GET fs/read 的 query 中传递 encoding，在 POST fs/read_many、fs/write 或 fs/replace 的 json 中传递，以及在 fs/replace/batch 的每个 json.items[] 条目中传递。类型化文件工具仍然使用其现有的默认编码；它们不暴露这个新字段。

支持的编解码器包括 UTF-8/BOM、显式端序 UTF-16、Big5、GBK/GB18030、Windows-1252、Latin-1、ASCII 和 Shift-JIS。有关确切的编解码器名称和 BOM 规则，请参阅捆绑的文件参考。没有猜测或有损转换。LF、CRLF 和 CR 保持字面：精确替换必须匹配原始结尾，而新文本选择自己的结尾。仅 UTF-8 的字节游标和搜索保留其现有限制。

RPC 优先映射（OpenKapsel 1.61.0+）

kapsel_mappings 可能报告 online: true 和 mounted: false：这是正常的。
直接使用文件、搜索、复制/传输、归档和 RPC 工具；绝不要仅仅为了让这些接口工作而挂载映射或运行 Shell 命令。静态预览也使用 RPC。保持默认的 target: "auto"：映射的 cwd 在其客户端上执行，无需服务器挂载；其他工作目录在服务器上执行。

对于有意的服务器执行，cwd 映射是自动的。使用可选的 mount_mappings 数组声明其他原生文件系统依赖，该数组最多包含 256 个非空工作区映射名称或 ID：

{
"command": "python laptop/project/main.py",
"cwd": ".",
"target": "server",
"mount_mappings": ["laptop"]
}

将此传递给 kapsel_shell_exec，或将其放入 kapsel_http.json 以用于 POST shell/exec。该字段不会改变自动放置，且非空依赖对于客户端执行无效。两种路由都保留正常的写入审批和 Plan/Context 归属。不要解析命令来猜测依赖，也不要默认挂载每个映射。

FastAPI 的额外原生依赖应放在应用程序的 api/mappings.json 中，例如 {"mount_mappings":["datasets"]}。其所在的映射是自动的。挂载租约跟随任务或 API worker，而不是单个 HTTP 请求；普通文件操作从不使用 FUSE 回退。服务器可以禁用原生挂载，同时保留文件/RPC 和客户端执行可用。

当前客户端始终启用核心文件 RPC：rpc.file 已被移除；请从旧客户端配置中删除该键。升级客户端和服务器以使用 file_stream 元数据。将 unavailable_mappings、truncated 以及不可用的树/清单节点视为不完整结果，而非缺失文件。在超时、取消或丢失写入/启动响应后，检查现有任务和受影响的路径；绝不要自动重放命令或 RPC 变更。

捆绑技能的映射、Shell 和 web/应用程序参考文档记录了该契约。运行时发现对于服务器版本差异仍然是权威的。

Shell 启动请求超时

插件设置 shellRequestTimeoutSeconds 控制初始 Shell 启动响应的 HTTP 等待时间，包括惰性原生挂载设置。它默认为 120 秒，并接受 1 到 3600 之间的有限数字。请在 DSH 组合行中配置它，而不是在工具的请求 JSON 中：

- id: tool-kapsel
name: 'dsh-openkapsel'
config:
taskname: dsh
enforceRemoteOnly: true
shellRequestTimeoutSeconds: 300

kapsel_shell_exec 和通用 POST shell/exec 调用都使用此设置。Python HTTP 请求使用该超时；主机辅助看门狗增加 10 秒（默认 130 秒）。凭据发现/续期以及测试框架或反向代理限制可能会施加各自的界限；这并不保证每个设置都能在配置的时间内完成。其他端点预算保持不变。工具的 timeout_seconds 是远程任务执行截止时间，并且
是刻意独立的。失败的启动请求绝不会自动重试；其错误会提醒模型，超时/取消并不能证明远程任务已停止，并且在任何重试之前必须检查 /tasks。

结构化配置和大表

使用 kapsel_mappings 检查客户端的 structured 和 tabular schema，然后调用 kapsel_rpc。结构化 JSON/YAML/TOML 编辑使用条件原子写入/补丁任务；CSV/Excel 操作是只读的，包括异步 tabular.scan。CSV 分页使用经过身份验证的 seek 游标，而不是重复的行偏移扫描。分段扫描返回明确的进度/延续信息，不得被误认为是完整的全文件聚合。格式可用性取决于映射客户端上安装的可选库。不需要 FUSE。

捆绑的 openkapsel-rest 技能包含 references/data-rpc.md。

原子计划批次

在通告 capabilities.context.plan_creation.atomic_subplans 的服务器上，使用一次 kapsel_http，其中 method: "POST"、endpoint: "context"，并且 json 包含 type: "plan"、taskname、content、可选的 request_id，以及 subplans: [{"ref":"code","content":"Implement"},{"ref":"tests","content":"Verify"}]。响应会返回父级 id 以及每个子级的 id/plan_id/ref。将返回的子级 ID 传递给后续的变更工具；无需额外创建 Plan。不要将 endpoint 字段放在 json 旁边。

服务器会原子性地创建整个批次。复用相同的 request_id 并仅请求以恢复不确定的响应，而不是启动新工作。该插件不会自动重放失败的写入或更改其审批策略。有关直接子级限制和幂等性规则，请参阅捆绑的 Context 参考。

OAuth 浏览器同意与此 REST 桥接是分开的

支持 OpenKapsel OAuth 的 MCP 客户端使用独立的浏览器同意页面。用户在那里使用当前控制令牌为确切链接的配置验证所有权；不需要管理员登录。此插件继续使用其现有的 REST 凭据，并且绝不会将它们提交到浏览器表单或客户端回调。OAuth 访问/刷新凭据与 REST 凭据保持分离。更新服务器同意不需要新的插件传输或新工具。如果您已经在另一个平台上拥有经过身份验证的 OAuth 或 Static MCP 连接，服务器端的 get_workspace_credentials 工具可以导出当前 REST 工作区 URL/控制令牌以配置此插件，而 renew_workspace_credentials 可以在正常续期窗口内轮换该 REST 对，而无需更改 MCP 凭据。