xiaohei/heicode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initial import — heicode manager + website

Browse Source
This commit is contained in:
chenchen
2026-05-20 14:07:30 +08:00
commit 2a1d8d8191
2079 changed files with 481382 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/2026-05-02-daily-summary.txt
+147
View File
@@ -0,0 +1,147 @@
Heicode 今日工作总结与后续计划
日期：2026-05-02
工作区：/Volumes/macOS/GO/heicode
分支策略：未新建分支，所有工作均在当前 main 上完成
一、今日完成简介
1. 项目主线梳理
- 已确认 docs/heicode.md 与 docs/plan.md 是当前实施主线。
- 已明确旧 Agnet API 草案、旧 M1-M5 计划、旧架构说明不作为当前实施依据。
- 已恢复 docs/README.md 为主线文档入口，并加入 Agnet 平台请求契约文档入口。
2. P0 文档边界收敛
- 已完成 P0：文档入口与实施依据收敛。
- 已清理 docs 下临时 sync-conflict 文档，当前未发现 docs 目录下残留同步冲突文件。
- 已提交：912e315 docs: converge heicode plan entrypoint。
3. P1 Manager 资源模型最小实现
- 已实现 Manager 侧最小 Resource Binding / Resource Grant 后端能力。
- 新增资源模型：ResourceBinding、ResourceGrant。
- 已加入 GORM 自动迁移。
- 新增认证 API：/api/resources 与 /api/resource-grants。
- 支持的资源类型包括：git、sk、project_document、cloud_account、cloud_resource。
- 资源授权可表达 tenant/project/resource 到 role/子 Agnet 的最小权限关系。
- 已实现 secret_ref-only 原则：只保存密钥引用，不保存明文密钥。
- 已加入校验，拒绝 metadata、permission_scope、constraints 中出现 password、token、secret、private_key、access_key、credential 等明文敏感字段。
4. Agnet 平台请求参数文档
- 已新增文档：docs/integration/agnet-platform-request-contract.md。
- 该文档说明 Manager 主动请求 Agnet 平台时需要携带的参数。
- 覆盖内容包括：
- 创建子 Agent 部署 POST /api/agnet/deployments。
- orchestration_plan、agents、sk_sources、runtime_execution、sk_access_policy、resource_grants 字段说明。
- secret_ref、安全边界、租户/项目边界、预算与模型约束。
- 部署状态查询、停止部署。
- 日志接口：批量日志、实时 SSE 日志流。
- 监控接口：项目 dashboard snapshot、单部署 metrics。
- 事件接口、审计日志接口。
- SK 快照解析与查询接口。
- 已提交：ab71d5b docs: add agnet platform request contract。
5. 团队协作与校验
- 已启动并完成 5 个 OMX worker 的协作任务。
- 5 个 worker 均已完成并关闭，团队已 graceful shutdown。
- 当前 main 分支 ahead origin/main 15 个提交。
- 当前工作区干净。
二、今日验证情况
已通过的校验：
- git diff --check：通过。
- gofmt changed backend files：通过。
- go vet ./controller ./model ./router：通过。
- go test ./controller ./model ./router：通过。
- 重点 controller/model/router 变更包测试：通过。
- docs Markdown fence 检查：通过。
已知未通过但不属于本次改动直接引入的问题：
- go test ./... 存在历史/环境相关失败：
1. heicode 根包 main.go embed 依赖 web/classic/dist，但当前环境缺少该构建产物。
2. relay/channel/claude 相关既有测试失败。
3. relay/helper stream scanner 相关既有测试失败。
- website/frontend typecheck/lint 在部分 worker 环境中因依赖未安装或 bun 不存在无法完整运行。
三、资源使用情况
1. 本地开发资源
- 使用当前外置盘工作区：/Volumes/macOS/GO/heicode。
- 使用 Git 当前 main 分支，无新分支。
- 使用 Go 后端测试、gofmt、go vet 完成验证。
- 使用 OMX team 5 worker 协作完成分析、实现、测试、文档和验证任务。
2. 数据库与缓存资源
- PostgreSQL 与 Redis 被确认为项目运行资源。
- 本次没有把 PostgreSQL、Redis 的真实连接信息写入代码、文档、Git、日志或提交。
- 本次本地验证未直接连接生产 PostgreSQL 或 Redis。
- 后续如需线上验证，应从 VM 环境变量或 Secret Store 临时读取，不应硬编码到仓库。
3. 云与部署资源
- 当前未执行生产 VM SSH 部署。
- 当前未对 Azure PostgreSQL、Redis、AKS 或其他云资源执行写操作。
- 当前未消耗可量化的线上运行资源。
- 本次新增的资源模型与 Agnet 请求契约为后续生产部署和平台联调准备。
4. Git 资源
- 当前 main 相对 origin/main ahead 15 个提交。
- 未新建分支。
- 尚未执行 git push。
- 目标远端仍应使用既有 origin，推送时不得把密码写入 remote URL、命令、脚本或日志。
四、部署情况
1. 当前部署状态
- 代码和文档已在本地 main 完成并提交。
- OMX team 已完成并关闭。
- 尚未推送到远端仓库。
- 尚未 SSH 到生产 VM 执行部署。
- 尚未执行 Docker/服务重启/迁移等生产动作。
2. 当前可部署基础
- P0 文档边界已收敛。
- P1 Manager 资源模型最小后端能力已实现。
- Manager → Agnet 平台接口参数文档已补齐，包含日志和监控接口。
- 变更包 controller/model/router 的测试与 vet 已通过。
3. 部署前阻塞/风险
- 需要确认是否允许将 main 推送到指定 Git 仓库。
- 需要确认生产 VM 当前运行方式、服务名、docker compose 文件与环境变量状态。
- 需要在 VM 上使用现有环境变量读取 PostgreSQL/Redis 配置，禁止写入仓库。
- 需要处理或确认 go test ./... 的既有失败是否影响生产发布。
- 如部署需要前端 embed 产物，需要在部署流程中构建 web/classic/dist 或确认当前生产镜像构建流程会生成该目录。
五、后续需要完成简介
1. Git 同步
- 在不新建分支的前提下，将当前 main 推送到指定远端。
- 推送过程必须使用安全凭据输入方式，不能把密码写入 remote URL、shell history、脚本或日志。
2. 生产部署
- SSH 到生产 VM。
- 在 VM 上通过环境变量确认 PostgreSQL、Redis、Manager 运行配置。
- 使用仓库更新方式拉取当前 main。
- 执行生产构建、数据库迁移、服务重启或 docker compose 更新。
- 部署后检查服务健康、日志、API 可用性。
3. P1 后续完善
- 将 Resource Binding / Resource Grant 与现有项目、用户、Agnet 部署流更紧密打通。
- 完善资源授权 revoke/disable/status transition。
- 补充跨数据库兼容验证，尤其 PostgreSQL 线上迁移验证。
- 补充前端资源绑定与授权页面，避免展示任何 secret。
4. Agnet 平台联调
- 按 docs/integration/agnet-platform-request-contract.md 与 Agnet 平台确认最终字段。
- 联调创建部署、查询状态、停止部署、日志拉取、监控快照、事件、审计日志。
- 明确哪些接口由 Manager 内部提供，哪些接口由 Agnet 平台提供。
- 确认 Agnet 平台对日志和监控返回的脱敏策略。
5. 测试与质量
- 解决或隔离 go test ./... 的既有失败。
- 确保 frontend/web 依赖可安装并完成 typecheck/lint/build。
- 增加 e2e 验证：创建资源 -> 创建授权 -> 创建 Agnet 部署 -> 查询事件/日志/监控。
六、安全说明
- 本次文档和代码未写入任何真实密码、Token、Redis 密钥、PostgreSQL 密码、SSH 密码或 Git 密码。
- 文档示例全部使用占位符或 vault:// secret_ref。
- 后续部署与推送仍需继续遵守：密钥只走环境变量、Secret Store、交互式凭据或平台安全注入，不进入 Git。
docs/README.md
+16
View File
@@ -0,0 +1,16 @@
# Heicode Docs
当前 `docs/` 只保留五类主线文档：
| 文档 | 用途 |
|------|------|
| [`heicode.md`](./heicode.md) | Heicode 当前产品定位、系统边界和架构共识 |
| [`plan.md`](./plan.md) | 按当前共识拆出的实施计划 |
| [`heicode-runtime-auth-newapi-secret-design.md`](./heicode-runtime-auth-newapi-secret-design.md) | 用户输入、登录用户复用、NewAPI 扣费映射、OpenBao 短期凭证注入边界 |
| [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md) | 已上线登录接口对接文档 |
| [`integration/agnet-platform-request-contract.md`](./integration/agnet-platform-request-contract.md) | Manager 请求 Agnet 平台时携带的部署、日志、监控、事件与审计接口参数 |
| [`deployment/azure-production-deploy-guardrails.md`](./deployment/azure-production-deploy-guardrails.md) | Azure VM / PostgreSQL / Redis / Agnet / NewAPI 生产部署前的安全守卫、环境变量注入和验证计划 |
旧 Agnet API 草案、旧里程碑、旧架构说明和旧上手材料不再作为实施依据。后续文档和实现以 `heicode.md` 与 `plan.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。
代码中的过渡期命名、旧接口注释或旧 UI 文案只作为现状参考；若与 `heicode.md` / `plan.md` 冲突，应先更新实现或另行补充当前主线文档，不得恢复旧 Agnet/M1-M5 草案作为依据。
docs/deployment/azure-production-deploy-guardrails.md
+188
View File
@@ -0,0 +1,188 @@
# Azure 生产部署安全守卫与验证计划
本文用于 Heicode Manager / Agnet / NewAPI 相关生产发布前的人工执行检查。它只描述安全命令、环境变量名和验证项，不保存任何真实地址、账号、密码、Token、连接串、SSH key 或云访问密钥。
适用范围：Azure VM、Azure PostgreSQL、Azure Redis、Git 同步、Nginx 统一入口、Heicode Manager 容器、OpenBao 内网密钥保管、Agnet 平台联调、NewAPI 网关能力验证。
## 1. 执行原则
| 项 | 要求 |
|---|---|
| 凭据处理 | 只使用 VM 环境、交互式 SSH、未提交的 `.env`、Key Vault 或 `secret_ref`；禁止把真实密钥写入 Git、Markdown、终端报告或 team state。 |
| Git 发布 | 仅允许快进同步已审核提交；禁止在生产 VM 上提交代码或保存临时补丁。 |
| 数据库/Redis | Azure PostgreSQL / Redis 连接串只写入 VM 本地 `.env` 或 Secret Store；验证时只打印变量名和连通性结果，不打印值。 |
| Agnet / NewAPI | Manager 只传 `secret_ref`、部署计划、资源授权和审计上下文；禁止把明文云账号、数据库密码、模型 Key 放入请求体。 |
| OpenBao | 只允许 Manager/Agnet 受控网络访问；如果 Manager 提供客户端验证和绑定接口，OpenBao 不暴露公网路由。 |
| 生产动作 | 执行 `up -d`、迁移、重启、回滚前必须记录当前镜像/提交和健康检查 URL；失败时停止扩大变更。 |
## 2. 本地发布前检查
在本地工作区执行，确认没有未提交变更和明文凭据：
```bash
git status --short
git diff --check
# 只允许命中占位符、变量名或文档中的禁用词说明；若命中真实值，立即停止。
grep -RIn --exclude-dir=.git --exclude-dir=node_modules --exclude='*.jpg' \
-E '(password|passwd|token|secret|private_key|access_key|credential|SQL_DSN|REDIS_CONN_STRING)' \
docs heicode/bin heicode/docker-compose.azure-vm.yml
```
预期：
- `git status --short` 只显示准备发布的已审核文档/代码变更。
- `git diff --check` 无输出。
- `grep` 结果不包含真实凭据；只允许出现 `secret_ref`、环境变量名、占位符或安全规则说明。
## 3. Git 同步守卫
在生产 VM 上只执行快进同步，避免产生生产端漂移：
```bash
export VM_HOST='<azure-vm-host-or-ip>'
export VM_USER='<ssh-user>'
export REMOTE_DIR='/opt/heicode'
export REMOTE="${VM_USER}@${VM_HOST}"
ssh "$REMOTE" "cd '$REMOTE_DIR' && git status --short"
ssh "$REMOTE" "cd '$REMOTE_DIR' && git fetch --all --prune"
ssh "$REMOTE" "cd '$REMOTE_DIR' && git merge --ff-only origin/main"
ssh "$REMOTE" "cd '$REMOTE_DIR' && git rev-parse --short HEAD"
```
若 `git status --short` 非空，先停止部署并人工判断；不要在 VM 上直接 `git reset --hard`，除非已有明确回滚授权。
## 4. VM 本地 `.env` 注入
真实连接串只能进入 VM 本地未提交 `.env` 或 Secret Store。推荐用交互式编辑器写入，不在命令行参数中携带值：
```bash
ssh -t "$REMOTE" "cd '$REMOTE_DIR/heicode' && umask 077 && \${EDITOR:-vi} .env"
```
`.env` 至少应包含以下键，值由运维在交互式 SSH 会话中填入：
```text
SQL_DSN=<azure-postgresql-connection-string>
REDIS_CONN_STRING=<azure-redis-connection-string>
SESSION_SECRET=<generated-session-secret>
HEICODE_ROOT_EMAILS=<comma-separated-root-emails-if-needed>
HEICODE_ADMIN_EMAILS=<comma-separated-admin-emails-if-needed>
```
验证只打印 key，不打印 value：
```bash
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && test -f .env && chmod 600 .env && awk -F= '/^[A-Z0-9_]+=/{print \$1}' .env | sort"
```
## 5. Azure PostgreSQL / Redis 连通性验证
优先通过应用容器的健康检查间接验证。若必须直接验证，只输出成功/失败：
```bash
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && docker compose -f docker-compose.azure-vm.yml --env-file .env config --services"
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && docker compose -f docker-compose.azure-vm.yml --env-file .env run --rm heicode sh -lc 'test -n \"\$SQL_DSN\" && test -n \"\$REDIS_CONN_STRING\" && echo env-present'"
```
禁止执行会打印完整环境的命令，例如 `env`、`printenv`、`docker inspect` 全量输出或 `docker compose config` 全量输出。
## 6. Heicode Manager / NewAPI 容器部署
当前仓库的 Heicode 服务保留 NewAPI 网关能力；生产部署以 `heicode/docker-compose.azure-vm.yml` 为入口，PostgreSQL / Redis 使用 Azure 托管实例。
公网入口约定：
- 对外域名统一使用 `heicode.xinghanlab.com`。
- Nginx 负责按路由转发 Manager 与 NewAPI，例如 Manager 主站、NewAPI 受控 API 或健康检查路由。
- OpenBao 仅供 Manager/Agnet 服务端访问，不通过 `heicode.xinghanlab.com` 暴露给浏览器用户。
- 若需要 OpenBao 运维 UI，也必须走临时 SSH tunnel、VPN、内网跳板或单独受保护管理入口，不走普通 SaaS 用户路由。
构建和启动：
```bash
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && docker compose -f docker-compose.azure-vm.yml --env-file .env build heicode"
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && docker compose -f docker-compose.azure-vm.yml --env-file .env up -d heicode"
```
健康检查：
```bash
ssh "$REMOTE" "curl -fsS http://127.0.0.1:3000/api/status | grep -q '\"success\":true' && echo heicode-health-ok"
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && docker compose -f docker-compose.azure-vm.yml --env-file .env ps heicode"
```
如使用现有脚本，仍需通过环境变量传参，不在命令里写真实凭据：
```bash
VM_HOST="$VM_HOST" VM_USER="$VM_USER" REMOTE_DIR="$REMOTE_DIR/heicode" \
IMAGE_TAG='heicode-manager:local' HEALTH_URL='http://127.0.0.1:3000/api/status' \
./heicode/bin/azure_vm_deploy.sh
```
## 7. Agnet 平台联调守卫
Manager 请求 Agnet 平台时遵循 `docs/integration/agnet-platform-request-contract.md`：
- `resource_grants[].secret_ref` 必须是 Secret Store 引用，不能是明文密钥。
- `repo_url` 不能包含用户名、密码或 Token。
- `metadata`、`constraints`、`audit` 的 key 和 value 都需要脱敏检查。
- 高风险部署设置 `risk_level=high`，并保留审批或人工确认记录。
安全 smoke request 模板：
```bash
export AGNET_BASE_URL='<agnet-platform-base-url>'
export MANAGER_SERVICE_TOKEN_SECRET_REF='<secret-ref-only>'
export USER_ID='<manager-user-id>'
export BINDING_SCOPE='<resource-binding-scope>'
# 真实 token 由运行环境注入；禁止把 token 字面值写入命令历史或文档。
curl -fsS -X POST "$AGNET_BASE_URL/api/agnet/deployments" \
-H 'Content-Type: application/json' \
-H "X-User-Id: $USER_ID" \
-H "X-Binding-Scope: $BINDING_SCOPE" \
-H "Idempotency-Key: deploy-$(date +%Y%m%d%H%M%S)" \
-H "Authorization: Bearer $MANAGER_SERVICE_TOKEN" \
--data @docs/integration/safe-agnet-deploy-example.json
```
若没有 `safe-agnet-deploy-example.json`，先用本地临时文件生成并确认只包含 `secret_ref`，不要提交包含环境特定值的 payload。
## 8. 发布后验证清单
| 验证项 | 安全命令 | 通过标准 |
|---|---|---|
| 服务健康 | `curl -fsS http://127.0.0.1:3000/api/status` | 返回 `success=true`。 |
| Nginx 公网入口 | `curl -fsS https://heicode.xinghanlab.com/api/status` | 返回 Manager 健康状态；DNS 需解析到生产入口。 |
| OpenBao 暴露面 | `curl -fsSI https://heicode.xinghanlab.com/v1/sys/health` | 普通公网入口不应返回 OpenBao 健康信息；预期为无路由、403 或 404。 |
| 容器状态 | `docker compose ... ps heicode` | `heicode` 为 running/healthy。 |
| Git 版本 | `git rev-parse --short HEAD` | 与已审核提交一致。 |
| DB/Redis 注入 | `awk -F= ... .env` | 只打印 key，包含 `SQL_DSN`、`REDIS_CONN_STRING`。 |
| 登录链路 | 调用登录文档中的生产验证流程 | 不在日志或报告输出 token。 |
| Agnet 部署 | 查询部署状态/事件/审计接口 | 能看到 deployment、events、audit，且无明文凭据。 |
| NewAPI 网关能力 | 使用 Manager 受控模型调用或健康接口 | 只记录 request id、状态码、模型名，不记录 provider key。 |
## 9. 回滚与停止条件
立即停止部署并进入回滚/人工排障的条件：
1. 任一日志、响应、Markdown 或 Git diff 中出现真实密钥。
2. `git merge --ff-only` 失败或 VM 工作区有未知改动。
3. 健康检查连续失败。
4. Agnet 平台返回的事件/审计中包含明文凭据。
5. 数据库迁移或容器启动错误无法在一次重试内恢复。
回滚指针：
```bash
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && cat .last_success_image 2>/dev/null || true"
ssh "$REMOTE" "cd '$REMOTE_DIR/heicode' && IMAGE_TAG=\$(cat .last_success_image) docker compose -f docker-compose.azure-vm.yml --env-file .env up -d heicode"
```
若 `.last_success_image` 为空，回滚到上一个已验证 Git commit，并重新执行健康检查。
## 10. 本次文档产物状态
本文件仅准备部署守卫和验证计划；未执行 Git push、SSH 登录、Azure 资源变更、生产容器重启或 Agnet 实际部署。
docs/heicode-runtime-auth-newapi-secret-design.md
+206
View File
@@ -0,0 +1,206 @@
# Heicode 运行时认证、扣费与密钥设计
日期：2026-05-04
本文修正 Manager、Agnet 平台、NewAPI 与 OpenBao 之间的运行时边界。若本文与旧文档中 `tenant`、`project` 或平台侧批准描述冲突，以本文为准。
## 一、用户输入在哪里
用户输入发生在 Heicode 的用户侧入口，也就是 Manager/客户端的“想法输入”主流程。
用户登录后输入目标、需求、约束、绑定的 Git/SK/云资源选择，以及是否批准高危操作。Manager 负责把这些输入整理成 Agnet 平台可执行的 work request：
- 用户想法和自然语言需求。
- 绑定的 Git 仓库、分支、路径范围和写入权限。
- 绑定的 SK 仓库或技能包。
- 绑定的云资源元数据和允许动作。
- 子 Agnet 角色、数量、运行模型和预算限制。
- 客户端已经确认的高危操作审批结果。
Manager 不应为了团队开发控制额外发明 `tenant/project` 产品概念。当前团队开发边界优先来自绑定的 Git 仓库、允许路径、分支策略、Agnet 角色和资源授权。
## 二、Manager 用户复用 Agnet 登录体系
Manager User 应复用 Heicode/Agnet 已上线登录体系，不再另建一套独立身份。
参考 [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md)，登录流程已经提供：
- `POST /api/auth/login`
- `GET /api/auth/me`
- `POST /api/auth/refresh`
- `POST /api/auth/logout`
登录返回的用户对象包含：
- `id`
- `name`
- `email`
- `role`
- `channelId`
JWT 中也包含：
- `sub`
- `email`
- `role`
- `channelId`
- `type`
- `iat`
- `exp`
因此 Manager 的认证设计应是：
```text
用户登录 Heicode/Agnet 认证体系
-> Manager 校验 token 并读取 /api/auth/me
-> Manager 使用 user.id / sub 作为业务用户 ID
-> Manager 使用 channelId 关联 NewAPI 余额、用量和扣费查询
-> Manager 本地只保存必要的用户会话、资源绑定和审计数据
```
Manager 可以有本地 user cache，但 canonical user identity 应来自登录接口返回的用户信息。除非未来产品明确引入企业组织、空间或项目账本，否则不要把 tenant/project 作为认证和扣费主轴。
## 三、高危操作审批与 OpenBao 密钥注入
高危操作审批只在客户端完成。用户在客户端明确批准后，Manager/Agnet 平台才可以执行对应动作。Agnet 平台不是审批主体，不发起额外审批；它只校验 `approval_id`、审批主体、审批范围、TTL、`risk_level` 和策略是否匹配。
密钥处理边界如下：
```text
长期密钥
-> 用户授权或绑定资源
-> Manager 写入 OpenBao
-> Manager DB 只保存 secret_ref
-> OpenBao 只允许 Manager/Agnet 受控网络访问，不对公网暴露
高危操作
-> 客户端审批
-> Manager/Agnet 平台按 secret_ref 从 OpenBao 获取或派生短期凭证
-> 短期凭证可注入子 Agnet
-> 子 Agnet 完成任务后凭证过期或撤销
```
允许注入子 Agnet 的只能是短期、最小权限、可审计的凭证。长期 Git token、云 access key、SSH 私钥、数据库密码、NewAPI key 原文不得进入 Git、Markdown、普通日志或长期 Agnet 状态。
公网入口边界：
- `heicode.xinghanlab.com` 是 Manager、NewAPI 与内部服务的统一公网域名入口。
- Nginx 可以为 Manager 和 NewAPI 制定路由，例如 Manager 主站与 NewAPI 受控 API 路由。
- OpenBao 不应作为普通公网路由开放；如果 Manager 已经提供客户端验证、资源绑定、审批和 `secret_ref` 管理接口，客户端不需要直连 OpenBao。
- OpenBao 访问应限制在容器网络、VM loopback、AKS 内网、Workload Identity 或其它受保护服务间通道。
OpenBao 不暴露公网的检查口径：
- 公网 DNS、Nginx `server_name`、Ingress、LoadBalancer 和安全组规则不得直接指向 OpenBao 服务端口。
- 外部客户端只能通过 Manager 的认证、资源绑定、审批和 `secret_ref` 管理接口间接操作密钥引用。
- Manager、Agnet 平台和子 Agnet 访问 OpenBao 时必须走内网地址、loopback、容器网络、AKS private endpoint 或 Workload Identity 绑定。
- 健康检查和联调报告只能证明内网访问可用；不得把公网可访问的 OpenBao health endpoint 作为验收口径。
短期凭证注入必须满足：
- 有客户端审批记录。
- 有 `secret_ref` 来源。
- 有 TTL 或明确撤销机制。
- 有资源范围、路径范围、云资源范围或 API 范围限制。
- 有 Agnet deployment、agent role、user id、操作类型的审计记录。
## 四、NewAPI 额度与扣费能力
公开 NewAPI 文档当前体现的是用户、Token、Group、余额和用量视角，而不是 Manager `tenant/project` 视角。
NewAPI 官方 skill 文档明确支持：
- 查询模型。
- 查询用户 Group。
- 查询账号余额。
- 管理 API Token。
- 创建 Token 并指定 Group。
- 切换 Token Group。
- Token 安全复制和注入。
因此当前结论是：
1. NewAPI 可以承担模型网关和用户/Token/Group 维度的额度、余额、用量、日志能力。
2. Manager 不应假设 NewAPI 已有 Heicode tenant/project 额度。
3. Manager 普通用户侧展示应围绕当前登录用户的模型可用性、余额、额度、调用量和调用日志。
4. 扣费映射应优先使用 `channelId`、NewAPI user、NewAPI token 或 NewAPI group。
5. 若未来需要团队、组织、项目维度账本，应作为独立产品决策重新设计，而不是在当前 Manager 里暗自添加。
6. 子 Agnet 的运行模型是 Agnet 平台的部署配置，独立于 NewAPI 的用户、Token、Group 扣费映射；NewAPI 不负责决定子 Agnet 使用哪个模型。
推荐映射：
| Heicode/Agnet 字段 | NewAPI 映射 | 用途 |
|------|------|------|
| `user.id` / JWT `sub` | NewAPI user ref | 标识调用归属用户 |
| `channelId` | NewAPI channel/user/group 绑定 | 关联模型渠道、额度或扣费策略 |
| 绑定 Git 仓库 | request metadata | 审计某次开发任务来源 |
| 预算或用量限制 | token quota 或 group policy | 限制本次任务可消耗额度 |
子 Agnet 角色、运行模型和实例数量应放在 Agnet 平台 deployment/runtime 配置里，不放进 NewAPI 扣费对象里。
## 五、传给 Agnet 平台的用户与扣费上下文
Manager 请求 Agnet 平台部署或执行任务时，应携带登录用户上下文，但不携带真实密钥。
建议传递结构：
```json
{
"request_id": "req_20260504_demo",
"user_context": {
"user_id": "123",
"email": "user@example.com",
"role": "user",
"channel_id": "channel_abc",
"subscription_tier": "pro"
},
"billing_context": {
"provider": "newapi",
"newapi_user_ref": "newapi_user_123",
"newapi_group": "development",
"quota_ref": "newapi_token_or_group_quota_ref"
},
"agent_runtime": {
"platform": "agnet",
"agents": [
{
"role": "backend",
"model_ref": "agnet_model_profile_backend",
"instance_count": 1
}
]
},
"work_context": {
"input": "用户输入的产品想法或任务目标",
"git_bindings": [
{
"resource_id": "res_git_1",
"repo_url": "https://example.com/org/repo.git",
"ref": "main",
"allowed_paths": ["services/**"],
"allowed_actions": ["read", "write"]
}
]
},
"secret_context": {
"secret_refs": ["vault://secret/resources/res_git_1"],
"inject_short_lived_credentials": true,
"approval_id": "approval_123"
}
}
```
这里的 `user_context` 用于确认身份，`billing_context` 用于 NewAPI 余额、用量和扣费映射，`agent_runtime` 用于 Agnet 平台独立选择子 Agnet 模型和实例数量，`work_context` 用于团队开发控制，`secret_context` 只传 `secret_ref` 和审批结果。
Agnet 平台执行时，应把用户、角色、Git 绑定、deployment、Agnet model profile 和 NewAPI 映射写入 metadata 或审计日志。真实 NewAPI key 和 OpenBao 凭证由平台安全通道读取，不进入 Markdown。
## 六、当前主线结论
- 用户输入在 Manager/客户端，不在 NewAPI 后台。
- Manager User 复用 Heicode/Agnet 登录体系。
- Manager 不自行发明 tenant/project 作为当前团队或扣费边界。
- 团队开发控制优先由绑定 Git、允许路径、Agnet 角色、资源授权表达。
- 子 Agnet 的运行模型由 Agnet 平台独立配置，不和 NewAPI 扣费对象混在一起。
- NewAPI 负责模型网关、用户/Token/Group 额度、余额、日志和扣费。
- OpenBao 负责长期密钥托管，子 Agnet 只拿短期、最小权限、可审计凭证。
- 高危操作审批发生在客户端，审批结果随任务上下文传给 Manager/Agnet 平台。
docs/heicode.md
+246
View File
@@ -0,0 +1,246 @@
# Heicode 当前共识
## 一、产品定位
Heicode 的最终形态是一款覆盖软件生命周期的智能开发 Code 工具。
目标用户注册账号后，只需要输入想法，平台逐步完成：
1. 团队生成。
2. 产品文档。
3. 原型描述。
4. 代码开发。
5. 代码检查。
6. 部署到生产并对外提供服务。
7. 后续定期维护和升级。
8. 软件生命周期管理。
一句话：Heicode 是面向全流程智能开发的代码工具，不是 NewAPI 的二次开发项目，也不是单纯的 Agent 控制台。
## 二、系统边界
| 系统 | 定位 | 负责内容 |
|------|------|----------|
| Heicode Manager | SaaS 用户控制台与编排中枢 | 用户输入、资源绑定、权限分配、Agnet 部署、审计、模型与余额展示 |
| Agnet 平台 | 执行与状态平台 | 在 AKS 上部署子 Agnet、运行任务、维护状态、事件、日志和执行元数据 |
| NewAPI | 内部模型网关与计费服务 | 模型渠道、模型调用、额度、余额、调用日志；后台不对普通用户开放 |
| Secret Store | 凭证保管库 | 保存 Git token、云密钥、SSH key、数据库密码等真实凭证 |
Manager 是用户操作入口；Agnet 是运行时执行层；NewAPI 是模型能力服务；Secret Store 是安全凭证底座。
## 三、不可破坏的原则
1. 在需求和边界没有想清楚前，不改代码。
2. NewAPI 保持独立服务，不继续改造成 Manager 的内嵌后台。
3. NewAPI 后台不开放给普通 SaaS 用户，模型管理由内部人员完成。
4. Manager 只补 NewAPI 没有的后端能力：用户输入编排、资源绑定、权限、Agnet 部署、审计和生命周期管理。
5. 用户绑定的是 Agnet 可用资源，不只是 Git 来源。
6. 密钥不能进入 Git、Markdown、前端、部署摘要或日志。
7. Manager 负责资源绑定、权限分配和凭证托管能力；真实密钥放入 Secret Store。
8. 子 Agnet 不保存长期密钥，只接收角色、资源元数据、AGENT.md 和受控访问方式。
9. Agnet 平台在 AKS 上负责运行时身份、隔离、状态、事件和审计回传。
10. 高危操作审批只在客户端完成；审批通过后可以把 OpenBao 派生的短期、最小权限凭证注入子 Agnet，但不能注入长期密钥。
11. 子 Agnet 的运行模型是 Agnet 平台的部署配置，独立于 NewAPI 的用户、Token、Group 扣费映射。
## 四、Manager 的核心功能
1. 绑定 GitHub、GitLab、Gitea、Gitee、自建 Git 等代码来源。
2. 绑定云资源，例如 AWS、Azure、GCP、虚拟机、数据库、对象存储、Kubernetes 集群。
3. 确认项目仓库、SK 仓库、项目文档仓库或二合一仓库。
4. 按敏捷或瀑布方法分配子 Agnet 角色。
5. 为每个子 Agnet 配置 AGENT.md、可用工具、Git 范围、云资源范围、模型和预算。
6. 部署子 Agnet，设置数量、模型和运行环境。
7. 观察子 Agnet 活动状态、失败原因、事件和运行日志。
8. 查看审计日志和模型调用日志。
9. 查看可用模型、余额、额度和使用情况。
10. 展示 NewAPI 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。
## 五、资源绑定与密钥托管
绑定不是保存一串密钥，而是创建面向登录用户、绑定 Git/SK/云资源和子 Agnet 角色的 Resource Grant。
```text
用户授权 Heicode 使用外部资源
-> Manager 记录资源元数据
-> Manager 的 Secret Broker 把真实凭证写入 Secret Store
-> Manager 生成可审计、可撤销、可分配给子 Agnet 的资源授权
```
资源类型：
| 类型 | 示例 | 子 Agnet 可见内容 |
|------|------|------------------|
| 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/Agnet 登录体系的 `user.id` 或 JWT `sub` |
| `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 内部生成 |
| `user_id` / `binding_scope` | 授权归属 | 来自登录用户、绑定 Git/SK/云资源和角色范围 |
| `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
{
"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": "vault://secret/resources/repo_demo"
}
]
}
```
该 manifest 可以包含 `secret_ref`，但不得包含 Git token、云 access key、SSH 私钥、数据库密码、NewAPI key 或 refresh token 原文。撤销 Resource Grant 后，下一次生成的 manifest 必须移除对应授权。
## 六、开源 Secret Store 方案
SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。
优先方案：
| 方案 | 判断 |
|------|------|
| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 |
| Infisical | 可选方案。产品体验较好，但需要验证 SaaS 多用户隔离策略和运行时授权能力 |
| Azure Key Vault | 适合 Azure 优先部署，也可以作为 Secret Provider 的一种实现 |
Secret Broker 负责：
- 接收 OAuth、GitHub App、云授权回调后的凭证。
- 生成按用户、资源和角色隔离的 secret path。
- 写入 Vault、Infisical 或 Azure Key Vault。
- 创建或更新 policy。
- 保存 `secret_ref` 到 Manager DB。
- 轮换、撤销、禁用凭证。
- 避免密钥进入日志、前端响应、Markdown 和 Git。
## 七、AKS 上的 Agnet 凭证访问
Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。
推荐流程：
```text
用户在 Manager 授权资源
-> Manager Secret Broker 写入 Secret Store
-> Manager 记录 Resource Grant
-> Manager 请求 Agnet 平台部署
-> Agnet 平台为 deployment / role 创建 K8s ServiceAccount
-> Agnet 平台绑定 Vault policy 或 Workload Identity
-> 子 Agnet Pod 运行时只能访问被授权的 secret
```
子 Agnet 拿到的是角色、目标、AGENT.md、resource context 和 permission manifest，不拿长期密钥。
运行时访问分两类：
| 模式 | 适用 |
|------|------|
| 受控注入 | Git clone、开发/测试环境、低风险资源 |
| 短期凭证注入 | 已经客户端审批的生产部署、数据库写入、高危云操作 |
普通开发资源可受控注入；生产云资源和高危操作也只在客户端审批通过后，注入 OpenBao 派生的短期、最小权限凭证。
## 八、NewAPI 边界
NewAPI 不作为普通用户后台开放。Manager 后端通过服务凭据调用 NewAPI，对用户展示必要信息。
Manager 可展示：
- 可用模型。
- 当前用户、Token 或 Group 额度。
- 余额。
- 调用量。
- 调用日志。
- 失败日志。
- 模型可用状态。
Manager 不展示：
- 渠道管理。
- 模型供应商后台配置。
- 价格配置。
- 系统管理员用户管理。
- NewAPI 原生管理后台入口。
用户登录 Manager，不直接登录 NewAPI。Manager User 复用 Heicode/Agnet 登录体系，并维护 `user.id`、`channelId` 到 NewAPI 用户、Token、Group、quota 或 usage 的映射。当前不要把 Manager tenant/project 作为扣费和团队开发控制主轴；团队开发控制优先由绑定 Git、路径范围、资源授权和 Agnet 角色表达。子 Agnet 的模型选择、模型 profile 和实例数属于 Agnet 平台部署配置，不放进 NewAPI 扣费对象里。
## 九、Markdown 与权限清单
绑定的资源最终可以生成 Markdown，但 Markdown 是上下文和规则，不是凭证载体。
Markdown 可包含：
- 子 Agnet 角色。
- 目标任务。
- 项目背景。
- AGENT.md 来源。
- 可使用的 Git 资源。
- 可使用的云资源。
- 可使用的 SK。
- 允许和禁止动作。
- 审计要求。
Markdown 不得包含：
- Git token。
- 云 access key。
- refresh token。
- SSH 私钥。
- 数据库密码。
- NewAPI key 原文。
Manager 应生成两类产物：
| 产物 | 用途 |
|------|------|
| AGENT.md / resource context | 给子 Agnet 的启动上下文，说明角色和可用资源 |
| permission manifest | 给 Agnet 平台和审计系统的结构化权限清单 |
Markdown 面向模型理解，manifest 面向系统强制执行。
docs/images/wecom-screenshot-01.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

docs/images/wecom-screenshot-02.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 KiB

docs/images/wecom-screenshot-03.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

docs/images/wecom-screenshot-04.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 75 KiB

docs/images/wecom-screenshot-05.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

docs/images/wecom-screenshot-06.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

docs/integration/Heicode-登录接口对接文档.md
+372
View File
@@ -0,0 +1,372 @@
# Heicode 客户端 — 登录接口对接文档
**版本**: v1.0
**生效日期**: 2026-04-30
**状态**: 已上线生产，已通过端到端测试
---
## 1. 概述
本文档描述 Heicode 客户端（桌面/CLI）与 Heicode Manager（即 mcp-server）之间的**登录认证接口**。共 4 个接口，覆盖完整登录生命周期：
| 接口 | 用途 |
| ------------------------ | ----------------------- |
| `POST /api/auth/login` | 账号密码登录，换取 token |
| `GET /api/auth/me` | 校验 token 有效性 + 获取当前用户资料 |
| `POST /api/auth/refresh` | access token 过期时换新的 |
| `POST /api/auth/logout` | 登出（token 加入黑名单） |
> 不在本期范围：注册、找回密码、改密码 — 这些走官网 web 端完成。
---
## 2. 接入信息
### 2.1 Base URL
生产环境通过 Azure APIM 网关接入：
```
https://apimtaiji.azure-api.net/api/mcp
```
完整路径示例：
```
POST https://apimtaiji.azure-api.net/api/mcp/api/auth/login
```
### 2.2 通用请求头
| Header | 必填 | 说明 |
| -------------------------------- | ----------- | -------------- |
| `Content-Type: application/json` | 是（POST/PUT） | 请求体 JSON |
| `Authorization: Bearer <token>` | 受保护接口必填 | 见 §3 |
| `X-Request-Id: <uuid>` | 建议 | 全链路追踪 ID，客户端生成 |
### 2.3 Token 模型
登录成功返回两个 token：
| Token | 用途 | 有效期 |
| ----------------- | ------------------------ | ----- |
| **Access Token** | 调业务接口（含 `/me`、`/logout`） | 24 小时 |
| **Refresh Token** | 仅用于 `/refresh` 换新 access | 7 天 |
JWT claims 包含：`sub`（user_id）、`email`、`role`、`channelId`、`type`（access/refresh）、`iat`、`exp`。
---
## 3. 接口详情
### 3.1 POST /api/auth/login — 登录
**请求**
```http
POST /api/auth/login HTTP/1.1
Content-Type: application/json
{
"email": "user@example.com",
"password": "YourPassword123",
"role": "user"
}
```
字段：
- `email` (string, 必填)
- `password` (string, 必填)
- `role` (string, 必填)：Heicode 客户端**固定传 `"user"`**
**成功响应 200**
```json
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "b00a7b8e-9e8b-463d-9593-a3b4d0006778",
"name": "张三",
"email": "user@example.com",
"role": "user",
"channelId": "6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6"
}
}
}
```
**错误响应**
| HTTP | 含义 | 客户端处理建议 |
| ---- | ------------------------- | -------------------------------- |
| 401 | 邮箱或密码错误 | 显示"账号或密码错误"，让用户重新输入 |
| 403 | 账户已被禁用 | 提示用户联系管理员 |
| 429 | 登录尝试过于频繁（**每 IP 5 次/分钟**） | 显示倒计时；响应头 `Retry-After: 60` 表示秒数 |
| 422 | 请求体校验失败（邮箱格式不合法等） | 检查 `detail` 字段 |
| 500 | 服务异常 | 重试或提示稍后再试 |
**重要：限流规则**
- **每 IP 每分钟最多 5 次**登录尝试（不区分成功失败）
- 超出返回 **429 Too Many Requests**，含 `Retry-After` 头（秒）
- 计数滑动窗口，60 秒后自动恢复
---
### 3.2 GET /api/auth/me — 获取当前用户
客户端**启动时**应调用此接口校验本地缓存的 access token 是否仍有效，并刷新用户信息。
**请求**
```http
GET /api/auth/me HTTP/1.1
Authorization: Bearer <accessToken>
```
**成功响应 200**
```json
{
"success": true,
"data": {
"id": "b00a7b8e-9e8b-463d-9593-a3b4d0006778",
"email": "user@example.com",
"name": "张三",
"role": "user",
"channelId": "6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6",
"status": "active",
"subscriptionTier": "free",
"lastLoginAt": "2026-04-30T06:38:14.765457"
}
}
```
**错误响应**
| HTTP | 含义 | 客户端处理建议 |
| ---- | --------------------- | ------------------------------------------ |
| 401 | Token 无效/过期/已登出/用户不存在 | 调 `/refresh` 换新 token；若 refresh 也 401，跳登录页 |
| 403 | 账户已被禁用 | 强制登出，提示联系管理员 |
---
### 3.3 POST /api/auth/refresh — 刷新 token
access token 接近或已过期时调用，使用 **refresh token** 换取新的 access + refresh token 对。
**请求**
```http
POST /api/auth/refresh HTTP/1.1
Authorization: Bearer <refreshToken>
```
> ⚠️ **必须传 refresh token**，传 access token 会被拒绝。
**成功响应 200**
```json
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
}
```
客户端收到新的 token 对后**应替换本地缓存**（包括 refresh token，旧的也作废）。
**错误响应**
| HTTP | 含义 | 客户端处理建议 |
| ---- | ---------------------------------------- | ------- |
| 401 | refresh token 无效 / 过期 / 错传了 access token | 跳登录页 |
实施细节：
- 服务端会校验 token claims `type == "refresh"`，否则拒绝
- 旧 refresh token 不会被立即吊销（容许并发换发期），但客户端应丢弃旧的
---
### 3.4 POST /api/auth/logout — 登出
将当前 access token 加入黑名单，使其立即失效。
**请求**
```http
POST /api/auth/logout HTTP/1.1
Authorization: Bearer <accessToken>
```
**成功响应 200**
```json
{
"success": true,
"data": null,
"message": "登出成功"
}
```
**错误响应**
logout 容错性较强，token 黑名单写入失败也会返回 200（前端清理本地 token 即可）。
**客户端登出流程**：
1. 调 `/api/auth/logout`
2. 清除本地存储的 access + refresh token
3. 清除当前用户资料缓存
4. 跳转到登录页
---
## 4. 完整登录流程（示例）
### 启动时
```
┌─ 本地有 access token ?
│
├─ 是 ─→ GET /me
│ ├─ 200 ─→ 进入主界面
│ └─ 401 ─→ 本地有 refresh token ?
│ ├─ 是 ─→ POST /refresh
│ │ ├─ 200 ─→ 替换 token，进入主界面
│ │ └─ 401 ─→ 跳登录页
│ └─ 否 ─→ 跳登录页
│
└─ 否 ─→ 跳登录页
```
### 登录页提交
```
POST /login
├─ 200 ─→ 存 token 对，进主界面
├─ 401 ─→ 显示"账号或密码错误"
├─ 429 ─→ 显示"尝试过于频繁，请 N 秒后重试"（N 取响应头 Retry-After）
└─ 其他 ─→ 显示通用错误
```
### 业务请求过程中 access token 过期
```
任意业务接口返回 401
└─→ POST /refresh (用 refresh token)
├─ 200 ─→ 替换 token，重试原请求
└─ 401 ─→ 清理 token，跳登录页
```
### 登出按钮
```
POST /logout
└─→ 不论结果都清理本地 token，跳登录页
```
---
## 5. 错误响应格式
当前为 FastAPI 默认格式（下个版本 `/api/v1/*` 路径会改为标准 envelope，本期保留兼容）：
```json
{
"detail": "邮箱或密码错误"
}
```
422 校验错误格式（Pydantic）：
```json
{
"detail": [
{
"type": "value_error",
"loc": ["body", "email"],
"msg": "value is not a valid email address: ...",
"input": "abc"
}
]
}
```
---
## 6. 安全注意事项
| 项 | 说明 |
| -------------- | -------------------------------------------------------------------------------------- |
| **token 存储** | 桌面应用建议存到 OS 安全凭据存储（Windows Credential Manager / macOS Keychain / Linux Secret Service） |
| **HTTPS 强制** | 生产 base URL 已是 HTTPS；客户端**禁止**回退 HTTP |
| **token 泄露应对** | 用户怀疑泄露时提示去官网 web 端改密码（改密会导致所有 session 黑名单） |
| **审计日志** | 所有 login 尝试（成功/失败）服务端均写审计 |
| **状态码不泄漏** | 错误信息已统一用"邮箱或密码错误"，不区分账号是否存在，防爆破 |
---
## 7. 测试账号（仅供联调）
| 角色 | 邮箱 | 密码 |
| ---- | ----------- | ------------ |
| 普通用户 | `55@55.com` | `By@123456.` |
> ⚠️ 测试账号仅用于联调阶段，正式上线前请务必关闭。
---
## 8. 已上线生产验证清单
| 测试项 | 结果 |
| ------------------------------------------ | --- |
| login 200 + 返回 access/refresh token | ✅ |
| /me 用 access token → 200 + 完整 profile | ✅ |
| /refresh 用 refresh token → 200 + 新 token 对 | ✅ |
| /refresh 用 access token → 401 拒绝 | ✅ |
| logout → 200 | ✅ |
| logout 后旧 token 调 /me → 401（黑名单生效） | ✅ |
| 连续 7 次错密 → 第 6 次起 429（每 IP 5/min 限流） | ✅ |
| 服务器审计日志记录所有 login（含成功/失败） | ✅ |
镜像 digest: `sha256:339b64ae090dc81fa13cb29705958167e77fe0698e27ac227c05054ed5c42309`
镜像 tag: `taiji.azurecr.io/mcp-server:heicode-auth-fix2-20260430`
部署日期: 2026-04-30
---
## 9. 联系
如对接过程发现接口行为与本文档不一致，请联系 Heicode Manager 后端团队，附上：
- 请求完整 URL / Headers / Body
- 响应 HTTP 状态 + Body
- `X-Request-Id` 头值（便于服务端按 ID 反查日志）
docs/integration/agnet-platform-request-contract.md
+961
View File
@@ -0,0 +1,961 @@
# Manager → Agnet 平台接口参数文档
**版本**: v0.3（P1/P5 联调契约）
**生效日期**: 2026-05-03
**状态**: 联调准备；当前仓库提供 Manager 侧最小验证端点，生产 Agnet 平台部署尚未在本文档中宣称完成。
**方向**: Heicode Manager 主动请求 Agnet 平台；Agnet 平台返回部署、日志、监控与审计状态。
**范围**: 创建/停止子 Agent 部署、查询部署、获取事件/日志/监控快照、解析 SK 快照、查询审计日志，以及 Agnet 辅助 NewAPI 重建/部署的参数约定。
> 2026-05-04 边界修正：Manager 当前不把 `tenant/project` 作为产品、认证或扣费主轴。新请求应使用 `user_context.user_id`、`user_context.channel_id`、`resource_grants[].binding_scope`、`billing_context(newapi)` 和 `agent_runtime(agnet)`。本文中仍出现的 `tenant_id/project_id` 只表示旧字段兼容或历史接口命名，不应作为新功能设计依据。
**安全红线**: 请求体只允许传资源元数据、权限范围与 `secret_ref`/环境变量名；不得传明文密码、Token、私钥、连接串或云访问密钥。
> 本文档描述 Manager 对 Agnet 平台的出站集成契约。当前仓库中 `/api/agnet/*` 是 Manager 侧最小控制面/模拟端点，用于校验同一套 payload 结构；生产接入时，Manager 应将下列请求发送到 Agnet 平台网关。
## 0. 概述
本文档按登录接口文档的对接方式组织：先定义接入信息，再逐个接口给出请求、响应、错误和安全约束。接口分组如下：
| 接口 | 用途 | 当前性质 |
|---|---|---|
| `POST /api/agnet/deployments` | 创建子 Agent/运维任务部署，含 NewAPI 重建/部署场景 | 必需 |
| `GET /api/agnet/deployments` | 查询部署列表 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}` | 查询单个部署详情 | 必需 |
| `POST /api/agnet/deployments/{deployment_id}/stop` | 停止部署或取消排队任务 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/logs` | 拉取部署日志 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/logs/stream` | 实时日志 SSE | 可选 |
| `GET /api/agnet/projects/{project_id}/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容，参数值按 `binding_scope` 解释 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/metrics` | 单部署指标序列 | 建议 |
| `GET /api/agnet/deployments/{deployment_id}/events` | 部署事件 | 必需 |
| `GET /api/agnet/audit-logs` | 审计日志 | 必需 |
| `POST /api/agnet/sk-snapshots/resolve` | 触发 SK 快照解析 | 必需 |
| `GET /api/agnet/deployments/{deployment_id}/sk-snapshots` | 查询 SK 快照 | 必需 |
> 不在本文档范围：真实 Secret Store 写入、生产 SSH 登录、云账号授权回调、NewAPI 管理后台开放。生产部署动作只有实际执行并通过日志/监控/审计验证后，才能在报告中标记为“已部署”。
---
## 1. 接入约定
### 1.1 Base URL
由部署环境配置，不写入仓库。例如：
```text
AGNET_PLATFORM_BASE_URL=https://agnet-platform.example.com
```
联调环境建议使用独立域名或内网网关，示例不得包含真实凭据：
```text
AGNET_PLATFORM_BASE_URL=https://staging-agnet.example.com
MANAGER_SERVICE_TOKEN_SECRET_REF=vault://secret/users/manager-service/bindings/agnet-platform/service-token
```
完整路径示例：
```http
POST https://agnet-platform.example.com/api/agnet/deployments
```
### 1.2 通用 Header
| Header | 必填 | 说明 |
|---|---:|---|
| `Authorization: Bearer <manager-service-token>` | 是 | Manager 服务身份令牌，由 Secret Store/运行环境注入。 |
| `Content-Type: application/json` | POST/PUT 是 | JSON 请求体。 |
| `X-User-Id: <user_id>` | 建议 | 登录用户边界；也可从 Manager 服务端 token 或 body `user_context.user_id` 推导。 |
| `X-Binding-Scope: <binding_scope>` | 建议 | Git/SK/云资源作用域；也可从 `resource_grants[].binding_scope` 推导。 |
| `X-Correlation-Id: <uuid>` | 是 | Manager 生成，全链路追踪。 |
| `X-Request-Id: <uuid>` | 建议 | 单次 HTTP 请求追踪 ID，可与 correlation_id 不同。 |
| `Idempotency-Key: <uuid>` | 创建类接口建议 | 避免重试造成重复部署。 |
### 1.3 通用响应包裹
成功：
```json
{
"success": true,
"data": {}
}
```
失败：
```json
{
"success": false,
"message": "human readable message",
"error": {
"code": "POLICY_REJECTED",
"message": "human readable message",
"request_id": "req_xxx"
}
}
```
建议错误码：
| code | 场景 |
|---|---|
| `POLICY_REJECTED` | 缺必填字段、权限策略不满足、风险等级非法。 |
| `BUDGET_EXCEEDED` | 超过 token/金额/时长预算。 |
| `MODEL_NOT_ALLOWED` | agent 默认模型不在允许列表内。 |
| `FORBIDDEN_SCOPE` | Header 与 body/query 的用户或资源作用域不一致。 |
| `RESOURCE_GRANT_INVALID` | Resource Grant 字段缺失、跨用户/跨资源作用域/角色不匹配。 |
| `RESOURCE_GRANT_SECRET_REF_REQUIRED` | 凭据型资源缺少 `secret_ref`。 |
| `RESOURCE_GRANT_SECRET_REJECTED` | 请求中出现明文密钥字段。 |
| `SK_SOURCE_UNRESOLVABLE` | SK 来源不可解析。 |
| `DEPLOYMENT_CONFLICT` | 部署不存在、状态冲突或重复提交。 |
| `NOT_FOUND` | deployment、agent instance、snapshot 或审计资源不存在。 |
| `CURSOR_EXPIRED` | 分页游标过期或不属于当前查询条件。 |
| `RATE_LIMITED` | 平台限流；响应头建议包含 `Retry-After`。 |
| `INTERNAL_ERROR` | 平台内部错误；Manager 应记录 request_id 并重试或提示稍后处理。 |
### 1.4 通用错误处理
| HTTP | business code | Manager 处理建议 |
|---:|---|---|
| 400 | `POLICY_REJECTED` / `RESOURCE_GRANT_INVALID` | 标记部署失败，展示校验原因，不自动重试。 |
| 401 | `UNAUTHORIZED` | 检查 Manager 服务令牌的 `secret_ref`/环境注入，不把令牌写入日志。 |
| 403 | `FORBIDDEN_SCOPE` / `MODEL_NOT_ALLOWED` | 阻断本次部署，写审计事件。 |
| 404 | `NOT_FOUND` | 对查询类接口返回空态；对控制类接口提示资源不存在。 |
| 409 | `DEPLOYMENT_CONFLICT` | 使用 `Idempotency-Key` 查询既有结果，避免重复创建。 |
| 410 | `CURSOR_EXPIRED` | 丢弃 cursor，使用 `since` 重新拉取。 |
| 422 | `RESOURCE_GRANT_SECRET_REF_REQUIRED` / `RESOURCE_GRANT_SECRET_REJECTED` | 要求 Manager 重新生成只含 `secret_ref` 的 payload。 |
| 429 | `RATE_LIMITED` | 按 `Retry-After` 退避重试。 |
| 500/503 | `INTERNAL_ERROR` | 指数退避重试；超过阈值后转人工排查。 |
---
## 2. 创建子 Agent 部署
### 2.1 Endpoint
```http
POST /api/agnet/deployments
```
### 2.2 请求体
```json
{
"orchestration_plan": {
"intent_id": "intent_20260502_001",
"template_hint": "manager-resource-binding",
"objective": "为已绑定的代码仓库启动 builder 子 Agent，允许其读取 SK 并在限定路径内提交代码",
"risk_level": "low",
"budget": {
"max_tokens": 100000,
"max_cost_usd": 30,
"max_duration_sec": 7200
},
"user_context": {
"user_id": "user_123",
"email": "user@example.com",
"role": "user",
"channel_id": "channel_abc",
"subscription_tier": "pro"
},
"billing_context": {
"provider": "newapi",
"newapi_user_ref": "newapi_user_123",
"newapi_group": "development",
"quota_ref": "newapi_token_or_group_quota_ref"
},
"agent_runtime": {
"platform": "agnet",
"agents": [
{
"role": "builder",
"model_ref": "agnet_model_profile_builder",
"instance_count": 1
}
]
},
"constraints": {
"allowed_model_ids": ["gpt-5.4-mini", "gpt-5.4"]
},
"metadata": {
"tenant_id": "legacy-user-scope",
"project_id": "legacy-resource-scope",
"correlation_id": "corr_20260502_001"
},
"agents": [
{
"role_template": "builder",
"goal": "按 Manager 下发的任务在允许资源内完成实现、验证并回传状态",
"default_model_id": "gpt-5.4-mini",
"sk_sources": [
{
"type": "git",
"mime": "text/markdown",
"repo_ref": {
"connection_id": "conn_sk_repo_001",
"repo_url": "https://example.com/org/sk-repo.git",
"ref": "main",
"paths": ["skills/heicode/**", "AGENTS.md"]
}
}
],
"runtime_execution": {
"profile_id": "aks-codex-standard",
"cloud_principal_refs": ["principal://users/user_123/agnet-runtime"],
"network_policy_ref": "netpol://bindings/repo_default/restricted-egress"
},
"sk_access_policy": {
"policy_ref": "sk-policy://bindings/repo_default/default-readonly",
"deny_skill_ids": ["dangerous-shell"],
"inherit_deployment_defaults": true
},
"resource_grants": [
{
"grant_id": "grant_git_repo_001",
"resource_id": "res_git_repo_001",
"resource_type": "git",
"user_id": "user_123",
"binding_scope": "repo_default",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-resource-scope",
"target_role": "builder",
"target_agent_ref": "agent-builder-1",
"permission_scope": ["repo:read", "repo:write:current-branch"],
"constraints": {
"ref": "main",
"allowed_paths": "heicode/**,docs/**",
"forbid_branch_create": "true"
},
"metadata": {
"provider": "gitee",
"repo_url": "https://example.com/org/repo.git"
},
"status": "active",
"secret_ref": "vault://secret/users/user_123/bindings/repo_default/resources/res_git_repo_001",
"audit": {
"created_by": "manager",
"approval_id": "approval_001"
}
},
{
"grant_id": "grant_doc_001",
"resource_id": "res_project_doc_001",
"resource_type": "project_doc",
"user_id": "user_123",
"binding_scope": "repo_default",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-resource-scope",
"target_role": "builder",
"target_agent_ref": "agent-builder-1",
"permission_scope": ["doc:read"],
"constraints": {
"doc_paths": "docs/heicode.md,docs/plan.md"
},
"metadata": {
"doc_ref": "project-doc://project-a/docs-mainline"
},
"status": "active",
"audit": {
"created_by": "manager"
}
}
]
}
]
}
}
```
### 2.3 字段说明
#### orchestration_plan
| 字段 | 类型 | 必填 | 约束/说明 |
|---|---|---:|---|
| `intent_id` | string | 是 | Manager 侧意图 ID，用于幂等、审计和追踪。 |
| `template_hint` | string | 是 | Agnet 平台选择编排模板的提示，如 `manager-resource-binding`。 |
| `objective` | string | 是 | 本次部署目标，应是自然语言但不能含密钥。 |
| `risk_level` | enum | 是 | `low` / `medium` / `high`。高风险必须携带客户端审批证据；缺失或不匹配时只能只读或拒绝执行。 |
| `budget.max_tokens` | int | 是 | 当前策略上限建议不超过 `500000`。 |
| `budget.max_cost_usd` | number | 是 | 当前策略上限建议不超过 `200`。 |
| `budget.max_duration_sec` | int | 是 | 当前策略上限建议不超过 `86400`。 |
| `user_context` | object | 建议 | 登录用户上下文，优先使用 Heicode/Agnet 登录返回的 `user.id`/`channelId`。 |
| `billing_context` | object | 条件 | NewAPI 扣费上下文；只表达 user/token/group/quota 映射，不表达子 Agnet 模型或实例数。 |
| `agent_runtime` | object | 条件 | Agnet 平台运行时上下文；表达子 Agnet 角色、模型 profile 和实例数，不承载 NewAPI key 或扣费对象。 |
| `constraints.allowed_model_ids` | string[] | 否 | agent 的 `default_model_id` 如填写，必须在此列表内。 |
| `metadata.tenant_id` | string | 否 | 旧兼容字段；新实现不得作为产品租户边界。 |
| `metadata.project_id` | string | 否 | 旧兼容字段；新实现不得作为项目账本边界。 |
| `metadata.correlation_id` | string | 是 | 全链路追踪 ID。 |
| `agents` | array | 是 | 至少 1 个子 Agent。 |
#### user_context / billing_context / agent_runtime
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `user_context.user_id` | string | 建议 | Manager 业务用户 ID，来自登录接口 `id` 或 JWT `sub`。 |
| `user_context.channel_id` | string | 建议 | 用于关联 NewAPI 用户、Token、Group、余额或额度策略。 |
| `billing_context.provider` | enum | 条件 | 当前只允许 `newapi`。设置后必须提供 `channel_id`、`newapi_user_ref`、`newapi_group` 或 `quota_ref` 之一。 |
| `billing_context.newapi_user_ref` | string | 否 | NewAPI 用户映射引用，不是 NewAPI key。 |
| `billing_context.newapi_group` | string | 否 | NewAPI Group 映射，用于额度或策略选择。 |
| `billing_context.quota_ref` | string | 否 | Token 或 Group 额度引用，不得包含真实 Token 原文。 |
| `agent_runtime.platform` | enum | 条件 | 当前只允许 `agnet`。 |
| `agent_runtime.agents[].role` | string | 条件 | 必须匹配 `agents[].role_template`。 |
| `agent_runtime.agents[].model_ref` | string | 条件 | Agnet 平台模型 profile 引用；不是 NewAPI 扣费字段。 |
| `agent_runtime.agents[].instance_count` | int | 条件 | 子 Agnet 实例数量，必须大于 0。 |
#### agents[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `role_template` | string | 是 | 平台角色模板，如 `builder`/`reviewer`/`operator`。 |
| `goal` | string | 是 | 此 agent 的任务目标。 |
| `default_model_id` | string | 否 | 默认模型；若设置需满足 allowed_model_ids。 |
| `sk_sources` | array | 否 | SK 来源，平台应解析为只读快照。 |
| `runtime_execution` | object | 否 | 运行环境绑定；任一字段存在时 `profile_id` 必填。 |
| `sk_access_policy` | object | 否 | SK 权限策略。若 `deny_skill_ids` 非空，需 `policy_ref` 或继承默认策略。 |
| `resource_grants` | array | 否 | Manager 下发给子 Agent 的最小权限资源授权。 |
#### sk_sources[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `type` | enum | 否 | 空值表示不启用；支持 `git`、`upload`。 |
| `artifact_id` | string | upload 必填 | 上传型 SK 包 ID。 |
| `mime` | string | 否 | 内容类型，如 `text/markdown`。 |
| `repo_ref.connection_id` | string | git 建议 | Git 连接资源 ID。 |
| `repo_ref.repo_url` | string | git 建议 | 仓库 URL；不得带用户名密码。 |
| `repo_ref.ref` | string | git 必填 | 分支/标签/commit。 |
| `repo_ref.paths` | string[] | git 必填 | 允许读取的路径。 |
#### runtime_execution
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `profile_id` | string | 条件必填 | Agnet 平台运行规格，如 AKS profile。 |
| `cloud_principal_refs` | string[] | 否 | 运行身份引用，不是明文凭据。 |
| `network_policy_ref` | string | 否 | 网络策略引用，用于限制出站/入站。 |
#### resource_grants[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `grant_id` | string | 是 | 授权记录 ID。 |
| `resource_id` | string | 是 | Manager 资源 ID。 |
| `resource_type` | enum | 是 | `git` / `sk` / `project_doc` / `cloud_account` / `cloud_resource`。 |
| `user_id` | string | 建议 | 与 `user_context.user_id` 一致；为空时平台可从部署上下文推导。 |
| `binding_scope` | string | 是 | Git/SK/云资源作用域，例如 repo/ref/path 或云资源引用。 |
| `tenant_id` | string | 否 | 旧兼容字段；新实现不应依赖。 |
| `project_id` | string | 否 | 旧兼容字段；新实现不应依赖。 |
| `target_role` | string | 是 | 必须等于当前 agent 的 `role_template`。 |
| `target_agent_ref` | string | 是 | Manager 侧对子 Agent 的逻辑引用。 |
| `permission_scope` | string[] | 是 | 最小权限列表，如 `repo:read`、`doc:read`。 |
| `constraints` | object<string,string> | 否 | 路径、分支、区域、超时等限制；不得含密钥字段。 |
| `metadata` | object<string,string> | 否 | 资源展示/审计元数据；不得含密钥字段。 |
| `status` | enum | 是 | `pending` / `active` / `disabled` / `revoked`。 |
| `secret_ref` | string | 条件必填 | `git`、`sk`、`cloud_account`、`cloud_resource` 必填；`project_doc` 可为空。 |
| `audit` | object<string,string> | 否 | 审计上下文；不得含密钥字段。 |
### 2.4 典型场景：Agnet 辅助 NewAPI 重建/部署
当 Manager 需要让 Agnet 平台协助重建或部署 NewAPI 时，仍使用 `POST /api/agnet/deployments`，但必须把任务表达为受控运维部署，不得把 VM、PostgreSQL、Redis、NewAPI key 等真实凭据写入请求体。
请求体示例：
```json
{
"orchestration_plan": {
"intent_id": "intent_newapi_rebuild_20260503_001",
"template_hint": "newapi-rebuild-deploy",
"objective": "在批准窗口内重建 NewAPI 服务并回传健康检查、日志与资源使用摘要",
"risk_level": "high",
"budget": {
"max_tokens": 80000,
"max_cost_usd": 20,
"max_duration_sec": 3600
},
"constraints": {
"allowed_model_ids": ["gpt-5.4", "gpt-5.4-mini"],
"requires_approval": "true",
"rollback_required": "true",
"healthcheck_url_ref": "env://NEWAPI_HEALTHCHECK_URL"
},
"metadata": {
"tenant_id": "legacy-user-scope",
"project_id": "legacy-newapi-scope",
"correlation_id": "corr_newapi_20260503_001",
"service": "new-api",
"environment": "production",
"commit": "origin/main",
"runbook_ref": "heicode/docs/deploy/new-api-rebuild-deploy-runbook.md"
},
"agents": [
{
"role_template": "operator",
"goal": "按 runbook 执行构建、服务重启、健康检查和失败回滚；只通过 secret_ref/env 获取凭据",
"default_model_id": "gpt-5.4",
"runtime_execution": {
"profile_id": "aks-codex-ops",
"cloud_principal_refs": ["principal://users/user_123/agnet-ops"],
"network_policy_ref": "netpol://bindings/newapi-prod/ops-egress"
},
"resource_grants": [
{
"grant_id": "grant_newapi_vm_ops",
"resource_id": "res_newapi_vm",
"resource_type": "cloud_resource",
"user_id": "user_123",
"binding_scope": "newapi-prod",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-newapi-scope",
"target_role": "operator",
"target_agent_ref": "agent-operator-1",
"permission_scope": ["vm:ssh:approved-window", "service:restart", "log:read", "healthcheck:read"],
"constraints": {
"approval_id": "approval_newapi_001",
"window": "2026-05-03T10:00:00Z/2026-05-03T11:00:00Z",
"rollback_command_ref": "runbook://newapi/rollback"
},
"metadata": {
"host_ref": "env://NEWAPI_VM_HOST",
"service_name": "new-api"
},
"status": "active",
"secret_ref": "vault://secret/users/user_123/bindings/newapi-prod/resources/res_newapi_vm",
"audit": {
"created_by": "manager",
"approval_id": "approval_newapi_001"
}
},
{
"grant_id": "grant_newapi_runtime_env",
"resource_id": "res_newapi_runtime_env",
"resource_type": "cloud_resource",
"user_id": "user_123",
"binding_scope": "newapi-prod",
"tenant_id": "legacy-user-scope",
"project_id": "legacy-newapi-scope",
"target_role": "operator",
"target_agent_ref": "agent-operator-1",
"permission_scope": ["env:read:runtime", "secret:read:scoped"],
"constraints": {
"allowed_env_refs": "DATABASE_DSN,REDIS_URL,NEWAPI_SERVICE_TOKEN",
"plaintext_export_forbidden": "true"
},
"metadata": {
"secret_provider": "openbao",
"scope": "newapi-runtime"
},
"status": "active",
"secret_ref": "vault://secret/users/user_123/bindings/newapi-prod/resources/res_newapi_runtime_env",
"audit": {
"created_by": "manager",
"approval_id": "approval_newapi_001"
}
}
]
}
]
}
}
```
Agnet 平台返回的部署详情、日志、监控和审计中应至少能证明：构建版本/commit、服务重启结果、健康检查结果、资源使用情况、失败回滚状态。未执行真实 SSH/生产动作时，只能返回 `phase=planned` 或 `phase=pending_approval`。
NewAPI 重建/部署的完成判定必须同时满足：
1. `metadata.commit` 或部署详情中的 resolved commit 已在 VM 仓库中生效。
2. 部署日志包含构建/compose/restart 的脱敏摘要。
3. 健康检查返回成功，且监控接口能返回本次 deployment 的状态或资源摘要。
4. 审计日志包含高风险审批 ID、执行者、目标环境和结果。
5. 回滚指针或回滚命令引用已记录。
### 2.5 成功响应
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"status": "accepted",
"agent_instances": [
{
"instance_id": "agi_abc123",
"role": "builder",
"phase": "pending"
}
]
}
}
```
---
## 3. 部署状态与控制接口
### 3.1 查询部署列表
```http
GET /api/agnet/deployments?user_id=user_123&binding_scope=repo_default
```
返回：
```json
{
"success": true,
"data": {
"items": [
{
"deployment_id": "dep_abc123",
"status": "accepted",
"phase": "pending",
"created_at": "2026-05-02T00:00:00Z",
"updated_at": "2026-05-02T00:00:00Z"
}
],
"total": 1
}
}
```
### 3.2 查询单个部署
```http
GET /api/agnet/deployments/{deployment_id}
```
返回应包含部署状态、phase、agent_instances、最近错误、资源授权摘要和预算消耗摘要。Agnet 平台返回时必须对 `secret_ref` 以外的凭据信息做脱敏；原则上不返回任何明文凭据。
### 3.3 停止部署
```http
POST /api/agnet/deployments/{deployment_id}/stop
```
请求体可为空；如需原因可扩展：
```json
{
"reason": "user_requested",
"requested_by": "manager"
}
```
成功：
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"status": "stopped"
}
}
```
错误与幂等：
| HTTP | business code | 说明 |
|---:|---|---|
| 200 | - | 已停止的部署重复停止也可返回 200，并保持 `status=stopped`。 |
| 404 | `NOT_FOUND` | 部署不存在或不属于当前租户/项目。 |
| 409 | `DEPLOYMENT_CONFLICT` | 部署已进入不可停止的终态，如 `completed` 且无运行实例。 |
| 422 | `POLICY_REJECTED` | 高风险停止缺少审批记录或 reason 不合法。 |
若停止请求触发异步回收，平台可返回 `status=stopping`；Manager 应继续通过事件、日志和监控接口确认最终状态。
---
## 4. 日志接口（Manager 拉取 Agnet 平台）
### 4.1 获取部署日志
```http
GET /api/agnet/deployments/{deployment_id}/logs?agent_instance_id=agi_abc123&stream=stdout&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
```
Query：
| 参数 | 必填 | 说明 |
|---|---:|---|
| `agent_instance_id` | 否 | 不传则返回该 deployment 下全部实例日志。 |
| `stream` | 否 | `stdout` / `stderr` / `system` / `audit`，默认全部。 |
| `since` | 否 | RFC3339 时间，增量拉取起点。 |
| `limit` | 否 | 默认 200，建议最大 1000。 |
| `cursor` | 否 | 分页游标。 |
响应：
```json
{
"success": true,
"data": {
"items": [
{
"log_id": "log_001",
"deployment_id": "dep_abc123",
"agent_instance_id": "agi_abc123",
"stream": "stdout",
"level": "info",
"message": "task started",
"redacted": true,
"occurred_at": "2026-05-02T00:00:01Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
日志要求：
- Agnet 平台必须在返回前完成密钥脱敏。
- `message` 不得包含密码、Token、私钥、连接串、云访问密钥。
- Manager 只保存必要摘要和审计索引；长日志建议落对象存储并设置保留期。
### 4.2 实时日志流（可选）
```http
GET /api/agnet/deployments/{deployment_id}/logs/stream?agent_instance_id=agi_abc123
Accept: text/event-stream
```
SSE event 示例：
```text
event: log
data: {"log_id":"log_002","level":"info","message":"step completed","occurred_at":"2026-05-02T00:00:02Z"}
```
SSE 事件类型：
| event | 说明 |
|---|---|
| `log` | 普通日志行，必须已脱敏。 |
| `heartbeat` | 保活事件，建议 15-30 秒一次。 |
| `error` | 流式读取错误；不包含敏感上下文。 |
| `done` | 部署进入终态或服务端主动结束流。 |
错误处理：
| HTTP | business code | Manager 处理建议 |
|---:|---|---|
| 401/403 | `UNAUTHORIZED` / `FORBIDDEN_SCOPE` | 立即断开流并记录审计。 |
| 404 | `NOT_FOUND` | 停止订阅并刷新部署详情。 |
| 429 | `RATE_LIMITED` | 退避后重连，保留 `Last-Event-Id`。 |
---
## 5. 监控接口（Manager 拉取 Agnet 平台）
### 5.1 项目监控快照
```http
GET /api/agnet/projects/{binding_scope}/dashboard-snapshot?window=1h
```
响应：
```json
{
"success": true,
"data": {
"project_id": "project-a",
"active_instances": 3,
"phase_distribution": {
"pending": 1,
"running": 2,
"stopped": 0,
"failed": 0
},
"failure_rate_1h": 0.02,
"avg_task_duration": 185.3,
"budget": {
"tokens_used": 32000,
"cost_usd": 4.21,
"duration_sec": 930
},
"resource_usage": {
"cpu_millicores": 1200,
"memory_mb": 2048,
"network_rx_bytes": 102400,
"network_tx_bytes": 204800
},
"updated_at": "2026-05-02T00:05:00Z"
}
}
```
### 5.2 单部署监控快照（建议平台实现）
```http
GET /api/agnet/deployments/{deployment_id}/metrics?window=15m&step=60s
```
响应：
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"window": "15m",
"series": [
{
"metric": "tokens_used",
"unit": "count",
"points": [["2026-05-02T00:00:00Z", 1200]]
},
{
"metric": "cpu_millicores",
"unit": "millicore",
"points": [["2026-05-02T00:00:00Z", 500]]
}
]
}
}
```
建议指标：`tokens_used`、`cost_usd`、`duration_sec`、`cpu_millicores`、`memory_mb`、`restart_count`、`tool_call_count`、`error_count`、`queue_latency_ms`。
---
## 6. 事件与审计接口
### 6.1 部署事件
```http
GET /api/agnet/deployments/{deployment_id}/events?since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
```
响应：
```json
{
"success": true,
"data": {
"items": [
{
"event_id": "evt_001",
"event": "deployment.accepted",
"schema_version": 1,
"user_id": "user_123",
"channel_id": "channel_abc",
"binding_scope": "repo_default",
"deployment_id": "dep_abc123",
"correlation_id": "corr_20260502_001",
"occurred_at": "2026-05-02T00:00:00Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
常用事件名：
| event | 说明 |
|---|---|
| `deployment.accepted` | 平台接受部署请求。 |
| `instance.phase_changed` | 子 Agent phase 变化。 |
| `sk_snapshot_refreshed` | SK 快照解析/刷新完成。 |
| `resource_grant.attached` | 资源授权已绑定到实例。 |
| `resource_grant.revoked` | 授权被撤销或禁用。 |
| `budget.threshold_reached` | 预算阈值触发。 |
| `deployment.failed` | 部署失败。 |
### 6.2 审计日志
```http
GET /api/agnet/audit-logs?user_id=user_123&binding_scope=repo_default&actor=agnet_control_plane&action=deployment.accepted&since=2026-05-02T00:00:00Z&limit=200&cursor=cur_001
```
响应：
```json
{
"success": true,
"data": {
"items": [
{
"audit_id": "aud_001",
"actor": "agnet_control_plane",
"action": "deployment.accepted",
"resource": "dep_abc123",
"user_id": "user_123",
"channel_id": "channel_abc",
"binding_scope": "repo_default",
"request_id": "req_001",
"correlation_id": "corr_20260502_001",
"result": "ok",
"occurred_at": "2026-05-02T00:00:00Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
---
## 7. SK 快照接口
### 7.1 触发解析/刷新
```http
POST /api/agnet/sk-snapshots/resolve
```
请求：
```json
{
"deployment_id": "dep_abc123"
}
```
响应：
```json
{
"success": true,
"data": {
"deployment_id": "dep_abc123",
"items": [
{
"snapshot_id": "sks_001",
"deployment_id": "dep_abc123",
"user_id": "user_123",
"binding_scope": "repo_default",
"source_type": "git",
"source_ref": "main:skills/heicode/**@sha_xxx",
"resolved_at": "2026-05-02T00:00:00Z"
}
],
"total": 1
}
}
```
### 7.2 查询部署 SK 快照
```http
GET /api/agnet/deployments/{deployment_id}/sk-snapshots
```
Query：
| 参数 | 必填 | 说明 |
|---|---:|---|
| `user_id` | 建议 | 与 `X-User-Id` 或 deployment 的 `user_context.user_id` 一致。 |
| `binding_scope` | 建议 | 与 `X-Binding-Scope` 或 deployment 的资源授权作用域一致。 |
| `source_type` | 否 | `git` / `upload`，用于筛选。 |
| `limit` | 否 | 默认 100，最大 500。 |
| `cursor` | 否 | 分页游标。 |
成功响应：
```json
{
"success": true,
"data": {
"items": [
{
"snapshot_id": "sks_001",
"deployment_id": "dep_abc123",
"user_id": "user_123",
"binding_scope": "repo_default",
"source_type": "git",
"source_ref": "main:skills/heicode/**@sha_xxx",
"artifact_ref": "artifact://bindings/repo_default/sk/sks_001",
"checksum": "sha256:example-redacted",
"status": "ready",
"resolved_at": "2026-05-02T00:00:00Z"
}
],
"next_cursor": "cur_002",
"total": 1
}
}
```
错误处理：
| HTTP | business code | 说明 |
|---:|---|---|
| 404 | `NOT_FOUND` | deployment 不存在或不属于当前租户/项目。 |
| 410 | `CURSOR_EXPIRED` | cursor 过期，使用不带 cursor 的查询重拉。 |
| 422 | `SK_SOURCE_UNRESOLVABLE` | 快照来源不可解析，详情在事件/日志中查看。 |
---
## 8. 安全校验清单
Manager 发给 Agnet 平台前必须执行：
1. `user_id`、`binding_scope`、`target_role` 与部署计划一致。
2. 凭据型资源只传 `secret_ref`，不传明文凭据。
3. `metadata`、`constraints`、`audit` 的 key 中不得出现 `password`、`token`、`secret`、`private_key`、`access_key`、`credential` 等敏感词。
4. `repo_url` 不得包含用户名、密码或访问 Token。
5. `permission_scope` 使用最小权限；生产写操作必须携带客户端审批记录，Agnet 平台不得自行补批。
6. 高风险操作（生产部署、云资源修改、删除、扩容）必须设置 `risk_level=high`，Agnet 平台执行前只校验客户端审批证据。
7. 所有日志/事件/审计返回给 Manager 前必须脱敏。
Agnet 平台不承担高危操作审批主体。审批只发生在客户端；Agnet 平台只能在执行前校验以下字段和策略是否一致：
| 校验项 | 要求 |
|---|---|
| `approval_id` | 必须存在于高危任务的 `constraints` 或 `audit`，并可追溯到客户端审批记录。 |
| 审批主体 | 审批用户必须与 `user_context.user_id`、`resource_grants[].user_id` 或授权代理主体一致。 |
| 审批范围 | 审批范围必须覆盖 `binding_scope`、`permission_scope`、目标环境、资源 ID 和操作类型。 |
| TTL / 时间窗口 | 审批记录必须未过期；若使用 `window` 或 TTL，当前执行时间必须落在允许范围内。 |
| `risk_level` | 高危资源写入、生产部署、云资源修改、删除和扩容必须为 `high`。 |
| 策略 | 平台 policy、OpenBao policy、Kubernetes/Workload Identity、网络策略和最小权限约束均必须允许本次动作。 |
任一校验不通过时，Agnet 平台应返回 `POLICY_REJECTED` 或 `FORBIDDEN_SCOPE`，不得发起额外批准流程。
### 8.1 字段级约束速查
| 对象/接口 | 必填最小集合 | 禁止内容 |
|---|---|---|
| `orchestration_plan` | `intent_id`、`template_hint`、`objective`、`risk_level`、`budget`、`user_context`、`billing_context`、`agent_runtime`、`metadata.correlation_id`、`agents[]` | 密钥、连接串、真实主机登录密码、NewAPI key 原文。 |
| `agents[]` | `role_template`、`goal` | 让子 Agent 绕过 Manager/Agnet 审计的指令。 |
| `runtime_execution` | 任一字段存在时 `profile_id` 必填 | 明文 kubeconfig、SSH key、云访问密钥。 |
| `resource_grants[]` | `grant_id`、`resource_id`、`resource_type`、`user_id`、`binding_scope`、`target_role`、`target_agent_ref`、`permission_scope`、`status` | 明文 `password`、`token`、`private_key`、`access_key`、`credential`、数据库 DSN。 |
| 日志/事件/审计返回 | `request_id` 或 `correlation_id`，以及发生时间 | 未脱敏命令行、环境变量 dump、密钥片段。 |
| NewAPI 重建/部署场景 | `approval_id`、`rollback_command_ref`、健康检查引用、运行环境 `secret_ref` | 真实 VM 密码、PostgreSQL/Redis 连接串、NewAPI 服务令牌。 |
### 8.2 联调验收清单
- 创建部署请求只包含 `secret_ref`/`env://`/`runbook://` 引用，不包含真实凭据。
- `user_id` 与 `binding_scope` 在 user context、resource grant、事件和审计中一致。
- `risk_level=high` 的生产运维任务包含 `approval_id` 和回滚引用。
- 日志、事件、监控、审计接口都能通过 `correlation_id` 串联。
- NewAPI 重建/部署只在实际执行并通过健康检查后标记为已部署；未执行时状态只能是 `planned`、`pending_approval`、`accepted` 或 `running`。
- Manager 本地 `/api/agnet/*` 占位端点通过 payload 校验不等于生产 Agnet 平台已上线。
---
## 9. Manager 侧当前实现映射
当前代码中可用于对齐/验证 payload 的 Manager 侧端点：
| Manager 路由 | 用途 |
|---|---|
| `POST /api/agnet/deployments` | 校验并接受 orchestration_plan。 |
| `GET /api/agnet/deployments` | 按 user/binding scope 查询部署。 |
| `GET /api/agnet/deployments/:deployment_id` | 查询部署详情。 |
| `POST /api/agnet/deployments/:deployment_id/stop` | 停止部署。 |
| `GET /api/agnet/deployments/:deployment_id/logs` | 查询脱敏日志占位/联调日志。 |
| `GET /api/agnet/deployments/:deployment_id/metrics` | 查询单部署指标占位/联调指标。 |
| `GET /api/agnet/deployments/:deployment_id/events` | 查询事件。 |
| `POST /api/agnet/sk-snapshots/resolve` | 解析 SK 快照。 |
| `GET /api/agnet/deployments/:deployment_id/sk-snapshots` | 查询 SK 快照。 |
| `GET /api/agnet/projects/:project_id/dashboard-snapshot` | 资源作用域监控快照；路径名保留旧兼容。 |
| `GET /api/agnet/audit-logs` | 审计日志。 |
生产对接时，Manager 应把相同契约的请求发送给 Agnet 平台；本地 Manager 端点仅作为最小验证与控制面占位，不代表所有日志/监控平台能力已完整实现。
当前本地 `logs` 与 `metrics` 端点只返回脱敏占位/联调数据，用于验证 Manager ↔ Agnet payload、路由和验收流程。生产级实时日志流 `GET /api/agnet/deployments/{deployment_id}/logs/stream` 仍属于 Agnet 平台能力；Manager 不得把“本地占位通过”误报为“生产日志/监控已上线”。
docs/integration/manager-side-contract-patches.md
+61
View File
@@ -0,0 +1,61 @@
# Manager → mcp-server 契约补丁清单
> 来源：Heicode Manager 前端集成 §1–§6 时打的本地 patch。建议 mcp-server 侧把这些归一掉，前端就能删掉对应的兼容层。
## 1. `manager_actions[].deeplink` 命名空间
**当前现象**：mcp-server 返回的 deeplink 形如 `/manager/resources`、`/manager/wallet`、`/manager/audit`。
**Manager 实际路由**：`/sk-sources`、`/wallet`、`/audit`。
**前端兜底**：`src/features/tasks/task-card-view.tsx::normalizeDeeplink()` 做了映射表。
**建议**：mcp-server 直接返回 Manager 真实路径，或返回 `{kind: 'resources' | 'wallet' | 'audit', ...}` 让前端自己拼。前者更简单。
| mcp-server 现返回 | Manager 应跳 |
|---|---|
| `/manager/resources` | `/sk-sources` |
| `/manager/wallet` | `/wallet` |
| `/manager/audit` | `/audit` |
| `/manager/tasks/{id}` | `/tasks/{id}` |
## 2. §5 审计日志的敏感字段 redact
**当前现象**：mcp-server `/api/agnet/audit` 返回的条目里 `payload` 字段可能包含 token / secret 原文（按 §5 设计应在服务端 mask）。
**前端兜底**：`src/features/agnet-console/pages.tsx::maskIfSecret()` 做了第二层 mask（按 key 名匹配 `secret|token|password|api_key`）。
**建议**：mcp-server 在写审计或读出时统一 mask，前端可以删掉那一层。
## 3. §6 任务卡 `manager_actions` 形状一致性
**当前确认**：HeicodeTaskCard 真实形状是 `{goal, scope, generated_artifacts, manager_actions: [{label, deeplink}]}`，前端已对齐。
**建议**：在 mcp-server contract 文档 §6 里把这个形状固定下来，避免后续漂移。
## 4. §4 usage 字段名
**当前消费**：`{date, total_quota, total_tokens, prompt_tokens, completion_tokens, count}`。
**Manager 用**：sparkline 取 `total_quota`、tooltip 拼 `date` + `formatQuota(total_quota)`。
**建议**：维持当前字段名即可。如果未来引入按模型聚合，建议另起 endpoint，不要在 `items` 里混。
## 5. §5 `/api/agnet/*` stub 数据
**当前**：mcp-server 内存 dict（按 §5.0 设计），无 agent-manager 真实转发。
**阻塞解除条件**：
- agent-manager 侧给 mcp-server 派发 service token
- mcp-server 把 stub 换成对 `20.212.121.126:80` 的真实转发（HTTP/80，Host 头 `agent-manager.taijiagnet.com`）
Manager 前端已按 §5 契约消费，stub → 真实数据无需前端改动。
## 6. SSE `/api/user/tasks/{id}/events` 状态
**当前**：Manager 用 `refetchInterval` 自适应轮询替代（active 状态 3 秒，terminal 状态停止，其它 15 秒）。
**建议**：mcp-server 把 SSE 帧格式（event name、data shape）写进契约文档，前端再切到 EventSource / fetch stream。事件至少要覆盖：
- `status_changed`（包含新 status）
- `followup_added`（包含 followup payload）
- `card_updated`（包含完整 HeicodeTaskCard）
docs/plan.md
+126
View File
@@ -0,0 +1,126 @@
# Heicode 实施计划
本文依据 [`heicode.md`](./heicode.md) 的当前共识拆分执行阶段。计划只描述方向和交付顺序，不代表每项已经进入开发。
## P0：边界收敛
状态：文档边界已收敛。当前 `docs/` 只保留 `heicode.md`、`plan.md` 和已上线登录接口文档作为实施依据；旧 Agnet API 草案、旧 M1-M5 计划和旧架构说明不再作为开发输入。现有代码中仍可能存在过渡期的 `sk_sources`、Agnet control plane 或部署计划命名，不能反向覆盖本文档边界。
目标：让团队只围绕一套产品和架构边界协作。
任务：
- 以 [`heicode.md`](./heicode.md) 作为当前产品与架构共识。
- 保留已上线登录接口文档。
- 不再维护旧 Agnet API 草案和旧 M1-M5 计划。
- 后续所有实现前先确认是否符合 Manager / Agnet / NewAPI / Secret Store 的边界。
- 需求和边界没有想清楚前，不改代码。
验收：
- `docs/` 中没有多套互相冲突的 Agnet、NewAPI 或 Manager 计划。
- 新需求讨论先落到文档共识，再进入实现。
## P1：Manager 资源模型
目标：把“Git 来源”升级为面向子 Agnet 的统一资源绑定模型。
任务：
- 将当前 Git 来源抽象为资源绑定模型。
- 增加资源类型：Git、SK、项目文档、云账号、单项云资源。
- 增加 Resource Grant，用于把资源分配给登录用户、绑定 Git/SK/云资源范围、角色和子 Agnet。
- 定义资源元数据、权限范围、约束、状态和审计字段。
- 前端从单点功能页逐步走向“绑定资源 -> 分配角色 -> 部署确认”的主流程。
当前实现状态：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、子 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
目标：建立 SaaS 多用户凭证托管能力。
任务：
- 优先选型 HashiCorp Vault。
- 保留 Infisical 和 Azure Key Vault 作为 Secret Provider 备选。
- 在 Manager 后端实现 Secret Broker。
- Secret Broker 负责写入、轮换、撤销、禁用和审计。
- Manager DB 只保存 `secret_ref`，不保存明文密钥。
- 增加日志脱敏、前端响应过滤、Markdown 生成过滤。
验收：
- Git token、云密钥、SSH key、数据库密码不会进入 Git、Markdown、前端响应或普通日志。
- 用户可以授权和撤销资源，平台负责实际凭证托管。
## P3：Agnet 平台 AKS 身份接入
目标：让子 Agnet 在 AKS 上按最小权限访问被授权资源。
任务：
- Agnet 平台支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
- 支持 Vault Kubernetes Auth 或等价 Workload Identity。
- 支持按 user / resource binding / role 生成 OpenBao policy。
- 子 Agnet 运行时只能访问被授权的 secret。
- 普通开发资源支持受控注入。
- 高危操作审批只在客户端完成；审批通过后允许向子 Agnet 注入 OpenBao 派生的短期、最小权限凭证。
验收：
- 子 Agnet 不保存长期密钥。
- 撤销 Resource Grant 后，子 Agnet 无法继续访问对应资源。
- 高危资源访问有审计记录。
## P4：NewAPI 解耦
目标：让 NewAPI 回到独立模型网关和计费服务的位置。
任务：
- NewAPI 保持独立服务。
- NewAPI 后台不开放给普通 SaaS 用户。
- Manager 通过服务凭据调用 NewAPI。
- Manager 展示普通用户需要的模型、余额、额度、调用日志。
- 隐藏渠道管理、价格配置、模型供应商后台配置和 NewAPI 管理员能力。
- 建立 Heicode/Agnet 登录用户 `user.id`、`channelId` 与 NewAPI user / token / group / quota / usage 的映射。
- 子 Agnet 的运行模型、模型 profile 和实例数归 Agnet 平台部署配置管理，不和 NewAPI 扣费映射混用。
验收：
- 普通用户只进入 Manager，不进入 NewAPI 后台。
- Manager 能展示模型与用量信息。
- NewAPI 升级不要求 Manager 跟着改核心后台逻辑。
## P5：部署和审计闭环
目标：跑通从用户想法到子 Agnet 部署、执行、观测和审计的闭环。
任务：
- Manager 生成 AGENT.md、resource context 和 permission manifest。
- Agnet 平台部署子 Agnet 后回传 deployment、agent instance、状态和事件。
- Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
- 对高危权限增加审批、撤销和运行中失效机制。
- 为每次部署保留可追溯的资源、权限、模型和上下文快照。
验收：
- 用户能看到每个子 Agnet 的角色、模型、资源权限、运行状态和失败原因。
- 审计能回答谁在什么时候让哪个子 Agnet 使用了什么资源。
- Markdown 只作为上下文，permission manifest 才是系统执行依据。
docs/product-package/01-product-overview.md
+82
View File
@@ -0,0 +1,82 @@
# 01. 产品说明文档
## 产品名称
Heicode
## 产品定位
Heicode 是一款覆盖软件生命周期的智能开发 Code 工具。它面向的是“从想法到上线”的完整开发过程，而不是单个模型聊天窗口、CodeGW 管理后台或简单的 Agent 控制台。
用户只需要注册登录，输入想法和约束，Heicode 就帮助用户组织子 Agnet 团队，接入用户授权的 Git、SK、项目文档和云资源，完成产品设计、代码开发、代码检查、部署、观测和后续维护。
## 目标用户
| 用户 | 典型问题 | Heicode 价值 |
|------|----------|--------------|
| 独立开发者 | 有想法但缺工程团队 | 用 AI 团队完成从需求到上线 |
| 创业团队 | 人少、迭代快、交付压力大 | 用 Heicode 编排产品、开发、测试、部署流程 |
| 企业创新团队 | 有资源和代码，但协作成本高 | 在既有 Git 和云资源边界内受控开发 |
| 技术负责人 | 担心权限、成本、质量和审计 | 统一资源授权、模型用量、日志和审计 |
## 核心价值
1. 把自然语言想法变成可执行的软件开发任务。
2. 把 Git、文档、SK、云资源变成可授权、可撤销、可审计的资源。
3. 把子 Agnet 的角色、权限、模型和上下文组织成可运行的开发团队。
4. 把持续开发拆成需求、设计、开发、测试、修复、部署等子环节，由 Agnet 持续推进。
5. 让 Agnet 在执行过程中可以调用项目 SK 工具和外部能力，而不是只做一次性任务分发。
6. 把模型调用、余额、额度和日志统一展示给用户。
7. 把长期密钥放入密钥保管器，只给子 Agnet 短期、最小权限凭证。
8. 把开发、检查、部署、维护纳入同一个生命周期闭环。
## 产品形态
| 产品面 | 说明 |
|--------|------|
| Heicode 客户端 | 用户主体验，负责本地对话、输入想法、继续开发、查看执行反馈、接收交付结果和高危审批，只登录 Heicode，只使用 Heicode 提供的模型 |
| Heicode Manager / 浏览器控制台 | 辅助控制台，负责账号与安全、客户端下载、Git/云资源绑定、Agnet 部署、任务状态总览、模型余额与用量、审计与日志查看 |
| Agnet 平台 | 执行层，负责部署和运行子 Agnet，在任务推进过程中完成需求、开发、测试、修复、交付与部署，并回传日志、状态、事件和指标 |
| CodeGW | 内部模型网关与计费服务，普通用户不直接进入后台 |
| 密钥保管器 | OpenBao 实现，保存长期凭证，按审批和权限提供短期凭证租约 |
说明：Heicode 客户端是用户主体验，用户不在网页上编码。Heicode Manager 是浏览器里的辅助控制台，承担资源、部署、状态、余额、审计和下载等辅助操作。真正持续推进任务的是 Heicode 调度下的 Agnet 执行闭环，Agnet 在过程中还可以调用已授权的 SK 工具和外部能力，最终完成交付与部署并把结果回传到客户端。
## 核心流程
```text
注册登录
-> 输入产品想法
-> 生成产品文档和任务计划
-> 在 Manager 绑定 Git 和云资源
-> 在 Manager 部署 Agnet
-> 客户端继续追加需求和修正方向
-> Agnet 按子环节执行需求、开发、测试、修复
-> Agnet 按需要调用已授权 SK 工具
-> 客户端确认高危操作
-> Agnet 完成交付物整理和部署
-> Manager 查看状态、余额、审计和下载
-> 客户端展示执行反馈和交付结果
-> 持续维护和升级
```
## 差异化
| 对比对象 | 差异 |
|----------|------|
| 普通 AI 聊天工具 | Heicode 不只回答问题，而是组织资源、权限和执行团队 |
| IDE 插件 | Heicode 不局限于本地代码编辑，而覆盖部署、审计和生命周期 |
| CodeGW 后台 | Heicode 不管理渠道后台，面向用户完成开发任务 |
| 传统 DevOps 平台 | Heicode 以自然语言和 AI 团队为核心，自动生成任务和执行上下文 |
## 产品承诺
1. 用户不需要理解底层模型供应商。
2. 用户不需要把密钥交给子 Agnet 长期保存。
3. 用户可以清楚知道哪些资源被哪个角色使用。
4. 高危操作必须经过客户端审批。
5. 所有关键动作都能审计。
## 当前一句话卖点
> 从一个想法开始，让 Heicode 组织 AI 开发团队，持续调用 Agnet 完成开发、测试、交付与部署，安全接入你的代码和云资源，把产品推进到生产环境。
docs/product-package/02-homepage-design-brief.md
+173
View File
@@ -0,0 +1,173 @@
# 02. 产品首页设计文档
## 首页目标
首页要让用户在第一屏理解三件事：
1. Heicode 是全流程智能开发工具。
2. 用户可以从想法开始，到代码、部署和维护。
3. Heicode 能安全接入 Git、云资源、模型和密钥保管器。
首页不是 CodeGW 后台入口，也不是单纯 Agent 平台介绍页。
## 首页受众
| 受众 | 第一眼要看到 |
|------|--------------|
| 创业者 | 想法可以快速变成产品 |
| 开发者 | 能接入真实代码仓库和云资源 |
| 技术负责人 | 权限、密钥、审计和成本可控 |
| 投资人/客户 | 这是完整的软件生命周期平台 |
## 首屏文案
标题建议：
> 从一个想法，到可上线的软件产品
副标题建议：
> Heicode 组织 AI 开发团队，接入你的代码、文档、SK 和云资源，完成需求、开发、检查、部署和后续维护。
主按钮：
- 开始使用 Heicode
次按钮：
- 查看产品演示
首屏辅助信息：
- 绑定 Git 与云资源
- 生成子 Agnet 团队
- 密钥保管器托管凭证
- CodeGW 统一模型与用量
## 首页结构
### 1. Hero 区
重点表达：
```text
想法输入
-> AI 开发团队
-> 代码与云资源
-> 生产部署
```
视觉建议：
- 使用真实产品界面截图或产品工作流图。
- 不做抽象渐变英雄图。
- 第一屏必须看到 Heicode 名称和产品主张。
- CTA 明确指向登录或演示。
### 2. 问题区
标题：
> 现在的软件开发，不缺模型，缺完整流程
要点：
- 想法和代码之间缺少可执行路径。
- AI 工具无法安全使用用户的云资源和密钥。
- 多个 Agent 缺少角色、权限和审计。
- 模型用量、余额、日志分散在后台。
- 部署和后续维护没有闭环。
### 3. 解决方案区
标题：
> Heicode 把开发流程变成可编排的 AI 团队任务
四个能力：
| 能力 | 说明 |
|------|------|
| 想法转任务 | 把自然语言目标转成产品文档、任务和角色 |
| 资源绑定 | 接入 Git、SK、项目文档、云账号和云资源 |
| 权限控制 | 按角色分配 Resource Grant 和审批规则 |
| 执行闭环 | 子 Agnet 持续推进开发、测试、修复和部署，可调用 SK 工具，Heicode 展示日志和审计 |
### 4. 工作流区
标题：
> 从登录到上线，一条主流程
流程：
1. 登录 Heicode。
2. 输入想法。
3. 绑定资源。
4. 生成 AI 开发团队。
5. 确认权限和审批。
6. 执行开发与部署。
7. 查看日志、用量和审计。
8. 持续维护。
### 5. 安全区
标题：
> 资源可以使用，密钥不能外泄
说明：
- 长期密钥进入密钥保管器。
- Heicode 服务端数据库只保存 `secret_ref`。
- 子 Agnet 只拿短期凭证。
- 高危操作在客户端审批。
- 日志、Markdown、前端响应不显示明文密钥。
### 6. 系统边界区
标题：
> 每个系统各司其职
| 系统 | 职责 |
|------|------|
| Heicode Manager | 资源、部署、状态、用量和审计辅助控制台 |
| 客户端 | 主对话体验、任务推进和高危审批 |
| Agnet 平台 | AKS 执行层 |
| CodeGW | 模型网关与用量 |
| OpenBao | 密钥保管器 |
补充说明：
- 用户主要在客户端对话和推进任务。
- Manager 主要承担资源准备、Agnet 部署、用量和审计辅助。
### 7. 适用场景区
场景：
- 从 0 到 1 创建 SaaS 产品。
- 为已有代码库增加功能。
- 让 AI 团队维护和升级系统。
- 在云资源边界内自动部署。
- 对模型用量和高危操作做审计。
### 8. CTA 区
标题：
> 让你的下一个想法进入开发流程
按钮：
- 登录 Heicode
- 观看 5 分钟演示
## 风格建议
- 产品感应偏专业、清晰、可信，不要娱乐化。
- 信息密度适中，避免空泛大词。
- 主色与 Heicode 和客户端保持一致。
- 图片优先使用真实界面和流程，不使用无意义装饰图。
- 首页文案避免出现 CodeGW 后台、OpenBao 控制台、模型提供方配置等内部概念。
docs/product-package/03-user-journey-and-core-flow.md
+184
View File
@@ -0,0 +1,184 @@
# 03. 用户旅程与核心流程
## 旅程目标
用户从“我有一个想法”开始，不需要先学习 Agent、CodeGW、密钥保管器或部署系统。Heicode 应该用一个连续流程带用户完成：
```text
想法
-> 资源
-> 团队
-> 权限
-> 执行
-> 上线
-> 维护
```
## 用户旅程总览
| 阶段 | 用户动作 | 平台动作 | 输出 |
|------|----------|----------|------|
| 1. 登录 | 注册或登录 Heicode | 获取用户身份和 channelId | 用户会话 |
| 2. 输入想法 | 描述要做的产品或任务 | 生成需求摘要和任务草案 | 需求草案 |
| 3. 绑定资源 | 授权 Git、文档、SK、云资源 | 保存资源元数据和 `secret_ref` | Resource Binding |
| 4. 生成团队 | 确认开发方法和角色 | 推荐子 Agnet 角色 | 角色方案 |
| 5. 分配权限 | 确认每个角色能用什么 | 生成 Resource Grant | 权限清单 |
| 6. 审批高危操作 | 在客户端确认高危动作 | 记录 approval | 审批记录 |
| 7. 执行任务 | 持续追加需求、查看进度 | Agnet 平台运行子 Agnet，按子环节推进开发 | 状态、日志、事件 |
| 8. SK 工具调用 | 允许平台使用技能能力 | Agnet 按权限调用 SK 工具和外部能力 | 中间产物、检查结果 |
| 9. 交付上线 | 确认部署结果 | Agnet 完成交付整理、部署并回写审计 | 生产服务 |
| 10. 维护升级 | 提出迭代或修复 | 复用上下文和权限再次进入 Agnet 闭环 | 新版本计划 |
## 关键任务状态流程
### 1. 初始入口
用户看到：
- 当前任务。
- 任务上下文状态。
- 模型余额和用量。
- 最近失败或待审批项。
- 客户端下载入口。
页面目标：
- 让用户知道下一步该做什么。
- 避免用户先进入复杂配置页。
### 2. 想法输入与追问
用户输入：
- 产品想法。
- 目标用户。
- 功能范围。
- 已有代码或是否从零开始。
- 部署目标。
- 风险和约束。
平台输出：
- 需求摘要。
- 产品文档草案。
- 原型描述。
- 推荐资源需求。
- 推荐子 Agnet 角色。
### 3. 任务上下文准备
用户应该看到简化路径：
```text
Heicode 判断本任务缺少哪些上下文
-> 用户授权代码、文档、SK 或云账号
-> 平台自动发现资源
-> 用户确认本任务允许使用的资源范围
-> Heicode 保存元数据和 secret_ref
```
任务上下文不要设计成大量裸字段表单。云账号授权后，应尽量自动展示已发现的 VM、数据库、对象存储、Kubernetes 或资源组。
### 4. 风险和权限确认卡
默认展示角色视角：
```text
Backend Agnet
- 可读写：后端代码路径
- 可读：项目文档
- 可部署：测试环境
- 生产部署：需要审批
```
高级用户可以打开 manifest 预览，但普通流程不应要求用户手写 manifest。
### 5. 开始执行前确认
展示：
- 本次目标。
- 子 Agnet 数量和角色。
- 每个角色使用的资源。
- 是否会访问密钥。
- 是否会部署云资源。
- 预计模型预算。
- 审批项。
用户确认后，Heicode 生成 Agnet 平台 payload。
### 6. 执行中的任务空间
展示：
- 子 Agnet 活跃状态。
- 当前步骤。
- 最近日志。
- 失败原因。
- 模型用量。
- 资源访问记录。
- 审批记录。
用户可以：
- 暂停任务。
- 停止任务。
- 查看日志。
- 撤销资源授权。
- 发起修复或继续迭代。
### 7. Agnet 执行闭环
Heicode 不是只把任务丢给 Agnet 一次就结束，而是会在开发过程中持续调用 Agnet 完成子环节。
闭环应表达为：
```text
客户端输入目标或追加需求
-> Heicode 生成下一步任务
-> Agnet 执行需求/设计/开发/测试/修复中的当前子环节
-> Agnet 按需要调用已授权的 SK 工具
-> Heicode 回传中间结果给客户端
-> 用户继续追问、修正或审批
-> Agnet 继续下一子环节
-> 最终由 Agnet 完成交付整理与部署
```
这意味着用户看到的不是一次性“已部署 Agent”，而是一个可连续推进的开发循环。
## 简化原则
1. 用户先表达目标，再补资源。
2. 用户选择资源，不手写底层配置。
3. 用户选择角色权限，不手写策略。
4. 高危操作单独审批，不埋在复杂表单里。
5. 技术细节可展开，但默认隐藏。
6. 所有资源、权限、模型、日志都回到同一个任务视角。
## 复杂度拆解
资源绑定复杂度来自三类问题：
| 复杂点 | 简化方式 |
|--------|----------|
| 云资源字段多 | 绑定云账号后自动发现资源 |
| 权限动作多 | 使用角色模板和推荐权限 |
| 密钥安全难理解 | 用户只看“密钥保管器已托管”，不看明文 |
## MVP 用户路径
MVP 最小路径：
1. 用户登录 Heicode。
2. 下载并登录客户端。
3. 输入一个产品想法。
4. 绑定一个 Git 仓库。
5. 绑定一个云账号或导入云资源。
6. 选择推荐角色。
7. 确认资源权限。
8. 预览 manifest。
9. 创建 Agnet 部署占位任务。
10. 在客户端持续推进子环节开发与测试。
11. 查看任务状态、日志、审计和交付结果。
当前唯一可延期项：Heicode 到 Agnet 平台真实部署 API 的完整联调。
docs/product-package/04-platform-usage-guide.md
+185
View File
@@ -0,0 +1,185 @@
# 04. 登录平台和使用平台指南
## 面向用户
本文面向第一次使用 Heicode 的普通用户，说明如何登录、绑定资源、下载客户端、创建任务和查看结果。
## 访问入口
平台入口：
```text
https://code.xinghanlab.com
```
用户只需要登录 Heicode。普通用户不需要登录 CodeGW 后台，也不需要登录 OpenBao。
## 第一步：登录 Heicode
1. 打开 `https://code.xinghanlab.com`。
2. 输入账号和密码，或使用平台支持的登录方式。
3. 登录成功后进入 Heicode 控制台。
4. 进入首页，查看资源、模型、任务和客户端下载状态。
登录后平台会读取：
- 用户 ID。
- 用户邮箱。
- 用户角色。
- `channelId`。
这些信息用于用户身份、CodeGW 额度和用量映射。
## 第二步：下载客户端
1. 在 Heicode 控制台进入 `客户端下载`。
2. 选择对应系统版本，例如 macOS 或 Windows。
3. 下载并安装 Heicode 客户端。
4. 打开客户端后，只需要登录 `https://code.xinghanlab.com`。
客户端不会要求选择模型提供方。客户端可用模型由 Heicode 提供。
macOS 提示说明：
- 如果安装时出现系统安全提示，说明当前安装包可能还没有完成 Apple Developer ID 签名和 notarization。
- 用户可以按平台提供的安装说明继续打开。
- 长期方案应完成签名和 notarization。
## 第三步：在客户端输入想法
主要在 Heicode 客户端输入要做的事情。Manager 负责下载、资源绑定、Agnet 部署、状态和审计等辅助能力，不承担主开发对话。
例如：
```text
我想做一个面向小团队的任务管理 SaaS，
需要登录、项目、任务、评论、通知和后台管理，
希望部署到 Azure。
```
平台会生成：
- 需求摘要。
- 产品文档草案。
- 推荐开发角色。
- 需要绑定的资源。
- 高危操作提示。
## 第四步：绑定资源
进入 `资源绑定`。
可绑定资源：
- 代码仓库。
- SK 仓库或技能包。
- 项目文档。
- 云账号。
- 云资源。
推荐流程：
```text
先绑定 Git
-> 再绑定项目文档或 SK
-> 再绑定云账号
-> 从云账号自动发现资源
-> 选择允许使用的云资源
```
用户不需要把密钥贴到文档里。真实凭证由 Heicode 写入密钥保管器，Heicode 只保存 `secret_ref`。
## 第五步：分配权限
用户可以使用平台推荐角色：
- Product Agnet。
- Architect Agnet。
- Frontend Agnet。
- Backend Agnet。
- Reviewer Agnet。
- Ops Agnet。
每个角色确认：
- 能访问哪些仓库。
- 能读写哪些路径。
- 能使用哪些云资源。
- 哪些操作需要审批。
- 授权是否有有效期。
## 第六步：确认高危操作
高危操作会在客户端审批。
常见高危操作：
- 生产部署。
- 修改数据库。
- 创建或删除云资源。
- 访问生产密钥。
- 大额模型预算消耗。
用户确认后，平台才会为子 Agnet 派生短期凭证。
## 第七步：启动任务
用户确认任务后，Heicode 会生成：
- 子 Agnet 角色。
- AGENT.md。
- resource context。
- permission manifest。
- 模型和预算配置。
- 审批策略。
Heicode 将这些内容提交给 Agnet 平台执行。
## 第八步：在客户端持续推进
任务开始后，主流程回到客户端。
闭环应理解为：
```text
客户端继续补充要求
-> Heicode 生成下一步子任务
-> Agnet 执行需求/开发/测试/修复/部署中的当前环节
-> Agnet 按权限调用需要的 SK 工具
-> 中间结果和失败原因回到客户端
-> 用户继续修正或审批
-> 最终返回交付物和部署结果
```
## 第九步：查看执行结果
用户可以在 Heicode 查看：
- 当前任务状态。
- 子 Agnet 活动状态。
- 运行日志。
- 失败原因。
- 模型用量。
- 资源访问记录。
- 高危审批记录。
- 部署结果。
## 第十步：维护和升级
上线后，用户可以继续输入：
- 修复 bug。
- 增加功能。
- 优化性能。
- 升级依赖。
- 调整部署资源。
Heicode 会复用已有项目上下文、资源绑定和审计信息。
## 用户注意事项
1. 不要把密钥写入需求、Markdown、聊天内容或 Git。
2. 授权云资源时先从测试环境开始。
3. 生产部署必须仔细确认审批内容。
4. 如果不确定某个资源是否应该授权，选择只读或暂不授权。
5. CodeGW 后台不是普通用户入口，模型和余额在 Heicode 中查看。
docs/product-package/05-ppt-copy.md
+191
View File
@@ -0,0 +1,191 @@
# 05. 产品 PPT 文案
## Slide 1：标题
标题：
> Heicode
副标题：
> 从一个想法，到可上线的软件产品
讲述：
Heicode 是一款全流程智能开发 Code 工具。它让用户输入想法，接入自己的代码和云资源，由 AI 开发团队完成需求、开发、检查、部署和维护。
## Slide 2：问题
标题：
> AI 已经会写代码，但软件交付仍然很难
要点：
- 想法到需求、原型、代码之间仍然断裂。
- AI 工具通常不能安全使用真实 Git、云资源和密钥。
- 多 Agent 协作缺少角色、权限、状态和审计。
- 模型用量、余额和日志分散在后台系统。
- 部署和后续维护没有统一生命周期。
## Slide 3：解决方案
标题：
> Heicode 把开发过程变成可编排的 AI 团队任务
要点：
- 用户输入自然语言目标。
- Heicode 生成任务、角色、权限和执行上下文。
- 客户端是主体验，Manager 负责资源、部署和审计辅助。
- 子 Agnet 按角色推进开发、测试、修复和部署，并可调用 SK 工具。
- 密钥进入密钥保管器，子 Agnet 只拿短期凭证。
- Heicode 展示模型用量、日志、事件和审计。
## Slide 4：产品工作流
标题：
> 一条从想法到上线的主流程
流程：
```text
登录
-> 客户端输入想法
-> Manager 绑定资源
-> Manager 部署 Agnet
-> 客户端继续推进任务
-> Agnet 执行开发/测试/修复并调用 SK
-> 审批高危操作
-> Agnet 交付与部署
-> 观测与维护
```
讲述：
用户不需要直接操作 CodeGW 后台，也不需要直接管理 OpenBao。所有操作都在 Heicode 和客户端内完成。
## Slide 5：核心能力
标题：
> Heicode 的四个核心能力
1. 想法转开发任务。
2. 资源绑定和权限分配。
3. 子 Agnet 编排和执行。
4. 用量、日志、安全和审计闭环。
## Slide 6：系统架构
标题：
> Heicode 产品面连接执行、模型和密钥底座
架构：
```text
用户 / 客户端
-> Heicode Manager
-> Agnet 平台
-> CodeGW
-> OpenBao
-> Git / SK / 云资源
```
讲述：
客户端是主体验，Manager 是辅助控制台。Agnet 平台是执行层，执行过程中可调用 SK。CodeGW 是模型网关和计费服务。OpenBao 是密钥保管器。
## Slide 7：安全模型
标题：
> 资源可用，密钥不外泄
要点：
- Heicode 服务端数据库只保存 `secret_ref`。
- 长期密钥进入 OpenBao。
- 子 Agnet 只获得短期、最小权限凭证。
- 高危操作必须在客户端审批。
- 日志、Markdown、前端响应不包含明文密钥。
## Slide 8：用户价值
标题：
> 让小团队拥有完整软件交付能力
对独立开发者：
- 更快从想法到 MVP。
对创业团队：
- 用更少人力完成产品迭代。
对企业团队：
- 在权限和审计边界内使用 AI 开发。
对技术负责人：
- 控制资源、成本、质量和风险。
## Slide 9：当前 MVP
标题：
> 当前 MVP 先闭环三件事
1. Heicode、CodeGW、OpenBao 解耦部署。
2. 资源绑定、Resource Grant、manifest 和密钥保管。
3. 客户端只登录 Heicode，只使用 Heicode 模型。
延期项：
- Heicode 到 Agnet 平台真实部署 API 的完整联调。
## Slide 10：路线图
标题：
> 从可用工具到生命周期平台
阶段：
1. 资源绑定和密钥保管。
2. CodeGW 用户侧模型和用量展示。
3. 客户端登录、审批和下载闭环。
4. Agnet 平台真实部署联调。
5. 自动维护、升级、成本和质量观测。
## Slide 11：演示故事
标题：
> 5 分钟看懂 Heicode
演示：
1. 登录 Heicode。
2. 客户端输入产品想法。
3. Manager 绑定 Git 和云资源。
4. Manager 部署 Agnet 并展示权限。
5. 客户端继续推进任务。
6. 展示 Agnet 调用 SK 和当前子环节。
7. 客户端审批高危操作。
8. 查看交付、部署结果、日志和模型用量。
## Slide 12：结束页
标题：
> Heicode，让想法进入真实开发流程
收尾语：
> 不是只生成代码，而是把产品、代码、权限、模型、部署和维护组织成一个可审计的软件生命周期。
docs/product-package/06-security-and-credential-management.md
+108
View File
@@ -0,0 +1,108 @@
# 06. 安全与凭证管理说明
## 核心原则
Heicode 是 SaaS 产品，不能把凭证管理转嫁给用户，也不能让密钥散落在 Git、Markdown、日志或子 Agnet 长期状态中。
安全目标：
1. 用户授权资源，平台托管凭证。
2. Heicode 服务端数据库只保存元数据和 `secret_ref`。
3. 长期密钥进入密钥保管器。
4. 子 Agnet 只拿短期、最小权限、可审计凭证。
5. 高危操作必须由客户端审批。
## 凭证分类
| 凭证 | 示例 | 存放位置 |
|------|------|----------|
| Git 凭证 | GitHub token、SSH key | 密钥保管器 |
| 云凭证 | Azure、AWS、GCP access key | 密钥保管器 |
| 数据库凭证 | DB password、connection secret | 密钥保管器 |
| CodeGW 服务凭据 | 内部服务 token | 服务环境或密钥保管器 |
| 短期凭证 | 临时云 token、临时 Git token | 运行时注入，TTL 到期失效 |
## 密钥保管器
用户可见名称：密钥保管器。
技术实现：OpenBao，兼容 Vault API。
用户不需要直接登录 OpenBao，也不需要看到 OpenBao 控制台。
## Secret Broker 流程
```text
用户绑定资源
-> Heicode 接收授权结果
-> Heicode Secret Broker 写入 OpenBao
-> OpenBao 返回或形成 secret_ref
-> Heicode DB 保存 secret_ref
-> 前端只展示脱敏引用和状态
```
Heicode 接口不得返回明文密钥。日志、错误信息、审计摘要也不得包含明文密钥。
## 子 Agnet 访问凭证
子 Agnet 不保存长期密钥。
推荐流程：
```text
Heicode 生成 Resource Grant
-> Agnet 平台部署子 Agnet
-> Agnet 平台绑定运行时身份
-> 子 Agnet 请求使用资源
-> 高危操作先走客户端审批
-> 审批通过后派生短期凭证
-> 短期凭证注入运行时
-> TTL 到期或任务结束后失效
```
## 高危操作
高危操作包括：
- 生产环境部署。
- 云资源创建、删除、扩缩容。
- 数据库迁移或写入。
- 访问生产密钥。
- 大额模型预算消耗。
审批必须记录：
- 审批人。
- 审批时间。
- 操作类型。
- 资源范围。
- 风险等级。
- TTL。
- 对应 deployment 或任务。
## 禁止事项
1. 禁止把 token 写入 Git。
2. 禁止把密钥写入 Markdown。
3. 禁止前端返回明文密钥。
4. 禁止在日志中打印密钥。
5. 禁止把长期云密钥注入子 Agnet。
6. 禁止把 OpenBao 暴露为普通公网入口。
7. 禁止把 CodeGW key 原文交给客户端长期保存。
## 用户侧解释
推荐文案：
> Heicode 会把你的授权凭证存入密钥保管器。平台只在你授权的范围内，为对应任务和角色生成短期访问能力。密钥不会写入 Git、文档、日志或子 Agnet 长期状态。
## 验收标准
| 验收项 | 标准 |
|--------|------|
| 数据库 | 只保存 `secret_ref`，不保存明文密钥 |
| 前端 | 不显示明文密钥 |
| 日志 | 不包含 token、password、private key、access key |
| 子 Agnet | 不保存长期凭证 |
| 高危操作 | 有客户端审批记录 |
| OpenBao | 不对普通公网暴露 |
docs/product-package/07-integration-boundaries.md
+148
View File
@@ -0,0 +1,148 @@
# 07. CodeGW、OpenBao、Agnet 平台边界说明
## 目标
本文用于讲清楚 Heicode 与 CodeGW、OpenBao、Agnet 平台之间的产品和技术边界，避免再次变成缝合式系统。
## 总体边界
| 系统 | 能力归属 | 普通用户是否直接进入 |
|------|----------|----------------------|
| Heicode | 产品总入口，包含客户端主体验与 Manager 辅助控制台 | 是 |
| CodeGW | 模型网关、模型调用、余额、额度、用量日志 | 否 |
| OpenBao | 长期凭证保管、短期凭证租约 | 否 |
| Agnet 平台 | AKS 执行层、状态、日志、事件、指标 | 否 |
## Heicode 与 CodeGW
Heicode 使用 CodeGW 的方式：
- 查询普通用户可见模型。
- 查询余额和额度。
- 查询用量和调用日志。
- 建立 `channelId`、CodeGW user、token 或 group 的映射。
Heicode 不做：
- CodeGW 渠道管理。
- CodeGW 模型供应商配置。
- CodeGW 价格配置。
- CodeGW 管理员用户管理。
- 把 CodeGW 后台开放给普通用户。
产品口径：
> CodeGW 是 Heicode 的模型网关和计费底座，用户在 Heicode 中查看模型和用量，不直接使用 CodeGW 后台。
## Heicode 与 OpenBao
Heicode 使用 OpenBao 的方式：
- 写入用户授权后的长期凭证。
- 保存和管理 `secret_ref`。
- 执行密钥 health、metadata、轮换、禁用、撤销。
- 为高危操作申请短期凭证。
Heicode 不做：
- 在数据库保存明文密钥。
- 把 OpenBao token 交给前端。
- 把 OpenBao 作为普通公网服务暴露。
产品口径：
> 密钥保管器负责保存凭证，Heicode 只保存引用。子 Agnet 使用资源时，平台按权限和审批结果获取短期访问能力。
## Heicode 与 Agnet 平台
Heicode 传给 Agnet 平台：
- 用户上下文。
- 任务目标。
- 子 Agnet 角色。
- AGENT.md。
- resource context。
- permission manifest。
- `secret_ref`。
- 审批策略。
- 模型和预算配置。
- `sk_context` / `tool_permissions`。
- 回调地址。
Agnet 平台回传 Heicode：
- deployment 状态。
- 子 Agnet 状态。
- 事件。
- 日志。
- 指标。
- 审计事件。
- 使用量。
- 当前子环节状态。
- 中间交付物。
- 部署结果。
Heicode 不传：
- 长期明文密钥。
- CodeGW key 原文。
- OpenBao root token。
- 数据库密码。
产品口径：
> Heicode 决定用户想做什么、能用什么资源和谁来做；Agnet 平台负责把这些任务安全运行起来，在过程中按权限调用需要的 SK 工具，并把子环节状态、交付物和部署结果回传给 Heicode。
## 客户端与 Manager 的边界
客户端主做：
- 登录 Heicode。
- 对话和任务输入。
- 继续补充要求和修正方向。
- 展示 Heicode 提供的模型。
- 高危操作审批。
- 查看执行反馈和交付结果。
Manager 主做：
- 账号与安全。
- 客户端下载。
- Git、文档、SK、云资源绑定。
- Agnet 部署。
- 任务状态、用量和审计查看。
- 风险与授权范围确认。
客户端不做：
- 选择模型提供方。
- 配置 CodeGW 渠道。
- 直接访问 OpenBao。
- 直接保存长期云密钥。
Manager 不做：
- 主开发对话。
- 网页编码。
- 替代客户端完成高危审批。
## 当前延期项
Heicode 到 Agnet 平台真实部署 API 的完整联调仍可延期。
但 Heicode 侧必须准备好：
- payload。
- manifest。
- 审计字段。
- callback URL。
- 本地占位控制面。
- 日志、事件、指标的数据展示位置。
## 验收口径
1. 普通用户只进入 Heicode。
2. 客户端只登录 Heicode。
3. CodeGW 独立服务运行。
4. OpenBao 只通过受控内网或后端访问。
5. Agnet 平台接口只收结构化上下文和 `secret_ref`，不收长期明文密钥。
docs/product-package/08-client-guide.md
+118
View File
@@ -0,0 +1,118 @@
# 08. Heicode 客户端说明
## 客户端定位
Heicode 客户端是用户主体验，承担本地对话、想法输入、任务推进、执行反馈、交付接收和高危审批。它不是独立模型配置工具，也不是 CodeGW 后台客户端。
Heicode Manager 不是主体验，但它仍然负责账号与安全、客户端下载、Git/云资源绑定、Agnet 部署、任务状态、余额与审计等辅助操作。用户不在网页上编码，主要在客户端里推进开发任务。
客户端必须保持：
- 只登录 Heicode。
- 只使用 Heicode 提供的模型。
- 不出现模型提供方选择。
- 不出现旧服务入口。
- 视觉风格与 Heicode 保持一致。
## 登录
客户端登录地址：
```text
https://code.xinghanlab.com
```
用户打开客户端后，点击登录，跳转或打开 Heicode 登录流程。登录完成后，客户端读取 Heicode 会话状态。
## 模型
客户端模型来源：
```text
Heicode
-> CodeGW 用户侧模型能力
-> 客户端展示可用模型
```
客户端不内置默认 Claude 模型，也不让用户选择模型提供方。用户看到什么模型，由 Heicode 和 CodeGW 映射决定。
## 主要功能
| 功能 | 说明 |
|------|------|
| 对话输入 | 用户描述产品想法、开发任务或维护需求 |
| 任务推进 | 继续要求、查看 Agnet 执行反馈、接收交付结果 |
| 任务状态 | 查看 Heicode 返回的任务和子 Agnet 进度 |
| 模型选择 | 从 Heicode 提供的模型中选择 |
| 高危审批 | 对生产部署、密钥访问、云操作做确认 |
| 日志反馈 | 展示关键执行反馈和失败原因 |
| 安装更新 | 从 Heicode 下载页获取安装包 |
## 客户端里的 Agnet 闭环
客户端里发生的不是单次对话，而是持续推进的任务闭环：
```text
用户输入想法或补充要求
-> Heicode 判断当前子任务
-> 调用 Agnet 执行需求/开发/测试/修复/部署中的某一环
-> Agnet 按权限调用需要的 SK 工具
-> 中间结果、失败原因和下一步建议回到客户端
-> 用户继续补充、修正或审批
-> Agnet 继续推进
-> 最终返回交付物和部署结果
```
所以客户端应该更像“任务驾驶舱”，而不是一次性聊天窗口。
## 高危审批体验
审批弹窗应清楚展示：
- 操作类型。
- 目标资源。
- 请求角色。
- 风险等级。
- 有效期。
- 预计影响。
- 是否会派生短期凭证。
用户操作：
- 批准。
- 拒绝。
- 查看详情。
## 安装包分发
安装包由 Heicode 下载页提供。
平台：
- macOS arm64。
- Windows。
- 后续可扩展 Linux。
macOS 注意：
- 如果未完成 Developer ID 签名和 notarization，系统可能弹出安全提示。
- 产品文案应说明当前安装方式和后续签名计划。
## 客户端不应该出现的内容
1. 模型提供方配置。
2. 旧登录入口。
3. 第三方路由登录入口。
4. CodeGW 后台入口。
5. OpenBao 地址或 token。
6. 长期云密钥输入框。
7. 无法解释的个人 API key 自动复制。
## 验收标准
1. 打开客户端只看到 Heicode 登录入口。
2. 登录地址是 `https://code.xinghanlab.com`。
3. 模型列表来自 Heicode。
4. 没有模型提供方菜单。
5. 没有旧品牌和旧模型默认文案。
6. 高危审批能明确展示风险和资源范围。
docs/product-package/09-demo-script.md
+177
View File
@@ -0,0 +1,177 @@
# 09. 产品演示脚本
## 演示目标
用 5 分钟讲清楚 Heicode 的核心价值：
> 用户从一个想法开始，绑定自己的代码和云资源，由 Heicode 组织 AI 开发团队完成开发、部署和审计。
## 演示准备
演示账号：
- 使用演示专用账号。
- 不展示真实密码。
- 不使用真实生产密钥。
演示资源：
- 一个演示 Git 仓库。
- 一个演示 SK 仓库或技能包。
- 一个演示云资源列表。
- 一个可展示的模型余额或用量页面。
- 一个客户端安装包下载入口。
## 5 分钟脚本
### 0:00 到 0:30 开场
话术：
> 今天演示 Heicode。它不是一个普通聊天工具，也不是 CodeGW 后台，而是一个从想法到生产的软件生命周期工具。用户输入想法，平台组织 AI 开发团队，并在权限和审计边界内使用代码、文档和云资源。
展示：
- 首页或 Heicode 登录页。
- 一句话定位。
### 0:30 到 1:00 登录和首页
操作：
1. 登录 `https://code.xinghanlab.com`。
2. 进入 Heicode 工作区。
话术：
> 用户只登录 Heicode。模型、资源、任务、日志和客户端下载都从这里进入，普通用户不需要进入 CodeGW 后台，也不需要直接接触密钥保管器。
展示：
- 首页。
- 模型或余额摘要。
- 客户端下载入口。
### 1:00 到 1:45 输入想法
操作：
输入演示想法：
```text
我想做一个小团队任务管理 SaaS，
需要登录、项目、任务、评论、通知和后台管理，
希望部署到 Azure。
```
话术：
> Heicode 先把自然语言想法整理成产品目标、功能范围、开发任务和需要的资源。
展示：
- 需求摘要。
- 推荐角色。
- 资源需求提示。
### 1:45 到 2:30 资源绑定
操作：
1. 打开资源绑定。
2. 选择演示 Git 仓库。
3. 选择演示云资源。
4. 展示密钥保管状态。
话术：
> 资源绑定不是把密钥贴到页面里。用户授权后，真实凭证进入密钥保管器，Heicode 只保存 secret_ref。子 Agnet 能看到的是资源元数据和权限，不是长期密钥。
展示：
- Git 资源。
- 云资源。
- `secret_ref` 或密钥保管状态。
### 2:30 到 3:15 角色和权限
操作：
1. 展示推荐子 Agnet 角色。
2. 打开某个角色权限。
3. 展示 manifest 预览。
话术：
> Heicode 会把资源按角色授权。例如 Backend Agnet 可以读写后端路径，Ops Agnet 可以部署测试环境，生产部署需要客户端审批。
展示：
- Product、Backend、Frontend、Reviewer、Ops 角色。
- Resource Grant。
- manifest 预览。
### 3:15 到 4:00 客户端和审批
操作：
1. 展示客户端下载入口。
2. 展示客户端登录只指向 Heicode。
3. 展示高危审批弹窗或审批设计稿。
话术：
> 客户端不选择模型提供方，也不配置 CodeGW。它只登录 Heicode，使用 Heicode 提供的模型。高危操作，例如生产部署或访问生产密钥，必须在客户端确认。
展示：
- 客户端登录页。
- 模型选择。
- 审批弹窗。
### 4:00 到 4:40 执行和观测
操作：
1. 切回客户端，追加一句新要求。
2. 展示当前 Agnet 子环节和 SK 工具调用。
3. 展示任务状态、日志、模型用量和审计。
话术：
> 主体验在客户端。用户继续补充要求后，Heicode 会调用 Agnet 推进下一子环节，例如开发、测试或修复。Agnet 在过程中还可以调用已授权的 SK 工具，最后把中间结果、交付物和部署结果回传回来。Manager 负责辅助查看状态、日志、用量和审计。
展示：
- 客户端追加需求。
- 当前 Agnet 子环节和 SK 工具调用。
- 子 Agnet 状态。
- 日志。
- 用量。
- 审计记录。
### 4:40 到 5:00 总结
话术：
> Heicode 的核心不是只生成代码，而是把想法、代码、云资源、模型、密钥、权限、部署和维护组织成一个可审计的软件生命周期。
结束 CTA：
- 开始使用 Heicode。
- 查看产品文档。
- 下载客户端。
## 演示注意事项
1. 不展示真实密钥。
2. 不进入 CodeGW 管理后台。
3. 不展示 OpenBao token。
4. 不强调底层配置复杂度，强调用户流程。
5. 如果 Agnet 真实部署尚未联调，明确说当前展示的是 Heicode 侧 payload、manifest 和占位控制面。
## 备用 1 分钟版本
话术：
> Heicode 是从想法到上线的智能开发工具。用户主要在客户端输入想法和继续推进任务，在 Manager 绑定 Git、文档、SK 和云资源并部署 Agnet。Heicode 生成子 Agnet 团队、角色和权限，密钥进入密钥保管器，子 Agnet 只拿短期凭证。Agnet 在执行中可以调用 SK 工具，最后完成交付与部署；CodeGW 提供模型、余额和用量，Heicode 展示日志、状态和审计。用户不需要进入 CodeGW 后台，也不需要管理 OpenBao，只在 Heicode 和客户端完成整个开发流程。
docs/product-package/10-frontend-detail-spec.md
+328
View File
@@ -0,0 +1,328 @@
# 10. 前端细节说明
## 目标
本文用于指导 Heicode 和 Heicode 客户端的前端产品设计。重点不是罗列后台页面，而是明确用户如何在一个任务空间里完成“想法 -> 追问 -> 上下文授权 -> 执行 -> 审批 -> 交付”。
## 设计原则
1. 第一屏只强调“你想做什么”。
2. 主流程围绕当前任务展开，不围绕后台模块展开。
3. 资源、权限、模型、日志和审计都作为任务上下文出现。
4. 复杂配置默认由 Heicode 解释成确认卡片，高级细节可以展开。
5. 密钥永不明文展示，只展示密钥保管状态和 `secret_ref`。
6. 客户端只登录 Heicode，只展示 Heicode 提供的模型。
7. 页面状态必须覆盖空态、加载、错误、成功、撤销和过期。
## 全局体验结构
Heicode 不以后台菜单作为主体验。建议使用顶部轻量入口和主任务空间：
| 入口 | 作用 | 出现方式 |
|------|------|----------|
| 输入想法 | 创建新产品、新功能或维护任务 | 首屏主输入框 |
| 当前任务 | 查看草案、上下文、执行状态和下一步 | 首页主区域和任务详情 |
| 资源上下文 | 选择本任务可用的代码、文档、SK、云资源 | 任务准备卡片 |
| 风险确认 | 确认可用资源、禁止动作和审批规则 | 开始执行前确认卡 |
| 执行记录 | 查看日志、用量、资源访问和审计 | 任务详情抽屉 |
| 客户端下载 | 下载本地客户端并完成高危审批 | 顶部辅助入口或审批提示 |
产品面边界需要在信息架构中明确：
- Heicode 客户端是主任务驾驶舱。
- Heicode Manager 是资源、部署、状态、余额和审计的辅助控制台。
- 用户不在网页上编码，但会在网页完成辅助管理动作。
禁止普通用户体验出现：
- CodeGW 后台。
- 渠道管理。
- 模型供应商配置。
- OpenBao 控制台。
- 模型提供方选择。
- 旧服务入口。
## 视觉风格
| 元素 | 要求 |
|------|------|
| 色系 | Heicode 与客户端保持统一，专业、可信、低噪音 |
| 布局 | 任务空间优先，辅助信息以抽屉、浮层或卡片呈现 |
| 卡片 | 只用于任务、上下文、审批、交付物等明确对象 |
| 按钮 | 主按钮用于继续任务，次按钮用于查看详情或取消 |
| 状态 | 使用清晰标签：待确认、运行中、待审批、失败、已完成、已撤销 |
| 图标 | 资源、审批、日志、模型、客户端下载使用稳定图标语义 |
## 初始首页
### 目标
让用户登录后马上知道可以输入想法或继续任务。
### 内容
| 区块 | 内容 |
|------|------|
| 主输入 | “你想把什么想法变成可以上线的软件？” |
| 继续任务 | 最近任务、运行状态、待审批提示 |
| 今日焦点 | 当前最重要任务、失败任务、待确认事项 |
| 辅助入口 | 客户端下载、账户安全、最近审计 |
### 空态文案
> 输入一个产品想法，Heicode 会帮你生成任务、需要的上下文和执行计划。
## 想法输入与追问
### 目标
把用户自然语言输入转成可执行任务，而不是让用户先填完整表单。
### 初始输入
只展示一个多行输入框。用户可以说产品想法、开发任务、修复目标或维护诉求。
### Heicode 追问
Heicode 只追问影响执行路径的少量问题：
| 问题 | 选项示例 |
|------|----------|
| 是否基于已有代码 | 从零开始 / 选择已有仓库 |
| 是否需要部署 | 暂不部署 / 测试环境 / 生产环境需审批 |
| 执行风格 | 保守 / 平衡 / 主动 |
| 预算限制 | 使用默认 / 自定义预算 |
更多约束放在“继续补充要求”中，不作为第一屏表单。
## 任务卡
### 目标
让用户确认“我要做什么”和“第一版做到哪里”。
### 内容
| 区块 | 内容 |
|------|------|
| 目标 | Heicode 总结的产品或任务目标 |
| 第一版范围 | 功能清单、交付边界、暂不做事项 |
| 自动生成 | 产品说明、原型描述、开发任务、检查清单、部署步骤 |
| 待确认上下文 | 代码和文档、云资源、风险审批 |
### 交互
- 用户可以直接修改目标。
- 用户可以继续用自然语言补充要求。
- 下一步不是“去配置资源”，而是“确认任务，准备上下文”。
## 任务上下文卡
### 目标
让用户理解这个任务需要哪些上下文，并用最少操作授权。
### 卡片类型
| 卡片 | 用户看到的内容 | 系统处理 |
|------|----------------|----------|
| 代码上下文 | 选择仓库或从零开始 | 保存仓库元数据和授权引用 |
| 文档和 SK | 选择已有产品文档或 SK 仓库 | 作为任务上下文提供给执行层 |
| 云资源 | 连接云账号并自动发现资源 | 展示可用资源和风险级别 |
| 密钥保管 | 凭证将保存到密钥保管器 | 前端不展示明文密钥 |
### 简化要求
- 云账号绑定后优先自动发现 VM、数据库、对象存储、Kubernetes 或资源组。
- 不要求用户手写 VM ID、数据库 ID、AKS ID 等复杂字段。
- 对不能自动发现的资源提供“手动补充”兜底，但放在次级入口。
- 默认推荐低风险资源，高风险资源默认不选。
## 执行前确认卡
### 目标
让用户在开始前确认结果、边界和风险。
### 内容
| 区块 | 内容 |
|------|------|
| 本次会做 | 需求、代码、检查、测试部署等 |
| 本次允许使用 | 仓库、文档、SK、测试云资源 |
| 本次不会做 | 生产部署、生产数据库访问、导出长期密钥 |
| 高危规则 | 生产部署、生产密钥访问、破坏性操作必须客户端审批 |
| 预计消耗 | 模型预算或任务预算 |
### 高级展开
高级用户可以展开 manifest 预览，但默认折叠。展开后只展示：
- `resource_id`
- `resource_type`
- `allowed_actions`
- `constraints`
- `secret_ref`
不得展示明文密钥。
## 执行中的任务空间
### 目标
让用户看到任务进展、产物和下一步。
### 内容
| 区块 | 内容 |
|------|------|
| 当前子环节 | 需求、设计、后端、前端、检查、测试、部署的阶段状态 |
| Agnet 调用 | 当前角色、正在调用的 SK 工具、工具输出摘要 |
| 最新动态 | Heicode 翻译后的关键执行事件 |
| 当前产物 | 产品文档、接口草案、代码变更、检查报告 |
| 继续输入 | 用户继续追加需求或修正方向 |
| 交付回流 | 交付物、测试结果、部署结果、待审批动作 |
| 辅助查看 | 资源使用、模型消耗、审计记录、停止任务 |
### 交互要求
- 日志默认摘要化，用户需要时再展开原始日志。
- 失败必须展示可理解原因和建议动作。
- 停止任务要说明影响范围。
- 当前子环节必须可见，不能只显示“运行中”。
- 如果 Agnet 调用了 SK 工具，前端要展示“调用了什么、产出了什么、是否失败”。
- 交付和部署结果必须回到客户端任务空间，而不是只留在后台日志里。
## 任务用量与审计
### 目标
回答“本任务用了什么模型、访问了什么资源、谁批准了什么”。
### 呈现方式
默认作为任务详情里的抽屉或浮层，不作为主体验。
### 内容
| 类型 | 示例 |
|------|------|
| 模型用量 | 任务、模型、消耗、状态、失败原因 |
| 资源访问 | 仓库、文档、云资源、动作、角色 |
| 审批记录 | 批准、拒绝、过期、有效期 |
| 安全记录 | 密钥轮换、短期凭证租约、撤销 |
## 交付结果
### 目标
让用户看到完成结果、质量证明和下一步。
### 内容
| 区块 | 内容 |
|------|------|
| 交付物 | 产品说明、代码变更、测试环境、部署链接 |
| 质量结果 | 代码检查、安全检查、测试结果 |
| 可信记录 | 使用资源、模型消耗、高危审批 |
| 继续动作 | 继续迭代、发起维护任务、查看完整记录 |
## 客户端下载
### 目标
让用户清楚下载哪个客户端，以及安装后只登录 Heicode。
### 内容
| 区块 | 内容 |
|------|------|
| 推荐版本 | 根据系统提示 macOS 或 Windows |
| 下载列表 | macOS arm64、Windows |
| 安装说明 | macOS 安全提示、Windows 安装说明 |
| 登录说明 | 只登录 `https://code.xinghanlab.com` |
| 版本信息 | 版本号、构建时间、校验值 |
## 账户与安全
### 目标
管理账号基础信息、安全设置和通知。
### 禁止
- 不自动生成无法解释的普通密钥。
- 若未来需要 API 令牌，命名为“Heicode API 访问令牌”，并说明用途、权限、过期时间和撤销方式。
- 无用途的 Token 入口应删除。
## 客户端前端细节
### 登录
只保留：
- Heicode 品牌。
- Heicode 登录按钮。
- 登录地址说明：`https://code.xinghanlab.com`。
- 登录失败提示。
不出现：
- 模型提供方卡片。
- 旧服务入口。
- 第三方路由入口。
- Claude 默认模型说明。
### 主对话
显示：
- 当前任务。
- 输入框。
- Heicode 提供的模型列表。
- 文件和资源上下文。
- 执行状态。
### 高危审批
字段：
- 操作名称。
- 风险等级。
- 目标资源。
- 请求角色。
- 有效期。
- 是否需要短期凭证。
- 批准/拒绝按钮。
文案示例：
> Heicode 请求在生产环境执行数据库迁移。该操作将使用密钥保管器派生的 15 分钟短期凭证。请确认资源、范围和影响后再批准。
## 响应式要求
| 视口 | 要求 |
|------|------|
| 桌面 | 顶部入口 + 主任务空间 + 可选右侧上下文 |
| 平板 | 顶部入口收进更多操作，主流程保持单列 |
| 手机 | 只保留继续输入、查看状态和审批能力 |
## 状态清单
每个关键状态必须设计：
- 加载态。
- 空态。
- 成功态。
- 错误态。
- 权限不足态。
- 网络异常态。
- 撤销/禁用后的只读态。
## 文案规则
- 用“任务上下文”或“资源上下文”，不要把主流程叫成资源管理。
- 用“密钥保管器”，不用“OpenBao”作为普通用户标题。
- 用“客户端”，不用“本地模型提供方”。
- 用“模型与余额”，不用“CodeGW 后台”。
- 用“执行计划”，不用“控制面草案”。
docs/product-package/11-product-prototype-wireframes.md
+454
View File
@@ -0,0 +1,454 @@
# 11. Heicode 客户端主体验与 Manager 辅助控制台原型图
## 说明
本文是 Heicode 产品的低保真原型图，用来说明 Heicode 客户端和 Heicode Manager 分别承担什么用户体验。
核心边界：
- Heicode 客户端是主体验。用户主要在客户端里对话、描述想法、推进开发任务、查看执行反馈和审批高危操作。
- Heicode Manager / 浏览器控制台是辅助控制台。它负责账号与安全、客户端下载、Git 绑定、云资源绑定、Agnet 部署、任务状态总览、模型余额与用量、审计与日志查看。
- 用户不在网页上编码，也不在网页上完成主要开发对话。
- 用户会在 Manager 里做辅助操作和观测，但主开发体验仍然在客户端。
- CodeGW、密钥保管器、Agnet 平台后台都不是普通用户入口，只作为 Heicode 的底层能力。
## 原型范围
| 范围 | 是否属于本文原型 | 说明 |
|------|------------------|------|
| Heicode 客户端 | 是，主体验 | 本地对话、想法输入、任务推进、执行反馈、高危审批 |
| Heicode Manager / 浏览器控制台 | 是，辅助控制台 | 账号与安全、客户端下载、Git/云资源绑定、Agnet 部署、任务总览、余额与审计 |
| 网页编码界面 | 否 | 用户不在网页上编码 |
| 底层服务后台 | 否 | CodeGW、密钥保管器、Agnet 平台后台不直接暴露给普通用户 |
## 原型原则
1. 客户端承载“我要做什么”和“继续开发”的主流程。
2. Manager 承载资源准备、部署准备、任务总览、用量和审计等辅助能力。
3. 主开发对话、编码推进和高危审批仍然以客户端为主。
4. 高危动作必须在客户端清晰审批。
5. 继续开发时，Heicode 会持续调用 Agnet 推进需求、开发、测试、修复和部署等子环节。
6. Agnet 执行过程中可以按权限调用 SK 工具。
7. Manager 可以查看任务状态、用量和审计，但不把网页设计成 IDE 或网页编码工作台。
8. 客户端只登录 Heicode，只使用 Heicode 提供的模型。
## 总体关系
```mermaid
flowchart LR
Client["Heicode 客户端主体验"] --> Idea["输入想法 / 继续开发"]
Idea --> Task["生成任务卡"]
Task --> Manager["Manager 准备资源 / 查看辅助信息"]
Manager --> Deploy["Manager 部署 Agnet"]
Deploy --> Loop["Agnet 子环节循环"]
Loop --> Dev["需求 / 开发 / 测试 / 修复"]
Dev --> SK["按权限调用 SK 工具"]
SK --> Run["执行反馈和对话"]
Run --> Approval["高危审批"]
Approval --> Loop
Run --> Result["交付结果 / 部署结果"]
Manager --> Git["绑定 Git"]
Manager --> Cloud["绑定云资源"]
Manager --> Audit["任务总览 / 用量 / 审计"]
Manager --> Download["客户端下载 / 账号安全"]
Git --> Deploy
Cloud --> Deploy
Result --> Client
```
## 1. 客户端登录
客户端是用户进入 Heicode 主体验的入口。
```text
┌──────────────────────────────────────────────┐
│ │
│ Heicode │
│ 从一个想法，到可上线的软件产品 │
│ │
│ 登录地址 │
│ https://code.xinghanlab.com │
│ │
│ [登录 Heicode] │
│ │
│ 登录后，客户端会使用 Heicode 提供的模型。 │
│ │
└──────────────────────────────────────────────┘
```
### 设计意图
- 不出现模型提供方选择。
- 不出现旧服务入口或第三方路由入口。
- 登录目标只有 Heicode。
## 2. 客户端主界面
用户在客户端里输入想法、继续开发、查看反馈。
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ Heicode Client 模型：heicode-code 用户头像 │
├──────────────────────────────────────────────────────────────────────────────┤
│ 当前任务：未选择 │
│ │
│ 你想把什么想法变成可以上线的软件？ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 做一个小团队任务管理 SaaS，需要登录、任务、评论、通知，部署到 Azure。 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ [发送] │
│ │
│ 最近任务 │
│ ┌────────────────────────────┐ ┌────────────────────────────┐ │
│ │ 小团队任务管理 SaaS │ │ 企业微信通知集成 │ │
│ │ 后端实现中 │ │ 等待生产部署审批 │ │
│ └────────────────────────────┘ └────────────────────────────┘ │
│ │
│ 辅助：打开 Manager 绑定资源、部署 Agnet、查看状态 │
└──────────────────────────────────────────────────────────────────────────────┘
```
### 设计意图
- 主界面像本地开发对话空间，不像后台控制台。
- 用户不在网页上编码，主要通过客户端持续表达需求和接收反馈。
- Manager 承担辅助配置和观测，但不是主开发对话空间。
## 3. 客户端追问和任务卡
Heicode 在客户端里追问关键缺口，并生成任务卡。
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ Heicode Client / 小团队任务管理 SaaS │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ 你：做一个小团队任务管理 SaaS，需要登录、任务、评论、通知，部署到 Azure。 │
│ │
│ Heicode：我可以开始整理任务。还需要确认 3 件事： │
│ │
│ 1. 基于已有仓库还是从零开始？ │
│ [从零开始] [选择已有仓库] │
│ │
│ 2. 第一版是否需要部署？ │
│ [暂不部署] [Azure 测试环境] [生产环境，需审批] │
│ │
│ 3. 执行风格？ │
│ [保守] [平衡] [主动] │
│ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ 继续补充你的要求... │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘
```
任务卡：
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ 小团队任务管理 SaaS / 任务卡 │
├──────────────────────────────────────────────────────────────────────────────┤
│ 目标：做一个面向小团队的任务协作 SaaS。 │
│ │
│ 第一版范围 │
│ - 登录和团队空间 │
│ - 项目、任务、评论 │
│ - 通知能力 │
│ - Azure 测试环境部署 │
│ │
│ Heicode 将自动生成 │
│ 产品说明 / 原型描述 / 开发任务 / 检查清单 / 部署步骤 │
│ │
│ 需要 Manager 辅助确认 │
│ [绑定 Git] [绑定云资源] [部署 Agnet] [查看预算与审计] │
│ │
│ [修改目标] [去 Manager 准备] │
└──────────────────────────────────────────────────────────────────────────────┘
```
## 4. Manager 辅助控制台
Manager 是网页端辅助控制台，不是编码主体验，但依然承载资源、部署、账号、下载、任务状态、余额和审计等辅助操作。
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ Heicode Manager 模型余额 ¥128.40 用户头像 │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ 当前任务辅助状态：小团队任务管理 SaaS │
│ │
│ ┌────────────────────────────┐ ┌────────────────────────────┐ │
│ │ Git 绑定 │ │ 云资源绑定 │ │
│ │ repo-main / main │ │ Azure / aks-test / db-dev │ │
│ └────────────────────────────┘ └────────────────────────────┘ │
│ ┌────────────────────────────┐ ┌────────────────────────────┐ │
│ │ 模型与余额 │ │ 审计与风险 │ │
│ │ ¥128.40 / 今日 ¥12.30 │ │ 1 个高危审批待处理 │ │
│ └────────────────────────────┘ └────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ Agnet 部署 │ │
│ │ 角色：Product / Backend / Frontend / Reviewer / Ops │ │
│ │ 状态：待部署 │ │
│ │ [部署 Agnet] │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 你可以在这里做辅助操作： │
│ [下载客户端] [查看任务状态] [确认资源范围] [查看审计记录] [管理账户安全] │
│ │
│ 提示：想法输入、开发对话、编码推进和审批请回到 Heicode 客户端。 │
└──────────────────────────────────────────────────────────────────────────────┘
```
### 设计意图
- Manager 展示资源、部署、任务状态、余额和审计等辅助信息。
- Manager 不承载网页编码。
- Manager 不替代客户端对话主流程。
## 5. Manager 绑定 Git 和云资源
Git 和云资源在 Manager 中绑定，作为部署 Agnet 的前置条件。
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ Heicode Manager / 绑定 Git 和云资源 │
├──────────────────────────────────────────────────────────────────────────────┤
│ 客户端任务：小团队任务管理 SaaS │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ Git 仓库 │ │
│ │ 状态：还没有可用仓库 │ │
│ │ [授权 GitHub/GitLab/Gitee/自建 Git] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 云资源 │ │
│ │ 已发现：aks-test、db-dev、aks-prod、db-prod │ │
│ │ [选择本任务允许使用的资源] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ [保存资源绑定] [继续部署 Agnet] │
└──────────────────────────────────────────────────────────────────────────────┘
```
### 设计意图
- Git 和云资源绑定属于 Manager。
- 用户不在网页上写代码。
- 绑定完成后可以继续部署 Agnet，也可以返回查看任务状态与辅助信息。
## 6. Manager 云资源自动发现
```text
┌────────────────────── Heicode 发现了可用 Azure 资源 ────────────────────────┐
│ │
│ 你不需要手动填写资源 ID。请选择客户端任务允许使用的范围： │
│ │
│ 建议用于本任务 │
│ [x] aks-test Kubernetes 测试部署 │
│ [x] db-dev PostgreSQL 开发读写 │
│ │
│ 高风险资源 │
│ [ ] aks-prod Kubernetes 生产部署，需要客户端审批 │
│ [ ] db-prod PostgreSQL 生产数据，默认禁止 │
│ │
│ 凭证处理 │
│ 长期凭证保存到密钥保管器。执行时只申请短期凭证。 │
│ │
│ [取消] [允许本任务使用] │
└──────────────────────────────────────────────────────────────────────────────┘
```
## 7. Manager 部署 Agnet
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ Heicode Manager / 部署 Agnet │
├──────────────────────────────────────────────────────────────────────────────┤
│ 任务：小团队任务管理 SaaS │
│ │
│ 已绑定资源 │
│ - Git：repo-main / main │
│ - 云资源：aks-test、db-dev │
│ │
│ Agnet 角色 │
│ [x] Product 需求和验收 │
│ [x] Backend API / 数据模型 │
│ [x] Frontend 页面和交互 │
│ [x] Reviewer 质量和安全检查 │
│ [x] Ops 测试环境部署 │
│ │
│ 安全边界 │
│ - 生产部署需要客户端审批 │
│ - 生产数据默认禁止 │
│ - 长期密钥不下发给 Agnet │
│ │
│ [返回修改资源] [部署 Agnet] │
└──────────────────────────────────────────────────────────────────────────────┘
```
### 设计意图
- Manager 的最终动作是部署 Agnet。
- Manager 不继续承担开发任务执行。
- 部署完成后主流程回到客户端，但状态和审计仍可在 Manager 查看。
## 8. 客户端执行空间
Agnet 部署完成后，主流程回到客户端。
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ Heicode Client / 小团队任务管理 SaaS 运行中 ¥12.30 │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Heicode：Agnet 已部署，我开始推进当前开发任务。 │
│ │
│ 当前 Agnet 子环节 │
│ - 需求和原型：已完成 │
│ - 后端开发：进行中 │
│ - 前端开发：等待接口确认 │
│ - 代码检查：等待代码变更 │
│ - 测试部署：等待构建 │
│ │
│ 正在调用的能力 │
│ - Git 代码仓库：已授权 │
│ - SK 工具：e2e-test / deploy-check / api-review │
│ │
│ 当前产物 │
│ [产品文档] [接口草案] [代码变更] [检查报告] │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 继续实现通知功能，并在完成后给我一份测试结果。 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ [发送] │
│ │
│ 辅助查看：打开 Manager 查看 Git/云资源绑定、Agnet 部署、用量和审计 │
└──────────────────────────────────────────────────────────────────────────────┘
```
### 设计意图
- 主执行反馈在客户端。
- 用户看到的是 Agnet 持续推进的子环节，而不是一次性执行结果。
- Agnet 可以在执行过程中调用已授权的 SK 工具。
- Manager 仍然是资源、部署、状态、余额和审计的辅助入口。
- 用户持续通过自然语言推进任务。
## 9. 客户端高危审批
高危动作必须在客户端确认。
```text
┌──────────────────────── Heicode 高危操作审批 ───────────────────────────────┐
│ │
│ 任务：小团队任务管理 SaaS │
│ 请求：部署到生产环境 │
│ 资源：aks-prod │
│ 风险：会更新对外服务 │
│ 凭证：将申请 15 分钟短期凭证 │
│ │
│ Heicode 建议：先完成测试环境验证，再批准生产部署。 │
│ │
│ [拒绝] [稍后提醒] [批准 15 分钟] │
└──────────────────────────────────────────────────────────────────────────────┘
```
## 10. 客户端交付结果
```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ Heicode Client / 小团队任务管理 SaaS 已完成 │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Heicode：第一版已完成，Agnet 已整理交付物并完成目标环境部署。 │
│ │
│ 交付物 │
│ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │
│ │ 产品说明 │ │ 代码变更 │ │ 测试环境 / 生产环境 │ │
│ │ 查看 / 导出 │ │ 查看 diff │ │ 打开服务 / 看部署记录 │ │
│ └────────────────────┘ └────────────────────┘ └────────────────────┘ │
│ │
│ 质量结果 │
│ - 代码检查：通过 │
│ - 安全检查：1 个问题已修复 │
│ - 部署：测试环境成功，生产环境待你确认后可继续 │
│ │
│ [继续迭代] [发起维护任务] [查看 Agnet 部署信息] │
└──────────────────────────────────────────────────────────────────────────────┘
```
## 11. 移动端
移动端只做三件事：继续输入、查看状态、审批风险。
```text
┌────────────────────────┐
│ Heicode │
├────────────────────────┤
│ 你想继续做什么？ │
│ ┌────────────────────┐ │
│ │ 输入想法或追加需求 │ │
│ └────────────────────┘ │
├────────────────────────┤
│ 当前任务 │
│ 小团队任务管理 SaaS │
│ 后端开发中 │
├────────────────────────┤
│ 待审批 │
│ 生产部署请求 │
│ [查看] │
├────────────────────────┤
│ 本次消耗 ¥12.30 │
└────────────────────────┘
```
## 不应该画成什么
这些不是 Heicode Manager 的主体验：
```text
┌────────────────────┐
│ 网页代码编辑器 │
│ 网页主开发对话 │
│ 网页编码推进 │
│ 任务推进 │
└────────────────────┘
```
正确表达应该是：
```text
客户端说目标
-> Heicode 生成任务
-> Manager 绑定 Git 和云资源
-> Manager 部署 Agnet
-> 客户端持续追加需求和修正方向
-> Agnet 执行需求、开发、测试、修复等子环节
-> Agnet 按权限调用 SK 工具
-> 客户端接收中间结果并审批高危动作
-> Agnet 完成交付整理和部署
-> Manager 提供状态、余额、下载和审计辅助
-> 客户端接收交付结果
```
## 页面关系图
```mermaid
flowchart TD
ClientHome["客户端输入想法"] --> ClientAsk["客户端追问缺口"]
ClientAsk --> Task["客户端任务卡"]
Task --> Manager["Manager 绑定资源 / 查看状态"]
Manager --> Deploy["Manager 部署 Agnet"]
Deploy --> Loop["Agnet 子环节循环"]
Loop --> ClientRun["客户端执行空间"]
Loop --> SK["SK 工具调用"]
SK --> ClientRun
Manager --> Audit["Manager 审计 / 余额 / 下载"]
ClientRun --> Approval["客户端高危审批"]
Approval --> Loop
ClientRun --> Result["客户端交付结果"]
Result --> ClientHome
```
docs/product-package/12-narrated-user-operation-flow.md
+341
View File
@@ -0,0 +1,341 @@
# 12. 口述用户操作流程
## 使用场景
本文用于产品演示、培训、录屏旁白和销售讲解。语气以真实用户操作为主，不讲复杂技术实现；当需要解释安全、模型、密钥和 Agnet 平台时，只讲用户需要理解的边界。
## 一句话开场
> 我现在打开 Heicode，从一个产品想法开始，绑定我的代码和云资源，让平台生成 AI 开发团队，并在我确认权限和高危操作后推进开发、部署和维护。
## 完整口述流程
### 1. 打开平台
我先打开 Heicode 的平台地址：
```text
https://code.xinghanlab.com
```
这里是 Heicode 的浏览器控制台，也就是 Heicode Manager。后续我不会直接进入 CodeGW 后台，也不会直接进入密钥保管器后台。Manager 负责资源、部署、状态和审计等辅助动作；真正持续推进开发任务和高危审批，主要会回到客户端完成。
### 2. 登录账号
我输入账号和密码登录。
登录成功后，平台会识别我的用户身份，包括用户 ID、邮箱、角色和 `channelId`。这些信息用于后续模型额度、用量和审计归属。
用户不需要理解 `channelId` 的技术细节，只需要知道：我的模型余额、调用记录和任务消耗都能在 Heicode 里看到。
### 3. 进入首页
登录后，我首先进入首页。
首页会告诉我：
- 当前有没有正在运行的任务。
- 有没有失败任务。
- 有没有待我审批的高危操作。
- 我绑定了哪些资源。
- 模型余额和今日用量。
- 客户端是否已经下载。
如果我是第一次使用，首页会提示我下一步：输入产品想法、绑定资源或下载客户端。
### 4. 下载客户端
如果我还没有安装客户端，我会先进入“客户端下载”。
这里可以看到适合我系统的安装包，比如 macOS 或 Windows。下载安装后，我打开客户端。
客户端只需要登录：
```text
https://code.xinghanlab.com
```
客户端不会让我选择模型提供方，也不会出现 旧服务入口 或其他旧入口。客户端里能用什么模型，由 Heicode 提供。
### 5. 输入产品想法
回到 Heicode 或客户端，我输入我的产品想法。
比如我输入：
```text
我想做一个小团队任务管理 SaaS，
需要登录、项目、任务、评论、通知和后台管理，
希望部署到 Azure。
```
我不需要一开始就写完整 PRD。Heicode 会先理解我的目标，再帮我生成需求摘要、功能清单、原型描述和需要的资源。
### 6. 查看平台生成的任务草案
平台会根据我的输入生成一个任务草案。
我可以看到：
- 这个产品要解决什么问题。
- 第一版包含哪些功能。
- 推荐哪些页面和接口。
- 需要哪些代码仓库、文档、SK 和云资源。
- 建议使用哪些子 Agnet 角色。
- 哪些操作可能属于高危操作。
如果草案不准确，我可以直接修改。确认后，Heicode 会提示我补充这个任务需要的上下文。
### 7. 绑定代码仓库
在任务上下文卡片里，我先授权代码仓库。
如果我已有项目仓库，我可以授权 GitHub、GitLab、Gitea、Gitee 或自建 Git。平台会让我选择仓库、分支和允许访问的路径。
例如：
- 仓库：`repo-main`
- 分支：`main`
- 后端路径：`services/api/**`
- 前端路径：`web/**`
这里的重点不是把 Git token 贴在页面里，而是完成授权。真实凭证会进入密钥保管器，Heicode 只保存密钥引用。
### 8. 绑定项目文档和 SK
如果我有产品文档、原型描述或技能仓库，我继续绑定项目文档和 SK。
项目文档可以作为 Product Agnet 和 Architect Agnet 的上下文。SK 可以作为子 Agnet 可调用的技能来源。
绑定后，平台知道：
- 哪些文档可以读。
- 哪些技能可以使用。
- 哪些路径和版本有效。
### 9. 绑定云账号
接下来我绑定云资源，比如 Azure、AWS 或 GCP。
以 Azure 为例，我授权云账号后，平台会尽量自动发现我账号下的资源，比如：
- 虚拟机。
- 数据库。
- 存储。
- Kubernetes 或 AKS。
- 资源组。
我不应该手动填写一堆复杂资源 ID。正常体验应该是：平台发现资源，我选择哪些资源允许 Heicode 使用。
### 10. 选择允许使用的云资源
云账号授权后，我从自动发现列表里选择资源。
例如：
- 允许使用测试环境 AKS。
- 允许读取开发数据库。
- 不允许直接操作生产数据库。
- 生产部署必须审批。
保存后，这些云资源会变成 Resource Binding。
### 11. 确认密钥保管状态
资源绑定完成后，我能看到密钥保管状态。
我看到的是：
- 已托管。
- 无需密钥。
- 待补充。
- 已撤销。
- 异常。
我不会看到明文密钥。平台最多展示 `secret_ref` 这种引用，让我知道凭证由密钥保管器管理。
### 12. 生成子 Agnet 团队
资源准备好后，Heicode 会推荐一组子 Agnet 角色。
例如：
- Product Agnet：负责需求和验收标准。
- Architect Agnet：负责架构和技术方案。
- Frontend Agnet：负责页面和交互。
- Backend Agnet：负责 API、数据模型和服务逻辑。
- Reviewer Agnet：负责代码检查和安全审查。
- Ops Agnet：负责构建、部署和运行观察。
我可以使用推荐团队，也可以增减角色。
### 13. 分配资源权限
接下来我确认每个角色可以使用哪些资源。
例如：
Backend Agnet 可以：
- 读项目文档。
- 读写后端代码路径。
- 使用开发数据库。
Frontend Agnet 可以：
- 读项目文档。
- 读写前端代码路径。
Ops Agnet 可以：
- 部署测试环境。
- 请求生产部署审批。
这一步不要求我手写复杂策略。页面应该用角色卡片告诉我：这个角色能用什么、能做什么、是否需要审批。
### 14. 预览权限清单
如果我想看更详细的权限，我可以打开 manifest 预览。
这里会展示：
- 资源 ID。
- 资源类型。
- 允许动作。
- 限制条件。
- `secret_ref`。
manifest 不会显示 Git token、云 access key、SSH 私钥、数据库密码或 CodeGW key 原文。
### 15. 确认开始执行
在开始执行前，Heicode 会用一张确认卡展示本次任务摘要：
- 本次要做什么。
- 会启动哪些子 Agnet。
- 每个子 Agnet 使用哪些资源。
- 是否会访问密钥。
- 是否会部署云资源。
- 预计模型预算。
- 哪些动作需要审批。
确认无误后，我点击开始执行。真实部署动作仍由任务过程触发，并在高危场景下要求客户端审批。
### 16. 客户端审批高危操作
如果任务过程中出现高危操作，客户端会弹出审批。
例如：
```text
Ops Agnet 请求部署到生产环境。
目标资源：aks-prod
操作：cloud:deploy
风险等级：高
凭证：密钥保管器将派生 15 分钟短期凭证
```
这时我可以批准或拒绝。
如果我批准，平台会使用密钥保管器派生短期、最小权限凭证。子 Agnet 不会拿到长期密钥。
### 17. 在客户端持续推进开发
任务启动后，我不会停留在网页上编码，而是回到客户端继续推进。
这里的真实闭环是：
```text
我在客户端补充要求
-> Heicode 判断下一步要推进哪个子环节
-> Agnet 执行需求、开发、测试、修复或部署中的当前任务
-> Agnet 按权限调用已绑定的 SK 工具
-> 中间结果回到客户端
-> 我继续修正方向或批准高危动作
-> Agnet 继续推进直到交付和部署完成
```
### 18. 查看执行状态
任务启动后，我在 Heicode 里查看执行状态。
我能看到：
- Product Agnet 是否完成需求。
- Backend Agnet 是否正在写代码。
- Frontend Agnet 是否等待后端接口。
- Reviewer Agnet 是否发现问题。
- Ops Agnet 是否等待审批或部署中。
如果失败，页面应该显示失败原因，而不是只显示一个错误码。
### 19. 查看执行记录和模型用量
我可以在当前任务里打开执行记录。
这里能看到：
- 子 Agnet 运行日志。
- 模型调用日志。
- 消耗了多少额度。
- 哪个任务使用了哪个模型。
- 哪些资源被访问。
- 哪些高危操作被批准或拒绝。
模型和余额来自 CodeGW，但我不需要进入 CodeGW 后台。Heicode 会展示用户需要知道的信息。
### 19. 查看交付结果
当任务完成后，我查看交付结果。
结果可能包括：
- 产品文档。
- 原型描述。
- 代码变更。
- 测试结果。
- 部署结果。
- 访问地址。
- 审计记录。
如果部署到生产，我还可以看到部署时间、目标资源和审批记录。
### 20. 后续维护和升级
上线后，如果我想继续迭代，我可以直接输入新的需求。
例如：
```text
给任务管理 SaaS 增加企业微信通知，
并检查现有权限模型是否支持团队成员邀请。
```
Heicode 会复用之前的项目上下文、资源绑定和 Agnet 角色，生成新的开发任务。
## 简短演示口述版
> 我先登录 Heicode 的浏览器控制台。这里不是 CodeGW 后台，而是资源、部署、状态和审计的辅助入口。登录后，我会在客户端输入一个产品想法，比如做一个小团队任务管理 SaaS。平台会生成需求草案、推荐资源和子 Agnet 团队。接下来我绑定 Git 仓库、项目文档、SK 和云资源。真实密钥会进入密钥保管器，Heicode 只保存 secret_ref。然后我确认每个子 Agnet 的角色和权限，比如 Backend 能写后端路径，Ops 可以部署测试环境，但生产部署需要客户端审批。任务运行后，Agnet 会持续推进开发、测试和部署，并按权限调用需要的 SK 工具；我可以看到每个子 Agnet 的状态、日志、模型用量和审计记录。客户端只登录 code.xinghanlab.com，不选择模型提供方，模型由 Heicode 提供。整个流程的重点是：从一个想法开始，把产品、代码、云资源、模型、密钥和审计组织成一个完整的软件生命周期。
## 极简销售口述版
> Heicode 让用户从一个想法开始，接入自己的代码和云资源，由 Heicode 生成 AI 开发团队。平台负责资源授权、密钥保管、模型用量和审计；子 Agnet 负责开发、检查和部署。用户只在 Heicode 和客户端中操作，不需要进入 CodeGW 后台，也不会把长期密钥交给子 Agnet。
## 口述时必须强调
1. Heicode 是用户主入口。
2. 客户端只登录 Heicode。
3. CodeGW 是内部模型网关，不是普通用户后台。
4. 密钥进入密钥保管器，不进入 Git、Markdown 或日志。
5. 高危操作在客户端审批。
6. 子 Agnet 拿短期凭证，不拿长期密钥。
7. 资源绑定和权限分配要尽量自动化和角色化。
## 口述时不要说
1. 让用户去 CodeGW 后台配置模型。
2. 让用户去 OpenBao 控制台管理密钥。
3. 让客户端选择模型提供方。
4. 让用户手写复杂 manifest。
5. 把 tenant/project 当作当前产品主轴。
6. 把 Agnet 平台说成用户控制台。
docs/product-package/13-platform-description.md
+392
View File
@@ -0,0 +1,392 @@
# 13. 平台说明文档
## 文档目的
本文用于向用户、团队、客户和合作方说明 Heicode 平台是什么、由哪些部分组成、用户如何使用、各系统如何协作，以及平台如何处理模型、权限、密钥和审计。
产品说明文档重点回答“为什么需要 Heicode”；平台说明文档重点回答“Heicode 如何被使用、如何运转”。
## 一、平台概述
Heicode 是一款面向全流程智能开发的 SaaS 平台。用户注册登录后，可以从一个产品想法开始，接入自己的代码仓库、项目文档、SK 技能和云资源，由平台生成 AI 开发团队，完成需求、开发、检查、部署、观测和后续维护。
Heicode 平台由五个主要部分组成：
| 部分 | 用户理解 | 平台职责 |
|------|----------|----------|
| Heicode Manager | 浏览器辅助控制台 | 账号与安全、客户端下载、绑定资源、部署 Agnet、查看状态、余额和审计 |
| Heicode 客户端 | 本地主体验和审批入口 | 登录 Heicode、输入任务、继续开发、查看反馈、接收交付结果、审批高危操作 |
| Agnet 平台 | AI 开发团队执行层 | 在 AKS 上运行子 Agnet，回传状态、日志、事件和指标 |
| CodeGW | 模型与用量底座 | 提供模型调用、余额、额度、用量和调用日志 |
| 密钥保管器 | 凭证托管服务 | 保存长期密钥，按审批和权限生成短期访问能力 |
用户主要使用客户端和 Manager。CodeGW、密钥保管器和 Agnet 平台是底层能力，不作为普通用户日常操作后台。
## 二、平台适合谁
| 用户 | 使用场景 |
|------|----------|
| 独立开发者 | 从一个想法开始生成 MVP，并部署上线 |
| 创业团队 | 用较少人力完成产品迭代、测试和部署 |
| 企业创新团队 | 在已有代码仓库和云资源边界内使用 AI 开发 |
| 技术负责人 | 控制资源权限、模型消耗、安全审批和审计 |
| 运维负责人 | 管理部署、运行日志、资源访问和生产操作审批 |
## 三、平台核心能力
### 1. 想法输入
用户可以用自然语言描述产品想法或开发任务。平台会生成需求摘要、功能清单、原型描述、任务计划和需要的资源建议。
示例：
```text
我想做一个小团队任务管理 SaaS，
需要登录、项目、任务、评论、通知和后台管理，
希望部署到 Azure。
```
### 2. 资源绑定
用户可以把外部资源授权给 Heicode 使用。
资源类型包括：
- Git 仓库。
- SK 仓库或技能包。
- 项目文档。
- 云账号。
- 云资源，例如 VM、数据库、对象存储、Kubernetes。
资源绑定不是简单保存密钥，而是生成可分配、可撤销、可审计的资源授权基础。
### 3. AI 开发团队生成
平台根据任务目标推荐子 Agnet 角色。
常见角色：
- Product Agnet。
- Architect Agnet。
- Frontend Agnet。
- Backend Agnet。
- Reviewer Agnet。
- Ops Agnet。
每个子 Agnet 都有明确职责、可用资源、权限范围、模型配置和审计记录。
### 3.1 Agnet 持续执行闭环
Heicode 不是把任务分发给 Agnet 一次就结束，而是在继续开发中持续调用 Agnet 完成子环节。
完整闭环应表达为：
```text
客户端输入想法或追加需求
-> Manager 准备资源和部署条件
-> Heicode 调度 Agnet 执行当前子环节
-> Agnet 完成需求/开发/测试/修复/部署中的一步
-> Agnet 按权限调用 SK 工具
-> 中间结果和状态回传给客户端与 Manager
-> 用户继续补充、修正或审批
-> 最终由 Agnet 完成交付整理和部署
```
### 4. 权限分配
Heicode 使用 Resource Grant 描述“哪个角色能用哪个资源、能做什么、是否需要审批”。
示例：
```text
Backend Agnet
-> 可读项目文档
-> 可读写后端代码路径
-> 可访问开发数据库
-> 生产数据库访问需要审批
```
普通用户看到的是角色和权限摘要，高级用户可以预览 permission manifest。
### 5. 高危操作审批
高危操作必须在客户端审批。
高危操作包括：
- 生产部署。
- 云资源创建、删除、扩缩容。
- 数据库迁移或写入。
- 访问生产密钥。
- 大额模型预算消耗。
审批通过后，平台可以从密钥保管器派生短期、最小权限凭证给子 Agnet 使用。
### 6. 模型与余额
Heicode 展示用户可见的模型、余额、额度、用量和调用日志。这些能力来自 CodeGW，但普通用户不需要进入 CodeGW 后台。
用户能看到：
- 可用模型。
- 当前余额。
- 当前额度。
- 今日消耗。
- 调用日志。
- 失败日志。
用户看不到：
- 渠道管理。
- 模型供应商后台配置。
- 价格配置。
- CodeGW 管理员设置。
### 7. 日志与审计
Heicode 统一展示任务执行、模型调用、资源访问、高危审批和部署记录。
审计要能回答：
```text
谁
在什么时候
为了哪个任务
让哪个子 Agnet
使用了哪个资源
执行了什么操作
是否经过审批
消耗了多少模型额度
```
### 8. 部署和维护
Agnet 平台负责执行开发、检查、测试、修复和部署任务。Heicode 展示部署状态、失败原因、日志、指标和审计。
上线后，用户可以继续输入维护和升级需求，平台复用已有项目上下文、资源绑定和权限规则。
## 四、用户使用流程
完整流程：
```text
登录 Heicode
-> 下载并登录客户端
-> 客户端输入产品想法
-> 查看任务草案
-> 绑定 Git / 文档 / SK / 云资源
-> 生成子 Agnet 团队
-> 分配角色权限
-> 预览 permission manifest
-> 确认部署计划
-> Manager 部署 Agnet
-> 客户端持续推进任务
-> 客户端审批高危操作
-> Agnet 平台执行任务并调用 SK
-> Heicode 查看日志、用量、审计和交付结果
-> 后续维护和升级
```
## 五、平台组成说明
### 5.1 Heicode Manager
Heicode Manager 是浏览器辅助控制台。
用户在 Manager 中完成：
- 登录和查看首页。
- 绑定资源。
- 分配角色和权限。
- 创建或部署 Agnet 任务。
- 查看模型和余额。
- 查看日志与审计。
- 下载客户端。
Manager 不应该变成 CodeGW 后台，也不应该要求用户直接管理底层密钥系统，更不应该承担网页编码主体验。
### 5.2 Heicode 客户端
客户端是用户本地交互入口。
客户端负责：
- 登录 Heicode。
- 输入对话和任务。
- 持续追加需求和修正方向。
- 展示 Heicode 提供的模型。
- 审批高危操作。
- 查看执行反馈和交付结果。
客户端不负责：
- 选择模型提供方。
- 配置 CodeGW 渠道。
- 直接访问密钥保管器。
- 保存长期云密钥。
### 5.3 Agnet 平台
Agnet 平台是运行时执行层。
它负责：
- 在 AKS 上部署子 Agnet。
- 维护子 Agnet 状态。
- 执行开发、检查、测试、修复、部署和维护任务。
- 在执行过程中按权限调用 SK 工具。
- 回传日志、事件、指标和审计数据。
- 按 Resource Grant 和运行时身份访问资源。
普通用户不直接操作 Agnet 平台后台，而是在 Heicode 中查看 Agnet 状态和结果。
### 5.4 CodeGW
CodeGW 是内部模型网关和计费服务。
它负责：
- 模型调用。
- 用户或 Token 维度的额度。
- 余额。
- 调用日志。
- 模型可用性。
Heicode 通过服务端调用 CodeGW，并把普通用户需要的信息展示出来。CodeGW 后台不对普通用户开放。
### 5.5 密钥保管器
密钥保管器用于保存长期凭证。当前技术实现是 OpenBao。
它负责：
- 保存 Git token、SSH key、云 access key、数据库密码等长期凭证。
- 为高危操作派生短期凭证。
- 支持撤销、轮换、禁用和审计。
用户不会直接看到明文密钥。Heicode 服务端数据库只保存 `secret_ref`。
## 六、任务资源上下文说明
任务资源上下文的目标是让 Heicode 安全、可审计地使用用户授权的外部资源，同时不把用户拉进资源管理后台。
任务上下文准备流程：
```text
Heicode 判断当前任务需要哪些上下文
-> 用户完成授权或连接配置
-> Heicode 保存资源元数据
-> Secret Broker 把凭证写入密钥保管器
-> Heicode 保存 secret_ref
-> 用户确认本任务允许使用的资源范围
```
云资源授权后应尽量自动发现资源。用户绑定 Azure、AWS 或 GCP 后，平台应展示可选择的 VM、数据库、对象存储、Kubernetes 或资源组，减少手工填写。
## 七、权限和审批说明
权限确认围绕当前任务和角色进行。
用户不需要手写复杂策略，只需要确认：
- 这个角色能看什么。
- 这个角色能改什么。
- 这个角色能部署到哪里。
- 哪些操作需要审批。
- 授权什么时候过期。
高危操作审批只在客户端完成。审批结果会进入任务上下文和审计记录。
## 八、模型和余额说明
用户在 Heicode 中查看模型与余额。
展示内容：
- 可用模型。
- 余额。
- 额度。
- 调用量。
- 调用日志。
- 失败日志。
子 Agnet 的运行模型属于 Agnet 平台部署配置，不等同于 CodeGW 后台的模型供应商配置。
## 九、密钥保管说明
长期密钥不会进入：
- Git。
- Markdown。
- 前端响应。
- 普通日志。
- 子 Agnet 长期状态。
长期密钥进入密钥保管器。Heicode 保存 `secret_ref`。子 Agnet 使用资源时，只获取短期、最小权限、可审计凭证。
## 十、平台边界
用户需要使用：
- Heicode。
- Heicode 客户端。
用户不需要直接使用：
- CodeGW 后台。
- OpenBao 控制台。
- Agnet 平台后台。
用户不应该看到：
- 模型提供方选择。
- 旧服务入口。
- 明文密钥。
- OpenBao token。
- CodeGW 管理员配置。
## 十一、常见问题
### 1. 我需要会写代码吗？
不一定。Heicode 的目标是让用户从自然语言想法开始。但如果用户已有代码仓库，平台可以更好地基于现有项目继续开发。
### 2. 我必须绑定 Git 吗？
如果要让子 Agnet 修改代码，建议绑定 Git 仓库。只做产品文档或原型描述时，可以先不绑定代码仓库。
### 3. 我必须绑定云资源吗？
如果需要部署、测试环境或生产环境操作，就需要绑定云资源。只做需求、代码或本地检查时，可以先不绑定云资源。
### 4. 密钥安全吗？
平台设计上不把明文密钥保存到 Heicode 服务端数据库、Git、Markdown、日志或前端响应中。真实凭证进入密钥保管器，子 Agnet 只使用短期、最小权限凭证。
### 5. 客户端必须安装吗？
客户端用于本地对话和高危操作审批。普通浏览器流程可以完成很多管理操作，但高危操作审批建议通过客户端完成。
### 6. CodeGW 是什么？
CodeGW 是 Heicode 的模型网关和计费服务。普通用户不需要进入 CodeGW 后台，只在 Heicode 中查看模型、余额、额度和调用日志。
### 7. Agnet 是什么？
Agnet 是平台生成的 AI 开发角色。不同 Agnet 负责不同任务，例如产品、架构、前端、后端、审查和部署。
### 8. 生产部署怎么保证安全？
生产部署属于高危操作，需要客户端审批。审批通过后，平台按权限和 TTL 派生短期凭证，并记录完整审计。
### 9. 如果授权错了资源怎么办？
用户可以在任务资源上下文或权限确认卡中禁用、撤销或调整授权。撤销后，新的 permission manifest 不应再包含对应授权。
### 10. 平台会不会自动删除我的云资源？
不会默认执行高危操作。删除、生产部署、数据库写入等高危动作必须经过客户端审批。
## 十二、平台说明标准话术
> Heicode 是一个从想法到上线的软件生命周期平台。用户在 Heicode 中输入产品想法，绑定代码、文档、SK 和云资源。Heicode 生成子 Agnet 团队和权限清单，客户端负责高危审批，Agnet 平台负责执行开发和部署，CodeGW 提供模型和用量，密钥保管器保存长期凭证。用户只需要使用 Heicode 和客户端，不需要直接进入 CodeGW 后台或密钥保管器后台。
docs/product-package/README.md
+48
View File
@@ -0,0 +1,48 @@
# Heicode 产品资料包
版本：v0.1
日期：2026-05-07
用途：对外介绍、官网设计、销售沟通、内部产品对齐、演示和用户上手。
## 资料包目录
| 文档 | 用途 |
|------|------|
| [`01-product-overview.md`](./01-product-overview.md) | 产品说明文档，回答 Heicode 是什么、解决什么问题、系统边界是什么 |
| [`02-homepage-design-brief.md`](./02-homepage-design-brief.md) | 产品首页设计文档，指导官网首页结构、文案和视觉重点 |
| [`03-user-journey-and-core-flow.md`](./03-user-journey-and-core-flow.md) | 用户旅程与核心流程，描述从想法到上线的完整路径 |
| [`04-platform-usage-guide.md`](./04-platform-usage-guide.md) | 登录平台和使用平台指南，面向真实用户上手 |
| [`05-ppt-copy.md`](./05-ppt-copy.md) | 产品 PPT 文案，面向路演、客户介绍和团队同步 |
| [`06-security-and-credential-management.md`](./06-security-and-credential-management.md) | 安全与凭证管理说明，解释密钥保管器、`secret_ref`、高危审批 |
| [`07-integration-boundaries.md`](./07-integration-boundaries.md) | CodeGW、OpenBao、Agnet 平台边界说明 |
| [`08-client-guide.md`](./08-client-guide.md) | Heicode 客户端说明，强调只登录 Heicode、只使用 Heicode 模型 |
| [`09-demo-script.md`](./09-demo-script.md) | 5 分钟演示脚本，用于产品演示和录屏 |
| [`10-frontend-detail-spec.md`](./10-frontend-detail-spec.md) | 前端细节说明，覆盖 Heicode 和客户端页面、组件、状态、文案规则 |
| [`11-product-prototype-wireframes.md`](./11-product-prototype-wireframes.md) | 产品原型图，说明 Heicode 客户端主体验、Manager 辅助控制台与 Agnet 执行闭环的边界 |
| [`12-narrated-user-operation-flow.md`](./12-narrated-user-operation-flow.md) | 口述用户操作流程，用于演示、培训、录屏旁白和销售讲解 |
| [`13-platform-description.md`](./13-platform-description.md) | 平台说明文档，解释平台组成、使用方式、系统边界和常见问题 |
## 统一表述
Heicode 是一款面向全流程智能开发的 SaaS Code 工具。用户注册登录后，只需要输入想法，平台逐步完成需求澄清、产品文档、原型描述、代码开发、代码检查、生产部署、后续维护和升级。
对外一句话：
> Heicode 让用户从一个想法开始，组织 AI 开发团队，接入自己的代码和云资源，完成从产品设计到生产部署的软件生命周期。
## 命名规则
- 用户侧叫 `Heicode`，不要叫 CodeGW 后台。
- `Heicode 客户端` 是用户主体验，用于对话、输入想法、推进开发任务、查看执行反馈、高危审批和接收交付结果。
- `Heicode Manager` 是浏览器里的辅助控制台，负责账号与安全、客户端下载、Git/云资源绑定、Agnet 部署、任务状态、余额与审计。
- 继续开发时，Heicode 会持续调用 Agnet 推进需求、开发、测试、修复和部署等子环节。
- Agnet 在执行过程中可以调用已授权的 SK 工具，最终完成交付与部署并把结果回传给客户端和 Manager。
- 用户侧叫 `密钥保管器`，技术实现可以说明是 OpenBao。
- 用户侧叫 `资源绑定`，不要叫 Git 来源。
- 客户端不出现 `模型提供方`、`旧服务入口`、`第三方路由入口`。
- CodeGW 是内部模型网关和计费服务，不作为普通用户产品入口。
- Agnet 平台是执行层，不替代 Heicode 的用户控制台。
## 当前产品边界
当前资料包以 `docs/heicode.md`、`docs/plan.md`、`docs/product-requirements.md` 为依据。旧 Agnet 草案、旧 M1-M5 计划和旧 UI 命名不作为产品主线。