DBT/clawgo
1
0
Fork 0
mirror of https://github.com/YspCoder/clawgo.git synced 2026-04-15 14:47:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix readme

Browse Source
This commit is contained in:
lpf
2026-03-07 12:42:05 +08:00
parent ee4a1a1775
commit fe0437b9cf
2 changed files with 211 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
README.md
View File

@@ -1,63 +1,85 @@
# ClawGo 🦞
ClawGo 是一个用 Go 构建的长期运行 Agent 系统，面向本地优先、多 Agent 协作、可审计运维。
**面向生产的 Go 原生 Agent Runtime。**
- 🎯 `main agent` 负责对话入口、路由、调度、汇总
- 🤖 `subagents` 负责具体执行，如编码、测试、文档
- 🌐 `node branches` 允许把远端节点挂成受控 agent 分支
- 🧠 记忆、线程、邮箱、任务运行态可持久化
- 🖥️ 内置统一 WebUI，覆盖配置、拓扑、日志、技能、记忆与运维
ClawGo 不是“又一个聊天壳子”，而是一套可长期运行、可观测、可恢复、可编排的 Agent 运行时。
- 👀 **可观测**：Agent 拓扑、内部流、任务审计、EKG 一体化可见
- 🔁 **可恢复**：运行态落盘，重启后任务可恢复，watchdog 按进展续时
- 🧩 **可编排**：`main agent -> subagent -> main`，支持本地与远端 node 分支
- ⚙️ **可工程化**：`config.json`、`AGENT.md`、热更新、WebUI、声明式 registry
[English](./README_EN.md)
## 架构概览
## 为什么是 ClawGo
ClawGo 的默认协作模式是：
大多数 Agent 项目停留在：
```text
user -> main -> worker -> main -> user
```
- 一个聊天界面
- 一组工具调用
- 一段 prompt
当前系统由四层组成：
ClawGo 更关注真正的运行时能力：
- `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 等运行态
- `main agent` 负责入口、路由、派发、汇总
- `subagent` 负责编码、测试、产品、文档等具体执行
- `node branch` 把远端节点挂成受控 agent 分支
- `runtime store` 持久化 run、event、thread、message、memory
## 主要能力
一句话：
- 🚦 路由与调度
- 支持 `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`
> **ClawGo = Agent Runtime，而不只是 Agent Chat。**
## 快速开始
## 核心亮点 ✨
### 1. 多 Agent 拓扑可视化
- 统一展示 `main / subagents / remote branches`
- 内部流与用户主对话分离
- 子 agent 协作过程可观测，但不污染用户通道
### 2. 任务可恢复，不是一挂全没
- `subagent_runs.jsonl`
- `subagent_events.jsonl`
- `threads.jsonl`
- `agent_messages.jsonl`
- 重启后可恢复运行中的任务
### 3. watchdog 按进展续时
- 系统超时统一走全局 watchdog
- 还在推进的任务不会因为固定墙钟超时被直接杀掉
- 无进展时才超时，行为更接近真实工程执行
### 4. 配置工程化，而不是 prompt 堆砌
- `config.json` 管理 agent registry
- `system_prompt_file -> AGENT.md`
- WebUI 可编辑、热更新、查看运行态
### 5. 适合真正长期运行
- 本地优先
- Go 原生 runtime
- 多通道接入
- Task Audit / Logs / Memory / Skills / Config / Agents 全链路闭环
## WebUI 亮点 🖥️
**Dashboard**
![ClawGo Dashboard](docs/assets/readme-dashboard.png)
**Agents 拓扑**
![ClawGo Agents Topology](docs/assets/readme-agents.png)
**Config 工作台**
![ClawGo Config](docs/assets/readme-config.png)
## 快速开始 🚀
### 1. 安装
@@ -98,45 +120,38 @@ clawgo gateway run
make dev
```
## WebUI
访问：
WebUI:
```text
http://<host>:<port>/webui?token=<gateway.token>
```
核心页面：
## 架构概览
- `Agents`
- 统一 agent 拓扑
- 本地 subagent 与远端 branch 展示
- 运行状态悬浮查看
- `Config`
- 配置编辑
- 热更新字段查看
- `Logs`
- 实时日志
- `Skills`
- 技能安装、查看、编辑
- `Memory`
- 记忆文件与摘要
- `Task Audit`
- 任务链路与执行审计
默认协作模式：
### 亮点截图
```text
user -> main -> worker -> main -> user
```
**Dashboard**
当前系统包含四层：
![ClawGo Dashboard](docs/assets/readme-dashboard.png)
1. `main agent`
负责用户入口、路由、派发、汇总
2. `local subagents`
在 `config.json -> agents.subagents` 中声明，使用独立 session 和 memory namespace
3. `node-backed branches`
远端节点作为受控 agent 分支挂载到主拓扑
4. `runtime store`
保存运行态、线程、消息、事件和审计数据
**Agents 拓扑**
## 你能用它做什么
![ClawGo Agents Topology](docs/assets/readme-agents.png)
**Config 工作台**
![ClawGo Config](docs/assets/readme-config.png)
- 🤖 本地长期运行的个人 Agent
- 🧪 `pm -> coder -> tester` 这种多 Agent 协作链
- 🌐 本地主控 + 远端 node 分支的分布式执行
- 🔍 需要强观测、强审计、强恢复的 Agent 系统
- 🏭 想把 prompt、agent、工具权限、运行策略工程化管理的团队
## 配置结构
@@ -172,8 +187,8 @@ http://<host>:<port>/webui?token=<gateway.token>
说明：
- `runtime_control` 已删除
- 现在使用：
- `runtime_control` 已移除
- 当前使用：
- `agents.defaults.execution`
- `agents.defaults.summary_policy`
- `agents.router.policy`
@@ -187,7 +202,7 @@ http://<host>:<port>/webui?token=<gateway.token>
## Prompt 文件约定
推荐把 agent prompt 放到独立文件中，例如：
推荐把 agent prompt 独立为文件：
- `agents/main/AGENT.md`
- `agents/coder/AGENT.md`
@@ -201,36 +216,34 @@ http://<host>:<port>/webui?token=<gateway.token>
}
```
约定：
规则：
- 路径必须是 workspace 内相对路径
- 这些路径只是示例，仓库不会内置对应文件
- 用户或 agent workflow 需要自行创建这些 `AGENT.md`
- 仓库不会内置这些示例文件
- 用户或 agent workflow 需要自行创建实际的 `AGENT.md`
## 记忆与运行态
ClawGo 默认不是“所有 agent 共用一份上下文”。
ClawGo 不是所有 agent 共用一份上下文。
- `main`
- 维护主记忆与协作摘要
- 保存主记忆与协作摘要
- `subagent`
- 使用独立 session key
- 写入自己的 memory namespace
- runtime store
- `runtime store`
- 持久化任务、事件、线程、消息
这样可以同时得到：
这带来三件事：
- 可恢复
- 可追踪
- 边界清晰
- 更好恢复
- 更好追踪
- 更清晰的执行边界
## 项目定位
## 当前最适合的人群
ClawGo 适合这些场景：
- 想用 Go 做 Agent Runtime 的开发者
- 想要可视化多 Agent 拓扑和内部流的团队
- 不满足于“聊天 + prompt”，而想要真正运行时能力的用户
- 本地长期运行的个人 AI agent
- 需要多 agent 协作但不想上重型编排平台
- 需要清晰配置、清晰审计、清晰可观测性的自动化系统
如果你希望先看一个完整配置，直接从 [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json) 开始。
如果你想快速上手，先看 [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json)，再跑一次 `make dev`。

194
README_EN.md
View File

@@ -1,63 +1,85 @@
# ClawGo 🦞
ClawGo is a long-running AI agent system built in Go for local-first operation, multi-agent coordination, and auditable runtime control.
**A production-oriented, Go-native Agent Runtime.**
- 🎯 `main agent` owns the user-facing loop, routing, dispatch, and merge
- 🤖 `subagents` handle concrete execution such as coding, testing, and docs
- 🌐 `node branches` let remote nodes appear as controlled agent branches
- 🧠 memory, threads, mailbox state, and task runtime are persisted
- 🖥️ a unified WebUI covers config, topology, logs, skills, memory, and ops
ClawGo is not just another chat wrapper. It is a long-running, observable, recoverable, orchestrated runtime for real agent systems.
- 👀 **Observable**: agent topology, internal streams, task audit, and EKG visibility
- 🔁 **Recoverable**: persisted runtime state, restart recovery, progress-aware watchdog
- 🧩 **Orchestrated**: `main agent -> subagent -> main`, with local and remote node branches
- ⚙️ **Operational**: `config.json`, `AGENT.md`, hot reload, WebUI, declarative registry
[中文](./README.md)
## Architecture
## Why ClawGo
The default collaboration flow is:
Most agent projects stop at:
```text
user -> main -> worker -> main -> user
```
- a chat UI
- a tool runner
- a prompt layer
ClawGo currently has four layers:
ClawGo focuses on runtime capabilities:
- `main agent`
- user-facing entrypoint
- handles routing, decomposition, dispatch, and merge
- `local subagents`
- declared in `config.json -> agents.subagents`
- use isolated sessions and memory namespaces
- `node-backed branches`
- registered nodes appear as remote agent branches in the topology
- `transport=node` tasks are sent via `agent_task`
- `runtime store`
- persists runs, events, threads, and messages
- `main agent` handles entry, routing, dispatch, and merge
- `subagents` execute coding, testing, product, docs, and other focused tasks
- `node branches` attach remote nodes as controlled agent branches
- `runtime store` persists runs, events, threads, messages, and memory
## Core Capabilities
In one line:
- 🚦 Routing and dispatch
- `rules_first`
- explicit `@agent_id`
- keyword-based auto routing
- 📦 Persistent runtime state
- `subagent_runs.jsonl`
- `subagent_events.jsonl`
- `threads.jsonl`
- `agent_messages.jsonl`
- 📨 mailbox and thread coordination
- dispatch
- wait
- reply
- ack
- 🧠 dual-write memory model
- subagents keep detailed local memory
- main memory keeps compact collaboration summaries
- 🪪 declarative agent config
- role
- tool allowlist
- runtime policy
- `system_prompt_file`
> **ClawGo is an Agent Runtime, not just an Agent Chat shell.**
## Quick Start
## Core Highlights ✨
### 1. Observable multi-agent topology
- unified view of `main / subagents / remote branches`
- internal subagent streams are visible
- user-facing chat stays clean while internal collaboration remains inspectable
### 2. Recoverable execution
- `subagent_runs.jsonl`
- `subagent_events.jsonl`
- `threads.jsonl`
- `agent_messages.jsonl`
- running tasks can recover after restart
### 3. Progress-aware watchdog
- system timeouts go through one global watchdog
- active tasks are extended instead of being killed by a fixed wall-clock timeout
- tasks time out only when they stop making progress
### 4. Engineering-first agent configuration
- agent registry in `config.json`
- `system_prompt_file -> AGENT.md`
- WebUI for editing, hot reload, and runtime inspection
### 5. Built for long-running use
- local-first
- Go-native runtime
- multi-channel capable
- end-to-end ops surface: Task Audit, Logs, Memory, Skills, Config, Agents
## WebUI Highlights 🖥️
**Dashboard**
![ClawGo Dashboard](docs/assets/readme-dashboard.png)
**Agent Topology**
![ClawGo Agents Topology](docs/assets/readme-agents.png)
**Config Workspace**
![ClawGo Config](docs/assets/readme-config.png)
## Quick Start 🚀
### 1. Install
@@ -98,45 +120,38 @@ Development mode:
make dev
```
## WebUI
Open:
WebUI:
```text
http://<host>:<port>/webui?token=<gateway.token>
```
Key pages:
## Architecture
- `Agents`
- unified agent topology
- local subagents and remote branches
- runtime status via hover
- `Config`
- configuration editing
- hot-reload field reference
- `Logs`
- real-time logs
- `Skills`
- install, inspect, and edit skills
- `Memory`
- memory files and summaries
- `Task Audit`
- execution and scheduling trace
Default collaboration flow:
### Highlights
```text
user -> main -> worker -> main -> user
```
**Dashboard**
ClawGo currently has four layers:
![ClawGo Dashboard](docs/assets/readme-dashboard.png)
1. `main agent`
user-facing entry, routing, dispatch, and merge
2. `local subagents`
declared in `config.json -> agents.subagents`, with isolated sessions and memory namespaces
3. `node-backed branches`
remote nodes mounted as controlled agent branches
4. `runtime store`
persisted runtime, threads, messages, events, and audit data
**Agent Topology**
## What It Is Good For
![ClawGo Agent Topology](docs/assets/readme-agents.png)
**Config Workspace**
![ClawGo Config](docs/assets/readme-config.png)
- 🤖 long-running local personal agents
- 🧪 multi-agent flows like `pm -> coder -> tester`
- 🌐 local control with remote node branches
- 🔍 systems that need strong observability, auditability, and recovery
- 🏭 teams that want agent config, prompts, tool permissions, and runtime policy managed as code
## Config Layout
@@ -173,7 +188,7 @@ Recommended structure:
Notes:
- `runtime_control` has been removed
- the current config uses:
- the current structure uses:
- `agents.defaults.execution`
- `agents.defaults.summary_policy`
- `agents.router.policy`
@@ -183,11 +198,11 @@ Notes:
- `node_id`
- `parent_agent_id`
See the full example in [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json).
See [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json) for a full example.
## Prompt File Convention
Keep agent prompts in dedicated files, for example:
Keep agent prompts in dedicated files:
- `agents/main/AGENT.md`
- `agents/coder/AGENT.md`
@@ -204,8 +219,7 @@ Example:
Rules:
- the path must be relative to the workspace
- the file must live inside the workspace
- these paths are examples only; the repo does not ship the files
- the repo does not ship these example files
- users or agent workflows should create the actual `AGENT.md` files
## Memory and Runtime
@@ -217,21 +231,19 @@ ClawGo does not treat all agents as one shared context.
- `subagent`
- uses its own session key
- writes to its own memory namespace
- runtime store
- `runtime store`
- persists runs, events, threads, and messages
This gives you:
- recoverability
- traceability
- clear execution boundaries
- better recovery
- better traceability
- clearer execution boundaries
## Positioning
## Best Fit
ClawGo is a good fit for:
- developers building agent runtimes in Go
- teams that want visible multi-agent topology and internal collaboration streams
- users who need more than “chat + prompt”
- local long-running personal agents
- multi-agent workflows without heavyweight orchestration platforms
- systems that need explicit config, explicit audit trails, and strong observability
If you want a working starting point, begin with [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json).
If you want a working starting point, open [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json) and run `make dev`.