# pilot-harness

> 为 DSH Web/Desktop 客户端换上 CodePilot 视觉皮肤的纯表现层主题包，不改交互逻辑与模型上下文。

## Metadata

- Author: [@op7418](https://github.com/op7418)
- Repo: <https://github.com/op7418/pilot-harness.git>
- GitHub: [op7418/pilot-harness](https://github.com/op7418/pilot-harness)
- Stars: 240
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `ai-agent`, `codepilot`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `linux`, `macos`, `typescript`, `windows`
- Forks: 13
- Open Issues: 16
- Last push: 2026-08-20T12:42:53.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:op7418/pilot-harness/packages/client/ui-codepilot-theme
```

## Wiki

## 一句话定位
为 DeepSeek Harness 客户端换上 CodePilot 视觉风格（浅色/深色配色、毛圆角、内嵌品牌图标），不改交互逻辑也不影响模型。桌面端会同步把原生标题栏外观切到同一个主题模式。

## 核心能力
- 注入 CodePilot 浅色与深色两套配色，覆盖 Pilot 颜色/平台表面 token 和 Harness 的语义、组件、阴影 alias token
- 在 `html` 根元素上设置 `data-codepilot-theme="true"` 激活标记；卸载插件时还原该属性之前的状态
- 内置品牌图标（以 data URL 形式打包进 bundle），覆盖空会话页 hero 区、侧边栏展开/收起态以及 About 页品牌位
- 桌面端通过 Electron preload 桥把当前主题模式（system/light/dark）同步给原生窗口，更新窗口材质、背板与 Windows 标题栏按钮
- 订阅 `theme/change` 事件跟随应用内主题切换，在桌面端保持原生外观与客户端一致
- 加载与卸载完全可逆：移除激活标记、释放 effect 订阅、依赖 CSS 模块作用域自动失效，回到默认主题

## 技术实现
- **语言**: TypeScript（ESM，两个 tsconfig 产物：host 与 client）
- **关键依赖**: `@deepseek-ai/cordis`、`@deepseek-ai/dsh-client-runtime`、`@deepseek-ai/dsh-client-ui-theme`、`@deepseek-ai/dsh-invariants`（均为 peerDependencies，以 workspace 形式解析）
- **架构模式**: DSH Client 端 Cordis 插件，`package.json#dsh.client` 声明 `platform: "web"`、`inject` 仅供预检显示；通过 CSS Modules + 根元素 `data-codepilot-theme` 属性作用域注入样式；`ctx.effect()` 钩子负责激活标记的设置/还原和桌面端主题事件订阅的生命周期
- **入口文件**: `src/client/index.ts`（激活与同步逻辑）、`src/index.ts`（host marker 占位）、`src/invariant.ts`（声明包名、附带"无 runtime invariant"原因）、`src/client/theme.module.css` 与 `src/client/brand-icon.module.css`（样式）

## 适用场景
想让 DSH 客户端换成 CodePilot/Luma 视觉风格的普通用户。安装一次就生效，没有配置项，没有副作用；如果只想临时看一眼，也可以装上后随时卸载。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.7 | peerDependencies 使用 `workspace:^`，跟随宿主 DSH workspace |
| Node | >=22.19.0 | 根 `package.json#engines.node: ^22.19.0 \|\| >=24.0.0` |
| 平台 | macOS / Windows / Linux / Web | 浏览器端仅使用 CSS；桌面端额外依赖 Electron preload 桥 |
| 原生模块 | 无 | 纯样式 + Cordis effect 钩子，不引入 node-gyp 模块 |

## 安装方式

```bash
dsh plugin --profile web add github:op7418/pilot-harness/packages/client/ui-codepilot-theme
```

## 配置项
本插件无需额外配置。`package.json` 没有声明 `Config` schema，源码里也没有读取任何配置或环境变量；样式、激活标记、同步逻辑都是写死的。

## 常见问题

**Q: 安装后怎么确认生效？**

A: 重启 Web profile 后执行 `dsh --profile web --dump-config`，能看到 `codepilot-theme` 节点即加载成功；也可直接打开客户端看侧边栏与空会话页是否已换上 CodePilot 视觉。

**Q: 怎么卸载回到原主题？**

A: 执行 `dsh plugin --profile web remove @deepseek-ai/dsh-client-ui-codepilot-theme`，重启 profile 即可。卸载时 `data-codepilot-theme` 标记会被清除，之前若有别的取值也会一并还原。

**Q: 装上之后会不会改变模型回答、对话内容或工具行为？**

A: 不会。源码与 README 都声明它不注册任何面向模型的上下文、工具、事件或请求内容，纯客户端表现层替换。

**Q: 桌面端和浏览器端都能用吗？**

A: 都能。浏览器端只应用同一份 CSS；桌面端多走一步：把当前主题（system/light/dark）通过 Electron preload 桥同步给原生窗口，让标题栏、材质、窗口背板跟随切换。

**Q: 装这个主题会让我之前的 KV 缓存失效吗？**

A: 不会。README 明确写出 Model Experience 与 KV Cache 影响均为"无"，加载或卸载只影响客户端显示，不动模型输入。

**Q: 跟我已经装的别的样式/主题插件会冲突吗？**

A: 浅色和深色两边都覆盖了同一组 Pilot 与 Harness 语义 token，加载顺序靠后的插件样式不会留下浅色文字、侧栏材质等错位值；卸载时干净还原，不互相污染。

**Q: 如果产品图标文件改了，主题会自动更新吗？**

A: 不会。每次改动 `apps/desktop/assets/icon-master.png` 后，需要在仓库根目录手动跑一次 `pnpm --filter @deepseek-ai/dsh-desktop run icons` 来重新生成 bundle 里的品牌样式表，然后重新打包发布。

## 上手难度
入门 — 一条 `dsh plugin add` 命令 + 重启 profile 即可，没有配置项、不会改模型上下文，普通用户可以直接装上试用、不喜欢再卸载。

## 已知问题与限制
- 修改 `apps/desktop/assets/icon-master.png` 后必须运行 `pnpm --filter @deepseek-ai/dsh-desktop run icons` 才能刷新 bundle 里嵌入的品牌样式表，否则客户端仍展示旧图标。
- 新增的品牌位需要先在宿主上加 `data-pilot-brand-mark` 表现层挂钩并完成视觉审计，主题才能以可逆方式替换；上游新增品牌位置而未加挂钩时，本插件不会自动接管。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [pilot-harness](https://deepseek-plugin.org/plugins/op7418/pilot-harness/packages/client/ui-codepilot-theme)
Wiki generated by AI (model: `MiniMax-M3`)