Koda Cowork 使用手册

本地 AI 协作工作区 —— 让 Agent 成为可靠的执行助手（可扮演秘书/同事/专家），在项目目录里安全高效地完成任务。

为什么选择 Koda Cowork？

与通用 AI 的本质区别

构建差异化 Agent

Koda Cowork 的核心价值在于：通过 Skills 和 MCP 的组合，构建出完全不同的专业化 Agent。

Koda Cowork 的三大核心能力

1. Skills - 专业能力模块

Skills 是专家知识的压缩包，每个 Skill 都是一套专业知识和工作流。

• 内置 9+ Skills：数据分析、可视化、前端设计、文档生成...
• 自定义 Skills：用 skill-creator 创建自己的专业能力
• 远程安装：从 GitHub 仓库一键安装，带审核流水线
• 质量保证：skill-judge 8 维度评分，确保质量

2. MCP 插件 - 外部连接器

MCP（Model Context Protocol）让 Agent 能连接任何外部服务。

• 内置 4 个 MCP：浏览器自动化、网络搜索、网页提取...
• 自定义 MCP：连接内部系统（CRM、ERP、数据库）
• 灵活配置：支持 stdio、HTTP、SSE 多种传输方式
• 环境变量：安全存储 API 密钥

3. 安全机制 - 可控的执行

本地运行 + 审批系统，确保 Agent 的行为可控、可追溯。

• 危险操作审批：删除、移动、覆盖写需要明确批准
• 路径边界防护：只能在项目目录内操作
• 记忆规则：记住审批决定，自动化工作流
• 本地优先：所有数据存储在本地，不上传云端

愿景和目标

应用场景

核心特性

Koda Cowork 是一个本地协作应用，它把 AI Agent 变成你的助手， 在你的项目目录里安全地执行任务。每个 Workspace（工作区）都是独立的， 拥有自己的对话历史、工具调用记录和审批策略。

核心特性

快速开始

1. 配置 API Key

首次打开 Koda Cowork，需要配置 Anthropic API Key：

1. 点击右上角 设置 图标 ⚙️
2. 在 Anthropic 标签页输入 API Key
3. （可选）自定义模型名称（默认：claude-sonnet-4-20250514）
4. 点击 保存

2. 创建第一个工作区

1. 点击左侧边栏的 + 新建工作区 按钮
2. 输入工作区名称（如"我的项目"）
3. 选择要关联的文件夹路径
4. 点击 创建

3. 发送第一个任务

在聊天输入框中输入你的需求，例如：

帮我分析一下这个项目的结构，然后告诉我主要功能

Agent 会先生成一个 TODO 计划，确认后开始执行。

工作区类型

Koda Cowork 支持三种工作区类型，满足不同场景需求：

📁 Folder（文件夹）

绑定到本地文件夹，Agent 可以读取、编辑、创建文件。
适用场景：代码项目、文档整理、批量文件操作

💬 Chat（对话）

纯对话模式，不绑定文件夹。
适用场景：咨询、讨论、创意头脑风暴、代码解释

🤖 Sub-Agent（子代理）

可配置定时任务，按计划自动执行。
适用场景：定期报告、监控、自动化任务

审批系统

Koda Cowork 的安全核心 —— 危险操作必须经过你的明确批准才能执行。

需要审批的操作

• fs_rm - 删除文件或文件夹
• fs_move - 移动或重命名文件
• fs_write/fs_edit - 覆盖已存在的文件

审批流程

1. Agent 执行到危险操作时，右下角弹出 审批卡片
2. 卡片显示操作类型、目标路径、风险等级
3. 选择 允许 或 拒绝
4. 可选：勾选"记住决定"创建规则

记忆规则

对于频繁的操作，可以创建记忆规则，下次自动处理：

• 作用范围：全局 / 特定工作区
• 匹配条件：工具名称、路径模式
• 决定：自动允许 / 自动拒绝

聊天与任务执行

Koda Cowork 的聊天界面不仅是对话工具，更是一个完整的任务执行环境。

聊天界面功能

智能建议（Onboarding）

进入新工作区时，Agent 会分析文件夹结构，生成个性化的任务建议：

• AI 分析：自动识别项目类型（代码/文档/数据）
• 智能建议：基于项目特点生成推荐任务
• 快速上手：点击建议即可直接执行
• 可刷新：不满意可重新生成建议

附件系统（Context Items）

除了聊天内容，你还可以为 Agent 提供文件和文件夹作为上下文：

