code-architecture-analysis

name	code-architecture-analysis
description	深入分析复杂项目的架构设计、核心机制和实现原理。当用户询问"为什么 X 能做到 Y"、"系统是怎么工作的"、"分析一下这个项目的架构"时使用。也适用于主动分析开源项目的技术栈、模块划分、数据流、配置体系。覆盖 LangChain/LangGraph Agent、前后端分离 Web 应用、CLI 工具等常见项目类型。也适用于：代码缺陷审查（安全漏洞、架构问题、设计反模式）、两个或多个项目的全面对比分析。触发词："缺陷"、"有什么问题"、"对比"、"区别"、"哪个更好"、"review"、"审计"。

代码架构分析技能

核心原则

回答用户的真实问题，不是你想象的问题。

用户问"为什么 X 能做到 Y"时：

• ❌ 错误：分析 Y 的技术实现细节
• ✅ 正确：解释 X 的架构设计如何支持 Y

用户问"分析这个项目"时：

• 先给全局概览（技术栈、核心能力、架构分层）
• 再按模块深入（可并行读取多个文件）
• 最后总结设计亮点和可借鉴之处

用户问"有什么缺陷"时：

• 按严重程度分级（P0 安全 → P1 架构 → P2 性能 → P3 可维护）
• 给出具体代码位置和修复方向
• 不要只列问题，要解释为什么是问题

用户要求"结合具体例子"时：

• 不要只描述架构，要追踪一个完整的数据流
• 用具体的函数调用链、具体的字段名、具体的代码位置
• 最好能画出时序图或流程图

系统性项目分析流程

当用户要求"分析这个项目"或 clone 后想了解项目时，按以下顺序执行：

Phase 1: 元信息（并行读取）

同时读取以下文件，快速建立全局认知：

文件	提取信息
pyproject.toml / requirements.txt / package.json	依赖列表、Python/Node 版本要求
main.py / index.js / app.py	入口点、启动流程
README.md / CLAUDE.md / AGENTS.md	项目定位、开发规范
version.py / __version__	版本号
start.bat / Makefile / docker-compose.yml	启动方式、部署模式

Phase 2: 结构扫描（并行 list_dir）

扫描核心目录，理解模块划分：

项目根目录/
├── 核心逻辑模块（agent/、core/、src/）
├── API 层（api/、routes/、server/）
├── 前端（web/、frontend/、client/）
├── 配置（config/、settings/）
├── 工具/插件（tools/、plugins/、extensions/）
├── 存储/记忆（memory/、storage/、db/）
└── 脚本（scripts/、bin/）

Phase 3: 核心模块深度分析（按需并行）

根据 Phase 2 的结构，选择最关键的 3-5 个模块深入：

入口模块：理解启动流程、依赖注入、生命周期管理 路由/API 模块：理解接口设计、中间件、认证 核心逻辑模块：理解业务逻辑、状态管理、算法 配置模块：理解配置来源（env/yaml/db）、热更新、多环境

Phase 4: 横向关注点

在分析过程中注意以下横向关注点：

• 错误处理：重试、降级、兜底策略
• 状态管理：内存/文件/数据库、持久化、过期清理
• 实时通信：WebSocket、SSE、轮询、事件驱动
• 可扩展性：插件机制、注册表模式、钩子系统
• 安全：认证、授权、输入校验、沙箱

技术栈特定检查清单

小模型优化编码代理分析案例（SmallCode）

当分析为小模型（8B-35B）优化的编码代理时，重点关注以下设计模式：

核心设计哲学：

• 约束驱动设计：从模型限制出发，不是从功能出发
• 优雅降级：所有组件都有回退机制
• 确定性优先：尽可能使用确定性逻辑而非LLM调用
• 上下文预算：每个令牌都有价值，需要主动管理

关键优化技术：

1. 智能工具路由系统

   • 加权正则评分系统（8个类别：read/write/search/run/plan/code-intelligence/web/respond）
   • 两阶段路由（≤16k上下文时）：先选类别，再获取工具
   • 肯定回答保护：避免"yes"/"ok"导致工具剥离
   • 国际化陷阱：所有信号词都是英文，\b 词边界对中文/日文/韩文无效，非英文输入会全部 fallback 到 respond（不注入任何工具）。验证方法：node -e "const r = require('./src/compiled/tool_router'); console.log(r.classifyToolCategory('读取文件'))"

2. 计划追踪器

   • 运行锚点：每轮重新注入计划进度
   • 依赖图分析：纯代码分析步骤间文件依赖
   • 解决小模型多步骤任务遗忘问题

