docs: 同步文档到当前实际（HM-only 仓 + 模板 Agent 模型）
- 根 README/CLAUDE/AGENTS：本仓已从 monorepo 拆分，只剩 Heicode Manager（heicode/ Go 网关 + docs/）。重写仓库地图为 HM-only；客户端指向 heicode-{mac,win}os-release-dev 独立仓；移除指向已删文档的死链（vision/milestones/agent-platform-api-design/cc-haha-AGENTS）；开发闭环改为 heicode/。
- 删除 docs/integration/agent-platform-request-contract.md（已被 AM 契约取代）；docs/README 索引去掉该条。
- product-package 03/12：执行闭环去掉「Heicode 生成/判断子环节」旧编排说法，改为客户端直连 agent、agent 自驱、模型走 HM /v1。
影响面：仅文档。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -1,83 +1,53 @@
|
||||
# CLAUDE.md — Heicode 单仓导航（给 Claude Code / 助手）
|
||||
# CLAUDE.md — Heicode Manager 单仓导航（给 Claude Code / 助手）
|
||||
|
||||
本文是 **仓库根级** 的快速地图与协作约定。细分栈的规则请看各子目录自带文档（避免重复与漂移）。
|
||||
本文是 **仓库根级** 的快速地图与协作约定。细分栈规则看子目录自带文档（避免重复与漂移）。
|
||||
|
||||
## 仓库地图（explore 摘要）
|
||||
> **本仓 = Heicode Manager（HM）端。** 历史上客户端（`cc-haha`）、官网（`website`）与 Manager 曾在同一 monorepo；现已拆分，**本仓只保留 Heicode Manager**。客户端（终端 + 桌面）在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。
|
||||
|
||||
## 仓库地图
|
||||
|
||||
| 路径 | 角色 | 栈 / 备注 |
|
||||
|------|------|-----------|
|
||||
| `cc-haha/` | **Heicode** 客户端：CLI（Ink）+ 本地 HTTP/WS 服务 + **Desktop**（Tauri + React） | Bun + TypeScript；产品入口 `bin/heicode` |
|
||||
| `heicode/` | **Heicode Manager**：网关 + 管理控制台 | Go（Gin/GORM）+ `web/default` 前端（Bun/Rsbuild/React） |
|
||||
| `website/` | 产品介绍站点 | Next.js；根 `docker-compose.yml` 提供 `heicode-www` :8888 |
|
||||
| `docs/` | 愿景、**里程碑**（`docs/milestones/`）、**Agent 集成**（`docs/integration/`） | Markdown |
|
||||
|
||||
根 `package.json` 仅少量 workspace 级依赖（如适配器用到的包）；**主要开发依赖在 `cc-haha/package.json`**。
|
||||
| `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台 | Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React） |
|
||||
| `docs/` | 产品共识 / 实施计划 / 集成契约 | Markdown，索引见 [`docs/README.md`](./docs/README.md) |
|
||||
|
||||
## 权威子文档（改代码前先打开对应一篇）
|
||||
|
||||
- **客户端（cc-haha）**：[`cc-haha/AGENTS.md`](./cc-haha/AGENTS.md) — 目录结构、运行命令、测试、提交约定。
|
||||
- **网关（heicode）**：[`heicode/CLAUDE.md`](./heicode/CLAUDE.md) — Go 分层、JSON/i18n/DB 规则等。
|
||||
- **产品愿景与交付节奏**：[`docs/vision-heicode-full-stack-agentic-dev.md`](./docs/vision-heicode-full-stack-agentic-dev.md)、[`docs/milestones/README.md`](./docs/milestones/README.md)。
|
||||
- **网关后端（`heicode/`，Go）**：[`heicode/CLAUDE.md`](./heicode/CLAUDE.md) — Go 分层、JSON / i18n / DB 规则、计费表达式等。
|
||||
- **产品共识与实施计划**：[`docs/heicode.md`](./docs/heicode.md)、[`docs/plan.md`](./docs/plan.md)。
|
||||
- **集成契约**：[`docs/integration/`](./docs/integration/) —— 当前模型「模板 Agent」见 `heicode-hm-template-agent-model.md`；HM↔AM 见 `heicode-am-contract.md`；桌面客户端对接见 `heicode-desktop-client-api.md`。
|
||||
- **客户端**：在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。
|
||||
|
||||
## 最小开发闭环
|
||||
|
||||
```bash
|
||||
# 依赖（客户端主体）
|
||||
cd cc-haha && bun install
|
||||
Heicode Manager = `heicode/`（Go 后端 + `web/default` 前端）。构建 / 运行命令与分层规则以 [`heicode/CLAUDE.md`](./heicode/CLAUDE.md) 与 `heicode/README.md` 为准。
|
||||
|
||||
# 终端 A：本地 API（桌面端依赖）
|
||||
bun run src/server/index.ts
|
||||
## 关键触摸点（代码索引）
|
||||
|
||||
# 终端 B：桌面
|
||||
cd desktop && bun run tauri dev
|
||||
```
|
||||
|
||||
联调本机 Manager（heicode）时常见：
|
||||
|
||||
```bash
|
||||
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts
|
||||
```
|
||||
|
||||
更多变量见 `cc-haha/src/server/config/providerPresets.ts` 与 `cc-haha/src/server/api/heicode-auth.ts`（如 `HEICODE_<PROVIDER>_OAUTH_*`）。
|
||||
|
||||
## Heicode ↔ Manager 关键触摸点（代码索引）
|
||||
|
||||
- **客户端登录 / Provider**：`cc-haha/src/server/api/heicode-auth.ts`，路由前缀 `/api/heicode-auth/*`（由 `cc-haha/src/server/router.ts` 挂载）。
|
||||
- **模型发现**：`cc-haha/src/server/services/providerService.ts`、`cc-haha/src/server/api/providers.ts`。
|
||||
- **Provider 预设**：`cc-haha/src/server/config/providerPresets.json` + `providerPresets.ts`。
|
||||
- **Manager 侧 Heicode OAuth**：`heicode/controller/heicode_oauth.go`，路由 `heicode/router/heicode-router.go`（例如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
|
||||
- **客户端登录**：客户端走 HM 的 `/api/heicode-auth/*`（转发到登录服务）+ V2 设备签名；详见 `docs/integration/heicode-desktop-client-api.md`。
|
||||
- **Manager 侧 Heicode OAuth**：`heicode/controller/heicode_oauth.go`，路由 `heicode/router/heicode-router.go`（如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
|
||||
- **HM↔AM（agent 部署）**：`heicode/controller/agent_template_runtime.go`、`agent_template_handlers.go`；契约见 `docs/integration/heicode-am-contract.md`。
|
||||
|
||||
## 协作约定（根级）
|
||||
|
||||
1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/CLAUDE.md` 为准；客户端 TS/React 以 `cc-haha/AGENTS.md` 为准。
|
||||
2. **小步提交**：沿用历史风格（如 `feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。
|
||||
3. **集成与「SK」边界**：平台契约见 [`docs/integration/agent-platform-api-design.md`](./docs/integration/agent-platform-api-design.md)，里程碑见 `docs/milestones/`。
|
||||
4. **不要臆测计费**：计费与订阅在平台侧，不在 Heicode 客户端内实现。
|
||||
1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/CLAUDE.md` 为准；产品 / 架构以 `docs/heicode.md` + `docs/plan.md` 为准。
|
||||
2. **小步提交**：沿用历史风格（`feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。
|
||||
3. **不要臆测计费**：计费在平台侧（new-api 计量），按 `docs/` 契约对接，不在本仓臆造扣费逻辑。
|
||||
|
||||
## Docker / 站点
|
||||
## 当前线上入口
|
||||
|
||||
- 根目录 [`docker-compose.yml`](./docker-compose.yml)：构建 `website/` 静态站点镜像（端口 **8888**）。
|
||||
- Manager 本地编排以 `heicode/docker-compose.yml` 及仓库内 override 为准（若存在）。
|
||||
- **VM / 生产同步代码**：优先在目标机上 **`git clone` / `git pull`** 与本仓库远程一致；**不要**用 `scp` 传整份源码或 compose（仅在仓库不可用或紧急热修时例外）。
|
||||
- **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 **`sudo docker image prune -f`**，清掉重建产生的悬空层；定期可 **`sudo docker system prune -f`**（不删仍在使用的卷）。避免只叠新镜像、旧层占满磁盘。
|
||||
|
||||
## 当前线上入口（2026-04）
|
||||
|
||||
- **Heicode 官网（Azure Static Web Apps）**：`https://ashy-dune-0e22d7b00.7.azurestaticapps.net`
|
||||
- **Heicode Manager（生产）**：`https://code.xinghanlab.com/`
|
||||
|
||||
官网中的主按钮（登录/开始使用/CTA）默认应跳转到 `https://code.xinghanlab.com/`，避免出现历史 IP 地址。
|
||||
|
||||
## Manager 生产拓扑（Azure）
|
||||
|
||||
- 应用层：Azure VM 上运行 `heicode`（当前用 Docker 容器承载应用进程）。
|
||||
- 数据库与缓存：使用 Azure 托管服务（不在 VM 上跑 PostgreSQL/Redis 容器）
|
||||
- PostgreSQL: `heicode.postgres.database.azure.com` / DB `heicode`
|
||||
- Redis: `heicode.redis.cache.windows.net:6380`（TLS）
|
||||
- 容器落盘：VM 仅承载应用进程；**容器内产生的文件**（如 `/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘，便于备份与重建容器后不丢。编排见 `heicode/docker-compose.azure-vm.yml`，目录由环境变量 `HEICODE_DATA_ROOT` 指定。
|
||||
- 说明：不要在生产 VM 上再启本地 `postgres`/`redis` 容器并指向业务库，避免与托管实例混淆。
|
||||
- 镜像清理：发版构建后删除悬空/旧镜像层（见上文「VM 部署后清镜像」），防止 OS 盘被 Docker 占满。
|
||||
- 应用层：Azure VM 上运行 `heicode`（Docker 容器承载应用进程）。
|
||||
- 数据库与缓存：Azure 托管服务（不在 VM 上跑 PostgreSQL / Redis 容器）
|
||||
- PostgreSQL：`heicode.postgres.database.azure.com` / DB `heicode`
|
||||
- Redis：`heicode.redis.cache.windows.net:6380`（TLS）
|
||||
- 容器落盘：容器内产生的文件（`/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘。编排见 `heicode/docker-compose.azure-vm.yml`，目录由 `HEICODE_DATA_ROOT` 指定。
|
||||
- **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 `sudo docker image prune -f`；定期 `sudo docker system prune -f`（不删在用卷），避免旧层占满磁盘。
|
||||
- **VM / 生产同步代码**：优先在目标机 `git clone` / `git pull` 与远程一致；不要用 `scp` 传整份源码（紧急热修例外）。
|
||||
|
||||
---
|
||||
|
||||
*若本文件与子目录 `AGENTS.md` / `CLAUDE.md` 冲突，以子目录为准并及时更新根文件摘要。*
|
||||
*若本文件与 `heicode/CLAUDE.md` 或 `docs/` 冲突，以子目录 / `docs` 为准并及时更新本文件。*
|
||||
|
||||
Reference in New Issue
Block a user