kwc-project-scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KWC Project Scaffold

将本 Skill 作为 KWC 工程脚手架工作的入口。优先把用户需求归入以下几类：初始化项目、创建组件、创建页面元数据、配置环境、部署、调试。

Use this Skill as the entry point for KWC project scaffolding work. Prioritize categorizing user requirements into the following types: project initialization, component creation, page metadata creation, environment configuration, deployment, debugging.

正确认知交付对象

Correct Understanding of Deliverables

不要把 KWC 工作流理解成“本地把一个组件渲染出来”。 KWC 的核心交付对象是：

组件工程本身
页面元数据
```
*.page-meta.kwp
```
目标环境配置与认证
通过
```
kd project deploy
```
上传后的环境渲染结果

页面最终展示依赖页面元数据中的

<controls>

和组件类型映射，而不是本地

main.tsx

是否挂载了某个组件。

main.tsx

和

npm run dev

只用于本地辅助预览，不是最终交付路径。

Do not interpret the KWC workflow as "rendering a component locally". The core deliverables of KWC are:

The component project itself
Page metadata
```
*.page-meta.kwp
```
Target environment configuration and authentication
Environment rendering results after uploading via
```
kd project deploy
```

The final page display depends on the

<controls>

in the page metadata and component type mapping, not whether a component is mounted in the local

main.tsx

main.tsx

and

npm run dev

are only used for local auxiliary preview, not the final delivery path.

元数据优先的开发模型

Metadata-First Development Model

从用户开发角度看，一个 KWC 功能要拆成三层：

组件代码：真正负责渲染和行为逻辑
组件元数据
```
.js-meta.kwc
```
：声明“这个组件可以被页面如何引用、可以暴露哪些可配置属性”
页面元数据
```
.page-meta.kwp
```
：声明“这个页面由哪些组件实例组成，并给每个实例传什么属性值”

因此，面对需求时不要只问“要写几个组件”，还要继续判断：

哪些参数是写死在组件代码里的
哪些参数需要暴露给页面配置者，通过组件元数据定义为
```
<property>
```
哪些组件实例会出现在页面元数据的
```
<controls>
```
中

默认原则：

能固定在组件内部的实现细节，不要暴露到元数据
只有需要被页面装配、复用、配置的参数，才进入组件元数据和页面元数据

From the user's development perspective, a KWC function should be divided into three layers:

Component code: Responsible for rendering and business 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"

Therefore, when handling requirements, do not only ask "how many components need to be written", but also judge:

Which parameters are hard-coded in the component code
Which parameters need to be exposed to page configurators and defined as
```
<property>
```
in component metadata
Which component instances will appear in the
```
<controls>
```
of the page metadata

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, or configured by pages should be included in component metadata and page metadata

先把需求翻译成工程目标

Translate Requirements into Project Objectives First

面对“帮我开发一个 KWC 页面/功能”的请求时，先把需求翻译成下面几项：

是否需要新建工程，还是在已有工程里继续开发
需要几个组件，各自承担什么职责
需要几个页面元数据文件，页面里如何组合这些组件
最终要部署到哪个环境
是否还需要进入
```
kd debug
```
做联调验证

只有把这几项补齐，脚手架命令才有明确目标。

When receiving a request like "Help me develop a KWC page/function", first translate the requirements into the following items:

Whether a new project needs to be created or development continues in an existing project
How many components are needed and their respective responsibilities
How many page metadata files are needed and how to combine these components in the page
Which target environment to deploy to finally
Whether
```
kd debug
```
is needed for joint debugging and verification

Only when these items are clarified can the scaffolding commands have clear objectives.

框架开发 Skill 协作

Framework Development Skill Collaboration

将

kwc-project-scaffold

视为 KWC 工作流的总入口，但不要让它吞掉框架开发 Skill 的职责。

职责边界如下：

```
kwc-project-scaffold
```
负责项目初始化、组件与页面元数据生成、环境配置、部署、调试编排
```
kwc-react-development
```
负责 React KWC 项目的具体组件代码实现、框架规范和本地预览约束
```
kwc-vue-development
```
负责 Vue KWC 项目的具体组件代码实现、框架规范和本地预览约束
```
kwc-lwc-development
```
负责 LWC KWC 项目的具体组件代码实现、框架规范和本地预览约束

协作约定：

当任务仍处于需求拆分、脚手架命令、元数据、环境、
```
deploy
```
、
```
debug
```
阶段时，继续由本 Skill 主导
当任务进入“具体代码开发、组件修改、页面前端实现”阶段时，建议加载与当前 framework 对应的开发 Skill
不要同时加载三个框架开发 Skill；只根据当前工程的 framework 推荐一个
不要把三个框架 Skill 的具体编码细则复制进本 Skill；本 Skill 只保留选择逻辑和切换时机

推荐规则：

若是新建工程，以
```
kd project init
```
交互中用户选择的 framework 作为后续推荐 Skill 依据
若是已有工程，以
```
.kd/config.json
```
中的
```
framework
```
作为推荐 Skill 依据
当
```
framework=react
```
时，建议转入
```
kwc-react-development
```
当
```
framework=vue
```
时，建议转入
```
kwc-vue-development
```
当
```
framework=lwc
```
时，建议转入
```
kwc-lwc-development
```
若还无法判断 framework，先停下来向用户确认，不要直接继续写代码

