From e08a5d4dccfec43e2f126923e39d6c0093908203 Mon Sep 17 00:00:00 2001 From: gongzhiyong Date: Sat, 2 May 2026 22:15:33 +0800 Subject: [PATCH] docs: consolidate current heicode plan --- docs/README.md | 242 ++++++++++++-- docs/architecture.md | 167 ---------- docs/glossary.md | 118 ------- docs/integration/README.md | 14 - docs/integration/heicode-oauth-flow.md | 149 --------- docs/onboarding/README.md | 42 --- docs/onboarding/env-variables.md | 76 ----- docs/onboarding/local-dev.md | 107 ------ docs/saas-manager-agnet-architecture-plan.md | 312 ------------------ docs/sk-lifecycle.md | 147 --------- docs/vision-heicode-full-stack-agentic-dev.md | 183 ---------- 11 files changed, 217 insertions(+), 1340 deletions(-) delete mode 100644 docs/architecture.md delete mode 100644 docs/glossary.md delete mode 100644 docs/integration/README.md delete mode 100644 docs/integration/heicode-oauth-flow.md delete mode 100644 docs/onboarding/README.md delete mode 100644 docs/onboarding/env-variables.md delete mode 100644 docs/onboarding/local-dev.md delete mode 100644 docs/saas-manager-agnet-architecture-plan.md delete mode 100644 docs/sk-lifecycle.md delete mode 100644 docs/vision-heicode-full-stack-agentic-dev.md diff --git a/docs/README.md b/docs/README.md index e904456..0bead19 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) | 产品愿景与协作范式（方向性，非排期） | -| [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) | SaaS Manager / NewAPI / Agnet / Secret Store 的新边界与实施计划 | -| [`glossary.md`](./glossary.md) | 术语表：Heicode / Manager / 客户端 / 子 agent / SK 等 | -| [`architecture.md`](./architecture.md) | 架构图与关键数据流（mermaid） | -| [`sk-lifecycle.md`](./sk-lifecycle.md) | SK（Skill 资产）单点真相：来源、快照、刷新、写权边界 | +| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 | +| Infisical | 可选方案。产品体验较好，但需要验证多租户策略和运行时授权能力 | +| Azure Key Vault | 适合 Azure 优先部署，也可以作为 Secret Provider 的一种实现 | -## 路径 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)：阅读顺序 -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) +## 七、AKS 上的 Agnet 凭证访问 -## 路径 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) -2. [`sk-lifecycle.md`](./sk-lifecycle.md)：SK 边界（Heicode 端写、Agnet 只读快照） -3. [`integration/README.md`](./integration/README.md)：当前仍保留的集成契约入口 -4. [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：Heicode 客户端 ↔ Manager 浏览器登录流程 +```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 拿到的是角色、目标、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 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。 +- 对高危权限增加审批、撤销和运行中失效机制。 diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 23e0891..0000000 --- a/docs/architecture.md +++ /dev/null @@ -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["人机入口
官网 · 控制台 · CLI · Desktop"] - manager["Heicode Manager
SaaS 控制台"] - client["Heicode 客户端
(cc-haha)"] - agnet["Agnet 平台
AKS 执行与状态"] - newapi["NewAPI
模型网关 · 余额 · 日志"] - secret["Secret Store
Vault / Infisical / Key Vault"] - assets["资产与环境
仓库 · 流水线 · 运行时"] - - 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 客户端
(Desktop / CLI + 本地服务)"] - manager["Heicode Manager"] - agnet["Agnet 平台"] - - user --> desktop - desktop -->|"OAuth: /heicode/oauth/*"| manager - desktop -->|"Anthropic Messages /
OpenAI Chat 调用"| manager - newapi["NewAPI
模型网关 / 额度 / 调用日志"] - secret["Secret Store
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
资源元数据与授权"] - broker["Secret Broker"] - store["Secret Store
Vault / Infisical / Key Vault"] - agnet["Agnet 平台"] - pod["子 Agnet Pod
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 编辑入口
仅 Heicode 客户端"] - git["Git 仓库
(SK 事实源)"] - upload["上传制品
(对象存储 / artifact_id)"] - manager["Heicode Manager
展开 sk_sources 与刷新策略"] - agnet["Agnet 平台"] - snapshot["不可变快照
commit_sha · artifact 版本"] - subAgent["Agnet 子 agent
(运行时只读)"] - - 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
控制台与 Dashboard"] - client["Heicode 客户端
编码会话面板"] - - agnet -->|"phase / health / metrics
(SSE · WS · webhook)"| manager - agnet -->|"sub_agent.output
(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` - -> 代码会演进，本文以 **架构关系** 为准；具体路径请以仓库当前实现为最终事实。 diff --git a/docs/glossary.md b/docs/glossary.md deleted file mode 100644 index 164796a..0000000 --- a/docs/glossary.md +++ /dev/null @@ -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 ` 形式的服务间令牌，由 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。 diff --git a/docs/integration/README.md b/docs/integration/README.md deleted file mode 100644 index e4115fa..0000000 --- a/docs/integration/README.md +++ /dev/null @@ -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 计划已经删除。后续需要按新主线重新生成正式契约，而不是沿用旧文档。 diff --git a/docs/integration/heicode-oauth-flow.md b/docs/integration/heicode-oauth-flow.md deleted file mode 100644 index 163b6f4..0000000 --- a/docs/integration/heicode-oauth-flow.md +++ /dev/null @@ -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 客户端
(本地 HTTP 服务) - participant B as 浏览器 - participant M as Heicode Manager
(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__OAUTH_AUTHORIZE_URL` | 自定义 authorize 端点 | -| `HEICODE__OAUTH_TOKEN_URL` | code → access_token 交换端点 | -| `HEICODE__OAUTH_CLIENT_ID` | OAuth Client ID（启用 PKCE 时必需） | -| `HEICODE__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/`，用于辅助理解登录链路与界面落位。 - -![Heicode login flow screenshot 01](../images/wecom-screenshot-01.jpg) -![Heicode login flow screenshot 02](../images/wecom-screenshot-02.jpg) -![Heicode login flow screenshot 03](../images/wecom-screenshot-03.jpg) -![Heicode login flow screenshot 04](../images/wecom-screenshot-04.jpg) -![Heicode login flow screenshot 05](../images/wecom-screenshot-05.jpg) -![Heicode login flow screenshot 06](../images/wecom-screenshot-06.jpg) diff --git a/docs/onboarding/README.md b/docs/onboarding/README.md deleted file mode 100644 index 0a62f1b..0000000 --- a/docs/onboarding/README.md +++ /dev/null @@ -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) diff --git a/docs/onboarding/env-variables.md b/docs/onboarding/env-variables.md deleted file mode 100644 index 00cec42..0000000 --- a/docs/onboarding/env-variables.md +++ /dev/null @@ -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__OAUTH_AUTHORIZE_URL`，用其值 -2. 否则使用 `/heicode/oauth/authorize` - -`` 取值范围与 base URL 相同（`TAIJIAICLOUD` / `CLAWDROUTER`）。 - -| 变量 | 用途 | 默认 | -|------|------|------| -| `HEICODE__OAUTH_AUTHORIZE_URL` | OAuth 授权入口 | `/heicode/oauth/authorize` | -| `HEICODE__OAUTH_TOKEN_URL` | OAuth `code → token` 交换端点 | `/heicode/oauth/token` | -| `HEICODE__OAUTH_CLIENT_ID` | OAuth Client ID（启用 PKCE 时必需） | 未设置 | -| `HEICODE__OAUTH_SCOPE` | OAuth Scope（可选，与 `client_id` 一并使用） | 未设置 | - -设置规则： -- **仅设置 AUTHORIZE_URL**：客户端跳转浏览器后，平台必须直接以 `?token=...` 形式回调（适合 Manager 当前的 loopback 实现） -- **同时设置 AUTHORIZE_URL + TOKEN_URL + CLIENT_ID**：启用标准 OAuth2 Authorization Code + PKCE -- **未设置 AUTHORIZE_URL** 时，客户端默认用 `/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 索引。 diff --git a/docs/onboarding/local-dev.md b/docs/onboarding/local-dev.md deleted file mode 100644 index 52f60fd..0000000 --- a/docs/onboarding/local-dev.md +++ /dev/null @@ -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 为准。 diff --git a/docs/saas-manager-agnet-architecture-plan.md b/docs/saas-manager-agnet-architecture-plan.md deleted file mode 100644 index 4430348..0000000 --- a/docs/saas-manager-agnet-architecture-plan.md +++ /dev/null @@ -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 的缝合后台。 diff --git a/docs/sk-lifecycle.md b/docs/sk-lifecycle.md deleted file mode 100644 index 298bd55..0000000 --- a/docs/sk-lifecycle.md +++ /dev/null @@ -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
(git / upload)"] - fetch["Agnet 解析
fetch + checkout / 拉取制品"] - snapshot["不可变快照
commit_sha · artifact 版本"] - inject["注入子 agent
(运行时只读)"] - - 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 边界即可。 diff --git a/docs/vision-heicode-full-stack-agentic-dev.md b/docs/vision-heicode-full-stack-agentic-dev.md deleted file mode 100644 index ca18cb5..0000000 --- a/docs/vision-heicode-full-stack-agentic-dev.md +++ /dev/null @@ -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（愿景重写：方向优先，明细迁入附录）