hiui-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HiUI 典型页 Skill

HiUI Typical Page 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”。

This skill is the standard generation protocol and delivery governance control plane for HiUI React page engineering.

page-task-plan.v1

remains the only top-level execution entry;

generationRecipe

is its internal forward generation sub-protocol; the final delivery state is still determined by

preflight-report.v1

hiui-page-governance-report.v1

acceptanceProfile

and

finalReportContract

. The core narrative is "Generate correctly according to the recipe first, then confirm via acceptance" rather than "Generate a version first, then correct via acceptance".

When standard typical pages hit

page-component + slot-fill

, they default to the

minimal-doc fast path

: prioritize consuming planner, scaffold and slot contract, instead of manually expanding lengthy governance documents; only complex pages, drifted pages and formal acceptance scenarios upgrade to the complete rule chain.

The main path for

legacy-host-compatible

is unified as

project-certified carrier first -> page-component semantics -> explicit fallback

. When the host undertaking fact is established, priority should be given to consuming project-certified carriers or certified page components, and

managed-translation

is only retained as an explicit fallback.

runtime-bridged-page-component

is just a bridged semantic naming of

page-component

in legacy, and does not introduce a parallel generation family; when hitting

header

, only carrier certification, page contract and preflight can jointly prove that the owner of

PageHeader

stretch,

extra

right-docked and

60px

rhythm does not drift, then the main chain is valid.

When communicating externally, two things should be explained separately: the legacy host main tree cannot be directly mounted as a generic

@hiui-design/typical-page-shells

at runtime, which does not mean that legacy projects cannot follow the normal typical page component main chain. As long as the planner has given

page-component + runtime bridge + slot fill

, it must be executed along this main chain, and the "cannot ad hoc direct shell import" should not be misread as "only 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
```
只作为 legacy
```
page-component
```
路径的附加解析对象存在；它通过
```
rules/runtime-bridged-component-matrix.json
```
描述运行时桥接策略，不重定义
```
pageComponent
```
、
```
baseMoldId
```
、
```
lockedRegions
```
或业务槽位事实。
project 级
```
host pack
```
、project-scoped
```
page 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

```
page-task-plan.v1
```
is the only execution plan and fact export; AI does not manually assemble
```
mode
```
,
```
pageType
```
,
```
pageUnits
```
,
```
startFrom
```
,
```
requiredDocs
```
,
```
requiredActions
```
or key command chains.
```
generationRecipe
```
is introduced as an incremental sub-object of
```
page-task-plan.v1
```
, and no parallel top-level contract is created separately.
```
generationRecipe
```
only describes assembly order, asset mapping, slot boundaries, forbidden actions and lightweight consistency checks; it does not repeatedly store facts that can be derived from
```
pageComponent
```
,
```
baseMoldId
```
, registry or existing contracts.
```
targetDeliverySemantics
```
and
```
currentExecutionState
```
must be output in layers: the former answers "Which managed delivery main chain should be followed after the plan is established", and the latter answers "What actions are allowed in this current step". When legacy is blocked, the former can still retain the target semantics of
```
page-component + runtime bridge + slot fill
```
, but the latter must only expose
```
ResolveBlockingFacts
```
.
```
editableSlots
```
,
```
lockedRegions
```
,
```
pageComponent
```
,
```
baseMoldId
```
prefer to remain "reference or derived", and are not copied into the planner.
```
runtimeBridgeProfile
```
only exists as an additional parsing object for the legacy
```
page-component
```
path; it describes the runtime bridging strategy through
```
rules/runtime-bridged-component-matrix.json
```
, and does not redefine
```
pageComponent
```
,
```
baseMoldId
```
,
```
lockedRegions
```
or business slot facts.
Project-level
```
host pack
```
, project-scoped
```
page carrier
```
and their certification results belong to runtime/asset facts, which are referenced by the plan through fields such as
```
facts
```
,
```
assetResolution
```
,
```
pageComponent
```
by default; do not flatten and copy these facts into each page contract again.
Carrier-critical layout facts, especially the stretch owner, actions docking and vertical rhythm owner of
```
header
```
, are machine facts jointly consumed by contract + certification + preflight; they must not degenerate into soft suggestions that only exist in documentation.

acceptanceProfile

preflight-report.v1

hiui-page-governance-report.v1

finalReportContract

are retained without degradation or removal.

```
requiredDocs
```
is the default only supplementary reading source; its minimum structure is fixed as
```
path
```
,
```
readMode
```
,
```
reason
```
. Read
```
readMode=required
```
first, and
```
reference
```
/
```
conditional
```
are only supplemented when the corresponding scenario is hit.
```
requiredActions
```
is the default only execution source; when there are no structured actions, priority is given to using compatible command fields instead of expanding gates by yourself.

