Back to Details

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

开始之前

  1. 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)
  2. If 
    ~/.obsidian-wiki/config
    doesn't exist, tell the user to run 
    bash setup.sh
    from their obsidian-wiki repo first.
  3. Read 
    $OBSIDIAN_VAULT_PATH/.manifest.json
    to check if this project has been synced before.
  4. Read 
    $OBSIDIAN_VAULT_PATH/index.md
    to know what the wiki already contains.
  1. 读取
    ~/.obsidian-wiki/config
    获取以下配置： 
    • OBSIDIAN_VAULT_PATH
      — 知识库的存储路径
    • OBSIDIAN_WIKI_REPO
      — obsidian-wiki代码库的克隆地址（如需读取其他技能时使用）
  2. 如果
    ~/.obsidian-wiki/config
    不存在，告知用户需要先在obsidian-wiki代码库下执行
    bash setup.sh
    。
  3. 读取
    $OBSIDIAN_VAULT_PATH/.manifest.json
    ，检查该项目之前是否有过同步记录。
  4. 读取
    $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 foundWhere 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
    是用户了解项目的入门内容，要保证内容质量。