CAWRA IDE 使用手册

实用指南：安装 CAWRA IDE、连接 Grok (xAI)、配置模型，以及使用聊天、任务编排、修复和其他内置 AI 工具。

1. 什么是 CAWRA IDE？

CAWRA IDE 是一款基于 VSCodium（Visual Studio Code 分支）的 Windows 开发环境，预装了原生扩展 CAWRA AI。与仅有简单侧边栏聊天的编辑器不同，CAWRA 包含：

• 任务编排器 — 将复杂目标拆解为子任务，支持 DAG 规划、并行执行与自动验证。
• Grok 多模型 — 自动为每个阶段路由至最合适的 xAI 模型（规划、编码、验证、视觉等）。
• 可执行聊天 — Ask、Edit 与 Agent 模式，可真实访问文件与终端。
• 语义索引 — 通过 @codebase 提及实现代码库智能搜索。
• VS Code 兼容 — 支持 VS Code/Codium 常用扩展、主题与工作流。

IDE 本身免费；您只需在网站注册以下载安装程序。AI 用量通过您自己的 API Key 直接在 xAI 账户中计费。

2. 安装（Windows）

1. 注册并下载
   访问首页，使用邮箱注册，并从注册区域下载 .exe 安装程序。
2. 运行安装程序
   按照安装向导操作。CAWRA IDE 作为独立应用安装；若您已安装 VS Code，不会被替换。
3. 打开项目
   使用文件 → 打开文件夹打开您的仓库。许多功能（@路径 引用、终端、索引）需要已打开的工作区。
4. 配置 Grok
   首次启动时，CAWRA 会提示您配置 API Key。在使用聊天或任务编排前，请先完成下一节的设置。

3. 入门：Grok API Key（xAI）

CAWRA IDE 使用 xAI 的 Grok API。您需要自己的密钥（GROK_API_KEY）才能启用聊天、任务编排、行内自动补全及其他 AI 功能。

3.1 在 xAI 获取密钥

1. 进入 xAI 开发者控制台：console.x.ai。
2. 创建账户，或使用已关联的 X/Twitter 账户登录。
3. 进入 API Keys 部分，点击 Create API Key。
4. 复制生成的密钥。请妥善保存；xAI 仅显示一次。
5. （可选）在 xAI 计费控制台添加额度或查看套餐。CAWRA 不对 AI 使用收费：token 消耗计入您的 xAI 账户。

3.2 在 CAWRA IDE 中配置密钥

有三种等效方式。密钥安全存储在 IDE 密钥库中（不会以明文写入 settings）。

在对话框（隐藏字段）中粘贴密钥。长度至少 8 个字符。您将看到消息：「CAWRA: API Key de Grok configurada correctamente.»

3.3 验证连接

1. 打开 聊天 面板（Ctrl+L 打开任务编排；聊天请使用侧边栏 CAWRA AI → 聊天标签页）。
2. 发送简单消息：「你好，Grok 能用吗？」
3. 若密钥有效，数秒内会收到回复。若缺失或错误，CAWRA 会再次提示配置。

4. IDE 界面

CAWRA 保留熟悉的 VS Code 布局，并包含以下专属元素：

• 左侧边栏 — 文件资源管理器、Git、扩展等。
• 次要侧边栏（右侧） — CAWRA AI 面板，含标签页：任务编排、聊天、修复与审计。
• 状态栏 — 指示器 ✦ CAWRA（空闲）或 ↻ CAWRA（工作中）。点击打开 Hub。
• 集成终端 — 智能体在 CAWRA AI 终端中执行命令。
• CAWRA AI 菜单 — 通过全局齿轮图标快速访问设置、API Key、模型与语言。

5. CAWRA AI Hub

Hub 是 CAWRA 的控制中心。点击状态栏 ✦ CAWRA，或聊天/任务编排内的 ⚙ CAWRA 按钮打开。

可用选项：

• CAWRA Settings — 扩展的全部设置。
• API Key Grok — 配置或更换密钥。
• Modelos Grok — 聊天模型快速选择器。
• Modelos avanzados (por rol) — Planner、Executor、inline、vision、enhancer。
• Grafo de agentes — 任务编排实时可视化。
• Encargo / Chat / Auditoría — 跳转到各面板。
• Reindexar proyecto — 重建语义索引。

