feat(hub): external capability registry for PDF/ASR transforms (ADR-0027)

Introduces the External Capability abstraction: platform-registered,
org-enabled document/media transform services invoked as side effects of
an AgentRun. The first concrete capability is pdf_to_md_bundle backed by
MinerU. This lands the contract, schema, adapter interface, and a fully
mock-tested adapter; the real MinerU HTTP client is deferred until
credentials and pricing are confirmed.

Contract:
- spec/Spec/System/Agent/Capability.lean pins ExternalCapability,
  OrganizationCapabilityConnection (reuses ADR-0024 envelope, distinct
  from model-provider connection), and CapabilityInvocation.Authorized
  (workspace containment predicate, ADR-0018). lake build green (41 jobs).
- ADR-0027 records why capability credentials are a separate connection
  type (MinerU/Whisper have their own auth shape, not OpenRouter /v1/models),
  the adapter seam, and what is deferred (capability invocation record,
  pricebook, agent-facing tool discovery).

Schema:
- OrganizationCapabilityConnection + CapabilityCredentialVersion, mirroring
  the Feishu Application Connection shape. Unique by (organizationId,
  capabilityId). Migration 20260718130000 applied.

Adapter (hub/src/capability):
- types.ts: CapabilityId, CapabilityAdapter interface, secret payload,
  CapabilityConnectionUnavailable.
- mineruClient.ts: MineruClient interface + MineruParseResult + errors.
  Real HTTP client deferred; the interface is the seam.
- capabilityConnections.ts: resolveCapabilityCredential — org-scoped,
  fail-closed, reuses LocalSecretEnvelope with purpose="capability".
- pdfToMdBundle.ts: adapter that resolves credential, confines input/output
  to the run workspace (ADR-0018), calls MineruClient, writes md + images
  into workspace, and writes a UsageFact (kind=external_capability,
  quantity=pages, costSource=provider_reported|unknown per ADR-0022).

Tests (7, all green):
- md + images written to workspace, UsageFact attributes pages + cost
- costUsd null -> costSource=unknown (missing cost != zero, ADR-0022)
- no ACTIVE connection -> fail-closed, no fact written
- input/output path escape -> CapabilityPathEscape
- MinerU client error propagates, no fact written
- empty markdown -> parse failure

Deferred (needs operator): MinerU account/API key/pricing, real MineruClient
HTTP implementation, org admin UI for capability connection management,
agent-facing tool exposure (MCP vs built-in).
This commit is contained in:
2026-07-18 15:54:00 +08:00
parent aaa098bb8b
commit 8df8156969
10 changed files with 1057 additions and 1 deletions
+5 -1
View File
@@ -11,6 +11,7 @@ import Spec.System.Agent.AgentRole
import Spec.System.Agent.Memory
import Spec.System.Agent.AgentSurface
import Spec.System.Agent.Usage
import Spec.System.Agent.Capability
import Spec.System.Lock
import Spec.System.Permission
import Spec.System.PermissionGrant
@@ -43,11 +44,14 @@ likec4 已画出结构;这里补语义:
- `Usage` —— Run 内 append-only 用量计量事实账本(ADR-0026);主模型 completion、
外部能力调用、代理网关旁路共用同一账本。fact 不持锁、不跨 run;`costUsd = none`
表示未知而非零(ADR-0022)。Run 上的 cost/token 标量是其 rollup cache。
- `Capability` —— 外部能力(PDF→MD、音视频→文本等)注册与调用(ADR-0027);
org-scoped 凭证连接复用 ADR-0024 信封但独立于 model-provider;调用是 Run 内副作用,
产物落 workspace,消耗记 UsageFact。capability credential 不进 Agent 进程。
- `Permission` —— read⊂edit⊂manage 角色体系、能力推导、单调性;force-release 在格外。
- `PermissionGrant` —— grant(resource×principal×role)与 settings(六 policy 旋钮)
(ADR-0004);组合规则 OPEN。
- `Audit` —— customer Project/Run 审计从简(内容 OPEN);Platform Audit 由
`PlatformAdministration` 独立承载。
标识符见 `Spec.Prelude`。决策出处:ADR-0001..0004, 0018, 0020..0026
标识符见 `Spec.Prelude`。决策出处:ADR-0001..0004, 0018, 0020..0027
-/