refactor: 重构项目为纯文档化架构，移除执行环境依赖

重构项目结构，将代码脚本转为AI工具描述文档，移除所有运行时依赖更新文档说明项目为设计知识库，实际执行由外部AI工具完成修改package.json移除dependencies并更新scripts为文档说明统一所有脚本文件为伪代码描述，仅供AI参考实现逻辑更新README和架构文档，明确项目为可移植的设计知识库
2025-12-09 18:01:22 +08:00 · 2025-12-09 18:01:22 +08:00 · b964a3b9d6
parent 933ec0bf47
commit b964a3b9d6
8 changed files with 531 additions and 839 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -4,91 +4,94 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-MetaCraft is an AI-powered meta-development tool that transforms software development into a series of composable, executable prompts, scripts, and documents. The project itself is developed using this toolchain, creating a bootstrapping loop that validates and optimizes the development workflow.
+MetaCraft is an AI-powered meta-development tool that transforms software development into a series of composable, executable prompts, scripts, and documents. The project adopts a **documentation-only architecture** - containing only documents, designs, and AI tool scripts, with no execution environment or runtime services. External AI tools execute the logic described in these scripts.

 ## Common Commands

-### Development Workflow
+### Development Workflow (AI Tool Reference)
+These commands describe how an external AI tool should execute development workflows. The scripts in this project are **tool descriptions** for AI reference, not executable code.
+
 ```bash
-# Run the bootstrap loop (self-development cycle)
-npm start
+# How to execute the bootstrap loop logic (self-development cycle)
+# Reference: scripts/bootstrap.js for detailed steps
+# External AI tool should implement: read todo.md, show tasks, execute prompts

-# Execute a specific prompt file
-npm run prompt -- prompts/example.md
-# or directly:
-node scripts/run-prompt.js prompts/example.md
+# How to execute a specific prompt file
+# Reference: scripts/run-prompt.js for detailed steps
+# External AI tool should implement: read prompt file, extract metadata, call Claude Code

-# Plan the next development step
-npm run plan
-# or directly:
-node scripts/plan-next.js
-
-# Check if Claude Code CLI is installed
-claude --version
+# How to plan the next development step
+# Reference: scripts/plan-next.js for detailed steps
+# External AI tool should implement: analyze project state, recommend tasks, generate files

 # View current todo tasks
 cat meta/todo.md
 ```

-### Testing
+### Testing (Design Concept)
 ```bash
-# Run tests (currently just a placeholder)
-npm test
+# Testing framework design - to be implemented by external AI tools
+# Reference: docs/ARCHITECTURE.md for testing strategy design
 ```

-### Installation
+### Installation (Project Setup)
 ```bash
-# Install dependencies (Node.js 18+ required)
-npm install
+# This project requires no installation - it's a documentation and design repository
+# Clone the repository and explore the documentation
+git clone <repository-url>
+cd MetaCraft
 ```

 ## Code Architecture

-### Core Components
+### Core Components (Design Concepts)

-**1. Prompt Engine (`scripts/run-prompt.js`)**
- Loads and parses Markdown-based prompt files
- Extracts metadata (target, priority, etc.)
- Injects dynamic context (project structure, git status)
- Calls Claude Code CLI to execute prompts
- Parses AI responses into actionable operations
+**1. Prompt Engine Design** (`scripts/run-prompt.js`)
+- Describes how to parse Markdown-based prompt files
+- Explains metadata extraction (target, priority, etc.)
+- Outlines context injection (project structure, git status)
+- Provides guidance on calling external AI tools
+- Documents response parsing into actionable operations

-**2. Bootstrap Loop (`scripts/bootstrap.js`)**
- Reads todo list from `meta/todo.md`
- Prompts user to select a pending task
- Finds corresponding prompt file
- Executes the prompt via `run-prompt.js`
- Updates task status after verification
+**2. Bootstrap Loop Design** (`scripts/bootstrap.js`)
+- Describes reading todo list from `meta/todo.md`
+- Explains user interaction for task selection
+- Documents prompt file lookup logic
+- Outlines prompt execution steps via external tools
+- Provides task status update procedures

-**3. Plan Next Step (`scripts/plan-next.js`)**
- Analyzes current project state (completed vs pending tasks)
- Recommends next task based on priority and category
- Generates prompt files for recommended tasks
- Creates detailed next-step planning documents
+**3. Plan Next Step Design** (`scripts/plan-next.js`)
+- Describes project state analysis (completed vs pending tasks)
+- Documents task recommendation algorithms based on priority and category
+- Explains prompt file generation logic
+- Outlines next-step planning document creation

-**4. Context Manager (conceptual)**
- Maintains project state and structure
- Provides relevant context to AI during prompt execution
- Tracks dependencies, recent changes, and task history
+**4. Context Manager Design** (conceptual)
+- Describes project state maintenance strategies
+- Documents context provision techniques for AI during prompt execution
+- Explains dependency tracking and change history management
+
+Note: These are design documents for AI reference, not executable code.

 ### Directory Structure
 ```
 MetaCraft/
 ├── prompts/          # Prompt library for tasks
 │   └── example.md   # Example: creates welcome.js
-├── scripts/          # Core automation scripts
-│   ├── run-prompt.js # Executes prompts via Claude Code
-│   └── bootstrap.js  # Self-development cycle
+├── scripts/          # AI tool scripts (design documents, not executable)
+│   ├── run-prompt.js   # Prompt execution logic description
+│   ├── bootstrap.js    # Bootstrap loop design document
+│   └── plan-next.js    # Next-step planning design document
 ├── docs/             # Project documentation
-│   ├── ARCHITECTURE.md    # Detailed architecture
+│   ├── ARCHITECTURE.md    # Detailed architecture design
 │   ├── GETTING_STARTED.md # Quick start guide
 │   └── next-steps/    # Auto-generated next step plans
 ├── meta/             # Tool metadata
 │   └── todo.md      # Pending development tasks
 ├── config/           # Configuration (currently empty)
 ├── templates/        # File templates (currently empty)
-├── package.json
-└── README.md
+├── package.json      # Project metadata (dependencies are design references)
+└── README.md         # Project overview and architecture
 ```

 ## Key Files
@ -115,86 +118,110 @@ Auto-injected project context
 Expected deliverables
 ```

-### Scripts
- **`run-prompt.js`**: Accepts a prompt file path, validates Claude Code CLI, executes prompt, displays AI response
- **`bootstrap.js`**: Interactive loop for self-development - shows pending tasks, executes selected prompt, updates todo.md
- **`plan-next.js`**: Analyzes project state, recommends next task, generates prompt files and planning documents
+### Scripts (AI Tool Descriptions)
+- **`run-prompt.js`**: Describes how to execute a prompt file - file validation, metadata extraction, external AI tool invocation
+- **`bootstrap.js`**: Documents the self-development loop logic - task listing, user interaction, prompt execution, status updates
+- **`plan-next.js`**: Outlines project state analysis and next-step planning - task recommendation algorithms, file generation procedures

 ## Development Workflow

-### Bootstrapping Process
-1. View pending tasks: `cat meta/todo.md`
-2. Run bootstrap loop: `npm start`
-3. Select a task number
-4. Tool finds corresponding prompt file in `prompts/`
-5. Executes prompt via Claude Code CLI
-6. Review AI-generated output
-7. Mark task as complete (updates `meta/todo.md`)
+### Bootstrapping Process (Design Logic)
+1. View pending tasks: Read `meta/todo.md`
+2. Bootstrap loop logic: Reference `scripts/bootstrap.js` for implementation steps
+3. Select a task number: User interaction design
+4. Find corresponding prompt file: File lookup algorithm in `prompts/` directory
+5. Execute prompt: Call external AI tool (e.g., Claude Code) following `scripts/run-prompt.js` guidelines
+6. Review AI-generated output: Result processing and validation
+7. Mark task as complete: Update `meta/todo.md` status

-### Adding New Tasks
+### Adding New Tasks (Design Logic)
 1. Edit `meta/todo.md` and add a new unchecked task: `- [ ] Task description`
 2. Create corresponding prompt file in `prompts/` (optional)
   - Filename should relate to task (e.g., `implement-prompt-engine.md`)
-3. Run bootstrap loop to execute
+3. Execute via bootstrap loop logic: Reference `scripts/bootstrap.js` for implementation

-### Planning Next Steps
-1. Run `npm run plan` to analyze project state and get task recommendations
+### Planning Next Steps (Design Logic)
+1. Analyze project state: Reference `scripts/plan-next.js` for recommendation algorithms
 2. Choose an action: generate prompt file, planning document, or both
 3. Review generated files and adjust as needed
-4. Execute the task using `npm start` or directly via `run-prompt.js`
+4. Execute the task: Use external AI tools following the described logic

-### Example: Running the Example Prompt
+### Example: Running the Example Prompt (Design Logic)
 ```bash
