@geeseeker/easyai-dev 3.0.5 → 3.0.6

package/README_AI.md

@@ -52,7 +52,10 @@ easyAI 的 MCP Server 已打包在 npm 包中，无需本地编译。
 
 3. **注入 easyAI MCP Server 配置**：
 
-   向用户展示将要添加的配置内容，**请求用户确认**后再写入：
+   向用户展示将要添加的配置内容，**请求用户确认**后再写入。
+
+   **关键**：必须包含 `EASYAI_PROJECT_ROOT` 环境变量，指向用户项目的绝对路径。
+   MCP Server 通过 `npx` 运行时，进程的工作目录不在项目内，需要此环境变量才能定位项目。
 
    ```
    我将在 Antigravity MCP 配置文件中添加 easyAI MCP Server：
@@ -62,12 +65,18 @@ easyAI 的 MCP Server 已打包在 npm 包中，无需本地编译。
    新增条目：
    "easyai-mcp-server": {
      "command": "npx",
-     "args": ["-y", "@geeseeker/easyai-dev", "serve"]
+     "args": ["-y", "@geeseeker/easyai-dev", "serve"],
+     "env": {
+       "EASYAI_PROJECT_ROOT": "<用户项目的绝对路径>"
+     }
    }
 
    是否确认添加？
    ```
 
+   > **`EASYAI_PROJECT_ROOT` 必须是项目根目录的绝对路径**（包含 `.trellis/` 的目录）。
+   > 例如：`/home/user/projects/my-app` 或 `/Users/user/projects/my-app`。
+
 4. **用户确认后，写入配置**：
 
    将 `easyai-mcp-server` 条目添加到 `mcpServers` 对象中（保留已有的其他 MCP Server 配置不变）。
@@ -83,9 +92,22 @@ easyAI 的 MCP Server 已打包在 npm 包中，无需本地编译。
 
    > 这是一个**必须的断点**，MCP 配置修改后需要重启 IDE 才能生效。
 
-6. **验证 MCP 连接**：用户确认重启后，尝试调用任意 easyai MCP 工具（如 `project_status`）验证连接。
-   - 如果调用失败，检查配置文件内容是否正确，协助用户排查。
-   - 如果没有 easyai MCP 工具可用，说明配置尚未生效，需要再次检查配置和重启。
+6. **验证 MCP 连接**：
+
+   用户确认重启后，按以下顺序验证：
+
+   a. 尝试读取 MCP 资源 `trellis://status`
+
+   b. **如果成功** → 包含 `git`、`tasks`、`journal` 字段 → MCP 工作正常，进入 S2
+
+   c. **如果报错「无法找到项目根目录」** → 按以下步骤自修复：
+   1. 读取 `~/.gemini/antigravity/mcp_config.json`
+   2. 检查 `easyai-mcp-server` 条目是否包含 `env.EASYAI_PROJECT_ROOT`
+   3. 如果缺失，添加 `"env": { "EASYAI_PROJECT_ROOT": "<项目绝对路径>" }`
+   4. 如果已有但路径错误，修正为正确的项目根目录路径
+   5. 告知用户需要再次重启 IDE
+
+   d. **如果没有 easyai MCP 工具可用** → 配置尚未生效，检查配置文件并重启
 
 ---
 
@@ -140,6 +162,40 @@ npx @geeseeker/easyai-dev check .
 
 ## 故障排查
 
+AI 遇到 MCP 相关报错时，应**先自行诊断和修复**，不要将底层错误暴露给用户。
+
+### 「无法找到项目根目录」
+
+**这是最常见的问题**。MCP Server 需要知道项目根目录才能工作。
+
+**诊断**：错误信息中会包含 `cwd(...)` 和 `__dirname(...)` 两个路径，表示它在这两条路径上都没找到 `.trellis` 目录。
+
+**自动修复步骤**（AI 应自行执行，无需用户介入）：
+
+1. 读取 `~/.gemini/antigravity/mcp_config.json`
+2. 找到 `easyai-mcp-server` 条目
+3. 检查是否包含 `env.EASYAI_PROJECT_ROOT`
+4. 如果缺失或路径错误 → 修正为当前项目根目录（包含 `.trellis/` 的目录）的绝对路径：
+   ```json
+   "easyai-mcp-server": {
+     "command": "npx",
+     "args": ["-y", "@geeseeker/easyai-dev", "serve"],
+     "env": {
+       "EASYAI_PROJECT_ROOT": "/绝对路径/到/项目根"
+     }
+   }
+   ```
+5. 告知用户「MCP 配置已自动修复，请重启 IDE」
+6. 用户重启后，再次验证
+
+**根因说明**：MCP Server 检测项目根的优先级为：
+
+1. `EASYAI_PROJECT_ROOT` 环境变量（推荐，最可靠）
+2. `process.cwd()` 向上遍历查找 `.trellis`（IDE 工作目录在项目内时有效）
+3. `__dirname` 向上遍历（MCP Server 安装在项目 `node_modules` 内时有效）
+
+通过 `npx -y` 运行时，cwd 和 `__dirname` 通常都在项目外，因此**必须设置环境变量**。
+
 ### MCP Server 无法启动
 
 ```bash
@@ -148,7 +204,7 @@ node --version  # 需要 >= 18
 
 # 手动测试 MCP Server
 npx @geeseeker/easyai-dev serve
-# 正常情况下会输出 "easyAI MCP Server v0.1.0 started" 到 stderr
+# 正常情况下会输出 "easyAI MCP Server started" 到 stderr
 ```
 
 ### MCP 配置文件路径不确定
@@ -176,3 +232,10 @@ npx @geeseeker/easyai-dev init .
 npx @geeseeker/easyai-dev update .
 # 只更新 .agents/ 和 .trellis/spec/，不影响用户数据
 ```
+
+### 切换项目
+
+如果用户切换到不同项目，需要更新 MCP 配置中的 `EASYAI_PROJECT_ROOT`：
+
+1. 修改 `~/.gemini/antigravity/mcp_config.json` 中的路径
+2. 重启 IDE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geeseeker/easyai-dev",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "easyAI — 让用户以纯客户的视角进行软件开发",
   "type": "module",
   "bin": {