Skip to content

README.zh-CN.md

Latest commit

 

History

History
246 lines (194 loc) · 12.5 KB

README.zh-CN.md

File metadata and controls

246 lines (194 loc) · 12.5 KB
WaveForge Logo

WaveForge MCP

一个专为 Vibe Coding 设计的、以开发者为中心的多 Agent 协作框架。将任务管理、实时协作与知识沉淀无缝融合，让你和你的 AI 们心流合一，专注创造。

Stargazers License PRs Welcome Last Commit

English

🚩 项目状态

WaveForge MCP 任务管理系统已基本完成！核心的项目管理和任务管理功能已全面实现并通过测试。你现在就可以开始使用完整的任务管理工作流程。我们正在持续优化性能和用户体验，欢迎试用并提供反馈！

💡 核心理念

  • Vibe Coding 友好: 告别僵化的流程，拥抱“边想边做、边聊边改”的开发模式。WaveForge 将任务分解为宏观计划与微观步骤，让你和 AI Agent 可以在同一上下文中流水线式思考、积木式开发。
  • 本地优先，Git 赋能: 所有任务数据、日志和文档都以纯文本文件形式存储在本地的 .wave 目录中。这意味着你可以完全掌控自己的数据，并利用 Git 进行版本管理、协作与备份，无需依赖任何外部服务。
  • 可溯源，不杜撰: 从需求来源、Git 提交、PR/Issue 链接到关键决策讨论，WaveForge 会自动为你建立详尽的“证据链”（Provenance）。生成的 Devlog 基于事实，而非 AI 的凭空想象，确保每一次复盘都有据可查。
  • 自动化，非侵入式: 系统通过自动化规则（如计划自动完成、步骤生成提示）和非侵入式的提示（Hints）辅助 Agent 开发，但从不打断 AI 的开发心流。它是一个聪明的副驾驶，而不是一个指手画脚的老板。

✨ 亮点功能

  • 智能任务系统
    • 双层级任务模型：通过“整体计划 (Plan)”和“具体步骤 (Step)”的结构，轻松驾驭复杂任务。既能总览全局，又能聚焦当下，实现宏观与微观的统一。
    • 三层级提示系统：提供任务、计划和步骤三个层级的提示信息，实现多 Agent 协同工作时的智能指导。提示信息会根据当前操作上下文自动传递给执行任务的 AI Agent。
    • 自动化流程驱动：当计划的最后一步完成时，系统会自动完成该计划并提示 AI 为下一个计划生成步骤。这种“接力棒”式的自动化，让任务推进如丝般顺滑。
  • 无缝的多 Agent 与跨工具协作
    • 项目唯一标识：革命性的项目绑定机制，彻底摆脱对当前工作目录 (CWD) 或编辑器工作区的依赖。无论你在哪个工具（Cursor, VSCode, Kiro）或终端中，都能确保所有 Agent 在同一个项目上下文中协作，不再有“找不着北”的烦恼。
    • 实时同步保障：通过文件锁和状态版本控制，确保多个 Agent 并行操作时的数据一致性，避免状态冲突。
  • 开发者体验至上
    • 零配置启动与自愈：首次运行自动创建所需目录结构、模板和配置文件，并具备幂等性。开箱即用，无需繁琐配置。
    • 一键生成 Devlog：任务完成后，只需一步确认，即可基于模板自动生成两种风格的开发日志：timeline（忠实记录执行轨迹）和 narrative（故事化叙事）。日志内容自动聚合 Git 提交、文件变更、测试结果和关键讨论，将繁琐的文档工作化为无形。
    • 全面的可追溯性 (Provenance)：自动采集和整理与任务相关的一切信息，包括 Git 提交范围、PR/Issue 链接、需求文档路径、会议纪要等，构建完整的可溯源信息视图。

🚀 快速上手

WaveForge 已经发布到 npm！最简单的上手方式是使用 npx。

MCP 客户端配置

配置你的 MCP 客户端（如 Cursor 或 Kiro）以使用 WaveForge：

JSON 格式 (.cursor/mcp.json):

{
  "mcpServers": {
    "waveforge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "waveforge@latest"],
      "env": {
        "WF_LOG_LEVEL": "SILENT",
        "WF_DEBUG": "false",
        "npm_config_loglevel": "silent",
        "npm_config_yes": "true"
      }
    }
  }
}

TOML 格式 (.codex/config.toml):

[mcp_servers.waveforge]
command = "npx"
args = ["-y", "waveforge@latest"]
env = { "WF_LOG_LEVEL" = "SILENT", "WF_DEBUG" = "false", "npm_config_loglevel" = "silent", "npm_config_yes" = "true" }

本地开发

如果你想为 WaveForge 贡献代码或运行本地版本：

  1. 克隆仓库：

    git clone https://github.com/DeadWaveWave/waveforge.git
cd waveforge

  2. 安装依赖：

    pnpm install

  3. 运行开发模式：

    pnpm dev

  4. 配置 MCP 客户端使用本地构建：

    JSON 格式 (.cursor/mcp.json):

    {
  "mcpServers": {
    "waveforge": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/your/waveforge/dist/esm/server.js"],
      "env": {
        "WF_LOG_LEVEL": "SILENT"
      }
    }
  }
}

    TOML 格式 (.codex/config.toml):

    [mcp_servers.waveforge]
command = "node"
args = ["/path/to/your/waveforge/dist/esm/server.js"]
env = { "WF_LOG_LEVEL" = "SILENT" }

关于更详细的说明，请参阅 使用指南 (USAGE.md) 和 快速开始指南 (docs/quick-start.zh-CN.md)。

