OpenXiangda

OpenXiangda is a lightweight CLI and skill package for private low-code platforms.

It uses normal platform user login tokens through /openxiangda-api/v1; it does not use AK/SK.

Private platform routing is fixed: backend APIs are under /service, platform management is under /platform, and app runtime access is under /view. Passing a root domain such as https://yida.wisejob.cn/ to the CLI is supported; OpenXiangda stores the API base as https://yida.wisejob.cn/service.

npm install -g openxiangda@latest --registry=https://registry.npmjs.org
openxiangda update check
openxiangda skill install

# during local development:
npm link

openxiangda skill status
openxiangda platform add dev https://dev-lowcode.example.com
openxiangda login --profile dev
openxiangda env
openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
cd ./my-app-workspace
pnpm install
openxiangda workspace publish --profile dev
openxiangda menu list --profile dev
openxiangda workflow list --profile dev
openxiangda automation list --profile dev
openxiangda automation executions daily_ticket_digest --profile dev
openxiangda automation diagnose daily_ticket_digest --profile dev
openxiangda permission role-list --profile dev
openxiangda settings get customer --profile dev
openxiangda data-view list --profile dev
openxiangda data-view status ticket_with_customer --profile dev
openxiangda resource validate --profile dev
openxiangda resource plan --profile dev
openxiangda resource publish --profile dev
openxiangda inspect app --profile dev --json
openxiangda app snapshot APP_XXXX --profile dev --json

User tokens are stored in ~/.openxiangda/profiles.json with 0600 permissions. Shared workspace environment values, including APP_OSS_*, can live in ~/.openxiangda/.env and are inherited by new workspaces. Project .env files still work and override the global defaults. Project state is stored in .openxiangda/state.json and contains only profile-specific resource IDs.

Feedback can be sent to a DingTalk custom robot from the CLI. AI agents should proactively report platform defects, missing capabilities, unclear design rules, repeated workarounds, implementation uncertainty, and user-visible UX gaps during development. Store the robot settings in ~/.openxiangda/.env, not in project files:

OPENXIANGDA_FEEDBACK_DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=...
OPENXIANGDA_FEEDBACK_DINGTALK_SECRET=SEC...

Submit directly when the report is clear; use preview when robot env is missing or you need to inspect the sanitized payload:

openxiangda feedback preview --profile dev --summary "发布后资源 404" --description "..."
openxiangda feedback submit --profile dev --summary "发布后资源 404" --description "..." --yes

Feedback messages include the logged-in user's name when available, profile/platform/app binding, workspace path, Git branch/commit, CLI/Node/OS versions, OSS bucket metadata, command, error text, logs, and optional context files. Token, cookie, secret, access key secret, phone, and email patterns are redacted before sending.

Use the official npm registry for OpenXiangda updates:

npm install -g openxiangda@latest --registry=https://registry.npmjs.org
openxiangda update check --json
openxiangda update install

Domestic npm mirrors may lag and return an older OpenXiangda version. openxiangda update check --json is designed for AI agents: it returns the installed version, latest official npm version, whether an update is available, and the compatibility commands to run after updating. openxiangda update install installs from the official registry and refreshes OpenXiangda skills by default.

Codex skills are installed separately from login/profile state. Run openxiangda skill install after installing or linking the CLI. It installs the openxiangda root skill plus the 7 top-level subskills into ${CODEX_HOME:-~/.codex}/skills by default:

• openxiangda
• openxiangda-core
• openxiangda-app
• openxiangda-form
• openxiangda-page
• openxiangda-workflow-automation
• openxiangda-permission-settings
• openxiangda-inspect

Use openxiangda skill install --dest <skills-dir> to target a different Codex skills directory. If a same-name skill exists but was not installed by OpenXiangda, the command refuses to overwrite it unless --force is provided. Restart Codex after installing skills.

For existing app workspaces created before AGENTS.md / .qoder/rules/ / .cursor/rules/ / scripts/guard-publish.mjs / package.json _guard:publish were added, run:

openxiangda skill bootstrap                 # current dir, dry-run by default? no — write
openxiangda skill bootstrap --dry-run --json # preview
openxiangda skill bootstrap --force          # overwrite drifted local copies

