# Heicode 全栈智能体开发范式（愿景与产品说明）

本文档把当前对 **Heicode** 工作区的技术理解，与产品侧「全自动化编程、多子智能体团队、与现有平台对接」的构想，整理成**可讨论、可迭代**的范式说明。随实现推进，应持续更新本文件中的状态与待决问题。

---

## 一、三问（直接回答）

### 1. 能否大致说清楚这个项目是干嘛的？

**可以。**

- **工作区层面**：`heicode` 是一个多项目容器，目前可见的核心是  
  - **`cc-haha`**：面向终端与桌面的智能体编程体验（CLI、API 路由、MCP/任务/团队等子系统，并含 `desktop` 的 Tauri 相关结构），目标方向与 **Claude Code 类** 工具体验一致。  
  - **`new-api`**：基于社区 **New API** 生态的 **大模型网关与运营侧能力**（渠道、计费、鉴权、多协议中继等），经你方 **深度改造** 后，作为 **用户/团队登录后看到的「后台」与 API 能力层**。

- **产品叙事层面（你的目标）**：Heicode 不是「单一编码插件」，而是 **结合 Agnet 平台子智能体团队 + 改造后的 New API + 类 oh-my-claudecode 的编程流程**，在 **软件全生命周期** 内支撑 **从需求到代码、到测试、到多云部署、到运维与迭代** 的 **自动化开发范式**；与仅「在 IDE 里写代码」相比，更强调 **多成员（多子 Agnet）协作、可重复的标准化团队模式、以及可审计的交付物**（产品文档、开发日志、多智能体沟通记录等）。

---

### 2. 能否做到和 Claude Code 目前一个效果？

**「方向一致、体验对等」是可实现的产品目标；「逐像素、逐协议完全一致」需要刻意对齐与持续跟进。**

| 维度 | 说明 |
|------|------|
| **CLI / Desktop 登录与会话** | 技术上可对齐同一套账号体系（OAuth/令牌）、同一后端（改造后的 New API），使你描述的「下载 CLI/Desktop → 登录 → 对话界面」闭环成立；是否与 Claude Code **完全一致**取决于是否采用相同的认证提供方、相同的会话模型以及相同的客户端发布节奏。 |
| **插件 / MCP / 工具生态** | `cc-haha` 已有 MCP、路由与工具链相关代码路径；要达到「一模一样」，除功能对等外，还需 **兼容性测试矩阵**（版本、权限模型、错误语义）。 |
| **结论** | 作为 **自托管 / 深度集成 Agnet + New API** 的产品，更合理的承诺是：**在贵司账号与策略域内，提供与 Claude Code 同等量级的「可开发、可协作、可部署」能力**；对 **商业 Claude Code 本身** 的 1:1 复刻，受外部产品变更与条款约束，应作为**长期对标**而非一次性验收项。 |

---

### 3. 目前这个项目处于什么状态？

**综合判断：偏「能力已铺底、产品叙事与平台级整合仍处早中期」的状态。**

| 信号 | 观察 |
|------|------|
| **工程** | `new-api` 与 `cc-haha` 均具备可读的领域代码与测试痕迹；但工作区**根级**未形成单一 `README` 与统一发布说明，**多仓/多副本**（如 `_all-in-one-upload`）暗示仍在整合或迁移中。 |
| **产品** | 你描述的 **Heicode 官网 → New API 后台 → CLI/Desktop 下载 → Agnet 一键部署子智能体** 的完整闭环，在文档与入口上**尚未在仓库内完全固化**（正是本文档要补的）。 |
| **平台依赖** | **Agnet 生产已部署**；**权限、多租户数据隔离、有状态子智能体可观测性** 仍属平台侧待完善项，会直接影响 Heicode 的**企业级**叙事落地节奏。 |

---

## 二、愿景一句话

**Heicode = 面向团队的、贯穿软件生命周期的「智能体软件交付」平台**：  
以 **改造后的 New API** 为统一账户与模型/计费/策略网关，以 **Agnet 平台上的子智能体团队** 为执行单元，以 **类 Claude Code 的 CLI/Desktop** 为人机界面，把「想法 → 规格 → 实现 → 验证 → 发布 → 运维 → 迭代」压缩成**可重复、可审计、可按团队规模裁剪**的标准范式。

---

## 三、架构鸟瞰（逻辑分层）

