思源知识库管理

When to Use（何时使用）

• 用户提到"思源笔记"、"SiYuan"、"笔记管理"时激活
• 用户要求"整理笔记"、"批量编号"、"加索引"时激活
• 用户需要"批量同步仓库到思源"、"微信文章导入"、"技术规范下载"时激活
• 用户咨询"父页索引规范"、"MOC 结构"、"标签体系"时激活
• 工作流涉及"文档层级命名"、"块 ID 获取"、"目录链接格式"时激活

Don't use for:
- 思源安装、配置、服务器部署（不是 PKM 方法论范畴）
- 纯写作/读书笔记内容生成（用 obsidian 或通用写作 skill）
- 思源插件开发（用 siyuan-skill-enhanced 处理 API）

三层架构

第一层：笔记本（注意本也要加编号！）
001_学习笔记   → 知识输入
002_工作笔记   → 工作事务
003_读书笔记   → 阅读管理
004_个人项目   → 项目追踪
005_日记       → 每日记录
006_闪念笔记   → 灵感碎片

第二层：PARA 分区（所有笔记本的第一层目录也用编号）
  笔记本/
  ├── 001_闪念笔记 Fleeting
  ├── 002_项目 Projects
  ├── 003_领域 Areas
  ├── 004_资源 Resources
  ├── 005_永久笔记 Permanent
  └── 006_档案 Archives

第三层：块 (双向链接)

父页索引规范

核心规则：目录索引必须是双链索引。

每个有子文档的父页必须在文档内容末尾包含子文档一览表，使用 SiYuan 双链（[[]] 文档链接），而不是 Markdown 纯文本表格。

原因： 双链索引可双向链接：从父页可跳转子页，反向链接面板也能看到谁引用了子页，形成真正的网状知识结构。Markdown 表格只是文字列表，没有链接能力。

