Skip to content

Commit 44d285f

Browse files
MackDingMackDing
committed
feat: bootstrap codex telegram claws with mcp and github skills
0 parents  commit 44d285f

17 files changed

Lines changed: 3058 additions & 0 deletions

‎.env.example‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
BOT_TOKEN=123456789:telegram-token-from-botfather
2+
ALLOWED_USER_IDS=123456789,987654321
3+
PROACTIVE_USER_IDS=123456789
4+
5+
CODEX_COMMAND=codex
6+
CODEX_ARGS=
7+
CODEX_WORKDIR=/absolute/path/to/your/workspace
8+
STREAM_THROTTLE_MS=1200
9+
STREAM_BUFFER_CHARS=120000
10+
REASONING_RENDER_MODE=spoiler
11+
12+
CRON_DAILY_SUMMARY=0 9 * * *
13+
CRON_TIMEZONE=Asia/Shanghai
14+
15+
MCP_SERVERS=[{"name":"filesystem","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/absolute/path/to/your/workspace"]}]
16+
17+
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
18+
GITHUB_DEFAULT_WORKDIR=/absolute/path/to/your/workspace
19+
GITHUB_DEFAULT_BRANCH=main
20+
E2E_TEST_COMMAND=npx playwright test --reporter=line

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
.env
3+
.DS_Store
4+
npm-debug.log*

‎AGENTS.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
This repository is currently minimal and does not yet include application code, tests, or build tooling. Until a concrete stack is added, keep contributions organized with a predictable layout:
5+
6+
- `src/` for production code
7+
- `tests/` for automated tests
8+
- `assets/` for static files such as images or fixtures
9+
- `docs/` for design notes or operational guides
10+
11+
Keep modules small and grouped by feature. For example, place Telegram client code in `src/telegram/` and matching tests in `tests/telegram/`.
12+
13+
## Build, Test, and Development Commands
14+
No project-specific commands are defined yet. When adding tooling, expose a minimal, documented set of commands such as:
15+
16+
- `npm install` or equivalent to install dependencies
17+
- `npm test` to run the full test suite
18+
- `npm run lint` to enforce style rules
19+
- `npm run dev` to start local development
20+
21+
If you introduce a different stack, update this file in the same change so contributors have one reliable entry point.
22+
23+
## Coding Style & Naming Conventions
24+
Use 4 spaces for indentation in Markdown, YAML, and Python-style formats; follow the formatter defaults for any language-specific toolchain you add. Prefer descriptive, lowercase directory names (`src/bot/`), `snake_case` for Python files, and `kebab-case` or framework-standard naming for frontend assets.
25+
26+
Add formatting and linting early and run them before opening a PR. Keep files ASCII unless the file already requires Unicode.
27+
28+
## Testing Guidelines
29+
Place tests under `tests/` and mirror the source layout. Name test files after the unit under test, such as `tests/telegram/test_dispatcher.py` or `dispatcher.test.ts`. Cover new behavior and important edge cases; avoid merging untested logic.
30+
31+
Document the exact test command in the project README and here once the framework is chosen.
32+
33+
## Commit & Pull Request Guidelines
34+
There is no Git history in the current workspace, so no established commit pattern can be inferred. Use short, imperative commit messages and prefer Conventional Commit prefixes where helpful, such as `feat: add webhook handler` or `fix: guard empty update payload`.
35+
36+
Pull requests should include a clear summary, testing notes, and linked issue references when applicable. Include screenshots or sample bot interactions for user-facing changes.
37+
38+
## Configuration & Secrets
39+
Do not commit API tokens, session files, or `.env` values. Keep local configuration in ignored files and document required environment variables in `README.md`.

