# OpenCowork OpenCowork [#opencowork] OpenCowork 是一个 **local-first 桌面 AI Agent 工作站**。它把聊天、工具调用、文件读写、Shell、MCP、子代理、Agent 团队、Cron 任务和工作消息平台接入放在同一个本地应用里。 Documentation index [#documentation-index] 完整页面索引可以从 [`/llms.txt`](/llms.txt) 获取，完整 Markdown 语料可以从 [`/llms-full.txt`](/llms-full.txt) 获取。它们用于让 AI 助手先发现页面，再深入阅读具体主题。 What ships today [#what-ships-today] | Area | Current implementation | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Desktop runtime | Electron 36, React 19, TypeScript strict, Tailwind CSS v4 | | Local system access | Main process owns file I/O, shell, database, MCP, SSH, Cron, channels | | Agent runtime | Renderer-driven loop with tool phases, sub-agents, teams, plans, and goals | | Messaging channels | Feishu, DingTalk, WeCom, QQ, Weixin, Telegram, Discord, WhatsApp | | Model providers | OpenAI, Anthropic, DeepSeek, Google, Ollama, Qwen, Moonshot, MiniMax, Baidu, Azure OpenAI, Copilot, Codex, and compatible endpoints | | Persistence | SQLite under `~/.open-cowork/`, plus JSON config and local agent/skill files | Start here [#start-here] Local-first shape [#local-first-shape] ```txt Main process system tools, SQLite, channels, MCP, SSH, Cron Preload bridge narrow, typed IPC surface Renderer UI React workspace, chat, previews, stores, agent loop Shared types stream protocol, tool contracts, team runtime events ``` Community [#community]
OpenCowork 飞书交流群二维码
扫码进入飞书群，获取更新与支持 / Scan the QR code to join the Feishu group.
# 应用插件 应用插件 / App Plugins [#应用插件--app-plugins] 应用插件是 OpenCowork 的“本地能力扩展层”。它们不是消息平台插件，而是直接增强 Agent 的本地执行能力。 当前内置插件 / Built-in plugins [#当前内置插件--built-in-plugins] | 插件 | ID | 默认状态 | 作用 | | --------------- | ----------------- | ------- | -------------- | | Image | `image` | 开启 | 图像生成 | | Browser | `browser` | 开启 | 内置浏览器控制 | | Desktop Control | `desktop-control` | 关闭 / 隐藏 | 截图、点击、输入、滚动、等待 | 1) Image plugin [#1-image-plugin] 工具 [#工具] * `ImageGenerate` 依赖 [#依赖] Image plugin 需要一个 **category = image** 的可用模型。 行为 [#行为] * 生成图片后会被保存到 `~/.open-cowork/images/YYYY-MM-DD/` * 结果会同时回到聊天流里 * 工具会尽量把 generated image 重新转成可展示的 image block 常见配置 [#常见配置] * 使用全局 image provider * 或在插件里单独指定 provider / model 2) Browser plugin [#2-browser-plugin] 工具 [#工具-1] * `BrowserNavigate` * `BrowserGetContent` * `BrowserScreenshot` * `BrowserSnapshot` * `BrowserClick` * `BrowserType` * `BrowserScroll` 特点 [#特点] * 直接在右侧面板打开 webview * 支持导航、回退、刷新和页面读取 * 支持按 URL 访问本地 dev server 安全规则 [#安全规则] Browser plugin 会检查域名规则： * `browserAllowedDomains` * `browserBlockedDomains` 如果地址不在允许列表中，导航会被拦截。 3) Desktop Control plugin [#3-desktop-control-plugin] 工具 [#工具-2] * `DesktopScreenshot` * `DesktopClick` * `DesktopType` * `DesktopScroll` * `DesktopWait` 特点 [#特点-1] * 依赖系统级输入模拟 * 默认隐藏 * 通常只在可信场景下开启 * 点击、输入、滚动这些动作默认需要审批 插件配置在哪里？ / Where is the config? [#插件配置在哪里--where-is-the-config] 插件状态存放在 `app-plugin-store`，并按 project 维度持久化。 它和消息平台插件的区别 / Difference from channel plugins [#它和消息平台插件的区别--difference-from-channel-plugins] * **App plugin**：增强本地 Agent 能力 * **Channel plugin**：把 Agent 接到外部消息平台 二者经常一起出现，但职责完全不同。 适合的使用场景 / When to use [#适合的使用场景--when-to-use] * 需要生成图片 * 需要控制浏览器页面 * 需要做桌面自动化 * 需要在工作台内部完成“看网页 -> 摘要 -> 执行”的闭环 # 聊天模式 聊天模式 / Chat Modes [#聊天模式--chat-modes] OpenCowork 的模式系统不只是“语气不同”，而是**工具权限、提示词目标和工作方式**都不同。当前模式包括：`chat`、`clarify`、`cowork`、`code` 和 `acp`。 模式总览 / Mode overview [#模式总览--mode-overview] | 模式 | 定位 | 典型行为 | | --------- | -------------------- | ------------------ | | `chat` | 轻量默认对话 | 直接回答、少工具、快速互动 | | `clarify` | 需求澄清 | 先问清楚，再进入 Plan Mode | | `cowork` | 通用协作 | 文档、信息、轻量执行和协同 | | `code` | 代码执行 | 读写文件、跑 Shell、做代码修改 | | `acp` | Architecture Control | 只做设计、拆解和委派，不直接改代码 | Chat [#chat] Chat 是最轻量的对话模式。它适合： * 日常问答 * 快速解释 * 不需要复杂工具的请求 它的目标是“先把话说清楚”，不是“先把工作做完”。 Clarify [#clarify] Clarify 模式的目标是把不清晰的需求变成可执行计划： 1. 先读取上下文 2. 再通过 `AskUserQuestion` 追问关键歧义 3. 最后进入 [Plan Mode](/docs/capabilities/plan-mode) 它适合： * 需求不完整 * 方案有多个分支 * 风险和约束还没确认 Cowork [#cowork] Cowork 是协作型模式，适合： * 文档整理 * 资料汇总 * 轻量执行 * 有一定上下文但不需要强代码权限的任务 它强调“合作”，不是“全自动替你做一切”。 Code [#code] Code 是代码执行模式，适合： * 读写项目文件 * 搜索实现 * 跑 Shell 命令 * 修 bug / 加功能 / 重构 如果你要让 Agent 修改仓库，优先用 Code，并且尽量先设置 working folder。 ACP [#acp] ACP（Architecture Control）是架构控制模式，适合： * 设计系统结构 * 拆解复杂任务 * 分派给子代理或团队成员 * 先确认边界，再决定实现路线 ACP 的关键点是：**不直接做实现**。它更像总控，而不是执行者。 模式和 Plan Mode 的关系 / Relation to Plan Mode [#模式和-plan-mode-的关系--relation-to-plan-mode] * Clarify 常常会把你引导到 Plan Mode * Code 模式下也可以进入 Plan Mode * ACP 负责设计和委派，通常不会直接写代码 * Plan Mode 是一个独立的执行前审阅阶段，不等同于模式切换 你可以怎么选 / How to choose [#你可以怎么选--how-to-choose] * **先聊天**：Chat * **先问清楚**：Clarify * **协作处理**：Cowork * **改仓库代码**：Code * **设计和委派**：ACP # 文件预览 文件预览 / File Preview [#文件预览--file-preview] OpenCowork 的文件预览不是一个独立 LLM 工具，而是一个**右侧面板的 viewer 系统**。它让你在对话之外查看文件、网页和开发预览。 预览系统在哪里 / Where it lives [#预览系统在哪里--where-it-lives] * `src/renderer/src/lib/preview/register-viewers.ts` * `src/renderer/src/lib/preview/viewer-registry.ts` * `src/renderer/src/lib/preview/viewers/` 注册方式 / Registration [#注册方式--registration] 启动时会调用 `registerAllViewers()`，把不同扩展名映射到不同 viewer。 ```ts viewerRegistry.register({ type: 'markdown', extensions: ['.md', '.mdx'], component: MarkdownViewer }) ``` 支持的 viewer / Supported viewers [#支持的-viewer--supported-viewers] | 类型 | 典型扩展名 | | --------------- | --------------------------------------------------------------------- | | `html` | `.html`, `.htm`, `.xhtml`, `.shtml` | | `spreadsheet` | `.csv`, `.tsv`, `.xlsx`, `.xls`, `.xlsm`, `.xlsb`, `.ods` | | `markdown` | `.md`, `.mdx`, `.markdown`, `.mdown`, `.mkd`, `.mkdn`, `.mdwn` | | `image` | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.heic`, `.heif` 等 | | `svg` | `.svg` | | `video` | `.mp4`, `.webm`, `.mov`, `.mkv`, `.avi` 等 | | `audio` | `.mp3`, `.wav`, `.ogg`, `.m4a`, `.flac`, `.opus` 等 | | `font` | `.ttf`, `.otf`, `.woff`, `.woff2` | | `docx` | `.docx`, `.docm`, `.dotx`, `.dotm` | | `office-online` | `.doc`, `.ppt`, `.pptx`, `.odp`, `.odt`, `.rtf` | | `pdf` | `.pdf` | | `binary` | `.zip`, `.rar`, `.7z`, `.db`, `.sqlite`, `.exe`, `.dylib` 等 | | `fallback` | 兜底 | 额外能力 / Extra capabilities [#额外能力--extra-capabilities] * Markdown 里支持 Mermaid 渲染 * 本地 dev server 页面可以走专门 viewer * SVG 有独立 viewer * 二进制文件不会假装自己是文本 预览面板怎么用 / How to use it [#预览面板怎么用--how-to-use-it] 预览通常从这些入口打开： * 文件列表 * 右侧面板 * 对话中的预览跳转 * 代码/文档中的链接 你在界面里会看到什么 / What you see in UI [#你在界面里会看到什么--what-you-see-in-ui] * 预览区标题 * view mode（preview / code） * 文件类型识别 * 对应的专用渲染器 重要结论 / Important note [#重要结论--important-note] 以前文档里把它写成 `Preview` 工具，这是不准确的。当前实现里，它是 **viewer registry + right panel**，不是一个 LLM tool。 # Capabilities Capabilities [#capabilities] Capabilities 是 Agent 能实际做事的表面：读写文件、搜索代码、执行 Shell、调用 MCP、打开浏览器、预览文件、规划任务、调度后台工作，以及通过插件扩展桌面能力。 Choose a surface [#choose-a-surface] | Need | Start with | | ----------------------- | ----------------------------------------------- | | 让 Agent 读写项目文件、跑命令、搜索代码 | [Tool system](/docs/capabilities/tools) | | 让 Agent 先产出可审阅计划 | [Plan mode](/docs/capabilities/plan-mode) | | 让 Agent 调用外部工具服务 | [MCP servers](/docs/capabilities/mcp-servers) | | 让 Agent 操作桌面、浏览器或图片能力 | [App plugins](/docs/capabilities/app-plugins) | | 让用户查看 PDF、图片、表格、文档、HTML | [File preview](/docs/capabilities/file-preview) | Tool posture [#tool-posture] OpenCowork 默认把高影响操作放进明确的工具和 UI 反馈里。Agent 可以很强，但用户需要知道它在做什么、在哪个工作区做、什么时候需要人工确认。 # MCP 服务器 MCP 服务器 / MCP Servers [#mcp-服务器--mcp-servers] OpenCowork 支持 Model Context Protocol (MCP)，用来把外部工具、资源和 prompts 接入 Agent。 配置存储 / Config storage [#配置存储--config-storage] MCP 服务器配置会被写入： ```text ~/.open-cowork/mcp-servers.json ``` 主进程会在启动时自动连接所有 `enabled=true` 的 server。 支持的 transport / Supported transports [#支持的-transport--supported-transports] | transport | 场景 | | ----------------- | ------------- | | `stdio` | 本地 CLI / 本地进程 | | `sse` | 远程 HTTP + SSE | | `streamable-http` | 新式 HTTP 传输 | `streamable-http` 失败时还可以按配置回退到 `sse`。 主要 IPC / Main IPC [#主要-ipc--main-ipc] MCP 主进程 handler 提供这些能力： * `mcp:list` * `mcp:add` * `mcp:update` * `mcp:remove` * `mcp:connect` * `mcp:disconnect` * `mcp:status` * `mcp:server-info` * `mcp:all-servers-info` * `mcp:list-tools` * `mcp:call-tool` * `mcp:read-resource` * `mcp:list-resources` * `mcp:get-prompt` * `mcp:list-prompts` * `mcp:refresh-capabilities` Server 配置 / Server config [#server-配置--server-config] `McpServerConfig` 常见字段： | 字段 | 作用 | | ---------------------------------- | ----------------------------------- | | `id` / `name` | server 标识 | | `enabled` | 是否启用 | | `projectId` | 是否绑定到某个项目 | | `transport` | `stdio` / `sse` / `streamable-http` | | `command` / `args` / `env` / `cwd` | stdio 进程配置 | | `url` / `headers` | HTTP/SSE 配置 | | `autoFallback` | streamable-http 失败后是否回退 | | `description` | 说明 | 能力发现 / Capability discovery [#能力发现--capability-discovery] 连接成功后，OpenCowork 会把 server 暴露出来的： * tools * resources * prompts 都整理到前端可用的列表里。Agent 就能像使用本地工具一样使用这些能力。 典型流程 / Typical flow [#典型流程--typical-flow] 1. 在设置里新增 MCP server 2. 保存到 `mcp-servers.json` 3. 启动或手动连接 server 4. 读取工具 / 资源 / prompts 5. 在对话里直接调用 6. server 断开后，能力自动消失 示例 / Example [#示例--example] ```json { "id": "github", "name": "GitHub MCP", "enabled": true, "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." } } ``` 什么时候该用 MCP？ / When to use MCP? [#什么时候该用-mcp--when-to-use-mcp] * 访问外部系统 API * 读写第三方资源 * 把 CLI 工具接进 Agent * 想把团队内部服务暴露成可调用能力 # 计划模式 计划模式 / Plan Mode [#计划模式--plan-mode] Plan Mode 是 OpenCowork 用来处理复杂任务的“先规划、后执行”流程。它的核心不是 UI 开关，而是两个工具：`EnterPlanMode` 和 `ExitPlanMode`。 Plan Mode 的目标 / Goal [#plan-mode-的目标--goal] * 把模糊需求拆成清晰步骤 * 让计划文件可审阅 * 在真正修改代码前先锁定方案 * 避免一边做一边改方向 工作流程 / Flow [#工作流程--flow] 关键文件 / Key files [#关键文件--key-files] | 位置 | 作用 | | ----------------------------------------- | ------------------------------------- | | `src/renderer/src/lib/tools/plan-tool.ts` | `EnterPlanMode` / `ExitPlanMode` 工具实现 | | `src/renderer/src/stores/plan-store.ts` | 计划状态和本地缓存 | | `src/main/db/database.ts` | `plans` 表和计划持久化 | 计划文件放在哪里？ / Where is the plan file? [#计划文件放在哪里--where-is-the-plan-file] 当一个会话进入 Plan Mode 时，系统会在当前 working folder 下创建： ```text .plan/.md ``` 也就是说，计划文件和项目代码在同一个上下文里，方便审阅和后续执行。 状态流转 / Status flow [#状态流转--status-flow] `PlanStore` 里可见的状态有： | 状态 | 含义 | | ----------------- | ------------ | | `drafting` | 正在写计划 | | `awaiting_review` | 计划已完成，等待用户审阅 | | `approved` | 用户已批准 | | `implementing` | 正在执行实现 | | `completed` | 计划执行完成 | | `rejected` | 用户驳回 | 工具行为 / Tool behavior [#工具行为--tool-behavior] EnterPlanMode [#enterplanmode] * 需要活跃 session * 需要 working folder * 如果已有草稿计划，可以恢复 * 如果没有计划，会创建新的 plan 记录和计划文件 * 进入后，当前会话会切换到 Plan Mode 状态 ExitPlanMode [#exitplanmode] * 会先读取当前 plan 文件 * 计划文件不能为空 * 退出时会把 plan 设为 `awaiting_review` * 返回 plan 内容，等待用户批准 计划模式下允许的工具 / Allowed tools [#计划模式下允许的工具--allowed-tools] Plan Mode 不是“完全禁用工具”，而是**限制工具边界**： * `Read` * `LS` * `Glob` * `Grep` * `Write` * `Edit` * `EnterPlanMode` * `ExitPlanMode` * `AskUserQuestion` * `TaskCreate` / `TaskGet` / `TaskUpdate` / `TaskList` * `Task` * `get_goal` / `create_goal` / `update_goal` * `visualize_show_widget` 其中 `Write` / `Edit` 只能作用于当前 plan 文件。 ACP 和 Plan Mode 的区别 / ACP vs Plan Mode [#acp-和-plan-mode-的区别--acp-vs-plan-mode] * **Plan Mode**：允许写计划文件，面向“执行前审阅” * **ACP**：不直接改代码，面向“架构控制和委派” 实际建议 / Practical advice [#实际建议--practical-advice] * 小任务可以直接 Code * 不清楚需求时先 Clarify，再 Plan Mode * 复杂功能、多人协作功能、风险较高的改动，优先 Plan Mode * 写完计划后，不要急着执行，先让用户看一眼 # 工具系统 工具系统 / Tool System [#工具系统--tool-system] 工具系统是 OpenCowork 把“聊天”变成“执行”的关键。入口位于 `src/renderer/src/lib/tools/`，统一通过 `toolRegistry` 注册。 ToolHandler 结构 / ToolHandler shape [#toolhandler-结构--toolhandler-shape] ```ts interface ToolHandler { definition: Tool execute(input: unknown, ctx: ToolContext): Promise requiresApproval?(input: unknown, ctx: ToolContext): boolean } ``` 注册顺序 / Registration order [#注册顺序--registration-order] `src/renderer/src/lib/tools/index.ts` 的注册顺序大致是： 1. 基础任务与文件工具 2. 搜索与 Shell 工具 3. Widget / AskUser / Plan / Cron / Notify / Goal 4. 动态目录刷新（skills / sub-agents） 5. Team 工具 6. Web Search 动态注册 7. 应用插件工具动态注册 8. MCP 工具运行时发现 工具分类 / Tool categories [#工具分类--tool-categories] 1) 文件系统 [#1-文件系统] * `Read` * `Write` * `Edit` 2) 搜索 [#2-搜索] * `Glob` * `Grep` 3) Shell [#3-shell] * `Bash` 4) 计划与任务 [#4-计划与任务] * `EnterPlanMode` * `ExitPlanMode` * `TaskCreate` * `TaskGet` * `TaskUpdate` * `TaskList` 5) 子代理与团队 [#5-子代理与团队] * `Task`（统一子代理入口） * `TeamCreate` * `SendMessage` * `TeamStatus` * `TeamDelete` 6) 目标与审批/提问 [#6-目标与审批提问] * `get_goal` * `create_goal` * `update_goal` * `AskUserQuestion` * `Notify` * `visualize_show_widget` 7) Cron [#7-cron] * `CronAdd` * `CronUpdate` * `CronRemove` * `CronList` 8) Web / Browser [#8-web--browser] * `WebSearch` * `WebFetch` * `BrowserNavigate` * `BrowserGetContent` * `BrowserScreenshot` * `BrowserSnapshot` * `BrowserClick` * `BrowserType` * `BrowserScroll` 9) App plugins [#9-app-plugins] * `ImageGenerate` * `DesktopScreenshot` * `DesktopClick` * `DesktopType` * `DesktopScroll` * `DesktopWait` 10) 消息平台插件 [#10-消息平台插件] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` * Feishu / Weixin 专属工具（如 `FeishuSendImage`、`WeixinSendFile`） 11) MCP [#11-mcp] MCP 工具不是预先写死的，它们由已连接 server 的能力发现动态注入。 审批 / Approval [#审批--approval] 并不是所有工具都会无条件执行。高风险工具通常会： * 需要用户审批 * 或者在 `forceApproval` 场景下由插件自动回复流程接管 常见需要审批的操作包括： * 文件写入 / 编辑 * Shell 命令 * 发消息到外部平台 * 桌面点击 / 输入 / 滚动 * Cron 创建或修改 动态目录 / Dynamic catalogs [#动态目录--dynamic-catalogs] `Skill` 和 `Task` 并不是两个割裂的系统： * `Skill` 从 `~/.agents/skills/` 加载 * `Task` 从 `~/.open-cowork/agents/` 加载子代理定义 这意味着工具系统可以根据用户本地安装的内容动态扩展。 你在代码里会看到什么 / What to look for in code [#你在代码里会看到什么--what-to-look-for-in-code] * `toolRegistry.register(...)` * `registerAllTools()` * `registerImagePluginTools()` / `registerBrowserTool()` / `registerDesktopControlTools()` * `refreshSkillTools()` / `refreshSubAgentTools()` * `isWebSearchToolRegistered()` 结论 / Conclusion [#结论--conclusion] OpenCowork 的工具系统本质上是一个**可注册、可动态扩展、带审批策略的能力总线**。Agent 不是“猜怎么做”，而是“拿工具去做”。 # 钉钉集成 钉钉集成 / DingTalk Integration [#钉钉集成--dingtalk-integration] 钉钉插件基于 Stream API，适合把 OpenCowork 接到企业内部的钉钉群里。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | ---------------- | ------------ | | `appKey` | 钉钉应用 Key | | `appSecret` | 钉钉应用 Secret | | `cardTemplateId` | 可选的流式卡片模板 ID | 支持的工具 / Tool set [#支持的工具--tool-set] 钉钉插件使用统一工具集： * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` 特点 / Characteristics [#特点--characteristics] * 内置 Stream API 支持 * 可使用卡片模板做流式展示 * 适合企业群聊自动回复 * 可与 Cron / Notify / Team Runtime 联动 适合什么场景？ / When to use it [#适合什么场景--when-to-use-it] * 群里需要 AI 助手 * 需要定时推送报告 * 需要把本地执行结果推到钉钉 # Discord 集成 Discord 集成 / Discord Integration [#discord-集成--discord-integration] Discord 插件使用官方 Gateway WS，适合社区机器人和群组自动回复。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | ---------- | ----------------- | | `botToken` | Discord bot token | 支持的工具 / Tool set [#支持的工具--tool-set] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` 说明 / Notes [#说明--notes] * 无需额外 relay * 适合社区和开源项目的自动回复 * 与其他平台一样，工具调用是统一的 适合什么场景？ / When to use it [#适合什么场景--when-to-use-it] * Discord 社区机器人 * 自动 FAQ * 结果推送 # 飞书集成 飞书集成 / Feishu Integration [#飞书集成--feishu-integration] Feishu Bot 是 OpenCowork 里功能最完整的消息平台之一。它支持流式卡片、图片和文件发送，以及一组较丰富的飞书专属工具。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | ----------- | ----------- | | `appId` | 飞书应用 ID | | `appSecret` | 飞书应用 Secret | 连接方式 / Transport [#连接方式--transport] * 内置 WS 连接 * 支持自动回复 * 支持流式卡片更新 支持的工具 / Tool set [#支持的工具--tool-set] 统一工具 [#统一工具] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` Feishu 专属工具 [#feishu-专属工具] * `FeishuSendImage` * `FeishuSendFile` * `FeishuListChatMembers` * `FeishuAtMember` * `FeishuSendUrgent` * `FeishuBitableListApps` * `FeishuBitableListTables` * `FeishuBitableListFields` * `FeishuBitableGetRecords` * `FeishuBitableCreateRecords` * `FeishuBitableUpdateRecords` * `FeishuBitableDeleteRecords` 流式卡片 / Streaming card [#流式卡片--streaming-card] 飞书插件可以把 Agent 的输出写进卡片并持续更新，适合： * 长回复 * 结果汇总 * 定时任务通知 * 自动化执行报告 什么时候用飞书？ / When to use it [#什么时候用飞书--when-to-use-it] * 你想把 AI 接进团队工作群 * 你需要更强的企业协作体验 * 你想让 Cron 或自动回复把结果直接发到飞书里 # Channels Channels [#channels] OpenCowork 的消息平台插件运行在 Electron main process。每个平台插件都扩展 `base-plugin-service.ts`，负责登录、连接、收消息、发消息和生命周期管理。 Supported platforms [#supported-platforms] | 平台 | 目录 | | -------------- | --------------------------------------- | | 飞书 / Feishu | `src/main/channels/providers/feishu/` | | 钉钉 / DingTalk | `src/main/channels/providers/dingtalk/` | | 企业微信 / WeCom | `src/main/channels/providers/wecom/` | | QQ | `src/main/channels/providers/qq/` | | Telegram | `src/main/channels/providers/telegram/` | | Discord | `src/main/channels/providers/discord/` | | 微信个人号 / Weixin | `src/main/channels/providers/weixin/` | | WhatsApp | `src/main/channels/providers/whatsapp/` | Lifecycle [#lifecycle] B[channel-manager] B --> C[create plugin service] C --> D[onStart] D --> E[receive platform message] E --> F[run agent loop] F --> G[send reply] `} /> Core contract [#core-contract] 每个插件服务需要提供： * `onStart()`：启动连接、登录或订阅事件。 * `onStop()`：停止连接并清理资源。 * 消息发送方法：发送文本、图片、文件或平台特定卡片。 * 状态管理：登录状态、连接状态、错误状态。 Choose a channel [#choose-a-channel] * 团队协作优先：从 [Feishu](/docs/channels/feishu)、[DingTalk](/docs/channels/dingtalk) 或 [WeCom](/docs/channels/wecom) 开始。 * 社区和移动端优先：从 [Telegram](/docs/channels/telegram)、[Discord](/docs/channels/discord) 或 [WhatsApp](/docs/channels/whatsapp) 开始。 * 中文个人号场景：查看 [QQ](/docs/channels/qq) 或 [Weixin personal](/docs/channels/weixin-personal)。 # QQ 集成 QQ 集成 / QQ Integration [#qq-集成--qq-integration] QQ 插件接入的是 QQ 官方 Gateway WS。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | ----------------- | ---------------- | | `appId` | QQ 应用 ID | | `clientSecret` | QQ 应用 Secret | | `useSandbox` | 是否使用 sandbox | | `markdownSupport` | 是否启用 markdown 能力 | 支持的工具 / Tool set [#支持的工具--tool-set] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` 说明 / Notes [#说明--notes] * QQ 插件适合官方机器人场景 * 如果你要发结构化结果，可以配合 markdownSupport * 工具层和其他消息平台一致 适合什么场景？ / When to use it [#适合什么场景--when-to-use-it] * QQ 群聊机器人 * 自动回复 * 轻量通知 # Telegram 集成 Telegram 集成 / Telegram Integration [#telegram-集成--telegram-integration] Telegram 插件是一个标准 bot 接入。某些部署场景下需要配合 WebSocket relay。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | ---------- | ------------------ | | `botToken` | Telegram bot token | | `wsUrl` | 可选的 relay 地址 | 支持的工具 / Tool set [#支持的工具--tool-set] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` 说明 / Notes [#说明--notes] * 适合把 OpenCowork 接入海外聊天环境 * 和其他平台一样，消息最终都走统一 plugin tools * 若部署环境无法直连 bot 端，就配置 relay 适合什么场景？ / When to use it [#适合什么场景--when-to-use-it] * 跨时区通知 * 社区机器人 * 远程消息自动回复 # 企业微信集成 企业微信集成 / WeCom Integration [#企业微信集成--wecom-integration] 企业微信插件适合把 OpenCowork 接到企业微信工作流中。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | --------- | ---------------------- | | `corpId` | 企业 ID | | `secret` | 应用 Secret | | `agentId` | 企业微信应用 Agent ID | | `wsUrl` | 可选的 WebSocket relay 地址 | 支持的工具 / Tool set [#支持的工具--tool-set] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` 说明 / Notes [#说明--notes] * 企业微信属于常见的企业聊天接入场景 * 如果你的环境需要 relay，就把 `wsUrl` 配好 * 其他能力和统一插件工具保持一致 适合什么场景？ / When to use it [#适合什么场景--when-to-use-it] * 企业内部自动回复 * 结果通知 * 部门群机器人 # 个人微信接入 个人微信接入 / Personal Weixin Integration [#个人微信接入--personal-weixin-integration] 这个页面对应的是 OpenCowork 当前的微信扫码绑定方案。虽然内部插件类型叫 `weixin-official`，但它的使用方式更接近“个人微信扫码接入 + 长轮询收发消息”。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | ----------- | ----------------------------------------- | | `baseUrl` | 微信网关地址，默认 `https://ilinkai.weixin.qq.com` | | `routeTag` | 可选路由标记 | | `token` | 网关 token | | `accountId` | 账号 ID | | `userId` | 用户 ID | 支持的工具 / Tool set [#支持的工具--tool-set] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetCurrentChatMessages` * `PluginSummarizeGroup` * `WeixinSendImage` * `WeixinSendFile` 工作方式 / How it works [#工作方式--how-it-works] 1. 通过扫码绑定个人微信账号 2. 保存 token / accountId / userId 3. 使用长轮询拉取消息 4. 用已有对话上下文做回复 特点 / Characteristics [#特点--characteristics] * 当前实现更偏“个人会话接入”而不是群聊机器人 * `getGroupMessages` / `listGroups` 语义上不是重点，通常返回空列表 * 回复依赖已有上下文 token，因此它更像“对已有聊天的自动接管” 适合什么场景？ / When to use it [#适合什么场景--when-to-use-it] * 个人微信私聊自动回复 * 把微信消息接入 OpenCowork 的本地 Agent 流程 * 在个人沟通场景里使用 AI 辅助 # WhatsApp 集成 WhatsApp 集成 / WhatsApp Integration [#whatsapp-集成--whatsapp-integration] WhatsApp 插件基于 WhatsApp Cloud API，通常还需要一个 relay 来做外部消息桥接。 配置字段 / Required fields [#配置字段--required-fields] | 字段 | 作用 | | --------------- | ---------------------------------- | | `phoneNumberId` | WhatsApp Cloud API phone number ID | | `accessToken` | Cloud API access token | | `wsUrl` | 可选 / 常见需要的 relay 地址 | 支持的工具 / Tool set [#支持的工具--tool-set] * `PluginSendMessage` * `PluginReplyMessage` * `PluginGetGroupMessages` * `PluginListGroups` * `PluginSummarizeGroup` * `PluginGetCurrentChatMessages` 说明 / Notes [#说明--notes] * 适合把 OpenCowork 接入 WhatsApp 工作流 * 依赖云 API 认证 * 需要时通过 relay 做消息桥接 适合什么场景？ / When to use it [#适合什么场景--when-to-use-it] * 客服场景 * 国际化通知 * 跨设备消息自动回复 # Agent 循环 Agent 循环 / Agent Loop [#agent-循环--agent-loop] Agent Loop 是 OpenCowork 的核心执行引擎，入口位于 `src/renderer/src/lib/agent/agent-loop.ts`。它是一个 `AsyncGenerator`：每轮都会把消息发给 provider、解析流式事件、执行工具、再把工具结果追加回消息队列。 工作流程 / Flow [#工作流程--flow] 核心入口 / Core entry [#核心入口--core-entry] ```ts runAgentLoop(messages, config, toolCtx, onApprovalNeeded?) ``` 关键参数 [#关键参数] | 参数 | 作用 | | --------------------------- | ------------------------- | | `messages` | 当前对话消息 | | `config.provider` | 当前 provider 配置 | | `config.tools` | 已注册工具定义 | | `config.contextCompression` | 上下文压缩配置 | | `config.maxIterations` | 最大循环轮次 | | `config.signal` | AbortSignal，用于取消请求 | | `toolCtx` | 工具执行上下文（IPC、工作目录、会话、插件信息） | 流式事件 / Streaming events [#流式事件--streaming-events] Agent Loop 会把流式事件持续抛给 UI，常见事件包括： * `loop_start` * `iteration_start` * `thinking_delta` * `text_delta` * `tool_use_streaming_start` * `tool_use_args_delta` * `tool_call_start` * `tool_call_approval_needed` * `tool_call_result` * `context_compression_start` * `context_compressed` * `message_end` * `error` * `loop_end` 这些事件最终驱动聊天窗口、右侧面板、审批弹窗和运行统计。 运行时细节 / Runtime details [#运行时细节--runtime-details] 1) Provider 重试 [#1-provider-重试] Provider 请求会进行有限次数重试。网络抖动、429、短暂连接问题会自动重试；认证错误通常不会重试。 2) 并行工具调用 [#2-并行工具调用] Agent Loop 会限制并行工具数，避免一次性把太多任务同时推向本地或远端工具。 3) 上下文管理 [#3-上下文管理] 在每轮迭代之间，Loop 会检查上下文是否接近阈值： * 先做轻量 pre-compress * 再做完整压缩 * 压缩后继续循环 4) 审批流 [#4-审批流] 对于危险操作，Loop 会把 `tool_call_approval_needed` 发给 UI，等待用户确认后再继续。 5) Thinking / image / provider 元数据 [#5-thinking--image--provider-元数据] Loop 不只处理纯文本，还会处理： * `thinking_delta` / `thinking_encrypted` * `image_generated` / `image_error` * provider response id * request debug 信息 主进程复用 / Main-process reuse [#主进程复用--main-process-reuse] 渲染进程的 Agent Loop 和主进程 JS Agent Runtime 共享同一套事件协议和工具语义。区别只是： * 渲染进程负责前台交互 * 主进程负责后台任务、Cron、插件自动回复 为什么它重要 / Why it matters [#为什么它重要--why-it-matters] 如果你想理解 OpenCowork 的本质，先看 Agent Loop： * 它决定模型怎么被调用 * 它决定工具怎么串起来 * 它决定 UI 为什么可以实时显示思考、工具和结果 * 它也是自动化是否可靠的核心 # 上下文压缩 上下文压缩 / Context Compression [#上下文压缩--context-compression] OpenCowork 的上下文压缩不是一个“开关”，而是一组分层策略。目标是：**在尽量保留推理上下文的前提下，避免对话历史把上下文窗口撑爆。** 默认策略 / Default policy [#默认策略--default-policy] `src/renderer/src/lib/agent/context-compression.ts` 里定义了几个关键默认值： | 项 | 默认值 | | ------------------- | ---------------- | | 最大上下文长度 | `200_000` tokens | | Full compression 阈值 | `0.8` | | 预留输出预算 | `20_000` tokens | | Pre-compress 阈值 | `0.65` | | Auto buffer | `13_000` tokens | | Pre buffer | `20_000` tokens | | Pre gap | `8_000` tokens | > 这些值会结合具体模型的 `contextLength`、`maxOutputTokens` 和模型配置动态调整。 两级压缩 / Two-stage compression [#两级压缩--two-stage-compression] 1) Pre-compress [#1-pre-compress] 轻量级压缩，尽量不改写结构： * 清理过旧的工具结果 * 清理部分 thinking 内容 * 保留消息骨架和调用痕迹 * 不额外发起一次模型摘要请求 适合“还没满，但已经开始臃肿”的对话。 2) Full compress [#2-full-compress] 真正触发上下文窗口回收时会做完整压缩： 1. 生成压缩摘要 2. 用摘要替换旧消息 3. 保留最近的消息和关键边界 4. 把压缩后的 transcript 放回 loop 继续执行 触发条件 / Trigger logic [#触发条件--trigger-logic] 压缩是否发生由运行时配置决定，而不是一个固定全局值： * `shouldPreCompress(inputTokens, config)` * `shouldCompress(inputTokens, config)` 这意味着不同模型、不同 provider、不同会话会有不同的压缩触发点。 压缩产物 / Compression artifacts [#压缩产物--compression-artifacts] 压缩后，消息会携带一些元数据，便于 UI 判断是否被压缩过： * `compactBoundary` * `compactSummary` 这些元数据会帮助界面显示“这里发生过上下文回收”，避免用户误以为历史消息丢失了。 和 Agent Loop 的关系 / Relation to the loop [#和-agent-loop-的关系--relation-to-the-loop] Agent Loop 在每一轮开始前都会检查： 1. 当前输入 token 是否接近阈值 2. 是否先做 pre-compress 3. 是否需要 full compress 4. 压缩完成后继续发送下一轮请求 因此，上下文压缩是 loop 的一部分，而不是独立后台任务。 实际建议 / Practical advice [#实际建议--practical-advice] * 长对话尽量让模型尽早总结阶段性结果 * 大段日志、长文件、重复工具输出不要无节制地堆进上下文 * 如果你正在做复杂的代码工作，建议在关键节点主动让 Agent 总结阶段结果 * 如果你发现回答开始变慢或上下文变乱，通常说明该压缩了 # Agents Agents [#agents] OpenCowork 的核心不是单轮问答，而是可持续执行的 Agent runtime。这里解释一次会话如何流式运行、如何保留上下文、什么时候派发子代理，以及团队协作如何把大任务拆成多条工作线。 Recommended path [#recommended-path] 理解模型、工具和事件如何串成一条执行循环。 掌握 chat、code、cowork、clarify、acp 等模式的边界。 决定什么时候用单个专用 agent，什么时候组建团队。 Runtime map [#runtime-map] | Concept | Use it when | | ------------------- | ------------------------------ | | Agent loop | 需要理解一次任务如何从输入推进到工具执行和最终回复 | | Session | 需要隔离上下文、窗口、模型、工作目录和 UI 状态 | | Context compression | 长会话需要保留关键信息并压缩噪声 | | Sub-agent | 一个明确任务可以交给专用角色独立完成 | | Team | 任务需要 lead/worker 协作、消息传递和多步骤计划 | # 会话与消息管理 会话与消息管理 / Sessions & Messages [#会话与消息管理--sessions--messages] OpenCowork 使用的是 **project → session** 的结构，而不是单纯的“聊天列表”。这样做是为了把工作目录、SSH、插件和模型绑定到真实工作上下文里。 业务模型 / Data model [#业务模型--data-model] Project [#project] ```ts interface Project { id: string name: string workingFolder?: string sshConnectionId?: string pluginId?: string pinned: boolean createdAt: number updatedAt: number } ``` Session [#session] ```ts interface Session { id: string title: string mode: 'chat' | 'clarify' | 'cowork' | 'code' | 'acp' projectId: string workingFolder?: string messageCount: number pluginId?: string sshConnectionId?: string providerId?: string modelId?: string planId?: string pinned: boolean createdAt: number updatedAt: number } ``` Message [#message] ```ts interface Message { id: string sessionId: string role: 'user' | 'assistant' | 'tool' content: string | ContentBlock[] usage?: string sortOrder: number createdAt: number } ``` 模式 / Modes [#模式--modes] | 模式 | 含义 | | --------- | ---------- | | `chat` | 轻量对话 | | `clarify` | 先问清楚，再进入计划 | | `cowork` | 通用协作 | | `code` | 代码修改与本地执行 | | `acp` | 架构控制与委派执行 | 消息内容 / Message content [#消息内容--message-content] 消息内容不是只有纯文本，`content` 可以是一个 block 数组： * `text` * `thinking` * `tool_use` * `tool_result` * `image` * `image_error` * `agent_error` 这就是为什么聊天窗口能同时展示文本、思考、工具调用和图片。 持久化 / Persistence [#持久化--persistence] 会话和消息最终落在 SQLite 中： * `sessions` * `messages` 其中 `messages.meta` 会保存压缩边界、摘要等辅助信息，`messages.sort_order` 保证流式写入顺序稳定。 UI store 的作用 / UI store responsibilities [#ui-store-的作用--ui-store-responsibilities] `chat-store` 负责： * 项目和会话列表 * 当前活动会话 * 会话模式切换 * 工作目录与 SSH 上下文 * 从数据库加载历史消息 project 为什么重要 / Why projects matter [#project-为什么重要--why-projects-matter] Project 不只是“分组”标签，它实际上承载了： * 工作目录 * SSH 目标 * 消息平台上下文 * 关联会话集合 * pinned 状态 这让 OpenCowork 能把“一个代码仓库 / 一个远程主机 / 一个插件聊天空间”当成真正的工作单元。 # 子代理 子代理 / Sub-Agents [#子代理--sub-agents] 子代理是 OpenCowork 用来处理“复杂但可独立拆分”的任务的方式。核心入口是 `Task` 工具，它会根据 `subagent_type` 启动一个专门的 agent。 子代理从哪里来？ / Where do they come from? [#子代理从哪里来--where-do-they-come-from] OpenCowork 会在首次运行时把内置 agent 从 `resources/agents/` 同步到： ```text ~/.open-cowork/agents/ ``` 之后 `agents:list` / `agents:load` 就会从这个目录读取用户可编辑的 `.md` 文件。 内置 agent / Built-in agents [#内置-agent--built-in-agents] 当前仓库内置的 agent 定义包括： * `api-designer` * `architect-reviewer` * `code-reviewer` * `copywriter` * `cron-agent` * `data-analyst` * `debugger` * `frontend-developer` * `fullstack-developer` * `meeting-summarizer` * `performance-engineer` * `refactor-expert` * `security-auditor` * `test-automator` * `translator` Agent 文件格式 / File format [#agent-文件格式--file-format] 每个 agent 是一个 Markdown 文件，前面带 frontmatter，例如： ```md --- name: code-reviewer description: 代码审查专家 icon: shield allowedTools: [Read, Glob, Grep, LS, Bash] maxTurns: 8 background: false --- 你是一个代码审查专家…… ``` 常见字段 [#常见字段] | 字段 | 作用 | | ---------------------------- | ------------------------------- | | `name` | agent 名称，也是 `subagent_type` 候选值 | | `description` | 给 `Task` 工具展示的描述 | | `icon` | 侧边栏图标名 | | `tools` / `allowedTools` | 允许使用的工具列表 | | `disallowedTools` | 显式禁止的工具 | | `maxTurns` / `maxIterations` | 最大轮次 | | `initialPrompt` | 初始提示词前缀 | | `background` | 是否用于后台执行 | | `model` | 覆盖模型 | | `temperature` | 覆盖采样温度 | | `systemPrompt` | frontmatter 后面的正文 | Task 工具怎么用？ / How to use Task [#task-工具怎么用--how-to-use-task] ```json { "subagent_type": "code-reviewer", "prompt": "请检查 src/main/index.ts 里的启动逻辑是否有明显问题", "run_in_background": false } ``` `Task` 工具是统一入口： * `subagent_type` 选 agent * `prompt` 说清楚要做什么 * `run_in_background=true` 可以让它独立跑 custom 子代理 / custom sub-agent [#custom-子代理--custom-sub-agent] 当内置 agent 都不合适时，可以用 `custom`。它是一个通用 fallback： * 使用默认系统提示词 * 工具范围更广 * 适合临时任务、研究任务和一次性委派 和团队的区别 / Difference from teams [#和团队的区别--difference-from-teams] * **Sub-agent**：单个专用 agent，偏“任务执行器” * **Team**：多成员协作，有 lead / worker / message / task / snapshot 体系 这两个系统看起来相似，但不是一回事。 什么时候该用子代理？ / When should you use one? [#什么时候该用子代理--when-should-you-use-one] * 代码审查 * 架构分析 * 复杂重构 * 数据分析 * 定时任务撰写 * 文案生成 * 测试设计 * 安全审计 一句话：**任务能清晰切片，就交给子代理。** # Agent 团队 Agent 团队 / Agent Teams [#agent-团队--agent-teams] Team Runtime 是 OpenCowork 的“多 Agent 协作层”。它和 `Task` 子代理不是一回事： * `Task` 负责启动一个专用子代理 * Team Runtime 负责 lead / worker 协作、消息通信、任务分配和运行状态 相关工具 / Related tools [#相关工具--related-tools] * `TeamCreate` * `SendMessage` * `TeamStatus` * `TeamDelete` * `TaskCreate` / `TaskUpdate` / `TaskGet` / `TaskList` 运行模型 / Runtime model [#运行模型--runtime-model] | 角色 | 作用 | | ------ | --------------- | | Lead | 负责协调、汇总、对用户输出 | | Worker | 执行子任务、回传进度、请求帮助 | Worker 可以使用两种 backend： * `in-process` * `isolated-renderer` 团队状态 / Team status [#团队状态--team-status] Team Runtime 使用 shared types 描述成员、消息和任务： * Member：`working` / `idle` / `waiting` / `stopped` * Task：`pending` / `in_progress` / `completed` * Message：`message` / `broadcast` / `shutdown_request` / `permission_request` / `plan_approval_request` 等 持久化目录 / Persistence directory [#持久化目录--persistence-directory] 每个 team 都会存到： ```text ~/.open-cowork/teams// ├── team.json └── messages.json ``` 其中： * `team.json` 存 manifest、成员和任务 * `messages.json` 存最近消息记录 权限模式 / Permission mode [#权限模式--permission-mode] Team Runtime 支持两种权限模式： * `default` * `plan` 在 `plan` 模式下，worker 需要先完成计划审批，再推进实现。 Team events / Event flow [#team-events--event-flow] Team 相关事件会把 UI 拉到右侧 team 面板，让你实时看到： * 成员加入 / 移除 * 任务创建 / 认领 / 完成 * worker 消息 * 运行状态变化 worker 的两种启动方式 / Worker startup modes [#worker-的两种启动方式--worker-startup-modes] 1) in-process [#1-in-process] 轻量，启动快，适合一般协作任务。 2) isolated-renderer [#2-isolated-renderer] 会起一个独立的 BrowserWindow / renderer，适合更重的、需要更强隔离的任务。 什么时候用团队？ / When to use teams? [#什么时候用团队--when-to-use-teams] * 多个子任务天然可以并行 * 你希望 lead 统一汇总结果 * 你想把“任务分派”和“结果回收”分开 * 你要一个长期运行、可追踪的协作结构 # FAQ FAQ [#faq] OpenCowork 和普通聊天客户端有什么区别？ [#opencowork-和普通聊天客户端有什么区别] OpenCowork 让 Agent 在本地工作区里执行工具。它可以读取文件、搜索代码、调用 Shell、使用 MCP、接入消息平台，并通过子代理或团队协作拆分任务。 数据放在哪里？ [#数据放在哪里] 运行时数据放在 `~/.open-cowork/`，包括 SQLite 数据库、配置、agents、commands 和 prompts。该目录不要提交到仓库。 文档站和桌面应用是一套构建吗？ [#文档站和桌面应用是一套构建吗] 不是。桌面应用在仓库根目录构建；文档站在 `docs/` 下构建，基于 Fumadocs、Next.js 和 MDX。 如何选择模型？ [#如何选择模型] 先从 [Models](/docs/models) 选择 provider，再在设置中配置默认模型。需要本地模型时优先看 Ollama 或 OpenAI-compatible providers。 什么时候使用子代理？ [#什么时候使用子代理] 当任务可以清晰切片，例如代码审查、架构分析、安全审计、数据分析或文案生成时，使用 [Sub-agents](/docs/agents/sub-agents)。 # Help Help [#help] 先按症状定位，再回到对应栏目深入。OpenCowork 是本地应用，很多问题都来自本地依赖、工作目录、模型凭据、消息平台凭据或运行时数据。 Fast path [#fast-path] ```bash npm run typecheck npm run lint npm run build ``` 如果问题只出现在文档站，在 `docs/` 目录运行： ```bash npm run types:check npm run build ``` # Troubleshooting Troubleshooting [#troubleshooting] App does not start [#app-does-not-start] 1. 确认 Node.js 版本满足项目要求。 2. 重新安装依赖并运行 native module rebuild。 3. 运行类型检查，先排除编译错误。 ```bash npm install npm run postinstall npm run typecheck ``` Docs build fails [#docs-build-fails] 文档站是独立 Next.js 应用，先进入 `docs/` 再检查。 ```bash cd docs npm install npm run types:check npm run build ``` 常见原因： * MDX frontmatter 缺少 `title` 或语法错误。 * `meta.json` 引用了不存在的页面。 * 组件名没有在 `src/mdx-components.tsx` 注册。 Model calls fail [#model-calls-fail] * 检查 provider preset 是否启用。 * 检查 API key 或 OAuth 状态。 * 尝试切换到另一个 provider，确认是不是单个服务不可用。 Channel integration fails [#channel-integration-fails] * 先确认 channel credentials。 * 再检查平台侧 webhook、socket 或机器人权限。 * 最后看 OpenCowork channel 页面里的专项配置。 Tool result looks stale [#tool-result-looks-stale] * 确认当前 session 绑定的 workspace。 * 检查文件是否由外部进程改动。 * 重新打开 preview 或刷新对应面板。 # Install Install [#install] OpenCowork 是 Electron 桌面应用。开发环境需要 Node.js 18 或更高版本；发布版本通过 GitHub Releases 分发。 Windows 上 `node-pty` 会被 postinstall 脚本跳过；`better-sqlite3`、`@jitsi/robotjs`、`ssh2` 等 native modules 仍需要按 Electron 版本 rebuild。 Desktop release [#desktop-release] ```bash https://github.com/AIDotNet/OpenCowork/releases/latest ``` 选择与你系统匹配的安装包： | Platform | Package | | -------- | ------------------ | | Windows | `.exe` installer | | macOS | `.dmg` | | Linux | AppImage or `.deb` | From source [#from-source] ```bash git clone https://github.com/AIDotNet/OpenCowork.git cd OpenCowork npm install npm run postinstall npm run dev ``` 首次启动时，Vite 会编译较多 React 模块，可能需要约 30 秒。之后会明显更快。 Build installers [#build-installers] ```bash npm run typecheck npm run build npm run build:win ``` Verify [#verify] ```bash npm run typecheck npm run lint ``` Local data directory [#local-data-directory] 运行时数据默认保存在： ```text ~/.open-cowork/ ``` 这里会包含： * `data.db`：SQLite 数据库。 * `config`：本地配置。 * `agents/`：用户可编辑 agent。 * `commands/`：用户命令。 * `prompts/`：提示词。 这个目录包含用户本地数据，不应提交到 Git 仓库。 Docs site [#docs-site] 文档站点在 `docs/` 目录中，是独立的 Fumadocs + Next.js 应用： ```bash cd docs npm install npm run dev ``` # Anthropic Anthropic / Claude [#anthropic--claude] Anthropic 是 OpenCowork 的原生提供商之一，适合需要稳定思考流、视觉输入和高质量代码协作的场景。 配置入口 / Setup [#配置入口--setup] 进入 **设置 → AI 提供商 → Anthropic**，填入 API Key 即可。通常不需要改 Base URL。 典型能力 / Typical capabilities [#典型能力--typical-capabilities] * 思考流（thinking） * 视觉输入（vision） * 稳定的长上下文交互 * 适合复杂代码、分析和规划任务 常见模型 / Common model examples [#常见模型--common-model-examples] | 模型 | 场景 | | ----------------- | --------- | | `claude-opus-*` | 最高能力、复杂任务 | | `claude-sonnet-*` | 平衡能力与速度 | | `claude-haiku-*` | 快速、低成本 | > 具体模型名会随 Anthropic 版本迭代而变化，文档里保留“常见示例”即可。 Thinking / 思考流 [#thinking--思考流] Anthropic 的 thinking 输出会被映射成统一的 `thinking_delta` / `thinking_encrypted` 事件，然后在 UI 中单独渲染。 Vision / 视觉 [#vision--视觉] Claude 系列支持图片输入，适合： * 截图分析 * 设计稿评审 * 图文混合输入 * 带图的故障排查 什么时候选 Anthropic？ / When to choose it? [#什么时候选-anthropic--when-to-choose-it] * 你要最稳定的长对话体验 * 你要比较强的 reasoning + coding 质量 * 你需要把图片一起喂给模型 # DeepSeek DeepSeek [#deepseek] DeepSeek 是 OpenCowork 里非常常用的 OpenAI-compatible 提供商之一，适合中文任务、代码任务和推理任务。 配置入口 / Setup [#配置入口--setup] 进入 **设置 → AI 提供商 → DeepSeek**，通常需要： | 配置项 | 值 | | -------- | ----------------------------- | | 协议 | `openai-chat` | | Base URL | `https://api.deepseek.com/v1` | | API Key | 你的 DeepSeek key | 常见模型 / Common model examples [#常见模型--common-model-examples] | 模型 | 作用 | | ------------------- | ------------ | | `deepseek-chat` | 通用对话 | | `deepseek-reasoner` | 推理任务 / R1 风格 | 特点 / Characteristics [#特点--characteristics] * 通过 OpenAI-compatible 接口接入 * 适合中文场景 * 适合复杂推理和代码辅助 * 对 token 成本比较敏感的场景很常用 推理模式 / Reasoning mode [#推理模式--reasoning-mode] 如果模型返回 reasoning-style 内容，OpenCowork 会把它转换成统一的 thinking 流，然后在 UI 中显示。 什么时候选 DeepSeek？ / When to choose it? [#什么时候选-deepseek--when-to-choose-it] * 你需要一个成本更友好的主力模型 * 你经常处理中文内容 * 你想把推理模型当作默认协作模型 # Google Gemini Google Gemini [#google-gemini] Gemini 适合超长上下文、多模态输入和大量文档处理任务。 配置入口 / Setup [#配置入口--setup] 进入 **设置 → AI 提供商 → Google**，通常会配置： | 配置项 | 值 | | -------- | --------------------------------------------------------- | | 协议 | `openai-chat` | | Base URL | `https://generativelanguage.googleapis.com/v1beta/openai` | | API Key | Google AI Studio 的 key | 常见模型 / Common model examples [#常见模型--common-model-examples] | 模型 | 场景 | | --------------------------- | ------------- | | `gemini-2.0-flash` | 快速、多模态 | | `gemini-2.5-pro` | 更强能力 | | `gemini-2.0-flash-thinking` | 推理 / thinking | 特点 / Characteristics [#特点--characteristics] * 超长上下文窗口 * 图片 / 视频 / 音频等多模态能力 * 适合长文档和复杂上下文整理 * 通过 OpenAI-compatible 接口接入 OpenCowork 什么时候选 Gemini？ / When to choose it? [#什么时候选-gemini--when-to-choose-it] * 你要处理超长文档 * 你要混合图片和文本 * 你希望一个模型能扛住比较长的上下文 # Models Models [#models] OpenCowork 的模型层是 provider-agnostic 的。Renderer store 管理 provider preset 和用户配置，Agent runtime 接收通用 provider 对象。 Runtime adapters [#runtime-adapters] | Adapter | 用途 | | ---------------- | ---------------- | | Anthropic | Claude API | | OpenAI Chat | Chat Completions | | OpenAI Responses | Responses API | | OpenAI Images | 图像生成 | | Gemini | Google Gemini | Built-in presets [#built-in-presets] 当前仓库内置多组 provider preset，包括： * OpenAI / Azure OpenAI / OpenRouter / Gitee AI / SiliconFlow。 * Anthropic / DeepSeek / Moonshot / Qwen / MiniMax / Baidu。 * Google / Gemini。 * Ollama / LM Studio compatible paths。 * Copilot / Codex OAuth。 Where config lives [#where-config-lives] * Renderer store：`src/renderer/src/stores/provider-store.ts` * Provider presets：`src/renderer/src/stores/providers/` * API clients：`src/renderer/src/lib/api/` * 安全存储：main process 的 secure key store Next [#next] * [Anthropic](/docs/models/anthropic) * [OpenAI](/docs/models/openai) * [DeepSeek](/docs/models/deepseek) * [Google](/docs/models/google) * [Ollama](/docs/models/ollama) # Ollama Ollama [#ollama] Ollama 是 OpenCowork 里最适合“离线 / 本地优先”场景的 provider。 安装 / Install [#安装--install] 从 [ollama.com](https://ollama.com/) 安装 Ollama，然后拉取模型： ```bash ollama pull llama3.2 ollama pull qwen2.5 ollama pull deepseek-r1:7b ``` 配置入口 / Setup [#配置入口--setup] 进入 **设置 → AI 提供商 → Ollama**，通常配置： | 配置项 | 值 | | -------- | --------------------------- | | 协议 | `openai-chat` | | Base URL | `http://localhost:11434/v1` | | API Key | 任意字符串（常见写法是 `ollama`） | 推荐模型 / Recommended models [#推荐模型--recommended-models] | 模型 | 场景 | | ---------------- | ---- | | `llama3.2:3b` | 低配机器 | | `llama3.2:8b` | 通用对话 | | `qwen2.5:7b` | 中文优化 | | `deepseek-r1:7b` | 本地推理 | | `codellama:13b` | 代码生成 | 特点 / Characteristics [#特点--characteristics] * 不需要云端 API Key * 数据留在本机 * 适合测试、离线和隐私敏感场景 * 本地性能取决于你的机器配置 什么时候选 Ollama？ / When to choose it? [#什么时候选-ollama--when-to-choose-it] * 你想先把工作流跑通 * 你不能把数据发到云端 * 你想本地验证 prompt / tool 流程 # OpenAI OpenAI / Azure OpenAI [#openai--azure-openai] OpenCowork 对 OpenAI 系列提供了三条主线： * **openai-chat**：Chat Completions 风格接口 * **openai-responses**：Responses API * **openai-images**：图像生成 配置入口 / Setup [#配置入口--setup] 进入 **设置 → AI 提供商 → OpenAI**，填入 API Key。默认 Base URL 是： ```text https://api.openai.com/v1 ``` 如果你用的是 Azure OpenAI，可以把 Base URL 指向你的 Azure deployment 路径。 常见模型 / Common model examples [#常见模型--common-model-examples] | 协议 | 典型用途 | 示例 | | ------------------------------ | ---------------------------- | -------------------------------- | | `openai-chat` | 通用对话、视觉、图像相关能力 | `gpt-4o`、`gpt-4o-mini`、`gpt-4.1` | | `openai-responses` | reasoning / 新版 Responses API | `o1`、`o3-mini` | | `openai-chat` + image category | 图像生成 | `dall-e-3`、Flux 类图像模型 | > 模型名称会随 OpenAI / Azure / 代理网关的配置而变化，文档中以“常见示例”为准。 Responses API [#responses-api] Responses API 适合需要： * reasoning 流式输出 * 更统一的 response id 续接 * 新版工具调用语义 OpenCowork 会把 Responses 事件转换成统一的 stream events，再交给 Agent Loop。 Azure OpenAI [#azure-openai] Azure OpenAI 本质上也是 OpenAI-compatible，只是 Base URL 和 deployment 方式不同。配置时通常需要： * Azure resource base URL * 对应的 deployment 名称 * Azure API key 图像生成 / Image generation [#图像生成--image-generation] 如果模型被标记为 `category = image`，就可以被图像插件识别，并通过 `ImageGenerate` 工具调用。 你在代码里会看到什么 / What to look for [#你在代码里会看到什么--what-to-look-for] * `src/renderer/src/lib/api/openai-chat.ts` * `src/renderer/src/lib/api/openai-responses.ts` * `src/renderer/src/lib/api/openai-images.ts` * `src/renderer/src/lib/api/openai-images-provider.ts` * `src/renderer/src/stores/providers/openai.ts` * `src/renderer/src/stores/providers/azure-openai.ts` # 其他提供商 其他提供商 / Other Providers [#其他提供商--other-providers] 这一页汇总的是 OpenCowork 里已经预置好的其他 provider preset。它们大多是 **OpenAI-compatible**，少数是 OAuth 或专用 preset。 OpenAI-compatible 预设 / Compatible presets [#openai-compatible-预设--compatible-presets] | 提供商 | Base URL / 说明 | | ------------ | --------------------------------------------------- | | Qwen | `https://dashscope.aliyuncs.com/compatible-mode/v1` | | Moonshot | `https://api.moonshot.cn/v1` | | MiniMax | `https://api.minimax.chat/v1` | | 百度文心 | `https://qianfan.baidubce.com/v2` | | SiliconFlow | `https://api.siliconflow.cn/v1` | | Azure OpenAI | 自定义 Azure deployment URL | | OpenRouter | OpenAI-compatible gateway | | Gitee AI | Gitee AI endpoint | | Xiaomi | 小米 AI 相关 preset | | BigModel | 智谱 / BigModel preset | | LongCat | LongCat preset | | Routin AI | Routin AI preset | OAuth 类预设 / OAuth presets [#oauth-类预设--oauth-presets] | 提供商 | 说明 | | ------------- | --------------------------- | | Codex OAuth | 通过系统浏览器授权后接入 OpenAI 相关接口 | | Copilot OAuth | GitHub Copilot OAuth preset | 适合什么场景？ / When to use them? [#适合什么场景--when-to-use-them] * 你已经有第三方 AI 平台账号 * 你想换更便宜的 API * 你想用企业自己的网关 * 你想用不止一个 provider，按任务切换 配置思路 / Configuration idea [#配置思路--configuration-idea] 1. 先选一个 provider preset 2. 填 API Key 或 OAuth 信息 3. 检查 Base URL 4. 选择模型 5. 确认模型 category 和能力标志 关键提醒 / Important reminder [#关键提醒--important-reminder] 只要服务兼容 OpenAI Chat Completions API，通常都能用 `openai-chat` 方式接入；如果要 reasoning 或更特殊的流式特性，再看具体 preset 是否需要单独 adapter。 # AI 提供商体系 AI 提供商体系 / API Providers [#ai-提供商体系--api-providers] OpenCowork 的 provider 层位于 `src/renderer/src/lib/api/`，它把不同供应商的 API 差异收敛到统一的调用模型里。 运行时适配器 / Runtime adapters [#运行时适配器--runtime-adapters] 应用启动时会注册 5 个运行时 adapter： * `anthropic` * `openai-chat` * `openai-responses` * `openai-images` * `gemini` 这 5 个 adapter 负责真正的请求、流式输出和图像生成事件。 内置预设 / Built-in presets [#内置预设--built-in-presets] `src/renderer/src/stores/providers/` 下维护了 24 个内置 provider preset，覆盖： * Anthropic / Claude * OpenAI / Azure OpenAI * Google / Gemini * Ollama * DeepSeek * Qwen * Moonshot * MiniMax * Baidu / ERNIE * SiliconFlow * Gitee AI * Codex OAuth * Copilot OAuth * Xiaomi * BigModel * LongCat * Routin AI * OpenRouter > 其中很多 preset 本质上是 OpenAI-compatible，只是默认 Base URL、认证方式或模型集合不同。 统一模型 / Unified model config [#统一模型--unified-model-config] 模型配置通常包含这些信息： | 字段 | 作用 | | -------------------- | ---------------- | | `id` / `name` | 模型标识和显示名 | | `category` | `chat` 或 `image` | | `vision` | 是否支持图片输入 | | `thinking` | 是否支持思考流 | | `reasoning` | 是否支持推理模型 | | `baseUrl` | 自定义 API 地址 | | `apiKey` | 认证凭据 | | `input/output price` | 费用估算 | 流式事件 / Stream events [#流式事件--stream-events] provider 层会把 API 响应转成统一的流事件，例如： * `text_delta` * `thinking_delta` * `thinking_encrypted` * `tool_call_start` * `tool_call_delta` * `tool_call_end` * `image_generated` * `image_error` * `message_end` * `request_debug` 这些事件再被 Agent Loop 消费，最终驱动 UI。 图像生成 / Image generation [#图像生成--image-generation] 图像模型只有在 `category = image` 时才会被图像插件识别。换句话说： * provider 负责提供模型 * app plugin 决定是否把这个模型暴露成 `ImageGenerate` OpenAI-compatible 规则 / Compatibility rule [#openai-compatible-规则--compatibility-rule] 只要一个服务兼容 OpenAI Chat Completions API，就可以通过 `openai-chat` 协议接入。必要时只改： * Base URL * API Key * 模型名 这也是为什么很多第三方模型都能直接进入 OpenCowork。 你在代码里会看到什么 / What to look for in code [#你在代码里会看到什么--what-to-look-for-in-code] * `src/renderer/src/lib/api/index.ts`：运行时 adapter 注册入口 * `src/renderer/src/stores/providers/`：内置 provider preset * `src/renderer/src/lib/api/types.ts`：统一消息、流事件、usage 类型 * `src/renderer/src/lib/api/provider.ts`：具体 provider 创建与发送逻辑 # 基础配置 基础配置 / Configuration [#基础配置--configuration] 设置面板 / Settings panel [#设置面板--settings-panel] 通过右上角的设置按钮打开设置面板。常见的标签页包括： * General / General * Memory / Memory * Analytics / Analytics * Migration / Migration * Provider / Provider * Model management / Model management * Model / Model * Plugin / Plugin * Channel / Channel * MCP / MCP * Web search / Web search * Skills market / Skills market * About / About 主要配置项 / Main configuration areas [#主要配置项--main-configuration-areas] AI 提供商 [#ai-提供商] 在 **AI 提供商** 中添加 provider 和 model。每个模型可配置： * 名称 * Base URL * API Key * category：`chat` / `image` * `vision` * `thinking` * `reasoning` * 价格信息（可选） > 图像模型必须标记为 `image`，这样图像插件才会把它识别为可用输入源。 工作目录 [#工作目录] 工作目录决定文件工具和 Shell 工具默认作用的路径。你可以： * 为全局设置默认目录 * 为某个项目单独指定目录 * 在会话中覆盖当前目录 代理 [#代理] `systemProxyUrl` 会直接应用到 Electron 的默认 session 代理设置。 Web 搜索 [#web-搜索] 可配置 Web 搜索提供商、API Key、超时参数等，让 `WebSearch` / `WebFetch` 工具可用。 消息平台 / Channels [#消息平台--channels] 聊天频道在 **设置 → 聊天频道** 中配置，配置会保存到 `plugins.json`。 MCP [#mcp] MCP 服务器配置保存在 `mcp-servers.json`，并可按项目绑定。 持久化文件 / Persistence files [#持久化文件--persistence-files] | 文件 | 作用 | | --------------------------------- | -------------------------------------------- | | `~/.open-cowork/data.db` | 会话、消息、计划、任务、Cron、SSH、Wiki、Goal、Usage 等主要业务数据 | | `~/.open-cowork/settings.json` | 设置面板中的通用偏好 | | `~/.open-cowork/config.json` | 需要安全保存的配置片段 | | `~/.open-cowork/mcp-servers.json` | MCP 服务器配置 | | `~/.open-cowork/plugins.json` | 消息平台插件实例 | | `~/.open-cowork/teams/` | Team Runtime 状态 | | `~/.open-cowork/agents/` | 用户自定义 sub-agent | | `~/.open-cowork/commands/` | 用户自定义 slash commands | | `~/.open-cowork/prompts/` | 用户自定义 prompt 模板 | | `~/.agents/skills/` | Skills 存放目录（内置内容首次运行后同步到这里） | 常见问题 / Common questions [#常见问题--common-questions] 为什么改了 provider 配置后立刻生效？ [#为什么改了-provider-配置后立刻生效] 因为 provider 配置会通过本地持久化存储和 store 同步，不需要重新安装应用。 为什么系统代理会影响整个应用？ [#为什么系统代理会影响整个应用] 因为代理直接配置到了 Electron 的 `defaultSession`。 为什么我找不到 skills 目录？ [#为什么我找不到-skills-目录] Skills 不在 `~/.open-cowork/skills/`，而是在 `~/.agents/skills/`。 # 定时任务 定时任务 / Cron Jobs [#定时任务--cron-jobs] OpenCowork 的 Cron 系统把“让 Agent 稍后执行”变成了可持久化、可审计、可回放的任务。入口工具是 `CronAdd`。 支持的调度 / Supported schedules [#支持的调度--supported-schedules] | kind | 含义 | 示例 | | ------- | --------------- | ------------------ | | `at` | 一次性延迟执行 | `+10m`、`+2h`、`+1d` | | `every` | 固定间隔重复执行 | `3600000`（1 小时） | | `cron` | 标准 5 段 cron 表达式 | `0 9 * * *` | 关键规则 / Important rules [#关键规则--important-rules] * `at` 必须使用相对时间偏移，**不要**传 ISO 时间戳 * `deleteAfterRun=true` 时，任务默认会在执行后清理 * CronAgent 默认会把结果发到桌面通知 * 如果你传了 `pluginId + pluginChatId`，结果可以转发到消息平台 工具入口 / Tool API [#工具入口--tool-api] CronAdd [#cronadd] `CronAdd` 接受的核心字段包括： * `name` * `schedule` * `prompt` * `agentId` * `model` * `workingFolder` * `sshConnectionId` * `deliveryMode` * `deliveryTarget` * `deleteAfterRun` * `maxIterations` * `pluginId` * `pluginChatId` * `sourceProviderId` * `sourceSessionTitle` * `sourceProjectId` * `sourceProjectName` 其他操作 [#其他操作] * `CronUpdate` * `CronRemove` * `CronList` 数据库结构 / Database structure [#数据库结构--database-structure] Cron 相关数据落在这些表里： * `cron_jobs` * `cron_runs` * `cron_run_messages` * `cron_run_logs` cron_jobs 关键字段 [#cron_jobs-关键字段] | 字段 | 作用 | | ------------------------------ | ------------------------ | | `schedule_kind` | at / every / cron | | `schedule_at` | 一次性执行时间 | | `schedule_every` | 间隔毫秒数 | | `schedule_expr` | cron 表达式 | | `schedule_tz` | 时区 | | `agent_id` | 指定子代理 | | `model` | 模型覆盖 | | `working_folder` | 执行目录 | | `ssh_connection_id` | 远程执行上下文 | | `session_id` | 来源 session | | `delivery_mode` | desktop / session / none | | `delivery_target` | session 目标 | | `plugin_id` / `plugin_chat_id` | 消息平台投递目标 | | `enabled` | 是否启用 | | `delete_after_run` | 运行后删除 | | `last_fired_at` | 最近触发时间 | | `fire_count` | 触发次数 | | `deleted_at` | 软删除时间 | cron_runs 会保存快照 [#cron_runs-会保存快照] 每次执行都会记录： * job 名称快照 * prompt 快照 * session / project / provider 快照 * model / working folder / delivery 快照 * 执行状态和输出摘要 运行方式 / Runtime behavior [#运行方式--runtime-behavior] * 应用启动时会恢复已持久化且启用的 jobs * 运行时会做并发限制 * 每次触发都会更新统计并写 run history * `Notify` 和 plugin 投递会共享一套 delivery 语义 典型场景 / Typical use cases [#典型场景--typical-use-cases] * 每天固定时间生成汇报 * 每小时检查日志并通知 * 周期性拉取外部系统数据 * 在指定 SSH 环境里执行巡检脚本 * 用消息平台定时推送结果 # 数据库设计 数据库设计 / Database Design [#数据库设计--database-design] OpenCowork 使用 **SQLite + better-sqlite3** 作为本地持久化核心。数据库文件位于 `~/.open-cowork/data.db`，初始化入口在 `src/main/db/database.ts`。 基础配置 / Database config [#基础配置--database-config] | 项 | 值 | | ---- | ------------------------ | | 引擎 | `better-sqlite3` | | 位置 | `~/.open-cowork/data.db` | | 模式 | WAL | | 外键 | `foreign_keys = ON` | | 迁移方式 | 集中建表 + 幂等列补齐 | 主要数据域 / Main domains [#主要数据域--main-domains] 1) 会话与消息 / Sessions & messages [#1-会话与消息--sessions--messages] ```sql CREATE TABLE sessions ( id TEXT PRIMARY KEY, title TEXT NOT NULL, mode TEXT NOT NULL DEFAULT 'chat', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, message_count INTEGER NOT NULL DEFAULT 0, working_folder TEXT, pinned INTEGER DEFAULT 0, icon TEXT, plugin_id TEXT, ssh_connection_id TEXT, project_id TEXT, provider_id TEXT, model_id TEXT, plan_id TEXT, external_chat_id TEXT ); CREATE TABLE messages ( id TEXT PRIMARY KEY, session_id TEXT NOT NULL, role TEXT NOT NULL, content TEXT NOT NULL, meta TEXT, created_at INTEGER NOT NULL, usage TEXT, sort_order INTEGER NOT NULL, FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE ); ``` 2) 项目、计划、任务 / Projects, plans, tasks [#2-项目计划任务--projects-plans-tasks] ```sql CREATE TABLE projects ( id TEXT PRIMARY KEY, name TEXT NOT NULL, working_folder TEXT, ssh_connection_id TEXT, plugin_id TEXT, pinned INTEGER DEFAULT 0, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL ); CREATE TABLE plans ( id TEXT PRIMARY KEY, session_id TEXT NOT NULL, title TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'drafting', file_path TEXT, content TEXT, spec_json TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE ); CREATE TABLE tasks ( id TEXT PRIMARY KEY, session_id TEXT NOT NULL, plan_id TEXT, subject TEXT NOT NULL, description TEXT NOT NULL DEFAULT '', active_form TEXT, status TEXT NOT NULL DEFAULT 'pending', owner TEXT, blocks TEXT DEFAULT '[]', blocked_by TEXT DEFAULT '[]', metadata TEXT, sort_order INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE, FOREIGN KEY (plan_id) REFERENCES plans(id) ON DELETE SET NULL ); ``` 3) 计划与目标 / Goals [#3-计划与目标--goals] ```sql CREATE TABLE session_goals ( session_id TEXT PRIMARY KEY NOT NULL, goal_id TEXT NOT NULL, objective TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('active', 'paused', 'budget_limited', 'complete')), token_budget INTEGER, tokens_used INTEGER NOT NULL DEFAULT 0, time_used_seconds INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL ); CREATE TABLE session_goal_events ( id TEXT PRIMARY KEY, session_id TEXT NOT NULL, goal_id TEXT, event_type TEXT NOT NULL, message TEXT, metadata_json TEXT, created_at INTEGER NOT NULL ); ``` 4) Cron / Scheduling [#4-cron--scheduling] ```sql cron_jobs cron_runs cron_run_messages cron_run_logs ``` `cron_jobs` 保存调度定义，`cron_runs` 保存每次运行快照，`cron_run_messages` / `cron_run_logs` 保存过程记录。 5) SSH / Remote access [#5-ssh--remote-access] ```sql ssh_groups ssh_connections ``` SSH 不只是连接配置，还承载远程目录、身份认证、默认目录、代理跳转、保活间隔等信息。 6) Wiki / Knowledge base [#6-wiki--knowledge-base] ```sql wiki_documents wiki_sections wiki_section_sources wiki_project_state wiki_generation_runs ``` 7) 可观测性 / Observability [#7-可观测性--observability] ```sql usage_events draw_runs agent_change_sets agent_file_changes qq_wakeup_windows ``` 迁移策略 / Migration strategy [#迁移策略--migration-strategy] OpenCowork 采用的是“**加列不删列**”的演进策略： * 先集中 `CREATE TABLE IF NOT EXISTS` * 再通过 `ensureColumn()` 或 `ALTER TABLE ... ADD COLUMN` 补齐旧列 * 再做少量回填，例如把旧 sessions 迁移到 projects 这种策略简单、稳定，也适合桌面应用的本地数据库。 设计结论 / Design takeaways [#设计结论--design-takeaways] * 数据库已经从“聊天记录仓库”演进成“本地 Agent 工作台的核心存储层” * 主线关系是：`project -> session -> messages / plans / tasks` * Cron、SSH、Wiki、Goal、Usage 都是一级对象，不是附属功能 * 文档里如果看到旧 schema，应该以 `src/main/db/database.ts` 为准 # Ops Ops [#ops] Ops 页面面向“运行起来以后”的问题：配置怎么生效、Cron 如何调度、SQLite 数据放在哪里、什么时候需要检查本地状态。 Operator checklist [#operator-checklist] 确认 provider、channel、MCP、agent 和 workspace 设置。 确认 Electron main process、IPC handlers 和 renderer stores 状态一致。 确认 `~/.open-cowork/data.db` 和本地资源目录存在。 Useful commands [#useful-commands] ```bash npm run typecheck npm run lint npm run build ``` # Electron 进程模型 Electron 进程模型 / Electron Process Model [#electron-进程模型--electron-process-model] OpenCowork 的 Electron 架构不是“一个窗口 + 一个渲染页”这么简单，而是一个有明确边界的四层系统：**Main、Preload、Renderer、Shared**。 进程边界 / Process boundaries [#进程边界--process-boundaries] | 层 | 入口 | 职责 | | -------- | --------------------------- | ------------------------------------------------------- | | Main | `src/main/index.ts` | 窗口、托盘、数据库、IPC、MCP、Cron、SSH、消息平台、更新、崩溃日志 | | Preload | `src/preload/index.ts` | 只暴露白名单 API，提供最小安全桥接 | | Renderer | `src/renderer/src/main.tsx` | UI、Agent Loop、Tool Registry、Stores、Preview、Team Runtime | | Shared | `src/shared/` | 跨进程类型、事件协议、消息协议、Team Runtime 契约 | Main 进程 / Main process [#main-进程--main-process] 主进程承担所有“系统级”能力： * 注册 `fs`、`db`、`settings`、`config`、`mcp`、`cron`、`ssh`、`plugin`、`channel`、`notify`、`screenshot`、`web-search`、`oauth`、`git`、`wiki`、`migration`、`sidecar`、`team-runtime`、`team-worker` 等 IPC * 管理 SQLite 数据库和本地数据目录 * 创建窗口、通知窗口、托盘和更新器 * 运行主进程 Agent Runtime，为 Cron 和插件自动回复复用同一套协议 * 负责退出时的清理：停止 channel、mcp、cron、ssh、terminal、worker 和数据库 Renderer 进程 / Renderer process [#renderer-进程--renderer-process] 渲染进程承担 UI 和 Agent 工作流： * React UI 和右侧面板 * Agent Loop 和流式事件渲染 * Provider 调用和流式文本 / thinking / tool-use 处理 * Tool Registry 和审批流 * 计划、任务、团队、MCP、插件、预览和浏览器面板 渲染进程是“工作台”，不是“系统权限入口”。它不直接操作文件系统、数据库或 SSH，而是通过 IPC 和工具系统请求主进程。 Preload 脚本 / Preload script [#preload-脚本--preload-script] Preload 只暴露经过筛选的桥接： * `window.electron`：Electron IPC 的安全子集 * `window.api`：图像、Team Runtime、Team Worker 等最小必要 API 这层的目标是把“能做什么”控制得很窄，把“谁能调用什么”变得清晰。 Shared / 共享契约 [#shared--共享契约] `src/shared/` 维护跨进程类型契约，主要包括： * Agent loop 事件协议 * Team Runtime 类型 * OpenAI / Anthropic / Responses 消息结构 * 迁移相关类型 主进程为什么还要有 Agent Runtime？ [#主进程为什么还要有-agent-runtime] 因为有些工作并不来自用户窗口： * Cron 定时任务 * 消息平台自动回复 * 后台队列式任务 * 某些需要独立生命周期的系统自动化 这些场景会复用主进程 JS Agent Runtime，而不是强行依赖前台 UI。 安全结论 / Security takeaway [#安全结论--security-takeaway] * renderer 负责表达和编排 * main 负责系统与持久化 * preload 负责安全桥接 * shared 负责协议稳定 这四层分工，是 OpenCowork 能同时兼顾“可用性”和“可控性”的基础。 # Platforms Platforms [#platforms] OpenCowork 是桌面应用，核心运行在 Electron main process，界面运行在 React renderer，系统能力通过 preload 暴露为窄 IPC surface。 Supported desktop targets [#supported-desktop-targets] | Platform | Notes | | -------- | ---------------------------------------------- | | Windows | 主要开发与打包目标；`node-pty` 在 Windows postinstall 中跳过 | | macOS | 支持 DMG 构建，签名/entitlements 在 `build/` 中配置 | | Linux | 支持 AppImage/deb 等 Electron Builder 输出 | Local data [#local-data] 运行时数据保存在 `~/.open-cowork/`。这里包含 SQLite 数据库、配置、agents、commands 和 prompts。不要把该目录提交到仓库。 # 整体架构概述 整体架构概述 / Architecture Overview [#整体架构概述--architecture-overview] OpenCowork 的实现可以概括为一句话：**Electron 主进程负责系统能力，渲染进程负责 Agent 运行时和 UI，Preload 只暴露最小桥接，Shared 维护跨进程契约。** 架构图 / Architecture diagram [#架构图--architecture-diagram] 四层职责 / Four layers [#四层职责--four-layers] 1) Main [#1-main] 入口是 `src/main/index.ts`。主进程负责： * 创建窗口、托盘和更新器 * 注册所有 IPC handlers * 管理 SQLite 数据库 * 管理 Cron、SSH、MCP 和消息平台插件 * 处理崩溃日志和系统级错误 * 在启动和退出时统一清理后台资源 2) Preload [#2-preload] 入口是 `src/preload/index.ts`。它只暴露少量能力： * image 下载 / base64 / 剪贴板 * Team Runtime 创建、快照、消息、成员更新 * Team Worker 的启动与停止 这层是安全边界，不承载业务逻辑。 3) Renderer [#3-renderer] 入口是 `src/renderer/src/main.tsx`。它承担： * React UI * Agent Loop * Tool Registry * Provider 适配 * 计划 / 任务 / 团队 / 资源面板 * 文件预览与浏览器面板 * 应用插件工具注册 4) Shared [#4-shared] `src/shared/` 集中放： * Agent stream / loop 协议 * Team Runtime 类型 * OpenAI / Anthropic 消息协议 * 迁移类型与其他跨进程 DTO 关键运行时 / Key runtime components [#关键运行时--key-runtime-components] | 组件 | 作用 | 位置 | | ------------------ | ------------------------------ | --------------------------------------------- | | `ChannelManager` | 管理 8 个消息平台插件 | `src/main/channels/` | | `McpManager` | 管理 MCP server 连接和能力发现 | `src/main/mcp/` | | `CronScheduler` | 处理 at / every / cron 调度 | `src/main/cron/` | | `JS Agent Runtime` | 供 Cron 和插件自动回复复用的主进程 Agent 运行时 | `src/main/ipc/js-agent-runtime.ts` | | `Tool Registry` | 统一注册与调用工具 | `src/renderer/src/lib/agent/tool-registry.ts` | | `viewerRegistry` | 注册文件预览器 | `src/renderer/src/lib/preview/` | 数据流 / Data flow [#数据流--data-flow] 1. 用户在 UI 中发起聊天、计划、任务或插件动作。 2. React store 更新本地运行态。 3. Agent Loop 通过 provider 发起模型请求并接收流式事件。 4. 工具调用被分发到 renderer、本地 store、主进程 IPC、MCP、Team Runtime 或插件服务。 5. 主进程负责落盘、系统调用、消息平台交互和后台调度。 6. 结果回流到 store，再驱动 UI、右侧面板、通知窗口或外部消息平台。 设计原则 / Design principles [#设计原则--design-principles] * **本地优先**：默认不依赖外部托管状态。 * **边界清晰**：系统能力不直接暴露给 renderer。 * **协议先行**：跨进程和跨 runtime 的对象优先定义在 `shared/`。 * **可插拔**：provider、channel、MCP、skill、command、agent 都是注册式扩展。 * **可追溯**：任务、计划、Cron、Goal 和 usage 都能在本地查询。 # 构建与打包 构建与打包 / Building & Packaging [#构建与打包--building--packaging] 构建命令 / Build Commands [#构建命令--build-commands] ```bash # 类型检查 + 构建（推荐） npm run build # 构建各平台安装包 npm run build:win # Windows (.exe) npm run build:mac # macOS (.dmg) npm run build:linux # Linux (.AppImage / .deb) ``` 构建产物 / Build Artifacts [#构建产物--build-artifacts] 打包完成后，安装包位于 `dist/` 目录： | 平台 | 文件 | | ------- | ---------------------------- | | Windows | `OpenCowork-x.x.x-setup.exe` | | macOS | `OpenCowork-x.x.x.dmg` | | Linux | `OpenCowork-x.x.x.AppImage` | 构建工具链 / Build Pipeline [#构建工具链--build-pipeline] 1. **electron-vite**：统一的 Vite 构建配置，支持主进程/预加载/渲染进程三入口 2. **electron-builder**：打包为各平台安装包 3. **better-sqlite3** 和 **node-pty** 等原生模块通过 `postinstall` 脚本为 Electron 重建 自动更新 / Auto Update [#自动更新--auto-update] 集成了 GitHub Releases 自动更新（`electron-updater`）： ```yaml # electron-builder.yml publish: provider: github owner: AIDotNet repo: OpenCowork ``` * 应用启动时检查新版本 * 后台下载更新包 * 提示用户重启安装 环境变量 / Environment Variables [#环境变量--environment-variables] | 变量 | 说明 | | ------------------ | -------------------------- | | `VITE_APP_VERSION` | 应用版本号 | | `GH_TOKEN` | GitHub Token（用于发布 Release） | 文档站点构建 / Docs Site Build [#文档站点构建--docs-site-build] 文档站点是一个独立的 Fumadocs + Next.js 项目： ```bash cd docs npm install npm run dev # 本地开发 npm run build # 生产构建（output: standalone） ``` # 贡献指南 贡献指南 / Contributing [#贡献指南--contributing] 欢迎为 OpenCowork 贡献代码！ 开始之前 / Before You Start [#开始之前--before-you-start] 1. Fork [AIDotNet/OpenCowork](https://github.com/AIDotNet/OpenCowork) 2. 克隆你的 Fork：`git clone https://github.com/YOUR_USERNAME/OpenCowork.git` 3. 搭建开发环境：参见 [开发环境搭建](/docs/reference/development-setup) 开发流程 / Development Workflow [#开发流程--development-workflow] ```bash # 创建功能分支 git checkout -b feature/your-feature-name # 开发并测试 npm run dev # 类型检查 npm run typecheck # 代码规范检查 npm run lint # 提交 git commit -m "feat: add your feature" # 推送并创建 PR git push origin feature/your-feature-name ``` Commit 规范 / Commit Convention [#commit-规范--commit-convention] 使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范： | 类型 | 说明 | 示例 | | ---------- | -------- | ------------------------------------- | | `feat` | 新功能 | `feat(tools): add git status tool` | | `fix` | Bug 修复 | `fix(agent): handle null tool result` | | `docs` | 文档更新 | `docs: update installation guide` | | `refactor` | 代码重构 | `refactor(store): migrate to immer` | | `chore` | 构建/工具链变更 | `chore: bump electron to v36` | 添加新工具 / Adding a New Tool [#添加新工具--adding-a-new-tool] 1. 在 `src/renderer/src/lib/tools/` 创建工具文件 2. 实现 `ToolHandler` 接口 3. 在 `src/renderer/src/lib/tools/index.ts` 的注册处添加 ```typescript export const myTool: ToolHandler = { definition: { name: 'MyTool', description: '工具描述', input_schema: { type: 'object', properties: { param: { type: 'string', description: '参数说明' } }, required: ['param'] } }, async execute(input, ctx) { const { param } = input as { param: string } return { type: 'text', text: `结果: ${param}` } } } ``` 添加新消息平台插件 / Adding a New Plugin [#添加新消息平台插件--adding-a-new-plugin] 1. 在 `src/main/channels/providers/` 创建平台目录 2. 实现 `MessagingChannelService` 接口（或继承 `BasePluginService`） 3. 在 `src/main/index.ts` 的 `ChannelManager` 中注册工厂 4. 在文档中添加对应的配置页面 更新文档 / Updating Docs [#更新文档--updating-docs] 文档站点是独立的 Fumadocs + Next.js 项目： ```bash cd docs npm run dev ``` MDX 源文件在 `docs/docs/` 目录下，修改后提交即可。 问题反馈 / Reporting Issues [#问题反馈--reporting-issues] 在 [GitHub Issues](https://github.com/AIDotNet/OpenCowork/issues) 提交问题，请包含： * 操作系统和版本 * OpenCowork 版本 * 复现步骤 * 错误日志（`~/.open-cowork/crash.log`） # 开发环境搭建 开发环境搭建 / Development Setup [#开发环境搭建--development-setup] 前置要求 / Prerequisites [#前置要求--prerequisites] | 工具 | 版本 | 说明 | | ------- | --- | ------------ | | Node.js | 18+ | 推荐使用 LTS 版本 | | npm | 9+ | 随 Node.js 安装 | | Git | 任意 | 版本控制 | 克隆与安装 / Clone & Install [#克隆与安装--clone--install] ```bash git clone https://github.com/AIDotNet/OpenCowork.git cd OpenCowork npm install ``` 启动开发模式 / Start Dev Mode [#启动开发模式--start-dev-mode] ```bash npm run dev ``` 这会同时启动： * Electron 主进程 * Vite 开发服务器（渲染进程，支持 HMR） 项目结构 / Project Structure [#项目结构--project-structure] ``` OpenCowork/ ├── src/ │ ├── main/ # Electron 主进程 │ │ ├── index.ts # 入口 │ │ ├── ipc/ # 30+ IPC 处理器 │ │ ├── db/ # SQLite 数据库（DAO + 迁移） │ │ ├── channels/ # 消息平台插件（8 个平台） │ │ ├── cron/ # 定时任务调度器 │ │ ├── mcp/ # MCP 服务器管理器 │ │ └── ssh/ # SSH 连接管理 │ ├── preload/ # 预加载桥接脚本 │ ├── renderer/ │ │ └── src/ │ │ ├── lib/ # 核心库（agent / api / tools / preview） │ │ ├── stores/ # 15+ Zustand stores │ │ ├── hooks/ # React hooks │ │ ├── components/ # UI 组件 │ │ └── locales/ # i18n（en/zh 7 个命名空间） │ └── shared/ # 主进程/渲染进程共享类型 ├── resources/ │ └── agents/ # 子代理定义（.md 文件） ├── docs/ # Fumadocs 文档站点 ├── electron.vite.config.ts ├── tsconfig.node.json # 主进程 TS 配置 └── tsconfig.web.json # 渲染进程 TS 配置 ``` 类型检查 / Type Checking [#类型检查--type-checking] ```bash # 检查所有进程 npm run typecheck # 仅检查主进程 npm run typecheck:node # 仅检查渲染进程 npm run typecheck:web ``` 代码规范 / Code Style [#代码规范--code-style] ```bash # Lint 检查 npm run lint # 格式化 npm run format ``` 路径别名 / Path Aliases [#路径别名--path-aliases] 渲染进程使用 `@renderer/*` 别名： ```typescript // 等价于 src/renderer/src/lib/agent/agent-loop.ts import { runAgentLoop } from '@renderer/lib/agent/agent-loop' ``` 配置在 `tsconfig.web.json` 和 `electron.vite.config.ts` 中。 # Reference Reference [#reference] Reference 是给贡献者和维护者查实现细节的区域。这里不重复入门路径，重点保留架构、IPC、状态管理、构建和贡献信息。 Source map [#source-map] | Area | Path | | ---------------- | ------------------- | | Main process | `src/main/` | | Preload bridge | `src/preload/` | | Renderer | `src/renderer/src/` | | Shared contracts | `src/shared/` | | Packaged agents | `resources/agents/` | | Packaged skills | `resources/skills/` | # IPC 通信机制 IPC 通信机制 / IPC Communication [#ipc-通信机制--ipc-communication] OpenCowork 使用 Electron IPC 把渲染进程和主进程连接起来。**渲染进程发起请求，主进程执行系统能力，结果再回流到 UI。** 通道组织 / Channel organization [#通道组织--channel-organization] IPC 按领域分组，避免字符串散落在业务代码里： | 领域 | 典型通道 | | ------------------ | -------------------------------------------------------- | | 文件系统 | `fs:*`, `ssh:fs:*` | | 数据库 | `db:*` | | 设置与配置 | `settings:*`, `config:*` | | Agent / 运行时 | `agent:*`, `sidecar:*`, `team:*`, `team-worker:*` | | 消息平台 | `plugin:*` | | MCP | `mcp:*` | | Cron | `cron:*` | | SSH / Terminal | `ssh:*`, `terminal:*` | | 搜索 / Web / Browser | `web-search:*`, `browser:*` | | 通知 / 截图 / 输入 | `notify:*`, `screenshot:*`, `input:*` | | 图像 | `image:*`, `clipboard:*` | | 资源目录 | `skills:*`, `agents:*`, `commands:*`, `prompts:*` | | 迁移 / 其他 | `migration:*`, `wiki:*`, `git:*`, `process:*`, `oauth:*` | 调用模式 / Invocation patterns [#调用模式--invocation-patterns] 1) Request / response [#1-request--response] 大多数读写操作都通过 `invoke` 完成： ```ts const servers = await window.electron.ipc.invoke('mcp:list') ``` 主进程侧通常对应： ```ts ipcMain.handle('mcp:list', () => readServers()) ``` 2) 事件推送 [#2-事件推送] 当主进程需要主动通知 UI 时，会使用 `send` 或安全封装： * `plugin:incoming-message` * `cron:fired` * `team:*` * `goal:*` * `chat:*` 3) Fire-and-forget [#3-fire-and-forget] 某些状态同步不需要等待返回值，例如写消息、更新任务、保存设置。前端会调用 `invoke`，但不强依赖返回结果。 重要通道示例 / Important channels [#重要通道示例--important-channels] | 通道 | 用途 | | ------------------------------- | ------------------- | | `settings:get` / `settings:set` | 设置读取与保存 | | `config:get` / `config:set` | 安全配置读写 | | `db:*` | SQLite 业务数据 CRUD | | `cron:*` | Cron 任务和运行日志 | | `mcp:*` | MCP server 管理和能力发现 | | `plugin:*` | 消息平台插件实例、消息路由和自动回复 | | `ssh:*` | SSH 连接、远程文件、远程终端 | | `team-runtime:*` | Team Runtime 持久化和快照 | | `team-worker:*` | 隔离 worker 启停 | | `web-search:*` | 搜索与抓取 | | `browser:*` | 内置浏览器控制 | | `notify:*` | 桌面通知 | 设计原则 / Design principles [#设计原则--design-principles] * **主进程是唯一的系统能力入口** * **通道名要能表达业务域** * **UI 只持有最小必要信息** * **复杂对象优先用 DTO / shared types 表达** * **事件推送只负责通知，状态详情由存储或查询接口提供** 一个实用判断 / Practical rule [#一个实用判断--practical-rule] 如果某个能力会碰到文件、数据库、SSH、窗口、通知、系统代理、更新、外部消息平台或后台任务，它就应该放在 **Main**，并通过 IPC 暴露；不要直接在 renderer 里硬做。 # 状态管理 状态管理 / State Management [#状态管理--state-management] OpenCowork 的渲染进程使用 **Zustand + Immer** 组织状态。总体思路是： * 业务实体尽量和 SQLite 对齐 * 运行时状态留在内存或本地持久化 store * 外部连接和配置通过专门 store 管理 * 复杂状态按域拆分，而不是堆在一个全局 store 里 核心 store / Core stores [#核心-store--core-stores] | Store | 作用 | 持久化 | | ------------------ | -------------------------------------------- | -------------------------- | | `chat-store` | 项目、会话、消息、模式、工作目录、活动会话 | SQLite + IPC | | `agent-store` | Agent loop、工具调用、审批、子代理、usage | 本地持久化 | | `task-store` | 会话级任务面板 / Steps | SQLite | | `plan-store` | Plan Mode 的计划文件与状态 | SQLite | | `team-store` | Team Runtime、成员、任务、消息 | 本地持久化 + runtime JSON | | `provider-store` | provider / model / auth 配置 | 配置存储 | | `settings-store` | 全局设置、代理、语言、Web 搜索、工作目录 | `settings.json` | | `app-plugin-store` | 图像、浏览器、桌面控制插件配置 | 配置存储 | | `channel-store` | 消息平台插件实例、自动回复状态 | 本地持久化 | | `mcp-store` | MCP server 配置与连接状态 | 本地持久化 + `mcp-servers.json` | | `cron-store` | Cron jobs、run history、日志 | SQLite | | `ssh-store` | SSH groups、connections、远程上下文 | 本地持久化 + SQLite | | `resources-store` | agents / commands / prompts / skills catalog | IPC + filesystem | | `goal-store` | Session goal / budget / progress | SQLite | 辅助 store / Supporting stores [#辅助-store--supporting-stores] 还有一些专门的状态 store，用来承载局部 UI 或辅助流程： * `ui-store`：界面布局、右侧面板、浏览器面板、预览面板、模式切换 * `notify-store`：通知窗口状态 * `terminal-store`：终端会话状态 * `git-store`：Git 相关状态 * `draw-store` / `image-edit-store`：生成与编辑图像状态 * `translate-store`：翻译工作流状态 * `background-session-store`：后台会话状态 * `input-draft-store`：输入框草稿 * `quota-store`：用量或额度提示 持久化方式 / Persistence [#持久化方式--persistence] 常见组合有三种： 1. **SQLite**：适合会话、消息、任务、计划、Cron、SSH、Wiki、Goal 这类可查询业务数据。 2. **ipcStorage / configStorage**：适合配置类、跨窗口同步类状态。 3. **纯内存**：适合短生命周期 UI 状态。 ```ts create()( persist( immer((set, get) => ({ /* ... */ })), { name: 'store-name', storage: createJSONStorage(() => ipcStorage) } ) ) ``` 状态边界 / State boundaries [#状态边界--state-boundaries] | 边界 | 原则 | | ---- | -------------------------------------------------------------------- | | 会话实体 | 由 `chat-store` 和数据库同步，避免单纯靠内存 | | 运行态 | `agent-store` 保留流式文本、工具调用、审批与子代理状态 | | 外部连接 | channel / MCP / SSH 各有独立 store | | 配置 | `settings-store`、`provider-store`、`app-plugin-store`、`channel-store` | | 视图 | `ui-store` 处理布局和面板，不承担业务逻辑 | 你在代码里会看到什么 / What to expect in code [#你在代码里会看到什么--what-to-expect-in-code] * Store 通常只做单一职责。 * 复杂动作会分成 `load / update / clear / sync` 几组方法。 * 很多 store 会用 IPC 做“写入后落盘”，但不会阻塞 UI。 * 业务层尽量依赖 store 暴露的方法，而不是直接读写底层存储。 # Slash commands Slash commands [#slash-commands] Slash commands 是轻量的工作流入口。OpenCowork 把内置命令放在 `resources/commands/`，用于快速触发计划、审查、提交、初始化和安全检查等常见动作。 Built-in commands [#built-in-commands] | Command file | Purpose | | -------------------- | --------------------- | | `plan.md` | 先分析目标，再形成可审阅计划 | | `review.md` | 代码审查，优先报告 bug、回归和测试缺口 | | `security-review.md` | 安全风险审查 | | `commit.md` | 组织改动、生成提交说明 | | `init.md` | 初始化项目上下文 | | `agents.md` | 生成或维护 agent 指令 | Runtime shape [#runtime-shape] ```txt resources/commands/*.md -> loaded by command loader -> injected into the active session -> executed with the current model/tools/workspace ``` Good command design [#good-command-design] * 目标要短，避免把命令变成完整长文档。 * 明确输出格式，例如 review findings、commit message 或 plan。 * 需要工具时写清楚约束，例如只读、先搜索、不要改文件。 # Skills Skills [#skills] Skills 是给 Agent 的可复用操作说明。它们通常不是新工具，而是告诉 Agent 如何组合已有工具完成某类任务，例如处理 Excel、读 PDF、写邮件、OCR、网页抓取或前端实现。 Built-in skill locations [#built-in-skill-locations] ```txt resources/skills/ packaged with the app ~/.agents/skills/ user-editable runtime copy ``` 首次运行后，OpenCowork 会把内置 skills 同步到用户目录。之后用户可以增删或改写自己的 skill，而不会直接修改应用包。 When to use a skill [#when-to-use-a-skill] | Use a skill when | Use something else when | | ------------------------ | ------------------------------ | | Agent 已有工具，但需要稳定流程、约束或格式 | 需要一个新可调用能力，改用 MCP 或 app plugin | | 任务有固定步骤，例如 OCR、表格、邮件、PDF | 任务需要独立上下文和角色，改用 sub-agent | | 团队希望共享操作规范 | 任务需要多角色协作，改用 Agent team | # 技能与工作流 技能与工作流 / Skills, Commands & Prompts [#技能与工作流--skills-commands--prompts] 当前实现里，“workflows” 这个概念主要落在三类资源上：**Skills、Commands、Prompts**。它们都来自文件系统，并在本地可编辑。 1) Skills [#1-skills] Skills 是可以被 `Skill` 工具加载的专门工作流指南。 存储位置 [#存储位置] * 内置：`resources/skills/` * 首次同步后：`~/.agents/skills/` 工具入口 [#工具入口] `Skill` 工具会： 1. 通过 `skills:list` 获取可用 skills 2. 通过 `skills:load` 读取指定 skill 的 `SKILL.md` 3. 把 skill 内容作为上下文返回给 Agent 内置 skills [#内置-skills] 当前仓库内置的 skill 包括： * `csv-pipeline` * `docx` * `email-drafter` * `excel-processor` * `frontend-skill` * `image-ocr` * `pdf` * `post-to-x` * `web-scraper` * `wechat-ui-sender` * `xlsx` > 如果系统里还有额外安装的 skills，它们也会出现在可加载列表里。 2) Slash commands [#2-slash-commands] Slash commands 是以 `/xxx` 形式调用的快捷指令。 存储位置 [#存储位置-1] * 内置：`resources/commands/` * 用户覆盖：`~/.open-cowork/commands/` 当前内置 commands [#当前内置-commands] * `agents` * `commit` * `init` * `plan` * `review` * `security-review` 规则 [#规则] * 文件必须是纯 Markdown * 名称必须是 kebab-case * 同名用户命令会覆盖内置命令 3) Prompts [#3-prompts] Prompts 是可复用的提示词模板。 存储位置 [#存储位置-2] * 内置：`resources/prompts/` * 用户覆盖：`~/.open-cowork/prompts/` 当前仓库的内置 prompt 只有一个： * `codex-instructions.md` 为什么把它们放一起讲？ / Why group them? [#为什么把它们放一起讲--why-group-them] 因为它们本质上都是“**本地文件驱动的可复用知识入口**”： * Skills 面向复杂工作流 * Commands 面向快速调用 * Prompts 面向可复用指令片段 与 Sub-Agent 的区别 / Difference from sub-agents [#与-sub-agent-的区别--difference-from-sub-agents] * **Skill**：返回工作流/指南/执行说明 * **Sub-agent**：启动一个独立 agent 去做事 * **Command**：快捷入口，通常用于一键式任务 使用建议 / Advice [#使用建议--advice] * 需要步骤化执行时，用 Skill * 需要快速触发模板任务时，用 Command * 需要变换系统提示词时，用 Prompt # Get started Get started [#get-started] OpenCowork 是一个开源桌面平台，用来让多个 AI Agent 在你的本地项目里协作。它提供本地文件读写、Shell、代码搜索、上下文感知、子代理、团队协作以及人类审批机制。 目标用户是：希望 AI Agent 能直接在本地代码库中工作、同时保留可控权限和可见执行过程的开发者。 你可以用它做什么 [#你可以用它做什么] * 在本地项目里和 AI 对话，并允许它读取、搜索、修改文件。 * 让 Agent 调用 Shell、MCP、浏览器、桌面控制等工具。 * 通过子代理把复杂任务拆给不同角色。 * 通过 Agent Teams 让多个成员协作完成计划。 * 配置 Cron，让 Agent 定时执行任务。 * 把 AI 接入飞书、钉钉、QQ、Telegram、Discord、WhatsApp 等消息平台。 First run [#first-run] 使用 release 安装包，或在仓库根目录运行开发命令。 在 Settings 里添加 provider key，选择默认模型。 把一个本地项目绑定到当前会话。 让 Agent 搜索代码、解释文件、制定计划或执行工具。 Key directories [#key-directories] | 目录 | 用途 | | --------------------- | ----------------------------------------------- | | `src/main/` | Electron main process、数据库、IPC、MCP、消息平台、Cron、SSH | | `src/preload/` | 安全桥接层 | | `src/renderer/src/` | React UI、Agent loop、工具注册、Zustand stores | | `src/shared/` | 跨进程类型、事件协议、工具契约 | | `resources/agents/` | 内置子代理定义 | | `resources/skills/` | 内置技能 | | `resources/commands/` | 内置 slash commands | Next [#next] * [Install](/docs/install) * [Quick start](/docs/start/quick-start) * [Agents](/docs/agents) * [Capabilities](/docs/capabilities) # 快速上手 快速上手 / Quick Start [#快速上手--quick-start] 1. 配置一个提供商 [#1-配置一个提供商] 打开应用后，先进入 **设置 → AI 提供商**，添加一个可用模型提供商。 推荐优先级： 1. Anthropic / Claude 2. OpenAI / Azure OpenAI 3. Google Gemini 4. DeepSeek、Qwen、Moonshot、MiniMax、Ollama 等兼容或本地方案 如果你不想先申请云端 Key，可以直接用 **Ollama**。 2. 创建一个会话 / Create a session [#2-创建一个会话--create-a-session] 新建会话后，先选一个适合当前任务的模式： | 模式 | 适合什么 | | ------- | -------------- | | Chat | 轻量问答、快速对话 | | Cowork | 日常协作、文档处理、信息整理 | | Code | 项目修改、脚本运行、代码审查 | | Clarify | 需求不明确，需要先问清楚 | | ACP | 架构设计、任务拆分、委派执行 | 3. 设置 working folder [#3-设置-working-folder] 如果你要让 Agent 读写项目代码，先为会话设置工作目录。这样文件工具和 Shell 工具都会围绕这个目录执行。 4. 让 Agent 做一个小任务 [#4-让-agent-做一个小任务] 先试一个简单的任务： ```text 请读取当前项目的 README，并总结这个项目的主要用途。 ``` 再试一个代码任务： ```text 请在当前项目里搜索和 cron 相关的实现，并告诉我调度器在哪里。 ``` 5. 尝试 Plan Mode [#5-尝试-plan-mode] 当需求开始变复杂时，切换到 **Clarify** 或直接启用 **Plan Mode**： ```text 请帮我把这个功能拆成可执行的实现计划。 ``` Plan Mode 会先写计划文件，再让你审阅，不会直接跳进实现。 6. 尝试一个自动化任务 [#6-尝试一个自动化任务] 如果你想把任务变成定时执行，可以直接让 Agent 创建 Cron： ```text 每天上午 9 点检查今天的待办，并把结果发给我。 ``` 7. 尝试一个消息平台插件 [#7-尝试一个消息平台插件] 如果你要把结果推到飞书、钉钉、企业微信、Telegram、Discord、WhatsApp、QQ 或微信，可以去 **设置 → 聊天频道** 配置对应插件。 快速判断 / Rule of thumb [#快速判断--rule-of-thumb] * **需求不清楚**：用 Clarify * **要先出方案**：用 Plan Mode * **要改代码**：用 Code * **要长时间协作**：用 Cowork * **要设计和分派**：用 ACP