From baaacbf3798ae54ce6afa51faa0040629c0ee2cc Mon Sep 17 00:00:00 2001 From: Shen Haoming <167516473+Haoming9527@users.noreply.github.com> Date: Sun, 25 Oct 2026 00:42:22 +0800 Subject: [PATCH] docs: explain host tool scope and discovery failure boundaries --- docs/CHANGELOG.md | 4 + docs/host-integration.md | 102 ++++++++++++++++++ docs/usage.md | 3 + ...77\347\224\250\346\214\207\345\215\227.md" | 2 + ...77\344\270\273\351\233\206\346\210\220.md" | 80 ++++++++++++++ 5 files changed, 191 insertions(+) create mode 100644 docs/host-integration.md create mode 100644 "docs/\345\256\277\344\270\273\351\233\206\346\210\220.md" diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index ecde18e1..d0557351 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,10 @@ 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 作用域排查方法。 + - Stop `dsh-ops-hide-official` from blocking a `run_code` (PTC) scope when `replaceTools` is set. That scope presents one program entry, and the selected counterparts are SDK functions rather than owned native providers, so readiness could never be proven and every PTC session failed prompt assembly with `READINESS_BLOCKED` as soon as one tool was selected. Readiness is now judged on the assembled surface: a scope that really kept a selected official tool still fails closed, while a collapsed scope's transport is not gated and the selected official names stay refused there. - 修复 `dsh-ops-hide-official` 在设置 `replaceTools` 后阻塞 `run_code`（PTC）作用域的问题。该作用域只呈现一个程序入口，所选替代工具是 SDK 函数而非已拥有的 native provider，就绪状态永远无法成立，只要选择了一项工具，每个 PTC 会话的提示词组装都会以 `READINESS_BLOCKED` 失败。现在改以装配出的表面判定：真正保留了所选官方工具的作用域仍然失败闭合；折叠作用域的 transport 不再被门禁阻塞，所选官方工具在该作用域内仍被拒绝。 - Make the Windows CI leg non-blocking while keeping it running on every event (#316): split `validate` into blocking `validate-posix` (Linux x64, macOS arm64) and `continue-on-error` `validate-windows`, and keep `ci-required` from depending on any `continue-on-error` job, so the aggregate neither waits for nor fails with the slowest leg. On `main` after #307 the Windows leg takes 527 / 529 s — up from 482 s before #307, because `npm ci` now downloads the 411 MB Windows Bash payload — against 136–139 s (Linux) and 168–182 s (macOS). `scripts/check-workflows.mjs` now enforces "every blocking job in the aggregate, no non-blocking job in it" and that the aggregate's failure loop names exactly the blocking jobs, so a job cannot stay in `needs` but escape judgement; the Windows result is a signal to act on, not a merge gate. 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 cced155a..a6a03f0f 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -102,6 +102,9 @@ The ordinary DSH CLI cannot manage the reserved `desktop` profile; do not confus ## 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 b82fdafb..3a15ee87 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" @@ -92,6 +92,8 @@ dsh plugin --profile dsh-tui add dsh-ops ## 更新 +继承白名单限制、缺少 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，以及带时间信息的生命周期轨迹以定位尚未完成的发布。 +重启/新建会话结果可用于比较，但不能证明无限热挂载停滞不会再次发生。