Claude Code Mods 扩展开发：自定义工具与终端界面实战

1. Claude Code Mods 到底是个什么东西

第一次听到 "Claude Code Mods" 这个词，很多人会下意识以为是某个插件市场或者第三方魔改版本。其实不是。Claude Code 本身是 Anthropic 推出的一个跑在终端里的编程助手，它不是一个网页对话框，而是直接驻留在你的命令行里，能读写文件、执行命令、跑测试、提交代码。而所谓 Mods，指的是围绕它构建的一套扩展机制——你可以给它加自定义工具（tools）、改它的系统提示、在终端里画出更复杂的交互界面，甚至把它的行为改造成完全贴合你自己工作流的形态。

说白了，原生的 Claude Code 是一个"能干活但比较朴素"的终端助手，Mods 就是让它从"能用"变成"好用、专属"的那一层。它解决的核心问题是：通用助手不懂你的项目规范、不认识你的内部工具、界面交互也满足不了复杂场景。通过 Mods，你可以把这些缺口一个个补上。

这篇文章适合谁看？三类人。第一类是把 Claude Code 当日常主力工具、想进一步榨干它能力的开发者；第二类是对终端 TUI（Terminal User Interface，终端用户界面）感兴趣、想用 JS/TS 在命令行里画界面的人；第三类是好奇"给 AI 助手加工具"这件事到底怎么落地、想自己动手试一把的技术爱好者。不管你之前有没有写过 Claude Code 的扩展，只要你会一点 JavaScript 或 TypeScript，这篇内容都能让你照着做出来。

我先把结论摆在这：Claude Code Mods 的本质，是用 JS/TS 写工具函数 + 用终端渲染库画界面 + 通过配置把它们挂到 Claude Code 上。三件事拆开都不难，难的是把它们串起来、并且知道哪些坑不能踩。下面我按这个逻辑一层层拆。

2. 核心机制拆解：Mods 凭什么能扩展 Claude Code

2.1 工具调用是扩展的第一入口

Claude Code 和普通聊天机器人最大的区别，是它能"动手"。这个动手能力来自工具调用（tool use）机制。模型本身只会输出文本，但当它判断需要执行某个动作时，会输出一个结构化的工具调用请求，由宿主程序去执行，再把结果喂回给模型。Claude Code 内置了一批工具，比如读文件、写文件、执行 shell 命令、搜索代码库。

Mods 要做的第一件事，就是往这个工具列表里塞进你自己的工具。比如你公司有一套内部的部署脚本，每次都要手动敲一长串参数，那你完全可以写一个deploy_service工具，让 Claude 直接调用。模型看到你的工具描述后，会在合适的时机自动触发它。

这里有个关键点很多人忽略：工具的描述（description）质量，直接决定模型会不会在正确的时机调用它。我见过太多人工具写得好好的，但描述写得含糊，结果模型要么不调用，要么乱调用。描述要写清楚三件事——这个工具干什么、什么时候该用、参数分别是什么含义。这跟给新人写接口文档是一个道理。

2.2 终端界面为什么值得单独做

Claude Code 跑在终端里，而终端天生是个"文本流"环境。但文本流不代表不能有交互。现代终端支持 ANSI 转义序列、光标控制、颜色、甚至鼠标事件，这就给 TUI 提供了土壤。像ink（用 React 写终端界面）、blessed、prompts这类库，能让你在命令行里画出带边框的表格、可选择的列表、实时刷新的进度条。

为什么要在 Claude Code 的扩展里画界面？因为有些场景纯文本输出体验太差。举个例子，你要让用户从 20 个服务里选一个来部署，纯文本就是打印 20 行让用户输编号，容易输错；而一个可上下键选择、带高亮的列表，体验完全是两个档次。再比如长时间运行的任务，一个实时更新的进度面板，比一行行滚动的日志友好得多。

2.3 JS/TS 生态是 Mods 的天然土壤

为什么 Mods 的扩展大多用 JS/TS 写？因为 Claude Code 本身就跑在 Node.js 运行时上，扩展直接复用同一套生态，不需要跨语言桥接。你可以直接用 npm 上现成的库，用 TypeScript 拿到类型提示，用熟悉的异步模型处理工具调用。这对前端和 Node 开发者极其友好——你几乎不需要学新语言，只要理解 Claude Code 的扩展接口就行。

TypeScript 在这里的价值尤其明显。工具的参数是有结构的，用 TS 定义好类型，编辑器里就有自动补全，参数传错了编译期就能发现。我强烈建议哪怕你平时写 JS，做 Mods 扩展时也上 TS，省下来的调试时间远超配置成本。

3. 动手前的环境准备与工具选型

