1. 从两万颗星说起一个AI编程教程凭什么被大模型推荐先交代一下背景。我维护了一套面向零基础开发者的AI编程入门教程从最早的Prompt基础写法到后面接入API做小工具再到用大模型辅助调试和重构代码前后迭代了差不多一年半。前段时间有个朋友截图给我看说他在豆包里问“有没有适合新手学AI编程的教程”结果回答里出现了我那个仓库的名字。当时第一反应是意外第二反应是——这事儿值得拆开讲讲。两万Star这个数字放在整个开源社区里不算顶流但在“AI编程教程”这个细分方向里已经算是跑出来了。更有意思的是被大模型推荐这件事本身。很多人以为被推荐是运气或者觉得只要Star多就会被收录。实际跑下来你会发现大模型的推荐逻辑和搜索引擎的排序逻辑完全是两码事。搜索引擎看的是外链、关键词密度、页面权重大模型看的是内容的结构化程度、信息密度、以及“这段内容能不能直接回答用户的问题”。所以这篇东西不是来炫耀Star数的而是想把“一个教程类项目怎么被大模型识别并推荐”这件事拆透。我会从内容结构、关键词布局、代码示例的组织方式、以及大模型抓取时的偏好这几个角度把踩过的坑和验证过的有效做法都倒出来。适合正在做技术教程、文档站、或者想让自己的开源项目被更多人看到的朋友参考。哪怕你不做教程做的是工具库或者框架里面关于“怎么让大模型理解你的项目”的部分同样适用。先说一个反直觉的结论Star数在两万这个量级对推荐的加成远没有你想象的大。我观察过几个Star数相近的项目有的被推荐有的完全搜不到。差别不在热度在于内容本身是否“可被拆解成问答对”。大模型在生成推荐时本质上是在做一件事——把用户的问题拆成若干子意图然后去它的知识库里找匹配度最高的片段。如果你的项目页面全是“欢迎Star”“求关注”“项目很棒”这类话术没有实质性的问题-解决方案结构那它很难被匹配上。2. 大模型眼里的“好教程”长什么样2.1 从豆包的推荐结果反推内容结构我特意去问了豆包几次把它的回答截图下来逐句分析。发现它推荐我的教程时引用的不是仓库首页的README而是几个具体的章节页面。一个是“如何用Python调用大模型API”一个是“Prompt调试的五个常见错误”还有一个是“用AI辅助写单元测试的完整流程”。这三个页面的共同点是标题本身就是一句完整的用户问题正文里每一步都有明确的输入和输出示例。这就引出了第一个关键点大模型偏好“问题即标题”的内容组织方式。你的章节标题如果写成“API调用详解”它很难判断这到底解决什么问题但如果写成“如何用Python调用大模型API并处理超时”它就能直接把这个标题和用户的提问做语义匹配。我在后续的迭代里把大部分章节标题都改成了疑问句或者“如何做X”的句式推荐命中率明显上升。另一个发现是豆包在回答里会引用具体的代码块。它不会把整段代码贴出来而是摘取关键几行然后用自己的话解释。这说明大模型在抓取时对代码块有单独的解析逻辑。如果你的代码块没有注释、没有上下文说明、变量名全是a、b、c那它解析出来的信息量极低自然也不会被引用。我后来养成了一个习惯每个代码块前面用一段话说明“这段代码解决什么问题”代码块内部关键行加注释代码块后面再补一段“运行结果是什么”。这三段式结构被推荐的概率最高。2.2 信息密度比篇幅更重要很多人写教程喜欢铺陈先讲背景再讲历史再讲原理最后才到实操。这种写法对人来说没问题但对大模型来说前面那些铺垫全是噪声。它在做语义匹配时会计算每个段落的“信息熵”熵值低的段落直接被跳过。什么叫信息熵低就是“正确的废话”。比如“AI编程是当前的热门方向掌握它对你的职业发展很有帮助”——这句话放在任何一篇AI文章里都成立那它就没有信息量。我做过一个对比实验。同一篇教程A版本开头写了三百字的行业背景B版本开头直接写“你需要先安装Python 3.9以上版本然后执行pip install openai”。两周后B版本在豆包里的引用次数是A版本的四倍多。这个实验不一定严谨但方向是明确的大模型更倾向于抓取那些“直接给答案”的段落。所以后来我调整了写作策略每篇文章开头不超过三句话直接进入“你需要准备什么”和“第一步做什么”。2.3 关键词的自然分布与语义场构建关键词这块我踩过一个坑。早期为了SEO在文章里硬塞了很多“AI编程”“大模型教程”“Prompt工程”之类的词结果发现大模型反而不怎么引用。后来想明白了大模型不是靠关键词匹配的它是靠语义向量匹配的。你堆砌关键词反而会稀释段落的语义浓度让向量变得模糊。正确的做法是构建一个“语义场”。比如你要讲“用AI辅助调试”那你的文章里应该自然出现“报错信息”“堆栈跟踪”“断点”“日志”“复现步骤”这些相关词。这些词不需要重复很多遍但要在不同的段落里从不同角度出现。这样大模型在计算语义相似度时你的文章会和一个完整的“调试”语义空间高度重合而不是只和“调试”这两个字重合。我后来用了一个笨办法来验证把自己写的章节复制到豆包里问它“这段内容主要讲什么”。如果它的回答和我预期的主题一致说明语义场构建成功了如果它回答得很泛比如“这段内容讲的是编程相关的东西”那就说明语义浓度不够需要补充具体场景和细节。3. 让代码示例自己会说话教程类项目的特殊优化3.1 代码块的可解析性设计教程类项目和普通文档最大的区别是代码占比高。大模型在解析代码块时和解析自然语言是两套逻辑。自然语言看语义代码看结构和模式。如果你的代码块里全是业务逻辑没有通用的模式那大模型很难从中提取出可复用的知识。我后来定了一个规矩每个代码示例必须包含一个“最小可运行单元”。什么意思就是读者复制这段代码改一两个参数就能跑起来不需要补全其他文件。比如讲API调用我不会只贴一个函数定义而是贴完整的“导入库-设置参数-发起请求-处理响应-异常捕获”的流程。这样大模型在解析时能识别出这是一个完整的“API调用模式”而不是一堆零散的代码片段。另外代码块的语言标注一定要准确。我早期有些代码块标的是text或者干脆不标后来发现豆包在引用时会把它们当成普通文本处理不会识别为代码。改成python、javascript、bash之后引用时的格式明显更规范它会用代码格式来展示而不是混在段落里。3.2 注释和文档字符串的写法注释这块我走过弯路。一开始觉得注释是给人看的写得比较随意比如# 这里设置一下参数。后来发现大模型会把注释也纳入解析范围而且注释的质量直接影响它对代码功能的理解。# 这里设置一下参数这种注释它提取不出任何有效信息但如果你写成# 设置API密钥和请求超时时间超时设为30秒它就能理解这段代码的意图。文档字符串docstring更重要。我在每个核心函数上都加了docstring格式参照Google风格包含功能描述、参数说明、返回值、异常类型。这些docstring后来成了豆包引用最多的内容之一。因为它本身就是结构化的自然语言和用户提问的匹配度极高。比如用户问“怎么处理API调用超时”豆包的答案里直接引用了我的docstring里关于timeout参数的说明。3.3 错误处理和边界条件的展示新手教程最容易忽略的就是错误处理。很多教程只讲“成功路径”不讲“失败了怎么办”。但大模型在推荐时反而更看重错误处理的部分。因为用户提问往往就是遇到了错误比如“API调用报401怎么办”“返回结果解析失败怎么处理”。如果你的教程里有这些内容被匹配到的概率会大幅增加。我在教程里专门加了一个章节叫“常见错误与排查”把我在实际开发中遇到过的报错信息、原因、解决方案都列了出来。这个章节后来成了被引用最多的部分之一。豆包在回答“API密钥无效怎么办”这类问题时直接引用了我的排查步骤。这说明大模型在判断内容价值时“解决问题的能力”权重高于“介绍知识的能力”。4. 从被收录到被推荐中间隔了什么4.1 收录和推荐是两回事很多人以为只要内容被大模型抓取了就会被推荐。实际不是。收录只是第一步相当于你的内容进了它的知识库推荐是第二步相当于它在回答具体问题时选择了你的内容。这两步之间有一个关键环节内容与问题的匹配度排序。我观察到一个现象同一个问题豆包在不同时间给出的推荐结果不一样。有时候推荐我的教程有时候推荐别人的。这说明它在做动态排序排序的依据可能包括内容的时效性、用户反馈、以及内容本身的“回答完整度”。什么叫回答完整度就是用户看完这段内容后是否还需要继续追问。如果你的教程只讲了“是什么”没讲“怎么做”那用户大概率会追问系统就会认为这段内容不够完整下次可能就不推荐了。所以后来我在写每个章节时都会问自己一个问题读者看完这一节能不能直接动手操作如果不能缺了什么把缺的部分补上内容的“回答完整度”就上去了。4.2 用户交互信号的影响还有一个容易被忽略的因素用户和推荐结果的交互。当豆包推荐了我的教程后如果用户点击了、阅读了、没有立刻返回去问别的问题系统就会认为这个推荐是有效的后续会加大推荐权重。反之如果用户点进去马上退出来或者继续追问“还有别的吗”系统就会降低权重。这个机制意味着教程的“第一屏”极其重要。用户点进来后如果前三行没有看到他想要的内容大概率会退出。所以我后来把每个章节的开头都改成了“结论先行”第一句话直接说这一节解决什么问题第二句话给出核心步骤第三句话再展开细节。这样用户一眼就能判断“这是不是我要的”减少无效点击。4.3 跨平台引用带来的权重叠加还有一个现象挺有意思我的教程被豆包推荐后陆续有其他平台的内容也引用了我的仓库链接。这些跨平台的引用反过来又强化了豆包对我内容的信任度。虽然我不确定具体的算法逻辑但从结果看被引用次数越多的内容被推荐的概率越高。这给我一个启发不要只盯着一个平台。你在技术社区发的帖子、在问答平台写的回答、在视频平台做的演示只要引用了你的教程都可能成为权重叠加的来源。当然前提是这些引用是自然的、有价值的而不是硬广。我后来在几个技术社区回答问题时会顺带贴一下教程里对应的章节链接既解决了提问者的问题也增加了内容的曝光和引用。5. 那些没人告诉你的实操细节5.1 标题里的数字和符号有讲究我测试过不同风格的章节标题发现带数字的标题被引用的概率更高。比如“Prompt调试的五个常见错误”比“Prompt调试常见错误”的引用率高出一截。我猜是因为数字给了大模型一个明确的“信息量预期”它知道这段内容里至少有五个要点值得解析。符号方面冒号和破折号比逗号更有效因为它们能更清晰地划分标题的语义结构。但要注意数字不能乱用。如果你标题写“十个技巧”正文里只写了三个那大模型解析后发现信息量不匹配反而会降低信任度。所以数字必须和实际内容对应宁少勿多。5.2 更新频率比单篇质量更重要这个结论可能有点反直觉。我早期花了很多时间打磨一篇“完美”的教程发布后确实被收录了但推荐频率不高。后来我改成每周更新一个小章节每次只讲一个具体问题反而推荐频率上去了。我分析原因是大模型偏好“活跃”的内容源。你持续更新说明这个内容源是活的、有人在维护的它就更愿意推荐。而且小步更新还有一个好处每次更新都是一个独立的“问题-答案”单元更容易被匹配到具体的用户提问。一篇大而全的教程语义太宽泛反而不容易匹配到具体问题多个小而精的章节每个都对应一个具体场景匹配精度更高。5.3 别忽视README之外的内容很多人把精力全花在README上觉得README写好了就行。但实际上大模型抓取的范围远不止README。你的issues、discussions、wiki、甚至commit message都可能被纳入解析范围。我有几个章节的内容最早就是在issues里回答别人问题时写的后来整理成了正式章节。豆包在推荐时引用的就是issues里的原始回答。所以我的建议是把每一次回答问题的过程都当成内容创作。你在issues里认真回答一个问题写清楚原因、步骤、代码示例这段内容就可能被大模型抓取成为推荐素材。反过来如果你在issues里只回一句“看文档”那你就浪费了一次内容积累的机会。5.4 避免过度优化导致的“AI味”最后说一个坑。我有一段时间为了迎合大模型把文章写得非常“结构化”每段都是“问题-原因-解决方案”的三段式结果发现推荐率反而下降了。后来想明白了大模型虽然偏好结构化内容但它也不喜欢“模板化”的内容。如果你的每一段都长得一模一样它会认为这是机器生成的降低信任权重。所以后来我在保持结构清晰的同时刻意加入了一些“人味”。比如在讲一个坑的时候我会写“我当时试了三种方法前两种都不行第三种才跑通”这种带过程描述的段落反而更容易被引用。因为大模型在判断内容质量时“真实经验”的权重很高。它能区分“教科书式的讲解”和“踩过坑的人写的总结”后者明显更受青睐。6. 如果你也想做一个被推荐的教程项目先把结论放在前面被大模型推荐这件事七分靠内容三分靠运气。内容这块核心就三件事——问题即标题、代码可运行、错误有方案。把这三件事做到位剩下的就是持续更新和耐心等待。具体操作上我建议从一个小切口开始。不要一上来就写“AI编程从入门到精通”这个题目太大大模型不知道把你匹配给谁。你可以先写“如何用Python调用大模型API并处理超时”把这个具体问题写透写清楚每一步的输入输出写明白报错怎么排查。这一篇被推荐后你再扩展下一个具体问题。积少成多整个教程的权重就上来了。另外别太在意Star数。Star是给人看的推荐是给机器看的。两万Star确实好看但真正让豆包推荐我的是那些具体章节里的具体内容。我见过一些Star数不高的项目因为内容扎实、结构清晰照样被大模型频繁引用。所以把精力放在内容上Star是结果不是原因。最后分享一个我一直在用的小技巧每写完一个章节把它复制到豆包里问它“这段内容主要解决什么问题”。如果它的回答和你的预期一致说明这一章写清楚了如果它回答得含糊那就回去改直到它能准确概括为止。这个办法虽然笨但比任何SEO工具都管用。毕竟你要说服的不是搜索引擎而是那个正在回答用户问题的大模型。