openyida 2026.9.21 → 2026.9.22-beta.1

package/yida-skills/skills/yida-app/workflow/step-9-output-finish.md

@@ -14,27 +14,21 @@
 - 页面/资源数量完整性风险检查结果。
 - `requirement-brief.json.constraints.prohibitedActions` 与对应跳过证据。
 
-主入口与页面入口必须取自本轮 CLI 成功结果返回的 `appUrl`、`workbenchUrl`、`adminUrl` 或 `url`，并在后续只读回查中保持一致。不得由模型根据 `appType` 自行拼接或猜测链接；下文 URL 规则仅用于校验服务端/CLI 返回值，不是缺失链接时的生成规则。若成功结果没有权威 URL，必须明确交付失败并执行只读回查，不能交付空卡片或用模板补齐。
-
-入口层级由用户的交付目标决定：应用访问、应用入口或应用工作台使用成功结果的 `appUrl`；具体表单、流程、报表或页面入口使用对应资源结果的 `url` / `workbenchUrl`。同一结果同时提供两种入口时，优先满足用户明确点名的层级。
+主入口与页面入口必须取自本轮 CLI 成功结果返回的 `appUrl`、`workbenchUrl` 或 `url`，并在后续只读回查中保持一致。不得由模型根据 `appType` 自行拼接或猜测链接；下文 URL 规则仅用于校验服务端/CLI 返回值，不是缺失链接时的生成规则。若成功结果没有权威 URL，必须明确交付失败并执行只读回查，不能交付空卡片或用模板补齐。
 
 ## 完成条件核对
 
-`execution.explicitScope.allowInferredResources=false` 时，逐项核对范围内资源的成功结果、必要回读和真实链接，完成后交付。下面的完整应用检查表适用于 `allowInferredResources=true`。
-
-按 PRD 的有效交付范围核对：第 1–2 条仅适用于本轮有自定义页面发布任务的应用；仅原生管理视图时记录不适用，并验证真实管理列表。frontend-only 不执行平台排序，不能为满足默认条件追加首页。其余条件按实际资源核验：
+完整应用默认完成需要同时满足：
 
 1. 主页面发布成功；
 2. Canvas 主页面发布结果为 `publishMode=canvas`，读回 `hasYidaCodeCanvas=true` 且 `runtimeCodeBytes>0`；
 3. 真实数据页面在已登录浏览器中退出 loading、无业务错误，并显示至少一条已 query 确认的记录；看板还必须有至少一个 KPI 数量或列表记录与只读 query 结果一致。已知记录数大于 0 但页面 KPI 全 0、列表为空或显示“暂无数据”时必须失败或标记 `needs_review`；
 4. 获得可访问 URL；
-5. 各入口的菜单顺序、默认页面和首屏任务已按规划落实；平台导航有排序回读，自定义导航有页面验证。未完成项按入口明确列出，不能仅因平台命令不适用就将排序记为完成；
+5. 轻量导航排序已执行，或给出明确 warning；
 6. 新建或作为页面数据源的核心普通表单已写入 1-3 条真实示例记录并 query 抽查，或明确说明跳过原因；
 7. 汇合此前并行执行的主题任务，确认 `themeVerification.verified=true`、`colour=custom`、`themeColor`、`navTheme`、`layoutDirection` 与已确认设置一致，`customThemeStyle.cssUrl` 非空；这里是完成检查，不是首次更新主题的时机。应用主题文件已在应用级统一配置，自定义页面只在 `YidaComp` 内消费对应 token，未向上层注入或同步主题样式。
