# 有解 Realize 操作手册

> 适用版本：有解 Realize 邀请内测版
> 更新日期：2026-08-11
> 说明：下文“平台”均指有解 Realize；Workflow Studio 是历史工程代号。

## 0. 安装与邀请授权

1. 从许可方提供的受控渠道取得安装包，并核对发布记录中的 SHA-256。
2. 首次启动时导出设备申请文件。该文件包含脱敏设备哈希，不包含 API Key、CLI 登录凭据或项目正文。
3. 将设备申请交给许可方，取得与本机绑定的离线许可证后导入。
4. 邀请许可证默认有效期为签发时刻起 15 天，仅供获邀用户在一台设备上测试。
5. 到期后平台进入只读模式，不删除项目和历史记录；续签并导入新许可证后恢复相应权益。

用户自行准备并承担模型 API 或 CLI Agent 的账号、额度和费用。不要把 API Key、Token、密码或 CLI 登录凭据发送给许可方。

## 1. 新建项目

1. 在“项目与配置中心”点击“新建配置”。
2. 填写配置名称与本地项目目录。
3. 点击“检测工程入口”，选择一个“主要产出目标”。模型的读写和测试范围受该目标约束。
4. 只读资料填写项目内相对路径，每行一个。不要填写其他项目或系统目录。

旧项目继续使用原有直接工作区配置；新建项目默认使用隔离 Run Workspace。

## 2. 首次设置 Run Workspace

新项目必须显式选择存储位置，平台不会静默回退到 C 盘。

1. 在“Run Workspace 存储”填写显示名称，例如“D 盘 Run Workspace”。
2. 填写非系统盘根目录，例如 `D:\WorkflowRuns`。
3. 点击“验证并保存”。平台会检查目录是否可写、是否与原项目重叠以及可用空间。
4. 看到“路径可写，Profile 已保存”后，确认空间估算为“通过”。

“Profile”表示一组保存在本机的配置名称。存储 Profile 记录显示名称、根目录、最低剩余空间和保留天数，不会进入团队包。

## 3. 普通版：统一模型

普通版适合只想配置一次 API 的用户。所有角色继承项目默认 Provider、协议和模型。

1. 可选择已保存 Provider，或填写供应商预设、API 格式、API 地址和模型 ID。
2. API Key 只在本机加密凭据库保存，不写入项目 YAML、Run 快照或团队包。
3. 点击“测试连接”验证配置。
4. 不开启“进阶 CLI Agent 增值模块”。

平台会利用供应商返回的 usage/cache 指标展示 Token 与缓存数据；供应商未返回的数据会显示“未知/不支持”，不会伪造为 0。

## 4. 进阶版：角色级 HTTP 与 CLI

开启“进阶 CLI Agent 增值模块”后，在“角色与流程”中可以为每个角色选择：

- 继承项目默认：使用普通版中的统一 HTTP Provider/模型。
- 单独 HTTP：选择独立 Provider Profile、主模型和可选备用模型。
- 平台桥接 CLI：平台通过受控协议调用 CLI。
- 原生 CLI：复用 Codex 或 Claude Code 已登录会话、工程探索、编辑和命令能力。

备用模型默认关闭。只有明确开启后，主 Provider 失败时才允许切换；未开启时平台暂停并给出恢复建议。

## 5. CLI Profile

CLI Profile 是“如何启动本机 CLI Agent”的本机配置，不是只填写一个目录。

### Codex

- Profile：`Codex`
- 可执行命令：通常填写 `codex`；平台按参数数组启动，不经过 shell 拼接。
- 模型：可选择“CLI 默认模型”，此时平台不传 `--model`，沿用 Codex CLI 本机默认设置；只有明确填写模型 ID 时才传递模型参数。
- 预设参数包含 JSONL 输出和 workspace-write 沙箱；平台通过参数数组启动。

### Claude Code

