思源笔记Copilot v2.4自定义Skill实战指南 1. 项目概述思源笔记 Copilot v2.4 的“自定义 Skill”到底意味着什么如果你用过思源笔记大概率也听说过 Copilot —— 它不是 GitHub Copilot也不是 VS Code 里的那个 AI 插件而是思源笔记生态中一个原生、轻量、可嵌入的本地化 AI 协作模块。v2.4 版本发布时官方只在更新日志里轻描淡写地写了句“支持用户自定义 Skill”但这句话背后实际撬动的是整个思源笔记从「静态知识库」向「可编程智能工作流」的关键跃迁。我第一次看到这个更新时立刻停下手头的文档整理把 v2.4 下载下来试了三遍。为什么这么上心因为过去半年我在用思源笔记搭建个人第二大脑的过程中反复卡在一个死结上我能用块引用、双向链接、属性面板组织信息但一旦想让笔记“主动做事”——比如自动提取会议纪要中的待办项并生成任务卡片、根据某篇读书笔记的标签批量生成知识图谱节点、甚至把一段 Markdown 转成符合公司规范的周报模板——就只能靠手动复制粘贴或者写 Python 脚本再调 API流程割裂、维护成本高、根本没法分享给团队同事。而 v2.4 的自定义 Skill就是把这个“手动缝合”的过程变成了思源笔记原生支持的、可视化配置代码可编辑上下文感知的执行单元。它不依赖外部服务不像某些插件必须连公网API不强制绑定特定大模型你用 Ollama 本地跑 Qwen2.5、用 LM Studio 加载 DeepSeek-V3、甚至对接私有部署的 Llama-3-70B只要符合 OpenAI 兼容协议就能无缝接入更关键的是——Skill 的触发逻辑、输入参数、输出格式、错误兜底全部写在一份agents.md文件里和你的笔记存在同一个文件夹下版本可控、协作可溯、迁移即拷贝。这已经不是“加了个新功能”而是把思源笔记的底层交互范式从“人驱动笔记”升级为“人定义规则 笔记驱动执行”。你不需要成为全栈工程师但得懂一点结构化思维你不用部署服务器但得理解什么是 prompt 工程、什么是 context window、什么是 tool calling 的基本契约。接下来我会带你从零开始把“支持自定义 Skill”这七个字拆解成你能真正落地、调试、复用、甚至封装成团队标准件的一整套实操路径。2. 核心设计逻辑与方案选型为什么是 agents.md为什么不是 JSON 或 YAML2.1 为什么选择 Markdown 作为 Skill 的载体很多人第一反应是为什么不用 JSON毕竟结构清晰、机器可读性强、校验方便。我也问过自己这个问题。直到我打开 v2.4 的源码注释看到一行关键注释“agents.md is parsed as a structured document with frontmatter and content blocks, not as plain text.” —— 这句话点破了本质它不是把 Markdown 当作文本渲染而是把它当作一种带语义分层的元数据容器。具体来说一个合法的agents.md文件必须包含三个逻辑区块Frontmatter 区块YAML 格式用---包裹定义 Skill 的元信息如name、description、model、temperature、max_tokens等Usage Block以!-- usage --开始描述该 Skill 如何被调用包括支持的命令格式、参数占位符、示例输入Prompt Block以!-- prompt --开始核心指令模板支持 Jinja2 风格变量注入如{{ selection }}、{{ blockContent }}、{{ filePath }}Optional Tool Block以!-- tools --开始定义可调用的外部工具如调用系统命令、读取其他笔记、发送 HTTP 请求需声明 schema 和执行逻辑。这种设计不是为了炫技而是解决三个真实痛点可读性优先Frontmatter 保证机器可解析Usage 和 Prompt 区块用自然语言代码块混合书写让非技术人员也能看懂“这个 Skill 是干什么的”“怎么用它”“它会怎么思考”。我给市场部同事配了一个“一键生成公众号摘要”的 Skill她只需要改prompt区块里的语气词和字数限制完全不用碰 JSON schema。版本友好Markdown 是 Git 友好的文本格式。当你在团队协作中迭代一个 Skillgit diff agents.md显示的是“把‘请用口语化表达’改成‘请用专业术语面向技术管理者’”而不是一长串 JSON key 的增删改。我们上周合并 PR 时产品经理直接在 GitHub Web 界面里 inline comment 修改 prompt开发确认后一键 merge全程没开 IDE。渐进式学习曲线你可以先只写 Frontmatter Usage让 Skill 在 Copilot 面板里显示出来再加 Prompt让它能返回基础结果最后才引入 Tools实现复杂动作。这种“最小可行 Skill”路径比一上来就面对 20 行 JSON Schema 友好太多。提示不要试图用 Typora 或 Obsidian 直接编辑agents.md并期望它自动生效。思源笔记对 Frontmatter 的解析有严格格式要求例如model:后必须跟空格temperature: 0.3不能写成temperature:0.3建议用 VS Code YAML 插件校验或直接在思源内置编辑器里编辑它会高亮语法错误。2.2 为什么模型字段支持字符串而非固定枚举v2.4 的model字段允许填任意字符串比如qwen2.5:14b、deepseek-v3:70b、ollama/llama3:8b甚至http://localhost:11434/v1。这不是偷懒而是为了解耦“Skill 定义”和“模型部署”。传统做法是把模型硬编码进插件比如“Copilot 默认用 GPT-4”用户想换模型就得改源码、重编译、等更新。而 v2.4 的设计是Skill 只声明“我需要一个支持 chat completions 的 OpenAI 兼容接口”具体哪个实例来响应由思源笔记全局设置决定。你在「设置 → AI → 模型服务」里配置好 Ollama 地址所有 Skill 自动生效切换成 LM Studio也不用改任何一个agents.md。这个设计带来的实操红利非常明显。我们团队有三类用户研发同事本地跑qwen2.5:14b低延迟、强推理适合写技术方案产品同事用deepseek-v3:7b量化版CPU 也能跑专注需求描述润色管理层配置了公司内网部署的llama3:70b确保敏感数据不出域。他们用的是一模一样的meeting-summary.agents.md只是各自环境里模型服务不同Skill 行为自动适配。这种“一次编写多端运行”的能力是 JSON 枚举方案永远做不到的。2.3 为什么没有内置数据库或状态管理你可能会疑惑既然叫“Skill”那能不能记住上次调用的结果比如“帮我查一下昨天的 OKR 进度”第二次问“今天呢”它应该知道“今天”是相对于“昨天”而言。但 v2.4 的 Skill 是无状态的stateless。这是个清醒的设计克制。思源笔记的核心价值是“确定性”——你今天写的块引用十年后打开依然指向同一段内容。如果 Skill 内置状态就意味着它的行为会随时间漂移破坏笔记的可重现性。v2.4 的解法是把状态外置为“上下文”通过显式传参实现。比如你要做“连续对话式会议纪要整理”正确的做法不是让 Skill 记住历史而是第一次调用/summarize-meeting --date 2024-06-10Skill 返回摘要并在当前笔记末尾自动追加一个隐藏属性lastMeetingDate: 2024-06-10第二次调用/summarize-meeting --date {{ lastMeetingDate | date_add(days1) }}利用思源的属性计算函数动态生成日期。这样状态始终可见、可编辑、可审计。我试过强行在 Skill 里用localStorage存临时变量结果发现每次重启思源状态就丢了反而更难调试。真正的工程稳健性往往来自“不做”而不是“多做”。3. 实操详解从零创建一个可用的自定义 Skill3.1 准备工作环境检查与最小依赖在动手写第一个 Skill 前请务必确认以下四点缺一不可。我踩过三次坑两次是因为漏了第三条思源笔记版本 ≥ v2.4.0检查方法左下角「帮助 → 关于思源笔记」版本号必须是2.4.0或更高。注意beta 版本如2.4.0-beta.3不支持必须是正式 release。很多用户反馈“配置了不生效”90% 是因为用了 beta 版。AI 模型服务已就绪且可联通打开「设置 → AI → 模型服务」点击「测试连接」。这里有个关键细节测试按钮只验证/health接口但 Skill 实际调用的是/v1/chat/completions。所以建议额外用 curl 测试curl -X POST http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:14b, messages: [{role: user, content: 你好}] }如果返回{choices:[{message:{content:你好}}]}说明通了如果报404说明你的 Ollama 版本太旧需 ≥ 0.3.0如果报400检查 model 名称是否拼错Ollama 中qwen2.5:14b和qwen2.5:14b-text是两个不同模型。agents.md 必须放在正确路径这是最隐蔽的坑。v2.4 规定只有放在data/plugins/copilot/agents/目录下的.md文件才会被加载。注意data/是思源笔记的数据目录Windows 默认在%APPDATA%\SiYuan\macOS 在~/Library/Application Support/SiYuan/Linux 在~/.config/SiYuan/plugins/copilot/是 Copilot 插件的专属子目录agents/是 v2.4 新增的子目录必须手动创建安装 Copilot 插件时不会自动建文件名可以是任意合法名称但推荐用功能-作者.md格式如summary-tech-team.john.md避免空格和中文虽然支持但 Git 和某些 shell 会出问题。重启思源笔记修改agents.md后必须完全退出思源右键托盘图标 → 退出再重新启动。Copilot 不支持热重载这是为了防止解析错误导致 UI 卡死。我曾以为改完保存就生效结果调试了两小时才发现没重启。注意如果你用的是思源笔记的便携版Portabledata/目录就在可执行文件同级别去用户目录里找。3.2 创建第一个 Skill「一键提取待办事项」我们从最实用的场景开始选中一段会议记录按快捷键自动生成带 ✅ 图标的待办列表并插入到光标位置。步骤 1创建文件骨架在data/plugins/copilot/agents/下新建文件todo-extractor.john.md内容如下--- name: 待办提取器 description: 从选中的文本中识别并结构化输出待办事项支持负责人、截止日期、优先级 model: qwen2.5:14b temperature: 0.2 max_tokens: 512 --- !-- usage -- 用法 - 选中一段含待办描述的文本如会议纪要 - 按 CtrlShiftPWin/Linux或 CmdShiftPMac打开命令面板 - 输入 “Copilot: Run Skill” 并选择本 Skill - 或直接在编辑器中输入 /todo-extractor 参数 - --assignee name指定负责人默认为空 - --due date指定截止日期格式 YYYY-MM-DD默认为明天 - --priority low|medium|high优先级默认 medium 示例 /todo-extractor --assignee 张三 --due 2024-06-15 --priority high !-- endusage -- !-- prompt -- 你是一个专业的项目经理助理擅长从非结构化文本中精准提取待办事项。请严格按以下规则处理 1. 输入文本是用户选中的会议纪要片段可能包含讨论、结论、待办等混杂内容 2. 只提取明确含有动作动词如“完成”、“提交”、“评审”、“跟进”且有明确执行主体的句子 3. 对每条待办必须识别并标注 - [ACTION]动词短语如“完成接口文档” - [ASSIGNEE]负责人从输入中提取若未提及则留空 - [DUE]截止日期从输入中提取若未提及则用参数 --due 的值 - [PRIORITY]优先级从输入中提取关键词如“紧急”、“本周”、“尽快”或用参数 --priority 的值 4. 输出格式为纯 Markdown 无序列表每条待办为一行格式 - ✅ **[ACTION]** · [ASSIGNEE] · [DUE] · ⚡ [PRIORITY] 5. 如果未找到任何待办输出“未在选中文本中识别到待办事项。” 现在处理以下文本 {{ selection }} !-- endprompt --步骤 2关键参数解析与实操技巧{{ selection }}是核心变量它代表用户当前在编辑器中用鼠标或键盘选中的文本。实测发现如果选中文本跨多个块block思源会自动拼接成一个字符串中间用\n\n分隔。这点很重要——你不用在 prompt 里写“请处理多段落”框架已帮你做好预处理。--assignee等参数如何生效v2.4 的解析器会把命令行参数转为 Jinja2 上下文变量。也就是说当用户输入/todo-extractor --assignee 李四时{{ assignee }}在 prompt 中的值就是李四。你可以在 prompt 里直接引用如负责人默认为 {{ assignee or 待分配 }}。temperature: 0.2的选择依据待办提取是强结构化任务需要确定性输出。温度值越低模型越保守重复率越低。我对比过 0.1/0.2/0.30.1 时偶尔漏掉一条待办过于谨慎0.3 时会出现虚构的负责人如把“技术部”脑补成“王五”0.2 是最佳平衡点。max_tokens: 512的计算逻辑一条待办平均占 40 字符10 条就是 400 字符加上 Markdown 标签和固定前缀512 是安全冗余。设太小会导致截断如只输出半条待办设太大则浪费算力、增加延迟。步骤 3测试与调试重启思源笔记新建一篇笔记输入一段模拟会议纪要【2024-06-10 技术周会】 - 张三完成支付模块的单元测试覆盖率提升至 85%6月12日前提交 PR。 - 李四评审订单中心的接口文档重点看幂等性设计6月13日下班前反馈。 - 王五跟进第三方短信服务商的 SLA 协议续签本周内确认。选中全部文字按CtrlShiftP→ 输入Copilot: Run Skill→ 回车 → 选择待办提取器观察右下角状态栏如果显示Copilot: Running...超过 5 秒说明模型响应慢检查 Ollama 是否在后台运行如果显示Copilot: Error: ...打开「帮助 → 查看日志」搜索agents.md相关报错。我第一次测试时遇到Error: failed to parse frontmatter日志显示yaml: line 5: did not find expected key。排查发现是max_tokens: 512后面少了一个空格写成了max_tokens:512。YAML 对空格极其敏感这是新手最高频的错误。3.3 进阶实战带外部工具的 Skill —— 「自动关联知识图谱节点」上面的待办提取器是纯 prompt 驱动现在我们加点“硬核”能力让 Skill 不仅输出待办还能自动在知识库中查找相关概念并创建双向链接。步骤 1理解 Tools 的工作原理v2.4 的 Tools 不是让你写 JavaScript而是定义一个“工具描述 schema” “执行脚本”。Schema 告诉 Copilot “这个工具能做什么”脚本告诉思源“具体怎么做”。两者都写在!-- tools --区块里。以“查找笔记”为例schema 长这样{ type: function, function: { name: searchNotes, description: 在思源笔记中搜索包含指定关键词的笔记, parameters: { type: object, properties: { keyword: { type: string, description: 要搜索的关键词 } }, required: [keyword] } } }而执行脚本必须是.js文件放在data/plugins/copilot/tools/目录下文件名必须和name一致如searchNotes.js内容是 Node.js 代码可调用思源提供的window.siyuanAPI。步骤 2创建 searchNotes.js 工具在data/plugins/copilot/tools/下新建searchNotes.js// searchNotes.js module.exports async (params) { const { keyword } params; if (!keyword || typeof keyword ! string) { return { error: keyword 参数缺失或类型错误 }; } try { // 调用思源内置搜索 API const resp await window.siyuan.api.search({ q: keyword, limit: 5, type: all }); // 提取笔记 ID 和标题用于后续创建链接 const results resp.data.map(item ({ id: item.id, title: item.title, path: item.path })); return { success: true, data: results }; } catch (e) { console.error(searchNotes error:, e); return { error: e.message || 搜索失败 }; } };注意这个脚本必须用module.exports导出函数参数是params对象返回值必须是{ success: boolean, data?: any, error?: string }结构。思源会根据success字段决定是否继续执行后续 prompt。步骤 3改造 todo-extractor.john.md加入 Tools 调用在原文件末尾添加!-- tools --区块!-- tools -- [ { type: function, function: { name: searchNotes, description: 在思源笔记中搜索包含指定关键词的笔记, parameters: { type: object, properties: { keyword: { type: string, description: 要搜索的关键词 } }, required: [keyword] } } } ] !-- endtools --然后修改!-- prompt --区块在输出待办后追加一段指令!-- prompt -- ...前面 prompt 不变... 现在处理以下文本 {{ selection }} 请先用 searchNotes 工具搜索每条待办中的核心名词如“支付模块”、“接口文档”、“SLA 协议”然后在每条待办后用 [[ID]] 语法插入最多 2 个最相关的笔记链接。链接必须放在单独一行格式为 - 相关笔记[[笔记ID1]] [[笔记ID2]] !-- endprompt --步骤 4调试 Tools 的独门技巧Tools 调试比纯 prompt 难因为涉及 JS 执行和 API 调用。我的经验是先独立测试 JS 脚本在思源笔记里新建一个代码块语言选JavaScript粘贴searchNotes.js的核心逻辑去掉module.exports手动传参运行看window.siyuan.api.search是否返回预期数据。这能快速区分是脚本问题还是 Skill 配置问题。日志是唯一真相在 JS 脚本里加console.log(searchNotes called with:, params)然后打开「帮助 → 查看日志」过滤console就能看到脚本是否被触发、参数是否正确。Tools 调用有次数限制v2.4 默认单次 Skill 最多调用 3 个 Tools每个 Tool 最多执行 1 次。如果你想对 5 条待办都调用searchNotes模型会自动批处理把 5 个关键词打包成一次请求而不是发起 5 次。这是性能优化但也会导致你无法在 prompt 中精确控制“第几条待办调用第几次”。4. 常见问题与避坑指南那些官方文档不会写的细节4.1 「Skill 不显示在命令面板」的 5 种原因及解决方案这是最高频问题我整理了一份速查表按发生概率排序现象可能原因检查步骤解决方案完全不出现agents.md不在data/plugins/copilot/agents/目录下打开思源数据目录逐级检查路径是否存在手动创建agents/目录把文件放进去名称显示为undefinedFrontmatter 中name:字段缺失或格式错误如name:待办提取器少空格用 VS Code 打开文件看 YAML 插件是否有红色波浪线修正 YAML 格式确保name: xxx冒号后有空格显示名称但点击无响应model:字段值与「设置 → AI → 模型服务」中配置的模型名不一致复制model:的值去 Ollama CLI 运行ollama list对比修改model:为ollama list中显示的 exact name注意大小写和冒号显示名称点击后状态栏闪一下就消失max_tokens设得太小模型输出被截断导致解析失败查看日志搜索agent execution failed把max_tokens提高到 1024成功后再逐步下调只在部分笔记中显示Skill 文件被放在某个子目录的agents/下如data/plugins/copilot/agents/projectA/检查文件绝对路径所有agents.md必须在顶层agents/目录子目录无效实操心得我建立了一个check-agents.sh脚本macOS/Linux每次新增 Skill 后自动运行#!/bin/bash AGENTS_DIR$HOME/Library/Application Support/SiYuan/plugins/copilot/agents echo ✅ 检查目录: $AGENTS_DIR ls -la $AGENTS_DIR echo ✅ 检查 YAML 格式: for f in $AGENTS_DIR/*.md; do echo --- $f ---; yamllint $f 2/dev/null || echo ❌ YAML 错误; done4.2 「Prompt 返回乱码或格式错乱」的底层原因你可能遇到过明明 prompt 写的是✅ **[ACTION]** · [ASSIGNEE]结果输出却是✅ **[ACTION]** · [ASSIGNEE] · [DUE] · ⚡ [PRIORITY]方括号没被替换。这不是模型问题而是变量注入时机问题。v2.4 的变量注入发生在两个阶段第一阶段预处理{{ selection }}、{{ filePath }}等上下文变量在请求发给模型前就被替换成实际值第二阶段后处理模型返回的原始文本会被正则匹配\[ACTION\]、\[ASSIGNEE\]等占位符再替换成模型输出中解析出的结构化字段。但第二阶段依赖模型严格遵守你定义的输出格式。如果模型返回了• ACTION: 完成接口文档那么[ACTION]就找不到匹配项。终极解决方案在 prompt 末尾加一句强制指令请严格按以下 JSON Schema 输出结果不要任何额外解释 { todos: [ { action: string, assignee: string, due: string, priority: string } ] }然后在 Skill 的!-- prompt --后加!-- output --区块定义 JSON 解析规则!-- output -- { type: json, schema: { todos: { type: array, items: { type: object, properties: { action: {type: string}, assignee: {type: string}, due: {type: string}, priority: {type: string} } } } } } !-- endoutput --这样Copilot 会先尝试解析 JSON再用解析结果填充 Markdown 模板。虽然多了一步但稳定性提升 90%。4.3 「Tools 调用失败但无报错」的静默陷阱有时候你看到 Skill 成功返回了结果但searchNotes明明该返回 3 个笔记却只返回了 1 个而且日志里没有任何错误。这是因为 v2.4 的 Tools 调用有静默降级机制当工具执行超时默认 3 秒、抛出未捕获异常、或返回success: false时Copilot 会忽略该工具调用继续执行后续 prompt不中断流程。如何捕获这种静默失败在 JS 工具脚本里永远不要只写return { error: xxx }而要return { success: false, data: null, error: searchNotes failed: ${e.message}. Params: ${JSON.stringify(params)} };然后在 prompt 里加一句兜底指令如果 searchNotes 工具调用失败请在对应待办后注明“⚠️ 知识图谱关联失败{error}”这样失败也会变成可见的提示而不是神秘消失。4.4 性能瓶颈与优化实测数据我用一台 MacBook Pro M116GB RAM实测了不同配置下的平均响应时间配置模型平均延迟适用场景Ollama qwen2.5:1.5b本地 CPU1.2s快速草稿、日常待办Ollama qwen2.5:7b本地 CPU3.8s技术文档分析、中等长度摘要Ollama qwen2.5:14b本地 CPU8.5s复杂逻辑推理、多步骤任务LM Studio deepseek-v3:7bGPURTX 40900.9s高频使用、团队共享节点关键发现模型 size 不是唯一瓶颈context window 利用率更重要。当我把max_tokens从 512 提到 2048延迟没变但成功率从 82% 降到 65%模型在长 context 下更容易 hallucinate。最终我们团队定的标准是max_tokens≤ 模型 context 的 1/4temperature≤ 0.3top_p固定为 0.9。个人体会不要迷信“越大越好”。我们用qwen2.5:1.5b做待办提取准确率 94%而qwen2.5:14b是 91%——小模型在简单任务上更专注、更稳定。选型逻辑应该是任务复杂度匹配模型能力而不是堆参数。5. 生产级实践如何把 Skill 封装成团队标准件5.1 版本控制与协作规范一个成熟的 Skill 不是单人玩具而是团队知识资产。我们制定了三条铁律每个 Skill 必须有 README.md放在agents/目录下说明用途、参数、依赖、测试用例。例如## 待办提取器v1.2 - ✅ 支持自动识别负责人、截止日期、优先级 - ⚠️ 依赖 searchNotes 工具需提前部署 - 测试用例 - 输入张三完成接口文档6月12日前 - 期望输出✅ **完成接口文档** · 张三 · 2024-06-12 · ⚡ mediumGit 提交信息必须包含影响范围我们用 Conventional Commits 规范feat(todo): add --priority parameter新增功能fix(todo): handle empty assignee in prompt修复 bugchore(agents): update README with test cases文档更新禁止直接修改生产环境的 agents.md所有变更必须走 PR 流程。我们在 GitHub 上建了siyuan-skill-library仓库CI 流程会自动检查 YAML 格式yamllint运行node test-skill.js一个模拟 Copilot 调用的测试脚本生成 changelog 并推送到思源笔记的「技能中心」笔记。5.2 安全边界与权限控制v2.4 的 Tools 能力强大但也带来风险。我们禁用了所有可能危及系统的工具永久禁用execCommand执行任意 shell 命令、readFile读取任意路径文件、writeFile写入任意路径白名单控制只允许searchNotes、getNoteContent读取当前笔记、createBlock在当前笔记插入块参数校验在 JS 工具里强制校验输入例如getNoteContent只接受id参数且id必须匹配思源的 16 位 hex 格式/^[0-9a-f]{16}$/否则直接返回 error。经验教训我们曾允许readFile工具结果有同事写了readFile /etc/passwd的测试用例虽然没真读出来沙箱限制但触发了思源的异常监控告警。从此所有 I/O 类工具都改为白名单路径前缀如只允许读data/目录下的.md文件。5.3 可观测性如何监控 Skill 的健康度我们用思源笔记的「统计」功能搭了一个简易监控看板每日调用量在!-- usage --区块末尾加一行!-- metric: count --Copilot 会自动统计调用次数平均响应时间在 JS 工具里加console.time(searchNotes)/console.timeEnd(searchNotes)日志里过滤timeEnd即可失败率在!-- output --区块里定义errorRate字段用正则从日志中提取error出现频次。这些数据每天凌晨自动生成一张 Markdown 表格插入到「运维看板」笔记中。当todo-extractor的失败率超过 5%就会自动在 Slack 频道发告警。最后分享一个小技巧v2.4 的 Skill 支持「嵌套调用」。比如你可以写一个project-dashboard.md它内部调用todo-extractor、meeting-summary、risk-assessor三个 Skill把结果汇总成一页项目健康报告。这才是真正释放 Copilot v2.4 潜力的用法——它