3. 补丁优先编辑

   • patch原语：搜索与替换，避免重写整个文件
   • 语义合并回退：补丁失败时的最后手段
   • 读取前写入保护：防止覆盖未读取文件

4. 上下文预算管理

   • 工具定义选择性包含（节省50-100%）
   • 读取守卫：大文件自动截断
   • 早期压缩（80%令牌使用时触发）

5. 宽容的工具调用解析器

   • 多格式支持：JSON/YAML/XML/Hermes/纯文本
   • 自动修复：参数名错误、类型不匹配
   • 工具调用提取（关键兼容层）：小模型（qwen2.5-coder、hermes、llama3 GGUF）经常把工具调用嵌入在 message.content 而非结构化 tool_calls 中。提取器支持 5 种格式：
     1. <tool_call>{...}</tool_call>（Hermes/qwen2.5）
     2. <|tool_call_start|>[func(kw=val)]<|tool_call_end|>（Liquid AI LFM2）
     3. ```json ... ```（通用 JSON 块）
     4. ```tool_call ... ```（llama3 微调）
     5. 裸 JSON 对象
   • 验证方法：检查 message.tool_calls 为空但 message.content 包含 JSON 时是否自动提取

6. 复合工具

   • read_and_patch、create_and_run、find_and_read
   • 减少工具调用链（1次 vs 3-4次）

7. 升级机制

   • 本地模型失败时升级到云模型（Anthropic/OpenAI/DeepSeek）
   • 会话上限（默认5次升级）

8. 早期停止检测

   • 重复循环、补丁螺旋、问候回归、读取循环
   • 注入纠正指令

分析要点：

• 如何平衡功能完整性与上下文限制
• 确定性逻辑与LLM调用的权衡
• 优雅降级策略的设计
• 复合工具对小模型的重要性

LangChain / LangGraph Agent 项目

□ agent/graph.py — 图构建方式（create_agent / StateGraph）
□ agent/prompts.py — 系统提示词组装（persona + memory + skills）
□ tools/ — 工具注册模式（集中注册 vs 动态发现）
□ tools/base.py — 工具基类（SharedAPIClient、ToolBase）
□ memory/ — 记忆系统（YAML/DB、叙事生成、CRUD 工具）
□ api/providers/ — LLM 提供商管理（配置存储、工厂模式、健康检查）
□ api/session_manager.py — 会话管理（TTL、子会话、checkpoint）
□ api/callbacks/ — 流式回调（token 推送、工具执行事件）

关键问题：

• checkpointer 类型（MemorySaver / SQLite / PostgreSQL）
• 工具执行是同步还是异步
• 子 Agent 如何创建和管理
• 上下文窗口如何监控和管理

前后端分离 Web 项目

后端（FastAPI/Express/etc）：

□ server.py / app.py — 应用工厂、中间件、lifespan
□ routes/ — 路由分组、REST vs WebSocket
□ dependencies.py — 依赖注入、单例管理
□ health.py — 健康检查、组件自检

前端（Vue/React/etc）：

□ package.json — 框架版本、构建工具
□ src/views/ — 页面组件
□ src/components/ — 通用组件
□ src/composables/ 或 src/hooks/ — 逻辑复用
□ src/types/ — 类型定义
□ src/api/ — API 调用层

关键问题：

• WebSocket 消息协议设计（事件类型、payload 结构）
• 状态管理方式（Pinia/Redux/Context/localStorage）
• 前端如何处理流式响应

CLI 工具项目

□ 入口参数解析（argparse/click/typer）
□ 子命令组织
□ 配置文件位置和格式
□ 输出格式（plain/json/table）
□ 交互模式（prompt/REPL）

加密/安全传输系统

当分析涉及加密传输的系统（如 CDN + 加密、端到端加密、安全消息传递）时：

核心追踪点：

□ 密钥生命周期 — 生成位置、存储方式、传输方式、使用时机
□ 加密算法 — 对称/非对称、分组模式（ECB/CBC/GCM）、填充方式
□ 密钥交换 — 如何把密钥传给接收方（消息字段、单独通道、派生）
□ 完整性校验 — MD5/SHA256、签名、HMAC

分析流程：

1. 找类型定义 — 定位 CDNMedia、EncryptedPayload、KeyInfo 等结构
2. 追踪密钥流 — 从生成点到使用点，画出完整路径
3. 分析加密/解密 — 分别看上传（加密）和下载（解密）流程
4. 检查边界 — 密钥轮换、过期处理、错误恢复

