openxiangda 1.0.26 → 1.0.28

package/README.md

@@ -25,6 +25,8 @@ openxiangda workspace publish --profile dev
 openxiangda menu list --profile dev
 openxiangda workflow list --profile dev
 openxiangda automation list --profile dev
+openxiangda automation executions daily_ticket_digest --profile dev
+openxiangda automation diagnose daily_ticket_digest --profile dev
 openxiangda permission role-list --profile dev
 openxiangda settings get customer --profile dev
 openxiangda resource validate --profile dev
@@ -78,6 +80,20 @@ openxiangda workspace bind --profile dev --app-type APP_XXXX
 
 工程化资源放在工作区 `src/resources/` 下，由 `openxiangda resource validate|plan|publish|pull` 管理。`workspace publish` 会先构建并注册 workspace 表单/页面，再执行非破坏性资源 upsert，这样菜单、权限组、流程和表单设置可以解析最新的 profile-local ID。需要删除平台中 manifest 未声明的资源时，显式传 `--prune`。连接器页面运行时通过 `sdk.connector.invoke()` / `sdk.connector.call("connector.api")` 调用平台运行时接口，第三方密钥只保存在后端连接器配置中。
 
+AI-authored automation can use code-first resources:
+
+- Source: `src/automations/<resourceCode>/index.ts`
+- Definition: `src/resources/automations/<resourceCode>/definition.code.json`
+- Preview: `src/resources/automations/<resourceCode>/preview.json`
+- Logs: `openxiangda automation executions|logs|diagnose`
+
+AI-authored workflows can use compile-time SDK resources:
+
+- Source: `src/workflows/<resourceCode>/workflow.ts`
+- Manifest: `src/resources/workflows/<resourceCode>/workflow.json`
+- Compiled graph: `definition.v3.json`
+- Read-only preview: `preview.json`
+
 Resource and connector manifest guide: [docs/openxiangda-resources-and-connectors.md](docs/openxiangda-resources-and-connectors.md).
 
 Skill migration plan: [docs/skill-refactor-plan.md](docs/skill-refactor-plan.md).

package/lib/cli.js

@@ -1,7 +1,10 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const os = require('os');
 const { spawnSync } = require('child_process');
