1. 从终端里长出来的“外挂”：Claude Code Mods 到底在解决什么问题
第一次听到 Claude Code Mods 这个词，很多人会下意识把它当成某种插件市场里的扩展包。其实不是。它更像是一套“给 Claude Code 这个终端里的编程助手加装工具、改界面、换交互方式”的机制。你可以把它理解成：Claude Code 本身是一个能在终端里读写文件、跑命令、理解代码库的智能体，而 Mods 就是在这个智能体外面套一层你自己写的壳，让它多出一些原本没有的能力，或者把原本黑漆漆的命令行输出变成有边框、有颜色、有布局的界面。
这件事为什么值得单独拿出来讲？因为绝大多数人用 Claude Code 的方式非常原始：装好、登录、在项目目录里敲一句需求，然后看着它一行行吐文字。用久了你会发现两个痛点。第一，它虽然能跑命令，但很多垂直场景的工具它并不直接支持，比如你想让它调用某个内部脚本、某个特定的代码检查器、某个自定义的数据处理流程，默认状态下它不会主动去用。第二，终端输出是纯文本流，信息密度低，长任务跑起来你根本不知道它现在处于哪个阶段，只能干等。Mods 恰好就是冲着这两个痛点去的：一个管“能力扩展”，一个管“界面呈现”。
从关键词里能看到 JS、TS、终端界面这几个词，这其实已经把技术栈框死了。Claude Code 的 Mods 体系基本是围绕 JavaScript 和 TypeScript 构建的，你写的工具、你画的界面，最终都跑在 Node 环境里。终端界面这块，常见做法是用类似 Ink 这样的库，它让你用 React 的组件化思路去写命令行 UI，把原本用 console.log 拼出来的东西变成真正的布局。所以如果你有前端背景，尤其是写过 React 的，上手 Mods 会比纯后端的人快很多，因为思维模型是通的。
那它适合谁？我觉得有三类人最该关注。第一类是每天泡在终端里的开发者，想让 Claude Code 更贴合自己的项目流程；第二类是工具链维护者，想把团队内部的脚本、检查规则包装成 Claude 能直接调用的能力；第三类是对终端 UI 有兴趣的人，想试试用 JS/TS 在命令行里画出像模像样的界面。如果你只是偶尔用 Claude Code 问几个问题，那 Mods 对你来说可能有点重，但了解一下它的思路没坏处，因为这套“给智能体加工具”的模式正在变成一种通用范式。
需要先说明一点：下面涉及的具体 API 名称、目录结构、配置字段，有一部分是基于 Claude Code 常见实践和同类终端智能体工具的通用做法做的合理推演。因为 Mods 这套东西还在快速演进，不同版本之间细节会有出入，你在实操时要以自己环境里的实际文档和报错为准。但整体思路和踩坑点是通用的，这部分我可以拍着胸脯讲。
2. 拆开 Mods 的两条主线：工具注入与终端渲染
2.1 工具注入：让 Claude 从“会聊天”变成“会干活”
Claude Code 默认能做的事，是读文件、写文件、执行 shell 命令、搜索代码。这些是通用能力。但真实项目里，通用能力往往不够用。举个例子，你们团队有一套自研的接口文档生成脚本，每次改完代码都要手动跑一遍。你当然可以在对话里让 Claude “执行 node scripts/gen-doc.js”，它也能跑。但问题是它不知道这个脚本的存在，不知道什么时候该跑，也不知道跑完要看什么输出。工具注入要解决的，就是把这类能力注册给 Claude，让它知道“有这么个工具，输入是什么，输出是什么，什么场景下该用”。
这套机制的核心是一个工具描述对象。通常包含几个字段：工具名、功能描述、参数 schema、以及真正的执行函数。描述字段特别关键，因为 Claude 是靠自然语言描述来判断要不要调用这个工具的。你写得含糊，它就不知道该用；你写得精准，它在合适场景下就会主动触发。我见过太多人工具写好了但描述写得像天书，结果 Claude 从来不调用，然后抱怨“这功能没用”。问题不在功能，在描述。
参数 schema 一般用 JSON Schema 或者 TypeScript 类型来定义。用 TS 的好处是类型即文档，你定义好入参类型，运行时还能做校验。执行函数就是普通异步函数，接收参数、干活、返回结果。返回结果建议结构化，不要返回一大坨无格式文本，因为 Claude 要解析这个结果来决定下一步。你返回得越清晰，它的后续行为越靠谱。
这里有个容易忽略的点：工具的执行环境。你的工具函数跑在什么上下文里？能不能访问项目文件？能不能读环境变量？能不能发起网络请求？这些边界要在设计时就定清楚。我个人的经验是，工具尽量保持“纯”，也就是输入确定、输出确定、副作用可控。如果一个工具既要读文件又要改文件还要发请求，那它出问题时你很难定位，Claude 也会因为结果太复杂而判断失误。
2.2 终端渲染：把文字流变成有结构的界面
第二条主线是界面。Claude Code 在终端里跑，终端本身只认字符。但字符也能玩出花，关键看你用什么方式组织。纯 console.log 是线性的，从上到下刷屏，信息一多就找不到重点。而用 Ink 这类库，你可以把终端当成一个画布，用 Flexbox 布局、用组件嵌套、用状态驱动重渲染。这就从“打印日志”升级成了“渲染界面”。
为什么要在终端里画界面？因为 Claude Code 执行任务是有过程的。它可能先分析需求，再读几个文件，再改代码，再跑测试，再根据测试结果调整。这个过程如果只是文字流，你看到的就是一大段一大段的输出，很难一眼看出“现在到哪一步了”。但如果你做一个状态面板，左边显示当前阶段，右边显示正在操作的文件，底部显示进度条，那体验完全不一样。你扫一眼就知道它在干嘛，不用去翻历史输出。
Ink 的工作方式和 React 很像。你写组件，组件接收 props，内部用 useState 管理状态，用 Box 和 Text 做布局和文本。区别在于最终渲染目标不是 DOM，而是终端的字符网格。这意味着你不能用 CSS，只能用它提供的布局属性，比如 flexDirection、padding、margin、borderStyle。刚开始会有点别扭，但写几个组件之后就习惯了。而且因为复用了 React 的心智模型，状态管理和组件拆分那套经验可以直接迁移。
终端界面的一个硬约束是刷新频率和性能。终端不像浏览器有 GPU 加速，频繁重渲染会闪屏或者卡顿。所以状态更新要节流，不要每来一个字符就 setState。另外终端宽度是动态的，用户可能随时调整窗口大小，你的布局要能响应这种变化，不能写死宽度。这些细节在浏览器里可能不是问题，在终端里就是实打实的坑。
3. 用 TypeScript 写一个可被 Claude 调用的工具：从零到跑通
3.1 项目初始化与依赖选择
动手之前先把工程结构定下来。我建议单独建一个目录，不要混在主项目里，因为 Mods 的依赖和主项目可能冲突。初始化用 npm init 或者 pnpm init 都行，看你习惯。然后装几个核心依赖：TypeScript 做类型，tsx 或 ts-node 做运行时，Ink 做界面（如果你要做 UI），zod 做参数校验。zod 这个库值得单独提一句，它和 TypeScript 配合得非常好，你可以用一套 schema 同时得到类型和运行时校验，省得写两遍。
tsconfig 的配置有几个点要注意。target 建议 ES2022 或更高，因为 Node 版本现在普遍不低。module 用 NodeNext 或者 ESNext，看你的运行方式。strict 一定要开，写工具代码最怕类型松散，后面出问题很难查。另外 outDir 和 rootDir 要配好，不然编译产物路径会乱。如果你用 tsx 直接跑 TS 不编译，那 outDir 可以先不管，但生产环境还是建议编译成 JS 再跑，启动更快。
依赖版本这块，我踩过的坑是 Ink 的大版本升级会有 breaking change。比如从 v3 到 v4，某些 props 名字变了，布局行为也有调整。所以锁定版本很重要，package.json 里不要用 ^ 让它自动升大版本。同理，Claude Code 相关的 SDK 如果存在，也要锁版本，因为它的接口可能随版本变。我一般会在项目里放一个 .nvmrc 指定 Node 版本，再在 README 里写清楚依赖版本，避免换台机器就跑不起来。
3.2 定义工具描述与参数 schema
工具描述对象是整个 Mods 的核心。我习惯先写 schema，再写描述，最后写执行函数。schema 用 zod 定义，比如一个“统计代码行数”的工具，入参可能是目录路径和文件扩展名。zod 写出来大概是这样：z.object({ dir: z.string(), ext: z.string().optional() })。然后从 schema 推导出 TS 类型，执行函数直接用这个类型，参数就不会错。
描述字段要写成“给 Claude 看的说明书”。不要写“统计行数”这种四个字的描述，太简略。要写成“统计指定目录下指定扩展名文件的总行数，用于评估代码规模，输入目录路径和可选的文件扩展名，返回总行数和文件数量”。这样 Claude 在判断是否调用时，能明确知道这个工具干什么、什么时候用、返回什么。描述里最好带上使用场景，比如“当用户询问代码规模或需要评估工作量时使用”。
参数 schema 里的每个字段也要有描述。zod 支持 .describe() 方法，给字段加说明。比如 dir 字段描述成“要统计的目录绝对路径”，ext 描述成“文件扩展名，如 .ts，不传则统计所有文件”。这些描述会进入工具定义，Claude 能看到。字段是否必填也要想清楚，能选填的就选填，减少 Claude 的决策负担。必填字段太多，它可能因为凑不齐参数而放弃调用。
还有一个细节是工具名的命名。建议用动词加名词的形式，比如 countLines、genDoc、checkStyle，全小写或者驼峰都行，但要统一。不要用中文名，也不要用带空格的名称，因为工具名在内部可能被当作标识符处理。命名要能自解释，看到名字大概知道干什么，这样即使描述写得一般，Claude 也能靠名字猜个八九不离十。
3.3 执行函数的编写与错误处理
执行函数是真正干活的地方。它接收经过校验的参数，返回结果。这里有几个原则。第一，函数要异步，因为可能涉及文件 IO 或网络请求。第二，要有超时控制，不能让一个工具卡死整个流程。第三，错误要捕获并返回结构化错误信息，而不是直接抛异常。因为 Claude 需要知道“这个工具失败了，失败原因是什么”，它才能决定是重试、换工具还是告诉用户。
返回结果的格式我建议统一成 { success: boolean, data?: any, error?: string }。成功时 data 放具体结果，失败时 error 放原因。data 内部再按工具语义组织，比如统计行数的工具返回 { totalLines: number, fileCount: number }。这样 Claude 解析起来很轻松。不要返回纯字符串，因为字符串没有结构，Claude 还得猜。也不要把所有信息塞进一个长文本，那样它抓不住重点。
错误处理要区分“可恢复”和“不可恢复”。比如目录不存在，这是可恢复的，Claude 可以问用户要正确路径。比如权限不足，这也是可恢复的，可以提示用户改权限。但如果是工具内部逻辑 bug，那就是不可恢复的，应该返回明确的错误码和堆栈摘要，方便排查。我一般会在执行函数外面包一层 try-catch，catch 里把 error.message 和 error.stack 的前几行返回。堆栈不要全返回，太长会污染上下文。
还有一个实战经验：工具执行时间要控制。如果一个工具要跑几十秒，Claude 在等待期间是阻塞的，用户体验很差。这种情况要么把工具拆成“启动任务”和“查询状态”两个工具，要么在工具内部做流式返回。但流式返回对 Claude 的解析能力有要求，不是所有版本都支持。稳妥做法是拆成两个工具，启动工具立即返回任务 ID，查询工具根据 ID 返回进度。这样 Claude 可以轮询，用户也能看到进展。
4. 在终端里画界面：Ink 组件化布局的实操细节
4.1 从 console.log 到组件树的思维转换
用 Ink 写界面，最大的障碍不是 API，是思维转换。以前你写 console.log，是“我在这里打印一行，那里打印一行”，顺序执行，线性输出。现在你要想的是“整个界面由哪些组件组成，每个组件在什么位置，状态变化时哪些组件需要重渲染”。这是从命令式到声明式的转变，写过 React 的人会觉得很自然，没写过的人需要适应一下。
Ink 的核心组件就几个：Box 是容器，负责布局；Text 是文本，负责显示内容；useState 管理状态；useEffect 处理副作用。布局靠 Box 的 flexDirection、justifyContent、alignItems 这些属性，和 CSS Flexbox 几乎一样。比如你要做一个左右分栏，外层 Box 设 flexDirection="row"，里面两个 Box 各占一半，用 flexGrow={1}。要加边框就设 borderStyle="round"，终端里就会画出圆角边框。
文本样式方面，Text 组件支持 color、backgroundColor、bold、italic、underline 这些属性。颜色可以用颜色名，也可以用 hex 值，但要注意终端对颜色的支持程度不一样。有些终端只支持 16 色，有些支持 256 色，有些支持真彩色。稳妥做法是用基础颜色名，或者用 chalk 这样的库做降级处理。我一般会在启动时检测终端能力，然后决定用哪套配色。
状态管理这块，Ink 组件内部用 useState 就够了。但如果多个组件要共享状态，就得把状态提升到父组件，或者用 Context。我倾向于把状态集中在一个顶层组件里，通过 props 往下传。这样数据流清晰，调试也方便。不要过早引入复杂的状态管理库，终端应用的状态通常没那么复杂，useState 加 props 足够应付大多数场景。
4.2 布局、边框与颜色：让终端界面不丑的三个要点
终端界面要好看，其实就三件事：对齐、留白、配色。对齐靠布局，留白靠 padding 和 margin，配色靠克制。先说对齐。终端是等宽字符网格，所以对齐比浏览器里更容易做到精确。但要注意中文字符占两个字符宽度，如果你混用中英文，对齐会乱。解决办法是统一用英文，或者用专门的宽度计算库处理中文。我一般界面文案用英文，避免宽度问题。
留白这块，Box 的 padding 和 margin 和 CSS 里含义一样。padding 是内边距，margin 是外边距。终端里空间有限，padding 不要给太大，一般 1 就够。边框会占字符，加了边框之后内容区域会变小，布局要相应调整。borderStyle 有 single、double、round、bold 几种，round 最柔和，single 最省空间。我常用 round 做面板，single 做分隔线。
配色是最容易翻车的地方。终端背景色可能是黑的也可能是白的，你的前景色要保证在两种背景下都能看清。我一般用亮色系做前景，比如 cyan、green、yellow，避免用深蓝、深灰这种在暗背景下看不清的颜色。强调信息用 bold 加颜色，普通信息用默认色。不要超过三种颜色，多了就花。状态指示可以用颜色区分，比如绿色表示成功，红色表示失败，黄色表示进行中，但红色在有些终端里偏暗，可以用 brightRed。
还有一个细节是刷新。Ink 默认会在状态变化时重渲染整个组件树，但终端渲染有开销。如果状态更新很频繁，比如每秒好几次，界面会闪。解决办法是用 useMemo 缓存计算结果，用 useCallback 缓存回调，减少不必要的重渲染。另外可以用 throttle 或 debounce 控制状态更新频率，比如进度更新每 200 毫秒一次就够了，没必要每来一个字节就更新。
4.3 处理终端尺寸变化与键盘输入
终端窗口大小是会变的，用户可能随时拖拽调整。Ink 提供了 useStdout 和 useStderr 钩子，可以拿到输出流，监听 resize 事件。拿到新的列数和行数后，更新状态，布局会自动重算。但要注意，如果布局里有写死的宽度，resize 后会溢出或者留白。所以宽度尽量用百分比或者 flexGrow，不要写死。行数方面，如果内容超过终端高度，要考虑滚动或者分页，不能让它无限往下刷。
键盘输入是交互的关键。Ink 的 useInput 钩子可以监听按键。你可以用它做快捷键，比如按 q 退出，按 r 刷新，按方向键切换面板。但要注意，终端里的按键事件和浏览器不一样，有些组合键收不到，有些键的表示方式不同。比如 Ctrl+C 通常被终端本身捕获用于中断，你的应用不一定能拿到。所以快捷键设计要避开系统级组合，用单键或者简单的组合。
输入处理还要考虑焦点。如果界面上有多个可交互区域，你得知道当前焦点在哪。Ink 没有内置的焦点管理，需要自己实现。简单做法是用一个 state 记录当前焦点索引，按键时更新索引，渲染时根据索引高亮对应区域。复杂一点可以用 Context 做焦点树，但终端应用通常不需要那么复杂。我一般就一个焦点状态，够用了。
还有一个坑是输入法。终端里输入中文时，输入法候选框可能和你的界面重叠，导致显示混乱。这个问题没有完美解法，只能建议用户在输入时注意，或者你的应用尽量少让用户输入中文。如果必须输入，可以在输入区域留出足够空间，避免候选框遮挡关键信息。
5. 把工具和界面接起来：Mods 的运行链路与调试方法
5.1 注册、发现与调用的完整链路
工具写好了，界面也画好了，接下来要把它们接起来。链路大概是这样的：Claude Code 启动时加载 Mods 配置，配置里声明了有哪些工具、界面入口在哪。Claude 在对话过程中，根据工具描述判断是否需要调用某个工具。如果需要，它生成调用请求，请求经过参数校验后传给执行函数。执行函数返回结果，结果再回传给 Claude，Claude 根据结果决定下一步。界面部分则是独立渲染的，它监听 Claude 的状态变化，把状态映射成 UI。
这个链路里最容易出问题的是“发现”环节。Claude 怎么知道有哪些工具？靠配置声明。配置通常是一个 JSON 或 TS 文件，里面列出工具模块的路径。路径写错、模块导出格式不对、依赖缺失，都会导致工具加载失败。我建议在启动时加一个自检逻辑，把所有声明的工具都尝试加载一遍，加载失败的打印明确错误。这样比等到 Claude 调用时才发现问题要好得多。
调用环节的坑在于参数传递。Claude 生成的参数是自然语言理解后的结果，可能类型不对、可能缺字段、可能多字段。所以参数校验必须严格，校验失败要返回清晰的错误信息，告诉 Claude 哪个字段不对、期望什么类型。Claude 看到错误后通常会重试，如果错误信息清晰，它第二次就能传对。如果错误信息含糊，它可能反复错，浪费轮次。
结果回传环节要注意上下文长度。工具返回的结果会进入 Claude 的上下文，如果结果太大，会挤占对话空间，甚至导致截断。所以工具返回要精简，只返回必要信息。比如统计行数，返回总数和文件数就够了，不要返回每个文件的明细。如果确实需要明细，可以返回一个摘要加一个文件路径，让 Claude 需要时再去读。
5.2 日志、断点与常见报错定位
调试 Mods 比调试普通 Node 程序麻烦，因为它涉及 Claude 和你的代码之间的交互。我的做法是分层打日志。第一层在工具入口，记录“收到调用请求，参数是什么”。第二层在执行函数内部，记录“开始执行，关键步骤”。第三层在返回前，记录“执行完成，返回什么”。这样出问题时，你能看到请求有没有到、执行到哪一步、返回了什么。
日志输出要注意不要污染界面。如果你在用 Ink 画界面，console.log 会打乱布局。解决办法是把日志写到文件，或者用 Ink 提供的静态输出区域。我一般写文件，路径放在临时目录，调试时 tail -f 看。生产环境可以关掉详细日志，只保留错误日志。
常见报错有这么几类。第一类是模块加载失败，通常是路径错或依赖没装，看错误堆栈第一行就能定位。第二类是参数校验失败，看是哪个字段不符合 schema，调整 schema 或让 Claude 重新生成。第三类是执行超时，看是工具本身慢还是卡住了，加超时和日志。第四类是返回结果解析失败，通常是返回格式不符合预期，检查返回结构。第五类是界面渲染异常，通常是布局属性用错或者状态更新导致死循环，用 React DevTools 类似的思路排查。
断点调试方面，Node 的 --inspect 标志可以用，配合 Chrome DevTools 或者 VS Code 的调试器。但因为 Claude Code 是独立进程，你的工具可能跑在子进程里，断点不一定能挂上。更实际的做法是加临时日志，或者写单元测试单独测执行函数。执行函数最好是纯函数或者接近纯函数，这样测试起来容易。我一般会给每个工具写几个测试用例，覆盖正常输入、边界输入、错误输入，跑通了再注册给 Claude。
6. 几个真实场景下的取舍与踩坑记录
6.1 工具粒度：太粗和太细都难受
工具粒度是个需要反复权衡的问题。太粗，比如一个工具干十件事，Claude 很难判断什么时候调用，调用时参数也复杂，容易出错。太细，比如每个小操作一个工具，Claude 要连续调用好几个才能完成一件事，轮次多、慢、容易中断。我的经验是，一个工具对应一个“用户可理解的完整动作”。比如“生成接口文档”是一个动作，“统计代码行数”是一个动作，“检查代码风格”是一个动作。每个动作内部可以复杂，但对外是一个清晰的语义单元。
判断粒度是否合适，有个简单方法：看工具描述能不能用一句话说清楚，且这句话里没有“并且”“然后”这种连接词。如果需要连接词，说明它其实是多个动作，应该拆开。反过来，如果两个工具的描述高度重叠，调用场景几乎一样，那可能应该合并。我一般会先粗后细，先写一个大工具跑通流程，发现哪里 Claude 老是用错，再把那部分拆出来。
6.2 界面刷新频率与性能的平衡
前面提过刷新频率，这里展开说。终端渲染比浏览器贵，因为每次重渲染都要重写字符网格。如果状态更新太频繁，比如每毫秒一次，终端会卡到没法用。我实测下来，进度类更新 100 到 200 毫秒一次比较合适，人眼能感知到变化，又不会太频繁。文本类更新可以更慢，500 毫秒一次都行。关键是找到“用户觉得流畅”和“终端扛得住”的平衡点。
实现上可以用一个定时器，把高频状态更新攒起来，定时批量更新。比如工具执行过程中不断产生日志，你不要每来一条就 setState，而是先存到一个 ref 里，每 200 毫秒把 ref 里的内容合并后 setState 一次。这样渲染次数大幅减少，界面也稳定。React 的 batched updates 在 Ink 里也生效，但跨异步边界的更新不一定批处理，所以手动攒更可靠。
还有一个性能点是组件树的深度。Ink 渲染是递归的，组件树太深会有开销。尽量扁平化，不要为了抽象而抽象。一个面板一个组件，面板里的区块用 Box 直接嵌套，不要每个区块都包一层自定义组件。自定义组件适合有独立状态或复用逻辑的场景，纯布局用 Box 就够了。
6.3 跨平台差异：Windows、macOS、Linux 下的表现
终端环境跨平台差异比想象中大。macOS 和 Linux 的终端通常支持真彩色和 Unicode 边框，Windows 的默认终端（cmd）支持有限，但 Windows Terminal 好很多。如果你的用户可能用 cmd，那边框字符和颜色都要做降级。Unicode 边框在 cmd 里可能显示成乱码，那就退回 ASCII 边框，用 +、-、| 画。颜色方面，cmd 只支持 16 色，真彩色会映射到最近的颜色，可能不好看。
路径处理也是坑。Windows 用反斜杠，Unix 用正斜杠。工具里涉及路径拼接时，用 path 模块的 join 和 resolve，不要手动拼字符串。环境变量读取也要注意，Windows 的环境变量名不区分大小写，Unix 区分。文件权限方面，Windows 的权限模型和 Unix 不同，涉及权限检查的工具要做平台判断。
换行符是另一个经典问题。Windows 用 \r\n，Unix 用 \n。如果你读写文件时不做转换，可能在另一个平台显示异常。Node 的 fs 模块默认不做转换，需要自己处理。我一般统一用 \n，读取时把 \r\n 替换成 \n，写入时按平台决定。但如果是二进制文件，就不能这么干，要按 Buffer 处理。
6.4 安全边界：工具能碰什么、不能碰什么
工具注入给了 Claude 更多能力，也带来了安全边界问题。你的工具能读文件、能执行命令、能发请求，如果被滥用，后果可能很严重。所以设计工具时要有最小权限原则。只读的工具就不要给写权限，只操作特定目录的就不要给全盘访问。参数里涉及路径的，要做校验，防止路径穿越。涉及命令执行的，要避免拼接用户输入，防止命令注入。
我一般会在工具执行前加一层权限检查。比如工具声明需要“读项目文件”权限，运行时检查当前上下文是否有这个权限。没有就拒绝，返回明确错误。这样即使 Claude 判断失误调用了不该调的工具，也不会造成实际损害。权限模型可以简单点，用字符串标签就行，不用搞太复杂。
还有一点是网络请求。工具如果要发请求，要限制目标域名，避免被诱导访问恶意地址。超时也要设，防止卡死。返回内容要过滤，不要把敏感信息带回给 Claude。如果工具涉及凭证，凭证不要放在工具代码里，用环境变量或者密钥管理服务。工具日志里也不要打印凭证，防止泄露。
7. 从能跑到好用：Mods 工程的持续维护思路
工具和界面跑通只是第一步，后面还有维护。维护的核心是“可发现、可测试、可扩展”。可发现是指工具描述要持续优化，根据 Claude 的实际调用情况调整描述措辞。我一般会记录 Claude 调用工具的成功率和误调用率，成功率低的工具回去改描述，误调用多的工具检查是不是和其他工具语义重叠。这个过程是迭代的，没有一劳永逸。
可测试是指每个工具都要有测试。测试分两层，一层是执行函数的单元测试，一层是工具描述的“语义测试”。语义测试比较新，就是拿一些典型用户输入，看 Claude 会不会正确调用这个工具。这个可以手动做，也可以半自动化。我一般会攒一批典型 query，每次改完描述跑一遍，看调用行为有没有变差。这比纯单元测试更贴近实际使用。
可扩展是指新增工具的成本要低。如果每加一个工具都要改一堆配置、写一堆样板代码，那没人愿意加。我一般会做一个工具注册的辅助函数，传入名称、描述、schema、执行函数，自动生成注册对象。这样新增工具就是填几个字段的事。界面方面，把通用组件抽出来，比如面板、状态条、日志区，新界面直接复用。这样扩展起来快，风格也统一。
最后说个心态问题。Mods 这套东西还在演进，今天能用的 API 明天可能就变了。所以不要把它当成一个稳定不变的产品来依赖，而是当成一个可以随时调整的实验场。保持代码模块化，把和 Claude Code 交互的部分隔离出来，这样底层变了，你只需要改隔离层，工具逻辑和界面逻辑不用动。这个隔离思路在我用过的各种智能体扩展体系里都适用，算是通用经验了。
