# Kwc Project Scaffold

> 【KWC 工程唯一入口 Skill】负责 KWC 项目的脚手架初始化、组件/页面/Controller 元数据生成、环境配置与部署。当用户请求涉及 KWC 工程创建、kd CLI 使用、.page-meta.kwp / .js-meta.kwc / .kws 元数据文件、环境部署时，必须优先使用本 Skill。本 Skill 是 KWC 工作流的总入口，框架开发 Skill（react/vue/lwc-development）仅在脚手架初始化完成后、且明确需要编写组件实现代码时才被激活。禁止在元数据操作、工程初始化、部署阶段直接使用框架开发 Skill。

- Skill: `kingdee/kwc-project-scaffold` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add kingdee/kwc-project-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kingdee/kwc-project-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: kingdee (https://skillmd.com/u/kingdee)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kingdee/kwc-project-scaffold

---


# 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，必须停止并向用户确认，禁止猜测

### 协作边界表

| 任务阶段 | 负责 Skill | 产出物 |
|----------|------------|--------|
| 工程初始化 | scaffold | .kd/config.json |
| 创建组件目录 | scaffold | app/kwc/Component/ |
| **编写组件代码** | **react/vue/lwc-development** | ***.tsx / *.vue / *.js** |
| 补全组件元数据 | scaffold | *.js-meta.kwc |
| 创建页面元数据 | scaffold | *.page-meta.kwp |
| 环境配置与部署 | scaffold | 环境渲染结果 |
| 创建 Controller 目录 | scaffold | app/ks/controller/ControllerName/ |
| 补全 Controller 元数据 | scaffold | *.kws（URL、方法、权限配置） |
| 构建 Controller | scaffold | dist/controller/ |
| **编写 Controller 脚本代码** | **kwc-ks-controller-development** | **.ts 脚本（业务逻辑实现）** |

#### 切换时机

- 当任务仍处于需求拆分、脚手架命令、元数据、环境、`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` 搜索表单，从返回结果中确认真实编码
3. **向用户澄清实体**：若用户未提供表单编码，且实体名称可能存在歧义（如"库存"可能对应库存台账、库存余额、安全库存等不同表单），必须主动向用户确认：
   - "您提到的'库存'对应的是哪个业务表单？请提供表单编码或名称，以便查询准确的字段结构"
   - 若实体名称无歧义且用户也不确定编码，可先用 `queryFormsByApp` 按关键词搜索，将结果展示给用户选择
4. **确认后再查询字段**：只有在明确了表单编码后，才执行 `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 元数据和代码编写，**禁止猜测字段名**
4. 补全所有元数据（本 Skill 职责，元数据先行）：
   a. 补全组件元数据 `.js-meta.kwc`
   b. 补全 Controller 元数据 `.kws`（定义 URL、方法、权限配置）
5. **移交前端代码实现**：加载框架开发 Skill 编写组件代码（*.tsx / *.vue / *.js）
6. **移交后端代码实现**：加载 `kwc-ks-controller-development` 编写 Controller 脚本（*.ts）
7. 回到本 Skill：创建页面元数据并补全 `<controls>`
8. 构建前端：`npm run build:frontend`
9. 确认或创建目标环境，完成认证
10. 执行 `kd project deploy`
11. 部署成功后，调用 `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` 确认环境认证状态
3. 只有当环境不存在时，才进入完整的环境创建和认证流程

### 新建环境流程

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

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 这类自由文本仍应让用户手填

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

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

## 部署与调试

### 构建命令

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

| 场景 | 构建命令 | 说明 |
|------|---------|------|
| 改了前端代码（.tsx/.vue/.js） | `npm run build:frontend` | 构建前端静态资源，输出到 dist/kwc/ |
| 改了 Controller 代码（.ts）或 .kws | 不需要 build | 开发阶段 deploy 直接处理 Controller |
| 仅改元数据文件（.kwc/.kwp/.kws） | 不需要 build | 元数据由 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/...`）

### 调用命令

```bash
# 页面无关联实体时（纯展示页、配置页等）
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](references/app-menu.md)。

### 触发条件

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

### 前置条件

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

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

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

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

| 约束 | 说明 |
|------|------|
| **menuId 只能从接口获取** | `menuId` 只能来自 `queryTree` 返回的菜单树、`addMenu` 返回的新建菜单、或 `getMenu` 返回的详情。禁止凭记忆或猜测构造 menuId |
| **修改/删除/移动前必须先查询** | 执行 `updateMenu`、`deleteMenu`、`moveMenu` 前，必须先执行 `queryTree` 获取当前菜单树，从返回结果中确认目标 menuId 存在且状态正确 |
| **新增后必须捕获 menuId** | `addMenu` 成功后，必须从响应中提取新菜单的 `menuId` 并记录，供后续修改/移动使用 |
| **写操作后必须验证** | 任何写操作（add/update/delete/move）完成后，必须执行 `getMenu` 或 `queryTree` 验证实际状态，不能仅凭返回的 success 判断 |
| **parentMenuId 必须来自查询** | 新增子菜单时，`parentMenuId` 必须从 `queryTree` 的返回结果中获取已有菜单的 menuId，禁止猜测 |

### 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: 查询并展示菜单树（任何操作的前置步骤）

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

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

- 按层级缩进展示，用图标区分类型（📁 分组 / 📄 页面 / 🔗 链接），展示规范见 [references/app-menu.md](references/app-menu.md)
- **记录所有菜单的 menuId**，后续操作必须使用这里获取到的 menuId
- 展示后根据来源引导下一步：
  - **部署后进入** → 根据表单名称和现有菜单结构，推荐菜单放置位置（分析语义关联，推荐同类分组；菜单树为空则推荐创建一级菜单）。推荐前须检查目标位置层级深度（不超过 3 级）
  - **用户直接触发** → 展示菜单树后等待用户指示操作

### Step 3: 执行菜单操作

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

| 操作 | 命令 | 执行前检查 |
|------|------|------------|
| 新增 | `addMenu --bizAppNumber {app} --name {name} --formNumber {form} [--parentMenuId {pid}] [--seq {n}]` | 确认菜单名称和位置；检查层级不超 3 级；parentMenuId 必须来自 queryTree 结果；**批量新增同级菜单时必须传递从小开始的递增 --seq 值（如 1、2、3），禁止使用大数值，范围 1–32767** |
| 修改 | `updateMenu --bizAppNumber {app} --menuId {id} [--name ...] [--visible ...] [--seq {n}]` | menuId 必须来自 queryTree 结果；修改 visible 为 0 时警告级联隐藏；修改 parentMenuId 时检查循环引用和层级 |
| 删除 | `deleteMenu --bizAppNumber {app} --menuId {id}` | menuId 必须来自 queryTree 结果；检查 HPCE 保护；警告级联删除子菜单；需用户确认 |
| 移动 | `moveMenu --bizAppNumber {app} --menuId {id} --direction {up/down}` | menuId 必须来自 queryTree 结果；展示当前排序位置；若报错「序号一致」，先用 updateMenu --seq 修改相邻菜单序号再重试 |

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

### 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 均已可从当前上下文获取）。

### 约束速查

| 约束 | 何时提醒 |
|------|----------|
| 菜单最多 3 级 | 新增或移动菜单时检查 |
| HPCE 菜单不可删除 | 删除前检查 menuId 是否以 HPCE 结尾 |
| 级联隐藏 | 修改 visible 从 1→0 时警告 |
| 级联删除 | 删除有子菜单的菜单时警告 |
| formNumber 取实际值 | 新增页面菜单时 |

## 元数据查询

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

### 触发条件

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

### 前置条件

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

### 工作流

#### Step 1: 搜索表单

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

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

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

#### Step 2: 确认目标表单

根据返回结果数量处理：

| 场景 | 处理方式 |
|------|----------|
| 返回单条 | 直接确认为目标表单，提取 `formNumber` |
| 返回多条 | 列表展示让用户选择（序号 / 表单名称 / 表单编码 / 模型类型 / 所属应用） |
| 返回空 | 提示未找到，建议尝试换关键词重试 |

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

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

```bash
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` 渲染卡片（见「部署完成标准输出」章节）

## 故障排查速查表

| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| `kd project deploy` 提示未认证 | 环境未执行 auth | `kd env auth openapi` |
| 页面元数据上传失败 | version 未递增 | 递增 version 后重试 |
| 页面显示空白 | control.type 与组件 name 不匹配 | 检查大小写完全一致 |
| 组件属性不生效 | 属性未在 .js-meta.kwc 声明 | 添加 `<property>` 定义 |
| name 校验失败 | 格式不符 | 字母开头，仅小写+数字+下划线，≤30字符 |
| isv 不一致 | 页面与环境开发商不匹配 | deploy 会自动替换，无需手填 |
| 在非 KWC 工程目录执行命令 | 缺少 .kd 目录 | 先执行 `kd project init` |
| 创建了页面但组件不显示 | 未把组件写入 `<controls>` | 编辑 page-meta.kwp 添加 control |
| `kd debug` 提示端口占用 | 3333 端口被占用 | 关闭占用进程或重启终端 |
| `kd debug` 启动后无法找到目标表单 / 进入了错误的表单 | 未使用 `-f` 参数指定页面元数据 name，或传入了文件名而非元数据 name 值 | 使用 `kd debug -f <page_name>`，其中 `<page_name>` 为**当前本地 `.page-meta.kwp` 文件中 `<name>` 节点的实际值**。注意：deploy 后脚手架会自动更新本地文件中的 name（拼接 isv 前缀），因此应使用 deploy 后的完整名称，如 `kdtest_demo_page` |
| `kd open` 打开页面后显示空白 | 未部署或静态文件未上传 | 先执行 `kd project deploy` 确保元数据和静态文件已上传 |
| `kd open` 提示表单不存在 | `-f` 参数值不正确 | 传入页面元数据 `<name>` 节点的实际值（deploy 后的完整名称） |

### 表单名称与 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` + 本文「元数据查询」章节

## 参考资料

| 主题 | 参考文件 |
|------|----------|
| CLI 命令语法、参数、示例 | `references/cli-reference.md` |
| 组件元数据字段与属性类型 | `references/component-metadata.md` |
| 环境信息收集与认证流程 | `references/env-setup.md` |
| 页面元数据字段、controls 规则、命名规范 | `references/page-metadata.md` |
| 应用菜单管理命令与展示规范 | `references/app-menu.md` |
| 元数据查询命令与响应格式 | `references/meta-query.md` |