章节总览
知识整理与写作方法 / 47 · 技能文档
原目录

knowledge2md 的来源处理、原文与解读分层、目录命名及图文归档流程。

knowledge2md / k2md — 知识源转离线 Markdown

把一篇(需登录才能看的)字节内部技术文章,抓成图文完整、可离线阅读的 Markdown, 存进本地知识库。核心价值:正文 + 所有图片 / 画板 / 视频都落地到本地,断网也能看,链接永不失效。

何时用

用户给出下列任一链接,并希望「转成 MD / 存下来 / 做离线版 / 存进开发知识库」:

  • ByteTech 社区文章:内部资源<id>
  • 飞书文档(很多 ByteTech 文章的正文实体):https://*.larkoffice.com/docx/<token>、/wiki/<token>、*.feishu.cn/docx/...
  • 微信公众号文章:https://mp.weixin.qq.com/s/<id>(公开网页,无需 cookie / lark-cli)
  • 公开 Notion 页面:https://*.notion.site/<slug>-<page-id>(匿名读取公开 block 与图片,不使用登录态)

原理(为什么要这样做)

ByteTech 文章页是登录态 SPA,正文不在网页里,而是寄存在一篇飞书 docx。 bytetech.info/proxy_tech_api/v1/article/detail 接口只返回元数据 + 指针字段 lark_doc_url。 所以流程是:bytetech 接口取到飞书链接和标题 → lark-cli 读飞书 docx 为 markdown → 下载全部素材 → 重写为本地相对路径。 若用户直接给飞书 docx 链接,则跳过第一步、不需要 cookie(lark-cli 自带 user 登录态)。 微信公众号文章是公开网页,正文就在 HTML 的 #js_content 里,走独立分支 (scripts/wx2md.py:curl 抓页面 → 标准库 html.parser 转 markdown → 图片带 Referer: mp.weixin.qq.com 下载, 扩展名按 magic bytes 判定——微信 wx_fmt=webp 经常实际返回 jpeg),全程不需要 cookie / lark-cli。 公开 Notion 页面走 scripts/notion2md.py:匿名分页读取公开 block,转换常见富文本、列表、代码、Mermaid、callout 和图片, 再把图片签名 URL 下载为本地素材。私有页面、登录态页面和未公开内容不在此分支范围内。

运行命令

默认 api 模式保持原有完整导出能力,会用 lark-cli 读取飞书文档并下载素材:

python3 ~/.agents/skills/knowledge2md/scripts/knowledge2md.py "<url>" [--cookie "<bytetech cookie>"] [--tag <标签>] [--out <目录>]

不需要离线视频时显式跳过,正文会保留“视频未归档”提示,且不会先下载再删除:

python3 ~/.agents/skills/knowledge2md/scripts/knowledge2md.py "<url>" --skip-videos

如果当前 shell 已加载 ~/.zshrc,也可以直接使用短命令:

k2md "<url>" [--cookie "<bytetech cookie>"] [--tag <标签>] [--out <目录>]

参数:

  • --mode api|browser:默认 api。browser 只读取当前浏览器中用户正常可见、已渲染的 docx/wiki 页面内容,不调用 lark-cli,不调用 docs/wiki/media 下载接口。
  • --cookie:仅 bytetech 链接需要。会缓存到 skill 目录 .cookie,下次可省略;失效时重新传。
  • --tag:文件名 【】 里的标签。缺省时自动从正文中的 skills.bytedance.net/.../<slug> 书签提取(如 skill-evo);没有则不加。
  • --out:输出基础目录,默认 ~/Desktop/dev-knowledge-base。
  • --skip-videos:仅飞书 API 模式使用;不下载视频文件,在正文对应位置保留来源文档观看提示。
  • --cdp-url:仅 --mode browser 使用。Chrome/CDP endpoint,例如 http://127.0.0.1:9222;省略时自动探测 9222/9223/9224/9225/9229。
  • --scroll-rounds:仅 --mode browser 使用。自动滚动轮数,用于触发懒加载,默认 12。

