docs: rewrite README/README_EN for multi-platform release workflow and current architecture

2026-04-19 05:27:29 +08:00 · 2026-03-01 13:42:35 +00:00
parent 5ea5b97068
commit 910d7bba39
2 changed files with 289 additions and 706 deletions
--- a/README.md
+++ b/README.md
@@ -1,444 +1,226 @@
-# ClawGo: 高性能 Go 语言 AI 助手 (Linux Server 专用)
+# ClawGo
+
+高性能、可长期运行的 Go 原生 AI Agent（支持多平台构建与多通道接入）。

 [English](./README_EN.md)

-**ClawGo** 是一个面向 Linux 服务器的 Go 原生 AI Agent。它提供单二进制部署、多通道接入与可热更新配置，适合长期在线自动化任务。
+---

-## 🚀 功能总览
+## 一句话介绍

- **双运行模式**：支持本地交互模式（`agent`）与服务化网关模式（`gateway`）。
- **多通道接入**：支持 Telegram、Discord、Feishu、WhatsApp、QQ、DingTalk、MaixCam。
- **自主协作能力**：支持自然语言驱动的自主执行、自动学习与启动自检。
- **多智能体编排**：支持 Pipeline 协议（`role + goal + depends_on + shared_state`）。
- **记忆与上下文治理**：支持分层记忆、`memory_search` 与自动上下文压缩。
- **可靠性增强**：支持代理内模型切换与跨代理切换（`proxy_fallbacks`），覆盖配额、路由、网关瞬时错误等场景。
- **稳定性保障**：Sentinel 巡检与自动修复能力。
- **技能扩展**：支持内置技能与 GitHub 技能安装，支持原子脚本执行。
+**ClawGo = 单二进制网关 + 多通道消息 + 工具调用 + 自治执行 + 可审计记忆。**

-## 🧠 架构级优化（Go 特性）
+适合：
+- 私有化 AI 助手
+- 持续巡检/自动任务
+- 多通道机器人（Telegram/Feishu/Discord 等）
+- 需要可控、可追踪、可回滚的 Agent 系统

-近期已完成一轮架构增强，重点利用 Go 并发与类型系统能力：
+---

-1. **Actor 化关键路径（process）**
-   - process 元数据持久化改为异步队列（`persistQ`）串行落盘。
-   - channel 启停编排使用 `errgroup.WithContext` 并发+统一取消。
-2. **Typed Events 事件总线**
-   - 新增 `pkg/events/typed_bus.go` 泛型事件总线。
-   - process 生命周期事件（start/exit/kill）可发布订阅。
-3. **日志批量刷盘**
-   - process 日志由 `logWriter` 批量 flush（时间片 + 大小阈值），减少高频 I/O。
-   - outbound 分发增加 `rate.Limiter`（令牌桶）平滑突发流量。
-4. **Context 分层取消传播**
-   - 后台进程改为 `exec.CommandContext`，通过父 `ctx` 统一取消。
-5. **原子配置快照**
-   - 新增 `pkg/runtimecfg/snapshot.go`，网关启动与热重载时原子替换配置快照。
+## 核心能力

-这些优化提升了高并发场景下的稳定性、可观测性与可维护性。
+- **双模式运行**
+  - `clawgo agent`：本地交互模式
+  - `clawgo gateway`：服务化网关模式（推荐长期运行）

-### 多节点 / 设备控制（Phase-1）
+- **多通道支持**
+  - Telegram / Feishu / Discord / WhatsApp / QQ / DingTalk / MaixCam

-已新增 `nodes` 工具控制平面（PoC）：
+- **工具与技能体系**
+  - 内置工具调用、技能安装与执行
+  - 支持任务编排与子任务协同

- `action=status|describe`：查看已配对节点状态与能力矩阵
- `action=run|invoke|camera_snap|screen_record|location_get`：已接入路由框架
- `mode=auto|p2p|relay`：默认 `auto`（优先 p2p，失败回退 relay）
- relay 已支持 HTTP 节点桥接：按 action 路由到 `/run` `/camera/snap` `/screen/record` `/location/get` `/canvas/*`（未知 action 回退 `/invoke`）
- 主节点网关支持节点注册：`POST http://<gateway_host>:<gateway_port>/nodes/register`
- 支持节点续租：`POST /nodes/heartbeat`（配合 TTL 自动离线）
- 可在 `gateway.token` 配置网关注册令牌；子节点注册/续租需带 `Authorization: Bearer <token>`
- 可在 `NodeInfo` 中配置 `token`，relay 会自动附加 `Authorization: Bearer <token>`
- `nodes` 工具支持设备快捷参数：`facing`、`duration_ms`、`command`
- 设备动作响应统一：`ok/code/error/payload`（code 示例：`ok` `unsupported_action` `transport_error`）
- 设备 `payload` 规范字段：`media_type` `storage` `url|path|image` `meta`
- 支持 `agent_task`：主节点可向具备 `model` 能力的子节点下发任务，子节点返回执行结果
- 节点分发审计写入：`memory/nodes-dispatch-audit.jsonl`
- `/status` 展示节点分发统计（total/ok/fail/avg_ms/top_action）
+- **自治与任务治理**
+  - 会话级自治（idle 预算、暂停/恢复）
+  - Task Queue / Task Audit 分层治理
+  - 自治任务冲突锁（resource_keys）

