ZIAForge 用户指南

快速入门

ZIAForge 将讨论、规划、执行和验证整合在单个任务中。对于 Git 项目，请选择 Code；对于普通文件夹中的文档、研究及其他成果，请选择 Work。

建议先在单独的项目中从一个小型任务开始。如果选择原生 CLI，请先在终端中安装它并使用其自身账户登录。或者，配置 API 连接。CLI 订阅与付费 API 是相互独立的连接方式；ZIAForge 不会为您登录，也不会在二者之间转移积分额度。

1. 打开“设置”，检查工作区文件夹和语言。“关于”会显示当前运行构建的确切标识。
2. 对于 Code，在边栏中添加 Git 仓库。对于 Work，在创建任务时选择一个单独的文件夹。
3. 保存包含 CLI、模型、推理强度和访问级别的预设。您也可以直接选择“自定义”，而无需使用已保存的预设。
4. 创建任务，选择其路线、角色以及手动或自动推进方式。在点击“开始”之前复核所做的选择。

相关指令: 项目概览 · 提供方兼容性.

安装正确的桌面端安装包

选择适合您的操作系统和 CPU 架构的安装包：x64 或 arm64。构建流水线可生成 macOS DMG/ZIP、Windows NSIS 安装程序/ZIP 以及 Linux DEB/RPM/AppImage/tar.gz/ZIP 格式。生成的文件或交叉构建并不能证明其安装程序和原生 UI 在您的机器上通过了测试；请查阅该版本的验证记录。

使用 Electron 44 的 macOS 构建需要 macOS 13 或更高版本。在 Apple Silicon 上请使用 arm64 安装包，Intel 上请使用 x64 安装包。在替换前请完全退出旧版应用。预览版安装包可能未经签名且未公证；切勿将开发产物误认为已签名的公开发布版本。

Windows 需要打包的 Electron 版本支持的操作系统，并且 PATH 中包含可用的 Git。选择相匹配的架构。未签名的预览版不具备 Authenticode 认证。便携式 ZIP 必须保留完整的应用程序目录和运行时文件，而不能仅保留其可执行文件。

Linux 需要兼容的图形桌面、Electron 所需的系统库以及 Git。对于加密控制凭据，请提供可正常工作的 Secret Service（如 gnome-libsecret 或 KWallet）；不接受不安全的 basic_text 后端。无头/容器冒烟证据并不证明适用于所有桌面或发行版。

使用 apt install ./file.deb 安装 DEB，或通过您发行版的软件包管理器安装 RPM。AppImage 需要可执行权限以及合适的 FUSE 支持；在受支持的环境中，--appimage-extract-and-run 是一种替代方案。解压 tar.gz 和 ZIP 安装包时须保留其所有运行时文件。替换安装包时请将用户数据与应用程序文件区分开。

要从源码构建，请使用 Node 24、Git 和 npm ci（包括标准的 Electron 安装程序）。原生重新构建需要平台工具：macOS 上的 Xcode 命令行工具；Windows 上的 MSVC C++、Windows SDK 和 Python；Linux 上的编译器、make、Python、pkg-config 以及所需的打包工具。请遵循 PLATFORM_BUILDS.md 获取确切命令和当前平台限制。

发布版本由中央统一保留，其输出不可变。CI 验证构建不是已发布的安装程序。源码归档包含源码、lockfile、文档和脚本；排除依赖项、凭据、用户配置文件和私有研究。切勿从成功的 x64 构建推断原生 ARM 或 Windows 验证已通过。

相关指令: 平台安装包、先决条件和验证限制 · 构建标识与发布检查.

Code：五种路线

Auto 评估范围：简单的问题可能直接以答案结束，而较大的任务则需要准备。“修复 Bug”排查原因并准备修正方案。“规范优先”从技术方案入手；“需求优先”则从需求和验收标准入手。

多模型在探索、设计、实现和审查中使用独立的上下文。该路线名称并不要求使用不同的提供方：每个角色使用您选择的预设或“自定义”配置。

工作树隔离任务的 Git 更改。“分支”在选定的检出中工作。开始前请检查项目、分支和模型；任务描述不会同时发送至普通对话。

对于产品或技术选择尚未确定的构想，请使用“需求优先”并在讨论中打下基础。Auto 对请求进行分类；它并不是立即实现每个短句的指令。“保存草稿”保留请求而不联系模型；“开始”保存并启动一次受管流程。一到四个任务副本拥有独立的创建 ID 和角色设置。

相关指令: Code 工作流契约 · Code 提示词配置文件.

Forge 讨论

“开始”会打开中央讨论区。自然回复、提出反问、添加约束并讨论技术选择。对话和提问随任务一同保留。

发送文本并不代表接受文档或授权新的实现计划。执行过程中的澄清会先暂停受管轮次并重新审视受影响的范围。对已接受步骤内的提问进行回答可以继续该步骤。

