pj0235-eai_agentplatform/docs/02_Architecture/AR11_技能专员连接器可删除封装规范.md

AR11 Skill / Specialist / Connector Removable Packaging Specification

版本：V1.3 日期：2026-09-18
性质：规范性文件（normative）
适用对象：skill、specialist、connector
关联文档：

• AR06_技能封装规范.md
• AR09_对象命名规范.md
• AR10_应用可删除封装规范.md

1. 目标

本文定义 skill、specialist、connector 三类对象的可删除封装方式。

本文中的“可删除”指：

1. 删除一个对象目录
2. 删除一条注册项
3. 不需要全仓手工搜改业务代码
4. 重新构建后不出现编译错误
5. 运行卸载脚本后，不残留该对象自有资源

在当前单仓工程内，合理目标应为：

• 删一个目录 + 删一条注册项 + 跑一次卸载 = 安全移除一个对象包

但三类对象的封装深度不同：

1. connector 是连接插件包
2. skill 是能力插件包
3. specialist 是策略定义包

它们不能机械复用同一套“完整业务包”模板。

2. 与 AR10 的关系

AR10_应用可删除封装规范.md 定义的是 xapp 的可删除封装规范。

本文是在 AR10 基础上，对另外三类对象做边界化扩展：

1. 复用 AR10 的 manifest / registry / contracts / own boundary 思想
2. 保留“删目录 + 删注册项 + 跑卸载”的工程目标
3. 明确指出：xapp 的“完整业务包”模板不能原样套到 skill / specialist / connector

换句话说：

1. AR10 解决的是“一级业务包如何可删除”
2. AR11 解决的是“能力包 / 策略包 / 连接包如何可删除”

3. 对 AR10 的复核结论

3.1 正确的部分

AR10 的大方向是正确的，尤其是以下几点：

1. 平台层只能认 manifest / registry / contracts
2. 总路由和总导航不应再手写对象业务路径
3. 私有对象不应继续停留在平台总 model 包
4. 持久化模型不应直接兼任 API DTO
5. 统计、画像、后台管理应通过 provider 聚合
6. “删目录 + 删注册 + 跑卸载”是比“删一个文件”更现实的工程目标

这些判断对 xapp 是成立的，也应成为其他对象的总体方向。

3.2 需要收窄的部分

AR10 的结构不能原样复用于全部对象，主要因为三类对象的职责不同：

1. skill 不是业务子系统，通常不 own 大量页面、任务和后台管理
2. specialist 不是业务应用，更不应强制 own 独立表、独立路由、独立后台
3. connector 才最接近真正的可插拔基础设施模块

因此：

1. 对 xapp，“完整业务包”模板基本成立
2. 对 connector，AR10 模板大体可复用，但要加强 auth / webhook / secret / health / job 的 own 边界
3. 对 skill，应改写为“能力包”模板
4. 对 specialist，应改写为“策略定义包”模板

3.3 最终结论

AR10 是对的，但它的适用对象主要是 xapp。

若把 AR10 原样套用到 skill / specialist / connector，会出现两种问题：

1. 对 connector 还不够彻底
2. 对 specialist 则会明显过度工程化

4. 三类对象的共同硬规则

4.0 一对象一目录是最终形态

对 skill / specialist / connector 三类对象而言，最终封装形态必须满足：

1. 一个对象对应一个后端目录
2. 一个对象对应一个前端目录
3. 该对象的定义文件、资源边界、可删除元数据都落在自己的目录中

因此：

1. 允许中心化注册
2. 不允许中心化定义

“中心化注册”是指：

1. registry 统一列出有哪些对象 manifest
2. installer / uninstall 统一执行安装和清理
3. platform core 统一聚合 provider

“中心化定义”是指：

1. 在一个平台公共文件里集中维护多个 specialist 的 prompt 和绑定
2. 在一个平台公共文件里集中维护多个 skill 的 schema 和静态定义
3. 在一个平台公共文件里集中维护多个 connector 的 catalog、能力和实现细节

前者允许，后者不是最终封装形态。

4.0.1 允许中心化 / 禁止中心化

