@c4a/context-cli 0.7.5 → 0.7.9

package/indexers/bundles/context-note-indexer/templates/articles/c02.md

@@ -0,0 +1,34 @@
+---
+id: context.article.c02
+kind: procedure
+media-type: text/markdown
+program:
+  article: c02
+  policies:
+    - standard
+  sections:
+    goals: 业务目标
+    actors: 角色与场景
+    prerequisites: 使用前提
+    operations: 操作与结果
+    exceptions: 规则与异常
+    acceptance: 验收依据
+    version: 版本和范围
+    capabilities: 能力边界
+    flows: 主要流程入口
+    references: 相关系统与文档
+---
+
+# C02 业务概览
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+适用：有业务说明、真实页面或用例能够支持业务定位时。建议章节为 **业务目标 → 角色与场景 → 能力边界 → 主要流程入口 → 相关系统与文档**。每个场景至少给角色、触发动作和代码／资料定位；业务指标与历史原因只在权威资料支持时增加。
+
+与 C01 区别：C01 帮读者找资料，C02 解释业务。内容过少时合并到 C01；不根据目录名虚构经营目标或业务指标。
+
+**纯产品与功能说明变体**：只有产品文档时也可独立采用。产品总览使用 **目标与适用对象 → 场景与角色 → 功能地图 → 使用与规则入口 → 版本和范围**；功能详情使用 **用户任务 → 前置条件 → 操作与结果 → 规则和异常 → 验收依据 → 相关资料**。需求中的预期、已发布行为和用户观察分别标明，不把需求文档直接当作线上已实现。详细操作可由已有用户指南承载，验收资料关联 Q03/Q04；不强制出现源码、API 或部署章节。
+
+## 图示选择
+
+在业务流程或操作章节用 flowchart TD；产品方案与已发布行为分别标注。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/c03.md

@@ -0,0 +1,26 @@
+---
+id: context.article.c03
+kind: procedure
+media-type: text/markdown
+program:
+  article: c03
+  policies:
+    - standard
+  sections:
+    scope: 适用范围
+    terms: 术语表
+    distinctions: 易混概念
+    references: 相关入口
+---
+
+# C03 术语与标识
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+适用：中文业务名、产品名、路由、API、领域类型之间存在定位需求。建议章节为 **适用范围 → 术语表 → 易混概念 → 相关入口**。
+
+表格列：读者用语、代码／协议标识、含义、适用范围、来源与相关页。同义词必须来自材料或真实问题；不把同名字段视为同一业务概念。短表并入模块概览，跨模块通用词仅维护一份。
+
+## 图示选择
+
+术语优先表格；有明确概念关系才补带关系标签的 flowchart，不凭同名连线。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/c04.md

@@ -0,0 +1,27 @@
+---
+id: context.article.c04
+kind: procedure
+media-type: text/markdown
+program:
+  article: c04
+  policies:
+    - standard
+  sections:
+    layers: 依赖分层
+    catalog: 核心依赖表
+    initialization: 初始化与注入
+    compatibility: 兼容和版本约束
+    boundaries: 跨边界定位
+---
+
+# C04 依赖与协作边界
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+适用：依赖影响模块运行、改动、问题归属时。建议章节为 **依赖分层 → 核心依赖表 → 初始化与注入 → 兼容和版本约束 → 跨边界定位**。
+
+表格列：依赖身份、用途、使用位置、版本／来源、静态导入或运行时加载、继续查阅入口。前端包依赖、后端运行时调用分别使用自己的证据；锁文件证明版本，调用点才证明使用。全部依赖清单不直接变成读者正文。
+
+## 图示选择
+
+依赖章节用 flowchart LR，分别标注导入、调用、注入，不混同运行关系。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/c05.md

