OpenYida is a bridge between AI coding tools and Yida. It gives agents a stable command-line interface for the full application lifecycle:

The result remains a native Yida application: teams can continue editing it in Yida, use existing enterprise security controls, and deploy through the Yida platform.

npm install -g openyida

OpenYida requires Node.js 18 or later. The package exposes both openyida and yida commands.

If Codex is already installed, OpenYida also imports a local Codex plugin during postinstall. Restart Codex after installation, then type @宜搭 or @openyida in the composer to attach the OpenYida context.

Run this from the AI coding workspace where you want OpenYida to operate:

openyida agent-capabilities --summary-json

OpenYida returns a compact machine-readable summary with the version, login state, workspace/cache paths, and command manifest digest. openyida agent-capabilities --json is the full diagnostic snapshot, where compact workdir maps to active.projectRoot and workdir_exists maps to active.projectRootExists. openyida commands --json remains available when an agent only needs the command manifest.

openyida login

OpenYida login defaults to OAuth token mode. It opens the DingTalk OAuth authorization page, receives the local loopback callback, exchanges code / authCode with the Yida server, and stores access_token / refresh_token in the current project cache.

When the user names a target Yida entry URL, pass it to the login command so OpenYida can select the matching environment and token session file. For example, Alibaba intranet Yida uses auth-token-alibaba.json:

openyida login https://yida-group.alibaba-inc.com/
openyida login --alibaba

For token status checks, use:

openyida login --check-only --json
openyida auth status

OpenYida does not install Playwright by default.

Ask your coding agent for a concrete Yida application or workflow:

Create a CRM application in Yida with customer, contact, opportunity, and follow-up forms.
Build an IPD workflow for chip production, including approval nodes and dashboard pages.
Generate a public landing page and publish it to my Yida app.

The agent can then call OpenYida commands to create the application, generate source files, publish pages, and return the final Yida URLs. In Codex, QoderWork, Qoder, and Wukong environments, successful creation and publish commands also include a browser handoff so the agent can open the resulting Yida page in the in-app browser. Use --open to force this handoff or --no-open to suppress it.

Wukong uses manual skill package installation instead of npm:

1. Download the latest .zip skill package from GitHub Releases.
2. Open Wukong.
3. Go to Skill Center > Upload Skill and select the downloaded package.

For Wukong terminal work, make sure its bundled Node.js path is active before running node, npm, or npx commands:

export PATH="$HOME/.real/.bin/node/bin:$PATH"

flowchart LR
  A["AI coding agent"] --> B["OpenYida CLI"]
  B --> C["Environment detection"]
  B --> D["Login and organization context"]
  B --> E["Yida API operations"]
  B --> F["Local page generation and compile"]
  E --> G["Native Yida app"]
  F --> G

OpenYida keeps platform-specific behavior inside the CLI, while agents interact with predictable commands and project files.

openyida/
├── bin/yida.js                 # CLI entry and command routing
├── lib/
│   ├── app/                    # Application, form, page, import/export commands
│   ├── 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
│   ├── report/                 # Yida report and chart generation
│   └── samples/                # Templates emitted by openyida sample
├── project/                    # Default workspace template for generated Yida projects
├── yida-skills/                # Source skill docs and Yida API references
└── scripts/                    # CI, packaging, and installation helpers

For a user-facing list of supported features and matching CLI commands, see OpenYida 功能完整列表.

openyida create-app "CRM"
openyida create-app --name "CRM" --desc "Customer management" --theme deepBlue
openyida app-list --size 20
openyida corp-efficiency
openyida create-form create APP_XXX "Customer" .cache/openyida/forms/customer-fields.json
openyida create-form update APP_XXX FORM_XXX .cache/openyida/forms/customer-changes.json
openyida get-schema APP_XXX FORM_XXX
openyida get-schema APP_XXX FORM_XXX --compact --resolve-fields "Customer Name,Status"
openyida get-schema APP_XXX --all --output-dir .cache/schemas

Form definitions support 19 business field types plus verified @ali/vc-deep-yida presentation/layout components. Prefer Divider for section titles and ColumnContainer (mapped to ColumnsLayout + Column) for multi-column layout; use GroupContainer / PageSection only when an actual grouping container is needed.

