# 🐙 yee88 完整使用指南

yee88 是一个 Telegram 桥接工具，让你可以通过 Telegram 聊天界面来运行 AI 编程助手（Codex、Claude Code、OpenCode、Pi）。

**当前版本: v0.8.0**

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 📦 一、安装与初始化（💻 电脑侧）

### 1. 安装依赖

```bash
# 安装 uv（Python 包管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 Python 3.14
uv python install 3.14

# 安装 yee88
uv tool install -U yee88
```

### 2. 安装 AI 引擎（至少一个）

```bash
# Codex (OpenAI)
npm install -g @openai/codex

# Claude Code (Anthropic)
npm install -g @anthropic-ai/claude-code

# OpenCode
npm install -g opencode-ai@latest

# Pi
npm install -g @mariozechner/pi-coding-agent
```

### 3. 首次运行配置（📱 手机侧配合）

```bash
yee88
```

这会启动交互式向导：

1. **创建 Telegram Bot** → 去 @BotFather 创建机器人，获取 token
2. **选择工作流**：
   - `assistant` - 持续对话模式（推荐个人使用）
   - `workspace` - 话题模式（团队多项目）
   - `handoff` - 回复继续模式
3. **连接聊天** → 在 Telegram 向机器人发送 `/start`
4. **选择默认引擎** → codex / claude / opencode / pi

配置保存在 `~/.yee88/yee88.toml`

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 🚀 二、日常使用

### 启动 yee88（💻 电脑侧）

```bash
# 在项目目录启动
cd ~/your-project
yee88

# 指定引擎启动
yee88 claude
yee88 codex
```

### 基本对话（📱 手机侧 Telegram）

直接发送消息给机器人：

```
解释这个项目是做什么的
```

### 切换引擎（📱 手机侧）

在消息前加引擎前缀：

```
/codex 修复这个 bug
/claude 重构这个函数
/opencode 优化性能
/pi 添加测试
```

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 📁 三、项目管理

### 注册项目（💻 电脑侧）

```bash
cd ~/dev/my-project
yee88 init myproject
```

### 从任意位置定位项目（📱 手机侧）

```
/myproject 添加新功能
/myproject @feat/new-ui 创建登录页面
```

### 设置默认项目（💻 电脑侧）

```bash
yee88 config set default_project myproject
```

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 🌳 四、工作树（Worktrees）

### 在特定分支上运行（📱 手机侧）

```
/myproject @feat/auth 实现 JWT 认证
```

yee88 会自动：

- 创建 `.worktrees/feat/auth` 工作树
- 在该分支上下文中运行 AI

### 配置工作树（💻 电脑侧）

```bash
yee88 config set projects.myproject.worktrees_dir ".worktrees"
yee88 config set projects.myproject.worktree_base "main"
```

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 💬 五、Telegram 命令（📱 手机侧）

| 命令 | 说明 |
|------|------|
| `/cancel` | 回复进度消息以取消当前运行 |
| `/agent` | 查看/设置当前聊天的默认引擎 |
| `/agent set claude` | 设置默认引擎为 Claude |
| `/model` | 查看/设置模型覆盖 |
| `/reasoning` | 查看/设置推理模式 |
| `/trigger` | 设置触发模式（mentions-only / all） |
| `/file put <path>` | 上传文件到仓库 |
| `/file get <path>` | 获取文件/目录（自动压缩） |
| `/topic <project> @branch` | 创建/绑定话题（需开启 topics） |
| `/ctx` | 显示当前上下文绑定 |
| `/ctx set <project> @branch` | 更新上下文 |
| `/ctx clear` | 清除上下文绑定 |
| `/new` | 清除当前会话，开始新对话 |

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 📎 六、文件传输

### 启用文件传输（💻 电脑侧）

```bash
yee88 config set transports.telegram.files.enabled true
yee88 config set transports.telegram.files.auto_put true
```

### 上传文件（📱 手机侧）

发送文档并附带说明：

```
/file put docs/spec.pdf
```

或直接发送文件（自动保存到 `incoming/`）

### 下载文件（📱 手机侧）

```
/file get src/main.py
/file get src/          # 目录会自动打包为 zip
```

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 🎙 七、语音消息

### 启用语音转录（💻 电脑侧）

```bash
yee88 config set transports.telegram.voice_transcription true
```

设置环境变量 `OPENAI_API_KEY`

```bash
export OPENAI_API_KEY="sk-..."
```

### 使用（📱 手机侧）

直接发送语音消息，yee88 会自动转录并执行

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## ⚙️ 八、配置管理（💻 电脑侧）

