wiki-capture

Wiki Capture — 对话转 Wiki 笔记

将当前对话中的知识保存为永久 Wiki 笔记。目标是提取实质内容——知识本身，而不是对谈话内容的总结。

写作规范： 在任何模式下起草或改写自然语言 Markdown 之前，请先阅读并应用 llm-wiki/SKILL.md 中的 Writing Profile Resolution 部分。框架架构、来源、 安全和特定操作要求优先。 WRITING.md 中的偏好仅适用于新起草或改写的自然语言 Markdown；保留源内容和结构化记录。

此技能有三种模式：

• 完整模式（默认） — 对内容进行分类，并直接在正确的类别中编写一篇完成的、带有交叉链接的 Wiki 页面。本文档其余部分为完整模式的步骤（步骤 1–7）。
• 快速模式（--quick） — 零阻力暂存：在 60 秒内将发现写入 _raw/，不写入清单、索引、日志或 QMD。用于会话中途捕获，也由会话结束 Stop hook 使用。请参阅下文，然后停止——不要执行完整模式的步骤。
• 更正模式（--correction） — 将一条原子更正作为派生知识捕获，同时保持不可变的对话/源内容不变。使用下方模板，然后仅更新派生内容的使用方和跟踪链接。

快速模式（--quick）

在以下情况下触发：以 /wiki-capture --quick 调用；用户说“快速记录”／“记录这个发现”／“保存这个 bug 修复”／“保存这个坑”／“把这个放到原始区”／“快速保存到 wiki”；或由会话结束 Stop hook 自动触发。

速度约定： 仅在当前流程中执行。不使用子代理。不使用 QMD。不写入清单／index.md／log.md／hot.md。目标：<60 秒。稍后通过 /wiki-ingest 将内容提升为完整 wiki 页面。

1. 解析配置（参阅 llm-wiki/SKILL.md 中的 Config Resolution Protocol）：获取 OBSIDIAN_VAULT_PATH 和 OBSIDIAN_RAW_DIR（默认值：$OBSIDIAN_VAULT_PATH/_raw）。确保 $OBSIDIAN_RAW_DIR 存在；如果不存在则创建。

   捕获流程不会独立重新解释校验器的 schema 输入。当 OBSIDIAN_ALLOWED_LIFECYCLES、OBSIDIAN_ALLOWED_RELATIONSHIP_TYPES、OBSIDIAN_REQUIRED_TRUST_FIELDS 或 OBSIDIAN_SCHEMA_SOURCE 存在时，应保留其值，供下游 lint／信任度使用：CLI 值优先于环境／配置值，环境／配置值优先于框架默认值；显式空值或仅含空白字符的值会导致校验失败。省略变量即可使用默认值。

2. 判断——保留还是跳过？ 提取内容前，判断本次会话是否有值得记录的内容。这样可确保该技能能够安全地自动调用，而不会让 _raw/ 中充斥无用内容。

   • 跳过（退出并显示“本次会话没有值得记录的内容。”）：以下条件全部满足时：对话纯属交流（规划／问答／解释），没有实现工作；没有可见的错误、调试或问题排查；没有令人意外或尚未记录的内容；所有发现都已在文档中明确说明。
   • 保留（继续）：满足以下任一条件：通过调查找到了修复方案或变通方法；确认了非显而易见的库／API／框架行为（边缘情况、未记录的限制、耗时才发现的问题）；调试得出了明确结论；总结出了可复用的模式。
   • 通过 Stop hook 调用时，倾向于跳过——只有证据明确时才保留。手动调用时，倾向于保留——用户有理由才会调用它。

3. 查找可复用的发现——非显而易见的 bug 及其根本原因、框架／库的注意事项、出乎意料的 API 行为、经调查确认的变通方法、环境／工具链问题，以及调试中总结出的模式。跳过项目管理更新、CLAUDE.md 中已有的配置、没有结论的来回讨论、文档中已明确说明的内容，以及客套话。如果没有实质性发现，请说明并停止。

4. 按主题归类——每个主题类别写入一个 _raw/ 文件，而不是每条发现各写一个。文件名使用 kebab-case slug（例如：swift-actor-reentrancy、nextjs-hydration-mismatch）。