类型	是否允许	说明
core/registry 集中列出 manifest	允许	这是注册中心
core/uninstall 统一执行清理	允许	这是卸载中心
specialists/rules.go 这类集中式多专员定义文件	禁止作为最终形态	最多只能做迁移期兼容层
skills/keys.go 或全局 skill catalog 承载多个 skill 完整定义	禁止作为最终形态	这会阻断目录级删除
connectors/static_catalog.go 集中维护多个 connector 完整能力定义	禁止作为最终形态	该文件承担完整定义中心职责，未收敛到注册中心形态

4.1 平台层只能依赖 registry / manifest / contracts

平台层允许依赖：

1. core/registry
2. core/contracts
3. 对象包暴露的 manifest

平台层禁止依赖：

1. 对象包内部的 domain
2. 对象包内部的 repo
3. 对象包内部的 service
4. 对象包内部的前端组件和内部运行时实现

4.2 总路由不得手写对象内部业务入口

总路由只能装配对象包，不得继续手写对象内部路径。

4.3 总导航不得手写对象内部菜单

平台导航只能聚合 manifest 暴露的菜单项，不能再认识对象包内部细节。

4.4 平台 seed 不得直接创建具体对象定义

平台总 seed 只允许：

1. 加载 registry
2. 调用对象包自注册 seed

平台总 seed 不允许继续硬编码：

1. 某个 specialist 的 prompt 和绑定
2. 某个 skill 的默认定义
3. 某个 connector 的静态目录项

4.5 删除对象包后，平台只能“少一个能力”

删除某个对象包后，平台允许出现：

1. 某个能力不再可选
2. 某个菜单自动消失
3. 某个 provider 的结果缺失

平台不允许出现：

1. 编译错误
2. 运行时 import error
3. 路由残留导致启动失败
4. 平台层空指针

4.6 一级导航三是对象治理区

skill / specialist / connector 三类对象，应统一纳入一级导航三进行治理。

一级导航三定位为对象治理区。

它应至少支持：

1. 查看对象基础信息
2. 编辑对象定义
3. 启停对象
4. 复制对象
5. 版本管理
6. 发布与回滚

因此：

1. 对象包的默认定义在目录中
2. 对象包的治理入口在导航三中
3. 对象包的当前生效状态不应直接依赖源码文件实时变更

4.7 对象包文件层与运行时持久化层必须分离

为了同时满足“目录级可删除”和“在线可编辑”，必须显式区分两层：

1. 对象包文件层
2. 运行时持久化层

对象包文件层负责：

1. 默认定义
2. 内置模板
3. manifest
4. 可导入导出的包资源
5. 可版本化的静态素材

运行时持久化层负责：

1. 管理员在导航三中的编辑结果
2. 草稿版本
3. 已发布版本
4. 回滚记录
5. 审计记录

因此：

1. 包目录是“对象源码与默认定义”
2. 数据库是“当前运行时生效定义”

4.8 在线编辑结果默认不直接回写源码文件

管理员在导航三中修改对象时，默认不应直接写回仓库内的 json / md / js / go 文件。

原因如下：

1. 运行中服务不适合直接改仓库源码
2. 多人协作下，文件写回缺少稳定的审计、并发控制、发布控制
3. 运行时读取数据库比扫描仓库文件更稳定
4. “对象包可删除”和“在线治理”是两套不同诉求，不能混为一体

因此规范要求：

1. 包目录中的 json / md 文件用于默认定义、模板、导入导出、离线版本管理
2. 在线编辑后的结构化结果应写入数据库
3. 运行时以数据库中的发布版本为准，而不是以仓库文件实时内容为准

4.9 文件格式建议

对象包文件层推荐使用可读、可审阅的静态格式：

1. manifest：go / js
2. 结构化配置：json
3. 长文本说明：md
4. 资源素材：对象目录内自有资源文件

但这些文件的角色是：

1. 包定义来源
2. 默认值来源
3. 导入导出载体
4. 开发期版本管理载体

它们不是在线治理的唯一真实存储。

4.10 发布模型建议

对象治理区建议统一采用以下发布模型：

1. 包默认定义
2. 运行时草稿
3. 已发布版本
4. 回滚版本

推荐流程：

1. 从对象包默认定义初始化对象
2. 管理员在导航三中编辑草稿
3. 发布后生成当前生效版本
4. 运行时只读取已发布版本
5. 删除对象目录时，只影响该对象的包来源和后续发布，不影响历史审计记录

4.11 定义条目也属于对象 own boundary