6. Grok 模型与路由

CAWRA 不会对所有任务使用单一模型。ModelRouter 根据每项任务的角色分配合适的 Grok 模型：

更改聊天模型

两种方式：

• 聊天面板标题栏的下拉选择器。
• Hub → Modelos Grok，或命令面板 CAWRA: Modelos Grok。

选择器中可用模型：grok-4-1-fast-reasoning、grok-4-1-fast-non-reasoning、grok-4-fast-reasoning、grok-4-fast-non-reasoning、grok-code-fast-1、grok-3、grok-3-mini、grok-2-1212、grok-2-latest。

按角色配置模型（任务编排与智能体）

在 Hub → Modelos avanzados 或设置中搜索 cawra.models 进行配置：

• cawra.models.planner — 任务编排规划器。
• cawra.models.executor — 编写代码并执行工具的智能体。
• cawra.models.inline — 编辑器 ghost text。
• cawra.models.vision — 附件图像分析。
• cawra.models.enhancer — 提示词增强。
• cawra.models.maxParallelExecutors — 并行运行的 Build executor 数量（1–8，默认 3）。

7. 高级设置

打开 文件 → 首选项 → 设置 并搜索 CAWRA AI，或使用 Hub → CAWRA Settings。

LLM 参数

• cawra.temperature — 创造性（默认 0.2）。
• cawra.maxTokens — 每次回复的最大 token 数（256–131072）。
• cawra.topP — 核采样。

上下文与索引

• cawra.contextMaxFiles / cawra.contextMaxChars — 注入上下文的限制。
• cawra.codebaseIndex.enabled — 启用语义索引。
• cawra.codebaseIndex.autoIndexOnOpen — 打开项目时自动索引。
• cawra.codebaseIndex.topKChunks — 使用 @codebase 时检索的片段数。

任务编排质量

• cawra.quality.enforceQaVerdict — QA 拒绝时阻止交付。
• cawra.quality.visualVerification — Web 项目的视觉验证。
• cawra.quality.clarifyDesign — 对歧义 UI 任务编排暂停以选择风格。
• cawra.quality.deepOnlineResearch — 并行智能体进行在线调研。
• cawra.testGate.enabled — 子任务完成前运行测试。

聊天与图像

• cawra.chat.maxImages — 每条消息最大图像数（默认 4）。
• cawra.chat.maxImageSizeMb — 单张图像最大大小（默认 5 MB）。
• cawra.promptEnhancer.enabled — 全局提示词增强。

项目文件 cawra.config.json

可在工作区或 IDE 根目录放置 cawra.config.json，作为 LLM、inline、聊天与上下文的默认值。用户在设置中的配置优先于该文件。

8. 界面语言切换

CAWRA IDE 支持三种界面语言：

• English（默认）
• Español
• 中文 (简体) — 简体中文

如何更改语言

1. 打开全局 CAWRA AI 菜单（左下角齿轮图标）。
2. 选择 Idioma / Language / 语言，或直接选择 English、Español 或 中文。
3. 也可使用命令面板：Ctrl+Shift+P → CAWRA: Idioma / Language / 语言。
4. CAWRA 将偏好保存到用户配置文件的 locale.json，并提示 Reiniciar ahora（立即重启）以应用更改。请接受窗口重启。

9. 聊天面板

聊天是 CAWRA AI 侧边栏 → 聊天 中的交互式助手。支持项目上下文、图像、文件引用，以及在高级模式下在终端中真实执行。

工作模式

聊天界面元素

• 模式选择器 — 标题栏 Ask / Edit / Agent。
• 模型选择器 — Ask 对话使用的 Grok 模型。
• 优化提示词 — 发送前使用 Enhancer 模型的复选框。
• 附加图像 — 📎 按钮、Ctrl+V 粘贴或拖拽图像到输入区。
• 工具进度 — Edit/Agent 模式下可见如「正在执行：./gradlew.bat assembleDebug」的消息。
• 清空历史 — 标题栏 🗑 按钮。

