What OpenYida Provides

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.

Quick Start

1. Install

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.

2. Check Your Environment

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

openyida env
openyida env --json
openyida commands --json

OpenYida detects the active agent environment, workspace path, login state, and organization context. Use --json when an agent needs a stable machine-readable snapshot. openyida commands --json emits the command manifest used by the CLI help, so agents can inspect available routes without scraping terminal output.

3. Log In

openyida login

In Codex, QoderWork, Qoder, Wukong, Claude Code, OpenCode, Cursor, and other detected AI tools, OpenYida first tries local Chrome/Edge/Chromium CDP when no valid cached login exists. If local CDP is unavailable, it falls back to an AI-dialog QR handoff. The agent should render qr_image_markdown or paste agent_response_markdown directly in the conversation so the QR code is visible, then run poll_command after the user scans it with DingTalk. If image rendering is unavailable, fall back to qr_url. The explicit openyida login --browser command still prefers CDP first and uses Playwright as an optional browser fallback.

The explicit QR polling command remains available:

openyida login --agent-qr

For terminal QR login, use:

openyida login --qr
openyida login --qr --corp-id dingxxxxxxxx
openyida login --check-only --json

OpenYida does not install Playwright by default.

4. Build With an AI Agent

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 Installation

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"

Supported AI Coding Tools

How It Works

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.

Project Layout

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
│   ├── 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

Capabilities

Application and Form Management

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 --all --output-dir .cache/schemas

Custom Page Development

openyida create-page APP_XXX "Dashboard" --mode dashboard
openyida generate-page product-homepage --spec .cache/openyida/page-specs/home.json --output pages/src/home.oyd.jsx --compile
openyida generate-page todo-mvc --output pages/src/todo-mvc.oyd.jsx --compile
openyida check-page pages/src/home.oyd.jsx
openyida compile pages/src/home.oyd.jsx
openyida publish pages/src/home.oyd.jsx APP_XXX FORM_XXX

generate-page turns a structured spec into a Page IR, renders a curated React 16-compatible template, writes a .openyida-page.json manifest, and optionally compiles the result. The manifest makes follow-up AI edits safer because agents can update known blocks instead of rewriting a large JSX file by hand. Built-in templates currently include product-homepage for product/portal pages and todo-mvc for a full interaction smoke page covering events, custom state, list rendering, editing, filtering, and localStorage persistence.

Workflow, Data, and Permissions

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.

Real Environment E2E

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 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. To inject CI cookies without relying on a local login cache, pass OPENYIDA_E2E_COOKIES_BASE64 as a base64 encoded cookie array or { "cookies": [...] } object.

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.

Connectors, Integrations, and Reports

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

CLI Reference

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

Auth & Environment

App Management

Forms & Pages

Data & Permissions

Process

Page Config & Sharing

Reports

Connectors

Integration & DingTalk

Utility

CLI Notes

Environment and Localization

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.

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.

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.

Data, Permissions, and Sharing

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.

Workflow, Reports, and Integrations

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,...>.

Agent Skills

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.

Examples

Business Systems: IPD and CRM

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

Custom Pages and Utilities

Interactive Campaigns

Common Prompts

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.

OpenClaw Integration

Use OpenYida through yida-app in OpenClaw:

npx clawhub@latest install nicky1108/yida-app

Development

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.

Security and Configuration

• Login cookies 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 authenticated cookies.
• For multi-organization accounts, prefer explicit --corp-id values in non-interactive automation.

Community

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

Contributors

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

Latest contributors: DDlixin1, fcloud.

License

MIT © 2026 Alibaba Group Holding Limited