kwc-project-scaffold（kwc 项目脚手架）

KWC Project Scaffold

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

正确认知交付对象

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

1. 组件工程本身（前端代码 + 组件元数据 .js-meta.kwc）
2. 页面元数据 *.page-meta.kwp
3. KS Controller 元数据 *.kws 和脚本代码（当功能涉及后端数据交互时）
4. 目标环境配置与认证
5. 通过 kd project deploy 上传后的环境渲染结果

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

KWC 不仅是前端开发框架。当页面需要读取或操作业务数据时，KS Controller 提供后端 REST API 能力，通过 KingScript 脚本访问苍穹平台的数据查询、业务操作等服务。一个完整的业务功能通常包含前端组件（展示与交互）和后端 Controller（数据获取与业务逻辑）两部分。

Controller 也遵循"元数据 + 代码"的二元模型：

• Controller 元数据（.kws）：定义路由 URL、HTTP 方法、权限策略等声明式配置
• Controller 脚本代码（.ts）：实现具体的业务逻辑

这与前端的"组件元数据.kwc + 组件代码"模式完全对称。

元数据驱动的全栈开发模型

从用户开发角度看，一个完整的 KWC 功能最多涵盖以下层次：

前端（展示与交互）：

1. 组件代码（*.tsx / *.vue / *.js）：负责渲染和交互逻辑
2. 组件元数据 .js-meta.kwc：声明"这个组件可以被页面如何引用、可以暴露哪些可配置属性"
3. 页面元数据 .page-meta.kwp：声明"这个页面由哪些组件实例组成，并给每个实例传什么属性值"

后端（数据与业务逻辑）： 4. Controller 元数据 .kws：声明"这个 Controller 暴露哪些 API 端点、使用什么 HTTP 方法、需要什么权限" 5. Controller 脚本代码（*.ts）：实现具体的数据查询、业务操作等后端逻辑

前端和后端都遵循"元数据先行、代码实现跟进"的模式——先声明结构和契约，再填充实现。

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

• 哪些参数是写死在组件代码里的
• 哪些参数需要暴露给页面配置者，通过组件元数据定义为 <property>
• 哪些组件实例会出现在页面元数据的 <controls> 中
• 组件是否需要调用后端 API 获取数据或提交操作
• 若需要，Controller 元数据（.kws）需要定义哪些 API 端点（URL、HTTP 方法、权限）
• Controller 脚本需要调用哪些 SDK 能力（数据查询、业务操作等）

默认原则：

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

先把需求翻译成工程目标

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

1. 是否需要新建工程，还是在已有工程里继续开发
2. 需要几个组件，各自承担什么职责
3. 组件是否需要后端数据支持？若需要，规划对应的 KS Controller 和 API 方法
4. 需要几个页面元数据文件，页面里如何组合这些组件
5. 最终要部署到哪个环境

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

框架开发 Skill 协作

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

硬性约束：代码实现必须移交框架 Skill

当任务进入"实现组件代码"阶段时，必须遵循以下强制规则：

1. 禁止直接编写代码：本 Skill 严禁直接编写、修改任何组件实现代码（*.tsx / *.vue / *.js）和 Controller 脚本代码（*.ts）
2. 必须先加载对应 Skill：前端代码加载框架开发 Skill（kwc-react/vue/lwc-development），Controller 代码加载 kwc-ks-controller-development
3. 禁止凭通用知识自行编写：KingScript 运行时的 request/response API 与 Node.js / Java Servlet 完全不同，凭通用经验编写的代码将部署失败
4. 多环节任务不是例外：即使当前任务涉及工程搭建 + 元数据 + Controller + 前端组件多个环节，每进入一个代码编写阶段都必须切换 Skill，不可"一口气"跳过
5. 框架识别依据：

- 新建工程：以 kd project init 时用户选择的 framework 为准 - 已有工程：以 .kd/config.json 中的 framework 字段为准 - 若无法识别 framework，必须停止并向用户确认，禁止猜测

协作边界表

切换时机