@@ -0,0 +1,28 @@
+---
+id: context.article.c05
+kind: procedure
+media-type: text/markdown
+program:
+  article: c05
+  policies:
+    - standard
+  sections:
+    symptoms: 现象索引
+    conditions: 适用条件
+    findings: 已知事实与判断
+    diagnosis: 排查步骤
+    recovery: 修复与验证
+    sources: 来源
+---
+
+# C05 已知问题与排障
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+适用：存在已核实缺陷、受限能力、历史事件或具体可复现现象。建议章节为 **现象索引 → 适用条件 → 已知事实与判断 → 排查步骤 → 修复／绕行及验证 → 来源**。
+
+记录列：现象、版本／环境、定位点、结论状态、下一步。TODO/FIXME 只能作为维护线索，不自动认定线上故障；已修问题标明适用历史版本。没有可信条目时不生成空的 known-issues 页。
+
+## 图示选择
+
+诊断步骤可用 flowchart TD，保留失败出口与下一步；不要画未经证实的根因链。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/c06.md

@@ -0,0 +1,28 @@
+---
+id: context.article.c06
+kind: procedure
+media-type: text/markdown
+program:
+  article: c06
+  policies:
+    - standard
+  sections:
+    context: 背景与问题
+    decision: 结论与状态
+    alternatives: 选项与取舍
+    impact: 影响范围
+    followup: 后续行动
+    sources: 来源与版本
+---
+
+# C06 补充说明与决策
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+适用：有被保存的业务说明、约定、讨论结论或事件复盘。建议章节为 **背景和问题 → 已确认说明／决定 → 依据与适用范围 → 对现有能力的影响 → 关联代码和文档**。
+
+沿用 Note／Sessions 的引用、观察、推测和纠正区分。能融入现有主题时优先更新对应章节；只有独立阅读价值才保留单篇。不会为每个模块预生成 supplements.md 或复制相同空框架。
+
+## 图示选择
+
+决策或历史过程可用 flowchart，标明采纳状态、时点和来源；短决定使用文字。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/c07.md

@@ -0,0 +1,27 @@
+---
+id: context.article.c07
+kind: procedure
+media-type: text/markdown
+program:
+  article: c07
+  policies:
+    - standard
+  sections:
+    entries: 问题到入口
+    identity: 源码身份与版本
+    reading: 推荐阅读顺序
+    boundaries: 外部边界
+    evidence: 进一步证据
+---
+
+# C07 从知识继续查源码
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+适用：入口优先的业务知识包，尤其是只持有 dist 的消费 Agent。建议章节为 **问题到入口的映射 → 源码身份与版本 → 推荐阅读顺序 → 外部边界 → 何时需要进一步证据**。
+
+定位记录：仓库身份、仓内路径／符号、证据版本、已证明到哪一层、接着读什么。在包内返回可执行的阅读指引；工作区 inspect 与包外源码归因遵循各自现有能力和授权，不声称普通 dist query 会自动 clone。无需在每篇文章重复整套工作流，只保留本篇起点和相关指引链接。
+
+## 图示选择
+
+源码坐标优先表格，阅读顺序可用 text 树；跨边界路径有证据再画 flowchart，并写下一步。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/d01.md

@@ -0,0 +1,29 @@
+---
+id: context.article.d01
+kind: procedure
+media-type: text/markdown
+program:
+  article: d01
+  policies:
+    - standard
+  sections:
+    scope: 领域职责
+    services: 服务分工
+    entries: 入口与调用边界
+    collaboration: 数据与事件协作
+    references: 阅读导航
+---
+
+# D01 领域架构与服务地图
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：多个已登记服务存在共同业务主题或明确协作关系。
+
+建议章节：**领域职责 → 服务分工 → 入口与调用边界 → 主要数据／事件协作 → 阅读导航**。
+
+服务表列：服务名／运行身份、仓库模块、职责依据、入口、下游边界、详细文章。图区分有证据的调用与仅共属某领域的节点；同组摆放不等于调用关系。未深化服务可直接保留可用源码入口。
+
+## 图示选择
+
+服务地图用 flowchart LR，分组只表示归属，调用必须另有带标签的边及来源。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/d02.md

@@ -0,0 +1,30 @@
+---
+id: context.article.d02
+kind: procedure
+media-type: text/markdown
+program:
+  article: d02
+  policies:
+    - standard
+  sections:
+    trigger: 场景与触发
+    actors: 参与方
+    flow: 主流程
+    branches: 分支与状态
+    failures: 失败和下一步
+    sources: 源码链路与证据边界
+---
+
+# D02 业务流程与跨层链路
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：有具体业务动作且相关来源已登记。适用于后端跨服务流程，也可跨前后端组织。
+
+建议章节：**场景与触发 → 参与方 → 主流程 → 关键分支与状态 → 失败和下一步 → 源码链路与证据边界**。
+
+步骤表列：动作、实现位置、输入／输出、下游、终止或继续条件。sequence／flow 图只绘制已证明的边；对授权范围外的服务终止在具名边界并提供入口。入口优先版本可仅写已有首跳，深度闭环作为后续增强。
+
+## 图示选择
+
+业务主流程用 flowchart TD，跨层交互用 sequenceDiagram；两图承担不同问题，避免重复。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/d03.md