使用发送按钮或 Ctrl+Enter 发送消息。

10. 任务编排（Orchestrator）

任务编排是 CAWRA 的核心差异：您描述高层目标，编排器将其拆解、规划子任务 DAG、按阶段分配 Grok 模型，并在可能时并行执行。

典型流程

1. 分析 — 理解已打开项目、依赖与目标（若附加图像则一并分析）。
2. 规划 — Planner（Grok 4 reasoning）生成带依赖关系的子任务。
3. 执行 — 一个或多个 Executor（Grok Build）使用代码与终端工具实现各子任务。
4. 验证 — QA、可选测试及 Web 项目的视觉验证。
5. 交付 — 最终摘要，含修改的文件与结果。

如何启动任务编排

• CAWRA AI 面板 → 任务编排 标签页。
• 快捷键 Ctrl+L（聚焦编排器）。
• Hub → Encargo (Orchestrator)。

用自然语言描述目标。示例：

• 「为现有 Express 后端添加 JWT 认证」
• 「重构支付模块并添加单元测试」
• 「根据附加 mockup 创建响应式 landing page」（附加图像）

若已有任务在进行，新任务会排队（cawra.queue.maxConcurrent 控制并发）。可打开智能体关系图（Ctrl+Shift+G）查看实时进度。

11. 修复

修复面板面向错误纠正：编译失败、测试失败、运行时异常。CAWRA 分析错误上下文并提议自动修复计划，类似任务编排但聚焦于解决具体故障。

从 CAWRA AI → 修复标签页打开，或使用命令 CAWRA: Abrir Repair。

12. 审计

审计记录智能体操作历史：子任务、使用的工具、消耗的 token 与结果。便于回顾编排器行为、导出日志或调试复杂任务。

访问方式：CAWRA AI 面板 → 审计，或 Hub → Auditoría。

13. 智能体关系图

进行中或已完成任务编排的交互式可视化。在动画关系图中展示阶段节点、子任务、智能体与工具及其连接。

• 快捷键：Ctrl+Shift+G
• Hub → Grafo de agentes
• 命令：CAWRA: Grafo de agentes

14. @文件 引用与上下文

使用以下提及时，CAWRA 会自动注入项目上下文：

• @codebase — 在项目索引中进行语义搜索。
• @src/app/main.ts — 指定文件内容。
• @app/ — 文件夹内最多 20 个文件。
• @"mi carpeta/archivo con espacios" — 含空格的路径用引号包裹。

无需输入即可添加引用

• 右键资源管理器中的文件或文件夹 → CAWRA: Referenciar en Chat 或 Referenciar en Encargo。
• 拖拽文件或文件夹到聊天或任务编排输入区（显示可视化 chip）。
• 编辑器上下文菜单 — 相同的引用选项。

15. 图像与视觉

聊天与任务编排均接受参考图像：

• 输入区底部的 📎 Imagen 按钮。
• 使用 Ctrl+V 粘贴截图。
• 拖拽图像文件到输入区。

图像由 Vision 模型处理（默认 grok-2-vision-1212）。适用于 UI mockup、错误截图、规划器需遵循的图表或设计。

可配置限制：默认最多 4 张图像，每张 5 MB。

16. 行内自动补全与 Composer

Ghost text（行内补全）

输入时，CAWRA 使用 grok-3-mini 以灰色 ghost text 建议代码。

• Tab — 接受建议。
• Escape — 丢弃。
• Alt+\ — 强制触发自动补全。

通过 cawra.inlineEnabled 启用/禁用。快速模式：cawra.inline.fastMode。

行内编辑（Ctrl+K）

在编辑器中选中代码并按 Ctrl+K。输入指令（如「转换为 async/await」），CAWRA 将替换选中内容。

Composer / Agent Mode（Ctrl+I）

Ctrl+I 打开 Composer，进行多文件变更与智能体规划，类似 Cursor Agent 流程。

选中内容操作（右键）

• 解释代码 — Ctrl+Shift+E
• 重构选中内容
• 生成测试

17. 代码库语义索引

CAWRA 索引您的项目，使 @codebase 与编排器无需读取整个仓库即可找到相关代码。

