kwc-project-scaffold

KWC プロジェクトのスキャフォールド

この 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（データ取得と業務ロジック）の 2 つの部分で構成されます。

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

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

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

调用命令

# 页面无关联实体时（纯展示页、配置页等）
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 验证结果

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

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

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

• 按层级缩进展示，用图标区分类型（📁 分组 / 📄 页面 / 🔗 链接），展示规范见 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。

触发条件

• 用户提到表单名称（如"销售订单"）但未提供 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: 确认目标表单

根据返回结果数量处理：

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

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

故障排查速查表

症状	可能原因	解决方案
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