tianshu-mcp 0.7.8 → 0.7.10

package/CHANGELOG.en.md

@@ -60,6 +60,88 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.7.10] - 2026-10-06
+
+### Fixed
+
+- **Precise semantics for the visual content-egress gate (issue #29)**: with `allowRemote` defaulting to
+  `false`, `<image:base64:file>` is rejected by the schema, while `<image:path>` / `<expect:file>` are
+  unconstrained — and the docs implied the contract layer blocked *every* way of handing an image to a
+  command, leading readers to believe the channels were sealed. Probes and counter-evidence show that
+  **gating the path channel yields zero security**: the judgement command runs with `shell:false` inside the
+  **project directory** and can already read project files itself; forcing an opt-in would also make users
+  set `allowRemote` just to pass the schema, which **opens up the inline base64 channel too**. This release
+  therefore does not change the gate — it states the boundary precisely and makes the channels visible.
+
+### Changed
+
+- **New `contentChannelUsage()` (`src/visual/schema.ts`) as the single source of channel semantics**: the
+  gate check and the doctor/probe display share the same logic, so the two cannot drift apart.
+- **`visual doctor` now reports each rule's actually-used placeholder channels and whether they are
+  constrained** (`GATED` / `NOT gated`) — surfacing what the command really receives (absence never raises
+  an alarm by itself).
+- **`visual content probe` output gains `egressConstrained` / `pathChannels`** for programmatic checks.
+- Wording synced across `SECURITY.md` / `SECURITY.en.md`, `docs/visual-acceptance.md` / `.en.md`, and
+  `skills/tianshu-mcp/SKILL.md`: `allowRemote` constrains **only** the inline-byte shape, and the contract
+  layer is **not** a complete block on image egress.
+- `<expect:file>` nature clarified: it delivers a temp file holding the **expectation text** and is **not**
+  an image-egress channel (the issue conflated the two).
+
+### Verification
+
+- 5 new channel/admission contract tests (`test/unit/visual-content-schema.test.ts`), 2 doctor
+  channel-semantics tests (`test/unit/visual-runtime.test.ts`), plus the probe field assertion.
+- Counter-evidence probe: the command read a project file with **zero placeholders**
+  (`READ 4187 bytes with zero placeholders`), proving gating the path channel has no benefit.
+- Full `npm test` **1582 passed / 12 skipped, 0 failed**; `typecheck` / `lint` / `build` / `pack:check` /
+  `check:stdio` all green.
+
+---
+
+## [0.7.9] - 2026-10-06
+
+### Fixed
+
+- **Dead link to `docs/agent-profiles.md` inside the npm package**: three places in the README (including
+  the top navigation "Agent Profiles" entry) point at that document, but it was missing from the
+  `package.json` `files` allowlist — users installing from npm hit a 404. Both `docs/agent-profiles.md`
+  and `.en.md` are now included. **This defect predates 0.7.8; it was not introduced by it.**
+
+### Docs
+
+- **Completed the documentation surface for the MiniMax Code adapter**: 0.7.8 shipped the full
+  `src/agents/minimax/` implementation and `docs/minimax-cdp.md`, but **the other documents that describe
+  agents were not synchronised** — this release fills in 4 files and 23 places:
+  - `README.md` / `README.en.md` (5 each): the agent banner, the `continue_task` resume-semantics list,
+    a new `minimax` row in the agent capability table, the `reasoningLevel` validation footnote, and the
+    version-history table.
+  - `docs/agent-profiles.md` / `.en.md` (4 each): the `adapter` enum comment, the `driver=gui` table's
+    agent list (**which had also been missing qoder / opendesign**), cross-document links, and a new
+    complete `minimax` profile example section.
+  - `skills/tianshu-mcp/SKILL.md` (35): the header `description` and `triggers` (**without which the skill
+    cannot be keyword-triggered**), the tool-surface `continue_task` support list, a new 8th column and a
+    `contextWindow` row in the §3.1 parameter matrix, a new minimax subsection in §3.2, the §3.3 platform
+    status, all six `needsUserKind` rows plus the anchor field in the §5 resume matrix, and minimax
+    semantics for six error codes in §9.
+  - `skills/tianshu-mcp/usage-examples.md` (9): a new §2.9 minimax example (including a **candidate table
+    for all four measured model shapes**), renumbering of the `codex-cli` section (**fixing a duplicate
+    `### 2.10` in the original**), a `contextWindow` row in the parameter-rejection table, and updates to
+    the `autoFixRounds` defaults and the session-anchor field table.
+
+  Every concrete assertion in these docs was **verified against the source** rather than recalled, and the
+  behavioural differences were exercised with a real probe:
+  `defaultAutoFixRounds=2` / `cdpPort=9999` / `permissionMode=始终授权` / the platform status check live in
+  `src/agents/minimax/profile.ts`; `contextWindow` is minimax-only per `src/mcp/handlers.ts:476`;
+  and **minimax is the only adapter that accepts `中`/`medium`** — it accepts `极高`/`最大` but
+  **rejects `关闭思考`** (confirmed by probe).
+
+### Changed
+
+- Version `0.7.8` → `0.7.9` (`package.json` and `src/version.generated.ts`).
+  This release contains **no logic changes** — documentation and the packaging allowlist only.
+
+---
+
 ## [0.7.8] - 2026-10-06
 
 ### Added

package/CHANGELOG.md

@@ -58,6 +58,75 @@
 
 ---
 
+## [0.7.10] - 2026-10-06
+
+### 修复
+
+- **视觉内容判定的外发闸门语义精确化（issue #29）**：`allowRemote` 默认 `false` 时，
+  `<image:base64:file>` 被 schema 拒绝，但 `<image:path>` / `<expect:file>` 不受任何约束——
+  文档措辞又暗示「契约层封死了所有把图交给命令的形态」，读者会以为通道已被堵死。
+  经探针实测与反证（见下），**门控路径通道零安全收益**：判定命令以 `shell:false` 在**项目目录内**
+  执行，本就能自读项目内文件；且强制放行会因「必须开 `allowRemote` 才能过 schema」而**反向连带
+  放行 base64 内联**。故本版不改门控、只把边界说清并把通道可见化。
+
+### 变更
+
+- **新增 `contentChannelUsage()`（`src/visual/schema.ts`）作为通道语义的单一来源**：
+  门控判定与 doctor/probe 展示共用同一段逻辑，避免两处实现分叉。
+- **`visual doctor` 逐规则输出实际使用的占位符通道与是否受约束**（`GATED` / `NOT gated`）——
+  把「命令实际拿到什么」摆到台面（缺席不会自己报警）。
+- **`visual content probe` 输出新增 `egressConstrained` / `pathChannels` 字段**，便于调用方可编程核对。
+- `SECURITY.md` / `SECURITY.en.md`、`docs/visual-acceptance.md` / `.en.md`、`skills/tianshu-mcp/SKILL.md`
+  同步措辞：明确 `allowRemote` **只**约束内联字节形态，契约层**不是**对图片外发的完备拦截。
+- `<expect:file>` 性质澄清：它交付的是**期望文本**临时文件，**不是图片外发通道**（issue 原文在此处有误归并）。
+
+### 验证
+
+- 新增 5 个 `contentChannelUsage` / 准入边界契约用例（`test/unit/visual-content-schema.test.ts`），
+  2 个 doctor 通道语义用例（`test/unit/visual-runtime.test.ts`），probe 字段断言同步。
+- 反证探针实测：命令在**零占位符**下即读到项目内文件字节（`READ 4187 bytes with zero placeholders`），
+  证明门控路径通道无收益。
+- 全量 `npm test` **1582 passed / 12 skipped，0 失败**；`typecheck` / `lint` / `build` / `pack:check` /
+  `check:stdio` 全绿。
+
+---
+
+## [0.7.9] - 2026-10-06
+
+### 修复
+
+- **npm 包内 `docs/agent-profiles.md` 死链**：README 有 3 处（含顶部导航「Agent 配置」）指向该文档，
+  但它不在 `package.json` 的 `files` 白名单里——从 npm 安装的用户点进去是 404。
+  已补 `docs/agent-profiles.md` 与 `.en.md`。**这是 0.7.8 之前就存在的缺陷，不是 0.7.8 引入的。**
+
+### 文档
+
+- **补全 MiniMax Code 适配的文档面**：0.7.8 发布了 `src/agents/minimax/` 全套实现与
+  `docs/minimax-cdp.md`，但**其它描述 agent 的文档面没同步**——本轮补齐 4 个文件共 23 处：
+  - `README.md` / `README.en.md`（各 5 处）：Agent 横幅、`continue_task` 恢复语义列表、
+    agent 能力表新增 `minimax` 行、`reasoningLevel` 校验规则脚注、版本线历史表。
+  - `docs/agent-profiles.md` / `.en.md`（各 4 处）：`adapter` 枚举注释、`driver=gui` 表格的
+    agent 列表（**此前连 qoder / opendesign 也漏了**）、文档互链、新增完整 `minimax` profile 示例段。
+  - `skills/tianshu-mcp/SKILL.md`（35 处）：头部 `description` 与 `triggers`（**否则关键词触发不到该技能**）、
+    工具面 `continue_task` 支持列表、§3.1 参数兼容矩阵新增第 8 列与 `contextWindow` 行、
+    §3.2 新增 minimax 小节、§3.3 平台状态、§5 恢复矩阵六类 `needsUserKind` 与锚点字段、
+    §9 六条错误码补 minimax 语义。
+  - `skills/tianshu-mcp/usage-examples.md`（9 处）：新增 §2.9 minimax 完整示例（含**四种模型形态的
+    候选对照表**）、`codex-cli` 小节顺延（**修掉原文重复的两个 `### 2.10`**）、参数拒绝表补 `contextWindow`、
+    `autoFixRounds` 缺省与会话锚点字段表。
+
+  文档里的具体断言均**回源码核验**而非凭记忆，并对其中的行为差异跑了实测：
+  `defaultAutoFixRounds=2` / `cdpPort=9999` / `permissionMode=始终授权` / 平台状态判定见
+  `src/agents/minimax/profile.ts`；`contextWindow` 仅 minimax 见 `src/mcp/handlers.ts:476`；
+  **minimax 是唯一接受 `中`/`medium` 的适配器**，接受 `极高`/`最大` 但**拒绝 `关闭思考`**（实测确认）。
+
+### 变更
+
+- 版本号 `0.7.8` → `0.7.9`（`package.json` 与 `src/version.generated.ts`）。
+  本版**无代码逻辑变更**，仅文档与打包白名单。
+
+---
+
 ## [0.7.8] - 2026-10-06
 
 ### 新增

package/README.en.md

@@ -63,7 +63,7 @@ Tianshu (TUI × GUI)              ← commander / user surface / verdict
               ↓  MCP over stdio (stdout carries JSON-RPC only)
         tianshu-mcp              ← scheduling · execution surface · acceptance gate
               ↓
-Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design
+Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design · MiniMax Code
               ↓ (GUI driven over CDP; CLI via child process)
         target project workspace ← git repo + tests + .tianshu-mcp/
 ```
@@ -227,7 +227,7 @@ run_task(projectPath=D:/xxx/my-app, task="…task brief…", agentId=codex,
 | Tool | Capability / approval | Purpose |
 |---|---|---|
 | `run_task` | write + approval | Dispatch work (optionally with auto-verify / auto-rework), returning a `taskId` asynchronously; optional `idempotencyKey`, `acceptanceOverride` and `dryRun` |
-| `continue_task` | write + approval | Resume a `needs_user` session (ZCode / Codex / Kimi Code / Qoder CN each have their own resume semantics) |
+| `continue_task` | write + approval | Resume a `needs_user` session (ZCode / Codex / Kimi Code / Qoder CN / MiniMax Code each have their own resume semantics) |
 | `query_task` | read | Poll status / progress / log tail / recent fine-grained events (optional `eventLimit`) |
 | `list_tasks` | read | Filtered list of historical tasks |
 | `get_task_report` | read | Full text of one round's acceptance report (`report.md`) |
@@ -256,9 +256,10 @@ run_task(projectPath=D:/xxx/my-app, task="…task brief…", agentId=codex,
 | `kimicode` | `gui` / `kimicode-gui` | **ready** (`research` on macOS) | Kimi Code desktop (Electron); **dual renderer processes** (main window plus a `Kimi Browser Overlay` that hosts the model / reasoning / mode menus); workspaces bind by full path; supports `model` / `reasoningLevel`, **not `mode`**, and **not project-less dispatch** |
 | `qoder` | `gui` / `qoder-gui` | closed-loop verified on Windows; **research** on macOS | Qoder CN only; requires an existing `projectPath` and a readable `planDoc`; `modelSource=default\|custom` disambiguates same-named models, and the reasoning level is saved as a global preference via "Model management" and read back |
 | `opendesign` | `gui` / `opendesign-gui` | **ready** (`research` on macOS) | Open Design desktop GUI; selectors are taken from the product's own web-frontend `data-testid` hooks, the full 12-step execution chain is wired, and the acceptance → auto-rework → re-acceptance loop is connected; it is the only driver with an "artifact signal" (file mtime / size fingerprint) |
+| `minimax` | `gui` / `minimax-gui` | **ready** (`research` on macOS) | MiniMax Code desktop (Electron); **dual renderer processes** (main window plus a `Model menu` popup); the reasoning level / context window live in a **second-level submenu that only appears on hovering a model row**, and their **candidate sets vary per model** (requesting them on a submenu-less model is fail-closed); supports `model` / `reasoningLevel` / **`contextWindow`** (this adapter only), **not `mode`**, and **not project-less dispatch**; "New project" takes **two steps: in-app modal → native `Select Directory` → modal submit** |
 | `stub` | `spawn` | tests only | `test/stub-agent/stub-agent.mjs` with three scripts (good / fix-on-first / never) |
 
-> `mode` supports `Work` / `Code` / `Design` (TraeWork only) and is inferred from the task text when omitted. Kimi Code's `reasoningLevel` is validated against the **set of levels actually rendered by the UI** (official models `low` / `high` / `max`; unofficial models only `on` / `off`). Adding an agent is usually just a profile — see [docs/agent-profiles.en.md](docs/agent-profiles.en.md) and [CONTRIBUTING.en.md](CONTRIBUTING.en.md).
+> `mode` supports `Work` / `Code` / `Design` (TraeWork only) and is inferred from the task text when omitted. Kimi Code's `reasoningLevel` is validated against the **set of levels actually rendered by the UI** (official models `low` / `high` / `max`; unofficial models only `on` / `off`). MiniMax Code's `reasoningLevel` / `contextWindow` are likewise validated against the **actual UI candidates** (e.g. `M3.1-Flash-Preview` offers `default`/`low`/`medium`/`high`/`xhigh`/`max` plus `512K`/`1M`, while `M3` has no level group and `deepseek-v4.1-flash` has no window group); an out-of-range or unreadable value is fail-closed. Adding an agent is usually just a profile — see [docs/agent-profiles.en.md](docs/agent-profiles.en.md) and [CONTRIBUTING.en.md](CONTRIBUTING.en.md).
 
 ### macOS headless path: codex-cli (user profile)
 
@@ -370,6 +371,7 @@ Allowing and disabling (a CLI flag or its equivalent environment variable; `--no
 | Visual and idempotency | 0.5.x | Visual acceptance (0.5.0) + optional AI content validation (0.5.4), ZCode project-less dispatch, Kimi Code / Qoder CN adapters, idempotency keys (0.5.10) |
 | Hardening and observability | 0.6.x | Skill self-install hardening (0.6.0), GUI selector drift fixes (0.6.2), fine-grained event stream, structured repair directives, dryRun, three-level acceptance config inheritance, terminal-state webhook |
 | Open Design | 0.7.x | Open Design desktop adapter (0.7.1), ZCode 3.14.x binding-contract fix (0.7.4) |
+| MiniMax Code | 0.7.8 | Seventh GUI agent (0.7.8); real-machine evidence corrected three structural assumptions (second-level submenu / per-model candidate sets / two-step project creation), plus the `contextWindow` parameter and a read-only diagnostic probe |
 | Log viewer GUI | `gui-v*` (separate line) | `mcp-gui/` local read-only log viewer (Tauri 2.x + Vue 3), independent version and tag, **not released with the MCP main package** |
 
 > The complete per-version record is in [CHANGELOG.en.md](CHANGELOG.en.md); handoff status and the troubleshooting handbook are in [HANDOFF.md](HANDOFF.md); engineering-metric definitions are in [ARCHITECTURE.en.md](ARCHITECTURE.en.md).

package/README.md

@@ -63,7 +63,7 @@
               ↓  MCP over stdio（stdout 仅承载 JSON-RPC）
         tianshu-mcp              ← 调度 · 执行面 · 验收仪
               ↓
-Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design
+Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design · MiniMax Code
               ↓（GUI 经 CDP 驱动桌面 UI；CLI 走子进程）
         目标项目工作区            ← git 仓库 + 测试 + .tianshu-mcp/
 ```
@@ -227,7 +227,7 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 | 工具 | 能力 / 审批 | 作用 |
 |---|---|---|
 | `run_task` | write + 审批 | 派活（可带自动验收 / 自动返修），异步返回 `taskId`；可选 `idempotencyKey`、`acceptanceOverride` 与 `dryRun` |
-| `continue_task` | write + 审批 | 恢复 `needs_user` 的原会话（ZCode / Codex / Kimi Code / Qoder CN 各有恢复语义） |
+| `continue_task` | write + 审批 | 恢复 `needs_user` 的原会话（ZCode / Codex / Kimi Code / Qoder CN / MiniMax Code 各有恢复语义） |
 | `query_task` | read | 轮询状态 / 进度 / 日志尾 / 最近细粒度事件（可选 `eventLimit`） |
 | `list_tasks` | read | 历史任务过滤列表 |
 | `get_task_report` | read | 某轮验收报告全文（`report.md`） |
@@ -256,9 +256,10 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 | `kimicode` | `gui` / `kimicode-gui` | **ready**（macOS 为 `research`） | Kimi Code 桌面端（Electron）；**双渲染进程**（主窗口 + `Kimi Browser Overlay` 浮层承载模型 / 档位 / 模式菜单）；工作区以完整路径绑定；支持 `model` / `reasoningLevel`，**不支持 `mode`**，且**不支持无项目派发** |
 | `qoder` | `gui` / `qoder-gui` | Windows 真机闭环通过；macOS **research** | 仅 Qoder CN；必须提供已有 `projectPath` 与可读 `planDoc`；`modelSource=default\|custom` 消除同名模型歧义，思考等级经「模型管理」保存为全局偏好并回读 |
 | `opendesign` | `gui` / `opendesign-gui` | **ready**（macOS 为 `research`） | Open Design 桌面端 GUI；选择器取自产品自身 Web 前端的 `data-testid` 钩子，12 步执行链全部接线，并接入验收 → 自动返修 → 再验收闭环；它是唯一带「产物信号」（文件 mtime / 大小指纹）的 driver |
+| `minimax` | `gui` / `minimax-gui` | **ready**（macOS 为 `research`） | MiniMax Code 桌面端（Electron）；**双渲染进程**（主窗口 + `Model menu` 弹层）；推理等级 / 上下文窗口在**悬停模型项展开的二级子菜单**里，且**候选集合随模型变化**（无子菜单的模型请求这两项即 fail-closed）；支持 `model` / `reasoningLevel` / **`contextWindow`**（本适配器专属），**不支持 `mode`**，且**不支持无项目派发**；「新建项目」为**应用内模态框 → 原生 `Select Directory` → 模态框提交**两步 |
 | `stub` | `spawn` | 仅测试 | `test/stub-agent/stub-agent.mjs` 三剧本（good / fix-on-first / never） |
 
-> `mode` 支持 `Work` / `Code` / `Design`（仅 TraeWork），不传时从任务书文本识别。Kimi Code 的 `reasoningLevel` 按**界面实际渲染的档位集合**校验（官方模型 `低` / `高` / `max`，非官方模型仅 `on` / `off`）。新增 agent 通常只需加一个 profile，详见 [docs/agent-profiles.md](docs/agent-profiles.md) 与 [CONTRIBUTING.md](CONTRIBUTING.md)。
+> `mode` 支持 `Work` / `Code` / `Design`（仅 TraeWork），不传时从任务书文本识别。Kimi Code 的 `reasoningLevel` 按**界面实际渲染的档位集合**校验（官方模型 `低` / `高` / `max`，非官方模型仅 `on` / `off`）。MiniMax Code 的 `reasoningLevel` / `contextWindow` 同样按**界面实际候选**校验（如 `M3.1-Flash-Preview` 为 `default`/`low`/`medium`/`high`/`xhigh`/`max` 与 `512K`/`1M`，而 `M3` 无档位组、`deepseek-v4.1-flash` 无窗口组），越权或读不到即 fail-closed。新增 agent 通常只需加一个 profile，详见 [docs/agent-profiles.md](docs/agent-profiles.md) 与 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 ### macOS 无头路径：codex-cli（用户 profile）
 
@@ -370,6 +371,7 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 | 视觉与幂等 | 0.5.x | 视觉验收（0.5.0）+ 可选 AI 内容校验（0.5.4）、ZCode 无项目派发、Kimi Code / Qoder CN 适配、幂等键（0.5.10） |
 | 加固与可观测 | 0.6.x | 技能自装加固（0.6.0）、GUI 选择器漂移修复（0.6.2）、细粒度事件流、结构化修复指令、dryRun、验收配置三级继承、终态通知 |
 | Open Design | 0.7.x | Open Design 桌面端适配（0.7.1）、ZCode 3.14.x 绑定契约修复（0.7.4） |
+| MiniMax Code | 0.7.8 | 第七个 GUI agent 接入（0.7.8）；真机取证修正三处结构假设（二级子菜单 / 集合随模型变化 / 项目创建两步），新增 `contextWindow` 参数与只读诊断探针 |
 | 日志台 GUI | `gui-v*`（独立线） | `mcp-gui/` 本地只读日志台（Tauri 2.x + Vue 3），独立版本与 tag，**不随 MCP 主包发布** |
 
 > 完整逐版记录见 [CHANGELOG.md](CHANGELOG.md)，交接状态与排障手册见 [HANDOFF.md](HANDOFF.md)，工程质量口径见 [ARCHITECTURE.md](ARCHITECTURE.md)。

package/dist/version.generated.js

@@ -4,4 +4,4 @@
  * 本文件由 scripts/sync-version.mjs 在每次 build 前重新生成。
  */
 // generated: 勿手改 —— 运行 `npm run build` 自动同步
-export const MCP_SERVER_VERSION = "0.7.8";
+export const MCP_SERVER_VERSION = "0.7.10";

package/dist/visual/manage.js

@@ -15,6 +15,7 @@ import { VisualBrowser } from "./capture.js";
 import { VisualServices } from "./services.js";
 import { clearContentCache } from "./content-cache.js";
 import { resolveCommandPath } from "./content-command.js";
+import { contentChannelUsage } from "./schema.js";
 import { contentCommandParts, hasContentRules, probeContent, } from "./content.js";
 import { isDefaultWorkspace } from "../tasks/task.js";
 function taskDirectory(home, taskId) {
@@ -159,6 +160,7 @@ export async function probeContentRules(home, projectPath, ruleId) {
                 command: effective.command,
                 resolved: (await resolveCommandPath(effective.command, await projectFile(projectPath, effective.cwd))) !== null,
                 allowRemote: effective.allowRemote,
+                ...contentChannelUsage(effective.argsTemplate),
             });
             for (const [fileIndex, file] of rule.files.entries())
                 results.push(await probeContent({ config, project: projectPath, budget, tempDir: tempRoot }, {
@@ -175,6 +177,7 @@ export async function probeContentRules(home, projectPath, ruleId) {
                 command: effective.command,
                 resolved: (await resolveCommandPath(effective.command, await projectFile(projectPath, effective.cwd))) !== null,
                 allowRemote: effective.allowRemote,
+                ...contentChannelUsage(effective.argsTemplate),
             });
             for (const viewport of config.viewports.filter((v) => page.viewports === undefined || page.viewports.includes(v.id))) {
                 const captured = await browser.capture(projectPath, page, viewport, await services.get(page.source));

package/dist/visual/runtime.js

@@ -5,6 +5,7 @@ import { VisualError } from "./errors.js";
 import { projectFile } from "./paths.js";
 import { contentCommandParts, hasContentRules, contentRulesOf } from "./content.js";
 import { resolveCommandPath } from "./content-command.js";
+import { contentChannelUsage } from "./schema.js";
 export function assertVisualRuntime(version = process.versions.node) {
     const [major = 0, minor = 0] = version.split(".").map(Number);
     if (major < 20 || (major === 20 && minor < 3))
@@ -117,6 +118,8 @@ export async function doctor(projectPath, home) {
     await check("browser", async () => resolveBrowser((await readAcceptanceConfig(projectPath))?.visual?.browser ?? { mode: "managed" }, home));
     // 内容校验诊断（issue #13 F 组）：逐条有效命令的解析结果 + allowRemote 声明清单、
     // 规则数 × samples × timeoutMs 与 roundTimeoutMs 的预算对比（超预算给出建议值，不自动改配置）
+    // issue #29：额外显性化**通道语义**——命令实际使用哪些占位符、哪些受 allowRemote 约束，
+    // 避免「allowRemote=false 即封死一切外发」的错误安全感（缺席不会自己报警）。
     await check("content command", async () => {
         const visual = (await readAcceptanceConfig(projectPath))?.visual;
         if (!visual?.content.enabled || !hasContentRules(visual))
@@ -129,7 +132,11 @@ export async function doctor(projectPath, home) {
             const resolved = await resolveCommandPath(effective.command, cwd);
             if (!resolved)
                 unresolved.push(rule.label);
-            lines.push(`${rule.label}: ${effective.command} -> ${resolved ?? "UNRESOLVED (will block the whole round)"}; allowRemote=${effective.allowRemote}`);
+            // allowRemote 的实际约束范围只有内联字节通道；路径通道不受约束（issue #29）
+            const channels = contentChannelUsage(effective.argsTemplate);
+            const gated = channels.egressConstrained ? "GATED" : "NOT gated";
+            const used = [...(channels.egressConstrained ? ["<image:base64:file>"] : []), ...channels.pathChannels];
+            lines.push(`${rule.label}: ${effective.command} -> ${resolved ?? "UNRESOLVED (will block the whole round)"}; allowRemote=${effective.allowRemote} (constrains only <image:base64:file>); channels used: ${used.length ? used.join(", ") : "(none)"} — ${gated} by allowRemote`);
         }
         // 有效命令不可解析会让整轮配置错误（assertContentReady 抛错），诊断必须据实报失败
         if (unresolved.length)

package/dist/visual/schema.js

@@ -132,6 +132,29 @@ export const ContentVerdictSchema = z
 const envReference = z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string().min(1));
 /** 占位符白名单：argsTemplate 中形如 <...> 的 token 只允许这三个 */
 export const CONTENT_PLACEHOLDERS = ["<image:path>", "<expect:file>", "<image:base64:file>"];
+/**
+ * 外发闸门的通道边界（issue #29）——**唯一的语义源**，schema 校验与 doctor/probe 展示共用：
+ * - `<image:base64:file>`：把图片字节**内联**进临时文件。这是「明确要把图片交给命令」的强信号，
+ *   受 `allowRemote` 约束（未放行即拒绝配置）。定位是**防无意/防误配**，不是防有意外发。
+ * - `<image:path>` / `<expect:file>`：交付路径/期望文本，**不受** `allowRemote` 约束。
+ *   命令的 cwd 本就在项目内、可自读文件，门控 path 无安全收益（见计划 §2.1 探针）；
+ *   且强制放行会反向扩大外发面（用户为过 schema 而开 allowRemote 会连带放行 base64）。
+ */
+export const EGRESS_CONSTRAINED_PLACEHOLDER = "<image:base64:file>";
+/** 按 argsTemplate 统计通道使用情况：doctor/probe 据此把「命令实际拿到什么」显性化 */
+export function contentChannelUsage(argsTemplate) {
+    const pathChannels = [];
+    let egressConstrained = false;
+    for (const token of argsTemplate)
+        for (const match of token.matchAll(/<[^<>\s]*>/g)) {
+            const channel = match[0];
+            if (channel === EGRESS_CONSTRAINED_PLACEHOLDER)
+                egressConstrained = true;
+            else if (!pathChannels.includes(channel))
+                pathChannels.push(channel);
+        }
+    return { egressConstrained, pathChannels };
+}
 /** 页面/规则共用的内容检查声明（pages[].content 与 contents[] 条目） */
 export const ContentCheckSchema = z
     .object({
@@ -296,9 +319,11 @@ export const VisualConfigSchema = z
             const argsTemplate = check.argsTemplate ?? v.content.argsTemplate;
             if (!command || !argsTemplate)
                 issue(`${label}: content checks require command and argsTemplate`);
-            // 外发闸门：字节外传占位符必须逐规则显式放行
+            // 外发闸门：仅内联字节通道（<image:base64:file>）需逐规则显式放行；
+            // 路径通道（<image:path>/<expect:file>）不受约束——边界见 EGRESS_CONSTRAINED_PLACEHOLDER 注释
             const allowRemote = check.allowRemote ?? v.content.allowRemote;
-            if (argsTemplate?.some((token) => token.includes("<image:base64:file>")) && allowRemote !== true)
+            const channels = contentChannelUsage(argsTemplate ?? []);
+            if (channels.egressConstrained && allowRemote !== true)
                 issue(`${label}: <image:base64:file> requires allowRemote = true`);
             // 预算自洽：roundTimeoutMs 是硬总闸，超预算配置必然整轮 ROUND_TIMEOUT，必须在配置期拦截
             const samples = check.samples ?? v.content.samples;