# 使用细节与开发

## 安装与更新

macOS 用户打开 Harness 的 **插件 → 添加插件**，输入 npm 包名 **`dsh-qiuya-tools`**，安装后点击 **立即启用**。设置入口为 **设置 → QiuYaTools**，左下角账号菜单也可进入。[查看 npm 包](https://www.npmjs.com/package/dsh-qiuya-tools)。

Windows 用户从 [GitHub Releases](https://github.com/z1223473749/dsh-QiuYaTools/releases) 选择与 Harness 进程架构一致的 ARM64 或 x64 安装包。macOS 也可在“添加插件”中粘贴 GitHub 安装链接：

```text
https://github.com/z1223473749/dsh-QiuYaTools/releases/latest/download/dsh-qiuya-tools.tgz
```

npm 镜像源可能延迟同步新版本；暂时找不到包或版本时，可切换到 [npm 官方源](https://registry.npmjs.org/) 后重试，或使用 GitHub 链接。

更新可在 **QiuYaTools → 版本更新 → 检查更新** 中完成。安装完成后完全退出并重新打开 Harness，原有设置保留。

## 使用细节

### 大文本阈值

在设置页编辑“字符数”和“行数”，点击“保存阈值”。字符数允许 `1–1,000,000`，行数允许 `1–100,000`，均为整数；达到任一阈值即转换。Unicode 字符按码点计数，CRLF 算一个换行。原文和换行保留在 TXT 中。

短文本、纯空白、图片、文件及非输入框粘贴保留原行为；原生附件接收失败时回退普通粘贴。旧版本官方 continuable 子代理输入仅接受图片，因此该输入不转换 TXT。上传、重试、删除、发送沿用原生附件流程。

### 多选与归档

Shift 范围按当前可见顺序选择；Command/Ctrl 可增减单条。**仅保留右键菜单操作，不显示多选悬浮条、归档进度或归档完成提示。** 右键已选会话可批量归档、取消选择，Esc 也可取消。

工作区归档按真实成员 ID 处理，也包含折叠隐藏成员，保留工作区和目录；排除空白、子代理与已归档会话。逐条调用官方归档服务，运行中的会话保留 Host 限制。部分失败不会阻断其他成员，失败项保留以便重试；重新打开右键菜单可查看失败信息。

### 会话与工作区菜单

会话右键菜单和原生 `…` 菜单使用同一套操作：置顶/取消置顶、重命名、分叉、归档和复制 ID 沿用 Harness 原生实现；工具箱增加手动未读/已读、复制标题、复制工作目录和打开工作目录。工作区菜单增加移到顶部、复制路径和打开目录。打开目录通过官方 Host 文件管理器接口处理。

手动未读标记保存在当前浏览器本机，再次进入该会话时清除；它独立于后台任务完成提醒。原生独立窗口使用各自的浏览器存储，手动未读标记不跨这些窗口同步。工作区“移到顶部”使用 Harness 的真实持久排序；会话置顶继续由原生服务管理。关闭批量归档后，会话菜单功能仍可独立使用。

### 独立窗口

窗口按会话 ID 复用，继续连接当前 Harness Host，不创建另一份会话。每个窗口固定到自己的目标会话，加载沿用 Harness 页面风格，确认实际正文与目标一致后才显示内容。拖动开始时提前加载该会话，松手分离时显示已经准备的窗口；取消或在列表内放下会清理隐藏窗口，已打开的窗口保留。关闭该功能后撤下菜单与拖拽入口。取消拖放、列表内部排序、已接受的其他拖放以及多选拖动不会触发分离。

窗口会复用会话目录正在进行的读取；读取结束仍未就绪时，进行三次有限重试，持续失败则显示可关闭的失败页。首次通过菜单打开仍需初始化独立网页客户端，速度取决于 Host 与会话大小；已经打开的窗口会直接唤起。

官方 Electron 应用没有开放原仓的窗口 IPC，所以插件带一个 Swift/AppKit/WKWebView 辅助应用。认证地址只通过 stdin 传递，程序退出随 Host 生命周期清理。每个会话使用独立的 WebKit 网络与存储实例，避免多个页面的长期更新连接挤满同一个 HTTP 请求池。macOS 14+ 按 Harness 配置目录和会话 ID 分配稳定的持久存储，关闭再打开同一会话继续复用；旧的共享存储保留。macOS 13 使用各窗口独立的临时存储。独立窗口使用标准 Web 附件上传，不提供官方 Electron preload 的本机路径引用接口。

会话数据和功能开关连接同一 Host。批注草稿保存在各浏览器的本地存储中，主窗口与辅助窗口的批注草稿不互通；辅助窗口的本地存储还受 Host 端口对应的网页来源限制。macOS 13 的辅助窗口关闭后不保留本地批注草稿，主窗口不受影响。

本分支原生独立窗口支持 macOS 和 Windows。Windows 使用独立的 C# / WinForms / WebView2 进程，按 Host profile 与会话的存储标识隔离用户数据目录；认证地址只通过 stdin 传递。用户无需安装 .NET SDK，仍需系统 WebView2 Runtime。不同原生架构的运行结果、文件选择/附件和真实宿主验收分别记录。

### 计划评论

每个待审计划自动打开一次全文预览，也可手动“查看全文”。在原文中选择文字添加批注，支持高亮、悬停阅读、编辑、单项和批量删除，评论保存在客户端。原文改变且无法可靠定位时标记为已变化，不错误定位。

无评论时只有计划审批卡；有评论后同一位置切换为修正卡；删除最后一条立即切回审批。修正直接提交独立提示，不覆盖原有输入草稿和附件。失败保留评论；只有相应用户消息真正写入会话记录后才清理已提交评论。历史卡片只读，编辑评论期间暂停计划等待计时。

### 提示词建议

会话回复结束且输入框为空时，显示当前会话的浅灰色建议，失去焦点仍保留。聚焦输入框后按 Tab 填入，仍需手动发送；按 Esc 隐藏本轮建议。已有草稿、附件、引用、输入法组合输入或正在运行的会话不会触发推荐。原生菜单打开时保留建议，Tab 和 Esc 优先交给菜单。

建议只读取当前主会话最近的用户和助手文字，不读取文件、附件、工具结果或推理内容。使用当前会话所选模型进行独立短请求，会产生少量额外模型用量；不创建会话、不发送消息，也不把建议写入聊天记录。相同回复会去重缓存；切换会话、页面隐藏或关闭功能时取消请求，失焦时保留正在生成和已经显示的建议。每个输入框绑定固定会话，并核对原生当前会话选择与 DOM 会话标记，旧请求不能填入新会话。

## 开发与验证

Node.js `^22.19.0 || >=24`，npm；macOS 原生窗口构建还需要 Command Line Tools 的 `swiftc`。

Windows 原生源码构建固定使用 .NET SDK `8.0.426` 和锁定的 WebView2 SDK `1.0.3912.50`，运行包自包含 .NET。使用 `QIUYA_DOTNET=/path/to/dotnet node scripts/build-windows-native.mjs arm64 x64` 构建。`package-candidates.mjs` 按平台分包，保留压缩 64 MiB/解压 256 MiB 的现有校验上限，并逐个核验原生组件 SHA256、协议及架构。

电脑操控的授权、原生预检、配对和真实 E2E 入口见[使用指南](computer-use-guide.md)。桌面测试只在显式运行对应脚本时启动；普通 `npm run check` 不申请系统权限、不操控桌面。

```sh
npm ci
npm run build
npm run check
```

`check` 执行严格类型检查、完整构建和测试。测试覆盖真实 DOM/React 交互、配置原子保存、快速启停和异步清理、附件接收、批量归档目标与失败处理、计划批注定位和耐久回执、窗口 RPC/进程生命周期及拖拽排序保护。归档测试使用隔离 fixture，不操作真实会话。

Host 将配置校验库一起打包，只保留 Node 内置模块作为运行时导入；Client 继续使用 Harness 提供的共享模块。发布前还会对最终 tgz 执行 `node scripts/verify-package.mjs <安装包路径>`，在没有开发依赖的空目录中加载 Host 并验证配置与注册。

### 版本发布

GitHub 正式版本与 npm 包使用相同版本号。配置好 npm 发布授权后，发布工作流会在 GitHub 新版发布后，将同一版本安装包同步到 npm；同步失败时应查看 Actions 报错并重试，镜像源还可能需要额外同步时间。

发布前更新 `package.json` 版本和 `CHANGELOG.md` 对应记录，版本标签使用 `v<版本号>`。工作流会先执行完整检查、构建通用 macOS 安装包并验证最终 tgz，再发布 GitHub 和 npm。GitHub 更新说明直接读取该版本的中文日志，缺少日志时停止发布。

首次发布需要 npm 账号登录。包创建后，在 npm 的包设置中添加 GitHub Actions 受信任发布者：用户为 `z1223473749`，仓库为 `dsh-QiuYaTools`，工作流文件为 `release.yml`，环境留空，并允许 `npm publish`。此后由 GitHub OIDC 完成认证，无需在仓库保存 npm token。配置方式见 [npm 官方说明](https://docs.npmjs.com/trusted-publishers/)。

如 npm 同步失败，可从对应版本标签手动运行 `Build and release` 重试。已存在的相同版本只在安装包校验值一致时跳过；校验值不同会停止，避免将不同内容视为同一个版本。

npm 会先扫描新发布的版本，公开索引可能延迟数分钟。工作流会等待最多约 15 分钟，并确认公开安装包的完整性与版本标签；超时后可稍后重试，同一版本不会重复上传。

| 路径 | 职责 |
| --- | --- |
| `src/index.ts` | Host volatile Config 和窗口通道 |
| `src/shared.ts` | 共享配置、默认值和字段校验 |
| `src/client/index.tsx` | QiuYaTools 设置页 |
| `src/client/about.tsx` | 关于我们、开源地址与更新入口 |
| `src/updates/` | 固定 GitHub 来源、版本比较、包验证与官方安装管理器接入 |
| `src/client/features.ts` | 按配置启停各功能子 fiber |
| `src/client/feature-switchboard.ts` | 串行启停与异步资源清理 |
| `src/features/pasted-text/` | 大文本附件 |
| `src/features/session-windows/` | 会话菜单、拖拽、Host 和原生窗口 |
| `src/features/bulk-archive/` | 范围选择及右键归档 |
| `src/features/plan-comments/` | 计划全文评论、单卡修正和回执 |
| `src/features/prompt-suggestions/` | 当前会话提示词推荐、灰字预览和 Tab 填入 |
| `scripts/build.mjs` | Host ESM、客户端 lazy-CJS/CSS 与原生辅助程序构建 |

运行时通过官方 slots、会话/工作区服务、连接服务和配置接口协作，不修改原项目或官方安装包。少数没有公开插件扩展点的行为以官方 `0.2.1-rc.2` 的稳定 DOM 与输入提供者契约适配，升级 Harness 后应重新验证。