# dsh-plugin-branch-origin · 开发项目维护

面向作者、维护者与协作 Agent，保存本轮范围、作者理解、已采纳取舍和检查流程。公开使用说明见 [中文 README](README.zh-CN.md) / [English README](README.md)。

文件名与所在目录不会限制访问；是否公开本文件由实际内容及项目发布范围决定。本仓库不含私人自述、原始会话或原始审计材料；未核验内容按文中状态标注。

> 为使用 DSH Desktop 的人解决「分叉出来的对话看不出是从哪个对话分出来的」。先完成一个可验证的使用场景，再逐步扩展。

## 目标与范围

- 本轮用户场景：在侧栏对一条对话点「分叉会话」之后，用户要能一眼看出这条新会话是从哪个对话分出来的 —— **包括把这条分叉改名之后**。
- 完成定义：侧栏该行行首出现 `⤷` 徽标，悬停该行出现「来源」段并显示源对话标题；同时会话标题被改写成 `⤷ 来源：<源标题>`。改名后徽标仍在、悬停仍显示源对话名。
- 本轮范围与限制：**只标注、不接管**；不创建分叉、不画树、不改 parent pointer、不注册模型可见工具。只对**装载之后**新建的 fork 生效（不做启动扫描）。宿主契约按 DSH 0.2.0-rc.2 核对，仅在 Windows 上实测。

## 作者视角（我用自己的话维护）

> 下面三行由协作 Agent 依据已核实事实起草，**待作者用自己的话确认或改写**；与作者理解不一致时以作者版本为准。

- 核心路径：用户分叉 → 宿主收到带父级的 `session/created` → 等 `settleMs` 600ms 让官方那次 `(1)` 改名落定 → 读出源标题，用 `sessionTitle.rename` 写成 `⤷ 来源：<子标题原文>`；客户端另从官方列表行的 `parentId` 读父级，在行首画 `⤷`、悬停画「来源」段。
- 当前为什么这样做：见下方「已采纳的关键取舍」；最要紧的是 D004（只标注不接管）与 D009（标题 + 徽标两条通道叠加）。
- 下一步要弄清：（1）与 autofork / session-tree 同装时的实际表现（规则上应互相放过，未实测）；（2）`settleMs=600` 在慢机器上是否始终够宽；（3）客户端半边的行首槽在 running 行会被官方状态点顶掉，用户是否接受。

## 运行与验证

| 用途 | 实际命令或操作 |
|---|---|
| 准备环境 | Node v24；**无需安装依赖**（零依赖、无构建链）。真机装置用仓库内的临时 `DSH_HOME`，不碰用户 `~/.dsh` |
| 启动/装载 | `node .verify/install-desktop.mjs`（写 profile，需一次性更宽权限）；随后**完全退出并重开** DSH Desktop |
| 检查本轮改动 | `npm test`（离线 13 + 客户端冒烟）、`npm run rm-test`（真机 14）、`node .verify/check-client-manifest.mjs`、`node .verify/md-lint.mjs` |
| 重现关键场景 | README「安装与启用」第 1–2 步：分叉 → 看行首 `⤷` → 改名 → 徽标仍在 |
| 组合预检（重启前） | `$env:NPM_GLOBAL_ROOT = (npm root -g)` 后 `node --import ./test/register.mjs .verify/diagnose-desktop-compose.mjs` |
| 浏览器机检（9 项） | 步骤见 [.verify/REPORT.md](.verify/REPORT.md) §7.3（无头 Chrome + CDP） |
| 提交前隐私检查 | [.privacy-tools/README.md](.privacy-tools/README.md) |

占位内容已填实际命令；未在本机执行过的检查在下方「公开前核对」标为待核验。

## 项目入口

- [AGENTS.md](AGENTS.md)：Agent 接手、执行和写文件的规则（含本机环境事实与危险边界）。
- [tasks.csv](tasks.csv)：当前功能与缺陷任务；状态为 `todo / doing / blocked / done`。
- `lib/`：实现（宿主 `index.js` + 客户端 `client.js`）；`tests/`：离线检查；`.verify/`：真机与浏览器验收装置；`docs/`：契约与先行者核查。
- `.privacy-tools/`：隐私检查脚本与规则副本（Hook 模板已复制、**未启用**）。

任务表的 `acceptance` 在实施前确定，`scope` 指向相关代码或模块。`evidence` 保存验证方式和产物位置，`verified_revision`、`verified_at` 对应验证时的代码版本与日期；实现变化后重新判断原有证据是否适用。

## 一轮工作

1. 选一个用户场景，把正常表现和关键失败表现写进任务表。
2. 检查相关代码与现有行为，完成一组容易审查的改动。
3. 按场景实际运行，检查与改动有关的测试；无需为简单排版建立完整测试套件。
4. 通过后更新同一任务行和证据位置，在对话中汇报；用户反馈不符时继续修正。

