dsh-TUI 上手

1. 安装安装两个全局包

   sh

   npm i -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui

   以一条命令安装 dsh CLI 与 dsh-tui 插件两个全局包；pnpm 用于首次启动时初始化 profile。

2. 安装技能以文件复制方式安装

   sh

   mkdir -p ~/.dsh/skills
   cp -R /path/to/my-skill ~/.dsh/skills/

   技能目录由宿主自动监听，无需重启，在下一次模型步骤中即生效。

3. 启动首次启动自动创建 profile

   sh

   cd ~/your-project && dsh-tui

   在项目目录启动 dsh-tui；首次启动自动创建 profile，无需手动执行 dsh plugin add。

4. 配置模型三种方式任选

   会话内通过 /provider 配置路由与密钥、/model 选择模型（首次配置推荐）；或修改 profile 补丁；或设置环境变量。

5. 启用完全访问关闭审批拦截

   会话内按 Shift+Tab 循环至「完全访问」——即时生效，但仅作用于当前会话；如需每次启动均默认启用，见第七章。

6. 寻优参数采集生成提交 SKILL 的 JSON

   用采集台（model-oob-perf-optimize-params.html）一次性采齐部署拓扑、业务建模与寻优目标，实时输出结构化 JSON，直接提交给寻优 SKILL。打开采集台：寻优参数采集台。

3.1核心认知：技能即目录，以 cp 方式安装

DSH 技能没有注册表文件、没有安装命令、也没有 lockfile。宿主每次扫描固定目录，看到 <name>/SKILL.md 即予以收录。因此：

cp -R <技能目录> ~/.dsh/skills/     # 安装完成

无需 dsh plugin add，也无需重启（详见 3.5）。

3.2两个落点

• rank 数值越小优先级越高：项目级优先于用户级。
• <项目根> 即最近的含 .git 的祖先目录；若无 .git，则回退至当前 cwd。
• ~/.dsh/skills 下的 .system 子目录会被忽略。

3.3目录形态（发现深度仅一层）

<root>/<name>/SKILL.md      ← 目录形态（可带 references/ scripts/ assets/）
<root>/<name>.md            ← 平铺单文件形态

• <name> 建议采用 kebab-case，即 /skills 中显示的名称。
• 不支持嵌套发现：<root>/a/b/SKILL.md 不会被收录。这一点直接决定 cp 命令的写法（见下文）。

3.4三种复制场景

mkdir -p ~/.dsh/skills
cp -R /path/to/my-skill ~/.dsh/skills/
# 结果：~/.dsh/skills/my-skill/SKILL.md

unzip -q my-skill.zip -d ~/.dsh/skills/
# 结果：~/.dsh/skills/my-skill/SKILL.md

unzip -q pkg.zip -d /tmp/pkg
find /tmp/pkg -name SKILL.md          # 定位包含 SKILL.md 的目录
cp -R /tmp/pkg/some-repo-main-skills/my-skill ~/.dsh/skills/

# 错误：目标目录已存在时会形成嵌套 ~/.dsh/skills/my-skill/my-skill/SKILL.md，技能直接消失
cp -R /path/to/my-skill ~/.dsh/skills/

# 正确：
rm -rf ~/.dsh/skills/my-skill && cp -R /path/to/my-skill ~/.dsh/skills/

3.5安装后的确认方式与生效时机

验证步骤：

# 1) 检查目录结构（必须直接看到 SKILL.md，中间不得再隔一层）
ls ~/.dsh/skills/my-skill/

# 2) 确认 frontmatter 包含 name 与 description
head -6 ~/.dsh/skills/my-skill/SKILL.md

3）回到会话中执行 /skills，在列表中查找该技能：

/skills 是全量目录浏览器（所列为模型可见技能的完整集合）；选中后按 Enter 仅将 /my-skill 填入输入行，不会代为执行。

改内容 vs 改目录：

3.6frontmatter 写错的后果：技能会被静默丢弃

DSH 仅识别 name 与 description 两个必填字段，其余为可选。字段写错不会显示错误，仅表现为技能不再出现。以下为本机实测结果：

一个最小可用模板：

---
name: my-skill
description: 一句话说清它做什么、什么时候该用（这句话决定模型会不会调用它）
---

# my-skill

（正文：执行步骤、约束、示例）

3.7同名技能会静默冲突

实测表明：当项目级与用户级存在同名技能时，两层均会被扫描（rank 100 与 400 各一份），最终由注册表层按“近层遮蔽远层”的规则裁决，仅生效其中一个，且无任何提示。

因此应避免在不同层级放置同名技能；升级用户级技能前，须先确认项目中不存在同名副本。