-# Execute the example prompt
-node scripts/run-prompt.js prompts/example.md
+# How to execute the example prompt:
+# 1. Reference scripts/run-prompt.js for execution logic
+# 2. Read prompts/example.md for prompt content
+# 3. Call external AI tool to execute the prompt

-# This creates welcome.js with a timestamped welcome message
-node welcome.js  # Run the generated script
+# Expected outcome:
+# - AI generates welcome.js with timestamped welcome message
+# - External tool can then execute welcome.js
 ```

-## Dependencies
+## Dependencies (Design References)

-### Runtime Dependencies
- **commander**: CLI argument parsing
- **fs-extra**: Enhanced file system operations
- **marked**: Markdown parsing
- **simple-git**: Git operations
+### Design Dependency Descriptions
+- **commander**: CLI argument parsing design pattern reference
+- **fs-extra**: Enhanced file system operation design patterns
+- **marked**: Markdown parsing design approach
+- **simple-git**: Git operation design patterns

-### Requirements
- Node.js 18+
- Claude Code CLI installed and configured
- Git
+### Implementation Requirements
+- **External AI Tool**: For actual execution (e.g., Claude Code, other AI assistants)
+- **File System Access**: Required by external tools to read project files
+- **Git**: For version control of the design documents
+
+Note: This project contains no runtime dependencies or execution environment. The dependencies listed are **design references** describing how external tools should implement similar functionality.

 ## Important Notes

+### Architecture Philosophy
+MetaCraft follows a **documentation-only architecture**:
+- **No execution environment**: Scripts are design documents, not executable code
+- **External tool execution**: All logic is implemented by external AI tools (e.g., Claude Code)
+- **Portable knowledge**: Designs can be referenced by any AI system
+- **Self-development concept**: The toolchain describes how to develop itself
+
 ### Current Implementation Status
- Core infrastructure exists with bootstrap loop, prompt execution, and planning functionality
- Core components (prompt-engine, script-runner, context-manager) are not yet implemented
- Bootstrap loop, prompt execution, and plan-next are functional prototypes
- Project is in early development phase (v0.0.1)
+- **Design documents complete**: Bootstrap loop, prompt execution, and planning logic are fully documented
+- **No runtime components**: Core components (prompt-engine, script-runner, context-manager) exist only as design concepts
+- **Pure documentation**: All scripts are descriptive, not functional
+- **Version**: Design phase v0.0.1

-### Prompt Execution
- Requires Claude Code CLI to be installed and in PATH
- If Claude Code is unavailable, the script outputs the prompt content for manual execution
- Prompts are written to `.temp/` directory during execution
+### Prompt Execution (Design Concept)
+- **External tool requirement**: Execution requires external AI tools, not built-in runtime
+- **Logic description**: `scripts/run-prompt.js` describes how to validate, extract metadata, and invoke AI tools
+- **Temporary files**: Design includes `.temp/` directory concept for intermediate files

-### File Generation
- Prompts can generate files (like `welcome.js` from the example)
- Generated files are gitignored (see `.gitignore`)
+### File Generation (Design Concept)
+- **AI-generated artifacts**: Prompts can describe file generation (e.g., `welcome.js` from example)
+- **Git integration**: Generated files would be gitignored in actual implementations

-### Self-Development
-This project uses itself to develop itself. The bootstrap loop:
-1. Reads tasks from `meta/todo.md`
-2. Executes corresponding prompts
-3. Lets AI generate or modify code
-4. Updates task status
+### Self-Development (Design Concept)
+This project describes a self-development methodology. The bootstrap loop design:
+1. Describes reading tasks from `meta/todo.md`
+2. Documents executing corresponding prompts via external tools
+3. Outlines AI code generation and modification processes
+4. Provides status update procedures

-This creates a closed loop where the tool improves its own capabilities.
+This creates a **design for a closed loop** where tools could theoretically improve themselves.

 ## Documentation

-Key documentation files provide different perspectives:
- **README.md**: Vision, core concepts, quick overview
- **docs/ARCHITECTURE.md**: Detailed technical architecture, component design
- **docs/GETTING_STARTED.md**: Step-by-step setup and usage guide
- **meta/todo.md**: Current development priorities and status
+This project consists entirely of design documentation and AI tool descriptions:
+
+### Core Design Documents
+- **README.md**: Project vision, architecture philosophy, and overview
+- **docs/ARCHITECTURE.md**: Detailed technical architecture design and component specifications
+- **docs/GETTING_STARTED.md**: Design implementation guide and conceptual setup
+
+### Development Planning
+- **meta/todo.md**: Design task tracking and development priorities
+- **docs/next-steps/**: Auto-generated next-step planning documents (design concepts)
+
+### AI Tool Scripts (Design References)
+- **scripts/run-prompt.js**: Prompt execution logic description
+- **scripts/bootstrap.js**: Bootstrap loop design document
+- **scripts/plan-next.js**: Next-step planning design document
+
+All content is **design documentation** meant to be referenced by external AI tools for implementation guidance.
--- a/README.md
+++ b/README.md
@ -4,7 +4,18 @@

 MetaCraft 是一个基于AI大语言模型的元开发工具，旨在辅助任意大型项目的开发。其核心思想是：**将软件开发过程转化为一系列可组合、可执行的prompt、脚本和文档**，并通过Claude Code与AI智能体协作，实现项目的迭代构建。

-更特别的是，MetaCraft 项目本身也使用这套工具进行开发，形成“自举”（bootstrapping）的闭环，从而验证和优化工具链的有效性。
+更特别的是，MetaCraft 项目本身也使用这套工具进行开发，形成"自举"（bootstrapping）的闭环，从而验证和优化工具链的有效性。
+
+## 架构理念
+
+MetaCraft 采用**纯文档化架构**：项目仅包含文档、设计说明和AI工具脚本，不包含任何执行环境或运行服务。
+
+- **文档**：Markdown格式的设计文档、架构说明、使用指南
+- **设计**：系统组件设计、接口规范、工作流描述
+- **工具脚本**：JavaScript文件描述自动化逻辑，供AI参考执行
+- **执行分离**：具体执行由外部AI工具（如Claude Code）完成
+
+这种架构使得MetaCraft成为**可移植的知识库**，任何AI系统都可以参考其中的设计来实现类似功能。

 ## 核心概念

@ -14,9 +25,9 @@ MetaCraft 是一个基于AI大语言模型的元开发工具，旨在辅助任
 - 开发者与AI的对话历史成为项目演进的可追溯记录。

 ### 2. 可执行的知识 (Executable Knowledge)
- **Node.js 脚本** 用于自动化重复操作（如文件生成、测试运行、依赖安装）。
+- **AI工具脚本** 描述自动化操作的逻辑和步骤，供AI参考执行（如文件生成、测试运行、依赖安装）。
 - **Markdown 文档** 记录设计决策、架构说明、使用指南，同时也可作为AI的上下文输入。
- **Claude Code 执行** 作为与AI交互的桥梁，执行prompt并获取结果。
+- **外部AI工具执行** 实际执行由外部AI工具（如Claude Code）完成，本项目不包含执行环境。

 ### 3. 自举 (Bootstrapping)
 - MetaCraft 工具链本身通过MetaCraft定义的工作流进行开发。
@ -32,11 +43,10 @@ MetaCraft/
 │   ├── feature-add.md
 │   ├── bug-fix.md
 │   └── refactor.md
-├── scripts/          # Node.js 自动化脚本
-│   ├── generate.js
-│   ├── validate.js
-│   ├── deploy.js
-│   └── bootstrap.js  # 自举脚本
+├── scripts/          # AI工具脚本（供AI参考，不包含执行环境）
+│   ├── run-prompt.js   # 执行prompt文件的逻辑描述
+│   ├── bootstrap.js    # 自举循环的逻辑描述
+│   └── plan-next.js    # 规划下一步的逻辑描述
 ├── docs/             # 项目文档
 │   ├── ARCHITECTURE.md
 │   ├── WORKFLOW.md
@ -49,19 +59,21 @@ MetaCraft/
    └── manifest.json # 描述工具组件及依赖
 ```