- Profile：`Claude Code`
- Windows 可执行命令通常为 `claude.cmd`，本机可用 `where claude` 核对。
- 模型可选择“CLI 默认模型”，此时平台不传 `--model`，沿用 Claude Code 本机默认设置。
- 当前支持状态以界面探测结果为准；未登录时会暂停，不会自动改用备用模型，除非用户已显式开启。

CLI executable、参数、环境和登录恢复引用只保存在本机运行配置，不进入 Run 公共快照或团队包。

## 6. 配置角色

每个角色需要名称、职责提示、输出目录和流程位置。验证角色还应选择审查、功能测试、内容审核或用户验收类型。

角色单独配置时，启动摘要会显示实际执行方式、Profile、模型和备用开关。修改配置只影响下一轮；运行中、已暂停或已完成 Run 始终使用启动时冻结的路由。

## 7. 启动前确认

点击“启动”后，平台先展示：

- 每个角色的执行方式；
- Provider/Profile 与主模型；
- 备用模型是否开启；
- Run Workspace 预计复制大小、文件数和可用空间；
- 验收并应用前原项目保持不变的提示。

摘要令牌限时且只能使用一次。摘要打开后若配置发生变化，平台会刷新摘要，必须重新确认。

## 8. 查看 CLI 过程

“执行阶段与活动日志”显示中文摘要，不展示协议 JSON。在工作台页面级操作栏中，点击与“筛选条件”“修改标题”并列的“CLI 完整过程”可打开抽屉查看：

- 启动、分析、文件变更和完成阶段；
- 相对文件路径；
- 脱敏命令标签、退出码和耗时；
- 限流、重试、恢复和平台复验结果；
- Token/缓存数据的支持状态。

隐藏推理、原始 JSONL、完整会话、凭据、本机绝对路径和私有恢复引用不会显示。

## 9. 暂停与恢复

- 用户暂停：当前执行保存检查点，恢复同一 Run 时继续使用冻结路由和原 workspace。
- Provider/CLI 限流：等待界面建议的时间后恢复。
- CLI 未登录：在本机完成对应 CLI 登录，再恢复同一 Run。
- Workspace 离线：恢复原存储位置，或在没有活动写租约时迁移到另一个已验证 Profile。
- 服务重启：平台会协调失联租约、未完成 merge 和 workspace 状态；无法证明安全时进入“需要人工恢复”。

不要删除或移动正在运行、等待人工、冲突或恢复中的 workspace。

## 10. 验收、diff 与应用

Run 完成不等于修改已经写入原项目。

1. 在“交付物”查看输出和“工作区变更”。
2. 点击“生成变更预检”，核对新建、修改、删除数量与相对路径。
3. 需要在外部开发工具验证时，可点击“应用到原项目验证”。平台会明确提示这会写入真实目录，但不会把本轮标记为最终验收或正式合并。
4. 外部验证发现问题时，把结果反馈到后续修复轮次；修复完成后重新预检并更新同一真实项目。
5. 完成本轮最终验收。只有“验收通过”且预检无冲突时，“验收并应用”才可用；已处于“待外部验证”的事务会先重核真实文件哈希，再升级为正式合并。
6. 应用过程逐文件校验、保存回滚数据并再次验证结果。

验收结论与应用状态相互独立：验收通过不自动写文件，应用失败也不会篡改验收记录。

## 11. 冲突与保留

原项目和隔离工作区修改了同一路径时，平台进入冲突状态且不写入：

- 重新预检：人工处理原项目后重新生成冲突矩阵。
- 人工处理：关闭对话框，在原项目中处理后再预检。
- 保留不应用：长期保留本轮 workspace，不修改原项目。

第一版不内置 Git，也不自动执行 rebase。未来 Git backend 是独立扩展，不改变当前 filesystem backend 的恢复边界。

## 12. 空间清理与迁移

- 已合并 workspace 可自动清理。
- PAUSED/FAILED 默认保留 7 天。
- WAITING_HUMAN、CONFLICT、RECOVERY_REQUIRED、显式长期保留不会自动清理。
- 迁移要求无活动 writer/merge 租约；平台复制后做完整目录哈希，重新打开成功后才删除旧副本。

