Norman-else/dsh-claude

dsh-claude

1. 概述

dsh-claude 将本地安装的 Claude Code CLI 作为一等对话提供程序运行在 DeepSeek Harness（DSH）中。它使用 Claude Code 官方的 Agent SDK 协议，而不是用单独的 API 客户端重新实现该 agent。

Claude Code 仍然负责其 agent 循环、工具、CLAUDE.md、Skills、Hooks、Plugins、MCP 服务器、设置和身份验证。DSH 提供对话 UI、审批和提问界面、仓库工作流、活动展示以及受管进程生命周期。

2. 安装与移除

要求

- 具有兼容公共插件 API 的 DeepSeek Harness Desktop。此包目前针对 DSH 0.1.5-rc.2 包系列（DSH Desktop 2.0.10）开发。插件 0.1.37 及更高版本导入了 0.1.1-rc.2 上不存在的符号；仍停留在该系列的 Host 必须固定使用 @norman-else/dsh-claude@0.1.36。
- 已通过身份验证的本地 Claude Code 安装。
- 从源代码检出安装时，需要 Node.js 20 或更高版本。

该插件从不请求或存储 Claude 凭据。在使用该插件之前，请先通过本地 Claude Code CLI 进行身份验证。

从 npm 安装

将已发布的包添加到正在运行的 DSH 实例所使用的 profile 中。以下命令使用 desktop；仅对现有的 Web profile 才将其替换为 web。使用该安装提供的 DSH CLI：

dsh plugin --profile desktop add @norman-else/dsh-claude

等待 profile 重新构建完成，然后完全退出 DSH Desktop 并重新打开。创建一个新对话，并从 Agent Preset 选择器中选择 Claude。

从源代码安装

git clone https://github.com/Norman-else/dsh-claude.git
cd dsh-claude
pnpm install
pnpm check

对于已链接到正在运行的 Desktop 的检出，请仅在其轮次完成后运行构建：重新构建可能会热重载该插件。在活跃工作期间，请使用单独的源代码副本进行验证。参见 INSTALL.md。

从 PowerShell 将检出链接到 DSH：

dsh plugin --profile desktop add "link:$($PWD.Path.Replace('\', '/'))"

或在 macOS/Linux 上：

dsh plugin --profile desktop add "link:$(pwd)"

移除插件

在移除包之前，先移除受管兼容预设：

dsh plugin --profile desktop exec dsh-claude remove-preset
dsh plugin --profile desktop remove @norman-else/dsh-claude

DSH 目前不提供插件卸载生命周期钩子。如果在清理其受管预设之前已移除该包，请直接运行匹配的已安装版本：

pnpm dlx @norman-else/dsh-claude@ remove-preset

预设清理仅移除安装程序管理的内容，并拒绝删除用户修改过的预设文件。

3. 功能

3.1 对话