• 若 cawra.codebaseIndex.autoIndexOnOpen 已启用，打开项目时自动索引。
• 手动重建：Hub → Reindexar proyecto 或 CAWRA: Reindexar proyecto。
• cawra.indexMaxFiles 限制索引文件数（默认 2000）。

18. 终端与安全

在聊天的 Agent 模式及任务编排执行期间，CAWRA 在集成终端 CAWRA AI 中运行命令。

安全控制

• cawra.shell.enabled — 启用/禁用 shell 执行（默认：启用）。
• cawra.shellBlockDestructive — 阻止 rm -rf 等破坏性命令（默认：启用）。
• cawra.agent.requireDiffApproval — 应用大型 diff 前要求确认。

gradlew、npm、git status 等常用命令在策略引擎白名单中。

19. 远程工作（SSH）

CAWRA 包含 Remote SSH 支持（基于 Open Remote SSH）：

• CAWRA: Abrir ventana remota（Open Remote Window）— 连接到主机的新窗口。
• CAWRA: Connect to Host... — 选择 SSH 主机。
• CAWRA: Configure SSH Hosts... — 编辑 ~/.ssh/config。

编排器与智能体在远程服务器上执行，如同本地一样。CAWRA AI 扩展会自动安装到远程主机。

19.1 Windows 上的 ssh-agent 服务

若 ssh-agent 无法启动（需要管理员权限），请以管理员身份在 PowerShell 中执行一次：

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

之后 SSH 代理将在 Windows 启动时自动运行，可管理私钥以进行公钥认证连接。

19.2 在 ~/.ssh/config 中配置主机

使用 CAWRA: Configure SSH Hosts... 或手动编辑本地 ~/.ssh/config。每个 Host 块定义一台服务器，可通过 Abrir ventana remota（打开远程窗口）或 Connect to Host... 连接。

公钥/私钥连接

服务器支持 SSH 密钥认证时推荐使用的格式（无需每次输入密码）：

Host NOMBRE_SERVER
  HostName IP_o_NOMBRE_HOST
  User root
  IdentityFile ~/.ssh/nombre
  IdentitiesOnly yes

• NOMBRE_SERVER — 在 CAWRA 主机选择器中显示的别名。
• HostName — 服务器公网 IP 或域名。
• User — SSH 用户（VPS 上通常为 root）。
• IdentityFile — 私钥路径（如 ~/.ssh/id_ed25519）。
• IdentitiesOnly yes — 仅使用指定密钥，不尝试代理中的其他密钥。

用户名和密码连接

使用密码进行 SSH 认证的格式（通常为 root 用户）。连接时 CAWRA 会提示输入密码：

Host NOMBRE_HOST
  HostName IP_o_NOMBRE_HOST
  User root
  LocalForward 8080 /var/www/vhosts/

• NOMBRE_HOST — 主机选择器中的服务器别名。
• HostName — 服务器 IP 或主机名。
• User root — 登录用户（通常为 root）。
• LocalForward —（可选）将本地端口转发到远程服务器；便于访问主机上的 Web 服务（如 /var/www/vhosts/ 下的站点）。

20. 键盘快捷键

21. 常见问题

CAWRA IDE 免费吗？

是的。IDE 与编排器免费。您仅按 xAI 费率在 xAI 账户中为 Grok API 使用付费。

可以使用 Grok 以外的 API 吗？

CAWRA 针对 xAI 的 OpenAI 兼容端点（https://api.x.ai/v1）优化。更换提供商需修改扩展；官方不支持。

聊天不在终端执行命令

请确认处于 Agent 模式，或使用执行类动词（「编译」「运行」等）触发自动升级。同时确认 cawra.shell.enabled 已启用。

API Key 存储在哪里？

存储在 VS Code/Codium 安全密钥库（SecretStorage），内部键为 cawra.grok.apiKey。若未保存密钥，环境变量 GROK_API_KEY 优先。

离线能用吗？

编辑器可以；AI 功能需要连接 xAI API。语义索引与本地编辑可离线使用。

兼容 VS Code 扩展吗？

是的。CAWRA 默认使用 Open VSX（https://open-vsx.org），兼容大多数 VS Code 扩展。