如果遇到任何问题，请查看 故障排除指南 (docs/troubleshooting.md) 获取已知问题的解决方案。

功能清单 (Roadmap)

我们正在积极推进以下核心功能的实现，欢迎你加入讨论或贡献代码！

核心框架

  • 项目绑定与环境自愈
    • connect_project: 实现项目与 MCP 服务的唯一绑定，现已包含全面的安全检查和路径验证机制。
    • project_info: 获取当前绑定的项目信息，内置健康监控和完整性检查功能。
    • 初始化与自愈：首次运行时自动创建 .wave 目录结构、模板及配置文件，具备完整的数据完整性验证。

任务管理工具 (MCP Tools)

  • 双层级任务模型
    • current_task_init: 初始化新任务，定义目标 (goal) 和宏观计划 (overall_plan)。
    • current_task_modify: 动态调整任务，支持：
      • plan: 整体调整计划。
      • steps: 为当前计划生成或修改具体步骤。
      • goal: 微调验收标准。
      • hints: 为 AI 添加上下文提示。
    • current_task_update: 更新计划 (plan) 或步骤 (step) 的状态。
  • 任务生命周期
    • current_task_read: 读取当前任务的完整上下文，便于在不同客户端间同步。
    • current_task_complete: 标记任务完成，并触发开发日志 (Devlog) 生成。
    • task_list: 查看历史任务列表。
    • task_switch: 在不同任务间切换。
  • 过程记录与追溯
    • current_task_log: 记录开发过程中的关键讨论、决策或异常。
    • 可追溯性 (Provenance): 自动关联 Git 提交、PR/Issue 链接等信息。

自动化与文档生成

  • 自动化流程
    • 当计划的所有步骤完成后，自动将计划标记为完成。
    • 当进入新计划时，提示 AI 生成具体步骤。
  • Devlog 自动生成
    • 任务完成时提供开发日志生成建议和模板。
    • devlog_prepare_context: 准备生成 Devlog 所需的上下文。
    • generate_devlog: 基于模板，将任务快照、日志、Git 历史等信息填充为 timeline 和 narrative 两种风格的开发日志。

协作流程：从灵感到实现

  1. 项目连接：使用 connect_project 将项目绑定到 MCP 会话，确保所有 AI Agent 在同一上下文中协作。
  2. 需求与讨论：在任何工具中与 AI 自由讨论，将会议纪要、灵感火花记录为任务的 hints（提示）或 knowledge_refs（知识引用），为后续开发提供上下文。
  3. 规划与设计：通过 current_task_init 初始化任务，你和 AI Agent 协同制定出宏观的"整体计划 (Overall Plan)"。
  4. 编码与实现：Agent 聚焦于当前计划，动态生成并执行"具体步骤 (Steps)"。你随时可以通过手动添加或让其他 Agent 添加 hints 来指导和调整 Agent 的行为。
  5. 复盘与沉淀：任务完成，一键生成 Devlog。无论是用于团队分享、技术复盘还是知识沉淀，都信手拈来。

⚠️ 重要说明

工具名称变更：由于发现 project_bind 在某些 IDE 中可能存在命名冲突，我们将其重命名为 connect_project。功能完全相同，只是名称更改。如果你在使用过程中遇到工具无法响应的问题，请检查是否使用了正确的工具名称。

🏗️ 软件架构

WaveForge 的所有数据都存储在项目根目录下的 .wave 文件夹中。服务器逻辑组织如下：

src/
├── server.ts              # MCP 服务器入口点
├── core/                  # 核心业务逻辑
│   ├── error-handler.ts   # 错误处理器
│   ├── logger.ts          # 日志记录器
│   └── project-root-manager.ts # 项目根目录管理器
├── tools/                 # MCP 工具定义
│   ├── index.ts           # 工具实现
│   └── schemas.ts         # JSON Schema 定义
├── types/                 # TypeScript 类型定义
│   └── index.ts           # 核心类型
└── adapters/              # 适配器层
    └── index.ts           # 适配器接口

数据架构与文件系统

WaveForge 的所有数据都存储在项目根目录下的 .wave 文件夹中，其结构清晰、可读性强：

.wave/
├── .gitignore            # 忽略本地可编辑的面板文件
├── current-task.md       # 全局当前任务面板，可在本地自由编辑
├── tasks/
│   ├── index.json        # 所有任务的索引
│   ├── _latest.json      # 指向最近活跃任务
│   ├── views/            # 任务的视图索引（如按 slug 分组）
│   └── 2025/09/21/
│       └── <slug>--<id8>/ # 单个任务的归档目录
│           ├── task.json             # 任务状态快照 (JSON)
│           ├── logs.jsonl            # 结构化日志 (JSON Lines)
│           ├── devlog.timeline.md    # 时间线风格的开发日志
│           └── devlog.narrative.md   # 叙事风格的开发日志
└── templates/
    └── devlog-template.md  # Devlog 模板，可自定义

Toolkit（未来）

一套核心，两种出入口：MCP 工具 与 原生 Toolkit（Agent 直接调用）。通过 Tool Manifest、能力握手与 Schema 版本化保证稳定演进。

🤝 参与开发

我们致力于最高的代码质量标准。

  • TypeScript: 完全使用严格模式的 TypeScript 编写。
  • 代码检查: 使用 ESLint 进行代码分析。
  • 代码格式化: 使用 Prettier 保证代码风格一致。
  • 测试: 使用 Vitest 作为测试框架，目标是 100% 的测试覆盖率。

🙏 致谢

Star History

Star History Chart

许可协议

本项目使用 MIT License。详见 LICENSE。