对 skill / specialist / connector 而言，own boundary 不能只覆盖代码、表和 storage key，还必须覆盖定义层资源。

定义层资源至少包括：

1. 对象定义记录
2. 对象目录页 / 市场页 / 治理页中的对象条目
3. seed 自动创建的对象默认定义
4. 对象包发布后形成的对象目录映射

如果删除对象目录后，这些定义条目仍然残留，那么就仍会出现：

1. 僵尸入口
2. 失效对象卡片
3. 后台目录中的死条目
4. 平台试图按已删除对象继续加载配置

因此，定义条目必须被视为对象 own boundary 的一部分。

4.12 Shared Reference Policy

对象删除时，不仅要处理 own resource，还要处理平台共享域中的历史引用。

共享引用至少包括：

1. 历史任务
2. 项目绑定
3. 收藏 / 最近使用
4. 历史通知
5. 审计日志
6. 历史发布版本

规范允许以下策略：

1. block_uninstall
2. convert_to_tombstone
3. detach_reference
4. readonly_history

不同对象可选择不同策略，但必须显式声明，不能留给运行时临时猜测。

4.13 Enforcement / Guard

若要保证封装不回退，平台至少应建立以下自动守卫：

1. import 边界检查
2. registry 完整性检查
3. owned resource audit
4. 定义条目完整性检查
5. shared reference dry-run 检查
6. CI gate

5. Skill 规范

5.1 Skill 的工程定义

skill 的本质是“能力包”，不是“业务子系统”。

它回答的是：

1. 这件事怎么做
2. 需要什么输入
3. 会产生什么结果

它通常不应该自带完整后台系统。

5.2 与 AR06 的关系

AR06_技能封装规范.md 解决的是“技能文件如何组织”。

本文在此基础上进一步定义：

1. 技能如何拥有 manifest
2. 技能如何注册到 platform
3. 技能如何形成 own boundary
4. 技能如何达到目录级安全删除

所以：

1. AR06 是文件组织规范
2. AR11 是可删除封装规范

二者不冲突，而是前后两层。

5.3 推荐目录结构

后端

backend-go/internal/skills/
  core/
    contracts.go
    registry.go
    manifest.go
    uninstall.go
  packages/
    document_translate/
      manifest.go
      provider.go
      dto/
      schema/
      tests/
    contract_review/
      manifest.go
      provider.go
      dto/
      schema/
      tests/

前端

frontend/src/skills/
  core/
    contracts.js
    registry.js
    installer.js
    uninstall.js
  packages/
    document-translate/
      manifest.js
      executor.js
      ResultCard.vue
      composer.js
      schema.js
      assets/
    contract-review/
      manifest.js
      executor.js
      ResultCard.vue
      composer.js
      schema.js
      assets/

5.4 Skill manifest 必须拥有的内容

每个 skill manifest 至少应声明：

1. key
2. label
3. source
4. executor
5. input_schema
6. output_schema
7. artifact_schema
8. result_renderer
9. starter_prompts
10. owned_storage_keys
11. owned_tables
12. owned_definition_keys
13. owned_catalog_entries
14. shared_reference_policy
15. register_providers()

5.5 Skill registry 的职责

skill registry 只负责：

1. 注册 skill manifest
2. 返回可用技能清单
3. 安装技能入口
4. 卸载技能资源

skill registry 不负责：

1. 业务执行
2. 页面逻辑
3. 平台级 fallback 逻辑

5.6 Skill 的资源归属

skill 可以 own：

1. 执行器
2. 输入输出 schema
3. 结果卡片
4. 对话挂载块
5. 可选 provider
6. 可选 own table
7. 可选 own localStorage key

skill 不应默认 own：

1. 一整套业务导航
2. 大量后台管理页面
3. 一整套任务系统
4. 专属业务报表入口

5.7 Skill 的命名空间建议

一个 skill 若拥有自有资源，命名空间应为：

1. 表：skill_<skill_key>_*
2. storage key：skill:<skill_key>:*
3. provider key：skill.<skill_key>.*

5.8 Skill 的删除标准

一个 skill 只有满足以下条件，才算达到“整包可删除”：

1. 删除 frontend/src/skills/packages/<skill>/
2. 删除 backend-go/internal/skills/packages/<skill>/
3. 删除 registry 注册项
4. 平台页面不直接 import 它的 executor / result card
5. 平台构建通过
6. 只是少了这个技能，不影响其他技能和工作台运行

