From 666f42a0a4845b2b675448634e282ba1f84c77c3 Mon Sep 17 00:00:00 2001 From: leesu Date: Wed, 1 Apr 2026 15:29:06 +0800 Subject: [PATCH] update: guide.html -> full beginner-friendly manual --- guide.html | 801 +++++++++++++++++++++++++++++------------------------ 1 file changed, 445 insertions(+), 356 deletions(-) diff --git a/guide.html b/guide.html index c0a60a4..f20d61d 100644 --- a/guide.html +++ b/guide.html @@ -3,7 +3,7 @@ -Bookworm Portable - 使用教程 +Bookworm Portable - 保姆式安装手册 - 
   ____              _
@@ -289,8 +196,8 @@
  | |_) | (_) | (_) |   <  \ V  V / (_) | |  | | | | | |
  |____/ \___/ \___/|_|\_\  \_/\_/ \___/|_|  |_| |_| |_|
-

Bookworm Portable 使用教程

-

纯云端便携部署 — 任意电脑一行命令激活 Bookworm 全套能力

+

Bookworm Portable 保姆式安装手册

+

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

97 Skills 18 Agents @@ -302,230 +209,412 @@
- +
-

工作原理

-

Bookworm 配置存储在私有 Gitea 服务器上，目标机通过 HTTPS 克隆并自动渲染为本地配置，凭证全程加密，不落盘。

- +

整体流程概览

-
Gitea 私有仓
code.letcareme.com
- → -
git clone
HTTPS 加密
- → -
渲染模板
settings.json
- → -
解密凭证
AES-256
- → -
Claude Code
Bookworm 激活
+
安装依赖
Node.js + Git
+ ➔ +
安装 Claude Code
npm 全局安装
+ ➔ +
克隆引导仓库
3 个文件
+ ➔ +
运行安装脚本
输入密码
+ ➔ +
开始使用
Bookworm 激活
+
+

全程约 10-15 分钟（含下载时间），之后每次启动只需 30 秒

+
+ + + + +
+

1安装依赖软件

+

需要安装 3 个软件。如果已装过可跳到下一步。

+ + +
+
A
+
+

安装 Node.js（必须）

+

去官网下载 LTS 版本安装包，双击安装，一路 Next 即可。

+
+
+ +
+

方式一：官网下载（推荐）

+

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

+
+ +
+

方式二：PowerShell 命令安装

+

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

+
+
+ PowerShell (管理员) + # 下载 Node.js 安装包 +Invoke-WebRequest -Uri "https://nodejs.org/dist/v22.15.0/node-v22.15.0-x64.msi" -OutFile "$env:TEMP\node-install.msi" + +# 运行安装（会弹出安装向导，一路 Next） +Start-Process msiexec.exe -ArgumentList "/i $env:TEMP\node-install.msi" -Wait +
+ +
+ ⚠ +
+ 安装完成后必须重开 PowerShell！
+ 关闭当前 PowerShell 窗口，重新打开一个新的，否则 node 和 npm 命令找不到。 +
+
+ +

验证安装成功：

+
+ node -v # 应显示 v22.x.x +npm -v # 应显示 10.x.x +
+ +
+ 如果 npm 报 "执行策略" 错误？ 执行以下命令后重试：
+ Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+ 提示确认时输入 Y 回车。 +
+ + +
+
B
+
+

安装 Git（必须）

+

去官网下载安装，全部默认设置即可。

+
+
+
+

打开 https://git-scm.com/download/win，下载 "64-bit Git for Windows Setup"，双击安装，全部 Next。

+
+

验证：

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

安装 PowerShell 7（推荐）

+

Windows 自带的 PowerShell 5.1 有中文兼容问题，建议升级到 7。

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

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

+
+ + + + +
+

2安装 Claude Code

+ +
+
1
+
+

全局安装

+

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

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

安装过程需要几分钟，等待完成即可。

+ +
+
2
+
+

验证安装

+
+
+
+ claude --version # 应显示版本号 +
+ +
+ 💡 +
+ 不需要登录 Claude 账号！
+ Bookworm 使用中转站 API，安装 Claude Code 后直接进入下一步，不用执行 claude login。 +
- + + +
-

0前置要求

-

目标电脑需要预先安装以下软件：

- - - - - - - -
软件必须安装方式
Claude Code是npm i -g @anthropic-ai/claude-code
Node.js ≥ 18是nodejs.org
Git是git-scm.com
PowerShell 7推荐winget install Microsoft.PowerShell
Python 3.x可选缺失则 3 个 MCP 服务降级
-
- - -
-

