chenchen/heicode-win

Fork 0

Files

T

gongzhiyong 72d0e095a4 docs: remove obsolete agnet plans

2026-05-02 22:11:19 +08:00

5.3 KiB

Raw Blame History

SK 生命周期（Skill 资产单点真相）

本文是 Heicode 仓库内 关于 SK 的唯一权威说明。其它文档涉及 SK 时请相对链接到本文件，避免规则在多处重复。

架构边界出处：saas-manager-agnet-architecture-plan.md。名称定义：glossary.md#sk（skill-资产）。

一、什么是 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。两类来源类型并存：

{
  "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 中声明。

四、解析、快照、注入

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 边界即可。

5.3 KiB Raw Blame History Unescape Escape