docs: consolidate current heicode plan

docs/README.md

@@ -1,37 +1,229 @@
-# Heicode 文档入口
+# Heicode 当前主线
 
-本目录是 Heicode 仓库的**文档主索引**。2026-05-02 之后，文档以 [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) 为主线；偏离该主线的旧 Agnet API 草案和 M1-M5 计划已清理。
+本文是 `docs/` 中唯一保留的新规划入口。旧 Agnet API 草案、旧里程碑、旧架构说明和旧上手材料已经删除，避免多套方向并行。已上线登录接口文档单独保留在 [`integration/Heicode-登录接口对接文档.md`](./integration/Heicode-登录接口对接文档.md)。
 
-## 共用骨架（建议都先读）
+## 一、产品定位
 
-| 文档 | 用途 |
+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. 高危生产权限优先走平台代理或审批，不直接把长期密钥注入子 Agnet。
+
+## 四、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 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。
+
+## 五、资源绑定与密钥托管
+
+绑定不是保存一串密钥，而是创建租户级 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`，不保存明文密钥。
+
+## 六、开源 Secret Store 方案
+
+SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。
+
+优先方案：
+
+| 方案 | 判断 |
 |------|------|
-| [`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md) | 产品愿景与协作范式（方向性，非排期） |
-| [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) | SaaS Manager / NewAPI / Agnet / Secret Store 的新边界与实施计划 |
-| [`glossary.md`](./glossary.md) | 术语表：Heicode / Manager / 客户端 / 子 agent / SK 等 |
-| [`architecture.md`](./architecture.md) | 架构图与关键数据流（mermaid） |
-| [`sk-lifecycle.md`](./sk-lifecycle.md) | SK（Skill 资产）单点真相：来源、快照、刷新、写权边界 |
+| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 |
+| Infisical | 可选方案。产品体验较好，但需要验证多租户策略和运行时授权能力 |
+| Azure Key Vault | 适合 Azure 优先部署，也可以作为 Secret Provider 的一种实现 |
 
-## 路径 A · 内部研发 / 新成员上手
+Secret Broker 负责：
 
-适合刚加入团队、负责 `cc-haha`（客户端）或 `heicode`（Manager）开发的同学。
+- 接收 OAuth、GitHub App、云授权回调后的凭证。
+- 生成租户隔离的 secret path。
+- 写入 Vault、Infisical 或 Azure Key Vault。
+- 创建或更新 policy。
+- 保存 `secret_ref` 到 Manager DB。
+- 轮换、撤销、禁用凭证。
+- 避免密钥进入日志、前端响应、Markdown 和 Git。
 
-1. [`onboarding/README.md`](./onboarding/README.md)：阅读顺序
-2. [`onboarding/local-dev.md`](./onboarding/local-dev.md)：本地联调步骤与排错
-3. [`onboarding/env-variables.md`](./onboarding/env-variables.md)：环境变量手册
-4. 回到共用骨架：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) → [`architecture.md`](./architecture.md) → [`glossary.md`](./glossary.md)
+## 七、AKS 上的 Agnet 凭证访问
 
-## 路径 B · Agnet / 平台集成方
+Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。
 
-适合实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师。
+推荐流程：
 