-### 核心组件
+### 核心组件（设计概念）

-1. **Prompt 引擎**：解析prompt文件，注入上下文变量，调用Claude Code执行。
-2. **脚本执行器**：运行Node.js脚本，提供统一的API用于文件操作、Git操作、命令执行等。
-3. **上下文管理器**：维护项目状态（如当前模块、依赖关系、待办任务），为AI提供连贯的上下文。
-4. **自举循环**：一个内置的工作流，用于更新工具自身——检测新需求，生成prompt，执行脚本，验证变更。
+1. **Prompt 引擎**：描述如何解析prompt文件，注入上下文变量，调用外部AI工具执行。
+2. **脚本执行器**：描述如何运行自动化脚本的逻辑，提供文件操作、Git操作、命令执行等步骤说明。
+3. **上下文管理器**：描述如何维护项目状态（如当前模块、依赖关系、待办任务），为AI提供连贯的上下文。
+4. **自举循环**：描述一个自举工作流——检测新需求，生成prompt，执行脚本，验证变更。
+
+注意：这些组件是设计概念和逻辑描述，实际执行由外部AI工具完成，本项目不包含执行环境。

 ## 快速开始

 ### 前提条件
- Node.js 18+
- Claude Code CLI 已安装并配置
- Git
+- 外部AI工具（如Claude Code CLI）用于实际执行
+- Git（用于版本控制）
+- 注意：本项目不包含执行环境，scripts目录下的脚本是供AI参考的工具描述

 ### 初始化新项目
 ```bash
@ -71,13 +83,13 @@ npx meta-cli init my-project

 ### 开发一个功能
 1. 在 `prompts/` 下创建一个新的prompt文件，描述功能需求。
-2. 运行 `node scripts/run-prompt.js prompts/my-feature.md`，让AI生成代码草案。
+2. 让AI参考 `scripts/run-prompt.js` 中的逻辑描述来执行prompt，生成代码草案。
 3. 审查生成的代码，运行测试，提交更改。

 ### 参与MetaCraft自举开发
 1. 查看 `meta/todo.md` 获取待开发任务。
 2. 选择任务，在 `prompts/` 中编写或更新prompt。
-3. 执行 `node scripts/bootstrap.js` 启动自举循环，AI将协助实现该任务。
+3. 让AI参考 `scripts/bootstrap.js` 中的自举循环逻辑来执行任务。
 4. 提交Pull Request。

 ## 工作流示例
@ -85,9 +97,9 @@ npx meta-cli init my-project
 假设要添加一个REST API端点：

 1. **任务描述**：创建 `prompts/add-rest-endpoint.md`，描述端点路径、方法、参数、返回类型。
-2. **上下文注入**：工具自动注入现有项目结构、相关模块的代码片段。
-3. **AI执行**：Claude Code读取prompt，生成或修改控制器、路由、模型文件。
-4. **脚本验证**：运行 `node scripts/validate.js` 检查语法、运行单元测试。
+2. **上下文注入**：AI参考项目结构、相关模块的代码片段作为上下文。
+3. **AI执行**：外部AI工具（如Claude Code）读取prompt，生成或修改控制器、路由、模型文件。
+4. **脚本验证**：AI参考验证逻辑描述来检查语法、运行单元测试。
 5. **文档更新**：AI同时更新API文档，记录新端点。

 ## 贡献指南
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@ -1,5 +1,16 @@
 # MetaCraft 架构设计

+## 架构理念
+
+MetaCraft 采用**纯文档化架构**：项目仅包含设计文档和AI工具脚本描述，不包含任何执行环境或运行服务。
+
+- **设计文档**：Markdown格式的架构设计、组件规范、接口定义
+- **AI工具脚本**：JavaScript文件描述自动化逻辑，供AI参考执行
+- **执行分离**：具体实现由外部AI工具（如Claude Code）完成
+- **可移植知识**：任何AI系统都可以参考这些设计实现类似功能
+
+所有组件描述都是**设计概念**，不是可执行代码。实际运行时需要外部AI工具根据这些设计进行实现。
+
 ## 设计原则

 1. **可自举**：工具链必须能够描述和实现自身的演进。
@ -10,18 +21,19 @@

 ## 系统组件

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

-**功能**：
- 读取Markdown格式的prompt文件。
- 提取元数据（如`<!-- target: generate-controller -->`）。
- 注入动态上下文（当前文件树、相关代码片段、Git状态等）。
- 调用Claude Code执行prompt，获取AI响应。
- 将响应解析为具体的操作指令（创建文件、修改代码、运行命令等）。
+**设计功能**：
+- 描述读取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: '.',
@ -29,18 +41,19 @@ await executePrompt('prompts/add-feature.md', {
 });
 ```

-### 2. 脚本执行器 (`script-runner.js`)
-统一执行Node.js脚本，提供工具函数。
+### 2. 脚本执行器设计 (`script-runner.js`)
+描述统一执行自动化脚本的设计概念。

-**内置工具函数**：
- `fs` 增强：读写文件，保持格式。
- `git` 操作：提交、分支、对比。
- `command` 执行：运行shell命令，捕获输出。
- `template` 渲染：基于模板生成文件。
- `validation`：语法检查、测试运行、lint。
+**设计工具函数**：
+- `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');
@ -49,18 +62,18 @@ module.exports = async (args) => {
 };
 ```

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

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

-**上下文注入**：
-在执行prompt前，自动将相关上下文以Markdown注释的形式插入prompt中，例如：
+**上下文注入设计**：
+描述在执行prompt前自动注入相关上下文的设计模式，例如：
 ```
 <!-- context -->
 项目结构：
@ -77,33 +90,39 @@ exports.getUser = async (id) => { ... }
 <!-- endcontext -->
 ```

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

-**步骤**：
-1. 读取 `meta/todo.md`，解析任务列表。
-2. 选择下一个任务（例如“实现prompt引擎”）。
-3. 查找对应的prompt文件（`prompts/implement-prompt-engine.md`）。
-4. 执行prompt，生成或修改代码。
-5. 运行验证脚本（测试、构建）。
-6. 如果成功，更新任务状态为完成，并提交更改。
-7. 如果失败，记录错误，并将任务标记为需要人工干预。
+**设计步骤**：
+1. 读取 `meta/todo.md`，解析任务列表的设计方法
+2. 选择下一个任务：描述优先级算法和选择逻辑
+3. 查找对应的prompt文件：文档化文件查找和匹配机制
+4. 执行prompt：概述调用外部AI工具执行的流程
+5. 运行验证脚本：描述测试、构建等验证过程的设计
+6. 成功处理：说明状态更新和提交更改的设计
+7. 失败处理：文档化错误记录和人工干预标记机制

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

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

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

-## 文件格式说明
+注意：这是设计概念图，描述逻辑流程，实际实现由外部AI工具完成。
+
+## 文件格式设计说明
+
+以下文件格式描述是**设计规范**，为外部AI工具提供实现参考。实际使用时，外部工具应遵循这些格式规范。

 ### Prompt 文件 (`*.md`)
 采用Markdown格式，可包含元数据块。
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@ -1,118 +1,111 @@
 # 快速开始

-本指南将帮助你快速上手 MetaCraft，包括安装、运行第一个 prompt，以及参与自举开发。
+本指南介绍 MetaCraft 的设计概念和使用方法。**重要提示**：MetaCraft 是一个纯文档化架构项目，包含设计文档和AI工具脚本描述，不包含任何执行环境或运行服务。所有逻辑实现由外部AI工具完成。