• 当任务仍处于需求拆分、脚手架命令、元数据、环境、deploy、open、debug 阶段时，继续由本 Skill 主导
• 当 kd project create 完成后需写代码 → 必须切到框架 Skill，禁止本 Skill 直接编写
• 当代码写完需补元数据或部署 → 回到 scaffold
• 当 Controller 目录已创建且需要编写脚本代码 → 必须切到 kwc-ks-controller-development，禁止本 Skill 直接编写
• 当 Controller 脚本代码写完需构建或部署 → 回到 scaffold

异常流程保护

当 CLI 命令失败（如 kd project create 报错）而改用手动方式创建文件/目录时，代码编写阶段的 Skill 切换规则同样适用。手动创建目录结构不等于可以手动编写业务代码。

• 只要进入 .ts / .tsx / .vue / .js 文件的编写，无论前置步骤是否通过 CLI 完成，都必须先切换到对应的框架 Skill
• 典型场景：kd project create 失败 → 手动创建 app/kwc/MyComponent/ 目录和 .js-meta.kwc → 到这里仍是 scaffold 职责 → 开始写 MyComponent.tsx 时 → 必须切换到框架 Skill
• Controller 同理：手动创建 app/ks/controller/ 目录和 .kws → scaffold 职责 → 开始写 .ts 脚本 → 必须切换到 kwc-ks-controller-development

框架 Skill 激活检查清单

在进入代码实现阶段前，确认以下事项：

• 已识别当前工程 framework（react/vue/lwc）
• 已调用对应的框架开发 Skill（kwc-*-development）
• 框架 Skill 的 rule.md 约束已加载并生效
• 本 Skill 不再直接处理任何代码文件内容

推荐规则

1. 若是新建工程，以 kd project init 交互中用户选择的 framework 作为后续推荐 Skill 依据
2. 若是已有工程，以 .kd/config.json 中的 framework 作为推荐 Skill 依据
3. 当 framework=react 时，必须转入 kwc-react-development
4. 当 framework=vue 时，必须转入 kwc-vue-development
5. 当 framework=lwc 时，必须转入 kwc-lwc-development
6. 若还无法判断 framework，先停下来向用户确认
7. 当任务涉及 Controller/脚本控制器代码编写时，必须转入 kwc-ks-controller-development
8. Controller 代码实现与前端框架无关，不受 framework 字段影响

注意：不要同时加载三个框架开发 Skill；只根据当前工程的 framework 推荐一个。

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

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

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

这些信息不要擅自编造，尤其是 app、环境 URL、认证参数和最终部署环境。

关于 isv（开发商标识）：开发阶段可以留空，在组件与环境绑定时会从环境拉取开发商标识，kd project deploy 时会自动写入组件和页面元数据，因此不需要用户手工提供或维护。

对 app 使用最严格的规则（本节为全文唯一权威定义）：

• app 必须由用户明确提供，或来自 .kd/config.json
• 不可猜测、不可使用示例值
• 新建工程时在 kd project init 交互中输入
• 若无 app，不继续生成元数据或部署

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

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

• 将业务需求拆成组件列表
• 为组件生成稳定的 PascalCase 名称
• 为页面和实例生成符合规范的小写标识
• 判断组件是否需要保留 .js-meta.kwc，还是应删除以避免被当成可部署组件
• 将需求映射为组件元数据里的 <property>
• 为页面生成 page-meta.kwp 并填充 <controls>
• 为页面中的每个组件实例生成唯一 name
• 判断当前该执行 init、create、deploy、open 还是 debug
• 查看环境效果时结合当前任务和页面元数据，自行判断使用 kd open 的目标页面；仅当用户明确要求本地联调时才使用 kd 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

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

• references/component-metadata.md

从需求生成页面元数据

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

按这个顺序处理：

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

例如，若组件元数据中的 name 是 OverviewCard，则页面元数据里的 control.type 只能写 OverviewCard。 不要因为组件目录在 app/kwc/ 下，就擅自写成 kwc_OverviewCard；这类前缀不是组件类型名的一部分。

页面字段默认策略：

