CaoGen

CaoGen Docs

产品操作手册

从安装和 Provider 配置，到项目会话、模型路由、工具、权限与交付。

当前文档 v0.1.5 Beta · 2026-07-14
手册目录

本手册适用于 CaoGen v0.1.5 Beta，发布日期 2026-07-14。安装包、校验值和临时限制可能随 Release 更新，请以 GitHub Releases 为准。

1. 使用范围与版本#

CaoGen 是本地运行的多厂商 AI 工作桌面。它把项目、会话、模型路由、文件、终端、Diff、Git、浏览器批注、插件、记忆和 3D Agent 控制室放在同一个工作区。

当前 v0.1.5 的公开资产包括：

平台 公开资产 状态
macOS Intel CaoGen-0.1.5.dmg、CaoGen-0.1.5-mac.zip 已发布，未签名、未公证
Windows x64 CaoGen.Setup.0.1.5.exe 已发布，未进行 Authenticode 签名
macOS Apple Silicon 本版没有原生 arm64 安装包 可查看历史版本，兼容性以对应 Release 为准
Linux 本版没有公开安装资产 可从源码运行或自行构建

不要从第三方网盘或聊天附件下载安装包。官方下载入口只有 CaoGen GitHub Release。

2. 下载与安装#

macOS Intel#

  1. 打开 v0.1.5 Release，下载 DMG 或 ZIP。
  2. 可先校验文件摘要：
shasum -a 256 CaoGen-0.1.5.dmg
  1. DMG 用户把 CaoGen 拖入“应用程序”；ZIP 用户解压后把应用放入“应用程序”。
  2. 当前应用未签名。第一次启动时，在 Finder 中右键 CaoGen，选择“打开”，再在系统提示中确认“打开”。
  3. 如果仍被拦截，打开“系统设置 → 隐私与安全性”，在对应提示下选择“仍要打开”。

Windows x64#

  1. 从同一个 Release 下载 CaoGen.Setup.0.1.5.exe。
  2. 使用 PowerShell 校验摘要，并与 Release 页面公布的 SHA256 对照：
Get-FileHash .\CaoGen.Setup.0.1.5.exe -Algorithm SHA256
  1. 当前安装程序没有 Authenticode 签名，SmartScreen 可能显示“未知发布者”。确认文件来源和 SHA256 后再运行。

不要为了安装 CaoGen 关闭系统整体安全防护。只对已经核对来源和摘要的当前安装包执行单次放行。

3. 第一次配置 Provider#

CaoGen 不要求绑定单一厂商。开始会话前，至少配置一个带 API Key 和模型列表的 Provider。

  1. 打开 CaoGen 左下角的“设置”。
  2. 在设置侧栏选择“厂商”。
  3. 点击“添加”。
  4. 选择执行引擎：
    • OpenAI-compatible：适合 OpenAI Responses、Chat Completions、DeepSeek、Qwen、兼容网关和自部署服务。
    • Claude Agent SDK：适合 Claude 原生执行路径；接入其他模型时，需要对应的 Anthropic 兼容网关。
  5. 选择快速模板，或填写名称、Base URL 和主 API Key。
  6. OpenAI-compatible 引擎需要选择协议：
    • Responses：OpenAI 原生 Responses API。
    • Chat Completions：通用兼容协议，常用于国产模型、网关和本地服务。
  7. 点击“用密钥获取”拉取模型列表；如果厂商不支持模型发现，也可以每行手工填写一个模型 ID。
  8. 保存后回到厂商列表，点击“检测”。页面显示可达、模型数量和延迟后再创建会话。

API Key 保存后不会在界面中回显明文。系统安全存储可用时，CaoGen 使用 Electron safeStorage 加密保存；不可用时当前版本仍有可逆编码回退，因此不要把它当作所有环境中的硬件级密钥保险箱。建议使用专用、限额、可撤销的 Key。

添加备用 API Key#

Provider 编辑页支持同一 Provider 保存多个 Key。新增备用 Key 时，每行写一个：

主账号=sk-...
备用额度=sk-...

