聊到Claude Code，很多终端党的第一反应是"这不就是个加强版的命令行AI助手嘛，能读代码、改文件、跑测试，挺方便"。但真正把这玩意儿玩出花的人，都在折腾Claude Code Mods。简单说，Mods就是给Claude Code加装自定义工具的插件机制，也是让它在纯字符终端里"画"出界面的唯一正路。你可以把自己的脚本、内部API、甚至一套完整的TUI组件挂进去，让Claude按需调用，然后它输出的不再是一堆干巴巴的文本，而是带颜色、带边框、带进度条的仪表盘、表格、交互菜单。这篇文章不聊概念，直接讲我实际折腾Mods的思路、代码、以及踩过的坑，适合已经用过Claude Code、想让它变得更"顺手"的人。
1. 先搞懂Claude Code和Mods的关系
1.1 Claude Code的定位：终端里的AI结对编程
Claude Code本质上是一个运行在终端里的AI编程助手。你告诉它需求，它会在工作目录里查文件、读代码、执行命令，然后基于上下文给出修改建议或直接动手改。它的核心优势是"离代码够近"——不像网页版那样得手动复制粘贴，它天生就能感知当前仓库的状态。很多团队已经把它当半个结对编程搭档用，写测试、修bug、解释陌生模块，效率确实能上一个台阶。
但用久了你会发现一个痛点：Claude Code内置的能力是固定的，它只能调用自带的那几个工具，比如读文件、写文件、跑shell命令。一旦遇到你内部的一些特殊操作，比如说"把这个构建产物的体积报告生成一下"、"查一下生产环境最近一小时的错误日志"、"把这份代码复杂度分析结果发到团队群"，它就没辙了。它不知道你有这些脚本，也不知道该去哪里找这些数据。这时候，Mods就是为这个场景准备的。
1.2 Mods到底改了什么东西：工具扩展机制
Mods这个说法，你可以理解成"模块"或者"modification"的合体。它的核心思路，是把一个或多个自定义工具的描述信息注册给Claude Code。注册之后，Claude在回答你问题时，会在后台看到"还有一个tool叫gen_report，它的参数有这些"，就像你给同事介绍"这位是负责数据统计的，你找他要报表就行"。
具体落地到技术上，Mods就是一套JSON Schema定义的工具清单，外加对应的可执行脚本。工具清单告诉Claude：这个工具叫什么、接收什么参数、返回什么类型的输出。脚本负责真正干活。当你问Claude问题时，它如果觉得需要调用这个工具，就会按照清单里的参数格式生成一条调用指令，Claude Code拿到指令后在本机执行对应的脚本，再把脚本的stdout作为工具结果返回给Claude。这个闭环跑通了，Claude就算"长出了新胳膊"。
我见过有人把Mods写成了一套内部运维命令的封装，也有人把Mods做成了自动生成周报的小工具。最热闹的，还是用Mods在终端里画界面。原理不复杂：脚本输出ANSI转义序列，Claude拿到这些输出后原样展示在终端里，于是你就能看到彩色表格、动态进度条、甚至可以模拟出一个简单的表单交互。
1.3 为什么要在终端画界面：效率与沉浸感
有人可能会问："终端还能画什么界面？网页不香吗？"要分场景。当你正埋头在终端里调试代码，为了看个数据分布还得切到浏览器、打开网页应用，这个切换成本其实是挺高的。而终端界面是"就地呈现"——你问完问题，界面直接出现在下一行。对于工程师来说，这种不打断思路的体验很有价值。
再一个是信息密度。终端渲染的字符界面，天然适合展示状态类信息：绿色表示通过、红色表示失败、黄色表示警告，再加几个缩进和表格线，一眼就能抓住重点。我之前用Mods做过一个"仓库健康度仪表盘"，把测试覆盖率、依赖过期数量、未提交变更数全打在屏幕上，利用率非常高。
还有个原因是表达方式的自由性。网页端无论做得多花哨，还是得遵循一套框架；终端界面反而有点"极客美学"——纯字符、无多余装饰，数据就是界面。对于喜欢折腾的人来说，用ANSI转义序列把一个终端变成一个可交互仪表盘，本身就是件很有成就感的事。
2. 动手前的准备：环境与核心概念
2.1 环境要求与安装
折腾Mods之前，先把基础环境准备好。我是在macOS的终端上搭的，理论上Linux和Windows终端也都支持，但Windows下要留意PowerShell对ANSI转义序列的处理方式，后面会细说。
第一步，确认Claude Code能正常跑。你至少得有一个能登录API的终端环境，以及一个可以执行脚本的shell。它本身是Node.js开发的，全局安装后就能用。安装完后，用"claude"命令进入交互模式，先跑一条简单的问答试试水，确认网络和数据通道没问题。
第二步，准备Python（或Node）运行环境。Mods的脚本部分用啥语言都行，我给你两个选择：如果要做数据处理、文本分析，Python够顺手；如果要做终端UI，强烈建议用Node + Ink这类React式的终端渲染库，做出来的界面结构清晰、好维护。但这里有个权衡：Claude Code每次调用工具都会启动一个独立进程，所以脚本启动速度很重要。个人实践下来，Python脚本的启动时长在终端UI场景下是能接受的，但如果你要高频调用，Node会更轻量。
工具方面，我建议先装好jq——它是一个通用的JSON解析器，在Mods的脚本里处理输入输出时特别好用。至于终端UI，你完全可以用Python的标准库加ANSI转义序列手写，但为了效率，我会用rich库来画表格和进度条。选rich的原因很简单：它对中文和Emoji的支持都算不错，而且API接近直觉，写起来快。
2.2 工具定义JSON Schema怎么理解
Mods的核心是一份JSON Schema，它描述你这个工具长什么样。Claude会基于这份Schema来决定要不要调用它、调用时该填什么参数。这玩意儿本质上是一个"API说明书"，只不过读者是AI。
一个最简单的工具定义长这样：
{ "name": "get_repo_stats", "description": "获取当前仓库的统计信息，包括代码行数、未提交变更、最近提交时间等", "input_schema": { "type": "object", "properties": { "path": { "type": "string", "description": "仓库路径，默认是当前目录" } }, "required": [] }, "command": "python3 /path/to/scripts/get_repo_stats.py", "output_format": "text" }这里面的关键信息有三块。第一，"name"最要谨慎，一旦Claude学会了某个工具名，再改名字就得重新训练它的调用习惯。第二，"description"要给AI讲清楚，这个工具在什么场景下使用、输入输出大概是什么样，描述得越精准，调用准确率越高。第三，"input_schema"要严格定义参数，尤其是必填参数，Claude不会猜你不能怼的参数，它只会严格照着schema去生成调用。
别小看这份schema，它决定了Claude的"判断力"。我之前有个Mods的参数是"date_from"，描述写得太泛，导致Claude在好几次对话中传了错误的日期格式。后来我把"date_from"的描述改成"格式为YYYY-MM-DD，只接受过去三十天内的日期"，效果立刻就不一样了。
2.3 终端UI的底层：ANSI转义序列入门
要在终端画界面，你就得先懂点ANSI转义序列。它是终端的一种控制码，用于控制光标位置、颜色、清屏等。这些序列本质上就是一堆印刷不出来的控制字符，但终端会把它当作指令来执行。
最常见的转义序列是这样的：
\033[31m红色文字\033[0m这里的"\033["是转义开始，31是红色，m表示"这是颜色代码"，\033[0m表示重置。如果你在终端里跑一下这个输出，就会看到"红色文字"显示成红色。同理，32是绿色，33是黄色。这些颜色组合起来，就成了终端UI的基础调色板。
更高级一点的控制是光标控制。比如"\033[x;yH"可以把光标移到第x行第y列，"\033[2J"可以清屏。这些控制码配合循环和sleep，就能做出动画效果。但我不建议纯手写这些，因为一旦项目变大，维护成本太高。我更推荐用现成的库：Python的rich、Node的chalk和ink，它们把转义序列封装成简单函数，让你像写CSS一样写样式。
这里有一个重要提示：Claude Code在调用工具时，工具的stdout会原样被吸收。如果你输出ANSI转义序列，Claude能"看到"这些序列吗？答案是不能完全看到，它拿到的是原始字符，包括终端的控制码。Claude会把它们当作输出文本的一部分原样返回给你现实中的终端，于是你看到的界面就是控制后的效果。这有点像一个中间人，Claude把画布交给了脚本，脚本直接往画布上画东西，Claude只是负责把画布递给你。
3. 实操：给Claude加一个自定义工具
3.1 搭建一个简单的"终端仪表盘"Mod
我以一个"仓库健康度仪表盘"为例，带你走一遍完整流程。目标是让Claude在收到"看下这个仓库状态"这种指令时，调起一个Python脚本，输出一个带颜色、带进度条的字符界面。
先建一个目录放脚本，比如叫"claude_mods"。然后写工具定义文件（假设叫repo_health.json），内容像之前那个get_repo_stats的例子，但流程更完整。我会把工具名定义成"show_repo_health"。这个工具接收一个可选参数"repo_path"，不传时用当前工作目录。
接下来是核心的Python脚本。我选用rich库来做渲染。它会输出一段ANSI控制序列，Claude Code会把这套序列原样打印出来，最终呈现在你面前。
脚本逻辑大致是：先通过git命令拿到仓库的当前分支、最近提交时间，再统计一下源码文件数和测试文件数的比例，然后模拟一个测试覆盖率数值。这些数据不一定完全准确，但作为演示足够了。界面部分，我画了一个大标题、一个分支信息、一个未提交变更列表，还有一个测试覆盖率的进度条。
#!/usr/bin/env python3 import argparse import json import subprocess from rich.console import Console from rich.table import Table from rich.progress import Progress console = Console() def get_git_info(repo_path): branch = subprocess.check_output(["git", "branch", "--show-current"], cwd=repo_path).decode().strip() recent = subprocess.check_output(["git", "log", "-1", "--format=%cd"], cwd=repo_path).decode().strip() dirty = subprocess.check_output(["git", "status", "--porcelain"], cwd=repo_path).decode().splitlines() return branch, recent, dirty def main(): parser = argparse.ArgumentParser() parser.add_argument("--repo_path", default=".") args = parser.parse_args() branch, recent, dirty = get_git_info(args.repo_path) table = Table(title="Repository Health") table.add_column("Metric", style="cyan") table.add_column("Value", style="magenta") table.add_row("Branch", branch) table.add_row("Last commit", recent) table.add_row("Uncommitted files", str(len(dirty))) console.print(table) with Progress(transient=True) as progress: task = progress.add_task("Coverage", total=100) progress.update(task, completed=72) if __name__ == "__main__": main()这个脚本跑完，会在终端里生成一个表格和一个进度条。你可以先手动执行一下这个脚本，确认它能正常渲染。注意，脚本必须把输出打到stdout，不要写stderr，否则Claude Code会当作错误处理。
3.2 注册工具并让Claude调用
有了脚本，下一步就是把它注册到Claude Code里。不同版本对Mods的加载方式可能略有差异，但核心思路都一致：在Claude Code的配置目录里放一份JSON格式的工具描述文件，告诉它"有个工具叫这个名字，它的入口是什么"。
具体操作上，你可以在个人配置目录下新建一个"mods"子目录，把repo_health.json拷贝进去。有些版本还支持直接在Claude Code的配置文件里通过路径引用脚本，方便你集中管理多个脚本。
注册完成后，重新启动Claude Code会话，输入这么一句话：
帮我看下当前这个仓库的健康状态。
正常情况下，Claude会先思考一下，然后生成一个调用show_repo_health的指令，接着你的Python脚本就会被执行，脚本输出的那堆ANSI序列就会以界面形式出现在终端里。我第一次跑通时，那个带进度条的画面出来，瞬间觉得这个终端AI比网页版香太多了。
如果你发现Claude没有调用这个工具，八成是工具描述写得不够清晰。你可以把description改得更主动一些，比如"当用户询问仓库健康状态时调用此工具"，它对触发场景的识别就会好很多。也可以直接给Claude举些例子，比如"你可以这样问：仓库要发布了吗？"这种方式能明显提高调用率。
3.3 在终端里绘制界面：字符画与颜色控制
当你掌握了基础的表单渲染，就可以往更"画"的方向探索了。比如做一个简单的字符画统计图，把多个月份的数据用柱状图或折线图的形式显示出来。
做法其实很简单：给脚本传入一组数据，脚本计算最大值，然后把每个数据点映射成若干个"#"字符，连同刻度标签一起输出。这个功能不依赖任何花哨的库，纯用Python就行。
def draw_bar_chart(data): max_val = max(data.values()) for label, value in data.items(): bar_length = int((value / max_val) * 40) bar = "#" * bar_length print(f"{label:10} | {bar:40} {value}") draw_bar_chart({"Jan": 12, "Feb": 19, "Mar": 8, "Apr": 25})这个柱状图在终端里的渲染效果意外地好，很直观。你甚至可以把它嵌入到Mods里，让Claude在回答"这个季度最活跃的仓库是哪个月"这种问题时，直接动态生成一张图。这种"字符画"不占空间、不依赖外部资源，对终端场景来说非常可靠。
如果想要更"界面感"的东西，可以试试ANSI转义序列画边框。一个表格始终是由线条和字符构成的，常见的绘图字符是│、─、┌、┐└、┘。在Python里可以用unicodedata控制输出，但直接用rich库的Table更省事。rich的Table会自动适配终端宽度，还能设置对齐方式，节省你大量手工调整的时间。
4. 进阶玩法与细节打磨
4.1 参数校验与错误处理
Mods脚本的输入来自Claude生成的参数，但这个参数并不总是靠谱。Claude可能把日期格式传成dd-mm-yyyy，也可能把路径传成不存在的目录。所以脚本里必须有严格的参数校验。
我的经验是，在所有Mods脚本的入口部做三层校验。第一层，检查必需参数是否都有，没有就报错并给出帮助信息。第二层，用类型转换加异常捕获来校验参数类型，比如把字符串日期转成datetime对象，转不了就拒绝执行。第三层，范围校验，比如只接受过去30天内的日期，超出的直接删掉。
错误处理要分两块。一块是给Claude看的错误提示，Claude会根据这个提示调整参数后重新调用工具，所以你的报错信息要写清楚"错在哪、怎么改"。另一块是给终端用户看的，如果工具调用本身失败，你应该在界面上显示一个友好的错误面板，而不是抛堆栈。
我踩过的一个坑是：脚本在子进程里崩溃了，但stdout还是输出了半个表格，Claude把那半个表格当成正常结果返回，导致用户看到一张残缺的界面。解决方法是，脚本输出前把所有数据都准备好，最后一次性渲染完成；或者捕获所有异常，保证输出要么完整、要么为空。
4.2 性能与体验优化
Mods脚本每次被调用，都会重新拉起一个进程。如果你的脚本要加载重型依赖、连数据库、扫描整个仓库，这个时间就会被白白浪费掉。优化方向有几个。
第一，轻量化。如果只是处理文本，尽量使用标准库，避免加载Pandas、Requests这种重型库。我之前试过用Python的csv库处理一个几MB的日志文件，加载时间远小于启动Pandas的时间，KPI明显不一样。
第二，缓存。同一个工具的多次调用，如果入参相同，可以直接把结果缓存到临时文件或内存里。我在做一个"依赖版本查询"的Mods时，就把常用包的版本信息缓存到一个JSON文件里，每次查询先读缓存，命中就直接返回，没命中才去真正解析包管理器。
第三，并行处理。如果你要同时查多个信息（代码行数、依赖旧版本、未提交变更），每个命令单独执行所花的时间会累加。可以在脚本里用并发方式同时发起这些查询，再等全部结果返回。Python的ThreadPoolExecutor就能干这事，简单有效。
终端体验方面，必须考虑小屏和滚动。如果输出的表格很长，比如超过终端高度，用户就得不停滚动。这个问题可以通过在输出前估算终端高度、仅打印当前一屏的内容来解决。如果你的终端工具支持交互，还可以做成"按任意键继续"的分页结构。
4.3 多个Mod如何协同
当你有七八个Mods的时候，散落在不同目录的脚本和JSON就没法管了。我建议把每个Mod做成一个独立的子目录，里面包含自己的JSON定义、脚本、测试用例，以及一份README说明。
协同的核心是标准输出协议的约定。每个Mods脚本的输出都应该是结构化的JSON，或者至少包含一段机器可读的摘要。我在本地搭了一个简单的协议：脚本输出三部分——status（成功或失败）、message（人类可读的提示）、result_data（结构化数据）。Claude拿到这三个字段后，可以很清楚地决定下一步动作。
多个Mods之间还能互相调用。比如一个"询价"Mods返回一批URL列表，另一个"抓取网页"Mods可以直接消费这些URL。关键在于，前一个工具的输出要能被后一个工具当成输入。所以定义JSON Schema时，尽量把输出设计成"一眼就能看懂的字典"，属性名用一致的命名规范。
5. 常见问题与排查技巧
5.1 Claude不调用你的工具怎么办
这是所有人都会遇到的头一个问题。你辛辛苦苦写好了脚本和JSON，但Claude就是视而不见，你说"看仓库状态"，它还是自己用ls、git status去猜。
排查思路第一条：检查工具定义是否被正确加载。在Claude Code的调试模式里，能看到它当前知道哪些工具。如果你看到的工具列表里没有你的Mod，那就说明JSON没读进去。
第二条：优化Description。描述里要包含明确的触发词和场景。比如"当用户提到'仓库''状态''健康''检查'这些词时，优先调用此工具，不要用其他方式泛泛回答"。Claude对大模型的指令遵循能力很强，你得把工具的"使用说明"写得跟产品需求文档一样清晰。
第三条：给Claude"喂"几个调用示例。在JSON Schema的description里写上"比如用户可能会问：这个项目能不能发布？这时候就该调用show_repo_health"。这种明确示例比任何规则都管用。
第四条：直接下命令。在Claude Code里输入"请调用show_repo_health工具，参数repo_path=."，如果这样它都不执行，那就不是调用策略问题，而是工具加载出错了。
5.2 中文乱码与控制台宽度问题
中文乱码是终端永恒的敌人。Claude Code自身对中文支持得很好，但Mods脚本输出的中文，一旦遇到终端编码不对，就会变成一门天书。
解决方案是在脚本里强制指定UTF-8编码：
import sys, io sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')如果在Windows PowerShell里，还要先执行"chcp 65001"把代码页切到UTF-8。另外，rich库默认情况下会检查终端宽度和颜色支持，如果检测到非UTF-8环境，会自动降级为纯文本，这虽然保险，但界面效果会打折。
控制台宽度问题表现为：表格突然换行、进度条溢出、界面被截断。rich库的Table可以通过设置"responsive=True"让列自适应，但遇到窄终端还是会措手不及。我的实践经验是，给表格列配一个最小和最大宽度，优先保证数据可读。
5.3 权限、环境变量与安全边界
Mods脚本默认继承Claude Code的权限。如果Claude Code以你的用户身份运行，Mods脚本也能执行所有你能执行的操作。这个便利性背后是隐患。你可能会让Claude调用一个删除临时文件的工具，如果不小心把参数拼接命令，就成了RCE风险。
我的建议是，Mods脚本尽量使用静态命令，入参只做值传递，绝对不能把参数拼进shell命令里。比如用Python的subprocess传参数列表，而不是拼字符串。如果你想让一个"删除构建目录"的工具工作，一定要在脚本里限制删除路径只能位于项目根目录下的build/子目录。
权限方面，可以把Mods脚本单独放在一个用户目录下，限制它只能读写特定文件夹。同时，在Claude Code配置里开启"工具调用确认"模式，让每次工具调用都经过你的手点确认，虽然多了一步，但安全感拉满。
最后再提醒一个环境变量的问题：Claude Code调用脚本时，环境变量不一定和你终端里一样。如果脚本依赖某个PATH下的可执行文件，建议在脚本开头重新设置PATH，或者直接用绝对路径。不然，你本地跑得好好的，Mods一调就"command not found"，那感觉可太糟糕了。
我做Mods踩过最大的坑，就是一开始低估了"描述能力"的重要性。工具本身的功能再强，如果JSON Schema里写不清楚，Claude就不是你的最佳拍档，而是个拿着锤子到处找钉子的助手。另一个更深的体会是，终端UI的关键不是让它看起来多炫酷，而是让它在一屏之内把最关键的信号传达出来。那些花里胡哨的动画，用几天就腻了；真正留在工作流里的，是那些稳定、快速、一眼能看懂的状态面板。从给Claude加一个小脚本开始，到在终端画出一个完整的仪表盘，整个过程其实就是在磨合AI和你的工作习惯。这个东西还能怎么扩展？把你的构建报警、代码评审、部署状态全部接进来，最终你拥有的就是一个完全属于你的终端指挥中心。