3.1 先把 Claude Code 本身跑起来

在折腾 Mods 之前，得先有一个能正常工作的 Claude Code。安装方式通常是通过 npm 全局安装，装完之后在终端里能直接调用命令。这里有个高频坑：npm 全局目录的写权限问题。很多人装完之后遇到自动更新失败、提示没有写权限，本质是全局 node_modules 目录归属不对。解决办法是把 npm 的全局前缀改到用户目录下，或者用版本管理工具（如 nvm）来管理 Node，避免动系统目录。

另一个常见问题是安装后命令找不到。这通常是 PATH 没配好，全局 bin 目录没进环境变量。装完先which一下确认路径，再决定要不要改 shell 配置。

提示：安装和升级尽量走官方推荐的渠道，不要手动去改安装目录里的文件，否则下次升级会被覆盖，你的改动全丢。

3.2 扩展项目的目录结构怎么定

一个清晰的 Mods 扩展项目，我一般这么组织：

my-claude-mods/ ├── package.json ├── tsconfig.json ├── src/ │ ├── tools/ # 每个工具一个文件 │ │ ├── deploy.ts │ │ └── queryLog.ts │ ├── ui/ # 终端界面组件 │ │ └── servicePicker.tsx │ └── index.ts # 扩展入口，注册所有工具 └── dist/ # 编译输出

把工具和界面分开，是因为它们的关注点不同。工具关心"做什么"，界面关心"怎么展示"。混在一起写，后期加功能会非常痛苦。入口文件只做一件事——把散落的工具和界面注册进去，保持它足够薄。

3.3 依赖选型：别一上来就堆库

终端界面库的选择，我踩过坑，给你一个直接的结论：

新手我建议从prompts+ora起步，先把工具跑通，等真的需要复杂界面了再上ink。一上来就选最重的库，往往卡在配置上，还没摸到 Claude Code 扩展的门就放弃了。

4. 写第一个自定义工具：从零到能跑

4.1 工具的基本结构长什么样

一个 Claude Code 工具，核心就是三部分：名字、描述、参数 schema，外加一个执行函数。用 TS 写大概是这样：

