magic-builder 1.2.0 → 1.3.0

package/README.md

@@ -72,6 +72,7 @@ This includes:
 ```text
 magic-token
 magic-apps.json
+widget-publish.json
 ```
 
 ## Common Commands
@@ -145,6 +146,15 @@ magic-builder performance --review-url <people-review-url> --markdown ./performa
 
 With `--review-url`, the CLI loads the operator and tenant from `/perf/api/user/settings`, then reuses the current draft version, template, units, fields, source ids, and root review id from `/perf/api/foundation/draft`. Business ids are not hard-coded into the generated request.
 
+Formally submit the latest draft to the current review stage:
+
+```bash
+magic-builder perf submit --review-url <people-review-url> --template-group-id <id> --dry-run
+magic-builder perf submit --review-url <people-review-url> --template-group-id <id> --yes
+```
+
+The command posts to `/perf/api/review/v2/stage`. It always reloads the latest draft, derives the root review, template, stage, and work units from it, and serializes rich-text values into the stage payload. `--template-group-id` is optional when the draft already contains it. A real submission requires `--yes`; use `--dry-run` to inspect the payload first.
+
 Extract Cookie from a copied curl command. This is a top-level general-purpose command. The default output is `./cookie.txt`; the file is created with mode `0600`:
 
 ```bash
@@ -160,6 +170,43 @@ magic-builder doc create --html app.html --title "Demo"
 magic-builder doc append --html app.html --doc-token <docx-token>
 ```
 
+Publish a document widget draft as a new app version:
+
+```bash
+magic-builder widget-publish \
+  --app-id cli_a98afe875979500d \
+  --block-type-id blk_6900429af84180025ce76527 \
+  --change-log "修复 HTML Box 高度反馈循环"
+```
+
+The command reads Open Platform browser authentication from
+`~/.magic-builder/widget-publish.json` by default:
+
+```json
+{
+  "cookie": "open_locale=zh-CN; session=...",
+  "csrfToken": "...",
+  "timezoneOffset": -480
+}
+```
+
+Keep this file local and set its mode to `0600`. Use `--config <file>` to select
+another file. The command fetches the widget detail, selects the latest uploaded
+test package before the existing draft/current package, updates the widget pkgId,
+increments the latest patch version, creates the app
+version with the application's actual default abilities and audit settings, and
+submits it for publishing. Use `--version` to override the generated
+version or `--dry-run` to inspect the payload without updating or publishing.
+
+You can generate the local config directly from a browser-copied curl command:
+
+```bash
+magic-builder extract-cookie --curl-file ./widget-request.curl --widget-publish
+```
+
+This extracts only the Cookie and `x-csrf-token`, writes them to the default
+widget publish config with mode `0600`, and does not print either secret.
+
 Install or update the Magic Builder Codex skill:
 
 ```bash

package/bin/magic-builder.js

@@ -14,6 +14,7 @@ const COMMANDS = {
   feedback: require('../src/commands/feedback'),
   performance: require('../src/commands/performance'),
   perf: require('../src/commands/performance'),
+  'widget-publish': require('../src/commands/widget-publish'),
   'extract-cookie': require('../src/commands/extract-cookie'),
   skill: require('../src/commands/skill'),
   version: require('../src/commands/version'),

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "magic-builder",
-  "version": "1.2.0",
-  "description": "CLI for Magic Builder — publish pages, functions, files, and performance drafts",
+  "version": "1.3.0",
+  "description": "CLI for Magic Builder — publish pages, functions, files, and performance reviews",
   "bin": {
     "magic-builder": "bin/magic-builder.js",
     "magic-cli": "bin/magic-builder.js",
     "miaobi": "bin/magic-builder.js"
   },
   "main": "./src/index.js",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=18.0.0"
   },

package/src/commands/config.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { CONFIG_DIR, getAppsConfigPath, getBaseUrl } = require('../lib/config');
+const { CONFIG_DIR, getAppsConfigPath, getBaseUrl, getWidgetPublishConfigPath } = require('../lib/config');
 const { TOKEN_FILE, showToken } = require('../lib/auth');
 const { success, fail } = require('../lib/output');
 
@@ -10,6 +10,7 @@ async function run(args, opts) {
   success({
     base_url: getBaseUrl(opts),
     config_dir: CONFIG_DIR,
+    widget_publish_config_file: getWidgetPublishConfigPath(),
     token_file: TOKEN_FILE,
     apps_config_file: getAppsConfigPath(),
     token: showToken() || '',

package/src/commands/extract-cookie.js

@@ -1,7 +1,8 @@
 'use strict';
 
-const { existsSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
+const { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
 const { basename, dirname, resolve } = require('path');
+const { getWidgetPublishConfigPath } = require('../lib/config');
 const { success, fail } = require('../lib/output');
 
 function run(args, opts) {
@@ -11,9 +12,24 @@ function run(args, opts) {
   const cookie = extractCookieFromCurl(curl);
   if (!cookie) fail('No Cookie found in curl. Expected -b/--cookie or a Cookie request header.', 'E_INVALID_ARGS');
 
+  if (opts.widgetPublish) {
+    const csrfToken = extractHeaderFromCurl(curl, 'x-csrf-token');
+    if (!csrfToken) fail('No x-csrf-token header found in curl.', 'E_INVALID_ARGS');
+    const output = resolve(String(opts.out || getWidgetPublishConfigPath()));
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, `${JSON.stringify({ cookie, csrfToken, timezoneOffset: -480 }, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    chmodSync(output, 0o600);
+    success({ path: output, filename: basename(output), widgetPublish: true }, opts);
+    return;
+  }
+
   const output = resolveOutput(opts.out, opts.outDir);
   mkdirSync(dirname(output), { recursive: true });
   writeFileSync(output, `${cookie}\n`, { encoding: 'utf8', mode: 0o600 });
+  chmodSync(output, 0o600);
   success({ path: output, filename: basename(output), cookieCount: cookie.split(';').filter(Boolean).length }, opts);
 }
 
