安装与本地预览

这一章只说明如何把当前项目跑起来，以及如何预览本书本身。

1. Rust Workspace

仓库根目录是一个 Cargo workspace，包含两个成员：

backend/
macos-helper/

在仓库根执行：

cargo test --workspace

如果需要更严格的静态检查：

cargo clippy --workspace --tests -- -D warnings

2. 启动云端后端

2.1 本地 dry-run 预览模式

这种模式不会真的调用 Kubernetes API，只会把即将提交的资源渲染出来。

export AGENT_STORE_BACKEND_CLUSTER_MODE=dry-run
cargo run -p agent-store-sandbox-backend

2.2 真实 K3s 模式

这种模式会调用 K3s，把每次运行提交成 Job。

export AGENT_STORE_BACKEND_BIND_ADDR=0.0.0.0:8090
export AGENT_STORE_BACKEND_CLUSTER_MODE=apply
export AGENT_STORE_BACKEND_DEFAULT_NAMESPACE=agent-store-runtime-demo
export AGENT_STORE_BACKEND_DEFAULT_SERVICE_ACCOUNT=agent-runner
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

export DEEPSEEK_API_KEY=replace-me
export DEEPSEEK_MODEL=deepseek-chat
export DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

cargo run -p agent-store-sandbox-backend

2.3 远程部署

当前仓库已经提供了部署模板：

backend/deploy/backend.env.example：环境变量模板
backend/deploy/agent-store-backend.service：systemd 单元模板
backend/deploy/install_backend_remote.sh：一键远程安装脚本

3. 启动本地 Helper

agent-store-macos-helper（macOS 本地桥接服务）负责把本地工作目录同步成云端 artifact，并把远端结果回写到本地。

export AGENT_STORE_BACKEND_BASE_URL=http://127.0.0.1:8090
export AGENT_STORE_USER_ID=demo-user
export MACOS_HELPER_BIND_ADDR=127.0.0.1:7480
export MACOS_HELPER_POLL_TIMEOUT_MS=120000

cargo run -p agent-store-macos-helper

浏览器访问：

http://127.0.0.1:7480

4. 打包 Helper

bash macos-helper/scripts/package_macos_helper.sh

输出文件：

macos-helper/dist/Agent Store Helper.app
macos-helper/dist/Agent Store Helper.zip

5. 构建本书

本书采用 mdBook 目录结构。首次安装工具：

cargo install mdbook --locked

构建 HTML：

mdbook build backend/docs

本地预览（本机装了 mdbook 时会启用热重载；否则回退到直接托管已构建好的 backend/docs/book/）：

bash backend/scripts/serve_docs.sh

访问：

http://127.0.0.1:3000

如果要把文档跑在远端机器或沙箱并允许任意位置访问，且远端已经有 backend/docs/book/index.html：

DOCS_SERVE_MODE=static MDBOOK_HOST=0.0.0.0 MDBOOK_PORT=3452 \
bash backend/scripts/serve_docs.sh

浏览器访问：

http://<remote-host>:3452

6. 快速回归命令

后端附带一个 smoke 脚本：

BACKEND_BASE_URL=http://127.0.0.1:8090 \
AGENT_STORE_USER_ID=smoke-user \
bash backend/scripts/smoke_backend_run.sh

如果只想看资源渲染，把环境变量 AGENT_STORE_APPLY_TO_CLUSTER=false 加进去即可。

Keyboard shortcuts

Agent Store Backend Runtime Book