hwc66626/dsh-powerkit

dsh-powerkit

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

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

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 模块）

| # | 模块 | 解决什么 | 命令入口 |
|---|------|----------|----------|
| 1 | 模式热切换 (modes) | 对话中途切换 agent 模式（plan/readonly/deep/standard/自定义），下一轮请求立即生效，无需新会话 | /pk mode  |
| 2 | 权限门卫 (guard) | glob 规则引擎 + 内置危险命令黑名单，allow/ask/deny 三档，支持纯观察模式 | /pk guard  [cmd] |
| 3 | 规则强制器 (rules) | 统一发现并合并 AGENTS.md/CLAUDE.md/.trae/.cursor/.lingma 等全部规则源，按节奏重注入防遗忘 | /pk rules reload |
| 4 | 上下文哨兵 (sentinel) | 监控上下文水位（去重后的净占用），warn/critical 分级预警，压缩前自动保留用户纠正摘要 | 自动 |
| 5 | 检查点救援 (checkpoints) | 每轮自动 + 手动检查点，会话中断后生成断点续跑提示词 | /pk checkpoint /pk rescue |
| 6 | 看门狗 (watchdog) | 检测卡死（超时无进展）、签名死循环、连续空命令（dsh 已知 bug 场景），自动 steer 纠偏 | 自动 |
| 7 | Token 计量 (meter) | 去重的 token 统计（修复宿主重复计数），预算告警，周期报告 | /pk report |
| 8 | 命令路由 (commands) | 零 token 的斜杠命令系统，/pk 一入口控制全部 16 个模块 | /pk menu |
| 9 | 提示词模板 (snippets) | 内置 5 个 + 无限自定义模板，{var} 变量展开，一键发送常用指令 | /pk snippet  [args] |
| 10 | 任务清单 (tasks) | 持久化任务看板，未完成任务每轮重注入，计划不怕压缩丢失 | /pk task add/done/list |
| 11 | 成本估算 (cost) | 按可配置价格表把 token 折算成钱，模型前缀匹配，预算超支提示 | /pk cost |
| 12 | 模型降级 (fallback) | 模型请求失败（429/503）自动沿链降级重试，不再手动重发 | /pk fallback list |
| 13 | 审计日志 (audit) | 每次工具调用的 JSONL 审计轨迹（工具/命令/判定/来源），事后可查 | /pk audit [n] |
| 14 | 输出风格 (style) | 语言/长度/格式三要素契约注入每轮请求，会话级覆盖 | /pk style set lang=zh |
| 15 | 会话导出 (exporter) | 一键导出会话全景报告（模式/花费/任务/检查点）为 Markdown | /pk export [dir] |
| 16 | 健康自检 (doctor) | 模块开关/配置校验/宿主能力/磁盘可写一键体检 | /pk doctor |

每个模块都有独立的 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:/dsh-powerkit

dsh plugin add 会把包写进 profile（$DSH_HOME/profiles/）的依赖与
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:///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。

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

| 区域 | 点击可做的事 |
|------|--------------|
| Agent 模式 | plan/act/speed/deep… 点按钮即切换，下一轮对话生效 |
| 输出风格 | 语言 / 长度 / 格式三组分段选择器，点选即改 |
| 任务看板 | 输入回车添加任务，点条目完成，未完成任务自动注入给模型 |
| 功能模块 | 16 个模块每个一张卡片开关，点击启用/停用，立即写入运行配置 |
| 参数微调 | 成本预算、降级链、权限默认动作（allow/ask/deny）改数字即生效 |
| 动作按钮 | 健康体检 / 导出会话报告 / 重载规则文件，一键执行 |
| 实时状态 | 当前模式、token 用量、成本、上下文水位、审计流水，2 秒自动刷新 |

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

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

命令手册

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

