chill/chill_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update from Sync Service

Browse Source
This commit is contained in:
FNS Service
2026-06-22 11:30:51 +08:00
parent eb80b7a8c1
commit 682e3e52df
52 changed files with 10099 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
2026-06-22.md Executable file
View File

@@ -0,0 +1,5 @@
- [ ] ⏫ 无人机测流项目预算
- [ ] 🔼

273
AI工程/3DGS在VR眼镜上的显示方案研究.md Executable file
View File

@@ -0,0 +1,273 @@
# 3DGS 数据在 VR 眼镜上的显示方案研究
> 研究日期：2026-06-07
> 关键词：3DGS, 3D Gaussian Splatting, SuperSplat, VR, WebXR, Meta Quest
---
## 一、3DGS (3D Gaussian Splatting) 技术概述
### 什么是 3DGS？
3D Gaussian Splatting 是 2023 年 SIGGRAPH 发表的革命性 3D 场景表示技术（论文作者：Kerbl, Kopanas 等），用**数百万个半透明的椭圆高斯球**来重建 3D 场景，而非传统的多边形网格。
**核心优势：**
- 📸 **照片级真实感**：从照片/视频直接生成，效果逼真
- ⚡ **实时渲染**：优化后可达交互帧率
- 🌟 **体积表示**：自然处理半透明材质、精细细节、复杂光照
- 💰 **低成本**：比传统 3D 建模便宜且快速
### 数据格式
| 格式 | 说明 | 大小 |
|------|------|------|
| **PLY** | 标准二进制 3DGS 格式（未压缩） | 大（数百MB~数GB） |
| **SOG** | PlayCanvas 压缩格式（ZIP + WebP） | PLY 的 1/15~1/20 |
| **SPZ** | SuperSplat 项目格式 | 压缩后更小 |
---
## 二、SuperSplat 工具
### 基本信息
- **开发者**：PlayCanvas
- **GitHub**：https://github.com/playcanvas/supersplat（⭐9k+）
- **在线版**：https://superspl.at/editor
- **许可证**：MIT（免费开源）
- **技术栈**：纯 Web（TypeScript + PlayCanvas Engine），浏览器直接运行
### 核心功能
1. **检查（Inspect）**：加载 .ply / .splat 文件，查看高斯球分布
2. **编辑（Edit）**：选中/删除/移动高斯球，清理噪点
3. **优化（Optimize）**：压缩、裁剪、降采样，减小文件体积
4. **发布（Publish）**：导出优化后的文件，或直接发布到 SuperSplat 平台
### ⚠️ SuperSplat 本身不支持 VR
SuperSplat 是一个**编辑器**，运行在桌面浏览器的 2D 界面中。它**不直接支持 VR 模式**。
要在 VR 中查看 3DGS 数据，需要使用以下方案之一。
---
## 三、3DGS 在 VR 上显示的技术方案
### 方案对比
| 方案 | 平台 | 渲染技术 | VR 支持 | 难度 | 适用场景 |
| ---------------------- | --------------- | -------------------- | -------- | ---- | ---------------- |
| **PlayCanvas + WebXR** | Web 浏览器 | WebGL/WebGPU | ✅ WebXR | ⭐⭐ | 最简单，跨平台 |
| **RSR** | Windows 原生 | Direct3D 12 + OpenXR | ✅ OpenXR | ⭐ | 最佳性能，PC VR |
| **Unity VR Viewer** | Windows (Unity) | CUDA + OpenXR | ✅ OpenXR | ⭐⭐⭐ | 开发者，需 NVIDIA GPU |
| **A-Frame + GS** | Web 浏览器 | WebGL | ✅ WebXR | ⭐⭐ | 快速原型 |
| **VRSplat** | Linux/CUDA | CUDA + OpenGL | ✅ 研究 | ⭐⭐⭐⭐ | 学术研究 |
### 方案 1：PlayCanvas + WebXR（推荐入门）
**原理**：PlayCanvas Engine 原生支持 Gaussian Splatting 渲染 + WebXR API。
**流程**：
1. 用 SuperSplat 编辑/优化 3DGS 数据
2. 导出 PLY 或 SOG 文件
3. 在 PlayCanvas 项目中加载并启动 WebXR VR 会话
**优势**：
- 浏览器直接运行，无需安装
- Meta Quest 浏览器原生支持 WebXR
- Apple Vision Pro Safari 也支持
**代码示例**（PlayCanvas）：
```javascript
// 检查 VR 支持并启动
button.element.on('click', () => {
if (app.xr.supported && app.xr.isAvailable(pc.XRTYPE_VR)) {
app.xr.start(entity.camera, pc.XRTYPE_VR, pc.XRSPACE_LOCALFLOOR);
}
});
```
**局限**：
- 浏览器性能有限，大场景可能卡顿
- 移动端 VR（Quest 独立模式）渲染能力受限
### 方案 2：RSR — Rapid Splat Renderer（推荐高性能）
- **GitHub**：https://github.com/warpgatelabs/RSR（⭐44）
- **技术**：Direct3D 12 + OpenXR
- **平台**：Windows only
**特点**：
- 原生 D3D12 渲染，性能最强
- 支持 PLY 和 SOG 格式
- 支持完整球谐函数（SH up to order 3）
- 可选 NVIDIA DLSS 超分辨率（RTX GPU）
- **免费个人/非商业使用**
**使用方式**：
```
RSR.exe # 启动文件浏览器
RSR.exe <path-to-scene> # 直接打开场景
```
按 V 或 F11 切换 VR 模式，支持 OpenXR（SteamVR / Oculus / 其他 OpenXR 运行时）。
**VR 控制方式**：
- 左摇杆：移动
- 右摇杆：转向/上下
- 左/右手柄 Grip：拖拽/缩放场景
- A 键：重置视角
**系统要求**：
- Windows 10/11 x64
- DirectX 12 GPU
- OpenXR 兼容 VR 头显
- NVIDIA RTX GPU（可选，用于 DLSS）
### 方案 3：Unity + CUDA VR Viewer
- **GitHub**：https://github.com/clarte53/GaussianSplattingVRViewerUnity（⭐373）
- **技术**：Unity + CUDA 原生插件 + OpenXR
**特点**：
- 使用原始 CUDA 光栅化器，渲染质量最高
- 支持同时加载多个模型
- 支持深度混合（高斯球与 3D 场景混合）
- 支持多相机渲染
**性能参考**（bicycle 场景，RTX 3060 Ti）：
- 桌面 OpenGL (FOV 60°): 12ms (80 FPS)
- Unity DirectX11 (FOV 60°): 15ms (67 FPS)
- **Unity OpenXR (双眼, FOV 90°): 38ms (26 FPS)**
**注意**：VR 模式需要渲染双眼 + 更大 FOV，性能开销约 2.5-3x
**硬件要求**：
- CUDA GPU（Compute Capability 7.0+，即 RTX 2060 以上）
- 推荐 RTX 4070+
- 16GB RAM
### 方案 4：VRSplat（学术方案）
- **GitHub**：https://github.com/Cekavis/VRSplat（⭐57）
- **论文**："VRSplat: Fast and Robust Gaussian Splatting for Virtual Reality"
- 专门优化 VR 渲染的学术方案，解决了 VR 中的高斯球渲染痛点
---
## 四、VR 眼镜选型
### 根据 3DGS 渲染需求分类
3DGS 渲染对 GPU 要求极高（百万级高斯球实时排序+渲染），需要区分两种使用模式：
**A. PC VR 模式（推荐）**：VR 眼镜连接 PC，由 PC GPU 负责渲染
**B. 独立 VR 模式**：VR 眼镜自带芯片渲染，性能受限
### 推荐设备
#### 🥇 方案 A：PC VR（最佳体验）
| 设备 | 价格（人民币） | 分辨率 | FOV | 连接方式 | 推荐理由 |
|------|---------------|--------|-----|---------|---------|
| **Meta Quest 3** | ¥3,500-4,000 | 2064×2208/眼 | 110° | WiFi串流/USB-C | 性价比之王，WebXR+PC串流都支持 |
| **Meta Quest 3S** | ¥2,200-2,800 | 1832×1920/眼 | 96° | WiFi串流/USB-C | 预算有限首选，3 的降配版 |
| **Pico 4 Ultra** | ¥3,500-4,000 | 2160×2160/眼 | 105° | WiFi串流/USB-C | 国行首选，售后好，国内生态完善 |
| **Pico 4** | ¥1,800-2,500 | 2160×2160/眼 | 105° | WiFi串流/USB-C | 性价比之选 |
| **Valve Index** | ¥6,000+ | 1440×1600/眼 | 130° | DP直连 | FOV最大，刷新率144Hz |
| **HTC Vive Pro 2** | ¥7,000+ | 2448×2448/眼 | 120° | DP直连 | 分辨率最高，专业级 |
| **Bigscreen Beyond 2** | ¥7,000+ | 2560×2560/眼 | 110° | DP直连 | 超轻(仅127g)，Micro OLED，极致画质 |
**PC VR 的关键**：GPU 决定体验，建议：
- **最低**：RTX 3060 Ti（VR 模式约 26 FPS，可接受但不算流畅）
- **推荐**：RTX 4070 Super 以上（流畅体验 60+ FPS）
- **理想**：RTX 4080/4090（大场景也能流畅）
#### 🥈 方案 B：独立 VR（便捷但性能受限）
| 设备 | 价格 | 芯片 | 分辨率 | 3DGS 能力 | 备注 |
|------|------|------|--------|-----------|------|
| **Meta Quest 3** | ¥3,500 | Snapdragon XR2 Gen 2 | 2064×2208/眼 | ⚠️ 仅小场景 | 浏览器 WebXR 运行 PlayCanvas |
| **Meta Quest 3S** | ¥2,200 | Snapdragon XR2 Gen 2 | 1832×1920/眼 | ⚠️ 仅小场景 | 同上 |
| **Apple Vision Pro** | ¥25,000+ | M2 + R1 | 3660×3200/眼 | ✅ 较好 | Safari WebXR，芯片性能强 |
| **Pico 4 Ultra** | ¥3,500 | Snapdragon XR2 Gen 2 | 2160×2160/眼 | ⚠️ 仅小场景 | 国行，浏览器支持 WebXR |
**独立模式的限制**：
- 移动端 GPU 性能仅为 PC 的 1/10~1/5
- 3DGS 场景必须大幅压缩（减少高斯球数量到数十万级）
- 只能通过 WebXR 浏览器方案（PlayCanvas）
- 大场景基本无法流畅运行
#### 🥉 方案 C：混合模式（Quest 串流 PC）
这是**性价比最优方案**：
1. 购买 Meta Quest 3 / Pico 4 Ultra
2. 独立使用时通过浏览器 WebXR 查看小场景
3. 连接 PC 时通过 Steam Link / Air Link / Virtual Desktop 使用 RSR 等原生方案
**一台设备，两种模式，兼顾便携和性能。**
### 最终推荐
| 需求 | 推荐设备 | 理由 |
|------|---------|------|
| 💰 **预算优先** | Meta Quest 3S + PC | ¥2,200 起步，PC 串流体验完整 |
| ⚖️ **性价比最优** | **Meta Quest 3 + PC（RTX 4070+）** | ¥3,500，独立+PC双模式 |
| 🇨🇳 **国内首选** | **Pico 4 Ultra + PC** | 国行保修，国内售后完善 |
| 🎯 **专业级** | Bigscreen Beyond 2 + PC（RTX 4090） | Micro OLED 极致画质 |
| 🍎 **苹果生态** | Apple Vision Pro | 25K+，M2 芯片性能强，但贵 |
---
## 五、完整工作流
```
拍照/录像 → 训练3DGS模型 → SuperSplat编辑优化 → VR显示
↓ ↓ ↓ ↓
手机/相机 gaussian-splatting superspl.at/editor ↓
Polycam gsplat/nerfstudio 裁剪/压缩/清理 ↓
Luma AI ↓ ↓
导出 PLY/SOG ↓
┌─────────┴──────────┐
↓ ↓
WebXR方案 原生方案
(PlayCanvas) (RSR/Unity)
↓ ↓
Quest浏览器 PC + OpenXR
(独立模式) (PC VR模式)
```
---
## 六、关键参考链接
### 工具
- SuperSplat Editor: https://superspl.at/editor
- PlayCanvas Engine: https://playcanvas.com
- RSR (Rapid Splat Renderer): https://github.com/warpgatelabs/RSR
- Unity VR Viewer: https://github.com/clarte53/GaussianSplattingVRViewerUnity
- VRSplat: https://github.com/Cekavis/VRSplat
- Splatapult (C++ OpenGL): https://github.com/hyperlogic/splatapult
### 3DGS 训练
- 原始实现: https://github.com/graphdeco-inria/gaussian-splatting
- gsplat (CUDA 加速): https://github.com/nerfstudio-project/gsplat
- Nerfstudio: https://github.com/nerfstudio-project/nerfstudio
### 数据来源
- Polycam (拍照生成3DGS): https://poly.cam/gaussian-splatting/
- Luma AI: https://lumalabs.ai
### 文档
- PlayCanvas Gaussian Splatting: https://developer.playcanvas.com/user-manual/gaussian-splatting/
- PlayCanvas XR: https://developer.playcanvas.com/user-manual/xr/
- SuperSplat User Guide: https://developer.playcanvas.com/user-manual/gaussian-splatting/editing/supersplat/
---
## 七、总结建议
1. **如果你有 PC（RTX 4070+）**：买 Meta Quest 3 或 Pico 4 Ultra，用 RSR 渲染，体验最佳
2. **如果只有笔记本**：Quest 3S 最低预算入门，通过 Steam Link 连笔记本
3. **如果要给客户展示**：SuperSplat 编辑优化 → PlayCanvas WebXR 发布 → 发链接即可在 Quest 浏览器打开
4. **3DGS 数据必须优化**：原始 PLY 文件太大，用 SuperSplat 裁剪+压缩后再用于 VR

114
AI工程/AI上下文体系_团队级AICoding.md Executable file
View File

@@ -0,0 +1,114 @@
# AI上下文体系 - 团队级AI Coding简明手册
> 来源：幻灯片分享，2026-06-20 归档
## 核心理念
使用完整的文档来描述上下文和约束体系，**区分过程方案和事实方案，减少维护成本**。
---
## 文档分层结构
| 目录 | 用途 | 维护者 | 性质 |
|------|------|--------|------|
| `docs/standards` | 标准规格（API、命名、安全规范） | Tech Lead | 事实方案 |
| `docs/features` | 需求规格 | 产品/BA | 事实方案 |
| `docs/plans` | 计划规格（每轮任务实现方案） | AI/开发 | **过程方案** |
| `docs/designs` | 设计规格（DB、表等 Source of Truth） | AI/开发 | 事实方案 |
| `docs/others` | 架构决策、Release、测试用例 | — | 按需 |
| `AGENTS.md` | 宪法级约束 | — | 事实方案 |
---
## 过程方案 vs 事实方案
### 过程方案（Plans）
**定义**：每次 Plan/Go 循环产生的**执行计划**，记录"我们打算怎么做"。
**特点**：
- 临时的、一次性的
- 每次创建**新文件**（如 `plan-2026-06-20-feature-x.md`）
- 细微修改**不再更新**旧文件，直接创建新版本
- 作为执行记录，不是长期参考
**示例**：
```
docs/plans/
├── plan-2026-06-01-user-auth.md
├── plan-2026-06-05-user-auth-v2.md
└── plan-2026-06-10-payment-flow.md
```
**为什么这样设计**：
- 避免反复修改同一文件导致的 Git 冲突
- 保留历史决策轨迹，方便复盘
- AI 每次执行完可以"丢弃"，不污染长期文档
---
### 事实方案（Designs / Standards / Features）
**定义**：反映系统**当前真实状态**的文档，是 Source of Truth。
**特点**：
- 长期有效的、稳定的
- 每次变更以**最终态更新**（覆盖式修改）
- 作为下一次 Plan 的**起点和依据**
- 必须与实际代码/系统保持一致
**示例**：
```
docs/designs/
├── database-schema.md # 当前数据库表结构
├── api-endpoints.md # 当前 API 定义
└── architecture.md # 当前架构图
docs/standards/
├── coding-style.md # 编码规范
└── security-guidelines.md # 安全规范
```
**为什么这样设计**：
- AI 每次 Plan 时读取这些文档，获得"当前真相"
- 避免 AI 基于过时的信息做决策
- 减少维护成本：只维护一份最终态
---
## Plan/Go 模式的规格流转
```
起点 Features
↓
Standards（约束）
↓
TDD 驱动测试 + 代码
↓
事实方案 Designs（更新最终态）
↓
过程方案 Plans（执行记录）
↓
回到起点 Features（验收）
```
**流转规则**：
- **追加**：创建新文件，细微修改不再更新 → 过程方案
- **变更**：以最终态更新，作为下一次 Plan 的事实依据 → 事实方案
---
## 实践建议
1. **AGENTS.md 作为宪法**：定义 AI 的行为边界和基本原则
2. **区分"打算做"和"已做完"**：Plans 是意图，Designs 是事实
3. **减少维护成本**：过程方案不维护，事实方案必须维护
4. **AI 友好**：每次 Plan 前读取事实方案，执行后更新事实方案
---
## 参考
- 幻灯片：如何让AI听话-构建AI上下文体系
- 归档日期：2026-06-20

588
AI工程/AI辅助硬件设计开发最佳实践.md Executable file
View File

