Capability Governance

PowerX Capability Governance

目标

按统一规则判断 PowerX 底座能力候选是否可以进入 backend/config/platform_capabilities/*.yaml，并区分：

• 可发布为租户能力目录中的正式能力。
• 可登记但不能作为 agent 可选能力。
• 已由手写业务聚合能力覆盖，不应重复发布 raw route。
• 不应发布，只能进入带原因的 ignore。
• 缺真实实现，不能靠 YAML 声明补齐。
• 生成器或审计器误判，需要修工具。

正式 YAML 不是文档。进入 backend/config/platform_capabilities 后会被 BaseCapabilitySeeder 写入 CapabilityRecord 并给 active tenants 建 registration，因此必须按运行时授权事实处理。

使用方式

在对话里直接点名 skill。完整审计使用：

用 $capability-governance 做一次完整能力治理审计

完整补齐使用：

用 $capability-governance 做一次完整能力治理补齐

执行“完整能力治理补齐”时，不只解释结果，必须按下面顺序实际处理：

1. 读取本 skill 的“必读文件”。
2. 运行 make capability-gen，确保 backend/config/platform_capabilities/generated.auto.yaml 被重新生成。
3. 检查 generated.auto.yaml 是否作为正式 platform capability 文件存在，并包含所有生成能力的治理字段：
   • permission_code
   • agent_usable
   • risk_level
   • REST binding 的 actor_context
   • REST binding 的 resource_scope
   • sts_direct 只能显式为 true，不得默认打开
4. 检查手写聚合能力 YAML 是否同样具备 permission_code / agent_usable / risk_level。
5. 如果审计插件 capability descriptor，检查面向普通成员的能力是否显式声明 default_role_grants: [role_user]，并确认未使用非法默认角色码。
6. 运行 make capability-check。如果失败，先判断是：
   • 缺真实 transport/service：先补实现，再补 YAML。
   • capability_gen/audit 误判：先修工具，例如 Gin Group("") 丢父路径。
   • 正式能力缺元数据：补 YAML 或生成器。
   • 路由不应发布：写入带 category/reason 的 ignore，不允许静默忽略。
7. 修完后重新运行 make capability-gen 和 make capability-check，直到通过。
8. 需要验证运行时 Registry 时，运行 make capability-seed，把正式 platform_capabilities/*.yaml 写入 capability_registry_records 并为 active tenants 补齐 registrations。
9. 如果改了 Go 工具或 STS 规则，运行对应 Go 测试。

也可以按问题缩小范围：

用 $capability-governance 检查 make capability-check 的失败原因
用 $capability-governance 判断这些候选能力哪些可以进 platform_capabilities
用 $capability-governance 分析 com.corex.customer.accounts.* 需要补哪些实现

必读文件

先读取这些位置，再给结论或改代码：

• make_files/capability.mk
• make_files/dev.mk
• backend/cmd/capability_gen/main.go
• backend/cmd/capability_audit/main.go
• backend/config/platform_capabilities/*.yaml
• backend/config/capability_audit_required.yaml
• backend/internal/service/integration_gateway/base_capabilities.go
• backend/internal/service/integration_gateway/platform_capability_config.go
• backend/internal/http/auth_subject_validator.go
• backend/internal/http/auth_subject_validator_test.go
• 相关 HTTP/gRPC/OpenAPI transport 源文件。

如果涉及 agent 能力授权，还要读取：

• backend/internal/service/agent_authz/service.go
• backend/internal/service/agent/agent_service.go
• web-admin/app/pages/settings/ai/agents.vue

基础命令

从仓库根目录运行：

make capability-gen
make capability-audit
make capability-check
make capability-seed
CAPABILITY_AUDIT_FIX=1 make capability-audit

解释命令结果时必须区分：

• capability-gen：从 OpenAPI/gRPC/Gin 生成底座 raw 能力，默认写入 backend/config/platform_capabilities/generated.auto.yaml。该文件是正式登记的一部分，但生成能力默认必须是 agent_usable: false，不能当成手写业务聚合能力。
• capability-audit：检查正式目录、required 清单和路由覆盖。
• capability-check：先临时生成候选，再审计正式目录覆盖关系，适合判断“现有接口是否已被正式声明或明确忽略”。
• capability-seed：只同步正式 platform capability YAML 到运行库，不执行 migrate，不执行全量 seed。
• CAPABILITY_AUDIT_FIX=1：只生成草稿，不得直接把草稿视为可发布。

当前 Make 约定：

• make capability-gen 默认输出：backend/config/platform_capabilities/generated.auto.yaml
• make capability-check 临时输出：tmp/capability-check/generated.platform-capabilities.yaml
• make capability-check 通过时应输出类似：

capability-audit: ok, declared=<正式能力数> referenced=<引用数> rest_routes=<REST覆盖数> candidates=<临时候选数> ignored_route_rules=<忽略规则数>

如果 declared 只有几十个，而 candidates 有几百个，说明 raw 能力没有完整进入正式目录，不能视为完整。

发布准入

能力进入正式 platform_capabilities 前必须满足：

• 有真实 HTTP/gRPC/OpenAPI transport，不能只有 model、migration、文档或调用方引用。
• 有稳定业务语义，不是临时调试、安装、迁移、root 支持或内部运维入口。
• capability_id 稳定且属于 com.corex.*。
• permission_code 明确，不能依赖不可读的粗粒度推导。
• agent_usable 明确设置。raw route 和后台管理能力默认应为 false。
• risk_level 明确设置。
• 插件 capability 同步 IAM permission 后，Core 默认授予 role_owner 和 role_admin；如需普通成员使用，descriptor 必须显式声明 default_role_grants: [role_user]，不得靠手工补 iam_role_permission。
• module、categories、intents、tool_scopes 与业务语义一致。
• protocols 指向真实路径/RPC，路径参数风格要与项目规范一致。
• 用户可见标题和描述要支持 locale/i18n 元数据；技术 ID 不能作为主要展示文本。
• 需要插件或 agent 通过 STS/API key 调用时，STS direct 自动派生、blocklist、tenant registration、permission code、调用路径要一起验证。

generated.auto.yaml 准入

backend/config/platform_capabilities/generated.auto.yaml 是底座 raw 能力登记文件，必须被当作正式目录的一部分读取和审计，但它与手写聚合能力语义不同：

• 必须由 make capability-gen 生成，不手工大段编辑。
• 每条能力必须包含 permission_code、agent_usable、risk_level。
• 生成能力默认 agent_usable: false，避免 raw route 出现在智能体能力选购页面。
• REST protocol 必须包含 actor_context 和 resource_scope。
• REST protocol 不得默认 sts_direct: true。
• 如果 generator 丢路径、丢 /admin、丢 /tenant、错误处理 Group("")，必须先修 generator，而不是手写补假能力。

能力与端点关系

Capability 是业务授权单元，不是 URL。REST/OpenAPI/Admin/gRPC endpoint 只是 capability 的 protocol binding。

规则：

• 同一业务语义、同一授权边界的多个入口 MUST 复用同一个 capability_id。
• /api/v1/admin/<resource> 与 /api/v1/<resource> 如果只是用户态后台入口和服务态开放入口的差异，应登记为同一个 capability 的不同 REST bindings。
• 不得因为路径前缀不同，把同一能力拆成多个 raw route capability。
• 只有当可操作资源范围、actor 约束、风险等级或授权开关必须独立时，才拆 capability。例如 admin 全量治理能力和插件 owner-scoped 自助能力可以拆开。
• 对 scheduler 这类能力，/api/v1/admin/scheduler/jobs、未来的 /api/v1/scheduler/jobs、powerx.scheduler.v1.SchedulerService 如果语义都是 Runtime Scheduler jobs，应优先归到 com.corex.scheduler.jobs；差异通过 binding metadata、service 层 actor/owner 校验和 tool_scope 表达。

Actor 与资源边界

审计 capability 时必须先确认调用主体：

• admin_user：PowerX Admin 或插件 Admin 页面，使用用户 JWT、tenant member、RBAC。典型路径 /api/v1/admin/*。
• service_actor：插件后端、agent、skill、系统集成，使用 STS/API Key/OAuth client。典型路径 /api/v1/tenant/invocations 或服务态开放 REST。
• web_user：租户侧 web 应用用户，使用用户 JWT 或业务 session。
• mini_app_user：小程序用户，使用小程序会话、用户 JWT 或 customer/user token。
• customer_actor：客户门户或外部客户身份，使用 customer token 或 customer-scoped OAuth/API Key。

规则：

• web、mini-app、customer 入口不是后台管理入口，不得复用 admin 全量治理语义。
• customer/mini-app 自助能力默认必须 owner-scoped/self-scoped，例如 com.corex.customer.account.self_read，不能继承 com.corex.customer.accounts.admin_manage。
• 如果同一资源在不同 actor 下资源范围不同，应拆 capability；例如 admin 管理全租户 customer accounts，与 customer 只能查看自己的 account，是两个授权单元。
• 如果 actor 不同但资源范围、操作风险和授权开关完全一致，可以共享 capability，并在 protocol binding metadata 中标明 actor_context。
• capability 命名建议用边界后缀表达语义：admin_manage、service_manage、self_read、self_update、owner_manage。

STS direct 访问规则

插件 STS token 直接访问 PowerX Core HTTP 的允许集合按下面公式计算：

STS direct route policy =
  static plugin runtime contracts
  + REST endpoints in formal platform_capabilities/*.yaml
  - STS blocklist

规则：

• /tenant/invocations 和 /tenant/invocations/stream 是插件调用底座能力的推荐主路径。
• Direct REST 是辅助路径，只能来自正式 platform_capabilities/*.yaml 中的 REST protocol endpoints；generated.auto.yaml 当前也参与自动派生，但必须经过 blocklist。
• 自动开放必须精确到 HTTP method，不允许因同一路径开放 GET 就放开写操作。
• /api/v1/admin/* 是后台用户态 API 命名空间，不等于“禁止插件后台页面使用”。浏览器中的 PowerX Admin、插件 Admin 页面、以及任何携带用户 JWT 的后台请求，仍然按用户鉴权、租户成员、RBAC 和业务权限判断；STS direct route policy 不得影响用户态 JWT。
• STS token 是插件服务态身份，不携带 uid/mid，不能代表登录用户通过 /api/v1/admin/* 绕过用户 RBAC。插件后端如果要代表当前用户调用底座后台 API，必须引入明确的 delegated/on-behalf-of 机制，不能复用普通 powerx:api STS token。
• blocklist 只约束插件服务态 STS direct call，必须拦截 /admin/*、/internal/*、/public/*、/auth/*、/setup/*、debug、migration、root、drain、bootstrap、mock、health、根级动态路径等非服务态开放入口。
• /admin/* 默认不允许服务态 STS direct call。只有确认为插件服务运行时合同的少量入口，才允许进入 static allow，并必须补用途说明和 auth_subject_validator 测试。
• 新增开放接口不得只改 STS validator。正确顺序是：实现真实 transport/service/permission/test，登记正式 platform capability REST protocol，运行 make capability-check，再验证 STS direct policy。
• 后台业务能力如果需要给插件服务态调用，不要把 /api/v1/admin/* 改成 sts_direct: true。应保留 admin_user/user_jwt binding，并新增 service_actor/sts 的 core_internal binding 或服务态开放 REST，由 /tenant/invocations 在校验 Registry 与 tenant registration 后调 Core service。例如 com.corex.customer.accounts.admin_manage 使用 /api/v1/admin/customers/* 作为 payload endpoint 选择参数，但实际由 Core 内部 customer service 执行。