-1. [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) → [`glossary.md`](./glossary.md) → [`architecture.md`](./architecture.md)
-2. [`sk-lifecycle.md`](./sk-lifecycle.md)：SK 边界（Heicode 端写、Agnet 只读快照）
-3. [`integration/README.md`](./integration/README.md)：当前仍保留的集成契约入口
-4. [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：Heicode 客户端 ↔ Manager 浏览器登录流程
+```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，不拿长期密钥。
 
-- 本目录下的文档以 **设计意图与契约语义** 为准；实现细节以仓库代码为准。
-- 任一文档与今晚主线出现冲突时，优先更新或删除冲突文档，不再保留多套计划并行。
-- 受众边界：`docs/` 内不做产品营销文案，营销内容归 `website/`。
+运行时访问分两类：
+
+| 模式 | 适用 |
+|------|------|
+| 受控注入 | Git clone、开发/测试环境、低风险资源 |
+| 平台代理 | 生产部署、数据库写入、高危云操作、需要审批的动作 |
+
+普通开发资源可受控注入，生产云资源和高危操作走平台代理或审批。
+
+## 八、NewAPI 边界
+
+NewAPI 不作为普通用户后台开放。Manager 后端通过服务凭据调用 NewAPI，对用户展示必要信息。
+
+Manager 可展示：
+
+- 可用模型。
+- 当前租户或项目额度。
+- 余额。
+- 调用量。
+- 调用日志。
+- 失败日志。
+- 模型可用状态。
+
+Manager 不展示：
+
+- 渠道管理。
+- 模型供应商后台配置。
+- 价格配置。
+- 系统管理员用户管理。
+- NewAPI 原生管理后台入口。
+
+用户登录 Manager，不直接登录 NewAPI。Manager 需要维护用户、租户、项目到 NewAPI 用户、key 或 quota 的映射。
+
+## 九、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 面向系统强制执行。
+
+## 十、实施计划
+
+### P0：边界收敛
+
+- 以本文作为当前唯一主线。
+- 保留已上线登录接口文档。
+- 不再维护旧 Agnet API 草案和旧 M1-M5 计划。
+
+### P1：Manager 资源模型
+
+- 将当前 Git 来源抽象为资源绑定模型。
+- 增加资源类型：Git、SK、项目文档、云账号、单项云资源。
+- 增加 Resource Grant，用于把资源分配给项目、角色和子 Agnet。
+
+### P2：Secret Broker 与 Secret Store
+
+- 优先选型 Vault。
+- 在 Manager 后端实现 Secret Broker。
+- DB 只保存 `secret_ref`，不保存明文密钥。
+- 增加日志脱敏、前端响应过滤、Markdown 生成过滤。
+
+### P3：Agnet 平台 AKS 身份接入
+
+- Agnet 平台支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
+- 支持 Vault Kubernetes Auth 或等价 Workload Identity。
+- 支持按 tenant / project / role 生成 Vault policy。
+- 子 Agnet 运行时只能访问被授权的 secret。
+
+### P4：NewAPI 解耦
+
+- NewAPI 保持独立服务。
+- Manager 通过服务凭据调用 NewAPI。
+- Manager 展示普通用户需要的模型、余额、额度、调用日志。
+- 隐藏 NewAPI 管理员后台能力。
+
+### P5：部署和审计闭环
+
+- Manager 生成 AGENT.md、resource context 和 permission manifest。
+- Agnet 平台部署子 Agnet 后回传 deployment、agent instance、状态和事件。
+- Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
+- 对高危权限增加审批、撤销和运行中失效机制。

docs/architecture.md

@@ -1,167 +0,0 @@
-# Heicode 架构与关键数据流
-
-本文用 mermaid 图示统一表达 **Heicode 客户端 / Manager / Agnet / NewAPI / Secret Store** 之间的边界与数据流，作为愿景与 SaaS 架构计划的视觉补充。
-
-> 与文字版的对应关系：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md)、[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。旧 Agnet API 草案若与新架构计划冲突，以新架构计划为准。
-
----
-
-## 一、概念分层（鸟瞰）
-
-```mermaid
-flowchart TD
-  entry["人机入口<br/>官网 · 控制台 · CLI · Desktop"]
-  manager["Heicode Manager<br/>SaaS 控制台"]
-  client["Heicode 客户端<br/>(cc-haha)"]
-  agnet["Agnet 平台<br/>AKS 执行与状态"]
-  newapi["NewAPI<br/>模型网关 · 余额 · 日志"]
-  secret["Secret Store<br/>Vault / Infisical / Key Vault"]
-  assets["资产与环境<br/>仓库 · 流水线 · 运行时"]
-
-  entry --> manager
-  entry --> client
-  manager <--> client
-  manager --> agnet
-  manager --> newapi
-  manager --> secret
-  agnet --> secret
-  client -. "会话子 agent 输出" .- agnet
-  agnet --> assets
-  manager --> assets
-```
-
-要点：
-- **Manager 是 SaaS 用户、租户、资源、权限与部署控制台**
-- **NewAPI 是独立模型服务**，普通用户不进入 NewAPI 后台
-- **Secret Store 保存真实密钥**，Manager DB 只保存 `secret_ref`
-- **Agnet 在 AKS 上执行**，按 Manager 下发的 Resource Grant 和运行身份使用资源
-
----
-
-## 二、HeiCode 客户端 ↔ Manager ↔ Agnet 主链路
-
-```mermaid
-flowchart LR
-  user["开发者"]
-  desktop["Heicode 客户端<br/>(Desktop / CLI + 本地服务)"]
-  manager["Heicode Manager"]
-  agnet["Agnet 平台"]
-
-  user --> desktop
-  desktop -->|"OAuth: /heicode/oauth/*"| manager
-  desktop -->|"Anthropic Messages /<br/>OpenAI Chat 调用"| manager
-  newapi["NewAPI<br/>模型网关 / 额度 / 调用日志"]
-  secret["Secret Store<br/>Vault / Infisical / Key Vault"]
-
-  manager -->|"模型、余额、调用日志"| newapi
-  manager -->|"资源绑定 / secret_ref"| secret
-  manager -->|"M2M JWT · 部署/查询编队"| agnet
-  agnet -->|"运行时受控读取密钥"| secret
-  agnet -->|"webhook / events"| manager
-  agnet -.->|"sub_agent.output (SSE/WS)"| desktop
-```
-
-关键边界：
-- 客户端 **不直连** 模型供应商，模型能力经 Manager / NewAPI 提供
-- Manager 用 **服务账号 / 用户委派令牌** 调 Agnet
-- 密钥不进入 Git、Markdown、前端或日志；子 Agnet 只通过受控身份使用被授权资源
-
----
-
-## 三、资源绑定与凭证托管
-
-```mermaid
-flowchart LR
-  user["用户"]
-  manager["Heicode Manager"]
-  registry["Resource Registry<br/>资源元数据与授权"]
-  broker["Secret Broker"]
-  store["Secret Store<br/>Vault / Infisical / Key Vault"]
-  agnet["Agnet 平台"]
-  pod["子 Agnet Pod<br/>AKS ServiceAccount"]
-
-  user -->|"OAuth / GitHub App / 云授权"| manager
-  manager --> registry
-  manager --> broker
-  broker -->|"写入真实凭证"| store
-  manager -->|"Resource Grant / permission manifest"| agnet
-  agnet -->|"创建运行身份 / policy"| pod
-  pod -->|"按最小权限读取短期凭证"| store
-```
-
-要点：
-- 用户完成授权，平台负责托管、轮换、撤销和审计
-- Manager DB 保存资源元数据、授权关系和 `secret_ref`
-- Secret Broker 是唯一写入真实凭证的后端边界
-- 子 Agnet 不保存长期密钥
-
----
-
-## 四、SK 数据流（Git / Upload → 快照 → 子 agent 注入）
-
-```mermaid
-flowchart TB
-  authoring["SK 编辑入口<br/>仅 Heicode 客户端"]
-  git["Git 仓库<br/>(SK 事实源)"]
-  upload["上传制品<br/>(对象存储 / artifact_id)"]
-  manager["Heicode Manager<br/>展开 sk_sources 与刷新策略"]
-  agnet["Agnet 平台"]
-  snapshot["不可变快照<br/>commit_sha · artifact 版本"]
-  subAgent["Agnet 子 agent<br/>(运行时只读)"]
-
-  authoring -->|"git push"| git
-  authoring -->|"上传 / 替换"| upload
-  manager -->|"声明 sk_sources"| agnet
-  git -->|"fetch + checkout ref"| agnet
-  upload -->|"只读获取"| agnet
-  agnet --> snapshot
-  snapshot -->|"注入"| subAgent
-```
-
-要点：
-- SK **写入路径单一**：经 Heicode 客户端到 Git，或经 Heicode 上传入口
-- Agnet 与 Manager **不得提供 SK 正文写 API**
-- 运行注入仅使用解析出的 **不可变快照**，避免「执行中偷偷换版本」
-
-详见 [`sk-lifecycle.md`](./sk-lifecycle.md)。
-
----
-
-## 五、事件流双轨（平台运行态 vs 会话子代理输出）
-
-```mermaid
-flowchart LR
-  agnet["Agnet 平台"]
-  manager["Heicode Manager<br/>控制台与 Dashboard"]
-  client["Heicode 客户端<br/>编码会话面板"]
-
-  agnet -->|"phase / health / metrics<br/>(SSE · WS · webhook)"| manager
-  agnet -->|"sub_agent.output<br/>(SSE · WS)"| client
-```
-
-两类事件 **同源端点可复用**，但 `event` / `type` 必须可区分：
-- 面向 Manager 的：`deployment.*`、`instance.*`、`phase_changed`、`health_changed`
-- 面向客户端的：`sub_agent.output`、`sub_agent.tool_result`、`output_delta`
-
----
-
-## 六、模块关注点对照
-
-| 关注点 | Heicode 客户端 (`cc-haha/`) | Heicode Manager (`heicode/`) | NewAPI | Agnet 平台 | Secret Store |
-|--------|------------------------------|-------------------------------|--------|------------|--------------|
-| 用户身份 | 浏览器登录 / API Key 兼容 | SaaS 登录、租户、项目、角色 | 后台服务身份 | 接收 M2M JWT 与委托令牌 | 接收服务身份 / K8s 身份 |
-| 模型调用 | 不直连模型，请求经 Manager | 展示模型、余额、日志 | 模型网关、额度、调用日志 | 不参与基础模型调用 | 不参与 |
-| 资源绑定 | 发起本地工作流 | Git / 云 / 文档 / SK 资源绑定与 Resource Grant | 不参与 | 接收授权后的运行引用 | 保存真实凭证 |
-| 编排 | 触发部署、订阅子 agent 输出 | 一键部署入口、permission manifest、审计 | 不参与 | 实际执行编队、维护实例生命周期 | 按策略提供密钥 |
-| SK | 主要编辑入口（写 Git / 上传） | 展开 `sk_sources`、刷新策略 | 不参与 | 拉取快照、运行时只读注入 | 可保存访问凭证 |
-| 观测 | 会话内子 agent 输出 | 平台运行态聚合、NewAPI 调用日志 | 调用日志、余额 | 提供事件流、指标导出 | 提供密钥访问审计 |
-
----
-
-## 六、相关代码索引
-
-- 客户端登录：`cc-haha/src/server/api/heicode-auth.ts`
-- 客户端 Provider 预设：`cc-haha/src/server/config/providerPresets.ts`
-- Manager OAuth：`heicode/controller/heicode_oauth.go`、`heicode/router/heicode-router.go`
-
-> 代码会演进，本文以 **架构关系** 为准；具体路径请以仓库当前实现为最终事实。

docs/glossary.md

@@ -1,118 +0,0 @@
-# 术语表
-
-本术语表是 Heicode 仓库内 **跨文档共享的命名标准**。任意文档涉及以下名称时，请相对链接回本文件锚点，避免规则漂移。
-
-> 与代号相关的方向性来源：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md)。
-> 与 SaaS 架构相关的来源：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。
-
-## 产品级代号
-
-### Heicode
-仓库与产品族的总称。在区分产品形态时，亦称 **Heicode 客户端**。
-
-### Heicode Manager
-SaaS 用户控制台与编排中枢，源码目录 `heicode/`。负责用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计，以及面向普通用户展示模型、余额和调用日志。
-
-### Heicode 客户端
-面向开发者的 CLI（Ink）+ 桌面应用（Tauri + React）+ 本地 HTTP/WS 服务，源码目录 `cc-haha/`。
-
-### Orchard
-**子智能体编排与团队模板** 所在平台的概念名。它是一个抽象代号，用以保持愿景叙事不绑死在某个厂商。落地形态可对应 Agnet。
-
-### Agnet
-当前实际接入的编排平台名称。Agnet 底层运行在 AKS，负责部署子 Agnet、维护执行状态、事件和日志，并按 Manager 下发的 Resource Grant 使用受控资源。
-
-### NewAPI
-独立的模型网关和计费服务。它提供模型渠道、模型调用、额度、余额和调用日志；普通 SaaS 用户不进入 NewAPI 后台，Manager 后端通过服务凭据调用 NewAPI。
-
-### Secret Store
-真实凭证的保管库，例如 HashiCorp Vault、Infisical 或 Azure Key Vault。Manager 数据库只保存 `secret_ref`，不保存 Git token、云密钥、SSH 私钥和数据库密码。
-
-### Secret Broker
-Manager 后端中负责凭证写入、轮换、撤销、路径生成、策略创建和审计的边界模块。业务代码不应绕过 Secret Broker 直接操作 Secret Store。
-
-## 编排相关
-
-### 执行单元 (`agent_instance`)
-按角色模板在编排侧实例化的智能体实例。生命周期字段详见 API 设计 §6.1。
-
-### 子 agent
-本仓库语境下，特指 **Agnet 平台内部** 的子智能体 / 子执行单元，由 Agnet 编排实例化，**不是** Heicode 自研运行时。
-
-### 部署 (`deployment`)
-一次「按团队模板把多个执行单元拉起」的整体行为，由 `deployment_id` 唯一标识。
-
-### 团队 / 编队
-一组在同一 `deployment` 中协同工作的执行单元。瀑布与敏捷下的最小/最大编队详见愿景附录 A。
-
-## 资产与边界
-
-### SK（Skill 资产）
-为子 agent 提供运行时只读上下文的说明类正文，多为 Markdown。详见 [`sk-lifecycle.md`](./sk-lifecycle.md)。
-
-### 资源绑定 (`resource binding`)
-用户授权 Heicode 使用某个外部资源的动作与结果。资源可以是 Git 仓库、SK 仓库、项目文档、Azure/AWS/GCP 账号、VM、数据库、对象存储或 AKS 集群。绑定产生资源元数据和 `secret_ref`，不产生可暴露的明文密钥。
-
-### Resource Grant
-Manager 中把某个资源授权给特定租户、项目、子 Agnet 角色和权限范围的记录。部署时，Manager 将 Resource Grant 转换为 permission manifest 发送给 Agnet 平台。
-
-### permission manifest
-面向系统强制执行的结构化权限清单，描述每个子 Agnet 可用的资源、动作、路径、环境和限制。它和 AGENT.md / resource context 配套使用。
-
-### resource context
-面向模型理解的启动上下文，通常可以生成为 Markdown。它描述角色、目标、可用资源和禁止事项，但不得包含任何真实密钥。
-
-### `sk_sources`
-SK 的来源数组。每个元素声明其来源类型：
-- `git`：以 commit SHA 为快照锚点
-- `upload`：以 `artifact_id` + 版本为快照锚点
-
-### `sk_file_refs`
-简化字段（路径数组），可视为 `sk_sources` 的简写；展开规则需在联合 RFC 中声明。
-
-### Provider Preset
-Heicode 客户端预先配置的供应商描述（baseUrl、默认模型、API 格式等），目前仅保留 `taijiaicloud` 与 `clawdrouter`，定义于 `cc-haha/src/server/config/providerPresets.json`。
-
-## 标识符
-
-| 名称 | 含义 | 出处 |
-|------|------|------|
-| `tenant_id` | 顶层租户隔离边界，所有持久化资源必带 | API 设计 §4.1 |
-| `org_id` | 租户内组织划分（可选） | API 设计 §4.1 |
-| `project_id` | 编排资源挂载点 | API 设计 §4.1 |
-| `deployment_id` | 一次部署的全局标识 | API 设计 §5.1 |
-| `instance_id` / `agent_instance_id` | 执行单元实例 | API 设计 §5.1 / §6.1 |
-| `sub_agent_id` | Agnet 内子 agent 实例 | API 设计 §5.0 / §6.4 |
-| `correlation_id` / `X-Heicode-Correlation-Id` | Heicode → Agnet 全链路关联键 | API 设计 §2.3 |
-| `request_id` / `X-Request-Id` | 单次请求追踪 | API 设计 §2.3 |
-| `state` | OAuth 流程会话标识 | [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md) |
-
-## 状态字段
-
-### `phase`
-执行单元的生命周期阶段：`pending` / `running` / `succeeded` / `failed` / `stopped` 等。
-
-### `health`
-执行单元健康度：`ok` / `degraded` / `unknown`。
-
-### `schema_version`
-事件载荷与某些资源体的版本号。客户端遇到未知字段必须忽略，破坏性变更须升级版本号。
-
-## 认证相关
-
-### M2M JWT
-`Authorization: Bearer <m2m_jwt>` 形式的服务间令牌，由 Manager 或 Agnet 签发；至少包含 `sub` / `tenant_id` / `scope` / `exp`。
-
-### 用户委派令牌
-终端用户经 Heicode OAuth 后，由 Manager 代发用于访问 Agnet 受限接口的令牌；Claims 含 `user_id` / `org_id` / `roles`。
-
-### loopback redirect_uri
-Heicode 客户端浏览器登录时使用的回跳地址，必须使用 `127.0.0.1` / `localhost` / `::1`。详见 [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)。
-
-## 范式与角色（参考）
-
-### 瀑布隐喻 / 敏捷隐喻
-两种协作叙事，分别强调「阶段闸门可审计」与「短迭代闭环」。详见愿景正文第六节。
-
-### 编队角色代号
-`WF-*` 表示瀑布编队角色（如 `WF-DEV`、`WF-QA`、`WF-REL`），`AG-*` 表示敏捷编队角色（如 `AG-PO`、`AG-DEV`、`AG-QA`）。完整对照见愿景附录 A。

docs/integration/README.md

@@ -1,14 +0,0 @@
-# 集成契约入口
-
-本目录只保留当前仍贴近实现的登录与客户端认证契约。Agnet / NewAPI / Secret Store 的新边界和实施计划统一放在 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md)。
-
-## 保留文档
-
-| 文档 | 用途 |
-|------|------|
-| [`Heicode-登录接口对接文档.md`](./Heicode-登录接口对接文档.md) | 已上线账号密码登录接口契约 |
-| [`heicode-oauth-flow.md`](./heicode-oauth-flow.md) | Heicode 客户端通过浏览器登录 Manager 的流程 |
-
-## 已清理内容
-
-旧的 Agnet API 草案、编排提案、验收矩阵和 M1-M5 计划已经删除。后续需要按新主线重新生成正式契约，而不是沿用旧文档。

docs/integration/heicode-oauth-flow.md

@@ -1,149 +0,0 @@
-# HeiCode 浏览器登录流程（客户端 ↔ Manager）
-
-本文给出 Heicode 客户端通过浏览器完成 Manager 登录的端到端流程，并说明字段、错误模型与扩展点。当前实现以 **loopback 直接回 token** 为主，OAuth2 + PKCE 已在客户端预留。
-
-> 代码位置：
->
-> - 客户端：`cc-haha/src/server/api/heicode-auth.ts`
-> - 服务端：`heicode/controller/heicode_oauth.go`、`heicode/router/heicode-router.go`
-
-## 一、设计目标
-
-- 用户启动 Heicode 客户端 → 看到登录卡片 → 点击「浏览器登录」
-- 浏览器跳到 Manager 控制台，完成账号登录
-- Manager 颁发 / 复用一条专用 Token，回跳客户端 loopback 地址
-- 客户端落地 Token，激活 Provider，自动拉模型列表
-
-整体不要求平台事先支持完整 OAuth2，loopback + token 即可工作；后续可平滑切换到 Authorization Code + PKCE。
-
-## 二、参与方与端点
-
-
-| 端点                                     | 谁实现              | 用途                                 |
-| -------------------------------------- | ---------------- | ---------------------------------- |
-| `POST /api/heicode-auth/oauth/start`   | 客户端本地服务          | 生成 `state` / PKCE，返回 authorize URL |
-| `GET /heicode/oauth/authorize`         | Manager（heicode） | 校验 loopback、引导登录、回跳 token          |
-| `GET /heicode/oauth/session`           | Manager（heicode） | 给「请先登录」过渡页轮询登录态                    |
-| `GET /api/heicode-auth/oauth/callback` | 客户端本地服务          | 接收 token / code，落地并激活              |
-
-
-## 三、当前实现（loopback + token 直回）
-
-```mermaid
-sequenceDiagram
-  autonumber
-  participant U as 用户
-  participant C as Heicode 客户端<br/>(本地 HTTP 服务)
-  participant B as 浏览器
-  participant M as Heicode Manager<br/>(heicode)
-
-  U->>C: 点击「浏览器登录」
-  C->>C: 生成 state / PKCE 并写入会话
-  C-->>B: 返回 authorize URL
-  B->>M: GET /heicode/oauth/authorize?state=...&redirect_uri=...&provider_id=...
-  alt 用户未登录
-    M-->>B: 渲染过渡页（链接到 /login）
-    loop 每 1.5s
-      B->>M: GET /heicode/oauth/session
-      M-->>B: { logged_in }
-    end
-    B->>M: 重新请求 authorize
-  end
-  M->>M: 校验 loopback redirect_uri
-  M->>M: 取或新建名为 "HeiCode" 的 Token
-  M-->>B: 302 redirect_uri?state=...&token=sk-XXXX
-  B->>C: GET /api/heicode-auth/oauth/callback?token=...&state=...
-  C->>C: 校验 state、激活 Provider、拉模型
-  C-->>B: 返回成功页（用户可关闭浏览器）
-```
-
-
-
-### 关键校验
-
-- `state` 与 `redirect_uri` 必填，`redirect_uri` 必须是 loopback 主机：`127.0.0.1` / `localhost` / `::1`
-- 客户端会话过期（默认 5 分钟）后回调直接判失败
-- 客户端默认从 `?token=` / `?access_token=` / `?apiKey=` / `?apikey=` 任一字段读取 Token
-
-### 字段表
-
-
-| 名称                                         | 在         | 说明                                                  |
-| ------------------------------------------ | --------- | --------------------------------------------------- |
-| `state`                                    | URL query | 客户端生成的不可猜测随机串，回跳时校验                                 |
-| `redirect_uri`                             | URL query | 必须是 loopback；Manager 会拒绝其它主机                        |
-| `provider_id`                              | URL query | `taijiaicloud` / `clawdrouter`；用于客户端识别落到哪个 provider |
-| `token`                                    | 回跳 query  | Manager 颁发的 HeiCode 专用 Token，前缀 `sk-`               |
-| `code` / `code_verifier`                   | 标准 OAuth  | 当前 loopback 模式不使用；启用 PKCE 时必需                       |
-| `code_challenge` / `code_challenge_method` | URL query | 启用 PKCE 时由客户端附带，方法固定 `S256`                         |
-| `client_id` / `scope`                      | URL query | 启用 PKCE 时附带，分别来自客户端环境变量                             |
-
-
-## 四、扩展形态：标准 OAuth2 + PKCE
-
-当平台具备 token 端点后，仅需在客户端配置环境变量即可启用：
-
-
-| 变量                                       | 用途                                        |
-| ---------------------------------------- | ----------------------------------------- |
-| `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL` | 自定义 authorize 端点                          |
-| `HEICODE_<PROVIDER>_OAUTH_TOKEN_URL`     | code → access_token 交换端点                  |
-| `HEICODE_<PROVIDER>_OAUTH_CLIENT_ID`     | OAuth Client ID（启用 PKCE 时必需）              |
-| `HEICODE_<PROVIDER>_OAUTH_SCOPE`         | 申请的 scope，例如 `models:read,messages:write` |
-
-
-详见 `[../onboarding/env-variables.md](../onboarding/env-variables.md)`。
-
-```mermaid
-sequenceDiagram
-  participant C as 客户端
-  participant B as 浏览器
-  participant P as 平台 Authorize
-  participant T as 平台 Token
-
-  C->>B: authorize URL?response_type=code&client_id&...&code_challenge
-  B->>P: 用户登录授权
-  P-->>B: 302 redirect_uri?code=&state=
-  B->>C: callback?code=&state=
-  C->>T: POST /token { grant_type=authorization_code, code, code_verifier, ... }
-  T-->>C: { access_token }
-  C->>C: 激活 Provider 并拉模型
-```
-
-
-
-## 五、错误模型
-
-
-| 触发                          | HTTP / 行为                                             | 客户端展示                      |
-| --------------------------- | ----------------------------------------------------- | -------------------------- |
-| `state` / `redirect_uri` 缺失 | Manager 400                                           | 浏览器停留报错                    |
-| `redirect_uri` 非 loopback   | Manager 400 `redirect_uri must be a loopback address` | 检查客户端配置                    |
-| 用户未登录                       | Manager 渲染过渡页并轮询 session                              | 浏览器停留并自动跳转                 |
-| 客户端会话过期                     | 客户端 callback 返回错误页                                    | 提示「登录会话已过期，请回到 HeiCode 重试」 |
-| 平台未配置 token 端点但只回了 code     | 客户端 callback 错误页                                      | 提示「平台未配置 token 交换端点」       |
-| Provider 模型校验失败             | 客户端 400                                               | 拉模型异常或返回空集                 |
-
-
-## 六、与 Agnet API 设计的衔接
-
-- 这里的 Token 用于 Heicode 客户端调 Manager；Manager 调 Agnet 时应使用服务间令牌或受控委托令牌，具体以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准
-- 跨链路追踪建议在 Manager 调 Agnet 时附带 `X-Heicode-Correlation-Id` 与本登录会话关联
-
-## 七、安全注意事项
-
-- 客户端必须在每次启动时 **新生成** `state` / `code_verifier`，禁止复用
-- Manager 必须 **拒绝** 非 loopback 的 `redirect_uri`（已实现）
-- Token 长生命周期使用前提：Manager 端可吊销且具备审计；不要在跨设备粘贴中传播
-- 出现安全事件时，Manager 应能批量吊销名为 `HeiCode` 的 Token
-
-## 八、界面截图（docs/images）
-
-> 下列截图来自 `docs/images/`，用于辅助理解登录链路与界面落位。
-
-![Heicode login flow screenshot 01](../images/wecom-screenshot-01.jpg)
-![Heicode login flow screenshot 02](../images/wecom-screenshot-02.jpg)
-![Heicode login flow screenshot 03](../images/wecom-screenshot-03.jpg)
-![Heicode login flow screenshot 04](../images/wecom-screenshot-04.jpg)
-![Heicode login flow screenshot 05](../images/wecom-screenshot-05.jpg)
-![Heicode login flow screenshot 06](../images/wecom-screenshot-06.jpg)

docs/onboarding/README.md

@@ -1,42 +0,0 @@
-# 新成员上手指引
-
-适合刚加入 Heicode 项目的研发同学：把环境跑起来 → 认识仓库结构 → 知道改哪、看哪。
-
-## 推荐阅读顺序
-
-1. [`local-dev.md`](./local-dev.md)：把 `cc-haha`（客户端）、`heicode`（Manager）、`website`（站点）跑起来；含常见错误与排查
-2. [`env-variables.md`](./env-variables.md)：客户端识别的环境变量（base URL、OAuth 配置）
-3. 共用骨架：[`../architecture.md`](../architecture.md)、[`../glossary.md`](../glossary.md)、[`../sk-lifecycle.md`](../sk-lifecycle.md)
-4. 主计划对齐：[`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md)
-5. 子项目细则：
-   - 客户端约定：[`../../cc-haha/AGENTS.md`](../../cc-haha/AGENTS.md)
-   - 网关约定：[`../../heicode/CLAUDE.md`](../../heicode/CLAUDE.md)
-
-## 改代码前的最小心智模型
-
-| 你要改什么 | 入口文件 | 备注 |
-|------------|----------|------|
-| 客户端登录 / Provider | `cc-haha/src/server/api/heicode-auth.ts` | 路由前缀 `/api/heicode-auth/*` |
-| 客户端模型发现 | `cc-haha/src/server/services/providerService.ts`、`cc-haha/src/server/api/providers.ts` | `/v1/models` 探活 |
-| Provider 预设 | `cc-haha/src/server/config/providerPresets.json` + `providerPresets.ts` | 仅保留 `taijiaicloud` / `clawdrouter` |
-| Manager OAuth | `heicode/controller/heicode_oauth.go` | 路由 `heicode/router/heicode-router.go` |
-| 桌面端 UI | `cc-haha/desktop/src/` | Tauri + React |
-
-## 你不需要做的事
-
-- **不要** 在 Heicode 客户端里实现计费 / 订阅；这部分由 Manager 展示，底层能力来自 NewAPI
-- **不要** 给 Agnet 平台或 Manager 增加可写 SK 正文的 API（违反 SK 边界，详见 [`../sk-lifecycle.md`](../sk-lifecycle.md)）
-- **不要** 引入「客户端 → 模型供应商直连」的捷径；所有模型调用应经 Manager 路由
-
-## 提交与协作
-
-- 提交风格沿用 Conventional Commits：`feat:` / `fix:` / `docs:` / `chore:` 等
-- 分支前缀：`feat/*`、`fix/*`、`docs/*`（不要新建 `codex/*`）
-- PR 描述列出影响面、验证步骤；UI 改动附截图
-- 文档与代码同 PR 提交：避免事后再补 docs
-
-## 提问与求助
-
-- 客户端 TS/React 行为问题：先看 [`../../cc-haha/AGENTS.md`](../../cc-haha/AGENTS.md)
-- 网关 Go 行为问题：先看 [`../../heicode/CLAUDE.md`](../../heicode/CLAUDE.md)
-- 集成 / Agnet 契约问题：先看 [`../integration/README.md`](../integration/README.md)

