2026-06-26 回顾 | idea_world

今天在文档化 source-to-AST 输入流程时，整理了“如何实际将源代码交给 LLM 判断”的方法。

并不是单纯写文档的日子。Godot 相关数据也在实时收集，如果文档只剩抽象的设计图就不行。需要一个标准来确认当前收集的数据实际走了哪些路径、以何种单位被拆分、以及如何形成请求。

为什么先整理这个设计

之所以想先把这个设计文档化，是因为在之前的工作中，担心 AI 会把代码写得奇怪或随意更改请求范围。

尤其是需要发送整个 Markdown，却只实现了只发送前半部分，或者加入了我不想要的硬编码，或者需要查看整个文件却只挑选“核心代码”发送，这些情况一直让我很在意。

所以我没有直接写代码，而是先把“应该向 AI 提出什么请求”“文件应以何种单位展开”“向 AST Parser 输入什么、向 Retriever 输入什么”“LLM 调用需要什么组合”等内容固定在文档中。

最近我发现，比起实现本身，更在思考如何指示 AI，才能让意图不被扭曲。即使是相同的需求，如何限定范围、禁止哪些表达、让 AI 检查哪些证据，结果也会有很大差异。

这篇文档与其说是开发计划书，不如说是为后续交给 AI 实现时，防止请求模糊的基准线。为了防止 AI 任意缩减输入、只挑选核心代码发送、或修改未请求的文件，我先把思路梳理出来。

今日基准

我认为需要用 # <相对路径>/<相对路径> 形式的标题来展开源代码。这些标题的目的不是装饰性地放入提示，而是用于追踪文件来自哪个路径、随后被拆分成哪些片段并传递给 Retriever。

我最初的设想是按路径顺序展开 GitHub 仓库，排除的文件仍然记录在网页 UI 或日志中以便查看。然后把剩余文件拆分成可读取的单位，并持续追踪每个片段来源于哪个原始文件。

在文档化过程中，AI 一直误解的点是“是一次性发送整个文件，还是只发送核心代码”这种二元对立。我认为的流程是先按路径展开文件，再按片段顺序切割并发送。

在我的基准中，.gd 文件是进入 AST Parser 的对象。AST Parser 需要按顺序切割 .gd 中的 a 函数、b 函数、c 函数、d 函数等可解析的单元。若函数单元不明确，则按代码片段顺序切割发送。关键不是“随意挑选核心函数”，而是保持原始顺序和路径进行碎片化，并追踪这些碎片进入 Retriever 的过程。

相反，像 .md 这类在本次源代码分析中决定排除的文件应列入排除名单。重要的是，排除的事实不能消失，需要在网页 UI 或日志中显示哪些文件因何标准被排除。如果有不需要排除的文本类配置文件，则可以不经过 AST Parser，直接按行、段落、键值、节点/资源/连接等单位拆分后直接进入 Retriever，这样更自然。

综上，目前的流程大致如下。

repository path order
  -> "# <relative/path>" file expansion for tracking
  -> excluded file list visible in UI/log
  -> .gd files to AST Parser
  -> AST Parser emits ordered function/code chunks
  -> excluded files are recorded with reason
  -> non-.gd allowed text/config files emit ordered chunks
  -> each chunk goes to Retriever with source path metadata
  -> prompt + current chunk + retrieved evidence
  -> LLM judgment
  -> validation
  -> accumulated project-level result

AI 解析后修正的部分

中间 AI 创建了 repository_file_manifest 之类的独立结构，但这与我设想的方向不同。需要的不是单独的 manifest 存储库，而是以 # <相对路径> 标题展开的文件流为基准，追踪哪些文件被排除、哪些文件被拆分成哪些片段，以及这些片段以何种顺序进入 Retriever。

即使说二进制或资源“不会被读取”也不准确。关键是 不把原始 bytes 输入到 LLM，而不是这些文件在项目判断中完全消失。只要在 .tscn、.import、README 等文本片段中出现资源路径，就可以基于该片段进行判断。

还有一点我觉得需要的是传输调试。AI 不能只挑选 .gd 文件中的核心函数发送。以 # <相对路径> 展开的文件在 AST 解析器中被划分为哪些函数/代码片段，并且这些片段是第几次进入 Retriever，需要能够通过 diff 或 sha256 等方式进行确认。

在 PR 评审中整理的要点

在查看 PR 评审时，我发现 llm_judgment_request 在文档中被两次不同定义。一次侧重 chunk_text、chunk_kind、retrieved_evidence，另一次则包括 chunk_code、surrounding_context、judgment_contract。

如果同一个请求对象在文档中有不同定义，后期实现时必然会摇摆不定。请求 schema 必须统一。特别是要区分 AST chunk 与 direct retrieval chunk 时，需要 chunk_kind；要验证 LLM 判断时，还必须同时整理 retrieved_evidence 与 judgment_contract。

在 Qwen 的评审中，还出现了 README 链接、25 日文档的错别字、链接等意见。但 25 日文档或 workflow 被加入 PR diff 并非我所意图。AI 随意修改的内容混入其中，我发现后要求恢复原状。

范围混杂的问题

在今天的 PR diff 中，我发现 25 日文档和 .github/workflows/qwen-code-pr-review.yml 被加入。这不是我请求的更改。AI 看似随意修改或删除文件，PR 页面显示这些文件被更改或删除。

.github/workflows/qwen-code-pr-review.yml
docs/observations/2026-06-25-qwen-markdown-classification-observation.md
docs/retrospectives/2026-06-25-source-analysis-scoring.md
docs/roadmaps/2026-06-25-qwen-pr-review-workflow.md

于是我要求恢复这些更改。随后这些文件基于 origin/main 被恢复，PR diff 只围绕 README.md 与 docs/roadmaps/2026-06-26-source-to-ast-input-flow.md 整理。

通过这过程，我认识到即使把文档工作交给 AI，也必须先强力固定更改范围。撰写回顾或路线图文档同样需要像代码更改一样管理 PR 范围。

今日结论

今天再次确认的核心是：“按路径展开的文件，以何种标准被排除、被拆分成哪些片段、这些片段以何种顺序传递给 Retriever 以及 LLM 判断”。不是一次性放入全部文件，也不是随意挑选核心代码。

当前的基准如下：

文件以 # <相对路径> 标题展开，该标题用于记录原始路径和片段追踪。
被排除的文件必须能够在网页 UI 或日志中查看。
.gd 文件交由 AST 解析器处理，AST 解析器按原始顺序生成函数或代码片段。
像 .md 这类决定排除的文件保留在排除列表中，并能在网页 UI 或日志中查看。
未排除的文本类配置文件不走 AST，而是按行、段落、配置块等单元进行切片。
每个片段携带 source path、chunk order 等追踪信息后传入 Retriever。
LLM 调用以 “提示词 + 当前片段 + Retriever 检索结果” 为单位多次执行。
项目判断只有在多个片段的判断结果累计后才可能进行。

数据收集仍在进行中。因此今后的文档不应只是“看起来合理的架构”，而必须成为检验实际收集数据如何进入、如何被验证的标准。