@@ -0,0 +1,30 @@
+---
+id: context.article.d03
+kind: procedure
+media-type: text/markdown
+program:
+  article: d03
+  policies:
+    - standard
+  sections:
+    scope: 业务与版本
+    catalog: 规则分类
+    conditions: 条件与结果
+    implementation: 执行位置
+    conflicts: 例外与冲突
+    references: 相关流程
+---
+
+# D03 业务规则
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：存在规则文档、条件判断、校验、枚举含义或领域不变量。
+
+建议章节：**适用业务与版本 → 规则分类 → 条件与结果 → 执行位置 → 例外与冲突 → 相关流程**。
+
+规则表列：规则名、作用对象、前提、允许／禁止或计算结果、代码／文档来源。区分客户端提示、网关校验、领域强制规则；以名字相同判断实现一致不可接受。代码推导规则标明证据，不解释无材料支持的商业原因。
+
+## 图示选择
+
+条件规则可用 flowchart TD；精确规则与例外保留表格，未知分支明确说明。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/d04.md

@@ -0,0 +1,36 @@
+---
+id: context.article.d04
+kind: procedure
+media-type: text/markdown
+program:
+  article: d04
+  policies:
+    - standard
+  sections:
+    scope: 工程边界
+    commands: 构建与测试入口
+    delivery: 环境与交付
+    conventions: 兼容与研发约定
+    environment: 运行与环境
+    configuration: 配置定位
+    observability: 日志指标与追踪
+    diagnosis: 诊断路径
+    recovery: 恢复与回滚
+    verification: 验证依据
+---
+
+# D04 运维与排障入口
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：有维护脚本、配置、指标注册或已保存的 SOP／事件记录。
+
+建议章节：**运行与环境 → 配置定位 → 日志／指标／追踪 → 常见现象与诊断路径 → 恢复／回滚 → 验证依据**。
+
+表格列：问题／配置类别、代码使用点、查询入口、适用环境、下一步。平台标识不等于当前配置值，存在监控调用不等于告警已配置。读取脚本可以产生文档，不代表获得执行线上操作的授权。
+
+**工程基础设施／研发规范变体**：承接技术基础设施、研发规范和后端构建部署资料。章节为 **工程边界 → 构建与测试入口 → 环境和交付 → 兼容与研发约定 → 排障定位**。有独立维护资料且内容足够时单独成篇；否则并入服务运行说明。操作事实、团队规范和 Agent 建议分清来源，不遗漏后端工程知识，也不复制前端命令。
+
+## 图示选择
+
+工程交付或故障诊断用 flowchart TD；部署依赖图仅在有实际配置依据时采用。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/f01.md

@@ -0,0 +1,30 @@
+---
+id: context.article.f01
+kind: procedure
+media-type: text/markdown
+program:
+  article: f01
+  policies:
+    - standard
+  sections:
+    architecture: 架构总览
+    stack: 技术栈与运行方式
+    startup: 启动与分层
+    crosscutting: 关键横切能力
+    deployment: 部署边界
+    references: 相关入口
+---
+
+# F01 架构
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：已定位启动入口与关键运行边界。
+
+建议章节：**架构总览 → 技术栈与运行方式 → 启动与分层 → 关键横切能力 → 部署边界 → 相关入口**。
+
+内容：启动／挂载文件、宿主与子应用职责、路由／状态／请求层的连接、跨层引用。架构图的每条边须有配置、调用或文档依据；历史设计原因需决策材料，不能从当前实现推断。远程模块身份不等于宿主身份。
+
+## 图示选择
+
+架构章节用 flowchart LR，按启动、宿主和请求层分组，每条边有来源。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/f06.md