脚本原始输出:<base>/<原标题>【<tag>】/<原标题>【<tag>】.md + 同目录 assets/(img-NNN.、wb-NNN.)。 完成抓取后,按下方“知识库语义命名”规则只整理外层目录名;目录内部文件名和文件内容保持原始归档状态。 脚本最后打印一行 JSON(md_path、assets、images、whiteboards),据此向用户汇报。

原文保存与二次解读(默认双层产物)

先判断输入是“来源原文”还是“已经成型的技术解读”。不要把两种情况混成同一种编辑策略。

来源原文:先原样归档,再另建解读版

公众号推送、新闻稿、ByteTech 原文、飞书原始材料和普通网页默认属于来源原文。处理顺序:

  1. 先生成图文完整的离线原文 Markdown,保留原始标题、正文顺序、作者表达、图片与来源 URL。
  2. 不在原文 Markdown 中直接插入大段改写、技术纠错或二次总结;必要的抓取说明只放在简短归档元数据中。
  3. 在同一外层目录另建 <原文件名>-解读版.md,明确标注“二次解读”,并在首屏回链原文离线版和一手来源。
  4. 解读版负责术语解释、核心机制、论文核验、事实更正、适用边界、工程启示和补充图示;观点与原文主张必须分开标注。
  5. 原文素材保持不变。解读版若替换为论文高清原图或增加 GPT Image 图,使用独立、可辨识的文件名,并保留来源或提示词。

二次解读的语言与术语规范(强制)

解读版采用技术教材或研究笔记的表达方式,目标是让没有阅读原论文的读者能够逐项理解概念、实验角色和公式。

  1. 专业名词首次出现时立即定义,说明它是什么、输入输出是什么、在当前论文中由什么实体实现。不得只保留英文缩写。例如首次出现 Grader 时,说明它是接收模型输出并返回分数、通过结果或风险判断的评分组件,并区分训练期 Reward Model、评测期 Verifier、部署期 Monitor。
  2. 对容易混淆的相邻概念使用对照表,例如 Grader / Reward / Reward Model / Verifier,Reward-Seeking / Reward Hacking / Metagaming。说明概念之间的包含、重叠和非蕴含关系。
  3. 为抽象术语提供一个贴合论文的具体例子。代码论文可用“单元测试给代码打分”,Agent 论文可用“一次 rollout 中模型调用工具并接收环境反馈”。例子必须服从一手来源,不虚构实验结果。
  4. 公式前先交代变量对应的对象和实验条件;公式后逐项解释符号、下标、上标、算子、概率条件和统计口径。解释性重构公式必须标注为编者重构,不得写成论文原式。
  5. 含公式的技术报告/论文解读,必须在文档标题之后、正文之前放置「符号速查表」,列出全文涉及的所有数学符号、希腊字母、上下标和算子,每项给出读法(拼音/英文音译)和含义。不得让读者在正文中首次遇到符号时才去猜测其含义。符号表随正文深化同步更新,新增符号必须补入表中。纯无公式的科普/新闻类解读不强制要求。
  6. 首次出现的缩写和实验术语必须展开,例如 RLVR、SFT、SDF、checkpoint、rollout、model organism、LoRA、token、baseline、positive control。面向非专业读者时补充中文名称和一句具体定义。
  7. 使用客观、直接、可核验的陈述。避免问答式标题、口号、拟人化和模板化 AI 语言,尤其避免反复使用“不是……而是……”“真正重要的是”“本质上”“简单来说”“换句话说”“读心术”“内心目标”“这就是……的核心含义”等句型。需要表达边界时,分别写清“证据支持什么”和“证据尚不支持什么”。
  8. 不用“讨好、欺骗、想要、知道”等拟人词替代可观测量;确需使用时,随后给出操作化定义,例如“讨好 Grader”具体指交换 Grader 偏好信念后,输出特征率向 Grader 偏好方向变化。
  9. 完稿后扫描上述模板词和未定义英文缩写。逐条判断保留是否必要;章节标题优先采用“术语与实验角色”“方法定义”“实验设置”“结果”“限制”等陈述式名称。

推荐结构:

<语义化外层目录>/
├── <原始标题>.md                 # 原文离线版,不做深度改写
├── <原始标题>-解读版.md          # 二次技术解读
├── assets/                       # 原文素材
├── analysis-assets/              # 解读新增素材,可按需要创建
└── references/                   # 论文、报告等一手证据

已有技术解读:允许在原解读上持续深化

如果输入本身已经是技术分析、论文解读、研究笔记或持续维护的论文合集,例如“Foundation Models 论文解读合集”,无需机械复制出第二份解读版。可以在原解读文档上继续补充、纠错和深化,但须满足:

  1. 能确认它是“解读/知识工程产物”,而不是唯一的来源原文副本。
  2. 保留来源 URL、本地原始材料、论文 PDF/版本和原图等证据链,不把二手解释伪装成原文。
  3. 对重大改写使用 Git 历史、独立原文快照或同目录归档文件保证可追溯。
  4. 明确区分论文事实、原作者观点、转引结果与编者推断。
  5. 用户只要求归档时不要自动扩写;用户要求“整理、总结、深化、解读”时才进入增强流程。

判断不清时采用保守策略:保留当前文件作为原文,再新建解读版,不覆盖唯一来源副本。

知识库语义命名(抓取后必做)

先决定唯一正文落点

不按文档中出现的所有主题复制多份。先按“来源原文 / 通用解读 / 项目事实”选一个 canonical 落点,其他身份通过 README 或专题索引回链:

材料身份 canonical 落点 处理
飞书 docx/wiki 原文 feishu-internal/ 保留来源和原始结构;即使与当前项目强相关,也不把原文搬进项目笔记
ByteTech/公众号/论文等通用技术解读 bytetech-community/ 按论文解读、框架调研、讲座等主题归类
用户主要负责项目的设计、实验、进展、决策和结果 project-notes/<项目>/<工作线>/ 直接进具体工作线,不用“历史实验”或整包 onboarding 作为默认容器
通用工程操作手册 engineering-basics/ 仅放不绑定某个业务项目的稳定能力
公司行政、财务、HR company/ 不与技术平台或项目资料混放

项目文档同时也是算法分享时,以“是否包含该项目的私有数据、路径、决策或结果”判断:有则正文归项目,在通用方法目录建链接;无则正文归通用方法,在项目 README 建链接。

Onboarding 主要用来临时记录进程时,默认提取其中的具体设计、实验、运行手册和决策到对应工作线,删去重复概览、新会话提示词和归并元文档。只有用户明确需要审计、合规或按时点还原时,才保留整份快照。

对大型论文解读合集及其成百上千个链接文档,保留一份完整语料镜像,另建主题精选索引。不按项目复制原文;项目只保留独立落地分析与回链。

不要直接沿用新闻稿、公众号或社区文章的传播标题作为知识目录名。遇到“重磅、超越、性能直逼、万字长文、玄学、某某之父、终于”等新闻化或营销化标题时,阅读正文并核验一手来源后,改成可检索的知识索引:

时间 - 方法/框架/主题 - 一个主要提出者或研究组织 - 在什么领域完成什么事

示例:

260721 - Contrastive SDF - OpenAI - 测量RL模型Reward-Seeking
260707 - LLM-as-a-Verifier - Stanford - 用连续评分扩展Agent验证
2607 - Codex Context Compaction - ByteTech调研 - 解析多轮上下文压缩与状态恢复

执行要求:

  1. 时间放最前面;论文使用首次公开或当前归档版本日期,官方研究使用官方发布日期,产品或工程文章使用研究/发布时点,不用转载日期冒充研究日期。
  2. 日期使用无连字符的紧凑格式:证据到日时写 YYMMDD(如 260721),只能确认月份时写 YYMM(如 2607),只能确认年份时写 YY(如 26);不得猜测缺失精度。
  3. 方法名优先保留官方英文名或公认简称。机构或创建者只写一个:优先选最知名、最能识别该工作的主体;若无法判断,则使用新闻正文中第一个出现的相关机构或创建者。避免并列多个机构,也避免“某大佬”“中国团队”等宣传称谓。
  4. 末段用一个短语说明知识贡献,优先写机制和问题,例如“测量RL模型Reward-Seeking”,不要写“全面超越某模型”。
  5. 普通教程、规范、产品说明若没有明确方法、提出者或研究时间,可省略不适用字段,不要为了套公式制造元数据。
  6. 只重命名外层输出目录。不要修改目录内部任何文件名,也不要为了匹配目录名修改 H1、正文、图片、PDF或其他文件内容;内部归档须保留原始标题和结构。
  7. 正文保留原始来源标题和 URL,必要时注明“原文标题”,以保留溯源信息。