清理和迁移只允许发生在已配置 storage root 的 `workspaces` 子树内。

## 13. 普通 API 与 CLI 的区别

HTTP API 配置最简单、运行更轻量，成本和调用口径通常更透明，适合统一模型和常规流程。CLI 能复用用户已登录的编码 Agent、工程探索、文件编辑和命令执行能力，复杂代码项目中的自主操作能力更强；代价是本机 CLI 安装/登录要求更高、过程可能更长、usage 指标可能不完整。

CLI 不保证比 API 节省 Token。不同厂商、CLI 和 API 的 usage/cache 口径可能不同，平台只展示实际返回的数据。推荐混合编排：需要深度工程操作的角色使用 CLI，稳定的分析、审核或结构化任务使用 API。平台负责连接、隔离、交接、审计、暂停恢复和最终应用，不替代各 CLI 自身能力。

## 14. 微信开发者工具动态验收

微信小游戏在最终验收前需要打开微信开发者工具的“设置 → 安全设置 → 服务端口”。该开关允许本机 CLI 和自动化工具控制开发者工具，属于持久安全设置，只应在用户明确同意后开启；验收结束后，不再使用自动化时建议关闭。

标准顺序是：环境与登录检查 → 打开隔离工作区 → 开启自动化端口 → 清理编译缓存 → 编译 → 检查首帧和控制台 → 触控主流程 → 前后台生命周期 → 开发模式广告 success/cancel/fail → 截图。任何一步失败都应反馈到同一个 Run 的修复角色，不要直接修改隔离工作区或源项目。

注意：只看到 MCP 返回“编译成功”还不够。必须同时确认原始 CLI 输出没有 `× initialize`、自动化端口可连接、首帧非空且控制台无阻断错误，才能把动态编译标记为通过。

## 15. 团队经验

新项目默认启用团队经验；旧项目继续保持原配置。团队经验只应用已由用户采纳且与当前目标类型、任务意图和角色能力匹配的策略。直接任务、广播任务和完整工作流都必须遵守“当前用户指令优先”，不兼容模板会显示为跳过，不会强行改变角色或权限。

完成最终验收后，在“项目经验 → 本轮复盘”查看候选，选择采纳、仅记录、稍后处理或不适用。采纳后必须用下一轮相似任务验证是否真实命中；更换 Provider、模型、CLI/API backend 或 workspace baseline 时，平台会隔离差分归因，不能把环境变化写成经验改善。

经验策略规定必需角色时，平台按该顺序创建正式交接，不同时保留普通工作流产生的竞争分支。没有同 Provider、模型、backend 和 workspace manifest 的可靠历史轮次时，页面显示“等待可比较基线”，这不是失败，也不能手工改写成“经验已改善”。测试或验收过程中产生的新经验候选默认保持待处理，平台不会代替用户自动采纳。

CLI Profile 建议使用稳定命令名（例如 `codex` 或 PATH 中的 `claude.cmd`），避免绑定 WindowsApps 的版本目录。升级桌面应用后若提示 CLI 无法启动，先在终端执行版本命令并修正 Profile，再恢复同一 Run；平台会复用已完成阶段，不重复消耗。

## 16. 安装客户端

最终邀请包应同时提供安装程序、SHA256SUMS 和签名信息。当前未签名工程样包只供发布工程验证，不应发送给内测用户。

正式邀请包的安装顺序：

1. 核对发送来源、安装包文件名、SHA-256 和 Windows 数字签名；任一不一致都停止安装。
2. 双击安装程序，按简体中文向导完成当前用户安装，不需要管理员权限。
3. 从开始菜单启动平台。目标电脑不需要预装 Python、Node.js、Rust、Visual Studio 或 VS Code。
4. 首次进入后输入审核邮件中的邀请码完成在线激活，再按第 2 节选择非系统盘 Run Workspace。在线服务暂时不可用时，才使用折叠区里的离线申请文件流程。

