setup-datamodel

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果输出消息，请在继续之前向用户显示。

📋 共享说明：shared-instructions.md ——请先阅读。

设置数据模型 + 连接器

**入口路由：**在执行以下工作流之前，使用共享的 应用功能入口点 进行预检。

**调用范围：**在读取任何项目内容或执行以下工作流之前，遵循数据源调用范围。

此独立的数据专用工作流不需要完整的应用计划。 它仅提出并审批当前的架构／连接器变更；保留现有应用章节，不要调用完整应用规划或屏幕生成。 由负责人调用时，保留其明确的当前请求、绝对根目录、阶段和范围，并将提案或已验证结果返回给该负责人。

用于独立数据源规划的组合协调器。设计 Dataverse 架构、规划连接器、获取两者的审批，然后委派给 /add-dataverse 和 /add-connector 执行。

在以下情况下使用此技能	在以下情况下直接使用 /add-dataverse
独立的架构 + 连接器设计（已初始化应用；数据计划可选）	计划已存在，只需应用表并生成服务
需要导入现有 ER 图（图片／Mermaid／文本）	/create-mobile-app 正将此技能作为具有已审批范围上下文的子步骤调用
在项目中途重新规划架构或连接器	只需添加单个表或单个连接器

工作流

1. 解析项目根目录并验证身份验证 → 2. 设计数据模型 → 3. 规划连接器 → 4. 联合审批 → 5. 执行添加／刷新 → 6. 执行连接器 → 6.25 退役已批准的绑定 → 6.5 协调离线配置文件 → 7. 协调清单并总结

---

阶段 1 — 验证项目和身份验证

在读取项目文件或发现环境之前，先解析出一个绝对 working_dir：

• 对于嵌套调用，继承负责方的绝对 working_dir。如果同时提供了 --working-dir，两者必须解析到同一目录；若不匹配，必须在进行任何项目或云操作之前返回 NEEDS_CONTEXT。
• 对于直接调用，将显式的 --working-dir 相对于调用目录解析。只有在直接调用且未提供覆盖值时，才可将该调用目录用作项目根目录。
• 要求所选目录存在，将其规范化为一个绝对路径，并在本次调用期间保留该路径。缺少嵌套调用负责方指定的路径属于错误：绝不可回退到 shell 当前目录或搜索相邻应用。

以下所有相对应用路径，包括图表输入、native-app-plan.md、_dm_section.md、.datamodel-manifest.json、offline-profile.json 和 memory-bank.md，均相对于此解析后的根目录，而非之后某个工具的 cwd。使用文件工具时使用绝对路径。每次调用 shell 读取或写入应用本地文件时，都要以单引号括起的故障封闭式应用根目录保护命令开头；shell 状态不会在工具调用之间延续。

确认所选根目录是 Power Apps 移动应用：

对于 --plan-only 或规划阶段交接，以只读方式执行文件／环境检查，并遵循共享的仅提案环境上下文规则。 在常规调用中，审批前也使用同样的不持久化查询。 上下文不完整或相互冲突时，在只读恢复后返回 NEEDS_CONTEXT；绝不可在不带安全标志的情况下重试，也不可重定向到应用配置。

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
if [ ! -f power.config.json ] || [ ! -f app.config.js ]; then
  printf '%s\n' 'ERROR: selected working directory is not an initialized mobile app' >&2
  exit 1
fi
environment_id="$(node -p "require('./power.config.json').environmentId || ''")" || exit 1
if [ -z "$environment_id" ]; then
  printf '%s\n' 'ERROR: selected app has no environmentId' >&2
  exit 1
fi
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$environment_id" --no-cache --require-tenant

失败时停止；不要切换目录或重新搭建项目。记录此根目录对应的环境 URL、环境 ID 和租户 ID，以供阶段 5 使用。每次规划器／技能交接及重试时，都传递同一个绝对根目录。

Phase 2 — 设计数据模型

遥测检查点：design_dataverse_schema

