mirror of
https://github.com/YspCoder/clawgo.git
synced 2026-05-17 11:47:28 +08:00
Rewrite README for current agent architecture
This commit is contained in:
lpf
343
README.md
343
README.md
@@ -1,75 +1,150 @@
|
|||||||
# ClawGo 🚀
|
# ClawGo
|
||||||
|
|
||||||
一个 Go 写的长期运行 AI Agent：轻量、可审计、可多通道接入。
|
一个用 Go 编写的长期运行 AI Agent 系统，核心特点是：
|
||||||
|
|
||||||
|
- 主 agent + subagent 的声明式配置
|
||||||
|
- 可持久化的 run / thread / mailbox 运行态
|
||||||
|
- node 注册后的远端 agent 分支
|
||||||
|
- 多通道接入与统一 WebUI 运维面板
|
||||||
|
- 轻量、可审计、适合长期运行
|
||||||
|
|
||||||
[English](./README_EN.md)
|
[English](./README_EN.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 它能做什么 ✨
|
## 当前架构
|
||||||
|
|
||||||
- 🤖 本地对话模式：`clawgo agent`
|
ClawGo 现在不是“单 agent + 一堆工具”的结构，而是一个可编排的 agent tree：
|
||||||
- 🌐 网关服务模式：`clawgo gateway`
|
|
||||||
- 💬 多通道接入：Telegram / Feishu / Discord / WhatsApp / QQ / DingTalk / MaixCam
|
- `main agent`
|
||||||
- 🧰 工具调用、技能系统、子任务协同
|
- 用户入口
|
||||||
- 🧠 自治任务（队列、审计、冲突锁）
|
- 负责路由、调度、汇总结果
|
||||||
- 📊 WebUI 可视化（Chat / Logs / Config / Cron / Tasks / EKG）
|
- `local subagents`
|
||||||
|
- 例如 `coder`、`tester`
|
||||||
|
- 由 `config.json` 中的 `agents.subagents` 声明
|
||||||
|
- `node-backed branches`
|
||||||
|
- 注册进来的 node 会被视为 `main` 下的一条远端 agent 分支
|
||||||
|
- 形如 `node.<node_id>.main`
|
||||||
|
- 可以作为主 agent 的受控执行目标
|
||||||
|
|
||||||
|
默认协作模式是：
|
||||||
|
|
||||||
|
```text
|
||||||
|
user -> main -> worker -> main -> user
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 并发调度（新）⚙️
|
## 主要能力
|
||||||
|
|
||||||
- 🧩 一条复合消息会先自动拆成多个子任务
|
### 1. Agent 配置与路由
|
||||||
- 🔀 同一会话内：无资源冲突的子任务可并发执行
|
|
||||||
- 🔒 同一会话内：有资源冲突的子任务自动串行（避免互相踩）
|
- `agents.router`
|
||||||
- 🏷️ 默认会自动推断 `resource_keys`，无需手动填写
|
- 主 agent 路由配置
|
||||||
|
- 支持 `rules_first`、显式 `@agent_id` 路由、关键词路由
|
||||||
|
- `agents.subagents`
|
||||||
|
- 声明 subagent 身份、角色、运行参数、工具白名单
|
||||||
|
- `system_prompt_file`
|
||||||
|
- subagent 优先读取 `agents/<agent_id>/AGENT.md`
|
||||||
|
- 不再依赖一句短 inline prompt
|
||||||
|
|
||||||
|
### 2. Subagent 运行态持久化
|
||||||
|
|
||||||
|
运行态会落到：
|
||||||
|
|
||||||
|
- `workspace/agents/runtime/subagent_runs.jsonl`
|
||||||
|
- `workspace/agents/runtime/subagent_events.jsonl`
|
||||||
|
- `workspace/agents/runtime/threads.jsonl`
|
||||||
|
- `workspace/agents/runtime/agent_messages.jsonl`
|
||||||
|
|
||||||
|
因此可以支持：
|
||||||
|
|
||||||
|
- run 恢复
|
||||||
|
- 线程追踪
|
||||||
|
- mailbox / inbox 查询
|
||||||
|
- dispatch / wait / merge
|
||||||
|
|
||||||
|
### 3. Node 分支
|
||||||
|
|
||||||
|
注册进来的 node 不只是设备状态，而是一个远端主 agent 分支：
|
||||||
|
|
||||||
|
- node 会出现在统一 agent topology 里
|
||||||
|
- 远端 registry 会以只读镜像方式展示
|
||||||
|
- `transport=node` 的 subagent 会通过 `agent_task` 发往远端 node
|
||||||
|
|
||||||
|
### 4. WebUI
|
||||||
|
|
||||||
|
当前 WebUI 已经整合为统一的 agent 操作台，包含：
|
||||||
|
|
||||||
|
- Dashboard
|
||||||
|
- Chat
|
||||||
|
- Config
|
||||||
|
- Logs
|
||||||
|
- Cron
|
||||||
|
- Skills
|
||||||
|
- Memory
|
||||||
|
- Task Audit
|
||||||
|
- EKG
|
||||||
|
- Agents
|
||||||
|
- 统一的 agent topology
|
||||||
|
- 本地/远端 agent 树
|
||||||
|
- subagent runtime
|
||||||
|
- registry
|
||||||
|
- prompt file editor
|
||||||
|
- dispatch / thread / inbox
|
||||||
|
|
||||||
|
### 5. 记忆策略
|
||||||
|
|
||||||
|
记忆不是简单共用，也不是完全隔离，而是双写：
|
||||||
|
|
||||||
|
- `main`
|
||||||
|
- 维护主记忆与协作摘要
|
||||||
|
- `subagent`
|
||||||
|
- 写入自己的 namespaced memory
|
||||||
|
- 路径类似 `workspace/agents/<memory_ns>/...`
|
||||||
|
- 对于 subagent 的自动摘要：
|
||||||
|
- 子 agent 自己记详细日志
|
||||||
|
- 主记忆里同步保留一条简洁协作摘要
|
||||||
|
|
||||||
|
当前摘要格式大致是：
|
||||||
|
|
||||||
|
```md
|
||||||
|
## 15:04 Code Agent | 修复登录接口并补测试
|
||||||
|
|
||||||
|
- Did: 完成了登录接口修复、增加回归测试，并验证通过。
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 记忆与 EKG 增强（新）🧠
|
## 3 分钟上手
|
||||||
|
|
||||||
- 📚 每个子任务执行前会自动检索相关记忆（`memory_search`）
|
### 1. 安装
|
||||||
- 🚨 会结合 EKG 与任务审计识别“重复错误签名”风险
|
|
||||||
- ⏱️ 高风险任务会自动附带重试退避建议，减少重复踩坑
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Telegram 流式渲染优化（新）💬
|
|
||||||
|
|
||||||
- 🧷 只在语法安全断点刷新流式内容（减少格式抖动）
|
|
||||||
- ✅ 结束时做一次最终收敛渲染，保证排版稳定
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3 分钟上手 ⚡
|
|
||||||
|
|
||||||
### 1) 安装
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://raw.githubusercontent.com/YspCoder/clawgo/main/install.sh | bash
|
curl -fsSL https://raw.githubusercontent.com/YspCoder/clawgo/main/install.sh | bash
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2) 初始化
|
### 2. 初始化
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
clawgo onboard
|
clawgo onboard
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3) 配置 Provider
|
### 3. 配置 provider
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
clawgo provider
|
clawgo provider
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4) 看状态
|
### 4. 查看状态
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
clawgo status
|
clawgo status
|
||||||
```
|
```
|
||||||
|
|
||||||
### 5) 开始使用
|
### 5. 启动
|
||||||
|
|
||||||
本地模式：
|
本地交互模式：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
clawgo agent
|
clawgo agent
|
||||||
@@ -79,18 +154,20 @@ clawgo agent -m "Hello"
|
|||||||
网关模式：
|
网关模式：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 注册并启用 systemd 服务
|
|
||||||
clawgo gateway
|
clawgo gateway
|
||||||
clawgo gateway start
|
clawgo gateway start
|
||||||
clawgo gateway status
|
clawgo gateway status
|
||||||
|
```
|
||||||
|
|
||||||
# 或前台运行
|
前台运行：
|
||||||
|
|
||||||
|
```bash
|
||||||
clawgo gateway run
|
clawgo gateway run
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## WebUI 🖥️
|
## WebUI
|
||||||
|
|
||||||
访问地址：
|
访问地址：
|
||||||
|
|
||||||
@@ -98,23 +175,101 @@ clawgo gateway run
|
|||||||
http://<host>:<port>/webui?token=<gateway.token>
|
http://<host>:<port>/webui?token=<gateway.token>
|
||||||
```
|
```
|
||||||
|
|
||||||
主要页面：
|
建议重点看这几个页面：
|
||||||
|
|
||||||
- Dashboard
|
- `Agents`
|
||||||
- Chat
|
- 看整个 agent tree
|
||||||
- Logs
|
- 看 node 分支
|
||||||
- Skills
|
- 看当前运行任务
|
||||||
- Config
|
- 配置本地 subagent
|
||||||
- Cron
|
- `Config`
|
||||||
- Nodes
|
- 调整配置
|
||||||
- Memory
|
- `Logs`
|
||||||
- Task Audit
|
- 实时日志
|
||||||
- Tasks
|
- `Task Audit`
|
||||||
- EKG
|
- 看任务拆解、调度与执行痕迹
|
||||||
|
- `EKG`
|
||||||
|
- 看错误签名、来源统计、负载分布
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 常用命令 📌
|
## 配置结构
|
||||||
|
|
||||||
|
当前推荐围绕这些字段配置：
|
||||||
|
|
||||||
|
```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": {},
|
||||||
|
"node.edge-dev.main": {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
关键点：
|
||||||
|
|
||||||
|
- `runtime_control` 已移除
|
||||||
|
- 现在使用：
|
||||||
|
- `agents.defaults.execution`
|
||||||
|
- `agents.defaults.summary_policy`
|
||||||
|
- `agents.router.policy`
|
||||||
|
- 启用中的本地 subagent 必须配置 `system_prompt_file`
|
||||||
|
- node-backed agent 使用：
|
||||||
|
- `transport: "node"`
|
||||||
|
- `node_id`
|
||||||
|
- `parent_agent_id`
|
||||||
|
|
||||||
|
可参考完整示例：
|
||||||
|
|
||||||
|
- [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Subagent Prompt 约定
|
||||||
|
|
||||||
|
推荐为每个 agent 提供独立 prompt 文件：
|
||||||
|
|
||||||
|
- `agents/main/AGENT.md`
|
||||||
|
- `agents/coder/AGENT.md`
|
||||||
|
- `agents/tester/AGENT.md`
|
||||||
|
|
||||||
|
对应配置示例：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"system_prompt_file": "agents/coder/AGENT.md"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
规则：
|
||||||
|
|
||||||
|
- 路径必须是 workspace 内相对路径
|
||||||
|
- 创建 subagent 时应同时更新 config 和对应 `AGENT.md`
|
||||||
|
- 如果 subagent 职责发生实质变化，应同步更新它的 `AGENT.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 常用命令
|
||||||
|
|
||||||
```text
|
```text
|
||||||
clawgo onboard
|
clawgo onboard
|
||||||
@@ -123,7 +278,6 @@ clawgo status
|
|||||||
clawgo agent [-m "..."]
|
clawgo agent [-m "..."]
|
||||||
clawgo gateway [run|start|stop|restart|status]
|
clawgo gateway [run|start|stop|restart|status]
|
||||||
clawgo config set|get|check|reload
|
clawgo config set|get|check|reload
|
||||||
clawgo channel test ...
|
|
||||||
clawgo cron ...
|
clawgo cron ...
|
||||||
clawgo skills ...
|
clawgo skills ...
|
||||||
clawgo uninstall [--purge] [--remove-bin]
|
clawgo uninstall [--purge] [--remove-bin]
|
||||||
@@ -131,74 +285,49 @@ clawgo uninstall [--purge] [--remove-bin]
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 构建与发布 🛠️
|
## 构建
|
||||||
|
|
||||||
构建全部默认平台：
|
本地构建：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make build
|
||||||
|
```
|
||||||
|
|
||||||
|
全平台构建：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
make build-all
|
make build-all
|
||||||
```
|
```
|
||||||
|
|
||||||
Linux 瘦身构建：
|
打包：
|
||||||
|
|
||||||
```bash
|
|
||||||
make build-linux-slim
|
|
||||||
```
|
|
||||||
|
|
||||||
自定义平台矩阵：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make build-all BUILD_TARGETS="linux/amd64 linux/arm64 darwin/arm64 windows/amd64"
|
|
||||||
```
|
|
||||||
|
|
||||||
打包并生成校验：
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
make package-all
|
make package-all
|
||||||
```
|
```
|
||||||
|
|
||||||
产物：
|
---
|
||||||
|
|
||||||
- `build/*.tar.gz`（Linux/macOS）
|
## 当前设计取向
|
||||||
- `build/*.zip`（Windows）
|
|
||||||
- `build/checksums.txt`
|
ClawGo 当前刻意偏向这些原则：
|
||||||
|
|
||||||
|
- 主 agent 仲裁优先
|
||||||
|
- 运行态落盘优先
|
||||||
|
- 配置声明优先
|
||||||
|
- WebUI 先做统一运维台，再做复杂自动化
|
||||||
|
- node 先作为受控远端 agent 分支，而不是完全独立自治体
|
||||||
|
|
||||||
|
也就是说，这个项目更像一个：
|
||||||
|
|
||||||
|
- 可长期运行的个人 AI agent runtime
|
||||||
|
- 带多 agent 编排能力
|
||||||
|
- 带 node 扩展能力
|
||||||
|
- 带运维与审计面的系统
|
||||||
|
|
||||||
|
而不是一个“只会聊天”的单体机器人。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 自动发布（GitHub Release）📦
|
## License
|
||||||
|
|
||||||
仓库内置 `.github/workflows/release.yml`。
|
|
||||||
|
|
||||||
触发方式：
|
|
||||||
|
|
||||||
- 推送 tag（如 `v0.0.2`）
|
|
||||||
- 手动触发 workflow_dispatch
|
|
||||||
|
|
||||||
示例：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git tag v0.0.2
|
|
||||||
git push origin v0.0.2
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 配置说明 ⚙️
|
|
||||||
|
|
||||||
- 配置文件严格 JSON 校验（未知字段会报错）
|
|
||||||
- 支持热更新：`clawgo config reload`
|
|
||||||
- 热更新失败会自动回滚备份
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 稳定运行建议 ✅
|
|
||||||
|
|
||||||
- 打开通道去重窗口（防重复消息）
|
|
||||||
- 定期看 Task Audit 和 EKG（查慢任务与高频错误）
|
|
||||||
- 长期运行推荐使用 `gateway` 服务模式
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## License 📄
|
|
||||||
|
|
||||||
见仓库中的 `LICENSE` 文件。
|
见仓库中的 `LICENSE` 文件。
|
||||||
|
|||||||
Reference in New Issue
Block a user