常见模式：

• CDN + 信封加密：文件用随机对称密钥加密，密钥放在消息体中传输
• 预签名 URL：服务器生成临时上传/下载凭证，客户端直接用
• 密钥派生：从主密钥派生出会话密钥，减少密钥暴露面

代码搜索关键词：

• encrypt、decrypt、aes、rsa、hmac
• aeskey、aes_key、encryption_key、secret_key
• upload_param、download_param、encrypt_query_param
• getUploadUrl、getDownloadUrl、preSign

缺陷分析流程

当用户问"有什么缺陷"、"代码审查"、"找问题"时，按以下维度系统审查：

安全审查（P0）

检查项	关键词/模式
代码执行沙箱	exec(, eval(, subprocess, os.system — 是否有隔离
文件操作边界	open(, os.remove, shutil.rmtree — 是否限制路径
认证/授权	WebSocket、REST API — 是否有 token/session 验证
CORS 配置	allow_origins=["*"] + allow_credentials=True — 危险组合
密钥存储	.env、YAML 明文、进程内存 — 是否加密
输入校验	用户输入是否直接拼接到命令/路径/SQL
目录遍历	../ 路径拼接、startswith 检查是否可绕过
加密实现	ECB 模式（无语义安全）、硬编码密钥、密钥复用

正则安全模式审计（P0 专项）

当代码用正则表达式做安全阻断（命令黑名单、输入过滤、路径校验）时，必须审计绕过面。

审计清单：

绕过类别	检查方法	示例（以 rm -rf / 为例）
Shell 变量展开	正则不处理 $VAR、${VAR}	x=/; rm -rf $x
命令替换	正则不处理 $(...)、`...`	rm -rf $(echo /)
路径等价	/、/.、/./、/..（根目录的 .. 仍是 /）	rm -rf /.
符号链接	ln -s / link && rm -rf link	正则匹配的是 link 路径
反斜杠转义	shell 忽略但正则不忽略	rm -rf \/
Unicode 规范化	NFKC 是否覆盖所有变体？全角字符？	ｒｍ → rm
ANSI 剥离	剥离函数是否覆盖所有序列（CSI/OSC/DCS）？	\x1b[31mrm\x1b[0m
环境变量路径	$HOME、$HERMES_HOME 的展开时机	正则匹配 $HOME 但 shell 展开为 /root
命令分隔符	;、&&、|、换行后的命令是否都检查？	echo x; rm -rf /
包装命令	sudo、env、exec、nohup、setsid	sudo rm -rf /

核心认知：正则匹配发生在命令字符串层面，shell 展开发生在执行层面。两者之间存在语义鸿沟，任何依赖 shell 展开的路径/变量都是绕过面。

审计方法：

1. 提取所有正则 pattern，逐条审查上述绕过类别
2. 写测试脚本验证：detect_dangerous_command("bypass_command") 是否返回 (False, None, None)
3. 特别关注 _normalize_command_for_detection 的处理范围——它做了什么、没做什么

常见错误假设：

• ❌ "用户输入就是命令本身" — 实际上 shell 会先展开变量和替换
• ❌ "路径规范化后就安全" — 实际上规范化不处理 shell 语法
• ❌ "正则覆盖了所有变体" — 实际上总有遗漏的编码/转义方式

架构审查（P1）

检查项	关键词/模式
缓存失效	@lru_cache、全局单例 — 修改后能否热更新
资源泄漏	清理函数存在但未被调用（grep 验证调用链）
静默吞异常	except: pass、except Exception: pass
同步阻塞异步	在 async 上下文中使用 requests、time.sleep
过期清理	TTL 机制存在但清理函数未被调度
单例生命周期	全局状态在进程生命周期内的创建/销毁时机

国际化审查（P1）

当项目使用正则表达式做意图分类、安全过滤、或用户输入匹配时，必须审查非英文语言支持。

检查项	问题模式	验证方法
\b 词边界	只匹配 \w（字母数字）边界，中文字符间无 \b	/\b读\b/i.test("读取") → false
英文硬编码信号词	所有关键词都是英文，非英文输入得分为 0	用目标语言测试分类函数
[:alpha:] / \w 范围	\w 包含中文字符但 \b 不在中文字符间生效	测试混合输入
空格分词假设	假设词以空格分隔，中文/日文无空格	测试连续字符输入
Unicode 规范化	NFKC 是否覆盖全角/半角变体	ｒｍ → rm

典型陷阱：

• 工具路由系统用英文正则分类意图，中文输入全部 fallback 到默认类别
• 安全过滤正则只匹配英文命令，中文路径/命令绕过
• 搜索功能假设空格分词，中文子串匹配失效

修复模式：

// ❌ 英文正则 + \b
/\b(read|write|search)\b/i

// ✅ 非捕获组，支持中英文
/(?:read|write|search|读取|写入|搜索)/i

工具/插件系统审查（Agent 项目专用）

检查项	说明
审批机制	哪些工具有用户确认？哪些直接执行？覆盖是否完整？
工具设计一致性	万能工具 vs 原子工具是否混用？参数 schema 是否合理？
同步/异步一致性	_run 和 _arun 是否都有实现？同步工具是否阻塞事件循环？
错误响应格式	是否统一（如 format_error）？是否有工具直接抛异常？
get_doc 反模式	是否把"读文档"和"执行"混在同一个工具里？
工具 description	是否把行为指令和功能描述混在一起？

性能审查（P2）

检查项	关键词/模式
串行可并行	多个独立 await 调用是否可用 asyncio.gather()
全量读写	每次操作是否读写整个文件（YAML/JSON）而非增量
重复计算	token 计数、上下文估算是否每次全量重算
轮询 vs 推送	健康检查、状态刷新是否用定时轮询而非事件推送

可维护性审查（P3）

检查项	说明
测试覆盖	tests/ 目录是否有实质内容？核心路径是否有测试？
日志规范	是否用 print() 代替结构化日志？stdout/stderr 是否混用？
类型定义重复	前后端是否各定义一套类型？是否有 schema 生成机制？
魔法数字	关键配置是否散落在代码各处？是否有统一配置管理？
依赖版本约束	是否有上限约束（>=x,<y）？大版本升级是否有保护？

缺陷报告格式

## 🔴 严重安全缺陷
### 1. [简短标题]
- **代码位置**: `path/to/file.py:line`
- **问题**: 具体描述
- **风险**: 可能的攻击场景
- **修复**: 建议的修复方向

## 🟠 架构设计缺陷
...

## 📋 缺陷优先级总结
| 优先级 | 缺陷 | 影响 |
|--------|------|------|
| P0 紧急 | #1 标题 | 影响描述 |

对比分析流程

同一功能跨本地项目对比（Surgical Comparison）

当用户要求"和 Hermes 对比"、"看看 Navi 的 XX 和 Hermes 有什么区别"时，执行手术式对比：聚焦同一功能，逐层深入。

Step 1: 定位双方实现（并行 grep）

用 grep 在两个项目中搜索同一功能的核心标识符（类名、函数名、常量）：

grep: project_a — "class SearchSession|search_messages|FTS5"
grep: project_b — "class.*Search.*Tool|search_messages|DISCOVERY|SCROLL|BROWSE"

Step 2: 并行读取核心逻辑

同时读取两边的核心实现文件。按分层组织：

层次	项目A	项目B
工具层（调用入口）	tools/builtin.py	tools/session_search_tool.py
存储层（数据操作）	storage/history_store.py	hermes_state.py
初始化层（schema）	_init_fts_tables()	FTS_SQL / FTS_TRIGRAM_SQL

Step 3: 分层对比

按数据流顺序逐层对比，不要跳来跳去：

1. Schema/初始化层：表结构、触发器、索引差异
2. 核心查询层：搜索算法、CJK 处理、排序逻辑
3. 工具层：参数设计、模式划分、返回格式
4. 周边功能：去重、bookend、scroll、browse

Step 4: 输出对比报告

## 对比：[功能名]

### 1. [层次名]

| 方面 | 项目A | 项目B | 差异分析 |
|------|-------|-------|----------|
| 方面1 | 做法 | 做法 | 哪种更好/为什么 |

### 2. ...

### 总结
| 维度 | 项目A | 项目B | 优势方 | 原因 |
|------|-------|-------|--------|------|

关键原则：

• 逐层对比，不要跳层
• 每个差异点都要分析"为什么"和"哪种更好"
• 重点关注：功能完整性、错误处理、边界情况处理
• 不要只罗列差异，要给出判断

全面项目对比（General Comparison）

当用户要求全面对比两个项目时，使用以下维度：

1. 技术栈：语言、框架、关键依赖版本
2. 架构模式：分层方式、模块划分、数据流
3. 配置管理：配置来源、热更新、多环境支持
4. 错误处理：重试、降级、兜底、日志
5. 可扩展性：插件机制、钩子、注册表模式

Agent 项目对比维度

1. Agent 循环：ReAct / Plan-Execute / 自定义循环
2. 工具系统：
   • 注册方式（集中/动态/装饰器）
   • 工具粒度（万能 vs 原子）
   • 审批机制（全量/可选/无）
   • 同步/异步支持
3. SubAgent 实现：
   • 创建方式（新会话/新进程/协程）
   • 上下文隔离程度
   • 嵌套深度限制
   • 前端集成方式
4. 记忆系统：
   • 短期记忆（checkpoint 类型）
   • 长期记忆（存储格式、更新策略）
   • 记忆工具（CRUD 操作）
5. LLM 管理：
   • 多提供商支持
   • 运行时切换
   • 健康检查和降级
6. 前端/UI：
   • 通信协议（WebSocket/SSE/轮询）
   • 流式渲染方式
   • 工具气泡/结果展示

对比输出格式

## [维度1]: [A] vs [B]

| 方面 | 项目A | 项目B |
|------|-------|-------|
| 方面1 | A的做法 | B的做法 |
| 方面2 | A的做法 | B的做法 |

**分析**: 哪种做法更好，为什么，适用场景。

## 对比总结

| 维度 | 项目A | 项目B | 优势方 |
|------|-------|-------|--------|
| 维度1 | 描述 | 描述 | A/B/各有优劣 |

示例：Hello Agents vs Navi Agent 对比

当对比两个 Agent 框架时，按以下维度分析：

1. 项目定位与目标：教育 vs 生产
2. 架构设计：分层方式、模块划分
3. 工具系统：调用方式、注册机制、执行方式
4. 技能系统：有无、管理方式
5. 上下文管理：历史存储、压缩、记忆
6. 中断与审批：支持程度
7. 技术栈：依赖、框架选择

关键差异点：

• Hello Agents：教学框架，模拟工具调用，简单架构
• Navi Agent：生产工具，真实工具执行，完整功能

分析要点：

• 教育项目追求简单易懂，生产项目追求功能完整
• 模拟工具调用适合教学，真实工具调用适合实际使用
• 技能系统是生产级 Agent 的重要特征

分析输出格式

给用户的分析报告应包含：

1. 项目定位：一句话说明项目是什么
2. 技术栈总览：语言、框架、关键依赖
3. 架构分层图：用文字或 Mermaid 表示
4. 核心模块详解：每个模块的职责、关键文件、设计模式
5. 数据流：用户请求 → 各模块 → 响应的完整链路
6. 设计亮点：可借鉴的架构决策
7. 配置与部署：如何启动、如何配置、环境依赖

反模式

❌ 平铺罗列：把每个文件都列一遍，没有主次之分 ❌ 只读不分析：复述代码内容，不解释设计意图 ❌ 忽略数据流：只说模块是什么，不说数据怎么流动 ❌ 遗漏配置体系：不说配置从哪来、怎么管理 ❌ 跳过启动流程：不说项目怎么跑起来的 ❌ 缺陷只列不分级：所有问题同等对待，没有优先级 ❌ 对比只罗列不分析：列出差异但不说哪种更好、为什么 ❌ 对比跳层：读了一层 A 就跳到另一层 B，没有逐层对照 ❌ 抽象描述：用户要具体例子时还只说架构概念 ❌ 正则安全只看 pattern 不测绕过：声称"不可绕过"但没验证 shell 展开、路径等价、编码变体

用户偏好

• 用户会追问"xxx 参数是什么"直到完全理解才允许动手
• 用户偏好先看设计、确认方案、再动手改代码
• 用户不喜欢不必要的函数包装（3行 wrapper 直接内联）
• 用户会质疑分析结果的合理性，要求搜索验证
• 用户会用本地参考项目（cc_src、kimi-cli、hermes-agent）来对比，优先读本地文件而非搜索
• 用户要求"具体例子"时，要追踪完整数据流，给出函数调用链和具体字段

何时触发

• 用户 clone 了一个项目，要求分析
• 用户问"这个项目是怎么工作的"
• 用户问"为什么 X 能做到 Y"
• 用户问"分析一下这个项目的架构"
• 用户问"这两个系统有什么区别"
• 用户问"有什么缺陷"、"找问题"、"代码审查"
• 用户问"对比"、"和 X 比怎么样"
• 用户问"X 是如何实现 Y 的"（需要追踪具体实现）

相关技能

• research-github-project：研究 GitHub 项目信息（在线调研）
• navi-design：Navi Agent 设计参考（参考实现对比）