@mokuyoaxis/dsh-iris 0.1.4 → 0.2.0

package/user_guide.md

@@ -4,26 +4,32 @@
 
 ## 安装
 
-你需要 DeepSeek Harness `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1`（这两个是已实测窗口，其余预览版未经验证）、PATH 中的 `pnpm`，以及至少一个媒体或视觉服务供应商。dsh-iris 自身要求 Node.js 20.10 或更高版本；如果所用 DSH 版本要求更高，以 DSH 为准。Iris 0.1.1 及后续 0.1.x 不兼容 DSH 0.1.0/0.1.1 的旧客户端 Runtime。
+先运行 `dsh --version`。Iris `0.2.0` 仅声明支持 DSH `0.2.0-rc.2`；旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 使用固定版本 Iris `0.1.4`。验证边界见[适配说明](docs/DSH_RC2_ADAPTATION.md)。还需要 PATH 中的 `pnpm`，以及至少一个媒体或视觉服务供应商。Iris 0.2.0 要求 Node.js 22.0.0 或更高版本，旧 npm 0.1.4 的历史要求为 20.10.0；如果所用 DSH 版本要求更高，以 DSH 为准。Iris 0.1.1 及后续 0.1.x 不兼容 DSH 0.1.0/0.1.1 的旧客户端 Runtime。
 
-从 npm 安装到 Web profile：
+在上述旧 DSH 范围内，从 npm 安装固定稳定版到 Web profile：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4
 dsh web
 ```
 
 npm 上无 scope 的 `dsh-iris` 是另一款插件；安装或更新 Iris Media 时必须使用完整 scoped 包名。
 
-从源码目录试用：
+只下载旧稳定包可运行 `npm pack @mokuyoaxis/dsh-iris@0.1.4`，安装为普通 npm 依赖可运行 `npm install @mokuyoaxis/dsh-iris@0.1.4`；后者不会自动加入 DSH profile。固定版本仍可在 latest 更新后安装，0.1.4 不包含新的 Core 媒体 CLI。DSH rc.2 使用 0.2.0。
+
+在 DSH `0.2.0-rc.2` 上，从 npm 安装：
 
 ```bash
-dsh plugin --profile web add .
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.0
 dsh web
 ```
 
 浏览器默认打开 `http://127.0.0.1:3080`。插件安装后只会在下一次 DSH 启动时装载；如果 DSH 已经运行，请先停止再启动。启动输出包含一次性认证参数时，必须完整打开该 URL，不能只输入裸地址。
 