先检查请求是否需要 Dataverse 架构；仅涉及连接器的请求走路径 C。否则，检查 $ARGUMENTS 中是否有图表提示（*.png、*.jpg、erDiagram、||--o{）。如果有，则走路径 A。如果已提供 Dataverse 需求，则走路径 B，提出只读方案。如果仍无法确定，则询问：

“你希望如何定义数据模型？”

选项	处理方式
上传现有 ER 图	提供 PNG/JPG 路径、Mermaid 代码块或文本描述
让 Data Model Architect 提出方案（默认）	启动 data-model-architect Agent，根据需求推断
跳过 — 不需要 Dataverse 表	跳到阶段 3

仅当需要 Dataverse 架构时，才建议选择“由架构师提出方案”。仅涉及连接器的需求走路径 C，不要凭空创建 Dataverse 表。空输入或取消不代表同意某个选项；请等待答复或停止。

对于路径 A 和 B，请阅读并执行 dataverse-change-planning.md。 前台负责范围限定的发现、精简证据验证和恢复；向架构师传递 Dataverse planning mode: required，绝不要走旧版实时发现路径。在每次交接时保留当前请求、绝对根目录和仅提案模式。路径 C、仅删除的工作以及仅刷新保留服务的工作，都跳过架构规划及其产物。

PDF 和签名的产物存储规则

当需求提到签名、签核、笔迹、绘图、生成的 PDF、导出的报告、证据包或保留的文档时，必须在审批前于 ## Data Model 中明确存储目标：

用户信号	Dataverse 模型影响
“采集签名”、“签核”、“审批签名”、“笔迹”	询问是否需要保留；仅在选择由 Dataverse 保留时，才复用或提出 Image/File 列，或子级 Evidence/Signature 表
“生成 PDF”、“导出报告”、“证据包”、“证书 PDF”	询问是否应保留生成的 PDF。若是，使用 Dataverse File 列，通常放在父记录上，或放在子级 Evidence/Attachment 表中。若否，记录仅在设备上/仅共享的行为，并且不添加列。
“上传 PDF”、“附加文件”、“导入文档”	使用 File 列，或使用带有指向父记录查找关系的子级 Attachment 表
“查看 PDF”	如果应用有持久来源，则存储或引用 HTTPS URL。原生 PDF 查看器 0.2.9+ 也支持本地 file:// URI；不支持 content://、blob: 和 http://。

绝不能将 PDF 内容建模为长文本/base64 文本。对于需要保留的 PDF，请使用 Dataverse File 列。如果生成的服务支持图像负载，签名 PNG 可以使用 Image 列；如果采集内容应作为附件处理，则使用 File 列或子级 Evidence 行。

路径 A — 解析用户提供的图表

接受 PNG/JPG（使用 Read 查看）、Mermaid 语法（粘贴到聊天中）或文本 描述。按用户要求，将表、列和关系解析为预期意图。 使用共享的精简证据工作流起草 _dm_section.md 和规范化的 .tmp/dataverse-schema-contract.json；图表名称本身不能证明现有架构。执行与路径 B 相同的决策验证，然后再进行阶段 4 的联合审批；此时不要更新实时计划。

路径 B — 启动 data-model-architect

Task: mobile-app:data-model-architect

Prompt:
  You are the data-model-architect agent for a Power Apps mobile app.
  Requirements: <$ARGUMENTS or ask the user what the app does>
  Working directory: <working_dir>
  Output proposal: <working_dir>/_dm_section.md
  Plugin root: ${PLUGIN_ROOT}
  Phase: planning
  Proposal only: <true for --plan-only or a planning-phase caller>
  Dataverse planning mode: required
  Normalized Dataverse foreground planning snapshot (validator input only): <SNAPSHOT_PATH>
  Compact Dataverse architect evidence: <ARCHITECT_EVIDENCE_PATH>
  Structured schema contract output: <working_dir>/.tmp/dataverse-schema-contract.json
  Scope: <current requested delta and necessary dependencies; unrelated rows are context only>
  Native capabilities and connector ownership: <retained approved constraints>

  Follow your snapshot-only path. Return a ## Data Model section with Mermaid ER diagram,
  reuse/extend/create table, and dependency-tier ordering. If requirements mention
  signatures, pen/ink, generated PDFs, report exports, evidence packets, or uploaded
  documents, include the artifact storage target: on-device/share-only, Dataverse
  Image column, Dataverse File column, or child Evidence/Attachment table. Retained
  PDF content must use a File column, not long text/base64.

对于结构化的 Dataverse 信号，先通过共享规划恢复流程处理，再遵循通用的 AGENTS.md 返回协议。必须同时提供章节和规范化合约，然后运行共享决策关卡，即使结果是 DONE/DONE_WITH_CONCERNS 也不例外。如果 Agent 不可用，则基于相同的精简证据内联起草这两项产物，并运行相同验证。将结果保留为阶段 4 的提案；遇到尚未解决的阻碍时停止，不要将提案视为已获批准。

Path C — 无 Dataverse

不提议任何 Dataverse 变更。保留任何现有的 Data Model 部分；只有当项目没有 Dataverse 模型时，才使用 “None — no Dataverse tables needed”。 继续进入 Phase 3，不要覆盖计划。

Phase 3 — 规划连接器

Telemetry checkpoint：plan_connector_integrations

遵循 shared/references/connector-planning.md：

1. 推断 — 如果 $ARGUMENTS 描述了应用的功能，扫描其中的连接器关键词。建立候选列表。
2. 确认 — 通过 AskUserQuestion 提交。让用户添加、移除或确认。
3. 记录 — 构建 ## Connectors 部分。

如果用户未提供需求上下文，请询问：

“您的应用需要连接到哪些服务？（例如 SharePoint、Teams、电子邮件、Excel、OneDrive、Azure DevOps，或没有）”

Phase 4 — 综合审批

Telemetry checkpoint：approve_data_model_and_connectors

对于现有的仅数据计划，在写入前比较当前绑定与提案。应用 data-source-removal.md 对移除项进行分类并明确审批。省略的表不会自动删除；保留现有使用方所需的一切。单独报告它们所需的变更；用户可以请求现有的 /edit-app 处理使用方工作，但此工作流不会自动调用它。

对于任何路径产生的 Dataverse 提案，在此关卡之前，必须确保当前规范化契约和快照通过 validate-dataverse-planning-decisions.js 验证，且退出码为 0。修订时重复验证，而不是进行广泛发现或再次执行审批流程。仅涉及连接器、退役或刷新的提案应使用各自的检查，不得复用过期的架构规划产物。

**仅提案退出：**如果存在 --plan-only，或调用方阶段为规划阶段，则展示提议的 Data Model、Connectors 以及退役/离线影响，然后返回调用方并在下方的执行审批之前停止。不要保存 native-app-plan.md、签发审批回执、更新物化清单，也不要调用 Phase 5–7。临时提案不是已应用的计划。对提案的审查批准不会覆盖 --plan-only；实施需要在不带该标志的情况下单独请求，并审批其确切变更范围。

在单个 EnterPlanMode 块中，一并展示此数据源变更的完整计划——数据模型 + 连接器。区分保留的上下文、添加项、刷新项和明确批准的退役项。当前实施阶段的负责人也可以直接提供确切的数据审批；此时应验证其与本提案一致，并在写入前将范围变更交还该负责人。仅有已保存的计划或 --skip-planning 不构成审批。

## Plan: Data Sources

### Data Model
[reuse/extend/create table]
[Mermaid ER diagram]
[creation order tiers]

### Connectors
[connector table or "None"]

Approve both to proceed with execution?

• 已批准 → 将两个已批准的部分保存到 native-app-plan.md，保留无关部分，然后进入 Phase 5。这适用于 Phase 2 的所有路径，包括架构师输出和仅连接器计划。
• 更改数据模型 → 仅返回 Phase 2 修改该部分，然后重新展示 Phase 4
• 更改连接器 → 返回 Phase 3，然后重新展示 Phase 4
• 取消 → 停止，不应用提议的计划或数据源变更。

将已接受的提案保存到 <working_dir>/native-app-plan.md；临时文件 _dm_section.md 不是第二个事实来源。不要重复使用绑定到先前计划的操作清单或审批回执。经验证的物化清单应在执行/验证后更新，而不是通过复制提议的行来更新。对于已批准的 Dataverse 实施，保留共享规划路径，并在 approved_scope 中固定已接受的 contract_sha256 和已保存的 plan_sha256。这不是创建流程回执，也不会授予与之无关的原生功能、连接器或屏幕审批。

第 5 阶段 — 执行数据模型

遥测检查点：apply_dataverse_schema

调用 /add-dataverse 并传入 --skip-planning，使其直接读取已批准的计划，而不重新询问：

此处仅应用新增或刷新操作。对于仅包含移除操作的差异，请跳过此阶段； 已批准的退役操作在第 6.25 阶段单独交接。

对于已注册表的纯服务刷新，请使用叶级流程的 --refresh --data-source-name "<registered-name>" 分支，并在 approved_scope 中传入其准确的已注册标识；不要对此行执行下方的架构新增交接。 对于架构变更，请保留常规交接流程。

Invoke skill: /add-dataverse

Context:
  MOBILE_APP_ORCHESTRATING=1
  orchestrator: setup-datamodel
  working_dir: <working_dir>
  phase: implementation
  offline_reconciliation_owner: setup-datamodel
  planning_snapshot: <SNAPSHOT_PATH>
  architect_evidence: <ARCHITECT_EVIDENCE_PATH>
  schema_contract: <working_dir>/.tmp/dataverse-schema-contract.json
  approved_scope: <approved Data Model delta and answers, contract_sha256, plan_sha256>

Arguments:
  --working-dir '<working_dir>'
  --plan-section '<working_dir>/native-app-plan.md#data-model'
  --skip-planning

/add-dataverse 会按层级顺序在此范围内创建表，仅添加已批准的缺失绑定或刷新已批准保留的服务，在需要时发布自定义项，写入 .datamodel-manifest.json，并进行类型检查。 它会验证范围限定的规划上下文并执行新一轮实时协调；不要传入不完整的仅创建快速通道标志。等待其返回后再进入第 6 阶段。

屏幕计划中的跨实体读取 — 已批准的 ### Cross-entity Reads 小节包含格式化查找、有界链式获取，或 external-projection-required 阻碍项。/add-dataverse 不会通过代码合成计算列或公式定义。用户提供的、由 maker 创建的计算列，会在协调期间作为现有依赖项进行验证，之后才能重复使用。

如果第 2 阶段选择了路径 C（不使用 Dataverse），则跳过。

第 6 阶段 — 执行连接器

遥测检查点：generate_connector_data_sources

读取 native-app-plan.md 中的 ## Connectors。对于每个已批准的新增或刷新连接器行（不包括保留或退役行），调用 /add-connector：

分派前应区分操作类型：新增行使用常规交接；刷新行则添加 --refresh --data-source-name "<registered-name>"，并在 approved_scope 中包含经过验证的 API／数据集／连接标识。 不要根据连接器显示标签推断已注册名称。刷新分支必须在不创建连接或执行 add-data-source 的情况下返回。

仅适用于新增源：

Invoke skill: /add-connector

Context:
  MOBILE_APP_ORCHESTRATING=1
  orchestrator: setup-datamodel
  working_dir: <working_dir>
  phase: implementation
  approved_scope: <approved connector row and answers>

Arguments:
  --working-dir '<working_dir>'
  --connector <api-name>

**仅适用于保留源的刷新：**使用此单独的交接流程，切勿使用新增代码块。

Invoke skill: /add-connector

Context:
  MOBILE_APP_ORCHESTRATING=1
  orchestrator: setup-datamodel
  working_dir: <working_dir>
  phase: implementation
  approved_scope: <refresh operation, exact registered name, verified API/dataset/resource and connection ID/reference>

Arguments:
  --working-dir '<working_dir>'
  --connector <verified-api-id>
  --refresh
  --data-source-name "<registered-name>"

按顺序运行。如果 ## Connectors 为“None”，则跳过。

第 6.25 阶段 — 退役未使用的应用绑定

对于每个明确批准的退役操作，调用匹配的叶级流程，并传入 --remove、MOBILE_APP_ORCHESTRATING=1、orchestrator: setup-datamodel、 phase: implementation、working_dir: <working_dir>、参数 --working-dir '<working_dir>' 以及其 approved_scope。 遵循 data-source-removal.md。 此独立的数据专用流程不会编辑使用方：如果仍有任何使用方，请停止操作，并向用户或当前负责人报告其集成工作，而不要破坏这些使用方。用户可以另行请求 /edit-app；切勿自动转到该流程。 在总结之前，验证 CLI 清理情况，并协调实际剩余的生成服务快照和应用清单。没有退役项时则跳过。 保留每个叶级流程根据共享移除约定产生的 offlineRetirement 结果，包括先前尝试记录在 memory-bank 中的未解决结果。 应用绑定清理与离线配置文件迁移的完成状态彼此独立。

Phase 6.5 — 离线配置文件协调

遥测检查点：reconcile_offline_profile

如果 Phase 5 创建或扩展了 Dataverse 表，现有的 Mobile Offline Profile 可能会缺少这些表或列。Phase 5 会传递完整的限定范围交接信息，其中包含 offline_reconciliation_owner: setup-datamodel；与 --skip-planning 配合使用时，由此协调器负责执行，而不是再次运行叶节点的 Step 8.5 检查。仅有该标志并不足够。如果 Phase 2 选择了 Path C（不使用 Dataverse），则跳过新增检查，但绝不可丢弃已记录的 offlineRetirement 结果。

运行本地、无网络的差异检查：

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/offline-profile-delta.js" --project-root '<working_dir>'

记录退出状态以及 stdout/stderr。在任何状态分支处理或 Phase 7 摘要之前，如果退出状态非零、status: error、JSON 缺失或格式错误，或状态未知，则按 offline-profile-reconciliation.md 中的失败路径处理：显示错误，在保留现有退役结果的同时记录 offline_reconciliation: failed，跳过变更辅助工具；对于已应用的数据变更，返回 DONE_WITH_CONCERNS（否则返回 BLOCKED）。 不得声称协调已完成，也不得继续输出正常成功摘要。

如果检查成功且结果有效，则根据 JSON 中的 status 分支处理：no-manifest / no-profile / in-sync 表示无需执行新增工作；保留现有 offlineRetirement 结果不变，继续进入 Phase 7（没有配置文件时，不要反复提醒）。对于 delta，先取得离线更新批准，然后使用参考文档的 Scoped helper handoffs，并提供 orchestrator: setup-datamodel、 working_dir: <working_dir>、 phase: implementation，以及确切获批的环境／配置文件／表／筛选器或列范围。对于 missingTables[]，向 add-table-to-offline-profile 传入 --working-dir '<working_dir>' --table <logicalName>；对于 tablesWithNewColumns[]，向 edit-offline-profile 传入相同参数，并附加 --columns "add:<newColumns>"。按照相同的失败路径重新检查，直至状态为 in-sync。 拒绝或未完成的新增工作仍应作为单独的问题处理。

这些离线辅助工具也必须使用相同的绝对路径 working_dir；协调过程中不得重新发现根目录。

Phase 7 — 摘要

在报告成功之前，逐一将受影响的计划部分与本项目已验证的输出进行核对，并刷新 Generated Services 快照。对于 Dataverse 变更，还需核对 .datamodel-manifest.json；移除最后一个 Dataverse 绑定后，也要保留有效的空清单。仅涉及 Connector 且不涉及 Dataverse 的工作不需要也不会创建 Dataverse 清单。在 memory-bank 中记录部分执行情况或尚未解决的移除问题，并返回非成功状态，而不是声称计划已全部应用。

根据已验证的结果生成摘要，不要照搬示例中可能出现的产物。对于没有 Dataverse 清单的纯 Connector 工作，将 Data Model 和 Manifest 标记为 not applicable；不要打印不存在的清单路径。如果已存在经过验证但未更改的清单，则标记为 unchanged。

在 memory-bank 和最终回复中包含每个受影响表的 offlineRetirement 状态。pending 应返回 DONE_WITH_CONCERNS，而不是正常的 DONE： “应用更改已完成。离线配置文件仍包含 Orders；是否保留或移除此覆盖范围尚待决定。” 使用实际表名和已验证的应用结果；如果应用清理失败，应报告失败，而不是声称已完成。retained 应报告获批的原因；只有经过验证的配置文件迁移才能标记为 reconciled，不能仅凭 in-sync 结果认定。

✅ Data sources set up
─────────────────────────────────────────────
Data model:
  Tables reused  : <list>
  Tables extended: <list>
  Tables created : <list>
  Manifest      : <verified manifest path and updated/unchanged status, or "not applicable">

Connectors:
  <list of added connectors, or "None">

Generated services:
  src/generated/services/ × <N>
  src/generated/models/   × <N>

Type-check: PASS

Next steps:
  /add-datasource   — add more data sources
  /add-native       — add device capabilities
  /edit-app         — separately request consumer/screen changes if needed
─────────────────────────────────────────────

参考资料

• shared/references/connector-planning.md — 连接器推断与确认逻辑
• shared/references/offline-profile-reconciliation.md — 第 6.5 阶段：离线差异检查与协调流程
• skills/add-dataverse/SKILL.md — 完整的数据模型执行工作流
• agents/data-model-architect.md — 只读架构师 Agent