# co-flow

**Repository Path**: theone-sun/co-flow

## Basic Information

- **Project Name**: co-flow
- **Description**: 一个agentscope的多智能体助手
- **Primary Language**: Python
- **License**: MIT-0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-26
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Co-Flow

**Co-Flow**（Collaborative Flow）是在 **AgentScope 1.x** 上实现的一套运行时：**主 ReAct 智能体**、**YAML 模型配置**、**SKILL.md 能力说明**、**子智能体委派工具**，以及一个极简 **FastAPI** 网关。

## 功能概览

| 组件 | 说明 |
|------|------|
| 主智能体 | `ReActAgent`（由 YAML 配置模型） |
| HTTP API | FastAPI：`/health`、`/v1/chat`、`/v1/chat/stream` 等 |
| Skills（`SKILL.md`） | `skills/public`、`skills/custom` 拼入系统提示 |
| 子智能体 | 工具 `delegate_to_subagent`（嵌套 `ReActAgent`） |
| 工具扩展 | 可选：`execute_python_code`（`pip install co-flow[full]`）等 |
| IM 通道 | 可选：与 deer-flow 类似的 `MessageBus` + 调度器；Telegram（`pip install co-flow[channels]`）或 `POST /v1/channels/ingest` 模拟入站 |

整体架构与模块说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## Web 控制台（类「千问」布局）

1. 启动后端（默认 `2030` 端口）。
2. 另开终端：

```bash
cd frontend
npm install
npm run dev
```

3. 浏览器打开 **http://127.0.0.1:5173** 。Vite 会将 `/v1`、`/health`、`/docs` 等代理到后端。

生产构建：`cd frontend && npm run build`，产物在 `frontend/dist`（可由任意静态服务器托管）。

**后端地址**：页面右上角「后端」可填 **IP/主机名、端口、是否 HTTPS**，并保存到浏览器本地；未保存时使用环境变量或默认 `http://127.0.0.1:2030`。构建时可设 `VITE_CO_FLOW_HOST`、`VITE_CO_FLOW_PORT`、`VITE_CO_FLOW_SECURE`，或完整 `VITE_API_BASE`（见 `frontend/.env.example`）。

## 环境要求

- Python 3.10+
- 至少配置一个聊天模型 API（示例默认为 OpenAI 兼容）

## 安装

```bash
cd co-flow
pip install -e .
# 使用本地 Ollama 时安装官方 Python SDK（AgentScope 的 OllamaChatModel 依赖它）：
# pip install -e ".[ollama]"
# 如需内置 Python 执行等完整工具集：
# pip install -e ".[full]"
# IM 通道（Telegram）：
# pip install -e ".[channels]"
```

启用方式：在 `config.yaml` 中设置 `channels.enabled: true`；Telegram 需配置 `channels.telegram` 并设置 `TELEGRAM_BOT_TOKEN`。联调可用 `POST /v1/channels/ingest` 将消息推入队列（可选环境变量 `CO_FLOW_CHANNEL_INGEST_SECRET` + 请求头 `X-Ingest-Secret`）。详见 `config.example.yaml`。

## 使用 Ollama（本地）

1. 安装并启动 [Ollama](https://ollama.com/)，拉取模型：`ollama pull qwen2.5:latest`（或你需要的模型）。
2. `pip install -e ".[ollama]"`。
3. 复制 `config.example.yaml` 为 `config.yaml`，将 `models.default` 改为 `ollama-local`，并按需修改 `model_name` / `base_url`（默认 `http://127.0.0.1:11434`）。
4. `generate_kwargs` 会映射为 Ollama 的 `options`（如 `temperature`、`num_ctx`、`num_predict` 等）。

## 配置

```bash
copy config.example.yaml config.yaml
# 编辑 config.yaml：OpenAI 填 OPENAI_API_KEY；用 Ollama 时见上一节
set OPENAI_API_KEY=sk-...
```

可选环境变量见 `.env.example`。

## 使用通义千问（阿里云 DashScope）

1. 在 [阿里云 DashScope](https://dashscope.console.aliyun.com/) 创建 API Key。
2. 设置环境变量 `DASHSCOPE_API_KEY`（或在 `config.yaml` 中直接写 `api_key`，不推荐提交仓库）。
3. 在 `config.yaml` 的 `models.entries` 中已包含示例条目 `qwen-dashscope`（`provider: qwen`，与 `dashscope` 等价）；将 `models.default` 改为 `qwen-dashscope`。
4. 流式接口需为该条目开启 `stream: true`，并建议 `agent.stream_llm: true`（见 `config.example.yaml`）。
5. 可选：通过 `base_url` 指定 DashScope 网关地址，会传给 AgentScope 的 `base_http_api_url`。

## 运行服务

```bash
co-flow --port 2030 --config d:\owner\Economic-Analyst\co-flow\config.yaml
# 或
python -m coflow --port 2030
```

若在项目根目录已存在 `config.yaml`，也可省略 `--config`，并设置工作目录为 `co-flow`。

访问：

- 根路径：`GET http://127.0.0.1:2030/`（简要说明与文档链接；非 Web 聊天 UI）
- 健康检查：`GET http://127.0.0.1:2030/health`
- 对话（一次性 JSON）：`POST http://127.0.0.1:2030/v1/chat`
- **流式（SSE）**：`POST http://127.0.0.1:2030/v1/chat/stream`，`Accept: text/event-stream`，响应为 `data: {...}\\n\\n` 行；事件含 `thread` / `chunk` / `done` / `error`。请在 `config.yaml` 中为模型开启 **`stream: true`**，并建议 **`agent.stream_llm: true`**（见 `config.example.yaml`）。Web 控制台默认走流式接口。

## 自定义 Skills

在 `skills/custom/<name>/SKILL.md` 添加 Markdown；启动时会**全量合并**进主智能体系统提示（适合中小体积说明）。

## 许可证

MIT（与上层仓库策略一致时可再调整）。