- 原生 Claude Code 对话 — 在普通 DSH 对话中将 Claude Code 作为主 agent 运行，而不是将其包装为工具或次级聊天。
- Claude 预设与模型选择 — 添加一个 Claude Agent 预设，并读取 Claude Code 的模型目录。当目录不可用时，default、opus[1m]、fable、sonnet 和 haiku 作为回退选项。
- 思考强度 — 将 DSH 的按模型推理强度映射到 Claude Code 的思考模式——off、low、medium、high（Claude Code 自身的默认值）、xhigh、max 和 ultracode——因此对话的强度控制会直接驱动扩展思考。不支持某个模式的模型会在 Claude Code 内部静默降级；ultracode 还会开启常驻动态工作流编排，并且需要支持 xhigh 的模型。
- 本地 Claude 环境兼容性 — 保留用户现有的 Claude Code 身份验证、设置、CLAUDE.md、Skills、Hooks、Plugins、工具和 MCP 配置。
- 实时流式传输与对话连续性 — 将 Claude 的响应和工具活动流式传输到 DSH，同时保留多轮上下文和持久化的 Claude 会话恢复。
- DSH 权限与问题 — 将 Claude 工具权限请求路由到 DSH 审批，并将 Claude 澄清提示路由到 DSH 的原生问题表单。
- Claude Code 权限模式 — 在 Permission selector 设置（Plugin，或 DSH 原生，以保留 Host 的三模式控制和普通沙箱映射）之后，仅针对 Claude 会话，在 composer 工具行的同一位置用 Claude Code 自身的模式替换 DSH 的三模式访问选择器：Plan、Default、Accept edits、Don't ask、Auto 和 Bypass permissions，每个模式都有自己的图标、双语名称和描述；当目录表明会话的模型无法运行 Auto 时，Auto 会置灰，而分类器升级的询问会到达 DSH 审批对话框，并在标题下方显示分类器的原因。该选择是插件自己的按会话记录，也是下一轮运行所依据的设置；DSH 沙箱模式和审批策略被移到承载该模式的预设上，因此审批和沙箱会随之生效，而无需 Host 了解任何新模式。Bypass 会先要求确认确认，控件在轮次运行期间会锁定，之后以原生方式切换的沙箱（/permission 命令）会优先于已记录的选择，因此 DSH 自身的旋钮永远不会被违背。Host 的选择器通过作用域 CSS 规则隐藏，而不是被替换，因为它不是插槽；如果 Host 重命名了它，则只会同时显示两者。新的 Claude 会话会从此插件设置中的 Default permission mode 开始，除非更改，否则为 Auto：在创建会话时，DSH 访问预设会被移到该模式所需的沙箱上，因此，如果 Host 自身的默认预设是完全访问，也不会将其变成 Bypass。
- 计划审阅——在只读访问下，Claude 以计划模式工作，它交回的计划会在右侧边栏标签页中一个由插件拥有的面板里读取，并按照此插件设置中所选的散文配色方案以 Markdown 渲染。批准本身仍由 DSH 负责：其对话框会指明该决定，并指向该面板，而不是把计划粘贴到一个纯文本模态框中；而且即使在完全访问权限下也会询问——该设置豁免的是操作，而不是计划本就要呈现在用户面前的那个决定。完全访问权限会直接让批准静默（approval/policy: never，在任何界面显示之前就已应答），因此只要计划处于打开状态，该询问就会被取消静默，之后会话自身的策略会被恢复。批准和拒绝是该对话框仅有的两个答案，而两者都不是“修改这个”，因此该面板添加了第三个：选中一段文字，写下应修改的内容，然后把计划发回——这些备注会作为计划被拒绝的原因传达给 Claude，随后对话框会自行关闭。一个会话如果多次提出计划，会保留每一份计划：面板标题会变成一个选择器，列出每一份计划及其各自的决定，而新的待批准提案会把面板切回该提案。会话标题栏带有一个计划开关，当计划仍在等待决定时显示为点状，而该轮次的工具卡片也带有同样的计划。
- Claude 命令桥接——将 Claude Code 自身的命令目录发布到 DSH 命令面板中，并在新的 CLI 完成加载 Skills 和 Plugins 期间以退避方式重试。
- 提示片段——将用户每天反复重新输入的半成品消息保存为 ~/.claude/prompts 中的普通 Markdown 文件，每个文件一个片段，并将它们作为 Claude 命令目录旁边的第二个 / 分组提供。选择一个片段会将其文本放入编辑器中，而不是直接发送，因此草稿仍可编辑——片段是用户最终完成的消息，而不是会运行的命令。编辑器自身工具栏行中的一个控件，位于附件和访问控件旁边，可将当前草稿保存为新片段：它会以草稿的首行作为文件名，并显示它写入的文件名。它不会给布局带来任何成本——一个停靠行会在每次按键时移动编辑器——并且绝不会覆盖已有名称。派生名称只是起点：一次 Claude Haiku 调用会为片段正确命名，并在结果返回时替换它，除非用户已经开始输入；而失败或缓慢的建议则无关紧要，因为从第一帧起就已有一个可用的名称。该调用在关闭扩展思考的情况下运行，这正是让它保持在约三秒而不是十秒的原因。
- 用 AI 重写草稿 — 同一工具行中的第二个控件将当前草稿交给 Claude Haiku，并用一个智能体无需追问即可据以行动的版本替换它，同时保留原文携带的每一个具体细节。SessionInput.setDraft 会合并进编辑器的撤销历史，而不是在其中新增一步，因此 Ctrl/Cmd+Z 无法将原文恢复：按钮会代为保留它，并且只要重写内容仍在屏幕上且未被编辑，就一直提供恢复选项。重写被要求将每一处对人物的引用都按原样保留——如果要求重写“assign it to me”，模型否则会深入 Claude Code 的环境上下文，替换为操作者的真实电子邮件地址。编辑、重命名和删除都在用户自己的编辑器中进行，在那里添加的文件无需重新加载就会出现在菜单中。
- 消息队列与引导 — 在一轮运行期间接受更多消息，并允许对已排队的消息进行编辑、移除，或引导到已在执行的那一轮中。引导到达该轮的方式与 Claude Code 自身相同：消息被推入 CLI 的输入流，并在其下一个模型步骤被读取，因此该轮会带着它已持有的一切继续运行，而不是等到结束再作为后续消息到达。转录会在它到达的位置绘制它，位于其之前的工作和之后的工作之间——对于此预设，DSH 自身的界面每轮只取一个节点，因此记录在那里的消息会位于该轮所做的一切之上，读起来像是整个回答所针对的问题。带附件的消息走与普通发送相同的路径，而到达时已没有可引导轮次的消息则保持排队，等待下一轮。在一轮运行时按普通 Enter 会将后续消息排队，除非 Host 的 busy-Enter 设置被设为引导；队列条自身的引导操作始终执行引导。另一个插件可以通过 claudeSteering 服务到达同一入口点。
- 回退 — 丢弃一条消息及其之后的所有内容：Claude 从保留轮次的转录锚点恢复，并真正忘记被丢弃的轮次，被丢弃的行会从仅追加的 DSH 日志中隐藏，原始文本会返回编辑器以供编辑和重新发送。每一轮都是针对捕获的工作树被接纳的，因此同一次回退可选地将检出恢复到被丢弃轮次发现它时的状态——此后创建的文件会被移除，已更改的文件会被恢复，而 .gitignore 覆盖的文件则保持不变。
- 询问所选内容 — 通过一个只读的侧查询，就任何选中的文本回答问题，该查询仅限于 Read、Grep 和 Glob，复用会话的模型和思考模式，答案可复制或发送到主对话中。
- 脱敏活动时间线 — 显示思考摘要、工具调用和结果、权限事件、问题、状态变化、用量、错误以及子智能体活动，而不持久化凭据。
- 可选择的 AI 输出渲染器 — 使用此插件自带的转录（交错的散文、分组的工具卡片、活动行）或 DSH 的原生对话渲染器来绘制 Claude 的输出；在原生渲染器中，散文以普通助手文本块的形式呈现，思考以推理块的形式呈现，根级 Claude 工具以原生工具卡片（终端、差异、搜索、读取）的形式呈现。在设置中选择，从下一轮开始应用；插件转录仍为默认值，已记录的轮次保留绘制它们时所用的渲染器。
- 自动会话标题和分支名称 — 使用单独的、单轮 Haiku 查询来总结第一条消息或工作树意图。两者都像主对话一样加载 user、project 和 local 设置，包括基于设置的身份验证和行为配置。出错结果会保留 DSH 的回退标题或生成的时间戳分支名称。这些查询不会借用主对话进程。
- 后台任务跟踪 — 显示正在运行和已完成的 Claude 子代理或后台任务，包括任务状态、最近使用的工具和可展开的活动。
- 上下文用量 — 从 Claude Code 收集聚合的上下文窗口用量，并显示在会话板上。它不会在模型选择器旁边注册单独的上下文计量槽位。
- 轮次核算 — 为插件转录绘制的每一轮补上 DSH 只给自己的消息提供的页脚：令牌数、缓存命中率、实际耗时、首令牌时间以及累计成本。这些计时是在轮次运行时测量的，因为活动记录本身不携带时钟。
- 受管进程生命周期 — 为每个活动会话保持一个活跃的 Claude 进程，串行化轮次，驱逐空闲进程，当所有进程槽位都忙碌时将用户轮次按 FIFO 排队，在限制降低后安全收敛，并处理停止、取消、重启和进程树清理。
- 双语界面 — 每个面向用户的字符串都同时提供英文和中文版本。