-实现位置：
- `pkg/nodes/types.go`
- `pkg/nodes/manager.go`
- `pkg/tools/nodes_tool.go`
+- **记忆与上下文治理**
+  - `memory_search` / 分层记忆
+  - 自动上下文压缩
+  - 启动自检与任务续跑

-### 并行任务冲突控制（Autonomy）
+- **可靠性增强**
+  - Provider fallback（含 errsig-aware 排序）
+  - 入站/出站去重（防重复收发）
+  - 审计可观测（provider/model/source/channel）

-支持基于 `resource_keys` 的锁调度。任务可在内容中显式声明资源键，提升并行判冲突精度：
+---

- 示例：`[keys: repo:clawgo, file:pkg/agent/loop.go, branch:main] 修复对话流程`
- 未显式声明时，系统会从任务文本自动推断资源键。
- 冲突任务进入 `resource_lock` 等待，默认 30 秒后重试抢锁，并带公平加权（等待越久优先级越高）。
- 自治完成/阻塞通知不再使用 `autonomy.notify_channel` / `autonomy.notify_chat_id`；默认自动从已启用通道的 `allow_from` 推导目标（优先 Telegram）。
+## EKG（Execution Knowledge Graph）

-### EKG（Execution Knowledge Graph）与审计治理
+ClawGo 内置轻量 EKG（无需外部图数据库），用于降低重复错误与无效重试：

-ClawGo 内置轻量执行知识图谱（JSONL 事件流 + 快照缓存），用于降低重复错误与无效重试：
-
- 事件存储：`memory/ekg-events.jsonl`
- 快照缓存：`memory/ekg-snapshot.json`（降低冷启动扫描开销）
+- 事件流：`memory/ekg-events.jsonl`
+- 快照：`memory/ekg-snapshot.json`
 - 错误签名归一化（路径/数字/hex 去噪）
- 自治重复错误抑制：`agents.defaults.autonomy.ekg_consecutive_error_threshold`
- Provider fallback 排序：按历史成功/失败排序，并支持 errsig-aware 加权
- EKG 与 Memory 联动：重复错误升级时写入结构化 incident（`[EKG_INCIDENT]`），后续可提前触发抑制
- Incident 节流：同 errsig 默认 6 小时内不重复写入 memory
+- 重复错误抑制（可配置阈值）
+- Provider fallback 历史打分（含错误签名维度）
+- 与 Memory 联动（`[EKG_INCIDENT]` 结构化沉淀，支持提前拦截）
+- WebUI 支持按 `6h/24h/7d` 时间窗口查看

-### Task Audit / Queue 降噪策略
+---

- 默认过滤 heartbeat 记录（API 可通过 `include_heartbeat=1` 查看完整数据）
- 自动任务使用稳定 task_id 合并追加，避免同任务产生大量碎片记录
- 审计记录补充 provider/model 字段，便于快速定位问题链路
- WebUI EKG 统计按 source/channel 分层（heartbeat 与 workload 分离），支持时间窗口 `6h/24h/7d`
+## 快速开始

-> 时间窗口必要性：
-> 全量历史会被旧数据与心跳噪音稀释，导致当前策略不敏感；建议默认看 24h，并按需切到 6h/7d。
-
-## 🏁 快速开始
-
-1. 初始化配置与工作区
+### 1) 初始化

 ```bash
 clawgo onboard
 ```

-2. 配置上游代理（必需）
+### 2) 配置上游模型/代理

 ```bash
 clawgo login
 ```

-3. 检查当前状态
+### 3) 查看状态

 ```bash
 clawgo status
 ```

-4. 交互式使用（本地）
+### 4) 本地模式

 ```bash
 clawgo agent
-# 或单轮消息
 clawgo agent -m "Hello"
 ```

-5. 启动网关服务（用于 Telegram/Discord 等）
+### 5) 网关模式

 ```bash
-# 注册服务（systemd）
+# 注册并启用 systemd 服务
 clawgo gateway
-
-# 服务管理
 clawgo gateway start
-clawgo gateway restart
-clawgo gateway stop
 clawgo gateway status

 # 前台运行
 clawgo gateway run
-
-# 自治开关（运行态）
-clawgo gateway autonomy status
-clawgo gateway autonomy on
-clawgo gateway autonomy off
 ```

-## 🖥️ WebUI（控制台）
+---

-ClawGo 提供内置 WebUI（React + Vite 构建产物由网关直接托管）：
+## WebUI

