diff --git a/guide-unified.html b/guide-unified.html new file mode 100644 index 0000000..4fd79e2 --- /dev/null +++ b/guide-unified.html @@ -0,0 +1,1318 @@ + + + + + +Bookworm Portable - 保姆式安装手册 (Windows + macOS) + + + + + + + +
+ 
  ____              _
+ | __ )  ___   ___ | | ____      _____  _ __ _ __ ___
+ |  _ \ / _ \ / _ \| |/ /\ \ /\ / / _ \| '__| '_ ` _ \
+ | |_) | (_) | (_) |   <  \ V  V / (_) | |  | | | | | |
+ |____/ \___/ \___/|_|\_\  \_/\_/ \___/|_|  |_| |_| |_|
+ +

Bookworm Portable 保姆式安装手册

+

从零开始，一步步教你在任意电脑上激活 Bookworm

+ +
+ + 检测到你的系统：Windows +
+ + +
+ + +
+ +
+ 92 Skills + 18 Agents + 34 Hooks + AES-256 加密 + NDA 技术保密 +
+
+ + + + +
+ + + + +
+

0最快方式 — 一键安装器 推荐

+ + +
+
+

最快方式：Windows 一键安装器

+

获取 Bookworm-AutoSetup.bat → 双击运行 → 输入密码 → 完成

+

安装器自动检测依赖、下载配置、创建桌面快捷方式、启动 Claude Code

+ ⬇ 下载一键安装器 (.bat) +
+ +

安装流程：

+
+
安装依赖
Node.js + Git
+ ➔ +
安装 Claude Code
npm 全局安装
+ ➔ +
双击运行
AutoSetup.bat
+ ➔ +
输入密码
主密码
+ ➔ +
Bookworm 激活
完成
+
+

首次安装约 10 分钟（含依赖下载），之后每次双击启动约 10-30 秒

+
+ + + + +
+ 👉 +
+ 想了解每一步在做什么？ + 继续向下阅读完整手册，每步都有详细说明。如果一键安装器已经成功，可直接跳到 第 4 节：日常使用。 +
+
+
+ + + + +
+

1安装依赖软件

+ + +
+ ⚠ +
+ 国内必须：代理/VPN 软件
+ Claude Code 启动时会检查 api.anthropic.com，国内无法直连。
+ 请先安装并启动代理软件（Clash / V2Ray / 快柠檬 / Surge / 任意 VPN），安装脚本会自动检测系统代理。
+ 无代理 = Claude Code 无法启动。 +
+
+ +
+ 💡 +
+ 中转站不走代理
+ API 中转站 bww.letcareme.com 部署在国内阿里云，不需要通过代理访问。
+ 安装脚本已自动设置 NO_PROXY=bww.letcareme.com,code.letcareme.com，无需手动配置。
+ 如果代理软件有"绕过规则"设置，建议把 *.letcareme.com 加入直连列表。 +
+
+ +

需要安装以下软件。如果已经装过，可以直接跳到下一节。

+ + +
+ +
+
A
+
+

安装 Node.js Windows（必须）

+

Node.js 是运行 Claude Code 的基础环境，必须安装。

+
+
+ +
+

方式一：官网下载（推荐，操作最简单）

+

打开浏览器访问 https://nodejs.org，点击绿色的 "LTS 推荐" 按钮下载，双击 .msi 文件安装，全部默认 Next，一路点到完成。

+
+ +
+

方式二：PowerShell 命令安装（winget）

+

右键开始菜单 → 选择 "PowerShell (管理员)" 或 "终端 (管理员)"，然后执行：

+
+
+ PowerShell (管理员) + winget install OpenJS.NodeJS.LTS +
+ +
+ ⚠ +
+ 安装完成后必须重开 PowerShell！
+ 关闭当前 PowerShell 窗口，重新打开一个新的，否则 node 和 npm 命令找不到。 +
+
+ +

验证安装成功（新开 PowerShell 后执行）：

+
+ node -v # 应显示 v22.x.x +npm -v # 应显示 10.x.x +
+ + +
+
B
+
+

安装 Git Windows（必须）

+

用于从服务器下载 Bookworm 配置文件，也会附带安装 openssl（解密凭证需要）。

+
+
+
+

打开 https://git-scm.com/download/win，下载 "64-bit Git for Windows Setup"，双击安装，全部 Next，不用修改任何设置。

+
+

验证：

+
+ git --version # 应显示 git version 2.x.x +
+ + +
+
C
+
+

安装 PowerShell 7 Windows（推荐）

+

Windows 自带的 PowerShell 5.1 有中文兼容问题，建议升级到 7，用命令 pwsh 启动。

+
+
+
+ PowerShell (管理员) + winget install Microsoft.PowerShell +
+

如果 winget 不可用，去 GitHub Releases 下载 .msi 安装包。安装后用 pwsh 命令启动新版 PowerShell。

+
+ + + + +
+ + + + +
+

2安装 Claude Code 通用

+ +
+
1
+
+

全局安装 Claude Code

+

在 PowerShell 中执行（不需要管理员权限）：

+ +
+
+
+ npm i -g @anthropic-ai/claude-code +
+

安装过程需要几分钟，等待完成即可。如果报"执行策略"错误，见第 7 节排查。

+ + +
+
2
+
+

验证安装

+
+
+
+ claude --version # 应显示版本号，如 1.x.x +
+ +
+ 💡 +
+ 不需要登录 Claude 账号！
+ Bookworm 使用自己的 API 中转站，安装完 Claude Code 后直接进入下一步。不要执行 claude login 或设置 ANTHROPIC_API_KEY，那是给个人用户用的。 +
+
+
+ + + + +
+

3安装 Bookworm（核心步骤）

+ + +
+
1
+
+

克隆引导仓库 通用

+

在 PowerShell 中执行以下命令：

+ +
+
+
+ git clone https://code.letcareme.com/bookworm/bookworm-boot.git +cd bookworm-boot +
+ +
+ 弹出用户名密码？ 输入管理员提供给你的 Gitea 账号密码。注意：这是 Gitea 的密码，不是下面说的主密码。 +
+ + +
+
+
2
+
+

双击运行安装脚本 Windows

+

双击文件夹里的 更新并启动Bookworm.bat，脚本会自动完成所有配置。

+
+
+ +
+

或者用命令行运行

+

如果双击 .bat 不起作用，在 PowerShell 中手动执行：

+
+
+ PowerShell + pwsh -ExecutionPolicy Bypass -File auto-setup.ps1 +
+

没有 pwsh 可用 powershell 替代。

+
+ + + + + +
+
3
+
+

输入主密码 通用

+

脚本会提示 "输入主密码解密凭证"，输入管理员提供的主密码（不是 Gitea 密码），按回车。

+ +

输错了可以重试，最多 3 次。

+
+
+ +
+ 两个密码不要搞混：
+ Gitea 密码 = 第 1 步克隆仓库时输入的，用于从服务器下载文件
+ 主密码 = 第 3 步解密 API 凭证时输入的，用于启动 Claude Code +
+ + +
+
4
+
+

等待完成 通用

+

脚本会显示步骤进度，自动完成：前置检查 → 代理检测 → 解密凭证 → 同步配置 → 完整性校验 → 启动 Claude Code

+
+
+ +
+ ✓ +
+ 看到绿色 "Bookworm 就绪" 横幅就说明成功了！
+ Claude Code 启动后，脚本会验证配置完整性，全部 [OK] 后进入 Bookworm 模式。
+ 所有 API 请求通过中转站转发，不需要自己的 Claude 账号。 +
+
+ +
+ ⚠ +
+ 看到黄色 "原生模式启动" 横幅？
+ 说明 Bookworm 配置不完整。请重新运行安装脚本（不加 -StartOnly 参数），或联系管理员。 +
+
+
+ + + + +
+

4日常使用

+ + +
+
+

方法一：双击 .bat 文件 Windows（推荐，最简单）

+

bookworm-boot 文件夹里有两个 .bat 文件，双击即可，无需打开 PowerShell：

+
+ + + + + + + + + + + + +
文件名作用适用场景
启动Bookworm.bat快速启动，不更新配置每天日常使用
更新并启动Bookworm.bat先同步最新 Skills 再启动管理员通知有更新时
+ +
+ 💡 +
+ 看到 "有新更新可用"？
+ 说明管理员推送了更新。双击 更新并启动Bookworm.bat 即可同步。 +
+
+ +
+

方法二：命令行（备用）

+

如果 .bat 文件无法运行，在 PowerShell 中手动执行：

+
+
+ PowerShell + # 快速启动 +cd bookworm-boot +pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly + +# 同步更新后启动 +cd bookworm-boot +pwsh -ExecutionPolicy Bypass -File install.ps1 +
+
+ + + + +
+ + + + +
+

5密码说明 通用

+ +
+

本系统有两个密码，不要搞混

+ + + + +
名称用途何时输入
Gitea 密码从服务器下载文件（克隆仓库）首次安装时，git 弹出要求
主密码解密 API 凭证每次启动脚本时提示输入
+
+ +
+ 💡 +
+ 密码输错了？ 最多可以重试 3 次，不用紧张。3 次都错才会退出，重新运行脚本即可。 +
+
+ +
+

本日免密功能

+

首次解密成功后，脚本会询问 "今日内免密启动? (y/n)"

+

选 y 后，当天再次启动无需输入主密码，次日自动过期。

+

+ 凭证缓存在 Windows Credential Manager 中（DPAPI 加密，仅当前用户可读）。 +

+ +
+ +
+ 🔒 +
主密码无法找回 — 请妥善保管。忘记后需联系管理员重新生成加密凭证文件。
+
+
+ + + + +
+

6使用完毕 — 清理 / 卸载

+ + +
+
+

最简单：双击 卸载Bookworm.bat Windows

+

bookworm-boot 文件夹里的 卸载Bookworm.bat，双击即可一键完整卸载：终止进程 + 清除凭证 + 恢复原始配置 + 删除桌面快捷方式。

+
+ +

或者用命令行精细控制：

+ + + + + + + + + + + + + + + + + +
场景命令说明
基础清理pwsh -File stop.ps1清除环境变量，保留配置供下次快速启动
完整恢复pwsh -File stop.ps1 -Restore删除 Bookworm，恢复电脑原始状态
深度清理pwsh -File stop.ps1 -Restore -Deep完整恢复 + 清除历史 + 清除 Git/凭证缓存
+ +
+ ⚠ +
+ 在他人电脑 / 公用电脑上务必卸载：
+ 双击 卸载Bookworm.bat 或执行 pwsh -File stop.ps1 -Restore -Deep，确保不留下任何凭证。 +
+
+
+ + + + +
+ + + + +
+

!常见问题排查

+ + +
+

❌ git clone 失败 / 认证失败 通用

+

解决步骤：

+
    +
  1. 浏览器打开 https://code.letcareme.com 确认网站可访问
    2. +
  2. 确认用户名密码正确（区分大小写）
    3. +
  3. 如果开了 2FA，需要用 Access Token 替代密码
    4. + +
  4. 检查网络是否需要代理才能访问
    5. +
+
+ +
+

❌ 解密凭证失败 / 主密码错误 通用

+

原因：主密码区分大小写，且无法找回。

+

解决：仔细检查密码是否有多余空格或大小写问题。如确认忘记，联系管理员重新生成 secrets.enc。

+
+ +
+

❌ ECONNRESET / "Unable to connect to API" 通用

+

原因：代理软件把国内中转站 bww.letcareme.com 的流量也走了国际线路，导致连接被重置。

+

解决：手动设置 NO_PROXY 后重试，或在代理软件中将 *.letcareme.com 加入直连规则：

+
+
+
+ PowerShell + # 设置中转站直连（不走代理） +$env:NO_PROXY = "bww.letcareme.com,code.letcareme.com" + +# 重新启动 +cd bookworm-boot +pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly +
+
+ +

新版安装脚本已自动设置 NO_PROXY，git pull 更新后此问题不再出现。

+ +
+

❌ "Not logged in" / 直接运行 claude 报错 通用

+

原因：API 凭证是进程级环境变量，只在安装脚本启动的进程中有效。新开终端直接运行 claude 没有凭证。

+

解决：不要直接运行 claude，必须通过以下方式启动：

+
    +
  • 双击桌面 Bookworm 快捷方式
    • +
  • 双击 启动Bookworm.bat
    • +
  • 命令行：pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly
    • +
+ +
+ +
+

❌ 安装包下载太慢 通用

+

解决：设置 npm 淘宝镜像加速下载：

+
+
+ # 设置 npm 淘宝镜像（加速下载） +npm config set registry https://registry.npmmirror.com + +# 然后重新安装 Claude Code +npm i -g @anthropic-ai/claude-code +
+ + +
+

❌ 需要自己的 Claude 账号吗？ 通用

+

不需要。所有 API 请求通过中转站转发，消耗中转站额度。你的电脑不需要任何 Anthropic 账号或订阅。

+
+ +
+

❌ 询问 AI 系统内部信息时被拒绝了？ 通用

+

这是正常行为。Bookworm 的技能库、路由引擎、配置架构属于技术保密范围（NDA），AI 被设定为不披露这些信息。

+

正确做法：直接告诉 AI 你要完成的任务（写代码、分析问题、设计方案等），它会自动调用最合适的专家能力。无需了解内部机制。

+
+ +
+ + +
+
+

❌ 输入 node -v 提示 "无法识别" Windows

+

原因：安装 Node.js 后没有重开 PowerShell 窗口，PATH 没有刷新。

+

解决：关闭当前 PowerShell，重新打开一个新的窗口再试。如果还不行，手动刷新：

+
+
+ PowerShell + $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User") +node -v +
+ +
+

❌ npm 报 "执行策略" / "Execution Policy" 错误 Windows

+

原因：Windows 默认禁止运行脚本。

+

解决：执行以下命令，提示确认时输入 Y 回车：

+
+
+ PowerShell + Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned +
+

之后 npm 和 pwsh 脚本都能正常运行。

+ +
+

❌ 提示 "openssl 未找到" Windows

+

原因：解密凭证需要 openssl，它随 Git for Windows 一起安装。

+

解决：确认 Git 已正确安装。脚本会自动搜索 C:\Program Files\Git 下的 openssl.exe。如果 Git 装在其他盘，可能需要手动将 Git 的 bin 目录加入 PATH。

+
+ +
+

❌ Claude Code 启动后没有 Bookworm 横幅 Windows

+

原因：配置文件未正确同步到 ~/.claude。

+

解决：不加 -StartOnly 重新运行安装脚本，让它重新同步配置：

+
+
+ PowerShell + pwsh -ExecutionPolicy Bypass -File install.ps1 +
+
+ + + + +
+ + + + +
+

安装检查清单

+

逐项确认，全部打勾即可开始使用：

+ + +
+
    +
  • Node.js 已安装 — node -v 显示版本号 (v22.x.x)
    • +
  • Git 已安装 — git --version 显示版本号
    • +
  • npm 可用 — npm -v 显示版本号（如报错先设 ExecutionPolicy）
    • +
  • Claude Code 已安装 — claude --version 显示版本号
    • +
  • PowerShell 7 已安装 — pwsh --version 显示 7.x（推荐但非必须）
    • +
  • 已获取 Gitea 账号密码 — 管理员提供
    • +
  • 已获取主密码 — 管理员提供（用于解密 API 凭证）
    • +
  • 能访问 code.letcareme.com — 浏览器打开确认可正常访问
    • +
  • 代理/VPN 已启动 — 国内必须，脚本自动检测 (Clash / V2Ray / 快柠檬等)
    • +
+
+ + + +
+ + + + +
+

快速参考

+ + +
+ + + + + + + + +
操作最简方式命令行方式
首次安装git clone + 双击
更新并启动Bookworm.bat		pwsh -ExecutionPolicy Bypass -File install.ps1
快速启动双击 启动Bookworm.batpwsh -File install.ps1 -StartOnly
同步更新双击 更新并启动Bookworm.batpwsh -File install.ps1
基础清理pwsh -ExecutionPolicy Bypass -File stop.ps1
完整恢复pwsh -ExecutionPolicy Bypass -File stop.ps1 -Restore
深度清理pwsh -ExecutionPolicy Bypass -File stop.ps1 -Restore -Deep
+
+ + + +
+ + + + +
+

安全须知 通用

+ + + + + + + + + + + + + + +
特性规格
凭证加密AES-256-CBC + PBKDF2 (600,000 迭代)
传输加密HTTPS (TLS 1.2+, Let's Encrypt 证书)
凭证存储进程级环境变量 + 可选本日缓存 (Windows Credential Manager, DPAPI 加密, 当日 23:59 过期)
登录保护fail2ban (5 次失败/小时 → 封禁 24 小时)
技术保密NDA — 系统内部架构、路由规则、技能库不对外披露
+
+ 🔒 +
+ 主密码无法找回 — 请妥善保管，不要写在便利贴上。忘记后需管理员重新生成加密凭证。 +
+
+
+ +
+ + + + +
+ Bookworm Portable v1.5-NDA — 保姆式安装手册 (Windows + macOS 统一版)
+ © 2026 Bookworm Smart Assistant — 技术保密 · 禁止转发 +
+ + + + + + + +