修改生成文档的AI智能体应用，不混淆新旧两套技术栈

## 先从代码中找出真正的启动命令和配置 从包元数据、控制台入口点、配置加载器、环境变量处理逻辑以及创建运行时工作区的代码开始检查。当这些可执行部分与说明文档冲突时，以前者为准。 - 确认哪个命令会启动主应用。 - 确认哪个命令会提供旧版服务或与MCP兼容的服务。 - 沿着每个命令追踪到实际的模块和函数。 - 找出配置模板和工作区的默认行为。 - 验证所有被引用的路径都存在于当前检出内容中。 将过时的概览视为历史背景，不要把它当作当前启动路径的依据。 ## 判断改动归现行栈还是旧版栈负责 一个仓库可能同时包含现行产品栈和较早一代的库，后者仍在为专用端点提供服务。编辑前先确定负责该行为的栈。 现行栈可能负责： - 命令行界面和引导流程； - 编排与多智能体执行； - 研究、生成和设计智能体； - 用于搜索、反思、转换和任务管理的MCP风格工具； - 配置、日志和工作区实用工具； - 基于浏览器的HTML转换和Node辅助程序； - 面向集成的测试。 旧版栈可能仍负责模板驱动的生成、布局推导、解析、评估和兼容服务器。不要假定在一个栈中修改某个共有概念就会更新另一个栈。 ## 减少特殊情况、用短函数让设计保持简单 优先采用能把边缘情况转化为普通情况的设计，而不是不断叠加条件分支。解决仓库中的实际问题，而不是假想的架构问题。 - 如果直接、运维负担小的方案能满足实际要求，就采用该方案。 - 函数应简短、职责集中且命名清楚。 - 将不必要的复杂性视为缺陷。 - 缩进超过3层，说明应当重构代码。 - 没有具体失败模式时，不要用宽泛的异常包装器隐藏正常控制流。 - 批评应保持技术性，并针对代码、设计或假设，而不是针对个人。 良好判断体现为更少的特殊情况、更小的作用面以及易于验证的行为。 ## 加上类型注解，把依赖项控制在最少 在维护中的栈内一致应用以下约定： - 为函数和方法添加类型注解； - 使用仓库规定的语言编写技术文档和代码注释； - 使用当前的依赖项管理器、仓库搜索工具、语言功能以及受支持的库API； - 优先使用当前的序列化和验证接口，而不是已弃用的形式； - 尽量减少依赖项和代码总量； - 让根包定义聚焦于主要产品； - 对于确实独立的子项目，将其依赖项放在各自的依赖项文件中。 不要只为了整洁而移动依赖项。仅当运行时边界和维护边界确实存在时才将其分离。 ## 沿着相连的部分追踪改动，包括 Python 和 Node 两侧 检查所改行为对应的完整职责路径： - 对于命令行行为，同时检查命令定义、共享命令辅助程序和配置加载； - 对于编排，检查主协调器和相关智能体实现； - 对于MCP行为，判断它应由现行工具服务器还是旧版兼容服务器负责； - 对于导出和转换，同时检查Python编排端和Node转换端； - 对于重复的生成概念，除非任务明确涉及双方，否则只修改负责该行为的栈。 限定变更范围。不要仅仅因为两个栈中出现相似名称，就同时重构双方。 ## 保持现有的配置名称和工作区位置不变 现有配置键、环境变量、引导行为、示例配置和工作区位置共同构成运行时约定。除非任务明确包含迁移，否则保留它们的名称。 浏览器和容器依赖项可能是转换路径的正常运行时要求，而不是可选的开发附加项。原生转换工具、模型凭据、浏览器自动化和容器镜像也可能决定哪些集成测试能够运行。 修改运行时路径时： 1. 找出所有配置来源和默认值。 2. 追踪引导流程和示例如何填入这些值。 3. 检查Python调用方和所有外部转换辅助程序。 4. 保持兼容性，或提供明确的迁移路径。 ## 用代码核对旧文档，并按所需环境给测试分类 在依赖文档中的说法之前，先对照当前文件树和可执行入口点进行验证。旧文档可能仍能解释有用概念，但同时提到了已移除的文件或已过时的启动流程。 按所需条件对测试分类： - 用于独立逻辑的单元测试； - 用于专用数据路径的解析器测试或带标记的测试； - 用于沙箱工具、浏览器或PDF转换、图像处理及外部实用工具的集成测试； - 需要凭据或网络服务的模型支持测试。 缺少浏览器、容器镜像、原生转换器或模型凭据属于验证限制，并不能证明无关代码已经损坏。 ## 运行最小但有意义的测试，并报告无法运行的检查 采用范围集中的变更顺序： 1. 确认哪个栈和入口点负责目标行为。 2. 编辑能够完整解决问题的最小作用面。 3. 运行范围最小但有意义的测试子集。 4. 仅将范围扩大到直接耦合的Python、Node、浏览器、容器或兼容路径。 5. 报告所有阻碍验证的依赖项或环境要求。 检查最终差异，确认没有对另一个栈的意外修改、配置约定名称的变更、陈旧文档引用、无关重构或未经测试的跨语言边界。 报告修改了什么、实际执行了哪条路径、哪些检查通过以及哪些检查无法运行。如果所需的运行时依赖项不可用，不要声称已完成全面验证。