- 访问入口：`http://<host>:<port>/webui?token=<gateway.token>`
- 移动端适配：侧边抽屉导航、紧凑头部、日志页可读模式
- 页面：Dashboard / Chat / Logs / Skills / Config / Cron / Nodes / Memory
-
-常用 WebUI API（均需 token）：
-
- 配置：`GET/POST /webui/api/config`
- 聊天：`POST /webui/api/chat`、`POST /webui/api/chat/stream`
- 日志：`GET /webui/api/logs/recent`、`GET /webui/api/logs/stream`
- 定时任务：`GET /webui/api/cron`、`POST /webui/api/cron`
- 节点：`GET /webui/api/nodes`、`POST /webui/api/nodes`
- 技能：`GET/POST/DELETE /webui/api/skills`
- 会话：`GET /webui/api/sessions`
- 记忆文件：`GET/POST/DELETE /webui/api/memory`
-
-## 📌 命令总览
+访问：

 ```text
-clawgo onboard                     初始化配置和工作区
-clawgo login                       配置 CLIProxyAPI 上游
-clawgo status                      查看配置、工作区、模型和日志状态
-clawgo agent [-m "..."]           本地交互模式
-clawgo gateway [...]               注册/运行/管理网关服务
-clawgo config set|get|check|reload 配置读写、校验与热更新
-clawgo channel test ...            通道连通性测试
-clawgo cron ...                    定时任务管理
-clawgo skills ...                  技能安装/查看/卸载
-clawgo uninstall [--purge] [--remove-bin]
+http://<host>:<port>/webui?token=<gateway.token>
 ```

-Make 多平台构建：
+主要页面：
+- Dashboard
+- Chat
+- Logs
+- Skills
+- Config
+- Cron
+- Nodes
+- Memory
+- Task Audit
+- Tasks
+- EKG
+
+---
+
+## 多平台构建（Make）
+
+### 构建所有默认平台

 ```bash
 make build-all
-# 自定义目标矩阵（示例）
+```
+
+默认矩阵：
+- linux/amd64
+- linux/arm64
+- linux/riscv64
+- darwin/amd64
+- darwin/arm64
+- windows/amd64
+- windows/arm64
+
+### 自定义平台矩阵
+
+```bash
 make build-all BUILD_TARGETS="linux/amd64 linux/arm64 darwin/arm64 windows/amd64"
-# 产物打包 + 校验和
+```
+
+### 打包与校验
+
+```bash
 make package-all
 ```

-全局参数：
+输出：
+- `build/*.tar.gz`（Linux/macOS）
+- `build/*.zip`（Windows）
+- `build/checksums.txt`
+
+---
+
+## GitHub Release 自动发布
+
+已内置 `.github/workflows/release.yml`：
+
+触发方式：
+- 推送 tag：`v*`（如 `v0.0.1`）
+- 手动触发（workflow_dispatch）
+
+自动完成：
+- 多平台编译
+- 产物打包
+- checksums 生成
+- WebUI dist 打包
+- 发布到 GitHub Releases
+
+示例：

 ```bash
-clawgo --config /path/to/config.json <command>
-clawgo --debug <command>
+git tag v0.0.2
+git push origin v0.0.2
 ```

-## ⚙️ 配置管理与热更新
+---

-支持命令行直接修改配置，并向运行中的网关发送热更新信号：
-
-```bash
-clawgo config set channels.telegram.enable true
-clawgo config get channels.telegram.enabled
-clawgo config check
-clawgo config reload
-```
-
-说明：
- `enable` 会自动映射到 `enabled`。
- `config set` 使用原子写入。
- 网关运行时若热更新失败，会自动回滚备份，避免损坏配置。
- `--config` 指定的自定义配置路径会被 `config` 命令与通道内 `/config` 指令一致使用。
- 配置加载使用严格 JSON 解析：未知字段与多余 JSON 内容会直接报错，避免拼写错误被静默忽略。
-
-## 🌐 通道与消息控制
-
-通道中支持以下斜杠命令：
+## 常用命令

 ```text
-/help
-/stop
-/status
-/status run [run_id|latest]
-/status wait <run_id|latest> [timeout_seconds]
-/config get <path>
-/config set <path> <value>
-/reload
-/pipeline list
-/pipeline status <pipeline_id>
-/pipeline ready <pipeline_id>
+clawgo onboard
+clawgo login
+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]
 ```

-自主与学习控制默认使用自然语言，不再依赖斜杠命令。例如：
- `开始自主模式，每 30 分钟巡检一次`
- `停止自动学习`
- `看看最新 run 的状态`
- `等待 run-1739950000000000000-8 完成后告诉我结果`
+---

-调度语义（按 `session_key`）：
- 同会话严格 FIFO 串行处理。
- `/stop` 会中断当前回复并继续队列后续消息。
- 不同会话并发执行，互不阻塞。
+## 配置与热更新

-通道连通测试：
+- 支持 `clawgo config set/get/check/reload`
+- 严格 JSON 解析（未知字段会报错）
+- 配置热更新失败自动回滚备份

-```bash
-clawgo channel test --channel telegram --to <chat_id> -m "ping"
-```
+---

-## 🧠 记忆、自主与上下文压缩
+## 稳定性与审计建议

- 启动会读取 `AGENTS.md`、`SOUL.md`、`USER.md` 作为行为约束与语义上下文。
- 网关启动后会执行一次自检任务，结合历史会话与 `HEARTBEAT.md` 判断是否继续未完成任务。
- 上下文压缩同时按消息数量阈值和上下文体积阈值触发，控制 token 成本与长会话稳定性。
- 上下文压缩模式支持 `summary`、`responses_compact`、`hybrid`；`responses_compact` 需要代理配置 `protocol=responses` 且 `supports_responses_compact=true`。
- 分层记忆支持 `profile / project / procedures / recent notes`。
+生产建议开启：
+- 通道去重窗口配置
+- task-audit heartbeat 默认过滤
+- EKG 时间窗口观察（默认 24h）
+- 定期查看 EKG Top errsig 与 provider 分数

