create-code-app

📋 共享说明：shared-instructions.md - 跨领域事项。

参考资料：

• prerequisites-reference.md - 前置条件和所需权限
• troubleshooting.md - 常见问题、npm 脚本、资源

创建 Power Apps Code App

工作流

1. 前置条件 → 2. 收集需求 → 3. 制定计划 → 4. 搭建骨架 → 5. 初始化 → 6. 构建和部署（基线） → 7. 添加数据源 → 8. 实现应用 → 9. 最终构建和部署 → 10. 总结

---

步骤 0：检查 Memory Bank

按照 shared-instructions.md 检查 memory-bank.md。跳过已完成的步骤。

步骤 1：验证前置条件

先运行前置条件检查——如果环境尚未就绪，收集需求就没有意义。详情请参阅 prerequisites-reference.md。

检查 Node.js 和 Git（在 bash 中原生运行）：

node --version   # Must be v22+
git --version    # Optional but recommended

• 缺少 Node.js：报告“请从 https://nodejs.org/ 安装 Node.js v22+”，然后停止。
• Node.js 版本低于 v22：报告“需要 Node.js 22+。请升级或使用 nvm use 22 切换版本。”，然后停止。
• 缺少 Git：报告“建议安装，但非必需。”获得批准后继续。
• 全部就绪：报告版本并继续。

步骤 2：收集需求

跳过用户已在初始指令中回答的问题。

如果用户尚未说明想要构建什么（例如，调用 /create-code-app 时没有参数，或只提供了含糊的提示词），先提出一个开放式问题，再询问其他内容：

“你想构建什么？请用自己的话描述——它的功能、使用者，以及它要解决的问题。”

等待用户回答。根据他们的回答来组织所有后续问题。在用户描述想法之前，不要列出应用类型供其选择。

收到用户的描述后：

1. 确认应用名称，并在需要时澄清用途
2. 询问数据相关需求——重点关注应用需要完成什么，而非特定技术：
   • “你的应用需要处理哪些数据？”（例如，公司电子邮件、项目任务、自定义业务记录）
   • “你的应用需要搜索现有信息、管理自己的数据，还是两者都需要？”
   • 根据用户的回答，推荐最佳方案：
     • 存储和管理自定义业务数据（表、表单、CRUD）→ Dataverse（/add-dataverse）
     • 与特定服务交互（发送电子邮件、发布消息、管理文件）→ 相应的连接器
     • 搜索 M365 数据或获取 AI 生成的答案（电子邮件、文件、人员、公司知识）→ Work IQ（/add-workiq）
   • 如果用户提到了现有的 Dataverse 表、SharePoint 列表或具体连接器名称，直接使用它们
3. 询问 UI 需求：关键屏幕、布局、交互方式、主题偏好
4. 此时提出任何澄清问题——进入计划模式前解决所有歧义

步骤 3：制定计划

1. 使用 EnterPlanMode 进入计划模式
2. 设计完整的实现方案：
   • 要运行哪些 /add-* 技能来添加数据源
   • 应用架构：组件、页面、状态管理
   • 按优先级排序的功能列表
3. 提交计划供用户批准，并包含 prerequisites-reference.md 中的 allowedPrompts
4. 获得批准后，使用 ExitPlanMode 退出计划模式

步骤 4：搭建项目骨架

询问用户文件夹名称。如果用户没有偏好，默认使用 powerapps-{app-name-slugified}-{timestamp}。

重要：使用 npx degit 下载模板。不要使用 git clone，不要手动创建文件，也不要从 GitHub UI 下载。degit 下载模板时不会包含 git 历史记录。

npx degit microsoft/PowerAppsCodeApps/templates/vite {folder} --force
cd {folder}
npm install

注意：

• 如果目录中已有文件（例如规划会话中创建的 .claude），请使用 --force 覆盖
• 如果目标是现有目录，请将文件夹名称设为 .：npx degit microsoft/PowerAppsCodeApps/templates/vite . --force
• 如果 npx degit 失败（网络问题、找不到 npm），重试一次，然后让用户手动运行

验证：package.json 存在，且已创建 node_modules/。

步骤 5：初始化

先解析 CLI（参见 cli-binary.md）：以 $PA app init …（npx --no-install pa …）的形式运行，绝不要直接运行 pa。对于仅使用 power-apps 的项目，改用 power-apps init …（两个二进制文件中的 init 动词及其 -n/-e 标志均保持不变）。

pa app init -n '{user-provided-app-name}' -e <environment-id>

**查找环境 ID：**它是 make.powerapps.com URL 中的 GUID：https://make.powerapps.com/environments/<env-id>/home。如果不传入 -e，CLI 会以交互方式提示输入。

**身份验证：**首次运行时，会打开浏览器窗口以登录 Microsoft。完成登录后，命令会继续执行。无需单独设置身份验证。

有关环境选择的详细信息，请参阅 preferred-environment.md。

pa app init 失败：

