【WorkBuddy · 三件套技能/专家/技能】第 15 章 · 把已有项目改造成技能上一章我们从零写了一个全新技能。这一章换一个角度你电脑里其实已经躺着不少小脚本本章把它们按规范打包成一个能被别人一句话调用的技能。一、学习目标读完本章并跟做完课后任务你将能够用skill-creator init一键生成技能骨架把散落的 Python 脚本挪进标准技能目录写出符合规范的 SKILL.md含触发词、参数、输出格式让一份本地脚本通过安全审计给技能补一组最小可用的测试预计耗时35 分钟。二、前置准备已经完成第 14 章电脑里有~/Documents/fortune-teller/电脑上有一个 Python 3.10 环境已经装好skill-creator技能第 14 章步骤 2 装的准备一个测试用的 CSV 文件比如一份购物清单提示如果你手边没有 CSV可以复制下面这段保存为shopping.csv日期,品类,金额 2026-09-01,餐饮,35 2026-09-02,交通,12 2026-09-03,日用,89 2026-09-04,餐饮,42 2026-09-05,娱乐,150三、为什么要改造而不是重写很多人以为我要做个技能就得从一行代码开始写。其实 WorkBuddy 的技能 90% 的价值在接口设计——也就是 SKILL.md 写得清不清楚。脚本本身完全可以是你已经在用的、可能写得还很丑的那段代码。本章要做的事本质上就是[散落的脚本] → [符合规范的技能包] → [WorkBuddy 帮别人调用]四、操作步骤我们分 7 步走。每一步都按先看 → 再做 → 验证的节奏。7 步流程看代码 → 装 creator → init → 改 SKILL.md → 拷脚本 → 安全审计 → 调用。步骤 1挑一个值得改造的小脚本挑的原则输入输出清晰看得见输入文件看得见输出文件不依赖外部账号不连数据库、不发邮件能 30 秒内跑完避免长任务本章的范例把csv-to-md.py改造为csv-to-md技能。它接收一个 CSV 文件输出一个 Markdown 表格。把下面这段保存为~/Documents/csv-to-md.pyimportcsvimportsysdefcsv_to_markdown(path):withopen(path,newline,encodingutf-8)asf:rowslist(csv.reader(f))ifnotrows:returnheaderrows[0]lines[]lines.append(| | .join(header) |)lines.append(||.join([---]*len(header))|)forrinrows[1:]:lines.append(| | .join(r) |)return\n.join(lines)if__name____main__:print(csv_to_markdown(sys.argv[1]))shopping.csv 内容参考Item,Category,Quantity,Unit Price,Store Apples,Fruit,6,0.80,Fresh Mart Milk,Dairy,2,3.50,Corner Shop Bread,Bakery,1,2.40,Corner Shop Eggs,Dairy,12,0.30,Fresh Mart Rice,Pantry,1,8.99,Market Hall Chicken Breast,Meat,2,6.75,Market Hall Spinach,Vegetable,3,1.20,Fresh Mart Coffee,Pantry,1,12.50,Corner Shop可以先用命令行验证一下python csv-to-md.py shopping.csv能打出 Markdown 表格就算 OK。图 15-1原始脚本运行截图图 15-1原始脚本运行截图截两张拼一起上终端输入python csv-to-md.py shopping.csv下完整的 Markdown 表格输出红框标注这就是我们要打包的原料步骤 2用 skill-creator 一键生成技能骨架打开 WorkBuddy 对话窗口输入我有一个 csv 转 markdown 的脚本路径是 ~/Documents/csv-to-md.py帮我初始化一个技能包skill-creator会自动建好以下结构csv-to-md/ ├── SKILL.md ├── scripts/ │ └── csv-to-md.py ← 你的原脚本会被自动挪进来 ├── tests/ │ └── test_basic.py ├── references/ └── assets/图 15-2自动生成的目录结构小贴士和第 14 章手工建文件夹相比skill-creator init帮你把目录规范这一步省了。这是为什么官方推荐先 init 再改而不是自己造文件夹。步骤 3改写 SKILL.md——把触发词写到位打开生成的SKILL.md把内容替换为下面这段--- name: csv-to-md description: 把任意 CSV 文件转成 Markdown 表格。输入文件路径输出 Markdown 字符串。当用户说把 CSV 转成表格、csv 转 markdown、表格化时调用。 --- # CSV 转 Markdown 表格 ## 何时调用 - 用户上传 CSV 文件要求转表格 - 用户说把这份 csv 转成 markdown - 用户问用表格展示这份数据 ## 调用方式 \\\bash python scripts/csv-to-md.py 输入文件路径 \\\ ## 输出格式 脚本输出 Markdown 表格字符串直接展示给用户。 ## 参数 - 输入文件路径必填相对路径相对于技能根目录 ## 示例 用户说把 shopping.csv 转成 markdown 表格给我看 → 脚本运行 python scripts/csv-to-md.py shopping.csv → 输出 Markdown 表格用户可见。保存。*图 15-3填好的 SKILL.md原来的内容帮忙写的还是比较好的看情况更新替换即可小贴士description 和何时调用段落的区别是description 写能干什么“何时调用写什么场景用”。两个一起写才完整。步骤 4原脚本挪位置 改命令行入口虽然第 2 步脚本已经被挪进scripts/了但你需要确保脚本里的sys.argv[1]仍然按命令行参数工作顶部加一行#!/usr/bin/env python3可选但加上更专业文件顶部加一个简短的注释说明用法修改后的scripts/csv-to-md.py头部#!/usr/bin/env python3 csv-to-md.py path/to/file.csv 把 CSV 文件转成 Markdown 表格并打印到 stdout。 importcsvimportsys# ... 后面保持不变图 15-4改后的脚本顶部步骤 5跑安全审计这一步是小白最容易跳过的——但跳过审计的技能WorkBuddy 在加载时会拦下来。3 档风险 · 3 种处理方式P0 必须改、P1 加确认、P2 写文档。WorkBuddy 对话窗口输入跑一下 csv-to-md 这个技能的安全审计skill-creator会调用安全检查模块输出类似[P2] 缺测试用例不阻塞但建议补 [P1] 脚本无超时限制长任务可能挂死建议加 timeout [P0] 无图 15-5安全审计报告其实WorkBuddy 构建这个技能的时候脚本已经做了优化 csv-to-md.py path/to/file.csv 把 CSV 文件转成 Markdown 表格并打印到 stdout。 importargparseimportcsvimportsysdefcsv_to_markdown(path,delimiter,,encodingutf-8):withopen(path,newline,encodingencoding)asf:rowslist(csv.reader(f,delimiterdelimiter))ifnotrows:returnheaderrows[0]lines[]lines.append(| | .join(header) |)lines.append(||.join([---]*len(header))|)forrinrows[1:]:lines.append(| | .join(r) |)return\n.join(lines)defmain(argvNone):ifhasattr(sys.stdout,reconfigure):sys.stdout.reconfigure(encodingutf-8)parserargparse.ArgumentParser(descriptionConvert a CSV file into a Markdown pipe table.)parser.add_argument(path,helppath to the input CSV file)parser.add_argument(--delimiter,default,,helpfield delimiter, one character (default: ,); use \\t for TSV,)parser.add_argument(--encoding,defaultutf-8,helpinput encoding (default: utf-8); try utf-8-sig for Excel exports or gbk for legacy Chinese CSV files,)parser.add_argument(--timeout,typefloat,defaultNone,helpoptional timeout in seconds for callers that enforce runtime limits,)argsparser.parse_args(argv)# Accept the literal two-character sequence \t as well as a real tab,# because shells pass \t through unexpanded.delimiter\tifargs.delimiter\\telseargs.delimiteriflen(delimiter)!1:parser.error(--delimiter must be a single character)try:sys.stdout.write(csv_to_markdown(args.path,delimiter,args.encoding))exceptUnicodeDecodeErrorasexc:parser.error(cannot decode input as %s (%s); retry with --encoding utf-8-sig or gbk%(args.encoding,exc))exceptFileNotFoundError:parser.error(input file not found: %s%args.path)exceptOSErrorasexc:parser.error(cannot read %s: %s%(args.path,exc))if__name____main__:main(sys.argv[1:])对 P1 提示我们要修。把脚本改写成接受--timeout参数(如果需要的话可以对应 原始的脚本进行调整)importargparse parserargparse.ArgumentParser()parser.add_argument(path)parser.add_argument(--timeout,typeint,default10)argsparser.parse_args()# ... 后面把 sys.argv[1] 改成 args.path图 15-6修复 P1 后的脚本再次让 WorkBuddy 跑审计确认[P1]消失。步骤 6写一组测试打开自动生成没有可以自行创建的tests/test_basic.py替换为importsubprocessimportosimportsys ROOTos.path.dirname(os.path.dirname(os.path.abspath(__file__)))SCRIPTos.path.join(ROOT,scripts,csv-to-md.py)SAMPLEos.path.join(ROOT,tests,shopping.csv)defrun(args):returnsubprocess.check_output([sys.executable,SCRIPT]args,cwdROOT,timeout5,).decode(utf-8)deftest_basic():outrun([SAMPLE])assert| 日期inoutassert| 餐饮inoutdeftest_empty():open(os.path.join(ROOT,tests,empty.csv),w).close()outrun([os.path.join(ROOT,tests,empty.csv)])assertoutdeftest_timeout_flag():# 仅验证参数能被识别outsubprocess.run([sys.executable,SCRIPT,--help],capture_outputTrue,textTrue)assert--timeoutinout.stdout把shopping.csv复制一份到tests/目录。终端运行cd~/.../csv-to-md 根据自己的目录自行调整 python-mpytest tests/-v应输出3 passed。图 15-7测试通过截图步骤 7让 WorkBuddy 加载 实战一次WorkBuddy 对话窗口加载 csv-to-md 这个技能路径是 ~/Documents/csv-to-md加载成功后输入帮我把购物.csv 转成 Markdown 表格WorkBuddy 会自动调用python scripts/csv-to-md.py 购物.csv把输出贴回来。至此你已经把一段散落的脚本改造成了一个规范技能。五、小贴士别想着一次到位。先 init → 改 SKILL.md → 跑通再回头补审计和测试。每步独立验证比一次写完再修要快得多。触发词别贪多。csv-to-md的 description 里只写了 3 个触发场景就够用写 20 个反而稀释精确度。审计不是走过场。P1 风险是真有用户踩过坑的比如长任务挂死、权限过大能修就修。测试覆盖最常见 最容易错两种用例就够了。第 6 步那种3 个测试是起步配置不要追求覆盖率。如果脚本依赖第三方包在技能根目录新建requirements.txt并在 SKILL.md 的前置依赖段落写明。六、课后任务任务难度★★★☆☆任务把你电脑上任何一个 Python 小脚本比如批量重命名、读取 JSON 之类按本章 7 步改造成技能。参考检查清单skill-creator init跑通SKILL.md 有 description 何时调用安全审计无 P0至少 2 个测试通过WorkBuddy 对话窗口能调用完成后在对话里跑一次你的技能把 WorkBuddy 的回复贴回来——这就是你最直接的作品集了。七、本章小结你做了你学到了用 skill-creator init 生成骨架不用手工建文件夹改写 SKILL.md触发词 调用方式 输出格式加 timeout 参数修掉 P1 风险写 3 个 pytest 测试给技能加一道质量护栏加载并实战调用散落脚本 → 可被调用的能力下一章第 16 章我们换个方向把你的工作方法沉淀成专家——脚本能干的事是一回事怎么思考、怎么判断、怎么表达是另一回事。十一、读者问答 QA10 个真实问题Q1原项目有几万行代码能改造成技能吗能但你不要把整个项目都搬过来。SKILL.md 描述的是何时调用 怎么调用不是项目说明。建议做法保留项目核心逻辑10%~20%把通用部分剥成 scripts/ 下的多个脚本由 SKILL.md 调度。几万行全塞进去WorkBuddy 启动该技能时就会很慢。Q2原项目用 Python 2 写的能改造吗可以但强烈建议先把代码迁到 Python 3。WorkBuddy 默认运行时是 Python 3.13跑 Python 2 项目会报语法错。简单粗暴做法2to3 -w your_script.py自动转换再人工修补几个常见坑。Q3项目里有数据库连接技能启动会一直占着连接吗看你的代码。如果用sqlite3.connect()全局连接连接会一直开着。建议改成用时连接、用完关闭——with sqlite3.connect(...) as conn:这样每次调用技能都用新连接避免并发问题。Q4项目依赖公司内网 API 怎么改要在 SKILL.md 里写明会访问 internal-api.company.com并在requirements.txt里写清楚依赖。但 WorkBuddy 在公网机器上跑时会访问不到内网 API——这时要靠网络代理或预调度把数据提前灌到本地文件技能读本地文件。Q5改造后性能会变差吗大多数情况会稍慢。因为 WorkBuddy 启动技能脚本要过一层进程间通信。优化手段scripts/ 里的脚本尽量短小单文件 100~300 行最舒服大型计算缓存到本地文件启动技能时直接读避免在技能脚本里import torch这类重库Q6原项目的测试用例能直接用吗可以。WorkBuddy 加载技能时不会跑测试但你自己开发时pytest一遍是必做的。建议在scripts/tests/下保存 pytest 文件第 7 步演示过这件事。Q7能改造多人合作的项目吗可以但做好约定谁负责 SKILL.md、谁负责 scripts/、谁负责测试。多人在同一个技能上跑容易冲突。建议用 git 分支管理PR 评审。Q8项目里有 GUI 界面比如 PyQt技能怎么调用GUI 部分可以剥掉保留核心计算逻辑 数据 IO。技能只需要输入 → 计算 → 输出不需要窗口这个外壳。Q9能改造加密/二进制文件吗可以。WorkBuddy 不会去读脚本里的二进制内容只要你的脚本代码本身是文本就行。scripts/下可以放.so、.pyd、.dll但审计会标 P1 风险二进制不可读需要人工 review。建议尽量保持纯 Python。Q10改造后的技能能反推回原项目吗可以。把 SKILL.md 当成接口定义scripts/ 当成重构后模块。这样原项目可以逐步迁移每次迁移一段代码就好。这是一种渐进式重构的好方法。十二、三个常见误区误区 1把 SKILL.md 当 README 写很多人写 SKILL.md 像写项目文档——“本技能基于 pandas 1.5…”。错——SKILL.md 是接口契约何时被 WorkBuddy 调用、怎么调用不是历史书。正确写法description:用户上传 CSV 文件并说转成 markdown 表格时调用输出 UTF-8 编码的 Markdown 表格字符串错误写法description:csv-to-md 是一个基于 csv 模块和 tabulate 的 Python 工具用于将 CSV 转换为 Markdown 表格误区 2把 scripts 当成技能入口有人以为scripts/ 里放什么技能就调什么。错——WorkBuddy 看的是 SKILL.md 里的调用入口也可能是entry字段或 frontmatter。scripts/ 下文件命名不影响调用逻辑只要 SKILL.md 里写明的脚本路径对就行。误区 3以为自己改造完就完事改造完只是装上技能。真正完成了还要跑安全审计写测试用例写 changelog记录改造前后的差异给同事看一遍不是 review而是演示给真人看很多小白改造完直接用遇到线上问题才回头补——这就是完成度不足的表现。十三、3 类人改造项目的不同打法场景 1纯 Python 工程师公司项目里有个老脚本data_processor.py跑了 3 年没出过问题。小王的工作是把它改造成技能让团队 10 个人都能用。他的打法重构代码用argparse接受输入参数写 SKILL.md描述清楚用户上传什么、得到什么加requirements.txt冻结依赖版本写 pytest 单元测试在 WorkBuddy 对话窗口试试场景 2业务分析师市场部有份 Excel 报告每次做都得手动整理 2 小时。小李的改造把 Excel 读取逻辑剥到scripts/parse_xlsx.py把数据清洗逻辑剥到scripts/clean_data.py把出报告逻辑剥到scripts/gen_report.pySKILL.md 写明用户上传 xlsx → 输出自动生成的报告2 小时的手工变成 5 分钟一句话。场景 3科研工作者研究生小张有 200 个数据处理的 Python 脚本散落在文件夹里论文写作时找不全。他的改造把 200 个脚本分组按论文章节每章一组对应一个技能SKILL.md 写用户提到第 3 章数据时调用这样论文 review 时一句话就能调出对应分析共同的逻辑把散落的脚本重组成可被调用的能力。这就是技能改造的核心价值。十四、踩坑实录一次完整的安全审计失败场景小李改造一个开源爬虫时跳过了审计结果上线即翻车。过程小李在 GitHub 找了个爬虫脚本复制到自己的web-scraper/文件夹写了 SKILL.md描述用户说’爬取 xxx 网页’时调用跳过了第 5 步的审计直接到第 6 步让 WorkBuddy 加载WorkBuddy 加载时报警“检测到 P0 风险脚本包含高危 APIsubprocess、eval、网络请求”技能被自动禁用根因脚本里用eval()解析网页返回的 JavaScript脚本里subprocess.run(rm -rf /tmp/*)这种危险命令这两个对 WorkBuddy 来说是 P0 风险远程代码执行风险排查把脚本传到 WorkBuddy让它检查 → 输出“P0eval 在 line 47, subprocess 在 line 92”改eval为ast.literal_eval改subprocess为具体的 Python 文件操作shutil.rmtree再审计 → 通过教训审计不是形式是过滤危险的护栏。你以为你跑过没问题但 WorkBuddy 在用户机上跑——你的没问题不等于用户的没问题。预防建议永远不要用eval/exec/subprocess除非你 100% 确定输入安全永远不要 hard-code 任何清理系统的命令审计时 WorkBuddy 会列风险项 → 一个个改 → 改完再审 → 通过再上十五、延伸阅读渐进式改造而非一步到位很多工程师拿到老项目第一反应是大重构——重写 80% 代码。这是错的。渐进式改造的 3 步法包一层原项目不动外面套一个wrapper.py把输入输出标准化接 SKILL.md写一个最简 SKILL.md只调 wrapper.py不动其他逐步替换每改一个函数就重测一次技能OK 后再改下一个这样做的好处任何阶段出问题都能立刻回滚到上一步测试金字塔始终可用你对系统的理解越来越深更激进的做法是功能开关 “ab test”同一功能提供两种实现技能运行时随机选让真实流量验证哪种更好。十六、课后任务参考答案详解任务给你的 csv-to-md 加一个--max-rows参数。评分要点10 分制评分项分值满分示范1. argparse 加--max-rows3 分--max-rows int默认值 10002. 代码里用它截断行3 分rows[:args.max_rows]或 pandas.head(n)3. SKILL.md 更新描述2 分注明参数 默认值 限制4. 测试覆盖2 分至少 1 个测试覆盖 max_rows常见扣分参数没默认值默认 -1 容易把内存吃爆-2 分没在 SKILL.md 写参数说明其他用户不知道有这个参数-2 分没测试-2 分高阶加分加--output-file参数把结果直接写文件2 分加--csv-encoding参数支持 GBK2 分加--markdown-style参数pipe/grid/list3 分完整参考代码importargparse parserargparse.ArgumentParser()parser.add_argument(--input,requiredTrue)parser.add_argument(--output,defaultoutput.md)parser.add_argument(--max-rows,typeint,default1000)argsparser.parse_args()# 读 CSV 时rowsread_csv(args.input)limited_rowsrows[:args.max_rows]write_markdown(limited_rows,args.output)十七、本章成本与 ROI学习成本60~90 分钟跑 7 步改造45 分钟排查审计问题15~30 分钟取决于原项目复杂度长期价值你掌握渐进式重构思维——以后面对任何遗留代码都不慌你掌握安全审计能力——这是一个被严重低估的专业技能你的 csv-to-md 真的能干活了——团队 10 个人每天可以省 5 分钟ROI 估算假设你每周用这个技能 5 次每次省 10 分钟每周省 50 分钟每月 200 分钟 ≈ 3.3 小时一年 40 小时 ≈ 1 周工作时间这 1 周工作时间几乎零成本获得。十八、本章小结扩充版核心收获知道项目 → 技能是一条可行的路径理解改造不是重写是重组织掌握 7 步标准流程把审计从形式变成习惯你可以接着做的把公司里的老脚本逐个改造成技能在团队里当技能改造推动者用第 18 章学的发布流程把你的技能上架到市场下一章第 16 章我们换个方向把你的工作方法沉淀成专家——脚本能干的事是一回事怎么思考、怎么判断、怎么表达是另一回事。 【WorkBuddy · 三件套：技能/专家/技能】第 15 章 · 把已有项目改造成技能
【WorkBuddy · 三件套技能/专家/技能】第 15 章 · 把已有项目改造成技能上一章我们从零写了一个全新技能。这一章换一个角度你电脑里其实已经躺着不少小脚本本章把它们按规范打包成一个能被别人一句话调用的技能。一、学习目标读完本章并跟做完课后任务你将能够用skill-creator init一键生成技能骨架把散落的 Python 脚本挪进标准技能目录写出符合规范的 SKILL.md含触发词、参数、输出格式让一份本地脚本通过安全审计给技能补一组最小可用的测试预计耗时35 分钟。二、前置准备已经完成第 14 章电脑里有~/Documents/fortune-teller/电脑上有一个 Python 3.10 环境已经装好skill-creator技能第 14 章步骤 2 装的准备一个测试用的 CSV 文件比如一份购物清单提示如果你手边没有 CSV可以复制下面这段保存为shopping.csv日期,品类,金额 2026-09-01,餐饮,35 2026-09-02,交通,12 2026-09-03,日用,89 2026-09-04,餐饮,42 2026-09-05,娱乐,150三、为什么要改造而不是重写很多人以为我要做个技能就得从一行代码开始写。其实 WorkBuddy 的技能 90% 的价值在接口设计——也就是 SKILL.md 写得清不清楚。脚本本身完全可以是你已经在用的、可能写得还很丑的那段代码。本章要做的事本质上就是[散落的脚本] → [符合规范的技能包] → [WorkBuddy 帮别人调用]四、操作步骤我们分 7 步走。每一步都按先看 → 再做 → 验证的节奏。7 步流程看代码 → 装 creator → init → 改 SKILL.md → 拷脚本 → 安全审计 → 调用。步骤 1挑一个值得改造的小脚本挑的原则输入输出清晰看得见输入文件看得见输出文件不依赖外部账号不连数据库、不发邮件能 30 秒内跑完避免长任务本章的范例把csv-to-md.py改造为csv-to-md技能。它接收一个 CSV 文件输出一个 Markdown 表格。把下面这段保存为~/Documents/csv-to-md.pyimportcsvimportsysdefcsv_to_markdown(path):withopen(path,newline,encodingutf-8)asf:rowslist(csv.reader(f))ifnotrows:returnheaderrows[0]lines[]lines.append(| | .join(header) |)lines.append(||.join([---]*len(header))|)forrinrows[1:]:lines.append(| | .join(r) |)return\n.join(lines)if__name____main__:print(csv_to_markdown(sys.argv[1]))shopping.csv 内容参考Item,Category,Quantity,Unit Price,Store Apples,Fruit,6,0.80,Fresh Mart Milk,Dairy,2,3.50,Corner Shop Bread,Bakery,1,2.40,Corner Shop Eggs,Dairy,12,0.30,Fresh Mart Rice,Pantry,1,8.99,Market Hall Chicken Breast,Meat,2,6.75,Market Hall Spinach,Vegetable,3,1.20,Fresh Mart Coffee,Pantry,1,12.50,Corner Shop可以先用命令行验证一下python csv-to-md.py shopping.csv能打出 Markdown 表格就算 OK。图 15-1原始脚本运行截图图 15-1原始脚本运行截图截两张拼一起上终端输入python csv-to-md.py shopping.csv下完整的 Markdown 表格输出红框标注这就是我们要打包的原料步骤 2用 skill-creator 一键生成技能骨架打开 WorkBuddy 对话窗口输入我有一个 csv 转 markdown 的脚本路径是 ~/Documents/csv-to-md.py帮我初始化一个技能包skill-creator会自动建好以下结构csv-to-md/ ├── SKILL.md ├── scripts/ │ └── csv-to-md.py ← 你的原脚本会被自动挪进来 ├── tests/ │ └── test_basic.py ├── references/ └── assets/图 15-2自动生成的目录结构小贴士和第 14 章手工建文件夹相比skill-creator init帮你把目录规范这一步省了。这是为什么官方推荐先 init 再改而不是自己造文件夹。步骤 3改写 SKILL.md——把触发词写到位打开生成的SKILL.md把内容替换为下面这段--- name: csv-to-md description: 把任意 CSV 文件转成 Markdown 表格。输入文件路径输出 Markdown 字符串。当用户说把 CSV 转成表格、csv 转 markdown、表格化时调用。 --- # CSV 转 Markdown 表格 ## 何时调用 - 用户上传 CSV 文件要求转表格 - 用户说把这份 csv 转成 markdown - 用户问用表格展示这份数据 ## 调用方式 \\\bash python scripts/csv-to-md.py 输入文件路径 \\\ ## 输出格式 脚本输出 Markdown 表格字符串直接展示给用户。 ## 参数 - 输入文件路径必填相对路径相对于技能根目录 ## 示例 用户说把 shopping.csv 转成 markdown 表格给我看 → 脚本运行 python scripts/csv-to-md.py shopping.csv → 输出 Markdown 表格用户可见。保存。*图 15-3填好的 SKILL.md原来的内容帮忙写的还是比较好的看情况更新替换即可小贴士description 和何时调用段落的区别是description 写能干什么“何时调用写什么场景用”。两个一起写才完整。步骤 4原脚本挪位置 改命令行入口虽然第 2 步脚本已经被挪进scripts/了但你需要确保脚本里的sys.argv[1]仍然按命令行参数工作顶部加一行#!/usr/bin/env python3可选但加上更专业文件顶部加一个简短的注释说明用法修改后的scripts/csv-to-md.py头部#!/usr/bin/env python3 csv-to-md.py path/to/file.csv 把 CSV 文件转成 Markdown 表格并打印到 stdout。 importcsvimportsys# ... 后面保持不变图 15-4改后的脚本顶部步骤 5跑安全审计这一步是小白最容易跳过的——但跳过审计的技能WorkBuddy 在加载时会拦下来。3 档风险 · 3 种处理方式P0 必须改、P1 加确认、P2 写文档。WorkBuddy 对话窗口输入跑一下 csv-to-md 这个技能的安全审计skill-creator会调用安全检查模块输出类似[P2] 缺测试用例不阻塞但建议补 [P1] 脚本无超时限制长任务可能挂死建议加 timeout [P0] 无图 15-5安全审计报告其实WorkBuddy 构建这个技能的时候脚本已经做了优化 csv-to-md.py path/to/file.csv 把 CSV 文件转成 Markdown 表格并打印到 stdout。 importargparseimportcsvimportsysdefcsv_to_markdown(path,delimiter,,encodingutf-8):withopen(path,newline,encodingencoding)asf:rowslist(csv.reader(f,delimiterdelimiter))ifnotrows:returnheaderrows[0]lines[]lines.append(| | .join(header) |)lines.append(||.join([---]*len(header))|)forrinrows[1:]:lines.append(| | .join(r) |)return\n.join(lines)defmain(argvNone):ifhasattr(sys.stdout,reconfigure):sys.stdout.reconfigure(encodingutf-8)parserargparse.ArgumentParser(descriptionConvert a CSV file into a Markdown pipe table.)parser.add_argument(path,helppath to the input CSV file)parser.add_argument(--delimiter,default,,helpfield delimiter, one character (default: ,); use \\t for TSV,)parser.add_argument(--encoding,defaultutf-8,helpinput encoding (default: utf-8); try utf-8-sig for Excel exports or gbk for legacy Chinese CSV files,)parser.add_argument(--timeout,typefloat,defaultNone,helpoptional timeout in seconds for callers that enforce runtime limits,)argsparser.parse_args(argv)# Accept the literal two-character sequence \t as well as a real tab,# because shells pass \t through unexpanded.delimiter\tifargs.delimiter\\telseargs.delimiteriflen(delimiter)!1:parser.error(--delimiter must be a single character)try:sys.stdout.write(csv_to_markdown(args.path,delimiter,args.encoding))exceptUnicodeDecodeErrorasexc:parser.error(cannot decode input as %s (%s); retry with --encoding utf-8-sig or gbk%(args.encoding,exc))exceptFileNotFoundError:parser.error(input file not found: %s%args.path)exceptOSErrorasexc:parser.error(cannot read %s: %s%(args.path,exc))if__name____main__:main(sys.argv[1:])对 P1 提示我们要修。把脚本改写成接受--timeout参数(如果需要的话可以对应 原始的脚本进行调整)importargparse parserargparse.ArgumentParser()parser.add_argument(path)parser.add_argument(--timeout,typeint,default10)argsparser.parse_args()# ... 后面把 sys.argv[1] 改成 args.path图 15-6修复 P1 后的脚本再次让 WorkBuddy 跑审计确认[P1]消失。步骤 6写一组测试打开自动生成没有可以自行创建的tests/test_basic.py替换为importsubprocessimportosimportsys ROOTos.path.dirname(os.path.dirname(os.path.abspath(__file__)))SCRIPTos.path.join(ROOT,scripts,csv-to-md.py)SAMPLEos.path.join(ROOT,tests,shopping.csv)defrun(args):returnsubprocess.check_output([sys.executable,SCRIPT]args,cwdROOT,timeout5,).decode(utf-8)deftest_basic():outrun([SAMPLE])assert| 日期inoutassert| 餐饮inoutdeftest_empty():open(os.path.join(ROOT,tests,empty.csv),w).close()outrun([os.path.join(ROOT,tests,empty.csv)])assertoutdeftest_timeout_flag():# 仅验证参数能被识别outsubprocess.run([sys.executable,SCRIPT,--help],capture_outputTrue,textTrue)assert--timeoutinout.stdout把shopping.csv复制一份到tests/目录。终端运行cd~/.../csv-to-md 根据自己的目录自行调整 python-mpytest tests/-v应输出3 passed。图 15-7测试通过截图步骤 7让 WorkBuddy 加载 实战一次WorkBuddy 对话窗口加载 csv-to-md 这个技能路径是 ~/Documents/csv-to-md加载成功后输入帮我把购物.csv 转成 Markdown 表格WorkBuddy 会自动调用python scripts/csv-to-md.py 购物.csv把输出贴回来。至此你已经把一段散落的脚本改造成了一个规范技能。五、小贴士别想着一次到位。先 init → 改 SKILL.md → 跑通再回头补审计和测试。每步独立验证比一次写完再修要快得多。触发词别贪多。csv-to-md的 description 里只写了 3 个触发场景就够用写 20 个反而稀释精确度。审计不是走过场。P1 风险是真有用户踩过坑的比如长任务挂死、权限过大能修就修。测试覆盖最常见 最容易错两种用例就够了。第 6 步那种3 个测试是起步配置不要追求覆盖率。如果脚本依赖第三方包在技能根目录新建requirements.txt并在 SKILL.md 的前置依赖段落写明。六、课后任务任务难度★★★☆☆任务把你电脑上任何一个 Python 小脚本比如批量重命名、读取 JSON 之类按本章 7 步改造成技能。参考检查清单skill-creator init跑通SKILL.md 有 description 何时调用安全审计无 P0至少 2 个测试通过WorkBuddy 对话窗口能调用完成后在对话里跑一次你的技能把 WorkBuddy 的回复贴回来——这就是你最直接的作品集了。七、本章小结你做了你学到了用 skill-creator init 生成骨架不用手工建文件夹改写 SKILL.md触发词 调用方式 输出格式加 timeout 参数修掉 P1 风险写 3 个 pytest 测试给技能加一道质量护栏加载并实战调用散落脚本 → 可被调用的能力下一章第 16 章我们换个方向把你的工作方法沉淀成专家——脚本能干的事是一回事怎么思考、怎么判断、怎么表达是另一回事。十一、读者问答 QA10 个真实问题Q1原项目有几万行代码能改造成技能吗能但你不要把整个项目都搬过来。SKILL.md 描述的是何时调用 怎么调用不是项目说明。建议做法保留项目核心逻辑10%~20%把通用部分剥成 scripts/ 下的多个脚本由 SKILL.md 调度。几万行全塞进去WorkBuddy 启动该技能时就会很慢。Q2原项目用 Python 2 写的能改造吗可以但强烈建议先把代码迁到 Python 3。WorkBuddy 默认运行时是 Python 3.13跑 Python 2 项目会报语法错。简单粗暴做法2to3 -w your_script.py自动转换再人工修补几个常见坑。Q3项目里有数据库连接技能启动会一直占着连接吗看你的代码。如果用sqlite3.connect()全局连接连接会一直开着。建议改成用时连接、用完关闭——with sqlite3.connect(...) as conn:这样每次调用技能都用新连接避免并发问题。Q4项目依赖公司内网 API 怎么改要在 SKILL.md 里写明会访问 internal-api.company.com并在requirements.txt里写清楚依赖。但 WorkBuddy 在公网机器上跑时会访问不到内网 API——这时要靠网络代理或预调度把数据提前灌到本地文件技能读本地文件。Q5改造后性能会变差吗大多数情况会稍慢。因为 WorkBuddy 启动技能脚本要过一层进程间通信。优化手段scripts/ 里的脚本尽量短小单文件 100~300 行最舒服大型计算缓存到本地文件启动技能时直接读避免在技能脚本里import torch这类重库Q6原项目的测试用例能直接用吗可以。WorkBuddy 加载技能时不会跑测试但你自己开发时pytest一遍是必做的。建议在scripts/tests/下保存 pytest 文件第 7 步演示过这件事。Q7能改造多人合作的项目吗可以但做好约定谁负责 SKILL.md、谁负责 scripts/、谁负责测试。多人在同一个技能上跑容易冲突。建议用 git 分支管理PR 评审。Q8项目里有 GUI 界面比如 PyQt技能怎么调用GUI 部分可以剥掉保留核心计算逻辑 数据 IO。技能只需要输入 → 计算 → 输出不需要窗口这个外壳。Q9能改造加密/二进制文件吗可以。WorkBuddy 不会去读脚本里的二进制内容只要你的脚本代码本身是文本就行。scripts/下可以放.so、.pyd、.dll但审计会标 P1 风险二进制不可读需要人工 review。建议尽量保持纯 Python。Q10改造后的技能能反推回原项目吗可以。把 SKILL.md 当成接口定义scripts/ 当成重构后模块。这样原项目可以逐步迁移每次迁移一段代码就好。这是一种渐进式重构的好方法。十二、三个常见误区误区 1把 SKILL.md 当 README 写很多人写 SKILL.md 像写项目文档——“本技能基于 pandas 1.5…”。错——SKILL.md 是接口契约何时被 WorkBuddy 调用、怎么调用不是历史书。正确写法description:用户上传 CSV 文件并说转成 markdown 表格时调用输出 UTF-8 编码的 Markdown 表格字符串错误写法description:csv-to-md 是一个基于 csv 模块和 tabulate 的 Python 工具用于将 CSV 转换为 Markdown 表格误区 2把 scripts 当成技能入口有人以为scripts/ 里放什么技能就调什么。错——WorkBuddy 看的是 SKILL.md 里的调用入口也可能是entry字段或 frontmatter。scripts/ 下文件命名不影响调用逻辑只要 SKILL.md 里写明的脚本路径对就行。误区 3以为自己改造完就完事改造完只是装上技能。真正完成了还要跑安全审计写测试用例写 changelog记录改造前后的差异给同事看一遍不是 review而是演示给真人看很多小白改造完直接用遇到线上问题才回头补——这就是完成度不足的表现。十三、3 类人改造项目的不同打法场景 1纯 Python 工程师公司项目里有个老脚本data_processor.py跑了 3 年没出过问题。小王的工作是把它改造成技能让团队 10 个人都能用。他的打法重构代码用argparse接受输入参数写 SKILL.md描述清楚用户上传什么、得到什么加requirements.txt冻结依赖版本写 pytest 单元测试在 WorkBuddy 对话窗口试试场景 2业务分析师市场部有份 Excel 报告每次做都得手动整理 2 小时。小李的改造把 Excel 读取逻辑剥到scripts/parse_xlsx.py把数据清洗逻辑剥到scripts/clean_data.py把出报告逻辑剥到scripts/gen_report.pySKILL.md 写明用户上传 xlsx → 输出自动生成的报告2 小时的手工变成 5 分钟一句话。场景 3科研工作者研究生小张有 200 个数据处理的 Python 脚本散落在文件夹里论文写作时找不全。他的改造把 200 个脚本分组按论文章节每章一组对应一个技能SKILL.md 写用户提到第 3 章数据时调用这样论文 review 时一句话就能调出对应分析共同的逻辑把散落的脚本重组成可被调用的能力。这就是技能改造的核心价值。十四、踩坑实录一次完整的安全审计失败场景小李改造一个开源爬虫时跳过了审计结果上线即翻车。过程小李在 GitHub 找了个爬虫脚本复制到自己的web-scraper/文件夹写了 SKILL.md描述用户说’爬取 xxx 网页’时调用跳过了第 5 步的审计直接到第 6 步让 WorkBuddy 加载WorkBuddy 加载时报警“检测到 P0 风险脚本包含高危 APIsubprocess、eval、网络请求”技能被自动禁用根因脚本里用eval()解析网页返回的 JavaScript脚本里subprocess.run(rm -rf /tmp/*)这种危险命令这两个对 WorkBuddy 来说是 P0 风险远程代码执行风险排查把脚本传到 WorkBuddy让它检查 → 输出“P0eval 在 line 47, subprocess 在 line 92”改eval为ast.literal_eval改subprocess为具体的 Python 文件操作shutil.rmtree再审计 → 通过教训审计不是形式是过滤危险的护栏。你以为你跑过没问题但 WorkBuddy 在用户机上跑——你的没问题不等于用户的没问题。预防建议永远不要用eval/exec/subprocess除非你 100% 确定输入安全永远不要 hard-code 任何清理系统的命令审计时 WorkBuddy 会列风险项 → 一个个改 → 改完再审 → 通过再上十五、延伸阅读渐进式改造而非一步到位很多工程师拿到老项目第一反应是大重构——重写 80% 代码。这是错的。渐进式改造的 3 步法包一层原项目不动外面套一个wrapper.py把输入输出标准化接 SKILL.md写一个最简 SKILL.md只调 wrapper.py不动其他逐步替换每改一个函数就重测一次技能OK 后再改下一个这样做的好处任何阶段出问题都能立刻回滚到上一步测试金字塔始终可用你对系统的理解越来越深更激进的做法是功能开关 “ab test”同一功能提供两种实现技能运行时随机选让真实流量验证哪种更好。十六、课后任务参考答案详解任务给你的 csv-to-md 加一个--max-rows参数。评分要点10 分制评分项分值满分示范1. argparse 加--max-rows3 分--max-rows int默认值 10002. 代码里用它截断行3 分rows[:args.max_rows]或 pandas.head(n)3. SKILL.md 更新描述2 分注明参数 默认值 限制4. 测试覆盖2 分至少 1 个测试覆盖 max_rows常见扣分参数没默认值默认 -1 容易把内存吃爆-2 分没在 SKILL.md 写参数说明其他用户不知道有这个参数-2 分没测试-2 分高阶加分加--output-file参数把结果直接写文件2 分加--csv-encoding参数支持 GBK2 分加--markdown-style参数pipe/grid/list3 分完整参考代码importargparse parserargparse.ArgumentParser()parser.add_argument(--input,requiredTrue)parser.add_argument(--output,defaultoutput.md)parser.add_argument(--max-rows,typeint,default1000)argsparser.parse_args()# 读 CSV 时rowsread_csv(args.input)limited_rowsrows[:args.max_rows]write_markdown(limited_rows,args.output)十七、本章成本与 ROI学习成本60~90 分钟跑 7 步改造45 分钟排查审计问题15~30 分钟取决于原项目复杂度长期价值你掌握渐进式重构思维——以后面对任何遗留代码都不慌你掌握安全审计能力——这是一个被严重低估的专业技能你的 csv-to-md 真的能干活了——团队 10 个人每天可以省 5 分钟ROI 估算假设你每周用这个技能 5 次每次省 10 分钟每周省 50 分钟每月 200 分钟 ≈ 3.3 小时一年 40 小时 ≈ 1 周工作时间这 1 周工作时间几乎零成本获得。十八、本章小结扩充版核心收获知道项目 → 技能是一条可行的路径理解改造不是重写是重组织掌握 7 步标准流程把审计从形式变成习惯你可以接着做的把公司里的老脚本逐个改造成技能在团队里当技能改造推动者用第 18 章学的发布流程把你的技能上架到市场下一章第 16 章我们换个方向把你的工作方法沉淀成专家——脚本能干的事是一回事怎么思考、怎么判断、怎么表达是另一回事。