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 源文件。