架构演进中的 Qoder

核心问题

Growth AIOS 不是一天建成的。在两年多的持续迭代中，架构经历了多次重构——模块拆分、接口统一、通信模式切换、引擎升级。每个重构周期都会问同一个问题：这次改了，下次还记得为什么改吗？

这一章不讲 Growth 的产品架构本身，而是讲一个实践：用文档管理架构演进。

---

使用篇：文档是架构演进的"锚点"

重构最大的成本不是改代码

在一次大规模重构中，我发现了一个规律：

重构代码花 1 天，理清为什么要重构花 3 天，理解当前架构是什么花 5 天。

最大的成本不是"改"，而是"理解"。

没有文档的情况下，每次重构都等于考古——翻代码、猜意图、试错。更糟糕的是，重构完几个月后，连你自己也忘了当初为什么要这么改。

每个模块的 Document 目录

Growth 项目有一个贯穿始终的实践：每个组件模块自带 Document 或 Documents 目录，存放该模块的架构设计文档。

这不是"写了就扔"的文档，而是随着代码演进的活文档。让我们看一组真实数据：

项目	文档数	模块数	覆盖范围
Components	557 篇	15 个模块	核心引擎全组件
Client 项目	378 篇	3 个大模块	桌面端 + Web 端
合计	935 篇	18+ 模块	全产品线

这 935 篇文档不是随意散落的，它们按组件分组，每个组件有自己的目录结构。以文档最密集的几个模块为例：

CLI 模块（159 篇）——按节点类型组织：

CLI/Documents/
├── 架构分析/
├── 脚本引擎/
├── 视频节点/           # 视频处理类节点
├── 通知节点/           # 通知推送类节点
├── 图片节点/           # 图片处理类节点
├── 文档节点/           # 文档处理类节点
├── 文件脚本/           # 文件操作类脚本
├── 自定义节点/          # 通用自定义节点
├── AI 节点/            # AI 交互类节点
└── ...                 # 共 11 个子目录

Workflow 模块（152 篇）——按功能维度组织：

Workflow/Document/
├── 架构设计/
├── 使用教程/
├── 模块设计/
├── 修改记录/           # 每次架构变更的记录
├── Coze 架构分析/
└── WorkflowCoze 架构/

LLM 模块（71 篇）——按架构层次组织：

LLM/Document/
├── 当前架构/
├── 模型管理/
├── 微调/MAF/
├── 信息会话/
├── 修改记录/
├── Agent 架构归档/     # 历史架构方案的归档
├── AiTool 设计/
├── Deerflow 集成/
└── LLM 节点/

Web 端（96 篇）——按业务组件分析：

Web/Document/组件分析/
├── 通用逻辑/
├── 节点列表/
├── 格式处理/
├── 模板管理/
├── 模块分析/
├── Workflow 模块/
├── WPF 桌面集成/
└── ...                 # 共 15 个子目录

关键点：这些文档不是一次性写出来的，而是伴随每次架构重构逐步积累的。每次重构都更新一批文档，新增一批文档，废弃一批文档。

贯穿案例中的应用

"文件压缩节点"开发了一段时间后，发现在某些场景下性能不达标。你需要优化它，但首先得理解这个节点在架构中的位置。

这种情况下，你会去代码里翻找依赖关系吗？不需要。CLI/Documents/视频节点/ 目录下有三篇关于文件压缩的文档，Qoder 读完之后直接告诉你：

这个节点依赖 FileSearch 节点的输出格式，当前瓶颈在循环嵌套的上下文解析。Workflow/Document/架构设计/嵌套上下文参数解析架构文档 中有完整分析。

这就是文档积累的效果——不需要 AI 从零理解代码，它从文档就已经知道架构的全貌。

---

实践篇：文档驱动的架构演进

实践一：每个重构周期都要更新文档

Growth 项目的重构不是"大爆炸式"的，而是以模块为单位逐步推进。每个模块的重构遵循三步法：

Step 1: 文档先行
  更新当前模块的架构文档 → 看清楚现状
  → 记录本次重构要解决的问题和目标

Step 2: 逐步迁移
  每次改动一个文件 → 编译通过 → 确认
  → 同时更新对应的接口文档

Step 3: 文档归档
  将旧架构文档标记为"历史归档"
  → 新架构文档标为"当前架构"
  → 更新 Qoder Memory 记录本次决策

关键是 Step 3 —— 为什么要"归档"而不是"删除"？因为旧架构文档还有价值——新人不理解当前的某些"遗迹"（过时的接口、废弃的参数）时，翻历史文档就能明白这代码为什么还留着。

实践二：修改记录是最被低估的文档

在每个模块的 Document 目录下，几乎都有一个"修改记录"子目录。这些文件记录了每次架构变更的时间、原因和影响范围：

Workflow/Document/修改记录/
├── 2026-03-10-嵌套上下文参数解析架构升级.md
├── 2026-03-25-WorkflowCoze架构分析.md
├── 2026-04-01-工作流上下文管理器架构升级.md
├── 2026-04-15-变量追踪设计文档.md
└── 2026-04-21-Trace 组合嵌套测试问题说明.md

每次修改记录其实回答了三个问题：

