OpenRouter 自定义 Agent TUI：create-agent-tui 脚手架完整指南
create-agent-tui 是 OpenRouter 官方提供的 Agent TUI 脚手架 skill，类似 create-react-app 但面向终端 agent。安装后，只需描述你想要的 agent，即可生成完整的 TypeScript 项目，使用 @openrouter/agent SDK 处理模型调用、工具执行、多轮循环和 stop conditions。支持工具显示（grouped/emoji/minimal）、输入框（block/bordered/plain）、加载动画等多种视觉风格，以及从文件系统工具到自定义领域工具的丰富预设选项。
create-agent-tui 是 OpenRouter 提供的 agent TUI 脚手架 skill，让你通过描述意图快速生成完整的终端 agent 项目。
核心能力：@openrouter/agent SDK 处理内层循环（模型调用、工具执行、stop conditions），脚手架提供配置、工具定义、会话管理和入口点等外围代码。
何时需要自定义 Agent TUI
以下场景适合使用此脚手架：
- 定制 UI：需要特定视觉风格或品牌化的终端界面
- 自定义工具：agent 需要与你自己的 API、数据库或领域系统交互
- 控制循环逻辑：需要自定义 stop conditions、审批流程、成本上限或模型选择逻辑
- 作为产品发布：agent 是应用的一部分，而非开发工具，需要掌控入口点
- 学习：了解工具执行层面的 agent 工作原理
如果你已在使用 Claude Code、Codex CLI 或 Cursor 且不需要定制，则不需要此 skill——这些都是成熟的生产级 agent TUI。
安装 Skill
npx skills add OpenRouterTeam/skills支持任何兼容 Agent Skills 的 agent（Claude Code、Cursor 等）。安装后，向 agent 描述你想要的功能，skill 自动激活。
工作原理
Skill 向你的编程 agent 展示一个交互式清单，包含工具、模块、视觉风格和斜杠命令。选择所需选项，agent 自动生成可运行的完整项目：
npm start@openrouter/agent SDK 负责处理
| 关注点 | SDK 如何处理 |
|---|---|
| 模型调用 | client.callModel() — 一次调用，任意 OpenRouter 模型 |
| 工具执行 | 用 tool() 和 Zod schema 定义工具，SDK 验证输入并调用 execute 函数 |
| 多轮循环 | SDK 循环执行（调用模型 → 执行工具 → 调用模型），直到 stop condition 触发 |
| Stop Conditions | stepCountIs(n)、maxCost(amount)、hasToolCall(name) 或自定义函数 |
| Streaming | result.getTextStream() 获取文本增量，result.getToolCallsStream() 获取工具调用 |
| 成本追踪 | result.getResponse().usage 包含输入/输出 token 数 |
| 共享上下文 | 通过 sharedContextSchema 在工具间传递类型安全的共享状态 |
视觉定制
工具显示风格
| 风格 | 说明 |
|---|---|
grouped（默认） |
粗体操作标签 + 树形分支输出，连续同类调用合并显示 |
emoji |
每次调用带标记、工具名、参数和耗时 |
minimal |
汇总单行摘要，在输出文本时刷新 |
hidden |
完全隐藏工具输出 |
| 自定义 | 描述你想要的风格，skill 实现 |
通过 display.toolDisplay 配置或 --tool-display 命令行参数设置。
输入框风格
| 风格 | 说明 |
|---|---|
block（默认） |
全宽背景色输入框，自适应终端色彩方案（OSC 11 背景检测） |
bordered |
上下横线边框，兼容任何终端 |
plain |
简单 > readline 提示符，无转义序列 |
| 自定义 | 描述你想要的风格，skill 实现 |
通过 display.inputStyle 或 --input 设置。
加载动画
| 风格 | 说明 |
|---|---|
gradient（默认） |
滚动色彩渐变 shimmer |
spinner |
盲文点阵旋转动画（⠋⠙⠹…） |
minimal |
追加省略号（Working···） |
| 自定义 | 描述动画，skill 实现 |
通过 display.loader.style 和 display.loader.text 配置。
ASCII Banner
启用 showBanner 或传入 --banner "你的 Agent 名" 在启动时显示大字母 ASCII 艺术 logo，使用 █ 字符，自动适配 60 列终端宽度。
生成的项目结构
生成后运行：
export OPENROUTER_API_KEY="sk-or-..."
npm start覆盖视觉风格：
npm start -- --banner "Acme Bot" --model anthropic/claude-sonnet-4 --input bordered --tool-display emoji可定制选项
服务端工具（OpenRouter 服务端执行，零客户端代码）
| 工具 | 默认 | 说明 |
|---|---|---|
| Web Search | 开启 | 实时网络搜索（openrouter:web_search） |
| Datetime | 开启 | 当前日期时间（openrouter:datetime） |
| Image Generation | 关闭 | 图像生成（openrouter:image_generation） |
用户定义工具（生成到 src/tools/）
| 工具 | 默认 | 说明 |
|---|---|---|
| File Read | 开启 | 读取文件，支持 offset/limit，自动检测图像 |
| File Write | 开启 | 写入/创建文件，自动创建目录 |
| File Edit | 开启 | 搜索替换，输出 diff |
| Glob/Find | 开启 | 按 glob 模式查找文件 |
| Grep/Search | 开启 | 按正则搜索文件内容 |
| Directory List | 开启 | 列出目录条目 |
| Shell/Bash | 开启 | 执行命令（含超时） |
| JS REPL | 关闭 | 持久化 Node.js 环境 |
| Sub-agent Spawn | 关闭 | 委派任务给子 agent |
| Plan/Todo | 关闭 | 追踪多步任务进度 |
| Request User Input | 关闭 | 向用户提结构化问题 |
| Web Fetch | 关闭 | 抓取 URL 文本内容 |
| View Image | 关闭 | 读取本地图像为 base64 |
| Custom Tool Template | 开启 | 领域专属工具空骨架 |
Harness 模块
| 模块 | 默认 | 说明 |
|---|---|---|
| Session Persistence | 开启 | JSONL 追加追加式对话日志 |
| Context Compaction | 关闭 | 上下文变长时摘要旧消息 |
| System Prompt Composition | 关闭 | 从静态+动态上下文文件构建指令 |
| Tool Permissions / Approval | 关闭 | 危险工具需用户确认 |
| Structured Event Logging | 关闭 | 发送工具调用、API 请求、错误事件 |
@ File References |
关闭 | @filename 将文件内容附加到下一条消息 |
! Shell Shortcut |
关闭 | !command 运行 shell 并注入输出到上下文 |
| Multi-line Input | 关闭 | Shift+Enter 多行输入（需要 raw terminal 模式） |
| ASCII Logo Banner | 关闭 | 启动时显示自定义 ASCII 艺术 logo |
斜杠命令（生成到 src/commands.ts）
| 命令 | 默认 | 说明 |
|---|---|---|
/model |
开启 | 通过 OpenRouter API 切换模型 |
/new |
开启 | 开始新对话 |
/help |
开启 | 列出可用命令 |
/compact |
关闭 | 手动触发上下文压缩 |
/session |
关闭 | 显示会话元数据和 token 用量 |
/export |
关闭 | 保存对话为 Markdown |
入口点
默认生成 CLI REPL，也可以要求：
- HTTP API 服务器：Express/Hono 服务器 + SSE streaming，用于构建 web 可访问的 agent
- 二者都要：CLI 用于开发，服务器用于生产
常见问题
Q: 生成的项目需要手动维护吗？
A: 生成后的项目完全属于你，你可以直接编辑源码。Skill 只是初始化，之后的所有改动都是正常的 TypeScript 开发工作。如果需要添加新工具或功能，可以再次运行 skill 或手动修改 src/tools/ 中的文件。
Q: @openrouter/agent SDK 和直接调用 OpenRouter API 有什么区别？
A: SDK 封装了 agent 循环的样板代码——你不需要手动管理"调用模型 → 执行工具 → 再调用模型"的循环逻辑、工具参数验证、stop condition 检测等。直接调用 API 适合单次请求场景；SDK 适合需要多步工具使用的 agent 场景。
Q: 生成的 agent 支持 streaming 输出吗？
A: 是的。@openrouter/agent SDK 原生支持 streaming，通过 result.getTextStream() 获取文本增量流，通过 result.getToolCallsStream() 获取工具调用流，默认 TUI 已集成流式输出。