heicode/docs/heicode.md

# Heicode 当前共识

## 一、产品定位

Heicode 的最终形态是一款覆盖软件生命周期的智能开发 Code 工具。

目标用户注册账号后，只需要输入想法，平台逐步完成：

1. 团队生成。
2. 产品文档。
3. 原型描述。
4. 代码开发。
5. 代码检查。
6. 部署到生产并对外提供服务。
7. 后续定期维护和升级。
8. 软件生命周期管理。

一句话：Heicode 是面向全流程智能开发的代码工具，不是 NewAPI 的二次开发项目，也不是单纯的 Agent 控制台。

## 二、系统边界

| 系统 | 定位 | 负责内容 |
|------|------|----------|
| Heicode Manager | SaaS 用户控制台与编排中枢 | 用户输入、资源绑定、权限分配、Agent 部署、审计、模型与余额展示 |
| Agent 平台 | 执行与状态平台 | 在 AKS 上部署子 Agent、运行任务、维护状态、事件、日志和执行元数据 |
| NewAPI | 内部模型网关与计费服务 | 模型渠道、模型调用、额度、余额、调用日志；后台不对普通用户开放 |
| Secret Store | 凭证保管库 | 保存 Git token、云密钥、SSH key、数据库密码等真实凭证 |

Manager 是用户操作入口；Agent 是运行时执行层；NewAPI 是模型能力服务；Secret Store 是安全凭证底座。

## 三、不可破坏的原则

1. 在需求和边界没有想清楚前，不改代码。
2. NewAPI 保持独立服务，不继续改造成 Manager 的内嵌后台。
3. NewAPI 后台不开放给普通 SaaS 用户，模型管理由内部人员完成。
4. Manager 只补 NewAPI 没有的后端能力：用户输入编排、资源绑定、权限、Agent 部署、审计和生命周期管理。
5. 用户绑定的是 Agent 可用资源，不只是 Git 来源。
6. 密钥不能进入 Git、Markdown、前端、部署摘要或日志。
7. Manager 负责资源绑定、权限分配和凭证托管能力；真实密钥放入 Secret Store。
8. 子 Agent 不保存长期密钥，只接收角色、资源元数据、AGENT.md 和受控访问方式。
9. Agent 平台在 AKS 上负责运行时身份、隔离、状态、事件和审计回传。
10. 高危操作审批只在客户端完成；审批通过后可以把密钥保管器派生的短期、最小权限凭证注入子 Agent，但不能注入长期密钥。
11. 子 Agent 的运行模型是 Agent 平台的部署配置，独立于 NewAPI 的用户、Token、Group 扣费映射。

## 四、Manager 的核心功能

1. 绑定 GitHub、GitLab、Gitea、Gitee、自建 Git 等代码来源。
2. 绑定云资源，例如 AWS、Azure、GCP、虚拟机、数据库、对象存储、Kubernetes 集群。
3. 确认项目仓库、SK 仓库、项目文档仓库或二合一仓库。
4. 按敏捷或瀑布方法分配子 Agent 角色。
5. 为每个子 Agent 配置 AGENT.md、可用工具、Git 范围、云资源范围、模型和预算。
6. 部署子 Agent，设置数量、模型和运行环境。
7. 观察子 Agent 活动状态、失败原因、事件和运行日志。
8. 查看审计日志和模型调用日志。
9. 查看可用模型、余额、额度和使用情况。
10. 展示 NewAPI 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。

## 五、资源绑定与密钥托管

绑定不是保存一串密钥，而是创建面向登录用户、绑定 Git/SK/云资源和子 Agent 角色的 Resource Grant。

```text
用户授权 Heicode 使用外部资源
-> Manager 记录资源元数据
-> Manager 的 Secret Broker 把真实凭证写入 Secret Store
-> Manager 生成可审计、可撤销、可分配给子 Agent 的资源授权
```

资源类型：

| 类型 | 示例 | 子 Agent 可见内容 |
|------|------|------------------|
| Git 资源 | GitHub repo、自建 Git、SK repo | repo URL、ref、允许路径、读写范围 |
| 云账号 | Azure subscription、AWS account、GCP project | account/project/subscription 元数据、允许动作 |
| 单项云资源 | VM、DB、Bucket、AKS namespace | 资源 ID、环境、网络边界、允许动作 |
| 项目文档 | 产品文档、原型说明、需求库 | 文档引用、版本、可读范围 |
| SK 资源 | 技能仓库、上传的技能包 | SK 来源、版本、允许/禁止策略 |

Manager 数据库只保存资源元数据、权限关系和 `secret_ref`，不保存明文密钥。

### P1 最小资源模型

P1 只要求 Manager 先具备可验证的资源表达和授权关系，不要求直接接入所有 Secret Provider。真实凭证仍由后续 Secret Broker 写入 Secret Store；P1 数据库只能保存 `secret_ref`。

Resource Binding 建议字段：

