dsh-plugin-orchd 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +79 -200
  2. package/package.json +1 -1
  3. package/README.public.md +0 -121
package/README.md CHANGED
@@ -1,242 +1,121 @@
1
1
  # dsh-plugin-orchd
2
2
 
3
- 把 [orchd](https://github.com/7bder/orchd-core) 的任务状态带进 DeepSeek Harness 的**右侧栏面板**：
3
+ Read-only **orchd** panel for the DeepSeek Harness (DSH) **right sidebar**: open a project session and see that
4
+ project's task board, dependency graph, ideas and review timeline next to the conversation.
5
+ No project configuration — the plugin derives the project from the session.
4
6
 
5
- > **点开一个项目会话，插件自动检测这个项目有没有用 orchd。**
6
- > 装了 → 同屏显示任务看板、依赖图、想法与审查历史；没装 → 给一个安装入口。
7
+ 把 [orchd](https://github.com/7bder/orchd-core) 的项目状态带进 DSH 右侧栏的**只读面板**：
7
8
 
8
- 只读：面板不含任何写操作（claim / done / review / merge 一律不出现在 UI）。
9
+ > 点开一个项目会话，面板自动检测这个项目有没有用 orchd。
10
+ > 装了 → 同屏显示任务看板、依赖图、想法与审查时间线；没装 → 给一个接入入口。
9
11
 
10
- ---
11
-
12
- ## 状态
13
-
14
- | 阶段 | 状态 | 交付物 |
15
- |---|---|---|
16
- | **M0** 前置验证 | ✅ 达成 | V1/V2/V4/V5 通过（V3/V6 未开始，不影响交付），记录见 [dev/README-m0.md](dev/README-m0.md) |
17
- | **P0** 端到端链路 | ✅ 完成 | 双半侧包骨架 + `/orchd/api/context` + 四态检测 + 四态卡片 UI + C 路径复制 |
18
- | **P1** 数据可用 | ✅ 完成 | 白名单 CLI 封装 + 定义层索引 + `/board` `/task` + 状态条 + 虚拟化列表 + 筛选/排序 + 详情 |
19
- | **P1b** 安装入口 A | ✅ 完成 | 斜杠命令 `/orchd-install` + 宿主侧 `agent.steer` 注入 + 两段式确认（**不依赖 V3**） |
20
- | **P2** 日常可用 | ✅ 完成 | 审查事件时间线 + 三种空态 + 快照保留/过期横幅 + i18n + 诊断导出 + 依赖跳转 + 每会话记忆 |
21
- | **P2b** 依赖图 | ✅ 完成 | `GET /orchd/api/graph` + 自绘 SVG（聚焦/活跃/全图、环与悬空标注、两轴自绘滚动条） |
22
- | **P3** 想法看板 | ✅ 完成 | `IDEAS.md` 解析 + 归档对照 + `/orchd/api/ideas` + 想法详情与命令生成 |
23
- | **P4** 工程化 | ✅ 完成 | 契约 fixture（六形态 + 录制真实输出）+ 只读冒烟 AC-10.1 + 白名单拒绝留痕 + 两份升级回归清单 |
12
+ **面板没有任何写操作**：`claim` / `done` / `review` / `merge` / `amend` 一律不出现在 UI 里。
24
13
 
25
- 验收口径与逐条证据见 [docs/05-实施计划与验收.md](docs/05-实施计划与验收.md)（§8 各阶段验收、§10 里程碑、§12 变更记录）。
26
-
27
- **测试：10 套件 / 872 项断言**
14
+ ---
28
15
 
29
- ```powershell
30
- node test/run.mjs # 10 套件 872 项
31
- ```
16
+ ## 面板内容
32
17
 
33
- | 套件 | 覆盖 |
18
+ | 视图 | 内容 |
34
19
  |---|---|
35
- | `lint` (8) | 全源文件语法（含 `dev/*.mjs`）、块注释提前闭合、不可见字符、bundle 外壳、seed 词表、无裸色值 |
36
- | `model` (118) | 定义层索引、两层合并优先级、**缺字段必须 null（JSON 往返不丢键）**、详情、看板与排序（含**默认档按时间**）、摘要回退、依赖图（环/悬空/截断/分层） |
37
- | `git-times` (24) | **FR-5.4 排序时间层**：`task/<id>` 分支 tip 时间与 `Merge branch 'task/<id>'` 合并时间的解析、只读调用面、真仓库端到端、非 git 降级 |
38
- | `client` (283) | 浏览器半侧纯函数与结构断言（状态单选、筛选、排序、空态互斥、时间线、滚动条、交互 CSS、i18n 成对） |
39
- | `ideas` (63) | IDEAS 解析（跳 HTML 注释块/未知字段保留）、归档流式计数与对照分组、徽章语义、命令生成 |
40
- | `install` (57) | 安装入口 A 路径：常量模板、消息形状、降级语义、只在显式确认时注入、插件自身不执行安装 |
41
- | `detect` (58) | 四态（AC-2.1..2.5）、flat/container+junction、布局自动探测、项目根推导、single-flight |
42
- | `contract` (45) | **P4 契约**：六种项目形态 → 四态判定；录制真实引擎输出的形状契约（升级漂移报警） |
43
- | `readonly` (55) | **FR-10 只读保证**：白名单 fail-closed、子进程 env 无身份、调用形态（含启动器回退）、超时/错误分类、静态扫描、拒绝留痕 |
44
- | `routes` (161) | 真实 `node:http` 端到端：8 条路由的包络与状态码、缓存语义、prefix 匹配、失败结构化日志 |
45
-
46
- **为什么测试都在进程内**：desktop profile 的宿主有「渲染器来源栅栏」（随机头 `x-dsh-desktop-renderer`），
47
- 宿主进程外的 HTTP 一律 403 —— 详见 [dev/README-m0.md](dev/README-m0.md) 第 2.5 节。
20
+ | **四态检测** | `未安装` / `未初始化` / `就绪` / `异常`，每种状态各自点名原因，不是一句「出错了」 |
21
+ | **看板** | 状态分布、待办 / 在途 / 终态，状态条即筛选器；关键词、筛选、排序；800+ 任务虚拟滚动 |
22
+ | **任务详情** | 目标、验收标准、验证命令、写范围、上游依赖与下游引用（可点跳转）、审查事件时间线 |
23
+ | **依赖图** | DAG：聚焦闭包 / 活跃子图 / 含终态全图；环、自依赖与悬空上游**显式标注**，不静默少画 |
24
+ | **想法（IDEAS）** | 只读想法看板：状态分组、归档任务对照、可复制的推进命令 |
25
+ | **接入入口** | 未安装的项目给两条路：复制命令自己跑，或让当前会话的 agent 去装（注入前先给你看文本） |
48
26
 
49
- ---
50
-
51
- ## 安装 / 卸载
27
+ ## 安装
52
28
 
53
- ```powershell
54
- $env:DSH_HOME='C:\Users\chenqi\.dsh'
29
+ ```sh
30
+ # 推荐：npm 包
31
+ dsh plugin --profile web add dsh-plugin-orchd
55
32
 
56
- # 安装（= 启用；DSH 启动时自动挂载，没有单独的「启动」命令）
57
- dsh plugin --profile desktop add C:\VibeCoding\dsh-plugin-orchd
33
+ # DSH Desktop：用应用自带的终端（欢迎页里那个），**不要**加 --profile
34
+ dsh plugin add dsh-plugin-orchd
35
+ ```
58
36
 
59
- # 确认进了合成树
60
- dsh --profile desktop --dump-config | Select-String orchd-tasks
37
+ 没有 npm 也能从源码装（被市场收录前的等价路径）：
61
38
 
62
- # 卸载（记得清 pnpm link 残留，见下）
63
- dsh plugin --profile desktop remove dsh-plugin-orchd
64
- Remove-Item "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-orchd" -Recurse -Force
39
+ ```sh
40
+ dsh plugin --profile web add github:7bder/dsh-plugin-orchd
65
41
  ```
66
42
 
67
- 装好后：会话 header 角落出现开关，右侧栏出现「orchd 任务」页；没有选中会话时不渲染（平台行为）。
43
+ ## 截图
68
44
 
69
- **已知残留**：`dsh plugin remove` 会在 profile 的 `node_modules/` 下留一个空壳目录（pnpm link 残留）。
70
- 不影响启动（`dsh.profile.bundles` 已无该行），卸载流程里手工删掉即可。
45
+ ![看板：状态条即筛选、搜索、排序、任务列表](assets/screenshot-1.png)
71
46
 
72
- ---
47
+ ![依赖图：分层 DAG、悬空依赖如实标注、异常提示](assets/screenshot-2.png)
73
48
 
74
- ## 开发
49
+ ![任务详情：验收标准、可复制的验证命令、依赖与审查时间线](assets/screenshot-3.png)
75
50
 
76
- ```powershell
77
- node test/run.mjs # 10 套件 872 项；任何改动后必须全绿
78
- node dev/check-docs.mjs # 文档体检（README + docs/*.md + dev/*.md：围栏/表格/重复标题/行号引用）
79
- node dev/build-public.mjs # 组装公开发布树（默认 ..\dsh-plugin-orchd-public）
80
- node dev/release.mjs # 发布同步（排练）：测试 + 体检 + 组装 + 打印公开树差异；--yes 才推送两仓
81
- node dev/render-store.mjs --shot # 商店截图：3 张 3:2 横图到 dev/store/assets/（配合 Chrome 无头）
82
- node dev/marketplace-entry.mjs --check # 上架条目校验（生成投稿文件用 --out <路径>）
83
- node dev/dsh-desktop-profile.mjs plugin --profile desktop add <spec> # 改 desktop profile（见下）
84
- ```
51
+ Desktop 的 `desktop` profile 由应用托管：普通 `dsh plugin --profile desktop ...` 会被 CLI 直接拒（
52
+ `profile "desktop" is managed exclusively by the Electron application`），应用自带终端里不带 `--profile`
53
+ 的命令才改得到它。装好后**重启 DSH**——宿主侧模块不热替换：会话 header 角落出现开关，右侧栏出现「orchd 任务」页。
85
54
 
86
- **改 `lib/**` 或 `client/**` 都要重启 Desktop。** 别绕路，两条路都堵死了：
87
- 浏览器半侧的 `dsh-client-hmr` 只监听产物、我们的包是 pnpm 装的（在监听范围外）；
88
- 宿主半侧的 `dsh-hmr` 在 Desktop 上要 `--expose-internals`，而该 flag 只在 `dsh.cmd` shim 上。
89
- 证据见 [dev/README-m0.md](dev/README-m0.md) 第 3.6 节与 [docs/04](docs/04-DSH插件机制.md) 第 10 节。
90
- **迭代方式：攒一批改动、一次重启**，重启前用 `node test/run.mjs` 拦住语法/契约错误。
91
-
92
- > **注意当前装的是什么**：desktop profile 里 `dsh-plugin-orchd` 是
93
- > `link:C:/VibeCoding/dsh-plugin-orchd-public`（**公开构建树目录**，不是打包件；见 [docs/07](docs/07-发布与上架.md) 第 4.1 节）。
94
- > 所以迭代路径是：**改 dev 源码 → `node dev/release.mjs` 重建公开树 → 重启 Desktop**，不用 remove/add。
95
- > 若确实要改 spec：`node dev/dsh-desktop-profile.mjs plugin --profile desktop add <spec>`（先完全退出 Desktop；
96
- > `--profile` 是 `plugin` 子命令的必需选项，别漏）。
97
- > `desktop` profile 由应用独占管理，普通 `dsh plugin --profile desktop ...` 会被 CLI 拒；这个脚本复刻的是应用自己那条调用。
98
- > ⚠ **2026-10 起应用改名 `DSH NEXT`（2.0.20-next）并改用 asar 打包**（没有 `resources/app` 解包目录）
99
- > ⇒ `dev/dsh-desktop-profile.mjs` 在新版上找不到入口、**用不了**；改 spec 请走应用「欢迎页终端」（不带 `--profile`）。
100
- > 平台事实见 [docs/04](docs/04-DSH插件机制.md) 第 1 节。
101
-
102
- ### 真实数据冒烟（不重启宿主）
103
-
104
- ```powershell
105
- node dev/smoke-real-project.mjs [项目根] # 布局解析 + 定义层索引 + 看板装配（不调引擎）
106
- node dev/smoke-real-cli.mjs [项目根] # 真引擎端到端：status/pool/单任务（只读）
107
- node dev/smoke-readonly.mjs [项目根] # AC-10.1：跑全部 8 条路由，比对前后零变更
108
- ```
55
+ > 被插件市场收录后可以在设置里搜索一键安装。Release 页另有 tarball 资产，但那条路依赖
56
+ > `github.com/release-assets`（在部分网络不稳），且 pnpm 11 对「URL tarball」的 lockfile 完整性要求更严
57
+ > （可能报 `ERR_PNPM_MISSING_TARBALL_INTEGRITY`），所以只作归档与手动备用。
109
58
 
110
- `smoke-readonly` 是**唯一在真引擎、真账本、真 git 仓库上**验证 FR-10.4/10.5 的地方：跑完全部路由后
111
- 比对工作区文件哈希集合、运行目录、会话文件集合、账本事件数（穿透 WAL 数行）与 `git status`。
112
- 唯一被容忍的差异是 SQLite 的 `-wal`/`-shm` 附随文件增删（引擎读路径行为、不含语义），会如实报出但不算失败。
59
+ ## 前置条件
113
60
 
114
- ### 布局探针（无头 Chrome，不重启宿主）
61
+ - **DSH** 提供右侧栏面板席位（`sidebarRightTabs` + `sidebar.right.pane.tab`，session 作用域）。
62
+ - **项目侧装了 orchd**（项目根或容器主工作树下有 `.orchd/`）。没装的话面板会给出接入入口，不会静默失败。
63
+ - **Python 3** 在 PATH 上（`python` / `py -3` / `python3` 依次探测，也可在配置里写死 `pythonPath`）——
64
+ 面板跑的是**项目自带的**引擎入口 `python <项目>/.orchd/__main__.py`，插件不自带、不安装引擎。
115
65
 
116
- ```powershell
117
- node dev/render-pane.mjs --shot # 出 dev/out/pane-*.png，页内自检布局几何
118
- node dev/probe-hover-feedback.mjs # 真发鼠标事件量 hover/按下/焦点环
119
- ```
66
+ ## 只读保证
120
67
 
121
- ---
68
+ 这是硬约束，不是口号：
122
69
 
123
- ## 升级回归
70
+ - 命令白名单 **fail-closed**：不在白名单里的子进程调用根本不 spawn，被拒时记一行结构化日志。
71
+ - 子进程环境**剥掉会话身份**，读命令不会带出任何会被引擎当成「有人在动这个任务」的变量。
72
+ - 不直读账本、不碰锁、不写项目文件；面板不做文件导出（诊断信息只复制到剪贴板）。
73
+ - 开发期在**真引擎、真账本、真 git 仓库**上跑只读冒烟：比对工作区文件哈希、账本事件数、`git status`，要求零变更。
124
74
 
125
- 引擎（orchd）与 DSH 各有自己的漂移风险，两边各一份清单：
75
+ ## 配置
126
76
 
127
- | 哪一侧升级 | 清单 | 怎么跑 |
128
- |---|---|---|
129
- | **orchd 引擎** | [docs/03 第 11 节](docs/03-orchd-对接契约.md) | `node dev/record-fixtures.mjs` 重录 → `node test/contract.test.mjs`；`git diff` 就是「响应形状变了没」的答案 |
130
- | **DSH 平台** | [docs/04 第 11.1 节](docs/04-DSH插件机制.md) | 逐条勾；重点是席位/seed 模块/栅栏/`ctx` API 四类事实是否仍成立 |
77
+ 配置写进 profile 的 `cordis.patch.yml`（`- id: orchd-tasks` 那一行的 `config:` 下），全部有默认值：
131
78
 
132
- 引擎侧要说清一点：**CLI 的响应字典是手写拼装的**（`orchd/report.py`、`orchd/cli/commands/query.py`），
133
- 没有响应侧 JSON Schema，所以形状契约只能靠 `test/fixtures/engine/<引擎版本>/` 里的**录制真实输出**来守。
134
- 录制文件按引擎版本目录化，`manifest.json` 记了每个文件的 `sha256`（契约测试逐文件校验，手改必然红灯）。
79
+ | 键 | 默认 | 说明 |
80
+ |---|---|---|
81
+ | `pythonPath` | `null` | `null` = 自动探测 |
82
+ | `requestTimeoutMs` | `20000` | 单次引擎调用超时（超时与「引擎报错」在 UI 上是两种状态） |
83
+ | `cacheTtlMs` / `pollTtlMs` / `detectTtlMs` | `5000` / `30000` / `10000` | 看板 / 轮询 / 四态检测的缓存 TTL |
84
+ | `maxProjectContexts` | `8` | 每会话项目上下文的 LRU 上限 |
85
+ | `orchdCoreRepo` | `null` | 接入入口里展示的引擎仓库地址 |
86
+ | `allowRoots` | `[]` | 调试用白名单；空 = 不额外收敛 |
135
87
 
136
- ---
88
+ ## HTTP API
137
89
 
138
- ## 包结构
90
+ 面板的数据全部来自插件自己注册的 8 条同源路由（会话绑定，前端只传 `sessionId`，不传路径）：
139
91
 
140
92
  ```
141
- dsh-plugin-orchd/
142
- ├── package.json # dsh.bundle.patch + dsh.client{platform:web} + exports（公开/私有共用一份）
143
- ├── cordis.patch.yml # 向 profile 插入宿主行（含全部配置项默认值）
144
- ├── LICENSE # MIT
145
- ├── README.public.md # 公开仓库用的 README（由 dev/build-public.mjs 改名成公开树的 README.md）
146
- ├── lib/ # 宿主半侧（Node / cordis 插件）
147
- │ ├── index.js # 插件入口：配置规范化 + 缓存 + 路由注册（全部走 ctx.effect）
148
- │ ├── config.js # 配置校验（非法值 warning + 默认值）+ 安装入口常量
149
- │ ├── paths.js # realpath 归一与缓存键
150
- │ ├── python.js # Python 探测（配置值独占；否则 python → py -3 → python3）
151
- │ ├── project.js # sessionId → 项目根；忽略请求里的路径参数
152
- │ ├── master.js # .layout.json 解析 + masterPath 推导 + 定义层索引
153
- │ ├── detect.js # 四态检测（FR-2）
154
- │ ├── orchd-cli.js # 白名单（fail-closed）+ 子进程调用形态 + env
155
- │ ├── cli-invoke.js # 注入式调用装配 + 结果归一 + 拒绝留痕
156
- │ ├── model.js # 两层合并 + 看板 + 依赖图（环/悬空/分层/截断）
157
- │ ├── ideas.js # IDEAS 解析 + 归档对照 + 命令生成
158
- │ ├── install-entry.js # 安装提示词常量模板 + 降级探测
159
- │ ├── cache.js # TTL + single-flight + LRU
160
- │ └── routes.js # HTTP 路由（8 条）+ 统一包络 + 失败结构化日志
161
- ├── client/client.js # 浏览器半侧（手写 bundle，零构建链）
162
- ├── test/ # 进程内测试（9 套件）
163
- │ └── fixtures/ # 契约夹具：六种项目形态 + 录制的真实引擎输出
164
- ├── dev/ # 探针、冒烟、录制与发布/上架脚本（非交付物）+ M0 执行记录
165
- └── docs/ # 本文件集
93
+ GET /orchd/api/context 四态 + 项目身份 + 诊断
94
+ GET /orchd/api/board 状态条 + 任务列表
95
+ GET /orchd/api/task 单任务详情（+ 审查时间线，按需）
96
+ GET /orchd/api/graph 依赖图（节点 / 边 / 环 / 悬空）
97
+ GET /orchd/api/history 审查事件时间线
98
+ GET /orchd/api/ideas 想法看板
99
+ POST /orchd/api/install-entry 返回将要注入的文本（本身不注入）
100
+ POST /orchd/api/install-inject 执行注入（需显式确认）
166
101
  ```
167
102
 
168
- ## 文档索引
169
-
170
- | 文档 | 内容 |
171
- |---|---|
172
- | [docs/01-需求规格.md](docs/01-需求规格.md) | 目标与定位、用户故事、功能需求（含验收标准）、非功能需求、范围边界、已确认决策、术语表 |
173
- | [docs/02-设计方案.md](docs/02-设计方案.md) | 架构总览、包结构、接口契约、四态检测算法、缓存与刷新、UI 设计、安装入口、配置项、失败降级矩阵、测试策略 |
174
- | [docs/03-orchd-对接契约.md](docs/03-orchd-对接契约.md) | orchd 布局与路径解析、命令清单、JSON 响应形状、只读姿势、任务数据模型、账本结构、版本漂移风险与**升级回归清单** |
175
- | [docs/04-DSH插件机制.md](docs/04-DSH插件机制.md) | 插件包形态、seed 模块表、客户端 bundle 契约、slot 席位、宿主路由、渲染器来源栅栏、HMR、**DSH 侧升级回归清单** |
176
- | [docs/05-实施计划与验收.md](docs/05-实施计划与验收.md) | 阶段拆解 P0→P4、M0 执行记录、各阶段验收标准、里程碑、工作量、变更记录 |
177
- | [docs/06-风险与未决项.md](docs/06-风险与未决项.md) | 风险登记表、未决问题、技术债、必须验证的假设、备选路径 |
178
- | [docs/07-发布与上架.md](docs/07-发布与上架.md) | 公开仓库与发布产物、发布流程、插件市场条目与收录门槛、三条安装路径的实测、回滚 |
179
- | [test/fixtures/projects/README.md](test/fixtures/projects/README.md) | 六种项目形态夹具的构造与期望判定、录制输出的重录方式 |
180
- | [dev/README-m0.md](dev/README-m0.md) | M0 全部执行记录：方法、命令、原始证据、清理步骤 |
181
-
182
- ## 四条核心架构决策
183
-
184
- | # | 决策 | 理由（详见设计文档） |
185
- |---|---|---|
186
- | A1 | **不引入 orchd 引擎。** 插件不 vendored、不 pip 安装引擎；只调**项目自带的**入口（`python <启动器路径>`，启动器按「主工作树 → 会话根 → 布局声明的容器根」取第一个存在的 `.orchd/__main__.py`）。 | orchd 的设计就是自包含（安装器把引擎组装进 `.orchd/`）；自带引擎会造成版本与项目数据错配，是最危险的一类静默事故。 |
187
- | A2 | **数据分三层取。** 定义层直读 `_master.json`；状态层调项目自己的 CLI；详情/历史按需调 CLI。 | DAG 所需的 `depends_on` 只有 `_master.json` 里有（CLI 的任何单次调用都不给全量）；而派生状态必须由引擎算，不能在前端重写。 |
188
- | A3 | **项目由会话上下文推导，不写项目配置列表。** `sessionId → ctx.workspaceRegistry.path`，兜底 session header `cwd`。 | 天然支持任意多个 orchd 项目；复用 DSH 已有的 Workspace 层级，不需要再造项目切换器。 |
189
- | A4 | **前端只传 `sessionId`，项目根由宿主推导。** | 否则面板会退化成「任意路径读取器」。 |
103
+ 前缀外的路径一律 404（fail-closed）。
190
104
 
191
- ## 已确认的产品决策
105
+ ## 卸载
192
106
 
193
- | # | 决策 | 状态 |
194
- |---|---|---|
195
- | D1 | 安装入口走 **A（注入提示词让 agent 装）+ C（展示并复制命令）** 双路径 | 已确认；C 路径在 P0，A 路径在 P1b |
196
- | D2 | 范围为 **只读 + DAG**，**不做**任何写操作 | 已确认，`readonly` 套件守着 |
197
- | D3 | 承载形态为 **右侧栏面板**（`sidebarRightTabs` + `sidebar.right.pane.tab`，session 作用域，与会话区 `push` 同屏） | 已确认（2026-10-15 由「左侧栏整页」变更，理由见 [docs/01](docs/01-需求规格.md) D3） |
198
- | D4 | 面板 **只跟当前会话的项目**，不做跨项目聚合、不做项目切换器 | 已确认 |
199
-
200
- ## 一个必须记住的坑：会话身份从哪来
201
-
202
- 右侧栏面板在 **session 作用域**下注册，因此能直接 `inject(sessionId)`；但任何改回 root 作用域
203
- （例如又去用 `main` keyed slot）的写法都会**拿不到 sessionId**——那时只能走
204
- `ctx.uiSession.current` 订阅。历史结论与证据见 [docs/04](docs/04-DSH插件机制.md) 第 6.2 节末尾。
107
+ ```sh
108
+ dsh plugin --profile web remove dsh-plugin-orchd
109
+ ```
205
110
 
206
- ## 接手指引（新会话开场白）
111
+ 已知残留：`remove` 之后 profile 的 `node_modules/` 里可能留一个空目录（包管理器行为），手工删掉即可，
112
+ 不影响启动。
207
113
 
208
- ```
209
- 这个工作目录 C:\VibeCoding\dsh-plugin-orchd 是一个 DSH 插件的实现仓库。
210
-
211
- 请先按顺序读：
212
- - README.md（含当前阶段与开发方式）
213
- - docs/01-需求规格.md
214
- - docs/02-设计方案.md
215
- - docs/03-orchd-对接契约.md
216
- - docs/04-DSH插件机制.md
217
- - docs/05-实施计划与验收.md（第 12 节是变更记录，改类似问题前先查这里）
218
- - docs/06-风险与未决项.md
219
-
220
- P0→P4 全部阶段均已完成（P2b 起由用户桌面验收），详细进度见 docs/05。
221
- 接下来按 docs/05 继续；若要动 P4 的契约夹具或回归清单，先读 test/fixtures/projects/README.md。
222
-
223
- 约束：
224
- 1. 这套文档是唯一依据；文档未覆盖的行为视为未定义——先补文档再实现。
225
- 2. 已确认的决策不要重开讨论：只读+DAG、右侧栏面板、只跟当前会话的项目、安装入口 A+C。
226
- 3. 参考 orchd 项目在 C:\VibeCoding\orchestra（只读）；它是 container 布局且 .orchd 是
227
- junction，是四态检测最难的样本，也是现成的 ready 态验证对象。
228
- 4. FR-10「只读保证」是硬约束：面板任何操作都不得修改项目状态、账本、锁或会话文件。
229
- 改完库代码跑 node dev/smoke-readonly.mjs（真引擎真账本上验零变更）。
230
- 5. 测试跑 node test/run.mjs；宿主侧与浏览器侧改动都需要重启 Desktop。
231
- ```
114
+ ## 边界
232
115
 
233
- > **维护约定**：本节只是**指针**，不重复 `docs/` 的内容。文档正文变更时不需要同步改这里；
234
- > 只有「阅读顺序 / 下一步 / 约束」本身变化时才改——避免与 `docs/` 形成双写。
116
+ 面板**只跟当前会话的项目**，不做跨项目聚合、不做项目切换器（DSH 的 Workspace 分组已经是项目导航）；
117
+ 不做实时推送（引擎没有常驻进程，用缓存 + 手动刷新）；不注册面向模型的工具。
235
118
 
236
- ## 相关项目
119
+ ## 许可
237
120
 
238
- - orchd 引擎：`https://github.com/7bder/orchd-core`（Gitee 镜像 `https://gitee.com/QQ7bder/orchd-core`）
239
- - 本插件的公开仓库（发布与上架流程见 [docs/07](docs/07-发布与上架.md)）：`https://github.com/7bder/dsh-plugin-orchd`
240
- - 开发仓的私有远端（docs/dev/test/feedback 全部在这里）：`https://github.com/7bder/dsh-plugin-orchd-dev`
241
- - npm 包（市场条目会自动映射到它，见 [docs/07](docs/07-发布与上架.md) 第 3/4 节）：`https://www.npmjs.com/package/dsh-plugin-orchd`
242
- - 首个验证项目：本机的 orchd 自托管仓库 `C:\VibeCoding\orchestra`（container 布局，工作区根 ≠ git 根）
121
+ MIT。引擎本体见 [7bder/orchd-core](https://github.com/7bder/orchd-core)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-orchd",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Read-only orchd panel for the DSH right sidebar: task board, dependency graph, ideas and review timeline for the project of the current session. · 把 orchd 项目状态带进 DSH 右侧栏的只读面板。",
5
5
  "license": "MIT",
6
6
  "repository": {
package/README.public.md DELETED
@@ -1,121 +0,0 @@
1
- # dsh-plugin-orchd
2
-
3
- Read-only **orchd** panel for the DeepSeek Harness (DSH) **right sidebar**: open a project session and see that
4
- project's task board, dependency graph, ideas and review timeline next to the conversation.
5
- No project configuration — the plugin derives the project from the session.
6
-
7
- 把 [orchd](https://github.com/7bder/orchd-core) 的项目状态带进 DSH 右侧栏的**只读面板**：
8
-
9
- > 点开一个项目会话，面板自动检测这个项目有没有用 orchd。
10
- > 装了 → 同屏显示任务看板、依赖图、想法与审查时间线；没装 → 给一个接入入口。
11
-
12
- **面板没有任何写操作**：`claim` / `done` / `review` / `merge` / `amend` 一律不出现在 UI 里。
13
-
14
- ---
15
-
16
- ## 面板内容
17
-
18
- | 视图 | 内容 |
19
- |---|---|
20
- | **四态检测** | `未安装` / `未初始化` / `就绪` / `异常`，每种状态各自点名原因，不是一句「出错了」 |
21
- | **看板** | 状态分布、待办 / 在途 / 终态，状态条即筛选器；关键词、筛选、排序；800+ 任务虚拟滚动 |
22
- | **任务详情** | 目标、验收标准、验证命令、写范围、上游依赖与下游引用（可点跳转）、审查事件时间线 |
23
- | **依赖图** | DAG：聚焦闭包 / 活跃子图 / 含终态全图；环、自依赖与悬空上游**显式标注**，不静默少画 |
24
- | **想法（IDEAS）** | 只读想法看板：状态分组、归档任务对照、可复制的推进命令 |
25
- | **接入入口** | 未安装的项目给两条路：复制命令自己跑，或让当前会话的 agent 去装（注入前先给你看文本） |
26
-
27
- ## 安装
28
-
29
- ```sh
30
- # 推荐：npm 包
31
- dsh plugin --profile web add dsh-plugin-orchd
32
-
33
- # DSH Desktop：用应用自带的终端（欢迎页里那个），**不要**加 --profile
34
- dsh plugin add dsh-plugin-orchd
35
- ```
36
-
37
- 没有 npm 也能从源码装（被市场收录前的等价路径）：
38
-
39
- ```sh
40
- dsh plugin --profile web add github:7bder/dsh-plugin-orchd
41
- ```
42
-
43
- ## 截图
44
-
45
- ![看板：状态条即筛选、搜索、排序、任务列表](assets/screenshot-1.png)
46
-
47
- ![依赖图：分层 DAG、悬空依赖如实标注、异常提示](assets/screenshot-2.png)
48
-
49
- ![任务详情：验收标准、可复制的验证命令、依赖与审查时间线](assets/screenshot-3.png)
50
-
51
- Desktop 的 `desktop` profile 由应用托管：普通 `dsh plugin --profile desktop ...` 会被 CLI 直接拒（
52
- `profile "desktop" is managed exclusively by the Electron application`），应用自带终端里不带 `--profile`
53
- 的命令才改得到它。装好后**重启 DSH**——宿主侧模块不热替换：会话 header 角落出现开关，右侧栏出现「orchd 任务」页。
54
-
55
- > 被插件市场收录后可以在设置里搜索一键安装。Release 页另有 tarball 资产，但那条路依赖
56
- > `github.com/release-assets`（在部分网络不稳），且 pnpm 11 对「URL tarball」的 lockfile 完整性要求更严
57
- > （可能报 `ERR_PNPM_MISSING_TARBALL_INTEGRITY`），所以只作归档与手动备用。
58
-
59
- ## 前置条件
60
-
61
- - **DSH** 提供右侧栏面板席位（`sidebarRightTabs` + `sidebar.right.pane.tab`，session 作用域）。
62
- - **项目侧装了 orchd**（项目根或容器主工作树下有 `.orchd/`）。没装的话面板会给出接入入口，不会静默失败。
63
- - **Python 3** 在 PATH 上（`python` / `py -3` / `python3` 依次探测，也可在配置里写死 `pythonPath`）——
64
- 面板跑的是**项目自带的**引擎入口 `python <项目>/.orchd/__main__.py`，插件不自带、不安装引擎。
65
-
66
- ## 只读保证
67
-
68
- 这是硬约束，不是口号：
69
-
70
- - 命令白名单 **fail-closed**：不在白名单里的子进程调用根本不 spawn，被拒时记一行结构化日志。
71
- - 子进程环境**剥掉会话身份**，读命令不会带出任何会被引擎当成「有人在动这个任务」的变量。
72
- - 不直读账本、不碰锁、不写项目文件；面板不做文件导出（诊断信息只复制到剪贴板）。
73
- - 开发期在**真引擎、真账本、真 git 仓库**上跑只读冒烟：比对工作区文件哈希、账本事件数、`git status`，要求零变更。
74
-
75
- ## 配置
76
-
77
- 配置写进 profile 的 `cordis.patch.yml`（`- id: orchd-tasks` 那一行的 `config:` 下），全部有默认值：
78
-
79
- | 键 | 默认 | 说明 |
80
- |---|---|---|
81
- | `pythonPath` | `null` | `null` = 自动探测 |
82
- | `requestTimeoutMs` | `20000` | 单次引擎调用超时（超时与「引擎报错」在 UI 上是两种状态） |
83
- | `cacheTtlMs` / `pollTtlMs` / `detectTtlMs` | `5000` / `30000` / `10000` | 看板 / 轮询 / 四态检测的缓存 TTL |
84
- | `maxProjectContexts` | `8` | 每会话项目上下文的 LRU 上限 |
85
- | `orchdCoreRepo` | `null` | 接入入口里展示的引擎仓库地址 |
86
- | `allowRoots` | `[]` | 调试用白名单；空 = 不额外收敛 |
87
-
88
- ## HTTP API
89
-
90
- 面板的数据全部来自插件自己注册的 8 条同源路由（会话绑定，前端只传 `sessionId`，不传路径）：
91
-
92
- ```
93
- GET /orchd/api/context 四态 + 项目身份 + 诊断
94
- GET /orchd/api/board 状态条 + 任务列表
95
- GET /orchd/api/task 单任务详情（+ 审查时间线，按需）
96
- GET /orchd/api/graph 依赖图（节点 / 边 / 环 / 悬空）
97
- GET /orchd/api/history 审查事件时间线
98
- GET /orchd/api/ideas 想法看板
99
- POST /orchd/api/install-entry 返回将要注入的文本（本身不注入）
100
- POST /orchd/api/install-inject 执行注入（需显式确认）
101
- ```
102
-
103
- 前缀外的路径一律 404（fail-closed）。
104
-
105
- ## 卸载
106
-
107
- ```sh
108
- dsh plugin --profile web remove dsh-plugin-orchd
109
- ```
110
-
111
- 已知残留：`remove` 之后 profile 的 `node_modules/` 里可能留一个空目录（包管理器行为），手工删掉即可，
112
- 不影响启动。
113
-
114
- ## 边界
115
-
116
- 面板**只跟当前会话的项目**，不做跨项目聚合、不做项目切换器（DSH 的 Workspace 分组已经是项目导航）；
117
- 不做实时推送（引擎没有常驻进程，用缓存 + 手动刷新）；不注册面向模型的工具。
118
-
119
- ## 许可
120
-
121
- MIT。引擎本体见 [7bder/orchd-core](https://github.com/7bder/orchd-core)。