AI-Analyze：五个不显而易见的设计决策

大部分代码分析工具的文章会讲"支持多少语言、有多少规则、能检测多少漏洞"。ai-analyze 支持 7 种语言、12 条安全规则、4 维度质量评分，这些功能数字在 README 里就能看到。这篇文章不讲功能清单，讲五个容易被忽略但值得深挖的设计决策——每个决策背后都有一个"为什么不那么做"的故事。

决策一：MCP 双策略不是为了性能，是为了安全边界

ai-analyze 实现了两种 MCP 集成策略。表面上看，直接调用 Serena 的 Python API（进程内导入）更快更简单，协议合规的 stdio 客户端（JSON-RPC 2.0 子进程通信）更慢更麻烦。选哪个似乎是个性能问题。

但真正的关键差异不在性能，在安全边界。直接调用策略暴露了 Serena 的全部工具——包括 rename_symbol 和 replace_symbol_body 这些修改源码的操作。你的代码分析器能重命名符号、替换函数体，这意味着一个误判的分析结果可能直接改坏你的代码。stdio 客户端刻意不实现这两个修改操作。原因是：子进程边界天然隔离了写操作。stdin/stdout 管道只能传查询请求和返回结果，无法跨进程修改文件系统。这是一个用架构来约束能力的设计——不是"我不想实现"，是"我不应该让你能做这件事"。

class StdioMCPClient:
    """MCP JSON-RPC 2.0 over stdio transport"""

    async def connect(self):
        self.process = await asyncio.create_subprocess_exec(
            *self.server_command,
            stdin=asyncio.subprocess.PIPE,
            stdout=asyncio.subprocess.PIPE,
        )

    async def send_request(self, method, params=None):
        request = {
            "jsonrpc": "2.0",
            "id": self._next_id,
            "method": method,
            "params": params or {}
        }
        self.process.stdin.write(json.dumps(request).encode() + b"\n")
        await self.process.stdin.drain()
        response = await self.process.stdout.readline()
        return json.loads(response.decode())

两种策略并存的核心判断是：你的 MCP 服务是给自己用的，还是给别人用的？给自己用，直接调用更高效，你能控制自己不做危险操作。给别人用，协议合规是必须的——你不能假设别人的 Agent 会正确使用修改能力，用架构边界把它限制掉比用文档约束更可靠。

决策二：合并层以 AST 为骨架，Serena 只是补充字段

Serena 提供符号结构——类继承、函数调用链、跨文件引用关系。AST 分析器提供复杂度评分、代码味道检测、参数分析、async/static 标记。两个数据源合并时，以谁为主？

直觉可能选 Serena——符号结构是代码的骨架，复杂度和味道是属性。但 ai-analyze 的 UnifiedAnalyzer 选择了 AST 为骨架。原因是：AST 产出的是可操作的指标——"这个函数的认知复杂度是 15，超过了阈值 10"是可以直接行动的发现。"这个类被 3 个模块引用"是结构信息，但无法告诉你该做什么。合并逻辑是以 AST 的文件列表为主循环，Serena 的符号数据作为补充属性挂上去。

更有趣的是，UnifiedSymbol 数据类有一个 serena_data 字段，但合并代码从不填充它。这不是 bug——这是架构占位符。当前流水线已经能用 AST 数据产出有用的分析报告，Serena 数据是未来的增强点，不阻塞当前功能。零运行时开销的架构前瞻。

这个决策传达的设计思路是：数据合并的主循环应该围绕可操作的维度，而不是结构维度。结构信息提供上下文，指标信息驱动决策。

决策三：AI 提示词里加了"反炒作"指令

ai-analyze 有三个 DeepSeek AI 调用：代码质量评估、Docker 策略建议、框架升级分析。每个调用的提示词都把 AST 分析产出的结构化事实嵌入进去——Top 5 复杂函数、Top 10 代码味道、Top 20 依赖关系。AI 不是被要求去发现复杂度问题，而是被 handed 已确认的事实去解读。这种"规则先行、AI 解读"的模式降低了幻觉风险——AI 不能声称"这个项目没有复杂度问题"，因为提示词里明确列出了 5 个复杂度超过 10 的函数。

但最不显而易见的设计决策在框架升级分析的提示词里。有一句显式的指令：

"如果当前版本已经是最新稳定版，请明确说明，不要强求升级"