```
┌─────────────────────────────────────────────────────────────────┐
│  用户 / 团队                                                      │
│  浏览器（官网、New API 控制台）│ CLI │ Desktop（Tauri）              │
└───────────────┬─────────────────────────────┬───────────────────────┘
                │                             │
                ▼                             ▼
┌───────────────────────────┐   ┌───────────────────────────────────┐
│  改造后的 New API           │   │  cc-haha（CLI / Desktop / 本地服务） │
│  账号 · 令牌 · 模型网关      │◄──► 对话 · 工具 · MCP · 任务 · 团队视图   │
│  计费 · 渠道 · 策略（可选）   │   │  与 New API 对齐登录态与 API          │
└───────────────┬───────────┘   └───────────────────┬───────────────┘
                │                                     │
                │         ┌───────────────────────────┘
                │         │
                ▼         ▼
┌─────────────────────────────────────────────────────────────────┐
│  Agnet 平台（已部署生产；权限/隔离/可观测性仍在演进）                 │
│  一键部署「子 Agnet 团队」· 瀑布 / 敏捷 模板 · 有状态子 Agnet        │
└─────────────────────────────────────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────────────────────┐
│  外部系统（默认假设「已具备集成能力」）                              │
│  Git · GCP · AWS · Azure · CI/CD · 监控 · 工单/文档库             │
└─────────────────────────────────────────────────────────────────┘
```

**边界声明**：下文 **不展开 Agnet 内部如何实现**，默认平台已提供「创建子智能体、编排、与外部工具集成」等能力；Heicode 侧聚焦 **集成契约、用户体验与安全边界**。

---

## 四、核心用户旅程（目标体验）

1. 访问 **Heicode 官网**，了解产品与下载入口。  
2. **登录** 进入 **改造后的 New API** 控制台：查看配额、令牌、模型/渠道策略（**现阶段可不新增功能，仅作为已有能力的聚合展示**）。  
3. **下载** 官方构建的 **CLI** 与 **Desktop**，安装后以 **与 Claude Code 对齐的登录方式** 进入 **对话界面**，并能看到 **与子 Agnet / 任务相关的状态**（具体 UI 依赖 Agnet 与本地 Agent 状态上报）。  
4. 在 **Agnet 平台** 对某一项目 **一键部署子 Agnet 团队**（瀑布或敏捷模板），与本地/云端仓库、流水线权限绑定。  
5. 团队在 **全生命周期** 内完成开发、测试、部署、运维与迭代；产物包括 **代码、产品文档、沟通记录、开发日志**。

---

## 五、子 Agnet 团队：瀑布 vs 敏捷（规模与角色）

本节给出 **Heicode 范式下的「最小 / 最大」子 Agnet 数量判断**，并为 **每一个子 Agnet 写明角色名称与职责边界**，供 Agnet 平台「一键部署团队」时直接映射为实例规格（名称可按平台惯例缩写）。

### 5.1 判定依据（为什么是这个区间）

| 维度 | 瀑布模式 | 敏捷模式 |
|------|----------|----------|
| **流程特征** | 阶段闸门强、文档与评审链长，角色边界清晰 | 迭代短、反馈密，强调跨职能小闭环 |
| **最小团队含义** | 仍能走完「规格→设计→实现→验证→上线」且 **不合并关键闸门**（否则失去瀑布的可审计性） | 仍能在一个迭代内完成「可演示增量」且具备 **独立质量门禁** |
| **最大团队含义** | 覆盖大型传统组织常见 **专岗**（安全、文档、前后端分立），且不超过单项目协调上限（约 **9** 个并行协调节点） | 覆盖规模化 Scrum 小组（双轨开发 + 嵌入式 SRE/UX），且不超过 **两个披萨团队** 上限（约 **8** 人 equivalent） |
| **超出上限时** | 应拆 **子系统 / 子项目** 或多套瀑布实例，而不是继续堆角色 | 应拆 **多个 Squad** 或引入 **平台组共享**，而不是单队列无限加 Agnet |

---

### 5.2 规模总览

| 模式 | 最小团队（子 Agnet 数） | 最大团队（子 Agnet 数） |
|------|-------------------------|-------------------------|
| **瀑布** | **5** | **9** |
| **敏捷** | **3** | **8** |

---

### 5.3 瀑布模式 — 最小团队（5 个子 Agnet）

适用于：**阶段清晰、评审链存在、但人力收紧** 的项目。五人对应瀑布五条「硬闸门」，互不合并，以保证可追溯。

| # | 角色代号（建议） | 角色名称 | 职责（该子 Agnet 专属） |
|---|------------------|----------|-------------------------|
| W1 | `WF-BA` | **业务/需求分析师** | 需求规格说明书、范围与假设、验收标准、变更登记；组织需求评审输入材料 |
| W2 | `WF-ARC` | **解决方案架构师** | 系统架构、模块边界、接口与数据契约、非功能需求（性能/可用/扩展）落档 |
| W3 | `WF-DEV` | **软件工程师（实现）** | 按设计实现功能、单元测试、静态检查与本地验证、参与设计澄清 |
| W4 | `WF-QA` | **测试工程师** | 测试策略与用例、集成/系统测试、缺陷管理与回归、**发布前质量门禁结论** |
| W5 | `WF-REL` | **发布与运维工程师** | CI/CD 流水线、环境一致性、发布编排与回滚预案、上线后健康检查与基础可观测 |

