故障排查

安装完成后提示找不到 lumenlan

macOS 与 Linux 默认安装到 ~/.local/bin。把该目录加入 shell 的 PATH 后重新打开终端；也可以用 --install-dir 安装到已有的命令目录。Windows 默认把安装目录加入用户 PATH，但当前 PowerShell 可能仍使用旧环境，请打开一个新窗口再运行 lumenlan version。

安装器报告 SHA-256 或版本探测失败

安装器会拒绝与正式版 SHA256SUMS 不一致的文件，也会运行下载后的二进制核对版本。先确认系统 时间、HTTPS 连接和磁盘空间正常，再重试一次。企业代理若替换下载内容会触发保护；不要绕过校验， 可以从手工下载页取得二进制与清单后在本机独立核对。

命令退出 2 或结果是 blocked

退出码 2 表示动作没有获得完整执行条件，不等于检查失败。查看 JSON 的 outcome、diagnostics 和 capability 信息，确认依赖工具、平台沙箱、授权期限、机器与项目是否匹配。Windows workspace 在 缺少合格沙箱后端时按设计 blocked；请换到支持的目标机，不要把它改成不隔离运行。

命令退出 3 或结果是 invalid

退出码 3 表示规格、字段、profile 或边界无效。确认请求使用已登记的版本，verification 中没有 自由命令或动态脚本，workspace 请求选择的 process、script 或 adapter 与授权 scope 一致。修正 输入后重新执行；不要把 invalid 当作普通业务失败重试。

stdout 不是合法 JSON

CLI 自身只把契约 JSON 写到 stdout。检查外层包装脚本、终端插件或 MCP 配置是否在 stdout 打印了 横幅；帮助、诊断和日志应读取 stderr。需要看帮助时单独运行 lumenlan --help。

MCP 客户端无法连接

先在同一用户环境确认 lumenlan mcp serve --transport stdio 能被找到，配置中不要添加网络地址。 修改后重启客户端。若仍失败，保存不含敏感内容的 stderr、CLI 版本、操作系统和退出码，再联系 support@lumenlan.com。