# Heicode 愿景：团队软件交付范式（方向性说明）

本文档只回答 **「为何存在」「指向何方」「坚持什么原则」**——不涉及版本排期、接口冻结清单或逐步交付计划；后者应在路线图或项目管理工具中单独立项。

**代号表（与真实工程名无绑定，仅为行文一致）**

| 称谓 | 含义 |
|------|------|
| **Heicode Manager** | SaaS 用户控制台与编排中枢，负责用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计，以及面向普通用户展示模型、余额和调用日志。 |
| **Heicode** | 终端与桌面侧人机编程客户端及本地服务（与 Manager 区分时亦称「Heicode 客户端」）。 |
| **Orchard** | 子智能体编排与团队模板所在平台（概念名）。 |
| **执行单元** | 在编排侧按角色模板实例化的智能体实例。 |

---

## 一、我们想改变什么

组织交付软件时，常见断层出在：**规格与实现脱节**、**质量闸门含糊**、**发布与环境无人认领**、**事后难以复盘**。个人侧的「写代码更快」解决不了这些结构性问题。

Heicode 的关切点是：**在多人、多环境、多迭代的条件下，如何让对齐方式、责任边界与可追溯性默认成立**——智能体适合承接其中 **标准化、可重复** 的环节；人机分工与审批边界则由组织策略定义，而不是由某一工具一次性替你定死。

---

## 二、北极星与成功图景（定性）

- **北极星**：团队能以可复述的方式回答——「谁在何时对什么负责」「依据是什么」「如何回溯到某次发布或某条决策」。
- **成功图景（不写 KPI）**：人在关键环节保有裁决权；机器与智能体放大吞吐与一致性；交付物（规格、代码、测试结论、发布记录）能与版本或发布锚点关联；编排与权限足以支撑多团队并存而不互相踩踏。

---

## 三、指导原则

1. **可追溯优于单次极速**：宁可多一道可查的记录，也不依赖口头默契替代闸门。
2. **范式可裁剪**：瀑布与敏捷是协作隐喻，不是教条；规模与角色应由组织工作坊裁剪，而非照搬单一数字。
3. **集成可替换**：Manager、客户端、编排平台、云与流水线均以「契约与边界」相接，避免叙事绑死在某一厂商或目录名上。
4. **人机协同**：涉及权限、费用、生产变更与高敏数据的决策，默认保留人在回路；自动化扩展 **提案权**，不默认 **无限代理权**。
5. **对内对外叙事分层**：愿景文档不写实施说明书；角色代号与编队明细放入附录，以免喧宾夺主。

---

## 四、战略支柱（方向）

### 4.1 身份与策略一元化

使人机在统一身份与组织策略下工作：谁能访问何种模型、何种环境、何种仓库与密钥引用——应由 Manager 统一资源与权限语义，并通过 NewAPI、Agnet 与 Secret Store 各自的服务边界执行，而不是散落在若干控制台口径不一致。

### 4.2 编排与角色范式

把「谁在流水线哪一段接力」说清楚：既可按阶段闸门（瀑布隐喻）也可按迭代闭环（敏捷隐喻）组织 **执行单元**；重点是 **闸门不被静默跳过**、**角色不重叠到互相推诿**。具体几人几岗属于落地裁剪，见附录。

### 4.3 全生命周期可信交付

从构想到运营，关键产物应能对齐到分支、标签或发布单元：**规格、实现、验证、发布、运维与复盘** 之间有可追溯链路；多云与环境仅是载体，原则是 **最小权限与环境晋升**。

### 4.4 平台化协作而非单机熟练度

与「个人终端技巧」相比，Heicode 更强调 **跨角色、跨会话、跨环境** 的一体化协作叙事——客户端与 Manager、编排侧共同服务于同一交付故事线。

---

## 五、概念分层（鸟瞰）

```
人机入口（官网 · 控制台 · CLI / Desktop）
        ↓ 同一身份与策略边界
Heicode Manager ←→ Heicode 客户端
        ↓
编排与执行（Orchard：角色模板 · 执行单元 · 状态）
        ↓
资产与环境（仓库 · 流水线 · 运行环境与观测）
```

**边界**：编排平台内部实现细节不属于愿景正文；Heicode 关心的是 **契约、体验与安全边界** 是否说得清、守得住。

**与编排侧（如 Agnet）的可观测分工（方向性）**：平台回传的 **运行态与性能类信息**（是否在跑、健康与资源等）宜在 **Heicode Manager** 上呈现；**子执行单元在会话中的产出内容**宜在 **Heicode** 编码与工作过程中 **实时展示**。团队与个人均可使用两端；划分依据是 **信息类型与载体**。具体边界以 [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) 为准。

---

## 六、协作范式（方向性，非排期）

