kwc-project-scaffold

KWC Project Scaffold

Use this Skill as the entry point for KWC project scaffolding work. Prioritize categorizing user requirements into the following types: initialize project, create component, create Controller, create page metadata, configure environment, deploy, view environment results, debug.

Correctly understand the delivery target

Do not understand the KWC workflow as "rendering a component locally". The core delivery targets of KWC are:

The component project itself (frontend code + component metadata .js-meta.kwc）
page metadata *.page-meta.kwp
KS Controller metadata *.kws and script code (when the functionality involves backend data interaction)
Target environment configuration and authentication
Through kd project deploy the environment rendering result after upload

The final page display depends on the <controls> in the page metadata and the component type mapping, not on whether the local main.tsx has mounted a certain component. main.tsx和npm run dev` is only used for local auxiliary preview, not the final delivery path.

KWC is not only a frontend development framework. When a page needs to read or operate on business data, KS Controller provides backend REST API capabilities, accessing data queries, business operations, and other services of the Cangqiong platform through KingScript scripts. A complete business function usually consists of two parts: a frontend component (display and interaction) and a backend Controller (data retrieval and business logic).

Controller also follows the "metadata + code" dual model:

Controller metadata (.kws): defines declarative configurations such as route URL, HTTP method, permission policy, etc.
Controller script code (.ts): implements the specific business logic

This is completely symmetrical with the frontend's "component metadata .kwc + component code" pattern.

Metadata-driven full-stack development model

From the user's development perspective, a complete KWC feature covers at most the following layers:

Frontend (display and interaction):

Component code (*.tsx / *.vue / *.js): responsible for rendering and interaction logic
Component metadata .js-meta.kwc: declares "how this component can be referenced by pages and which configurable properties it can expose"
Page metadata .page-meta.kwp: declares "which component instances this page consists of, and what property values are passed to each instance"

Backend (data and business logic): 4. Controller metadata .kws: declares "which API endpoints this Controller exposes, what HTTP methods are used, and what permissions are required" 5. Controller script code (*.ts): implements specific backend logic such as data queries and business operations

Both frontend and backend follow the pattern of "metadata first, code implementation follows"—first declare the structure and contract, then fill in the implementation.

Therefore, when facing requirements, do not only ask "how many components need to be written"; also continue to determine:

Which parameters are hardcoded in the component code
Which parameters need to be exposed to page configurators, defined as <property>
Which component instances will appear in the <controls> of the page metadata
Whether the component needs to call backend APIs to fetch data or submit operations
If needed, which API endpoints (URL, HTTP method, permissions) need to be defined in the Controller metadata (.kws)
Which SDK capabilities (data queries, business operations, etc.) the Controller script needs to call

Default principles:

Implementation details that can be fixed inside the component should not be exposed to metadata
Only parameters that need to be assembled, reused, and configured by the page enter the component metadata and page metadata

First translate the requirements into engineering goals

When facing a request to "help me develop a KWC page/feature", first translate the requirements into the following items:

Whether a new project needs to be created, or development should continue in an existing project
How many components are needed, and what responsibilities each one bears
Do the components need backend data support? If so, plan the corresponding KS Controller and API methods
How many page metadata files are needed, and how the components are combined in the page
Which environment it will ultimately be deployed to

Only after these items are completed does the scaffolding command have a clear target.

Framework development Skill collaboration

Treat kwc-project-scaffold as the overall entry point for the KWC workflow, but do not let it swallow the responsibilities of the framework development Skill.

Hard constraints: code implementation must be handed over to the framework Skill

When a task enters the "implement component code" stage, the following mandatory rules must be followed:

Writing code directly is prohibited: This Skill is strictly prohibited from directly writing or modifying any component implementation code (*.tsx / *.vue / .js) and Controller script code (.ts）
The corresponding Skill must be loaded first: Frontend code loads the framework development Skill (kwc-react/vue/lwc-development), Controller code loads kwc-ks-controller-development
Writing on your own based on general knowledge is prohibited: The request/response APIs of the KingScript runtime are completely different from Node.js / Java Servlet; code written based on general experience will fail to deploy
Multi-stage tasks are not an exception: Even if the current task involves multiple stages such as project setup + metadata + Controller + frontend components, the Skill must be switched every time a code-writing stage is entered, and it must not be skipped "in one go"
Basis for framework identification：
- New project: based on the kd project init the framework selected by the user at that time
- Existing project: based on the .kd/config.json in framework field
- If the framework cannot be identified, you must stop and confirm with the user; guessing is prohibited

Collaboration boundary table

Task stage	Responsible Skill	Deliverable
Project initialization	scaffold	.kd/config.json
Create component directory	scaffold	app/kwc/Component/
Write component code	react/vue/lwc-development	**.tsx / .vue / .js*
Complete component metadata	scaffold	*.js-meta.kwc
Create page metadata	scaffold	*.page-meta.kwp
Environment configuration and deployment	scaffold	Environment rendering result
Create Controller directory	scaffold	app/ks/controller/ControllerName/
Complete Controller metadata	scaffold	*.kws (URL, method, permission configuration)
Build Controller	scaffold	dist/controller/
Write Controller script code	kwc-ks-controller-development	.ts script (business logic implementation)

Switching timing

When the task is still in the requirements breakdown, scaffold command, metadata, environment,deploy、open、debug stage, this Skill continues to lead
When kd project create is completed and code needs to be written → must switch to the framework Skill; this Skill is prohibited from writing directly
When the code is written and metadata needs to be supplemented or deployment is needed → return to scaffold
When the Controller directory has been created and script code needs to be written → must switch to kwc-ks-controller-development, this Skill is prohibited from writing directly
When the Controller script code is written and building or deployment is needed → return to scaffold

Exception flow protection

When a CLI command fails (e.g., kd project create reports an error) and files/directories are created manually instead, the Skill switching rules for the code writing phasealso apply. Manually creating the directory structure does not mean business code may be written manually.

As long as writing of the .ts / .tsx / .vue / .js file is entered, regardless of whether the preceding steps were completed via CLI, youmust first switch to the corresponding framework Skill
Typical scenario:kd project create fails → manually create the app/kwc/MyComponent/ directory and .js-meta.kwc → up to here it is still scaffold's responsibility → when starting to write MyComponent.tsx → must switch to the framework Skill
The same applies to Controller: manually create the app/ks/controller/ directory and .kws → scaffold's responsibility → start writing the .ts script → must switch to kwc-ks-controller-development

Framework Skill activation checklist

Before entering the code implementation phase, confirm the following:

The current project framework (react/vue/lwc) has been identified
The corresponding framework development Skill (kwc-*-development) has been invoked
The rule.md constraints of the framework Skill have been loaded and are in effect
This Skill no longer directly handles the content of any code file

Recommended rules

If it is a new project, use the framework selected by the user in the kd project init interaction as the basis for the subsequently recommended Skill
If it is an existing project, use the .kd/config.json in framework as the basis for the recommended Skill
When framework=react ,mustswitch to kwc-react-development
When framework=vue ,mustswitch to kwc-vue-development
When framework=lwc ,mustswitch to kwc-lwc-development
If the framework still cannot be determined, stop first and confirm with the user
When the task involves writing Controller/script controller code,mustswitch to kwc-ks-controller-development
Controller code implementation is unrelated to the frontend framework and is not affected by the framework field

Note: do not load three framework development Skills at the same time; recommend only one based on the current project's framework.

Inputs that need to be provided or confirmed by the user

If these inputs cannot be inferred from the existing project or context, they must be confirmed with the user:

Project name or existing project path
Framework and language
Cangqiong application code app
Target environment alias and URL
Authentication method, and the real parameters required by OpenAPI
Page identifier, e.g., page name, and the business page purpose
Which components need to be exposed for use by the page, and which are only internal logic components
Which parameters need to be made into configurable properties
If the user already has an environment, whether it is allowed to deploy directly to that environment

Do not fabricate this information on your own, especially app, environment URL, authentication parameters, and the final deployment environment.

Regarding isv(developer identifier): during the development phase it can be left blank; when the component is bound to an environment, the developer identifier will be pulled from the environment,kd project deploy it will be automatically written into the component and page metadata, so the user does not need to provide or maintain it manually.

For app use the strictest rules (this section is the sole authoritative definition in the entire document):

app must be explicitly provided by the user, or come from .kd/config.json
must not be guessed, and example values must not be used
when creating a new project, enter it in the kd project init interaction
if there is no app, do not continue generating metadata or deploying

Content that is automatically decided or generated by the Skill

This content should be proactively completed by the Skill based on user requirements; do not push it back to the user to design item by item:

Break business requirements down into a component list
Generate a stable PascalCase name for the component
Generate lowercase identifiers that conform to the specification for pages and instances
Determine whether the component needs to keep .js-meta.kwc, or whether it should be deleted to avoid being treated as a deployable component
Map requirements into the component metadata's <property>
Generate page-meta.kwp for the page and fill in <controls>
Generate a unique name
for each component instance in the page init、create、deploy、open Determine whether to currently execute debug
or kd open When checking the environment effect, combine the current task and page metadata to determine on your own whether to use kd debug
the target page; use version
only when the user explicitly requests local integration debugging kd env list Only when the corresponding metadata file changes and needs to be re-uploaded, increment that metadata's kd env info

after environment operations, recheck

app and app The default strategy is: have the user confirm key environment parameters that cannot be inferred, and let the Skill be responsible for turning requirements into the project structure and metadata.

is an exception: even within the scope of automatic decision-making, the

rules in "Inputs that require the user to provide or confirm" must be strictly followed. .js-meta.kwcGenerating component metadata from requirements

When the user wants to "develop a page feature," do not wait until the end to add

. Once the component responsibilities are determined, immediately determine how the component metadata should be generated.
Handle it in this order: .js-meta.kwc。
First identify whether the component will be directly referenced by the page metadata. .js-meta.kwcIf it will be referenced by the page, keep and improve the corresponding
If the component is only internal reusable logic and does not need to be declared in the metadata page, you may delete the corresponding <property>, to avoid being treated by the scaffold as a deployable component.

Refine "parameters configurable by the page configurator" into

version, and do not expose all internal props.
nameComponent metadata should at least focus on these fields:
masterLabel：The Chinese name of the component (e.g., "Sales Order Card", "Purchase Request List"), used as the display title of the component on the page assembly side
isv：Developer identifier; it can be left blank during the development phase and is automatically pulled from the environment and written during deploy
app：For rules, see the "Inputs that need to be provided or confirmed by the user" section
framework
targets
targetConfigs

If you need field rules, types, and examples, read:

references/component-metadata.md

Generate page metadata from requirements

Page metadata is not simply "listing component names"; rather, it explicitly writes out the page assembly structure the user wants.

Process in this order:

First determine the page name, title, owning application, business unit, and version strategy.
Split the page into one or more component instances according to the requirements.
Generate for each instance <control>。
control.type must be exactly consistent with the component name in the component metadata, including case.
control.name is the unique instance name within the page and must comply with the page metadata naming specification.
Only properties defined in the component metadata can be written into <propertys>。

For example, if in the component metadata name is OverviewCard, then in the page metadata control.type can only be written as OverviewCard. Do not, just because the component directory is under app/kwc/ , arbitrarily write it as kwc_OverviewCard; such prefixes are not part of the component type name.

Default policy for page fields:

masterLabel：The Chinese name of the page (e.g., "Sales Order", "Purchase Request", "Inventory Query"), used as the display title of the page in the navigation and management interface
template uses by default oneregion
isv automatically written during deploy, no manual entry required
app For rules, see the "Inputs that need to be provided or confirmed by the user" section

If you need field rules, validation constraints, and examples, read:

references/page-metadata.md

First determine the current stage

Determine and proceed in this order:

If the current directory does not contain .kd, first treat it as "KWC project not yet initialized".
If the user wants to create a new page or component, prefer using kd project create, do not manually assemble the directory structure.
If the user wants to deploy or debug, first check whether the environment has already passed kd env create and kd env auth openapi to complete configuration.
If the user starts writing specific frontend implementation code, first determine the current project framework, then recommend switching to the specialized Skill for the corresponding framework; do not treat this Skill as a component coding specification.

Perform pre-checks

First confirm the following prerequisites:

Understand Project as the local project directory.
Understand Env as the remote Cangqiong environment.
Remind the user that locally they need node、npm、git。

Initialize the project

When the user does not yet have a KWC project, execute according to the following process:

Install the CLI.
Run kd project init <project-name>。
In the interactive process, select the framework and language according to the user's requirements; if the user has not specified, proactively ask.
Enter the application identifier app(for rules, see the "Inputs that need to be provided or confirmed by the user" section).
After initialization is complete, enter the project directory and execute npm install。
Only when local auxiliary preview of the component is needed, then execute npm run dev。

Supplement:kd project init depends on git clone Download the template. If it fails, first check git。

Create Component

When adding a component to an existing project:

Run kd project create <ComponentName> --type kwc。
Use PascalCase component name.
Let the CLI generate the directory and base files.
Immediately check the generated .js-meta.kwc, and fill in the fields and attribute definitions required for deployment(this is the responsibility of this Skill).
Component code implementation handoff: after confirming .js-meta.kwc is filled in, you must stop code writing in this Skill and instead load the corresponding framework development Skill (kwc-react-development / kwc-vue-development / kwc-lwc-development) to write the component implementation code.
If the user wants to create multiple components at the same time, execute the creation command one by one; do not manually copy and infer the directory structure.

If the user only provides a page structure idea and no component names, first generate stable, reusable component names based on semantics, then create them. If the user provides a complete business requirement rather than a component list, first proactively split the component responsibilities, then create them in batches.

Additional notes:

The component is generated under app/kwc/<ComponentName>/ under
The scaffold-generated .js-meta.kwc is only a template and must be filled in according to the above rules
**It is strictly prohibited to directly modify component code files (*.tsx / .vue / .js) in this Skill; code implementation must be handed over to the framework Skill

Create Controller

When adding a KingScript script controller to an existing project:

Run kd project create <ControllerName> --type controller。
Use PascalCase controller name; it is recommended to end with the Controller suffix.
Let the CLI generate the directory and base files. The Controller project is generated under app/ks/controller/<ControllerName>/ under.
After creation, check the generated .kws metadata file and fill in the required fields (name/isv/app/version/url/scriptFile/methods).
Controller code implementation handoff: after confirming the .kws metadata is filled in, you must stop code writing in this Skill and instead load kwc-ks-controller-development to write the controller script code.
If you need to specify the target environment for pulling the SDK, you can use the -e option:kd project create <ControllerName> --type controller -e dev。

Additional notes:

Controller and front-end components (KWC) are independent engineering entities and can coexist in the same project
The scaffold-generated .kws metadata is only a template and must be filled in according to the controller development guide
It is strictly prohibited to directly modify Controller script code (*.ts) in this Skill; code implementation must be handed over to kwc-ks-controller-development

Create page metadata

Page metadata is the core of the final delivery chain. After deployment, the environment will render the components included in the page based on the page-meta.kwp of <controls> of

When a new page needs to be added:

Run kd project create <page-name> --type page。
Open app/pages/<page-name>.page-meta.kwp。
At minimum, check and fill in name、masterLabel、app、version。
In <controls> , associate the page instance with the component type.
Only when the page metadata file has changed and is about to be re-uploaded, manually add version to 1。
Map the component tree, instance names, and page layout to XML, rather than stopping at the step of "the component has been created."

Do not ignore the following constraints:

type is the component type name, which must be exactly the same as the component name in the component metadata; semantic correspondence or a similar name is not sufficient.
name is the component instance name, which must be unique within the page.
isv can be left empty during development; at deploy time it will be automatically pulled from the environment and written in
app For rules, see the section "Inputs that require user provision or confirmation"

If field rules, validation constraints, and examples are needed, read references/page-metadata.md。

Supplement: newly generated page-meta.kwp by default contains only the commented-out <control> template; the Skill must proactively complete it according to requirements <controls>。

Recommended orchestration of scaffolding commands

Frontend and backend assessment of requirements

When facing complete business requirements, determine whether a Controller is needed according to the following priorities:

Strong signals (if any one is matched, directly determine that a Controller is needed, without asking the user):

The requirement involves list/table data display (such as "XX list", "XX query", "XX monitoring")
The requirement involves filter/search/filter conditions
The requirement involves charts/reports/statistics/dashboards
The requirement involves create, update, and delete operations on data (save, submit, review, delete, etc.)
The requirement involves detail viewing/editing
The requirement involves business entity names (such as material, warehouse, order, customer, inventory, etc.)

Weak signals (require asking the user for confirmation):

The requirement only describes UI style or layout and does not mention the data source
The requirement may be fulfilled through local mock data or configuration items

Exclusion signals (no Controller needed):

The page only displays static content, documentation, or local calculation results
Purely presentational components (such as welcome pages, about pages)

Default tendency: when any business-data-related vocabulary appears in the requirement description, prioritize determining that a Controller is needed rather than asking the user.

Entity identification and clarification

After determining that a Controller is needed, you must further identify which business entities the requirement involves, for subsequent meta-query-api.mjs queries of real fields:

Extract entity keywords from the requirement: Analyze the user requirement description and extract all possible business entity names (such as "material", "warehouse", "inventory", "order", etc.)
Confirm the source of the form code: Form/entity codeGuessing is prohibited, and it can only be obtained in the following two ways:
- Provided directly by the user: The user explicitly provides the form code in the requirement (such as bd_material、im_inventory）
- Confirm through query: Use queryFormsByApp to search forms and confirm the real code from the returned results
Clarify the entity with the user: If the user does not provide a form code, and the entity name may be ambiguous (for example, "inventory" may correspond to different forms such as inventory ledger, inventory balance, safety stock, etc.), you must proactively confirm with the user:
- "Which business form does the 'inventory' you mentioned correspond to? Please provide the form code or name so that the accurate field structure can be queried"
- If the entity name is unambiguous and the user is also unsure of the code, you may first use queryFormsByApp to search by keyword and show the results to the user for selection
After confirmation, query the fields: Only after the form encoding is clarified, execute getEntityFields query field structure

Unified frontend-backend orchestration

When the requirement involves both frontend components and backend Controllers, execute according to the following process (metadata precedes code):

If there is no project, execute kd project init
create project structure (this Skill's responsibility): a. For each frontend component, execute kd project create <ComponentName> --type kwc b. For each backend Controller, execute kd project create <ControllerName> --type controller
query business entity fields(when the Controller involves entity data operations):
- When the user provides information related to the form name/encoding/entity, use meta-query-api.mjs query real fields
- First queryFormsByApp search forms, then getEntityFields get field structure (see the "Metadata Query" chapter)
- The query results are used to guide subsequent Controller metadata and code writing,guessing field names is prohibited
Complete all metadata (this Skill's responsibility, metadata comes first): a. Complete component metadata .js-meta.kwc b. Complete Controller metadata .kws(define URL, methods, permission configuration)
Hand over frontend code implementation: load the framework development Skill to write component code (*.tsx / *.vue / *.js)
Hand over backend code implementation: load kwc-ks-controller-development write Controller scripts (*.ts)
Return to this Skill: create page metadata and complete <controls>
Build frontend:npm run build:frontend
Confirm or create the target environment, complete authentication
Execute kd project deploy
After successful deployment, call form-link.mjs output rendering card (see the "Deployment Completion Standard Output" chapter)

Key principles：

In step 4 (metadata completion), component metadata .kwc + Controller metadata .kws are both completed by this Skill
Steps 5-6 (code implementation) are respectively handed over to the corresponding development Skill; this Skill is strictly prohibited from directly writing code
Starting from step 7, return to this Skill for leadership

Frontend-only orchestration

If it is confirmed that the backend is not involved and it is frontend-only development, prioritize executing in this order:

If there is no project, execute kd project init
For each "component that will appear on the page", execute kd project create <ComponentName> --type kwc
Complete component .js-meta.kwc(this Skill's responsibility)
Query associated business entities(optional, when the component involves form data binding): use meta-query-api.mjs query the field structure of the associated form to assist component design (see the "Metadata Query" chapter)
Hand over code implementation: confirm the current project framework,mustload and switch to the corresponding framework development Skill (kwc-react-development / kwc-vue-development / kwc-lwc-development)
Framework Skill implements component code（*.tsx / *.vue / *.js）
After code implementation is complete, return to this Skill: execute kd project create <page-name> --type page
Complete page app/pages/<page-name>.page-meta.kwp
Confirm or create the target environment, complete authentication
Build frontend:npm run build:frontend
If metadata has changed or static files on the environment need to be updated, execute kd project deploy(when deploying to the development environment, frontend static files will also be uploaded)
After all deployments of this task are complete, call form-link.mjs to output the rendered card (see "Standard Output for Deployment Complete",cannot be skipped）
Execute only when the user explicitly requests to view the effect kd open, and when local joint debugging is explicitly requested, execute kd debug(must be in background mode)

Key Principles：

Step 3 (metadata completion) must be completed by this Skill
Steps 5-6 (code implementation)mustbe completed by the framework Skill; this Skill is strictly prohibited from writing code directly
From Step 7 onward (page creation and subsequent steps), control returns to this Skill

If modifying an existing page:

First identify whether it is changing the component implementation, changing component metadata, changing page metadata, or all three
If component code modification is involved: the corresponding framework Skill must be loaded; this Skill is prohibited from modifying code directly
Refer to "whether deploy is needed decision" to determine subsequent operations

Backend Controller orchestration only

If it is confirmed that only the backend is involved and no new frontend components are needed:

If there is no project, execute kd project init
Execute kd project create <ControllerName> --type controller to create the Controller
Query business entity fields(when the Controller involves entity data operations): use meta-query-api.mjs to first search the form and then obtain the field structure (see the "Metadata Query" chapter),guessing field names is prohibited
Complete the Controller metadata .kws(responsibility of this Skill)
Hand over code implementation：mustload and switch to kwc-ks-controller-development
the controller-development Skill to write the script code（*.ts）
After code implementation is complete, return to this Skill: execute kd project deploy to deploy to the target environment (the Controller does not need to be built in advance)
After all deployments of this task are complete, call form-link.mjs to output the rendered card (see "Standard Output for Deployment Complete",cannot be skipped）

Configure Environment

Complete environment configuration before deployment.

Environment Existence Check

When the user provides a specific environment name or alias (such as dev、sit、uat , etc.), an environment existence check should be performed first:

Run kd env list to view the list of currently configured environments
If the target environment already exists in the list:
- There is no need to ask the user to provide environment information such as URL, Client ID/Secret
- Use that environment directly for subsequent operations (such as deploy, debug)
- If the environment is not the current default environment, it can be switched via kd env set target-env <name> switch
- Use kd env info to confirm the environment authentication status
Only when the environment does not exist should you enter the complete environment creation and authentication process

New Environment Process

When the environment does not exist, execute the following process:

Use kd env create <env-name> --url <url> to create an environment alias.
Use kd env auth openapi for interactive authentication.
If the user frequently switches environments, kd env set target-env <env-name> can be used to set the default environment.
If necessary, use kd env list and kd env info to check the current configuration.

Prioritize openapi authentication method;web mode is not used as the default path for now.

Cases where environment information needs to be collected

If the target environment does not exist, or the environment exists but authentication has not yet been completed, stop first and collect these fields:

Environment alias
Environment URL
Client ID
Client Secret
Username

Among these, data center is not a pre-filled manual field, but a "read then select" field:

First have the environment URL
Then enter kd env auth openapi
Have the scaffold read the list of data centers available for that environment
Finally let the user choose from the list

Collection rules:

Values such as environment alias, environment URL, Client ID, Client Secret, and Username must be provided manually by the user
data center Do not let the user enter freely; have the scaffold read the candidates and then select
Do not use credentials from historical environments to guess the new environment
Do not, because aliases such as dev、sit、base exist, automatically infer which environment is to be bound this time

Interaction method rules:

Do not assume that pop-ups or form-based input are necessarily supported currently
In the current conventional mode, first have the user fill in the manual fields, then in kd env auth openapi interaction, select the data center
If the runtime environment clearly supports a structured selection tool, after reading the data center list, you can present the candidates to the user for selection
Even so, free text such as Client Secret should still be manually filled in by the user

Recommended format for requesting environment information from the user:

请补充以下环境信息：
1. env name:
2. env url:
3. client id:
4. client secret:
5. username:

说明：data center 不需要先手填，后续会由脚手架读取候选项供选择。

Note: The environment configuration is saved in ~/.kd rather than the project directory; after creation, you must use kd env list to verify whether persistence succeeded;kd env auth openapi will fail directly when the URL is unreachable.

Deployment and debugging

Build command

During development, only the frontend needs to be built; the Controller is handled directly by deploy:

Scenario	Build command	Description
Changed frontend code (.tsx/.vue/.js)	`npm run build:frontend`	Build frontend static assets, output to dist/kwc/
Changed Controller code (.ts) or .kws	No build needed	During development, deploy handles the Controller directly
Only changed metadata files (.kwc/.kwp/.kws)	No build needed	Metadata is uploaded directly by deploy

Additional usage:

npm run build:frontend -- MyComponent: build the specified frontend component
npm run build:controller: used only for building Controller artifacts in the production environment; not needed during development
npm run build: full build (frontend + Controller), used only for the production environment

Whether a deploy decision is needed

改了什么？
├── 只改前端代码（.tsx/.vue/.js/.html/.scss）
│   ├── 仅本地调试 → npm run build:frontend → kd debug（不需要 deploy）
│   └── 更新环境效果 → npm run build:frontend → kd project deploy
├── 只改 Controller 代码（.ts）或 .kws 元数据
│   → .kws version + 1 → 直接 kd project deploy（不需要 build）
├── 前端 + Controller 都改了
│   → 递增相关 version → npm run build:frontend → kd project deploy
├── 只改元数据（.js-meta.kwc / .page-meta.kwp）
│   → version + 1 → 直接 kd project deploy（不需要 build）
└── 新建组件/页面/Controller
    → version = 1 → 若有前端代码则 npm run build:frontend → kd project deploy

Common commands

kd project deploy: deploy all metadata of the entire project at once (.js-meta.kwc + .page-meta.kwp + .kws) and frontend static files to the default environment; during development, the Controller is handled directly by deploy, with no need to build in advance
kd project deploy -d app/kwc/MyComponent -e sit: deploy only the specified component to sit
kd project deploy -d app/pages/my_page -e sit: deploy only the specified page metadata to sit
kd project deploy -d app/ks/controller/MyController -e sit: deploy only the specified Controller to sit
kd open -e dev -f kdtest_demo_page: after deployment, directly open the form on the environment to view the effect (no DNS proxy)
kd debug: enter local debugging and connect to the environment through a DNS proxy (Must use is_background: true to run, and only use it when the user explicitly requests debugging)

Deployment completion standard output

Whenever the AI completes a piece of work and the deployment succeeds,mustcall the form-link.mjs script to generate a rendering card and output it to the user, showing the access entry for the deployed page. The rendering card is the entry point for the user to trigger the preview effect.

Key rules:

Output upon completion: whenever a piece of previewable work is completed (all deploys involved in that piece have succeeded), immediately output the rendering card. In a multi-turn conversation, each completed piece of work should have a rendering card output; do not save them all until the end to output
No repetition within the same piece of work: if a piece of work involves multiple deploys (e.g., first deploy a component, then deploy a page, then deploy a Controller), output once after all deployments in that piece are completed; do not output once for every deploy command executed
Applies to any deploy form: full deployment (kd project deploy), specified-path deployment (-d app/kwc/...、-d app/pages/...、-d app/ks/controller/...）

Call command

# 页面无关联实体时（纯展示页、配置页等）
node "{form_link}" generate --pageMeta app/pages/<page-name>.page-meta.kwp [--env <envName>]

# 页面关联了业务实体时（如销售订单、采购申请等）
node "{form_link}" generate --pageMeta app/pages/<page-name>.page-meta.kwp --formNumber <entity-formNumber> [--env <envName>]

metadata field determination rules

metadata field isconditional, and is output only when the page is associated with a business entity
--formNumber is passedthe entity's formNumber(e.g., sal_salorder), not the page metadata's <name>
must be passed --formNumber Scenarios where --formNumber must be passed(must be passed if any one is satisfied):
- The user requirement mentions any existing form, entity, or metadata name (such as business objects like "sales order" and "purchase request")
- During development, meta-query-api.mjs was used to query forms/fields (e.g., queryFormsByApp、getEntityFields）
- Controller is configured with entityNumber
- The user explicitly provided the form code / formNumber
Active query rule for existing entities: when the requirement involves an already existing entity, metadata, or form,mustfirst use meta-query-api.mjs 's queryFormsByApp to search forms to obtain the formNumber, and then pass it to --formNumber. Do not ignore this parameter just because getEntityFields was not called during development
If unsure, query: when unsure whether the page is associated with an existing entity, you should first confirm by querying through queryFormsByApp , rather than leaving it unpassed by default
Scenarios where --formNumber may be omitted(may be omitted only in the following cases):
- It is clearly a purely display page, configuration page, dashboard, or other page with no associated entity
- The page is newly created and is not based on any existing entity

Execution order

当段工作所有 deploy 完成 → 调用 form-link.mjs 输出渲染卡片（强制） → 询问菜单发布（可选）

Mandatory constraints

After the deployment of each piece of work is completed,mustoutput the rendering card; it cannot be omitted or skipped
In a multi-turn conversation, each completed piece of work should be output; do not output only at the very end
Do not output repeatedly within the same piece of work (when multiple deploy commands belong to the same piece of work, wait until all are completed and output once)
The script output content must be presented directly to the user
All values must be read from actual files and the environment; guessing is prohibited

View environment result (kd open)

Note: after deployment, only the render card is output by default (see "Deployment Completion Standard Output"), and kd open is not executed automatically. Use this command only when the user explicitly asks to view the environment result.

After deployment, use kd open to view the form result on the environment:

kd open -e <env> -f <page_name>: directly open the deployed form page on the corresponding environment in the browser
-e specify the target environment (required),-f pass in the page metadata <name> value (required), with the same value rules as kd debug -f -e Specify the target environment (required), -f pass in the page metadata <name> value (required); the value rules are the same as kd debug -f
no local dev server needs to be running, and it does not go through the DNS proxy
Prerequisite: the metadata and static files have already been deployed to the target environment via kd project deploy Deploy metadata and static files to the target environment

Applicable scenarios: the user says "take a look at the result", "open the page", "view the form on the environment", "see the deployment result", etc.

Local debugging (kd debug)

Use kd debug：

only when the user explicitly says "debug", "local debugging", "joint debugging", or "real-time preview of code changes" kd debug must use background mode ( is_background: true ) when running kd debug, because this is a continuously running development server that will not end automaticallymust use background mode（is_background: true), because this is a continuously running development server and will not end automatically
If foreground mode is used to run kd debug, the command will be forcibly terminated after a 90-second timeout, causing the local service to be killed
kd debug after startup first opens the browser to access the corresponding address, but at this point the local development service may not be fully started, and the page may be temporarily inaccessible. You should wait for the service to finish starting, then refresh the browser
You can use get_terminal_output to view the running status and output of kd debug runtime status and output
If the target environment is not the current default environment, first execute kd env set target-env <env-name>
Do not manually assemble the debug URL; the AI should determine the preview target itself based on the task and page metadata
After the browser opens automatically, continue to locate the target page

Trigger decision

Prerequisites (must be completed before triggering open/debug):

Code writing has been completed
The necessary build command has been executed (if the code was modified)
kd project deploy has been executed (if deployment is needed)
The render card has been output (see "Deployment Completion Standard Output"; after deployment, the render card must be output first before executing open/debug)
The environment has been authenticated

用户意图判断：
├── "看效果/打开页面/查看部署结果/看看环境上的表单" → kd open
├── "调试/联调/本地调试/实时预览修改" → kd debug
└── 未明确表达 → 默认输出渲染卡片即结束，不自动执行 kd open 或 kd debug

Additional note: when the environment is not authenticated, kd project deploy will directly block deployment.

Application menu management

Menu management registers deployed pages into the application navigation menu so that pages can be navigated and accessed by users in the Cosmic environment. All menu operations are performed through the scripts/menu-api.mjs script; for detailed command reference, see references/app-menu.md。

Trigger conditions

kd project deploy After success, guide the user on whether to publish the page to the application menu
The user directly says "publish menu", "add menu", "menu management", "view menu", "modify menu", "delete menu", "move menu"

Prerequisites

The environment has been authenticated (kd env auth openapi completed)
bizAppNumber is known (from the .kd/config.json bizAppNumber is known (from the app field in .kd/config.json, or explicitly provided by the user) app field, or explicitly provided by the user)

Interface dependencies (mandatory constraints)

All menu operations must follow the "query before modify" principle; it is forbidden to skip the query and directly perform write operations.

queryTree（必须）→ 获得 menuId / 菜单结构 → 执行写操作 → getMenu 或 queryTree 验证结果

Constraints	Description
menuId can only be obtained from the API	`menuId` can only come from `queryTree` the returned menu tree,`addMenu` the returned newly created menu, or `getMenu` the returned details. It is forbidden to construct menuId from memory or guesswork
Before modifying/deleting/moving, you must first query	Before executing updateMenu , deleteMenu , moveMenu , you must first execute queryTree to obtain the current menu tree, and confirm from the returned result that the target menuId exists and its status is correct `updateMenu`、`deleteMenu`、`moveMenu` Before executing `queryTree` you must first execute queryTree to obtain the current menu tree, and confirm from the returned result that the target menuId exists and its status is correct
After adding, menuId must be captured	`addMenu` After success, you must extract the new menu's `menuId` from the response and record it for subsequent modification/moving
After a write operation, verification is required	After any write operation (add/update/delete/move) is completed, you must execute `getMenu` After any write operation (add/update/delete/move) is completed, you must execute getMenu or queryTree to verify the actual state, and cannot judge solely based on the returned success `queryTree` to verify the actual state, and cannot judge solely based on the returned success
parentMenuId must come from a query	When adding a submenu,`parentMenuId` When adding a submenu, parentMenuId must be obtained from the queryTree returned result as the menuId of an existing menu; guessing is forbidden `queryTree` must be obtained from the returned result of

Step 1: Context preparation

Read .kd/config.json 's app field as bizAppNumber .kd/config.json Read .kd/config.json 's app field as bizAppNumber app field as bizAppNumber
If entering from the deployment process: formNumber = after deploy .page-meta.kwp If entering from the deployment process: formNumber = after deploy .page-meta.kwp the actual value of the <name> tag (already includes the ISV prefix) <name> the actual value of the tag (already includes the ISV prefix)
If the user directly triggers menu management: only bizAppNumber is known, enter Step 2 to query the menu tree

⚠ formNumber must be read from the deployed .page-meta.kwp file, read the actual value of the <name> tag; do not concatenate the ISV prefix yourself.

Step 2: Query and display the menu tree (a prerequisite step for any operation)

No matter what menu operation the user requests, this step must be executed first to obtain the current menu status.

node "{menu_api}" queryTree --bizAppNumber {bizAppNumber}

Display by hierarchical indentation, use icons to distinguish types (📁 group / 📄 page / 🔗 link); see the display specification in references/app-menu.md
Record the menuId of all menus, and subsequent operations must use the menuId obtained here
After displaying, guide the next step according to the source:
- Enter after deployment → Based on the form name and existing menu structure, recommend a menu placement location (analyze semantic associations, recommend grouping similar items; if the menu tree is empty, recommend creating a first-level menu). Before recommending, check the target location's hierarchy depth (no more than 3 levels)
- User directly triggers → After displaying the menu tree, wait for the user to indicate the operation

Step 3: Execute menu operations

Execute the corresponding operation according to the user's intent (all menuIds must come from the query results of Step 2):

Operation	Command	Pre-execution check
Add	`addMenu --bizAppNumber {app} --name {name} --formNumber {form} [--parentMenuId {pid}] [--seq {n}]`	Confirm the menu name and location; check that the hierarchy does not exceed 3 levels; parentMenuId must come from the queryTree result;When batch-adding sibling menus, you must pass incrementing --seq values starting from a small number (e.g., 1, 2, 3); large values are prohibited, range 1–32767
Modify	`updateMenu --bizAppNumber {app} --menuId {id} [--name ...] [--visible ...] [--seq {n}]`	menuId must come from the queryTree result; when modifying visible to 0, warn about cascading hiding; when modifying parentMenuId, check for circular references and hierarchy
Delete	`deleteMenu --bizAppNumber {app} --menuId {id}`	menuId must come from the queryTree result; check HPCE protection; warn about cascading deletion of child menus; user confirmation required
Move	`moveMenu --bizAppNumber {app} --menuId {id} --direction {up/down}`	menuId must come from the queryTree result; display the current sort position; if the error "sequence numbers are identical" is reported, first use updateMenu --seq to modify the sequence numbers of adjacent menus, then retry

Before every operation, the configuration plan must be shown to the user for confirmation, and execution proceeds only after user confirmation.

Step 4: Verify and display results

After any write operation is completedmustverify the actual result:
- Delete operation: Prefer using getMenu to confirm that the target menu returns MENU_NOT_FOUND(the menu tree may have a brief cache delay)
- Other write operations: Execute getMenu(single menu) or queryTree(global) to verify
After addMenu succeeds, extract and record the new menu's menuId from the response
Display completion information and provide follow-up operation options:
1. Modify this menu
2. Move menu position
3. Delete this menu
4. Continue adding other menus
5. View the complete menu tree
6. Done

Integration with the deployment process

kd project deploy After success:

First output the rendered card: Call form-link.mjs to generate the deployment completion rendered card (see the "Deployment Completion Standard Output" section)
Then guide menu publishing: Ask the user whether the page needs to be published to the application menu

Deployment succeeded. Do you need to publish the page to the application menu?

If the user agrees → automatically enter Step 1 (bizAppNumber and formNumber are both already available from the current context).

Constraint quick reference

Constraint	When to remind
Menus can be at most 3 levels	Check when adding or moving menus
HPCE menus cannot be deleted	Before deletion, check whether menuId ends with HPCE
Cascading hiding	Warn when modifying visible from 1→0
Cascading deletion	Warn when deleting a menu that has child menus
formNumber takes the actual value	When adding a page menu

Metadata query

Metadata query is used to search forms and obtain entity field structures in an authenticated environment, providing contextual information for KS script writing, page development, etc. All query operations are completed through the scripts/meta-query-api.mjs script; for detailed command reference, see references/meta-query.md。

Trigger conditions

The user mentions a form name (e.g., "Sales Order") but does not provide a formNumber
Need to query the field structure of a certain form
Need to understand the target form's entity fields before KS Controller development
When developing pages, you need to understand the data model of the associated form

Prerequisites

Environment is authenticated (kd env auth openapi completed)
appNumber is known (from the .kd/config.json field of app , or explicitly provided by the user)

Workflow

Step 1: Search for the form

Prefer using queryFormsByApp to search within the current application scope:

node "{meta_query_api}" queryFormsByApp --appNumber {appNumber} --keyword {keyword}

appNumber obtained from the .kd/config.json field of app Field retrieval
keyword is the form name keyword mentioned by the user (optional; if not provided, all forms under the application will be listed)

Step 2: Confirm the target form

Handle according to the number of returned results:

Scenario	Handling method
Single result returned	Directly confirm it as the target form and extract `formNumber`
Multiple results returned	Display a list for the user to choose (number / form name / form code / model type / owning application)
Empty result returned	Prompt that it was not found, and suggest trying again with different keywords

Step 3: Get entity fields (as needed)

After confirming the target form, get the field structure as needed:

node "{meta_query_api}" getEntityFields --formNumber {formNumber}

The returned results are displayed grouped by header and entry, showing the fields' key, type, whether they are required, and other information.

Use flexibly

The user may also perform only Steps 1-2 (query the form list only), and does not need to query fields every time
If the user already knows formNumber, they can directly perform Step 3 to get the field structure
The query results can be used for KS script writing, page development, or simply understanding the form structure

Integration with other processes

KS Controller development: Before development, first query the target form's field structure to understand the field keys and types of the header/entry/sub-entry
Page development: Query associated forms to understand the data model and assist component design
Standalone use: When the user only wants to understand a certain form structure, it can be called independently

End-to-end execution principles

When the user says "help me develop a KWC page/feature", proceed by default along this chain:

Identify whether it is a new project or an existing project
Collect non-inferable environment inputs
Assess whether the requirement involves backend data interaction; if so, plan the Controller
Split components and create the component project; if a Controller is needed, create the Controller project as well
Complete all metadata: component metadata .js-meta.kwc, Controller metadata .kws(if any)
Implement the frontend component code (hand off to the framework Skill)
If there is a Controller, implement the Controller script code (hand off to kwc-ks-controller-development)
Create and complete page metadata
If there is a Controller, execute npm run build:controller
Configure the environment and confirm the authentication status
If metadata has changed, execute deploy
After successful deployment, call form-link.mjs to output the rendering card (see the "Deployment Completion Standard Output" section)
Execute only when the user explicitly requests to view the effect kd open
Execute only when the user explicitly requests local joint debugging kd debug

Do not complete only the "create component" or "run locally" part, unless the user explicitly asks for just a partial step.

Output requirements

When outputting a plan or executing commands, try to also provide:

Which key inputs the user still needs to supply
Which stage is currently in progress
The next command to execute
Whether it depends on existing environment authentication
Whether it is necessary to modify page-meta.kwp
How the page metadata will combine the components
Whether it is really necessary to deploy
If deployment is needed, whether it must be incremented due to metadata changes version
Whether it has been output after successful deployment :::render:kdform Render card (see the "Deployment Completion Standard Output" section)

Troubleshooting quick reference table

Symptom	Possible cause	Solution
`kd project deploy` Prompt says unauthenticated	The environment has not executed auth	`kd env auth openapi`
Page metadata upload failed	version was not incremented	Retry after incrementing version
Page displays blank	control.type does not match the component name	Check that case is exactly consistent
Component properties do not take effect	Properties are not declared in .js-meta.kwc	Add `<property>` definition
name validation failed	Format does not match	Start with a letter, only lowercase + digits + underscores, ≤30 characters
isv is inconsistent	The page and the environment developer do not match	deploy will replace it automatically, no manual entry needed
Executing the command in a non-KWC project directory	Missing .kd directory	First execute `kd project init`
Created the page but the component does not display	The component was not written into `<controls>`	Edit page-meta.kwp to add control
`kd debug` Prompt says port is occupied	Port 3333 is occupied	Close the occupying process or restart the terminal
`kd debug` After starting, the target form cannot be found / the wrong form was entered	Did not use `-f` The parameter specifies the page metadata name, or a file name was passed instead of the metadata name value	Use `kd debug -f <page_name>`, where `<page_name>` isthe current local `.page-meta.kwp` in the file `<name>` the actual value of the node. Note: after deploy, the scaffold will automatically update the name in the local file (concatenating the isv prefix), so the full name after deploy should be used, such as `kdtest_demo_page`
`kd open` After opening the page, it displays blank	Not deployed or static files were not uploaded	First execute `kd project deploy` to ensure the metadata and static files have been uploaded
`kd open` Prompt says the form does not exist	`-f` The parameter value is incorrect	Pass in the page metadata `<name>` the actual value of the node (the full name after deploy)

Form name and ISV prefix explanation

Creation stage：.page-meta.kwp in <name> can be filled with a business identifier, such as demo_page
Deploy phase: the scaffolding automatically pulls the isv from the environment (e.g., kdtest), concatenates it into kdtest_demo_page and uploads it to the remote end, andsynchronously updates the local file
Debug/Open phase：kd debug -f and kd open -f both should pass inthe current local file's <name> value(i.e., the full name after deploy)
If unsure, directly open .page-meta.kwp to view the <name> node

Quick navigation

Quickly locate reference documentation by common scenario:

New project initialization → cli-reference.md(project init) + this article's "Initialize project" section
Add component → cli-reference.md（project create）+ component-metadata.md
Create page → page-metadata.md + this article's "Create page metadata" section
Environment configuration and deployment → env-setup.md + cli-reference.md(deploy/open/debug) + this article's "Configure environment" and "Deploy and debug" sections
Application menu management → app-menu.md + this article's "Application menu management" section
Metadata query → meta-query.md + this article's "Metadata query" section

Reference materials

Topic	Reference file
CLI command syntax, parameters, examples	`references/cli-reference.md`
Component metadata fields and property types	`references/component-metadata.md`
Environment information collection and authentication process	`references/env-setup.md`
Page metadata fields, controls rules, naming conventions	`references/page-metadata.md`
Application menu management commands and display conventions	`references/app-menu.md`
Metadata query commands and response format	`references/meta-query.md`

About this skill

Correctly understand the delivery target

Metadata-driven full-stack development model

First translate the requirements into engineering goals

Framework development Skill collaboration

Hard constraints: code implementation must be handed over to the framework Skill

Collaboration boundary table

Switching timing

Exception flow protection

Framework Skill activation checklist

Recommended rules

Inputs that need to be provided or confirmed by the user

Content that is automatically decided or generated by the Skill

is an exception: even within the scope of automatic decision-making, the

Generate page metadata from requirements

First determine the current stage

Perform pre-checks

Initialize the project

Create Component

Create Controller

Create page metadata

Recommended orchestration of scaffolding commands

Frontend and backend assessment of requirements

Entity identification and clarification

Unified frontend-backend orchestration

Frontend-only orchestration

Backend Controller orchestration only

Configure Environment

Environment Existence Check

New Environment Process

Cases where environment information needs to be collected

Deployment and debugging

Build command

Whether a deploy decision is needed

Common commands

Deployment completion standard output

Call command

metadata field determination rules

Execution order

Mandatory constraints

View environment result (kd open)

Local debugging (kd debug)

Trigger decision

Application menu management

Trigger conditions

Prerequisites

Interface dependencies (mandatory constraints)

Step 1: Context preparation

Step 2: Query and display the menu tree (a prerequisite step for any operation)

Step 3: Execute menu operations

Step 4: Verify and display results

Integration with the deployment process

Constraint quick reference

Metadata query

Trigger conditions

Prerequisites

Workflow

Step 1: Search for the form

Step 2: Confirm the target form

Step 3: Get entity fields (as needed)

Use flexibly

Integration with other processes

End-to-end execution principles

Output requirements

Troubleshooting quick reference table

Form name and ISV prefix explanation

Quick navigation

Reference materials