1. 这次想做的事情是什么
1.1 痛点：手动搬运内容到底有多烦
作为一个常年在飞书写稿的人，我一直被一个问题卡着：稿子写完之后，怎么同步到公众号、CSDN、知乎这几个平台。刚开始是复制粘贴，后来发现复制粘贴根本不是“复制粘贴”这么简单，我在飞书里排得整整齐齐的标题、列表、代码块、表格，一到公众号编辑后台就散架了。标题层级丢了，列表缩进乱了，表格粘贴过去经常变成一堆看不懂的HTML碎片。CSDN倒是支持Markdown，但飞书导出的Markdown跟CSDN的编辑器又有兼容性问题，最典型的就是图片转存失败，飞书图片链接在CSDN上根本加载不出来。知乎就更麻烦，直接粘贴飞书的内容，格式基本全丢，还需要重新配图、重新调整标题层级，一次手动搬家，快的话二十分钟，慢的话四十分钟。
这个痛点持续了大概两个月，我终于决定做点什么。我的想法很直接：既然每次都要做同样的事情，不如写一个“内容分发管理器”，把飞书当作内容源头，一键把文章分发到公众号、CSDN、知乎。当时把这个想法跟几个朋友聊了聊，有人觉得可行，有人劝我别折腾。我属于那种不撞南墙不回头的人，于是就开始动手了。
1.2 理想中的自动化流程
我最初画了一个非常理想化的流程：
飞书写文章 → 脚本自动拉取文档内容 → 转换成各平台需要的格式 → 自动发布到三个平台 → 回传发布链接
这个流程看起来很顺滑，实际操作起来涉及的东西远超预期。首先我要想办法从飞书取到内容，然后把飞书的块结构转成通用的Markdown，再把Markdown分别转成公众号能接受的HTML、CSDN能直接导入的Markdown，以及知乎需要的富文本格式。每个平台的接口各不相同，公众号要先去申请开发者权限，CSDN需要找到它的发布接口，知乎那边则完全是另一个次元的问题。
我当时对自动化的理解其实存在一个根本性的假设错误：我默认“内容是一样的，只是发布衔接不同”。但我后来才意识到，内容分发不是转发，而是再排版。公众号、CSDN、知乎这三个平台的读者群体不同，内容调性、排版风格、图片要求都有差异。同一个标题放公众号可能需要更口语化，放CSDN则需要带上明显的技术关键词。这不是一个脚本能解决的问题。
1.3 技术方案选型背后的考虑
技术选型上，我几乎没有犹豫就选了Python。原因很简单：生态好，第三方SDK齐全，不管是飞书还是公众号，都有现成的SDK封装，省去了自己拼签名、算时间戳的麻烦。Node.js和Go当然也能做，但Python在处理文本转换、Markdown解析、HTML生成这块明显更有优势，可以说是一抓一大把现成的库。
在自动化方式上，我考虑过RPA那种模拟鼠标键盘的方式，但是很快就放弃了。原因也很现实：RPA方案太脆了，平台前端一改版，脚本就废了，而且发布时一旦网络卡顿、弹窗提示、验证码弹出，完全没法处理。用API虽然有各种权限限制和渠道门槛，至少逻辑是稳定的。
所以整体架构就是：Python脚本 + 各平台开放API + 中间转格式模块。核心数据格式选Markdown，因为从飞书拉下来的内容可以转成Markdown，而Markdown再到各平台做渲染，理论上最接近我们日常写作习惯。
2. 飞书侧接入：第一道坎就差点劝退
2.1 创建应用和申请权限的细节
飞书接入的第一步是在飞书开放平台创建一个企业自建应用。这个流程本身并不难，填个应用名称、描述，上传个图标就能建起来。但真正的坑在权限申请环节。
要读取文档内容，我需要申请两个权限：一个是docx:document，用来读取文档的正文内容；另一个是云空间相关的权限，用来访问文档所在的文件夹。当时我在开放平台后台申请这些权限，提交之后需要管理员在飞书管理后台审批。审批本身等了一天，但真正折腾人的是权限范围和版本发布的限制。飞书开放平台的权限设计是按应用版本管理的，你修改了权限之后，必须发一个新的应用版本，审核通过之后权限才真正生效。也就是说，我改一次权限，就要等一次审核，每次审核间隔少则几个小时，多则一天。整个调试期间，因为权限不足导致的接口报错特别多，很多时候明明代码逻辑已经对了，还是返回“无权限访问”，排查半天才发现是版本没有重新发布。
后来我学到一个经验：在项目一开始就把所有可能用到的权限一次性申请完，不要抱着“用到再申请”的心态。应用权限申请通过后会在开发版本里生效，但你调试时会发现当下用的是正式版本还是测试版本，这个一定要搞清楚。我就是因为混淆了“开发环境”和“正式环境”的权限，白白浪费了一个下午。
2.2 飞书文档的导出和读取：两条路都走了一遍
读取飞书文档内容，我当时调研出两条技术路径。
第一条路径是使用导出接口，把飞书文档导出成Markdown文件，然后下载。这个接口的形式是一个异步任务，调用之后需要主动查询任务状态，等到导出完成再下载文件。听起来很方便，但实践后发现导出的Markdown质量并不理想。飞书导出的Markdown，保留了文档里大部分内容，但会出现很多额外的空行、特殊标记，而且表格的转换方式尤其诡异，导出的表格在其它平台里经常变成行列错乱的代码块。更致命的是，图片没有导出本地文件，而是保留了飞书域名的临时链接，这些链接放到外部平台，要么加载不出来，要么过期失效。
第二条路径是读取飞书文档的Block（块）结构。飞书文档本质上是一棵块树的JSON结构，标题、段落、列表、代码块、图片、表格，每一种内容都对应不同的Block类型。我需要递归遍历所有Block，然后根据Block类型自己组装成Markdown。这条路更灵活，能完全控制内容输出的格式。但代价是工作量巨大。
我当时先试了第一条路径，发现质量和预期差距太大，于是转到第二条路径，结果这一转就让我彻底体会到了什么叫“看似简单，实则复杂”。飞书的Block结构里，嵌套列表是重点难点。一个列表项下面可能有子列表，子列表下还有引用块、代码块，这让我必须处理树的递归。我花了一个晚上才写完第一版转换函数，调试到凌晨两点，看到控制台输出的Markdown基本成型的那一刻，还挺有成就感的。
2.3 飞书块结构里那些预料之外的坑
第一个坑是标题层级。飞书的标题分为标题一、标题二、标题三共三个层级，但每个标题Block包含一个子Block，真实的标题文本在子Block里，转换的时候稍不留神就会输出成普通的段落文本，标题层级信息就丢了。更烦人的是，从飞书文档复制出来的标题，可能会带上自带的序号，如果你在飞书文档里用了“1. 2. 3.”这样的自动编号，导出之后序号和内容会重复。
第二个坑是图片。飞书文档里的图片Block，Alt文本和图注是分开存储的，转成Markdown时需要自己拼图片语法以及可选的图注文本。但图片链接本身存放的是临时地址，大部分情况下，这些链接只在特定时间内有效，一旦超过时效，分发目标平台就会得到一张裂图。因为这个问题，我后来只能单独写一个图片下载模块，把飞书图片下载到本地或图床，然后在转换的时候替换成新的链接，这又是一个额外的工程。
第三个坑是思维导图、流程图这类高级块，它们在飞书里展示很好看，但导出到Markdown之后只剩下一个链接，点击链接跳转到飞书页面，跟内容分发到外部平台的场景格格不入。我在转换器里对这类特殊块做了注释标记，提示自己“这里需要手工处理”，结果就是把这个问题延后了，而不是解决了。
说实话，飞书侧接入花费的精力约占整个项目的四成，我一度以为熬过了最难的部分，后续会顺利很多。但后来的经历很快证明我天真了。
3. 公众号发布：第二道坎，也是第二座山
3.1 公众号API的基本约束和权衡
公众号的接入方式跟飞书完全不是一个路数。飞书开放平台是面向企业应用的，权限和接口都相对透明。公众号虽然也有开发者接口，但它在设计上就把“自动发布”这条路卡得很死。
我的目标用户是个人订阅号，没有支付认证，只能申请订阅号。订阅号的接口权限本来就少，包括“生成草稿”、“发布接口”在内的一些能力，我花了不少时间确认才发现：个人主体订阅号部分接口受到限制，尤其是主动推送接口基本无缘。还有一个硬约束是，即使是已经接入的开发模式，调用接口也必须在白名单IP里配置服务器IP，这意味着如果脚本跑在本地，IP变化一次就要重新配置一次，非常痛苦。
还有access_token有效期的问题。公众号的access_token有效期是两小时，而且获取接口有频率限制。本来以为这不是什么大事，但在处理图片素材上传、正文HTML生成、草稿创建这些步骤时，如果每个步骤都各自获取一次token，很容易中途就把配额耗完，而且刷新token的并发问题也会导致后面的请求拿着过期token报错。这个问题的标准做法是用一个全局缓存，每次取token时先判断是否过期，过期了再刷新。可正因为这个机制，我写的第一版代码在调试时频繁报401错误，排查了几次才发现是缓存失效逻辑写反了。
3.2 草稿箱、图文素材和封面的连环坑
公众号发布内容最核心的接口是“新增图文草稿”，调用它需要三样东西：正文HTML、标题和封面图的media_id。正文要的是HTML，这意味着我得把Markdown转成HTML。这一步本身倒不难，Python的markdown库就能完成。但公众号编辑器支持的HTML标签是有限集合，JavaScript脚本全部不允许，部分CSS样式也会被过滤。代码块高亮需要额外引入样式和类名，否则发出去代码块就是白底黑字，阅读体验很糟糕。表格的HTML需要加上特定样式才能正常显示边框，而图片则必须用公众号的域名，或者转为material_id形式。也就是说，正文里的每一张图，都要先通过素材管理接口上传，得到media_id，再把素材URL放到正文里。这一套流程如果遇到一篇二十多张图的文章，处理时间肉眼可见地变长。
封面图是另一个隐蔽的坑。封面图在飞书文档里往往就是最上面一张图，但公众号的封面要求有大小比例，通常建议900x500或者2.35:1的比例。我的脚本里做了自动裁剪，但经常把人物脸裁没了，或者把代码截图裁掉一半，最后只能回到编辑器里手动调整封面。一旦有了手动操作，“全自动分发”的愿景就破灭了。
3.3 “自动发布”在公众号上很难是真的
最让我崩溃的，是我整理完所有逻辑、接口也调通之后才发现：就算我成功把内容投递到了草稿箱，真正的发布动作仍然需要人工到后台点一下“群发”。公众号开放平台确实提供了群发接口，但对订阅号来说，每天只能群发一次，并且群发本身还有原创性校验、敏感词审核、失败后当日不能重发等一系列潜在风险。像我这个项目，脚本一天跑一次，还是需要有人盯着，并不能做到真正的全自动化。
到最后，我对公众号的目标做了一个降级处理：不再追求自动群发，只做到“自动生成草稿并填入正文、标题、封面”，剩下的点按钮动作由人工完成。这一步虽然缩小了目标，但至少让前面写的代码没有完全白费。
4. CSDN 与知乎：平台差异是终极考验
4.1 CSDN接入：原本以为最省心，结果还是踩坑
CSDN是三个平台里最接近开发者习惯的一个，因为它原生支持Markdown发布，我的飞书转Markdown输出理论上可以直接用它。实践起来，CSDN的编辑器对Markdown的方言限制让我重新理解了“兼容”这个词。
CSDN的Markdown解析器支持的是CommonMark标准的一个子集，但不是完整支持。比如飞书文档里常用的==高亮==语法，CSDN不支持；markdown标准的表格语法倒是支持，但要求表格前后必须有空行，否则不渲染；代码块的语言标识符，CSDN只认自己列表里的那几十种，我传一个rust，它也能识别，但我传一个text，有时候会莫名加上奇怪的类名。最麻烦的还是目录标签：CSDN会自动提取你的标题生成文章目录，但如果你在文章里手动添加了[TOC]，可能造成目录重复。我对每个平台写了一个独立的Markdown预处理函数，对语法做裁剪和替换，这些工作比预想的琐碎得多。
CSDN的图片问题也不容小觑。它的编辑器支持外链图片，但会给图片加上水印，还有加载限制。更麻烦的是，CSDN的图片平台有自己的防盗链策略，当你在公众号文章里引用CSDN图片URL时，有时候能显示，有时候不能，完全看对方心情。我在设计时直接做了统一处理：所有图片先下载到一个统一图床，再往三个平台分发，这样至少保证图片不裂。
4.2 知乎接入：根本没法用常规API玩
知乎的接入，是压垮我这个项目的一根重要稻草。
知乎本身不提供面向个人开发者的内容发布API，想发布文章，只能模拟网页端的登录会话，带着Cookie去请求发布接口。这意味着我做的是一个典型的网页端脚本适配，整个方案和飞书、CSDN、公众号的API思路完全不同。网页端接口的每一次请求，都要带着正确的Cookie、X-XSRF-Token、User-Agent等一堆请求头，有一次没带全，知乎直接返回302跳转或者400错误。Cookie的有效期还特别短，过了几个小时就要重新登录，重新过滑块验证。
就算登录状态保持住了，知乎的内容发布也不是简单的POST文本。知乎的编辑器用一套自定义JSON结构来表示富文本，标题、段落、代码块、图片、引用都有独立的类型，我在把Markdown转换到知乎JSON结构时，还要费劲理解它的嵌套规则。整个过程下来，知乎这一块的代码量占了整个项目近三分之一，但是成功率最低，经常发布失败后返回一串对我来说毫无意义的错误码。
更要命的是，知乎发布内容后会触发内容审核和风控。一篇正常的技术文章，第一次发布就提示“正在审核，请稍后查看”，过几个小时再刷新，居然被拦截或者判定为疑似营销内容。这种不确定性，让“自动化发布到知乎”变成了一场体力活：你得盯着状态，随时准备重新排版、重新发布。
4.3 多平台字段映射：配置爆炸的开始
如果只有知乎一个平台难搞，我还能忍。真正让项目失控的，是三个平台之间的字段映射差异。
我们在飞书里定义了一篇标准文章，包含标题、作者、标签、分类、封面、摘要、原文链接。但公众号需要的是标题、作者（在图文消息里）、封面素材ID、正文HTML、原创声明；CSDN需要的是标题、标签（多个，用逗号分隔）、分类（一个）、文章类型、Markdown正文；知乎需要的是标题、问题绑定或者专栏选择、标签最多三个、富文本JSON。
我最初的设计是定义一个大而全的中间格式，把飞书内容输出成统一的JSON，然后每个平台写一个适配器，从JSON里取自己需要的字段。结果适配器越写越多，每个适配器里又充满了条件判断：如果source这个字段为空，就用title的值；如果summary为空，就从前200个字符截取；封面如果是横图，公众号那边要裁成竖图。这些规则属于典型的“经验沉淀型”逻辑，每一条单独看都对，组合在一起就是一个巨型配置系统，代码的复杂度肉眼可见地膨胀。
我大概写了四个适配器，到了第五个终于撑不住了。我开始意识到，问题不在于某个平台的接口有多难调，而在于我试图用一套脚本去覆盖三种并不完全相同的发布逻辑。
5. 失败原因复盘：问题远比“技术难度”更深
5.1 低估了平台的“内容语义”差异
回头来看，这个项目失败的根本原因，不是飞书接口难调，也不是公众号权限卡人，而是我低估了“内容分发”这件事本身的复杂度。
不同平台对同一篇文章的期望是截然不同的。公众号的文章，读者倾向于阅读完整篇幅，那么排版需要更注重视觉舒适度，段落之间要有呼吸感；CSDN的文章，读者要的是快速定位技术点，所以标题要清晰，代码块要突出，tab键层级要准确；知乎的文章，讨论氛围更强，开头需要抛出问题或观点，否则用户很难有耐心往下看。
这些内容语义层面的差异，并不是靠“转格式”能解决的。我当时只想着把Markdown转成HTML、把HTML转成知乎JSON，却从来没有问自己：读者在哪个平台看到这篇文章时，内容形态是否符合该平台的语境。等到想明白这一点，我已经在适配器里改了一轮又一轮，每一个平台的文章都需要人工二次修改，自动化成本反而比手动发布更高了。
5.2 哪些模块其实没有白做
虽然整体项目是失败的，但有几个模块沉淀下来，在后续其他项目里依然能用。
第一个是飞书文档块结构转Markdown的转换器。后续我自己写技术文档时，还是先在飞书写，再用这个转换器导出到本地Markdown仓库，配合Git做版本管理，体验比之前手动复制好很多。第二个是图片统一处理模块。飞书文档里的图片会被脚本自动下载，并重新上传到我的图床，这个流程后来用在了很多其他内容同步任务里。第三个是“平台适配器”的思路。它虽然不适合用于自动化分发，但很适合用来做发布检查，比如发布前根据各平台规则做格式预检：有没有不支持的语法、图片链接是否有效、标签是否超长，这比盲发然后等反馈高效得多。
5.3 如果重新来一次，我会怎么做
回看整个历程，如果重新动手，我先会做单平台闭环，而不是一上来就做三平台统一分发。
先专注把飞书到公众号这条链路打通，把格式转换、图片处理、草稿创建做到稳定，中间所有“需要人工点一下”的步骤都明确标记出来。确认单平台跑通了，再考虑扩展到CSDN，最后才是知乎。横向扩展时不再写一个通用适配器，而是每个平台独立写一个小型发布脚本，每个脚本只关心自己的平台规则，避免被“统一抽象”绑架。
这相当于把“内容分发管理器”降级成“内容辅助发布工具箱”。格局小了，但每一步都更稳。
6. 一些实际操作中值得保留的经验
6.1 内容中间格式：别贪心，够用就行
如果你也想做类似的事情，我强烈建议不要设计一套大而全的中间格式。只需要定一个最小字段集：标题、作者、正文Markdown、封面URL、标签列表、原文链接。正文只用Markdown格式，不要既存Markdown又存HTML，更不要存JSON。各平台的适配器各自负责把Markdown转成自己需要的格式，各平台特有的字段放在适配器内部配置，不要塞进中间格式。这套做法的好处是，中间格式足够简单，任何脚本都能直接处理，不会变成一个大而全但谁都看不懂的结构。
6.2 平台发布的“人工节点”值得保留
我这个项目最大的执念就是全自动，后来才意识到很多平台的设计初衷并不希望你全自动。公众号要求人工确认群发，知乎要求内容审核，CSDN虽然发布方便，但也会有反作弊机制。与其费尽心思绕过这些限制，不如把精力花在“如何减少人工确认的负担”上。比如公众号做到“脚本生成草稿 + 手机App推送提醒编辑确认”，相比全自动就合理得多，也稳定得多。这不是妥协，而是对平台规则的理解与尊重。
6.3 反过来做：内容存档优先
经历了这次失败，我现在更倾向“反向分发”的做法：先在某个主要平台完成内容发布，再把已发布内容自动同步回飞书存档。比如先把文章发在CSDN，然后用脚本抓取CSDN的已发布内容，转成Markdown存进飞书知识库。这样飞书永远是最终归档的地方，内容的准确性和完整性都能得到保证，而分发端也不需要管各平台的排版问题。对于大多数个人创作者来说，这套思路简单、实用、不容易被平台风控针对。
最后说一个自己的体会：折腾这个项目花了大半个月，最后拆掉了很多代码，表面看是白忙活。但正是这段失败经历让我真正理解了各平台内容分发与发布机制的设计逻辑。现在每次发布文章，我至少能预判哪些环节容易出问题，并提前准备好对应方案。如果你也在做类似的事，希望这篇总结能帮你少踩几个坑。