Treat

kwc-project-scaffold

as the general entry point for the KWC workflow, but do not let it take over the responsibilities of framework development Skills.

Responsibility boundaries:

```
kwc-project-scaffold
```
is responsible for project initialization, component and page metadata generation, environment configuration, deployment, and debugging orchestration
```
kwc-react-development
```
is responsible for specific component code implementation, framework specifications, and local preview constraints for React KWC projects
```
kwc-vue-development
```
is responsible for specific component code implementation, framework specifications, and local preview constraints for Vue KWC projects
```
kwc-lwc-development
```
is responsible for specific component code implementation, framework specifications, and local preview constraints for LWC KWC projects

Collaboration agreements:

When the task is still in the stages of requirement splitting, scaffolding commands, metadata, environment,
```
deploy
```
, or
```
debug
```
, this Skill continues to lead
When the task enters the stage of "specific code development, component modification, front-end page implementation", it is recommended to load the development Skill corresponding to the current framework
Do not load three framework development Skills at the same time; only recommend one based on the framework of the current project
Do not copy the specific coding rules of the three framework Skills into this Skill; this Skill only retains the selection logic and switching timing

Recommendation rules:

For new projects, use the framework selected by the user in the
```
kd project init
```
interaction as the basis for subsequent Skill recommendations
For existing projects, use the
```
framework
```
in
```
.kd/config.json
```
as the basis for Skill recommendations
When
```
framework=react
```
, it is recommended to switch to
```
kwc-react-development
```
When
```
framework=vue
```
, it is recommended to switch to
```
kwc-vue-development
```
When
```
framework=lwc
```
, it is recommended to switch to
```
kwc-lwc-development
```
If the framework cannot be determined yet, stop and confirm with the user instead of proceeding directly to write code

需要用户提供或确认的输入

Inputs that Require User Provision or Confirmation

这些输入若无法从现有工程或上下文推断，就必须向用户确认：

项目名或现有项目路径
框架和语言
苍穹应用编码
```
app
```
目标环境别名和 URL
认证方式，以及 OpenAPI 所需的真实参数
页面标识，例如 page name、formId、业务页面用途
页面标题、是否需要
```
bizUnit
```
、是否需要扩展和权限控制
哪些组件需要暴露给页面使用，哪些只是内部逻辑组件
哪些参数需要做成可配置属性
若用户已有环境，是否允许直接部署到该环境

这些信息不要擅自编造，尤其是

app

、环境 URL、认证参数和最终部署环境。

关于

isv

（开发商标识）：开发阶段可以留空，在组件与环境绑定时会从环境拉取开发商标识，

kd project deploy

时会自动写入组件和页面元数据，因此不需要用户手工提供或维护。

对

app

使用最严格的规则（本节为全文唯一权威定义，后续各章节不再重复）：

```
app
```
不是 Skill 可以猜测或写死的值
```
app
```
必须由用户明确提供，或来自当前工程里已经存在的
```
.kd/config.json
```
新建工程时，
```
kd project init
```
的交互步骤里必须手动填写
```
app
```
如果用户没有给
```
app
```
，就不要继续初始化、生成正式元数据或部署
不要把示例中的
```
app
```
值当默认值
不要复用上一次任务里的
```
app
```
不要因为当前环境里存在某个应用就自动代入

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
Sky application code
```
app
```
Target environment alias and URL
Authentication method, and real parameters required by OpenAPI
Page identifier, such as page name, formId, business page purpose
Page title, whether
```
bizUnit
```
is needed, whether extension and permission control are needed
Which components need to be exposed to 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 direct deployment to this environment is allowed

Do not fabricate this information without authorization, especially

app

, environment URL, authentication parameters, and the final deployment environment.

Regarding

isv

(developer identifier): It can be left blank during the development phase, and the developer identifier will be pulled from the environment when binding components to the environment, and automatically written into components and page metadata during

kd project deploy

, so users do not need to provide or maintain it manually.

The strictest rules apply to

app

(this section is the only authoritative definition in the full text and will not be repeated in subsequent sections):

```
app
```
is not a value that can be guessed or hard-coded by the Skill
```
app
```
must be explicitly provided by the user or come from the existing
```
.kd/config.json
```
in the current project
When creating a new project,
```
app
```
must be manually filled in during the interaction steps of
```
kd project init
```
If the user does not provide
```
app
```
, do not proceed with initialization, formal metadata generation, or deployment
Do not use the
```
app
```
value in examples as the default value
Do not reuse the
```
app
```
from the previous task
Do not automatically substitute it just because an application exists in the current environment

由 Skill 自动决策或生成的内容

Content Automatically Decided or Generated by the Skill

这些内容应由 Skill 基于用户需求主动完成，不要把它们再推回给用户逐项设计：