-心跳与上下文压缩配置示例：
+---

-```json
-"agents": {
-  "defaults": {
-    "heartbeat": {
-      "enabled": true,
-      "every_sec": 1800,
-      "ack_max_chars": 64,
-      "prompt_template": "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK."
-    },
-    "texts": {
-      "no_response_fallback": "I've completed processing but have no response to give.",
-      "think_only_fallback": "Thinking process completed.",
-      "memory_recall_keywords": ["remember", "记得", "上次", "之前", "偏好", "preference", "todo", "待办", "决定", "decision"],
-      "lang_usage": "Usage: /lang <code>",
-      "lang_invalid": "Invalid language code.",
-      "lang_updated_template": "Language preference updated to %s",
-      "subagents_none": "No subagents.",
-      "sessions_none": "No sessions.",
-      "unsupported_action": "unsupported action",
-      "system_rewrite_template": "Rewrite the following internal system update in concise user-facing language:\n\n%s",
-      "runtime_compaction_note": "[runtime-compaction] removed %d old messages, kept %d recent messages",
-      "startup_compaction_note": "[startup-compaction] removed %d old messages, kept %d recent messages"
-    },
-    "context_compaction": {
-      "enabled": true,
-      "mode": "summary",
-      "trigger_messages": 60,
-      "keep_recent_messages": 20,
-      "max_summary_chars": 6000,
-      "max_transcript_chars": 20000
-    }
-  }
-}
-```
+## License

-运行控制配置示例（自主循环守卫 / 运行态保留）：
-
-```json
-"agents": {
-  "defaults": {
-    "runtime_control": {
-      "intent_max_input_chars": 1200,
-      "autonomy_tick_interval_sec": 20,
-      "autonomy_min_run_interval_sec": 20,
-      "autonomy_idle_threshold_sec": 20,
-      "autonomy_max_rounds_without_user": 120,
-      "autonomy_max_pending_duration_sec": 180,
-      "autonomy_max_consecutive_stalls": 3,
-      "autolearn_max_rounds_without_user": 200,
-      "run_state_ttl_seconds": 1800,
-      "run_state_max": 500,
-      "tool_parallel_safe_names": ["read_file", "list_files", "find_files", "grep_files", "memory_search", "web_search", "repo_map", "system_info"],
-      "tool_max_parallel_calls": 2
-    }
-  }
-}
-```
-
-## 🤖 多智能体编排 (Pipeline)
-
-内置标准化编排工具：
- `pipeline_create`
- `pipeline_status`
- `pipeline_state_set`
- `pipeline_dispatch`
- `spawn`（支持 `pipeline_id/task_id/role`）
-
-适用于拆解复杂任务、跨角色协作和共享状态推进。
-
-## 🛡️ 稳定性
-
- **Proxy/Model fallback**：先在当前代理中按 `models` 顺序切换，全部失败后再按 `proxy_fallbacks` 切换代理。
- **HTTP 兼容处理**：可识别非 JSON 错页并给出响应预览；兼容从 `<function_call>` 文本块提取工具调用。
- **Sentinel**：周期巡检配置/内存/日志目录，支持自动修复与告警转发。
-
-Sentinel 配置示例：
-
-```json
-"sentinel": {
-  "enabled": true,
-  "interval_sec": 60,
-  "auto_heal": true,
-  "notify_channel": "",
-  "notify_chat_id": ""
-}
-```
-
-## ⏱️ 定时任务 (Cron)
-
-```bash
-clawgo cron list
-clawgo cron add -n "daily-check" -m "检查待办" -c "0 9 * * *"
-clawgo cron add -n "heartbeat" -m "汇报状态" -e 300
-clawgo cron enable <job_id>
-clawgo cron disable <job_id>
-clawgo cron remove <job_id>
-```
-
-`cron add` 支持：
- `-n, --name` 任务名
- `-m, --message` 发给 agent 的消息
- `-e, --every` 每 N 秒执行
- `-c, --cron` cron 表达式
- `-d, --deliver --channel <name> --to <id>` 投递到消息通道
-
-## 🧩 技能系统
-
-技能管理命令：
-
-```bash
-clawgo skills list
-clawgo skills search
-clawgo skills show <name>
-clawgo skills install <github-repo>
-clawgo skills remove <name>
-clawgo skills install-builtin
-clawgo skills list-builtin
-```
-
-说明：
- 支持从 GitHub 仓库安装技能（例如 `owner/repo/skill`）。
- 支持安装内置技能到工作区。
- 支持 `skill_exec` 原子执行 `skills/<name>/scripts/*`。
-
-## 🗂️ 工作区与文档同步
-
-默认工作区通常为 `~/.clawgo/workspace`，关键目录：
-
-```text
-workspace/
-  memory/
-    MEMORY.md
-    HEARTBEAT.md
-  skills/
-  AGENTS.md
-  SOUL.md
-  USER.md
-```
-
-`clawgo onboard` 与 `make install` 会同步 `AGENTS.md`、`SOUL.md`、`USER.md`：
- 文件不存在则创建。
- 文件存在则仅更新 `CLAWGO MANAGED BLOCK` 区块，保留用户自定义内容。
-
-## 🧾 日志
-
-默认启用文件日志，支持轮转和保留：
-
-```json
-"logging": {
-  "enabled": true,
-  "dir": "~/.clawgo/logs",
-  "filename": "clawgo.log",
-  "max_size_mb": 20,
-  "retention_days": 3
-}
-```
-
-推荐统一检索的结构化字段：
-`channel`、`chat_id`、`sender_id`、`preview`、`error`、`message_content_length`、`assistant_content_length`、`output_content_length`、`transcript_length`。
-
-## 🛠️ 安装与构建（Linux）
-
-```bash
-cd clawgo
-make build
-make install
-```
-
-可选构建参数：
-
-```bash
-# 默认 1：剥离符号，减小体积
-make build STRIP_SYMBOLS=1
-
-# 保留调试符号
-make build STRIP_SYMBOLS=0
-```
-
-## 🧹 卸载
-
-```bash
-clawgo uninstall
-clawgo uninstall --purge
-clawgo uninstall --remove-bin
-```
-
-## 📜 许可证
-
-MIT License.
+请参考仓库中的 License 文件。
--- a/README_EN.md
+++ b/README_EN.md
@@ -1,425 +1,226 @@
-# ClawGo: High-Performance AI Agent (Linux Server Only)
+# ClawGo
+
+A high-performance, long-running Go-native AI Agent with multi-platform builds and multi-channel messaging.

 [中文](./README.md)

