1. Claude Code Mods 到底在改什么从“对话工具”到“可编程终端工作台”很多人第一次听到 Claude Code Mods 这个词会下意识以为它是某种插件市场或者像浏览器扩展那样点一下“安装”就完事。实际用下来你会发现它更像是一套“给 Claude Code 这个终端里的编程助手加装外设”的机制——你可以给它挂上自定义工具也可以让它在终端里画出真正可交互的界面而不是只吐一堆纯文本。先把概念拆开。Claude Code 本身是一个跑在终端里的编程助手它能读文件、改代码、跑命令交互方式以文本为主。而 Mods 这层东西核心解决两个痛点第一Claude 原生能力有限遇到它不擅长的领域比如查某个内部系统、调用某个特定 API、做复杂的数据转换你需要把能力“喂”给它第二纯文本交互在有些场景下效率太低比如你要选一个文件、勾几个选项、看一个进度条用文字来回描述很累这时候终端界面TUI就派上用场了。所以 Claude Code Mods 的本质是两件事的组合工具扩展Tools和终端界面Terminal UI。前者让 Claude 能“做更多事”后者让 Claude 能“更好沟通”。关键词里出现的 JS、TS说明这套东西的扩展开发主要用 JavaScript 或 TypeScript 来写这对前端和 Node.js 背景的人非常友好——你不需要学一门新语言用现有的 JS/TS 技能就能上手。适合谁来参考这篇内容三类人最合适一是已经在用 Claude Code、但觉得原生功能不够用的开发者二是想把自己的一些脚本、内部工具接进 AI 工作流的人三是对终端界面开发感兴趣、想看看怎么用 JS/TS 在终端里画 UI 的人。哪怕你只是刚装好 Claude Code这篇文章也能帮你理解它后面能扩展成什么样。我自己的体会是很多人卡在“知道有 Mods 但不知道从哪下手”。网上关于安装的教程一大堆但讲清楚“Mods 的扩展点在哪、工具怎么注册、界面怎么渲染”的内容很少。下面我就按实际动手的顺序把这条链路完整走一遍。2. 工具扩展的注册机制Claude 怎么知道你新加了一个工具2.1 工具描述文件是整个扩展的入口Claude Code Mods 加工具不是你把一个 JS 文件丢进去就自动生效的。它需要一个“描述文件”来告诉 Claude这个工具叫什么、干什么用、需要哪些参数、返回什么。这个描述文件通常是一个 JSON 或 TS 模块里面定义工具的 name、description、input schema 和 handler。为什么要有描述文件因为 Claude 是语言模型它决定要不要调用一个工具靠的是读这个工具的说明。描述写得清楚Claude 就知道什么时候该用描述写得含糊它要么不用要么乱用。这一点和函数调用的原理一致——模型根据自然语言描述来匹配意图。我见过最常见的错误是把 description 写成“处理数据”这种废话。Claude 看到这种描述根本不知道什么时候该调用。正确的写法应该像给同事写接口文档“当用户需要把 CSV 文件转换成 JSON 格式时使用此工具输入为文件路径输出为转换后的 JSON 字符串”。描述里带上触发场景命中率会高很多。2.2 参数 schema 决定了 Claude 传什么给你input schema 一般用 JSON Schema 来描述定义每个参数的类型、是否必填、含义。这一步很多人偷懒把所有参数都写成 string结果 Claude 传过来的数字变成字符串handler 里还得手动转。更麻烦的是如果 schema 里没写清楚参数含义Claude 可能传错值。举个实际例子。你要做一个“查询订单状态”的工具参数是订单号。schema 里如果只写orderId: stringClaude 可能把“帮我查一下订单”里的“订单”两个字传进来。但如果你写成orderId: string, description: 订单编号格式为 16 位数字例如 2024010112345678Claude 就会知道要去对话里找那串数字。这里有个经验schema 的 description 字段是给 Claude 看的不是给人看的。所以要用自然语言把参数的格式、范围、示例都写进去。这跟写 API 文档给人类开发者看是一个道理只不过读者换成了模型。2.3 handler 里最容易踩的坑异步和错误处理handler 就是你真正执行逻辑的地方通常是一个 async 函数。JS/TS 写异步很自然但有两个坑特别常见。第一个坑是没有处理超时。如果你的工具要去请求一个外部接口接口挂了或者很慢Claude 会一直等整个会话就卡住了。稳妥的做法是在 handler 里加超时控制比如用Promise.race配一个定时器超过 10 秒就返回一个明确的错误信息。这样 Claude 能收到反馈继续往下走而不是干等。第二个坑是错误信息写得太技术化。比如你直接throw new Error(ECONNREFUSED)Claude 看到这个不一定能理解发生了什么也就没法给用户一个有用的回复。更好的做法是 catch 住错误返回一句人话“无法连接到订单服务请检查网络或稍后重试”。Claude 拿到这句话就能自然地转述给用户。提示handler 的返回值最好是结构化的对象而不是一坨字符串。结构化数据让 Claude 更容易理解结果也方便你在终端界面里做进一步渲染。2.4 工具注册后的验证方法写完工具怎么确认 Claude 真的能调用我的做法是分三步验证。第一步先单独跑 handler用一个写死的输入确认逻辑本身没问题。第二步在 Claude Code 里用一句非常明确的指令触发比如“用查询订单工具查一下订单号 2024010112345678”看它是否调用。第三步换一种模糊的说法比如“我那个订单到哪了”看它能不能自己找到订单号并调用。这三步能帮你区分问题出在哪如果第一步就挂了是代码问题如果第一步过、第二步不过是描述或 schema 问题如果前两步过、第三步不过是描述不够自然需要补充触发场景的说明。3. 在终端里画界面TUI 渲染的基本原理和 JS/TS 实现路径3.1 终端界面不是“画图”是“控制字符”很多人以为在终端里画界面得像 GUI 那样有画布和像素。其实终端界面的本质是往标准输出里写特定的控制字符让光标移动、清屏、变色、画框。你看到的“边框”“按钮”“进度条”都是字符拼出来的。理解这一点很关键因为它决定了你的实现思路。你不需要什么图形库只需要一个能控制光标和颜色的库。JS/TS 生态里这类库不少常见的有 ink用 React 的方式写终端界面、blessed、以及更底层的 ansi-escapes。选哪个取决于你的需求如果界面复杂、有状态管理ink 很合适如果只是简单输出直接拼 ANSI 转义序列也行。为什么 Claude Code Mods 要用终端界面因为有些交互用文字描述太啰嗦。比如让用户从 20 个文件里选一个文字方式得列出来让用户输编号而终端界面可以直接做一个可上下移动的选择列表回车确认。体验差距很大。3.2 用 ink 写一个最小的选择界面ink 的思路是把 React 组件渲染到终端。你写 JSX它负责把组件树转成终端输出。下面是一个最小可用的选择列表import React, { useState } from react; import { render, Box, Text, useInput } from ink; const items [订单查询, 库存检查, 价格计算]; function Selector() { const [index, setIndex] useState(0); useInput((input, key) { if (key.upArrow) setIndex(i Math.max(0, i - 1)); if (key.downArrow) setIndex(i Math.min(items.length - 1, i 1)); }); return ( Box flexDirectioncolumn {items.map((item, i) ( Text key{item} color{i index ? green : white} {i index ? : }{item} /Text ))} /Box ); } render(Selector /);这段代码跑起来终端里就会出现一个可以用上下键移动的选择列表。useInput是 ink 提供的钩子专门用来处理键盘输入。Box和Text是布局和文本组件类似 HTML 里的 div 和 span。为什么用 ink 而不是手写 ANSI因为手写要自己管理光标位置、重绘逻辑界面一复杂就容易乱。ink 帮你处理了 diff 和重绘你只管写组件。代价是引入了一个依赖但对于稍微复杂点的界面这个代价很值。3.3 界面和工具怎么配合终端界面不是孤立的它通常和工具配合使用。一个典型流程是Claude 判断需要用户做选择调用一个“展示选择界面”的工具工具内部用 ink 渲染界面用户选完后把结果返回给 ClaudeClaude 再根据选择调用下一个工具。这里有个细节要注意终端界面会接管输入。当 ink 的界面在运行时用户的键盘输入被界面捕获Claude 的对话输入是暂停的。所以界面必须有一个明确的退出条件比如用户按回车确认或按 Esc 取消否则用户会被“困”在界面里。我的做法是给每个界面都加一个 Esc 取消的兜底逻辑并且在界面上用文字提示“按 Esc 取消”。这样即使逻辑出问题用户也有办法退出来。这个习惯是从做 CLI 工具时养成的——永远给用户留一条退路。3.4 界面渲染的性能和兼容性终端界面在不同终端里的表现可能不一样。比如有些终端对颜色支持有限有些对光标控制的支持有差异。ink 这类库已经做了不少兼容处理但仍有边界情况。一个实际遇到的坑是中文宽度问题。终端里一个中文字符通常占两个英文字符的宽度但有些库计算宽度时按一个算导致边框对不齐。解决办法是使用能正确计算东亚字符宽度的库比如 string-width在计算布局时用它来测量文本宽度。另一个坑是界面刷新频率。如果你的界面里有实时更新的内容比如进度条刷新太快会导致终端闪烁刷新太慢又显得卡顿。一般控制在每秒 10 到 20 次比较合适。ink 内部有节流机制但如果你自己写重绘逻辑就要注意这一点。4. 从零跑通一个 Mod完整流程和实测中的意外情况4.1 环境准备里最容易被忽略的一步在动手写 Mod 之前环境准备有个细节很多人会漏确认 Claude Code 的版本和 Mods 支持情况。不同版本对 Mods 的支持程度不一样有些扩展点在新版本才有。所以第一步应该是查一下当前版本并确认你要用的扩展点是否可用。安装依赖时如果你用 TS 写记得配好 tsconfig特别是 module 和 target 要跟 Node 版本匹配。我见过有人用 ES module 的写法但 Node 配置成了 CommonJS结果 import 报错排查半天。稳妥的做法是先跑一个最小的 hello world确认工具链通了再往上加功能。4.2 一个完整 Mod 的目录结构一个结构清晰的 Mod 目录大概长这样my-mod/ package.json tsconfig.json src/ index.ts // 入口注册工具和界面 tools/ queryOrder.ts // 工具实现 ui/ selector.tsx // 终端界面入口文件负责把工具和界面注册到 Claude Code。工具和界面分开放是为了职责清晰——工具管逻辑界面管展示。这样改界面不影响工具逻辑改工具也不影响界面。package.json 里要声明入口和依赖。如果你的 Mod 要被 Claude Code 加载通常需要在某个配置里指向这个入口。具体配置方式随版本变化建议以你所用版本的文档为准。这里要说明的是这部分是基于常见实践的补充实际配置请对照你手头的版本文档。4.3 实测中遇到的三个意外第一个意外是工具名冲突。我注册了一个叫search的工具结果和 Claude 内置的某个能力重名导致调用行为不稳定。后来改成searchInternalDocs这种带前缀的名字就正常了。所以给工具起名时加个前缀能避免冲突。第二个意外是界面退出后终端状态没恢复。ink 渲染时会切换终端到某种模式如果异常退出终端可能停留在那个模式表现为光标不见了或者输入不回显。解决办法是在界面组件卸载时确保调用清理逻辑ink 的 render 返回值里有 unmount 方法记得在合适时机调用。第三个意外是长文本换行导致布局错乱。工具返回的结果如果很长直接塞进界面里会把布局撑坏。后来我在渲染前先对文本做截断或换行处理用 string-width 计算实际宽度保证每行不超过界面宽度。4.4 调试 Mod 的实用技巧调试终端界面比调试普通代码麻烦因为输出被界面接管了。我的做法是把日志写到文件而不是打印到终端。这样界面正常渲染日志在另一个地方看互不干扰。另一个技巧是给界面加一个“调试模式”通过环境变量开启。开启后界面会在角落显示一些内部状态比如当前选中项索引、输入缓冲区内容。这在排查“为什么按键没反应”这类问题时特别有用。还有一个习惯是先写纯逻辑再套界面。比如选择列表的逻辑先用一个纯函数实现“根据按键更新索引”单独测试这个函数确认没问题了再接到 ink 组件里。这样能把逻辑 bug 和渲染 bug 分开排查起来快很多。5. 工具与界面的协作模式什么时候该用工具什么时候该画界面5.1 判断标准交互复杂度不是所有事情都值得画界面。我的判断标准是看交互复杂度。如果只是让用户确认一个“是/否”文字问一句就够了没必要画界面。如果需要用户从多个选项里选、需要展示结构化信息、需要实时反馈进度那界面就更合适。举个例子。“是否继续”这种问题Claude 直接问就行。但“从这 30 个文件里选出要处理的”这种文字列出来太长用户输编号也容易错这时候一个可滚动的选择界面就明显更好。5.2 工具负责“做事”界面负责“沟通”一个清晰的职责划分是工具负责实际的业务逻辑界面负责和用户交互。工具不应该直接渲染界面界面也不应该包含业务逻辑。两者通过数据传递来协作。比如“批量重命名文件”这个功能。工具负责扫描文件、执行重命名界面负责让用户预览将要重命名的列表、确认或取消。工具把文件列表传给界面界面把用户的选择传回工具。这样职责清晰也方便单独测试。5.3 一个协作流程的完整拆解假设我们要做一个“代码审查助手”的 Mod。流程是这样的用户对 Claude 说“帮我审查一下这个目录的代码”。Claude 调用“扫描目录”工具拿到文件列表。Claude 判断文件较多调用“展示选择界面”工具把文件列表传进去。界面渲染出可多选的列表用户勾选几个文件确认。界面把选中的文件返回给 Claude。Claude 对每个选中文件调用“审查代码”工具。审查结果汇总后Claude 用文字呈现给用户。这个流程里工具和界面交替出现各司其职。用户感觉是在和一个助手对话但背后是工具和界面在配合。5.4 避免过度设计我见过有人把简单功能做得很复杂明明一句话能问清楚的事非要画个界面。结果是开发成本高用户还觉得别扭。终端界面的优势在于处理“结构化选择”和“实时反馈”不擅长表达复杂语义。语义沟通交给 Claude 的文字能力界面只做它擅长的事。一个实用的原则是如果这个交互用一句话说不清楚才考虑画界面。能用文字解决的就别上界面。这样既省开发时间用户体验也更自然。6. 扩展思路把 Mods 用在你自己的场景里6.1 从重复劳动里找机会Mods 最适合的场景是你每天重复做、但又不够自动化的事情。比如每天要查几次某个内部系统的状态每次都要打开网页、登录、点几下。如果把这个查询做成一个工具Claude 一句话就能帮你查省下的时间积少成多。我自己的做法是记录一周内重复操作超过三次的事情然后挑一个做成工具。不用一次做很多做一个用一个慢慢积累。这样每个工具都是真实需求驱动的不会做完就闲置。6.2 把现有脚本包装成工具如果你已经有一些写好的脚本包装成工具是最快的路径。脚本的逻辑不用改只需要加一层描述文件和 handler把输入输出对接好。这样你原来的脚本资产就接入了 AI 工作流。包装时要注意输入输出的格式。脚本可能接受命令行参数工具则接受结构化输入。中间需要一个转换层把结构化输入转成命令行参数再把脚本输出转成结构化结果。这层转换不复杂但要认真处理边界情况比如参数为空、脚本报错等。6.3 界面扩展的想象空间终端界面的想象空间比很多人以为的大。除了选择列表还可以做进度条、表格、树形结构、甚至简单的图表用字符拼。比如一个“监控面板”实时显示几个指标的变化用字符画个简单的折线图在终端里就能看。不过要克制。终端界面的表达能力有限硬要做复杂图表效果不如直接生成图片。界面的价值在于“轻量、快速、不离开终端”超出这个范围的用别的工具更合适。6.4 维护和迭代的建议Mods 写多了之后维护是个问题。我的建议是给每个 Mod 写一个简短的 README说明它做什么、怎么用、依赖什么。这样过几个月回来看还能快速想起来。另外工具的描述文件要跟着功能更新。改了工具行为但忘了改描述会导致 Claude 调用时判断失误。把描述文件当成代码的一部分来维护改功能时同步改描述。最后分享一个小心得先做最小可用版本再迭代。不要一上来就设计一个功能齐全的 Mod先做一个能跑通的最小版本用起来再根据实际感受加功能。这样能避免做了一堆用不上的东西也能更快拿到反馈。