openxiangda 1.0.92 → 1.0.94

package/lib/design-gates.js

@@ -0,0 +1,449 @@
+const DESIGN_GATE_HARD_RULE =
+  '架构类需求默认只规划、不实现；用户明确确认设计后，才允许改文件、写平台资源或发布。';
+
+const DESIGN_GATE_TOPICS = [
+  {
+    code: 'new-app',
+    title: '新应用 / 大版本应用',
+    triggers: ['新应用', '从零搭建', '门户', '后台系统', '管理系统', '业务系统'],
+    mustAsk: [
+      '目标用户是谁，内部用户和外部用户是否都存在',
+      '核心对象和主流程是什么，哪些对象需要表单、data-view 或 App Function',
+      '是否需要登录注册、公开访问、组织内权限分层',
+      '首屏是工作台、列表、表单、公开页还是仪表盘',
+      '是否需要集成外部系统、通知、流程自动化',
+    ],
+    recommendedDefaults: [
+      'React SPA runtime，路由用 src/resources/routes 声明',
+      '多资源正式开发走 src/resources/** + resource plan/publish',
+      '先输出应用地图、资源清单、权限矩阵、验收用例，再实现',
+    ],
+    antiPatterns: [
+      '先创建页面再回头补权限和数据模型',
+      '把公开访问写成旧版 ?publicAccess=guest 链接',
+      '用页面本地状态模拟应落库的数据',
+    ],
+    acceptance: [
+      '用户确认资源边界和权限策略',
+      'resource validate/plan 无错误',
+      '关键公开、登录、权限拒绝路径都有验收步骤',
+    ],
+  },
+  {
+    code: 'complex-page',
+    title: '复杂页面 / 工作台 / Dashboard',
+    triggers: ['复杂页面', '看板', '工作台', '详情页', '列表页', '移动端', '大屏'],
+    mustAsk: [
+      '页面的主任务、最高频操作、首屏信息密度',
+      '数据来自表单直读、data-view 聚合、App Function 还是连接器',
+      '是否需要编辑、批量操作、导入导出、移动端适配',
+      '各角色能看哪些模块和字段',
+      '加载、空状态、失败重试和越权状态如何呈现',
+    ],
+    recommendedDefaults: [
+      '读取类复杂列表优先用 data-view，跨表逻辑优先 App Function',
+      '管理后台采用紧凑、可扫描布局，避免营销式 hero',
+      '页面路由和菜单分离声明，页面权限单独验收',
+    ],
+    antiPatterns: [
+      '直接在前端拼接跨表权限逻辑',
+      '宽泛授予表单全部数据再靠 UI 隐藏',
+      '移动端只靠桌面页面缩放',
+    ],
+    acceptance: [
+      '不同角色打开页面看到的模块符合权限矩阵',
+      '无数据、错误、越权、加载状态可用',
+      '公开页面不依赖 PageProvider 私有页面上下文',
+    ],
+  },
+  {
+    code: 'auth',
+    title: '登录 / 注册 / 账号绑定',
+    triggers: ['登录', '注册', '手机号', '验证码', '外部账号', '账号绑定', 'SSO'],
+    mustAsk: [
+      '用户来源是平台组织用户、应用自注册用户、外部账号还是混合',
+      '登录方式：密码、手机号验证码、第三方 SSO、免登 ticket',
+      '注册策略：开放注册、邀请码、管理员审核、禁止注册',
+      '账号和组织用户如何匹配：手机号、邮箱、工号、外部 ID',
+      '失败、冻结、解绑、找回密码的处理边界',
+    ],
+    recommendedDefaults: [
+      '用 src/resources/auth/*.json 声明 auth-config',
+      '默认 registration.mode=reject，除非用户确认开放注册',
+      '验证码发送优先由显式 grant 的 App Function/连接器承接',
+    ],
+    antiPatterns: [
+      '前端自行保存明文密码或验证码',
+      '未确认注册策略就开放外部用户写入',
+      '把登录页和公开访问页混为同一权限模型',
+    ],
+    acceptance: [
+      'auth-config methods 与实际登录页参数一致',
+      '未登录访问内部路由会跳登录或拒绝',
+      '注册/绑定失败有明确错误码和文案',
+    ],
+  },
+  {
+    code: 'public-access',
+    title: '公开访问 / 外部人员无需登录',
+    triggers: ['公开访问', '无需登录', '外部人员', '游客', '报名', '公开查询', '分享链接'],
+    mustAsk: [
+      '公开的是哪些 route，是否仅 /view/:appType/public/*',
+      '外部角色有哪些，是否只读、可提交表单、可调用函数或连接器',
+      '是否需要 ticket：一次性、有效期、绑定手机号/邮箱、签名来源',
+      '允许访问哪些 form、data-view、function、connector grant',
+      '是否需要限流、过期时间、审计字段和回收策略',
+    ],
+    recommendedDefaults: [
+      '新 React SPA 仅使用 /view/:appType/public/* + routes + public-access policy',
+      '普通公开页用 scoped public session；敏感页用 ticket 模式',
+      '未显式 grant 的 form/dataView/function/connector 一律拒绝',
+    ],
+    antiPatterns: [
+      '新应用继续使用 ?publicAccess=guest',
+      '给游客账号平台级宽权限',
+      '公开页读取内部 data-view 但没有 public-access grant',
+    ],
+    acceptance: [
+      '无登录直接打开公开 route 成功获得 scoped public session',
+      '允许的 form/data-view/function/connector 可访问',
+      '未 grant 的内部路由和资源返回拒绝，ticket 缺失/过期也拒绝',
+    ],
+  },
+  {
+    code: 'permissions',
+    title: '角色 / 页面权限 / 表单数据范围',
+    triggers: ['权限', '角色', '数据范围', '只看自己', '部门数据', '页面权限', '字段权限'],
+    mustAsk: [
+      '角色清单及成员来源：固定成员、组织部门、外部角色',
+      '页面、菜单、公开路由分别开放给哪些角色',
+      '每个表单的 submit/view/manage 操作和字段权限',
+      '数据范围是全部、本人、部门、自定义条件还是公开 grant',
+      '验收时需要模拟哪些角色和拒绝场景',
+    ],
+    recommendedDefaults: [
+      '角色写 src/resources/roles，页面组写 permissions/page-groups',
+      '表单权限组写 permissions/form-groups，显式声明 dataScope/operations',
+      '公开访问不要复用内部管理员权限组',
+    ],
+    antiPatterns: [
+      '只配菜单可见，不配后端数据权限',
+      '为了省事授予全部数据再在前端过滤',
+      '公开角色和内部角色混用',
+    ],
+    acceptance: [
+      'permission audit 输出无高危缺口',
+      '内部角色允许项可用，未授权项拒绝',
+      '公开访问受 public-access grant 和权限组双重约束',
+    ],
+  },
+  {
+    code: 'workflow-automation',
+    title: '流程 / 自动化 / App Function',
+    triggers: ['流程', '审批', '自动化', '定时', 'App Function', 'JS_CODE', '函数'],
+    mustAsk: [
+      '触发来源：表单提交、状态变化、定时、手动按钮、公开访问',
+      '节点输入输出、失败重试、幂等键和日志保留',
+      '函数需要访问哪些 forms/dataViews/connectors',
+      '是否需要人工审批、通知、回写表单或调用外部系统',
+      '测试用例包含成功、失败、重复触发、越权调用哪些场景',
+    ],
+    recommendedDefaults: [
+      '函数源码放 src/functions/<code>/index.ts 或对应模板约定目录',
+      'definitionJson 中通过 resources 声明依赖，发布时自动绑定',
+      '公开调用函数必须通过 public-access grants.functions 显式开放',
+    ],
+    antiPatterns: [
+      '函数里硬编码 formUuid 或外部密钥',
+      '忽略重复触发导致重复写入或重复通知',
+      '公开页面直接调用未 grant 的内部函数',
+    ],
+    acceptance: [
+      '函数 invoke 测试 envelope 成功，失败码会被识别',
+      '自动化 executions/logs 可追踪',
+      '重复触发不会产生重复副作用',
+    ],
+  },
+  {
+    code: 'connector-notification',
+    title: '连接器 / 通知 / 外部集成',
+    triggers: ['连接器', '第三方接口', '通知', '消息', 'Webhook', '短信', '钉钉'],
+    mustAsk: [
+      '外部接口域名、鉴权方式、超时、重试、脱敏要求',
+      '哪些 connector API 允许内部调用，哪些允许公开访问调用',
+      '通知类型、模板变量、渠道、接收人解析方式',
+      '失败降级：重试、人工补偿、只记日志还是阻断主流程',
+      '是否需要 preview/send/batch-send 的验收样例',
+    ],
+    recommendedDefaults: [
+      '连接器写 src/resources/connectors，通知写 src/resources/notifications',
+      '复杂写入通过 App Function 包装，连接器只做外部通信',
+      '公开访问连接器必须显式 grants.connectors，并限制 API 粒度',
+    ],
+    antiPatterns: [
+      '把密钥写入前端或公开 manifest',
+      '只看 HTTP 200，不检查 JSON envelope 错误码',
+      '通知模板变量和实际 send body 不一致',
+    ],
+    acceptance: [
+      'connector invoke/download-test 请求 body 与 SDK DTO 一致',
+      'notification preview/send 能用真实模板变量',
+      'PUBLIC_GRANT_DENIED 等业务错误码被当作失败',
+    ],
+  },
+  {
+    code: 'resource-maintenance',
+    title: '资源维护 / 小步修复',
+    triggers: ['改一个资源', '补路由', '调整权限', '修复菜单', '删除配置', '同步 manifest'],
+    mustAsk: [
+      '这是临时 live mutation，还是要同步到仓库 manifest',
+      '是否允许删除、覆盖、发送通知等高风险操作',
+      '影响哪些 profile/appType，是否覆盖 workspace binding',
+      '是否需要先 pull/plan/audit 再写入',
+    ],
+    recommendedDefaults: [
+      '多资源正式变更仍走 resource plan/publish',
+      '直接 CLI 写平台资源时加 --write-manifest 防漂移',
+      '删除、发送、覆盖前需要 --force',
+    ],
+    antiPatterns: [
+      '手写未知 HTTP 绕过 CLI',
+      '平台改了但 src/resources 没同步',
+      '不传 profile/app-type 就在错误应用上写资源',
+    ],
+    acceptance: [
+      'dry-run 能展示 method/path/body',
+      '成功写入后 state 和 manifest 同步',
+      'commands --json 可发现相应资源命令',
+    ],
+  },
+];
+
+function selectTopics(topicCode) {
+  if (!topicCode || topicCode === 'all') return DESIGN_GATE_TOPICS;
+  const wanted = new Set(String(topicCode).split(',').map(item => item.trim()).filter(Boolean));
+  return DESIGN_GATE_TOPICS.filter(topic => wanted.has(topic.code));
+}
+
+function getDesignGates(topicCode) {
+  return {
+    hardRule: DESIGN_GATE_HARD_RULE,
+    topics: selectTopics(topicCode),
+  };
+}
+
+function renderDesignGatesText(topicCode) {
+  const gates = getDesignGates(topicCode);
+  const lines = [gates.hardRule, ''];
+  for (const topic of gates.topics) {
+    lines.push(`# ${topic.code}: ${topic.title}`);
+    lines.push(`触发词: ${topic.triggers.join('、')}`);
+    lines.push(`必须提问: ${topic.mustAsk.join('；')}`);
+    lines.push(`推荐默认: ${topic.recommendedDefaults.join('；')}`);
+    lines.push(`反模式: ${topic.antiPatterns.join('；')}`);
+    lines.push(`验收: ${topic.acceptance.join('；')}`);
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd();
+}
+
+function renderDesignTemplate(topicCode) {
+  const gates = getDesignGates(topicCode);
+  const lines = [
+    '# OpenXiangda 架构设计确认稿',
+    '',
+    `> ${gates.hardRule}`,
+    '> 本稿确认前，只允许读取、快照、dry-run、提问和输出设计。',
+    '',
+    '## 1. 需求边界',
+    '- 目标用户：',
+    '- 内部/外部访问：',
+    '- 核心对象与流程：',
+    '- 明确不做：',
+    '',
+    '## 2. 推荐方案',
+    '- Runtime：React SPA',
+    '- 资源发布：src/resources/** + openxiangda resource plan/publish',
+    '- 公开访问：仅使用 /view/:appType/public/* + routes + public-access policy',
+    '',
+    '## 3. 待确认问题',
+  ];
+  for (const topic of gates.topics) {
+    lines.push(`### ${topic.title}`);
+    for (const question of topic.mustAsk) {
+      lines.push(`- [ ] ${question}`);
+    }
+  }
+  lines.push(
+    '',
+    '## 4. 资源设计',
+    '- routes：',
+    '- public-access：',
+    '- auth-config：',
+    '- roles/page-groups/form-groups：',
+    '- forms/data-views/functions/connectors/notifications：',
+    '',
+    '## 5. 验收清单',
+  );
+  for (const topic of gates.topics) {
+    for (const item of topic.acceptance) {
+      lines.push(`- [ ] ${item}`);
+    }
+  }
+  lines.push('', '## 6. 用户确认', '- [ ] 用户确认后再进入实现。');
+  return lines.join('\n');
+}
+
+const RESOURCE_EXPLAINS = {
+  route: {
+    dir: 'src/resources/routes/*.json',
+    minimalManifest: {
+      code: 'public.register',
+      title: '公开报名',
+      kind: 'page',
+      pathPattern: '/view/:appType/public/register',
+      publicAccess: 'guest',
+      publicPolicyCode: 'public_register',
+    },
+    commands: [
+      'openxiangda route upsert --json-file src/resources/routes/public_register.json --dry-run',
+      'openxiangda resource plan',
+      'openxiangda resource publish',
+    ],
+  },
+  'public-access': {
+    dir: 'src/resources/public-access/*.json',
+    minimalManifest: {
+      code: 'public_register',
+      mode: 'guest',
+      routeCode: 'public.register',
+      externalRoleCodes: ['external_visitor'],
+      grants: {
+        forms: ['FORM_OR_FORM_CODE'],
+        dataViews: ['public_lookup'],
+        functions: [],
+        connectors: [],
+      },
+    },
+    commands: [
+      'openxiangda public-access upsert --json-file src/resources/public-access/public_register.json',
+      'openxiangda public-access session-test public_register --path /view/APP_XXX/public/register',
+      'openxiangda public-access grant-check public_register --form-code customer',
+    ],
+  },
+  'auth-config': {
+    dir: 'src/resources/auth/*.json',
+    minimalManifest: {
+      code: 'default',
+      status: 'active',
+      configJson: {
+        methods: [{ type: 'password', enabled: true }],
+        registration: { mode: 'reject' },
+        binding: { mode: 'auto' },
+      },
+    },
+    commands: [
+      'openxiangda auth-config methods',
+      'openxiangda auth-config upsert --json-file src/resources/auth/default.json',
+    ],
+  },
+  function: {
+    dir: 'src/resources/functions/*.json',
+    minimalManifest: {
+      code: 'summarize_customer',
+      definitionJson: {
+        kind: 'app_function',
+        version: 'function_v1',
+        runtimeMode: 'trusted_node',
+        sourceType: 'inline',
+        code: 'module.exports = async () => ({ ok: true })',
+      },
+      status: 'active',
+    },
+    commands: [
+      'openxiangda function upsert --json-file src/resources/functions/summarize_customer.json',
+      'openxiangda function invoke summarize_customer --body-json \'{"input":{}}\'',
+    ],
+  },
+  connector: {
+    dir: 'src/resources/connectors/*.json',
+    minimalManifest: {
+      code: 'third_party',
+      name: '第三方服务',
+      protocol: 'https',
+      domain: 'api.example.com',
+      authType: 'none',
+      apis: [{ code: 'ping', path: '/ping', method: 'GET' }],
+    },
+    commands: [
+      'openxiangda connector upsert --json-file src/resources/connectors/third_party.json',
+      'openxiangda connector invoke third_party.ping --query-json query.json',
+    ],
+  },
+  notification: {
+    dir: 'src/resources/notifications/*.json',
+    minimalManifest: {
+      templates: [{ code: 'reservation_reminder', name: '预约提醒', content: '{{title}}' }],
+      typeConfigs: [{ notificationType: 'reservation_reminder', templateCode: 'reservation_reminder', enabled: true }],
+    },
+    commands: [
+      'openxiangda notification template-upsert --json-file src/resources/notifications/reservation_reminder.json',
+      'openxiangda notification preview reservation_reminder --body-json \'{"variables":{"title":"测试"}}\'',
+    ],
+  },
+  'data-view': {
+    dir: 'src/resources/data-views/*.json',
+    minimalManifest: {
+      code: 'customer_lookup',
+      base: { formCode: 'customer', alias: 'customer' },
+      select: [{ field: 'customer.form_instance_id', as: 'id' }],
+      refresh: { mode: 'manual' },
+    },
+    commands: [
+      'openxiangda data-view upsert --json-file src/resources/data-views/customer_lookup.json',
+      'openxiangda data-view query customer_lookup --query-json query.json',
+    ],
+  },
+  permission: {
+    dir: 'src/resources/roles 与 src/resources/permissions/**',
+    minimalManifest: {
+      role: { code: 'manager', name: '管理员' },
+      pageGroup: { code: 'manager_pages', name: '管理员页面', roles: ['manager'], routeCodes: ['admin.home'] },
+      formGroup: { code: 'customer_view', formCode: 'customer', name: '客户查看', type: 'view', roles: ['manager'] },
+    },
+    commands: [
+      'openxiangda permission audit --json',
+      'openxiangda permission role-update manager --json-file role.json --write-manifest',
+    ],
+  },
+};
+
+function getResourceExplain(type) {
+  const key = type || 'route';
+  return RESOURCE_EXPLAINS[key];
+}
+
+function renderResourceExplain(type) {
+  const item = getResourceExplain(type);
+  if (!item) {
+    return `未知资源类型: ${type}`;
+  }
+  return [
+    `# ${type}`,
+    `目录: ${item.dir}`,
+    '最小 manifest:',
+    JSON.stringify(item.minimalManifest, null, 2),
+    '常用命令:',
+    ...item.commands.map(command => `- ${command}`),
+  ].join('\n');
+}
+
+module.exports = {
+  DESIGN_GATE_HARD_RULE,
+  DESIGN_GATE_TOPICS,
+  getDesignGates,
+  getResourceExplain,
+  renderDesignGatesText,
+  renderDesignTemplate,
+  renderResourceExplain,
+};

package/openxiangda-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openxiangda
-description: "Use OpenXiangda for any private low-code platform or sy-lowcode-app-workspace work: architecture design, app creation, forms, pages, resources, workflows, automations, JS_CODE, permissions, data views, connectors, notifications, publishing, deployment, diagnosis, feedback, profile/login state, and CLI commands. Trigger on OpenXiangda, 湘搭, 私有化低代码, 低代码平台, .openxiangda/state.json, app-workspace.config.ts, or openxiangda CLI usage."
+description: "Use OpenXiangda for any private low-code platform or sy-lowcode-app-workspace work: architecture design, app creation, forms, pages, resources, workflows, automations, JS_CODE, permissions, data views, connectors, notifications, publishing, deployment, diagnosis, feedback, profile/login state, and CLI commands. Trigger on OpenXiangda, 享搭, 私有化低代码, 低代码平台, .openxiangda/state.json, app-workspace.config.ts, or openxiangda CLI usage."
 ---
 
 # OpenXiangda
@@ -15,30 +15,31 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 
 ### Routing — user intent → skill / command
 
-| User says (zh / en) | Skill | First command |
-|---|---|---|
-| 发布 classic workspace / 上线旧模式 | `openxiangda-core` | `openxiangda workspace publish --profile <name> --changed --dry-run` |
-| 发布 React SPA / Phase 6 runtime | `openxiangda-core` | `openxiangda resource publish --profile <name>` then `openxiangda runtime deploy --profile <name>` |
-| 只发布改动 / 增量 / 单页 / 单表 | `openxiangda-core` | `... --changed` / `--page <code>` / `--form <code>` / `--only pages/a,forms/b` |
-| 架构设计 / 详细设计 / 新应用需求 / 需求文档转享搭应用 | `openxiangda-architecture-design` | read `references/architecture-design.md`; inspect workspace/app state before coding |
-| 创建应用 / 新建 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` |
-| App Function / function_call / 可复用后端逻辑 | `openxiangda-workflow-automation` | declare `src/resources/functions/<code>.json` + `src/functions/<code>/index.ts` |
-| 应用登录 / Auth SDK / 手机号验证码 / CAS / 钉钉免登 | `openxiangda-architecture-design` + `openxiangda-page` | design security gate first, then declare `src/resources/auth/<code>.json` and use `createAuthClient` / `LoginPage` |
-| 角色 / 权限组 / 字段权限 / 数据范围 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| User says (zh / en)                                      | Skill                                                                                      | First command                                                                                                                                            |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 发布 classic workspace / 上线旧模式                      | `openxiangda-core`                                                                         | `openxiangda workspace publish --profile <name> --changed --dry-run`                                                                                     |
+| 发布 React SPA / Phase 6 runtime                         | `openxiangda-core`                                                                         | `openxiangda resource publish --profile <name>` then `openxiangda runtime deploy --profile <name>`                                                       |
+| 只发布改动 / 增量 / 单页 / 单表                          | `openxiangda-core`                                                                         | `... --changed` / `--page <code>` / `--form <code>` / `--only pages/a,forms/b`                                                                           |
+| 架构设计 / 详细设计 / 新应用需求 / 需求文档转享搭应用    | `openxiangda-architecture-design`                                                          | read `references/architecture-design.md`; inspect workspace/app state before coding                                                                      |
+| 创建应用 / 新建 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`                                                                                            |
+| App Function / function_call / 可复用后端逻辑            | `openxiangda-workflow-automation`                                                          | declare `src/resources/functions/<code>.json` + `src/functions/<code>/index.ts`                                                                          |
+| 应用登录 / Auth SDK / 手机号验证码 / CAS / 钉钉免登      | `openxiangda-architecture-design` + `openxiangda-page`                                     | design security gate first, then declare `src/resources/auth/<code>.json` and use `createAuthClient` / `LoginPage`                                       |
+| 角色 / 权限组 / 字段权限 / 数据范围                      | `openxiangda-permission-settings`                                                          | `openxiangda permission ...` / `openxiangda settings ...`                                                                                                |
 | 外部人员无需登录访问 / 公开报名 / 公开查询 / public page | `openxiangda-architecture-design` + `openxiangda-permission-settings` + `openxiangda-page` | 先确认公开范围、外部角色、ticket、grants；再声明 `routes` + `public-access`，并用 `OpenXiangdaProvider` + `OpenXiangdaPageProvider` + `PublicAccessGate` |
-| 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错 | `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` with `storageMode` → `resource publish` |
-| 调外部 / 第三方 API / 钉钉 / 自建系统 | `openxiangda-page` (connector) | declare `src/resources/connectors/<code>.json` → `sdk.connector.invoke` |
+| 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错            | `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` with `storageMode` → `resource publish`                                                                   |
+| 调外部 / 第三方 API / 钉钉 / 自建系统                    | `openxiangda-page` (connector)                                                             | declare `src/resources/connectors/<code>.json` → `sdk.connector.invoke`                                                                                  |
 
 ### Hard rules — always
 
 - ✅ Publish classic workspaces through `openxiangda workspace publish --profile <name>`; publish React SPA workspaces through `openxiangda resource publish` + `openxiangda runtime deploy`.
+- ✅ Architecture-class requests are plan-gated by default. For 新应用、复杂页面、登录注册、公开访问、权限数据范围、流程自动化、连接器/通知、外部集成, first run `openxiangda doctor --json` when a workspace exists and `openxiangda design gates --topic <code> --json`; then ask the user to confirm the design. Before confirmation, only read files, inspect/snapshot, dry-run, ask questions, and write/output design docs. Do not edit source files, write platform resources, send notifications, publish, or deploy.
 - ✅ `runtime deploy` defaults to staged multipart `dist/` uploads plus a final manifest. Use `--upload-mode legacy-json` only for old platform servers.
 - ✅ 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.
@@ -47,6 +48,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ✅ For app login/auth requirements, run the auth security gate before coding: enabled methods, registration policy, identity matching keys, provider boundary, default roles, rate limits, audit fields, and third-party ownership must be confirmed.
 - ✅ For public/no-login access requirements, run the public access design gate before coding: public routes, external role codes, guest vs ticket, form/dataView/function/connector grants, backend permission groups, and visible loading/error fallback states must be confirmed. New React SPA apps use `/view/:appType/public/*`, `src/resources/routes/`, `src/resources/public-access/`, and `PublicAccessGate`; route children that use Page SDK hooks must be inside `OpenXiangdaProvider` + `OpenXiangdaPageProvider`.
 - ✅ Public/no-login validation must inspect the JSON envelope, not only HTTP status. HTTP 200 with `code: "PUBLIC_GRANT_DENIED"` is a denied request; success requires `code` `200`, `"200"`, or compatible `0`, and no `success: false`.
+- ✅ Use first-class resource CLI commands for discovery, diagnosis, and small live fixes: `route`, `public-access`, `auth-config`, `function`, `connector`, `notification`, `data-view`, `menu`, and `permission`. For multi-resource formal development, still prefer `src/resources/**` + `openxiangda resource validate|plan|publish`. If a direct CLI write is intentionally used, add `--write-manifest` when the repository should stay the source of truth.
 - ✅ For form-entry UX, pick components in this order: OpenXiangda platform form components → `antd` / `antd-mobile` wrappers → custom component only when neither exists.
 - ✅ List pages, linked options, remote selectors, and report drill-downs must use paginated server-side queries with explicit searchable fields. Do not fetch a large page and filter in local state.
 - ✅ Treat workflow forms as an exception. Ordinary ticket/order/task/asset lifecycles use status fields, state machines, action logs, permissions, and automations; workflows are for real approval tasks.
@@ -58,6 +60,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ❌ 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.
+- ❌ 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.
 - ❌ 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`.
 - ❌ Raw native HTML form controls in AI-authored workspace code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, hand-written upload controls). They are allowed only inside OpenXiangda SDK/platform component internals.

package/openxiangda-skills/references/architecture-design.md

@@ -44,6 +44,16 @@ Do not insult the person. Criticize the proposal and explain the technical conse
 
 ## Architecture Gate Workflow
 
+Before any implementation for architecture-class work, run the CLI gate when available:
+
+```bash
+openxiangda doctor --profile <name> --json
+openxiangda design gates --topic public-access --json
+openxiangda design template --topic auth,public-access
+```
+
+Until the user confirms the design, only read, inspect, snapshot, dry-run, ask questions, and write/output the architecture document. Do not edit app source, mutate platform resources, publish, deploy, send notifications, or invoke live write/delete endpoints.
+
 1. **Read the input**: user prompt, uploaded requirements, current workspace files, app snapshots, and existing resources.
 2. **Classify the app**: admin CRUD, portal, workbench, dashboard, workflow approval, status lifecycle, automation-heavy app, integration-heavy app, or mixed.
 3. **Draft the resource map**:
@@ -60,6 +70,21 @@ Do not insult the person. Criticize the proposal and explain the technical conse
    `docs/architecture/<app-slug>-openxiangda-design.md`.
 8. **Create a development task table** that can be executed by OpenXiangda subskills.
 
+## Design Gate Matrix
+
+Use this matrix to decide what to ask. Ask in small rounds, and recommend the default option when the user is unsure.
+
+| Topic | Trigger examples | Must confirm | Recommended default | Resources to design | Acceptance |
+|---|---|---|---|---|---|
+| 新应用 / 大版本 | 新应用、从零搭建、门户、管理系统 | actors, core objects, internal/external access, first screen, integrations | React SPA + `src/resources/**` + design doc first | forms, routes, menus, roles, dataViews, auth/public policies | user confirms resource map and permission matrix |
+| 复杂页面 / 工作台 | 看板、工作台、详情页、移动端、大屏 | page task, data source, edits/batch actions, role visibility, empty/error states | dataView for repeated reads, App Function for backend orchestration | route/menu, page component, dataView/function, permissions | role-specific UI works; no PageProvider errors |
+| 登录 / 注册 | 登录、注册、手机号验证码、SSO、账号绑定 | methods, registration policy, identity match keys, provider function, default roles, rate limits | `registration.mode=reject`; provider returns identity assertion only | `src/resources/auth`, login route/page, App Function provider | methods match SDK DTO; internal route requires auth |
+| 公开访问 | 无需登录、外部人员、公开报名、分享链接 | public routes, external roles, guest vs ticket, grants, rate limit, audit/expiry | `/view/:appType/public/*` + route + public-access policy; sensitive lookup uses ticket | `src/resources/routes`, `src/resources/public-access`, external role permission groups, `PublicAccessGate` | no-login public route works; ungranted resources deny |
+| 权限 / 数据范围 | 角色、只看自己、部门数据、字段权限 | roles, page/menu groups, form operations, data scope, field access, rejection tests | backend permission groups, not frontend-only filtering | roles, page-groups, form-groups, field access policy | `permission audit` clean; allowed/denied paths verified |
+| 流程 / 自动化 / Function | 审批、状态流转、定时、JS_CODE、App Function | trigger, node IO, idempotency, resources, approval vs status machine, logs | normal status machine unless real approval; reusable logic as App Function | workflows, automations, functions, JS_CODE source | invoke/executions/logs verified; duplicate trigger safe |
+| 连接器 / 通知 | 第三方接口、Webhook、短信、钉钉、消息 | auth, timeout/retry, secret owner, notification type/template, recipients, failure policy | connector for external HTTP; notification resources before sending | connectors, notifications, App Function wrapper if needed | `connector invoke` and notification preview/send DTOs pass |
+| 资源维护 | 补路由、修权限、删除配置、同步 manifest | live mutation or repo source of truth, profile/appType, force/delete/send risk | `resource plan/publish` for formal changes; direct CLI with `--write-manifest` for small fixes | affected manifest and state mapping | dry-run path/body reviewed; no repo/platform drift |
+
 ## Anti-Patterns To Reject
 
 | Anti-pattern | Why it is wrong | Required replacement |

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -13,14 +13,50 @@
 
 ## 命令
 
+正式多资源开发仍推荐先写 `src/resources/**`，再走声明式发布：
+
 ```bash
 openxiangda resource validate --profile <name>          # 静态校验所有 manifest
 openxiangda resource plan     --profile <name>          # diff：本地 vs. 平台
 openxiangda resource publish  --profile <name>          # 非破坏性 upsert（不 prune）
 openxiangda resource publish  --profile <name> --prune  # 删除 manifest 未声明的平台资源（谨慎）
 openxiangda resource pull     --profile <name>          # 拉取平台资源回写到本地（用于初次同步）
+openxiangda resource explain public-access --json       # 查看资源目录、最小 manifest、验证命令
+```
+
+小步诊断、修复或 AI 自动发现能力时，可以用一等资源 CLI。写命令默认是 live mutation；需要让仓库继续作为来源时加 `--write-manifest`，复杂 DTO 用 `--json-file`，危险动作用 `--force`，先看请求就加 `--dry-run`。
+
+```bash
+openxiangda doctor --profile <name> --json
+openxiangda design gates --topic public-access --json
+
+openxiangda route upsert --json-file src/resources/routes/public_register.json --dry-run
+openxiangda public-access upsert --json-file src/resources/public-access/public_register.json --write-manifest
+openxiangda public-access ticket-create public_register --json-file ticket.json
+openxiangda public-access session-test public_register --path /view/APP_XXX/public/register --json
+openxiangda public-access grant-check public_register --form-code registration_form --json
+
+openxiangda auth-config methods --json
+openxiangda auth-config upsert --json-file src/resources/auth/default.json --write-manifest
+
+openxiangda function upsert --json-file src/resources/functions/submit_public_registration.json
+openxiangda function invoke submit_public_registration --body-json '{"input":{}}'
+
+openxiangda connector upsert --json-file src/resources/connectors/sms.json
+openxiangda connector invoke sms.sendCode --body-json '{"body":{"phone":"13800000000"}}'
+
+openxiangda notification template-upsert --json-file src/resources/notifications/register.json
+openxiangda notification type-upsert --json-file src/resources/notifications/register.json
+openxiangda notification preview public_register_notice --body-json '{"variables":{"title":"测试"}}'
+
+openxiangda data-view upsert --json-file src/resources/data-views/public_lookup.json
+openxiangda menu update public_register --json-file src/resources/menus/public_register.json --write-manifest
+openxiangda permission audit --json
+openxiangda permission role-update external_visitor --json-file src/resources/roles/external_visitor.json --write-manifest
 ```
 
+调用和测试类命令会检查 JSON envelope。HTTP 200 但 `code: "PUBLIC_GRANT_DENIED"`、`success: false` 或其他字符串错误码必须当失败，不能只看 HTTP status。
+
 ## 0. Auth — `src/resources/auth/<code>.json`
 
 ```json