• masterLabel：页面的中文名称（如「销售订单」「采购申请」「库存查询」），作为页面在导航和管理界面的显示标题
• template 默认使用 oneregion
• isv deploy 时自动写入，无需手填
• app 规则见“需要用户提供或确认的输入”一节

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

• references/page-metadata.md

先判断当前所处阶段

按这个顺序判断并推进：

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

执行前置检查

先确认以下前提：

• 将 Project 理解为本地工程目录。
• 将 Env 理解为远端苍穹环境。
• 提醒用户本地需具备 node、npm、git。

初始化工程

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

1. 安装 CLI。
2. 运行 kd project init <project-name>。
3. 在交互流程中按用户要求选择框架和语言；若用户未指定，应主动询问。
4. 输入应用标识 app（规则见“需要用户提供或确认的输入”一节）。
5. 初始化完成后进入项目目录，执行 npm install。
6. 仅在需要本地辅助预览组件时，再执行 npm run dev。

补充：kd project init 依赖 git clone 下载模板，若失败优先检查 git。

创建组件

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

1. 运行 kd project create <ComponentName> --type kwc。
2. 使用 PascalCase 组件名。
3. 让 CLI 生成目录和基础文件。
4. 立刻检查生成出来的 .js-meta.kwc，补齐可部署所需字段和属性定义（这是本 Skill 的职责）。
5. 组件代码实现移交：确认 .js-meta.kwc 补齐后，必须停止本 Skill 的代码编写，转而加载对应的框架开发 Skill（kwc-react-development / kwc-vue-development / kwc-lwc-development）来编写组件实现代码。
6. 若用户同时要创建多个组件，逐个执行创建命令，不要手工复制推断目录结构。

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

补充：

• 组件生成在 app/kwc/<ComponentName>/ 下
• 脚手架生成的 .js-meta.kwc 只是模板，需按上述规则补齐
• **严禁在本 Skill 中直接修改组件代码文件（*.tsx / *.vue / *.js），代码实现必须交由框架 Skill**

创建 Controller

在已有项目中新增 KingScript 脚本控制器时：

1. 运行 kd project create <ControllerName> --type controller。
2. 使用 PascalCase 控制器名，建议以 Controller 后缀结尾。
3. 让 CLI 生成目录和基础文件。Controller 工程生成在 app/ks/controller/<ControllerName>/ 下。
4. 创建后检查生成的.kws 元数据文件，补齐必填字段（name/isv/app/version/url/scriptFile/methods）。
5. Controller 代码实现移交：确认.kws 元数据补齐后，必须停止本 Skill 的代码编写，转而加载 kwc-ks-controller-development 来编写控制器脚本代码。
6. 若需指定拉取 SDK 的目标环境，可使用 -e 选项：kd project create <ControllerName> --type controller -e dev。

补充：

• Controller 与前端组件（KWC）是独立的工程实体，可以在同一个项目中共存
• 脚手架生成的.kws 元数据只是模板，需按控制器开发指南补齐
• **严禁在本 Skill 中直接修改 Controller 脚本代码（*.ts），代码实现必须交由 kwc-ks-controller-development**

创建页面元数据

页面元数据是最终交付链路的核心。 环境在部署后会根据 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 完全一致，不能只做到语义对应或名称相近。
• name 是组件实例名，需要在页面内唯一。
• isv 开发阶段可留空，deploy 时会自动从环境拉取并写入
• app 规则见“需要用户提供或确认的输入”一节

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

补充：新生成的 page-meta.kwp 默认只包含注释掉的 <control> 模板，Skill 必须根据需求主动补全 <controls>。

脚手架命令的推荐编排

需求前后端评估

面对完整业务需求时，按以下优先级判断是否需要 Controller：

强信号（命中任意一条即直接判定需要 Controller，无需询问用户）：

• 需求涉及列表/表格数据展示（如"XX列表"、"XX查询"、"XX监控"）
• 需求涉及筛选/搜索/过滤条件
• 需求涉及图表/报表/统计/仪表盘
• 需求涉及数据的增删改操作（保存、提交、审核、删除等）
• 需求涉及详情查看/编辑
• 需求涉及业务实体名称（如物料、仓库、订单、客户、库存等）