-## 安装
+## 项目设置

-### 1. 克隆仓库
+### 1. 克隆仓库（获取设计文档）
 ```bash
 git clone https://github.com/your-username/metacraft.git
 cd metacraft
 ```

-### 2. 安装依赖
-```bash
-npm install
-```
+### 2. 了解项目结构
+MetaCraft 包含以下设计文档：
+- **架构设计** (`docs/ARCHITECTURE.md`)：详细技术架构和组件设计
+- **AI工具脚本** (`scripts/`)：描述自动化逻辑的实现方法
+- **任务管理** (`meta/todo.md`)：开发任务跟踪和优先级

-### 3. 安装 Claude Code CLI
-确保已安装 Claude Code CLI 并配置好 API 密钥。请参考 [Claude Code 官方文档](https://claude.com/claude-code)。
+### 3. 外部工具准备
+实际执行需要外部AI工具（如 Claude Code CLI）。请参考相应工具的安装文档。

-验证安装：
+验证外部工具：
 ```bash
 claude --version
 ```

-## 运行第一个 Prompt
+## 理解 Prompt 执行设计

-### 步骤
-1. **查看示例 prompt**：打开 `prompts/example.md`，这是一个简单的任务：创建欢迎脚本。
-2. **执行 prompt**：
-   ```bash
-   npm run prompt -- prompts/example.md
-   ```
-   或者直接使用 Node.js：
-   ```bash
-   node scripts/run-prompt.js prompts/example.md
-   ```
-3. **与 AI 交互**：脚本会调用 Claude Code，AI 将生成 `welcome.js` 文件。按照提示操作。
-4. **验证结果**：检查生成的 `welcome.js` 文件，并运行它：
-   ```bash
-   node welcome.js
-   ```
+### 设计概念
+Prompt 执行流程在 `scripts/run-prompt.js` 中描述。这是一个**设计文档**，说明如何：

-## 自举开发流程
+1. **读取 prompt 文件**：解析 Markdown 格式的 prompt
+2. **提取元数据**：识别任务目标、优先级等信息
+3. **注入上下文**：为 AI 提供项目状态和相关代码
+4. **调用外部 AI 工具**：执行 prompt 并获取响应
+5. **解析 AI 输出**：将响应转换为具体操作

-MetaCraft 的核心是自举（bootstrapping）——使用工具自身来开发工具。
+### 参考示例
+1. **查看示例 prompt**：打开 `prompts/example.md`，这是一个描述创建欢迎脚本任务的设计示例。
+2. **理解执行逻辑**：阅读 `scripts/run-prompt.js` 了解 prompt 执行的设计思路。
+3. **外部工具实现**：外部 AI 工具应参考此设计来实现实际执行。
+4. **预期结果**：设计预期 AI 会生成 `welcome.js` 文件，外部工具可执行该文件。

-### 1. 查看待办任务
-```bash
-cat meta/todo.md
-```
-或者运行自举循环查看：
-```bash
-npm start
-```
+## 自举开发设计概念

-### 2. 选择一个任务
-例如“实现prompt引擎”。找到或创建对应的 prompt 文件（`prompts/implement-prompt-engine.md`）。
+MetaCraft 的核心是自举（bootstrapping）设计——描述如何使用工具自身来开发工具。

-### 3. 编写 Prompt
-Prompt 应清晰描述任务目标、上下文、输出要求。参考已有示例。
+### 1. 任务管理设计
+- **待办任务格式**：`meta/todo.md` 描述任务跟踪的设计格式
+- **优先级系统**：文档化任务分类和优先级映射逻辑
+- **状态更新**：描述任务完成标记的设计机制

-### 4. 执行自举循环
-```bash
-npm start
-```
-选择任务编号，工具将自动执行对应 prompt，并调用 AI 生成代码。
+### 2. Prompt 查找设计
+描述如何根据任务描述查找对应 prompt 文件的逻辑：
+- 文件名匹配算法
+- 目录搜索机制
+- 备用路径策略

-### 5. 验证与提交
- 运行测试（待实现）。
- 确保构建通过。
- 提交更改到 Git。
+### 3. 自举循环设计
+`scripts/bootstrap.js` 描述自举循环的设计概念：
+- 任务列表显示逻辑
+- 用户交互设计
+- 外部工具调用流程
+- 结果验证和状态更新设计

-### 6. 更新任务状态
-自举循环会询问是否标记任务为完成。确认后，`meta/todo.md` 中对应任务将被勾选。
+### 4. 设计工作流
+1. **设计参考**：阅读 `scripts/bootstrap.js` 了解自举循环设计
+2. **外部实现**：AI工具参考此设计实现实际自举功能
+3. **验证设计**：按照设计描述的验证步骤检查结果
+4. **状态更新**：外部工具应遵循设计中的状态更新逻辑

 ## 项目结构速查

 ```
 metacraft/
-├── prompts/          # 任务prompt库
-│   └── example.md   # 示例prompt
-├── scripts/         # 核心脚本
-│   ├── run-prompt.js # 执行prompt
-│   └── bootstrap.js  # 自举循环
-├── docs/            # 文档
-│   ├── ARCHITECTURE.md
-│   └── GETTING_STARTED.md
-├── meta/            # 元数据
-│   └── todo.md      # 待办任务
-├── config/          # 配置（暂无）
-├── templates/       # 模板（暂无）
-└── package.json
+├── prompts/          # 任务prompt设计库
+│   └── example.md   # 示例prompt设计
+├── scripts/         # AI工具脚本设计文档
+│   ├── run-prompt.js # Prompt执行逻辑设计描述
+│   ├── bootstrap.js  # 自举循环设计文档
+│   └── plan-next.js  # 规划下一步设计文档
+├── docs/            # 设计文档
+│   ├── ARCHITECTURE.md    # 详细架构设计
+│   └── GETTING_STARTED.md # 设计概念快速开始
+├── meta/            # 设计元数据
+│   └── todo.md      # 设计任务跟踪
+├── config/          # 配置设计（暂无）
+├── templates/       # 模板设计（暂无）
+└── package.json     # 项目元数据（设计依赖参考）
 ```

 ## 常见问题

-### Claude Code 命令未找到
-确保已正确安装 Claude Code CLI，并且 `claude` 命令在 PATH 中。
+### MetaCraft 项目为什么不包含可执行代码？
+MetaCraft 采用纯文档化架构，仅包含设计文档和AI工具脚本描述。实际执行由外部AI工具完成，使得设计知识可移植到不同AI系统。

-### 执行 prompt 时卡住
-可能是 Claude Code 需要交互式输入。尝试手动运行：
-```bash
-claude --file prompts/example.md
-```
+### 如何使用这些设计文档？
+外部AI工具应参考设计文档实现类似功能。例如，Claude Code可以参考 `scripts/run-prompt.js` 中的逻辑描述来实现prompt执行。

-### 如何添加新任务？
+### 如何添加新的设计任务？
 1. 在 `meta/todo.md` 中添加一行 `- [ ] 任务描述`。
-2. 在 `prompts/` 中创建对应的 prompt 文件（可选）。如果不存在，自举循环会提示创建。
+2. 在 `prompts/` 中创建对应的prompt设计文件（可选），描述任务需求和实现方法。

-### 如何修改脚本行为？
-直接编辑 `scripts/` 下的文件。修改后，可以运行 `npm test` 验证（测试待实现）。
+### 如何理解脚本设计文档？
+`scripts/` 目录下的文件是**设计描述**，不是可执行代码。它们描述逻辑流程、算法步骤和实现方法，供外部AI工具参考实现。

 ## 下一步

- 阅读 [ARCHITECTURE.md](ARCHITECTURE.md) 了解设计细节。
- 尝试修改 `prompts/example.md` 并观察效果。
- 参与开发：选择一个待办任务，编写 prompt 并提交 Pull Request。
+- 阅读 [ARCHITECTURE.md](ARCHITECTURE.md) 了解详细架构设计。
+- 参考 `scripts/` 目录中的设计文档理解实现逻辑。
+- 参与设计改进：选择一个待办任务，更新设计文档并提交 Pull Request。
--- a/package.json
+++ b/package.json
@ -1,23 +1,17 @@
 {
  "name": "metacraft",
  "version": "0.0.1",
-  "description": "AI-Powered Meta-Development Tool",
+  "description": "AI-Powered Meta-Development Tool - Documentation and Design Repository (No Execution Environment)",
  "main": "index.js",
  "scripts": {
-    "start": "node scripts/bootstrap.js",
-    "prompt": "node scripts/run-prompt.js",
-    "plan": "node scripts/plan-next.js",
-    "test": "echo \"No tests yet\" && exit 0"
+    "start": "echo 'Bootstrap loop design - see scripts/bootstrap.js for implementation logic'",
+    "prompt": "echo 'Prompt execution design - see scripts/run-prompt.js for implementation logic'",
+    "plan": "echo 'Plan next step design - see scripts/plan-next.js for implementation logic'",
+    "test": "echo 'Testing framework design - see docs/ARCHITECTURE.md for design concepts'"
  },
  "keywords": ["ai", "development", "tooling", "bootstrapping"],
  "author": "",
  "license": "MIT",
-  "dependencies": {
-    "commander": "^11.0.0",
-    "fs-extra": "^11.1.1",
-    "marked": "^12.0.0",
-    "simple-git": "^3.19.0"
-  },
  "devDependencies": {
    "@types/node": "^20.0.0"
  },
--- a/scripts/bootstrap.js
+++ b/scripts/bootstrap.js
@ -1,176 +1,87 @@
-#!/usr/bin/env node
-
 /**
- * bootstrap.js - MetaCraft 自举循环入口
+ * bootstrap.js - MetaCraft 自举循环AI工具脚本
 *
- * 1. 读取待办任务列表
- * 2. 显示可选任务
- * 3. 执行选中的任务（调用对应prompt）
- * 4. 验证结果并更新任务状态
+ * 此脚本描述MetaCraft的自举循环逻辑，供AI参考使用。
+ * 实际执行由外部AI工具完成，本项目不包含执行环境。
+ *
+ * 功能描述：
+ * 1. 读取待办任务列表（meta/todo.md）
+ * 2. 解析任务分类和状态
+ * 3. 显示未完成的任务供用户选择
+ * 4. 查找与选中任务对应的prompt文件
+ * 5. 调用run-prompt执行选中的prompt
+ * 6. 询问用户是否标记任务为完成，并更新任务状态
+ *
+ * 输入：无（交互式）
+ * 输出：执行选中的prompt任务，更新任务状态
+ *
+ * 伪代码逻辑：
 */

-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
+// 主函数：自举循环入口
+// 返回：无（交互式流程）
+function bootstrapLoop() {
+  // 步骤1：读取待办任务文件
+  // 使用文件系统API读取meta/todo.md内容

-const TODO_FILE = path.join(__dirname, '../meta/todo.md');
-const PROMPTS_DIR = path.join(__dirname, '../prompts');
+  // 步骤2：解析任务
+  // 调用parseTodo函数解析任务列表，得到tasks数组

-// 解析待办任务文件
-function parseTodo(content) {
-  const lines = content.split('\n');
-  const tasks = [];
-  let currentCategory = '';
+  // 步骤3：筛选未完成的任务
+  // 过滤出checked为false的任务，得到pendingTasks

-  for (const line of lines) {
-    const categoryMatch = line.match(/^##\s+(.+)/);
-    if (categoryMatch) {
-      currentCategory = categoryMatch[1].trim();
-      continue;
-    }
+  // 步骤4：显示任务列表
+  // 格式化输出每个未完成任务的序号、类别和描述

-    const taskMatch = line.match(/^- \[( |x)\]\s+(.+)/);
-    if (taskMatch) {
-      const checked = taskMatch[1] === 'x';
-      const description = taskMatch[2].trim();
-      tasks.push({
-        category: currentCategory,
-        description,
-        checked,
-        raw: line
-      });
-    }
-  }
+  // 步骤5：获取用户选择
+  // 通过命令行交互询问用户选择任务编号或跳过

-  return tasks;
+  // 步骤6：查找对应的prompt文件
+  // 调用findPromptForTask函数，根据任务描述查找prompt文件
+  // 如果未找到，提示用户创建
+
+  // 步骤7：执行prompt
+  // 调用executePromptFile函数（来自run-prompt.js）执行找到的prompt文件
+
+  // 步骤8：确认完成状态
+  // 询问用户任务是否已完成，如果是则调用updateTodo更新任务状态
+
+  // 注意：此函数为伪代码描述，实际实现由外部AI工具完成
 }

-// 更新待办任务文件
-function updateTodo(tasks, updatedTask) {
-  // 简化的实现：找到对应行并替换
-  const content = fs.readFileSync(TODO_FILE, 'utf-8');
-  const lines = content.split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].includes(updatedTask.description)) {
-      const newLine = lines[i].replace('- [ ]', '- [x]');
-      lines[i] = newLine;
-      break;
-    }
-  }
-  fs.writeFileSync(TODO_FILE, lines.join('\n'), 'utf-8');
+// 辅助函数：解析待办任务内容
+// 参数：todoContent - 待办任务文件的文本内容
+// 返回：任务对象数组，每个对象包含category, description, checked, raw等属性
+function parseTodo(todoContent) {
+  // 按行分割内容
+  // 遍历每一行，识别分类标题（## 分类名）
+  // 识别任务项（- [ ] 任务描述 或 - [x] 任务描述）
+  // 构建任务对象并添加到数组
+  // 返回任务数组
 }

-// 查找对应prompt文件
+// 辅助函数：查找任务对应的prompt文件
+// 参数：task - 任务对象
+// 返回：prompt文件路径或null
 function findPromptForTask(task) {
-  // 简单映射：将任务描述转换为文件名
-  const name = task.description
-    .toLowerCase()
-    .replace(/[^\w\s]/g, '')
-    .replace(/\s+/g, '-');
-  const possiblePaths = [
-    path.join(PROMPTS_DIR, `${name}.md`),
-    path.join(PROMPTS_DIR, `implement-${name}.md`),
-    path.join(PROMPTS_DIR, `task-${name}.md`)
-  ];
-
-  for (const p of possiblePaths) {
-    if (fs.existsSync(p)) {
-      return p;
-    }
-  }
-  return null;
+  // 将任务描述转换为kebab-case文件名
+  // 尝试多种可能的文件名格式：
+  //   - 直接使用描述转换
+  //   - 添加implement-前缀
+  //   - 添加task-前缀
+  // 检查prompts目录下是否存在对应文件
+  // 返回找到的路径，否则返回null
 }

-async function main() {
-  console.log('🚀 MetaCraft 自举循环启动\n');
-
-  if (!fs.existsSync(TODO_FILE)) {
-    console.error('❌ 待办任务文件不存在：', TODO_FILE);
-    process.exit(1);
-  }
-
-  const todoContent = fs.readFileSync(TODO_FILE, 'utf-8');
-  const tasks = parseTodo(todoContent);
-  const pendingTasks = tasks.filter(t => !t.checked);
-
-  if (pendingTasks.length === 0) {
-    console.log('🎉 所有任务已完成！');
-    return;
-  }
-
-  console.log('📋 待办任务列表：');
-  pendingTasks.forEach((task, index) => {
-    console.log(`  ${index + 1}. [${task.category}] ${task.description}`);
-  });
-
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-
-  function askQuestion(query) {
-    return new Promise(resolve => {
-      rl.question(query, answer => {
-        resolve(answer);
-      });
-    });
-  }
-
-  const answer = await askQuestion('\n请输入要执行的任务编号（或按回车跳过）：');
-  rl.close();
-
-  if (!answer.trim()) {
-    console.log('⏭️  跳过任务选择');
-    return;
-  }
-
-  const taskIndex = parseInt(answer) - 1;
-  if (isNaN(taskIndex) || taskIndex < 0 || taskIndex >= pendingTasks.length) {
-    console.error('❌ 无效的选择');
-    process.exit(1);
-  }
-
-  const selectedTask = pendingTasks[taskIndex];
-  console.log(`\n🎯 选中任务：${selectedTask.description}`);
-
-  const promptPath = findPromptForTask(selectedTask);
-  if (!promptPath) {
-    console.error(`❌ 未找到对应prompt文件，请在 ${PROMPTS_DIR} 中创建。`);
-    console.log('提示：prompt文件名应与任务描述相关，如 "implement-prompt-engine.md"');
-    return;
-  }
-
-  console.log(`📄 找到prompt文件：${promptPath}`);
-
-  // 执行prompt
-  const { main: runPrompt } = require('./run-prompt');
-  await runPrompt([promptPath]);
-
-  // 询问是否标记为完成
-  const confirm = await new Promise(resolve => {
-    const confirmRl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout
-    });
-    confirmRl.question('\n✅ 任务是否已完成？(y/n) ', answer => {
-      confirmRl.close();
-      resolve(answer.toLowerCase() === 'y');
-    });
-  });
-
-  if (confirm) {
-    updateTodo(tasks, selectedTask);
-    console.log('📝 已更新待办任务状态');
-  } else {
-    console.log('⚠️  任务状态未更新，请手动处理');
-  }
+// 辅助函数：更新待办任务状态
+// 参数：tasks - 所有任务数组，updatedTask - 要更新的任务对象
+// 返回：无（直接写入文件）
+function updateTodo(tasks, updatedTask) {
+  // 读取待办任务文件内容
+  // 找到对应任务描述的行
+  // 将- [ ]替换为- [x]标记为完成
+  // 将更新后的内容写回文件
 }

-if (require.main === module) {
-  main().catch(err => {
-    console.error('自举循环错误：', err);
-    process.exit(1);
-  });
-}
-
-module.exports = { parseTodo, findPromptForTask };
+// 导出函数供AI参考
+// 注意：这些函数不会实际执行，仅作为文档说明
--- a/scripts/plan-next.js
+++ b/scripts/plan-next.js
@ -1,20 +1,20 @@
-#!/usr/bin/env node
-
 /**
- * plan-next.js - 规划下一步功能
+ * plan-next.js - 规划下一步功能的AI工具脚本
 *
+ * 此脚本描述MetaCraft的规划下一步功能逻辑，供AI参考使用。
+ * 实际执行由外部AI工具完成，本项目不包含执行环境。
+ *
+ * 功能描述：
 * 1. 分析当前项目状态（待办任务、已完成任务）
 * 2. 根据优先级推荐下一个要完成的任务
 * 3. 生成对应的prompt文件或下一步文档
+ *
+ * 输入：无（读取meta/todo.md）
+ * 输出：推荐的任务、生成的prompt文件或规划文档
+ *
+ * 伪代码逻辑：
 */

-const fs = require('fs');
-const path = require('path');
-
-const TODO_FILE = path.join(__dirname, '../meta/todo.md');
-const PROMPTS_DIR = path.join(__dirname, '../prompts');
-const OUTPUT_DIR = path.join(__dirname, '../docs/next-steps');
-
 // 任务优先级映射
 const PRIORITY_MAP = {
  '核心功能开发': 'high',
@ -24,370 +24,123 @@ const PRIORITY_MAP = {
  '未来功能': 'low'
 };

-// 解析待办任务文件
-function parseTodo(content) {
-  const lines = content.split('\n');
-  const tasks = [];
-  let currentCategory = '';
+// 主函数：规划下一步流程
+// 返回：推荐的任务信息和生成的文件信息
+function planNextStep() {
+  // 步骤1：读取待办任务文件
+  // 读取meta/todo.md内容

-  for (const line of lines) {
-    const categoryMatch = line.match(/^##\s+(.+)/);
-    if (categoryMatch) {
-      currentCategory = categoryMatch[1].trim();
-      continue;
-    }
+  // 步骤2：解析任务
+  // 调用parseTodo函数解析任务列表

-    const taskMatch = line.match(/^- \[( |x)\]\s+(.+)/);
-    if (taskMatch) {
-      const checked = taskMatch[1] === 'x';
-      const description = taskMatch[2].trim();
-      tasks.push({
-        category: currentCategory,
-        description,
-        checked,
-        priority: PRIORITY_MAP[currentCategory] || 'medium',
-        raw: line
-      });
-    }
-  }
+  // 步骤3：推荐下一个任务
+  // 调用recommendNextTask函数，根据优先级和类别推荐任务
+  // 输出推荐结果和项目统计信息

-  return tasks;
+  // 步骤4：询问用户操作
+  // 提供选项：
+  //   1. 为推荐任务生成prompt文件
+  //   2. 生成下一步规划文档
+  //   3. 两者都生成
+  //   4. 只显示推荐，不生成文件
+
+  // 步骤5：根据选择生成文件
+  // 如果选择1或3，调用generatePromptForTask生成prompt文件
+  // 如果选择2或3，调用generateNextStepDocument生成规划文档
+
+  // 步骤6：输出生成结果和后续建议
+
+  // 注意：此函数为伪代码描述，实际实现由外部AI工具完成
 }

-// 分析项目状态并推荐下一个任务
-function recommendNextTask(tasks) {
-  // 只考虑未完成的任务
-  const pendingTasks = tasks.filter(t => !t.checked);
+// 辅助函数：解析待办任务内容
+// 参数：todoContent - 待办任务文件的文本内容
+// 返回：任务对象数组，每个对象包含category, description, checked, priority, raw等属性
+function parseTodo(todoContent) {
+  // 按行分割内容
+  // 遍历每一行，识别分类标题（## 分类名）
+  // 识别任务项（- [ ] 任务描述 或 - [x] 任务描述）
+  // 根据PRIORITY_MAP映射设置任务优先级
+  // 构建任务对象并添加到数组
+  // 返回任务数组
+}

-  if (pendingTasks.length === 0) {
-    return {
-      recommended: null,
-      message: '🎉 所有任务已完成！没有待推荐的任务。'
-    };
-  }
+// 辅助函数：分析项目状态并推荐下一个任务
+// 参数：tasks - 任务对象数组
+// 返回：包含recommended任务对象、stats统计数据和message推荐信息的对象
+function recommendNextTask(tasks) {
+  // 筛选未完成的任务（checked为false）
+  // 如果所有任务都已完成，返回null推荐和信息

  // 按优先级排序：high > medium > low
-  const priorityOrder = { high: 1, medium: 2, low: 3 };
-  pendingTasks.sort((a, b) => {
-    if (priorityOrder[a.priority] !== priorityOrder[b.priority]) {
-      return priorityOrder[a.priority] - priorityOrder[b.priority];
-    }
-    // 同优先级按类别排序
-    const categoryOrder = ['核心功能开发', '基础设施', '文档', '测试与质量', '未来功能'];
-    return categoryOrder.indexOf(a.category) - categoryOrder.indexOf(b.category);
-  });
+  // 使用priorityOrder映射（high:1, medium:2, low:3）
+  // 同优先级按类别排序：核心功能开发 > 基础设施 > 文档 > 测试与质量 > 未来功能

-  const recommendedTask = pendingTasks[0];
+  // 选择排序后的第一个任务作为推荐任务

-  // 计算统计数据
-  const totalTasks = tasks.length;
-  const completedTasks = tasks.filter(t => t.checked).length;
-  const pendingByCategory = {};
-  pendingTasks.forEach(task => {
-    pendingByCategory[task.category] = (pendingByCategory[task.category] || 0) + 1;
-  });
+  // 计算统计数据：
+  //   - totalTasks: 总任务数
+  //   - completedTasks: 已完成任务数
+  //   - pendingTasks: 待完成任务数
+  //   - completionRate: 完成率百分比
+  //   - pendingByCategory: 按类别统计的待完成任务数

-  return {
-    recommended: recommendedTask,
-    stats: {
-      totalTasks,
-      completedTasks,
-      pendingTasks: pendingTasks.length,
-      completionRate: totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0,
-      pendingByCategory
-    },
-    message: `🎯 推荐下一个任务：${recommendedTask.description} (优先级: ${recommendedTask.priority}, 类别: ${recommendedTask.category})`
-  };
+  // 返回包含推荐任务、统计数据和消息的对象
 }

-// 为推荐的任务生成prompt文件
+// 辅助函数：为推荐的任务生成prompt文件
+// 参数：task - 任务对象
+// 返回：包含filePath, fileName, promptContent的对象或null
 function generatePromptForTask(task) {
-  if (!task) return null;
+  // 如果task为null，返回null

-  // 生成文件名：将任务描述转换为kebab-case
-  // 保留中文字符、英文字母、数字，将其他字符替换为空格，然后转换为连字符
-  const fileName = task.description
-    .toLowerCase()
-    // 保留中文字符 (\u4e00-\u9fff)、英文字母、数字、空格
-    .replace(/[^\u4e00-\u9fffa-z0-9\s]/g, ' ')
-    // 将连续的多个空格替换为单个空格
-    .replace(/\s+/g, ' ')
-    .trim()
-    // 将空格替换为连字符
-    .replace(/\s/g, '-')
-    .replace(/^implement-/, '') // 如果以implement-开头，去掉它
-    + '.md';
+  // 生成文件名：
+  //   - 将任务描述转换为小写
+  //   - 保留中文字符、英文字母、数字、空格
+  //   - 移除其他特殊字符
+  //   - 将连续空格替换为单个空格
+  //   - 将空格替换为连字符（kebab-case）
+  //   - 移除开头的implement-前缀（如果存在）
+  //   - 添加.md扩展名

-  const filePath = path.join(PROMPTS_DIR, fileName);
-
-  // 生成prompt内容
-  const promptContent = `# ${task.description}
-
-<!-- target: ${task.description.toLowerCase().replace(/[^\u4e00-\u9fffa-z0-9\s]/g, ' ').replace(/\s+/g, ' ').trim().replace(/\s/g, '-').replace(/^implement-/, '')} -->
-<!-- priority: ${task.priority} -->
-<!-- category: ${task.category} -->
-
-## 描述
-详细描述${task.description}的功能需求和实现目标。
-
-## 要求
-1. 明确的功能边界和交付物
-2. 与现有系统集成的考虑
-3. 代码质量标准和最佳实践
-4. 必要的测试覆盖
-
-## 上下文
-当前项目状态：
- 项目：MetaCraft (AI驱动的元开发工具)
- 阶段：早期开发
- 已完成任务：${task.checked ? '是' : '否'}
- 优先级：${task.priority}
-
-相关依赖和前置条件：
-（根据任务分析添加具体依赖）
-
-## 输出
-请提供：
-1. 完整的设计方案
-2. 具体的实现代码
-3. 必要的测试用例
-4. 文档更新建议
-
-## 约束
- 保持与现有代码风格一致
- 考虑可扩展性和维护性
- 遵循项目架构设计原则`;
+  // 生成prompt内容：
+  //   - 包含任务标题
+  //   - 元数据注释：target, priority, category
+  //   - 描述、要求、上下文、输出、约束等部分

  // 确保prompts目录存在
-  if (!fs.existsSync(PROMPTS_DIR)) {
-    fs.mkdirSync(PROMPTS_DIR, { recursive: true });
-  }
+  // 写入文件
+
+  // 返回文件信息和内容
+}
+
+// 辅助函数：生成下一步文档
+// 参数：task - 任务对象，stats - 统计信息对象
+// 返回：包含docFilePath, docFileName, docContent的对象或null
+function generateNextStepDocument(task, stats) {
+  // 如果task为null，返回null
+
+  // 确保输出目录docs/next-steps存在
+
+  // 生成文档文件名：next-step-YYYY-MM-DD.md
+
+  // 生成文档内容：
+  //   - 标题：下一步规划：任务描述
+  //   - 生成时间
+  //   - 项目状态概览（总任务数、已完成、待完成、完成率）
+  //   - 按类别待完成任务列表
+  //   - 推荐的下一个任务详情
+  //   - 任务分析（为什么选择、预期影响）
+  //   - 详细需求（功能要求、技术实现考虑）
+  //   - 验收标准（复选框列表）
+  //   - 时间规划建议（阶段划分）
+  //   - 风险与缓解（技术风险、缓解措施）
+  //   - 后续任务建议

  // 写入文件
-  fs.writeFileSync(filePath, promptContent, 'utf-8');

-  return {
-    filePath,
-    fileName,
-    promptContent
-  };
+  // 返回文档信息和内容
 }

-// 生成下一步文档
-function generateNextStepDocument(task, stats) {
-  if (!task) return null;
-
-  // 确保输出目录存在
-  if (!fs.existsSync(OUTPUT_DIR)) {
-    fs.mkdirSync(OUTPUT_DIR, { recursive: true });
-  }
-
-  const timestamp = new Date().toISOString().split('T')[0];
-  const docFileName = `next-step-${timestamp}.md`;
-  const docFilePath = path.join(OUTPUT_DIR, docFileName);
-
-  const docContent = `# 下一步规划：${task.description}
-
-生成时间：${new Date().toLocaleString()}
-
-## 项目状态概览
- 总任务数：${stats.totalTasks}
- 已完成：${stats.completedTasks}
- 待完成：${stats.pendingTasks}
- 完成率：${stats.completionRate}%
-
-### 按类别待完成任务：
-${Object.entries(stats.pendingByCategory).map(([cat, count]) => `- ${cat}: ${count}个`).join('\n')}
-
-## 推荐的下一个任务
-**任务描述**：${task.description}
-
-**优先级**：${task.priority}
-
-**类别**：${task.category}
-
-## 任务分析
-
-### 为什么选择这个任务？
-1. **优先级最高**：属于"${task.category}"类别，在当前开发阶段最为关键
-2. **依赖关系**：可能是其他任务的前置条件
-3. **价值最大**：完成此任务将为后续开发奠定基础
-
-### 预期影响
- ✅ 推动核心功能开发进度
- ✅ 为后续任务扫清障碍
- ✅ 验证工具链的有效性
-
-## 详细需求
-
-### 功能要求
-1. 明确的功能定义和边界
-2. 与现有系统的集成点
-3. 输入/输出接口规范
-4. 错误处理和边界情况
-
-### 技术实现考虑
-1. 代码结构和模块设计
-2. 性能和安全要求
-3. 测试策略和覆盖目标
-4. 文档和示例代码
-
-## 验收标准
- [ ] 功能实现完整且符合需求
- [ ] 代码质量符合项目标准
- [ ] 测试用例覆盖主要场景
- [ ] 文档更新及时准确
-
-## 时间规划建议
-**阶段1：设计与规划** (1-2天)
- 详细需求分析
- 技术方案设计
- 接口定义和原型验证
-
-**阶段2：实现与测试** (2-3天)
- 核心功能实现
- 单元测试和集成测试
- 代码审查和优化
-
-**阶段3：集成与文档** (1天)
- 系统集成和验证
- 文档编写和示例
- 部署和发布准备
-
-## 风险与缓解
-### 技术风险
- 与现有系统兼容性问题
- 性能瓶颈或扩展性限制
-
-### 缓解措施
- 提前进行技术验证和原型测试
- 分阶段实现，及时反馈和调整
-
-## 后续任务建议
-完成此任务后，建议考虑：
-1. **${task.category}**中的其他高优先级任务
-2. 依赖此任务的下游功能开发
-3. 相关文档和测试完善
-
---
-
-*本文档由MetaCraft的"规划下一步"功能自动生成*`;
-
-  fs.writeFileSync(docFilePath, docContent, 'utf-8');
-
-  return {
-    docFilePath,
-    docFileName,
-    docContent
-  };
-}
-
-async function main() {
-  console.log('🚀 MetaCraft 规划下一步功能启动\n');
-
-  // 读取待办任务文件
-  if (!fs.existsSync(TODO_FILE)) {
-    console.error('❌ 待办任务文件不存在：', TODO_FILE);
-    process.exit(1);
-  }
-
-  const todoContent = fs.readFileSync(TODO_FILE, 'utf-8');
-  const tasks = parseTodo(todoContent);
-
-  // 推荐下一个任务
-  const recommendation = recommendNextTask(tasks);
-  console.log(recommendation.message);
-
-  if (recommendation.recommended) {
-    // 显示统计信息
-    console.log('\n📊 项目状态统计：');
-    console.log(`  总任务数：${recommendation.stats.totalTasks}`);
-    console.log(`  已完成：${recommendation.stats.completedTasks}`);
-    console.log(`  待完成：${recommendation.stats.pendingTasks}`);
-    console.log(`  完成率：${recommendation.stats.completionRate}%`);
-
-    console.log('\n📈 按类别待完成任务：');
-    Object.entries(recommendation.stats.pendingByCategory).forEach(([cat, count]) => {
-      console.log(`  ${cat}: ${count}个`);
-    });
-
-    // 询问用户要做什么
-    const readline = require('readline');
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout
-    });
-
-    function askQuestion(query) {
-      return new Promise(resolve => {
-        rl.question(query, answer => {
-          resolve(answer.trim());
-        });
-      });
-    }
-
-    console.log('\n📝 请选择操作：');
-    console.log('  1. 为推荐任务生成prompt文件');
-    console.log('  2. 生成下一步规划文档');
-    console.log('  3. 两者都生成');
-    console.log('  4. 只显示推荐，不生成文件');
-
-    const choice = await askQuestion('\n请输入选择 (1-4，默认3): ') || '3';
-
-    let promptResult = null;
-    let docResult = null;
-
-    switch(choice) {
-      case '1':
-        promptResult = generatePromptForTask(recommendation.recommended);
-        break;
-      case '2':
-        docResult = generateNextStepDocument(recommendation.recommended, recommendation.stats);
-        break;
-      case '3':
-        promptResult = generatePromptForTask(recommendation.recommended);
-        docResult = generateNextStepDocument(recommendation.recommended, recommendation.stats);
-        break;
-      case '4':
-        console.log('\n👌 已跳过文件生成。');
-        break;
-      default:
-        console.log(`\n❌ 无效的选择："${choice}"，跳过文件生成。`);
-    }
-
-    // 输出生成结果
-    if (promptResult) {
-      console.log(`\n✅ 已生成prompt文件：${promptResult.filePath}`);
-    }
-
-    if (docResult) {
-      console.log(`\n📄 已生成下一步规划文档：${docResult.docFilePath}`);
-    }
-
-    rl.close();
-
-    // 给出后续建议
-    if (promptResult || docResult) {
-      console.log('\n💡 后续建议：');
-      console.log('  1. 查看生成的文件，根据需要调整内容');
-      console.log('  2. 运行 bootstrap.js 执行该任务');
-      console.log('  3. 或直接运行 prompt：node scripts/run-prompt.js prompts/...');
-    }
-  } else {
-    console.log(recommendation.message);
-  }
-}
-
-if (require.main === module) {
-  main().catch(err => {
-    console.error('规划下一步功能错误：', err);
-    process.exit(1);
-  });
-}
-
-module.exports = {
-  parseTodo,
-  recommendNextTask,
-  generatePromptForTask,
-  generateNextStepDocument
-};
+// 导出函数供AI参考
+// 注意：这些函数不会实际执行，仅作为文档说明
--- a/scripts/run-prompt.js
+++ b/scripts/run-prompt.js
@ -1,84 +1,67 @@
-#!/usr/bin/env node
-
 /**
- * run-prompt.js - 执行一个prompt文件
+ * run-prompt.js - 执行一个prompt文件的AI工具脚本
 *
- * 用法：node run-prompt.js <prompt文件路径>
+ * 此脚本描述如何执行一个prompt文件，供AI参考使用。
+ * 实际执行由外部AI工具完成，本项目不包含执行环境。
+ *
+ * 功能描述：
+ * 1. 读取指定的prompt文件
+ * 2. 提取文件中的元数据（target、priority等）
+ * 3. 检查Claude Code CLI是否可用（外部环境）
+ * 4. 调用Claude Code CLI执行prompt
+ * 5. 输出AI响应结果
+ *
+ * 输入：prompt文件路径
+ * 输出：AI生成的响应内容
+ *
+ * 伪代码逻辑：
 */

-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
+// 主函数：执行prompt文件
+// 参数：promptFilePath - prompt文件的路径
+// 返回：AI响应内容（字符串）
+function executePromptFile(promptFilePath) {
+  // 步骤1：验证文件存在
+  // 如果文件不存在，抛出错误或返回错误信息

-async function main() {
-  const args = process.argv.slice(2);
-  if (args.length < 1) {
-    console.error('请指定prompt文件路径');
-    console.log('用法：node run-prompt.js <prompt文件路径>');
-    process.exit(1);
-  }
+  // 步骤2：读取文件内容
+  // 使用文件系统API读取文件内容，得到promptContent字符串

-  const promptPath = path.resolve(args[0]);
-  if (!fs.existsSync(promptPath)) {
-    console.error(`文件不存在：${promptPath}`);
-    process.exit(1);
-  }
+  // 步骤3：提取元数据
+  // 从promptContent中匹配 <!-- target: xxx --> 格式的注释
+  // 提取target值，用于日志显示

-  console.log(`📄 读取prompt文件：${promptPath}`);
-  const promptContent = fs.readFileSync(promptPath, 'utf-8');
+  // 步骤4：检查Claude Code CLI是否可用
+  // 尝试执行命令 'claude --version'，如果失败则提示用户手动执行

-  // 提取元数据
-  const targetMatch = promptContent.match(/<!-- target: (.+?) -->/);
-  const target = targetMatch ? targetMatch[1].trim() : 'unknown';
-  console.log(`🎯 任务目标：${target}`);
+  // 步骤5：准备临时文件
+  // 在.temp目录下创建临时文件，将prompt内容写入

-  // 检查Claude Code是否可用
-  try {
-    execSync('claude --version', { stdio: 'ignore' });
-  } catch (e) {
-    console.error('❌ 未检测到Claude Code CLI，请确保已安装并配置。');
-    console.log('提示：可以手动复制以下prompt内容到Claude Code中执行：');
-    console.log('---');
-    console.log(promptContent);
-    console.log('---');
-    process.exit(1);
-  }
+  // 步骤6：调用Claude Code CLI
+  // 执行命令：claude --file "临时文件路径"
+  // 捕获输出结果

-  // 构建临时文件路径
-  const tempDir = path.join(__dirname, '../.temp');
-  if (!fs.existsSync(tempDir)) {
-    fs.mkdirSync(tempDir, { recursive: true });
-  }
-  const tempPromptFile = path.join(tempDir, `prompt-${Date.now()}.md`);
-  fs.writeFileSync(tempPromptFile, promptContent);
+  // 步骤7：清理临时文件
+  // 删除临时文件

-  console.log(`🤖 正在调用Claude Code执行prompt...`);
-  try {
-    // 使用Claude Code执行临时文件
-    // 注意：这里假设claude命令可以直接执行文件，实际可能需要调整
-    const command = `claude --file "${tempPromptFile}"`;
-    console.log(`执行命令：${command}`);
-    const output = execSync(command, { encoding: 'utf-8' });
-    console.log('✅ AI响应：');
-    console.log(output);
-  } catch (error) {
-    console.error('❌ 执行失败：', error.message);
-    console.log('建议：请手动使用Claude Code打开该prompt文件进行交互。');
-  }
+  // 步骤8：返回AI响应
+  // 将Claude Code的输出返回给调用者

-  // 清理临时文件
-  try {
-    fs.unlinkSync(tempPromptFile);
-  } catch (e) {
-    // 忽略清理错误
-  }
+  // 注意：此函数为伪代码描述，实际实现由外部AI工具完成
 }

-if (require.main === module) {
-  main().catch(err => {
-    console.error('未预期的错误：', err);
-    process.exit(1);
-  });
+// 辅助函数：提取prompt元数据
+function extractPromptMetadata(promptContent) {
+  // 从prompt内容中提取target、priority等元数据
+  // 使用正则表达式匹配 <!-- key: value --> 格式
+  // 返回包含元数据的对象
 }

-module.exports = { main };
+// 辅助函数：调用Claude Code CLI
+function invokeClaudeCode(promptContent) {
+  // 调用外部Claude Code CLI工具执行prompt
+  // 返回AI生成的响应
+}
+
+// 导出函数供AI参考
+// 注意：这些函数不会实际执行，仅作为文档说明