# Obsidian Note Style

> Use when creating, restructuring, formatting, linking, illustrating, or maintaining Chinese Obsidian research notes, especially when concepts need prerequisite hierarchy, formula explanation, cross-course connections, evidence layers, WikiLinks, or media cleanup.

- Skill: `w5711112/obsidian-note-style` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add w5711112/obsidian-note-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/w5711112/obsidian-note-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: w5711112 (https://skillmd.com/u/w5711112)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/w5711112/obsidian-note-style

---


# Obsidian Note Style

## 插件级轻量故障协作

> [!important]- **快路径与慢路径**
> - **正常成功路径不写故障库**；普通成功步骤直接继续，不为每次工具调用扫描、查询或记录
> - 当前组件已知脆弱、准备复用历史方案或某路线刚失败时，才运行 `incident_registry.py preflight`：先查项目守卫指定的**本地事故库**，未命中再查**公共事故库只读**；都无匹配就继续
> - 出现**任意异常、非零退出、权限拒绝、结果缺失或验证失败**时，立即运行 `capture-event`；记录后才换路，同一路线再次执行前必须通过 retry guard
> - **最终回答前**扫描真实工具结果；预期 TDD RED、受控探针和用户取消不算产品事故
> - **只有本轮事件发生变化**或历史方案出现新复用结果才查候选；候选非空才加载 `promotion_audit.py`
> - **本 Skill 的效果验证**：Callout 可渲染，WikiLink/标题/块可达，知识只在唯一位置完整解释，媒体被引用且无误删/无用副本
> - 插件任务开始或 Skill 清单变化时读取插件根目录的 `references/skill-collaboration-contract.md`；同一任务内清单与来源哈希未变时不重复枚举

## 触发与权威读取

用户说“**使用我的 Obsidian 语言风格**”“按我的 Obsidian 笔记风格写”或语义等价表达时，**必须调用** `obsidian-note-style`；未调用不得声称输出符合该风格。

凡生成或实质修改简体中文 Obsidian 正文，先由负责事实的专业 Skill 形成完整语义草稿，再按 `专业语义草稿 → global.renhua → Obsidian 格式化` 执行。`global.renhua` 是必需的语言闸门，不是用户额外提出“润色”后才调用的可选步骤。格式化阶段新增实质性正文时，只把新增文字送回 `global.renhua`，通过后再写入；纯标题层级、Callout 标记、WikiLink 和颜色调整不重跑正文。

入口只负责任务分流、证据主链和不可变硬门。按当前分支完整读取一次下列直接参考，不预载无关分支，且参考不得继续路由第二层参考：

| 任务分支 | 唯一直接参考 |
| --- | --- |
| 任何风格化写作 | `references/style-profile.md` |
| 唯一归属、前置链、WikiLink、改名与语义缺链 | `references/knowledge-architecture-and-links.md` |
| 标题、段落、强调、代码、术语、模板与证据语气 | `references/formatting-and-evidence-contract.md` |
| 出现正式公式；复杂式进入 12 步长版 | `references/formula-explanation-patterns.md` |
| 发现或使用跨课程概念桥 | `references/cross-course-concept-bridges.md` |
| 新增/扩充正式知识点、配图、换图或清理媒体 | `references/visual-media-lifecycle.md` |
| 续写、重整、批量修改、恢复与交付 | `references/workflow-and-acceptance.md` |

本文件与直接参考共同构成权威合同；架构清单、authority map、测试与报告只是记录，不能替代原要求。

## 单一证据主链

在同一证据边界内，每个对象只生成并验证一次；后续步骤复用对象 ID 和来源哈希。只有目标字节、Vault 图谱、用户确认、媒体集合或风险等级实质变化时刷新对应对象，不能进入新章节就重复跑全库验证。

| 对象 | 生成内容 | 唯一消费门 |
| --- | --- | --- |
| `NOTE_BASELINE` | Vault 根、目标字节/编码/换行、标题/块/链接/媒体基线、恢复点 | 写入与最终差异 |
| `KNOWLEDGE_PLACEMENT` | 文件预算、全库匹配、唯一主笔记、前置链、写入位置 | 新建/合并/归属 |
| `LINK_GRAPH` | 修改前后入链、出链、改名影响面、失效和语义缺链 | 链接写回与归零 |
| `VISUAL_DECISION` | 每个知识点 0/1、证据、draw-style 交接、实际宽度与媒体结果 | 配图/替换/清理 |
| `NOTE_ACCEPTANCE` | 内容、公式、证据、链接、视觉、恢复、架构与清理结论 | 交付 |

## 不可变内容硬门

### 风格、术语与证据层

- **理解优先于紧凑**；紧凑只能删空泛引言、重复总结和多余空行，不能为了紧凑删除必要的认知台阶
- 完整知识块顺序固定为：**是什么 → 为什么 → 怎么做 → 适用条件/局限 → 延伸链接**
- 术语首次出现回答 5 项：是什么、为何出现、怎么使用、边界、去哪里深入
- 控制、感知和机器人论文的主链模块必须另写清：**输入来源 → 输入内容 → 处理顺序 → 输出的物理意义 → 下游模块 → 训练阶段与部署阶段的差异 → 条件与边界**。不能用“射线距离”“速度目标”“PPO 选速度”“几何投影”等压缩词组代替解释
- 学术主张固定分成“**论文报告**”“**可以推断**”“**尚不能证明**”；量化算力、延迟、显存、功耗、频率和实验数字必须有全文/官方证据。不把推荐写成论文事实，未知不写 0，研究方向分析保留两位小数、量化可行性、最小实验与明确缺口

**英文全称—简称的首字母映射**只加粗真实构成字母：**H**igh-**O**rder **C**ontrol **B**arrier **F**unction（**HOCBF**）、**P**roximal **P**olicy **O**ptimization（**PPO**）、**E**uclidean **S**igned **D**istance **F**ield（**ESDF**）。必须核对公认全称，**不得为了视觉效果篡改全称**；同页定义后，后续只写加粗简称。

### 唯一归属、链接与恢复

写入前从当前路径向上定位 `.obsidian`，建全 Vault 索引。0 个同名先查文件预算，1 个即唯一主笔记，多个先合并独有可靠内容；不得把项目目录当 Vault，也不得为一术语建一文件。

**知识前置链**按“基础概念 → 扩展概念 → 论文特定用法”组织；知识点总标题只写标准名称，不把通俗解释写进知识点总标题。第一层使用“第一层｜直觉理解 | 一句话本质”，批准后的跨课程概念桥放在正文层级内，不改写标准标题。

**当前无人机论文项目的知识文件冻结**：知识枢纽冻结为两个现有文件——`安全控制与<YOUR_METHOD>.md`、`路径规划与环境表示.md`。**作者履历不进入知识枢纽**，不能新增第三个论文枢纽。

链接默认带别名并精确到标题/块，规范形式为 `[[笔记名#标题\|简短别名]]`；表格内若出现未转义的别名分隔符，必须改为 `\|`。任何改名生成同一份 `LINK_GRAPH`，同时检查**入链**、**出链**与**改名影响面**。最终全 Vault 的 `missing-file`、`missing-heading`、`missing-block`、`ambiguous-file`、`relocatable-file` 五类均为 0，并把 `ambiguous-file` 作为歧义引用处理。链接治理同时覆盖 Markdown 与 Canvas。失效块必须在真实承载位置修复，**不得创建空白占位笔记**/空图/虚构标题来归零。

链接检查器只能发现失效链接，不能发现新增技术名词有**已有唯一知识位置**却**仍以纯文本出现**。新增/扩充正文必须做语义缺链审计，同段同概念只补一个入口。

链接治理备份默认放 **Vault 外**；只能放 Vault 内时先证明它不在扫描范围。检查器返回非零先解析 JSON，不等同脚本崩溃。PowerShell 双引号会处理 Markdown 反引号；写回保持 BOM 与 LF/CRLF。依赖缺失先确认并补齐；中断恢复先查 `.orig`、`.rej`、`NUL`、补丁与隐藏备份，不重放已成功修改。

### 公式与跨课程概念桥

公式先判断**允许短版**或**强制长版**；复杂公式的解释可以明显长于直觉层。长版采用 12 步**公式引导式推导链**：具体问题 → 核心句 → 人话公式 → 具体例子 → 一次只引入一个新概念 → 每步回答“**这一步意味着什么**”并做逐符号人话翻译 → 误解纠正 → **重新合回完整公式** → 性质 → 系统作用/条件/边界 → 记忆收束 → 符号表。完整说明同时覆盖例子、性质来源、误解和边界。适合时**先给具体例子，再推广到一般形式**；符号表放在引导式正文之后，第一遍讲解不得用一张大符号表代替。

**误解纠正后，下一语义阶段必须是重新合回完整公式**；不得在二者之间插入性质、系统作用、边界、跨课程公式桥或记忆句。

B-spline 首次出现 $k$ 附近必须直接写清：`$k$ 是当前基函数的次数（degree），也是当前递推层`；`$k$ 不是控制点索引，也不是 knot 索引`；`$B_{t,3}$ 中的 $3$ 是 $k=3$ 的特例`，不得推迟到符号速查表。

执行**跨课程概念桥审计**时，桥只在用户主动提出并确认或此前逐条批准后落盘。Agent 自主提出的候选必须展示共同结构、逐项映射、具体区别、拟解决疑问与确认问题，并且必须先经用户确认；**未确认不得写入**笔记、图例、公式卡或 WikiLink。普通同领域计算例子不属于跨课程桥，无需暂停；未确认时只暂停桥本身，不阻塞独立正文。

### 视觉、媒体与零质量衰减

执行**新增或扩充知识点本地门禁**：**每个本轮新增或扩充的正式知识点**立即执行本地门，每个知识点独立判断为 `0` 或 `1` 张；多面板仍是一张，**不限制整篇笔记或一次论文处理的总图数**。算法、控制、空间表示、曲线、轨迹、网络和机制比较等可视化知识点在没有合格现图时默认配 `1` 张；组织性标题不属于知识点。

论文级审计**不能豁免本地门禁**。论文正文与知识链接完成后，本 Skill**每篇论文只触发一次**覆盖 Vault 全部正式知识点的视觉审计：一次结构扫描，已有合格图快速跳过，只深入无图候选；不在论文阅读、逐段写入或单张图片完成时重复触发。命令为 `audit_obsidian_visual_coverage.py`。

缺图时调用 `draw-style`，将知识点语义要求、原文证据和输出约束一并交接；它独占**八项硬质量门槛**。最终图统一放入 `AI绘图存放位置`。本 Skill 在**实际 Obsidian 宽度下一次完成八项检查**，不做独立联系表复核；全部引用写入后只运行一次媒体审计，固定使用 `audit_obsidian_media.py`。图后用 `[!info]- **读图与图例**`，按需覆盖**怎么读、名词、箭头/编码、来源、边界**且不设固定条数；核心原理、公式与成立边界仍在正文展开。

已有图先判断质量：**合格现图不修改**。版面顺序固定为图放在第一层正文之后、第二层紧跟图例；同一结论只保留一处，解释闭环后不重复。

第二层公式写**完整的必要计算链**；公式解释可以比直觉层更长，**不在每个短句之间插空行**。不稳定的等宽公式教学示意改成紧凑表格或单行变化链。

旧图先生成独立候选。只有新图全部通过八门且关键维度均不弱于旧图时，按“**先生成并验收全部新图** → **再更新正式引用** → 审计后**最后删除旧格式**”执行；任一失败保留整批旧引用。媒体删除默认只生成 dry-run，删除还需白名单路径、反链、SHA-256、恢复源与删除后复扫。

### 格式与 Windows 固定接口

无序列表项的最后一个可见内容字符通常不保留任何收尾标点：默认删除 `。`、`．`、`.`、`；`、`;`、`：`、`:`、`，`、`,`、`、`。问号、感叹号与有意义省略号保留；代码块、Frontmatter、原始引用、URL 和公式不机械改；规则只在 canonical 文件中维护。

Windows 多步写入前设 `$ErrorActionPreference = 'Stop'`。PowerShell 5 的 `New-Item -LiteralPath` 无效，白名单精确目录用 `[System.IO.Directory]::CreateDirectory`；部署用 `Copy-Item -LiteralPath`，源文件与目标文件的 SHA-256 相同才成功。中文验证统一 `python -X utf8 <quick_validate.py>`；`UnicodeDecodeError` 指向 GBK 时固定 UTF-8，不能改写成 ANSI。零上下文补丁才用 `--unidiff-zero` 且先检查。`view_image` 受 split roots 拒绝时不循环，可复制预览到批准目录并用 `node_repl`/确定性渲染复核。

## 执行与交付

先完成专业语义草稿和 `global.renhua` 语言闸门，再按工作流参考生成 `NOTE_BASELINE` → `KNOWLEDGE_PLACEMENT` → `LINK_GRAPH` → `VISUAL_DECISION` → `NOTE_ACCEPTANCE`。只刷新变化对象；同一风险不得在正文、图例、链接、媒体和最终交付五处各验证一次。

交付必须确认：知识唯一归属；前置链完整；公式可复述；概念桥授权明确；5 类链接问题归零；每个新增知识点已有 0/1 决策；新图八门与媒体审计通过；论文报告/推断/未证明分层；无新增标签、预算外文件、重复标题/块、孤儿媒体、临时备份或测试残留。

本 Skill 负责知识归属、中文结构、Callout、WikiLink、视觉覆盖和媒体集成；`draw-style` 负责绘图质量，`read-paper-analysis-highlight` 负责全文证据/PDF 批注，`zotero-obsidian-paper-import` 负责 DOI/PDF/Zotero，`global.collect-bug-update-accelerate` 负责执行故障。

## canonical、总体系说明与完整指南

本文件及其强制 reference 是本 Skill 的唯一权威来源。Vault 的 `Skill完整指南/Skill与Plugin的总体系说明.md` 只说明用途、输入输出、协作和边界；`Skill完整指南/research/obsidian-note-style-完整指南.md` 是本文件与 references 的只读可读镜像，集中保存可执行规则。职责或依赖变化时，只更新总体系说明中的对应段；规则或 reference 变化时，只刷新本 Skill 的完整指南。两类派生说明都不得反向覆盖 canonical。架构层级或直接参考集合只有在用户明确批准、架构版本提升并通过迁移测试后才可改变；普通内容增删不得顺带改变架构。