magic-builder 1.3.0 → 1.3.1

package/README.md

@@ -120,6 +120,8 @@ magic-builder file list --title logo
 magic-builder file delete --id <id>
 ```
 
+文件上传采用 `sign -> PUT -> audit confirm` 流程。预签名成功后会返回 `audit_id`，CLI 在对象上传完成后自动确认审计；确认失败时命令返回失败，重复执行确认不会新增审计记录。
+
 Generate a Magic link:
 
 ```bash
@@ -146,6 +148,18 @@ 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.
 
+Update the text fields in the self-review draft while preserving both rating fields and any omitted text:
+
+```bash
+magic-builder perf self-review --review-url <people-review-url> \
+  --good "What went well" \
+  --improve-file ./improvements.md \
+  --values-comment-file ./values-comment.md
+magic-builder perf self-review --review-url <people-review-url> --good-file ./good.md --dry-run
+```
+
+Each field can be provided as literal text or through its matching `--*-file` option. At least one field is required. The command reloads the latest `self_review` draft before every run and writes by default; `--dry-run` prints the payload without saving it.
+
 Formally submit the latest draft to the current review stage:
 
 ```bash
@@ -166,8 +180,9 @@ cat ./request.curl | magic-builder extract-cookie --out-dir ./secrets
 Create or append a Feishu document HTML Box:
 
 ```bash
-magic-builder doc create --html app.html --title "Demo"
+magic-builder doc create --html app.html --title "Demo" # defaults to --edition external
 magic-builder doc append --html app.html --doc-token <docx-token>
+magic-builder doc create --html app.html --title "ByteDance Demo" --edition bytedance
 ```
 
 Publish a document widget draft as a new app version:
@@ -215,6 +230,10 @@ magic-builder skill check-update
 magic-builder skill update
 ```
 