Browser mode(低干扰可见内容提取)

当用户已在浏览器中登录并打开有权限访问的飞书 docx/wiki 页面,且希望避免 API/素材下载接口时,用:

python3 ~/.agents/skills/knowledge2md/scripts/knowledge2md.py "<lark docx/wiki url>" --mode browser --cdp-url http://127.0.0.1:9222

也可直接运行:

python3 ~/.agents/skills/knowledge2md/scripts/browser2md.py "<lark docx/wiki url>" --cdp-url http://127.0.0.1:9222

browser mode 的权限边界:

  • 只处理当前浏览器页面中用户正常可见、已渲染的正文和目录内容。
  • 自动滚动页面以触发懒加载,但不伪造请求、不绕过访问控制、不规避审计或风控。
  • 图片优先按已渲染 DOM 元素位置截图保存到 assets/img-NNN.png;截图失败时写 assets/IMAGE_PLACEHOLDER_NNN.txt 并在 Markdown 中保留占位符。
  • 不主动下载视频或大附件,仅保留页面中可见链接/文本。
  • 不调用 lark-cli docs/wiki/media 下载接口;输出目录会生成 extraction_meta.json,记录 mode=browser、used_lark_cli=false、used_media_download_api=false、图片数、占位符数和 warnings。

执行流程(agent 操作指引)

  1. 判断输入类型:
    • 是 mp.weixin.qq.com/s/... → 微信分支(wx2md.py),公开网页,不需要 cookie / lark-cli,直接运行。
    • 是 *.notion.site/... → 公开 Notion 分支(notion2md.py),匿名读取;私有页面直接停止,不索要 cookie。
    • 是 larkoffice.com / feishu.cn 的 /docx/ /wiki/ → 直接运行,不需要 cookie。
    • 是 bytetech.info/articles/... → 需要 cookie:先试 --cookie 省略(用缓存);若脚本报「cookie 失效/过期」,按下方引导用户重新抓 cookie。
    • 用户明确要求 browser mode / 当前浏览器页面提取 / 低干扰提取 → 使用 --mode browser,优先连接当前 Codex Desktop 浏览器;若在命令行脚本中执行,则连接当前 Chrome/CDP。
  2. 运行脚本(图片 authcode 有 ~1 小时时效,拿到就立即下,勿拖延)。 用户明确说“不需要视频”时传 --skip-videos,不得先下载视频再删除。
  3. 判断产物类型:来源原文先完整归档,再按用户需求另建解读版;已有技术解读在有深化请求时可原位增强并保留证据链。
  4. 语义命名:按“时间 - 方法/框架/主题 - 一个主要提出者或研究组织 - 在什么领域完成什么事”只整理外层目录;内部原文文件名和内容保持原样。
  5. 核对产物:残留远程引用应全部为 0(飞书源查 internal-api-drive-stream authcode URL、/file/<token> 内嵌图、<whiteboard>、<figure>;微信源查 mmbiz.qpic.cn、data-src),assets/ 引用数 = 素材数;本地相对链接缺失数为 0;解读版必须回链原文。
  6. 汇报:分别给出原文离线版与解读版路径(若生成)、素材数量、原文标题与 tag。

browser mode 汇报时改为给出:md_path、图片数量、占位符数量、是否使用 lark-cli、是否使用 media download API、主要 warnings。

让用户提供 bytetech cookie(仅 bytetech 链接 + 无有效缓存时)

