dsh-expert-group 0.1.1 → 0.1.3

package/README.md

@@ -8,20 +8,6 @@
 把「按角色区分模型与思考深度」的专家子代理能力引入 DSH，并在 Web 界面的“dsh-expert-group”设置页维护全局模型、思考深度与通知偏好。
 同时把 oh-my-opencode-slim 的主代理 orchestrator 设计移植过来：根会话负责拆解、委派、整合和验证，专家子代理保持叶子 worker 约束。
 
-本包**不修改** `@deepseek-ai/dsh` 的任何核心源码，也不修改 shipped agent preset。能力全部通过
-现有 Host 服务与客户端 Slot 注册；**最低宿主契约**是下面这些声明在 `inject` 里的服务：
-`tools`、`subagents`、`systemPrompt`、`llm`、`agents`、`settings`、`webServer`。
-
-其中 **goals 是可选兼容服务**：插件通过 `ctx.get("goals")` 读取，不把它声明为 `inject` 依赖。
-宿主缺少该服务时，插件主体、专家派发与其他工具仍正常加载，只有依赖真实 `pause` / `resume`
-的 **goal handoff** 不可用；能力矩阵标记 `required: false`、`status: "absent"` 和
-`degradation: "goal-handoff-disabled"`。服务存在但缺少 `get` / `pause` / `resume` 时同样
-fail-closed，并标记为 `status: "incomplete"`；绝不伪造 paused ref 或假装能 resume。
-
-图片规范化额外使用可选公开 `ctx.attachments` 服务，冷会话精确读取使用可选 `ctx.sessionQuery`；
-两者缺失时只禁用受影响能力（`image-normalization-disabled` / `cold-session-read-disabled`），
-文本专家能力仍可加载。
-
 ## 能力
 
 - 5 个专家子代理工具（默认启用）：
@@ -29,8 +15,8 @@ fail-closed，并标记为 `status: "incomplete"`；绝不伪造 paused ref 或
   - `librarian` — 只读外部文档 / 库 API 调研
   - `oracle` — 只读架构决策 / 疑难调试 / 代码审查
   - `designer` — UI/UX 与视觉实现（可写）
-  - `fixer` — 边界清晰的多文件实现与测试补齐（可写）
-- **视觉代理** `observer`：只读视觉分析专家，负责图片 / 截图 / UI 稿 / 图表 / PDF 的解读。裸 Config 默认关闭；当前 `cordis.patch.yml` 显式把 bundle override 设为开启。图片路由会把 Host 创建的 `image/png` durable attachment ContentBlock 直接交给 Observer；自动图片入口只派发有界的纯视觉任务，用户原始任务仍由主代理持有并综合视觉报告。
+  - `fixer` — 已定方案的实现、重复修改、迁移与测试补齐，含单文件的大量工作（可写）
+- **视觉代理** `observer`：只读视觉分析专家，负责 Host 提供的真实 durable 图片附件的解读，包括截图、UI 稿、图表和已呈现为图片的 PDF 页面；不接受任意本地路径。裸 Config 默认关闭；当前 `cordis.patch.yml` 显式把 bundle override 设为开启。图片路由会把 Host 创建的 `image/png` durable attachment ContentBlock 直接交给 Observer；自动图片入口只派发有界的纯视觉任务，用户原始任务仍由主代理持有并综合视觉报告。
 - 插件工具使用简短、无冲突的角色工具名（`explorer`、`librarian` 等），注册在当前 DSH 的 `ctx.tools`；
   主代理不得把 Harness 外层 `subagent_<role>`、PTC 的 `run_code` 或通用 subagent 入口当作插件委派替代。
 - 每个专家委派始终是可继续（continuable）子代理：默认后台运行立即返回子代理 id；
@@ -38,23 +24,27 @@ fail-closed，并标记为 `status: "incomplete"`；绝不伪造 paused ref 或
 - **无内置默认模型**：新安装后所有角色均为空，需在“dsh-expert-group”设置页从 DSH
   已配置的模型中自行选择并保存；未配置模型的角色在调用时会给出明确提示。
 - 模型与思考深度通过 `llm.listProviders/listModels` + `resolveCallConfig` 校验，只接受设置中已添加的模型。