5.9 当前仓库的主要问题

当前仓库中，skill 仍存在以下硬耦合：

1. 技能静态定义大量停留在全局配置
2. 后端存在独立的技能 key 硬编码白名单
3. 工作台页面仍直接感知部分技能运行时细节

因此当前的 skill 还没有达到目录级安全删除标准。

5.10 迁移期兼容层判定

以下结构只允许作为迁移期兼容层存在，不是最终封装形态：

1. 全局静态 skill catalog
2. 后端统一维护的 skill key 白名单
3. 平台页面直接 import 单个 skill 的内部 executor / result card

兼容层若存在，必须满足：

1. 只做桥接和转发
2. 不再新增新 skill 定义
3. 有明确退场目标

5.11 Skill 在对象治理区的编辑模型

skill 应允许在一级导航三中被查看、编辑、复制、启停和发布。

但编辑内容应分层：

1. 包目录中保留 skill 的默认定义
2. 导航三中的编辑结果写入运行时持久化层

对 skill 而言，包目录中适合保留的内容包括：

1. manifest.js / manifest.go
2. schema.js / schema.json
3. starter prompts
4. result renderer 的默认元数据

运行时持久化层适合保存：

1. 当前启用状态
2. 管理员修改后的输入输出 schema
3. 对话挂载配置
4. 发布版本与回滚记录

因此，skill 可以使用 json 表达部分默认定义，但导航三中的在线编辑结果不应直接回写 skill 源码目录。

6. Specialist 规范

6.1 Specialist 的工程定义

specialist 的本质是“策略定义包”，不是“业务应用包”。

它回答的是：

1. 以谁的方式做
2. 用什么身份说话
3. 默认挂载哪些技能和连接器
4. 以什么交互卡片和任务骨架呈现

因此，不应把每个 specialist 都设计成自带一整套后端系统的业务模块。

6.2 推荐目录结构

后端

backend-go/internal/specialists/
  core/
    contracts.go
    registry.go
    prompt_provider.go
    binding_provider.go
    uninstall.go
  packages/
    contract_review/
      manifest.go
      prompt.md
      bindings.json
      interaction_card.json
      seeds.go
      tests/
    report_generation/
      manifest.go
      prompt.md
      bindings.json
      interaction_card.json
      seeds.go
      tests/

前端

frontend/src/specialists/
  core/
    contracts.js
    registry.js
    uninstall.js
  packages/
    contract-review/
      manifest.js
      interaction-card.json
      starter-prompts.json
      bindings.json
      assets/
    report-generation/
      manifest.js
      interaction-card.json
      starter-prompts.json
      bindings.json
      assets/

6.3 Specialist manifest 必须拥有的内容

每个 specialist manifest 至少应声明：

1. key
2. label
3. mode
4. prompt_file
5. interaction_card
6. starter_prompts
7. allowed_skills
8. allowed_connectors
9. default_task_template
10. default_action_template
11. owned_seed_keys
12. owned_storage_keys
13. owned_definition_keys
14. owned_catalog_entries
15. shared_reference_policy

6.4 Specialist registry 的职责

specialist registry 只负责：

1. 注册 specialist manifest
2. 暴露 prompt provider
3. 暴露 binding provider
4. 安装 specialist 目录项
5. 卸载 specialist 自有资源

specialist registry 不负责：

1. 创建任务实例
2. 执行技能
3. 查询 connector 数据

6.5 Specialist 的资源归属

specialist 应 own：

1. prompt / rule file
2. 技能绑定
3. 连接器绑定
4. 交互卡片
5. 默认任务骨架
6. 默认动作骨架
7. 自身 seed

specialist 不应默认 own：

1. 独立业务数据表
2. 独立后台管理系统
3. 独立业务路由
4. 独立统计系统

除非未来出现真正“专员子产品”级别的对象，否则不建议突破这条边界。

6.6 Specialist 的命名空间建议

specialist 若拥有自有资源，命名空间应为：

1. seed key：specialist.<specialist_key>.*
2. storage key：specialist:<specialist_key>:*
3. provider key：specialist.<specialist_key>.*

6.7 Specialist 的删除标准

一个 specialist 只有满足以下条件，才算达到“整包可删除”：

