dsh-powerkit

![tests]() ![modules]() ![deps]() ![license]()

dsh-powerkit 是 DeepSeek Harness (dsh) 的全能增强工具箱插件——16 个独立可配置的功能模块，把 AI 编程代理使用中最常被抱怨的问题变成开箱即用的能力。零运行时依赖，Node 内置 test runner 覆盖 125 项测试，MIT 开源。

[English summary](#english-summary) · [安装](#安装) · [功能总览](#功能总览) · [命令手册](#命令手册) · [配置参考](#配置参考) · [架构](#架构) · [质量保障](#质量保障)

---

为什么需要它

AI 编程代理（dsh / Trae / Cursor / Claude Code / Copilot / Gemini CLI 等）存在一批跨工具的共性痛点，社区 issue 区反复出现：

• 对话进行到一半，想换个模式（比如从自由探索切到严格只读）只能开新会话，上下文全丢
• 规则文件四分五裂：AGENTS.md / CLAUDE.md / .trae/rules / .cursor/rules，各家只认自家的，长对话还会"忘记"
• 上下文压缩后丢失关键纠正信息，模型重复犯错
• 长任务中断后无法从断点恢复，只能从头再来
• 代理陷入死循环 / 空命令循环，token 烧完才发现
• token 用量、花费、工具调用记录不透明，事后无法审计
• 输出风格漂移：同样的提问，一会中文一会英文、一会冗长一会简略

dsh-powerkit 把这些问题的社区验证过的解法，做成 16 个可自由开关的模块装进 dsh。

功能总览（16 模块）

每个模块都有独立的 enabled 开关——不想要的功能关掉即等同于不存在，全部关闭则插件近乎零开销。

安装

官方接入方式（已在 @deepseek-ai/dsh@0.1.0-rc.7 上实测通过）：

# 本地路径安装（开发/自建，最常用）
dsh plugin --profile web add /path/to/dsh-powerkit

# npm 安装（发布后）
dsh plugin --profile web add dsh-powerkit

# GitHub 安装
dsh plugin --profile web add github:<owner>/dsh-powerkit

dsh plugin add 会把包写进 profile（$DSH_HOME/profiles/<name>）的依赖与 dsh.profile.bundles，随后正常 dsh web 启动即可。

要求与原理（对齐官方 dsh-client-modules 扫描规则）：

• Node.js ≥ 22.7；客户端 UI 半边必须先构建：npm run build 产出

lib/index.js（宿主半）与 lib/client.js（浏览器半）。缺失 client bundle 会让 dsh web 启动直接报 MissingClientBundleError。

• 插件在 package.json 里声明 dsh.client.platform = "web" 与

exports["./client"]，dsh 才会把它收进 window.__DSH_BOOT__ 并在浏览器加载 /plugins/dsh-powerkit/client.js。

• 插件必须以包名注册进 profile（dsh plugin add 即如此）；用绝对源码

路径写 cordis.yml 覆盖层时，官方扫描无法解析到 package.json，客户端 UI 不会出现。

快速开始

装好后直接在 dsh 对话里输入：

/pk doctor          # 第一步：体检，看模块开关与宿主能力
/pk menu            # 浏览全部命令
/pk mode plan       # 切到规划模式：只读 + 输出计划
/pk task add 重构权限模块
/pk task add 写集成测试
/pk snippet tests src/permissions.ts   # 一键展开"补测试"模板
/pk style set lang=zh length=concise  # 输出风格：中文 + 精炼
/pk cost            # 看这次会话花了多少钱
/pk export          # 导出会话报告

中途切换模式的实际效果

你: （聊了 40 轮的复杂重构会话）
你: /pk mode readonly
[powerkit] 模式已切换: readonly（下一轮模型请求即生效）。
  覆盖: model=deepseek-v4, maxTokens=8192
  策略: readonly
你: 帮我把这个函数改成 async
模型: 当前处于只读模式，我不会修改文件。改动方案如下：…（输出计划而非动手）

图形控制台（不用记任何命令）

所有 /pk 能做的事，都可以在浏览器里点出来。两种形态，同一份实现：

① dsh web 内嵌面板（官方形态，实测截图见 docs/screenshots/）

插件装进 web profile 后，dsh web 界面右缘出现 ⚡ launcher，点击滑出 "Powerkit 控制台"；同一页面也能直达 http://<dsh-web>/powerkit/。 挂载走官方 webServer 服务（ctx.plugin({ inject: ['webServer'] }) 的 可选依赖子 fiber，服务就绪后自动挂上），无需独立端口。

② 独立面板（非 dsh 宿主 / 纯 CLI 场景）

# 脱离 dsh 单独跑（同一个面板，同一份配置）：
npm run panel
PORT=3000 npm run panel   # 换端口

在 cordis/dsh 组合里检测到 webServer 时不再起独立端口，避免双面板； 只有独立运行时才默认监听 127.0.0.1:17654。

控制台上可以直接点击操作：

生效机制：面板把改动写入 .dsh-powerkit/ui.json，运行中的 dsh 插件每 2 秒轮询该文件并热合并进运行配置——不需要重启 dsh，不需要重启会话，点完开关下一轮对话就是新行为。就算面板进程和 dsh 进程不在一台机器上，同一份工作目录也能协同。

安全默认：只绑定回环地址（127.0.0.1），不会暴露到局域网；要开放局域网需显式设置 ui.allowLan: true（见下方配置参考）。

命令手册

/pk 与 /powerkit 等价；子命令均有别名。

| 命令 | 作用 | |------|------| | /pk mode [id\|list] | 查看/切换模式，list 列出全部可用模式 | | /pk model <id> | 本会话一次性模型覆盖（不动模式） | | /pk fallback [list] | 查看降级链与累计降级统计 | | /pk style [set k=v] | 查看输出风格；set lang=auto\|zh\|en length=concise\|normal\|detailed format=markdown\|plain | | /pk snippet [list\|<id> 参数] | 列出/展开提示词模板 | | /pk task [add 文本\|done id\|all\|list\|clear] | 任务看板，支持 id/关键词/all 完成任务 | | /pk guard <tool> [command] | 权限引擎试算：这条命令会被 allow/ask 还是 deny，命中哪条规则 | | /pk audit [n] | 最近 n 条（默认 20）工具调用审计 | | /pk checkpoint [list] | 立即创建/列出检查点 | | /pk rescue | 由最近检查点生成断点续跑提示词 | | /pk report /pk cost | token 报告 / 成本估算 | | /pk rules reload | 重载工作区规则文件 | | /pk export [dir] | 导出会话全景 Markdown 报告 | | /pk status | 一屏总览：模式/检查点/任务/token/水位/风格/模块开关 | | /pk doctor | 健康体检 | | /pk menu /pk help | 命令菜单 / 详细帮助 |

配置参考

插件配置位于 dsh 配置的 plugins['dsh-powerkit'] 节。所有字段均有默认值与防御性校验/钳制——写错配置只会回退默认，不会拖垮插件。完整类型定义见 src/config.ts。

模块开关与核心项

配置示例

只保留模式热切换（最小 footprint）：

{
  "modes": { "enabled": true },
  "guard": { "enabled": false }, "rules": { "enabled": false },
  "sentinel": { "enabled": false }, "checkpoints": { "enabled": false },
  "watchdog": { "enabled": false }, "meter": { "enabled": false },
  "snippets": { "enabled": false }, "tasks": { "enabled": false },
  "cost": { "enabled": false }, "fallback": { "enabled": false },
  "audit": { "enabled": false }, "style": { "enabled": false },
  "exporter": { "enabled": false }
}

团队规范 + 自定义模式 + 价格表：

{
  "modes": {
    "presets": [{
      "id": "release", "name": "发布模式", "toolPolicy": "shell-only",
      "systemPromptSuffix": "发布模式下必须走 CI 流水线，禁止本地 npm publish。"
    }]
  },
  "rules": { "extra": ["所有 shell 命令前先 dry-run", "不允许修改 migrations/ 目录"] },
  "guard": { "rules": [{ "pattern": "shell:npm publish*", "action": "deny", "comment": "发布走 CI" }] },
  "cost": { "prices": { "my-model": { "inputPerM": 0.5, "outputPerM": 2 } }, "budgetUsd": 1 },
  "fallback": { "chain": ["deepseek-v4-flash", "deepseek-chat"] },
  "style": { "language": "zh", "length": "concise" },
  "snippets": { "custom": [{ "id": "pr", "name": "提 PR", "template": "为 {target} 创建 PR：标题、描述、自查清单。" }] }
}

架构

dsh (Cordis kernel)
 └─ dsh-powerkit 插件
     ├─ 事件监听  session/event · agent/pre-step · agent/request · agent/status
     ├─ 模式层    modes ──► agent/request 改写 provider/model/maxTokens/systemPrompt
     ├─ 安全层    guard + audit ──► 工具调用拦截/审计
     ├─ 记忆层    rules + sentinel + tasks ──► context pack 注入
     ├─ 稳定层    checkpoints + watchdog + fallback ──► 救援/纠偏/降级
     ├─ 计量层    meter + cost ──► 去重统计与折算
     ├─ 表现层    style + snippets + exporter ──► 风格/模板/导出
     └─ 命令层    /pk 路由 ──► 零 token 控制 16 模块

设计原则：

• 绝不向宿主抛异常：所有宿主 API 调用都做特性检测 + try/catch；dsh 处于开发者预览期，宿主 API 变更时自动降级运行
• Cordis HMR 干净装卸：监听器全部走 ctx.on/ctx.effect，热重载无泄漏（有 20 轮 attach/dispose × 事件风暴的压力测试背书）
• 持久化全部防御式：JSONL 追加写、损坏文件自动重置、磁盘不可用时静默降级为内存模式

质量保障

npm test        # 125 项单元测试（Node 内置 runner）
npm run check   # 13 项自动化自检底座（结构/清单/秘密/测试/冒烟/tsc/模糊/文档一致性）
npm run smoke   # 敌对宿主冒烟：畸形事件、缺失 API、配置模糊
npm run fuzz    # 对抗性模糊测试

• 10 轮全面自检记录：见 [SELF_CHECK_REPORT.md](./SELF_CHECK_REPORT.md)——累计发现并修复 9 个真实缺陷（含多行命令安全绕过、null 崩溃、空引擎试算等），每轮可复现
• 痛点溯源：见 [RESEARCH.md](./RESEARCH.md)——每个模块对应的社区 issue 原始链接
• tsc 严格模式零错误：strict + noUncheckedIndexedAccess
• 零运行时依赖：npm install 不需要

English summary

dsh-powerkit is an all-in-one community-driven plugin toolkit for DeepSeek Harness (dsh): 16 independently-configurable modules that turn widely-reported pain points of AI coding agents into plug-and-play features — live mid-conversation mode switching, a glob-based permission guard with danger blacklist, unified rules enforcement across AGENTS.md/CLAUDE.md/.trae/.cursor/.lingma, a context sentinel with correction-preserving digests, crash-resilient checkpoints, a stuck/loop watchdog, deduplicated token metering, a zero-token slash command router, prompt snippets, a persistent task board, cost estimation, model fallback chains, JSONL audit trails, output-style contracts, Markdown session export, and a one-command doctor. Zero runtime dependencies, 125 tests on Node's built-in runner, tsc-strict clean, adversarial fuzz + hostile-host smoke suites, 10 documented self-check rounds. MIT.

License

[MIT](./LICENSE) © dsh-powerkit contributors