# 进入项目目录后启动（启动目录即 Agent 的默认工作区）
cd ~/your-project
dsh-tui

三个等价入口：

A交互式向导（推荐）

进会话后依次：

/provider 里三种添加方式：

1. 内置 provider：从 catalog 中选择（deepseek、openai、anthropic 等），仅需填写 API Key；可选覆盖 baseURL（用于代理网关）
2. 自定义 API 端点：填写路由名 / Key / baseURL / 协议（openai-completions、openai-responses、anthropic-messages）；向导将以草稿凭据探测端点公布的模型供勾选
3. 订阅账号登录（OAuth）：使用 ChatGPT / Claude / Grok 等订阅账号登录，无需 API Key（@deepseek-harness-tui/dsh-auth 已作为依赖随包安装）

向导写两个产物：

与 dsh web 的 Models 设置页互通（同一 settings section）。会话记录中密钥仅显示为 ••••••。

B声明式：修改 profile 补丁

$DSH_HOME/profiles/dsh-tui/cordis.patch.yml（顶层为 YAML 数组）：

- id: dsh-tui
  config:
    provider: deepseek-official
    model: deepseek-flash
    effort: max

四个注意点：

• config 为整块替换而非深合并：所修改字段所在的 config 块将被整段覆盖，原依赖 base 继承的其他字段需一并重写。
• provider 与 model 必须同时配置才构成显式路由；只写一个不生效。
• 修改后必须重启进程（/restart 或退出重进）；/reload 不会应用补丁。
• 不要在补丁中写入 cwd: !!js process.cwd()：这会把工作区固定于启动子目录（issue #96）。默认解析为启动目录所在的 git worktree 根，通常无需处理。

C最简方式：环境变量

export DEEPSEEK_API_KEY=sk-xxxxxxxx
# 自建/代理端点：
export DEEPSEEK_BASE_URL=https://your-endpoint/v1

当进程环境已存在同名变量时，/provider 向导会跳过写入，运行时直接从环境解析（删除时亦不触碰环境变量）。适用于 CI 与临时试跑。

6.1打开采集台

采集台是一个独立的单文件 HTML（model-oob-perf-optimize-params.html），无需后端、无需联网，双击或在浏览器打开即用。本指南在线版也附带同款入口：打开寻优参数采集台。

6.2选择运行模式

6.3填写部署拓扑（Phase 0）

选择部署形态，决定后续哪些字段必填：

• 单机标准：自动采集 NPU，无需额外输入。
• 多机：需填 node0 通信 IP、worker SSH 信息；拓扑 JSON 智能模式可留空（由 SKILL 推导），离线模式必填。
• PD 分离：需填 PD SSH 节点（多节点必填），其余（速记部署、端口、connector、proxy 等）可留空由 SKILL 推导。

6.4填写业务建模（Phase 2）

描述压测负载，标 * 为必填：

6.5填写寻优需求（Phase 3）

指定模型与寻优目标：

• 模型权重路径 *：如 /mnt/weight/llama-7b。
• 硬件要求：留空用 Phase 0 检测值；PD/多机须含节点数（如“2节点×8张A3卡”），禁止裸集群总量。
• 寻优目标 *：吞吐优先 / TTFT < Xms 下最大吞吐 / TPOT < Xms 且 TTFT < Yms 下最大吞吐，阈值可自定义。
• 启动 / 测试脚本、寻优变量、环境变量：可选；留空由 SKILL 推导或保持脚本固定值。

6.6离线推理：全字段人工输入（仅离线模式）

切到“离线推理”后，采集台展开独立的“全字段人工输入”区，要求逐项手填：

• 硬件信息：npu_type、card_count（必填）；chip_count / soc_version / hbm_size_gb 留空按型号推断（A2 = 卡数，A3/A5 = 卡数×2）。
• 软件版本：vllm_version、vllm_ascend_version、cann_version（仅数字，必填）；torch / torch_npu / transformers 可选。
• 平台微架构 9 项：platform_l2_size_mb 等，缺省用内建默认值。
• 模型 config.json 路径 / 链接 *：无法提供将阻断流程。

6.7获取并提交结构化 JSON

右侧“实时输出”面板随表单即时更新：

• 必填项完成度：进度条显示“已完成 / 总数”，缺失项以红色 badge 列出并支持点击跳转。
• 实时 JSON：按当前填写生成结构化 JSON，语法高亮。
• 复制 / 下载：“复制 JSON”得到提交给 SKILL 的纯参数；“复制触发指令”会附带模式与拓扑触发词（如“一键寻优（单机）”）；“下载 .json”存为本地文件。