5. 推断项目背景：根据仓库名称、文件路径、框架提及和错误消息判断。使用能够可靠推断出的最具体名称；否则使用 null。

6. 写入原始文件——每个类别写入 $OBSIDIAN_RAW_DIR/<ISO-date>-<slug>.md。阅读 references/RAW-FORMAT.md，了解完整的 frontmatter 规范、发现条目的正文结构，以及来源／置信度的校准方式。各类别中可能不同的字段：title、tags（从分类体系中选 2–4 个）、summary（≤200 个字符）、project（推断所得或 null）、base_confidence（讨论过：0.6 → 已应用修复：0.75 → 测试已确认：0.9）、provenance.extracted／provenance.inferred（合计为 1.0）、lifecycle_changed（今天）、sources（"<project> session (<YYYY-MM-DD>)"）。

7. 确认——列出已暂存的文件，并告诉用户运行 /wiki-ingest 以将其提升：

   Staged to _raw/:
     _raw/2026-05-27-swift-actor-reentrancy.md   — "Actor reentrancy causes deadlock in async forEach"
   Run /wiki-ingest to promote these to full wiki pages.
   

   快速模式刻意不写入清单、index.md、log.md、hot.md，也不刷新 QMD——这些操作都由 /wiki-ingest 在内容提升过程中处理。到此为止；不要执行下方的完整模式步骤。

---

更正模式（--correction）

当用户或更高权限的来源更正了基于不可变对话、工具结果或其他原始来源得出的说法时，使用此模式。切勿编辑或复制原始来源。解析配置，读取知识库中的 AGENTS.md，并在已有的派生页面拥有该说法时更新该页面；否则，创建符合所属要求的最小更正页面。

只记录一组原子说法对。speaker_type 是语义属性，必须独立于序列化消息的 role 进行判断（工具结果可能被序列化为 role=user）。不要包含原始对话摘录。

correction_id: <stable-id>
source_locator: <immutable file:line or channel/thread/timestamp>
source_text_sha256: <64 lowercase hex chars>
serialized_role: <source role, if present>
speaker_type: user | assistant | teammate | tool_result | slack_member
original_claim:
  subject: <exact entity or capability>
  assertion: <single atomic value>
corrected_claim:
  subject: <same exact entity or capability>
  assertion: <single atomic value or null>
authority_class: contract | decision | code | test | deploy | runtime | db | narrative
verification_state: verified | inferred | unverified | contradicted
asserted_at: <ISO-8601 timestamp>
effective_at: <ISO-8601 timestamp or null>
as_of: <ISO-8601 timestamp>
supersedes: [<original-claim-id>]
consumer_propagation:
  kw: open | not_applicable | complete
  ob: open | not_applicable | complete
  requirements: open | not_applicable | complete
  code: open | not_applicable | complete
  tests: open | not_applicable | complete
  ai_memory: open | not_applicable | complete
corrected_at: <ISO-8601 timestamp>

在进行任何派生内容写入之前，直接从不可变来源计算 source_pre_sha256，并要求其等于 source_text_sha256。写入更正并更新派生内容的使用方后，从同一定位符重新计算 source_post_sha256。除非满足 source_pre_sha256 == source_post_sha256 == source_text_sha256，否则中止并报告不可变性违规。即使更正写入成功，也必须执行此验证。

写入派生更正后，通过 .manifest.json 将不可变来源链接到已创建或更新的页面；仅将更正 ID 和受影响页面数量追加到 log.md；并分别将原子更正传递给每个使用方。只有在验证某个使用方后，才能将其标记为 complete；不要将不同结果合并为一个汇总状态。更正记录中不得包含密钥、原始摘录或来源副本。

---

完整模式

开始之前

1. 解析配置 — 按照 llm-wiki/SKILL.md 中的配置解析协议操作（内联 @name 覆盖 → 从 CWD 向上查找 .env → 全局配置 → 提示设置）。这会提供 OBSIDIAN_VAULT_PATH 和 OBSIDIAN_LINK_FORMAT（默认值：wikilink）。
2. 阅读 $OBSIDIAN_VAULT_PATH/index.md，了解现有 Wiki 内容（避免重复）
3. 如果 $OBSIDIAN_VAULT_PATH/hot.md 存在，则阅读该文件，以了解近期活动的背景

