203 lines
6.1 KiB
Markdown
203 lines
6.1 KiB
Markdown
# 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和脚本。 |