将业务需求拆成组件列表
为组件生成稳定的
```
PascalCase
```
名称
为页面和实例生成符合规范的小写标识
判断组件是否需要保留
```
.js-meta.kwc
```
，还是应删除以避免被当成可部署组件
将需求映射为组件元数据里的
```
<property>
```
为页面生成
```
page-meta.kwp
```
并填充
```
<controls>
```
为页面中的每个组件实例生成唯一
```
name
```
判断当前该执行
```
init
```
、
```
create
```
、
```
deploy
```
还是
```
debug
```
仅当对应元数据文件变更并需要重新上传时，递增该元数据的
```
version
```
在环境操作后复核
```
kd env list
```
和
```
kd env info
```

默认策略是：让用户确认不可推断的关键环境参数，由 Skill 负责把需求落实成工程结构和元数据。

app

是例外：即使在自动决策范围内，也必须严格遵守"需要用户提供或确认的输入"中的

app

规则。

These contents should be actively completed by the Skill based on user requirements, and should not be pushed back to the user for item-by-item design:

Split business requirements into component lists
Generate stable
```
PascalCase
```
names for components
Generate standardized lowercase identifiers for pages and instances
Judge whether components need to retain
```
.js-meta.kwc
```
or should be deleted to avoid being treated as deployable components by the scaffolding
Map requirements to
```
<property>
```
in component metadata
Generate
```
page-meta.kwp
```
for pages and fill in
```
<controls>
```
Generate a unique
```
name
```
for each component instance in the page
Judge whether to execute
```
init
```
,
```
create
```
,
```
deploy
```
, or
```
debug
```
currently
Increment the
```
version
```
of the metadata only when the corresponding metadata file is changed and needs to be re-uploaded
Review
```
kd env list
```
and
```
kd env info
```
after environment operations

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

app

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

app

rules in "Inputs that Require User Provision or Confirmation" must be strictly followed.

从需求生成组件元数据

Generate Component Metadata from Requirements

当用户要“开发一个页面功能”时，不要等到最后才补

.js-meta.kwc

。应在组件职责确定后，立即判断组件元数据应如何生成。

按这个顺序处理：

先识别组件是否会被页面元数据直接引用。
若会被页面引用，就保留并完善对应的
```
.js-meta.kwc
```
。
若组件只是内部复用逻辑、不需要在元数据页面中声明，可删除对应
```
.js-meta.kwc
```
，避免被脚手架当作可部署组件。
将“页面配置者可调的参数”提炼为
```
<property>
```
，不要把所有内部 props 都暴露出去。

组件元数据至少应关注这些字段：

```
version
```
：自然数；脚手架模板可能留空，Skill 需要补成有效值
```
name
```
：通常与组件名保持一致，作为组件类型标识
```
masterLabel
```
：组件在页面装配侧显示的名称
```
isv
```
：开发商标识，开发阶段可留空，deploy 时自动从环境拉取写入
```
app
```
：规则见"需要用户提供或确认的输入"一节
```
framework
```
```
targets
```
```
targetConfigs
```

属性设计原则：

文本输入用
```
String
```
整数范围用
```
Integer
```
开关型配置用
```
Boolean
```
固定枚举选择用
```
Combo
```

只有当页面需要给组件实例传值时，才在组件元数据里声明

<property>

。页面元数据

<propertys>

中出现的属性名，必须能在组件元数据里找到对应定义。

app

的填写规则见"需要用户提供或确认的输入"一节；若当前工程无可信

app

，不要生成正式可部署元数据。

如果需要字段规则、类型和示例，读取：

```
references/component-metadata.md
```

When the user wants to "develop a page function", do not wait until the end to supplement

.js-meta.kwc

. After determining component responsibilities, immediately judge how to generate component metadata.

Process in this order:

First identify whether the component will be directly referenced by page metadata.
If it will be referenced by the page, retain and improve the corresponding
```
.js-meta.kwc
```
.
If the component is only for internal reuse logic and does not need to be declared in the metadata page, the corresponding
```
.js-meta.kwc
```
can be deleted to avoid being treated as a deployable component by the scaffolding.
Refine "parameters adjustable by page configurators" into
```
<property>
```
, and do not expose all internal props.

Component metadata should focus on at least these fields:

```
version
```
: Natural number; the scaffolding template may leave it blank, and the Skill needs to fill in a valid value
```
name
```
: Usually consistent with the component name, used as the component type identifier
```
masterLabel
```
: The name of the component displayed on the page assembly side
```
isv
```
: Developer identifier, can be left blank during development, and automatically pulled from the environment and written during deploy
```
app
```
: Rules refer to the section "Inputs that Require User Provision or Confirmation"
```
framework
```
```
targets
```
```
targetConfigs
```

Property design principles:

Use
```
String
```
for text input
Use
```
Integer
```
for integer ranges
Use
```
Boolean
```
for switch-type configurations
Use
```
Combo
```
for fixed enumeration selections

Only when the page needs to pass values to component instances should

<property>

be declared in the component metadata. The property names appearing in

<propertys>

of page metadata must have corresponding definitions in component metadata.

The filling rules for

app

refer to the section "Inputs that Require User Provision or Confirmation"; if there is no credible

app

in the current project, do not generate formal deployable metadata.

If field rules, types, and examples are needed, read:

```
references/component-metadata.md
```

从需求生成页面元数据

Generate Page Metadata from Requirements

页面元数据不是简单“列出组件名称”，而是把用户要的页面装配结构显式写出来。

按这个顺序处理：