docs/onboarding/env-variables.md

@@ -1,76 +0,0 @@
-# 环境变量手册（Heicode 客户端）
-
-仅列出 Heicode 客户端（`cc-haha/`）当前 **代码中已支持** 的环境变量。Manager（`heicode/`）的环境变量请以 `heicode/CLAUDE.md` 与 `heicode/.env.example` 为准。
-
-> 来源代码：
-> - `cc-haha/src/server/config/providerPresets.ts`
-> - `cc-haha/src/server/api/heicode-auth.ts`
-> 改动这些变量后 **需要重启** 本地服务才能生效。
-
-## 一、Provider Base URL 覆盖
-
-让客户端把某个 provider 的 `baseUrl` 指向本地或自部署网关，常用于联调本机 Manager。
-
-| 变量 | 作用对象 | 示例 |
-|------|----------|------|
-| `HEICODE_TAIJIAICLOUD_BASE_URL` | `taijiaicloud` provider | `http://localhost:3000` |
-| `HEICODE_CLAWDROUTER_BASE_URL` | `clawdrouter` provider | `http://localhost:4000` |
-
-行为：
-- 模块加载时读取，未设置则用 preset 中的默认 baseUrl
-- 末尾斜杠会被自动去除
-
-## 二、OAuth 配置
-
-客户端浏览器登录会按如下顺序解析授权地址：
-
-1. 若设置了 `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL`，用其值
-2. 否则使用 `<baseUrl>/heicode/oauth/authorize`
-
-`<PROVIDER>` 取值范围与 base URL 相同（`TAIJIAICLOUD` / `CLAWDROUTER`）。
-
-| 变量 | 用途 | 默认 |
-|------|------|------|
-| `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL` | OAuth 授权入口 | `<baseUrl>/heicode/oauth/authorize` |
-| `HEICODE_<PROVIDER>_OAUTH_TOKEN_URL` | OAuth `code → token` 交换端点 | `<baseUrl>/heicode/oauth/token` |
-| `HEICODE_<PROVIDER>_OAUTH_CLIENT_ID` | OAuth Client ID（启用 PKCE 时必需） | 未设置 |
-| `HEICODE_<PROVIDER>_OAUTH_SCOPE` | OAuth Scope（可选，与 `client_id` 一并使用） | 未设置 |
-
-设置规则：
-- **仅设置 AUTHORIZE_URL**：客户端跳转浏览器后，平台必须直接以 `?token=...` 形式回调（适合 Manager 当前的 loopback 实现）
-- **同时设置 AUTHORIZE_URL + TOKEN_URL + CLIENT_ID**：启用标准 OAuth2 Authorization Code + PKCE
-- **未设置 AUTHORIZE_URL** 时，客户端默认用 `<baseUrl>/heicode/oauth/authorize`，与 Manager 默认路由对齐
-
-详见 [`../integration/heicode-oauth-flow.md`](../integration/heicode-oauth-flow.md)。
-
-## 三、本地服务
-
-| 变量 | 用途 | 默认 |
-|------|------|------|
-| `SERVER_PORT` | 客户端本地 HTTP/WS 服务端口 | `3456` |
-
-## 四、配置示例
-
-### 仅切 baseUrl 到本地 Manager
-
-```bash
-HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 \
-  bun run src/server/index.ts
-```
-
-### 启用浏览器登录 + 标准 OAuth
-
-```bash
-export HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000
-export HEICODE_TAIJIAICLOUD_OAUTH_AUTHORIZE_URL=http://localhost:3000/heicode/oauth/authorize
-export HEICODE_TAIJIAICLOUD_OAUTH_TOKEN_URL=http://localhost:3000/heicode/oauth/token
-export HEICODE_TAIJIAICLOUD_OAUTH_CLIENT_ID=heicode-desktop
-export HEICODE_TAIJIAICLOUD_OAUTH_SCOPE=models:read,messages:write
-bun run src/server/index.ts
-```
-
-> 注：当前 Manager 的实现仅以 loopback 直接回 `?token=...`，标准 OAuth 等待平台侧补全后再启用。
-
-## 五、变更约束
-
-新增环境变量时请同步更新本文与代码注释，避免漂移。本文不是 `.env.example` 的替代，仅作为 docs 索引。