### 查看配置

```bash
yee88 config list
yee88 config get default_engine
```

### 修改配置

```bash
# 设置默认值
yee88 config set default_engine "claude"
yee88 config set default_project "myproject"

# Telegram 设置
yee88 config set transports.telegram.session_mode "chat"
yee88 config set transports.telegram.show_resume_line false

# 引擎特定配置
yee88 config set claude.model "claude-sonnet-4-5-20250929"
yee88 config set codex.profile "work"

# 启用配置热重载
yee88 config set watch_config true
```

### 诊断检查

```bash
yee88 doctor
```

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 🗂 九、话题模式（Topics）

适合团队协作，每个话题绑定一个项目/分支：

### 启用（💻 电脑侧）

```bash
yee88 config set transports.telegram.topics.enabled true
```

### 创建话题（📱 手机侧）

在论坛群组中：

```
/topic myproject @main 设置主分支
/topic myproject @feat/ui 前端开发
```

每个话题会自动记住绑定的项目和分支，无需重复输入。

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 🔧 十、完整配置参考

### 配置文件位置

- **默认**: `~/.yee88/yee88.toml`
- **锁文件**: `~/.yee88/yee88.lock`

### 顶层配置

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `watch_config` | bool | `false` | 热重载配置更改（传输层除外） |
| `default_engine` | string | `"codex"` | 新线程的默认引擎 ID |
| `default_project` | string\|null | `null` | 默认项目别名 |
| `transport` | string | `"telegram"` | 传输后端 ID |
| `system_prompt` | string | (内置) | 系统提示词 |

### Telegram 传输配置 (`transports.telegram`)

#### 基础配置

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `bot_token` | string | (必需) | Telegram Bot Token（从 @BotFather 获取） |
| `chat_id` | int | (必需) | 默认聊天 ID |
| `allowed_user_ids` | int[] | `[]` | 允许的用户 ID 列表（空列表表示不限制） |
| `message_overflow` | string | `"trim"` | 长消息处理方式：`"trim"`(截断) 或 `"split"`(分割) |
| `session_mode` | string | `"stateless"` | 会话模式：`"stateless"`(回复继续) 或 `"chat"`(自动恢复) |
| `show_resume_line` | bool | `true` | 在消息页脚显示恢复行 |
| `forward_coalesce_s` | float | `1.0` | 转发消息合并的静默窗口（秒），设为 `0` 禁用 |

#### 语音转录配置

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `voice_transcription` | bool | `false` | 启用语音笔记转录 |
| `voice_max_bytes` | int | `10485760` | 最大语音文件大小（字节，默认 10MB） |
| `voice_transcription_model` | string | `"gpt-4o-mini-transcribe"` | 转录模型名称 |
| `voice_transcription_base_url` | string\|null | `null` | 转录 API 基础 URL（可选） |
| `voice_transcription_api_key` | string\|null | `null` | 转录 API 密钥（可选） |

#### 话题配置 (`transports.telegram.topics`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `enabled` | bool | `false` | 启用论坛话题功能 |
| `scope` | string | `"auto"` | 话题管理范围：`"auto"`、`"main"`、`"projects"`、`"all"` |

#### 文件传输配置 (`transports.telegram.files`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `enabled` | bool | `false` | 启用 `/file put` 和 `/file get` 命令 |
| `auto_put` | bool | `true` | 自动保存上传的文件 |
| `auto_put_mode` | string | `"upload"` | 上传后行为：`"upload"`(仅保存) 或 `"prompt"`(保存并启动运行) |
| `uploads_dir` | string | `"incoming"` | 上传目录（相对于仓库/worktree） |
| `allowed_user_ids` | int[] | `[]` | 允许文件传输的用户 ID（空列表允许私聊，群组需要管理员） |
| `deny_globs` | string[] | (见下) | 拒绝的文件模式列表 |

默认 `deny_globs`:
```toml
deny_globs = [
    ".git/**",
    ".env",
    ".envrc",
    "**/*.pem",
    "**/.ssh/**"
]
```

**文件大小限制**（不可配置）：
- 上传：20 MiB
- 下载：50 MiB

### 项目配置 (`projects.<alias>`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `path` | string | (必需) | 仓库根目录路径（支持 `~` 展开） |
| `worktrees_dir` | string | `".worktrees"` | Worktree 根目录（相对于 `path`） |
| `default_engine` | string\|null | `null` | 项目默认引擎 |
| `worktree_base` | string\|null | `null` | 新 worktree 的基础分支 |
| `chat_id` | int\|null | `null` | 绑定到此项目的 Telegram 聊天 ID |
| `system_prompt` | string\|null | `null` | 项目特定的系统提示词 |

