Cocurdex快速上手
安装 Cocurdex、打开工作区、配置 Agent 运行时，并运行第一个会话。
本指南带你从安装走到一个有用的 Agent 会话。
环境要求
| 项目 | 说明 |
|---|---|
| macOS | Apple silicon 与 Intel |
| Windows | x64（未签名的 NSIS 安装包） |
| Linux | x64 AppImage 或 .deb |
| Agent 运行时 | 至少一个你已在使用的受支持 Agent CLI 或 provider（见 Agent） |
| 磁盘 / 项目 | 磁盘上的一个项目目录，供 Agent 和编辑器用作工作区根目录 |
安装
公开构建
- 从下载页获取对应平台的构建。
- 安装并打开 Cocurdex。
- 首次启动时会显示欢迎使用 cocurdex页面，介绍这台机器上的可用功能。点击打开文件夹即可开始使用工作区——Agent 会在你选择的文件夹中运行。内置 Pi Agent 需要配置服务商；其他 Agent CLI 自带模型。页面还提供配置模型服务商、跳过和不再显示选项。
把 CLI 放到 PATH 上
安装后，打开 设置 → 常规 → Shell 命令 并点击安装，让 cocurdex 启动器在终端可用。
cocurdex --version
cocurdex --help如果二进制找不到桌面应用，请先从 Dock/应用程序打开一次 Cocurdex，或将 COCURDEX_ELECTRON 设为应用可执行文件。见 CLI。
打开工作区
工作区是 Cocurdex 挂接的项目上下文——通常是磁盘上的一个目录。
从桌面应用
- 打开 Cocurdex。
- 打开或创建一个指向项目根目录的工作区。
- 确认工作台中会话/对话与终端、编辑器并列呈现。
从终端（VS Code 风格）
# 打开应用
cocurdex
# 把文件夹作为工作区打开
cocurdex .
cocurdex open /path/to/project列出已知工作区：
cocurdex workspace list准备一个 Agent
在第一次有效运行之前：
- 安装你想用的 Agent CLI——
claude、codex或opencode——或者在 设置 → Agent CLI → 从 ACP Registry 添加 中添加 Cursor、Devin、Grok Build 等 Agent。如果cursor-agent、devin或grok已在PATH上，Cocurdex 会自动识别。只需要无本地写入的对话式工作时，也可以配合 Provider 配置使用内置的 Pi（pi）运行时。 - 完成该工具自身的授权（API key、ChatGPT 登录等）。Cocurdex 会尽可能复用你已有的 provider 配置。
- 在桌面应用中创建会话，选择 Agent + provider + 模型。
受支持的 Agent id 与权限模式见 Agent。
从 CLI 查看 provider 配置（daemon 必须已运行——打开桌面应用即会启动）：
cocurdex provider list
cocurdex provider models <provider-id>第一个会话（桌面端）
- 从桌面工作台发起一个新会话。
- 选择一个你已完成授权的 Agent 运行时和模型。
- 保持终端和编辑器可用——Agent 的工作往往不止于对话流。
- 先发一个小而具体的任务（例如「列出顶层结构并总结入口点」）。
- 观察会话状态：
- 工作中 / 思考中 / 使用工具——Agent 正在忙
- 待批准 / 等待输入——需要你处理
- 就绪 / 已完成——检查结果，然后继续或开始另一个会话
在信任任务之前，优先使用更窄的权限模式。提权或「完全访问」模式是为重度用法准备的，风险有意偏高。
第一个会话（CLI TUI）
在 daemon 可用时（桌面已打开或 daemon 可达）：
cocurdex session tui \
--workspace /path/to/project \
--agent codex \
--provider <provider-id> \
--model <model-id>或者先创建会话，再发送消息：
cocurdex session create \
--workspace /path/to/project \
--agent codex \
--provider <provider-id> \
--model <model-id>
cocurdex session list
cocurdex session send <session-id> "Summarize the repo structure"
cocurdex session stop <session-id>五分钟上手产品数据
笔记、Issue 和演示文稿是应用私有的，而不是仓库里的第二棵 Markdown 树：
cocurdex note create --title "Kickoff notes" --body "Goals for this week"
cocurdex issue create --title "Ship getting-started docs" --status backlog
cocurdex search "getting-started"演示文稿是同一类记录。见演示文稿。
可选：产品 Skills
安装命名空间化的产品 Skills,让 Agent 可以对同一数据面执行 /cocurdex-* 流程（note → issue → ship，以及用 /cocurdex-deck 做演示文稿）：
cocurdex skills list
cocurdex skills install --scope project
# 或
cocurdex skills install --scope global见 Skills。
排障
| 现象 | 尝试 |
|---|---|
| 某个 Agent 显示不可用 | 安装并登录它的 CLI，然后查看 设置 → Agent CLI(它也会标出需要升级的版本) |
| Agent 提示需要登录 | 在输入框的模型菜单中选择登录 …，然后重新发送 |
| CLI 数据命令失败 | 打开桌面应用以启动 daemon；运行 cocurdex daemon status |
| 笔记、Issue 或 Agent 无响应 | 设置 → 常规 中重启 daemon |
| 浏览器要求配对 | 在运行 Cocurdex 的电脑上打开 设置 → 设备，生成配对码，然后打开链接或输入配对码。见设备与本地网页 |
| 手机上只有电脑、没有会话 | 打开会话标签。列表对应当前工具栏里的那台电脑。见设备与本地网页 |
| 其他问题 | 帮助 → 导出诊断日志…，把文件附到 GitHub Issue，或到 Discord 提问 |
检查清单
- 应用能打开，且工作区指向正确的项目根目录
- 至少一个 Agent 运行时已安装并完成授权
- 能创建会话，并在运行期间看到如实的状态
- 终端里
cocurdex --help可用 - 你知道笔记、Issue 和演示文稿存在哪里（应用私有存储，而非仓库里散落的文件）