# Architecture Lens (架构透镜) — 设计文档

## 概述

Architecture Lens 是一个跨平台通用的 OpenCode subagent，能够分析任意项目的架构，输出结构化的"俯瞰图" Markdown 文档。

## 核心产出

对任意项目输出一份标准化的架构文档，包含 7 层结构：

### 第 1 层：项目元信息

| 子项 | 内容 | 数据来源 |
|------|------|---------|
| **项目元信息** | 项目名称、版本号、组织/团队、仓库 URL | README.md / package.json / gradle.properties / Info.plist |
| **技术栈** | 项目类型、构建系统、主力语言、最低部署目标 | settings.gradle / Podfile / oh-package.json5 / pubspec.yaml |
| **多模块结构** | 模块/Target 数量、模块清单 | settings.gradle / Podfile / workspace / app.json |
| **依赖管理** | 包管理器、依赖总数、关键 Direct 依赖 | build.gradle / Podfile.lock / package.json / oh-package.json5 |
| **代码规范** | Lint 工具、Formatter、Pre-commit hooks 配置 | .eslintrc / .swiftlint.yml / detekt.yml / .pre-commit-config.yaml |

### 第 2 层：外部依赖库

| 子项 | 内容 | 分析方式 |
|------|------|---------|
| 外部依赖清单 | 外部依赖清单（如 Android: Retrofit/Glide; iOS: Alamofire/Kingfisher; 通用: React/Vue; Flutter: provider/dio） | 解析依赖声明文件（build.gradle / Podfile / package.json / pubspec.yaml / oh-package.json5） |

### 第 3 层：基础设施

| 子项 | 内容 | 分析方式 |
|------|------|---------|
| 基础设施 | 网络库、数据库、日志、本地存储、图片加载、状态管理等基础设施及其技术选型 | codegraph + import/类名匹配知名库 |

### 第 4 层：公共服务

| 子项 | 内容 | 分析方式 |
|------|------|---------|
| 公共服务 | 路由、推送通知、账户/登录、权限管理、主题、国际化等通用业务能力 | 模块角色推断 + 调用方分析 |

### 第 5 层：业务模块

| 子项 | 内容 | 分析方式 |
|------|------|---------|
| 业务模块 | 各业务模块列表，标注依赖了哪些公共服务 | 模块扫描 + codegraph 引用分析 |

### 第 6 层：工程支撑

| 子项 | 内容 | 数据来源 |
|------|------|---------|
| **测试配置** | 测试框架、测试目录结构、覆盖率工具 | test/ / __tests__ / build.gradle test config / Package.swift |
| **CI/CD** | CI 平台、配置文件路径、构建流水线阶段 | Jenkinsfile / .gitlab-ci.yml / .github/workflows |
| **外部支撑** | 代码生成脚本、自动化工具、初始化脚本、项目文档（API 文档/架构记录/变更日志/知识库） | scripts/ / Makefile / gradlew / fastlane / husky / docs/ / CHANGELOG.md / OpenAPI spec / ADR |

### 第 7 层：资源文件

| 子项 | 内容 | 数据来源 |
|------|------|---------|
| **资源文件** | 图片、字体、布局、字符串、多媒体等静态资源文件 | res/ / src/main/res/ / Resources/ / assets/ |

### 模块依赖/协作（跨层全景）

| 子项 | 内容 | 分析方式 |
|------|------|---------|
| 模块依赖/协作 | 跨第 2~6 层的模块间依赖关系图 + 跨模块通信机制（如接口/路由/EventBus/Provider 等） | codegraph 跨模块引用分析 |

## 跨平台支持

| 平台 | 模块边界检测 | 技术栈识别 |
|------|------------|-----------|
| Android | settings.gradle / build.gradle | import + 类名匹配 |
| iOS | Podfile / Package.swift / xcodeproj | import + 类名匹配 |
| HarmonyOS | oh-package.json5 / build-profile.json5 | import + 类名匹配 |
| Web/Node.js | package.json workspaces | package.json dependencies |
| Flutter | pubspec.yaml | pubspec 依赖分析 |

## 分析引擎策略

1. **codegraph 优先** — 如果项目有 `.codegraph/` 索引，优先使用 codegraph 的跨文件依赖分析
2. **启发式规则兜底** — 无 codegraph 时走文件路径/包名/import 的规则匹配
3. **混合模式** — 部分模块有 codegraph 索引则用，其余兜底

## 输出格式

### Markdown 结构

```markdown
# Architecture Overview: [项目名]

> 生成时间: 2026-07-03 | Commit: abc1234

## 第 1 层：项目元信息

### 项目元信息
| 属性 | 值 |

### 技术栈
| 属性 | 值 |

### 多模块结构
| 模块 | 类型 |

### 依赖管理
| 库名 | 用途 | 版本 |

### 代码规范
| 工具 | 配置路径 |

## 第 2 层：外部依赖库

### 外部依赖清单
| 库名 | 用途 | 版本 |

## 第 3 层：基础设施

### 基础设施
| 领域 | 技术选型 | 所属模块 | 源码路径 | 说明 |

## 第 4 层：公共服务

### 公共服务
| 服务 | 描述 | 所属模块 | 源码路径 | 被业务引用数 |

## 第 5 层：业务模块

### 业务模块列表
| 模块 | 描述 | 源码路径 | 依赖的公共服务 | 包含的子功能 | 代码量 |

## 第 6 层：工程支撑

### 测试配置
| 框架 | 配置路径 |

### CI/CD
| 工具 | 配置路径 |

### 外部支撑
| 工具/脚本 | 用途 |

## 第 7 层：资源文件

### 资源文件
| 类型 | 路径 | 说明 |
|------|------|------|
| {图片/字体/布局/字符串/多媒体} | {res/ / Resources/ / assets/} | {用途} |

## 模块依赖/协作（跨层全景）

**依赖关系表：**

| 模块 | 所属层 | 依赖模块 | 依赖类型 | 证据 |

**Mermaid 依赖图：**
```mermaid
graph TD
  ...
```

**跨模块通信机制：**
- Router / EventBus / Intent / Provider ...

## 工作流程

```
用户触发 (指令 或 skill)
  ↓
Step 1: 检测项目类型
  - 读取根目录构建文件判断平台:
    - settings.gradle / build.gradle → Android
    - Podfile / Package.swift / xcodeproj → iOS
    - oh-package.json5 / build-profile.json5 → HarmonyOS
    - package.json workspaces → Web/Node
    - pubspec.yaml → Flutter
  - 选择对应分析策略
  ↓
Step 2: 扫描第 1 层 — 项目元信息
  - 解析构建配置（项目属性）
  - 扫描技术栈、模块结构、依赖管理、代码规范
  ↓
Step 3: 扫描第 2 层 — 外部依赖库
  - 解析依赖声明文件，列出外部依赖清单
  ↓
Step 4: 扫描第 5 层 — 业务模块（优先判断）
  - 按平台读取模块划分，识别所有模块
  - 逐模块扫描业务特征：UI入口/业务逻辑/独立子领域/模块名暗示
  - 只要满足任一业务特征，即归为业务模块（即使被其他模块引用）
  - 标注依赖了哪些第 3/4 层的服务
  ↓
Step 5: 扫描第 3 层 — 基础设施（仅限非业务模块）
  - 搜索已知库的类名/import，匹配基础设施能力
  ↓
Step 6: 扫描第 4 层 — 公共服务（仅限非业务、非基础模块）
  - 用 codegraph/heuristics 识别扇入≥2 的公共服务
  ↓
Step 7: 扫描第 6 层 — 工程支撑
  - 扫描测试配置、CI/CD、外部支撑
  ↓
Step 8: 扫描第 7 层 — 资源文件
  - 扫描 res/、Resources/、assets/ 等资源目录
  - 按资源类型（图片/字体/布局/字符串/多媒体）归类
  ↓
Step 9: 分析跨层依赖/协作
  - codegraph 追踪第 2~6 层所有模块间的跨模块调用
  - 输出依赖关系表 + Mermaid 图
  ↓
Step 10: 生成架构全景图
  - 按 template/architecture-overview.template.md 格式输出
  - 写入 local_knowledge/knowledge-card/architecture/architecture-overview.md
  ↓
Step 11: 生成模块源码清单
  - 等待 Step 10 文件写入磁盘
  - 从 architecture-overview.md 中提取所有模块行
  - 按来源层映射 node_type（第1层→项目配置, 第2层→外部依赖库, 第3层→基础设施, 第4层→公共服务, 第5层→业务模块, 第6层→工程支撑, 第7层→资源文件；跨层依赖本身不入清单）
  - 按 template/module-source-manifest.template.md 格式输出
  - 写入 local_knowledge/knowledge-card/architecture/module-source-manifest.md
  ↓
Step 12: 生成 .lens-config.yaml
  - 获取当前完整 git commit hash（完整 40 位，不可用短 hash）
  - 写入 local_knowledge/knowledge-card/architecture/.lens-config.yaml
```

## Agent 定义

- **名称**: `architecture-lens`
- **类型**: subagent
- **模式**: subagent
- **权限**: read-only（不修改业务代码）
- **调度方式**: 由 user 直接触发，或由 skill 调度
- **输出目录**: `local_knowledge/knowledge-card/architecture/`（知识卡片体系下的架构文档归档）

## 输出文件

每次分析生成到项目根目录:

```
local_knowledge/knowledge-card/architecture/
├── architecture-overview.md     ← 主报告（7 层结构）
├── module-source-manifest.md   ← 模块源码清单（每模块一行，含 node_type/源码路径）
└── .lens-config.yaml           ← 扫描记录（last_analyzed_commit / last_analyzed_at）
``` 

## 依赖的工具

- codegraph（主分析引擎，可选但有最好）

## 成功标准

- [ ] 能正确识别 Android / iOS / HarmonyOS / Web / Flutter 项目类型
- [ ] 输出文档包含完整的 7 层结构 + 跨层依赖全景图（项目元信息 / 外部依赖库 / 基础设施 / 公共服务 / 业务模块 / 工程支撑 / 资源文件 / 跨层依赖协作）
- [ ] 能绘制模块依赖关系 Mermaid 图
- [ ] 在新项目上也能运行（不依赖本项目特有约定）
