文件体系与全局 README
掌握基于文件目录树、全局产品 README 以及结构化页面文件组织与维护复杂规格的最佳实践。
在 OriginAI 中，你的完整产品上下文完全承载于标准化的文件体系之中。将交互页面、状态分支与业务规则清晰划分为组织良好的文件单元，能确保人类协作者与各类外部编码 Agent 始终在一个统一且结构严谨的知识基准上协同。
本指南将深入解析 OriginAI 项目文件的标准组织范式，以及保持各文件之间高度一致性的维护策略。
规格文件体系的标准分工
| 文件类型 | 典型文件命名 | 核心职责与业务价值 |
|---|---|---|
| 全局产品设计文档 | README.rpml（显式声明 mode="doc"） | 作为全系统顶层蓝图：涵盖功能模块划分、信息架构、全局路由规划、关键用户旅程及角色权限矩阵。 |
| 具体页面与功能区域 | *.rpml（例如 dashboard.rpml、settings.rpml） | 承载具体的独立屏幕或区域：包含精准的 DOM 布局结构、全交互状态分支及就地锚点业务标注。 |
| 辅助与扩展文件 | 各类附随资产与配置文档 | 记录系统补充说明、设计参考备注或依赖元数据，按需灵活扩充。 |
可以将 README.rpml 视为整个产品的“顶层全景导航地图”，而具体的每一个 .rpml 页面文件则是该地图上对应坐标的“高保真微观实景”。当两者保持严密同步时，任何人类工程师或自主 Agent 仅凭全局 README 即可完整掌握并导航整个系统的所有细节。
供外部 Agent 查阅的完整 RPML 语法规范与标准原语参考，均内聚在官方 Skill 的 rpml/ 资产目录中；当你执行 originai link --skill 时，系统将自动在本地环境中完成部署。
保持文件体系的一致性与严密性
- 在工作台中展开左侧文件目录树。
- 优先通读
README.rpml，全面理解系统的全局架构蓝图与路由划分。 - 依次点开规划中的各核心路由
.rpml文件，在画布上确认其实际渲染形态与状态建模是否完备。 - 在编辑器中手动调整，或借助应用内 Agent 进行指令式重构，确保 README 中所罗列的页面清单与实际存在的文件树一一对应。
- 当整棵文件树的完备度完全契合工程实现预期时，即可从容执行版本发布。
首次发布前：允许编码 Agent 逆向写入文件
必须特别注意的是：外部编码 Agent 仅在项目完成首次版本发布之前，拥有直接向动态工作区写入或修改规格文件的权限。在这一阶段，典型的逆向初始化交互流程如下：
npx originai validate --content "<rpml>"
npx originai write-document --name "README.rpml" --content "<rpml>"
npx originai list-documents --read-type workspace一旦项目完成了首次正式发布，系统的版本安全写入保护将立即自动生效：外部 Agent 的所有写入将不再直接修改正在运行的工作区，而是自动暂存为变更请求。在此之后，直接修改工作区的特权仅保留给在 Web 工作台中操作的人类成员。
健康规范的核心标志
- 系统的关键交互规则与状态边界均显式沉淀在实体规格文件中，而非遗失在漫无边际的模型对话记录里。
- 全局
README.rpml中所规划的每一个路由与功能页面，在工作区中均能找到与其对应的实体.rpml规格文件。