chenchenandClaude Opus 4.8
0fe1d20d67
按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。
命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。
统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。
验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
127 lines
6.0 KiB
Markdown
127 lines
6.0 KiB
Markdown
# 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 才是系统执行依据。
|