docs/onboarding/local-dev.md

@@ -1,107 +0,0 @@
-# 本地联调指引
-
-把仓库内三块跑起来：`cc-haha`（客户端）、`heicode`（Manager）、`website`（站点）。下面命令以 macOS / Linux 为主，Windows 仅在差异点提示。
-
-> 命令以仓库当前 README 与 package.json 为准；如出现冲突，以代码为最终事实。
-> 客户端工程级别的更细约定在 [`../../cc-haha/AGENTS.md`](../../cc-haha/AGENTS.md)。
-
-## 一、前置依赖
-
-| 依赖 | 用途 | 检查命令 |
-|------|------|----------|
-| Bun ≥ 1.x | 客户端 / 站点 / Tauri 前端构建 | `bun --version` |
-| Node 22 | 仅 docs 工作流（CI 用 npm） | `node --version` |
-| Rust toolchain | Tauri 桌面端 | `cargo --version` |
-| Docker / Docker Compose | 起 Manager 与站点容器 | `docker compose version` |
-| Go 1.22+ | 直接跑 Manager 源码（可选） | `go version` |
-
-> Bun 安装：`curl -fsSL https://bun.sh/install | bash`（Windows 用 PowerShell `irm bun.sh/install.ps1 | iex`）。
-> Rust 安装：`curl --proto '=https' https://sh.rustup.rs | sh`（如遇 HTTP/2 报错，去掉 `--http2` 重试）。
-
-## 二、最小开发闭环
-
-```bash
-# 1. 安装客户端依赖
-cd cc-haha && bun install
-
-# 2. 终端 A：本地 API（桌面端依赖）
-bun run src/server/index.ts
-
-# 3. 终端 B：桌面端
-cd cc-haha/desktop
-bun run tauri dev
-```
-
-服务默认监听 `http://127.0.0.1:3456`（可用 `SERVER_PORT` 覆盖）。
-
-## 三、联调本机 Manager（heicode）
-
-```bash
-# 1. 起 Manager（heicode）
-cd heicode
-docker compose -f docker-compose.yml -f docker-compose.override.yml up --build -d
-
-# 2. 让客户端把 TaijiAICloud 指向本地 Manager
-cd ../cc-haha
-HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts
-```
-
-完整可用变量见 [`env-variables.md`](./env-variables.md)。
-
-## 四、桌面端常见排错
-
-| 现象 | 原因 / 解决 |
-|------|--------------|
-| `error: script "tauri" exited with code 1` 提示 `cargo metadata` 找不到 | 缺 Rust toolchain；安装后重开终端 |
-| `Could not resolve: "grammy"` / `@larksuiteoapi/node-sdk` | 客户端依赖未装；`cd cc-haha && bun install` |
-| `Cannot find module 'lodash-es/sumBy.js'` | 同上，`bun install` 后再启动 |
-| 端口 3456 被占 | 用 `SERVER_PORT=3457 bun run src/server/index.ts` |
-
-## 五、跑客户端测试
-
-```bash
-cd cc-haha/desktop
-bun run test       # Vitest 单测
-bun run lint       # tsc --noEmit
-```
-
-桌面端构建产物：`bun run build` 或针对平台用 `bun run build:macos-arm64` / `bun run build:windows-x64`。
-
-## 六、Manager（heicode）开发
-
-简版命令以 `heicode/CLAUDE.md` 为准，本节只列联调相关：
-
-```bash
-# 用本地 source 构建（覆盖镜像）
-cd heicode
-docker compose -f docker-compose.yml -f docker-compose.override.yml up --build -d
-
-# 看日志
-docker compose logs -f heicode
-```
-
-启动后访问 `http://localhost:3000`，注册管理员，再测试客户端登录链路。
-
-## 七、站点（website）
-
-```bash
-cd website
-pnpm install
-pnpm dev
-```
-
-或用根目录 `docker-compose.yml` 起静态预览镜像（端口 8888）：
-
-```bash
-docker compose up -d --build heicode-www
-```
-
-## 八、回归三件套
-
-每次大改前后至少回归：
-
-1. 客户端登录（API Key 粘贴 + 浏览器登录二选一）
-2. 拉取模型列表（应来自 Provider API，不是硬编码）
-3. 发起一次对话或 Anthropic Messages 请求
-
-后续端到端闭环以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 的 P0-P5 为准。