| 命令 | 作用 |
|------|------|
| /pk mode [id\|list] | 查看/切换模式，list 列出全部可用模式 |
| /pk model  | 本会话一次性模型覆盖（不动模式） |
| /pk fallback [list] | 查看降级链与累计降级统计 |
| /pk style [set k=v] | 查看输出风格；set lang=auto\|zh\|en length=concise\|normal\|detailed format=markdown\|plain |
| /pk snippet [list\| 参数] | 列出/展开提示词模板 |
| /pk task [add 文本\|done id\|all\|list\|clear] | 任务看板，支持 id/关键词/all 完成任务 |
| /pk guard  [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。

模块开关与核心项

| 键 | 默认值 | 说明 |
|----|--------|------|
| enabled | true | 插件总开关 |
| modes.enabled | true | 模式热切换 |
| modes.defaultMode | "standard" | 初始模式 id |
| modes.presets | [] | 自定义模式（同 id 覆盖内置） |
| modes.announceSwitch | true | 切模式时注入行为指引（false=极简确认省 token） |
| presets.enabled | true | 原生 Agent 预设透传（「博士」等宿主 agentPresets，不代造） |
| guard.enabled | true | 权限门卫 |
| guard.defaultAction | "ask" | 无规则命中时的动作 |
| guard.rules | [] | glob 规则，最长匹配优先，平局 deny>ask>allow |
| guard.builtins | true | 叠加内置危险命令黑名单 |
| guard.auditOnly | false | 纯观察：只记日志不干预 |
| guard.onDeny | "steer" | 拒绝后动作（steer/cancel/log） |
| guard.maxAskPerTurn | 2 | 每轮最多"请确认"注入次数（0-10） |
| guard.approvalMode | "manual" | 审批模式：manual 逐次确认 / auto 规则放行 / full 全放行 |
| guard.queue | true | 挂起调用进待审批队列（面板//pk approval 处理） |
| rules.enabled | true | 规则强制器 |
| rules.searchPaths | 7 个内置路径 | 规则文件发现列表 |
| rules.injectCadence | 3 | 每 N 轮重注入（1-50） |
| rules.maxBytes | 4096 | 统一规则块上限（256-65536） |
| rules.extra | [] | 团队级内联规则，永远追加在末尾 |
| sentinel.enabled | true | 上下文哨兵 |
| sentinel.contextWindowTokens | 128000 | 当前模型上下文窗口 |
| sentinel.warnPct | 75 | 水位告警阈值（10-99） |
| sentinel.criticalPct | 90 | 水位危险阈值（≥warnPct） |
| sentinel.preserveCorrections | true | 压缩前重注入用户纠正 |
| sentinel.digestMaxBytes | 2048 | 纠正摘要上限 |
| checkpoints.enabled | true | 检查点 |
| checkpoints.dir | ".dsh-powerkit/checkpoints" | 存储目录 |
| checkpoints.autoEveryTurns | 5 | 每 N 轮自动落点（1-100） |
| checkpoints.keep | 50 | 每会话保留数（3-1000） |
| checkpoints.includeToolLog | true | 检查点带最近工具日志 |
| watchdog.enabled | true | 看门狗 |
| watchdog.stuckMs | 180000 | 卡死判定毫秒数（10s-1h） |
| watchdog.loopWindow | 8 | 死循环检测窗口 |
| watchdog.loopThreshold | 4 | 窗口内同签名重复阈值 |
| watchdog.onStuck | "steer" | 卡死动作（steer/cancel/warn） |
| watchdog.emptyLoopLimit | 2 | 连续空命令上限 |
| meter.enabled | true | Token 计量 |
| meter.dedupe | true | usage 样本去重 |
| meter.budgetTokens | 0 | 会话 token 预算（0=不限） |
| meter.reportEveryTurns | 1 | 报告节奏（1-100） |
| snippets.enabled | true | 提示词模板 |
| snippets.custom | [] | 自定义模板（同 id 覆盖内置） |
| tasks.enabled | true | 任务清单 |
| tasks.maxActive | 20 | 未完成任务上限（1-100） |
| tasks.inject | true | 每轮重注入未完成任务 |
| cost.enabled | true | 成本估算 |
| cost.prices | DeepSeek 系列默认表 | 每百万 token 价格表（可完全自定义，default 条目兜底） |
| cost.budgetUsd | 0 | 会话预算 USD（0=不限） |
| fallback.enabled | true | 模型降级 |
| fallback.chain | ["deepseek-v4-flash"] | 降级链（失败后依次尝试，绝不回头循环） |
| fallback.maxRetries | 2 | 单次请求最大降级次数（0-5） |
| audit.enabled | true | 审计日志 |
| audit.keep | 500 | 内存/文件保留条数（50-10000） |
| style.enabled | true | 输出风格 |
| style.language | "auto" | auto/zh/en |
| style.length | "normal" | concise/normal/detailed |
| style.format | "markdown" | markdown/plain |
| style.extra | [] | 自由格式追加指令（≤20 条） |
| exporter.enabled | true | 会话导出 |
| exporter.dir | "." | 报告输出目录 |
| memory.enabled | true | 长期记忆模块 |
| memory.globalDir | "" | 全局记忆目录（空=宿主数据目录下 .dsh-powerkit） |
| memory.projectDir | ".dsh-powerkit" | 项目级记忆目录（相对工作区） |
| memory.maxEntries | 100 | 记忆条目上限（5-1000） |
| memory.maxBytes | 2048 | 每轮注入记忆块上限（256-16384） |
| memory.autoCapture | true | 自动捕捉"记住:"指令 |
| skills.enabled | true | 技能库模块 |
| skills.globalDir | "" | 全局技能目录（空=宿主数据目录下 .dsh-powerkit/skills） |
| skills.projectDir | ".dsh-powerkit" | 项目技能目录（skills/ 子目录） |
| skills.maxSkills | 50 | 技能数上限（1-200） |
| skills.maxBodyBytes | 8192 | 单个技能正文上限（256-65536） |
| skills.topK | 2 | 命中后最多注入技能数（1-5） |
| commands.enabled | true | 自定义斜杠命令模块 |
| commands.projectDir | ".dsh-powerkit" | 命令模板目录（commands/ 子目录） |
| commands.maxTemplateBytes | 8192 | 单个模板上限（128-65536） |
| commands.custom | [] | 配置内联命令（id/template，≤100 条） |
| docindex.enabled | true | 工作区文档索引 |
| docindex.include | [] | 追加索引扩展名（如 [".adoc"]，≤60 项） |
| docindex.maxFiles | 8000 | 索引文件数上限（100-100000） |
| docindex.topK | 5 | 检索返回条数（1-20） |
| docindex.buildOnStart | true | 启动时自动建索引 |
| behavior.enabled | true | 跟进行为模块 |
| behavior.presets | ["explain-first"] | 启用的行为预设 id（≤10） |
| behavior.custom | [] | 自定义行为条目（text/once，逐轮注入） |
| behavior.maxBytes | 2048 | 行为注入块上限（256-16384） |
| ui.enabled | true | 图形控制台总开关（关闭则不启动面板也不挂载路由） |
| ui.standalone | true | 在 dsh 进程内启动独立面板服务（127.0.0.1:17654） |
| ui.host | "0.0.0.0" | allowLan=true 时的绑定地址（否则忽略，恒为回环） |
| ui.port | 17654 | 面板端口（1-65535） |
| ui.allowLan | false | 显式允许非回环绑定（局域网访问，默认关闭） |
| logging.level | "info" | debug/info/warn/error/silent |

配置示例

只保留模式热切换（最小 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"] },json
"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 追加写、损坏文件自动重置、磁盘不可用时静默降级为内存模式

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

- 10 轮全面自检记录：见 SELF_CHECK_REPORT.md——累计发现并修复 9 个真实缺陷（含多行命令安全绕过、null 崩溃、空引擎试算等），每轮可复现
- 痛点溯源：见 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 © dsh-powerkit contributors