dsh-plugin-agent-tree 0.0.0-stage → 0.1.1

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Agent Tree —— DSH Web 插件
+#
+# 插入一个 host 行（插件宿主半部负责 GET /local/dsh-agent-tree/processes）；
+# 客户端半部由本包 package.json 的 dsh.client 声明（./client.js）。
+- insert:
+    - id: dsh-agent-tree
+      name: 'dsh-plugin-agent-tree'
+      config: {}

package/docs/compat.md

@@ -0,0 +1,43 @@
+# 兼容性
+
+## 已验证组合
+
+| 项目 | 版本 | 结果 |
+|---|---|---|
+| DSH | `0.2.1-rc.2`（npm 全局安装，Web profile） | 通过：座位注册、树、模型、定时、外部进程接口、鉴权（未登录 401） |
+| Node.js | 22.x / 24.x | 通过：单测与 verify 脚本 |
+| macOS | 14/15（Apple Silicon） | 通过（`ps` + `lsof` 进程探测） |
+| Linux | 未实机验证 | 预期可用（两者都是 POSIX 工具，参数一致） |
+| Windows | 不支持进程段 | 树本身正常；进程探测依赖 `ps -axo` / `lsof`，不可用 |
+
+## 依赖契约
+
+- 客户端座位：`shell.overlay`（z-index 20 的浮层，`pointer-events` 只在卡片和按钮上开启）。
+- 客户端服务注入：`@deepseek-ai/dsh-client-ui-workspace`（`ctx.workspaces.list`、`ctx.uiWorkspace.openSession`）。
+- 客户端用到的数据：
+  - `useSessions()` / `useSessionStatus()`（拿不到时回落 `ctx.remote.$on('api-session/status')`）
+  - `projectionValues.subagentTiming` / `projectionValues.modelSelection`
+  - `ctx.remote.schedule.catalog()` + `schedule/changed`
+  - `ctx.sessions.subagentAddress()`
+- 宿主侧服务：`webServer`（`ctx.webServer.register`）+ `connection.requestRejection` 鉴权。
+
+## 预发布版本的 peer 坑
+
+DSH 还在 `-rc` 线时，`peerDependencies` 的范围必须**显式带上当前预发布标签**，否则 node-semver 会静默排除它：
+
+```json
+"peerDependencies": { "@deepseek-ai/dsh": ">=0.2.1-rc.2 <0.3.0" }   // ✅
+"peerDependencies": { "@deepseek-ai/dsh": ">=0.2.1-rc.1 <0.3.0" }   // ❌ 0.2.1-rc.2 被排除
+```
+
+`engines.dsh` 同理（本包两者都写了，安装时会校验）。
+
+## 已知不兼容 / 限制
+
+- **0.2.0 及更早**：客户端 `shell.overlay` 座位与 `schedule` 服务都不保证存在，不保证可用。
+- **其它前端**（CLI、Desktop）：本插件只注册 Web 客户端座位，非 Web 端不出现卡片。
+- **多实例**：只看得到当前 Web 实例里的会话；`claude/codex` 进程段看的是本机所有进程（这是有意为之）。
+
+## 变更记录
+
+见 [CHANGELOG.md](../CHANGELOG.md)。

package/docs/install.en.md

