6.1 KiB

Raw Blame History

MetaCraft 架构设计

设计原则

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

系统组件

1. Prompt 引擎 (`prompt-engine.js`)

负责加载、解析、执行prompt文件。

功能：

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

接口示例：

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。

示例脚本：

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，验证结果，更新任务状态。

步骤：

读取 meta/todo.md，解析任务列表。
选择下一个任务（例如“实现prompt引擎”）。
查找对应的prompt文件（prompts/implement-prompt-engine.md）。
执行prompt，生成或修改代码。
运行验证脚本（测试、构建）。
如果成功，更新任务状态为完成，并提交更改。
如果失败，记录错误，并将任务标记为需要人工干预。

自动化程度：

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

数据流

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

文件格式说明

Prompt 文件 (`*.md`)

采用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任务列表。

# 待办任务

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

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

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

配置文件 (`config/default.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       # 插件描述

自定义工具函数

脚本中可以加载自定义工具模块：

const { myTool } = require('../tools/my-tool');

安全性考虑

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

性能优化

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

未来架构演进

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

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

6.1 KiB Raw Blame History Unescape Escape