Rewrite English README for current architecture

2026-04-15 23:57:29 +08:00 · 2026-03-06 15:19:53 +08:00
parent 4e56d9a79f
commit ac5a1bfcb2
1 changed files with 237 additions and 107 deletions
--- a/README_EN.md
+++ b/README_EN.md
@@ -1,75 +1,150 @@
-# ClawGo 🚀
+# ClawGo

-A long-running AI Agent written in Go: lightweight, auditable, and multi-channel ready.
+ClawGo is a long-running AI agent system written in Go, designed around:
+
+- declarative main-agent and subagent configuration
+- persistent run / thread / mailbox state
+- node-registered remote agent branches
+- multi-channel access plus a unified WebUI
+- lightweight runtime behavior with strong auditability

 [中文](./README.md)

 ---

-## What It Does ✨
+## Current Architecture

- 🤖 Local chat mode: `clawgo agent`
- 🌐 Gateway service mode: `clawgo gateway`
- 💬 Multi-channel support: Telegram / Feishu / Discord / WhatsApp / QQ / DingTalk / MaixCam
- 🧰 Tool calling, skills, and sub-task collaboration
- 🧠 Autonomous tasks (queue, audit, conflict locks)
- 📊 WebUI for visibility (Chat / Logs / Config / Cron / Tasks / EKG)
+ClawGo is no longer a "single agent plus some tools" runtime. It is now an orchestrated agent tree:
+
+- `main agent`
+  - user-facing entrypoint
+  - owns routing, dispatch, merge, and coordination
+- `local subagents`
+  - for example `coder`, `tester`
+  - declared in `config.json` under `agents.subagents`
+- `node-backed branches`
+  - a registered node is treated as a remote branch under `main`
+  - branch ids look like `node.<node_id>.main`
+  - they can be targeted by the main agent as controlled remote execution branches
+
+The default collaboration pattern is:
+
+```text
+user -> main -> worker -> main -> user
+```

 ---

-## Concurrency Scheduling (New) ⚙️
+## Core Capabilities

- 🧩 A composite message is automatically split into sub-tasks
- 🔀 Within the same session: non-conflicting tasks run in parallel
- 🔒 Within the same session: conflicting tasks run serially (to avoid collisions)
- 🏷️ `resource_keys` are inferred automatically by default (no manual input needed)
+### 1. Agent Config and Routing
+
+- `agents.router`
+  - main-agent routing configuration
+  - supports `rules_first`, explicit `@agent_id`, and keyword routing
+- `agents.subagents`
+  - declares agent identity, role, runtime policy, and tool allowlists
+- `system_prompt_file`
+  - subagents now prefer `agents/<agent_id>/AGENT.md`
+  - they are no longer expected to rely on a one-line inline prompt
+
+### 2. Persistent Subagent Runtime
+
+Runtime state is persisted under:
+
+- `workspace/agents/runtime/subagent_runs.jsonl`
+- `workspace/agents/runtime/subagent_events.jsonl`
+- `workspace/agents/runtime/threads.jsonl`
+- `workspace/agents/runtime/agent_messages.jsonl`
+
+This enables:
+
+- run recovery
+- thread tracing
+- mailbox / inbox inspection
+- dispatch / wait / merge workflows
+
+### 3. Node Branches
+
+A registered node is not treated as just a device entry anymore. It is modeled as a remote main-agent branch:
+
+- nodes appear inside the unified agent topology
+- remote registries are shown as read-only mirrors
+- a subagent with `transport=node` is dispatched through `agent_task` to the target node
+
+### 4. WebUI
+
+The WebUI is now organized as a unified agent operations console, including:
+
+- Dashboard
+- Chat
+- Config
+- Logs
+- Cron
+- Skills
+- Memory
+- Task Audit
+- EKG
+- Agents
+  - unified agent topology
+  - local and remote agent trees
+  - subagent runtime
+  - registry
+  - prompt file editor
+  - dispatch / thread / inbox controls
+
+### 5. Memory Strategy
+
+Memory is not fully shared and not fully isolated either. It uses a dual-write model:
+
+- `main`
+  - keeps workspace-level memory and collaboration summaries
+- `subagent`
+  - writes to its own namespaced memory
+  - paths look like `workspace/agents/<memory_ns>/...`
+- for automatic subagent summaries:
+  - the subagent keeps its own detailed entry
+  - the main memory also receives a short collaboration summary
+
+Example summary format:
+
+```md
+## 15:04 Code Agent | Fix login API and add tests
+
+- Did: Fixed the login API, added regression coverage, and verified the result.
+```

 ---

-## Memory + EKG Enhancements (New) 🧠
+## Quick Start

- 📚 Before each sub-task runs, related memory is fetched via `memory_search`
- 🚨 EKG + task-audit are used to detect repeated error-signature risks
- ⏱️ High-risk tasks include retry-backoff hints to reduce repeated failures
-
---
-
-## Telegram Streaming Rendering (New) 💬
-
- 🧷 Stream flushes happen at syntax-safe boundaries to reduce formatting jitter
- ✅ A final convergence render is applied when streaming ends for stable layout
-
---
-
-## 3-Minute Quick Start ⚡
-
-### 1) Install
+### 1. Install

 ```bash
 curl -fsSL https://raw.githubusercontent.com/YspCoder/clawgo/main/install.sh | bash
 ```