弱信号（需要询问用户确认）：

• 需求仅描述了 UI 样式或布局，未提及数据来源
• 需求可能通过本地 mock 数据或配置项完成

排除信号（不需要 Controller）：

• 页面仅展示静态内容、说明文档或本地计算结果
• 纯展示型组件（如欢迎页、关于页）

默认倾向：当需求描述中出现任何业务数据相关的词汇时，优先判定需要 Controller，而非询问用户。

实体识别与澄清

判定需要 Controller 后，必须进一步识别需求涉及哪些业务实体，用于后续 meta-query-api.mjs 查询真实字段：

1. 从需求中提取实体关键词：分析用户需求描述，提取所有可能的业务实体名称（如"物料"、"仓库"、"库存"、"订单"等）
2. 确认表单编码来源：表单/实体编码禁止猜测，只能通过以下两种方式获取：

- 用户直接提供：用户在需求中明确给出了表单编码（如 bd_material、im_inventory） - 通过查询确认：使用 queryFormsByApp 搜索表单，从返回结果中确认真实编码

1. 向用户澄清实体：若用户未提供表单编码，且实体名称可能存在歧义（如"库存"可能对应库存台账、库存余额、安全库存等不同表单），必须主动向用户确认：

- "您提到的'库存'对应的是哪个业务表单？请提供表单编码或名称，以便查询准确的字段结构" - 若实体名称无歧义且用户也不确定编码，可先用 queryFormsByApp 按关键词搜索，将结果展示给用户选择

1. 确认后再查询字段：只有在明确了表单编码后，才执行 getEntityFields 查询字段结构

前后端统一编排

当需求同时涉及前端组件和后端 Controller 时，按以下流程执行（元数据先于代码）：

1. 若无工程，执行 kd project init
2. 创建工程结构（本 Skill 职责）： a. 对每个前端组件执行 kd project create <ComponentName> --type kwc b. 对每个后端 Controller 执行 kd project create <ControllerName> --type controller
3. 查询业务实体字段（当 Controller 涉及实体数据操作时）：

- 用户提供了表单名称/编码/实体相关信息时，使用 meta-query-api.mjs 查询真实字段 - 先 queryFormsByApp 搜索表单，再 getEntityFields 获取字段结构（见「元数据查询」章节） - 查询结果用于指导后续 Controller 元数据和代码编写，禁止猜测字段名

1. 补全所有元数据（本 Skill 职责，元数据先行）： a. 补全组件元数据 .js-meta.kwc b. 补全 Controller 元数据 .kws（定义 URL、方法、权限配置）
2. 移交前端代码实现：加载框架开发 Skill 编写组件代码（*.tsx / *.vue / *.js）
3. 移交后端代码实现：加载 kwc-ks-controller-development 编写 Controller 脚本（*.ts）
4. 回到本 Skill：创建页面元数据并补全 <controls>
5. 构建前端：npm run build:frontend
6. 确认或创建目标环境，完成认证
7. 执行 kd project deploy
8. 部署成功后，调用 form-link.mjs 输出渲染卡片（见「部署完成标准输出」章节）

关键原则：

• 步骤 4（元数据补全）中，组件元数据 .kwc + Controller 元数据 .kws 都由本 Skill 完成
• 步骤 5-6（代码实现）分别移交给对应的开发 Skill，本 Skill 严禁直接编写代码
• 步骤 7 起回到本 Skill 主导

仅前端编排

若确认不涉及后端，仅前端开发时，优先按这条顺序执行：

