personal-siyuan-standards

个人思源笔记规范

用户的思源笔记库个人记笔记约定。此技能是一个路由和约定层，而非操作层——所有实际操作（创建文档、搜索、添加标签，……）均通过 siyuan-note MCP 工具完成。对于每个新建笔记请求，它会回答两个问题：

• 新笔记应放在哪里？ → map.md（仅用于创建；通过搜索定位现有笔记）
• 新笔记应添加哪些标签？ → tag.md

要求

• 已连接 siyuan-note MCP 服务，且已加载其工具 （笔记本、文档、搜索、块/属性，……）。如果这些工具不可用，请停止操作， 并告知用户在继续之前需要连接 MCP 服务。

运行时文件

所有运行时数据均存放在 ~/.wmyskills/personal-siyuan-standards/：

文件	用途	维护者
map.md	新笔记的笔记本 → hPath 映射（仅用于创建）	用户（Agent 提议）
tag.md	标签规则：新笔记应添加哪些标签，以及何时添加	用户（Agent 提议）

首次运行： 如果缺少 map.md 或 tag.md，请从此技能的 references/ 中复制对应模板（map.example.md、 tag.example.md）并创建文件，然后继续。切勿重新创建已有文件。

写入策略（适用于两个文件）： 这些文件由用户维护。当 Agent 发现值得记录的信息（新的位置、新的标签）时，请在最终报告中提出修改建议，并仅在用户确认后写入。绝不自动记录一次性决定。

用户的明确指示始终优先于这些规范。

映射：新笔记的存放位置（map.md）

创建笔记时，如果用户没有明确指定位置，请阅读 map.md——它会将新笔记路由到对应的存放 hPath，不用于定位现有笔记（应改用搜索）。这是一个包含三列的 Markdown 表格：

列	含义
Notebook	新笔记所在的思源笔记本
hPath	笔记本内便于阅读的路径（例如 /Parent/Child）——绝不包含笔记本名称，参见下文“路径”
Description	此位置的用途，以及何时优先选择此位置

匹配。 根据含义选择 Notebook、hPath 和 Description 最符合用户请求的行，而不是按关键词是否相同来匹配。如果有多行都可能适用，优先选择其描述与当前请求意图相符的一行（例如，阅读笔记选择研究位置，工作笔记选择工作位置）。所选行仅是起始位置：随后“创建”工作流会递归进入子文档，找到最合适的位置（见下文“创建”）。

没有匹配项？ 按以下顺序处理两种情况：

1. 如果某行的 Description 明确声明该行是兜底选项（例如 “Use this when nothing else matches/未匹配时使用此”——其他选项都不匹配时使用此 Notebook 和 hPath），则将笔记放在那里。
2. 否则自行决定存放位置——查看实际的笔记本层级和笔记内容，选择合适的位置。此决定为一次性决定：仅用于本次请求，不要将其追加到 map.md。你可以在最终报告中提议添加一行。

hPath。 思源的便于阅读的路径以笔记本内部为根，绝不包含笔记本名称——笔记本始终单独选择（此处的 Notebook 列；MCP 调用的 notebook 参数）。例如，对于笔记本 Daily 中位于 2026/08 下的文档 2026-08-10，hPath 为 /2026/08/2026-08-10——写成 /Daily/2026/08/2026-08-10 是错误的。开头的 / 表示笔记本根目录。在映射的 hPath 下创建文档时，请先创建任何缺失的父文档。

标签：要添加哪些标签（tag.md）

创建笔记时读取 tag.md（查找/修改时不读取）。条目如下所示：

**tagName**: <actual tag name>
Explanation lines: when to apply / not apply this tag

• 要应用的标签是 **tagName**: 后面的名称。下面的行可能会说明何时应用或不应用该标签。
• 如果某条目的说明未提及时间，则采用默认规则：每篇新笔记都添加该标签。
• 如果有多条条目符合新笔记的情况，则全部应用。
• 如果没有符合的条目，则不要给笔记添加标签，并在报告中说明。

添加标签的方法。 通过 MCP attr/block 工具，在新文档的根块上设置 tags 自定义属性（以逗号分隔），以添加真正的 SiYuan 标签。切勿添加 tag.md 中未定义的标签（除非用户明确要求）。

