大部分代码分析工具的文章会讲"支持多少语言、有多少规则、能检测多少漏洞"。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 SerenaStdioClient:
"""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 字段，但合并代码对它采用了按需填充的策略——只有当 Serena 报告中存在同名同类型的符号时才填充，找不到时保持 None。这意味着 AST 分析永远不依赖 Serena 数据的可用性：有 Serena 时补充结构信息，没有时 AST 产出的指标依然完整。这不是 bug——这是容错设计。Serena 数据是增强点，不是依赖点。
这个决策传达的设计思路是：数据合并的主循环应该围绕可操作的维度，而不是结构维度。结构信息提供上下文，指标信息驱动决策。
决策三：AI 提示词里加了"反炒作"指令
ai-analyze 有三个 AI 调用：代码质量评估、Docker 策略建议、框架升级分析。每个调用的提示词都把 AST 分析产出的结构化事实嵌入进去——Top 5 复杂函数、Top 10 代码味道、Top 20 依赖关系。AI 不是被要求去发现复杂度问题，而是被 handed 已确认的事实去解读。这种"规则先行、AI 解读"的模式降低了幻觉风险——AI 不能声称"这个项目没有复杂度问题"，因为提示词里明确列出了 5 个复杂度超过 10 的函数。
AI 调用基于 litellm，支持 100+ LLM 提供商——OpenAI、DeepSeek、Anthropic、Groq 等。切换提供商只需改一个环境变量 OPENAI_MODEL=deepseek/deepseek-chat，不需要改代码。但不管底层是哪个模型，提示词工程的原则不变。
最不显而易见的设计决策在框架升级分析的提示词里。有一句显式的指令：
"如果当前版本已经是最新稳定版，请明确说明，不要强求升级"
这句指令在对抗 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 不只是一个分析工具，是一个有工程判断力的系统。
源码导航
| 模块 | 源码文件 | 说明 |
|---|---|---|
| MCP 协议客户端 | serena_stdio_client.py | 刻意不实现修改操作的安全边界 |
| MCP 直接调用客户端 | serena_client.py | 进程内全功能调用，性能优先 |
| 统一合并层 | unified_analyzer.py | AST 为骨架、Serena 为补充、serena_data 空占位 |
| AI 集成（litellm） | ai_enhanced_analyzer.py | 规则先行提示词、反炒作指令、温度梯度、100+ LLM |
| 质量评分 | quality_score.py | 可维护性 0.35 最高、安全 0.15 低权重诚实代理 |
| 安全扫描 | security_scanner.py | 严重度几何加权 + 饱和曲线 |
| 三层缓存 | multi_level_cache.py | 读时回填自动升温、Redis 吸收式容错 |
| 增量分析 | incremental_analyzer.py | MD5 变化检测 + 文件缓存渐进迁移 + 内存对象层 |
| AST 分析器 | ast_analyzer.py | 单次树遍历替代 3 次遍历、最长任务优先调度 |
| 流水线编排 | full_analyzer.py | skip 标志作为成本控制网格 |
| Docker 生成 | docker_generator.py | 内容检测而非结构检测、Husky 移除实战细节 |
| 插件系统 | plugin_system.py | shared_data 管道、命名空间防冲突 |
| 异常体系 | exceptions.py | error_code + context dict、日志可解析格式 |