# Obsidian Project Notes

> Use for any project when the user asks to read, summarize, organize, or update local Obsidian project notes, including architecture, development plans, business logic, requirements context, historical decisions, daily/project records, feature explanations, interface notes, or implementation notes. Trigger on “Obsidian 项目资料”, “项目笔记”, “开发计划”, “架构文档”, “业务逻辑文档”, “个人功能开发说明”, “更新到 Obsidian”, or similar requests; always locate the matching project, note name, and section, distinguish current code facts from historical notes, and get explicit second confirmation before writing.

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

---


# Obsidian Project Notes

用于任何项目的本地 Obsidian 项目资料读取和更新。默认中文，优先事实核验，写入前必须确认。

## 核心原则

- 先定位项目，再定位笔记，再定位章节；不要把内容写到“看起来差不多”的文件。
- Obsidian 历史记录不是当前事实；涉及当前行为时必须回到代码、接口、配置、日志或运行态核对。
- 写入前必须二次确认。确认前只能给目标文件、目标章节、拟写内容和影响范围。
- 只改确认过的文件和段落，不顺手重排、润色、压缩其他历史内容。
- 如果用户要求“不要删减内容”，只允许结构化、补充或定点修正，不允许改写成摘要版。

## 项目资料定位

本地项目资料常见根目录：

```text
/Users/caiguoyu/Library/Mobile Documents/iCloud~md~obsidian/Documents/cainiao/项目资料
```

先从当前工作区、用户原话、仓库名、产品名、目录名推断项目关键词，再搜索：

```bash
rg -n "<项目名>|<产品名>|<模块名>|<用户原话关键词>" "<项目资料根目录>"
find "<项目资料根目录>" -maxdepth 8 -type f -name "*<关键词>*.md"
```

常见项目目录示例：

- `项目资料/盛迭/浦东人才`
- `项目资料/盛迭/节能管理`

示例只能作为候选，不能当作默认结论。任何项目都要按当前请求重新定位。

## 触发场景

- 用户要求读取或整理架构、开发计划、业务逻辑、需求背景、历史决策。
- 编码任务需要确认业务语义、页面链路、接口边界、历史方案，而代码本身不足以判断。
- 用户要求把结论、方案、日报、计划、复盘、字段说明、接口说明、计算口径更新到 Obsidian 项目资料。
- 用户只说“更新到 Obsidian”“补到项目资料”“写到个人功能开发说明”等。

如果任务重点是“字段取值方式、计算规则、业务逻辑、接口逻辑”，可同时参考 `$obsidian-project-logic-docs` 的更细流程。

## 读取流程

1. 确认当前工作区和真实子仓，特别是多仓 workspace：

```bash
pwd
find . -maxdepth 2 -name .git -type d -prune
```

2. 在项目资料根目录或已知项目目录内用 `rg --files` 找候选 Markdown 文件。
3. 用用户原话、页面名、接口名、模块名、业务名、字段名做关键词搜索。
4. 只读取最相关的 1 到 3 个文件；命中太多时先列候选并说明选择依据。
5. 读取后明确区分：
   - 当前代码/API/配置事实。
   - Obsidian 里的历史记录。
   - 基于两者做出的推断。

如果笔记和代码不一致，不要直接覆盖结论；先说明差异，再继续查事实源或让用户确认取舍。

## 更新规则

更新前先读取目标上下文：

```bash
sed -n '1,180p' "<目标笔记>"
rg -n "<目标章节>|<关键词>" "<目标笔记>"
```

二次确认必须包含：

- 目标文件绝对路径。
- 目标章节或插入位置。
- 新增、替换或删除的内容摘要。
- 会影响的标题或段落范围。
- 拟写内容预览。
- 事实来源摘要，例如“已对照代码、接口、配置、现有笔记”。

确认前使用这种形式：

```text
我准备写入：
目标文件：...
目标章节：...
改动摘要：...
事实来源：...

预览：
...

你确认后我再写入。
```

只有用户明确回复“确认”“可以”“写入”“更新吧”“ok”等，才修改文件。

确认后使用 `apply_patch` 最小修改，不用 shell 重写整篇笔记。写完后回读目标区域并检查关键字：

```bash
sed -n '<start>,<end>p' "<目标笔记>"
rg -n "<关键标题>|<关键字段>|<关键公式>" "<目标笔记>"
```

## 输出要求

- 永远用中文。
- 面向用户的总结要短，重点说明从哪些笔记和事实源得到了什么结论。
- 写入 Obsidian 的正文保持可长期维护，不写工具过程、memory citation、内部判断过程。
- 最终回复说明已写入哪个文件、更新了哪些内容、如何验证；如果没有写入，说明仍在等用户确认。