openxiangda 1.0.36 → 1.0.37

package/README.md

@@ -79,6 +79,16 @@ Codex skills are installed separately from login/profile state. Run `openxiangda
 
 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.
 
+For existing app workspaces created before AGENTS.md / `.qoder/rules/` / `.cursor/rules/` / `scripts/guard-publish.mjs` / `package.json` `_guard:publish` were added, run:
+
+```bash
+openxiangda skill bootstrap                 # current dir, dry-run by default? no — write
+openxiangda skill bootstrap --dry-run --json # preview
+openxiangda skill bootstrap --force          # overwrite drifted local copies
+```
+
+It copies the AI-guidance bundle (AGENTS.md, Qoder/Cursor always-on + glob rules, the publish guard script) and patches `package.json` with the `_guard:publish` script plus `prepublish:all` / `prepublish:oss` / `preregister` / `preregister-bundle` / `prepublish:changed` / `preopenxiangda:publish` hooks so that direct `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` calls fail-fast unless invoked through `openxiangda workspace publish ...`.
+
 Create a new publishable app workspace with `openxiangda workspace init <dir>`. The command writes a minimal `sy-lowcode-app-workspace` template with React, Ant Design, the single `openxiangda` package, and the required `publish:all` / `openxiangda:publish` scripts. Use `--install` to run `pnpm install` immediately, or run it manually after creation.
 
 New OpenXiangda code pages and form custom pages publish with `cssIsolation: "none"` by default, so Tailwind utilities and normal Ant Design styles apply without a `.sy-app-workspace` prefix. Explicit `namespace` and `shadow` settings are kept only for legacy compatibility.

package/lib/cli.js

@@ -20,6 +20,7 @@ const {
 const { requestJson } = require('./http');
 const { getSkillStatusReport, installSkills } = require('./skills');
 const { assertCanInitializeWorkspace, initWorkspace } = require('./workspace-init');
+const { bootstrapWorkspace } = require('./workspace-bootstrap');
 const {
   fail,
   maskText,
@@ -116,6 +117,7 @@ Usage:
   openxiangda feedback preview|submit --summary <text> [--type bug] [--severity medium] [--profile name] [--yes]
   openxiangda skill install [--agent codex|claude|qoder|dual] [--dest <skills-dir>] [--force] [--dry-run] [--json]
   openxiangda skill status [--agent codex|claude|qoder|dual] [--dest <skills-dir>] [--json]
+  openxiangda skill bootstrap [<dir>] [--force] [--dry-run] [--json]
 
 OpenXiangda 使用普通用户登录 token，不需要 AK/SK。
 表单页、流程表单页和代码页的主链路是 sy-lowcode-app-workspace + openxiangda workspace publish。
@@ -2681,7 +2683,7 @@ async function commands(args) {
       'resource validate|plan|publish|pull',
       'inspect app|form|workflow|automation|permissions',
       'feedback preview|submit',
-      'skill install|status',
+      'skill install|status|bootstrap',
     ],
   };
   if (flags.json) return writeJson(manifest);
@@ -2711,7 +2713,7 @@ function printWorkspaceInitReport(result) {
 
 async function skill(args) {
   const [subcommand, ...rest] = args;
-  const { flags } = parseArgs(rest);
+  const { flags, positional } = parseArgs(rest);
   const options = {
     agent: flags.agent || 'codex',
     dest: flags.dest,
@@ -2733,7 +2735,18 @@ async function skill(args) {
     return;
   }
 
-  fail('用法: openxiangda skill install|status [--agent codex|claude|qoder|dual] [--dest <skills-dir>]');
+  if (subcommand === 'bootstrap') {
+    const result = bootstrapWorkspace({
+      dir: positional[0],
+      force: Boolean(flags.force),
+      dryRun: Boolean(flags['dry-run']),
+    });
+    if (flags.json) return writeJson(result);
+    printSkillBootstrapReport(result);
+    return;
+  }
+
+  fail('用法: openxiangda skill install|status [--agent codex|claude|qoder|dual] [--dest <skills-dir>]\n      openxiangda skill bootstrap [<dir>] [--force] [--dry-run] [--json]');
 }
 
 function printSkillInstallReport(result) {
@@ -2792,6 +2805,33 @@ function printSkillStatusReport(result) {
   }
 }
 
+function printSkillBootstrapReport(result) {
+  const lines = [
+    `OpenXiangda skill bootstrap${result.dryRun ? ' (dry-run)' : ''}`,
+    `Workspace: ${result.targetDir}`,
+  ];
+  for (const file of result.files) {
+    const reason = file.reason ? ` — ${file.reason}` : '';
+    lines.push(`- ${file.path}: ${file.action}${reason}`);
+  }
+  const pkg = result.packageJson;
+  const pkgReason = pkg.reason ? ` — ${pkg.reason}` : '';
+  lines.push(`- ${pkg.path}: ${pkg.action}${pkgReason}`);
+  if (pkg.added && pkg.added.length > 0) {
+    lines.push(`  + scripts: ${pkg.added.join(', ')}`);
+  }
+  if (pkg.changed && pkg.changed.length > 0) {
+    lines.push(`  ~ scripts: ${pkg.changed.join(', ')}`);
+  }
+  lines.push(`Summary: ${result.summary}`);
+  if (result.dryRun) {
+    lines.push('dry-run completed; no files were changed');
+  } else {
+    lines.push('Done. 重启 Qoder / Cursor / Claude / Codex 以加载新的 always-on rules。');
+  }
+  print(lines.join('\n'));
+}
+
 function getWorkspaceTarget(config, profileName, flags = {}) {
   const resolved = getProfile(config, profileName);
   const state = loadProjectState();

package/lib/workspace-bootstrap.js

@@ -0,0 +1,238 @@
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.join(__dirname, '..');
+const TEMPLATE_DIR = path.join(ROOT_DIR, 'templates', 'sy-lowcode-app-workspace');
+
+// AI 引导/守卫"四件套 + glob rules"清单。
+// 这些路径是相对于 workspace 根，文件源都来自 templates/sy-lowcode-app-workspace。
+const BOOTSTRAP_FILES = [
+  'AGENTS.md',
+  'scripts/guard-publish.mjs',
+  '.qoder/rules/openxiangda.md',
+  '.qoder/rules/openxiangda-form.md',
+  '.qoder/rules/openxiangda-page.md',
+  '.qoder/rules/openxiangda-workflow-automation.md',
+  '.qoder/rules/openxiangda-resources.md',
+  '.cursor/rules/openxiangda.mdc',
+  '.cursor/rules/openxiangda-form.mdc',
+  '.cursor/rules/openxiangda-page.mdc',
+  '.cursor/rules/openxiangda-workflow-automation.mdc',
+  '.cursor/rules/openxiangda-resources.mdc',
+];
+
+// package.json 必须存在的守卫脚本与 prefoo hook。
+const PACKAGE_JSON_GUARD_SCRIPTS = {
+  '_guard:publish': 'node scripts/guard-publish.mjs',
+  'prepublish:all': 'pnpm _guard:publish',
+  'prepublish:oss': 'pnpm _guard:publish',
+  'preregister': 'pnpm _guard:publish',
+  'preregister-bundle': 'pnpm _guard:publish',
+  'prepublish:changed': 'pnpm _guard:publish',
+  'preopenxiangda:publish': 'pnpm _guard:publish',
+};
+
+function bootstrapWorkspace(options = {}) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options.dryRun);
+
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    throw new Error(`workspace 模板不存在: ${TEMPLATE_DIR}`);
+  }
+  if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+    throw new Error(`目标目录不存在或不是目录: ${targetDir}`);
+  }
+
+  const fileOps = BOOTSTRAP_FILES.map(rel => planFileOp(rel, targetDir, force));
+  const packageJsonOp = planPackageJsonOp(targetDir, force);
+
+  if (!dryRun) {
+    for (const op of fileOps) {
+      if (op.action === 'install' || op.action === 'overwrite') {
+        ensureDir(path.dirname(op.targetPath));
+        fs.copyFileSync(op.sourcePath, op.targetPath);
+      }
+    }
+    if (packageJsonOp.action === 'patch' || packageJsonOp.action === 'create-scripts') {
+      writePackageJson(packageJsonOp.targetPath, packageJsonOp.nextContent);
+    }
+  }
+
+  return {
+    targetDir,
+    dryRun,
+    force,
+    files: fileOps.map(op => ({
+      path: op.relativePath,
+      action: op.action,
+      reason: op.reason || null,
+    })),
+    packageJson: {
+      path: packageJsonOp.relativePath,
+      action: packageJsonOp.action,
+      added: packageJsonOp.added || [],
+      changed: packageJsonOp.changed || [],
+      reason: packageJsonOp.reason || null,
+    },
+    summary: buildSummary(fileOps, packageJsonOp),
+  };
+}
+
+function planFileOp(relativePath, targetDir, force) {
+  const sourcePath = path.join(TEMPLATE_DIR, relativePath);
+  const targetPath = path.join(targetDir, relativePath);
+  if (!fs.existsSync(sourcePath)) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'missing-source',
+      reason: '模板缺失，请升级 openxiangda',
+    };
+  }
+  const sourceContent = fs.readFileSync(sourcePath);
+  if (!fs.existsSync(targetPath)) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'install',
+    };
+  }
+  const targetContent = fs.readFileSync(targetPath);
+  if (sourceContent.equals(targetContent)) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'unchanged',
+    };
+  }
+  if (force) {
+    return {
+      relativePath,
+      sourcePath,
+      targetPath,
+      action: 'overwrite',
+    };
+  }
+  return {
+    relativePath,
+    sourcePath,
+    targetPath,
+    action: 'skip',
+    reason: '本地版本与模板不同；如需覆盖请传 --force',
+  };
+}
+
+function planPackageJsonOp(targetDir, force) {
+  const targetPath = path.join(targetDir, 'package.json');
+  const relativePath = 'package.json';
+  if (!fs.existsSync(targetPath)) {
+    return {
+      targetPath,
+      relativePath,
+      action: 'absent',
+      reason: 'package.json 不存在；不是 npm 工作区',
+    };
+  }
+  const raw = fs.readFileSync(targetPath, 'utf8');
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch (error) {
+    return {
+      targetPath,
+      relativePath,
+      action: 'invalid-json',
+      reason: `package.json 解析失败: ${error.message}`,
+    };
+  }
+  const scripts = pkg.scripts ? { ...pkg.scripts } : null;
+  if (!scripts) {
+    const nextPkg = { ...pkg, scripts: { ...PACKAGE_JSON_GUARD_SCRIPTS } };
+    return {
+      targetPath,
+      relativePath,
+      action: 'create-scripts',
+      added: Object.keys(PACKAGE_JSON_GUARD_SCRIPTS),
+      changed: [],
+      nextContent: stringifyPackageJson(raw, nextPkg),
+    };
+  }
+  const added = [];
+  const changed = [];
+  for (const [name, value] of Object.entries(PACKAGE_JSON_GUARD_SCRIPTS)) {
+    if (!(name in scripts)) {
+      scripts[name] = value;
+      added.push(name);
+    } else if (scripts[name] !== value) {
+      if (force) {
+        scripts[name] = value;
+        changed.push(name);
+      } else {
+        changed.push(`${name} (skipped, value differs; pass --force to overwrite)`);
+      }
+    }
+  }
+  if (added.length === 0 && changed.length === 0) {
+    return {
+      targetPath,
+      relativePath,
+      action: 'unchanged',
+      added: [],
+      changed: [],
+    };
+  }
+  const nextPkg = { ...pkg, scripts };
+  return {
+    targetPath,
+    relativePath,
+    action: 'patch',
+    added,
+    changed,
+    nextContent: stringifyPackageJson(raw, nextPkg),
+  };
+}
+
+function stringifyPackageJson(originalRaw, nextPkg) {
+  const indent = detectIndent(originalRaw);
+  const trailingNewline = originalRaw.endsWith('\n') ? '\n' : '';
+  return `${JSON.stringify(nextPkg, null, indent)}${trailingNewline}`;
+}
+
+function detectIndent(raw) {
+  const match = raw.match(/^(\s+)\"/m);
+  if (!match) return 2;
+  if (match[1].includes('\t')) return '\t';
+  return match[1].length;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writePackageJson(targetPath, nextContent) {
+  fs.writeFileSync(targetPath, nextContent);
+}
+
+function buildSummary(fileOps, packageJsonOp) {
+  const counts = { install: 0, overwrite: 0, unchanged: 0, skip: 0 };
+  for (const op of fileOps) {
+    if (counts[op.action] !== undefined) counts[op.action] += 1;
+  }
+  const parts = [];
+  parts.push(`installed=${counts.install}`);
+  parts.push(`overwritten=${counts.overwrite}`);
+  parts.push(`unchanged=${counts.unchanged}`);
+  parts.push(`skipped=${counts.skip}`);
+  parts.push(`package.json=${packageJsonOp.action}`);
+  return parts.join(' ');
+}
+
+module.exports = {
+  BOOTSTRAP_FILES,
+  PACKAGE_JSON_GUARD_SCRIPTS,
+  bootstrapWorkspace,
+};

package/openxiangda-skills/SKILL.md

@@ -1,13 +1,51 @@
 ---
 name: openxiangda
-description: Use OpenXiangda to help AI agents build and publish apps on a private low-code platform through the openxiangda CLI, ordinary user login tokens, platform profiles, workspace initialization, workspace binding, and app snapshots; use when the user mentions OpenXiangda, 湘搭, 私有化低代码平台, sy-lowcode-app-workspace, profile/domain login, or multi-platform publishing.
+description: Use OpenXiangda for ANY work inside a sy-lowcode-app-workspace or any private low-code platform (OpenXiangda / 湘搭 / 私有化低代码) — publishing / 发布 / 上线 / deploying / 部署 / shipping / releasing / 上传 / pushing apps, pages, forms, workflows, automations; creating / scaffolding / 创建 / 搭建 / 新建 apps, code pages, form pages, workflow forms, JS_CODE nodes; editing / 修改 / 编辑 schemas, options, fields, layouts, menus; managing / 管理 roles, page permission groups, form permission groups, form settings, public access, data views, connectors, notifications; diagnosing / 排查 / 诊断 / 看快照 app snapshots, executions, logs, version drift, profile isolation, token / login / profile issues; running the openxiangda CLI or anything that touches `.openxiangda/state.json`, `~/.openxiangda/profiles.json`, `/openxiangda-api/v1`, `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE`, `app-workspace.config.ts`. Trigger when the user mentions OpenXiangda / 湘搭 / 私有化低代码 / 低代码平台 / sy-lowcode-app-workspace, or when the workspace contains `.openxiangda/state.json` or `app-workspace.config.ts`. Always prefer this skill over running `pnpm publish:all`, `pnpm publish:oss`, `pnpm register`, or `lowcode-workspace publish-*` directly.
 ---
 
 # OpenXiangda
 
-OpenXiangda is a lightweight bridge between an AI coding tool and a private low-code platform. It does not ask users for 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. 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.
 
-For page generation, OpenXiangda must use `sy-lowcode-app-workspace`: form pages, workflow form pages, and custom code pages are implemented as workspace source files, built into bundles, uploaded to OSS, and registered through `openxiangda workspace publish`. Do not generate final user-facing pages by relying on the platform's legacy default schema page.
+For any user-facing page (form pages, workflow form pages, custom code pages), OpenXiangda must use `sy-lowcode-app-workspace`: source files in `src/`, built into bundles, uploaded to OSS, and registered through `openxiangda workspace publish`. Do not rely on the platform's legacy default schema page.
+
+## TL;DR — Decision Card
+
+**If the workspace has `.openxiangda/state.json` or `app-workspace.config.ts`, you are in an OpenXiangda app workspace. Read this card before any tool call.**
+
+### Routing — user intent → skill / command
+
+| User says (zh / en) | Skill | First command |
+|---|---|---|
+| 发布 / 上线 / 部署 / publish / deploy / ship / release | `openxiangda-core` | `openxiangda workspace publish --profile <name> --changed --dry-run` |
+| 只发布改动 / 增量 / 单页 / 单表 | `openxiangda-core` | `... --changed` / `--page <code>` / `--form <code>` / `--only pages/a,forms/b` |
+| 创建应用 / 新建 app / scaffold / 初始化工作区 | `openxiangda-app` | `openxiangda workspace init <dir> --profile <name> --app-name "..."` |
+| 绑定已有应用 / bind existing app | `openxiangda-app` | `openxiangda workspace bind --profile <name> --app-type APP_XXX` |
+| 创建 / 修改表单字段 / 表单页 / schema | `openxiangda-form` | edit `src/forms/<code>/{schema.ts,page.tsx}` → `workspace publish --form <code>` |
+| 创建 / 修改自定义代码页 / portal / dashboard | `openxiangda-page` | edit `src/pages/<code>/` → `workspace publish --page <code>` |
+| 审批流程 / workflow / 流程节点 / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow validate / create / publish` |
+| 自动化 / 定时任务 / 提交触发 / cron | `openxiangda-workflow-automation` | `openxiangda automation validate / create / publish / enable` |
+| 角色 / 权限组 / 字段权限 / 数据范围 / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot <APP_XXX> --profile <name> --json` |
+| 登录 / 切换平台 / profile / token / whoami | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
+| 多表只读联表查询 / 报表数据源 | `openxiangda-form` (data view) | declare `src/resources/data-views/<code>.json` → `resource publish` |
+| 调外部 / 第三方 API / 钉钉 / 自建系统 | `openxiangda-page` (connector) | declare `src/resources/connectors/<code>.json` → `sdk.connector.invoke` |
+
+### Hard rules — always
+
+- ✅ Publish through `openxiangda workspace publish --profile <name>` (with `--changed` / `--page` / `--form` / `--only` for routine edits).
+- ✅ User token lives in `~/.openxiangda/profiles.json`; project state in `.openxiangda/state.json` (IDs only).
+- ✅ Each profile (dev / prod / ...) has its own `appType` and resource IDs; never copy a `formUuid` / `pageId` / `workflowId` / `automationId` across profiles.
+- ✅ Run `openxiangda update check --json` at the start of substantial work; if `updateAvailable`, run `openxiangda update install` and `openxiangda skill install --force`.
+
+### 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.
+- ❌ 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.
+- ❌ Running a full publish after editing one file. Default to `--changed --dry-run` → `--changed`, or targeted `--page` / `--form`.
+- ❌ Storing tokens, AK, SK, or third-party API secrets in project files. Shared env (`APP_OSS_*`, feedback robot) goes to `~/.openxiangda/.env`.
 
 ## Platform Routing
 
@@ -128,6 +166,7 @@ Core CLI / state:
 - `references/openxiangda-api.md` — `/openxiangda-api/v1` request and response fields.
 - `references/workspace-state.md` — `.openxiangda/state.json` shape and profile isolation rules.
 - `references/connector-resources.md` — `src/resources` manifests, connector schema, and SDK connector calls.
+- `references/resource-manifest-cheatsheet.md` — 复制即用的 connector / data-view / notification / workflow / automation / JS_CODE / role / permission group / settings / menu manifest 骨架与运行时调用示例。在创建任何 `src/resources/` 资源前先看这份。
 - `references/data-views.md` — `src/resources/data-views` materialized view resources, DSL, permissions, refresh, CLI commands, and runtime SDK usage.
 - `references/notifications.md` — `src/resources/notifications`, notification templates/type bindings, and `sdk.notification` / `ctx.notification`.
 - `references/best-practices.md` — initialized examples for modular pages, state lifecycles, role governance, permission isolation, high-performance queries, portal shells, workflow boundaries, and automation patterns.