常见问题 (FAQ)
安装相关
Q: pip install ipman-cli 报错 "no matching distribution found"，怎么办？
此错误有两种常见原因：
原因 1（最常见）：Python 版本低于 3.10
IpMan 要求 Python >= 3.10。当你的 Python 版本不满足要求时，PyPI 找不到兼容的发行版。
原因 2：VPN / 代理导致 SSL 连接失败
如果你处于 VPN 或企业网络环境，pip 可能因 SSL 证书验证失败而无法连接 PyPI，错误信息有时也会表现为 "no matching distribution"（伴随 SSL 相关警告）。参见下方 SSL 报错（见下方） 条目。
排查步骤：
# 1. 确认 Python 版本（必须 >= 3.10）
python3 --version
# 2. 如果版本满足要求，测试 PyPI 连通性
pip index versions ipman-cli
解决： - 如果是版本问题，升级 Python 到 3.10+ - 如果是网络问题，参见下方 SSL 报错（见下方）
macOS 用户推荐通过 Homebrew 安装：
brew install python@3.12
安装后需将其设为默认版本，参见安装指南。
Q: macOS 上如何将 Homebrew 安装的 Python 3.12 设为默认？
在 ~/.zshrc 中添加 PATH 配置：
echo 'export PATH="$(brew --prefix python@3.12)/libexec/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
验证：
python3 --version # 应显示 3.12.x
which python3 # 应指向 Homebrew 路径
注意：不要删除或覆盖
/usr/bin/python3，macOS 系统工具可能依赖它。上述方法通过 PATH 优先级"遮盖"系统版本，安全且可逆。
Q: Python 3.12 下 pip install 报错 "externally-managed-environment"，怎么办？
原因：Python 3.12 实施了 PEP 668，禁止 pip 直接向 Homebrew 等包管理器维护的 Python 环境中安装包，以防止系统包管理器和 pip 之间的冲突。
推荐方案：使用 pipx 安装 CLI 工具：
brew install pipx
pipx ensurepath
pipx install ipman-cli
pipx 会自动为 ipman-cli 创建独立的虚拟环境，不影响系统 Python 环境。
VPN 用户注意：如果 pipx 安装时也报 SSL 错误，需要加信任参数：
详见下方 SSL 报错（见下方） 条目。pipx install ipman-cli --pip-args="--trusted-host pypi.org --trusted-host files.pythonhosted.org"
备选方案：手动创建虚拟环境：
python3 -m venv ~/.ipman-venv
source ~/.ipman-venv/bin/activate
pip install ipman-cli
不推荐：
pip install --break-system-packages ipman-cli虽然可以绕过限制，但可能导致 Homebrew 管理的 Python 包损坏。
Q: pip install 报错 "SSL: CERTIFICATE_VERIFY_FAILED"，怎么办？
典型报错：
WARNING: Retrying ... after connection broken by 'SSLError(SSLCertVerificationError(1,
'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate'))'
原因：通常是 VPN、企业代理或缺少 CA 根证书导致 pip 无法验证 PyPI 的 SSL 证书。
方案 1：VPN / 企业代理环境（最常见）
临时跳过 SSL 验证完成安装：
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org ipman-cli
pipx 用户：
pipx install ipman-cli --pip-args="--trusted-host pypi.org --trusted-host files.pythonhosted.org"
提示：如需永久生效，可写入 pip 配置文件
~/.pip/pip.conf：[global] trusted-host = pypi.org files.pythonhosted.org
方案 2：macOS 缺少 CA 证书
brew install ca-certificates
方案 3：将企业根证书加入信任链
如果你的公司网络使用 SSL 中间人代理，需要把公司根证书导入系统钥匙串或 Python 的证书库：
# 获取公司根证书（通常由 IT 部门提供），然后：
# macOS：双击 .crt 文件导入钥匙串，并设为"始终信任"
# 或：通过环境变量指定
export SSL_CERT_FILE=/path/to/company-root-ca.crt
Q: 支持哪些 Python 版本？
IpMan 要求 Python >= 3.10。推荐使用 Python 3.12 或更高版本。
不支持 Python 3.9 及以下版本，因为项目使用了 3.10+ 的语言特性（如 match/case 模式匹配、X | Y 类型联合语法等）。
Q: 支持哪些操作系统？
核心工作流在 macOS 上验证通过。Linux 预期可用（软链接语义相同）但尚未进入验证矩阵。Windows 有降级代码路径（目录 junction），目前未验证，暂不作为支持目标。
使用相关
Q: IpMan 支持哪些 Agent 工具？
- Claude Code（
.claude/skills/）—— 已验证目标 - OpenClaw（
.openclaw/skills/）—— 仅路径映射，未验证
store 和 lockfile 在设计上与 agent 无关；新增一个 agent 只需一行路径映射。下一个正式验证的 agent 由真实用户需求决定。
Q: ipman add 报错说仓库里有多个技能？
这是有意设计。多技能仓库必须显式选择：
ipman add https://github.com/owner/skills-repo#skills/你要的那个
报错信息会列出仓库里所有含 SKILL.md 的目录。
Q: ip.lock 要提交进 git 吗？
要——ip.yaml 和 ip.lock 都提交。这正是意义所在：任何人 clone 你的仓库后跑一句 uvx ipman-cli sync，就能拿到完全一致的技能源码。受管软链接本身会被自动 git-ignore。
Q: 换机器后 sync 报 portable: false？
从本地路径添加的技能（含 --adopt）无法在没有该路径的机器上复原。需要跨机器的技能请使用 git URL 源；本地源适合你自己开发中的技能。
Q: ipman install / ipman hub 去哪了？
休眠了，没删——仍可执行，但从 --help 中隐藏。现在的核心命令面是 init/add/sync/list/remove/update/doctor。
Q: ipman init 以前是配置 shell 的，现在怎么变了？
shell 集成移到了 ipman shell init。带显式 shell 参数的旧用法（如 ipman init zsh）仍然有效，会转发并提示弃用；不带参数的 ipman init 现在是项目初始化（生成 ip.yaml）。
Q: 我想接管某个工具包 clone（比如 gstack），被拒绝了，为什么？
因为有别的技能依赖它。gstack 这类工具包是 git clone，你另外几十个技能只是薄外壳——它们的 SKILL.md 软链接指向这个 clone 内部。接管（移动）这个 clone 会把它们全部弄断，而且是静默的。IpMan 检测到依赖者就会拒绝，并列出它们。工具包的正确保护是接管目录（ipman takeover）：整个技能目录进 IpMan 保管，工具包与外壳原地保留，它自己的更新器照常工作。没有任何东西依赖的普通 git clone 则可正常接管（会提示上游丢失）。
Q: 归属为"套件"的技能为什么不能接管？
刻意保护。套件型技能的目录里文件本身就是软链接，指向套件自己的 clone——内容在那边，由套件的更新器管理。硬接管只会收进一壳指针（不省空间、无法去重），还会在每次套件升级时跟更新器打架。想保护套件技能，用接管目录（ipman takeover）：整个技能目录进 IpMan 保管，套件外壳原样保留（相对链接自动改写为绝对），套件更新器照常工作，同时获得防误删与一键复原。
Q: 怎么更新 ipman？
命令行用 pipx upgrade ipman-cli（或 uv tool upgrade ipman-cli），然后 ipman skill-sync 让技能跟上。更省事的办法是在 agent 里用 /ipman-update 技能——它会检测安装方式、征得同意后升级 CLI 并重新生成技能。
Q: 界面能显示中文吗？
能，而且自动。状态值、报错、TUI 与 CLI 输出都会根据 LANG / LC_ALL（zh* → 中文，其它 → 英文）自动切换，无需任何配置。
Q: 套件·gstack 是什么意思？
这个技能是指向 gstack 工具包 clone 内部的外壳——由 gstack 自己的更新器管理。IpMan 只识别、不接管这类技能；想保护它们请对整个目录用 ipman takeover。
Q: 怎么把 ipman 放进状态栏？
ipman statusline 输出一行状态，在 Claude Code 的 settings.json 的 statusLine 命令里接入即可。
Q: 支持哪些操作系统？
macOS + Claude Code 已验证。Windows 的逐技能操作有 CI 覆盖（junction 降级），目录级接管待 Windows 验证后开放。Linux 预期可用。
Q: 如何查看已安装的版本？
ipman --version