# pilot-harness

> 为 DeepSeek Harness Web 版提供工作区文件树面板，可在对话页头一键开关，支持新建、重命名文件目录以及把路径加入对话草稿。

## 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/workspace/ui-worktree
```

## Wiki

## 一句话定位
pilot-harness（包名 `@deepseek-ai/dsh-ui-worktree`，Cordis 插件 ID `pilot-worktree`）是 DeepSeek Harness Web 版的工作区文件树面板。在对话页头多出一个 "Files" 切换按钮，点开后右侧出现一栏真实布局的文件目录树，方便浏览当前项目、创建/重命名文件/目录，以及把文件路径以 `@路径` 形式快速加入对话草稿。

## 核心能力
- 在会话头新增 "Files" 切换按钮，弹出右侧文件树侧栏并自动收窄对话区宽度
- 列出当前 Workspace 的目录树，支持嵌套展开与目录/文件排序
- 显示 Workspace 根目录的可见文件数（自动跳过 `.git`、`.DS_Store`、`node_modules`、符号链接）
- 每个文件/文件夹行提供三点菜单：用本机应用打开、把 `@路径` 追加到当前会话草稿、重命名
- 工具栏支持新建文件、新建目录和整体刷新
- 通过 `summary=branch` 路径直接读取 `.git/HEAD`，在工作区侧栏概要里展示当前 Git 分支（游离 HEAD 显示短提交前缀，非 Git 项目不显示这一行）

## 技术实现
- **语言**: TypeScript + React（TSX 组件）
- **关键依赖**: `@deepseek-ai/cordis`、`@deepseek-ai/dsh-client-runtime`、`@deepseek-ai/dsh-client-connection`、`@deepseek-ai/dsh-workspace`
- **架构模式**: 双面插件 —— `src/index.ts` 注册 Host 端 `/pilot-worktree` RPC（loopback 授权），`src/client/index.ts` 注册浏览器端 React 组件并通过 cordis patch 注入宿主
- **入口文件**: `src/index.ts`（Host RPC 注册）/ `src/client/index.ts`（浏览器组件注册）/ `cordis.patch.yml`（cordis 装配 patch）

## 适用场景
想在和 AI 对话时直接浏览工作区文件、引用多个路径或快速新建/整理项目目录的人。比如开发者跟 AI 讨论代码时想引用 `src/auth/login.ts` 这种具体路径，或者要在不离开对话页的前提下新建文件/目录并立即让 AI 看到。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH（宿主） | 未声明（需 Pilot Harness v0.1.0+） | 宿主必须公开 `conversation.session.header.utilities`、`shell.right-sidebar`、`sidebar.workspaces.session.detail` 三个呈现槽位 |
| Node.js | ^22.19.0 \|\| >=24.0.0 | 来自根 `package.json` 的 `engines.node` |
| 平台 | 跨平台 | 源码头部只引用 `node:fs/promises` 等内置模块，未声明 `os`/`cpu` 限制 |
| 原生模块 | 无 | 仅使用 Node 内置 `fs/promises`、`path`，无 `node-pty` 等原生依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:op7418/pilot-harness/packages/workspace/ui-worktree
```

## 配置项
本插件无需额外配置。所有交互参数（工作区 ID、相对路径、操作类型）都通过 RPC 请求动态传入，源码中未暴露可由用户在 `cordis.yml` 调整的 Config 字段。

## 常见问题

**Q: 这个插件依赖 Electron 或桌面客户端吗？**

A: 不依赖。它是普通 Web profile 插件，浏览器端和 Host 端通过 loopback 授权的 Connection RPC 通信，不依赖 Electron。原生"打开文件"调用走的是宿主运行时受 loopback 保护的 `openPath` 路径，不绕过浏览器安全边界。

**Q: 安装后看不到 Files 按钮或右侧栏怎么办？**

A: 上游 Harness 版本必须支持三个呈现槽位契约 —— `conversation.session.header.utilities`、`shell.right-sidebar`、`sidebar.workspaces.session.detail`。Pilot Harness v0.1.0 已包含这些契约；旧版 Harness 可以加载插件但无法渲染 UI。

**Q: 能删除文件吗？**

A: 不能。删除属于不可逆操作，插件有意只暴露新建文件、新建目录、重命名三种目录操作。需要删除文件请使用系统文件管理器或命令行工具。

**Q: 面板里看不到某些文件？**

A: 插件主动跳过 `.git`、`.DS_Store`、`node_modules`、符号链接，以及非常规的文件类型（如 socket、块设备）。单个目录的列举上限是 5,000 项、Workspace 根目录的递归计数上限是 20,000 个可见文件，超出会显示为"截断"提示而不是无限制读取。

**Q: 可以远程访问文件吗？**

A: 不可以。RPC 通道使用严格 loopback 授权，不提供 trusted-host 例外。即使把 LAN origin 加到 Harness 的 `trustedHosts` 设置也不会获得远程文件系统访问权限 —— 远程 Web 场景需要插件未提供的独立认证传输层。

**Q: 如何确认安装成功？**

A: 安装后重启 Web profile，然后运行 `dsh --profile web --dump-config`，确认输出里列出 `pilot-worktree` 条目。

**Q: 如何卸载？**

A: 运行 `dsh plugin --profile web remove @deepseek-ai/dsh-ui-worktree`，重启 Web profile 后标题栏的 Files 控件和右侧栏会一起消失。

**Q: 把文件加到对话草稿时，AI 真的会"看到"这个路径吗？**

A: 只是把 `@路径` 文本追加到用户草稿里，是否发送由 conversation 包决定；插件不注入隐藏模型上下文、不添加工具 Schema、也不写 Session 事件。

## 上手难度
入门 —— 安装一条命令后无需任何配置，会话头即出现 Files 按钮；普通用户也能直接使用浏览、新建、重命名和路径引用。

## 已知问题与限制
- Workspace 根目录递归统计在达到 20,000 个可见文件后停止，并标记为截断计数
- 单个目录列举在 5,000 项后停止并标记为截断，避免一次性缓冲整个超大目录
- 故意不提供删除操作（不可逆），目前支持的目录变更只有新建文件、新建目录、重命名
- 名称校验会拒绝 Windows 保留设备名（CON/PRN/AUX/NUL/COM1-9/LPT1-9 等）、备用数据流语法、末尾带点的名称；重命名不会覆盖已有条目，目标冲突时报错
- 原生标题栏拖动和原生目录选择框是桌面外壳能力，纯浏览器组合无法获得
- 文件 RPC 严格 loopback 授权，没有 trusted-host 例外；LAN 远程访问不被支持
- 不暴露 Git 子目录详情、依赖目录、平台元数据和符号链接
- 旧版上游 Harness（缺少三个呈现槽位契约）可以加载 bundle 但无法显示 Files 控件或右侧栏

---

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/workspace/ui-worktree)
Wiki generated by AI (model: `MiniMax-M3`)