1. 一个教程项目被大模型推荐意味着什么先交代背景。我维护了一套面向零基础开发者的 AI 编程入门教程纯开源、纯文档没有花哨的官网也没有做任何付费投放。前段时间有读者截图给我说在某个国产 AI 助手里问“AI 编程怎么入门”回答里直接点名推荐了我这套教程还附上了仓库地址。当时那个仓库的 Star 数刚过 2 万。这件事本身不大但值得拆开讲。因为它回答了一个很多人关心的问题在 AI 搜索和 AI 问答逐渐取代传统搜索引擎的当下一个开源项目、一套技术教程到底靠什么被“推荐”是靠 Star 数靠关键词堆砌还是靠别的什么东西我先把结论摆出来大模型推荐一个内容源本质上是在做“可信度 匹配度 可引用性”的三重判断。Star 数只是可信度里最表层的一个信号真正起作用的是内容结构、语义密度和可被切块引用的能力。这套教程能被推荐不是因为我运气好而是因为它在写作阶段就无意中踩中了几个关键点。这篇文章我会把这套教程从设计到落地的完整思路拆开讲包括为什么我选择“文档即产品”而不是做视频或课程教程的目录结构是怎么设计的为什么这么设计内容颗粒度控制在什么范围为什么这个范围对 AI 引用最友好2 万 Star 是怎么一步步积累的哪些动作真正有效被 AI 推荐之后我观察到的流量变化和后续调整适合谁看如果你正在维护开源项目、写技术教程、做知识付费内容或者单纯想知道“怎么让我的内容更容易被 AI 引用”这篇应该能给你一些可以直接抄的作业。如果你只是刚入门 AI 编程也可以看看一套合格的入门教程应该长什么样方便你筛选学习材料。2. 为什么我放弃了视频和课程选择纯文档路线2.1 三种内容形态的成本结构对比做 AI 编程教程市面上主流有三种形态视频课、付费专栏、开源文档。我在动手之前把这三条路都推演了一遍最后选了最“笨”的那条。维度视频课付费专栏开源文档制作成本极高需录制剪辑中等需持续更新低纯文本更新成本极高改一处要重录中等极低改一行即可检索友好度差内容在音频里中平台内搜索极好全文可索引AI 引用友好度差难以切块差有付费墙极好结构化文本传播路径平台推荐为主平台推荐为主搜索 社交 AI变现路径直接卖课订阅赞助 引流这张表里最关键的一行是“AI 引用友好度”。视频和付费专栏的内容大模型基本抓不到或者抓到了也没法直接引用——视频没有文本付费内容有访问限制。而开源文档是纯文本、公开可访问、结构清晰天然就是大模型最喜欢的“语料形态”。提示如果你做内容的目的是长期被检索、被引用纯文本 公开可访问 结构化这三个条件缺一不可。视频适合做流量入口但不适合做知识沉淀。2.2 文档路线的隐性优势可组合性纯文档还有一个被低估的优势可组合性。视频课是一个个独立的文件用户看完一节就看下一节内容之间是线性关系。而文档可以通过链接、锚点、目录互相引用形成一张知识网络。这套教程里我在每个章节末尾都加了“相关章节”的链接。比如讲“提示词工程”的那一节会链到“模型参数调优”和“上下文管理”。读者可以从任意一个点进入然后顺着链接走到其他相关知识点。这种网状结构恰好也是大模型做知识检索时最喜欢的形态——它可以沿着链接关系判断内容的相关性和权威性。我实测下来这种内部链接密度高的文档被 AI 引用的概率明显高于孤立的单篇教程。原因很简单链接关系本身就是一种“投票”你链向谁就说明你认为谁重要。2.3 为什么不做视频一个反直觉的判断很多人觉得视频传播效率高但那是针对“娱乐型内容”。技术教程的消费场景是“遇到问题—搜索—找到答案—解决问题”这个链条里用户需要的是快速定位和精准阅读而不是看一个人从头讲到尾。我做过一个小范围测试同一节内容一个做成 10 分钟视频一个做成 800 字文档给两组新手看。结果是文档组的完成率高出视频组近一倍而且文档组的读者更倾向于继续看下一节。原因不复杂——文档可以扫读、可以跳读、可以复制代码视频只能线性播放。所以我的判断是技术教程的默认形态应该是文档视频只适合做“导览”和“演示”的补充。这套教程后来也加了一些短视频但都是作为文档的附属而不是主体。3. 目录结构设计让 AI 和人都能三秒找到答案3.1 三层目录结构的取舍教程的目录结构我改了四版最后定下来的是三层第一层入门准备环境、工具、基础概念 第二层核心技能提示词、上下文、参数、调试 第三层实战项目三个完整的小项目为什么是三层而不是两层或四层两层太粗用户找不到具体内容四层太细目录本身就变得难以浏览。三层刚好对应“知道要学什么—知道怎么学—知道怎么用”这个认知路径。更重要的是三层结构对大模型的分块非常友好。大模型在检索内容时会按照标题层级把文档切成块。三层结构意味着每个知识块的大小适中既不会太大导致检索不精准也不会太小导致上下文丢失。注意目录层级不要超过四层。超过四层之后不仅人看起来累机器切块也会变得混乱检索命中率反而下降。3.2 每个章节的固定模板我给每一节都定了一个固定模板包含五个部分一句话结论这节要解决什么问题一句话说清楚背景说明为什么会有这个问题什么场景下会遇到操作步骤具体怎么做带代码和截图常见错误新手最容易踩的坑相关链接链到其他相关章节这个模板看起来死板但它解决了一个大问题读者和 AI 都能快速判断这一节有没有自己要的答案。一句话结论放在最前面扫一眼就知道要不要继续读常见错误放在最后方便遇到问题时直接跳过来查。我后来观察 AI 引用这套教程的方式发现它最常引用的就是“一句话结论”和“常见错误”这两部分。因为这两部分信息密度最高语义最完整最适合直接摘出来回答用户问题。3.3 标题命名的具体规则标题命名我定了几条硬规则不用“浅谈”“漫谈”“那些事”这类模糊词每节标题必须包含一个具体动作或对象同一层级的标题长度尽量接近视觉上整齐标题里自然包含用户可能搜索的关键词举个例子我不用“提示词入门”而是用“如何写出模型能理解的提示词”。前者是概念后者是动作。用户搜索时更可能搜“怎么写提示词”而不是“提示词入门”。大模型在匹配时也更倾向于匹配动作型描述。这套规则执行下来整个教程的标题看起来非常“工具化”没有文学性但检索效率极高。我个人的体会是技术教程的标题不需要好看需要好搜。4. 内容颗粒度为什么每节控制在 800 到 1200 字4.1 颗粒度与检索命中率的关系内容颗粒度是我花最多时间调的一个参数。太短信息不完整读者看完还得再搜太长重点被淹没AI 切块时容易把关键信息切散。我最后的结论是每节正文控制在 800 到 1200 字代码块不计入字数。这个范围是实测出来的。我做过对比把同一批内容分别按 500 字、1000 字、2000 字一节来组织然后看读者停留时间和 AI 引用频率。结果是 1000 字左右一节的综合表现最好。500 字一节太碎读者需要频繁翻页2000 字一节太长读者容易中途放弃AI 引用时也经常只引到一半。每节字数读者完成率AI 引用完整度综合评分500 字高低中1000 字高高高2000 字低中低提示这个字数范围是针对技术教程的。如果是概念讲解类内容可以适当放长如果是操作步骤类可以适当缩短。核心原则是“一节只讲一件事”。4.2 代码块的处理方式代码块我单独处理。每一段代码前面必须有一句话说明这段代码干什么后面必须有一句话说明运行结果是什么。代码本身尽量控制在 20 行以内超过 20 行就拆成两段。为什么这么处理因为大模型在引用代码时如果代码前后没有说明它很难判断这段代码的上下文。加上前后说明之后代码块就变成了一个自包含的单元引用起来不会出错。另外我给所有代码块都加了语言标注。这看起来是小事但实测下来加了语言标注的代码块被正确引用的概率明显更高。因为大模型可以据此判断代码类型匹配对应的技术问题。4.3 图文比例的控制这套教程里图片只用在三个地方环境配置的界面截图、运行结果的截图、架构示意图。其他一律用文字和代码。原因很简单图片对 AI 不友好。大模型读不到图片里的信息图片多了反而会稀释文本的语义密度。而且图片维护成本高界面一改就得重新截图。我个人的经验是技术教程里能用文字说清楚的就不用图能用代码演示的就不用文字。图片只在“文字说不清楚且代码演示不了”的时候才用。5. 从 0 到 2 万 Star哪些动作真正有效5.1 冷启动阶段先做搜索再做社交教程刚发布的时候我没有去任何社区发帖而是先做了一件事把教程里每一节的标题都改成用户可能搜索的问句形式。然后等搜索引擎收录。这个阶段大概持续了一个月流量很少但来的都是精准流量——都是带着具体问题来的。这些人的停留时间长跳出率低对后续的搜索排名有帮助。一个月之后我才开始在技术社区发帖。发帖的时候也不是直接甩链接而是把教程里的某一节内容整理成一个独立的问题解答发在对应板块末尾附上教程链接。这样既提供了价值又不会被认为是纯广告。5.2 增长阶段被引用比被点赞重要教程到 5000 Star 左右的时候我开始注意到一个现象很多 Star 来自其他项目的 README 引用。有人在写自己的项目文档时把教程链接放进了“参考资料”里。这让我意识到一件事开源项目的增长很大程度上靠的是“被引用”而不是“被点赞”。点赞是一次性的引用是持续的。一个被 100 个项目引用的教程比一个被 10000 人点赞的教程更有生命力。所以后来我主动做了一件事把教程里通用的部分抽出来做成独立的、可以被其他项目直接引用的小模块。比如“如何配置开发环境”这一节我把它整理成一个独立的 Markdown 文件其他项目可以直接链接过去不用复制内容。这个动作带来的效果非常明显。半年之内引用这套教程的项目数量翻了三倍Star 数也跟着上来了。5.3 稳定阶段更新频率比更新量重要到 1 万 Star 之后我调整了更新策略从“每周写新章节”改成“每周更新已有章节”。更新内容包括补充新的模型参数、修正过时的截图、增加读者反馈的常见问题。这个策略看起来保守但效果很好。因为教程的核心价值不在于“新”而在于“准”。一个过时的教程Star 再多也没用。保持已有内容的准确性比不断堆新内容更重要。我给自己定了一个规矩任何一节内容如果超过三个月没有检查过就标记为“待验证”。读者看到标记就知道这节可能过时了我也能据此安排更新优先级。6. 被 AI 推荐之后我观察到的三个变化6.1 流量结构的变化被 AI 推荐之后最明显的变化是流量来源。之前流量主要来自搜索引擎和技术社区被推荐之后来自 AI 助手的流量占比从不到 5% 涨到了接近 20%。这部分流量的特点是停留时间短但转化率高。因为用户是从 AI 那里带着具体问题来的进来之后直接找答案找到就走。虽然停留时间短但他们更倾向于 Star 和分享因为他们已经通过 AI 确认了这个教程的可信度。6.2 内容需求的变化AI 推荐带来的用户问的问题更具体。比如之前读者问的是“怎么入门 AI 编程”现在问的是“提示词里的 temperature 参数设多少合适”。这说明 AI 在推荐之前已经帮用户做了一轮筛选来的都是更明确的需求。这反过来影响了我后续的内容规划。我开始增加更多“参数级”的细节内容减少“概念级”的泛泛介绍。因为概念性的问题AI 自己就能回答参数级的细节AI 需要引用具体文档。6.3 引用方式的变化我观察了 AI 引用这套教程的具体方式大致分三种直接引用把某一节的结论原样摘出来回答用户组合引用把两到三节的内容拼在一起形成一个完整答案指路引用不直接给答案而是说“可以参考这个教程的某一节”这三种方式里组合引用最多。这意味着 AI 在引用时会主动做内容重组。这对教程的结构提出了更高要求每一节必须自包含同时又要能和其他节无缝拼接。我后来调整了写作方式每节开头都加一句“本节假设你已经了解 XX”这样 AI 在组合引用时能自动判断前置知识是否满足。7. 常见问题与排查技巧实录7.1 内容写得很全但没人看问题出在哪这是我最常被问到的问题。我的排查思路是三步看标题标题是不是用户会搜的词把标题输入搜索框看有没有联想词看开头前 100 字有没有说清楚“这节解决什么问题”没有就改看结构有没有小标题有没有代码块全是文字大段堆砌的读者看不下去这三步走完大部分“没人看”的问题都能找到原因。我见过太多教程内容质量很高但标题起得太文艺开头绕来绕去结构一坨。读者三秒内找不到重点就走了内容再好也没用。7.2 怎么判断一节内容该不该拆判断标准很简单如果一节里出现了两个以上的“一句话结论”就该拆。因为这意味着这节在讲两件事而一节只应该讲一件事。拆的时候注意拆出来的两节要有明确的先后关系或并列关系不能随便拆。拆完之后在原来那节的位置加一个目录链到拆出来的两节。7.3 更新旧内容时怎么处理已经过时的截图我的做法是不删旧截图而是在旁边加新截图并标注版本。这样读者能看到变化过程也能理解为什么会有差异。如果旧截图对应的功能已经完全移除那就直接删掉并在更新日志里说明。不要留着误导读者。7.4 被 AI 引用后要不要主动去“优化”内容我的建议是不要为了被引用而刻意优化。AI 的引用逻辑一直在变你今天优化的点明天可能就不适用了。真正稳定的做法是保持内容本身的高质量结构清晰、语义完整、更新及时。我试过刻意在内容里堆关键词结果反而被降权了。后来回归到“把每节写清楚”这个基本盘引用量反而稳定上升。常见问题排查方向解决动作内容没人看标题、开头、结构改标题为动作型开头加结论加小标题一节太长数“一句话结论”超过两个就拆截图过时看功能是否还在加新截图标注版本或直接删除引用量下降看内容是否过时检查三个月未更新的章节7.5 一个容易被忽略的细节锚点命名Markdown 的锚点默认是根据标题生成的中文标题生成的锚点往往是一串编码又长又难记。我后来手动给每个重要章节加了英文锚点比如#prompt-basics、#context-management。这个动作很小但效果很好。因为 AI 在引用时如果能拿到一个语义清晰的锚点它更倾向于直接链接过去。而且手动锚点也方便我在其他文档里引用。提示锚点命名用英文小写加连字符不要用拼音不要用数字开头。语义清晰的锚点对人和机器都友好。8. 如果重新做一遍我会调整的三件事第一件事更早引入版本化。这套教程前期没有版本概念导致后来更新时读者不知道哪些内容是新的。如果重来我会从第一版就加上版本号和更新日志每节标注最后更新日期。第二件事更早做内容模块化。前期很多内容是耦合在一起的后来想拆出来给其他项目引用时发现拆不动。如果重来我会从第一天就把通用内容做成独立模块用链接而不是复制来复用。第三件事更早关注 AI 引用数据。我是在被推荐之后才开始观察 AI 引用方式的之前完全没关注。如果重来我会从发布第一天就定期检查主流 AI 助手对这套教程的引用情况据此调整内容结构。这三件事的共同点是都是结构层面的调整而不是内容层面的。内容写得好不好读者能感觉到结构做得好不好机器能感觉到。在 AI 逐渐成为内容分发渠道的当下后者的重要性正在快速上升。最后分享一个我一直在用的小技巧每写完一节把它单独复制出来假装自己是一个完全不懂这个领域的人读一遍。如果读完之后能说清楚“这节讲了什么、怎么用”那这节就合格了。如果读完还是模糊那就重写。这个自检方法很笨但比任何工具都管用。