Nexus 文档内容与图示标准¶
本标准用于新增和修改的平台文档。目标是让读者明确任务、条件、操作和结果，
能够沿文档完成使用、接入、维护或验收。既有页面按
实施台账逐批审查；本标准的存在不表示
正文迁移、图册、自动检查、翻译或发布已经完成。
必须/不得表示合同要求；应/不应表示默认做法，例外需有理由；可以表示允许的 选择。规范性要求必须明确主体、条件、动作和可检查的结果。责任由 Codex 承担， 独立 agent 进行内容和图示评审，不要求虚构人员账号。
1. 内容必须帮助读者完成任务¶
编号 |
约束 |
验收方法 |
|---|---|---|
TXT-01 |
开头说明读者能完成什么、适用配置和必要限制 |
单看开头能够判断是否适用 |
TXT-02 |
tutorial/how-to 围绕一个主要目标，先给结果和必要步骤 |
独立读者能够按步骤完成 |
TXT-03 |
一段围绕一个问题，使用具体主体、主动动词和稳定术语 |
去掉重复结论、口号和无解释的缩写 |
TXT-04 |
比较/字段用表；顺序用步骤；结构与并发用对应图 |
表、图、正文各自承担必要信息 |
TXT-05 |
原始日志、大量hash和失败尝试链接到证据，不打断操作主线 |
可读摘要能定位完整原件 |
TXT-06 |
精确区分当前实现、已验证、估计和计划 |
每个能力/性能结论有范围与出处 |
TXT-07 |
同一规范只维护一份，概述/翻译/图链接权威合同 |
修改接口不需同步两份手写声明 |
TXT-08 |
架构和合同改变同时核对受影响图、示例与翻译 |
PR列出影响范围与审查结果 |
不设机械字数、句数或图数量门槛。复杂页面需要任务索引和分层说明；简单动作 不强制配图。不能用“极致、完整、全部支持”等无范围结论代替成本和资格记录。
页面采用 五类内容模板。模板规定必须回答的问题， 不强制所有页面使用相同标题。当前架构解释需回答：为何分层、谁拥有状态和资源、 谁调用谁、构建与运行各做什么、合法上下文、失败责任、成本及验证边界。
2. 术语、单位和约束¶
首次出现可给中英文对应，随后同一概念使用同一词。C符号、配置键、错误码、 结构字段、CSV/JSON值和版本ID保持原样，不翻译标识符。必须区分：
术语 |
本文档体系中的含义 |
|---|---|
factory |
返回该装配已有静态接口的typed查找 |
face |
公共只读接口，含ops和实例context |
provider |
具体实现及私有状态 |
controller/endpoint |
控制器身份与其逻辑/外部端点身份 |
owner/executor |
资源/生命周期责任与实际执行推进责任 |
request/buffer |
请求元数据与被借用的数据存储 |
DMA complete |
DMA阶段完成，尚需外设和引用排空 |
wire complete |
外设线上传输完成，尚需满足其余结束条件 |
SETTLED |
provider最终访问后release发布；调用方acquire观察 |
QUARANTINED |
未安全结束，借用和恢复责任仍保留 |
所有容量和测量写单位：B/KiB、Hz/MHz、cycles、µs/ms。Flash LOAD、Flash footprint、预留RAM和实测栈高水位分别记录。对齐、长度粒度、inclusive limit、 溢出、deadline时间域和最大配置须明确。理论上界、估计和实测值不能混写。
有效约束示例：ACCEPTED后，调用方必须保持请求和缓冲区有效，直到acquire观察 SETTLED；复用相关adapter/observer存储还需对应引用排空。无效表述示例： “注意生命周期”。后者缺少主体、结束条件和失败责任。
3. 事实、计划和资格必须分别表达¶
表述 |
必需依据 |
|---|---|
当前实现 |
对应源码、配置/模式和行为范围 |
已通过模型/Native |
精确源码、测试scope、实际执行结果 |
ARM链接/资源验证 |
对应配置、工具、ELF/BIN/map与检查 |
软件候选 |
clean source、SDK、实际复现和同产物证据 |
实板通过 |
PCB/芯片/设备/station/image和实际测量 |
计划或目标 |
未实施任务及退出条件，不写成现有能力 |
芯片具备、SDK提供、provider维护、Board授权、软件通过、HIL通过不能合并成 一个“支持”。当前、目标和参考配置必须在页面及图的caption中可见。文档发布 不建立新的平台资格。旧结果保留原始源码、失败尝试和状态，不能重标为新HEAD。
4. 示例与命令¶
完整例子必须来自维护fixture或固定版本外部示例，并关联实际consumer验证。 优先literalinclude；省略部分注明fragment原因。不能把示意片段称为完整教程。 普通构建不自动刷写、不执行任意Markdown命令，也不取得远程latest。
每个命令说明工作目录、工具和连接前提、输入、预期结果、检查成功方法、清理。 固件C示例遵守现有C11、80列、四空格、附着大括号、类型侧指针和反斜杠 Doxygen风格。工具及测试示例遵守对应语言规范，包括现有Python工具和C++17 GoogleTest/GoogleMock用法。文档规则不重新定义仓库代码风格。
异步例子必须说明拒绝、接受借用、执行推进、等待、取消、排空及结束后资源。 timeout/cancel不自动撤销借用；失败停止保留QUARANTINED存储。唤醒只是提示， 不能用无限等待掩盖推进条件。产品任务、私有分区和恢复政策仍属于外部工程。
5. 图示身份与关系¶
每张图至少有ID、名称、用途、类型、适用范围、关系图例、正文合同和来源。
ID用于目录和迁移；公共anchor使用标准显式target/label，不能依靠front matter
自动产生引用。图源与输出登记在 图册清单。
图的身份 |
允许表达 |
不得暗示 |
|---|---|---|
current |
经源码核对的结构/契约 |
整个平台、所有模式或实板均通过 |
target |
已制定但待实施的设计 |
新模块/工具已存在或已部署 |
reference |
精确芯片/板卡/模式的参考装配 |
自动推广到其他平台、PCB和安全域 |
一张图解决一个主要问题。分层图、编译依赖图、生成流程、数据流、时序和状态图 分别表达对应关系；混合关系时逐边标明含义。跨边界箭头必须可解释，不能同时 把未标记箭头理解为调用、生成和所有权转移。
节点名对应源码、接口或明确概念；可选项必须有文字或线型标记，不能只靠颜色。 返回箭头、异步事件、状态迁移的方向准确。图不会因美化增加不存在的CPU factory、 隐藏任务、统一池或强制OS层。
6. 必需图册与语义检查¶
下列图分别对应DOC-43至DOC-57，具体顺序与退出条件在实施台账。
图ID |
内容 |
必须表达的关键事实 |
|---|---|---|
FIG-01 |
全平台架构与外部边界 |
产品外置，Core/Arch/SoC/I/O，组件和OS可选 |
FIG-02 |
编译目标依赖 |
从实际CMake核对，SDK私有，应用依赖平台 |
FIG-03 |
配置和生成 |
TOML+facts→typed IR→原子bundle→CMake→产物；失败失效 |
FIG-04 |
factory/实例结构 |
既有face、共享ops、独立context；controller与endpoint |
FIG-05 |
初始化与失败撤回 |
显式启动、部分效果、逆序撤回、失败保留责任 |
FIG-06 |
请求状态 |
拒绝/借用/排空/隔离/SETTLED，观察者另需退出 |
FIG-07 |
UART/SPI DMA时序 |
DMA TC、线上完成、引用排空与最终发布分开 |
FIG-08 |
wait/wake/退出 |
ready-arm-ready-wait-ready，执行器和join责任 |
FIG-09 |
CPU/内存/DMA/Cache |
精确配置、可达域、完整cache line与维护时点 |
FIG-10 |
SDK消费 |
实际外部工程、搬移、配置/链接/运行和产物检查 |
FIG-11 |
软件与HIL证据 |
各自实际取得，再按scope准入；不自动生成物理资格 |
FIG-12 |
文档/SDK发布与恢复 |
身份、不可变版本、离线包、下载和独立恢复 |
FIG-13 |
Cortex-M能力分层 |
原语、Runtime、SoC接入、实板资格分别表达 |
FIG-14 |
U575双域 |
仅选定TZEN=1同步参考；SAU/MPU/GTZC/gateway责任 |
FIG-15 |
连续流与丢块 |
producer/block/consumer、overrun和停止排空；服务预算 |
运行图必须让读者看到：factory取得已有接口以后，日常I/O直接通过face进入 provider；Arch按编译目标选择；应用拥有调度和执行进度。初始化顺序不能由静态 结构图推断，静态结构图也不能代表运行时每次调用路径。
状态图中REJECTED/ACCEPTED是admission结果，不伪造为nx_request_state_t状态。 SETTLED只在全部必要引用排空后发布；取消/deadline不能直接指向“存储已释放”。 QUARANTINED到结束必须有实际恢复/排空证明，不暗示每个provider都有恢复API。 时序图必须包含相关失败分支或链接独立失败图，并标清Task/IRQ/DMA/安全域。
图不能替代正文的调用前提与权威合同。图文冲突时暂停相关交付结论并修正来源， 不能只改图或教程隐藏规范冲突。
7. 图源、视觉和离线交付¶
首批采用可编辑Graphviz DOT和本地SVG，图源与输出成对保存。Sphinx后续可用 内置graphviz扩展；新图链及工具锁仍按DOC-25/33实施。既有Mermaid作为迁移输入， 不能另维护同一图的第二份权威源。需要时序专用工具时，以实际需求另行审查闭包。
每张图同时满足：
图源可审查，图名/ID稳定；图源变更后重新生成输出。
深色文字与清楚边界；颜色不是唯一含义，灰度下仍可区分。
标签短且具体，复杂说明放正文；过密时拆图，不缩小到无法阅读。
中文、英文、C符号完整，无缺字、重叠、裁切和模糊截图。
提供alt和caption；窄屏可以放大或独立打开SVG，不把整图强制缩成小字。
SVG默认无脚本、动画、foreignObject、外部href/资源及DOCTYPE。
图和图源随离线包交付，加载、字体说明与检查不依赖CDN。
Graphviz及实际字体进入文档工具闭包，缺失或差异不伪称已验证。
SVG解析和渲染成功不证明架构正确。独立审查必须逐边核对调用/依赖、状态和 失败责任。实际显示需要检查桌面、窄屏/放大和打印；未执行项保留未验证状态。
8. 评审与自动化职责¶
检查 |
机器可负责 |
独立语义审查负责 |
|---|---|---|
正文 |
格式、字段、链接、anchor、导航 |
任务完整、前提准确、术语清楚 |
示例 |
实际解析/构建、固定输入与退出码 |
正常/失败/恢复和所有权正确 |
图 |
图源语法、文件配对、SVG资源、哈希 |
箭头/可选项/时序/状态与代码一致 |
翻译 |
源版本、缺译/fuzzy、状态 |
规范强度、单位和失败条件保持 |
交付 |
manifest、相对链接、实际站点身份 |
支持/计划/资格边界没有混淆 |
不通过正则扫描正文来自动判定“支持”或“安全”。新增gate行为采用实际负路径 TDD；纯正文和图源修改采用对应检查与语义评审，不新增镜像实现测试。
审查记录至少绑定页面/图、代码与文档来源、发现、处理结果和退出条件。下列情况 必须修正后才能关闭相应任务：错误配置、借用提前回收、错误完成顺序、图中虚构 模块、错误支持/HIL声明、断链、未标注的过期翻译、关键图无法阅读。
完整标准应用和58项系统实施以台账实际状态为准。快速提交检查、严格文档CI、 图源/输出配对和关键翻译检查由统一CLI执行；独立语义、视觉、发布与恢复结果 分别绑定实际输入，不从规则或工作流存在推断执行完成。