From fe0437b9cfa0c31b38301183881fc008161c4ad2 Mon Sep 17 00:00:00 2001
From: lpf <lipengfei886@qq.com>
Date: Sat, 7 Mar 2026 12:42:05 +0800
Subject: [PATCH] fix readme

---
 README.md    | 203 +++++++++++++++++++++++++++------------------------
 README_EN.md | 194 +++++++++++++++++++++++++-----------------------
 2 files changed, 211 insertions(+), 186 deletions(-)

diff --git a/README.md b/README.md
index c66e19c..4a7f971 100644
--- a/README.md
+++ b/README.md
@@ -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`。
diff --git a/README_EN.md b/README_EN.md
index f43c648..52fd77c 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -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`.