• 📎 附件按钮：点击输入框左侧的回形针图标
• 文件/文件夹：添加本地文件或整个目录
• 上下文感知：Agent 可以读取和分析附件内容
• 计数提示：附件按钮显示已添加的数量

消息交互

• 流式输出：实时显示 Agent 的思考和执行过程
• Markdown 渲染：支持代码高亮、表格、列表
• 消息操作：复制消息内容、查看时间戳
• 历史摘要：长对话自动压缩，保留关键信息
• 快速跳转：一键回到顶部、上一问、最新消息
• 未读提醒：离开时显示新消息数量

输入增强

• 多行输入：Shift + Enter 换行，Enter 发送
• 自动高度：输入框根据内容自动调整
• 附件提醒：发送按钮显示包含的附件数量
• 状态禁用：Agent 工作时自动禁用输入

发送任务

在聊天输入框中用自然语言描述你的需求：

帮我整理一下 Downloads 文件夹，把图片移到 Images，文档移到 Documents

Agent 会先分析任务，然后生成 TODO 计划列表供你确认。

TODO 计划系统

计划生成

接到任务后，Agent 会生成结构化的 TODO 计划：

• 标题：简洁的任务描述
• 状态：pending（待办）/ in_progress（进行中）/ completed（已完成）
• 负责人：通常是 "Koda"（Agent 名称）
• 可编辑：用户可以修改计划内容

计划确认

在 Agent 开始执行前，你可以：

• 查看计划：了解 Agent 的执行思路
• 调整计划：添加、删除、修改任务
• 确认执行：批准后 Agent 开始工作
• 取消执行：改变主意可以中止

执行监控

确认计划后，Agent 开始执行。右侧任务面板实时显示：

TODO 面板

• 状态变化：任务从 pending → in_progress → completed
• 进度跟踪：当前正在执行的任务
• 工作时间：显示 Agent 已工作时长
• 任务统计：完成/失败/等待的数量

执行日志

• 工具调用：每个工具的名称、参数、执行时间
• 执行结果：成功/失败/需要审批
• 详细输出：可展开查看完整的工具返回
• 时间戳：每个操作的精确时间

流式输出

在执行过程中，Agent 会实时输出：

• 思考过程：展示 Agent 的决策逻辑
• 执行进展：当前正在做什么
• 结果说明：操作完成后的总结
• Markdown 格式：支持富文本和代码块

任务状态

Agent 有三种主要状态：

高效任务描述技巧

好的任务描述

• 具体明确：说明具体的文件、文件夹、操作类型
• 包含上下文：说明为什么需要这样做，预期结果是什么
• 分阶段：复杂任务可以拆分成多个步骤
• 示例：如果需要特定格式，提供示例

示例对比

协作模式

分阶段执行

复杂任务可以分阶段完成：

1. 第一阶段："先分析一下项目结构，告诉我你的理解"
2. 确认理解后："根据你的理解，重构 X 模块"
3. 检查结果："看一下代码质量，有没有需要改进的"

迭代优化

Agent 执行完后，你可以：

• 要求重试："刚才那步失败了，请重试"
• 提供反馈："这个方案不太对，我需要的是..."
• 继续深化："在此基础上，再优化一下"

文件预览

Koda Cowork 内置强大的文件预览系统，支持多种格式，无需打开外部应用。

支持的文件类型

预览操作

• 双击文件：在预览窗口中打开
• 顶部工具栏：在 Finder 中显示 / 用默认应用打开
• HTML 特殊处理：使用独立的 runtime 窗口，确保相对路径资源正常加载

Skills 技能系统

Skills 是 Koda Cowork 的扩展机制，每个 Skill 都是一套专业知识和工作流， 让 Agent 具备领域能力。

内置 Skills

Koda Cowork 内置了 9+ 个专业 Skills：

创建自定义 Skills

Koda Cowork 提供了完整的 Skill 创建工具链，让你可以轻松扩展 Agent 的能力。

Skill 的结构

每个 Skill 包含以下内容：

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter (name, description)
│   └── Markdown 指南
└── 可选资源
    ├── scripts/       # 可执行脚本
    ├── references/    # 参考文档
    └── assets/        # 模板、图标等资源

创建流程（6 步）

