tianshu-mcp 0.7.9 → 0.7.10

package/CHANGELOG.en.md

@@ -60,6 +60,44 @@ 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

package/CHANGELOG.md

@@ -58,6 +58,39 @@
 
 ---
 
+## [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
 
 ### 修复

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.9";
+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;

package/docs/visual-acceptance.en.md

@@ -166,13 +166,15 @@ client. Judgement is fully delegated to a local command you supply, which uses i
 
 - **Placeholders** (a placeholder absent from the template produces no temporary file):
 
-| Placeholder | Expands to | Extra condition |
-|---|---|---|
-| `<image:path>` | absolute path of the inspected image (through the project path gate) | — |
-| `<expect:file>` | absolute path of a temporary file holding the expectation as UTF-8 | — |
-| `<image:base64:file>` | absolute path of a temporary file holding the image's base64 | **requires** the rule's effective `allowRemote === true`, else the schema rejects it |
+| Placeholder | Expands to | Constrained by `allowRemote`? | Extra condition |
+|---|---|---|---|
+| `<image:path>` | absolute path of the inspected image (through the project path gate) | **No** | — |
+| `<expect:file>` | absolute path of a temporary file holding the expectation as UTF-8 (**not** an image-egress channel; it carries expectation text only) | **No** | — |
+| `<image:base64:file>` | absolute path of a temporary file holding the image's base64 (inlines the image **bytes**) | **Yes** | **requires** the rule's effective `allowRemote === true`, else the schema rejects it |
 
-  Any other `<...>` token is rejected at configuration time.
+  Any other `<...>` token is rejected at configuration time. `allowRemote` constrains **only** the
+  inline-byte shape `<image:base64:file>`; the two path channels are unconstrained (see “Egress statement”
+  below), and `visual doctor` marks each rule's actually-used channels.
 
 - **stdout**: the **last non-empty line** is parsed as JSON: `{ "passed": boolean, "confidence"?: 0..1, "reason": string }` (strict mode; unknown fields rejected).
 - **Exit code**: `0` means the command ran normally (**not** that the judgement passed — read the JSON); non-`0` means the command failed.
@@ -221,7 +223,9 @@ There is no separate cap on judgement count or spend. Cost is bounded entirely b
 
 ### Egress statement
 
