openxiangda 1.0.155 → 1.0.157

package/README.md

@@ -2,7 +2,7 @@
 
 OpenXiangda is a lightweight CLI and skill package for private low-code platforms.
 
-It uses normal platform user login tokens through `/openxiangda-api/v1`; it does not use AK/SK.
+Normal OpenXiangda app development uses platform-user login tokens through `/openxiangda-api/v1`; it does not use AK/SK. External backend and third-party integrations use the separate `openxiangda-open-api` skill, `/dingtalk-api/v1.0`, and a platform-managed AK/SK credential.
 
 Private platform routing is fixed: backend APIs are under `/service`, platform management is under `/platform`, and app runtime access is under `/view`. Passing a root domain such as `https://yida.wisejob.cn/` to the CLI is supported; OpenXiangda stores the API base as `https://yida.wisejob.cn/service`.
 
@@ -119,13 +119,18 @@ openxiangda organization department-list --profile dev --json
 openxiangda organization account-list --profile dev --keyword alice --json
 openxiangda permission snapshot --form-codes customer,orders --json
 openxiangda permission audit --json
+
+# external backend Open API contract and one-time credential management:
+openxiangda open-api spec list --search submitFormData --json
+openxiangda open-api spec describe /dingtalk-api/v1.0/forms/submitFormData --method post --json
+openxiangda open-api credential list --profile dev --json
 ```
 
 调用和测试类命令会检查 JSON envelope。HTTP 200 但 `code: "PUBLIC_GRANT_DENIED"`、`success: false` 或其他字符串业务错误码会被当作失败。
 
 角色资源里的 `apiPermissionCodes` 依赖平台端已存在的 API 权限点。比如校区管理员需要维护应用角色时，manifest 应声明 `app:role:manage`；如果 `resource publish` 提示缺少这个权限点，说明当前平台租户的 `api_permissions` seed 不完整，通常是平台版本未包含 seed、服务启动 seed 没跑成功，或租户创建在 seed 之后。处理方式是升级/重启平台并补齐权限点 seed，或由平台管理员补入 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage` 等应用级权限点；不要为了通过发布删除 manifest 里的权限声明。
 
-Codex skills are installed separately from login/profile state. Run `openxiangda skill install` after installing or linking the CLI. It installs the `openxiangda` root skill plus the 8 top-level subskills into `${CODEX_HOME:-~/.codex}/skills` by default:
+Codex skills are installed separately from login/profile state. Run `openxiangda skill install` after installing or linking the CLI. It installs the `openxiangda` root skill plus the 9 top-level subskills into `${CODEX_HOME:-~/.codex}/skills` by default:
 
 - `openxiangda`
 - `openxiangda-core`
@@ -136,6 +141,7 @@ Codex skills are installed separately from login/profile state. Run `openxiangda
 - `openxiangda-workflow-automation`
 - `openxiangda-permission-settings`
 - `openxiangda-inspect`
+- `openxiangda-open-api`
 
 Use `openxiangda skill install --dest <skills-dir>` to target a different Codex skills directory. If a same-name skill exists but was not installed by OpenXiangda, the command refuses to overwrite it unless `--force` is provided. Restart Codex after installing skills.
 

package/lib/cli.js

@@ -37,6 +37,13 @@ const {
   renderResourceExplain,
 } = require('./design-gates');
 const { buildDesignReview, renderDesignReview } = require('./design-review');
+const {
+  describeOpenApiOperation,
+  listOpenApiOperations,
+  listOpenApiTags,
+  loadOpenApiDocument,
+  redactOpenApiSecret,
+} = require('./open-api');
 const {
   appendBypassLog,
   archiveSddChange,
@@ -83,6 +90,7 @@ async function main(argv) {
   if (command === 'platform') return platform(rest);
   if (command === 'doctor') return doctor(rest);
   if (command === 'contract') return contract(rest);
+  if (command === 'open-api') return openApi(rest);
   if (command === 'design') return design(rest);
   if (command === 'sdd') return sdd(rest);
   if (command === 'workspace') return workspace(rest);
@@ -126,6 +134,8 @@ Usage:
   openxiangda auth status|refresh|logout [--profile name]
   openxiangda doctor [--profile name] [--app-type APP_XXX] [--release] [--json]
   openxiangda contract list|explain <contract-name> [--json]
+  openxiangda open-api spec tags|list|describe [operationId|path] [--method post] [--tag name] [--search text] [--json]
+  openxiangda open-api credential list|get|create|update|rotate-secret [id] [--profile name] [--show-secret] [--yes] [--json]
   openxiangda design gates|template|review [--topic code] [--json]
   openxiangda sdd init|migrate|propose|approve|status|context|verify|sync|archive [change] [--json]
   openxiangda env [--profile name]
@@ -186,7 +196,7 @@ Usage:
   openxiangda skill status [--agent codex|claude|qoder|dual] [--dest <skills-dir>] [--json]
   openxiangda skill bootstrap [<dir>] [--force] [--dry-run] [--json]
 
-OpenXiangda 使用普通用户登录 token，不需要 AK/SK。
+OpenXiangda 应用开发使用普通用户登录 token，不需要 AK/SK；外部后端集成使用 open-api skill 与 AK/SK。
 表单页、流程表单页和代码页的主链路是 sy-lowcode-app-workspace + openxiangda workspace publish。
 新 React SPA 公开访问使用 public-access 命令和 src/resources/public-access；settings public-access 仅用于旧表单公开设置兼容/修复。
 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 校验、再构建并上传为快照。`);