-**ClawGo** is a Go-native AI agent for Linux servers. It provides single-binary deployment, multi-channel integration, and hot-reloadable config for long-running autonomous workflows.
+---

-## 🚀 Feature Overview
+## What is ClawGo?

- **Dual runtime modes**: local interactive mode (`agent`) and service-oriented gateway mode (`gateway`).
- **Multi-channel integration**: Telegram, Discord, Feishu, WhatsApp, QQ, DingTalk, MaixCam.
- **Autonomous collaboration**: natural-language autonomy, auto-learning, and startup self-check.
- **Multi-agent orchestration**: built-in Pipeline protocol (`role + goal + depends_on + shared_state`).
- **Memory and context governance**: layered memory, `memory_search`, and automatic context compaction.
- **Reliability enhancements**: in-proxy model switching and cross-proxy fallback (`proxy_fallbacks`) for quota, routing, and transient gateway failures.
- **Stability controls**: Sentinel inspection and auto-heal support.
- **Skill extensibility**: built-in skills plus GitHub skill installation and atomic script execution.
+**ClawGo = single-binary gateway + channel integrations + tool calling + autonomy + auditable memory.**

-## 🧠 Architecture-Level Optimizations (Go)
+Best for:
+- Self-hosted AI assistants
+- Continuous automation / inspections
+- Multi-channel bots (Telegram/Feishu/Discord/...)
+- Agent systems requiring control, traceability, and rollback safety

-A recent architecture pass leveraged core Go strengths:
+---

-1. **Actor-style process path**
-   - Process metadata persistence is serialized via async queue (`persistQ`).
-   - Channel start/stop orchestration uses `errgroup.WithContext` for concurrent + unified cancellation.
-2. **Typed Events bus**
-   - Added generic typed pub/sub bus (`pkg/events/typed_bus.go`).
-   - Process lifecycle events (start/exit/kill) are now publishable.
-3. **Batched log flushing**
-   - Process logs are flushed by `logWriter` with time/size thresholds to reduce I/O churn.
-   - Outbound dispatch adds a token-bucket `rate.Limiter` for burst smoothing.
-4. **Context hierarchy + cancellation propagation**
-   - Background exec now uses `exec.CommandContext` with parent `ctx` propagation.
-5. **Atomic runtime config snapshot**
-   - Added `pkg/runtimecfg/snapshot.go`; gateway startup/reload atomically swaps config snapshot.
+## Core Capabilities

-These changes improve stability, observability, and maintainability under concurrency.
+- **Dual runtime modes**
+  - `clawgo agent`: local interactive mode
+  - `clawgo gateway`: service mode for long-running workloads

-### Multi-node / device control (Phase-1)
+- **Multi-channel support**
+  - Telegram / Feishu / Discord / WhatsApp / QQ / DingTalk / MaixCam

-A `nodes` tool control-plane PoC is now available:
+- **Tools & skills**
+  - Built-in tool-calling and skill execution
+  - Task orchestration support

- `action=status|describe`: inspect paired node status and capability matrix
- `action=run|invoke|camera_snap|screen_record|location_get`: routing framework is in place
- `mode=auto|p2p|relay`: default `auto` (prefer p2p, fallback to relay)
- relay now supports HTTP node bridging with action-specific routes: `/run`, `/camera/snap`, `/screen/record`, `/location/get`, `/canvas/*` (unknown action falls back to `/invoke`)
- gateway supports node registration: `POST http://<gateway_host>:<gateway_port>/nodes/register`
- supports node lease renew: `POST /nodes/heartbeat` (TTL-based offline marking)
- configure `gateway.token` as registration token; child nodes must send `Authorization: Bearer <token>` for register/heartbeat
- `NodeInfo.token` is supported; relay automatically sets `Authorization: Bearer <token>`
- `nodes` tool supports device shortcuts: `facing`, `duration_ms`, `command`
- unified device response envelope: `ok/code/error/payload` (code examples: `ok`, `unsupported_action`, `transport_error`)
- device `payload` normalized fields: `media_type` `storage` `url|path|image` `meta`
- supports `agent_task`: parent node can dispatch tasks to child nodes with `model` capability and receive execution results
- node dispatch audit is persisted to `memory/nodes-dispatch-audit.jsonl`
- `/status` shows node dispatch stats (total/ok/fail/avg_ms/top_action)
+- **Autonomy & task governance**
+  - Session-level autonomy (idle budget, pause/resume)
+  - Task Queue + Task Audit governance
+  - Resource-key locking for conflict control