-- **动态 settings 保存能力**：插件不在模块加载期 import `@deepseek-ai/dsh-settings`，package 也不声明该 peer，因此默认安装不会额外下载 settings 包。目标运行时为 `0.2.0-rc.1`；插件通过宿主 settings 服务的 describe/update/mutate 面读写 profile 条目，并由 DEG 自有的 settings-commit 端点完成语义校验与 revision 冲突检测（宿主不再提供 owner validate 钩子）。
+- **动态 settings 保存能力**：插件不在模块加载期 import `@deepseek-ai/dsh-settings`，package 也不声明该 peer，因此默认安装不会额外下载 settings 包。目标运行时为 `0.2.0-rc.2`；插件通过宿主 settings 服务的 describe/update/mutate 面读写 profile 条目，并由 DEG 自有的 settings-commit 端点完成语义校验与 revision 冲突检测（宿主不再提供 owner validate 钩子）。
 - 子代理的 `reasoningEffort` 通过子代理 `agent/request` waterfall 注入，绕开 `dsh-tool-subagent`
   `AgentOptions` 尚未公开该字段的限制。
 
 ## 安装
 
-本插件发布到 npm 公共源，按包名安装：
+本插件发布到 npm 公共源，用 DSH 官方 `dsh plugin` CLI 按包名安装（`--profile` 为必填参数，一般填 `web`）：
 
 ```powershell
 dsh plugin --profile web add dsh-expert-group
 ```
 
-安装会把本包写入 `$DSH_HOME\profiles\web` 的依赖并加入 profile 的 bundle 层；**重启 DSH Web** 后生效（已运行的进程不会热加载新的 Host 行）。
+前置条件：DSH Web 可正常运行（`dsh web`）、Node.js ≥ 22，且 PATH 上有 `pnpm`。安装后重启 `dsh web` 使插件生效。
 
-要求：DSH Web 可运行（`dsh web`）、Node.js ≥ 22、PATH 上有 `pnpm`。**本插件不内置任何角色默认模型**——安装后需先在「设置 → dsh-expert-group」为各角色选择模型并保存。
+桌面版（Electron 客户端）的 `desktop` profile 由客户端独占管理，PATH 上的 `dsh` CLI 改不动它：先打开 Desktop 完成初始化再完全退出，用安装目录自带的 CLI 执行同一命令。
 
-**可选图像增强**：`sharp` 是 `optionalDependencies`（约 30 MB 原生二进制），用于把 JPEG / WebP / GIF 转码为 PNG；拉取失败或未安装都不影响插件加载，仅会拒绝非 PNG 图片的转码，其余功能全部正常。
+```powershell
+& '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add dsh-expert-group
+```
+
+安装后重新打开 Desktop 使插件生效。本插件不内置角色默认模型：先在 DSH「设置 → 模型」配置模型，再到「设置 → dsh-expert-group」为各角色选择模型并保存。
 
 ## 界面总览
 
@@ -171,7 +161,7 @@ DEG 没有模型可调用的通知工具，也不在会话标题栏或右侧栏
 | 弹窗停留时间（下拉） | `5s` | `5s / 10s / 30s / 60s / 5min / 10min / 永久` | `dsh-expert-group.notificationHoldMs` |
 | 通知音量（滑杆 + 数字框） | `100` | `0 – 100`，步进 `1` | `dsh-expert-group.notificationVolume` |
 
-- 「通知弹窗」关闭后 Host **完全不发送通知**，也不补发；它只影响投递，不影响任务快照、goal handoff 或恢复语义。
+- 「通知弹窗」关闭后 Host **完全不发送通知**，也不补发；它只影响投递，不影响任务快照、root turn 等待或恢复语义。
 - 音量 `100` 表示不做任何衰减，只受 Windows 主音量影响；滑杆与数字框同值双向绑定。
 - 三项都是延迟保存：改完要点页脚「保存」；非法值会回落到默认（停留时间 → `5s`，音量 → `100`）。
 
@@ -351,5 +341,3 @@ Expert Group 是 DEG 注册在右侧栏的任务视图：它把**当前会话所
 - 首次从「只有 Expert Group」的单 pane 分栏时，打开事务会先临时把右栏写到约 50%，目标 tab 确认落到返回的 pane 后保留 50% 的可调模式；分栏失败则恢复原来的 20% 锁定宽度。
 - 日常在已有子代理 pane 里打开 / 关闭 tab 不改宽度。
 - 首次形成两个 pane 后：Expert Group 占右栏 40%（视口约 20%），子代理 pane 占右栏 60%（视口约 30%）；最后一个被跟踪的 pane 关闭后恢复约 20% 的默认宽度。
-
-**能力缺失时的降级**：宿主没有 `sidebarRight.openResource` 时箭头不渲染、其余行内容完整；缺少关闭确认能力时保留静态 `>>`；整条侧栏接缝不可用时 DEG 只注册页面，不猜测打开状态。