@@ -0,0 +1,30 @@
+---
+id: context.article.f06
+kind: procedure
+media-type: text/markdown
+program:
+  article: f06
+  policies:
+    - standard
+  sections:
+    scope: 模型范围
+    catalog: 类型目录
+    roles: DTO 与视图模型
+    mapping: 转换与校验
+    authority: 权威与生成关系
+    references: 使用与源码
+---
+
+# F06 类型模型
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：DTO、请求／响应、View Model 或生成类型的映射对理解应用有价值。
+
+建议章节：**类型来源与生成边界 → 核心类型 → 页面与 API 类型链路 → 转换及兼容约束 → 修改入口**。
+
+表格列：类型名、类别、关键字段语义、使用位置、权威来源；链路表列页面／能力、View Model、Request、Response、转换函数。仅保留稳定且被使用的类型；完整声明仍留源码或契约引用，不恢复长段 Source type declaration。
+
+## 图示选择
+
+类型目录优先表格；转换关系用 flowchart，不把 DTO 直接画成数据库实体。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/f08.md

@@ -0,0 +1,34 @@
+---
+id: context.article.f08
+kind: procedure
+media-type: text/markdown
+program:
+  article: f08
+  policies:
+    - standard
+  sections:
+    systems: 使用的组件库与设计系统
+    layers: 样式分层
+    tokens: Token 定义与消费
+    overrides: 局部覆盖
+    platforms: 主题与平台差异
+    accessibility: 响应式与可访问性
+    examples: 调整入口与示例
+    references: 系统规范与源码
+---
+
+# F08 样式与设计系统
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：存在影响页面开发的主题、token、样式覆盖或组件库接入规则。
+
+建议章节：**使用的组件库与设计系统 → 样式组织 → Token 与主题 → 覆盖顺序和隔离 → 响应式／可访问性 → 调整入口与示例**。
+
+保留 token 身份、定义／消费位置、配置与维护示例。响应式断点、无障碍保证和颜色语义需代码／规范支持。设计稿与代码不一致时标明版本，不从截图猜 Props 或 token。
+
+本篇负责应用如何消费和覆盖；系统自身的规范、基础资源和跨平台映射归 L03 独立设计系统模板。一组 CSS 变量不足以证明存在完整设计系统；没有系统资料时仍可写真实样式入口。
+
+## 图示选择
+
+token 定义/覆盖可用 flowchart；实际颜色或响应式外观使用授权来源图，代码不证明视觉效果。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/f09.md

@@ -0,0 +1,30 @@
+---
+id: context.article.f09
+kind: procedure
+media-type: text/markdown
+program:
+  article: f09
+  policies:
+    - standard
+  sections:
+    scope: 工程与交付边界
+    prerequisites: 运行前提
+    commands: 构建与测试入口
+    deployment: 部署与配置
+    verification: 验证与回滚
+    references: 相关资料
+---
+
+# F09 构建与部署
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+生成条件：有项目拥有的脚本、工程配置或交付文档。
+
+建议章节：**开发前提 → 本地启动与调试 → 构建入口及产物 → 环境选择 → 发布与回滚入口 → 常见定位点**。
+
+命令来自 scripts／维护文档；说明包与执行目录、配置生效位置、产物身份。已存在发布脚本不等于线上已部署；仓库证据不足的真实平台值不补写。公共工程规则由一篇父级指南承载，子应用只写差异。
+
+## 图示选择
+
+构建交付顺序用 flowchart；命令和前提保留文字，步骤计划不代表执行回执。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/l01.md

