wiki-update

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wiki Update — Sync Any Project to Your Wiki

知识库更新 — 将任意项目同步到你的Wiki

You are distilling knowledge from the current project into the user's Obsidian wiki. This skill works from any project directory, not just the obsidian-wiki repo.

你正在将当前项目的知识提炼存入用户的Obsidian知识库。该技能可在任意项目目录下使用，不局限于obsidian-wiki代码库。

Before You Start

开始之前

Read
```
~/.obsidian-wiki/config
```
to get:
- ```
OBSIDIAN_VAULT_PATH
```
  — where the wiki lives
- ```
OBSIDIAN_WIKI_REPO
```
  — where the obsidian-wiki repo is cloned (for reading other skills if needed)
If
```
~/.obsidian-wiki/config
```
doesn't exist, tell the user to run
```
bash setup.sh
```
from their obsidian-wiki repo first.
Read
```
$OBSIDIAN_VAULT_PATH/.manifest.json
```
to check if this project has been synced before.
Read
```
$OBSIDIAN_VAULT_PATH/index.md
```
to know what the wiki already contains.

读取
```
~/.obsidian-wiki/config
```
获取以下配置：
- ```
OBSIDIAN_VAULT_PATH
```
  — 知识库的存储路径
- ```
OBSIDIAN_WIKI_REPO
```
  — obsidian-wiki代码库的克隆地址（如需读取其他技能时使用）
如果
```
~/.obsidian-wiki/config
```
不存在，告知用户需要先在obsidian-wiki代码库下执行
```
bash setup.sh
```
。
读取
```
$OBSIDIAN_VAULT_PATH/.manifest.json
```
，检查该项目之前是否有过同步记录。
读取
```
$OBSIDIAN_VAULT_PATH/index.md
```
，了解知识库中已有的内容。

Step 1: Understand the Project

步骤1：了解项目

Figure out what this project is by scanning the current working directory:

```
README.md
```
, docs/, any markdown files
Source structure (frameworks, languages, key abstractions)

package.json

pyproject.toml

go.mod

Cargo.toml

or whatever defines the project

Git log (focus on commit messages that signal decisions, not "fix typo" stuff)
Claude memory files if they exist (
```
.claude/
```
in the project)

Derive a clean project name from the directory name.

通过扫描当前工作目录，梳理项目的基本信息：

```
README.md
```
、docs/目录、任意markdown文件
源码结构（框架、编程语言、核心抽象）

package.json

、

pyproject.toml

、

go.mod

、

Cargo.toml

或其他项目定义文件

Git日志（重点关注体现决策的提交信息，忽略「修正拼写错误」这类内容）
若存在Claude记忆文件（项目下的
```
.claude/
```
目录）也可参考

从目录名称衍生出一个简洁的项目名。

Step 2: Compute the Delta

步骤2：计算变更内容

Check

.manifest.json

for this project:

First time? Full scan. Everything is new.
Synced before? Look at
```
last_commit_synced
```
. Only consider what changed since then. Use
```
git log <last_commit>..HEAD --oneline
```
to see what's new.

If nothing meaningful changed since last sync, tell the user and stop.

在

.manifest.json

中查找该项目的同步记录：

首次同步？ 全量扫描项目，所有内容都是新增内容。
之前同步过？ 查看
```
last_commit_synced
```
字段，仅处理该提交之后的变更。使用
```
git log <last_commit>..HEAD --oneline
```
查看新增内容。

如果上次同步之后没有产生有意义的变更，告知用户后终止流程。

Step 3: Decide What to Distill

步骤3：确定需要提炼的内容

This is the core question from Karpathy's pattern: what would you want to know about this project if you came back in 3 months with zero context?

Worth distilling:

Architecture decisions and why they were made
Patterns discovered while building (things you'd Google again otherwise)
What tools, services, APIs the project depends on and how they're wired together
Key abstractions, how they connect, what the mental model is
Trade-offs that were evaluated, what was picked and why
Things learned while building that aren't obvious from reading the code

Not worth distilling:

File listings, boilerplate, config that's obvious
Individual bug fixes with no broader lesson
Dependency versions, lock file contents
Implementation details the code already says clearly
Routine changes anyone could read from the diff

The heuristic: if reading the codebase answers the question, don't wiki it. If you'd have to re-derive the reasoning by reading git blame across 20 commits, wiki it.

核心判断标准参考Karpathy的模式：如果你3个月后完全忘记了项目上下文，你会想要了解这个项目的哪些信息？

值得提炼的内容：

架构决策及其背后的原因
开发过程中总结的模式（不然之后你还会再谷歌搜索的内容）
项目依赖的工具、服务、API以及它们的关联方式
核心抽象、它们之间的关联、整体心智模型
评估过的取舍方案，最终选择的方案以及选择原因
开发过程中学到的、仅读代码无法明确感知的内容

不值得提炼的内容：

文件列表、样板代码、显而易见的配置
没有普遍参考价值的单个bug修复
依赖版本、锁文件内容
代码已经清晰表达的实现细节
任何人看diff就能明白的常规变更

判断准则：如果读代码库就能得到答案，就不用写入wiki。如果你需要翻20条提交的git blame才能推导出来背后的逻辑，就写入wiki。

Step 4: Distill into Wiki Pages

步骤4：提炼为知识库页面

Project-specific knowledge

项目专属知识

Goes under

$VAULT/projects/<project-name>/

projects/<project-name>/
├── <project-name>.md          ← project overview (named after the project, NOT _project.md)
├── concepts/                  ← project-specific ideas, architectures
├── skills/                    ← project-specific how-tos, patterns
└── references/                ← project-specific source summaries

The overview page (

<project-name>.md

) should have:

What the project is (one paragraph)
Key concepts and how they connect
Links to project-specific and global wiki pages

存放在

$VAULT/projects/<project-name>/

目录下：

projects/<project-name>/
├── <project-name>.md          ← 项目概览（以项目名命名，不要用_project.md）
├── concepts/                  ← 项目专属概念、架构
├── skills/                    ← 项目专属操作指南、模式
└── references/                ← 项目专属源码总结

概览页面（

<project-name>.md

）需要包含：

项目是什么（一段文字说明）
核心概念以及它们的关联
指向项目专属页面和全局知识库页面的链接

Global knowledge

全局知识

Things that aren't project-specific go in the global categories:

What you found	Where it goes
A general concept learned	`concepts/`
A reusable pattern or technique	`skills/`
A tool/service/person	`entities/`
Cross-project analysis	`synthesis/`

不属于项目专属的内容存放到全局分类目录：

提炼的内容类型	存放位置
学到的通用概念	`concepts/`
可复用的模式或技巧	`skills/`
工具/服务/人物相关内容	`entities/`
跨项目分析内容	`synthesis/`

Page format

页面格式

Every page needs YAML frontmatter:

markdown

---
title: >-
    Page Title
category: concepts
tags: [tag1, tag2]
sources: [projects/<project-name>]
summary: >-
    One or two sentences (≤200 chars) describing what this page covers.
provenance:
  extracted: 0.6
  inferred: 0.35
  ambiguous: 0.05
created: TIMESTAMP
updated: TIMESTAMP
---

Use folded scalar syntax (summary: >-) for title and summary to keep frontmatter parser-safe across punctuation (:, #, quotes) without escaping rules.
Keep the title and summary contents indented by two spaces under summary: >-.

每个页面都需要包含YAML frontmatter：

markdown

---
title: >-
    Page Title
category: concepts
tags: [tag1, tag2]
sources: [projects/<project-name>]
summary: >-
    One or two sentences (≤200 chars) describing what this page covers.
provenance:
  extracted: 0.6
  inferred: 0.35
  ambiguous: 0.05
created: TIMESTAMP
updated: TIMESTAMP
---

标题和摘要使用折叠标量语法（summary: >-），避免标点（:, #, 引号）导致frontmatter解析出错，无需额外转义。
标题和摘要内容需要在summary: >-下缩进两个空格。

Page Title

页面标题

A fact the codebase or a doc actually states.
A reason the design works this way. ^[inferred]

Use [[wikilinks]] to connect to other pages.


**Write a `summary:` frontmatter field** on every new/updated page (1–2 sentences, ≤200 chars), using `>-` folded style. For project sync, a good summary answers "what does this page tell me about the project I wouldn't guess from its title?" This field powers cheap retrieval by `wiki-query`.

**Apply provenance markers** per `llm-wiki` (Provenance Markers section). For project sync specifically:

- **Extracted** — anything visible in the code, config, or a doc/commit message: file structure, dependencies, function signatures, what a file does.
- **Inferred** — *why* a decision was made, design rationale, trade-offs, "the team chose X because Y" — unless a commit message, doc, or ADR states it explicitly.
- **Ambiguous** — when the code and docs disagree, or when there's clearly an in-progress migration with two patterns living side by side.

Compute the rough fractions and write the `provenance:` block on every new/updated page.

代码库或文档、提交信息中明确记录的事实。
设计采用该方案的原因。^[inferred]

使用[[wikilinks]]关联其他页面。


**每个新增/更新的页面都要填写`summary:` frontmatter字段**（1-2句话，不超过200字符），使用`>-`折叠格式。对于项目同步场景，好的摘要需要回答「这个页面告诉了我哪些从标题猜不到的项目相关信息？」，该字段可用于`wiki-query`的快速检索。

**按照`llm-wiki`（来源标识章节）的要求添加来源标记**，针对项目同步场景的具体规则：

- **Extracted（提取内容）** — 代码、配置、文档/提交信息中可见的任何内容：文件结构、依赖、函数签名、文件用途。
- **Inferred（推断内容）** — 决策背后的原因、设计逻辑、取舍考量、「团队选择X是因为Y」这类内容，除非提交信息、文档或架构决策记录明确说明。
- **Ambiguous（模糊内容）** — 代码和文档表述不一致，或者明显有正在进行的迁移，同时存在两种模式的情况。

计算大致的占比，在每个新增/更新的页面中写入`provenance:`区块。

Updating vs creating

更新 vs 新建

If a page already exists in the vault, merge new information into it. Don't create duplicates.
If you're adding to an existing page, update the
```
updated
```
timestamp and add the new source.
Check
```
index.md
```
to see what's already there before creating anything new.

如果vault中已经存在对应页面，合并新信息到现有页面，不要创建重复内容。
如果是在现有页面中添加内容，更新
```
updated
```
时间戳，添加新的来源。
新建内容前先检查
```
index.md
```
，确认没有已有的相关内容。

Step 5: Cross-link

步骤5：添加交叉链接

After creating/updating pages:

Add
```
[[wikilinks]]
```
from new pages to existing related pages
Add
```
[[wikilinks]]
```
from existing pages back to the new ones where relevant
Link the project overview to all project-specific pages and relevant global pages

创建/更新页面后：

从新页面添加[[wikilinks]]指向已有的相关页面
相关的已有页面也添加[[wikilinks]]反向指向新页面
项目概览页面需要关联所有项目专属页面和相关的全局页面

Step 6: Update Tracking

步骤6：更新跟踪记录

Update

.manifest.json

更新

.manifest.json

Add or update this project's entry:

json

{
  "projects": {
    "<project-name>": {
      "source_cwd": "/absolute/path/to/project",
      "last_synced": "TIMESTAMP",
      "last_commit_synced": "abc123f",
      "pages_in_vault": ["projects/<project-name>/<project-name>.md", "..."]
    }
  }
}

添加或更新该项目的条目：

json

{
  "projects": {
    "<project-name>": {
      "source_cwd": "/absolute/path/to/project",
      "last_synced": "TIMESTAMP",
      "last_commit_synced": "abc123f",
      "pages_in_vault": ["projects/<project-name>/<project-name>.md", "..."]
    }
  }
}

Update

index.md

更新

index.md

Add entries for any new pages created.

为所有新建的页面添加条目。

Update

log.md

更新

log.md

Append:

- [TIMESTAMP] WIKI_UPDATE project=<project-name> pages_updated=X pages_created=Y source_cwd=/path/to/project

追加内容：

- [TIMESTAMP] WIKI_UPDATE project=<project-name> pages_updated=X pages_created=Y source_cwd=/path/to/project

Tips

提示

Be aggressive about merging. If the project uses React Server Components, don't create a new page if
```
concepts/react-server-components.md
```
already exists. Update the existing one and add this project as a source.
Consult the tag taxonomy. Read
```
$VAULT/_meta/taxonomy.md
```
if it exists, and use canonical tags.
Don't copy code. Distill the knowledge, not the implementation. "This project uses a debounced search pattern with 300ms delay" is useful. Pasting the actual debounce function is not.
Project overview is the anchor. The
```
<project-name>.md
```
file is what you'd read to get oriented. Make it good.

尽量合并内容。 如果项目使用了React Server Components，且
```
concepts/react-server-components.md
```
已经存在，不要新建页面，更新现有页面并将该项目添加为来源即可。
参考标签分类体系。 如果存在
```
$VAULT/_meta/taxonomy.md
```
，读取该文件使用规范标签。
不要复制代码。 提炼知识，而不是实现细节。「该项目使用300ms延迟的防抖搜索模式」是有用的，直接粘贴防抖函数代码则没有价值。
项目概览是核心锚点。
```
<project-name>.md
```
是用户了解项目的入门内容，要保证内容质量。

wiki-update

Original

Translation

Wiki Update — Sync Any Project to Your Wiki

知识库更新 — 将任意项目同步到你的Wiki

Before You Start

开始之前

Step 1: Understand the Project

步骤1：了解项目

Step 2: Compute the Delta

步骤2：计算变更内容

Step 3: Decide What to Distill

步骤3：确定需要提炼的内容

Step 4: Distill into Wiki Pages

步骤4：提炼为知识库页面

Project-specific knowledge

项目专属知识

Global knowledge

全局知识

Page format

页面格式

Page Title

页面标题

Updating vs creating

更新 vs 新建

Step 5: Cross-link

步骤5：添加交叉链接

Step 6: Update Tracking

步骤6：更新跟踪记录

Update
`.manifest.json`

更新
`.manifest.json`

Update
`index.md`

更新
`index.md`

Update
`log.md`

更新
`log.md`

Tips

提示

wiki-update

Original

Translation

Wiki Update — Sync Any Project to Your Wiki

知识库更新 — 将任意项目同步到你的Wiki

Before You Start

开始之前

Step 1: Understand the Project

步骤1：了解项目

Step 2: Compute the Delta

步骤2：计算变更内容

Step 3: Decide What to Distill

步骤3：确定需要提炼的内容

Step 4: Distill into Wiki Pages

步骤4：提炼为知识库页面

Project-specific knowledge

项目专属知识

Global knowledge

全局知识

Page format

页面格式

Page Title

页面标题

Updating vs creating

更新 vs 新建

Step 5: Cross-link

步骤5：添加交叉链接

Step 6: Update Tracking

步骤6：更新跟踪记录

Update .manifest.json

更新.manifest.json

Update index.md

更新index.md

Update log.md

更新log.md

Tips

提示

Update
`.manifest.json`

更新
`.manifest.json`

Update
`index.md`

更新
`index.md`

Update
`log.md`

更新
`log.md`