要刻意重新审视基础，请选择“需求”、“规范”或“规划”。新版本需要重新接受依赖项决定。已完成的步骤及其凭据予以保留；被取代的未完成阶段保留在历史记录中。

受管阶段会话与自由对话不同。请使用 Forge 讨论，而不是直接向工作流专属的会话发送手动提示词。

相关指令: Forge 讨论契约.

文档与决定

打开文档、检查其版本并在需要时进行编辑。通过讨论提交编辑会生成新版本；报告和验证结果不会被追溯重写。

在接受提议的计划之前，编辑顺序、指令、验收标准和验证命令。请授权您理解的具体命令：它们在任务文件夹中运行。多模型提议一个贯穿全任务的实现步骤，详情包含在其文档和指令中。

“批准”是一项独立的刻意决定。Auto 不会绕过提问，也不会跳过对需求、规范和计划的接受。外部更改的文档无法复用旧的批准。

准备阶段的文件以产物形式呈现。它们的版本、生成阶段和哈希将其与结果绑定。Code 文档保存在工作树外部，不会自动进入提交。

接受前请同时检查文档和所显示的决定。接受操作会绑定当前关口 ID、计划修订版以及保留的文档哈希。当范围或凭据有误时，请“请求更改”。如果某项决定已失效，在做出新选择前请重新加载已保存的状态；发生更改的文件无法在较早版本下被接受。

相关指令: 工作流关口与文档版本.

执行与审查

待办事项显示实际步骤、当前尝试、验证和审查结果。智能体声称“完成”并不代表步骤已完成：必须存在计划所要求的凭据。

手动模式在符合条件的步骤之间暂停。Auto 推进已验证的步骤并允许受限重试。“在此后停止”始终会创建检查点。“暂停”会停止工作流的活动工作；关闭面板并不会停止它。

独立审查员使用包含文件和验证结果的独立上下文。必须解决所有要求的阻塞性发现；多个审查员无法通过投票消除阻塞性错误。

在多模型中，修正发现需要做出显式决定。修正不会静默启动另一轮审查：“再次审查”会开启一个新周期。审查意见可以请求协调员重新考虑，而无需重复实现。

已完成的步骤无法被静默编辑。在 TDD 中，Red 阶段必须确实因预期原因失败，随后 Green 阶段必须通过。受限尝试次数可防止无休止的重试。

在“设置 → 审查团队”中保存独立的 CLI/API 审查员，然后在 Code 或 Work 中选择该团队。审查员并行运行，随后由团队的报告架构师跟进。您也可以在没有已保存团队的情况下配置独立审查员。报告架构师仅接收匿名结构化报告，没有项目文件或工具；此隔离目前需要 Claude Code 或 API。

每个实现步骤都需要可执行检查、要求的独立审查，或两者兼备。准备阶段则保留经过验证的结果和产物凭据；这些凭据并不假装实现测试已运行。只有在确认实际退出状态和所属进程清理完毕后，命令才算成功。TDD 的 Red 检查在实现和 Green 验证前必须正常失败；缺失可执行文件或超时不是有效的 Red 结果。

默认熔断机制会在单个步骤失败三次或总计尝试五十次后停止。中断会消耗一次尝试，但其本身不算作失败的尝试。限制和已完成的凭据在重启后依然保留；“重试”不会重置它们。在授权下一次尝试之前，请阅读保留的失败信息。

相关指令: 验证与审查.

并行审查团队与报告架构师

打开“设置 → 审查团队”并保存团队。添加带有各自 CLI 或 API、模型、推理强度和专业化的独立审查员，然后选择报告架构师。在任务的审查配置中选择该团队。执行器预设也可以由审查员使用，“自定义”仍然可用；独立角色仍拥有独立的上下文。

审查员基于相同的任务凭据并行运行。每份要求的报告、错误和裁决均予以保留。架构师接收匿名的编号报告，其中不包含审查员名称、模型或提供方标识、原始任务内容、仓库访问权限或工具。它比对报告并返回一份结构化裁决；它不执行新的源码审查。

阻塞性发现或必要审查员的拒绝不能通过多数票或架构师偏好予以豁免。缺失或格式错误的报告将阻止批准。在接受或授权修正之前，请检查各个发现和汇总决定。已保存的团队在运行期间解析并冻结；编辑其预设不会重写已完成的凭据。

仅限报告的架构师目前使用受支持的 Claude 或 API 无工具配置。Codex 和 Antigravity 仍可作为审查员使用，但在存在经核实的无工具契约之前，拒绝用于此隔离的架构师角色。仅在提示词中写明“无工具”是不够的。

相关指令: 类型化团队配置 · 审查汇总.

智能体专业化与提示词策略