@@ -0,0 +1,35 @@
+---
+id: context.article.l01
+kind: procedure
+media-type: text/markdown
+program:
+  article: l01
+  policies:
+    - standard
+  sections:
+    purpose: 用途与适用范围
+    installation: 安装与初始化
+    capabilities: 主要能力
+    usage: 典型用法
+    contracts: 契约与扩展点
+    limits: 限制与兼容
+    references: 源码与验证入口
+---
+
+# L01 公共能力与使用指南
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+建议章节：**用途和适用场景 → 支持的导入／命令 → 初始化及前提 → 能力分组 → 维护示例 → 兼容与修改入口**。
+
+能力表列：能力身份、入口、使用方、对应契约和示例。SDK 初始化、CLI 参数与插件注册各用已有专门模板；不复制源码中所有 export。可补分层架构、provider／middleware 和维护约定，但必须服务具体读者任务。
+
+## 公共组件与设计系统的专用标准
+
+L02 公共组件 已独立细化建议章节、家族、Props／事件／方法／Ref、示例与行为变体。非 UI 的公共 API 仍沿用对应 SDK／CLI 程序模板与 L01 的消费原则，不强套 UI 的样式／焦点章节。
+
+L03 设计系统 独立覆盖系统入口、基础规范、主题接入和平台版本关系，避免缩成组件库的一小段颜色说明。
+
+## 图示选择
+
+接入调用有顺序要求时用 sequenceDiagram；命令/签名用表格，模块层次用 text 树。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。

package/indexers/bundles/context-note-indexer/templates/articles/l02.md

