flow-codeblock-rust-mcp 0.1.0 → 0.1.2

package/README.md

@@ -7,7 +7,7 @@ Flow Codeblock Rust+Bun 的本地 stdio MCP Server。它只调用服务端 Rust
 需要 Bun 1.4.0 或更高版本：
 
 ```bash
-bunx --bun flow-codeblock-rust-mcp@0.1.0
+bunx --bun flow-codeblock-rust-mcp@0.1.2
 ```
 
 配置环境变量：
@@ -26,7 +26,7 @@ export FLOW_CODEBLOCK_TOKEN='<YOUR_INTERNAL_ACCESS_TOKEN>'
   "mcpServers": {
     "flow-codeblock-rust": {
       "command": "bunx",
-      "args": ["--bun", "flow-codeblock-rust-mcp@0.1.0"],
+      "args": ["--bun", "flow-codeblock-rust-mcp@0.1.2"],
       "env": {
         "FLOW_CODEBLOCK_BASE_URL": "https://flow.example.com",
         "FLOW_CODEBLOCK_TOKEN": "<YOUR_INTERNAL_ACCESS_TOKEN>"
@@ -38,10 +38,22 @@ export FLOW_CODEBLOCK_TOKEN='<YOUR_INTERNAL_ACCESS_TOKEN>'
 
 ## 工具边界
 
-工具覆盖代码生成、未发布代码测试、脚本列表、版本读取、接口文档校验/预览/保存、脚本创建/更新、锁定/解锁和已发布脚本执行。创建或代码更新要求完整接口文档；预览会调用 `/flow/scripts/validate`，应用时使用事务级 `expected_version` 检测并发冲突。所有脚本写操作需要预览后显式 `confirm: true`。
+工具覆盖代码生成、未发布代码测试、脚本列表、版本读取、接口文档校验/预览/保存、脚本创建/更新、锁定/解锁和已发布脚本执行。创建或代码更新可提交完整接口文档或 RFC 6902 `interface_doc_patch`；预览会调用 `/flow/scripts/validate`，应用时会再次透传补丁并使用事务级 `expected_version` 检测并发冲突。所有脚本写操作需要预览后显式 `confirm: true`。
+
+最终用户交付按模式区分：`non_script` 输出完整 JavaScript、接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和完整 `execution_url`；`script` 默认不主动回显 JavaScript 或原始 `interface_doc`，只输出接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和发布后的完整 `script_url`。脚本代码与 `interface_doc` 仍由 MCP 内部用于预览、校验和发布，除非用户明确索要源码或原始文档。
 
 MCP 不提供脚本删除、紧急恢复解锁、Token 查询、执行统计、所有权转移或任意 HTTP 代理工具。当前版本只提供本地 stdio 连接，不提供远程 HTTP、SSE 或 Streamable HTTP 连接。
 
+## MCP 工具契约
+
+服务器初始化时会通过 MCP `instructions` 下发完整的工具选择、脚本预览/确认流程、代码运行时约束和接口文档规则，因此不依赖额外 Skill 也可以直接调用工具。客户端应优先使用工具 description 和 input schema 中的字段说明，不要通过试错猜测参数。
+
+接口文档必须包含 `schema_version`、`title`、`summary`、`endpoint`、`request`、`responses`、`logic_description`；`endpoint` 必须有 `methods` 和 `description`，`request.query` 与 `request.headers` 必须存在（没有参数时传 `[]`）。POST 还必须提供 `request.body`，其 `content_type`、`schema`、`example` 均必填；每个响应的 `status`、`description`、`content_type`、`schema`、`example` 均必填；查询参数和请求头的每个字段必须有 `name`、`type`、`required`、`description`、`example`。
+
+接口文档的 `endpoint.path` 使用相对路径：创建时省略，更新时使用 `/flow/codeblock/<实际脚本ID>`。对外展示完整请求地址时，将用户提供的服务域名与 `/flow/codeblock/{{脚本ID}}` 拼接；不要把真实令牌、密码、Cookie 或 Authorization 值写入代码、文档、示例或 URL。
+
+`interface_doc_patch` / `document_patch` 必须携带正整数 `expected_version`，最多 256 个 `add/remove/replace/move/copy/test` 操作。补丁预览仅返回操作数量、JSON Pointer 路径、警告和版本信息，不返回完整合并文档。
+
 ## 安全行为
 
 - 管理请求使用 `Authorization: Bearer`，执行已发布脚本时不会把 MCP Token 转发到脚本输入。

package/dist/index.js

@@ -27877,23 +27877,68 @@ var EMPTY_COMPLETION_RESULT = {
 var interfaceDocRequiredFields = {
   document: ["schema_version", "title", "summary", "endpoint", "request", "responses", "logic_description"],
   endpoint: ["methods", "description"],
-  request: ["query", "headers", "body (POST only)"],
+  request: ["query", "headers", "body (required for POST; omit for GET-only)"],
   parameter: ["name", "type", "required", "description", "example"],
   body: ["content_type", "schema", "example"],
   response: ["status", "description", "content_type", "schema", "example"],
-  optional: ["endpoint.path (omit on create; actual path on update)", "usage_refs"]
+  optional: ["endpoint.path (omit on create; actual relative path on update)", "usage_refs"]
 };
 var interfaceDocNestedRules = [
+  "title is the document title; summary is a one-sentence summary; endpoint.description explains the callable interface; logic_description explains the business logic.",
+  "request.query and request.headers are always present arrays; use [] when the interface has no query or header parameters.",
+  "Each query/header parameter requires name, type, required, description, and example. Do not use the internal input.query/input.header/input.body/input.cookies names in the caller-facing document.",
+  "For POST, request.body is required and content_type must be application/json; for GET-only documents, omit request.body.",
+  "Each response requires status, description, content_type, schema, and example. Describe every response shape returned by the script, including errors when applicable.",
   "Every JSON Schema node declares type. Object schemas use properties for fixed fields or a complete additionalProperties schema for dynamic keys.",
   "Every array schema has items. Object array items have complete properties, and every example item covers those properties.",
   "At every nesting level, schema properties and example fields cover each other. Optional properties still appear in the complete example.",
   "required contains only runtime-required fields. Use separate responses when success and error payloads have different shapes."
 ];
 var interfaceDocInputDescription = [
-  "A complete script-interface-doc.v1 document is required when creating a script or changing code.",
+  "A complete script-interface-doc.v1 document is required when creating a script, changing code, or saving documentation.",
   `Required structure: ${Object.entries(interfaceDocRequiredFields).map(([key, fields]) => `${key}=[${fields.join(", ")}]`).join("; ")}.`,
-  ...interfaceDocNestedRules
+  ...interfaceDocNestedRules,
+  "endpoint.path is relative and must be /flow/codeblock/<actual-script-id> on update; the final public URL is the caller-provided domain followed by /flow/codeblock/<script-id>.",
+  "Never include real tokens, passwords, cookies, Authorization values, or other credentials in the document or examples."
 ].join(" ");
+var patchPathSchema = exports_external.string().describe("RFC 6901 JSON Pointer 路径；数组路径使用当前 canonical 文档的索引。");
+var interfaceDocPatchOperationSchema = exports_external.union([
+  exports_external.object({ op: exports_external.literal("add"), path: patchPathSchema, value: exports_external.unknown() }).strict(),
+  exports_external.object({ op: exports_external.literal("remove"), path: patchPathSchema }).strict(),
+  exports_external.object({ op: exports_external.literal("replace"), path: patchPathSchema, value: exports_external.unknown() }).strict(),
+  exports_external.object({ op: exports_external.literal("move"), from: patchPathSchema, path: patchPathSchema }).strict(),
+  exports_external.object({ op: exports_external.literal("copy"), from: patchPathSchema, path: patchPathSchema }).strict(),
+  exports_external.object({ op: exports_external.literal("test"), path: patchPathSchema, value: exports_external.unknown() }).strict()
+]).superRefine((operation, context) => {
+  if (["add", "replace", "test"].includes(operation.op) && !Object.prototype.hasOwnProperty.call(operation, "value")) {
+    context.addIssue({ code: "custom", path: ["value"], message: "value is required for this operation" });
+  }
+});
+var interfaceDocPatchSchema = exports_external.array(interfaceDocPatchOperationSchema).min(1).max(256).describe("RFC 6902 JSON Patch 操作数组；按顺序应用，不能与完整 interface_doc 同时提供。");
+var interfaceDocPatchJsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://flow-codeblock.local/schemas/script-interface-doc.patch.v1.json",
+  title: "script-interface-doc.v1 JSON Patch",
+  description: "RFC 6902 operations applied in order to an existing canonical script interface document.",
+  type: "array",
+  minItems: 1,
+  maxItems: 256,
+  items: {
+    oneOf: [
+      { type: "object", additionalProperties: false, required: ["op", "path", "value"], properties: { op: { const: "add" }, path: { type: "string" }, value: {} } },
+      { type: "object", additionalProperties: false, required: ["op", "path"], properties: { op: { const: "remove" }, path: { type: "string" } } },
+      { type: "object", additionalProperties: false, required: ["op", "path", "value"], properties: { op: { const: "replace" }, path: { type: "string" }, value: {} } },
+      { type: "object", additionalProperties: false, required: ["op", "from", "path"], properties: { op: { const: "move" }, from: { type: "string" }, path: { type: "string" } } },
+      { type: "object", additionalProperties: false, required: ["op", "from", "path"], properties: { op: { const: "copy" }, from: { type: "string" }, path: { type: "string" } } },
+      { type: "object", additionalProperties: false, required: ["op", "path", "value"], properties: { op: { const: "test" }, path: { type: "string" }, value: {} } }
+    ]
+  }
+};
+function assertInterfaceDocPatch(patch) {
+  const parsed = interfaceDocPatchSchema.safeParse(patch);
+  if (!parsed.success)
+    throw new Error(`interface_doc_patch 格式无效: ${parsed.error.message}`);
+}
 function isObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -27941,6 +27986,8 @@ function validateSchemaExampleCoverage(schema, example, schemaPath, examplePath,
         issues.push(`${examplePath} is missing ${key}`);
       } else if (isObject2(propertySchema)) {
         validateSchemaExampleCoverage(propertySchema, example[key], `${schemaPath}.properties.${key}`, `${examplePath}.${key}`, issues);
+      } else {
+        issues.push(`${schemaPath}.properties.${key} must be a JSON Schema object`);
       }
     }
   }
@@ -27973,6 +28020,9 @@ function validateParameters(value, path, issues) {
     issues.push(`${path} must be present; use [] when there are no parameters`);
     return;
   }
+  if (value.length > 100)
+    issues.push(`${path} must contain at most 100 parameters`);
+  const names = new Set;
   value.forEach((parameter, index) => {
     const itemPath = `${path}[${index}]`;
     if (!isObject2(parameter)) {
@@ -27981,6 +28031,13 @@ function validateParameters(value, path, issues) {
     }
     requireText(parameter, "name", itemPath, issues);
     requireText(parameter, "description", itemPath, issues);
+    if (typeof parameter.name === "string") {
+      const name = parameter.name.trim();
+      if (name && names.has(name))
+        issues.push(`${itemPath}.name must be unique within ${path}`);
+      if (name)
+        names.add(name);
+    }
     if (!["string", "integer", "number", "boolean", "array", "object"].includes(String(parameter.type))) {
       issues.push(`${itemPath}.type is unsupported`);
     }
@@ -28027,6 +28084,9 @@ function interfaceDocCompletenessIssues(document, operation) {
       if (methods.some((method) => method !== "GET" && method !== "POST")) {
         issues.push("interface_doc.endpoint.methods may contain only GET or POST");
       }
+      if (new Set(methods).size !== methods.length) {
+        issues.push("interface_doc.endpoint.methods must not contain duplicates");
+      }
     }
     if (operation === "update") {
       if (typeof document.endpoint.path !== "string" || !document.endpoint.path.startsWith("/flow/codeblock/") || document.endpoint.path.includes("{script_id}")) {
@@ -28053,6 +28113,8 @@ function interfaceDocCompletenessIssues(document, operation) {
   if (!Array.isArray(document.responses) || document.responses.length === 0) {
     issues.push("interface_doc.responses must contain at least one response");
   } else {
+    if (document.responses.length > 50)
+      issues.push("interface_doc.responses must contain at most 50 responses");
     document.responses.forEach((response, index) => {
       const path = `interface_doc.responses[${index}]`;
       if (!isObject2(response)) {
@@ -28110,7 +28172,11 @@ var interfaceDocSchema = {
       additionalProperties: false,
       properties: {
         methods: { type: "array", minItems: 1, maxItems: 2, uniqueItems: true, items: { enum: ["GET", "POST"] } },
-        path: { type: "string", pattern: "^/flow/codeblock/" },
+        path: {
+          type: "string",
+          pattern: "^/flow/codeblock/",
+          description: "相对路径；创建时可省略，更新时必须为 /flow/codeblock/<实际脚本ID>。完整地址另行拼接调用方提供的域名。"
+        },
         description: { type: "string", minLength: 1, maxLength: 4000 }
       }
     },
@@ -28191,51 +28257,182 @@ function schemaFromExample(value) {
     return { type: Number.isInteger(value) ? "integer" : "number" };
   return { type: typeof value };
 }
-function codeWriterContext(mode, requirement, inputExample, includeFullSchema) {
+function codeWriterContext(mode, requirement, inputExample, includeFullSchema, baseUrl) {
   const common = {
     contract_version: "flow-code-writer.v1",
     mode,
     requirement,
     mutates_or_executes: false,
     runtime: "Bun 1.4+ fresh worker; no state is shared between executions.",
+    runtime_limits: {
+      execution_timeout_ms: { minimum_default: 100, default_maximum: 15000 },
+      code_bytes: 65535,
+      input_bytes: 2 * 1024 * 1024,
+      result_bytes: 10 * 1024 * 1024
+    },
     code_rules: [
-      "Read business input only from the global input object and return a JSON-serializable value.",
-      "Use a top-level return by default. Use qf_output only when explicitly requested, never both.",
-      "Prefer standard JavaScript and native fetch. Await or return every asynchronous operation.",
-      "Do not use import/export, dynamic require, browser APIs, timers, blocked identifiers, blocked Node modules, or real credentials."
+      "所有业务数据只从全局 input 读取，不从环境变量、持久化全局变量或其他外部状态读取；返回值必须可 JSON 序列化。",
+      "默认使用顶层 return；只有事件式/异步流程或用户明确要求时才使用 qf_output，且必须是裸的 qf_output = { ... } 对象字面量赋值，不能与顶层 return 混用，也不能遮蔽该标识符。",
+      "优先标准 JavaScript 和服务端原生 fetch；只有原生能力确实无法满足且用户明确要求时，才使用白名单 CommonJS 字面量 require。",
+      "禁止 import/export、动态 require、浏览器 API、定时器、阻止标识符、阻止成员和黑名单 Node 模块，不得写入真实凭据。",
+      "业务逻辑和异步操作放在 try-catch 中；错误转换为字符串或普通对象后返回。",
+      "不得创建无界循环、未 settle 的 Promise 或执行结束后仍运行的后台任务；所有请求必须 await 或 return。",
+      "外部 URL、请求头、查询参数和请求体必须校验类型、长度和允许范围；HTTP 响应检查状态并按 JSON、文本、空响应分别处理。"
+    ],
+    async_lifecycle: [
+      "禁止 setTimeout、setInterval、setImmediate、轮询、延迟和后台重试。",
+      "请求必须在执行超时内完成，不能遗留未等待的 fetch。"
+    ],
+    require_policy: {
+      allowed_call_form: "仅允许单个字符串字面量 require('模块名')，不得间接调用、动态模块名或使用 import/export。",
+      dayjs_exception: "日期处理优先原生 Date；复杂日期解析/格式化/时区才允许使用 dayjs。",
+      other_modules: "除 dayjs 外，只有原生能力确实无法实现且用户明确要求时才允许白名单模块。"
+    },
+    forbidden: {
+      identifiers: [
+        "eval",
+        "Function",
+        "Proxy",
+        "__proto__",
+        "child_process",
+        "exec",
+        "execFile",
+        "execSync",
+        "fork",
+        "spawn",
+        "module",
+        "exports",
+        "setImmediate",
+        "setInterval",
+        "setTimeout"
+      ],
+      members: [
+        "Object.getPrototypeOf",
+        "Object.setPrototypeOf",
+        "Reflect.construct",
+        "Reflect.apply",
+        "Reflect.get",
+        "Reflect.set",
+        "process.exit",
+        "process.kill",
+        "process.binding",
+        "process._linkedBinding",
+        "process.dlopen"
+      ],
+      modules: [
+        "child_process",
+        "cluster",
+        "dgram",
+        "dns",
+        "http",
+        "http2",
+        "https",
+        "inspector",
+        "internal",
+        "module",
+        "node:module",
+        "net",
+        "os",
+        "perf_hooks",
+        "async_hooks",
+        "bun",
+        "process",
+        "readline",
+        "repl",
+        "tls",
+        "undici",
+        "v8",
+        "vm",
+        "vm2",
+        "worker_threads",
+        "ws"
+      ]
+    },
+    output_rules: [
+      "返回值只能是普通可序列化值或 Promise；禁止循环引用、BigInt、函数、Symbol、未处理的复杂类实例及无界数组/字符串。",
+      "平台会把即时接口返回值放入外层 HTTP 响应的 result 字段；脚本接口通常直接返回业务值。推荐 { success: true, data: value } 或 { success: false, error: message }。"
     ],
     allowed_modules: allowedModules
   };
   if (mode === "non_script") {
     return {
       ...common,
-      input_contract: "POST /flow/codeblock makes request.body.input the global input object.",
-      deliverables: ["Executable JavaScript", "Input and output contract"],
+      input_contract: {
+        method: "POST",
+        path: "/flow/codeblock",
+        rule: "请求体中的 input 原样注入全局 input，缺省为 {}；平台请求体可包含 codebase64、input、qingcodeTimeout。",
+        example: { codebase64: "<base64 JavaScript>", input: inputExample ?? {} }
+      },
+      generation_decisions: [
+        "用户未说明时生成即时执行的非脚本模式。",
+        "如果需求包含 HTTP 重定向，必须改用 script 模式 /flow/codeblock/{{script_id}}。"
+      ],
+      deliverables: ["只含可执行 JavaScript 的 javascript 代码块", "输入和输出契约"],
       test_tool: { name: "flow_execute_code", arguments: { code: "<JavaScript>", input: inputExample ?? {}, timeout_ms: 3000 } },
-      rule: "Do not execute unless the user explicitly asks to test the code."
+      rule: "除非用户明确要求测试，否则不要调用 flow_execute_code。",
+      response_format: [
+        "除非用户明确要求只返回代码，否则先说明模式和输出方式，再给 JavaScript 代码块，最后给请求/响应示例。",
+        "非脚本接口交付完整 JavaScript、接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和 execution_url。"
+      ]
     };
   }
   const bodyExample = inputExample && typeof inputExample === "object" ? inputExample : { value: "example" };
+  const normalizedBaseUrl = baseUrl?.trim().replace(/\/+$/, "");
+  const endpointPathTemplate = "/flow/codeblock/{{script_id}}";
   return {
     ...common,
     input_contract: {
-      endpoint: "GET|POST /flow/codeblock/{script_id}",
+      endpoint: "GET|POST /flow/codeblock/{{script_id}}",
       shape: { query: {}, header: {}, body: {}, cookies: {} },
-      note: "POST callers send their business JSON directly; do not wrap it in input or input.body."
+      mapping: {
+        query: "input.query；单值为字符串，重复参数为字符串数组；不含 qingcodeToken/qingcodeTimeout。",
+        headers: "input.header；服务端过滤 x-original-cookie，需要 Cookie 时使用 cookie。",
+        body: "input.body；POST JSON 请求体，空请求体为 {}；业务数据直接发送，不包装为 input 或 input.body。",
+        cookies: "input.cookies；Cookie 键值对象，无 Cookie 时可能不存在。"
+      },
+      reserved_query: ["qingcodeToken", "qingcodeTimeout"]
     },
-    deliverables: ["Executable JavaScript", "A separate complete script-interface-doc.v1 JSON object"],
+    endpoint_url_template: normalizedBaseUrl ? `${normalizedBaseUrl}${endpointPathTemplate}` : endpointPathTemplate,
+    endpoint_url_rule: "提供域名时，输出该域名 + /flow/codeblock/{{script_id}}；URL 中不得包含凭据。",
+    internal_artifacts: [
+      "只含可执行代码的 JavaScript 代码块（提交预览、校验和发布；默认不回显）",
+      "独立且完整的 script-interface-doc.v1 JSON 对象（提交预览、校验和发布；默认不回显）"
+    ],
+    final_deliverables: [
+      "接口调用说明",
+      "请求参数及示例",
+      "执行逻辑",
+      "成功/错误输出示例",
+      "发布后的完整 script_url"
+    ],
     interface_doc_contract: {
       strict_preview_gate: true,
       required_fields: interfaceDocRequiredFields,
       nested_rules: interfaceDocNestedRules,
       body_example_schema: schemaFromExample(bodyExample),
-      full_json_schema: includeFullSchema ? interfaceDocSchema : undefined
+      full_json_schema: includeFullSchema ? interfaceDocSchema : undefined,
+      patch_json_schema: includeFullSchema ? interfaceDocPatchJsonSchema : undefined,
+      separation: [
+        "javascript 代码块只含可执行代码，不写接口文档注释。",
+        "json 代码块只含一个合法 script-interface-doc.v1 对象，不混入 Markdown、注释或尾随逗号。"
+      ]
+    },
+    redirect_contract: {
+      rule: "只有脚本接口解析 flow_redirect_url/flow_redirect_code；即时接口把它们作为普通结果。",
+      url: "flow_redirect_url 必须是单斜杠相对路径或带主机的 http/https URL，不得含空白或控制字符。",
+      code: "flow_redirect_code 只能是 301、302、303、307、308 或对应数字字符串。"
     },
     workflow: [
-      "Read the current version before updating.",
-      "Generate code and documentation together, then call flow_preview_script_change once.",
-      "Apply only after explicit user confirmation.",
-      "Run flow_execute_script only when the user asks to test the published script."
+      "如果是更新，先调用 flow_get_script 读取当前版本；更新文档可先调用 flow_get_script_documentation。",
+      "代码和完整 interface_doc 一起生成；创建或代码更新只调用一次 flow_preview_script_change。",
+      "仅在用户明确确认后调用 flow_apply_script_change 或 flow_apply_script_documentation，并传 confirm=true。",
+      "只有用户要求测试已发布脚本时才调用 flow_execute_script；仅测试未发布代码时调用 flow_execute_code。",
+      "版本冲突、预览过期或校验失败时停止并重新读取、重新预览，不重试旧 preview_id。"
+    ],
+    response_format: [
+      "脚本模式默认不回显 JavaScript 或原始 interface_doc；只展示接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和发布后的 script_url，除非用户明确索要源码或原始文档。",
+      "脚本代码与 interface_doc 仍必须在内部提交给预览、校验和发布工具。",
+      "说明请求参数、主要业务行为、响应和错误处理，并提供与模式匹配的 HTTP 方法、路径、Headers/Query/Body/Cookie 和响应示例。"
     ]
   };
 }
@@ -28302,9 +28499,45 @@ class PreviewStore {
 var result = (value) => ({
   content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
 });
+var serverInstructions = [
+  "这是 Flow Codeblock Rust+Bun MCP Server。除 flow_write_code 外，工具直接调用服务端 REST API；flow_write_code 只返回生成契约。不要猜测 REST 路径，也不要把 MCP 内部令牌放入业务参数。",
+  "代码运行于服务端 Bun 异步函数上下文，支持现代 JavaScript、async/await、Promise、箭头函数和顶层 return；默认最小超时 100ms、最大超时 15000ms，代码 65535 字节、输入 2MiB、结果 10MiB。",
+  "工具选择：flow_write_code 只生成代码与契约，不执行、不写库；flow_execute_code 只用于用户明确要求的未发布非脚本测试；flow_execute_script 只执行已发布脚本。",
+  "脚本读取、创建和更新流程：更新前先 flow_get_script 读取当前 version；创建必须提供完整 interface_doc，更新代码或文档可提供完整 interface_doc 或 RFC 6902 interface_doc_patch（二选一，补丁必须带 expected_version）；先 flow_preview_script_change，再在用户明确确认后 flow_apply_script_change(confirm=true)。文档单独修改使用 flow_preview_script_documentation -> flow_apply_script_documentation。",
+  "预览 ID 是一次性且有时效的；版本冲突、预览过期或校验失败时停止，重新读取并预览，不要重试旧 preview_id。flow_apply_* 永远需要 confirm=true。",
+  "script-interface-doc.v1 必须包含 schema_version、title、summary、endpoint、request、responses、logic_description。endpoint 必须包含 methods 和 description；request.query、request.headers 必须存在（没有参数用 []）；POST 必须有 request.body，GET-only 必须省略。增量文档使用最多 256 项的 add/remove/replace/move/copy/test JSON Patch，预览只回显操作数量和路径，不回显合并文档。",
+  "查询参数和请求头的每一项必须有 name、type、required、description、example。请求体和每个响应必须有 content_type=application/json、schema、example；每个响应还必须有 status、description。JSON Schema 的每个节点必须声明 type，数组必须有 items，对象和 example 必须互相覆盖。",
+  "接口文档 endpoint.path 只写相对路径：创建时省略，更新时写 /flow/codeblock/<实际脚本ID>。对外展示的完整调用地址必须使用用户提供的域名拼接 /flow/codeblock/{{脚本ID}}；不要把真实 Token、密码、Cookie 或 Authorization 值写入代码、文档、示例或 URL。",
+  "脚本模式输入来自 input.query、input.header、input.body、input.cookies；即时非脚本模式 POST /flow/codeblock 的 body.input 原样成为全局 input。代码默认使用顶层 return；只有事件式/异步流程或用户明确要求时才使用裸 qf_output 赋值，不能混用。",
+  "最终用户交付按模式区分：non_script 输出完整 JavaScript、接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和完整 execution_url；script 默认不主动回显 JavaScript 或原始 interface_doc，只输出接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和发布后的完整 script_url，除非用户明确索要源码或原始文档。script 的代码与 interface_doc 仍必须内部提交给预览、校验和发布工具。",
+  "优先原生 JavaScript、URL/URLSearchParams 和 fetch；禁止浏览器 API、定时器、动态模块加载、黑名单 Node 模块和危险标识符。HTTP 请求必须检查状态并处理 JSON/文本/空响应，所有异步任务必须显式 await 或 return。",
+  "执行脚本时 method 只能是 GET 或 POST；MCP 认证、Cookie、CSRF、代理来源头和测试工具标识会被过滤。不要使用删除脚本、紧急恢复解锁或任意 HTTP 代理能力，本 MCP 不提供这些工具。"
+].join(`
+`);
 function encodedScriptId(scriptId) {
   return encodeURIComponent(scriptId);
 }
+function scriptUrl(api2, scriptId) {
+  return new URL(`/flow/codeblock/${encodedScriptId(scriptId)}`, api2.baseUrl).toString();
+}
+function executionUrl(api2) {
+  return new URL("/flow/codeblock", api2.baseUrl).toString();
+}
+function withScriptUrl(api2, payload, fallbackScriptId) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return payload;
+  const data = responseData(payload);
+  const scriptId = typeof data.script_id === "string" && data.script_id.length > 0 ? data.script_id : fallbackScriptId;
+  if (!scriptId)
+    return payload;
+  return {
+    ...payload,
+    data: {
+      ...data,
+      script_url: scriptUrl(api2, scriptId)
+    }
+  };
+}
 function encodeCode(code, codeBase64) {
   if (code === undefined && codeBase64 === undefined)
     return;
@@ -28379,30 +28612,40 @@ function withApiErrors(handler) {
   };
 }
 var documentationFields = {
-  document: exports_external.unknown().optional(),
-  raw_document: exports_external.string().optional(),
-  format: exports_external.literal("json").optional()
+  document: exports_external.unknown().optional().describe(`规范化的 script-interface-doc.v1 JSON 对象。与 raw_document、document_patch 三选一；保存或代码更新时必须完整。${interfaceDocInputDescription}`),
+  raw_document: exports_external.string().optional().describe("待服务端解析的 JSON/OpenAPI 文档文本。与 document、document_patch 三选一；format=json 时按 JSON 解析。"),
+  format: exports_external.literal("json").optional().describe("raw_document 的格式，目前只支持 json。"),
+  document_patch: interfaceDocPatchSchema.optional().describe("仅已有脚本使用的 RFC 6902 增量补丁；与 document、raw_document 三选一。"),
+  expected_version: exports_external.number().int().positive().optional().describe("补丁的当前脚本版本；提交补丁时必填，必须来自刚读取的当前版本。")
 };
 var changeSchema = exports_external.object({
-  operation: exports_external.enum(["create", "update"]),
-  script_id: exports_external.string().min(1).optional(),
-  code: exports_external.string().optional(),
-  code_base64: exports_external.string().optional(),
-  description: exports_external.string().optional(),
-  ip_whitelist: exports_external.array(exports_external.string()).nullable().optional(),
+  operation: exports_external.enum(["create", "update"]).describe("create 创建脚本；update 更新已有脚本。"),
+  script_id: exports_external.string().min(1).optional().describe("更新目标脚本 ID。create 不得传入。"),
+  code: exports_external.string().optional().describe("UTF-8 JavaScript 源码，与 code_base64 二选一。创建或修改代码时必填；代码只包含可执行 JavaScript。"),
+  code_base64: exports_external.string().optional().describe("JavaScript 源码的非空 Base64，与 code 二选一。"),
+  description: exports_external.string().optional().describe("脚本说明。可在不改代码时单独更新。"),
+  ip_whitelist: exports_external.array(exports_external.string()).nullable().optional().describe("来源 IP/CIDR 白名单。省略表示更新时保持原值；null 或 [] 表示清除限制。"),
   interface_doc: exports_external.unknown().optional().describe(interfaceDocInputDescription),
-  rollback_to_version: exports_external.number().int().positive().optional(),
-  expected_version: exports_external.number().int().positive().optional()
+  interface_doc_patch: interfaceDocPatchSchema.optional().describe("仅 update 使用的 RFC 6902 JSON Patch；与完整 interface_doc 互斥，create 禁止使用。"),
+  rollback_to_version: exports_external.number().int().positive().optional().describe("回滚到的历史版本号。只能与单独的 update 操作使用，不能和 code、interface_doc 或 interface_doc_patch 同时传入。"),
+  expected_version: exports_external.number().int().positive().optional().describe("更新时必填的当前版本号。必须来自刚读取的 flow_get_script，用于并发冲突保护；create 不得传入。")
 });
 var documentationSchema = exports_external.object({
-  script_id: exports_external.string().min(1),
+  script_id: exports_external.string().min(1).describe("目标脚本 ID，不是完整 URL；校验或预览现有脚本的文档。"),
   ...documentationFields
 }).superRefine((input, context) => {
-  if (input.document === undefined === (input.raw_document === undefined)) {
-    context.addIssue({ code: "custom", message: "Provide exactly one of document or raw_document" });
+  const supplied = [input.document, input.raw_document, input.document_patch].filter((value) => value !== undefined).length;
+  if (supplied !== 1) {
+    context.addIssue({ code: "custom", message: "Provide exactly one of document, raw_document, or document_patch" });
+  }
+  if (input.document_patch !== undefined && input.expected_version === undefined) {
+    context.addIssue({ code: "custom", message: "document_patch requires expected_version" });
   }
 });
 function documentationBody(input) {
+  if (input.document_patch !== undefined) {
+    return { document_patch: input.document_patch, expected_version: input.expected_version };
+  }
   if (input.raw_document !== undefined) {
     return { raw_document: input.raw_document, ...input.format ? { format: input.format } : {} };
   }
@@ -28422,6 +28665,9 @@ function assertScriptChangeInput(input) {
     }
     if (!hasCode)
       throw new Error("Create preview requires code or code_base64");
+    if (input.interface_doc_patch !== undefined) {
+      throw new Error("Create preview cannot use interface_doc_patch; submit a complete interface_doc");
+    }
     if (input.interface_doc === undefined) {
       throw new Error("Create preview requires a complete interface_doc");
     }
@@ -28432,34 +28678,64 @@ function assertScriptChangeInput(input) {
     if (!input.script_id || input.expected_version === undefined) {
       throw new Error("Update preview requires script_id and expected_version");
     }
-    if (!hasCode && input.description === undefined && input.ip_whitelist === undefined && input.interface_doc === undefined && input.rollback_to_version === undefined) {
-      throw new Error("Update preview requires code, description, ip_whitelist, interface_doc, or rollback_to_version");
+    if (!hasCode && input.description === undefined && input.ip_whitelist === undefined && input.interface_doc === undefined && input.interface_doc_patch === undefined && input.rollback_to_version === undefined) {
+      throw new Error("Update preview requires code, description, ip_whitelist, interface_doc, interface_doc_patch, or rollback_to_version");
     }
-    if (hasCode && input.interface_doc === undefined) {
-      throw new Error("Updating code requires a complete interface_doc");
+    if (hasCode && input.interface_doc === undefined && input.interface_doc_patch === undefined) {
+      throw new Error("Updating code requires a complete interface_doc or interface_doc_patch");
     }
   }
-  if (input.rollback_to_version !== undefined && (hasCode || input.interface_doc !== undefined)) {
-    throw new Error("rollback_to_version cannot be combined with code or interface_doc");
+  if (input.interface_doc !== undefined && input.interface_doc_patch !== undefined) {
+    throw new Error("interface_doc and interface_doc_patch are mutually exclusive");
+  }
+  if (input.rollback_to_version !== undefined && (hasCode || input.interface_doc !== undefined || input.interface_doc_patch !== undefined)) {
+    throw new Error("rollback_to_version cannot be combined with code, interface_doc, or interface_doc_patch");
   }
   if (input.interface_doc !== undefined) {
     assertCompleteInterfaceDoc(input.interface_doc, input.operation);
   }
+  if (input.interface_doc_patch !== undefined)
+    assertInterfaceDocPatch(input.interface_doc_patch);
 }
 async function validateScriptChange(api2, operation, payload) {
   const hasCode = typeof payload.code_base64 === "string";
   const hasDocument = payload.interface_doc !== undefined && payload.interface_doc !== null;
+  const hasPatch = payload.interface_doc_patch !== undefined;
   const hasWhitelist = payload.ip_whitelist !== undefined;
-  if (!hasCode && !hasDocument && !hasWhitelist) {
+  if (!hasCode && !hasDocument && !hasPatch && !hasWhitelist) {
     return { success: true, data: { valid: true, warnings: [] } };
   }
   return api2.post("/flow/scripts/validate", {
     ...hasCode ? { code_base64: payload.code_base64 } : {},
     ...operation === "update" ? { script_id: payload.script_id } : {},
+    ...hasPatch ? { expected_version: payload.expected_version } : {},
     ...hasWhitelist ? { ip_whitelist: payload.ip_whitelist } : {},
-    ...hasDocument ? { interface_doc: payload.interface_doc } : {}
+    ...hasDocument ? { interface_doc: payload.interface_doc } : {},
+    ...hasPatch ? { interface_doc_patch: payload.interface_doc_patch } : {}
   });
 }
+function compactPatchValidation(validation, patch, currentVersion2) {
+  const data = responseData(validation);
+  const operations = Array.isArray(patch) ? patch : [];
+  return {
+    valid: data.valid ?? true,
+    warnings: Array.isArray(data.warnings) ? data.warnings : [],
+    current_version: currentVersion2,
+    interface_doc_patch: {
+      operation_count: operations.length,
+      paths: operations.map((operation) => {
+        if (!operation || typeof operation !== "object")
+          return null;
+        const value = operation;
+        return {
+          op: typeof value.op === "string" ? value.op : "unknown",
+          path: typeof value.path === "string" ? value.path : "",
+          ...typeof value.from === "string" ? { from: value.from } : {}
+        };
+      })
+    }
+  };
+}
 function assertPreview(record3, operation) {
   if (!record3 || record3.operation !== operation)
     throw new Error("Preview is missing, expired, or has the wrong operation");
@@ -28469,26 +28745,37 @@ function assertPreview(record3, operation) {
   return record3;
 }
 function createMcpServer({ api: api2, previews = new PreviewStore }) {
-  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.0" });
+  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.2" }, { instructions: serverInstructions });
   server.registerTool("flow_write_code", {
-    description: "返回符合当前 Flow Codeblock Rust+Bun 运行时、输入和接口文档约束的代码生成契约。本工具不写数据库也不执行代码。",
+    description: "生成代码实现契约，不写数据库、不发布脚本、不执行代码。mode=non_script 生成即时 POST /flow/codeblock 代码，最终交付包含完整 execution_url；mode=script 生成 GET/POST /flow/codeblock/{{script_id}} 代码，内部生成完整 script-interface-doc.v1 供预览、校验和发布，最终交付默认只展示接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和 script_url，除非用户明确索要源码或原始 interface_doc。脚本文档的 title、summary、endpoint.methods、endpoint.description、request、responses、logic_description 必须齐全；query/header 参数必须有 name/type/description/example，body 和 response 字段必须有 content_type/schema/example。需要展示用户指定的完整地址时可传入 base_url。",
     inputSchema: {
-      mode: exports_external.enum(["non_script", "script"]),
-      requirement: exports_external.string().min(1).max(20000),
-      input_example: exports_external.unknown().optional(),
-      include_full_schema: exports_external.boolean().optional()
+      mode: exports_external.enum(["non_script", "script"]).describe("执行模式：non_script 为即时接口；script 为按脚本 ID 发布的 GET/POST 接口。未明确要求重定向时使用 non_script。"),
+      requirement: exports_external.string().min(1).max(20000).describe("用户的业务需求、输入字段、同步/异步要求和错误行为。只写与本次代码有关的需求。"),
+      input_example: exports_external.unknown().optional().describe("业务输入示例。脚本模式下用于生成 request.body/schema/example；非脚本模式下用于 flow_execute_code 测试参数。不要放真实凭据。"),
+      include_full_schema: exports_external.boolean().optional().describe("脚本模式是否在结果中附带完整 JSON Schema；默认 false。接口文档实例仍必须按必填字段生成。"),
+      base_url: exports_external.string().url().refine((value) => {
+        try {
+          const parsed = new URL(value);
+          return (parsed.protocol === "http:" || parsed.protocol === "https:") && !parsed.username && !parsed.password && !parsed.search && !parsed.hash && !/[\u0000-\u001f\u007f]/.test(value);
+        } catch {
+          return false;
+        }
+      }, "base_url must be an http(s) URL without credentials or control characters").optional().describe("可选的用户服务域名，例如 https://flow.example.com。仅用于输出完整调用地址，会拼接 /flow/codeblock/{{script_id}}；不得包含用户名、密码或 Token。")
     }
-  }, async ({ mode, requirement, input_example, include_full_schema }) => result(codeWriterContext(mode, requirement, input_example, include_full_schema ?? false)));
+  }, async ({ mode, requirement, input_example, include_full_schema, base_url }) => {
+    const context = codeWriterContext(mode, requirement, input_example, include_full_schema ?? false, base_url);
+    return result(mode === "non_script" ? { ...context, execution_url: executionUrl(api2) } : context);
+  });
   server.registerTool("flow_list_scripts", {
-    description: "分页查询当前 Flow Codeblock 服务中的脚本。",
+    description: "只读分页查询脚本。默认使用 page/size 偏移分页；需要连续遍历时使用 pagination=cursor，首次不传 cursor，后续使用响应中的游标。不会创建、更新或执行脚本。",
     inputSchema: {
-      page: exports_external.number().int().positive().optional(),
-      size: exports_external.number().int().min(1).max(100).optional(),
-      keyword: exports_external.string().optional(),
-      sort: exports_external.enum(["updated_at", "created_at", "code_length", "version"]).optional(),
-      order: exports_external.enum(["asc", "desc"]).optional(),
-      pagination: exports_external.literal("cursor").optional(),
-      cursor: exports_external.string().optional()
+      page: exports_external.number().int().positive().optional().describe("偏移分页页码，从 1 开始；使用游标分页时省略。"),
+      size: exports_external.number().int().min(1).max(100).optional().describe("每页数量，1-100，默认由服务端决定。"),
+      keyword: exports_external.string().optional().describe("按脚本关键词筛选。"),
+      sort: exports_external.enum(["updated_at", "created_at", "code_length", "version"]).optional().describe("排序字段。游标分页只支持 updated_at、created_at、code_length。"),
+      order: exports_external.enum(["asc", "desc"]).optional().describe("排序方向，默认由服务端决定。"),
+      pagination: exports_external.literal("cursor").optional().describe("传 cursor 启用游标分页；首次调用不要传 cursor。"),
+      cursor: exports_external.string().optional().describe("上一页返回的游标，仅与 pagination=cursor 一起使用。")
     }
   }, withApiErrors(async ({ page, size, keyword, sort, order, pagination, cursor }) => {
     const query = new URLSearchParams;
@@ -28509,36 +28796,48 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
     return result(await api2.get(`/flow/scripts${query.size ? `?${query}` : ""}`));
   }));
   server.registerTool("flow_get_script", {
-    description: "读取脚本的当前版本或指定历史版本。",
-    inputSchema: { script_id: exports_external.string().min(1), version: exports_external.number().int().min(0).optional() }
+    description: "只读读取脚本代码、元数据和版本信息。更新前必须先调用本工具并使用返回的 current_version 作为 flow_preview_script_change.expected_version。",
+    inputSchema: {
+      script_id: exports_external.string().min(1).describe("脚本 ID，不是完整 URL。"),
+      version: exports_external.number().int().min(0).optional().describe("可选历史版本号；省略时读取当前版本。")
+    }
   }, withApiErrors(async ({ script_id, version: version2 }) => {
     const query = version2 === undefined ? "" : `?version=${encodeURIComponent(String(version2))}`;
     return result(await api2.get(`/flow/scripts/${encodedScriptId(script_id)}${query}`));
   }));
   server.registerTool("flow_get_script_documentation", {
-    description: "读取当前或指定历史版本的脚本接口文档。",
-    inputSchema: { script_id: exports_external.string().min(1), version: exports_external.number().int().min(0).optional() }
+    description: "只读读取当前或指定历史版本的 script-interface-doc.v1 接口文档。修改文档前先读取当前版本并保留版本号。",
+    inputSchema: {
+      script_id: exports_external.string().min(1).describe("脚本 ID，不是完整 URL。"),
+      version: exports_external.number().int().min(0).optional().describe("可选历史版本号；省略时读取当前文档。")
+    }
   }, withApiErrors(async ({ script_id, version: version2 }) => {
     const query = version2 === undefined ? "" : `?version=${encodeURIComponent(String(version2))}`;
     return result(await api2.get(`/flow/scripts/${encodedScriptId(script_id)}/documentation${query}`));
   }));
   server.registerTool("flow_validate_script_documentation", {
-    description: "校验并规范化接口文档，不写入数据库。",
+    description: "只读校验并规范化指定脚本的接口文档，不写入数据库。完整 document、raw_document 和 RFC 6902 document_patch 三选一；补丁必须带 expected_version，响应不会用于发布确认。",
     inputSchema: documentationSchema.shape
   }, withApiErrors(async (input) => {
     const parsed = documentationSchema.parse(input);
     if (parsed.document !== undefined) {
       assertCompleteInterfaceDoc(parsed.document, "update");
     }
-    const validation = await api2.post(`/flow/scripts/${encodedScriptId(parsed.script_id)}/documentation`, documentationBody(parsed));
-    const document = responseData(validation).document;
+    if (parsed.document_patch !== undefined)
+      assertInterfaceDocPatch(parsed.document_patch);
+    const validation = parsed.document_patch !== undefined ? await api2.post("/flow/scripts/validate", {
+      script_id: parsed.script_id,
+      expected_version: parsed.expected_version,
+      interface_doc_patch: parsed.document_patch
+    }) : await api2.post(`/flow/scripts/${encodedScriptId(parsed.script_id)}/documentation`, documentationBody(parsed));
+    const document = responseData(validation).document ?? responseData(validation).interface_doc;
     if (document === undefined)
       throw new Error("Documentation validation response did not include document");
     assertCompleteInterfaceDoc(document, "update");
     return result(validation);
   }));
   server.registerTool("flow_preview_script_change", {
-    description: "预览脚本创建或更新。预览不会写数据库，应用必须再次传 confirm=true。",
+    description: "预览脚本创建或更新，不写数据库。create 必须传 code/code_base64 和完整 interface_doc，且不得传 script_id/expected_version；update 必须传 script_id 和刚读取的 expected_version，修改代码时必须同时传完整 interface_doc 或 interface_doc_patch。预览成功后只能在用户明确确认时调用 flow_apply_script_change(confirm=true)。",
     inputSchema: changeSchema.shape
   }, withApiErrors(async (input) => {
     const parsed = changeSchema.parse(input);
@@ -28551,6 +28850,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       ...parsed.description !== undefined ? { description: parsed.description } : {},
       ...parsed.ip_whitelist !== undefined ? { ip_whitelist: parsed.ip_whitelist } : {},
       ...parsed.interface_doc !== undefined ? { interface_doc: parsed.operation === "create" ? removeCreatePath(parsed.interface_doc) : parsed.interface_doc } : {},
+      ...parsed.interface_doc_patch !== undefined ? { interface_doc_patch: parsed.interface_doc_patch } : {},
       ...parsed.rollback_to_version !== undefined ? { rollback_to_version: parsed.rollback_to_version } : {}
     };
     const expectedVersion = parsed.operation === "update" ? await fetchCurrentVersion(api2, parsed.script_id) : undefined;
@@ -28559,8 +28859,9 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
     }
     const validation = await validateScriptChange(api2, parsed.operation, payload);
     const normalized = responseData(validation).interface_doc;
-    if (normalized !== undefined)
+    if (parsed.interface_doc !== undefined && normalized !== undefined)
       payload.interface_doc = normalized;
+    const previewValidation = parsed.interface_doc_patch !== undefined ? compactPatchValidation(validation, parsed.interface_doc_patch, expectedVersion) : { valid: true, server_validation: validation };
     const previewId = randomUUID();
     const storedPreview = previews.put(previewId, "script_change", payload, expectedVersion);
     return result({
@@ -28569,21 +28870,24 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       expected_version: expectedVersion,
       expires_at: new Date(storedPreview.expiresAt).toISOString(),
       validation: {
-        valid: true,
-        server_validation: validation
+        ...previewValidation
       },
       changes: {
         code: codeBase64 !== undefined,
         description: parsed.description !== undefined,
         ip_whitelist: parsed.ip_whitelist !== undefined,
         interface_doc: parsed.interface_doc !== undefined,
+        interface_doc_patch: parsed.interface_doc_patch !== undefined,
         rollback_to_version: parsed.rollback_to_version !== undefined
       }
     });
   }));
   server.registerTool("flow_apply_script_change", {
-    description: "应用已预览的创建或更新，必须传入 confirm=true；不支持删除脚本。",
-    inputSchema: { preview_id: exports_external.string().uuid(), confirm: exports_external.literal(true) }
+    description: "应用 flow_preview_script_change 返回的一次性 preview_id。必须传 confirm=true；工具会再次检查版本并在成功或失败后销毁预览。发布成功时返回由 FLOW_CODEBLOCK_BASE_URL 生成的完整 script_url。不支持删除脚本。版本冲突时重新读取并预览。",
+    inputSchema: {
+      preview_id: exports_external.string().uuid().describe("最近一次脚本变更预览返回的 UUID；不能复用过期或已应用的 ID。"),
+      confirm: exports_external.literal(true).describe("必须为 true，表示用户已明确确认写入。")
+    }
   }, withApiErrors(async ({ preview_id }) => {
     try {
       const record3 = assertPreview(previews.get(preview_id), "script_change");
@@ -28595,45 +28899,60 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
         if (actualVersion !== record3.expectedVersion) {
           throw new Error(`Script version changed from ${record3.expectedVersion} to ${actualVersion}; read and preview again`);
         }
+        if (payload.interface_doc_patch !== undefined) {
+          await validateScriptChange(api2, "update", payload);
+        }
         const body = { ...payload };
         delete body.script_id;
         response = await api2.put(`/flow/scripts/${encodedScriptId(scriptId)}`, body);
       } else {
         response = await api2.post("/flow/scripts", payload);
       }
-      return result(response);
+      return result(withScriptUrl(api2, response, scriptId));
     } finally {
       previews.delete(preview_id);
     }
   }));
   server.registerTool("flow_preview_script_documentation", {
-    description: "预览并校验接口文档保存，不写数据库。",
+    description: "预览接口文档保存，不写数据库。先读取脚本当前版本；document、raw_document 和 document_patch 三选一，补丁必须带 expected_version，完整文档必须包含所有强制字段。成功后只有 flow_apply_script_documentation(confirm=true) 才会写入。",
     inputSchema: documentationSchema.shape
   }, withApiErrors(async (input) => {
     const parsed = documentationSchema.parse(input);
     const expectedVersion = await fetchCurrentVersion(api2, parsed.script_id);
+    if (parsed.document_patch !== undefined && parsed.expected_version !== expectedVersion) {
+      throw new Error(`Script version changed from ${parsed.expected_version} to ${expectedVersion}; read and preview again`);
+    }
     const rawBody = documentationBody(parsed);
-    const validation = parsed.raw_document !== undefined ? await api2.post(`/flow/scripts/${encodedScriptId(parsed.script_id)}/documentation`, rawBody) : await api2.post("/flow/scripts/validate", {
+    const validation = parsed.document_patch !== undefined ? await api2.post("/flow/scripts/validate", {
+      script_id: parsed.script_id,
+      expected_version: parsed.expected_version,
+      interface_doc_patch: parsed.document_patch
+    }) : parsed.raw_document !== undefined ? await api2.post(`/flow/scripts/${encodedScriptId(parsed.script_id)}/documentation`, rawBody) : await api2.post("/flow/scripts/validate", {
       script_id: parsed.script_id,
       interface_doc: rawBody.document
     });
     const document = responseData(validation).interface_doc ?? responseData(validation).document;
-    if (document === undefined)
-      throw new Error("Documentation validation response did not include document");
-    assertCompleteInterfaceDoc(document, "update");
+    if (parsed.document_patch === undefined) {
+      if (document === undefined)
+        throw new Error("Documentation validation response did not include document");
+      assertCompleteInterfaceDoc(document, "update");
+    }
     const previewId = randomUUID();
-    const storedPreview = previews.put(previewId, "documentation", { script_id: parsed.script_id, document }, expectedVersion);
+    const storedPreview = previews.put(previewId, "documentation", parsed.document_patch !== undefined ? { script_id: parsed.script_id, expected_version: expectedVersion, document_patch: parsed.document_patch } : { script_id: parsed.script_id, document }, expectedVersion);
     return result({
       preview_id: previewId,
       script_id: parsed.script_id,
       expected_version: expectedVersion,
       expires_at: new Date(storedPreview.expiresAt).toISOString(),
-      validation: responseData(validation)
+      validation: parsed.document_patch !== undefined ? compactPatchValidation(validation, parsed.document_patch, expectedVersion) : responseData(validation)
     });
   }));
   server.registerTool("flow_apply_script_documentation", {
-    description: "应用已预览的接口文档，必须传入 confirm=true。",
-    inputSchema: { preview_id: exports_external.string().uuid(), confirm: exports_external.literal(true) }
+    description: "应用 flow_preview_script_documentation 返回的一次性预览。必须传 confirm=true；工具会再次检查脚本版本并在成功或失败后销毁预览。发布成功时返回完整 script_url。版本冲突时重新读取、预览。",
+    inputSchema: {
+      preview_id: exports_external.string().uuid().describe("最近一次接口文档预览返回的 UUID；不能复用过期或已应用的 ID。"),
+      confirm: exports_external.literal(true).describe("必须为 true，表示用户已明确确认写入。")
+    }
   }, withApiErrors(async ({ preview_id }) => {
     try {
       const record3 = assertPreview(previews.get(preview_id), "documentation");
@@ -28642,33 +28961,42 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       if (actualVersion !== record3.expectedVersion) {
         throw new Error(`Script version changed from ${record3.expectedVersion} to ${actualVersion}; read and preview again`);
       }
+      const patch = record3.payload.document_patch;
+      if (patch !== undefined) {
+        assertInterfaceDocPatch(patch);
+        await api2.post("/flow/scripts/validate", {
+          script_id: scriptId,
+          expected_version: record3.expectedVersion,
+          interface_doc_patch: patch
+        });
+      }
       const response = await api2.put(`/flow/scripts/${encodedScriptId(scriptId)}/documentation`, {
-        document: record3.payload.document,
+        ...patch !== undefined ? { document_patch: patch } : { document: record3.payload.document },
         expected_version: record3.expectedVersion
       });
-      return result(response);
+      return result(withScriptUrl(api2, response, scriptId));
     } finally {
       previews.delete(preview_id);
     }
   }));
   const lockSchema = {
-    script_id: exports_external.string().min(1),
-    owner_name: exports_external.string().min(1),
-    lock_password: exports_external.string().min(6),
-    confirm: exports_external.literal(true)
+    script_id: exports_external.string().min(1).describe("要锁定或解锁的脚本 ID。"),
+    owner_name: exports_external.string().min(1).describe("锁定时设置、解锁时核对的所有者名称。"),
+    lock_password: exports_external.string().min(6).describe("锁定口令；仅传给服务端，不会写入 MCP 预览或日志。"),
+    confirm: exports_external.literal(true).describe("必须为 true，表示用户明确确认锁定或解锁。")
   };
-  server.registerTool("flow_lock_script", { description: "锁定脚本。必须显式传入 confirm=true；锁定口令不会被 MCP 保存。", inputSchema: lockSchema }, withApiErrors(async ({ script_id, owner_name, lock_password }) => result(await api2.post(`/flow/scripts/${encodedScriptId(script_id)}/lock`, { owner_name, lock_password }))));
-  server.registerTool("flow_unlock_script", { description: "解锁脚本。必须显式传入 confirm=true；锁定口令不会被 MCP 保存。", inputSchema: lockSchema }, withApiErrors(async ({ script_id, owner_name, lock_password }) => result(await api2.post(`/flow/scripts/${encodedScriptId(script_id)}/unlock`, { owner_name, lock_password }))));
+  server.registerTool("flow_lock_script", { description: "锁定脚本以阻止并发写入。必须显式传入 confirm=true；锁定口令不会被 MCP 保存。锁定后脚本变更和文档保存可能被服务端拒绝。", inputSchema: lockSchema }, withApiErrors(async ({ script_id, owner_name, lock_password }) => result(await api2.post(`/flow/scripts/${encodedScriptId(script_id)}/lock`, { owner_name, lock_password }))));
+  server.registerTool("flow_unlock_script", { description: "使用所有者名称和口令正常解锁脚本。必须显式传入 confirm=true；锁定口令不会被 MCP 保存。不提供紧急恢复解锁。", inputSchema: lockSchema }, withApiErrors(async ({ script_id, owner_name, lock_password }) => result(await api2.post(`/flow/scripts/${encodedScriptId(script_id)}/unlock`, { owner_name, lock_password }))));
   const queryValueSchema = exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean(), exports_external.array(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()]))]);
   server.registerTool("flow_execute_script", {
-    description: "执行已发布脚本。执行请求不向脚本转发 MCP 认证凭据、Cookie、CSRF 或测试工具标识。",
+    description: "执行已发布脚本，仅用于用户明确要求测试或调用时。method 只能是 GET/POST；结果包含由 FLOW_CODEBLOCK_BASE_URL 和 script_id 生成的完整 script_url。query 数组会生成重复参数，POST 的 body 作为 JSON 发送。MCP 认证、Cookie、CSRF、代理来源头和测试工具标识会被过滤，qingcodeToken/qingcodeTimeout 不能作为业务参数传入。",
     inputSchema: {
-      script_id: exports_external.string().min(1),
-      method: exports_external.enum(["GET", "POST"]).default("POST"),
-      query: exports_external.record(exports_external.string(), queryValueSchema).optional(),
-      headers: exports_external.record(exports_external.string(), exports_external.string()).optional(),
-      body: exports_external.unknown().optional(),
-      timeout_ms: exports_external.number().int().positive().optional()
+      script_id: exports_external.string().min(1).describe("已发布脚本 ID；工具会调用 /flow/codeblock/{script_id}。"),
+      method: exports_external.enum(["GET", "POST"]).default("POST").describe("脚本请求方法，只能是 GET 或 POST；默认 POST。"),
+      query: exports_external.record(exports_external.string(), queryValueSchema).optional().describe("业务查询参数。值可为 string/number/boolean 或其数组；数组生成重复 query 参数。不要传 qingcodeToken/qingcodeTimeout。"),
+      headers: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("业务请求头。认证、Cookie、CSRF、Forwarded、X-Real-IP 等保留头会被过滤。"),
+      body: exports_external.unknown().optional().describe("POST JSON 请求体；GET 不发送 body。不要把脚本模式业务 body 包装为 input 或 input.body。"),
+      timeout_ms: exports_external.number().int().positive().optional().describe("执行超时毫秒数；只能通过此字段配置，不能在 query 中传 qingcodeTimeout。")
     }
   }, withApiErrors(async ({ script_id, method, query, headers, body, timeout_ms }) => {
     const url2 = new URL(`/flow/codeblock/${encodedScriptId(script_id)}`, api2.baseUrl);
@@ -28694,15 +29022,15 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       authenticated: false,
       execution: true
     });
-    return result({ response });
+    return result({ script_url: scriptUrl(api2, script_id), method, response });
   }));
   server.registerTool("flow_execute_code", {
-    description: "执行未发布的非脚本 JavaScript。使用当前认证、配额、安全策略和 MCP Web lane；不会把认证信息写入用户脚本输入。",
+    description: "执行未发布的非脚本 JavaScript，仅在用户明确要求测试时使用。结果包含完整 execution_url。请求固定为 POST /flow/codeblock，body.input 原样注入全局 input；代码和 code_base64 二选一。不会把 MCP 认证信息写入用户脚本输入，也不会创建或发布脚本。",
     inputSchema: {
-      code: exports_external.string().min(1).optional(),
-      code_base64: exports_external.string().min(1).optional(),
-      input: exports_external.unknown().optional(),
-      timeout_ms: exports_external.number().int().positive().optional()
+      code: exports_external.string().min(1).optional().describe("UTF-8 JavaScript 源码，与 code_base64 二选一。"),
+      code_base64: exports_external.string().min(1).optional().describe("JavaScript 源码的非空 Base64，与 code 二选一。"),
+      input: exports_external.unknown().optional().describe("注入全局 input 的业务数据，默认 {}。不要放 Token、密码、Cookie 或 Authorization 值。"),
+      timeout_ms: exports_external.number().int().positive().optional().describe("本次测试执行超时毫秒数；必须在服务端允许的最小/最大范围内。")
     }
   }, withApiErrors(async ({ code, code_base64, input, timeout_ms }) => {
     const codeBase64 = encodeCode(code, code_base64);
@@ -28713,6 +29041,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
     };
     return result({
       mode: "non_script",
+      execution_url: executionUrl(api2),
       response: await api2.request("/flow/codeblock", {
         method: "POST",
         body: JSON.stringify(body),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-codeblock-rust-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Flow Codeblock Rust+Bun stdio MCP Server for script management and execution.",
   "license": "MIT",
   "repository": {