1. 若无工程，执行 kd project init
2. 对每个"会出现在页面里的组件"执行 kd project create <ComponentName> --type kwc
3. 补全组件 .js-meta.kwc（本 Skill 职责）
4. 查询关联业务实体（可选，当组件涉及表单数据绑定时）：使用 meta-query-api.mjs 查询关联表单的字段结构，辅助组件设计（见「元数据查询」章节）
5. 移交代码实现：确认当前工程 framework，必须加载并切换到对应框架开发 Skill（kwc-react-development / kwc-vue-development / kwc-lwc-development）
6. 框架 Skill 实现组件代码（*.tsx / *.vue / *.js）
7. 代码实现完成后，回到本 Skill：执行 kd project create <page-name> --type page
8. 补全页面 app/pages/<page-name>.page-meta.kwp
9. 确认或创建目标环境，完成认证
10. 构建前端：npm run build:frontend
11. 若元数据有变更或需要更新环境上的静态文件，执行 kd project deploy（部署到开发环境时会同时上传前端静态文件）
12. 当次任务所有部署完成后，调用 form-link.mjs 输出渲染卡片（见「部署完成标准输出」，不可跳过）
13. 仅当用户明确要求查看效果时执行 kd open，明确要求本地联调时执行 kd debug（须后台模式）

关键原则：

• 步骤 3（元数据补全）必须由本 Skill 完成
• 步骤 5-6（代码实现）必须由框架 Skill 完成，本 Skill 严禁直接编写代码
• 步骤 7 起（页面创建及后续）回到本 Skill 主导

如果是修改已有页面：

1. 先识别是改组件实现、改组件元数据、改页面元数据，还是三者都改
2. 若涉及组件代码修改：必须加载对应框架 Skill，禁止本 Skill 直接修改代码
3. 参考"是否需要 deploy 决策"决定后续操作

仅后端 Controller 编排

若确认仅涉及后端，不需要新增前端组件时：

1. 若无工程，执行 kd project init
2. 执行 kd project create <ControllerName> --type controller 创建 Controller
3. 查询业务实体字段（当 Controller 涉及实体数据操作时）：使用 meta-query-api.mjs 先搜索表单再获取字段结构（见「元数据查询」章节），禁止猜测字段名
4. 补全 Controller 元数据 .kws（本 Skill 职责）
5. 移交代码实现：必须加载并切换到 kwc-ks-controller-development
6. controller-development Skill 编写脚本代码（*.ts）
7. 代码实现完成后，回到本 Skill：执行 kd project deploy 部署到目标环境（Controller 无需预先 build）
8. 当次任务所有部署完成后，调用 form-link.mjs 输出渲染卡片（见「部署完成标准输出」，不可跳过）

配置环境

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

环境存在性检查

当用户提供了具体的环境名称或别名（如 dev、sit、uat 等）时，应先执行环境存在性检查：

1. 运行 kd env list 查看当前已配置的环境列表
2. 若目标环境已存在于列表中：

- 不需要再让用户提供 URL、Client ID/Secret 等环境信息 - 直接使用该环境进行后续操作（如 deploy、debug） - 若该环境不是当前默认环境，可通过 kd env set target-env <name> 切换 - 使用 kd env info 确认环境认证状态

1. 只有当环境不存在时，才进入完整的环境创建和认证流程

新建环境流程

当环境不存在时，按以下流程执行：

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 不可达时会直接失败。

部署与调试

构建命令

开发阶段只需要构建前端，Controller 由 deploy 直接处理：

补充用法：

• npm run build:frontend -- MyComponent：构建指定前端组件
• npm run build:controller：仅用于生产环境构建 Controller 产物，开发阶段不需要
• npm run build：全量构建（前端 + Controller），仅用于生产环境

是否需要 deploy 决策

改了什么？
├── 只改前端代码（.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

常用命令

1. kd project deploy：一次性部署整个项目的所有元数据（.js-meta.kwc +.page-meta.kwp +.kws）和前端静态文件到默认环境；开发阶段 Controller 由 deploy 直接处理，无需预先 build
2. kd project deploy -d app/kwc/MyComponent -e sit：仅部署指定组件到 sit
3. kd project deploy -d app/pages/my_page -e sit：仅部署指定页面元数据到 sit
4. kd project deploy -d app/ks/controller/MyController -e sit：仅部署指定 Controller 到 sit
5. kd open -e dev -f kdtest_demo_page：部署后直接打开环境上的表单查看效果（无 DNS 代理）
6. kd debug：进入本地调试，通过 DNS 代理连接环境（必须使用 is_background: true 运行，仅当用户明确要求调试时使用）

