-knowledge：AI Agent 工具实践指南

面对实际交付，我看-knowledge的重点不在星标，而在这项能力：将任何 视频平台 视频中的知识上传到您的第二个大脑：Claude Code 和 Codex 读取完整的文字记录和关键帧，然后编写关联的黑曜石笔记。这类视频制作工具真正难在素材、节奏、编码和最终画面容易不一致，仓库说明只能作为第一层证据。短测时我会拿一组已有素材完成一段短样片，并保留素材路径、渲染结果、音画同步和导出格式的结果，方便团队复盘。我的判断是，它更适合有真实素材并需要稳定视频产出的创作者；若眼下没有这类需求，先保留观察即可。

名称：-知识 描述：当用户要求学习或记录 视频平台 视频时，从任意长度的 视频平台 视频中提取完整的知识，分析其整个文字记录和有意义的视觉内容，并创建大量主题路由的黑曜石 MOC 和带有经过验证的双向链接的见解笔记。

视频平台 知识

将视频变成实质性的、相互关联的知识。方法完成 在写作之前分析视频是否持续15分钟或3小时或更长时间。 CLI 处理提取和检查；你进行分析并写笔记。

解决请求

在克劳德代码中输入：/-knowledge [vault]。 在 Codex 中输入：$-knowledge [vault]，或用自然语言询问。

在运行 CLI 命令之前，请使用 yk（如果 PATH 上可用）。否则使用 下面安装的包装器，或者默认安装的 ~/.-knowledge/bin/yk。 在此技能中的每个命令中，将该可执行文件替换为 yk。

1. 按以下顺序解析保管库：用户的显式参数，然后 yk config get vault --json，然后询问用户路径并提出保存 与 yk config set vault "/path/to/vault"。不要猜测个人保管库路径。
2. 确认所选目录存在并包含 .obsidian/。阅读并 修改注释之前请遵守保管库的指示。
3. 读取 yk config get --json。 notes_language: auto 表示视频的原创 语言。否则，请使用为散文和章节标题配置的语言。 需要时保留准确的来源引文和标签翻译。
4. no_dashes: true 是默认的房屋风格：规范化 U+2013 和 U+2014 在源标题中，frontmatter source_title，以及对普通文本的精确引用 与周围空格的连字符。这种标准化是唯一允许的 更改为其他准确的标题或引文。不要使用那些 Unicode 在注释、前言或报告中的其他地方用破折号。用户可以通过以下方式禁用此功能 yk config set no_dashes false。将报价属性设置为 > Speaker, Video Title。

仅当 yk 和包装器都不存在时，告诉用户运行此安装程序， 然后在设置后恢复：

curl -fsSL https://raw.githubusercontent.com/ogabrielalonso/-knowledge/main/install.sh | bash

原则

• 在写任何笔记之前分析完整的文字记录和有意义的关键帧。
• 比起十个浅薄的笔记，更喜欢两三个精彩的见解。没有空的笔记。
• 按主导主题进行路由，而不是按标题中提到的工具进行路由。一个视频 关于使用AI助手作为第二大脑属于知识管理， 不会自动使用该助理的工具注释。
• 在写作之前，使用关键字和代理的搜索工具搜索保鲜库。 如果保管库提供语义搜索，请使用语义搜索。找到已有的主题簇， 写在那里，并将新笔记与相关兄弟姐妹双向连接。
• 坚持观看长视频。跟踪进度并继续阅读直至结束。 如果依赖项或访问问题阻止完成，请报告实际的阻止者 并保留工作工件以供恢复。切勿声称部分分析已完成。
• 成功验证后仅清理该视频拥有的工作目录。 切勿删除 yt_* 等 glob 或其他会话的文件。

提取确定性工件

yk fetch "URL" --json

使用真实的URL。读取返回的workdir、lease、video_id；使用这些精确值 在后续命令中。默认目录是配置的临时根目录 或系统临时目录，后跟 yt_。明确的 --workdir 是一个确切的目录，并且必须具有该基本名称。

该命令写入info.json，原语言和英文字幕时 可用，不超过 720p 的视频、frames/、transcript.txt 和 meta.json。 字幕变成带时间戳的文本，并删除滚动重复项。当字幕 不存在时，CPU Whisper 使用配置的模型（默认 base）转录音频。 第一次后备运行会下载该模型。从以下位置读取 transcript_source 元数据；在最终报告中区分 manual、auto 和 whisper。

每五秒提取一次 1280 像素宽的帧。框架 N 盖 (N-1)*5 到 N*5 秒。重新运行重用已完成的工件。 --no-video 用于明确请求的仅转录本运行；可能仍然需要音频 对于耳语。不要在正常的知识运行中默默地跳过视觉分析。

如果提取失败，请检查报告的错误。机器人检查可能是由于 数据中心或 加密网络通道 IP。解释建议的浏览器 cookie 设置，如果需要， 在用户自己的计算机上重试。私人或不可用的视频需要有效的 URL 和具有访问权限的帐户。不要盲目重试。对于持久提取器 失败，建议重新运行安装程序来升级 yt-dlp，然后重试一次。 如果仍然失败，请报告原因并索要可访问的 URL 或成绩单。 请勿使用原始 yt-dlp、ffmpeg 或即兴转录脚本。

写作前先分析一切

1. 以大约 650 行的块读取 ENTIRE transcript.txt。继续 从最后一个偏移量到最后，而不仅仅是直到似乎有足够的材料可用为止。 跟踪主题和时间戳、准确的报价、框架、工具和可操作的内容 步骤。摘要或样本转录本不满足此步骤。