模型是执行引擎；专业化是指令配置文件。选择“无”表示不添加专业化，“标准”表示默认指南，Auto 表示相关的内置指南，或“手动”表示选定的指南和您自己的受限指令。预设可保留该选择。

原始目录涵盖通用编程、架构、安全、可靠性、性能、测试以及界面可用性。Auto 使用可用的任务/步骤文本选择指南；它不会暗中调用其他模型或证明专业能力。在接受实现计划之前，可以检查和更改规划建议。

审查专业化有助于引导关注重点，但绝不能替代独立凭据、访问限制或结构化裁决。将自定义指令视为任务范围的一部分：切勿使用它们绕过文档接受、工具策略、身份验证或审查员未通过判定。

相关指令: 原始提示词目录.

Work：从问题到文档

Work 不需要 Git。“默认”会创建一个单独的任务文件夹；“自定义”通过原生选择器选择已有文件夹。“保存草稿”无需推理即可存储设置；“开始”运行第一阶段。

Auto 直接回答或提议包含实际待办事项的合适计划。“头脑风暴”在您选择更多构想或评估之前创建 ideas.md。“研究”保留 findings.md、来源和局限性。“撰写”从意图出发，并在有用时通过 outline.md 生成描述性文档或 draft.md；修订会保留之前的版本。

通过原生选择器选取文件输入，并使用 @ 进行引用。应用会将它们复制为不可变的任务输入，并在运行前验证其一致性。“默认”会创建应用所有的任务文件夹；“自定义”文件夹访问权限是已保存的所有者授权。已保存且未启动的草稿可以更改其文件夹。

创建 1–4 个具有独立执行器设置的副本。使用重叠文件夹的任务无法并发写入。此协调仅适用于 ZIAForge 操作，不适用于任意外部程序。

“深度头脑风暴”默认使用三个独立工作节点，最多支持八个。选择它们的顺序和配置，包括在不同上下文中复用预设。工作节点提出的问题保留其来源；格式错误的报告有一次格式修复尝试。部分失败保持可见，而不是呈现为全员成功。

“深度”将保留的工作节点报告整合到 brainstorm_report.md 中，并始终请求用户做出决定。微调跟进会通过协调员修订报告；重大更改会启动冻结工作节点的下一轮运行。产物保留其版本。

解析后的角色在任务创建或显式保存草稿时冻结。在首次调用后，仅可更改自动/手动推进设置；若要使用不同的角色或模型设置，请创建新任务。编辑全局预设不会静默更改后续阶段。

手动模式在符合条件的阶段之间暂停，包括实质性的“撰写”大纲。Auto 可以继续推进该大纲。即使在 Auto 下，提问、提议的可执行计划、“头脑风暴”方向以及“深度”报告审查仍属于显式决定。仅有引用并不证明实际进行了浏览，仅保留二进制文件并不证明其渲染成功。

相关指令: Work 模式与决定.

预设、模型与访问权限

预设用于保存 CLI/API、模型、推理强度和权限。对话页脚包含预设、CLI、模型和选项分段。“自定义”无需预设即可工作；“创建预设”用于保存当前选择。

目录来自所选已安装的 CLI 或受支持的 API。“刷新”会更新列表而不更改当前选择。如果发现功能不可用，请输入显式模型 ID；提供方仍必须支持它。推理级别取决于模型和 CLI。“提供方默认”不同于显式的 none 标记。

仅在后端确认后才应用更改。在活动轮次或队列非空期间限制切换。草稿和可见历史记录会保留，但更换提供方不会转移其私有内部状态。

在 Forge 中，角色标签很重要：准备工作可以使用独立的规划员。页脚可更改显示的角色；审查员和助手在工作流设置中选择。已验证实现的策略可能会被锁定。

各提供方的权限有所不同。“只读”和“工作区写入”在适配器支持时可用。Antigravity 使用原生 CLI 设置或显式选择的完全访问权限。完全访问权限并不是沙箱。

专业化增加提示词指导，而不是另一个模型或权限。预设和角色支持“无”、“标准”、Auto 和“手动”。Auto 根据步骤文本选择配置文件，无需额外的模型调用；“手动”最多可接受四个专长和自定义指令。规划员提议的分配可以在接受计划前进行编辑。

手动输入的模型 ID 或强度仍由您决定，但提供方可能会拒绝。编辑全局预设不会追溯更改正在运行的对话或已接受的计划。若要刻意更改处于空闲状态的对话，请使用其自身的配置控件并等待确认。禁用的选项应理解为功能或生命周期限制，切勿通过编辑已保存的 JSON 来绕过。

相关指令: 提供方能力.

对话、“停止”与队列

打开的标签页、“最近”和草稿均属于同一个任务。关闭标签页会将其从“打开”中移除，但仍保留在“最近”中，且不会停止其提供方进程或受管工作流。可以从历史记录菜单搜索历史记录、重新打开对话或关闭所有附加标签页。