修改操作绝不处理标签——只有创建笔记时才会添加标签。

语法规则

编写笔记内容时（代码块和行内代码除外）：

• 美元符号 $——SiYuan 会将 $...$ 视为行内数学公式。如果不是要写公式，则将每个 $ 转义为 \$，包括单独出现的 $。例如：The fee is \$100. 会呈现为“The fee is $100。”
• 井号 #——在标题和代码块之外，# 可能会被解释为标签标记。如果不是要写标签，则将每个 # 转义为 \#，包括单独出现的 #。例如：Issues \#101 and \#102.——如果不转义，SiYuan 会在两个 # 之间创建标签。例如：#tagName# → 一个标签；\#tag\# → 文本“#tag#”。

标题（行首的 #）使用自己的语法，无需转义。标题文本中的 $ 和 # 若未用于其特殊用途，仍需转义。

在代码块中（包括行内 `code` 和围栏代码块），$ 和 # 按原样书写，无需转义。

链接约定

每当编写或修改笔记内容时均适用：

• 外部链接——跳转到网页或静态资源页面的链接：使用 Markdown 链接语法 [锚文本](URL)，呈现为可直接点击的链接。
• SiYuan 引用——块引用和文档引用：使用 SiYuan 的引用语法——块引用使用 ((blockID "锚文本"))，文档引用使用 ((docID "锚文本"))，显示文本需用引号括起作为锚文本。

单轮工作流

每个用户请求都是一轮：从请求到报告，一轮会在执行任何操作之前进行一次轮前同步（即使是只读轮），并且——如果执行了任何写入操作——进行一次轮后同步。不要在每次单独的笔记操作后同步；将整轮操作打包为一对轮前／轮后同步。这就是完整的一轮，涵盖每个请求：

graph TD
    A[User request] --> B[Load this skill and the siyuan-note MCP tools]
    B --> B2[List notebooks to get notebook IDs]
    B2 --> C["Read map.md and tag.md (creation only)"]
    C --> D[Pre-round sync]
    D --> E[Operate on SiYuan notes<br/>1 or more operations]
    E --> F[Review: operations succeeded]
    F --> G[Post-round sync]
    G --> H[Report to user]

1. 列出笔记本。 MCP 工具加载后，立即使用 MCP notebook 工具列出笔记本，并记下它们的ID——后续每次需要 notebook 参数的 MCP 调用都必须使用 ID，而不是名称。map.md 中的映射行按名称匹配；在此处将每个匹配项解析为其 ID。 （已关闭的笔记本不会列出——如果映射的笔记本未出现在列表中，很可能是已关闭；请询问用户或选择其他位置。）
2. 读取规范文件。 如果本轮会创建笔记，则读取 tag.md（参见标签规则）；除非用户指定了位置（参见映射规则），否则还要读取 map.md。使用 MCP search 工具查找现有笔记，而不是使用 map.md。
3. 轮前同步。 在任何操作之前，使用 MCP sync 工具触发同步——创建、修改、移动等操作，以及纯查找／只读轮都包括在内。每轮恰好执行一次，并且在第一个操作之前执行。
4. 执行操作。 按照下方的操作说明执行请求——执行一项或多项笔记操作。
5. 检查。 确认每项操作均已成功；如果某个步骤失败，请先修复或重试，再继续。
6. 轮后同步。 如果本轮执行了任何写入操作，则再次使用 MCP sync 工具触发同步。
7. 报告。 遵循报告格式；始终注明同步状态。

同步失败处理。 同步失败不会阻止本轮操作——仍需继续执行——但最终报告必须明确警告知识库可能未同步。不要重试失败的同步，也不要因此跳过剩余步骤。

操作说明

创建