1. 删除 frontend/src/specialists/packages/<specialist>/
2. 删除 backend-go/internal/specialists/packages/<specialist>/
3. 删除 registry 注册项
4. 平台 prompt 组装只通过 provider，不直读具体对象文件
5. 任务系统遇到历史 specialist_key 时可安全 fallback
6. 平台构建通过
7. 只是少了这个专员定义，不影响任务系统和其他专员

6.8 当前仓库的主要问题

当前仓库中，specialist 仍存在以下硬耦合：

1. 平台 API 仍直接组装专员 prompt
2. 平台种子仍承载专员说明书和技能绑定
3. 其他模块仍直接感知专员的具体字段结构

因此当前的 specialist 仍然是“平台共享对象”，还不是可删除的策略定义包。

6.9 关于集中式 rules.go 的判定

类似下面这种结构：

1. 一个公共文件里集中维护多个 specialist 的 prompt
2. 同一个公共文件里集中维护多个 specialist 的 skill binding
3. 同一个公共文件里集中维护多个 specialist 的默认规则草稿

它不算完成封装。

这种文件最多只能算：

1. 迁移期种子汇总
2. 迁移期兼容层
3. 过渡期桥接实现

但它不是最终形态。

specialist 的最终形态必须是：

1. 一个 specialist 一个目录
2. 每个 specialist 自己拥有 prompt / binding / interaction card / manifest
3. 平台只通过 registry 和 provider 认识它

6.10 Specialist 在对象治理区的编辑模型

specialist 也应允许在一级导航三中被查看、编辑、启停、复制和发布。

但其编辑模型应遵守“文件层与持久化层分离”：

1. 包目录保留默认 prompt、默认 binding、默认 interaction card
2. 导航三中的编辑结果写入数据库中的 specialist 草稿与发布版本

对 specialist 而言，包目录中适合保留的内容包括：

1. prompt.md
2. bindings.json
3. interaction_card.json
4. starter-prompts.json
5. manifest.go / manifest.js

运行时持久化层适合保存：

1. 管理员编辑后的 prompt 版本
2. 管理员编辑后的技能绑定和连接器绑定
3. 启停状态
4. 发布版本
5. 回滚与审计记录

因此：

1. specialist 可以以 md + json 作为包定义格式
2. 但在线编辑后的结果不应直接回写 backend-go/internal/specialists/packages/...
3. 运行时应以数据库中的已发布版本为准

7. Connector 规范

7.1 Connector 的工程定义

connector 的本质是“连接包 / 适配器包”。

它回答的是：

1. 连谁
2. 怎么鉴权
3. 能查什么对象
4. 能执行什么动作
5. 健康状态怎么判断

在三类对象里，connector 最适合做成真正的可插拔插件包。

7.2 推荐目录结构

后端

backend-go/internal/connectors/
  core/
    contracts.go
    registry.go
    auth_contract.go
    query_contract.go
    webhook_contract.go
    health_contract.go
    uninstall.go
  packages/
    kingdee/
      manifest.go
      adapter.go
      auth.go
      health.go
      webhook.go
      dto/
      schema/
      tests/
    feishu_bitable/
      manifest.go
      adapter.go
      auth.go
      health.go
      webhook.go
      dto/
      schema/
      tests/

前端

frontend/src/connectors/
  core/
    contracts.js
    registry.js
    uninstall.js
  packages/
    kingdee/
      manifest.js
      settings.js
      health.js
      assets/
    feishu-bitable/
      manifest.js
      settings.js
      health.js
      assets/

7.3 Connector manifest 必须拥有的内容

每个 connector manifest 至少应声明：

1. key
2. label
3. direction
4. auth_kind
5. supported_objects
6. query_provider
7. webhook_provider
8. health_provider
9. owned_secret_keys
10. owned_tables
11. owned_job_keys
12. owned_storage_keys
13. owned_definition_keys
14. owned_catalog_entries
15. shared_reference_policy

7.4 Connector registry 的职责

connector registry 只负责：

1. 注册 connector manifest
2. 按 key 路由到 provider
3. 安装 connector 目录项
4. 枚举 connector 健康和能力
5. 卸载 connector 自有资源

connector registry 不负责：

1. 平台级业务调度
2. 平台统计拼装
3. 平台任务决策

7.5 Connector 的资源归属