docs/saas-manager-agnet-architecture-plan.md

@@ -1,312 +0,0 @@
-# Heicode SaaS Manager 与 Agnet 平台架构计划
-
-本文记录 2026-05-02 讨论后确认的新边界：Heicode 的最终形态是一款覆盖软件生命周期的智能开发 Code 工具。用户注册后，用自然语言描述想法，平台应能逐步完成团队生成、产品文档、原型描述、代码开发、代码检查、生产部署、定期维护和升级。
-
-本文是后续 Manager / NewAPI / Agnet / 凭证托管方案的主参考。旧的 Agnet 接口草案如与本文冲突，以本文为准。
-
-## 一、核心判断
-
-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. 高危生产权限优先走平台代理或审批，不直接把长期密钥注入子 Agnet。
-
-## 三、Manager 的产品主线
-
-Manager 面向普通用户展示的是一条从想法到交付的控制流程，而不是 NewAPI 管理后台。
-
-核心功能：
-
-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 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。
-
-## 四、资源绑定模型
-
-“绑定”不是保存一串密钥，而是创建租户级 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 数据库保存资源元数据和授权关系，不保存明文密钥：
-
-```text
-resources:
-  id
-  tenant_id
-  provider
-  type
-  display_name
-  external_id
-  metadata_json
-  secret_ref
-  status
-
-resource_grants:
-  id
-  tenant_id
-  project_id
-  resource_id
-  agnet_role
-  permissions_json
-  constraints_json
-
-secret_bindings:
-  id
-  tenant_id
-  resource_id
-  secret_provider
-  secret_ref
-  version
-  status
-  last_rotated_at
-```
-
-## 五、开源 Secret Store 架构
-
-SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。
-
-推荐抽象：
-
-```text
-Manager API
-  -> Secret Broker
-  -> Secret Provider
-  -> Vault / Infisical / Azure Key Vault
-```
-
-开源优先方案：
-
-| 方案 | 适用判断 |
-|------|----------|
-| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 |
-| Infisical | 产品体验较好，适合作为可选 Secret Provider，需要进一步验证多租户策略和运行时授权能力 |
-| SOPS + KMS | 适合配置文件密钥，不适合作为 SaaS 动态资源绑定主方案 |
-
-Secret Broker 负责：
-
-- 接收 OAuth / GitHub App / 云授权回调后的凭证。
-- 生成租户隔离的 secret path。
-- 写入 Vault / Infisical / Key Vault。
-- 创建或更新 policy。
-- 保存 secret_ref 到 Manager DB。
-- 轮换、撤销、禁用凭证。
-- 避免密钥进入日志、前端响应、Markdown 和 Git。
-
-Vault 路径示例：
-
-```text
-secret/heicode/tenants/{tenant_id}/resources/{resource_id}/github
-secret/heicode/tenants/{tenant_id}/resources/{resource_id}/azure
-secret/heicode/tenants/{tenant_id}/projects/{project_id}/deployments/{deployment_id}
-```
-
-## 六、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 拿到的是：
-
-```text
-你是 backend-agent
-你可以访问 project-main-repo
-权限是 read_repo / write_branch / create_pr
-凭证由运行环境提供
-禁止输出、持久化或提交任何凭证
-```
-
-子 Agnet 不应拿到：
-
-```text
-github_pat_xxx
-azure_client_secret_xxx
-ssh_private_key
-database_password
-```
-
-运行时访问分两种模式：
-
-| 模式 | 用法 | 适用场景 |
-|------|------|----------|
-| 受控注入 | Pod 通过 Vault Agent、Kubernetes Auth、CSI 或 Workload Identity 读取短期凭证 | Git clone、开发/测试环境、低风险资源 |
-| 平台代理 | 子 Agnet 请求 Manager / Agnet Platform 代执行资源动作 | 生产部署、数据库写入、高危云操作、需要审批的动作 |
-
-推荐混合策略：普通开发资源可受控注入，生产云资源和高危操作走平台代理或审批。
-
-## 七、NewAPI 的边界
-
-NewAPI 不作为普通用户后台开放。Manager 后端通过服务凭据调用 NewAPI，对用户展示必要信息。
-
-Manager 可展示：
-
-- 可用模型。
-- 当前租户或项目额度。
-- 余额。
-- 调用量。
-- 调用日志。
-- 失败日志。
-- 模型可用状态。
-
-Manager 不展示：
-
-- 渠道管理。
-- 模型供应商后台配置。
-- 价格配置。
-- 系统管理员用户管理。
-- NewAPI 原生管理后台入口。
-
-用户登录 Manager，不直接登录 NewAPI。Manager 需要维护用户 / 租户 / 项目到 NewAPI 用户、key 或 quota 的映射。
-
-## 八、认证与权限统一策略
-
-不要求三套系统完全统一登录，但必须统一租户、项目、角色、资源授权语义。
-
-| 系统关系 | 建议 |
-|----------|------|
-| Manager ↔ NewAPI | 服务端对服务端调用。用户不直接进入 NewAPI 后台。Manager 按租户映射 NewAPI key、额度和日志 |
-| Manager ↔ Agnet | 必须共享 tenant / project / deployment / role / resource grant 语义。使用 M2M token 或受控委托令牌 |
-| Agnet ↔ Secret Store | 通过 AKS ServiceAccount、Vault Kubernetes Auth、Workload Identity 或平台代理访问 |
-| 用户 ↔ Manager | Manager 是 SaaS 登录和用户体验入口 |
-
-因此，可行方案是：Manager 统一用户体验和资源权限，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 面向系统强制执行。
-
-## 十、实施 Plan
-
-### P0：文档和边界收敛
-
-- 清理废弃或冲突的旧文档入口。
-- 确认本文为 Manager / NewAPI / Agnet / Secret Store 的主参考。
-- 更新术语表：资源绑定、Resource Grant、Secret Broker、Secret Store、平台代理。
-- 明确代码修改铁律：边界未讨论清楚前不改代码。
-
-### P1：Manager 资源模型
-
-- 将当前“Git 来源”抽象为资源绑定模型。
-- 增加资源类型：Git、SK、项目文档、云账号、单项云资源。
-- 增加 resource_grants，用于把资源分配给项目、角色和子 Agnet。
-- 前端从“填 JSON”升级为“绑定资源 -> 分配角色 -> 部署确认”的向导。
-
-### P2：Secret Broker 与开源 Secret Store
-
-- 选型 Vault 作为首个开源 Secret Provider。
-- 在 Manager 后端实现 Secret Broker。
-- 支持写入、读取引用、轮换、撤销、禁用。
-- DB 只保存 secret_ref，不保存明文密钥。
-- 增加密钥泄露防护：日志脱敏、前端响应过滤、Markdown 生成过滤。
-
-### P3：Agnet 平台 AKS 身份接入
-
-- Agnet 平台支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
-- 支持 Vault Kubernetes Auth 或等价 Workload Identity。
-- 支持按 tenant / project / role 生成 Vault policy。
-- 子 Agnet 运行时只能访问被授权的 secret。
-- 生产云操作支持平台代理或审批。
-
-### P4：NewAPI 解耦
-
-- NewAPI 保持独立服务。
-- Manager 通过服务凭据调用 NewAPI。
-- Manager 展示普通用户需要的模型、余额、额度、调用日志。
-- 隐藏 NewAPI 管理员后台能力。
-- 建立 Manager tenant / user / project 与 NewAPI key / quota / usage 的映射。
-
-### P5：部署和审计闭环
-
-- Manager 生成 AGENT.md / resource context / permission manifest。
-- Agnet 平台部署子 Agnet 后回传 deployment、agent instance、状态和事件。
-- Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
-- 对高危权限增加审批、撤销和运行中失效机制。
-
-## 十一、当前不做
-
-- 不把云密钥写入 Markdown。
-- 不把 NewAPI 后台开放给普通用户。
-- 不让 Agnet 平台成为长期密钥明文存储地。
-- 不在边界未确认时继续堆功能。
-- 不把 Manager 继续改造成 NewAPI 的缝合后台。

