=== BRAIN CLI 助手安装说明 (Windows / Mac / Linux) ===

【Windows 安装方式】
1. 将整个项目文件夹放到自己用户目录的子目录中，例如 C:\Users\Steve\AIWorker。
2. 普通双击 _auto_setup.bat，不要选择“以管理员身份运行”。
   也可在普通 PowerShell 窗口进入项目目录后运行：
   powershell -NoProfile -ExecutionPolicy Bypass -File ".\_auto_setup.ps1"
3. 脚本按需申请 UAC 管理员授权；不要把整个安装过程提权。
4. 项目目录或已有 .venv 不可写时，会仅为权限修复弹出 UAC。
   修复完成后，原来的普通用户进程会重新检查权限，再继续创建虚拟环境和安装工具。
   自动修复仅限用户目录中的项目子目录，不处理整个用户目录、系统目录或项目外部链接目标。
   如果取消 UAC、修复失败或修复后仍不可写，安装会停止并说明原因。
5. Claude CLI 使用 Anthropic 官方原生安装器 https://claude.ai/install.ps1，
   不再通过 npm 安装，也不再为此安装 Node.js。
   用户级 Claude 路径为 %USERPROFILE%\.local\bin\claude.exe。
6. 按提示配置 BRAIN 账号、模型 API Key 及可选功能。完成后重新打开终端。

【Windows 启动方式】
1. 在普通 PowerShell 终端进入项目目录。
2. 运行官方原生版：& "$env:USERPROFILE\.local\bin\claude.exe" --agent brain-consultant
   也可使用 claude --agent brain-consultant；若命中了旧 npm 版，请用上面的完整路径。
3. Windows 安装会将项目 hook 改为通过 uv 使用虚拟环境中的 Python，不要求系统另装 Python。

【Mac/Linux 安装方式】
1. 打开终端（Mac: 访达 → 应用程序 → 实用工具 → 终端）
2. 进入此文件夹：cd /path/to/Brain_工具一键安装_MacLinux版本
3. 以普通用户运行一键安装：bash _auto_setup.sh（不要在前面加 sudo）
4. 项目目录不可写或需要安装系统依赖时，脚本会单独调用 sudo；修复后继续使用普通用户安装
5. 按提示完成配置（BRAIN 平台账号密码（必填）、API Key、可选知识库等）
6. 安装完成后，关闭终端重新打开

【Mac/Linux 启动方式】
1. 打开终端
2. 进入安装目录：cd /path/to/Brain_工具一键安装_MacLinux版本
3. 启动助手：claude --agent brain-consultant

【Mac/Linux 工具安装方式】
- Claude CLI 使用 Anthropic 官方原生安装器：https://claude.ai/install.sh
- 安装到 ~/.local/bin/claude，不再通过 npm 安装，也不再为此安装 Node.js
- 新终端的 PATH 会自动补充 ~/.local/bin；已有其他位置的 Claude 不会自动卸载

【需要准备】
- BRAIN 平台账号密码（必填，安装时会强制配置，用于知识库、Osmosis 和 MCP 工具）
- LLM API Key

【Hook 说明】
- .claude/settings.json 是一个 hook 配置文件
- 它会在 simulate alpha 之后自动检查表达式语法
- 如果不需要，可以用 /hooks 命令禁用

【常见问题】
Q: 直接运行 ./_auto_setup.sh 提示 "permission denied"
A: 可改用 bash _auto_setup.sh；也可以先 chmod +x _auto_setup.sh。

Q: 第 2 步创建 .venv 提示 "Permission denied (os error 13)"
A: 这表示项目目录或已有 .venv 无法写入，与脚本是否有执行权限不同。
   常见原因是曾用 sudo 复制、解压或安装，目录归 root 所有。
   新版脚本会在安装前测试项目目录和已有 .venv 是否可写。
   如果不可写，会调用 sudo 修复当前项目的所有权和当前用户读写权限；
   按提示输入 sudo 密码即可，不需要手动执行修复命令。
   修复后会再次检查权限，通过后继续以普通用户创建虚拟环境并安装 Claude。
   自动修复只适用于家目录内的项目子目录，例如 /home/steve/AIWorker；
   不会修复整个家目录或系统目录，也不会沿项目内的符号链接修改外部目标。
   如果 .venv 指向项目外部，请先将虚拟环境放回项目目录。
   sudo 失败、取消或修复后仍不可写时，脚本会停止；请检查 ACL、只读挂载或磁盘空间。
   始终使用 bash _auto_setup.sh 启动，不要给整个脚本加 sudo。