connector 应 own：

1. adapter
2. auth
3. query
4. webhook
5. health check
6. secret key 命名空间
7. own tables
8. own jobs
9. own localStorage key

connector 不应再把这些能力散在平台通用文件中。

7.6 Connector 的命名空间建议

connector 的命名空间建议如下：

1. 表：connector_<connector_key>_*
2. secret key：connector.<connector_key>.*
3. job key：connector.<connector_key>.*
4. storage key：connector:<connector_key>:*
5. provider key：connector.<connector_key>.*

7.7 Connector 的删除标准

一个 connector 只有满足以下条件，才算达到“整包可删除”：

1. 删除 frontend/src/connectors/packages/<connector>/
2. 删除 backend-go/internal/connectors/packages/<connector>/
3. 删除 registry 注册项
4. 平台 runtime 不再 switch key
5. 平台控制台 / 统计页只消费 provider 输出
6. secret / webhook / job / health 状态都在该 connector 命名空间下
7. 平台构建通过

7.8 当前仓库的主要问题

当前仓库中，connector 仍存在以下硬耦合：

1. connector registry 仍是平台硬编码 map
2. runtime 仍直接 import connector 根包并调用具体能力
3. 前端还没有 connector manifest / registry 分层

因此 connector 虽然最接近插件化，但仍未达到目录级安全删除标准。

7.9 关于集中式 connector catalog 的判定

类似下面这种结构：

1. 一个公共文件里集中维护多个 connector 的 definition
2. 在同一个 catalog 中继续扩张多个 connector 的能力、对象、动作
3. 平台 runtime 直接依赖这个 catalog 来判断 connector 行为

它也不算完成封装。

这种文件最多只能算：

1. 迁移期注册表
2. 迁移期兼容目录
3. 过渡期桥接实现

但它不是最终形态。

connector 的最终形态必须是：

1. 一个 connector 一个目录
2. 每个 connector 自己拥有 adapter / auth / health / webhook / manifest
3. 平台只通过 registry 和 contracts 认识它

7.10 Connector 在对象治理区的编辑模型

connector 同样应纳入一级导航三治理，但它的在线编辑边界要更谨慎。

包目录中适合保留：

1. manifest
2. 默认 settings 元数据
3. 健康检查元数据
4. 能力声明

运行时持久化层适合保存：

1. connector 启停状态
2. 租户级配置
3. 凭据引用
4. 健康状态快照
5. 发布版本与审计记录

特别说明：

1. connector 的在线治理通常只改配置和启停
2. 不应允许在导航三中直接改 adapter 源码实现
3. 凭据应进入独立 secret 存储，不应直接裸写进包定义文件

8. 三类对象的拥有边界

为了避免过度工程化，三类对象的拥有边界必须明确区分。

8.1 Skill owns

1. executor
2. schema
3. result card
4. composer block
5. capability provider

8.2 Specialist owns

1. prompt
2. bindings
3. interaction card
4. default strategy
5. default task skeleton

8.3 Connector owns

1. adapter
2. auth
3. health
4. webhook
5. query
6. secrets
7. jobs
8. own tables

因此：

1. skill 是“做什么”
2. specialist 是“以谁的方式做”
3. connector 是“连谁、取谁、写谁”

9. 合同接口建议

9.1 Skill manifest

SkillManifest
  Key()
  Meta()
  Install()
  RegisterProviders()
  OwnedTables()
  OwnedStorageKeys()
  OwnedDefinitionKeys()
  OwnedCatalogEntries()
  SharedReferencePolicy()

9.2 Specialist manifest

SpecialistManifest
  Key()
  Meta()
  PromptProvider()
  BindingProvider()
  RegisterSeeds()
  OwnedStorageKeys()
  OwnedDefinitionKeys()
  OwnedCatalogEntries()
  SharedReferencePolicy()

9.3 Connector manifest

ConnectorManifest
  Key()
  Meta()
  RegisterQueryProvider()
  RegisterWebhookProvider()
  RegisterHealthProvider()
  RegisterMigrations()
  OwnedTables()
  OwnedSecretKeys()
  OwnedJobKeys()
  OwnedStorageKeys()
  OwnedDefinitionKeys()
  OwnedCatalogEntries()
  SharedReferencePolicy()

10. 卸载协议

三类对象都必须支持卸载协议，但清理维度不同。