“停止”会中断当前轮次。在进行下一次“发送”前请等待停止完成：中断确认并不代表进程已结束。在此期间您可以输入下一份草稿。

在普通对话中，“加入队列”将后续请求与当前草稿分开保存。“暂停队列”会暂缓后续交付。“停止”和“退出”会暂停队列。重启后，先“恢复”，然后再显式“继续队列”。

“不确定”表示交付状态未知。此类消息不会自动重发：请检查历史记录，适当时复制文本并忽略该排队项。再次发送属于一次新的刻意请求。

受管阶段对话使用其工作流，而非普通队列。“跟随阶段”显示当前阶段；手动选择另一个标签页将停止跟随。CLI 日志与回复分开显示诊断信息。

Markdown 回复可渲染标题、列表、表格、链接及围栏代码块。工具卡片和 CLI 诊断信息与回答保持分离。模型报告的思考过程和令牌指标仅在提供方实际公开时才会显示；请勿根据动画推断私有推理或用量。

在遇到不确定的发送或队列确认后，请检查历史记录，并且仅在提供选项时重试同一个保留的请求。队列凭据仅表示存储已接收该项目，并不代表推理已完成。仅可将移除不确定排队项作为显式忽略操作；它无法撤回已交付的提示词。

相关指令: 持久消息队列.

文件、Git 与完成

“文件”显示任务文件夹。将结果与需求进行比对、打开文档并检查差异。保留二进制文件并不证明其在目标应用程序中能正确渲染。

Git 提供状态、更改以及记录有结果的操作。提交、合并和推送默认均为手动；自动操作是针对完全验证的计划的独立选择。

在验证和发布之间请勿更改工作文件：批准与精确的字节绑定。冲突、推送失败和未知的操作结果会阻塞进度，直到做出显式决定。Auto 不会静默授权发布。

Work 不创建 Git 分支，也没有 Git 定稿流程。请从选定文件夹中保留所需文档，包括版本和来源。

文件编辑器提供按扩展名高亮语法、查找与替换、撤销历史记录、自动换行以及按标签页保存草稿功能。保存操作会保留受支持的 UTF-8/UTF-16 编码，并拒绝外部修改冲突。其他编码和二进制内容需要外部编辑器。未保存的草稿将阻止应用程序“退出”，直到所有者保存或放弃它们。

高达 8 MiB 的文件可启用完整语法高亮。更大的文本文件以 256 KiB 窗口打开；8–64 MiB 可以显式完整加载而不带语法高亮。超过 64 MiB 则使用窗口编辑和有界的“下一处匹配”搜索。这是一种有限的大文件模式，并非针对任意大文档达到 Sublime Text 的同等水准。

“打开文件夹”使用当前任务或分支/工作树上下文，而不是静默地仅打开原始仓库。文件行可以显示该文件的父目录。后端会根据已注册的任务授权验证路径。二进制文件无法作为纯文本编辑；请使用其目标查看器并保留原始字节。

移除工作树是一项独立的受保护操作。在移除它之前，请结束关联的结构化会话和终端，包括处于空闲状态的会话。检查已保存的 Git 结果和恢复状态；删除任务记录不能替代安全保留未提交的工作。

相关指令: 类型化编辑器契约 · Git 策略.

API 连接

“连接”可添加显式选定的兼容 OpenAI 的端点。输入名称、基本 URL、模型以及所需的密钥。许多服务器要求基本 URL 以 /v1 结尾；请查阅您的端点文档。

除环回 HTTP 外，必须使用 HTTPS。请使用未在 URL 中嵌入凭据的纯端点。密钥使用受支持的 OS 加密且不会返回给 UI。更改端点需要重新输入其密钥。将密钥字段留空会保留已保存的密钥；“移除已保存密钥”会显式清除它。

API 调用不使用 CLI 订阅。工具和模型与原生会话不同，成功的模型发现并不证明能正常推理。仅当提供方实际返回时才会显示令牌用量。

请将凭据保留在“连接”中，而非任务正文或预设指令中。只读审查员仅接收其获准的 API 文件工具；报告架构师没有工具。不受支持的工具调用将被拒绝而非静默执行。各服务器在推理参数、工具支持和模型列表方面存在差异；请将错误与您端点自身的契约进行比对。

相关指令: API 连接.

设置、语言与安全重置

常规设置可选择工作区、界面语言和默认值。“连接”用于管理 API 端点。“预设”与“审查团队”保留角色配置。“远程控制”管理本地凭据、服务器范围和所有者权限；“更新”管理发布源/通道。“关于”显示正在运行的具体构建。

界面语言与提示词语言以及文档审阅状态相互独立。产品名称、命令 ID、文件扩展名、提供商模型 ID 和用户创建的名称仍保留为标识符。当当前翻译可用时，帮助会采用所选的界面语言；机器翻译会予以标注，而英语始终是权威参考。

