# Knowledge Capture

> 将项目工作和用户资料转化为可复用知识：维护项目 cairn 当前真相，检索旧教训，汇总经验证发现，并按机器 profile 把成熟知识写入 Obsidian。用户调用 $knowledge-capture，要求“初始化/维护/审计项目知识”“记录进展”“沉淀到知识库”“保存到 Obsidian”“整理资料”，或导入 PDF、Word、PPT、表格、Markdown、教材、课程、书籍时使用；AGENTS.md 启用持续复盘，或任务末审查子 Agent 发现经核实的问题时也使用。普通问答、临时编辑、重复内容和未验证推测不写入。

- **Type:** Skill
- **Install:** `agentstack add skill-empty8492-knowledge-capture-knowledge-capture`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Empty8492](https://agentstack.voostack.com/s/empty8492)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Empty8492](https://github.com/Empty8492)
- **Source:** https://github.com/Empty8492/knowledge-capture/tree/main/skills/knowledge-capture

## Install

```sh
agentstack add skill-empty8492-knowledge-capture-knowledge-capture
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/Empty8492)
- **Source:** [Empty8492/knowledge-capture](https://github.com/Empty8492/knowledge-capture)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-empty8492-knowledge-capture-knowledge-capture
- Seller: https://agentstack.voostack.com/s/empty8492
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.