工作区与 Release 快照

OriginAI 将“人类日常编辑调试中的动态规格”与“已正式冻结交付的权威规格”在架构上严格解耦。平台的绝大部分交互逻辑与权限边界均由此演化而来。

工作区（Workspace）

工作区是指你在 OriginAI Web 工作台中持续维护的动态活动文件树（系统底层维护为 rpml_files 树结构）。

• 支持使用可视化画布、文件目录树以及应用内 Agent 进行增删改查。
• 在项目进行首次正式发布之前，编码 Agent 可以通过 CLI 命令（write-document）直接将提取的规格写入工作区。
• 在项目完成首次发布之后，编码 Agent 仍可调用 API 发起写入，但这些变更会自动转换为变更请求（Change Request），由人类在 OriginAI 中逐项审核应用（在应用确认前绝不会直接污染动态工作区）。

Release 快照

Release 快照是发布时刻对整个工作区文件树进行内容级固化生成的不可变快照，由内容哈希唯一标识。

• 它是所有外部 Agent 检索读取的默认目标源（包括 list-documents、get-document、get-diff 等接口）。
• 可一键编译并部署至 spec.getoriginai.com，生成独立的公开 HTML 交互预览。
• 完整的版本哈希历史忠实记录了项目在各个关键工程阶段实际交付给实现的规格全貌。

首次发布后的核心协同规则

完成首次发布后，编码 Agent 默认依然读取最新已发布的权威 Release。任何来自外部的写入操作将不再直接修改工作区，而是暂存为变更请求，等待人类在 OriginAI 界面中进行应用（Apply），确认后再行发布新版本。

设计原因：编码 Agent 是基于已发布的 Release 快照进行上下文理解与代码编写的。如果允许其直接覆写工作区，极易因版本信息差而无意抹掉人类在工作台中尚未完结的灵感或改动草稿。暂存机制将决策权稳健留给人类把控，同时避免直接返回 403 权限拒绝导致外部自动化流程中断。

在项目发布首个 Release 之后的典型协作流程如下：

1. Agent（或协作者）发起规格修订请求，暂存变更；执行 submit-proposal 将变更请求标记为就绪状态。
2. 人类在工作台中审视可视化差异（Diff），决定批准应用或驳回（驳回时可附带原因说明，Agent 在下次交互时可读取该上下文）。
3. 人类在工作台中确认无误，发布新的 Release 版本。
4. Agent 运行 get-diff 获取最新版本差异，完成代码实现，最后执行 sync。在 GitHub PR 协作中，亦可在 .origin.json 中绑定 proposal_id，触发 spec-review 审查专项代码。只有在产生新的 Release 哈希后，sync 才会清除本地绑定的 proposal_id。

通过 CLI 读取指定的数据源

在默认情况下，CLI 会直接读取最新发布的 Release。你也可以通过特定参数显式指定读取源：

# 默认行为 —— 读取最新发布的权威 Release 快照
npx originai list-documents

# 读取动态工作区（用于发布前的规格索引或校验刚刚写入的草稿）
npx originai list-documents --read-type workspace

# 通过哈希精准读取历史特定的某一版 Release 快照
npx originai list-documents --release-tag <hash>

相关内容

• 以 Release 快照为权威事实源
• 发布一个 Release
• OriginAI CLI 命令行参考