3.2 仓库、工作树和拉取请求

- 仓库和工作树准备 — 允许用户在提交前选择分支、切换符合条件的本地分支，或创建一个专用的 Git 工作树和 DSH 工作区，同时转移当前草稿和附件，并在插件管理的工作树被删除后对其进行协调。该删除操作可能会用 --force 移除一个脏工作树；在删除工作区之前，请提交或保留所需的文件。单独的已合并分支清理操作要求工作树干净，并检查是否有未推送的提交。
- 分支选择器 — 列出仓库的本地分支和远程跟踪分支，在用户输入时进行筛选，并按需从远程刷新，以便在别处创建的分支无需离开 DSH 即可选择。
- Jira 驱动的会话 — 连接到 Jira Cloud 并从工单开始工作：分支以工单键命名，composer 中预填工单简报，worktree 创建后将工单分配给用户，并且可以同时启动多个工单，每个工单都在自己的 worktree 会话中。
- 仓库和拉取请求状态 — 在 composer 附近显示当前仓库、分支、worktree 状态、更改行数、未推送提交、GitHub 拉取请求、检查、审查状态、合并状态以及阻塞性的 Claude 速率限制。
- 会话面板 — 在一个地方汇总每个 Claude 会话，包括其运行状态、分支、拉取请求、上下文使用情况、自动修复状态，以及它是否正在等待批准或回答。
- 会话提醒 — 当用户未在查看的会话开始等待批准或回答，或完成其轮次时，发出桌面通知；点击它会将该会话调到前台。屏幕上的会话永远不会触发提醒，一个提示只通知一次，并且整个功能可在“设置”中关闭。
- 分支差异查看器 — 在右侧边栏标签页中提供分支差异，由 Host 管理全屏，包含文件统计、全部展开和全部折叠、按需显示未修改的上下文，以及评论到评论的导航。
- 行级审查评论 — 记录用户自己对差异的行或范围评论，并将它们附加到下一条 Claude 消息中。
- GitHub 审查线程 — 以内联方式读取、回复、解决和取消解决拉取请求审查线程，支持对仓库成员的 @ 补全、将机器人作者标记为机器人，以及链接回 GitHub 上的线程。
- 提交、推送、合并和拉取请求操作 — 支持提交、提交并推送、推送、创建草稿拉取请求，以及以合并提交、压缩或变基方式合并拉取请求，并带有仓库快照验证和 Claude 编写的文本。提交消息根据它所提交的差异编写：一个主题行，并且当差异包含多个独立更改时，在其下为每个更改列出一个项目符号；仓库最近的提交主题仅用于展示风格，而过长而无法发送的差异会被标记为截断，而不是被当作完整内容传递。拉取请求根据分支而非工作树来描述：其提交和相对于基础分支（对话框中指定的分支，否则为 origin 的默认分支）的差异，再加上其之前提交所添加的内容，生成自己的标题以及包含 Summary 和 Changes 的正文，每个独立更改对应一个项目符号，因此从已提交的工作打开的拉取请求不再根据空差异来描述。
- 分支更新 — 通过变基（使用 --force-with-lease 推送）或合并从基础分支更新当前分支，并将由此产生的任何冲突交给 Claude 解决。
- 拉取请求反馈交接 — 展开失败的检查详情和 GitHub 拉取请求评论，并将其中任一内容作为修复请求交给 Claude。
- 自动修复 — 监视打开的拉取请求中的新审查评论和失败的检查，将每一批新内容交给 Claude 进行修复、提交并推送，并持续进行，直到一切通过或监视器被关闭。
- 已合并分支清理 — 移除工作树和本地分支，归档工作区的会话，并删除工作区；而普通检出则返回基础分支并删除已合并的分支。