“保存”会应用所显示的配置。数据库重置或恢复出厂设置可能会移除应用程序元数据；在特意使用重置之前，请保留文件并准备经过测试的备份。这些操作属于本地所有者行为。请勿将它们用作调查失败工作流或损坏记录的捷径。

相关指令: 本地化说明 · 数据恢复.

咨询帮助助手

打开“帮助”，在其助手面板中选择已保存的已连接预设，然后咨询有关 ZIAForge 的问题。回答会使用当前的权威英文指南以及您所选的界面语言。章节引用按钮可打开相关的指南主题，以便您将解释与参考内容进行对比。

该助手保留单独的私密对话，最多可保存 100 条记录和 3 MiB。输入最多 12,000 个字符的问题；“发送”会提交问题，“停止”会取消当前的回答并保留您的问题，而“清除”会移除此帮助对话。在同一应用会话中关闭或重新打开“帮助”后，您未发送的草稿和预设选择仍会保留，但草稿不会保存到磁盘。该助手不会发送应用程序命令、更改工作流或批准门限。其建议并非对任务、账户或外部连接的实时验证。

Claude Code 和 API 帮助会话会强制执行受支持的无工具策略。原生 Codex 和 Antigravity 帮助会话需要现有的本地所有者原生计算机权限。若该权限被禁用，应用程序会解释该前置条件，而不是另选其他提供商。只有所有者才能在本地控制设置中启用它；助手自身无法启用它。

Codex 帮助使用只读沙箱并拒绝工具审批请求。Antigravity 使用计划模式及其原生沙箱标志。这些原生模式并不能全面保证操作系统级的隔离限制。源指南哈希标识了回答所使用的参考内容；生成的解释仍可能存在错误，因此在采取行动前请检查其链接的章节。当早期回答所依据的源指南版本与当前指南不同时，会予以标记。

相关指令: 权威指南与翻译维护 · 应用程序助手与权限.

助手与 Telegram

助手使用所选预设和相同的应用程序控制 API。检查状态的权限与执行操作的权限相互独立。请检查命令与结果：助手的文字陈述并不能作为操作已完成的凭据。

Telegram 仅可由本地所有者启用，且需要现有的机器人令牌和数字所有者 ID。控制权限仅限该所有者的私聊。未配置或未激活的机器人绝不能接收应用程序消息。

切勿将机器人令牌粘贴到普通聊天中。配置此集成并不证明 Telegram 具有连通性，也不会自动创建机器人。屏幕截图和回复可能包含私密工作区数据。

选择助手预设，并将应用程序操作权限与检查权限分开授予。Codex 和 Antigravity 助手的执行需要所有者的原生权限；系统不会将其静默替换为无工具的 API 或 Claude 会话。屏幕截图可在助手对话中显示，但当前的模型输入不包含图像分析。切勿仅因为助手显示了图像就假定其已在视觉上检查了该图像。

助手可以通过类型化工具检查摘要、任务、聊天、工作流状态、进程上下文和应用程序窗口。它可以更改允许的常规设置并启动授权的应用程序操作。它不能授予原生权限、泄露存储的凭据、远程更改根工作区授权，或者仅仅为了方便而批准 Forge 门限。

相关指令: 应用程序控制契约.

操作您的私有 Telegram 机器人

创建或获取您自己的机器人，开启其私聊，并在本地控制设置中输入其令牌以及您的数字 Telegram 用户 ID。仅在您打算让应用程序进行连接时才启用该集成。所有者 ID 是用户标识符，而非用户名或机器人 ID。系统仅接受该用户在同一私聊中发送的消息。

使用 /start、/menu 或 /status 可以查看运行版本、项目/任务计数以及任务状态的概览。按钮可打开“项目”、“任务”、“屏幕截图”、“帮助”和“语言”。列表每页显示八项，并带有“返回”、“刷新”、“主页”以及“上一页/下一页”导航。项目按钮可筛选任务列表。任务卡片会显示其保存的工作流进度、模型/预设以及待处理的问题（若存在）。

打开任务的“聊天”可预览已打开/近期的对话以及工作流阶段聊天。每个预览最多显示六条最新的用户/助手消息，并明显截短至每条 200 个字符。私密推理内容不会显示。读取历史记录不会启动提供商。预览为只读模式：普通文本和 /ask TEXT 仍面向应用程序助手，绝不会隐式定向到您当前正在查看的任务聊天。

“运行 / 继续”会重新读取当前 Code 或 Work 工作流，并启动符合条件的已保存工作流。“暂停”会请求其暂停。两者均不接受需求、规范、计划、审查结果或问题；待决决策会阻止“运行”。请在应用程序中做出决策，或使用带有其确切当前门限和修订版本的明确授权类型化命令。