-Implementation:
- `pkg/nodes/types.go`
- `pkg/nodes/manager.go`
- `pkg/tools/nodes_tool.go`
+- **Memory & context governance**
+  - `memory_search` and layered memory
+  - Automatic context compaction
+  - Startup self-check and task continuation

-### Parallel task conflict control (Autonomy)
+- **Reliability hardening**
+  - Provider fallback (errsig-aware ranking)
+  - Inbound/outbound dedupe protection
+  - Better observability (provider/model/source/channel)

-Autonomy supports lock scheduling via `resource_keys` for deterministic conflict control:
+---

- Example: `[keys: repo:clawgo, file:pkg/agent/loop.go, branch:main] fix dialog flow`
- Without explicit keys, the engine derives keys from task text heuristically.
- Conflicting tasks enter `resource_lock`, retry lock acquisition after 30s, and use fairness weighting (longer wait => higher scheduling priority).
- Autonomy completion/blocked notifications no longer rely on `autonomy.notify_channel` / `autonomy.notify_chat_id`; target is derived from enabled channel `allow_from` (Telegram first).
+## EKG (Execution Knowledge Graph)

-### EKG (Execution Knowledge Graph) and audit governance
+ClawGo includes a lightweight EKG (no external graph DB required):

-ClawGo includes a lightweight execution knowledge graph (JSONL event stream + snapshot cache) to reduce repeated failures and ineffective retries:
-
- Event store: `memory/ekg-events.jsonl`
- Snapshot cache: `memory/ekg-snapshot.json` (reduces cold-start scan cost)
+- Event log: `memory/ekg-events.jsonl`
+- Snapshot cache: `memory/ekg-snapshot.json`
 - Normalized error signatures (path/number/hex denoise)
- Repeated-error suppression for autonomy: `agents.defaults.autonomy.ekg_consecutive_error_threshold`
- Provider fallback ranking by historical outcomes (including errsig-aware weighting)
- EKG-memory integration: repeated-error escalation writes structured `[EKG_INCIDENT]` entries to memory and enables earlier suppression on known signatures
- Incident write throttling: same errsig is not re-written within a default 6-hour cooldown
+- Repeated-error suppression (configurable threshold)
+- Historical provider scoring (including error-signature dimension)
+- Memory linkage (`[EKG_INCIDENT]` structured notes for earlier suppression)
+- WebUI time windows: `6h / 24h / 7d`

-### Task Audit / Queue noise-control strategy
+---

- Heartbeat records are filtered by default (use `include_heartbeat=1` to view full data)
- Recurring autonomy runs are merged via stable task IDs (append instead of fragment explosion)
- Task-audit rows include provider/model for faster root-cause tracing
- WebUI EKG stats are stratified by source/channel (heartbeat vs workload) and support `6h/24h/7d` windows
+## Quick Start

-> Why time windows matter:
-> Full-history metrics are diluted by stale data and heartbeat noise. A recent window (default 24h; optional 6h/7d) keeps fallback and alerts aligned with current runtime behavior.
-
-## 🏁 Quick Start
-
-1. Initialize config and workspace
+### 1) Initialize

 ```bash
 clawgo onboard
 ```

-2. Configure upstream proxy (required)
+### 2) Configure upstream model/proxy

 ```bash
 clawgo login
 ```

-3. Check runtime status
+### 3) Check status

 ```bash
 clawgo status
 ```

-4. Run local interactive mode
+### 4) Local mode

 ```bash
 clawgo agent
-# or one-shot message
 clawgo agent -m "Hello"
 ```

-5. Start gateway service (for Telegram/Discord/etc.)
+### 5) Gateway mode

 ```bash
-# register systemd service
+# register + enable systemd service
 clawgo gateway
-
-# service control
 clawgo gateway start
-clawgo gateway restart
-clawgo gateway stop
 clawgo gateway status

-# foreground run
+# foreground mode
 clawgo gateway run
-
-# runtime autonomy switches
-clawgo gateway autonomy status
-clawgo gateway autonomy on
-clawgo gateway autonomy off
 ```

-## 📌 Command Reference
+---
+
+## WebUI
+
+Access:

 ```text
-clawgo onboard                     Initialize config and workspace
-clawgo login                       Configure CLIProxyAPI upstream
-clawgo status                      Show config/workspace/model/logging status
-clawgo agent [-m "..."]           Local interactive mode
-clawgo gateway [...]               Register/run/manage gateway service
-clawgo config set|get|check|reload Config CRUD, validation, hot reload
-clawgo channel test ...            Channel connectivity test
-clawgo cron ...                    Scheduled job management
-clawgo skills ...                  Skill install/list/remove/show
-clawgo uninstall [--purge] [--remove-bin]
+http://<host>:<port>/webui?token=<gateway.token>
 ```

