Files

T

gongzhiyong 2a6a709f58 docs: expand integration and onboarding documentation set

Add a complete docs skeleton for onboarding and integration, including orchestration-plan contract, acceptance matrix, OAuth flow, architecture maps, and milestone status tracking to support Agnet-facing delivery work.

Made-with: Cursor

2026-04-30 14:26:25 +08:00

5.1 KiB

Raw Blame History

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

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

上游契约出处：integration/agnet-platform-api-design.md §3.2 / §5.0 / §5.0.1。名称定义：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 绑定关系	允许	允许	允许

权限模型在 integration/agnet-platform-api-design.md §3 中给出 RBAC 角色：

agnet:credential:write：用于绑定 Git Token / 云 SA
heicode:sk:write（示例命名）：仅授予 Heicode 客户端身份

七、与一键部署的关系

integration/agnet-platform-api-design.md §5.0 要求 Heicode Manager 提供「一键部署 Agnet 团队」单次操作，部署请求体须显式包含：

团队成员列表与组织内角色
各成员所用模型 / provider_profile_id
子 agent 模板与 sk_sources

部署完成后 Manager 应能展示：

团队成员 → 模型 → Agnet 子 agent → SK 源（Git ref / 上传件）→ 快照版本

未授权模型不得在执行路径上静默生效。

八、违规判定（评审清单）

新增能力时，凡命中下列之一，需在评审中明确拒绝：

提供 Agnet 或 Manager 控制台对 SK 正文的在线编辑器
在 Agnet 暴露面向 SK 正文的通用写 API
子 agent 在运行中拉取绑定列表外的 SK 路径
跨租户读取 SK 快照
「软隔离」下未带 tenant_id 的 SK 查询路径

九、与 Heicode 客户端实现的关联

当前仓库中 SK 编辑入口由 Heicode 客户端承担。具体逻辑实现以 cc-haha/ 内代码为准，集成方仅需要遵守本文 SK 边界即可。

5.1 KiB Raw Blame History Unescape Escape