1. 项目定位与用途
cli-gateway 是一个独立运行的网关服务，定位为聊天平台与 ACP 兼容 AI 编码代理之间的桥梁。它允许用户通过 Discord、Telegram 或飞书等聊天界面与 AI 代理（如 Codex、Claude、Gemini）进行交互，实现编程协作。核心用途是协议转换与会话管理，将聊天消息转换为 ACP 协议请求，并将代理响应回译为聊天消息，从而让用户在不离开聊天环境的情况下使用强大的 AI 编码能力。
项目档案命令行工具
cli-gateway：聊天平台与ACP AI代理网关服务，支持Discord/Telegram/飞书，含调度器与进程守护
cli-gateway 是一个独立网关服务，让你通过 Discord、Telegram 或飞书聊天界面与 ACP 兼容的 AI 编码代理（如 Codex/Claude/Gemini）交互。它实现协议转换、会话隔离、并发管理，并内置 cron 调度器执行定时任务。本页提供项目介绍、安装指南、使用说明及技术架构解析。
AI 总结
cli-gateway 是一个独立网关服务，将 Discord、Telegram、飞书等聊天平台连接至 ACP 兼容的 AI 编码代理，实现协议转换、会话隔离、并发处理与定时任务调度，让团队通过熟悉聊天界面协作编程。
中文项目介绍
cli-gateway 是一个独立运行的网关服务，作为聊天平台（Discord、Telegram、飞书）与 ACP 兼容的 AI 编码代理（如 Codex、Claude、Gemini）之间的桥梁。它允许用户通过熟悉的聊天界面与 AI 代理交互，进行编程协作。
项目解决了多平台聊天工具与 AI 代理之间的协议转换问题，实现了会话隔离（每个对话绑定独立的 ACP stdio 代理进程以避免交叉对话）和并发管理，同时提供了任务调度能力。
适用场景包括：团队在 Discord 或 Telegram 频道中共享 AI 编程助手；个人开发者通过聊天界面使用 ACP 代理进行编码；需要定时执行编码任务或提示的自动化场景。
技术特征上，cli-gateway 实现了 ACP stdio 传输（JSON-RPC 2.0 over 换行分隔的 JSON），支持客户端工具表面如 session/update 流式更新、session/request_permission、fs/read_text_file、fs/write_text_file 以及 terminal/* 操作。它使用 better-sqlite3 进行数据持久化，内置基于 node-cron 的调度器管理定时任务，并通过 run-guard.sh 提供进程守护、自动重启与更新机制。配置通过交互式向导生成并存储在 ~/.cli-gateway/config.json 中。
详细信息与使用说明
2. 解决的问题
项目主要解决三个问题：一是协议转换，将不同聊天平台的消息格式统一为 ACP 协议，并处理认证与事件订阅；二是会话隔离与并发，通过为每个对话绑定独立的 ACP stdio 代理进程，避免多用户对话间的交叉对话与状态污染，同时支持高并发；三是任务调度与持久化，内置 cron 调度器执行定时任务，并使用 SQLite 数据库存储会话历史、权限设置和任务配置，确保状态可恢复。
3. 适用场景
适用场景包括：团队在 Discord 或 Telegram 频道中共享 AI 编程助手，进行代码审查、调试或功能开发；个人开发者通过聊天界面快速使用 ACP 代理进行编码，无需本地配置复杂环境；需要定时执行编码任务或提示的场景，如定期代码检查、自动化脚本生成；以及希望将 AI 代理集成到现有工作流（如飞书通知）中的开发团队。目前 Feishu 为 webhook 模式 MVP，适合事件驱动集成。
4. 安装方式
安装需满足 Node.js >= 18 环境。提供两种方式：全局安装执行 npm i -g cli-gateway，安装后可直接使用 cli-gateway 命令；或使用 npx 直接运行 npx -y cli-gateway，无需全局安装。本地开发需运行 npm i 安装依赖，然后 npm run dev 启动。项目还提供进程守护脚本，可通过 npm run start:guard 启动带守护的服务，守护脚本支持自动更新、构建与重启。
5. 使用方式
启动服务后，在支持的聊天频道中使用斜杠命令与代理交互。关键命令包括：/new 开启新会话；/allow 和 /deny 处理权限请求；/whitelist 管理工具权限白名单；/cron 管理定时任务（help/list/add/del/enable/disable）；/last 查看上次输出；/replay 重放历史运行；/ui 设置 UI 详细程度；/cli 切换 ACP CLI 预设。配置通过首次运行交互式生成的 ~/.cli-gateway/config.json 文件管理，可编辑代理命令、令牌等参数。
6. 实现特点与架构
架构上，项目分为多个模块：ACP 协议实现层处理 stdio 传输与 JSON-RPC 2.0 消息；频道适配层集成 Discord、Telegram、飞书平台；网关核心层管理会话路由、权限验证与历史记录；调度器层基于 node-cron 管理定时任务；工具层封装文件与终端操作；数据层使用 better-sqlite3 持久化。每个对话绑定独立代理进程确保隔离，进程守护脚本 run-guard.sh 提供崩溃保护、指数退避重启、生命周期控制，并支持沙箱环境重启桥接。配置已弃用环境变量，统一使用 JSON 配置文件。
思维导图
cli-gateway
ACP 协议实现
stdio 传输
JSON-RPC 2.0
session/update 流式
工具调用表面
频道适配器
Discord
Telegram
Feishu (webhook)
网关核心
会话路由
权限管理
历史记录
绑定运行时
调度器
cron 任务
模板引擎
工具与工作区
文件操作
终端操作
数据存储
SQLite (better-sqlite3)
会话存储
任务存储
进程守护
run-guard.sh
自动重启
生命周期管理
重启观察器
常见问题
如何安装 cli-gateway？
需要 Node.js >= 18 环境。可通过 npm i -g cli-gateway 全局安装，或使用 npx -y cli-gateway 直接运行无需安装。本地开发需运行 npm i 安装依赖。
支持哪些聊天平台？
目前支持 Discord、Telegram 和飞书（webhook 事件订阅模式，MVP）。每个平台通过专用适配器集成，统一由网关核心管理。
如何配置 ACP 代理？
首次运行会交互式生成配置文件 ~/.cli-gateway/config.json。可编辑该文件设置代理命令、API 令牌、默认参数等。详细配置选项参考 skills.md 文件。
如何保证服务稳定运行？
提供 run-guard.sh 进程守护脚本，支持自动重启、指数退避、更新构建和生命周期管理。可通过 npm run start:guard 启动，或使用 bash scripts/run-guard.sh 系列命令控制重启、停止、查看状态与日志。
有哪些可用的聊天命令？
包括 /new 开启新会话、/allow 和 /deny 处理权限、/whitelist 管理工具白名单、/cron 管理定时任务、/last 查看输出、/replay 重放历史、/ui 设置详细程度、/cli 切换代理预设等。具体用法可通过 /help 查看。