规则：
- 📌 仅笔记本根目录下有 999_README 文档，用于总览索引
- 📌 子父页（如 010_Agent、001_论文笔记）不另外建 README 文档，双链索引表写在文档正文末尾。如需从旧版子 README 迁移，见 references/parent-index-migration.md
- 📌 必须用 [title](siyuan://blocks/块ID) 格式，[[]] 文档双链语法仅在思源编辑器里交互式输入时生效，通过 API 写入时会被存为纯文本而非可点击的链接。双链索引表格式示例：

# 001_论文笔记（23篇）

## 📑 目录索引

- [000_Agent Survey](siyuan://blocks/20260619201703-1em2nl4) — 总结各类Agent范式，综述
- [001_AutoGen](siyuan://blocks/20260619201641-j7lnwm3) — 微软多Agent对话框架
...

> 📌 编号从 `000` 开始，因为子文档在父文档之下，000 表示"第一个子文档"
> 📌 编号同样用于双链显示名，方便在反向链接面板中定位排序
> ⚡ 块ID = 文档ID，从 `structure` 命令的输出中获取
> 🔗 技术细节见 [references/siyuan-api-wikilinks.md](references/siyuan-api-wikilinks.md)（含验证方法）
> 🔗 文档正文 `## 目录` 的双链匹配算法见 [references/siyuan-dir-link-algorithm.md](references/siyuan-dir-link-algorithm.md)（涵盖章节号匹配、翻译文本不一致处理、Markdown 链接格式陷阱、常见 Pitfalls）

双链索引优势：
1. ✅ 可跳转 — 点击 [标题](siyuan://blocks/块ID) 直达子文档
2. ⚠️ 反向链接有限 — 叶子页的列表级 siyuan:// 链接会显示在反向链接面板；MOC 页的标题级链接不会（标题块本身是目标）
3. ✅ 图图谱 — 在思源关系图中保持父子关系可见
4. ✅ 永久有效 — 使用块ID链接，文档改名后链接不失效
5. ✅ 结构化 — 在 - 列表项中用冒号分隔编号和描述，保持可读性

MOC 总览页配分类导读即可。

大规模子文档的索引策略（50+ 篇）

当父页面有 50+ 子文档时，不要用一页扁平的列表。用分组概览 + 精选链接替代：

# 父页标题

## 📑 系列概览

| 分组 | 数量 | 链接 |
|------|:----:|:----:|
| 📘 系列A | 20 | [A 系列](siyuan://blocks/<ID>) |
| 📗 系列B | 101 | [B 系列](siyuan://blocks/<ID>) |

• 按文档类型/系列分组（如 AUTOSAR 的 ASWS/EXP/RS/SWS/TPS/TR）
• 每个系列给一小段概述 + 代表性链接
• 完整列表由 structure 命令提供，不在父页正文穷举
• 实战参考：software-development/autosar-import-pipeline 技能的 references/batch-import-reference.md

日常流程

捕获 → 暂存 → 归置 → 提炼 → 链接 → 回顾

• 捕获：灵感记到闪念笔记或目标笔记本的 01-收集箱
• 归置（每周）：有任务→02-项目，工作领域→03-领域，学习材料→04-资源，可提炼→05-永久笔记，过期→06-档案
• 提炼：渐进式摘要（加粗→高亮→写摘要）
• 链接：((block-id)) 建立双向链接
• 回顾：每月合并重复笔记，更新 MOC

批量同步工作流（仓库→思源）

Phase 1-2：探明结构 + 建分组骨架

# 先建 MOC
node siyuan.js create "主题" --parent-id <id>
# 再建分类分组
node siyuan.js create "论文笔记" --parent-id <moc-id>
node siyuan.js create "框架笔记" --parent-id <moc-id>

Phase 3：写入文档

curl -s "http://<host>/.../contents/<path>" -u "<user>:<pass>" \
  | python3 -c "import sys,json,base64; print(base64.b64decode(json.load(sys.stdin)['content']).decode())" \
  > /tmp/doc.md
node siyuan.js create "标题" --parent-id <category-id> --file /tmp/doc.md

⚠️ 70+ 文档平铺 = 不可读。先建分组再倒入。

微信文章导入

完整流程（抓取 / 提取 / 创建 / 后处理）→ references/wechat-article-import.md

4 步要点：
1. 抓取（公众号链接）
2. 提取纯文本 + 图片 URL
3. 下载图片 → 上传思源（key: file[]）→ 嵌入
4. 分类 → 后处理（重命名 + 移动 + 更新索引）

📑 论文笔记（N篇）

一句话描述

```bash
node siyuan.js update <moc-id> --file /tmp/moc.md

Phase 6：给每个分类父页写双链索引（写入父文档正文，不建 README）

⚠️ 关键：必须用 [title](siyuan://blocks/块ID) 格式，[[]] 通过 API 写入不会生效。

# Step 1: 获取子文档精确标题 + 块ID（必须！不要猜）
node siyuan.js structure <parent-id> --depth 1
# 输出中 title 为显示名，id 为块ID（= 文档ID），用于 siyuan://blocks/ 链接

# Step 2: 构建双链索引内容到文件
# 每条格式：
# - [NNN_精确文档标题](siyuan://blocks/子文档ID) — 一句话简介
# 用标准 Markdown 链接 + siyuan://blocks/ 协议，不用 [[]]
# 块ID = 文档ID = structure 输出中的 id 字段
# 编号从 000 开始 +1 递增

# Step 3: 更新文档
node siyuan.js update <parent-doc-id> --file /tmp/parent_with_index.md

MOC 页特殊处理： MOC 页的双链直接嵌入 ## 标题中：

## 📑 [001_论文笔记](siyuan://blocks/20260619202941-qagswuo)（23篇）

AI Agent 领域经典论文与综述...

## 🛠 [002_框架笔记](siyuan://blocks/20260619203045-gloi0hm)（14个）

这样用户点击标题即可跳转到对应子页面，比正文末尾再加列表更直观。

⚠️ MOC 的反向链接面板：MOC 页的 ## 标题链接不会被反向链接面板捕获（标题块本身就是目标），子页面底部不显示「反向链接来自 MOC」。如需反向链接追踪，需在子页面正文内加 [返回 MOC](siyuan://blocks/MOC-id) 或正文末尾加索引段。

编号规范（核心规则 ⭐）

所有笔记本和所有笔记必须加编号。 没有编号=不合格。

编号规则：
- 笔记本 和 第一层目录 从 001 开始 +1 递增（001, 002, 003…）
- 子文档（父文档之下的文档）从 000 开始 +1 递增（000, 001, 002…）—— 因为子文档在层级上低于父文档，000 表示"第一个下层文档"
- 数字按语义分组排列，不是按创建时间

> 📌 所有笔记必须编号：不管是文件夹还是单个文档，只要在思源文件树里出现，就必须有 NNN_ 前缀。
> - 笔记本直下层 → 从 001 开始
> - 父文档下的子文档 → 从 000 开始
> - README 仅笔记本根目录有，固定 999_README + custom-sort=999

笔记本结构规范

每个笔记本必须遵循以下结构：

001_笔记本名称/
├── 001_目录名/    ← 从001开始编号（笔记本直下层）
│   ├── 000_子文档名   ← 从000开始编号（父文档之下）
│   ├── 001_子文档名
│   └── ...
├── 002_目录名/
├── ...
└── 999_README     ← 仅笔记本根目录下建README（设 custom-sort=999）

规则：
- 所有笔记本必须有 NNN_ 前缀，从 001 开始 +1 递增
- 笔记本直下的一级目录/文档 从 001 开始编号
- 二级及以下子文档（在父文档之下的）从 000 开始编号
- README 仅建在笔记本根目录下（999_README + custom-sort=999），父文档下不建 README
- 每个父文档的内容末尾包含其子文档的索引表（参见父页索引规范）

工作流：设置笔记本的编号

# 1. 重命名笔记本加上编号
node siyuan.js rename-notebook <notebook-id> "001_新名称"

# 2. 重命名第一层目录加上编号
node siyuan.js rename <folder-id> "001_目录名称"

# 3. 重命名文档加上编号
node siyuan.js rename <doc-id> "001_文档标题"

# 4. 创建/更新 README（仅笔记本根目录）
# README 放在笔记本根目录下，不放在子父页
node siyuan.js create "README" --parent-id <notebook-id> --file /tmp/readme.md

# 5. 重命名 README 为固定编号 999_README
node siyuan.js rename <readme-id> "999_README"

# 6. 设 README 的 custom-sort=999 双重沉底
# attrs 命令自动加 custom- 前缀，所以传 sort=999 会存为 custom-sort=999
node siyuan.js attrs <readme-id> --set "sort=999"

工作流：为笔记本内所有文档批量编号

# 列出结构，定位需要编号的文档
node siyuan.js structure <parent-id> --depth 2

# 逐个重命名
node siyuan.js rename <doc1-id> "001_文档名"
node siyuan.js rename <doc2-id> "002_文档名"
# ↓ 依此类推

完整批量重命名工作流（含获取ID、顺序、注意事项）：references/batch-rename-workflow.md
批量编号格式转换（001→000 重编号）：references/batch-numbering-conversion.md
父文档索引表迁移（删除子README → 正文内嵌索引）：references/parent-index-migration.md

README 索引格式

# 笔记本名 · 目录

| # | 目录/文档 | 一句话说明 |
|---|----------|-----------|
| 001 | 闪念笔记 | 快速捕获灵感，每天清理 |
| 002 | 项目 | 有截止目标的短期任务 |
| ...
| 999 | README | — | 本页说明 |

分类归属

不确定先放 03，用户觉得是资料再移 04。报告类直接放 06 档案即可，不需要走 03→06 的迁移路径。

外部技术规范下载（行业标准 → 本地文件 + 思源索引）

当需要将官方技术标准/规范文档纳入知识库（如 AUTOSAR、ISO、SAE 等标准），使用以下流程。

查找规范文档 URL 模式

多数标准化网站的规范 PDF 其实是公开可访问的，只是入口隐藏在搜索界面后：

# 1. 先找到搜索页面，分析 URL 结构
# 2. 确定文件存储路径模式（常见：fileadmin/standards/<release>/<platform>/...pdf）
# 3. 翻页遍历搜索页面（遍历所有结果页）获取完整列表

AUTOSAR 示例（autosar.org）：

# ⚠️ 不要用架构元素过滤器：会遗漏文件（验证发现约 10% 漏掉）
# 正确做法：逐页翻取搜索结果（paginated search）
import requests, re, time
BASE = "https://www.autosar.org"
all_paths = set()
page = 1
while True:
    url = f"{BASE}/search?tx_solr%5Bfilter%5D%5B0%5D=category%3AR25-11&tx_solr%5Bfilter%5D%5B1%5D=platform%3ACP&tx_solr%5BresultsPerPage%5D=100&tx_solr%5Bpage%5D={page}"
    resp = requests.get(url, headers={"User-Agent": "Mozilla/5.0 ..."}, timeout=30, verify=False)
    paths = re.findall(r'href="(fileadmin/standards/R25-11/CP/[^"]+\.(pdf|zip))"', resp.text)
    if not paths: break  # 没有更多结果
    all_paths.update(p[0] for p in paths)
    if f'tx_solr%5Bpage%5D={page+1}' not in resp.text: break  # 无下一页
    page += 1
    time.sleep(0.5)
print(f"Total: {len(all_paths)}")

处理服务器限速

标准化网站通常有连接级限速（~10 KB/s/连接），需要并行下载。推荐用 Python requests 流式下载：

import requests, concurrent.futures, os
BASE = "https://www.autosar.org/fileadmin/standards/R25-11/CP"
OUTDIR = "/mnt/c/Users/<user>/Desktop/autosar-cp-r25-11"

def download(fn):
    url = f"{BASE}/{fn}"
    fp = os.path.join(OUTDIR, fn)
    r = requests.get(url, stream=True, timeout=(15, 600))
    with open(fp, 'wb') as f:
        for chunk in r.iter_content(65536):
            f.write(chunk)
    return f"{fn} OK ({os.path.getsize(fp)//1024} KB)"

with concurrent.futures.ThreadPoolExecutor(max_workers=3) as ex:
    for result in ex.map(download, file_list):
        print(result)

关键参数：
- stream=True — 流式下载，不因慢速断开
- timeout=(15, 600) — 连接超时 15s，传输超时 600s（大文件需 10+ 分钟）
- max_workers=3 — 3 路并行，超过可能被服务器封 IP

生成索引清单

下载完成后，生成文件清单和目录索引：

# 生成 Markdown 索引文件（含文件名、大小、在线链接）
cat > _index.md << 'EOF'
# 规范名称 · 文件清单
| # | 文档名称 | 大小 | 链接 |
|---|---------|------|------|
EOF

# JSON 文件列表供程序使用
python3 -c "import json, os; ..."

分类决策

> 完整 PDF 规范通常不直接上传思源（文件大、数量多），而是存在桌面文件夹，思源笔记中做链接索引。如需将 PDF 正文转为 Markdown 导入思源（含表格保留），推荐使用 MinerU 桌面客户端（Windows 端 F:\\MinerU\\MinerU.exe，拖拽即转，表格输出为 HTML 格式，保真度远超 pdftotext/pdfplumber）。MinerU 转换后的 full.md 位于 C:\\Users\\<user>\\MinerU\\<filename-UUID>\\full.md，可直接导入思源或用 skills/productivity/ocr-and-documents 的 MinerU 工作流批量处理。从 MinerU 桌面端批量提取所有 full.md 到分组目录的脚本见 references/standards-download.md。

MinerU 输出后处理

MinerU 输出的 full.md 含 HTML <table> 标签、水印符号、旧式目录页等需要清理的元素。使用 scripts/clean_mineru.py 一键清理：

python3 scripts/clean_mineru.py "input/full.md" -o "output/clean.md"

清理效果：
- HTML <table> → Markdown 管道表（标准 | col1 | col2 |）
- 水印符号 ▽ △ → 移除
- ## Table of Contents 旧式目录 → 移除
- List of Figures / List of Tables → 移除
- <details><summary> 包装 → 移除，mermaid 图直接展示
- 连续空行 → 压缩到最多 2 行

翻译中文：清理后的 Markdown 可通过 delegate_task 子代理翻译。详见 references/mineru-postprocess.md。翻译后文档导入思源的完整流水线（含图片上传、表格转换、目录双链、Mermaid 修复）见 references/autosar-mineru-import-pipeline.md。

智能标签

标签是与目录正交的维度。目录管「放哪里」，标签管「是什么」。

五维标签法

每个笔记从 5 个维度各取 0-1 个标签：

自动化标记规则

命令行

# 设置标签（覆盖）
siyuan tags <doc-id> -t "AI-Agent,论文,微信"

# 追加标签
siyuan tags <doc-id> -t "AI-Agent" -a

# 查看标签
siyuan tags <doc-id> -g

完整参考：references/tagging-guide.md

SiYuan CLI 速查

所有命令详解（create / edit / tags / structure / 删除保护等）→ references/siyuan-cli-usage.md

核心 5 原则：
1. create 标题是位置参数（不是 --title）
2. 大文档用三步法：空创建 → 重命名 → 编辑
3. edit 写入后用 info 命令的 updated 字段验证
4. tags 命令是 -t（不是 --tags）
5. 删除需先关 safeMode（~/skills/siyuan-skill-enhanced/config.json）

Common Pitfalls（常见陷阱）

• ⚠️ 父页索引用 [[]] 写会被存为纯文本 → 必须用 [标题](siyuan://blocks/块ID) 格式（详见 references/siyuan-api-wikilinks.md）
• ⚠️ create --title + --content 同时传 → --title 被忽略，--content 当标题写。幽灵文档陷阱，必须用三步法
• ⚠️ 删除文档默认有保护 → 必须先关 safeMode（~/skills/siyuan-skill-enhanced/config.json）才能删
• ⚠️ API 写入 [[]] 不解析 → 通过 API 写入时 [[文档名]] 被存为纯文本，不是可点击链接
• ⚠️ 块 ID 必须是 structure 命令输出的 id 字段 → 不能猜，不能从 title 推算
• ⚠️ 思源 SQL parent_id 对 doc-type 父页返回空 → 查子页必须用 node siyuan.js structure <docId> --depth -1
• ⚠️ 目录匹配用章节号前缀（不是文本相似度）→ 避免"需求"等同词错配
• ⚠️ /api/asset/upload 字段名必须是 file[]（不是 assets[]）→ 静默失败无错误
• ⚠️ 处理顺序：先替换图片引用 → 再转 HTML 表（避免表格里的 ![](images/xxx) 被吃）

Verification Checklist（验证清单）

每篇新建文档：
- [ ] 文档标题按 NNN_ 编号
- [ ] 父页文档在末尾含子文档双链索引（用 siyuan://blocks/ 格式）
- [ ] 块 ID 从 structure 命令的 id 字段获取（不是猜的）
- [ ] 没有用 [[]] 写双链（API 写入不解析）

每个父页：
- [ ] 没有独立的 999_README（仅笔记本根目录允许）
- [ ] 索引条目在文档正文末尾（不在单独 README）
- [ ] 编号从 000 开始（子文档在父文档之下）

每条索引：
- [ ] 格式：[NNN_标题](siyuan://blocks/ID) — 一句话简介
- [ ] 块 ID 有效（structure 命令能查到）
- [ ] 简介不超过 30 字

每次批量同步后：
- [ ] 旧父页索引条目已移除
- [ ] 新父页索引条目已添加
- [ ] 父页 updated 时间戳变化（确认 API 写入成功）

v2.0 更新日志（当前版本）

结构性重构（refactor-skill-to-spec 工作流）：

• SKILL.md 大幅精简：27,470 → 13,746 字符（-50%，从超 8-15K 同行上限 1.8 倍 → 同行范围内）
• 2 个大章节拆出到 references/：
• references/siyuan-cli-usage.md（20.6KB，12 个 SiYuan CLI 命令详解）
• references/wechat-article-import.md（3.7KB，微信文章导入完整流程）
• 3 个必需章节补全（validate_skill.py 必检）：
• ## When to Use（何时使用 + Don't use for）
• ## Common Pitfalls（9 个常见陷阱）
• ## Verification Checklist（4 类验证项）

评分提升： 基线 ~60 → 终分（待鲁班评）

行为无变化：
- 所有核心方法论（三层架构、PARA、Zettelkasten、MOC、编号规范）不变
- 所有命令详解移到 references/，但通过 siyuan://blocks/ 双链引用，SKILL.md 内可直接跳转
- 父页索引规范、标签体系、批量同步、微信文章导入等核心功能完全保留

v1.17 更新日志（此前版本）

PARA + Zettelkasten + MOC 融合方法论。

```