鉴权、额度或限流失败时，CaoGen 可以先尝试同 Provider 的可用备用 Key。保存后界面只显示名称、状态和最近使用信息。

4. 创建项目和会话#

点击侧栏“新建会话”，或在某个项目分组右侧点击“+”。新会话入口会同时完成项目归属、模型路径和权限选择。

  1. 选择已有项目，或者选择“新项目目录”并浏览到本地目录。
  2. 不希望归入项目时，可以选择“未关联项目的会话”。
  3. 输入第一条任务说明。
  4. 选择调度范围、CaoGen Drive 档位和权限模式。
  5. 点击发送，或在输入法没有组合输入时按 Enter；Shift + Enter 用于换行。

推荐第一次使用只让 Agent 阅读，不立即修改：

帮我阅读这个项目，指出最重要的入口文件、启动方式和当前最值得修的 3 个问题。先不要修改文件。

侧栏会按项目收纳会话。项目分组中的“+”会直接以该项目为上下文创建新会话；没有项目归属的会话进入独立集合。

5. 三种调度范围#

调度范围在会话创建前确定：

范围 你需要选择 行为
指定模型 Provider + 模型 整个会话优先使用明确指定的模型
厂商内自动 Provider 只在该 Provider 的可用模型中自动选择
跨厂商自动 无需预先固定 Provider 在所有已配置且可用的 Provider 中选择厂商和模型

自动路由会识别调研、策划、开发、测试和文档任务，并结合模型角色映射、策略、预算、健康状态和项目规则作出选择。

跨厂商选择发生在创建会话前。会话运行后，只会在兼容当前执行引擎的 Provider 之间切换，以避免破坏原生上下文。它不意味着任意 Provider、协议和模型可以无条件热切换。

6. 使用工作桌面#

会话开始后，中央时间线显示 Agent 的回复、工具调用、权限请求和执行结果。常用入口位于工作桌面工具区：

文件#

  • 浏览和搜索当前会话目录中的文件。
  • 打开文本、Markdown、JSON、CSV、图片、PDF 和部分 Office 文档。
  • 保存操作写入当前会话目录；使用隔离 worktree 时写入隔离副本。

Diff 与 Git#

  • 使用“工作区 Diff”查看当前改动。
  • 可以逐 hunk 检查、暂存或放弃改动。
  • 隔离 worktree 支持检查合并、导出 Patch、应用到主工作区和查看冲突文件。
  • 创建提交、推送或 PR/MR 前，检查目标仓库、分支和最终 Diff。

终端#

  • 打开当前会话目录的内置终端。
  • 终端命令直接在本机执行，不是容器或系统级沙箱。
  • 运行测试、构建或迁移命令前，先确认目录和参数。

浏览器#

  • 输入 URL 打开内置浏览器。
  • 可以保存文本或页面区域批注、圈选元素，并把观测发送给 Agent。
  • 登录态、页面内容和第三方网站仍属于外部系统，不会因为在 CaoGen 内打开就变成受控测试环境。

停止、恢复与回溯#

  • 任务运行时可以点击“停止”。
  • 历史会话可以从侧栏恢复。
  • 输入 /rewind 或使用 Esc Esc 打开最近检查点回溯面板。
  • 回溯前先预览范围，再选择只恢复代码、只恢复对话或同时恢复。

7. 权限与安全边界#

新会话会显示权限模式。敏感工具调用可能暂停任务并请求授权。

  • 仔细阅读工具名称、目标路径、命令和风险等级。
  • 不确定时选择拒绝，让 Agent 解释目的或改用只读方案。
  • GUI 自动化默认关闭；启用后仍应逐次审批，或仅授予短时间临时权限。
  • “启用宿主机执行”表示命令直接在本机运行，不代表存在系统级沙箱。
  • 文件工具受项目目录边界约束，但终端命令本身可能访问更广的本机资源，取决于系统权限。
  • 高风险任务优先使用测试仓库或隔离 worktree，并在交付前运行自己的验证命令。

不要在聊天、公开 Issue、截图或日志中粘贴真实 API Key、密码、Cookie、签名证书或私有仓库凭据。

