# 本地联调指引

把仓库内三块跑起来：`cc-haha`（客户端）、`heicode`（Manager）、`website`（站点）。下面命令以 macOS / Linux 为主，Windows 仅在差异点提示。

> 命令以仓库当前 README 与 package.json 为准；如出现冲突，以代码为最终事实。
> 客户端工程级别的更细约定在 [`../../cc-haha/AGENTS.md`](../../cc-haha/AGENTS.md)。

## 一、前置依赖

| 依赖 | 用途 | 检查命令 |
|------|------|----------|
| Bun ≥ 1.x | 客户端 / 站点 / Tauri 前端构建 | `bun --version` |
| Node 22 | 仅 docs 工作流（CI 用 npm） | `node --version` |
| Rust toolchain | Tauri 桌面端 | `cargo --version` |
| Docker / Docker Compose | 起 Manager 与站点容器 | `docker compose version` |
| Go 1.22+ | 直接跑 Manager 源码（可选） | `go version` |

> Bun 安装：`curl -fsSL https://bun.sh/install | bash`（Windows 用 PowerShell `irm bun.sh/install.ps1 | iex`）。
> Rust 安装：`curl --proto '=https' https://sh.rustup.rs | sh`（如遇 HTTP/2 报错，去掉 `--http2` 重试）。

## 二、最小开发闭环

```bash
# 1. 安装客户端依赖
cd cc-haha && bun install

# 2. 终端 A：本地 API（桌面端依赖）
bun run src/server/index.ts

# 3. 终端 B：桌面端
cd cc-haha/desktop
bun run tauri dev
```

服务默认监听 `http://127.0.0.1:3456`（可用 `SERVER_PORT` 覆盖）。

## 三、联调本机 Manager（heicode）

```bash
# 1. 起 Manager（heicode）
cd heicode
docker compose -f docker-compose.yml -f docker-compose.override.yml up --build -d

# 2. 让客户端把 TaijiAICloud 指向本地 Manager
cd ../cc-haha
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts
```

完整可用变量见 [`env-variables.md`](./env-variables.md)。

## 四、桌面端常见排错

| 现象 | 原因 / 解决 |
|------|--------------|
| `error: script "tauri" exited with code 1` 提示 `cargo metadata` 找不到 | 缺 Rust toolchain；安装后重开终端 |
| `Could not resolve: "grammy"` / `@larksuiteoapi/node-sdk` | 客户端依赖未装；`cd cc-haha && bun install` |
| `Cannot find module 'lodash-es/sumBy.js'` | 同上，`bun install` 后再启动 |
| 端口 3456 被占 | 用 `SERVER_PORT=3457 bun run src/server/index.ts` |

## 五、跑客户端测试

```bash
cd cc-haha/desktop
bun run test       # Vitest 单测
bun run lint       # tsc --noEmit
```

桌面端构建产物：`bun run build` 或针对平台用 `bun run build:macos-arm64` / `bun run build:windows-x64`。

## 六、Manager（heicode）开发

简版命令以 `heicode/CLAUDE.md` 为准，本节只列联调相关：

```bash
# 用本地 source 构建（覆盖镜像）
cd heicode
docker compose -f docker-compose.yml -f docker-compose.override.yml up --build -d

# 看日志
docker compose logs -f heicode
```

启动后访问 `http://localhost:3000`，注册管理员，再测试客户端登录链路。

## 七、站点（website）

```bash
cd website
pnpm install
pnpm dev
```

或用根目录 `docker-compose.yml` 起静态预览镜像（端口 8888）：

```bash
docker compose up -d --build heicode-www
```

## 八、回归三件套

每次大改前后至少回归：

1. 客户端登录（API Key 粘贴 + 浏览器登录二选一）
2. 拉取模型列表（应来自 Provider API，不是硬编码）
3. 发起一次对话或 Anthropic Messages 请求

后续端到端闭环以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 的 P0-P5 为准。