It copies the AI-guidance bundle (AGENTS.md, Qoder/Cursor always-on + glob rules, the publish guard script) and patches package.json with the _guard:publish script plus prepublish:all / prepublish:oss / preregister / preregister-bundle / prepublish:changed / preopenxiangda:publish hooks so that direct pnpm publish:all / pnpm publish:oss / pnpm register calls fail-fast unless invoked through openxiangda workspace publish ....

Create a new publishable app workspace with openxiangda workspace init <dir>. The command writes a minimal sy-lowcode-app-workspace template with React, Ant Design, the single openxiangda package, and the required publish:all / openxiangda:publish scripts. Use --install to run pnpm install immediately, or run it manually after creation.

New OpenXiangda code pages and form custom pages publish with cssIsolation: "none" by default, so Tailwind utilities and normal Ant Design styles apply without a .sy-app-workspace prefix. Explicit namespace and shadow settings are kept only for legacy compatibility.

OpenXiangda workspaces include a lightweight runtime preview for new user pages. /view remains the user-facing URL prefix, but local development does not enter the legacy sy-lowcode-view workbench checks; the Vite dev host mounts src/pages/* directly and sends SDK requests through the configured service proxy.

OPENXIANGDA_BASE_URL=https://dev-lowcode.example.com
OPENXIANGDA_APP_TYPE=APP_XXXX
OPENXIANGDA_DEV_HOST=myapp.local
OPENXIANGDA_DEV_PORT=5174
APP_SERVICE_PREFIX=/service

npm run dev

When OPENXIANGDA_BASE_URL or APP_PLATFORM_URL is set, the workspace Vite server proxies /service/* to the platform backend with changeOrigin, cookieDomainRewrite: "", and cookiePathRewrite: "/". This keeps local browser requests same-origin and lets HttpOnly access_token / refresh_token cookies be saved on the local dev domain.

The dev host also calls the backend runtime route resolver for the current /view/... URL. Workbench code-page routes select and mount the matching local src/pages/<page>/index.tsx; built-in routes such as form submit, detail, process detail, data list, and file preview render the SDK default pages directly instead of accidentally mounting the first local page.

Built-in route defaults come from the openxiangda SDK: StandardFormPage, FormSubmitTemplate, FormDetailTemplate, ProcessDetailTemplate, and DataManagementList. Workspaces can override whole built-in pages from src/runtime/builtin-overrides.tsx; exact formUuid entries win before the * fallback.

import type { BuiltinRouteOverrides } from "openxiangda/runtime"

export const runtimeRouteOverrides: BuiltinRouteOverrides = {
  "form-submit": {
    customer: CustomerSubmitPage,
    "*": SubmitShell,
  },
  "form-detail": {},
  "process-detail": {},
  "data-manage-list": {},
}

AI / Playwright verification should use real user identity, not a bypass mode. The backend exposes POST /openxiangda-api/v1/apps/:appType/verification-login-links for platform admins to create a short-lived, single-use loginUrl for a target user and redirect URI. Playwright can open the returned URL directly; the backend writes cookies and redirects back to the local or tenant /view/... page. Test users can be created with POST /openxiangda-api/v1/apps/:appType/test-users; they use the __ox_ai_test__:<appType>:<key> ID prefix and are intended to be used through verification login links.

An independent production user shell can call resolveBrowserRuntimeRoute() from openxiangda/runtime first. It posts the current /view/... path to /openxiangda-api/v1/apps/:appType/runtime/routes/resolve; the backend classifies the route as custom-page, builtin-route, legacy-fallback, or not-found. Code pages return backend-authorized bootstrap data directly, so the shell can pass that to mountBrowserPageRuntime() or mount with createBrowserPageContext() without reusing the legacy view workbench logic. Built-in routes can be rendered with BuiltinRouteRenderer, which loads form schema through the same /service proxy and keeps backend permission checks authoritative.

import { resolveBrowserRuntimeRoute } from "openxiangda/runtime"

const route = await resolveBrowserRuntimeRoute({
  appType: "APP_XXXX",
  path: window.location.pathname,
  search: window.location.search,
})

Local workspace state is authoritative. If the current folder has no .openxiangda/state.json app binding, create a new app instead of searching the platform for a similar app name:

openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"

Bind to an existing app only when the user explicitly provides an appType or asks to reuse an existing platform app:

openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
openxiangda workspace bind --profile dev --app-type APP_XXXX

表单页、流程表单页和自定义代码页都应在 sy-lowcode-app-workspace 中实现，由 openxiangda workspace publish --profile <name> 统一构建、上传 OSS 并注册到平台。openxiangda form create、form publish、page publish 只作为底层修复/诊断命令，不作为 AI 生成页面的主入口。

运行时页面读取当前用户信息时，优先使用 sdk.user.getCurrent<PageUserRecord>()。用户对象会返回常规组织成员关系 departments，也会返回系统维护的所属单位字段 affiliatedDepartmentId / affiliatedDepartment。departments 表示用户真实所在的部门、班级、专业等成员关系；affiliatedDepartment 表示业务上用于统计、筛选和展示的归属单位，通常是学院、单位或在源单位缺失时可用的具体部门节点，不用于替代权限部门成员关系。

import type { PageUserRecord } from "openxiangda/runtime"

const currentUser = await sdk.user.getCurrent<PageUserRecord>()
const user = currentUser.result

const affiliatedDepartmentName = user?.affiliatedDepartment?.name
const affiliatedDepartmentExternalId = user?.affiliatedDepartment?.externalId

工程化资源放在工作区 src/resources/ 下，由 openxiangda resource validate|plan|publish|pull 管理。workspace publish 会先构建并注册 workspace 表单/页面，再执行非破坏性资源 upsert，这样菜单、权限组、流程和表单设置可以解析最新的 profile-local ID。需要删除平台中 manifest 未声明的资源时，显式传 --prune。连接器页面运行时通过 sdk.connector.invoke() / sdk.connector.call("connector.api") 调用平台运行时接口，第三方密钥只保存在后端连接器配置中。

多表只读查询和固定口径统计优先声明 src/resources/data-views/*.json 数据视图，而不是在页面里手写多次单表查询再拼数据。默认数据视图是行级联表视图，适合工单+客户、订单+商品、项目+成员、报表列表、跨页面复用查询等读多写少场景；viewType: "aggregate" 是统计聚合视图，适合按客户、状态、月份等维度预聚合 count/sum/avg/min/max。发布时 CLI 会把 formCode 解析为当前 profile 的 formUuid，平台创建 PostgreSQL materialized view；页面通过 sdk.dataView.query(code, params) 查询行级视图，通过 sdk.dataView.stats(code, params) 查询聚合视图，也可以用 sdk.dataSource.run() 路由 dataView.query / dataView.stats。发布前应为常用筛选、排序、统计维度和时间桶声明 indexes，并确认用户能接受的刷新延迟；默认不要设置低于 5 分钟的定时刷新。数据视图只读，刷新后才反映源表变化，不适合单表 CRUD、写回源表、强实时状态、临时 BI 查询或简单 linkedForm 下拉。

常用数据视图命令：

openxiangda resource validate --profile dev
openxiangda resource plan --profile dev
openxiangda resource publish --profile dev
openxiangda data-view list --profile dev
openxiangda data-view status ticket_with_customer --profile dev
openxiangda data-view refresh ticket_with_customer --profile dev
openxiangda data-view query ticket_with_customer --query-json query.json --profile dev
openxiangda data-view stats ticket_stats_by_customer --query-json stats-query.json --profile dev

AI-authored automation can use code-first resources:

• Source: src/automations/<resourceCode>/index.ts
• Definition: src/resources/automations/<resourceCode>/definition.code.json
• Preview: src/resources/automations/<resourceCode>/preview.json
• Logs: openxiangda automation executions|logs|diagnose

AI-authored workflows can use compile-time SDK resources:

• Source: src/workflows/<resourceCode>/workflow.ts
• Manifest: src/resources/workflows/<resourceCode>/workflow.json
• Compiled graph: definition.v3.json
• Read-only preview: preview.json

Resource and connector manifest guide: docs/openxiangda-resources-and-connectors.md.

Skill migration plan: docs/skill-refactor-plan.md.