-Make cross-platform build:
+Main pages:
+- Dashboard
+- Chat
+- Logs
+- Skills
+- Config
+- Cron
+- Nodes
+- Memory
+- Task Audit
+- Tasks
+- EKG
+
+---
+
+## Multi-Platform Build (Make)
+
+### Build all default targets

 ```bash
 make build-all
-# Override build matrix (example)
+```
+
+Default matrix:
+- linux/amd64
+- linux/arm64
+- linux/riscv64
+- darwin/amd64
+- darwin/arm64
+- windows/amd64
+- windows/arm64
+
+### Custom build matrix
+
+```bash
 make build-all BUILD_TARGETS="linux/amd64 linux/arm64 darwin/arm64 windows/amd64"
-# Package artifacts + checksums
+```
+
+### Package + checksums
+
+```bash
 make package-all
 ```

-Global flags:
+Outputs:
+- `build/*.tar.gz` (Linux/macOS)
+- `build/*.zip` (Windows)
+- `build/checksums.txt`
+
+---
+
+## GitHub Release Automation
+
+Built-in workflow: `.github/workflows/release.yml`
+
+Triggers:
+- tag push: `v*` (e.g. `v0.0.1`)
+- manual dispatch (workflow_dispatch)
+
+Pipeline includes:
+- Multi-platform compilation
+- Artifact packaging
+- Checksum generation
+- WebUI dist packaging
+- GitHub Releases publishing
+
+Example:

 ```bash
-clawgo --config /path/to/config.json <command>
-clawgo --debug <command>
+git tag v0.0.2
+git push origin v0.0.2
 ```

-## ⚙️ Config Management and Hot Reload
+---

-Update config values directly from CLI and trigger gateway hot reload:
-
-```bash
-clawgo config set channels.telegram.enable true
-clawgo config get channels.telegram.enabled
-clawgo config check
-clawgo config reload
-```
-
-Notes:
- `enable` is normalized to `enabled`.
- `config set` uses atomic write.
- If gateway reload fails while running, config auto-rolls back from backup.
- Custom `--config` path is consistently used by CLI config commands and in-channel `/config` commands.
- Config loading uses strict JSON decoding: unknown fields and trailing JSON content now fail fast.
-
-## 🌐 Channels and Message Control
-
-Supported in-channel slash commands:
+## Common Commands

 ```text
-/help
-/stop
-/status
-/status run [run_id|latest]
-/status wait <run_id|latest> [timeout_seconds]
-/config get <path>
-/config set <path> <value>
-/reload
-/pipeline list
-/pipeline status <pipeline_id>
-/pipeline ready <pipeline_id>
+clawgo onboard
+clawgo login
+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]
 ```

-Autonomy and auto-learn control now default to natural language (no slash commands required). Examples:
- `start autonomy mode and check every 30 minutes`
- `stop auto-learn`
- `show latest run status`
- `wait for run-1739950000000000000-8 and report when done`
+---

-Scheduling semantics (`session_key` based):
- Strict FIFO processing per session.
- `/stop` interrupts current response and continues queued messages.
- Different sessions are processed concurrently.
+## Config & Hot Reload

-Channel test example:
+- Supports `clawgo config set/get/check/reload`
+- Strict JSON parsing (unknown fields fail fast)
+- Auto rollback on failed hot reload

-```bash
-clawgo channel test --channel telegram --to <chat_id> -m "ping"
-```
+---

-## 🧠 Memory, Autonomy, and Context Compaction
+## Stability / Operations Notes

- On startup, the agent loads `AGENTS.md`, `SOUL.md`, and `USER.md` as behavior and semantic constraints.
- Gateway startup triggers a self-check task using history and `HEARTBEAT.md` to decide whether unfinished tasks should continue.
- Context compaction is triggered by both message-count and transcript-size thresholds.
- Compaction modes are `summary`, `responses_compact`, and `hybrid`; `responses_compact` requires `protocol=responses` and `supports_responses_compact=true` on the active proxy.
- Layered memory supports `profile / project / procedures / recent notes`.
+Recommended for production:
+- tune channel dedupe windows
+- keep heartbeat filtered in task-audit by default
+- monitor EKG with 24h window baseline
+- review Top errsig/provider score periodically

-Heartbeat + context compaction config example:
+---

-```json
-"agents": {
-  "defaults": {
-    "heartbeat": {
-      "enabled": true,
-      "every_sec": 1800,
-      "ack_max_chars": 64,
-      "prompt_template": "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK."
-    },
-    "texts": {
-      "no_response_fallback": "I've completed processing but have no response to give.",
-      "think_only_fallback": "Thinking process completed.",
-      "memory_recall_keywords": ["remember", "记得", "上次", "之前", "偏好", "preference", "todo", "待办", "决定", "decision"],
-      "lang_usage": "Usage: /lang <code>",
-      "lang_invalid": "Invalid language code.",
-      "lang_updated_template": "Language preference updated to %s",
-      "subagents_none": "No subagents.",
-      "sessions_none": "No sessions.",
-      "unsupported_action": "unsupported action",
-      "system_rewrite_template": "Rewrite the following internal system update in concise user-facing language:\n\n%s",
-      "runtime_compaction_note": "[runtime-compaction] removed %d old messages, kept %d recent messages",
-      "startup_compaction_note": "[startup-compaction] removed %d old messages, kept %d recent messages"
-    },
-    "context_compaction": {
-      "enabled": true,
-      "mode": "summary",
-      "trigger_messages": 60,
-      "keep_recent_messages": 20,
-      "max_summary_chars": 6000,
-      "max_transcript_chars": 20000
-    }
-  }
-}
-```
+## License

