审阅变更请求
审核并应用或驳回编码 Agent 在版本发布后暂存提交的规格更新建议。
在项目完成首次版本发布之后，编码 Agent 依然可以通过 CLI 或 MCP 协议发起规格写入——但这些写入操作将不再直接进入动态的工作区。相反，它们会被平台自动组织并暂存为一条等待人类审核的变更请求（Change Request）。你可以逐项审阅，将合理修改应用进工作区，驳回不合理的诉求（并注明原因），随后发布新版本，使后续的代码开发基于全新快照展开。
人类在 Web 工作台中的编辑操作依然保持即时保存生效。变更请求机制专为编码 Agent（以及 GitHub App 在代码审查时捕获的规格差异）提供了安全的反馈与反向同步管道，而绝不会在后台滋生混乱的第二份文件分支。
为什么需要引入变更请求
编码 Agent 默认读取的是最新已发布的 Release 快照，而非你正在工作台中调整中的动态草稿。如果允许它们基于相对陈旧的快照直接覆写工作区，极易冲撞并覆盖人类尚未完成的规格修改。
暂存机制将决策把控权稳固保留在人类手中。当写入返回 suggested: true 时代表暂存成功——修改建议已平稳进入 变更请求 面板等待决策，而非粗暴抛出权限拒绝错误中断 Agent 执行流程。
| 参与方 | 首次发布后的权限行为 |
|---|---|
| 人类成员（或应用内 Agent）在 Web 工作台中 | 直接写入并保存至动态工作区 |
| 外部编码 Agent（通过 CLI 或 MCP） | 自动受控转换为暂存变更请求 |
| GitHub App（当 CI 评审发现规格有待校准时） | 自动暂存为变更请求 |
访问与打开变更请求
- 打开目标项目。
- 在项目导航栏中切换至 变更请求。标签上的数字角标直观提示当前尚有文档待决策的开放请求数量。
- 点击目标条目展开详情以供审阅。
若 Agent 或 GitHub 评审尚未提交任何修改建议，该列表为空属于正常状态。你在工作台中的自主编辑不会出现在此处。首次接收到变更时，系统会弹出明确指引，提示有待决定的变更请求需要处理。
审阅变更请求的详情
每个变更请求代表一组协同修改的文档建议集合，并非 Git 意义上的复杂分支。
| 界面元素 | 对应含义与作用 |
|---|---|
| 状态（Status） | 开放中（Open）（仍在持续写入中）、待审阅（Submitted）（作者已标记为就绪）、已决定（Decided）（全部文档均已被应用或驳回）。 |
| 来源（Source） | 标明发起方：编码 Agent、GitHub App 或协作者。来自 GitHub 的变更支持直接点击反查对应的 Pull Request。 |
| 变更动机（Intent） | 阐明本次变更旨在解决的具体业务问题，以及关键的技术与设计选型权衡说明。 |
| 涉及文档 | 支持直观预览渲染后的视觉效果，亦可阅读行内对比或并排的规格 Diff 差异。 |
| 写入批次（Batch） | 展示已固化的写入波次。Agent 可在不标记整单就绪的情况下封存单批次写入。 |
| 历史版本冲突标识 | 提示该修改建议所基于的工作区基线，在此期间已被人类修改过。 |
你还可以点击 在画布中审阅，像浏览正常规格文件一样，在画布上逐屏走查被修改的原型页面。
应用与驳回操作
变更请求中的所有建议内容，在人类执行应用确认之前，绝不会渗入当前生效的工作区。
- 打开目标变更请求。
- 逐一审阅相关文档的变更细节。
- 可点击 全部应用（Apply All），亦可逐个文档点击局部应用。
- 若部分文档被标记为冲突旧版，你可以选择跳过忽略、前往工作台手动修改，或在确认建议依然有效时选择 强制应用。
- 如需整体拒绝剩余修改，请点击 关闭（Close） 并填写明确驳回原因。待处理文档将被正式标记为驳回；Agent 在下一次发起相似提议前将能读取该原因。
关闭操作必须注明驳回理由。list-proposals 接口会在已决定的记录中返回 dismiss_reason，编码 Agent 能据此自主复盘并调整策略，避免盲目重复提交已被否决的内容。
执行应用操作会将内容写入当前工作区，但不会自动触发发布。只有当你确认整套规格已完善且达到交付标准时，再前往发布新的 Release 快照。
Agent 后台执行流程
你通常无需手动运行底层命令——OriginAI 官方 Skill 已将这一链路深度内化。以下为 Agent 端执行的标准命令交互逻辑：
npx originai list-proposals --status all # 再次写入前主动检索历史驳回原因与反馈
npx originai write-document --name "…" --content "…"
# 首次暂存写入会自动创建变更请求（返回 suggested: true 与 proposal_id）
# 系统无须显式调用 create_change_request 命令
npx originai describe-proposal <id> --title "…" --note "…" --rationale "…"
npx originai submit-proposal <id>除非 Agent 显式指定 --proposal <id> 或是 --new-proposal，否则 write-document 会自动追加至当前访问令牌名下最近一条处于开放状态的变更请求中。最终的批准应用、原因驳回与结论定夺始终在 OriginAI 界面中完成——Agent 严禁自审自批。
当你在平台完成应用与发布后，本地代码仓库可以显式绑定该变更请求，指引下一条 PR 对齐实现：
npx originai get-proposal-diff <id> --bind
npx originai get-diff # 此时对比内容为：已发布 Release 与该变更请求的差集
# 在工程代码中落地实现 Diff 中的规格
npx originai sync # 在产生新的 Release 哈希之后执行同步请注意：sync 命令仅在检测到新的 Release 哈希生成后，才会清除本地配置文件中绑定的 proposal_id。命令完整说明见 CLI 参考。
良好运作的标志
- 发布版本后，来自外部 Agent 的写入能够平稳在 变更请求 面板暂存，动态工作区在确认应用前保持纯净。
- 人类能够从容应用修改、识别冲突版本，或附带清晰理由关闭请求——外部 Agent 能够有效读取驳回反馈。
- 外部编码 Agent 始终对齐已发布的权威 Release 实施开发，将变更请求纯粹作为下一版本的演进建议。
- 团队完全理解返回
suggested: true是安全机制而非写入异常。
常见排查与处理建议
| 现象 | 排查原因与应对方式 |
|---|---|
写入操作返回 suggested: true | 此为发布后的标准预期行为。前往 Web 端 变更请求 面板审核应用，随后发布新版。 |
| 变更请求列表空空如也 | 当前尚无外部 Agent 发起过暂存请求。人类在工作台中的修改是直接保存的。 |
| 点击 全部应用 时部分文件被跳过 | 这些文件被判定为与当前工作区基线存在版本偏差。审阅差异后选择强制应用或忽略。 |
| Agent 反复提交已被拒绝的相同修改 | 在关闭时附带更详尽的驳回说明，或确保 Agent 在写入前调用了 list-proposals --status all 读取历史上下文。 |
| 工作区中已应用修改但 Agent 仍实现旧代码 | 应用仅仅同步至工作区草稿，尚未对外发布——请执行发布 Release 版本。 |
| 希望下一次 PR 审查严格对照此请求开展 | 执行 get-proposal-diff <id> --bind 完成绑定，并参见 GitHub App 代码审查指南。 |