@@ -0,0 +1,87 @@
+# Install & configuration
+
+[简体中文](install.md) · English
+
+`dsh-plugin-agent-tree` is a DSH Web client plugin with a tiny host half. It is not a standalone app: it runs on a
+DSH profile and shows up as a small floating card in a corner of the DSH Web UI.
+
+## 0. Prerequisites
+
+| Dependency | Version | Notes |
+|---|---|---|
+| Node.js | `^22.19` or `≥ 24` | same as the DSH runtime |
+| pnpm | 10+ | DSH manages profile dependencies with pnpm |
+| DSH | `≥ 0.2.1-rc.2 < 0.3.0` | verified on `0.2.1-rc.2`, npm-distributed build |
+| An LLM provider | — | the plugin needs no key itself, but you need sessions to observe |
+
+```sh
+npm i -g @deepseek-ai/dsh@0.2.1-rc.2
+dsh --version
+```
+
+## 1. Fresh profile (recommended)
+
+```sh
+dsh --profile agent-tree --from-default-profile web
+dsh plugin --profile agent-tree add dsh-plugin-agent-tree
+dsh --profile agent-tree --port 13090
+```
+
+Open the URL printed in the terminal (the one with the token) — the card is in the bottom-right corner.
+
+## 2. Existing profile
+
+```sh
+dsh plugin --profile web add dsh-plugin-agent-tree
+# then restart the command you normally use to start dsh web
+```
+
+## 3. Other install paths
+
+```sh
+dsh plugin --profile web add "github:yuna78/dsh-agent-tree"
+dsh plugin --profile web add "$PWD"        # local development
+```
+
+## 4. One mandatory step: restart
+
+The plugin ships a **host half** (it registers `GET /local/dsh-agent-tree/processes` for the process probe), so the
+`dsh` process must be restarted once after installing; then hard-refresh the browser (`Cmd/Ctrl + Shift + R`).
+
+Client-only changes (`client.js`) need just a page refresh — the bundle `rev` is computed per request.
+
+## 5. Verify
+
+1. Open DSH Web: `● Agent 树 ▸` or the expanded tree card is in the corner.
+2. Start a conversation and let it work: the headline becomes `● 1 个 agent 在跑`.
+3. Run `claude --help` (or `codex --help`) in a terminal and leave it hanging: a `● claude …` row appears at the
+   bottom of the card within a few seconds — that proves the host endpoint works.
+
+## 6. Upgrade
+
+```sh
+dsh plugin --profile web add dsh-plugin-agent-tree@latest
+# restart dsh, hard-refresh the browser
+```
+
+## 7. Uninstall
+
+```sh
+dsh plugin --profile web remove dsh-plugin-agent-tree
+# restart dsh
+```
+
+A stale `dsh-agent-tree:pos` key stays in `localStorage`; remove it with
+`localStorage.removeItem('dsh-agent-tree:pos')` if you care.
+
+## 8. Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| No card at all | dsh not restarted (host half) / page not hard-refreshed / package missing: `dsh plugin --profile web list` |
+| Card off-screen | drag it back, or clear `dsh-agent-tree:pos` and refresh |
+| Card says `空闲` (idle) | nothing is running and no active schedule — start a conversation |
+| Subagent missing from the tree | that session is not running, or it belongs to another profile (the card only sees this Web instance) |
+| No claude/codex block | host half not loaded (no restart) / not macOS or Linux / executable basename is not exactly `claude` or `codex` |
+| "Add plugin" in DSH can't find it | the market index refreshes nightly; make sure the name is `dsh-plugin-agent-tree` |
+| `[dsh-agent-tree]` warning in the startup log | host half warns and skips the endpoint when `webServer` is unavailable; the client keeps working |

package/docs/install.md