在步骤 5 中编写内部链接时，根据 OBSIDIAN_LINK_FORMAT 的值，应用 llm-wiki/SKILL.md 中的链接格式章节所述的链接格式。

步骤 1：确定值得保留的内容

浏览对话并思考：如果 3 个月后不记得这次聊天，哪些新知识仍会有价值？

值得保留的内容：

• 做出的决定以及做出这些决定的原因
• 得出的分析、框架和思维模型
• 技术发现、模式或流程
• 对某个主题综合归纳后的理解
• 经过一番推理后得出的清晰概念解释
• 对话中讨论的外部来源中的关键信息

跳过：

• 后勤事务、日程安排、客套话
• 尚无结论的探索性往返讨论
• Wiki 中已有的内容

如果没有产生实质性内容，请告知用户并停止。

步骤 2：对内容类型进行分类

分配以下五种类型之一，这决定了目标文件夹和语气：

类型	说明	目标文件夹
synthesis	多步骤分析，或需要推理才能回答的特定问题	synthesis/
concept	定义、框架或思维模型（某事物是什么）	concepts/
source	对话中讨论的外部文档、文章或资源的摘要	references/
decision	战略、架构或设计选择及其理由	synthesis/
session	对话涉及多个主题时的完整讨论摘要	journal/

如果根据上下文或用户提及的内容可以明确判断该内容属于某个特定项目，则将其放在 projects/<project-name>/<category>/ 下。

步骤 3：改写为陈述性知识

不要总结对话。直接用陈述语气写出知识本身：

• 不要写：“用户询问了 X，Claude 解释说……”
• 应写：“X 的工作原理是……”
• 不要写：“我们决定使用 Y，因为……”
• 应写：“由于 [原因]，Y 优于 Z。若理由是隐含的，而非明确陈述的，则添加 [^[inferred]]”

按照 llm-wiki 添加来源标记：

• Extracted — 对话中明确陈述的内容（不添加标记）
• Inferred — 根据对话进行概括或综合得出的内容 → ^[inferred]
• Ambiguous — 存在争议、不确定或相互矛盾的内容 → ^[ambiguous]

步骤 4：生成 Slug 和标题

根据内容拟定清晰、描述性强的标题。生成 slug：

• 使用小写字母，单词之间以连字符分隔
• 最多 50 个字符
• 避免在 slug 中使用日期（frontmatter 中已有 created）

步骤 5：编写 Wiki 笔记

在目标路径创建文件，并添加必需的 frontmatter：

---
title: >-
  <Title>
category: <synthesis|concepts|references|journal|skills>
tags: [<2-5 domain tags from taxonomy>]
sources:
  - conversation:<ISO-date>
created: <obsidian-wiki memory now>
updated: <obsidian-wiki memory now>
summary: >-
  <1-2 sentences, ≤200 chars, answering "what knowledge does this page hold?">
provenance:
  extracted: 0.X
  inferred: 0.X
  ambiguous: 0.X
base_confidence: 0.42
lifecycle: draft
lifecycle_changed: <obsidian-wiki memory now --date>
---

按类型组织正文结构：

synthesis / decision：

# Title

## Context
<What prompted this — the problem or question being addressed>

## Finding / Decision
<The core knowledge or conclusion>

## Reasoning
<Why this is the case or why this choice was made>

## Implications
<What follows from this — what to watch for, next steps, trade-offs>

## Related
<[[wikilinks]] to connected pages>

concept：

# Title

<Definition in one clear sentence.>

## What It Is
<Explanation of the concept>

## How It Works
<Mechanism or structure>

## When to Use
<Applicability, conditions, trade-offs>

## Related
<[[wikilinks]]>

source：

# Title

> Source: <title or URL>

## What It Covers
<What the source is about>

## Key Points
<Bulleted claims with provenance markers>

## Open Questions
<What it raises but doesn't answer — omit if none>

## Related
<[[wikilinks]]>

session：

# Title

*Session captured: <date>*

## Topics Covered
<Brief list>

## Key Takeaways
<The 3-5 most important things that emerged>

## Decisions Made
<Any explicit decisions, with rationale>

