agentleFS
levi-qiaolevi-qiao/obsidian-llm-wiki/.claude/skills/ingest/SKILL.md

ingest

Skill9 starsChanged 7 months agoMITView on GitHub

将 raw/ 目录下的原始资料编译到 wiki/ 中。处理完成后,将源文件自动移动到 raw/09-archive/ 归档。支持 `/ingest` (扫描 raw/ 下所有未归档文件) 或 `/ingest <path>` (处理指定文件)。当用户提到"摄取"、"导入"、"收入"资料,或要求将文件加入知识库时,也应该触发此技能。绝对忽略 raw/09-archive/ 目录。

90 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use daily-arxiv, exp-eval and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • LambenthanSkill

    daily-arxiv

    每日从 arXiv 拉取新论文,过滤相关性,auto-ingest 高优先级论文,检测 SOTA 更新

    Also in 5 projects that use this

  • LambenthanSkill

    exp-eval

    实验判决门:Review LLM 独立评判实验结果 → 4 种判决路径 → 自动更新 claims confidence、ideas status、graph edges

    Also in 5 projects that use this

  • phanghonghaoSkill

    poster

    HTML/CSS A4 海报生成。从沙龙/活动 Markdown 文件生成科技风 A4 海报 PDF/PNG。Use when user mentions: poster, 海报, 海报生成, make poster, generate poster, 活动海报, 沙龙海报.

    Also in 5 projects that use this

  • skyllwtSkill

    exp-pilot-eval

    Pilot result evaluation — read pilot results, apply success criteria, update idea page (pilot_result, failure_reason if failed), generate PILOT_VERDICT_REPORT. Called by /ideate Phase 5 after /exp-pilot-run.

    Also in 4 projects that use this

  • skyllwtSkill

    exp-pilot-run

    Pilot experiment execution — read Pilot Spec YAML, write pilot code, run experiment(Confirm with the user before operation and require the applicant to conduct manual inspection), return results. Called by /ideate Phase 5. Does NOT modify wiki pages or judge pass/fail.

    Also in 4 projects that use this

  • +6 more from Lambenthan
  • +1 more from skyllwt

The file

Files
SKILL.md

Ingest 技能

核心目标

你正在维护一个 LLM Wiki(Obsidian 知识库)。raw/ 目录是"待处理收件箱",wiki/ 是"编译输出层"。本技能负责将原始资料编译到知识库中,并自动归档。

目录结构

  • raw/ — 用户自定义的分类结构(可动态调整)
  • raw/09-archive/ — 已处理文件的归档目录,禁止读取(固定,写死)
  • wiki/concepts/ — 概念(框架、方法论、理论)
  • wiki/entities/ — 实体(人物、公司、工具、产品)
  • wiki/sources/ — 资料摘要
  • wiki/syntheses/ — 综合研究报告

触发条件

  1. 用户执行 /ingest — 扫描 raw/ 所有子目录(排除 09-archive/),找出待处理文件
  2. 用户执行 /ingest <path> — 仅处理指定文件
  3. 隐式触发 — 用户说"把这个资料摄入知识库"、"导入这篇文章"时,自动执行

工作流程

前置检查:扫描待处理文件

关键准则:

  1. 使用 Glob 扫描 raw/**/*.{md,pdf,txt}(自动排除 raw/09-archive/)
  2. 读取 raw/.processed.json,识别已处理的文件
  3. 为每个待处理文件创建处理清单,确保不遗漏任何文件
  4. 按文件名字母顺序处理,便于追踪进度

处理清单示例:

📋 待处理文件清单:
- [ ] raw/01-articles/文件A.md (ID: file-a)
- [ ] raw/01-articles/文件B.md (ID: file-b)
- [ ] raw/02-papers/文件C.pdf (ID: file-c)

重要:在开始处理前,向用户展示这个清单,让用户确认要处理的文件列表。


对每个待处理源文件,严格按以下步骤执行:

步骤 1:读取源文件

  • 如果是 .md 文件:使用 Read 工具完整读取内容
  • 如果是 .pdf 文件:使用 Read 工具尝试提取文本。如果无法提取或内容为空,改为记录文件元信息(文件名、页数)
  • 检查点 ✓:确认文件内容已完整读取,记录文件路径和字数

步骤 2:内容分析与 ID 生成

生成稳定 ID:

  • 从文件名提取(去除扩展名和路径)
  • 转换为 kebab-case
  • 示例:raw/01-articles/Attention Is All You Need.md → ID: attention-is-all-you-need
  • 检查点 ✓:确认 ID 已生成,且在 .processed.json 中不存在(避免重复处理)

