Add CI and bilingual install guide

Author: ukgorclawbot-stack

.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  syntax-and-generate:
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Python syntax check
+        run: |
+          python3 -m py_compile \
+            bootstrap_bot_stack.py \
+            configure_stack.py \
+            reverse_export_bot_stack.py \
+            make_migration_ready_stack.py \
+            bot.py \
+            group_bot.py \
+            xhs_adapter.py \
+            memory_store.py \
+            routing.py \
+            runners.py \
+            task_registry.py
+
+      - name: Shell syntax check
+        run: |
+          bash -n install.sh
+          bash -n configure.sh
+          bash -n apply_stack.sh
+          bash -n health_check.sh
+          bash -n scripts/shared-memory-write.sh
+          zsh -n bootstrap_bot_stack.sh
+          zsh -n run_role_bot.sh
+          zsh -n run_group_bot.sh
+
+      - name: Generate local config for CI
+        run: |
+          printf '%s\n%s\n%s\n%s\n%s\n' \
+            "$HOME" \
+            "123456789" \
+            "com.example.telegrambots" \
+            "Y" \
+            "N" \
+            | python3 configure_stack.py
+
+      - name: Generate stack from CI config
+        run: |
+          python3 bootstrap_bot_stack.py --config bot_stack.bootstrap.toml
+
+      - name: Build migration-ready template
+        run: |
+          python3 reverse_export_bot_stack.py \
+            --source-repo "$PWD" \
+            --launch-agents-dir "$PWD/.ci-launchagents" \
+            --output "$PWD/bot_stack.reverse_exported.toml"
+          python3 make_migration_ready_stack.py \
+            --source "$PWD/bot_stack.reverse_exported.toml" \
+            --output "$PWD/bot_stack.migration_ready.toml" \
+            --target-home "/Users/your_user"

INSTALL.md

@@ -1,8 +1,13 @@
-# 安装说明
+# 安装说明 / Installation Guide
 
-这份说明是给第一次接触这套框架的人准备的。
+这份说明是给第一次接触这套框架的人准备的。  
+This guide is written for first-time users.
 
-## 1. 你需要准备什么
+---
+
+## 中文
+
+### 1. 你需要准备什么
 
 在开始之前，请先准备：
 
@@ -21,7 +26,7 @@ git --version
 
 如果其中任意一条报错，先安装对应软件，再继续下面步骤。
 
-## 2. 如何创建 Telegram bot
+### 2. 如何创建 Telegram bot
 
 在 Telegram 里搜索 `@BotFather`，然后按下面步骤做：
 
@@ -32,14 +37,14 @@ git --version
 
 如果你要用推荐的 6 bot 结构，就需要准备 6 个 token。
 
-## 3. 下载项目
+### 3. 下载项目
 
 ```bash
 git clone https://github.com/ukgorclawbot-stack/telegram-multi-bot-stack.git
 cd telegram-multi-bot-stack
 ```
 
-## 4. 一键安装依赖
+### 4. 一键安装依赖
 
 ```bash
 bash ./install.sh
@@ -52,7 +57,7 @@ bash ./install.sh
 - 初始化本地目录
 - 准备配置模板
 
-## 5. 一键生成配置
+### 5. 一键生成配置
 
 ```bash
 bash ./configure.sh
@@ -66,7 +71,7 @@ bash ./configure.sh
 
 如果你不知道自己的 `user_id`，可以先用任意临时 bot 或现有 bot 的 `/whoami` 来查。
 
-## 6. 写入 token
+### 6. 写入 token
 
 如果你在配置向导里没有直接输入 token，就手动编辑：
 
@@ -87,7 +92,7 @@ TG_GEMINI_PRIVATE_TOKEN=
 TG_CODEX_PRIVATE_TOKEN=
 ```
 
-## 7. 启动
+### 7. 启动
 
 ```bash
 bash ./apply_stack.sh
@@ -100,7 +105,7 @@ bash ./apply_stack.sh
 - 生成正式 launchd plist
 - 自动加载并启动服务
 
-## 8. 只想先试运行
+### 8. 只想先试运行
 
 如果你还不想真正启动，只想先看会生成什么：
 
@@ -114,7 +119,7 @@ bash ./bootstrap_bot_stack.sh generate
 - `generated/bot-stack/launchd/`
 - `generated/bot-stack/STACK_SUMMARY.md`
 
-## 9. 安装完成后怎么检查是否成功
+### 9. 安装完成后怎么检查是否成功
 
 直接执行：
 
@@ -123,11 +128,12 @@ bash ./health_check.sh
 ```
 
 如果安装成功，你会看到：
+
 - Telegram API 检查结果
 - bot 服务状态
 - 监控和晨报状态
 
-## 10. 推荐给零基础用户的完整顺序
+### 10. 推荐给零基础用户的完整顺序
 
 按这个顺序照做最稳：
 
@@ -141,21 +147,21 @@ bash ./apply_stack.sh
 bash ./health_check.sh
 ```
 