- **瀑布隐喻**：强调阶段闸门与可审计链条；适合强合规、长评审链的组织语境——「最小编队 / 最大编队」表示协调复杂度量级，不是 HR 编制。
- **敏捷隐喻**：强调短迭代与跨职能闭环；适合快速试错的产品语境——同样，人数区间是 **协调上限的提示**，落地时需结合真实产能与依赖。
- **超出协调上限时**：拆分子系统、拆分 Squad 或引入共享平台能力，而不是在同一队列上无限堆角色。

全生命周期上，Heicode 主张覆盖 **构思 → 规格 → 实现 → 验证 → 发布 → 运维 → 迭代** 的 **语义连贯**，而非单独优化其中一环的工具速度。

---

## 七、可信交付与多主体协作（方向）

多执行单元、多人协作时，需要 **可关联的会话与决策摘要**、与分支或发布对齐的文档、以及可供审计的开发日志聚合维度——实现形态可为日志服务、工单或治理平台，愿景层只坚持 **可追溯** 这一条。

---

## 八、已知张力（非缺陷清单）

组织级叙事依赖 **编排侧的租户隔离、权限模型与可观测性**；客户端体验若对标商业产品，属于 **长期对齐** 而非愿景正文承诺。工程仓库如何组织、文档入口如何统一，属于 **工程卫生**，与范式方向并行演进。

---

## 九、阶段性方向（非路线图）

仅给出 **时间无序** 的三层递进意象，方便对齐讨论；**不绑定季度、不设里程碑编号**：

1. **对齐**：身份、策略与叙事口径一致，避免「各说各话」。  
2. **贯通**：人机链路在一条交付故事线下可走通，关键闸门有据可查。  
3. **规模化**：编队模板与审批策略可按组织复制，而不是单次项目手工拼装。

---

## 十、开放议题（范式层）

- 执行单元的 **所有权**：按项目、组织还是环境切分？  
- **人在回路**：哪些类别动作必须人工批准？  
- **商业与责任**：对内效率工具与对外承诺的边界如何划分？  

---

## 附录 A：编队规模与角色明细（落地参考）

以下为 **职务说明书级别的参考**，用于工作坊裁剪与编排映射；**不属于愿景层的承诺范围**。数字与代号均可按组织调整。

### A.1 规模总览

| 模式 | 最小编队（执行单元数） | 最大编队（执行单元数） |
|------|-------------------------|-------------------------|
| **瀑布** | **5** | **9** |
| **敏捷** | **3** | **8** |

### A.2 判定依据摘要

| 维度 | 瀑布 | 敏捷 |
|------|------|------|
| **流程特征** | 阶段闸门强、评审链长 | 迭代短、反馈密 |
| **「最小」含义** | 仍能走完规格→设计→实现→验证→上线且不合并关键闸门 | 仍能在一个迭代内交付可演示增量并有独立质量门禁 |
| **「最大」含义** | 覆盖常见专岗且不超过约 9 个并行协调节点 | 覆盖规模化小组且不超过约「两个披萨」协调上限 |
| **溢出策略** | 拆子系统或多套实例 | 拆 Squad 或平台组共享，而非单队列无限加人 |

### A.3 瀑布 — 最小编队（5）

| 代号 | 角色 | 职责摘要 |
|------|------|----------|
| `WF-BA` | 业务/需求分析师 | 规格、范围、验收标准、变更登记 |
| `WF-ARC` | 解决方案架构师 | 架构边界、接口与数据契约、NFR 落档 |
| `WF-DEV` | 软件工程师 | 实现、单测、静态检查、设计澄清 |
| `WF-QA` | 测试工程师 | 测试策略与用例、缺陷与回归、发布前质量门禁结论 |
| `WF-REL` | 发布与运维工程师 | CI/CD、环境一致性、发布编排与回滚预案、基础可观测 |

### A.4 瀑布 — 最大编队（9）

在 A.3 思路上扩展：`WF-PM`、`WF-DEV-B`、`WF-DEV-F`、`WF-SEC`、`WF-DOC` 等专岗；职责聚焦「合规、前后端分立、安全与文档独立审计」场景。

### A.5 敏捷 — 最小编队（3）

| 代号 | 角色 | 职责摘要 |
|------|------|----------|
| `AG-PO` | 产品负责人 | Backlog、验收标准、冲刺目标 |
| `AG-DEV` | 软件工程师 | 迭代实现与设计澄清、评审协作 |
| `AG-QA` | 测试工程师 | 迭代测试、自动化与探索性测试、DoD 质量项 |

### A.6 敏捷 — 最大编队（8）

在 A.5 基础上扩展：`AG-SM`、`AG-TL`、`AG-DEV-A`、`AG-DEV-B`、`AG-UX`、`AG-SRE` 等；强调双轨并行与嵌入式流程时协调上限。

### A.7 角色对照（摘编）

| 通用抽象 | 瀑布最小 | 瀑布最大 | 敏捷最小 | 敏捷最大 |
|----------|----------|----------|----------|----------|
| 产品/需求 | 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 |

---

*愿景正文止于附录之上；附录仅供落地与工作坊使用。*

**最近更新**：2026（愿景重写：方向优先，明细迁入附录）