## 已采纳的关键取舍

仅记录会影响后续实现的决定；完整表见 [docs/DESIGN.md](docs/DESIGN.md) §5。

| 编号 | 日期 | 决定与原因 | 依据或确认人 | 状态或替代关系 |
|---|---|---|---|---|
| D001 | 2026-10-07 | 标签落在会话标题，先只做宿主半边 | 用户选定；同类实现 2/2 | 被 D009 叠加，未替换 |
| D002 | 2026-10-07 | 挂**原生** `session/created`，覆盖所有 fork 入口 | 与同类插件的唯一差异点 | 生效中 |
| D004 | 2026-10-07 | **只标注、不接管**：标题一旦不是继承形态就放过 | 避免与同类插件双重加前缀、避免覆盖手动命名 | 生效中 |
| D005 | 2026-10-07 | 零 import、零依赖、不注册工具 | 工作区纪律；绕开 junction 装载的解析限制 | 生效中 |
| D006 | 2026-10-07 | 写入走 `sessionTitle.rename`，冷会话退 `sessionController.rename` | `rename` 会 pin 标题；退路处理冷会话 | 生效中 |
| D008 | 2026-10-07 | 只处理装载之后的新 fork，不做启动扫描 | 避免给旧分叉重新贴标 | 生效中 |
| D009 | 2026-10-07 | **保留**标题前缀，另加客户端侧栏徽标（叠加不替换） | 用户追问"改名会不会抹掉来源"后选定方案 C | 生效中 |
| D011 | 2026-10-07 | 悬停段字色改用官方卡片的**固定色**（`#cfd3d6` / `#fff` / `#adb2b8`） | 官方悬停卡是深色菜单材质、字色写死在它的 CSS module 里；主题 token 在该作用域解析成浅色主题近黑值，与卡片背景同色 ⇒ 字隐形 | 替代 D009 里的 token 取色；A7/A8 断言防回归 |

## 隐私与发布

提交前检查完整暂存内容、实际署名、凭据、私人标识与原始会话；首次公开、新分支或发布标签时另检查拟发布历史和附件。

检查模块已复制到 `.privacy-tools/`（**Hook 未启用**）。实际命令与实际结果：

```powershell
pwsh -NoProfile -File .privacy-tools\Invoke-PrivacyCheck.ps1 -Repo . -Mode Staged -Policy .privacy-tools\privacy-policy.json
```

| 模式 | 2026-10-07 实测结果（历史改写后） |
|---|---|
| `Staged`（日常） | **0 阻断项** |
| `Index`（全快照） | **1 阻断项** —— 只剩 `.privacy-tools/Invoke-PrivacyCheck.ps1` 自身，是工具已知误报 |
| `History`（全部历史） | **6 阻断项** —— 本机绝对路径已 **0 处**；6 项全是工具的两类误报（自身 1 项 + 历史文档里 `home` 路径段命中「用户主目录」分支 5 项） |

### 已执行「泄露后的处理与验证」（2026-10-07）

- 定位（**处理当时**）：**已本地提交，未推送**（无远端、无标签、无 Fork/克隆）；泄露类别是**本机绝对路径**，不含凭据。
- 处理：全量 `git bundle` 备份 → 受控副本里 `git filter-branch` 脱敏 → 删 `refs/original` + `gc --prune=now` → `git fetch` 回收到原仓库 → 旧提交从本地对象库清除。
- 本地验证：新 HEAD 的 tree 与改写前**逐字节相同**；全部可达历史盘符路径 **0 处**；`npm test` 13/13、`npm run rm-test` 14/14、客户端声明预检 14/14 全通过；`git fsck` 无输出。
- **上传后核验**（2026-10-07 15:55，GitHub REST API + 未登录网页）：仓库为 **public**、默认分支 `main`，远端 HEAD 与本地 HEAD **一致**，远端 8 个提交**全部是改写后的编号**；改写前的旧 HEAD 在 GitHub 上 **API 422 / 网页 404**，远端无标签、无 Fork、无 Issue/PR。⇒ **本次泄露未公开**（推送发生在改写完成之后）。
- 记录：[.privacy-tools/VERIFICATION.md](.privacy-tools/VERIFICATION.md)（只记类别与结论）；完整旧编号与原始备份留在工作区内的**受控位置**，不入库。

**待核验 / 注意**：

- 受控备份 bundle 含改写前的本机路径，**不得**进入任何仓库或公开位置。
- 本仓库历史已改写：**不要**从旧备份 bundle 推送任何分支。
- 本机 `git` 无法直连 GitHub（受限令牌下 schannel 取不到 TLS 凭据），远端核验走 API；`git ls-remote` / `git fetch` 未执行，本地 `main` 也未设置上游。
- 图片像素、PDF 正文、Office 备注、压缩包、LFS 实际对象不在自动检查范围内（本仓库当前无此类附件）。