-8. final 前先写入轻量 `prd/<项目名>/build-manifest.json`，再运行 `openyida check-prd-completeness prd/<项目名>/prd.md --app-type <appType> --build-manifest prd/<项目名>/build-manifest.json --json`；该命令检查页面/资源数量及已提供的素材执行记录一致性，不能替代第 3 条运行态数据验收。只有 `verdict=pass` 且运行态数据证据通过时才说“已按 PRD 完成搭建”；`verdict=needs_review` 时可以交付但必须列出 `items` 中 `status=needs_review/not_checked` 的复核项，`verdict=fail` 时列出 `hardFailures` 并说明未完成；
-9. 未继续执行用户未要求的公开访问、额外截图报告、报表、大屏、数据源深接或精细导航分组。
-
-第 7 条的设置回读不代表视觉通过。按 [跨页面主题验收](../../yida-design/references/application-theme-consistency.md#验证主题是否真正一致) 检查实际存在的原生页、自定义页与抽屉/详情；没有浏览器证据时标记跨页面视觉待验证。不能以 `iframePropagation=false` 推断主题未加载，也不能以页面 fallback 正常或资源检查通过宣称全应用风格一致。
+8. final 前先写入轻量 `prd/<项目名>/build-manifest.json`，再运行 `openyida check-prd-completeness prd/<项目名>/prd.md --app-type <appType> --build-manifest prd/<项目名>/build-manifest.json --json`；该命令只证明页面/资源数量完整性，不能替代第 3 条运行态数据验收。只有 `verdict=pass` 且运行态数据证据通过时才说“已按 PRD 完成搭建”；`verdict=needs_review` 时可以交付但必须列出 `items` 中 `status=needs_review/not_checked` 的复核项，`verdict=fail` 时列出 `hardFailures` 并说明未完成；
+9. 未继续执行用户未要求的公开访问、截图验收、报表、大屏、数据源深接或精细导航分组。
 
 用户明确禁止的动作优先于上述默认条件：禁止 `theme-file` 时，第 7 条改为核验本轮没有生成、复制、修改或上传主题文件，并如实说明沿用现有/平台默认主题，不把它判为主题任务失败；禁止 `publish` 时不得宣称完整应用已发布或把历史 URL 当成本轮发布产物，只交付已完成的未发布范围和后续发布条件；禁止 `page-source` 时不得宣称本轮修改了页面源码，也不得用编译或现有页面状态替代源码变更证据。跳过项必须来自用户明确约束，不能由模型自行缩减范围。
 
@@ -42,17 +36,13 @@
 
 若本轮修改过页面源码但没有成功执行 `openyida publish <source> <appType> <displayPageFormUuid>`，只能交付“源码已修改，尚未发布”的说明。
 
-需求含 `userTasks` 和 `entryRecommendation` 时，按最终 PRD 核对服务与管理任务的实际访问路径，沿用用户已确认的调整；入口建议不作为完成证据。只有相关页面及访问配置回读通过后才交付对应入口，不为双入口补造后台功能，不用 `/admin` 开发后台代替业务管理工作区。
-
 ## build-manifest 约定
 
 完整搭建收尾前，从本轮真实创建、复用和发布结果写入 `prd/<项目名>/build-manifest.json`。它只是轻量事实源，不是严格 schema；只记录已经拿到的真实资源名、类型和 ID，用于让 `check-prd-completeness` 做一次 app 资源列表 readback 后判断页面/资源数量是否完整。
 
 `build-manifest.json` 与 Step 2 的 `requirement-brief.json`、`prd.md`、`design.md` 一样只供内部编排和验收使用。不得把它们登记为用户可见附件或下载卡片。若 final 将概述 seed records，manifest 中为每个资源分别记录实际写入数、query 抽查数和核验状态；未知值保持未知，不得从其他资源推导。
 
-平台导航管理页需另外从实际 workbench 入口核对没有重复跨模块菜单；将页面配置回读与视觉检查分开记录，未打开页面时标记视觉待验证，不把 build-manifest 资源齐全或编译成功当作导航验收。
-
-资源检查只消费 `display-page`、`normal-form`、`process-form` 资源项；不检查字段、必填、选项、seed records、导航顺序、表单 Schema、页面发布内容、截图或视觉体验。
+一期检查只消费 `display-page`、`normal-form`、`process-form` 资源项；不检查字段、必填、选项、seed records、导航顺序、表单 Schema、页面发布内容、截图或视觉体验。
 
 最小示例：
 
@@ -75,79 +65,49 @@
 }
 ```
 
-## 素材调度记录
-
-有素材任务时，build-manifest 另保留物化输出 `assetTasks`（Fast 使用同契约），并汇总每页真实 taskState 到 `assetExecution.tasks`；业务任务起止时间记录在 `assetExecution.businessWork`。所有时间使用带时区的 ISO 格式，不能用当前时间补造历史。示例只说明字段，值必须换成真实执行回执：
-
-```json
-{
-  "assetExecution": {
-    "tasks": [{
-      "taskKey": "/actual/project/asset-manifests/home.json", "pageId": "home",
-      "executionMode": "background_shell", "toolName": "Bash", "backgroundOption": "run_in_background=true",
-      "hostTaskId": "actual-host-job-id", "status": "completed",
-      "startedAt": "2026-09-16T07:00:00Z", "dispatchReturnedAt": "2026-09-16T07:00:01Z", "endedAt": "2026-09-16T07:00:30Z"
-    }],
-    "businessWork": [{ "taskKey": "create-app", "startedAt": "2026-09-16T07:00:02Z", "endedAt": "2026-09-16T07:00:20Z" }]
-  }
-}
-```
-
-`executionMode=synchronous` 必须记录 fallbackReason，并先推进独立业务；不伪造 hostTaskId。复用已验证 final 素材用 reused/completed 和 reuseEvidence。纯素材修补确无独立业务时，记录 independentWork=none、noIndependentWorkReason，businessWork 为空；仍不能声称业务并行。
-
-`check-prd-completeness` 返回 assetExecution 审计状态。后台调用完成后才返回、业务与素材没有实际时间重叠、同步路径素材前置、缺少时间或预期任务记录，都会产生 needs_review 项；正确的同步退化可通过记录检查，不被说成异步。旧 manifest 没有这类记录时为 not_checked，不能认定已经并行；有 assetTasks 却缺记录则需复核。本检查只验证记录一致性，不独立证明宿主确实执行，更不替代图片内容验收。
-
-## 访问态入口验收
-
-按 [访问态入口契约](../references/entry-navigation.md) 分别验收访客与业务管理者。管理端可以直接交付已验证的 `/workbench/{formUuid}?viewUuid=...` 作为本入口的唯一默认任务链接，不展开全部表单地址；根 `/workbench` 只有默认落点符合任务时才使用。管理端没有自定义首页时以原生管理视图和权限验证为准，不要求主页面 KPI。前台必须使用已回读的独立 custom 链接；菜单隐藏不授予权限，未取得真实角色证据时明确标记多身份在线验收未完成。开发后台不属于前后台业务切换。
-
 ## 结果输出格式
 
-- 准备 2-3 句业务交付总结，并给一个名为“应用访问入口”的入口组。
-- `notify_human` 是终态交付动作，其终态 artifact 的可见 `description` 是本轮业务总结、readback 事实和必要上下文的统一载体；用户要求的记录数、资源 ID、发布状态或核验结果也写入这里。调用成功即完成本轮交付。宿主没有交付工具时，在最终回复中给出相同的总结、核验结果与入口。
-- 一次完整应用 run 交付一组用户可见的“应用访问入口”。同一应用的后续交付从已有资源和已验证 URL 生成当前 run 的入口组；资源变更由用户本轮明确要求的变更范围驱动。
-- 业务资源在总结中按能力或数量概述，例如“已完成 4 张业务表单、1 条审批流程和 1 个经营看板”。
-- 用户或调用方明确要求资源清单、资源 UUID/ID、发布状态或测试数据摘要时，终态 artifact 的 `description` 包含简洁的“交付清单”。清单是本轮真实返回值和只读 readback 的投影，覆盖已创建或发布资源的名称、类型、ID、主页面发布状态及 seed records 写入/抽查摘要；未知信息标记为未核验。
-- 业务总结中的资源数量、seed records 数量和完成状态与逐资源真实返回值/readback 一一对应；证据不完整的资源标记为未核验。
-- 新增、修改或发布单个具体页面时，交付当前页面并保持单页范围。
-- 完整应用的入口组按有效范围交付：不分前后台时提供经验证的“系统入口”，分前后台或只有访问后台时提供经验证的“业务后台入口”：根 `{base_url}/{appType}/workbench` 或上述指定任务/视图链接；明确仅前台时不追加业务后台，但仍提供开发者管理后台。
-- 只有访问后台时核验业务处理人员的入口、数据范围和操作，不追加前台；只有访问前台且提交后需要处理时，核验已有系统、人员入口或自动流程如何承接，未核验的部分明确说明。
-- 前台页面在 PRD 中为 `entryMode=standalone`，且 Step 8 回读确认 `renderNav=false` 时，入口组包含“前台” `{base_url}/{appType}/custom/{formUuid}`；否则不得输出。
-- 完整应用默认交付“开发者管理后台” `{base_url}/{appType}/admin`，使用 `create-app` 或 `app-list` 成功结果中的 `adminUrl`。`application_entry_policy.entries.admin=include` 不受云端/本地宿主或登录态注入方式影响；不要沿用旧版本云端省略 admin 的规则。地址生成不代表已验证收件人的管理权限，实际访问仍由平台鉴权。
-- 完整应用一般为 2–3 个地址：有前后台时为“前台、业务后台、开发者管理后台”；仅前台时为“前台、开发者管理后台”；仅业务后台时为“业务后台、开发者管理后台”；不分前后台时为“系统入口、开发者管理后台”。同一业务入口不重复凑数，不为补链接创建额外业务后台。用户明确排除开发者入口时遵从；单页任务保持单页交付范围。
-- 若历史创建结果缺少 `adminUrl`，分页查询 `app-list` 并匹配真实 `appType`（名称仅辅助识别），保留其 `adminUrl`；不要自行猜租户域名或资源 ID。无法取得时明确标记开发者入口待补齐，不得静默省略或声明交付完成。
+- 先写 2-3 句业务交付总结，再给一个名为“应用访问入口”的入口组。
+- 调用 `notify_human` 前必须先输出上述正文总结；用户明确要求记录数、资源 ID、发布状态或核验结果时，先在正文写完经 readback 支撑的简洁清单，再调用交付工具。链接卡或平台产物卡不能替代正文总结与显式要求的清单。
+- 一次完整应用搭建只产生这一组用户可见交付，不把表单、流程、报表、页面、资源清单或内部文件分别登记为附件、链接卡或下载卡。
+- 业务资源只在总结中按能力或数量概述是默认规则，例如“已完成 4 张业务表单、1 条审批流程和 1 个经营看板”；不默认输出资源 ID 表格、资源清单、长列表、appType、formUuid、pageId、reportId。
+- 用户或调用方明确要求资源清单、资源 UUID/ID、发布状态或测试数据摘要时，final 必须在业务总结与唯一入口组之间补充一个简洁的“交付清单”。清单只列本轮已通过真实返回值或只读 readback 核验的资源名称、类型和 ID，并同时写明主页面发布状态及 seed records 写入/抽查摘要；不得遗漏已创建或发布的资源，不得用链接卡代替正文清单，也不得编造未知 ID。
+- 即使用户没有要求技术清单，业务总结中的资源数量、seed records 数量以及“已写入/已验证/已就绪”等完成状态也必须逐资源来自真实返回值或只读 readback。证据不完整时缩小表述范围并明确未核验项，禁止为了让总结完整而补齐推测数字。
+- 新增、修改或发布单个具体页面时，仍只交付当前页面，不扩展成完整应用入口组。
+- 完整应用的入口组始终包含“应用工作台” `{base_url}/{appType}/workbench`。
+- 主页面在 PRD 中为 `entryMode=standalone`，且 Step 8 回读确认 `isRenderNav=false` 时，入口组额外包含“独立业务入口” `{base_url}/{appType}/custom/{formUuid}`；否则不得输出。
+- 先读取 `openyida agent-capabilities --summary-json` 的 `application_entry_policy.entries.admin`：值为 `include` 时，入口组额外包含“应用开发后台” `{base_url}/{appType}/admin`；值为 `omit` 时不得输出。不要根据 Agent 名称或自然语言猜测云端/非云端。
 - 三个入口属于同一个应用入口组，不得各自连同业务资源再生成多组交付。
 - 不把 `g.alicdn.com` 的 `index.css`、`index.js`、`index.html`、`locales/*.json`、构建产物 URL、CDN 资源 URL 或中间文件链接当成最终结果展示。
 - 调用方或评测要求结构化结果时，额外输出顶层 `skillsUsed`，只填写本轮实际读取并使用的 `yida-*` 子技能名；不得把计划使用或未加载的技能写入。
 
-交付卡片描述与入口示例（根据本轮实际完成内容填写）：
+推荐口径：
 
 ```markdown
 已完成订单、客户和商品等核心业务表单，并发布首页、订单管理和库存看板等入口页面。当前应用已支持订单录入、库存预警、销售统计、表单提交入口和详情查看，示例记录、轻量导航排序与统一应用主题也已就绪。
 
 应用访问入口：
 
-- 前台：`{base_url}/{appType}/custom/{formUuid}`（仅 `standalone` 且回读通过）
-- 业务后台：`{base_url}/{appType}/workbench`（有独立业务后台时，按已验证的默认任务选择入口）
-- 开发者管理后台：`{base_url}/{appType}/admin`（完整应用默认提供）
+- 应用工作台：`{base_url}/{appType}/workbench`
+- 独立业务入口：`{base_url}/{appType}/custom/{formUuid}`（仅 `standalone` 且回读通过）
+- 应用开发后台：`{base_url}/{appType}/admin`（仅 capability 明确为 `include`）
 ```
 
-只有用户或调用方明确要求资源清单、资源 UUID/ID、发布状态、测试数据摘要、排障、复盘、迁移或复制配置时，才补充技术 ID。显式要求一旦命中，这些信息写入交付卡片描述，属于本轮验收结果，不能被“默认隐藏技术 ID”规则覆盖。
+只有用户或调用方明确要求资源清单、资源 UUID/ID、发布状态、测试数据摘要、排障、复盘、迁移或复制配置时，才补充技术 ID。显式要求一旦命中，这些正文信息属于本轮验收结果，不能被“默认隐藏技术 ID”规则覆盖。
 
 ## URL 规则
 
 | 页面类型 | URL 格式 |
 | --- | --- |
-| 开发者管理后台 | `{base_url}/{appType}/admin`（取 CLI `adminUrl`） |
 | 应用首页 | `{base_url}/{appType}/workbench` |
 | 表单提交页（默认隐藏导航） | `{base_url}/{appType}/submission/{formUuid}?isRenderNav=false` |
 | 自定义页面 | `{base_url}/{appType}/custom/{formUuid}` |
-| 独立自定义页面 | `{base_url}/{appType}/custom/{formUuid}`；页面 `renderNav=false` 回读通过，混合前后台应用保留 `hideAppNav=n` |
+| 自定义页面（应用导航隐藏） | `{base_url}/{appType}/custom/{formUuid}`；由应用基础设置 `hideAppNav='y'` 控制 |
 | 原生报表（仅单独交付该报表时） | 使用 CLI 返回的 `{base_url}/{appType}/workbench/{reportId}`；禁止拼接 `/{appType}/report/{reportId}` |
 | 表单详情页（抽屉/隐藏导航） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&navConfig.layout=1180&isRenderNav=false` |
 | 表单详情页（编辑模式） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&mode=edit&navConfig.layout=1180&isRenderNav=false` |
 
-完整应用即使包含原生报表，也不得把模型猜测的报表路由或每张表单的管理地址作为应用交付入口。入口组包含范围内的工作台、经回读确认的前台，以及完整应用默认提供的开发者管理后台。
+完整应用即使包含原生报表，也不得把模型猜测的报表路由或每张表单的管理地址作为应用交付入口。入口组只允许工作台、经回读确认的独立业务入口，以及 capability 允许的开发后台。
 
 ## 可选后置
 
@@ -172,17 +132,17 @@
 
 ## Checklist
 
-- [ ] 唯一一组“应用访问入口”的终态 artifact `description` 已包含业务总结；
-- [ ] `notify_human` 作为最后一个动作调用，用户显式要求的事实清单和资源 ID 已进入可见 `description`；
+- [ ] final 先写业务总结，再给唯一一组“应用访问入口”；
+- [ ] `notify_human` 在正文总结与用户显式要求的事实清单之后调用，未把链接卡当成正文替代品；
 - [ ] final 中每个资源数量和数据完成声明都有对应资源自己的成功返回值/readback；未把一张表单的记录数套用到其他表单；
-- [ ] 用户或调用方显式要求资源清单/UUID/发布状态/测试数据摘要时，终态 artifact `description` 已完整列出经核验的交付清单；
+- [ ] 用户或调用方显式要求资源清单/UUID/发布状态/测试数据摘要时，正文已完整列出经核验的交付清单，未只返回链接卡；
 - [ ] 已写入轻量 build-manifest 并运行页面/资源数量完整性风险检查；未通过时没有声称“已按 PRD 完成搭建”；
 - [ ] 已按 `constraints.prohibitedActions` 调整完成条件；跳过写操作时没有伪造已换肤、已修改源码或已发布；
 - [ ] 未把内部文件或每个业务资源分别交付；
-- [ ] 按有效范围交付管理入口，frontend-only 不追加工作台；custom 只在 `standalone` 写后回读通过时存在，完整应用默认包含开发者管理后台，登录方式不作为省略依据；
+- [ ] 工作台始终存在，custom 只在 `standalone` 写后回读通过时存在，admin 严格跟随 capability；
 - [ ] 未默认暴露资源 ID 或其他管理态链接；
 - [ ] 结构化结果中的 `skillsUsed` 只包含实际读取并使用的技能；
 - [ ] 未把 CDN 构建产物当作交付链接；
 - [ ] 未执行用户未要求的可选后置动作。
 
-整个应用采用自定义导航时，交付前核对应用导航已隐藏，且 PRD 清单中每个表单、流程表单和自定义页面均有 `get-form-config` 返回 `isRenderNav=false` 的记录。任一页面配置失败时，该导航方案尚未完成。
+自定义导航应用交付前，核对应用导航已隐藏，且 PRD 清单中每个表单、流程表单和自定义页面均有 `get-form-config` 返回 `isRenderNav=false` 的记录。任一页面配置失败时，该导航方案尚未完成。

package/yida-skills/skills/yida-canvas-custom-page/SKILL.md

@@ -7,35 +7,38 @@ description: 宜搭自定义页面开发规范，使用 `YidaCodeCanvas` 组件
 
 ## 编码前必读（MUST）
 
-先确认导航归属：使用平台导航的管理端自定义页面默认只实现业务内容，同任务可用页内 Tab，跨模块由平台菜单切换。编码前按[管理页面边界](references/navigation-and-entry-guide.md#平台导航下的管理页面)核对，不把后台任务清单或前台菜单复制为第二套导航。
+新建自定义页面，或修改页面布局、卡片、背景、主题与控件样式时，**第一次写入页面源码前**必须通过文件读取工具完整读取 [canvas-style-implementation-guide.md](references/canvas-style-implementation-guide.md)，再结合当前 PRD 和 `design.md` 实现。它是实现规范，不是可选示例；不能用本技能中的摘要、历史记忆、搜索命中几行或仅阅读 `design.md` 替代。输出被截断时分段读完；同一任务已完整读取且文件未变化时可复用，无须反复读取。仅改数据逻辑且不涉及视觉时可标记不适用并说明原因。
 
-先确定控件与动作的接入方式，再写业务 JSX：使用 antd 时先读取并合并 [标准主题桥](references/canvas-theme-provider.md)，所有 Button、Tabs、Segmented、链接与弹层放在同一主题子树；普通 DOM 控件直接消费应用 CSS 变量。需要跨页按钮或链接时，先按 [入口契约](references/navigation-and-entry-guide.md#先建立动作与目标清单) 提取 `canvas-navigation`，填写真实资源 ID 和目标类型。本页 Tab 用状态或 hash；按钮点击和链接 href 共用同一个 URL 构造函数。缺少目标资源时保留布局并禁用该入口，不猜地址。
+在现有实现计划或检查记录中留下：实际读取的文件路径、本页适用的章节、采用的规则与对应页面区块。例如：`同色表面的卡片边界 → 客户列表白底白卡 → 主题中性细边框`。至少明确画布与浮导搭配（无自绘导航则不适用）、卡片边界、控件主题和密度留白。不要把这份记录放进页面 UI，也不要求另建文档。
 
-新建页面或调整视觉前，完整读取 [canvas-style-implementation-guide.md](references/canvas-style-implementation-guide.md)，结合当前 PRD 和 `design.md` 实现。读取结果被截断时分段读完；同一任务已读完且文件未变时可复用。仅修改数据逻辑时可跳过，并记录原因。
+读取记录只能证明输入已获取。交付前还必须按该文件检查源码及实际页面；仅写“已读”、加注释或搜索到 `border` 不代表卡片层级验收通过。尚未实测的项目标记待验证，不能勾选通过。
 
-在现有实现计划中记录适用章节、采用规则和页面位置，覆盖画布与导航、卡片边界、控件主题、密度留白。例如：`客户列表白底白卡 → 主题中性细边框`。交付前核对源码与实际页面，未实测项标为待验证。
+## 核心定位
 
-有筛选、分页、详情往返或编辑区时，先按[状态恢复规则](references/view-state-recovery.md)明确刷新与返回策略；无现有路由且无未保存编辑拦截需求时，可提取 `canvas-view-state`。有确认、取消、签到等写操作时，同时加载 `yida-canvas-data-binding`，按其业务动作权限清单核对服务端约束，再接入按钮；隐藏按钮不等于授权完成。
+本技能是宜搭自定义页面开发的默认实现：用户写标准 React18 函数组件源码，OpenYida 本地编译为 `runtimeCode` + `importedModules`，运行时由 `YidaCodeCanvas` 组件加载前端资源并执行 `YidaComp`。
 
-## 核心定位
+产品与视觉输入来自 `yida-prd` 输出的 `prd/<项目名>/prd.md` 和 `yida-design` 输出的 `prd/<项目名>/design.md`，或单页 PRD 章节 + design spec。本技能负责把 PRD 的页面场景、区块、交互、数据绑定和功能契约，以及 design.md 的主题色、视觉 DNA、布局、材质、圆角、密度、呼吸感、组件和状态规则落到 `.canvas.jsx` / `.canvas.tsx`、antd token、CSS 变量、数据桥、表单入口和发布验收。
 
-用 React18 函数组件编写 `.canvas.jsx` / `.canvas.tsx` 页面。适用于官网、工作台、列表、详情、门户、看板，以及含图表、表单入口和复杂交互的页面。
+本技能适合：
 
-从 `yida-prd` 的 `prd/<项目名>/prd.md` 读取业务目标、页面区块、交互和数据要求；从 `yida-design` 的 `prd/<项目名>/design.md` 读取主题、布局、材质、圆角、密度、组件和状态规则。单页任务读取对应 PRD 章节和设计说明。
+- 现代 React hooks 交互、图表、动效、复杂状态。
+- 首版页面生成：官网、看板、工作台、列表、详情、门户壳。
+- 需要 React18 函数组件、状态隔离和现代前端体验的页面。
+- 只需要通过 HTTP / 连接器读写数据的页面。
+- 需要在 `YidaCodeCanvas` 组件内受控接入门户、成员、部门、上传等宜搭运行态组件的页面。
 
-维护 `.oyd.jsx` / `.oyb.jsx` / `renderJsx` / 平台 `Jsx` 页面时使用 `yida-custom-page`；用户要求转为 Canvas 时，交给 `yida-canvas-upgrade`。
+若已确认目标是存量 `.oyd.jsx` / `.oyb.jsx` / `renderJsx` / 平台 `Jsx` 组件页面维护，不在本技能内改写；该历史源码只由 `yida-custom-page` 自身闭环维护。若用户要求把存量页面迁移为 `YidaCodeCanvas` 组件实现，交给 `yida-canvas-upgrade`。
 
 ## 运行时事实
 
-- 独立前台需向应用管理员提供业务工作台入口时，按 [管理员入口](references/navigation-and-entry-guide.md#管理员返回业务工作台) 提取 `canvas-admin-entry`。核对当前应用 loginUser.isAppAdmin 的明确允许值，未知时隐藏；目标来自真实管理页资源，不从访客菜单或 CLI 登录身份推断。
 - 使用 `YidaCodeCanvas` 组件实现的源码写成 `.canvas.jsx` / `.canvas.tsx`，`openyida publish` 会自动写入 `YidaCodeCanvas` Schema。
-- 页面源码路径按 Bash cwd 选择：从工作区根执行命令时用 `project/pages/src/...`；cwd 已是 `<workspace>/project` 时用 `pages/src/...`。
+- 页面源码路径按 Bash cwd 选择：从仓库根执行命令时用 `project/pages/src/...`；cwd 已是 `<workspace>/project` 时用 `pages/src/...`。
 - `runtimeCode` 在运行页面真实 `window` 中执行，入口必须返回 `YidaComp` / `YidaComp.default` / 组件函数。
-- 入口推荐写 `function YidaComp(props) { ... }`，也支持 `const App = ...; export default App;`。
+- 推荐入口写法是 `function YidaComp(props) { ... }`，或 `const App = ...; export default App;`。CLI 已兼容 `const/let/class YidaComp; export default YidaComp`，但生成新代码时优先避开同名默认导出，减少不同运行态装配器下的重复声明风险。
 - `YidaCodeCanvas` 组件使用 React 函数组件上下文；表单数据通过 yida JS-API 桥读写，平台连接器通过连接器桥调用，自定义同源接口才使用 `fetch`。
 - OpenYida 发布层会在外层普通自定义页面 `didMount` 自动注入 `window.__OPENYIDA_YIDA_API__`、`window.__OPENYIDA_UTILS__` 和 `window.__OPENYIDA_CONNECTOR_API__`。前两者暴露表单、流程及根级工具；连接器桥只接受 `Http_*` 内部 `connectorName`、`operationId`、`connectionId` 和结构化业务输入，数字连接器 ID 只用于 CLI 管理。
 - 第三方前端资源只从可用资源清单中选择；React、antd、Ant Design Icons、ahooks、d3、recharts、Radix、framer-motion、lucide-react 等必须按规则 import，由编译器写入 `importedModules`。源码严禁出现 `const { Drawer } = antd`、`const { Search } = lucideReact`、`window.antd`、`window.icons` 等手写依赖全局。
-- 宜搭运行态组件按“先探测、可用增强、fallback 保底、值统一归一化”接入；以 `window.Deep` / `window.DeepYida` 探测为主，`window.YidaNativeComponents` 作为补充来源。嵌入门户数据管理视图时使用 `DataManageViews`，并显式传入目标表单 `form.value/formUuid`。
+- 宜搭运行态组件按“先探测、可用增强、fallback 保底、值统一归一化”接入；以 `window.Deep` / `window.DeepYida` 探测为主，`window.YidaNativeComponents` 作为可用主题。嵌入门户数据管理视图时使用 `DataManageViews`，并显式传入目标表单 `form.value/formUuid`。
 
 > 可用资源清单和运行时细节见 [dependencies-and-cdn.md](references/dependencies-and-cdn.md) 与 [employeefield-verification.md](references/employeefield-verification.md)。
 
@@ -43,7 +46,7 @@ description: 宜搭自定义页面开发规范，使用 `YidaCodeCanvas` 组件
 
 | 需求 | 推荐做法 |
 | --- | --- |
-| 官网、看板、工作台、列表、详情、门户壳 | 读取 `yida-prd` 的 prd.md 与 `yida-design` 的 design.md；生成器路径再读取派生 `page-spec.json`，按页面场景实现 `.canvas.jsx` |
+| 官网、看板、工作台、列表、详情、门户壳 | 同时读取 `yida-design` 的 PRD 与 design.md；生成器路径再读取派生 `page-spec.json`，按页面场景实现 `.canvas.jsx` |
 | 需要开放 API / 连接器读写数据 | 同时加载 `yida-canvas-data-binding`；开放 API 先配置平台连接器，页面只保存资源 ID 并调用连接器桥 |
 | 需要门户 topBanner / quickEntry / 数据卡片 | 使用本技能，按“门户组件桥”接入，必要时 fallback 自绘 |
 | 需要成员、部门、附件上传、图片上传 | 使用本技能，按“宜搭组件桥”接入并归一化值 |
@@ -89,8 +92,8 @@ description: 宜搭自定义页面开发规范，使用 `YidaCodeCanvas` 组件
 5. **使用 `YidaCodeCanvas` 组件契约**：页面代码写 `YidaComp` React 函数组件；数据、生命周期和渲染都通过 hooks、props、外层 yida JS-API 桥或连接器完成。组件内部不能直接写 `this.$(fieldId)`、`this.utils.yida.*` 或 `this.dataSourceMap`。
 6. **副作用清理**：`useEffect` 注册事件、定时器、图表实例时必须返回 cleanup。
 7. **交互控件必须受控且真正驱动数据**：筛选 `Select`、搜索 `Input`/`Input.Search`、周期切换、`Tabs`/`Segmented`、批量/重置 `Button` 等控件都用 `useState` 建立受控状态，绑定 `onChange`/`onClick`，并让 `Table`/列表/卡片的数据源通过 `useMemo` 按状态派生后渲染。切换筛选后若当前选中项失效，回退选中态（如 `selected < filteredRows.length ? selected : 0`）。
-8. **视觉壳层必须消费 design.md**：写页面源码前，通过 `designRefs` 查询 `design.md` frontmatter 的 anchor 索引，读取当前页八项设计与对应共享组件、状态规则。页面外壳、焦点、布局、表面、动作、反馈和响应式都要落实，但不要求旧 `visualScaffold` 等字段。页面背景、组件样式和主题 Provider 只作用于 `YidaComp` 的组件子树，不修改平台容器；新页面的颜色映射由生成的 CanvasThemeProvider 负责。主题和当前页面明确的圆角、padding/gap、密度与分组节奏优先，通用数值只在未定义时兜底；同步到 CSS、antd 和真实布局，不用固定内距或大圆角覆盖已选主题。
-9. **按数据来源接入**：表单页面填写 `dataBinding.mode="form"`、真实 `appType/formUuid` 和字段 ID，通过 `useYidaData(binding)` / `DataBridge` 调用 `window.__OPENYIDA_YIDA_API__.searchFormDatas(params)`。每行业务字段位于 `row.formData[fieldId]`；先按 `row.formData || row.data || row` 和真实字段 ID 转为页面行数据，再把表格 `dataIndex` 绑定到转换后的字段。根级工具使用 `window.__OPENYIDA_UTILS__`。连接器填写 `Http_*` 格式的 `connectorName`、`operationId`、`connectionId`，通过 `window.__OPENYIDA_CONNECTOR_API__.invoke(binding, inputs)` 调用，Body 传对象。密钥、Cookie 和签名由平台或后端保存。数据桥、同源接口兜底与字段映射见 [数据接入](references/data-bridge-guide.md)。
+8. **视觉壳层必须消费 design.md**：工作台、门户、看板、首页、展示页和真实交付页写页面源码前，先从 `design.md` 抽取 `backgroundLayer`、`visualScaffold.rootShell`、`surfaceMap`、`componentRecipe`、`roundedRule`、`densityRule` 和 `breathingRule`。页面背景、组件样式和主题 Provider 只作用于 `YidaComp` 的组件子树，不修改平台容器；新页面的颜色映射由生成的 CanvasThemeProvider 负责。若 `design.md` 声明圆润高密和呼吸感规则，源码必须同步到 antd `borderRadius`、CSS `border-radius`、页面 padding/gap、区块间距、列表行高、状态摘要高度、空态高度和内容安全内距，并保证卡片 padding >20px、卡片 gap <20px、卡片圆角 0-32px。
+9. **表单和连接器必须使用各自的 dataBinding 契约**：完整应用、工作台、列表、看板、详情等真实交付页只要本轮已经创建或解析业务表单，先写入 `dataBinding.mode="form"`、真实 `appType/formUuid` 和字段 ID，再用本地 `useYidaData(binding)` / `DataBridge` 读取。发布层必须在外层页面 `didMount` 注册 `window.__OPENYIDA_YIDA_API__`，把 `this.utils.yida` 下官方表单、流程、表单设计 API 和运行态已有函数同步暴露给 `YidaCodeCanvas` 组件；同时注册 `window.__OPENYIDA_UTILS__`，把 `this.utils.toast/dialog/router.push/openPage/isMobile` 等根级工具暴露给组件，且 `window.__OPENYIDA_UTILS__.yida` 指向同一个 yida API 桥。表单读取默认调用 `window.__OPENYIDA_YIDA_API__.searchFormDatas(params)`，流程能力可通过 `startProcessInstance`、`getProcessInstances`、`getProcessInstanceById` 等方法调用，其他运行态方法可通过 `request`、`searchUserList` 或运行时自动枚举出的同名方法调用。只有桥不可用时才降级同源直连 `/dingtalk/web/<appType>/v1/form/searchFormDatas.json`。`searchFormDatas` 的每行业务字段位于 `row.formData[fieldId]`；列表、卡片和详情展示必须先用真实字段 ID 把 `row.formData || row.data || row` 归一化为页面行模型，不能把字段 ID 直接作为原始行顶层的 `dataIndex`，否则会出现“有记录但全部显示空值/--”的伪成功。连接器绑定必须写入真实 `connectorName/operationId/connectionId`，其中 `connectorName` 以 `Http_` 开头；Body 直接传对象，不使用 `JSON.stringify`。页面调用 `window.__OPENYIDA_CONNECTOR_API__.invoke(binding, inputs)`；页面不能保存 AK/SK、请求任意外部 URL，也不能使用 `/query/form/searchFormDatas.json` 或只写前端 seedRows 后声称已接真实数据。
 10. **表单排序只使用真实业务字段 ID**：`searchFormDatas` 的 `dynamicOrder` key 必须来自当前 `get-schema` 返回的真实业务字段 ID，禁止使用返回记录的元数据名 `gmtCreate`，不得生成 `dynamicOrder: { "gmtCreate": "-" }`。没有可排序的业务日期字段时删除 `dynamicOrder`；如仅需调整当前已取回页的展示顺序，可在响应解包后按 `row.createTime` 排序，但不能声称实现了跨页稳定排序。遇到 `selectListException 无法找到字段:gmtCreate` 时，先移除错误排序参数、重新回读 Schema 并使用真实字段 ID，再重新发布。
 11. **分页查询默认写 50**：表单、流程、任务、成员等分页查询参数一般显式写 `pageSize: 50` 或 `pageSize: '50'`。只有用户明确要求小页或大页时才改成其他值，且不得超过平台上限 100。
 12. **源码保持零未绑定标识符**：每个 import、辅助函数、Ref、状态、局部变量和函数参数都在同一文件声明后使用。非标准运行时能力通过 `window.<name>` 或 `parentWindow.<name>` 获取，调用前检查目标方法。`compileCanvasLocal` 报 `OPENYIDA_CANVAS_UNBOUND_IDENTIFIER` 时，一次修复 `details.issues` 中的全部名称，再重新编译。
@@ -106,44 +109,44 @@ function setNavigationTitle(title) {
 }
 ```
 
-> 编译通过后仍需检查变量拼写：`name`、`status`、`length`、`event`、`origin`、`top` 是浏览器全局名称，误写成这些名字时编译器也可能放行。
+> **未绑定标识符守卫边界**：该守卫只拦截不属于 ECMAScript、Browser 或 Canvas wrapper 白名单的裸标识符。`name`、`status`、`length`、`event`、`origin`、`top` 等浏览器标准短名会解析为 `window` 属性，无法判断它原本是否是业务变量拼写错误；例如把 `orderName` 误写成 `name`、把 `rowStatus` 误写成 `status` 或把 `listLength` 误写成 `length` 都不会被拦截。守卫主要兜底 `getInstId`、`loadedRef` 这类自定义名，不代表能发现全部拼写错误；生成或重命名代码后仍须逐项核对业务标识符。
 
 ### 重要规则（IMPORTANT）
 
-1. **按数据来源选择接口**：表单使用 yida 数据桥，平台连接器使用连接器桥，自定义同源业务接口使用明确的 endpoint。详见上方“按数据来源接入”。
+1. **数据桥显式化**：表单数据默认通过外层 yida JS-API 桥读写；平台连接器只通过 `window.__OPENYIDA_CONNECTOR_API__.invoke(binding, inputs)` 调用；自定义同源业务接口才通过显式 endpoint 读写。Cookie、CSRF、密钥和签名留在平台、连接器或后端服务侧。
 2. **组件增强可降级**：门户、成员、部门、上传组件都做 feature detect 和 fallback；组件缺失时页面仍展示自绘基线。
 3. **值先归一化**：成员、部门、文件的原始返回值保留到 `raw` 用于检查，业务 payload 使用统一结构。
 4. **UI 改造保持功能契约**：页面美感提升、页面重构和局部美化只调整颜色、布局、密度、间距、视觉层级、素材和图标表达；已有数据源、字段映射、按钮动作、筛选逻辑、提交 URL、权限和业务状态按原有实现保留。
-5. **页面跟随应用主题**：应用设置使用 `app-theme.css`；页面通过 `--color-brand1-*`、`--color-group` 和 `--pod-*` 取色。页面底色使用 `--pod-page-bg-color`，卡片使用 `--pod-card-bg-color`，抽屉外壳背景使用 `--pod-shell-theme-bg-color`，正文容器保持透明；自绘导航页按 `design.md` 设置内部画布背景。样式限定在 `YidaComp` 内，应用主题通过 `update-app --theme-file` 更新。根节点使用 `display:flow-root` 或 flex/grid，将导航间距留在根节点内部。宿主背景和局部画布规则见 [样式指南](references/canvas-style-implementation-guide.md)。
+5. **主题只消费、不上注**：`app-theme.css` 是应用级唯一主题文件。CLI 生成的 Canvas Page 宿主必须让 `contentBgColor`、`pageStyle.backgroundColor` 和 `contentBgColorMobile` 使用 `var(--pod-page-bg-color, var(--color-white, #fff))`；普通自定义页根节点默认消费同一平台背景 token；自绘应用导航页可按 `design.md` 为内部画布设置局部背景或渐变，平台宿主仍消费原 token，不能向全局注入另一套背景。隐藏导航本身不自动改变底色，卡片和面板消费 `--pod-card-bg-color`。根节点使用 `display:flow-root` 或 flex/grid，保留浮导间距在根节点内部；这是宿主容器消费应用 token，不是注入主题。`YidaComp` 内使用 `--color-brand1-*`、`--color-group` 和 `--pod-*`；严禁修改 `document.documentElement`、`document.body`、父页面或平台容器的主题变量，也不得从页面代码上传或更新应用主题。
 6. **先验证再扩展业务**：原生组件、上传、组织搜索、弹层类能力先做 smoke 页面，确认 PC/移动端都可用后再进入复杂业务页面。
-7. **按设计编写 UI，示例按需参考**：新建 `.canvas.jsx` / `.canvas.tsx` 时，直接按 PRD、`design.md`、真实数据和页面交互实现，允许从空文件编写。需要参考完整表单交互时，可执行 `openyida sample openyida-page-template canvas-form-drawer --output .cache/samples/form-drawer.canvas.jsx --var APP_TYPE=<appType> --var FORM_UUID=<formUuid>`；整页示例按需参考；含表单打开入口时，必须按下方“表单打开入口统一容器”整体合并抽屉片段，不能裁剪交互能力。页面其余布局、材质、留白、圆角和选中态按设计实现。未改写的示例不得直接发布；页面 UI、业务文案、交付说明和 final 中不出现内部示例名、生成过程或实现代号。使用示例时，发布前删除 `@openyida-page-template-base`、`SAMPLE_ROWS`、`{{APP_TYPE}}` / `{{FORM_UUID}}`、示例数据和占位文案。
-8. **用文件编辑工具维护源码**：业务源码使用 Write/Edit/patch 编写，已有 JSX/CSS/JSON 源码只做定点 Edit。主题代码使用 `sample` 提取，或由 `scripts/build-canvas-theme.js` 插入标记处并输出独立文件。修改业务时编辑原始文件，再重新运行主题脚本。
-9. **按整页关系配色**：业务列表、协同表、数据管理页、工作台和门户默认使用 light 模式；指标、按钮和选中态按 `design.md` 的颜色角色实现，可用与品牌不同但协调的颜色，不默认黑色或全部使用主色。按[指标卡与按钮配色](../yida-design/references/application-theme-consistency.md#指标卡与按钮配色)检查背景、前景、强调面积和交互状态。用户明确要求暗色大屏/夜间模式/高对比风格时使用深色主视觉。
+7. **按设计编写 UI，示例按需参考**：新建 `.canvas.jsx` / `.canvas.tsx` 时，直接按 PRD、`design.md`、真实数据和页面交互实现，允许从空文件编写。需要参考完整表单交互时，可执行 `openyida sample openyida-page-template canvas-form-drawer --output .cache/samples/form-drawer.canvas.jsx --var APP_TYPE=<appType> --var FORM_UUID=<formUuid>`；整页示例按需参考；含表单打开入口时，必须按第 19 条整体合并抽屉片段，不能裁剪交互能力。页面其余布局、材质、留白、圆角和选中态按设计实现。未改写的示例不得直接发布；页面 UI、业务文案、交付说明和 final 中不出现内部示例名、生成过程或实现代号。使用示例时，发布前删除 `@openyida-page-template-base`、`SAMPLE_ROWS`、`{{APP_TYPE}}` / `{{FORM_UUID}}`、示例数据和占位文案。
+8. **业务源码用文件编辑工具维护**：业务组件通过 Write/Edit/patch 编写；已有 JSX/CSS/JSON 源码只做定点 Edit。不得用 Python、Node、Shell 或 `run_workspace_script` 任意生成、搬运或整文件改写业务源码。唯一的主题装配例外是本技能 `scripts/build-canvas-theme.js`：它只在一个显式标记处插入受维护的 Provider，输出独立派生文件，不改业务输入和 app-theme.css。修改业务仍回到输入文件；此例外不允许绕过用户的只读要求或源码修改禁令。
+9. **light 页面使用清爽业务色**：业务列表、协同表、数据管理页、工作台和门户默认使用 light 模式；主操作、选中态、筛选焦点和批量操作使用品牌色，边框用浅色品牌混合。用户明确要求暗色大屏/夜间模式/高对比风格时使用深色主视觉。
 10. **门户运行态组件要补必需 props 和局部降级**：`QuickAccessCard` / `RecentlyUsedCard` 传 `theme="row-white"` 等必需 props；所有门户/字段/上传增强组件外层加局部 ErrorBoundary，单个组件不兼容时只降级该块，整页保持可用。
+11. **消费设计结果**：页面直接使用 `yida-design` 已确定的视觉 token、布局、材质和组件规则。
+12. **真实交付使用真实数据源**：完整应用或真实交付页只要需要列表、看板、详情记录，并且本轮已经创建/解析业务表单，就在 `page-spec.json` 写入 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射，让页面从表单读取。完整应用默认在页面实现前通过 `yida-data-management` 写入 1-3 条业务化 demo records；页面读取这些真实表单记录，不使用前端 seedRows 冒充。真实数据暂未接入或 seed records 写入失败时展示空态、表单入口、刷新/登记按钮。
+13. **PRD + design.md 进入实现输入**：完整应用和真实交付页在写页面前，先消费 `yida-prd` 的 `prd/<项目名>/prd.md` 和 `yida-design` 的 `prd/<项目名>/design.md`。PRD 提供产品定位、页面场景、页面区块、数据来源、`functionContract`、素材/图标策略、原生表单入口、页面实现交付顺序、业务化自检、应用主题色和风格摘要；design.md 提供完整 UI 设计，包括 `themeProfile`、tokens、视觉 DNA、`visualScaffold`、材质、组件、圆角、密度、呼吸感和状态规则。两者是唯一设计事实源；`page-spec.json` 只能作为派生 handoff，不得覆盖或改写 PRD/design.md，也不得复制完整 UI 设计规则。
+14. **页面实现二选一**：结构化实现路径先从 `prd.md + design.md` 派生 `page-spec.json`，写入 `sourceOfTruth.prdFile/designFile/designRefs/conflictPolicy`，生成可编译骨架后读取 CLI 摘要或 `.openyida-page.json` 判断业务化程度和 dataBinding。业务或视觉事实源缺失时先回写 `prd.md` / `design.md` 并重生成 spec；只有 className、布局比例、字段映射、响应式、状态渲染或编译错误等实现偏差才对生成源码做小范围 Edit/patch。手写路径直接 Write 最终 `.canvas.jsx` 并快检/发布。
+15. **实现骨架消费业务 spec**：品牌名、行业词、导航、指标、卡片标题、图片 alt、CTA、色彩 profile 和 section 说明来自当前业务 spec。若 CLI 报业务内容不足，补齐/改写 spec 或 patch 源码后重新生成/编译。
+16. **页面产物使用纯文本业务文案**：`.canvas.jsx` 源码、`page-spec.json` 中会渲染到页面的文案、JS 注释、数据常量和产物文件路径都使用无 emoji 文本。页面生成、`compileCanvasLocal` 或 `publish` 报 emoji 错误时，先改 spec/源码/路径，再重新校验发布。若 emoji 原本承担图标含义，必须按 `design.md.iconSystem` 改成 `lucide-react` 或 `@ant-design/icons` 的具体组件，默认 `lucide-react`；不得用 CSS 绘制图形、单字母、首字母、标点符号、Unicode 符号或临时 SVG 冒充图标。
+17. **JSX 文案只能是文本或字符串**：JSX 文案只能写成纯文本 `所有级别` 或带引号字符串 `{'所有级别'}`；筛选项、按钮、状态、空态和表格列名等中文业务文案都按此规则书写。花括号里只能放真实 JS 变量/表达式，不能把中文文案写成 `{所有级别}`、`{处理中}`；Unicode escape 被工具解码后也必须保留字符串引号。
+18. **应用级导航归平台承载**：默认不要在自定义页面中创建侧边导航、顶部应用导航、门户导航壳或同级模块菜单；同应用页面入口优先写入 `appBlueprint.navigation` 或平台导航分组，由应用导航内切换。自定义页内容区只放当前页动作、表单新建/查看、外部链接、跨应用资源。只有用户显式要求“在自定义页面中实现自己的顶部导航 / 侧边导航 / 导航壳 / 自绘应用级导航 / 隐藏应用导航”时，才执行 `use_skill("yida-nav-shell")`，生成页面内导航壳，并在发布后执行 `openyida update-app <appType> --hide-app-nav`；只要求页面隐藏导航、无导航全屏或 `isRenderNav=false` 时，走页面级配置，不自动配置 `hideAppNav`。其他自定义页默认不配置 `hideAppNav`。
+19. **表单打开入口统一容器**：页面内新增、提交和详情操作统一使用 `FormOpenContainer`，接入真实表单、实例 ID 和刷新函数。**MUST** 先执行 `openyida sample openyida-page-template form-open-container --output .cache/samples/form-open-container.jsx` 拉取当前模板，再整体合并 `CanvasDrawer` / `FormOpenContainer` / `useYidaFormOpen` 及依赖的辅助函数和 import。禁止自绘 fixed 遮罩 + iframe 抽屉壳；必须保留 `.openyida-form-drawer`、三个 header 图标操作、拖拽调宽、关闭刷新、移动端处理和 iframe 自适应高度。设计调整通过模板主题变量和已有 props 完成，不得重写外壳。调用方式见 [容器接入示例](references/navigation-and-entry-guide.md#接入示例)。应用级报名、申请等导航入口按 [入口用途](../yida-nav-shell/references/nav-shell-patterns.md#入口用途与嵌入页面) 在主内容区嵌入提交页。
+20. **图标资源固定为可加载库**：页面图标只使用 `lucide-react` 或 `@ant-design/icons`，默认使用 `lucide-react` named import。只有页面已经采用 Ant Design 图标语言、或 antd 组件语境需要 Outlined 图标时，才使用 `@ant-design/icons`。快捷入口、按钮、状态、导航和空态图标在写源码前先建立 `actionIconMap` / `statusIconMap`，按业务语义映射到具体组件，例如 `Plus`、`Upload`、`Download`、`Eye`、`Building2`、`AlertCircle`、`Check`。图标外层可以用 CSS 控制尺寸、颜色、圆角、背景和 hover，但图标本体必须来自上述两类组件，不能用 CSS 形状、字母或 emoji 替代。
 
-11. **选择页面编写方式**：结构明确时直接编写 `.canvas.jsx`；使用生成器时，从 `prd.md + design.md` 整理 `page-spec.json`，填写 `sourceOfTruth.prdFile/designFile/designRefs/conflictPolicy`，生成后读取 CLI 摘要或 `.openyida-page.json`。业务缺漏补 PRD，视觉缺漏补 design.md，再更新 spec；源码中的布局、字段映射或编译问题直接 Edit/patch。详见 [页面生成](references/page-generation-guide.md)。
-12. **实现骨架消费业务 spec**：品牌名、行业词、导航、指标、卡片标题、图片 alt、CTA、色彩 profile 和 section 说明来自当前业务 spec。若 CLI 报业务内容不足，补齐/改写 spec 或 patch 源码后重新生成/编译。
-13. **页面产物使用纯文本业务文案**：`.canvas.jsx` 源码、`page-spec.json` 中会渲染到页面的文案、JS 注释、数据常量和产物文件路径都使用无 emoji 文本。页面生成、`compileCanvasLocal` 或 `publish` 报 emoji 错误时，先改 spec/源码/路径，再重新校验发布。若 emoji 原本承担图标含义，必须按 `design.md.iconSystem` 改成 `lucide-react` 或 `@ant-design/icons` 的具体组件，默认 `lucide-react`；不得用 CSS 绘制图形、单字母、首字母、标点符号、Unicode 符号或临时 SVG 冒充图标。
-14. **JSX 文案只能是文本或字符串**：JSX 文案只能写成纯文本 `所有级别` 或带引号字符串 `{'所有级别'}`；筛选项、按钮、状态、空态和表格列名等中文业务文案都按此规则书写。花括号里只能放真实 JS 变量/表达式，不能把中文文案写成 `{所有级别}`、`{处理中}`；Unicode escape 被工具解码后也必须保留字符串引号。
-15. **先区分应用导航与入口菜单**：按 PRD 应用 navigationType 和当前页 pageSpecHandoff.entryMode/navigation 执行。普通页默认保留平台导航，页面内 tab 不触发应用级隐藏；独立前台可有自己的顶部、侧边或底部菜单，执行 `use_skill("yida-nav-shell")` 的页面级分支，只配置当前页。仅整个应用采用自定义导航时才执行 `openyida update-app <appType> --hide-app-nav`；不得因前台 custom 隐藏后台应用菜单。
-16. **表单提交必须接入提供的抽屉模板（登录态默认，匿名态窄例外）**：前台、后台、Fast、Plan 的页面内新增、报名、申请、预约等普通登录态表单提交，以及表单详情入口，统一使用 `FormOpenContainer`；不能因为页面是全码开发就自绘填写表单并直接调用登录态提交 API，也不能由 AI 自行改成普通链接、新窗口或简化弹层。先执行 `openyida sample openyida-page-template form-open-container --output .cache/samples/form-open-container.jsx`，整体合并 `CanvasDrawer` / `FormOpenContainer` / `useYidaFormOpen` 及其 import 和辅助函数。业务按钮调用 `openForm`，页面 JSX 必须渲染 `formOpenContainer`，接入真实表单、实例 ID 和刷新函数。保留三个标题栏图标操作、拖拽调宽、关闭刷新和 iframe 自适应高度；移动端打开方式由模板处理。只能通过主题变量和现有 props 调整外观，不重写外壳。搜索筛选不是表单提交；已明确的表格批量录入沿用专用技能。应用级导航已确定在主内容区嵌入原生提交页时按 [入口用途](../yida-nav-shell/references/nav-shell-patterns.md#入口用途与嵌入页面) 执行；不能以此绕过页面内按钮的抽屉要求。接入步骤见 [标准容器](references/navigation-and-entry-guide.md#接入示例)。唯一窄例外是用户明确要求 `/o/...` 公开页面匿名采集，且显示页、目标普通表单公开状态和目标表单 `FREE_LOGIN` 权限三项门禁均已回读通过；此时加载 `yida-canvas-data-binding`，按[公开访问（匿名态）提交](references/data-bridge-guide.md#公开访问匿名态提交)自绘受控字段并走 `RECEIPT_SAVE_FORM_DATA`，发布后必须按返回的实例 ID 回读字段值。任一门禁不满足、需要流程或需要真实身份时仍使用登录态方案，不适用该例外。
-17. **图标资源固定为可加载库**：页面图标只使用 `lucide-react` 或 `@ant-design/icons`，默认使用 `lucide-react` named import。只有页面已经采用 Ant Design 图标语言、或 antd 组件语境需要 Outlined 图标时，才使用 `@ant-design/icons`。快捷入口、按钮、状态、导航和空态图标在写源码前先建立 `actionIconMap` / `statusIconMap`，按业务语义映射到具体组件，例如 `Plus`、`Upload`、`Download`、`Eye`、`Building2`、`AlertCircle`、`Check`。图标外层可以用 CSS 控制尺寸、颜色、圆角、背景和 hover，但图标本体必须来自上述两类组件，不能用 CSS 形状、字母或 emoji 替代。包名可用不代表任意图标都存在；以宜搭运行时导出为准，不照搬最新版官网名称。`OPENYIDA_CANVAS_ICON_EXPORT_UNAVAILABLE` 必须修正具体 import 后重新编译；动态名称使用显式组件映射并提供可用图标兜底，详见 [运行时图标校验](references/component-library-guide.md#运行时图标校验)。
-
-18. **对话框统一消费主题 token**：新增或改造对话框时，执行 `openyida sample openyida-page-template canvas-dialog --output .cache/samples/canvas-dialog.jsx`，将 `CanvasDialog` 合并到当前页面并接入业务状态，见 [对话框](references/dialog-guide.md)。标题、正文、背景、页脚、关闭按钮和操作按钮均消费应用 token；整体暗色适配与导航明暗分别判断。
+21. **对话框统一消费主题 token**：新增或改造对话框时，执行 `openyida sample openyida-page-template canvas-dialog --output .cache/samples/canvas-dialog.jsx`，将 `CanvasDialog` 合并到当前页面并接入业务状态，见 [对话框](references/dialog-guide.md)。标题、正文、背景、页脚、关闭按钮和操作按钮均消费应用 token；整体暗色适配与导航明暗分别判断。
 
-19. **Header 工具操作默认用图标按钮**：页面、卡片、弹窗和抽屉标题栏中的刷新、新窗口打开、全屏、关闭等工具操作，默认使用无可见文字的图标按钮，并提供 `title` 提示、`aria-label` 和键盘焦点样式。新增、提交、保存等业务主操作可保留文字。表单抽屉必须保留新窗口打开、全屏/退出全屏、关闭三个图标按钮，不能简化为文字链接或省略全屏；实现与验收见 [标准 FormOpenContainer](references/navigation-and-entry-guide.md#标准-formopencontainer)。
+22. **Header 工具操作默认用图标按钮**：页面、卡片、弹窗和抽屉标题栏中的刷新、新窗口打开、全屏、关闭等工具操作，默认使用无可见文字的图标按钮，并提供 `title` 提示、`aria-label` 和键盘焦点样式。新增、提交、保存等业务主操作可保留文字。表单抽屉必须保留新窗口打开、全屏/退出全屏、关闭三个图标按钮，不能简化为文字链接或省略全屏；实现与验收见 [标准 FormOpenContainer](references/navigation-and-entry-guide.md#标准-formopencontainer)。
 
-20. **同色页面与卡片要有边界**：白色或近白背景上的白色独立卡片、面板、表格外壳，使用细边框或清晰柔和的投影区分层级；浅灰或浅彩色背景上的白卡默认无边框，利用底色对比形成层级。边框使用主题中性分割线 token，投影沿用应用已确认的阴影规则，不默认叠加边框和投影。无框内容区不强行卡片化，iframe 外层不加卡片。实现及验收见 [同色表面的卡片边界](references/canvas-style-implementation-guide.md#同色表面的卡片边界)。
+23. **同色页面与卡片要有边界**：白色或近白背景上的白色独立卡片、面板、表格外壳，使用细边框或清晰柔和的投影区分层级；浅灰或浅彩色背景上的白卡默认无边框，利用底色对比形成层级。边框使用主题中性分割线 token，投影沿用应用已确认的阴影规则，不默认叠加边框和投影。无框内容区不强行卡片化，iframe 外层不加卡片。实现及验收见 [同色表面的卡片边界](references/canvas-style-implementation-guide.md#同色表面的卡片边界)。
 
 ## 主题实现入口
 
-纯 DOM 页面直接消费平台 CSS 变量，不必引入 antd 或 Provider。按 [共用主题规则](../yida-design/references/application-theme-consistency.md) 引用画布、卡片、文字与特色角色；风格缺项回写设计源，不在页面根复制固定色盘。
+纯 DOM 页面直接消费平台 CSS 变量，不必引入 antd 或 Provider。
 
-antd 页面使用 CanvasThemeProvider，图表通过 useCanvasThemeContext 取色。`sample` 输出的表单抽屉、批量表格和趋势图页面已包含主题与加载遮罩防闪边样式，合并代码时保留 Provider 内的 style；其他页面及旧页面升级按 [主题接入步骤](references/canvas-theme-provider.md) 操作。
+新写或改造 antd Canvas 页面时，使用本技能 `scripts/build-canvas-theme.js`，输入本地 app-theme.css 和真实上传 URL，生成 CanvasThemeProvider 测试页或展开业务页面的适配层。业务代码只包 Provider，不再手写变量映射和监听；图表按需使用 useCanvasThemeContext。页面底色统一消费 --pod-page-bg-color，卡片消费 --pod-card-bg-color。具体命令、preview 与应用主题模式、编译发布边界见 [CanvasThemeProvider 脚本指南](references/canvas-theme-provider.md)。已有 useCanvasTheme 页面可暂时保留，迁移时移除重复 Provider 和 hook。
 
-页面入口按 `YidaComp → CanvasThemeProvider → PageContent` 组织，主题 hook 放在 PageContent 或其子组件内。编译通过后，打开实际页面检查首屏、主题和交互。
-
-## 接入真实数据
+## 数据真实性边界
 
 - 完整应用或真实交付页先解析真实 `appType/formUuid/fieldId`，并在 `page-spec.json` 写入 `dataBinding.mode=form`。
 - 完整应用默认先用 `yida-data-management` 把 1-3 条业务化 seed records 写入核心普通表单并抽查，再让页面读取；前端静态数据只能用于明确标注的离线演示态。
@@ -152,7 +155,7 @@ antd 页面使用 CanvasThemeProvider，图表通过 useCanvasThemeContext 取
 
 ## 开发流程
 
-下面命令从工作区根执行；cwd 已是 `<workspace>/project` 时，把 `project/pages/src/...` 改为 `pages/src/...`。文件内容使用当前工具的 Read / Glob / Grep 读取。
+下面命令以仓库根为视角；如果当前 cwd 已经是 `<workspace>/project`，把 `project/pages/src/...` 改成 `pages/src/...`。读取生成文件、Schema 或校验产物时优先用当前工具的 Read / Glob / Grep。
 
 ```bash
 # 1. 只读检查环境、登录态和可用能力；真实创建资源前必须通过
@@ -176,8 +179,6 @@ openyida publish project/pages/src/<页面名>.canvas.jsx <appType> <formUuid>
 openyida get-schema <appType> <formUuid> --field-map-json
 ```
 
-导航生成前读取 [页面与导航连续性](../yida-design/references/page-continuity.md)。纯页内展示直接切换本地视图或用 canvas-nav-data 的 local 模式；真实资源才按 platform/independent 过滤。长页提取最新 canvas-nav-content，使用 document 自然高度；顶部模板以 headerOnly 接入，有首屏背景用 overlay。`OPENYIDA_CANVAS_NAVIGATION_INVALID` 按 details.issueType 和源码行修正，禁止删除检查或回退全量菜单；动态数据与宿主滚动仍需实际浏览器验收。
-
 `openyida compile` 会自动识别 `.canvas.jsx` / `.canvas.tsx` 并调用 Canvas 编译器；`--json` 返回可机器读取的 hash 和依赖清单。该命令只读、无需登录、不访问网络、不发布页面，也不写入构建产物。`openyida publish` 仍是远端写入证据。
 
 云端与本地 Agent 都使用同一条 `openyida compile <页面源码.canvas.jsx> --json` 快检命令，不依赖仅云端 Builder 提供的 `run_workspace_script`。
@@ -196,7 +197,7 @@ openyida get-schema <appType> <formUuid> --field-map-json
 | [dependencies-and-cdn.md](references/dependencies-and-cdn.md) | 可用前端资源、import 写法、运行时加载方式 | 选择或验证前端资源时必读 |
 | [employeefield-verification.md](references/employeefield-verification.md) | 运行时事实、原生组件验证、EmployeeField 验收 | 验证成员/字段组件时阅读 |
 | [data-bridge-guide.md](references/data-bridge-guide.md) | 表单、平台连接器与自定义同源接口的数据桥 | 接入真实数据时阅读 |
-| [canvas-theme-provider.md](references/canvas-theme-provider.md) | 统一主题接入、示例装配、预览与发布 | 编写或调整 antd 页面时必读 |
+| [canvas-theme-provider.md](references/canvas-theme-provider.md) | 主题脚本、新页面接入、旧页面迁移、预览与发布 | 新写或迁移 antd 页面时必读 |
 | [canvas-style-implementation-guide.md](references/canvas-style-implementation-guide.md) | 将 `design.md` 的 App 主题色、antd token、背景层、卡片边界、圆角密度、控件焦点/下拉 reset、图表配色落到 `YidaCodeCanvas` 组件 | MUST：新建页面或调整视觉前完整读取，见顶部编码前必读 |
 | [component-library-guide.md](references/component-library-guide.md) | 组件库推荐组合和页面选型建议 | 选择 UI/图表依赖时阅读 |
 | [canvas-authoring-examples.md](references/canvas-authoring-examples.md) | 最小组件、hooks、副作用、图表示例 | 手写 `.canvas.jsx` 代码时阅读 |