[MD]
**TRAM — 终端里的开源 AI 开服智能体，让你的开服效率翻倍**
快速使用教程：
https://www.bilibili.com/video/BV13uojB6EwU/
项目开源地址：
https://github.com/Tram-ai/tram
---
## 产品概述
TRAM 是一款完全开源的 AI 开服智能体，它直接运行在你的终端中，像一位随时待命的资深工程师，帮助你理解服务器插件库、自动化繁琐任务、加速开发流程。无论你是个人开发者还是团队协作，TRAM 都能成为你最得力的 AI 诊断搭档。
TRAM 基于 [QwenCode](https://github.com/QwenLM/qwen-code) 和 [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) 二次开发，融合了两者的优势，采用 MIT 许可开源。核心代码使用 TypeScript 编写，以 npm workspaces 单体仓库管理，构建工具使用 esbuild，确保高效和可维护性。
## 核心理念：从被动回答到主动协作
不同于传统的 AI Agent，TRAM CLI 的设计理念是**主动协作**。它不仅能回答问题，更能直接在你的服务器环境中执行操作：读取文件、搜索插件、运行命令、编辑代码、主动修复报错、管理服务器——一切都在终端内完成。它不需要你复制粘贴代码，不需要你在不同窗口间切换，所有的交互都在同一个终端会话中自然流动。
这种设计理念的核心支撑就是 TRAM 的 **Skills 技能系统**，它让 TRAM 从一个通用 AI 变成了一个可以适应任意开发场景的专业助手。
## 快速上手
安装只需一行命令（需要 Node.js 20+）：
```bash
npm install -g @tram-ai/tram@latest
```
然后输入 `tram` 进入交互式对话，或使用无头模式：
```bash
tram -p "帮我开一个Paper核心的1.20.1服务器"
```
## 核心特性详解
### 一、终端原生体验
TRAM 使用 Ink（React for Terminal）构建了丰富的交互式终端 UI，支持：
- **语法高亮**的代码展示和 diff 预览
- **多会话管理**，可同时处理多个任务
- **主题定制**，适配不同终端配色方案
- **模糊搜索**补全，快速定位文件、命令和 Skill
- **流式输出**，AI 响应实时呈现，无需等待完整生成
### 二、双模式运行
| 模式 | 启动方式 | 适用场景 |
|------|----------|----------|
| 交互模式 | `tram` | 日常开服、错误修复、服务器管理 |
| 无头模式 | `tram -p "问题"` | CI/CD 集成、脚本调用、批量处理 |
无头模式让 TRAM 可以无缝嵌入你的自动化工作流，例如 Git hooks、CI 流水线中的自动代码审查。
### 三、多模型支持
TRAM 不绑定单一 AI 供应商，支持主流的 LLM 后端：
- **OpenAI** — GPT-5 / GPT-5-Codex系列
- **Anthropic** — Claude 4.8 Sonnet / Claude 4.8 Opus
- **Google Gemini** — Gemini 3.5 Pro / Gemini 3.5 Flash
- 支持通过配置扩展自定义模型
你可以根据任务需求选择不同模型：复杂代码重构用更强的模型，简单问答用更快更便宜的模型。
### 四、丰富的内置工具
TRAM 内置约 90 种工具，涵盖开发全流程：
**代码理解**
- `glob` / `grep_search` — 快速定位文件和搜索代码
- `read_file` — 读取文件内容
- `tree-sitter` 解析 — 理解代码的 AST 结构
- **LSP 集成** — 利用 Language Server Protocol 实现跳转定义、查找引用
**文件操作**
- `write_file` / `edit` — 创建和编辑文件
- `edit` 支持精确的字符串替换和 diff 应用
**Shell 执行**
- `run_shell_command` — 在沙箱或本地执行命令
- 支持 Docker/Podman 沙箱隔离
**Web 与网络**
- `web_fetch` — 抓取网页内容
- `web_search` — 联网搜索
**媒体处理**
- OCR 图片文字识别
- 视频转音频
- 图片分析
**工程化**
- Git 操作集成
- Cron 定时任务
- MCP 客户端（Model Context Protocol）
### 五、Skills 技能系统（核心亮点）
Skills 是 TRAM 区别于其他开服工具的最大特色。与工具的"单一操作"不同，Skill 是一个**可复用的领域知识包**——本质上是一份带结构化元数据的 Markdown 文档，它教会模型"如何完成一类特定任务"。
#### Skill 的文件结构
每个 Skill 是一个目录，包含一个 `SKILL.md` 文件：
```
.tram/skills/review/SKILL.md
```
```markdown
---
name: review
description: 审查命令变更的正确性、安全性、操作质量和性能
argument-hint: '[pr-number|file-path] [--comment]'
allowedTools:
- task
- run_shell_command
- grep_search
- read_file
- write_file
- edit
- glob
when_to_use: 当用户要求审查代码变更或 PR 时使用
disable-model-invocation: false
paths:
- 'src/**/*.ts'
---
# 命令审查工作流
当你被要求审查代码时，请按以下步骤执行：
1. 先获取变更的文件列表（git diff --stat）
2. 逐文件审查，重点关注：
- 安全性问题（SQL 注入、XSS、敏感信息泄露）
- 性能问题（不必要的循环、内存泄漏）
- 代码质量问题（重复代码、不符合项目规范）
3. 对每个问题给出修改建议
4. 汇总输出审查报告
```
#### Skill 的四种加载来源（优先级从高到低）
| 级别 | 路径 | 说明 |
|------|------|------|
| **project** | `.tram/skills/<name>/SKILL.md` | 项目特有，纳入版本控制，团队共享 |
| **user** | `~/.tram/skills/<name>/SKILL.md` | 用户全局，所有项目可用 |
| **extension** | 扩展提供 | 安装的 TRAM 扩展注入 |
| **bundled** | 内置在 packages/core 中 | 随 TRAM 发行，开箱即用 |
同名 Skill 高优先级覆盖低优先级，让你可以灵活定制内置 Skill 的行为。
#### Skill 的三种调用方式
**1. 模型自动调用** — TRAM 在系统提示中嵌入可用 Skill 列表，模型识别到匹配场景时自动调用：
```
skill("review")
```
**2. 用户斜杠命令** — 每个 Skill 自动注册为斜杠命令：
```
/review # 触发代码审查
/skills # 列出所有 Skill（支持模糊搜索）
```
**3. 文件路径条件触发** — Skill 设置 `paths` 字段后，当模型访问匹配路径的文件时自动激活：
```yaml
paths:
- 'src/**/*.ts'
```
此时系统会提醒模型："以下 Skill 已基于你访问的文件激活，可通过 Skill 工具使用..."
#### Skill Hooks（生命周期钩子）
高级用户可以在 Skill 中注册钩子，在 Agent 执行的不同阶段触发自定义行为：
```yaml
hooks:
PreToolUse:
- matcher: 'git *'
hooks:
- type: command
command: 'echo "检测到 Git 操作，开始记录..."'
PostToolUse:
- matcher: 'write_file'
hooks:
- type: command
command: 'npm run lint -- --fix {file}'
UserPromptSubmit:
- type: http
url: 'http://localhost:3000/log'
method: POST
```
支持的事件类型：`PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 等，钩子类型支持 `command`（执行命令）和 `http`（发送 HTTP 请求）。
#### Skill 应用场景示例
- **代码审查**：自动审查 PR 变更，检查安全性、性能、代码规范
- **批量重构**：按指定规则批量重命名、提取函数、拆分文件
- **项目初始化**：按团队规范初始化新项目结构
- **部署验证**：检查部署配置的正确性
- **Minecraft 服务器管理**：管理 Mod、配置服务器核心、诊断问题
- **技术文档生成**：从代码自动生成 API 文档
### 六、多平台消息通道
TRAM 不只是终端工具，还可以作为 Bot 接入各类消息平台：
| 通道 | 功能 |
|------|------|
| **Telegram** | 通过 Telegram Bot 与 TRAM 交互 |
| **微信** | 企业微信/个人微信集成 |
| **钉钉** | 钉钉机器人接入 |
| **WebSocket** | 自定义 WebSocket 连接 |
| **SSE** | Server-Sent Events 实时推送 |
通道采用插件化架构，基于统一的 `ChannelBase` 基类开发，你可以轻松编写自定义通道插件。
### 七、多语言 SDK
- **TypeScript SDK**（`@tram-ai/sdk`）— 提供 `query()` 函数流式获取 AI 响应
- **Python SDK** — 实验性支持，通过 `stream-json` 协议通信
- **Java SDK** — 支持 Java 项目集成
### 八、知识驱动
TRAM 内置了基于 RAG（检索增强生成）的知识库系统。`knowledge/` 目录包含 26 个 Markdown 文件，涵盖开发技能、工具使用指南、Minecraft 运维等领域。当模型需要执行特定任务时，可以通过知识搜索（支持全文搜索和向量搜索）自动检索相关知识，确保即使面对不熟悉的任务也能给出专业级回答。
## 技术架构
```
┌────────────────────────────────────────────┐
│ packages/cli (终端 UI) │
│ Ink + React 19 + yargs + i18n │
├────────────────────────────────────────────┤
│ packages/core (引擎层) │
│ AI 客户端 | 工具注册表 | Agent 运行时 │
│ 配置文件 | 内存持久化 | 提示词管理 │
│ MCP 协议 | 遥测 | Skills 管理器 │
├──────────┬──────────┬──────────────────────┤
│ 通道插件 │ IDE 扩展 │ SDK │
│ Telegram │ VS Code │ TypeScript │
│ 微信/钉钉 │ Zed │ Python / Java │
│ WebSocket │ │ │
└──────────┴──────────┴──────────────────────┘
```
核心引擎 `packages/core` 包含了所有 AI 编排逻辑、工具执行、Agent 运行时和配置管理。`packages/cli` 基于 Ink（React for Terminal）构建了丰富的交互式终端界面。通道层采用插件化架构，可以无缝接入任意消息平台。
## 适用人群
- **个人开发者** — 加速日常插件编写、代码审查、问题排查
- **技术团队** — 统一开发规范、自动化代码审查、新人 onboarding
- **Minecraft开服小白** — 一句话开服并自动诊断，提供修复服务器报错的解决方案
- **开源项目维护者** — 批量处理 Issue、自动 PR 审查
## 开源与社区
- **许可证**：MIT
- **源码**：GitHub https://github.com/Tram-ai/tram
- **贡献指南**：欢迎提交 Issue 和 PR
TRAM 是完全开源的项目，我们相信 AI 开服工具应该属于每一个开发者，不受限于闭源产品的功能边界和定价策略。无论你是想贡献代码、报告 Bug、还是提出新特性，都可以在 GitHub 仓库中参与进来。[/MD]