1. 理解需求：用具体例子明确 Skill 要解决的问题
2. 规划内容：确定需要哪些 scripts、references、assets
3. 初始化 Skill：使用 Cowork 自动生成模板
4. 编辑内容：实现 SKILL.md 和相关资源
5. 打包发布：生成 .skill 文件供使用
6. 迭代优化：根据实际使用改进

在 Koda Cowork 中创建 Skill

Cowork 内置了 skill-creator 和 skill-judge 两个 Skills：

使用 skill-creator 创建 Skill

在任何工作区中，告诉 Agent：

我想创建一个 [你的 Skill 领域] 的 Skill，帮我规划一下

Agent 会引导你完成：

• 分析具体使用场景
• 规划 Skill 结构（scripts/references/assets）
• 编写 SKILL.md 的 frontmatter 和正文
• 测试和打包

Skill 设计核心原则

1. Frontmatter（触发机制）

SKILL.md 开头的 YAML 元数据是 Skill 被激活的关键：

---
name: my-skill
description: "简洁描述技能功能和触发场景。包含：
- WHAT：做什么
- WHEN：何时使用
- KEYWORDS：触发关键词
例如：处理 PDF 文档的创建、编辑、分析。
当用户提到 PDF、文档处理、或需要操作 .pdf 文件时使用。
---

description 是最重要的字段 —— Agent 只根据 description 决定是否激活 Skill。

2. 渐进式披露

分三层组织内容，节省 token：

• Layer 1（元数据）：name + description，始终在内存中
• Layer 2（SKILL.md）：核心指南，理想 < 500 行
• Layer 3（资源）：scripts/references/assets，按需加载

3. 适当的自由度

根据任务脆弱性选择指导粒度：

• 高自由度（文字指导）：创意任务、设计（frontend-design）
• 中等自由度（伪代码）：有模式可循但有变化空间
• 低自由度（精确脚本）：易错操作、格式处理（docx/pdf）

4. 反模式列表

专家知识的一半是"什么不该做"。明确列出 NEVER 列表：

NEVER use generic AI aesthetics:
- Overused fonts: Inter, Roboto, Arial
- Purple gradients on white
- Cookie-cutter layouts

Skill 质量评估

使用 skill-judge 评估你的 Skill 质量：

请评估一下我刚才创建的 my-skill 的质量

skill-judge 会从 8 个维度打分（满分 120 分）：

Skill 存放位置

创建好的 Skill 应放在：

• 用户 Skills：~/.koda-cowork/skills/
• 应用内置 Skills：apps/cowork/skills/

从远程源安装 Skills

Cowork 支持从 Git 仓库或本地目录远程安装 Skills，并提供完整的审核流水线确保安全。

安装方式

https://github.com/user/skills-repo

/path/to/skills

.claude-plugin/marketplace.json

审核流水线（4 步）

Cowork 提供企业级的 Skill 审核流程，确保安装的 Skills 安全可靠：

风险评估

静态检查会自动评估 Skill 的风险等级：

使用审核流水线安装

通过 Cowork 的 UI 界面安装远程 Skills：

1. 打开设置
   • 点击右上角 ⚙️ 设置图标
   • 切换到 "Skills" 标签页
   • 点击 "审核并安装" 按钮
2. 输入来源
   • Git URL：https://github.com/anthropics/skills
   • 本地路径：/Users/xxx/my-skills
   • 点击"选择目录"按钮浏览文件夹
3. 等待审核
   • 自动执行 4 步审核流程
   • 查看每个 Skill 的风险等级和评分
   • 阅读 LLM 生成的 strengths / issues / recommendations
4. 选择并安装
   • 勾选要安装的 Skills
   • 点击"安装"按钮
   • Skills 被复制到 ~/.koda-cowork/skills/

手动安装（跳过审核）

对于可信来源，可以手动复制 Skill 文件：

# 1. Clone 仓库
git clone https://github.com/user/skills-repo.git /tmp/skills

# 2. 复制到用户目录
cp -r /tmp/skills/my-skill ~/.koda-cowork/skills/

# 3. 重启 Cowork 或等待自动重载

Claude Marketplace 格式

如果仓库包含 .claude-plugin/marketplace.json，Cowork 会自动按插件分组展示 Skills。

marketplace.json 示例：

{
  "name": "My Skills Collection",
  "description": "组织内部常用 Skills",
  "skills": [
    {
      "name": "my-skill-1",
      "description": "第一个技能"
    },
    {
      "name": "my-skill-2",
      "description": "第二个技能"
    }
  ]
}

常见 Skill 创建模式

