ai-cli-online
v3.0.6
Published
AI-Cli Online - Web Terminal for Claude Code via xterm.js + tmux
Maintainers
huacheng99Readme
AI-Cli Online
在浏览器中运行的 AI 开发环境。持久化终端会话、结构化任务生命周期、自主执行 — 单个 Node.js 进程即可运行。
专为在不稳定网络下运行 Claude Code、Codex CLI、Gemini CLI 或任意 AI CLI 而构建。tmux 保证断网后进程存活；浏览器 UI 在终端旁提供规划、批注和对话面板。
npm: https://www.npmjs.com/package/ai-cli-online | GitHub: https://github.com/huacheng/ai-cli-online
核心能力
终端 + 规划 + 执行，一屏完成：
┌─ 标签页 ────────────────────────────────────────────────────┐
│ ┌─ Plan 面板 ──────┬─ 终端 ─────────────────────────────┐ │
│ │ AiTasks/ 文件浏览 │ │ │
│ │ Markdown 查看器 │ $ /ai-cli-task auto my-feature │ │
│ │ 内联批注 │ ▶ 规划中... │ │
│ │ (插入/删除/ │ ▶ 检查(post-plan): 通过 │ │
│ │ 替换/评注) │ ▶ 执行步骤 1/4... │ │
│ │ │ ▶ 执行步骤 2/4... │ │
│ │ Mermaid 图表 │ ... │ │
│ │ ├────────────────────────────────────┤ │
│ │ │ Chat 编辑器 │ │
│ │ │ 多行 Markdown + /命令 │ │
│ └───────────────────┴────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘- Plan 面板 — 浏览
AiTasks/文件，4 种批注类型标注文档，向 AI 发送结构化反馈 - 终端 — 完整 xterm.js + WebGL 渲染，二进制协议实现超低延迟
- Chat 编辑器 — 多行 Markdown 编辑器，斜杠命令，草稿服务端持久化
- 三个面板可同时打开，各自独立调整大小
AI 任务生命周期
ai-cli-task 插件提供 8 个 skill 的完整任务执行生命周期：
init → plan → check → exec → check → merge → report
↑ ↓
re-plan ←──┘ (遇到问题时)| Skill | 功能 |
|-------|------|
| init | 创建任务模块 (AiTasks/<name>/)，git 分支，可选 worktree |
| plan | 生成实施计划或处理人工批注 |
| check | 在 3 个检查点评估可行性 (post-plan / mid-exec / post-exec) |
| exec | 逐步执行计划，每步验证 |
| merge | 合并任务分支到主干，冲突解决（最多 3 次重试） |
| report | 生成完成报告，提炼经验到知识库 |
| auto | 在单个 Claude 会话中自主运行完整生命周期 |
| cancel | 停止执行，设为已取消，可选清理 |
自主模式
/ai-cli-task auto my-feature一条命令触发完整生命周期。单个 Claude 会话在内部依次运行 plan → check → exec → merge → report，所有步骤共享上下文。守护进程通过 .auto-signal 文件监控进度，强制超时，检测停滞。
任务结构
AiTasks/
├── .index.json # 模块索引
├── .experiences/ # 跨任务知识库（按领域类型分类）
│ ├── .summary.md # 经验文件索引
│ └── <type>.md
├── .references/ # 外部参考资料（执行中收集）
│ ├── .summary.md # 参考文件索引
│ └── <topic>.md
└── my-feature/
├── .index.json # 状态、阶段、时间戳、依赖 (JSON)
├── .target.md # 需求描述（人工编写）
├── .summary.md # 浓缩上下文（防止上下文溢出）
├── .analysis/ # 评估历史
├── .test/ # 测试标准与结果
├── .bugfix/ # 问题历史
├── .notes/ # 研究发现
├── .report.md # 完成报告
└── .plan.md # 实施计划类型感知执行
任务按领域类型分类（software、dsp、ml、literary、science:physics 等）。每种类型会调整规划方法、执行工具和验证标准。已完成任务的经验存储在 .experiences/<type>.md 中，供同类型的后续任务参考。
终端特性
- 会话持久化 — tmux 保证断网后进程存活；固定 socket 路径，服务重启后自动重连
- Tab 多标签页 — 独立终端分组，布局跨刷新持久化
- 分屏布局 — 水平/垂直任意嵌套分割
- 二进制协议 — 1 字节前缀帧用于终端 I/O，TCP Nagle 禁用，WebSocket 压缩
- WebGL 渲染 — 吞吐量比 canvas 提升 3-10 倍
- 复制粘贴 — 鼠标选中自动复制，右键粘贴
- 滚动历史 — capture-pane 回看，保留 ANSI 颜色
- 文件传输 — 上传/下载文件，浏览目录，CWD 打包下载为 tar.gz
- 网络指示器 — 实时 RTT 延迟 + 信号条
- 自动重连 — 指数退避 + jitter 防雷群效应
批注系统
Plan 面板提供 4 种批注类型，用于向 AI 发送结构化反馈：
| 类型 | 图标 | 说明 |
|------|------|------|
| 插入 | + | 在指定位置添加内容 |
| 删除 | − | 标记待删除的文本 |
| 替换 | ↔ | 用新文本替换旧文本 |
| 评注 | ? | 提问或留下备注 |
批注双层持久化（localStorage + SQLite），以结构化 JSON 发送给 AI。plan skill 处理批注 — 按影响分级、应用变更、更新任务文件。
快速开始
方式一：npx 一键启动（推荐）
npx ai-cli-online方式二：全局安装
npm install -g ai-cli-online
ai-cli-online方式三：从源码运行
git clone https://github.com/huacheng/ai-cli-online.git
cd ai-cli-online
npm install
npm run build
npm start前提条件
- Node.js >= 18
- tmux 已安装（
sudo apt install tmux或brew install tmux）
配置
创建 server/.env：
PORT=3001 # 服务端口
HOST=0.0.0.0 # 绑定地址
AUTH_TOKEN=your-secret-token # 认证 Token（生产环境必须设置）
DEFAULT_WORKING_DIR=/home/user # 默认工作目录
HTTPS_ENABLED=true # nginx 反代时设为 false
TRUST_PROXY=1 # nginx 反代时设为 1完整选项参见 server/.env.example。
架构
浏览器 (xterm.js + WebGL)
├── Plan 面板 (批注编辑器)
├── Chat 编辑器 (Markdown + /命令)
└── 终端视图 (WebGL 渲染器)
│
↕ WebSocket binary/JSON + REST API
│
Express 服务 (Node.js)
├── WebSocket ↔ PTY relay
├── tmux 会话管理
├── 文件传输 API
├── SQLite (草稿、批注、设置)
└── 路由模块 (sessions, files, editor, settings)
│
↕ PTY / tmux sockets
│
tmux sessions → shell → Claude Code / AI agents
└── AiTasks/ 生命周期 (init/plan/check/exec/merge/report/auto)- 前端: React + Zustand + xterm.js (WebGL)
- 后端: Node.js + Express + node-pty + WebSocket + better-sqlite3
- 会话管理: tmux（持久化终端会话）
- 布局系统: Tab 标签页 + 递归分割树（LeafNode / SplitNode）
- 传输协议: 二进制帧（热路径）+ JSON（控制消息）
- 任务系统: 8-skill 插件，状态机 + 依赖门控 + 经验知识库
项目结构
ai-cli-online/
├── shared/ # 共享类型定义
├── server/src/
│ ├── index.ts # 主入口 (中间件 + 路由 + 服务)
│ ├── websocket.ts # WebSocket ↔ PTY relay (二进制 + JSON)
│ ├── tmux.ts # tmux 会话管理
│ ├── files.ts # 文件操作 + 路径校验
│ ├── pty.ts # node-pty 封装
│ ├── db.ts # SQLite 数据库
│ ├── auth.ts # 认证工具
│ ├── middleware/ # 认证中间件
│ └── routes/ # REST API 路由 (sessions, files, editor, settings)
├── web/src/
│ ├── App.tsx # 主应用 (登录 / TabBar / 终端 / 主题)
│ ├── store/ # Zustand 状态管理 (模块化切片)
│ ├── components/
│ │ ├── TerminalPane.tsx # 2D 网格布局 (Plan + 终端 + Chat)
│ │ ├── TerminalView.tsx # xterm.js 终端
│ │ ├── PlanPanel.tsx # Plan 批注面板
│ │ ├── PlanAnnotationRenderer.tsx # Markdown + 内联批注
│ │ ├── PlanFileBrowser.tsx # AiTasks/ 文件浏览器
│ │ ├── MarkdownEditor.tsx # Chat 编辑器
│ │ └── ...
│ ├── hooks/ # React Hooks (WebSocket, 文件流, resize 等)
│ └── api/ # 类型化 API 客户端模块
├── bin/ # npx 入口
├── start.sh # 生产启动脚本
└── install-service.sh # systemd + nginx 安装器开发
# 开发模式（前后端分离）
npm run dev
# 构建
npm run build
# 生产模式（构建 + 启动）
bash start.shsystemd 服务 + nginx 反向代理
sudo bash install-service.sh # 交互安装 (systemd + 可选 nginx 反代)
sudo systemctl start ai-cli-online # 启动服务
sudo journalctl -u ai-cli-online -f # 查看日志安装脚本会：
- 创建 systemd 服务，支持开机自启和进程管理
- 检测 nginx 并可选配置反向代理（WebSocket 支持、SSL、
client_max_body_size） - nginx 启用时自动设置
HTTPS_ENABLED=false和TRUST_PROXY=1
安全
- Token 认证 + timing-safe 比较
- 所有文件操作的 symlink 穿越防护
- 未认证 WebSocket 连接限制
- TOCTOU 下载防护（流式大小检查）
- CSP Headers (frame-ancestors, base-uri, form-action)
- 限速（可配置读/写阈值）
License
MIT