Skip to content

Commit 91e9a38

Browse files
author
ukgorclawbot-stack
committed
Add architecture guide
1 parent e5d7d05 commit 91e9a38

4 files changed

Lines changed: 212 additions & 0 deletions

File tree

‎README.en.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ Language:
6262
- Code of Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
6363
- FAQ: [docs/faq.md](./docs/faq.md)
6464
- Changelog: [CHANGELOG.md](./CHANGELOG.md)
65+
- Architecture Guide: [docs/architecture.md](./docs/architecture.md)
6566

6667
## Quick Start
6768

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
- 行为准则：[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
2323
- 常见问题：[docs/faq.md](./docs/faq.md)
2424
- 更新记录：[CHANGELOG.md](./CHANGELOG.md)
25+
- 架构详解：[docs/architecture.md](./docs/architecture.md)
2526

2627
适合这些场景：
2728
- 团队协作群里的任务拆分和汇报

‎RELEASE_NOTES_v0.1.7.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Telegram Multi-Bot Stack v0.1.7
2+
3+
This release adds a dedicated architecture guide.
4+
5+
## What's New
6+
7+
- added `docs/architecture.md`
8+
- linked the architecture guide from both Chinese and English README files
9+
10+
## Why This Matters
11+
12+
- new users can understand the 6-bot layout faster
13+
- contributors can see the routing, memory, permission, and shared-skill model in one place
14+
- the repository now has a clearer technical overview beyond the landing-page diagram
15+
16+
## Quick Start
17+
18+
```bash
19+
git clone https://github.com/ukgorclawbot-stack/telegram-multi-bot-stack.git
20+
cd telegram-multi-bot-stack
21+
bash ./install.sh
22+
bash ./configure.sh
23+
bash ./apply_stack.sh
24+
```

‎docs/architecture.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Architecture
2+
3+
This document explains how the public Telegram Multi-Bot Stack is structured.
4+
5+
这份文档解释公开版 Telegram Multi-Bot Stack 的整体架构。
6+
7+
## 1. High-Level Idea / 总体思路
8+
9+
The stack separates:
10+
11+
- group bots for collaboration, routing, and reporting
12+
- private bots for deeper execution and personal workflows
13+
- shared layers for task queue, memory summaries, and reusable skills
14+
15+
这套系统把能力拆成三层：
16+
17+
- 群聊 bots：负责协作、分派、汇报
18+
- 私聊 bots：负责深度执行和个人工作流
19+
- 共享层：负责任务队列、记忆摘要和复用 skill
20+
21+
## 2. Default 6-Bot Layout / 默认 6 Bot 结构
22+
23+
| Bot | Scene | Main responsibility |
24+
|---|---|---|
25+
| `OpenClaw-Group` | Group | routing, task decomposition, status, shared memory write-back |
26+
| `Gemini-Group` | Group | daily report, research summary, analysis, reporting |
27+
| `Codex-Group` | Group | coding, scripts, debugging, technical execution |
28+
| `OpenClaw-Private` | Private | personal control plane, private delegation |
29+
| `Gemini-Private` | Private | high-permission autonomous execution |
30+
| `Codex-Private` | Private | private coding execution |
31+
32+
## 3. Shared Layers / 共享层
33+
34+
### 3.1 Task Queue
35+
36+
Used for:
37+
38+
- delegated execution
39+
- worker pickup
40+
- final result handoff
41+
42+
用途：
43+
44+
- 跨 bot 任务委派
45+
- worker 认领执行
46+
- 最终结果回传
47+
48+
### 3.2 Memory Summaries
49+
50+
The stack does not rely only on raw chat history.
51+
52+
Instead, it keeps short summaries so bots can:
53+
54+
- recall recent context faster
55+
- share important outcomes without copying full conversations
56+
- reduce group/private cross-contamination
57+
58+
这套系统不是只靠原始聊天历史。
59+
60+
它会保留简短摘要，帮助 bot：
61+
62+
- 更快召回最近上下文
63+
- 共享关键结论而不是整段聊天
64+
- 降低群聊和私聊上下文串线
65+
66+
### 3.3 Shared Skills
67+
68+
Skills are designed to be shared across bots.
69+
70+
That means:
71+
72+
- new skills can be installed once
73+
- multiple bots can reuse the same capability
74+
- the stack stays extensible without hardcoding everything into bot logic
75+
76+
skill 设计成可共享：
77+
78+
- 新 skill 装一次即可
79+
- 多个 bot 可以复用
80+
- 扩展能力不需要都写死进 bot 逻辑
81+
82+
## 4. Message Routing / 消息路由
83+
84+
### Group Chat
85+
86+
Typical pattern:
87+
88+
1. `OpenClaw-Group` receives an unassigned task-like message
89+
2. it decomposes the task
90+
3. it routes to `Gemini-Group` or `Codex-Group`
91+
4. final result is written back into shared memory
92+
93+
群聊典型链路：
94+
95+
1. `OpenClaw-Group` 接住未点名的任务型消息
96+
2. 它先拆分任务
97+
3. 再分派给 `Gemini-Group` 或 `Codex-Group`
98+
4. 最终结果写回共享记忆
99+
100+
### Private Chat
101+
102+
Typical pattern:
103+
104+
- private bots handle deeper direct requests
105+
- private execution can use broader local permissions
106+
- group-facing behavior stays more stable and lower-risk
107+
108+
私聊典型链路：
109+
110+
- 私聊 bot 直接接住深度请求
111+
- 私聊执行可以拥有更高的本机权限
112+
- 群聊侧保持更稳、更低风险
113+
114+
## 5. Permission Model / 权限模型
115+
116+
The default stack usually uses:
117+
118+
- more constrained workdirs for some group bots
119+
- broader home-directory workdirs for private bots
120+
121+
默认情况下通常是：
122+
123+
- 群聊部分 bot 使用更收敛的工作目录
124+
- 私聊 bot 使用更宽的 home 目录工作范围
125+
126+
Why:
127+
128+
- group bots should be safer and more predictable
129+
- private bots are expected to do deeper personal work
130+
131+
原因：
132+
133+
- 群聊 bot 更强调安全和稳定
134+
- 私聊 bot 更强调深度执行能力
135+
136+
## 6. Config Model / 配置模型
137+
138+
The stack is generated from a TOML spec.
139+
140+
Important pieces:
141+
142+
- `bot_stack.bootstrap.toml`
143+
- generated env files
144+
- generated launchd plist files
145+
146+
这套系统通过 TOML 清单生成配置。
147+
148+
关键文件：
149+
150+
- `bot_stack.bootstrap.toml`
151+
- 生成出来的 env 文件
152+
- 生成出来的 launchd plist 文件
153+
154+
## 7. Migration and Rebuild / 迁移与重建
155+
156+
The project supports:
157+
158+
- reverse export from a live stack
159+
- migration-ready templates for a fresh machine
160+
161+
支持：
162+
163+
- 从线上运行中的配置反向导出
164+
- 为新机器生成可落地的迁移模板
165+
166+
This makes it easier to:
167+
168+
- move to another Mac
169+
- clone the setup safely
170+
- document a running deployment
171+
172+
这样更方便：
173+
174+
- 迁移到另一台 Mac
175+
- 安全复制一套环境
176+
- 文档化当前运行架构
177+
178+
## 8. Recommended Reading Order / 建议阅读顺序
179+
180+
If you are new, read in this order:
181+
182+
1. `README.md` or `README.en.md`
183+
2. `INSTALL.md` or `INSTALL.en.md`
184+
3. `docs/faq.md`
185+
4. this file
186+
5. `CONTRIBUTING.md` and `SECURITY.md` if you plan to contribute

0 commit comments

Comments
 (0)