#包模型

A3S 认知包是一种类似 npm package 的版本化分发单元。它可以只包含原生能力、只包含声明式认知内容，或同时包含两者，也可以通过 package ID 与 SemVer 范围依赖其他认知包。所有表面共享一个签名身份、一个代际和一个卸载边界。

A3S package
├── native plane       executable · runtime assets · target · provenance
└── cognitive plane    Tool · MCP · OKF · Flow · Skill · UI · agent context

典型 schema-v3 包结构如下：

acme-research/
├── a3s-use-extension.acl   身份 · 版本 · 依赖 · 表面
├── README.md               必需的包说明
├── tools/                  原生 Task 或 Service 产物
├── releases/               内容绑定的 Tool/MCP descriptor
├── flows/                  A3S Flow TypeScript 源码
├── skills/                 SKILL.md 与支持内容
├── ui/                     完整性绑定的静态资产
└── okf/                    合规知识 bundle

只有 manifest 与 README.md 文件名固定；贡献路径由 manifest 声明。

#schema-v3 表面

这里的 Tool 不是 MCP tools/list item。Tool 保留它自己的 CLI 或 HTTP 合约；Use 不将所有工作负载翻译为私有通用协议。静态 UI 也不是 Runtime 工作负载，只有它声明的 Tool 或 MCP 后端进入 Runtime。

Tool、MCP、OKF、Flow、Skill、UI 共用 schema-v3 包基线。当前图生命周期已实现有界 SemVer 解析、精确 Registry/TUF lock、依赖前向准备、共享依赖保留、一次持久切换、反向退休、精确 generation 排空和崩溃重放。Flow 只使用 a3s-flow 引擎，并把 Native TypeScript 源码证据绑定到显式 Tool/MCP/OKF 边。A3S Code 已组合本地 Tool Task、stdio MCP、Flow preflight、Skill 与 UI adapter；standalone OKF 使用 scope-isolated SQLite/FTS5 后端、精确 promoted projection 和带引用搜索。生产 Runtime Service、HTTP MCP/Gateway、托管 Knowledge/UI 组合、分布式 Flow 与完整跨平台宿主验收仍是发布阻塞项；宿主证据缺失时不会发布表面。

OKF 不是可执行 workload。它是一个可共享知识包：每个非保留概念是带 YAML frontmatter 的 UTF-8 Markdown，文件路径是概念身份，标准 Markdown links 形成知识图，type 是必需字段。A3S Use 只接受 OKF v0.2，不提供旧格式 fallback。原始 PDF、Office、图片或网页不直接作为 OKF 权威内容；独立 compiler 必须先生成合规 bundle。

#ACL manifest

包使用 a3s-use-extension.acl，由 A3S ACL 解析。ACL 是 A3S Agent Configuration Language，不是 HCL。

extension "acme/research" {
  schema_version = 3
  version        = "2.0.0"
  route          = "research"
  requires_use   = ">=0.3.0, <0.4.0"
  actions        = ["read", "execute"]

  dependency "acme/base" {
    version = "^1.4.0"
  }

  dependency "acme/vector-store" {
    version = ">=2.1.0, <3.0.0"
  }

  repository {
    url      = "https://github.com/acme/research"
    revision = "0123456789abcdef0123456789abcdef01234567"
  }

  tool "convert" {
    workload    = "task"
    interface   = "cli"
    executable  = "tools/convert/bin/convert"
    command     = "acme-research-convert"
    json_output = true
    interactive = false
    timeout_ms  = 120000
    activation  = "lazy"
    optional    = false
  }

  mcp "library" {
    transport  = "streamable-http"
    release    = "releases/library-mcp-v1.json"
    activation = "eager"
    optional   = false
  }

  okf "domain-knowledge" {
    format_version         = "0.2"
    root                   = "okf/domain-knowledge"
    content_digest         = "sha256:bd85b0b63adb32bdf616384a619286af4c32401542655dd09e00450902ab478d"
    concept_count          = 4
    file_count             = 7
    expanded_bytes         = 2053
    max_files              = 256
    max_concepts           = 64
    max_expanded_bytes     = 67108864
    max_document_bytes     = 1048576
    max_links_per_document = 2048
    optional               = false
  }

