architecture-optimizer

name	architecture-optimizer
description	优化 JavaScript、TypeScript、React、Vue、HTML、CSS 和 Node.js 架构，重点关注清晰分层编排、可单测的纯原子函数、可复用的纯编排函数、高内聚低耦合、类型定义清晰的模块边界、业务无关的可复用架构模块、文件体量控制和可维护性。用于审查、设计或重构前端、Node.js、全栈、组件、状态、API、服务、工作流、调度器、流水线或编排器代码。

架构优化器

目标

按代码事实和系统设计优化架构。核心偏好是：主流程由编排函数清晰呈现，细节沉到纯原子函数；可复用编排函数也必须保持纯；模块通过公开入口和入参/出参类型协作；架构级能力脱离业务并可复用；最上层业务实现只要求清晰编排、行为正确、易改。

工作流

1. 先读现状：目录结构、入口、技术栈、关键流程、核心类型、测试、lint、构建约定。
2. 区分函数层级：原子函数、下层编排函数、架构编排函数、最上层业务编排函数。
3. 识别模块边界：业务模块、架构级通用模块、基础设施适配、模块公开入口、入参/出参类型。
4. 检查耦合：循环依赖、深层 import、能力模块互相驱动流程、公共模块带业务语义、全局可变状态和隐式上下文。
5. 控制体量：默认单代码文件不超过 500 行；超过时保留主文件编排骨架，把可命名原子步骤拆到局部结构文件。
6. 区分架构审美标准和实际改造优先级：把问题分为立即值得改、可排期改、仅记录不动；不要把体检标准当成全量重构许可。
7. 给出小步改造：按收益、风险、影响范围和可验证性排序；保持行为不变并运行测试、类型检查、lint、构建。

核心模型

• 原子函数：必须是纯函数、可单测、无隐藏副作用，负责校验、转换、格式化、计算、映射等小步骤。不能纯函数处理的逻辑不归类为原子函数，应放到业务编排、入口层或适配器边界。
• 编排函数：组合原子函数或下层编排函数，呈现流程、顺序、吞吐、并发、重试、取消、降级和错误策略。凡是期望复用的编排函数也必须是纯函数，通过参数接收依赖，通过返回值表达结果。
• 业务编排：最上层业务实现通常不追求复用，因为业务不同会有不同组装方式；只要求主线清晰、行为正确、容易修改。业务编排可以承接必要副作用，但应把副作用隔离在入口、适配器或明确边界处。
• 模块契约：默认就是模块公开函数签名、入参 interface 或 type、出参类型、返回值和错误约定。不要为普通函数调用额外制造 protocol、contract、DTO、port、adapter。
• 显式工程协议：只在跨进程、插件化、多实现切换、异步事件、外部系统边界或测试替身需要稳定抽象时引入。
• 架构级模块：除业务模块外，通用模块应脱离业务语义，可单独迁移到其他项目。它们表达吞吐、调度、缓存、日志、配置、错误、校验、UI 原语、数据访问适配等横向能力。

代码形态

优先让主流程像可执行设计文档：

function run(input: RunInput): RunOutput {
  const a = moduleA(input)
  const b = moduleB(a)
  const c = moduleC(b)
  return c
}

如果文件难以拆到 500 行以内，不要打散主流程。保留主流程编排入口和必要的上层业务编排，把校验、转换、格式化、映射、局部计算等纯原子步骤抽到当前模块局部的 utils/、helpers/、mappers/、validators/ 或同级结构文件；含副作用的适配逻辑应放在入口层、适配器或明确边界处。不要把携带业务上下文的局部工具升级成全局 utils。

前端与 Node

需要更细检查表时读取 references/frontend-node-principles.md。只有在用户请求架构审查、重构实现、前端/Node 最佳实践或需要输出评估清单时才加载该参考文件。

输出要求

• 审查类任务：先列问题，按严重程度排序；每条包含位置、风险、违反原则和建议改法。
• 改造类任务：先说明要改的边界和文件；实施后列出变更、验证命令和剩余风险。
• 设计类任务：优先给出顶层编排伪代码，再列模块、公开入口、入参/出参类型、复用目标和需要显式工程协议的位置。
• 优先级判断：只有影响主流程阅读、阻碍测试/复用、造成循环依赖、隐式副作用、全局状态污染或高频修改痛点的问题，才建议立即改；只是“不够优雅”的问题应标为可延期或不改。
• 不为了套模式增加抽象；不把重构和功能变更混在一起；不默认推翻现有技术栈和命名约定。