docs/sk-lifecycle.md

@@ -1,147 +0,0 @@
-# SK 生命周期（Skill 资产单点真相）
-
-本文是 Heicode 仓库内 **关于 SK 的唯一权威说明**。其它文档涉及 SK 时请相对链接到本文件，避免规则在多处重复。
-
-> 架构边界出处：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。
-> 名称定义：[`glossary.md#sk（skill-资产）`](./glossary.md)。
-
----
-
-## 一、什么是 SK
-
-SK（Skill）= 给 Agnet 子 agent 在运行时注入的 **只读说明类正文**，承载团队规范、流程提示、领域约束、提示词模板等可被编排消费的「软知识」。
-
-它不是：
-- 模型权重或微调样本
-- 业务数据或敏感凭据
-- Agnet 控制台可在线编辑的内容
-
----
-
-## 二、唯一编辑入口
-
-| 来源 | 谁可以写 | 谁不能写 |
-|------|----------|----------|
-| Git 仓库（事实源） | 经 **Heicode 客户端** 提交，或用户在 Git 远端按授权直接操作 | Manager / Agnet **不得**提供改 SK 正文的 API/UI |
-| 上传 MD / 文件（补充源） | 仅经 **Heicode 客户端** 提供的入口 | Manager 仅做登记与透传；Agnet 仅做只读副本 |
-
-**底线**：若 Agnet 控制台出现可直接改 SK 正文的 API 或 UI，视为 **违背产品边界**，需在评审中拒绝。
-
----
-
-## 三、来源（`sk_sources`）
-
-SK 在部署请求中以 `sk_sources` 数组绑定到指定子 agent。两类来源类型并存：
-
-```json
-{
-  "role_template": "sub_reviewer",
-  "sk_sources": [
-    {
-      "type": "git",
-      "repo_ref": {
-        "connection_id": "gitconn_1",
-        "repo_url": "https://example.com/org/sk-repo.git",
-        "ref": "main",
-        "paths": ["policy/review.md"]
-      }
-    },
-    {
-      "type": "upload",
-      "artifact_id": "sk_upl_9f3a",
-      "mime": "text/markdown"
-    }
-  ]
-}
-```
-
-兼容字段：
-- `sk_file_refs`（路径数组）：可视作 `sk_sources` 的简写，**展开规则需在联合 RFC 中声明**。
-
----
-
-## 四、解析、快照、注入
-
-```mermaid
-flowchart LR
-  src["sk_sources<br/>(git / upload)"]
-  fetch["Agnet 解析<br/>fetch + checkout / 拉取制品"]
-  snapshot["不可变快照<br/>commit_sha · artifact 版本"]
-  inject["注入子 agent<br/>(运行时只读)"]
-
-  src --> fetch --> snapshot --> inject
-```
-
-要求：
-- 每个 `deployment_id` / `sub_agent_id` 必须能查到对应 **已解析的 SK 快照**
-- 运行时 **仅** 使用该快照内容，不得在执行中切换版本
-- 快照锚点：
-  - `git`：`commit_sha` + 文件路径哈希
-  - `upload`：`artifact_id` + 版本
-
-Agnet 不需要、也不应该提供针对 SK 正文的 `PUT` / `PATCH`：写操作发生在 Git 远端，或经 Heicode 上传入口。
-
----
-
-## 五、刷新策略
-
-需要约定何时重新解析 SK 并发布新快照：
-
-| 触发 | 期望行为 |
-|------|----------|
-| Git 出现新 commit | 按策略重新解析；可即时或滚动 |
-| 用户在 Heicode 触发刷新 | 即时重新解析，并向 Manager 发出事件 |
-| 部署新版本 | 必然重新解析 |
-
-事件示例：`sk_snapshot_refreshed`（可在事件流中下发，Heicode 客户端可提示「已用新版本 SK」）。
-
----
-
-## 六、写权与读权矩阵
-
-| 行为 | Heicode 客户端 | Heicode Manager | Agnet 平台 / 子 agent |
-|------|----------------|-----------------|------------------------|
-| 创建 / 修改 / 删除 SK 正文（Git） | 允许（提交到仓库） | **禁止** | **禁止** |
-| 创建 / 替换上传类 SK | 允许（专用入口） | 仅登记/透传 | **禁止** |
-| 注册 Git 凭据 / 连接 | 发起授权 | 持久化、轮换 | 按租户使用 |
-| 读 SK 快照 | 允许（用于展示） | 允许（运营/审计） | 允许（运行时注入） |
-| 列出 SK 绑定关系 | 允许 | 允许 | 允许 |
-
-权限模型以后续 P1-P3 的 Resource Grant、Secret Broker 和 Agnet AKS 运行身份实现为准：
-- `agnet:credential:write`：用于绑定 Git Token / 云 SA
-- `heicode:sk:write`（示例命名）：仅授予 Heicode 客户端身份
-
----
-
-## 七、与一键部署的关系
-
-Heicode Manager 提供「部署 Agnet 团队」操作时，部署请求或等价 permission manifest 须显式包含：
-
-- 团队成员列表与组织内角色
-- 各成员所用模型 / `provider_profile_id`
-- 子 agent 模板与 `sk_sources`
-- **子 agent 云上 / 运行时权限等参数**（如 `runtime_execution`）与 **SK 允许 / 禁止策略**（如 `sk_access_policy`）须 **在 Agnet 拉起编队/运行时随部署请求传入**；**生效副本落在 Agnet**，由其运行时强制执行；Manager 仅透传配置并展示回传锚点，不作执行时代替
-
-部署完成后 Manager 应能展示：
-
-`团队成员 → 模型 → Agnet 子 agent → SK 源（Git ref / 上传件）→ 快照版本 → 运行时绑定 → 生效 SK 策略`
-
-未授权模型 **不得** 在执行路径上静默生效。
-
----
-
-## 八、违规判定（评审清单）
-
-新增能力时，凡命中下列之一，需在评审中明确拒绝：
-
-- 提供 Agnet 或 Manager 控制台对 SK 正文的在线编辑器
-- 在 Agnet 暴露面向 SK 正文的通用写 API
-- 子 agent 在运行中拉取绑定列表外的 SK 路径
-- 跨租户读取 SK 快照
-- 「软隔离」下未带 `tenant_id` 的 SK 查询路径
-
----
-
-## 九、与 Heicode 客户端实现的关联
-
-当前仓库中 SK 编辑入口由 Heicode 客户端承担。具体逻辑实现以 `cc-haha/` 内代码为准，集成方仅需要遵守本文 SK 边界即可。

