coara 使用文档

1. 安装与启动

安装

在首页复制一键安装命令，在 PowerShell 窗口中执行（Windows 终端或系统自带的 PowerShell 窗口都行，不影响安装）。

首次启动

新开终端，运行 coara。首次使用会自动打开 Web 配置页「模型」，填入任一厂商的 API key 保存即可。

启动方式

2. 对话与操作

在 CLI 提示符下直接输入。输入 / 可补全斜杠命令；输入 @ 可补全服务台（如 daily、配置）。

快捷键

使用习惯

• 连续输入：coara 执行工具时你可继续打字，消息会排队，在本回合结束后依次处理。
• 会话持久化：对话会落盘；/new 开启新会话（清空当前历史）。
• 切换模型：/model 按序号或名称切换；切换后采用目标模型自身参数。

斜杠命令

以下命令在 CLI 对话内输入，完整列表以 /help 为准。

3. CLI / Web / 手机

三个入口连接同一运行时，共享对话历史与配置。运行中的正文、工具过程只跟当前说话的那一端；影响整段会话的操作（新会话、打断、切模型、压缩等）若他端正在跑，会先征求同意。

• CLI：终端对话，适合长时间交互、查看工具执行过程。
• Web：默认随 coara 启动（端口可用环境变量 COARA_WEB_PORT 修改，默认 8080）。可聊天、审批敏感操作、编辑与运行工作流、查看动态与配置。
• 手机：在手机 App 页下载安装 App，再从电脑托盘菜单「手机连接（二维码）」或终端命令 /qrcode 取配对码扫码。未配置时不影响本机使用。

4. 工作空间

每个工作空间对应一个项目目录。登记多个后可在其间切换；各空间有独立的对话会话与动态收件箱。

离线登记（终端子命令）

coara ws list
coara ws add <路径> --name <名> [--summary 简介]
coara ws rename <旧名> <新名>
coara ws default <名>          # 设启动默认，不切当前会话
coara ws remove <名>            # 取消登记，保留磁盘目录
coara ws remove <名> --delete-disk

对话内切换

网页端在左侧栏点空间名切换，手机端在空间列表里点目标空间；命令行端一个终端一个工作空间，换空间请在目标目录新开终端。也可直接用自然语言说明要切换的工作空间。

若在回合进行中由 coara 主动切换工作空间，当前回合会结束，且为切换而输入的最近几条消息不会写入目标空间的历史，避免串线。

5. 工作流

适合多步骤、有分支、需重复运行或需人工审批的流程。每个步骤由智能体执行，不是固定脚本。

怎么用

• 对话：在工作流空间描述流程目标，coara 会实时编排并在画布上同步呈现。
• 画布：Web「工作流」页可视化编辑节点与连线、声明起点与终点，改动即时保存。
• 实例化：点「实例化」并确认后，草案生效为一张空间网络——每个节点是一个真实工作空间，边是订阅关系。
• 启动：在起点节点上点「运行」即启动；起点也可声明为定时（到点自动启动）或输入型（收到指定产物即启动），产物沿边接力直到终点。

草案在所有工作空间间共享；每个节点绑定一个工作空间，文件读写落在该空间目录下。

6. 事件与动态

工作空间事件：把文件变更、定时任务、webhook 等外部信号接入 coara，写入对应工作空间的动态列表（Web 与手机上有未读提示）。在对话中说「帮我加一个每天早上 9 点的定时检查」即可，也可用 /events 查看现有配置。

个人提醒：口语说明「明天 9 点提醒我…」，与工作空间事件相互独立。

查看与批示动态：在 Web「消息」页操作，或手机端工作空间菜单的红点入口。

7. 配置

COARA_HOME 解析顺序：配置文件中的 coara_home 字段 → 环境变量 COARA_HOME → 当前目录下的 .coara（试用）。长期使用建议在用户目录固定为 coara。

常用配置文件（均在 COARA_HOME 下）

也可在 Web 配置页修改大部分设置。改 .env 或系统 PATH 后请新开终端；改配置后通常需重启 coara。

8. 安全

coara 默认不会静默执行高风险操作。主要保护机制：

• 人工确认：破坏性命令、写到工作空间外的文件、删除工作流草案等会弹窗确认；约 5 分钟无响应视为未执行。
• 沙箱：对不可信来源可限制可执行的命令、路径与网络访问（配置页「安全」管理）。

数据默认留在本机。请妥善保管 API key。

9. 排障