-## 11. 常见问题
+### 11. 常见问题
 
-### 11.1 提示没找到 Python
+#### 11.1 提示没找到 Python
 
 先安装 Python 3，再重试：
 
 ```bash
 python3 --version
 ```
 
-### 11.2 提示 token 没提供
+#### 11.2 提示 token 没提供
 
 说明 `.bot_tokens.env` 还没写完整。
 
-### 11.3 机器人没响应
+#### 11.3 机器人没响应
 
 先检查 launchd 是否在线：
 
@@ -168,3 +174,175 @@ launchctl list | grep telegram
 ```bash
 tail -n 100 generated/bot-stack/logs/*.log
 ```
+
+---
+
+## English
+
+### 1. What You Need
+
+Before you start, prepare:
+
+1. A macOS computer
+2. `Python 3` installed
+3. `Git` installed
+4. `Telegram` installed
+5. Telegram bot tokens you plan to use
+
+If you are not sure whether `Python 3` and `Git` are installed, run:
+
+```bash
+python3 --version
+git --version
+```
+
+If either command fails, install the missing software first.
+
+### 2. How to Create Telegram Bots
+
+In Telegram, search for `@BotFather` and follow these steps:
+
+1. Send `/newbot`
+2. Pick a bot name
+3. Pick a bot username ending with `bot`
+4. Save the returned token
+
+If you use the recommended 6-bot layout, prepare 6 tokens.
+
+### 3. Clone the Project
+
+```bash
+git clone https://github.com/ukgorclawbot-stack/telegram-multi-bot-stack.git
+cd telegram-multi-bot-stack
+```
+
+### 4. Install Dependencies
+
+```bash
+bash ./install.sh
+```
+
+This script will automatically:
+
+- create `.venv`
+- install Python dependencies
+- initialize local directories
+- prepare configuration templates
+
+### 5. Configure the Stack
+
+```bash
+bash ./configure.sh
+```
+
+The wizard will ask for:
+
+- your home directory
+- which Telegram user ID is allowed to use the bots
+- whether to use the recommended 6-bot layout
+
+If you do not know your Telegram `user_id`, use any temporary bot or an existing bot command such as `/whoami`.
+
+### 6. Fill in Bot Tokens
+
+If you did not enter tokens during the wizard, edit the token file manually:
+
+```bash
+open .bot_tokens.env
+```
+
+Fill in one token per bot. This file is created automatically on first install.
+
+For the recommended 6-bot layout, these are the main fields:
+
+```bash
+TG_OPENCLAW_GROUP_TOKEN=
+TG_GEMINI_GROUP_TOKEN=
+TG_CODEX_GROUP_TOKEN=
+TG_OPENCLAW_PRIVATE_TOKEN=
+TG_GEMINI_PRIVATE_TOKEN=
+TG_CODEX_PRIVATE_TOKEN=
+```
+
+### 7. Start the Stack
+
+```bash
+bash ./apply_stack.sh
+```
+
+This step will:
+
+- load `.bot_tokens.env`
+- generate final env files
+- generate final launchd plist files
+- load and start the services automatically
+
+### 8. Preview Only
+
+If you do not want to start services yet and only want to preview generated files:
+
+```bash
+bash ./bootstrap_bot_stack.sh generate
+```
+
+Generated files will appear in:
+
+- `generated/bot-stack/env/`
+- `generated/bot-stack/launchd/`
+- `generated/bot-stack/STACK_SUMMARY.md`
+
+### 9. Verify the Installation
+
+Run:
+
+```bash
+bash ./health_check.sh
+```
+
+If setup is successful, you will see:
+
+- Telegram API status
+- bot service status
+- monitor and report status
+
+### 10. Best Order for Beginners
+
+Follow these steps in this exact order:
+
+```bash
+git clone https://github.com/ukgorclawbot-stack/telegram-multi-bot-stack.git
+cd telegram-multi-bot-stack
+bash ./install.sh
+bash ./configure.sh
+open .bot_tokens.env
+bash ./apply_stack.sh
+bash ./health_check.sh
+```
+
+### 11. Common Problems
+
+#### 11.1 Python Not Found
+
+Install Python 3 first, then retry:
+
+```bash
+python3 --version
+```
+
+#### 11.2 Token Missing
+
+That means `.bot_tokens.env` is incomplete.
+
+#### 11.3 Bots Are Not Responding
+
+Check whether launchd services are loaded:
+
+```bash
+launchctl list | grep telegram
+```
+
+Then inspect logs:
+
+```bash
+tail -n 100 generated/bot-stack/logs/*.log
+```