使用“语言”或 /language 可按其原生名称选择 56 种界面语言中的任意一种。这仅会持久保存该机器人及所有者的偏好设置。“使用应用语言”会清除该偏好设置。它既不会更改应用程序的语言，也不会更改访问权限；现有消息不会自动重发。

导航通常会更新同一条已发布的菜单消息。按钮具有不透明标识，在 15 分钟后失效且仅可使用一次；更改卡片会使其旧按钮失效。已失效、已使用、消息不匹配以及上一进程的按钮无法执行操作。明确不可编辑的消息可替换为新卡片；未知的网络错误不会作为新消息重试。

激活时，轮询器会丢弃早期的积压消息，并在分派前记录更新接收状态，从而使中断的命令在重启时不会自动重放。这可以防止重放，但不能保证完成。出错后特意下发新工作之前，请先检查状态/上下文。系统不会发送自动任务状态通知。

明确命令依然可用：/projects、/tasks、/task TASK_ID、/run TASK_ID、/pause TASK_ID、/screenshot 以及 /ask TEXT。/new {JSON} 通过类型化 createTask 创建任务；/command {JSON} 发送明确的目录命令。有关参数结构，请查阅实时目录。此处适用与应用程序中相同的后端授权和文件夹授权。

应用程序绝不会将存储的机器人令牌值发送给助手。然而，屏幕截图、摘要和对话文本仍可能包含私密项目信息。如果机器人或所有者账户不再受信任，请在本地停止该集成。若令牌泄露，请在机器人提供商处轮换令牌，然后更新其本地加密配置。

相关指令: 私有机器人与命令.

仅限所有者的原生计算机权限

原生计算机访问初始处于禁用状态。只有所有者才能在本地“设置”→“远程控制”中启用它。助手和 HTTP/MCP/Telegram 命令无法自行启用此标志。如果某项操作被拒绝，助手应当说明该设置并由所有者自行决定。

明确启用后，computer.run 接受可执行文件、参数数组和可选的绝对工作目录。它不使用 shell 插值，具有 30 秒限制，并将输出限制在 1 MiB 内。若提供的目录不存在或无效，请求将被拒绝；若省略 cwd，则使用应用程序拥有的设置目录，而非 HOME。“退出”会取消正在活动的自有命令并等待其进程清理。

应用程序读取/操作范围与原生访问属于独立的决策。工作树并不能限制无约束提供商的文件系统访问。任务完成后若不再需要原生访问，请将其撤销，并检查命令回执，而不是将助手的文字叙述作为凭据。

相关指令: 仅限所有者控制契约.

浏览器与远程实例

本地所有者启用服务器并选择其地址、端口和范围：用于检查的 read（读取）或用于操作的 operate（操作）。默认地址 127.0.0.1 仅在此计算机上可用。0.0.0.0 会监听网络接口；在启用前请审查网络访问权限。

通过令牌登录后，浏览器会打开相同的界面。切勿在公开链接或屏幕截图中包含令牌。单凭 HTTP 并不能加密流量；在不可信网络上请使用受保护的信道。

所有者通过 URL 和令牌配置其他实例。后端会代理请求；这不会将这些实例的项目复制到本地计算机上。每次操作前请先检查所选的实例。

类型化命令和事件承载应用程序控制。读取范围不授权任务修改。原生计算机控制是独立的本地所有者选项，初始处于禁用状态。

应用程序必须保持运行才能支持浏览器、Telegram 和外部代理控制。每个实例都有其专有的私有配置文件、任务状态、令牌和服务器端口。切勿在独立实例之间并发复用同一个配置文件。浏览器事件和命令响应的作用域限定在所选实例内；切换 UI 不会移动文件或复制原生登录状态。

相关指令: HTTP 与实例控制.

OpenClaw、Hermes 及其他外部代理

使用经过身份验证的应用程序控制 API 或捆绑的 MCP stdio 桥接器。在本地启用服务器，选择 read（读取）或 operate（操作），并使用该实例的 URL 和令牌配置每个客户端。运行独立的 MCP 桥接器需要 Node.js 22 或更高版本；Electron 应用程序不会安装您的代理客户端。浏览器 URL 不是 Streamable HTTP MCP 端点：请将其作为 ZIAFORGE_URL 提供给 stdio 桥接器。

该桥接器公开了 ziaforge_status、ziaforge_commands、ziaforge_command 和 ziaforge_screenshot。先从状态和实时命令目录开始，然后读取所选任务的 system.context。类型化命令遵循与本地 UI 相同的修订版本、门限、任务文件夹和清理检查。

实时命令目录包括 documentation.guide，即权威英文帮助，及其源路径和 sourceSha256。内部应用程序架构师通过其工具接收相同的参考内容。这为代理提供了完整的产品上下文，而无需依赖过时的笔记；文档绝不授予访问权限，也不能替代当下的人工作出决策。