-### 2) Initialize
+### 2. Initialize

 ```bash
 clawgo onboard
 ```

-### 3) Configure provider
+### 3. Configure a provider

 ```bash
 clawgo provider
 ```

-### 4) Check status
+### 4. Check status

 ```bash
 clawgo status
 ```

-### 5) Start using it
+### 5. Start

-Local mode:
+Local interactive mode:

 ```bash
 clawgo agent
@@ -79,18 +154,20 @@ clawgo agent -m "Hello"
 Gateway mode:

 ```bash
-# Register + enable systemd service
 clawgo gateway
 clawgo gateway start
 clawgo gateway status
+```

-# Or run in foreground
+Foreground mode:
+
+```bash
 clawgo gateway run
 ```

 ---

-## WebUI 🖥️
+## WebUI

 Open:

@@ -98,23 +175,102 @@ Open:
 http://<host>:<port>/webui?token=<gateway.token>
 ```

-Main pages:
+Recommended pages:

- Dashboard
- Chat
- Logs
- Skills
- Config
- Cron
- Nodes
- Memory
- Task Audit
- Tasks
- EKG
+- `Agents`
+  - view the entire agent tree
+  - inspect node branches
+  - inspect active runtime tasks
+  - edit local subagent configuration
+- `Config`
+  - edit runtime configuration
+- `Logs`
+  - inspect real-time logs
+- `Task Audit`
+  - inspect task decomposition, scheduling, and execution flow
+- `EKG`
+  - inspect error signatures, source distribution, and workload hotspots

 ---

-## Common Commands 📌
+## Config Layout
+
+The current recommended structure is centered around:
+
+```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": {}
+    }
+  }
+}
+```
+
+Important notes:
+
+- `runtime_control` has been removed
+- the current structure uses:
+  - `agents.defaults.execution`
+  - `agents.defaults.summary_policy`
+  - `agents.router.policy`
+- enabled local subagents must define `system_prompt_file`
+- node-backed agents use:
+  - `transport: "node"`
+  - `node_id`
+  - `parent_agent_id`
+
+See the full example:
+
+- [config.example.json](/Users/lpf/Desktop/project/clawgo/config.example.json)
+
+---
+
+## Subagent Prompt Convention
+
+Each agent should ideally have its own prompt file:
+
+- `agents/main/AGENT.md`
+- `agents/coder/AGENT.md`
+- `agents/tester/AGENT.md`
+
+Example:
+
+```json
+{
+  "system_prompt_file": "agents/coder/AGENT.md"
+}
+```
+
+Rules:
+
+- the path must stay inside the workspace
+- the path should be relative
+- when creating a subagent, update both config and the matching `AGENT.md`
+- when a subagent's responsibility changes materially, update its `AGENT.md` too
+
+---
+
+## Common Commands

 ```text
 clawgo onboard
@@ -123,7 +279,6 @@ clawgo status
 clawgo agent [-m "..."]
 clawgo gateway [run|start|stop|restart|status]
 clawgo config set|get|check|reload
-clawgo channel test ...
 clawgo cron ...
 clawgo skills ...
 clawgo uninstall [--purge] [--remove-bin]
@@ -131,74 +286,49 @@ clawgo uninstall [--purge] [--remove-bin]

 ---

-## Build & Release 🛠️
+## Build

-Build all default targets:
+Local build:
+
+```bash
+make build
+```
+
+Build all targets:

 ```bash
 make build-all
 ```

-Linux slim build:
-
-```bash
-make build-linux-slim
-```
-
-Custom target matrix:
-
-```bash
-make build-all BUILD_TARGETS="linux/amd64 linux/arm64 darwin/arm64 windows/amd64"
-```
-
-Package + checksums:
+Package outputs:

 ```bash
 make package-all
 ```

-Outputs:
+---

- `build/*.tar.gz` (Linux/macOS)
- `build/*.zip` (Windows)
- `build/checksums.txt`
+## Design Direction
+
+ClawGo currently leans toward these design choices:
+
+- main-agent mediation first
+- persisted runtime state first
+- declarative config first
+- unified operations UI before more aggressive automation
+- nodes modeled as controlled remote agent branches, not fully autonomous peers
+
+In practice, that means this project is closer to:
+
+- a long-running personal AI agent runtime
+- with multi-agent orchestration
+- with node expansion
+- with operational visibility and auditability
+
+rather than a simple chat bot wrapper.

 ---

-## GitHub Release Automation 📦
-
-Built-in workflow: `.github/workflows/release.yml`
-
-Triggers:
-
- Tag push (e.g. `v0.0.2`)
- Manual `workflow_dispatch`
-
-Example:
-
-```bash
-git tag v0.0.2
-git push origin v0.0.2
-```
-
---
-
-## Config Notes ⚙️
-
- Strict JSON validation (unknown fields fail fast)
- Supports hot reload: `clawgo config reload`
- Auto rollback if hot reload fails
-
---
-
-## Production Tips ✅
-
- Enable channel dedupe windows
- Monitor Task Audit and EKG regularly
- Use gateway mode for long-running workloads
-
---
-
-## License 📄
+## License

 See `LICENSE` in this repository.