graph TD
    A[Start: create a note] --> A1{Location specified by user?}
    A1 -- Yes --> A2[Create at the specified location<br/>skip map.md and descent]
    A2 --> T
    A1 -- No --> B[Read map.md for the preferred hPath]
    B --> C[Enter that hPath]
    C --> D[List child notes under the hPath]
    D --> E{Any child fits better?}
    E -- Yes --> F[Read that note's content]
    F --> G[Make it the current hPath]
    G --> D
    E -- No --> H[Current hPath is the best match]
    H --> I[Create the note here]
    I --> J{hPath already in map.md?}
    J -- No --> K[Propose adding it to map.md<br/>never write without confirmation]
    J -- Yes --> T[Apply matching tags from tag.md]
    K --> T
    T --> R[Report location, sync status,<br/>and any map.md/tag.md proposals]
    R --> L[Done]

1. 用户指定的位置优先。 如果用户明确说明笔记应放在哪里（笔记本或路径），就直接在那里创建——跳过 map.md 和递归下探。只有用户未指定位置时，才使用 map.md 和下探流程。
2. 阅读 map.md；选择目标位置（参见上文的 Map 规则）。如果没有匹配的行，也没有任何行声明其为默认位置，则自行决定一次性放置位置——直接放置笔记，不再下探。
3. 下探到最合适的 hPath。 从映射到的 hPath 开始，列出其子文档。先根据标题判断，再阅读最有希望的候选文档内容，并询问：是否有哪个子文档比当前 hPath 更符合请求？如果有，就将其设为当前 hPath 并重复此过程。直到没有更合适的子文档为止——当前 hPath 即为最终位置。 深度不受限制：下探只会沿子文档向下进行，因此一定会终止。
4. 使用 MCP document 工具创建文档——notebook 用于选择笔记本，而 path 是包含文档名称的完整目标路径，不是父文件夹（例如：notebook: "Daily-notebook-id"，path: "/2026/08/2026-08-10"；笔记本名称绝不会在 path 中重复）。父文件夹必须已存在；如果缺少父文档，请先创建。工具的响应会回显你传入的 path，因此如有疑问，请使用 siyuna MCP 工具核实实际位置。
5. 笔记正文中不要使用 h1。 文档标题已显示为 h1，因此正文中绝不要写一级标题（# …）——章节标题从 h2 开始。
6. 阅读 tag.md；将所有匹配的标签应用到新文档（参见上文的 Tag 规则）。
7. 报告：笔记创建的位置；该位置是否为一次性猜定（没有匹配的 map 行）——并可酌情提议添加 map.md 行或 tag.md 条目，供用户确认。如果最终 hPath 比映射行更深（或没有匹配的行），请提议将最终 hPath 添加到 map.md——未经用户确认，绝不要写入。

查找（只读）

1. 使用 MCP search 工具（全文搜索）定位笔记——map.md 仅供创建新笔记时参考。
2. 打开并阅读候选笔记的内容，确认它确实是用户所指的笔记后再报告。
3. 只读轮次仍会运行轮次前同步（参见 One Round Workflow）；只有因为没有执行写入，才跳过轮次后同步。

修改

1. 使用 MCP search 工具定位笔记（适用查找规则）。
2. 先阅读文档内容，并确认其符合用户意图，再进行任何更改。 修改错误的笔记比询问用户更糟。
3. 如果找到的文档不匹配，请重新搜索；如果仍不确定，请询问用户。
4. 执行更改。不要修改笔记的标签。

删除 / 移动 / 重命名

1. 使用 MCP search 工具定位笔记（适用查找规则）。
2. 删除、移动或重命名前，请阅读文档内容并确认它就是目标笔记——同样要遵循“修改”中的谨慎原则。
3. 执行操作。移动时，path 必须是已存在的目标位置——笔记会成为它的子项，因此如有需要，请先创建目标位置（适用与“创建”相同的完整 hPath 规则）。
4. 移动或重命名后，报告笔记的新位置；删除后，报告删除了什么以及它原本所在的位置。

报告风格

创建、查找或修改笔记后，始终告知用户笔记所在位置；移动或重命名后，告知新位置——使用 Notebook / hPath，以便用户核实。如果你一次性猜定了放置位置、跳过了标签应用，或未能定位某项内容，请明确说明。如果发现了稳定的新模式，请提议更新 map.md / tag.md。

始终报告本轮的同步状态。如果轮次前或轮次后同步失败，请明确警告用户知识库可能未同步。