3.3 诊断、设置和更新

- Claude Code 设置和 Doctor — 添加一个设置面板，用于运行时诊断、支持的 Claude 设置、输出样式、AI 输出渲染器、会话警报、工作树分支前缀、进程限制以及身份验证和握手状态。
- 计划用量 — 报告已登录订阅的利用率窗口——五小时、所有模型的每周以及每个模型的每周——并带有重置倒计时，在 API 密钥、Bedrock 和 Vertex 会话上降级为不可用，而不是失败。
- 有界请求和配给的连接池 — 限制插件在浏览器每源连接中所占的份额，使其自己的面板永远不会相互饿死或饿死 Host，并为每条路由声明一个时间预算——来自内存的答案、本地 Git 工作和到达网络的调用各有自己的预算——客户端比服务器多等待一个往返，因此慢操作会报告哪个预算已耗尽，而不是挂在浏览器的队列中。
- 插件更新 — 检查 npm 是否有新版本并就地更新，仅在安装被唯一标识时进行；本地开发链接永远不会被替换。
- 托管预设兼容性 — 安装一个受保护的 Claude 预设，其路由复用活动配置文件包源，在不重复客户端模块 Loader 或覆盖用户更改的情况下，保留在不保留第三方预设根的 Desktop 版本上的发现。

