如果你做过智能体或者自动化工具相关的项目对 skills 这个词一定不陌生。它在最近一年的个人效率工具、智能助手类项目里出现频率极高已经从一个普通英文单词变成了具体的工程范式把一组可复用的能力封装成独立模块统一放进一个叫 skills 的目录让主程序通过描述文件去发现、加载和调用。这套机制我自己在多个项目里反复用过从最初单体脚本里堆if-else到后来抽出完整的技能库框架可以说踩过不少坑也积累了一些可复用的设计经验。这篇文章我打算完整拆解一遍“如何从零搭建一套属于自己的 Skills 技能库”。它解决的核心问题是当你需要给助手、机器人或者自动化系统持续添加新能力时如何做到不改主程序、不破坏旧功能、让每个能力独立演进并且能方便地分享给其他人直接使用。非常适合正在做个人助手类项目、想系统整理自己自动化脚本的开发者参考。文章里我会给出目录结构、清单文件规范、加载器实现、三个真实技能示例以及我在调试和部署中总结的排查技巧。如果你手上正好有这类项目可以直接照着抄作业。1. 为什么要做一套可插拔的Skills技能库先聊点实际的。早些年我做自动化脚本习惯把所有功能塞进一个入口文件里先判断用户发来的关键词再走对应的分支函数。功能少的时候确实爽一个文件从头看到尾逻辑全在脑子里。但功能一旦超过十个局面就失控了——新增一个指令要小心翼翼改主流程生怕动到别人的变量某个功能崩了整个进程跟着遭殃想删掉一个没用的功能代码里有可能还留着看不见的依赖。这时候你才会意识到模块化不是优雅不优雅的问题是能不能继续维护下去的问题。1.1 “Skills”机制到底解决了什么问题Skills 机制本质上是一种插件化设计。它的思路是把每个独立能力做成一个目录目录里面放两样东西描述这个能力是什么、需要什么参数的清单文件以及真正干活的实现文件。主程序不关心每个技能内部怎么写的它只做三件事扫描目录、读取清单、注册调用入口。用生活里的事情来类比就像手机系统和 App 的关系。手机出厂时没有把所有功能都内置进去而是给你一个应用商店。你想用导航装一个导航 App想用记账装一个记账 App。系统本身只需要知道“你装了哪些应用、每个应用叫什么、图标长什么样”真正打开后的界面完全由应用自己负责。Skills 机制就是给智能体或者自动化系统装 App 的那套框架技能目录就是应用商店里的货架。这套设计带来的收益非常直接新能力上线不影响老功能。加一个技能只是往目录里多放一个文件夹主程序扫描时自然会发现它跟其他技能互不干扰。技能之间天然隔离。每个技能有自己的子目录、自己的依赖声明、自己的实现文件出了问题单独摘除即可。可以批量复用。今天写的天气查询技能换个项目只要把目录复制过去就能继续用省去重复开发。协作门槛变低。你不再需要看懂整个主程序的内部结构只要按照清单文件格式写一个目录就能参与贡献能力。这些收益单独看每条都很朴素但合在一起会让项目的演进节奏完全不一样。我从单体脚本切换到技能库结构之后最明显的感受是“加功能”这件事从危险操作变成了机械操作。1.2 目录结构与清单文件设计思路技能库的目录结构并不复杂。我推荐一个相对通用、也方便后续扩展的布局skills/ weather/ SKILL.md main.py requirements.txt memo/ SKILL.md main.py remind/ SKILL.md main.py tasks.json common/ utils.py每个技能至少包含一个 SKILL.md 清单文件和一个实现文件。SKILL.md 我用的是 Markdown 加 YAML front matter 的组合格式也就是文件顶部用---包裹一段 YAML 元数据下面写给人看的完整说明。选择这种格式而不是单独的 JSON 或 YAML主要因为两份信息合并在同一个文件里复制技能目录时不会漏文件人和机器读起来都方便。常见的 SKILL.md 长这样--- name: weather description: 查询指定城市当前天气 version: 1.0.0 author: anonymous license: MIT inputs: city: type: string required: true description: 城市名称如 北京 unit: type: string enum: [celsius, fahrenheit] default: celsius description: 温度单位 --- # weather 技能 查询当前天气支持指定城市和温度单位。这里有几个字段值得展开说一下。name是技能的全局唯一标识加载器会用它在注册表里做 key重复的 name 会导致后加载的技能覆盖前面的所以命名一定要有区分度。description必须写清楚“这个技能到底做什么”因为主程序需要靠它判断什么场景下该调用哪个技能写得含含糊糊很容易误调度。inputs字段是清单文件里最重要的一部分。它声明了这个技能需要哪些输入参数每个参数什么类型、是否必填、有没有默认值、取值范围是什么。为什么必须在清单文件里声明得这么细因为主程序要根据这些声明做三件事对外生成统一的调用入口、调用时做参数校验和类型转换、在其他技能编排时准确判断能传入什么数据。很多技能库项目后期出现参数对不上、运行时才发现缺字段的问题根源都在一开始的 inputs 声明不完整。2. 核心机制拆解加载器、描述文件与执行器技能库的落地核心就三个部分加载器负责发现技能描述文件负责说明技能执行器负责运行技能。这三者的关系很像餐厅的运作加载器是引导员负责把菜品从后厨端到菜单上描述文件是菜单上的菜品介绍让食客知道这道菜是什么味执行器是后厨本身真正把菜做出来。2.1 描述文件的字段规范与参数声明我在规划字段规范时给自己定了几条原则字段尽量少语义尽量清楚可选项尽量有默认值。除了上面提到的基础字段我还会加两个可选字段。一个是tags用来给技能打标签方便按场景检索。另一个是outputs声明技能返回什么结构。outputs灵活度很高不需要特别严格但至少要告诉调用方返回的是 JSON 对象还是原始文本。这个字段在编排多个技能时非常有用后面讲技能编排的时候会详细说。参数声明这块我吃过亏的地方是type的取值设计。最早我只用 string 和 number 两种后来发现大量参数实际上是字符串枚举和布尔开关导致调用方要想很久才能传对参数。现在我的规范里固定支持五种类型类型说明适用场景string任意文本名称、关键词、路径number整数或浮点数数量、金额、时间戳boolean逻辑真或假开关、标记位enum枚举值列表类型选择、模式切换list数组元素为基础类型批量数据、集合输入给参数声明一个合理的default也要养成习惯。用户不传这个参数时加载器会用默认值填充技能内部就不需要写一大堆“如果参数不存在就怎样”的防守代码。不过注意默认值选什么要想清楚宁可默认行为保守也不要让默认值导致意外副作用。比如天气技能的unit默认设为celsius对绝大多数用户是合理的但如果是给美国市场用的项目默认值就该反过来。2.2 加载与注册流程的代码实现加载器的实现并不复杂但有一些细节值得抠。我用 Python 做示例核心逻辑是遍历skills目录下所有子目录逐个读取 SKILL.md解析 front matter然后通过动态导入把技能实现注册到内存里的一个注册表。# loader.py import importlib from pathlib import Path import yaml def parse_manifest(skill_dir): manifest_path skill_dir / SKILL.md content manifest_path.read_text(encodingutf-8-sig) if not content.startswith(---): raise ValueError(f{skill_dir}: SKILL.md 缺少 YAML front matter) parts content.split(---) if len(parts) 3: raise ValueError(f{skill_dir}: SKILL.md 格式不完整) manifest yaml.safe_load(parts[1]) if not manifest.get(name): raise ValueError(f{skill_dir}: 缺少 name 字段) return manifest def discover_skills(skills_dirskills): registry {} base Path(skills_dir) if not base.exists(): return registry for entry in sorted(base.iterdir()): if not entry.is_dir(): continue if not (entry / SKILL.md).exists(): continue try: manifest parse_manifest(entry) module_path f{skills_dir}.{entry.name}.main module importlib.import_module(module_path) if not hasattr(module, run): raise ValueError(f{entry.name}: main.py 缺少 run 函数) registry[manifest[name]] { manifest: manifest, handler: module.run, dir: str(entry), } except Exception as exc: print(f[loader] 跳过技能 {entry.name}: {exc}) return registry代码里有几个细节是我自己吃过亏后加进去的。第一读取文件用了utf-8-sig编码而不是utf-8。Windows 下很多人用记事本保存文件会自动带上 BOM 头用utf-8读会把\ufeff混进第一个字符导致 YAML 解析失败。这个排查过程当年浪费了我不少时间。第二sorted(base.iterdir())保证扫描顺序是稳定的这在团队协作时很重要——技能加载顺序会影响同名技能的覆盖结果固定顺序至少让问题可复现。第三加载过程中任何异常都被捕获并输出提示而不是直接让整个程序崩溃。一个技能文件写坏了不该影响其他正常技能运行这个思想贯穿了整个设计。动态导入用的是importlib.import_module路径skills.weather.main要求skills目录下有一个__init__.py文件或者整体作为命名空间包运行。我在实际项目中习惯在技能库目录里放一个空的__init__.py这样做的好处是让 IDE 能正确识别模块跳转到代码时的体验会好很多。2.3 执行器与安全边界加载器把技能注册进来之后执行器就是负责安全调用的那层。虽然很多技能的代码是信任的但技能库里难免有一天会放进从别处复制来的脚本执行器这一层就应该把危险拦住。我在执行器里固定做四件事超时控制、输出大小限制、工作目录隔离、异常归一化。超时控制是最重要的一个技能如果内部发起了网络请求而对方迟迟不响应没有超时兜底的话整个主程序会一直卡在那儿其他技能也跟着没法用。# executor.py import threading import time class SkillTimeout(Exception): pass def run_with_timeout(handler, ctx, timeout10): result_holder {} error_holder {} def target(): try: result_holder[data] handler(ctx) except Exception as exc: error_holder[error] exc thread threading.Thread(targettarget, daemonTrue) thread.start() thread.join(timeout) if thread.is_alive(): raise SkillTimeout(f技能执行超过 {timeout} 秒已终止) if error in error_holder: raise error_holder[error] return result_holder.get(data)这里用的是线程加join(timeout)的方式简单直接适合大多数场景。注意线程必须是 daemon 线程否则主程序退出时子线程还在跑会造成进程无法结束。超时之后线程实际上还在后台运行只是调用方不再等待结果对于一般个人项目来说这是可接受的取舍你要追求彻底杀掉子任务就得上进程级隔离了。输出大小限制也很有必要。我之前遇到过一个技能因为内部某个接口返回格式变化把一整本小说长度的文本灌进了上下文字段直接导致后续处理变慢。执行器里加一个简单的长度判断就可以避免这种问题。工作目录隔离则是要求技能内部涉及文件操作时一律使用Path(__file__).resolve().parent作为根目录而不是直接写相对路径。因为加载器调用技能时进程的当前工作目录通常是项目根目录技能里写open(data.json)就会在错误的位置创建文件后续排查起来非常隐蔽。3. 从零实现三个真实可用的技能模块理论部分聊得差不多接下来看真实的技能实现。我选了三个最能体现技能库价值的模块天气查询、备忘记录、定时提醒。这三个技能覆盖了外部请求、文件存储、后台调度三类典型场景组合起来就是一个很实用的个人助手雏形。3.1 天气查询技能从模拟数据到真实接口天气查询技能的核心是输入城市名返回当前温度和天气状况。考虑到不少公共天气接口对个人开发者并不友好我在示例代码里做了一个两层设计默认使用内置的模拟数据只要配置了 API 密钥就自动切换为网络请求。这样你本地测试时不会因为网络问题跑不通链路。# skills/weather/main.py import json import os from datetime import datetime from pathlib import Path # 模拟城市天气数据 MOCK_WEATHER { 北京: {temp: 18, condition: 晴, humidity: 30}, 上海: {temp: 22, condition: 多云, humidity: 60}, 广州: {temp: 26, condition: 小雨, humidity: 80}, } def run(ctx): inputs ctx[inputs] city inputs.get(city, ) unit inputs.get(unit, celsius) if not city: return {ok: False, error: 缺少 city 参数} api_key os.environ.get(WEATHER_API_KEY, ) if api_key: return fetch_remote_weather(city, unit, api_key) mock MOCK_WEATHER.get(city) if not mock: return {ok: False, error: f没有找到城市 {city} 的模拟数据} temp mock[temp] if unit fahrenheit: temp round(temp * 9 / 5 32) return { ok: True, data: { city: city, temp: temp, unit: unit, condition: mock[condition], humidity: mock[humidity], update_time: datetime.now().isoformat(), }, } def fetch_remote_weather(city, unit, api_key): # 这里替换为你常用的天气服务商接口 # 注意统一返回结构与模拟数据保持一致 return {ok: True, data: {city: city, temp: 20, unit: unit, condition: 晴, humidity: 50, update_time: datetime.now().isoformat()}}注意返回结构被我统一成了{ok: ..., data: ...}或者{ok: False, error: ...}。这个设计不是随手写的——编排器需要统一处理所有技能的返回如果每个技能返回格式都不同编排层的代码就会变成一堆呆板的特判。统一返回结构相当于技能与技能之间的通信协议后面写编排器的时候你会体会到它的价值。模拟数据这个思路我建议你保留下来。不只是为了测试更是为了让技能具备降级能力。真实天气接口挂了至少还有一个兜底结果不至于让整个助手完全失效。3.2 备忘记录技能文件存储与并发写入备忘记录技能负责往本地文件里追加备忘事项支持添加、查看、删除三个操作。这个技能最大的技术点在于文件读写的安全性。直接open一个 JSON 文件反复读写在高频调用时容易遇到数据错乱的问题。# skills/memo/main.py import json import os import tempfile from pathlib import Path BASE_DIR Path(__file__).resolve().parent DATA_FILE BASE_DIR / memo_data.json def load_data(): if not DATA_FILE.exists(): return [] try: with open(DATA_FILE, r, encodingutf-8) as f: return json.load(f) except json.JSONDecodeError: return [] def save_data(items): # 原子写入先写临时文件再替换避免进程中途崩溃导致数据损坏 fd, tmp_path tempfile.mkstemp(dirstr(BASE_DIR), suffix.tmp) with os.fdopen(fd, w, encodingutf-8) as f: json.dump(items, f, ensure_asciiFalse, indent2) os.replace(tmp_path, DATA_FILE) def run(ctx): inputs ctx[inputs] action inputs.get(action, add) content inputs.get(content, ) items load_data() if action add: if not content: return {ok: False, error: 缺少 content 参数} items.append({id: len(items) 1, content: content}) save_data(items) return {ok: True, data: {id: len(items), count: len(items)}} if action list: return {ok: True, data: {items: items, count: len(items)}} if action delete: target_id inputs.get(id) if target_id is None: return {ok: False, error: 缺少 id 参数} new_items [item for item in items if item[id] ! int(target_id)] save_data(new_items) return {ok: True, data: {deleted: len(items) - len(new_items)}} return {ok: False, error: f未知操作 {action}}save_data函数里我用的是原子写入先把数据写到一个临时文件再用os.replace替换目标文件。这个过程能保证任何时刻读取那个 JSON 文件看到的要么是旧数据要么是新数据不会出现半个文件的情况。这个技巧在本地工具类技能里非常通用凡是涉及到持久化文件的项目都应该这么干。另外要注意 BASE_DIR 的获取方式。我写的是Path(__file__).resolve().parent意思是“当前代码文件所在目录”。这个写法保证了无论你从哪里启动主程序技能都能找到自己的数据文件。这个坑我提过不止一次单独拎出来再说一遍因为确实太常见了。3.3 定时提醒技能后台调度与跨技能协作定时提醒技能比前两个复杂一些因为它涉及后台线程的常驻运行。我的实现思路是技能启动时开启一个 daemon 线程每秒检查一次任务列表凡到时间的任务就调用一个回调函数把提醒内容塞给主程序的消息发送模块。# skills/remind/main.py import json import threading import time from datetime import datetime from pathlib import Path BASE_DIR Path(__file__).resolve().parent TASK_FILE BASE_DIR / tasks.json _scheduler_thread None _on_trigger None def load_tasks(): if not TASK_FILE.exists(): return [] with open(TASK_FILE, r, encodingutf-8) as f: return json.load(f) def save_tasks(tasks): import tempfile import os fd, tmp_path tempfile.mkstemp(dirstr(BASE_DIR), suffix.tmp) with os.fdopen(fd, w, encodingutf-8) as f: json.dump(tasks, f, ensure_asciiFalse, indent2) os.replace(tmp_path, TASK_FILE) def scheduler_loop(): while True: now datetime.now().isoformat() tasks load_tasks() due [t for t in tasks if t.get(time) now and not t.get(triggered)] for task in due: task[triggered] True if _on_trigger: _on_trigger(task[content]) if due: save_tasks(tasks) time.sleep(1) def start_scheduler(callback): global _scheduler_thread, _on_trigger _on_trigger callback if _scheduler_thread is None or not _scheduler_thread.is_alive(): _scheduler_thread threading.Thread(targetscheduler_loop, daemonTrue) _scheduler_thread.start() def run(ctx): inputs ctx[inputs] action inputs.get(action, add) tasks load_tasks() if action add: new_task { id: len(tasks) 1, time: inputs.get(time, ), content: inputs.get(content, ), triggered: False, } if not new_task[time] or not new_task[content]: return {ok: False, error: 缺少 time 或 content 参数} tasks.append(new_task) save_tasks(tasks) return {ok: True, data: {id: new_task[id], count: len(tasks)}} if action list: return {ok: True, data: {tasks: tasks}} return {ok: False, error: f未知操作 {action}}回调函数_on_trigger是跨技能协作的切入点。主程序在启动时调用start_scheduler把消息发送函数传进来。这样定时技能不用关心消息最终是通过日志、通知服务还是前端页面发出去只要把提醒内容交出去就行。职责边界划分得越清楚技能的组合能力就越强。后台调度线程要注意一个问题daemon 线程在主程序退出时会立即终止不保证任务完整执行。如果你需要“程序退出前保存所有未触发任务”这样的强保证就得改成前台线程并在退出时做处理。个人项目一般用 daemon 线程就够了至少能避免进程无法退出。4. 技能编排让多个Skills协同工作单个技能只能处理单点问题真正体现技能库威力的是编排层。编排器负责接收一段用户指令拆解成多个技能的调用序列再把结果拼装成一段完整回复。这一层设计得好整个系统的智能化体验会提高一个档次。4.1 编排器的职责与执行流程编排器做的事情可以拆成三块意图解析、步骤规划、结果聚合。意图解析是理解用户想干什么步骤规划是决定调用哪些技能以及按什么顺序调用结果聚合是把多个技能的输出拼接成有意义的回复。意图解析最简单的方式是维护一组规则关键词。比如用户消息里同时出现“提醒”和“天气”两个词编排器就知道要同时触发 remind 和 weather 两个技能。当然也可以用大模型来做意图解析结果会更灵活但成本更高响应也更慢。我个人的经验是规则兜底加模型增强的双层方案最稳妥先用规则快速匹配规则没有命中再走模型模型超时或者出错时再退回规则。步骤规划上要支持顺序执行和数据传递。顺序执行好理解前一个技能跑完再跑下一个。数据传递是指前一个技能的输出可以作为后一个技能的输入比如备忘技能返回的新条目 ID可以传给删除接口用。我在编排器的上下文里维护一个result_map每个技能的执行结果都会放在里面后续技能通过变量引用拿到这些数据。# orchestrator.py def execute_plan(steps, skills, base_ctx): result_map {} for step in steps: skill_name step[skill] skill skills.get(skill_name) if not skill: return {ok: False, error: f未找到技能 {skill_name}} inputs {} for key, value in step.get(inputs, {}).items(): if isinstance(value, str) and value.startswith($): ref_key value[1:] if ref_key not in result_map: return {ok: False, error: f上下文缺失 {ref_key}} inputs[key] result_map[ref_key] else: inputs[key] value ctx dict(base_ctx) ctx[inputs] inputs result skill(ctx) result_map[step.get(id, skill_name)] result return {ok: True, data: result_map}这里$前缀用来表示“引用上下文里的某个变量”。比如第二步的输入写成city: $weather_result.data.city编排器就会自动从第一步的结果里取值填入。这种简单的引用语法比直接写代码判断要通用得多一个刚加入项目的人看一遍也能明白。4.2 一个组合示例天气加提醒来看一个完整示例。用户说“明早9点提醒我带伞顺便查下北京天气”。规则层解析出两个意图提醒任务和天气查询。步骤规划如下[ { id: weather_step, skill: weather, inputs: {city: 北京, unit: celsius} }, { id: remind_step, skill: remind, inputs: { action: add, time: next 09:00, content: 带伞 } } ]执行顺序上两个技能之间没有数据依赖并行执行和顺序执行结果一样。但如果后续步骤需要用到天气结果来修正提醒内容比如“明天有雨才提醒带伞”那就必须先执行 weather 再执行 remind并把weather.data.condition作为判断条件传入。这个场景我在实际项目里遇到过所以步骤规划器最好支持声明depends_on字段编排器根据依赖关系自动调整执行顺序。结果聚合阶段编排器从result_map里提取关键信息生成一段自然语言回复。比如已为你添加提醒明早 09:00 提醒带伞。 北京当前天气18℃晴湿度 30%。回复内容不需要太长把两个技能的有效信息讲清楚就行。这里其实又回到统一返回结构的价值了如果每个技能返回的数据形态都不一样聚合函数就得写一大堆特判而统一结构下只需要写一次模板。5. 常见问题与排查技巧实录技能库框架本身不算复杂但实际跑起来总会碰到一些奇奇怪怪的问题。我把这一类项目里最常遇到的情况整理成了一份排查速查表都是我真实踩过或者帮别人排查过的。5.1 技能加载失败先看清单文件再看编码技能加载失败是最常见的问题症状是主程序启动时打印了一行“跳过技能 xxx”。绝大多数原因出在 SKILL.md 上要么不是合法的 YAML front matter要么缺少 name 字段要么文件开头带着 BOM 头导致解析错位。我的排查顺序是先确认文件编码。Windows 下和 Mac 下保存的 Markdown 文件编码习惯不同最简单的方法是用hexdump或者直接file命令看一下文件开头几个字节。处理方式就是我在加载器里写的那样统一用utf-8-sig读取能兼容带不带 BOM 的两种文件。其次是缩进问题。YAML 对缩进极其敏感尤其 inputs 参数嵌套了两三层的时候多一个空格少一个空格都能让解析结果跟你预期完全不同。我建议编辑器里开启空格显示或者直接粘贴到一个在线 YAML 校验工具里过一遍再放进项目。5.2 模块导入失败依赖管理和路径问题技能目录被加载器识别之后importlib.import_module如果抛ModuleNotFoundError基本就是技能依赖的第三方库没装。个人项目里不同技能可能需要不同依赖全装在主环境里很容易冲突。我建议给技能库做独立的虚拟环境然后每个技能配一个 requirements.txt部署时按需安装。另一种情况是技能实现文件里用了相对导入比如from ..common import utils在技能作为独立模块运行时没问题但被加载器动态导入时会因为父包初始化顺序不同而报错。我现在的规范是技能之间不共享 Python 内部符号需要复用的工具代码放到一个独立能力包里技能通过绝对导入引用它。路径问题我在前面提到过凡是技能内部要读写文件一律用Path(__file__).resolve().parent拼路径。绝对不要用相对路径不要依赖进程工作目录。一个技能被两个不同的调用方触发时工作目录可能完全不同这是我在多入口项目里踩过的真实教训。5.3 执行超时卡住的不只是当前技能网络请求、外部进程调用都可能让技能执行时间超出预期。我最早没有超时控制的时候遇到一个技能里请求第三方接口连续重试五次每次等 30 秒直接导致整个助手在两分钟内对任何指令都没有响应。给执行器加上默认 10 秒超时之后这个场景至少能被兜住。超时问题上还有一个容易被忽略的细节线程超时之后只是不再等待结果技能内部的代码还在跑。如果这个技能持有某个全局锁或者占了某个设备资源后续其他技能可能间接被拖住。所以我建议在技能实现里尽量把耗时的部分做成可取消的或者至少不要在技能里持有跨技能的共享资源。5.4 并发与数据一致性文件技能要注意原子写当主程序同时处理多个请求时多个技能可能并发调用同一个文件的读写操作。比如备忘技能和提醒技能同时写各自的 JSON 文件时如果直接open写入可能发生数据交叉损坏。原子写方案能避免坏文件但应对不了更复杂的并发一致性需求。如果你的技能库将来可能同时服务多个用户我建议文件型技能加上一把进程内的线程锁或者干脆把存储迁移到轻量级数据库。个人项目阶段原子写入加临时文件替换已经足够稳定不需要引入额外组件。5.5 手册之外的几条避坑建议最后分享几条零散的实战建议每一条都是真金白银换来的经验。技能清单里的description字段值得认真写。它不只是给加载器看的技术元数据还是给所有使用者看的“使用说明书”。一个描述清楚的技能别人看了就能判断该不该用、怎么用一个描述含糊的技能就算实现再牛也会被弃用。技能目录的命名和实现文件的命名保持统一约定。我约定每个技能目录里必须有一个main.py里面必须有一个run(ctx)函数每次走到新技能时不用翻代码就能定位入口。主程序的注册表逻辑实际上只需要这一个约定就能工作。不要把密钥直接写进技能代码里。技能库一旦分享出去写在代码里的 API 密钥就会被别人看到。我都是通过环境变量或者主程序提供的配置对象传给技能技能从ctx[config]里取配置而不是自己读文件。这样分享代码时也安全一些。还有技能的ctx参数不要设计得太复杂。我最初版本塞了一堆全局对象进去表面上看“什么都能拿到”实际上一来导致技能与主程序耦合很深二来给后来接手的人造成巨大的认知负担。现在我的 ctx 里只有inputs和config两项简单到看一眼就知道怎么用这反而是更强的扩展性。这套 Skills 技能库框架我从最开始几十行的单体脚本一路演进到现在的可插拔结构最大的感受是真正值钱的不是某个技能实现得有多炫而是它沉淀到技能库之后可以被反复调用、组合、迭代。你维护的每一个独立技能都是在为自己的个人效率系统添砖加瓦。如果在搭建过程中遇到什么问题回头看看这份记录里的细节大部分坑都已经被踩过了。
