CodexQA该不该拿来画仓库地图

CodexQA该不该拿来画仓库地图

你让编程助手画一张架构图。箭头很全。仓库里经常没有那些边。

CodexQA 是一套装在 Cursor、Claude Code、Codex、OpenClaw 里的本地技能包。GitHub 上公开的是说明书，真正算图的程序要另外安装，而且不公开源码。这里只讲其中一支：codexqa-code-wiki，以前叫 code-wiki。

它要回答的问题很窄。这个仓库分成几块，哪一块是枢纽，新人从哪一页读起。该不该拿来画仓库地图，取决于你要的是核对，还是一段好看的聊天。

谁会为这张图停下来

三类人用得上。

刚接手一个没人讲得清的仓库。README 写了愿景，没写「改支付会碰到谁」。你需要一张能指着说的图，而不是再听一遍介绍。

带新人，或者让编程助手进仓。没有阅读顺序时，助手会从它觉得像入口的文件开始讲。你要的是一条顺着真实调用走的路。

负责看架构有没有被改散。一次改动看起来只动了几个函数，分层可能已经串了。先有一张对照，再谈这次 diff 伤到哪。

另外一些人会点进来，但用不对。你要审这一次改动、圈回归范围，换 codexqa-code-analyzer。要扫 bug 和密钥，换 codexqa-defect-analyzer。要一份能发给评审人的报告，换 codexqa-code-reviewer。code-wiki 不打 P0，也不审 PR。

问题是，这四件事经常被塞进同一句「帮我看看这个仓库」。助手就会开始编。点名要地图时，把范围说死：只用 wiki inputs，不要跑 LLM wiki。

它做的不是总结，是三步

第一步在你自己的电脑上建索引。命令是 codexqa index，后面跟仓库路径。它把函数和调用收成一张符号图，存在 ~/.codexqa/。这一步不把仓库交给模型。CLI 卸掉以后，这份本地索引不会自动删。

第二步导出 wiki inputs。你可以把它理解成「把符号图按团切开，写成 JSON」。团有个学名，叫社区，算法是 Leiden，再叠加目录、模块这些先验，以及页数上限。所以一页地图常常不是资源管理器里的那个文件夹。一个真包可能被拆开，没关系的文件也可能被并到一页。但文件夹对上了，不代表调用也这样走。

第三步才轮到助手。它读 SKILL.md，只许按 JSON 填一份 HTML。版式像 DeepWiki：左边目录，中间正文，旁边本页目录，默认简体中文。社区编号写成 P01。符号名保持原样。能当证据的只有每一行上的 input。system 和 user 那两段是提示词模板，不是证据。

这是仓库里的 docs/assets/previews/code-wiki.png，对应页面标题是「codexqa — 架构知识图谱」。能看清成品长什么样：左边是目录，中间是总览，右边是本页目录。已知边界写明，这类示例图用来说明报告契约，不是一份你可以拿去复现的公开分析。图里的模块结论，以你自己仓库导出的 JSON 为准。另外两张浅色、深色 svg 只是一行技能名，没有信息，不用。

有两件命令明确不要跑。不带 --no-llm 的 codexqa wiki 会去调模型。wiki embed 和 query wiki 要一份已经嵌好的 wiki。图上的事实，JSON 里已经有了。可选的 wiki --no-llm 只是把规则页存进 Web UI，报告仍然以 wiki inputs 为准。你可能会问，助手填 HTML 算不算又叫了一次模型？算。它只能填，不能改图。

地图上的词，别按字面猜

社区不是「这个目录很重要」。它是聚类切出来的一团。切完要看 stats、summary，再看 communities 和 selected 是否一致。对不上，就别当成完整结论。stub 节点和重名符号会把置信度拉低。然而切得再整齐，也不等于线上就这么走。

不调模型时，页标题是规则起的，常常就像目录名。这是预期。签名撑不住，不要改成好听的产品名。（无摘要） 不是一条发现。architecture、overview、visualization 这几类导出只有规则标题，没有模型写好的正文。