根据任务类型选择合适的设计模式：

MCP 插件系统

Cowork 支持 Model Context Protocol (MCP) 插件系统， 通过外部服务扩展 Agent 的能力。MCP 服务器可以提供额外的工具、数据源和集成。

内置 MCP 服务器

Cowork 默认配置了以下 MCP 服务器：

MCP 配置文件

MCP 配置存储在 ~/.koda-cowork/mcp/ 目录：

• mcp_settings.json：主配置文件（内置服务器默认配置）
• mcp_settings.d/*.json：用户自定义服务器
• .env：API 密钥和环境变量

配置格式

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    },
    "http-server": {
      "transport": "streamableHttp",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_TOKEN}"
      }
    }
  }
}

传输类型

环境变量配置

API 密钥等敏感信息存储在 ~/.koda-cowork/mcp/.env：

# Cowork MCP secrets
# 智谱 / Z.ai
Z_AI_API_KEY=your_api_key_here
Z_AI_MODE=ZHIPU

# 其他服务
MY_API_KEY=another_key_here

变量占位符

在 mcp_settings.json 中使用 ${VARIABLE_NAME} 引用环境变量：

{
  "mcpServers": {
    "glm-zai-mcp-server": {
      "env": {
        "Z_AI_API_KEY": "${Z_AI_API_KEY}",
        "Z_AI_MODE": "${Z_AI_MODE}"
      }
    }
  }
}

管理 MCP 服务器

通过设置界面

1. 打开设置 → MCP 标签页
2. 查看所有已配置的服务器及其状态
3. 启用/禁用特定服务器（工作区级别覆盖）
4. 点击"导入"添加新服务器
5. 点击"..."菜单查看详情或删除服务器

手动添加服务器

在 ~/.koda-cowork/mcp/mcp_settings.d/ 目录创建 JSON 文件：

# 1. 创建配置文件
cat > ~/.koda-cowork/mcp/mcp_settings.d/my-server.json << 'EOF'
{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}
EOF

# 2. 在 .env 中添加密钥
echo "MY_API_KEY=xxx" >> ~/.koda-cowork/mcp/.env

# 3. 重启 Cowork 或等待自动重载

MCP 服务器状态

工作区级别覆盖

你可以为特定工作区启用或禁用 MCP 服务器：

• 默认：跟随全局设置
• 启用：强制在此工作区启用该服务器
• 禁用：强制在此工作区禁用该服务器

这在需要为不同工作区配置不同工具集时非常有用。

调试 MCP 问题

常见问题

• 服务器无法启动：检查 command 路径是否正确，依赖是否已安装
• 认证失败：确认 .env 中的 API 密钥正确
• 连接超时：HTTP 服务器检查 url 和网络连接
• 变量未替换：确认占位符格式为 ${VARIABLE_NAME}

查看服务器详情

在设置 → MCP 中点击服务器名称，可以查看：

• 完整配置（command/args/env/url/headers）
• 提供的工具列表
• 错误信息（如果启动失败）
• 来源（内置/用户自定义）

高级功能

历史归档

导出工作区的对话历史和工具调用记录，用于备份或分析。 支持 JSON 和 Markdown 格式。

调试模式

开发者可以打开调试抽屉，查看原始事件流、Agent 状态和系统日志。

MCP 插件

支持 Model Context Protocol（MCP）插件系统，可以扩展 Agent 的能力。 MCP 配置文件位于 ~/.koda-cowork/mcp/。

常见问题

Q: Cowork 的数据存储在哪里？

所有数据（设置、工作区、对话历史）都存储在本地，路径为系统 userData 目录下的 cowork/ 文件夹。 不会上传到任何云端。

Q: 可以同时运行多个工作区吗？

可以。每个工作区都有独立的 Agent 实例，可以同时活跃。 但建议一次专注一个任务，避免混淆。

Q: Agent 执行出错怎么办？

查看右侧执行日志，了解失败原因。 然后告诉 Agent "刚才那步失败了，请重试"或提供更多上下文帮助它修正。

Q: 如何自定义 Skills？

Skills 是标准的 SKILL.md 文件。在 ~/.koda-cowork/skills/ 目录创建你的技能文件夹， 包含 SKILL.md 和相关资源即可。参考内置 Skills 的结构。

Q: 支持哪些 LLM 模型？

当前版本仅支持 Anthropic Claude 系列（claude-sonnet-4-20250514 等）。 未来计划扩展其他模型。