docs/vision-heicode-full-stack-agentic-dev.md

@@ -1,183 +0,0 @@
-# Heicode 愿景：团队软件交付范式（方向性说明）
-
-本文档只回答 **「为何存在」「指向何方」「坚持什么原则」**——不涉及版本排期、接口冻结清单或逐步交付计划；后者应在路线图或项目管理工具中单独立项。
-
-**代号表（与真实工程名无绑定，仅为行文一致）**
-
-| 称谓 | 含义 |
-|------|------|
-| **Heicode Manager** | SaaS 用户控制台与编排中枢，负责用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计，以及面向普通用户展示模型、余额和调用日志。 |
-| **Heicode** | 终端与桌面侧人机编程客户端及本地服务（与 Manager 区分时亦称「Heicode 客户端」）。 |
-| **Orchard** | 子智能体编排与团队模板所在平台（概念名）。 |
-| **执行单元** | 在编排侧按角色模板实例化的智能体实例。 |
-
----
-
-## 一、我们想改变什么
-
-组织交付软件时，常见断层出在：**规格与实现脱节**、**质量闸门含糊**、**发布与环境无人认领**、**事后难以复盘**。个人侧的「写代码更快」解决不了这些结构性问题。
-
-Heicode 的关切点是：**在多人、多环境、多迭代的条件下，如何让对齐方式、责任边界与可追溯性默认成立**——智能体适合承接其中 **标准化、可重复** 的环节；人机分工与审批边界则由组织策略定义，而不是由某一工具一次性替你定死。
-
----
-
-## 二、北极星与成功图景（定性）
-
-- **北极星**：团队能以可复述的方式回答——「谁在何时对什么负责」「依据是什么」「如何回溯到某次发布或某条决策」。
-- **成功图景（不写 KPI）**：人在关键环节保有裁决权；机器与智能体放大吞吐与一致性；交付物（规格、代码、测试结论、发布记录）能与版本或发布锚点关联；编排与权限足以支撑多团队并存而不互相踩踏。
-
----
-
-## 三、指导原则
-
-1. **可追溯优于单次极速**：宁可多一道可查的记录，也不依赖口头默契替代闸门。
-2. **范式可裁剪**：瀑布与敏捷是协作隐喻，不是教条；规模与角色应由组织工作坊裁剪，而非照搬单一数字。
-3. **集成可替换**：Manager、客户端、编排平台、云与流水线均以「契约与边界」相接，避免叙事绑死在某一厂商或目录名上。
-4. **人机协同**：涉及权限、费用、生产变更与高敏数据的决策，默认保留人在回路；自动化扩展 **提案权**，不默认 **无限代理权**。
-5. **对内对外叙事分层**：愿景文档不写实施说明书；角色代号与编队明细放入附录，以免喧宾夺主。
-
----
-
-## 四、战略支柱（方向）
-
-### 4.1 身份与策略一元化
-
-使人机在统一身份与组织策略下工作：谁能访问何种模型、何种环境、何种仓库与密钥引用——应由 Manager 统一资源与权限语义，并通过 NewAPI、Agnet 与 Secret Store 各自的服务边界执行，而不是散落在若干控制台口径不一致。
-
-### 4.2 编排与角色范式
-
-把「谁在流水线哪一段接力」说清楚：既可按阶段闸门（瀑布隐喻）也可按迭代闭环（敏捷隐喻）组织 **执行单元**；重点是 **闸门不被静默跳过**、**角色不重叠到互相推诿**。具体几人几岗属于落地裁剪，见附录。
-
-### 4.3 全生命周期可信交付
-
-从构想到运营，关键产物应能对齐到分支、标签或发布单元：**规格、实现、验证、发布、运维与复盘** 之间有可追溯链路；多云与环境仅是载体，原则是 **最小权限与环境晋升**。
-
-### 4.4 平台化协作而非单机熟练度
-
-与「个人终端技巧」相比，Heicode 更强调 **跨角色、跨会话、跨环境** 的一体化协作叙事——客户端与 Manager、编排侧共同服务于同一交付故事线。
-
----
-
-## 五、概念分层（鸟瞰）
-
-```
-人机入口（官网 · 控制台 · CLI / Desktop）
-        ↓ 同一身份与策略边界
-Heicode Manager ←→ Heicode 客户端
-        ↓
-编排与执行（Orchard：角色模板 · 执行单元 · 状态）
-        ↓
-资产与环境（仓库 · 流水线 · 运行环境与观测）
-```
-
-**边界**：编排平台内部实现细节不属于愿景正文；Heicode 关心的是 **契约、体验与安全边界** 是否说得清、守得住。
-
-**与编排侧（如 Agnet）的可观测分工（方向性）**：平台回传的 **运行态与性能类信息**（是否在跑、健康与资源等）宜在 **Heicode Manager** 上呈现；**子执行单元在会话中的产出内容**宜在 **Heicode** 编码与工作过程中 **实时展示**。团队与个人均可使用两端；划分依据是 **信息类型与载体**。具体边界以 [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) 为准。
-
----
-
-## 六、协作范式（方向性，非排期）
-
-- **瀑布隐喻**：强调阶段闸门与可审计链条；适合强合规、长评审链的组织语境——「最小编队 / 最大编队」表示协调复杂度量级，不是 HR 编制。
-- **敏捷隐喻**：强调短迭代与跨职能闭环；适合快速试错的产品语境——同样，人数区间是 **协调上限的提示**，落地时需结合真实产能与依赖。
-- **超出协调上限时**：拆分子系统、拆分 Squad 或引入共享平台能力，而不是在同一队列上无限堆角色。
-
-全生命周期上，Heicode 主张覆盖 **构思 → 规格 → 实现 → 验证 → 发布 → 运维 → 迭代** 的 **语义连贯**，而非单独优化其中一环的工具速度。
-
----
-
-## 七、可信交付与多主体协作（方向）
-
-多执行单元、多人协作时，需要 **可关联的会话与决策摘要**、与分支或发布对齐的文档、以及可供审计的开发日志聚合维度——实现形态可为日志服务、工单或治理平台，愿景层只坚持 **可追溯** 这一条。
-
----
-
-## 八、已知张力（非缺陷清单）
-
-组织级叙事依赖 **编排侧的租户隔离、权限模型与可观测性**；客户端体验若对标商业产品，属于 **长期对齐** 而非愿景正文承诺。工程仓库如何组织、文档入口如何统一，属于 **工程卫生**，与范式方向并行演进。
-
----
-
-## 九、阶段性方向（非路线图）
-
-仅给出 **时间无序** 的三层递进意象，方便对齐讨论；**不绑定季度、不设里程碑编号**：
-
-1. **对齐**：身份、策略与叙事口径一致，避免「各说各话」。  
-2. **贯通**：人机链路在一条交付故事线下可走通，关键闸门有据可查。  
-3. **规模化**：编队模板与审批策略可按组织复制，而不是单次项目手工拼装。
-
----
-
-## 十、开放议题（范式层）
-
-- 执行单元的 **所有权**：按项目、组织还是环境切分？  
-- **人在回路**：哪些类别动作必须人工批准？  
-- **商业与责任**：对内效率工具与对外承诺的边界如何划分？  
-
----
-
-## 附录 A：编队规模与角色明细（落地参考）
-
-以下为 **职务说明书级别的参考**，用于工作坊裁剪与编排映射；**不属于愿景层的承诺范围**。数字与代号均可按组织调整。
-
-### A.1 规模总览
-
-| 模式 | 最小编队（执行单元数） | 最大编队（执行单元数） |
-|------|-------------------------|-------------------------|
-| **瀑布** | **5** | **9** |
-| **敏捷** | **3** | **8** |
-
-### A.2 判定依据摘要
-
-| 维度 | 瀑布 | 敏捷 |
-|------|------|------|
-| **流程特征** | 阶段闸门强、评审链长 | 迭代短、反馈密 |
-| **「最小」含义** | 仍能走完规格→设计→实现→验证→上线且不合并关键闸门 | 仍能在一个迭代内交付可演示增量并有独立质量门禁 |
-| **「最大」含义** | 覆盖常见专岗且不超过约 9 个并行协调节点 | 覆盖规模化小组且不超过约「两个披萨」协调上限 |
-| **溢出策略** | 拆子系统或多套实例 | 拆 Squad 或平台组共享，而非单队列无限加人 |
-
-### A.3 瀑布 — 最小编队（5）
-
-| 代号 | 角色 | 职责摘要 |
-|------|------|----------|
-| `WF-BA` | 业务/需求分析师 | 规格、范围、验收标准、变更登记 |
-| `WF-ARC` | 解决方案架构师 | 架构边界、接口与数据契约、NFR 落档 |
-| `WF-DEV` | 软件工程师 | 实现、单测、静态检查、设计澄清 |
-| `WF-QA` | 测试工程师 | 测试策略与用例、缺陷与回归、发布前质量门禁结论 |
-| `WF-REL` | 发布与运维工程师 | CI/CD、环境一致性、发布编排与回滚预案、基础可观测 |
-
-### A.4 瀑布 — 最大编队（9）
-
-在 A.3 思路上扩展：`WF-PM`、`WF-DEV-B`、`WF-DEV-F`、`WF-SEC`、`WF-DOC` 等专岗；职责聚焦「合规、前后端分立、安全与文档独立审计」场景。
-
-### A.5 敏捷 — 最小编队（3）
-
-| 代号 | 角色 | 职责摘要 |
-|------|------|----------|
-| `AG-PO` | 产品负责人 | Backlog、验收标准、冲刺目标 |
-| `AG-DEV` | 软件工程师 | 迭代实现与设计澄清、评审协作 |
-| `AG-QA` | 测试工程师 | 迭代测试、自动化与探索性测试、DoD 质量项 |
-
-### A.6 敏捷 — 最大编队（8）
-
-在 A.5 基础上扩展：`AG-SM`、`AG-TL`、`AG-DEV-A`、`AG-DEV-B`、`AG-UX`、`AG-SRE` 等；强调双轨并行与嵌入式流程时协调上限。
-
-### A.7 角色对照（摘编）
-
-| 通用抽象 | 瀑布最小 | 瀑布最大 | 敏捷最小 | 敏捷最大 |
-|----------|----------|----------|----------|----------|
-| 产品/需求 | BA | PM + BA | PO | PO |
-| 架构 | ARC | ARC | （并入 DEV/TL） | TL |
-| 开发 | DEV | DEV-B + DEV-F | DEV | DEV-A + DEV-B |
-| 测试 | QA | QA | QA | QA |
-| DevOps/SRE | REL | REL | （平台/兼任） | SRE |
-| 安全/合规 | （ARC 兼） | SEC | （门禁委托） | （平台策略 + TL） |
-| 技术写作 | （REL 兼） | DOC | （最小化） | （可由 PO 兼） |
-| 流程推动 | — | — | — | SM |
-| 体验设计 | — | （可由 DEV-F 兼） | — | UX |
-
----
-
-*愿景正文止于附录之上；附录仅供落地与工作坊使用。*
-
-**最近更新**：2026（愿景重写：方向优先，明细迁入附录）