@@ -0,0 +1,588 @@
# AI辅助硬件设计开发最佳实践
> 研究日期：2026-06-11
> 状态：深度研究版
---
## 目录
1. [概述](#概述)
2. [AI辅助硬件设计全景图](#ai辅助硬件设计全景图)
3. [AI辅助设计评审详解](#ai辅助设计评审详解)
4. [LLM辅助芯片设计](#llm辅助芯片设计)
5. [Agentic EDA趋势](#agentic-eda趋势)
6. [国内外工具对比](#国内外工具对比)
7. [最佳实践建议](#最佳实践建议)
8. [风险与局限](#风险与局限)
9. [参考资料](#参考资料)
---
## 概述
### 什么是AI辅助硬件设计？
AI辅助硬件设计是指将人工智能技术（特别是大语言模型LLM和强化学习RL）应用于电子硬件设计全流程，包括：
- **原理图设计**：元器件选型、电路拓扑生成、原理图绘制
- **PCB设计**：布局、布线、层叠设计
- **设计评审**：DRC/ERC检查、信号完整性分析、EMC评估、DFM分析
- **仿真验证**：热仿真、信号完整性仿真、电源完整性仿真
- **芯片设计**：RTL生成、验证用例生成、物理设计优化
### 发展时间线
| 时间 | 里程碑 |
|------|--------|
| 2020 | Synopsys推出DSO.ai，首次将强化学习引入芯片物理设计 |
| 2021 | Cadence推出Cerebrus AI引擎 |
| 2023 | Quilter.ai成立，专注AI PCB设计 |
| 2024 | Flux.ai获B轮融资，用户突破100万 |
| 2025 | 华秋发布国内首款AI EDA工具 |
| 2025 | 嘉立创接入大模型，实现自然语言选型+AI建库 |
| 2025 | Quilter获2500万美元B轮融资 |
| 2026 | Agentic EDA概念兴起，从L2辅助迈向L3自主 |
---
## AI辅助硬件设计全景图
### 板级设计工具
#### Quilter.ai ⭐⭐⭐⭐⭐
- **官网**：https://www.quilter.ai
- **核心技术**：物理驱动的强化学习 + 大模型
- **主要能力**：
- 从原理图自动生成PCB布局布线
- 自动优化信号完整性、电源完整性
- 自动DRC/DFM检查
- 设计时间从数周缩短到数小时
- **融资历程**：
- 2024年：2700万美元B轮
- 2025年4月：2500万美元B+轮
- **适用场景**：消费电子、IoT、工业控制
- **局限**：复杂高速板仍需人工干预
#### Flux.ai ⭐⭐⭐⭐
- **官网**：https://www.flux.ai
- **核心技术**：云端协作 + AI辅助布局
- **主要能力**：
- 实时多人协作编辑
- AI辅助元件放置和走线建议
- 实时DRC检查
- 内置元器件数据库（100万+器件）
- **用户规模**：100万+注册用户
- **定价**：免费版 + 付费Pro版
- **适用场景**：教育、快速原型、小团队
#### 华秋AI EDA ⭐⭐⭐
- **官网**：https://www.huqiu.com
- **定位**：国内首款深度融合大模型的AI EDA工具
- **主要能力**：
- 自然语言描述→电路原理图
- AI元器件推荐
- 智能布局建议
- 与华秋PCB打样深度集成
- **特色**：开源+AI，与嘉立创生态打通
- **局限**：与国际顶尖工具有2-3年差距
#### 嘉立创EDA ⭐⭐⭐⭐
- **官网**：https://www.lceda.com
- **2026年新能力**：
- 自然语言选型：输入功能描述，推荐合适元器件
- AI智能建库：导入器件手册自动创建符号+封装
- 原理图辅助设计：基于大模型的电路建议
- 集成ERC/DRC/DFM验证工具
- **企业版特色**：
- 团队协作
- 问题前置到设计阶段
- 与LCSC元器件商城深度集成
- **用户规模**：全球最大EDA用户群之一
### 芯片级EDA工具
#### Synopsys DSO.ai ⭐⭐⭐⭐⭐
- **定位**：AI驱动的芯片物理设计自动化
- **核心技术**：强化学习
- **主要能力**：
- 自动探索布局布线设计空间
- 优化PPA（性能、功耗、面积）
- 时序收敛优化
- 自动识别关键路径
- **效果**：设计周期缩短30-50%，PPA优化提升10-20%
- **用户**：Intel、NVIDIA、Qualcomm等头部芯片公司
#### Cadence Cerebrus ⭐⭐⭐⭐⭐
- **定位**：AI辅助的全流程芯片设计
- **主要能力**：
- 智能布局规划
- 自动时钟树综合优化
- 布线资源智能分配
- 设计空间探索
- **集成**：与Cadence全流程工具深度集成
- **效果**：工程效率提升2-3倍
#### 华大九天 ⭐⭐⭐
- **定位**：国产全流程EDA工具
- **AI能力**：正在逐步引入AI辅助
- **主要工具**：
- 模拟电路设计
- 平板显示设计
- 晶圆制造工具
- **差距**：AI能力与国际顶尖仍有差距
---
## AI辅助设计评审详解
### 传统评审 vs AI评审
| 维度 | 传统评审 | AI评审 |
|------|----------|--------|
| **DRC** | 基于规则的静态检查 | 规则+AI预测潜在问题 |
| **信号完整性** | 手动仿真验证 | AI预测+自动优化建议 |
| **EMC/EMI** | 经验+后期测试 | AI预判+设计阶段优化 |
| **DFM** | 人工对照检查表 | AI自动分析+建议 |
| **热分析** | 后仿真 | AI预测+布局优化 |
| **评审时间** | 数天到数周 | 数小时 |
| **可追溯性** | 人工记录 | 自动生成评审报告 |
### DRC（设计规则检查）
#### 传统DRC
- 基于制造厂商提供的规则文件
- 检查线宽、线距、孔径等几何参数
- 只能发现明确的违规，无法预测潜在问题
#### AI增强DRC
- **预测性检查**：基于历史数据预测可能的制造问题
- **上下文感知**：理解设计意图，区分关键/非关键违规
- **自动修复建议**：不仅报告问题，还给出修复方案
- **持续学习**：从制造反馈中学习，更新检查规则
**代表工具**：
- Quilter.ai：自动DRC + 修复建议
- 嘉立创EDA：集成DRC + DFM分析
- Cadence Cerebrus：智能DRC优先级排序
### 信号完整性（SI）评审
#### AI在SI领域的应用
1. **串扰预测**
- 传统：需要完整3D电磁仿真，耗时数小时
- AI：基于几何特征快速预测串扰水平，秒级响应
2. **反射分析**
- 传统：需要S参数仿真
- AI：基于走线拓扑自动识别阻抗不连续点
3. **衰减预测**
- 传统：需要传输线仿真
- AI：根据走线长度、介质、频率预测衰减
4. **自动优化建议**
- 调整走线间距
- 建议参考平面层叠
- 推荐端接方案
**代表工具**：
- Quilter.ai：内置SI预测引擎
- Cadence Sigrity + AI：信号完整性仿真+AI优化
- Ansys SIwave + ML：机器学习加速仿真
### EMC/EMI评审
#### AI辅助EMC评审
1. **辐射热点预测**
- 基于电流回路分析预测辐射源
- 识别高速信号回流路径不连续
2. **自动屏蔽建议**
- 推荐屏蔽罩位置
- 建议滤波电容放置
3. **接地策略优化**
- 分析接地方案
- 建议分割/统一地平面策略
4. **预合规检查**
- 预测EMC测试结果
- 提前识别可能的不合规项
**现状**：
- EMC领域的AI应用相对滞后
- 主要因为EMC问题复杂，变量多
- 目前更多是辅助分析，还无法完全自动化
### DFM（可制造性分析）
#### AI在DFM领域的应用
1. **焊接缺陷预测**
- 基于焊盘设计预测虚焊/桥接风险
- 自动建议焊盘优化
2. **元件摆放优化**
- 考虑贴片机限制
- 优化元件方向便于自动贴片
3. **钻孔优化**
- 减少钻头更换次数
- 优化钻孔顺序
4. **成本预估**
- 基于设计特征预估制造成本
- 建议降本方案
**代表工具**：
- 嘉立创EDA：集成DFM检查
- Quilter.ai：DFM自动优化
- Valor（Mentor）：DFM分析+AI建议
### 热分析
#### AI辅助热设计
1. **热点预测**
- 基于功率分布预测PCB温度场
- 识别过热区域
2. **散热方案建议**
- 推荐散热过孔布局
- 建议铜皮面积
- 推荐散热器规格
3. **布局优化**
- 热源分散布局建议
- 敏感器件远离热源
**现状**：
- 热分析的AI应用还在早期
- 主要依靠传统CFD仿真
- AI可用于快速估算和布局建议
---
## LLM辅助芯片设计
### RTL代码生成
#### 当前能力
| 工具/模型 | 能力 | 成熟度 |
|-----------|------|--------|
| GPT-4/Qwen | 简单模块生成 | 中 |
| ChipNeMo（NVIDIA） | 芯片领域专用LLM | 中高 |
| RTLCoder | 开源RTL代码生成 | 中 |
| 内部微调模型 | 企业专用RTL生成 | 高 |
#### 应用场景
1. **模块模板生成**
- 输入：接口描述 + 功能需求
- 输出：Verilog/VHDL模块框架
2. **验证环境生成**
- 自动生成testbench
- 生成覆盖率驱动的测试用例
3. **代码补全**
- IDE集成的RTL代码补全
- 基于上下文的智能建议
4. **文档生成**
- 从RTL生成设计文档
- 自动生成注释
#### 局限性
- **复杂逻辑**：超过500行的复杂模块仍需人工
- **时序约束**：LLM难以理解时序要求
- **验证完备性**：生成的验证用例无法保证覆盖所有边界
- **安全关键**：汽车/航空芯片需要人工严格验证
### 验证用例生成
#### AI在验证领域的应用
1. **Testbench生成**
- 基于DUT接口自动生成框架
- 生成激励/监测组件
2. **覆盖率驱动测试**
- 分析覆盖率空洞
- 自动生成针对性的测试用例
3. **断言生成**
- 从规范文档提取要求
- 自动生成SVA断言
4. **回归测试优化**
- 智能选择最小回归测试集
- 优化仿真资源分配
**代表工具**：
- Synopsys Verdi + AI：调试辅助
- Cadence JedAI：验证优化
- 自研微调模型：企业专用
---
## Agentic EDA趋势
### EDA自动化等级
参考自动驾驶分级概念：
| 等级 | 名称 | 描述 | 代表 |
|------|------|------|------|
| L0 | 纯手工 | 完全人工操作 | 传统EDA |
| L1 | 辅助 | 单点AI辅助（如自动布线） | Altium自动布线 |
| L2 | 部分自动 | 多步骤AI辅助，人做决策 | 当前主流AI EDA |
| L3 | 有条件自主 | AI自主完成，人审核确认 | Agentic EDA（兴起中） |
| L4 | 高度自主 | AI完成绝大部分工作 | 实验阶段 |
| L5 | 完全自主 | 端到端全自动 | 尚未实现 |
### Agentic EDA的特征
1. **自主规划**
- 理解设计意图后自主制定设计方案
- 多步骤任务的自主分解和执行
2. **工具调用**
- 自主调用EDA工具链
- 根据中间结果调整策略
3. **迭代优化**
- 自动检测问题并修复
- 多轮迭代直到满足要求
4. **人机协作**
- 关键决策点请求人工确认
- 异常情况自动上报
### 2025-2026关键转折
- **技术成熟度**：LLM能力达到理解复杂设计规范的水平
- **工具集成**：EDA厂商纷纷推出AI Agent接口
- **用户接受度**：工程师开始习惯与AI协作
- **商业模式**：按设计任务收费的新模式出现
---
## 国内外工具对比
### 板级EDA对比
| 工具 | 国家 | AI能力 | 生态集成 | 价格 | 推荐度 |
|------|------|--------|----------|------|--------|
| Quilter.ai | 美国 | ⭐⭐⭐⭐⭐ | 中 | 高 | 高速/复杂板 |
| Flux.ai | 美国 | ⭐⭐⭐⭐ | 高 | 中 | 教育/小团队 |
| 华秋AI EDA | 中国 | ⭐⭐⭐ | 高 | 低 | 国产替代 |
| 嘉立创EDA | 中国 | ⭐⭐⭐⭐ | 很高 | 低 | 性价比首选 |
| Altium | 澳大利亚 | ⭐⭐ | 高 | 很高 | 传统强项 |
| KiCad | 开源 | ⭐ | 中 | 免费 | 开源爱好者 |
### 芯片级EDA对比
| 工具 | 国家 | AI能力 | 主要优势 |
|------|------|--------|----------|
| Synopsys DSO.ai | 美国 | ⭐⭐⭐⭐⭐ | 物理设计优化 |
| Cadence Cerebrus | 美国 | ⭐⭐⭐⭐⭐ | 全流程集成 |
| 华大九天 | 中国 | ⭐⭐ | 国产替代 |
| 中国电科SUNV-EDA | 中国 | ⭐⭐ | 军工应用 |
| Mentor（Siemens） | 德国/美国 | ⭐⭐⭐ | 验证强项 |
### 差距分析
**国产EDA与国际顶尖的差距**：
- **时间差距**：约2-3年
- **核心差距**：
- AI算法积累不足
- 大规模设计数据缺乏
- 先进制程支持有限
- **追赶优势**：
- 政策支持力度大
- 本土市场需求旺盛
- 开源生态发展迅速
---
## 最佳实践建议
### 选型建议
#### 按项目类型
| 项目类型 | 推荐工具 | 理由 |
|----------|----------|------|
| 简单IoT设备 | 嘉立创EDA + Quilter | 快速+低成本 |
| 消费电子 | Flux.ai / Quilter | 协作+质量 |
| 高速数字板 | Quilter.ai | SI/PI优化 |
| 汽车电子 | Cadence/Altium + AI辅助 | 可靠性优先 |
| 芯片设计 | Synopsys/Cadence | 业界标准 |
#### 按团队规模
| 团队规模 | 推荐方案 |
|----------|----------|
| 个人/学生 | KiCad + AI辅助工具 |
| 3-5人小团队 | Flux.ai / 嘉立创EDA |
| 10-50人团队 | Quilter.ai + 嘉立创 |
| 大型企业 | Cadence/Synopsys + 自研AI |
### 工作流建议
#### AI辅助设计评审最佳实践
1. **设计前**
- 明确设计约束（成本、性能、可靠性）
- 选择合适的AI工具
- 准备设计规范文档
2. **设计中**
- 利用AI进行方案探索
- 实时运行DRC检查
- AI预测SI/PI问题
3. **评审阶段**
- AI自动评审 + 人工审核
- 重点关注AI标记的问题
- 生成评审报告
4. **迭代优化**
- 根据AI建议优化设计
- 重新运行评审验证
- 记录经验反馈给AI
#### 人工评审重点
AI评审不能完全替代人工，以下方面需要人工重点关注：
1. **设计意图**：AI可能误解设计需求
2. **安全余量**：关键参数的安全裕度
3. **可靠性**：长期工作条件下的可靠性
4. **成本优化**：综合成本的权衡决策
5. **供应链**：元器件的可获得性和生命周期
### Prompt工程
#### 高效使用AI辅助设计的Prompt技巧
1. **明确上下文**
```
我需要设计一个STM32F4的最小系统板，工作温度-20~70°C，
供电3.3V，需要引出UART/SPI/I2C接口...
```
2. **分步骤提问**
```
第1步：请推荐合适的电源方案
第2步：基于此方案，设计电源电路
第3步：检查此电路的EMC风险
```
3. **提供约束**
```
成本<50元，PCB面积<50x50mm，4层板，
需要过CE认证...
```
4. **要求解释**
```
请解释为什么推荐这个方案，有什么优缺点？
与备选方案相比如何？
```
---
## 风险与局限
### 当前局限
1. **可解释性差**
- AI给出的建议难以追溯依据
- 难以满足安全认证的审计要求
2. **训练数据偏差**
- AI可能继承历史设计的缺陷
- 对新工艺/新材料缺乏经验
3. **安全关键领域受限**
- 汽车（ISO 26262）要求完整验证链
- 航空（DO-254）需要可追溯设计过程
- 医疗（IEC 62304）需要严格文档
4. **知识产权风险**
- AI生成的设计是否侵权？
- 训练数据中的专利问题
### 缓解策略
1. **人机协作**
- AI作为助手，人做最终决策
- 关键节点人工审核
2. **渐进采用**
- 从简单项目开始
- 逐步扩大AI应用范围
3. **建立规范**
- 制定AI辅助设计规范
- 明确人工审核清单
4. **持续学习**
- 积累AI使用经验
- 建立企业内部最佳实践
---
## 参考资料
### 工具官网
- Quilter.ai: https://www.quilter.ai
- Flux.ai: https://www.flux.ai
- 华秋EDA: https://www.huqiu.com
- 嘉立创EDA: https://www.lceda.com
- Synopsys: https://www.synopsys.com
- Cadence: https://www.cadence.com
### 技术文章（微信公众号）
- "华秋电子发布国内首款AI EDA工具!开启硬件设计Agent时代" - 愉悦资本
- "AI开始'造硬件'了:自然语言生成电路,大模型重写电子设计" - 天天AI研习社
- "Agentic EDA 黎明:从 AI 辅助到 AI 自主的芯片设计革命" - 麒芯说AI
- "让大模型真正懂电路:硬件 AI 大模型全流程工程化开发指南" - 万星智库
- "vibe PCB来了?关注这家AI公司" - 橙子随记
- "让设计更快,让研发更稳!嘉立创EDA企业级解决方案正式发布" - 嘉立创科技
### 行业报告
- "别吹了!现在的AI硬件设计工具,90%都是玩具" - AI硬件未来眼
- "AI越火,PCB越吃香!2026年最值得入局的硬核高薪赛道" - Layout日记
---
## 附录：术语表
| 术语 | 全称 | 含义 |
|------|------|------|
| EDA | Electronic Design Automation | 电子设计自动化 |
| DRC | Design Rule Check | 设计规则检查 |
| ERC | Electrical Rule Check | 电气规则检查 |
| DFM | Design for Manufacturing | 可制造性设计 |
| SI | Signal Integrity | 信号完整性 |
| PI | Power Integrity | 电源完整性 |
| EMC | Electromagnetic Compatibility | 电磁兼容性 |
| EMI | Electromagnetic Interference | 电磁干扰 |
| RTL | Register Transfer Level | 寄存器传输级 |
| PPA | Power, Performance, Area | 功耗、性能、面积 |
| LLM | Large Language Model | 大语言模型 |
| RL | Reinforcement Learning | 强化学习 |
| DUT | Device Under Test | 被测设备 |
| SVA | SystemVerilog Assertions | SystemVerilog断言 |
---
*本文档持续更新，最后修改：2026-06-11*

173
AI工程/GSD_Core_上下文工程框架.md Executable file
View File

@@ -0,0 +1,173 @@
# GSD Core - AI 编码上下文工程与规范驱动开发框架
> **GitHub**: https://github.com/open-gsd/gsd-core
> **npm**: `@opengsd/gsd-core`
> **License**: MIT
> **Slogan**: Git. Ship. Done.
> **研究日期**: 2026-06-07
---
## 一句话总结
GSD Core 是一套**上下文工程（Context Engineering）+ 规范驱动开发**框架，通过**全新上下文子代理（fresh-context subagent）** 架构解决 AI 编码中「上下文腐化」问题，让 Claude Code、Cursor、Codex 等 AI 编程工具在大型项目中保持高质量输出。
## 解决的核心问题：上下文腐化（Context Rot）
AI 编码会话随着对话轮次增加，上下文窗口逐渐被填满。模型不会报错，但输出质量**静默下降**：
- 开始 contradicts 早期决策
- 代码风格偏离初始约定
- 计划忽略早期明确的需求
- 臆造之前正确记忆的文件名/函数签名
这不是 bug，是 Transformer 注意力机制在长序列上的**固有特性**——信噪比随窗口填充而劣化。
## 核心方案：全新上下文子代理
**核心洞察**：编码会话中大部分工作（研究、规划、编写、验证）不需要在主上下文中进行。
架构设计：
- **主会话（编排器）**：不碰源文件，只负责派发代理、收集结果、更新状态。上下文缓慢增长。
- **子代理**：每个子代理以**干净 200k token 上下文**启动，只接收当前任务所需上下文，完成后终止。
```
主会话（轻量编排器）
├── Researcher Agent (200k fresh context)
├── Planner Agent (200k fresh context)
├── Plan-Checker Agent (200k fresh context)
├── Executor Agent × N (200k fresh context, 并行)
└── Verifier Agent (200k fresh context)
```
## 5阶段循环（Phase Loop）
每个里程碑通过重复的 5 步循环推进：
```
Discuss → [UI Design] → Plan → Execute → Verify → Ship
```
### 1. Discuss（讨论）
- 在规划前捕获实现决策（用什么库、错误处理策略、边界情况）
- 输出 `CONTEXT.md`（结构化决策记录）
- 几分钟对话避免几小时返工
### 2. UI Design（可选）
- 视觉相关阶段可选 `/gsd-ui-phase`
- 输出 `UI-SPEC.md`（布局、交互、视觉行为的设计契约）
### 3. Plan（规划）
- 3个全新上下文子代理依次运行：
- **Researcher** → 调研生态，输出 `RESEARCH.md`
- **Planner** → 读研究+CONTEXT，输出 `PLAN.md`
- **Plan-Checker** → 验证计划完整、一致、在范围内
- 计划按依赖波次排列，支持并行执行
### 4. Execute（执行）
- 每个 Executor 以 200k 干净上下文启动
- 只加载：项目摘要 + 阶段上下文 + 研究 + 具体 PLAN.md
- 原子提交，每 commit 对应一个计划任务
- 按波次并行，前波完成后启动后波
### 5. Verify（验证）
- 不只是测试，检查：
- 需求覆盖率（REQ-ID 是否都处理了）
- 决策覆盖率（CONTEXT.md 的决策是否落地了）
- 整体阶段目标对齐
- 输出 `VERIFICATION.md` + 修复计划（如有偏差）
### 6. Ship（交付）
- 创建 PR，归档阶段产物
- 更新 `STATE.md` 标记阶段完成
- 开始下一个阶段循环
## 关键文件结构
```
.planning/
├── STATE.md # 项目当前状态（里程碑/阶段/进度）——系统脊梁
├── phases/
│ ├── CONTEXT.md # 讨论阶段的实现决策
│ ├── RESEARCH.md # 调研发现
│ ├── PLAN.md # 具体执行计划（按波次）
│ ├── UI-SPEC.md # UI 设计契约（可选）
│ └── VERIFICATION.md # 验证报告
ROADMAP.md # 项目路线图
```
## 支持平台
Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等。
## 快速开始
```bash
npx @opengsd/gsd-core@latest
# 选择运行时和安装方式
/gsd-new-project
```
也提供轻量模式：
- `/gsd-quick` — 不需要完整阶段循环的快速任务
- `/gsd-fast` — 更轻量的即时操作
## 三大支柱
1. **Fresh-context subagents** — 每个子代理干净启动，结构性地解决上下文腐化
2. **Spec-driven development** — 执行前产出结构化产物（CONTEXT/RESEARCH/PLAN/VERIFICATION），代理精确执行
3. **Meta-prompting** — 代理定义本身是精心工程化的 prompt，编码了领域知识
## 与 Trellis 对比
| 维度 | GSD Core | Trellis |
|------|----------|---------|
| **核心理念** | 上下文工程 + 子代理架构 | 规范持久化 + 记忆 |
| **解决痛点** | 上下文腐化（质量随窗口填充下降） | AI 每次从零开始（无记忆） |
| **架构** | 主会话编排 + fresh-context subagents | 4阶段循环（Plan→Implement→Verify→Finish） |
| **记忆机制** | 文件系统（.planning/ 目录） | .trellis/workspace/ journal |
| **平台支持** | 10+ 平台 | 14+ 平台 |
| **License** | MIT | AGPL-3.0 |
| **适用规模** | 中大型复杂项目（上下文腐化严重时收益最大） | 个人/团队通用 |
| **轻量模式** | /gsd-quick, /gsd-fast | 无 |
| **验证深度** | 需求+决策+目标三重验证 | lint+type-check+测试 |
## 评价
### ✅ 优点
- **深刻理解了 AI 编码的根本问题**（上下文腐化是 Transformer 固有特性，不是 workaround 能解决的）
- fresh-context subagent 是**结构性解决方案**，不是权宜之计
- 5阶段循环设计严谨，每步都有明确存在的理由
- 验证环节不仅是测试，而是需求+决策+目标三重覆盖
- MIT 许可证友好
- 诚实承认 trade-off（简单任务不需要用完整循环）
### ⚠️ 注意
- 对简单任务有**流程开销**（官方也承认）
- 子代理启动延迟比单会话编辑慢
- 需要一定学习曲线理解阶段循环概念
- 最适合**中大型复杂项目**，小项目用 /gsd-quick 即可
### 📊 项目成熟度
- 完整文档体系（教程/指南/参考/概念）
- CI/CD 测试覆盖
- 活跃的社区（Discord + 多语言 README）
- 多平台支持
- 有 CLI 工具和完整命令体系
## 核心洞察（值得记住）
> "The model is not forgetting — it never 'remembered' in the human sense. It is weighting relevance across a finite window, and as that window fills with accumulated noise, signal-to-noise degrades."
> "An executor that runs with 180k tokens of accumulated session history is a degraded executor. An executor that starts clean and reads only what its plan requires is an executor operating at full capacity."
## 相关链接
- [GitHub](https://github.com/open-gsd/gsd-core)
- [npm](https://www.npmjs.com/package/@opengsd/gsd-core)
- [Discord](https://discord.gg/mYgfVNfA2r)
- [上下文工程详解](https://github.com/open-gsd/gsd-core/blob/next/docs/explanation/context-engineering.md)
- [阶段循环详解](https://github.com/open-gsd/gsd-core/blob/next/docs/explanation/the-phase-loop.md)
---
*研究归档：2026-06-07 | 路径：/obsidian/AI工程/GSD_Core_上下文工程框架.md*

318
AI工程/HyperFrames_HTML视频引擎研究.md Executable file
View File

@@ -0,0 +1,318 @@
# HyperFrames — HTML 视频引擎完全研究
> 研究日期：2026-06-01
> 官网：https://www.hyperframes.net/zh
> GitHub：https://github.com/heygen-com/hyperframes
> 文档：https://hyperframes.mintlify.app/introduction
> 开发商：HeyGen
> 许可证：MIT（开源引擎）
---
## 一句话概括
**用 HTML 写视频。** HyperFrames 是 HeyGen 出品的开源 HTML-to-video 框架，将 HTML composition 直接渲染成 MP4，专为 AI Agent 驱动的视频生产设计。
---
## 核心理念
- 视频的「源代码」就是 HTML 文件
- 用 `data-start`、`data-duration`、`data-track-index` 等 data attribute 定义时间线
- 动画用熟悉的 GSAP、Lottie、CSS 等任何可 seek 到指定帧的运行时
- **确定性渲染**：同一输入 → 完全相同的输出帧，可 CI 化、可回归测试
- 不需要 React，不需要时间线编辑器，不需要专有格式
---
## 架构与包
| 包 | 作用 |
|---|---|
| `@hyperframes/core` | 类型定义、HTML 解析、composition lint |
| `@hyperframes/engine` | seek 驱动的帧捕获引擎（headless Chrome） |
| `@hyperframes/producer` | 捕获 + FFmpeg 编码的完整流水线 |
| `@hyperframes/studio` | 可视化编辑器 UI |
| `hyperframes (CLI)` | 命令行工具，默认非交互，适合 Agent 自动化 |
### 渲染管线
```
HTML Composition → headless Chrome 逐帧捕获 (beginFrame API) → FFmpeg 编码 → MP4/MOV/WebM
```
渲染模式：
- **Local Mode**：本地 Puppeteer + 系统 FFmpeg，开发迭代快
- **Docker Mode**：确定性输出，固定 Chrome 版本 + 字体集，适合 CI/CD
---
## Composition 模型
### 项目结构
```
project/
├── index.html # 根 composition（视频入口）
├── compositions/ # 子 composition（可复用片段）
│ ├── intro-anim.html
│ ├── caption-overlay.html
│ └── outro-title.html
├── assets/ # 媒体素材
│ ├── video.mp4
│ ├── music.mp3
│ └── logo.png
└── meta.json # 项目元数据
```
### 最小示例
```html
<div id="root" data-composition-id="demo"
data-start="0" data-width="1920" data-height="1080">
<h1 id="title" class="clip"
data-start="1" data-duration="4" data-track-index="1"
style="font-size: 72px; color: white;">
Welcome to Hyperframes
</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
const tl = gsap.timeline({ paused: true });
tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
window.__timelines = window.__timelines || {};
window.__timelines["demo"] = tl;
</script>
</div>
```
### 三条核心规则
1. **根元素**必须有 `data-composition-id`、`data-width`、`data-height`
2. **定时元素**需要 `data-start`、`data-duration`、`data-track-index` 和 `class="clip"`
3. **GSAP timeline** 必须用 `{ paused: true }` 创建，注册到 `window.__timelines`
### 嵌套 Composition
- **外部文件**：用 `data-composition-src` 引用，内容包在 `<template>` 里
- **内联**：直接在父 composition 里定义
- 框架自动管理子 composition 的时间线嵌套
### 变量系统
- 在 `<html>` 上用 `data-composition-variables` 声明变量（id + type + default）
- 在实例上用 `data-variable-values` 传值
- 在脚本里用 `window.__hyperframes.getVariables()` 读取
- 同一个子 composition 可以多次嵌入，每次不同参数
---
## GSAP 动画
HyperFrames 使用 GSAP 作为主要动画运行时。
### 关键要点
- Timeline 必须 `{ paused: true }`，框架控制播放
- 通过 position 参数（第3个参数）做绝对时间定位
- 只能做视觉属性动画，**不能**控制媒体播放
- 支持的方法：`to()`、`from()`、`fromTo()`、`set()`
- **Timeline 时长 = Composition 时长**（最长的动画决定总时长）
### 常见陷阱
- ❌ 在脚本里 play/pause/seek 媒体元素
- ❌ 创建非 paused 的 timeline
- ❌ 直接在 `<video>` 元素上动画 width/height（用 div 包装）
- ❌ 手动嵌套子 timeline
---
## 渲染配置
### 输出选项
| 参数 | 可选值 | 默认 |
|---|---|---|
| `--format` | mp4, mov, webm, png-sequence | mp4 |
| `--fps` | 24, 30, 60 | 30 |
| `--quality` | draft, standard, high | standard |
| `--workers` | 1-8 或 auto | auto |
| `--gpu` | NVENC, VideoToolbox, AMF, VAAPI, QSV | off |
| `--docker` | 确定性渲染 | off |
| `--hdr` / `--sdr` | HDR 输出控制 | off |
### 环境要求
- **Node.js 22+**
- **FFmpeg 7.x**
- Chrome（bundled）
- Docker（可选，生产渲染推荐）
---
## Agent 集成
这是 HyperFrames 的最大亮点。
### 为什么对 Agent 友好
1. LLM 天生擅长生成 HTML — 不需要学新 DSL
2. CLI 完全非交互，参数驱动，纯文本输出
3. 可以从文档、网页、GitHub 仓库等现成内容起步
4. 支持 Claude Code、Cursor、Gemini CLI、Codex 等 AI 编码 Agent
### Skills 安装
```bash
npx skills add heygen-com/hyperframes
```
安装后在 Claude Code 中注册为 slash commands：
- `/hyperframes` — composition 创作
- `/hyperframes-cli` — init, lint, preview, render
- `/hyperframes-media` — TTS、转录、背景移除
- `/tailwind` — Tailwind v4 样式
- `/gsap` — GSAP 时间线动画
- 以及 `/animejs`、`/css-animations`、`/lottie`、`/three`、`/waapi`
### 示例提示词
```
Using /hyperframes, create a 10-second product intro with a fade-in title over a dark background.
Summarize the attached PDF into a 45-second pitch video using /hyperframes.
Turn this CSV into an animated bar chart race using /hyperframes.
Make a 9:16 TikTok-style hook video about [topic] using /hyperframes.
```
---
## 使用场景
| 场景 | 描述 |
|---|---|
| **文档转视频** | onboarding、release note、帮助中心 → 解释型视频 |
| **网站转视频** | 产品页、发布文案 → demo、功能讲解 |
| **仓库转视频** | GitHub README、架构说明 → devrel walkthrough |
| **数据转视频** | CSV、看板、指标 → 动态图表叙事 |
| **产品 demo** | 从提示词或 HTML 生成产品演示视频 |
| **社交媒体内容** | YouTube、TikTok、短视频 |
---
## Catalog 组件库
50+ 开箱即用的 blocks 和 components：
- 字幕样式（caption-clip-wipe 等）
- 社交 overlay
- Shader 转场
- 数据可视化图表
- 电影化特效
安装方式：`npx hyperframes add <component-name>`
---
## 定价
### 开源引擎
- **免费**，本地渲染不限量
- Docker 渲染也不收费（用自己的基础设施）
### 托管 Studio（hyperframes.net）
| 套餐 | 价格 | 积分/月 | 备注 |
|---|---|---|---|
| 入门版 | $29/月（年付 $87） | 500 | 基础功能 |
| 标准版 | $99/月（年付 $297） | 2,000 | 优先队列 |
| 高级版 | $199/月（年付 $597） | 8,000 | 最快速度 |
| 试用 | 免费 | 30 积分 | 新用户 |
积分消耗：4秒视频 = 40积分，15秒视频 = 150积分
免费浏览器工具（视频转换、缩略图、GIF、图片压缩）不扣积分。
---
## Frame Adapters
HyperFrames 通过 Frame Adapter 模式支持多种动画运行时：
- **GSAP** — 主要推荐
- **Lottie** — 通过 `window.__hfLottie` 注册
- **CSS Animations** — 原生支持
- **Three.js** — 3D 场景
- **WAAPI** — Web Animations API
- **Anime.js** — 轻量动画库
只要运行时能 seek 到某一帧，就能通过适配器接入渲染链路。
---
## 竞品对比思考
| 维度 | HyperFrames | Remotion | After Effects |
|---|---|---|---|
| 视频定义方式 | HTML + data attributes | React + JS | 时间线 GUI |
| Agent 适配 | ⭐⭐⭐ 原生设计 | ⭐⭐ 需 React | ⭐ 无法自动化 |
| 确定性渲染 | ✅ | ✅ | ❌ |
| 学习曲线 | 低（会 HTML 就行） | 中（需 React） | 高 |
| 动画运行时 | GSAP/Lottie/CSS/任意 | CSS/React 状态 | 内置 |
| 渲染依赖 | Chrome + FFmpeg | Chrome + FFmpeg | Adobe |
| 开源 | ✅ MIT | ✅ MIT | ❌ |
---
## 评价
**优点：**
- 概念非常清晰 — HTML 即视频，零新 DSL 学习成本
- Agent 友好设计是杀手级特性，开箱即用的 skills 系统
- 确定性渲染让视频也能 CI/CD
- HeyGen 背书，项目活跃
- 50+ Catalog 组件开箱即用
**局限：**
- 适合结构化、信息展示类视频，不适合复杂真人特效
- 托管 Studio 定价偏贵（相比自建）
- 依赖 Chrome 逐帧捕获，渲染速度不如原生视频引擎
- 生态还比较新，社区资源有限
**适用人群：**
- 需要批量生成视频的开发者团队
- 想用 AI Agent 自动化视频生产的人
- DevRel、产品营销团队
- 数据可视化视频制作者
---
## 快速上手
```bash
# 1. 初始化项目
npx hyperframes init my-video
cd my-video
# 2. 浏览器预览
npx hyperframes preview
# 3. 渲染 MP4
npx hyperframes render --output output.mp4
# 4. 环境检查
npx hyperframes doctor
```
---
## 相关链接
- 官网：https://www.hyperframes.net/zh
- GitHub：https://github.com/heygen-com/hyperframes
- 文档：https://hyperframes.mintlify.app/introduction
- Catalog：https://hyperframes.mintlify.app/catalog
- 定价：https://www.hyperframes.net/zh/pricing
- 使命：https://www.hyperframes.net/zh/mission

160
AI工程/JetLinks物联网平台深度研究.md Executable file
View File

@@ -0,0 +1,160 @@
# JetLinks 物联网平台深度研究
> 研究日期：2026-06-12
> 来源：GitHub 官方仓库 + 官网
## 基本信息
| 项目 | 内容 |
|---|---|
| **GitHub** | https://github.com/jetlinks/jetlinks-community |
| **Stars** | 6.5k ⭐ |
| **Forks** | 1.9k |
| **当前版本** | 2.3（社区版）/ 2.11（分支） |
| **公司** | 重庆，深圳设研发中心 |
| **许可证** | Apache 2.0 |
| **官网** | https://www.jetlinks.cn |
| **文档** | 语雀托管 |
## 技术架构
### 核心技术栈
- **Java 8+**, Spring Boot 2.7.x
- **Spring WebFlux** — 全响应式 Web（非传统 Servlet）
- **R2DBC** — 响应式关系型数据库驱动
- **Reactor** — 响应式编程框架
- **Netty + Vert.x** — 高性能网络编程
- **PostgreSQL** — 业务数据存储
- **ElasticSearch / TDengine** — 时序数据存储
### 模块结构
```
jetlinks-community
├── jetlinks-components/ # 核心组件层
│ ├── network-component # 网络：MQTT/TCP/UDP/CoAP/HTTP
│ ├── protocol-component # 协议适配
│ ├── gateway-component # 消息网关/设备接入
│ ├── rule-engine-component # 规则引擎
│ ├── things-component # 物模型
│ ├── elasticsearch-component # ES 时序存储
│ ├── tdengine-component # TDengine 集成
│ └── notify-component # 通知（短信/邮件）
├── jetlinks-manager/ # 业务管理层
│ ├── authentication-manager # 用户/权限
│ ├── device-manager # 设备管理
│ ├── network-manager # 网络组件管理
│ ├── rule-engine-manager # 规则引擎管理
│ ├── visualization-manager # 数据可视化
│ └── notify-manager # 通知管理
└── simulator/ # 设备模拟器
```
## 核心能力
### 协议支持
| 协议 | 支持 | 水利适用 |
|---|---|---|
| MQTT | ✅ | ⭐⭐⭐⭐⭐ |
| TCP | ✅ | ⭐⭐⭐⭐ |
| UDP | ✅ | ⭐⭐⭐ |
| CoAP | ✅ | ⭐⭐⭐ |
| HTTP | ✅ | ⭐⭐⭐ |
| TLS/DTLS | ✅ | ⭐⭐⭐⭐ |
| Modbus | ⚠️ 需自研 | 需扩展 |
| SL651水文规约 | ❌ 无 | **核心缺口** |
### 物模型管理
- 产品(Product) → 物模型(ThingModel)
- 属性(Properties): 水位、流量、水温、电量
- 功能(Functions): 开闸、关闸、重启
- 事件(Events): 超水位告警、断电告警
- 设备(Device) → 绑定产品 → 继承物模型
- 支持设备影子（离线缓存指令）
### 规则引擎
- 支持多种规则模型（阈值告警、场景联动、自定义）
- **ReactorQL**：用 SQL 描述流式数据处理
- 告警 → 通知（短信/邮件/Webhook）
- 联动：水位超限 → 自动开闸
### 数据存储方案
- **PostgreSQL**：设备信息、用户权限、配置等业务数据
- **ElasticSearch**：属性时序数据、设备日志
- **TDengine**（可选）：高性能时序写入
## 部署
### Docker 一键部署
```bash
cd docker/run-all
docker-compose up -d
# 访问 http://localhost:9000
```
### 依赖组件
- PostgreSQL
- ElasticSearch（或 TDengine）
- Redis
- MQTT Broker（内置）
### 硬件要求
- 最低：2C4G（开发/测试）
- 生产：4C8G 起步，数据量大建议 8C16G
## 社区版 vs 企业版
| 功能 | 社区版 | 企业版 |
|---|---|---|
| 设备接入+管理 | ✅ | ✅ |
| 物模型 | ✅ | ✅ |
| 协议适配 | ✅ | ✅ |
| 规则引擎 | ✅ | ✅ 更强 |
| 数据可视化 | ✅ 基础 | ✅ 高级大屏 |
| 多租户 | ⚠️ 基础 | ✅ 完整 |
| AI 视觉 | ❌ | ✅ |
| 边缘网关 | ❌ | ✅ |
| 源码 | ✅ 全开放 | 需购买 |
## 水利场景评估
### 优势
1. Java 生态，水利行业 Java 开发者多
2. 响应式架构，高并发性能好
3. 协议扩展灵活，SL651 可自研接入
4. 中文文档完善（语雀 + QQ 群）
5. 模块化设计，按需裁剪
6. 国产项目，等保合规
### 注意事项
1. **SL651 需自研**：无现成实现
2. **响应式学习曲线**：WebFlux + Reactor 有门槛
3. **社区版文档滞后**
4. **GIS 能力弱**：需自己集成地图
5. **前端 Vue 版本较旧**
### 落地路径建议
1. Docker 部署社区版，跑通 MQTT demo
2. 开发 SL651 协议包
3. 对接 TDengine 做时序存储
4. 前端集成 GIS 地图（天地图/高德）
5. 开发水利业务大屏
预估：2-3 人团队，MVP 约 2-3 个月
## 竞品对比
| 维度 | JetLinks | ThingsBoard | 自研+TDengine |
|---|---|---|---|
| 语言 | Java | Java | 自选 |
| 学习成本 | 中 | 中 | 高 |
| 中文文档 | ⭐⭐⭐⭐⭐ | ⭐⭐ | 自己写 |
| 协议扩展 | 好 | 好 | 完全自由 |
| 二次开发 | 友好 | 一般 | 完全自由 |
| 部署复杂度 | 中 | 中 | 高 |
| 社区规模 | 中（国内） | 大（全球） | 无 |

311
AI工程/New_API_研究报告.md Executable file
View File

@@ -0,0 +1,311 @@
# New API 研究报告
**研究日期**: 2026-06-09
**项目**: QuantumNous/new-api
**Stars**: 37,729 ⭐
**语言**: Go
**最新版本**: v1.0.0-rc.10 (2026-05-26)
**官网**: https://www.newapi.ai
**文档**: https://docs.newapi.pro
---
## 📋 项目概述
**New API** 是下一代 LLM 网关和 AI 资产管理系统，是 One API 的增强版本。它将多个 AI 模型提供商统一转换为 OpenAI/Claude/Gemini 兼容格式，提供集中化的模型管理平台。
### 核心定位
- **AI API 网关**: 聚合多个 AI 提供商，统一接口
- **企业级管理**: 组织级鉴权、用量统计、成本核算
- **私有化部署**: 支持 Docker 一键部署
- **格式转换**: OpenAI ⇄ Claude ⇄ Gemini 互相转换
---
## 🚀 核心功能
### 1. 多协议支持
- ⚡ **OpenAI Responses API** (最新格式)
- ⚡ **OpenAI Realtime API** (包括 Azure)
- ⚡ **Claude Messages API**
- ⚡ **Google Gemini API**
- 🔄 **Rerank Models** (Cohere, Jina)
### 2. 智能路由
- ⚖️ 渠道加权随机
- 🔄 失败自动重试
- 🚦 用户级模型限流
- 💾 缓存命中统计 (OpenAI/Azure/DeepSeek/Claude/Qwen)
### 3. 格式转换
- OpenAI Compatible ⇄ Claude Messages
- OpenAI Compatible → Google Gemini
- Google Gemini → OpenAI Compatible (仅文本)
- 🔄 思考内容转换 (thinking-to-content)
### 4. 推理努力控制
**OpenAI 系列**:
- o3-mini-high/medium/low
- gpt-5-high/medium/low
**Claude 系列**:
- claude-3-7-sonnet-thinking
**Gemini 系列**:
- gemini-2.5-flash-thinking/nothinking
- gemini-2.5-pro-thinking
- 支持 -low/-medium/-high 后缀
### 5. 计费与配额
- ✅ 内部充值和配额分配 (EPay, Stripe)
- ✅ 按请求/用量/缓存命中率成本核算
- ✅ 灵活计费策略
- ✅ 企业客户管理
### 6. 权限管理
- 🔑 Token 分组
- 🔒 模型限制
- 👥 用户管理
- 🔐 多种登录方式 (Discord/LinuxDO/Telegram/OIDC)
---
## 📡 支持的渠道类型 (50+)
| 渠道类型 | 编号 | 默认 BASE_URL |
|---------|------|---------------|
| OpenAI | 1 | https://api.openai.com |
| Azure | 3 | - |
| Anthropic | 14 | https://api.anthropic.com |
| **阿里云 (Ali)** | **17** | **https://dashscope.aliyuncs.com** |
| 百度文心 | 15/46 | https://aip.baidubce.com |
| 智谱 | 16/26 | https://open.bigmodel.cn |
| Gemini | 24 | https://generativelanguage.googleapis.com |
| Moonshot | 25 | https://api.moonshot.cn |
| DeepSeek | 43 | - |
| 火山引擎 | 45 | - |
| OpenRouter | 20 | https://openrouter.ai/api |
| Cohere | 34 | https://api.cohere.ai |
| MiniMax | 35 | https://api.minimax.chat |
| Mistral | 42 | - |
| xAI | 48 | - |
| 更多... | - | - |
---
## 🔗 阿里云百炼对接
### 百炼 OpenAI 兼容接口
阿里云百炼的千问模型支持 OpenAI 兼容接口，只需调整 API Key、BASE_URL 和模型名称。
### 配置信息
**BASE_URL (SDK)**:
- 北京: `https://dashscope.aliyuncs.com/compatible-mode/v1`
- 弗吉尼亚: `https://dashscope-us.aliyuncs.com/compatible-mode/v1`
- 新加坡: `https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`
**HTTP Endpoint**:
- 北京: `POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`
### 支持的千问模型
**商业版**:
- **千问 Max**: qwen3.7-max, qwen3-max, qwen-max
- **千问 Plus**: qwen3.6-plus, qwen3.5-plus, qwen-plus
- **千问 Flash**: qwen3.6-flash, qwen3.5-flash, qwen-flash
- **千问 Coder**: qwen3-coder-plus, qwen3-coder-flash
- **QwQ**: qwq-plus
**开源版**:
- qwen3.6-35b-a3b, qwen3.5-397b-a17b, qwen3.5-122b-a10b
- qwen3-235b-a22b, qwen3-32b, qwen3-30b-a3b, qwen3-14b, qwen3-8b
### New API 对接百炼步骤
1. **部署 New API**
```bash
docker run -d --name new-api -p 3000:3000 \
-e TZ=Asia/Shanghai \
-v ./data:/data \
calciumion/new-api:latest
```
2. **添加阿里云渠道**
- 进入管理后台 → 渠道管理 → 添加渠道
- 选择 **阿里云 (Ali)** 类型 (Channel Type: 17)
- 填写 **百炼 API Key**
- BASE_URL 默认已填: `https://dashscope.aliyuncs.com`
- 选择要启用的模型
3. **创建 Token**
- 令牌管理 → 创建令牌
- 生成 API Key 供下游应用使用
4. **下游应用调用**
```python
from openai import OpenAI
client = OpenAI(
api_key=*** # New API 生成的 Token
base_url="http://localhost:3000/v1", # New API 地址
)
```
### 渠道额外设置
```json
{
"force_format": true, // 强制格式化为 OpenAI 格式
"thinking_to_content": true, // 将思考内容转为 <think> 标签
"proxy": "socks5://xxx" // 网络代理
}
```
---
## 🐳 部署方式
### Docker Compose（推荐）
```yaml
version: '3.4'
services:
new-api:
image: calciumion/new-api:latest
container_name: new-api
restart: always
ports:
- "3000:3000"
volumes:
- ./data:/data
- ./logs:/app/logs
environment:
- SQL_DSN=postgresql://root:123456@postgres:5432/new-api
- REDIS_CONN_STRING=redis://:123456@redis:6379
- TZ=Asia/Shanghai
depends_on:
- redis
- postgres
redis:
image: redis:latest
restart: always
command: ["redis-server", "--requirepass", "123456"]
postgres:
image: postgres:15
restart: always
environment:
POSTGRES_USER: root
POSTGRES_PASSWORD: 123456
POSTGRES_DB: new-api
volumes:
- pg_data:/var/lib/postgresql/data
```
### Docker 单容器（SQLite）
```bash
docker run --name new-api -d --restart always \
-p 3000:3000 \
-e TZ=Asia/Shanghai \
-v ./data:/data \
calciumion/new-api:latest
```
部署后访问: `http://localhost:3000`
---
## 📊 支持的接口
- Chat Interface (Chat Completions)
- Response Interface (Responses)
- Image Interface (Image)
- Audio Interface (Audio)
- Video Interface (Video)
- Embedding Interface (Embeddings)
- Rerank Interface (Rerank)
- Realtime Conversation (Realtime)
- Claude Chat
- Google Gemini Chat
---
## 🌍 多语言支持
- 简体中文
- 繁体中文
- English
- Français
- 日本語
---
## 🎨 UI 特性
- 现代化界面设计
- 数据看板（可视化控制台和统计分析）
- 主题定制（支持 Anthropic/Simple Large 预设）
- 响应式设计（移动端友好）
- 暗色模式
---
## 🔐 认证方式
- Discord 授权登录
- LinuxDO 授权登录
- Telegram 授权登录
- OIDC 统一认证
---
## 💡 使用场景
### 个人开发者
- 统一管理多个 AI 提供商的 API Key
- 跨平台模型切换
- 用量追踪
### 企业用户
- 组织级鉴权和权限管理
- 成本核算和计费系统
- 多租户管理
- 用量统计和分析
### API 转售
- 支持多租户
- 配额管理
- 计费系统 (EPay, Stripe)
- 缓存优化降低成本
---
## 🔗 相关资源
- **官方文档**: https://docs.newapi.pro
- **GitHub**: https://github.com/QuantumNous/new-api
- **Docker Hub**: https://hub.docker.com/r/calciumion/new-api
- **One API (原版)**: https://github.com/songquanpeng/one-api
- **百炼文档**: https://help.aliyun.com/zh/model-studio/
- **Key 工具**: https://github.com/Calcium-Ion/new-api-key-tool
---
## 📝 总结
**New API** 是一个功能强大的 AI API 网关，适合：
1. **个人开发者**: 统一管理多个 AI 提供商的 API Key
2. **企业用户**: 组织级鉴权、成本核算、用量统计
3. **API 转售**: 支持多租户、配额管理、计费系统
**百炼对接优势**:
- 原生支持阿里云渠道 (Channel Type 17)
- 百炼提供 OpenAI 兼容接口，迁移成本低
- 千问模型性价比高，适合各种场景
- 支持缓存统计，可降低成本
**推荐部署方式**: Docker Compose，包含 PostgreSQL + Redis，适合生产环境。

336
AI工程/R3与LingBot-Map_流式3D重建技术对比.md Executable file
View File

@@ -0,0 +1,336 @@
# R³ 与 LingBot-Map：流式3D重建技术深度对比
> 研究日期：2026-06-12
> 来源：GitHub README + arXiv 论文摘要
---
## 一、R³：3D Reconstruction via Relative Regression
### 基本信息
| 项目 | 信息 |
|------|------|
| 论文 | [arXiv:2605.26519](https://arxiv.org/abs/2605.26519) |
| GitHub | [KevinXu02/R3](https://github.com/KevinXu02/R3) ⭐ 188 |
| 作者 | Congrong Xu (西湖大学/密歇根大学), Huachen Gao, Xingyu Chen, Yuliang Xiu, Jun Gao (NVIDIA), Anpei Chen |
| 参数量 | **372M** |
| 发布时间 | 2026-05-26 |
| 许可 | 未明确（仅开放推理代码） |
| 项目主页 | https://kevinxu02.github.io/r3-site/ |
### 核心问题
传统前馈几何基础模型（如 DUSt3R、MASt3R）依赖**全局坐标系假设**：
- 网络必须在单一全局帧中回归所有相机位姿
- 长时间流式重建时，平移量随时间无界增长
- 必须维护任意时间原点，导致长上下文/流式场景性能下降
### 解决方案：相对回归（Relative Regression）
**核心思想**：不直接预测全局坐标，而是预测**置信度加权的成对相对位姿约束**，再在后处理中组装全局轨迹。
#### 架构设计
```
输入视频流 → Depth Anything 3 骨干 → 轻量级成对位姿 MLP → 置信度加权相对位姿 → 全局轨迹组装
```
**两个关键创新**：
1. **轻量级成对位姿 MLP**
- 基于 Depth Anything 3 (DA3) 骨干网络
- 无循环状态（no recurrent state）
- 无 TTT 模块（Test-Time Training）
- 无额外 Transformer
- 仅通过简单 MLP 预测相邻帧间的相对位姿
2. **单一学习置信度（Single Learned Confidence）**
- 每条边（edge）一个置信度值
- 解耦为旋转置信度 + 平移置信度
- 三重作用：
- **训练时**：加权损失函数
- **推理时**：指导位姿聚合（pose aggregation）
- **运行时**：管理关键帧库（keyframe-bank management）
#### 推理模式
| 模式 | 适用场景 | 说明 |
|------|---------|------|
| `test` | 快速测试 | 保留所有 KV 缓存，跳过回退/度量缩放 |
| `local` | 室内/小覆盖场景 | 默认检查点 r3，短片段局部一致性强 |
| `long` | 户外/长轨迹 | 使用 r3_long 检查点 |
| `strided` | 时间稀疏视频 | 跳帧处理 |
#### 检查点
| 名称 | 训练视图数 | 适用场景 | 特点 |
|------|-----------|---------|------|
| `r3` | 4–32 | 室内/小覆盖场景 | 论文报告结果，短片段局部一致性强 |
| `r3_long` | 32–100 | 户外/长轨迹 | 用于 `--mode long` 和 `--mode strided` |
### 性能指标
- **参数量**：372M（约 1B 级模型的 1/3）
- **推理速度**：20+ FPS
- **长序列能力**：数千帧（有界内存预算）
- **精度**：匹配或超越 SOTA 流式方法（位姿估计 + 密集重建）
### 技术栈依赖
- **Depth Anything 3**（字节跳动）：深度估计骨干
- **CUT3R**：3D 重建基础
- **STream3R**：流式 3D 重建
### 开源状态
- ✅ 推理代码
- ✅ 检查点（HuggingFace）
- ❌ 评估代码（TODO）
- ❌ 训练代码（TODO）
---
## 二、LingBot-Map：Geometric Context Transformer
### 基本信息
| 项目 | 信息 |
|------|------|
| 论文 | [arXiv:2604.14141](https://arxiv.org/abs/2604.14141) |
| GitHub | [Robbyant/lingbot-map](https://github.com/Robbyant/lingbot-map) ⭐ 7166 |
| 团队 | **蚂蚁灵波科技（Robbyant）** — 蚂蚁集团具身智能研究团队 |
| 作者 | Lin-Zhuo Chen, Jian Gao, Yihang Chen, Ka Leong Cheng, Yipengjing Sun, Liangxiao Hu, Nan Xue, Xing Zhu, Yujun Shen, Yao Yao, Yinghao Xu |
| 参数量 | **1B+**（基于模型体积 ~350MB+ 和描述推断） |
| 发布时间 | 2026-04-15 |
| 许可 | **Apache 2.0**（完整开源） |
| 项目主页 | https://technology.robbyant.com/lingbot-map |
### 核心定位
受 **SLAM（Simultaneous Localization and Mapping）** 原理启发的**前馈 3D 基础模型**，专为流式 3D 重建设计。
### 架构设计：几何上下文 Transformer（GCT）
**核心创新**：在单一注意力机制中统一三大功能，解决流式重建的三大挑战：
```
┌─────────────────────────────────────────────────────────┐
│ Geometric Context Transformer │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌──────────────────┐ ┌────────┐ │
│ │ Anchor Context │ │ Pose-Reference │ │Traject-│ │
│ │ (锚点上下文) │ │ Window │ │ ory │ │
│ │ │ │ (位姿参考窗口) │ │Memory │ │
│ │ • 坐标定位 │ │ • 密集几何线索 │ │ │ │
│ │ • 全局参考系 │ │ • 局部精细信息 │ │• 漂移 │ │
│ │ │ │ │ │ 校正 │ │
│ └─────────────────┘ └──────────────────┘ └────────┘ │
└─────────────────────────────────────────────────────────┘
```
#### 三大组件详解
| 组件 | 功能 | 解决的问题 | 技术实现 |
|------|------|-----------|---------|
| **Anchor Context**<br>（锚点上下文） | 坐标定位 | 为重建提供全局参考系，避免坐标系漂移 | 在注意力机制中引入锚点 token，作为空间参考基准 |
| **Pose-Reference Window**<br>（位姿参考窗口） | 密集几何线索 | 提供精细的局部几何信息，支持高精度重建 | 滑动窗口机制，维护局部帧间几何一致性 |
| **Trajectory Memory**<br>（轨迹记忆） | 长程漂移校正 | 防止长时间累积误差导致的全局不一致 | 显式记忆模块，存储历史轨迹信息用于回环检测 |
#### 推理优化
- **分页 KV 缓存注意力**（Paged KV Cache Attention）
- 基于 **FlashInfer** 实现
- 支持高效流式推理
- 内存占用可控
- **关键帧策略**（Keyframe Interval）
- 每 N 帧保留一个关键帧到 KV 缓存
- 非关键帧仍产生预测但不存储
- 解决超过 320 帧后性能下降问题（训练时 RoPE 在 320 视图上训练）
- **窗口化推理**（Windowed Inference）
- 适用于 >3000 帧的长序列
- 滑动窗口 + 重叠关键帧
- 每个窗口重置 KV 缓存
### 检查点
| 名称 | 说明 | 适用场景 |
|------|------|---------|
| `lingbot-map-long` | 长序列优化版 | 长序列 + 大场景（**推荐**） |
| `lingbot-map` | 均衡版 | 短长序列均衡 |
| `lingbot-map-stage1` | Stage-1 训练权重 | 支持双向推理（c2w） |
### 性能指标
- **参数量**：1B+
- **推理速度**：~20 FPS（518×378 分辨率）
- **长序列能力**：**10,000+ 帧**（实测 25,000 帧 / 13 分钟室内漫游）
- **精度**：多个 benchmark 达到 SOTA（超越流式和迭代优化方法）
### 技术栈依赖
- **VGGT**（Meta）：视觉几何基础模型
- **DINOv2**（Meta）：视觉特征提取
- **FlashInfer**：分页 KV 缓存注意力加速
- **NVIDIA Kaolin**：批量渲染管线（可选）
### 开源状态
- ✅ 完整代码（Apache 2.0）
- ✅ 检查点（HuggingFace + ModelScope）
- ✅ 评估脚本（KITTI、Oxford Spires 等）
- ✅ Demo 脚本（交互式 + 离线渲染）
- ✅ 长视频示例（25,000 帧室内漫游）
---
## 三、深度对比分析
### 3.1 架构对比
| 维度 | R³ | LingBot-Map |
|------|-----|-------------|
| **核心思想** | 相对回归（避免全局坐标） | 几何上下文 Transformer（统一三大功能） |
| **骨干网络** | Depth Anything 3 | VGGT + DINOv2 |
| **位姿预测** | 成对相对位姿 MLP | 注意力机制直接预测 |
| **长序列处理** | 置信度引导的关键帧管理 | 轨迹记忆 + 窗口化推理 |
| **复杂度** | 轻量（无额外 Transformer） | 重（GCT 架构） |
### 3.2 性能对比
| 指标 | R³ | LingBot-Map |
|------|-----|-------------|
| 参数量 | **372M**（轻量） | 1B+（重） |
| 推理速度 | 20+ FPS | ~20 FPS |
| 长序列上限 | 数千帧 | **10,000+ 帧** |
| 内存控制 | 有界内存预算 | 分页 KV 缓存 + 关键帧策略 |
| 漂移控制 | 置信度加权聚合 | 显式轨迹记忆 |
### 3.3 工程成熟度对比
| 维度 | R³ | LingBot-Map |
|------|-----|-------------|
| 代码开放 | 仅推理 | **完整开源** |
| 训练代码 | ❌ 未开放 | ✅ 未明确（但完整可用） |
| 评估脚本 | ❌ TODO | ✅ 完整（多数据集） |
| 文档完善度 | 基础 | **详尽**（含长视频示例、渲染管线） |
| 社区热度 | 188 stars | **7166 stars** |
| 许可证 | 未明确 | **Apache 2.0** |
### 3.4 适用场景对比
| 场景 | R³ | LingBot-Map |
|------|-----|-------------|
| **手机/消费级设备实时重建** | ✅ 首选 | ⚠️ 可能过重 |
| **短中长度视频（几百帧）** | ✅ 适合 | ✅ 适合 |
| **长视频建图（数千帧）** | ⚠️ 有上限 | ✅ 首选 |
| **机器人导航** | ⚠️ 无漂移校正 | ✅ 首选（轨迹记忆） |
| **自动驾驶** | ⚠️ 无长期稳定性 | ✅ 首选 |
| **快速原型验证** | ✅ 即插即用 | ⚠️ 配置复杂 |
| **学术研究/复现** | ⚠️ 训练代码缺失 | ✅ 完整 |
### 3.5 技术选型决策树
```
需要 3D 重建？
├─ 视频长度 < 1000 帧？
│ ├─ 是 → 需要轻量部署？
│ │ ├─ 是 → R³
│ │ └─ 否 → LingBot-Map（精度更高）
│ └─ 否 → 视频长度 > 3000 帧？
│ ├─ 是 → LingBot-Map（万帧级稳定性）
│ └─ 否 → 需要长期空间记忆？
│ ├─ 是（机器人/自动驾驶） → LingBot-Map
│ └─ 否 → R³（快速部署）
```
---
## 四、技术背景：Feed-forward 3D Foundation Model 赛道
### 4.1 技术演进
```
传统 NeRF/3DGS → Feed-forward 模型
（每场景优化，慢） （一次前向，快）
↓ ↓
per-scene optimization depth + pose + pointcloud
需要 COLMAP 等 SfM 无需 SfM，端到端
分钟级/场景 秒级/场景
```
### 4.2 上游技术谱系
**R³ 谱系**：
```
Depth Anything 3 (字节) → CUT3R → STream3R → R³
```
**LingBot-Map 谱系**：
```
DINOv2 (Meta) → VGGT (Meta) → LingBot-Map
```
### 4.3 相关竞品
| 项目 | 机构 | 特点 |
|------|------|------|
| DUSt3R | Naver | 早期前馈 3D 重建 |
| MASt3R | Naver | DUSt3R 改进版 |
| CUT3R | - | 流式 3D 重建 |
| STream3R | - | 流式 3D 重建 |
| **R³** | 西湖大学/密歇根 | 相对回归，轻量 |
| **LingBot-Map** | 蚂蚁灵波 | GCT，万帧级 |
---
## 五、总结与建议
### 5.1 核心差异一句话
- **R³**：用"相对回归"绕过全局坐标问题，轻量但功能有限
- **LingBot-Map**：用"几何上下文 Transformer"统一解决三大问题，重但完整
### 5.2 技术成熟度
- **R³**：学术原型阶段，训练代码未开放，复现困难
- **LingBot-Map**：工程成熟阶段，完整开源，可直接用于生产
### 5.3 选型建议
| 你的需求 | 推荐方案 |
|---------|---------|
| 手机 App 实时 3D 扫描 | R³ |
| 快速验证 3D 重建 idea | R³ |
| 机器人 SLAM 替代方案 | LingBot-Map |
| 长视频建图（>3000 帧） | LingBot-Map |
| 学术研究/论文复现 | LingBot-Map（完整代码） |
| 生产环境部署 | LingBot-Map（Apache 2.0） |
### 5.4 未来展望
- **R³**：等待训练代码开放，可能成为轻量级 3D 重建标准
- **LingBot-Map**：蚂蚁灵波科技持续投入，可能成为具身智能空间感知标准组件
---
## 六、参考链接
### R³
- 论文：https://arxiv.org/abs/2605.26519
- 代码：https://github.com/KevinXu02/R3
- 检查点：https://huggingface.co/KevinXu02/R3
- 项目主页：https://kevinxu02.github.io/r3-site/
### LingBot-Map
- 论文：https://arxiv.org/abs/2604.14141
- 代码：https://github.com/Robbyant/lingbot-map
- 检查点：https://huggingface.co/robbyant/lingbot-map
- 项目主页：https://technology.robbyant.com/lingbot-map
- Demo 数据集：https://huggingface.co/datasets/robbyant/lingbot-map-demo
---
*来源：GitHub README + arXiv 摘要 + 项目主页，2026-06-12*

150
AI工程/Trellis_AI编码工程化框架.md Executable file
View File

@@ -0,0 +1,150 @@
# Trellis - AI 编码工程化框架
> **GitHub**: https://github.com/mindfold-ai/Trellis
> **官网/文档**: https://docs.trytrellis.app/zh
> **npm**: `@mindfoldhq/trellis`
> **License**: AGPL-3.0
> **开发商**: Mindfold (mindfold-ai)
> **研究日期**: 2026-06-06
---
## 一句话总结
Trellis 是一个**开箱即用的 AI 编码工程化框架**，核心解决的问题是：**AI 编码 Agent 每次会话从零开始，记不住项目规范和团队标准**。它将规范、任务、记忆沉淀进代码仓库，让任何 Coding Agent 都按你的工程标准执行。
## 核心痛点
AI 编码工具（Cursor、Claude Code、Codex 等）虽然能快速生成代码，但存在以下问题：
1. **无记忆** — 每次新会话从零开始理解项目
2. **无规范持久化** — `CLAUDE.md`、`.cursorrules` 等文件容易膨胀变臃肿
3. **无任务结构化** — PRD、实现上下文、审查记录散落各处
4. **无跨平台统一** — 每个工具都要单独配置工作流
## 核心能力
| 能力 | 说明 |
|------|------|
| **自动注入规范** | 规范写在 `.trellis/spec/`，Trellis 按当前任务自动注入相关上下文 |
| **任务驱动工作流** | PRD、实现上下文、审查上下文统一在 `.trellis/tasks/` 管理 |
| **项目记忆** | `.trellis/workspace/` 中的 journal 保留上次会话脉络 |
| **团队共享标准** | Spec 随仓库版本化，个人规则可成为团队基础设施 |
| **多平台复用** | 一套结构覆盖 **14 个 AI Coding 平台** |
## 工作原理（4阶段循环）
```
Plan → Implement → Verify → Finish → (循环)
```
### 1. Plan（规划）
- `trellis-brainstorm` 逐题梳理需求 → 写入 `prd.md`
- 资料调研派发给 `trellis-research` 子代理
- 产出：精选 Spec + 研究文件，由 `implement.jsonl` / `check.jsonl` 编排
### 2. Implement（实现）
- `trellis-implement` 子代理依据 PRD 编写代码
- 上下文按 `implement.jsonl` 自动注入
- **不会执行 git commit**
### 3. Verify（验证）
- `trellis-check` 子代理基于 diff 对照 Spec 逐项核查
- 运行 lint、type-check、测试
- 自动修复能力范围内的问题
### 4. Finish（收尾）
- 最终检查
- `trellis-update-spec` 将新增认知沉淀回 `.trellis/spec/`
- 归档任务，更新 journal
## 目录结构
```
.trellis/
├── spec/ # 项目规范（自动注入到 Agent 上下文）
├── tasks/ # 任务 PRD、实现/审查上下文、状态
├── workspace/ # 工作日志（journal），会话间记忆
└── ... # 各平台适配文件（自动生成）
```
## 支持平台（14个）
仓库中包含以下平台的配置目录：
- `.claude/` — Claude Code
- `.cursor/` — Cursor
- `.codex/` — OpenAI Codex
- `.opencode/` — OpenCode
- `.pi/` — Pi
- `.agents/` — 通用 Agent Skills
- `.husky/` — Git Hooks 集成
- 其他更多...
## 快速开始
```bash
# 安装
npm install -g @mindfoldhq/trellis@latest
# 在项目中初始化
trellis init -u your-name
# 指定平台初始化
trellis init --cursor --opencode --codex -u your-name
```
**前置要求**：Node.js >= 18, Python >= 3.9
## 使用流程
1. 用自然语言描述需求
2. AI 逐题头脑风暴 → 澄清 PRD
3. AI 自主调用 `trellis-implement` 编码 + 自动校验
4. 完成时输入 `/trellis:finish-work`，归档任务、更新记忆
## 与 CLAUDE.md / AGENTS.md / .cursorrules 的区别
这些文件是有用的入口，但容易膨胀。Trellis 在此之上补充了：
- **作用域明确的 Spec**（不是一个大文件）
- **按任务划分的 PRD**
- **工作流关卡**（Plan→Implement→Verify→Finish）
- **工作区记忆**（跨会话）
- **多平台自动适配文件**
## 适用场景
- **个人开发者**：记忆机制 + 可复用工作流，不用每次重复说明
- **团队**：标准统一、任务边界清晰、上下文可审查、跨平台可移植
- **多工具用户**：同一套 Trellis 结构在 Cursor/Claude Code/Codex 间复用
## 评价
### ✅ 优点
- 解决了 AI 编码的核心痛点（记忆 + 规范持久化）
- 多平台支持是一大亮点，不用为每个工具单独配置
- 4阶段循环（Plan→Implement→Verify→Finish）是成熟的工程化思路
- 规范随仓库版本化，团队协作友好
- 开源 AGPL-3.0，可自托管
### ⚠️ 注意
- AGPL-3.0 许可证，商业使用需注意传染性
- 需要团队统一采用，否则收益有限
- 增加 `.trellis/` 目录到仓库，有一定侵入性
### 📊 项目热度
- GitHub Stars：持续增长中
- 有微信群 + 飞书群，国内社区活跃
- npm 周下载量可见
## 相关链接
- [官方文档](https://docs.trytrellis.app/zh)
- [快速开始](https://docs.trytrellis.app/zh/start/install-and-first-task)
- [支持平台](https://docs.trytrellis.app/zh/advanced/multi-platform)
- [真实场景](https://docs.trytrellis.app/zh/start/real-world-scenarios)
- [Spec 模板](https://docs.trytrellis.app/zh/templates/specs-index)
- [Discord](https://discord.com/invite/tWcCZ3aRHc)
- [DeepWiki](https://deepwiki.com/mindfold-ai/Trellis)
---
*研究归档：2026-06-06 | 路径：/obsidian/AI工程/Trellis_AI编码工程化框架.md*

522
AI工程/团队级AI_Coding简明手册_逐页研究/00_概述与前言.md Executable file
View File

@@ -0,0 +1,522 @@
# 团队级 AI Coding 简明手册 - 逐页详细研究
> 原文：系统设计研讨会分享 PPT v0.2（2026年6月18日）
> 研究日期：2026-06-20
> 研究目标：逐页深入分析，补充背景知识、工具推荐、实践建议
---
## 第1页：封面
### 原文内容
- 标题：团队级 AI Coding 简明手册 v0.2
- 日期：2026年6月18日
- 来源：系统设计研讨会分享
- 版权声明：版权归分享人所有
### 研究要点
- 这是 v0.2 版本，说明经过了迭代完善
- "团队级"强调这不是个人技巧，而是组织层面的工程实践
- "简明手册"定位：实用导向，非学术理论
---
## 第2页：AI 编程思想发展过程
### 原文内容
AI 编程经历5个阶段演进：
| 阶段 | 特征 | 自动化程度 |
|------|------|------------|
| **原始阶段** | 基于本能，手动复制代码或通过问答交互 | 半自动，有人值守 |
| **Rule 约束** | 经验规则显化，如 RIPER-5 定义工作模式 | 半自动，持续对话 |
| **规格驱动** | 需求结构化表达，如 OpenSpec 框架 | 过渡阶段 |
| **Loop Engineering** | 可反馈闭环，AI 根据验收规则自动循环 | 接近全自动 |
| **Harness 驾驭工程** | 纳入工程治理体系，提供约束+外部接口 | 全自动，Plan 后无人值守 |
### 深入解读
**1. 原始阶段**
- **现状**：大多数开发者仍在这个阶段
- **典型场景**：复制 ChatGPT 生成的代码到 IDE，手动调整
- **问题**：上下文断裂，每次对话都要重新解释背景
- **工具**：ChatGPT 网页版、早期 Copilot
**2. Rule 约束阶段**
- **RIPER-5 模式**（Research-Investigate-Plan-Execute-Review）：
- 由 AI 编程社区提出的结构化工作流
- 将复杂任务分解为5个明确阶段
- 每个阶段有不同的提示词策略
- **其他 Rule 框架**：
- Cursor Rules：在 `.cursor/rules` 定义项目规范
- Claude Code 的 `CLAUDE.md`：项目级指令
- OpenCode 的 `.opencode/config.json`
**3. 规格驱动阶段**
- **OpenSpec 框架**：
- 将需求写成结构化的 Spec 文件
- AI 读取 Spec 生成代码，文件进文件出
- Spec 可以作为版本控制的产物
- **优势**：需求可追溯，AI 行为可预测
**4. Loop Engineering**
- **核心理念**：AI 不是执行一次就结束，而是进入循环
- **循环机制**：
- 定义验收标准（测试用例）
- AI 执行 → 运行测试 → 失败则修复 → 再次运行
- 直到所有测试通过才退出循环
- **代表工具**：Claude Code 的 `/loop` 命令
**5. Harness 驾驭工程**
- **概念来源**：OpenAI、Anthropic 等公司提出的工程理念
- **Harness（驾驭工具）**：
- 为 AI 提供约束体系（Rules、Specs）
- 为 AI 提供外部接口（MCP、Skills、CLI）
- 让 AI 在受控环境中自主工作
- **关键特征**：
- Plan 阶段人机协作
- 执行阶段无人值守
- 可审计、可回溯
### 实践建议
- **评估你所在团队的位置**：大多数团队在阶段1-2之间
- **渐进式升级**：不要跳级，先建立 Rule，再引入 Spec
- **关键指标**：AI 代码采纳率、人均代码产出、缺陷率
### 相关资源
- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
- [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
- [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
---
## 第3页：四大核心问题
### 原文内容
团队级 AI Coding 面临4个核心问题：
1. **需求衔接**：如何用 AI 整理需求？
2. **开发实现**：如何获得高质量的代码？
3. **测试验收**：如何根据规格自动化测试？
4. **Agent as Code**：如何组织协作文件，构建 AI 友好环境？
### 深入解读
**问题1：需求衔接**
- **痛点**：AI 无法理解模糊需求，需要结构化输入
- **关键问题**：
- 格式：Markdown vs YAML vs JSON
- 组织：按功能模块 vs 按用户故事
- 原型图传递：Figma 链接 vs HTML 原型
- 模版设计：新建需求 vs 变更需求
- **解决方案**：使用 `docs/features/` 目录管理需求规格
**问题2：开发实现**
- **痛点**：AI 生成的代码质量不稳定，缺乏上下文
- **关键问题**：
- 上下文管理：如何让 AI 理解项目结构
- 外部工具：如何调用数据库、API、文件系统
- 代码一致性：如何保证风格统一
- 多任务并发：如何同时开发多个功能
- 调试能力：如何让 AI 自主排查问题
- **解决方案**：
- AGENTS.md 定义项目约束
- MCP 协议接入外部工具
- 打样工程提供代码模版
**问题3：测试验收**
- **痛点**：AI 生成的代码缺乏测试，难以验证
- **关键问题**：
- 测试策略：单元测试 vs 集成测试 vs E2E 测试
- 浏览器操作：如何让 AI 操作浏览器进行 E2E 测试
- 测试用例管理：如何组织、版本控制
- **解决方案**：
- TDD 驱动：先写测试再写代码
- Playwright MCP：AI 操作浏览器
- 测试用例生成：Browser Use 探索 → Playwright 固化
**问题4：Agent as Code**
- **痛点**：AI 协作文件散乱，缺乏组织
- **关键问题**：
- 文件结构：如何组织 docs、skills、mcp 等目录
- 工具支持：如何让 Claude、Cursor、OpenCode 都识别
- 版本控制：如何将 AI 配置纳入 Git 管理
- **解决方案**：
- AGENTS.md 作为宪法级文件
- 软链接到各工具的配置文件
- 统一目录结构：`docs/`, `skills/`, `mcp/`
### 实践建议
- **优先级排序**：先解决问题4（Agent as Code），建立基础
- **逐步引入**：需求衔接 → 开发实现 → 测试验收
- **度量指标**：AI 代码采纳率、测试覆盖率、缺陷逃逸率
---
## 第4页：AI 赋能软件开发实现地图
### 原文内容
完整的软件开发生命周期中，人与 AI 的分工：
```
需求分析 → 需求文档/原型图 → 技术方案 → 代码框架+打样
↓ ↓ ↓ ↓
人+AI 人+AI 人+AI 人+AI
↓ ↓ ↓ ↓
AI代码编写 → 单元/API测试 → E2E测试 → Code Review → 提测部署
↓ ↓ ↓ ↓ ↓
机 机+人 机+人 机+人 机+人
```
**核心 Loop**：研发自测阶段（AI 自治运行）
**全流程超级 Loop**：从需求到部署（人机协作）
### 深入解读
**阶段1：需求分析（人+AI）**
- **人的角色**：用户访谈、竞品分析、业务理解
- **AI 的角色**：整理访谈记录、生成用户故事、绘制流程图
- **工具推荐**：
- ChatGPT/Claude：整理访谈笔记
- Miro AI：自动生成流程图
- Whimsical AI：生成用户旅程图
**阶段2：需求文档+原型图（人+AI）**
- **人的角色**：定义业务规则、审核原型
- **AI 的角色**：生成需求文档草稿、生成 HTML 原型
- **工具推荐**：
- Cursor/Claude Code：生成 Markdown 需求文档
- v0.dev：生成 React 原型
- Galileo AI：生成 UI 设计稿
**阶段3：技术方案（人+AI）**
- **人的角色**：架构决策、技术选型
- **AI 的角色**：生成技术规格文档、绘制架构图
- **工具推荐**：
- PlantUML + AI：生成领域模型、时序图
- Claude Code：生成 API 设计文档
**阶段4：代码框架+打样（人+AI）**
- **人的角色**：定义目录结构、编写核心接口
- **AI 的角色**：生成 CRUD 代码、填充模版
- **工具推荐**：
- Claude Code + 打样工程：生成符合项目规范的代码
- Cursor Composer：批量生成代码
**阶段5：AI 代码编写（机）**
- **AI 的角色**：根据 Spec 自动生成代码
- **人的角色**：审核关键逻辑
- **工具推荐**：
- Claude Code Loop 模式：自动循环直到测试通过
- OpenCode：根据 OpenSpec 生成代码
**阶段6：单元/API 测试（机+人）**
- **AI 的角色**：生成测试代码、运行测试
- **人的角色**：审核测试用例、补充边界条件
- **工具推荐**：
- Jest + AI：生成单元测试
- Karate：生成 API 测试
**阶段7：E2E 测试（机+人）**
- **AI 的角色**：操作浏览器、生成测试脚本
- **人的角色**：定义关键路径、审核测试
- **工具推荐**：
- Playwright MCP：AI 操作浏览器
- Browser Use：探索式测试生成
**阶段8：Code Review（机+人）**
- **AI 的角色**：自动审查代码、发现问题
- **人的角色**：审核 AI 的审查结果
- **工具推荐**：
- GitHub Copilot Code Review
- Claude Code：PR Review
- CodeRabbit：AI 代码审查
**阶段9：提测部署（机+人）**
- **AI 的角色**：生成部署脚本、执行部署
- **人的角色**：审核部署配置、处理异常
- **工具推荐**：
- GitHub Actions + AI：自动生成 CI/CD
- Vercel/Netlify：一键部署
### 实践建议
- **从核心 Loop 开始**：先在研发自测阶段引入 AI
- **逐步扩展到超级 Loop**：覆盖需求、测试、部署
- **关键指标**：AI 参与率、自动化程度、交付周期
---
## 第5页：AI 赋能软件开发工具体系
### 原文内容
展示了各阶段使用的工具和产出物：
| 阶段 | 工具 | 产出 |
|------|------|------|
| 原型图 | Stitch/Figma/HTML | Design.md |
| 需求规格 | AI IDE + 模版 | Markdown |
| 技术规格 | AI IDE + 模版 | Markdown |
| 代码编写 | AI IDE + 规范 | TS/Java |
| 测试规格 | AI IDE + 模版 | Markdown |
| E2E 测试 | Playwright MCP | TS 代码 |
| Bug 修复 | AI IDE + 模版 | 代码修复 |
| 部署 | AI IDE + Yaml | 环境部署 |
### 深入解读
**工具链核心：AI IDE**
- **定义**：集成 AI 能力的开发环境
- **代表工具**：
- **Cursor**：基于 VS Code，AI 优先设计
- **Claude Code**：命令行 AI 编程工具
- **OpenCode**：开源的 AI 编程终端
- **Kiro**：AWS 推出的 AI IDE
- **Trae**：字节跳动推出的 AI IDE
**模版体系**
- **需求规格模版**：定义需求文档结构
- **技术规格模版**：定义技术设计文档结构
- **测试规格模版**：定义测试用例结构
- **代码模版**：定义代码风格、目录结构
**关键工具详解**
1. **Design.md**
- 作用：约束 AI 生成的前端风格
- 内容：颜色、字体、间距、组件库
- 来源：从设计稿提炼或从现有代码反推
2. **Playwright MCP**
- 作用：让 AI 操作浏览器
- 场景：E2E 测试、UI 调试
- 优势：标准化接口，支持 Accessibility Tree
3. **MCP（Model Context Protocol）**
- 作用：AI 与外部系统通信的标准协议
- 场景：数据库、API、文件系统接入
- 优势：标准化、双向通信、即插即用
### 实践建议
- **建立模版库**：将常用的文档结构模版化
- **统一工具链**：团队使用相同的 AI IDE
- **维护 Design.md**：确保 AI 生成的 UI 风格一致
---
## 第6页：分隔页（01 需求衔接）
### 原文内容
章节分隔页，标志进入"需求衔接"部分
### 研究要点
- 这是第4个核心问题的展开
- 需求衔接是整个开发流程的起点
- 良好的需求衔接能大幅提升 AI 代码质量
---
## 第7页：需求规格编写
### 原文内容
**AI 能理解的需求格式**：Markdown/Excel 表格
**关键要素**：
1. **模块切分**（增量/存量）
2. **字段清单**
3. **原型链接**
4. **业务规则**
**编写原则**：
- 先写业务背景，再切模块
- 一个模块 = 一个文档
- 分解为增量需求和存量需求：
- **增量需求**：全新功能，需新建模块
- **存量修改**：对已有功能做变更
- Tips：增量建模块，存量标改动
**字段清单示例**：
```markdown
| 字段名 | 类型 | 必填 | 默认值 | 描述 |
|-----------|---------|------|--------|--------------|
| username | string | 是 | — | 登录用户名 |
| email | string | 是 | — | 电子邮箱 |
| role | enum | 否 | user | 用户角色 |
| status | boolean | 否 | true | 是否启用 |
```
**字段定义要求**：
- 定义完整字段
- 标注校验规则
- 标注 UI 展示
- 标注数据来源
**原型图传递**：
- Figma：选中 Frame → Share → Copy link
- Stitch：选中设计稿 → 获取分享链接
- HTML 版本：用 HTML/CSS 做可交互原型，提交到代码仓库
**业务规则示例**：
```markdown
R1 用户名唯一不可重复
R2 邮箱格式正则校验
R3 密码 ≥ 8 位含大小写
R4 删除需二次确认
R5 超时自动登出
R6 管理员不可降级
```
**编写原则**：
- 条目化 + 正交分解
- 每条规则独立可测
**重要 Tip**：BA 也应该工作在代码仓库中，让 AI 基于当前系统事实构建新需求
### 深入解读
**为什么用 Markdown？**
- **版本控制友好**：可以纳入 Git 管理
- **AI 友好**：LLM 对 Markdown 理解能力强
- **可读性好**：人和 AI 都能轻松阅读
- **工具支持**：所有 AI IDE 都支持
**为什么区分增量/存量？**
- **增量需求**：AI 从零生成，需要完整上下文
- **存量修改**：AI 需要理解现有代码，才能安全修改
- **影响 AI 策略**：增量可以用生成式 AI，存量需要理解现有代码
**字段清单的价值**
- **明确数据模型**：AI 可以根据字段生成数据库表、API 接口
- **减少歧义**：类型、必填、默认值都明确定义
- **自动生成代码**：可以根据字段清单生成前端表单、后端 DTO
**业务规则条目化**
- **独立可测**：每条规则可以单独写测试用例
- **正交分解**：规则之间不重叠、不冲突
- **可追溯**：每条规则可以追溯到代码实现
**BA 在代码仓库中工作**
- **优势**：
- BA 可以看到现有需求、代码结构
- AI 可以基于现有需求生成新需求
- 需求变更可以追溯历史
- **实践**：
- BA 使用 Git 管理需求文档
- 需求变更通过 PR 审核
- AI 参与需求文档的生成和审核
### 实践建议
- **建立需求模版**：统一需求文档结构
- **使用字段清单**：明确数据模型
- **业务规则条目化**：方便测试和追溯
- **BA 使用 Git**：将需求管理纳入版本控制
### 工具推荐
- **需求管理**：Git + Markdown
- **原型设计**：Figma、Stitch、HTML
- **字段清单**：Excel、Markdown 表格
- **业务规则**：Markdown 列表
---
## 第8页：原型图设计
### 原文内容
**原型图设计的3种方式**：
**1. AI 设计软件输出**
- 在设计工具中完成原型，通过 URL 链接嵌入需求文档
- 标注映射：在需求中注明对应模块和页面
- **Figma**：选中 Frame → Share → Copy link
- **Stitch**：选中设计稿 → 获取分享链接
**2. HTML + CSS 输出**
- 用 HTML/CSS 做可交互原型，提交到代码仓库
- **优势**：
- 真实代码：直接使用项目组件库拼装
- 可交互：点击、跳转、表单输入均可演示
- 版本管理：随代码仓库一起管理和 Review
**3. Design.md 生成统一的视觉风格**
- **Design.md**：用 Markdown 约束 AI 生成的前端风格，确保输出与项目组件库一致
- **两种产生方式**：
- 从设计稿提炼规则
- 从现有代码反推样式
**Design.md 示例**：
```markdown
# Design System
## Colors
- primary: #1a1a1a
- background: #ffffff
- text: #333333
## Typography
- font: -apple-system, sans-serif
- h1: 1.5rem / 700
- body: 0.875rem / 400
## Spacing
- unit: 8px (base)
```
**参考资源**：https://getdesign.md
### 深入解读
**为什么需要原型图？**
- **减少歧义**：文字描述容易产生误解，原型图直观展示
- **AI 理解**：AI 可以通过原型图理解 UI 结构
- **用户确认**：用户可以提前看到效果，减少返工
**Figma vs Stitch vs HTML**
| 维度 | Figma | Stitch | HTML |
|------|-------|--------|------|
| **学习成本** | 中 | 低 | 高 |
| **AI 友好度** | 中 | 高 | 极高 |
| **版本控制** | 差 | 中 | 极好 |
| **交互能力** | 中 | 中 | 极强 |
| **协作能力** | 极强 | 强 | 中 |
**Figma**
- **优势**：设计师常用，生态丰富
- **劣势**：AI 无法直接读取 Figma 文件，需要通过链接
- **适用场景**：专业设计师参与的项目
**Stitch**
- **优势**：AI 友好，可以直接生成设计稿
- **劣势**：生态较小
- **适用场景**：AI 优先的项目
**HTML**
- **优势**：AI 可以直接生成，版本控制友好
- **劣势**：需要前端开发能力
- **适用场景**：技术团队主导的项目
**Design.md 的价值**
- **统一风格**：确保 AI 生成的 UI 风格一致
- **可维护**：Markdown 格式，易于修改和版本控制
- **可复用**：可以在多个项目中复用
**Design.md 的内容**
- **Colors**：主色、背景色、文字色
- **Typography**：字体、字号、字重
- **Spacing**：间距、边距
- **Components**：按钮、表单、卡片等组件样式
- **Layout**：布局规则
### 实践建议
- **选择适合的原型工具**：根据团队能力选择 Figma/Stitch/HTML
- **维护 Design.md**：确保 AI 生成的 UI 风格一致
- **原型与代码同步**：原型变更时同步更新代码
- **使用 getdesign.md**：参考现成的 Design.md 模版
### 工具推荐
- **设计工具**：Figma、Stitch
- **原型工具**：HTML/CSS、v0.dev
- **Design.md 生成**：从设计稿提炼、从代码反推
---
（由于篇幅较长，我将继续为剩余页面创建详细研究文档。需要我继续吗？）

354
AI工程/团队级AI_Coding简明手册_逐页研究/00_索引.md Executable file
View File

@@ -0,0 +1,354 @@
# 团队级 AI Coding 简明手册 v0.2 - 逐页研究索引
> 原文：系统设计研讨会分享 PPT（2026年6月18日）
> 研究日期：2026-06-20
> 研究范围：第1-30页（全文）
> 归档位置：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/
---
## 文档结构
### 00_概述与前言.md
**覆盖页码**：第1-8页
**核心内容**：
- 第1页：封面信息
- 第2页：AI 编程思想发展过程（5个阶段）
- 第3页：四大核心问题概述
- 第4页：AI 赋能软件开发实现地图
- 第5页：AI 赋能软件开发工具体系
- 第6页：分隔页（01 需求衔接）
- 第7页：需求规格编写
- 第8页：原型图设计
**关键概念**：
- AI 编程5阶段：原始 → Rule约束 → 规格驱动 → Loop工程 → Harness驾驭
- 4个核心问题：需求衔接、开发实现、测试验收、Agent as Code
- 需求规格：Markdown格式、字段清单、业务规则条目化
- 原型图：Figma/Stitch/HTML + Design.md
---
### 01_开发实现_第9-15页.md
**覆盖页码**：第9-15页
**核心内容**：
- 第9页：分隔页（02 开发实现）
- 第10页：如何让 AI 听话 - 规则、规格、技能
- 第11页：构建 AI 上下文体系
- 第12页：如何让 AI 调用外部工具
- 第13页：用什么 AI 编程工具
- 第14页：用什么 SDD 框架比较好
- 第15页：一个新星：Superpower
**关键概念**：
- 三要素：Rules（规则）、Specification（规格）、Skill（技能）
- 上下文体系：AGENTS.md + docs/（standards/features/plans/designs/others）
- 过程方案 vs 事实方案：Plans（追加新文件）vs Designs（覆盖更新）
- 外部工具：MCP、Skills、CLI
- AI 工具：Claude Code、Cursor、Kiro、Trae、OpenCode、Codex CLI
- SDD 框架：BMAD、Spec Kit、OpenSpec、Kiro
---
### 02_开发实现续_第16-19页.md
**覆盖页码**：第16-19页
**核心内容**：
- 第16页：技术规格如何编写
- 第17页：打样工程：如何让 AI 抄作业
- 第18页：如何多任务同步开发
- 第19页：完整的核心 Loop 过程（研发自测）
**关键概念**：
- 技术规格 DSL：领域模型（PlantUML）、数据库（SQL DDL）、API（OpenAPI）、时序图、专题设计
- 打样工程：提供代码模版，让 AI "抄作业"
- 三层架构：Controller → Service → Repository
- Git Worktree：多任务并行开发
- 核心 Loop：Plan → TDD → 验证
---
### 03_测试验收_第20-25页.md
**覆盖页码**：第20-25页
**核心内容**：
- 第20页：分隔页（03 测试验收）
- 第21页：AI 辅助下的测试策略
- 第22页：AI 如何操作浏览器
- 第23页：如何用测试用例生成 E2E 测试
- 第24页：Playwright E2E 示例
- 第25页：超级 Loop（E2E Loop）
**关键概念**：
- 测试策略：Lint → Code Review → 单元测试 → API 测试 → E2E 测试
- AI 操作浏览器：Playwright MCP、Chrome DevTools MCP、Browser Use、Computer Use
- E2E 测试生成：Browser Use 探索 → Playwright 固化 → 截图视觉兜底
- Playwright 最佳实践：稳定选择器、API 登录、测试数据管理
- 超级 Loop：在核心 Loop 基础上增加 E2E 测试验证
---
### 04_Agent_as_Code_第26-30页.md
**覆盖页码**：第26-30页
**核心内容**：
- 第26页：分隔页（04 Agent as Code）
- 第27页：AI 工程文件管理
- 第28页：分隔页（附录&参考资料）
- 第29页：关于 AI 编程实践的心得
- 第30页：参考资料
**关键概念**：
- Agent as Code：将 AI 协作文件以代码方式管理
- AGENTS.md 作为宪法级配置
- 软链接实现多工具共享配置
- Skills 目录：可复用的 AI 能力单元
- MCP 配置：让 AI 访问外部工具
- 实践心得：放弃"开箱即用"，"少量取用，大量实践"
---
## 核心框架总结
### 团队级 AI Coding 的4个核心问题
| 问题 | 核心挑战 | 解决方案 |
|------|---------|---------|
| **需求衔接** | 如何编写 AI 能理解的需求？ | Markdown 格式、字段清单、业务规则条目化、原型图传递 |
| **开发实现** | 如何让 AI 生成高质量代码？ | 规则/规格/技能、上下文体系、MCP/Skills/CLI、SDD 框架、打样工程、核心 Loop |
| **测试验收** | 如何自动化测试 AI 生成的代码？ | 分层测试、AI 操作浏览器、E2E 测试生成、超级 Loop |
| **Agent as Code** | 如何组织 AI 协作文件？ | AGENTS.md、文档体系、Skills 库、MCP 配置、软链接 |
### AI 编程5阶段演进
```
原始阶段 → Rule 约束 → 规格驱动 → Loop Engineering → Harness 驾驭工程
↓ ↓ ↓ ↓ ↓
手动复制 RIPER-5 OpenSpec 自动循环 工程治理
半自动 持续对话 文件进出 测试驱动 无人值守
```
### 文档分层体系
```
AGENTS.md ← 宪法（所有 AI 工具读取）
docs/
├── standards/ ← 标准规格（架构/命名/API/安全规范）
├── features/ ← 需求规格（产品/BA维护）
├── designs/ ← 设计规格（事实方案，Source of Truth）
├── plans/ ← 计划规格（过程方案，追加不修改）
└── others/ ← 架构决策、Release、测试用例等
skills/ ← AI 技能（可复用能力单元）
mcp/ ← MCP 配置（外部工具接入）
```
### 核心 Loop 流程
```
Plan 阶段（人机协作）
↓
装载需求规格 → 创建 Plan → 确认 Plan
↓
执行阶段（AI 自治）
↓
编写 API 测试 → 编写实现 → 运行测试
↓ ↓
↓ 失败 ↓ 成功
↓ ↓
修复重试 ←──────────────────── 退出循环
```
### 测试策略金字塔
```
E2E 测试（Playwright）
/ \
/ API 测试（Karate） \
/ \
/ 单元测试（JUnit/Jest） \
/ \
/ Code Review（AI + 人工） \
/ \
/ Lint 代码扫描（ESLint/SonarQube）\
/____________________________________\
```
---
## 关键工具清单
### AI 编程工具
- **Claude Code**：Anthropic 出品，强大的推理能力
- **Cursor**：基于 VS Code，AI 优先设计
- **Kiro**：AWS 出品，深度集成 AWS 服务
- **Trae**：字节跳动出品，中文支持好
- **OpenCode**：开源，支持多种 AI 模型
- **Codex CLI**：OpenAI 出品，基于 GPT-4
### SDD 框架
- **BMAD**：企业级，强治理，多 Agent 编排
- **Spec Kit**：工程化，Git 集成，适合新项目
- **OpenSpec**：轻量级，灵活，适合存量项目
- **Kiro**：IDE 原生，可执行 Spec，自动验证
### 测试工具
- **Playwright**：最流行的 E2E 测试框架
- **Browser Use**：AI 操作浏览器，Token 消耗低
- **Karate**：BDD 风格的 API 测试框架
- **RestAssured**：Java API 测试库
- **SonarQube**：代码质量分析工具
- **ESLint**：JavaScript 代码检查工具
### 文档工具
- **PlantUML**：文本化的 UML 图
- **OpenAPI**：API 规范定义
- **Markdown**：通用文档格式
- **Mermaid**：Markdown 中的图表
### 协作工具
- **Git**：版本控制
- **GitHub/GitLab**：代码托管和协作
- **Git Worktree**：多工作区并行开发
---
## 最佳实践清单
### 需求阶段
- [ ] 使用 Markdown 编写需求规格
- [ ] 区分增量需求和存量需求
- [ ] 使用字段清单定义数据模型
- [ ] 业务规则条目化，每条规则独立可测
- [ ] 通过原型图传递 UI 设计（Figma/Stitch/HTML）
- [ ] 维护 Design.md 约束前端风格
### 开发阶段
- [ ] 建立 AGENTS.md 作为宪法级配置
- [ ] 区分过程方案（Plans）和事实方案（Designs）
- [ ] 使用 DSL 编写技术规格（PlantUML/SQL/OpenAPI）
- [ ] 建立打样工程，提供代码模版
- [ ] 使用 TDD 驱动开发
- [ ] 使用 Git Worktree 并行开发
- [ ] Plan 阶段充分沟通，关闭所有开放性问题
### 测试阶段
- [ ] 分层测试：单元测试 → API 测试 → E2E 测试
- [ ] 先用 Browser Use 探索，再固化到 Playwright
- [ ] 使用稳定的选择器（data-testid、角色、标签）
- [ ] 关键页面截图验证（视觉回归测试）
- [ ] 所有测试集成到 CI/CD 流程
### 协作阶段
- [ ] 使用 AGENTS.md 作为统一入口
- [ ] 使用软链接让多个工具共享配置
- [ ] 所有配置纳入 Git 管理
- [ ] 建立 Skills 库，沉淀常用 AI 能力
- [ ] 配置 MCP 让 AI 访问外部工具
---
## 学习路径
### 入门（1-2周）
1. 理解 AI 编程的5个发展阶段
2. 建立 AGENTS.md
3. 使用一个 AI 工具（如 Claude Code）
4. 实践核心 Loop（Plan → TDD → 验证）
### 进阶（1-2月）
1. 学习 SDD 框架（BMAD/SpecKit/OpenSpec/Kiro）
2. 使用 DSL 编写技术规格
3. 建立打样工程
4. 实践分层测试
5. 使用 Playwright 进行 E2E 测试
### 高级（持续）
1. 构建完整的 Harness 体系
2. 开发自定义 Skills
3. 配置 MCP 访问外部工具
4. 优化 AI 工作流
5. 分享实践经验
---
## 关键洞察
1. **AI 编程不是银弹**：需要工程化的方法来驾驭
2. **上下文是关键**：AI 需要清晰的上下文才能生成高质量代码
3. **测试是保障**：自动化测试是 AI 生成代码质量的保障
4. **实践出真知**：没有放之四海而皆准的方案，需要根据项目特点定制
5. **持续演进**：AI 能力在快速提升，方法也需要持续演进
6. **区分过程和事实**：Plans 是过程记录（追加不修改），Designs 是事实描述（覆盖更新）
7. **少量取用，大量实践**：不要一开始就引入所有概念，先实践核心，再逐步扩展
---
## 术语表
| 术语 | 英文 | 定义 |
|------|------|------|
| AI 编程 | AI Coding | 使用 AI 辅助或自动化进行软件开发 |
| Harness | Harness | 为 AI 提供约束和工具的工程实践 |
| SDD | Spec-Driven Development | 以规格文档为核心的开发方法 |
| MCP | Model Context Protocol | AI 与外部系统通信的标准协议 |
| AGENTS.md | AGENTS.md | AI 协作的宪法级配置文件 |
| Plan | Plan | AI 执行任务的规划文档 |
| Spec | Specification | 结构化的需求描述 |
| Rule | Rule | 约束 AI 行为的规则 |
| Skill | Skill | 可复用的 AI 能力单元 |
| Loop | Loop | AI 自治运行的开发循环 |
| TDD | Test-Driven Development | 测试驱动开发 |
| E2E | End-to-End | 端到端测试 |
| DSL | Domain Specific Language | 领域特定语言 |
| Worktree | Git Worktree | Git 的多工作区功能 |
| Browser Use | Browser Use | AI 操作浏览器的框架 |
| Playwright | Playwright | 浏览器自动化测试框架 |
| BMAD | Business Model Architecture Design | 企业级 SDD 框架 |
| OpenSpec | OpenSpec | 轻量级 SDD 框架 |
| Kiro | Kiro | AWS 推出的 AI IDE 和 SDD 框架 |
---
## 参考资料
1. [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
2. [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
3. [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
4. [从 Rule、Spec 到 Harness：AI Coding 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
5. [让 AI 乖乖听话的几个 Rules](https://mp.weixin.qq.com/s/FXNzk_y2Z2h8BVe62uEn_A)
6. [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
7. [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)
8. [attractor-guided-engineering-template](https://github.com/entropy-cloud/attractor-guided-engineering-template)
9. [OpenAI: Tools Computer Use](https://developers.openai.com/api/docs/guides/tools-computer-use)
---
## 文档信息
- **原文**：团队级 AI Coding 简明手册 v0.2
- **作者**：系统设计研讨会分享人
- **日期**：2026年6月18日
- **研究日期**：2026-06-20
- **研究范围**：第1-30页（全文）
- **归档位置**：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/
- **文件列表**：
- 00_概述与前言.md（第1-8页）
- 01_开发实现_第9-15页.md（第9-15页）
- 02_开发实现续_第16-19页.md（第16-19页）
- 03_测试验收_第20-25页.md（第20-25页）
- 04_Agent_as_Code_第26-30页.md（第26-30页）
- 00_索引.md（本文档）
---
**研究完成** ✅
所有30页内容已详细研究并归档，包含：
- 原文内容提取
- 深入解读和背景知识
- 实践建议和工具推荐
- 代码示例和配置示例
- 最佳实践清单
- 学习路径指南

315
AI工程/团队级AI_Coding简明手册_逐页研究/01_开发实现_第9-15页.md Executable file
View File

@@ -0,0 +1,315 @@
# 第9-15页：开发实现篇
> 章节：02 开发实现
> 核心问题：如何让 AI 听话？如何构建 AI 上下文体系？如何调用外部工具？
---
## 第9页：分隔页（02 开发实现）
### 原文内容
章节分隔页，标志进入"开发实现"部分
### 研究要点
- 这是4个核心问题中的第2个
- 开发实现是整个流程中最关键的环节
- 核心目标：让 AI 生成高质量、符合规范的代码
---
## 第10页：如何让 AI 听话 - 规则、规格、技能
### 原文内容
**三要素模型**：
| 要素 | 定义 | 示例 |
|------|------|------|
| **规则 Rules** | 约束 AI 行为的边界，定义能做什么、不能做什么 | "请做一个登录注册页面，需要能实现邮箱验证" |
| **规格 Specification** | 把模糊的需求收敛为结构化的内容，甚至通过 DSL 描述 | 用户故事 + 验收标准 |
| **技能 Skill** | 通过打包提示词、脚本、模版，进一步精确拓展 AI 的能力 | 提示词 + 规格文档 |
**规则示例（Java 代码风格）**：
```markdown
# Java 代码风格 Rules
1. 使用 Java 17 语法，不使用已废弃 API
2. 类名使用大驼峰（PascalCase），方法名和变量名使用小驼峰（camelCase）
3. 常量使用全大写下划线分隔（UPPER_SNAKE_CASE）
4. 单行代码不超过 120 字符，超过则换行
5. 大括号采用 Egyptian 风格（左括号不换行）
6. 禁止使用 @Autowired 字段注入，改用构造器注入
```
**规格示例（用户故事 + 验收标准）**：
```markdown
作为一个新用户或现有用户，我想要一个同时支持注册和登录的页面，
并且在注册时能通过邮箱完成身份验证，以便安全地创建账户并登录系统。
验收标准（AC）：
1. 用户可以输入邮箱、密码等必要信息进行注册。注册提交后，
系统向用户邮箱发送验证链接（或验证码）。用户点击链接
（或输入验证码）后，账户状态变为"已验证"。
2. 已验证用户可使用邮箱和密码登录系统。未验证邮箱的用户
尝试登录时，系统提示"请先完成邮箱验证"。
3. 邮箱格式不正确或已被注册时，系统给出明确提示。验证链
接过期或无效时，支持重新发送验证邮件。
```
### 深入解读
**规则 Rules 的本质**
- 作用：约束 AI 的行为边界
- 载体：
- Cursor：`.cursor/rules/` 目录
- Claude Code：`CLAUDE.md` 文件
- OpenCode：`.opencode/config.json`
- 通用：`AGENTS.md` 文件
**规则的分类**：
1. 代码风格规则：命名规范、格式规范
2. 架构规则：分层架构、依赖方向
3. 安全规则：敏感数据处理、权限控制
4. 性能规则：数据库查询优化、缓存策略
**规格 Specification 的价值**
- 消除歧义：将模糊需求转化为明确定义
- 可验证性：验收标准可以直接转化为测试用例
- 可追溯性：需求变更有历史记录
**规格的格式**：
1. 用户故事格式：As a... I want... So that...
2. Given-When-Then 格式：行为驱动开发（BDD）
3. 表格格式：字段清单、业务规则
4. DSL 格式：领域特定语言
**技能 Skill 的概念**
- 定义：打包的可复用能力单元
- 组成：提示词模版、脚本工具、文档模版、配置文件
- 复用性：可以在多个项目中使用
### 实践建议
- 建立规则库：将常用的规则沉淀下来
- 使用规格模版：统一需求文档格式
- 开发技能包：将常用的能力封装成技能
---
## 第11页：构建 AI 上下文体系
### 原文内容
**核心理念**：使用完整的文档来描述上下文和约束体系，区分过程方案和事实方案，减少维护成本。
**文档分层结构**：
```
AGENTS.md ← 宪法
docs/
├── standards/ ← 标准规格（架构/命名/API/安全规范）
├── features/ ← 需求规格（产品/BA维护）
├── plans/ ← 计划规格（过程方案）
├── designs/ ← 设计规格（事实方案，Source of Truth）
└── others/ ← 架构决策、Release、测试用例等
```
**规格流转**：
- 追加（Plans）：每次创建新文件，细微修改不再更新
- 变更（Designs）：每次以最终态更新，作为下一次 Plan 的事实依据
### 深入解读
**AGENTS.md 的内容**：
```markdown
# 项目基本信息
- 项目名称：示例项目
- 技术栈：Java 17, Spring Boot 3.x, MySQL 8.0
- 代码规范：阿里巴巴 Java 开发手册
# AI 行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含 created_at, updated_at 字段
3. API 接口必须使用 RESTful 风格
4. 敏感数据必须加密存储
```
**过程方案 vs 事实方案详细对比**
| 维度 | 过程方案（Plans） | 事实方案（Designs） |
|------|------------------|-------------------|
| 目的 | 记录实现过程 | 记录当前状态 |
| 更新方式 | 追加新文件 | 覆盖更新 |
| 生命周期 | 短期（任务完成后归档） | 长期（持续维护） |
| 维护成本 | 低（不修改旧文件） | 高（必须保持最新） |
| 使用场景 | 任务执行、问题排查 | 新功能开发、架构决策 |
| 示例 | plan-2026-06-20-feature-x.md | database-schema.md |
**Plans 最佳实践**：
- 命名规范：`plan-YYYY-MM-DD-feature-name.md`
- 内容结构：目标、方案、任务列表、状态、问题记录
- 归档策略：任务完成后移动到 `archive/` 目录
**Designs 最佳实践**：
- 命名规范：使用功能名称，如 `database-schema.md`
- 内容结构：概述、详细设计、变更历史
- 更新策略：每次变更必须更新文档，保持最新
---
## 第12页：如何让 AI 调用外部工具？
### 原文内容
**三种方式**：
**1. MCP（Model Context Protocol）**
- AI 与外部系统通信的标准协议
- 标准化接口、双向通信、即插即用
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-sqlite"]
}
}
}
```
**2. Skills**
- 将开源工具用脚本封装成 AI 可直接调用的能力单元
- 脚本封装、触发词驱动、可复用
```markdown
# Commit & Push Skill
## 触发词: commit, push
## 执行
git add -A
git commit -m "{message}"
git push
## 规则
- 提交前检查 lint
- 信息遵循 conventional commit
```
**3. Commands（CLI）**
- 通过 CLI 命令让 AI 直接调用外部工具
- 即时执行、管道组合、权限可控
```bash
# AI 通过 CLI 调用工具
> 部署到生产环境
npm run build
npx vercel --prod
```
### 深入解读
**MCP 详解**
- Anthropic 提出的开放标准协议
- Client-Server 架构
- 常用 MCP Server：
- 数据库：mcp-server-sqlite、mcp-server-postgres
- 文件系统：mcp-server-filesystem
- Web 搜索：mcp-server-brave-search
- GitHub：mcp-server-github
- 浏览器：mcp-server-playwright
**Skills 详解**
- 可复用的能力单元
- 组成：触发词、执行逻辑、参数、规则
- 开发流程：需求分析 → 脚本开发 → 触发词定义 → 测试验证 → 文档编写
**CLI 安全考虑**：
- 白名单机制：只允许执行特定的命令
- 沙箱环境：在隔离环境中执行
- 审计日志：记录所有执行的命令
---
## 第13页：用什么 AI 编程工具？
### 原文内容
**三类工具**：
**1. 命令行类**（AI 优先，人辅助）
- Claude Code、Codex CLI、OpenCode
**2. AI IDE**（人掌控感更强）
- Cursor、Kiro、Trae
**3. 增强插件**（预制辅助工具集）
- Superpower、oh-my-opencode、oh-my-codex
### 工具对比表
| 工具 | 类型 | 价格 | AI 模型 | 适用场景 |
|------|------|------|---------|---------|
| Claude Code | CLI | 按 Token | Claude | 复杂逻辑 |
| Codex CLI | CLI | 按 Token | GPT-4 | 快速原型 |
| OpenCode | CLI | 免费 | 多模型 | 预算有限 |
| Cursor | IDE | $20/月 | 多模型 | 日常开发 |
| Kiro | IDE | 免费+付费 | Claude | AWS 项目 |
| Trae | IDE | 免费+付费 | 豆包 | 中文项目 |
### 各工具详解
**Claude Code**
- 强大的推理能力，支持长上下文
- 内置 MCP 支持，Loop 模式
- 适合复杂逻辑开发、架构设计
**Cursor**
- 基于 VS Code，AI 优先设计
- 强大的代码补全，Composer 模式
- 适合日常开发
**Kiro（AWS）**
- 深度集成 AWS 服务
- 支持 Spec 驱动开发
- 自动化测试生成
**Trae（字节跳动）**
- 集成豆包大模型
- 中文支持好
- 适合中文项目
---
## 第14页：用什么 SDD 框架比较好？
### 原文内容
**SDD（Spec-Driven Development）框架对比**
Spec = 单一事实来源（SSoT），甚至可以直接生成代码
| 维度 | BMAD | Spec Kit | OpenSpec | Kiro |
| --------- | ------------------------ | ---------------------- | ----------------- | ------------------ |
| 方法定位 | 企业级 SDD 操作系统 | 工程化 Spec 工作流 | 轻量 Spec 层 | IDE 原生 SDD |
| 核心理念 | Spec = 治理体系 + 多 Agent 编排 | Spec = 开发入口 + Git 生命周期 | Spec = 变更单元（持续演化） | Spec = 可执行源（代码与测试） |
| Spec 生命周期 | 全生命周期 | 与分支绑定（短生命周期） | 长期存在（持续演化） | 持续驱动 |
| Spec 粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 可执行能力 | 通过流程驱动 | 驱动开发流程 | 类 Prompt | 可生成代码+测试并自动校验 |
| 流程控制 | 强（阶段+审批+Agent） | 中（Plan→Spec→Tasks） | 弱（自由演化） | 强（闭环） |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 与代码关系 | 间接 | 半耦合 | 弱耦合 | 强耦合 |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
### 框架选择指南
| 团队规模 | 项目类型 | 推荐框架 |
| ---- | ----- | -------- |
| 大型团队 | 企业级项目 | BMAD |
| 中型团队 | 新项目 | Spec Kit |
| 小型团队 | 存量项目 | OpenSpec |
| 个人开发 | 快速迭代 | Kiro |
---
## 第15页：一个新星：Superpower
### 原文内容
- 提供了一些内置的 skills
- 方便开箱即用
- 缺点是不太方便精细调整
### 深入解读
- 为 AI 编程工具提供增强功能的插件集合
- 内置 Skills：预制的常用能力
- 优势：快速上手、功能丰富、社区支持
- 劣势：不够灵活、黑盒、依赖性强
- 适合快速原型和学习，不适合深度定制

692
AI工程/团队级AI_Coding简明手册_逐页研究/02_开发实现续_第16-19页.md Executable file
View File

@@ -0,0 +1,692 @@
# 第16-19页：开发实现续篇（技术规格 + 打样 + 多任务 + 核心Loop）
> 章节：02 开发实现（续）
> 核心问题：技术规格如何编写？如何让 AI 抄作业？如何多任务同步开发？核心 Loop 如何运转？
---
## 第16页：技术规格如何编写？
### 原文内容
**技术规格的5个模块**（DSL 驱动）：
| 模块 | 表达标准 | 格式 | 产出内容 | 约束/规范 |
|------|---------|------|---------|----------|
| **领域模型** | PlantUML/Smart Domain | .puml | 实体、属性、关系（ER/类图） | 必须表达实体关系；字段需与数据库一致；标注聚合关系 |
| **数据库** | SQL DDL/DBML/Flyway 脚本 | .sql | 表结构、索引、约束 | 必须可执行；包含索引和外键；字段与领域模型一致 |
| **API** | OpenAPI 3.x | .yaml/.json | 接口定义、请求/响应结构 | 必须定义 schema；禁止只写接口说明；字段与模型一致 |
| **时序图** | PlantUML | .puml | 调用流程、系统交互 | 必须反映真实调用链；建议包含异常分支（alt） |
| **专题设计** | Markdown | .md | 架构策略（权限/事务/缓存等） | 只写"策略与规则"，不重复 API/DDL；强调设计决策 |
### 深入解读
**为什么用 DSL？**
- **可执行**：DDL 可以直接运行，OpenAPI 可以生成代码
- **AI 友好**：LLM 对 DSL 的理解比自然语言更精确
- **一致性保证**：DSL 有语法规则，不容易产生歧义
**领域模型详解**
**PlantUML 示例**：
```plantuml
@startuml
entity User {
* id : Long <<PK>>
--
* username : String(50)
* email : String(100)
* role_id : Long <<FK>>
}
entity Role {
* id : Long <<PK>>
--
* name : String(20)
}
User }o--|| Role : "拥有"
note right of User : 聚合根
@enduml
```
**约束要求**：
- 必须表达实体关系（1:1, 1:N, M:N）
- 字段需与数据库一致（类型、长度、默认值）
- 标注聚合关系（哪些是聚合根）
**数据库设计详解**
**SQL DDL 示例**：
```sql
-- Flyway migration: V1__create_users_table.sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(50) NOT NULL UNIQUE,
email VARCHAR(100) NOT NULL UNIQUE,
password VARCHAR(255) NOT NULL,
role_id BIGINT NOT NULL,
status TINYINT(1) DEFAULT 1,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_username (username),
INDEX idx_email (email),
CONSTRAINT fk_user_role FOREIGN KEY (role_id) REFERENCES roles(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
**必须可执行**：
- DDL 必须可以直接在数据库中运行
- 使用 Flyway/Liquibase 管理版本
- 包含索引（查询性能）和外键（数据完整性）
**API 设计详解**
**OpenAPI 3.x 示例**：
```yaml
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/api/v1/users:
post:
summary: 创建用户
tags: [User]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: 创建成功
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'400':
description: 参数错误
components:
schemas:
CreateUserRequest:
type: object
required: [username, email, password]
properties:
username:
type: string
minLength: 3
maxLength: 50
description: 登录用户名，唯一
email:
type: string
format: email
description: 电子邮箱，唯一
password:
type: string
minLength: 8
description: 密码，≥8位含大小写
UserResponse:
type: object
properties:
id:
type: integer
format: int64
username:
type: string
email:
type: string
role:
type: string
enum: [admin, user]
status:
type: boolean
```
**约束要求**：
- 必须定义 schema（请求和响应的结构）
- 禁止只写接口说明（"返回用户列表"这种描述不够）
- 字段与领域模型一致（类型、名称、约束）
**时序图详解**
**PlantUML 时序图示例**：
```plantuml
@startuml
actor User
participant "UserController" as C
participant "UserService" as S
participant "UserRepository" as R
database "MySQL" as DB
User -> C: POST /api/v1/users
C -> C: 参数校验
C -> S: createUser(CreateUserRequest)
S -> S: 业务规则校验
S -> R: save(User)
R -> DB: INSERT INTO users ...
DB --> R: 返回结果
R --> S: 返回 User
S --> C: 返回 UserResponse
C --> User: 201 Created
alt 用户名已存在
S --> C: throw DuplicateException
C --> User: 409 Conflict
end
@enduml
```
**约束要求**：
- 必须反映真实调用链
- 建议包含异常分支（alt）
- 标注关键步骤（参数校验、业务规则校验）
**专题设计详解**
**专题设计示例**：
```markdown
# 权限设计方案
## 策略
- 使用 RBAC（基于角色的访问控制）
- 权限注解：@RequirePermission("user:create")
- 默认拒绝所有未授权的请求
## 规则
1. 管理员角色拥有所有权限
2. 普通用户只能操作自己的数据
3. 敏感操作需要二次确认
## 设计决策
- 选择 RBAC 而非 ABAC：业务场景简单，角色固定
- 权限存储在 Redis：减少数据库查询
- 权限变更实时生效：通过 Redis Pub/Sub 通知
```
**约束要求**：
- 只写"策略与规则"
- 不重复 API/DDL（避免信息冗余）
- 强调设计决策（为什么选择这个方案）
### 实践建议
- 使用 DSL：统一技术规格的表示方式
- 保持一致性：领域模型、数据库、API 要一致
- AI 辅助生成：让 AI 根据规格生成代码
- 版本控制：技术规格纳入 Git 管理
---
## 第17页：打样工程：如何让 AI 抄作业？
### 原文内容
**参考代码**：https://github.com/domain-driven-design/ddd-microservices
**原则**：
1. 约定大于配置
2. 编排逻辑和原子能力分离
3. 操作者和被操作对象分离
**常见 CQRUD 操作的工序**：
**1. 简单 CRUD**：
```
Controller + Command → AppService → Repository → Response 对象
```
**2. 复杂或有复用逻辑的 CRUD**：
```
Controller + Command → AppService → DomainService → Repository → Response 对象
```
**3. 复杂的查询操作**：
```
Controller + Query 对象 → AppService → QueryPO（或复用 PO）→ Response 对象
```
### 深入解读
**什么是打样工程？**
- 定义：提供代码模版和示例，让 AI 参考生成代码
- 目的：保证代码风格统一、质量稳定
- 核心理念：让 AI "抄作业"，而不是自由发挥
**为什么需要打样工程？**
- AI 生成的代码质量不稳定
- 不同 AI 工具生成的代码风格不同
- AI 可能不知道项目的最佳实践
**打样工程的优势**：
1. 提高代码质量：基于模版生成，质量有保障
2. 统一代码风格：所有代码遵循相同的风格
3. 减少 Review 成本：代码符合规范，Review 更快
4. 知识沉淀：最佳实践沉淀在模版中
**三层架构详解**
**Controller 层**：
- 职责：接收请求、参数校验、调用 Service
- 输入：Command/Query 对象
- 输出：Response 对象
- 不包含业务逻辑
**Service 层**：
- 职责：编排业务逻辑、调用 DomainService/Repository
- AppService：应用服务，编排逻辑
- DomainService：领域服务，复杂业务逻辑
- Repository：数据访问
**Repository 层**：
- 职责：数据持久化
- 输入：实体对象
- 输出：实体对象或 PO（Persistent Object）
**工序详解**
**简单 CRUD（无复用逻辑）**：
```java
// Controller
@PostMapping("/users")
public Response<UserResponse> createUser(@Valid @RequestBody CreateUserCommand cmd) {
return Response.success(userAppService.create(cmd));
}
// AppService
public UserResponse create(CreateUserCommand cmd) {
User user = userRepository.save(User.from(cmd));
return UserResponse.from(user);
}
// Repository
public User save(User user) {
userMapper.insert(user);
return user;
}
```
**复杂 CRUD（有复用逻辑）**：
```java
// AppService - 编排逻辑
public UserResponse create(CreateUserCommand cmd) {
// 1. 校验用户名唯一
domainService.checkUsernameUnique(cmd.getUsername());
// 2. 加密密码
String encryptedPassword = domainService.encryptPassword(cmd.getPassword());
// 3. 保存用户
User user = User.from(cmd, encryptedPassword);
userRepository.save(user);
// 4. 发送欢迎邮件
domainService.sendWelcomeEmail(user);
return UserResponse.from(user);
}
// DomainService - 原子能力
public void checkUsernameUnique(String username) {
if (userRepository.existsByUsername(username)) {
throw new BusinessException("用户名已存在");
}
}
```
**复杂查询**：
```java
// Controller
@GetMapping("/users")
public Response<Page<UserResponse>> listUsers(@Valid UserQuery query) {
return Response.success(userAppService.list(query));
}
// AppService
public Page<UserResponse> list(UserQuery query) {
Page<UserPO> page = userRepository.findByQuery(query);
return page.map(UserResponse::from);
}
// Repository
public Page<UserPO> findByQuery(UserQuery query) {
// 构建查询条件
// 执行分页查询
// 返回分页结果
}
```
### 实践建议
- 建立打样工程：提供标准的代码模版
- 分层清晰：Controller、Service、Repository 职责明确
- 工序标准化：简单 CRUD、复杂 CRUD、复杂查询各有标准
- AI 参考打样：让 AI 根据打样工程生成代码
---
## 第18页：如何多任务同步开发？
### 原文内容
使用 git 的 Worktree 功能同时把一个仓库的多个分支映射到不同文件夹。Claude Code、Codex、Cursor 等已经自动支持使用 subagent 创建 Worktree，加速开发。
```bash
# 基于已有分支创建
git worktree add ../feature-login feature/login
# 创建新分支 + 工作区（最常用）
git worktree add -b feature-payment ../feature-payment
# 查看所有 worktree
git worktree list
# 删除工作区
git worktree remove ../feature-login
```
### 深入解读
**什么是 Git Worktree？**
- 定义：Git 的一个功能，允许你从同一个仓库检出多个工作目录
- 每个工作目录都是一个独立的分支
- 共享同一个 .git 目录（节省磁盘空间）
**为什么需要 Worktree？**
- AI 编程时，经常需要同时开发多个功能
- 传统方式：切换分支，容易丢失上下文
- Worktree：每个功能在独立的目录，互不干扰
**Worktree 的优势**：
1. 并行开发：多个 AI 实例可以同时工作在不同分支
2. 上下文隔离：每个功能的上下文独立，不会混淆
3. 快速切换：不需要 `git checkout`，直接切换目录
4. 节省空间：共享 .git 目录
**使用场景**
**场景1：多 AI 实例并行开发**
```bash
# 主工作区：开发功能 A
cd /project/feature-a
claude-code # 启动 Claude Code
# 新开终端：开发功能 B
cd /project/feature-b
claude-code # 启动另一个 Claude Code 实例
# 再开终端：开发功能 C
cd /project/feature-c
claude-code # 启动第三个 Claude Code 实例
```
**场景2：AI + 人工并行开发**
```bash
# AI 在 feature-a 开发
cd /project/feature-a
claude-code
# 人工在 main 分支修复紧急 bug
cd /project/main
# 手动修复 bug
```
**场景3：Code Review 时继续开发**
```bash
# 主工作区：feature-a 提交 PR，等待 review
# 新开工作区：继续开发 feature-b
git worktree add -b feature-b ../feature-b
cd ../feature-b
claude-code
```
**Worktree 管理**
**列出所有工作区**：
```bash
git worktree list
# 输出：
# /project/main abc1234 [main]
# /project/feature-a def5678 [feature-a]
# /project/feature-b ghi9012 [feature-b]
```
**清理工作区**：
```bash
# 删除工作区（会自动删除目录）
git worktree remove ../feature-a
# 强制删除（即使有未提交的更改）
git worktree remove --force ../feature-a
# 清理已删除的工作区记录
git worktree prune
```
**AI 工具自动支持**：
- Claude Code：自动创建 Worktree 进行并行开发
- Codex CLI：支持在独立工作区运行
- Cursor：可以在多个窗口打开不同 Worktree
### 实践建议
- 使用 Worktree 并行开发：提高开发效率
- 命名规范：工作区目录名与分支名一致
- 及时清理：完成的功能及时删除 Worktree
- AI 工具支持：利用 AI 工具的自动 Worktree 功能
---
## 第19页：完整的核心 Loop 过程（研发自测）
### 原文内容
**核心理念**：通过 TDD/浏览器调试（前端），AI 自治运行
**Loop 流程图**：
```
开始进入循环
↓
[Chat] 进入 Plan 模式
↓
装载需求规格，给出指令进行 Plan
↓
[Chat] 符合要求，退出 Plan 模式，开始执行？
↓ 是
[模型] 读取 Plan
↓
创建 API 测试，实现代码
↓
[模型] 运行测试/浏览器调试，是否成功？
↓ 否
重复多次 / 白天持续很久 / 夜间
↓ 是
[模型] 退出循环
↓
（给予 ByPass 权限）
```
**核心思想**：
1. Plan 阶段尽可能锁定上下文到 Plan 中，关闭所有的开放性问题
2. Plan 中记录实现状态，让任务可以分批完成或者重试
3. 需要给出确定性的验收方式：例如通过所有的 API 测试，让 AI 能建立自我修复标准
**Loop 规则（API 为例，放到 AGENTS.md 作为开发流程要求）**：
1. **Plan 等待确认**：在 docs/plans 下根据模版创建 Plan
2. **编写 API 测试**：根据 Plan 实现 API 测试，运行成功并断言失败
3. **编写实现**：编写单元测试 + 实现代码，通过编译
4. **运行 API 测试**：运行测试，并修复失败的测试和其他错误
### 深入解读
**什么是核心 Loop？**
- 定义：AI 自治运行的开发循环
- 目标：通过 TDD 驱动，AI 自动实现需求并修复问题
- 特点：Plan 阶段人机协作，执行阶段 AI 自治
**Loop 的三个阶段**
**阶段1：Plan（规划）**
- 输入：需求规格、技术规格
- 输出：实现方案、任务列表
- 关键：关闭所有开放性问题
- 人工介入：确认 Plan 是否合理
**阶段2：执行（Implementation）**
- 输入：Plan
- 输出：API 测试、实现代码
- 关键：按照 Plan 逐步实现
- AI 自治：无需人工介入
**阶段3：验证（Verification）**
- 输入：API 测试、实现代码
- 输出：测试结果、修复建议
- 关键：所有测试通过
- AI 自治：自动运行测试，自动修复
**Plan 模版示例**：
```markdown
# Plan: 实现用户注册功能
## 目标
实现用户注册 API，支持邮箱验证
## 任务列表
- [ ] 1. 创建数据库表 users
- [ ] 2. 实现 POST /api/v1/users API
- [ ] 3. 实现邮箱验证逻辑
- [ ] 4. 编写单元测试
- [ ] 5. 编写 API 测试
## 实现方案
1. 使用 Flyway 创建 users 表
2. Controller 接收 CreateUserCommand
3. AppService 调用 UserRepository 保存
4. 发送验证邮件（使用 JavaMail）
## 验收标准
- 所有单元测试通过
- 所有 API 测试通过
- 代码符合阿里巴巴 Java 开发手册
## 状态
- 开始时间：2026-06-20 10:00
- 预计完成：2026-06-20 12:00
- 实际完成：待更新
```
**TDD 驱动详解**
**步骤1：编写 API 测试**
```java
@Test
public void testCreateUser() {
CreateUserRequest request = new CreateUserRequest();
request.setUsername("testuser");
request.setEmail("test@example.com");
request.setPassword("Password123");
Response<UserResponse> response = userClient.create(request);
assertEquals(201, response.getCode());
assertNotNull(response.getData().getId());
assertEquals("testuser", response.getData().getUsername());
}
@Test
public void testCreateUser_DuplicateUsername() {
// 先创建一个用户
CreateUserRequest request1 = new CreateUserRequest();
request1.setUsername("testuser");
request1.setEmail("test1@example.com");
request1.setPassword("Password123");
userClient.create(request1);
// 再创建一个同名用户
CreateUserRequest request2 = new CreateUserRequest();
request2.setUsername("testuser");
request2.setEmail("test2@example.com");
request2.setPassword("Password123");
Response<UserResponse> response = userClient.create(request2);
assertEquals(409, response.getCode());
assertEquals("用户名已存在", response.getMessage());
}
```
**步骤2：运行测试（断言失败）**
```bash
mvn test -Dtest=UserApiTest
# 预期：测试失败（因为没有实现）
```
**步骤3：编写实现代码**
```java
// Controller
@PostMapping("/users")
public Response<UserResponse> createUser(@Valid @RequestBody CreateUserRequest request) {
return Response.success(userAppService.create(request));
}
// AppService
public UserResponse create(CreateUserRequest request) {
// 校验用户名唯一
if (userRepository.existsByUsername(request.getUsername())) {
throw new BusinessException(409, "用户名已存在");
}
// 加密密码
String encryptedPassword = passwordEncoder.encode(request.getPassword());
// 保存用户
User user = User.from(request, encryptedPassword);
userRepository.save(user);
// 发送验证邮件
emailService.sendVerificationEmail(user);
return UserResponse.from(user);
}
```
**步骤4：运行测试（通过）**
```bash
mvn test -Dtest=UserApiTest
# 预期：所有测试通过
```
**ByPass 权限**
- 定义：AI 在某些情况下可以跳过某些步骤
- 场景：
- 测试环境不可用
- 第三方服务不可用
- 紧急修复
- 控制：在 AGENTS.md 中定义 ByPass 规则
**Loop 的退出条件**
1. 所有 API 测试通过
2. 所有单元测试通过
3. 代码符合规范（Lint 通过）
4. 没有编译错误
### 实践建议
- Plan 阶段充分沟通：关闭所有开放性问题
- TDD 驱动：先写测试再写代码
- AI 自治运行：执行阶段无需人工介入
- 记录实现状态：方便复盘和优化
- ByPass 权限控制：紧急情况可以跳过某些步骤
---
## 本章小结
**开发实现的核心要点**：
1. 让 AI 听话：规则、规格、技能三要素
2. 构建上下文体系：区分过程方案和事实方案
3. 调用外部工具：MCP、Skills、CLI
4. 选择合适的工具：命令行类、AI IDE、增强插件
5. SDD 框架：BMAD、Spec Kit、OpenSpec、Kiro
6. 技术规格 DSL 驱动：领域模型、数据库、API、时序图、专题设计
7. 打样工程：让 AI 抄作业
8. 多任务同步开发：Git Worktree
9. 核心 Loop：Plan → TDD → 验证
**关键工具**：
- Claude Code、Cursor、Kiro
- MCP Server、Skills
- PlantUML、OpenAPI
- Git Worktree
**最佳实践**：
- AGENTS.md 作为宪法
- 区分 Plans（过程）和 Designs（事实）
- 使用 DSL 编写技术规格
- 建立打样工程
- TDD 驱动开发

1056
AI工程/团队级AI_Coding简明手册_逐页研究/03_测试验收_第20-25页.md Executable file
View File

File diff suppressed because it is too large Load Diff

491
AI工程/团队级AI_Coding简明手册_逐页研究/04_Agent_as_Code_第26-30页.md Executable file
View File

@@ -0,0 +1,491 @@
# 第26-30页：Agent as Code + 附录
> 章节：04 Agent as Code + 附录
> 核心问题：如何组织 AI 工程文件？如何让多个 AI 工具协同？
---
## 第26页：分隔页（04 Agent as Code）
### 原文内容
章节分隔页，标志进入"Agent as Code"部分
### 研究要点
- 这是4个核心问题中的第4个
- Agent as Code 是整个体系的基础设施
- 核心目标：让 AI 协作文件可版本化、可复用、可共享
---
## 第27页：AI 工程文件管理
### 原文内容
**核心思路**：使用 AGENTS.md 构建引用关系，让 Claude/OpenCode 等工具支持相关 Harness 文件
**目录结构**：
```
AGENTS.md ← 宪法
docs/
├── standards/ ← 标准规格
├── features/ ← 需求规格
├── plans/ ← 计划规格
├── designs/ ← 设计规格
└── others/ ← 其他
skills/ ← AI 技能
mcp/ ← MCP 配置
```
**工具配置**：
- `.claude/` - Claude Code 配置
- `.opencode/` - OpenCode 配置
- `.cursor/` - Cursor 配置
**实现方式**：通过软链接（symlink）让各工具读取同一份 AGENTS.md
### 深入解读
**什么是 Agent as Code？**
- 定义：将 AI 协作的所有文件以代码的方式管理
- 目标：可版本化、可复用、可共享
- 核心理念：AI 的行为由代码（配置文件）决定
**为什么需要 Agent as Code？**
- AI 工具配置分散：每个工具有自己的配置文件
- 难以复用：不同项目需要重复配置
- 难以协作：团队成员无法共享 AI 配置
- 难以追溯：AI 行为变更没有历史记录
**AGENTS.md 的作用**
- **宪法级约束**：定义 AI 的基本行为规则
- **统一入口**：所有 AI 工具都从这个文件开始
- **引用枢纽**：通过引用关系组织其他文件
**AGENTS.md 示例**：
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x, React 18
- 代码规范：阿里巴巴 Java 开发手册
# AI 行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含 created_at, updated_at 字段
3. API 接口必须使用 RESTful 风格
4. 敏感数据必须加密存储
# 目录结构
- src/main/java/com/example/project/controller
- src/main/java/com/example/project/service
- src/main/java/com/example/project/repository
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API 规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
```
**软链接实现**
**Linux/Mac**：
```bash
# 创建软链接
ln -s ../AGENTS.md .claude/AGENTS.md
ln -s ../AGENTS.md .opencode/AGENTS.md
ln -s ../AGENTS.md .cursor/AGENTS.md
```
**Windows**：
```cmd
# 创建软链接（需要管理员权限）
mklink .claude\AGENTS.md ..\AGENTS.md
mklink .opencode\AGENTS.md ..\AGENTS.md
mklink .cursor\AGENTS.md ..\AGENTS.md
```
**Git 管理**：
```bash
# 添加到 Git
git add AGENTS.md
git add .claude/AGENTS.md
git add .opencode/AGENTS.md
git add .cursor/AGENTS.md
# 提交
git commit -m "feat: add AGENTS.md for AI collaboration"
```
**Skills 目录**
- 定义：可复用的 AI 能力单元
- 组成：提示词、脚本、文档
- 示例：
```
skills/
├── commit-push/
│ ├── SKILL.md
│ └── commit.sh
├── deploy/
│ ├── SKILL.md
│ └── deploy.sh
└── test/
├── SKILL.md
└── test.sh
```
**MCP 配置**
- 定义：Model Context Protocol 配置
- 作用：让 AI 访问外部工具
- 示例：
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-sqlite"]
},
"filesystem": {
"command": "node",
"args": ["mcp-server-filesystem", "/path/to/dir"]
}
}
}
```
### 实践建议
- **使用 AGENTS.md 作为统一入口**：所有 AI 工具从这个文件开始
- **使用软链接**：让多个工具共享同一份配置
- **纳入 Git 管理**：配置可版本化、可追溯
- **建立 Skills 库**：沉淀常用的 AI 能力
- **使用 MCP**：让 AI 访问外部工具
---
## 第28页：分隔页（附录&参考资料）
### 原文内容
章节分隔页，标志进入"附录&参考资料"部分
### 研究要点
- 提供进一步学习的资源
- 包含实践心得和参考资料
---
## 第29页：关于 AI 编程实践的心得
### 原文内容
**两条核心心得**：
1. **放弃"开箱即用"的框架**
- 每个项目需要构建自己 Harness 工具和文档
- 没有放之四海而皆准的解决方案
- 需要根据项目特点定制
2. **"少量取用，大量实践"是更好的策略**
- 不要一开始就引入所有概念
- 先实践核心概念，再逐步扩展
- 实践出真知
### 深入解读
**为什么没有"开箱即用"的框架？**
**原因1：项目差异大**
- 技术栈不同：Java vs Python vs JavaScript
- 团队规模不同：个人 vs 小团队 vs 大团队
- 业务复杂度不同：简单 CRUD vs 复杂业务逻辑
- 合规要求不同：内部项目 vs 金融项目 vs 医疗项目
**原因2：AI 能力在快速演进**
- 模型能力不断提升
- 工具生态快速变化
- 最佳实践还在形成中
- 昨天的最佳实践可能今天已过时
**原因3：团队文化差异**
- 有的团队喜欢严格规范
- 有的团队喜欢灵活自由
- 有的团队重视文档
- 有的团队重视代码
**如何构建自己的 Harness？**
**步骤1：从 AGENTS.md 开始**
- 定义项目基本信息
- 定义 AI 行为规则
- 定义目录结构
**步骤2：建立文档体系**
- docs/standards/ - 标准规范
- docs/features/ - 需求规格
- docs/designs/ - 设计规格
- docs/plans/ - 计划规格
**步骤3：开发常用 Skills**
- commit-push - 提交和推送代码
- deploy - 部署到环境
- test - 运行测试
**步骤4：配置 MCP**
- 数据库访问
- 文件系统访问
- 外部 API 访问
**"少量取用，大量实践"的具体做法**
**第一阶段：基础配置（1-2周）**
- 建立 AGENTS.md
- 建立基本文档结构
- 配置一个 AI 工具（如 Claude Code）
**第二阶段：核心实践（2-4周）**
- 使用 AI 生成代码
- 使用 AI 进行 Code Review
- 使用 AI 编写测试
**第三阶段：扩展应用（1-2月）**
- 引入更多 AI 工具
- 开发更多 Skills
- 配置更多 MCP
**第四阶段：持续优化（持续）**
- 根据实践反馈优化配置
- 沉淀最佳实践
- 分享给团队
### 实践建议
- **不要追求完美**：先跑起来，再优化
- **小步快跑**：每次只引入一个新概念
- **记录实践**：记录什么有效，什么无效
- **分享经验**：与团队分享实践经验
- **持续学习**：关注 AI 编程领域的最新进展
---
## 第30页：参考资料
### 原文内容
**参考资料列表**：
1. [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
2. [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
3. [Anthropic: Harness Design for Long-running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps)
4. [从 Rule、Spec 到 Harness：AI Coding 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
5. [让 AI 乖乖听话的几个 Rules](https://mp.weixin.qq.com/s/FXNzk_y2Z2h8BVe62uEn_A)
6. [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
7. [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)
8. [attractor-guided-engineering-template](https://github.com/entropy-cloud/attractor-guided-engineering-template)
9. [OpenAI: Tools Computer Use](https://developers.openai.com/api/docs/guides/tools-computer-use)
### 深入解读
**资料分类**
**Harness Engineering 理论**：
1. OpenAI 的文章：介绍 Harness Engineering 的概念和实践
2. Martin Fowler 的文章：从软件工程角度阐述 Harness
3. Anthropic 的文章：针对长时间运行应用的 Harness 设计
**AI Coding 实践**：
4. 微信公众号文章：从 Rule 到 Spec 到 Harness 的渐进式路径
5. 微信公众号文章：让 AI 听话的 Rules 实践
**SDD 框架**：
6. Martin Fowler 的文章：对比 Kiro、spec-kit、Tessl 三个 SDD 框架
**开源项目**：
7. harness-engineering-in-ai-coding：Harness Engineering 实践项目
8. attractor-guided-engineering-template：引导式工程模版
**官方文档**：
9. OpenAI 官方文档：Computer Use 工具使用指南
**推荐阅读顺序**
**入门阶段**：
1. 先读第4、5篇微信公众号文章（中文，易理解）
2. 再读 OpenAI 的 Harness Engineering 文章
**进阶阶段**：
3. 读 Martin Fowler 的 Harness Engineering 文章
4. 读 Anthropic 的 Harness Design 文章
5. 读 SDD 框架对比文章
**实践阶段**：
6. 参考开源项目实践
7. 阅读官方文档
**关键概念解释**
**Harness Engineering**：
- 定义：为 AI 提供约束和工具的工程实践
- 目标：让 AI 在受控环境中高效工作
- 核心：约束体系 + 工具体系
**SDD（Spec-Driven Development）**：
- 定义：以规格文档为核心的开发方法
- 核心理念：Spec 是单一事实来源
- 代表框架：Kiro、spec-kit、OpenSpec、BMAD
**Rule/Spec/Harness 演进**：
- Rule：约束 AI 行为的规则
- Spec：结构化的需求描述
- Harness：完整的约束和工具体系
### 实践建议
- **循序渐进**：按照推荐阅读顺序学习
- **理论结合实践**：读完理论后动手实践
- **关注官方文档**：获取最新信息
- **参与社区**：关注开源项目和社区讨论
---
## 全文总结
### 核心框架
**团队级 AI Coding 的4个核心问题**：
1. **需求衔接**：如何编写 AI 能理解的需求？
2. **开发实现**：如何让 AI 生成高质量代码？
3. **测试验收**：如何自动化测试 AI 生成的代码？
4. **Agent as Code**：如何组织 AI 协作文件？
**解决方案概览**：
**需求衔接**：
- 使用 Markdown 编写需求规格
- 区分增量需求和存量需求
- 使用字段清单和业务规则
- 通过原型图传递 UI 设计
**开发实现**：
- 规则、规格、技能三要素
- 构建 AI 上下文体系（AGENTS.md + docs/）
- 区分过程方案（Plans）和事实方案（Designs）
- 使用 MCP/Skills/CLI 调用外部工具
- 选择合适的 AI 编程工具
- 使用 SDD 框架（BMAD/SpecKit/OpenSpec/Kiro）
- 使用 DSL 编写技术规格
- 建立打样工程
- 使用 Git Worktree 并行开发
- 核心 Loop：Plan → TDD → 验证
**测试验收**：
- 分层测试：Lint → Code Review → 单元测试 → API 测试 → E2E 测试
- AI 操作浏览器：Playwright MCP、Chrome DevTools MCP、Browser Use、Computer Use
- 生成 E2E 测试：Browser Use 探索 → Playwright 固化 → 截图视觉兜底
- 超级 Loop：在核心 Loop 基础上增加 E2E 测试验证
**Agent as Code**：
- 使用 AGENTS.md 作为统一入口
- 建立文档体系（standards/features/plans/designs）
- 开发 Skills 库
- 配置 MCP
- 使用软链接让多个工具共享配置
### 关键工具
**AI 编程工具**：
- Claude Code、Cursor、Kiro、Trae、OpenCode、Codex CLI
**SDD 框架**：
- BMAD、Spec Kit、OpenSpec、Kiro
**测试工具**：
- Playwright、Browser Use、Karate、RestAssured
**文档工具**：
- PlantUML、OpenAPI、Markdown
**协作工具**：
- Git、GitHub、GitLab
### 最佳实践
**需求阶段**：
- 使用 Markdown 编写需求
- 区分增量和存量需求
- 使用字段清单
- 通过原型图传递 UI
**开发阶段**：
- 建立 AGENTS.md
- 区分 Plans 和 Designs
- 使用 DSL 编写技术规格
- 建立打样工程
- TDD 驱动开发
**测试阶段**：
- 分层测试
- 先用 Browser Use 探索，再固化到 Playwright
- 使用稳定的选择器
- 关键页面截图验证
**协作阶段**：
- 使用 AGENTS.md 作为统一入口
- 使用软链接共享配置
- 纳入 Git 管理
- 建立 Skills 库
### 学习路径
**入门（1-2周）**：
1. 理解 AI 编程的5个发展阶段
2. 建立 AGENTS.md
3. 使用一个 AI 工具（如 Claude Code）
4. 实践核心 Loop
**进阶（1-2月）**：
1. 学习 SDD 框架
2. 使用 DSL 编写技术规格
3. 建立打样工程
4. 实践分层测试
5. 使用 Playwright 进行 E2E 测试
**高级（持续）**：
1. 构建完整的 Harness 体系
2. 开发自定义 Skills
3. 配置 MCP 访问外部工具
4. 优化 AI 工作流
5. 分享实践经验
### 关键洞察
1. **AI 编程不是银弹**：需要工程化的方法来驾驭
2. **上下文是关键**：AI 需要清晰的上下文才能生成高质量代码
3. **测试是保障**：自动化测试是 AI 生成代码质量的保障
4. **实践出真知**：没有放之四海而皆准的方案，需要根据项目特点定制
5. **持续演进**：AI 能力在快速提升，方法也需要持续演进
---
## 附录：术语表
| 术语 | 英文 | 定义 |
|------|------|------|
| AI 编程 | AI Coding | 使用 AI 辅助或自动化进行软件开发 |
| Harness | Harness | 为 AI 提供约束和工具的工程实践 |
| SDD | Spec-Driven Development | 以规格文档为核心的开发方法 |
| MCP | Model Context Protocol | AI 与外部系统通信的标准协议 |
| AGENTS.md | AGENTS.md | AI 协作的宪法级配置文件 |
| Plan | Plan | AI 执行任务的规划文档 |
| Spec | Specification | 结构化的需求描述 |
| Rule | Rule | 约束 AI 行为的规则 |
| Skill | Skill | 可复用的 AI 能力单元 |
| Loop | Loop | AI 自治运行的开发循环 |
| TDD | Test-Driven Development | 测试驱动开发 |
| E2E | End-to-End | 端到端测试 |
| DSL | Domain Specific Language | 领域特定语言 |
| Worktree | Git Worktree | Git 的多工作区功能 |
| Browser Use | Browser Use | AI 操作浏览器的框架 |
| Playwright | Playwright | 浏览器自动化测试框架 |
| BMAD | Business Model Architecture Design | 企业级 SDD 框架 |
| OpenSpec | OpenSpec | 轻量级 SDD 框架 |
| Kiro | Kiro | AWS 推出的 AI IDE 和 SDD 框架 |
---
**文档信息**：
- 原文：团队级 AI Coding 简明手册 v0.2
- 研究日期：2026-06-20
- 研究范围：第1-30页（全文）
- 归档位置：/obsidian/AI工程/团队级AI_Coding简明手册_逐页研究/

323
AI工程/团队级AI_Coding简明手册v0.2.md Executable file
View File

@@ -0,0 +1,323 @@
# 团队级 AI Coding 简明手册 v0.2
> 来源：系统设计研讨会分享 PPT（2026.06.18），版权归分享人所有
> 归档日期：2026-06-20
---
## 一、AI 编程思想发展过程
| 阶段 | 特征 | 模式 |
|------|------|------|
| **原始阶段** | 基于本能的 AI 编程，手动复制代码或通过问答交互 | 半自动，有人值守 |
| **Rule 约束** | 经验规则显化（如 RIPER-5），通过持续对话输入需求 | 半自动 |
| **规格驱动** | 需求结构化表达，基于规格流转（如 OpenSpec），文件进文件出 | 全自动过渡 |
| **Loop Engineering** | 可反馈闭环：AI 根据验收规则自动循环 + 测试套件 | 全自动 |
| **Harness 驾驭工程** | 纳入工程治理体系，提供约束体系 + 外部接口 | 全自动，Plan 后无人值守 |
> 每一次思想的变更是对前者的重新表述而非推翻
---
## 二、AI 赋能软件开发实现地图
```
需求分析 → 需求文档/原型图 → 技术方案设计 → 代码框架+打样工程
↓ ↓ ↓ ↓
人+AI 人+AI 人+AI 人+AI
↓ ↓ ↓ ↓
AI代码编写 → 单元测试/调试 → E2E测试 → Code Review → 提测部署
↓ ↓ ↓ ↓ ↓
机 机+人 机+人 机+人 机+人
```
**核心 Loop**：研发自测阶段，AI 自治运行
**全流程超级 Loop**：从需求到部署的完整闭环
---
## 三、四大核心问题
### 01 需求衔接
- 如何编写 AI 能理解的需求？
- 使用什么格式？如何组织需求规格？
- 如何传递原型图？需求模版长什么样？
### 02 开发实现
- 如何让 AI 理解上下文且按要求执行？
- 如何调用外部工具？生成一致的代码？
- 如何多任务同步开发？
### 03 测试验收
- AI 编程需要什么测试策略？
- 如何让 AI 操作浏览器？
- 如何管理测试用例？
### 04 Agent as Code
- 如何把和 AI 协作的文件在代码仓库中合理组织？
- 构建 AI 更友好的环境
---
## 四、需求规格编写
### 关键要素
- **模块切分**（增量/存量）
- **字段清单**
- **原型链接**
- **业务规则**
### 编写原则
1. 先写业务背景，再切模块。**一个模块 = 一个文档**
2. 分解为增量需求和存量需求：
- **增量需求** — 全新功能，需新建模块
- **存量修改** — 对已有功能做变更
3. 字段定义需完整：类型、必填、默认值、描述、校验规则、UI展示、数据来源
4. 业务规则条目化 + 正交分解，每条规则独立可测
> **Tips**: BA 也应该工作在代码仓库中，让 AI 基于当前系统事实构建新需求
### 原型图设计
- **设计工具输出**：Figma/Stitch URL 嵌入需求文档
- **HTML+CSS 输出**：可交互原型提交到代码仓库
- **Design.md**：约束 AI 生成的前端风格，确保与项目组件库一致
---
## 五、开发实现
### 让 AI 听话的三要素
| 要素 | 说明 | 示例 |
|------|------|------|
| **规则 Rules** | 约束 AI 行为边界 | Java 代码风格、命名规范 |
| **规格 Specification** | 结构化需求，甚至用 DSL 描述 | 用户故事 + 验收标准 |
| **技能 Skill** | 打包提示词/脚本/模版扩展能力 | Commit & Push Skill |
### 构建 AI 上下文体系（详见下方重点章节）
### 让 AI 调用外部工具的三种方式
1. **CLI Commands** — 最直接，AI 生成命令并执行
2. **MCP** — 标准协议，统一接入数据库/API/文件系统
3. **Skills** — 脚本封装，触发词驱动
### AI 编程工具选择
- **命令行类**：Claude Code、Codex CLI、OpenCode
- **AI IDE**：Cursor、Kiro、Trae
- **增强插件**：Superpower、oh-my-opencode、oh-my-codex
### SDD 框架对比
| 维度 | BMAD | Spec Kit | OpenSpec | Kiro |
|------|------|----------|----------|------|
| 定位 | 企业级 SDD 操作系统 | 工程化 Spec 工作流 | 轻量 Spec 层 | IDE 原生 SDD |
| Spec 粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
### 技术规格编写（DSL 驱动）
| 模块 | 标准 | 格式 | 约束 |
|------|------|------|------|
| 领域模型 | PlantUML/Smart Domain | .puml | 必须表达实体关系 |
| 数据库 | SQL DDL/DBML | .sql | 必须可执行 |
| API | OpenAPI 3.x | .yaml/.json | 必须定义 schema |
| 时序图 | PlantUML | .puml | 必须反映真实调用链 |
| 专题设计 | Markdown | .md | 只写策略与规则 |
### 打样工程：让 AI 抄作业
- 原则：约定大于配置、编排逻辑和原子能力分离、操作者和被操作对象分离
- 简单 CRUD：Controller + Command → AppService → Repository → Response
- 复杂 CRUD：Controller + Command → AppService → DomainService → Repository → Response
- 复杂查询：Controller + Query → AppService → QueryPO → Response
### 多任务同步开发
使用 `git worktree` 同时把多个分支映射到不同文件夹：
```bash
git worktree add -b feature-payment ../feature-payment
```
---
## 六、⭐ 过程方案 vs 事实方案（重点）
### 核心理念
> 使用完整的文档来描述上下文和约束体系，**区分过程方案和事实方案，减少维护成本**。
### 文档分层体系
```
AGENTS.md ← 宪法级约束
docs/
├── standards/ ← 标准规格（架构/命名/API/安全规范）
├── features/ ← 需求规格（产品/BA维护）
├── designs/ ← 设计规格（DB/表等 Source of Truth） ⬅ 事实方案
├── plans/ ← 计划规格（每轮任务实现方案） ⬅ 过程方案
└── others/ ← 架构决策、Release、测试用例等
```
### 过程方案（Plans）
**定义**：每一轮任务的实现方案、Tasking、工作状态。
**特征**：
- **临时性**：每次创建新文件，用完即弃
- **不维护**：细微修改不再更新旧文件
- **可追溯**：保留历史决策轨迹，方便复盘
- **增量追加**：`追加: 每次创建一个新的文件`
**示例**：
```
docs/plans/
├── plan-2026-06-01-user-auth.md # 第1轮
├── plan-2026-06-05-user-auth-v2.md # 第2轮迭代
├── plan-2026-06-10-payment-flow.md # 新任务
└── plan-2026-06-15-order-module.md # 新任务
```
**为什么这样设计**：
1. 避免反复修改同一文件导致的 Git 冲突
2. 保留完整决策轨迹，AI 和人都能回溯
3. AI 执行完可以"丢弃"，不污染长期文档
4. 降低维护成本——过程方案不需要维护
**在 Plan/Go 模式中的角色**：
- Plan 阶段产出 → 锁定上下文到 Plan 中
- 记录实现状态，让任务可以分批完成或重试
- 关闭所有开放性问题后再进入执行
### 事实方案（Designs / Standards / Features）
**定义**：反映系统**当前真实状态**的文档，是 Source of Truth。
**特征**：
- **长期有效**：稳定的、持续维护的
- **最终态更新**：`变更: 每次以最终态更新`
- **事实依据**：作为下一次 Plan 的起点
- **必须一致**：与实际代码/系统保持同步
**示例**：
```
docs/designs/
├── database-schema.md # 当前数据库表结构（最终态）
├── api-endpoints.md # 当前 API 定义（最终态）
└── architecture.md # 当前架构图（最终态）
docs/standards/
├── coding-style.md # 编码规范
└── security-guidelines.md # 安全规范
docs/features/
├── user-management.md # 用户管理需求（当前版本）
└── order-system.md # 订单系统需求（当前版本）
```
**为什么这样设计**：
1. AI 每次 Plan 前读取这些文档，获得"当前真相"
2. 避免 AI 基于过时信息做决策
3. 只维护一份最终态，减少维护成本
4. 是团队共识的载体
### 规格流转图
```
起点 Features（需求规格）
↓
Standards（约束规范）
↓
TDD 驱动 → 测试 + 代码
↓
事实方案 Designs（更新最终态） ← 变更：覆盖更新
↓
过程方案 Plans（执行记录） ← 追加：新建文件
↓
回到起点 Features（验收）
```
### 实践建议
1. **AGENTS.md 作为宪法**：定义 AI 行为边界和基本原则
2. **区分"打算做"和"已做完"**：Plans 是意图，Designs 是事实
3. **Plan 阶段尽可能锁定上下文**：关闭所有开放性问题
4. **Plan 中记录实现状态**：让任务可以分批完成或重试
5. **给出确定性验收方式**：如通过所有 API 测试，让 AI 建立自我修复标准
---
## 七、测试验收
### AI 辅助测试策略
| 测试类型 | 工具 | 负责人 |
|----------|------|--------|
| Lint 代码扫描 | TS Lint/SonarQube | 程序 |
| Code Review | Copilot/Claude Code/CodeRabbit | 开发者 + AI |
| 单元测试 | JUnit/pytest/Jest | 开发者 + AI |
| API 测试 | Karate/RestAssured | QA + 后端 + AI |
| E2E 测试 | Playwright | QA + 自动化 + AI |
### AI 操作浏览器方案对比
| 方案 | 原理 | 速度 | Token 消耗 | 跨应用 |
|------|------|------|-----------|--------|
| OpenWright (Playwright MCP) | Accessibility Tree | 快 ~0.9s | 高 | 仅浏览器 |
| Chrome DevTools MCP | CDP 协议 | 中 ~1.2s | 中 | 仅浏览器 |
| Browser Use | DOM + 截图双模 | 中 ~1.5s | 极低 | 仅浏览器 |
| Computer Use | 视觉识别+坐标 | 慢 0.8-2s | 高 | 全桌面 |
### E2E 测试生成策略
1. **Browser Use 探索**：AI 自主遍历页面，记录操作轨迹（消耗 Token）
2. **Playwright 固化**：转为测试脚本加入 CI（零 Token 可重复运行）
3. **截图视觉兜底**：覆盖布局偏移、动效、Canvas 等场景
### 核心 Loop（研发自测）
```
Plan 模式装载需求规格 → Plan 确认 → 编写 API 测试 → 编写实现
→ 运行测试 → 通过？→ 退出循环
↓ 否
修复重试
```
### 超级 Loop（E2E Loop）
在核心 Loop 基础上增加：
- 编写测试用例（docs/test-cases）
- 浏览器调试（Playwright 确认视觉效果）
- 编写 E2E 测试覆盖本轮需求
---
## 八、Agent as Code
### AI 工程文件管理
```
AGENTS.md ← 宪法，构建引用关系
docs/
├── .ai/ ← AI 配置
├── standards/ ← 标准规格
├── features/ ← 需求规格
├── designs/ ← 设计规格
├── plans/ ← 计划规格
├── skills/ ← AI 技能
└── mcp/ ← MCP 配置
.claude / .opencode / .cursor → 软链到 AGENTS.md
```
---
## 九、实践心得
> - 放弃"开箱即用"的框架，每个项目需要构建自己的 Harness 工具和文档
> - "少量取用，大量实践"是更好的策略
---
## 参考资料
- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/)
- [Harness Engineering - Martin Fowler](https://martinfowler.com/articles/harness-engineering.html)
- [Harness Design for Long-running Apps - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)
- [从 Rule、Spec 到 Harness 的渐进式建设路径](https://mp.weixin.qq.com/s/UCh2bPzMZjNBMBCCJysuNw)
- [Understanding SDD: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
- [harness-engineering-in-ai-coding](https://github.com/2361485765/harness-engineering-in-ai-coding)

174
AI工程/概念/AGENTS.md.md Executable file
View File

@@ -0,0 +1,174 @@
# AGENTS.md
> 相关：[[Agent_as_Code]]、[[上下文体系]]、[[Harness工程]]
## 定义
**AGENTS.md**是AI协作的宪法级配置文件，定义AI的基本行为规则，所有AI工具都从这个文件开始。
**核心思想**：AGENTS.md是AI的"宪法"，约束AI的行为边界。
## 核心特征
### 1. 宪法级
- 最高优先级
- 所有AI工具都读取
- 定义基本行为规则
### 2. 统一入口
- AI从这个文件开始
- 引用其他文档
- 形成完整的上下文
### 3. 可版本化
- 纳入Git管理
- 变更有历史记录
- 可回滚
## 内容结构
### 基本信息
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x, React 18
- 代码规范：阿里巴巴Java开发手册
```
### AI行为规则
```markdown
# AI行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含created_at, updated_at字段
3. API接口必须使用RESTful风格
4. 敏感数据必须加密存储
```
### 目录结构
```markdown
# 目录结构
- src/main/java/com/example/project/controller
- src/main/java/com/example/project/service
- src/main/java/com/example/project/repository
```
### 引用文件
```markdown
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
```
## 完整示例
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x, React 18
- 代码规范：阿里巴巴Java开发手册
# AI行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含created_at, updated_at字段
3. API接口必须使用RESTful风格
4. 敏感数据必须加密存储
5. 所有方法必须有注释
6. 所有API必须有单元测试
# 目录结构
- src/main/java/com/example/project/controller
- src/main/java/com/example/project/service
- src/main/java/com/example/project/repository
- src/main/java/com/example/project/domain
- src/main/java/com/example/project/infrastructure
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
- 安全规范：./docs/standards/security.md
# 开发流程
1. Plan阶段：创建Plan文档，等待确认
2. 执行阶段：按照Plan实现代码
3. 验证阶段：运行测试，确保通过
# 测试要求
- 单元测试覆盖率 > 80%
- 所有API必须有集成测试
- 关键流程必须有E2E测试
```
## 配置位置
### 项目根目录
```
项目根目录/
├── AGENTS.md # 宪法级配置
├── .claude/
│ └── AGENTS.md -> ../AGENTS.md # 软链接
├── .opencode/
│ └── AGENTS.md -> ../AGENTS.md # 软链接
└── .cursor/
└── AGENTS.md -> ../AGENTS.md # 软链接
```
### 软链接实现
```bash
# Linux/Mac
ln -s ../AGENTS.md .claude/AGENTS.md
ln -s ../AGENTS.md .opencode/AGENTS.md
ln -s ../AGENTS.md .cursor/AGENTS.md
# Windows
mklink .claude\AGENTS.md ..\AGENTS.md
mklink .opencode\AGENTS.md ..\AGENTS.md
mklink .cursor\AGENTS.md ..\AGENTS.md
```
## Git管理
```bash
# 添加到Git
git add AGENTS.md
git add .claude/AGENTS.md
git add .opencode/AGENTS.md
git add .cursor/AGENTS.md
# 提交
git commit -m "feat: add AGENTS.md for AI collaboration"
```
## 适用场景
- **团队协作**：多个开发者共享AI配置
- **多项目**：在多个项目间复用配置
- **持续迭代**：配置需要持续演进
- **知识沉淀**：最佳实践需要沉淀
## 优势
- **统一入口**：所有AI工具从这个文件开始
- **一致性**：所有AI工具行为一致
- **可追溯**：配置变更有历史记录
- **易维护**：修改一处，多处生效
## 挑战
- **初始成本**：需要建立完整的配置
- **维护成本**：需要持续维护配置
- **学习曲线**：团队需要理解配置
## 最佳实践
1. **从核心规则开始**：先定义最重要的规则
2. **逐步扩展**：根据实践逐步添加配置
3. **定期Review**：定期审查和优化配置
4. **团队共享**：将配置纳入团队知识管理
## 相关概念
- [[Agent_as_Code]]：AGENTS.md是Agent as Code的核心文件
- [[上下文体系]]：AGENTS.md是上下文体系的宪法级文件
- [[Harness工程]]：AGENTS.md是Harness的组成部分

67
AI工程/概念/AI编程演进阶段.md Executable file
View File

@@ -0,0 +1,67 @@
# AI 编程演进阶段
> 相关：[[团队级AI_Coding简明手册v0.2]]、[[Harness工程]]、[[Rule约束]]、[[规格驱动开发]]、[[Loop工程]]
## 概述
AI 编程从简单的手动复制粘贴，逐步演进到工程化的自动化开发体系。
## 5 个阶段
### 阶段1：原始阶段（本能驱动）
- **特征**：手动从浏览器中复制 AI 的代码，通过问答和 AI IDE 交互
- **方式**：人工复制粘贴，逐行审查
- **效率**：低，依赖人工
- **适用**：个人学习、简单脚本
### 阶段2：Rule 约束（经验规则显化）
- **特征**：定义 AI 在不同工作模式下的处理方式，如 RIPER-5
- **方式**：通过 Rules 文件约束 AI 行为
- **效率**：中等，需要持续对话输入需求
- **适用**：个人项目、小团队
### 阶段3：规格驱动（需求结构化表达）
- **特征**：基于规格流转的开发方式，如 OpenSpec 框架
- **方式**：文件进、文件出，结构化需求文档
- **效率**：较高，AI 可理解完整上下文
- **适用**：中型项目、团队协作
### 阶段4：Loop 工程（闭环自动化）
- **特征**：让 AI 能根据验收规则自动循环，构建测试套件
- **方式**：TDD 驱动，AI 自治运行，自动修复
- **效率**：高，半自动有人值守
- **适用**：复杂项目、持续集成
### 阶段5：Harness 驾驭工程（工程治理）
- **特征**：把 AI 纳入工程治理体系，提供约束体系和外部接口
- **方式**：完整的 Harness 体系，全自动 Plan 后无人值守
- **效率**：最高，全自动无人值守
- **适用**：企业级项目、大规模团队
## 演进路径
```
原始 → Rule → 规格驱动 → Loop → Harness
手动 规则 文档 自动 治理
低效 中效 高效 自动 全自动
```
## 关键转变
1. **从人工到自动**：减少人工干预
2. **从对话到文档**：从口头需求到结构化规格
3. **从单次到循环**：从一次性生成到持续迭代
4. **从自由到约束**：从无约束到工程化治理
## 实践建议
- **小团队**：从 Rule 约束开始，逐步引入规格驱动
- **中型团队**：采用规格驱动 + Loop 工程
- **大型团队**：构建完整的 Harness 体系
## 相关概念
- [[Harness工程]]
- [[核心Loop]]
- [[规格驱动开发]]
- [[Agent_as_Code]]

131
AI工程/概念/Agent_as_Code.md Executable file
View File

@@ -0,0 +1,131 @@
# Agent as Code
> 相关：[[Harness工程]]、[[AGENTS.md]]、[[上下文体系]]、[[Skills]]
## 定义
**Agent as Code**是将AI协作的所有文件以代码的方式管理的理念，实现可版本化、可复用、可共享。
**核心思想**：AI的行为由代码（配置文件）决定，而不是由人的临时提示决定。
## 核心特征
### 1. 可版本化
- 所有配置纳入Git管理
- 变更有历史记录
- 可回滚到历史版本
### 2. 可复用
- 配置可在项目间复用
- Skills可在团队间共享
- 最佳实践可沉淀
### 3. 可共享
- 团队成员共享AI配置
- 新成员快速上手
- 统一团队AI行为
## 核心文件
### AGENTS.md（宪法级）
```markdown
# 项目信息
- 项目名称：XXX
- 技术栈：Java 17, Spring Boot 3.x
# AI行为规则
1. 代码必须符合规范
2. 数据库表必须包含时间戳字段
3. API必须使用RESTful风格
```
### Skills目录
```
skills/
├── commit-push/
│ ├── SKILL.md
│ └── commit.sh
├── deploy/
│ ├── SKILL.md
│ └── deploy.sh
```
### MCP配置
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-sqlite"]
}
}
}
```
## 实现方式
### 软链接共享配置
```bash
# 让多个AI工具共享AGENTS.md
ln -s ../AGENTS.md .claude/AGENTS.md
ln -s ../AGENTS.md .opencode/AGENTS.md
ln -s ../AGENTS.md .cursor/AGENTS.md
```
### Git管理
```bash
git add AGENTS.md
git add .claude/AGENTS.md
git commit -m "feat: add AGENTS.md for AI collaboration"
```
## 目录结构
```
项目根目录/
├── AGENTS.md # 宪法级配置
├── docs/
│ ├── standards/ # 标准规范
│ ├── features/ # 需求规格
│ ├── designs/ # 设计规格
│ └── plans/ # 计划规格
├── skills/ # AI技能
├── mcp/ # MCP配置
├── .claude/ # Claude Code配置
├── .opencode/ # OpenCode配置
└── .cursor/ # Cursor配置
```
## 适用场景
- **团队协作**：多个开发者共享AI配置
- **多项目**：在多个项目间复用配置
- **持续迭代**：配置需要持续演进
- **知识沉淀**：最佳实践需要沉淀
## 优势
- **一致性**：所有AI工具行为一致
- **可追溯**：配置变更有历史记录
- **可复用**：Skills和配置可复用
- **易维护**：修改一处，多处生效
## 挑战
- **初始成本**：需要建立完整的文档体系
- **维护成本**：需要持续维护配置
- **学习曲线**：团队需要理解Agent as Code理念
## 最佳实践
1. **从AGENTS.md开始**：先定义最基本的规则
2. **逐步扩展**：根据实践逐步添加配置
3. **定期Review**：定期审查和优化配置
4. **团队共享**：将配置纳入团队知识管理
## 相关概念
- [[Harness工程]]：Agent as Code是Harness的技术实现
- [[AGENTS.md]]：Agent as Code的核心文件
- [[上下文体系]]：Agent as Code的文档组织
- [[Skills]]：Agent as Code的能力单元

74
AI工程/概念/BMAD.md Executable file
View File

@@ -0,0 +1,74 @@
# BMAD
> 相关：[[规格驱动开发]]、[[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]
## 定义
**BMAD**（Business Model Architecture Design）是企业级SDD框架，提供强治理和多Agent编排能力。
**核心思想**：Spec = 治理体系 + 多Agent编排，适合大型系统和多团队协作。
## 核心特征
### 1. 企业级定位
- 强治理体系
- 多Agent编排
- 全生命周期管理
### 2. 大粒度Spec
- 系统级/模块级规格
- 完整的架构设计
- 详细的实现方案
### 3. 强流程控制
- 阶段+审批+Agent
- 严格的变更控制
- 完整的审计轨迹
## 与其他SDD框架对比
| 维度 | BMAD | [[Spec_Kit]] | [[OpenSpec]] | [[Kiro]] |
|------|------|--------------|--------------|----------|
| 方法定位 | 企业级SDD操作系统 | 工程化Spec工作流 | 轻量Spec层 | IDE原生SDD |
| 核心理念 | Spec = 治理体系 + 多Agent编排 | Spec = 开发入口 + Git生命周期 | Spec = 变更单元（持续演化） | Spec = 可执行源（代码与测试） |
| Spec生命周期 | 全生命周期 | 与分支绑定（短生命周期） | 长期存在（持续演化） | 持续驱动 |
| Spec粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 可执行能力 | 通过流程驱动 | 驱动开发流程 | 类Prompt | 可生成代码+测试并自动校验 |
| 流程控制 | 强（阶段+审批+Agent） | 中（Plan→Spec→Tasks） | 弱（自由演化） | 强（闭环） |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 与代码关系 | 间接 | 半耦合 | 弱耦合 | 强耦合 |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **大型系统**：需要完整的架构设计
- **多团队协作**：需要强治理体系
- **企业级项目**：需要严格的变更控制
- **合规要求高**：需要完整的审计轨迹
## 优势
- **强治理**：完整的治理体系
- **多Agent编排**：支持多个AI Agent协同
- **全生命周期**：覆盖从需求到交付的全流程
- **失控风险低**：严格的流程控制
## 挑战
- **学习曲线陡峭**：需要理解完整的框架
- **初始成本高**：需要建立完整的治理体系
- **灵活性低**：流程严格，不够灵活
- **维护成本高**：需要持续维护治理体系
## 最佳实践
1. **适合大型团队**：小型团队不建议使用
2. **逐步引入**：不要一开始就引入所有概念
3. **培训团队**：团队成员需要充分培训
4. **持续优化**：根据实践持续优化流程
## 相关概念
- [[规格驱动开发]]：BMAD是SDD框架之一
- [[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]：其他SDD框架

144
AI工程/概念/Browser_Use.md Executable file
View File

@@ -0,0 +1,144 @@
# Browser Use
> 相关：[[测试策略金字塔]]、[[Playwright]]、[[Computer_Use]]、[[MCP]]
## 定义
**Browser Use**是一个Python框架，让AI可以自主操作浏览器，支持DOM和截图双模式。
**核心思想**：AI自主决策循环，支持DOM和截图双模，Token消耗极低。
## 核心特征
### 1. Python框架
- 基于Playwright
- AI自主决策循环
- 易于集成到Python项目
### 2. 双模式支持
- DOM模式：结构化DOM快照
- 截图模式：视觉理解
- 可以混合使用
### 3. 极低Token消耗
- CLI模式~75 tok/步
- 比其他方案低很多
- 成本敏感项目首选
## 原理
```
AI决策
↓
Browser Use框架
↓
Playwright操作浏览器
↓
获取DOM/截图
↓
AI分析结果
↓
下一步操作
```
## 与其他方案对比
| 维度 | Browser Use | Playwright MCP | Chrome DevTools MCP | Computer Use |
|------|-------------|----------------|---------------------|--------------|
| 原理 | Python框架 + Playwright，AI自主决策循环 | 通过Playwright访问浏览器Accessibility Tree | 通过Chrome DevTools Protocol直接与浏览器引擎通信 | AI截取屏幕截图 → 视觉识别元素 → 输出坐标/按键操作 |
| 抽象层 | DOM + 截图 视觉 + 结构化混合 | Accessibility Tree 结构化DOM快照 | CDP Protocol DevTools协议原生 | 截图 + 坐标 OS级视觉理解 |
| 速度 | 中 ~1.5s/步 | 快 ~0.9s/步 | 中 ~1.2s/步 | 慢 0.8-2s/步 |
| Token消耗 | 极低 CLI模式 ~75 tok/步 | 高 截图+结构全传 | 中 按需取数据 | 高 截图编码开销大 |
| JS重页面 | 中 — 视觉兜底 | 中 — DOM可读 | 中 — CDP可取 | 高 — 视觉理解 |
| 跨应用操作 | 仅浏览器 | 仅浏览器 | 仅浏览器 | 全桌面 |
## 使用示例
### 基本使用
```python
from browser_use import Agent
agent = Agent(
task="Go to Reddit, search for 'r/LocalLLaMA' and click on the first post",
llm=llm
)
result = await agent.run()
print(result)
```
### 原始指令
```python
agent = Agent(
task="""
1. 打开 /login 页面
2. 输入用户名 test@example.com
3. 输入密码 123456
4. 点击登录按钮
5. 验证跳转到 /dashboard
6. 验证页面显示 "Welcome"
""",
llm=llm
)
```
### AI探索后生成的Playwright脚本雏形
```typescript
test('login flow', async ({ page }) => {
await page.goto('/login');
await page.fill('[name="email"]', 'test@example.com');
await page.fill('[name="password"]', '123456');
await page.click('button[type="submit"]');
await expect(page).toHaveURL('/dashboard');
await expect(page.locator('text=Welcome')).toBeVisible();
});
```
## E2E测试生成三步法
### Step 1: Browser Use探索
- AI自主遍历页面，记录操作轨迹、选择器、页面状态
- 输出Playwright脚本雏形
- 消耗Token
### Step 2: Playwright E2E固化
- 将探索结果转为Playwright测试脚本
- 加入CI，零Token可重复运行
### Step 3: 截图视觉兜底
- Playwright覆盖不到的视觉场景（布局、动效、图表）
- 重回截图判断
## 适用场景
- **Token成本敏感**：极低Token消耗
- **复杂网页自动化**：需要视觉理解
- **E2E测试探索**：快速生成测试脚本雏形
- **网页数据抓取**：自动化数据提取
## 优势
- **Token消耗极低**：CLI模式~75 tok/步
- **AI自主决策**：无需手动编写脚本
- **支持视觉理解**：可以处理复杂视觉场景
- **易于集成**：Python框架，易于集成到项目
## 挑战
- **仅限浏览器**：不能操作其他应用
- **依赖Python**：需要Python生态
- **学习成本**：需要了解框架使用
## 最佳实践
1. **Token成本敏感首选**：极低Token消耗
2. **先用Browser Use探索**：快速生成测试脚本雏形
3. **人工审查后固化**：优化选择器，加入CI/CD
4. **关键页面截图验证**：视觉回归测试
## 相关概念
- [[测试策略金字塔]]：Browser Use是E2E测试的工具
- [[Playwright]]：Browser Use基于Playwright
- [[Computer_Use]]：Browser Use和Computer Use的对比
- [[MCP]]：Browser Use和MCP的对比

73
AI工程/概念/Claude_Code.md Executable file
View File

@@ -0,0 +1,73 @@
# Claude Code
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Cursor]]、[[Kiro]]、[[Trae]]
## 定义
**Claude Code**是Anthropic推出的AI编程工具，基于Claude模型，提供强大的推理能力和长上下文支持。
**核心思想**：强大的推理能力，支持长上下文，内置MCP支持，Loop模式。
## 核心特征
### 1. 强大的推理能力
- 基于Claude模型
- 强大的逻辑推理
- 适合复杂逻辑
### 2. 长上下文支持
- 支持超长上下文
- 可以理解完整项目
- 适合大型项目
### 3. 内置MCP支持
- 原生支持MCP协议
- 可以访问外部工具
- 即插即用
### 4. Loop模式
- 支持自治运行
- 自动修复问题
- 持续迭代
## 与其他AI工具对比
| 工具 | 类型 | 价格 | AI模型 | 适用场景 |
|------|------|------|--------|---------|
| Claude Code | CLI | 按Token | Claude | 复杂逻辑 |
| [[Cursor]] | IDE | $20/月 | 多模型 | 日常开发 |
| [[Kiro]] | IDE | 免费+付费 | Claude | AWS项目 |
| [[Trae]] | IDE | 免费+付费 | 豆包 | 中文项目 |
## 适用场景
- **复杂逻辑**：需要强大的推理能力
- **大型项目**：需要长上下文支持
- **架构设计**：需要理解完整架构
- **问题排查**：需要深入分析问题
## 优势
- **推理能力强**：适合复杂逻辑
- **长上下文**：可以理解完整项目
- **MCP支持**：可以访问外部工具
- **Loop模式**：支持自治运行
## 挑战
- **按Token计费**：成本可能较高
- **CLI界面**：不如IDE直观
- **学习曲线**：需要了解CLI使用
## 最佳实践
1. **复杂逻辑首选**：推理能力最强
2. **长上下文利用**：充分利用长上下文能力
3. **MCP配置**：配置必要的MCP Server
4. **Loop模式**：充分利用Loop模式
## 相关概念
- [[Harness工程]]：Claude Code是Harness的工具之一
- [[Agent_as_Code]]：Claude Code支持Agent as Code
- [[Cursor]]、[[Kiro]]、[[Trae]]：其他AI编程工具

120
AI工程/概念/Computer_Use.md Executable file
View File

@@ -0,0 +1,120 @@
# Computer Use
> 相关：[[测试策略金字塔]]、[[Browser_Use]]、[[Playwright]]、[[MCP]]
## 定义
**Computer Use**是Anthropic推出的OS级视觉操作方案，让AI可以操作任何桌面应用。
**核心思想**：AI截取屏幕截图 → 视觉识别元素 → 输出坐标/按键操作 → 沙箱执行。
## 核心特征
### 1. OS级通用
- 可以操作任何应用
- 不限于浏览器
- 桌面级操作
### 2. 视觉理解
- 基于截图识别元素
- 输出坐标和按键
- 强大的视觉理解能力
### 3. 沙箱执行
- 在沙箱环境中执行
- 安全性高
- 可控制
## 原理
```
AI截取屏幕截图
↓
视觉识别元素
↓
输出坐标/按键操作
↓
沙箱执行
↓
返回结果
```
## 与其他方案对比
| 维度 | Computer Use | Playwright MCP | Chrome DevTools MCP | Browser Use |
|------|--------------|----------------|---------------------|-------------|
| 原理 | AI截取屏幕截图 → 视觉识别元素 → 输出坐标/按键操作 | 通过Playwright访问浏览器Accessibility Tree | 通过Chrome DevTools Protocol直接与浏览器引擎通信 | Python框架 + Playwright，AI自主决策循环 |
| 抽象层 | 截图 + 坐标 OS级视觉理解 | Accessibility Tree 结构化DOM快照 | CDP Protocol DevTools协议原生 | DOM + 截图 视觉 + 结构化混合 |
| 速度 | 慢 0.8-2s/步 | 快 ~0.9s/步 | 中 ~1.2s/步 | 中 ~1.5s/步 |
| Token消耗 | 高 截图编码开销大 | 高 截图+结构全传 | 中 按需取数据 | 极低 CLI模式 ~75 tok/步 |
| JS重页面 | 高 — 视觉理解 | 中 — DOM可读 | 中 — CDP可取 | 中 — 视觉兜底 |
| 跨应用操作 | 全桌面 | 仅浏览器 | 仅浏览器 | 仅浏览器 |
## 使用示例
### 基本使用
```python
from anthropic import Anthropic
client = Anthropic()
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=[{
"type": "computer_20241022",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
}],
messages=[{
"role": "user",
"content": "Open Chrome and go to google.com"
}]
)
```
## 适用场景
- **桌面应用自动化**：操作任何桌面应用
- **需要跨应用操作**：多个应用协同
- **复杂视觉场景**：需要视觉理解
- **无法使用API的场景**：没有API的应用
## 优势
- **可以操作任何应用**：不限于浏览器
- **可以处理复杂的视觉场景**：视觉理解能力强
- **OS级通用**：桌面级操作
## 挑战
- **速度慢**：0.8-2s/步
- **Token消耗高**：截图编码开销大
- **依赖视觉识别准确性**：可能误识别
- **成本高**：Token消耗大
## 最佳实践
1. **需要跨应用选Computer Use**：OS级通用
2. **复杂视觉场景选Computer Use**：视觉理解能力强
3. **成本敏感不选Computer Use**：Token消耗高
4. **速度要求高不选Computer Use**：速度慢
## 方案选择指南
| 场景 | 推荐方案 | 理由 |
|------|---------|------|
| E2E测试 | Playwright MCP | 速度快，结构化信息丰富 |
| 性能分析 | Chrome DevTools MCP | 可以监控网络和性能 |
| 网页自动化 | Browser Use | Token消耗低，AI自主决策 |
| 桌面应用 | Computer Use | 可以操作任何应用 |
| Token成本敏感 | Browser Use | 极低Token消耗 |
| 复杂视觉场景 | Computer Use | 视觉理解能力强 |
## 相关概念
- [[测试策略金字塔]]：Computer Use是测试的工具
- [[Browser_Use]]：Computer Use和Browser Use的对比
- [[Playwright]]：Computer Use和Playwright的对比
- [[MCP]]：Computer Use和MCP的对比

73
AI工程/概念/Cursor.md Executable file
View File

@@ -0,0 +1,73 @@
# Cursor
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Claude_Code]]、[[Kiro]]、[[Trae]]
## 定义
**Cursor**是基于VS Code的AI IDE，提供AI优先的开发体验。
**核心思想**：基于VS Code，AI优先设计，强大的代码补全，Composer模式。
## 核心特征
### 1. 基于VS Code
- 熟悉的IDE界面
- 丰富的插件生态
- 易于上手
### 2. AI优先设计
- AI深度集成
- 智能代码补全
- 上下文感知
### 3. Composer模式
- 多文件编辑
- 智能重构
- 批量修改
### 4. 多模型支持
- 支持多种AI模型
- 可以切换模型
- 灵活选择
## 与其他AI工具对比
| 工具 | 类型 | 价格 | AI模型 | 适用场景 |
|------|------|------|--------|---------|
| [[Claude_Code]] | CLI | 按Token | Claude | 复杂逻辑 |
| Cursor | IDE | $20/月 | 多模型 | 日常开发 |
| [[Kiro]] | IDE | 免费+付费 | Claude | AWS项目 |
| [[Trae]] | IDE | 免费+付费 | 豆包 | 中文项目 |
## 适用场景
- **日常开发**：最常用的开发工具
- **代码补全**：需要智能代码补全
- **多文件编辑**：需要批量修改
- **团队协作**：需要熟悉的IDE环境
## 优势
- **熟悉界面**：基于VS Code，易于上手
- **AI集成**：AI深度集成
- **代码补全**：强大的代码补全
- **多模型**：支持多种AI模型
## 挑战
- **付费**：需要$20/月
- **资源消耗**：可能消耗较多资源
- **依赖网络**：需要网络连接
## 最佳实践
1. **日常开发首选**：最适合作为日常开发工具
2. **代码补全利用**：充分利用智能代码补全
3. **Composer模式**：充分利用多文件编辑能力
4. **模型选择**：根据需求选择合适的模型
## 相关概念
- [[Harness工程]]：Cursor是Harness的工具之一
- [[Agent_as_Code]]：Cursor支持Agent as Code
- [[Claude_Code]]、[[Kiro]]、[[Trae]]：其他AI编程工具

125
AI工程/概念/Git_Worktree.md Executable file
View File

@@ -0,0 +1,125 @@
# Git Worktree
> 相关：[[Harness工程]]、[[核心Loop]]、[[超级Loop]]
## 定义
**Git Worktree**是Git的一个功能，允许从同一个仓库检出多个工作目录，每个工作目录都是一个独立的分支。
**核心思想**：共享同一个.git目录，节省磁盘空间，实现多任务并行开发。
## 核心特征
### 1. 多工作区
- 一个仓库，多个工作目录
- 每个工作目录是一个独立分支
- 共享同一个.git目录
### 2. 并行开发
- 多个AI实例可以同时工作
- 互不干扰
- 快速切换
### 3. 节省空间
- 共享.git目录
- 不需要克隆多个仓库
- 节省磁盘空间
## 基本命令
### 创建Worktree
```bash
# 基于已有分支创建
git worktree add ../feature-login feature/login
# 创建新分支 + 工作区（最常用）
git worktree add -b feature-payment ../feature-payment
# 查看所有worktree
git worktree list
# 删除工作区
git worktree remove ../feature-login
```
### 管理Worktree
```bash
# 列出所有工作区
git worktree list
# 输出：
# /project/main abc1234 [main]
# /project/feature-a def5678 [feature-a]
# /project/feature-b ghi9012 [feature-b]
# 删除工作区
git worktree remove ../feature-a
# 强制删除（即使有未提交的更改）
git worktree remove --force ../feature-a
# 清理已删除的工作区记录
git worktree prune
```
## 使用场景
### 场景1：多AI实例并行开发
```bash
# 主工作区：开发功能A
cd /project/feature-a
claude-code # 启动Claude Code
# 新开终端：开发功能B
cd /project/feature-b
claude-code # 启动另一个Claude Code实例
# 再开终端：开发功能C
cd /project/feature-c
claude-code # 启动第三个Claude Code实例
```
### 场景2：AI + 人工并行开发
```bash
# AI在feature-a开发
cd /project/feature-a
claude-code
# 人工在main分支修复紧急bug
cd /project/main
# 手动修复bug
```
### 场景3：Code Review时继续开发
```bash
# 主工作区：feature-a提交PR，等待review
# 新开工作区：继续开发feature-b
git worktree add -b feature-b ../feature-b
cd ../feature-b
claude-code
```
## 优势
1. **并行开发**：多个AI实例可以同时工作在不同分支
2. **上下文隔离**：每个功能的上下文独立，不会混淆
3. **快速切换**：不需要`git checkout`，直接切换目录
4. **节省空间**：共享.git目录
## 挑战
- **分支管理**：需要管理多个分支
- **冲突处理**：可能需要处理分支冲突
- **学习成本**：需要了解Git Worktree概念
## 最佳实践
1. **命名规范**：工作区目录名与分支名一致
2. **及时清理**：完成的功能及时删除Worktree
3. **AI工具支持**：利用AI工具的自动Worktree功能
4. **定期Prune**：定期清理无效的工作区记录
## 相关概念
- [[Harness工程]]：Git Worktree是Harness的组成部分
- [[核心Loop]]：Git Worktree支持并行执行多个Loop
- [[超级Loop]]：Git Worktree支持并行执行多个超级Loop

114
AI工程/概念/Harness工程.md Executable file
View File

@@ -0,0 +1,114 @@
# Harness工程（驾驭工程）
> 相关：[[AI编程演进阶段]]、[[Agent_as_Code]]、[[核心Loop]]、[[上下文体系]]
## 定义
**Harness工程**是AI编程的第5阶段，将AI纳入工程治理体系，为其提供约束体系和外部接口，实现全自动无人值守的开发。
**核心思想**：不是让AI更聪明，而是让AI在受控环境中工作。
## 核心特征
### 1. 约束体系
- **规则约束**：Rules定义AI能做什么、不能做什么
- **规格约束**：Spec定义需求和设计的边界
- **测试约束**：自动化测试验证AI输出质量
### 2. 外部接口
- **MCP**：让AI访问数据库、文件系统等外部工具
- **Skills**：可复用的能力单元
- **CLI**：命令行工具集成
### 3. 自动化流程
- **Plan阶段**：人机协作，锁定需求
- **执行阶段**：AI自治，无需人工介入
- **验证阶段**：自动化测试，自动修复
## 关键原则
### 约束大于提示
- 不要依赖AI的"聪明"
- 通过约束体系保证质量
- 规则 > 提示词
### 文档即代码
- AGENTS.md作为宪法
- 规格文档可版本化
- 所有配置纳入Git
### 持续验证
- TDD驱动开发
- 自动化测试覆盖
- 持续集成持续交付
## 组成部分
```
Harness = 约束体系 + 工具体系 + 验证体系
约束体系：
- Rules（规则）
- Specs（规格）
- Standards（标准）
工具体系：
- MCP（外部工具）
- Skills（能力单元）
- CLI（命令行）
验证体系：
- 单元测试
- API测试
- E2E测试
- Code Review
```
## 适用场景
- **企业级项目**：需要严格的质量控制
- **多团队协作**：需要统一的开发规范
- **长期维护**：需要持续的代码质量保证
- **合规要求**：金融、医疗等需要审计的场景
## 实践要点
### 1. 建立文档体系
```
AGENTS.md ← 宪法
docs/
├── standards/ ← 标准规格
├── features/ ← 需求规格
├── designs/ ← 设计规格（事实方案）
└── plans/ ← 计划规格（过程方案）
```
### 2. 配置工具链
- 选择合适的AI工具（Claude Code/Cursor/Kiro）
- 配置MCP访问外部工具
- 开发Skills封装常用能力
### 3. 建立验证流程
- 定义测试策略
- 配置CI/CD流程
- 建立Code Review规范
## 优势
- **质量可控**：通过约束体系保证代码质量
- **可追溯**：所有配置和变更有历史记录
- **可复用**：Skills和配置可在项目间复用
- **可扩展**：易于引入新的工具和流程
## 挑战
- **学习曲线**：需要理解完整的工程体系
- **维护成本**：需要持续维护文档和配置
- **工具依赖**：依赖多个AI工具和协议
## 相关概念
- [[Agent_as_Code]]：Harness的技术实现方式
- [[核心Loop]]：Harness中的开发循环
- [[上下文体系]]：Harness的文档组织
- [[AI编程演进阶段]]：Harness是第5阶段

73
AI工程/概念/Kiro.md Executable file
View File

@@ -0,0 +1,73 @@
# Kiro
> 相关：[[规格驱动开发]]、[[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]
## 定义
**Kiro**是AWS推出的AI IDE和SDD框架，提供IDE原生的SDD能力。
**核心思想**：Spec = 可执行源（代码与测试），可以生成代码+测试并自动校验。
## 核心特征
### 1. IDE原生
- 深度集成IDE
- 原生SDD支持
- 无缝开发体验
### 2. 可执行Spec
- Spec可以直接生成代码
- Spec可以直接生成测试
- 自动校验
### 3. 强流程控制
- 闭环流程
- 自动验证
- 高度自动化
## 与其他SDD框架对比
| 维度 | [[BMAD]] | [[Spec_Kit]] | [[OpenSpec]] | Kiro |
|------|----------|--------------|--------------|----------|
| 方法定位 | 企业级SDD操作系统 | 工程化Spec工作流 | 轻量Spec层 | IDE原生SDD |
| 核心理念 | Spec = 治理体系 + 多Agent编排 | Spec = 开发入口 + Git生命周期 | Spec = 变更单元（持续演化） | Spec = 可执行源（代码与测试） |
| Spec生命周期 | 全生命周期 | 与分支绑定（短生命周期） | 长期存在（持续演化） | 持续驱动 |
| Spec粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 可执行能力 | 通过流程驱动 | 驱动开发流程 | 类Prompt | 可生成代码+测试并自动校验 |
| 流程控制 | 强（阶段+审批+Agent） | 中（Plan→Spec→Tasks） | 弱（自由演化） | 强（闭环） |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 与代码关系 | 间接 | 半耦合 | 弱耦合 | 强耦合 |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **小团队**：不需要强治理
- **高自动化需求**：需要自动验证
- **AWS项目**：深度集成AWS服务
- **新项目**：从零开始的项目
## 优势
- **IDE原生**：无缝开发体验
- **可执行Spec**：Spec可以直接生成代码和测试
- **自动验证**：内建自动验证
- **高度自动化**：减少人工干预
## 挑战
- **IDE绑定**：依赖特定IDE
- **学习成本**：需要了解Kiro的工作流
- **灵活性低**：不如OpenSpec灵活
## 最佳实践
1. **适合小团队**：小型团队最适合
2. **高自动化**：充分利用自动验证能力
3. **AWS集成**：充分利用AWS集成能力
4. **持续学习**：持续学习Kiro的最佳实践
## 相关概念
- [[规格驱动开发]]：Kiro是SDD框架之一
- [[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]：其他SDD框架

98
AI工程/概念/Loop工程.md Executable file
View File

@@ -0,0 +1,98 @@
# Loop工程
> 相关：[[核心Loop]]、[[超级Loop]]、[[Harness工程]]、[[测试策略金字塔]]
## 定义
**Loop工程**是AI编程的第4阶段，通过构建测试套件和验收规则，让AI能够根据验收规则自动循环，实现半自动有人值守的开发。
**核心思想**：让AI能根据验收规则自动循环，构建测试套件，定义输出结果。
## 核心特征
### 1. 自动循环
- AI根据验收规则自动运行
- 失败时自动修复并重试
- 直到满足退出条件
### 2. 测试驱动
- TDD驱动开发
- 先写测试再写代码
- 测试作为验收标准
### 3. 有人值守
- Plan阶段需要人工确认
- 执行阶段AI自治
- 异常时需要人工介入
## Loop类型
### [[核心Loop]]
- 范围：API测试
- 验证：后端逻辑
- 复杂度：中等
- 适用：后端开发
### [[超级Loop]]
- 范围：API测试 + E2E测试
- 验证：前后端联动
- 复杂度：高
- 适用：全栈开发
## Loop流程
```
Plan阶段（人机协作）
↓
装载需求规格 → 创建Plan → 确认Plan
↓
执行阶段（AI自治）
↓
编写测试 → 编写实现 → 运行测试
↓ ↓
↓ 失败 ↓ 成功
↓ ↓
修复重试 ←──────────────────── 退出循环
```
## 退出条件
1. 所有测试通过
2. 代码符合规范（Lint通过）
3. 没有编译错误
4. 满足验收标准
## 适用场景
- **复杂项目**：需要自动化开发流程
- **持续集成**：需要持续交付
- **团队协作**：需要统一的开发流程
- **质量保证**：需要严格的测试覆盖
## 优势
- **自动化**：减少人工干预
- **质量保证**：TDD驱动，代码质量有保障
- **可追溯**：Plan记录了实现过程
- **持续迭代**：可以快速修复问题
## 挑战
- **Plan质量**：Plan阶段需要充分沟通
- **测试覆盖**：需要编写全面的测试
- **运行时间**：Loop可能需要较长时间
- **调试复杂**：失败时需要调试
## 最佳实践
1. **Plan阶段充分沟通**：关闭所有开放性问题
2. **TDD驱动**：先写测试再写代码
3. **记录状态**：方便复盘和优化
4. **逐步扩展**：从核心Loop开始，逐步引入超级Loop
## 相关概念
- [[核心Loop]]：Loop工程的具体实现
- [[超级Loop]]：Loop工程的扩展实现
- [[Harness工程]]：Loop工程是Harness的组成部分
- [[测试策略金字塔]]：Loop工程使用的测试策略

157
AI工程/概念/MCP.md Executable file
View File

@@ -0,0 +1,157 @@
# MCP（Model Context Protocol）
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Skills]]
## 定义
**MCP**（Model Context Protocol）是AI与外部系统通信的标准协议，由Anthropic提出。
**核心思想**：标准化接口、双向通信、即插即用，让AI可以访问外部工具。
## 核心特征
### 1. 标准化接口
- 统一的协议规范
- 跨工具兼容
- 易于扩展
### 2. 双向通信
- AI可以调用外部工具
- 外部工具可以返回结果
- 支持流式通信
### 3. 即插即用
- 配置即可使用
- 无需修改AI代码
- 支持热插拔
## 架构
### Client-Server架构
```
AI工具（Client）
↓
MCP协议
↓
MCP Server（外部工具）
↓
数据库/文件系统/API等
```
### 常用MCP Server
| 类型 | Server | 用途 |
|------|--------|------|
| 数据库 | mcp-server-sqlite | SQLite数据库访问 |
| 数据库 | mcp-server-postgres | PostgreSQL数据库访问 |
| 文件系统 | mcp-server-filesystem | 文件系统访问 |
| Web搜索 | mcp-server-brave-search | Brave搜索 |
| GitHub | mcp-server-github | GitHub API访问 |
| 浏览器 | mcp-server-playwright | 浏览器自动化 |
## 配置示例
### Claude Code配置
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-sqlite"]
},
"filesystem": {
"command": "node",
"args": ["mcp-server-filesystem", "/path/to/dir"]
},
"brave-search": {
"command": "node",
"args": ["mcp-server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key"
}
}
}
}
```
### 配置文件位置
- Claude Code：`.claude/mcp.json`
- Cursor：`.cursor/mcp.json`
- OpenCode：`.opencode/mcp.json`
## 使用场景
### 1. 数据库访问
```json
{
"mcpServers": {
"database": {
"command": "node",
"args": ["mcp-server-postgres"],
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
}
}
}
}
```
### 2. 文件系统访问
```json
{
"mcpServers": {
"filesystem": {
"command": "node",
"args": ["mcp-server-filesystem", "/path/to/project"]
}
}
}
```
### 3. Web搜索
```json
{
"mcpServers": {
"brave-search": {
"command": "node",
"args": ["mcp-server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key"
}
}
}
}
```
## 适用场景
- **数据库访问**：让AI直接查询数据库
- **文件系统访问**：让AI读写文件
- **API调用**：让AI调用外部API
- **浏览器自动化**：让AI操作浏览器
## 优势
- **标准化**：统一的协议规范
- **易用性**：配置即可使用
- **可扩展**：支持自定义Server
- **跨工具**：多个AI工具可以共用
## 挑战
- **安全性**：需要控制AI的访问权限
- **性能**：可能影响AI响应速度
- **维护成本**：需要维护MCP Server
## 最佳实践
1. **最小权限**：只开放必要的MCP Server
2. **环境隔离**：不同环境使用不同的MCP配置
3. **监控日志**：记录AI的MCP调用
4. **定期审查**：定期审查MCP配置
## 相关概念
- [[Harness工程]]：MCP是Harness的组成部分
- [[Agent_as_Code]]：MCP是Agent as Code的组成部分
- [[Skills]]：MCP和Skills都是AI的能力扩展方式

73
AI工程/概念/OpenSpec.md Executable file
View File

@@ -0,0 +1,73 @@
# OpenSpec
> 相关：[[规格驱动开发]]、[[BMAD]]、[[Spec_Kit]]、[[Kiro]]
## 定义
**OpenSpec**是轻量级SDD框架，提供灵活的Spec层。
**核心思想**：Spec = 变更单元（持续演化），适合存量项目和快速迭代。
## 核心特征
### 1. 轻量级定位
- 灵活自由
- 最小化约束
- 快速迭代
### 2. 小粒度Spec
- 变更/Patch级规格
- 长期存在
- 持续演化
### 3. 弱流程控制
- 自由演化
- 最小化流程
- 适合快速迭代
## 与其他SDD框架对比
| 维度 | [[BMAD]] | [[Spec_Kit]] | OpenSpec | [[Kiro]] |
|------|----------|--------------|----------|----------|
| 方法定位 | 企业级SDD操作系统 | 工程化Spec工作流 | 轻量Spec层 | IDE原生SDD |
| 核心理念 | Spec = 治理体系 + 多Agent编排 | Spec = 开发入口 + Git生命周期 | Spec = 变更单元（持续演化） | Spec = 可执行源（代码与测试） |
| Spec生命周期 | 全生命周期 | 与分支绑定（短生命周期） | 长期存在（持续演化） | 持续驱动 |
| Spec粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 可执行能力 | 通过流程驱动 | 驱动开发流程 | 类Prompt | 可生成代码+测试并自动校验 |
| 流程控制 | 强（阶段+审批+Agent） | 中（Plan→Spec→Tasks） | 弱（自由演化） | 强（闭环） |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 与代码关系 | 间接 | 半耦合 | 弱耦合 | 强耦合 |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **存量项目**：已有代码库的项目
- **快速迭代**：需要快速响应变化
- **小型团队**：不需要强治理
- **灵活需求**：需要最大的灵活性
## 优势
- **轻量灵活**：最小化约束
- **快速迭代**：适合快速变化
- **易于上手**：学习曲线平缓
- **适合存量项目**：不需要重构
## 挑战
- **失控风险高**：缺乏流程控制
- **不适合大型项目**：缺乏治理能力
- **不适合新项目**：不如Spec Kit结构化
## 最佳实践
1. **适合存量项目**：已有代码库的项目最适合
2. **快速迭代**：充分利用灵活性
3. **适度约束**：虽然灵活，但需要适度约束
4. **持续演化**：Spec持续演化，保持最新
## 相关概念
- [[规格驱动开发]]：OpenSpec是SDD框架之一
- [[BMAD]]、[[Spec_Kit]]、[[Kiro]]：其他SDD框架

192
AI工程/概念/Playwright.md Executable file
View File

@@ -0,0 +1,192 @@
# Playwright
> 相关：[[测试策略金字塔]]、[[Browser_Use]]、[[MCP]]
## 定义
**Playwright**是最流行的浏览器自动化测试框架，支持Chromium、Firefox、WebKit。
**核心思想**：提供稳定、快速的浏览器自动化能力，支持多浏览器、多平台。
## 核心特征
### 1. 多浏览器支持
- Chromium（Chrome、Edge）
- Firefox
- WebKit（Safari）
- 一套API，多浏览器运行
### 2. 自动化能力
- 自动等待元素可操作
- 自动重试断言
- 网络拦截
- 截图和视频录制
### 3. 稳定性
- 使用稳定的选择器
- 自动处理动态内容
- 支持并行测试
## 基本使用
### 安装
```bash
npm init playwright@latest
```
### 基本测试
```typescript
import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {
await page.goto('https://playwright.dev/');
await page.getByText('Get Started').click();
await expect(page).toHaveTitle(/Getting started/);
});
```
### 登录测试
```typescript
test('login success', async ({ page }) => {
await page.goto('https://example.com/login');
await page.getByPlaceholder('Email').fill('test@example.com');
await page.getByPlaceholder('Password').fill('123456');
await page.getByRole('button', { name: 'Login' }).click();
await expect(page).toHaveURL(/dashboard/);
await expect(page.getByText('Welcome')).toBeVisible();
});
```
### API登录（更稳定）
```typescript
test('login via API + set session', async ({ page, request }) => {
const response = await request.post('https://example.com/api/login', {
data: {
email: 'test@example.com',
password: '123456'
}
});
expect(response.ok()).toBeTruthy();
const cookies = await response.headers()['set-cookie'];
await page.context().addCookies([{
name: 'session',
value: cookies,
domain: 'example.com',
path: '/'
}]);
await page.goto('https://example.com/dashboard');
await expect(page.getByText('Welcome')).toBeVisible();
});
```
## 选择器最佳实践
### 推荐的选择器（从优到差）
```typescript
// 1. 使用data-testid（最稳定）
await page.getByTestId('submit-button').click();
// 2. 使用角色和名称（推荐）
await page.getByRole('button', { name: 'Login' }).click();
// 3. 使用标签文本（推荐）
await page.getByLabel('Email').fill('test@example.com');
// 4. 使用占位符（可用）
await page.getByPlaceholder('Enter your email').fill('test@example.com');
// 5. 使用文本（可用）
await page.getByText('Welcome').toBeVisible();
// 6. 使用CSS选择器（不推荐，容易变）
await page.locator('.btn-primary').click();
// 7. 使用XPath（不推荐，容易变）
await page.locator('//button[@type="submit"]').click();
```
## 等待策略
### 自动等待
```typescript
// Playwright自动等待元素可见、可操作
await page.getByRole('button', { name: 'Login' }).click();
```
### 显式等待
```typescript
// 等待URL变化
await expect(page).toHaveURL(/dashboard/);
// 等待元素可见
await expect(page.getByText('Welcome')).toBeVisible();
// 等待元素隐藏
await expect(page.getByText('Loading')).toBeHidden();
// 等待网络请求完成
await page.waitForLoadState('networkidle');
```
## 配置
### playwright.config.ts
```typescript
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry',
},
projects: [
{ name: 'chromium', use: { browserName: 'chromium' } },
{ name: 'firefox', use: { browserName: 'firefox' } },
{ name: 'webkit', use: { browserName: 'webkit' } },
],
});
```
## 适用场景
- **E2E测试**：最流行的E2E测试框架
- **浏览器自动化**：自动化浏览器操作
- **视觉回归测试**：截图对比
- **性能测试**：页面加载性能
## 优势
- **多浏览器支持**：一套API，多浏览器运行
- **稳定性**：自动等待、自动重试
- **速度快**：比Selenium快
- **生态成熟**：社区活跃，文档完善
## 挑战
- **学习成本**：需要了解框架API
- **维护成本**：需要维护测试脚本
- **运行时间**：完整的E2E测试运行时间长
## 最佳实践
1. **优先使用稳定的选择器**：data-testid、角色、标签
2. **使用API登录**：提高测试速度
3. **测试数据管理**：使用Fixture或API准备数据
4. **并行测试**：提高测试效率
5. **CI/CD集成**：每次提交自动运行测试
## 相关概念
- [[测试策略金字塔]]：Playwright是E2E测试的工具
- [[Browser_Use]]：Playwright和Browser Use的对比
- [[MCP]]：Playwright MCP是MCP的一种实现

133
AI工程/概念/Rule约束.md Executable file
View File

@@ -0,0 +1,133 @@
# Rule约束
> 相关：[[AI编程演进阶段]]、[[Harness工程]]、[[规格驱动开发]]
## 定义
**Rule约束**是AI编程的第2阶段，通过规则文件约束AI在不同工作模式下的处理方式。
**核心思想**：用明确的规则告诉AI能做什么、不能做什么，而不是依赖AI的"聪明"。
## 核心特征
### 1. 规则显化
- 将隐式的经验转化为显式的规则
- 规则以文件形式存在
- 规则可版本化、可共享
### 2. 工作模式
- 定义AI在不同模式下的行为
- 如：Research模式、Plan模式、Code模式
- 每种模式有不同的约束
### 3. 持续对话
- 需要通过对话输入需求
- AI根据规则约束生成代码
- 人工需要持续监督
## 典型框架
### RIPER-5
- **R**esearch：研究阶段，分析需求
- **I**mplement：实现阶段，编写代码
- **P**lan：规划阶段，制定计划
- **E**valuate：评估阶段，验证结果
- **R**eview：审查阶段，Code Review
### 规则示例
```markdown
# Java代码风格Rules
1. 使用Java 17语法，不使用已废弃API
2. 类名使用大驼峰，方法名使用小驼峰
3. 常量使用全大写下划线分隔
4. 单行代码不超过120字符
5. 禁止使用@Autowired字段注入
6. 数据库表必须包含created_at和updated_at字段
```
## 规则分类
### 1. 代码风格规则
- 命名规范
- 格式规范
- 注释规范
### 2. 架构规则
- 分层架构约束
- 依赖方向约束
- 模块划分规则
### 3. 安全规则
- 敏感数据处理
- 权限控制
- 加密要求
### 4. 性能规则
- 数据库查询优化
- 缓存策略
- 并发控制
## 载体
### .cursor/rules/
```
.cursor/
└── rules/
├── java-style.md
├── api-style.md
└── security.md
```
### CLAUDE.md
```markdown
# 项目规则
## 代码规范
- 使用阿里巴巴Java开发手册
- 所有方法必须有注释
## 数据库规范
- 表名使用下划线命名
- 必须包含时间戳字段
```
### AGENTS.md
```markdown
# AI行为规则
1. 生成代码必须符合代码规范
2. 敏感数据必须加密存储
3. API必须使用RESTful风格
```
## 适用场景
- **个人项目**：约束AI生成符合个人习惯的代码
- **小团队**：统一团队代码风格
- **学习阶段**：通过规则学习最佳实践
## 优势
- **简单直接**：规则清晰，易于理解
- **快速上手**：不需要复杂的工具链
- **灵活调整**：规则可以随时修改
## 局限
- **需要持续对话**：每次都需要输入需求
- **无法自动化**：依赖人工监督
- **规则冲突**：复杂场景规则可能冲突
## 最佳实践
1. **从核心规则开始**：先定义最重要的规则
2. **逐步完善**：根据实践逐步添加规则
3. **定期Review**：定期审查和优化规则
4. **规则分层**：区分强制规则和推荐规则
## 相关概念
- [[AI编程演进阶段]]：Rule是第2阶段
- [[Harness工程]]：Rule是Harness的组成部分
- [[规格驱动开发]]：Rule的进阶是Spec

155
AI工程/概念/Skills.md Executable file
View File

@@ -0,0 +1,155 @@
# Skills
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[MCP]]
## 定义
**Skills**是可复用的AI能力单元，通过打包提示词、脚本、模版，进一步精确拓展AI的能力。
**核心思想**：将常用的能力封装成可复用的单元，提高AI的工作效率。
## 核心特征
### 1. 可复用
- 可以在多个项目中使用
- 可以在团队间共享
- 可以版本化管理
### 2. 触发词驱动
- 通过触发词调用
- 自动识别使用场景
- 无需手动配置
### 3. 封装完整
- 包含提示词
- 包含脚本工具
- 包含文档模版
## 组成
### 1. SKILL.md
- 技能描述
- 使用说明
- 触发词定义
### 2. 脚本文件
- 可执行的脚本
- 自动化工具
- 配置文件
### 3. 文档模版
- 输出格式模版
- 配置文件模版
- 报告模版
## 示例
### Commit & Push Skill
```markdown
# Commit & Push Skill
## 触发词
commit, push, 提交
## 执行
git add -A
git commit -m "{message}"
git push
## 规则
- 提交前检查lint
- 信息遵循conventional commit
- 推送前确认分支
```
### Deploy Skill
```markdown
# Deploy Skill
## 触发词
deploy, 部署, 发布
## 执行
npm run build
npx vercel --prod
## 规则
- 构建前运行测试
- 部署前确认环境
- 部署后验证功能
```
### Test Skill
```markdown
# Test Skill
## 触发词
test, 测试, 运行测试
## 执行
mvn test
## 规则
- 运行所有测试
- 生成测试报告
- 失败时提供修复建议
```
## 目录结构
```
skills/
├── commit-push/
│ ├── SKILL.md
│ └── commit.sh
├── deploy/
│ ├── SKILL.md
│ └── deploy.sh
├── test/
│ ├── SKILL.md
│ └── test.sh
└── code-review/
├── SKILL.md
└── review.sh
```
## 开发流程
1. **需求分析**：确定技能的功能和触发词
2. **脚本开发**：编写可执行的脚本
3. **触发词定义**：定义触发词和使用场景
4. **测试验证**：测试技能的功能
5. **文档编写**：编写SKILL.md文档
## 适用场景
- **常用操作**：提交代码、部署、测试等
- **复杂流程**：需要多个步骤的操作
- **团队协作**：需要统一的操作规范
- **知识沉淀**：最佳实践需要沉淀
## 优势
- **可复用**：可以在多个项目中使用
- **易共享**：可以在团队间共享
- **易维护**：可以版本化管理
- **易扩展**：可以快速添加新技能
## 挑战
- **初始成本**：需要开发Skills
- **维护成本**：需要持续维护Skills
- **学习成本**：团队需要学习Skills
## 最佳实践
1. **从常用操作开始**：先封装最常用的操作
2. **保持简单**：每个Skill只做一件事
3. **文档清晰**：SKILL.md要清晰易懂
4. **定期Review**：定期审查和优化Skills
## 相关概念
- [[Harness工程]]：Skills是Harness的组成部分
- [[Agent_as_Code]]：Skills是Agent as Code的组成部分
- [[MCP]]：MCP和Skills都是AI的能力扩展方式

73
AI工程/概念/Spec_Kit.md Executable file
View File

@@ -0,0 +1,73 @@
# Spec Kit
> 相关：[[规格驱动开发]]、[[BMAD]]、[[OpenSpec]]、[[Kiro]]
## 定义
**Spec Kit**是工程化SDD框架，提供Git集成的Spec工作流。
**核心思想**：Spec = 开发入口 + Git生命周期，适合新项目（0→1）。
## 核心特征
### 1. 工程化定位
- Git集成
- 工程化工作流
- 与开发流程紧密结合
### 2. 中粒度Spec
- Feature级规格
- 与Git分支绑定
- 短生命周期
### 3. 中等流程控制
- Plan→Spec→Tasks
- 灵活但有序
- 适合敏捷开发
## 与其他SDD框架对比
| 维度 | [[BMAD]] | Spec Kit | [[OpenSpec]] | [[Kiro]] |
|------|----------|----------|--------------|----------|
| 方法定位 | 企业级SDD操作系统 | 工程化Spec工作流 | 轻量Spec层 | IDE原生SDD |
| 核心理念 | Spec = 治理体系 + 多Agent编排 | Spec = 开发入口 + Git生命周期 | Spec = 变更单元（持续演化） | Spec = 可执行源（代码与测试） |
| Spec生命周期 | 全生命周期 | 与分支绑定（短生命周期） | 长期存在（持续演化） | 持续驱动 |
| Spec粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 可执行能力 | 通过流程驱动 | 驱动开发流程 | 类Prompt | 可生成代码+测试并自动校验 |
| 流程控制 | 强（阶段+审批+Agent） | 中（Plan→Spec→Tasks） | 弱（自由演化） | 强（闭环） |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 与代码关系 | 间接 | 半耦合 | 弱耦合 | 强耦合 |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
| 失控风险 | 低 | 中 | 高 | 中 |
## 适用场景
- **新项目（0→1）**：从零开始的项目
- **中型团队**：需要工程化工作流
- **敏捷开发**：需要灵活但有序的流程
- **Git重度用户**：深度集成Git
## 优势
- **Git集成**：与Git深度集成
- **工程化**：完整的工程化工作流
- **灵活性**：比BMAD更灵活
- **易于上手**：学习曲线相对平缓
## 挑战
- **失控风险中等**：需要一定的流程控制
- **不适合大型项目**：大粒度不如BMAD
- **不适合存量项目**：不如OpenSpec灵活
## 最佳实践
1. **适合新项目**：从零开始的项目最适合
2. **Git工作流**：充分利用Git的分支和PR
3. **团队协作**：团队成员需要理解工作流
4. **持续迭代**：根据实践持续优化流程
## 相关概念
- [[规格驱动开发]]：Spec Kit是SDD框架之一
- [[BMAD]]、[[OpenSpec]]、[[Kiro]]：其他SDD框架

68
AI工程/概念/Trae.md Executable file
View File

@@ -0,0 +1,68 @@
# Trae
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[Claude_Code]]、[[Cursor]]、[[Kiro]]
## 定义
**Trae**是字节跳动推出的AI IDE，集成豆包大模型，中文支持好。
**核心思想**：集成豆包大模型，中文支持好，适合中文项目。
## 核心特征
### 1. 豆包大模型
- 字节跳动自研模型
- 中文理解能力强
- 适合中文项目
### 2. 中文支持好
- 中文文档完善
- 中文社区活跃
- 中文优化
### 3. IDE集成
- 完整的IDE功能
- AI深度集成
- 易于使用
## 与其他AI工具对比
| 工具 | 类型 | 价格 | AI模型 | 适用场景 |
|------|------|------|--------|---------|
| [[Claude_Code]] | CLI | 按Token | Claude | 复杂逻辑 |
| [[Cursor]] | IDE | $20/月 | 多模型 | 日常开发 |
| [[Kiro]] | IDE | 免费+付费 | Claude | AWS项目 |
| Trae | IDE | 免费+付费 | 豆包 | 中文项目 |
## 适用场景
- **中文项目**：中文理解和生成能力强
- **国内团队**：国内团队使用更方便
- **豆包生态**：使用豆包生态的项目
- **成本敏感**：有免费版本
## 优势
- **中文支持好**：中文理解和生成能力强
- **国内团队**：国内团队使用更方便
- **成本较低**：有免费版本
- **豆包生态**：与豆包生态集成
## 挑战
- **国际项目**：不如Claude Code适合国际项目
- **复杂逻辑**：推理能力不如Claude Code
- **生态成熟度**：生态不如Cursor成熟
## 最佳实践
1. **中文项目首选**：中文项目最适合
2. **国内团队**：国内团队使用更方便
3. **豆包生态**：充分利用豆包生态
4. **成本优化**：使用免费版本降低成本
## 相关概念
- [[Harness工程]]：Trae是Harness的工具之一
- [[Agent_as_Code]]：Trae支持Agent as Code
- [[Claude_Code]]、[[Cursor]]、[[Kiro]]：其他AI编程工具

162
AI工程/概念/_概念索引.md Executable file
View File

@@ -0,0 +1,162 @@
# AI工程概念索引
> 本索引收录团队级 AI Coding 相关的所有核心概念
## 基础概念
### [[AI编程演进阶段]]
AI 编程从手动复制到全自动的5个发展阶段
### [[Harness工程]]
为 AI 提供约束体系和外部接口的工程实践
### [[Agent_as_Code]]
将 AI 协作文件以代码方式管理的理念
---
## 开发方法论
### [[Rule约束]]
通过规则文件约束 AI 行为的方法
### [[规格驱动开发]]
以规格文档为核心的开发方法（SDD）
### [[Loop工程]]
AI 自治运行的开发循环
### [[核心Loop]]
Plan → TDD → 验证的开发循环
### [[超级Loop]]
核心Loop + E2E测试验证的扩展循环
---
## 技术概念
### [[过程方案vs事实方案]]
Plans（追加不维护）vs Designs（覆盖更新）
### [[上下文体系]]
AI 协作的文档组织结构
### [[打样工程]]
提供代码模版让 AI 参考生成代码
### [[技术规格DSL]]
领域模型、数据库、API、时序图的标准化表达
---
## 工具与协议
### [[MCP]]
Model Context Protocol，AI 与外部系统通信的标准协议
### [[Skills]]
可复用的 AI 能力单元
### [[AGENTS.md]]
AI 协作的宪法级配置文件
### [[Git_Worktree]]
Git 多工作区并行开发功能
---
## AI工具
### [[Claude_Code]]
Anthropic 出品的 AI 编程工具
### [[Cursor]]
基于 VS Code 的 AI IDE
### [[Kiro]]
AWS 推出的 AI IDE 和 SDD 框架
### [[Trae]]
字节跳动推出的 AI IDE
---
## SDD框架
### [[BMAD]]
企业级 SDD 框架，强治理
### [[Spec_Kit]]
工程化 SDD 框架，Git 集成
### [[OpenSpec]]
轻量级 SDD 框架，灵活
---
## 测试相关
### [[测试策略金字塔]]
Lint → Code Review → 单元测试 → API测试 → E2E测试
### [[Browser_Use]]
AI 操作浏览器的框架
### [[Playwright]]
浏览器自动化测试框架
### [[Computer_Use]]
Anthropic 的 OS 级视觉操作方案
---
## 统计
- 总概念数：28个
- 分类：7大类
- 创建日期：2026-06-20
- 最后更新：2026-06-20
## 概念清单
### 基础概念
- [[AI编程演进阶段]]
- [[Harness工程]]
- [[Agent_as_Code]]
### 开发方法论
- [[Rule约束]]
- [[规格驱动开发]]
- [[Loop工程]]
- [[核心Loop]]
- [[超级Loop]]
### 技术概念
- [[过程方案vs事实方案]]
- [[上下文体系]]
- [[打样工程]]
- [[技术规格DSL]]
### 工具与协议
- [[MCP]]
- [[Skills]]
- [[AGENTS.md]]
- [[Git_Worktree]]
### AI工具
- [[Claude_Code]]
- [[Cursor]]
- [[Kiro]]
- [[Trae]]
### SDD框架
- [[BMAD]]
- [[Spec_Kit]]
- [[OpenSpec]]
### 测试相关
- [[测试策略金字塔]]
- [[Browser_Use]]
- [[Playwright]]
- [[Computer_Use]]

141
AI工程/概念/上下文体系.md Executable file
View File

@@ -0,0 +1,141 @@
# 上下文体系
> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[AGENTS.md]]、[[过程方案vs事实方案]]
## 定义
**上下文体系**是AI协作的文档组织结构，通过分层文档为AI提供完整的上下文信息，让AI能够理解和遵循项目规范。
**核心思想**：使用完整的文档来描述上下文和约束体系，区分过程方案和事实方案，减少维护成本。
## 核心特征
### 1. 分层结构
- 宪法级：AGENTS.md
- 标准层：standards/
- 需求层：features/
- 设计层：designs/
- 计划层：plans/
### 2. 引用关系
- 上层文档引用下层文档
- 形成清晰的依赖关系
- AI可以理解完整上下文
### 3. 双轨管理
- 过程方案：Plans（追加不修改）
- 事实方案：Designs（覆盖更新）
## 文档分层结构
```
AGENTS.md ← 宪法（所有AI工具读取）
docs/
├── standards/ ← 标准规格（架构/命名/API/安全规范）
├── features/ ← 需求规格（产品/BA维护）
├── designs/ ← 设计规格（事实方案，Source of Truth）
├── plans/ ← 计划规格（过程方案，追加不修改）
└── others/ ← 架构决策、Release、测试用例等
skills/ ← AI技能（可复用能力单元）
mcp/ ← MCP配置（外部工具接入）
```
## 各层职责
### AGENTS.md（宪法级）
- 定义项目基本信息
- 定义AI行为规则
- 定义目录结构
- 所有AI工具都从这个文件开始
### standards/（标准层）
- 代码风格规范
- API设计规范
- 数据库设计规范
- 安全规范
### features/（需求层）
- 产品需求文档
- 用户故事
- 验收标准
- 由产品/BA维护
### designs/（设计层）
- 数据库设计
- API设计
- 架构设计
- 事实方案，必须保持最新
### plans/（计划层）
- 任务计划
- 实现方案
- 过程方案，追加不修改
### skills/（技能层）
- 可复用的AI能力单元
- 包含提示词、脚本、文档
### mcp/（工具层）
- MCP配置
- 外部工具接入
## 构建引用关系
### 示例：AGENTS.md
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
```
### 示例：Plan引用Design
```markdown
# Plan: 实现用户注册功能
## 参考设计
- 数据库设计：../designs/database-schema.md
- API设计：../designs/api-design.md
## 实现方案
根据设计文档实现...
```
## 适用场景
- **团队协作**：多人协作需要统一的上下文
- **复杂项目**：复杂项目需要完整的文档体系
- **长期维护**：长期项目需要持续的上下文管理
- **知识传承**：新成员需要快速理解项目
## 优势
- **完整上下文**：AI可以理解完整的项目背景
- **易于维护**：分层结构，职责清晰
- **可追溯**：文档变更有历史记录
- **可复用**：标准和设计可以在项目间复用
## 挑战
- **初始成本**：需要建立完整的文档体系
- **维护成本**：需要持续维护文档
- **学习曲线**：团队需要理解文档体系
## 最佳实践
1. **从AGENTS.md开始**：先定义最基本的规则
2. **逐步扩展**：根据实践逐步添加文档
3. **明确职责**：每层文档有明确的职责
4. **定期Review**：定期审查和优化文档
5. **保持最新**：事实方案必须保持最新
## 相关概念
- [[Harness工程]]：上下文体系是Harness的组成部分
- [[Agent_as_Code]]：上下文体系是Agent as Code的文档组织
- [[AGENTS.md]]：上下文体系的宪法级文件
- [[过程方案vs事实方案]]：上下文体系的双轨管理方式

153
AI工程/概念/打样工程.md Executable file
View File

@@ -0,0 +1,153 @@
# 打样工程
> 相关：[[Harness工程]]、[[上下文体系]]、[[技术规格DSL]]
## 定义
**打样工程**是提供代码模版和示例，让AI参考生成代码的工程实践。
**核心思想**：让AI"抄作业"，而不是自由发挥，保证代码风格统一、质量稳定。
## 核心原则
1. **约定大于配置**：通过模版约定代码风格
2. **编排逻辑和原子能力分离**：Controller、Service、Repository职责明确
3. **操作者和被操作对象分离**：分层清晰
## 常见工序
### 1. 简单CRUD（无复用逻辑）
```
Controller + Command → AppService → Repository → Response对象
```
**示例**：
```java
// Controller
@PostMapping("/users")
public Response<UserResponse> createUser(@Valid @RequestBody CreateUserCommand cmd) {
return Response.success(userAppService.create(cmd));
}
// AppService
public UserResponse create(CreateUserCommand cmd) {
User user = userRepository.save(User.from(cmd));
return UserResponse.from(user);
}
// Repository
public User save(User user) {
userMapper.insert(user);
return user;
}
```
### 2. 复杂CRUD（有复用逻辑）
```
Controller + Command → AppService → DomainService → Repository → Response对象
```
**示例**：
```java
// AppService - 编排逻辑
public UserResponse create(CreateUserCommand cmd) {
// 1. 校验用户名唯一
domainService.checkUsernameUnique(cmd.getUsername());
// 2. 加密密码
String encryptedPassword = domainService.encryptPassword(cmd.getPassword());
// 3. 保存用户
User user = User.from(cmd, encryptedPassword);
userRepository.save(user);
// 4. 发送欢迎邮件
domainService.sendWelcomeEmail(user);
return UserResponse.from(user);
}
// DomainService - 原子能力
public void checkUsernameUnique(String username) {
if (userRepository.existsByUsername(username)) {
throw new BusinessException("用户名已存在");
}
}
```
### 3. 复杂查询
```
Controller + Query对象 → AppService → QueryPO（或复用PO）→ Response对象
```
**示例**：
```java
// Controller
@GetMapping("/users")
public Response<Page<UserResponse>> listUsers(@Valid UserQuery query) {
return Response.success(userAppService.list(query));
}
// AppService
public Page<UserResponse> list(UserQuery query) {
Page<UserPO> page = userRepository.findByQuery(query);
return page.map(UserResponse::from);
}
// Repository
public Page<UserPO> findByQuery(UserQuery query) {
// 构建查询条件
// 执行分页查询
// 返回分页结果
}
```
## 三层架构
### Controller层
- **职责**：接收请求、参数校验、调用Service
- **输入**：Command/Query对象
- **输出**：Response对象
- **不包含业务逻辑**
### Service层
- **AppService**：应用服务，编排逻辑
- **DomainService**：领域服务，复杂业务逻辑
- **职责**：编排业务逻辑、调用DomainService/Repository
### Repository层
- **职责**：数据持久化
- **输入**：实体对象
- **输出**：实体对象或PO
## 参考代码
- **DDD微服务示例**：https://github.com/domain-driven-design/ddd-microservices
## 为什么需要打样工程
- **AI生成代码质量不稳定**：需要模版约束
- **不同AI工具风格不同**：需要统一风格
- **AI不知道最佳实践**：需要沉淀最佳实践
## 优势
1. **提高代码质量**：基于模版生成，质量有保障
2. **统一代码风格**：所有代码遵循相同的风格
3. **减少Review成本**：代码符合规范，Review更快
4. **知识沉淀**：最佳实践沉淀在模版中
## 挑战
- **初始成本**：需要建立打样工程
- **维护成本**：需要持续维护模版
- **灵活性**：模版可能限制创新
## 最佳实践
1. **建立打样工程**：提供标准的代码模版
2. **分层清晰**：Controller、Service、Repository职责明确
3. **工序标准化**：简单CRUD、复杂CRUD、复杂查询各有标准
4. **AI参考打样**：让AI根据打样工程生成代码
## 相关概念
- [[Harness工程]]：打样工程是Harness的组成部分
- [[上下文体系]]：打样工程是上下文体系的组成部分
- [[技术规格DSL]]：打样工程使用技术规格DSL

220
AI工程/概念/技术规格DSL.md Executable file
View File

@@ -0,0 +1,220 @@
# 技术规格DSL
> 相关：[[规格驱动开发]]、[[Harness工程]]、[[上下文体系]]
## 定义
**技术规格DSL**（Domain Specific Language）是使用领域特定语言编写技术规格的方法，包括领域模型、数据库、API、时序图等。
**核心思想**：使用DSL驱动技术规格，保证一致性和可执行性。
## 5个模块
| 模块 | 表达标准 | 格式 | 产出内容 | 约束/规范 |
|------|---------|------|---------|----------|
| **领域模型** | PlantUML/Smart Domain | .puml | 实体、属性、关系 | 必须表达实体关系；字段需与数据库一致 |
| **数据库** | SQL DDL/DBML/Flyway | .sql | 表结构、索引、约束 | 必须可执行；包含索引和外键 |
| **API** | OpenAPI 3.x | .yaml/.json | 接口定义、请求/响应 | 必须定义schema；字段与模型一致 |
| **时序图** | PlantUML | .puml | 调用流程、系统交互 | 必须反映真实调用链；包含异常分支 |
| **专题设计** | Markdown | .md | 架构策略 | 只写策略与规则；强调设计决策 |
## 领域模型
### PlantUML示例
```plantuml
@startuml
entity User {
* id : Long <<PK>>
--
* username : String(50)
* email : String(100)
* role_id : Long <<FK>>
}
entity Role {
* id : Long <<PK>>
--
* name : String(20)
}
User }o--|| Role : "拥有"
note right of User : 聚合根
@enduml
```
### 约束要求
- 必须表达实体关系（1:1, 1:N, M:N）
- 字段需与数据库一致
- 标注聚合关系
## 数据库设计
### SQL DDL示例
```sql
-- Flyway migration: V1__create_users_table.sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(50) NOT NULL UNIQUE,
email VARCHAR(100) NOT NULL UNIQUE,
password VARCHAR(255) NOT NULL,
role_id BIGINT NOT NULL,
status TINYINT(1) DEFAULT 1,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_username (username),
INDEX idx_email (email),
CONSTRAINT fk_user_role FOREIGN KEY (role_id) REFERENCES roles(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 约束要求
- 必须可执行
- 使用Flyway/Liquibase管理版本
- 包含索引和外键
## API设计
### OpenAPI 3.x示例
```yaml
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/api/v1/users:
post:
summary: 创建用户
tags: [User]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: 创建成功
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
components:
schemas:
CreateUserRequest:
type: object
required: [username, email, password]
properties:
username:
type: string
minLength: 3
maxLength: 50
email:
type: string
format: email
password:
type: string
minLength: 8
```
### 约束要求
- 必须定义schema
- 禁止只写接口说明
- 字段与领域模型一致
## 时序图
### PlantUML时序图示例
```plantuml
@startuml
actor User
participant "UserController" as C
participant "UserService" as S
participant "UserRepository" as R
database "MySQL" as DB
User -> C: POST /api/v1/users
C -> C: 参数校验
C -> S: createUser(CreateUserRequest)
S -> S: 业务规则校验
S -> R: save(User)
R -> DB: INSERT INTO users ...
DB --> R: 返回结果
R --> S: 返回 User
S --> C: 返回 UserResponse
C --> User: 201 Created
alt 用户名已存在
S --> C: throw DuplicateException
C --> User: 409 Conflict
end
@enduml
```
### 约束要求
- 必须反映真实调用链
- 建议包含异常分支（alt）
- 标注关键步骤
## 专题设计
### 示例
```markdown
# 权限设计方案
## 策略
- 使用RBAC（基于角色的访问控制）
- 权限注解：@RequirePermission("user:create")
- 默认拒绝所有未授权的请求
## 规则
1. 管理员角色拥有所有权限
2. 普通用户只能操作自己的数据
3. 敏感操作需要二次确认
## 设计决策
- 选择RBAC而非ABAC：业务场景简单，角色固定
- 权限存储在Redis：减少数据库查询
```
### 约束要求
- 只写"策略与规则"
- 不重复API/DDL
- 强调设计决策
## 为什么用DSL
- **可执行**：DDL可以直接运行，OpenAPI可以生成代码
- **AI友好**：LLM对DSL的理解比自然语言更精确
- **一致性保证**：DSL有语法规则，不容易产生歧义
## 适用场景
- **复杂项目**：需要完整的技术规格
- **团队协作**：需要统一的技术规范
- **AI辅助开发**：需要精确的技术规格
## 优势
- **一致性**：领域模型、数据库、API保持一致
- **可执行**：部分DSL可以直接执行
- **AI友好**：AI可以精确理解DSL
- **可维护**：DSL可以版本化
## 挑战
- **学习成本**：需要学习多种DSL
- **维护成本**：需要保持DSL的一致性
- **工具支持**：需要相应的工具支持
## 最佳实践
1. **使用DSL**：统一技术规格的表示方式
2. **保持一致性**：领域模型、数据库、API要一致
3. **AI辅助生成**：让AI根据规格生成代码
4. **版本控制**：技术规格纳入Git管理
## 相关概念
- [[规格驱动开发]]：技术规格DSL是SDD的组成部分
- [[Harness工程]]：技术规格DSL是Harness的组成部分
- [[上下文体系]]：技术规格DSL是上下文体系的组成部分

177
AI工程/概念/核心Loop.md Executable file
View File

@@ -0,0 +1,177 @@
# 核心Loop
> 相关：[[Loop工程]]、[[超级Loop]]、[[Harness工程]]、[[测试策略金字塔]]
## 定义
**核心Loop**是AI编程中AI自治运行的开发循环，通过Plan → TDD → 验证的流程，实现半自动有人值守的开发。
**核心思想**：Plan阶段人机协作，执行阶段AI自治。
## 核心流程
```
开始进入循环
↓
[Chat] 进入Plan模式
↓
装载需求规格，给出指令进行Plan
↓
[Chat] 符合要求，退出Plan模式，开始执行？
↓ 是
[模型] 读取Plan
↓
创建API测试，实现代码
↓
[模型] 运行测试/浏览器调试，是否成功？
↓ 否 → 重复多次/白天持续很久/夜间
↓ 是
[模型] 退出循环
↓
（给予ByPass权限）
```
## 三个阶段
### 阶段1：Plan（规划）
- **输入**：需求规格、技术规格
- **输出**：实现方案、任务列表
- **关键**：关闭所有开放性问题
- **人工介入**：确认Plan是否合理
**Plan模版**：
```markdown
# Plan: 实现用户注册功能
## 目标
实现用户注册API，支持邮箱验证
## 任务列表
- [ ] 1. 创建数据库表users
- [ ] 2. 实现POST /api/v1/users API
- [ ] 3. 实现邮箱验证逻辑
- [ ] 4. 编写单元测试
- [ ] 5. 编写API测试
## 实现方案
1. 使用Flyway创建users表
2. Controller接收CreateUserCommand
3. AppService调用UserRepository保存
4. 发送验证邮件
## 验收标准
- 所有单元测试通过
- 所有API测试通过
- 代码符合阿里巴巴Java开发手册
## 状态
- 开始时间：2026-06-20 10:00
- 预计完成：2026-06-20 12:00
```
### 阶段2：执行（Implementation）
- **输入**：Plan
- **输出**：API测试、实现代码
- **关键**：按照Plan逐步实现
- **AI自治**：无需人工介入
**步骤**：
1. 编写API测试
2. 运行测试（断言失败）
3. 编写实现代码
4. 运行测试（通过）
### 阶段3：验证（Verification）
- **输入**：API测试、实现代码
- **输出**：测试结果、修复建议
- **关键**：所有测试通过
- **AI自治**：自动运行测试，自动修复
## Loop规则
### 1. Plan等待确认
在docs/plans下根据模版创建Plan，等待人工确认。
### 2. 编写API测试
根据Plan实现API测试，运行成功并断言失败。
```java
@Test
void testCreateUser() {
CreateUserRequest request = new CreateUserRequest();
request.setUsername("testuser");
request.setEmail("test@example.com");
request.setPassword("Password123");
Response<UserResponse> response = userClient.create(request);
assertEquals(201, response.getCode());
assertNotNull(response.getData().getId());
}
```
### 3. 编写实现
编写单元测试 + 实现代码，通过编译。
```java
@PostMapping("/users")
public Response<UserResponse> createUser(@RequestBody CreateUserRequest request) {
return Response.success(userAppService.create(request));
}
```
### 4. 运行API测试
运行测试，并修复失败的测试和其他错误。
```bash
mvn test -Dtest=UserApiTest
```
## 退出条件
1. 所有API测试通过
2. 所有单元测试通过
3. 代码符合规范（Lint通过）
4. 没有编译错误
## ByPass权限
AI在某些情况下可以跳过某些步骤：
- 测试环境不可用
- 第三方服务不可用
- 紧急修复
在AGENTS.md中定义ByPass规则。
## 适用场景
- **后端开发**：API开发、业务逻辑实现
- **中等复杂度**：需要TDD驱动的开发
- **团队协作**：需要统一开发流程
## 优势
- **质量可控**：TDD驱动，代码质量有保障
- **可追溯**：Plan记录了实现过程
- **AI自治**：执行阶段无需人工介入
- **持续迭代**：可以快速修复问题
## 挑战
- **Plan质量**：Plan阶段需要充分沟通
- **测试覆盖**：需要编写全面的测试
- **运行时间**：Loop可能需要较长时间
## 最佳实践
1. **Plan阶段充分沟通**：关闭所有开放性问题
2. **TDD驱动**：先写测试再写代码
3. **记录状态**：方便复盘和优化
4. **ByPass控制**：紧急情况可以跳过步骤
## 相关概念
- [[Loop工程]]：核心Loop是Loop工程的具体实现
- [[超级Loop]]：核心Loop的扩展，增加E2E测试
- [[Harness工程]]：核心Loop是Harness的组成部分
- [[测试策略金字塔]]：核心Loop使用的测试策略

99
AI工程/概念/测试策略金字塔.md Executable file
View File

@@ -0,0 +1,99 @@
# 测试策略金字塔
> 相关：[[核心Loop]]、[[超级Loop]]、[[Playwright]]、[[Browser_Use]]
## 定义
**测试策略金字塔**是AI辅助下的分层测试策略，从代码扫描到端到端测试，层层递进。
**核心思想**：分层测试，每层有不同的测试对象和工具。
## 测试层级
| 测试类型 | 测试对象 | 工具（含AI） | 负责人 |
|---------|---------|--------------|-------------------|
| **Lint代码扫描** | 代码风格、代码逻辑和片段 | TS Lint/SonarQube | 程序 |
| **Code Review** | 代码逻辑、架构设计、规范 | GitHub Copilot、Claude Code、CodeRabbit、GitHub PR | 开发者 + AI Review Agent |
| **单元测试** | 函数/类行为、边界条件、异常处理 | JUnit、pytest、Jest + AI生成测试代码 | 开发者 + Test Generation Agent |
| **API测试** | 接口契约、输入输出、鉴权、错误码、业务规则 | Karate（主）、RestAssured（补充） + AI生成测试用例 | QA + 后端开发 + API Test Agent |
| **E2E测试** | 用户关键路径、跨系统流程、前后端联动 | Playwright + AI生成脚本/自愈 | QA + 自动化测试工程师 + E2E Agent |
## AI的作用
### Lint代码扫描
- 自动修复格式问题
- 检测潜在的bug
- 提供修复建议
### Code Review
- 速度快：几分钟内完成审查
- 覆盖广：可以检查多个维度（安全、性能、规范）
- 一致性：不会遗漏
### 单元测试
- 快速生成大量测试用例
- 覆盖边界条件
- 生成Mock数据
### API测试
- 根据OpenAPI规范生成测试用例
- 生成测试数据
- 自动生成断言
### E2E测试
- 生成测试脚本
- 自愈（selector修复）
- 步骤补全
## 测试金字塔演变
### 传统测试金字塔
```
E2E测试（少量）
/ \
/ 集成测试 \
/ （中等数量） \
/ \
/ 单元测试 \
/ （大量） \
/_________________________\
```
### AI时代的测试策略
- **AI生成大量单元测试**：覆盖边界条件
- **AI生成API测试**：基于OpenAPI规范
- **AI操作浏览器做E2E测试**：模拟真实用户
- **人工专注于Code Review**：审查AI的审查结果
## 适用场景
- **所有项目**：都需要分层测试
- **复杂项目**：需要完整的测试金字塔
- **AI辅助开发**：充分利用AI生成测试
## 优势
- **全面覆盖**：从代码到端到端，全面覆盖
- **自动化**：充分利用AI生成测试
- **质量保障**：多层测试保证代码质量
- **效率提升**：AI生成测试提高效率
## 挑战
- **维护成本**：需要维护多层测试
- **运行时间**：完整的测试金字塔运行时间长
- **学习成本**：需要了解多种测试工具和策略
## 最佳实践
1. **分层测试**：单元测试→API测试→E2E测试
2. **AI生成测试**：利用AI快速生成大量测试用例
3. **人工审查**：AI生成的测试需要人工审查
4. **持续集成**：所有测试集成到CI/CD流程
## 相关概念
- [[核心Loop]]：核心Loop使用测试策略金字塔
- [[超级Loop]]：超级Loop扩展了测试策略金字塔
- [[Playwright]]：E2E测试使用的工具
- [[Browser_Use]]：E2E测试使用的工具

150
AI工程/概念/规格驱动开发.md Executable file
View File

@@ -0,0 +1,150 @@
# 规格驱动开发（SDD）
> 相关：[[AI编程演进阶段]]、[[Harness工程]]、[[Rule约束]]、[[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]
## 定义
**规格驱动开发**（Spec-Driven Development，SDD）是AI编程的第3阶段，以规格文档为核心的开发方法。
**核心思想**：Spec是单一事实来源（SSoT），所有开发活动围绕Spec展开。
## 核心特征
### 1. 规格中心化
- Spec是唯一的真相来源
- 所有代码从Spec生成
- Spec变更驱动代码变更
### 2. 结构化表达
- 需求以结构化形式表达
- 使用Markdown、YAML等格式
- 可机器解析和验证
### 3. 文件驱动
- 文件进，文件出
- 规格文件可版本化
- 规格文件可复用
## SDD框架对比
| 维度 | [[BMAD]] | [[Spec_Kit]] | [[OpenSpec]] | [[Kiro]] |
|------|----------|--------------|--------------|----------|
| 定位 | 企业级SDD操作系统 | 工程化Spec工作流 | 轻量Spec层 | IDE原生SDD |
| 理念 | Spec=治理体系+多Agent编排 | Spec=开发入口+Git生命周期 | Spec=变更单元（持续演化） | Spec=可执行源 |
| 生命周期 | 全生命周期 | 与分支绑定（短） | 长期存在（持续） | 持续驱动 |
| 粒度 | 大（系统/模块级） | 中（Feature级） | 小（变更/Patch级） | 中（Feature+行为） |
| 可执行 | 流程驱动 | 驱动开发流程 | 类Prompt | 可生成代码+测试 |
| 自动验证 | 无 | 无 | 弱 | 强（内建） |
| 适用场景 | 大型系统/多团队 | 新项目（0→1） | 存量项目/快速迭代 | 小团队/高自动化 |
## 规格类型
### 1. 需求规格（Feature Spec）
```markdown
# 用户注册功能
## 用户故事
作为一个新用户，我想要注册账号，以便使用系统功能。
## 验收标准
1. 用户可以输入邮箱和密码
2. 系统发送验证邮件
3. 用户点击链接完成验证
4. 验证成功后可以登录
## 字段定义
- email: string, required, unique
- password: string, required, min:8
- verified: boolean, default:false
```
### 2. 设计规格（Design Spec）
```markdown
# 数据库设计
## users表
- id: bigint, primary key
- email: varchar(100), unique
- password: varchar(255)
- verified: tinyint(1), default:0
- created_at: timestamp
- updated_at: timestamp
```
### 3. API规格（API Spec）
```yaml
openapi: 3.0.3
paths:
/api/v1/users:
post:
summary: 创建用户
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
```
## 规格流转
### 过程方案（Plans）
- 每次创建新文件
- 记录实现过程
- 不修改旧文件
- 保留决策轨迹
### 事实方案（Designs）
- 覆盖更新最终态
- 作为下次Plan的起点
- 必须保持最新
- Source of Truth
## 适用场景
### BMAD
- 企业级项目
- 多团队协作
- 强治理需求
- 合规要求高
### Spec Kit
- 新项目（0→1）
- 需要Git集成
- 中等复杂度
### OpenSpec
- 存量项目
- 快速迭代
- 轻量级需求
### Kiro
- 小团队
- 高自动化需求
- AWS项目
## 优势
- **单一真相来源**：避免信息不一致
- **可追溯**：Spec变更有历史记录
- **可验证**：Spec可以生成测试
- **可复用**：Spec可以在项目间复用
## 挑战
- **初始成本**：需要建立完整的Spec体系
- **维护成本**：Spec需要持续更新
- **学习曲线**：团队需要理解SDD理念
## 最佳实践
1. **从核心Spec开始**：先定义最重要的规格
2. **逐步扩展**：根据实践逐步添加规格
3. **定期Review**：定期审查和优化规格
4. **自动化验证**：尽可能自动化Spec验证
## 相关概念
- [[AI编程演进阶段]]：SDD是第3阶段
- [[Harness工程]]：SDD是Harness的组成部分
- [[过程方案vs事实方案]]：SDD的规格管理方式
- [[BMAD]]、[[Spec_Kit]]、[[OpenSpec]]、[[Kiro]]：SDD框架

223
AI工程/概念/超级Loop.md Executable file
View File

@@ -0,0 +1,223 @@
# 超级Loop（E2E Loop）
> 相关：[[核心Loop]]、[[Loop工程]]、[[测试策略金字塔]]、[[Playwright]]、[[Browser_Use]]
## 定义
**超级Loop**是在[[核心Loop]]基础上增加E2E测试验证的扩展循环，确保前后端联动的正确性。
**核心思想**：通过E2E测试纳入更大的Loop范围，验证完整的用户流程。
## 核心流程
```
开始进入循环
↓
[Chat] 进入Plan模式
↓
装载需求规格/界面原型，给出指令进行Plan
↓
[Chat] 符合要求，退出Plan模式，开始执行？
↓ 是
[模型] 读取Plan，按照Loop规则进行实现
↓
[模型] 满足Loop准出要求？
↓ 否 → 重复多次/白天持续很久/夜间
↓ 是
[模型] 退出循环
↓
（给予ByPass权限）
```
## 7个步骤
### 1. Plan等待确认
在docs/plans下根据模版创建Plan。
```markdown
# Plan: 实现用户注册功能（含前端）
## 目标
实现用户注册功能，包括后端API和前端页面
## 任务列表
- [ ] 1. 实现POST /api/v1/users API
- [ ] 2. 实现注册页面 /register
- [ ] 3. 实现表单验证
- [ ] 4. 实现注册成功跳转
- [ ] 5. 编写API测试
- [ ] 6. 编写E2E测试
## 验收标准
- 所有API测试通过
- 所有E2E测试通过
- 前端页面视觉效果符合设计稿
```
### 2. 编写测试用例
在docs/test-cases下编写E2E测试用例。
```markdown
# docs/test-cases/register.md
## 测试用例
### TC-001: 成功注册
1. 访问 /register 页面
2. 输入用户名 testuser
3. 输入邮箱 test@example.com
4. 输入密码 Password123
5. 确认密码 Password123
6. 点击注册按钮
7. 验证跳转到 /login
8. 验证提示"注册成功"
### TC-002: 用户名已存在
1. 访问 /register 页面
2. 输入已存在的用户名 existinguser
3. 点击注册按钮
4. 验证提示"用户名已存在"
```
### 3. 编写API测试
根据Plan实现API测试，运行成功并断言失败。
```java
@Test
void testRegister() {
CreateUserRequest request = new CreateUserRequest();
request.setUsername("testuser");
request.setEmail("test@example.com");
request.setPassword("Password123");
Response<UserResponse> response = userClient.create(request);
assertEquals(201, response.getCode());
assertNotNull(response.getData().getId());
}
```
### 4. 编写实现
编写后端和前端实现代码。
**后端实现**：
```java
@PostMapping("/users")
public Response<UserResponse> createUser(@RequestBody CreateUserRequest request) {
return Response.success(userAppService.create(request));
}
```
**前端实现**：
```tsx
function RegisterPage() {
const [form] = Form.useForm();
const handleSubmit = async (values) => {
await axios.post('/api/v1/users', values);
message.success('注册成功');
navigate('/login');
};
return (
<Form form={form} onFinish={handleSubmit}>
<Form.Item name="username" rules={[{ required: true }]}>
<Input placeholder="用户名" />
</Form.Item>
<Button type="primary" htmlType="submit">注册</Button>
</Form>
);
}
```
### 5. 运行API测试
运行测试，并修复失败的测试和其他错误。
```bash
mvn test -Dtest=UserApiTest
```
### 6. 浏览器调试
使用[[Playwright]]调试前端，确认视觉效果和交互功能。
```typescript
test('注册页面视觉效果', async ({ page }) => {
await page.goto('/register');
// 截图验证视觉效果
const screenshot = await page.screenshot();
// 调用AI视觉模型验证
// 验证表单验证
await page.fill('[name="email"]', 'invalid-email');
await page.click('button[type="submit"]');
await expect(page.getByText('请输入有效的邮箱')).toBeVisible();
});
```
### 7. 编写E2E测试
编写[[Playwright]] E2E测试，覆盖本轮需求的测试场景。
```typescript
test('完整的注册流程', async ({ page }) => {
await page.goto('/register');
await page.getByLabel('用户名').fill('testuser');
await page.getByLabel('邮箱').fill('test@example.com');
await page.getByLabel('密码').fill('Password123');
await page.getByLabel('确认密码').fill('Password123');
await page.getByRole('button', { name: '注册' }).click();
await expect(page).toHaveURL(/\/login/);
await expect(page.getByText('注册成功')).toBeVisible();
});
```
## 超级Loop vs 核心Loop
| 维度 | [[核心Loop]] | 超级Loop |
|------|-------------|----------|
| 测试范围 | API测试 | API测试 + E2E测试 |
| 验证层次 | 后端逻辑 | 前后端联动 |
| 复杂度 | 中等 | 高 |
| 运行时间 | 几分钟 | 几十分钟到几小时 |
| Token消耗 | 中等 | 高 |
| 适用场景 | 后端开发 | 全栈开发 |
## 适用场景
- **全栈开发**：需要同时开发前后端
- **复杂交互**：需要验证前后端联动
- **用户体验**：需要验证视觉效果
- **完整流程**：需要验证完整的用户流程
## 优势
- **全面验证**：验证前后端联动的正确性
- **用户体验**：验证视觉效果和交互
- **完整流程**：验证完整的用户流程
- **质量保障**：E2E测试保证质量
## 挑战
- **成本高**：运行时间长，Token消耗大
- **维护成本**：E2E测试需要持续维护
- **调试复杂**：需要调试前后端
- **环境依赖**：依赖完整的环境
## 最佳实践
1. **先写测试用例**：明确验收标准
2. **API测试先通过**：确保后端逻辑正确
3. **浏览器调试**：验证前端视觉效果
4. **E2E测试覆盖**：确保前后端联动正确
5. **成本控制**：仅在必要时使用
## 相关概念
- [[核心Loop]]：超级Loop基于核心Loop
- [[Loop工程]]：超级Loop是Loop工程的扩展
- [[测试策略金字塔]]：超级Loop使用的测试策略
- [[Playwright]]：超级Loop使用的E2E测试工具
- [[Browser_Use]]：超级Loop可能使用的浏览器自动化工具

170
AI工程/概念/过程方案vs事实方案.md Executable file
View File

@@ -0,0 +1,170 @@
# 过程方案vs事实方案
> 相关：[[规格驱动开发]]、[[上下文体系]]、[[Harness工程]]
## 定义
**过程方案**和**事实方案**是[[规格驱动开发]]中两种不同的规格管理方式。
- **过程方案（Plans）**：记录实现过程，每次新建文件，用完即弃
- **事实方案（Designs）**：记录系统真相，覆盖更新，长期维护
## 核心区别
| 维度 | 过程方案（Plans） | 事实方案（Designs） |
|------|------------------|-------------------|
| 目的 | 记录实现过程 | 记录当前状态 |
| 更新方式 | 追加新文件 | 覆盖更新 |
| 生命周期 | 短期（任务完成后归档） | 长期（持续维护） |
| 维护成本 | 低（不修改旧文件） | 高（必须保持最新） |
| 使用场景 | 任务执行、问题排查 | 新功能开发、架构决策 |
| 示例 | plan-2026-06-20-feature-x.md | database-schema.md |
## 过程方案（Plans）
### 特征
- 每次任务创建新文件
- 文件命名包含日期：`plan-YYYY-MM-DD-feature-name.md`
- 任务完成后移动到`archive/`目录
- 不修改旧文件，保留决策轨迹
### 内容结构
```markdown
# Plan: 实现用户注册功能
## 目标
实现用户注册API，支持邮箱验证
## 任务列表
- [ ] 1. 创建数据库表users
- [ ] 2. 实现POST /api/v1/users API
- [ ] 3. 实现邮箱验证逻辑
## 实现方案
1. 使用Flyway创建users表
2. Controller接收CreateUserCommand
3. AppService调用UserRepository保存
## 状态
- 开始时间：2026-06-20 10:00
- 预计完成：2026-06-20 12:00
- 实际完成：2026-06-20 11:30
## 问题记录
- 10:30 发现数据库连接池配置问题
- 11:00 邮箱服务超时，增加重试机制
```
### 最佳实践
- **命名规范**：`plan-YYYY-MM-DD-feature-name.md`
- **内容结构**：目标、方案、任务列表、状态、问题记录
- **归档策略**：任务完成后移动到`archive/`目录
## 事实方案（Designs）
### 特征
- 每次覆盖更新
- 文件命名使用功能名称：`database-schema.md`
- 必须保持最新状态
- 作为下次Plan的事实依据
### 内容结构
```markdown
# 数据库设计
## 概述
系统数据库设计，包含用户、角色、权限等表。
## users表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| username | varchar(50) | 用户名，唯一 |
| email | varchar(100) | 邮箱，唯一 |
| password | varchar(255) | 密码，加密存储 |
| status | tinyint(1) | 状态：0-禁用，1-启用 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |
## roles表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| name | varchar(20) | 角色名称 |
## 变更历史
- 2026-06-20：添加users表
- 2026-06-21：添加roles表
- 2026-06-22：添加user_roles关联表
```
### 最佳实践
- **命名规范**：使用功能名称，如`database-schema.md`
- **内容结构**：概述、详细设计、变更历史
- **更新策略**：每次变更必须更新文档，保持最新
## 目录结构
```
docs/
├── standards/ # 标准规格（事实方案）
├── features/ # 需求规格（事实方案）
├── designs/ # 设计规格（事实方案）
├── plans/ # 计划规格（过程方案）
│ ├── archive/ # 归档的计划
│ └── plan-2026-06-20-feature-x.md
└── others/ # 架构决策、Release、测试用例等
```
## 使用策略
### 何时使用过程方案
- 任务执行过程记录
- 问题排查记录
- 决策轨迹记录
- 临时方案记录
### 何时使用事实方案
- 数据库设计
- API设计
- 架构设计
- 标准规范
- 需求规格
## 优势与局限
### 过程方案
**优势**：
- 维护成本低
- 保留决策轨迹
- 易于追溯历史
**局限**：
- 文件数量多
- 需要定期归档
- 不反映当前状态
### 事实方案
**优势**：
- 反映当前状态
- 单一真相来源
- 易于理解
**局限**：
- 维护成本高
- 需要持续更新
- 丢失历史信息
## 最佳实践
1. **明确区分**：清楚区分哪些是过程方案，哪些是事实方案
2. **定期归档**：过程方案定期归档到`archive/`目录
3. **保持最新**：事实方案必须保持最新状态
4. **变更历史**：事实方案记录变更历史
5. **关联引用**：Plans引用Designs，确保一致性
## 相关概念
- [[规格驱动开发]]：过程方案和事实方案是SDD的规格管理方式
- [[上下文体系]]：过程方案和事实方案是上下文体系的组成部分
- [[Harness工程]]：过程方案和事实方案是Harness的文档管理方式

128
Docker/Docker安装redis.md
View File

@@ -1,128 +0,0 @@
# Docker 安装 Redis
## 1. 下载 Redis 镜像
```bash
docker pull redis:latest
# 或者指定版本
docker pull redis:7-alpine
```
## 2. 创建本地目录
```bash
# 创建配置和数据目录
mkdir -p redis/conf redis/data
```
## 3. 创建 Redis 配置文件
```bash
cat > redis/conf/redis.conf << 'EOF'
# 基本配置
bind 0.0.0.0
protected-mode no
port 6379
# 持久化
appendonly yes
appendfilename "appendonly.aof"
# 内存管理
maxmemory 256mb
maxmemory-policy allkeys-lru
# 日志
loglevel notice
EOF
```
## 4. 启动 Redis 容器
```bash
docker run -d \
--name redis \
-p 6379:6379 \
-v $PWD/redis/conf/redis.conf:/usr/local/etc/redis/redis.conf \
-v $PWD/redis/data:/data \
redis:latest \
redis-server /usr/local/etc/redis/redis.conf
```
### 参数说明
| 参数 | 说明 |
|------|------|
| `-d` | 后台运行 |
| `--name redis` | 容器名称 |
| `-p 6379:6379` | 端口映射 |
| `-v .../redis.conf:...` | 配置文件挂载 |
| `-v .../data:/data` | 数据目录挂载 |
| `redis-server ...` | 使用指定配置文件启动 |
## 5. 连接测试
```bash
# 使用 redis-cli 连接
docker exec -it redis redis-cli
# 或者直接用 redis-cli（如果主机已安装）
redis-cli
# 测试
> PING
PONG
> SET test "hello"
OK
> GET test
"hello"
```
## 6. 常用运维命令
```bash
# 查看容器状态
docker ps | grep redis
# 查看日志
docker logs -f redis
# 进入容器
docker exec -it redis sh
# 停止/启动
docker stop redis
docker start redis
```
## 7. 无配置文件快速启动
如果不需要自定义配置：
```bash
docker run -d \
--name redis \
-p 6379:6379 \
-v redis-data:/data \
redis:latest \
redis-server --appendonly yes
```
## 8. 数据备份
Redis 数据存储在 `/data` 目录（已挂载到本地）：
```bash
# 备份
tar -czvf redis-backup-$(date +%Y%m%d).tar.gz redis/data/
# 恢复
tar -xzvf redis-backup-xxxxxxxx.tar.gz
```
---
> 参考：[Redis Docker 官方文档](https://hub.docker.com/_/redis)

62
Docker/docker镜像清理.md
View File

@@ -1,62 +0,0 @@
# Docker 镜像清理
## 清理无用镜像
### 方法一：prune 命令（推荐）
```bash
# 清理悬空镜像（无 tag 的镜像）
docker image prune -f
# 清理所有未使用镜像
docker image prune -a -f
```
### 方法二：批量清理
```bash
# 批量删除所有无用镜像，不会影响正在使用的镜像
docker images | awk 'NR!=1{print $1":"$2}' | xargs docker rmi
```
### 方法三：system prune（全面清理）
```bash
# 清理所有未使用的容器、网络、镜像
docker system prune -f
# 清理所有未使用的镜像，不仅仅是悬空镜像
docker system prune -a -f
# 清理卷（注意：会删除数据）
docker system prune --volumes -f
```
## 清理前后对比
```bash
# 查看清理前
docker images -a
# 清理
docker system prune -f
# 查看清理后
docker images -a
```
## 定时清理（可选）
创建 cron 任务定期清理：
```bash
# 编辑 crontab
crontab -e
# 每周日凌晨 3 点清理
0 3 * * 0 /usr/bin/docker system prune -f
```
---
> 参考：[Docker 官方文档](https://docs.docker.com/config/pruning/)

95
HomePage/MeNav导航站.md Executable file
View File

@@ -0,0 +1,95 @@
# MeNav 个人导航站生成器
> 一个轻量的个人导航网站，轻量级、高度可定制，完全静态部署
- **⭐ GitHub**: rbetree/menav (256 stars)
- **许可证**: AGPL-3.0
- **技术栈**: HTML5 + CSS3 + JavaScript + Handlebars
---
## 核心特点
- 🚀 **静态一键部署** — 无数据库，无后端，纯静态页面
- 📂 **书签导入** — 从浏览器书签一键导入
- 🎨 **多层级嵌套** — 支持 2-4 层级的分类结构
- 🌙 **双主题** — 明亮/黑暗主题切换
- 🔗 **GitHub Pages** — 一键 Fork 部署
- 🔖 **自动同步** — 配合 MarksVault 浏览器扩展，支持书签自动同步
---
## 快速开始
### 1. 克隆仓库
```bash
git clone https://github.com/rbetree/menav.git
cd menav
```
### 2. 安装依赖
```bash
npm install
```
### 3. 配置
编辑 `config/` 下的配置文件，定义你的网站分类和链接。
### 4. 本地预览
```bash
npm run dev
```
### 5. 构建
```bash
npm run build
```
构建产物在 `dist/` 目录。
---
## 部署到 GitHub Pages
1. Fork [menav](https://github.com/rbetree/menav) 仓库
2. 在仓库 Settings → Pages 中启用 GitHub Pages
3. 选择 `gh-pages` 分支
4. 访问 `https://yourusername.github.io/menav/`
---
## 书签导入
支持从浏览器书签导入，生成导航站点：
1. 导出浏览器书签为 HTML
2. 使用 MeNav 的书签导入功能
3. 自动生成分类结构
---
## 项目结构
```
menav/
├── src/ # 生成器、书签处理、前端脚本
├── templates/ # Handlebars 模板
├── config/ # 模块化配置
├── assets/ # 静态资源
├── bookmarks/ # 书签导入相关
└── dist/ # 构建产物
```
---
## 适用场景
- 个人导航主页
- 书签管理
- 团队内部链接导航
- 实验室/项目资源汇总

41
wiki/Areas/AI编程工具/Obsidian+AI工作流研究.md Executable file
View File

@@ -0,0 +1,41 @@
---
created: 2026-05-01
type: knowledge
tags: [Obsidian, AI, 知识管理, 工作流, 抖音, Aiob]
source: https://v.douyin.com/gjP5VZmI9_A/
---
# Obsidian + AI 工作流研究
> 抖音博主 @Aiob 分享：Obsidian + AI，2026 唯一的神
## 为什么 Obsidian 天然适合 AI？
1. **本地 Markdown 文件** — AI 可直接读写，无需 API
2. **双向链接 + 知识图谱** — 为 AI 提供丰富的上下文
3. **插件生态丰富** — Remotely Save、Templater、Dataview 等
## 推荐工作流
1. 用 AI 生成笔记内容 → 存入 Obsidian
2. 利用双向链接构建知识网络
3. 通过 AI 插件实现对话式查询和总结
## 为什么是"唯一的神"？
- 相比 Notion/语雀等云端方案，Obsidian 数据完全本地
- 配合 AI 后，知识管理效率提升数倍
- 开源生态 + 插件，可定制性极强
## 与我们的实践对比
| 方面 | 我们 | @Aiob |
|------|------|-------|
| AI 工具 | OpenClaw + obsidian-headless | 通用 AI 插件 |
| 同步方式 | WebDAV | Remotely Save |
| 知识管理 | PARA 结构 | 双向链接 |
| 自动化 | ✅ cron/heartbeat | ❌ 手动 |
---
*基于抖音博主 @Aiob 内容整理 | 归档：2026-05-01*

32
wiki/Projects/软考高项冲刺-知识点.md
View File

@@ -101,6 +101,23 @@ exam_date: 2026-05-24
## 🏗️ 二、项目管理知识体系 ⭐核心（占 47%）
### 2.0 8 大绩效域（PMBOK 第七版）⭐新增
> **绩效域 = 宏观战略地图（价值实现）** | **10大知识领域 = 施工蓝图（过程控制）**
| 绩效域 | 口诀 | 对应知识领域/过程组 | 详情 |
|--------|------|-------------------|------|
| [[团队绩效域]] | 团33：共享所有绩效，文化领导绩效 | 资源管理 | [详情](高项知识领域/绩效域/团队绩效域.md) |
| [[干系人绩效域]] | 干46：惨痛满无负，十里分忧参督 | 干系人管理、沟通管理 | [详情](高项知识领域/绩效域/干系人绩效域.md) |
| [[不确定性绩效域]] | 不74：了解识别依赖预测负面改进储备 | 风险管理 | [详情](高项知识领域/绩效域/不确定性绩效域.md) |
| [[测量绩效域]] | 度46：充分理解及时决策 | 监控过程组 | [详情](高项知识领域/绩效域/测量绩效域.md) |
| [[规划绩效域]] | 规58：腿细城内挑 | 规划过程组 | [详情](高项知识领域/绩效域/规划绩效域.md) |
| [[交付绩效域]] | 交53：战果手里满 | 质量管理、范围管理 | [详情](高项知识领域/绩效域/交付绩效域.md) |
| [[项目工作绩效域]] | 工78：高湿干物采变雪 | 执行过程组 | [详情](高项知识领域/绩效域/项目工作绩效域.md) |
| [[开发方法与生命周期绩效域]] | 开34：妇联租借发宣泄 | 整合管理 | [详情](高项知识领域/绩效域/开发方法与生命周期绩效域.md) |
**12 大原则口诀：关键干架，互领材质，复风韧变**
### 2.1 五大过程组
| 过程组 | 说明 | 核心输出 |
@@ -518,7 +535,20 @@ ROI = (收益 - 成本) / 成本 × 100%
| 风险应对 | 4 种威胁 + 3 种机会 |
| 合同类型 | 总价/成本补偿/工料 |
### 7.3 冲刺策略
### 7.3 8 大绩效域速记
| 绩效域 | 口诀 | 核心要点 |
|--------|------|----------|
| 团队 | 团33 | 共享责任、高绩效团队、领导力技能 |
| 干系人 | 干46 | 识别→理解→参与→监督，权力/利益方格 |
| 不确定性 | 不74 | 风险/模糊性/复杂性，应急+管理储备 |
| 测量 | 度46 | 度量指标+霍桑效应陷阱 |
| 规划 | 规58 | 估算/团队/沟通/采购/变更规划 |
| 交付 | 交53 | 价值交付+可交付成果+质量 |
| 项目工作 | 工78 | 变更控制/学习/采购/沟通/资源 |
| 开发方法 | 开34 | 预测vs适应，交付节奏 |
### 7.4 冲刺策略
| 科目 | 策略 |
|------|------|

86
wiki/Projects/高项知识领域/十大管理/质量管理.md Executable file
View File

@@ -0,0 +1,86 @@
---
created: 2026-04-29
type: knowledge
tags: [软考高项, PMBOK, 质量管理]
source: 十大管理.xmind
---
# 质量管理
> 核心：确定项目质量的方针、目标、职责，通过质量规划、保证、控制、改进来实现
## 3 大过程
### 1. 规划质量管理
**定义**：识别项目可交付成果验收的质量要求、标准，并书面描述项目符合质量要求的证明
**输入**：项目章程、项目管理计划、项目文件
**工具**：
- 数据收集（**标杆对照**）
- 数据分析（**成本效益分析**、**质量成本**）
- **质量成本（COQ）**：找预防成本和评估成本的投资平衡点，用于规避失败成本
- 数据表现：
- **流程图**（SIPOC：供应商→输入→流程→输出→客户，全景视角）
- 逻辑数据模型
- **矩阵图**（行列交叉展示因素和目标的强弱关系）
- 思维导图、鱼骨图
- **测试与检查的规划**：α测试、β测试
**输出**：
- 质量管理计划
- 质量测量指标
- 质量核对单
### 2. 管理质量（QA）
### 3. 控制质量（QC）
## 高频考点
### 质量测量指标示例
| 指标 | 说明 |
|------|------|
| 网络时延 | 性能指标 |
| 易用性 | 用户体验 |
| 事件报警精度 | 准确性 |
### 质量核对单
| 核对项 | 结果 | 备注 |
|--------|------|------|
| ... | ✓/✗ | ... |
### QA（质量保证）职责
- **过程辅导**：为项目组提供过程指导
- **过程审计**：公司内部质量审计
- **过程改进**：收集数据，数据分析，提出项目质量提升建议
- **过程度量**
### 管理质量 vs 控制质量
| | 管理质量（QA） | 控制质量（QC） |
|--|---------------|---------------|
| 导向 | 过程导向（预防） | 结果导向（检查） |
| 时机 | 过程中 | 完成后 |
| 目标 | 确保过程正确 | 确保结果正确 |
### 如何提升项目质量
1. 做好人员培训
2. 严格执行质量管理计划
3. 持续过程改进
4. 加强质量审计
### 质量管理 vs 其他管理
- **范围**：质量的基础，质量核对单里有范围基准定义的验收标准
- **成本**：质量测量指标影响成本高低，质量成本构成成本
- **进度**：在高质量和完成时间中找平衡
---
*基于《十大管理》XMind 整理*

53
wiki/Resources/方法论/机器学习.md Executable file
View File

@@ -0,0 +1,53 @@
---
created: 2026-04-28
type: concept
tags: [机器学习，AI，监督学习，无监督学习]
---
# 机器学习（Machine Learning）
> 让计算机从数据中自动学习规律，无需显式编程
## 定义
机器学习是人工智能的一个子领域，研究如何通过算法让计算机从数据中学习模式，并用这些模式进行预测或决策。
## 三大范式
| 范式 | 说明 | 典型任务 |
|------|------|---------|
| [[监督学习]] | 从标注数据中学习映射 | 分类、回归 |
| [[无监督学习]] | 从未标注数据中发现结构 | 聚类、降维 |
| [[强化学习]] | 通过与环境交互学习策略 | 游戏 AI、机器人控制 |
## 工作流程
```
数据收集 → 数据预处理 → 特征工程 → 模型训练 → 模型评估 → 部署
```
## 核心概念
| 概念 | 说明 |
|------|------|
| 特征（Feature） | 输入数据的属性 |
| 标签（Label） | 要预测的目标值 |
| 过拟合（Overfitting） | 模型记住了训练数据的噪声 |
| 泛化（Generalization） | 模型在新数据上的表现 |
| [[反向传播]] | 神经网络训练的核心算法 |
## 与深度学习的区别
- **机器学习**：包含所有从数据中学习的算法（包括简单算法如线性回归、决策树）
- **深度学习**：机器学习的子集，特指使用多层[[神经网络]]的方法
## 相关概念
- [[神经网络]] / [[深度学习]]
- [[监督学习]] / [[无监督学习]] / [[强化学习]]
- [[Transformer 架构]]
- [[RAG]]
---
*基于 AI 基础知识整理*