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 执行。

分类规则

可以正式发布

满足发布准入，且插件/agent/skill 有复用价值的底座业务能力，例如 media、knowledge、workflow、scheduler、event fabric、agent runtime、AI 模型调用等。

优先使用手写业务聚合能力，而不是每个 raw route 一个 capability。聚合能力可以包含多个 REST/gRPC protocol binding。

可登记但 agent 不可选

后台治理、观测、诊断、插件运行时辅助接口，如果确实需要被租户或插件调用，可以登记，但必须：

• agent_usable: false
• 权限码、风险等级和文档明确。
• UI 不把它当成 agent 能力选购项。

已被聚合能力覆盖

如果 raw route 已经被手写聚合能力覆盖，不要再发布重复 capability。应把 raw route 覆盖关系体现在聚合能力的 protocols 中，或在审计 ignore 中说明“covered_by: <capability_id>”。

不应发布

以下类型不得进入租户能力注册目录：

• /internal/** 或 /api/v1/internal/**
• /api/v1/admin/root/**
• migration/fix/bootstrap/debug/test-only 路由
• public signup/auth/icon 等公共入口
• plugin drain、tenant instance enable/disable、registry sync、安装任务等运维控制接口
• runtime task-queue、ws-bus grant/publish 等底层运行时控制接口，除非已经被明确设计为插件运行时合同并标记非 agent 可选
• _test.go 中的测试路由
• capability_gen 误解析出来的假路径

这些需要进入 capability_audit_ignore.yaml 时，每条必须有 category 和 reason，不能静默忽略。

这些类型即使被 OpenAPI/Gin/gRPC 生成器识别为候选，也不得通过服务态 STS direct 自动开放；如果确实属于插件服务运行时合同，应从 capability 发布判断中剥离，进入静态合同入口并单独测试。用户态后台页面访问 /api/v1/admin/* 不受这条 STS blocklist 影响，仍由用户 JWT 和 RBAC 判定。

缺实现

如果只有 required_capabilities、插件调用方或文档提到某 capability，但底座没有真实 transport，不得补 YAML 伪造能力。必须先实现 API/service/repository/transport/权限/测试，然后再登记 capability。

典型判断：com.corex.customer.accounts.* 如果没有真实 customer admin HTTP/gRPC transport，就属于缺实现，不能仅靠 capability YAML 解决。

生成器与审计器规则

发现以下情况时先修工具，不要发布候选：

• Gin group 解析丢父路径，例如 group := adminGroup.Group("") 后路由被生成到 /api/v1/catalog 而不是 /api/v1/admin/skills/catalog。
• 扫描 _test.go 产生候选。
• 生成路径缺 /admin、/tenant、/internal 等实际前缀。
• OpenAPI、gRPC、Gin 对同一路由生成重复或冲突 capability ID。
• permission_code、agent_usable、risk_level 缺省导致 UI 或授权过宽。

修工具后重新运行 make capability-check，用新结果重新分类。

审计器必须强制：

• 正式 YAML 中每个 capability 必须有 permission_code。
• 正式 YAML 中每个 capability 必须显式设置 agent_usable。
• 正式 YAML 中每个 capability 必须有合法 risk_level：low、medium、high、critical。
• 正式 YAML 中每个 REST binding 必须有 actor_context 和 resource_scope。
• sts_direct: true 只能用于 actor_context: service_actor。
• sts_direct: true 不得指向 /api/v1/admin/*。
• generated.auto.yaml 也必须满足上述元数据规则。

完整补齐后应能同时满足：

• backend/config/platform_capabilities/generated.auto.yaml 中有 700+ raw 能力。
• 手写聚合能力 YAML 中有业务语义稳定的高层能力。
• make capability-check 通过。
• BaseCapabilitySeeder 读取正式目录后会登记 raw 能力与手写聚合能力。

输出格式

给用户结论时按这个顺序：

1. 当前事实：正式能力数、候选能力数、差异数、命令结果。
2. 可以发布：列模块、代表能力、原因、需要写入哪个 YAML。
3. 不发布：列分类、代表路径、原因、是否进入 ignore。
4. 聚合覆盖：列 raw route 和覆盖它的聚合 capability。
5. 缺实现：列 capability_id、缺哪个 transport/service/permission/test。
6. 工具问题：列 capability_gen/audit/check 需要修的点。
7. STS direct 影响：列自动开放数量、被 blocklist 拦截的代表路径、是否需要静态合同入口。
8. 下一步改动：代码、配置、文档、验证命令。

不要只回答“可以”或“不可以”。必须说明运行时影响和授权边界。

修改约束

• 不做兼容 fallback；错误格式或缺字段要 fail fast。
• 不把草稿 YAML 直接搬进正式目录。
• 不把 root/internal/debug/migration/test 路由发布为租户能力。
• 不通过手工改 STS validator 代替正式 capability 登记；普通开放 REST 能力必须从 platform capability 自动派生。
• 不用 UUID 或 raw technical ID 做用户主展示文本。
• 业务对象关联使用 UUID；中间表可以没有 UUID，但外键映射业务对象 UUID。
• 后端启动和 migrate 分离，不把 AutoMigrate 当成运行时启动副作用。
• 新增用户可见文案必须走 i18n/locale。
• 插件 capability 的 default_role_grants 只能使用 role_owner、role_admin、role_user、role_readonly、role_vendor；非法角色码必须 fail fast。

验证

完成治理或代码修改后至少运行：

make capability-check

如果改了 Go 代码，按影响范围运行对应测试；如果新增/修改生成器或审计器，至少运行：

cd backend && go test ./cmd/capability_audit
cd backend && go test ./cmd/capability_gen

如果改了 STS direct 规则或 platform capability REST endpoints，还要运行：

cd backend && go test ./internal/http

如果对应包没有测试，也要明确说明无法运行或当前没有测试包。