| 字段 | 含义 | 约束 |
|------|------|------|
| `id` | 资源绑定 ID | Manager 内部生成 |
| `user_id` | 登录用户 ID | 来自 Heicode/Agent 登录体系的 `user.id` 或 JWT `sub` |
| `type` | 资源类型 | `git`、`sk`、`project_doc`、`cloud_account`、`cloud_resource` |
| `name` | 用户可见名称 | 不包含密钥 |
| `external_ref` | 外部资源定位 | repo URL、subscription ID、resource ID、文档引用等非密钥标识 |
| `metadata` | 子 Agent 可见元数据 | 只包含 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 内部生成 |
| `user_id` / `binding_scope` | 授权归属 | 来自登录用户、绑定 Git/SK/云资源和角色范围 |
| `resource_id` | 被授权资源 | 指向 Resource Binding |
| `role` | 子 Agent 角色 | 例如 product、frontend、backend、reviewer、ops |
| `agent_id` | 子 Agent 标识 | 可为空；为空表示授予该项目角色下的下一次部署 |
| `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
{
  "user_id": "user_demo",
  "binding_scope": "repo_demo:main",
  "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": "azkv://heicode-kv.vault.azure.net/secrets/repo-demo"
    }
  ]
}
```

该 manifest 可以包含 `secret_ref`，但不得包含 Git token、云 access key、SSH 私钥、数据库密码、NewAPI key 或 refresh token 原文。撤销 Resource Grant 后，下一次生成的 manifest 必须移除对应授权。

## 六、开源 Secret Store 方案

SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。

**密钥保管库基线 = Azure Key Vault（`azkv://`）。** 已裁决：统一使用 Azure Key Vault，不使用 OpenBao / HashiCorp Vault；`secret_ref` 一律 `azkv://<vault>/secrets/<name>`，代码强制该前缀（`controller/resource.go`、`agent_approval.go`、`secret_store.go`），不向后兼容 `vault://`。

| 方案 | 判断 |
|------|------|
| **Azure Key Vault** | **采用**。当前 Secret Store 基线；通过 REST + 用户分配托管身份（Managed Identity）访问，`secret_ref` 前缀 `azkv://` |
| HashiCorp Vault / OpenBao | 不采用（历史候选，已弃；代码中无此路径） |
| Infisical | 不采用 |

Secret Broker 负责：

- 接收 OAuth、GitHub App、云授权回调后的凭证。
- 生成按用户、资源和角色隔离的 secret path。
- 写入 Azure Key Vault。
- 创建或更新 policy。
- 保存 `secret_ref` 到 Manager DB。
- 轮换、撤销、禁用凭证。
- 避免密钥进入日志、前端响应、Markdown 和 Git。

## 七、AKS 上的 Agent 凭证访问

Agent 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。

推荐流程：

```text
用户在 Manager 授权资源
-> Manager Secret Broker 写入 Secret Store
-> Manager 记录 Resource Grant
-> Manager 请求 Agent 平台部署
-> Agent 平台为 deployment / role 创建 K8s ServiceAccount
-> Agent 平台绑定 Azure Workload Identity / Managed Identity
-> 子 Agent Pod 运行时只能访问被授权的 secret
```

子 Agent 拿到的是角色、目标、AGENT.md、resource context 和 permission manifest，不拿长期密钥。

运行时访问分两类：

| 模式 | 适用 |
|------|------|
| 受控注入 | Git clone、开发/测试环境、低风险资源 |
| 短期凭证注入 | 已经客户端审批的生产部署、数据库写入、高危云操作 |

普通开发资源可受控注入；生产云资源和高危操作也只在客户端审批通过后，注入密钥保管器派生的短期、最小权限凭证。

## 八、NewAPI 边界

NewAPI 不作为普通用户后台开放。Manager 后端通过服务凭据调用 NewAPI，对用户展示必要信息。

Manager 可展示：

- 可用模型。
- 当前用户、Token 或 Group 额度。
- 余额。
- 调用量。
- 调用日志。
- 失败日志。
- 模型可用状态。

Manager 不展示：

- 渠道管理。
- 模型供应商后台配置。
- 价格配置。
- 系统管理员用户管理。
- NewAPI 原生管理后台入口。

用户登录 Manager，不直接登录 NewAPI。Manager User 复用 Heicode/Agent 登录体系，并维护 `user.id`、`channelId` 到 NewAPI 用户、Token、Group、quota 或 usage 的映射。当前不要把 Manager tenant/project 作为扣费和团队开发控制主轴；团队开发控制优先由绑定 Git、路径范围、资源授权和 Agent 角色表达。子 Agent 的模型选择、模型 profile 和实例数属于 Agent 平台部署配置，不放进 NewAPI 扣费对象里。

## 九、Markdown 与权限清单

绑定的资源最终可以生成 Markdown，但 Markdown 是上下文和规则，不是凭证载体。

Markdown 可包含：

- 子 Agent 角色。
- 目标任务。
- 项目背景。
- AGENT.md 来源。
- 可使用的 Git 资源。
- 可使用的云资源。
- 可使用的 SK。
- 允许和禁止动作。
- 审计要求。

Markdown 不得包含：

- Git token。
- 云 access key。
- refresh token。
- SSH 私钥。
- 数据库密码。
- NewAPI key 原文。

Manager 应生成两类产物：

| 产物 | 用途 |
|------|------|
| AGENT.md / resource context | 给子 Agent 的启动上下文，说明角色和可用资源 |
| permission manifest | 给 Agent 平台和审计系统的结构化权限清单 |

Markdown 面向模型理解，manifest 面向系统强制执行。