heicode-mananger/docs/plan.md

Heicode 实施计划

本文依据 heicode.md 的当前共识拆分执行阶段。计划只描述方向和交付顺序，不代表每项已经进入开发。

P0：边界收敛

状态：文档边界已收敛。当前 docs/ 只保留 heicode.md、plan.md 和已上线登录接口文档作为实施依据；旧 Agnet API 草案、旧 M1-M5 计划和旧架构说明不再作为开发输入。现有代码中仍可能存在过渡期的 sk_sources、Agnet control plane 或部署计划命名，不能反向覆盖本文档边界。

目标：让团队只围绕一套产品和架构边界协作。

任务：

• 以 heicode.md 作为当前产品与架构共识。
• 保留已上线登录接口文档。
• 不再维护旧 Agnet API 草案和旧 M1-M5 计划。
• 后续所有实现前先确认是否符合 Manager / Agnet / NewAPI / Secret Store 的边界。
• 需求和边界没有想清楚前，不改代码。

验收：

• docs/ 中没有多套互相冲突的 Agnet、NewAPI 或 Manager 计划。
• 新需求讨论先落到文档共识，再进入实现。

P1：Manager 资源模型

目标：把“Git 来源”升级为面向子 Agnet 的统一资源绑定模型。

任务：

• 将当前 Git 来源抽象为资源绑定模型。
• 增加资源类型：Git、SK、项目文档、云账号、单项云资源。
• 增加 Resource Grant，用于把资源分配给登录用户、绑定 Git/SK/云资源范围、角色和子 Agnet。
• 定义资源元数据、权限范围、约束、状态和审计字段。
• 前端从单点功能页逐步走向“绑定资源 -> 分配角色 -> 部署确认”的主流程。

当前实现状态：P1 资源模型尚未在代码中完整落地；如现有 UI/API 仍使用 Git source、sk_sources 或旧部署计划字段，应先按下列最小模型收敛，再进入 P2。

最小可验证实现：

1. 后端先落库资源绑定和 Resource Grant 两类记录，不在本阶段实现 Secret Broker 的真实写入。
2. Resource Binding 表达登录用户绑定的资源元数据：资源类型、名称、外部标识、可见元数据、权限范围、约束、状态、secret_ref 和审计字段。
3. Resource Grant 表达授权关系：user、resource、binding scope、role、子 Agnet 标识、允许动作、限制条件、状态、过期时间和审计字段。
4. 提供只返回元数据和 secret_ref 的列表、详情、创建、授权、撤销接口；任何接口响应、日志和 Markdown 产物都不得包含真实密钥。
5. 生成一份 permission manifest 示例，用结构化数据证明“某登录用户把某个绑定资源授予某个子 Agnet 角色使用”。

验收：

• Manager 能表达“某登录用户把某个绑定资源授予某个子 Agnet 角色使用”。
• 数据库不保存明文密钥，只保存 secret_ref。
• P1 测试样例能覆盖 Git、SK、项目文档、云账号和单项云资源五类资源的元数据建模。
• 撤销 Resource Grant 后，对应 permission manifest 不再包含该授权。

P2：Secret Broker 与 Secret Store

目标：建立 SaaS 多用户凭证托管能力。

任务：

• 优先选型 HashiCorp Vault。
• 当前生产方向使用 Azure Key Vault 作为 Secret Provider。
• 在 Manager 后端实现 Secret Broker。
• Secret Broker 负责写入、轮换、撤销、禁用和审计。
• Manager DB 只保存 secret_ref，不保存明文密钥。
• 增加日志脱敏、前端响应过滤、Markdown 生成过滤。

验收：

• Git token、云密钥、SSH key、数据库密码不会进入 Git、Markdown、前端响应或普通日志。
• 用户可以授权和撤销资源，平台负责实际凭证托管。

P3：Agnet 平台 AKS 身份接入

目标：让子 Agnet 在 AKS 上按最小权限访问被授权资源。

任务：

• Agnet 平台支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
• 支持 Vault Kubernetes Auth 或等价 Workload Identity。
• 支持按 user / resource binding / role 生成密钥访问策略。
• 子 Agnet 运行时只能访问被授权的 secret。
• 普通开发资源支持受控注入。
• 高危操作审批只在客户端完成；审批通过后允许向子 Agnet 注入密钥保管器派生的短期、最小权限凭证。

验收：

• 子 Agnet 不保存长期密钥。
• 撤销 Resource Grant 后，子 Agnet 无法继续访问对应资源。
• 高危资源访问有审计记录。

P4：NewAPI 解耦

目标：让 NewAPI 回到独立模型网关和计费服务的位置。

任务：

• NewAPI 保持独立服务。
• NewAPI 后台不开放给普通 SaaS 用户。
• Manager 通过服务凭据调用 NewAPI。
• Manager 展示普通用户需要的模型、余额、额度、调用日志。
• 隐藏渠道管理、价格配置、模型供应商后台配置和 NewAPI 管理员能力。
• 建立 Heicode/Agnet 登录用户 user.id、channelId 与 NewAPI user / token / group / quota / usage 的映射。
• 子 Agnet 的运行模型、模型 profile 和实例数归 Agnet 平台部署配置管理，不和 NewAPI 扣费映射混用。

验收：

• 普通用户只进入 Manager，不进入 NewAPI 后台。
• Manager 能展示模型与用量信息。
• NewAPI 升级不要求 Manager 跟着改核心后台逻辑。

P5：部署和审计闭环

目标：跑通从用户想法到子 Agnet 部署、执行、观测和审计的闭环。

任务：

• Manager 生成 AGENT.md、resource context 和 permission manifest。
• Agnet 平台部署子 Agnet 后回传 deployment、agent instance、状态和事件。
• Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
• 对高危权限增加审批、撤销和运行中失效机制。
• 为每次部署保留可追溯的资源、权限、模型和上下文快照。

验收：

• 用户能看到每个子 Agnet 的角色、模型、资源权限、运行状态和失败原因。
• 审计能回答谁在什么时候让哪个子 Agnet 使用了什么资源。
• Markdown 只作为上下文，permission manifest 才是系统执行依据。