一键寻优（单机）

{
  "mode": "智能模式",
  "topology": "单机标准",
  "business_modeling": { "tool": "evalscope", "concurrency": "64", "input_len": "4096", "output_len": "1024" },
  "optimization_requirement": { "weight_path": "/mnt/weight/llama-7b", "goal": "吞吐优先" }
}

把复制到的 JSON（或触发指令）直接提交给 model-oob-perf-optimize SKILL，即可进入自动寻优流程。

7.1三个权限档位的说明

7.2原理：为何切换档位后下次又恢复默认

模式状态不保存于任何配置文件，而是由会话日志折叠推导得出——plan/mode、sandbox/mode、approval/policy 三类会话事件，取最后一次生效的值。新会话不存在这些事件，因而回落到 modes 数组的第 0 项（基础档）。

由此得到两条结论：

• Shift+Tab 与 /permission 仅对当前会话生效，切换会话即恢复基础档；
• 如需让“自动”成为每次启动的默认，须修改配置（见 7.4）。

（附带效果：循环起点取自“日志推导出的档”而非存储索引，因此手动执行 /plan 不会导致 Shift+Tab 档位顺序错乱。）

7.3方式一：会话内切换（仅作用于当前会话）

7.4方式二：设为每次启动的默认权限档位（长期使用推荐）

# $DSH_HOME/profiles/dsh-tui/cordis.patch.yml
- id: dsh-tui
  config:
    provider: deepseek-official      # config 为整块替换，原有字段需一并写全
    model: deepseek-flash
    modes:
      - id: auto                     # 置于首位 = 启动即生效该档位
        label: 自动
        sandbox: danger-full-access
        approval: never
      - id: default
        plan: false
        sandbox: workspace-write
        approval: ask
      - id: plan
        plan: true
        sandbox: read-only
        approval: ask

要点：

• 数组顺序即 Shift+Tab 的循环顺序；第 0 项为无标记的基础档，新会话默认落于此处。
• 不应保留内置的 full 档：它与新增的 auto 档原子完全相同，匹配时永远命中靠前的条目，导致后一档在循环中成为死档（Shift+Tab 永远无法到达）。
• 每个条目支持 plan / sandbox / approval / permission；permission 可与 plan 并用，但与 sandbox、approval 互斥；未声明任何原子的条目将被丢弃。
• 修改后通过 /restart 生效；/reload 不应用补丁。

7.5方式三：环境变量（临时，不写入磁盘）

DSH_PERMISSION_MODE=danger-full-access dsh-tui

非 Windows 平台以该变量覆盖沙箱策略。沙箱限制已完全放开后，不再出现需要提升权限的场景，审批自然不再弹出——适用于 CI 或一次性试跑。

7.6折中方案：保留边界、关闭审批

不采用完全放开，仅关闭审批：将 7.4 中的 auto 档替换为：

- id: auto
  label: 半自动
  sandbox: workspace-write     # 保留工作区边界
  approval: never              # 不再打断操作

7.7风险与平台差异

# 安装
npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
npm install -g pnpm            # ≥10
cd ~/your-project && dsh-tui

# 配置模型（会话内）
/provider                      # 添加路由与 API Key
/model                         # 选择模型
/effort                        # 调整推理等级
/login  /balance               # 凭证 / 余额查询

# 配置模型（环境变量，最简方式）
export DEEPSEEK_API_KEY=sk-xxx
export DEEPSEEK_BASE_URL=https://your-endpoint/v1   # 可选

# 权限：授权工具自动执行、不再弹出审批提示（见第七章）
Shift+Tab                      # 会话内循环切换档位，直至完全访问
/permission danger-full-access # 或直接指定权限预设
DSH_PERMISSION_MODE=danger-full-access dsh-tui   # 临时生效（不写入磁盘）
# 永久默认：修改 cordis.patch.yml 的 modes[0]（数组第一项即基础档位）

# 安装技能（以文件复制方式）
mkdir -p ~/.dsh/skills
cp -R /path/to/my-skill ~/.dsh/skills/              # 首次
rm -rf ~/.dsh/skills/my-skill && cp -R /path/to/my-skill ~/.dsh/skills/   # 升级

# 验证
ls ~/.dsh/skills/my-skill/     # 须直接看到 SKILL.md
head -6 ~/.dsh/skills/my-skill/SKILL.md   # 须包含 name 与 description
# 会话内：通过 /skills 查找名称，/doctor 检查整体健康

常见错误与规避

• dsh-TUI 官网 —— DeepSeek Harness 的 Claude Code 风格全屏终端界面：安装、功能、命令、快捷键与架构说明。