diff --git a/docs/heicode.md b/docs/heicode.md index 7b518d1..8bccb8d 100644 --- a/docs/heicode.md +++ b/docs/heicode.md @@ -77,6 +77,66 @@ Manager 是用户操作入口;Agnet 是运行时执行层;NewAPI 是模型 Manager 数据库只保存资源元数据、权限关系和 `secret_ref`,不保存明文密钥。 +### P1 最小资源模型 + +P1 只要求 Manager 先具备可验证的资源表达和授权关系,不要求直接接入所有 Secret Provider。真实凭证仍由后续 Secret Broker 写入 Secret Store;P1 数据库只能保存 `secret_ref`。 + +Resource Binding 建议字段: + +| 字段 | 含义 | 约束 | +|------|------|------| +| `id` | 资源绑定 ID | Manager 内部生成 | +| `tenant_id` | 租户 ID | 必填,所有资源租户隔离 | +| `type` | 资源类型 | `git`、`sk`、`project_doc`、`cloud_account`、`cloud_resource` | +| `name` | 用户可见名称 | 不包含密钥 | +| `external_ref` | 外部资源定位 | repo URL、subscription ID、resource ID、文档引用等非密钥标识 | +| `metadata` | 子 Agnet 可见元数据 | 只包含 ref、允许路径、环境、网络边界等非密钥信息 | +| `permission_scope` | 可授权动作范围 | 例如 `read`、`write`、`deploy`、`approve_required` | +| `constraints` | 使用限制 | 路径、分支、环境、网络、审批要求、TTL 等 | +| `secret_ref` | Secret Store 引用 | 可为空;有凭证时只保存引用,不保存原文 | +| `status` | 资源状态 | `pending`、`active`、`disabled`、`revoked` | +| `created_by` / `updated_by` / `created_at` / `updated_at` | 审计字段 | 必填 | + +Resource Grant 建议字段: + +| 字段 | 含义 | 约束 | +|------|------|------| +| `id` | 授权 ID | Manager 内部生成 | +| `tenant_id` / `project_id` | 授权归属 | 必填 | +| `resource_id` | 被授权资源 | 指向 Resource Binding | +| `role` | 子 Agnet 角色 | 例如 product、frontend、backend、reviewer、ops | +| `agent_id` | 子 Agnet 标识 | 可为空;为空表示授予该项目角色下的下一次部署 | +| `allowed_actions` | 本次授权动作 | 必须是 `permission_scope` 的子集 | +| `constraints` | 本次授权限制 | 不得放宽 Resource Binding 的限制 | +| `status` | 授权状态 | `active`、`suspended`、`revoked`、`expired` | +| `expires_at` | 过期时间 | 可为空;高危资源建议必填 | +| `created_by` / `revoked_by` / `created_at` / `revoked_at` | 审计字段 | 创建与撤销均需可追溯 | + +P1 permission manifest 示例: + +```json +{ + "tenant_id": "tenant_demo", + "project_id": "project_demo", + "agent_role": "backend", + "resource_grants": [ + { + "grant_id": "grant_demo_git_read", + "resource_type": "git", + "resource_ref": "https://example.com/org/repo.git", + "allowed_actions": ["read"], + "constraints": { + "ref": "main", + "paths": ["services/api/**"] + }, + "secret_ref": "secret://tenant_demo/git/repo_demo" + } + ] +} +``` + +该 manifest 可以包含 `secret_ref`,但不得包含 Git token、云 access key、SSH 私钥、数据库密码、NewAPI key 或 refresh token 原文。撤销 Resource Grant 后,下一次生成的 manifest 必须移除对应授权。 + ## 六、开源 Secret Store 方案 SaaS 场景下,凭证不能转嫁给用户手工管理。用户负责授权,平台负责托管、隔离、轮换、撤销和审计。 diff --git a/docs/plan.md b/docs/plan.md index 20938fd..173de12 100644 --- a/docs/plan.md +++ b/docs/plan.md @@ -4,6 +4,8 @@ ## P0:边界收敛 +状态:已收敛。当前 `docs/` 只保留 `heicode.md`、`plan.md` 和已上线登录接口文档作为实施依据;旧 Agnet API 草案、旧 M1-M5 计划和旧架构说明不再作为开发输入。 + 目标:让团队只围绕一套产品和架构边界协作。 任务: @@ -31,10 +33,20 @@ - 定义资源元数据、权限范围、约束、状态和审计字段。 - 前端从单点功能页逐步走向“绑定资源 -> 分配角色 -> 部署确认”的主流程。 +最小可验证实现: + +1. 后端先落库资源绑定和 Resource Grant 两类记录,不在本阶段实现 Secret Broker 的真实写入。 +2. Resource Binding 表达租户级资源元数据:资源类型、名称、外部标识、可见元数据、权限范围、约束、状态、`secret_ref` 和审计字段。 +3. Resource Grant 表达项目级授权关系:tenant、project、resource、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