**说明**：最小瀑布 **不单独设** PM/安全/文档岗——由 BA（对外表述）、ARC（安全架构底线）、REL（Runbook 最低集）**兼带轻量职责**；若监管或合同要求独立签字，应升级到 **最大团队**。

---

### 5.4 瀑布模式 — 最大团队（9 个子 Agnet）

适用于：**强合规、多干系人、前后端并行、安全与文档独立审计** 的大型项目。

| # | 角色代号（建议） | 角色名称 | 职责（该子 Agnet 专属） |
|---|------------------|----------|-------------------------|
| W1 | `WF-PM` | **产品经理** | 路线图与里程碑、干系人沟通、优先级裁决、发布范围与 Go/No-Go 协同 |
| W2 | `WF-BA` | **业务/需求分析师** | 需求规格与验收标准、变更控制、与 PM 对齐「做什么」 |
| W3 | `WF-ARC` | **解决方案架构师** | 总体架构与技术选型、跨团队接口冻结、架构评审组织 |
| W4 | `WF-DEV-B` | **后端开发工程师** | 服务/API、领域模型、数据访问与集成、后端侧单元与契约测试 |
| W5 | `WF-DEV-F` | **前端开发工程师** | UI 实现、前端状态与可访问性、与后端联调、前端侧测试 |
| W6 | `WF-QA` | **测试工程师** | 端到端质量责任、测试环境与数据、缺陷 SLAs、发布签字前的测试结论 |
| W7 | `WF-SEC` | **安全与合规专员** | 威胁建模输入、密钥与凭据策略、依赖与供应链审查、发布前安全复核 |
| W8 | `WF-DOC` | **技术文档工程师** | 用户文档、API/集成说明、对内 Runbook 与培训材料 |
| W9 | `WF-REL` | **发布与运维工程师** | 多云/多环境发布路径、IaC 与配置治理、监控告警与值班交接 |

**说明**：若项目为 **纯后端或纯工具链**，可折叠 `WF-DEV-F` 与 `WF-DEV-B` 之一，团队规模降到 **8**，仍属瀑布最大思想的变体。

---

### 5.5 敏捷模式 — 最小团队（3 个子 Agnet）

适用于：**单迭代内完成可演示增量** 的 **最小跨职能小组**（对标经典 PO + Dev + QA）。

| # | 角色代号（建议） | 角色名称 | 职责（该子 Agnet 专属） |
|---|------------------|----------|-------------------------|
| A1 | `AG-PO` | **产品负责人（Product Owner）** | 迭代 Backlog 排序、验收标准、冲刺目标对齐、对「完成」有定义的解释权 |
| A2 | `AG-DEV` | **软件工程师** | 迭代内设计与实现、重构、代码评审协作；简单流水线改动可由本角色在策略允许下执行 |
| A3 | `AG-QA` | **测试工程师** | 迭代测试计划、自动化与探索性测试、DoD 中质量项、阻塞发布的缺陷升级 |

**说明**：**不设专职 Scrum Master / SRE**——节奏由 PO 与团队自律维持，环境与发布依赖 **平台默认模板** 或 **WF-REL 类共享服务**（组织级平台组）。

---

### 5.6 敏捷模式 — 最大团队（8 个子 Agnet）

适用于：**双轨并行特性、节奏复杂、需要嵌入式流程与平台能力** 的规模化迭代。

| # | 角色代号（建议） | 角色名称 | 职责（该子 Agnet 专属） |
|---|------------------|----------|-------------------------|
| A1 | `AG-PO` | **产品负责人** | Backlog、价值排序、迭代目标与验收 |
| A2 | `AG-SM` | **敏捷教练 / 流程负责人（Scrum Master）** | 阻碍清除、仪式效率、改进项跟踪；**不作**业务优先级裁决（与 PO 分工） |
| A3 | `AG-TL` | **技术负责人（Tech Lead）** | 迭代内架构切片、技术债边界、难点攻关与跨 Dev 对齐 |
| A4 | `AG-DEV-A` | **开发工程师 A** | 特性/区域 A 的端到端交付（含与 QA 的自动化协作） |
| A5 | `AG-DEV-B` | **开发工程师 B** | 特性/区域 B 的并行交付，减少单点阻塞 |
| A6 | `AG-QA` | **测试工程师** | 迭代质量策略、CI 质量门禁、发布候选验证 |
| A7 | `AG-UX` | **UX/UI 设计师** | 迭代内交互与视觉、可用性标准、与设计系统对齐 |
| A8 | `AG-SRE` | **DevOps / SRE 工程师** | 流水线即代码、环境晋升策略、可观测与容量、发布与回滚执行 |