## Open Questions
<What remains unresolved>

## Related
<[[wikilinks]]>

每篇笔记都必须链接到至少 2 个现有 wiki 页面。写入前搜索 index.md。如果相关页面少于 2 个，则为最重要的相关概念创建最简存根页面。

步骤 5b：更新所有者档案和待办索引

记忆层的价值取决于写入其中的内容。此步骤能让它持续发挥作用——如果没有这一步，档案将一直为空，会话回顾也无内容可注入。

关于用户的长期事实。 如果对话揭示了用户工作方式中稳定的特征——例如技术栈、惯例、限制条件或时区——请记录下来：

obsidian-wiki memory profile set <key> "<value>" --confidence 0.85 --source "session:<date>"

遵循与步骤 1 相同的 KEEP/SKIP 原则，并额外遵守一条更重要的规则：

• 只记录用户实际告知的内容，包括直接告知或通过明确行为展示的内容。绝不要根据导入的文档推断关于用户的长期事实——那属于文档内容，应写入页面，而非用户档案。
• 记录稳定事实，不记录偶发事件。“使用 Postgres”是事实；“今天运行了一次迁移”是事件，应记入日志。
• 有时限的事实会过期。“本周末有考试”或“要旅行到 20 日”值得带入接下来的几次会话，但不应永久保留。使用 --until YYYY-MM-DD（事实有效的最后一天）记录；过了该日期后，回顾内容便不再注入此信息。
• **校准置信度。**明确陈述的置信度约为 0.9；多次表现出来的约为 0.75；根据单次会话中的行为推断的约为 0.5——低于 0.5 时不要记录。
• 更正，不要重复。profile set 会替换现有键，因此更新已变化事实时使用同一条命令即可。

未完成事项。 如果对话中有尚未完成的工作，请记录下来，以便下次会话继续处理：

obsidian-wiki memory todo add "<the open thread>" --origin "<page or project>"

使用相同文本重新添加未完成事项会更新该事项，而不会创建重复项；因此，如果不确定该事项是否已存在，可以放心调用。如果对话中已完成某个已列出的事项，则将其关闭：

obsidian-wiki memory todo list --vault "$OBSIDIAN_VAULT_PATH"
obsidian-wiki memory todo done <id>

绝不要关闭用户实际上尚未完成的事项。工具会报告过时事项；整理列表不是你的职责。

在快速模式下，执行此步骤，但跳过步骤 6——档案和待办事项的写入成本低、有锁保护，而且正是记录信息的核心目的。

步骤 6：更新跟踪文件

一次带锁调用即可更新这三个文件：

obsidian-wiki memory sync CAPTURE \
  type=<type> page="<path>" title="<title>" \
  --takeaways "<what this capture changes about the picture, if anything>"

绝不要手动编辑 index.md、log.md 或 hot.md——参见 .skills/llm-wiki/references/MEMORY.md。如果本次记录没有改变整体认知，请省略 --takeaways；先前的要点会保留。

步骤 7：向用户确认

报告已保存的路径和标题：

Saved to: projects/<name>/synthesis/<slug>.md
Title: <Title>
Type: synthesis

质量检查清单

• 内容已改写为陈述性知识（而非聊天记录）
• 类型分类正确；目标路径位于正确文件夹
• Frontmatter 完整，包含标题、类别、标签、来源、摘要和出处
• 至少有 2 个指向现有页面的维基链接
• 已更新 index.md、log.md 和 hot.md
• 已向用户确认保存路径

写入 Vault 后刷新 QMD

QMD 是搜索索引，不是真实信息来源。如果 $QMD_WIKI_COLLECTION 为空或未设置，请跳过此步骤。仅当此技能已写入或改写 Vault Markdown 后，才运行此步骤。如果 QMD 刷新失败，请勿回滚 Vault 更改；应单独报告 QMD 状态。

如果已设置 $QMD_CLI，则使用它；否则使用 qmd。

${QMD_CLI:-qmd} update

如果输出提示需要向量或嵌入可能已过期，请运行：

${QMD_CLI:-qmd} embed

使用以下任一方式验证集合：

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

或者，如果已知特定页面路径：

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

记录以下其中一项：

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>