flow-codeblock-rust-mcp 0.1.1 → 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.1
+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.1"],
+      "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,7 +38,9 @@ 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 连接。
 
@@ -50,6 +52,8 @@ MCP 不提供脚本删除、紧急恢复解锁、Token 查询、执行统计、
 
 接口文档的 `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

@@ -27901,6 +27901,44 @@ var interfaceDocInputDescription = [
   "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);
 }
@@ -28334,7 +28372,7 @@ function codeWriterContext(mode, requirement, inputExample, includeFullSchema, b
       rule: "除非用户明确要求测试，否则不要调用 flow_execute_code。",
       response_format: [
         "除非用户明确要求只返回代码，否则先说明模式和输出方式，再给 JavaScript 代码块，最后给请求/响应示例。",
-        "非脚本接口请求地址是用户服务域名 + /flow/codeblock。"
+        "非脚本接口交付完整 JavaScript、接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和 execution_url。"
       ]
     };
   }
@@ -28356,13 +28394,24 @@ function codeWriterContext(mode, requirement, inputExample, includeFullSchema, b
     },
     endpoint_url_template: normalizedBaseUrl ? `${normalizedBaseUrl}${endpointPathTemplate}` : endpointPathTemplate,
     endpoint_url_rule: "提供域名时，输出该域名 + /flow/codeblock/{{script_id}}；URL 中不得包含凭据。",
-    deliverables: ["只含可执行代码的 JavaScript 代码块", "独立且完整的 script-interface-doc.v1 JSON 对象"],
+    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,
+      patch_json_schema: includeFullSchema ? interfaceDocPatchJsonSchema : undefined,
       separation: [
         "javascript 代码块只含可执行代码，不写接口文档注释。",
         "json 代码块只含一个合法 script-interface-doc.v1 对象，不混入 Markdown、注释或尾随逗号。"
@@ -28381,9 +28430,9 @@ function codeWriterContext(mode, requirement, inputExample, includeFullSchema, b
       "版本冲突、预览过期或校验失败时停止并重新读取、重新预览，不重试旧 preview_id。"
     ],
     response_format: [
-      "生成或修改脚本时必须同时输出独立的 javascript 和 json 代码块，除非用户明确只要代码。",
-      "说明请求参数、主要业务行为、响应和错误处理，并提供与模式匹配的 HTTP 方法、路径、Headers/Query/Body/Cookie 和响应示例。",
-      "脚本接口完整请求地址使用用户提供的域名 + /flow/codeblock/{{script_id}}；接口文档 endpoint.path 仍使用相对路径。"
+      "脚本模式默认不回显 JavaScript 或原始 interface_doc；只展示接口调用说明、请求参数及示例、执行逻辑、成功/错误输出示例和发布后的 script_url，除非用户明确索要源码或原始文档。",
+      "脚本代码与 interface_doc 仍必须在内部提交给预览、校验和发布工具。",
+      "说明请求参数、主要业务行为、响应和错误处理，并提供与模式匹配的 HTTP 方法、路径、Headers/Query/Body/Cookie 和响应示例。"
     ]
   };
 }
@@ -28454,12 +28503,13 @@ 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；先 flow_preview_script_change，再在用户明确确认后 flow_apply_script_change(confirm=true)。文档单独修改使用 flow_preview_script_documentation -> flow_apply_script_documentation。",
+  "脚本读取、创建和更新流程：更新前先 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 必须省略。",
+  "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(`
@@ -28467,6 +28517,27 @@ var serverInstructions = [
 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;
@@ -28541,9 +28612,11 @@ function withApiErrors(handler) {
   };
 }
 var documentationFields = {
-  document: exports_external.unknown().optional().describe(`规范化的 script-interface-doc.v1 JSON 对象。与 raw_document 二选一；保存或代码更新时必须完整。${interfaceDocInputDescription}`),
-  raw_document: exports_external.string().optional().describe("待服务端解析的 JSON/OpenAPI 文档文本。与 document 二选一；format=json 时按 JSON 解析。"),
-  format: exports_external.literal("json").optional().describe("raw_document 的格式，目前只支持 json。")
+  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"]).describe("create 创建脚本；update 更新已有脚本。"),
@@ -28553,18 +28626,26 @@ var changeSchema = exports_external.object({
   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().describe("回滚到的历史版本号。只能与单独的 update 操作使用，不能和 code 或 interface_doc 同时传入。"),
+  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).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 } : {} };
   }
@@ -28584,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");
     }