**说明**：超过 **8** 时优先 **拆分第二个 Squad（另一套 3～8 人模板）**，而不是在同一 backlog 上继续加角色，否则协调成本会吞噬并行收益。

---

### 5.7 角色对照（可选摘编）

与 **5.1 通用抽象** 的对应关系：

| 通用抽象 | 瀑布最小 | 瀑布最大 | 敏捷最小 | 敏捷最大 |
|----------|----------|----------|----------|----------|
| 产品/需求 | BA | PM + BA | PO | PO |
| 架构 | ARC | ARC | （并入 DEV/TL） | TL |
| 开发 | DEV | DEV-B + DEV-F | DEV | DEV-A + DEV-B |
| 测试 | QA | QA | QA | QA |
| DevOps/SRE | REL | REL | （平台/兼任） | SRE |
| 安全/合规 | （ARC 兼） | SEC | （门禁委托） | （可由平台策略 + TL） |
| 技术写作 | （REL 兼） | DOC | （最小化） | （可由 PO 兼） |
| 流程推动 | — | — | — | SM |
| 体验设计 | — | （可由 DEV-F 兼） | — | UX |

---

## 六、全生命周期能力（Heicode 要覆盖的「范式」）

| 阶段 | 目标产出 | 依赖（概念） |
|------|-----------|--------------|
| 构思 / 规格 | PRD、接口草案、风险清单 | 产品子 Agnet + 文档模板 |
| 实现 | MR/PR、代码、Review 记录 | 开发子 Agnet + Git 权限 |
| 验证 | 测试报告、覆盖率门禁 | 测试子 Agnet + CI |
| 发布 | 灰度、版本说明 | DevOps 子 Agnet + 云平台凭证 |
| 运维 | 告警、Runbook、容量 | SRE 子 Agnet + 监控 |
| 迭代 | 路线图、变更日志 | 与 Backlog/发布节奏联动 |

**自动化部署全流程**：在策略上授予子 Agnet **Git + 多云** 的最小权限（按仓库、按环境、按资源组），并通过 **New API / 企业 IdP** 做 **人机审批** 或 **策略引擎**（避免无人值守的越权发布）。

---

## 七、多智能体协作与可审计交付物

- **多 Agnet 沟通**：需要 **会话标识、线程 ID、决策摘要** 写入不可篡改或可追溯存储（至少 **追加式日志**）。  
- **产品文档**：与代码分支或发布版本 **绑定**（例如 tag / release 维度）。  
- **开发日志**：多成员场景下，按 **人/子 Agnet/任务** 维度聚合，便于复盘与合规。  

---

## 八、与 oh-my-claudecode 的关系

**定位**：oh-my-claudecode 提供的是 **「高效使用 Claude Code 类的实践与脚手架」**；Heicode 在其之上叠加 **平台化**（New API + Agnet）与 **团队级生命周期**，从「个人极致效率」扩展到 **组织级交付**。

---

## 九、已知缺口与风险（诚实清单）

| 领域 | 缺口 | 对 Heicode 的影响 |
|------|------|-------------------|
| Agnet 平台 | 权限与数据隔离未完善 | 多租户与企业售卖受阻 |
| Agnet 平台 | 有状态子 Agnet 的可视化运行态不足 | CLI/Desktop 内「状态面板」信息不完整 |
| 客户端对标 | 与 Claude Code 完全一致 | 需专门里程碑与合规评估 |
| 仓库治理 | 根目录 README/单一构建入口 | 新成员与发布节奏成本高 |

---

## 十、推荐路线图（粗粒度）

1. **契约冻结**：New API 与 cc-haha 的 **登录、令牌、用户上下文** API 冻结一版。  
2. **MVP 闭环**：官网下载 → 安装 → 登录 → 能看到 **账户/配额** 与 **一次完整 Git 推送流水线**（可先单云）。  
3. **Agnet 集成**：一键部署 **最小敏捷团队**，打通 **状态上报** 到 CLI。  
4. **可观测与合规**：审计日志、最小权限、环境隔离。  
5. **规模化**：瀑布/敏捷模板、最大团队配置、多云与混合审批。

---

## 十一、开放问题（供脑爆继续）

- 子 Agnet **所有权模型**：按项目、按组织、还是按环境？  
- **审批**：哪些操作必须人工（生产发布、费用、密钥）？  
- **计费**：模型调用走 New API；Agnet 算力是否单独计费？  
- **SLA**：对内工具 vs 对客户承诺的边界？  

---

*文档版本：与仓库内实现同步演进；修改时请更新本节日期。*

**最近更新**：2026-04-30