# 新成员上手指引

适合刚加入 Heicode 项目的研发同学：把环境跑起来 → 认识仓库结构 → 知道改哪、看哪。

## 推荐阅读顺序

1. [`local-dev.md`](./local-dev.md)：把 `cc-haha`（客户端）、`heicode`（Manager）、`website`（站点）跑起来；含常见错误与排查
2. [`env-variables.md`](./env-variables.md)：客户端识别的环境变量（base URL、OAuth 配置）
3. 共用骨架：[`../architecture.md`](../architecture.md)、[`../glossary.md`](../glossary.md)、[`../sk-lifecycle.md`](../sk-lifecycle.md)
4. 现状对齐：[`../milestones/STATUS.md`](../milestones/STATUS.md)
5. 子项目细则：
   - 客户端约定：[`../../cc-haha/AGENTS.md`](../../cc-haha/AGENTS.md)
   - 网关约定：[`../../heicode/CLAUDE.md`](../../heicode/CLAUDE.md)

## 改代码前的最小心智模型

| 你要改什么 | 入口文件 | 备注 |
|------------|----------|------|
| 客户端登录 / Provider | `cc-haha/src/server/api/heicode-auth.ts` | 路由前缀 `/api/heicode-auth/*` |
| 客户端模型发现 | `cc-haha/src/server/services/providerService.ts`、`cc-haha/src/server/api/providers.ts` | `/v1/models` 探活 |
| Provider 预设 | `cc-haha/src/server/config/providerPresets.json` + `providerPresets.ts` | 仅保留 `taijiaicloud` / `clawdrouter` |
| Manager OAuth | `heicode/controller/heicode_oauth.go` | 路由 `heicode/router/heicode-router.go` |
| 桌面端 UI | `cc-haha/desktop/src/` | Tauri + React |

## 你不需要做的事

- **不要** 在 Heicode 客户端里实现计费 / 订阅；这部分归 Manager 与平台
- **不要** 给 Agnet 平台或 Manager 增加可写 SK 正文的 API（违反 SK 边界，详见 [`../sk-lifecycle.md`](../sk-lifecycle.md)）
- **不要** 引入「客户端 → 模型供应商直连」的捷径；所有模型调用应经 Manager 路由

## 提交与协作

- 提交风格沿用 Conventional Commits：`feat:` / `fix:` / `docs:` / `chore:` 等
- 分支前缀：`feat/*`、`fix/*`、`docs/*`（不要新建 `codex/*`）
- PR 描述列出影响面、验证步骤；UI 改动附截图
- 文档与代码同 PR 提交：避免事后再补 docs

## 提问与求助

- 客户端 TS/React 行为问题：先看 [`../../cc-haha/AGENTS.md`](../../cc-haha/AGENTS.md)
- 网关 Go 行为问题：先看 [`../../heicode/CLAUDE.md`](../../heicode/CLAUDE.md)
- 集成 / Agnet 契约问题：先看 [`../integration/README.md`](../integration/README.md)