‎README.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# codex-telegram-claws
2+
3+
`codex-telegram-claws` 是一个 Node.js (ESM) Telegram 超级代理。它在宿主机使用 `node-pty` 安全托管 `@openai/codex` CLI，并提供智能路由、MCP 上下文接入、推理流可视化、GitHub 自动化技能和定时主动任务。
4+
5+
对标参考项目：`RichardAtCT/claude-code-telegram`，但本项目专注 Codex CLI + MCP + Subagent 组合。
6+
7+
## 核心特性
8+
9+
- PTY 托管：强制 TTY 场景运行 CLI，避免无终端卡死。
10+
- Agentic Routing：将消息分流到 Codex 链路或 Skill 链路（MCP/GitHub）。
11+
- MCP Client：以 stdio 方式连接本机 MCP Server 并拉取上下文。
12+
- Reasoning Stream：解析 `<think>...</think>` 并用 Spoiler 或引用渲染。
13+
- 丝滑输出：节流 `editMessageText`，长文自动切片，MarkdownV2 防崩。
14+
- Zero Trust：白名单用户鉴权，非授权请求静默丢弃。
15+
- GitHub Skill：自然语言驱动 commit/push、创建 repo、触发和查看测试。
16+
- Cron 主动推送：每日发送“昨日代码变更摘要”。
17+
18+
## 架构总览
19+
20+
```text
21+
Telegram Message
22+
-> bot/handlers.js
23+
-> orchestrator/router.js
24+
-> runner/ptyManager.js (Codex CLI)
25+
-> orchestrator/skills/*.js (MCP/GitHub)
26+
-> bot/formatter.js
27+
-> Telegram editMessageText/sendMessage
28+
```
29+
30+
关键模块：
31+
32+
- `src/bot/`: 鉴权、中间件、格式化、Telegram 交互。
33+
- `src/orchestrator/`: 路由决策、MCP 客户端、技能调度。
34+
- `src/runner/`: PTY 生命周期、流式缓冲、节流刷新。
35+
- `src/cron/`: 定时任务注册与主动消息推送。
36+
37+
## 目录结构
38+
39+
```text
40+
codex-telegram-claws/
41+
├── package.json
42+
├── .env.example
43+
├── src/
44+
│ ├── index.js
45+
│ ├── config.js
46+
│ ├── bot/
47+
│ │ ├── middleware.js
48+
│ │ ├── formatter.js
49+
│ │ └── handlers.js
50+
│ ├── orchestrator/
51+
│ │ ├── router.js
52+
│ │ ├── mcpClient.js
53+
│ │ └── skills/
54+
│ │ ├── githubSkill.js
55+
│ │ └── mcpSkill.js
56+
│ ├── runner/
57+
│ │ └── ptyManager.js
58+
│ └── cron/
59+
│ └── scheduler.js
60+
└── README.md
61+
```
62+
63+
## 前置条件
64+
65+
- Node.js: https://nodejs.org/en/download/current
66+
- Codex CLI: https://github.com/openai/codex
67+
- Telegram Bot Token: 通过 `@BotFather` 获取
68+
- 可选：GitHub PAT（用于创建仓库与自动化操作）
69+
70+
## 快速开始
71+
72+
```bash
73+
npm install
74+
cp .env.example .env
75+
# 至少配置 BOT_TOKEN, ALLOWED_USER_IDS, CODEX_WORKDIR
76+
npm run start
77+
```
78+
79+
开发与检查：
80+
81+
```bash
82+
npm run dev
83+
npm run check
84+
```
85+
86+
## 环境变量说明
87+
88+
必填：
89+
90+
- `BOT_TOKEN`: Telegram Bot Token。
91+
- `ALLOWED_USER_IDS`: 白名单用户 ID，逗号分隔。
92+
- `CODEX_WORKDIR`: Codex CLI 工作目录（建议受限目录）。
93+
94+
常用可选：
95+
96+
- `CODEX_COMMAND`, `CODEX_ARGS`: Codex 启动命令与参数。
97+
- `STREAM_THROTTLE_MS`: 1-1.5 秒最佳（建议 `1200`）。
98+
- `REASONING_RENDER_MODE`: `spoiler` 或 `quote`。
99+
- `CRON_DAILY_SUMMARY`, `CRON_TIMEZONE`: Cron 表达式与时区。
100+
- `MCP_SERVERS`: JSON 数组，定义 MCP stdio server。
101+
- `GITHUB_TOKEN`: GitHub API Token。
102+
- `GITHUB_DEFAULT_WORKDIR`: Git 技能本地目录。
103+
- `E2E_TEST_COMMAND`: 测试命令（默认 Playwright）。
104+
105+
MCP 示例：
106+
107+
```env
108+
MCP_SERVERS=[{"name":"filesystem","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/abs/path/workspace"]}]
109+
```
110+
111+
## Telegram 指令与技能
112+
113+
基础命令：
114+
115+
- `/help`: 查看帮助。
116+
- `/interrupt`: 向 PTY 发送 `Ctrl+C`。
117+
- `/stop`: 结束当前 chat 的 PTY 会话。
118+
- `/cron_now`: 手动触发一次日报推送。
119+
120+
MCP Skill：
121+
122+
- `/mcp tools <server>`
123+
- `/mcp call <server> <tool> {"query":"..."}`
124+
125+
GitHub Skill：
126+
127+
- `/gh commit "feat: xxx"` 自动 `git add .` + commit + push。
128+
- `/gh push` 仅推送当前分支。
129+
- `/gh create repo my-new-repo` 在当前账号创建仓库并关联 origin。
130+
- `/gh run tests` 触发测试任务。
131+
- `/gh test status <jobId>` 查询测试状态与输出尾部。
132+
133+
## 推理流可视化
134+
135+
当 Codex CLI 输出包含 `<think>...</think>` 时，`formatter.js` 会抽取并渲染：
136+
137+
- `spoiler` 模式：`||...||`（默认，点击展开）。
138+
- `quote` 模式：引用块展示。
139+
140+
普通输出与推理输出会分段显示，避免污染代码可读性。
141+
142+
## 定时任务设计
143+
144+
默认 Cron：每天 09:00（`CRON_DAILY_SUMMARY`）统计昨日提交数据并主动推送给 `PROACTIVE_USER_IDS`。
145+
146+
摘要包含：
147+
148+
- 提交数量
149+
- 改动文件数 / 插入 / 删除
150+
- 最近提交列表（最多 8 条）
151+
152+
## 安全基线
153+
154+
- 白名单鉴权必须开启，拒绝公开 Bot。
155+
- 不提交 `.env`、Token、会话数据。
156+
- 建议使用最小权限 PAT，限制 repo scope。
157+
- 建议在生产使用独立系统用户运行并限制工作目录权限。
158+
159+
## 常见问题排查
160+
161+
- Bot 不响应：检查 `BOT_TOKEN` 与 `ALLOWED_USER_IDS` 是否正确。
162+
- Codex 无输出：检查 `CODEX_COMMAND` 是否可执行，`CODEX_WORKDIR` 是否存在。
163+
- Markdown 报错：确认输出是否超长，已内置切片与转义，但极端字符流仍建议缩短上下文。
164+
- GitHub 创建仓库失败：检查 `GITHUB_TOKEN` scope 与账号配额。
165+
- MCP 调用失败：先 `/mcp tools <server>` 验证服务连通与工具列表。

0 commit comments

Comments
 (0)