openyida 2026.7.18 → 2026.7.19

package/README.md

@@ -149,7 +149,7 @@ openyida/
 ├── bin/yida.js                 # CLI entry and command routing
 ├── lib/
 │   ├── app/                    # Application, form, page, import/export commands
-│   ├── auth/                   # Login, QR login, browser handoff, organization switch
+│   ├── auth/                   # OAuth token login, token session storage, organization switch
 │   ├── connector/              # HTTP connector lifecycle and smart creation
 │   ├── core/                   # Environment detection, i18n, diagnostics, data commands
 │   ├── process/                # Process form creation, configuration, preview
@@ -277,6 +277,20 @@ The E2E paths above prove the *CLI* works. The eval harness under `scripts/eval/
 # the selected sub-skill against the golden set.
 npm run eval:routing
 
+# Doc quality — static analysis of all SKILL.md files (standards + maintainability).
+npm run eval:doc-quality
+
+# Safety — credential leak detection, command whitelist, corpId consistency.
+npm run eval:safety
+
+# Coverage — how much of the skill/category/reference space is covered by scenarios.
+npm run eval:coverage
+
+# Comprehensive — 10-dimension scorecard for a single skill (doc quality, routing,
+# safety, step completeness, output validity, efficiency, stability, coverage).
+# Outputs a JSON scorecard, SVG radar chart, and trend analysis.
+npm run eval:comprehensive -- --skill yida-dashboard
+
 # Tool-pipeline baseline (end-to-end) — wraps the real-environment runner for one
 # sub-skill, adds guardrail assertions, screenshots the published page, and writes a
 # human scoring template. Runs deterministic CLI commands (no agent) so it serves as
@@ -302,15 +316,19 @@ OPENYIDA_E2E=1 npm run eval:all -- --skill yida-dashboard --screenshot
 # that runs the tasks above on click. Binds to 127.0.0.1 only; tasks are a fixed
 # whitelist. Use the Node version you start it with, so run `nvm use 20` first.
 npm run eval:dashboard          # http://127.0.0.1:4500
+
+# You can also run eval directly via the CLI:
+openyida eval --mode comprehensive --skill yida-dashboard
 ```
 
 Configuration precedence is `CLI flag > env (OPENYIDA_EVAL_*) > scripts/eval/eval.config.json > defaults`.
 
 | Flag | Purpose |
 |------|---------|
-| `--mode e2e\|routing\|generate\|all` | Which evals to run (default `e2e`; `all` = routing + tool-pipeline baseline + real generation) |
+| `--mode e2e\|routing\|generate\|doc-quality\|safety\|coverage\|comprehensive\|all` | Which evals to run (default `e2e`) |
 | `--skill <name>` | Restrict the e2e run to one sub-skill; stages are reverse-looked-up from the `SKILL_COVERAGE` matrix |
 | `--stages a,b` | Explicit stage list, overriding the skill reverse-lookup |
+| `--runs N` | Multi-run stability: repeat routing N times, report consistency rate |
 | `--screenshot` / `--no-screenshot` | Capture the published page (default on; skipped gracefully if Playwright is absent) |
 | `--auto-score` / `--no-auto-score` | Score screenshots with the local `claude -p` agent (default off → human template only) |
 | `--scenarios <dir>` | Routing golden-set directory (default `scripts/eval/scenarios`) |