部署完成标准输出

每当 AI 完成一段工作并且部署成功后，必须调用 form-link.mjs 脚本生成渲染卡片并输出给用户，展示已部署页面的访问入口。渲染卡片是用户触发预览效果的入口。

关键规则：

• 完成即输出：每完成一段可预览的工作（该段涉及的所有 deploy 均已成功），立即输出渲染卡片。多轮对话中，每段完成的工作都应有渲染卡片输出，不要攒到最后才输出
• 同一段工作内不重复：如果一段工作涉及多次 deploy（如先部署组件、再部署页面、再部署 Controller），应在该段全部部署完成后输出一次，不要每执行一条 deploy 命令就输出一次
• 适用于任何 deploy 形式：整体部署（kd project deploy）、指定路径部署（-d app/kwc/...、-d app/pages/...、-d app/ks/controller/...）

调用命令

# 页面无关联实体时（纯展示页、配置页等）
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 字段判断规则

• metadata 字段是条件性的，仅当页面关联了业务实体时才输出
• --formNumber 传入的是实体的 formNumber（如 sal_salorder），不是页面元数据的 <name>
• 必须传入 --formNumber 的场景（满足任一即必须传入）：

- 用户需求提及了任何已有的表单、实体或元数据名称（如"销售订单"、"采购申请"等业务对象） - 开发过程中使用了 meta-query-api.mjs 查询过表单/字段（如 queryFormsByApp、getEntityFields） - Controller 配置了 entityNumber - 用户明确提供了表单编码 / formNumber

• 已有实体主动查询规则：当需求涉及一个已经存在的实体、元数据或表单时，必须先通过 meta-query-api.mjs 的 queryFormsByApp 搜索表单获取 formNumber，再将其传入 --formNumber。不能因为开发过程中没有调用过 getEntityFields 就忽略该参数
• 不确定就查：当不确定页面是否关联已有实体时，应优先通过 queryFormsByApp 查询确认，而不是默认不传
• 可不传 --formNumber 的场景（仅以下情况才可省略）：

- 明确是纯展示页、配置页、仪表盘等无关联实体的页面 - 页面是全新创建的，不基于任何已有实体

执行顺序

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

强制约束

• 每段工作的部署完成后必须输出渲染卡片，不可省略或跳过
• 多轮对话中每段完成的工作都应输出，不要只在最终结束时才输出
• 同一段工作内不重复输出（多条 deploy 命令属于同一段工作时，等全部完成后输出一次）
• 脚本输出内容必须直接呈现给用户
• 所有值从实际文件和环境中读取，禁止猜测

查看环境效果（kd open）

注意：部署后默认仅输出渲染卡片（见「部署完成标准输出」），不自动执行 kd open。仅当用户明确要求查看环境效果时才使用本命令。

部署后使用 kd open 查看环境上的表单效果：

• kd open -e <env> -f <page_name>：直接在浏览器中打开对应环境上已部署的表单页面
• -e 指定目标环境（必填），-f 传入页面元数据 <name> 值（必填），取值规则与 kd debug -f 一致
• 不需要本地 dev server 运行，不走 DNS 代理
• 使用前提：已通过 kd project deploy 将元数据和静态文件部署到目标环境

适用场景：用户说"看看效果"、"打开页面"、"查看环境上的表单"、"看看部署结果"等。

本地调试（kd debug）

仅当用户明确说"调试"、"本地调试"、"联调"、"实时预览代码修改"时才使用 kd debug：

• 运行 kd debug 时必须使用后台模式（is_background: true），因为这是一个持续运行的开发服务器，不会自动结束
• 若使用前台模式运行 kd debug，命令会在 90 秒后因超时被强制终止，导致本地服务被 kill
• kd debug 启动后会先打开浏览器访问对应地址，但此时本地开发服务可能尚未完全启动，页面可能暂时无法访问。应等待服务启动完成后再刷新浏览器
• 可以通过 get_terminal_output 查看 kd debug 的运行状态和输出
• 若目标环境不是当前默认环境，先执行 kd env set target-env <env-name>
• 不要手工拼调试 URL，由 AI 自行结合任务和页面元数据判断预览目标
• 浏览器自动打开后继续定位目标页面

