gongzhiyong
2a6a709f58
Add a complete docs skeleton for onboarding and integration, including orchestration-plan contract, acceptance matrix, OAuth flow, architecture maps, and milestone status tracking to support Agnet-facing delivery work. Made-with: Cursor
108 lines
3.4 KiB
Markdown
108 lines
3.4 KiB
Markdown
# 本地联调指引
|
||
|
||
把仓库内三块跑起来：`cc-haha`（客户端）、`new-api`（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（new-api）
|
||
|
||
```bash
|
||
# 1. 起 Manager（new-api）
|
||
cd new-api
|
||
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（new-api）开发
|
||
|
||
简版命令以 `new-api/CLAUDE.md` 为准，本节只列联调相关：
|
||
|
||
```bash
|
||
# 用本地 source 构建（覆盖镜像）
|
||
cd new-api
|
||
docker compose -f docker-compose.yml -f docker-compose.override.yml up --build -d
|
||
|
||
# 看日志
|
||
docker compose logs -f new-api
|
||
```
|
||
|
||
启动后访问 `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 请求
|
||
|
||
详见 [`../milestones/M2-local-e2e.md`](../milestones/M2-local-e2e.md)。
|