• 改了什么（变更范围）
• 为什么改（旧方案有什么问题）
• 怎么改的（新方案的核心逻辑）

当 Qoder 在处理代码时遇到问题，它会先去翻对应模块的修改记录——最近改过什么，可能跟当前问题有关。这是 Memory 机制之外的另一层文档上下文。

实践三：文档的交叉引用

模块间的文档不是孤立的。一个 Workflow 的架构文档会引用 CLI 的节点设计，LLM 的模型管理文档会引用 Workflow 的上下文传递方案。

这种交叉引用形成了一张文档图谱。当 Qoder 需要理解某个模块时，它能沿着引用链主动加载相关文档：

CLI/视频节点/文件压缩设计.md
  → 引用了 Workflow/嵌套上下文架构文档
    → 引用了 LLM/模型管理/AI 节点参数传递

这个能力来自于 Qoder 的 Memory 系统——当文档建立交叉引用时，Qoder 记住这些关系。下次遇到文件压缩节点的问题，它自动知道要加载哪些相关文档。

---

实践篇：Qoder 在架构演进中的具体用法

场景一：重构前先让 AI 读文档

/plan 分析 Workflow 模块的嵌套上下文架构，输出优化方案

不是让 AI 从零扫代码，而是告诉它先读 Workflow/Document/架构设计/ 下的文档。AI 读完文档后再扫代码确认一致性，输出方案。

场景二：用需求记录 Skill 追踪架构变更

每次产生架构变更的需求，不是直接改代码，而是先记录：

/record-architecture-request

需求：文件压缩节点需要支持流式处理
原因：当前方案在大文件场景内存占用过高
影响范围：CLI/视频节点，Workflow/嵌套上下文

这个 Skill 会在对应模块的 Document 目录下生成一个"待处理"的需求记录。等到真正开始重构时，这些记录就是第一手资料。

场景三：增量更新文档而非重写

架构重构后，不需要重写整个 Document 目录。Qoder 的做法是增量更新：

对比文件压缩节点的新旧两版接口设计，
找出文档中需要更新的部分，只改这些部分

AI 对比代码层面的差异，映射到文档中的对应章节，做精准的局部更新。而不是把整篇文档扔给 AI 重写——重写的文档往往丢失了原有的上下文和细微判断。

场景四：生成架构差异报告

当从旧接口迁移到新接口时，让 AI 生成差异报告：

对比旧版 INodeExecutionContext 和新版 INodeExecutionContext，
列出所有接口方法的变更，标注每个变更涉及的模块

AI 分析两个接口的差异，扫描代码库找到所有调用方，生成迁移清单。这份清单本身就成为一页新的归档文档。

---

知识篇：架构文档体系的三层结构

第一层：模块级文档（Document/ 目录）

每个组件模块的架构设计文档，解决"这个模块怎么工作的"。

谁写：负责该模块的开发者 谁读：新加入的开发者、Qoder（需要理解该模块时） 更新频率：每次架构变更时同步更新 例子：CLI/Documents/架构分析/CLI架构演进记录.md

第二层：修改记录（修改记录/ 子目录）

每次架构变更的时间线记录，解决"为什么改成现在这样"。

谁写：执行重构的开发者 谁读：遇到历史遗留问题时的人 更新频率：每次架构变更时新增一篇记录 特点：只追加，不修改——保持历史记录的真实性

第三层：Memory 记录（Qoder 内部）

Qoder 通过 Memory 系统记住的架构决策，解决"AI 下次遇到时自动知道"。

谁写：Qoder（通过用户的自然语言记录） 谁读：Qoder 自己（下次遇到相关问题时自动注入） 更新频率：每次架构决策后记录 特点：自动注入上下文，不需要主动翻文档

三层的关系

模块级文档         ← 人工编写，代码同步
  ↓ 引用
修改记录           ← 人工编写，只追加不修改
  ↓ 注入
Memory 记录        ← AI 自动维护，编码为嵌入向量

前面两层是人写给 AI 看的，第三层是 AI 写给 AI 用的。

为什么这套体系有效

935 篇文档听起来很多，但实际上维护它们的工作量比想象中小：

• 不需要全部维护：核心模块（CLI、Workflow、LLM）占了 382 篇（68%），这些是架构最复杂、重构最频繁的模块，文档投入与复杂度成正比
• 不需要一次性写完：文档是伴随重构逐步积累的，每次重构改 3-5 篇文档，并不费时
• 不需要保持完美：文档是"活"的，允许过期——即使文档比代码落后半个月，也比没有文档有价值

文档的价值不在于"最新"，而在于"记录了当时的设计上下文"。

---

本章小结

实践	内容	对贯穿案例的作用
模块级文档	每个组件自带 Document 目录	快速理解模块架构
修改记录	每次变更记录原因和范围	追踪架构演进历史
Memory 记录	AI 记录架构决策	下次自动注入上下文
需求记录 Skill	先记录需求，再改代码	避免遗漏变更动机
增量更新	只改文档中过时的部分	保持文档的连续性
交叉引用	模块间文档互相引用	跨模块架构分析

关联：第一部分 06（Memory 记忆系统）、章节 04（技能沉淀）。