+const { pathToFileURL } = require('url');
+const esbuild = require('esbuild');
 const {
   CONFIG_FILE,
   PROJECT_STATE_FILE,
@@ -94,6 +97,9 @@ Usage:
   openxiangda automation list [--profile name] [--json]
   openxiangda automation create <automationCode> --name <text> --trigger-json <file> --definition-json <file>
   openxiangda automation bind <automationCode> --automation-id <id>
+  openxiangda automation executions <automationCode|automationId> [--status failed] [--json]
+  openxiangda automation logs <instanceId> [--automation <automationCode|automationId>] [--summary] [--redact] [--json]
+  openxiangda automation diagnose <automationCode|automationId> [--redact] [--json]
   openxiangda automation publish|enable|disable <automationCode|automationId>
   openxiangda permission role-list|role-create|role-bind
   openxiangda permission page-group-list|page-group-create|page-group-bind
@@ -106,7 +112,7 @@ Usage:
 
 OpenXiangda 使用普通用户登录 token，不需要 AK/SK。
 表单页、流程表单页和代码页的主链路是 sy-lowcode-app-workspace + openxiangda workspace publish。
-JS_CODE V2 使用 trusted_node；AI 源码必须写在 src/js-code-nodes/<scriptCode>/index.ts，definition-json 中的 sourceFile.localPath 会在 validate/create 时先 TS 校验、再构建并上传为快照。`);
+JS_CODE V2 使用 trusted_node；AI 源码必须写在 src/js-code-nodes/<scriptCode>/index.ts，代码自动化源码写在 src/automations/<resourceCode>/index.ts。definition-json 中的 sourceFile.localPath 会在 validate/create/publish 时先 TS 校验、再构建并上传为快照。`);
 }
 
 async function update(args) {
@@ -840,6 +846,81 @@ async function form(args) {
     return;
   }
 
+  if (subcommand === 'executions') {
+    const [automationKey] = positional;
+    if (!automationKey) fail('用法: openxiangda automation executions <automationCode|automationId>');
+    const target = getWorkspaceTarget(config, profileName, flags);
+    const automationId = resolveAutomationId(target.bound, automationKey, flags);
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      apiPathWithQuery(
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/automations/${encodeURIComponent(automationId)}/executions`,
+        {
+          status: flags.status,
+          triggerEventType: flags['trigger-type'],
+          startDate: flags['start-date'],
+          endDate: flags['end-date'],
+          page: flags.page,
+          pageSize: flags['page-size'] || flags.limit,
+        }
+      )
+    );
+    if (flags.json) return writeJson(data);
+    printAutomationExecutionList(data);
+    return;
+  }
+
+  if (subcommand === 'logs') {
+    const [instanceId] = positional;
+    if (!instanceId) fail('用法: openxiangda automation logs <instanceId> [--automation <automationCode|automationId>]');
+    const target = getWorkspaceTarget(config, profileName, flags);
+    const data = await getAutomationExecutionDetailFromCli(
+      config,
+      target,
+      instanceId,
+      flags.automation || flags['automation-code'] || flags['automation-id']
+    );
+    const output = flags.redact ? redactLogValue(data) : data;
+    if (flags.json) return writeJson(output);
+    printAutomationExecutionLogs(output, { summary: Boolean(flags.summary) });
+    return;
+  }
+
+  if (subcommand === 'diagnose') {
+    const [automationKey] = positional;
+    if (!automationKey) fail('用法: openxiangda automation diagnose <automationCode|automationId>');
+    const target = getWorkspaceTarget(config, profileName, flags);
+    const automationId = resolveAutomationId(target.bound, automationKey, flags);
+    const records = await requestWithAuth(
+      config,
+      target.profileName,
+      apiPathWithQuery(
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/automations/${encodeURIComponent(automationId)}/executions`,
+        {
+          status: flags.status || 'failed',
+          page: 1,
+          pageSize: flags['page-size'] || flags.limit || 1,
+        }
+      )
+    );
+    const first = records?.data?.[0];
+    if (!first?.id) {
+      if (flags.json) return writeJson({ found: false, message: '未找到失败执行记录' });
+      print('未找到失败执行记录');
+      return;
+    }
+    const detail = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/automations/${encodeURIComponent(automationId)}/executions/${encodeURIComponent(first.id)}`
+    );
+    const output = flags.redact ? redactLogValue(detail) : detail;
+    if (flags.json) return writeJson({ found: true, detail: output, summary: buildAutomationDiagnosis(output) });
+    print(buildAutomationDiagnosis(output));
+    return;
+  }
+
   if (subcommand === 'publish') {
     const [formKey] = positional;
     if (!formKey || !flags['bundle-url']) {
@@ -1460,7 +1541,7 @@ async function automation(args) {
     return;
   }
 
-  fail('用法: openxiangda automation list|create|bind|pull|publish|unpublish|enable|disable|delete|validate|cron-validate');
+  fail('用法: openxiangda automation list|create|bind|pull|executions|logs|diagnose|publish|unpublish|enable|disable|delete|validate|cron-validate');
 }
 
 async function permission(args) {
@@ -2724,8 +2805,8 @@ function validateResourceItem(kind, item, errors, warnings) {
   if (kind === 'menus' && !item.name) errors.push(`${label}: 缺少 name`);
   if (kind === 'workflows') {
     if (!item.formCode && !item.formUuid) errors.push(`${label}: 缺少 formCode 或 formUuid`);
-    if (!item.definitionJson && !item.definitionFile) {
-      errors.push(`${label}: 缺少 definitionJson 或 definitionFile`);
+    if (!item.definitionJson && !item.definitionFile && !item.workflowFile) {
+      errors.push(`${label}: 缺少 definitionJson、definitionFile 或 workflowFile`);
     }
   }
   if (kind === 'automations') {
@@ -2852,6 +2933,158 @@ function resourceLabel(kind, item) {
   return `${kind}:${item.code || item.__source || item.__index || '?'}`;
 }
 
+async function getAutomationExecutionDetailFromCli(config, target, instanceId, automationKey) {
+  const automationIds = [];
+  if (automationKey) {
+    automationIds.push(resolveAutomationId(target.bound, automationKey, {}));
+  } else {
+    for (const entry of Object.values(target.bound.resources?.automations || {})) {
+      if (entry?.automationId) automationIds.push(entry.automationId);
+    }
+  }
+  const uniqueAutomationIds = Array.from(new Set(automationIds.filter(Boolean)));
+  if (uniqueAutomationIds.length === 0) {
+    fail('无法定位自动化，请传入 --automation <automationCode|automationId> 或先绑定本地自动化资源');
+  }
+
+  let lastError;
+  for (const automationId of uniqueAutomationIds) {
+    try {
+      return await requestWithAuth(
+        config,
+        target.profileName,
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/automations/${encodeURIComponent(automationId)}/executions/${encodeURIComponent(instanceId)}`
+      );
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError || new Error(`执行记录不存在: ${instanceId}`);
+}
+
+function printAutomationExecutionList(result) {
+  const rows = Array.isArray(result?.data) ? result.data : [];
+  if (rows.length === 0) {
+    print('暂无执行记录');
+    return;
+  }
+  for (const item of rows) {
+    print(
+      [
+        item.id,
+        item.status,
+        item.triggerEventType,
+        `${item.executionDuration ?? 0}ms`,
+        item.startedAt || item.createdAt || '',
+        item.errorMessage ? `error=${item.errorMessage}` : '',
+      ]
+        .filter(Boolean)
+        .join('  ')
+    );
+  }
+  if (result?.totalCount !== undefined) {
+    print(`共 ${result.totalCount} 条，page=${result.page || 1}, pageSize=${result.pageSize || rows.length}`);
+  }
+}
+
+function printAutomationExecutionLogs(detail, options = {}) {
+  if (options.summary) {
+    print(buildAutomationDiagnosis(detail));
+    return;
+  }
+  print(`执行记录: ${detail.id}`);
+  print(`状态: ${detail.status}`);
+  print(`自动化: ${detail.definitionName || detail.definitionId}`);
+  print(`触发: ${detail.triggerEventType || ''} ${detail.triggerEventId || ''}`.trim());
+  print(`耗时: ${detail.executionDuration ?? 0}ms`);
+  if (detail.errorMessage) print(`错误: ${detail.errorMessage}`);
+  if (detail.triggerEventData !== undefined) {
+    print('\ntriggerEventData:');
+    print(JSON.stringify(detail.triggerEventData, null, 2));
+  }
+  if (detail.result !== undefined && detail.result !== null) {
+    print('\nresult:');
+    print(typeof detail.result === 'string' ? detail.result : JSON.stringify(detail.result, null, 2));
+  }
+  print('\nlogs:');
+  const executionLogs = Array.isArray(detail.nodeExecutionLogs) ? detail.nodeExecutionLogs : [];
+  for (const entry of executionLogs) {
+    if (entry?.logs && Array.isArray(entry.logs)) {
+      print(`# ${entry.nodeLabel || entry.nodeId || entry.nodeType || 'node'} (${entry.success ? 'success' : 'failed'})`);
+      for (const log of entry.logs) print(formatAutomationLogLine(log));
+    } else {
+      print(formatAutomationLogLine(entry));
+    }
+  }
+}
+
+function formatAutomationLogLine(log) {
+  if (typeof log === 'string') return log;
+  if (!log || typeof log !== 'object') return String(log);
+  const prefix = [log.timestamp, log.level, log.stepKey ? `step=${log.stepKey}` : '']
+    .filter(Boolean)
+    .join(' ');
+  const message = log.message || JSON.stringify(log);
+  const data = log.data !== undefined ? ` ${JSON.stringify(log.data)}` : '';
+  return `${prefix ? `[${prefix}] ` : ''}${message}${data}`;
+}
+
+function buildAutomationDiagnosis(detail) {
+  const lines = [];
+  lines.push(`执行记录: ${detail.id}`);
+  lines.push(`状态: ${detail.status}`);
+  lines.push(`自动化: ${detail.definitionName || detail.definitionId}`);
+  if (detail.errorMessage) lines.push(`错误: ${detail.errorMessage}`);
+  lines.push(`耗时: ${detail.executionDuration ?? 0}ms`);
+  const importantLogs = flattenAutomationLogs(detail.nodeExecutionLogs).filter(log => {
+    if (typeof log === 'string') return /ERROR|WARN|异常|失败|超时/i.test(log);
+    const level = String(log?.level || '').toUpperCase();
+    return ['ERROR', 'WARN', 'CONSOLE ERROR', 'CONSOLE WARN'].includes(level);
+  });
+  if (importantLogs.length > 0) {
+    lines.push('\n关键日志:');
+    for (const log of importantLogs) lines.push(`- ${formatAutomationLogLine(log)}`);
+  }
+  if (detail.triggerEventData !== undefined) {
+    lines.push('\n触发数据:');
+    lines.push(JSON.stringify(detail.triggerEventData, null, 2));
+  }
+  if (detail.result !== undefined && detail.result !== null) {
+    lines.push('\n返回结果:');
+    lines.push(typeof detail.result === 'string' ? detail.result : JSON.stringify(detail.result, null, 2));
+  }
+  return lines.join('\n');
+}
+
+function flattenAutomationLogs(nodeExecutionLogs) {
+  const result = [];
+  for (const entry of Array.isArray(nodeExecutionLogs) ? nodeExecutionLogs : []) {
+    if (Array.isArray(entry?.logs)) result.push(...entry.logs);
+    else result.push(entry);
+  }
+  return result;
+}
+
+function redactLogValue(value) {
+  if (typeof value === 'string') {
+    return value
+      .replace(/(access[_-]?token|refresh[_-]?token|authorization|password|secret|key)(["':= ]+)([^"',\s}]+)/gi, '$1$2***')
+      .replace(/1[3-9]\d{9}/g, '1**********')
+      .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '***@***');
+  }
+  if (Array.isArray(value)) return value.map(redactLogValue);
+  if (value && typeof value === 'object') {
+    const next = {};
+    for (const [key, item] of Object.entries(value)) {
+      next[key] = /token|authorization|password|secret|credential/i.test(key)
+        ? '***'
+        : redactLogValue(item);
+    }
+    return next;
+  }
+  return value;
+}
+
 async function publishResourcesForWorkspace(config, profileName, options = {}) {
   const manifest = loadWorkspaceResources();
   const validation = validateWorkspaceResources(manifest);
@@ -3412,21 +3645,32 @@ async function publishNotificationResources(config, target, notifications, resul
 async function publishWorkflowResources(config, target, workflows, result) {
   for (const workflowItem of workflows) {
     const existing = await findExistingWorkflow(config, target, workflowItem.code);
-    const definitionJson = await resolveManifestJson(
+    const compiledWorkflow = await compileWorkflowSourceFile(workflowItem);
+    const definitionJson = compiledWorkflow?.definitionJson || await resolveManifestJson(
       config,
       target.profileName,
       workflowItem,
       'definitionJson',
       'definitionFile'
     );
-    const viewJson = await resolveManifestJson(
+    const viewJson =
+      compiledWorkflow?.previewJson ??
+      (await resolveManifestJson(
+        config,
+        target.profileName,
+        workflowItem,
+        'viewJson',
+        'viewFile',
+        true
+      )) ??
+      (await resolveManifestJson(
       config,
       target.profileName,
       workflowItem,
-      'viewJson',
-      'viewFile',
+      'previewJson',
+      'previewFile',
       true
-    );
+    ));
     const formUuid = resolveManifestFormUuid(target.bound, workflowItem);
     const body = {
       resourceCode: workflowItem.code,
@@ -3492,14 +3736,23 @@ async function publishAutomationResources(config, target, automations, result) {
       'definitionJson',
       'definitionFile'
     );
-    const viewJson = await resolveManifestJson(
+    const viewJson =
+      (await resolveManifestJson(
+        config,
+        target.profileName,
+        automationItem,
+        'viewJson',
+        'viewFile',
+        true
+      )) ??
+      (await resolveManifestJson(
       config,
       target.profileName,
       automationItem,
-      'viewJson',
-      'viewFile',
+      'previewJson',
+      'previewFile',
       true
-    );
+    ));
     const automationPayload = resolveAutomationManifestPayload(target, automationItem);
     const body = {
       resourceCode: automationItem.code,
@@ -4379,6 +4632,57 @@ async function resolveManifestJson(config, profileName, item, objectKey, fileKey
   return value;
 }
 
+async function compileWorkflowSourceFile(workflowItem) {
+  if (!workflowItem.workflowFile) return undefined;
+  const sourcePath = path.resolve(workflowItem.__dir || process.cwd(), workflowItem.workflowFile);
+  if (!fs.existsSync(sourcePath)) {
+    fail(`${resourceLabel('workflow', workflowItem)} workflowFile 不存在: ${sourcePath}`);
+  }
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openxiangda-workflow-'));
+  const outfile = path.join(tmpDir, `${workflowItem.code || 'workflow'}.mjs`);
+  try {
+    await esbuild.build({
+      entryPoints: [sourcePath],
+      outfile,
+      bundle: true,
+      platform: 'node',
+      format: 'esm',
+      target: ['node18'],
+      sourcemap: false,
+      logLevel: 'silent',
+    });
+    const mod = await import(`${pathToFileURL(outfile).href}?t=${Date.now()}`);
+    const exported = mod.default || mod.workflow || mod.definition;
+    if (!exported) {
+      fail(`${resourceLabel('workflow', workflowItem)} workflowFile 必须 default export defineWorkflow(...)`);
+    }
+    const compiled =
+      typeof exported.compile === 'function'
+        ? exported.compile()
+        : typeof exported === 'function'
+          ? exported()
+          : exported;
+    if (!compiled?.definitionJson || !compiled?.previewJson) {
+      fail(`${resourceLabel('workflow', workflowItem)} workflowFile 编译结果必须包含 definitionJson 和 previewJson`);
+    }
+    if (workflowItem.definitionFile) {
+      writeCompiledResourceFile(workflowItem, workflowItem.definitionFile, compiled.definitionJson);
+    }
+    if (workflowItem.previewFile) {
+      writeCompiledResourceFile(workflowItem, workflowItem.previewFile, compiled.previewJson);
+    }
+    return compiled;
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+function writeCompiledResourceFile(item, relativeFile, value) {
+  const filePath = path.resolve(item.__dir || process.cwd(), relativeFile);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
 function resolveManifestFormUuid(bound, item, options = {}) {
   const formKey = item.formCode || item.form || (options.fallbackToCode ? item.code : undefined);
   if (formKey) {
@@ -4889,23 +5193,26 @@ function resolveJsCodeBundlePath(localPath, scriptCode) {
   }
 
   const normalized = localPath.replace(/\\/g, '/');
-  const matched = normalized.match(/src\/js-code-nodes\/([^/]+)\/index\.tsx?$/);
+  const jsCodeMatched = normalized.match(/src\/js-code-nodes\/([^/]+)\/index\.tsx?$/);
+  const automationMatched = normalized.match(/src\/automations\/([^/]+)\/index\.tsx?$/);
+  const matched = jsCodeMatched || automationMatched;
   const resolvedScriptCode = scriptCode || matched?.[1];
   if (!resolvedScriptCode) {
     fail(
-      `无法从 sourceFile.localPath 推断 scriptCode，请使用 src/js-code-nodes/<scriptCode>/index.ts: ${localPath}`
+      `无法从 sourceFile.localPath 推断 scriptCode，请使用 src/js-code-nodes/<scriptCode>/index.ts 或 src/automations/<scriptCode>/index.ts: ${localPath}`
     );
   }
+  const sourceKind = automationMatched ? 'automations' : 'js-code-nodes';
 
   const workspaceRoot = findWorkspaceRoot(localPath);
-  const result = spawnSync('pnpm', ['build-js-code', '--script', resolvedScriptCode], {
+  const result = spawnSync('pnpm', ['build-js-code', '--script', resolvedScriptCode, '--source', sourceKind], {
     cwd: workspaceRoot,
     stdio: 'inherit',
   });
   if (result.status !== 0) {
     fail(`JS_CODE bundle构建失败: ${resolvedScriptCode}`);
   }
-  return path.join(workspaceRoot, 'dist', 'js-code-nodes', resolvedScriptCode, 'index.cjs');
+  return path.join(workspaceRoot, 'dist', sourceKind, resolvedScriptCode, 'index.cjs');
 }
 
 function findWorkspaceRoot(startPath) {

package/openxiangda-skills/SKILL.md

@@ -144,7 +144,7 @@ Workflow / automation / permissions:
 Platform domain knowledge (read these first when generating forms or pages so the output matches the live platform behavior):
 
 - `references/platform-data-model.md` — how the platform persists field values (JSONB, `{label, value}` for option fields, attachment shape, etc.). Use this whenever you write, render, or diagnose form data.
-- `references/style-system.md` — three-layer style architecture, CSS namespace, and the no-hardcoded-color rule. Use this before writing any page or form CSS.
+- `references/style-system.md` — three-layer style architecture, CSS namespace, and flexible Tailwind/CSS guidance. Use this before writing substantial page or form CSS.
 - `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, recommended directory layout for `src/pages` and `src/forms`. Use this before scaffolding a new page or list view.
 - `references/best-practices.md` — read this before implementing app-level business patterns; it points to `examples/best-practices/` and explains when to use status fields instead of workflow.
 - `references/component-guide.md` — when to pick platform components vs. raw Ant Design vs. custom components, with the rules for option fields. Use this before introducing a new component.

package/openxiangda-skills/references/automation-v3.md

@@ -62,6 +62,54 @@ Use CLI flags such as `--form-code customer` so the CLI can fill `formUuid` from
 
 ## Definition JSON
 
+AI-authored automations should prefer code-first definitions when the logic is mainly backend orchestration and does not need a visual editable canvas.
+
+Code automation definition:
+
+```json
+{
+  "kind": "automation_code_ts",
+  "version": "code_v1",
+  "runtimeMode": "trusted_node",
+  "sourceType": "file_snapshot",
+  "scriptCode": "daily_ticket_digest",
+  "sourceFile": {
+    "localPath": "src/automations/daily_ticket_digest/index.ts"
+  },
+  "timeoutMs": 30000
+}
+```
+
+Author source in `src/automations/<resourceCode>/index.ts`. During validate/create/publish, the CLI runs `pnpm build-js-code --script <resourceCode> --source automations`, uploads `dist/automations/<resourceCode>/index.cjs`, and replaces `sourceFile.localPath` with immutable snapshot metadata.
+
+Pair it with a structured preview file:
+
+```json
+{
+  "kind": "automation_code_preview",
+  "version": "preview_v1",
+  "steps": [
+    { "id": "load", "type": "data_read", "label": "查询待处理数据" },
+    { "id": "notify", "type": "notification", "label": "发送提醒" }
+  ],
+  "edges": [{ "source": "load", "target": "notify" }]
+}
+```
+
+Resource manifest shape:
+
+```json
+{
+  "code": "daily_ticket_digest",
+  "name": "每日工单摘要",
+  "triggerConfig": { "type": "scheduled", "enabled": true },
+  "definitionFile": "definition.code.json",
+  "previewFile": "preview.json",
+  "publish": true,
+  "enable": true
+}
+```
+
 Minimum shape:
 
 ```json
@@ -123,6 +171,14 @@ The backend runs the snapshot in the trusted Node runtime, applies the node time
 
 Runtime context includes `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`. Data/process bridge methods include `ctx.methods.queryOneData`, `queryManyData`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
 
+Code automation also exposes `ctx.logger.debug/info/warn/error(message, data?)`. AI-authored code should log input parsing, query conditions, external calls, writes, branch decisions, and caught errors. Logs are stored as full raw execution data by default. Use CLI diagnosis commands:
+
+```bash
+openxiangda automation executions daily_ticket_digest --status failed --profile dev
+openxiangda automation logs <instanceId> --automation daily_ticket_digest --profile dev
+openxiangda automation diagnose daily_ticket_digest --profile dev
+```
+
 Notification bridge methods include `ctx.notification.sendByType`, `batchSendByType`, `findConfig`, and `previewTemplate`. For custom business messages, create `src/resources/notifications/` first and use its `notificationType`; do not call legacy `/api/notification-config/*` endpoints directly.
 
 Example `src/js-code-nodes/scheduled_reconcile/index.ts`:

package/openxiangda-skills/references/component-guide.md

@@ -9,8 +9,8 @@
 1. **平台组件优先**：所有平台组件已经接入了组织架构、文件存储、权限、多端适配等平台能力，重写一遍 = 丢能力 + 后续无法维护。
 2. **基于 antd / antd-mobile 包装**：自定义组件必须站在 antd 之上，保证 PC 和移动端的基础体验一致。
 3. **成熟能力先调研开源方案**：图表、动画、拖拽、虚拟列表、富文本、日历、导入导出、复杂表格等，不要直接手写。先查当前项目依赖、官方文档和维护状态，再决定使用库或轻量封装。
-4. **样式走变量与语义类**：使用 CSS 变量、Tailwind 语义类，**禁止**在 JSX 中硬编码颜色、间距、字号、圆角。
-5. **不覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变。
+4. **样式优先走变量与语义类**：常规后台体验优先使用 CSS 变量、Tailwind 语义类和 Ant Design token；当业务视觉需要时，可以使用 Tailwind 普通类、任意值、局部 CSS、页面级变量或少量动态 inline style。
+5. **谨慎覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变；确实需要覆盖时要限定页面作用域，并优先考虑组件 props、`className`、CSS 变量或 `ConfigProvider`。
 
 ---
 
@@ -86,7 +86,7 @@ import {
 
 ## 4. 自定义组件开发规范
 
-### 4.1 正确：基于 antd 包装 + CSS 变量 + 语义类
+### 4.1 推荐：基于 antd 包装 + CSS 变量 + 语义类
 
 ```tsx
 import { Select, SelectProps } from 'antd';
@@ -115,7 +115,7 @@ export function CustomSelect({ options, className, ...rest }: CustomSelectProps)
 - 透传 `...rest`，保留 antd 全部 API。
 - `popupClassName="sy-app-workspace"` 确保弹层应用平台样式作用域。
 - `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
-- 使用 `w-full`、`rounded-form` 等语义类，不写 `style={{ width: '100%' }}`。
+- 使用 `w-full`、`rounded-form` 等语义类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 普通类、任意值或局部 CSS。
 
 ### 4.2 错误：从头实现选择器
 
@@ -162,7 +162,7 @@ function BadSelect({ options }) {
    }
    ```
 
-   > 覆盖时只能使用 `style-system.md` 中定义的 `--sy-color-*`、`--sy-radius-*`、`--sy-spacing-*` 等变量名，自创变量不会生效。
+   > 优先覆盖 `style-system.md` 中定义的 `--sy-color-*`、`--sy-radius-*`、`--sy-spacing-*` 等平台变量。需要页面专属视觉时，可以新增页面级 CSS 变量，建议加业务前缀，避免与平台变量冲突。
 
 3. **antd `ConfigProvider` 主题**
    ```tsx
@@ -171,7 +171,7 @@ function BadSelect({ options }) {
    </ConfigProvider>
    ```
 
-4. **禁止**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）—— fragile，升级即坏。
+4. **谨慎**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）属于私有 API，升级风险较高。确实需要时必须限定在页面根类或 `.sy-app-workspace` 下，并优先考虑 `ConfigProvider`、`className`、组件 props 或 CSS 变量是否能解决。
 
 ---
 
@@ -207,10 +207,10 @@ export function ActionButton(props) {
 | 用 `<input type="file">` 上传 | 用 `AttachmentField` / `ImageField` |
 | 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
 | 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
-| `style={{ color: '#333', padding: 16 }}` 硬编码 | Tailwind 语义类或 CSS 变量 |
+| 常规组件大量写 `style={{ color: '#333', padding: 16 }}` | 优先 Tailwind 语义类、普通工具类、CSS 变量或局部 CSS；动态值和少量精调 inline style 可接受 |
 | Select / Date / Modal 弹层错位、被滚动容器裁切 | 加 `getPopupContainer={(trigger) => trigger.parentElement}`，并在弹层 `popupClassName` 上加 `sy-app-workspace` |
 | 不分端，PC 组件直接放移动端 | 按端拆页 + 端内用对应 UI 库 |
-| 覆盖 `.ant-xxx` 内部 class | 用 `className`、CSS 变量或 `ConfigProvider` 主题 |
+| 无作用域覆盖 `.ant-xxx` 内部 class | 优先用 `className`、CSS 变量或 `ConfigProvider` 主题；必要覆盖时限定到页面命名空间 |
 | 在自定义组件中不透传 `...rest` / `ref` | 透传 props 与 `forwardRef`，保留底层组件全部能力 |
 
 ---
@@ -219,6 +219,6 @@ export function ActionButton(props) {
 
 - [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
 - [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
-- [ ] 样式 → 全部走 Tailwind 语义类 / CSS 变量 / ConfigProvider，无硬编码？
+- [ ] 样式 → 常规区域优先 Tailwind 语义类 / CSS 变量 / ConfigProvider；特殊视觉用 Tailwind 任意值、局部 CSS 或页面级变量且作用域收敛？
 - [ ] 弹层 → 设置了 `getPopupContainer` 与 `sy-app-workspace` 弹层样式作用域？
 - [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？

package/openxiangda-skills/references/openxiangda-api.md

@@ -358,6 +358,10 @@ Requires Bearer token. Lists versions in the same automation group.
 
 Requires Bearer token. Lists execution records for diagnosis.
 
+### GET `/apps/:appType/automations/:automationId/executions/:instanceId`
+
+Requires Bearer token. Returns one execution record with raw `nodeExecutionLogs`, `triggerEventData`, `executionContext`, result, and error details for AI diagnosis.
+
 ### GET `/apps/:appType/roles`
 
 Requires Bearer token. Lists app roles visible to the current user.