2. 生成视觉候选：

   yk keyframes "WORKDIR" --json
   

   替换返回的目录。选择器比较连续的灰度 具有像素差异的 32x18 缩略图。读取keyframes.json，将其对齐 记录中带有屏幕共享窗口的时间戳，并检查 选定的图像。不要单独读取每个原始帧。

3. 始终检查包含文本、图表、幻灯片、代码或内容的有意义的框架 示威活动。像素相似度只是一个过滤器，而不是冗余证明。 如果缺少屏幕共享间隔或小的文本更改，请检查附近的 原始帧并根据需要降低 --threshold。不要使用 --max 截断 所需的分析。跟踪您实际详细检查了多少帧。 参考规模，而不是配额：94分钟的视频可以产生1126个提取帧， 大约220个关键帧，大约30个需要详细阅读的帧。

4. 综合BEFORE写作：中心问题，三到五个主要概念， 什么是新颖的，什么是通用的，以及实用的要点。分开什么来源 从你的解释中可以看出。不要发明未读过的视觉效果或引文。

5. 现在搜索现有的主题集群。检查可能的兄弟姐妹和任何来源 INDEX。决定目的地，什么值得独立洞察，以及什么 现有笔记应该收到相互链接。

写大量笔记

始终创建一个 MOC（概述）。通常会创建两到五个见解，更多的用于 合理时视频超过三个小时。独立的见解至少应该具有 三分钟的专门解释、有意义的框架或图表、 分步过程，或同等的独立价值。不要制造见解 达到计数。

使用连字符分隔的文件名，不包含特殊字符，最多 50 个字符 包括.md。使用描述性 ASCII slugs，同时将标题保留在配置中 注释语言。遵循现有的主题组织和命名约定 兼容。现有笔记是用户的内容。切勿删除、重写、重新排序、 或重新格式化现有文本，并且切勿更改现有注释的标题、文件名或 现有的 frontmatter 值。在写入现有注释之前，记录其当前 通过阅读内容。编辑完成后，确认原文仍然存在 逐字记录；如果不是，请在继续之前恢复它。

对现有注释的编辑仅是附加的。将 wiki 链接附加到现有相关 部分，或者如果不存在则在末尾添加相关部分。添加 frontmatter 键 仅当保管库已使用这些密钥时。 （可选）附加一个标题清晰的 最后的部分，例如 ## From "，带有简短的摘要和 链接到新的 MOC 或见解。切勿更改现有的 frontmatter 值或内容 以适应该技能的架构。

当现有笔记已经涵盖了视频深入解释的概念时， 将新的见解写为具有不同的、更具体的文件名的新注释，并且 将现有笔记和新见解双向链接。在 报告。不要使用现有的注释来替代新的见解。

每个音符都有 YAML frontmatter 和这些键：

使用实际值并引用 YAML 中的 wiki 链接。真正不可用的源字段 可以为空，并在注释中进行解释。不要发明元数据或使用填充物。

MOC：至少 150 个非空行

包括所有适用的部分，翻译成注释语言：

• 元数据表：频道、持续时间、URL。
• 中心论点：一个重要的段落。
• 概述：三到五个段落，涵盖问题和建议的解决方案。
• 关键概念：详细解释、来源引用、如何应用和链接 对于每个概念，都有相应的见解（如果存在）。
• 时间戳：将时刻与主题链接起来的表格。
• 值得注意的引文：准确的、归因的陈述。
• 工具和资源：实际提到的工具和资源（如果有）。
• 行动项目：来源支持的实际步骤。
• 相关注释：相关主题集群和新创建的见解。
• 处理页脚：转录源和提取、选择和检查 帧计数。

见解：每行至少 50 个非空行

无需阅读 MOC，洞察力就一定有用。包括：

• 带有出处的报价。
• 它是什么。
• 它解决的问题。
• 它是如何运作的，并附有具体步骤。
• 实际例子。
• 关键原则。
• 何时使用以及何时使用 NOT。
• 相关：MOC 和相关兄弟笔记。
• 带有相关时间戳的源页脚。

删除原本为空的部分。切勿留下占位符，TODOs， 通用填充符或空标题。行最小值计算实际非空行； 它是实质性内容的基础，而不是人为分割句子的理由。 如果来源不能支持所需的物质，请解释限制 填充注释或声称已完成。

验证、连接、清理、报告

1. 完成所有新笔记，以便解析它们的链接。运行：

   yk check "MOC_PATH" "INSIGHT_PATH" --vault "VAULT_PATH" --json
   

   提供所有实际的新的或更新的源注释。修复每个故障：必需 frontmatter、最少行数、启用时禁止的破折号以及每个 wiki 链接。 别名和标题链接必须指向现有注释。验证检查注意事项 目标，而不是标题存在或你的分析的真相。也审查内容。

2. 在引用的同级注释的相关部分中添加相互链接 如果适用，请遵循上述仅附加规则更新源 INDEX。 重新检查更改的视频平台注释；检查添加到旧笔记的链接，无需 将此技能的源注释模式强加于整个保管库。

3. 验证成功后，使用准确的值运行 yk clean "WORKDIR" --lease "LEASE" --json 该提取返回 workdir 和 lease。每次成功的获取都会创建一个 新租约，包括缓存的重播。每个租约释放一次；目录 仅在最后一次租约后才被删除。视频 IDs 和过时的令牌被拒绝。 切勿使用 shell 删除 glob。 中断时，报告保留的工作并在清理之前恢复。

4. 报告视频、频道和时长；每个创建的音符的路径和实际线条 计数；成绩单来源； extracted/keyframe/actually 检查计数； 验证结果；相互链接和 INDEX 更改；和清理结果。 列出所触及的所有现有注释以及准确附加的内容。提及任何 新见解与现有注释之间的重叠，以及明显的局限性。 仅报告实际完成的操作的成功。