Knowledge Capture

Knowledge Capture

用一个技能管理两层知识：项目内的 cairn/ 保存持续变化的当前真相，Obsidian 保存已验证、可复用、已抽象且可追溯的长期知识。事实、文档主张、推断和待验证项必须分开；不得把聊天流水、完整日志或文件全文不加判断地塞入知识库。

任何 Obsidian 搜索、引用、迁移或写入前，必须完整阅读 [references/configuration.md](references/configuration.md)，并用 [scripts/resolve-vault.ps1](scripts/resolve-vault.ps1) 解析当前 profile。不得从历史会话、示例或某台主机的硬编码路径猜测 Vault。

当用户要求初始化、维护、审计项目层，或项目已经通过 AGENTS.md 启用持续复盘时，还必须完整阅读 [references/project-lifecycle.md](references/project-lifecycle.md)。

授权与写入模式

• explicit_only：只在用户明确调用本技能、要求写入知识库或确认候选后写入 Obsidian。写入前展示候选内容、证据、目标分类和待确认项。
• automatic_after_substantive_work：实质性任务结束时可自动写入通过毕业门槛且有实质新增的知识；不降低证据和去重要求。
• disabled：禁止写入 Obsidian，但仍可只读检索并维护已授权的项目层知识。
• 任务末审查或评审子 Agent 发现问题时，主 Agent 先回到代码、测试、配置、运行结果或用户确认核实。成立且具有复用或防复发价值时自动执行知识复盘；explicit_only 下只能形成并展示 Obsidian 候选，不能越过人工审核。
• 自动模式依赖 Agent 实际读取并执行 AGENTS.md，不是后台守护进程。没有 Agent 任务运行时，它不会主动扫描项目。
• 普通问答、临时格式调整、聊天流水、重复结论、未验证推测和秘密值不创建笔记。
• 不覆盖现有笔记、不修改 .obsidian、不因整理一篇笔记顺手重构整个 Vault。唯一例外是 profile 明确配置的 rulesMirrorPath：它是用户授权的受管镜像，只能由 [scripts/sync-rules-mirror.ps1](scripts/sync-rules-mirror.ps1) 与源规则文件同步。

双层生命周期

• 项目层：cairn/LOG.md 保存倒序进展和指针，cairn/ROADMAP.md 保存当前焦点，cairn/.md 保存主题当前真相，cairn/Cited.md 只记录实际采用的外部知识指针。
• 知识库层：Obsidian 保存跨任务或跨项目仍有价值的长期知识。项目日志、工程资产和原始附件默认不复制进去。
• 消费闭环：先搜索项目主题，再按需搜索 Obsidian；只有真正改变本次决策或实现的外部笔记才进入 Cited.md。
• 防复发闭环：主 Agent汇总自身和所有子 Agent 的发现，核实、去重后记录根因、保护措施和回归证据。未确认内容只能标记“待验证”。

Obsidian 沉淀工作流

1. 确定范围和证据

1. 明确主题、项目、时间范围、来源文件和用户期望的完整程度。
2. 把信息分成：已确认事实、设计决策、验证结果、来源文档主张、推断、待验证项。
3. 只有用户明确确认，或代码、测试、配置、命令输出、运行结果、权威来源直接支持的内容，才可写成事实。
4. 文件名中的“最新版”、文档修改时间、PPT 能力描述不能单独证明当前实现；只证明“该资料这样描述”。
5. 多个互不相关的主题拆成不同笔记；同一主题多份资料可以合并，但每个重要结论都要保留来源定位。

候选知识必须同时满足：

• 已验证，而不是模型猜测。
• 离开当前对话后仍有复用或防复发价值。
• 已去掉无关偶然细节，但保留类名、API、表名、字段、错误码等检索锚点。
• 能回到项目文件、测试、命令结果、原始资料或用户确认。
• 符合当前 writeMode 和用户授权。

2. 读取 PDF、Office 和个人笔记

• 文件格式只决定读取方式，不决定最终模板。先用当前环境对应的 PDF、Word、PPT、表格能力忠实读取，再按知识主要用途选模板。
• PDF 先提取文本；表格、图示、页眉页脚或排版影响结论时，渲染相关页视觉核验。扫描件需要 OCR；无法可靠识别的部分明确报告，不推断补齐。
• Word、PPT、表格保留文件名、版本、章节、页码、幻灯片或表格定位。必要时记录 SHA-256，但不把全文塞入 YAML。
• 默认使用 capture_mode: knowledge_digest 提炼知识。用户要求“全文转换”“直接转 Markdown”“不要过度提炼”或完整性优先时，使用 capture_mode: source_conversion，近原文保留标题层级、正文顺序、表格和图位，并说明合并、缺失、OCR、脱敏和附件边界。
• 个人笔记若已有稳定标题、清晰结构和可复用结论，只补必要 YAML、摘要和证据边界，不强制套满扩展模板。碎片或临时清单先提炼。
• 默认不复制原始附件和大量图片进 Vault；只有用户明确要求且确认目录、隐私和体积后才复制。

3. 解析配置并检索去重

1. 运行 resolve-vault.ps1，确认 vaultPath 存在且包含 .obsidian，读取 obsidianWriteMode、contentPaths、inboxPath 和 indexPath。
2. 使用 rg --files、rg -n 搜索整个 Vault 的 Markdown，排除 .obsidian；搜索主题、项目、同义词和精确技术锚点，不只查文件名。
3. 相同结论没有实质新增时跳过。已有笔记需要更新时，必须得到用户对该笔记的明确授权；否则新建带语义限定词的候选并链接旧笔记。
4. 新文件使用稳定主题名，不加日期、随机数或无意义序号；日期只写在 YAML created 和 updated。