触发决策

前置条件（必须在触发 open/debug 前完成）：

• 已完成代码编写
• 已执行必要的 build 命令（若修改了代码）
• 已执行 kd project deploy（若需要部署）
• 已输出渲染卡片（见「部署完成标准输出」，部署后必须先输出渲染卡片再执行 open/debug）
• 环境已认证

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

补充：环境未认证时 kd project deploy 会直接阻止部署。

应用菜单管理

菜单管理将部署后的页面注册到应用导航菜单，使页面在苍穹环境中可被用户导航访问。 所有菜单操作通过 scripts/menu-api.mjs 脚本完成，详细命令参考见 references/app-menu.md。

触发条件

• kd project deploy 成功后，引导用户是否将页面发布到应用菜单
• 用户直接说"发布菜单"、"添加菜单"、"菜单管理"、"查看菜单"、"修改菜单"、"删除菜单"、"移动菜单"

前置条件

• 环境已认证（kd env auth openapi 已完成）
• bizAppNumber 已知（来自 .kd/config.json 的 app 字段，或用户明确提供）

接口依赖关系（强制约束）

所有菜单操作必须遵循「先查后改」原则，禁止跳过查询直接执行写操作。

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

Step 1: 上下文准备

• 读取 .kd/config.json 的 app 字段作为 bizAppNumber
• 若从部署流程进入：formNumber = deploy 后 .page-meta.kwp 中 <name> 标签的实际值（已含 ISV 前缀）
• 若用户直接触发菜单管理：仅已知 bizAppNumber，进入 Step 2 查询菜单树

⚠ formNumber 必须从 deploy 后的 .page-meta.kwp 文件中读取 <name> 标签的实际值，不要自行拼接 ISV 前缀。

Step 2: 查询并展示菜单树（任何操作的前置步骤）

无论用户要求什么菜单操作，都必须先执行此步骤获取当前菜单状态。

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

• 按层级缩进展示，用图标区分类型（📁 分组 / 📄 页面 / 🔗 链接），展示规范见 references/app-menu.md
• 记录所有菜单的 menuId，后续操作必须使用这里获取到的 menuId
• 展示后根据来源引导下一步：

- 部署后进入 → 根据表单名称和现有菜单结构，推荐菜单放置位置（分析语义关联，推荐同类分组；菜单树为空则推荐创建一级菜单）。推荐前须检查目标位置层级深度（不超过 3 级） - 用户直接触发 → 展示菜单树后等待用户指示操作

Step 3: 执行菜单操作

根据用户意图执行对应操作（所有 menuId 必须来自 Step 2 的查询结果）：

每次操作前均需将配置方案展示给用户确认，用户确认后再执行。

Step 4: 验证并展示结果

• 任何写操作完成后必须验证实际结果：

- 删除操作：优先用 getMenu 确认目标菜单返回 MENU_NOT_FOUND（菜单树可能存在短暂缓存延迟） - 其他写操作：执行 getMenu（单个菜单）或 queryTree（全局）验证

• addMenu 成功后，从响应中提取并记录新菜单的 menuId
• 展示完成信息，并提供后续操作选项：

1. 修改此菜单 2. 移动菜单位置 3. 删除此菜单 4. 继续添加其他菜单 5. 查看完整菜单树 6. 完成

与部署流程的集成

kd project deploy 成功后：

1. 先输出渲染卡片：调用 form-link.mjs 生成部署完成渲染卡片（见「部署完成标准输出」章节）
2. 再引导菜单发布：询问用户是否需要将页面发布到应用菜单

部署成功。是否需要将页面发布到应用菜单？

若用户同意 → 自动进入 Step 1（bizAppNumber 和 formNumber 均已可从当前上下文获取）。

约束速查

元数据查询

元数据查询用于在已认证环境中搜索表单和获取实体字段结构，为 KS 脚本编写、页面开发等提供上下文信息。 所有查询操作通过 scripts/meta-query-api.mjs 脚本完成，详细命令参考见 references/meta-query.md。