openyida create-page APP_XXX "Dashboard" --mode dashboard
openyida generate-page product-homepage --scene workbench --theme-profile yida-app-theme --theme-scope page --spec .cache/openyida/page-specs/home.json --output pages/src/home.canvas.jsx --compile
openyida generate-page official-homepage --theme-profile yida-app-theme --spec .cache/openyida/page-specs/official-home.json --resolve-assets --upload-assets --output pages/src/official-home.canvas.jsx --compile
openyida generate-page data-screen --theme-profile yida-app-theme --output pages/src/data-screen.canvas.jsx --compile
openyida generate-page split-pane-detail --theme-profile yida-app-theme --output pages/src/split-pane-detail.canvas.jsx --compile
openyida generate-page portal-shell-home --theme-profile yida-app-theme --output pages/src/portal-shell-home.canvas.jsx --compile
openyida sample yida-canvas-custom-page dashboard-starter --output pages/src/dashboard-starter.canvas.jsx
openyida sample yida-canvas-custom-page native-components-smoke --output pages/src/native-components-smoke.canvas.jsx
openyida sample yida-canvas-custom-page portal-native-components --output pages/src/portal-native-components.canvas.jsx
openyida generate-page todo-mvc --output pages/src/todo-mvc.canvas.jsx --compile
openyida publish pages/src/home.canvas.jsx APP_XXX FORM_XXX

generate-page turns a structured spec into a Page IR, renders a curated template, writes a .openyida-page.json manifest, and optionally compiles the result. Code Canvas is the default output (.canvas.jsx); pass --native or output .oyd.jsx only when the page must use the 普通自定义页面 JSX/Jsx 组件链路. Pass --scene workbench|dashboard|list|detail|landing|screen and --theme-profile <name-or-json> / --visual-profile <name-or-json> to preserve the visual direction decision in both source comments and the manifest. The user-facing default theme profile is yida-app-theme, which follows Yida application theme styling, compact business density, and layered 12/8/6/4 radii. --theme-scope page only injects theme variables into the generated page root; --theme-scope app additionally calls window.__YIDA__.updateShellConfig({ themeConfig }) so the application shell can adopt the same theme. Landing pages should declare spec.assets.heroImage / productImages; use --resolve-assets to verify public image URLs and --upload-assets to mirror local or verified external images to CDN when CDN is configured. Use --offline-assets only for draft/offline gating. The manifest makes follow-up AI edits safer because agents can update known blocks and visual constraints instead of rewriting a large JSX file by hand. Built-in templates currently include official-homepage for brand/law-firm/product official sites, data-screen for immersive monitoring screens, dashboard-overview for business dashboards, workbench-home for task/entry workbenches, business-list for list management pages, detail-profile for single-object detail pages, split-pane-detail for left-list/right-detail processing consoles, portal-shell-home for in-page portal shells, native-components-smoke for runtime probing existing Yida host components without changing vc-deep-yida, portal-native-components for runtime-bridged portal, member, department, and upload components, product-homepage for legacy workbench-style pages, and todo-mvc for a full interaction smoke page covering events, custom state, list rendering, editing, filtering, and localStorage persistence.

For member, department, attachment, and image upload components, choose the page chain first. Code Canvas pages should start with native-components-smoke or portal-native-components and follow yida-canvas-custom-page/references/native-components-bridge.md for feature detection, fallback, and value normalization. 普通自定义页面 JSX/Jsx pages should use .oyd.jsx, read yida-custom-page/references/component-jsx-guide.md, and read attachment-upload-guide.md when upload fields are involved.

openyida create-process APP_XXX "Purchase Request" .cache/openyida/process/fields.json .cache/openyida/process/process.json
openyida configure-process APP_XXX FORM_XXX .cache/openyida/process/process.json
openyida process preview APP_XXX PROC_INST_XXX --output .cache/openyida/process/process.html
openyida data query form APP_XXX FORM_XXX --page 1 --size 20
openyida data create form APP_XXX FORM_XXX --data-file .cache/openyida/data-import/record.json
openyida get-permission APP_XXX FORM_XXX

configure-process 的流程 JSON 中，审批人可配置为发起人、指定成员、指定角色、部门主管或直属主管，例如：

{
  "nodes": [
    {
      "type": "approval",
      "name": "主管审批",
      "approver": {
        "type": "user",
        "users": [{ "id": "manager7350", "name": "九神" }],
        "multiApproverType": "all"
      }
    }
  ]
}

When creating or updating test data with openyida data, Yida date fields must use 13-digit millisecond timestamps, for example "dateField_xxx": 1719705600000. Do not submit YYYY-MM-DD strings for DateField or CascadeDateField values. Temporary JSON, CSV, and one-off import scripts should live under .cache/openyida/ so generated run artifacts do not clutter the repository root.