+其他 DSH 版本，包括 `0.2.0` 正式版与其他 rc，须另行验收。让 Agent 协助安装时，可使用[简要 Prompt](docs/AGENT_QUICKSTART.md)。
+
+通过 dsh-market 安装时也要核对显示的 Iris 版本、完整 scoped 包名和 DSH 支持范围。市场可能缓存 npm 信息；旧宿主仍按固定 `@0.1.4` 命令安装，不直接跟随 latest。
+
 可以在启动前检查组合配置：
 
 ```bash
@@ -38,8 +44,8 @@ dsh --profile web --dump-config
 
 1. 点击“+ 添加供应商”。
 2. 名称可填“阿里云百炼”。
-3. Base URL 填 `https://dashscope.aliyuncs.com/compatible-mode/v1`。
-4. 填入 DashScope API Key，点击“保存”。
+3. Base URL 填 `https://dashscope.aliyuncs.com/compatible-mode/v1`；如果账号使用百炼业务空间专属域名，再把“媒体 Base URL”填为同地域的 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`（地域按账号实际情况替换）。
+4. 填入与模型、Endpoint 同地域的 DashScope API Key，点击“保存”。
 5. 展开刚添加的供应商，点击“发现模型”。
 
 如果只有一个供应商，可以先保留“能力分配”为自动。Iris 会从模型池中为画图、视频、语音、转写和视觉能力选择第一个匹配模型。需要固定模型或设置故障转移顺序时，再到“能力分配（failover 顺序）”中调整。
@@ -55,13 +61,17 @@ Iris 当前支持两类调用路径：
 | DashScope 百炼 | 图片、视频、TTS、转写、视觉 | 覆盖最完整；媒体请求只允许阿里云官方 HTTPS 域名 |
 | OpenAI 兼容 | Images 图片生成、Chat Completions 视觉 | 具体模型和能力取决于兼容服务 |
 
-工作台新增供应商时会按 Base URL 安全推断媒体协议：阿里云官方 DashScope HTTPS 域名使用 `dashscope`，其他地址使用 `openai-images`，也可以在供应商卡片中明确选择。即使配置被误标为 `dashscope`，Iris 也会在 fetch 前拒绝向非官方地址发送 DashScope API Key。
+工作台会按实际媒体端点安全推断协议：设置了“媒体 Base URL”时以它为准，否则沿用 Base URL。阿里云官方 DashScope、地域和 Workspace HTTPS 域名可使用 `dashscope`，其他地址使用 `openai-images`，也可以在供应商卡片中明确选择。即使配置被误标为 `dashscope`，Iris 也会在 fetch 前拒绝向非官方地址发送 DashScope API Key。分离端点后，普通 Base URL 可继续服务视觉/对话，媒体 Base URL 专门服务图片、视频、TTS、转写和媒体模型发现；留空即保持旧行为。
 
 同一个 OpenAI 兼容 Base URL 只有在实际提供相应接口时才能承担对应能力：图片生成需要 Images 接口，视觉理解需要支持图片输入的 Chat Completions 接口。通用 OpenAI 兼容端点目前不能替代 Iris 的 DashScope 视频、TTS 或转写协议。
 
+开发分支中，自动选择的未知端点会在供应商管理区显示“协议为推断值，请确认”，仍按 OpenAI Images 兼容格式请求。显式选择协议后清除标记；不支持的显式协议会在请求前报错，配置值仍保留。视觉类型 `type` 与媒体协议独立，未支持的视觉类型不会被转换为 OpenAI。
+
 ## 模型池
 
-“发现模型”会读取供应商的 `GET /models`，再按模型名识别媒体能力。发现失败时，原模型池不会被清空。
+“发现模型”对普通 OpenAI 兼容服务读取 `GET /models`；对阿里云官方端点读取并分页拉完 `GET /api/v1/models`。官方 `IG/VG/ASR/TTS/VU` 能力元数据优先，缺少元数据时才按模型名兜底。用户手工纠正的能力标签优先级最高，后续重新发现不会覆盖。发现失败时，原模型池不会被清空。
+
+开发分支采用合并发现：保留手工模型、手工能力标注及本次目录未返回的旧模型，只追加或更新发现项。删除模型仍需用户显式操作。运行时仅使用已配置模型；某项能力缺少模型时会提示配置，不再猜测厂商默认值。旧裸账号的兼容目录会在配置写入时转成可编辑的模型条目，显式空模型池不会触发该迁移。
 
 模型池中的能力名称如下：
 
@@ -90,7 +100,7 @@ Iris 当前支持两类调用路径：
 
 | 颜色 | 状态 | 如何得到 |
 |---|---|---|
-| 灰色 | 未配置 | 没有启用且带 API Key 的当前候选；移除 Key 后也回到灰色 |
+| 灰色 | 未配置 | 没有可用的当前候选；默认 bearer 认证缺 Key 时会回到灰色，`auth:'none'` 不要求 Key |
 | 蓝色 | 已配置，待验证 | 配置可用于路由，但尚无 7 天内成功证据，或旧成功已经过期 |
 | 绿色 | 近期验证成功 | 显式实测或真实任务在 7 天内成功 |
 | 暗红色 | 认证失败 | 最近出现明确 401、403 或认证/权限错误 |
@@ -103,7 +113,7 @@ Iris 当前支持两类调用路径：
 
 每项能力都可以设置一个有序的“供应商 + 模型”列表。界面显示的是模型名和供应商，配置中保存为 `providerId::modelId` 复合引用，因此不同供应商的同名模型不会冲突。
 
-- 未手工分配时，按模型池顺序自动选择。
+- 未手工分配时，每个新请求都从模型池第一个匹配项开始；这不是 round-robin。
 - 手工列表中的模型优先，并按列表顺序尝试。
 - 模型池中其余具备该能力的模型仍会作为后续候选。
 - 点击“恢复自动”会清除手工顺序。
@@ -149,6 +159,7 @@ $DSH_HOME/iris/v1/providers.json
       "name": "Primary media provider",
       "type": "openai",
       "baseUrl": "https://api.example.com/v1",
+      "mediaBaseUrl": "https://WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
       "apiKey": "YOUR_API_KEY",
       "enabled": true,
       "mediaProtocol": "openai-images",
@@ -165,7 +176,9 @@ $DSH_HOME/iris/v1/providers.json
 }
 ```
 