## 给 Agent 的启动语

> 请读 AGENTS.md、MAINTAINER.md、README.md 和 tasks.csv 中本次任务行，再检查相关实现。按已确定的用户场景完成一个小块并验证，更新已有任务记录，在对话中给出证据与未解决问题。若关键路径改变，说明依据和影响，提供一个便于作者检查的实际场景；作者视角由我理解后回写。

## 公开文档与双语维护

| 文件 | 面向谁、保存什么 |
|---|---|
| [README.zh-CN.md](README.zh-CN.md) / [README.md](README.md) | 读者与使用者：用途、可用能力、实际使用步骤、限制、获取帮助与许可 |
| 本文件 | 维护者：本轮目标、理解、决策、验收与公开前检查 |
| [AGENTS.md](AGENTS.md) | Agent 接手与执行规则；任务状态仍由 `tasks.csv` 保存 |

未提供 `CONTRIBUTING.md` / `CONTRIBUTING.zh-CN.md`：模板列了这一项，但本轮范围由用户选定为「README 双语化 + 隐私检查 + MAINTAINER + LICENSE」，**不含贡献指南**，因此先不建。仓库已公开且 Issue / PR 可用，需要时按模板补齐两版并互链。

- 公开入口回答读者怎样使用当前可获取的版本；本轮任务、作者疑点和内部检查过程保存在维护记录。
- 两版公开文档使用相同的事实字段：运行命令、路径、配置键、版本、接口与许可标识保持一致，代码标识（含产品字符串 `⤷ 来源：`）不翻译。
- 同一变更同时更新两个语言版本；暂未完成翻译时在两版入口注明缺项与适用版本。

### GitHub 仓库元数据（英文，按平台语言倾向维护）

| 字段 | 当前值（2026-10-07 设置并回读核对） |
|---|---|
| About（`description`） | `DSH (DeepSeek Harness) plugin for people who fork sessions: it labels each fork with the conversation it came from — a title prefix (⤷ 来源：) plus a sidebar badge that survives renaming. Zero dependencies; v0.1.2, MIT.` |
| Topics | `cordis`、`deepseek-harness`、`dsh`、`dsh-plugin`、`fork`、`session` |

- 改法：`gh api -X PATCH /repos/<owner>/<repo> --input <json>`（About）与 `gh api -X PUT /repos/<owner>/<repo>/topics --input <json>`（topics）。**用 UTF-8 JSON 文件而不是命令行参数** —— Windows 下把中文与破折号当参数传会走样。两者都需要能联网的凭据（本机由 `gh` 提供）。
- About 按母库规则写英文：一到两句讲清**做什么、给谁用、当前状态**，不留占位；版本号与许可标识必须与 README 一致，改动时同步改这里。
- Topics 的选法有依据、不自造：`deepseek-harness` / `dsh` / `dsh-plugin` 是生态通用三件套（官方仓库 `deepseek-ai/deepseek-harness` 与精选列表 `awesome-dsh-plugin` 都在用），`cordis` 取自官方仓库（DSH 的插件框架，本插件确实是 Cordis 插件），`session` / `fork` 取自同类插件 `vlln/dsh-autofork`。

### 公开前核对

1. 占位字段：README 两版均无 `{{…}}` 占位；快速开始的分叉→改名两步已在**真实 GUI** 上由用户目视确认（2026-10-07）。
2. 公开状态只写已核查的能力与适用边界：验证表里的检查均已实际执行，结果见 [.verify/REPORT.md](.verify/REPORT.md)。
3. 链接目标：README 只链接仓库内存在的文件与他人公开项目；两版互链已在顶部。
4. 许可：MIT，见 [LICENSE](LICENSE)（Copyright (c) 2026 WindFromKadath）；无捆绑第三方代码或素材。
5. 按拟公开版本检查暂存内容、历史、身份信息、附件与链接目标：**已执行** —— 当前版本 `Index` 模式只剩工具自身 1 项误报；历史已按「泄露后的处理与验证」改写，并做了上传后核验，结果见 [.privacy-tools/VERIFICATION.md](.privacy-tools/VERIFICATION.md)。

已核对的公开版本：2026-10-07 15:55 经 GitHub API 核验，远端 `main` 与本地 HEAD **一致**（8 个提交，全部为改写后的编号）；双语核对：2026-10-07 由协作 Agent 完成（事实字段逐条对齐，命令与路径未翻译）；隐私与许可核对：`.privacy-tools/README.md` 记录实际命令与结果，`.privacy-tools/VERIFICATION.md` 记录历史改写与上传后核验。