@@ -43,6 +59,21 @@ function extractCookieFromCurl(curl) {
   return '';
 }
 
+function extractHeaderFromCurl(curl, headerName) {
+  const expected = String(headerName || '').toLowerCase();
+  const tokens = tokenizeShell(String(curl || '').replace(/\\\r?\n/g, ' '));
+  for (let i = 0; i < tokens.length; i++) {
+    let header = '';
+    if (tokens[i] === '-H' || tokens[i] === '--header') header = tokens[i + 1] || '';
+    else if (tokens[i].startsWith('--header=')) header = tokens[i].slice('--header='.length);
+    if (!header) continue;
+    const separator = header.indexOf(':');
+    if (separator < 0 || header.slice(0, separator).trim().toLowerCase() !== expected) continue;
+    return header.slice(separator + 1).trim();
+  }
+  return '';
+}
+
 function normalizeCookie(raw) {
   return String(raw || '').replace(/^cookie\s*:\s*/i, '').trim();
 }
@@ -82,4 +113,4 @@ function resolveOutput(out, outDir) {
   return resolve(String(outDir || process.cwd()), 'cookie.txt');
 }
 
-module.exports = { run, extractCookieFromCurl, resolveOutput };
+module.exports = { run, extractCookieFromCurl, extractHeaderFromCurl, resolveOutput };

package/src/commands/performance.js