程序文件和小型本机状态分开保存。数据库、凭据、配置、日志和许可证位于当前 Windows 用户的应用数据目录；大体积项目副本、版本、回滚数据和过程产物不放在该目录，必须保存到用户明确选择的 Run Workspace storage root。

Windows 11 开发机的真实安装、启动、修复安装、卸载保留和重装恢复已经通过，证据见 [Windows 安装记录](../test-records/windows-offline-beta-install-record.md)。Windows 10/11 独立干净机尚未完成，不得把该记录描述为正式兼容性认证。

## 17. 邀请码激活与离线兜底

平台不要求注册在线账号，也不会把设备原始标识发送给服务器。首次启动显示“需要激活”时：

1. 输入审核邮件中的邀请码并点击“联网激活”。同一个邀请码既用于下载安装包，也用于首次激活。
2. 客户端只上传域分离后的匿名设备哈希、安装实例 UUID、产品版本和渠道；不会上传用户名、原始 MachineGuid、项目内容或凭据。
3. 服务端把邀请码绑定到这一台设备并返回签名许可证；客户端先验签，再用 Windows DPAPI 保存。
4. 页面显示“已激活”和到期时间后，才可新建、修改配置或启动 Run。许可证从首次成功激活起有效 15 天。

同一设备重装或本地许可证丢失时，可用同一邀请码恢复同一张许可证；另一台设备会被拒绝。确需换机时联系发行者解绑，解绑后新设备会获得新的 15 天窗口。解绑或撤销不能让旧设备已经保存的签名许可证立即失效，旧许可证最多使用到原到期时间。

在线激活故障时，展开“离线激活与故障恢复”，导出设备申请 JSON 并交给邀请方。邀请方使用独立离线签发工具返回许可证后再导入。离线申请文件只含安装实例 UUID、派生设备哈希、版本和渠道；离线主私钥不会进入服务器或客户端。

许可证与设备、产品主版本和有效期绑定。许可证到期或检测到明显时钟回拨时，平台进入只读：仍可查看历史和导出允许的数据，但拒绝启动 Run、修改配置、写入凭据和应用合并。许可证状态损坏时不要自行删除状态文件，应保留现场并联系维护者。

## 18. 升级、回滚与卸载

升级前：

1. 结束正在运行的 Run，确认没有活动写入或合并租约。
2. 关闭桌面客户端，确认 sidecar 随窗口退出。
3. 备份应用数据库、配置和用户选择的 Run Workspace storage；不要只备份安装目录。
4. 核对新安装包 SHA-256 和数字签名，再运行覆盖安装。

同版本修复安装和卸载后重装已经验证会保留用户数据。真实旧版本到新版本的数据库迁移失败回滚尚未通过双安装包验证，因此当前工程包不能用于生产升级。

卸载默认只移除程序文件，保留应用数据和外置 Run Workspace。需要彻底删除时，应先在平台中导出允许保留的配置和记录，再由用户人工确认数据目录及各 storage root；不要把卸载程序的“保留数据”误认为已经释放项目副本占用空间。

## 19. 常见故障与诊断

- 客户端打不开：确认安装包签名与哈希，再检查是否被安全软件隔离；不要从未知来源下载 DLL 或关闭系统防护。
- 页面提示“需要激活”：重新导出当前设备申请，不要复用另一台电脑的许可证。
- 页面提示“只读”：核对许可证到期时间和系统时间；历史数据仍可查看，不要删除许可证状态强行绕过。
- CLI 无法启动：在系统终端执行对应 CLI 的版本/登录状态命令，修正 Profile 后恢复同一个 Run。
- Workspace 不可用或空间不足：恢复原磁盘，或在无活动租约时使用平台迁移；不要手工移动正在运行的 workspace。
- 合并冲突：保留当前 Run，处理源项目变化后重新预检；平台不会自动执行 Git rebase。
- 本地服务失败：完整退出客户端后重开。桌面 sidecar 应只监听随机 `127.0.0.1` 端口，不能占用或连接 8899。

