fix(maker): install lua lsp in private venv

[529951164]

背景

• mac 冒烟发现 uv-managed Python 3.12.13 会拒绝直接 pip install。
• 原流程把 maker-lua-lsp 装进 uv-managed Python，触发 externally-managed-environment。

改动内容

• 创建 Maker 私有 lua-lsp-venv，并在 venv 内安装 maker-lua-lsp。
• 保持 uv-managed Python 只负责创建 venv，不直接写入诊断依赖。
• doctor 探测支持 maker-lua-lsp 不提供 --version 时 fallback 到 --help。
• 更新 CLI/runtime 测试和 Maker 文档里的 LSP 安装流程。

验证

• npm test -- makerLuaLspRuntime.test.ts makerCliCommands.test.ts makerBuildLocalChanges.test.ts --runInBand
• npm run format:check
• npm run lint
• npm run build -- --skip-server --skip-proxy --skip-native
• 构建 @taptap/maker tgz 并用全新 TAPTAP_MAKER_HOME 冒烟验证。
• 冒烟确认 maker-lua-lsp 安装在 lua-lsp-venv，uv-managed Python 中未安装该包。

[greptile-apps]

Greptile Summary

此 PR 修复了 uv-managed Python 3.12 拒绝直接 pip install 导致的 externally-managed-environment 错误，核心方案是为 maker-lua-lsp 创建专用私有 venv（~/.taptap-maker/lua-lsp-venv/），将 LSP 安装与 uv-managed Python 完全隔离。

• venv 隔离：新增 ensureLuaLspVenv + isLuaLspVenvComplete（同时检查 pyvenv.cfg 和 venvPython），解决了中断后残留不完整 venv 导致的反复失败问题；resolveLuaLspCommand 优先从 venv 路径解析命令。
• doctor 健壮性：readLuaLspVersion 在 --version 失败时 fallback 到 --help，两次探测均加入 5 s 超时；checkMakerLuaLspEnvironment 新增 saved.command 快速路径，避免不必要的磁盘扫描。
• 文档与测试：8 个文件同步更新，新增 venv 重建和 --help fallback 两个测试用例，已有测试全部更新 mock 路径。

Confidence Score: 5/5

变更范围清晰，核心逻辑已有单元测试覆盖，可安全合并。

本次改动将 LSP 安装路径从 uv-managed Python 迁移到独立 venv，逻辑层次清晰：venv 完整性检测兼顾了 Python 二进制和 pyvenv.cfg 两个判断条件，修复了之前 review 指出的不完整 venv 循环失败问题；readLuaLspVersion 的 --help fallback 和超时约束也已到位。测试新增了 venv 重建和 --help fallback 两个关键场景。仅存在一处冗余版本探测的效率问题（同一损坏二进制最多被探测两次），属于边缘场景下的轻微开销，不影响功能正确性。

src/maker/system/luaLsp.ts 中 checkMakerLuaLspEnvironment 的 saved.command 快速路径与 resolveLuaLspCommand 存在冗余探测路径，值得关注但不阻塞合并。

Important Files Changed

Filename	Overview
src/maker/system/luaLsp.ts	核心变更：新增 ensureLuaLspVenv / isLuaLspVenvComplete / getLuaLspVenv* 辅助函数将 LSP 安装隔离到私有 venv；checkMakerLuaLspEnvironment 添加 saved.command 快速路径；readLuaLspVersion 新增 --help fallback 及 5 s 超时；整体逻辑正确，存在 saved.command 与 venv command 路径相同时的冗余版本探测问题。
src/tests/makerLuaLspRuntime.test.ts	新增两个测试：(1) venv 不完整时触发重建；(2) 仅支持 --help 的 LSP 被 doctor 正确识别；现有测试用例同步更新 venv 路径和 mock 行为，覆盖完整。
src/tests/makerCliCommands.test.ts	两个测试用例更新：mock 改为先触发 python -m venv，再用 venvPython 执行 pip install，断言也同步添加了 venv 创建步骤的 spawnSync 调用校验。
docs/MAKER.md	lua-lsp setup 和 python setup 的描述更新为引用私有 LSP venv，文档与代码行为一致。
docs/MAKER_PYTHON_RUNTIME_WINDOWS_TEST.md	更新 Windows 测试文档，添加 lua-lsp-venv 创建步骤及预期输出，与新流程一致。
AGENTS.md	单行更新，将直接安装/升级改为创建 Maker 私有 LSP venv 并在其中安装/升级，与实现保持一致。
docs/MAKER_CLI_MCP_SKILL_REWORK_OVERVIEW.md	更新 CLI 命令描述以反映 venv 隔离策略，无遗漏。
skills/taptap-maker-local/SKILL.md	Skill 说明更新，指出 setup 先创建私有 LSP venv 再安装，英文表述准确。

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[setupMakerLuaLspEnvironment] --> B{Python ready?}
    B -- No --> Z1[返回 python_missing]
    B -- Yes --> C[ensureLuaLspVenv]

    C --> D{isLuaLspVenvComplete?\nvenvPython + pyvenv.cfg 均存在}
    D -- Yes --> E
    D -- No --> F[python -m venv lua-lsp-venv\ntimeout=120s]
    F --> G{status=0?}
    G -- No --> Z2[返回 setup_failed]
    G -- Yes --> E

    E[venv.python pip install maker-lua-lsp\ntimeout=120s] --> H{status=0?}
    H -- No --> Z3[返回 setup_failed]
    H -- Yes --> I[resolveLuaLspCommand\n优先检查 venv command]
    I --> J[maker-lua-lsp install --ide\ntimeout=120s]
    J --> K{status=0?}
    K -- No --> Z4[返回 setup_failed]
    K -- Yes --> L[readLuaLspVersion\n--version / --help fallback\ntimeout=5s]
    L --> M[saveLuaLspRuntimeConfig status=ready]
    M --> N[返回 changed=true]

    subgraph checkMakerLuaLspEnvironment
        P[加载 lua-lsp.json] --> Q{saved.command?}
        Q -- Yes --> R[readLuaLspVersion timeout=5s]
        R --> S{version?}
        S -- Yes --> T[返回 ready 快速路径]
        S -- No --> U[resolveLuaLspCommand]
        Q -- No --> U
        U --> V[readLuaLspVersion timeout=5s]
        V --> W{version?}
        W -- Yes --> T2[返回 ready]
        W -- No --> X{setup_failed?}
        X -- Yes --> Y[返回 setup_failed]
        X -- No --> Z[返回 missing]
    end

Loading

_{Reviews (2): Last reviewed commit: "fix(maker): harden lua lsp venv recovery" | Re-trigger Greptile}