xiaomi HiUI 典型页 Skill
Positioning
本 skill 是 HiUI React 页面工程的标准生成协议与交付治理控制面。page-task-plan.v1 继续是唯一顶层执行入口；generationRecipe 是其内部的正向生成子协议；交付完成态仍由 preflight-report.v1、hiui-page-governance-report.v1、acceptanceProfile 与 finalReportContract 决定。主叙事是“先按 recipe 正确生成，再由验收确认”，而不是“先生成一版，再靠验收纠偏”。
标准典型页命中 page-component + slot-fill 时，默认走 minimal-doc fast path：优先消费 planner、scaffold 与 slot contract，不再手工展开大段治理文档；复杂页、漂移页和正式验收场景才升级到完整规则链路。
legacy-host-compatible 的主路径统一为 project-certified carrier first -> page-component semantics -> explicit fallback。宿主承接事实成立时，应优先消费项目认证 carrier 或已认证页面组件，managed-translation 只保留为显式 fallback。runtime-bridged-page-component 只是 legacy 中对 page-component 的桥接语义命名，不引入平行 generation family；命中 header 时，只有 carrier certification、page contract 与 preflight 能共同证明 PageHeader stretch、extra right-docked 和 60px 节奏 owner 不漂移，主链路才成立。
对外沟通时要把两件事拆开说明：legacy 宿主主树不能被当成 generic @hiui-design/typical-page-shells 直挂运行时，不等于 legacy 项目不能走普通典型页组件主链。只要 planner 已给出 page-component + runtime bridge + slot fill，就必须沿该主链执行，不得把“不能 ad hoc direct shell import”误读成“只能 reference/fallback”。
Core Object Model
page-task-plan.v1是唯一执行计划与事实出口；AI 不手工拼mode、pageType、pageUnits、startFrom、requiredDocs、requiredActions或关键命令链。generationRecipe作为page-task-plan.v1的增量子对象引入，不单独创建平行顶层 contract。generationRecipe只描述装配顺序、资产映射、槽位边界、禁止动作与轻量一致性检查；不重复存储可由pageComponent、baseMoldId、registry 或既有 contract 派生出的事实。targetDeliverySemantics与currentExecutionState必须分层输出：前者回答“计划成立后应沿哪条受管交付主链落地”，后者回答“当前这一步允许执行什么”。legacy blocked 时，前者仍可保留page-component + runtime bridge + slot fill目标语义，但后者必须只暴露ResolveBlockingFacts。editableSlots、lockedRegions、pageComponent、baseMoldId优先保持“引用或派生”，不复制进 planner。runtimeBridgeProfile只作为 legacypage-component路径的附加解析对象存在；它通过rules/runtime-bridged-component-matrix.json描述运行时桥接策略，不重定义pageComponent、baseMoldId、lockedRegions或业务槽位事实。- project 级
host pack、project-scopedpage carrier与其认证结果属于运行时 / 资产事实，默认由计划通过facts、assetResolution、pageComponent等字段引用；不要把这些事实再平铺复制进每个页面合同。 - carrier-critical layout facts，尤其
header的 stretch owner、actions docking 与 vertical rhythm owner，属于 contract + certification + preflight 共同消费的机器事实；不得退化成只存在于说明文档里的软建议。 acceptanceProfile、preflight-report.v1、hiui-page-governance-report.v1、finalReportContract继续保留，不降级、不移除。requiredDocs是默认唯一补读来源；其最小结构固定为path、readMode、reason。先读readMode=required，reference/conditional只在命中对应场景时补读。requiredActions是默认唯一执行来源；没有结构化动作时，优先使用兼容命令字段，不自行扩展 gate。
对象模型与字段分级：docs/generation/explainers/core-object-model.md
Standard Generation Protocol
Standard Generation Protocol 只回答 4 个问题：
- 从什么骨架起步。
- 关键 region 的装配顺序是什么。
- 哪些区域允许业务填充。
- 每完成一个关键步骤后做什么
inlineChecks。
generationRecipe.required 默认至少包含：
startingPointassemblyOrderrequiredAssetsforbiddenMoves
generationRecipe.optional 可按页型与复杂度逐步补齐：
slotFillPolicyregionOwnershipinlineChecks
第一批 recipe 只覆盖高频页型：
table-pageanalytics-pageedit/detail-page
标准生成协议补读：docs/generation/explainers/standard-generation-protocol.md
Guardrails
- 本 skill 只处理 HiUI React 页面工程任务；需求细化、端到端流程编排、Figma 写入 / 设计稿生成、通用 React 重构必须交给对应 skill 或普通代码流程。
- 页面生成、重写、大改、页型迁移和旧系统 / 截图转译必须先取得
page-task-plan.v1；没有机器计划时不得手工拼结论、命令链或完成态。 blockingIssues/blockingReasons非空时必须 fail closed，只补事实；不得生成页面、写合同、跑 preflight 或输出完成态。- 资产新增、补齐和更新只能走 shipped public contract；
add-asset/update-asset必须 dry-run，未 shipped 的 write / force / asset type 不得执行。 - 未经机器计划明确授权或维护者明确要求，不得执行 deploy、upload、publish、sync、global sync、Feishu / bitable 后台写入、release archive 生成或历史输出覆盖。
- 涉及外部服务、后台 agent、launch agent、守护进程或用户配置写入的动作，执行前必须同时验证目标范围、授权来源和 side effect 边界；缺任一条件时必须拒绝执行。
preflightfailed、hard profile governance failed、source snapshot 缺失 / 低置信度、acceptance contract缺 provenance 时，最终回复必须是 blocked / failed。- 开源版不得采集 usage data，必须按
PRIVACY.md呈现not_applicable、skipped或unavailable。
Generation Gates
- 生成前门禁：项目根、机器计划、能力画像、mode lock、pre-plan facts。
- 生成协议门禁：page-component 可用性、route ownership、slot 边界、shell / adapter 证明、analytics contract、业务内容边界、受控扩展。
legacy-host-compatible普通典型页的硬门禁真相统一收口到rules/legacy-host-hard-gates.json：baseline 固定为 4 个硬门禁，命中header时再追加header-layout-proof条件门禁，因此当前常见典型页通常会落到 5 个有效硬门禁。styleBoundary、portalBoundary、runtimeSmoke仍按风险触发；但header的 stretch / right-dock / rhythm owner 不再只是样式建议，缺少结构化证明时必须阻断主链路。legacy-host-compatible下若 planner 已证明page-componentready 且runtimeAdapterProof.status=available，默认执行语义就是page-component + runtime bridge + slot fill。缺少 legacy 主树 direct shell import 前提，只能阻止 ad hoc standard-shell mount，不能作为擅自降级到兼容手拼页、reference 默认翻译页或自由 fallback 的理由。- 前两层门禁属于“如何正确生成”的组成部分，不再和交付阻断口吻混写。
required级generationRecipe字段缺失时，不得假设或手工脑补；只能 blocked， 或按计划明确给出的 fallback 执行。startingPoint无法解析、requiredAssets不可用、或assemblyOrder不完整时， 不允许自由退回空白页手写。- 只有当计划明确给出
managed-fallback、host-archetype或reference-or-scaffold为合法 fallback 时，才允许降级生成。 optional字段缺失不自动阻断，但不得伪造填充；缺失时按页型默认策略或现有规则执行。
生成门禁细节：docs/generation/explainers/generation-gates.md
Delivery Gates
preflight-report.v1与hiui-page-governance-report.v1继续是交付确认层核心判断对象。acceptanceProfile决定验收范围；formal acceptance是验收等级，不是生成链路。finalReportContract继续保留，用于完整报告与下游兼容。- 交付门禁只负责“是否允许宣告完成”，不再主导生成叙事。
- 若某类问题连续多次在
DeliveryConfirmation阶段暴露，必须优先回灌到generationRecipe或 generation gates，而不是持续追加新的验收描述。
交付门禁细节：docs/generation/explainers/delivery-gates.md
Runtime Protocol
- 运行时协议的唯一真相是
rules/runtime-contract.md；受管页面治理协议的唯一真相是rules/page-governance.md。 rules/runtime-bridged-component-matrix.json是 legacypage-component桥接语义的唯一真相；它只声明 bridge profile、runtime shell 来源与薄桥层职责，不复制 mold / slot / ownership 事实。rules/legacy-host-hard-gates.json是 legacy 普通典型页硬门禁编排的唯一机器真相；SKILL.md、生成门禁说明和 planner 只引用它，不再各自手写门禁数量。- 基础项目事实（mode、capabilities、route ownership、i18n、governance availability）与基础资产事实（certified page component、mold、adapter catalog）应由计划内部消费并通过
facts、assetResolution、projectMode、targetPage.routeOwnership等字段暴露。 - 对已接入项目，接入阶段写入的
.local-context/hiui-design/outputs/project-integration-state.json属于 project 级 runtime input fact。PlanTask应优先复用它与project-mode.json， 直接进入页面规划；只有该状态缺失、损坏或与当前事实冲突时，才回退到 host profile / mode detection 诊断。 project-integration-state.json.integrationReady=true只有在接入阶段已经验证过 project-certified carriers 的componentSource、componentShell与componentSupportSources都能解析到真实项目源码时才成立；缺任一项时，接入必须保持integrationReady=false，页面生成阶段只允许暴露阻断原因，不得把缺失 carrier 问题延后到 业务页实现期才发现。- 对
legacy-host-compatible，integrationReady=true的定义本身就包含项目级 required rollout 已完成： 默认先覆盖table-basic、table-stat、tree-table、tree-split、drawer-form、drawer-detail、full-page-edit、full-page-detail这些carrier-first-required页型；feedback-status与data-visualization可作为 deferred batch 后补。缺少 required batch 的 project-certified carrier 时，integration state 必须显式输出requiredLegacyPageTypes、deferredLegacyPageTypes、certifiedLegacyPageTypes、missingRequiredLegacyPageTypes与legacyRolloutCoverageStatus=blocked，并把当前项目视为 legacy 接入未完成，而不是“已接入但页面阶段再补 rollout”。 integrationReady默认只回答“项目是否已完成 hiui-design 接入”和“legacy 宿主桥接是否已具备项目级承接事实”。对 legacy，这个完成态已经内含 required carrier batch ready；rules-only/host-integration下标准典型页组件是否可用，属于 planner 消费的资产事实与页型支持事实，不应被收口为通用项目接入失败。- project-scoped host pack / carrier facts 也属于 runtime input facts。对 legacy 项目，应优先 在项目接入 / capabilities 阶段一次认证，再由页面生成阶段复用，不要在每个页面重复解释宿主边界。
- Agent 只在 plan 缺失 / 冲突 / 排障 / 维护时显式读取 capabilities、mode lock、 认证文件或 catalog。
host-qualification-facts.v1只是 runtime input facts contract，不是 execution plan； 它只承载 legacy 宿主边界、bridge / adapter 事实与 provenance。typical-page:runtime-smoke只记录“当前源码快照上的浏览器级证据”，不负责宣告页面完成；preflight/doctor只把该证据与当前源码快照对齐并识别是否已过期； 只有typical-page:finalize-page可以把交付状态翻转为finalized。
Task Lifecycle
文档叙事层统一为：
LocateProjectRoot -> PlanTask -> ResolveBlockingFacts -> BuildGenerationRecipe -> GenerateByRecipe -> InlineConformanceChecks -> DeliveryConfirmation -> OutputDeliverySummary
PlanTask：默认先消费项目级 integration facts，再补 capabilities / route / asset-resolution；不要把“确认仓库结构 / 确认是否已接入 hiui-design”当成每次页面任务的可见前置步骤。planner 默认还要把生成期与交付期动作拆成generationInputs、inlineChecks、deliveryChecks，避免把重验收口径前移成生成指导。PlanTask输出层必须同时暴露targetDeliverySemantics与currentExecutionState：前者描述目标交付主链，后者描述当前允许动作、阻断相位与 blocker 优先级。requiredCommands、requiredActions与canStartImplementation必须跟currentExecutionState一致，不得再让 blocked 计划对外看起来像可以直接开始页面生成。PlanTask对 legacy 普通典型页的首要职责之一，是把 “禁止 legacy 主树 ad hoc 直挂 standard shell” 与 “允许 page-component + runtime bridge + slot fill 主链” 同时暴露清楚；不得把 direct shell import 不成立，回退表达成通用 page-component 不可用。- 若项目级 integration facts 已存在但
integrationReady=false，PlanTask必须 fail closed， 直接回显接入阻断原因；不要再尝试把页面生成、起手 scaffold 或页面级 preflight 当成接入 / legacy bridge 完整性的补救路径。页型级page-component资产是否 ready，继续由 planner 的assetResolution/projectTypicalPageSupport独立判断，而不是反写成通用 integration debt。 - 当
integrationReady=false的原因来自 legacy required rollout 未完成时，PlanTask默认应把bootstrap-target-project放在ResolveBlockingFacts队首；这表示当前项目的 legacy 接入 / bootstrap 还未完成，而不是“已接入项目在页面阶段追加一个 rollout 步骤”。若同时命中 route ownership blocker，再在其后追加 route 修复动作，不得跳过项目级 carrier rollout 直接进入页面实现。 BuildGenerationRecipe：把generationStrategy转化为标准装配协议。GenerateByRecipe：生成行为必须遵循assemblyOrder、requiredAssets、forbiddenMoves；不允许自由发明页壳、region owner、slot 顺序。InlineConformanceChecks：关键装配步骤后的轻量一致性检查，不把重验收前移。DeliveryConfirmation：末端确认层，内部继续承接WriteContract、Preflight、PreviewReady、FormalAcceptance、RuntimeGovernance。开源版不承担 usage telemetry / stats closeout，最终回复只收口页面交付与质量验证状态。- 这是叙事改名，不是立即的外部接口改名；公共脚本、报告对象和字段至少保留一个迁移周期 alias。
详细生命周期仍以 rules/page-task-lifecycle.md 为唯一真相。
First Turn Output
页面任务首轮回复默认优先展示生成信息，而不是先铺验收字段。默认优先字段：
generationStrategygenerationRecipegenerationInputsinlineChecksprimaryGenerationAssetassemblyOrderrequiredAssetsextensionPolicyrequiredActions
复杂或严格场景再展开：
deliveryChecksacceptanceLevelacceptanceProfilefinalReportContract
若命中 non-typical-overlay 或 single-page-composite，首轮还必须直接暴露 layoutStrategy、layoutArchetype、nonTypicalScope、mandatoryComponents、compositionGuardrails、strategyEvidence 与 ownershipPlan；这些属于生成输入事实，不是交付后才补的检查备注。
若命中不规范原型截图、旧系统截图 / URL / 源码，首轮按
docs/generation/ai-kickoff-template.md 输出 kickoffType=pre-plan-facts，只解释
visual-translation-brief.v1 与必要的 host-qualification-facts.v1 状态。
Truth Index
- 机器计划入口、成功信号和失败信号：
scripts/README.md - 快路径执行入口与补读顺序：
rules/QUICK-START.md - 公开 CLI 契约：
scripts/public-cli-contracts.json - 运行时协议：
rules/runtime-contract.md - 页面任务生命周期：
rules/page-task-lifecycle.md - 失败恢复矩阵：
rules/failure-matrix.md - 生成约束：
rules/generation-rules.md - 数据可视化主次/样式机器策略：
rules/chart-semantic-policy.json、rules/data-visualization-layout-policy.json - 页面组件与模具注册表：
rules/page-component-registry.json、rules/page-mold-registry.json - runtime bridge profiles：
rules/runtime-bridged-component-matrix.json - legacy hard gates：
rules/legacy-host-hard-gates.json - runtime 交付策略：
rules/runtime-delivery-policy.json - adapter 注册表：
rules/adapter-registry.json - contract 约束与摘要：
rules/contract-regions.md - 页面治理与 source snapshot / acceptance contract：
rules/page-governance.md - 验收清单：
rules/validation-checklist.md - 前向验证与成功指标：
docs/validation/generation-recipe-forward-tests.md - 页面组件策略与认证：
docs/generation/page-level-components.md、docs/generation/component-certification.md - explainers（解释层，不是 source of truth）：
docs/generation/explainers/README.md - 页头几何与宿主 baseline：
docs/generation/figma-reference.md - 旧宿主转译：
docs/generation/legacy-host-compatibility.md - 视觉 / 旧系统 pre-plan facts：
docs/generation/visual-to-hiui-translation.md - 非典型页面：
docs/generation/non-typical-pages.md - 图表与数据可视化：
docs/generation/figma-page-rules.md、docs/generation/figma-pages/data-visualization.md - usage stats：
PRIVACY.md
默认只读计划里的 requiredDocs；先消费 readMode=required，再按 reason 命中情况补读 reference / conditional 项。不要为选择模具或解释页型而整包遍历 docs/、rules/、templates/、manifests/。
Final Report
- 最终回复默认基于
deliverySummaryProfile输出轻量交付摘要。 - 复杂 / 高风险场景、严格验收、legacy 迁移、真非典型、复杂数据可视化、
preflight/ smoke 失败时，再进入finalReportContract/final-page-report.v1。 final-page-report.v1应优先复用 managed page contract / workflow 已有事实来判断页面是否已生成、是否 stale、是否曾完成 formal finalize；不要再要求上层重复手填同一组状态。- 最终报告默认阅读顺序是：页面如何生成 -> 使用了哪些主资产与槽位 -> 哪些区域继承 / 哪些区域业务填充 -> 当前交付确认状态。
- 状态字段必须完整保留，但不再占据主阅读中心。
- 若无法运行
typical-page:render-final-report，也必须呈现页面状态、preflight 状态、 formal 验收状态、usage stats 状态、已执行动作、变更文件、验证命令与剩余风险。