• 退出码非零：报告确切输出并停止。不要继续执行步骤 6。
• 出现“environmentId not found”或环境验证错误：确认环境 ID 正确，且用户在该环境中拥有 maker 权限，然后重试。
• 示例：“pa app init 命令失败：[error text]。请检查环境 ID 32a51012-... 是否正确，以及你是否拥有该环境中的 maker 权限。”

**关键：**初始化后读取 power.config.json，并确认 environmentId 设置正确。

步骤 6：生成并部署（基准版本）

已预先批准：此基准部署属于搭建项目骨架流程的一部分，无需单独请求确认。

在添加数据源之前，先构建并部署空白模板，以验证流水线正常运行。

npm run build

验证是否已创建 dist/ 文件夹，其中包含 index.html 和 assets/。

使用已解析的 CLI 进行部署：对于 pa，运行 $PA app push；对于仅使用 power-apps 的项目，运行 power-apps push（参见 cli-binary.md）。

pa app push

从输出中获取应用 URL：https://apps.powerapps.com/play/e/{env-id}/app/{app-id}

**常见部署错误：**参见 troubleshooting.md。

现在立即在项目根目录中创建或更新 memory-bank.md -- 不要等到最后。包含：

• 项目路径、应用名称、环境 ID、应用 URL
• 已完成的步骤：搭建项目骨架、初始化、基准部署
• 计划使用的数据源（来自步骤 2）

这样即使会话意外结束，也能保存进度。

步骤 7：添加数据源

调用计划中确定的 /add-* 技能（步骤 3）。依次运行每个技能。将上下文作为参数传入，以便子技能跳过重复提问（项目路径、连接器名称等）：

应用需要……	调用
存储／管理自定义业务数据	/add-dataverse
跟踪工作项、Bug、管道	/add-azuredevops
发送或读取 Teams 消息	/add-teams
读取／写入 Excel 电子表格数据	/add-excel
上传、下载或管理文件	/add-onedrive
使用 SharePoint 列表或文档	/add-sharepoint
发送电子邮件、读取收件箱、管理日历	/add-office365
调用 Copilot Studio Agent	/add-mcscopilot
搜索 M365 数据或获取 AI 赋能的答案	/add-workiq
连接到其他服务	/add-connector

每个 /add-* 技能都会运行 npm run build 来检查错误。现在不要部署。

**如果不需要数据源：**跳到步骤 8。

步骤 8：实现应用

**这是核心步骤。**根据步骤 3 的计划，构建实际的应用功能。

1. 检查生成的服务：使用 Grep 在生成的服务文件中查找方法（这些文件可能很大——请参阅 connector-reference.md）。不要读取整个生成文件。
2. 构建组件：为计划中的每个屏幕／功能创建 React 组件
3. 连接数据：将组件连接到生成的服务（使用 *Service.getAll()、*Service.create() 等）
4. 应用主题：使用用户偏好的主题（默认：按照开发标准使用深色主题）
5. 与用户迭代：展示进度、征求反馈，并根据需要调整

关键规则：

• 所有数据访问都使用生成的服务——绝不要直接使用 fetch/axios
• 如果使用 Dataverse，请阅读 dataverse-reference.md（选项集字段、虚拟字段、查找字段有需要特别注意的问题）
• 构建前删除未使用的导入（TS6133 严格模式）
• 除非要修复已知问题，否则不要编辑 src/generated/ 中的文件

步骤 9：最终构建与部署

npm run build

修复任何 TypeScript 错误。确认 dist/ 中包含更新后的应用。

询问用户："准备好部署到 [environment name] 了吗？这将更新线上应用。" 等待用户明确确认后再继续。

pa app push

步骤 10：总结

提供：

• 应用名称、环境、应用 URL、项目位置
• 构建内容：功能、数据源、组件
• 后续步骤：如何迭代（npm run build && pa app push）、如何添加更多数据源
• 建议应用还可以实现哪些功能：
  • /add-datasource —— 添加其他数据源（说明你的需求，插件会推荐最佳方案）
  • /add-dataverse —— 存储和管理自定义业务数据
  • /add-azuredevops —— 跟踪工作项、Bug 和管道
  • /add-teams —— 发送和读取 Teams 消息
  • /add-sharepoint —— 使用 SharePoint 列表或文档
  • /add-office365 —— 发送电子邮件、管理日历
  • /add-workiq —— 搜索 M365 数据，或获取有关公司信息的 AI 赋能答案
  • /add-connector —— 连接到任何其他服务
• 在 https://make.powerapps.com/environments//home 管理

更新记忆库

使用最终状态更新记忆库（在步骤 6 中创建）：

• 所有已完成的步骤（脚手架、数据源、实现、部署）
• 已实现的功能和已创建的组件
• 已连接的数据源
• 建议的后续步骤

---

示例演练

以下演练展示了从用户请求到最终输出的完整流程——运行的命令、修改的文件，以及助手应使用的逐字总结格式。

---

示例 1：使用 Dataverse 创建任务跟踪器应用

用户请求：

