taijibaga/heicode
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand integration and onboarding documentation set

Browse Source 
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
This commit is contained in:
gongzhiyong
2026-04-30 14:26:25 +08:00
parent 55181c1958
commit 2a6a709f58
15 changed files with 1263 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+64
View File
@@ -0,0 +1,64 @@
# CLAUDE.md — Heicode 单仓导航（给 Claude Code / 助手）
本文是 **仓库根级** 的快速地图与协作约定。细分栈的规则请看各子目录自带文档（避免重复与漂移）。
## 仓库地图（explore 摘要）
| 路径 | 角色 | 栈 / 备注 |
|------|------|-----------|
| `cc-haha/` | **Heicode** 客户端：CLI（Ink）+ 本地 HTTP/WS 服务 + **Desktop**（Tauri + React） | Bun + TypeScript；产品入口 `bin/heicode` |
| `new-api/` | **Heicode Manager**：网关 + 管理控制台 | Go（Gin/GORM）+ `web/default` 前端（Bun/Rsbuild/React） |
| `website/` | 产品介绍站点 | Next.js；根 `docker-compose.yml` 提供 `heicode-www` :8888 |
| `docs/` | 愿景、**里程碑**（`docs/milestones/`）、**Agnet 集成**（`docs/integration/`） | Markdown |
根 `package.json` 仅少量 workspace 级依赖（如适配器用到的包）；**主要开发依赖在 `cc-haha/package.json`**。
## 权威子文档（改代码前先打开对应一篇）
- **客户端（cc-haha）**：[`cc-haha/AGENTS.md`](./cc-haha/AGENTS.md) — 目录结构、运行命令、测试、提交约定。
- **网关（new-api）**：[`new-api/CLAUDE.md`](./new-api/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)。
## 最小开发闭环
```bash
# 依赖（客户端主体）
cd cc-haha && bun install
# 终端 A：本地 API（桌面端依赖）
bun run src/server/index.ts
# 终端 B：桌面
cd desktop && bun run tauri dev
```
联调本机 Manager（new-api）时常见：
```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**：`new-api/controller/heicode_oauth.go`，路由 `new-api/router/heicode-router.go`（例如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
## 协作约定（根级）
1. **改哪一层跟哪篇文档**：Go 行为以 `new-api/CLAUDE.md` 为准；客户端 TS/React 以 `cc-haha/AGENTS.md` 为准。
2. **小步提交**：沿用历史风格（如 `feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。
3. **集成与「SK」边界**：平台契约见 [`docs/integration/agnet-platform-api-design.md`](./docs/integration/agnet-platform-api-design.md)，里程碑见 `docs/milestones/`。
4. **不要臆测计费**：计费与订阅在平台侧，不在 Heicode 客户端内实现。
## Docker / 站点
- 根目录 [`docker-compose.yml`](./docker-compose.yml)：构建 `website/` 静态站点镜像（端口 **8888**）。
- Manager 本地编排以 `new-api/docker-compose.yml` 及仓库内 override 为准（若存在）。
---
*若本文件与子目录 `AGENTS.md` / `CLAUDE.md` 冲突，以子目录为准并及时更新根文件摘要。*
docs/README.md
+39
View File
@@ -0,0 +1,39 @@
# Heicode 文档入口
本目录是 Heicode 仓库的**文档主索引**。整体内容按受众分两条阅读路径，再共享一组通用骨架。
## 共用骨架（建议都先读）
| 文档 | 用途 |
|------|------|
| [`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md) | 产品愿景与协作范式（方向性，非排期） |
| [`glossary.md`](./glossary.md) | 术语表：Heicode / Manager / 客户端 / 子 agent / SK 等 |
| [`architecture.md`](./architecture.md) | 架构图与关键数据流（mermaid） |
| [`sk-lifecycle.md`](./sk-lifecycle.md) | SK（Skill 资产）单点真相：来源、快照、刷新、写权边界 |
## 路径 A · 内部研发 / 新成员上手
适合刚加入团队、负责 `cc-haha`（客户端）或 `new-api`（Manager）开发的同学。
1. [`onboarding/README.md`](./onboarding/README.md)：阅读顺序
2. [`onboarding/local-dev.md`](./onboarding/local-dev.md)：本地联调步骤与排错
3. [`onboarding/env-variables.md`](./onboarding/env-variables.md)：环境变量手册
4. 回到共用骨架：[`architecture.md`](./architecture.md) → [`glossary.md`](./glossary.md)
5. 计划与现状：[`milestones/README.md`](./milestones/README.md)、[`milestones/STATUS.md`](./milestones/STATUS.md)
## 路径 B · Agnet / 平台集成方
适合实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师。
1. [`glossary.md`](./glossary.md) → [`architecture.md`](./architecture.md)
2. [`integration/README.md`](./integration/README.md)：集成方阅读地图
3. [`sk-lifecycle.md`](./sk-lifecycle.md)：SK 边界（Heicode 端写、Agnet 只读快照）
4. [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md)：详细 API 设计
5. [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：HeiCode 客户端 ↔ Manager 浏览器登录流程
6. 落地节奏：[`milestones/README.md`](./milestones/README.md)（M3–M5）+ [`milestones/STATUS.md`](./milestones/STATUS.md)
## 关于版本与更新
- 本目录下的文档以 **设计意图与契约语义** 为准；实现细节以仓库代码为准。
- 任一文档与代码出现冲突时，请在 PR 里同步更新文档与 [`milestones/STATUS.md`](./milestones/STATUS.md)。
- 受众边界：`docs/` 内不做产品营销文案，营销内容归 `website/`。
docs/architecture.md
+126
View File
@@ -0,0 +1,126 @@
# Heicode 架构与关键数据流
本文用 mermaid 图示统一表达 **Heicode 客户端 / Manager / Agnet** 之间的边界与数据流，作为愿景与集成 API 设计的视觉补充。
> 与文字版的对应关系：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md) 第五节、[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §1.1 / §5 / §6 / §7。
---
## 一、概念分层（鸟瞰）
```mermaid
flowchart TD
entry["人机入口<br/>官网 · 控制台 · CLI · Desktop"]
manager["Heicode Manager<br/>(new-api)"]
client["Heicode 客户端<br/>(cc-haha)"]
agnet["Agnet 平台<br/>(角色模板 · 执行单元)"]
assets["资产与环境<br/>仓库 · 流水线 · 运行时"]
entry --> manager
entry --> client
manager <--> client
manager --> agnet
client -. "会话子 agent 输出" .- agnet
agnet --> assets
manager --> assets
```
要点：
- **同一身份与策略边界** 跨越 Manager 与客户端
- 编排细节归 Agnet 内部；Heicode 关注 **契约、体验与安全边界**
- 资产层（仓库 / 流水线 / 运行时）是被动载体
---
## 二、HeiCode 客户端 ↔ Manager ↔ Agnet 主链路
```mermaid
flowchart LR
user["开发者"]
desktop["Heicode 客户端<br/>(Desktop / CLI + 本地服务)"]
manager["Heicode Manager"]
agnet["Agnet 平台"]
user --> desktop
desktop -->|"OAuth: /heicode/oauth/*"| manager
desktop -->|"Anthropic Messages /<br/>OpenAI Chat 调用"| manager
manager -->|"模型路由 / 计费 / RBAC"| manager
manager -->|"M2M JWT · 部署/查询编队"| agnet
agnet -->|"webhook / events"| manager
agnet -.->|"sub_agent.output (SSE/WS)"| desktop
```
关键边界：
- 客户端 **不直连** 模型供应商，所有调用经 Manager 路由
- Manager 用 **服务账号 / 用户委派令牌** 调 Agnet
- 客户端按 [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §6.4 订阅会话内子 agent 输出流
---
## 三、SK 数据流（Git / Upload → 快照 → 子 agent 注入）
```mermaid
flowchart TB
authoring["SK 编辑入口<br/>仅 Heicode 客户端"]
git["Git 仓库<br/>(SK 事实源)"]
upload["上传制品<br/>(对象存储 / artifact_id)"]
manager["Heicode Manager<br/>展开 sk_sources 与刷新策略"]
agnet["Agnet 平台"]
snapshot["不可变快照<br/>commit_sha · artifact 版本"]
subAgent["Agnet 子 agent<br/>(运行时只读)"]
authoring -->|"git push"| git
authoring -->|"上传 / 替换"| upload
manager -->|"声明 sk_sources"| agnet
git -->|"fetch + checkout ref"| agnet
upload -->|"只读获取"| agnet
agnet --> snapshot
snapshot -->|"注入"| subAgent
```
要点：
- SK **写入路径单一**：经 Heicode 客户端到 Git，或经 Heicode 上传入口
- Agnet 与 Manager **不得提供 SK 正文写 API**
- 运行注入仅使用解析出的 **不可变快照**，避免「执行中偷偷换版本」
详见 [`sk-lifecycle.md`](./sk-lifecycle.md)。
---
## 四、事件流双轨（平台运行态 vs 会话子代理输出）
```mermaid
flowchart LR
agnet["Agnet 平台"]
manager["Heicode Manager<br/>控制台与 Dashboard"]
client["Heicode 客户端<br/>编码会话面板"]
agnet -->|"phase / health / metrics<br/>(SSE · WS · webhook)"| manager
agnet -->|"sub_agent.output<br/>(SSE · WS)"| client
```
两类事件 **同源端点可复用**，但 `event` / `type` 必须可区分：
- 面向 Manager 的：`deployment.*`、`instance.*`、`phase_changed`、`health_changed`
- 面向客户端的：`sub_agent.output`、`sub_agent.tool_result`、`output_delta`
---
## 五、模块关注点对照
| 关注点 | Heicode 客户端 (`cc-haha/`) | Heicode Manager (`new-api/`) | Agnet 平台 |
|--------|------------------------------|-------------------------------|------------|
| 用户身份 | 浏览器登录 / API Key 兼容 | OAuth 提供方、Token 颁发与吊销 | 接收 M2M JWT 与用户委派令牌 |
| 模型调用 | 不直连模型，请求经 Manager | 路由、计费、RBAC | 不参与基础模型调用 |
| 编排 | 触发部署、订阅子 agent 输出 | 一键部署入口、Webhook 注册 | 实际执行编队、维护实例生命周期 |
| SK | 唯一编辑入口（写 Git / 上传） | 展开 `sk_sources`、刷新策略 | 拉取快照、运行时只读注入 |
| 观测 | 会话内子 agent 输出 | 平台运行态聚合 | 提供事件流、指标导出 |
---
## 六、相关代码索引
- 客户端登录：`cc-haha/src/server/api/heicode-auth.ts`
- 客户端 Provider 预设：`cc-haha/src/server/config/providerPresets.ts`
- Manager OAuth：`new-api/controller/heicode_oauth.go`、`new-api/router/heicode-router.go`
> 代码会演进，本文以 **架构关系** 为准；具体路径请以仓库当前实现为最终事实。
docs/glossary.md
+97
View File
@@ -0,0 +1,97 @@
# 术语表
本术语表是 Heicode 仓库内 **跨文档共享的命名标准**。任意文档涉及以下名称时，请相对链接回本文件锚点，避免规则漂移。
> 与代号相关的方向性来源：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md)。
> 与 API 字段相关的来源：[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md)。
## 产品级代号
### Heicode
仓库与产品族的总称。在区分产品形态时，亦称 **Heicode 客户端**。
### Heicode Manager
账户、模型策略、渠道、计费与平台管控的服务端，源码目录 `new-api/`。在文档中亦称 **Manager**。
### Heicode 客户端
面向开发者的 CLI（Ink）+ 桌面应用（Tauri + React）+ 本地 HTTP/WS 服务，源码目录 `cc-haha/`。
### Orchard
**子智能体编排与团队模板** 所在平台的概念名。它是一个抽象代号，用以保持愿景叙事不绑死在某个厂商。落地形态可对应 Agnet。
### Agnet
当前实际接入的编排平台名称。规范上 Heicode 与 Agnet 通过 [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) 中定义的契约通信。
## 编排相关
### 执行单元 (`agent_instance`)
按角色模板在编排侧实例化的智能体实例。生命周期字段详见 API 设计 §6.1。
### 子 agent
本仓库语境下，特指 **Agnet 平台内部** 的子智能体 / 子执行单元，由 Agnet 编排实例化，**不是** Heicode 自研运行时。
### 部署 (`deployment`)
一次「按团队模板把多个执行单元拉起」的整体行为，由 `deployment_id` 唯一标识。
### 团队 / 编队
一组在同一 `deployment` 中协同工作的执行单元。瀑布与敏捷下的最小/最大编队详见愿景附录 A。
## 资产与边界
### SK（Skill 资产）
为子 agent 提供运行时只读上下文的说明类正文，多为 Markdown。详见 [`sk-lifecycle.md`](./sk-lifecycle.md)。
### `sk_sources`
SK 的来源数组。每个元素声明其来源类型：
- `git`：以 commit SHA 为快照锚点
- `upload`：以 `artifact_id` + 版本为快照锚点
### `sk_file_refs`
简化字段（路径数组），可视为 `sk_sources` 的简写；展开规则需在联合 RFC 中声明。
### Provider Preset
Heicode 客户端预先配置的供应商描述（baseUrl、默认模型、API 格式等），目前仅保留 `taijiaicloud` 与 `clawdrouter`，定义于 `cc-haha/src/server/config/providerPresets.json`。
## 标识符
| 名称 | 含义 | 出处 |
|------|------|------|
| `tenant_id` | 顶层租户隔离边界，所有持久化资源必带 | API 设计 §4.1 |
| `org_id` | 租户内组织划分（可选） | API 设计 §4.1 |
| `project_id` | 编排资源挂载点 | API 设计 §4.1 |
| `deployment_id` | 一次部署的全局标识 | API 设计 §5.1 |
| `instance_id` / `agent_instance_id` | 执行单元实例 | API 设计 §5.1 / §6.1 |
| `sub_agent_id` | Agnet 内子 agent 实例 | API 设计 §5.0 / §6.4 |
| `correlation_id` / `X-Heicode-Correlation-Id` | Heicode → Agnet 全链路关联键 | API 设计 §2.3 |
| `request_id` / `X-Request-Id` | 单次请求追踪 | API 设计 §2.3 |
| `state` | OAuth 流程会话标识 | [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md) |
## 状态字段
### `phase`
执行单元的生命周期阶段：`pending` / `running` / `succeeded` / `failed` / `stopped` 等。
### `health`
执行单元健康度：`ok` / `degraded` / `unknown`。
### `schema_version`
事件载荷与某些资源体的版本号。客户端遇到未知字段必须忽略，破坏性变更须升级版本号。
## 认证相关
### M2M JWT
`Authorization: Bearer <m2m_jwt>` 形式的服务间令牌，由 Manager 或 Agnet 签发；至少包含 `sub` / `tenant_id` / `scope` / `exp`。
### 用户委派令牌
终端用户经 Heicode OAuth 后，由 Manager 代发用于访问 Agnet 受限接口的令牌；Claims 含 `user_id` / `org_id` / `roles`。
### loopback redirect_uri
Heicode 客户端浏览器登录时使用的回跳地址，必须使用 `127.0.0.1` / `localhost` / `::1`。详见 [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)。
## 范式与角色（参考）
### 瀑布隐喻 / 敏捷隐喻
两种协作叙事，分别强调「阶段闸门可审计」与「短迭代闭环」。详见愿景正文第六节。
### 编队角色代号
`WF-*` 表示瀑布编队角色（如 `WF-DEV`、`WF-QA`、`WF-REL`），`AG-*` 表示敏捷编队角色（如 `AG-PO`、`AG-DEV`、`AG-QA`）。完整对照见愿景附录 A。
docs/integration/README.md
+55 -12
View File
@@ -1,18 +1,61 @@
# 集成与平台接口
# 集成与平台接口（阅读地图）
| 文档 | 说明 |
|------|------|
| [agnet-platform-api-design.md](./agnet-platform-api-design.md) | **Agnet 平台**对 Heicode 暴露的 API 设计：身份、RBAC、多租户隔离、编排、运行态、事件流、审计。 |
> 受众：实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师；以及 Heicode Manager / 客户端中负责对外契约的同学。
**Agnet 可视化分工（摘要）**
本目录回答三个问题：
- **Heicode Manager**：呈现 Agnet 平台回传的 **运行态与性能类字段**（是否在跑、阶段、健康、资源、聚合指标等）。
- **Heicode 客户端**：在编码与会话中 **实时展示 Agnet 平台子 agent 产出**（流式输出等），与 §6.4 / 事件流中的会话侧增量对应。
团队与个人均可使用两端；划分依据是 **信息类型与载体**，详见集成文档 **§1.1**。
1. Heicode 与 Agnet **谁负责什么**（产品分工与边界）
2. 二者之间走 **什么协议、什么字段**（API 契约）
3. 这些能力 **何时落地**（与里程碑对齐）
**Manager 一键部署与 SK（摘要）**
## 推荐阅读顺序
- **Heicode Manager** 须支持 **一键部署 Agnet 团队**，并在契约中写清 **团队成员**、**各成员所用模型**、**Agnet 子 agent 绑定的 SK 源（只读）**。
- **SK**：以 **Git 为统一事实源**，并允许 **上传 MD** 等作为补充；对 Agnet 的接口与语义要求见集成文档 **§5.0.1**。SK 正文不经 Agnet/Manager 编辑，详见 **§5.0**、**§3.2**。
**里程碑**（何时落地哪些能力）见 [`../milestones/README.md`](../milestones/README.md)。
| 步骤 | 文档 | 你将得到 |
| --- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| 1 | `[../glossary.md](../glossary.md)` | 统一术语：Heicode / Manager / 客户端 / 子 agent / SK / 标识符等 |
| 2 | `[../architecture.md](../architecture.md)` | 整体架构与数据流（mermaid） |
| 3 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §1.1 | Manager 与客户端在 Agnet 可视化中的职责划分 |
| 4 | `[../sk-lifecycle.md](../sk-lifecycle.md)` | SK 来源、快照、写权边界（**单点真相**） |
| 5 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §2–§3 | 身份、调用方式、RBAC |
| 6 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §4 | 多租户与隔离 |
| 7 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §5 | 一键部署、SK 绑定、控制面 API |
| 8 | `[./orchestration-plan-contract.md](./orchestration-plan-contract.md)` | 模型提案对象与平台裁决规则 |
| 9 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §6–§7 | 运行态、聚合视图、事件流（双轨） |
| 10 | `[./heicode-oauth-flow.md](./heicode-oauth-flow.md)` | 客户端浏览器登录到 Manager 的完整流程 |
| 11 | `[./acceptance-matrix.md](./acceptance-matrix.md)` | 集成验收最小测试矩阵 |
| 12 | `[../milestones/README.md](../milestones/README.md)` + `[../milestones/STATUS.md](../milestones/STATUS.md)` | 落地节奏与现状 |
## 边界速览
| 主题 | Heicode Manager | Heicode 客户端 | Agnet 平台 |
| -------------- | --------------- | ----------- | ---------------------- |
| 一键部署 Agnet 团队 | 入口与编排请求 | 不参与 | 接收 `POST /deployments` |
| 模型策略与计费 | 路由 / RBAC / 计费 | 调用 Manager | 不参与 |
| 子 agent 输出展示 | 平台运行态汇总 | 会话内增量展示 | 提供 SSE/WS 流 |
| SK 正文写入 | **不允许** | 唯一编辑入口 | **不允许**（仅只读快照） |
| 凭据（Git/云 SA）写入 | 持久化与轮换 | 发起授权 | 按租户使用 |
## 与里程碑的关系
API 设计中的章节与里程碑的对应：
| API 设计章节 | 主对应里程碑 |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| §2 身份 / §3 RBAC | [M1](../milestones/M1-contract-identity.md)、[M4](../milestones/M4-tenant-rbac-isolation.md) |
| §4 多租户隔离 | [M4](../milestones/M4-tenant-rbac-isolation.md) |
| §5 编排控制面 | [M3](../milestones/M3-agnet-orchestration-bridge.md) |
| §6 / §7 运行态、事件流 | [M5](../milestones/M5-observability-visualization.md) |
| §8 审计 | [M4](../milestones/M4-tenant-rbac-isolation.md) / [M5](../milestones/M5-observability-visualization.md) |
## 集成方常见疑问
- **「Agnet 控制台为什么不能改 SK？」** 见 `[../sk-lifecycle.md](../sk-lifecycle.md)` §二 / §六
- **「子 agent 输出走 §6 还是 §7？」** 两节互补：`§6.4` 强调内容增量，`§7` 强调订阅与重连；事件 `type` 必须可区分
- **「跨租户负例怎么测？」** 见 `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §4.3
- **「破坏性变更怎么走？」** 见 `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §10
docs/integration/acceptance-matrix.md
+52
View File
@@ -0,0 +1,52 @@
# Agnet 集成验收矩阵
本文用于把集成设计从“建议”变成“可执行验收项”。
## 1. 验收范围
- 编排控制面（部署/停止/查询）
- 租户隔离与权限
- SK 快照只读边界
- 事件流（运行态 + 子 agent 输出）
- 回调签名与重试
## 2. 用例矩阵（最小集）
| ID | 类别 | 场景 | 前置条件 | 期望结果 |
|----|------|------|----------|----------|
| A01 | Happy path | `agile_min` 一键部署成功 | 模板可用、成员与模型已授权 | 返回 `deployment_id`，实例进入 `pending→running` |
| A02 | Happy path | `waterfall_min` 一键部署成功 | 同 A01 | 返回 `deployment_id`，角色实例齐全 |
| A03 | 授权 | 成员指定未授权模型 | 组织模型白名单不包含该模型 | 拒绝，`MODEL_NOT_ALLOWED` |
| A04 | 多租户 | Tenant A 访问 Tenant B 部署 | 两租户均有数据 | 返回 `403` 或 `404`（不泄漏存在性） |
| A05 | SK 边界 | 子 agent 绑定越权路径 | `sk_sources` 路径超白名单 | 拒绝，`SK_SOURCE_UNRESOLVABLE` 或 `FORBIDDEN_CROSS_TENANT` |
| A06 | 预算 | 模型提案预算超限 | 策略设定 max budget | 拒绝，`BUDGET_EXCEEDED` |
| A07 | 幂等 | 同 `intent_id` 重复提交 | 首次已 accepted | 第二次返回冲突或幂等复用，`DEPLOYMENT_CONFLICT` |
| A08 | 回调安全 | callback 签名错误 | 模拟篡改签名 | 拒绝处理并记审计 |
| A09 | 事件流 | SSE 断线后续传 | 已产生事件、支持 `Last-Event-ID` | 重连后补齐丢失窗口事件 |
| A10 | 子输出流 | 会话订阅 `sub_agent.output` | 会话内子 agent 正在运行 | 客户端收到 `output_delta` 流式事件 |
## 3. 验收字段（每条事件必须）
- `event_id`
- `schema_version`
- `tenant_id`
- `project_id`
- `deployment_id`
- `correlation_id`
- `occurred_at`
## 4. 验收结论模板
| 项目 | 结果 | 备注 |
|------|------|------|
| 通过数 / 总数 | | |
| 阻断问题 | | |
| 风险接受项 | | |
| 下一轮回归时间 | | |
## 5. 执行建议
- 每次版本上线前至少执行 A01/A02/A04/A05/A08/A09
- 每次策略变更后追加 A03/A06 回归
- 验收输出应关联 `request_id` 与 `correlation_id`，便于排障
docs/integration/agnet-platform-api-design.md
+88 -9
View File
@@ -9,22 +9,26 @@
## 1. 设计目标
| 目标 | 说明 |
|------|------|
| ---------- | ----------------------------------------- |
| **权界清晰** | 调用方身份可解析为「谁、属于哪一租户、具备何种角色」 |
| **租户默认隔离** | 无显式授权则不可读他租户资源 |
| **有状态可观测** | 执行单元生命周期与运行态可通过 API + 事件流呈现 |
| **可演进** | 资源带 `api_version` / schema 版本；破坏性变更走新版本路径 |
### 1.1 Agnet 可视化：Heicode Manager 与 Heicode 客户端的职责划分
**使用方**：团队与个人都会使用 Heicode；下列划分依据的是 **信息类型与界面载体**，不是「只有某类用户才用某一端」。
| 载体 | 主要职责 | 典型内容 |
|------|----------|----------|
| ------------------- | ----------------------------------------------------------------------------------- | --------------------------------- |
| **Heicode Manager** | 呈现 **Agnet 平台回传的运行态与性能类字段**：编队/实例是否在跑、阶段（phase）、健康度、资源占用、队列与心跳、项目级聚合指标与近期错误摘要等。 | 控制台、Dashboard、与平台 SLA/运维相关的观测面。 |
| **Heicode（客户端）** | 在 **编码与工作会话过程中**，**实时或准实时展示 Agnet 平台内子 agent 产出的内容**（流式文本/结构化片段/工具结果等），与编辑、会话上下文同屏。 | 会话内输出面板、流式增量、与当前任务绑定的子 agent 交付物。 |
**边界**：Manager 侧重 **平台契约下的状态与指标**；Heicode 侧重 **工作流中的执行输出**。二者可调用同源底层 API，但 **不得**把「平台大盘」与「子代理会话输出」混为同一套 UI 假设——后者通常带更强会话/项目上下文与更细粒度流式协议。
---
@@ -43,8 +47,9 @@
### 2.3 必需传递的上下文头（建议）
| Header | 必填 | 说明 |
|--------|------|------|
| -------------------------- | ----------- | --------------------------------- |
| `Authorization` | 是 | Bearer Token |
| `X-Request-Id` | 强建议 | 全链路追踪 |
| `X-Tenant-Id` | 多租户时必填 | 顶层隔离键；与 Token 声明互相校验，不一致则 **401** |
@@ -53,20 +58,23 @@
| `X-Environment` | 可选 | `dev` / `staging` / `prod` |
| `X-Heicode-Correlation-Id` | 强建议 | 与 Manager 审计日志关联 |
---
## 3. 权限模型（RBAC 概要）
### 3.1 角色（示例命名，可映射贵司 IAM）
| 角色 | 典型 scope | 说明 |
|------|------------|------|
| ------------------------- | -------------- | ---- |
| `agnet:platform_admin` | 全租户元数据、调试接口 | 极少人数 |
| `agnet:org_admin` | 本租户内项目、编队、凭据绑定 | |
| `agnet:project_editor` | 指定项目下部署/停止/读状态 | |
| `agnet:operator_readonly` | 读状态、读事件、读审计 | |
| `agnet:auditor` | 仅审计与导出 | |
### 3.2 权限分离原则
- **控制面**（部署/改策略）与 **观测面**（读指标）可分角色授予。
@@ -93,12 +101,14 @@ Tenant（租户）
### 4.2 数据面实现选项（择一或组合）
| 方案 | 适用 | Agnet 侧责任 |
|------|------|----------------|
| --------------- | ------- | ------------------------------ |
| **逻辑隔离** | 快速迭代 | 每张业务表 `tenant_id` + RLS 或统一拦截器 |
| **Schema 分库** | 强合规 | 每租户独立 schema / database |
| **命名空间隔离（K8s）** | 执行单元运行时 | 编排器按租户分配 NS 与网络策略 |
### 4.3 负例测试（验收必备）
- 使用 Tenant A 的凭证访问 Tenant B 的 `deployment_id` → **403** 或 **404（对外不区分）**。
@@ -114,8 +124,9 @@ Tenant（租户）
下列条款为 **Heicode 与 Agnet 联合落地时必须写清** 的契约；API 形状可与 **`POST /deployments`** 合一或拆为 **`POST /teams/deployments`** 等聚合端点，但 **语义不得缩水**。
| 契约项 | 要求 |
|--------|------|
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **一键部署** | 在 **Heicode Manager** 控制台提供 **单次操作**（按钮或向导终点）完成：在 Agnet 上 **部署一支 Agnet 团队/编队**，并得到可追踪的 `deployment_id`、团队视图入口与后续观测衔接（见 §1.1、§6）。不得依赖用户在 Agnet 原生控制台重复手工编排才能跑通 Heicode 叙事。 |
| **团队成员** | 部署配置须 **显式包含团队成员**（至少：`user_id`、组织内角色、是否纳入该 Agnet 团队）。成员关系由 Manager/Agnet 持久化，供 **RBAC、配额与审计**；团队管理员经 **Manager 控制面**维护名单（增删改须审计）。 |
| **成员所用模型** | 须能声明 **各成员默认使用的模型/路由**（如 `default_model_id`、`provider_profile_id` 或与 Manager **模型策略**对齐的引用）。支持「团队缺省 + 成员覆盖」；未授权模型 **不得**在执行路径上静默生效。 |
@@ -123,6 +134,7 @@ Tenant（租户）
| **SK 与 Git / 上传 MD** | **SK 正文资产以 Git 仓库为统一事实源**（用户指定的远端/连接与分支、路径规则由集成约定）。同时允许用户 **上传 Markdown 等文件** 作为 **补充 SK 源**（租户内对象存储/制品 ID）。Agnet 执行前将两类来源 **解析为不可变快照**（commit SHA / upload version），再注入子 agent 上下文。 |
| **SK 文件仅在 Heicode 中编辑** | Git 侧 SK 的 **创建、修改、删除** 经 **Heicode 客户端**提交到仓库（或 Heicode 发起变更后再同步）；**上传类 SK** 的 **新增/替换** 仅通过 **Heicode 提供的入口**（Manager 可做登记与透传，**不提供 SK 正文在线编辑器**）。**Agnet 平台与子 agent 对 SK 均只读**；若 Agnet 控制台出现可直接改 SK 正文的 API/UI，视为 **违背产品边界**。 |
**部署请求体扩展（示意，可与 §5.1 合并）**
```json
@@ -180,15 +192,17 @@ Tenant（租户）
下列为 **Agnet 应向 Heicode/Manager 提供或可观测** 的最小要求；路径可为等价 gRPC。
| 类别 | 要求 |
|------|------|
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **部署与编队** | 实现 **`POST /deployments`**（或 **`POST /teams/deployments`**）可接收 **成员、成员模型、子 agent 模板及 `sk_sources`**；返回 **`deployment_id`**、实例/子 agent 标识，供 Callback 与观测关联。 |
| **SK 快照只读** | 对每个 `deployment_id` / `sub_agent_id`，Agnet 须能记录 **已解析的 SK 快照**（Git：`commit_sha` + 路径哈希；Upload：`artifact_id` + 版本）。运行注入 **仅此快照**，不得在执行中「瞒报版本」拉未授权路径。 |
| **Git 拉取** | Agnet 须支持 **按租户注册 Git 凭据/连接**（`connection_id` 或等价），由用户在 **Heicode/Manager 流程**中授权；**Agnet 不提供 Git 写接口用于改 SK**——写操作发生在 Git 远端或经 Heicode 提交后，Agnet 仅 **fetch + checkout 指定 ref**。 |
| **上传制品** | 若支持 `type: "upload"`：Agnet（或与 Manager 分工）须提供 **`artifact_id` 的只读获取**（如 `GET /sk-artifacts/{artifact_id}/content` 或预签名 URL），**无 `PUT` 修改正文**于 Agnet 控制台；上传入口 **仅** Heicode 侧发起、Agnet 存只读副本。 |
| **上传制品** | 若支持 `type: "upload"`：Agnet（或与 Manager 分工）须提供 **`artifact_id`** 的只读获取（如 `GET /sk-artifacts/{artifact_id}/content` 或预签名 URL），**无 `PUT` 修改正文**于 Agnet 控制台；上传入口 **仅** Heicode 侧发起、Agnet 存只读副本。 |
| **刷新策略** | 约定 **何时重新解析 SK**（如新 commit、用户触发刷新、部署新版本）；须可通过 API 或事件暴露 **`sk_snapshot_refreshed`**，便于 Heicode 提示「已用新版本 SK」。 |
| **禁止项** | **不得**提供面向 SK 正文的 **通用写 API**（与 §3.2 一致）；子 agent **只读**绑定列表内的快照。 |
- **`sk_file_refs`**（若保留简化字段）：视为 **相对某默认 Git 根**或 **由 Manager 展开为 `sk_sources`** 前的简写；联合 RFC 须声明展开规则。
- **验收**：部署完成后，Manager 可展示「团队成员—模型—**Agnet 子 agent**—SK 源（Git ref / 上传件）—快照版本」；Git 更新或 Heicode 重新上传后，按刷新策略在后续运行使用新快照。
@@ -348,8 +362,9 @@ Tenant（租户）
## 9. 错误模型
| HTTP | 含义 | 客户端行为 |
|------|------|------------|
| ---- | ------------ | --------- |
| 400 | 参数错误 | 展示校验细节 |
| 401 | 未认证 | 刷新令牌 |
| 403 | 权限不足 | 引导申请角色 |
@@ -358,6 +373,7 @@ Tenant（租户）
| 429 | 限流 | 退避 |
| 503 | 编排背压 | 重试 + 降级文案 |
**响应体**统一 envelope：
```json
@@ -380,4 +396,67 @@ Tenant（租户）
---
## 12. 编排决策权模型（新增约束）
为避免“模型直接执行导致越权/失控”，本项目明确采用：
- **模型提案**：模型基于 SK 产出 `orchestration_plan`
- **平台裁决**：Agnet 对提案执行权限、租户、预算、模型授权校验后决定执行
- **Manager 入口**：Heicode Manager 仅作为调用入口与状态展示，不绕过裁决链路
详见：[`./orchestration-plan-contract.md`](./orchestration-plan-contract.md)。
最低校验项（平台必须执行）：
1. `tenant_id` / `project_id` 与令牌一致
2. 成员与角色具备部署权限
3. `default_model_id` 在组织策略允许范围
4. `sk_sources` 可解析且无越权路径
5. 预算上限（tokens / cost / duration）未超策略阈值
---
## 13. 事件字典（建议最小集）
建议固定以下事件名，避免前后端各自命名造成协议漂移：
| event | 用途 |
|------|------|
| `deployment.accepted` | 部署请求被接受，进入编排队列 |
| `deployment.rejected` | 部署被策略拒绝 |
| `instance.phase_changed` | 执行单元阶段变化 |
| `instance.health_changed` | 执行单元健康状态变化 |
| `sub_agent.output_delta` | 子 agent 流式输出增量 |
| `sk_snapshot_refreshed` | SK 快照刷新完成 |
每个事件最小字段建议：
- `event_id`
- `schema_version`
- `tenant_id`
- `project_id`
- `deployment_id`
- `correlation_id`
- `occurred_at`
---
## 14. 业务错误码字典（补充）
除 HTTP 状态码外，建议统一错误码最小集合：
| code | 说明 |
|------|------|
| `POLICY_REJECTED` | 平台策略拒绝执行提案 |
| `MODEL_NOT_ALLOWED` | 模型未授权 |
| `SK_SOURCE_UNRESOLVABLE` | SK 源不可解析或不可读 |
| `BUDGET_EXCEEDED` | 超预算 |
| `FORBIDDEN_CROSS_TENANT` | 跨租户访问拒绝 |
| `DEPLOYMENT_CONFLICT` | 幂等或状态冲突 |
| `CALLBACK_SIGNATURE_INVALID` | 回调签名校验失败 |
验收用例集合见：[`./acceptance-matrix.md`](./acceptance-matrix.md)。
---
*本文档随里程碑评审更新；实现细节以 Agnet 与 Heicode 联合 RFC 为准。*
docs/integration/heicode-oauth-flow.md
+139
View File
@@ -0,0 +1,139 @@
# HeiCode 浏览器登录流程（客户端 ↔ Manager）
本文给出 Heicode 客户端通过浏览器完成 Manager 登录的端到端流程，并说明字段、错误模型与扩展点。当前实现以 **loopback 直接回 token** 为主，OAuth2 + PKCE 已在客户端预留。
> 代码位置：
>
> - 客户端：`cc-haha/src/server/api/heicode-auth.ts`
> - 服务端：`new-api/controller/heicode_oauth.go`、`new-api/router/heicode-router.go`
## 一、设计目标
- 用户启动 Heicode 客户端 → 看到登录卡片 → 点击「浏览器登录」
- 浏览器跳到 Manager 控制台，完成账号登录
- Manager 颁发 / 复用一条专用 Token，回跳客户端 loopback 地址
- 客户端落地 Token，激活 Provider，自动拉模型列表
整体不要求平台事先支持完整 OAuth2，loopback + token 即可工作；后续可平滑切换到 Authorization Code + PKCE。
## 二、参与方与端点
| 端点 | 谁实现 | 用途 |
| -------------------------------------- | ---------------- | ---------------------------------- |
| `POST /api/heicode-auth/oauth/start` | 客户端本地服务 | 生成 `state` / PKCE，返回 authorize URL |
| `GET /heicode/oauth/authorize` | Manager（new-api） | 校验 loopback、引导登录、回跳 token |
| `GET /heicode/oauth/session` | Manager（new-api） | 给「请先登录」过渡页轮询登录态 |
| `GET /api/heicode-auth/oauth/callback` | 客户端本地服务 | 接收 token / code，落地并激活 |
## 三、当前实现（loopback + token 直回）
```mermaid
sequenceDiagram
autonumber
participant U as 用户
participant C as Heicode 客户端<br/>(本地 HTTP 服务)
participant B as 浏览器
participant M as Heicode Manager<br/>(new-api)
U->>C: 点击「浏览器登录」
C->>C: 生成 state / PKCE 并写入会话
C-->>B: 返回 authorize URL
B->>M: GET /heicode/oauth/authorize?state=...&redirect_uri=...&provider_id=...
alt 用户未登录
M-->>B: 渲染过渡页（链接到 /login）
loop 每 1.5s
B->>M: GET /heicode/oauth/session
M-->>B: { logged_in }
end
B->>M: 重新请求 authorize
end
M->>M: 校验 loopback redirect_uri
M->>M: 取或新建名为 "HeiCode" 的 Token
M-->>B: 302 redirect_uri?state=...&token=sk-XXXX
B->>C: GET /api/heicode-auth/oauth/callback?token=...&state=...
C->>C: 校验 state、激活 Provider、拉模型
C-->>B: 返回成功页（用户可关闭浏览器）
```
### 关键校验
- `state` 与 `redirect_uri` 必填，`redirect_uri` 必须是 loopback 主机：`127.0.0.1` / `localhost` / `::1`
- 客户端会话过期（默认 5 分钟）后回调直接判失败
- 客户端默认从 `?token=` / `?access_token=` / `?apiKey=` / `?apikey=` 任一字段读取 Token
### 字段表
| 名称 | 在 | 说明 |
| ------------------------------------------ | --------- | --------------------------------------------------- |
| `state` | URL query | 客户端生成的不可猜测随机串，回跳时校验 |
| `redirect_uri` | URL query | 必须是 loopback；Manager 会拒绝其它主机 |
| `provider_id` | URL query | `taijiaicloud` / `clawdrouter`；用于客户端识别落到哪个 provider |
| `token` | 回跳 query | Manager 颁发的 HeiCode 专用 Token，前缀 `sk-` |
| `code` / `code_verifier` | 标准 OAuth | 当前 loopback 模式不使用；启用 PKCE 时必需 |
| `code_challenge` / `code_challenge_method` | URL query | 启用 PKCE 时由客户端附带，方法固定 `S256` |
| `client_id` / `scope` | URL query | 启用 PKCE 时附带，分别来自客户端环境变量 |
## 四、扩展形态：标准 OAuth2 + PKCE
当平台具备 token 端点后，仅需在客户端配置环境变量即可启用：
| 变量 | 用途 |
| ---------------------------------------- | ----------------------------------------- |
| `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL` | 自定义 authorize 端点 |
| `HEICODE_<PROVIDER>_OAUTH_TOKEN_URL` | code → access_token 交换端点 |
| `HEICODE_<PROVIDER>_OAUTH_CLIENT_ID` | OAuth Client ID（启用 PKCE 时必需） |
| `HEICODE_<PROVIDER>_OAUTH_SCOPE` | 申请的 scope，例如 `models:read,messages:write` |
详见 `[../onboarding/env-variables.md](../onboarding/env-variables.md)`。
```mermaid
sequenceDiagram
participant C as 客户端
participant B as 浏览器
participant P as 平台 Authorize
participant T as 平台 Token
C->>B: authorize URL?response_type=code&client_id&...&code_challenge
B->>P: 用户登录授权
P-->>B: 302 redirect_uri?code=&state=
B->>C: callback?code=&state=
C->>T: POST /token { grant_type=authorization_code, code, code_verifier, ... }
T-->>C: { access_token }
C->>C: 激活 Provider 并拉模型
```
## 五、错误模型
| 触发 | HTTP / 行为 | 客户端展示 |
| --------------------------- | ----------------------------------------------------- | -------------------------- |
| `state` / `redirect_uri` 缺失 | Manager 400 | 浏览器停留报错 |
| `redirect_uri` 非 loopback | Manager 400 `redirect_uri must be a loopback address` | 检查客户端配置 |
| 用户未登录 | Manager 渲染过渡页并轮询 session | 浏览器停留并自动跳转 |
| 客户端会话过期 | 客户端 callback 返回错误页 | 提示「登录会话已过期，请回到 HeiCode 重试」 |
| 平台未配置 token 端点但只回了 code | 客户端 callback 错误页 | 提示「平台未配置 token 交换端点」 |
| Provider 模型校验失败 | 客户端 400 | 拉模型异常或返回空集 |
## 六、与 Agnet API 设计的衔接
- 这里的 Token 用于 Heicode 客户端调 Manager；Manager 调 Agnet 时使用 `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §2.1 / §2.2 中的 M2M JWT 或用户委派令牌
- 跨链路追踪建议在 Manager 调 Agnet 时附带 `X-Heicode-Correlation-Id` 与本登录会话关联
## 七、安全注意事项
- 客户端必须在每次启动时 **新生成** `state` / `code_verifier`，禁止复用
- Manager 必须 **拒绝** 非 loopback 的 `redirect_uri`（已实现）
- Token 长生命周期使用前提：Manager 端可吊销且具备审计；不要在跨设备粘贴中传播
- 出现安全事件时，Manager 应能批量吊销名为 `HeiCode` 的 Token
docs/integration/orchestration-plan-contract.md
+105
View File
@@ -0,0 +1,105 @@
# 编排提案契约（`orchestration_plan`）
本文定义「模型提案、平台裁决」模式下的最小编排对象，供 Heicode / Manager / Agnet 三方对齐。
## 1. 决策边界
- **模型（经 SK 引导）**：产出编排提案 `orchestration_plan`
- **Agnet 平台**：执行策略裁决（权限、预算、模型授权、租户隔离），并决定是否执行
- **Heicode Manager**：承载入口与状态展示，透传提案并记录 `correlation_id`
## 2. 最小对象
```json
{
"intent_id": "intent_20260430_001",
"template_hint": "agile_min",
"objective": "实现并验证用户登录链路",
"risk_level": "medium",
"budget": {
"max_tokens": 120000,
"max_cost_usd": 8.0,
"max_duration_sec": 3600
},
"agents": [
{
"role_template": "AG-PO",
"goal": "拆解验收标准并输出任务分配",
"default_model_id": "mdl_claude_sonnet",
"sk_sources": [
{
"type": "git",
"repo_ref": {
"connection_id": "gitconn_1",
"repo_url": "https://example.com/org/sk-repo.git",
"ref": "main",
"paths": ["agile/po-guideline.md"]
}
}
]
},
{
"role_template": "AG-DEV",
"goal": "按拆解清单完成实现与自测",
"default_model_id": "mdl_claude_sonnet",
"sk_sources": []
}
],
"constraints": {
"allowed_model_ids": ["mdl_claude_sonnet", "mdl_claude_haiku"],
"forbidden_actions": ["cross_tenant_read", "credential_write"]
},
"metadata": {
"tenant_id": "ten_001",
"project_id": "prj_auth",
"correlation_id": "mgr_cor_abc"
}
}
```
## 3. 字段说明（最小集）
| 字段 | 必填 | 说明 |
|------|------|------|
| `intent_id` | 是 | 业务意图 ID，幂等与审计用 |
| `template_hint` | 是 | 期望模板（如 `agile_min` / `waterfall_min`） |
| `objective` | 是 | 任务目标摘要 |
| `risk_level` | 是 | `low` / `medium` / `high` |
| `budget.*` | 是 | token、成本、时长预算上限 |
| `agents[]` | 是 | 子 agent 提案列表 |
| `agents[].role_template` | 是 | 角色模板 |
| `agents[].goal` | 是 | 该角色目标 |
| `agents[].default_model_id` | 否 | 建议模型；最终由平台策略裁决 |
| `agents[].sk_sources` | 否 | SK 来源列表 |
| `constraints.allowed_model_ids` | 否 | 允许模型白名单 |
| `metadata.tenant_id` | 是 | 顶层隔离键 |
| `metadata.project_id` | 是 | 项目标识 |
| `metadata.correlation_id` | 是 | 全链路追踪键 |
## 4. 裁决规则（平台侧）
Agnet 在执行前必须做下列校验：
1. 租户与项目一致性：`tenant_id` / `project_id` 与令牌声明匹配
2. 权限校验：调用主体具备部署与读取权限
3. 模型授权：`default_model_id` 在组织与项目策略允许范围内
4. SK 边界：`sk_sources` 可解析、可读、无越权路径
5. 预算约束：`max_tokens` / `max_cost_usd` / `max_duration_sec` 不超策略上限
## 5. 典型拒绝码
| code | 含义 |
|------|------|
| `POLICY_REJECTED` | 平台策略拒绝执行 |
| `MODEL_NOT_ALLOWED` | 模型未授权 |
| `SK_SOURCE_UNRESOLVABLE` | SK 源无法解析或无权限读取 |
| `BUDGET_EXCEEDED` | 预算超限 |
| `FORBIDDEN_CROSS_TENANT` | 跨租户访问拒绝 |
| `DEPLOYMENT_CONFLICT` | 幂等冲突或状态冲突 |
## 6. 对接建议
- `orchestration_plan` 建议由 Manager 转换成 Agnet `POST /deployments` 标准 payload
- 拒绝时应返回 `error.code` + `request_id` + `correlation_id`
- 接受后返回 `deployment_id`，并通过事件流持续反馈执行状态
docs/milestones/README.md
+3 -1
View File
@@ -1,7 +1,9 @@
# Heicode 交付里程碑（索引）
> 导航：[`../README.md`](../README.md) · [`../glossary.md`](../glossary.md) · [`../architecture.md`](../architecture.md) · [`./STATUS.md`](./STATUS.md)
本目录将整体交付拆成**可验收、可并行准备**的里程碑事件；每个文件定义**完成定义（DoD）**、**依赖**与**与 Agnet 平台的衔接点**。
全局范式仍以 [`../vision-heicode-full-stack-agentic-dev.md`](../vision-heicode-full-stack-agentic-dev.md) 为准。
全局范式仍以 [`../vision-heicode-full-stack-agentic-dev.md`](../vision-heicode-full-stack-agentic-dev.md) 为准；当前实现状态见 [`./STATUS.md`](./STATUS.md)。
## 推荐阅读顺序
docs/milestones/STATUS.md
+76
View File
@@ -0,0 +1,76 @@
# 里程碑现状对齐
本文以仓库当前代码为依据，对 M1–M5 的 DoD 项做粗粒度盘点，便于例会与评审快速对齐。**不替代** 各里程碑文档的 DoD 原文。
> 状态图例：
> - `done`：代码已落地并经过基本验证
> - `partial`：部分项可用，关键缺口已知
> - `todo`：尚未开始或仅有占位
> - `docs-only`：仅文档定义，待实现承接
>
> 来源依据：`cc-haha/src/server/api/heicode-auth.ts`、`cc-haha/src/server/services/providerService.ts`、`new-api/controller/heicode_oauth.go`、`new-api/router/heicode-router.go`、本仓库 `docs/`。
## M1 · 契约与身份对齐
| DoD | 状态 | 备注 |
|-----|------|------|
| 登录与会话语义文档化 | `done` | 详见 [`../integration/heicode-oauth-flow.md`](../integration/heicode-oauth-flow.md) |
| `/v1/models` 模型发现契约 | `partial` | 客户端 `providerService.fetchProviderModels` 已支持探活与多种返回结构；分页/过滤约定尚未文档化 |
| 用户上下文 `tenant_id` / `org_id` 传播 | `todo` | Heicode 客户端尚未在请求中显式注入；预留位置在请求头层 |
| 版本协商 `User-Agent` / `X-Heicode-Client-Version` | `todo` | 未在客户端统一植入 |
| `X-Tenant-Id` 预留约定 | `docs-only` | 见 API 设计 §2.3 |
## M2 · 本地端到端闭环
| DoD | 状态 | 备注 |
|-----|------|------|
| 本地可启动 Manager 与客户端 | `done` | 步骤见 [`../onboarding/local-dev.md`](../onboarding/local-dev.md) |
| 登录 → 模型 → 至少一类任务调用 | `partial` | API Key 路径完整；浏览器登录可达；端到端任务回归未自动化 |
| 可追溯锚点（Git commit / CI Run） | `todo` | 客户端尚未把会话与 Git/CI 关联 |
| 文档：30 分钟内复现 | `done` | 根 README + `onboarding/` 已覆盖 |
## M3 · Agnet 编排桥接
| DoD | 状态 | 备注 |
|-----|------|------|
| Agnet 控制面最小集（部署/伸缩/停止） | `docs-only` | 设计完整，本仓库不含实现 |
| Heicode Manager「一键部署 Agnet 团队」 | `todo` | 尚未在 `new-api` 中提供 |
| SK 边界（写权仅 Heicode、子 agent 只读） | `partial` | 文档单点真相已就绪（[`../sk-lifecycle.md`](../sk-lifecycle.md)）；客户端 SK 编辑入口待落地 |
| Webhook / 回调（Agnet → Heicode） | `todo` | Manager 未提供回调注册端点 |
| 幂等与 `deployment_id` / `correlation_id` | `docs-only` | 字段约定见 API 设计 §5.1、§2.3 |
| 失败语义（超时 / 部分就绪 / 不可调度） | `docs-only` | 待与 Agnet 联合评审落地 |
| 联调环境对打成功 | `todo` | 需要真实 Agnet 接入 |
## M4 · 租户、RBAC 与隔离
| DoD | 状态 | 备注 |
|-----|------|------|
| 租户模型（`tenant` 顶层） | `partial` | `new-api` 自身有用户/组/Token 体系；Heicode 维度未与 Agnet 集成 |
| RBAC 角色矩阵 | `partial` | `new-api` 控制台已有基础角色；与 Agnet 设计（`agnet:*` 角色）未对齐 |
| 数据面隔离与跨租户负例 | `todo` | 待联合 Agnet 落地后补测 |
| 凭据写入隔离（Git Token / 云 SA） | `docs-only` | 见 API 设计 §3.2 |
| 审计日志（追加式） | `partial` | `new-api` 自带操作日志；统一 `correlation_id` 字段未规范化 |
## M5 · 可观测性与可视化
| DoD | 状态 | 备注 |
|-----|------|------|
| 实例快照 API | `docs-only` | 字段定义见 API 设计 §6.1 |
| 子 Agnet 输出流（SSE/WS） | `todo` | 客户端 UI 尚未实现订阅 |
| 项目级聚合 / Dashboard | `partial` | `new-api` 控制台具备模型/Token 指标基础 |
| 事件流（含 `Last-Event-ID` 重连） | `docs-only` | 见 API 设计 §7 |
| 与 RBAC 联动 | `todo` | 需在 M4 落地后回填 |
| SLI 指标导出 | `todo` | Prometheus / JSON 端点未配置 |
## 风险与建议
1. **SK 边界要尽早写到自动化校验**：避免后续在 Agnet 控制台或 Manager 误开 SK 写 API
2. **`correlation_id` 与 `tenant_id` 在客户端先注入**：即便 Agnet 还没接，也方便后续审计回看
3. **Webhook 与回调签名先做规范**：联调时再补会引入兼容包袱
4. **客户端订阅子 agent 输出的协议** 在 UI 还没动前就该确定多路 `type` 命名
## 维护约定
- 每次 PR 涉及 M1–M5 任一 DoD 变化时，在本文相应行更新状态并简述
- 状态从 `docs-only` 升到 `partial` / `done` 时，标注 PR 链接或代码入口
- 本文不写时间表，避免与里程碑原文重复
docs/onboarding/README.md
+42
View File
@@ -0,0 +1,42 @@
# 新成员上手指引
适合刚加入 Heicode 项目的研发同学：把环境跑起来 → 认识仓库结构 → 知道改哪、看哪。
## 推荐阅读顺序
1. [`local-dev.md`](./local-dev.md)：把 `cc-haha`（客户端）、`new-api`（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)
- 网关约定：[`../../new-api/CLAUDE.md`](../../new-api/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 | `new-api/controller/heicode_oauth.go` | 路由 `new-api/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 行为问题：先看 [`../../new-api/CLAUDE.md`](../../new-api/CLAUDE.md)
- 集成 / Agnet 契约问题：先看 [`../integration/README.md`](../integration/README.md)
docs/onboarding/env-variables.md
+76
View File
@@ -0,0 +1,76 @@
# 环境变量手册（Heicode 客户端）
仅列出 Heicode 客户端（`cc-haha/`）当前 **代码中已支持** 的环境变量。Manager（`new-api/`）的环境变量请以 `new-api/CLAUDE.md` 与 `new-api/.env.example` 为准。
> 来源代码：
> - `cc-haha/src/server/config/providerPresets.ts`
> - `cc-haha/src/server/api/heicode-auth.ts`
> 改动这些变量后 **需要重启** 本地服务才能生效。
## 一、Provider Base URL 覆盖
让客户端把某个 provider 的 `baseUrl` 指向本地或自部署网关，常用于联调本机 Manager。
| 变量 | 作用对象 | 示例 |
|------|----------|------|
| `HEICODE_TAIJIAICLOUD_BASE_URL` | `taijiaicloud` provider | `http://localhost:3000` |
| `HEICODE_CLAWDROUTER_BASE_URL` | `clawdrouter` provider | `http://localhost:4000` |
行为：
- 模块加载时读取，未设置则用 preset 中的默认 baseUrl
- 末尾斜杠会被自动去除
## 二、OAuth 配置
客户端浏览器登录会按如下顺序解析授权地址：
1. 若设置了 `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL`，用其值
2. 否则使用 `<baseUrl>/heicode/oauth/authorize`
`<PROVIDER>` 取值范围与 base URL 相同（`TAIJIAICLOUD` / `CLAWDROUTER`）。
| 变量 | 用途 | 默认 |
|------|------|------|
| `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL` | OAuth 授权入口 | `<baseUrl>/heicode/oauth/authorize` |
| `HEICODE_<PROVIDER>_OAUTH_TOKEN_URL` | OAuth `code → token` 交换端点 | `<baseUrl>/heicode/oauth/token` |
| `HEICODE_<PROVIDER>_OAUTH_CLIENT_ID` | OAuth Client ID（启用 PKCE 时必需） | 未设置 |
| `HEICODE_<PROVIDER>_OAUTH_SCOPE` | OAuth Scope（可选，与 `client_id` 一并使用） | 未设置 |
设置规则：
- **仅设置 AUTHORIZE_URL**：客户端跳转浏览器后，平台必须直接以 `?token=...` 形式回调（适合 Manager 当前的 loopback 实现）
- **同时设置 AUTHORIZE_URL + TOKEN_URL + CLIENT_ID**：启用标准 OAuth2 Authorization Code + PKCE
- **未设置 AUTHORIZE_URL** 时，客户端默认用 `<baseUrl>/heicode/oauth/authorize`，与 Manager 默认路由对齐
详见 [`../integration/heicode-oauth-flow.md`](../integration/heicode-oauth-flow.md)。
## 三、本地服务
| 变量 | 用途 | 默认 |
|------|------|------|
| `SERVER_PORT` | 客户端本地 HTTP/WS 服务端口 | `3456` |
## 四、配置示例
### 仅切 baseUrl 到本地 Manager
```bash
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 \
bun run src/server/index.ts
```
### 启用浏览器登录 + 标准 OAuth
```bash
export HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000
export HEICODE_TAIJIAICLOUD_OAUTH_AUTHORIZE_URL=http://localhost:3000/heicode/oauth/authorize
export HEICODE_TAIJIAICLOUD_OAUTH_TOKEN_URL=http://localhost:3000/heicode/oauth/token
export HEICODE_TAIJIAICLOUD_OAUTH_CLIENT_ID=heicode-desktop
export HEICODE_TAIJIAICLOUD_OAUTH_SCOPE=models:read,messages:write
bun run src/server/index.ts
```
> 注：当前 Manager 的实现仅以 loopback 直接回 `?token=...`，标准 OAuth 等待平台侧补全后再启用。
## 五、变更约束
新增环境变量时请同步更新本文与代码注释，避免漂移。本文不是 `.env.example` 的替代，仅作为 docs 索引。
docs/onboarding/local-dev.md
+107
View File
@@ -0,0 +1,107 @@
# 本地联调指引
把仓库内三块跑起来：`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)。
docs/sk-lifecycle.md
+146
View File
@@ -0,0 +1,146 @@
# SK 生命周期（Skill 资产单点真相）
本文是 Heicode 仓库内 **关于 SK 的唯一权威说明**。其它文档涉及 SK 时请相对链接到本文件，避免规则在多处重复。
> 上游契约出处：[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §3.2 / §5.0 / §5.0.1。
> 名称定义：[`glossary.md#sk（skill-资产）`](./glossary.md)。
---
## 一、什么是 SK
SK（Skill）= 给 Agnet 子 agent 在运行时注入的 **只读说明类正文**，承载团队规范、流程提示、领域约束、提示词模板等可被编排消费的「软知识」。
它不是：
- 模型权重或微调样本
- 业务数据或敏感凭据
- Agnet 控制台可在线编辑的内容
---
## 二、唯一编辑入口
| 来源 | 谁可以写 | 谁不能写 |
|------|----------|----------|
| Git 仓库（事实源） | 经 **Heicode 客户端** 提交，或用户在 Git 远端按授权直接操作 | Manager / Agnet **不得**提供改 SK 正文的 API/UI |
| 上传 MD / 文件（补充源） | 仅经 **Heicode 客户端** 提供的入口 | Manager 仅做登记与透传；Agnet 仅做只读副本 |
**底线**：若 Agnet 控制台出现可直接改 SK 正文的 API 或 UI，视为 **违背产品边界**，需在评审中拒绝。
---
## 三、来源（`sk_sources`）
SK 在部署请求中以 `sk_sources` 数组绑定到指定子 agent。两类来源类型并存：
```json
{
"role_template": "sub_reviewer",
"sk_sources": [
{
"type": "git",
"repo_ref": {
"connection_id": "gitconn_1",
"repo_url": "https://example.com/org/sk-repo.git",
"ref": "main",
"paths": ["policy/review.md"]
}
},
{
"type": "upload",
"artifact_id": "sk_upl_9f3a",
"mime": "text/markdown"
}
]
}
```
兼容字段：
- `sk_file_refs`（路径数组）：可视作 `sk_sources` 的简写，**展开规则需在联合 RFC 中声明**。
---
## 四、解析、快照、注入
```mermaid
flowchart LR
src["sk_sources<br/>(git / upload)"]
fetch["Agnet 解析<br/>fetch + checkout / 拉取制品"]
snapshot["不可变快照<br/>commit_sha · artifact 版本"]
inject["注入子 agent<br/>(运行时只读)"]
src --> fetch --> snapshot --> inject
```
要求：
- 每个 `deployment_id` / `sub_agent_id` 必须能查到对应 **已解析的 SK 快照**
- 运行时 **仅** 使用该快照内容，不得在执行中切换版本
- 快照锚点：
- `git`：`commit_sha` + 文件路径哈希
- `upload`：`artifact_id` + 版本
Agnet 不需要、也不应该提供针对 SK 正文的 `PUT` / `PATCH`：写操作发生在 Git 远端，或经 Heicode 上传入口。
---
## 五、刷新策略
需要约定何时重新解析 SK 并发布新快照：
| 触发 | 期望行为 |
|------|----------|
| Git 出现新 commit | 按策略重新解析；可即时或滚动 |
| 用户在 Heicode 触发刷新 | 即时重新解析，并向 Manager 发出事件 |
| 部署新版本 | 必然重新解析 |
事件示例：`sk_snapshot_refreshed`（可在事件流中下发，Heicode 客户端可提示「已用新版本 SK」）。
---
## 六、写权与读权矩阵
| 行为 | Heicode 客户端 | Heicode Manager | Agnet 平台 / 子 agent |
|------|----------------|-----------------|------------------------|
| 创建 / 修改 / 删除 SK 正文（Git） | 允许（提交到仓库） | **禁止** | **禁止** |
| 创建 / 替换上传类 SK | 允许（专用入口） | 仅登记/透传 | **禁止** |
| 注册 Git 凭据 / 连接 | 发起授权 | 持久化、轮换 | 按租户使用 |
| 读 SK 快照 | 允许（用于展示） | 允许（运营/审计） | 允许（运行时注入） |
| 列出 SK 绑定关系 | 允许 | 允许 | 允许 |
权限模型在 [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §3 中给出 RBAC 角色：
- `agnet:credential:write`：用于绑定 Git Token / 云 SA
- `heicode:sk:write`（示例命名）：仅授予 Heicode 客户端身份
---
## 七、与一键部署的关系
[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §5.0 要求 Heicode Manager 提供「一键部署 Agnet 团队」单次操作，部署请求体须显式包含：
- 团队成员列表与组织内角色
- 各成员所用模型 / `provider_profile_id`
- 子 agent 模板与 `sk_sources`
部署完成后 Manager 应能展示：
`团队成员 → 模型 → Agnet 子 agent → SK 源（Git ref / 上传件）→ 快照版本`
未授权模型 **不得** 在执行路径上静默生效。
---
## 八、违规判定（评审清单）
新增能力时，凡命中下列之一，需在评审中明确拒绝：
- 提供 Agnet 或 Manager 控制台对 SK 正文的在线编辑器
- 在 Agnet 暴露面向 SK 正文的通用写 API
- 子 agent 在运行中拉取绑定列表外的 SK 路径
- 跨租户读取 SK 快照
- 「软隔离」下未带 `tenant_id` 的 SK 查询路径
---
## 九、与 Heicode 客户端实现的关联
当前仓库中 SK 编辑入口由 Heicode 客户端承担。具体逻辑实现以 `cc-haha/` 内代码为准，集成方仅需要遵守本文 SK 边界即可。