Object model and field classification:

docs/generation/explainers/core-object-model.md

Standard Generation Protocol

Standard Generation Protocol

只回答 4 个问题：

从什么骨架起步。
关键 region 的装配顺序是什么。
哪些区域允许业务填充。
每完成一个关键步骤后做什么
```
inlineChecks
```
。

generationRecipe.required

默认至少包含：

```
startingPoint
```
```
assemblyOrder
```
```
requiredAssets
```
```
forbiddenMoves
```

generationRecipe.optional

可按页型与复杂度逐步补齐：

```
slotFillPolicy
```
```
regionOwnership
```
```
inlineChecks
```

第一批 recipe 只覆盖高频页型：

```
table-page
```
```
analytics-page
```
```
edit/detail-page
```

标准生成协议补读：

docs/generation/explainers/standard-generation-protocol.md

Standard Generation Protocol

only answers 4 questions:

What skeleton to start from.
What is the assembly order of key regions.
Which regions allow business filling.
What
```
inlineChecks
```
to perform after completing each key step.

generationRecipe.required

contains at least by default:

```
startingPoint
```
```
assemblyOrder
```
```
requiredAssets
```
```
forbiddenMoves
```

generationRecipe.optional

can be supplemented step by step according to page type and complexity:

```
slotFillPolicy
```
```
regionOwnership
```
```
inlineChecks
```

The first batch of recipes only covers high-frequency page types:

```
table-page
```
```
analytics-page
```
```
edit/detail-page
```

Supplementary reading for standard generation protocol:

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 边界；缺任一条件时必须拒绝执行。
```
preflight
```
failed、hard profile governance failed、source snapshot 缺失 / 低置信度、
```
acceptance contract
```
缺 provenance 时，最终回复必须是 blocked / failed。
开源版不得采集 usage data，必须按
```
PRIVACY.md
```
呈现
```
not_applicable
```
、
```
skipped
```
或
```
unavailable
```
。

This skill only handles HiUI React page engineering tasks; requirement refinement, end-to-end process orchestration, Figma writing/design draft generation, and general React refactoring must be handed over to the corresponding skill or ordinary code process.
Page generation, rewriting, major modification, page type migration and old system/screenshot translation must first obtain
```
page-task-plan.v1
```
; without a machine plan, conclusions, command chains or final states cannot be manually assembled.
When
```
blockingIssues
```
/
```
blockingReasons
```
are not empty, it must fail closed and only supplement facts; page generation, contract writing, preflight running or final state output are not allowed.
Asset addition, supplementation and update can only be done through shipped public contracts;
```
add-asset
```
/
```
update-asset
```
must be dry-run, and unshipped write / force / asset type cannot be executed.
Without explicit authorization from the machine plan or explicit requirements from maintainers, deploy, upload, publish, sync, global sync, Feishu / bitable background writing, release archive generation or historical output coverage cannot be executed.
For actions involving external services, background agents, launch agents, daemons or user configuration writing, the target scope, authorization source and side effect boundary must be verified simultaneously before execution; if any condition is missing, execution must be refused.
When
```
preflight
```
fails, hard profile governance fails, source snapshot is missing/low confidence, or
```
acceptance contract
```
lacks provenance, the final response must be blocked / failed.
The open-source version must not collect usage data, and must present
```
not_applicable
```
,
```
skipped
```
or
```
unavailable
```
in accordance with
```
PRIVACY.md
```
.

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-component
```
ready 且
```
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

Pre-generation gates: project root, machine plan, capability profile, mode lock, pre-plan facts.
Generation protocol gates: page-component availability, route ownership, slot boundaries, shell / adapter proof, analytics contract, business content boundaries, controlled extension.
The hard gate truths of
```
legacy-host-compatible
```
ordinary typical pages are unified in
```
rules/legacy-host-hard-gates.json
```
: the baseline is fixed as 4 hard gates, and when hitting
```
header
```
, the conditional gate of
```
header-layout-proof
```
is added, so currently common typical pages usually fall into 5 effective hard gates.
```
styleBoundary
```
,
```
portalBoundary
```
,
```
runtimeSmoke
```
are still triggered according to risks; but the stretch / right-dock / rhythm owner of
```
header
```
is no longer just a style suggestion, and the main chain must be blocked when structured proof is missing.
Under
```
legacy-host-compatible
```
, if the planner has proven that
```
page-component
```
is ready and
```
runtimeAdapterProof.status=available
```
, the default execution semantics is
```
page-component + runtime bridge + slot fill
```
. The lack of the premise of legacy main tree direct shell import can only prevent ad hoc standard-shell mount, and cannot be used as a reason to unilaterally degrade to compatible manually assembled pages, reference default translation pages or free fallback.
The first two layers of gates are part of "how to generate correctly", and are no longer mixed with delivery blocking tone.
When
```
required
```
level
```
generationRecipe
```
fields are missing, assumptions or manual supplementation are not allowed; it can only be blocked, or executed according to the fallback explicitly given by the plan.
When
```
startingPoint
```
cannot be parsed,
```
requiredAssets
```
are unavailable, or
```
assemblyOrder
```
is incomplete, free fallback to blank page handwriting is not allowed.
Only when the plan explicitly gives
```
managed-fallback
```
,
```
host-archetype
```
or
```
reference-or-scaffold
```
as legal fallbacks, downgraded generation is allowed.
Missing
```
optional
```
fields do not automatically block, but forgery and filling are not allowed; when missing, execute according to the default strategy of the page type or existing rules.