Q: uv 安装失败
A: 手动安装：curl -LsSf https://astral.sh/uv/install.sh | sh

Q: Claude CLI 安装失败
A: 以普通用户运行官方安装器：curl -fsSL https://claude.ai/install.sh | bash
   然后运行：export PATH="$HOME/.local/bin:$PATH"
   验证：claude --version
   官方说明：https://code.claude.com/docs/en/setup
   若官方下载失败，请检查网络；脚本不会回退到 npm 安装。

Q: 镜像源连接超时
A: 检查网络连接，或手动设置：export UV_DEFAULT_INDEX="https://pypi.org/simple"

Q: 知识库创建失败 / 提示缺少账号密码
A: 账号密码在安装时已强制配置（Step3），可稍后单独运行：
   .venv/bin/python Step5_create_knowledge_base.py
   若提示缺少账号，先运行: .venv/bin/python Step3_set_brain_credentials.py

Q: BRAIN 账号配置失败或需要更换账号
A: 重新运行: .venv/bin/python Step3_set_brain_credentials.py

【Windows 常见问题】
Q: uv 安装失败
A: 在普通 PowerShell 中执行：irm https://astral.sh/uv/install.ps1 | iex

Q: Claude CLI 安装失败
A: 使用官方原生安装器，在普通 PowerShell 中执行：
   irm https://claude.ai/install.ps1 | iex
   验证：claude --version
   若找不到命令，请重新打开终端；或在当前 PowerShell 执行：
   $env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
   官方说明：https://code.claude.com/docs/en/setup

Q: 镜像源连接超时
A: 检查网络连接，或在 PowerShell 中手动设置：
   $env:UV_DEFAULT_INDEX="https://pypi.org/simple"

Q: Windows 需要单独配置账号或创建知识库
A: 在项目目录的普通 PowerShell 中运行：
   .\.venv\Scripts\python.exe Step3_set_brain_credentials.py
   .\.venv\Scripts\python.exe Step5_create_knowledge_base.py

【Python 3.12 与 MCP SDK 2 依赖修复】
- 项目固定使用 Python 3.12（3.12.*）。uv 会按 pyproject.toml 创建或更新项目内的 .venv。
- MCP 服务使用官方 Python SDK 2（mcp>=2.3,<3）与 pydantic>=2.14.1,<3。
- 所有依赖统一由 pyproject.toml 管理，uv.lock 保存已验证的版本组合；不要另外单独安装 fastmcp 或手动降低 Pydantic 版本。
- 本次升级需同步更新服务端及安装辅助文件，建议更新整套程序文件并保留原账号/API 配置；只替换 pyproject.toml 无法完成 SDK 2 迁移。
- Step1 会静态适配 cnhkmcp 复制出的服务端，重复安装不会恢复旧的 SDK 1 导入；不会添加 MCP 启动检查。
- dep_installer_safe.py 保留为旧命令入口，现仅调用 uv sync，不再维护第二份依赖清单或使用系统 pip。
- 更新文件后，如需修复已有环境，在普通用户终端同步即可：

  Windows PowerShell（将路径替换为实际项目目录）：
  cd "$env:USERPROFILE\AIWorker"
  uv sync --locked --project .

  Mac/Linux（将路径替换为实际项目目录）：
  cd "$HOME/AIWorker"
  uv sync --locked --project .

  本机若使用 AIWorkerNext 文件夹，请将上面的 AIWorker 替换为 AIWorkerNext。
  不需要给 uv sync 加 sudo 或使用管理员 PowerShell；若项目不可写，重新运行对应的一键安装脚本修复权限。
