MetaCraft/docs/ARCHITECTURE.md

# MetaCraft 架构设计

## 架构理念

MetaCraft 采用**纯文档化架构**：项目仅包含设计文档和AI工具脚本描述，不包含任何执行环境或运行服务。

- **设计文档**：Markdown格式的架构设计、组件规范、接口定义
- **AI工具脚本**：JavaScript文件描述自动化逻辑，供AI参考执行
- **执行分离**：具体实现由外部AI工具（如Claude Code）完成
- **可移植知识**：任何AI系统都可以参考这些设计实现类似功能

所有组件描述都是**设计概念**，不是可执行代码。实际运行时需要外部AI工具根据这些设计进行实现。

## 设计原则

1. **可自举**：工具链必须能够描述和实现自身的演进。
2. **可组合**：prompt、脚本、文档应能像乐高一样组合，支持复杂任务。
3. **上下文感知**：AI操作应基于完整的项目上下文，避免盲区。
4. **渐进式**：从简单原型开始，逐步增加功能，每一步都可用。
5. **透明性**：所有决策和变更都有迹可循（prompt历史、脚本日志）。

## 系统组件

### 1. Prompt 引擎设计 (`prompt-engine.js`)
描述如何加载、解析、执行prompt文件的设计概念。

**设计功能**：
- 描述读取Markdown格式prompt文件的逻辑
- 说明元数据提取方法（如`<!-- target: generate-controller -->`）
- 概述上下文注入机制（当前文件树、相关代码片段、Git状态等）
- 提供调用外部AI工具（如Claude Code）执行prompt的指导
- 文档化AI响应解析为操作指令的过程

**设计接口示例**：
```javascript
// 设计概念：外部AI工具应实现的接口
const { executePrompt } = require('./prompt-engine');
await executePrompt('prompts/add-feature.md', {
  projectRoot: '.',
  context: { module: 'user', type: 'controller' }
});
```

### 2. 脚本执行器设计 (`script-runner.js`)
描述统一执行自动化脚本的设计概念。

**设计工具函数**：
- `fs` 增强：描述读写文件、保持格式的逻辑
- `git` 操作：说明提交、分支、对比的实现方法
- `command` 执行：概述运行shell命令、捕获输出的设计
- `template` 渲染：文档化基于模板生成文件的流程
- `validation`：描述语法检查、测试运行、lint的设计

**设计示例脚本**：
```javascript
// 设计概念：外部AI工具应实现的脚本模式
const { runScript, fs, git } = require('@metacraft/runner');
module.exports = async (args) => {
  const content = await fs.read('templates/component.js');
  await fs.write(`src/components/${args.name}.js`, content);
  await git.commit(`Add component ${args.name}`);
};
```

### 3. 上下文管理器设计 (`context-manager.js`)
描述维护项目状态、为AI提供连贯上下文的设计概念。

**设计存储内容**：
- 项目结构树：描述如何存储和查询文件树结构
- 模块依赖图：说明依赖关系的建模和管理方法
- 待办任务列表：文档化从`meta/todo.md`解析任务的逻辑
- 操作历史：描述跟踪最近修改、提交的设计
- 自定义变量：说明环境配置、版本等变量的存储机制

**上下文注入设计**：
描述在执行prompt前自动注入相关上下文的设计模式，例如：
```
<!-- context -->
项目结构：
- src/
  - controllers/user.js
  - models/user.js

最近修改：
- src/routes/user.js (2 hours ago)

相关代码片段：
// src/controllers/user.js
exports.getUser = async (id) => { ... }
<!-- endcontext -->
```

### 4. 自举循环设计 (`bootstrap.js`)
描述核心自举逻辑的设计概念：读取待办任务，选择优先级最高的任务，执行对应prompt，验证结果，更新任务状态。

**设计步骤**：
1. 读取 `meta/todo.md`，解析任务列表的设计方法
2. 选择下一个任务：描述优先级算法和选择逻辑
3. 查找对应的prompt文件：文档化文件查找和匹配机制
4. 执行prompt：概述调用外部AI工具执行的流程
5. 运行验证脚本：描述测试、构建等验证过程的设计
6. 成功处理：说明状态更新和提交更改的设计
7. 失败处理：文档化错误记录和人工干预标记机制

**自动化程度设计**：
- 初期：描述人工审核每个变更的设计模式
- 中期：概述AI自动处理简单任务（文档更新、代码格式化）的设计
- 长期：说明AI处理复杂功能开发、人类负责高层次设计的架构

## 数据流设计

描述自举循环中数据流动的设计概念：

```
[待办任务] -> [选择任务] -> [加载prompt] -> [注入上下文] -> [外部AI工具执行]
     ^                                                              |
     |                                                              v
[更新状态] <- [验证结果] <- [执行脚本] <- [解析AI响应]
```

注意：这是设计概念图，描述逻辑流程，实际实现由外部AI工具完成。

## 文件格式设计说明

以下文件格式描述是**设计规范**，为外部AI工具提供实现参考。实际使用时，外部工具应遵循这些格式规范。

### Prompt 文件 (`*.md`)
采用Markdown格式，可包含元数据块。

```markdown
# 任务：添加用户登录功能

<!-- target: add-login-feature -->
<!-- priority: high -->
<!-- estimated: 2h -->

## 描述
为现有用户模块添加登录功能，需要：
- 在 `src/controllers/auth.js` 中添加 `login` 方法。
- 在 `src/routes/auth.js` 中注册 `/login` 路由。
- 使用JWT生成令牌。

## 上下文
<!-- auto-injected -->

## 输出要求
1. 修改或创建的文件列表。
2. 具体的代码变更（diff格式）。
3. 需要更新的测试文件。
```

### 任务文件 (`meta/todo.md`)
采用Markdown任务列表。

```markdown
# 待办任务

## 功能开发
- [ ] 实现prompt引擎
- [ ] 实现脚本执行器
- [ ] 添加项目初始化模板

## 文档
- [x] 编写README
- [ ] 编写架构设计文档

## 修复
- [ ] 修复Windows路径问题
```

### 配置文件 (`config/default.json`)
```json
{
  "claudeCodePath": "claude",
  "defaultModel": "claude-3-5-sonnet",
  "projectType": "nodejs",
  "templatePath": "templates",
  "autoCommit": false
}
```

## 扩展机制

### 插件系统
可以编写插件来支持不同的项目类型（React、Python、Go等）。

插件结构：
```
plugins/
└── react/
    ├── prompts/          # 领域特定prompt
    ├── scripts/          # 领域特定脚本
    ├── templates/        # 组件模板
    └── plugin.json       # 插件描述
```

### 自定义工具函数
脚本中可以加载自定义工具模块：
```javascript
const { myTool } = require('../tools/my-tool');
```

## 安全性考虑

- **沙箱执行**：脚本在受限环境中运行，禁止访问敏感目录。
- **权限控制**：Git操作前需确认，避免强制推送。
- **审计日志**：所有AI操作和脚本执行都记录日志，便于追溯。
- **密钥管理**：API密钥等敏感信息不存入prompt或脚本，使用环境变量。

## 性能优化

- **缓存**：解析的项目结构、Git历史可缓存，减少重复计算。
- **增量更新**：仅注入变更相关的上下文，减少prompt长度。
- **并行执行**：独立任务可并行执行prompt（需注意上下文隔离）。

## 未来架构演进

随着工具复杂度的增加，可能引入：

- **分布式执行**：将任务分发给多个AI实例或计算节点。
- **版本化prompt库**：prompt文件本身可版本化、比较、合并。
- **可视化编排器**：图形界面拖拽组合prompt和脚本。