lkhfrgc/scholar-llm-wiki / .dsh/skills/lint
lint
Verified知识库全局健康度检查。扫描 wiki/ 目录,按 AGENTS.md 规范执行十项检查:索引一致性、死链与孤儿页面、文中提及但缺少页面的概念、过时论断、核心问题覆盖、空白领域建议、概念分层一致性、Canvas 同步、Tag 受控词表合规、Team 受控词表合规。支持 `/lint`、`/scan`、`/health` 触发。当用户说「检查知识库」「跑一下 lint」「wiki 健康状况怎么样」「帮我检查一下 wiki」时触发。默认仅读,修复需用户确认。
lint 技能:知识图谱健康巡检
前置:初始化
若 .dsh/wiki.config.json 或根目录的 index.md 不存在,说明骨架尚未生成,先跑一次 python .dsh/scripts/setup_wiki.py;没有 wiki 内容时巡检会全部落空,此时直接告知用户即可。
路径以配置为准
.dsh/wiki.config.json 是本仓唯一配置源,目录名、文件名、画布名都从它读:
python .dsh/scripts/wiki_env.py --paths # 常用目录一览(wiki / raw / inbox / index / log / tags_doc / vocab)
python .dsh/scripts/wiki_env.py --json # 完整配置 + 解析结果
下文出现的
wiki/、index.md、log.md、TAGS.md、.dsh/tag-vocab.json等均为默认值;若配置改过,以配置为准,拿不准先跑上面的自省命令。
核心目标
将软件工程中的"静态分析"引入知识管理。定期运行此 skill,按照 AGENTS.md 定义的十项检查,找出知识库在长期演进中积累的问题:死链、孤岛、未同步索引、缺失页面、过时论断、研究空白,以及概念分层、Canvas 地图、tag 词表与团队词表的漂移。
触发条件
- 用户输入
/lint - 用户询问"知识库健康状况如何"、"帮我检查一下 wiki"、"跑一下 lint"
- 用户要求"检查知识库状态"
知识库范围
扫描范围(按检查项不同):
| 范围 | 用途 |
|---|---|
wiki/ 五个子目录 | 检查 1 的"未注册页面"、检查 2 的孤儿判定、检查 4/5 的页面级统计 |
根目录 *.md(index.md、log.md、AGENTS.md) | 检查 2 的死链必须覆盖它们——只扫 wiki/ 会漏掉这些文件里的链接 |
全库 basename 索引(含 wiki 之外的笔记目录,默认 我的研究/,见配置 dirs.my_research;以及 .canvas/.pdf 附件) | 判定链接目标是否存在(Obsidian 按 basename 解析,见检查 1) |
raw/ 不参与 lint——它是不可变的原始资料层。
巡检流水线(十项检查,与 AGENTS.md 对齐)
检查 1:索引一致性
目标:确保 index.md 中注册的页面与实际文件一一对应。
方法:
- 读取
index.md,提取所有[[页面名称]]格式的注册条目,按分类(Papers / Concepts / Connections / Questions / Syntheses)归类 - 用
glob扫描wiki/下所有.md文件(index.md和log.md位于根目录,不会被 glob 匹配到) - 交叉比对,输出两类问题:
| 问题 | 含义 |
|---|---|
| 幽灵条目 | index.md 中注册了 [[X]],但全库任何位置都没有 X.md |
| 未注册页面 | wiki/ 下的 X.md 存在,但 index.md 中没有任何分类下列出它 |
⚠️ 判定链接是否存在时,必须按 Obsidian 的规则:basename 全局唯一。[[X]] 指向的是任意目录下名为 X.md 的文件,不限于 wiki/。因此:
- 存在于 wiki 之外的笔记目录(如默认的
我的研究/)里的笔记是合法的链接目标,不得报为幽灵条目- 实例:
[[某篇调研]]指向我的研究/调研/某篇调研.md,是合法条目
- 实例:
- 链接目标也可能不是
.md:Obsidian 维基链接能指向.canvas、.pdf等附件- 实例:
[[某张画布.canvas]]指向我的研究/某张画布.canvas,合法
- 实例:
- 只扫
wiki/会把上述两类全部误报。检查前先建立全库 basename 索引(含根目录、wiki 之外的笔记目录、附件)
必须排除的三类"假死链",否则报告会被噪音淹没:
- 文档占位符:
AGENTS.md的模板示例里的[[页面名称]]、[[EntityName]]、[[ConceptName]]、[[摘要-source-slug]]等是格式说明,不是真实链接。行内代码`[[概念名称]]`内的同理。 log.md的历史引用:日志是 append-only 的历史记录,其中的[[已删页面]]、[[旧版调研]]反映的是当时的真实操作。不得据此修改日志,只作为"历史上存在过但已删除"的信息记录。- 路径型引用:
[[raw/papers/xxx.pdf]]是文件引用(见检查 2 说明),不参与存在性判定。
同时校验 frontmatter 与必需小节(index.md 对不上只是表象,字段缺失才是根因):
- 每个页面的 frontmatter 必须含
title、type、created、updated、tags;sources除纯综述页外应存在tags的取值是否合法由**检查 9(Tag 规范)**负责,此处只看字段是否存在- 论文页(
type: paper)还必须含team字段(来源团队);其取值是否合法由**检查 10(Team 规范)**负责,此处只看字段是否存在
type必须与所在目录匹配:papers/→paper、concepts/→concept、connections/→connection、questions/→question、syntheses/→synthesis(目录↔type 的对应表以配置的wiki_types段为准)- 每个页面必须有
## 关联连接小节——这是 AGENTS.md 的硬性要求。判定时注意三点:- 用包含匹配而非精确匹配:
## 五、关联连接这类带编号的标题算合规,### 关联连接(级别写成三级)算违规但易修,单独列为一类 ## 涉及论文/## 相关论文/## 涉及概念之类的分节不能替代它(有则可以共存,缺了它就判不通过)- 小节应位于页面末尾;若出现在开头,Obsidian 大纲与阅读顺序都不对,也列入待修
- 用包含匹配而非精确匹配:
- 顺带检查文件编码:frontmatter 必须能被解析,即文件不得带 UTF-8 BOM(BOM 会让首行变成
\uFEFF---,整个页面被判为"无 frontmatter")
经验:
## 关联连接是最常被漏掉的必需小节,尤其 connection / question / synthesis 三类页面;updated/sources字段则在 question 页面上最容易被漏掉。这两类问题如果检查项不覆盖,就会长期无人发现——所以它们必须进巡检清单。
检查 2:死链与孤儿页面
目标:确保双向链接网络的健康。
方法:
-
用
grep扫描所有.md文件,提取所有[[...]]格式的双链⚠️ 本宿主(DSH)的检索工具是
grep,不是search_content/search_files。用错名字会让检查 2、3 直接失效。 -
过滤掉指向 raw/ 的链接、指向自身的链接
-
对每个目标,检查对应
.md文件是否存在 -
死链:链接指向不存在的页面
-
孤儿页面要分两级报告,二者修复动作不同:
- 真孤岛:既没有任何页面引用,也没有在 index.md 注册 → 严重,必须处理
- 仅索引可达:有 index.md 注册,但零个页面用
[[...]]引用它 → 轻度,它实际上没进入知识网络
-
命名不一致单列:若某死链目标是不存在的英文 slug,而
wiki/下存在语义对应的中文文件(反之亦然),归入「命名不一致」而非「缺失页面」 -
扫描范围必须包含根目录文件:
index.md、log.md、AGENTS.md也含有[[...]]双链。只扫wiki/会漏掉这些链接里的死链——它们是根目录文件,不算 wiki 页面,因此判断存在性时要同时看根目录和wiki/各子目录。
⚠️ 解析双链的三个坑(不处理会产生大量假阳性):
- 表格内的别名链接用转义竖线:Obsidian 在表格里写
[[目标\|别名]]。提取目标时必须在第一个|或\|处截断,否则目标名会带上\|别名,被误报成死链。 - 标题锚点:
[[页面#小节]]的目标是页面,#之后要丢掉。 - 英文 slug 与中文文件名的命名漂移:若链接目标是不存在的英文 slug,先在
wiki/里搜同义的中文文件名(例如[[sparse-coding-attention]]对应稀疏编码与注意力.md)。这类应归类为「命名不一致」,而不是「缺失页面」——两者的修复动作完全不同(前者是改链接或建别名,后者才需要新建页面)。 - 指向
raw/或含/的路径引用不算死链——它们是文件引用,不是 wiki 页面引用。
检查 3:文中提及但缺少独立页面的概念
目标:发现那些在正文中被频繁讨论、但尚未拥有独立 concept 页面的概念。
方法:
- 收集所有死链中有意义的非拼写错误目标(如
[[反向传播]]大概率是缺页面,而[[asdf]]是笔误) - 用
grep扫描所有页面的## 关联连接区域,提取以纯文本形式出现但未用[[]]包裹的概念名——这些是"应该链接但没链接"的信号 - 合并去重,输出"建议创建的概念页面"清单,按被提及次数排序
输出示例:
⚠️ 以下概念在 wiki 中被多次引用但缺少独立页面:
- "稀疏编码" — 在 3 个页面的关联连接中被提及
- "自由能原理" — 在 2 个页面中出现死链
检查 4:过时论断检测
目标:找出可能被新资料推翻的陈旧说法。
方法:
- 扫描所有 paper 页面的 frontmatter,提取
year字段 - 扫描所有 concept 页面的 frontmatter,提取
updated字段和sources字段 - 对每个 concept 页面,检查其引用的 sources 中最新 paper 的年份
- 标记以下情况:
- concept 页面的
updated日期距今超过 6 个月,且其引用的所有 paper 均为 2 年以前 - 同一概念存在新旧两篇 paper,旧 paper 的结论与新 paper 冲突,但 concept 页面未记录此冲突
- concept 页面的
局限性说明:此项检查无法完全自动化判断"论断是否真的过时"——它只能标记可能需要复核的页面。最终判断由用户做出。
检查 5:核心研究问题覆盖分析
目标:找出覆盖薄弱的核心研究问题。
方法:
- 搜索
wiki/下是否有定义核心研究问题的文件(如wiki/questions/下的页面,或某个专门的配置文件) - 扫描所有 wiki 页面的 frontmatter
questions字段,统计每个问题编号被多少页面标注 - 输出覆盖矩阵:
| 核心问题 | 标注页面数 | 状态 |
|---|---|---|
| 1: [问题描述] | 12 | ✅ 充分 |
| 2: [问题描述] | 3 | ⚠️ 薄弱 |
| 3: [问题描述] | 0 | ❌ 空白 |
如果 wiki/ 中尚未定义核心研究问题,报告此项为"跳过"并建议用户先定义。
检查 6:空白领域建议
目标:基于以上所有检查的综合结论,给出可操作的建议。
方法:
- 汇总检查 3(缺失概念)、检查 4(可能过时)、检查 5(覆盖薄弱问题)
- 针对每个薄弱领域,建议具体的论文或主题方向
- 检查收件箱(默认
raw/research/)中是否有尚未摄入的资料恰好能填补这些空白 → 一并提醒
检查 7:概念分层一致性(母概念 / 子概念)
目标:保证「母页 + 子页」两级结构在 tag、正文链接、索引三处一致——分层只有在三处同时成立时才会在 Obsidian 关系图谱中可见(核心图谱的边只来自正文 [[链接]],frontmatter 纯文本不进图谱)。
方法(只读扫描):
- 取
tags含母概念的页面为母页集合、含子概念的为子页集合 - 对每个母页:
- 必须存在
## 子概念段,否则报「有 tag 无子概念段」 ## 子概念段中,每条 bullet—之前的链接才是子页声明(描述文字里的链接不计入,它们属## 关联连接范畴);同一条 bullet 可含多个声明(以、分隔)。每个声明链接的目标必须存在,且其文首定位行应含> **母概念**:…[[本页]]…,否则报「单向声明」。注意:不要整行抓取所有链接——描述文字中的链接会造成假阳性- 不得把自己列为子页(自环)
- 必须存在
- 对每个子页:文首定位行中的每个母页必须存在,且该母页的
## 子概念段必须列出本页,否则报「孤儿声明」 - 环检测:若 A 的
## 子概念含 B 且 B 的含 A → 报环(多父 DAG 本身不是问题,环才是) - 索引一致性:子页应作为缩进条目出现在
index.md的某个母页下(或它本身也是母页)
输出:黄灯项「分层不一致 N 个」,逐条给出页面与缺失项;总览中追加「母页 N / 子页 N」。
检查 8:Canvas 同步(族地图 / 总图)
目标:保证「族结构」与画布一致——族变了却没重生成画布时,画布会展示陈旧结构(错误分组、缺失子页、失效链接)。
方法:
- 运行
python .dsh/scripts/gen_canvas.py --check(只需标准库,用 harness 自带解释器),退出码 0 = 全部新鲜 - 退出码非 0 时报告清单:
MISSING(画布缺失)与STALE(结构指纹失配,附旧→新指纹),并提示运行同脚本(不带--check)重新生成 - 附加只读校验:画布 JSON 中不得出现
"type": "file"节点(必须全部为text卡片 +[[双链]]);每个tags含母概念的页面都应有对应的族图画布(文件名见配置canvas.family_prefix) - 触发条件提醒:新增/删除母页或子页、改动母页
## 子概念段、改动子页文首定位行(多父)、母页改名 —— 任何一项都要求重新生成
输出:红灯项「画布过期 N 张 / 缺失 N 张」(若仓库尚无画布则记为"跳过")。
检查 9:Tag 规范(受控词表)
目标:保证 tags 字段始终落在 .dsh/tag-vocab.json(canonical 段)定义的封闭词表内——这是防止 tag 膨胀的唯一机制。经验:不设封闭词表时,tag 数量会随页数线性膨胀,每个页面都造几个新词,最终彻底失去检索价值。
方法(优先用脚本,不要靠肉眼):
- 运行
python .dsh/scripts/tag_audit.py(只需标准库,用 harness 自带解释器),退出码 0 = 全部合规。 - 退出码非 0 时,逐条报告:
- 未登记 tag(红灯):出现在 frontmatter 但不在
canonical中。可用tag_audit.py --unregistered只看这一类。修复方式见下。 - 硬性违规(红灯):单页主题 tag > 8 个,或 0 个主题 tag。
- 未登记 tag(红灯):出现在 frontmatter 但不在
- 只读补充校验(脚本已覆盖大部分,异常时人工复核):
- 角色 tag
母概念/子概念是否仍位于tags首位(gen_canvas.py依赖) - 是否仍存在 YAML 块序列写法的
tags:(应统一为单行内联) - 分面软上限:domain 2 / task 4 / modality 4 / method 6 / challenge 4 / data 2 / meta 2
- 推荐区间 3–5 个/页(仅提示,不报错)
- 角色 tag
- 修复路径(二选一,不要直接改页面 tag):
- 该 tag 其实是已有词条的近义/大小写/单复数变体 → 在
.dsh/tag-vocab.json的map里 登记「来源词 → 规范词」,然后tag_apply.py(先预演,再--apply)。 - 该 tag 确有独立检索价值(≥3 个页面用得上,且能归入某个分面)→ 在
canonical增加词条 +map登记来源(TAGS.md只写规则、不列词条,无需刷新)。 ⚡ 冷启动例外:若canonical为空(出厂状态)或该分面为空,免于 3 页门槛—— 首次摄入本来就不可能攒够页面。此时应把这些 tag 报成「待登记」而非「违规」, 并提示登记进词表即可,不要建议删除页面上的 tag。 - 两者都不成立 → 删掉这个 tag(信息写进正文即可)。
- 该 tag 其实是已有词条的近义/大小写/单复数变体 → 在
- 收尾:修改词表后按 AGENTS.md「Tag 规范 → 改动流程」五步执行
(改
canonical/map→tag_vocab.py --check→--emit-doc→tag_apply.py --apply→tag_audit.py), 并确认tag_vocab.py --check与tag_audit.py均返回 0。
输出:红灯项「未登记 tag N 个 / 硬违规 N 个」;黄灯项「超软上限 N 处」;
总览中追加「规范 tag 使用数 N / 词表容量(从 .dsh/tag-vocab.json 统计)」与 tag 数分布。
检查 10:Team 规范(论文来源团队)
目标:保证每篇论文页的 team 字段都落在 .dsh/team-vocab.json 定义的团队词表内,
且同一个团队只有一种规范写法(没有别名分叉)。
方法(优先用脚本,不要靠肉眼):
- 运行
python .dsh/scripts/team_audit.py,退出码 0 = 合规。它覆盖五条规则:- R1 每个论文页必须有非空
team; - R2 每个取值必须是词表规范名——写了别名会直接给出「应写规范名」;未登记则报违规;
- R3 不得保留旧的
affiliations字段(已被team取代); - R4 归一化后同名的疑似重复(机构 ↔ 其实验室的父子关系属正常,不算重复);
- R5 frontmatter 结构:
team是合法单行内联列表、必需字段齐全、无孤立块序列。
- R1 每个论文页必须有非空
- 脚本另给三类提示(不计入错误):
team: ["待确认"]占位页、 词表为空却已有页面写了 team、词表中尚未被引用的团队。 - ⚡ 冷启动例外:出厂时词表为空。此时页面上的团队名应报成「待登记」而非「违规」,
并提示登记进
.dsh/team-vocab.json的teams/aliases即可(团队是事实字段, 没有 tag 那样的页数门槛),不要建议删除页面上的 team。 - 修复路径:
- 写法差异(缩写 / 中英文 /
The、of之类)→ 用python .dsh/scripts/team_vocab.py --resolve "<写法>"查规范名; 改页面,或把该写法登记进aliases; - 新团队 → 按 AGENTS.md「Team 规范 → 改动流程」五步登记
(
teams补base/type/note→--check→--emit-doc→team_apply.py→team_audit.py); - 团队与原文署名不符 → 回源 PDF 首页 / 脚注核对后再改,不要凭印象;
待确认页 → 双盲审稿或 PDF 缺失,在报告里单列,不要臆造。
- 写法差异(缩写 / 中英文 /
- 收尾:确认
team_vocab.py --check与team_audit.py均返回 0。
输出:红灯项「缺 team N 页 / 未登记团队 N 个 / 残留 affiliations N 页」;
黄灯项「待确认 N 页」;总览中追加「团队词表容量 N / 被引用 N」。
报告输出规范
扫描完成后,输出结构化报告:
## 🩺 知识库健康体检报告 — YYYY-MM-DD
### 📊 总览
- 页面总数:N(papers: N, concepts: N, connections: N, questions: N, syntheses: N)
- 双链总数:N
- 整体评分:[健康 / 需要注意 / 需要修复]
### ❌ 红灯(需立即处理)
- **死链 N 个**:[来源页面] → [[不存在的目标]]
- **幽灵条目 N 个**:index.md 注册了但文件不存在
- **真孤岛 N 个**:无引用且未注册的页面
### ⚠️ 黄灯(建议处理)
- **缺 `## 关联连接` 的页面 N 个**:[列表] — 违反 AGENTS.md 硬性要求
- **frontmatter 字段不全 N 个**:[页面] 缺 [字段]
- **仅索引可达 N 个**:[列表] — 已注册但无任何页面引用
- **未注册页面 N 个**:[列表]
- **命名不一致 N 个**:[英文 slug] ↔ [中文文件名]
- **未解决的知识冲突 N 个**:[页面名称]
### 🔵 提示(优化建议)
- **建议创建的概念页面 N 个**:[列表] — 在多个页面中被提及但无独立页面
- **可能需要复核的页面 N 个**:[列表] — 长期未更新且引用资料较旧
### 📈 核心问题覆盖
[覆盖矩阵表]
### 🛠️ 建议的下一步行动
1. [最优先行动]
2. [次优先行动]
3. [可选优化]
是否需要我执行自动修复?(仅限:更新 index.md、修复明显拼写错误的死链)
硬约束
-
仅读扫描:生成报告前,绝对禁止修改、删除、重命名任何文件
-
手动确认:报告后等待用户选择要执行哪些修复,不可自动执行
-
可修复项(需用户确认):
- 更新
index.md添加未注册页面 / 移除幽灵条目 - 修复明确由拼写错误导致的死链
- 更新
-
不可自动修复项(仅报告):
- 创建新页面
- 判断论断是否过时
- 修改页面内容
-
操作日志:用户确认修复后,在
log.md顶部追加:## [YYYY-MM-DD] lint | 健康检查 - **结果**: 修复 N 处死链,修复 N 处索引,发现 N 个孤儿页面 [[PageA]]⚠️ 写入前检查格式:操作类型只允许
ingest / query / lint;新条目必须独占一行并以空行结尾——经验:上一条记录最后一行漏了换行时,两条记录会粘连在同一行。追加后回读一眼确认新条目开头是## [而不是接在旧内容后面。
关联连接
- [[AGENTS.md]] — Wiki 架构总规范
- [[index]] — 索引一致性检查的基准
- [[log]] — 修复日志记录
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |