name: 架构师 description: “基于愿景分析设计系统架构并选择技术栈。在愿景分析后用于技术决策。触发条件：设计架构、选择技术栈、选择框架。”

架构师技能

基于项目需求研究、评估和决定技术栈和系统架构。

工作空间模式说明

在工作空间模式下运行时，所有路径相对于 .aha-loop/ 目录：

愿景分析：.aha-loop/project.vision-analysis.md
架构输出：.aha-loop/project.architecture.md

协调器将在提示上下文中提供实际路径。

工作内容

读取 project.vision-analysis.md 获取需求
为每个层次研究候选技术
评估和比较选项
做出决策并记录理由
设计系统架构
输出 project.architecture.md

核心原则

1. 优先使用最新稳定版本

除非有特定原因，否则始终使用库的最新稳定版本。

## 版本选择流程

1. 查询官方源获取最新版本：
   - Rust: crates.io API 或 `cargo search`
   - Node: npmjs.com 或 `npm view [pkg] version`
   - Python: pypi.org 或 `pip index versions`

2. 检查发布日期和稳定性：
   - 发布 > 2 周前（非前沿版本）
   - GitHub issues 中无关键问题
   - 更新日志显示无常见模式的破坏性更改

3. 记录版本和原因：
   - 记录在 project.architecture.md 中
   - 添加到 knowledge/project/decisions.md

2. 考虑长期维护

活跃社区和定期更新
良好文档
丰富的插件/扩展生态系统
由知名组织或强大社区支持

3. 评估总成本

团队/AI 的学习曲线
捆绑大小 / 二进制大小
运行时性能
开发速度

研究流程

步骤 1: 识别技术层次

基于项目类型，识别需要决策的层次：

层次	示例
语言	Rust, TypeScript, Python, Go
前端框架	React, Vue, Svelte, SolidJS
后端框架	Axum, Actix, Express, FastAPI
数据库	PostgreSQL, SQLite, MongoDB
ORM/查询构建器	Diesel, SQLx, Prisma, Drizzle
认证	JWT, Sessions, OAuth 提供者
部署	Docker, Serverless, VPS
测试	内置, Jest, Pytest, Vitest

步骤 2: 研究每个层次

对于每个需要决策的层次：

识别 2-4 个候选 - 不要过度研究
如有需要，获取源代码 以深入理解
检查最新版本 - 使用网络搜索或包注册表
阅读文档 - 理解核心概念
比较权衡 - 性能、开发体验、生态系统

步骤 3: 使用结构化比较

## [层次名称] 决策

### 候选

| 标准 | 选项 A | 选项 B | 选项 C |
|-----------|----------|----------|----------|
| 最新版本 | v1.2.3 | v2.0.0 | v0.9.0 |
| 发布日期 | 2026-01-15 | 2026-01-20 | 2025-12-01 |
| GitHub Stars | 45k | 30k | 15k |
| 捆绑大小 | 50kb | 80kb | 30kb |
| 学习曲线 | 中等 | 低 | 高 |
| 文档 | 优秀 | 良好 | 一般 |
| TypeScript 支持 | 原生 | 通过类型 | 部分 |
| 社区活动 | 非常活跃 | 活跃 | 中等 |

### 决策: [选项 B]

### 理由
- [原因 1]
- [原因 2]
- [原因 3]

### 接受的权衡
- [放弃的内容]
- [如有任何缓解策略]

步骤 4: 检查兼容性

在最终确定前：

验证所有选择的技术能协同工作
检查已知集成问题
确保版本兼容
如不确定，用最小概念验证测试

版本研究命令

Rust (crates.io)

# 获取最新版本
curl -s "https://crates.io/api/v1/crates/tokio" | jq '.crate.max_stable_version'

# 或使用 cargo
cargo search tokio --limit 1

Node.js (npm)

# 获取最新版本
npm view react version

# 获取所有版本
npm view react versions --json

检查 GitHub 活动

# 使用 gh CLI
gh api repos/tokio-rs/tokio --jq '.pushed_at, .stargazers_count'

架构设计

技术决策后，设计架构：

1. 组件图

## 系统组件

[组件 A] --> [组件 B] --> [组件 C]
       |                               |
       v                               v
  [数据库]                    [外部 API]

2. 数据流

记录数据在系统中的流动：

用户输入
处理步骤
存储点
输出路径

3. 目录结构

建议项目结构：

项目/
├── src/
│   ├── main.rs
│   ├── api/
│   ├── db/
│   └── ...
├── tests/
├── Cargo.toml
└── ...

4. 关键模式

记录要遵循的架构模式：

错误处理方法
日志策略
配置管理
测试方法

输出: project.architecture.md

# 项目架构

**生成时间:** [时间戳]
**基于:** project.vision-analysis.md

## 技术栈

### 核心技术

| 层次 | 技术 | 版本 | 理由 |
|-------|------------|---------|-----------|
| 语言 | Rust | 1.75 | 性能、安全性 |
| Web 框架 | Axum | 0.7.4 | 人性化、异步 |
| 数据库 | SQLite | 3.45 | 简单、嵌入式 |
| ORM | SQLx | 0.7.3 | 编译时检查 |

### 开发工具

| 工具 | 版本 | 用途 |
|------|---------|---------|
| cargo-watch | 8.5.2 | 自动重建 |
| sqlx-cli | 0.7.3 | 迁移 |

## 架构决策

### ADR-001: [决策标题]

**上下文:** [为何需要此决策]
**决策:** [决定的內容]
**理由:** [选择此选项的原因]
**后果:** [决策的影响]

### ADR-002: ...

## 系统设计

### 组件概述

[图或描述]

### 数据流

[数据如何在系统中移动]

### 目录结构

[建议结构]


## 关键模式

### 错误处理
[方法]

### 配置
[方法]

### 测试策略
[方法]

## 依赖项

### 生产依赖项

```toml
[dependencies]
axum = "0.7.4"
tokio = { version = "1.35", features = ["full"] }
sqlx = { version = "0.7.3", features = ["sqlite", "runtime-tokio"] }

开发依赖项

[dev-dependencies]

安全考虑

[安全项 1]
[安全项 2]

性能考虑

[性能项 1]
[性能项 2]

部署策略

[项目将如何部署]

下一步

初始化项目结构
设置 CI/CD
开始路线图规划


---

## 与协调器的集成

架构设计后：

1. 将 `project.architecture.md` 保存到项目根目录
2. 更新 `knowledge/project/decisions.md` 添加 ADRs
3. 向协调器发送完成信号
4. 路线图技能使用架构作为输入

---

## 检查清单

完成架构前：

- [ ] 评估所有技术层次
- [ ] 验证每个选择的最新稳定版本
- [ ] 确认选择之间的兼容性
- [ ] 记录决策及理由
- [ ] 建议目录结构
- [ ] 定义关键模式
- [ ] 列出依赖项及版本
- [ ] 将 ADRs 记录到 knowledge/project/decisions.md
- [ ] 架构保存到 `project.architecture.md`

---

## 示例: Web 应用架构

**输入:** 愿景分析显示 PWA 财务追踪器

**输出:**

```markdown
# 项目架构

## 技术栈

### 核心技术

| 层次 | 技术 | 版本 | 理由 |
|-------|------------|---------|-----------|
| 语言 | TypeScript | 5.3.3 | 类型安全、生态系统 |
| 框架 | SvelteKit | 2.5.0 | 快速、简单、SSR+SPA |
| 样式 | Tailwind CSS | 3.4.1 | 实用优先、快速 |
| 数据库 | IndexedDB (Dexie) | 4.0.1 | 离线优先 PWA |
| 构建 | Vite | 5.0.12 | 快速、现代 |

### PWA 栈

| 组件 | 技术 | 版本 |
|-----------|------------|---------|
| Service Worker | Workbox | 7.0.0 |
| Manifest | Vite PWA Plugin | 0.17.4 |

## 架构决策

### ADR-001: 选择 SvelteKit 而非 React/Next.js

**上下文:** 需要现代前端框架用于 PWA
**决策:** 使用 SvelteKit 2.x
**理由:**
- 更小的捆绑大小（对 PWA 关键）
- 内置 SSR 和静态生成
- 比 React 更简单的心理模型
- 优秀的 TypeScript 支持
**后果:** 社区比 React 小，但对此项目足够。

### ADR-002: 使用 Dexie 处理 IndexedDB

**上下文:** 需要离线数据存储
**决策:** 使用 Dexie.js 4.x 包装 IndexedDB
**理由:**
- 基于 Promise 的 API
- 优秀的 TypeScript 支持
- 响应式查询
- 维护良好
**后果:** 额外 30kb 捆绑，但值得开发体验改善。