docs: consolidate current heicode plan
This commit is contained in:
gongzhiyong
+217
-25
@@ -1,37 +1,229 @@
|
|||||||
# Heicode 文档入口
|
# Heicode 当前主线
|
||||||
|
|
||||||
本目录是 Heicode 仓库的**文档主索引**。2026-05-02 之后，文档以 [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) 为主线；偏离该主线的旧 Agnet API 草案和 M1-M5 计划已清理。
|
本文是 `docs/` 中唯一保留的新规划入口。旧 Agnet API 草案、旧里程碑、旧架构说明和旧上手材料已经删除，避免多套方向并行。已上线登录接口文档单独保留在 [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md)。
|
||||||
|
|
||||||
## 共用骨架（建议都先读）
|
## 一、产品定位
|
||||||
|
|
||||||
| 文档 | 用途 |
|
Heicode 的最终形态是一款覆盖软件生命周期的智能开发 Code 工具。
|
||||||
|
|
||||||
|
目标用户注册账号后，只需要输入想法，平台逐步完成：
|
||||||
|
|
||||||
|
1. 团队生成。
|
||||||
|
2. 产品文档。
|
||||||
|
3. 原型描述。
|
||||||
|
4. 代码开发。
|
||||||
|
5. 代码检查。
|
||||||
|
6. 部署到生产并对外提供服务。
|
||||||
|
7. 后续定期维护和升级。
|
||||||
|
8. 软件生命周期管理。
|
||||||
|
|
||||||
|
一句话：Heicode 是面向全流程智能开发的代码工具，不是 NewAPI 的二次开发项目，也不是单纯的 Agent 控制台。
|
||||||
|
|
||||||
|
## 二、系统边界
|
||||||
|
|
||||||
|
| 系统 | 定位 | 负责内容 |
|
||||||
|
|------|------|----------|
|
||||||
|
| Heicode Manager | SaaS 用户控制台与编排中枢 | 用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计、模型与余额展示 |
|
||||||
|
| Agnet 平台 | 执行与状态平台 | 在 AKS 上部署子 Agnet、运行任务、维护状态、事件、日志和执行元数据 |
|
||||||
|
| NewAPI | 内部模型网关与计费服务 | 模型渠道、模型调用、额度、余额、调用日志；后台不对普通用户开放 |
|
||||||
|
| Secret Store | 凭证保管库 | 保存 Git token、云密钥、SSH key、数据库密码等真实凭证 |
|
||||||
|
|
||||||
|
Manager 是用户操作入口；Agnet 是运行时执行层；NewAPI 是模型能力服务；Secret Store 是安全凭证底座。
|
||||||
|
|
||||||
|
## 三、不可破坏的原则
|
||||||
|
|
||||||
|
1. 在需求和边界没有想清楚前，不改代码。
|
||||||
|
2. NewAPI 保持独立服务，不继续改造成 Manager 的内嵌后台。
|
||||||
|
3. NewAPI 后台不开放给普通 SaaS 用户，模型管理由内部人员完成。
|
||||||
|
4. Manager 只补 NewAPI 没有的后端能力：项目、资源、权限、Agnet 部署、审计和生命周期管理。
|
||||||
|
5. 用户绑定的是 Agnet 可用资源，不只是 Git 来源。
|
||||||
|
6. 密钥不能进入 Git、Markdown、前端、部署摘要或日志。
|
||||||
|
7. Manager 负责资源绑定、权限分配和凭证托管能力；真实密钥放入 Secret Store。
|
||||||
|
8. 子 Agnet 不保存长期密钥，只接收角色、资源元数据、AGENT.md 和受控访问方式。
|
||||||
|
9. Agnet 平台在 AKS 上负责运行时身份、隔离、状态、事件和审计回传。
|
||||||
|
10. 高危生产权限优先走平台代理或审批，不直接把长期密钥注入子 Agnet。
|
||||||
|
|
||||||
|
## 四、Manager 的核心功能
|
||||||
|
|
||||||
|
1. 绑定 GitHub、GitLab、Gitea、Gitee、自建 Git 等代码来源。
|
||||||
|
2. 绑定云资源，例如 AWS、Azure、GCP、虚拟机、数据库、对象存储、Kubernetes 集群。
|
||||||
|
3. 确认项目仓库、SK 仓库、项目文档仓库或二合一仓库。
|
||||||
|
4. 按敏捷或瀑布方法分配子 Agnet 角色。
|
||||||
|
5. 为每个子 Agnet 配置 AGENT.md、可用工具、Git 范围、云资源范围、模型和预算。
|
||||||
|
6. 部署子 Agnet，设置数量、模型和运行环境。
|
||||||
|
7. 观察子 Agnet 活动状态、失败原因、事件和运行日志。
|
||||||
|
8. 查看审计日志和模型调用日志。
|
||||||
|
9. 查看可用模型、余额、额度和使用情况。
|
||||||
|
10. 展示 NewAPI 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。
|
||||||
|
|
||||||
|
## 五、资源绑定与密钥托管
|
||||||
|
|
||||||
|
绑定不是保存一串密钥，而是创建租户级 Resource Grant。
|
||||||
|
|
||||||
|
```text
|
||||||
|
用户授权 Heicode 使用外部资源
|
||||||
|
-> Manager 记录资源元数据
|
||||||
|
-> Manager 的 Secret Broker 把真实凭证写入 Secret Store
|
||||||
|
-> Manager 生成可审计、可撤销、可分配给子 Agnet 的资源授权
|
||||||
|
```
|
||||||
|
|
||||||
|
资源类型：
|
||||||
|
|
||||||
|
| 类型 | 示例 | 子 Agnet 可见内容 |
|
||||||
|
|------|------|------------------|
|
||||||
|
| Git 资源 | GitHub repo、自建 Git、SK repo | repo URL、ref、允许路径、读写范围 |
|
||||||
|
| 云账号 | Azure subscription、AWS account、GCP project | account/project/subscription 元数据、允许动作 |
|
||||||
|
| 单项云资源 | VM、DB、Bucket、AKS namespace | 资源 ID、环境、网络边界、允许动作 |
|
||||||
|
| 项目文档 | 产品文档、原型说明、需求库 | 文档引用、版本、可读范围 |
|
||||||
|
| SK 资源 | 技能仓库、上传的技能包 | SK 来源、版本、允许/禁止策略 |
|
||||||
|
|
||||||
|
Manager 数据库只保存资源元数据、权限关系和 `secret_ref`，不保存明文密钥。
|
||||||
|
|
||||||
|
## 六、开源 Secret Store 方案
|
||||||
|
|
||||||
|
SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。
|
||||||
|
|
||||||
|
优先方案：
|
||||||
|
|
||||||
|
| 方案 | 判断 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| [`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md) | 产品愿景与协作范式（方向性，非排期） |
|
| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 |
|
||||||
| [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) | SaaS Manager / NewAPI / Agnet / Secret Store 的新边界与实施计划 |
|
| Infisical | 可选方案。产品体验较好，但需要验证多租户策略和运行时授权能力 |
|
||||||
| [`glossary.md`](./glossary.md) | 术语表：Heicode / Manager / 客户端 / 子 agent / SK 等 |
|
| Azure Key Vault | 适合 Azure 优先部署，也可以作为 Secret Provider 的一种实现 |
|
||||||
| [`architecture.md`](./architecture.md) | 架构图与关键数据流（mermaid） |
|
|
||||||
| [`sk-lifecycle.md`](./sk-lifecycle.md) | SK（Skill 资产）单点真相：来源、快照、刷新、写权边界 |
|
|
||||||
|
|
||||||
## 路径 A · 内部研发 / 新成员上手
|
Secret Broker 负责：
|
||||||
|
|
||||||
适合刚加入团队、负责 `cc-haha`（客户端）或 `heicode`（Manager）开发的同学。
|
- 接收 OAuth、GitHub App、云授权回调后的凭证。
|
||||||
|
- 生成租户隔离的 secret path。
|
||||||
|
- 写入 Vault、Infisical 或 Azure Key Vault。
|
||||||
|
- 创建或更新 policy。
|
||||||
|
- 保存 `secret_ref` 到 Manager DB。
|
||||||
|
- 轮换、撤销、禁用凭证。
|
||||||
|
- 避免密钥进入日志、前端响应、Markdown 和 Git。
|
||||||
|
|
||||||
1. [`onboarding/README.md`](./onboarding/README.md)：阅读顺序
|
## 七、AKS 上的 Agnet 凭证访问
|
||||||
2. [`onboarding/local-dev.md`](./onboarding/local-dev.md)：本地联调步骤与排错
|
|
||||||
3. [`onboarding/env-variables.md`](./onboarding/env-variables.md)：环境变量手册
|
|
||||||
4. 回到共用骨架：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) → [`architecture.md`](./architecture.md) → [`glossary.md`](./glossary.md)
|
|
||||||
|
|
||||||
## 路径 B · Agnet / 平台集成方
|
Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。
|
||||||
|
|
||||||
适合实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师。
|
推荐流程：
|
||||||
|
|
||||||
1. [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) → [`glossary.md`](./glossary.md) → [`architecture.md`](./architecture.md)
|
```text
|
||||||
2. [`sk-lifecycle.md`](./sk-lifecycle.md)：SK 边界（Heicode 端写、Agnet 只读快照）
|
用户在 Manager 授权资源
|
||||||
3. [`integration/README.md`](./integration/README.md)：当前仍保留的集成契约入口
|
-> Manager Secret Broker 写入 Secret Store
|
||||||
4. [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：Heicode 客户端 ↔ Manager 浏览器登录流程
|
-> Manager 记录 Resource Grant
|
||||||
|
-> Manager 请求 Agnet 平台部署
|
||||||
|
-> Agnet 平台为 deployment / role 创建 K8s ServiceAccount
|
||||||
|
-> Agnet 平台绑定 Vault policy 或 Workload Identity
|
||||||
|
-> 子 Agnet Pod 运行时只能访问被授权的 secret
|
||||||
|
```
|
||||||
|
|
||||||
## 关于版本与更新
|
子 Agnet 拿到的是角色、目标、AGENT.md、resource context 和 permission manifest，不拿长期密钥。
|
||||||
|
|
||||||
- 本目录下的文档以 **设计意图与契约语义** 为准；实现细节以仓库代码为准。
|
运行时访问分两类：
|
||||||
- 任一文档与今晚主线出现冲突时，优先更新或删除冲突文档，不再保留多套计划并行。
|
|
||||||
- 受众边界：`docs/` 内不做产品营销文案，营销内容归 `website/`。
|
| 模式 | 适用 |
|
||||||
|
|------|------|
|
||||||
|
| 受控注入 | Git clone、开发/测试环境、低风险资源 |
|
||||||
|
| 平台代理 | 生产部署、数据库写入、高危云操作、需要审批的动作 |
|
||||||
|
|
||||||
|
普通开发资源可受控注入，生产云资源和高危操作走平台代理或审批。
|
||||||
|
|
||||||
|
## 八、NewAPI 边界
|
||||||
|
|
||||||
|
NewAPI 不作为普通用户后台开放。Manager 后端通过服务凭据调用 NewAPI，对用户展示必要信息。
|
||||||
|
|
||||||
|
Manager 可展示：
|
||||||
|
|
||||||
|
- 可用模型。
|
||||||
|
- 当前租户或项目额度。
|
||||||
|
- 余额。
|
||||||
|
- 调用量。
|
||||||
|
- 调用日志。
|
||||||
|
- 失败日志。
|
||||||
|
- 模型可用状态。
|
||||||
|
|
||||||
|
Manager 不展示：
|
||||||
|
|
||||||
|
- 渠道管理。
|
||||||
|
- 模型供应商后台配置。
|
||||||
|
- 价格配置。
|
||||||
|
- 系统管理员用户管理。
|
||||||
|
- NewAPI 原生管理后台入口。
|
||||||
|
|
||||||
|
用户登录 Manager，不直接登录 NewAPI。Manager 需要维护用户、租户、项目到 NewAPI 用户、key 或 quota 的映射。
|
||||||
|
|
||||||
|
## 九、Markdown 与权限清单
|
||||||
|
|
||||||
|
绑定的资源最终可以生成 Markdown，但 Markdown 是上下文和规则，不是凭证载体。
|
||||||
|
|
||||||
|
Markdown 可包含：
|
||||||
|
|
||||||
|
- 子 Agnet 角色。
|
||||||
|
- 目标任务。
|
||||||
|
- 项目背景。
|
||||||
|
- AGENT.md 来源。
|
||||||
|
- 可使用的 Git 资源。
|
||||||
|
- 可使用的云资源。
|
||||||
|
- 可使用的 SK。
|
||||||
|
- 允许和禁止动作。
|
||||||
|
- 审计要求。
|
||||||
|
|
||||||
|
Markdown 不得包含：
|
||||||
|
|
||||||
|
- Git token。
|
||||||
|
- 云 access key。
|
||||||
|
- refresh token。
|
||||||
|
- SSH 私钥。
|
||||||
|
- 数据库密码。
|
||||||
|
- NewAPI key 原文。
|
||||||
|
|
||||||
|
Manager 应生成两类产物：
|
||||||
|
|
||||||
|
| 产物 | 用途 |
|
||||||
|
|------|------|
|
||||||
|
| AGENT.md / resource context | 给子 Agnet 的启动上下文，说明角色和可用资源 |
|
||||||
|
| permission manifest | 给 Agnet 平台和审计系统的结构化权限清单 |
|
||||||
|
|
||||||
|
Markdown 面向模型理解，manifest 面向系统强制执行。
|
||||||
|
|
||||||
|
## 十、实施计划
|
||||||
|
|
||||||
|
### P0：边界收敛
|
||||||
|
|
||||||
|
- 以本文作为当前唯一主线。
|
||||||
|
- 保留已上线登录接口文档。
|
||||||
|
- 不再维护旧 Agnet API 草案和旧 M1-M5 计划。
|
||||||
|
|
||||||
|
### P1：Manager 资源模型
|
||||||
|
|
||||||
|
- 将当前 Git 来源抽象为资源绑定模型。
|
||||||
|
- 增加资源类型：Git、SK、项目文档、云账号、单项云资源。
|
||||||
|
- 增加 Resource Grant，用于把资源分配给项目、角色和子 Agnet。
|
||||||
|
|
||||||
|
### P2：Secret Broker 与 Secret Store
|
||||||
|
|
||||||
|
- 优先选型 Vault。
|
||||||
|
- 在 Manager 后端实现 Secret Broker。
|
||||||
|
- DB 只保存 `secret_ref`，不保存明文密钥。
|
||||||
|
- 增加日志脱敏、前端响应过滤、Markdown 生成过滤。
|
||||||
|
|
||||||
|
### P3：Agnet 平台 AKS 身份接入
|
||||||
|
|
||||||
|
- Agnet 平台支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
|
||||||
|
- 支持 Vault Kubernetes Auth 或等价 Workload Identity。
|
||||||
|
- 支持按 tenant / project / role 生成 Vault policy。
|
||||||
|
- 子 Agnet 运行时只能访问被授权的 secret。
|
||||||
|
|
||||||
|
### P4：NewAPI 解耦
|
||||||
|
|
||||||
|
- NewAPI 保持独立服务。
|
||||||
|
- Manager 通过服务凭据调用 NewAPI。
|
||||||
|
- Manager 展示普通用户需要的模型、余额、额度、调用日志。
|
||||||
|
- 隐藏 NewAPI 管理员后台能力。
|
||||||
|
|
||||||
|
### P5：部署和审计闭环
|
||||||
|
|
||||||
|
- Manager 生成 AGENT.md、resource context 和 permission manifest。
|
||||||
|
- Agnet 平台部署子 Agnet 后回传 deployment、agent instance、状态和事件。
|
||||||
|
- Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
|
||||||
|
- 对高危权限增加审批、撤销和运行中失效机制。
|
||||||
|
|||||||
@@ -1,167 +0,0 @@
|
|||||||
# Heicode 架构与关键数据流
|
|
||||||
|
|
||||||
本文用 mermaid 图示统一表达 **Heicode 客户端 / Manager / Agnet / NewAPI / Secret Store** 之间的边界与数据流，作为愿景与 SaaS 架构计划的视觉补充。
|
|
||||||
|
|
||||||
> 与文字版的对应关系：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md)、[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。旧 Agnet API 草案若与新架构计划冲突，以新架构计划为准。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、概念分层（鸟瞰）
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
flowchart TD
|
|
||||||
entry["人机入口<br/>官网 · 控制台 · CLI · Desktop"]
|
|
||||||
manager["Heicode Manager<br/>SaaS 控制台"]
|
|
||||||
client["Heicode 客户端<br/>(cc-haha)"]
|
|
||||||
agnet["Agnet 平台<br/>AKS 执行与状态"]
|
|
||||||
newapi["NewAPI<br/>模型网关 · 余额 · 日志"]
|
|
||||||
secret["Secret Store<br/>Vault / Infisical / Key Vault"]
|
|
||||||
assets["资产与环境<br/>仓库 · 流水线 · 运行时"]
|
|
||||||
|
|
||||||
entry --> manager
|
|
||||||
entry --> client
|
|
||||||
manager <--> client
|
|
||||||
manager --> agnet
|
|
||||||
manager --> newapi
|
|
||||||
manager --> secret
|
|
||||||
agnet --> secret
|
|
||||||
client -. "会话子 agent 输出" .- agnet
|
|
||||||
agnet --> assets
|
|
||||||
manager --> assets
|
|
||||||
```
|
|
||||||
|
|
||||||
要点：
|
|
||||||
- **Manager 是 SaaS 用户、租户、资源、权限与部署控制台**
|
|
||||||
- **NewAPI 是独立模型服务**，普通用户不进入 NewAPI 后台
|
|
||||||
- **Secret Store 保存真实密钥**，Manager DB 只保存 `secret_ref`
|
|
||||||
- **Agnet 在 AKS 上执行**，按 Manager 下发的 Resource Grant 和运行身份使用资源
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、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
|
|
||||||
newapi["NewAPI<br/>模型网关 / 额度 / 调用日志"]
|
|
||||||
secret["Secret Store<br/>Vault / Infisical / Key Vault"]
|
|
||||||
|
|
||||||
manager -->|"模型、余额、调用日志"| newapi
|
|
||||||
manager -->|"资源绑定 / secret_ref"| secret
|
|
||||||
manager -->|"M2M JWT · 部署/查询编队"| agnet
|
|
||||||
agnet -->|"运行时受控读取密钥"| secret
|
|
||||||
agnet -->|"webhook / events"| manager
|
|
||||||
agnet -.->|"sub_agent.output (SSE/WS)"| desktop
|
|
||||||
```
|
|
||||||
|
|
||||||
关键边界：
|
|
||||||
- 客户端 **不直连** 模型供应商，模型能力经 Manager / NewAPI 提供
|
|
||||||
- Manager 用 **服务账号 / 用户委派令牌** 调 Agnet
|
|
||||||
- 密钥不进入 Git、Markdown、前端或日志；子 Agnet 只通过受控身份使用被授权资源
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、资源绑定与凭证托管
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
flowchart LR
|
|
||||||
user["用户"]
|
|
||||||
manager["Heicode Manager"]
|
|
||||||
registry["Resource Registry<br/>资源元数据与授权"]
|
|
||||||
broker["Secret Broker"]
|
|
||||||
store["Secret Store<br/>Vault / Infisical / Key Vault"]
|
|
||||||
agnet["Agnet 平台"]
|
|
||||||
pod["子 Agnet Pod<br/>AKS ServiceAccount"]
|
|
||||||
|
|
||||||
user -->|"OAuth / GitHub App / 云授权"| manager
|
|
||||||
manager --> registry
|
|
||||||
manager --> broker
|
|
||||||
broker -->|"写入真实凭证"| store
|
|
||||||
manager -->|"Resource Grant / permission manifest"| agnet
|
|
||||||
agnet -->|"创建运行身份 / policy"| pod
|
|
||||||
pod -->|"按最小权限读取短期凭证"| store
|
|
||||||
```
|
|
||||||
|
|
||||||
要点：
|
|
||||||
- 用户完成授权，平台负责托管、轮换、撤销和审计
|
|
||||||
- Manager DB 保存资源元数据、授权关系和 `secret_ref`
|
|
||||||
- Secret Broker 是唯一写入真实凭证的后端边界
|
|
||||||
- 子 Agnet 不保存长期密钥
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、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 (`heicode/`) | NewAPI | Agnet 平台 | Secret Store |
|
|
||||||
|--------|------------------------------|-------------------------------|--------|------------|--------------|
|
|
||||||
| 用户身份 | 浏览器登录 / API Key 兼容 | SaaS 登录、租户、项目、角色 | 后台服务身份 | 接收 M2M JWT 与委托令牌 | 接收服务身份 / K8s 身份 |
|
|
||||||
| 模型调用 | 不直连模型，请求经 Manager | 展示模型、余额、日志 | 模型网关、额度、调用日志 | 不参与基础模型调用 | 不参与 |
|
|
||||||
| 资源绑定 | 发起本地工作流 | Git / 云 / 文档 / SK 资源绑定与 Resource Grant | 不参与 | 接收授权后的运行引用 | 保存真实凭证 |
|
|
||||||
| 编排 | 触发部署、订阅子 agent 输出 | 一键部署入口、permission manifest、审计 | 不参与 | 实际执行编队、维护实例生命周期 | 按策略提供密钥 |
|
|
||||||
| SK | 主要编辑入口（写 Git / 上传） | 展开 `sk_sources`、刷新策略 | 不参与 | 拉取快照、运行时只读注入 | 可保存访问凭证 |
|
|
||||||
| 观测 | 会话内子 agent 输出 | 平台运行态聚合、NewAPI 调用日志 | 调用日志、余额 | 提供事件流、指标导出 | 提供密钥访问审计 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、相关代码索引
|
|
||||||
|
|
||||||
- 客户端登录：`cc-haha/src/server/api/heicode-auth.ts`
|
|
||||||
- 客户端 Provider 预设：`cc-haha/src/server/config/providerPresets.ts`
|
|
||||||
- Manager OAuth：`heicode/controller/heicode_oauth.go`、`heicode/router/heicode-router.go`
|
|
||||||
|
|
||||||
> 代码会演进，本文以 **架构关系** 为准；具体路径请以仓库当前实现为最终事实。
|
|
||||||
@@ -1,118 +0,0 @@
|
|||||||
# 术语表
|
|
||||||
|
|
||||||
本术语表是 Heicode 仓库内 **跨文档共享的命名标准**。任意文档涉及以下名称时，请相对链接回本文件锚点，避免规则漂移。
|
|
||||||
|
|
||||||
> 与代号相关的方向性来源：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md)。
|
|
||||||
> 与 SaaS 架构相关的来源：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。
|
|
||||||
|
|
||||||
## 产品级代号
|
|
||||||
|
|
||||||
### Heicode
|
|
||||||
仓库与产品族的总称。在区分产品形态时，亦称 **Heicode 客户端**。
|
|
||||||
|
|
||||||
### Heicode Manager
|
|
||||||
SaaS 用户控制台与编排中枢，源码目录 `heicode/`。负责用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计，以及面向普通用户展示模型、余额和调用日志。
|
|
||||||
|
|
||||||
### Heicode 客户端
|
|
||||||
面向开发者的 CLI（Ink）+ 桌面应用（Tauri + React）+ 本地 HTTP/WS 服务，源码目录 `cc-haha/`。
|
|
||||||
|
|
||||||
### Orchard
|
|
||||||
**子智能体编排与团队模板** 所在平台的概念名。它是一个抽象代号，用以保持愿景叙事不绑死在某个厂商。落地形态可对应 Agnet。
|
|
||||||
|
|
||||||
### Agnet
|
|
||||||
当前实际接入的编排平台名称。Agnet 底层运行在 AKS，负责部署子 Agnet、维护执行状态、事件和日志，并按 Manager 下发的 Resource Grant 使用受控资源。
|
|
||||||
|
|
||||||
### NewAPI
|
|
||||||
独立的模型网关和计费服务。它提供模型渠道、模型调用、额度、余额和调用日志；普通 SaaS 用户不进入 NewAPI 后台，Manager 后端通过服务凭据调用 NewAPI。
|
|
||||||
|
|
||||||
### Secret Store
|
|
||||||
真实凭证的保管库，例如 HashiCorp Vault、Infisical 或 Azure Key Vault。Manager 数据库只保存 `secret_ref`，不保存 Git token、云密钥、SSH 私钥和数据库密码。
|
|
||||||
|
|
||||||
### Secret Broker
|
|
||||||
Manager 后端中负责凭证写入、轮换、撤销、路径生成、策略创建和审计的边界模块。业务代码不应绕过 Secret Broker 直接操作 Secret Store。
|
|
||||||
|
|
||||||
## 编排相关
|
|
||||||
|
|
||||||
### 执行单元 (`agent_instance`)
|
|
||||||
按角色模板在编排侧实例化的智能体实例。生命周期字段详见 API 设计 §6.1。
|
|
||||||
|
|
||||||
### 子 agent
|
|
||||||
本仓库语境下，特指 **Agnet 平台内部** 的子智能体 / 子执行单元，由 Agnet 编排实例化，**不是** Heicode 自研运行时。
|
|
||||||
|
|
||||||
### 部署 (`deployment`)
|
|
||||||
一次「按团队模板把多个执行单元拉起」的整体行为，由 `deployment_id` 唯一标识。
|
|
||||||
|
|
||||||
### 团队 / 编队
|
|
||||||
一组在同一 `deployment` 中协同工作的执行单元。瀑布与敏捷下的最小/最大编队详见愿景附录 A。
|
|
||||||
|
|
||||||
## 资产与边界
|
|
||||||
|
|
||||||
### SK（Skill 资产）
|
|
||||||
为子 agent 提供运行时只读上下文的说明类正文，多为 Markdown。详见 [`sk-lifecycle.md`](./sk-lifecycle.md)。
|
|
||||||
|
|
||||||
### 资源绑定 (`resource binding`)
|
|
||||||
用户授权 Heicode 使用某个外部资源的动作与结果。资源可以是 Git 仓库、SK 仓库、项目文档、Azure/AWS/GCP 账号、VM、数据库、对象存储或 AKS 集群。绑定产生资源元数据和 `secret_ref`，不产生可暴露的明文密钥。
|
|
||||||
|
|
||||||
### Resource Grant
|
|
||||||
Manager 中把某个资源授权给特定租户、项目、子 Agnet 角色和权限范围的记录。部署时，Manager 将 Resource Grant 转换为 permission manifest 发送给 Agnet 平台。
|
|
||||||
|
|
||||||
### permission manifest
|
|
||||||
面向系统强制执行的结构化权限清单，描述每个子 Agnet 可用的资源、动作、路径、环境和限制。它和 AGENT.md / resource context 配套使用。
|
|
||||||
|
|
||||||
### resource context
|
|
||||||
面向模型理解的启动上下文，通常可以生成为 Markdown。它描述角色、目标、可用资源和禁止事项，但不得包含任何真实密钥。
|
|
||||||
|
|
||||||
### `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。
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
# 集成契约入口
|
|
||||||
|
|
||||||
本目录只保留当前仍贴近实现的登录与客户端认证契约。Agnet / NewAPI / Secret Store 的新边界和实施计划统一放在 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md)。
|
|
||||||
|
|
||||||
## 保留文档
|
|
||||||
|
|
||||||
| 文档 | 用途 |
|
|
||||||
|------|------|
|
|
||||||
| [`Heicode-登录接口对接文档.md`](./Heicode-登录接口对接文档.md) | 已上线账号密码登录接口契约 |
|
|
||||||
| [`heicode-oauth-flow.md`](./heicode-oauth-flow.md) | Heicode 客户端通过浏览器登录 Manager 的流程 |
|
|
||||||
|
|
||||||
## 已清理内容
|
|
||||||
|
|
||||||
旧的 Agnet API 草案、编排提案、验收矩阵和 M1-M5 计划已经删除。后续需要按新主线重新生成正式契约，而不是沿用旧文档。
|
|
||||||
@@ -1,149 +0,0 @@
|
|||||||
# HeiCode 浏览器登录流程（客户端 ↔ Manager）
|
|
||||||
|
|
||||||
本文给出 Heicode 客户端通过浏览器完成 Manager 登录的端到端流程，并说明字段、错误模型与扩展点。当前实现以 **loopback 直接回 token** 为主，OAuth2 + PKCE 已在客户端预留。
|
|
||||||
|
|
||||||
> 代码位置：
|
|
||||||
>
|
|
||||||
> - 客户端：`cc-haha/src/server/api/heicode-auth.ts`
|
|
||||||
> - 服务端：`heicode/controller/heicode_oauth.go`、`heicode/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（heicode） | 校验 loopback、引导登录、回跳 token |
|
|
||||||
| `GET /heicode/oauth/session` | Manager（heicode） | 给「请先登录」过渡页轮询登录态 |
|
|
||||||
| `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/>(heicode)
|
|
||||||
|
|
||||||
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 时应使用服务间令牌或受控委托令牌，具体以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准
|
|
||||||
- 跨链路追踪建议在 Manager 调 Agnet 时附带 `X-Heicode-Correlation-Id` 与本登录会话关联
|
|
||||||
|
|
||||||
## 七、安全注意事项
|
|
||||||
|
|
||||||
- 客户端必须在每次启动时 **新生成** `state` / `code_verifier`，禁止复用
|
|
||||||
- Manager 必须 **拒绝** 非 loopback 的 `redirect_uri`（已实现）
|
|
||||||
- Token 长生命周期使用前提：Manager 端可吊销且具备审计；不要在跨设备粘贴中传播
|
|
||||||
- 出现安全事件时，Manager 应能批量吊销名为 `HeiCode` 的 Token
|
|
||||||
|
|
||||||
## 八、界面截图（docs/images）
|
|
||||||
|
|
||||||
> 下列截图来自 `docs/images/`，用于辅助理解登录链路与界面落位。
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -1,42 +0,0 @@
|
|||||||
# 新成员上手指引
|
|
||||||
|
|
||||||
适合刚加入 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. 主计划对齐：[`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.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 展示，底层能力来自 NewAPI
|
|
||||||
- **不要** 给 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)
|
|
||||||
@@ -1,76 +0,0 @@
|
|||||||
# 环境变量手册（Heicode 客户端）
|
|
||||||
|
|
||||||
仅列出 Heicode 客户端（`cc-haha/`）当前 **代码中已支持** 的环境变量。Manager（`heicode/`）的环境变量请以 `heicode/CLAUDE.md` 与 `heicode/.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 索引。
|
|
||||||
@@ -1,107 +0,0 @@
|
|||||||
# 本地联调指引
|
|
||||||
|
|
||||||
把仓库内三块跑起来：`cc-haha`（客户端）、`heicode`（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（heicode）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. 起 Manager（heicode）
|
|
||||||
cd heicode
|
|
||||||
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（heicode）开发
|
|
||||||
|
|
||||||
简版命令以 `heicode/CLAUDE.md` 为准，本节只列联调相关：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 用本地 source 构建（覆盖镜像）
|
|
||||||
cd heicode
|
|
||||||
docker compose -f docker-compose.yml -f docker-compose.override.yml up --build -d
|
|
||||||
|
|
||||||
# 看日志
|
|
||||||
docker compose logs -f heicode
|
|
||||||
```
|
|
||||||
|
|
||||||
启动后访问 `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 请求
|
|
||||||
|
|
||||||
后续端到端闭环以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 的 P0-P5 为准。
|
|
||||||
@@ -1,312 +0,0 @@
|
|||||||
# Heicode SaaS Manager 与 Agnet 平台架构计划
|
|
||||||
|
|
||||||
本文记录 2026-05-02 讨论后确认的新边界：Heicode 的最终形态是一款覆盖软件生命周期的智能开发 Code 工具。用户注册后，用自然语言描述想法，平台应能逐步完成团队生成、产品文档、原型描述、代码开发、代码检查、生产部署、定期维护和升级。
|
|
||||||
|
|
||||||
本文是后续 Manager / NewAPI / Agnet / 凭证托管方案的主参考。旧的 Agnet 接口草案如与本文冲突，以本文为准。
|
|
||||||
|
|
||||||
## 一、核心判断
|
|
||||||
|
|
||||||
Heicode 不是 NewAPI 的二次开发项目，也不是单纯的 Agent 控制台。产品边界应拆成四层：
|
|
||||||
|
|
||||||
| 层 | 定位 | 主要职责 |
|
|
||||||
|----|------|----------|
|
|
||||||
| Heicode Manager | SaaS 用户控制台与编排中枢 | 用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计、余额与模型可见性 |
|
|
||||||
| Agnet 平台 | 执行与状态平台 | 在 AKS 上部署子 Agnet、运行任务、维护状态、事件、日志和执行元数据 |
|
|
||||||
| NewAPI | 内部模型网关与计费服务 | 模型渠道、模型列表、模型调用、额度、余额、调用日志；后台不开放给普通用户 |
|
|
||||||
| Secret Store | 凭证保管库 | 保存 Git token、云密钥、SSH key、数据库密码等真实凭证 |
|
|
||||||
|
|
||||||
Manager 是用户操作入口；Agnet 是运行时执行层；NewAPI 是模型能力服务；Secret Store 是安全凭证底座。
|
|
||||||
|
|
||||||
## 二、不可破坏的原则
|
|
||||||
|
|
||||||
1. 在需求和边界没有想清楚前，不改代码。
|
|
||||||
2. NewAPI 保持独立服务，不继续改造成 Manager 的内嵌后台。
|
|
||||||
3. NewAPI 后台不开放给普通 SaaS 用户，模型管理由内部人员完成。
|
|
||||||
4. Manager 只补 NewAPI 没有的后端能力：项目、资源、权限、Agnet 部署、审计和生命周期管理。
|
|
||||||
5. 用户绑定的是 Agnet 可用资源，不只是 Git 来源。
|
|
||||||
6. 密钥不能进入 Git、Markdown、前端、部署摘要或日志。
|
|
||||||
7. Manager 负责资源绑定、权限分配和凭证托管能力；真实密钥放入 Secret Store。
|
|
||||||
8. 子 Agnet 不保存长期密钥，只接收角色、资源元数据、AGENT.md 和受控访问方式。
|
|
||||||
9. Agnet 平台在 AKS 上负责运行时身份、隔离、状态、事件和审计回传。
|
|
||||||
10. 高危生产权限优先走平台代理或审批，不直接把长期密钥注入子 Agnet。
|
|
||||||
|
|
||||||
## 三、Manager 的产品主线
|
|
||||||
|
|
||||||
Manager 面向普通用户展示的是一条从想法到交付的控制流程，而不是 NewAPI 管理后台。
|
|
||||||
|
|
||||||
核心功能：
|
|
||||||
|
|
||||||
1. 绑定 GitHub、GitLab、Gitea、Gitee、自建 Git 等代码来源。
|
|
||||||
2. 绑定云资源，例如 AWS、Azure、GCP、虚拟机、数据库、对象存储、Kubernetes 集群。
|
|
||||||
3. 确认项目仓库、SK 仓库、项目文档仓库或二合一仓库。
|
|
||||||
4. 按敏捷或瀑布方法分配子 Agnet 角色。
|
|
||||||
5. 为每个子 Agnet 配置 AGENT.md、可用工具、Git 范围、云资源范围、模型和预算。
|
|
||||||
6. 部署子 Agnet，设置数量、模型和运行环境。
|
|
||||||
7. 观察子 Agnet 活动状态、失败原因、事件和运行日志。
|
|
||||||
8. 查看审计日志和模型调用日志。
|
|
||||||
9. 查看可用模型、余额、额度和使用情况。
|
|
||||||
10. 展示 NewAPI 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。
|
|
||||||
|
|
||||||
## 四、资源绑定模型
|
|
||||||
|
|
||||||
“绑定”不是保存一串密钥，而是创建租户级 Resource Grant。
|
|
||||||
|
|
||||||
```text
|
|
||||||
某个用户/租户授权 Heicode 使用某个外部资源
|
|
||||||
-> Manager 记录资源元数据
|
|
||||||
-> Manager 的 Secret Broker 把真实凭证写入 Secret Store
|
|
||||||
-> Manager 生成可审计、可撤销、可分配给子 Agnet 的资源授权
|
|
||||||
```
|
|
||||||
|
|
||||||
资源类型建议统一建模为：
|
|
||||||
|
|
||||||
| 类型 | 示例 | 子 Agnet 可见内容 |
|
|
||||||
|------|------|------------------|
|
|
||||||
| Git 资源 | GitHub repo、自建 Git、SK repo | repo URL、ref、允许路径、读写范围 |
|
|
||||||
| 云账号 | Azure subscription、AWS account、GCP project | account/project/subscription 元数据、允许动作 |
|
|
||||||
| 单项云资源 | VM、DB、Bucket、AKS namespace | 资源 ID、环境、网络边界、允许动作 |
|
|
||||||
| 项目文档 | 产品文档、原型说明、需求库 | 文档引用、版本、可读范围 |
|
|
||||||
| SK 资源 | 技能仓库、上传的技能包 | SK 来源、版本、允许/禁止策略 |
|
|
||||||
|
|
||||||
Manager 数据库保存资源元数据和授权关系，不保存明文密钥：
|
|
||||||
|
|
||||||
```text
|
|
||||||
resources:
|
|
||||||
id
|
|
||||||
tenant_id
|
|
||||||
provider
|
|
||||||
type
|
|
||||||
display_name
|
|
||||||
external_id
|
|
||||||
metadata_json
|
|
||||||
secret_ref
|
|
||||||
status
|
|
||||||
|
|
||||||
resource_grants:
|
|
||||||
id
|
|
||||||
tenant_id
|
|
||||||
project_id
|
|
||||||
resource_id
|
|
||||||
agnet_role
|
|
||||||
permissions_json
|
|
||||||
constraints_json
|
|
||||||
|
|
||||||
secret_bindings:
|
|
||||||
id
|
|
||||||
tenant_id
|
|
||||||
resource_id
|
|
||||||
secret_provider
|
|
||||||
secret_ref
|
|
||||||
version
|
|
||||||
status
|
|
||||||
last_rotated_at
|
|
||||||
```
|
|
||||||
|
|
||||||
## 五、开源 Secret Store 架构
|
|
||||||
|
|
||||||
SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。
|
|
||||||
|
|
||||||
推荐抽象：
|
|
||||||
|
|
||||||
```text
|
|
||||||
Manager API
|
|
||||||
-> Secret Broker
|
|
||||||
-> Secret Provider
|
|
||||||
-> Vault / Infisical / Azure Key Vault
|
|
||||||
```
|
|
||||||
|
|
||||||
开源优先方案：
|
|
||||||
|
|
||||||
| 方案 | 适用判断 |
|
|
||||||
|------|----------|
|
|
||||||
| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 |
|
|
||||||
| Infisical | 产品体验较好，适合作为可选 Secret Provider，需要进一步验证多租户策略和运行时授权能力 |
|
|
||||||
| SOPS + KMS | 适合配置文件密钥，不适合作为 SaaS 动态资源绑定主方案 |
|
|
||||||
|
|
||||||
Secret Broker 负责：
|
|
||||||
|
|
||||||
- 接收 OAuth / GitHub App / 云授权回调后的凭证。
|
|
||||||
- 生成租户隔离的 secret path。
|
|
||||||
- 写入 Vault / Infisical / Key Vault。
|
|
||||||
- 创建或更新 policy。
|
|
||||||
- 保存 secret_ref 到 Manager DB。
|
|
||||||
- 轮换、撤销、禁用凭证。
|
|
||||||
- 避免密钥进入日志、前端响应、Markdown 和 Git。
|
|
||||||
|
|
||||||
Vault 路径示例：
|
|
||||||
|
|
||||||
```text
|
|
||||||
secret/heicode/tenants/{tenant_id}/resources/{resource_id}/github
|
|
||||||
secret/heicode/tenants/{tenant_id}/resources/{resource_id}/azure
|
|
||||||
secret/heicode/tenants/{tenant_id}/projects/{project_id}/deployments/{deployment_id}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 六、AKS 上的 Agnet 凭证访问
|
|
||||||
|
|
||||||
Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。
|
|
||||||
|
|
||||||
推荐流程：
|
|
||||||
|
|
||||||
```text
|
|
||||||
用户在 Manager 授权资源
|
|
||||||
-> Manager Secret Broker 写入 Secret Store
|
|
||||||
-> Manager 记录 Resource Grant
|
|
||||||
-> Manager 请求 Agnet 平台部署
|
|
||||||
-> Agnet 平台为 deployment / role 创建 K8s ServiceAccount
|
|
||||||
-> Agnet 平台绑定 Vault policy 或 Workload Identity
|
|
||||||
-> 子 Agnet Pod 运行时只能访问被授权的 secret
|
|
||||||
```
|
|
||||||
|
|
||||||
子 Agnet 拿到的是：
|
|
||||||
|
|
||||||
```text
|
|
||||||
你是 backend-agent
|
|
||||||
你可以访问 project-main-repo
|
|
||||||
权限是 read_repo / write_branch / create_pr
|
|
||||||
凭证由运行环境提供
|
|
||||||
禁止输出、持久化或提交任何凭证
|
|
||||||
```
|
|
||||||
|
|
||||||
子 Agnet 不应拿到：
|
|
||||||
|
|
||||||
```text
|
|
||||||
github_pat_xxx
|
|
||||||
azure_client_secret_xxx
|
|
||||||
ssh_private_key
|
|
||||||
database_password
|
|
||||||
```
|
|
||||||
|
|
||||||
运行时访问分两种模式：
|
|
||||||
|
|
||||||
| 模式 | 用法 | 适用场景 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 受控注入 | Pod 通过 Vault Agent、Kubernetes Auth、CSI 或 Workload Identity 读取短期凭证 | Git clone、开发/测试环境、低风险资源 |
|
|
||||||
| 平台代理 | 子 Agnet 请求 Manager / Agnet Platform 代执行资源动作 | 生产部署、数据库写入、高危云操作、需要审批的动作 |
|
|
||||||
|
|
||||||
推荐混合策略：普通开发资源可受控注入，生产云资源和高危操作走平台代理或审批。
|
|
||||||
|
|
||||||
## 七、NewAPI 的边界
|
|
||||||
|
|
||||||
NewAPI 不作为普通用户后台开放。Manager 后端通过服务凭据调用 NewAPI，对用户展示必要信息。
|
|
||||||
|
|
||||||
Manager 可展示：
|
|
||||||
|
|
||||||
- 可用模型。
|
|
||||||
- 当前租户或项目额度。
|
|
||||||
- 余额。
|
|
||||||
- 调用量。
|
|
||||||
- 调用日志。
|
|
||||||
- 失败日志。
|
|
||||||
- 模型可用状态。
|
|
||||||
|
|
||||||
Manager 不展示：
|
|
||||||
|
|
||||||
- 渠道管理。
|
|
||||||
- 模型供应商后台配置。
|
|
||||||
- 价格配置。
|
|
||||||
- 系统管理员用户管理。
|
|
||||||
- NewAPI 原生管理后台入口。
|
|
||||||
|
|
||||||
用户登录 Manager，不直接登录 NewAPI。Manager 需要维护用户 / 租户 / 项目到 NewAPI 用户、key 或 quota 的映射。
|
|
||||||
|
|
||||||
## 八、认证与权限统一策略
|
|
||||||
|
|
||||||
不要求三套系统完全统一登录，但必须统一租户、项目、角色、资源授权语义。
|
|
||||||
|
|
||||||
| 系统关系 | 建议 |
|
|
||||||
|----------|------|
|
|
||||||
| Manager ↔ NewAPI | 服务端对服务端调用。用户不直接进入 NewAPI 后台。Manager 按租户映射 NewAPI key、额度和日志 |
|
|
||||||
| Manager ↔ Agnet | 必须共享 tenant / project / deployment / role / resource grant 语义。使用 M2M token 或受控委托令牌 |
|
|
||||||
| Agnet ↔ Secret Store | 通过 AKS ServiceAccount、Vault Kubernetes Auth、Workload Identity 或平台代理访问 |
|
|
||||||
| 用户 ↔ Manager | Manager 是 SaaS 登录和用户体验入口 |
|
|
||||||
|
|
||||||
因此，可行方案是：Manager 统一用户体验和资源权限，Agnet 统一执行身份和运行隔离，NewAPI 只提供模型服务能力。
|
|
||||||
|
|
||||||
## 九、启动上下文与 Markdown
|
|
||||||
|
|
||||||
绑定的资源最终可以生成 Markdown，但 Markdown 是上下文和规则，不是凭证载体。
|
|
||||||
|
|
||||||
Markdown 可包含：
|
|
||||||
|
|
||||||
- 子 Agnet 角色。
|
|
||||||
- 目标任务。
|
|
||||||
- 项目背景。
|
|
||||||
- AGENT.md 来源。
|
|
||||||
- 可使用的 Git 资源。
|
|
||||||
- 可使用的云资源。
|
|
||||||
- 可使用的 SK。
|
|
||||||
- 允许和禁止动作。
|
|
||||||
- 审计要求。
|
|
||||||
|
|
||||||
Markdown 不得包含：
|
|
||||||
|
|
||||||
- Git token。
|
|
||||||
- 云 access key。
|
|
||||||
- refresh token。
|
|
||||||
- SSH 私钥。
|
|
||||||
- 数据库密码。
|
|
||||||
- NewAPI key 原文。
|
|
||||||
|
|
||||||
建议 Manager 生成两类产物：
|
|
||||||
|
|
||||||
| 产物 | 用途 |
|
|
||||||
|------|------|
|
|
||||||
| AGENT.md / resource context | 给子 Agnet 的启动上下文，说明角色和可用资源 |
|
|
||||||
| permission manifest | 给 Agnet 平台和审计系统的结构化权限清单 |
|
|
||||||
|
|
||||||
Markdown 面向模型理解，manifest 面向系统强制执行。
|
|
||||||
|
|
||||||
## 十、实施 Plan
|
|
||||||
|
|
||||||
### P0：文档和边界收敛
|
|
||||||
|
|
||||||
- 清理废弃或冲突的旧文档入口。
|
|
||||||
- 确认本文为 Manager / NewAPI / Agnet / Secret Store 的主参考。
|
|
||||||
- 更新术语表：资源绑定、Resource Grant、Secret Broker、Secret Store、平台代理。
|
|
||||||
- 明确代码修改铁律：边界未讨论清楚前不改代码。
|
|
||||||
|
|
||||||
### P1：Manager 资源模型
|
|
||||||
|
|
||||||
- 将当前“Git 来源”抽象为资源绑定模型。
|
|
||||||
- 增加资源类型：Git、SK、项目文档、云账号、单项云资源。
|
|
||||||
- 增加 resource_grants，用于把资源分配给项目、角色和子 Agnet。
|
|
||||||
- 前端从“填 JSON”升级为“绑定资源 -> 分配角色 -> 部署确认”的向导。
|
|
||||||
|
|
||||||
### P2：Secret Broker 与开源 Secret Store
|
|
||||||
|
|
||||||
- 选型 Vault 作为首个开源 Secret Provider。
|
|
||||||
- 在 Manager 后端实现 Secret Broker。
|
|
||||||
- 支持写入、读取引用、轮换、撤销、禁用。
|
|
||||||
- DB 只保存 secret_ref，不保存明文密钥。
|
|
||||||
- 增加密钥泄露防护：日志脱敏、前端响应过滤、Markdown 生成过滤。
|
|
||||||
|
|
||||||
### P3：Agnet 平台 AKS 身份接入
|
|
||||||
|
|
||||||
- Agnet 平台支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
|
|
||||||
- 支持 Vault Kubernetes Auth 或等价 Workload Identity。
|
|
||||||
- 支持按 tenant / project / role 生成 Vault policy。
|
|
||||||
- 子 Agnet 运行时只能访问被授权的 secret。
|
|
||||||
- 生产云操作支持平台代理或审批。
|
|
||||||
|
|
||||||
### P4：NewAPI 解耦
|
|
||||||
|
|
||||||
- NewAPI 保持独立服务。
|
|
||||||
- Manager 通过服务凭据调用 NewAPI。
|
|
||||||
- Manager 展示普通用户需要的模型、余额、额度、调用日志。
|
|
||||||
- 隐藏 NewAPI 管理员后台能力。
|
|
||||||
- 建立 Manager tenant / user / project 与 NewAPI key / quota / usage 的映射。
|
|
||||||
|
|
||||||
### P5：部署和审计闭环
|
|
||||||
|
|
||||||
- Manager 生成 AGENT.md / resource context / permission manifest。
|
|
||||||
- Agnet 平台部署子 Agnet 后回传 deployment、agent instance、状态和事件。
|
|
||||||
- Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
|
|
||||||
- 对高危权限增加审批、撤销和运行中失效机制。
|
|
||||||
|
|
||||||
## 十一、当前不做
|
|
||||||
|
|
||||||
- 不把云密钥写入 Markdown。
|
|
||||||
- 不把 NewAPI 后台开放给普通用户。
|
|
||||||
- 不让 Agnet 平台成为长期密钥明文存储地。
|
|
||||||
- 不在边界未确认时继续堆功能。
|
|
||||||
- 不把 Manager 继续改造成 NewAPI 的缝合后台。
|
|
||||||
@@ -1,147 +0,0 @@
|
|||||||
# SK 生命周期（Skill 资产单点真相）
|
|
||||||
|
|
||||||
本文是 Heicode 仓库内 **关于 SK 的唯一权威说明**。其它文档涉及 SK 时请相对链接到本文件，避免规则在多处重复。
|
|
||||||
|
|
||||||
> 架构边界出处：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。
|
|
||||||
> 名称定义：[`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 绑定关系 | 允许 | 允许 | 允许 |
|
|
||||||
|
|
||||||
权限模型以后续 P1-P3 的 Resource Grant、Secret Broker 和 Agnet AKS 运行身份实现为准：
|
|
||||||
- `agnet:credential:write`：用于绑定 Git Token / 云 SA
|
|
||||||
- `heicode:sk:write`（示例命名）：仅授予 Heicode 客户端身份
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、与一键部署的关系
|
|
||||||
|
|
||||||
Heicode Manager 提供「部署 Agnet 团队」操作时，部署请求或等价 permission manifest 须显式包含：
|
|
||||||
|
|
||||||
- 团队成员列表与组织内角色
|
|
||||||
- 各成员所用模型 / `provider_profile_id`
|
|
||||||
- 子 agent 模板与 `sk_sources`
|
|
||||||
- **子 agent 云上 / 运行时权限等参数**（如 `runtime_execution`）与 **SK 允许 / 禁止策略**（如 `sk_access_policy`）须 **在 Agnet 拉起编队/运行时随部署请求传入**；**生效副本落在 Agnet**，由其运行时强制执行；Manager 仅透传配置并展示回传锚点，不作执行时代替
|
|
||||||
|
|
||||||
部署完成后 Manager 应能展示：
|
|
||||||
|
|
||||||
`团队成员 → 模型 → Agnet 子 agent → SK 源（Git ref / 上传件）→ 快照版本 → 运行时绑定 → 生效 SK 策略`
|
|
||||||
|
|
||||||
未授权模型 **不得** 在执行路径上静默生效。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 八、违规判定（评审清单）
|
|
||||||
|
|
||||||
新增能力时，凡命中下列之一，需在评审中明确拒绝：
|
|
||||||
|
|
||||||
- 提供 Agnet 或 Manager 控制台对 SK 正文的在线编辑器
|
|
||||||
- 在 Agnet 暴露面向 SK 正文的通用写 API
|
|
||||||
- 子 agent 在运行中拉取绑定列表外的 SK 路径
|
|
||||||
- 跨租户读取 SK 快照
|
|
||||||
- 「软隔离」下未带 `tenant_id` 的 SK 查询路径
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 九、与 Heicode 客户端实现的关联
|
|
||||||
|
|
||||||
当前仓库中 SK 编辑入口由 Heicode 客户端承担。具体逻辑实现以 `cc-haha/` 内代码为准，集成方仅需要遵守本文 SK 边界即可。
|
|
||||||
@@ -1,183 +0,0 @@
|
|||||||
# 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（愿景重写：方向优先，明细迁入附录）
|
|
||||||
Reference in New Issue
Block a user