diff --git a/README_EN.md b/README_EN.md index 2194404..054d371 100644 --- 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..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.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//...` +- 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://:/webui?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.