@@ -468,6 +486,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida copy [--force]` | Copy project working directory |
 | `openyida sample [--list]` | Output code samples/templates |
 | `openyida doctor [--fix]` | Environment diagnostics & auto-fix |
+| `openyida eval --mode <mode> [--skill <name>] [--runs N]` | Multi-dimensional skill evaluation (doc quality, routing accuracy, safety, etc.) |
 | `openyida db-seq-fix [--fix]` | Detect and repair PostgreSQL sequence drift |
 | `openyida formula evaluate <formula\|file> [--schema file]` | Static-check Yida formula syntax and field refs |
 | `openyida update` | Check and update to latest version |
@@ -493,6 +512,8 @@ Environment selectors such as `--env intl`, `--intl`, `--overseas`, `--global`,
 
 For overseas apps, pass `--locale en_US` or `--locale ja_JP` on creation commands, or set `OPENYIDA_CONTENT_LOCALE`. OpenYida writes YiDA resource names with `zh_CN`, `en_US`, and `ja_JP` values so Global YiDA does not fall back to Chinese-only metadata.
 
+The CLI package ships the core UI languages `zh` and `en` by default. Other CLI UI language packs are optional: keep or install files such as `ja.js` / `fr.js` in an external directory and point `OPENYIDA_LOCALE_DIR` to that directory, then set `OPENYIDA_LANG=ja`. If an optional language pack is unavailable, OpenYida falls back through `en -> zh`.
+
 #### Forms and Pages
 
 Form field definitions can include `alias` or `componentAlias` to populate Yida designer component aliases, stored as `pages[0].componentAlias.items`. Yida runtime resolves these aliases in page JS, so `this.$('phone')` can be used instead of `this.$('textField_xxx')`; OpenYida form rules, validations, and `openyida data ... --resolve-aliases` JSON inputs also accept aliases as field references. For server-side DingTalk OpenAPI calls, use `GET /v2.0/yida/forms/component/alias/{appType}/{formUuid}` to read the `{ fieldId, alias }` mapping, then translate aliases before sending form data/search JSON. That endpoint requires `systemToken`, `userId`, an access token, and the Yida form data read permission; grant that permission in DingTalk developer console API permissions and publish the DingTalk app. Yida app code and app secret are available under app settings > deployment/maintenance.

package/bin/yida.js

@@ -1051,6 +1051,12 @@ async function main() {
       break;
     }
 
+    case 'eval': {
+      const { main: evalMain } = require('../scripts/eval/runner');
+      await evalMain(args);
+      break;
+    }
+
     default: {
       throwCliUsage(t('cli.unknown_command', command), t('cli.run_help'));
     }

package/docs/capabilities.md

@@ -0,0 +1,202 @@
+# OpenYida 功能完整列表
+
+这份清单面向宜搭使用者，说明 OpenYida 支持的功能，以及对应可以执行的 `openyida` 命令。参数细节可以继续查看 `openyida --help`、`openyida <command> --help` 或 `openyida commands --json`。
+
+## 基础操作
+
+| 功能 | 执行操作 |
+|---|---|
+| 查看当前环境和登录态 | `openyida env` / `openyida env --json` |
+| 登录宜搭 | `openyida login` |
+| 指定入口登录 | `openyida login <target-url>` |
+| 只检查是否已登录 | `openyida login --check-only --json` |
+| 查看可切换组织 | `openyida org list` |
+| 交互式切换组织 | `openyida org switch` |
+| 切换到指定组织 | `openyida org switch --corp-id <corpId>` |
+| 退出登录 | `openyida logout` |
+| 管理 token 登录态 | `openyida auth <status\|login\|refresh\|logout>` |
+| 查看全部命令清单 | `openyida commands --json` |
+| 查看 Agent 一次性能力快照 | `openyida agent-capabilities --json` / `openyida agent-capabilities --summary-json` |
+
+## 应用与组织管理
+
+| 功能 | 执行操作 |
+|---|---|
+| 查询我的应用 | `openyida app-list [--size N]` |
+| 创建应用 | `openyida create-app "<应用名称>"` |
+| 更新应用名称、布局、主题 | `openyida update-app <appType> [--name "..."] [--layout slide\|ver] [--theme deepBlue]` |
+| 导出应用迁移包 | `openyida export <appType> [output]` |
+| 导入应用迁移包 | `openyida import <file> [name]` |
+| 管理左侧导航分组 | `openyida nav-group <list\|create\|rename\|delete\|move\|order\|hide\|show> <appType> ...` |
+| 管理应用管理员 | `openyida app-permission <get\|set\|add\|remove\|search-user> ...` |
+| 管理应用多语言 | `openyida i18n <overview\|config\|languages\|list\|upsert\|delete\|translate\|translate-all\|upgrade> <appType> ...` |
+| 查询组织基础信息、容量、额度、域名 | `openyida basic-info <overview\|commodity\|grant\|capacity\|quota\|abs-path\|dataflow\|i18n\|domain>` |
+| 查询企业效能 | `openyida corp-efficiency [overview\|details\|detail\|groups\|notify] [options]` |
+| 管理平台管理员和通讯录权限 | `openyida corp-manager <search-user\|list\|add\|remove\|address-book> ...` |
+
+说明：CLI 界面语言默认内置 `zh` / `en`。其他语言包可通过 `OPENYIDA_LOCALE_DIR` 按需加载；应用内多语言仍使用 `openyida i18n` 管理宜搭应用文案。
+
+## 表单与数据模型
+
+| 功能 | 执行操作 |
+|---|---|
+| 创建表单 | `openyida create-form create <appType> ...` |
+| 更新表单字段 | `openyida create-form update <appType> ...` |
+| 用 patch 更新表单 | `openyida create-form patch <appType> <formUuid> <patchJsonOrFile>` |
+| 配置表单联动规则 | `openyida create-form rule <appType> <formUuid> <rulesJsonOrFile>` |
+| 配置字段校验 | `openyida create-form validation <appType> <formUuid> <validationsJsonOrFile>` |
+| 快速新增字段校验 | `openyida add-validation <appType> <formUuid> --field <labelOrId> --type <phone\|regex\|idCard\|email\|...>` |
+| 绑定字段远程数据源 | `openyida create-form bind-datasource <appType> <formUuid> <fieldLabelOrId> <dataSourceJsonOrFile>` |
+| 给选项字段追加选项 | `openyida create-form add-option <appType> <formUuid> <fieldLabel> <option1> [option2] ...` |
+| 查询应用内表单/页面 | `openyida list-forms <appType> [--keyword <text>]` |
+| 获取表单 Schema | `openyida get-schema <appType> <formUuid>` |
+| 获取应用全部 Schema | `openyida get-schema <appType> --all` |
+| 导出 ER 关系图 | `openyida er <appType> [--format mermaid\|json] [--output file]` |
+| 管理聚合表 virtualView | `openyida aggregate-table <list\|create-empty\|inspect\|preview\|save\|publish\|status> <appType> ...` |
+
+## 自定义页面与发布
+
+| 功能 | 执行操作 |
+|---|---|
+| 创建自定义页面 | `openyida create-page <appType> "<页面名称>"` |
+| 创建看板页 | `openyida create-page <appType> "<页面名称>" --mode dashboard` |
+| 从模板生成页面源码 | `openyida generate-page <template>` |
+| 构建宜搭兼容页面源码 | `openyida build-page <sourceFile> [--output file\|--write]` |
+| 检查普通自定义页面 JSX 规范 | `openyida check-page <src> [--compat]` |
+| 本地编译普通自定义页面 JSX | `openyida compile <src>` |
+| 发布普通自定义页面 JSX | `openyida publish project/pages/src/home.oyd.jsx <appType> <formUuid>` |
+| 发布 Code Canvas 页面 | `openyida publish project/pages/src/home.canvas.jsx <appType> <formUuid>`（`.canvas.jsx` / `.canvas.tsx` 自动启用 Canvas 编译，生成 `runtimeCode` + `importedModules` 并保存为 `YidaCodeCanvas` Schema） |
+| 显式按 Code Canvas 链路发布 | `openyida publish <src> <appType> <formUuid> --canvas` |
+| 发布并做健康检查 | `openyida publish <src> <appType> <formUuid> --health-check` |
+| 更新页面/表单配置 | `openyida update-form-config <appType> ...` |
+| 查询页面/表单配置 | `openyida get-form-config <appType> <formUuid> [--json]` |
+| 开发高级自定义页面、看板、图表或幻灯片 | 默认优先使用 Code Canvas 链路；明确要求普通自定义页面 JSX/Jsx，或强依赖普通自定义页实例桥时使用 `.oyd.jsx` + `check-page` / `compile` / `publish` |
+| Code Canvas 页面使用成员/部门/上传等宜搭运行态组件 | `openyida sample yida-canvas-custom-page native-components-smoke --output pages/src/native-components-smoke.canvas.jsx`；再参考 `yida-canvas-custom-page/references/native-components-bridge.md` |
+| Code Canvas 门户 + 成员/部门/上传组件示例 | `openyida sample yida-canvas-custom-page portal-native-components --output pages/src/portal-native-components.canvas.jsx` |
+| 普通自定义页面 JSX/Jsx 使用成员/部门组件 | 使用 `.oyd.jsx`，参考 `yida-custom-page/references/component-jsx-guide.md` |
+| 普通自定义页面 JSX/Jsx 使用附件/图片上传 | 使用 `.oyd.jsx`，参考 `yida-custom-page/references/attachment-upload-guide.md` |
+
+### 自定义页面链路选择
+
+| 需求 | 推荐链路 |
+|---|---|
+| 现代 React、hooks、官网、工作台、看板、列表、详情、可视化、AI 首次生成页面 | Code Canvas：`.canvas.jsx` / `YidaCodeCanvas` |
+| 需要成员、部门、附件上传、图片上传等宜搭运行态组件，且希望页面保持现代 React 体验 | Code Canvas + 原生组件桥；先跑 smoke 示例验证运行态组件，再做 fallback 和值归一化 |
+| 用户明确要求普通自定义页面 JSX/Jsx 组件链路 | 普通自定义页面：`.oyd.jsx` / `Jsx` |
+| 强依赖 `this.$(fieldId)`、`this.utils.yida.*`、`this.dataSourceMap`、表单提交或字段双向绑定 | 普通自定义页面：`.oyd.jsx` / `Jsx` |
+| 已有普通 `.oyd.jsx` 页面要迁移到 Code Canvas | 参考 `yida-canvas-upgrade` 技能 |
+
+## 流程、审批与任务
+
+| 功能 | 执行操作 |
+|---|---|
+| 创建流程表单并配置流程 | `openyida create-process <appType> ...` |
+| 配置并发布流程规则 | `openyida configure-process <appType> ...` |
+| 预览流程实例 | `openyida process preview <appType> <processInstanceId> [--output <path>]` |
+| 查询 AI 审批提示配置 | `openyida ai-form-setting get <appType> <formUuid>` |
+| 查询 AI 审批可用字段 | `openyida ai-form-setting fields <appType> <formUuid>` |
+| 查询 AI 审批模型 | `openyida ai-form-setting models <appType>` |
+| 开启或关闭 AI 审批提示 | `openyida ai-form-setting <enable\|disable> <appType> <formUuid>` |
+| 保存 AI 审批提示配置 | `openyida ai-form-setting save <appType> <formUuid> <config.json>` |
+| 查询任务中心 | `openyida task-center <type> [options]` |
+| 管理流程代理/离职代理 | `openyida agent-center <list\|create\|update\|cancel\|range\|search-user> ...` |
+
+## 数据、权限与分享
+
+| 功能 | 执行操作 |
+|---|---|
+| 查询表单数据 | `openyida data query form <appType> <formUuid> [options]` |
+| 新增表单数据 | `openyida data create form <appType> <formUuid> --data-file <file>` |
+| 更新表单数据 | `openyida data update form <appType> <formUuid> <formInstId> --data-file <file>` |
+| 查询流程/任务/子表数据 | `openyida data <action> <resource> [args]` |
+| 查询表单权限 | `openyida get-permission <appType> <formUuid>` |
+| 保存表单权限 | `openyida save-permission <appType> <formUuid> ...` |
+| 验证短链接 | `openyida verify-short-url <appType> ...` |
+| 保存公开访问/分享配置 | `openyida save-share-config <appType> ...` |
+| 查询页面分享配置 | `openyida get-page-config <appType> <formUuid>` |
+| 规划公开表单镜像字段 | `openyida externalize-form <appType> <formUuid> [--schema-file file]` |
+
+## 报表、看板与可视化
+
+| 功能 | 执行操作 |
+|---|---|
+| 创建宜搭原生报表 | `openyida create-report <appType> "<报表名称>" ...` |
+| 向已有报表追加图表 | `openyida append-chart <appType> <reportId> ...` |
+| 创建 ECharts 高级报表 | 使用自定义页面开发链路，并执行 `openyida publish ...` |
+| 创建经营看板/管理驾驶舱/数据大屏 | 使用 `create-page`、数据源配置、报表命令和 `publish` 组合完成 |
+
+## 连接器、集成与钉钉
+
+| 功能 | 执行操作 |
+|---|---|
+| 查询 HTTP 连接器 | `openyida connector list` |
+| 创建 HTTP 连接器 | `openyida connector create "name" "domain" ...` |
+| 查看连接器详情 | `openyida connector detail <id>` |
+| 删除连接器 | `openyida connector delete <id>` |
+| 添加连接器动作 | `openyida connector add-action --operations <file> --connector-id <id>` |
+| 查询连接器动作 | `openyida connector list-actions <id>` |
+| 删除连接器动作 | `openyida connector delete-action <id> <operation-id>` |
+| 测试连接器动作 | `openyida connector test --connector-id <id> --action <actionId>` |
+| 查询连接器鉴权账号 | `openyida connector list-connections <id>` |
+| 创建连接器鉴权账号 | `openyida connector create-connection <id> <name>` |
+| 从 cURL 智能创建连接器 | `openyida connector smart-create --curl "..."` |
+| 解析 API 文档/接口信息 | `openyida connector parse-api [options]` |
+| 生成 API 文档模板 | `openyida connector gen-template [output]` |
+| 创建集成自动化 | `openyida integration create <appType> ... [--spec file.json]` |
+| 查询集成自动化 | `openyida integration list <appType> [--form-uuid <uuid>]` |
+| 启用集成自动化 | `openyida integration enable <appType> <formUuid> <processCode>` |
+| 停用集成自动化 | `openyida integration disable <appType> <formUuid> <processCode>` |
+| 检查集成异常日志 | `openyida integration check <appType...>` |
+| 诊断集成配置问题 | `openyida integration diagnose (--text <text>\|--file <path>\|--rules)` |
+| 调用钉钉 CLI | `openyida dws <command> [args]` |
+| 搜索钉钉联系人 | `openyida dws contact user search --keyword <text>` |
+| 生成钉钉 AppLink | `openyida dingtalk-link <url> [--target fullScreen]` |
+
+## AI、公式与知识整理
+
+| 功能 | 执行操作 |
+|---|---|
+| 宜搭 AI 文生文 | `openyida ai text [options]` |
+| 宜搭 AI 识图 | `openyida ai image [options]` |
+| 检测素材能力 | `openyida asset status [options]` |
+| 校验图片 URL | `openyida asset verify-url <url> [options]` |
+| 解析并回填页面素材 | `openyida asset resolve [options]` |
+| 生成 AI 图片素材 | `openyida asset generate [options]` |
+| 检查宜搭公式 | `openyida formula evaluate <formula\|file> [--schema file]` |
+| 闪记/会议纪要转 PRD | `openyida flash-to-prd --file <path> --name "<project>"` |
+| 导出 AI 对话记录 | `openyida export-conversation [options]` |
+| 整理 VOC 反馈材料 | 按故障、需求或性能问题整理成可提交材料 |
+| 配置体验反馈入口 | `openyida feedback <setup\|url\|dismiss\|status> [options]` |
+
+## 本地开发、诊断与运维
+
+| 功能 | 执行操作 |
+|---|---|
+| 初始化 project 工作目录 | `openyida copy [--force]` |
+| 查看/输出示例模板 | `openyida sample [--list]` |
+| 环境诊断与自动修复 | `openyida doctor [--fix]` |
+| 批量执行命令文件 | `openyida batch <file> [--stop-on-error] [--json]` |
+| 批量执行内联命令 | `openyida batch --commands "cmd1 ; cmd2" [--stop-on-error] [--json]` |
+| 检查并更新 OpenYida | `openyida update` |
+| 配置 CDN/OSS 上传 | `openyida cdn-config [options]` |
+| 上传图片到 CDN | `openyida cdn-upload <image-path>` |
+| 刷新 CDN 缓存 | `openyida cdn-refresh [options]` |
+| 检测/修复 PostgreSQL Sequence 漂移 | `openyida db-seq-fix [--fix]` |
+| 启动 MCP 服务 | `openyida mcp` |
+| 启动 A2A adapter 或输出 Agent Card | `openyida a2a <serve\|agent-card> [options]` |
+| 启动本地 Web bridge | `openyida bridge start [--token <pair-token>] [--port 6736]` |
+| 输出机器可读命令清单 | `openyida commands --json` |
+| 输出 Agent 能力快照 | `openyida agent-capabilities --json` |
+| 运行技能评测 | `openyida eval --mode <mode> [--skill <name>] [--runs N]` |
+
+## Agent 能力、评测与安全提示
+
+| 功能 | 执行操作 |
+|---|---|
+| 快速判断当前工作区、登录态、组织和命令能力 | `openyida agent-capabilities --summary-json` |
+| 获取完整命令 Manifest、副作用和权限元数据 | `openyida commands --json` |
+| 运行无副作用路由评测 | `openyida eval --mode routing [--skill <name>]` |
+| 运行文档质量 / 安全 / 覆盖率评测 | `openyida eval --mode <doc-quality\|safety\|coverage\|comprehensive>` |
+| 运行真实端到端评测 | `OPENYIDA_E2E=1 openyida eval --mode <e2e\|generate>` |
+
+`commands --json` 中的 `sideEffect` 和 `permission` 是 Agent 执行前的重要依据。`mixed` 命令需要继续查看具体子命令或参数：例如 `data query` 是读操作，`data delete` 是删除；`nav-group list` 是读操作，`nav-group delete` 需要确认。

package/lib/agent-center/agent-center.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('fs');
+const { throwUsage } = require('../core/command-errors');
 
 const {
   listAgentTasks,
@@ -44,9 +45,7 @@ Examples:
 `;
 
 function fail(message) {
-  console.error(message);
-  console.error(USAGE);
-  process.exit(1);
+  throwUsage(message, USAGE);
 }
 
 function parseCliOptions(tokens) {

package/lib/app/app-list.js

@@ -12,6 +12,7 @@
 'use strict';
 
 const { createAuthRef, createYidaClient } = require('../core/yida-client');
+const { throwCommandError } = require('../core/command-errors');
 
 const API_PATH = '/query/app/getAppList.json';
 
@@ -115,14 +116,12 @@ async function run(args) {
   try {
     apps = await fetchAllApps(authRef, pageSize);
   } catch (err) {
-    console.error(`查询应用列表失败：${err.message}`);
-    process.exit(1);
+    throwCommandError(`查询应用列表失败：${err.message}`);
   }
 
   // 如果重试后仍然返回登录失效标记，说明登录态确实不可用
   if (apps && apps.__needLogin) {
-    console.error('登录态已失效，请重新登录');
-    process.exit(1);
+    throwCommandError('登录态已失效，请重新登录', { code: 'CLI_AUTH_REQUIRED' });
   }
 
   if (!apps || apps.length === 0) {

package/lib/app/build-page.js

@@ -4,8 +4,9 @@ const fs = require('fs');
 const path = require('path');
 const { buildPageFile } = require('./page-compat');
 const { printLintResult } = require('./page-linter');
-const { warn, error, success, result, label, hint } = require('../core/chalk');
+const { warn, success, result, label, hint } = require('../core/chalk');
 const { t } = require('../core/i18n');
+const { throwCommandError, throwUsage } = require('../core/command-errors');
 
 function parseArgs(args) {
   const options = {
@@ -45,14 +46,17 @@ function parseArgs(args) {
 async function run(args) {
   const options = parseArgs(args || []);
   if (!options.sourceFile) {
-    warn(t('cli.build_page_usage'));
-    warn(t('cli.build_page_example'));
-    process.exit(1);
+    throwUsage(t('cli.build_page_usage'), t('cli.build_page_example'), {
+      code: 'BUILD_PAGE_INVALID_ARGUMENTS',
+    });
   }
 
   const sourcePath = path.resolve(options.sourceFile);
   if (!fs.existsSync(sourcePath)) {
-    error(t('publish.source_not_found', sourcePath));
+    throwCommandError(t('publish.source_not_found', sourcePath), {
+      code: 'BUILD_PAGE_SOURCE_NOT_FOUND',
+      details: { sourcePath },
+    });
   }
 
   const buildResult = buildPageFile(sourcePath, {
@@ -88,7 +92,10 @@ async function run(args) {
   }
 
   if (!buildResult.ok) {
-    process.exit(1);
+    throwCommandError(t('build_page.failed'), {
+      code: 'BUILD_PAGE_FAILED',
+      details: { errors: buildResult.errors },
+    });
   }
 
   if (!options.json) {

package/lib/app/check-page.js

@@ -6,7 +6,8 @@ const { lintYidaSource, printLintResult } = require('./page-linter');
 const { buildPageSource, shouldBuildPageSource } = require('./page-compat');
 const { warnLargePageSource } = require('./page-size-guard');
 const { t } = require('../core/i18n');
-const { warn, error, hint } = require('../core/chalk');
+const { warn, hint } = require('../core/chalk');
+const { throwCommandError, throwUsage } = require('../core/command-errors');
 
 function parseArgs(args) {
   return {
@@ -20,14 +21,17 @@ async function run(args) {
   const options = parseArgs(args || []);
 
   if (!options.sourceFile) {
-    warn(t('cli.check_page_usage'));
-    warn(t('cli.check_page_example'));
-    process.exit(1);
+    throwUsage(t('cli.check_page_usage'), t('cli.check_page_example'), {
+      code: 'CHECK_PAGE_INVALID_ARGUMENTS',
+    });
   }
 
   const sourcePath = path.resolve(options.sourceFile);
   if (!fs.existsSync(sourcePath)) {
-    error(t('publish.source_not_found', sourcePath));
+    throwCommandError(t('publish.source_not_found', sourcePath), {
+      code: 'CHECK_PAGE_SOURCE_NOT_FOUND',
+      details: { sourcePath },
+    });
   }
 
   const sourceCode = fs.readFileSync(sourcePath, 'utf-8');
@@ -63,7 +67,13 @@ async function run(args) {
   }
 
   if (!ok) {
-    process.exit(1);
+    throwCommandError(t('check_page.failed'), {
+      code: 'CHECK_PAGE_FAILED',
+      details: {
+        errors: lintResult.errors,
+        buildErrors,
+      },
+    });
   }
 }
 

package/lib/app/compile.js

@@ -7,7 +7,8 @@ const { runLintCheck } = require('./page-linter');
 const { buildPageFile, shouldBuildPageSource } = require('./page-compat');
 const { warnLargePageSource } = require('./page-size-guard');
 const { t } = require('../core/i18n');
-const { warn, error, info, step } = require('../core/chalk');
+const { warn, info, step } = require('../core/chalk');
+const { throwCommandError, throwUsage } = require('../core/command-errors');
 
 /**
  * compile 命令：只编译自定义页面源码，不发布到宜搭。
@@ -15,9 +16,9 @@ const { warn, error, info, step } = require('../core/chalk');
  */
 async function run(args) {
   if (!args || args.length < 1) {
-    warn(t('cli.compile_usage'));
-    warn(t('cli.compile_example'));
-    process.exit(1);
+    throwUsage(t('cli.compile_usage'), t('cli.compile_example'), {
+      code: 'COMPILE_INVALID_ARGUMENTS',
+    });
   }
 
   const skipLint = args.includes('--skip-lint');
@@ -25,7 +26,10 @@ async function run(args) {
   const filteredArgs = args.filter(arg => arg !== '--skip-lint' && arg !== '--compat' && arg !== '--modern');
   let sourcePath = path.resolve(filteredArgs[0]);
   if (!fs.existsSync(sourcePath)) {
-    error(t('publish.source_not_found', sourcePath));
+    throwCommandError(t('publish.source_not_found', sourcePath), {
+      code: 'COMPILE_SOURCE_NOT_FOUND',
+      details: { sourcePath },
+    });
   }
 
   const initialSourceCode = fs.readFileSync(sourcePath, 'utf-8');
@@ -35,7 +39,10 @@ async function run(args) {
     const buildResult = buildPageFile(sourcePath, { modern: compat, skipSizeWarning: true });
     if (!buildResult.ok) {
       buildResult.errors.forEach((issue) => warn(`${issue.code}: ${issue.message}`));
-      process.exit(1);
+      throwCommandError(t('build_page.failed'), {
+        code: 'COMPILE_BUILD_PAGE_FAILED',
+        details: { errors: buildResult.errors },
+      });
     }
     sourcePath = buildResult.outputPath;
     info(t('build_page.output', sourcePath));
@@ -46,7 +53,10 @@ async function run(args) {
     const sourceCode = fs.readFileSync(sourcePath, 'utf-8');
     const lintPassed = runLintCheck(sourceCode, sourcePath);
     if (!lintPassed) {
-      process.exit(1);
+      throwCommandError(t('check_page.failed'), {
+        code: 'COMPILE_LINT_FAILED',
+        details: { sourcePath },
+      });
     }
   } else {
     info(t('publish.lint_skipped'));

package/lib/app/create-app.js

@@ -17,6 +17,7 @@ const { createAuthRef } = require('../core/yida-client');
 const { t } = require('../core/i18n');
 const { buildYidaI18n, normalizeYidaLocale, resolveContentLocale } = require('../core/yida-i18n');
 const { parseOpenOption, withBrowserHandoff } = require('../core/browser-handoff');
+const { throwCommandError } = require('../core/command-errors');
 const { assertPresetThemeKey } = require('./theme-presets');
 
 const DEFAULT_APP_OPTIONS = {
@@ -370,7 +371,7 @@ async function run(args) {
     const errorMsg = response ? response.errorMsg || t('common.unknown_error') : t('common.request_failed');
     chalkResult(false, t('create_app.failed', errorMsg));
     console.log(JSON.stringify({ success: false, error: errorMsg }));
-    process.exit(1);
+    throwCommandError(errorMsg);
   }
 }
 

package/lib/app/create-form/api-path.js

@@ -0,0 +1,25 @@
+'use strict';
+
+/**
+ * create-form/api-path.js
+ *
+ * 接口路径生成：构建宜搭表单设计相关的 API 请求路径。
+ *
+ * @param {string} appType         应用标识（appType）
+ * @param {string} apiName         接口名称（不含扩展名），如 saveFormSchema
+ * @param {object} [options]       可选项
+ * @param {string} [options.prefix]        额外的路径前缀（会以 / 拼接）
+ * @param {string} [options.namespace]     命名空间，默认 dingtalk
+ * @param {boolean} [options.addTimestamp] 是否追加 _stamp 时间戳查询参数
+ * @returns {string} 拼接完成的 API 请求路径
+ */
+function buildApiPath(appType, apiName, options = {}) {
+  const { prefix = '', namespace = 'dingtalk', addTimestamp = false } = options;
+  const prefixPath = prefix ? `/${prefix}` : '';
+  const timestamp = addTimestamp ? `?_stamp=${Date.now()}` : '';
+  return `/${namespace}/web/${appType}${prefixPath}/query/formdesign/${apiName}.json${timestamp}`;
+}
+
+module.exports = {
+  buildApiPath,
+};

package/lib/app/create-form/commands.js

@@ -17,7 +17,11 @@ function dispatchCreateFormCommand(parsedArgs, authContext, handlers) {
     case 'add-option':
       return handlers.addOption(...args);
     case 'create':
+      return handlers.create(...args);
     default:
+      if (parsedArgs.mode && parsedArgs.mode !== 'create') {
+        throw new Error('Unknown create-form mode: ' + parsedArgs.mode);
+      }
       return handlers.create(...args);
   }
 }