dsh-codespace-workspace 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,794 @@
-# Temporary Holding Version
+# dsh-codespace-workspace
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 **GitHub Codespace 直接当作一个 DSH 工作区**使用。本地 DSH 连接云端
+Codespace，Agent 在 Codespace 里读写文件、执行命令。
+
+这不是一个通用的 SSH 远程连接插件：Codespace 就是工作区本身。它不往 DSH 的
+SSH 主机列表里塞任何东西，因此不会和其他云工作区插件冲突。
+
+```
+┌─────────────── 本地 DSH ───────────────┐        ┌────── GitHub Codespace ──────┐
+│  侧边栏工作区行（云朵图标）              │        │                              │
+│    ▶️ / ⏸️ / 🕐  ← 启停 + 自动暂停倒计时 │  SSH   │  /workspaces/<repo>          │
+│                                        │ ─────► │    read / write / edit       │
+│  Agent 会话（cwd = 占位目录）           │        │    glob / grep / bash        │
+└────────────────────────────────────────┘        └──────────────────────────────┘
+```
+
+## 功能
+
+### 设置页：Codespace
+
+在 DSH 设置里新增一栏 **Codespace**：
+
+| 设置项 | 说明 |
+|---|---|
+| GitHub 用户名 | 用于校验与展示；留空则从 token 读取登录名 |
+| 默认分支 | 新建 Codespace 时使用，默认 `main` |
+| 自动暂停等待时间（分钟） | 一轮对话结束后开始倒计时，默认 30 |
+| SSH 密钥（可选） | 仅保存路径；值永不回显，只显示「已设置 / 未设置」 |
+| 始终显示云端工作区按钮 | 开关，默认关；开启后按钮不再跟随 hover 隐藏 |
+| 自动初始化空仓库 | 开关，默认开；空仓库先提交一个 README 再建 Codespace |
+| README 初始内容 | 可选；留空则创建空 README |
+
+设置通过 DSH 标准设置存储（`Config` + `.volatile()` + settings 服务）持久化，
+写在 profile 的 `cordis.patch.yml` 里，不占用 `localStorage`，升级不丢。
+
+### 工作区列表
+
+- 新建云端工作区的按钮放在**工作区分组标题栏的图标行里**，与 DSH 原有的图标
+  同地位，紧挨在「添加工作区」的**左边**——不是另做一个独立控件。
+- 云端工作区**沿用原工作区的文件夹图标位置**，把那里的文件夹字形换成**云朵**：位置、
+  尺寸、颜色，以及悬停时「让位给展开箭头」的行为都和原来一致，行首始终只有一个图标。
+  云朵固定不变，不随 Codespace 状态变化。
+- 操作按钮位于**倒数第三个**——在三个点菜单和新建对话按钮之前。
+- 显示逻辑跟随宿主默认行为：不 hover 时隐藏；打开「始终显示」后常显。
+- **正在使用的工作区，云朵和宿主的文件夹图标一样变蓝**：宿主给「拥有当前会话」的那个工作区
+  的图标槽加 `folderActive`，云朵就排在那个槽里，**继承**它的颜色，不自己定颜色。
+- 按钮状态（四个图标都是**照着宿主图标手绘的 SVG**，不是 emoji；转圈用的是宿主自己的
+  `IconLoadingOutline` 圆弧，不是 CSS 方块环）：
+
+| 状态 | 图标 | 悬停提示 | 点击 |
+|---|---|---|---|
+| 已停止 | 播放 | 启动 Codespace | 启动 |
+| 运行中 | 暂停 | 暂停 Codespace | 暂停 |
+| 倒计时中 | 闹钟 | 还剩 X 分钟自动暂停 | 取消倒计时 |
+| 启动/暂停中 | 转圈 | 正在切换状态… | 不可点 |
+
+**转圈只表示「状态正在变化」**，不表示「Agent 正在干活」——后者会让按钮整个回合都在转。
+
+**双击时钟图标 = 立即暂停。**
+
+工作区行的标题用**仓库短名**（`owner/name` 里的 `name`）——Codespace 自己的名字是机器生成的
+（`psychic-goggles-7v9974jwpwr5fpqxq`），看不出是哪个项目。标题装不下的两件事放在 hover
+卡片里：那一行「工作区位置」显示 **`owner/name · Codespace 名字`**。
+
+**在 Codespace 会话里发消息时，会先等 Codespace 跑起来**：如果它已经自动暂停（或还在启动），
+这一轮会等到 `Available` 才真正发给模型，而不是让每个工具调用都报连接错误。
+
+### 新建云端工作区
+
+只有一个窗口，分步显示，不弹一堆窗：
+
+1. 拉取 GitHub 仓库列表，选择仓库
+2. 检查该仓库的 Codespace：多个 → 选择；一个 → 直接用；没有 → 创建
+3. 创建前检查 prebuild，**三态**而非二态：
+   - 有 → 「该仓库已配置预构建。」
+   - 明确没有 → 「未配置预构建，创建可能较慢」，给出 `取消` / `直接创建`
+   - **读不出来** → 「无法确认预构建状态，创建可能需要 1–3 分钟」，不给按钮
+     （没有可决定的事）。这一态是刻意保留的：把插件自己读取失败说成「你仓库没配
+     预构建」，是在陈述一件从未被证实的事实。
+4. 空仓库 → 自动提交一个空 README，然后继续创建
+5. 机器规格可选，默认最小
+6. 启动失败 → 窗口内报错，可重试
+
+### 生命周期
+
+- **DSH 启动时**：不自动启动任何 Codespace。检查上次遗留的运行中 Codespace 并
+  提示用户（带「停止」按钮），但不自动停。
+- **退出 DSH 时**：尝试自动关闭所有本插件管理的 Codespace。
+- **自动暂停**：一轮对话结束后开始倒计时；倒计时期间用户发新消息 → 取消倒计时，
+  等 Agent 干完活重新计时；点时钟 → 取消；双击时钟 → 立即暂停。
+- **发消息前保证机器在跑**：挂 `agent/pre-step`（Agent 循环在向模型要 step 之前会
+  **await** 这个 waterfall），发现 Codespace 没运行就先启动、等它变成 `Available`
+  再放行。启动失败或超时不会把这一轮卡死——照常放行，让模型看到真实的连接错误。
+  等待期间你点「停止」/发送中断会立刻结束等待（转发的是这一轮的 abort signal）。
+
+### Git
+
+Agent 拥有完整的 `git` 命令执行能力。**插件不干预 Git 操作，不封装 push 逻辑。**
+只在创建会话时向系统提示词注入一条规则，告诉 Agent 这是云端 Codespace 工作区、
+改动完成后请 `git push` 回仓库——不需要每次提醒。
+
+### 多工作区
+
+每个云端工作区独立控制自己的 Codespace 启停，互不干扰。
+
+### 删除 Codespace
+
+在三个点菜单里，与「删除工作区」**分开**。点击后弹确认框，确认后删除。
+
+## 前置条件
+
+| 依赖 | 必需 | 说明 |
+|---|---|---|
+| `git` | 是 | Agent 用它 push 回仓库 |
+| `ssh` | 是 | 连接 Codespace 的数据通道 |
+| `gh`（GitHub CLI） | 推荐 | 用于 `gh codespace ssh`；**未安装时插件仍可用**，改用你在设置里配置的 SSH 别名 |
+| GitHub token | 是 | 控制面（REST API）。取值顺序：设置 → `GITHUB_TOKEN` → `gh auth token` |
+
+> **本机现状**：`gh` 未安装，`git` 与 `ssh` 已安装。插件会在设置页明确显示这一
+> 状态，并在缺少 `gh` 时回退到 SSH 别名，而不是直接失败。
+
+所需 GitHub 权限范围：`codespace`、`repo`。
+
+## 安装
+
+```powershell
+# 1. 装进当前 profile（只改写 profile 的 package.json dependencies 与 lockfile）
+dsh plugin --profile desktop add dsh-codespace-workspace
+
+# 2. 把包名登记进 dsh.profile.bundles，否则不会被挂载
+#    编辑 %USERPROFILE%\.dsh\profiles\desktop\package.json
+#    在 dsh.profile.bundles 数组里加入 "dsh-codespace-workspace"
+
+# 3. 重启 DSH（插件文件改动不会热生效）
+```
+
+也可以从本地克隆装（改代码时用这个）：
+
+```powershell
+git clone <this-repo> dsh-codespace-workspace
+dsh plugin --profile desktop add "link:<绝对路径>\dsh-codespace-workspace"
+```
+
+`dsh plugin add` 只改 `dependencies` 与 `pnpm-lock.yaml`，**不会**登记
+`dsh.profile.bundles`，第 3 步必须手工做。它会报一条 peer dependency 警告
+（`@deepseek-ai/cordis`、`@deepseek-ai/schemastery` 由宿主提供），可以忽略。
+
+装完可以确认插件已被解析并导入。注意 `desktop` profile 由 Electron 应用独占管理，
+CLI 对它只允许 `dsh plugin`，跑 `--dump-config-schema` 会报
+`profile "desktop" is managed exclusively by the Electron application`。所以要用一个
+临时 profile 来验证（下面的 `cscheck` 只是举例，验证完删掉即可）：
+
+```powershell
+# 建一个只含 dsh-base 的临时 profile
+dsh plugin --profile cscheck add "@deepseek-ai/dsh-base@0.2.0-rc.2"
+dsh plugin --profile cscheck add "link:<绝对路径>\dsh-codespace-workspace"
+# 手工把 "dsh-codespace-workspace" 加进该 profile 的 dsh.profile.bundles
+# 然后 dump：它会真的 import() 每个插件的 main，并用其 Config 生成 JSON Schema
+dsh --profile cscheck --dump-config-schema | Select-String dsh-codespace-workspace
+```
+
+输出里应出现 `"const":"dsh-codespace-workspace"` 指向一个 `config<N>` 定义，
+该定义包含全部 8 个设置字段、正确的默认值、`"volatile":true`，以及
+`githubToken` 上的 `"role":"secret"`。这证明模块能加载、`Config` 合法。
+
+确认无误后重启 DSH，设置页就会出现 **Codespace**。
+
+## 架构
+
+```
+lib/
+  shared.js              Host/Client 之间的冻结契约（动作名、状态映射、脱敏）
+  index.js               Host 入口：apply() / Config / inject / 装配
+  host/
+    github.js            GitHub REST 客户端 + token 解析
+    gh.js                gh CLI 探测与调用（缺失时优雅降级）
+    codespaces.js        生命周期、机器规格、prebuild、空仓库、自动暂停计时器
+    transport.js         远程执行与文件读写（base64，无字符串插值）
+    remote-tools.js      为 Codespace 会话注册远程工具（agent.ctx 作用域）
+    session.js           agent/created、提示词注入、倒计时、退出停止
+    routes.js            RPC 路由
+  client.js              浏览器半边：设置页 + DOM 增强（标题栏按钮 / 行 / 菜单）+ 多步窗口
+locale/{en,zh}.json      文案
+test/
+  check.mjs              Node 侧自检（不需要浏览器、token、gh）
+  shutdown.mjs           「退出即停」的可靠性自检
+  e2e.mjs                载体端到端：真实 webserver + 真实 connection + 真实签名 cookie
+  serve.mjs              浏览器自检的静态服务器
+  browser/               浏览器自检：index.html + harness.js + react-lite.js
+```
+
+### 关键设计决策
+
+1. **占位目录**：Codespace 工作区在 DSH 自己的 registry 里登记为一个真实存在的
+   本地目录 `<DSH_HOME>/codespaces/<name>/`（`dsh-workspace` 要求路径存在且可
+   `realpath`）。会话 `cwd` 就是这个路径，DSH 的工作区/会话机制原样工作。
+2. **按 cwd 路由，不替换全局服务**：任何会话只要 `cwd` 落在占位根目录下，就是
+   Codespace 会话。其余会话与其他插件完全不受影响。
+3. **按 Agent 注册工具**：在 `agent/created` 时，把远程实现注册到 `agent.ctx`，
+   用 `tools.restrict()` 屏蔽本地对应工具。这是 DSH 支持的 per-agent 扩展点。
+4. **一行提示词**：只在会话创建时注入一条规则，不做每轮提醒。
+5. **退出即停**：退出时停止所有本插件管理的 Codespace。挂点是 `ctx.effect` 的
+   cleanup —— `runProfile` 的 dispose 会 await 根 fiber 的 `fiber.dispose()`，而
+   cordis 会并发 await 每一个 effect disposer（已核对 `fiber.ts` 的 `_unload`）。
+   预算很紧：进程 5 秒后强退，崩溃路径只有 2 秒。因此 `stopAll()` 是幂等的、用
+   `Promise.allSettled` 并发发出、单个请求 3.5 秒超时、且**绝不 reject**（reject 的
+   disposer 会让 `runProfile` 抛 `AggregateError`）。没有停成功的名字写进
+   `pending-stop.json`，下次启动的“残留 Codespace”提示会一并列出。
+
+## 验证
+
+四套离线自检（不需要 token、`gh` 或真实 Codespace），加一套需要令牌的联网自检：
+
+```bash
+# Node 侧：包清单与打包白名单、Config 默认值、RPC 动作表与 HTTP 守卫、
+# 工作区命名、发消息前的就绪检查、shell 引用、文案一致性
+node test/check.mjs                # 181 项，全通过
+
+# 退出即停：对着真实 CodespaceManager 跑，只把 fetch 换成桩
+node test/shutdown.mjs             # 31 项，全通过
+
+# 载体端到端：起真实的 dsh-host-webserver + dsh-client-connection，
+# 用真实签名 cookie 走真实 HTTP
+node test/e2e.mjs                  # 全通过（找不到已安装的 Harness 时自动 SKIP）
+
+# 浏览器侧：在真实 DOM 里跑真实 bundle，对着宿主 markup/CSS 的忠实副本
+node test/serve.mjs                # 然后打开 http://127.0.0.1:19501/
+                                   # 217 项，全通过
+
+# 联网：用 gh 的令牌打真实 GitHub API（无令牌时自动 SKIP）
+node test/live.mjs
+```
+
+`test/live.mjs` 是唯一会碰网络的一套，它存在的理由很具体：离线套件看不见本机那个
+**TLS 拦截**故障——中间人根证书只在 Windows 系统信任库里，Node 的 `fetch` 只信自带
+CA 包，于是所有 GitHub API 调用都变成 `TypeError: fetch failed`，而 `gh` 走 Go 读系统
+库完全正常。这套测试先量出「直连能不能用」，再断言控制面**两条路都通**，这样回退路径
+真的被走到时才算数。
+
+`test/e2e.mjs` 是这套里最有价值的一个：它不驱动桩，而是从已安装的 Harness 里
+`import` **真实的** `dsh-host-webserver` 与 `dsh-client-connection`，注册真实的
+路由，然后对真实监听的端口发真实 HTTP。它证明的正是桩测不了的三件事：
+
+1. 路由能穿过 DSH 自己的 `/api` 前缀路由到达；
+2. **没有会话 cookie 的请求被 harness 拒掉（401）**——即路由没有遮住 fence 和鉴权；
+3. 用真实 launch-token 换来的**真实签名 cookie** 能打通，拿到 `{ok:true}`。
+
+它还**当场演示了影子风险**以证明自己有牙齿：故意在同路径注册一个 `webServer`
+exact 路由，匿名请求立刻从 401 变成 200（绕过了 fence）；撤掉它，401 回来。
+所以「匿名必须是 401」这句断言对载体是敏感的——这正是之前那版实现栽的地方。
+
+`test/shutdown.mjs` 覆盖的是「退出即停」这条最重要的可靠性要求——一个没停掉的
+Codespace 会按小时计费，而用户看不见也补不回来。它断言的是真正要紧的性质：
+
+- 每个受管 Codespace 都被要求停止，而且是**并发**发出（两个 300ms 的停止必须在
+  550ms 内跑完，串行会超）。
+- 请求失败、连接被拒、**API 收下连接但永不回复**这三种情况下，disposer 都**必须
+  resolve**。reject 的 disposer 会让 `runProfile` 抛 `AggregateError`——那就从
+  「有一个 Codespace 没停掉」变成「DSH 退不出去」，是更糟的失败模式。
+- 最坏情况仍在 5 秒进程预算之内，且不早于单请求的 3.5 秒预算。
+- 幂等：teardown 跑第二次不再发任何请求。
+- 没停成功的名字会写进 `pending-stop.json`，下次启动的残留提示还能兜住。
+- 没有 token 时不去发请求，而是把名字全部记成 pending。
+
+其中「API 永不回复」这一例用的是**真实 socket**（本地起一个只收不回的
+`http` server，把真实 `init`——含 signal——转给真实 `fetch`），不是桩。原因值得记：
+Node 里 `AbortSignal.timeout()` 的定时器是 **unref'd** 的，一个「返回永不 settle 的
+promise」的桩不持有任何 ref'd handle，进程会直接退出而不是触发超时——用桩测这一条
+会得到假结果。已单独核实：真实 socket 下 `api()` 在 1215ms 抛 `E_TIMEOUT`。
+
+浏览器侧覆盖的是 Node 里没法验证的部分：真实属性反射、`:hover` 驱动的 CSS、
+`MutationObserver` 合并、portal 到 `document.body` 的菜单。它实际抓到过两个 bug：
+
+- **时钟双击失效**：倒计时行上，第一次点击会立刻发出「取消倒计时」（这是刻意的，
+  因为那里双击没有别的含义），于是剩余时间归零；而 `dblclick` 的处理里原本用
+  「剩余时间 > 0」做守卫，结果第二次点击被静默丢弃——需求里的「双击时钟 = 立即暂停」
+  从来没生效过。守卫已改为判断**状态**而不是剩余时间。
+- **运行中单击不生效**：`beginClickWindow` 只清了计时器并重绘，从来没有真正发出
+  被延后的那个动作，所以运行中的行单击一次什么都不会发生。现在窗口关闭时会按
+  **当前**记录重新推导动作（轮询可能在这期间落地），并丢弃已经进入 busy 的记录。
+
+另外它抓到过一个真实的时序问题：`alwaysShowCloudButton` 原本只在设置页挂载时才
+读取，因此全新启动时行增强读到的是 `null`，开关实际上不生效。现在由行增强模块
+自己在拿到 owner claim 时读一次设置。
+
+### 真机（真实 GUI）上抓到的 bug
+
+下面这些都不是桩能测出来的，必须对着跑起来的 DSH 才暴露；而且第一个的成因是
+**我自己的测试把 bug 写进了断言里**，所以它一直是绿的。
+
+**一、`状态读取失败：Requests must be same-origin.`**
+
+设置页的「状态」卡片一直红着，`GitHub CLI (gh)` 卡在「检查中…」。原因是 RPC
+路由上那道**自己手写的** Host/Origin fence 要求请求必须带 `Origin`，而桌面外壳
+的载体**两者都不带**（`Origin` 和 Fetch-Metadata 都没有），于是每一发都被 403。
+Web GUI 反而正常，因为浏览器会发 `Origin`——这就是它看起来「只坏一半」的原因。
+
+修法不是放宽自己那套，而是**逐字对齐 harness 自己的 `isTrustedApiRequest`**：它
+的第一条就是 `if (origin === void 0) return true`。承重的检查是 **Host**，因为
+`Host` 是 DNS rebinding 唯一伪造不了的头；`Origin` 与 `Sec-Fetch-Site` 只是补充。
+另外 `isLoopbackHostname` 接受 `localhost`、`[::1]` 和**整个 127/8**，不只是
+`127.0.0.1`。
+
+对着跑着的宿主复现过（旧代码）：不带 `Origin` → 403，带上匹配的 `Origin` → 200。
+
+**二、我自己的路由遮住了 harness 的鉴权（安全相关）**
+
+修好 fence 之后顺手量了一下，发现更值得修的一处：路由原本注册成 `webServer` 的
+**exact** 路由，而 webserver 的 `match()` 是**先查 exact 表、再查前缀表**，所以它
+比 DSH 自己的 `/api` **前缀**路由先命中，直接把 `/api` 那条路整个遮掉了——而
+fence 和浏览器鉴权（cookie）都挂在 `/api` 那条路上。实测（旧代码）：
+
+```
+POST /api/dsh-codespace-workspace/rpc   （无 cookie，Origin 匹配）-> 200
+POST /api/no-such-plugin-xyz            （无 cookie，Origin 匹配）-> 401 unauthorized
+```
+
+第二行是 DSH 在拒绝未鉴权调用；第一行说明我们的 exact 路由绕过了它。
+
+正确做法是注册到 `connection.fetch`：DSH 自己的 `/api` 前缀路由会先 `admit(req)`
+（Host/Origin fence **加上** cookie 鉴权），再 `bridge()` 派发到插件注册的 Fetch
+路由。这样等于白拿 harness 的安全策略，浏览器和桌面外壳还都能用。exact 路由现在
+只作为「composition 里根本没有 `connection` 服务」时的兜底保留。
+
+两个细节值得记：
+
+- `connection` 不在本模块的 `inject` 里，直接读 `ready.connection` 会被 cordis
+  门禁拦下（`cannot get property ... without inject`）。要用 `ctx.get(name, false)`
+  ——cordis 文档里写明的「不经 inject 读取服务」的公开入口。
+- 服务加载顺序没有保证，所以载体选择**不能是一次性判断**。`ready.inject(['connection'], ...)`
+  是公开的触发点（已实测：服务晚到时它会触发，永不出现时保持沉默且不抛），
+  于是晚到的 `connection` 会把兜底路由换掉，而不是让进程一直停在较弱的载体上。
+
+**三、`仓库读取失败：cannot reach the GitHub API (TypeError)`**
+
+`gh` 装好、状态卡全绿之后，仓库列表依然读不出来。原因是**本机有 TLS 拦截**：中间人
+根证书只装在 Windows 系统信任库里，而 Node 的 `fetch` 只信**自带**的 CA 包，于是每次
+调用都失败——真正的成因藏在 `error.cause.code = UNABLE_TO_VERIFY_LEAF_SIGNATURE`，
+而旧代码只把 `error.name` 写进消息，于是用户看到的是一个毫无信息量的 `TypeError`。
+`gh` 用 Go 读系统库，同一个请求完全正常，这才造成「令牌来自 gh auth token 却调不通
+API」这种一半好的假象。
+
+修法是给控制面加一条**进程内**的回退：`tls.getCACertificates('system')` 取到系统信任库
+（本机 225 个证书），失败的那一发改走 `node:https` 请求并带上 `ca`，结果包成真的
+`Response`，所以下游的 `status`/`headers.get`/`text()` 全都不用改。**没有**用
+`tls.setDefaultCACertificates()`——那会让本插件偷偷放宽整个 host 进程的 TLS 信任，影响到
+别的插件；改动留在自己的传输层里。错误消息也改成报 `cause` 的 code，不再是 `TypeError`。
+
+另有 `NODE_OPTIONS=--use-system-ca` 可用（一次修好所有 Node 代码），但它要改环境变量并
+重启 DSH，所以只作为备选写在这里。
+
+**四、启动图标的样式和旁边的按钮不一样**
+
+需求里那句「样式要和其他的等价」原来没做到：我的按钮做成了 **16×16**、`radius-xs`、
+hover 只变色，而标题栏真正用的 `_9lTDKa_iconButton` 是 **28×28**、`radius-sm`、
+`--dsw-alias-label-secondary`，**hover 出现背景**而不是变色。图标本身也偏重：我写了
+`stroke-width="1.3"`（那是宿主 `Medium` 档）**并且写在 path 上**，而旁边的加号是
+`IconProjectAddOutlineRegular`，即 **1**，且按 primitives 的规范 `stroke-width` 应该放在
+`<svg>` 上。
+
+我一开始把 16×16 当成对的，是因为把 `Rows` 模块的 `hIlkoa_iconButton`（工作区行的按钮，
+确实是 16×16）错当成了标题栏的类——**浏览器 harness 的夹具也照抄了这个错值**，于是
+「launcher 和其它按钮一样大」这条断言一直是绿的。夹具已按真实 CSS 改正，并补上几何、
+圆角、颜色、hover 背景、描边宽度、rail 下字形 18px 的断言（浏览器侧从 107 项涨到 114 项）。
+云朵路径同时抽成一个常量，React 与 DOM 两条渲染路径共用，避免再次漂移。
+
+**五、图标会「有时候」跑到「新建工作区」按钮的右边**
+
+听起来像时序问题，其实是**确定性**的，只是触发条件不明显：**只有宿主自己的提示框
+正开着时才会发生**。原因是 DSH 的 `Tooltip` 在缺省配置下**不是 portal**（工作区标题栏
+没传 `portal`），所以气泡是以**兄弟节点**的形式渲染在**同一个 `headerActions` 容器**里
+的。我那段「把按钮插到最后一个子元素之前」的代码于是把按钮插到了气泡前面 —— 也就是
+「添加工作区」的右边。
+
+更糟的是它**不能自愈**：一旦插错，按钮的 `nextElementSibling` 正是那段代码要去找的
+东西，于是每次重扫都「看起来已经就位」。现在改成**记住锚点元素**、永远贴在它前面，
+而不是每轮重新猜「最后一个控件」；选锚点只看标签名（`BUTTON`），不看子节点顺序。
+浏览器套件补了两条会真的触发它的回归测试：宿主重渲染追加控件、以及一个开着的提示框
+气泡。另外我自己那个提示框**挂到 `document.body`**，从根上不再进这个容器。
+
+**六、`typeof` 一个未声明的名字让提示框静默失效**
+
+改提示框时踩了个安静的坑：`attachTooltip` 是模块作用域的函数，而 `doc` 是
+`installRowAugmentation` 的**局部变量**。我写了 `typeof doc === 'undefined'` 当守卫 ——
+但 `typeof` 对**未声明的标识符**返回 `'undefined'` **而不抛错**，于是这个函数每次都直接
+返回空操作：**没有报错、console 干净、看起来一切正常，只是提示框永远不出现**。
+
+现在改成在函数内部解析 `document`（那是真实全局）。这条也写进了记忆：客户端 bundle 里
+绝不要用 `typeof someUndeclaredName` 当守卫。
+
+**七、图标补上了右上角的加号，云朵保持原尺寸、只在交叉处断开**
+
+「新建云端工作区」的图标原本是一个单独的云朵，而它旁边宿主自己的按钮是
+`IconProjectAddOutlineRegular`（文件夹 + 加号）。现在这个图标是**云朵 + 加号**：加号
+**逐字抄**宿主那两条 path。
+
+第一版我把云朵**缩小**塞到左下角、给加号让位。那不对 —— 宿主的做法是主体**保持原尺寸**，
+只把轮廓在加号穿过的地方**断开**（它的文件夹就是满尺寸，右上角被切开让加号坐进去）。
+现在照这个做：云朵用**未修改的原 path**，套一个 SVG `<mask>`，mask 里先把 16×16 的白底
+铺满，再用 `stroke-width:2.6` 的**黑线**沿着加号两条笔画走一遍 —— 于是云朵轮廓在加号
+经过的那一段被擦掉，云朵本身的尺寸一点没变。
+
+几个具体取舍：
+
+- 用 mask 而不是手算断点。这条轮廓与加号实际有**两处**相交（竖笔切右瓣于 y≈6.706，横笔
+  的**描边带**还会蹭到大弧 x≈9.76 附近），手写子路径就得把这两组交点算准并永久跟着
+  path 同步；mask 直接表达「绕开加号」这个意图，不会漂移。
+- 裁切笔画用 `stroke-linecap="butt"`：圆头会多伸出半个带宽，在瓣的下端可能咬下一小块
+  孤立的碎线。
+- 每个图标一个独立 mask id（`maskUnits="userSpaceOnUse"`）。id 是全文档唯一的，两个
+  图标共用会让 `url(#id)` 解析到第一个，静默用错 mask。
+
+校验上补了一条**栅格化对照**：克隆同一个图标、只摘掉 cloud path 上的 `mask` 属性，
+两张都画到 canvas 上逐像素比对 —— 差值就是被 mask 擦掉的那部分墨。这一点很重要，因为
+**结构断言证明不了 mask 真的擦掉了东西**：mask 颜色写错、`maskUnits` 漏了、id 撞了，
+都照样渲染成一朵完整的云。我前两版采样框写法都不稳（按「列」判空会被弧线在别的高度上
+的墨抵消；按固定矩形采样则会被抗锯齿边缘的零星像素和加号自身的墨干扰），最后换成这种
+不依赖几何假设的做法。
+
+**八、hover 提示框换成 DSH 那种**
+
+原来用的是原生 `title`，画出来是操作系统的气泡，和旁边宿主控件的完全不是一回事。现在
+照抄宿主 Tooltip 的**渲染结果**：`position:fixed`、真实的 tooltip 设计令牌、
+`role="tooltip"`、500ms 悬停延迟（宿主 `delayMs: 500`），并挂在 `document.body` 上。
+CSS 全部只引用 `--dsw-alias-tooltip-bg` / `--dsw-static-neutral-bluish-00` 这些主题
+变量，不硬编码任何颜色值。
+
+**九、预构建提示原本是二态，把「读不出来」说成了「你没配」**
+
+用户报「仓库明明配了预构建，却仍提示未配置」。查下来那一次**插件是对的** —— 仓库当时
+确实没配好。但顺着这条线查，发现了一个真的缺陷，位置和我一开始猜的不一样。
+
+先纠正我自己一个错判：我一度怀疑 `prebuild_availability` 对个人账号根本不填、导致永远
+误报。**实测推翻了它** —— 我扫了 15 个仓库共 23 个机型行（含 `microsoft/vscode`、
+`python/cpython` 这类确实配了预构建的）：
+
+```
+null     x23
+"ready"  x3      ← 只出现过这两种值
+```
+
+**从来没有 `"none"`，也没有 `"in_progress"`**。所以「字段可读但为 `null`」**确实就是
+「没有预构建」**，插件的 `false` 判断是站得住的、不需要改。
+
+真正的缺陷在**失败路径**：客户端原来写的是
+
+```js
+setPrebuild(data.hasPrebuild === true ? true : false)   // null 被压成 false
+.catch(() => setPrebuild(false))                        // 失败也被压成 false
+```
+
+于是**只要读取失败，就显示「未配置预构建」** —— 那是把插件自己的故障当成你仓库的事实
+来陈述。现在 `hasPrebuild` 的 `true | false | null` **三态一路传到 UI**，`null` 单独
+渲染成「无法确认预构建状态，创建可能需要 1–3 分钟」，而且**不给按钮**（没有可决定的事，
+给了反而让人以为需要决策）。
+
+顺带查出并修掉两个**既有 bug**：
+
+- **机器步会直接崩溃**。我删掉 `needsNotice` 时漏了「下一步」按钮的 `disabled` 还在引用
+  它 —— 一进机器步就 `ReferenceError`。这是浏览器套件当场抓到的。
+- **确认后反而说「已配置预构建」**。点过「直接创建」之后，`prebuildAcknowledged` 会让
+  渲染落到「该仓库已配置预构建。」那一支 —— 恰好说了与刚刚相反的话。现在确认后不再显示
+  任何提示，而不是显示一句假的。
+
+浏览器套件 136 → **147 项**（后续又涨到 217，见下文「十一」「十三」），其中 8 项专测这三态（含
+「`null` 绝不能说成未配置」和「确认后绝不能说成已配置」两条否定断言）。
+
+**十、云端会话里本地工具根本没让位 —— 提示词说远程，手上还是本地**
+
+用户报「扫描工作区时环境与流程不一致」。顺着这条线查，抓到了这个插件**最核心那条
+承诺**上的一个真缺陷：`installRemoteTools` 从未真正执行过。
+
+成因是开头这三行：
+
+```js
+const tools = agentCtx?.tools;
+if (tools === undefined) return () => {};   // 静默放弃
+```
+
+`agent/created` 那一刻的 `agent.ctx` 是**作用域 ctx**，cordis 对没有写进 `inject` 的
+服务本应门禁报错（`cannot get property "x" without inject`）——**但这里偏偏不报**。
+`ReflectService.handler.get` 的最后三行是（已核对 `@deepseek-ai/cordis` `lib/index.js:680`）：
+
+```js
+if (!ctx.fiber.runtime) return ctx.reflect.get(prop, false);   // 退化成「不需要 inject」的读法
+```
+
+agent 作用域 ctx **没有运行中的 fiber**，于是这次读取降级成 `undefined` 而不是抛错。
+于是整个函数变成空操作：**没有报错、console 干净、远程工具一个没注册、本地
+`read`/`write`/`edit`/`bash` 全部照旧可用**；而 `session.js` 在同一时刻已经把
+「你这个会话操作的是云端 Codespace」写进了系统提示词。两边就是这么对不上的。
+
+DSH 自己的写法在 `dsh-file-reference-local` 里给得很清楚
+（`lib/index.js:342`）：`agent.ctx.inject(["systemPrompt","tools"], (scope) => …)`。
+**等工具服务就绪再安装**是唯一正确的做法，现在也照这个改：
+
+```js
+fiber = agentCtx.inject(['tools'], (scope) => {
+  const tools = scope.tools            // ← 只能从 scope 拿，不能从 agentCtx 拿
+  …
+})
+```
+
+关键细节是服务要**从 `inject` 回调的 `scope` 参数上取**：只有 `inject` 新建的那个
+fiber 的 store 里才有 `tools`，`agentCtx` 上永远没有。收尾用 `fiber.dispose()`。
+
+顺带澄清一处容易混的地方：上文「二」里 `ctx.get(name, false)` 那个「不经 `inject`
+读服务」的口子，解决的是**「服务可选、要探测在不在」**的问题；而这里的问题是
+**作用域** —— 注册远程工具要的是 agent 作用域里的那个 `tools` 实例，只有 `inject`
+新建的那个 fiber 的 store 里有它。我没有去核实 `get` 能不能从 agent ctx 上摸到同一个
+实例，也没必要：`inject` 是 DSH 自己的做法，抄它就对了。
+
+`check` 111 → **122 项**，新增的 11 项专测这条接线，覆盖三种情形：工具已就绪、工具
+**晚到**、以及根本没有 `agent.ctx`。改完后我把源码退回旧写法反向验证了一次，两项立刻
+变红：
+
+```
+FAIL when tools arrives, the remote surface is installed -- got "", want "read,write,edit,glob,grep,bash"
+FAIL   -> and the local tools are hidden
+```
+
+这正是它值得存在的理由：一个「静默空操作」的 bug，只有故意让它失败一次，才能证明测试
+真的看得见它。
+
+**十一、行首多了一个图标，状态图标用的是 emoji**
+
+两处都是「看起来能用，但和旁边的东西不是一类」的问题。
+
+**（一）云朵被加在文件夹**旁边**，而不是**替换**它**
+
+需求写的是「替换原来工作区的文件夹图标，样式等相同」，我做成了「在行首再插一个云朵」，
+于是行首出现两个图标。
+
+根因不是手滑，是**读错了宿主的 CSS**。`Rows` 模块里三条相关规则是：
+
+```css
+.hIlkoa_projectRow .hIlkoa_chevron{display:none}            /* 平时：箭头藏起来 */
+.hIlkoa_projectRow:hover .hIlkoa_chevron{display:inline-flex}
+.hIlkoa_projectRow:hover .hIlkoa_folder{display:none}       /* 悬停时才轮到文件夹让位 */
+```
+
+我当时只看到最后一条，就把它当成了「文件夹在两种状态下都不可见」，于是得出「没有可见的
+文件夹可替换」的结论，选择另加一个。**实际上文件夹在平时是看得见的**，它是行的第一个
+子元素，悬停时才让位给展开箭头。
+
+更糟的是，这个错误结论被**夹具固化**了：`test/browser/index.html` 里写着一条
+
+```css
+.hIlkoa_folder { display: none; }      /* ← 宿主里根本没有这条规则 */
+```
+
+于是「文件夹本来就看不见」在测试里成了前提，所有断言都是绿的。这和上文「四」里把
+16×16 当成 28×28 是同一类失误：**夹具抄了一个错的模型，测试就成了 bug 的帮凶**。
+
+现在改成把云朵塞进宿主那个 `span.slot.folder`，并用内联 `display:none` 藏掉宿主自己的
+svg（原 `style` 值连同标记一起存下，撤销时还原）。好处是位置、尺寸、颜色、以及「悬停让位
+给箭头」全部**从宿主 CSS 继承**，我一行都不用复刻。夹具里的伪规则已按真实 CSS 修正。
+
+补充一个实现细节：文件夹在展开/折叠时会换 svg（`IconFolderClose` ↔ `IconFolderOpen`），
+React 会把节点换掉，所以每次 `sync()` 都要重新藏一遍「现在这个」；循环里要跳过我自己那个
+节点——它也是子元素，第一版没跳过，第二次 `sync()` 就会把云朵自己藏起来。
+
+**（二）状态图标是 emoji**
+
+四个状态原本用 `⏸️`/`🕐`/`⚠️`/`▶️`。问题是 emoji 是**平台字体的彩色字形**，有自己的
+光学尺寸和粗细，它和旁边两个控件（`Menu` 的三点、`IconNewChatOutline` 的新建对话）——都是
+16px、1px `currentColor` 描边、跟随主题色的 `Icon*OutlineRegular`——放在一起，就是一个
+更重、全彩、且每个系统渲染都不同的方块。它连主题色都不跟随。
+
+现在四个图标都**照抄宿主自己的 artwork**（path 逐字复制，只挑用哪个字形）：
+
+| 状态 | 抄自 |
+|---|---|
+| 暂停/停止 | `IconPauseOutlineRegular` |
+| 倒计时 | `IconAlarmClockOutlineRegular` |
+| 异常 | `IconWarningTriangleOutlineRegular` |
+| 启动 | `IconPlayOutlineRegular` |
+
+抽了一个 `iconNode(spec)` 承载公共规范（16px 盒子、`Regular` 权重 = 1 **写在 `<svg>` 上**、
+`fill="none"` + `stroke="currentColor"`），但每个字形保留**它自己的** `viewBox` 和线帽设置
+——闹钟就是画在 **17×17** 网格上的，warning 三角形要用圆角线帽，这些都不能被"统一"掉。
+
+顺带把**多步窗口右上角的关闭按钮**也一起改了：那里的 `✕` 是同一类问题——用文本字符
+当图标。现在换成宿主自己的 `IconCloseOutlineRegular`（两条对角线，逐字照抄）。全库扫过
+一遍，`lib/client.js` 里已经**没有任何 emoji 当图标**，只剩两条注释在举例说明旧实现。
+
+浏览器套件 147 → **201 项**。新增的不只是数数，而是**能抓到这两类错误**的断言：
+- 云朵必须在 folder 槽**里面**，且 folder 槽仍是行首第一个子元素；
+- 宿主的 svg 真的 `display:none`，云朵真的可见；
+- **静止状态下整个行只有 1 个图标可见**——这条否定了「加一个在旁边」；
+- 承载云朵的 span 正是宿主 `:hover ._folder{display:none}` 规则所命中的那个（悬停行为等价）；
+- 每个字形逐条比对 `viewBox` / `stroke-width` 在 svg 上 / 每个 path 都是 `currentColor`
+  且**都不带** `stroke-width`，外加一条「glyph 文本里不得含 emoji 码点」；
+- 关闭按钮是 svg 而不是文本，artwork 与 `IconCloseOutlineRegular` 逐字一致，且整个窗口
+  标题区**不得出现任何 emoji 码点**。
+
+两类错误都反向验证过牙齿。把「替换」退回「在行首另加一个」，**6 项变红**，其中最关键的是
+
+```
+FAIL exactly one glyph is visible in the resting row — got 2, want 1
+```
+
+把关闭按钮退回 `'✕'`，**5 项变红**，最后一条正是那条 emoji 扫描。
+
+**十二、`icon.svg` 没打进安装包，以及工作区名是一串乱码**
+
+**（一）`Plugin metadata ... ENOENT ... icon.svg`**
+
+`package.json` 里有 `"icon": "./icon.svg"`，仓库里也**确实有**这个文件（第一个提交就在），
+但 `files` 白名单里**漏了它**。`files` 是 npm/pnpm 的打包白名单，而这个 profile 是从 GitHub
+tarball 装的（`github:Ckarefulon/dsh-codespace-workspace`）—— 打包时按白名单过滤，`icon.svg`
+就被丢掉了。DSH 读插件元信息时按 `icon` 字段去找它，`lstat` 失败。
+
+关键在于**仓库看起来是好的，只有打包后的副本是坏的**：本地 `git status` 干净、文件就在
+根目录，所以怎么读源码都发现不了。这也是为什么现在加了一条自检：把 `main`、`icon`、
+每个 `exports` 目标、以及 `dsh.bundle.patch` 都拿去和 `files` 白名单比对，缺一个就红。
+`package.json` 本身豁免（npm 无论如何都会打它）。
+
+**（二）工作区名是 `psychic-goggles-7v9974jwpwr5fpqxq`**
+
+那是 Codespace 自己的名字，GitHub 机器生成的，看不出是哪个项目。现在行标题取**仓库短名**
+（`owner/name` 里的 `name`），标题装不下的两件事放进 hover 卡片那一行：
+**`owner/name · Codespace 名字`**。
+
+三处要一起改，否则会出现「新行对、老行还是乱码」或者「有 locale 服务时对、没有时显示原始
+key」：
+
+- `titleForCodespace()`（host 侧）决定新行的标题；
+- `listWorkspaces()` 里加了一步**回填**，把已登记记录改成新标题 —— DSH 的 registry 会
+  **保留已存在记录的标题**，不回填的话你现有的那一行永远还是旧名字；
+- 客户端 `hoverLocationOf()` 拼 hover 那行。
+
+这里还踩到一个自己造的坑：`lib/client.js` 里**另有一份内联的 zh/en 字典**（没有 `locale`
+服务时用它，浏览器 harness 就是这种情况）。我只改了 `locale/*.json`，于是浏览器套件里那行
+直接显示成了字面量 `row.hoverRepo`。原来的 locale 自检只比对「两个 JSON 文件之间」和
+「JSON 与 `t()` 调用之间」，**从没比对过内联字典**——现在补上了，两边键集合必须一致
+（`nav` 豁免，那是宿主读的）。
+
+`check` 122 → **147 项**（含 10 项 `titleForCodespace`、11 项打包白名单、2 项内联字典），
+浏览器套件 201 → **203 项**。两处都反向验证过牙齿：把 `icon.svg` 从白名单里删掉 → 1 项变红；
+把 hover 那行退回只显示标签 → 1 项变红（`got "my-box", want "Ckarefulon/app.ckarefulon.main · my-box"`）。
+
+**十三、云朵不变蓝、转圈停不下来、转圈是个方块，以及发消息不等机器**
+
+四处都是「照理说应该很明显」的问题，四处的原因各不相同。
+
+**（一）正在使用的工作区里，云朵不变蓝**
+
+宿主是这样标记「当前会话所在的工作区」的：给那一行的**文件夹图标槽**加一个
+`folderActive` 类，规则是 `.…_folderActive{color:var(--dsw-alias-state-business-primary)}`
+—— 也就是变蓝。云朵本来就排在那同一个 span 里、`stroke="currentColor"`，看起来应该自动继承。
+
+问题是**我自己给云朵的容器写了一行 `color: var(--dsw-alias-label-secondary)`**。继承是继承，
+但**显式声明会盖掉继承值**，于是云朵永远是灰的。删掉那行就好——位置、尺寸、颜色、悬停让位
+全都该由宿主的 CSS 说了算。
+
+这条还牵出一个**夹具的老毛病**（这是第三次了，前两次是 16×16 当 28×28、`:hover` 当无条件）：
+夹具里 `.hIlkoa_slot`（设 `label-tertiary`）**排在** `.hIlkoa_folderActive` **后面**，
+而真实宿主里是反过来的。两个都是单类选择器，同优先级，所以**后写的赢** —— 夹具里的
+`folderActive` 根本不起作用，颜色测试一开始是红的。夹具的规则顺序已按宿主改正，并写了注释。
+
+**（二）「正在切换状态…」能转一整个回合**
+
+`isBusy()` 里有一行 `if (record.busy === true) return true`。而 `record.busy` 是
+**host 在 `user/message` 时置位、在 `turn/end` 时清除**的 —— 它的意思是「Agent 正在这个
+工作区里干活」，可以持续好几分钟。把它接进「该不该转圈」里，按钮就会在整个回合里转，还
+配着「正在切换状态…」这句错误的话，而 GitHub 那边的状态其实很明确。现在 `isBusy` 只认两件事：
+**我们自己的 RPC 在飞**，或者 **GitHub 说它确实在过渡态**（`Provisioning`/`Starting`/
+`ShuttingDown`…）。`record.busy` 保留在契约里，只是不再驱动这个按钮。
+
+**（三）转圈图标是个方块**
+
+原来是一个 CSS 环：`border:2px solid; border-top-color:transparent; border-radius:50%`。
+但宿主自己的加载指示器是 **`IconLoadingOutlineRegular`** —— 一段圆圆弧，配一个纯旋转动画
+（在 DSH 自己的 bundle 里核对过）。现在照抄它，于是转圈和那四个状态图标、以及旁边宿主的
+控件是同一套语言（16px、`currentColor`、1px 描边）。顺带补了 `prefers-reduced-motion`。
+
+**（四）发消息时没有等 Codespace 起来**
+
+Codespace 自动暂停之后，直接在会话里发消息，每个远程工具调用都会撞上连接错误。现在挂
+**`agent/pre-step`**：Agent 循环在向模型要 step 之前会 **await** 这个 waterfall
+（`dsh-agent-loop/lib/index.js` ≈L911），所以在这里等是真的在推迟这一轮，而不是和它赛跑。
+DSH 自己的 `archived-session-gate` 用的是同一个钩子 —— 但它是**拦住**这一轮；这里要的是
+**等**，所以拿到结果后照常 `next()`。
+
+几个克制的设计：**本地会话完全不碰**（cwd 判断在最前面）；`ensureRunning` 永不抛错，失败就
+`{ok:false, reason}` 然后照常放行（否则用户会看到一轮莫名其妙地什么都没发生，而不是一个
+明确的连接错误）；等待受这一轮的 abort signal 约束，用户中断立刻结束；成功状态记 20 秒，
+所以一个回合最多查一次 GitHub，而不是每一步都查。
+
+`check` 147 → **181 项**（33 项新增：`ensureRunning` 的各种路径 + `agent/pre-step` 网关的
+行为），浏览器套件 203 → **217 项**。三处都反向验证过牙齿：不启动机器 + 把过渡态当成就绪
+→ 6 项变红；给云朵加回颜色 + 让 `busy` 重新驱动转圈 → 8 项变红。
+
+## 已知限制
+
+- **工作区分组标题栏的图标行、以及工作区行，都没有官方插槽**。DSH 把「添加工作区」
+  按钮和 `ProjectRowItem` 的操作按钮、文件夹图标全部写死，因此以下四处通过 DOM 增强
+  实现（与 `dsh-pet` 处理设置导航图标同一手法）：标题栏里的新建按钮、行首云朵、
+  行内启停按钮、hover 文案（外加菜单里的「删除 Codespace…」）。做法是全部打上
+  `data-dsh-codespace-*` 标记、一个合并的 `MutationObserver`、dispose 时完整撤销，
+  并且**不删除任何 React 拥有的节点**：行首的云朵是把自己塞进宿主那个文件夹
+  `span.slot` 里，再把宿主自己的 svg 用内联 `display:none` 藏起来（连同原 `style`
+  一起登记，撤销时还原）。这样位置、尺寸、颜色和悬停让位全都从宿主的 CSS 继承，
+  不需要我自己复刻。宿主改版可能影响它。已核对：客户端运行时的
+  插槽目录共 90 个，其中有 `sidebar.workspaces.session.menu.item`，但**没有**工作区行
+  的菜单插槽，也没有标题栏图标行的插槽；`sidebar.footer.action` 是真实存在的插槽，
+  但它把控件放在侧边栏底部，不符合「与原有三个图标同地位、紧挨添加工作区左侧」的要求。
+  标题栏的 `_sectionHeader` / `_headerActions` 两个类名后缀经核对为
+  `dsh-client-ui-workspace` 独有，不会误匹配；行首文件夹槽位按 `_folder` 后缀匹配，
+  并限定在 `span[class*="_slot"]` 上，避免误伤同模块的 `_folderActive`。
+- 标题栏图标行是 `justify-content:flex-end` + `max-width:60px`，而标题栏的控件是
+  **28×28**（`_9lTDKa_iconButton`），所以 60px 正好放**两个**（28+4+28）。加进第三个
+  控件需要放宽容器宽度，放宽规则带了 `:not([class*="_headerActionsHidden"])`，以免盖掉
+  宿主自己在展开搜索框时的收起行为。**注意别把 `Rows` 模块的 `hIlkoa_iconButton`
+  （16×16，工作区行的按钮）当成标题栏的类**——两者同后缀不同模块，混淆过一次，见上文
+  「四」。另外「添加工作区」按钮只在目录流插槽被占用时才渲染，所以插入位置是「最后一个
+  子元素之前」而不是固定下标。窄栏（rail）下宿主把盒子放大到 36px、字形放大到 18px。
+- 远程工具以文本方式传输文件（base64），大文件不适合；大仓库建议让 Agent 在
+  Codespace 内直接操作。
+- `gh` 缺失时依赖用户自行配置 SSH 别名。设置项名为「SSH 密钥」，但**私钥路径无法
+  指定主机**，所以该值被当作 `~/.ssh/config` 的主机别名使用；填成路径会得到一条
+  说明如何修正的错误，而不是把路径当主机名交给 `ssh`。
+- 未在本机实测的部分：**真实 SSH 数据面**（没有已配置的 Codespace 目标），以及
+  Codespace 的创建/启停/删除这些会改云端状态的调用。控制面本身已联网实测：
+  `test/live.mjs` 用 `gh` 的令牌打真实 GitHub API，`getViewer` / `listRepos` /
+  `listCodespaces` 都通（本机 18 个仓库、0 个 Codespace）。命令拼装也已用真实 bash
+  验证：20 组逐字节往返 + 5 组注入载荷，均保持为单个 shell 词且无副作用。
+
+  **「退出即停」不在此列**：它的逻辑已按上面的 `test/shutdown.mjs` 实测（并发、
+  不 reject、5 秒预算内、幂等、pending 落盘）。仍然未经实测的只有「真实 GitHub
+  是否接受这次 stop 调用」这一层——那取决于 token 与账号，不取决于本插件的逻辑。
+  另外「宿主在退出时确实会 await 根 effect 的 disposer」这一条是**读 DSH 源码**
+  核实的（`runProfile` 的 `dispose` → `fiber.dispose()` → cordis `_unload` 并发
+  await 每个 disposer），不是在本机跑一次退出观察到的；本机没有可复现的 Codespace
+  目标，无法做端到端退出观察。
+
+## 发布（维护者）
+
+包名 `dsh-codespace-workspace` 已发布到 npm。`package.json` 里写了 `publishConfig`
+（`access: public` + `registry: https://registry.npmjs.org/`），所以**直接 `npm publish`
+不带任何参数**就会发到正确的地方——即使本机 `~/.npmrc` 指向的是镜像站。
+
+> 注意：这个包曾经带 `"private": true`（那时只从 GitHub 装）。npm 会以 `EPRIVATE`
+> 直接拒绝发布，所以该字段已**删除**（不是改成 `false`）。`test/check.mjs` 里有一条
+> 断言专门盯着它「必须不存在」，复制回来会立刻变红。
+
+后续版本**自动发布**：推送到 `main` 时 `.github/workflows/publish.yml` 会先跑测试再
+`npm publish`——但**只有 `package.json` 里的 `version` 是 registry 上还没有的版本时才发**。
+所以发版流程就是两步：
+
+1. 改 `package.json` 的 `version`。
+2. 推送到 `main`。
+
+这次运行要么发出这个版本，要么报告「该版本已在线上」并以成功结束。
+**没改版本号的推送是 no-op，不是失败**——所以每个要发出去的改动都必须自己带一次版本号
+变更；只改文档的提交同样会触发工作流，同样 no-op。
+
+认证用 npm **Trusted Publishing（OIDC）**：GitHub 给这个 job 签一个短时 token，npm 拿它换
+一个只对这一个包有效的发布 token。**仓库里没有任何 `NPM_TOKEN` secret。** 工作流刻意
+**不用** `actions/setup-node` 的 `registry-url` 输入——它会往 `~/.npmrc` 写
+`//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`，而该变量没定义时这个占位符会
+原样留下、被 npm 当作 token 发出去。registry 交给 `publishConfig` 就够了。
+
+工作流在发布前会先 `npm install` 那两个 peer（`@deepseek-ai/cordis`、
+`@deepseek-ai/schemastery`）：本仓库故意不 vendor 它们，而 `test/check.mjs` 是沿着
+import 路径往上找的，装到仓库自己的 `node_modules` 里才能跑到真实模块。
+
+<details>
+<summary>一次性配置：绑定 Trusted Publisher</summary>
+
+Trusted Publisher **只能绑到 registry 上已存在的包**，所以**首次发布是手工做的**
+（在检出目录里跑了一次 `npm publish`），从第二个版本起才轮到工作流接管。在 npmjs.com 上：
+包 → Settings → Trusted Publisher → GitHub Actions，填
+
+| 字段 | 值 |
+|---|---|
+| Repository | `Ckarefulon/dsh-codespace-workspace` |
+| Workflow filename | `publish.yml` |
+| Environment | *留空* |
+
+文件名必须**逐字一致**——npm 把授权绑在它上面，写错会表现为发布报 `ENEEDAUTH`。
+
+</details>
+
+## 文档
+
+- [`docs/CONTRACT.md`](docs/CONTRACT.md) —— 实现契约：经过核实的 DSH API 事实、
+  冻结的 RPC 契约、模块接口、以及每条未经核实项的处理分支。
+
+## 许可
+
+MIT