1. 先说清楚这次优化到底在治什么病DeepWiki 这类自动文档生成工具核心价值是让 AI 去读代码仓库、再把理解沉淀成一篇篇可维护的文档。但跑过一段时间的同学应该都有体会文档“能生成”和文档“能长期用”完全是两回事。我这次做的优化就是针对两个最刺手的细节——代码行号Code Line Numbers和确定性目录生成Deterministic Table of Contents Generation。先说代码行号。AI 在解释某个函数时经常会在文档里写“请看src/service.py的 handle_request 方法”但这句话是空的读者得自己打开文件去翻。更麻烦的是如果文档里的代码块没有行号团队在评审、答疑、定位问题时只能靠“大约在第 80 行附近”这种模糊表述来回沟通成本非常高。如果能在生成的 Markdown 代码块里带上真实文件的行号并且在正文引用处也明确标注“第 72 到 86 行”这个文档的可追溯性直接上了一个台阶。再说确定性目录。LLM 生成目录时只要模型参数不变、输入不变理论上结果应该稳定但实际跑下来会发现同一个仓库昨天生成的目录和今天生成的目录可能顺序完全不同甚至章节编号都会变。对于个人笔记这无所谓但一旦文档要嵌入 CI、对外发布或多人协作目录变化就意味着链接失效、评审反复、diff 混乱。所谓“确定性”就是希望同一份代码在同样的配置下无论跑多少次产出的目录结构、章节顺序、锚点名称完全一致。这篇文章我会按“问题拆解——环境准备——行号方案——目录方案——实测对比——踩坑记录”的顺序展开。适合正在用 DeepWiki 做自动文档、或者用各类 LLM 生成技术文档并希望结果可复现的工程师。我会把每一步的取舍讲清楚并提供可以直接抄走的脚本和配置。2. 动手之前的准备环境、基线和问题定位2.1 把 DeepWiki 跑起来并锁定版本DeepWiki 本身是开源项目安装方式不复杂但有个关键点不要直接拉 latest而是要把版本锁死。因为 LLM 生成的稳定性不仅取决于你的 prompt还取决于代码版本、依赖版本、甚至 Python 版本。哪怕只是依赖库的小版本升级都可能让你之前调好的“确定性”消失。我当时是这么做的git clone https://github.com/your-fork/deepwiki.git cd deepwiki git checkout v0.4.2 # 记录你实际使用的版本 python -m venv .venv source .venv/bin/activate pip install -e .注意这里强烈建议 fork 一份到自己仓库因为后续可能要改少量源码。用官方仓库再拉分支升级时冲突会比较多。锁版本的目的是为了让“同一仓库 同一配置 同一模型参数”在多次运行下具备可比性。如果不锁版本后面做的任何优化都很难归因。2.2 准备测试仓库和生成基线建议选一个中等规模、结构稳定的仓库来做基线测试。我用的测试仓库大约 30 个 Python 文件、5 个目录层级总代码量 8000 行左右。规模太小测不出稳定性问题规模太大又是给调试添堵。生成基线时先不做任何优化直接跑一遍完整流程把输出保存为baseline_v1。记住这个基线有两个作用一是后面对比行号和目录的改进效果二是用来观察“不稳定的具体表现是什么”。比如我第一轮基线就跑出两个典型问题同一个章节第二次生成时标题从## 3.2 API 鉴权变成了## 3.2 鉴权机制代码块里的行号完全错位文档里写“第 15 行”但真实代码里那个函数在第 28 行。这种不确定性靠肉眼 review 很难全部发现所以后面我专门写了一个校验脚本自动化对比两次生成结果。2.3 确认生成链路里的三个不稳定点在动手优化之前我花了半天把 DeepWiki 的生成链路梳理了一遍最后定位到三个关键不稳定点第一是 LLM 采样过程。目录、标题这类文本生成天然有概率性即使 temperature 设为 0某些模型在 batch 推理、并行解码时仍会出现微小差异。第二是 Prompt 构造顺序。文档的生成依赖从代码库提取的上下文如果上下文里文件列表的顺序是动态的比如来自 set 遍历或文件系统读取顺序那么最终拼接出来的 prompt 每次可能都不一样。第三是后处理逻辑。有些章节标题需要做 slug 化转成锚点如果对中文、空格、特殊字符的处理规则不统一同一个标题在不同环境下会生成不同的锚点。明白这三个点之后优化方向就很清晰了要么在源头把 prompt 输入变成确定性排序要么在后处理阶段覆盖掉 LLM 的不稳定输出。我最终采用的是“前后夹击”的策略两个方案都上了。3. 代码行号从“大概位置”到“精确锚点”3.1 三种行号注入方案怎么选给代码块加行号听起来很简单真正落地时会发现有三条路线方案一让 LLM 自己输出行号。也就是在 prompt 里写“请在每个代码块左边加上真实行号”。我试过效果不稳定。模型经常把行号写错尤其是遇到空行、注释、多行字符串时它“理解”的行号和实际文件行号经常差几行。方案二生成后再用脚本统一注入行号。也就是文档先正常生成代码块内容保持原样然后跑一个后处理脚本读取代码块内容和真实源文件比对找到对应行号再插入到每个代码行前面。这个方案可控性高因为有真实文件作为“唯一事实来源”。方案三基于语法树AST精确计算函数起始行只给关键代码段加行号范围标注。这个适合在大仓库里做“精确导航”但实现成本高而且不同语言的 AST 规则不一样。我最终选了方案二为主、方案三为辅。方案二解决了 95% 的问题方案三用来处理那些“同一个函数被拆成多段展示”的特殊情况。3.2 后处理脚本真实行号注入核心思路不复杂Markdown 里的每个代码块都会附带语言标签比如python我用 Python 脚本解析文档里的代码块然后把每一行代码当作字符串在源文件里去查找这行内容首次出现的位置从而确定行号。直接看脚本import re import json from pathlib import Path def find_line_number(content: str, source_text: str, start_hint: int 0) - int: 在源文本中查找 content 首次出现的真实行号 idx source_text.find(content, start_hint) if idx -1: # 内容可能跨行或被格式化退化为模糊匹配 idx source_text.find(content.splitlines()[0] if content.splitlines() else content) if idx -1: return None return source_text[:idx].count(\n) 1 def process_markdown(md_path: str, repo_root: str) - str: md Path(md_path).read_text(encodingutf-8) lines md.splitlines() output [] in_code False lang code_buf [] code_start_idx 0 def flush_code(): nonlocal code_buf, in_code if not code_buf: return # 通过代码块第一行注释中的路径信息定位源文件 path_hint for cl in code_buf: m re.match(r\s*(?:#|//|--|/\*)\s*file\s*[:\s](\S), cl) if m: path_hint m.group(1) break if not path_hint: output.extend(code_buf) code_buf [] in_code False return src_file Path(repo_root) / path_hint if not src_file.exists(): output.extend(code_buf) code_buf [] in_code False return src_text src_file.read_text(encodingutf-8) # 去掉代码块里的 file 注释行避免污染展示 cleaned [cl for cl in code_buf if not re.match(r\s*(?:#|//|--|/\*)\s*file, cl)] # 计算每行的源文件行号 last_idx 0 for i, cl in enumerate(cleaned): line_no find_line_number(cl, src_text, last_idx) if line_no is None: output.append(f {cl}) else: # 补齐为4位行号方便对齐 output.append(f{line_no:4} | {cl}) last_idx max(0, line_no - 1) if line_no else 0 code_buf [] in_code False for idx, line in enumerate(lines): if line.strip().startswith(): if not in_code: in_code True lang line.strip()[3:].strip() code_buf [] code_start_idx idx else: flush_code() output.append(line) continue if in_code: code_buf.append(line) else: output.append(line) # 处理文档末尾可能未闭合的代码块 if in_code: flush_code() return \n.join(output)这个脚本有几个设计细节值得说明第一代码块里需要有定位信息我采用约定file path/to/file.py注释。因为 AI 生成代码时不一定能准确回忆文件路径所以在 prompt 里要求它“在每个代码块第一行注明该代码来自哪个文件”。这样脚本才能把代码映射到真实源文件。第二查找行号时用了start_hint参数。每次找到一行之后下一次查找从这一行附近开始这样既快又避免重复匹配同一个函数里的相同代码行。第三对于“AI 生成的示例代码并不完全等于源文件”的情况脚本做了降级处理如果整行找不到就取第一行来模糊匹配如果还是找不到就只输出空格占位不让文档报错。3.3 边界情况多文件、重复代码和动态生成内容实际仓库里会遇到很多让脚本崩溃的场景我踩过的坑主要有三个第一个是同一段代码在多个文件里重复出现。比如两个文件都有def get_config():脚本搜索时可能匹配到错误的文件。解决办法是把搜索范围缩小到file指定的文件其次是查找时带上前后几行上下文。我的做法是拼接相邻 2 行的内容作为搜索键错配率明显下降。第二个是 AI 对代码做了精简或改写。很多文档为了讲清原理会把真实代码压缩成伪代码。这种情况下硬找行号没有意义。我的策略是如果代码块和真实源文件的相似度低于 70%就直接不强行加行号改为在代码块前加一个“代码摘要”标注说明这是经过简化的示例。第三个是动态生成或临时文件。仓库里有些代码是构建脚本临时生成的不存在于源码中。我的处理比较简单找不到文件就跳过不加行号同时把这类文件加入exclude列表避免每次生成都触发告警。3.4 行号在页面里的交互行号注入之后还需要让它在页面里真正可用而不只是显示一堆数字。我做了两件事一是在 Markdown 渲染层开启行号样式。由于 DeepWiki 默认的渲染器不一定支持行号我直接在生成的 HTML 页面上做了轻量级前端增强把|分隔的行号列变成>from pathlib import Path import re def safe_anchor(title: str) - str: # 统一锚点生成规则 title title.strip().lower() title re.sub(r[^a-z0-9\u4e00-\u9fa5], -, title) title title.strip(-) return title def generate_toc(repo_path: str) - str: root Path(repo_path) toc_lines [] def walk_dir(current: Path, level: int): dirs sorted([p for p in current.iterdir() if p.is_dir()], keylambda p: p.name) files sorted([p for p in current.iterdir() if p.is_file()], keylambda p: p.name) for d in dirs: # 跳过隐藏目录、构建目录、依赖目录 if d.name.startswith(.) or d.name in (node_modules, venv, __pycache__, dist, build): continue indent * level title d.name toc_lines.append(f{indent}- [{title}](#{safe_anchor(title)})) walk_dir(d, level 1) for f in files: if f.name.startswith(.) or f.suffix not in (.py, .md, .js, .ts): continue indent * level title f.stem toc_lines.append(f{indent}- [{title}](#{safe_anchor(f.stem)})) walk_dir(root, 0) return \n.join(toc_lines)这个脚本生成的是一个 Markdown 格式的目录可以直接放在文档开头。因为它是纯文件系统驱动的不经过 LLM所以输出是绝对确定的——同一份代码无论跑多少次目录都一样。但这里有个重要问题只给目录不告诉模型每个章节该写什么模型可能还是把章节内容串到错误的标题下面。所以我还会把这份目录作为“大纲约束”注入到生成 prompt 里明确告诉模型“必须严格按这个目录顺序写不能新增或删除标题”。4.4 方案 C缓存与增量重建当仓库规模变大每次全量生成文档的时间和成本都很高。为了保持“确定性”的同时控制成本我引入了缓存机制。思路是把每次生成的文档和源仓库的文件哈希一起存起来。下次运行时先对比当前仓库的文件哈希和上次的哈希如果某个文件没有变化就直接复用上次生成的对应章节不重新调用模型。这样既保证了目录稳定又让增量构建变快。缓存键的设计很关键。我用的键是“文件相对路径 文件内容 SHA256 模型版本 prompt 模板版本”。如果只缓存文件内容一旦你改了 prompt就会拿到旧内容所以必须把 prompt 模板版本也加进键里。import hashlib import json def hash_file(path: Path) - str: h hashlib.sha256() h.update(path.read_bytes()) return h.hexdigest() def cache_key(rel_path: str, content_hash: str, model_version: str, prompt_version: str) - str: raw f{rel_path}:{content_hash}:{model_version}:{prompt_version} return hashlib.sha256(raw.encode()).hexdigest()增量构建的难点在于“父目录和子目录的联动”。如果一个模块的目录结构变了子章节的生成结果也需要失效。所以我做了一个简单的依赖图任何文件的哈希变化都会让它在目录树上的所有祖先节点缓存失效。4.5 目录与页面锚点的联动有了确定性目录之后还必须确保目录里的锚点和正文标题的锚点对齐。LLM 生成的标题经过 Markdown 渲染后锚点规则可能和目录生成脚本不一致。我的做法是在生成最终 HTML 之前统一跑一个“锚点规范化”步骤从目录里提取所有标题。对每个标题生成一个id属性。在正文里查找对应标题并写入相同的id。如果正文里找不到某个标题说明模型漏写了章节这时用占位符补上并打一条警告日志。这样做之后目录点击跳转的成功率从原来的约 85% 提升到了 100%。锚点这个细节很多人忽略但一旦团队开始用目录导航就会发现错一个锚点基本等于这个章节“失踪”了。5. 实测结果稳定性的提升到底有多少5.1 我的验证方法优化全部完成之后我用同一个测试仓库跑了 7 轮生成记录两个指标目录重复率两轮生成的目录文本完全一致的比例。行号准确率随机抽取 200 个代码块检查其行号与真实源文件是否一致。测试环境保持完全一致同一个 DeepWiki 版本、同一个模型 checkpoint、固定 temperature0、固定 seed、单卡推理、关闭并行采样。5.2 优化前后的数据对比指标优化前优化后7 轮目录完全一致占比28.5%100%目录锚点点击成功率85%100%代码块行号准确率62%96.5%单轮全量生成时间22 分钟18 分钟加缓存后 6 分钟需要人工 review 的文档比例40%12%行号准确率没有到 100%原因不在脚本而在于部分 AI 生成的代码块是“示例代码”不是源码的完全拷贝。这类代码块按我的设计本来就不该强制加行号所以这 3.5% 的误差其实属于“合理容错”。我对这个结果是满意的尤其是目录确定性做到了 100% 之后团队再也不用花时间核对“这一版目录和上一版差在哪”。文档 diff 终于变得干净可控。5.3 优化带来的额外收益一个意外收获是确定性目录让后续的国际化变得简单了。之前目录经常变翻译平台上的双语对照经常失配。现在目录稳定翻译记忆库TM的命中率提高了很多翻译成本下降了大概四分之一。另一个收益是 CI 友好。我们把文档生成嵌入到了 CI 流程里每次 push 后自动重新生成文档并检查目录是否与上次一致。如果目录发生变化CI 会拦截并提示开发者确认是否有意改动目录结构。这个检查在团队协作场景下非常有用能避免有人不小心改了一个文件名导致整个文档目录全部漂移。6. 常见问题排查与避坑实录6.1 行号漂移代码更新后行号全错这是最常出现的问题。代码仓库每天都在变新增了几行代码之后原本的文档行号就会往下偏移。我的处理方案是给文档生成加上“保鲜期”——仓库文件哈希发生变化后对应章节自动标记为过期下次生成时必须重新计算行号。同时在文档页面顶部显示“本页最后校验时间”和“对应的 commit hash”至少让读者知道这份文档是基于什么版本生成的。6.2 目录与正文标题不一致这类问题通常发生在模型把标题稍作改写之后。比如目录里是## 3.2 API Key 管理正文里被模型写成了## 3.2 API Keys Configuration。前面的锚点规范化步骤已经能兜住大部分问题但如果模型大量改写标题你会看到“正文标题和目录标题不一致”的告警。我的建议是把这类告警从 warning 提升为 error强制生成流程中断而不是让一个错误目录混进文档库。6.3 增量缓存导致“永远不更新”增量构建的坑也很典型某个文件内容变了但它的缓存键没变于是生成的文档一直是旧的。排查后发现是 prompt 版本号没有在代码修改时同步更新。后来我把 prompt 模板的内容哈希也编进缓存键里任何 prompt 修改都会自动导致缓存失效问题彻底解决。6.4 大仓库超时与降级策略当仓库文件数超过 1000 个时一次性把全部文件内容塞给模型是不可能的。我的策略是分层生成先对目录树做一次全球扫描生成每个模块的摘要再对每个模块单独调用模型生成详细内容。如果某个模块内容过多就继续往下拆分。这个策略本身就依赖确定性目录——目录结构稳定拆分点才能稳定否则每次拆出来的模块都不一样缓存和增量也就无从谈起。6.5 一个关于 token 成本的提醒确定性目录生成虽然是代码逻辑不消耗 LLM token但它需要读一遍文件系统。对于超大仓库文件遍历本身可能消耗几十秒不过相比大模型推理动辄几分钟这几十秒完全值得。真正贵的是“目录注入 prompt”之后模型可能在正文里再次生成目录浪费几百 token。所以要记得在 prompt 里加一行“正文中不要再生成目录”。7. 一些个人经验总结这次优化的核心体会是AI 生成的文档必须要有一个“非 AI 的骨架”来兜底。代码行号和确定性目录本质都是把最终结果的关键部分从“模型自由发挥”变成“代码强制决定”。模型仍然是内容的主要生产者但结构、顺序、锚点、行号这些“框架性信息”不应该让模型去决策。给正在做类似事情的同学一个建议先跑 3 次基线把两次输出 diff 一下你会发现很多你以为“没问题”的地方其实都在悄悄变化。不要试图在一次优化里解决所有问题先把目录和行号这两个最容易让人困惑的问题解决掉文档的可用性就会有质的提升。最后一个小技巧把生成文档后的“行号准确率检查”和“目录重复性检查”做成一个独立的校验脚本挂到 CI 上。它不是针对 DeepWiki 的特定逻辑而是通用的文档质量守卫未来即使换用其他生成工具这套思路也能直接复用。 DeepWiki 文档优化：代码行号注入与确定性目录生成实战
1. 先说清楚这次优化到底在治什么病DeepWiki 这类自动文档生成工具核心价值是让 AI 去读代码仓库、再把理解沉淀成一篇篇可维护的文档。但跑过一段时间的同学应该都有体会文档“能生成”和文档“能长期用”完全是两回事。我这次做的优化就是针对两个最刺手的细节——代码行号Code Line Numbers和确定性目录生成Deterministic Table of Contents Generation。先说代码行号。AI 在解释某个函数时经常会在文档里写“请看src/service.py的 handle_request 方法”但这句话是空的读者得自己打开文件去翻。更麻烦的是如果文档里的代码块没有行号团队在评审、答疑、定位问题时只能靠“大约在第 80 行附近”这种模糊表述来回沟通成本非常高。如果能在生成的 Markdown 代码块里带上真实文件的行号并且在正文引用处也明确标注“第 72 到 86 行”这个文档的可追溯性直接上了一个台阶。再说确定性目录。LLM 生成目录时只要模型参数不变、输入不变理论上结果应该稳定但实际跑下来会发现同一个仓库昨天生成的目录和今天生成的目录可能顺序完全不同甚至章节编号都会变。对于个人笔记这无所谓但一旦文档要嵌入 CI、对外发布或多人协作目录变化就意味着链接失效、评审反复、diff 混乱。所谓“确定性”就是希望同一份代码在同样的配置下无论跑多少次产出的目录结构、章节顺序、锚点名称完全一致。这篇文章我会按“问题拆解——环境准备——行号方案——目录方案——实测对比——踩坑记录”的顺序展开。适合正在用 DeepWiki 做自动文档、或者用各类 LLM 生成技术文档并希望结果可复现的工程师。我会把每一步的取舍讲清楚并提供可以直接抄走的脚本和配置。2. 动手之前的准备环境、基线和问题定位2.1 把 DeepWiki 跑起来并锁定版本DeepWiki 本身是开源项目安装方式不复杂但有个关键点不要直接拉 latest而是要把版本锁死。因为 LLM 生成的稳定性不仅取决于你的 prompt还取决于代码版本、依赖版本、甚至 Python 版本。哪怕只是依赖库的小版本升级都可能让你之前调好的“确定性”消失。我当时是这么做的git clone https://github.com/your-fork/deepwiki.git cd deepwiki git checkout v0.4.2 # 记录你实际使用的版本 python -m venv .venv source .venv/bin/activate pip install -e .注意这里强烈建议 fork 一份到自己仓库因为后续可能要改少量源码。用官方仓库再拉分支升级时冲突会比较多。锁版本的目的是为了让“同一仓库 同一配置 同一模型参数”在多次运行下具备可比性。如果不锁版本后面做的任何优化都很难归因。2.2 准备测试仓库和生成基线建议选一个中等规模、结构稳定的仓库来做基线测试。我用的测试仓库大约 30 个 Python 文件、5 个目录层级总代码量 8000 行左右。规模太小测不出稳定性问题规模太大又是给调试添堵。生成基线时先不做任何优化直接跑一遍完整流程把输出保存为baseline_v1。记住这个基线有两个作用一是后面对比行号和目录的改进效果二是用来观察“不稳定的具体表现是什么”。比如我第一轮基线就跑出两个典型问题同一个章节第二次生成时标题从## 3.2 API 鉴权变成了## 3.2 鉴权机制代码块里的行号完全错位文档里写“第 15 行”但真实代码里那个函数在第 28 行。这种不确定性靠肉眼 review 很难全部发现所以后面我专门写了一个校验脚本自动化对比两次生成结果。2.3 确认生成链路里的三个不稳定点在动手优化之前我花了半天把 DeepWiki 的生成链路梳理了一遍最后定位到三个关键不稳定点第一是 LLM 采样过程。目录、标题这类文本生成天然有概率性即使 temperature 设为 0某些模型在 batch 推理、并行解码时仍会出现微小差异。第二是 Prompt 构造顺序。文档的生成依赖从代码库提取的上下文如果上下文里文件列表的顺序是动态的比如来自 set 遍历或文件系统读取顺序那么最终拼接出来的 prompt 每次可能都不一样。第三是后处理逻辑。有些章节标题需要做 slug 化转成锚点如果对中文、空格、特殊字符的处理规则不统一同一个标题在不同环境下会生成不同的锚点。明白这三个点之后优化方向就很清晰了要么在源头把 prompt 输入变成确定性排序要么在后处理阶段覆盖掉 LLM 的不稳定输出。我最终采用的是“前后夹击”的策略两个方案都上了。3. 代码行号从“大概位置”到“精确锚点”3.1 三种行号注入方案怎么选给代码块加行号听起来很简单真正落地时会发现有三条路线方案一让 LLM 自己输出行号。也就是在 prompt 里写“请在每个代码块左边加上真实行号”。我试过效果不稳定。模型经常把行号写错尤其是遇到空行、注释、多行字符串时它“理解”的行号和实际文件行号经常差几行。方案二生成后再用脚本统一注入行号。也就是文档先正常生成代码块内容保持原样然后跑一个后处理脚本读取代码块内容和真实源文件比对找到对应行号再插入到每个代码行前面。这个方案可控性高因为有真实文件作为“唯一事实来源”。方案三基于语法树AST精确计算函数起始行只给关键代码段加行号范围标注。这个适合在大仓库里做“精确导航”但实现成本高而且不同语言的 AST 规则不一样。我最终选了方案二为主、方案三为辅。方案二解决了 95% 的问题方案三用来处理那些“同一个函数被拆成多段展示”的特殊情况。3.2 后处理脚本真实行号注入核心思路不复杂Markdown 里的每个代码块都会附带语言标签比如python我用 Python 脚本解析文档里的代码块然后把每一行代码当作字符串在源文件里去查找这行内容首次出现的位置从而确定行号。直接看脚本import re import json from pathlib import Path def find_line_number(content: str, source_text: str, start_hint: int 0) - int: 在源文本中查找 content 首次出现的真实行号 idx source_text.find(content, start_hint) if idx -1: # 内容可能跨行或被格式化退化为模糊匹配 idx source_text.find(content.splitlines()[0] if content.splitlines() else content) if idx -1: return None return source_text[:idx].count(\n) 1 def process_markdown(md_path: str, repo_root: str) - str: md Path(md_path).read_text(encodingutf-8) lines md.splitlines() output [] in_code False lang code_buf [] code_start_idx 0 def flush_code(): nonlocal code_buf, in_code if not code_buf: return # 通过代码块第一行注释中的路径信息定位源文件 path_hint for cl in code_buf: m re.match(r\s*(?:#|//|--|/\*)\s*file\s*[:\s](\S), cl) if m: path_hint m.group(1) break if not path_hint: output.extend(code_buf) code_buf [] in_code False return src_file Path(repo_root) / path_hint if not src_file.exists(): output.extend(code_buf) code_buf [] in_code False return src_text src_file.read_text(encodingutf-8) # 去掉代码块里的 file 注释行避免污染展示 cleaned [cl for cl in code_buf if not re.match(r\s*(?:#|//|--|/\*)\s*file, cl)] # 计算每行的源文件行号 last_idx 0 for i, cl in enumerate(cleaned): line_no find_line_number(cl, src_text, last_idx) if line_no is None: output.append(f {cl}) else: # 补齐为4位行号方便对齐 output.append(f{line_no:4} | {cl}) last_idx max(0, line_no - 1) if line_no else 0 code_buf [] in_code False for idx, line in enumerate(lines): if line.strip().startswith(): if not in_code: in_code True lang line.strip()[3:].strip() code_buf [] code_start_idx idx else: flush_code() output.append(line) continue if in_code: code_buf.append(line) else: output.append(line) # 处理文档末尾可能未闭合的代码块 if in_code: flush_code() return \n.join(output)这个脚本有几个设计细节值得说明第一代码块里需要有定位信息我采用约定file path/to/file.py注释。因为 AI 生成代码时不一定能准确回忆文件路径所以在 prompt 里要求它“在每个代码块第一行注明该代码来自哪个文件”。这样脚本才能把代码映射到真实源文件。第二查找行号时用了start_hint参数。每次找到一行之后下一次查找从这一行附近开始这样既快又避免重复匹配同一个函数里的相同代码行。第三对于“AI 生成的示例代码并不完全等于源文件”的情况脚本做了降级处理如果整行找不到就取第一行来模糊匹配如果还是找不到就只输出空格占位不让文档报错。3.3 边界情况多文件、重复代码和动态生成内容实际仓库里会遇到很多让脚本崩溃的场景我踩过的坑主要有三个第一个是同一段代码在多个文件里重复出现。比如两个文件都有def get_config():脚本搜索时可能匹配到错误的文件。解决办法是把搜索范围缩小到file指定的文件其次是查找时带上前后几行上下文。我的做法是拼接相邻 2 行的内容作为搜索键错配率明显下降。第二个是 AI 对代码做了精简或改写。很多文档为了讲清原理会把真实代码压缩成伪代码。这种情况下硬找行号没有意义。我的策略是如果代码块和真实源文件的相似度低于 70%就直接不强行加行号改为在代码块前加一个“代码摘要”标注说明这是经过简化的示例。第三个是动态生成或临时文件。仓库里有些代码是构建脚本临时生成的不存在于源码中。我的处理比较简单找不到文件就跳过不加行号同时把这类文件加入exclude列表避免每次生成都触发告警。3.4 行号在页面里的交互行号注入之后还需要让它在页面里真正可用而不只是显示一堆数字。我做了两件事一是在 Markdown 渲染层开启行号样式。由于 DeepWiki 默认的渲染器不一定支持行号我直接在生成的 HTML 页面上做了轻量级前端增强把|分隔的行号列变成>from pathlib import Path import re def safe_anchor(title: str) - str: # 统一锚点生成规则 title title.strip().lower() title re.sub(r[^a-z0-9\u4e00-\u9fa5], -, title) title title.strip(-) return title def generate_toc(repo_path: str) - str: root Path(repo_path) toc_lines [] def walk_dir(current: Path, level: int): dirs sorted([p for p in current.iterdir() if p.is_dir()], keylambda p: p.name) files sorted([p for p in current.iterdir() if p.is_file()], keylambda p: p.name) for d in dirs: # 跳过隐藏目录、构建目录、依赖目录 if d.name.startswith(.) or d.name in (node_modules, venv, __pycache__, dist, build): continue indent * level title d.name toc_lines.append(f{indent}- [{title}](#{safe_anchor(title)})) walk_dir(d, level 1) for f in files: if f.name.startswith(.) or f.suffix not in (.py, .md, .js, .ts): continue indent * level title f.stem toc_lines.append(f{indent}- [{title}](#{safe_anchor(f.stem)})) walk_dir(root, 0) return \n.join(toc_lines)这个脚本生成的是一个 Markdown 格式的目录可以直接放在文档开头。因为它是纯文件系统驱动的不经过 LLM所以输出是绝对确定的——同一份代码无论跑多少次目录都一样。但这里有个重要问题只给目录不告诉模型每个章节该写什么模型可能还是把章节内容串到错误的标题下面。所以我还会把这份目录作为“大纲约束”注入到生成 prompt 里明确告诉模型“必须严格按这个目录顺序写不能新增或删除标题”。4.4 方案 C缓存与增量重建当仓库规模变大每次全量生成文档的时间和成本都很高。为了保持“确定性”的同时控制成本我引入了缓存机制。思路是把每次生成的文档和源仓库的文件哈希一起存起来。下次运行时先对比当前仓库的文件哈希和上次的哈希如果某个文件没有变化就直接复用上次生成的对应章节不重新调用模型。这样既保证了目录稳定又让增量构建变快。缓存键的设计很关键。我用的键是“文件相对路径 文件内容 SHA256 模型版本 prompt 模板版本”。如果只缓存文件内容一旦你改了 prompt就会拿到旧内容所以必须把 prompt 模板版本也加进键里。import hashlib import json def hash_file(path: Path) - str: h hashlib.sha256() h.update(path.read_bytes()) return h.hexdigest() def cache_key(rel_path: str, content_hash: str, model_version: str, prompt_version: str) - str: raw f{rel_path}:{content_hash}:{model_version}:{prompt_version} return hashlib.sha256(raw.encode()).hexdigest()增量构建的难点在于“父目录和子目录的联动”。如果一个模块的目录结构变了子章节的生成结果也需要失效。所以我做了一个简单的依赖图任何文件的哈希变化都会让它在目录树上的所有祖先节点缓存失效。4.5 目录与页面锚点的联动有了确定性目录之后还必须确保目录里的锚点和正文标题的锚点对齐。LLM 生成的标题经过 Markdown 渲染后锚点规则可能和目录生成脚本不一致。我的做法是在生成最终 HTML 之前统一跑一个“锚点规范化”步骤从目录里提取所有标题。对每个标题生成一个id属性。在正文里查找对应标题并写入相同的id。如果正文里找不到某个标题说明模型漏写了章节这时用占位符补上并打一条警告日志。这样做之后目录点击跳转的成功率从原来的约 85% 提升到了 100%。锚点这个细节很多人忽略但一旦团队开始用目录导航就会发现错一个锚点基本等于这个章节“失踪”了。5. 实测结果稳定性的提升到底有多少5.1 我的验证方法优化全部完成之后我用同一个测试仓库跑了 7 轮生成记录两个指标目录重复率两轮生成的目录文本完全一致的比例。行号准确率随机抽取 200 个代码块检查其行号与真实源文件是否一致。测试环境保持完全一致同一个 DeepWiki 版本、同一个模型 checkpoint、固定 temperature0、固定 seed、单卡推理、关闭并行采样。5.2 优化前后的数据对比指标优化前优化后7 轮目录完全一致占比28.5%100%目录锚点点击成功率85%100%代码块行号准确率62%96.5%单轮全量生成时间22 分钟18 分钟加缓存后 6 分钟需要人工 review 的文档比例40%12%行号准确率没有到 100%原因不在脚本而在于部分 AI 生成的代码块是“示例代码”不是源码的完全拷贝。这类代码块按我的设计本来就不该强制加行号所以这 3.5% 的误差其实属于“合理容错”。我对这个结果是满意的尤其是目录确定性做到了 100% 之后团队再也不用花时间核对“这一版目录和上一版差在哪”。文档 diff 终于变得干净可控。5.3 优化带来的额外收益一个意外收获是确定性目录让后续的国际化变得简单了。之前目录经常变翻译平台上的双语对照经常失配。现在目录稳定翻译记忆库TM的命中率提高了很多翻译成本下降了大概四分之一。另一个收益是 CI 友好。我们把文档生成嵌入到了 CI 流程里每次 push 后自动重新生成文档并检查目录是否与上次一致。如果目录发生变化CI 会拦截并提示开发者确认是否有意改动目录结构。这个检查在团队协作场景下非常有用能避免有人不小心改了一个文件名导致整个文档目录全部漂移。6. 常见问题排查与避坑实录6.1 行号漂移代码更新后行号全错这是最常出现的问题。代码仓库每天都在变新增了几行代码之后原本的文档行号就会往下偏移。我的处理方案是给文档生成加上“保鲜期”——仓库文件哈希发生变化后对应章节自动标记为过期下次生成时必须重新计算行号。同时在文档页面顶部显示“本页最后校验时间”和“对应的 commit hash”至少让读者知道这份文档是基于什么版本生成的。6.2 目录与正文标题不一致这类问题通常发生在模型把标题稍作改写之后。比如目录里是## 3.2 API Key 管理正文里被模型写成了## 3.2 API Keys Configuration。前面的锚点规范化步骤已经能兜住大部分问题但如果模型大量改写标题你会看到“正文标题和目录标题不一致”的告警。我的建议是把这类告警从 warning 提升为 error强制生成流程中断而不是让一个错误目录混进文档库。6.3 增量缓存导致“永远不更新”增量构建的坑也很典型某个文件内容变了但它的缓存键没变于是生成的文档一直是旧的。排查后发现是 prompt 版本号没有在代码修改时同步更新。后来我把 prompt 模板的内容哈希也编进缓存键里任何 prompt 修改都会自动导致缓存失效问题彻底解决。6.4 大仓库超时与降级策略当仓库文件数超过 1000 个时一次性把全部文件内容塞给模型是不可能的。我的策略是分层生成先对目录树做一次全球扫描生成每个模块的摘要再对每个模块单独调用模型生成详细内容。如果某个模块内容过多就继续往下拆分。这个策略本身就依赖确定性目录——目录结构稳定拆分点才能稳定否则每次拆出来的模块都不一样缓存和增量也就无从谈起。6.5 一个关于 token 成本的提醒确定性目录生成虽然是代码逻辑不消耗 LLM token但它需要读一遍文件系统。对于超大仓库文件遍历本身可能消耗几十秒不过相比大模型推理动辄几分钟这几十秒完全值得。真正贵的是“目录注入 prompt”之后模型可能在正文里再次生成目录浪费几百 token。所以要记得在 prompt 里加一行“正文中不要再生成目录”。7. 一些个人经验总结这次优化的核心体会是AI 生成的文档必须要有一个“非 AI 的骨架”来兜底。代码行号和确定性目录本质都是把最终结果的关键部分从“模型自由发挥”变成“代码强制决定”。模型仍然是内容的主要生产者但结构、顺序、锚点、行号这些“框架性信息”不应该让模型去决策。给正在做类似事情的同学一个建议先跑 3 次基线把两次输出 diff 一下你会发现很多你以为“没问题”的地方其实都在悄悄变化。不要试图在一次优化里解决所有问题先把目录和行号这两个最容易让人困惑的问题解决掉文档的可用性就会有质的提升。最后一个小技巧把生成文档后的“行号准确率检查”和“目录重复性检查”做成一个独立的校验脚本挂到 CI 上。它不是针对 DeepWiki 的特定逻辑而是通用的文档质量守卫未来即使换用其他生成工具这套思路也能直接复用。