cyanseek/dsh-native-playbook

dsh-native-playbook

把你已经安装的 DeepSeek Harness 真正用起来。

CI
License: MIT

先用好 DeepSeek Harness 已经提供的能力，再考虑重复开发。

dsh-native-playbook 是连接
DeepSeek Harness 的社区插件，不是独立的
Agent runtime。它只增加一个 native_capability 工具：把任务路由到 DSH 官方能力，判断整条
能力链是否可运行，并在条件明确时安全激活经过审核的原生路径。

English

快速开始

把预构建的 GitHub package 安装到 DSH profile：

dsh plugin --profile web add github:cyanseek/dsh-native-playbook

到这里就结束了。之后正常使用 DSH。 直接描述目标，不需要记 package 名：

在后台运行测试，结束后告诉我结果。
查找这个符号的全部引用。
从历史会话里查找部署方案。

这条路径不需要 clone 仓库、本地构建、批准构建脚本、账号、本项目 API key、本项目配置文件、
守护进程、第二次安装或手工验证。npm package 名留给后续正式发布；在此之前，上面的 GitHub
命令是受支持的安装方式。

常见任务会发生什么

| 任务 | 优先使用的原生路径 | 实际行为 |
| --- | --- | --- |
| 长时间命令 | bash(run_in_background=true) → job_output | 在支持的类 Unix profile 中直接可用；Windows 使用 pwsh。 |
| 符号导航 | lsp | 只有 provider 真正就绪时才用 LSP，否则回退 grep 和 glob。 |
| 历史会话搜索 | session_search | 使用官方、受 workspace 授权的查询工具；在经过验证的 DSH 版本中可首次使用时自动激活，并明确报告是否需要重启 DSH。 |
| 委派调查 | subagent → list_agents / send_message | 使用 DSH 内置的子 Agent 生命周期。 |
| 固定多步骤任务 | workflow | 优先使用确定性的原生工作流引擎，而不是 Shell 编排。 |

插件不会把“package 存在”或“看到了工具名”误判为能力已经可用。

可相信的就绪判断

每条推荐会区分五个生命周期事实：

| 事实 | 回答的问题 |
| --- | --- |
| shipped | 经过验证的 DSH 目录是否包含它？ |
| mounted | 工具或服务是否进入有效 profile？ |
| visible | 当前调用 Agent 能否看到它？ |
| providerReady | provider 前置条件是否真的满足？ |
| operational | Agent 现在能否使用它？ |

汇总状态为 ready、platform-dependent、opt-in、requires-provider、
disabled 或 unsupported。条件变更还会报告 immediate、next-turn、
new-session 或 restart 的生效时机。

安全激活

激活能力被刻意限制在很小的范围：

- 只能执行仓库中已经审核的配方。
- 当前 DSH 版本必须通过明确的兼容性门禁。
- 凭据、安全策略、网络 provider 和任意命令不在激活范围内。
- 每次修改都交给 DSH 校验且可恢复；验证失败时保留原始 profile。
- 停用时恢复精确保存的内容；如果用户后来修改过文件，则拒绝覆盖新修改。

第一条 Tier-1 配方会启用 DSH 官方、受 workspace 授权的会话全文搜索，并使用延迟打开的
本地索引。当前已验证的激活目标是 DSH 0.1.0-rc.6。其他版本仍可使用静态查询，但不会
执行未经验证的配置修改。

Agent Skill

相同的原生优先指导也以 Agent Skill 提供：

npx skills@latest add cyanseek/dsh-native-playbook \
--skill dsh-native-playbook \
--agent codex \
--yes

Skill 保持聚焦，只加载当前任务所需的参考资料。

CLI

CLI 是面向高级检查与自动化的界面。下面标注的命令都支持稳定 JSON 输出：

dsh-native lookup "" [--profile ] [--json]
dsh-native status --profile  [--json]
dsh-native list [--profile ] [--json]
dsh-native explain  [--profile ] [--json]
dsh-native doctor [--json]
dsh-native install --target project|dsh [--json]
dsh-native plan  --profile  [--json]
dsh-native activate  --profile  [--json]
dsh-native deactivate  --profile  [--json]
dsh-native verify  --profile  [--json]

在开发 checkout 中的示例：

pnpm dsh-native lookup "查找全部符号引用" --json
pnpm dsh-native status --profile web --json
pnpm dsh-native plan session_search --profile web --json

Node API

import {
inspectDshProfile,
lookupNativeCapability,
planNativeActivation,
} from 'dsh-native-playbook'

const profile = await inspectDshProfile({ profile: 'web' })
const result = await lookupNativeCapability('后台运行一个耗时测试', { profile })
const plan = await planNativeActivation('session_search', { profile: 'web' })

公开 API 还导出 listNativeCapabilities、explainNativeCapability、
activateNativeCapability、deactivateNativeCapability 和
verifyNativeCapability。公开 API 不会弹出交互式询问。

兼容性与隐私

- 需要 Node.js 22 或 24，以及 DeepSeek Harness。
- 能力事实覆盖 59 项官方工具，固定到 DSH revision c291e7961a51（2026 年 9 月 10 日）。该默认 profile 已启用 HTTP 网页抓取；实时就绪判断仍联合检查工具、路由和 provider。
- 静态查询不要求 DSH；实时就绪判断需要已存在的 DSH profile。
- 不收集遥测。
- API 不访问凭据存储或私有会话内容。
- 本项目是社区扩展，与 DeepSeek 不存在官方从属或背书关系。

卸载

dsh plugin --profile web remove dsh-native-playbook

开发

corepack enable
pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm validate:skill
pnpm validate:plugin
pnpm validate:dsh-plugin
pnpm verify:upstream
pnpm smoke:json
pnpm smoke:consumer
pnpm metrics

CI 会在 Linux、macOS、Windows 的 Node.js 22 和 24 上运行这些门禁，并额外执行干净的
GitHub 消费者安装检查。

另见 CONTRIBUTING.md、SECURITY.md 和
CHANGELOG.md。

许可证

MIT