@@ -0,0 +1,95 @@
+# 安装与配置
+
+简体中文 · [English](install.en.md)
+
+`dsh-plugin-agent-tree` 是 DSH Web 的客户端插件（外加一个很小的宿主半部）。它不是独立 App，
+必须挂在 DSH 的 profile 上运行；装完的形态是 DSH Web 界面角落里的那张小卡片。
+
+## 0. 前置条件
+
+| 依赖 | 版本 | 说明 |
+|---|---|---|
+| Node.js | `^22.19` 或 `≥ 24` | 与 DSH 运行时一致 |
+| pnpm | 10+ | DSH 用 pnpm 管理 profile 依赖 |
+| DSH | `≥ 0.2.1-rc.2 < 0.3.0` | 已验证 `0.2.1-rc.2`；用 npm 全局安装的发行版 |
+| 一个 LLM provider | — | 插件本身不需要 key，但要能跑会话才有东西可看 |
+
+```sh
+npm i -g @deepseek-ai/dsh@0.2.1-rc.2   # 若还没装
+dsh --version
+```
+
+## 1. 装到新 profile（推荐，干净）
+
+```sh
+dsh --profile agent-tree --from-default-profile web
+dsh plugin --profile agent-tree add dsh-plugin-agent-tree
+```
+
+启动：
+
+```sh
+dsh --profile agent-tree --port 13090
+```
+
+浏览器打开终端里打印的地址（带 token 的那个），卡片就在右下角。
+
+## 2. 装到现有 profile
+
+```sh
+dsh plugin --profile web add dsh-plugin-agent-tree
+# 然后重启你平时启动 dsh web 的那条命令
+```
+
+## 3. 其它安装方式
+
+```sh
+# GitHub 源码（market 探测之外的花式装法）
+dsh plugin --profile web add "github:yuna78/dsh-agent-tree"
+
+# 本地目录（开发用；改 client.js 刷新即可，改 index.js 要重启）
+dsh plugin --profile web add "$PWD"
+```
+
+## 4. 必须做的一步：重启
+
+插件有**宿主半部**（注册 `GET /local/dsh-agent-tree/processes` 进程探测接口），
+所以 `dsh` 进程需要重启一次才会生效；重启后浏览器硬刷新（`Cmd/Ctrl + Shift + R`）。
+
+只改 `client.js` 时不需要重启宿主，刷新页面即可（bundle 的 `rev` 是运行时计算的）。
+
+## 5. 验证装好了吗
+
+1. 打开 DSH Web，右下角出现 `● Agent 树 ▸` 或展开的树状卡；
+2. 起一个会话让它干活，卡片标题变成 `● 1 个 agent 在跑`；
+3. 在终端跑 `claude --help` 或 `codex --help` 让它挂着，几秒后卡片底部出现 `● claude …` 行
+   （说明宿主半部的进程接口通了）。
+
+## 6. 升级
+
+```sh
+dsh plugin --profile web add dsh-plugin-agent-tree@latest
+# 重启 dsh + 硬刷新
+```
+
+## 7. 卸载
+
+```sh
+dsh plugin --profile web remove dsh-plugin-agent-tree
+# 重启 dsh
+```
+
+浏览器 `localStorage` 里会残留一个位置键 `dsh-agent-tree:pos`，卸载后无副作用；
+想清掉就在浏览器控制台 `localStorage.removeItem('dsh-agent-tree:pos')`。
+
+## 8. 排查
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| 根本没有卡片 | 没重启 dsh（宿主半部）/ 页面没硬刷新 / profile 里没这个包：`dsh plugin --profile web list` |
+| 卡片在屏幕外面 | 拖回来即可；或清 `dsh-agent-tree:pos` 后刷新 |
+| 卡片是空的（`空闲`） | 当前没有正在跑的会话、也没有 active 定时任务；起个会话或 `dsh` 里发一条消息 |
+| 有 subagent 但树里没有 | 该会话不是 running 状态；或它属于别的 profile（本卡只显示当前 Web 实例的会话） |
+| 底部没有 claude/codex 段 | 宿主半部没加载（没重启）/ 平台不是 macOS、Linux / 进程 basename 不是精确的 `claude`、`codex` |
+| 市场「Add plugin」搜不到包 | 见 <https://github.com/yuna78/dsh-agent-tree#readme>；通常是市场夜间索引还没收录，或包名打错（是 `dsh-plugin-agent-tree`） |
+| 启动日志有 `[dsh-agent-tree]` 警告 | 宿主半部在缺 `webServer` 时会 warn 并跳过接口，客户端照常工作 |

package/docs/manual.en.md

