openyida 2026.9.21 → 2026.9.22

package/README.md

@@ -393,6 +393,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
+| `openyida app-entry get <appType> [--json]` | Read frontend and management runtime entries |
+| `openyida app-entry set <appType> [--frontend <url>] [--management <url>] [--clear-frontend] [--clear-management] [--json]` | Register application entries with partial update and readback |
 | `openyida app-list [--type managed\|created] [--page N] [--size N]` | Page through apps I manage or created |
 | `openyida corp-efficiency [overview\|details\|detail\|groups\|notify] [options] [--open\|--no-open]` | Query enterprise efficiency overview and detail reports |
 | `openyida create-app "<name>"\|--name <name> [options] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a Yida app |

package/bin/yida.js

@@ -733,6 +733,12 @@ async function main() {
       break;
     }
 
+    case 'app-entry': {
+      const { run } = require('../lib/app/app-entry');
+      await run(args);
+      break;
+    }
+
     case 'app-list': {
       const { run } = require('../lib/app/app-list');
       await run(args);

package/lib/app/app-entry.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const { createAuthRef, createYidaClient, unwrapYidaResponse } = require('../core/yida-client');
+const { t } = require('../core/i18n');
+const { throwUsage } = require('../core/command-errors');
+
+/** Keep complete runtime URLs; the server verifies tenant and resource ownership. */
+function normalizeUrl(value, appType) {
+  const input = String(value || '').trim();
+  if (!input) { throw new Error(t('app_entry.invalid_url')); }
+  // eslint-disable-next-line no-control-regex -- reject control characters in persisted URLs
+  if (input.length > 2048 || /[\\\s\x00-\x1f\x7f]/.test(input)) {
+    throw new Error(t('app_entry.invalid_url'));
+  }
+  const match = /^https?:\/\/[^/?#]+(\/[^?#]*)(?:\?([^#]*))?(?:#(.*))?$/i.exec(input);
+  if (!match) { throw new Error(t('app_entry.invalid_url')); }
+  const url = new URL(input);
+  const route = match[1];
+  const prefix = `/${appType}/`;
+  const parts = route.startsWith(prefix) ? route.slice(prefix.length).split('/') : [];
+  const short = /^\/(?:s\/[A-Za-z0-9_-]+|o\/[A-Za-z0-9_-]+(?:\/FORM-[A-Za-z0-9_-]+)?)$/.test(route);
+  const runtime = ['custom', 'workbench', 'submission', 'manage'].includes(parts[0]) &&
+    ((parts.length === 1 && parts[0] === 'workbench') ||
+      (parts.length === 2 && /^[A-Za-z0-9_-]+$/.test(parts[1])));
+  if (url.username || url.password || url.pathname !== route || (!short && !runtime)) {
+    throw new Error(t('app_entry.invalid_url'));
+  }
+  if (match[2] !== undefined) {
+    const seen = new Set();
+    for (const parameter of match[2].split('&')) {
+      const pair = /^(corpid|locale|viewUuid|processCode|hideLeftNav|noShowTopBottom)=([A-Za-z0-9_-]+)$/.exec(parameter);
+      if (!pair || seen.has(pair[1]) ||
+        (['hideLeftNav', 'noShowTopBottom'].includes(pair[1]) && !/^(true|false|y|n|0|1)$/.test(pair[2]))) {
+        throw new Error(t('app_entry.invalid_url'));
+      }
+      seen.add(pair[1]);
+    }
+  }
+  if (match[3] !== undefined && !/^[A-Za-z0-9_/-]+$/.test(match[3])) {
+    throw new Error(t('app_entry.invalid_url'));
+  }
+  return input;
+}
+
+/** Reject duplicate or ambiguous flags; omissions never clear stored entries. */
+function parseArgs(args) {
+  const [action, appType, ...flags] = args;
+  if (!['get', 'set'].includes(action) || !/^[A-Za-z0-9_-]+$/.test(appType || '')) {
+    throwUsage(t('app_entry.usage'));
+  }
+  const values = {};
+  for (let index = 0; index < flags.length; index++) {
+    const flag = flags[index];
+    if (flag === '--json') {
+      continue;
+    }
+    const match = /^--(clear-)?(frontend|management)$/.exec(flag);
+    if (action !== 'set' || !match || Object.prototype.hasOwnProperty.call(values, match[2])) {
+      throwUsage(t('app_entry.usage'));
+    }
+    const value = match[1] ? null : flags[++index];
+    if (value !== null && (!value || value.startsWith('--'))) {
+      throwUsage(t('app_entry.usage'));
+    }
+    values[match[2]] = value;
+  }
+  if (action === 'set' && !Object.keys(values).length) {
+    throwUsage(t('app_entry.usage'));
+  }
+  return { action, appType, values };
+}
+
+/** Read the revision used for a conditional partial write. */
+async function readEntries(client, appType) {
+  const result = unwrapYidaResponse(await client.get(`/${appType}/query/app/getAccessEntries.json`));
+  if (!result || typeof result.revision !== 'string' || !result.revision ||
+      !result.accessEntries || typeof result.accessEntries !== 'object' || Array.isArray(result.accessEntries)) {
+    throw new Error(t('app_entry.invalid_response'));
+  }
+  return result;
+}
+
+/** Persist only supplied entries and verify them through a separate read. */
+async function run(args = []) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(t('app_entry.usage'));
+    return;
+  }
+  const { action, appType, values } = parseArgs(args);
+  const authRef = createAuthRef();
+  const client = createYidaClient({ authRef });
+  const patch = {};
+  for (const [key, value] of Object.entries(values)) {
+    patch[key] = value === null ? null : { url: normalizeUrl(value, appType) };
+  }
+  let result = await readEntries(client, appType);
+  if (action === 'set') {
+    unwrapYidaResponse(await client.postForm(`/${appType}/query/app/saveAccessEntries.json`, {
+      accessEntries: JSON.stringify(patch), revision: result.revision,
+    }));
+    result = await readEntries(client, appType);
+    for (const [key, entry] of Object.entries(patch)) {
+      if ((result.accessEntries[key]?.url || '') !== (entry?.url || '')) {
+        throw new Error(t('app_entry.readback_failed'));
+      }
+    }
+  }
+  const urls = {};
+  for (const key of ['frontend', 'management']) {
+    if (result.accessEntries[key]?.url) {
+      urls[key] = normalizeUrl(result.accessEntries[key].url, appType);
+    }
+  }
+  console.log(JSON.stringify({ appType, ...result, urls }, null, 2));
+  return result;
+}
+
+module.exports = { run, parseArgs, normalizeUrl };

package/lib/app/app-list.js

@@ -84,6 +84,7 @@ function formatApp(app, baseUrl) {
     appName: (app.appName && app.appName.zh_CN) || '',
     appType: app.appType || '',
     systemLink: app.systemLink || '',
+    ...(app.accessEntries ? { accessEntries: app.accessEntries } : {}),
     ...buildApplicationEntryUrls({ appType: app.appType, systemLink: app.systemLink, baseUrl }),
   };
 }

package/lib/app/canvas-theme-guard.js

@@ -2,8 +2,33 @@
 
 const Babel = require('@babel/standalone');
 const { CliError } = require('../core/cli-error');
+const { warn } = require('../core/chalk');
 const { t } = require('../core/i18n');
 
+// Whether provably fixed brand overrides should be downgraded from a hard
+// failure to a warning. Mirrors OPENYIDA_CANVAS_ALLOW_UNSUPPORTED_IMPORTS so
+// legacy pages can ship first and migrate to canvas-theme later.
+function isTruthy(value) {
+  return ['1', 'true', 'yes', 'on'].includes(String(value || '').trim().toLowerCase());
+}
+
+function allowFixedBrand(options = {}, env = process.env) {
+  return options.allowFixedBrand === true || isTruthy(env.OPENYIDA_CANVAS_ALLOW_FIXED_BRAND);
+}
+
+// Whether fixed brand overrides should hard-block publishing. Off by default so
+// users are never stuck: the guard warns and lets the app theme apply. Teams
+// that want CI enforcement opt in via --strict-theme / OPENYIDA_CANVAS_STRICT_THEME.
+function strictFixedBrand(options = {}, env = process.env) {
+  return options.strictBrand === true || isTruthy(env.OPENYIDA_CANVAS_STRICT_THEME);
+}
+
+function emitThemeWarning(options, message) {
+  if (typeof options.onThemeWarning === 'function') { options.onThemeWarning(message); return; }
+  warn(message);
+}
+
+
 // Check the maintained theme contract without executing business code.
 // Dynamic component factories and runtime branches still need browser verification.
 function assertCanvasThemeStructure(source, options = {}) {
@@ -123,9 +148,12 @@ function assertCanvasThemeStructure(source, options = {}) {
   }
 }
 
-// Only reject provably fixed brand colors passed to antd's ConfigProvider.
-// Semantic colors, layout tokens and dynamic theme resolvers remain supported.
-function assertBrandOverrides(ast, traverse, options) {
+// Collect every provably fixed brand color passed to antd's ConfigProvider.
+// Semantic colors, layout tokens and dynamic theme resolvers are ignored.
+// Each entry keeps the offending property's char offsets so the theme codemod
+// can surgically remove it while the guard reuses the same detection to fail.
+function collectBrandOverrides(ast, traverse) {
+  const violations = [];
   const resolve = (p, seen = new Set()) => {
     if (!p?.node || seen.has(p.node)) { return null; }
     seen.add(p.node);
@@ -147,10 +175,12 @@ function assertBrandOverrides(ast, traverse, options) {
     const color = val.isStringLiteral() ? val.node.value : val.node.quasis[0].value.cooked;
     if (!color) { return; }
     const line = val.node.loc?.start.line || 1;
-    throw new CliError(t('publish.canvas_theme_fixed_brand', line), {
-      code: 'OPENYIDA_CANVAS_THEME_FIXED_BRAND',
-      details: { stage: 'canvas_compile', sourcePath: options.sourcePath || '', line, field, value: color,
-        sample: 'openyida sample openyida-page-template canvas-theme' },
+    // Remove the override at its ConfigProvider usage site, not the resolved literal.
+    const property = p?.parentPath?.isObjectProperty() ? p.parentPath.node : null;
+    violations.push({
+      field, color, line,
+      start: property ? property.start : val.node.start,
+      end: property ? property.end : val.node.end,
     });
   };
   const tokens = p => properties(p).forEach(item => {
@@ -179,6 +209,46 @@ function assertBrandOverrides(ast, traverse, options) {
       }
     },
   });
+  return violations;
+}
+
+// Fixed brand colors passed to antd's ConfigProvider are relaxed by default:
+// warn and continue so users are never blocked (the app theme still applies at
+// runtime). --strict-theme / OPENYIDA_CANVAS_STRICT_THEME restores the hard fail
+// for CI enforcement; --allow-fixed-brand keeps its explicit ship-as-is warning.
+function assertBrandOverrides(ast, traverse, options) {
+  const explicitlyAllowed = allowFixedBrand(options);
+  const strict = strictFixedBrand(options);
+  for (const { field, color, line } of collectBrandOverrides(ast, traverse)) {
+    if (explicitlyAllowed) {
+      emitThemeWarning(options, t('publish.canvas_theme_fixed_brand_allowed', line, field));
+      continue;
+    }
+    if (!strict) {
+      emitThemeWarning(options, t('publish.canvas_theme_fixed_brand_relaxed', line, field));
+      continue;
+    }
+    throw new CliError(t('publish.canvas_theme_fixed_brand', line), {
+      code: 'OPENYIDA_CANVAS_THEME_FIXED_BRAND',
+      details: { stage: 'canvas_compile', sourcePath: options.sourcePath || '', line, field, value: color,
+        retryable: false, retrySafe: true, sideEffectState: 'none',
+        nextAction: { type: 'edit_source_then_recheck' },
+        sample: 'openyida sample openyida-page-template canvas-theme' },
+    });
+  }
+}
+
+// Parse a canvas source and return removable fixed-brand overrides (with char
+// offsets). Returns [] when the source has no theme markers or fails to parse,
+// mirroring the guard's own gate so the codemod never acts on unrelated code.
+function collectFixedBrandViolations(source) {
+  if (!/CanvasThemeProvider|useCanvasThemeContext|CanvasThemeContext|@canvas-theme-provider|antd/.test(source)) { return []; }
+  let ast;
+  try {
+    ast = Babel.packages.parser.parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript'] });
+  } catch { return []; }
+  const traverse = Babel.packages.traverse.default || Babel.packages.traverse;
+  return collectBrandOverrides(ast, traverse);
 }
 
-module.exports = { assertCanvasThemeStructure };
+module.exports = { assertCanvasThemeStructure, collectFixedBrandViolations };

package/lib/app/fix-theme.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * fix-theme.js - Canvas 主题迁移 codemod（纯函数）
+ *
+ * 把写死在 antd `ConfigProvider` 里的品牌交互色覆盖（如 `colorPrimary: '#1677ff'`）
+ * 从源码中移除，交由外层应用主题（CanvasThemeProvider / 平台主题）解析。这是
+ * "un-pin" 迁移：移除硬编码覆盖后，品牌色由应用主题接管，正好满足主题守卫
+ * `OPENYIDA_CANVAS_THEME_FIXED_BRAND` 的要求。
+ *
+ * 本模块不做任何 IO，只接收源码字符串、返回改写后的源码，便于单测与复用。
+ */
+
+const { collectFixedBrandViolations } = require('./canvas-theme-guard');
+
+/**
+ * 计算某个对象属性的删除区间：优先连同其后的逗号一起删；若是最后一个属性，
+ * 则回退删除其前的逗号。属性独占一行时顺带清理该行缩进与换行，避免留下空行。
+ * @param {string} source
+ * @param {number} start - 属性节点起始偏移
+ * @param {number} end - 属性节点结束偏移
+ * @returns {{ start: number, end: number }}
+ */
+function expandRemovalSpan(source, start, end) {
+  let removeStart = start;
+  let removeEnd = end;
+  const trailing = source.slice(removeEnd).match(/^[ \t]*,/);
+  if (trailing) {
+    removeEnd += trailing[0].length;
+    const lineStart = source.lastIndexOf('\n', removeStart - 1) + 1;
+    const indent = source.slice(lineStart, removeStart);
+    if (/^[ \t]*$/.test(indent)) {
+      removeStart = lineStart;
+      const newline = source.slice(removeEnd).match(/^[ \t]*\r?\n/);
+      if (newline) { removeEnd += newline[0].length; }
+    }
+    return { start: removeStart, end: removeEnd };
+  }
+  // Last property in its object: drop the preceding comma instead.
+  const leading = source.slice(0, removeStart).match(/,[ \t\r\n]*$/);
+  if (leading) { removeStart -= leading[0].length; }
+  return { start: removeStart, end: removeEnd };
+}
+
+/**
+ * 移除源码中写死的品牌色覆盖。改写按偏移从后往前应用，避免前面的偏移失效。
+ * @param {string} source - canvas 源码
+ * @returns {{ changed: boolean, output: string, violations: Array<{field:string,color:string,line:number}> }}
+ */
+function transformFixedBrandTheme(source) {
+  const violations = collectFixedBrandViolations(source)
+    .filter(item => Number.isInteger(item.start) && Number.isInteger(item.end) && item.end > item.start);
+  if (!violations.length) {
+    return { changed: false, output: source, violations: [] };
+  }
+  const spans = violations
+    .map(item => expandRemovalSpan(source, item.start, item.end))
+    .sort((a, b) => a.start - b.start);
+
+  // Adjacent overrides can claim the same separating comma (one as trailing,
+  // the next as leading), so merge overlapping spans instead of dropping one.
+  const merged = [];
+  for (const span of spans) {
+    const last = merged[merged.length - 1];
+    if (last && span.start <= last.end) { last.end = Math.max(last.end, span.end); }
+    else { merged.push({ ...span }); }
+  }
+
+  let output = source;
+  // Apply from the back so earlier offsets stay valid.
+  for (let i = merged.length - 1; i >= 0; i -= 1) {
+    output = output.slice(0, merged[i].start) + output.slice(merged[i].end);
+  }
+
+  return {
+    changed: output !== source,
+    output,
+    violations: violations.map(({ field, color, line }) => ({ field, color, line })),
+  };
+}
+
+module.exports = { transformFixedBrandTheme, expandRemovalSpan };

package/lib/app/publish.js

@@ -99,9 +99,12 @@ function parseArgs(argv = process.argv.slice(2)) {
   const compat = args.includes('--compat') || args.includes('--modern');
   const force = args.includes('--force');
   const canvas = args.includes('--canvas');
+  const allowFixedBrand = args.includes('--allow-fixed-brand');
+  const fixTheme = args.includes('--fix-theme');
+  const strictTheme = args.includes('--strict-theme');
   const autoNavOrder = args.includes('--auto-nav-order');
   const help = args.includes('--help') || args.includes('-h');
-  const filteredArgs = args.filter(arg => arg !== '--skip-lint' && arg !== '--health-check' && arg !== '--check' && arg !== '--compat' && arg !== '--modern' && arg !== '--force' && arg !== '--canvas' && arg !== '--auto-nav-order' && arg !== '--json' && arg !== '--help' && arg !== '-h');
+  const filteredArgs = args.filter(arg => arg !== '--skip-lint' && arg !== '--health-check' && arg !== '--check' && arg !== '--compat' && arg !== '--modern' && arg !== '--force' && arg !== '--canvas' && arg !== '--allow-fixed-brand' && arg !== '--fix-theme' && arg !== '--strict-theme' && arg !== '--auto-nav-order' && arg !== '--json' && arg !== '--help' && arg !== '-h');
 
   if (help) {
     usage(t('publish.usage'), t('publish.example'));
@@ -122,6 +125,9 @@ function parseArgs(argv = process.argv.slice(2)) {
     compat,
     force,
     canvas,
+    allowFixedBrand,
+    fixTheme,
+    strictTheme,
     autoNavOrder,
     browserOpenMode: openOption.mode,
   };
@@ -146,6 +152,52 @@ function buildCanvasCompileCliError(errorObject, sourcePath) {
   });
 }
 
+// Ask the human (via stdin) whether to migrate. Returns false unless both the
+// input and the prompt's output stream are real TTYs, so agent/CI/piped runs
+// never block on a question nobody can answer and must opt in with --fix-theme.
+function canPromptInteractively() {
+  return Boolean(process.stdin.isTTY) && Boolean(process.stderr.isTTY);
+}
+
+function confirmFixedBrandMigration() {
+  if (!canPromptInteractively()) { return Promise.resolve(false); }
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(`${t('publish.fix_theme_confirm')} `, (answer) => {
+      rl.close();
+      resolve(/^(y|yes)$/i.test(String(answer).trim()));
+    });
+  });
+}
+
+// Offer to un-pin fixed brand colors so the app theme takes over. Confirms with
+// the user (or auto-applies when --fix-theme is set), rewrites the source file
+// in place, and returns the migrated source; returns null when nothing changed
+// or the user declined. Callers continue publishing regardless unless strict.
+async function offerFixedBrandThemeMigration(sourcePath, source, { autoConfirm, strict } = {}) {
+  const { transformFixedBrandTheme } = require('./fix-theme');
+  const result = transformFixedBrandTheme(source);
+  if (!result.changed) { return null; }
+
+  warn(t('publish.fix_theme_detected', result.violations.length));
+  result.violations.forEach((item) => hint(t('publish.fix_theme_item', item.line, item.field, item.color)));
+
+  const proceed = autoConfirm === true || await confirmFixedBrandMigration();
+  if (!proceed) {
+    // Only nudge harder in strict mode; the relaxed path prints its own note.
+    if (strict) {
+      if (!canPromptInteractively()) { info(t('publish.fix_theme_flag_hint')); }
+      else { info(t('publish.fix_theme_skipped')); }
+    }
+    return null;
+  }
+
+  fs.writeFileSync(sourcePath, result.output);
+  success(t('publish.fix_theme_applied', sourcePath));
+  return result.output;
+}
+
 function enableQuietForJson(argv = []) {
   if (!Array.isArray(argv) || !argv.includes('--json')) {
     return () => {};
@@ -614,7 +666,7 @@ async function runMain(argv) {
   if (options.help) {
     return options;
   }
-  const { appType, formUuid, sourceFile, skipLint, healthCheck, compat, force, canvas: canvasFlag, autoNavOrder, browserOpenMode } = options;
+  const { appType, formUuid, sourceFile, skipLint, healthCheck, compat, force, canvas: canvasFlag, allowFixedBrand, fixTheme, strictTheme, autoNavOrder, browserOpenMode } = options;
 
   let sourcePath = path.resolve(sourceFile);
   if (!fs.existsSync(sourcePath)) {
@@ -644,8 +696,20 @@ async function runMain(argv) {
     // （JSX/TS → runtimeCode + importedModules），无需登录态，可在开浏览器前失败快。
     step(1, t('publish.step_canvas_compile'));
     info(t('publish.canvas_compiling'));
+    // Offer to un-pin fixed brand colors before compiling so the ask-human /
+    // --fix-theme migration still runs now that the guard no longer blocks by
+    // default. Skipped when --allow-fixed-brand explicitly ships as-is. In
+    // non-TTY runs the prompt declines instead of hanging, and the guard warns
+    // (or hard-fails under --strict-theme) rather than blocking the user.
+    if (!allowFixedBrand) {
+      const migratedSource = await offerFixedBrandThemeMigration(sourcePath, initialSourceCode, {
+        autoConfirm: fixTheme,
+        strict: strictTheme,
+      });
+      if (migratedSource !== null) { sourceCode = migratedSource; }
+    }
     try {
-      canvasResult = await compileCanvas(initialSourceCode, { sourcePath });
+      canvasResult = await compileCanvas(sourceCode, { sourcePath, allowFixedBrand, strictBrand: strictTheme });
     } catch (canvasCompileError) {
       throw buildCanvasCompileCliError(canvasCompileError, sourcePath);
     }

package/lib/core/command-manifest.js

@@ -403,6 +403,7 @@ const COMMAND_SIDE_EFFECTS = new Map([
 
   ...sideEffectEntries([
     'app-list',
+    'app-entry.get',
     'connector.detail',
     'connector.list',
     'connector.list-actions',
@@ -473,6 +474,7 @@ const COMMAND_SIDE_EFFECTS = new Map([
     'save-permission',
     'save-share-config',
     'update-app',
+    'app-entry.set',
     'update-form-config',
   ], sideEffect('remote_write')),
 
@@ -634,6 +636,7 @@ const COMMAND_PERMISSIONS = new Map([
   ...permissionEntries([
     'agent-capabilities',
     'app-list',
+    'app-entry.get',
     'check-design',
     'check-prd-completeness',
     'check-page',
@@ -725,6 +728,7 @@ const COMMAND_PERMISSIONS = new Map([
     'save-permission',
     'save-share-config',
     'update-app',
+    'app-entry.set',
     'update-form-config',
   ], permission('allow', 'write', {
     reason: ALLOW_WRITE_REASON,
@@ -1047,6 +1051,8 @@ const COMMAND_GROUPS = [
     id: 'app',
     titleKey: 'help.group_app',
     commands: [
+      command('app-entry.get', ['app-entry', 'get'], 'app-entry get <appType> [--json]', 'app_entry.desc_get'),
+      command('app-entry.set', ['app-entry', 'set'], 'app-entry set <appType> [--frontend <url>] [--management <url>] [--clear-frontend] [--clear-management] [--json]', 'app_entry.desc_set'),
       command('app-list', ['app-list'], 'app-list [--type managed|created] [--page N] [--size N]', 'help.cmd_app_list', {
         notes: ['Successful results include appUrl/workbenchUrl for the business workspace and adminUrl for developer administration. Complete application delivery retains adminUrl regardless of auth runtime; route construction does not verify recipient access. Preserve the frontend URL from its own page result.'],
       }),
@@ -1860,6 +1866,10 @@ function summarizeLocalizedCommands(commands) {
         },
         application_entry_policy: {
           delivery_unit: 'single_application_entry_group',
+          persistence: {
+            command_ids: ['app-entry.get', 'app-entry.set'],
+            policy: 'After successful application delivery, register only verified in-scope runtime entries; set performs partial merge and readback. Do not register admin/design URLs. Incremental resource-only work preserves existing entries. Clear only on explicit removal. Conflicts require reread and review, never blind retries.',
+          },
           workbench: {
             include: 'when_workspace_in_scope',
             url: '{base_url}/{appType}/workbench',

package/lib/core/locales/en.js

@@ -4,10 +4,18 @@
 'use strict';
 
 module.exports = {
+  app_entry: {
+    desc_get: 'Read frontend and management runtime entries',
+    desc_set: 'Register application entries with partial update and readback',
+    usage: 'Usage: openyida app-entry get <appType> [--json]\n       openyida app-entry set <appType> [--frontend <url>] [--management <url>] [--clear-frontend] [--clear-management] [--json]\nRegister only published, verified runtime URLs for this application. Omitted entries remain unchanged.',
+    invalid_url: 'Provide a complete http:// or https:// URL for a page, public page, or short link in the current application. Relative paths, designer URLs, and temporary authentication parameters are unsupported.',
+    invalid_response: 'Incomplete entry response. Read the current entries before retrying and check that the server supports the entry configuration API.',
+    readback_failed: 'Saved entries do not match the readback. Read and review the current entries; do not overwrite automatically.',
+  },
   design_plan: {
     rebase_required: 'Before first materialization, repair the matching facts in business.json/visual.json and preserve the source baseline. If the source changed, add --rebase-parts to the original materialize command to reconcile against the saved baseline. Do not invent a digest, delete drafts, or run init again.',
     baseline_missing: 'No trusted baseline matches these parts. Preserve the plan and facts; restore .build-plan-base.json from the original workspace. If unavailable, report the blocker instead of inventing a digest or rebuilding.',
-    rebase_stage_invalid: 'Rebasing is limited to drafts before first materialization. For presented or materialized plans use patch --materialize on the current build-plan.json, without merging initial parts again.',
+    rebase_stage_invalid: 'The plan is confirmed, so initial parts are no longer merged. Keep the current build-plan.json and adjust it through patch --materialize.',
     rebase_conflict: 'The source and part changed the same field differently. Review conflicts and explicitly select the current or baseline value in the part before retrying; preserve other facts. No files were saved.',
     repair_page_bindings: 'Repair pageApplications in visual.json to match customPageDetails in business.json one to one; exclude native forms. Each visualMemoryApplications must be an array; use [] when none apply. Keep the existing draft, fix the listed fields and retry the original command. Do not delete the directory or run init again.',
   },
@@ -1336,7 +1344,15 @@ Examples:
   },
   publish: {
     canvas_path_missing_app_type: 'Line {0}: navigation is missing appType. Use the canvas-navigation sample and verified IDs to build /{appType}/{pageType}/{formUuid}, not a bare /custom/ route.',
-    canvas_theme_fixed_brand: 'Line {0}: ConfigProvider fixes a brand interaction color to a string. Use canvas-theme and resolved application colors; CSS var belongs in DOM styles, not unresolved antd color tokens.',
+    canvas_theme_fixed_brand: 'Line {0}: ConfigProvider fixes a brand interaction color to a string. Use canvas-theme and resolved application colors; CSS var belongs in DOM styles, not unresolved antd color tokens. This is a local compile-time check and no network request has been made yet; pass --allow-fixed-brand or set OPENYIDA_CANVAS_ALLOW_FIXED_BRAND=1 to bypass temporarily.',
+    canvas_theme_fixed_brand_allowed: 'Line {0}: ConfigProvider hardcodes a brand interaction color ({1}); allowed for now because --allow-fixed-brand / OPENYIDA_CANVAS_ALLOW_FIXED_BRAND is set. Migrate to canvas-theme (resolved application colors) soon; this bypass will be removed in a later release.',
+    canvas_theme_fixed_brand_relaxed: 'Line {0}: ConfigProvider hardcodes a brand interaction color ({1}). Publishing is no longer blocked by default and continues as-is, but this color will not follow the application theme. Add --fix-theme to migrate automatically, or migrate to canvas-theme manually; use --strict-theme to hard-fail in CI.',
+    fix_theme_detected: 'Found {0} hardcoded brand interaction color override(s) that can be auto-migrated: remove the hardcoded overrides and let the application theme resolve them.',
+    fix_theme_item: '  · Line {0} {1}: {2}',
+    fix_theme_confirm: 'Auto-migrate the theme now? This rewrites your source file (removes the hardcoded brand-color overrides). [y/N]',
+    fix_theme_applied: 'Theme migration applied and written back to source: {0}',
+    fix_theme_skipped: 'Skipped theme migration; source left unchanged. Migrate to canvas-theme manually, or pass --allow-fixed-brand to bypass temporarily.',
+    fix_theme_flag_hint: 'Non-interactive environment: no auto-migration. Re-run with --fix-theme to rewrite the source automatically.',
     canvas_navigation_local_platform: 'Line {0} filters local views through platform navigation. Use mode=local or local view state; bind real pages to formUuid/navUuid and continue checking declared access.',
     canvas_navigation_document_flex: 'Line {0} uses a zero-basis workspace flex layout for document content. Refresh canvas-nav-content: document pages need natural height and block flow; fixed-height flex belongs to workspace.',
     canvas_theme_not_assembled: 'The theme marker on line {0} is not assembled. Run build-canvas-theme.js and compile/publish its separate output file. Pages with an integrated Provider do not need this marker.',
@@ -1467,7 +1483,7 @@ Examples:
     error: '\n❌ Publish error: {0}',
     source_not_found: '❌ Source file not found: {0}',
     source_path_hint: '💡 Try this source file path: {0}',
-    usage: 'Usage: openyida publish <sourceFile> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--auto-nav-order] [--open|--no-open] [--json]',
+    usage: 'Usage: openyida publish <sourceFile> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--fix-theme] [--strict-theme] [--auto-nav-order] [--open|--no-open] [--json]',
     example: 'Example: openyida publish pages/src/xxx.js APP_XXX FORM-XXX --health-check --auto-nav-order',
   },
 

package/lib/core/locales/zh.js

@@ -4,10 +4,18 @@
 'use strict';
 
 module.exports = {
+  app_entry: {
+    desc_get: '读取应用前台和业务工作台入口',
+    desc_set: '登记应用访问入口（局部更新并回读）',
+    usage: '用法：openyida app-entry get <appType> [--json]\n      openyida app-entry set <appType> [--frontend <url>] [--management <url>] [--clear-frontend] [--clear-management] [--json]\n仅登记已发布并验证的当前应用访问态地址；未指定的入口保持不变。',
+    invalid_url: '请提供当前组织、当前应用的完整访问 URL（http:// 或 https://）；支持页面地址、公开地址和短链接，不支持相对路径、开发后台和临时鉴权参数。',
+    invalid_response: '访问入口响应不完整，请重新读取后再决定是否重试，并确认服务端支持入口配置接口。',
+    readback_failed: '访问入口保存后的回读结果不一致，请重新读取并确认；不要自动覆盖。',
+  },
   design_plan: {
     rebase_required: '首次物化前请修正 business.json/visual.json 中的对应 facts，保留主计划基线。如果主计划已改变，在原 materialize 命令加 --rebase-parts，CLI 会根据保存的基线核对差异；不要手填 digest、删除草稿或重新 init。',
     baseline_missing: '未找到与片段匹配的可信原始基线。保留当前计划与 facts；从原工作区恢复 .build-plan-base.json 后重试。无法恢复时明确告知用户阻塞，不伪造摘要或自动重建。',
-    rebase_stage_invalid: '基线恢复仅用于首次物化前的草稿。已展示或已物化方案请沿用当前 build-plan.json，通过 patch --materialize 调整，不再合并初始化片段。',
+    rebase_stage_invalid: '方案已确认，不再合并初始化片段。请沿用当前 build-plan.json，通过 patch --materialize 调整。',
     rebase_conflict: '主计划和片段对同一字段有不同修改。按 conflicts 核对并在片段中明确采用当前值或原基线值后重试；其他 facts 保留。本次未保存文件。',
     repair_page_bindings: '按 business.json 的 customPageDetails 逐一修复 visual.json 的 pageApplications；原生表单不加入绑定。每项 visualMemoryApplications 必须为数组，无适用项用 []。保留现有草稿，按列出的字段修复后重试原命令；不要删除目录或重新 init。',
   },
@@ -1333,7 +1341,15 @@ openyida - 宜搭命令行工具
   },
   publish: {
     canvas_path_missing_app_type: '第 {0} 行的跳转地址缺少 appType。请提取 canvas-navigation，使用真实 appType 与页面 ID 构造 /{appType}/{pageType}/{formUuid}；不要直接跳转 /custom/ 等裸路径。',
-    canvas_theme_fixed_brand: '第 {0} 行的 ConfigProvider 将品牌交互色固定为字符串。请提取 canvas-theme，使用应用主题解析值；CSS var 仅直接用于 DOM 样式，不能替代 antd 色值解析。',
+    canvas_theme_fixed_brand: '第 {0} 行的 ConfigProvider 将品牌交互色固定为字符串。请提取 canvas-theme，使用应用主题解析值；CSS var 仅直接用于 DOM 样式，不能替代 antd 色值解析。这是本地编译期校验，此时尚未发起任何网络请求；如需临时放行请加 --allow-fixed-brand 或设置 OPENYIDA_CANVAS_ALLOW_FIXED_BRAND=1。',
+    canvas_theme_fixed_brand_allowed: '第 {0} 行的 ConfigProvider 写死了品牌交互色（{1}），因已设置 --allow-fixed-brand / OPENYIDA_CANVAS_ALLOW_FIXED_BRAND 暂时放行。请尽快迁移到 canvas-theme（应用主题解析），此旁路将在后续版本移除。',
+    canvas_theme_fixed_brand_relaxed: '第 {0} 行的 ConfigProvider 写死了品牌交互色（{1}）。默认不再阻断发布，已按原样继续；但该色值不会跟随应用主题。建议加 --fix-theme 自动迁移，或手动迁移到 canvas-theme；如需在 CI 强制拦截可加 --strict-theme。',
+    fix_theme_detected: '检测到 {0} 处写死的品牌交互色覆盖，可自动迁移：移除这些硬编码覆盖，交由应用主题解析。',
+    fix_theme_item: '  · 第 {0} 行 {1}：{2}',
+    fix_theme_confirm: '是否自动迁移主题？此操作会改写你的源码文件（移除写死的品牌色覆盖）。[y/N]',
+    fix_theme_applied: '已完成主题迁移并写回源码：{0}',
+    fix_theme_skipped: '已跳过主题迁移，未改动源码；你可以手动迁移到 canvas-theme，或加 --allow-fixed-brand 临时放行。',
+    fix_theme_flag_hint: '非交互环境未自动迁移；如需自动改写请重新执行并加 --fix-theme。',
     canvas_navigation_local_platform: '第 {0} 行把页内菜单交给平台导航过滤。请使用 mode=local 或直接切换本地视图；真实页面绑定 formUuid/navUuid，声明的权限仍需校验。',
     canvas_navigation_document_flex: '第 {0} 行的导航内容仍使用工作区 flex 零基准布局，会压缩 document 长页。请重新提取 canvas-nav-content：document 使用自然高度与块布局，workspace 才使用定高 flex。',
     canvas_theme_not_assembled: '第 {0} 行的主题标记尚未装配。请运行 build-canvas-theme.js 生成独立页面并编译发布输出文件；已直接接好 Provider 的页面无需此标记。',
@@ -1464,7 +1480,7 @@ openyida - 宜搭命令行工具
     error: '\n❌ 发布异常: {0}',
     source_not_found: '❌ 源文件不存在：{0}',
     source_path_hint: '💡 可尝试使用源文件路径：{0}',
-    usage: '用法: openyida publish <源文件路径> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--auto-nav-order] [--open|--no-open] [--json]',
+    usage: '用法: openyida publish <源文件路径> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--fix-theme] [--strict-theme] [--auto-nav-order] [--open|--no-open] [--json]',
     example: '示例：openyida publish pages/src/xxx.js APP_XXX FORM-XXX --health-check --auto-nav-order',
   },
 

package/lib/design-plan/materialize.js

@@ -827,6 +827,7 @@ function renderHtml(plan, sections) {
     if (result.error || result.status !== 0) {
       throw new CliError((result.stderr || result.error?.message || 'build-plan.html 生成失败').trim(), {
         code: 'DESIGN_PLAN_VALIDATION_FAILED',
+        details: { executable, status: result.status, stderr: result.stderr, error: result.error?.message },
       });
     }
     return result.stdout;
@@ -850,19 +851,13 @@ function renderDraftPrd(plan) {
 
 function prepareArtifacts(sourcePlan, outputDir, themeSeed, options = {}) {
   const timings = {};
-  let authoringIssues = [];
   const measure = (name, action) => {
     const start = performance.now();
-    try {return action();} catch (error) {
-      if (authoringIssues.length && !error.details?.issues) {
-        error.details = { ...error.details, issues: authoringIssues };
-      }
-      throw error;
-    } finally {timings[name] = Math.round((performance.now() - start) * 100) / 100;}
+    try {return action();} finally {timings[name] = Math.round((performance.now() - start) * 100) / 100;}
   };
   const plan = measure('validationAndNormalizationMs', () => {
     const normalized = normalizePlan(sourcePlan);
-    authoringIssues = validateAuthoring(normalized);
+    validateAuthoring(normalized);
     return normalized;
   });
   const designFile = path.resolve(outputDir, 'design.md');
@@ -880,11 +875,6 @@ function prepareArtifacts(sourcePlan, outputDir, themeSeed, options = {}) {
   measure('designValidationMs', () => validateDesignDocument(design, { prdMarkdown: prd, designFile }));
   // Validate the same public CSS pipeline used by both Fast and Plan before writing artifacts.
   const baseTheme = measure('themeValidationMs', () => applyDesignTokens(fs.readFileSync(path.join(PACKAGE_ROOT, 'yida-skills/skills/yida-design/references/theme/app-custom-theme-template.css'), 'utf8'), design));
-  if (options.renderHtml === false && authoringIssues.length) {
-    throw new CliError(t('design_document.invalid', 'build-plan.json', authoringIssues.map(issue => `${issue.path}: ${issue.message}`).join('; ')), {
-      code: 'DESIGN_PLAN_VALIDATION_FAILED', details: { issues: authoringIssues },
-    });
-  }
   const html = options.renderHtml === false ? undefined : measure('htmlMs', () => renderHtml({ ...plan, execution }));
   const outputs = {
     prd: path.join(outputDir, 'prd.md'),

package/lib/design-plan/preview.js

@@ -27,7 +27,10 @@ function readPart(file, base) {
   if (part.base?.digest !== base.digest || part.base?.revision !== base.revision) { invalid('stale base'); }
   if (!part.facts || typeof part.facts !== 'object' || Array.isArray(part.facts)) { invalid('facts'); }
   const keys = Object.keys(part.facts);
-  if (!keys.length || keys.some(key => !MODULES.includes(key))) { invalid('facts modules'); }
+  const unsupported = keys.filter(key => !MODULES.includes(key));
+  if (!keys.length || unsupported.length) {
+    invalid(`facts modules: ${keys.length ? unsupported.join(', ') : 'none'}; allowed: ${MODULES.join(', ')}`);
+  }
   for (const [key, value] of Object.entries(part.facts)) {
     if (['dataModels', 'businessFlows'].includes(key) ? !Array.isArray(value) : !value || typeof value !== 'object' || Array.isArray(value)) { invalid(key); }
   }

package/lib/design-plan/rebase.js

@@ -26,6 +26,13 @@ function reconcile(base, current, proposed, field, conflicts) {
   return proposed;
 }
 
+// Only part-proposed meta keys merge, so CLI-owned fields (revision, status, planState) stay untouched.
+function reconcileMeta(base, current, proposed, conflicts) {
+  if (!object(proposed)) { return reconcile(base, current, proposed, 'meta', conflicts); }
+  return Object.fromEntries(Object.entries(proposed).map(([key, value]) => [key,
+    reconcile(base?.[key], current?.[key], value, `meta.${key}`, conflicts)]));
+}
+
 function rebaseParts(source, input, businessFile, visualFile) {
   const { planBase } = require('./parallel');
   const baselinePath = path.join(path.dirname(path.resolve(input)), BASE_FILE);
@@ -35,8 +42,9 @@ function rebaseParts(source, input, businessFile, visualFile) {
   if (saved.schemaVersion !== 1 || !object(saved.plan) || !equal(saved.base, planBase(saved.plan))) {
     fail('DESIGN_PLAN_BASELINE_INVALID', { nextStep: t('design_plan.baseline_missing') });
   }
-  if (source.meta?.status !== 'draft' || source.meta?.planState?.presentedRevision
-      || source.meta?.planState?.planConfirmed || !equal(source.meta, saved.plan.meta)) {
+  // Confirmed plans are final: later edits go through patch --materialize.
+  if (source.meta?.status === 'confirmed' || source.meta?.planState?.planConfirmed === true
+      || source.meta?.planState?.confirmedRevision) {
     fail('DESIGN_PLAN_REBASE_STAGE_INVALID', { nextStep: t('design_plan.rebase_stage_invalid') });
   }
   const parts = [businessFile, visualFile].map(file => readJson(file));
@@ -47,8 +55,9 @@ function rebaseParts(source, input, businessFile, visualFile) {
   }
   return parts.map((part, index) => {
     const conflicts = [];
-    const facts = Object.fromEntries(Object.keys(part.facts).map(key => [key,
-      reconcile(saved.plan[key], source[key], part.facts[key], key, conflicts),
+    const facts = Object.fromEntries(Object.keys(part.facts).map(key => [key, key === 'meta'
+      ? reconcileMeta(saved.plan.meta, source.meta, part.facts.meta, conflicts)
+      : reconcile(saved.plan[key], source[key], part.facts[key], key, conflicts),
     ]));
     if (conflicts.length) {
       fail('DESIGN_PLAN_REBASE_CONFLICT', { sourcePath: [businessFile, visualFile][index], conflicts, nextStep: t('design_plan.rebase_conflict') });

package/lib/design-plan/validate.js

@@ -181,8 +181,8 @@ function collectIssues(plan) {
 
 function validateAuthoring(plan) {
   const issues = collectIssues(plan);
-  // A single issue keeps the existing precise error code from the full validator.
-  if (issues.length > 1 || issues.some(issue => issue.path.startsWith('visualStyle.forUser.pageApplications['))) {
+  // Report every gap here: stricter downstream validators would surface it with a different error shape.
+  if (issues.length) {
     throw new CliError(`计划有 ${issues.length} 项待补充：\n${issues.map(issue => `${issue.path}: ${issue.message}`).join('\n')}`, {
       code: 'DESIGN_PLAN_VALIDATION_FAILED', details: { issues },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.9.21",
+  "version": "2026.9.22",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",

package/yida-skills/skills/yida-app/workflow/plan/workflow.md

@@ -63,4 +63,4 @@ build-plan.json（业务和视觉的源事实）
 
 技能加载失败、限流或换模型后，先成功读取本工作流和当前步骤，再沿用已确认需求继续；未加载成功不得凭记忆生成 HTML 或确认参数。首次物化前只修 business.json/visual.json 对应 facts（菜单与执行规划在 business.facts.execution），不要直接修初始化主计划。字段错误按具体路径修正后重试。
 
-如果已经改动主计划并出现 DESIGN_PLAN_STALE_PART，在原 materialize 命令增加 --rebase-parts。CLI 使用 init 保存的 .build-plan-base.json 做三方核对，保留已完成 facts；冲突按 details.conflicts 明确选择后重试。基线缺失或无法核实时告知阻塞并恢复可信文件，不手填 digest、不删除重建、不重新 init。已物化后调整走 patch --materialize，不继续复用初始化片段。
+如果已经改动主计划并出现 DESIGN_PLAN_STALE_PART，在原 materialize 命令增加 --rebase-parts。CLI 使用 init 保存的 .build-plan-base.json 做三方核对，保留已完成 facts；冲突按 details.conflicts 明确选择后重试。基线缺失或无法核实时告知阻塞并恢复可信文件，不手填 digest、不删除重建、不重新 init。方案确认后调整一律走 patch --materialize；确认前重复物化仍可用 --rebase-parts 与基线核对，但改动内容以当前 build-plan.json 为准。

package/yida-skills/skills/yida-app/workflow/step-9-output-finish.md

@@ -44,6 +44,26 @@
 
 需求含 `userTasks` 和 `entryRecommendation` 时，按最终 PRD 核对服务与管理任务的实际访问路径，沿用用户已确认的调整；入口建议不作为完成证据。只有相关页面及访问配置回读通过后才交付对应入口，不为双入口补造后台功能，不用 `/admin` 开发后台代替业务管理工作区。
 
+## 登记应用访问入口
+
+前台与业务工作台是两个独立可选的入口，不是完整应用必须填满的字段。完整应用搭建完成后，根据本轮实际业务场景、用户确认的交付范围和入口回读证据决定是否登记，使应用卡片可以直接访问；不能只因为 CLI 返回了 `appUrl` / `workbenchUrl` 就自动登记为业务工作台。
+
+有需要登记的入口时，先执行 `openyida app-entry get <appType>` 查看已有配置，再按以下情况调用。命令内部执行版本校验、局部更新和保存后回读，输出 `urls` 供交付使用。
+
+| 本轮实际场景 | 登记方式 |
+| --- | --- |
+| 只有已验证的前台入口，例如公开展示或用户提交页面 | `openyida app-entry set <appType> --frontend <已验证前台完整URL>` |
+| 只有已验证的业务管理入口，例如内部管理工作区 | `openyida app-entry set <appType> --management <已验证业务管理完整URL>` |
+| 两类入口均在交付范围内，且各自验证通过 | `openyida app-entry set <appType> --frontend <已验证前台完整URL> --management <已验证业务管理完整URL>` |
+| 两类入口均不适用或尚未验证 | 不执行 `app-entry set`；不传空字符串、`null`、占位 URL，不为了补齐配置创建页面或拼接工作台链接 |
+
+- 前台地址必须来自已发布页面的成功返回及回读；独立前台仍需核验 `isRenderNav=false`。
+- 已验证的公开地址按完整 URL 原样登记，保留所选入口的域名、路径和有效参数；不能替换成需要登录的长链接，也不能为了登记而自动开启公开访问。
+- 业务工作台使用已验证的访问态 URL，不能登记 `/admin` 或设计器地址。
+- 单页、表单、流程等局部修改不自动覆盖应用入口。只搭前台时不传 `--management`；缺省值保留原配置。
+- 仅在用户明确移除入口时使用 `--clear-frontend` 或 `--clear-management`。
+- 版本冲突时重新读取并核对，不盲目重试覆盖。接口未部署、保存或回读失败时，明确说明入口尚未登记，不能宣称应用卡片已可访问。
+
 ## build-manifest 约定
 
 完整搭建收尾前，从本轮真实创建、复用和发布结果写入 `prd/<项目名>/build-manifest.json`。它只是轻量事实源，不是严格 schema；只记录已经拿到的真实资源名、类型和 ID，用于让 `check-prd-completeness` 做一次 app 资源列表 readback 后判断页面/资源数量是否完整。

package/yida-skills/skills/yida-canvas-custom-page/SKILL.md

@@ -198,5 +198,6 @@ openyida get-schema <appType> <formUuid> --field-map-json
 | [data-bridge-guide.md](references/data-bridge-guide.md) | 表单、平台连接器与自定义同源接口的数据桥 | 接入真实数据时阅读 |
 | [canvas-theme-provider.md](references/canvas-theme-provider.md) | 统一主题接入、示例装配、预览与发布 | 编写或调整 antd 页面时必读 |
 | [canvas-style-implementation-guide.md](references/canvas-style-implementation-guide.md) | 将 `design.md` 的 App 主题色、antd token、背景层、卡片边界、圆角密度、控件焦点/下拉 reset、图表配色落到 `YidaCodeCanvas` 组件 | MUST：新建页面或调整视觉前完整读取，见顶部编码前必读 |
+| [waf-safe-authoring.md](references/waf-safe-authoring.md) | 接口加白前规避平台安全（WAF）误拦的临时写法：不写正则字面量、危险 HTML/脚本串、注入特征串，及二分法定位 | 仅当用户反馈发布反复失败、疑似 WAF 拦截时阅读；常规生成不套用 |
 | [component-library-guide.md](references/component-library-guide.md) | 组件库推荐组合和页面选型建议 | 选择 UI/图表依赖时阅读 |
 | [canvas-authoring-examples.md](references/canvas-authoring-examples.md) | 最小组件、hooks、副作用、图表示例 | 手写 `.canvas.jsx` 代码时阅读 |

package/yida-skills/skills/yida-canvas-custom-page/references/waf-safe-authoring.md

@@ -0,0 +1,45 @@
+# WAF 安全误拦规避写法（临时方案）
+
+> **仅在用户反馈发布反复失败、且疑似被平台安全（WAF）拦截时才启用本文档。**
+> 这是接口尚未加白前的临时兜底方案，不是常规编码约束；正常生成 Canvas 页面时不必刻意套用，以免牺牲可读性。加白完成后本文档可下线。
+
+## 何时判定为 WAF 拦截
+
+发布返回 **HTTP 200，但响应体不是 JSON**，且 body 中含 `waf_block` 字样，即为安全拦截（并非业务报错）。表现为「发布一直失败」但登录态、参数、源码语法都正常。
+
+## 定位命中片段
+
+用二分法定位被拦截的源码片段：
+
+1. 注释/删除页面源码的一半，重发 `openyida publish`。
+2. 若仍被拦截，命中片段在保留的一半；若通过，命中片段在删掉的一半。
+3. 继续对半缩小范围，直到定位到触发拦截的具体写法。
+4. 按下方规则替换该写法后，恢复其余代码并重新发布。
+
+## 规避写法
+
+### 1. 不写正则字面量
+
+日期/字符串解析改用非正则方式：`String.split()`、`slice()`、`Number()`、`Date` 等。
+
+确需正则时用 `new RegExp('...')` 动态构造，避免形如 `\d{4}` 这类字面量直接出现在源码里。
+
+- 命中示例（避免）：直接在源码里写 `/\d{4}-\d{2}-\d{2}/` 之类的正则字面量。
+- 安全写法：`new RegExp('\\d{4}')`，或直接用 `str.split('-')` 取段、`Number(x)`、`new Date(str)` 解析。
+
+### 2. 不出现危险 HTML / 脚本字符串字面量
+
+源码中避免出现下列字符串字面量：`<script`、``eval(` ``、`innerHTML`、`javascript:`、`onerror=`、`<iframe` 等。
+
+事件处理写成 JSX 的 `onClick={fn}`，不要拼成 HTML 属性字符串（如把 `onclick="..."` 拼进字符串再注入）。
+
+### 3. 不出现注入特征串
+
+源码中不要出现 `union select`、`or 1=1`、`../`、`$(...)`、`/etc/passwd` 等注入特征串，即使只是常量、注释或示例数据。
+
+## 复发时的处理顺序
+
+1. 确认是 WAF 拦截（HTTP 200 + 非 JSON + `waf_block`），排除登录态/参数/语法问题。
+2. 二分法定位命中片段。
+3. 按上述规则替换写法。
+4. 恢复完整源码，重新发布并回读验收。