边也有死规定。子图要按 Entry、Application、Domain、Storage 分层。写成 Renderer、Compiler 这种包名，报告不合格。deps 为空的模块留在外围，不许为了图好看塞进某一层。deps 和 cross_community 是符号图上数出来的。JSON 里没有的边，助手不能补。阅读路径同理：相邻两步必须有列出的依赖。

四个点全连上，只是为了把「有边」和「没边」分开。真实仓库不会这么整齐。

最容易看反的是空依赖。deps 为空，意思是没有计入的跨社区边。不是没人调用，更不是可以删。而且这是静态关系。配置里拼出来的调用、反射、运行时注册，图上可以是断的。拿它证明「线上没有流量」，证据不够。不过先别把它读成「这段代码没人用」。

还有三个字段别读满。call_chain 和 method_flows 是篇幅预算里的摘录，不是完整方法。called_by 是这份摘要里的被调用次数，不是线上流量。导览只是沿着已有的边走一条路，不证明新人只该读这些文件。

仓库总说明里有一组很硬的数字。你可能会问，那个 7/7 能不能给地图背书？inventory-service 放了 7 个语义缺陷和 4 个诱饵，Composer 在 2026-09-08 跑了一次，召回 7/7，陷阱误报 0。

那是缺陷扫描的单次记录。code-wiki 自己写明了：目前没有公开的宿主运行记录，也没有独立的质量评测。示例图是在说明报告长什么样。别把 7/7 安到这张地图上。

你能核对说明书，核对不了算法

技能文件、操作说明、报告模板在 openqa-cn/codexqa，许可证是 Apache-2.0。SKILL.md 标的版本是 1.2.0。codexqa 这条命令来自另一个包 @openqa-cn/codexqa。分析引擎闭源，源码不在这个 GitHub 仓库里。安装会从 npm 下载。

不过你能核对的范围，比「完全开源」小得多。说明书管得住助手：不许编边，不许拿 README 当证据，孤立模块不许进功能层。聚类怎么切，你在网页上对不了。本仓库的持续集成现在也不会安装、不会执行这个闭源命令。技能和命令还没有正式的版本对照表。反馈时带上 codexqa --version。

Node.js 要 18 或更高。命令找不到，把 $(npm prefix -g)/bin 加进 PATH。已经装过就不要重装。Cursor 放到 ~/.cursor/skills/，Claude Code 放到 ~/.claude/skills/，放进项目里也行。

怎么判断这张图能不能收

怎么判断？三处对上再信。stats 和 summary 说明索引在。communities 和 selected 对得上。你关心的那条边，在 deps 或 cross_community 里真有，不是助手后补的。

什么时候别用？仓库还没 index，或者导出是空的，先查索引。动态调用很多的项目，静态图会偏瘦，只能当阅读地图，不能当流量证据。前提是你受得了规则标题不好看。为了给领导看而改名，地图就废了。--limit 8 是在限制页数，不是说仓库只有 8 个模块。

如果你是今晚要进一个陌生仓库的人，第一步先装技能和命令行，再对这个仓库建索引。别开口就问「帮我总结架构」。

范围可以照下面说：

给这个仓库建代码知识图谱。只用 wiki inputs，不要跑 LLM wiki。先出架构地图，再讲核心模块和一条阅读路径。

技能：

npx skills add openqa-cn/codexqa --skill codexqa-code-wiki

引擎：

npm install -g @openqa-cn/codexqa --registry https://registry.npmjs.org/

索引和导出：

codexqa index /path/to/repo
codexqa wiki inputs /path/to/repo --kind architecture --limit 8
codexqa wiki inputs /path/to/repo --kind overview
codexqa wiki inputs /path/to/repo --kind page --id p01

你让编程助手画一张架构图之前，先要这份 JSON。仓库里有的边，才能留在图上。没有的边，不要收。