Most checks should stay offline, but OpenYida also includes an explicit real-environment smoke path for release and nightly validation:

OPENYIDA_E2E=1 npm run test:e2e:real
OPENYIDA_E2E=1 npm run test:e2e:real:full
OPENYIDA_E2E=1 OPENYIDA_E2E_FULL_STAGES=auth,app,form,process npm run test:e2e:real:full
npm run test:e2e:real:skills

The runner creates a disposable app, form, and custom page with an OY_E2E_* prefix, then verifies token login, app listing, schema fetch, data query, and page publish. It writes a registry to project/.cache/e2e-real/ so created resources can be audited later. Run openyida login for the target environment before starting the real E2E runner.

test:e2e:real:full extends the smoke path into a broad deterministic feature matrix: auth/env, app update, form update and option mutation, page build/compile/generate/publish, data create/get/update/query, permission read, page config and short URL check, report create/append, dashboard skill verification, export/import, batch, task-center, formula/doctor/sample/CDN config, and local connector parsing/template generation. AI-backed commands such as flash-to-prd are available as the optional ai stage because they depend on remote model availability. Workflow mutation is available as the opt-in process stage; it creates and republishes a workflow on the disposable E2E form and records advanced official-node fixtures for review.

test:e2e:real:skills enforces coverage for every directory under yida-skills/skills/. Each skill must be classified as real E2E, offline/unit, opt-in, or deprecated with an explicit reason. This prevents new skills from quietly bypassing the real-environment test plan.

Each successful full run leaves a human-inspectable result app in the target organization. The final step publishes a dedicated Full E2E Dashboard custom page, renames the app to OY_E2E_*_PASSED by default, and prints direct links for the app, form, dashboard page, and report; the same links are saved under resultApp in the registry JSON.

Useful options:

Use npm run test:e2e:real:cleanup to list recorded disposable resources. OpenYida does not yet expose a safe app/form deletion command, so cleanup is intentionally a registry-backed audit step rather than an automatic destructive action.

The E2E paths above prove the CLI works. The eval harness under scripts/eval/ measures whether the agent still routes natural-language requests to the right sub-skill and produces good output after you edit yida-skills/SKILL.md. It is the feedback loop for harness engineering.

# Routing eval — "did it pick the right sub-skill?" No real resources, no login.
# Drives a headless `claude -p` agent with each scenario prompt and checks
# 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
# a control that proves the build→publish→screenshot→score plumbing itself works.
# Requires OPENYIDA_E2E=1 and a valid token session.
OPENYIDA_E2E=1 npm run eval:e2e -- --skill yida-dashboard --screenshot

# Same, plus automatic screenshot scoring via the local multimodal `claude -p`.
OPENYIDA_E2E=1 npm run eval:e2e -- --skill yida-dashboard --screenshot --auto-score

# Real-generation eval — "can one sentence really build a usable app?" Feeds a
# natural-language request ("帮我创建一个订单管理系统") to a headless `claude -p`
# that actually reads the openyida skill and runs the CLI to build a real app, then
# reuses the screenshot + scoring + report pipeline. Creates real 宜搭 resources, so
# it needs OPENYIDA_E2E=1 + an authenticated agent. Unlike the deterministic baseline
# above, here the agent self-orchestrates.
OPENYIDA_E2E=1 npm run eval:generate -- --screenshot

# Run all three in one pass (routing + tool-pipeline baseline + real generation).
OPENYIDA_E2E=1 npm run eval:all -- --skill yida-dashboard --screenshot

# Optional: a zero-dependency local web console (buttons + live streamed output)
# 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.

Results are written back into the existing acceptance-manifest.json under a new eval section (guardrails, screenshots, scores) plus two sibling artifacts: a scoring.md human-scoring template and a self-contained eval-report.html visual report (screenshots inlined as base64, so the single file opens anywhere). Routing results land in project/.cache/eval/routing-report.json; generation results (with their own scoring.md + eval-report.html) land in project/.cache/eval/generate/gen-<timestamp>/. The harness degrades gracefully: a missing Playwright skips screenshots (enable with npm install --no-save playwright && npx playwright install chromium), and a missing claude CLI skips auto-scoring while keeping the human template. A guardrail failure (for example a resource-creating command issued before a successful login --check-only) fails the run.

