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

Slim subagent runtime surface and remove legacy interfaces

Browse Source
This commit is contained in:
LPF
2026-03-17 13:41:12 +08:00
parent 341e578c9f
commit 0674d85ae1
76 changed files with 778 additions and 8782 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
README.md
View File

@@ -1,13 +1,13 @@
# ClawGo 🦞
# ClawGo
**面向生产的 Go 原生 Agent Runtime。**
ClawGo 不是“又一个聊天壳子”，而是一套可长期运行、可观测、可恢复、可编排的 Agent 运行时。
- 👀 **可观测**：Agent 拓扑、内部流、任务审计、EKG 一体化可见
- 🔁 **可恢复**：运行态落盘，重启后任务可恢复，watchdog 按进展续时
- 🧩 **可编排**：`main agent -> subagent -> main`，支持本地与远端 node 分支
- ⚙️ **可工程化**：`config.json`、`AGENT.md`、热更新、WebUI、声明式 registry
- `main agent` 负责入口、路由、派发、汇总
- `subagent runtime` 负责本地或远端分支执行
- `runtime store` 持久化 run、event、thread、message、memory
- WebUI 负责检查、状态展示和账号管理，不负责运行时配置写入
[English](./README_EN.md)
@@ -21,74 +21,59 @@ ClawGo 不是“又一个聊天壳子”，而是一套可长期运行、可观
ClawGo 更关注真正的运行时能力：
- `main agent` 负责入口、路由、派发、汇总
- `subagent` 负责编码、测试、产品、文档等具体执行
- `node branch` 把远端节点挂成受控 agent 分支
- `runtime store` 持久化 run、event、thread、message、memory
- 多 Agent 拓扑和内部协作流
- 可恢复的 subagent run
- 本地主控加远端 node 分支
- 配置、审计、日志、记忆的工程化闭环
一句话：
> **ClawGo = Agent Runtime，而不只是 Agent Chat。**
> **ClawGo 是 Agent Runtime，而不只是 Agent Chat。**
## 核心亮点 ✨
## 核心能力
### 1. 多 Agent 拓扑可视化
### 1. 多 Agent 拓扑
- 统一展示 `main / subagents / remote branches`
- 内部流与用户主对话分离
- 子 agent 协作过程可观测，但不污染用户通道
- 内部协作流与用户对话分离
- 子代理执行过程可追踪，但不会污染用户主通道
### 2. 任务可恢复，不是一挂全没
### 2. 可恢复执行
- `subagent_runs.jsonl`
- `subagent_events.jsonl`
- `threads.jsonl`
- `agent_messages.jsonl`
- 重启后可恢复运行中的任务
- 重启后可恢复进行中的 subagent run
### 3. watchdog 按进展续时
- 系统超时统一走全局 watchdog
- 还在推进的任务不会因为固定墙钟超时被直接杀掉
- 无进展时才超时，行为更接近真实工程执行
### 4. 配置工程化，而不是 prompt 堆砌
### 3. 工程化配置
- `config.json` 管理 agent registry
- `system_prompt_file -> AGENT.md`
- WebUI 可编辑、热更新、查看运行态
- WebUI 可查看状态、节点、账号与运行信息
- 运行时配置修改回到文件，不通过 WebUI 写入
### 5. Spec Coding（规范驱动开发）
- 明确需要编码且属于非 trivial 的任务可走 `spec.md -> tasks.md -> checklist.md`
- 小修小补、轻微代码调整、单点改动默认不启用这套流程
- `spec.md` 负责范围、决策、权衡
- `tasks.md` 负责任务拆解和进度更新
- `checklist.md` 负责最终完整性核查
- 这三份文档是活文档，允许在开发过程中持续修订
### 6. 适合真正长期运行
### 4. 长期运行能力
- 本地优先
- Go 原生 runtime
- 多通道接入
- Task Audit / Logs / Memory / Skills / Config / Agents 全链路闭环
## WebUI 亮点 🖥️
## WebUI
**Dashboard**
WebUI 当前定位：
![ClawGo Dashboard](docs/assets/readme-dashboard.png)
- Dashboard 与 Agent 拓扑查看
- 节点、日志、记忆、运行态检查
- OAuth 账号管理
**Agents 拓扑**
WebUI 当前不负责：
![ClawGo Agents Topology](docs/assets/readme-agents.png)
- 修改 subagent/runtime 配置
- 查询或控制公开 task runtime
**Config 工作台**
![ClawGo Config](docs/assets/readme-config.png)
## 快速开始 🚀
## 快速开始
### 1. 安装
@@ -110,28 +95,18 @@ clawgo provider use openai/gpt-5.4
clawgo provider configure
```
如果服务商使用 OAuth 登录，例如 `Codex`、`Anthropic`、`Antigravity`、`Gemini CLI`、`Kimi`、`Qwen`：
如果服务商使用 OAuth，例如 `codex`、`anthropic`、`gemini`、`kimi`、`qwen`：
```bash
clawgo provider list
clawgo provider login codex
clawgo provider login codex --manual
```
登录完成后会把 OAuth 凭证保存到本地，并自动同步该账号可用模型，后续可直接作为普通 provider 使用。
回调型 OAuth（如 `codex` / `anthropic` / `antigravity` / `gemini`）在云服务器场景下可使用 `--manual`：服务端打印授权链接，你在桌面浏览器登录后，把最终回调 URL 粘贴回终端即可完成换取 token。
设备码型 OAuth（如 `kimi` / `qwen`）会直接打印验证链接和用户码，桌面浏览器完成授权后，网关会自动轮询换取 token，无需回填 callback URL。
对同一个 provider 重复执行 `clawgo provider login codex --manual` 会追加多个 OAuth 账号；当某个账号额度耗尽或触发限流时，会自动切换到下一个已登录账号重试。
WebUI 也支持发起 OAuth 登录、回填 callback URL、设备码确认、上传 `auth.json`、查看账号列表、手动刷新和删除账号。
如果你同时有 `API key` 和 `OAuth` 账号，推荐直接把同一个 provider 配成 `auth: "hybrid"`：
如果同一个 provider 同时有 `API key` 和 `OAuth` 账号，推荐配置 `auth: "hybrid"`：
- 优先使用 `api_key`
- 当 `api_key` 触发额度不足、429、限流等错误时，自动切到该 provider 下的 OAuth 账号池
- OAuth 账号仍然支持多账号轮换、后台预刷新、`auth.json` 导入和 WebUI 管理
- `oauth.cooldown_sec` 可控制某个 OAuth 账号被限流后暂时熔断多久，默认 `900`
- provider runtime 面板会显示当前候选池排序、最近一次成功命中的凭证，以及最近命中/错误历史
- 如需在重启后保留 runtime 历史，可给 provider 配置 `runtime_persist`、`runtime_history_file`、`runtime_history_max`
- 额度或限流失败时自动切到 OAuth 账号池
- 仍保留多账号轮换和后台刷新
### 4. 启动
@@ -154,7 +129,7 @@ clawgo gateway run
make dev
```
WebUI:
WebUI：
```text
http://<host>:<port>/?token=<gateway.token>
@@ -179,25 +154,22 @@ user -> main -> worker -> main -> user
4. `runtime store`
保存运行态、线程、消息、事件和审计数据
## 你能用它做什么
说明：
- 🤖 本地长期运行的个人 Agent
- 🧪 `pm -> coder -> tester` 这种多 Agent 协作链
- 🌐 本地主控 + 远端 node 分支的分布式执行
- 🔍 需要强观测、强审计、强恢复的 Agent 系统
- 🏭 想把 prompt、agent、工具权限、运行策略工程化管理的团队
- 📝 想把编码过程变成可追踪的 spec-driven delivery 流程
- `subagent_profile` 保留，用来创建和管理 subagent 定义
- `spawn` 保留，用来触发 subagent 执行
- 公开 task runtime、WebUI 配置写入、EKG、watchdog 已移除
## 配置结构
当前有两层配置视图：
- 落盘文件仍然使用下面的原始结构
- WebUI 与运行时接口优先使用标准化视图：
- 落盘文件继续使用原始结构
- 只读接口可暴露标准化视图：
- `core`
- `runtime`
原始配置的推荐结构：
推荐结构：
```json
{
@@ -230,87 +202,29 @@ user -> main -> worker -> main -> user
说明：
- `runtime_control` 已移除
- 当前使用：
- `agents.defaults.execution`
- `agents.defaults.summary_policy`
- `agents.router.policy`
- WebUI 配置保存优先走 normalized schema：
- `core.default_provider`
- `core.main_agent_id`
- `core.subagents`
- `runtime.router`
- `runtime.providers`
- 运行态面板优先消费统一 `runtime snapshot / runtime live`
- WebUI 配置编辑已禁用
- 运行时配置修改请直接改 `config.json`
- 启用中的本地 subagent 必须配置 `system_prompt_file`
- 远端分支需要：
- `transport: "node"`
- `node_id`
- `parent_agent_id`
完整示例见 [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json)。
## Node P2P
远端 node 的调度数据面现在支持：
- `websocket_tunnel`
- `webrtc`
默认仍然关闭，只有显式配置 `gateway.nodes.p2p.enabled=true` 才会启用。建议先用 `websocket_tunnel` 验证链路，再切到 `webrtc`。
`webrtc` 建议同时理解这两个字段：
- `stun_servers`
- 兼容旧式 STUN 列表
- `ice_servers`
- 推荐的新结构
- 可以配置 `stun:`、`turn:`、`turns:` URL
- `turn:` / `turns:` 必须同时提供 `username` 和 `credential`
示例：
```json
{
"gateway": {
"nodes": {
"p2p": {
"enabled": true,
"transport": "webrtc",
"stun_servers": ["stun:stun.l.google.com:19302"],
"ice_servers": [
{
"urls": ["turn:turn.example.com:3478"],
"username": "demo",
"credential": "secret"
}
]
}
}
}
}
```
说明：
- `webrtc` 建连失败时，调度层仍会回退到现有 relay / tunnel 路径
- Dashboard、`status`、`/api/nodes` 会显示当前 Node P2P 状态和会话摘要
- 两台公网机器的实网验证流程见 [docs/node-p2p-e2e.md](/Users/lpf/Desktop/project/clawgo/docs/node-p2p-e2e.md)
完整示例见 [config.example.json](/G:/gopro/clawgo/config.example.json)。
## MCP 服务支持
ClawGo 现在支持通过 `tools.mcp` 接入 `stdio`、`http`、`streamable_http`、`sse` 型 MCP server。
ClawGo 支持通过 `tools.mcp` 接入 `stdio`、`http`、`streamable_http`、`sse` 型 MCP server。
- 先在 `config.json -> tools.mcp.servers` 里声明 server
- 当前支持 `list_servers`、`list_tools`、`call_tool`、`list_resources`、`read_resource`、`list_prompts`、`get_prompt`
- 启动时会自动发现远端 MCP tools，并注册为本地工具，命名格式为 `mcp__<server>__<tool>`
- `permission=workspace`（默认）时，`working_dir` 会按 workspace 解析，并且必须留在 workspace 内
- `permission=full` 时，`working_dir` 可指向 `/` 下任意绝对路径，但实际访问权限仍然继承运行 `clawgo` 的 Linux 用户权限
示例配置可直接参考 [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json) 中的 `tools.mcp` 段落。
- 在 `config.json -> tools.mcp.servers` 中声明 server
- 启动时自动发现远端 MCP tools，并注册为本地工具
- 工具命名格式为 `mcp__<server>__<tool>`
- `permission=workspace` 时，`working_dir` 必须留在 workspace 内
- `permission=full` 时，`working_dir` 可以是任意绝对路径
## Prompt 文件约定
推荐把 agent prompt 独立为文件：
推荐把 agent prompt 独立成文件：
- `agents/main/AGENT.md`
- `agents/coder/AGENT.md`
@@ -327,8 +241,8 @@ ClawGo 现在支持通过 `tools.mcp` 接入 `stdio`、`http`、`streamable_http
规则：
- 路径必须是 workspace 内相对路径
- 仓库不会内置这些示例文件
- 用户或 agent workflow 需要自行创建实际的 `AGENT.md`
- 仓库不内置这些示例 prompt
- 用户或 agent workflow 需要自行创建实际文件
## 记忆与运行态
@@ -340,7 +254,8 @@ ClawGo 不是所有 agent 共用一份上下文。
- 使用独立 session key
- 写入自己的 memory namespace
- `runtime store`
- 持久化任务、事件、线程、消息
- 持久化 runs、events、threads、messages
- 内部仍可使用 task 建模，但不再暴露成公开控制面
这带来三件事：
@@ -348,10 +263,11 @@ ClawGo 不是所有 agent 共用一份上下文。
- 更好追踪
- 更清晰的执行边界
## 当前最适合的人群
## 适合谁
- 想用 Go 做 Agent Runtime 的开发者
- 想要可视化多 Agent 拓扑和内部流的团队
- 不满足于“聊天 + prompt”，而想要真正运行时能力的用户
- 想要可视化多 Agent 拓扑和内部协作流的团队
- 需要强观测、强审计、强恢复能力的系统
- 想把 agent 配置、prompt、工具权限工程化管理的团队
如果你想快速上手，先看 [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json)，再跑一次 `make dev`。
如果你想快速上手，先看 [config.example.json](/G:/gopro/clawgo/config.example.json)，再跑一次 `make dev`。