文档系统

文档范围#

本页定义 UIChat Mira 公共文档站与主仓库工程文档的职责、生命周期、内容结构和写作规则。

两套文档视图#

主仓库工程文档#

主仓库 uichat-mira/dev 中的 docs/ 用于：

保存 current-contract 和 current-snapshot；
记录施工任务、测试、评审和缺陷；
归档历史方案和迁移过程；
为工程人员和 Agent 提供完整检索入口；
核对代码、合同和验证证据。

完整性优先于简洁性。

tomz.io 公共文档#

uichat-mira-docs 中的 src/pages/docs/ 用于：

解释当前产品定义；
提供用户操作说明；
说明稳定架构和边界；
展示当前状态和明确计划；
为公开读者提供可维护的阅读路径。

可读性和当前事实优先，不复制全部施工材料。

真相优先级#

公开文档的事实来源顺序：

Current Code + Repeatable Verification
→ Main Repository Current Contract / Snapshot
→ Public Product Documentation
→ Construction Record / Review / Test Evidence
→ Design / Proposal / POC
→ Historical Archive

公开文档不能使用旧 Proposal 覆盖当前代码，也不能用未验证代码覆盖 settled contract。

内容生命周期#

状态	说明	可以回答当前行为
Current	已由当前代码、测试或重复验证支持	是
Partial	已有部分实现，但入口、合同或验证不完整	只回答已明确部分
Experimental	有真实代码或入口，接口仍可能变化	需明确限制
Planned	已定义目标或方向，尚未完成	否
Historical	仅用于解释过去	否

公共页面在描述混合状态的模块时，应逐项标记，不使用一个“已支持”覆盖所有子能力。

文档语言合同#

文档区负责#

文档区使用说明书和技术文档语言，优先回答：

这页定义什么；
适用范围是什么；
当前有哪些对象和入口；
调用链和状态如何流转；
需要哪些前置条件；
有哪些限制和非目标；
如何验证；
应继续阅读哪份文档。

推荐结构：

文档范围
当前结论
核心对象 / 数据模型
调用链 / 操作步骤
能力或状态矩阵
边界与非目标
验证清单
相关文档

博客区负责#

博客可以记录：

为什么做出某个判断；
施工过程和经验；
失败、争议和演进；
产品观点与个人叙事；
更自由的语气和结构。

博客文章不能自动成为当前产品合同。

禁止的混写#

文档区避免：

用“为什么值得做”替代当前能力；
用品牌愿景替代产品定义；
用情绪化自述替代操作和状态；
用手写 HTML 展示卡代替表格和字段；
用“我们将会”描述成已经实现；
用入口卡片存在推断 Runtime Ready；
用模型表述或 UI 文案证明任务完成；
把作者私人信息写入产品说明。

品牌句、截图和示例可以保留，但必须服务于明确文档目标。

Frontmatter 约定#

公共文档至少使用：

字段	作用
`title`	页面标题
`description`	搜索和列表摘要
`group`	侧栏分组
`order`	分组内顺序

博客可额外使用 date、readTime、tags、author、writingMode、writtenBy 和 reviewedBy。

Frontmatter 不替代正文中的状态说明。对于 Partial、Experimental 或 Planned 能力，正文仍需明确边界。

目录职责#

目录	回答的问题
认识 Mira	产品是什么、由谁维护、有哪些一级产品域
产品哲学	哪些设计原则是稳定约束
产品能力	用户如何使用具体能力，当前支持什么
架构	Runtime、职责、调用链和不变量是什么
配置	前置条件、配置项、验证和失败处理是什么
工程	仓库、开发、诊断和文档维护方式是什么
现状与方向	当前事实、已知偏差和明确计划是什么

搜索与 Sitemap#

Ctrl + K / Command + K 搜索标题、描述和正文；
Sitemap 提供人工维护的推荐阅读顺序；
侧栏由 group 和 order 生成；
页内导航由 Markdown 标题生成。

搜索结果可能同时包含当前、计划和历史内容。读者仍需检查页面状态和核验日期。

更新流程#

修改公共文档时：

先确认主仓库当前代码和合同；
确定页面属于定义、操作、架构还是状态；
保留已验证事实，删除过时绝对表述；
明确 Partial、Experimental 和 Planned；
补充边界、失败处理和验证方式；
运行内容兼容、生产 Build 和静态输出检查；
通过 PR 合入主分支。

防回退检查#

评审文档改动时检查：

页面是否先说明范围；
是否区分当前与计划；
是否存在无法核验的宣传用语；
表格中的状态是否有代码或验证依据；
是否把博客语言带入说明书；
是否破坏链接和内容发现；
是否通过生产构建和静态输出验证。