引导用户在浏览器(已登录 bytetech):

  1. F12 → Network → 点 Fetch/XHR → Filter 框输入 detail → 刷新页面
  2. 找到 proxy_tech_api/v1/article/detail 这条 → 右键 → Copy → Copy as cURL
  3. 把整段粘贴给我;我从中取出 cookie: 头作为 --cookie 传入。

⚠️ cookie 是临时登录凭证,用完缓存于本机 skill 目录(chmod 600)。用户可自行登出使其失效。

备选路径(cookie 麻烦时)

bytetech 文章页通常能找到「飞书文档 / 原文」链接。让用户直接给那个 larkoffice.com/docx/... 链接, 本技能无需 cookie即可一步到位。

微信图片高清化(找原图)

微信 CDN 会把插图重编码压缩(常只剩 ~1080px 宽 JPEG),分类树、表格这类小字密集图基本不可读。 转换论文解读类文章时,不要满足于微信版图,应主动找论文原图替换,优先级:

  1. arXiv 源文件(首选):curl -L https://arxiv.org/e-print/<id> 解包后 fig/ 里通常是矢量 PDF, 用 pdftoppm -png -r 300 -singlefile fig/x.pdf x 渲染(大图 200 DPI),再自动裁白边(PIL 或复用 knowledge2md.py 的 crop_white_margins)。
  2. TeX 排版的表格/算法/分类树(不在 fig/ 里):用 pdftotext -f N -l N 定位所在页码, pdftoppm -r 300 -f N -l N 渲染整页后按区域裁剪。注意边缘渗漏:栏外正文文字混进裁剪框时收紧框线,逐张目检。
  3. 项目页 / 官方 GitHub / 作者博客的原图。

操作要点:

  • 逐张建立「微信图 ↔ 论文图/表号」映射(按图注和目视比对),替换后更新 md 引用(.jpg→.png 等)。
  • 含公众号自有标注的图(红框、箭头等)保留原样,不替换。
  • 宽图等比缩到 ≤2600px 控制体积;全部过 sips --verify;在文档头部校注里注明图片来源已替换。
  • 论文 PDF 同时归档到文档目录 references/,并在头部注明版本(arXiv id + v 版本 + 日期)。

已知边界 / 可扩展点

  • 当前知识源:ByteTech + 飞书 docx/wiki + 微信公众号(公开文章)+ 公开 Notion 页面。要支持新站点,只需新增「URL → 飞书文档链接 + 标题」的解析分支,或像 wx2md.py / notion2md.py 一样加独立抓取分支。
  • Notion 分支(notion2md.py):只导出匿名可读的公开页面;支持常见正文、标题、列表、代码、Mermaid、callout 和图片。数据库视图、嵌入应用及其他未知块会保留明确占位和 warning,不伪装成完整导出。
  • 微信分支(wx2md.py):只依赖 curl + Python 标准库;图片带 Referer: https://mp.weixin.qq.com/ 下载,扩展名按 magic bytes 判定;HTML→MD 为内建轻量转换(html.parser),覆盖公众号正文常见标签,复杂嵌套结构会降级为纯文本;视频/iframe 保留为链接占位。微信对频繁抓取有风控,失败时隔几分钟重试。
  • 素材:authcode 图片用 curl 直下;docx 内嵌图(渲染成 /file/<token>)用 lark-cli docs +media-preview(这类 token 走 +media-download 常 403);画板用 lark-cli docs +media-download --type whiteboard,下载后自动裁掉飞书 2560×2560 白画布边缘,避免 Markdown 预览出现大段空白;视频(figure/source)按链接下载,文件较大属正常。
  • Browser mode 是可回退的低干扰提取,不保证达到 API 完整导出的图文完整度;复杂飞书富文本、折叠块、未进入视口的虚拟列表内容、跨域 iframe 和无法稳定截图的图片会以占位符或 warning 表达。
  • 飞书富 block(callout/grid/bookmark/blockquote)已做轻量清洗为标准 Markdown;表格保留原样(pipe / HTML 均可渲染)。
  • 依赖:curl、python3、已登录 user 身份的 lark-cli(见 ../lark-shared/SKILL.md)。