@kiritoko1029/dsh-multi-agent 0.0.0-stage → 0.9.3

package/CHANGELOG.md

@@ -0,0 +1,234 @@
+# 更新日志
+
+本项目的更新日志遵循 [Keep a Changelog] 风格，版本编号遵循 [语义化版本]。历史条目按现有说明与验证记录整理；无法确认发布日期的版本不标注日期。
+
+## [0.9.3] - 2026-11-14
+
+### 新增
+
+- GitHub Release 工作流新增 `publish-npm` 后续任务：新版本标签完成 GitHub Release 后，下载并校验同一份 TGZ 资产，自动发布到 npm 并附加 provenance。
+- 使用 npm Trusted Publishing：npm 11.20.0 通过 GitHub OIDC 获取短期发布凭证，不配置或存储 `NPM_TOKEN` 等长期令牌。
+- 新增发布校验脚本，绑定标签、checkout 与 TGZ 清单、仓库、Release 构建 SHA-256、侧车和 npm SHA-512 integrity；支持重复运行跳过与发布后有界验证。
+- Release 任务增加完整测试门禁，测试通过后才创建 Release 并进入 npm 发布任务。
+
+### 变更
+
+- 包名改为 `@kiritoko1029/dsh-multi-agent`，移除 `private: true`，显式设置公共 npm registry 与 `access: public`；后续 Release TGZ 使用 scoped 包名生成的资产文件名。
+- Cordis patch、Client module id 与 locale namespace 同步使用 scoped 包名；包名也是 DSH 插件安装身份，升级时不要同时启用新旧两个包。
+- 为配置 Trusted Publisher 创建 `0.9.3-stage.0` 预发布引导版本；它不是稳定插件发行版。现有 0.9.2 及更早版本不追溯发布，从 0.9.3 开始由发布工作流自动发布稳定版。
+
+### 修复
+
+- 默认 `main-session` 策略现在读取主会话有效权限预设；仅在 `never + danger-full-access`（不再询问 + 完全权限）同时成立时继承完全权限，不再把 Host 的策略自动拒绝误当成子代理应拒绝。
+- 继承时 Codex 使用原生 `danger-full-access` 线程，agy 追加 `--dangerously-skip-permissions`，Kimi 自动允许 ACP 权限申请。其他权限组合、显式人工审批等策略及服务检测失败仍走原审批链，用户主动拒绝保持拒绝。
+
+### 测试
+
+- 新增发布资产身份、OIDC、integrity、幂等恢复及主会话权限继承测试；完整回归共 400 项，399 通过、0 失败、1 项原有条件跳过。
+- `npm run check`、`npm run build`、`npm run release:pack` 与 `git diff --check` 通过；真实 rc.1 / rc.2 双版本契约矩阵仍需固定官方源码，未在本轮执行。
+
+## [0.9.2] - 2026-11-14
+
+### 新增
+
+- 会话顶栏右侧新增“多 Agent 派发”小按钮，通过 `shell.overlay` 打开宽约 1180px、高约 85vh 的设置浮层，并带小屏尺寸约束。
+- 面板按“全部”“模型与思考强度”“派发策略与规则”“运行参数”分组，集中管理 DSH、Codex、Kimi Code 和 Antigravity（agy）的模型、思考强度、路由、权限与运行配置。
+- 支持未保存修改关闭确认、Escape 与遮罩关闭、焦点圈定和焦点恢复，并提供中英文界面。
+
+### 变更
+
+- 移除 DSH 设置页中的旧“多 Agent 派发”入口；保留四个 Config namespace 的已有配置值、独立 revision / CAS 保存及部分失败处理，无需迁移设置。
+- 更新 README、安装与分享文档，统一说明新的顶栏入口。
+
+### 修复
+
+- 使用宿主实际提供的主题 token，以 `color-mix(...)` 和 `--dsw-alias-brand-primary` 替代不存在的 `--dsw-alias-brand-primary-soft`。
+
+### 已知限制
+
+- 主会话设为“不再询问”（`never`）时，走 `main-session` 的子代理审批会按 fail-closed 语义拒绝；当前审批结果未区分策略自动拒绝与用户主动拒绝，本版没有放宽权限或改变该语义。
+
+### 测试
+
+- 新增顶栏 Slot 注册、面板分组、焦点与关闭行为、主题约束及 CAS 保存等 Client 测试。
+- `npm run check` 通过；`npm test` 共 371 项，370 通过、0 失败、1 项原有条件跳过；`npm run build` 与 `git diff --check` 通过。
+
+## [0.9.1] - 2026-11-13
+
+### 修复
+
+- 子代理权限申请现在会显示**具体要做什么**：ACP `session/request_permission` 的命令（`command:`）、目标路径（`path:`）和内容预览（`content:`）都会被解析进审批卡片，不再只剩 `Write` / `Bash` 这类工具标题。
+- 兼容不同 ACP 实现的信息位置：Kimi Code 只在 `toolCall.content` 的文本块里给出动作说明（没有 `kind`、`rawInput`、`locations`）；agy 则用 `kind`、`locations`、`diff` 内容块和 `rawInput`（`CommandLine` / `Path` / `Content`）。两种载荷都能还原出命令与文件路径。
+- 缺少 `kind` 时按工具名或标题推断类别（`Bash` → 执行命令、`Write` → 写入文件等）；中文任务下审批标题显示中文类别（如“子代理权限请求（写入文件）”），不再出现“（unknown）”。
+
+### 测试
+
+- 新增 5 项权限详情测试，夹具取自 Kimi 与 agy 实际 ACP 会话捕获的原始载荷；`npm test` 共 366 项，365 通过、0 失败、1 项原有条件跳过。
+
+## [0.9.0] - 2026-11-13
+
+### 新增
+
+- 为 Codex、Kimi Code 和 Antigravity（agy）分别提供子代理权限请求策略：主会话审批（默认）、人工审批、允许所有、拒绝所有及子代理控制。子代理控制支持 `auto`、`full-access`（完全访问）和 `ask-request`（逐次询问）三级。
+- 主会话审批将申请送入派发任务的主会话审批链，在 Web 端显示原生审批面板；轮次已结束、无可用应答器或审批服务异常时，降级为交互式审批卡片。人工审批直接提供“允许一次”“始终允许”“拒绝”选项。
+- Kimi 与 agy 的 ACP `session/request_permission` 按所选策略处理；子代理控制的 `auto` 接受其内部规则过滤后提出的单次申请，`ask-request` 将每次申请送主会话审批。Kimi 的 ACP 子命令没有公开的跳过权限参数，其 `full-access` 通过自动允许申请实现。
+- Codex 在主会话审批、人工审批、允许所有及子代理控制的 `ask-request` 模式下使用 `approvalPolicy: on-request` 与 `sandbox: workspace-write`，不配置自动审查器，使真实升级请求可送审。子代理控制的 `auto` 沿用配置的原生权限模式，`full-access` 使用绕过审批的线程模式。
+- 任务面板新增权限申请与处理结果的活动条目。
+
+### 变更
+
+- **破坏性变更：** 包名由 `@local/dsh-multi-agent` 改为 `dsh-multi-agent`。插件标识、Cordis 补丁组件名、Client 模块标识、设置存储键及任务面板标签页标识随之变化。从 `0.8.x` 升级时，先备份或记录现有设置，在 DSH 插件管理器卸载旧包，再安装新版 TGZ，按管理器提示应用或重启，并核对、按需重新填写设置；不要将新旧包同时安装，也不要假定旧设置键会自动迁移。
+- 从 `0.8.x` 升级后，未改过策略的安装默认从 Kimi／agy 的 `reject` 或 Codex 的 `approve-for-me` 自动审查转为主会话审批。这是收紧交互而非放权：申请改由主会话决定；已保存的 `allow`／`reject` 值继续有效。包名迁移后仍需核对这些设置是否已恢复。
+- `0.9.0` 为首个 GitHub 发布版本；此前的 `0.8.x` 仅通过本地 TGZ 分享。发布产物为 `dist/dsh-multi-agent-0.9.0.tgz` 及 SHA-256 校验文件，作为 GitHub Release 资产提供；保持 `private: true`，不执行 `npm publish`。
+
+### 安全
+
+- 所有未决路径均采用拒绝策略（`fail-closed`）：主会话审批与交互卡片均无人应答时拒绝，主会话审批策略为 `never` 时按其语义拒绝。
+- ACP 一次授权只选择 `allow_once`；子代理未提供该选项时拒绝，绝不扩大为持续授权。持续授权仅在用户选择“始终允许”或使用 `full-access` 等级，且子代理提供 `allow_always` 时出现。
+- 拒绝 ACP 请求时优先选择子代理提供的 `reject_once`，未提供时按取消返回；运行取消后迟到的批准一律作废。
+- agy 的 `full-access` 使用原生 `--dangerously-skip-permissions`，会跳过其权限确认。批准类策略可能允许写文件和执行命令，不构成操作系统级沙箱，应仅在理解风险的受信任工作区使用。
+
+### 测试
+
+- 新增 20+ 权限场景测试，覆盖主会话审批、人工审批、允许所有、拒绝所有与子代理控制三级，以及 ACP 单次授权、拒绝回选与取消后迟到批准作废。
+- 本版发布前验证：`npm run check` 通过；`npm test` 共 361 项，360 通过、0 失败、1 项原有条件跳过。
+
+## [0.8.8]
+
+### 新增
+
+- 使用 DSH 原生右侧栏注册 Agent 任务面板，在开始页提供入口；仅为当前显示的主会话自动打开新外部任务。
+- 报告与 Markdown 文件链接使用原生文件预览，支持绝对路径、相对路径、Windows 盘符、UNC、空格和文件 URL，相对路径按子任务工作区解析。
+
+### 变更
+
+- 移除 Better Sidebar 依赖及其页面、文件调用，保留任务列表、活动流水、历史、归档、恢复、清理、续接、Token 信息和完成卡片；面板隐藏时停止相应读取。
+
+### 修复
+
+- 通过原生导航参数传递父会话、子任务及工作区，避免后台会话误开面板；使用导航修订值修复再次打开同一任务时未重新选中的问题。
+
+## [0.8.7]
+
+### 变更
+
+- 从生产依赖中移除三个 DSH Host Provider 包及 `dsh-sdk-protocol`，Cordis 改由宿主提供。
+- ACP 直接使用 `@agentclientprotocol/sdk`；Codex 使用插件内的纯 Node JSON-RPC 传输与 `@openai/codex` 原生平台包，必要辅助代码保留在插件内部。
+
+### 修复
+
+- 修复全新配置环境中旧 Host 依赖遮蔽 DSH 自带实现，导致 `subagents` 服务、标准／PTC／创造模式及会话创建失败的问题。
+
+## [0.8.6]
+
+### 变更
+
+- Codex 按“手动命令 → 检测到的原生命令 → 依赖包内原生二进制”选择，模型目录与 `app-server` 共用命令，并支持嵌套平台包解析；JavaScript 包装器兼容回退显式启用 Electron 的 Node 模式。
+- 补齐跨平台测试脚本、CRLF 源码校验与 agy 冒烟脚本的平台处理，测试入口不再依赖 POSIX 通配符展开。
+
+### 修复
+
+- 处理 Windows 大小写环境键、重复 `Path`／`PATH` 与带引号的路径目录；启动前明确拒绝 `.cmd`、`.bat`、JavaScript 和 PowerShell 启动脚本。
+- 修复 Kimi／agy 手动路径被自动检测门禁误拦、模型目录未继承 Provider 环境的问题，保留命令热更新；ACP 目录探测观察进程退出，启动失败及时返回并清理。
+- 续接工作区按真实路径及设备／文件身份比较，避免等价路径被误判；任务 Markdown 与旧完成通知支持 Windows 报告路径，同时保留危险协议与协议相对链接拦截。
+
+## [0.8.5]
+
+### 新增
+
+- 为 Codex、Kimi Code、agy 的统一设置页增加 CLI 路径输入：手动配置优先，留空或清空已保存覆盖可恢复自动检测。
+
+### 变更
+
+- 手动命令同时用于模型目录查询与实际任务；本版 Codex 缺省仍使用官方包内包装器，后续由 `0.8.6` 调整原生命令优先级。
+- 未检测到 CLI 时可通过显式路径与配置重载启用 Provider；不可用时保留 DSH 回退。
+
+## [0.8.4]
+
+### 修复
+
+- Windows CLI 检测支持分号分隔的 `PATH`、大小写不敏感环境键和原生 `.exe`／`.com` 候选，不再将 `.cmd`／`.bat` 视作可直接启动的原生程序。
+- 补充 Codex、Kimi 与 agy 的 Windows 官方安装位置检测，保留 POSIX 路径规则。
+- 三个 Provider 改为通过 Cordis 注入等待可用性服务，修复冷启动时动态禁用条件过早求值、导致组件未挂载的问题。
+
+## [0.8.3]
+
+### 修复
+
+- 将 Codex 使用的五个进程辅助函数移入插件内仅依赖 Node 的辅助模块，保留官方 `rc.1` 实现与 MIT 许可。
+- 移除 Codex 对 `subagent`、`timeout`、`brand` 入口的顶层导入，消除为辅助函数加载整套服务而引入的不必要宿主依赖链。
+
+## [0.8.2]
+
+### 新增
+
+- 补充首次安装、前置依赖、CLI 检测、费用与安全说明，提供包含预构建 Client、Host 入口、语言资源、图标及第三方声明的 npm 格式 TGZ。
+
+### 变更
+
+- 移除打包者专用的 Kimi／agy 绝对路径，改用接收者本机检测结果；基于 `0.8.1` 保留 DSH `rc.1`／`rc.2` 双版本适配。
+- Kimi／agy 新安装采用保守的 ACP `reject` 默认权限，明确报告写入可能因此被拒绝。
+- 分享包不捆绑 `node_modules`、用户配置、账户凭据、会话、任务报告、备份、开发测试或本机日志。
+
+## [0.8.0]
+
+### 新增
+
+- 任务与历史详情显示模型、思考强度及 Token 用量，区分后端确认值、请求配置与未提供数据。
+- 按后端实际返回数据展示 Token，区分任务累计、会话及本轮口径；缓存和思考 Token 明细单列，避免重复计入总数。
+- DSH 按事件序号去重真实用量，Codex 使用线程累计快照，Kimi／agy 仅在响应提供 `usage` 时显示消耗；上下文窗口占用不作为消耗。
+
+## [0.7.0]
+
+### 新增
+
+- 接入 Antigravity（agy）ACP 后端，提供独立模型、思考强度与运行配置，可通过路由规则、默认 Agent 或 `dispatch_agent` 选择。
+- 通过短暂 ACP 会话读取实际模型与支持的思考强度；续接使用 `session/load` 核验原历史，缺失能力或历史为空时拒绝，不静默新建会话。
+
+### 变更
+
+- 子任务正文改为连续消息流，相邻工具活动按顺序分组并默认折叠；与最后一条正文相同的最终结果不重复展示。
+
+## [0.6.0]
+
+### 新增
+
+- 将任务摘要、归档状态、输出及真实外部会话引用持久化到 DSH 原生存储域 `multi_agent_task_history`；重启后将未结束任务标为已中断并归档，不自动重跑。
+- 终态任务支持归档、恢复与清理；清理保留磁盘报告及底层会话，恢复标签本身不启动模型。
+- 提供面板“继续指挥”与 `continue_agent`，复用原 DSH 子会话、Codex 持久线程或 Kimi 会话；仅允许所属父会话的终态任务续接，拒绝重复并发续接及无法可靠恢复的任务。
+
+### 修复
+
+- 修复历史存储单元名称不合规范及初始化拒绝未及时捕获导致的 Host 崩溃；初始化失败时明确报错并阻止任务操作，不自动删除或重置损坏数据。
+
+## [0.5.1]
+
+### 新增
+
+- 提供按子任务区分的任务标签面板，展示任务正文与工具活动，完成通知可定位对应任务。
+- 完成通知以任务卡片展示，提供任务面板、报告及原始通知全文入口。
+- 主 Agent 可通过 `agent_tasks` 查询自己派发的任务状态与活动，查询范围限制在所属主会话。
+
+## 支持边界
+
+- DSH 仅支持 `0.2.2-rc.1`、`0.2.2-rc.2` 和 `0.2.2-rc.3`，以 `engines.dsh` 声明为准。
+- 已在 macOS 上完成构建与回归；Linux／Windows 未经实机验证，模拟 Windows 路径测试不等同于 Windows 端到端验收。
+- 外部 Agent 需自行安装相应 CLI 并登录；插件不携带模型服务或额度。
+- 真实上游契约测试使用隔离边界替身，不代表完整 `rc.2` Desktop 或所有真实 CLI 场景已验收。
+- 从 `0.8.8` 起，任务面板使用 DSH 原生右侧栏与文件预览，无需 Better Sidebar。
+
+## 链接
+
+- [0.9.3 发布页][0.9.3]
+- [0.9.2 发布页][0.9.2]
+- [0.9.1 发布页][0.9.1]
+- [0.9.0 发布页][0.9.0]
+- [Keep a Changelog]
+- [语义化版本]
+
+[0.9.3]: https://github.com/kiritoko1029/dsh-multi-agent/releases/tag/v0.9.3
+[0.9.2]: https://github.com/kiritoko1029/dsh-multi-agent/releases/tag/v0.9.2
+[0.9.1]: https://github.com/kiritoko1029/dsh-multi-agent/releases/tag/v0.9.1
+[0.9.0]: https://github.com/kiritoko1029/dsh-multi-agent/releases/tag/v0.9.0
+[Keep a Changelog]: https://keepachangelog.com/zh-CN/1.1.0/
+[语义化版本]: https://semver.org/lang/zh-CN/