@@ -6,23 +6,41 @@ const { success, fail } = require('../lib/output');
 
 const DEFAULTS = {
   endpoint: 'https://people.bytedance.net/perf/api/foundation/v2/draft',
+  submitEndpoint: 'https://people.bytedance.net/perf/api/review/v2/stage',
   settingsEndpoint: 'https://people.bytedance.net/perf/api/user/settings',
   draftEndpoint: 'https://people.bytedance.net/perf/api/foundation/draft',
 };
 
 async function run(args, opts) {
-  if (args.length) fail('Usage: magic-builder performance --cookie <content|file> --markdown <content|file|url>', 'E_INVALID_ARGS');
+  const action = args[0] || 'draft';
+  if (args.length > 1 || !['draft', 'submit'].includes(action)) {
+    fail('Usage: magic-builder performance [submit] --review-url <url> --cookie <content|file>', 'E_INVALID_ARGS');
+  }
 
   const cookie = readCookie(opts.cookie, opts.cookieFile);
   if (!cookie) fail('Missing Cookie. Use --cookie <content|file> or --cookie-file <file>.', 'E_INVALID_ARGS');
 
-  const markdown = await readMarkdown(opts.markdown, opts.markdownFile);
-  if (!markdown.trim()) fail('Missing Markdown. Use --markdown <content|file|url>, --markdown-file <file>, or stdin.', 'E_INVALID_ARGS');
-
   const csrf = getCookie(cookie, 'x-f-csrf');
   if (!csrf) fail('Cookie does not contain x-f-csrf.', 'E_INVALID_ARGS');
 
   const config = await resolveConfig(opts, cookie);
+  if (action === 'submit') {
+    const payload = buildStagePayloadFromDraft(config.draft, config);
+    if (opts.dryRun) {
+      success({ dryRun: true, action: 'submit', endpoint: config.submitEndpoint, payload }, opts);
+      return;
+    }
+    if (!opts.yes) {
+      fail('Formal performance submission requires --yes. Run with --dry-run first to review the payload.', 'E_CONFIRM_REQUIRED');
+    }
+    const data = await postPerformance(config.submitEndpoint, payload, cookie, csrf, config);
+    success(data, opts);
+    return;
+  }
+
+  const markdown = await readMarkdown(opts.markdown, opts.markdownFile);
+  if (!markdown.trim()) fail('Missing Markdown. Use --markdown <content|file|url>, --markdown-file <file>, or stdin.', 'E_INVALID_ARGS');
+
   const payload = config.draft
     ? buildPayloadFromDraft(markdown, config.draft, config)
     : buildPayload(markdown, config);
@@ -31,7 +49,13 @@ async function run(args, opts) {
     return;
   }
 
-  const response = await fetch(config.endpoint, {
+  const data = await postPerformance(config.endpoint, payload, cookie, csrf, config);
+  success(data, opts);
+}
+
+async function postPerformance(endpoint, payload, cookie, csrf, config) {
+  assertPeoplePerfEndpoint(endpoint);
+  const response = await fetch(endpoint, {
     method: 'POST',
     headers: {
       accept: 'application/json, text/plain, */*',
@@ -55,7 +79,7 @@ async function run(args, opts) {
     error.code = response.status === 401 || response.status === 403 ? 'E_AUTH_FAILED' : 'E_REQUEST_FAILED';
     throw error;
   }
-  success(data === null ? text : data, opts);
+  return data === null ? text : data;
 }
 
 function readCookie(value, file) {
@@ -119,6 +143,7 @@ async function resolveConfig(opts, cookie) {
     if (!draftResponse?.success || !draftResponse?.data) fail('Unable to load the current performance draft.', 'E_REQUEST_FAILED');
     return {
       endpoint: String(opts.endpoint || DEFAULTS.endpoint),
+      submitEndpoint: String(opts.submitEndpoint || DEFAULTS.submitEndpoint),
       reviewId: review.reviewId,
       formId: review.formId,
       operatorId,
@@ -126,6 +151,7 @@ async function resolveConfig(opts, cookie) {
       referer: review.referer,
       uid: String(opts.uid || `magic-builder-${Date.now()}`),
       version: opts.draftVersion === undefined ? undefined : Number(opts.draftVersion),
+      templateGroupId: String(opts.templateGroupId || ''),
       draft: draftResponse.data,
     };
   }
@@ -137,6 +163,7 @@ async function resolveConfig(opts, cookie) {
   }
   return {
     endpoint: String(opts.endpoint || DEFAULTS.endpoint),
+    submitEndpoint: String(opts.submitEndpoint || DEFAULTS.submitEndpoint),
     reviewId: String(opts.reviewId),
     formId: String(opts.formId),
     templateId: String(opts.templateId),
@@ -147,6 +174,7 @@ async function resolveConfig(opts, cookie) {
     sourceId: String(opts.sourceId),
     fieldSourceId: String(opts.fieldSourceId),
     rootReviewId: String(opts.rootReviewId),
+    templateGroupId: String(opts.templateGroupId || ''),
     version: Number(opts.draftVersion || opts.version),
     tenantId: String(opts.tenantId || ''),
     referer: String(opts.referer || `https://people.bytedance.net/performance/perf/review/${opts.reviewId}/${opts.formId}?mode=editable`),
@@ -172,6 +200,7 @@ function parseReviewLocation(value, reviewId, formId) {
 }
 
 async function requestJson(url, cookie, referer) {
+  assertPeoplePerfEndpoint(url);
   const response = await fetch(url, {
     headers: { accept: 'application/json, text/plain, */*', cookie, referer },
   });
@@ -181,6 +210,16 @@ async function requestJson(url, cookie, referer) {
   return data;
 }
 
+function assertPeoplePerfEndpoint(value) {
+  const url = new URL(String(value || ''));
+  if (url.origin !== 'https://people.bytedance.net' || !url.pathname.startsWith('/perf/api/')) {
+    const error = new Error('Performance API endpoint must use https://people.bytedance.net/perf/api/.');
+    error.code = 'E_INVALID_ARGS';
+    throw error;
+  }
+  return url;
+}
+
 function buildPayload(markdown, config) {
   const now = Date.now();
   const sections = splitMarkdownSections(markdown);
@@ -256,6 +295,56 @@ function buildPayloadFromDraft(markdown, draft, config) {
   };
 }
 
+function buildStagePayloadFromDraft(draft, config = {}) {
+  if (!draft?.data?.keyWorks) fail('Current draft does not contain keyWorks.', 'E_REQUEST_FAILED');
+  const keyWorks = structuredClone(draft.data.keyWorks);
+  const stageId = String(config.stageId || config.formId || '');
+  const rootReviewId = String(config.rootReviewId || draft.data.rootReviewId || draft.data.root_review_id || '');
+  const templateId = String(config.templateId || keyWorks.template_id || keyWorks.templateId || '');
+  const templateGroupId = String(
+    config.templateGroupId
+      || draft.data.templateGroupId
+      || draft.data.template_group_id
+      || keyWorks.templateGroupId
+      || keyWorks.template_group_id
+      || ''
+  );
+  const missing = [
+    ['root_review_id', rootReviewId],
+    ['template_id', templateId],
+    ['template_group_id', templateGroupId],
+    ['stage_id', stageId],
+  ].filter(([, value]) => !value).map(([name]) => name);
+  if (missing.length) {
+    fail(`Unable to build formal submission payload; missing ${missing.join(', ')}. Pass --template-group-id when it is absent from the draft.`, 'E_INVALID_ARGS');
+  }
+  if (!Array.isArray(keyWorks.units) || !keyWorks.units.length) {
+    fail('Current draft does not contain keyWorks.units.', 'E_REQUEST_FAILED');
+  }
+  return {
+    root_review_id: rootReviewId,
+    template_id: templateId,
+    template_group_id: templateGroupId,
+    stage_id: stageId,
+    stage_ids: [stageId],
+    data: { units: keyWorks.units.filter(unit => unit?.type === 'object').map(serializeStageUnit) },
+  };
+}
+
+function serializeStageUnit(unit) {
+  const output = structuredClone(unit);
+  for (const field of output.fields || []) {
+    delete field.json_value;
+    for (const group of field.sub_units || []) {
+      for (const subUnit of group || []) {
+        if (subUnit?.value && typeof subUnit.value !== 'string') subUnit.value = JSON.stringify(subUnit.value);
+        delete subUnit.json_value;
+      }
+    }
+  }
+  return output;
+}
+
 function createSubUnits(markdown, textFieldId, sourceId, now = Date.now()) {
   return splitMarkdownSections(markdown).map((section, index) => {
     const value = { '0': { ops: markdownToDelta(section), zoneId: '0', zoneType: 'Z' } };
@@ -273,17 +362,28 @@ function splitMarkdownSections(markdown) {
   for (const line of lines) {
     if (/^##\s+/.test(line)) {
       if (current.some(item => item.trim()) && !current.every(item => /^#\s+/.test(item) || !item.trim())) {
-        sections.push(current.join('\n').trim());
+        sections.push(cleanMarkdownSection(current.join('\n')));
       }
       current = [`# ${line.replace(/^##\s+/, '')}`];
     } else if (current.length || !/^#\s+/.test(line)) {
       current.push(line);
     }
   }
-  if (current.some(item => item.trim())) sections.push(current.join('\n').trim());
+  if (current.some(item => item.trim())) sections.push(cleanMarkdownSection(current.join('\n')));
   return sections.length ? sections : [text];
 }
 
+function cleanMarkdownSection(value) {
+  const cleaned = String(value || '').trim().replace(/(?:\n\s*(?:---+|\*\*\*+|___+)\s*)+$/u, '').trim();
+  return cleaned.split('\n').map((line, index) => {
+    if (index === 0) return line.replace(/^#{1,6}\s+/, '# ');
+    if (!line.trim() || /^\s*(?:[-*+]\s+|\d+[.)]\s+)/u.test(line)) return line;
+    if (/^\s*[-*+]\S/u.test(line)) return line.replace(/^(\s*[-*+])\s*/u, '$1 ');
+    if (/^\s*\d+[.)]\S/u.test(line)) return line.replace(/^(\s*\d+[.)])\s*/u, '$1 ');
+    return `- ${line.trim()}`;
+  }).join('\n');
+}
+
 function markdownToDelta(markdown) {
   const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
   const ops = [];
@@ -298,18 +398,29 @@ function markdownToDelta(markdown) {
       ops.push({ insert: '\n', attributes: { 'code-block': true } });
       continue;
     }
+    if (!line.trim()) continue;
     const heading = line.match(/^(#{1,6})\s+(.+)$/);
-    const unordered = line.match(/^\s*[-*+]\s+(.+)$/);
-    const ordered = line.match(/^\s*\d+[.)]\s+(.+)$/);
+    const unordered = line.match(/^(\s*)[-*+]\s+(.+)$/);
+    const ordered = line.match(/^(\s*)(\d+)[.)]\s+(.+)$/);
     const quote = line.match(/^\s*>\s?(.*)$/);
-    const content = heading?.[2] ?? unordered?.[1] ?? ordered?.[1] ?? quote?.[1] ?? line;
-    appendInline(ops, content);
-    const attributes = heading ? { header: heading[1].length }
-      : unordered ? { list: 'bullet' }
-        : ordered ? { list: 'ordered' }
-          : quote ? { blockquote: true }
-            : undefined;
-    ops.push(attributes ? { insert: '\n', attributes } : { insert: '\n' });
+    if (heading) {
+      ops.push({ insert: `${heading[1]} ${heading[2]}`, attributes: { bold: true } });
+      ops.push({ insert: '\n' });
+      continue;
+    }
+    if (unordered || ordered) {
+      const indent = (unordered?.[1] || ordered?.[1] || '').replace(/\t/g, '  ').length;
+      const level = Math.max(1, Math.floor(indent / 2) + 1);
+      const list = `${unordered ? 'bullet' : 'ordered'}${level}`;
+      const marker = unordered ? '*' : `${ordered[2]}.`;
+      const content = unordered?.[2] ?? ordered?.[3] ?? '';
+      ops.push({ insert: marker, attributes: { list, lmkr: '1' } });
+      appendInline(ops, content);
+      ops.push({ insert: '\n' });
+      continue;
+    }
+    appendInline(ops, quote?.[1] ?? line);
+    ops.push(quote ? { insert: '\n', attributes: { blockquote: true } } : { insert: '\n' });
   }
   if (ops.length > 1 && lines.at(-1) === '') ops.pop();
   return ops.length ? ops : [{ insert: '\n' }];
@@ -334,4 +445,4 @@ function parseJson(text) {
   try { return text ? JSON.parse(text) : {}; } catch (_) { return null; }
 }
 
-module.exports = { run, readCookie, normalizeCookie, getCookie, parseReviewLocation, splitMarkdownSections, markdownToDelta, buildPayload, buildPayloadFromDraft };
+module.exports = { run, readCookie, normalizeCookie, getCookie, parseReviewLocation, splitMarkdownSections, markdownToDelta, buildPayload, buildPayloadFromDraft, buildStagePayloadFromDraft, assertPeoplePerfEndpoint };

package/src/commands/skill.js

@@ -142,7 +142,7 @@ function readSkillMetadata(skillDir) {
   if (!fs.existsSync(skillPath)) return { exists: false, name: null, version: null, path: skillPath };
   const text = fs.readFileSync(skillPath, 'utf8');
   const nameMatch = text.match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m);
-  const versionMatch = text.match(/^version:\s*["']?([^"'\n]+)["']?\s*$/m);
+  const versionMatch = text.match(/^\s*version:\s*["']?([^"'\n]+)["']?\s*$/m);
   return {
     exists: true,
     name: nameMatch ? nameMatch[1].trim() : null,

package/src/commands/widget-publish.js

@@ -0,0 +1,339 @@
+'use strict';
+
+const { existsSync, readFileSync } = require('fs');
+const { resolve } = require('path');
+const { getWidgetPublishConfigPath } = require('../lib/config');
+const { success, fail } = require('../lib/output');
+
+const DEFAULT_ORIGIN = 'https://open.larkoffice.com';
+
+async function run(args, opts) {
+  if (args.length) {
+    fail('Usage: magic-builder widget-publish --app-id <id> --block-type-id <id>', 'E_INVALID_ARGS');
+  }
+
+  const appId = String(opts.appId || '').trim();
+  const blockTypeId = String(opts.blockTypeId || '').trim();
+  if (!appId || !blockTypeId) {
+    fail('Missing --app-id or --block-type-id.', 'E_INVALID_ARGS');
+  }
+
+  const auth = loadPublishAuth(opts.config);
+  const client = createOpenPlatformClient(auth, opts.origin || DEFAULT_ORIGIN);
+  const detail = await client.post(`/developers/v2/block/detail/${appId}/${blockTypeId}`, {});
+  const block = extractBlock(detail);
+  const pkgId = extractDraftPkgId(detail, block);
+  if (!pkgId) throw commandError('Draft widget pkgId was not found in block detail.', 'E_INVALID_RESPONSE');
+
+  const updatePayload = { block: buildBlockUpdatePayload(block, pkgId, blockTypeId) };
+  if (!opts.dryRun) {
+    await client.post(`/developers/v2/block/detail/update/${appId}/${blockTypeId}`, updatePayload);
+  }
+  const versionChangeResponse = await client.post(`/developers/v1/app_version/change/${appId}`, {});
+  const versionChange = unwrapData(versionChangeResponse) || {};
+  const versionsResponse = await client.post(`/developers/v1/app_version/list/${appId}`, {});
+  const versions = extractVersionList(versionsResponse);
+  const appVersion = opts.version || getNextPatchVersion(versions);
+  const createPayload = buildCreateVersionPayload(
+    appVersion,
+    opts.changeLog,
+    getLatestVersion(versions),
+    versionChange
+  );
+
+  if (opts.dryRun) {
+    success({
+      dryRun: true,
+      appId,
+      blockTypeId,
+      pkgId,
+      appVersion,
+      updatePayload,
+      createPayload,
+    }, opts);
+    return;
+  }
+
+  const createResponse = await client.post(`/developers/v1/app_version/create/${appId}`, createPayload);
+  const appVersionId = extractAppVersionId(createResponse);
+  if (!appVersionId) throw commandError('Created app version id was not found in response.', 'E_INVALID_RESPONSE');
+
+  const publishResponse = await client.post(`/developers/v1/publish/commit/${appId}/${appVersionId}`, {});
+  success({
+    appId,
+    blockTypeId,
+    pkgId,
+    appVersion,
+    appVersionId,
+    published: true,
+    response: publishResponse,
+  }, opts);
+}
+
+function loadPublishAuth(configFile) {
+  const path = resolve(String(configFile || getWidgetPublishConfigPath()));
+  if (!existsSync(path)) {
+    throw commandError(`Widget publish config not found: ${path}`, 'E_NO_CONFIG');
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw commandError(`Invalid widget publish config: ${error.message}`, 'E_INVALID_CONFIG');
+  }
+
+  const cookie = String(config.cookie || '').trim();
+  const csrfToken = String(config.csrfToken || config.csrf_token || '').trim();
+  if (!cookie || !csrfToken) {
+    throw commandError('Widget publish config must contain cookie and csrfToken.', 'E_INVALID_CONFIG');
+  }
+  return {
+    cookie,
+    csrfToken,
+    timezoneOffset: Number.isFinite(Number(config.timezoneOffset)) ? Number(config.timezoneOffset) : -480,
+    locale: String(config.locale || 'zh-CN'),
+  };
+}
+
+function createOpenPlatformClient(auth, origin = DEFAULT_ORIGIN, fetchImpl = fetch) {
+  const baseUrl = String(origin || DEFAULT_ORIGIN).replace(/\/+$/, '');
+  return {
+    async post(path, body) {
+      const response = await fetchImpl(`${baseUrl}${path}`, {
+        method: 'POST',
+        headers: {
+          accept: '*/*',
+          'accept-language': `${auth.locale},zh;q=0.9`,
+          'cache-control': 'no-cache',
+          'content-type': 'application/json',
+          cookie: auth.cookie,
+          origin: baseUrl,
+          pragma: 'no-cache',
+          referer: getRequestReferer(baseUrl, path),
+          'x-csrf-token': auth.csrfToken,
+          'x-timezone-offset': String(auth.timezoneOffset),
+        },
+        body: JSON.stringify(body || {}),
+      });
+      const text = await response.text();
+      const data = parseJson(text);
+      if (!response.ok || isApiFailure(data)) {
+        const reason = data?.msg || data?.message || `HTTP ${response.status}`;
+        throw commandError(
+          `Open Platform request failed at ${path}: ${reason}`,
+          response.status === 401 || response.status === 403 ? 'E_AUTH_FAILED' : 'E_REQUEST_FAILED'
+        );
+      }
+      return data ?? text;
+    },
+  };
+}
+
+function extractBlock(response) {
+  const data = unwrapData(response);
+  return data?.block || data?.detail?.block || data?.blockDetail?.block || data?.detail || data;
+}
+
+function extractDraftPkgId(response, block = {}) {
+  const candidates = [
+    response?.data?.blockVersions?.testVersion?.id,
+    response?.data?.blockVersions?.testVersion?.pkgId,
+    response?.data?.blockVersions?.draftVersion?.id,
+    response?.data?.blockVersions?.draftVersion?.pkgId,
+    block?.draftVersion?.pkgId,
+    block?.draftPkg?.pkgId,
+    block?.draftPackage?.pkgId,
+    block?.draft?.pkgId,
+    findDraftPkgId(response),
+    findValue(response, ['draftPkgId', 'draftPackageId']),
+    block?.pkgId,
+  ];
+  return String(candidates.find(Boolean) || '').trim();
+}
+
+function buildBlockUpdatePayload(block = {}, pkgId, blockTypeId) {
+  return {
+    pkgId: String(pkgId),
+    icon: block.icon || '',
+    i18nTitle: block.i18nTitle || {},
+    i18nDesc: block.i18nDesc || {},
+    status: block.status !== false,
+    blockTypeId: block.blockTypeId || block.blockTypeID || blockTypeId,
+    pkgUpdateType: Number.isFinite(Number(block.pkgUpdateType)) ? Number(block.pkgUpdateType) : 0,
+    docXHost: block.docXHost || block.docxHost || {},
+  };
+}
+
+function extractVersionList(response) {
+  const data = unwrapData(response);
+  if (Array.isArray(data)) return data;
+  for (const key of ['items', 'list', 'appVersions', 'versions']) {
+    if (Array.isArray(data?.[key])) return data[key];
+  }
+  return findArray(data, ['items', 'list', 'appVersions', 'versions']);
+}
+
+function getNextPatchVersion(versions) {
+  const parsed = versions
+    .map(item => String(item?.appVersion || item?.version || item?.versionName || item || ''))
+    .map(parseSemver)
+    .filter(Boolean)
+    .sort(compareSemver);
+  const latest = parsed.at(-1) || [1, 0, -1];
+  return `${latest[0]}.${latest[1]}.${latest[2] + 1}`;
+}
+
+function getLatestVersion(versions) {
+  return versions
+    .map(item => ({ item, version: parseSemver(item?.appVersion || item?.version || item?.versionName || item) }))
+    .filter(entry => entry.version)
+    .sort((a, b) => compareSemver(a.version, b.version))
+    .at(-1)?.item || {};
+}
+
+function buildCreateVersionPayload(
+  appVersion,
+  changeLog = '更新文档小组件版本',
+  latestVersion = {},
+  versionChange = {}
+) {
+  const shareConfig = versionChange.changeAppShareConfig?.b2cShareSplitConfigSuggest;
+  return {
+    appVersion: String(appVersion),
+    mobileDefaultAbility: versionChange.mobileDefaultAbility || latestVersion.mobileDefaultAbility || 'bot',
+    pcDefaultAbility: versionChange.pcDefaultAbility || latestVersion.pcDefaultAbility || 'bot',
+    changeLog: String(changeLog || '更新文档小组件版本'),
+    visibleSuggest: latestVersion.visibleSuggest || { departments: [], members: [], groups: [], isAll: 1 },
+    applyReasonConfig: versionChange.applyReasonConfig || latestVersion.applyReasonConfig || {
+      apiPrivilegeNeedReason: true,
+      contactPrivilegeNeedReason: true,
+      dataPrivilegeReasonMap: {},
+      visibleScopeNeedReason: true,
+      apiPrivilegeReasonMap: {},
+      contactPrivilegeReason: '',
+      isDataPrivilegeExpandMap: { vc: false },
+      visibleScopeReason: '',
+      dataPrivilegeNeedReason: true,
+      isAutoAudit: false,
+      isContactExpand: false,
+    },
+    b2cShareSplitConfigSuggest: shareConfig || latestVersion.b2cShareSplitConfigSuggest || {
+      b2cGroupChatShareEnable: false,
+      b2cP2PChatShareEnable: false,
+      b2cP2PChatNeedAudit: false,
+    },
+    autoPublish: false,
+    blackVisibleSuggest: latestVersion.blackVisibleSuggest || { departments: [], members: [], groups: [], isAll: 0 },
+  };
+}
+
+function extractAppVersionId(response) {
+  const data = unwrapData(response);
+  return String(
+    data?.appVersionId
+    || data?.versionId
+    || data?.appVersion?.id
+    || data?.version?.id
+    || data?.id
+    || findValue(data, ['appVersionId', 'versionId'])
+    || ''
+  ).trim();
+}
+
+function unwrapData(value) {
+  let current = value;
+  for (let i = 0; i < 3; i++) {
+    if (!current || typeof current !== 'object' || Array.isArray(current) || !('data' in current)) break;
+    current = current.data;
+  }
+  return current;
+}
+
+function findValue(value, names, predicate = () => true, path = '') {
+  if (!value || typeof value !== 'object') return '';
+  for (const [name, child] of Object.entries(value)) {
+    const childPath = path ? `${path}.${name}` : name;
+    if (names.includes(name) && child != null && predicate({ name, path: childPath })) return child;
+    const nested = findValue(child, names, predicate, childPath);
+    if (nested) return nested;
+  }
+  return '';
+}
+
+function findDraftPkgId(value, path = '') {
+  if (!value || typeof value !== 'object') return '';
+  const marker = [
+    path,
+    value.status,
+    value.versionStatus,
+    value.pkgStatus,
+    value.type,
+    value.name,
+  ].filter(Boolean).join(' ');
+  if (/draft|草稿/i.test(marker) && value.pkgId) return value.pkgId;
+  for (const [name, child] of Object.entries(value)) {
+    const found = findDraftPkgId(child, path ? `${path}.${name}` : name);
+    if (found) return found;
+  }
+  return '';
+}
+
+function findArray(value, names) {
+  if (!value || typeof value !== 'object') return [];
+  for (const [name, child] of Object.entries(value)) {
+    if (names.includes(name) && Array.isArray(child)) return child;
+    const found = findArray(child, names);
+    if (found.length) return found;
+  }
+  return [];
+}
+
+function getRequestReferer(baseUrl, path) {
+  const blockMatch = path.match(/\/block\/detail(?:\/update)?\/([^/]+)\/([^/]+)/);
+  if (blockMatch) return `${baseUrl}/app/${blockMatch[1]}/blocks/${blockMatch[2]}`;
+  const publishMatch = path.match(/\/publish\/commit\/([^/]+)\/([^/]+)/);
+  if (publishMatch) return `${baseUrl}/app/${publishMatch[1]}/version/${publishMatch[2]}`;
+  const appMatch = path.match(/\/app_version\/(?:list|create)\/([^/]+)/);
+  if (appMatch) return `${baseUrl}/app/${appMatch[1]}/version/create`;
+  return `${baseUrl}/`;
+}
+
+function parseSemver(value) {
+  const match = String(value || '').trim().match(/^(\d+)\.(\d+)\.(\d+)$/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function compareSemver(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text); } catch (_) { return null; }
+}
+
+function isApiFailure(data) {
+  if (!data || typeof data !== 'object') return false;
+  if ('code' in data && ![0, '0', 200, '200'].includes(data.code)) return true;
+  return data.success === false;
+}
+
+function commandError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+module.exports = {
+  run,
+  loadPublishAuth,
+  createOpenPlatformClient,
+  extractBlock,
+  extractDraftPkgId,
+  buildBlockUpdatePayload,
+  extractVersionList,
+  getNextPatchVersion,
+  getLatestVersion,
+  buildCreateVersionPayload,
+  extractAppVersionId,
+};

package/src/index.js

@@ -15,6 +15,7 @@ module.exports = {
     feedback: require('./commands/feedback'),
     performance: require('./commands/performance'),
     perf: require('./commands/performance'),
+    widgetPublish: require('./commands/widget-publish'),
     extractCookie: require('./commands/extract-cookie'),
     skill: require('./commands/skill'),
     version: require('./commands/version'),

package/src/lib/config.js

@@ -8,6 +8,7 @@ const DEFAULT_BASE_URL = 'https://magic.solutionsuite.cn';
 const CONFIG_DIR = path.join(os.homedir(), '.magic-builder');
 const APPS_CONFIG_FILE = 'magic-apps.json';
 const LEGACY_APPS_CONFIG_FILE = '.magic-apps.json';
+const WIDGET_PUBLISH_CONFIG_FILE = 'widget-publish.json';
 
 function normalizeMagicBaseUrl(value) {
   const raw = String(value || DEFAULT_BASE_URL).trim().replace(/\/+$/, '');
@@ -23,6 +24,10 @@ function getAppsConfigPath() {
   return path.join(CONFIG_DIR, APPS_CONFIG_FILE);
 }
 
+function getWidgetPublishConfigPath() {
+  return path.join(CONFIG_DIR, WIDGET_PUBLISH_CONFIG_FILE);
+}
+
 function loadAppsConfig() {
   const p = fs.existsSync(getAppsConfigPath())
     ? getAppsConfigPath()
@@ -38,4 +43,13 @@ function saveAppsConfig(config) {
   fs.writeFileSync(getAppsConfigPath(), JSON.stringify(config, null, 2));
 }
 
-module.exports = { DEFAULT_BASE_URL, CONFIG_DIR, normalizeMagicBaseUrl, getBaseUrl, getAppsConfigPath, loadAppsConfig, saveAppsConfig };
+module.exports = {
+  DEFAULT_BASE_URL,
+  CONFIG_DIR,
+  normalizeMagicBaseUrl,
+  getBaseUrl,
+  getAppsConfigPath,
+  getWidgetPublishConfigPath,
+  loadAppsConfig,
+  saveAppsConfig,
+};

package/src/lib/help.js

@@ -21,7 +21,8 @@ COMMANDS:
   link       Generate Magic share links
   doc        Create or append Feishu Doc HTML Box apps
   feedback   Create Magic feedback records
-  performance Submit Markdown content to a People performance draft (alias: perf)
+  performance Write or formally submit a People performance review (alias: perf)
+  widget-publish Publish a document widget draft as a new app version
   extract-cookie Extract Cookie data from a curl command
   skill      Check or update the Magic Builder skill package
   version    Show CLI version
@@ -48,6 +49,7 @@ EXAMPLES:
   magic-builder doc create --html app.html --title "Demo"
   magic-builder feedback create --feedback "打不开页面"
   magic-builder performance --cookie ./cookie.txt --markdown ./performance.md
+  magic-builder widget-publish --app-id cli_xxx --block-type-id blk_xxx
   magic-builder extract-cookie --curl-file ./request.curl
   magic-builder skill install
   magic-builder skill check-update
@@ -108,9 +110,13 @@ COMMANDS:
   feedback create --feedback-file <file> [--dry-run]
 
   performance --review-url <url> --cookie <content|file> --markdown <content|file|url> [--dry-run]
+  perf submit --review-url <url> --cookie-file <file> --template-group-id <id> [--dry-run|--yes]
   perf --review-url <url> --cookie-file <file> --markdown-file <file> [--dry-run]
 
-  extract-cookie --curl <content|file> [--out <file>|--out-dir <dir>]
+  widget-publish --app-id <id> --block-type-id <id> [--version <x.y.z>] [--change-log <text>]
+    [--config <file>] [--dry-run]
+
+  extract-cookie --curl <content|file> [--out <file>|--out-dir <dir>] [--widget-publish]
 
   skill install [--environment auto|local|cloud] [--skills-root <dir>]
   skill check-update [--environment auto|local|cloud] [--skills-root <dir>]
@@ -198,6 +204,8 @@ SYNTAX:
 
 SYNTAX:
   magic-builder performance --review-url <url> --cookie <content|file> --markdown <content|file|url>
+  magic-builder perf submit --review-url <url> --cookie-file <file> --template-group-id <id> --dry-run
+  magic-builder perf submit --review-url <url> --cookie-file <file> --template-group-id <id> --yes
   magic-builder perf --review-url <url> --cookie-file <file> --markdown-file <file>
 
 COOKIE:
@@ -210,6 +218,9 @@ DRAFT:
 OPTIONS:
   --dry-run                    Print the generated payload without sending it
   --review-url <url>           People performance review URL (recommended)
+  --template-group-id <id>     Template group id (only needed when absent from the draft)
+  --submit-endpoint <url>      Override the formal submission endpoint
+  --yes                        Confirm the irreversible formal submission
   --draft-version <number>     Override the version loaded from the current draft
   --review-id <id>             Override the performance review id
   --form-id <id>               Override the invitation/form id used by the draft key
@@ -224,12 +235,31 @@ OPTIONS:
   perf: `@HELP magic-builder/performance
 
 Alias of "magic-builder performance".
+`,
+  'widget-publish': `@HELP magic-builder/widget-publish
+
+SYNTAX:
+  magic-builder widget-publish --app-id <id> --block-type-id <id>
+    [--version <x.y.z>] [--change-log <text>] [--config <file>] [--dry-run]
+
+AUTH CONFIG:
+  Defaults to ~/.magic-builder/widget-publish.json:
+  {
+    "cookie": "open_locale=zh-CN; session=...",
+    "csrfToken": "...",
+    "timezoneOffset": -480
+  }
+
+FLOW:
+  Load widget detail and latest uploaded pkgId, update the widget package, load the app's
+  version defaults, calculate the next version, create it, then submit publishing.
 `,
   'extract-cookie': `@HELP magic-builder/extract-cookie
 
 SYNTAX:
   magic-builder extract-cookie --curl <content|file> [--out <file>]
   magic-builder extract-cookie --curl-file <file> [--out-dir <dir>]
+  magic-builder extract-cookie --curl-file <file> --widget-publish
   cat request.curl | magic-builder extract-cookie [--out <file>]
 
 OPTIONS:
@@ -237,6 +267,7 @@ OPTIONS:
   --curl-file <file>      Read curl command from a local file
   --out <file>            Output file (default: ./cookie.txt)
   --out-dir <dir>         Output directory; created when missing
+  --widget-publish        Write Cookie and x-csrf-token to the widget publish config
 `,
   skill: `@HELP magic-builder/skill