代理应当根据人类简短的想法讨论需求、技术决策和规划。它们必须保留明确的人工门限、所选模型、手动/Auto 策略以及必需的审查。它们绝不能捏造审批、在新的 ID 下重放不确定的命令，或在违背所有者意图的情况下发布 Git 更改。

为多个安装配置多个具名的 MCP 服务器。实例切换属于路由决策，而非同步操作。OpenClaw 和 Hermes 的配置示例位于 AGENT_CONTROL.md 中；必须针对所安装的客户端版本检查特定客户端的设置和兼容性。

外部 requestId 缓存仅在应用程序运行期间对有限数量的请求进行去重。持久化操作使用各自的标识：用于任务创建的 createRequestId、用于工作流决策的 commandId、用于消息的 clientMessageId 以及用于 operationId 的 Git 变更。收到未知确认后，请保留原始标识和有效载荷；在特意下发新工作之前，请先读取已保存的状态。

相关指令: MCP 客户端说明.

本地 CLI 与自动化限制

ziaf 分派器控制着同一个运行中的应用程序和已保存的工作流。从源码构建时，使用 npm run ziaf -- list、npm run ziaf -- status --task TASK_ID --json、npm run ziaf -- start --task TASK_ID 或 npm run ziaf -- pause --task TASK_ID。成功的“启动”确认并不意味着任务已完成。

--until-success 会专门为已保存的工作流启用 Auto，但问题、审查、验收门限、限制和检查点依然适用。Ctrl+C 会退出正在观察的分派器；它不会隐式停止应用程序工作流。有关退出代码、本地端点和配置文件处理，请参见 CLI.md。

“自动化”界面目前仅存储显示定义和本地运行计数器。它不是经过认证的定期调度程序，也不能证明后台模型轮次已运行。若要实际执行，请使用已保存的工作流控件、ziaf 或经过身份验证的 API，并检查其回执。切勿将演示面板误认为是无人值守的调度系统。

相关指令: 分派器命令.

版本与更新

“关于”显示当前运行的确切版本。公开更新需要受信任的 GitHub 发布仓库以及稳定（stable）或预览（preview）通道。检查、下载和安装具有各自独立的状态；出现错误并不意味着更新已安装。

自动安装仅适用于已签名的 macOS 发布版本。未签名的开发构建版不会通过此机制自动安装。如需手动替换，请彻底退出当前应用程序并使用经过验证的产物。

启用后，自动检查会立即运行，随后每六小时运行一次。

稳定通道不包含预览版本；预览通道也允许开发版本。成功的检查仅确定可用的发布元数据。下载和安装需要对应的平台软件包和配置的发布源。Linux DEB 分发属于独立的安装程序路径；切勿假定 DEB 会通过 macOS 更新机制自动升级。

相关指令: 发布准备情况.

重启与恢复

在 macOS 上，使用“退出”/ ⌘Q 进行完全关闭。关闭窗口可能会使应用程序仍在后台运行。替换应用程序之前，请彻底退出旧版本。

启动后，选择同一个任务。历史记录和草稿将会恢复。“恢复”会还原原生/本地上下文，但不会发送草稿、取消队列暂停，也不会授权重复执行未知操作。

如果出现“恢复”，请勿手动编辑 JSON。检查受影响的文档类型，保留原始文件，并选择经过验证的备份。恢复较旧的队列会将其条目标记为不确定。

当传递情况未知时，托管工作流可能需要明确的权限以建立全新上下文。早期的工作和失败的尝试仍会保留；明确可见的拒绝比捏造的成功更安全。

请在所有应用实例关闭的情况下备份任务文件和应用配置文件。复制的文件夹并不是经过测试的还原方案。如果恢复过程要求您选择经过验证的备份，也请保留确切受损的文件。恢复较旧的工作流或队列并不会授权重放不确定的推理或 Git 操作。

相关指令: 恢复契约.

故障排除

未找到 CLI：请在普通终端中检查其安装情况和版本，然后重启 ZIAForge。可执行文件存在并不意味着您已登录。请使用提供商自己的登录机制。

模型不可用或授权失败：请刷新发现列表，选择一个可用的 ID 并检查您的账户与限额。在检查其历史记录之前，请勿重复发送不确定的请求。

工作流已停止：打开当前阶段、问题、验证回执或 CLI 日志。解决具体原因：未回答的问题、命令、文件夹权限或尝试次数限制。“继续”无法将失败的检查变成成功。

文件夹丢失或被替换：请恢复对原始文件夹的访问权限或创建新任务。应用程序绝不能从 HOME 继续执行。如果您观察到其他 cwd，请停止当前轮次并保留诊断信息。

提交报告时，请附上“关于”中的版本、路由、CLI/模型、预期行为与实际行为、屏幕截图以及安全的日志摘录。请移除机密信息、个人内容以及不可公开的路径。