1安装 Bookworm（首次）

+

3安装 Bookworm（核心步骤）

-
1
+
1

克隆引导仓库

-

打开 PowerShell，运行：

+

在 PowerShell 中执行以下命令。系统会提示输入用户名和密码。

-
- PowerShell - -git clone https://code.letcareme.com/bookworm/bookworm-boot.git
-cd bookworm-boot - +
+ git clone https://code.letcareme.com/bookworm/bookworm-boot.git +cd bookworm-boot +
+ +
+ 弹出用户名密码？ 输入管理员提供给你的 Gitea 账号密码。
-

系统会提示输入 Gitea 用户名和密码。

-
2
+
2

运行安装脚本

-

执行安装，自动克隆配置 + 解密凭证 + 渲染模板 + 启动 Claude Code：

+

这条命令会自动完成所有配置：克隆 97 个 Skills、渲染配置文件、解密 API 凭证、启动 Claude Code。

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

输入主密码

-

脚本会提示输入主密码来解密 API 凭证。输入后自动完成配置并启动 Claude Code。

+

脚本会提示 "输入主密码解密凭证"，输入管理员提供的主密码，按回车。密码输入时不显示字符，这是正常的。

+
+
+ +
+
4
+
+

等待完成

+

脚本会显示步骤进度 [1/6] 到 [6/6]，全部显示 [OK] 后自动启动 Claude Code。

✓ -
完成！Claude Code 启动后即进入 Bookworm 模式，97 个 Skills、18 个 Agents、28 个 Hooks 全部激活。所有 API 请求通过中转站转发。
+
+ 看到 Bookworm 横幅就说明成功了！
+ Claude Code 启动后会显示 ASCII 艺术字 "Bookworm" 横幅，表示 97 个 Skills 全部激活。
+ 现在可以直接开始使用，所有 API 请求通过中转站转发，不需要自己的 Claude 账号。 +
- + + +
-

2后续使用（已安装过）

-

已安装过的电脑，再次使用时只需：

-
- PowerShell - -cd bookworm-boot
-pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly - -
-

-StartOnly 跳过 git clone，直接解密凭证并启动。

+

4日常使用

-

如需同步最新配置更新：

-
- PowerShell - -cd bookworm-boot
-pwsh -ExecutionPolicy Bypass -File install.ps1 - +
+

场景一：快速启动（已安装过，不更新配置）

+

适合每天打开电脑后快速进入工作状态。

-

不加 -StartOnly 会自动 git pull 拉取最新 Skills/Hooks 更新。

+
+ cd bookworm-boot +pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly +
+

-StartOnly 跳过 git 同步，直接解密凭证并启动，约 10 秒完成。

+ +
+

场景二：同步最新配置后启动

+

管理员更新了 Skills 或 Hooks 后，用这个命令拉取最新版本。

+
+
+ cd bookworm-boot +pwsh -ExecutionPolicy Bypass -File install.ps1 +
+

不加 -StartOnly 会自动 git pull 拉取更新。

+ +
-

3使用完毕 — 清理

-

离开电脑前，清理环境变量和凭证痕迹：

+

5使用完毕 — 清理

-
-

基础清理（保留配置，下次可快速启动）

-
- pwsh -ExecutionPolicy Bypass -File stop.ps1 -
-
- -
-

完整恢复（删除 Bookworm，恢复电脑原始状态）

-
- pwsh -ExecutionPolicy Bypass -File stop.ps1 -Restore -
-
- -
-

深度清理（含 PowerShell 历史 + Git 凭证缓存）

-
- pwsh -ExecutionPolicy Bypass -File stop.ps1 -Restore -Deep -
-
-
- - -
-

!安全须知

- -
- ⚠ -
- 主密码无法找回
- 主密码用于解密 API 凭证，没有重置机制。请牢记或存入密码管理器。 -
-
- -
- 🔒 -
- 凭证不落盘
- API Key 仅存在于当前进程的环境变量中。关闭终端或运行 stop.ps1 后自动消失，不会写入磁盘或注册表。 -
-
+ + + + + + + + + + + + + + + + + +
场景命令说明
基础清理pwsh -File stop.ps1清除环境变量，保留配置下次快速启动
完整恢复pwsh -File stop.ps1 -Restore删除 Bookworm，恢复电脑原始状态
深度清理pwsh -File stop.ps1 -Restore -Deep完整恢复 + 清除历史记录 + 清除 Git 缓存
⚠
- 在他人电脑上使用后务必清理
- 运行 stop.ps1 -Restore -Deep 确保不留痕迹。尤其注意公用电脑。 + 在他人电脑/公用电脑上务必执行深度清理：
+ pwsh -ExecutionPolicy Bypass -File stop.ps1 -Restore -Deep
+
+ + + +
+