@@ -0,0 +1,101 @@
+---
+id: context.article.l02
+kind: procedure
+media-type: text/markdown
+program:
+  article: l02
+  policies:
+    - standard
+  sections:
+    purpose: 用途与选用
+    setup: 接入与基本用法
+    scenarios: 场景与变体
+    api: API 与公开契约
+    behavior: 行为与组合规则
+    styles: 样式与设计系统
+    limits: 环境可访问性与限制
+    references: 相关组件与源码入口
+---
+
+# L02 公共组件与组件家族
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+### 身份与拆页条件
+
+先确认包／公开入口、组件名、平台、适用版本、稳定或弃用状态。仓内共享组件如果有明确跨模块消费契约，即使未发布 npm，也可按公共组件处理；单纯 export、放在 components/ 或出现在演示站不构成公共性证明。
+
+默认按读者会选择和使用的能力成页。主组件、仅供其使用的 part、配置类型及辅助 hook 可以同页；独立公共能力、独立运行契约或明显不同平台再拆。静态方法不是第二个 SDK，Props 类型不是另一篇组件文章。
+
+Toast 类家族可以先给成员选择表，再按成员或调用方式分节；复杂家族可以保留一篇入口和少量详情。不因为导出多个符号就强制多页，也不因同名而合并不同平台、包版本和 deprecated 实现。
+
+### 默认文章结构
+
+以下八个章节角色和顺序稳定。1、2、4、8 是基本阅读责任；其他章节按事实适用性出现。没有资料支撑的示例可以只保留维护示例入口和具体缺失前提，不能补造行为。
+
+```markdown
+# <组件或家族名称>
+> 包与导入入口 · 平台 · 适用版本 · 维护状态
+
+## 用途与选用
+## 接入与基本用法
+## 典型场景与变体
+## API
+## 行为与组合规则
+## 样式与设计系统
+## 运行环境、可访问性与限制
+## 相关组件与源码入口
+```
+
+| 章节 | 应回答什么 | 内容形式与证据 |
+| --- | --- | --- |
+| 用途与选用 | 解决什么界面任务；与相近组件如何区分 | 简短用途；家族成员／选型表；产品语义来自维护说明或用法，不能按组件名发明设计建议 |
+| 接入与基本用法 | 怎么导入、先配置什么、最少怎样使用 | 精确 import／entry、必要 Provider／CSS 链接、最小有来源示例；示例依赖不能只存在于演练场隐藏 scope |
+| 典型场景与变体 | 哪些选择会改变使用方式 | 场景→相关 API→预期表现→示例；按行为差异选取，不枚举所有颜色和大小的笛卡尔积 |
+| API | 消费者能传什么、调用什么、收到什么 | 下述分类契约表；公共关键配置类型可在本节局部解释，规范信息只维护一份 |
+| 行为与组合规则 | 状态谁控制、如何交互、配置如何叠加 | 受控／非受控、回调、数据结构、覆盖顺序、关闭／清理、组合约束；具体内容由组件能力决定 |
+| 样式与设计系统 | 哪些是组件可覆盖项、哪些来自全局系统 | 变体、尺寸、slot、token、逻辑方向等具体差异；公共基础规范链接到设计系统，不整篇复制 |
+| 运行环境、可访问性与限制 | 在什么条件下可用、有什么已知边界 | SSR／Portal／宿主／移动端限制；已证实键盘、焦点、role、对比度相关行为；实际测试与静态观察区分 |
+| 相关组件与源码入口 | 继续查哪里、换用谁、哪份证据支持本页 | 相关能力、实现／类型／示例／文档定位，明确证据版本；关键行为的定位尽量贴近对应章节 |
+
+章节可以有组件特定的小节，例如“选择后是否关闭”“清理时机”“嵌套分组”。固定公共章节不要求把每个组件的业务特点改成相同文案，也不改变事实的原有语义。
+
+### API 分组规范
+
+| 类别 | 默认列 | 适用条件 |
+| --- | --- | --- |
+| Props／属性 | 名称、类型、必填、默认或取值来源、语义／约束 | 公共输入属性；仅展示一次，不混入 export-entry 伪属性 |
+| 事件／回调 | 名称、参数、触发时机、与状态的关系 | callback 也是 prop 时用链接或合并行，避免两份定义漂移 |
+| 方法／静态 API | 名称、签名或参数、返回、生命周期／清理 | show/destroy 等公开方法；不能只打印 JSDoc 一段字符串 |
+| Ref／命令式句柄 | 获取方式、公开成员、何时可用、失效／清理 | 有 ref/handle 契约时，函数类型需保留有效签名 |
+| 子组件／slot／part | 身份、放置位置、组合限制、独立 API | 公开复合组件，不将仅内部渲染函数列为消费者可用 |
+| Hook | 调用前提、参数、返回、Provider／生命周期依赖 | 有明确公共契约时；独立用途较大可另用公共库参考 |
+| 关键配置类型 | 判别字段、各分支必需项、嵌套项、关联 API | 对象数组、union、group/item、受约束配置等对用法必要时 |
+
+**类型必须可理解。** 保留 union 成员、数组元素、泛型和函数参数。无法解析的类型给准确别名与权威定义入口，不能渲染成 `{}` 后当作完整契约。不递归展开整个 React、宿主上下文或基础库类型树。
+
+**默认值必须有来源。** 区分参数默认、运行时分支默认、继承环境与文档声明。同版本事实矛盾时说明冲突并回查，不能用大量 `unknown` 遮住已知默认；未声明的默认不能猜成 false／undefined。正文与 API 表不能给相互冲突的确定值。
+
+继承属性优先“来源链接＋本组件差异／覆盖”；仅在独立消费必须时展开必要字段。配置类型用于解释约束，不在表后再次粘贴完整原始声明。少量无法由表表达的签名可以保留，声明压缩后的正确性需要核验。
+
+### 不同组件能力的章节变体
+
+| 能力形态 | 必须额外表达的有效信息 |
+| --- | --- |
+| 展示型 | 内容与截断、尺寸／外观变体；不能强造状态管理章节 |
+| 可交互／表单型 | 受控关系、输入输出、禁用与只读、校验、触发时机；不要混淆视觉禁用和实际阻止事件 |
+| 浮层型 | trigger、Portal root、定位／碰撞、开合、dismiss、焦点、安全区与层级；已证实的环境差异 |
+| 数据／复合型 | item/group 判别结构、部件组合、全局与局部配置优先级、选择后的动作 |
+| 命令式型 | 初始化上下文、show/update/destroy 等实际公开方法、返回句柄、排队／替换、卸载与资源清理 |
+
+这些是同一标准模板的条件章节，不是新增 Provider。一个组件同时满足多个形态时组合使用，语义信息只写一次。
+
+### 示例标准
+
+默认一个可说明基本用法的维护示例，再按独立行为补必要案例；没有固定六个示例或每个 Prop 一个示例的要求。命令式与声明式都是公开用法时，分别保留入口。至少覆盖会改变消费方式的关键分支，而非只提供装饰性按钮 demo。
+
+示例需标明原始文件／故事／官网来源及适用版本。摘取时保留必需 import、状态回写、Provider 和样式前提；允许省略重复的演示布局，不能删掉决定行为的控制代码。引用已有例子不等于本轮实际运行通过。官方示例若与目标版本不匹配，先记录版本差异，不能直接覆盖代码契约。
+
+## 图示选择
+
+公开 parts 层级用 text 树；有证据的受控交互或命令式生命周期用 sequenceDiagram/状态图；外观用授权示例图。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。