mirror of
https://github.com/YspCoder/clawgo.git
synced 2026-04-14 19:37:31 +08:00
237 lines
4.6 KiB
Markdown
237 lines
4.6 KiB
Markdown
# ClawGo 🦞
|
||
|
||
ClawGo 是一个用 Go 构建的长期运行 Agent 系统，面向本地优先、多 Agent 协作、可审计运维。
|
||
|
||
- 🎯 `main agent` 负责对话入口、路由、调度、汇总
|
||
- 🤖 `subagents` 负责具体执行，如编码、测试、文档
|
||
- 🌐 `node branches` 允许把远端节点挂成受控 agent 分支
|
||
- 🧠 记忆、线程、邮箱、任务运行态可持久化
|
||
- 🖥️ 内置统一 WebUI，覆盖配置、拓扑、日志、技能、记忆与运维
|
||
|
||
[English](./README_EN.md)
|
||
|
||
## 架构概览
|
||
|
||
ClawGo 的默认协作模式是：
|
||
|
||
```text
|
||
user -> main -> worker -> main -> user
|
||
```
|
||
|
||
当前系统由四层组成：
|
||
|
||
- `main agent`
|
||
- 用户入口
|
||
- 负责路由、拆解、派发、汇总
|
||
- `local subagents`
|
||
- 在 `config.json -> agents.subagents` 中声明
|
||
- 使用独立 session 和 memory namespace
|
||
- `node-backed branches`
|
||
- 注册 node 后，会在主拓扑里表现为远端 agent 分支
|
||
- `transport=node` 的任务通过 `agent_task` 发往远端
|
||
- `runtime store`
|
||
- 保存 run、event、thread、message 等运行态
|
||
|
||
## 主要能力
|
||
|
||
- 🚦 路由与调度
|
||
- 支持 `rules_first`
|
||
- 支持显式 `@agent_id`
|
||
- 支持关键词自动路由
|
||
- 📦 持久化运行态
|
||
- `subagent_runs.jsonl`
|
||
- `subagent_events.jsonl`
|
||
- `threads.jsonl`
|
||
- `agent_messages.jsonl`
|
||
- 📨 mailbox / thread 协作
|
||
- dispatch
|
||
- wait
|
||
- reply
|
||
- ack
|
||
- 🧠 记忆双写
|
||
- 子 agent 写自己的详细记忆
|
||
- 主记忆保留简洁协作摘要
|
||
- 🪪 声明式 agent 配置
|
||
- role
|
||
- tool allowlist
|
||
- runtime policy
|
||
- `system_prompt_file`
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/YspCoder/clawgo/main/install.sh | bash
|
||
```
|
||
|
||
### 2. 初始化
|
||
|
||
```bash
|
||
clawgo onboard
|
||
```
|
||
|
||
### 3. 配置模型
|
||
|
||
```bash
|
||
clawgo provider
|
||
```
|
||
|
||
### 4. 启动
|
||
|
||
交互模式：
|
||
|
||
```bash
|
||
clawgo agent
|
||
clawgo agent -m "Hello"
|
||
```
|
||
|
||
网关模式：
|
||
|
||
```bash
|
||
clawgo gateway run
|
||
```
|
||
|
||
开发模式：
|
||
|
||
```bash
|
||
make dev
|
||
```
|
||
|
||
## WebUI
|
||
|
||
访问：
|
||
|
||
```text
|
||
http://<host>:<port>/webui?token=<gateway.token>
|
||
```
|
||
|
||
核心页面：
|
||
|
||
- `Agents`
|
||
- 统一 agent 拓扑
|
||
- 本地 subagent 与远端 branch 展示
|
||
- 运行状态悬浮查看
|
||
- `Config`
|
||
- 配置编辑
|
||
- 热更新字段查看
|
||
- `Logs`
|
||
- 实时日志
|
||
- `Skills`
|
||
- 技能安装、查看、编辑
|
||
- `Memory`
|
||
- 记忆文件与摘要
|
||
- `Task Audit`
|
||
- 任务链路与执行审计
|
||
|
||
### 亮点截图
|
||
|
||
**Dashboard**
|
||
|
||
|
||
|
||
**Agents 拓扑**
|
||
|
||
|
||
|
||
**Config 工作台**
|
||
|
||
|
||
|
||
## 配置结构
|
||
|
||
当前推荐结构：
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"context_compaction": {},
|
||
"execution": {},
|
||
"summary_policy": {}
|
||
},
|
||
"router": {
|
||
"enabled": true,
|
||
"main_agent_id": "main",
|
||
"strategy": "rules_first",
|
||
"policy": {
|
||
"intent_max_input_chars": 1200,
|
||
"max_rounds_without_user": 200
|
||
},
|
||
"rules": []
|
||
},
|
||
"communication": {},
|
||
"subagents": {
|
||
"main": {},
|
||
"coder": {},
|
||
"tester": {}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `runtime_control` 已删除
|
||
- 现在使用：
|
||
- `agents.defaults.execution`
|
||
- `agents.defaults.summary_policy`
|
||
- `agents.router.policy`
|
||
- 启用中的本地 subagent 必须配置 `system_prompt_file`
|
||
- 远端分支需要：
|
||
- `transport: "node"`
|
||
- `node_id`
|
||
- `parent_agent_id`
|
||
|
||
完整示例见 [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json)。
|
||
|
||
## Prompt 文件约定
|
||
|
||
推荐把 agent prompt 放到独立文件中，例如：
|
||
|
||
- `agents/main/AGENT.md`
|
||
- `agents/coder/AGENT.md`
|
||
- `agents/tester/AGENT.md`
|
||
|
||
配置示例：
|
||
|
||
```json
|
||
{
|
||
"system_prompt_file": "agents/coder/AGENT.md"
|
||
}
|
||
```
|
||
|
||
约定：
|
||
|
||
- 路径必须是 workspace 内相对路径
|
||
- 这些路径只是示例，仓库不会内置对应文件
|
||
- 用户或 agent workflow 需要自行创建这些 `AGENT.md`
|
||
|
||
## 记忆与运行态
|
||
|
||
ClawGo 默认不是“所有 agent 共用一份上下文”。
|
||
|
||
- `main`
|
||
- 维护主记忆与协作摘要
|
||
- `subagent`
|
||
- 使用独立 session key
|
||
- 写入自己的 memory namespace
|
||
- runtime store
|
||
- 持久化任务、事件、线程、消息
|
||
|
||
这样可以同时得到：
|
||
|
||
- 可恢复
|
||
- 可追踪
|
||
- 边界清晰
|
||
|
||
## 项目定位
|
||
|
||
ClawGo 适合这些场景：
|
||
|
||
- 本地长期运行的个人 AI agent
|
||
- 需要多 agent 协作但不想上重型编排平台
|
||
- 需要清晰配置、清晰审计、清晰可观测性的自动化系统
|
||
|
||
如果你希望先看一个完整配置，直接从 [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json) 开始。
|