import { z } from "zod"; export const deployTool = { name: "deploy_service", description: "部署指定服务到目标环境。当用户要求部署、发布某个服务时使用此工具。", parameters: z.object({ service: z.string().describe("要部署的服务名，例如 user-api"), env: z.enum(["dev", "staging", "prod"]).describe("目标环境"), dryRun: z.boolean().optional().describe("是否只做演练不真正部署"), }), async execute({ service, env, dryRun }) { // 实际执行逻辑 return `已${dryRun ? "演练" : "执行"}部署 ${service} 到 ${env}`; }, };

注意parameters用的是 zod，这是目前最主流的 schema 校验方案。它既能做运行时校验，又能推导出 TS 类型，一举两得。describe里的文字会作为参数说明传给模型，所以别偷懒，写清楚。

4.2 描述怎么写模型才买账

我前面强调过描述的重要性，这里给个具体的对比。差的描述：

description: "部署服务"

好的描述：

description: "部署指定服务到目标环境。当用户明确要求部署、发布、上线某个服务时调用。不要用于查询服务状态。"

差别在哪？好的描述明确了触发时机和排除条件。模型是靠语义匹配来决定调不调工具的，你告诉它"什么时候别用"，能大幅减少误触发。这跟给搜索引擎写关键词是一个思路——既要覆盖该命中的，也要排除不该命中的。

4.3 参数校验与错误处理

工具执行函数里，永远不要假设参数一定合法。哪怕 schema 已经校验过类型，业务层面的校验还得自己做。比如服务名是否真实存在、环境是否允许部署。错误处理的原则是：返回清晰的错误信息，而不是抛异常让整个流程崩掉。因为模型会读取你的返回内容，如果返回的是"服务 xxx 不存在，可选服务有 a、b、c"，模型就能自己纠正，重新调用。如果直接抛异常，模型可能就卡住了。

async execute({ service, env }) { const validServices = await listServices(); if (!validServices.includes(service)) { return `服务 ${service} 不存在。可选服务：${validServices.join(", ")}`; } // ... }

这种"把错误当信息返回"的模式，是让 AI 助手稳定工作的关键技巧之一。

5. 在终端里画界面：让扩展真正好用

5.1 从最简单的交互开始

先别急着画复杂界面。最简单的交互就是一个选择列表，用prompts几行就能搞定：

import prompts from "prompts"; async function pickService(services: string[]) { const { service } = await prompts({ type: "select", name: "service", message: "选择要操作的服务", choices: services.map((s) => ({ title: s, value: s })), }); return service; }

这段代码在终端里会渲染出一个可上下键选择、回车确认的列表。相比让用户手输编号，体验提升是立竿见影的。而且prompts会自动处理光标、颜色、键盘事件，你不需要碰任何 ANSI 转义序列。

5.2 用 ink 做实时刷新的面板

当你要展示实时变化的数据，比如部署进度、日志流，prompts就不够了，得上ink。ink 让你用 React 组件的方式描述终端界面，状态一变，界面自动重渲染。

import React, { useState, useEffect } from "react"; import { render, Box, Text } from "ink"; function DeployProgress({ steps }: { steps: string[] }) { const [current, setCurrent] = useState(0); useEffect(() => { const timer = setInterval(() => { setCurrent((c) => (c < steps.length - 1 ? c + 1 : c)); }, 1000); return () => clearInterval(timer); }, []); return ( <Box flexDirection="column"> {steps.map((step, i) => ( <Text key={step} color={i < current ? "green" : i === current ? "yellow" : "gray"}> {i < current ? "✓" : i === current ? "▶" : "○"} {step} </Text> ))} </Box> ); }

这个组件会渲染出一个带状态标记的步骤列表，已完成的绿色打勾，进行中的黄色箭头，未开始的灰色圆圈。这种视觉反馈，比一行行打印"步骤 1 完成""步骤 2 完成"要直观得多。

5.3 界面与工具如何配合

界面不是孤立的，它通常服务于工具的执行过程。一个典型的配合模式是：工具被调用 → 弹出选择界面让用户确认 → 执行并展示进度 → 返回结果给模型。这里要注意，界面交互是阻塞的，用户没选完，工具不能往下走。所以异步流程要处理好，别让界面卡住整个 Claude Code 的响应。

注意：在工具执行函数里做交互式界面，要确保终端处于可交互状态。如果 Claude Code 是在非交互环境（比如管道、CI）里跑的，界面会失效，这时候要有降级方案，比如直接返回错误提示或走默认参数。

6. 常见问题与排查实录

6.1 工具不触发或乱触发

这是最高频的问题。排查顺序我一般这么走：先看描述是否清晰，再看参数 schema 是否有歧义，最后看是不是工具太多导致模型选择困难。工具数量超过十几个之后，模型的选择准确率会下降，这时候要么合并相似工具，要么在描述里强化区分度。

6.2 终端界面显示错乱

界面错乱通常有几个来源：终端宽度不够导致换行、颜色码在不支持的终端里显示成乱码、多个界面同时渲染互相覆盖。解决办法是渲染前先读终端宽度做适配，颜色用库提供的抽象而不是手写转义码，同一时间只允许一个界面占用输出。

6.3 TypeScript 编译报错

TS 报错里最常见的是类型不匹配和模块解析问题。类型不匹配多半是 zod schema 和实际参数对不上，仔细核对。模块解析问题通常是tsconfig.json里的module和moduleResolution配置和运行时不匹配，Node 环境一般用NodeNext或CommonJS，别用浏览器那套配置。

6.4 升级后扩展失效

Claude Code 升级后，扩展接口可能有变化。这是所有扩展生态的通病。我的做法是：把扩展的依赖版本锁死，升级 Claude Code 前先看变更说明，升级后跑一遍回归测试。别在生产工作流里用最新版，稳一版再升。

7. 我踩过的坑和几条实在建议

做 Claude Code Mods 这段时间，有几个教训是文档里不会写的。第一，别贪多。一开始就想做十个工具、五个界面，结果每个都半成品。正确做法是先做一个真正解决自己痛点的工具，跑顺了再扩展。第二，工具的返回值要"对模型友好"。返回一大坨 JSON，模型读起来费劲还容易漏信息；返回结构化的、带自然语言说明的文本，模型理解得更准。第三，界面是锦上添花，不是必需品。很多场景纯文本就够了，为了炫技硬上界面，反而增加维护成本。

还有一点关于 TypeScript 的：如果你项目里同时有 JS 和 TS 文件，注意模块系统别混用。CommonJS 和 ESM 混在一起，import和require打架，报错能让你查半天。统一用一种，从项目初始化就定好。

最后分享一个实用的小技巧：调试工具时，先脱离 Claude Code 单独跑。把工具的 execute 函数抽出来，写个简单的脚本直接调用，确认逻辑没问题了，再挂到 Claude Code 上测触发。这样能把"工具逻辑错误"和"模型触发问题"分开排查，效率高很多。等这套流程跑顺了，你会发现给 Claude Code 加工具、画界面这件事，其实比想象中简单得多，真正的门槛在于想清楚你到底要它帮你解决什么问题。