!常见问题排查

+ +
+

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

+

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

+

解决：关闭当前 PowerShell，重新打开一个新的窗口再试。

+

如果还不行，手动刷新 PATH：

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

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

+

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

+

解决：

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

提示确认时输入 Y 回车。之后 npm 和 pwsh 脚本都能正常运行。

+ +
+

❌ 提示 "openssl 未找到"

+

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

+

解决：确认 Git 已安装。脚本会自动搜索 C:\Program Files\Git 和 D:\Git 下的 openssl。

+
+ +
+

❌ git clone 失败 / 认证失败

+

解决步骤：

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

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

+

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

+

解决：仔细检查密码是否正确。如确认忘记，联系管理员重新生成 secrets.enc。

+
+ +
+

❌ Claude Code 启动后没有 Bookworm 横幅

+

原因：配置文件未正确同步。

+

解决：不加 -StartOnly 重新运行安装脚本，让它重新 clone：

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

❌ 安装包下载太慢

+

解决：Node.js 官网在国内可能较慢，可以用淘宝镜像：

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

❌ 需要自己的 Claude 账号吗？

+

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

+
+
+ + + + +
+

安装检查清单

+

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

+
    +
  • Node.js 已安装 — node -v 显示版本号
    • +
  • Git 已安装 — git --version 显示版本号
    • +
  • npm 可用 — npm -v 显示版本号（如报错先设 ExecutionPolicy）
    • +
  • Claude Code 已安装 — claude --version 显示版本号
    • +
  • PowerShell 7 已安装 — pwsh --version 显示 7.x（推荐但非必须）
    • +
  • 已获取 Gitea 账号密码 — 管理员提供
    • +
  • 已获取主密码 — 管理员提供（用于解密 API 凭证）
    • +
  • 能访问 code.letcareme.com — 浏览器打开确认
    • +
+
+ + + + +
+

快速参考

- + + + + + + + +
安全特性规格
操作命令
首次安装git clone https://code.letcareme.com/bookworm/bookworm-boot.git && cd bookworm-boot && pwsh -ExecutionPolicy Bypass -File install.ps1
快速启动cd bookworm-boot && pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly
同步更新cd bookworm-boot && pwsh -ExecutionPolicy Bypass -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 证书)
凭证存储进程级环境变量，不写磁盘
登录保护fail2ban (5次失败/小时 → 封禁24h)
完整性校验SHA-256 文件哈希验证
凭证存储仅进程级环境变量，不写磁盘，不写注册表
登录保护fail2ban (5 次失败/小时 → 封禁 24 小时)
-
- - -
-

?常见问题

- -
-

Q: 提示 "openssl 未找到"

-

确认 Git for Windows 已安装。脚本会自动搜索 C:\Program Files\Git 和 D:\Git 下的 openssl。

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

Q: 提示 "执行策略" 错误

-

使用 pwsh -ExecutionPolicy Bypass -File install.ps1 运行，或以管理员身份执行 Set-ExecutionPolicy RemoteSigned。

-
- -
-

Q: 克隆失败 / Gitea 不可达

-

检查网络是否能访问 https://code.letcareme.com。如在内网环境，可能需要配置代理。

-
- -
-

Q: 解密失败

-

确认主密码正确（区分大小写）。如忘记密码，需要管理员重新运行 encrypt-secrets.ps1 生成新的 secrets.enc。

-
- -
-

Q: Claude Code 启动后没有 Bookworm 横幅

-

检查 ~/.claude/CLAUDE.md 是否存在。运行 install.ps1（不加 -StartOnly）重新同步。

-
- -
-

Q: 目标机需要自己的 Claude 订阅吗？

-

不需要。所有 API 请求通过中转站转发，消耗中转站额度，目标机无需任何 Anthropic 账号。

-
-
- - -
-

快速参考卡片

- - - - - - - - -
场景命令
首次安装git clone ... && pwsh -File install.ps1
快速启动pwsh -File install.ps1 -StartOnly
同步更新pwsh -File install.ps1
基础清理pwsh -File stop.ps1
完整恢复pwsh -File stop.ps1 -Restore
深度清理pwsh -File stop.ps1 -Restore -Deep
- Bookworm Portable v1.1 — Powered by Gitea + Claude Code
+ Bookworm Portable v1.1 — 保姆式安装手册
© 2026 Bookworm Smart Assistant
+ +