“帮我构建一个简单的任务跟踪器，将任务存储在 Dataverse 中。我想添加任务、标记任务为已完成，并查看任务列表。”

运行的命令（按顺序）：

# Step 1: Prerequisites
node --version   # → v22.4.0

# Step 4: Scaffold
npx degit microsoft/PowerAppsCodeApps/templates/vite powerapps-task-tracker-20260302 --force
cd powerapps-task-tracker-20260302
npm install

# Step 5: Initialize (browser login prompt on first run; CLI prompts for env ID if -e omitted)
pa app init -n 'Task Tracker' -e <environment-id>

# Step 6: Baseline deploy (pre-approved as part of scaffold flow)
npm run build
pa app push
# → App URL: https://apps.powerapps.com/play/e/32a51012-.../app/<app-id>

# Step 7: Add Dataverse (via /add-dataverse)
pa app add data-source --connector dataverse --table cr123_task
npm run build   # verify connector — no deploy yet

# Step 9: Final deploy (requires user confirmation)
npm run build
pa app push

更改的文件：

文件	更改
power.config.json	由 pa app init 创建 — 包含 environmentId
src/generated/models/Cr123_taskModel.ts	由 pa app add data-source 生成
src/generated/services/Cr123_taskService.ts	由 pa app add data-source 生成
src/components/TaskList.tsx	已创建 — 渲染带状态筛选器的任务列表
src/components/AddTaskForm.tsx	已创建 — 用于添加新任务的表单
src/App.tsx	已更新 — 将组件连接到 Cr123_taskService
memory-bank.md	在第 7 步创建，在第 11 步更新

助手最终摘要（原样格式）：

Task Tracker is live.

App: Task Tracker
Environment: <your-environment-name> (<environment-id>)
URL: https://apps.powerapps.com/play/e/<environment-id>/app/<app-id>
Project: ~/powerapps-task-tracker-20260302/

What was built:
- Task list view with Active / Completed filter
- Add task form (title, description, due date)
- Mark complete / delete actions
- Dataverse table `cr123_task` (Title, Description, DueDate, IsComplete)

To redeploy: npm run build && pa app push (from the project folder)

What you can add next:
- /add-teams — post task updates to a Teams channel
- /add-office365 — send email notifications on completion

memory-bank.md 中应记录的内容：

# Task Tracker — Memory Bank

## Project

- Path: ~/powerapps-task-tracker-20260302/
- App name: Task Tracker
- Environment: <your-environment-name> (<environment-id>)
- App URL: https://apps.powerapps.com/play/e/<environment-id>/app/<app-id>

## Completed Steps

- [x] Step 1: Prerequisites validated
- [x] Step 4: Scaffold (npx degit)
- [x] Step 5: Initialize (pa app init)
- [x] Step 6: Baseline deploy
- [x] Step 7: Add Dataverse (cr123_task)
- [x] Step 8: Implement app (TaskList, AddTaskForm)
- [x] Step 9: Final deploy

## Data Sources

- Dataverse: cr123_task (Title, Description, DueDate, IsComplete)

## Components

- TaskList.tsx — filtered list, mark complete, delete
- AddTaskForm.tsx — create new tasks

## Next Steps

- Consider /add-teams for task assignment notifications

---

示例 2：向现有应用添加 SharePoint 连接器

用户请求：

“我的应用已经存在。添加 SharePoint，这样我就可以读取名为 ‘Project Milestones’ 的列表中的项目。”

运行的命令（按顺序）：

# Step 6: Get connection ID (via /list-connections)
pa connection list
# → ConnectionId: conn-sp-xyz789  (SharePoint Online)

# Step 7: Discover sites
pa connector list-datasets --connector sharepointonline -c conn-sp-xyz789
# → https://contoso.sharepoint.com/sites/Projects

# Step 8: Discover tables
pa connector list-tables --connector sharepointonline -c conn-sp-xyz789 -d 'https://contoso.sharepoint.com/sites/Projects'
# → Project Milestones, Documents, Team Wiki

# Step 9: Add connector
pa app add data-source --connector sharepointonline -c conn-sp-xyz789 -d 'https://contoso.sharepoint.com/sites/Projects' --table 'Project Milestones'

# Step 11: Build to verify
npm run build   # → success

更改的文件：

文件	更改
src/generated/services/SharePointOnlineService.ts	已生成 — 包含 GetItems、PostItem 等。
src/generated/models/SharePointOnlineModel.ts	已生成 — TypeScript 接口
.power/schemas/sharepointonline/	已生成架构文件
memory-bank.md	已更新 — 已记录连接器

助手最终摘要（原样格式）：

SharePoint Online connector added.

Connector: SharePoint Online
Site: https://contoso.sharepoint.com/sites/Projects
List: Project Milestones
Build: Passed ✓

Usage:
  const result = await SharePointOnlineService.GetItems({
    dataset: "https://contoso.sharepoint.com/sites/Projects",
    table: "Project Milestones"
  });
  const milestones = result.data?.value || [];

Next: Implement your UI components using the generated service, then run /deploy when ready.