@geeseeker/easyai-dev 3.0.0-alpha.1 → 3.0.0

package/README.md

@@ -1,131 +1,133 @@
-<div align="center">
-
-# easyAI-dev
-
-**AI Agent 协作框架 — 让 AI 团队帮你完成整个开发流程**
-
-[![npm version](https://img.shields.io/npm/v/@geeseeker/easyai-dev.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@geeseeker/easyai-dev)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Antigravity](https://img.shields.io/badge/IDE-Antigravity-purple.svg?style=flat-square)](https://antigravity.dev)
-
-⭐ 觉得有用？Star 一下支持我们！
-
-</div>
+<p align="center">
+  <h1 align="center">🤖 easyAI</h1>
+  <p align="center">
+    <strong>让用户以纯客户的视角进行软件开发</strong><br>
+    用户只需提需求、审批方案、验收结果。
+  </p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/@geeseeker/easyai-dev"><img src="https://img.shields.io/npm/v/@geeseeker/easyai-dev?color=blue&label=npm" alt="npm version"></a>
+    <a href="https://github.com/GeeSeeker/easyAI-dev/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
+    <a href="https://antigravity.google/"><img src="https://img.shields.io/badge/IDE-Antigravity-purple" alt="Antigravity"></a>
+  </p>
+</p>
 
 ---
 
-## 这是什么？
+## 💡 这是什么？
 
-easyAI 是一个为 [Antigravity IDE](https://antigravity.dev) 打造的 **AI Agent 协作框架**。它在你的 IDE 里组建了一支 AI 团队，覆盖从需求分析到代码交付的完整开发流程。
+easyAI 是一个为 [Antigravity IDE](https://antigravity.google/) 打造的 **AI 协作开发框架**。
 
-**即使你完全不懂代码，也能通过 AI 协作完成高质量的软件开发。**
+它在 IDE 中组建 **PM（项目经理）** + **Worker（执行者）** 双角色 AI 团队，覆盖从需求分析到代码交付的完整开发流程。你不需要写代码、不需要了解技术细节 — 只需和 PM 对话。
 
-### 核心亮点
+### 核心特性
 
-- 🛡️ **9 条硬阻断 + 12 条 Red Flags** — 流程纪律，防止 AI 跳步
-- 🔒 **风险分级代码审查** — 低风险自动通过，高风险交叉验证
-- 🧪 **TDD 红绿重构铁律** — 先写失败测试再写代码
-- 🧠 **知识沉淀闭环** — 每次任务的经验自动归档，越用越聪明
-- 🤖 **多 AI 协作** — 通过 MCP 调度 Claude Code / Codex / Gemini CLI
+| 特性 | 说明 |
+|------|------|
+| 🎯 **角色驱动** | PM 管需求和验收，Worker 管编码和测试 |
+| 📋 **任务管理** | 完整的任务生命周期：创建 → 分配 → 执行 → 验收 → 归档 |
+| 🧠 **记忆系统** | journal 日志 + Artifacts 沉淀，跨会话不丢失上下文 |
+| 🛡️ **反幻觉** | 第三方 API 必须查文档，禁止凭记忆编码 |
+| ✅ **TDD 铁律** | 所有新功能必须先写测试，Worker 无法跳过 |
+| 🔧 **MCP 集成** | 19 个工具 + 5 个数据源，通过 MCP 协议与 IDE 深度集成 |
 
 ---
 
-## 快速安装
+## 🚀 快速安装
+
+> **前置要求**：[Antigravity IDE](https://antigravity.google/) + [Node.js](https://nodejs.org/) >= 18
 
-> **前置要求**：[Antigravity IDE](https://antigravity.dev) + [Node.js](https://nodejs.org/) (v18+)
+### 方式一：让 AI 帮你安装（推荐 👈）
 
-复制下面这段话，粘贴到 Antigravity 的对话框中：
+复制以下文字，粘贴到 Antigravity 对话框中：
 
 ```
-请帮我安装 easyAI-dev 框架。
-仓库地址：https://github.com/GeeSeeker/easyAI-3.0
-请克隆仓库后阅读 README_AI.md，按步骤自动完成配置。
+请帮我安装 easyAI 框架。
+安装指南：https://raw.githubusercontent.com/GeeSeeker/easyAI-dev/main/README_AI.md
+请读取这份指南，按步骤自动完成配置。
 ```
 
-AI 会自动帮你完成以下所有步骤：
+AI 会自动完成 MCP 配置 + 项目初始化。**这就是 easyAI 的哲学** — 连安装都不需要你亲自动手。
 
-1. ✅ 安装 `@geeseeker/easyai-dev` CLI 工具
-2. ✅ 配置 MCP Server（Claude Code / Gemini / Codex）
-3. ✅ 验证环境可用性
+### 方式二：命令行安装
 
-安装完成后，AI 会告诉你如何初始化项目。
-
----
+```bash
+# 新项目
+npx @geeseeker/easyai-dev init my-project
 
-## 日常使用
+# 已有项目
+cd your-project
+npx @geeseeker/easyai-dev init .
+```
 
-### 新项目初始化
+然后在 Antigravity 的 MCP 设置中添加：
 
-```bash
-cd my-project
-easyai-dev init
+```json
+{
+  "easyai-mcp-server": {
+    "command": "npx",
+    "args": ["-y", "@geeseeker/easyai-dev", "serve"]
+  }
+}
 ```
 
-这会在项目中生成：
+重启 IDE，完成。
 
-- `.agents/` — 规则、工作流、技能链（AI 的大脑）
-- `.trellis/` — 规范库、会话记忆、任务看板（项目记忆）
+---
 
-### 框架升级
+## 🎮 使用
 
-```bash
-npm update -g @geeseeker/easyai-dev   # 升级 CLI 工具
-easyai-dev update                       # 更新项目中的框架文件
+```
+1. 打开 Antigravity IDE
+2. 输入 /pm 启动项目经理
+3. 和 PM 对话，描述你的需求
+4. 等待交付 🎉
 ```
 
 ---
 
-## 角色体系
+## 📁 项目结构
 
-easyAI 采用**角色与 AI 解耦**的设计：角色定义职责，AI 是执行角色的载体。
+安装 easyAI 后，你的项目会多出以下目录：
 
-| 角色            | 定位         | 职责                                     |
-| --------------- | ------------ | ---------------------------------------- |
-| 🎯 **项目经理** | 资源调度中枢 | 与用户沟通、拆分任务、验收审查、知识沉淀 |
-| 🔧 **技术主管** | 外包工头     | 调度外部 CLI、处理 Diff、技术执行        |
-| 💻 **开发者**   | 核心骨干     | TDD 编码、精细重构、兜底开发             |
-| 🔍 **审核员**   | 架构评审     | 核心 Milestone 把关、一票否决            |
-| 🛠️ **助理**     | 机动支持     | 环境配置、资料检索（免硬阻断）           |
+```
+your-project/
+├── .agents/            ← AI 角色层
+│   ├── rules/          │  3 条始终生效的规则
+│   ├── workflows/      │  PM + Worker 工作流
+│   └── skills/         │  10+ 个能力模块
+├── .trellis/           ← 数据持久层
+│   ├── config/         │  框架配置
+│   ├── spec/           │  项目规范
+│   ├── tasks/          │  任务管理
+│   └── workspace/      │  开发者记忆（journal）
+├── .docs/              ← 用户文档空间
+│   ├── requirements/   │  需求文档
+│   ├── design/         │  设计方案
+│   ├── guides/         │  使用指南
+│   ├── notes/          │  临时笔记
+│   └── archive/        │  文档归档
+└── ...                 ← 你的项目代码
+```
 
 ---
 
-## 工作流体系
+## 🛠️ CLI 命令
 
-| 工作流     | 说明                                          |
-| ---------- | --------------------------------------------- |
-| 开工检查   | 上下文恢复 + 硬阻断检查 + Red Flags 自检      |
-| 需求脑暴   | 苏格拉底式提问，将想法转化为设计              |
-| 微任务撰写 | BDD 验收标准 + 测试契约卡片                   |
-| TDD 开发   | RED → GREEN → REFACTOR                        |
-| 代码审查   | 自动化验证 → PM 审查 → 交叉验证（按风险分级） |
-| 系统化调试 | 根因调查 → 模式分析 → 假设验证 → 修复         |
-| 收工流程   | Git 卫生 + 知识沉淀 + 会话记录                |
+```bash
+npx @geeseeker/easyai-dev init [dir]     # 初始化项目
+npx @geeseeker/easyai-dev check [dir]    # 检查框架完整性
+npx @geeseeker/easyai-dev update [dir]   # 更新框架版本
+npx @geeseeker/easyai-dev serve          # 启动 MCP Server
+```
 
 ---
 
-## 致谢
+## 📄 许可证
 
-easyAI 的诞生离不开以下优秀项目的启发 🙏
-
-### 参考项目
-
-| 项目                                                         | 融合点                                |
-| ------------------------------------------------------------ | ------------------------------------- |
-| [Trellis](https://github.com/mindfold-ai/Trellis)            | 会话持久化、Spec 规范库、任务看板     |
-| [superpowers](https://github.com/obra/superpowers)           | TDD 铁律、系统化调试、强制 Skill 触发 |
-| [ccg-workflow](https://github.com/fengshao1227/ccg-workflow) | 多模型编排、安全沙箱                  |
-| [GuDa-spec](https://github.com/GuDaStudio/commands)          | 零歧义目标检查、约束集                |
-
-### MCP Server
-
-| 项目                                                           | 用途                 |
-| -------------------------------------------------------------- | -------------------- |
-| [claude-code-mcp](https://github.com/steipete/claude-code-mcp) | Claude Code CLI 调用 |
-| [codexmcp](https://github.com/GuDaStudio/codexmcp)             | Codex CLI 调用       |
-| [geminimcp](https://github.com/GuDaStudio/geminimcp)           | Gemini CLI 调用      |
+[MIT](LICENSE)
 
 ---
 
-## 许可证
-
-[MIT License](LICENSE) © 2025 GeeSeeker
+<p align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/GeeSeeker">GeeSeeker</a></sub>
+</p>

package/README_AI.md

@@ -0,0 +1,143 @@
+# AI 安装指南
+
+> **本文档供 AI 阅读。** 人类用户无需手动操作，AI 会按以下步骤自动执行。
+
+## 前置条件
+
+- Antigravity IDE 已安装（https://antigravity.google/）
+- Node.js >= 18 已安装
+- Git 已安装
+
+---
+
+## S0：状态探测（断点续接）
+
+收到安装请求后，按顺序检测当前状态，跳过已完成的步骤：
+
+```
+1. 检查 easyai-mcp-server 是否已在 IDE 中配置
+   → 已配置且可调用 → 跳过 S1
+2. 检查目标项目是否已初始化（.agents/ 和 .trellis/ 存在）
+   → 已初始化 → 跳过 S2
+3. 全部就绪 → 进入 S3
+```
+
+---
+
+## S1：全局安装 — 配置 MCP Server（仅需一次）
+
+easyAI 的 MCP Server 已打包在 npm 包中，无需本地编译。
+
+### 步骤
+
+1. **生成 MCP 配置 JSON**：
+
+```json
+{
+  "easyai-mcp-server": {
+    "command": "npx",
+    "args": ["-y", "@geeseeker/easyai-dev", "serve"]
+  }
+}
+```
+
+2. **引导用户操作**：
+
+告知用户：
+
+```
+请将以下 MCP 配置添加到 Antigravity IDE 的 MCP 设置中：
+
+{
+  "easyai-mcp-server": {
+    "command": "npx",
+    "args": ["-y", "@geeseeker/easyai-dev", "serve"]
+  }
+}
+
+添加完成后，请重启 Antigravity IDE，然后告诉我已重启。
+```
+
+3. **等待用户确认重启** — 这是一个**必须的断点**，MCP 配置修改后需要重启 IDE 才能生效。
+
+4. **验证 MCP 连接**：用户确认重启后，尝试调用任意 easyai MCP 工具（如 `project_status`）验证连接。
+   - 如果调用失败，协助用户排查 MCP 配置。
+   - 如果没有 easyai MCP 工具可用，说明配置尚未生效，需要再次检查配置和重启。
+
+---
+
+## S2：项目安装 — 初始化框架
+
+在目标项目目录中执行：
+
+```bash
+npx @geeseeker/easyai-dev init .
+```
+
+此命令会：
+- 复制 `.agents/`（规则 + 工作流 + Skills）
+- 复制 `.trellis/`（配置 + 规范骨架）
+- 创建 `.docs/`（空文档子文件夹）
+- 创建 `.gitignore`（或合并到已有的）
+- 生成 `.easyai-version` 版本清单
+
+如果用户要在已有项目中安装，命令相同。脚本会自动检测并进入集成模式（不覆盖已有的 README.md 和 .gitignore）。
+
+---
+
+## S3：验证
+
+```bash
+npx @geeseeker/easyai-dev check .
+```
+
+确认所有必需目录和文件都已就位。
+
+---
+
+## S4：安装完成
+
+告知用户：
+
+```
+✅ easyAI 3.0 安装完成！
+
+已配置：
+- 1 个 MCP Server — easyai-mcp-server
+- 框架骨架 — .agents/ + .trellis/ + .docs/
+
+使用方式：
+1. 在 Antigravity IDE 中打开此项目
+2. 输入 /pm 启动项目经理
+3. 和 PM 对话，描述你的需求即可！
+```
+
+---
+
+## 故障排查
+
+### MCP Server 无法启动
+
+```bash
+# 检查 Node.js 版本
+node --version  # 需要 >= 18
+
+# 手动测试 MCP Server
+npx @geeseeker/easyai-dev serve
+# 正常情况下会输出 "easyAI MCP Server v0.1.0 started" 到 stderr
+```
+
+### 框架完整性检查失败
+
+```bash
+# 重新初始化（需先删除现有框架目录）
+rm -rf .agents/ .trellis/ .docs/ .easyai-version
+npx @geeseeker/easyai-dev init .
+```
+
+### 更新框架
+
+```bash
+npx @geeseeker/easyai-dev update .
+# 只更新 .agents/ 和 .trellis/spec/，不影响用户数据
+```

package/bin/easyai-dev.js

@@ -1,3 +1,129 @@
 #!/usr/bin/env node
 
-import("../src/cli/index.js");
+/**
+ * easyai-dev CLI — easyAI 框架命令行工具
+ *
+ * 命令：
+ *   init [dir]    初始化新项目或集成到已有项目
+ *   check [dir]   检查框架完整性
+ *   update [dir]  更新框架（只更新 .agents/ 和 .trellis/spec/）
+ *   serve         启动 MCP Server（供 Antigravity IDE 使用）
+ */
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// 解析命令行参数
+const args = process.argv.slice(2);
+const command = args[0];
+const targetDir = args[1] || ".";
+
+// 颜色常量
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BLUE = "\x1b[34m";
+const BOLD = "\x1b[1m";
+const NC = "\x1b[0m";
+
+/**
+ * 打印帮助信息
+ */
+function printHelp() {
+  console.log(`
+${BOLD}easyAI — 让用户以纯客户的视角进行软件开发${NC}
+
+${BOLD}用法:${NC}
+  easyai-dev <command> [options]
+
+${BOLD}命令:${NC}
+  ${GREEN}init${NC} [dir]      初始化新项目或集成到已有项目（默认: 当前目录）
+  ${GREEN}check${NC} [dir]     检查框架完整性
+  ${GREEN}update${NC} [dir]    更新框架（只更新 .agents/ 和 .trellis/spec/）
+  ${GREEN}serve${NC}           启动 MCP Server（供 Antigravity IDE 使用）
+
+${BOLD}示例:${NC}
+  npx @geeseeker/easyai-dev init my-project
+  npx @geeseeker/easyai-dev init .
+  npx @geeseeker/easyai-dev check
+  npx @geeseeker/easyai-dev serve
+
+${BOLD}MCP 配置:${NC}
+  在 Antigravity IDE 中配置 MCP Server:
+  {
+    "easyai-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@geeseeker/easyai-dev", "serve"]
+    }
+  }
+`);
+}
+
+/**
+ * 主函数
+ */
+async function main() {
+  switch (command) {
+    case "init": {
+      const { doInit } = await import("../lib/init.js");
+      const resolvedDir = path.resolve(targetDir);
+      await doInit(resolvedDir);
+      break;
+    }
+
+    case "check": {
+      const { doCheck } = await import("../lib/init.js");
+      const resolvedDir = path.resolve(targetDir);
+      await doCheck(resolvedDir);
+      break;
+    }
+
+    case "update": {
+      const { doUpdate } = await import("../lib/init.js");
+      const resolvedDir = path.resolve(targetDir);
+      await doUpdate(resolvedDir);
+      break;
+    }
+
+    case "serve": {
+      // 支持 --project-root 参数和环境变量
+      const projectRootArg = args.find((a) => a.startsWith("--project-root="));
+      if (projectRootArg) {
+        const root = projectRootArg.split("=")[1];
+        process.env.EASYAI_PROJECT_ROOT = path.resolve(root);
+      }
+      // 动态导入 MCP Server
+      await import("../lib/server/index.js");
+      break;
+    }
+
+    case "--help":
+    case "-h":
+    case undefined:
+      printHelp();
+      break;
+
+    case "--version":
+    case "-v": {
+      const pkgPath = path.join(__dirname, "..", "package.json");
+      const { default: pkg } = await import(pkgPath, {
+        with: { type: "json" },
+      });
+      console.log(pkg.version);
+      break;
+    }
+
+    default:
+      console.error(`${RED}未知命令: ${command}${NC}`);
+      console.error(`使用 ${BOLD}easyai-dev --help${NC} 查看可用命令`);
+      process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(`${RED}错误: ${error.message}${NC}`);
+  process.exit(1);
+});