@@ -211,6 +221,7 @@ const SUBCOMMAND_BOOLEAN_FLAGS = new Set([
   '--release',
   '--resources',
   '--skip-resources',
+  '--show-secret',
   '--strict',
   '--sdd-bypass',
   '--summary',
@@ -1049,6 +1060,168 @@ async function contract(args) {
   fail('用法: openxiangda contract list|explain <contract-name> [--json]');
 }
 
+async function openApi(args) {
+  const [section, action, ...rest] = args;
+  const { flags, positional } = parseArgs(rest);
+  const usage = [
+    '用法:',
+    '  openxiangda open-api spec tags',
+    '  openxiangda open-api spec list [--tag name] [--search text] [--json]',
+    '  openxiangda open-api spec describe <operationId|path> [--method post] [--json]',
+    '  openxiangda open-api credential list [--profile name] [--json]',
+    '  openxiangda open-api credential get <id> [--profile name] [--show-secret] [--json]',
+    '  openxiangda open-api credential create --name <name> [--description text] [--permissions a,b] --yes [--show-secret] [--json]',
+    '  openxiangda open-api credential update <id> [--name text] [--description text] [--permissions a,b] [--json]',
+    '  openxiangda open-api credential rotate-secret <id> --yes --show-secret [--json]',
+  ].join('\n');
+  if (
+    !section ||
+    section === 'help' ||
+    section === '--help' ||
+    section === '-h' ||
+    !action ||
+    action === 'help' ||
+    action === '--help' ||
+    action === '-h' ||
+    flags.help ||
+    flags.h
+  ) {
+    print(usage);
+    return;
+  }
+
+  if (section === 'spec') {
+    const document = loadOpenApiDocument();
+    if (action === 'tags') {
+      const tags = listOpenApiTags(document);
+      if (flags.json) return writeJson({ tags });
+      print(tags.map(item => `${item.name}\t${item.description}`).join('\n'));
+      return;
+    }
+    if (action === 'list') {
+      const operations = listOpenApiOperations(document, {
+        tag: flags.tag,
+        search: flags.search,
+      });
+      if (flags.json) return writeJson({ operations, total: operations.length });
+      print(
+        operations
+          .map(item => `${item.method}\t${item.path}\t${item.summary}\t${item.operationId}`)
+          .join('\n')
+      );
+      return;
+    }
+    if (action === 'describe') {
+      const selector = positional[0];
+      if (!selector) fail('open-api spec describe 缺少 operationId 或 path');
+      const operation = describeOpenApiOperation(document, selector, flags.method);
+      if (flags.json) return writeJson(operation);
+      print(
+        [
+          `${operation.method} ${operation.path}`,
+          `${operation.summary} (${operation.operationId})`,
+          '',
+          operation.description,
+          '',
+          `Authentication: ${operation.authenticated ? Object.keys(operation.securitySchemes).join(', ') : 'none'}`,
+          '',
+          'Parameters:',
+          JSON.stringify(operation.parameters, null, 2),
+          '',
+          'Request body:',
+          JSON.stringify(operation.requestBody, null, 2),
+          '',
+          'Responses:',
+          JSON.stringify(operation.responses, null, 2),
+          '',
+          'Source:',
+          JSON.stringify(operation.source, null, 2),
+        ].join('\n')
+      );
+      return;
+    }
+    fail(usage);
+  }
+
+  if (section === 'credential') {
+    const config = loadConfig();
+    const profileName = flags.profile || config.currentProfile;
+    const id = positional[0];
+    try {
+      let data;
+      if (action === 'list') {
+        data = await requestWithAuth(config, profileName, '/api/dingtalk-apps');
+      } else if (action === 'get') {
+        if (!id) fail('open-api credential get 缺少凭证 id');
+        data = await requestWithAuth(
+          config,
+          profileName,
+          `/api/dingtalk-apps/${encodeURIComponent(id)}`
+        );
+      } else if (action === 'create') {
+        if (!flags.yes) {
+          fail('创建开放 API 凭证会写入平台。用户确认后请追加 --yes。');
+        }
+        if (!flags.name) fail('open-api credential create 缺少 --name');
+        data = await requestWithAuth(config, profileName, '/api/dingtalk-apps', {
+          method: 'POST',
+          body: compactObject({
+            name: flags.name,
+            description: flags.description,
+            permissions:
+              flags.permissions === undefined ? undefined : splitList(flags.permissions),
+          }),
+        });
+      } else if (action === 'update') {
+        if (!id) fail('open-api credential update 缺少凭证 id');
+        const body = compactObject({
+          name: flags.name,
+          description: flags.description,
+          permissions:
+            flags.permissions === undefined ? undefined : splitList(flags.permissions),
+        });
+        if (Object.keys(body).length === 0) {
+          fail('open-api credential update 至少需要 --name、--description 或 --permissions');
+        }
+        data = await requestWithAuth(
+          config,
+          profileName,
+          `/api/dingtalk-apps/${encodeURIComponent(id)}`,
+          { method: 'POST', body }
+        );
+      } else if (action === 'rotate-secret') {
+        if (!id) fail('open-api credential rotate-secret 缺少凭证 id');
+        if (!flags.yes || !flags['show-secret']) {
+          fail('重置 SK 需要显式确认并安全接收新密钥，请同时追加 --yes --show-secret。');
+        }
+        data = await requestWithAuth(
+          config,
+          profileName,
+          `/api/dingtalk-apps/${encodeURIComponent(id)}/regenerate-secret`,
+          { method: 'POST', body: {} }
+        );
+      } else {
+        fail(usage);
+      }
+      const output = redactOpenApiSecret(data, Boolean(flags['show-secret']));
+      return outputDirectResult(output, flags);
+    } catch (error) {
+      if (/平台管理员|无权限|forbidden/i.test(String(error.message || ''))) {
+        fail(`开放 API 凭证管理需要平台管理员权限: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+
+  fail(usage);
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== undefined)
+  );
+}
+
 async function platform(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
@@ -5415,6 +5588,8 @@ async function commands(args) {
       'auth status|refresh|logout',
       'doctor [--profile name] [--app-type APP_XXX] [--release]',
       'contract list|explain <contract-name>',
+      'open-api spec tags|list|describe [operationId|path]',
+      'open-api credential list|get|create|update|rotate-secret [id]',
       'design gates|template|review [--topic code]',
       'sdd init|migrate|propose|approve|status|context|verify|sync|archive',
       'env',

package/lib/open-api.js

@@ -0,0 +1,256 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const OPEN_API_SPEC_FILE = path.join(
+  __dirname,
+  '..',
+  'openxiangda-skills',
+  'skills',
+  'openxiangda-open-api',
+  'references',
+  'dingtalk-api.openapi.json'
+);
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
+
+function loadOpenApiDocument(file = OPEN_API_SPEC_FILE) {
+  const document = JSON.parse(fs.readFileSync(file, 'utf8'));
+  validateOpenApiDocument(document);
+  return document;
+}
+
+function validateOpenApiDocument(document) {
+  if (!document || typeof document !== 'object') {
+    throw new Error('DingTalk OpenAPI document must be a JSON object');
+  }
+  if (document.openapi !== '3.0.1') {
+    throw new Error(`Unsupported DingTalk OpenAPI version: ${document.openapi || 'missing'}`);
+  }
+  const operations = collectOperations(document);
+  if (operations.length === 0) {
+    throw new Error('DingTalk OpenAPI document contains no operations');
+  }
+  const securitySchemes = document.components?.securitySchemes || {};
+  for (const item of operations) {
+    const operation = item.operation;
+    for (const field of ['operationId', 'summary', 'description']) {
+      if (!String(operation[field] || '').trim()) {
+        throw new Error(`${item.method.toUpperCase()} ${item.path} is missing ${field}`);
+      }
+    }
+    if (!Array.isArray(operation.tags) || operation.tags.length === 0) {
+      throw new Error(`${item.method.toUpperCase()} ${item.path} is missing tags`);
+    }
+    if (!operation.responses || Object.keys(operation.responses).length === 0) {
+      throw new Error(`${item.method.toUpperCase()} ${item.path} is missing responses`);
+    }
+    for (const requirement of operation.security || []) {
+      for (const name of Object.keys(requirement)) {
+        if (!securitySchemes[name]) {
+          throw new Error(
+            `${item.method.toUpperCase()} ${item.path} references unknown security scheme ${name}`
+          );
+        }
+      }
+    }
+  }
+  return document;
+}
+
+function collectOperations(document) {
+  const operations = [];
+  for (const [routePath, pathItem] of Object.entries(document.paths || {})) {
+    for (const [method, operation] of Object.entries(pathItem || {})) {
+      if (!HTTP_METHODS.has(method)) continue;
+      operations.push({
+        method,
+        path: routePath,
+        operation,
+      });
+    }
+  }
+  return operations.sort((left, right) =>
+    `${left.path} ${left.method}`.localeCompare(`${right.path} ${right.method}`)
+  );
+}
+
+function listOpenApiTags(document) {
+  const declared = new Map(
+    (document.tags || []).map(item => [item.name, item.description || ''])
+  );
+  for (const { operation } of collectOperations(document)) {
+    for (const tag of operation.tags || []) {
+      if (!declared.has(tag)) declared.set(tag, '');
+    }
+  }
+  return [...declared.entries()]
+    .map(([name, description]) => ({ name, description }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function listOpenApiOperations(document, options = {}) {
+  const tag = String(options.tag || '').trim().toLowerCase();
+  const search = String(options.search || '').trim().toLowerCase();
+  return collectOperations(document)
+    .filter(({ operation }) => {
+      if (!tag) return true;
+      return (operation.tags || []).some(item => String(item).toLowerCase() === tag);
+    })
+    .filter(item => {
+      if (!search) return true;
+      return [
+        item.method,
+        item.path,
+        item.operation.operationId,
+        item.operation.summary,
+        item.operation.description,
+        ...(item.operation.tags || []),
+      ]
+        .join('\n')
+        .toLowerCase()
+        .includes(search);
+    })
+    .map(item => ({
+      method: item.method.toUpperCase(),
+      path: item.path,
+      operationId: item.operation.operationId,
+      summary: item.operation.summary,
+      tags: item.operation.tags || [],
+      authenticated: (item.operation.security || []).length > 0,
+    }));
+}
+
+function describeOpenApiOperation(document, selector, method) {
+  const normalizedSelector = String(selector || '').trim();
+  if (!normalizedSelector) {
+    throw new Error('Missing operationId or path');
+  }
+  const normalizedMethod = String(method || '').trim().toLowerCase();
+  let matches = collectOperations(document).filter(item =>
+    item.operation.operationId === normalizedSelector || item.path === normalizedSelector
+  );
+  if (normalizedMethod) {
+    matches = matches.filter(item => item.method === normalizedMethod);
+  }
+  if (matches.length === 0) {
+    throw new Error(`Open API operation not found: ${normalizedSelector}`);
+  }
+  if (matches.length > 1) {
+    const methods = matches.map(item => item.method.toUpperCase()).join(', ');
+    throw new Error(
+      `Path ${normalizedSelector} has multiple methods (${methods}); pass --method`
+    );
+  }
+
+  const { path: routePath, method: operationMethod, operation } = matches[0];
+  const security = operation.security || [];
+  const securitySchemeNames = [
+    ...new Set(security.flatMap(requirement => Object.keys(requirement))),
+  ];
+  const securitySchemes = Object.fromEntries(
+    securitySchemeNames.map(name => [
+      name,
+      resolveNode(document.components?.securitySchemes?.[name], document),
+    ])
+  );
+  return {
+    method: operationMethod.toUpperCase(),
+    path: routePath,
+    operationId: operation.operationId,
+    summary: operation.summary,
+    description: operation.description,
+    tags: operation.tags || [],
+    authenticated: security.length > 0,
+    security,
+    securitySchemes,
+    parameters: resolveNode(operation.parameters || [], document),
+    requestBody: resolveNode(operation.requestBody || null, document),
+    responses: resolveNode(operation.responses || {}, document),
+    source: operation['x-code-source'] || null,
+  };
+}
+
+function resolveNode(value, document, seen = new Set()) {
+  if (Array.isArray(value)) {
+    return value.map(item => resolveNode(item, document, seen));
+  }
+  if (!value || typeof value !== 'object') return value;
+
+  if (value.$ref) {
+    const reference = value.$ref;
+    if (seen.has(reference)) return { $ref: reference };
+    const target = resolveJsonPointer(document, reference);
+    if (!target) return { ...value };
+    const nextSeen = new Set(seen);
+    nextSeen.add(reference);
+    return resolveNode(target, document, nextSeen);
+  }
+
+  const resolved = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === 'allOf') continue;
+    resolved[key] = resolveNode(item, document, seen);
+  }
+  if (!Array.isArray(value.allOf)) return resolved;
+
+  const merged = {};
+  for (const item of value.allOf) {
+    mergeSchema(merged, resolveNode(item, document, seen));
+  }
+  mergeSchema(merged, resolved);
+  return merged;
+}
+
+function resolveJsonPointer(document, reference) {
+  if (!String(reference).startsWith('#/')) return null;
+  return reference
+    .slice(2)
+    .split('/')
+    .map(part => part.replace(/~1/g, '/').replace(/~0/g, '~'))
+    .reduce((current, part) => current?.[part], document);
+}
+
+function mergeSchema(target, source) {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) return target;
+  for (const [key, value] of Object.entries(source)) {
+    if (key === 'properties' && value && typeof value === 'object') {
+      target.properties = { ...(target.properties || {}), ...value };
+    } else if (key === 'required' && Array.isArray(value)) {
+      target.required = [...new Set([...(target.required || []), ...value])];
+    } else {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+function redactOpenApiSecret(value, showSecret = false) {
+  if (showSecret || value === null || value === undefined) return value;
+  if (Array.isArray(value)) {
+    return value.map(item => redactOpenApiSecret(item, false));
+  }
+  if (typeof value !== 'object') return value;
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    result[key] = /^(appSecret|secret)$/i.test(key)
+      ? '***redacted***'
+      : redactOpenApiSecret(item, false);
+  }
+  return result;
+}
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+module.exports = {
+  OPEN_API_SPEC_FILE,
+  collectOperations,
+  describeOpenApiOperation,
+  listOpenApiOperations,
+  listOpenApiTags,
+  loadOpenApiDocument,
+  redactOpenApiSecret,
+  sha256File,
+  validateOpenApiDocument,
+};

package/lib/skills.js

@@ -73,6 +73,15 @@ const SKILL_SPECS = [
     sourceRelativePath: 'openxiangda-skills/skills/openxiangda-inspect',
     type: 'subskill',
   },
+  {
+    name: 'openxiangda-open-api',
+    displayName: 'OpenXiangda Open API',
+    shortDescription: '外部后端开放接口契约与 AK/SK 管理。',
+    defaultPrompt:
+      'Use $openxiangda-open-api to implement a secure backend integration with the private low-code platform Open API.',
+    sourceRelativePath: 'openxiangda-skills/skills/openxiangda-open-api',
+    type: 'subskill',
+  },
 ];
 
 function getDefaultCodexSkillsDir(env = process.env) {
@@ -323,6 +332,10 @@ function copyRootSkill(stagingDir) {
 function copySubskill(spec, stagingDir) {
   const sourceDir = path.join(ROOT_DIR, spec.sourceRelativePath);
   fs.mkdirSync(stagingDir, { recursive: true });
+  fs.cpSync(sourceDir, stagingDir, {
+    recursive: true,
+    dereference: false,
+  });
   const skillMarkdown = fs
     .readFileSync(path.join(sourceDir, 'SKILL.md'), 'utf8')
     .replace(/\.\.\/\.\.\/references\//g, 'references/');
@@ -337,9 +350,10 @@ function writeAgentMetadata(spec, skillDir) {
   const agentsDir = path.join(skillDir, 'agents');
   fs.mkdirSync(agentsDir, { recursive: true });
   const defaultPrompt =
-    spec.name === 'openxiangda'
+    spec.defaultPrompt ||
+    (spec.name === 'openxiangda'
       ? '使用 $openxiangda 处理私有化低代码平台的登录、发布和诊断任务。'
-      : `使用 $${spec.name} 处理对应的 OpenXiangda 低代码平台任务。`;
+      : `使用 $${spec.name} 处理对应的 OpenXiangda 低代码平台任务。`);
   const content = [
     'interface:',
     `  display_name: ${yamlQuote(spec.displayName)}`,

package/openxiangda-skills/SKILL.md

@@ -5,7 +5,7 @@ description: "Use OpenXiangda for any private low-code platform or sy-lowcode-ap
 
 # OpenXiangda
 
-OpenXiangda is a lightweight bridge between an AI coding tool and a private low-code platform. No AK/SK. The user provides a platform domain, logs in as a normal platform user, and the CLI calls `/openxiangda-api/v1` with that user's token.
+OpenXiangda is a lightweight bridge between an AI coding tool and a private low-code platform. Normal app development uses a platform domain, a normal-user login, and `/openxiangda-api/v1`; it does not use AK/SK. External backend and third-party integrations are a separate track that uses the `openxiangda-open-api` skill and `/dingtalk-api/v1.0`.
 
 OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` publishes form/page bundles with `openxiangda workspace publish`. Phase 6 `react-spa` workspaces are standard React/Vite apps: publish resources with `openxiangda resource publish`, then publish the frontend dist with `openxiangda runtime deploy`. Do not send React SPA routes through old `isRenderNav`, app-shell, or workbench page parameters.
 
@@ -37,6 +37,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 | 登录 / 切换平台 / profile / token / whoami               | `openxiangda-core`                                                                         | `openxiangda env --profile <name>` / `openxiangda auth status`                                                                                           |
 | 多表只读联表 / 固定口径统计 / 强实时复杂查询 / 看板指标  | `openxiangda-form` (data view)                                                             | declare `src/resources/data-views/<code>.json` with `storageMode` → `resource publish`                                                                   |
 | 调外部 / 第三方 API / 钉钉 / 自建系统                    | `openxiangda-page` (connector)                                                             | declare `src/resources/connectors/<code>.json` → `sdk.connector.invoke`                                                                                  |
+| 外部后端 / 三方系统调用享搭 / AK/SK / 开放接口          | `openxiangda-open-api`                                                                     | `openxiangda open-api spec list --search <keyword> --json` → describe the selected operation                                                             |
 
 ### Hard rules — always
 
@@ -68,7 +69,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 ### Hard rules — never
 
 - ❌ `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*` directly — they are workspace internals and miss the profile token injection. Use `openxiangda workspace publish ...` instead.
-- ❌ Asking the user for `AK` / `SK` / `appKey` / `appSecret`. The whole flow is normal-user token only.
+- ❌ Asking the user to paste `AK` / `SK` / `appKey` / `appSecret` into chat. Normal OpenXiangda flows use the user token; authorized external backend work uses `open-api credential` for a direct secure handoff.
 - ❌ Searching the platform for a similar app name when `.openxiangda/state.json` has no binding — create a new app with `workspace init --app-name`.
 - ❌ Using `openxiangda form create` / `form publish` / `page publish` as the normal page generation path. They are low-level repair commands.
 - ❌ Implementing an architecture-class request before the user confirms the design. This includes creating files, mutating platform resources, publishing runtime, sending notifications, or calling live write/delete endpoints.
@@ -195,13 +196,16 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - `skills/openxiangda-workflow-automation/SKILL.md`: workflow v3 definitions, automation triggers, publishing, enabling, and profile-isolated IDs.
 - `skills/openxiangda-permission-settings/SKILL.md`: app roles, page permission groups, form permission groups, and settings-oriented guidance.
 - `skills/openxiangda-inspect/SKILL.md`: read-only app and resource diagnosis using snapshots and profile-local resource IDs.
+- `skills/openxiangda-open-api/SKILL.md`: external backend integration through the complete `/dingtalk-api/v1.0` contract and one-time API credential management.
 
 ## API Namespace
 
-OpenXiangda uses `/openxiangda-api/v1`. Old `/dingtalk-api/v1.0` APIs are compatibility only and should not be used for new OpenXiangda workflows.
+OpenXiangda CLI and low-code app development use `/openxiangda-api/v1`. External backend and third-party integrations use `/dingtalk-api/v1.0` through `openxiangda-open-api`; do not switch normal workspace workflows to AK/SK.
 
 On private deployments, the public API URL is normally `<platform-domain>/service/openxiangda-api/v1`.
 
+For external backend integrations, the public base is normally `<platform-domain>/service/dingtalk-api/v1.0`. Use `openxiangda open-api spec describe` for exact request and response fields.
+
 For endpoint details, read `references/openxiangda-api.md` only when you need request or response fields.
 
 ## References Index

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

@@ -2,7 +2,7 @@
 
 Base path: `/openxiangda-api/v1`
 
-OpenXiangda APIs use `/openxiangda-api/v1`. Legacy `/dingtalk-api/v1.0` exists only for compatibility and should not be used for new AI workflow or automation work.
+OpenXiangda CLI and low-code app workflows use `/openxiangda-api/v1`. External backend and third-party integrations use the separate `openxiangda-open-api` skill and `/dingtalk-api/v1.0`; do not switch workspace publishing, page, form, workflow, or automation work to AK/SK.
 
 Standard private deployment public paths:
 
@@ -16,7 +16,7 @@ Authentication:
 
 - Normal CLI calls use `Authorization: Bearer <accessToken>`.
 - Refresh calls use the `refreshToken` request body.
-- Legacy `/dingtalk-api/v1.0` AK/SK authentication is not part of OpenXiangda.
+- `/dingtalk-api/v1.0` AK/SK authentication is not part of this user-token API contract. Read the `openxiangda-open-api` skill for external backend integration.
 
 ## Auth
 

package/openxiangda-skills/references/pages/page-sdk.md

@@ -151,7 +151,7 @@ const api = usePageFormRuntimeApi()
 </FormProvider>
 ```
 
-Use `createPageFormRuntimeApi(sdk)` when hooks are unavailable. Both APIs preserve JSON envelopes and route `responseType: "blob"` through `sdk.transport.download`. Never forward every form request to `sdk.request`; that method is the JSON channel and cannot return the Blob required by Office, image, audio, and video preview parsers.
+Use `createPageFormRuntimeApi(sdk)` when hooks are unavailable. Both APIs preserve JSON envelopes, route `responseType: "blob"` through `sdk.transport.download`, and normalize ticket content URLs such as `/file/download-by-ticket/*` with the current PageSdk `servicePrefix`. They do not rewrite `/view/*` page URLs or absolute storage URLs. Never forward every form request to `sdk.request`, and never prepend `/service` in application code.
 
 Shareable file preview ticket:
 

package/openxiangda-skills/references/troubleshooting.md

@@ -32,6 +32,18 @@
 
 ---
 
+## 问题：附件下载打开站点根 `/file/` 并返回 404
+
+**症状**：附件下载 ticket 创建成功，但浏览器打开 `https://host/file/...`，实际平台文件接口位于 `https://host/service/file/...`。
+
+**原因**：应用手写了 PageSdk 到 `FormProvider` 的不完整适配，或使用了未归一化的 ticket payload，绕过了当前 runtime 的 `servicePrefix`。
+
+**解决方案**：升级 OpenXiangda，并让 `FormProvider.config.api` 来自 `usePageFormRuntimeApi()` 或 `createPageFormRuntimeApi(sdk)`。SDK 会把 ticket payload 中的 `/file/*` 内容地址补成当前 `servicePrefix`，同时保留 `/view/*` 页面地址和绝对 OSS URL。业务代码不要直接 `window.open(ticket.downloadUrl)` 后再自行猜测前缀。
+
+**验证方式**：点击下载后地址应为 `/service/file/download-by-ticket/:ticket` 或服务端返回的绝对存储 URL，不应是站点根 `/file/*`。
+
+---
+
 ## 问题：antd/antd-mobile 弹层样式丢失
 
 **症状**：Select / Dropdown / Popup / Modal 等组件的弹出层没有样式，直接跑到屏幕外，或呈现为无样式的裸 HTML。