diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 83c0ceb8..24618fe8 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,9 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +- Document the owned Bash restriction boundary and publication switch (#380), + provider tool-change error ownership (#367), and scoped discovery troubleshooting (#346). +- 说明 Bash 自有工具的掩码边界与发布开关、提供商工具变更错误的职责边界及 discovery 作用域排查方法。 - Add macOS Intel (`darwin-x64`) as a first-class native target on macOS 13+: accept it in the resolver and profile commands, declare it in every component row, ship its Mach-O worker with a receipt, and add a non-blocking `macos-15-intel` CI leg plus the fourth release artifact. The Intel leg measured 318 s, so it follows the >300 s non-blocking rule. macOS 12 is not part of this support: its kernel lacks `CLONE_ACL`, so the write path fails closed; that fallback is a separate follow-up. See [macOS](macos.md). - 将 macOS Intel（`darwin-x64`）作为 macOS 13+ 的一等原生目标：解析器与 profile 命令接受它，所有组件行声明它，发布其 Mach-O worker 与收据，并新增非阻塞的 `macos-15-intel` CI leg 与第四个发布 artifact。Intel leg 实测 318 秒，因此按 >300 秒规则作为非阻塞信号。macOS 12 不在本次支持范围内：其内核缺少 `CLONE_ACL`，写路径会 fail closed；该回退是独立后续项。说明见 [macOS](macos.zh.md)。 - Declare DSH 0.2.0-rc.2 and 0.2.1-rc.2 consistently in engines/peers, export every diff --git a/docs/host-integration.md b/docs/host-integration.md new file mode 100644 index 00000000..4ddb6828 --- /dev/null +++ b/docs/host-integration.md @@ -0,0 +1,102 @@ +# Host integration troubleshooting + +English | [中文](宿主集成.md) + +These checks separate plugin configuration from host presentation and provider +transport failures. They do not establish that an unobserved Desktop freeze or +an old conversation has been repaired. + +## A whitelist does not hide `ops_bash` (#380) + +In the pinned DSH tools API, `tools.restrict()` masks inherited registrations. +An agent's own registrations are resolved separately. OPS publishes Bash in the +agent's scope so its definition follows that session's authority and services; +an inherited-tool whitelist therefore cannot be assumed to remove `ops_bash`. +The fact that the same whitelist hides a globally registered file tool does not +prove it also hides the session's shell. A read-only sandbox is also a filesystem +permission mode, not a promise that every command tool is absent. + +To stop OPS Bash publication, set `publishBashTool: false` in its owning shell +row. Merge this setting into the existing config, preserving other keys: + +```yaml +- id: dsh-ops-shell + name: dsh-ops/shell + config: + publishBashTool: false +``` + +Check every `dsh-ops/shell` row in the effective configuration: another enabled +row can still publish its own tool. Apply the change through the host settings +or profile lifecycle, then verify a new session's tool list. This switch controls +OPS Bash; it does not disable independently installed command tools. + +Per-preset command denial requires a host execution policy that covers owned +tools, or a verified scoped mounting arrangement. Merely moving a shell row into +a preset is not established as an isolation guarantee: the component also +enumerates already live agents when mounted. Before relying on such an arrangement, +verify both allowed and disallowed presets, existing and newly created sessions, +and actual invocation rejection. OPS does not rewrite the shared tool registry +to make inherited restrictions act on owned tools. + +## A provider rejects `tool_addition` in an old conversation (#367) + +OPS publishes tool definitions through the host registry. DSH records changes +to the available tool set and serializes provider messages; OPS does not construct +`tool_addition` blocks or choose their wire-message roles. The reported +`tool_addition blocks can only be in system messages` error is therefore a +host/provider serialization boundary, even when an OPS discovery change triggers it. + +For a bounded diagnostic, choose the intended configuration before creating a +fresh session, then keep the tool set stable during that run. Configure any +`alwaysLoaded` discovery capabilities before session creation and avoid changing +selections or component settings mid-conversation. Disabling discovery removes +that progressive-publication trigger but also removes access to capabilities +that were available only through discovery. This does not repair retained history +or guarantee compatibility with every provider. + +If the rejection persists, retain the exact host/plugin versions, provider/model, +request ID, added/removed tool names, and the smallest redacted message-role +fragment that demonstrates the invalid block. The host/provider adapter needs +that evidence; changing OPS tool names or editing historical message roles is +not a plugin-side serializer fix. [Issue #367](https://github.com/T-Auto/dsh-ops/issues/367) +tracks the reported trigger. + +## `ops_discover_tools` is missing (#346) + +First inspect the profile actually used by the application, using its own CLI. +Desktop uses its bundled CLI; the ordinary CLI does not manage the reserved +Desktop profile. For a non-Desktop test profile: + +```console +dsh plugin --profile ops-test add dsh-ops@latest +dsh --profile ops-test --dump-config +dsh --profile ops-test --dump-config-schema +``` + +Replace `@latest` with the intended version or packed checkout when testing an +unpublished fix. Put `--profile` before `add` and package-manager arguments. The +effective configuration should contain an enabled `dsh-ops-discovery` row named +`dsh-ops/discovery`, with `enabled: true`. Inspect saved overrides and duplicate +rows before adding another row. A stale profile missing discovery is a different +case from an enabled row whose publication stalls. + +Presentation matters: ordinary Native scopes use `ops_discover_tools`; PTC scopes +use the PTC SDK loader under the host's `run_code` presentation. Check the scoped +assembled tools and presentation, not just a global registry or a prompt section +name. An empty discovery section alone does not identify the cause. + +Host support declarations and component resource exports are addressed in +[PR #395](https://github.com/T-Auto/dsh-ops/pull/395), with explicit 0.2.0-rc.2 and +0.2.1-rc.2 coverage. The text-only PTC hook adaptation in +[PR #390](https://github.com/T-Auto/dsh-ops/pull/390) is not full 0.2.1-rc.3 support. +[PR #383](https://github.com/T-Auto/dsh-ops/pull/383) and #390 address unnecessary +session work and append-time Bash publication. Check whether the installed version +actually contains these changes before attributing its behavior to them. + +The original #346 report also describes an enabled row and a stalled publication +chain. The profile checks above do not prove that failure fixed. If the row is +enabled and the expected scoped tool remains absent, capture a minimal profile, +exact versions, Native/PTC mode, affected scoped schemas, and a timed lifecycle +trace showing the pending publication. Restart/new-session results are useful +comparisons, not proof that an indefinite hot-mount stall cannot recur. diff --git a/docs/usage.md b/docs/usage.md index 7c6ff9e5..86ab5c9b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -143,6 +143,9 @@ the resulting warning fails the gate. ## Update +For inherited whitelist limits, missing discovery rows and provider tool-change +errors, see [host integration troubleshooting](host-integration.md). + Repeat the same `npx --yes dsh-ops@latest install --profile ...` command, or use the official CLI's `add dsh-ops@latest`. Reload as requested by the application; restart it when replacing already-loaded code. --- diff --git "a/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" "b/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" index 76ade4b0..ad68fc8a 100644 --- "a/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" +++ "b/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" @@ -124,6 +124,8 @@ CI 清单校验使用同一个公开宿主 patch 合成器，将跳过 override ## 更新 +继承白名单限制、缺少 discovery 行及提供商工具变更错误，见[宿主集成排查](宿主集成.md)。 + 重新运行相同的 `npx --yes dsh-ops@latest install --profile ...`，或用官方 CLI `add dsh-ops@latest`。按应用提示重载；替换已加载代码时重启应用。 --- diff --git "a/docs/\345\256\277\344\270\273\351\233\206\346\210\220.md" "b/docs/\345\256\277\344\270\273\351\233\206\346\210\220.md" new file mode 100644 index 00000000..e49b4ea9 --- /dev/null +++ "b/docs/\345\256\277\344\270\273\351\233\206\346\210\220.md" @@ -0,0 +1,80 @@ +# 宿主集成排查 + +[English](host-integration.md) | 中文 + +以下检查区分插件配置、宿主展示与提供商传输问题，不代表已修复未复现的 Desktop 卡死， +也不代表已修复旧会话的历史记录。 + +## 白名单无法隐藏 `ops_bash`（#380） + +固定版本的 DSH tools API 中，`tools.restrict()` 只遮蔽继承的注册项，agent 自有注册项 +单独解析。OPS 在 agent 作用域发布 Bash，使定义跟随该会话的权限与服务。因此不能认为 +继承工具白名单也会移除 `ops_bash`。同一白名单能隐藏全局注册的文件工具，并不能证明它 +能隐藏会话自身的 shell。只读沙箱也是文件系统权限模式，不承诺命令工具全部不可见。 + +要停止 OPS Bash 发布，在拥有它的 shell 行设置 `publishBashTool: false`。 +把该字段合并进已有配置，保留其他键： + +```yaml +- id: dsh-ops-shell + name: dsh-ops/shell + config: + publishBashTool: false +``` + +检查有效配置中的所有 `dsh-ops/shell` 行：另一条启用的行仍可能发布自己的工具。 +通过宿主设置或 profile 生命周期应用变更，再验证新会话的工具清单。该开关只控制 OPS +Bash，不会禁用其他独立安装的命令工具。 + +按 preset 禁止命令，需要能覆盖自有工具的宿主执行策略，或经过验证的作用域挂载方案。 +仅把 shell 行移入某个 preset，尚不能作为隔离保证：组件挂载时也会枚举已存活的 agent。 +依赖此方案前，应验证允许与禁止的 preset、已有与新建会话，以及实际调用被拒绝的结果。 +OPS 不会改写共享工具注册表，让继承掩码强行作用于自有工具。 + +## 提供商拒绝旧会话中的 `tool_addition`（#367） + +OPS 通过宿主注册表发布工具定义；DSH 记录工具集变化并序列化提供商消息。OPS 不构造 +`tool_addition` 块，也不选择它在线路消息中的角色。因此，报告中的 +`tool_addition blocks can only be in system messages` 属于宿主/提供商序列化边界， +即使触发条件是一次 OPS discovery 工具变化。 + +进行有限诊断时，先确定配置，再新建会话，并在该次运行中保持工具集稳定。需要的 +`alwaysLoaded` discovery 能力应在创建会话前配置，运行中避免修改选择或组件设置。 +禁用 discovery 可以去掉该渐进发布触发器，但也会失去只能通过 discovery 获得的能力。 +这不会修复保留的历史，也不保证适配所有提供商。 + +若仍被拒绝，保留准确的宿主/插件版本、提供商/模型、request ID、新增/移除工具名， +以及能展示错误块的最小脱敏消息角色片段。宿主/提供商适配器需要这些证据；改 OPS 工具名 +或修改历史消息角色，不是插件侧序列化修复。 +[议题 #367](https://github.com/T-Auto/dsh-ops/issues/367) 记录了该触发场景。 + +## 缺少 `ops_discover_tools`（#346） + +先用应用自己的 CLI 检查它实际使用的 profile。Desktop 使用自带 CLI；普通 CLI 不能管理 +保留的 Desktop profile。非 Desktop 测试 profile 的示例： + +```console +dsh plugin --profile ops-test add dsh-ops@latest +dsh --profile ops-test --dump-config +dsh --profile ops-test --dump-config-schema +``` + +验证未发布修复时，将 `@latest` 换成目标版本或本地打包产物。把 `--profile` 放在 `add` +及包管理器参数之前。有效配置中应有启用的 `dsh-ops-discovery` 行，名称为 +`dsh-ops/discovery`，且 `enabled: true`。先检查已保存的 override 与重复行，再决定是否 +补行。旧 profile 缺少 discovery，与启用的行发生发布停滞，是不同问题。 + +展示模式也影响工具：普通 Native 作用域使用 `ops_discover_tools`；PTC 作用域通过宿主 +`run_code` 展示使用 PTC SDK loader。应检查具体作用域的装配工具和展示模式，不只查看 +全局注册表或提示词段名称。discovery 段为空本身不足以确定原因。 + +[PR #395](https://github.com/T-Auto/dsh-ops/pull/395) 处理宿主兼容声明与组件资源导出， +明确覆盖 0.2.0-rc.2 和 0.2.1-rc.2。 +[PR #390](https://github.com/T-Auto/dsh-ops/pull/390) 的纯文本 PTC hook 适配不代表完整 +支持 0.2.1-rc.3。[PR #383](https://github.com/T-Auto/dsh-ops/pull/383) 与 #390 处理会话 +重复工作及 append 期间 Bash 发布问题。判断行为前，先确认安装版本确实包含这些改动。 + +#346 原始报告也包含“行已启用，但发布链停滞”的情况，上述 profile 检查不能证明它已被 +修复。若行已启用而预期的作用域工具仍缺失，应提供最小 profile、准确版本、Native/PTC +模式、受影响作用域的 schemas，以及带时间信息的生命周期轨迹以定位尚未完成的发布。 +重启/新建会话结果可用于比较，但不能证明无限热挂载停滞不会再次发生。