MetaCraft/docs/ARCHITECTURE.md

# MetaCraft 架构设计

## 设计原则

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

## 系统组件

### 1. Prompt 引擎 (`prompt-engine.js`)
负责加载、解析、执行prompt文件。

**功能**：
- 读取Markdown格式的prompt文件。
- 提取元数据（如`<!-- target: generate-controller -->`）。
- 注入动态上下文（当前文件树、相关代码片段、Git状态等）。
- 调用Claude Code执行prompt，获取AI响应。
- 将响应解析为具体的操作指令（创建文件、修改代码、运行命令等）。

**接口示例**：
```javascript
const { executePrompt } = require('./prompt-engine');
await executePrompt('prompts/add-feature.md', {
  projectRoot: '.',
  context: { module: 'user', type: 'controller' }
});
```

### 2. 脚本执行器 (`script-runner.js`)
统一执行Node.js脚本，提供工具函数。

**内置工具函数**：
- `fs` 增强：读写文件，保持格式。
- `git` 操作：提交、分支、对比。
- `command` 执行：运行shell命令，捕获输出。
- `template` 渲染：基于模板生成文件。
- `validation`：语法检查、测试运行、lint。

**示例脚本**：
```javascript
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前，自动将相关上下文以Markdown注释的形式插入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. 选择下一个任务（例如“实现prompt引擎”）。
3. 查找对应的prompt文件（`prompts/implement-prompt-engine.md`）。
4. 执行prompt，生成或修改代码。
5. 运行验证脚本（测试、构建）。
6. 如果成功，更新任务状态为完成，并提交更改。
7. 如果失败，记录错误，并将任务标记为需要人工干预。

**自动化程度**：
- 初期：需要人工审核每个变更。
- 中期：AI可自动处理简单任务（如文档更新、代码格式化）。
- 长期：AI可处理复杂功能开发，人类仅负责高层次设计。

## 数据流

```
[待办任务] -> [选择任务] -> [加载prompt] -> [注入上下文] -> [Claude Code执行]
     ^                                                              |
     |                                                              v
[更新状态] <- [验证结果] <- [执行脚本] <- [解析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和脚本。