# Heicode 实施计划

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

## P0：边界收敛

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

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

任务：

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

验收：

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

## P1：Manager 资源模型

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

任务：

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

当前实现状态：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、子 Agent 标识、允许动作、限制条件、状态、过期时间和审计字段。
4. 提供只返回元数据和 `secret_ref` 的列表、详情、创建、授权、撤销接口；任何接口响应、日志和 Markdown 产物都不得包含真实密钥。
5. 生成一份 permission manifest 示例，用结构化数据证明“某登录用户把某个绑定资源授予某个子 Agent 角色使用”。

验收：

- Manager 能表达“某登录用户把某个绑定资源授予某个子 Agent 角色使用”。
- 数据库不保存明文密钥，只保存 `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：Agent 平台 AKS 身份接入

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

任务：

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

验收：

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

## P4：NewAPI 解耦

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

任务：

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

验收：

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

## P5：部署和审计闭环

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

任务：

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

验收：

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