A zero-dependency local dashboard (npm run eval:dashboard, then open http://127.0.0.1:4500) drives these runs from buttons and streams output live; its "📊 查看最新报告" button opens the most recent eval-report.html.

openyida connector smart-create --curl "curl https://api.example.com/users"
openyida connector list
openyida integration create APP_XXX FORM_XXX "Sync customer data"
openyida integration create APP_XXX FORM_XXX "Approval result notify" \
  --events processFinish --approval-actions agree,disagree --receivers 123456
openyida create-report APP_XXX "Sales Dashboard" .cache/openyida/reports/charts.json
openyida append-chart APP_XXX REPORT_XXX .cache/openyida/reports/chart.json

Run openyida --help or openyida <command> --help for detailed usage.

openyida asset resolve --hero <path-or-url> --product <path-or-url> --require-hero --upload-assets --json is the preferred preflight for homepage visuals. It verifies public image URLs, uploads local images when CDN is configured, mirrors verified external images to CDN when --upload-assets is passed, and returns materialStatus: final|draft|none so agents do not claim an unfinished visual page is final.

Environment selectors such as --env intl, --intl, --overseas, --global, and --yidaapps can be used on login-required commands to choose the target Yida environment for that run. The intl preset uses https://www.yidaapps.com as the built-in Global YiDA entrypoint (not the bare https://yidaapps.com domain) and DingTalk International OAuth at https://login.dingtalk.io; business API requests still use the authenticated environment baseUrl, so customer custom subdomains are supported.

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.

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.

openyida publish preserves existing custom page data sources by default. Before saving the new compiled JSX Schema, it reads the current page Schema and merges the Page-level dataSource with the built-in urlParams and timestamp sources, so manually configured data sources are not deleted during republish.

openyida externalize-form is useful when a form contains fields such as AssociationFormField, EmployeeField, or DepartmentSelectField that depend on internal organization permissions. It produces a report plus optional --mirror-fields-output JSON that can be used with openyida create-form create to build a separate public intake form while keeping the internal form and its association fields private.

openyida integration create supports form events (insert, update, delete, comment) and approval events (processFinish, activityTask; aliases: approval, approvalNode). Approval events require --approval-actions agree,disagree,terminated; activityTask also requires --approval-node-ids <nodeId,...>.

The yida-skills/ directory is the source skill library used by OpenYida during development. Release assets for Wukong are generated by npm run build:skills: the expanded package is written to dist/skills/openyida/, and the upload-ready zip is written to openyida-skills.zip.

When OpenYida is used inside a supported AI coding environment, these skills help the agent choose the right command sequence and file conventions.

For Wukong manual import, upload the generated openyida-skills.zip. The package follows Wukong's custom skill rules: folder name and frontmatter.name are both openyida, root frontmatter only contains name and description, and long references live under references/.

For Codex, npm install -g openyida additionally creates a local plugin marketplace under ~/.openyida/codex-plugin and enables openyida@openyida in ~/.codex/config.toml when Codex is detected. This makes OpenYida show up in Codex's @ plugin menu as 宜搭 after Codex reloads.

Describe your requirements in one sentence; the agent can create a complete multi-form Yida application.

Build a Yida application for [business scenario].
Generate an app from this requirements document.
Create a [name] form page with these fields.
Add a required [field type] field named [field name] to [form name].
Publish this custom page to the Yida app.
Make this page publicly accessible.
Export the application as a migration package.

Use OpenYida through yida-app in OpenClaw:

npx clawhub@latest install nicky1108/yida-app

git clone https://github.com/openyida/openyida.git
cd openyida
npm install
npm run check:ci

Useful checks:

When adding new CLI commands, register the route in bin/yida.js, add it to lib/core/command-manifest.js, regenerate the README command index with npm run docs:commands, and keep agent skills in yida-skills/ aligned when the workflow changes. npm run check:commands fails if the router, manifest, or README drift apart.

• OAuth token sessions are cached locally and should never be hard-coded into source files.
• Private deployment environments are managed through lib/core/env-manager.js.
• Yida API requests should use the active environment base URL and Bearer token auth.
• For multi-organization accounts, prefer explicit --corp-id values in non-interactive automation.

Scan the QR code to join the OpenYida DingTalk user group for updates and support.

Thanks to everyone who has contributed to OpenYida. Read the Contributing Guide to get involved.

Latest contributors: DDlixin1, fcloud.

MIT © 2026 Alibaba Group Holding Limited