-Runtime-control config example (autonomy guards / run-state retention):
-
-```json
-"agents": {
-  "defaults": {
-    "runtime_control": {
-      "intent_max_input_chars": 1200,
-      "autonomy_tick_interval_sec": 20,
-      "autonomy_min_run_interval_sec": 20,
-      "autonomy_idle_threshold_sec": 20,
-      "autonomy_max_rounds_without_user": 120,
-      "autonomy_max_pending_duration_sec": 180,
-      "autonomy_max_consecutive_stalls": 3,
-      "autolearn_max_rounds_without_user": 200,
-      "run_state_ttl_seconds": 1800,
-      "run_state_max": 500,
-      "tool_parallel_safe_names": ["read_file", "list_files", "find_files", "grep_files", "memory_search", "web_search", "repo_map", "system_info"],
-      "tool_max_parallel_calls": 2
-    }
-  }
-}
-```
-
-## 🤖 Multi-Agent Orchestration (Pipeline)
-
-Built-in orchestration tools:
- `pipeline_create`
- `pipeline_status`
- `pipeline_state_set`
- `pipeline_dispatch`
- `spawn` (supports `pipeline_id/task_id/role`)
-
-Useful for complex task decomposition, role-based execution, and shared state workflows.
-
-## 🛡️ Reliability
-
- **Proxy/model fallback**: retries models in the current proxy first, then switches proxies in `proxy_fallbacks` when all models fail.
- **HTTP compatibility handling**: detects non-JSON error pages with body preview; parses tool calls from `<function_call>` blocks.
- **Sentinel**: periodic checks for config/memory/log resources with optional auto-heal and notifications.
-
-Sentinel config example:
-
-```json
-"sentinel": {
-  "enabled": true,
-  "interval_sec": 60,
-  "auto_heal": true,
-  "notify_channel": "",
-  "notify_chat_id": ""
-}
-```
-
-## ⏱️ Scheduled Jobs (Cron)
-
-```bash
-clawgo cron list
-clawgo cron add -n "daily-check" -m "check todo" -c "0 9 * * *"
-clawgo cron add -n "heartbeat" -m "report status" -e 300
-clawgo cron enable <job_id>
-clawgo cron disable <job_id>
-clawgo cron remove <job_id>
-```
-
-`cron add` options:
- `-n, --name` job name
- `-m, --message` agent input message
- `-e, --every` run every N seconds
- `-c, --cron` cron expression
- `-d, --deliver --channel <name> --to <id>` deliver response to a channel
-
-## 🧩 Skills
-
-Skill management commands:
-
-```bash
-clawgo skills list
-clawgo skills search
-clawgo skills show <name>
-clawgo skills install <github-repo>
-clawgo skills remove <name>
-clawgo skills install-builtin
-clawgo skills list-builtin
-```
-
-Notes:
- Install skills from GitHub (for example `owner/repo/skill`).
- Install built-in skills into workspace.
- Execute atomic scripts through `skill_exec` from `skills/<name>/scripts/*`.
-
-## 🗂️ Workspace and Managed Docs
-
-Default workspace is typically `~/.clawgo/workspace`:
-
-```text
-workspace/
-  memory/
-    MEMORY.md
-    HEARTBEAT.md
-  skills/
-  AGENTS.md
-  SOUL.md
-  USER.md
-```
-
-`clawgo onboard` and `make install` sync `AGENTS.md`, `SOUL.md`, `USER.md`:
- Create file if missing.
- Update only `CLAWGO MANAGED BLOCK` if file exists, preserving user custom sections.
-
-## 🧾 Logging
-
-File logging is enabled by default with rotation and retention:
-
-```json
-"logging": {
-  "enabled": true,
-  "dir": "~/.clawgo/logs",
-  "filename": "clawgo.log",
-  "max_size_mb": 20,
-  "retention_days": 3
-}
-```
-
-Recommended structured fields for querying/alerting:
-`channel`, `chat_id`, `sender_id`, `preview`, `error`, `message_content_length`, `assistant_content_length`, `output_content_length`, `transcript_length`.
-
-## 🛠️ Build and Install (Linux)
-
-```bash
-cd clawgo
-make build
-make install
-```
-
-Optional build flag:
-
-```bash
-# default: strip symbols for smaller binary
-make build STRIP_SYMBOLS=1
-
-# keep debug symbols
-make build STRIP_SYMBOLS=0
-```
-
-## 🧹 Uninstall
-
-```bash
-clawgo uninstall
-clawgo uninstall --purge
-clawgo uninstall --remove-bin
-```
-
-## 📜 License
-
-MIT License.
+See repository License file.