先确定页面名称、标题、所属应用、业务单元、版本策略。
根据需求把页面拆成一个或多个组件实例。
为每个实例生成
```
<control>
```
。
```
control.type
```
必须与组件元数据里的组件
```
name
```
完全一致，包含大小写也必须一致。
```
control.name
```
是页面内唯一实例名，必须符合页面元数据命名规范。
只有组件元数据中定义过的属性，才能写进
```
<propertys>
```
。

例如，若组件元数据中的

name

是

OverviewCard

，则页面元数据里的

control.type

只能写

OverviewCard

。不要因为组件目录在

app/kwc/

下，就擅自写成

kwc_OverviewCard

；这类前缀不是组件类型名的一部分。

页面字段默认策略：

```
template
```
默认使用
```
oneregion
```

bizUnit

、

enableExtend

、

enablePermissionControl

仅在需求明确时填写

```
isv
```
、
```
app
```
以页面主信息为主，控制级别只有在需要覆盖时才填写

app

的填写规则见"需要用户提供或确认的输入"一节。若发现页面元数据

app

与

.kd/config.json

不一致，优先停下来核对，不要直接 deploy。

如果需要字段规则、校验约束和示例，读取：

```
references/page-metadata.md
```

Page metadata is not simply "listing component names", but explicitly writing out the page assembly structure required by the user.

Process in this order:

First determine the page name, title, affiliated application, business unit, and version strategy.
Split the page into one or more component instances according to requirements.
Generate
```
<control>
```
for each instance.
```
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 specifications.
Only properties defined in component metadata can be written into
```
<propertys>
```
.

For example, if the

name

in the component metadata is

OverviewCard

, then

control.type

in the page metadata can only be written as

OverviewCard

. Do not arbitrarily write it as

kwc_OverviewCard

just because the component directory is under

app/kwc/

; such prefixes are not part of the component type name.

Default strategies for page fields:

```
template
```
uses
```
oneregion
```
by default
```
bizUnit
```
,
```
enableExtend
```
,
```
enablePermissionControl
```
are only filled in when explicitly required by the requirements
```
isv
```
and
```
app
```
are based on the main page information, and the control level is only filled in when overwriting is needed

The filling rules for

app

refer to the section "Inputs that Require User Provision or Confirmation". If it is found that the

app

in the page metadata is inconsistent with

.kd/config.json

, stop and check first instead of deploying directly.

If field rules, verification constraints, and examples are needed, read:

```
references/page-metadata.md
```

先判断当前所处阶段

First Judge the Current Stage

按这个顺序判断并推进：

若当前目录下不存在
```
.kd
```
，先视为“尚未初始化 KWC 工程”。
若用户要新建页面或组件，优先使用
```
kd project create
```
，不要手工拼目录结构。
若用户要部署或调试，先检查环境是否已经通过
```
kd env create
```
和
```
kd env auth openapi
```
完成配置。
若用户开始编写具体前端实现代码，先判断当前工程 framework，再建议转入对应框架的专用 Skill，不要把本 Skill 当成组件编码规范。

判断顺序：

新建工程：以
```
kd project init
```
中用户选择的 framework 作为推荐依据
已有工程：以
```
.kd/config.json.framework
```
作为推荐依据
```
react
```
-> 建议加载
```
kwc-react-development
```
```
vue
```
-> 建议加载
```
kwc-vue-development
```
```
lwc
```
-> 建议加载
```
kwc-lwc-development
```
若 framework 未知，先停下来确认，不要默认猜测

Judge and advance in this order:

If
```
.kd
```
does not exist in the current directory, it is regarded as "KWC project not initialized yet".
If the user wants to create a new page or component, prefer using
```
kd project create
```
instead of manually constructing the directory structure.
If the user wants to deploy or debug, first check whether the environment has been configured via
```
kd env create
```
and
```
kd env auth openapi
```
.
If the user starts writing specific front-end implementation code, first judge the framework of the current project, then recommend switching to the dedicated Skill for the corresponding framework, and do not treat this Skill as the component coding specification.

Judgment order:

New project: Use the framework selected by the user in
```
kd project init
```
as the recommendation basis
Existing project: Use
```
.kd/config.json.framework
```
as the recommendation basis
```
react
```
-> It is recommended to load
```
kwc-react-development
```
```
vue
```
-> It is recommended to load
```
kwc-vue-development
```
```
lwc
```
-> It is recommended to load
```
kwc-lwc-development
```
If the framework is unknown, stop and confirm first instead of guessing by default

执行前置检查

Perform Pre-Checks

本 Skill 基于

kd 0.0.9

验证，若 CLI 版本有较大变更，部分 workaround 可能不再适用。

先确认以下前提：

将
```
Project
```
理解为本地工程目录。
将
```
Env
```
理解为远端苍穹环境。
提醒用户本地需具备
```
node
```
、
```
npm
```
、
```
git
```
。
若命令需要联网安装 CLI 或依赖，再根据环境决定是否需要设置内网镜像。

This Skill is verified based on

kd 0.0.9

. If there are major changes in the CLI version, some workarounds may no longer be applicable.

First confirm the following prerequisites:

Treat
```
Project
```
as the local project directory.
Treat
```
Env
```
as the remote Sky environment.
Remind the user that
```
node
```
,
```
npm
```
, and
```
git
```
are required locally.
If the command requires network installation of CLI or dependencies, decide whether to set up an intranet mirror according to the environment.

初始化工程

Initialize the Project

在用户尚未拥有 KWC 工程时，按以下流程执行：

安装 CLI。
运行
```
kd project init <project-name>
```
。
在交互流程中按用户要求选择框架和语言；若用户未指定框架和语言，不要擅自假定，应主动询问用户选择。
输入应用标识
```
app
```
编码，这个值必须由用户手工提供。
初始化完成后进入项目目录，执行
```
npm install
```
。
仅在需要本地辅助预览组件时，再执行
```
npm run dev
```
。

若用户只是让你“创建一个 KWC 工程”，默认交付应至少覆盖：初始化命令、框架/语言选择、

app

编码输入、依赖安装，以及后续如何继续创建组件、页面元数据和部署。

如果用户没有提供

app

，遵循"需要用户提供或确认的输入"中的

app

规则，先停在初始化前让用户补齐。

补充：

kd project init

依赖

git clone

下载模板，若失败优先检查

git

、网络连通性和执行环境是否允许联网。更多实测细节见

references/validation-notes.md

。

When the user does not have a KWC project yet, follow this process:

Install the CLI.
Run
```
kd project init <project-name>
```
.
Select the framework and language as required by the user during the interaction process; if the user does not specify the framework and language, do not assume it arbitrarily and should actively ask the user to choose.
Enter the application identifier
```
app
```
code, which must be manually provided by the user.
After initialization is completed, enter the project directory and execute
```
npm install
```
.
Only execute
```
npm run dev
```
when local auxiliary preview of components is needed.

If the user only asks you to "create a KWC project", the default delivery should at least cover: initialization commands, framework/language selection,

app

code input, dependency installation, and how to continue creating components, page metadata, and deployment later.

If the user does not provide

app

, follow the

app

rules in "Inputs that Require User Provision or Confirmation" and stop before initialization to let the user supplement it.

Supplement:

kd project init

relies on

git clone

to download the template. If it fails, first check

git

, network connectivity, and whether the execution environment allows network access. For more actual measurement details, see

references/validation-notes.md

创建组件

Create Components

在已有项目中新增组件时：

运行

kd project create <ComponentName> --type kwc

。

使用
```
PascalCase
```
组件名。
让 CLI 生成目录和基础文件，再在生成结果上修改代码。
立刻检查生成出来的
```
.js-meta.kwc
```
，补齐可部署所需字段和属性定义。
若用户同时要创建多个组件，逐个执行创建命令，不要手工复制推断目录结构。

若用户只提供了页面结构想法，没有组件名，先根据语义生成稳定、可复用的组件名，再创建。若用户给的是完整业务诉求，而不是组件清单，先主动拆分组件职责，再批量创建。

补充：组件生成在

app/kwc/<ComponentName>/

下；脚手架生成的

.js-meta.kwc

只是模板，需按上述规则补齐。更多实测细节见

references/validation-notes.md

。

When adding new components to an existing project:

Run

kd project create <ComponentName> --type kwc

Use
```
PascalCase
```
for component names.
Let the CLI generate the directory and basic files, then modify the code based on the generated results.
Immediately check the generated
```
.js-meta.kwc
```
and complete the fields and property definitions required for deployment.
If the user wants to create multiple components at the same time, execute the creation command one by one instead of manually copying and inferring the directory structure.

If the user only provides ideas for the page structure but no component names, first generate stable, reusable component names based on semantics, then create them. If the user provides complete business requirements instead of a component list, first actively split component responsibilities, then create them in batches.

Supplement: Components are generated under

app/kwc/<ComponentName>/

; the

.js-meta.kwc

generated by the scaffolding is only a template and needs to be completed according to the above rules. For more actual measurement details, see

references/validation-notes.md

创建页面元数据

Create Page Metadata

页面元数据是最终交付链路的核心。环境在部署后会根据

page-meta.kwp

的

<controls>

来渲染页面包含的组件，因此这里不是可选步骤，而是页面交付的主入口。

在需要新增页面时：

运行

kd project create <page-name> --type page

。

打开
```
app/pages/<page-name>.page-meta.kwp
```
。
至少核对并填写
```
name
```
、
```
masterLabel
```
、
```
app
```
、
```
version
```
。
在
```
<controls>
```
中把页面实例和组件类型关联起来。
仅当该页面元数据文件有变更并准备重新上传时，手动将
```
version
```
加
```
1
```
。
将组件树、实例名和页面布局映射到 XML，而不是停留在“组件已经创建”这一步。

不要忽略以下约束：

```
type
```
是组件类型名，必须与组件元数据中的组件
```
name
```
完全一致，不能只做到语义对应或名称相近。
```
name
```
是组件实例名，需要在页面内唯一。
```
app
```
必须与当前苍穹应用编码一致。
```
isv
```
开发阶段可留空，deploy 时会自动从环境拉取并写入，不需要手工维护。

若需要字段规则、校验约束和示例，读取

references/page-metadata.md

。

补充：新生成的

page-meta.kwp

默认只包含注释掉的

<control>

模板，Skill 必须根据需求主动补全

<controls>

。更多实测细节见

references/validation-notes.md

。

Page metadata is the core of the final delivery link. After deployment, the environment will render the components contained in the page according to the

<controls>

page-meta.kwp

, so this is not an optional step but the main entry point for page delivery.

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 least check and fill in
```
name
```
,
```
masterLabel
```
,
```
app
```
, and
```
version
```
.
Associate page instances with component types in
```
<controls>
```
.
Manually increase
```
version
```
by 1 only when the page metadata file is changed and ready for re-upload.
Map the component tree, instance names, and page layout to XML instead of stopping at the step of "components have been created".

Do not ignore the following constraints:

```
type
```
is the component type name and must be exactly consistent with the component
```
name
```
in the component metadata, not just semantically corresponding or similar in name.
```
name
```
is the component instance name and must be unique within the page.
```
app
```
must be consistent with the current Sky application code.
```
isv
```
can be left blank during the development phase and will be automatically pulled from the environment and written during deploy, so no manual maintenance is needed.

If field rules, verification constraints, and examples are needed, read

references/page-metadata.md

Supplement: The newly generated

page-meta.kwp

only contains a commented-out

<control>

template by default, and the Skill must actively complete

<controls>

according to requirements. For more actual measurement details, see

references/validation-notes.md

脚手架命令的推荐编排

Recommended Orchestration of Scaffold Commands

当用户要新增一个完整 KWC 页面功能时，优先按这条顺序执行：

若无工程，执行
```
kd project init
```
对每个“会出现在页面里的组件”执行
```
kd project create <ComponentName> --type kwc
```
确认当前工程 framework；若后续进入代码实现，建议切换到对应框架开发 Skill
实现组件代码
先确认当前工程
```
.kd/config.json
```
里的
```
app
```
是用户手工输入的真实值，再补全这些组件的
```
.js-meta.kwc
```

执行

kd project create <page-name> --type page

补全页面
```
app/pages/<page-name>.page-meta.kwp
```
确认或创建目标环境
完成认证
若组件元数据或页面元数据有变更，执行
```
kd project deploy
```
需要联调时执行
```
kd debug
```

如果是修改已有页面：

先识别是改组件实现、改组件元数据、改页面元数据，还是三者都改
若组件元数据或页面元数据变更，部署前一定检查版本号
若仅是组件实现代码变更，且所有元数据文件未变，通常不需要
```
deploy
```
若仅是组件实现代码变更，优先执行
```
npm run build
```
；需要联调时再继续
```
kd debug
```

不要采用下面这些错误顺序：

先写页面元数据，再回头猜组件属性名
先 deploy，再补版本号
创建了组件后完全不检查
```
.js-meta.kwc
```
把所有组件都保留元数据，即使它们只是内部辅助组件

When the user wants to add a complete KWC page function, follow this order first:

If there is no project, execute
```
kd project init
```
Execute
```
kd project create <ComponentName> --type kwc
```
for each "component that will appear in the page"
Confirm the current project framework; if entering code implementation later, it is recommended to switch to the corresponding framework development Skill
Implement component code
First confirm that the
```
app
```
in the current project's
```
.kd/config.json
```
is the real value manually entered by the user, then complete the
```
.js-meta.kwc
```
of these components

Execute

kd project create <page-name> --type page

Complete the page
```
app/pages/<page-name>.page-meta.kwp
```
Confirm or create the target environment
Complete authentication
If component metadata or page metadata is changed, execute
```
kd project deploy
```
Execute
```
kd debug
```
when joint debugging is needed

If modifying an existing page:

First identify whether to modify component implementation, component metadata, page metadata, or all three
If component metadata or page metadata is changed, be sure to check the version number before deployment
If only component implementation code is changed and all metadata files are unchanged,
```
deploy
```
is usually not needed
If only component implementation code is changed, prefer executing
```
npm run build
```
; continue with
```
kd debug
```
when joint debugging is needed

Do not use the following wrong orders:

Write page metadata first, then guess component property names later
Deploy first, then supplement the version number
Create components and completely ignore checking
```
.js-meta.kwc
```
Retain metadata for all components even if they are only internal auxiliary components

配置环境

Configure the Environment

在部署前先完成环境配置：

使用
```
kd env create <env-name> --url <url>
```
创建环境别名。
使用
```
kd env auth openapi
```
走交互式认证。
若用户经常切换环境，可用
```
kd env set target-env <env-name>
```
设置默认环境。
必要时使用
```
kd env list
```
和
```
kd env info
```
检查当前配置。

优先采用

openapi

认证方式；

web

模式暂不作为默认路径。

如果目标环境不存在，或环境存在但尚未完成认证，先停下来收集这些字段：

环境别名
环境 URL
Client ID
Client Secret
Username

其中

data center

不属于预先手填字段，而属于“读取后选择”的字段：

先有环境 URL
再进入
```
kd env auth openapi
```
由脚手架读取该环境可用的数据中心列表
最后让用户从列表中选择

收集规则：

环境别名、环境 URL、Client ID、Client Secret、Username 这些值必须由用户手工提供
```
data center
```
不要让用户自由输入，应让脚手架读取候选项后再选择
不要使用历史环境中的凭据去猜测新环境
不要因为存在
```
dev
```
、
```
sit
```
、
```
base
```
等别名，就自动推断这次要绑定哪个环境

交互方式规则：

不要假设当前一定支持弹窗或表单式输入
在当前常规模式下，先让用户回填手工字段，再在
```
kd env auth openapi
```
的交互里选择数据中心
若运行环境明确支持结构化选择工具，可以在读到数据中心列表后把候选项展示给用户选择
即便如此，Client Secret 这类自由文本仍应让用户手填

推荐向用户索要环境信息的格式：

text

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

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

补充：环境配置保存在

~/.kd

而非项目目录；创建后必须用

kd env list

复核是否持久化成功；

kd env auth openapi

在 URL 不可达时会直接失败。更多实测细节见

references/validation-notes.md

。

Complete environment configuration before deployment:

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, use
```
kd env set target-env <env-name>
```
to set the default environment.
Use
```
kd env list
```
and
```
kd env info
```
to check the current configuration when necessary.

Prioritize using the

openapi

authentication method; the

web

mode is not used as the default path for now.

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

Environment alias
Environment URL
Client ID
Client Secret
Username

Among them,

data center

is not a pre-filled field but a field that is "selected after reading":

First have the environment URL
Then enter
```
kd env auth openapi
```
The scaffolding reads the list of available data centers in the environment
Finally, let the user select from the list

Collection rules:

Environment alias, environment URL, Client ID, Client Secret, and Username must be manually provided by the user
Do not let the user freely enter
```
data center
```
; instead, let the scaffolding read the candidates before selection
Do not use credentials from historical environments to guess new environments
Do not automatically infer which environment to bind this time just because aliases like
```
dev
```
,
```
sit
```
, and
```
base
```
exist

Interaction rules:

Do not assume that pop-up windows or form-based input are currently supported
In the current regular mode, first let the user fill in the manual fields, then select the data center in the interaction of
```
kd env auth openapi
```
If the running environment clearly supports structured selection tools, the candidates can be displayed to the user for selection after reading the data center list
Even so, free-text fields like Client Secret should still be filled in manually by the user

Recommended format for requesting environment information from the user:

text

Please supplement the following environment information:
1. env name:
2. env url:
3. client id:
4. client secret:
5. username:

Note: data center does not need to be filled in first; candidates will be read by the scaffolding for selection later.

Supplement: Environment configurations are saved in

~/.kd

instead of the project directory; after creation, be sure to use

kd env list

to review whether the persistence is successful;

kd env auth openapi

will fail directly if the URL is unreachable. For more actual measurement details, see

references/validation-notes.md

部署与调试

Deployment and Debugging

不要把

kd project deploy

当成“每次改代码后都要跑”的固定步骤。

deploy

的核心作用是把元数据上传到目标环境，因此只有组件元数据

.js-meta.kwc

或页面元数据

.page-meta.kwp

发生变更时，才需要考虑

deploy

。

常用命令：

```
kd project deploy
```
：部署整个项目到默认环境

kd project deploy -d app/kwc/MyComponent -e sit

：仅部署指定组件到

sit

kd project deploy -d app/pages/MyPage -e sit

：仅部署指定页面元数据到

sit

```
kd debug
```
：进入调试

若需要指定环境或表单，使用

kd debug -e <env-name>

或

kd debug -f <formid>

版本管理规则：

只改组件实现代码，如
```
.tsx
```
、
```
.vue
```
、
```
.js
```
、
```
.html
```
、
```
.scss
```
，且没有改任何元数据文件：不需要
```
deploy
```
，也不要递增
```
version
```
改了组件元数据
```
.js-meta.kwc
```
：递增该组件元数据的
```
version
```
，再部署该组件或整个项目
改了页面元数据
```
.page-meta.kwp
```
：递增该页面元数据的
```
version
```
，再部署该页面元数据或整个项目
同时改了组件元数据和页面元数据：分别递增各自
```
version
```
，再部署受影响路径或整个项目
新建组件元数据或页面元数据：初始
```
version
```
设为
```
1
```
，首次上传时执行
```
deploy
```

判断原则：

是否需要
```
deploy
```
，先看元数据文件是否变更，不要只因为“刚改过代码”就默认部署
是否需要递增
```
version
```
，也先看对应元数据文件是否变更，不要因为构建、调试或纯代码改动而递增
若只是组件代码改动，优先
```
npm run build
```
；需要联调时继续
```
kd debug
```

遇到跨应用调试时，优先检查

.kd/config.json

里的

app

编码是否需要手工切换。

补充：环境未认证时

kd project deploy

会直接阻止部署；

kd debug -e <env> -f <formid>

在部分版本中可能异常，更稳妥的路径是先

kd env set target-env <env>

再执行

kd debug -f <formid>

。更多实测细节见

references/validation-notes.md

。

Do not treat

kd project deploy

as a fixed step that "must be run every time code is changed". The core function of

deploy

is to upload metadata to the target environment, so

deploy

only needs to be considered when component metadata

.js-meta.kwc

or page metadata

.page-meta.kwp

changes.

Common commands:

```
kd project deploy
```
: Deploy the entire project to the default environment

kd project deploy -d app/kwc/MyComponent -e sit

: Only deploy the specified component to

sit

kd project deploy -d app/pages/MyPage -e sit

: Only deploy the specified page metadata to

sit

```
kd debug
```
: Enter debugging mode

To specify an environment or form, use

kd debug -e <env-name>

kd debug -f <formid>

Version management rules:

Only modify component implementation code, such as
```
.tsx
```
,
```
.vue
```
,
```
.js
```
,
```
.html
```
,
```
.scss
```
, and no metadata files are changed: No need for
```
deploy
```
, and no need to increment
```
version
```
Modify component metadata
```
.js-meta.kwc
```
: Increment the
```
version
```
of the component metadata, then deploy the component or the entire project
Modify page metadata
```
.page-meta.kwp
```
: Increment the
```
version
```
of the page metadata, then deploy the page metadata or the entire project
Modify both component metadata and page metadata: Increment their respective
```
version
```
s, then deploy the affected paths or the entire project
Create new component metadata or page metadata: Set the initial
```
version
```
to
```
1
```
, and execute
```
deploy
```
during the first upload

Judgment principles:

Whether
```
deploy
```
is needed depends on whether metadata files are changed, not just because "code has just been modified"
Whether
```
version
```
needs to be incremented also depends on whether the corresponding metadata file is changed, not because of build, debugging, or pure code changes
If only component code is modified, prefer executing
```
npm run build
```
; continue with
```
kd debug
```
when joint debugging is needed

When debugging across applications, first check whether the

app

code in

.kd/config.json

needs to be manually switched.

Supplement:

kd project deploy

will be directly blocked if the environment is not authenticated;

kd debug -e <env> -f <formid>

may be abnormal in some versions, and a more reliable path is to first execute

kd env set target-env <env>

and then execute

kd debug -f <formid>

. For more actual measurement details, see

references/validation-notes.md

端到端执行原则

End-to-End Execution Principles

当用户说“帮我开发一个 KWC 页面/功能”时，默认按这条链路推进：

识别是新工程还是已有工程
收集不可推断的环境输入
拆分组件并创建组件工程
实现组件代码
创建并补全页面元数据
配置环境并确认认证状态
若元数据有变更，执行
```
deploy
```
必要时执行
```
debug
```

不要只完成其中的“创建组件”或“本地跑起来”，除非用户明确只要某个局部步骤。

When the user says "Help me develop a KWC page/function", follow this link by default:

Identify whether it is a new project or an existing project
Collect environment inputs that cannot be inferred
Split components and create component projects
Implement component code
Create and complete page metadata
Configure the environment and confirm the authentication status
If metadata is changed, execute
```
deploy
```
Execute
```
debug
```
when necessary

Do only complete "component creation" or "run locally" unless the user explicitly only wants a partial step.

输出要求

Output Requirements

输出方案或执行命令时，尽量同时给出：

用户还需要补充哪些关键输入
当前处于哪个阶段
下一条应执行的命令
是否依赖已有环境认证
是否需要修改
```
page-meta.kwp
```
页面元数据将如何组合组件
是否真的需要
```
deploy
```
若需要部署，是否因为元数据变更而必须递增
```
version
```

When outputting solutions or execution commands, try to provide the following at the same time:

Which key inputs the user still needs to supplement
Which stage is currently in
The next command to be executed
Whether it depends on existing environment authentication
Whether
```
page-meta.kwp
```
needs to be modified
How the page metadata will combine components
Whether
```
deploy
```
is really needed
If deployment is needed, whether
```
version
```
must be incremented due to metadata changes

常见失误

Common Mistakes

优先排查这些问题：

在非 KWC 工程目录里直接执行
```
kd project create
```
创建了页面但没有把组件写入
```
<controls>
```
```
type
```
和真实组件名不一致
```
app
```
编码与目标应用不一致
页面元数据重复上传但未递增
```
version
```
只改了组件代码，却误以为必须立刻
```
deploy
```
只创建了组件，却没有把组件写进页面元数据
元数据已经变更，却只做了本地预览，没有继续
```
deploy
```
未认证环境就直接执行
```
deploy
```
或
```
debug
```

Prioritize troubleshooting these issues:

Directly execute
```
kd project create
```
in a non-KWC project directory
Create a page but do not write components into
```
<controls>
```
```
type
```
is inconsistent with the real component name
```
app
```
code is inconsistent with the target application
Page metadata is uploaded repeatedly but
```
version
```
is not incremented
Only modify component code but mistakenly think that
```
deploy
```
must be done immediately
Only create components but do not write them into page metadata
Metadata has been changed but only local preview is done without continuing to
```
deploy
```
Execute
```
deploy
```
or
```
debug
```
directly without authenticating the environment

参考资料

Reference Materials

在需要精确命令、参数说明、OpenAPI 字段说明和 page-meta 示例时，读取：

```
references/cli-reference.md
```
```
references/component-metadata.md
```
```
references/env-setup.md
```
```
references/page-metadata.md
```
```
references/validation-notes.md
```

When precise commands, parameter descriptions, OpenAPI field descriptions, and page-meta examples are needed, read:

```
references/cli-reference.md
```
```
references/component-metadata.md
```
```
references/env-setup.md
```
```
references/page-metadata.md
```
```
references/validation-notes.md
```