  flow "review" {
    engine         = "a3s-flow"
    runtime        = "native-ts"
    source         = "flows/review.ts"
    export         = "run"
    requires_tool  = ["convert"]
    requires_mcp   = ["library"]
    requires_okf   = ["domain-knowledge"]
    optional       = false
  }

  skill "review" {
    path          = "skills/review/SKILL.md"
    requires_tool = ["convert"]
    requires_mcp  = ["library"]
    requires_okf  = ["domain-knowledge"]
    requires_flow = ["review"]
    optional      = false
  }

  ui "review" {
    entry    = "ui/review/index.html"
    skill    = "review"
    bind_mcp = ["library"]
    bind_flow = ["review"]
    optional = false
  }
}

当前只接受 schema v3。它定义可重复命名表面、包依赖、必需且有大小限制的 UTF-8 README.md，以及无环 readiness graph。过时的预览 manifest 和 receipt 会被拒绝，并提示清理后重新安装。所有路径都相对包根目录；激活前会拒绝路径穿越、链接、归档歧义、超限包、provenance 漂移和宿主版本不兼容。可选 route 只是人类可读别名：允许重复，显式解析遇到歧义时会 fail closed。

仓库包含可执行 plugin-v3.acl、知识 plugin-v3-okf.acl，以及包含六类表面的 plugin-v3-cognitive fixture。

#包依赖与精确 lock

dependency block 只能包含 canonical package ID 与 canonical SemVer requirement。包不能选择下载 URL、Registry、trust root、channel、target 或 mutable tag。宿主从已启用的具名 Registry 中解析完整传递闭包；缺少版本、约束冲突、循环、超过解析上限，或同一依赖身份出现在多个 Registry 时都会 fail closed。

Canonical a3s.use.plugin-package-lock.v1 会冻结每个选定版本与依赖边、archive/package/manifest digest、宿主 target 与 Use version、Registry name/URL、channel/target、TUF root 身份与 TUF role version。Operation plan 绑定 lock digest；apply 在下载第一个 archive 前重新验证完整 lock。

解析签名 catalog → 冻结精确 lock → 重验全部 metadata
  → 前向下载/安装依赖 → 验证 retained generation
  → 一次发布变更包 → 反向移除不再需要的包

共享依赖不会被重复提交。只有精确的 Registry-backed generation 已安装、启用并出现在当前 capability snapshot 中时，Retain node 才可复用。其他已安装包仍依赖目标时，直接卸载会被拒绝。

公开的 CognitivePackageManager 接受一个 root Registry 和一组有界的 host-injected dependency Registry。它持久化精确 root lock 以及已经准入的 pending manifest/generation evidence，因此 published install 可以补齐未完成 journal，reverse uninstall 也能在 root metadata 已移除后继续。产品宿主通过 CognitivePackageLifecycleFactory 注入 surface owner；standalone factory 不会替换缺失的 Runtime、Gateway、A3S Flow 或 Knowledge provider。

#表面依赖与 readiness

表面不是独立安装的。Surface Reconciler 对一个包代际构建完整依赖闭包：

1. Tool/MCP 必须有满足 workload、网络、资源和隔离要求的显式 Runtime provider。
2. OKF 表面必须通过 frontmatter、路径、链接、大小和内容摘要检查；A3S Knowledge 只能索引宿主原子提升的 generation。
3. Flow 源码必须匹配摘要、通过类型化 a3s-flow preflight，并等待所有 required Tool/MCP/OKF 依赖。
4. Skill 内容摘要必须匹配，并且所有 required Flow 或直接依赖已可用。
5. UI 内容必须完整，并且所有声明的后端 binding 已授权。
6. 所有 required 表面就绪后，才原子发布一个 capability generation；optional 失败可形成 degraded，required 失败则不发布新代际。

#身份与所有权

• package ID：稳定生命周期身份，例如 acme/research。
• generation：一次不可变安装内容；升级产生新 generation。
• route：可选展示/CLI 别名，允许重复且绝不拥有包。
• receipt：记录该 generation 拥有的文件、投影与资源。
• grant：将主体、scope、权限和精确 generation 绑定。

卸载只删除 receipt-owned 内容。默认保留插件数据；永久清除必须是独立、显式且仅用户可执行的操作。