8. 3D Agent 控制室#

点击侧栏“3D 办公区”进入 Agent 控制室。它展示真实会话状态，而不是独立的装饰动画。

  • 运行、待授权、完成和失败会反映在工位状态中。
  • 成本、路由、故障切换、文件和 Git 状态来自对应会话数据。
  • 单击选择 Agent，双击进入对应会话。
  • “总览、Agent、设施、异常”等镜头用于快速定位不同状态。

成本显示依赖 Provider 返回的 token/用量信息和本地定价配置，只能作为当前配置下的估算，不应直接当作厂商账单。

9. 项目规则与全局设置#

项目规则#

打开“设置 → 项目规则”，选择项目目录后可以维护 caogen.md。它可以记录：

  • 项目背景、技术栈和输出风格。
  • 启动、测试和构建命令。
  • 关键目录、禁止修改路径和验收标准。
  • 调度策略、模型偏好和记忆摘要。

保存后规则从下一轮 Agent 消息开始生效。项目规则应放在对应项目中，不要把某个项目的私有要求写入全局指令。

通用指令与模型角色#

  • “通用指令”会追加到所有项目的内置提示词之后。
  • “控制中心”可以设置默认 Provider、模型、调度策略和模型角色偏好。
  • 模型角色包括调研、策划、开发、测试、文档、低成本、强推理、审查和备用。
  • 自定义调度规则可按关键词、任务类型、风险和当前策略匹配 Provider/模型。

10. 常见问题与排查#

提示“尚未配置可用 Provider”#

确认 Provider 已保存 API Key，模型列表不为空，并在厂商列表运行“检测”。只填写名称而没有 Key 的 Provider 不能开始真实会话。

获取模型列表失败#

检查 Base URL、协议、API Key、账号额度和本机网络。部分兼容服务不提供 /v1/models，此时按厂商控制台给出的真实模型 ID 手工填写，不要猜测模型名称。

自动路由没有切换厂商#

检查是否选择了“跨厂商自动”、是否至少有两个健康 Provider、是否启用了故障切换，以及候选 Provider 的执行引擎是否兼容当前会话。

任务停在“等待授权”#

回到会话时间线查看权限请求。批准、拒绝或停止任务后才会继续；不要在没有看清命令和目标路径时直接允许。

工具无法修改文件或运行命令#

检查会话权限模式、允许/禁止工具规则、项目目录边界和“启用宿主机执行”设置。旧版严格 Docker 设置迁移后，变更类工具可能保持禁用，避免静默转为宿主机执行。

macOS 或 Windows 阻止启动#

当前安装包没有平台签名。重新核对下载来源和 SHA256，然后按本手册“下载与安装”中的单次放行步骤操作。不要关闭整个系统的安全防护。

如何提交问题#

在 GitHub Issues 提交可复现步骤、CaoGen 版本、操作系统、所选执行引擎和已脱敏的错误信息。不要上传 API Key、Cookie、私人代码、完整用户目录或未经处理的日志。

11. 云端能力、隐私与第三方服务#

  • 当前官网和公开桌面版不包含 CaoGen 自营的用户账号、云 Runner、远程续跑或跨设备接管服务。
  • Routines 当前是本地执行能力，不代表云端常驻任务。
  • 项目文件保留在本机，但发送给 Agent 的上下文和工具结果会交给你选择的 Provider、网关或本地服务处理。
  • Provider 的价格、模型、额度、网络可用性和服务条款由对应厂商决定。
  • 官网中的 CiYuan2API 是第三方推广链接。CaoGen 不保存该厂商账号或支付信息，也不对其模型、价格或可用性作额外承诺。

12. 更新与文档维护#

升级前先查看目标版本的 Release Notes 和已知限制。重要项目建议在升级前保留仓库提交、Patch 或独立备份。

本手册的 Markdown 源文件与官网代码一起进行版本管理。版本号、发布日期和下载入口从官网共享配置派生；产品操作变化仍需要人工更新并通过构建检查。

发现文档与实际界面不一致时，请通过 GitHub Issues 反馈，并注明实际版本和对应页面。