-Whether images leave the machine **depends on the behaviour of your command**; the MCP cannot block that at the system level. Its enforcement is contract-level only: a rule that has not explicitly opted into `allowRemote` may not use `<image:base64:file>` (the schema rejects it). `visual doctor` lists each rule's `allowRemote` declaration. Confirm your command's actual behaviour yourself.
+Whether images leave the machine **depends on the behaviour of your command**; the MCP cannot block that at the system level. Its enforcement is contract-level only, and **covers just the `allowRemote` constraint on `<image:base64:file>`** (inlining the image bytes into a temp file; the schema rejects it unless the rule explicitly opts in).
+
+**The contract layer is not a complete block on image egress** (issue #29): `<image:path>` / `<expect:file>` are **not** constrained by `allowRemote`. The judgement command runs with `shell:false` inside the **project directory** and can read the inspected project image by itself, so gating the path channel adds no security while forcing users to set `allowRemote` just to pass the schema — which would also open up the inline base64 channel. `allowRemote` is about **preventing accidental/misconfigured inline egress**, not “blocking every way of handing an image to a command”. `visual doctor` lists each rule's `allowRemote` declaration and the placeholder channels it **actually uses** (marking which are constrained). Confirm your command's actual behaviour yourself.
 
 ### Testing your command
 

package/docs/visual-acceptance.md

@@ -168,13 +168,14 @@ tianshu-mcp visual rules approve TASK_ID REVIEW_ID DIGEST "用户确认的批准
 
 - **占位符**（未在模板中出现的占位符不会生成对应临时文件）：
 
-| 占位符 | 展开为 | 附加条件 |
-|---|---|---|
-| `<image:path>` | 被检图片的绝对路径（经项目路径闸门） | — |
-| `<expect:file>` | 写入 UTF-8 期望原文的临时文件绝对路径 | — |
-| `<image:base64:file>` | 写入该图片 base64 的临时文件绝对路径 | **必须**该规则有效 `allowRemote === true`，否则 schema 拒绝 |
+| 占位符 | 展开为 | 是否受 `allowRemote` 约束 | 附加条件 |
+|---|---|---|---|
+| `<image:path>` | 被检图片的绝对路径（经项目路径闸门） | **否** | — |
+| `<expect:file>` | 写入 UTF-8 期望原文的临时文件绝对路径（**不是图片外发通道**，只交付期望文本） | **否** | — |
+| `<image:base64:file>` | 写入该图片 base64 的临时文件绝对路径（把图片**字节**内联进文件） | **是** | **必须**该规则有效 `allowRemote === true`，否则 schema 拒绝 |
 
-  出现任何其他 `<...>` token 直接拒绝配置。
+  出现任何其他 `<...>` token 直接拒绝配置。`allowRemote` **只**约束 `<image:base64:file>` 这一内联字节
+  形态；两个路径通道不受约束（原因见下方「数据外发声明」），`visual doctor` 会逐规则标出实际使用的通道。
 
 - **stdout**：取**最后一行非空文本**解析 JSON：`{ "passed": boolean, "confidence"?: 0..1, "reason": string }`（严格模式，未知字段拒绝）。
 - **退出码**：`0` 表示命令正常执行（**不代表判定通过**，通过与否看 JSON）；非 `0` 表示命令执行失败。
@@ -230,9 +231,14 @@ tianshu-mcp visual rules approve TASK_ID REVIEW_ID DIGEST "用户确认的批准
 
 ### 数据外发声明
 
-图片是否离开本机取决于**用户自备命令的行为**，MCP 无法在系统层拦截。MCP 的强制力仅在契约层：未显式放行
-`allowRemote` 的规则禁止使用 `<image:base64:file>`（schema 拒绝）。`visual doctor` 列出各规则的 `allowRemote`
-声明。请自行确认命令的实际行为。
+图片是否离开本机取决于**用户自备命令的行为**，MCP 无法在系统层拦截。MCP 的强制力仅在契约层，且
+**只覆盖 `allowRemote` 对 `<image:base64:file>` 的约束**（把图片字节内联进临时文件；未显式放行即 schema 拒绝）。
+
+**契约层不是对图片外发的完备拦截**（issue #29）：`<image:path>` / `<expect:file>` 不受 `allowRemote`
+约束。判定命令以 `shell:false` 在**项目目录内**执行，本身就能读取项目内的被检图片，因此门控路径通道
+既无安全收益，又会因「必须开 `allowRemote` 才能过 schema」而反向连带放行 base64 内联。`allowRemote`
+的定位是**防无意/防误配的内联外发**，不是「封死一切把图交给命令的形态」。`visual doctor` 列出各规则的
+`allowRemote` 声明与**实际使用的占位符通道**（标明哪些通道受约束）。请自行确认命令的实际行为。
 
 ### 验证自备命令
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tianshu-mcp",
-  "version": "0.7.9",
+  "version": "0.7.10",
   "description": "天枢 × AI-Agent 编排 MCP server —— 驱动 Codex、TraeWork、ZCode、Kimi Code、Qoder CN 与 Open Design 完成项目开发、验收、失败返修与再验收闭环。",
   "type": "module",
   "license": "Apache-2.0",

package/skills/tianshu-mcp/SKILL.md

@@ -274,7 +274,7 @@ meta 的 `needsUserKind` 给出等待类型，`pendingQuestion` 给出问题原
 - **整轮阻塞**：任一规则的**有效**命令不可解析（`CONTENT_COMMAND_MISSING`）或宿主环境变量缺失（`CONTENT_ENV_MISSING`）会让整轮进 `needs_attention` 且**不产出任何视觉结果行**。这是 fail-closed，不是告警。
 - **`uncertain` 不是失败**：票不集中或低于 `minConfidence` 时判 `uncertain`，永不阻塞、不触发返修；命令不报 confidence 时 `minConfidence` 不生效。
 - 排查：`tianshu-mcp visual doctor <project>`、`visual content probe <project> [ruleId]`、`visual content cache clear <taskId>`。
-- **数据外发**：`allowRemote` 默认 `false`，未放行的规则禁止使用字节外传占位符；图片是否离开本机取决于用户命令的行为，MCP 无法在系统层拦截。
+- **数据外发**：`allowRemote` 默认 `false`，**只**禁止受约束的内联字节通道 `<image:base64:file>`（未放行即 schema 拒绝）；`<image:path>` / `<expect:file>` 是**不受约束**的路径通道（命令在项目内执行、本就能自读文件，门控无收益）。契约层不是对图片外发的完备拦截——图片是否离开本机取决于用户命令的行为，MCP 无法在系统层拦截。`visual doctor` 逐规则标出实际使用的通道与是否 `GATED`。
 
 ---