openxiangda 1.0.25 → 1.0.27

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

@@ -79,6 +79,7 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - If there is no `sy-lowcode-app-workspace`, create one with `openxiangda workspace init <dir>` before writing forms, pages, or JS_CODE nodes.
 - Never treat `openxiangda form create` as page generation. It only creates a low-level platform form shell for diagnostics or for workspace publish internals. The source of user-facing pages is `sy-lowcode-app-workspace`.
 - Publish normal form pages, workflow form pages, and custom code pages through `openxiangda workspace publish --profile <name>` from the app workspace.
+- For live platform publishing, do not call `lowcode-workspace publish-all`, `pnpm publish:all`, or legacy project scripts such as `scripts/openxiangda-publish.mjs` directly. They are workspace internals and may miss the normal-user token/profile injection. Use `openxiangda workspace publish ...` so `OPENXIANGDA_PROFILE`, `OPENXIANGDA_BASE_URL`, `OPENXIANGDA_ACCESS_TOKEN`, and `OPENXIANGDA_APP_TYPE` are injected consistently.
 - For routine AI edits, avoid reflexive full publish. First run `openxiangda workspace publish --profile <name> --changed --dry-run`, then use `--changed`, `--page <pageCode>`, `--form <formCode>`, or `--only pages/a,forms/b`. Use full publish only when broad shared/config changes intentionally affect many modules.
 - Never store token data in the project directory. User tokens live in `~/.openxiangda/profiles.json`; project state lives in `.openxiangda/state.json` and stores only IDs and mappings.
 - Use logical resource codes in local files. Platform-specific IDs such as `formUuid`, `pageId`, `workflowId`, and `automationId` must be isolated by profile.

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/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.

package/openxiangda-skills/references/pages/publish-flow.md

@@ -6,6 +6,13 @@ Preferred publish command:
 openxiangda workspace publish --profile <name>
 ```
 
+Do not run `lowcode-workspace publish-all`, `pnpm publish:all`, or legacy
+project scripts such as `scripts/openxiangda-publish.mjs` directly for live
+publishing. Those commands are workspace internals. They may skip OpenXiangda's
+normal-user token/profile injection and fall back to old `APP_KEY` /
+`APP_SECRET` behavior, or publish with a buildId that the platform menu does not
+activate. Use `openxiangda workspace publish ...` as the external entry.
+
 For day-to-day AI edits, prefer a targeted publish:
 
 ```bash

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

@@ -2,6 +2,50 @@
 
 Workflow definitions are JSON objects saved by `openxiangda workflow create`.
 
+AI-authored workflows should prefer compile-time TypeScript SDK when the user does not need canvas editing. The SDK compiles local `workflow.ts` into the current v3 graph JSON, so the backend still uses the existing workflow engine for approval tasks, copy tasks, callback waits, branch advancement, operation logs, and process completion events.
+
+Example `src/workflows/expense_approval/workflow.ts`:
+
+```ts
+import { defineWorkflow } from "openxiangda/workflow";
+
+export default defineWorkflow({
+  build(flow) {
+    const start = flow.start();
+    const approve = flow.approval("manager_approval", {
+      label: "主管审批",
+      approverType: "ext_target_approval",
+      approvals: ["USER_MANAGER"],
+      approvalNames: ["主管"],
+      multiApprove: "or",
+    });
+    const copy = flow.copy("copy_finance", {
+      label: "抄送财务",
+      approverType: "ext_target_approval",
+      approvals: ["USER_FINANCE"],
+      approvalNames: ["财务"],
+    });
+    const end = flow.end();
+    flow.sequence(start, approve, copy, end);
+  },
+});
+```
+
+Resource manifest:
+
+```json
+{
+  "code": "expense_approval",
+  "formCode": "expense",
+  "workflowFile": "../../../workflows/expense_approval/workflow.ts",
+  "definitionFile": "definition.v3.json",
+  "previewFile": "preview.json",
+  "publish": true
+}
+```
+
+During `openxiangda resource publish`, the CLI compiles `workflowFile`, writes `definitionFile` and `previewFile` when configured, sends v3 `definitionJson` to the backend, and stores the preview in `viewJson` for read-only frontend display.
+
 Minimum shape:
 
 ```json

package/openxiangda-skills/skills/openxiangda-core/SKILL.md

@@ -154,6 +154,8 @@ openxiangda workspace publish --profile dev --only pages/dashboard,forms/custome
 
 Do not run a full publish automatically after a single page or form edit. Full publish is for intentional broad changes, shared/config changes that affect many modules, or cache repair. Targeted publish skips resources by default; pass `--resources` or run `openxiangda resource publish` when resource manifests changed.
 
+Do not call `lowcode-workspace publish-all`, `pnpm publish:all`, or legacy project scripts such as `scripts/openxiangda-publish.mjs` directly for live publishing. They are internal workspace commands and may not receive the normal-user access token from the selected profile. The external entry is always `openxiangda workspace publish ...`.
+
 - `OPENXIANGDA_PROFILE`
 - `OPENXIANGDA_BASE_URL`
 - `OPENXIANGDA_ACCESS_TOKEN`

package/openxiangda-skills/skills/openxiangda-workflow-automation/SKILL.md

@@ -52,6 +52,10 @@ Use `workflow pull` to inspect the live definition. Use logical workflow codes l
 
 JS_CODE is the backend execution escape hatch for workflow and automation. Use it when the logic must run on the server after a backend trigger, such as a fixed cron schedule, a form date-field schedule, a form submit/update/delete/field-change event, or a workflow approval/process event. It is appropriate for cross-form data queries, create/update/batch update operations, process termination, platform API calls, external HTTP calls, and complex orchestration that the frontend cannot handle reliably.
 
+For new AI-authored automations, prefer code-first `automation_code_ts` resources instead of visual v3 graph definitions. Put the source in `src/automations/<resourceCode>/index.ts`, define `definition.code.json` with `kind: "automation_code_ts"`, and provide `preview.json` for read-only frontend display. Use `ctx.logger.debug/info/warn/error(message, data?)` at every important step; OpenXiangda can inspect logs with `automation executions`, `automation logs`, and `automation diagnose`.
+
+For new AI-authored workflows where users do not need canvas editing, prefer compile-time `workflow.ts` using `openxiangda/workflow`. The CLI compiles it to v3 `definitionJson` and `preview.json`; the backend still runs the normal workflow engine for approval tasks, copy tasks, callback waits, branch advancement, and process records.
+
 Do not use JS_CODE for simple UI interactions, ordinary form validation, display-only page behavior, or logic that belongs in a normal React code page. For non-trivial backend logic, prefer JS_CODE V2 trusted Node scripts over large inline snippets. AI-authored JS_CODE source must be TypeScript:
 
 1. Put source in `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`.