@@ -0,0 +1,197 @@
+# Manual: how to read the card
+
+[简体中文](manual.md) · English
+
+```
+┌──────────────────────────────────────────────────┐
+│ ● 5 个 agent 在跑 · 2 个定时                  ▾  │ ← headline + collapse
+├──────────────────────────────────────────────────┤
+│ ▾ ● dsh                          2 个 workspace  │ ← top-level agent: this DSH instance
+│ ├─ ▾ proj-alpha                              2  │ ← workspace
+│ │  ├─ ▾ ● Refactor billing flow  ⏱8m  v4.1-pro  │ ← conversation (green)
+│ │  │  ├─ ● Explore repo structure      1m5s     │ ← subagent (blue)
+│ │  │  │  └─ ● Run unit tests              9s     │ ← grandchild (violet)
+│ │  │  └─ ● Write migration plan          31s     │
+│ │  └─   Fix flaky login test      ⏱2h  v4.1-flash │ ← scheduled, currently idle
+│ ├─ ▾ my-repo                                 1  │
+│ │  └─ ● Triage CI failures        v4.1-pro       │
+│ ▾ ● claude  proj-alpha                 12m 3%    │ ← top-level agent: local claude (dsh peer)
+│ │  └─ computer use ×2                    41m     │ ← its children, grouped by kind
+│ ▾ ● codex   ChatGPT                 69h35m 2%    │
+│    ├─ MCP ×2                             2h50m   │
+│    ├─ computer use ×2                     41m    │
+│    └─ code mode                           41m    │
+│ 会话 6 · 子代理 3 · 运行中 5（live）             │ ← self-check line
+└──────────────────────────────────────────────────┘
+```
+
+## 1. Headline
+
+| Text | Meaning |
+|---|---|
+| `● 5 个 agent 在跑 · 2 个定时` | 5 sessions/subagents are running; 2 sessions have an active schedule |
+| `空闲 · 2 个定时待命` | nothing running, only scheduled tasks pending |
+| `● Agent 树 ▸` | collapsed (single line) |
+| `▾ / ▸` on the right | manual expand / collapse; manual wins over auto-collapse |
+
+Auto-collapse rule: collapse when `running === 0 && scheduled === 0`; expand automatically as soon as work appears
+(unless you collapsed it manually).
+
+## 1.4 Sessions waiting for your call
+
+When an agent asks a question (`ask_user_question`), waits for an approval, or waits for a plan review, the session
+stops at "waiting for input" and no longer counts as running. The card puts those rows **first**, in amber, with a badge:
+
+```
+├─ ● Research team 1         待答   v4.1-pro
+│  └─ ● Plan review          待审
+```
+
+- `待答` — the agent asked a question and waits for your answer.
+- `待批` — waiting for you to approve one operation.
+- `待审` — waiting for your plan review.
+
+They sort above running rows, so they can never be collapsed away for "not running"; the headline becomes
+`N waiting for you · M running · K scheduled`.
+
+## 1.5 Levels
+
+Four levels (plus grandchild, i.e. five in the deepest row):
+
+```
+dsh (this instance)
+└─ workspace
+   └─ conversation
+      └─ subagent
+         └─ grandchild …
+```
+
+The `dsh` root row collapses every workspace at once; its right side shows the workspace count.
+
+## 2. Row elements
+
+| Element | Meaning |
+|---|---|
+| `├─ └─ │` | git-log-style connectors; each depth adds three columns of indentation |
+| `▾ / ▸` | this row has children — expand / collapsed |
+| `●` | status dot, colored by depth (below) |
+| Title | session title (`displayTitle`), elided when long; running rows are bolder |
+| `⏰` + `8m` | countdown to the next scheduled run: `now` / `<1m` / `8m` / `2h` / `3d` |
+| `v4.1-flash` | model chip (right aligned) from `modelSelection`, with `deepseek-` / `anthropic-` prefixes stripped |
+| `1m5s` | elapsed duration (subagent rows only): `45s` / `12m` / `1h5m` |
+
+## 3. Colors
+
+| Color | Meaning |
+|---|---|
+| green | top-level conversation running in its own session |
+| blue | level-2 subagent |
+| violet | level 3 and deeper |
+| grey / dim | finished, kept only to preserve the hierarchy |
+| orange / green (bottom block) | claude process / codex process |
+
+## 4. Model inheritance
+
+Subagent projections often carry no `modelSelection`; the card then uses the nearest ancestor's model and the tooltip
+says it was inherited. So every row can answer "which model is this".
+
+## 5. Scheduled rows
+
+DSH Automation tasks (`schedule.catalog()`) drive intermittent sessions: idle most of the time, they fire on a timer.
+Those sessions are listed even while idle, with `⏱` showing the next fire time — clicking jumps to them as usual.
+
+## 6. Local external agents (peers of dsh)
+
+Read-only probe from the host half, listing running `claude` / `codex` CLIs on this machine. They are
+**top-level nodes just like `dsh`** (same row spec: same font size, same dot, same collapse); only the dot
+color differs (claude orange / codex green):
+
+```
+├─ ● claude  proj-alpha        12m 3%
+└─ ● codex   my-repo            3m
+```
+
+- `label` resolution: real cwd basename → `--cwd/--cd/-C` from the command line → `ChatGPT` for the desktop backend → empty.
+- Max 8 rows, 3s cache on the host, requires a logged-in session (401 otherwise).
+- Purpose: "while I work inside DSH, is some other agent also running on this machine?"
+
+### 6.1 Children of an external agent
+
+`claude` / `codex` children hang under them by `ppid`, grouped by kind:
+
+```
+├─ ▾ ● codex  ChatGPT        69h35m 2%
+│  ├─ MCP ×2                    2h50m
+│  ├─ computer use ×2             41m
+│  └─ code mode                   41m
+```
+
+- `×N` = how many children of that kind; the right column shows the longest elapsed among them.
+- Clicking the process root collapses its subtree.
+- A real agent CLI found among the descendants is listed as its own root instead of being nested twice.
+
+### 6.2 codex sub-conversations (subagent threads)
+
+Every codex session (CLI or ChatGPT desktop) writes a rollout: `~/.codex/sessions/<y>/<m>/<d>/rollout-*.jsonl`.
+Its first line is `session_meta`, which already carries `thread_source: subagent`, `parent_thread_id`,
+`agent_nickname` and `agent_path`. The plugin reads only those headers and rebuilds the tree by `parent_thread_id`,
+hanging it under the codex row:
+
+```
+▾ ● codex ChatGPT              69h35m 2%
+   ├─ ● Hubble   advance_review_logic       running
+   ├─ ● Carson   review_nextarchive_code    16m前
+   ├─ ● Wegener  review_nextarchive_triage  1h42m前
+   ├─ MCP ×2                                2h50m
+   └─ computer use ×2                        41m
+```
+
+- Active within the last two minutes → `running` (green, bold); otherwise "last active N ago".
+- Which main session: matched by the process cwd first (worktree runs match on a cwd prefix); for ChatGPT desktop
+  processes the cwd is usually `/`, so a session whose `originator` contains `Desktop` wins.
+- At most 8 sub-conversations, 3 levels deep. Local read-only, no network.
+
+### 6.3 The codex row's name
+
+The row is named after **the first real request of that codex session** (skipping codex's own
+`environment_context` / `AGENTS.md instructions` injections), followed by a grey directory chip:
+
+```
+▾ ● codex 推进一下能推进的任务，看看流水线…   devline   69h35m 2%
+```
+
+- Falls back to the directory name / `ChatGPT` only when the rollout has no user message yet.
+- With several codex processes in one cwd, each claims a distinct session by recency, so rows never share a name.
+
+## 7. Interaction
+
+| Action | Effect |
+|---|---|
+| click a row | jump to that session (subagents open their own conversation) |
+| click `▾/▸` | collapse / expand that node's children |
+| drag the header | move the card; position saved in `localStorage: dsh-agent-tree:pos` |
+| click headline `▾/▸` | collapse / expand the whole card |
+
+## 8. Refresh cadence
+
+| Data | Cadence |
+|---|---|
+| running state | official `api-session/status` events (`live`); 1s snapshot polling (`poll`) as fallback |
+| scheduled tasks | `schedule/changed` events + a 15s poll |
+| external processes | every 5s (host caches for 3s) |
+| countdown / duration | recomputed every second |
+
+## 9. Self-check line
+
+`会话 N · 子代理 M · 运行中 K（live|poll）`
+
+- `N` sessions in the snapshot, `M` of them `origin: subagent`, `K` considered running;
+- `live` = official realtime events, `poll` = fallback. If it stays `poll`, this DSH build lacks the global status
+  store — worth an issue.
+
+## 10. Known limits
+
+- Only the current Web instance's sessions are visible (not other profiles or machines).
+- Running state follows DSH status events; a finished subagent may linger for a second or two.
+- Width is fixed at 288px; long titles elide (change `WIDTH` in `client.js`).
+- UI strings are Chinese for now.