@@ -28594,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");
@@ -28631,9 +28745,9 @@ function assertPreview(record3, operation) {
   return record3;
 }
 function createMcpServer({ api: api2, previews = new PreviewStore }) {
-  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.1" }, { instructions: serverInstructions });
+  const server = new McpServer({ name: "flow-codeblock-rust", version: "0.1.2" }, { instructions: serverInstructions });
   server.registerTool("flow_write_code", {
-    description: "生成代码实现契约，不写数据库、不发布脚本、不执行代码。mode=non_script 生成即时 POST /flow/codeblock 代码；mode=script 生成 GET/POST /flow/codeblock/{{script_id}} 代码，并同时给出完整 script-interface-doc.v1 接口文档规则。脚本文档的 title、summary、endpoint.methods、endpoint.description、request、responses、logic_description 必须齐全；query/header 参数必须有 name/type/description/example，body 和 response 字段必须有 content_type/schema/example。需要展示完整地址时传入 base_url，结果会拼接为 base_url + /flow/codeblock/{{script_id}}。",
+    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"]).describe("执行模式：non_script 为即时接口；script 为按脚本 ID 发布的 GET/POST 接口。未明确要求重定向时使用 non_script。"),
       requirement: exports_external.string().min(1).max(20000).describe("用户的业务需求、输入字段、同步/异步要求和错误行为。只写与本次代码有关的需求。"),
@@ -28648,7 +28762,10 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
         }
       }, "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, base_url }) => result(codeWriterContext(mode, requirement, input_example, include_full_schema ?? false, base_url)));
+  }, 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: "只读分页查询脚本。默认使用 page/size 偏移分页；需要连续遍历时使用 pagination=cursor，首次不传 cursor，后续使用响应中的游标。不会创建、更新或执行脚本。",
     inputSchema: {
@@ -28699,22 +28816,28 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
     return result(await api2.get(`/flow/scripts/${encodedScriptId(script_id)}/documentation${query}`));
   }));
   server.registerTool("flow_validate_script_documentation", {
-    description: "只读校验并规范化指定脚本的接口文档，不写入数据库。document 与 raw_document 必须二选一；传 document 时会在调用服务端前检查全部必填字段，包含 title、summary、接口说明、请求方式、请求/响应结构和示例。",
+    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: "预览脚本创建或更新，不写数据库。create 必须传 code/code_base64 和完整 interface_doc，且不得传 script_id/expected_version；update 必须传 script_id 和刚读取的 expected_version，修改代码时必须同时传完整 interface_doc。预览成功后只能在用户明确确认时调用 flow_apply_script_change(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);
@@ -28727,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;
@@ -28735,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({
@@ -28745,20 +28870,20 @@ 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: "应用 flow_preview_script_change 返回的一次性 preview_id。必须传 confirm=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，表示用户已明确确认写入。")
@@ -28774,44 +28899,56 @@ 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: "预览接口文档保存，不写数据库。先读取脚本当前版本；document/raw_document 二选一，并确保接口文档包含所有强制字段。成功后只有 flow_apply_script_documentation(confirm=true) 才会写入。",
+    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: "应用 flow_preview_script_documentation 返回的一次性预览。必须传 confirm=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，表示用户已明确确认写入。")
@@ -28824,11 +28961,20 @@ 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);
     }
@@ -28843,7 +28989,7 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
   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: "执行已发布脚本，仅用于用户明确要求测试或调用时。method 只能是 GET/POST；脚本地址为当前服务域名 + /flow/codeblock/{script_id}，结果包含不带业务 query 值的 request_url。query 数组会生成重复参数，POST 的 body 作为 JSON 发送。MCP 认证、Cookie、CSRF、代理来源头和测试工具标识会被过滤，qingcodeToken/qingcodeTimeout 不能作为业务参数传入。",
+    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).describe("已发布脚本 ID；工具会调用 /flow/codeblock/{script_id}。"),
       method: exports_external.enum(["GET", "POST"]).default("POST").describe("脚本请求方法，只能是 GET 或 POST；默认 POST。"),
@@ -28876,12 +29022,10 @@ function createMcpServer({ api: api2, previews = new PreviewStore }) {
       authenticated: false,
       execution: true
     });
-    const requestUrl = new URL(url2);
-    requestUrl.search = "";
-    return result({ request_url: requestUrl.toString(), method, response });
+    return result({ script_url: scriptUrl(api2, script_id), method, response });
   }));
   server.registerTool("flow_execute_code", {
-    description: "执行未发布的非脚本 JavaScript，仅在用户明确要求测试时使用。请求固定为 POST /flow/codeblock，body.input 原样注入全局 input；代码和 code_base64 二选一。不会把 MCP 认证信息写入用户脚本输入，也不会创建或发布脚本。",
+    description: "执行未发布的非脚本 JavaScript，仅在用户明确要求测试时使用。结果包含完整 execution_url。请求固定为 POST /flow/codeblock，body.input 原样注入全局 input；代码和 code_base64 二选一。不会把 MCP 认证信息写入用户脚本输入，也不会创建或发布脚本。",
     inputSchema: {
       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 二选一。"),
@@ -28897,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.1",
+  "version": "0.1.2",
   "description": "Flow Codeblock Rust+Bun stdio MCP Server for script management and execution.",
   "license": "MIT",
   "repository": {