heicode-win/docs/README.md

Heicode 当前主线

本文是 docs/ 中唯一保留的新规划入口。旧 Agnet API 草案、旧里程碑、旧架构说明和旧上手材料已经删除，避免多套方向并行。已上线登录接口文档单独保留在 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。

用户授权 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 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。

优先方案：

方案	判断
HashiCorp Vault	优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权
Infisical	可选方案。产品体验较好，但需要验证多租户策略和运行时授权能力
Azure Key Vault	适合 Azure 优先部署，也可以作为 Secret Provider 的一种实现

Secret Broker 负责：

• 接收 OAuth、GitHub App、云授权回调后的凭证。
• 生成租户隔离的 secret path。
• 写入 Vault、Infisical 或 Azure Key Vault。
• 创建或更新 policy。
• 保存 secret_ref 到 Manager DB。
• 轮换、撤销、禁用凭证。
• 避免密钥进入日志、前端响应、Markdown 和 Git。

七、AKS 上的 Agnet 凭证访问

Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。

推荐流程：

用户在 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，不拿长期密钥。

运行时访问分两类：

模式	适用
受控注入	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 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
• 对高危权限增加审批、撤销和运行中失效机制。