@hupan56/wlkj 2.7.1 → 2.7.2

package/MAC-VERIFY.md

@@ -0,0 +1,174 @@
+# macOS 验证清单 (v2.7.1)
+
+> 给 mac 同事跑这份清单，验证工作流在 macOS × Qoder 全系列上可用。
+> 跑完把结果（每条 ✓/✗ + 截图或输出）反馈回来。
+> 预计耗时：15-20 分钟（含装环境）。
+
+## 已在 Windows 上模拟验证的项（mock sys.platform=darwin）
+
+这些项已用 `mock sys.platform='darwin'` 在 Windows 上验证过逻辑正确，
+mac 同事只需确认真实环境跑通（不需要深入查代码）：
+
+| 验证项 | 模拟结果 | 说明 |
+|--------|---------|------|
+| detectPyCmd（python3 探测） | ✓ PASS | mac 上 python 不存在时正确回退 python3 |
+| .repo-root 锚点 | ✓ PASS | 用 PROJECT_ROOT，从任意 cwd 跑都指向仓库根 |
+| venv 路径分支 | ✓ PASS | mac 下正确指向 `bin/python`（非 Scripts/python.exe） |
+| find_repo_root 4 级回退 | ✓ PASS | 纯 os.path，跨平台无硬编码分隔符 |
+| _find_python_with_deps | ✓ PASS | 用 shutil.which 探测，不硬编码 mac 路径 |
+
+## 前置：你的 mac 环境是什么
+
+先跑这条，把基础信息发回来：
+```bash
+sw_vers  # macOS 版本
+which python python3 node git brew 2>/dev/null  # 已装的工具
+```
+
+---
+
+## 阶段 1：环境安装（如果 python/node 没装）
+
+```bash
+npx @hupan56/wlkj install-env --check
+```
+**预期**：列出 Node/Python/git 检测结果。缺哪个会标 `[缺失]`。
+
+如果缺，去掉 `--check` 自动装（用 brew）：
+```bash
+npx @hupan56/wlkj install-env
+```
+**预期**：`[OK] Node.js 已装` / `[OK] Python 已装` / pip 依赖装上（失败会切清华镜像）。
+
+**关键验证点**（本轮修复）：
+- pip 装包如果默认源失败，应该自动切"清华"镜像重试
+- 如果看到 `pip 安装失败 (尝试了所有镜像)` 才算异常
+
+**mac 专属排查（brew 装完 PATH 未更新的常见坑）**：
+- `brew install python@3.12` 装完后，**当前终端的 PATH 可能还没更新**，
+  导致 `python3: command not found`。
+- 如果装完仍报缺失，**重开一个终端**再跑 `install-env --check`。
+- 或手动验证：`which python3`（应指向 `/opt/homebrew/bin/python3` 或 `/usr/local/bin/python3`）
+- 如果 `which python3` 找不到，跑：`brew link python@3.12` 或按 brew 提示加 PATH。
+
+---
+
+## 阶段 2：初始化工作流
+
+```bash
+cd ~/your-workspace   # 你放工作流的目录
+npx @hupan56/wlkj init 你的名字 你的角色
+```
+角色填：`pm` / `design` / `dev` / `test` / `admin`
+
+**预期**：
+- 环境检测：`Python: [OK] Python 3.x.x (python3)` ← **mac 上应该是 python3，不是 python**
+- 角色选择菜单（如果没传角色参数）：列出 5 个角色让你选
+- 安装完成：`安装完成! (v2.7.0)`
+
+**关键验证点**（本轮修复）：
+- macOS 上用 `python3` 不报错（旧版硬编码 `python` 会 `command not found`）
+- 角色不是写死的 pm（旧版所有人都是 pm）
+
+---
+
+## 阶段 3：状态检查
+
+```bash
+npx @hupan56/wlkj status
+```
+**预期**：
+```
+dev: 你的名字 (角色: dev)    ← 显示你的角色，不是 pm
+...
+engine: 2.7.0 (最新: v2.7.0) [最新]
+```
+
+---
+
+## 阶段 4：MCP 健康检查（核心！）
+
+```bash
+python3 .qoder/scripts/check_mcp.py
+```
+**预期**：7 项检查，每项 `[OK]` 或 `[WARN]`（WARN 是可选功能没装，正常）：
+```
+--- 1. mcp.json 配置 ---
+[OK]   mcp.json 存在, 注册了 4 个 server
+[OK]   N 个 server 用 launcher 模式
+--- 2. 仓库根定位 ---
+[OK]   .repo-root 锚点正确: /Users/你的名字/your-workspace
+--- 3. MCP launcher ---
+[OK]   launcher 存在: ~/.qoderwork/mcp_launcher.py
+--- 4. 知识图谱 MCP (kg) ---
+[OK]   kg 就绪 (python=..., 装了 duckdb)
+--- 5. MySQL MCP ---
+[OK/WARN] ...
+--- 6. 蓝湖 MCP ---
+[OK/WARN] ...
+--- 7. Playwright MCP ---
+[OK/WARN] ...
+所有 MCP 就绪, Qoder 全系列可正常调用。
+```
+
+**关键验证点**（本轮修复）：
+- `.repo-root 锚点正确` 指向你的工作流目录（旧版可能指向错误目录）
+- 末尾 `所有 MCP 就绪` 或明确列出未就绪项
+
+---
+
+## 阶段 5：QoderWork 桌面端验证
+
+1. 打开 QoderWork 桌面端
+2. 新建对话，输入：`/wl-status`
+3. **预期**：显示项目状态，含"当前角色: 你的角色名"
+
+**关键验证点**：
+- MCP 工具能调（说"查一下车辆代码"，kg MCP 响应）
+- 不出现"MCP 连接失败"黄标
+
+---
+
+## 阶段 6：性能感受（非必须，主观）
+
+- `/wl-search 车辆`：应该 < 1 秒返回
+- `/wl-prd-quick` 写个小需求：取上下文 + 出原型应该顺畅
+
+如果某个命令明显卡（> 5 秒），记下是哪个命令 + 大概多久。
+
+---
+
+## 反馈格式
+
+跑完把这份填回来：
+```
+阶段1 环境: ✓/✗ (备注)
+阶段2 init: ✓/✗ (python3 是否正常 / 角色是否正确)
+阶段3 status: ✓/✗ (角色显示对不对)
+阶段4 check_mcp: ✓/✗ (几个 OK / 几个 WARN / 有无 BAD)
+阶段5 QoderWork: ✓/✗ (MCP 是否绿 / 工具能否调)
+阶段6 性能: (主观, 卡不卡)
+```
+
+有 ✗ 的项，把完整命令输出贴回来，我来定位修复。
+
+---
+
+## mac 专属注意事项（Windows 上测不到的坑）
+
+1. **cron 全盘访问**：init 时会装周五 18:00 的定时更新（setup_weekly_cron.sh）。
+   macOS 默认 cron 没磁盘权限，任务会静默失败。
+   - 现象：`.qoder/logs/weekly-update.log` 不增长或报权限错
+   - 修复：系统设置 → 隐私与安全 → 完全磁盘访问 → 添加 `/usr/sbin/cron`
+   - 不影响日常使用，只影响每周自动更新（可手动跑 git_sync.py 替代）
+
+2. **brew python 的 PATH**：见阶段 1 的排查提示。brew 装完要重开终端。
+
+3. **lanhu venv 路径**：mac 上是 `.venv/bin/python`（非 Windows 的 `Scripts/python.exe`）。
+   check_mcp.py 已适配，但如果 setup_lanhu.py 没在 mac 上测过，留意这步。
+
+4. **文件权限**：mac 上从 git 拉的 .sh 脚本可能没执行权限。
+   如果 `setup_weekly_cron.sh` 报 permission denied：`chmod +x .qoder/scripts/*.sh`
+
+5. **大小写敏感文件系统**：mac 默认大小写不敏感（APFS），
+   如果代码里有 `Search.py` 和 `search.py` 会冲突。工作流脚本都是小写，一般无碍。

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@hupan56/wlkj",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
   "bin": {
     "wlkj": "bin/cli.js"
   },
   "files": [
     "bin/",
-    "templates/"
+    "templates/",
+    "MAC-VERIFY.md"
   ],
   "keywords": [
     "workflow",