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