@hupan56/wlkj 2.7.1 → 2.7.3

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.3",
   "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",

package/templates/qoder/scripts/platform_doctor.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+platform_doctor.py - 跨平台环境自诊断 (任何 OS 跑, 输出环境真相)
+
+为什么需要它:
+  MAC-VERIFY.md 是人工清单, mac 同事跑完如果失败, 反馈信息往往不够定位。
+  本脚本自动收集所有跨平台关键信息, 一次跑完输出结构化报告,
+  同事直接把输出贴回来即可 —— 无需懂代码。
+
+  它在任何 OS (Windows/macOS/Linux) 上行为一致, 显式报告:
+  - 平台 + 架构
+  - python/python3/node/git 是否可用 + 真实路径
+  - 工作流引擎是否完整 (关键脚本在不在)
+  - MCP 各组件就绪状态
+  - 角色配置
+  - 发现的问题 + 修复建议
+
+Usage:
+    python3 .qoder/scripts/platform_doctor.py
+    # 或 mac 上: python3 platform_doctor.py (从包目录跑也行)
+Exit: 0 = 健康, 1 = 有问题
+"""
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except (AttributeError, IOError):
+        pass
+
+# 定位仓库根 (和 mcp_launcher 同样的多级回退)
+HERE = Path(__file__).resolve().parent
+BASE = None
+for candidate in [HERE.parent.parent, HERE.parent, HERE]:
+    if (candidate / '.qoder' / 'scripts').is_dir():
+        BASE = candidate
+        break
+if BASE is None:
+    BASE = HERE.parent.parent  # 最佳猜测
+
+report = {'platform': {}, 'tools': {}, 'engine': {}, 'mcp': {},
+          'role': {}, 'issues': [], 'verdict': 'UNKNOWN'}
+
+
+def add_issue(level, msg, fix=None):
+    report['issues'].append({'level': level, 'msg': msg, 'fix': fix or ''})
+
+
+def which(cmd):
+    """找命令路径, 返回字符串或 None。"""
+    return shutil.which(cmd)
+
+
+def run(cmd, timeout=8):
+    """跑命令, 返回 (rc, output)。"""
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True,
+                           encoding='utf-8', errors='replace', timeout=timeout)
+        return r.returncode, (r.stdout or '').strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return 1, ''
+
+
+# ============================================================
+# 1. 平台信息
+# ============================================================
+report['platform'] = {
+    'sys_platform': sys.platform,
+    'platform_system': platform.system(),
+    'machine': platform.machine(),
+    'python_version': sys.version.split()[0],
+    'python_executable': sys.executable,
+}
+plat_name = platform.system()
+is_mac = sys.platform == 'darwin'
+is_win = sys.platform == 'win32'
+print('【平台】 %s %s (sys.platform=%s)' % (
+    plat_name, platform.machine(), sys.platform))
+print('  Python: %s @ %s' % (sys.version.split()[0], sys.executable))
+
+# ============================================================
+# 2. 工具探测 (python/python3/node/git/brew)
+# ============================================================
+print('\n【工具探测】')
+for tool in ['python', 'python3', 'node', 'npm', 'npx', 'git']:
+    if is_mac and tool == 'python':
+        # mac 上 python 通常不存在, 这是正常的
+        pass
+    p = which(tool)
+    ver = ''
+    if p:
+        if tool in ('python', 'python3'):
+            rc, v = run([tool, '--version'])
+            ver = v or '(版本未知)'
+        elif tool in ('node',):
+            rc, v = run([tool, '--version'])
+            ver = v
+        elif tool == 'git':
+            rc, v = run([tool, '--version'])
+            ver = v
+    report['tools'][tool] = {'path': p, 'version': ver}
+    status = '✓ %s' % ver if p else '✗ 未找到'
+    print('  %-8s %s' % (tool, status))
+
+# 关键: python/python3 关系 (mac 验证核心)
+py = which('python')
+py3 = which('python3')
+if is_mac and not py and py3:
+    print('  [mac 正常] python 不存在, python3 可用 (cli.js detectPyCmd 会选 python3)')
+elif not py and not py3:
+    add_issue('CRITICAL', 'python 和 python3 都没找到',
+              'mac: brew install python@3.12; win: 装 Python 勾 Add to PATH')
+elif not py3 and py:
+    add_issue('WARN', '只有 python 没有 python3 (罕见, 一般不影响)')
+
+if is_mac:
+    brew = which('brew')
+    print('  brew:    %s' % (brew or '✗ (装包用: https://brew.sh)'))
+
+# ============================================================
+# 3. 引擎完整性
+# ============================================================
+print('\n【工作流引擎】')
+scripts_dir = BASE / '.qoder' / 'scripts'
+key_scripts = [
+    'setup.py', 'kg.py', 'context_pack.py', 'search_index.py',
+    'mcp_launcher.py', 'install_qoderwork.py', 'role.py',
+    'common/pip_install.py', 'common/events.py', 'common/platform_guard.py',
+    'check_mcp.py', 'check_carriers.py',
+]
+missing_scripts = []
+for s in key_scripts:
+    exists = (scripts_dir / s).is_file()
+    if not exists:
+        missing_scripts.append(s)
+    report['engine'][s] = exists
+
+if missing_scripts:
+    add_issue('CRITICAL', '引擎脚本缺失: %s' % ', '.join(missing_scripts),
+              '跑: npx @hupan56/wlkj update')
+    print('  ✗ 缺失: %s' % ', '.join(missing_scripts))
+else:
+    print('  ✓ %d 个关键脚本齐全' % len(key_scripts))
+
+# 引擎版本
+ver_file = BASE / '.qoder' / '.engine-version'
+if ver_file.is_file():
+    ver = ver_file.read_text(encoding='utf-8').strip()
+    report['engine']['version'] = ver
+    print('  引擎版本: %s' % ver)
+
+# ============================================================
+# 4. MCP 组件
+# ============================================================
+print('\n【MCP 组件】')
+# 4.1 mcp.json
+HOME = Path(os.environ.get('USERPROFILE') or os.path.expanduser('~'))
+mcp_file = HOME / '.qoderwork' / 'mcp.json'
+if mcp_file.is_file():
+    try:
+        cfg = json.loads(mcp_file.read_text(encoding='utf-8'))
+        servers = list(cfg.get('mcpServers', {}).keys())
+        report['mcp']['servers'] = servers
+        print('  mcp.json: %d 个 server (%s)' % (len(servers), ', '.join(servers)))
+    except (ValueError, OSError):
+        add_issue('WARN', 'mcp.json 解析失败', '重跑 install_qoderwork.py --mcp-only')
+        print('  mcp.json: 解析失败')
+else:
+    add_issue('WARN', 'mcp.json 不存在 (QoderWork 未配 MCP)',
+              '跑: python .qoder/scripts/install_qoderwork.py --mcp-only')
+    print('  mcp.json: 不存在')
+
+# 4.2 .repo-root 锚点
+anchor = HOME / '.qoderwork' / '.repo-root'
+if anchor.is_file():
+    root_val = anchor.read_text(encoding='utf-8').strip()
+    is_correct = (Path(root_val) / '.qoder' / 'scripts').is_dir()
+    report['mcp']['repo_root'] = root_val
+    if is_correct:
+        print('  .repo-root: ✓ 指向 %s' % root_val)
+    else:
+        add_issue('CRITICAL', '.repo-root 指向错误目录: %s' % root_val,
+                  '跑: python install_qoderwork.py --mcp-only (会用 PROJECT_ROOT 修复)')
+        print('  .repo-root: ✗ 指向错误 %s' % root_val)
+else:
+    add_issue('WARN', '.repo-root 锚点不存在',
+              '跑: install_qoderwork.py --mcp-only')
+    print('  .repo-root: 不存在')
+
+# 4.3 duckdb (kg MCP 依赖)
+try:
+    import duckdb
+    print('  duckdb: ✓ 已装 (kg MCP 可用)')
+    report['mcp']['duckdb'] = True
+except ImportError:
+    add_issue('CRITICAL', 'duckdb 未装 (kg MCP 会崩)',
+              'pip install duckdb 或 npx wlkj install-env')
+    print('  duckdb: ✗ 未装')
+
+# ============================================================
+# 5. 角色配置
+# ============================================================
+print('\n【角色配置】')
+dev_file = BASE / '.qoder' / '.developer'
+if dev_file.is_file():
+    lines = dev_file.read_text(encoding='utf-8').split('\n')
+    name_l = next((l for l in lines if l.startswith('name=')), '')
+    role_l = next((l for l in lines if l.startswith('role=')), '')
+    name = name_l.split('=', 1)[1].strip() if name_l else '?'
+    role = role_l.split('=', 1)[1].strip() if role_l else 'pm(默认)'
+    report['role'] = {'name': name, 'role': role}
+    print('  开发者: %s' % name)
+    print('  角色: %s' % role)
+    if not role_l:
+        add_issue('INFO', '角色未显式设置 (默认 pm)',
+                  '重跑 init 选角色: npx wlkj init %s <pm|design|dev|test|admin>' % name)
+else:
+    add_issue('CRITICAL', '.developer 不存在 (未初始化)',
+              '跑: npx @hupan56/wlkj init <名字> <角色>')
+    print('  未初始化!')
+
+# ============================================================
+# 6. 总结
+# ============================================================
+criticals = [i for i in report['issues'] if i['level'] == 'CRITICAL']
+warns = [i for i in report['issues'] if i['level'] == 'WARN']
+
+print('\n' + '=' * 56)
+if criticals:
+    print('发现 %d 个严重问题:' % len(criticals))
+    for i in criticals:
+        print('  🔴 %s' % i['msg'])
+        if i['fix']:
+            print('     修复: %s' % i['fix'])
+    report['verdict'] = 'BROKEN'
+elif warns:
+    print('发现 %d 个警告 (非阻塞, 但建议处理):' % len(warns))
+    for i in warns:
+        print('  🟡 %s' % i['msg'])
+        if i['fix']:
+            print('     建议: %s' % i['fix'])
+    report['verdict'] = 'OK_WITH_WARNINGS'
+else:
+    print('✓ 环境健康, 工作流可用。')
+    report['verdict'] = 'HEALTHY'
+print('=' * 56)
+
+# 机器可读报告 (便于同事贴回来)
+print('\n--- 可粘贴报告 (JSON) ---')
+print(json.dumps(report, ensure_ascii=False, indent=2))
+
+sys.exit(1 if criticals else 0)