聊到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], cwdrepo_path).decode().strip() recent subprocess.check_output([git, log, -1, --format%cd], cwdrepo_path).decode().strip() dirty subprocess.check_output([git, status, --porcelain], cwdrepo_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(titleRepository Health) table.add_column(Metric, stylecyan) table.add_column(Value, stylemagenta) table.add_row(Branch, branch) table.add_row(Last commit, recent) table.add_row(Uncommitted files, str(len(dirty))) console.print(table) with Progress(transientTrue) as progress: task progress.add_task(Coverage, total100) progress.update(task, completed72) 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, encodingutf-8)如果在Windows PowerShell里还要先执行chcp 65001把代码页切到UTF-8。另外rich库默认情况下会检查终端宽度和颜色支持如果检测到非UTF-8环境会自动降级为纯文本这虽然保险但界面效果会打折。控制台宽度问题表现为表格突然换行、进度条溢出、界面被截断。rich库的Table可以通过设置responsiveTrue让列自适应但遇到窄终端还是会措手不及。我的实践经验是给表格列配一个最小和最大宽度优先保证数据可读。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和你的工作习惯。这个东西还能怎么扩展把你的构建报警、代码评审、部署状态全部接进来最终你拥有的就是一个完全属于你的终端指挥中心。
聊到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], cwdrepo_path).decode().strip() recent subprocess.check_output([git, log, -1, --format%cd], cwdrepo_path).decode().strip() dirty subprocess.check_output([git, status, --porcelain], cwdrepo_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(titleRepository Health) table.add_column(Metric, stylecyan) table.add_column(Value, stylemagenta) table.add_row(Branch, branch) table.add_row(Last commit, recent) table.add_row(Uncommitted files, str(len(dirty))) console.print(table) with Progress(transientTrue) as progress: task progress.add_task(Coverage, total100) progress.update(task, completed72) 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, encodingutf-8)如果在Windows PowerShell里还要先执行chcp 65001把代码页切到UTF-8。另外rich库默认情况下会检查终端宽度和颜色支持如果检测到非UTF-8环境会自动降级为纯文本这虽然保险但界面效果会打折。控制台宽度问题表现为表格突然换行、进度条溢出、界面被截断。rich库的Table可以通过设置responsiveTrue让列自适应但遇到窄终端还是会措手不及。我的实践经验是给表格列配一个最小和最大宽度优先保证数据可读。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和你的工作习惯。这个东西还能怎么扩展把你的构建报警、代码评审、部署状态全部接进来最终你拥有的就是一个完全属于你的终端指挥中心。
函数完全指南：从参数详解到中文乱码解决)