+Skills are installed to `~/.agents/skills` by default so Codex, Trae, Doubao,
+and other compatible agents can share them. Use `--skills-root <dir>` to
+override the destination.
+
 Check local environment:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-builder",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "CLI for Magic Builder — publish pages, functions, files, and performance reviews",
   "bin": {
     "magic-builder": "bin/magic-builder.js",

package/src/commands/config.js

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

package/src/commands/doc.js

@@ -4,7 +4,10 @@ const { readFileSync } = require('fs');
 const { execFileSync } = require('child_process');
 const { success, fail } = require('../lib/output');
 
-const HTML_BOX_COMPONENT_TYPE_ID = 'blk_6900429af84180025ce76527';
+const HTML_BOX_COMPONENT_TYPE_IDS = {
+  external: 'blk_6358a421bca0001c190a9805',
+  bytedance: 'blk_6900429af84180025ce76527',
+};
 
 async function run(args, opts) {
   const sub = args[0];
@@ -16,14 +19,17 @@ async function run(args, opts) {
   const html = readFileSync(opts.html, 'utf8');
   const record = buildRecord(opts, html);
   const identity = resolveIdentity(opts.as);
+  const { edition, componentTypeId } = resolveEdition(opts.edition);
   const created = sub === 'append'
     ? { docToken: opts.docToken, url: `https://bytedance.larkoffice.com/docx/${opts.docToken}` }
     : createDocument(opts.title, opts.summary, identity);
-  const htmlBoxBlockId = insertHtmlBox(created.docToken, record, identity);
+  const htmlBoxBlockId = insertHtmlBox(created.docToken, record, identity, componentTypeId);
 
   success({
     ok: true,
     identity,
+    edition,
+    component_type_id: componentTypeId,
     doc_token: created.docToken,
     doc_url: created.url,
     html_box_block_id: htmlBoxBlockId,
@@ -51,6 +57,16 @@ function resolveIdentity(requestedIdentity) {
   return 'bot';
 }
 
+function resolveEdition(requestedEdition) {
+  const edition = requestedEdition || 'external';
+  if (!Object.prototype.hasOwnProperty.call(HTML_BOX_COMPONENT_TYPE_IDS, edition)) {
+    const error = new Error('--edition must be external or bytedance');
+    error.code = 'E_INVALID_ARGS';
+    throw error;
+  }
+  return { edition, componentTypeId: HTML_BOX_COMPONENT_TYPE_IDS[edition] };
+}
+
 function createDocument(title, summary, identity) {
   const intro = summary || `这个妙笔应用以交互式网页的形式展示「${title}」，可直接在文档中查看和体验。`;
   const content = `<title>${escapeXml(title)}</title><p>${escapeXml(intro)}</p>`;
@@ -73,7 +89,7 @@ function createDocument(title, summary, identity) {
   };
 }
 
-function insertHtmlBox(docToken, recordObject, identity) {
+function insertHtmlBox(docToken, recordObject, identity, componentTypeId) {
   const record = JSON.stringify(recordObject);
   const resp = runJson([
     'api',
@@ -87,15 +103,18 @@ function insertHtmlBox(docToken, recordObject, identity) {
         block_type: 40,
         add_ons: {
           component_id: '',
-          component_type_id: HTML_BOX_COMPONENT_TYPE_ID,
+          component_type_id: componentTypeId,
           record,
         },
       }],
       index: -1,
     }),
   ]);
-  if (resp?.code !== 0) throw new Error(`failed to insert HTML Box: ${JSON.stringify(resp)}`);
+  if (!isSuccessfulLarkResponse(resp)) throw new Error(`failed to insert HTML Box: ${JSON.stringify(resp)}`);
   const block = resp?.data?.children?.[0];
+  if (block?.add_ons?.component_type_id && block.add_ons.component_type_id !== componentTypeId) {
+    throw new Error(`inserted HTML Box component type mismatch: ${JSON.stringify(block?.add_ons)}`);
+  }
   const returnedRecord = parseRecordValue(block?.add_ons?.record);
   if (!recordIncludes(recordObject, returnedRecord)) {
     throw new Error(`inserted HTML Box record mismatch: ${JSON.stringify(block?.add_ons)}`);
@@ -103,6 +122,10 @@ function insertHtmlBox(docToken, recordObject, identity) {
   return block?.block_id || '';
 }
 
+function isSuccessfulLarkResponse(resp) {
+  return resp?.ok === true || resp?.code === 0;
+}
+
 function runJson(commandArgs) {
   const out = execFileSync('lark-cli', commandArgs, {
     encoding: 'utf8',
@@ -149,4 +172,4 @@ function escapeXml(value) {
     .replaceAll("'", '&apos;');
 }
 
-module.exports = { run };
+module.exports = { HTML_BOX_COMPONENT_TYPE_IDS, resolveEdition, isSuccessfulLarkResponse, run };

package/src/commands/page.js

@@ -17,7 +17,103 @@ async function run(args, opts) {
   if (sub === 'list') return list(opts);
   if (sub === 'export') return exportApps(opts);
   if (sub === 'delete') return deletePage(opts);
-  fail('Usage: magic-builder page <publish|list|export|delete>', 'E_INVALID_ARGS');
+  if (sub === 'collaborators') return collaborators(args.slice(1), opts);
+  if (sub === 'access') return access(args.slice(1), opts);
+  fail('Usage: magic-builder page <publish|list|export|delete|collaborators|access>', 'E_INVALID_ARGS');
+}
+
+async function authenticatedRequest(opts, endpoint, requestOpts = {}) {
+  let token;
+  try { token = await getToken(opts); } catch (e) { fail(e.message, 'E_NO_TOKEN', 2); }
+  try { return await request(`${getBaseUrl(opts)}${endpoint}`, { token, ...requestOpts }); }
+  catch (e) { failFromHttpError(e); }
+}
+
+function requiredPageId(opts, command) {
+  const id = normalizeId(opts.id);
+  if (!id) fail(`Missing --id. Usage: magic-builder page ${command} --id <id>`, 'E_INVALID_ARGS');
+  return id;
+}
+
+function readJsonFile(file) {
+  if (!file) return null;
+  if (!fs.existsSync(file)) fail(`File not found: ${file}`, 'E_NOT_FOUND');
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { fail(`Invalid JSON file: ${e.message}`, 'E_INVALID_ARGS'); }
+}
+
+function parseIds(value, pattern, label, allowEmpty = false) {
+  const raw = Array.isArray(value) ? value : String(value ?? '').split(/[,，;；\n\r\t|]/);
+  const values = Array.from(new Set(raw.map((item) => String(item || '').trim()).filter(Boolean)));
+  const invalid = values.filter((id) => !pattern.test(id));
+  if (invalid.length) fail(`Invalid ${label}: ${invalid.join(', ')}`, 'E_INVALID_ARGS');
+  if (!allowEmpty && !values.length) fail(`Missing ${label}`, 'E_INVALID_ARGS');
+  return values;
+}
+
+async function collaborators(args, opts) {
+  const action = String(args[0] || '').toLowerCase();
+  const id = requiredPageId(opts, `collaborators ${action || '<list|add|remove|set>'}`);
+  const endpoint = `/api/html-box/${encodeURIComponent(id)}/collaborators`;
+  if (action === 'list') {
+    const res = await authenticatedRequest(opts, endpoint);
+    if (res.code !== 0) fail(res.msg || 'Collaborator query failed', 'E_COLLABORATORS_FAILED');
+    return success(res.data || res, opts);
+  }
+  if (!['add', 'remove', 'set'].includes(action)) fail('Usage: magic-builder page collaborators <list|add|remove|set> --id <id>', 'E_INVALID_ARGS');
+  const file = readJsonFile(opts.file);
+  const openIds = parseIds(file?.open_ids ?? file?.openIds ?? opts.openIds, /^ou_[A-Za-z0-9_-]+$/, 'open_id');
+  const res = await authenticatedRequest(opts, endpoint, { method: 'PATCH', body: { operation: action, open_ids: openIds } });
+  if (res.code !== 0) fail(res.msg || 'Collaborator update failed', 'E_COLLABORATORS_FAILED');
+  success(res.data || res, opts);
+}
+
+function parseBoolean(value, label) {
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (['true', '1', 'yes', 'on', 'enabled'].includes(normalized)) return true;
+  if (['false', '0', 'no', 'off', 'disabled'].includes(normalized)) return false;
+  fail(`${label} must be true or false`, 'E_INVALID_ARGS');
+}
+
+async function access(args, opts) {
+  const action = String(args[0] || '').toLowerCase();
+  const id = requiredPageId(opts, `access ${action || '<get|enable|disable|require-login|users|groups|set>'}`);
+  const endpoint = `/api/html-box/${encodeURIComponent(id)}/access`;
+  if (action === 'get') {
+    const res = await authenticatedRequest(opts, endpoint);
+    if (res.code !== 0) fail(res.msg || 'Access query failed', 'E_ACCESS_FAILED');
+    return success(res.data || res, opts);
+  }
+  let body;
+  if (action === 'enable' || action === 'disable') {
+    body = { access_control_enabled: action === 'enable' };
+  } else if (action === 'require-login') {
+    if (opts.enabled === undefined) fail('Missing --enabled true|false', 'E_INVALID_ARGS');
+    body = { require_feishu_login: parseBoolean(opts.enabled, '--enabled') };
+  } else if (action === 'users' || action === 'groups') {
+    const operation = String(args[1] || '').toLowerCase();
+    if (!['add', 'remove', 'set'].includes(operation)) fail(`Usage: magic-builder page access ${action} <add|remove|set> --id <id>`, 'E_INVALID_ARGS');
+    const file = readJsonFile(opts.file);
+    const isUsers = action === 'users';
+    const source = isUsers ? (file?.open_ids ?? file?.user_open_ids ?? opts.openIds) : (file?.chat_ids ?? file?.group_chat_ids ?? opts.chatIds);
+    const ids = parseIds(source, isUsers ? /^ou_[A-Za-z0-9_-]+$/ : /^oc_[A-Za-z0-9_-]+$/, isUsers ? 'open_id' : 'chat_id', operation === 'set');
+    body = { operation, target: action, [isUsers ? 'access_users' : 'access_groups']: ids.map((value) => ({ id: value })) };
+  } else if (action === 'set') {
+    const file = readJsonFile(opts.file);
+    if (!file || typeof file !== 'object' || Array.isArray(file)) fail('Missing --file <access.json>', 'E_INVALID_ARGS');
+    body = {};
+    if (Object.prototype.hasOwnProperty.call(file, 'access_control_enabled')) body.access_control_enabled = parseBoolean(file.access_control_enabled, 'access_control_enabled');
+    if (Object.prototype.hasOwnProperty.call(file, 'require_feishu_login')) body.require_feishu_login = parseBoolean(file.require_feishu_login, 'require_feishu_login');
+    if (Object.prototype.hasOwnProperty.call(file, 'user_open_ids')) body.access_users = parseIds(file.user_open_ids, /^ou_[A-Za-z0-9_-]+$/, 'open_id', true).map((value) => ({ id: value }));
+    if (Object.prototype.hasOwnProperty.call(file, 'group_chat_ids')) body.access_groups = parseIds(file.group_chat_ids, /^oc_[A-Za-z0-9_-]+$/, 'chat_id', true).map((value) => ({ id: value }));
+    if (!Object.keys(body).length) fail('Access JSON contains no supported settings', 'E_INVALID_ARGS');
+  } else {
+    fail('Usage: magic-builder page access <get|enable|disable|require-login|users|groups|set> --id <id>', 'E_INVALID_ARGS');
+  }
+  const res = await authenticatedRequest(opts, endpoint, { method: 'PATCH', body });
+  if (res.code !== 0) fail(res.msg || 'Access update failed', 'E_ACCESS_FAILED');
+  success(res.data || res, opts);
 }
 
 async function publish(args, opts) {
@@ -39,7 +135,9 @@ async function publish(args, opts) {
   const existingId = opts.id || config[relPath]?.id || config[relPath]?.remoteId;
 
   const body = { html, title };
+  if (opts.customId !== undefined) body.custom_id = String(opts.customId).trim();
   if (opts.openSource) body.is_open_source = true;
+  if (opts.comments !== undefined) body.comments_enabled = opts.comments === true || String(opts.comments).toLowerCase() !== 'false';
 
   if (!opts.quiet) process.stderr.write(`${existingId ? 'Updating' : 'Publishing'} ${relPath}... `);
 
@@ -56,13 +154,17 @@ async function publish(args, opts) {
   const data = res.data || res;
   const id = normalizeId(data.id || data.record_id || existingId);
   const htmlBoxUrl = data.html_box_url || `${baseUrl}/html-box/${id}`;
+  const appUrl = data.app_url || `${baseUrl}/app/${id}`;
+  const url = data.url || (data.runtime === 'html-box' ? htmlBoxUrl : appUrl);
   const dashboardUrl = data.dashboard_url || `${baseUrl}/dashboard/${id}`;
 
   config[relPath] = {
     id,
     remoteId: id,
     title,
+    customId: opts.customId !== undefined ? String(opts.customId).trim() : (config[relPath]?.customId || ''),
     urls: {
+      app: appUrl,
       html_box: htmlBoxUrl,
       dashboard: dashboardUrl,
       panel: data.panel_url || '',
@@ -76,6 +178,10 @@ async function publish(args, opts) {
   success({
     id,
     title,
+    custom_id: data.custom_id || body.custom_id || '',
+    url,
+    runtime: data.runtime || (url === htmlBoxUrl ? 'html-box' : 'app'),
+    app_url: appUrl,
     html_box_url: htmlBoxUrl,
     dashboard_url: dashboardUrl,
     panel_url: data.panel_url || '',
@@ -273,4 +379,4 @@ function formatHtmlLimitMessage(html) {
   return `HTML exceeds publish limit (${HTML_LIMIT} characters; ${HTML_CODE_FIELD_COUNT} HTML code fields x ${HTML_CODE_FIELD_LIMIT} characters). Current: ${html.length}; over by: ${overflow}. ${hint}`;
 }
 
-module.exports = { run };
+module.exports = { run, parseIds, parseBoolean };

package/src/commands/performance.js

@@ -3,6 +3,7 @@
 const { existsSync, readFileSync } = require('fs');
 const { resolve } = require('path');
 const { success, fail } = require('../lib/output');
+const { getPerformanceConfigPath, loadPerformanceConfig } = require('../lib/config');
 
 const DEFAULTS = {
   endpoint: 'https://people.bytedance.net/perf/api/foundation/v2/draft',
@@ -13,8 +14,8 @@ const DEFAULTS = {
 
 async function run(args, opts) {
   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');
+  if (args.length > 1 || !['draft', 'submit', 'self-review', 'key-works', 'review-users', 'invite-review'].includes(action)) {
+    fail('Usage: magic-builder performance [submit|self-review|key-works|review-users|invite-review] --review-url <url> --cookie <content|file>', 'E_INVALID_ARGS');
   }
 
   const cookie = readCookie(opts.cookie, opts.cookieFile);
@@ -23,7 +24,44 @@ async function run(args, opts) {
   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 === 'key-works') {
+    const data = await getKeyWorks(opts, cookie, csrf);
+    success(data, opts);
+    return;
+  }
+  if (action === 'review-users') {
+    const data = await getReviewUsers(opts, cookie, csrf);
+    success(data, opts);
+    return;
+  }
+  if (action === 'invite-review') {
+    const payload = readInviteReviewPayload(opts);
+    const endpoint = String(opts.endpoint || DEFAULTS.endpoint);
+    if (opts.dryRun) {
+      success({ dryRun: true, action: 'invite-review', endpoint, payload }, opts);
+      return;
+    }
+    const review = parseReviewLocation(opts.reviewUrl || opts.referer);
+    const data = await postPerformance(endpoint, payload, cookie, csrf, {
+      referer: String(opts.referer || review.referer || 'https://people.bytedance.net/performance/perf/review'),
+      tenantId: String(opts.tenantId || ''),
+    });
+    success(data, opts);
+    return;
+  }
+
+  const config = await resolveConfig(opts, cookie, action === 'self-review' ? 'self_review' : 'confirm_invitation');
+  if (action === 'self-review') {
+    const updates = readSelfReviewInputs(opts);
+    const payload = buildSelfReviewPayloadFromDraft(config.draft, updates);
+    if (opts.dryRun) {
+      success({ dryRun: true, action: 'self-review', endpoint: config.endpoint, payload }, opts);
+      return;
+    }
+    const data = await postPerformance(config.endpoint, payload, cookie, csrf, config);
+    success(data, opts);
+    return;
+  }
   if (action === 'submit') {
     const payload = buildStagePayloadFromDraft(config.draft, config);
     if (opts.dryRun) {
@@ -53,6 +91,136 @@ async function run(args, opts) {
   success(data, opts);
 }
 
+function readInviteReviewPayload(opts) {
+  if (opts.payload && opts.payloadFile) {
+    fail('Pass either --payload or --payload-file, not both.', 'E_INVALID_ARGS');
+  }
+  const input = opts.payloadFile
+    ? readFileSync(resolve(String(opts.payloadFile)), 'utf8')
+    : String(opts.payload || '');
+  if (!input.trim()) fail('invite-review requires --payload <json> or --payload-file <file>.', 'E_INVALID_ARGS');
+  const payload = parseJson(input);
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    fail('Invite-review payload must be a valid JSON object.', 'E_INVALID_ARGS');
+  }
+  const missing = ['key', 'data', 'version'].filter(key => payload[key] === undefined || payload[key] === null);
+  if (missing.length) fail(`Invite-review payload is missing ${missing.join(', ')}.`, 'E_INVALID_ARGS');
+  if (!String(payload.key).includes('__invite_review__')) {
+    fail('Invite-review payload key must contain __invite_review__.', 'E_INVALID_ARGS');
+  }
+  return normalizePerformancePayload(payload);
+}
+
+function normalizePerformancePayload(payload) {
+  const normalized = structuredClone(payload);
+  normalizePerformanceNode(normalized);
+  return normalized;
+}
+
+function normalizePerformanceNode(node) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    node.forEach(normalizePerformanceNode);
+    return;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'insert' && typeof value === 'string') {
+      node[key] = value.replace(/\\n(?=\r?\n|$)/g, '\n');
+      continue;
+    }
+    if (typeof value === 'string' && ['text', 'value', 'rich_text'].includes(key)) {
+      const embedded = parseJson(value);
+      if (embedded && typeof embedded === 'object') {
+        normalizePerformanceNode(embedded);
+        node[key] = JSON.stringify(embedded);
+      }
+      continue;
+    }
+    normalizePerformanceNode(value);
+  }
+}
+
+async function getKeyWorks(opts, cookie, csrf) {
+  if (!opts.rootReviewId) {
+    fail('key-works requires --root-review-id <id>.', 'E_INVALID_ARGS');
+  }
+  const personalConfig = opts.performanceConfig || loadPerformanceConfig();
+  const templateId = String(opts.templateId || personalConfig.invite_review_template_id || personalConfig.inviteReviewTemplateId || '');
+  if (!templateId) {
+    fail(`Missing template id. Use --template-id <id> or set invite_review_template_id in ${getPerformanceConfigPath()}.`, 'E_INVALID_ARGS');
+  }
+  const endpoint = assertPeoplePerfEndpoint(opts.stageEndpoint || DEFAULTS.submitEndpoint);
+  endpoint.searchParams.set('template_id', templateId);
+  endpoint.searchParams.set('root_review_id', String(opts.rootReviewId));
+  const referer = String(opts.referer || opts.reviewUrl || 'https://people.bytedance.net/performance/perf/review');
+  const headers = {
+    accept: 'application/json, text/plain, */*',
+    'accept-language': 'zh-CN,zh;q=0.9',
+    cookie,
+    referer,
+    'x-f-csrf': csrf,
+    'x-f-lang': 'zh-CN',
+    'x-f-timezone': 'Asia/Shanghai',
+  };
+  if (opts.tenantId) headers['rpc-persist-lane-c-perfx-tenant-id'] = String(opts.tenantId);
+  const response = await fetch(endpoint, { method: 'GET', headers });
+  const text = await response.text();
+  const data = parseJson(text);
+  if (!response.ok) {
+    const error = new Error(data?.message || data?.msg || `Performance request failed: HTTP ${response.status}`);
+    error.code = response.status === 401 || response.status === 403 ? 'E_AUTH_FAILED' : 'E_REQUEST_FAILED';
+    throw error;
+  }
+  if (data === null) {
+    const error = new Error('Performance response is not valid JSON.');
+    error.code = 'E_REQUEST_FAILED';
+    throw error;
+  }
+  return data;
+}
+
+async function getReviewUsers(opts, cookie, csrf) {
+  const location = opts.reviewUrl ? parseReviewLocation(opts.reviewUrl) : {};
+  const reviewId = String(opts.reviewId || location.reviewId || '');
+  const stageId = String(opts.stageId || location.formId || '');
+  if (!reviewId || !stageId) {
+    fail('review-users requires --review-url <url> or both --review-id <id> and --stage-id <id>.', 'E_INVALID_ARGS');
+  }
+  const base = assertPeoplePerfEndpoint(opts.reviewUsersEndpoint || DEFAULTS.submitEndpoint);
+  const endpoint = new URL(`${base.origin}/perf/api/review/v2/stage/${encodeURIComponent(reviewId)}/list_invite_review`);
+  const referer = String(opts.referer || location.referer || `https://people.bytedance.net/performance/perf/review/${reviewId}/${stageId}/members`);
+  const headers = {
+    accept: 'application/json, text/plain, */*',
+    'accept-language': 'zh-CN,zh;q=0.9',
+    'content-type': 'application/json;charset=UTF-8',
+    cookie,
+    origin: 'https://people.bytedance.net',
+    referer,
+    'x-f-csrf': csrf,
+    'x-f-lang': 'zh-CN',
+    'x-f-timezone': 'Asia/Shanghai',
+  };
+  if (opts.tenantId) headers['rpc-persist-lane-c-perfx-tenant-id'] = String(opts.tenantId);
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ stage_id: stageId }),
+  });
+  const text = await response.text();
+  const data = parseJson(text);
+  if (!response.ok) {
+    const error = new Error(data?.message || data?.msg || `Performance request failed: HTTP ${response.status}`);
+    error.code = response.status === 401 || response.status === 403 ? 'E_AUTH_FAILED' : 'E_REQUEST_FAILED';
+    throw error;
+  }
+  if (data === null) {
+    const error = new Error('Performance response is not valid JSON.');
+    error.code = 'E_REQUEST_FAILED';
+    throw error;
+  }
+  return data;
+}
+
 async function postPerformance(endpoint, payload, cookie, csrf, config) {
   assertPeoplePerfEndpoint(endpoint);
   const response = await fetch(endpoint, {
@@ -129,14 +297,14 @@ function getCookie(cookie, name) {
   return '';
 }
 
-async function resolveConfig(opts, cookie) {
+async function resolveConfig(opts, cookie, draftKind = 'confirm_invitation') {
   const review = parseReviewLocation(opts.reviewUrl || opts.referer, opts.reviewId, opts.formId);
   if (review.reviewId && review.formId) {
     const settings = await requestJson(opts.settingsEndpoint || DEFAULTS.settingsEndpoint, cookie, review.referer);
     const operatorId = String(opts.operatorId || settings?.data?.user?.id || '');
     const tenantId = String(opts.tenantId || settings?.data?.tenant?.id || '');
     if (!operatorId) fail('Unable to resolve operator id from /perf/api/user/settings.', 'E_REQUEST_FAILED');
-    const key = `${review.reviewId}__confirm_invitation__${operatorId}__${review.formId}`;
+    const key = buildDraftKey(review.reviewId, draftKind, operatorId, review.formId);
     const draftUrl = new URL(opts.draftEndpoint || DEFAULTS.draftEndpoint);
     draftUrl.searchParams.set('key', key);
     const draftResponse = await requestJson(draftUrl.toString(), cookie, review.referer);
@@ -182,6 +350,36 @@ async function resolveConfig(opts, cookie) {
   };
 }
 
+function buildDraftKey(reviewId, draftKind, operatorId, formId) {
+  return `${reviewId}__${draftKind}__${operatorId}__${formId}`;
+}
+
+function readSelfReviewInputs(opts) {
+  const inputs = [
+    ['good', 'goodFile'],
+    ['improve', 'improveFile'],
+    ['valuesComment', 'valuesCommentFile'],
+  ];
+  const updates = {};
+  for (const [valueKey, fileKey] of inputs) {
+    const hasValue = Object.prototype.hasOwnProperty.call(opts, valueKey);
+    const hasFile = Object.prototype.hasOwnProperty.call(opts, fileKey);
+    if (hasValue && hasFile) {
+      fail(`Pass either --${toKebab(valueKey)} or --${toKebab(fileKey)}, not both.`, 'E_INVALID_ARGS');
+    }
+    if (hasFile) updates[valueKey] = readFileSync(resolve(String(opts[fileKey])), 'utf8');
+    else if (hasValue) updates[valueKey] = String(opts[valueKey]);
+  }
+  if (!Object.keys(updates).length) {
+    fail('Pass at least one of --good, --improve, or --values-comment (or the matching --*-file option).', 'E_INVALID_ARGS');
+  }
+  return updates;
+}
+
+function toKebab(value) {
+  return String(value).replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+}
+
 function parseReviewLocation(value, reviewId, formId) {
   if (reviewId && formId) {
     return {
@@ -295,6 +493,42 @@ function buildPayloadFromDraft(markdown, draft, config) {
   };
 }
 
+function buildSelfReviewPayloadFromDraft(draft, updates) {
+  const snapshot = structuredClone(draft);
+  const units = snapshot?.data?.units;
+  if (!Array.isArray(units)) throw selfReviewSchemaError('Current self-review draft does not contain data.units.');
+  const fields = units.flatMap(unit => Array.isArray(unit?.fields) ? unit.fields : []);
+  const textFields = fields.filter(field => field?.entityType === 'text');
+  const tagTextFields = fields.filter(field => field?.entityType === 'tag_text');
+  if (textFields.length !== 2 || tagTextFields.length !== 1) {
+    throw selfReviewSchemaError('Unable to identify the self-review text fields from the current template.');
+  }
+  if (Object.prototype.hasOwnProperty.call(updates, 'good')) {
+    textFields[0].value = selfReviewTextValue(updates.good);
+  }
+  if (Object.prototype.hasOwnProperty.call(updates, 'improve')) {
+    textFields[1].value = selfReviewTextValue(updates.improve);
+  }
+  if (Object.prototype.hasOwnProperty.call(updates, 'valuesComment')) {
+    tagTextFields[0].json_value = selfReviewTextValue(updates.valuesComment);
+  }
+  return {
+    key: snapshot.key,
+    data: snapshot.data,
+    version: Number(snapshot.version),
+  };
+}
+
+function selfReviewSchemaError(message) {
+  const error = new Error(message);
+  error.code = 'E_REQUEST_FAILED';
+  return error;
+}
+
+function selfReviewTextValue(text) {
+  return { '0': { ops: markdownToDelta(String(text)), zoneId: '0', zoneType: 'Z' } };
+}
+
 function buildStagePayloadFromDraft(draft, config = {}) {
   if (!draft?.data?.keyWorks) fail('Current draft does not contain keyWorks.', 'E_REQUEST_FAILED');
   const keyWorks = structuredClone(draft.data.keyWorks);
@@ -445,4 +679,4 @@ function parseJson(text) {
   try { return text ? JSON.parse(text) : {}; } catch (_) { return null; }
 }
 
-module.exports = { run, readCookie, normalizeCookie, getCookie, parseReviewLocation, splitMarkdownSections, markdownToDelta, buildPayload, buildPayloadFromDraft, buildStagePayloadFromDraft, assertPeoplePerfEndpoint };
+module.exports = { run, getKeyWorks, getReviewUsers, readInviteReviewPayload, normalizePerformancePayload, readCookie, normalizeCookie, getCookie, readSelfReviewInputs, buildDraftKey, parseReviewLocation, splitMarkdownSections, markdownToDelta, buildPayload, buildPayloadFromDraft, buildSelfReviewPayloadFromDraft, buildStagePayloadFromDraft, assertPeoplePerfEndpoint };

package/src/commands/skill.js

@@ -24,7 +24,7 @@ async function run(args, opts) {
   if (sub !== 'check-update' && sub !== 'update' && sub !== 'install') {
     fail('Usage: magic-builder skill <check-update|update|install>', 'E_INVALID_ARGS');
   }
-  const skillsRoot = path.resolve(opts.skillsRoot || path.join(os.homedir(), '.codex', 'skills'));
+  const skillsRoot = path.resolve(opts.skillsRoot || defaultSkillsRoot());
   const environment = resolveEnvironment(String(opts.environment || 'auto'), skillsRoot);
   const remote = await prepareRemotePackage();
   const report = buildReport(remote, skillsRoot, environment);
@@ -106,7 +106,7 @@ function buildCloudUpdateDescriptor(report, options = {}) {
     }] : [],
     instructions: [
       'Use the cloud runtime managed skill update/install mechanism.',
-      'Do not copy files into ~/.codex/skills or overwrite local filesystem paths in cloud mode.',
+      'Do not copy files into ~/.agents/skills or overwrite local filesystem paths in cloud mode.',
       'If no managed cloud updater is exposed, report this descriptor and do not claim the update was applied.',
     ],
   };
@@ -189,4 +189,8 @@ function ensureSafeSkillId(id) {
   if (!/^[a-z0-9][a-z0-9-]*$/i.test(id)) throw new Error(`Unsafe skill id in update package: ${id}`);
 }
 
-module.exports = { run };
+function defaultSkillsRoot(homeDir = os.homedir()) {
+  return path.join(homeDir, '.agents', 'skills');
+}
+
+module.exports = { run, defaultSkillsRoot };

package/src/lib/config.js

@@ -9,6 +9,7 @@ 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';
+const PERFORMANCE_CONFIG_FILE = 'performance.json';
 
 function normalizeMagicBaseUrl(value) {
   const raw = String(value || DEFAULT_BASE_URL).trim().replace(/\/+$/, '');
@@ -28,6 +29,16 @@ function getWidgetPublishConfigPath() {
   return path.join(CONFIG_DIR, WIDGET_PUBLISH_CONFIG_FILE);
 }
 
+function getPerformanceConfigPath() {
+  return path.join(CONFIG_DIR, PERFORMANCE_CONFIG_FILE);
+}
+
+function loadPerformanceConfig() {
+  const p = getPerformanceConfigPath();
+  if (!fs.existsSync(p)) return {};
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return {}; }
+}
+
 function loadAppsConfig() {
   const p = fs.existsSync(getAppsConfigPath())
     ? getAppsConfigPath()
@@ -50,6 +61,8 @@ module.exports = {
   getBaseUrl,
   getAppsConfigPath,
   getWidgetPublishConfigPath,
+  getPerformanceConfigPath,
+  loadPerformanceConfig,
   loadAppsConfig,
   saveAppsConfig,
 };

package/src/lib/help.js

@@ -15,7 +15,7 @@ SYNTAX:
 
 COMMANDS:
   auth       Login and manage Magic developer tokens
-  page       Publish, list, export, and delete Magic pages
+  page       Publish and manage Magic pages, collaborators, and access
   faas       Publish, list, and delete Magic FaaS functions
   file       Upload, list, and delete TOS files
   link       Generate Magic share links
@@ -39,6 +39,8 @@ EXAMPLES:
   magic-builder page list --scope mine
   magic-builder page export --id recxxx --out app.html
   magic-builder page delete --id recxxx
+  magic-builder page collaborators add --id recxxx --open-ids ou_xxx,ou_yyy
+  magic-builder page access groups add --id recxxx --chat-ids oc_xxx
   magic-builder faas publish handler.js --name report-api
   magic-builder faas list
   magic-builder faas delete --id recxxx
@@ -85,11 +87,19 @@ COMMANDS:
   auth set <token>
   auth show
 
-  page publish <html> --title <title> [--id <id>] [--open-source]
+  page publish <html> --title <title> [--id <id>] [--custom-id <id>] [--open-source] [--comments]
   page list [--title <keyword>] [--scope mine|public]
   page export --id <id> --out <file|dir> [--scope mine|public]
   page export --title <keyword> --out <dir> [--all] [--scope mine|public]
   page delete --id <id>
+  page collaborators list --id <id>
+  page collaborators add|remove|set --id <id> --open-ids <ou_a,ou_b>
+  page collaborators set --id <id> --file <collaborators.json>
+  page access get|enable|disable --id <id>
+  page access require-login --id <id> --enabled true|false
+  page access users add|remove|set --id <id> --open-ids <ou_a,ou_b>
+  page access groups add|remove|set --id <id> --chat-ids <oc_a,oc_b>
+  page access set --id <id> --file <access.json>
 
   faas publish <file.js> --name <name> [--id <id>]
   faas publish --code <code> --name <name> [--id <id>]
@@ -103,14 +113,20 @@ COMMANDS:
   link create --title <text>
   link create --fid <id>
 
-  doc create --html <file> --title <title> [--summary <text>] [--as bot|user]
-  doc append --html <file> --doc-token <token> [--as bot|user]
+  doc create --html <file> --title <title> [--summary <text>] [--as bot|user] [--edition external|bytedance]
+  doc append --html <file> --doc-token <token> [--as bot|user] [--edition external|bytedance]
 
   feedback create --feedback <text> [--title <title>] [--summary <text>]
   feedback create --feedback-file <file> [--dry-run]
 
   performance --review-url <url> --cookie <content|file> --markdown <content|file|url> [--dry-run]
+  perf self-review --review-url <url> [--good <text>|--good-file <file>]
+    [--improve <text>|--improve-file <file>] [--values-comment <text>|--values-comment-file <file>] [--dry-run]
   perf submit --review-url <url> --cookie-file <file> --template-group-id <id> [--dry-run|--yes]
+  perf key-works --root-review-id <id> [--template-id <id>] --cookie-file <file>
+  perf review-users --review-id <id> --stage-id <id> --cookie-file <file>
+  perf review-users --review-url <url> --cookie-file <file>
+  perf invite-review --payload-file <file> --review-url <url> --cookie-file <file> [--dry-run]
   perf --review-url <url> --cookie-file <file> --markdown-file <file> [--dry-run]
 
   widget-publish --app-id <id> --block-type-id <id> [--version <x.y.z>] [--change-log <text>]
@@ -161,11 +177,19 @@ SYNTAX:
   page: `@HELP magic-builder/page
 
 SYNTAX:
-  magic-builder page publish <html> --title <title> [--id <id>] [--open-source]
+  magic-builder page publish <html> --title <title> [--id <id>] [--custom-id <id>] [--open-source] [--comments]
   magic-builder page list [--title <keyword>] [--scope mine|public]
   magic-builder page export --id <id> --out <file|dir> [--scope mine|public]
   magic-builder page export --title <keyword> --out <dir> [--all] [--scope mine|public]
   magic-builder page delete --id <id>
+  magic-builder page collaborators list --id <id>
+  magic-builder page collaborators add|remove|set --id <id> --open-ids <ou_a,ou_b>
+  magic-builder page collaborators set --id <id> --file <collaborators.json>
+  magic-builder page access get|enable|disable --id <id>
+  magic-builder page access require-login --id <id> --enabled true|false
+  magic-builder page access users add|remove|set --id <id> --open-ids <ou_a,ou_b>
+  magic-builder page access groups add|remove|set --id <id> --chat-ids <oc_a,oc_b>
+  magic-builder page access set --id <id> --file <access.json>
 `,
   faas: `@HELP magic-builder/faas
 
@@ -191,8 +215,8 @@ SYNTAX:
   doc: `@HELP magic-builder/doc
 
 SYNTAX:
-  magic-builder doc create --html <file> --title <title> [--summary <text>] [--as bot|user]
-  magic-builder doc append --html <file> --doc-token <token> [--as bot|user]
+  magic-builder doc create --html <file> --title <title> [--summary <text>] [--as bot|user] [--edition external|bytedance]
+  magic-builder doc append --html <file> --doc-token <token> [--as bot|user] [--edition external|bytedance]
 `,
   feedback: `@HELP magic-builder/feedback
 
@@ -204,8 +228,14 @@ SYNTAX:
 
 SYNTAX:
   magic-builder performance --review-url <url> --cookie <content|file> --markdown <content|file|url>
+  magic-builder perf self-review --review-url <url> --good <text> --improve <text> --values-comment <text>
+  magic-builder perf self-review --review-url <url> --good-file <file> --improve-file <file> --values-comment-file <file>
   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 key-works --root-review-id <id> [--template-id <id>] --cookie-file <file>
+  magic-builder perf review-users --review-id <id> --stage-id <id> --cookie-file <file>
+  magic-builder perf review-users --review-url <url> --cookie-file <file>
+  magic-builder perf invite-review --payload-file <file> --review-url <url> --cookie-file <file> [--dry-run]
   magic-builder perf --review-url <url> --cookie-file <file> --markdown-file <file>
 
 COOKIE:
@@ -215,9 +245,38 @@ DRAFT:
   --review-url resolves operator, tenant, form ids, and the current version
   from /perf/api/user/settings and /perf/api/foundation/draft.
 
+SELF REVIEW:
+  self-review updates only the explicitly passed text fields and preserves
+  the current performance and values ratings. It writes by default; use
+  --dry-run to inspect the generated payload without saving it.
+
+KEY WORKS:
+  key-works reads the review-stage data for the specified template and root
+  review. The template id defaults to invite_review_template_id in
+  ~/.magic-builder/performance.json and can be overridden with --template-id.
+  It is read-only and prints the complete API response as JSON.
+
+REVIEW USERS:
+  review-users reads the invited review-user list for a review and stage. It
+  accepts either --review-url or explicit --review-id and --stage-id. Explicit
+  ids override values parsed from the URL. It does not modify review data and
+  prints the complete API response as JSON.
+
+INVITE REVIEW:
+  invite-review writes a complete invite-review draft payload to People. Pass
+  the current payload as JSON or a JSON file. Use --dry-run to inspect it
+  without writing. The payload must contain key, data, and version, and its key
+  must identify an invite_review draft.
+
 OPTIONS:
   --dry-run                    Print the generated payload without sending it
   --review-url <url>           People performance review URL (recommended)
+  --good <text>                Update the "did well" self-review text
+  --good-file <file>           Read the "did well" text from a file
+  --improve <text>             Update the "to improve" self-review text
+  --improve-file <file>        Read the "to improve" text from a file
+  --values-comment <text>      Update the values self-review comment
+  --values-comment-file <file> Read the values comment from a file
   --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
@@ -230,6 +289,12 @@ OPTIONS:
   --source-id <id>             Override the form source id
   --field-source-id <id>       Override the writable field source id
   --tenant-id <id>             Override the People tenant id
+  --referer <url>              Override the People request Referer
+  --stage-endpoint <url>       Override the key-works query endpoint
+  --stage-id <id>              Review stage id used by review-users
+  --review-users-endpoint <url> Override the review-users API origin
+  --payload <json>              Complete invite-review draft payload
+  --payload-file <file>         Read invite-review draft payload from a file
   --endpoint <url>             Override the draft API endpoint
 `,
   perf: `@HELP magic-builder/performance

package/src/lib/multipart.js

@@ -21,6 +21,7 @@ async function uploadSingle(filePath, opts = {}) {
 
   const signRes = await request(`${baseUrl}/api/tos/sign`, {
     method: 'POST',
+    token,
     body: signBody,
   });
 
@@ -48,6 +49,8 @@ async function uploadSingle(filePath, opts = {}) {
     token,
     body: {
       action: 'record',
+      audit_id: signRes.data.audit_id,
+      audit_table_id: signRes.data.audit_table_id,
       url,
       key: signRes.data.key,
       filename,