10.1 Skill uninstall

至少应支持：

1. 清理 owned storage key
2. 清理 owned table
3. 清理 provider 注册
4. 清理 definition key / catalog entry
5. 报告 shared reference 的阻塞或降级结果

10.2 Specialist uninstall

至少应支持：

1. 清理 owned storage key
2. 清理 seed 注册
3. 移除 prompt / binding provider
4. 对历史任务 key 做 fallback，而不是报错
5. 清理 definition key / catalog entry
6. 对历史发布版本和任务引用执行 tombstone / readonly 策略

10.3 Connector uninstall

至少应支持：

1. 清理 owned storage key
2. 清理 owned table
3. 清理 secret key
4. 清理 webhook 配置
5. 清理 job key
6. 清理 provider 注册
7. 清理 definition key / catalog entry
8. 对共享引用执行 block / detach / tombstone 策略

10.4 卸载的统一 dry-run 输出要求

三类对象的卸载都应支持统一的 dry_run 输出，至少包括：

1. 将被清理的 owned resource
2. 将被清理的定义条目
3. 将被阻塞的共享引用
4. 将被降级为 tombstone / readonly 的历史引用

11. 迁移顺序

推荐按以下顺序实施，避免边搬边炸：

1. 先建立 skills / specialists / connectors 的 core/contracts
2. 建立三类对象各自的 registry
3. 先把平台层硬编码改为 registry 消费
4. 再把默认定义迁成 manifest 注册
5. 再搬迁对象包目录
6. 最后补卸载脚本和 owned resource 清理

这个顺序的核心原因是：

1. 先修正依赖方向
2. 再修正代码落点
3. 最后修正资源所有权

12. 判定红线

如果一个 skill / specialist / connector 还存在以下任意一条，则不算完成封装：

1. 总路由中仍手写它的内部业务路径
2. 总导航中仍手写它的对象级菜单
3. 平台配置文件仍硬编码它的完整定义
4. 平台总 seed 仍直接创建它
5. 别的模块还能直接 import 它内部包
6. 统计、控制台、工作台仍直接读取它的内部实现细节
7. 该对象自己的存储 key / 表 / job / secret 没有进入 own 命名空间
8. 一个公共定义文件里仍集中维护多个对象的完整定义
9. 对象定义记录、目录条目、seed 默认定义没有进入 own boundary
10. 共享引用没有明确降级策略
11. 缺少 dry_run、资源审计或 CI guard

12.1 集中式定义文件的红线说明

以下文件形态，不管名字叫什么，只要内容本质相同，都应视为未完成封装：

1. 多 specialist 的集中式规则定义文件
2. 多 skill 的集中式静态定义文件
3. 多 connector 的集中式 catalog 定义文件

判断标准取决于它是否同时满足：

1. 承载多个对象
2. 承载对象完整定义，而不只是注册引用
3. 删除单个对象时仍需进入该文件手工删业务细节

只要满足这三条，就说明它仍属于“定义中心”，尚未收敛到“注册中心”。

12.2 Enforcement / Guard 的最低要求

若三类对象要长期保持可删除封装，平台至少应实现：

1. import boundary lint
2. registry completeness check
3. owned definition audit
4. shared reference dry-run report
5. CI fail 条件

13. 验收清单

三类对象只有满足以下条件，才算达到“整包可删除”：

1. 删除对象目录
2. 删除 registry 注册项
3. 前后端构建通过
4. 平台层没有 import 残留
5. 卸载脚本只清理该对象 own 的资源
6. 平台只是少一个能力，不发生整体失败
7. 对象定义记录、目录条目、seed 默认定义不会残留死入口
8. dry_run 能准确报告 shared reference 的阻塞、解绑与 tombstone 结果

14. 最终标准

三类对象的最终定义应为：

1. 一个可注册的对象包
2. 一个有 manifest 的对象
3. 一个只通过 contract 暴露能力的模块
4. 一个可以通过“删目录 + 删注册 + 跑卸载”安全移除的工程单元

但三类对象的最终形态不同：

1. skill 是能力包
2. specialist 是策略定义包
3. connector 是连接插件包

只有先承认这种边界差异，所谓“可删除封装”才不会走向两种错误：

1. 该做彻底的地方没有做彻底
2. 不该做成子系统的对象被硬做成子系统