远程页面不可用：请确认所有者已启用服务器，检查监听地址和端口，然后使用正确的实例令牌进行身份验证。401 表示身份验证问题；被拒绝的修改可能属于读取范围限制或仅限所有者的控制。更改令牌会关闭现有的浏览器客户端。切勿将独立的 DevTools 检查端口暴露为远程应用程序控制。

编辑器保存被拒：请保留草稿，检查磁盘上的当前文件，并解决外部更改冲突。切勿通过重写应用程序元数据来绕过对比。如果大文件完整加载不可用，请使用受支持的窗口化编辑/搜索或外部编辑器。

Telegram 不可用：请在本地确认机器人令牌、数字所有者、私聊和状态。竞争的 webhook 或轮询器可能会阻塞轮询；ZIAForge 不会自动删除 webhook 或接管其他轮询器。在未知边界被拒绝或中断的命令不会自动重放。

相关指令: 测试与诊断.

报告问题与检查证据

记录“关于”中的确切运行构建版本、OS/架构、任务模式、所选提供商/模型以及重现该问题的步骤。描述预期结果与观察到的结果。附上安全的屏幕截图以及相关的保留命令或验证回执，而不是整个私有配置文件。

CLI 日志、事件日志记录、模型对话记录、浏览器跟踪和屏幕截图可能会暴露源码、个人路径或令牌。分享前请先进行检查并脱敏。尽力而为的日志脱敏器并不能证明屏幕截图或归档文件可以直接发布。

对于贡献者，qa:doctor 用于读取环境/构建标识；qa:inspect 会打开带有提供商桩模块的隔离配置文件。测试夹具（fixture）可以在不联系模型的情况下验证被测应用程序路径。实时推理、Telegram 连通性、原生 Linux 桌面、签名和打包产物检查属于各自独立的证据。有关可重现的命令和清理操作，请参见 TESTING.md。

相关指令: 证据命令.

本地数据与边界

项目、历史记录、计划、文档和诊断信息可能包含私密文本。切勿将配置文件、原始抓取数据、密钥或带有源代码的完整日志公开发布。

在 Linux 上，保存 API、控制、Telegram 和实例凭据需要解锁的 GNOME Secret Service 或 KWallet；在没有受支持的密钥存储区的情况下，ZIAForge 会拒绝保存这些机密，而不是使用 Electron 的 basic_text 回退方案。

本地存储并不意味着请求会留在您的计算机上：所选的 CLI/API 会将请求发送至其提供商。工作文件夹和进程监管并不等同于 OS 隔离。请检查所选权限。

区分证据类型：夹具在没有模型的情况下测试应用程序；原生实测演练真实的 CLI/账户；打包检查验证特定的产物。通过其中一项并不保证其他各项也能通过。

应用程序作用域、工作树和只读提示词不同于操作系统级的强制执行。Antigravity 审查者/辅助者策略是通过检测收集到的工作区证据中的更改，而非强制实施文件系统只读访问。原生计算机控制会在常规应用工具边界之外执行经所有者授权的程序；在不再需要时请将其关闭。

相关指令: 出处与发布.

理解并修改此开源项目

请先阅读 AGENTS.md 和 CONTRIBUTING.md，然后查阅 PROJECT_MAP.md 了解当前的源码边界。已实现的类型化契约以及当前的工作流/提供商文档决定了系统行为。CONCEPT.md 和 ARCHITECTURE.md 中终端优先的部分保留了历史设计意图，绝不能误认为是当前发布版本的说明。

英文帮助源文件为 docs/help/en.json。切勿手动编辑生成的 USER_GUIDE.md 或 website/guide.html。请修改权威章节，更新受影响的契约，并运行 node scripts/help/generate.cjs。应用内“帮助”读取的是相同的源文件。请对照实际实现审查新增内容，包括限制、权限和不受支持的路径。

在 docs/help/locales.json 中，56 种界面语言区域中的每一种都具有独立的帮助状态。缺失或不完整的帮助会回退到英语。完整的机器翻译正文会被予以标注并与英文源哈希绑定，不声明经过人工审阅。经过人工审阅的翻译还会额外记录其审阅者。所有翻译都必须保留章节 ID、操作、文件/命令标识符和技术限制，使用正确的文本方向，并在英文源发生更改时予以刷新。

在交付发布之前，请运行 node scripts/help/generate.cjs --check 以检测过期的生成输出、无效的语言区域脚手架或损坏的本地契约链接。UI 翻译检查与应用程序行为检查相互独立。HELP_MAINTENANCE.md 提供了贡献者和 AI 更新流程；文档绝不能声称通过了未实际运行的测试。

相关指令: 当前项目图谱 · 文档维护 · 贡献者说明 · 代理说明.