你会得到什么 · 真实成果 · 它擅长什么 · 三层工作流 · 开始使用
给它一个模糊的学习主题、一条网页或视频、一个帖子、一份 transcript，甚至一段还没有结构的原始文案；它会先取得真正的一手材料，再把材料重建成知识地图、学习顺序、论证结构、迁移方法和带证据定位的学习文章。
当前版本：v0.7.1。 这是一个面向 Codex 的端到端知识工作流，不是单纯的视频总结器，也不是平台抓取命令的集合。项目运行时不依赖 Agent Reach；OpenCLI 只是可选采集路线之一。
| 你现在遇到的问题 | 工作流替你完成 | 最终得到 |
|---|---|---|
| “我想学这个主题，但不知道搜什么、信什么” | 拆解搜索意图、组织查询、比较来源、排除低质量候选 | 候选来源台账、可信度判断、推荐选材理由 |
| “我有网页、视频或帖子，但不想只看一篇摘要” | 获取正文、字幕或授权媒体，确认目标和材料范围 | 通过 Source Gate 的一手材料与分析包 |
| “内容很长、很散，不知道重点和学习顺序” | 重建核心问题、概念关系、论证步骤、案例作用和前置依赖 | 知识地图、前置知识、推荐学习路径 |
| “我理解了，但不知道怎样迁移和行动” | 从来源中提炼可复用方法，并把建议与作者原话分开 | 迁移方法、练习、理解检查和今天的第一步 |
| “我要写报告、提纲、简报或研究笔记” | 只使用当前有效的证据和声明生成文档 | Source / Inference / Extension 分层的正式交付物 |
它交付的不是“更长的摘要”，而是一套可以继续学习和使用的知识产品：
原始材料
→ 这份内容到底在解决什么问题
→ 作者的核心主张与论证是怎样展开的
→ 哪些概念必须先学，哪些应该后学
→ 每个案例在论证中承担什么作用
→ 哪些方法可以迁移到其他问题
→ 今天可以做什么，以及怎样检查自己是否理解
→ 每条关键结论对应哪段原文、时间戳和证据记录
下面不是模板设想，而是 v0.7.1 在 2026-07-23 完成的真实在线运行。数据用于展示产品能力，不是效果优越性 benchmark。
输入是一个关于 Codex 使用方法的 X 内嵌视频。工作流没有把帖子 caption 当成视频内容，而是取得内嵌视频字幕，再完成证据审计和学习重构。
- 716 个带时间信息的 transcript 片段；
- 76 个 evidence map 条目，全部绑定 transcript 范围；
- 14 条 claims，全部具有来源范围，0 个 blocking claim；
- 12 项学习文章质量门全部通过；
- 最终文章包含 30 个标题层级、知识地图、前置知识、5 个核心概念、3 个教学案例、迁移方法、行动步骤和原文定位索引。
最终文章回答的不是“视频讲了什么”，而是：
怎样把 Codex 从一个会给建议的问答工具，变成能在真实项目里执行、审查并交付工作的可控智能体？
另一次 YouTube 视频 没有可用字幕。工作流没有根据标题或简介猜内容，而是记录字幕路线失败，取得授权音频，再由证据层完成 ASR：
- 605 个 transcript 片段；
- 74 个 evidence map 条目，全部绑定 transcript 范围；
- 14 条 claims，0 个 blocking claim、0 个 evidence error；
- 17 个重建后的 Source 条目逐一通过原文锚点校验；
- 最终生成知识地图、嫌疑假设的检验框架、学习顺序、迁移方法和时间定位索引。
这展示了项目真正的价值：当普通摘要最容易凭 metadata 补写时，它会先补齐材料；当材料真的成立时，它又不止停在转录稿。
视频、访谈和长文通常按照表达顺序展开，但表达顺序不一定是最好的学习顺序。工作流会同时保留：
- 作者原本怎样提出问题和推进论证；
- 学习者应该先掌握哪些前置知识；
- 核心概念之间是什么关系；
- 哪些内容可以暂时跳过。
时间戳只负责把你带回原文，不再充当文章目录。
它会区分：
- 核心问题与核心主张；
- 观察、假设、案例、反证和结论；
- 执行者、原因、受益者等容易混淆的角色；
- 强证据、弱线索和仍需验证的推测。
所以最终结果不仅告诉你“结论是什么”，还告诉你“为什么可以这样判断”。
普通总结经常把案例压缩掉；本项目会保留案例在原文中的教学作用，并进一步提炼：
- 这个案例解释了哪个概念；
- 它支持或限制了哪条结论；
- 怎样把同样的方法迁移到另一个问题；
- 迁移时有哪些边界。
学习文章可以生成：
- 推荐学习顺序与最低掌握标准；
- 可迁移的方法模式；
- 今天的第一步；
- 练习与理解检查；
- 应该暂时跳过的细节。
这让结果从“读完觉得懂了”变成“知道下一步怎样学、怎样验证自己真的懂了”。
- Source：原始材料明确表达、可以回到来源定位；
- Inference：为了理解而重建的关系、结构和学习顺序；
- Extension：面向迁移、练习和行动增加的建议。
工作流不会把 Agent 的学习设计伪装成作者原话，也不会把搜索摘要升级成来源事实。
帖子文字不是内嵌视频，metadata 不是正文，媒体文件也不是 transcript。材料不足时，系统会返回明确状态、失败路线和下一步，而不是生成一份无法回到来源的报告。
| 层 | 它负责回答 | 公开入口 | 交接结果 |
|---|---|---|---|
| 搜索与选材 | 应该找什么，哪份材料更值得进入工作流？ | web-intent-scout |
intent map、查询族、source ledger、候选来源 |
| 材料采集 | 实际取得了什么，是正文、帖子、字幕、媒体还是 metadata？ | acquire-source-material |
Acquisition Bundle v2、Provider 日志、哈希和范围 |
| 证据分析与交付 | 当前材料能支持什么，怎样变成学习成果？ | source-gated-evidence-layer → knowledge-learning-article / knowledge-document-composer |
evidence map、receipts、学习文章或正式文档 |
knowledge-workflow-console 是总入口，只负责路由、交接和状态汇总。搜索层的推荐不能直接成为最终证据；采集成功也不代表分析层一定放行。
宽泛学习需求 ─→ 搜索与选材 ─→ 选定原始来源 ─┐
已有 URL / 文件 ──────────────────────────┘
▼
采集正文 / 字幕 / 授权媒体 / 仓库内容
▼
目标匹配 · 完整度 · 哈希 · ASR · 证据审计
┌──────────────┴──────────────┐
▼ ▼
面向学习的知识文章 来源忠实的正式文档
└──────────────┬──────────────┘
▼
quality gate + receipt
查看六个公开 Skills 与内部边界
knowledge-workflow-console：端到端路由与状态汇总；web-intent-scout：网页搜索、意图拆解与来源筛选；acquire-source-material：本地与在线材料采集；source-gated-evidence-layer：范围、哈希、ASR 和证据门；knowledge-learning-article：知识地图、前置关系、学习路径与学习文章；knowledge-document-composer：来源忠实的报告、提纲、简报和研究笔记。
knowledge-video-decomposer 只保留为内部兼容脚本库。browser-host-identity 是独立项目，不属于本工作流的产品链。
| 你需要解决的问题 | 普通 Agent | Agent Reach / 单独平台 CLI | Knowledge Workflow |
|---|---|---|---|
| 快速问答或临时总结 | 合适 | 不是主要目标 | 可以，但不是优势所在 |
| 执行一次平台命令、取得平台数据 | 取决于工具 | 更直接 | 可以通过 Provider 层完成 |
| 从模糊需求开始搜索并选材 | 容易与回答混在一起 | 不负责完整学习链 | 独立搜索层与来源台账 |
| 判断材料能支持什么结论 | 通常依赖模型自觉 | 不负责下游证据许可 | Source Gate 强制检查目标、范围和哈希 |
| 把材料变成系统学习成果 | 通常是一篇摘要 | 不负责 | 知识地图、前置关系、学习路径、迁移与行动 |
| 回到原始证据检查 | 依赖回答中的链接 | 以工具结果为主 | claims、evidence map、时间锚点和 receipts |
如果只想调用一次平台工具，Agent Reach 或单独 CLI 可能更轻。这个项目适合的是一条更完整的需求：
帮我找到值得学的材料，取得真正内容，判断它能支持什么，再把它整理成我可以系统学习和长期复用的知识。
需要 Python 3.10 或更高版本。请使用完整源码 checkout 或 Release 中的 source ZIP；Python wheel 只包含 CLI，不包含完整 Skills 和内部脚本。
git clone https://github.com/sitabanubanu/codex-knowledge-workflow-skills.git
cd codex-knowledge-workflow-skills
python -m pip install -e .
kw versionWindows：
.\sync_to_codex_skills.ps1 -DryRun
.\sync_to_codex_skills.ps1
.\sync_to_codex_skills.ps1 -VerifyOnlymacOS / Linux：
./sync_to_codex_skills.sh --dry-run
./sync_to_codex_skills.sh
./sync_to_codex_skills.sh --verify-onlykw demo
kw result --project-root .\outputs\knowledge-workflow\demo-transcript从 outputs/knowledge-workflow/demo-transcript/result_index.md 开始阅读。这个 demo 用来证明安装和证据链正常；上面的真实运行案例才用于展示完整学习产品。
kw source doctor
kw source plan --input <URL或文件> --target <目标> --operation <操作>
kw run `
--input <URL或本地文件> `
--target <目标> `
--operation <操作> `
--mode audit `
--deliverable learning_article `
--final-language zh-CN常见目标：
| 你要分析的对象 | --target |
--operation |
|---|---|---|
| 网页正文 | web_article |
read |
| GitHub 仓库 | repository |
read |
| X 等平台的帖子文字 | social_post |
read |
| YouTube、Bilibili、X 内嵌视频 | video_content |
extract_transcript |
standard / deep 路线需要 Agent 只依据已验收材料完成语义重构。总控台会生成：
15_learning/learning_enrichment_request.json
生成证据锚定的 learning_enrichment.json 后继续：
kw learn `
--project-root <任务目录> `
--enrichment <任务目录>\15_learning\learning_enrichment.json `
--depth standard这个停顿是产品设计的一部分：程序负责验证证据，Agent 负责受约束的理解和学习设计。
- 不承诺每个 URL 都能获取；平台登录、反自动化、地区和账号权限会变化；
- 不绕过 CAPTCHA、付费墙、私密访问或平台授权；
- OpenCLI 是可选浏览器 Provider，不是总控台，也不是唯一采集路线；
- 没有正文、字幕或可转录媒体时，不会根据 metadata 生成完整报告；
- 搜索结果只用于选材，必须重新采集原始来源后才能进入正式分析；
- 当前回归和真实案例证明工作流可以运行并产出上述结构，不等于已经证明它在大规模 A/B 实验中优于普通 Agent。
在线材料跑不通时，先检查这些条件
| 必须确认 | 漏掉后的典型结果 |
|---|---|
--target 和 --operation 对应真正要分析的对象 |
target_mismatch |
| Provider 支持当前平台、目标和操作 | source_blocked |
| 取得的是正文或 transcript，而不是标题、caption 或播放器 | secondary_only |
| OpenCLI / cookies / 浏览器导出声明真实 Edge 或 Chrome 宿主 | 路线停止，不会猜测或切换浏览器 |
| 当前账号、地区和内容权限真实有效 | source_blocked |
| 媒体能够通过本地 ASR 派生 transcript | 否则停在 pending_derivation |
--resume 仍是同一 source + target + operation |
否则拒绝污染旧任务 |
opencli doctor 显示 connected，只证明 daemon 与某个扩展建立连接，不能证明浏览器宿主、账号权限或目标字幕已经可用。yt-dlp --cookies-from-browser 的 cookie 数据库锁也是另一套机制。
完整排查见 TROUBLESHOOTING.md。
查看支持材料、Provider 与典型结果目录
主要路线包括：
- 本地 transcript、字幕、音频和视频；
- 普通网页的
curl/ Jina Reader； - YouTube、X 内嵌视频的
yt-dlp字幕、授权媒体与 ASR； - GitHub CLI 与临时仓库读取；
- Bilibili detail / audio；
- X 帖子文字 Provider；
- 可选 OpenCLI 与用户授权浏览器导出。
典型输出：
00_acquisition/
manifest.json
logs/route_plan.json
10_video/
00_source/source_status.json
00_source/gate_receipt.json
source_analysis_pack.md
15_learning/
learning_enrichment_request.json
learning_enrichment.json
20_document/
learning_article.md 或 final_report.md
*_receipt.json
result_index.md
完整平台矩阵见 SUPPORTED_PLATFORMS.md。
kw validate --include-sync
python eval/v2/leakage_lint.py
python eval/v2/schema_contract_test.py