### 插件配置 (`plugins`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `enabled` | string[] | `[]` | 启用的插件列表（空列表表示加载所有已安装插件） |

### 引擎特定配置

#### Codex 配置 (`[codex]`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `extra_args` | string[] | `["-c", "notify=[]"]` | 额外的 CLI 参数（不支持 exec-only 标志） |
| `profile` | string | (未设置) | 配置文件名称，作为 `--profile` 传递并用于会话标题 |

#### Claude 配置 (`[claude]`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `model` | string | (未设置) | 可选的模型覆盖 |
| `allowed_tools` | string[] | `["Bash", "Read", "Edit", "Write"]` | 自动批准的工具列表 |
| `dangerously_skip_permissions` | bool | `false` | 跳过 Claude 权限提示（**高风险**） |
| `use_api_billing` | bool | `false` | 使用 API 计费（默认使用订阅） |

#### Pi 配置 (`[pi]`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `model` | string | (未设置) | 传递给 `--model` |
| `provider` | string | (未设置) | 传递给 `--provider` |
| `extra_args` | string[] | `[]` | 额外的 CLI 参数 |

#### OpenCode 配置 (`[opencode]`)

| 配置项 | 类型 | 默认值 | 中文说明 |
|--------|------|--------|----------|
| `model` | string | (未设置) | 可选的模型覆盖 |


⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 📋 十一、三种工作流的完整配置示例

### Assistant 工作流（持续聊天）

```toml
default_engine = "codex"
transport = "telegram"

[transports.telegram]
bot_token = "YOUR_BOT_TOKEN"
chat_id = 123456789
session_mode = "chat"           # 自动恢复
show_resume_line = false        # 隐藏恢复行

[transports.telegram.topics]
enabled = false
scope = "auto"
```

### Workspace 工作流（话题分支）

```toml
default_engine = "codex"
transport = "telegram"

[transports.telegram]
bot_token = "YOUR_BOT_TOKEN"
chat_id = -1001234567890        # 论坛群组
session_mode = "chat"
show_resume_line = false

[transports.telegram.topics]
enabled = true                  # 启用话题
scope = "auto"

[projects.my-project]
path = "~/dev/my-project"
chat_id = -1001234567890
```

### Handoff 工作流（回复继续）

```toml
default_engine = "codex"
transport = "telegram"

[transports.telegram]
bot_token = "YOUR_BOT_TOKEN"
chat_id = 123456789
session_mode = "stateless"      # 回复继续
show_resume_line = true         # 始终显示恢复行
```

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 📲 十二、会话接力（Handoff）

将电脑端的 OpenCode 会话上下文发送到 Telegram，方便在手机上继续对话。

### 使用方法（💻 电脑侧）

```bash
yee88 handoff
```

### 工作流程

1. 自动列出当前项目的最近会话（带话题名称）
2. 选择要接力的会话
3. 自动创建新的 Telegram Topic
4. 将会话上下文和最近消息发送到 Topic
5. 在 Telegram 中直接继续对话

### 选项

| 选项 | 说明 |
|------|------|
| `--session, -s` | 指定会话 ID（默认交互选择） |
| `--limit, -n` | 包含的消息数量（默认 3） |
| `--project, -p` | 项目名称 |

### 示例

```bash
# 交互式选择会话
yee88 handoff

# 指定会话和消息数量
yee88 handoff -s ses_abc123 -n 5
```

### 前置条件

- 需要启用 Topics 模式：`yee88 config set transports.telegram.topics.enabled true`
- 需要配置 Telegram bot_token 和 chat_id

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 🔀 十三、话题分叉（Fork）

在 Telegram Topics 模式下，将当前话题的上下文和会话状态分叉到一个新话题。

### 使用方法

在任意话题中发送：

```
/fork
```

### 功能说明

- 自动创建新话题，标题格式：`原话题 (fork #1)`
- 支持多次分叉，自动递增编号：`原话题 (fork #2)`、`原话题 (fork #3)`...
- 复制原话题的上下文和会话状态到新话题
- 在新话题中继续对话，不影响原话题

### 使用场景

- 从当前对话中派生新的探索方向
- 保存当前状态，尝试不同的解决方案
- 多人协作时创建个人工作分支

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## ⏰ 十四、定时任务（Cron）

通过配置定时任务，让 yee88 自动在指定时间执行指令。

### 定时任务特性

