有解 Realize返回文档中心

有解 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 安装记录。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 构建记录。

当前仍缺少 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。