4. 贡献

4.1 两种贡献类型

对本仓库的每一次贡献都恰好是两种类型之一。没有第三种类型。

| 类型 | 含义 | 示例 |
| --- | --- | --- |
| feature | 尚不存在的行为 | 新的 composer 操作、新的设置字段、对新的 Claude Code 能力的支持、从未被记录下来的已记录行为 |
| fix | 已经存在但错误的行为 | 崩溃的槽条目、错误的令牌计数、在 Desktop 升级后不再被发现的预设、不再与代码匹配的 README 陈述 |

重构、依赖升级、仅测试更改和文档编辑不是单独的类型。将它们归档为与其目的匹配的类型：今天错误的东西是 fix，今天不存在的东西是 feature。如果你无法决定适用哪一种，这表明该问题尚未确定范围——先将其作为问题打开，让维护者对其进行分类。

4.2 必需流程
问题永远优先。没有问题的拉取请求会被直接关闭而不予审查，无论代码质量如何。

1. 搜索现有问题。 如果你的问题或想法已被提交，请在那里评论，而不是开启重复项。
2. 开启一个问题，访问 https://github.com/Norman-else/dsh-claude/issues/new/choose 并选择 Feature 或 Fix 表单。选择表单即是你声明类型的方式：它会为你设置 [feature] / [fix] 标题前缀和匹配的标签。§4.3 中列出的每个字段都是表单必填项，因此，如果一个问题没有解释为什么需要它或在什么环境中发生，就无法提交。空白问题已被禁用——如果你确实无法判断适用哪种类型，请使用该页面上的“不确定是功能还是修复”链接，让维护者进行分类，而不是为了通过表单而猜测类型。
3. 等待问题被接受。 维护者会确认类型、范围，以及该变更是否属于此插件——有些看起来像插件缺陷的问题实际上是 DSH Host 或 Claude Code CLI 的行为。在此之前不要开始实现。在被拒绝的问题上所做的工作无法被合并。
4. 从 master 分支，使用 feature/- 或 fix/-。
5. 实现并验证，遵循 §4.4 中的规则。
6. 开启拉取请求，声明其类型并链接其问题（§4.5）。
7. 处理审查。 维护者审查并批准；维护者合并。贡献者不合并自己的拉取请求。

master 受保护：直接推送、强制推送和分支删除均被阻止，并且拉取请求在合并前需要一次批准审查。向拉取请求推送新提交会撤销现有的批准，因此预计在更改后需要再次请求审查。

4.3 问题必须包含的内容

两种类型都需要足够的细节，以便他人在不向你追问的情况下重现你的情况。

一个 feature 问题必须说明：

- 动机——DSH 用户今天无法做什么，以及为什么当前的变通方法不够好。
- 提议的行为——应该发生什么，从用户的角度描述，并指明它所属的界面（composer、hero repository controls、diff panel、activity timeline、Settings panel、Agent Preset picker……）。
- 范围和非目标——这明确不涵盖什么，以便拉取请求可以对照固定边界进行审查。
- 受影响的层——插件服务器（src/）、客户端（src/client/）、托管预设（preset/），或组合。
- 兼容性——它所针对的 DSH Desktop 和 DSH 包系列，以及它所依赖的 Claude Code CLI 版本。如果它依赖于旧版 CLI 不具备的 Claude Code 能力，请说明。
- 考虑过的替代方案——包括“什么都不做”，以及为什么它们被拒绝。
- 你是否打算实现它——这样维护者就知道是把它分配给你，还是安排它。

一个 fix issue 必须说明：