- ✅ **全新 Session 运行** - 每个定时任务都在独立的全新会话中运行，不受任何上下文干扰
- ✅ **可配置引擎和模型** - 每个任务可独立指定使用的 AI 引擎和模型
- ✅ **支持 Cron 表达式** - 使用标准 Cron 表达式设置执行时间
- ✅ **支持一次性任务** - 可设置仅执行一次的定时任务

### 配置定时任务

定时任务配置保存在 `~/.yee88/cron.toml`。

#### 配置文件格式

```toml
[[jobs]]
id = "daily-summary"                # 任务唯一标识
schedule = "0 9 * * *"              # Cron 表达式：每天上午 9 点
message = "总结昨天提交的代码"       # 要执行的指令
project = "myproject"               # 关联的项目（可选）
enabled = true                      # 是否启用
engine = "claude"                   # 指定引擎：codex / claude / opencode / pi（可选）
model = "claude-sonnet-4-5-20250929" # 指定模型（可选）

[[jobs]]
id = "weekly-report"
schedule = "0 18 * * 5"             # 每周五下午 6 点
message = "生成本周工作总结"
project = "myproject"
enabled = true
engine = "codex"
model = "gpt-4o"
```

#### 一次性任务

设置 `one_time = true`，任务执行一次后自动删除：

```toml
[[jobs]]
id = "one-time-task"
schedule = "2025-02-10T14:30:00+08:00"  # ISO 8601 格式时间
message = "执行一次性的数据分析"
project = "myproject"
one_time = true
engine = "opencode"
```

### CLI 命令管理

```bash
# 查看所有定时任务
yee88 cron list

# 添加定时任务（交互式）
yee88 cron add

# 删除定时任务
yee88 cron remove daily-summary

# 启用/禁用定时任务
yee88 cron enable daily-summary
yee88 cron disable daily-summary
```

### 关键特性说明

#### 1. 全新 Session 运行

定时任务默认在**全新的会话**中运行：
- 不继承任何之前的对话上下文
- 不恢复之前的会话状态
- 每个任务都是独立的 AI 会话

这确保了定时任务不会因为之前的对话而产生意外行为。

#### 2. 引擎和模型配置

可以为每个定时任务独立配置：

| 参数 | 说明 | 示例 |
|------|------|------|
| `engine` | AI 引擎类型 | `codex`, `claude`, `opencode`, `pi` |
| `model` | 具体模型名称 | `gpt-4o`, `claude-sonnet-4-5-20250929` |

**优先级**：任务配置 > 项目配置 > 全局配置

#### 3. Cron 表达式参考

| 表达式 | 说明 |
|--------|------|
| `0 9 * * *` | 每天上午 9:00 |
| `0 0 * * 1` | 每周一午夜 |
| `*/30 * * * *` | 每 30 分钟 |
| `0 0 1 * *` | 每月 1 号午夜 |
| `0 9,18 * * 1-5` | 工作日 9:00 和 18:00 |

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 📝 十五、使用技巧

### 1. 快速切换上下文

```
/ctx set myproject @feat/new-feature
```

之后的所有消息都会在这个项目和分支上下文中执行。

### 2. 使用定时消息

在 Telegram 中安排消息，yee88 会在指定时间执行。

### 3. 查看进度

运行过程中会显示实时进度消息，包含：
- 正在执行的命令
- 工具调用
- 文件变更
- 已用时间

### 4. 恢复会话

每个完成的运行都会在消息底部显示恢复命令：

```
codex resume <token>
```

复制到终端即可继续会话。

### 5. 多引擎协作

```
/codex 实现基础功能
/claude 优化代码结构
/opencode 添加测试
```

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

## 📋 版本历史

### v0.8.0 (2025-02-02)

**新功能**
- ✨ **定时任务增强**:
  - 支持配置引擎和模型 - 每个定时任务可独立指定使用的 AI 引擎和模型
  - 全新 Session 运行 - 定时任务默认在独立的全新会话中执行，不受上下文干扰
  - 支持一次性任务 - 可设置仅执行一次的定时任务（执行后自动删除）

**改进**
- 优化定时任务的执行隔离性，确保任务之间互不干扰

### v0.7.1 (2025-02-01)

**新功能**
- ✨ **话题分叉 (`/fork`)**: 在 Topics 模式下将当前话题上下文分叉到新话题，支持多次分叉自动编号
- ✨ **会话接力 (`yee88 handoff`)**: 将电脑端 OpenCode 会话发送到 Telegram 继续对话

**改进**
- 优化 handoff 命令的输出提示信息

### v0.7.0

- 初始版本发布
