dsh-native-playbook

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

先用好 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 "<task>" [--profile <name>] [--json]
dsh-native status --profile <name> [--json]
dsh-native list [--profile <name>] [--json]
dsh-native explain <capability> [--profile <name>] [--json]
dsh-native doctor [--json]
dsh-native install --target project|dsh [--json]
dsh-native plan <capability> --profile <name> [--json]
dsh-native activate <capability> --profile <name> [--json]
dsh-native deactivate <capability> --profile <name> [--json]
dsh-native verify <capability> --profile <name> [--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。
• 能力事实固定到 DSH 官方源码的一个明确 revision。
• 静态查询不要求 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