package/INSTALL.zh.md

@@ -0,0 +1,99 @@
+# DSH 多 Agent 派发 0.9.3 — 安装与安全说明
+
+本项目不是 DSH 官方插件。源码与安装包发布在 [GitHub 仓库](https://github.com/kiritoko1029/dsh-multi-agent)；0.9.3 起使用 scoped npm 包 `@kiritoko1029/dsh-multi-agent`，请从 [Releases](https://github.com/kiritoko1029/dsh-multi-agent/releases) 下载 `kiritoko1029-dsh-multi-agent-0.9.3.tgz` 及其 `.sha256` 校验文件。npm 发布不改变 DSH 安装方式：仍按本文使用插件管理器，不要在 profile 目录手动执行 npm / pnpm 安装。0.9.2 及更早版本不追溯发布到 npm。
+
+0.9.3 的 Release 资产名为 `kiritoko1029-dsh-multi-agent-0.9.3.tgz`。包名同时也是插件安装身份；从旧 `dsh-multi-agent` 升级时应先备份配置并按插件管理器提示处理旧包，不要让新旧两个包同时启用。既有 0.9.2 资产名和安装方式不变。
+
+## 一、准备环境
+
+1. DSH 必须为 `0.2.2-rc.1`、`0.2.2-rc.2` 或 `0.2.2-rc.3`；其它版本未列入兼容范围，不要通过版本豁免强行安装。
+2. 在自己的 DSH 中配置可用模型。仅使用 DSH 子代理时，不需要安装外部 CLI。
+3. 需要哪个外部 Agent，就在本机安装并登录哪个 CLI：Codex、Kimi Code 或 Google Antigravity（agy）。安装这个插件不会赠送账号、模型额度，也不会带入分享者的登录。
+4. “Agent 任务”面板直接使用 DSH 原生右侧栏和文件预览，无需安装第三方侧栏插件。
+5. 安装依赖需要联网。macOS 是打包与回归验证平台；Linux / Windows 未经过实机安装和 CLI 执行验收。
+
+## 从 0.8.x 升级到 0.9.x
+
+0.9.0 有两处会影响既有安装的变化，升级前请先读：
+
+1. **包名改为 `dsh-multi-agent`**（原 `@local/dsh-multi-agent`）。插件标识、Cordis 补丁中的组件名、Client 模块标识、设置存储键和任务面板标签页标识都随之改变。新旧包不能同时安装，否则会出现两套重复的工具注册。
+2. **默认权限策略改为主会话审批**：Kimi / agy 的 `reject`、Codex 的 `approve-for-me` 自动审查，变为主会话审批。这是收紧交互而不是放权；已保存的 `allow` / `reject` 值继续有效。
+
+升级步骤：
+
+1. 记录或备份当前插件设置（模型、CLI 路径、路由规则、权限策略）。
+2. 在 DSH 插件管理器中卸载旧的 `@local/dsh-multi-agent` bundle；不要清空整个 profile，也不要删除整个 `.dsh`。
+3. 安装 Releases 中的 `kiritoko1029-dsh-multi-agent-0.9.3.tgz`，按管理器提示应用或重启 DSH。
+4. 重新核对顶栏“多 Agent 派发”面板：包名变化后旧设置键不会自动迁移，请按第 1 步的记录重新填写，再确认每个 Agent 的权限策略符合预期。
+
+若 0.8.6 曾导致标准 / PTC / 创造模式失败，0.9.0 已包含 0.8.7 的宿主依赖隔离修复，升级后完全重启 DSH 即可；不要为恢复而删除整个 `.dsh`。旧版 profile 若保留 `disabled: !!js ...` 条件覆盖，会继续绕过新版默认，升级时只清理这三个 Provider 的旧动态 disabled 覆盖，保留模型、命令、权限和其他插件设置，无需删除整份 `cordis.patch.yml`。
+
+## 二、首次安装（推荐）
+
+从 Releases 页面下载 `kiritoko1029-dsh-multi-agent-0.9.3.tgz`，需要时一并下载 `.sha256` 校验文件：在 macOS / Linux 上执行 `shasum -a 256 -c kiritoko1029-dsh-multi-agent-0.9.3.tgz.sha256` 即可核对传输完整性（该校验值不是数字签名，也不能独立证明来源可信）。TGZ 本身就是插件安装包，不需要先解开。
+
+把 TGZ 文件或它在 DSH 所在电脑上的绝对路径交给 DSH，并发送：
+
+> 请安装我提供的本地多 Agent 派发插件 TGZ。先检查我的 DSH 版本和安装包信息，再通过插件管理器安装。不要手动改 profile 文件，不要开启版本豁免，不要替我把权限策略改成 allow 或 full-access。如果需要执行依赖安装脚本，先说明具体脚本和原因。安装后核验插件状态，并按管理器返回结果告知是否需要重启。
+
+对应 DSH 工具是 `plugin_manager` 的 `install_bundle` 操作，`target` 使用本地 TGZ 的绝对路径（也支持绝对 `file:` tarball spec）。不要在 profile 目录手工执行 npm / pnpm 安装。
+
+管理器若返回需要重启，就重启 DSH；若返回已应用，仍要检查顶栏“多 Agent 派发”面板、任务面板和测试任务。仅看到磁盘文件或包版本不代表新模块已生效。
+
+**如果已安装旧包 `@local/dsh-multi-agent`：** 先备份自己的插件设置，遵循管理器的升级结果。旧版管理器可能要求先卸载再安装；不要盲目卸载、复制整个 profile 或覆盖其它插件配置。
+
+## 三、首次配置与 CLI 手动覆盖
+
+点击会话顶栏右侧的“多 Agent 派发”按钮，在面板中配置 Codex、Kimi Code、Antigravity 的“CLI 路径（留空自动检测）”：
+
+- 留空：使用本机自动检测结果。
+- 手动填写：保存后优先使用该路径。Windows 下通常填写实际 `.exe` 的绝对路径。
+- 清空并保存：删除当前用户的手动覆盖，恢复自动检测。
+- 修改后点击对应 Agent 的“重新读取模型列表”，再选择模型。
+
+Codex 的手动路径也用于实际 app-server 调用；Kimi / agy 的手动路径用于模型目录与 ACP 任务。路径指向的程序由用户选择，填错会在目录读取或任务启动时失败，不要把它当作模型配置错误。
+
+打开会话顶栏右侧的“多 Agent 派发”面板：
+
+- 先用 DSH 自身做一个小任务确认基础能力，再启用需要的外部 Agent。
+- 模型/推理强度可留空继承后端默认；只填写自己账号可用的模型。
+- 根据需要调整自然语言路由。插件会向主会话添加主动派发指引，并对部分原生新建委派工具施加工作流约束，影响当前 profile 中可使用该插件的主会话，不只是一个面板装饰。
+- Kimi / agy CLI 缺失且未手动配置时对应 Provider 不启用；Codex 可回退到依赖包内的原生二进制。向不可用外部 Agent 派发可能回退 DSH，工具回执会说明 fallback。请检查实际执行者，不要以为始终由指定外部 CLI 完成。
+
+### CLI 路径
+
+- Codex：Windows 检测 `%CODEX_INSTALL_DIR%\codex.exe`、`%LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe` 和 PATH，并可回退到依赖包内的原生 Codex；macOS/Linux 保留原常见位置。可用 `CODEX_COMMAND` 指定原生程序路径。模型目录和 app-server 使用同一选择结果。
+- Kimi：Windows 检测当前用户的 `%USERPROFILE%\.kimi-code\bin\kimi.exe`；macOS/Linux 检测 `~/.kimi-code/bin/kimi`，再搜索 PATH。可用 `KIMI_COMMAND` 指定路径。
+- agy：Windows 检测 `%LOCALAPPDATA%\agy\bin\agy.exe`；macOS/Linux 检测 `~/.local/bin/agy`，再搜索 PATH。可用 `AGY_COMMAND` 指定路径。
+
+Windows 只接受 DSH 托管进程边界可直接启动的原生程序。`.cmd` / `.bat` / `.js` / `.ps1` 等脚本或 shim 不会被当作 EXE 启动，而会在启动前提示选择原生 `.exe` / `.com`。若 PATH 中只有 npm 的 `.cmd`，Codex 会尝试依赖包内的原生二进制；Kimi / agy 仍需填写对应原生可执行文件。
+
+这些变量必须进入 **DSH 进程的启动环境**。在另一个终端里临时 export，不会改变已运行桌面进程的环境。自定义命令也可在顶栏“多 Agent 派发”面板中填写，手动路径优先于自动检测；新装 CLI 或修改环境变量后通常需要重启或重载插件。
+
+## 四、权限与费用：先读再启用
+
+- **0.9.0 起，Kimi / agy / Codex 新安装默认 `permission: main-session`（主会话审批）。** 子代理的权限申请会送到派发它的主会话：主会话轮次进行中出现原生审批面板；轮次已结束则弹出交互式审批卡片。没有人作答或服务不可用时一律拒绝（fail-closed）。
+- 五种策略按 Agent 在顶栏“多 Agent 派发”面板独立配置：`main-session`（主会话审批）、`human`（人工审批卡片）、`allow`（允许所有）、`reject`（拒绝所有，0.8.x 的 Kimi/agy 默认，旧保存值继续有效）、`subagent`（子代理控制，含 `auto` / `full-access` / `ask-request` 三个等级；agy 的 `full-access` 会追加其原生 `--dangerously-skip-permissions` 参数）。
+- **当前版本的完全权限继承例外：** 默认 `main-session` 策略会读取主会话有效权限；只有恰好为“不再询问 + 完全权限”（`never + danger-full-access`）时才自动继承，避免 Host 将自动拒绝传给子代理。Codex 使用原生完全权限线程，agy 使用原生跳过权限参数，Kimi 自动允许其 ACP 权限申请。其他组合仍走原审批链，用户主动拒绝继续拒绝；显式选择 `human` 等其他策略时不触发继承。
+- 批准操作可能允许写文件、执行命令及访问 CLI 自身可访问的内容。这些策略**都不是操作系统级沙箱**，也不保证 CLI 的所有行为都会请求权限。敏感工作应使用独立工作目录、容器或其它隔离方式。
+- Codex 在主会话审批 / 人工审批 / 允许所有策略下以 on-request 线程运行（workspace-write 沙箱、无自动审查器），真实升级请求才会到达送审；继承上述完全权限组合时改用原生 `danger-full-access` 线程；拒绝所有与子代理控制 `auto` 沿用其 `permissionMode`（默认 `approve-for-me` 自动审查）。
+- DSH、Codex、Kimi、agy 使用各自的模型配置、登录和计费。多个 Agent 并行可能同时消耗额度。
+- 除上述默认策略下的明确完全权限组合外，父 DSH 的权限设置不等于所有外部 CLI 自动继承相同权限。安装本插件本身不代表授予所有后续操作无限权限；只有主会话有效组合和 Agent 策略同时满足上述条件才继承。
+
+本包不包含分享者的账号、密钥、会话历史、任务报告、备份或 node_modules。首次安装仍会从配置的包仓库下载 npm 依赖；它不是离线全依赖包。
+
+## 五、安装后检查
+
+1. 插件管理器未显示加载失败；会话顶栏右侧出现“多 Agent 派发”按钮，面板可打开。
+2. 在 DSH 原生右侧栏的开始页打开“Agent 任务”，或在新任务派发后查看自动打开的页面。
+3. 给 DSH 一个小型只读分析任务，确认派发回执、最终通知和任务状态一致。
+4. 按需测试已登录的外部 CLI。若需要写报告，应事先选择自己接受的权限策略，不要为了测试直接关闭所有安全限制。
+5. 测试已完成任务的续接，确认沿用原任务，而不是创建另一份会话。
+
+## 六、兼容性与数据提醒
+
+插件沿用 rc.1 / rc.2 双版本兼容层，测试覆盖两版接口及官方固定源码的隔离契约。**这不等于在所有系统、CLI 版本和桌面窗口尺寸上完成了端到端验收；rc.2 桌面完整验收仍有限制。**
+
+DSH rc.2 创建具名子代理后可能写入 rc.1 无法读取的会话记录。升级 DSH 前备份自己的会话存储，不要让两版进程同时读写同一份存储，也不要直接在新版记录上降级。
+
+本项目自有代码以 [MIT 许可证](LICENSE) 发布。第三方版权与许可证见 `THIRD_PARTY_NOTICES.md`；`acp-provider.js`、`lib/codex-run.js`、`lib/provider-process-contract.js`、`lib/dsh-model.js` 和 `lib/json-rpc-line-transport.js` 包含改编自 DeepSeek Harness 的 MIT 代码，其原始声明保留在对应文件内。

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Jerry Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project adapts MIT-licensed code from DeepSeek Harness. The retained
+upstream notices are listed in THIRD_PARTY_NOTICES.md and inside the adapted
+source files.

package/PUBLISHING.md

@@ -0,0 +1,60 @@
+# 发布维护
+
+本文只面向仓库维护者。DSH 用户的安装与配置请阅读 [README.md](README.md) 和 [INSTALL.zh.md](INSTALL.zh.md)，版本变更只记录在 [CHANGELOG.md](CHANGELOG.md)。
+
+## npm Trusted Publisher
+
+npm 包为 [`@kiritoko1029/dsh-multi-agent`](https://www.npmjs.com/package/@kiritoko1029/dsh-multi-agent)。在 npm 包的 **Settings → Trusted publishing** 中配置 GitHub Actions：
+
+- Repository owner：`kiritoko1029`
+- Repository name：`dsh-multi-agent`
+- Workflow filename：`release.yml`
+- Environment：留空；工作流当前未使用 GitHub Environment
+
+发布工作流通过 GitHub OIDC 换取 npm 短期凭证，不配置 `NPM_TOKEN`，也不在仓库、workflow 日志或插件配置中保存长期 npm 令牌。`publish-npm` 任务显式安装 npm `11.20.0`，满足 Trusted Publishing 所需的 npm 11.5.1+，并使用包含后续修复的 11.x 版本。
+
+`0.9.3-stage.0` 仅用于建立 npm 包与 Trusted Publisher 的引导关系。它是预发布版本，不是稳定插件发行版，也不应作为稳定安装来源。
+
+## 正常发布步骤
+
+1. 更新 `package.json` 的版本和 `CHANGELOG.md` 的对应版本段落。
+2. 运行语法检查、完整测试、Client 构建和 `release:pack`，检查生成的 TGZ 与 SHA-256。
+3. 提交并推送 `main`，确认 CI 成功后创建并推送对应的 `vX.Y.Z` 标签。
+4. 等待 `.github/workflows/release.yml` 中的 `release` 与 `publish-npm` 两个任务完成，并检查 GitHub Release 和 npm registry 中的版本。
+
+普通 `main` 提交、本地安装、手动 `npm pack` 都不会发布 npm。只有版本标签会触发该工作流。
+
+## 工作流与产物校验
+
+`release` 任务依次执行依赖安装、语法检查、完整测试、标签版本核对、Client 构建和 TGZ / SHA-256 构建，随后创建 GitHub Release。`scripts/build-release.mjs` 同时把本次构建产物的 SHA-256 写入 GitHub Actions step output，由 `release` job output 传给 npm 任务。
+
+`publish-npm` 任务使用最小权限 `contents: read` 与 `id-token: write`，从刚创建的 GitHub Release 下载 TGZ 和校验侧车。`scripts/publish-npm.mjs` 在发布前验证：
+
+- 标签版本、checkout 的 `package.json` 与 TGZ 内 `package/package.json` 的名称和版本一致；
+- 包不是 private，目标 registry 为 `https://registry.npmjs.org/`，访问级别为 public；
+- checkout 与 TGZ 的 repository 均属于触发工作流的 GitHub 仓库；
+- `dist` 中只有预期 TGZ 和同名 `.sha256`，TGZ 的实际 SHA-256 与 Release 构建 job output 一致；
+- 侧车只包含该精确 TGZ 的一条有效 SHA-256 记录；
+- 本地 TGZ 计算出用于发布前后比对的 SHA-512 `dist.integrity`。
+
+校验通过后，脚本只发布这个精确文件，不使用 TGZ 通配符：
+
+```sh
+npm publish <精确TGZ> --access public --provenance --registry=https://registry.npmjs.org/
+```
+
+## 重试与故障恢复
+
+- 发布前发现同版本且 integrity 相同：视为已完成，跳过重复发布。
+- 发布前发现同版本但 integrity 不同：拒绝发布，不能覆盖 npm 中已有内容。
+- `npm publish` 返回错误：继续执行有界 registry 查询；若版本实际已接收且 integrity 一致，则恢复成功，避免重跑时重复发布。
+- 发布后 registry 暂时不可见或查询失败：在限定次数内重试，不把网络错误当成“包不存在”。
+- 发布后 integrity 不同或最终无法确认：任务失败，不报告发布成功。
+
+Trusted Publisher、OIDC 或仓库绑定配置错误时，GitHub Release 可能已经创建，但 npm 发布会失败。修正配置后在原工作流运行中选择 **Re-run failed jobs**，不要重复创建同一标签或版本，也不要删除 Release 来掩盖失败。
+
+## 分发边界
+
+0.9.3 起包名为 `@kiritoko1029/dsh-multi-agent`，`npm pack` 生成的 Release 资产名为 `kiritoko1029-dsh-multi-agent-<version>.tgz`。既有 0.9.2 的 `dsh-multi-agent-0.9.2.tgz` 资产名不变。
+
+0.9.2 及更早版本保持原有 GitHub Release 分发，不追溯发布到 npm。npm 发布不改变 DSH 安装方式：用户仍通过插件管理器安装 TGZ，不在 profile 目录手动执行 npm / pnpm 安装。