package/yida-skills/skills/yida-publish-page/SKILL.md

@@ -172,6 +172,7 @@ body { background-color: #f2f3f5; }
 | 发布后页面空白 | `YidaCodeCanvas` 页面检查 `YidaComp` 是否正确导出和依赖是否可加载；平台 JSX 组件页面检查 `renderJsx` 是否正确导出；同时查看浏览器控制台报错 |
 | 发布接口成功但页面坏了 | 重新执行 `openyida publish <源文件路径> <appType> <formUuid> --health-check` 先确认远端 Schema 已读回且内容匹配；首屏渲染、控制台报错和体验问题仍结合浏览器验证 |
 | 发布后功能异常 | `YidaCodeCanvas` 页面优先查依赖白名单、`YidaComp` 导出、hooks 副作用清理；平台 JSX 组件页面检查 `forceUpdate is not a function` 等常见错误，参考 `yida-custom-page` 平台 JSX 组件页面规范 |
+| 用户反馈发布反复失败、疑似安全（WAF）拦截 | 仅当发布返回 HTTP 200 但响应体非 JSON 且 body 含 `waf_block` 时判定为拦截；按 `yida-canvas-custom-page` 的 [waf-safe-authoring.md](../yida-canvas-custom-page/references/waf-safe-authoring.md) 用二分法定位命中片段并替换写法后重发。非常规场景不启用 |
 
 ## Agent 错误处理策略