这句指令在对抗 LLM 的一个固有倾向：总是建议改动。LLM 培训数据里充满了"升级到最新版本"、"迁移到新框架"的建议，因为技术文章和 Stack Overflow 答案天然偏向推荐改变。但现实场景里，一个 React 18 项目不需要升级到 React 19 RC，一个 Python 3.11 项目不需要升级到 3.12。不加这条指令，AI 几乎一定会建议升级，哪怕升级没有实际收益，哪怕升级会引入兼容风险。

这跟三个 AI 调用的温度梯度是同一思路：代码质量评估用 temperature=0.3（建议可以有创造性），Docker 策略和框架升级用 temperature=0.2（输出必须保守）。温度梯度映射的是后果严重性——糟糕的质量建议只是烦人，糟糕的 Docker 配置会导致部署失败，糟糕的升级建议会导致生产故障。后果越严重，随机性越低。

决策四：安全维度权重只有 0.15，因为它是"弱指标"

质量评分公式：overall = complexity × 0.25 + maintainability × 0.35 + reliability × 0.25 + security × 0.15

为什么可维护性权重最高（0.35）？因为它是长期成本驱动因子——不可维护的代码每次修改都更难，技术债指数增长。复杂度是"当前状态"指标，可靠性是"风险"指标，可维护性是"趋势"指标，趋势预测未来成本，权重应该最高。

但更有意思的是为什么安全权重最低（0.15）。安全评分的计算是 max(0, 100 - code_smells // 2 * 10)——把代码味道数量除以 2，当成安全问题的粗略代理。代码作者在注释里承认了这一点："实际应该使用专门的安全分析工具"。安全评分是一个不成熟的指标。把它加权到 0.25，这个粗略代理就会主导整体评分，产出不可靠的结果。对弱指标低权重比高权重更诚实——你不想让一个分母除以 2 的近似值决定一个项目能不能部署。

安全扫描器本身是正则匹配的 12 条规则，风险评分用的是严重度几何加权（INFO=0.1, LOW=0.25, MEDIUM=0.5, HIGH=0.75, CRITICAL=1.0）加饱和曲线（10 个 CRITICAL 满分 100，再多也不涨）。几何加权防止了"修一堆 LOW 级问题来冲高分"的规避策略，饱和曲线防止了大型遗留项目因发现数量多而得分虚高。这些设计让安全扫描器本身很可靠，但安全维度的评分公式是个粗糙的代理，所以权重只能保守。

决策五：缓存不是"读最快的层"，而是"读时自动往快层迁移"

三级缓存系统（内存 → 文件 → Redis）的标准模式是"写时写所有层，读时找最快的层"。ai-analyze 加了一个额外的行为：读时回填。当一次读取命中 L2（文件缓存），系统把这条数据拷贝到 L1（内存）。当命中 L3（Redis），回填到 L1 和 L2。

这意味着缓存会按使用模式自动升温。第一次分析走 L3→L2→L1 全链路，第二次在 L2 命中后拷贝到 L1，第三次直接命中 L1。不需要预热步骤，不需要手动迁移——缓存随着使用自然地向最快层流动。

Redis 还有一个"吸收式"容错设计：连接失败时 _client 被设为 None，之后每次操作检查 if not self._client: return None。Redis 完全挂掉不会抛异常，系统静默降级到 L1+L2 继续运行。这不是"Redis 可选"的意思——这是"Redis 的失败不应该阻塞分析流水线"。

增量分析器还有一层额外的优化：合并缓存结果和新分析结果时，用内存里的 _file_result_cache 字典保存反序列化后的 Python 对象。MultiLevelCache 存的是序列化 JSON，合并阶段需要的是对象。反序列化是昂贵操作，在内存里保持对象状态避免了反复读缓存再反序列化的开销。这是第三层未标注的缓存，专为合并阶段存在。

这五个决策的共同线索是：每一个"为什么不那么做"比"怎么做"更值得讲。 不暴露修改操作（架构约束），不以结构为主（可操作性优先），不让 AI 强求升级（对抗固有倾向），不给弱指标高权重（诚实优于精度），不让缓存被动等待（主动升温）。这些决策不是代码实现的细节，是设计思想的表达——它们决定了 ai-analyze 不只是一个分析工具，是一个有工程判断力的系统。

源码导航

项目仓库：https://github.com/erishen/ai-analyze