# 开发、调试与发布

## 环境

- Node.js：`^22.19.0 || >=24.0.0`
- npm：10.x（DSH CLI 执行插件包操作时使用 pnpm）
- DeepSeek Harness：0.1.x，且 profile 包含标准 base/web 能力

先确认 Node 版本：

```powershell
node --version
```

如果 Windows nvm 当前仍指向旧版 Node：

```powershell
nvm install 22.19.0
nvm use 22.19.0
node --version
```

## 安装与检查

```powershell
npm install
npm run check
```

`npm run check` 依次执行 TypeScript 检查、Vitest 和构建。成功后重点产物如下：

```text
lib/
├─ index.js
├─ index.js.map
├─ client.js
├─ client.js.map
└─ types/
   ├─ index.d.ts
   ├─ usage.d.ts
   └─ client/...
```

## 本地安装

官方 DSH Desktop 使用自己的 Harness home，而不是标准 CLI 的 `%USERPROFILE%\.dsh`。执行：

```powershell
npm run install:desktop
```

Windows 默认目标为 `%APPDATA%\dsh-desktop\harness\profiles\web`。脚本会把该目录写入子进程的 `DSH_HOME`，并把 `DSH_HOME\.desktop-bin` 放在 PATH 首位，从而使用桌面端自带且与现有 store 匹配的 pnpm。

若自定义发行版明确使用标准 DSH_HOME 下名为 `desktop` 的 profile：

```powershell
npm run install:profile-desktop
```

`scripts/install-profile.mjs` 会：

1. 校验 Node.js 版本。
2. 定位 DSH Desktop 数据目录和内置 CLI。
3. 桌面安装使用桌面端 pnpm shim。
4. 标准 profile 安装才通过 corepack 准备 pnpm。
5. 只有本机确实没有 CLI 时才回退到 `npx` 下载。

安装成功时终端会出现类似输出：

```text
[dsh-install] DSH Desktop home：...\AppData\Roaming\dsh-desktop\harness
dependencies:
+ dsh-skin-token-dashboard link:D:/AI/harness-plugin
Done using pnpm v10.x
```

修改 Host 或 Client 代码后执行 `npm run check`，再完全退出并重新打开桌面应用。启动页的 `__DSH_BOOT__.entries` 应包含 `dsh-skin-token-dashboard`。

## 新增皮肤

在 `src/client/themes.ts` 追加 `SkinTheme`：

```ts
{
  label: '主题名称',
  description: '简短说明',
  definition: {
    id: 'skin-my-theme',
    colorScheme: 'dark',
    tokens: {
      '--dsw-alias-bg-base': '#000000',
      '--dsw-alias-brand-primary': '#00d4ff',
      // 建议同时覆盖文字、边框、层级背景和侧边栏。
    },
  },
}
```

约束：

1. ID 不得为 `light`、`dark` 或 `system`。
2. ID 必须在当前 ThemeRuntime 中唯一。
3. 功能组件只消费语义变量，不写死主题分支。
4. 保证主要文字与背景有足够对比度。
5. 交互态仍需清晰的键盘焦点。
6. 执行 `npm test` 验证 ID 与 Token 字典。

## 修改 Token 汇总

官方投影适配集中在 `src/usage.ts`。若 Harness 改变字段：

1. 更新 `TokenUsageBuckets`。
2. 更新 `parseTokenUsageBuckets()` 的运行时校验。
3. 明确新字段是否与现有桶互斥。
4. 更新公式、测试和 `docs/ARCHITECTURE.md`。
5. 不要把 reasoning token 再加到 output 上。

## 打包与发布

```powershell
npm run check
npm pack
```

Git 仓库安装会运行 `prepare`，因此 TypeScript 源码能够自行生成 `lib/`。发布前应检查 tarball 中包含：

- `lib/index.js`
- `lib/client.js`
- `lib/types/**`
- `cordis.patch.yml`
- `README.md`
- `docs/**`
- `LICENSE`

安装已发布包时，把脚本末尾的 `.` 替换成包名：

```powershell
npx --yes --package=@deepseek-ai/dsh --package=pnpm@11.7.0 -- dsh plugin --profile web add dsh-skin-token-dashboard
```

## 故障排查

### 无法将“dsh”识别为 cmdlet

裸命令 `dsh ...` 只有在全局安装 CLI 且 PATH 正确时才可用。项目默认不要求全局安装，请改用：

```powershell
npm run install:desktop
```

### 执行安装后只有旋转光标

旧版脚本的 `npx` 需要临时解析完整 DSH 依赖树，可能长时间不输出。新版脚本会优先使用本机 DSH Desktop 内置 CLI。若旧进程仍在运行，先按 `Ctrl+C`，再执行 `npm run install:desktop`。

### Unsupported engine 或安装阶段报 Node 版本错误

执行 `node --version`。Node `v22.4.0` 低于最低要求，应升级到 `v22.19.0` 或 Node 24+，然后重新打开终端并安装。

### 插件已安装但没有皮肤设置项

- 安装输出必须显示 `DSH Desktop home：...\AppData\Roaming\dsh-desktop\harness`，否则可能误装到 `%USERPROFILE%\.dsh`。
- 检查 `%APPDATA%\dsh-desktop\harness\profiles\web\package.json` 是否包含本插件。
- 检查启动页的 `__DSH_BOOT__.entries` 是否包含 `dsh-skin-token-dashboard`。
- 检查 `lib/client.js`、package.json 的 `dsh.client` 和 `./client` export。
- 完全退出 DSH Desktop 后重新打开；只关闭窗口不一定结束后台进程。

### Host 插件一直 pending

Host 激活仅要求 `sessionProjections`。标准 base profile 默认提供该服务；精简自定义 profile 需要显式装载：

```yaml
- name: '@deepseek-ai/dsh-session-projection'
```

Token 明细由官方 token-meter 投影写入；缺少它不会阻止插件加载，但统计值会为空。

### Token 显示为零或缺失

模型适配器必须报告 usage。未报告时 Harness 只能做上下文压力估算，不能把估算值冒充计费统计。先确认模型提供方与适配器是否返回 usage。