1. 这套组合到底在解决什么问题飞书里沉淀的东西太多了。文档、多维表格、聊天记录里的决策片段、会议纪要、知识库页面甚至评论区里某个人随手写的一句关键结论。这些东西散落在不同空间里想批量拿出来做二次加工传统做法要么手动复制粘贴要么走开放平台接口写一堆鉴权代码。前者费人后者费时间而且飞书开放平台的权限申请流程对个人开发者并不友好很多人卡在“没有CLI权限”这一步就放弃了。WorkBuddy加仓颉.Skill 2.5这套组合核心思路是把“取内容”和“炼内容”拆成两段。WorkBuddy负责跟飞书打交道把散落的内容抓出来仓颉.Skill负责把抓出来的原始素材做结构化蒸馏变成可以直接用的知识单元。整个链路不需要你懂飞书开放平台的OAuth流程也不需要自己维护一套爬虫脚本。我第一次接触这个组合是在整理一个跨部门项目的知识库时。当时手头有四十多篇飞书文档、三个多维表格、还有一堆群聊里零散的需求变更记录。手动整理了两天之后我放弃了转而研究自动化方案。试过直接调飞书API卡在权限审批上试过用浏览器插件导出格式乱得没法看。后来在社区里看到有人提到WorkBuddy配合仓颉.Skill做内容蒸馏抱着试试看的心态搭了一遍结果四十分钟跑完了我两天没干完的活。这篇文章适合三类人看一是手里有大量飞书内容需要批量处理的知识管理者二是想搭建个人知识库但不想写太多代码的独立开发者三是对“蒸馏”这个概念感兴趣、想知道怎么把非结构化内容变成结构化知识的人。不需要你有很深的编程基础但需要你能看懂基本的命令行操作和配置文件格式。2. 核心概念拆解WorkBuddy、仓颉.Skill和蒸馏分别是什么2.1 WorkBuddy的角色定位WorkBuddy在这个链路里扮演的是“搬运工”加“适配器”的角色。它本身不是一个飞书官方工具而是一个第三方的内容桥接工具支持把飞书里的文档、表格、知识库页面等内容抓取到本地或指定的存储位置。它的价值在于绕开了飞书开放平台那套复杂的应用注册和权限审批流程用更轻量的方式拿到你需要的内容。WorkBuddy有国际版和国内版之分功能上大同小异主要区别在于默认的存储端点和部分配置项。安装方式支持Windows、Linux和macOSLinux下通常以命令行工具的形式运行Windows下则有图形界面和命令行两种模式。我个人的习惯是在Linux环境下用命令行跑因为方便跟后续的仓颉.Skill做管道衔接。它的核心能力包括指定飞书文档链接批量抓取、按知识库空间遍历、按多维表格视图导出、以及把抓取结果输出为Markdown、JSON或纯文本格式。输出格式的选择很关键后面会详细说。2.2 仓颉.Skill 2.5在做什么仓颉.Skill是一个内容蒸馏工具2.5版本在蒸馏精度和脚本扩展性上做了比较大的改进。所谓“蒸馏”在这里不是指模型压缩里的知识蒸馏而是指把大段非结构化的原始文本提炼成结构化的、信息密度更高的知识单元。你可以把它理解成一个“智能摘要加结构化重组”的工具。举个例子。一篇三千字的飞书会议纪要里面有讨论、有决策、有待办事项、有背景信息。仓颉.Skill 2.5跑完之后输出的可能是三条决策记录、五个待办事项带负责人和截止日期、一段背景摘要、以及若干条关键结论。每条内容都带来源标记方便回溯。2.5版本相比之前的主要变化有三个一是支持自定义蒸馏脚本你可以用Python写自己的蒸馏逻辑二是对中文语义的切分更准确了尤其是对飞书文档里常见的多级标题和嵌套列表处理得更好三是增加了“蒸馏模板”的概念你可以针对不同类型的飞书内容会议纪要、需求文档、知识库页面预设不同的蒸馏策略。2.3 “蒸馏”在这个场景下的具体含义很多人第一次听到“蒸馏”会联想到模型训练里的知识蒸馏那是把一个大型模型的能力迁移到小型模型上。但在这个场景里蒸馏的含义更接近“信息提纯”。原始内容里有很多冗余重复的表述、无关的寒暄、格式噪音、上下文依赖的指代。蒸馏就是把这些去掉保留核心信息并且按照你预设的结构重新组织。我习惯把蒸馏分成三个层次。第一层是“去噪”把格式标记、页眉页脚、无关评论去掉。第二层是“提纯”识别出关键信息块比如决策、待办、数据、结论。第三层是“重组”按照你定义的结构把提纯后的内容重新排列输出成可以直接入库的格式。仓颉.Skill 2.5在这三个层次上都有对应的配置项。去噪层可以配置忽略规则提纯层可以配置识别规则重组层可以配置输出模板。理解这三层结构后面配置的时候就不会晕。3. 环境准备与工具安装从零把链路搭起来3.1 WorkBuddy的安装与初始化配置WorkBuddy的安装方式取决于你的操作系统。Linux下推荐用官方提供的安装脚本Windows下可以直接下载安装包。我以Linux环境为例说明因为这是最常用的部署方式。安装完成后第一步是初始化配置。WorkBuddy需要一个配置文件来指定飞书账号的认证信息、默认的输出目录、以及抓取时的并发数等参数。配置文件通常是YAML格式放在用户目录下的.workbuddy文件夹里。# ~/.workbuddy/config.yaml feishu: auth_type: token token: 你的飞书访问令牌 base_url: https://open.feishu.cn output: default_dir: ./workbuddy_output format: markdown overwrite: true fetch: concurrency: 3 timeout: 30 retry: 2这里有几个关键参数需要解释。auth_type指定认证方式WorkBuddy支持token和cookie两种模式token模式更稳定但需要你从飞书网页端手动获取一次。concurrency控制并发抓取数设太高容易被限流设太低速度慢3到5之间是比较稳妥的范围。timeout是单个请求的超时时间飞书文档如果内容很多加载时间会比较长30秒是个保守值。注意token是有有效期的通常几天到几周不等。如果抓取时报认证失败第一件事就是检查token是否过期。WorkBuddy本身不提供自动刷新token的功能需要你手动更新。初始化完成后可以用一个简单的命令测试连通性workbuddy test-connection如果返回成功说明配置没问题。如果报错根据错误码排查401通常是token问题403是权限问题404是URL写错了。3.2 仓颉.Skill 2.5的部署与依赖安装仓颉.Skill 2.5是一个Python工具包安装方式比较直接。推荐用虚拟环境安装避免跟系统Python的依赖冲突。python3 -m venv cangjie_env source cangjie_env/bin/activate pip install cangjie-skill2.5.0安装完成后需要初始化蒸馏工作区。仓颉.Skill的工作区结构包括输入目录、输出目录、脚本目录、模板目录。初始化命令会帮你把这些目录建好。cangjie init --workspace ./my_distill_workspace初始化完成后你会看到这样的目录结构my_distill_workspace/ ├── input/ # 放原始素材 ├── output/ # 蒸馏结果输出 ├── scripts/ # 自定义蒸馏脚本 ├── templates/ # 蒸馏模板 └── config.yaml # 工作区配置config.yaml里需要配置几个关键项默认使用的蒸馏模板、输出格式、是否保留中间结果。我一般会把keep_intermediate设为true方便调试蒸馏效果。3.3 两个工具的衔接方式WorkBuddy和仓颉.Skill之间的衔接有两种方式。一种是文件系统衔接WorkBuddy把抓取结果写到某个目录仓颉.Skill从这个目录读。另一种是管道衔接WorkBuddy的输出直接通过标准输入传给仓颉.Skill。前者适合批量处理后者适合单篇快速处理。我推荐用文件系统衔接因为批量处理的时候你可以先检查WorkBuddy抓下来的原始内容有没有问题确认无误再跑蒸馏。如果直接管道衔接中间出了问题不好排查。衔接的关键是输出格式要对齐。WorkBuddy输出Markdown格式仓颉.Skill的输入解析器默认支持Markdown。如果你用JSON格式输出需要在仓颉.Skill的配置里指定输入解析器为JSON。# my_distill_workspace/config.yaml input: parser: markdown encoding: utf-8 output: format: json template: meeting_notes distill: keep_intermediate: true min_block_size: 50min_block_size这个参数值得说一下。它控制最小内容块的大小小于这个字数的块会被合并到相邻块里。设太小会导致碎片化设太大会丢失细节。50到100之间是比较合理的范围具体取决于你的内容类型。4. 实操全流程从飞书抓取到蒸馏输出4.1 第一步确定抓取范围并生成任务清单在跑WorkBuddy之前你需要先明确要抓什么。飞书里的内容形态很多文档、表格、知识库页面、群聊记录每种形态的抓取方式不一样。我的习惯是先列一个任务清单把要抓的URL和对应的输出文件名写清楚。任务清单可以用一个简单的文本文件维护# fetch_list.txt https://xxx.feishu.cn/docx/xxxxx project_overview https://xxx.feishu.cn/docx/xxxxx requirement_spec https://xxx.feishu.cn/base/xxxxx task_tracker https://xxx.feishu.cn/wiki/xxxxx knowledge_base_indexWorkBuddy支持批量读取这个清单然后按顺序抓取。命令如下workbuddy fetch --list fetch_list.txt --output-dir ./raw_content抓取过程中WorkBuddy会在终端显示进度。如果某个URL抓取失败它会记录下来并在最后汇总。我一般会先跑一遍看看哪些失败了手动处理失败项再跑第二遍。实操心得飞书文档的URL格式有好几种docx、docs、wiki、base分别对应不同类型的文档。WorkBuddy对docx和wiki的支持最好base多维表格的支持稍弱一些复杂视图可能需要手动调整。如果抓取多维表格时发现数据不全先检查视图筛选条件是不是被WorkBuddy忽略了。4.2 第二步原始内容的预处理与清洗WorkBuddy抓下来的原始内容通常带有一些噪音页面的导航文字、评论区内容、格式标记残留。这些噪音如果不处理会直接影响蒸馏效果。仓颉.Skill 2.5内置了一个预处理模块可以在蒸馏之前做一轮清洗。预处理配置在config.yaml的preprocess段preprocess: remove_nav: true remove_comments: true normalize_headings: true strip_empty_lines: true max_line_length: 200remove_nav去掉页面导航文字remove_comments去掉评论区内容normalize_headings把不同级别的标题统一成标准Markdown格式strip_empty_lines去掉多余空行max_line_length控制单行最大长度超过的会被换行。预处理跑完之后建议人工抽查几篇看看清洗效果。我遇到过一种情况飞书文档里的代码块被预处理模块误判为导航文字删掉了。后来在配置里加了preserve_code_blocks: true才解决。4.3 第三步配置蒸馏模板蒸馏模板决定了输出内容的结构。仓颉.Skill 2.5内置了几种常用模板会议纪要模板、需求文档模板、知识库页面模板、通用摘要模板。你也可以自定义模板。以会议纪要模板为例它的结构定义大概是这样的# templates/meeting_notes.yaml name: 会议纪要 sections: - key: decisions label: 决策记录 type: list extractor: decision_pattern - key: action_items label: 待办事项 type: table columns: [事项, 负责人, 截止日期] extractor: action_pattern - key: background label: 背景摘要 type: text max_length: 300 - key: key_points label: 关键结论 type: list extractor: conclusion_pattern每个section对应输出里的一个部分。extractor指定用哪个提取器来识别这类内容。仓颉.Skill 2.5内置了十几种提取器覆盖了决策、待办、结论、数据、风险等常见类型。如果内置提取器不够用可以在scripts/目录下写自定义提取器。自定义提取器就是一个Python函数输入是原始文本块输出是提取到的内容列表。比如你想提取所有带“注意”字样的句子# scripts/custom_extractor.py def extract_attention_blocks(text): results [] for line in text.split(\n): if 注意 in line: results.append(line.strip()) return results然后在模板里引用这个提取器- key: attention label: 注意事项 type: list extractor: custom:extract_attention_blocks4.4 第四步执行蒸馏并检查输出配置好之后执行蒸馏命令cangjie distill --input ./raw_content --output ./distilled --template meeting_notes仓颉.Skill会遍历输入目录下的所有文件逐个跑蒸馏然后把结果写到输出目录。输出格式默认是JSON每个输入文件对应一个JSON文件文件名跟输入文件名一致。蒸馏过程中会在终端显示每个文件的处理状态。如果某个文件蒸馏失败会显示错误信息。常见的失败原因包括输入文件为空、模板配置有误、自定义提取器报错。蒸馏完成后我建议先看几个输出文件检查蒸馏质量。重点看三个方面一是提取到的内容是否完整有没有漏掉关键信息二是提取到的内容是否准确有没有把不相关的内容混进来三是结构是否符合预期各个section的内容有没有放错位置。如果发现质量问题调整模板配置或提取器逻辑然后重新跑。仓颉.Skill支持增量蒸馏已经处理过的文件如果没变化不会重复处理。5. 常见问题与排查技巧实录5.1 WorkBuddy抓取失败的几种典型情况抓取失败是最高频的问题。根据我的经验失败原因可以归为几类每类的排查思路不一样。错误现象可能原因排查方法解决方式401 Unauthorizedtoken过期或无效检查token有效期重新获取token并更新配置403 Forbidden没有该文档的访问权限确认账号是否有权限联系文档所有者开通权限404 Not FoundURL错误或文档已删除手动打开URL验证修正URL或移除该任务超时无响应文档过大或网络问题单独抓取该文档测试增大timeout值或降低并发数内容为空文档是动态加载的检查抓取结果改用其他抓取模式或手动导出其中“内容为空”这种情况最隐蔽。飞书有些文档是动态加载的WorkBuddy的默认抓取模式拿不到内容。这时候需要在配置里把fetch_mode改成render让它用渲染模式抓取。渲染模式速度慢一些但能拿到动态内容。踩过的坑有一次抓一个多维表格抓下来发现只有表头没有数据。排查了半天才发现那个表格用了筛选视图WorkBuddy默认抓的是主视图而主视图恰好是空的。后来在URL里加上视图参数才解决。所以抓多维表格的时候一定要确认URL里带的是哪个视图。5.2 蒸馏结果不理想的调整思路蒸馏结果不理想通常表现为该提取的没提取到、提取到的内容不准确、输出结构混乱。这三种情况的调整方向不一样。该提取的没提取到一般是提取器的识别规则太严格。仓颉.Skill 2.5的提取器基于模式匹配加语义判断如果原文的表述方式跟提取器的预期差异较大就会漏掉。解决办法是放宽提取器的匹配条件或者在自定义提取器里补充针对性的规则。提取到的内容不准确通常是提取器的识别规则太宽松把不相关的内容也抓进来了。这时候需要收紧匹配条件或者增加排除规则。比如待办事项提取器默认会把所有带“需要”“应该”“必须”的句子都抓进来但有些句子只是表达观点而不是真正的待办。可以在配置里加一个exclude_patterns列表把常见的误判模式排除掉。输出结构混乱一般是模板配置的问题。检查各个section的type和extractor是否匹配max_length是否设置合理。有时候两个section的提取器会抓到重叠的内容导致同一段文字出现在多个地方。这时候需要调整提取器的优先级或者给提取器加上互斥条件。5.3 性能优化大批量处理时怎么提速当你要处理几百上千篇文档时性能就成了瓶颈。WorkBuddy的抓取速度和仓颉.Skill的蒸馏速度都可以优化。WorkBuddy这边主要调两个参数concurrency和batch_size。concurrency控制并发请求数但飞书服务端有限流设太高反而会触发限流导致整体变慢。我的经验值是3到5之间具体取决于你的网络环境和账号等级。batch_size控制每批处理的文档数设大一些可以减少批次间的等待时间。仓颉.Skill这边蒸馏是CPU密集型操作主要靠多进程并行来提速。在配置里设置workers参数distill: workers: 4 batch_size: 20workers设成CPU核心数的一半到三分之二比较合适。设太高会因为进程切换开销导致效率下降。batch_size控制每批处理的文件数设大一些可以减少I/O等待。另外如果输入文件很多但内容重复度高可以开启去重模式。仓颉.Skill 2.5支持基于内容哈希的去重相同的文档只会蒸馏一次。distill: dedup: true dedup_threshold: 0.95dedup_threshold是相似度阈值0.95表示95%以上相似的内容会被视为重复。这个值设太低会误删不同但相似的内容设太高又起不到去重效果。0.9到0.95之间是比较稳妥的范围。5.4 输出内容的后续利用方式蒸馏输出的JSON文件可以直接导入各种知识管理工具。我常用的几种方式导入Notion仓颉.Skill输出的JSON结构跟Notion的数据库结构比较接近写一个简单的转换脚本就能批量导入。关键是字段映射把蒸馏输出的section key映射到Notion数据库的property。导入ObsidianObsidian支持Markdown格式所以需要把JSON转成Markdown。仓颉.Skill内置了一个Markdown输出模板可以直接用。导入自建知识库如果你有自己的知识库系统蒸馏输出的JSON可以直接作为数据源。我一般会把蒸馏结果存到SQLite里然后用全文检索做查询。一个小技巧蒸馏输出的JSON里每条内容都带source字段记录了来源文档的URL和位置信息。导入其他系统时保留这个字段以后回溯原始内容会方便很多。我吃过亏有一次把来源信息丢了后来想查某条决策的上下文翻了半天才找到原始文档。6. 进阶玩法自定义蒸馏脚本与模板扩展6.1 用Python写一个针对特定文档类型的蒸馏脚本内置模板覆盖了常见场景但如果你处理的文档类型比较特殊就需要写自定义脚本。仓颉.Skill 2.5的脚本接口设计得比较友好一个蒸馏脚本本质上就是一个Python类实现几个约定的方法。# scripts/tech_doc_distiller.py from cangjie.distiller import BaseDistiller class TechDocDistiller(BaseDistiller): def preprocess(self, text): # 去掉技术文档里常见的版本号标注 import re text re.sub(rv\d\.\d\.\d, , text) return text def extract(self, text): sections {} sections[api_changes] self._extract_api_changes(text) sections[breaking_changes] self._extract_breaking_changes(text) sections[migration_guide] self._extract_migration(text) return sections def _extract_api_changes(self, text): # 自定义提取逻辑 pass def _extract_breaking_changes(self, text): pass def _extract_migration(self, text): pass写完之后在模板里引用这个脚本name: 技术文档 distiller: scripts/tech_doc_distiller.py:TechDocDistiller这个脚本的好处是你可以完全控制蒸馏逻辑不受内置提取器的限制。代价是需要自己处理边界情况比如空输入、格式异常等。6.2 模板继承与组合仓颉.Skill 2.5支持模板继承你可以基于一个基础模板派生出多个变体。比如你有一个通用的“文档模板”然后派生出“会议纪要模板”和“需求文档模板”两者共享通用部分只覆盖差异部分。# templates/base_doc.yaml name: 基础文档 sections: - key: summary label: 摘要 type: text max_length: 200 - key: key_points label: 要点 type: list # templates/meeting_notes.yaml inherit: base_doc name: 会议纪要 sections: - key: decisions label: 决策 type: list - key: action_items label: 待办 type: table继承的时候子模板的sections会跟父模板的sections合并。如果key相同子模板覆盖父模板。这个机制在维护多个相似模板时特别有用改一处就能影响所有派生模板。6.3 把蒸馏结果接入自动化工作流蒸馏只是中间步骤最终目的是让蒸馏结果自动流转到你需要的地方。我自己的做法是用一个简单的调度脚本把WorkBuddy抓取、仓颉.Skill蒸馏、结果导入这三个步骤串起来定时执行。#!/bin/bash # daily_sync.sh # 第一步抓取 workbuddy fetch --list fetch_list.txt --output-dir ./raw_content # 第二步蒸馏 source cangjie_env/bin/activate cangjie distill --input ./raw_content --output ./distilled --template meeting_notes # 第三步导入知识库 python import_to_kb.py --input ./distilled --target sqlite:///knowledge.db然后用crontab设置每天定时执行0 8 * * * /path/to/daily_sync.sh /var/log/sync.log 21这样每天早上八点自动跑一遍你到工位的时候蒸馏结果已经躺在知识库里了。注意定时任务里跑的时候环境变量可能跟交互式终端不一样。特别是Python虚拟环境的激活最好在脚本里写绝对路径不要依赖source命令的默认行为。我因为这个踩过坑手动跑没问题放到crontab里就报模块找不到。7. 关于这套组合的一些个人体会这套组合我用了大概三个月处理了上千篇飞书文档。最大的感受是它把“整理知识”这件事从体力活变成了配置活。前期花时间把模板和脚本调好后面就是自动化运行边际成本几乎为零。但有几个地方需要提前有心理预期。一是飞书的内容形态在变WorkBuddy的适配不一定能第一时间跟上遇到抓取异常要有手动处理的预案。二是蒸馏质量高度依赖模板配置没有一套模板能通吃所有文档类型需要针对不同场景分别调优。三是这套组合毕竟不是官方工具稳定性和长期维护性需要自己评估重要数据建议保留原始抓取结果作为备份。如果你刚开始接触我的建议是先拿十篇左右的文档跑通全流程把每个环节都摸一遍再逐步扩大规模。不要一上来就导入几百篇出了问题排查起来会很痛苦。先跑通再跑量最后跑自动化这个节奏比较稳妥。