- 预期行为与实际行为——两句话分开写，而不是合并成一句抱怨。
- 复现步骤——编号、最小化，并从干净状态开始。说明它是每次都复现还是间歇性复现。
- 环境——插件版本（package.json 中的 version 字段，或 DSH 显示的版本）、DSH Desktop 版本、Claude Code CLI 版本、操作系统，以及如果你是从源码安装的，还有 Node.js 版本。
- 证据——相关的已脱敏日志行、活动时间线摘录或截图。启动和 slot 失败会在 DSH 日志中以 dsh-claude client [boot-check] 和 [slot-entry-crashed] 的形式出现；当插件加载失败时，请附上这些日志行。
- 回归范围——如果你知道的话，最后一个能正常工作的插件或 DSH Desktop 版本。

发布前先脱敏。 绝不要把 Claude 凭据、API 密钥、会话令牌、私有仓库内容或客户数据粘贴到 issue、pull request、测试夹具或日志摘录中。这也适用于附件和截图。该插件从不请求或存储 Claude 凭据，其 issue 跟踪器也不应如此。

4.4 变更本身的规则

- 保持在树外。 只使用公开的 DSH 导出。绝不要修补已安装的 DSH 检出，也绝不要依赖未导出的 DSH 内部实现。
- 尊重所有权划分。 Claude Code 拥有其 agent 循环和工具；该插件拥有展示、审批和提问界面，以及托管进程的生命周期。在插件内重新实现 Claude Code 行为的变更将被拒绝。
- 在更改运行时行为之前先阅读规范：docs/aegis/spec/2026-08-15-dsh-claude-spec.md，以及 docs/aegis/plan/ 和 docs/aegis/plans/ 下的当前计划。如果你是在应对 DSH Desktop 升级，请遵循 docs/upgrading-dsh-desktop.md——Host 不附带类型声明，因此 pnpm typecheck 无法发现其 API 漂移。
- 绝不要使用真实凭据进行日志记录、持久化、渲染或测试。 在任何持久化事件追加之前先脱敏。
- 运行 pnpm check——对两个 tsconfig 进行类型检查、运行 Vitest 测试套件并构建——并确保它在打开 pull request 之前通过。没有通过就不要声称变更有效。
- 在变更可测试的地方用测试覆盖行为。 一个 fix 应附带一个在变更前失败、变更后通过的测试。
- 每个分支只保留一种类型。 不要在同一个 pull request 中混合 feature 和 fix，即使你是一起发现的——开两个 issue 和两个 pull request。
- 不要碰发布。 不要提升 package.json 中的 version、编辑 scripts/publish.mjs 或发布。发布仅由维护者通过 pnpm release 进行。
- 以仓库现有的风格编写提交主题：使用祈使语气，描述意图而非机制，不加 feat: / fix: 前缀。参见 git log 中既定的模式——例如，Report the whole turn's output tokens, not the last call's。

4.5 拉取请求要求

针对 master 打开拉取请求，并包含以下所有内容：

- 描述的第一行为 Type: 行——要么是 Type: feature，要么是 Type: fix。这是声明贡献类型的方式；没有它的拉取请求不会被审查。
- 对其 issue 的关闭引用——Closes #。不关闭任何 issue 的拉取请求不会被合并。
- 匹配的标签——feature 或 fix，与 issue 所携带的标签相同。
- 改动了什么以及你如何验证——包括 pnpm check 的结果，以及你针对任何涉及 UI 或进程生命周期的内容在 DSH Desktop 中执行的手动验证。
- 当改动新增或改变用户可见行为时更新 README。新功能应归入 §3 中的 Features 列表。

类型通过标签和 Type: 行来声明，而不是通过标题前缀，这样压缩后的提交主题才能保持仓库的朴素祈使风格。

4.6 什么会被拒绝

- 背后没有已接受 issue 的拉取请求，或未声明类型的拉取请求。
- 将一项功能和一项修复捆绑在同一个拉取请求中。
- 修补 DSH、触及非公开 DSH API，或重新实现 Claude Code 的 agent loop 的改动。
- 失败或未运行的 pnpm check。
- 任何记录、持久化或渲染凭据的内容，包括在测试和 fixture 中。
- 从贡献分支进行版本号提升、发布脚本编辑或发布尝试。

5. 文档

- 安装与移除：配置文件选择、安全的源码构建、Doctor 和冒烟检查。
- 当前架构：行为和归属边界，尽管原始文件名如此，仍会维护。
- 桌面升级：已安装 Host 的审计和验证流程。
- 文档索引：区分当前指南与历史计划和证据。