这阵子我几乎一整天都泡在终端里，Claude Code Mods 这个词反复出现。别人问起时，我最短的解释是：它是挂在 Claude Code 这个命令行助手上的扩展模块，目的就两件事——第一，给 Claude 加工具、加命令，让它能调用真正项目里那些私有脚本和本地能力；第二，让 Claude 输出不再只是干巴巴的文本，而是能在终端里画出一个实时刷新、带颜色、带边框、能拨动状态的界面。前几周我在自己的项目里把这套玩法完整跑了一遍，踩了不少坑，也沉淀出一套比较稳的写法。这篇想把概念、环境、代码实现和避坑经验一次说清楚。
1. 概念拆解：Mods 到底扮演了什么角色
1.1 为什么一个“对话助手”还需要一层额外的工具
先聊一个基础事实：Claude Code 本身已经能读文件、改代码、跑测试、执行 Git 操作。但这些能力大多是内置的、固定的。真实工程里永远会有一些它完全不知道的东西，比如你公司内部的构建脚本、运维命令、数据同步工具、带业务规则的状态机逻辑。没有扩展机制的时候，你只能把命令复制进对话里，让 Claude 照着说明去调用。这样做有三个痛点：一是对话历史会越拖越长；二是指令格式一旦变化，Claude 可能理解错；三是每次换一台机器、换一个仓库，都要把同样的上下文重新喂一遍。
Mods 的思路就是把“系统外能力”注册成 Claude 能识别的命令或工具，让 Claude 知道某个名字对应哪个脚本、需要哪些参数、输出什么格式。等于给助手加了一条清晰的“通信协议”。这是它和普通插件最大的区别：Mods 面向的不是浏览器也不是 IDE，而是命令行会话本身的运行环境。
1.2 Mods 扩展的四种能力边界
按我自己的使用经验，Mods 解决的能力场景大致可以分成四类：
| 能力类型 | 具体表现 | 典型例子 |
|---|---|---|
| 工具执行 | 让 Claude 调用本地脚本或外部程序 | 跑一个打包脚本、同步资源文件 |
| 命令入口 | 给 Mod 定义一套参数，像 CLI 一样被调用 | my-mod --env=prod --dry-run |
| 终端界面 | 在终端里渲染动态 UI，支持刷新和响应 | 仓库状态仪表盘、部署进度面板 |
| 工作流编排 | 把多个工具串起来，做多步骤自动化 | 提交前检查、发布前回归清单 |
表格里最后一项经常被忽略。很多人以为 Mods 只是“给 Claude 加一个工具”，其实 Mod 之间也能互相组合。一个 Mod 拉取数据，另一个 Mod 做校验，第三个 Mod 负责把结果渲染成界面，整条链路可以在 Claude 一次对话里完成。这种可组合性，比单点工具更有想象力。
1.3 “在终端画界面”是怎么做到的
“画界面”这三个字很容易让人想到 GUI，但终端里压根没有窗口级组件库，也没有像素坐标。它靠的是 ANSI 转义序列、光标定位、颜色代码、备用屏幕缓冲区这几个底层能力。
- ANSI 颜色：
\x1b[32m设置前景色，\x1b[0m复位。 - 光标控制：
\x1b[H回到左上角，\x1b[2J清屏。 - 备用屏幕：
tput smcup进入“独立显示区”，退出时rmcup恢复原界面。 - 定时刷新：脚本按固定间隔重新渲染，形成“动态感”。
所以在 Mods 场景里，终端 UI 其实是一封一封“给终端打的电报”。一个成熟的 Mod，通常有两种运行姿态：一次性输出型，跑完就给结果；常驻界面型，启动后接管终端区域，直到你按q退出。这两种姿态对应完全不同的代码写法，写之前得先想清楚。
2. 动手前准备：环境、约定与 Mods 的组织形式
2.1 安装与前置依赖
开始写 Mods 之前，先确保 Claude Code 已经能在当前环境正常运行。常见的安装方式是通过包管理器或者官方脚本，具体命令以对应版本的文档为准。我自己的环境要求是：
- Node.js 18 或更高版本，大多数 Mod 运行在这个运行时上；
- Git 已经安装并可以无交互调用；
- 终端支持 ANSI 转义（macOS 自带终端、Windows Terminal 等基本都没问题）。
鉴权方面，进入 Claude Code 后会提示登录或配置访问密钥。每个项目第一次使用时会询问是否授予文件读写权限，建议先允许并记住授权，否则调 Mod 的过程中老是弹确认框，体验会碎掉。
2.2 一个在社区里很常见的目录约定
Mods 没有特别强制的目录结构，但社区里流行一种约定：在项目根目录下建claude-code-mods文件夹，或者mods文件夹，里面放每个 Mod 的独立子目录。同时维护一份清单文件，把名字、入口、描述、参数说明登记进去。
{ "mods": [ { "name": "status-dashboard", "description": "显示当前仓库的分支、未提交文件数和待推送提交数", "command": "node ./mods/status-dashboard/index.js" } ] }这里有个细节：description不是给人看的备注，它会被 Claude 当成功能接口说明。写得越清楚，Claude 就越知道什么时候调它、怎么调、输出长什么样。你可以把这段描述理解成“给 AI 看的 API 文档”。具体字段名称可能随版本变化，但“描述驱动调用”的原理是通用的。
2.3 三类 Mods：一次性脚本、带参数命令、交互式界面
我建议把 Mods 分成三类看待，写起来思路会清晰很多。
第一类是“一次性脚本型”。它做一件事，输出结果后立即退出。比如统计某目录下代码行数、检查依赖版本是否过期。这类 Mod 最容易被 Claude 正确调用，因为输入输出都非常短。
第二类是“带参数命令型”。它像一个小型 CLI，支持--env、--dry-run、--output之类的参数。Claude 会根据对话内容生成合理的参数组合，再调用命令。这就要求 Mod 本身要有参数解析逻辑，并且对非法参数能给出友好报错。
第三类是“交互式界面型”。它启动后不会立即退出，而是常驻终端，渲染一个带刷新逻辑的界面，等待用户按键操作。这一类对代码结构的要求最高，也是“在终端画界面”最集中的体现。别一上来就写第三种，先从前两种练手。
3. 实战：从零写一个终端界面 Mod
3.1 目标选定与信息结构
我选一个很常见的场景：仓库状态仪表盘。目标是在终端里显示四条信息：
- 当前分支名；
- 工作区里有多少个改动文件；
- 本地分支比远端领先多少提交；
- 最近一次提交的信息。
这个例子足够简单，但已经覆盖了“数据提取 + 界面渲染 + 命令行参数”三块核心。我先把数据提取写成一个独立脚本，后面单独写渲染层，让两层可以独立测试。
3.2 先做数据层，再想界面长什么样
很多人写界面第一步就开画框，结果数据一变，布局跟着崩。正确做法是先把“数据长什么样”定下来。我写了一个 Node 脚本，只负责收集 Git 状态，输出成 JSON：
#!/usr/bin/env node const { execSync } = require('child_process'); function run(cmd) { try { return execSync(cmd, { encoding: 'utf8' }).trim(); } catch { return ''; } } const branch = run('git branch --show-current'); const ahead = run('git rev-list --count @{u}..HEAD'); const statusLines = run('git status --porcelain') .split('\n') .filter((line) => line.trim().length > 0); const lastLog = run('git log -1 --pretty=format:"%h %s"'); const data = { branch: branch || 'detached HEAD', ahead: ahead ? Number(ahead) : 0, dirtyCount: statusLines.length, lastLog: lastLog || '(no commits yet)' }; console.log(JSON.stringify(data, null, 2));把这个脚本存成mods/status-dashboard/collect.js，直接在终端跑一遍，先确认数据没有错。这里有一个很实用的设计思路：数据层永远输出纯 JSON，不要混入任何颜色或排版字符。因为 Claude 在阅读输出时，越干净的结构化数据越容易理解；而人类想看的是漂亮界面，那属于渲染层的工作。
3.3 渲染层：用 ANSI 转义画出一个像样界面
我新建一个render.js，它不重新采集数据，而是读取collect.js的输出，然后负责排版。这样调试时我可以反复跑render.js而不影响真实 Git 仓库。
#!/usr/bin/env node const { execFileSync } = require('child_process'); const data = JSON.parse( execFileSync('node', ['./mods/status-dashboard/collect.js'], { encoding: 'utf8' }) ); const C = { green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', cyan: '\x1b[36m', reset: '\x1b[0m', bold: '\x1b[1m' }; const width = process.stdout.columns || 80; const line = '─'.repeat(Math.max(0, width - 2)); console.log(`${C.bold}${C.cyan}┌${line}┐${C.reset}`); console.log(`${C.bold}${C.cyan}│${C.reset} ${C.green}${data.branch}${C.reset}`); console.log(`${C.bold}${C.cyan}│${C.reset} 改动文件: ${data.dirtyCount > 0 ? C.yellow + data.dirtyCount + C.reset : C.green + '0' + C.reset}`); console.log(`${C.bold}${C.cyan}│${C.reset} 领先远端: ${data.ahead > 0 ? C.red + data.ahead + ' commits' + C.reset : C.green + '0' + C.reset}`); console.log(`${C.bold}${C.cyan}│${C.reset} 最近提交: ${C.yellow}${data.lastLog}${C.reset}`); console.log(`${C.bold}${C.cyan}└${line}┘${C.reset}`);整体效果是一个用方框字符围起来的简洁信息面板。字段颜色规则我做了硬编码：分支名绿色，改动文件和领先条数则根据数值变色。这种颜色规则不复杂，但已经足够让 Claude 在汇报时不用再自己造颜色。
3.4 让 Claude 学会调用这个 Mod
文件写好了，还要在清单文件里登记，并且要把“输出示例”写进描述里。我的做法是跑一次collect.js，把一条真实 JSON 输出贴到 description 中：
{ "name": "status-dashboard", "description": "读取当前 Git 仓库状态，返回 JSON，包含分支名、改动文件数、领先远端提交数与最近提交信息。示例输出: {\"branch\":\"feature/x\",\"ahead\":2,\"dirtyCount\":5,\"lastLog\":\"a1b2c3d fix: optimize cache\"}", "command": "node ./claude-code-mods/status-dashboard/collect.js" }这里命令我故意指向collect.js，因为 Claude 最需要的其实还是那个结构化的 JSON。等到我要给另一个开发者演示“终端画界面”时，才建议他跑render.js。也就是说，Claude Code 和终端 UI 之间应该有一道很明确的边界：Claude 默认取数据，界面是给人看的。
之后在 Claude Code 会话里说一句“看一下当前仓库状态”，它就会读取描述、执行命令，并把返回的 JSON 翻译成自然语言。如果说出“打开仪表盘界面”，我通常会追加一个前缀命令来启动渲染脚本，让它接管终端区域。
4. 终端 UI 绘制的进阶技巧与常见翻车点
4.1 设计终端界面的四条原则
第一个原则是“数据层和渲染层严格分离”。上面示例已经示范了这一点。数据层应该像 API 一样稳定，渲染层则可以随意换风格。
第二个原则是“永远准备纯文本出口”。不要在渲染层里把全部输出都画成框，要预留一个--json或者--plain参数。因为日志要进 CI、要进剪贴板、要发给别人，不是所有场景都适合 ANSI 彩色界面。
第三个原则是“默认宽度优先，不要追求华丽”。终端宽度可能只有 80 列，也可能有 150 列。如果代码里硬编码上线宽度，一旦终端变小就会出现折行和错位。我一般用process.stdout.columns拿实时列数，再动态计算边框长度。
第四个原则是“刷新时只更新变化区域”。不要每次整屏清空重新打一遍，那会引发严重闪烁。能定位到局部坐标更新的，就只更新那一行。终端最低层的开销远高于渲染层的假设，在很多地方都成立。
4.2 中文和字符宽度是最大暗坑
终端界面里，最让我头疼的不是颜色，而是中文字宽。一个英文字符占 1 列宽度，但中文、日文、韩文这类全角字符占 2 列。如果画框的时候用字符串.length计算宽度，中文数据一进来，边框就会对不齐。
解决思路是不要用length，要按“显示宽度”计算。Node 侧可以借用wcwidth这类工具库，或者用Intl.Segmenter配合正则做粗略估算。最稳妥的做法是：凡是要放进固定宽度面板的文本，先按显示宽度截断，超长部分用省略号代替。
另一个坑是中文终端里的换行符。某些终端在行尾遇到全角字符时，即使总宽度已经刚好，也可能自动折行。遇到这种情况，建议在绘制前先做尾部硬空格填充，宁可让行尾多一个空格，也不要让它折行。
4.3 刷新、隐藏光标和备用屏幕
如果界面需要“实时刷新”，需要三件事同时做好。
第一是进入备用屏幕。用tput smcup切换到一个不干扰原始终端内容的显示区，退出时用tput rmcup恢复。这样界面退出后，之前的命令记录还在，不会在屏幕下方残留一堆重绘痕迹。如果没进备用屏幕，界面退出后整个终端历史全被污染，非常难看。
第二是隐藏光标。常驻界面刷新时，光标闪动会干扰视觉。用\x1b[?25l隐藏，退出时用\x1b[?25h恢复。
第三是定时器刷新。Node 里可以用setInterval，Go 里用time.Ticker，每 1 到 2 秒重绘一次。重绘开头先\x1b[H回到左上角，然后再画，而不是插入新行。如果你希望支持按键交互，比如按r手动刷新、按q退出，还需要处理终端的原始模式输入，让程序能立即读到单个按键，而不是等用户按回车。Node 生态里process.stdin.setRawMode(true)就是干这个的。
4.4 调试 Mod 的实用手法
交互式界面一旦跑起来，普通console.log调试基本就没用了，因为输出都进了界面区域。我踩过几次坑后，总结出一套调试流程。
第一步，先把数据层单独跑一遍，把 JSON 存到/tmp/debug.json，确认数据没问题。
第二步，写一个测试脚本，把模拟 JSON 直接喂给渲染层，检查边框和布局。渲染层根本不碰真实 Git 仓库，这样出问题一定是在渲染逻辑。
第三步，用script -q /tmp/session.log或者终端自带的“录制输出”功能，把一整段界面运行过程保存下来，再慢慢回放分析。
第四步，如果界面崩溃但原因不明，可以在代码里加一个环境变量开关，比如DEBUG_RENDER=1，一旦开启就不进入备用屏幕，也不隐藏光标，所有错误信息直接抛在普通输出里。这样能快速定位到是布局计算问题，还是异步刷新问题。
5. 常见问题速查与应对实录
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| Claude 说找不到某个 Mod | 清单文件没登记，或路径写错 | 检查 name 与 command 路径，确认相对路径基准 |
| 界面输出乱码或不断闪烁 | 没有使用备用屏幕，整屏重复重绘 | 进入 smcup 区域，改用局部坐标刷新 |
| 退出界面后终端历史被污染 | 忘记恢复光标和备用屏幕 | 捕获退出信号，统一恢复光标并调用 rmcup |
| 中文表格对不齐 | 用了字符串 length 计算宽度 | 改用显示宽度计算，或给文本补齐空格 |
| Claude 把 ANSI 颜色代码原样当文字回复 | 对话上下文里混入了 raw 转义序列 | 给 Claude 调用默认走数据层 JSON，只有当人需要界面时才渲染 |
| 界面运行后 Claude 卡住不动 | 常驻进程占用终端，没有退出机制 | 确保界面支持按 q 退出，或设置超时自动退出 |
| 多行输出被 Claude 截断 | 输出信息量太大，超过一句话摘要范围 | 数据层精简字段，关键信息放在最前面 |
第一个问题很常见，我自己遇到过。Claude 会严格依赖清单里的 name 字段去找 Mod，名字敲错一个字符就查不到。解决的技巧是在 description 里主动写上“当用户提到仪表盘、状态、仓库概览时，都会优先调用这个 mod”，相当于给 AI 一个“触发条件提示”。
第二个问题的深层原因，是很多人没有理解“备用屏幕”和“普通输出”的本质区别。普通终端输出像一条滚动的卷轴，每一行都会留在历史里。备用屏幕则是一个临时的画板，程序退出时画板撤掉，原来的卷轴内容原封不动。界面型的 Mod 一定要走画板逻辑，否则每一次刷新都污染历史。
第三个问题里，最隐蔽的情况是用户在界面运行途中直接按了Ctrl+C，进程被强制结束，恢复光标的代码根本没执行。所以要在信号捕获里处理SIGINT和SIGTERM，保证退出路径唯一。
第四个问题牵扯到字符宽度，我在 4.2 节已经展开过，不再重复。
第五个问题要特别说明：Claude Code 读取输出时会把这些内容带入它的上下文，而 ANSI 转义序列这种不可见字符很容易让模型产生困惑，甚至在回答里原样吐出\x1b[32m。所以我在所有 Mod 里都遵守一个约定：默认输出纯 JSON，界面渲染只作为可选项，并且渲染输出只给人看，不进入对话历史。
第六个问题属于进程管理。常驻型 Mod 如果忘了退出，Claude 可能会误以为命令还没执行完，一直等下去。所以在代码里要有一个明确的生命周期：要么等待用户按键退出，要么设置最长运行时间，超时自动结束。
第七个问题是信息过载。给 Claude 的输出不是越长越好。数据层的字段数量尽量控制在 5 到 10 个，超过的话反而容易让模型抓不住重点。宁可拆成两个 Mod，也別塞一堆字段。
最后一点个人实操心得
这套 Mods 玩法我连续用了几个项目之后，最大的感受是：它的精髓并不仅仅是“给 Claude 加工具”，而是把“人能看的界面”和“机器能读的数据”拆成了两层。过去我总想写一个全能型的界面，把什么都画进去，结果既难维护，Claude 也不知道怎么用。现在我的习惯是数据层尽量保持干净，渲染层按需出现，界面是给汇报和演示用的，平时的自动流程全部走 JSON。
如果你也想上手，建议不要一开始就照着网上那种复杂仪表盘案子抄。先挑一个最简单的小命令，比如“统计今天改了多少行代码”“列出仓库里最近三天的新分支”，做成一次性脚本型 Mod 试试跑通。跑通之后再逐步增加参数、增加颜色、增加刷新逻辑。每一步只做一件事，踩坑时也容易定位。我后来把几个小 Mod 拼在一起才发现，真正省时间的不是某个单个功能，而是“让 Claude 自己决定调用哪一个工具”这套规则带来的解释成本下降。先把基础链路打通，后面玩出花来都会很顺。