4. 标记来源

| 核心证据来源 | origin_type | source | capture_mode | |---|---|---|---| | 用户的 PDF、Word、PPT、表格、文本或个人笔记 | user_document | 用户文档 或资料名称 | knowledge_digest / source_conversion | | Agent 执行中的代码、测试、命令、运行结果或复盘 | agent_runtime | 形成结论的具体 Agent 名称 | runtime_experience |

用户文件经 Agent 转换后仍是 user_document。混合证据按支撑核心结论的主要来源选一个 origin_type，并在 source_paths 中保留全部证据。来源路径位于名为 交接 的目录树下时，在 tags 中增加 交接。

5. 按主要用途选择目录

目录从解析结果的 contentPaths 取得；默认一级目录统一使用 编号_English_中文 命名，英文由多个词组成时用下划线连接。默认映射如下：

| 主要用途 | 配置键 | 默认目录 | |---|---|---| | 项目背景、产品说明、使用手册、交接、项目连续性 | project | 02_Projects_项目资料 | | API、数据库、协议、实现、Docker、部署、运维 | technical | 03_Technical_技术资料 | | 标准、教材、课程、书籍、概念、复习笔记 | learning | 04_Learning_学习资料 | | 业务域、业务规则、指标口径、数据保留、产品约束 | business | 05_Business_业务知识 | | 症状、根因、排查、修复、防复发 | troubleshooting | 06_Troubleshooting_故障案例 | | 架构、技术选型、重要取舍、已排除方案 | decision | 07_Decisions_决策方案 | | Agent、Obsidian、Git、知识管理和协作流程 | agentWorkflow | 08_AI_Workflows_AI与工作流 |

00_Inbox_收集箱 只用于用户明确要求保留但尚未审核，或暂时无法可靠分类的候选。能确定用途的已审核笔记直接进入对应内容目录。跨类型关系用 knowledge_type、标签、关键词和有语义的 [[双向链接]] 表达，不再增加细碎目录。

6. 选择正文模板

每篇笔记先使用 [assets/note-template.md](assets/note-template.md) 的统一 YAML、标题、摘要、背景和结论，再按主要用途选一个扩展模板：

| 场景 | 模板 | |---|---| | 故障、错误、性能根因与修复 | [troubleshooting.md](assets/note-templates/troubleshooting.md) | | 架构、技术选型和重要取舍 | [decision.md](assets/note-templates/decision.md) | | API、数据库、消息、模型和 schema 契约 | [data-api-contract.md](assets/note-templates/data-api-contract.md) | | 部署、发布、备份、恢复和运行手册 | [operations.md](assets/note-templates/operations.md) | | 项目状态、里程碑、连续性和交接 | [project-handoff.md](assets/note-templates/project-handoff.md) | | 独立可复用的代码或命令 | [code-command.md](assets/note-templates/code-command.md) | | 教材、课程和书籍的理解、复习与实践 | [learning-concept.md](assets/note-templates/learning-concept.md) | | 业务域、规则、口径、角色和流程 | [business-domain.md](assets/note-templates/business-domain.md) | | Agent 工具、协作流程和知识工作流 | [agent-workflow.md](assets/note-templates/agent-workflow.md) | | 忠实归纳资料主张、证据定位和时效 | [source-digest.md](assets/note-templates/source-digest.md) | | 近原文把资料转换为 Markdown | [source-conversion.md](assets/note-templates/source-conversion.md) |

• 模板按知识用途选择，不按文件扩展名选择。一份 PDF 可以生成故障、决策、接口或学习笔记。
• 学习资料以理解和应用为目标时用 learning-concept.md；以忠实说明资料写了什么为目标时用 source-digest.md；需要尽量完整保留原文时用 source-conversion.md。
• 一本书或一门课程包含多个独立主题时按稳定知识主题拆分，不按每章机械生成摘要。
• 每篇笔记只选一个主模板；必要时从另一模板增加少量章节。删除所有占位符、模板注释和空章节。

7. 创建、验证和报告

1. 生成有效 YAML，至少包含 title、created、updated、source、origin_type、capture_mode、project、project_path、status、knowledge_type、validity、confidentiality、tags、keywords、source_paths。
2. YAML 后直接写 # 标题、摘要、背景和结论；属性保持短小，证据链放正文。
3. 代码块带语言标识；命令写明前置条件、风险、验证和回滚，不包含秘密值。
4. 写入后重读文件，验证 UTF-8、YAML、目标目录、来源、标签、稳定文件名、wikilink 和敏感信息。
5. 最终报告新建/更新/跳过的文件、证据和待确认项。没有合格候选时明确说明“本轮无须沉淀”，不创建空笔记。

项目层与审查问题

• 项目已启用持续维护时，实质性进展更新 cairn/LOG.md；稳定结论更新主题当前真相；路线图只维护当前焦点和未决问题。
• 子 Agent 默认只返回“发现、证据、影响、建议、确认状态”，由主 Agent 统一核验和写入，避免并发覆盖知识文件。
• 故障或审查问题应记录症状/触发条件、根因、误导假设、防复发约束和回归验证。只有证据充分时才写成规则。
• 项目层可按项目规则自动维护；是否毕业到 Obsidian仍由 profile 的 writeMode 独立决定。

敏感信息和边界

绝不写入密码、API Key、Token、Cookie、私钥或完整秘密连接字符串。内部地址、账号、客户信息和个人信息只有在用户明确授权、对结论必要且有长期价值时才保留；否则使用明确占位符。数据库备份、构建物、依赖包、整库数据和无长期价值的二进制文件不进入知识层。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Empty8492
• Source: Empty8492/knowledge-capture
• License: MIT

Install and usage instructions live in the source repository linked above.