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