-`assignments` 可以省略；省略后使用模型池顺序。包含特殊字符的 provider 或模型引用会经过 URL 编码，复杂引用建议在工作台中生成，不要手写。
+`mediaBaseUrl` 可以省略或留空，此时媒体调用沿用 `baseUrl`。`assignments` 可以省略；省略后使用模型池顺序。包含特殊字符的 provider 或模型引用会经过 URL 编码，复杂引用建议在工作台中生成，不要手写。
+
+当前开发分支允许为明确不需要认证的本地端点设置 `"auth": "none"` 并省略 `apiKey`；缺省或 `"auth": "bearer"` 仍要求 Key，保持旧配置行为。无认证模式不会发送 Authorization 头，已有的旧 Key 也不会被带入该模式的媒体请求。工作台尚无专门的无认证开关，需要按上述停机原则编辑私有配置；不要对需要认证的公网端点使用 `auth:none`。
 
 API Key 以明文保存在宿主侧的 `providers.json` 中。POSIX 上 Iris 目录为 `0700`、文件为 `0600`，0.1.1 首次启动会收紧既有 Iris 树但不修改内容或跟随符号链接；Windows 的 mode 不能替代 ACL。状态接口和界面只返回掩码，不会显示完整 Key。不要把这个文件提交到版本库或发给他人。
 
@@ -312,6 +325,8 @@ npx @mokuyoaxis/dsh-iris doctor --json
 
 已安装包也可以直接运行 `dsh-iris doctor`。退出码为 `0`（正常）、`1`（警告）和 `2`（硬错误）。Doctor 会执行一个随后立即删除的本地写入探针，并检查配置、任务、能力分配、临时文件和产物引用；输出不含完整 API Key。离线模式无法检查 DSH 工具/客户端是否已经装载，也不会用付费请求验证 Provider。
 
+**0.2.0** 另提供 `doctor --data-root <绝对路径> --json`：只读盘点指定 Core 数据根的 Task、Artifact、Index 和租约，不执行上述写入探针，也不自动修复。`providers list` 与 `capabilities list` 可用 `--provider-config <私有配置绝对路径>` 只读查看脱敏供应商摘要和按配置排序的候选链；它们不代表远端能力已实测。异常退出留下租约时，先用显式 Doctor 查看 owner，再按 [Headless CLI 的恢复步骤](docs/HEADLESS_CLI.md#异常退出后的写者租约)人工确认并运行 `runtime recover`，不要手动删除租约。安装 npm 0.2.0 后使用 `dsh-iris` 命令；临时运行可用 `npx --package @mokuyoaxis/dsh-iris@0.2.0 dsh-iris ...`。旧版 0.1.4 不包含这些 Core 命令。
+
 ## Host Doctor
 
 DSH 运行后，打开“设置 → Iris 工作台 → 宿主诊断”。卡片会自动检查当前 DSH 版本、Iris 服务端和客户端版本、14 个工具、两项随包 Skill、四组 Web 路由、四个 UI Slot，以及 Browser、附件、会话和宿主模型端口；点击“刷新”可重新读取，展开项可查看全部结果。需要原始 JSON 时，可在已经完成 DSH Web 认证的同一浏览器访问 `/iris/api/doctor`。