software-architecture-analysis

软件架构分析 — 从代码库逆向工程到设计文档

适用场景

• 已有参考实现，你需要了解其架构以获取设计灵感
• 你需要为相同问题领域的系统编写 PRD、设计文档或规范
• 输出必须符合 clean-room 原则：不得复制参考代码库中的任何源代码示例
• 你正在设计的系统与参考实现有不同的架构约束（本地优先、隐私优先、可自托管）
• 你需要提取隐式契约——代码库执行的存储操作——以设计正式的提供程序抽象
• 你需要基于代码库证据评估架构健康状况、耦合度、模块化程度、数据所有权、分布式工作流，或系统是否已准备好进行边界变更

不适用于： 从零开始或主动进行架构设计（请转至 software-architecture）、直接代码审查、漏洞排查或安全审计。API／接口语义请转至 api-design-and-evolution，数据平台策略请转至 data-architect，实现工作请转至相关工程技能，部署基础设施请转至 platform-engineering，执行已批准的跨系统迁移请转至 migration-engineering。

构建工作流

Phase 1: Clone + Map  →  Phase 2: Find Key Files  →  Phase 3: Map Architecture
                                                              ↓
Phase 6: Constraint Redesign  ←  Phase 5: Write Spec  ←  Phase 4: Feature Inventory
                                                              ↓
                                                      Phase 7: QA

阶段 1：克隆仓库并映射结构

使用浅克隆克隆目标仓库：

git clone --depth=1 https://github.com/owner/repo /tmp/target-repo

映射顶层目录结构。对每个目录，确定：

• 使用的语言／框架
• 它属于前端、后端、服务、固件还是支持组件
• 它是核心组件（业务逻辑）还是支持组件（CI、文档、工具）

ls -la /tmp/target-repo/
find /tmp/target-repo -type f -name "*.swift" | sort   # or *.py, *.rs, *.ts, *.go

阶段 2：识别关键架构文件

按行数排序，找出最大的文件——这些文件承载着核心逻辑：

wc -l /tmp/target-repo/**/*.swift /tmp/target-repo/**/**/*.swift 2>/dev/null | sort -n

阅读排名前 15–25 的文件，并按以下顺序优先处理：

1. 入口点：main、App、bootstrap——应用如何启动
2. 数据模型：在系统中流转的类型
3. 核心服务：采集、处理、存储流水线
4. UI／页面文件：从用户视角呈现的功能
5. 配置：环境文件、配置结构体——外部依赖
6. 隐私敏感文件：任何访问用户数据的服务

阶段 3：映射架构

对每个核心服务，确定：

• 采集什么：数据类型、来源、频率、存储位置
• 在哪里处理：本地还是云端，会调用哪些 API／服务
• 存储在哪里：本地数据库、云数据库、文件系统
• 外部依赖：每个第三方服务、API 密钥、云服务提供商
• 隐私状况：哪些数据会离开设备，以及在什么条件下离开

使用 Mermaid 语法绘制图表（GitHub 和大多数 Markdown 编辑器均可原生渲染）：

graph TD
    subgraph Capture["Capture Layer"]
        CAM[Camera/Mic Capture]
        FS[File Scanner]
    end

    subgraph Processing["Processing Layer"]
        OCR[OCR/NLP]
        STT[Speech-to-Text]
    end

    subgraph Storage["Storage Layer"]
        DB[(Local Database)]
        CLOUD[(Cloud Sync)]
    end

    CAM --> OCR
    FS --> OCR
    STT --> DB
    OCR --> DB
    DB --> CLOUD

    style Capture fill:#0a1a2e,stroke:#22d3ee
    style Processing fill:#0a2a1a,stroke:#34d399
    style Storage fill:#1a0a3a,stroke:#a78bfa

使用子图表示云端／本地边界。所有图表代码块都必须使用 ```mermaid——不得使用 ASCII 框图，也不得使用图像文件。

架构证据视角

完成初始梳理后，只加载问题所需的参考资料：

• 当需要根据观察到的场景、控制措施和运维证据推断质量特征时，参阅架构特征分析。
• 当需要比较边界、变更传播、模块化、部署形态或分解就绪度时，参阅耦合、模块化与分解。在确定目标边界前，先评估静态、动态、数据、时间、部署和组织耦合。
• 当需要追踪数据权威性、分布式事务、编排／协同、故障处理或对账时，参阅数据所有权与工作流分析。
• 当交付物是可重复使用的健康报告或结构化交接材料时，使用架构健康评估模板。

将每项主张标记为已观察、推断、已报告或未知。引用支持该主张的制品、跟踪记录、配置、测试、指标或访谈证据。缺少观察证据时，不要直接将其认定为缺陷；应标明不确定性。

阶段 3b：接口提取模式（DAO／Provider 契约设计）

当目标是提取隐式契约——即这段代码需要数据库或存储层提供哪些操作？——请遵循以下变体：

步骤 1 — 先了解设计理念

在查看代码之前，先阅读任何 PHILOSOPHY.md、DESIGN.md、ARCHITECTURE.md 或主 README。这些文件包含接口必须遵守的设计约束。例如，cashew 思维图谱库的 PHILOSOPHY.md 写道：“简单的图谱，智能的推理层”——边不携带类型标签，节点类型只是提供给 LLM 的描述性提示，并非图谱引擎操作的关键依据。必须将这一约束纳入契约设计。

步骤 2 — 列出所有存储操作

阅读所有涉及存储层（数据库、文件系统、外部服务）的文件。对于每个文件，列出每项不同的操作：

类别	操作示例
节点 CRUD	创建、读取、更新、删除、扫描、计数
边 CRUD	create_edge、get_neighbors、delete_incident
向量 KNN	find_similar、set_embedding、delete_embedding
图遍历	bfs、shortest_path、trace_derivation
维护	similarity_candidates、random_sample、get_metrics
事务	begin、commit、rollback

按命名约定查找目标文件：db.py、store.py、storage.py、embedding.py、session.py、persist.py，以及任何批处理／维护模块。

步骤 3 — 找出暴露边界泄漏的变通方案

这些代码的存在是因为底层存储技术的限制，而非应用逻辑。相关信号包括：

• 双写模式（为适配不同查询路径，将相同数据写入两个表）
• 维度不匹配检测和回退链
• 将整张表加载到 numpy/scipy 中，以执行原生存储技术本可支持的操作
• 在 SQL 中通过递归 CTE 重新实现图遍历
• 使用 try/except 在快速路径和回退路径之间切换
• 类似“因为 X 不原生支持 Y，所以需要这样做”的注释

这些变通方案是当前边界位置不当所带来的代价，可以考虑移到契约后面。

步骤 4 — 根据操作清单设计契约

定义抽象接口（ABC、Protocol 或 trait），涵盖步骤 2 中的所有操作，同时不泄漏步骤 3 中的底层存储技术特有细节。

设计原则：

• 根据代码库需要什么来设计，而非根据当前底层存储技术能做什么来设计
• 让设计理念约束接口
• 高成本操作（相似度搜索、图遍历、扫描）决定性能特征——契约必须支持在原生存储技术上高效实现这些操作
• 事务必须明确

步骤 5 — 用双提供方验证

设计第二种提供方实现来测试抽象。它不需要达到生产就绪状态，只需通过相同的测试套件即可。双提供方验证可以发现：

• 过于依赖原始底层系统语义的操作
• 第二种提供方所需但缺失的操作
• 契约泄漏（方法签名假定采用类似 SQL 的游标行为，而不是返回数据类）

请参阅 references/interface-extraction-pattern.md，其中以 cashew thought-graph 库为例，提供了完整的演示。该库是一个展示全部五个步骤的真实开源项目。

第 4 阶段：功能界面盘点

通过阅读 UI 视图文件、页面文件和引导界面，梳理所有面向用户的功能。按类别分组：

• 采集：录制、扫描、导入
• 处理：转录、OCR、分析
• AI：聊天、助手、洞察、建议
• 存储：本地、云端、导出
• 集成：第三方服务、API
• 插件：扩展、自定义工具、MCP

第 5 阶段：编写洁净室规格说明

这是最关键的阶段。 输出文档必须：

1. 描述架构模式，不得引用或复现源代码
2. 使用自然语言描述组件之间的交互方式
3. 按架构层引用原始代码库，不得使用行号或变量名
4. 绝不包含源代码片段——不得包含 Swift、Rust、Python 或任何参考项目中的代码。规格说明面向的是新代码，而非衍生作品

**“不受污染”原则：**如果输出中包含可辨认出源自参考项目的代码模式，就应在更高的抽象层次上重写。

请按以下章节组织输出：

• 产品愿景与设计原则
• 架构概览（Mermaid 图）
• 功能需求（编号列出）
• 非功能需求（性能、电池、隐私）
• 技术架构（包含技术的组件列表）
• 插件/扩展 API 规范
• 隐私架构详解（数据流图）
• 发布标准（MVP → v1 → v2）

图表规则：

• 所有图表都使用 ```mermaid 代码块——不得使用 ASCII 方框图或图像文件
• 数据流图应按流水线分别放在独立的 Mermaid 代码块中，不得合并为一张大型图表
• 每项外部依赖都应注明其开放标准替代方案（例如：“兼容 OpenAI 的 API，因此可使用任意提供方”）

第 6 阶段：突破约束

在新设计约束（本地优先、隐私优先）下重新构想系统时：

1. 找出参考架构中所有强制性的云端依赖
2. 为每项依赖找出本地替代方案（云端 API → 本地模型、Firestore → SQLite 等）
3. 对于同时支持本地和云端的接口，注明开放标准（兼容 OpenAI 的 API、兼容 S3 的存储、兼容 Whisper 的 STT）
4. 如果参考项目使用了侵犯隐私的模式（访问浏览器 Cookie、直接读取其他应用的数据），将其列为禁止使用的机制——新设计必须使用适当的 API（OAuth、平台 API、官方 SDK）

第 7 阶段：交付后 QA

交付设计文档后：

1. 验证链接完整性——如果文档引用了其他设计文档，请确保存在双向链接。运行 Markdown 链接检查器，找出失效的引用。
2. 验证图表渲染——确认所有 ```mermaid 代码块都能正常渲染，并检查输出中不再包含任何 ASCII 方框绘制字符（┌、├、└、┐、┤、┘、┴、┬、┼）
3. 检查代码污染——扫描是否存在看起来源自参考项目的内嵌源代码片段。如有发现，应在架构层面重写
4. 交叉引用审查——一个章节中引入的每个概念，都应与另一个章节中的实现相联系。整份文档应保持内部一致

退出标准

当请求的架构产物已存在、证据台账明确区分事实、推断和未知项、洁净室检查确认没有复制实现材料、链接的参考资料均可访问，且输出说明了与相邻技能的边界时，此技能即告完成。除非用户另行授权，否则应在提出实现或迁移执行方案之前停止。

参考资料

• references/interface-extraction-pattern.md — Phase 3b 接口提取模式的完整示例，使用 cashew thought-graph 库（MIT，公开发布于 GitHub）。在为可切换存储后端的代码库设计提供方抽象或 DAO 契约时阅读。
• references/architecture-characteristics-analysis.md — 基于证据得出的质量特征和场景分析。
• references/coupling-modularity-and-decomposition.md — 六种耦合视角、模块化信号和分解就绪度评估。
• references/data-ownership-and-workflow-analysis.md — 数据权威性、事务/工作流拓扑、故障和协调分析。
• templates/architecture-health-assessment.md — 可复用的架构健康报告模板。