package/docs/manual.md

@@ -0,0 +1,205 @@
+# 使用手册：这张卡怎么读
+
+简体中文 · [English](manual.en.md)
+
+```
+┌──────────────────────────────────────────────────┐
+│ ● 5 个 agent 在跑 · 2 个定时                  ▾  │ ← 头部：统计 + 折叠
+├──────────────────────────────────────────────────┤
+│ ▾ ● dsh                          2 个 workspace  │ ← 顶层 agent：这个 DSH 实例
+│ ├─ ▾ proj-alpha                              2  │ ← workspace
+│ │  ├─ ▾ ● ⏰ Refactor billing flow  8m  v4.1-pro  │ ← 对话（绿点，挂了定时）
+│ │  │  ├─ ● Explore repo structure      1m5s     │ ← subagent（蓝点）
+│ │  │  │  └─ ● Run unit tests              9s     │ ← 孙代理（紫点）
+│ │  │  └─ ● Write migration plan          31s     │
+│ │  └─   ⏰ Fix flaky login test      2h  v4.1-flash │ ← 有定时、当前空闲
+│ ├─ ▾ my-repo                                 1  │
+│ │  └─ ● Triage CI failures        v4.1-pro       │
+│ ▾ ● claude  proj-alpha                 12m 3%    │ ← 顶层 agent：本机 claude（和 dsh 同级）
+│ │  └─ computer use ×2                    41m     │ ← 它的子进程（按种类归组）
+│ ▾ ● codex   ChatGPT                 69h35m 2%    │
+│ ├─ MCP ×2                                2h50m   │
+│ ├─ computer use ×2                        41m    │
+│ └─ code mode                              41m    │
+│ 会话 6 · 子代理 3 · 运行中 5（live）             │ ← 自检行
+└──────────────────────────────────────────────────┘
+```
+
+## 1. 头部
+
+| 文案 | 含义 |
+|---|---|
+| `● 5 个 agent 在跑 · 2 个定时` | 5 个会话/子代理处于 running；另有 2 个会话有 active 定时任务 |
+| `空闲 · 2 个定时待命` | 没有正在跑的，只有定时任务等着 |
+| `● Agent 树 ▸` | 收起状态（只有一行） |
+| 右侧 `▾ / ▸` | 手动展开 / 收起；手动操作优先于自动折叠 |
+
+自动折叠规则：`running === 0 && scheduled === 0` 时收起；一旦有活儿自动展开（除非你手动收起了）。
+
+## 1.4 需要你拍板的会话
+
+agent 提问（`ask_user_question`）、等你批准一次操作、等你审阅计划时，会话会停在「等输入」状态，不算在跑。
+卡片把这类会话**放在最上面**，并换成琥珀色 + 小徽标：
+
+```
+├─ ● 智力研发团队 1            待答   v4.1-pro
+│  └─ ● 计划审阅               待审
+```
+
+- `待答`：agent 提了问题，等你选/答。
+- `待批`：等你批准一次操作（命令、写文件、联网等）。
+- `待审`：等你审阅计划（plan review）。
+
+这类行排在「在跑」之前，所以永远不会因为「没在跑」被折叠掉；标题栏也会变成
+「N 个等你处理 · M 个在跑 · K 个定时」。
+
+## 1.5 层级
+
+**顶层是「本机上的 agent」列表**：`dsh`（这个实例）和每个外部 `claude` / `codex` 是同级节点，
+各自往下展开：
+
+```
+dsh（这个实例）                  claude / codex（本机其它 agent）
+└─ workspace                     └─ 子进程（按种类归组）
+   └─ 对话
+      └─ subagent
+         └─ 孙代理 …
+```
+
+所以从 `dsh` 往下是 4 层（workspace → 对话 → subagent → 孙代理），每个顶层 agent 都可以单独折叠。
+
+## 2. 树行元素
+
+从左到右：
+
+| 元素 | 含义 |
+|---|---|
+| `├─ └─ │` | git log 风格连接线，表示层级；每深一层多三格缩进 |
+| `▾ / ▸` | 这一行有子代理，可展开 / 已收起 |
+| `●` | 状态点：颜色见下表 |
+| 标题 | 会话标题（`displayTitle`），过长省略；运行的会话字更粗更深 |
+| `⏰` + `8m` | 标题前的小闹钟表示这行挂了定时 / 循环任务；右侧是倒计时：`now` / `<1m` / `8m` / `2h` / `3d`（到期显示 `now`，闹钟不消失） |
+| `v4.1-flash` | 模型标签（右侧对齐）：来自 `modelSelection`，`deepseek-` / `anthropic-` 前缀会去掉 |
+| `1m5s` | 运行或已运行时长（subagent 行才有）：`45s` / `12m` / `1h5m` |
+
+## 3. 颜色
+
+| 颜色 | 含义 |
+|---|---|
+| 绿点 | 顶层对话在自己的会话里跑 |
+| 蓝点 | 第 2 层 subagent |
+| 紫点 | 第 3 层及更深（孙代理……） |
+| 灰点 / 浅字 | 已结束，但为了让层级完整仍保留的行 |
+| 橙点 / 绿点（底部段） | claude 进程 / codex 进程 |
+
+## 4. 模型标签的继承
+
+subagent 的 `modelSelection` 常常为空，这时用最近一个祖先会话的模型，悬停会显示「继承自上级」。
+所以「这一行用的是哪个模型」永远有答案，不会留白。
+
+## 5. 定时任务行
+
+DSH 的 Automation tasks（`schedule.catalog()`）驱动的是「间歇式工作」的会话：它们大部分时间空闲，
+到点自己跑一次。卡片会把这些会话**即使不在跑也列出来**：
+
+- 标题前固定一个 `⏰`（小闹钟），一眼认出「这行是循环任务」；
+- 右侧是距下次触发的倒计时；
+- 刚跑完、倒计时到期时显示 `now`，但 `⏰` 保持——正在跑的循环任务不会看起来像普通会话。
+
+点它同样能跳过去看上一次跑出来的东西。
+
+## 6. 本机外部 agent（和 dsh 同级）
+
+宿主半部的只读探测，列出本机正在跑的 `claude` / `codex` CLI。它们**和 `dsh` 一样是顶层节点**
+（同一套行规格：同样字号、同样圆点、同样折叠），区别只有圆点颜色（claude 橙 / codex 绿）：
+
+```
+▾ ● claude  proj-alpha        12m 3%
+▾ ● codex   ChatGPT        69h35m 2%
+```
+
+- 行名（`label`）的取值顺序：该 codex 会话的第一条真实用户消息（跳过 `environment_context` / `AGENTS.md` 注入）
+  → 进程真实 cwd 的目录名 → 命令行里的 `--cwd/--cd/-C` → `ChatGPT`（桌面端 backend）→ 空。
+- 只显示前 8 条；结果缓存 3 秒；接口需要登录态（未登录 401）。
+- 目的是「我在 DSH 里干活时，本机还有没有别的 agent 在偷偷跑」；点这一行可折叠子树。
+
+### 6.1 外部 agent 的子进程
+
+`claude` / `codex` 的子进程按 `ppid` 挂成子树；同一种子进程会归组成一行：
+
+```
+├─ ▾ ● codex  ChatGPT        69h35m 2%
+│  ├─ MCP ×2                    2h50m
+│  ├─ computer use ×2             41m
+│  └─ code mode                   41m
+```
+
+- `×N` 表示有几个同类子进程，右侧显示其中跑得最久的时长；
+- 点进程根行可以折叠它的子树；
+- 子孙里如果又是一个真正的 agent CLI，会单独作为根出现，不重复挂。
+
+### 6.2 codex 的子对话（subagent threads）
+
+codex（CLI 和 ChatGPT 桌面端）每开一个会话都会写一条 rollout：`~/.codex/sessions/<年>/<月>/<日>/rollout-*.jsonl`。
+第一行是 `session_meta`，里面就有 `thread_source: subagent`、`parent_thread_id`、`agent_nickname`、`agent_path`。
+插件只读这些头部、按 `parent_thread_id` 串成树，挂在 codex 那一行下面：
+
+```
+▾ ● codex ChatGPT              69h35m 2%
+   ├─ ● Hubble   advance_review_logic       running
+   ├─ ● Carson   review_nextarchive_code    16m前
+   ├─ ● Wegener  review_nextarchive_triage  1h42m前
+   ├─ MCP ×2                                2h50m
+   └─ computer use ×2                        41m
+```
+
+- 2 分钟内活动过标 `running`（绿点加粗），否则显示「最后活动多久前」。
+- 找的是哪条主会话：先按进程 cwd 匹配，worktree 里跑的就取 cwd 互为前缀的那条；
+  ChatGPT 桌面端进程 cwd 常常是 `/`，这时优先挑 `originator` 带 `Desktop` 的会话。
+- 最多 8 个子对话、最深 3 层。只读本机、不联网、不外发。
+
+### 6.3 codex 那行的名字
+
+行名不是目录名，而是**这条 codex 会话的第一句真实需求**（跳过 codex 自己塞的 `environment_context`、
+`AGENTS.md instructions` 这类上下文），后面跟一个灰色的目录小标签：
+
+```
+▾ ● codex 推进一下能推进的任务，看看流水线…   devline   69h35m 2%
+```
+
+- 取不到（rollout 刚建、还没写用户消息）才回落到目录名 / `ChatGPT`。
+- 同一 cwd 下有多个 codex 进程时，按时间各认领一条会话，所以不会出现两行同名。
+
+## 7. 交互
+
+| 操作 | 效果 |
+|---|---|
+| 点一行 | 跳到该会话（subagent 会落到它自己的对话） |
+| 点 `▾/▸` | 折叠 / 展开该节点的子代理 |
+| 拖标题栏 | 移动卡片，位置存 `localStorage: dsh-agent-tree:pos` |
+| 点头部 `▾/▸` | 收起 / 展开整张卡 |
+
+## 8. 刷新节奏
+
+| 数据 | 频率 |
+|---|---|
+| running 状态 | 官方实时事件 `api-session/status`（`live`）；拿不到时 1s 轮询快照（`poll`） |
+| 定时任务 | 事件 `schedule/changed` + 15s 轮询兜底 |
+| 外部进程 | 5s 一次（宿主侧再缓存 3s） |
+| 倒计时 / 时长 | 每秒重算显示 |
+
+## 9. 自检行
+
+`会话 N · 子代理 M · 运行中 K（live|poll）`
+
+- `N` 是快照里能看到的会话数，`M` 是其中 `origin: subagent` 的数量；
+- `K` 是判定为 running 的数量；
+- `live` 表示用的是官方实时事件，`poll` 表示回落到了轮询 —— 如果长期是 `poll`，说明这个 DSH 版本的全局
+  props 里没有状态 store，可以据此提 issue。
+
+## 10. 已知限制
+
+- 只显示**当前 Web 实例**的会话（别的 profile / 别的机器看不到）。
+- 运行状态以 DSH 的状态事件为准；如果某个子代理在 DSH 里已经结束、但事件还没到，可能短暂多显示一两秒。
+- 卡宽固定 288px，超长标题会省略；想加宽改 `client.js` 顶部的 `WIDTH`。
+- UI 文案暂时是中文。