从源文件中提取:

  • 核心主旨 — 这段资料讲什么(1-2句话)
  • 实体 — 人物、公司、工具、产品等具体名词(列出所有实体)
  • 概念 — 框架、方法论、理论等抽象名词(列出所有概念)
  • 关键标签 — 3-5个细粒度标签(优先复用 index.md 标签云中的现有标签)

如果是非中文内容,则翻译成中文。

检查点 ✓:确认已提取实体列表、概念列表、标签列表

步骤 3:知识网络化(动态 Top-K)

读取总索引:

Read wiki/index.md

智能定位候选页面:

  1. 用步骤 2 提取的实体、概念、标签作为关键词
  2. 在 index.md 中匹配相关页面(不限数量)
  3. 按相关性排序,动态决定更新数量:
    • 简单博客/短文(< 1000 字):2-5 个页面
    • 技术文章/论文(1000-5000 字):5-15 个页面
    • 书籍章节/长文(> 5000 字):15-30 个页面
  4. 如果需要更新超过 20 个页面 → 询问用户是否批量处理

只读取 Top-K 页面的内容(避免全量扫描)

对于步骤 2 提取的每个实体和概念:

目标目录:

  • 实体 → wiki/entities/
  • 概念 → wiki/concepts/

处理逻辑:

  1. 页面不存在 → 按照 CLAUDE.md 的 Frontmatter 规范创建新页面
  2. 页面已存在 → 读取现有内容,增量合并新信息
  3. 发现冲突 → 根据冲突类型处理:
    • 时间性冲突(旧版本 vs 新版本)→ 直接更新,在页面中标注 ## 历史版本
    • 观点性冲突(A 说法 vs B 说法)→ 在页面中新建 ## 知识冲突 区块
    • 复杂冲突(无法判断)→ 在 wiki/_conflicts/ 创建冲突文件,暂停并询问用户

页面模板:

---
type: entity | concept
tags: [标签1, 标签2, 标签3]
source_id: 稳定ID
created: 2026-04-29
updated: 2026-04-29
---

## 定义
[对该实体/概念的定义]

## 关键信息
[从源文件中提取的详细信息]

## 关联连接
- [[摘要-source-slug]] — 来源
- [[RelatedEntity]] — 相关实体

标签使用原则:

  • 优先复用已存在的标签
  • 每个页面 3-5 个标签
  • 标签使用中文或英文,保持一致性

检查点 ✓:确认所有实体和概念页面已创建或更新,记录创建/更新的页面列表

步骤 4:创建来源摘要

在 wiki/sources/ 创建 Markdown 文件:

---
type: source
tags: [标签1, 标签2, 标签3]
source_id: 稳定ID
created: 2026-04-29
updated: 2026-04-29
---

## 核心摘要
[3-5句话的核心总结]

## 关联连接
- [[EntityName]] — 关联实体
- [[ConceptName]] — 关联概念

文件名使用 kebab-case:摘要-{稳定ID}.md

检查点 ✓:确认来源摘要页面已创建

步骤 5:更新索引与日志

更新总索引 wiki/index.md

按照 type(类型)分组,将新增页面添加到对应分类下:

  • 格式:- [[页面名称]] — 一句话描述
  • 更新标签云:重新统计所有标签使用频率

检查点 ✓:确认 index.md 已更新,新增页面已添加到索引

更新操作日志 wiki/log.md(Append-only):

## [YYYY-MM-DD] ingest | 操作简述
- 变更: 新增 [[PageName]] (N个); 更新 [[ExistingPage]] (M个)
- 标签: #标签1 #标签2 #标签3
- 冲突: 无 (或: 时间性冲突已更新; 或: 复杂冲突已生成报告到 _conflicts/)
- 源文件: raw/xx/文件名.md

检查点 ✓:确认 log.md 已追加新记录

步骤 6:更新处理状态并归档源文件

更新 raw/.processed.json:

使用稳定 ID(从文件名提取),记录处理状态:

{
  "文件ID": {
    "original_path": "raw/01-articles/xxx.md",
    "archived_path": "raw/09-archive/xxx.md",
    "processed_at": "2026-04-29T14:30:00Z",
    "pages_created": ["页面1", "页面2"],
    "pages_updated": ["页面3"]
  }
}

时间戳格式:使用 ISO 8601 格式(YYYY-MM-DDTHH:MM:SSZ)

检查点 ✓:确认 .processed.json 已更新

归档源文件:

关键准则:只有在以下所有条件都满足时,才能归档源文件:

  • ✓ sources 页面已创建
  • ✓ 实体/概念页面已创建或更新
  • ✓ index.md 已更新
  • ✓ log.md 已更新
  • ✓ .processed.json 已更新

