KWC Project Scaffold

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

正确认知交付对象

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

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

页面最终展示依赖页面元数据中的 <controls> 和组件类型映射，而不是本地 main.tsx 是否挂载了某个组件。 main.tsx 和 npm run dev 只用于本地辅助预览，不是最终交付路径。

元数据优先的开发模型

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

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

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

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

默认原则：

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

先把需求翻译成工程目标

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

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

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

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

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

• 项目名或现有项目路径
• 框架和语言
• 苍穹应用编码 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
• 不要因为当前环境里存在某个应用就自动代入

由 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 规则。

从需求生成组件元数据

当用户要“开发一个页面功能”时，不要等到最后才补 .js-meta.kwc。 应在组件职责确定后，立即判断组件元数据应如何生成。

按这个顺序处理：

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

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

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

属性设计原则：

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

只有当页面需要给组件实例传值时，才在组件元数据里声明 <property>。 页面元数据 <propertys> 中出现的属性名，必须能在组件元数据里找到对应定义。

app 的填写规则见"需要用户提供或确认的输入"一节；若当前工程无可信 app，不要生成正式可部署元数据。

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

• references/component-metadata.md

从需求生成页面元数据

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

按这个顺序处理：

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

页面字段默认策略：

• template 默认使用 oneregion
• bizUnit、enableExtend、enablePermissionControl 仅在需求明确时填写
• isv、app 以页面主信息为主，控制级别只有在需要覆盖时才填写

app 的填写规则见"需要用户提供或确认的输入"一节。若发现页面元数据 app 与 .kd/config.json 不一致，优先停下来核对，不要直接 deploy。

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

• references/page-metadata.md

先判断当前所处阶段

按这个顺序判断并推进：

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

执行前置检查

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

先确认以下前提：

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

初始化工程

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

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

若用户只是让你“创建一个 KWC 工程”，默认交付应至少覆盖：初始化命令、框架/语言选择、app 编码输入、依赖安装，以及后续如何继续创建组件、页面元数据和部署。

如果用户没有提供 app，遵循"需要用户提供或确认的输入"中的 app 规则，先停在初始化前让用户补齐。

补充：kd project init 依赖 git clone 下载模板，若失败优先检查 git、网络连通性和执行环境是否允许联网。更多实测细节见 references/validation-notes.md。

创建组件

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

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

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

补充：组件生成在 app/kwc/<ComponentName>/ 下；脚手架生成的 .js-meta.kwc 只是模板，需按上述规则补齐。更多实测细节见 references/validation-notes.md。

创建页面元数据

页面元数据是最终交付链路的核心。 环境在部署后会根据 page-meta.kwp 的 <controls> 来渲染页面包含的组件，因此这里不是可选步骤，而是页面交付的主入口。

在需要新增页面时：

1. 运行 kd project create <page-name> --type page。
2. 打开 app/pages/<page-name>.page-meta.kwp。
3. 至少核对并填写 name、masterLabel、app、version。
4. 在 <controls> 中把页面实例和组件类型关联起来。
5. 每次重新上传页面元数据前，手动将 version 加 1。
6. 将组件树、实例名和页面布局映射到 XML，而不是停留在“组件已经创建”这一步。

不要忽略以下约束：

• type 是组件类型名，必须与实际组件对应。
• name 是组件实例名，需要在页面内唯一。
• app 必须与当前苍穹应用编码一致。
• isv 开发阶段可留空，deploy 时会自动从环境拉取并写入，不需要手工维护。

若需要字段规则、校验约束和示例，读取 references/page-metadata.md。

补充：新生成的 page-meta.kwp 默认只包含注释掉的 <control> 模板，Skill 必须根据需求主动补全 <controls>。更多实测细节见 references/validation-notes.md。

脚手架命令的推荐编排

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

1. 若无工程，执行 kd project init
2. 对每个“会出现在页面里的组件”执行 kd project create <ComponentName> --type kwc
3. 实现组件代码
4. 先确认当前工程 .kd/config.json 里的 app 是用户手工输入的真实值，再补全这些组件的 .js-meta.kwc
5. 执行 kd project create <page-name> --type page
6. 补全页面 app/pages/<page-name>.page-meta.kwp
7. 确认或创建目标环境
8. 完成认证
9. 执行 kd project deploy
10. 需要联调时执行 kd debug

如果是修改已有页面：

1. 先识别是改组件实现、改组件元数据、改页面元数据，还是三者都改
2. 若组件元数据或页面元数据变更，部署前一定检查版本号
3. 若仅是内部组件实现变更，但该组件仍有 .js-meta.kwc，它依然会随 deploy 上传

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

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

配置环境

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

1. 使用 kd env create <env-name> --url <url> 创建环境别名。
2. 使用 kd env auth openapi 走交互式认证。
3. 若用户经常切换环境，可用 kd env set target-env <env-name> 设置默认环境。
4. 必要时使用 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 这类自由文本仍应让用户手填

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

请补充以下环境信息：
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。

部署与调试

在完成组件和页面元数据后，默认要把交付链路推进到部署，而不是停在本地代码层面：

1. 运行 kd project deploy 部署整个项目。
2. 若用户只想部署某个组件，使用 kd project deploy -d <path> -e <env-name>。
3. 运行 kd debug 进入调试。
4. 若需要指定环境或表单，使用 kd debug -e <env-name> 或 kd debug -f <formid>。

遇到跨应用调试时，优先检查 .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。

端到端执行原则

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

1. 识别是新工程还是已有工程
2. 收集不可推断的环境输入
3. 拆分组件并创建组件工程
4. 实现组件代码
5. 创建并补全页面元数据
6. 配置环境并确认认证状态
7. 执行 deploy
8. 必要时执行 debug

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

输出要求

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

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

常见失误

优先排查这些问题：

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

参考资料

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

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