Details of generation gates:

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

```
preflight-report.v1
```
and
```
hiui-page-governance-report.v1
```
remain the core judgment objects of the delivery confirmation layer.
```
acceptanceProfile
```
determines the acceptance scope;
```
formal acceptance
```
is the acceptance level, not the generation chain.
```
finalReportContract
```
is retained for complete reports and downstream compatibility.
Delivery gates are only responsible for "whether to allow declaring completion", and no longer dominate the generation narrative.
If a certain type of problem is exposed continuously in the
```
DeliveryConfirmation
```
stage, it must be prioritized to be fed back to
```
generationRecipe
```
or generation gates, instead of continuously adding new acceptance descriptions.

Details of delivery gates:

docs/generation/explainers/delivery-gates.md

Runtime Protocol

运行时协议的唯一真相是
```
rules/runtime-contract.md
```
；受管页面治理协议的唯一真相是
```
rules/page-governance.md
```
。
```
rules/runtime-bridged-component-matrix.json
```
是 legacy
```
page-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
```
。

The only truth of the runtime protocol is
```
rules/runtime-contract.md
```
; the only truth of the managed page governance protocol is
```
rules/page-governance.md
```
.
```
rules/runtime-bridged-component-matrix.json
```
is the only truth of the legacy
```
page-component
```
bridging semantics; it only declares bridge profile, runtime shell source and thin bridge layer responsibilities, and does not copy mold / slot / ownership facts.
```
rules/legacy-host-hard-gates.json
```
is the only machine truth of the hard gate orchestration for legacy ordinary typical pages;
```
SKILL.md
```
, generation gate descriptions and planners only reference it, and no longer write the number of gates separately.
Basic project facts (mode, capabilities, route ownership, i18n, governance availability) and basic asset facts (certified page component, mold, adapter catalog) should be consumed internally by the plan and exposed through fields such as
```
facts
```
,
```
assetResolution
```
,
```
projectMode
```
,
```
targetPage.routeOwnership
```
.
For connected projects,
```
.local-context/hiui-design/outputs/project-integration-state.json
```
written during the connection phase belongs to the project-level runtime input fact.
```
PlanTask
```
should prioritize reusing it and
```
project-mode.json
```
to directly enter page planning; only when this state is missing, damaged or conflicts with current facts, it falls back to host profile / mode detection diagnosis.
```
project-integration-state.json.integrationReady=true
```
is only established when
```
componentSource
```
,
```
componentShell
```
and
```
componentSupportSources
```
of project-certified carriers have been verified to be resolved to real project source code during the connection phase; if any item is missing, the connection must remain
```
integrationReady=false
```
, and only blocking reasons can be exposed during page generation phase, and the missing carrier problem must not be delayed until the business page implementation phase to be discovered.
For
```
legacy-host-compatible
```
, the definition of
```
integrationReady=true
```
itself includes the completion of project-level required rollout: it defaults to covering
```
table-basic
```
,
```
table-stat
```
,
```
tree-table
```
,
```
tree-split
```
,
```
drawer-form
```
,
```
drawer-detail
```
,
```
full-page-edit
```
,
```
full-page-detail
```
these
```
carrier-first-required
```
page types;
```
feedback-status
```
and
```
data-visualization
```
can be supplemented later as deferred batch. When project-certified carriers of required batch are missing, the integration state must explicitly output
```
requiredLegacyPageTypes
```
,
```
deferredLegacyPageTypes
```
,
```
certifiedLegacyPageTypes
```
,
```
missingRequiredLegacyPageTypes
```
and
```
legacyRolloutCoverageStatus=blocked
```
, and regard the current project as incomplete legacy connection, rather than "connected but supplement rollout in page phase".
```
integrationReady
```
only answers "whether the project has completed hiui-design connection" and "whether legacy host bridging has project-level undertaking facts" by default. For legacy, this final state already includes required carrier batch ready; whether standard typical page components are available under
```
rules-only
```
/
```
host-integration
```
belongs to asset facts and page type support facts consumed by the planner, and should not be closed as a general project connection failure.
Project-scoped host pack / carrier facts also belong to runtime input facts. For legacy projects, they should be certified once in the project connection / capabilities phase first, then reused in the page generation phase, instead of repeatedly explaining host boundaries in each page.
Agent only explicitly reads capabilities, mode lock, certification files or catalog when the plan is missing / conflicting / troubleshooting / maintaining.
```
host-qualification-facts.v1
```
is only a runtime input facts contract, not an execution plan; it only carries legacy host boundaries, bridge / adapter facts and provenance.
```
typical-page:runtime-smoke
```
only records "browser-level evidence on the current source code snapshot", and is not responsible for declaring page completion;
```
preflight
```
/
```
doctor
```
only aligns this evidence with the current source code snapshot and identifies whether it has expired; only
```
typical-page:finalize-page
```
can flip the delivery state to
```
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

为唯一真相。

The document narrative layer is unified as:

LocateProjectRoot -> PlanTask -> ResolveBlockingFacts -> BuildGenerationRecipe -> GenerateByRecipe -> InlineConformanceChecks -> DeliveryConfirmation -> OutputDeliverySummary

```
PlanTask
```
: By default, first consume project-level integration facts, then supplement capabilities / route / asset-resolution; do not treat "confirming warehouse structure / confirming whether hiui-design has been connected" as a visible pre-step for each page task. The planner also defaults to splitting generation and delivery actions into
```
generationInputs
```
,
```
inlineChecks
```
,
```
deliveryChecks
```
to avoid moving heavy acceptance caliber forward as generation guidance.
The output layer of
```
PlanTask
```
must expose both
```
targetDeliverySemantics
```
and
```
currentExecutionState
```
: the former describes the target delivery main chain, and the latter describes currently allowed actions, blocking phase and blocker priority.
```
requiredCommands
```
,
```
requiredActions
```
and
```
canStartImplementation
```
must be consistent with
```
currentExecutionState
```
, and blocked plans must not appear to be directly startable for page generation.
One of the primary responsibilities of
```
PlanTask
```
for legacy ordinary typical pages is to clearly expose both "forbid legacy main tree ad hoc direct mount of standard shell" and "allow page-component + runtime bridge + slot fill main chain"; the failure of direct shell import must not be regressively expressed as general page-component unavailable.
If project-level integration facts exist but
```
integrationReady=false
```
,
```
PlanTask
```
must fail closed and directly display the connection blocking reason; do not attempt to use page generation, initial scaffold or page-level preflight as a remedy for connection / legacy bridge integrity. Whether page-type
```
page-component
```
assets are ready is still independently judged by the planner's
```
assetResolution
```
/
```
projectTypicalPageSupport
```
, rather than being rewritten as general integration debt.
When the reason for
```
integrationReady=false
```
comes from incomplete legacy required rollout,
```
PlanTask
```
should default to placing
```
bootstrap-target-project
```
at the top of
```
ResolveBlockingFacts
```
; this indicates that the legacy connection / bootstrap of the current project has not been completed, rather than "adding a rollout step in the page phase for a connected project". If route ownership blocker is hit at the same time, add route repair action after it, and do not skip project-level carrier rollout directly into page implementation.
```
BuildGenerationRecipe
```
: Convert
```
generationStrategy
```
into a standard assembly protocol.
```
GenerateByRecipe
```
: Generation behavior must follow
```
assemblyOrder
```
,
```
requiredAssets
```
,
```
forbiddenMoves
```
; free invention of page shells, region owners, slot orders is not allowed.
```
InlineConformanceChecks
```
: Lightweight consistency checks after key assembly steps, without moving heavy acceptance forward.
```
DeliveryConfirmation
```
: End confirmation layer, which internally continues to undertake
```
WriteContract
```
,
```
Preflight
```
,
```
PreviewReady
```
,
```
FormalAcceptance
```
,
```
RuntimeGovernance
```
. The open-source version does not undertake usage telemetry / stats closeout, and the final response only focuses on page delivery and quality verification status.
This is a narrative rename, not an immediate external interface rename; public scripts, report objects and fields retain at least one migration cycle alias.

Detailed lifecycle still takes

rules/page-task-lifecycle.md

as the only truth.

First Turn Output

页面任务首轮回复默认优先展示生成信息，而不是先铺验收字段。默认优先字段：

```
generationStrategy
```
```
generationRecipe
```
```
generationInputs
```
```
inlineChecks
```
```
primaryGenerationAsset
```
```
assemblyOrder
```
```
requiredAssets
```
```
extensionPolicy
```
```
requiredActions
```

复杂或严格场景再展开：

```
deliveryChecks
```
```
acceptanceLevel
```
```
acceptanceProfile
```
```
finalReportContract
```

若命中

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

状态。

The first-round response of page tasks prioritizes displaying generation information by default, rather than laying out acceptance fields first. Default priority fields:

```
generationStrategy
```
```
generationRecipe
```
```
generationInputs
```
```
inlineChecks
```
```
primaryGenerationAsset
```
```
assemblyOrder
```
```
requiredAssets
```
```
extensionPolicy
```
```
requiredActions
```

Expand in complex or strict scenarios:

```
deliveryChecks
```
```
acceptanceLevel
```
```
acceptanceProfile
```
```
finalReportContract
```

non-typical-overlay

single-page-composite

is hit, the first round must also directly expose

layoutStrategy

layoutArchetype

nonTypicalScope

mandatoryComponents

compositionGuardrails

strategyEvidence

and

ownershipPlan

; these belong to generation input facts, not inspection notes supplemented after delivery.

If unstandard prototype screenshots, old system screenshots / URLs / source code are hit, output

kickoffType=pre-plan-facts

in the first round according to

docs/generation/ai-kickoff-template.md

, and only explain the status of

visual-translation-brief.v1

and necessary

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/

。

Machine plan entry, success signals and failure signals:
```
scripts/README.md
```
Fast path execution entry and supplementary reading order:
```
rules/QUICK-START.md
```
Public CLI contracts:
```
scripts/public-cli-contracts.json
```
Runtime protocol:
```
rules/runtime-contract.md
```
Page task lifecycle:
```
rules/page-task-lifecycle.md
```
Failure recovery matrix:
```
rules/failure-matrix.md
```
Generation constraints:
```
rules/generation-rules.md
```

Machine strategies for data visualization priority/style:

rules/chart-semantic-policy.json

rules/data-visualization-layout-policy.json

Page component and mold registry:

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 delivery strategy:
```
rules/runtime-delivery-policy.json
```
Adapter registry:
```
rules/adapter-registry.json
```
Contract constraints and summary:
```
rules/contract-regions.md
```
Page governance and source snapshot / acceptance contract:
```
rules/page-governance.md
```
Acceptance checklist:
```
rules/validation-checklist.md
```

Forward validation and success metrics:

docs/validation/generation-recipe-forward-tests.md

Page component strategy and certification:

docs/generation/page-level-components.md

docs/generation/component-certification.md

Explainers (explanation layer, not source of truth):
```
docs/generation/explainers/README.md
```
Header geometry and host baseline:
```
docs/generation/figma-reference.md
```

Old host translation:

docs/generation/legacy-host-compatibility.md

Visual / old system pre-plan facts:

docs/generation/visual-to-hiui-translation.md

Atypical pages:
```
docs/generation/non-typical-pages.md
```

Charts and data visualization:

docs/generation/figma-page-rules.md

docs/generation/figma-pages/data-visualization.md

Usage stats:
```
PRIVACY.md
```

By default, only read

requiredDocs

in the plan; consume

readMode=required

first, then supplement

reference

conditional

items according to the hit situation of

reason

. Do not traverse

docs/

rules/

templates/

manifests/

as a whole to select molds or explain page types.

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 状态、已执行动作、变更文件、验证命令与剩余风险。

The final response outputs a lightweight delivery summary based on
```
deliverySummaryProfile
```
by default.
Enter
```
finalReportContract
```
/
```
final-page-report.v1
```
only in complex / high-risk scenarios, strict acceptance, legacy migration, true atypical, complex data visualization,
```
preflight
```
/ smoke failure situations.
```
final-page-report.v1
```
should prioritize reusing existing facts of managed page contract / workflow to judge whether the page has been generated, whether it is stale, and whether it has completed formal finalize; do not require the upper layer to repeatedly fill in the same set of states manually.
The default reading order of the final report is: How the page is generated -> Which main assets and slots are used -> Which regions are inherited / which regions are filled by business -> Current delivery confirmation status.
Status fields must be completely retained, but no longer occupy the main reading center.
If
```
typical-page:render-final-report
```
cannot be run, the page status, preflight status, formal acceptance status, usage stats status, executed actions, changed files, verification commands and remaining risks must still be presented.