提供诊断材料时，只提供平台允许导出的脱敏状态、错误码、版本、时间和相对文件引用。不要发送 API Key、Token、密码、`credentials.json`、许可证保护状态、原始 CLI JSONL、项目源码、绝对路径或完整数据库。

## 20. 当前发布边界

截至 2026-08-11，最终源码验证包括 804 项 Python 测试通过、5 项条件跳过、13 组/152 项非破坏性 reliability、Tauri Rust 测试 7/7、两轮干净构建和 Windows 11 本机安装生命周期。构建证据见 [Windows 构建记录](../test-records/windows-offline-beta-build-record.md)。

当前仍缺少 Authenticode、Windows 10/11 独立干净机和真实双版本迁移失败回滚，因此对外邀请制分发为 `NO-GO`。品牌与 15 天默认期限已经确认；版权主体信息、EULA 法律审阅和签名证书仍须在最终发布前完成。

## 21. 官网申请与邀请下载

正式官网提供两个互不干扰的入口：

1. “申请邀请码”会打开独立申请页。填写称呼、联系邮箱、职业或身份、使用场景、Windows 版本、计划使用的 API/CLI 模式和申请理由，确认隐私说明后提交。申请会先可靠写入官网申请数据库，再由服务器通过 QQ SMTP 自动通知运营者；通知暂时失败不会丢失申请，系统会自动重试。请勿在申请中填写 API Key、Token、密码、项目源码或完整日志。
2. “使用邀请码下载”进入独立下载页。用户输入发行者回复的有效邀请码后，服务器创建 10 分钟有效的受控下载链接，并按邀请策略记录下载次数。

SMTP 通知暂时不可用时，已经提交的申请仍会保存并等待自动重试；已有邀请码的下载入口也可正常使用。运营者在管理后台审核通过后，系统才生成可下载、可激活的邀请码，并自动发送到申请人邮箱；未审核申请不会自动获得邀请码。下载后在 PowerShell 运行 `Get-FileHash "安装包路径" -Algorithm SHA256`，把完整结果与下载页实时公示值逐字比对。签名状态也以下载页为准，SHA-256 不替代 Authenticode。

## 22. 设置中心与扩展能力

客户端左下角“设置”统一承载项目、服务商、通用、扩展和运维信息。未打开项目时工作台保持空白，并显示最近项目、新建项目和打开目录入口；加载项目后，工作台才显示该项目的轮次、角色和交付数据。

- **Agent**：查看六个内置专业 Agent，按需启用或停用。角色会根据当前任务和冻结策略自主发现并调用，不需要把 Agent 固定绑定到某个角色。子 Agent 使用独立 execution 和只读契约，主角色必须决定是否采纳结果。
- **Skill**：从本地目录导入包含 `SKILL.md` 的 Skill。导入后先处于隔离状态，必须由用户明确启用；新设置只进入下一轮，已经运行或恢复的 Run 不会改变。运行时先发现摘要，再按需加载正文，避免把所有 Skill 注入初始 Prompt。
- **MCP**：当前可导入并测试本机 `stdio` MCP Profile。导入后默认隔离，启用后只进入下一轮。HTTP MCP Profile 会明确显示当前版本不可用，不会伪装连接成功。MCP 命令、地址、本机路径和凭据不会在列表页回显。
- **Token 用量**：API 调用显示供应商实际返回的输入、输出和缓存数据；未报告的数据标记为未知。CLI 显示会话与耗时，CLI 未提供 Token 口径时显示“无法测量 Token”。Agent、Skill 和 MCP 使用可按能力维度追踪。
- **诊断**：显示本地服务、数据库、Provider 和扩展注册状态，并可重新读取或导出脱敏日志。若页面提示“客户端服务版本过旧”，需安装包含 `settings-v2` sidecar 的新客户端，而不是反复修改项目配置。

高风险 MCP 工具在当前版本中会被确定性阻断并提示需要用户确认；完整的界面审批后续跑流程尚未开放。因此邀请内测阶段只应启用来源可信、权限最小且可在测试项目中验证的 MCP，不要导入带安装钩子或未知执行逻辑的第三方扩展。