使用 Bash 工具执行移动操作:

# 确保归档目录存在
mkdir -p raw/09-archive

# 移动文件(使用相对路径)
mv "raw/01-articles/文件名.md" raw/09-archive/

验证归档:

# 验证文件已移动
test -f "raw/09-archive/文件名.md" && echo "归档成功" || echo "归档失败"

检查点 ✓:确认源文件已成功移动到 raw/09-archive/,原位置不再存在该文件

绝对禁止修改源文件内部的文字。

步骤 7:完成提示

对于每个处理完成的文件,输出:

✅ 已完成文件处理:raw/xx/文件名.md
- 稳定ID: xxx
- 新增页面:N 个
- 更新页面:M 个
- 已归档到:raw/09-archive/

所有文件处理完成后,输出总结:

🎉 所有文件摄入完成!

📊 总计:
- 处理文件:X 个
- 新增页面:N 个
- 更新页面:M 个
- 源文件已归档到:raw/09-archive/

📝 下一步:使用 `/sync` 提交到 Git

冲突处理

当发现新旧知识冲突时,根据冲突类型自动处理:

1. 时间性冲突(旧版本 vs 新版本)

特征:同一事实的不同时间点描述,新信息明显更新 处理:直接更新为新版本,在页面中添加 ## 历史版本 区块记录旧信息

2. 观点性冲突(A 说法 vs B 说法)

特征:不同来源对同一问题的不同观点,无法判断对错 处理:在页面中新建 ## 知识冲突 区块,保留两种说法并对比

3. 复杂冲突(无法判断类型)

特征:涉及多个页面、多个维度的矛盾,LLM 无法自动决策 处理:

  1. 在 wiki/_conflicts/ 创建冲突文件:conflict_YYYY-MM-DD_主题.md
  2. 文件内容包含:
    • 冲突描述
    • 涉及的页面和来源
    • 建议的解决方案
    • 决策选项(供用户勾选)
  3. 暂停 ingest 流程,向用户报告冲突位置
  4. 等待用户决策后继续

细节准则

文件处理准则

  1. 批量处理:处理多个文件时,按字母顺序逐个处理,每个文件完成后立即归档
  2. 错误恢复:如果某个文件处理失败,记录错误信息,继续处理下一个文件
  3. 进度追踪:处理多个文件时,实时更新处理清单,标记已完成的文件
  4. 文件名编码:处理中文文件名时,使用相对路径和 cd 命令避免编码问题

页面创建准则

  1. 命名规范:
    • 实体:使用原名(中文或英文),保持 TitleCase
    • 概念:使用中文名称,保持 TitleCase
    • 来源:使用 摘要-{kebab-case-id} 格式
  2. 去重检查:创建页面前,检查是否已存在同名或相似页面
  3. 链接完整性:每个页面必须包含 ## 关联连接 区域,至少链接到来源页面
  4. 标签一致性:优先复用现有标签,避免创建语义相同的新标签

索引更新准则

  1. 分类准确:确保页面添加到正确的分类(Concepts/Entities/Sources/Syntheses)
  2. 描述简洁:每个条目的描述控制在 10-15 字以内
  3. 标签统计:标签云按使用频率降序排列,格式为 #标签 (数量)
  4. 计数准确:每个分类的计数必须与实际页面数量一致

日志记录准则

  1. 时间格式:使用 [YYYY-MM-DD] 格式
  2. 操作类型:明确标注操作类型(ingest/query/lint/sync)
  3. 变更详情:列出所有新增和更新的页面,使用 wikilink 格式
  4. 源文件追溯:记录源文件的原始路径,便于追溯

归档验证准则

  1. 移动前检查:确认所有相关页面和索引都已更新
  2. 移动后验证:使用 ls 或 find 命令验证文件已成功移动
  3. 原位置清理:确认原位置不再存在该文件
  4. 归档记录:在 .processed.json 中记录归档路径和时间

注意事项

  • 绝对不读取 raw/09-archive/ 下的任何文件
  • 所有 wiki 页面必须包含 ## 关联连接 区域,不能产生孤岛页面
  • 使用简体中文编写所有内容
  • 实体命名使用 TitleCase,概念和来源使用 kebab-case
  • 使用 Glob 工具扫描文件,使用 Read 工具读取内容,使用 Write/Edit 工具创建/更新页面
  • 使用 Bash 工具移动文件到归档目录
  • 只读取总索引和相关页面,不要全量扫描
  • 处理多个文件时,必须逐个完成,不能跳过任何文件
  • 每个文件处理完成后,立即归档,不要等到所有文件都处理完才归档

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.