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>
3.2 KiB
3.2 KiB
06. 安全与凭证管理说明
核心原则
Heicode 是 SaaS 产品，不能把凭证管理转嫁给用户，也不能让密钥散落在 Git、Markdown、日志或子 Agent 长期状态中。
安全目标：
- 用户授权资源，平台托管凭证。
- Heicode 服务端数据库只保存元数据和
secret_ref。 - 长期密钥进入密钥保管器。
- 子 Agent 只拿短期、最小权限、可审计凭证。
- 高危操作必须由客户端审批。
凭证分类
| 凭证 | 示例 | 存放位置 |
|---|---|---|
| Git 凭证 | GitHub token、SSH key | 密钥保管器 |
| 云凭证 | Azure、AWS、GCP access key | 密钥保管器 |
| 数据库凭证 | DB password、connection secret | 密钥保管器 |
| CodeGW 服务凭据 | 内部服务 token | 服务环境或密钥保管器 |
| 短期凭证 | 临时云 token、临时 Git token | 运行时注入，TTL 到期失效 |
密钥保管器
用户可见名称：密钥保管器。
技术实现：Azure Key Vault。生产环境中 Manager 通过 VM Managed Identity 访问 Key Vault，不在业务数据库保存明文密钥。
用户不需要直接登录 Azure Key Vault，也不需要看到 Key Vault 控制台。
Secret Broker 流程
用户绑定资源
-> Heicode 接收授权结果
-> Heicode Secret Broker 写入 Azure Key Vault
-> Azure Key Vault 返回或形成 azkv://... 形式的 secret_ref
-> Heicode DB 保存 secret_ref
-> 前端只展示脱敏引用和状态
Heicode 接口不得返回明文密钥。日志、错误信息、审计摘要也不得包含明文密钥。
子 Agent 访问凭证
子 Agent 不保存长期密钥。
推荐流程：
Heicode 生成 Resource Grant
-> Agent 平台部署子 Agent
-> Agent 平台绑定运行时身份
-> 子 Agent 请求使用资源
-> 高危操作先走客户端审批
-> 审批通过后派生短期凭证
-> 短期凭证注入运行时
-> TTL 到期或任务结束后失效
高危操作
高危操作包括：
- 生产环境部署。
- 云资源创建、删除、扩缩容。
- 数据库迁移或写入。
- 访问生产密钥。
- 大额模型预算消耗。
审批必须记录：
- 审批人。
- 审批时间。
- 操作类型。
- 资源范围。
- 风险等级。
- TTL。
- 对应 deployment 或任务。
禁止事项
- 禁止把 token 写入 Git。
- 禁止把密钥写入 Markdown。
- 禁止前端返回明文密钥。
- 禁止在日志中打印密钥。
- 禁止把长期云密钥注入子 Agent。
- 禁止把 Azure Key Vault 管理入口作为普通用户入口暴露。
- 禁止把 CodeGW key 原文交给客户端长期保存。
用户侧解释
推荐文案：
Heicode 会把你的授权凭证存入密钥保管器。平台只在你授权的范围内，为对应任务和角色生成短期访问能力。密钥不会写入 Git、文档、日志或子 Agent 长期状态。
验收标准
| 验收项 | 标准 |
|---|---|
| 数据库 | 只保存 secret_ref，不保存明文密钥 |
| 前端 | 不显示明文密钥 |
| 日志 | 不包含 token、password、private key、access key |
| 子 Agent | 不保存长期凭证 |
| 高危操作 | 有客户端审批记录 |
| Azure Key Vault | 普通用户不可直接进入；Manager 仅通过受控后端身份访问 |