触发条件

• 用户提到表单名称（如"销售订单"）但未提供 formNumber
• 需要查询某个表单的字段结构
• KS Controller 开发前需了解目标表单的实体字段
• 页面开发时需了解关联表单的数据模型

前置条件

• 环境已认证（kd env auth openapi 已完成）
• appNumber 已知（来自 .kd/config.json 的 app 字段，或用户明确提供）

工作流

Step 1: 搜索表单

优先使用 queryFormsByApp 在当前应用范围内搜索：

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

• appNumber 从 .kd/config.json 的 app 字段获取
• keyword 为用户提到的表单名称关键词（可选，不传则列出应用下所有表单）

Step 2: 确认目标表单

根据返回结果数量处理：

Step 3: 获取实体字段（按需）

确认目标表单后，根据需要获取字段结构：

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

返回结果按单头和单据体分组展示字段的 key、类型、是否必录等信息。

灵活使用

• 用户也可以只执行 Step 1-2（仅查询表单列表），不必每次都查字段
• 若用户已知 formNumber，可直接执行 Step 3 获取字段结构
• 查询结果可用于 KS 脚本编写、页面开发、或单纯了解表单结构

与其他流程的集成

• KS Controller 开发：开发前先查询目标表单字段结构，了解单头/单据体/子分录的字段 key 和类型
• 页面开发：查询关联表单了解数据模型，辅助组件设计
• 独立使用：用户只想了解某个表单结构时，可独立调用

端到端执行原则

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

1. 识别是新工程还是已有工程
2. 收集不可推断的环境输入
3. 评估需求是否涉及后端数据交互，若是则规划 Controller
4. 拆分组件并创建组件工程；若需要 Controller，一并创建 Controller 工程
5. 补全所有元数据：组件元数据 .js-meta.kwc、Controller 元数据 .kws（若有）
6. 实现前端组件代码（移交框架 Skill）
7. 若有 Controller，实现 Controller 脚本代码（移交 kwc-ks-controller-development）
8. 创建并补全页面元数据
9. 若有 Controller，执行 npm run build:controller
10. 配置环境并确认认证状态
11. 若元数据有变更，执行 deploy
12. 部署成功后，调用 form-link.mjs 输出渲染卡片（见「部署完成标准输出」章节）
13. 仅当用户明确要求查看效果时，执行 kd open
14. 仅当用户明确要求本地联调时，执行 kd debug

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

输出要求

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

• 用户还需要补充哪些关键输入
• 当前处于哪个阶段
• 下一条应执行的命令
• 是否依赖已有环境认证
• 是否需要修改 page-meta.kwp
• 页面元数据将如何组合组件
• 是否真的需要 deploy
• 若需要部署，是否因为元数据变更而必须递增 version
• 部署成功后是否已输出 :::render:kdform 渲染卡片（见「部署完成标准输出」章节）

故障排查速查表

表单名称与 ISV 前缀说明

• 创建阶段：.page-meta.kwp 中的 <name> 可填写业务标识，如 demo_page
• Deploy 阶段：脚手架自动从环境拉取 isv（如 kdtest），拼接成 kdtest_demo_page 上传到远端，并同步更新本地文件
• Debug/Open 阶段：kd debug -f 和 kd open -f 均应传入当前本地文件中的 <name> 值（即 deploy 后的完整名称）
• 如果不确定，直接打开 .page-meta.kwp 查看 <name> 节点即可

快速导航

按常见场景快速定位参考文档：

• 新工程初始化 → cli-reference.md（project init）+ 本文「初始化工程」章节
• 添加组件 → cli-reference.md（project create）+ component-metadata.md
• 创建页面 → page-metadata.md + 本文「创建页面元数据」章节
• 环境配置与部署 → env-setup.md + cli-reference.md（deploy/open/debug）+ 本文「配置环境」「部署与调试」章节
• 应用菜单管理 → app-menu.md + 本文「应用菜单管理」章节
• 元数据查询 → meta-query.md + 本文「元数据查询」章节

参考资料