feat(schema): consume Contract declarations in agent-metadata, drop devapp hints
The agent-metadata generator now merges each registered Contract final
overlay (cmdcore.SchemaDecl) as the top-precedence contract_final
candidate, so declared tools no longer need hint-file rows for
agent_summary/use_when/avoid_when/examples/safety/interface. Selection
eval fixtures and example execution plans synthesize the same assertions
from the declaration, keeping semantic-eval and example coverage intact.
- devapp hint rows deleted from schema_hints/{metadata,selection}/dev.json
(connect_status/connect_stop/search_open_platform_docs_rag kept);
artifact content for all 31 declared leaves is byte-identical, only
provenance now reads contract_final / cmdcore.SchemaDecl
- exact-coverage gates exempt declared tools (hints remain required for
every non-declared command); reviewed-delivery gate accepts
contract_final as the stronger reviewed source
- cmdcore derives effect_source=cmdcore.contract for SchemaDecl-only
safety (read leaves), matching the Risk-shorthand path
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
玉澜andCursor committed
1 parent
52324e9bc2
commit
9911d8f9c9
14 files changed
+2651
-4233
No files matched your search
+2125
-3066
File diff suppressed because it is too large.
Load diff
@@ -1,17 +1,17 @@
|
||||
{
|
||||
"version": 1,
|
||||
"source_hash": "sha256:7484b82d1ca793a6129acfaa192ff08fc0864d47a6e75ecd16d8e7fa32857e16",
|
||||
"surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
|
||||
"source_hash": "sha256:91782bf8e515f82b68aad7cd9c910b0c1aa933e06daee1dabbff4cc0369a3ee7",
|
||||
"surface_hash": "sha256:29d4f5f43688cc01bc2277a4528b597de4fbab89a7b2f13fe2e56df85d1c66c4",
|
||||
"coverage": {
|
||||
"surface_products": 26,
|
||||
"products_with_metadata": 26,
|
||||
"surface_tools": 845,
|
||||
"tools_with_metadata": 845,
|
||||
"tools_with_agent_summary": 845,
|
||||
"tools_with_use_when": 845,
|
||||
"tools_with_avoid_when": 845,
|
||||
"tools_with_examples": 845,
|
||||
"tools_with_interface_mode": 845,
|
||||
"surface_tools": 840,
|
||||
"tools_with_metadata": 840,
|
||||
"tools_with_agent_summary": 840,
|
||||
"tools_with_use_when": 840,
|
||||
"tools_with_avoid_when": 840,
|
||||
"tools_with_examples": 840,
|
||||
"tools_with_interface_mode": 840,
|
||||
"unmatched_skill_tools": 122,
|
||||
"unreviewed_skill_tools": 11
|
||||
},
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -20,6 +20,8 @@ import (
|
||||
"fmt"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
var marshalManualAgentSelectionFixture = json.Marshal
|
||||
@@ -71,17 +73,27 @@ func BuildManualAgentSelectionEvalFixture(bound BoundCommandRegistry, hints Manu
|
||||
fixture := ManualAgentSelectionFixture{Version: manualAgentSelectionFixtureVersion}
|
||||
report := ManualAgentSelectionReport{}
|
||||
expectedTools := make(map[string]bool, len(bound.Commands))
|
||||
declaredTools := map[string]bool{}
|
||||
candidatesByProduct := map[string][]string{}
|
||||
for _, command := range bound.Commands {
|
||||
canonical := strings.TrimSpace(command.CanonicalPath)
|
||||
expectedTools[canonical] = true
|
||||
// Declared tools source selection assertions from the Contract final
|
||||
// overlay (cmdcore.SchemaDecl) instead of a hint-file row.
|
||||
if HasRuntimeContractFinal(command.PrimaryCommand) {
|
||||
declaredTools[canonical] = true
|
||||
}
|
||||
productID, _, ok := strings.Cut(canonical, ".")
|
||||
if !ok || strings.TrimSpace(productID) == "" {
|
||||
return fixture, report, fmt.Errorf("agent_hints selection has invalid bound canonical path %q", canonical)
|
||||
}
|
||||
candidatesByProduct[productID] = append(candidatesByProduct[productID], canonical)
|
||||
}
|
||||
if err := validateManualAgentHintExactSet("selection tools", expectedTools, mapKeysManualAgentTools(hints.Tools)); err != nil {
|
||||
hintTools := mapKeysManualAgentTools(hints.Tools)
|
||||
for canonical := range declaredTools {
|
||||
hintTools[canonical] = true
|
||||
}
|
||||
if err := validateManualAgentHintExactSet("selection tools", expectedTools, hintTools); err != nil {
|
||||
return fixture, report, err
|
||||
}
|
||||
for productID := range candidatesByProduct {
|
||||
@@ -105,7 +117,10 @@ func BuildManualAgentSelectionEvalFixture(bound BoundCommandRegistry, hints Manu
|
||||
return fixture, report, err
|
||||
}
|
||||
|
||||
hint := hints.Tools[canonical]
|
||||
hint, hintOK := hints.Tools[canonical]
|
||||
if !hintOK && declaredTools[canonical] {
|
||||
hint = contractFinalSelectionHint(command.PrimaryCommand)
|
||||
}
|
||||
if len(hint.UseWhen) == 0 {
|
||||
return fixture, report, fmt.Errorf("agent_hints tool %s requires at least one positive use_when selection assertion", canonical)
|
||||
}
|
||||
@@ -169,6 +184,23 @@ func ValidateManualAgentSelectionContract(bound BoundCommandRegistry, hints Manu
|
||||
return report, err
|
||||
}
|
||||
|
||||
// contractFinalSelectionHint synthesizes the selection assertions of a
|
||||
// declared tool from its Contract final overlay, so declared tools keep full
|
||||
// semantic-eval coverage without a hint-file row.
|
||||
func contractFinalSelectionHint(command *cobra.Command) ManualAgentToolHint {
|
||||
hint := ManualAgentToolHint{Reviewed: true, Revision: "contract", Reason: "Contract final declaration (cmdcore.SchemaDecl)"}
|
||||
payload, ok := RuntimeContractFinal(command)
|
||||
if !ok || payload.Selection == nil {
|
||||
return hint
|
||||
}
|
||||
selection := payload.Selection
|
||||
hint.AgentSummary = selection.AgentSummary
|
||||
hint.UseWhen = selection.UseWhen
|
||||
hint.AvoidWhen = selection.AvoidWhen
|
||||
hint.Examples = selection.Examples
|
||||
return hint
|
||||
}
|
||||
|
||||
func validateManualAgentSelectionBinding(bound BoundCommandRegistry, canonical string, command BoundCommandSpec) error {
|
||||
if command.CanonicalPath != canonical {
|
||||
return fmt.Errorf("agent_hints selection canonical %q resolves to mismatched BoundCommandRegistry entry %q", canonical, command.CanonicalPath)
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"version": 1,
|
||||
"surface_hash": "sha256:29d4f5f43688cc01bc2277a4528b597de4fbab89a7b2f13fe2e56df85d1c66c4",
|
||||
"source_hash": "sha256:3dcad29c4e7f0653621e9aeaf8a7ad663d1495e7c373e297f9a49a5c918af41e",
|
||||
"source_hash": "sha256:26c7461cde3019fd9ec7378606e59a5725ca78a3d465ac8a865f9f70ecc28c3a",
|
||||
"catalog": {
|
||||
"agent_metadata": {
|
||||
"products_with_metadata": 26,
|
||||
"source": "embedded-skill-metadata",
|
||||
"source_hash": "sha256:eb6e44775a6e85f92ca31c90c876f67543ab928d8a8bda04f07a33dc802f7028",
|
||||
"source_hash": "sha256:91782bf8e515f82b68aad7cd9c910b0c1aa933e06daee1dabbff4cc0369a3ee7",
|
||||
"surface_hash": "sha256:29d4f5f43688cc01bc2277a4528b597de4fbab89a7b2f13fe2e56df85d1c66c4",
|
||||
"surface_products": 26,
|
||||
"surface_tools": 840,
|
||||
|
||||
@@ -6572,6 +6572,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app get --unified-app-id \u003cunifiedAppId\u003e --format json",
|
||||
"dws dev app get --app-key \u003cappKey\u003e --format json"
|
||||
@@ -7193,6 +7194,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app credentials get --unified-app-id \u003cunifiedAppId\u003e --format json"
|
||||
],
|
||||
@@ -7696,6 +7698,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app version get --unified-app-id \u003cunifiedAppId\u003e --version-id \u003cversionId\u003e"
|
||||
],
|
||||
@@ -8314,6 +8317,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app version status --unified-app-id \u003cunifiedAppId\u003e --version-id \u003cversionId\u003e"
|
||||
],
|
||||
@@ -8932,6 +8936,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app robot get --unified-app-id \u003cunifiedAppId\u003e --format json"
|
||||
],
|
||||
@@ -9435,6 +9440,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app webapp get --unified-app-id \u003cunifiedAppId\u003e --format json"
|
||||
],
|
||||
@@ -9938,6 +9944,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app list --name \"DemoApp\" --page-size 20 --format json"
|
||||
],
|
||||
@@ -11496,6 +11503,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app event list --unified-app-id \u003cunifiedAppId\u003e --keyword \"审批\" --page-size 20"
|
||||
],
|
||||
@@ -12297,6 +12305,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app member list --unified-app-id \u003cunifiedAppId\u003e"
|
||||
],
|
||||
@@ -12800,6 +12809,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app permission list --unified-app-id \u003cunifiedAppId\u003e --keyword \"通讯录\" --page-size 20"
|
||||
],
|
||||
@@ -14044,6 +14054,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app version list --unified-app-id \u003cunifiedAppId\u003e --page-size 20"
|
||||
],
|
||||
@@ -15576,6 +15587,7 @@
|
||||
"preview_kind": "invocation"
|
||||
},
|
||||
"effect": "read",
|
||||
"effect_source": "cmdcore.contract",
|
||||
"examples": [
|
||||
"dws dev app robot result --task-id \u003ctaskId\u003e --format json"
|
||||
],
|
||||
|
||||
@@ -8,28 +8,6 @@
|
||||
"reviewed": true
|
||||
},
|
||||
"tools": {
|
||||
"dev.add_dev_app_members": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.apply_dev_app_permissions": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.connect_status": {
|
||||
"interface_mode": "local",
|
||||
"availability": "available",
|
||||
@@ -44,204 +22,6 @@
|
||||
"interface_reason": "命令仅操作本地进程或策略文件，不调用 MCP 接口",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.create_dev_app": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.create_dev_app_version": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.delete_dev_app": {
|
||||
"effect": "destructive",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.disable_dev_app": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.disable_dev_app_robot": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.enable_dev_app": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.enable_dev_app_robot": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.get_dev_app": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.get_dev_app_credentials": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.get_dev_app_version_detail": {
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.get_dev_app_version_status": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.get_extension_robot_config": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.get_extension_webapp_config": {
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.list_dev_app": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.list_dev_app_events": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.list_dev_app_members": {
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.list_dev_app_permissions": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.list_dev_app_versions": {
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.publish_dev_app_version": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.query_robot_create_result": {
|
||||
"effect": "read",
|
||||
"risk": "low",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.remove_dev_app_members": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.remove_dev_app_permissions": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.search_open_platform_docs_rag": {
|
||||
"interface_ref": {
|
||||
"product_id": "devdoc",
|
||||
@@ -250,83 +30,6 @@
|
||||
"interface_mode": "mcp",
|
||||
"availability": "available",
|
||||
"reviewed": true
|
||||
},
|
||||
"dev.set_extension_robot_config": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.set_extension_webapp_config": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.submit_robot_create_task": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.subscribe_dev_app_events": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.unsubscribe_dev_app_events": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.update_dev_app": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
},
|
||||
"dev.update_dev_app_security_config": {
|
||||
"effect": "write",
|
||||
"risk": "high",
|
||||
"confirmation": "user_required",
|
||||
"idempotency": "unknown",
|
||||
"interface_mode": "composite",
|
||||
"availability": "available",
|
||||
"interface_reason": "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command.",
|
||||
"reviewed": true,
|
||||
"runtime_gate": "typed_yes"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -8,46 +8,6 @@
|
||||
"reviewed": true
|
||||
},
|
||||
"tools": {
|
||||
"dev.add_dev_app_members": {
|
||||
"agent_summary": "向应用添加开发者或管理员成员",
|
||||
"use_when": [
|
||||
"需要授予指定用户应用协作角色时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"只查看现有成员时使用 dev app member list"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app member add --unified-app-id <unifiedAppId> --user-ids userId1,userId2 --member-type DEVELOPER --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.add_dev_app_members",
|
||||
"cobra-help:dws dev app member add",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.apply_dev_app_permissions": {
|
||||
"agent_summary": "为应用申请一个或多个接口权限",
|
||||
"use_when": [
|
||||
"已确认 scopeValue 并需要新增权限时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"查找或核对已有权限时使用 dev app permission list"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app permission add --unified-app-id <unifiedAppId> --scope-values Contact.User.mobile --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.apply_dev_app_permissions",
|
||||
"cobra-help:dws dev app permission add",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.connect_status": {
|
||||
"agent_summary": "查看后台连接器守护进程状态",
|
||||
"use_when": [
|
||||
@@ -90,456 +50,6 @@
|
||||
"live-dws-schema:dev.connect_stop#FAILED"
|
||||
]
|
||||
},
|
||||
"dev.create_dev_app": {
|
||||
"agent_summary": "创建钉钉开放平台应用并返回 unifiedAppId/凭证信息",
|
||||
"use_when": [
|
||||
"需要新建企业内部应用或三方个人应用并拿到 unifiedAppId"
|
||||
],
|
||||
"avoid_when": [
|
||||
"应用已存在只需改信息时用 dev app update",
|
||||
"只查文档时用 devdoc"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app create --name \"我的 AI 机器人\" --desc \"接 opencode\" --dry-run --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.create_dev_app",
|
||||
"cobra-help:dws dev app create",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md",
|
||||
"live-dws-schema:dev app create",
|
||||
"helper:devAppRequireWriteGuard"
|
||||
]
|
||||
},
|
||||
"dev.create_dev_app_version": {
|
||||
"agent_summary": "为应用当前配置创建待发布版本",
|
||||
"use_when": [
|
||||
"配置变更完成后需要生成版本进入发布流程时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"只是查看已有版本时使用 dev app version list"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app version create --unified-app-id <unifiedAppId> --desc \"新增机器人能力\" --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.create_dev_app_version",
|
||||
"cobra-help:dws dev app version create",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.delete_dev_app": {
|
||||
"agent_summary": "删除开放平台企业内部应用（不可恢复）",
|
||||
"use_when": [
|
||||
"用户明确要求永久删除应用，且接受不可恢复后果"
|
||||
],
|
||||
"avoid_when": [
|
||||
"只需临时下架时用 dev app disable",
|
||||
"用户未确认应用名/影响范围时不要删除"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app delete --unified-app-id <unified-app-id> --dry-run --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.delete_dev_app",
|
||||
"cobra-help:dws dev app delete",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md",
|
||||
"live-dws-schema:dev app delete",
|
||||
"helper:devAppRequireWriteGuard"
|
||||
]
|
||||
},
|
||||
"dev.disable_dev_app": {
|
||||
"agent_summary": "停用指定开放平台应用",
|
||||
"use_when": [
|
||||
"需要让应用暂时不可用但保留配置时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"永久删除应用使用 dev app delete"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app disable --unified-app-id <unifiedAppId> --dry-run --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.disable_dev_app",
|
||||
"cobra-help:dws dev app disable",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.disable_dev_app_robot": {
|
||||
"agent_summary": "停用指定应用的机器人能力",
|
||||
"use_when": [
|
||||
"需要暂时让应用机器人离线时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"停用整个应用使用 dev app disable"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app robot disable --unified-app-id <unifiedAppId> --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.disable_dev_app_robot",
|
||||
"cobra-help:dws dev app robot disable",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.enable_dev_app": {
|
||||
"agent_summary": "启用指定开放平台应用",
|
||||
"use_when": [
|
||||
"需要恢复一个已停用应用时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"启用应用内机器人能力使用 dev app robot enable"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app enable --unified-app-id <unifiedAppId> --dry-run --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.enable_dev_app",
|
||||
"cobra-help:dws dev app enable",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.enable_dev_app_robot": {
|
||||
"agent_summary": "启用指定应用的机器人能力",
|
||||
"use_when": [
|
||||
"机器人配置存在但处于 OFFLINE 时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"建立本地 Stream 连接使用 dev connect"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app robot enable --unified-app-id <unifiedAppId> --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.enable_dev_app_robot",
|
||||
"cobra-help:dws dev app robot enable",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.get_dev_app": {
|
||||
"agent_summary": "获取指定开放平台应用详情",
|
||||
"use_when": [
|
||||
"已知 unifiedAppId 或 appKey 并需要核对应用配置或状态时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"需要搜索或分页浏览多个应用时使用 dev app list"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app get --unified-app-id <unifiedAppId> --format json",
|
||||
"dws dev app get --app-key <appKey> --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.get_dev_app",
|
||||
"cobra-help:dws dev app get",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.get_dev_app_credentials": {
|
||||
"agent_summary": "读取指定应用的客户端凭证",
|
||||
"use_when": [
|
||||
"已知 unifiedAppId 且需要 clientId 或 clientSecret 时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"不要把凭证内容用于普通应用详情查询或写入日志"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app credentials get --unified-app-id <unifiedAppId> --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.get_dev_app_credentials",
|
||||
"cobra-help:dws dev app credentials get",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.get_dev_app_version_detail": {
|
||||
"agent_summary": "获取指定应用版本的详细内容",
|
||||
"use_when": [
|
||||
"已知 versionId 并需要核对版本配置时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"查看发布进度时使用 dev app version status"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app version get --unified-app-id <unifiedAppId> --version-id <versionId>"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.get_dev_app_version_detail",
|
||||
"cobra-help:dws dev app version get",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.get_dev_app_version_status": {
|
||||
"agent_summary": "查询指定应用版本的发布或审批状态",
|
||||
"use_when": [
|
||||
"需要判断版本是否已发布、审核中或受阻时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"需要版本配置详情时使用 dev app version get"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app version status --unified-app-id <unifiedAppId> --version-id <versionId>"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.get_dev_app_version_status",
|
||||
"cobra-help:dws dev app version status",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.get_extension_robot_config": {
|
||||
"agent_summary": "获取指定应用的机器人配置和状态",
|
||||
"use_when": [
|
||||
"需要判断机器人是否未配置、离线或在线时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"查询机器人建号异步任务使用 dev app robot result"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app robot get --unified-app-id <unifiedAppId> --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.get_extension_robot_config",
|
||||
"cobra-help:dws dev app robot get",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.get_extension_webapp_config": {
|
||||
"agent_summary": "获取指定应用的网页入口配置",
|
||||
"use_when": [
|
||||
"需要核对应用 H5 或 PC 首页地址时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"修改网页入口时使用 dev app webapp config"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app webapp get --unified-app-id <unifiedAppId> --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.get_extension_webapp_config",
|
||||
"cobra-help:dws dev app webapp get",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.list_dev_app": {
|
||||
"agent_summary": "按条件分页查询开放平台应用",
|
||||
"use_when": [
|
||||
"需要按名称、创建人或应用键筛选应用时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"已经持有明确 unifiedAppId 时使用 dev app get"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app list --name \"DemoApp\" --page-size 20 --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.list_dev_app",
|
||||
"cobra-help:dws dev app list",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.list_dev_app_events": {
|
||||
"agent_summary": "列出或搜索应用可订阅的事件",
|
||||
"use_when": [
|
||||
"需要查事件码、事件名称或当前事件列表时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"订阅或退订事件使用对应写命令"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app event list --unified-app-id <unifiedAppId> --keyword \"审批\" --page-size 20"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.list_dev_app_events",
|
||||
"cobra-help:dws dev app event list",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.list_dev_app_members": {
|
||||
"agent_summary": "列出指定应用的协作成员",
|
||||
"use_when": [
|
||||
"需要查看应用开发者和管理员清单时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"新增或移除成员使用对应 member 写命令"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app member list --unified-app-id <unifiedAppId>"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.list_dev_app_members",
|
||||
"cobra-help:dws dev app member list",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.list_dev_app_permissions": {
|
||||
"agent_summary": "查询应用权限及其授权状态",
|
||||
"use_when": [
|
||||
"需要按关键词、范围或状态查权限时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"新增或移除权限使用对应 permission 写命令"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app permission list --unified-app-id <unifiedAppId> --keyword \"通讯录\" --page-size 20"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.list_dev_app_permissions",
|
||||
"cobra-help:dws dev app permission list",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.list_dev_app_versions": {
|
||||
"agent_summary": "分页列出应用的历史和待发布版本",
|
||||
"use_when": [
|
||||
"需要查找 versionId 或浏览版本记录时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"已知版本并需详情或状态时使用 get 或 status"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app version list --unified-app-id <unifiedAppId> --page-size 20"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.list_dev_app_versions",
|
||||
"cobra-help:dws dev app version list",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.publish_dev_app_version": {
|
||||
"agent_summary": "发布开放平台应用指定版本（可先预检）",
|
||||
"use_when": [
|
||||
"版本已创建，需要预检或正式发布到线上"
|
||||
],
|
||||
"avoid_when": [
|
||||
"还没有 versionId 时先 version create / list / get",
|
||||
"含高敏权限但尚未确认时不要正式发布"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app version publish --unified-app-id <unifiedAppId> --version-id <versionId> --dry-run --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.publish_dev_app_version",
|
||||
"cobra-help:dws dev app version publish",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md",
|
||||
"live-dws-schema:dev app version publish",
|
||||
"helper:devAppRequireWriteGuard"
|
||||
]
|
||||
},
|
||||
"dev.query_robot_create_result": {
|
||||
"agent_summary": "查询机器人建号异步任务结果",
|
||||
"use_when": [
|
||||
"已有 taskId，需要轮询 WAITING、SUCCESS 或审批状态时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"没有建号任务时先使用 dev app robot submit"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app robot result --task-id <taskId> --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.query_robot_create_result",
|
||||
"cobra-help:dws dev app robot result",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.remove_dev_app_members": {
|
||||
"agent_summary": "从应用移除开发者或管理员成员",
|
||||
"use_when": [
|
||||
"需要撤销指定用户的应用协作角色时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"删除应用本身或只查看成员时不要使用"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app member remove --unified-app-id <unifiedAppId> --user-ids userId1,userId2 --member-type DEVELOPER --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.remove_dev_app_members",
|
||||
"cobra-help:dws dev app member remove",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.remove_dev_app_permissions": {
|
||||
"agent_summary": "移除应用的一个或多个接口权限",
|
||||
"use_when": [
|
||||
"需要撤销已知 scopeValue 的权限时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"只查看权限状态时使用 dev app permission list"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app permission remove --unified-app-id <unifiedAppId> --scope-values Contact.User.mobile --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.remove_dev_app_permissions",
|
||||
"cobra-help:dws dev app permission remove",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.search_open_platform_docs_rag": {
|
||||
"agent_summary": "通过 dev 兼容入口搜索开放平台文档",
|
||||
"use_when": [
|
||||
@@ -559,148 +69,6 @@
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.set_extension_robot_config": {
|
||||
"agent_summary": "创建或更新应用的机器人能力配置",
|
||||
"use_when": [
|
||||
"已有 unifiedAppId 并需要配置机器人名称、回调或技能时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"机器人建号使用 robot submit，本地建联使用 dev connect"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app robot config --unified-app-id <unifiedAppId> --name \"小助手\" --brief \"审批助手\" --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.set_extension_robot_config",
|
||||
"cobra-help:dws dev app robot config",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.set_extension_webapp_config": {
|
||||
"agent_summary": "创建或更新应用网页入口配置",
|
||||
"use_when": [
|
||||
"需要设置 H5、PC 首页或 OMP 地址时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"只查看当前网页配置时使用 dev app webapp get"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app webapp config --unified-app-id <unifiedAppId> --homepage-url https://example.com --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.set_extension_webapp_config",
|
||||
"cobra-help:dws dev app webapp config",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.submit_robot_create_task": {
|
||||
"agent_summary": "提交机器人建号异步任务",
|
||||
"use_when": [
|
||||
"需要创建新的机器人账号并取得 taskId 时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"已有任务应先用 robot result 轮询，不能重复提交"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app robot submit --name \"我的智能体\" --robot-name \"小助手\" --desc \"处理审批问答\" --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.submit_robot_create_task",
|
||||
"cobra-help:dws dev app robot submit",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.subscribe_dev_app_events": {
|
||||
"agent_summary": "为应用订阅指定事件码",
|
||||
"use_when": [
|
||||
"已确认事件码并需要新增事件订阅时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"查询事件码或已有订阅时先使用 dev app event list"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app event subscribe --unified-app-id <unifiedAppId> --event-codes bpms_task_change --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.subscribe_dev_app_events",
|
||||
"cobra-help:dws dev app event subscribe",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.unsubscribe_dev_app_events": {
|
||||
"agent_summary": "取消应用的指定事件订阅",
|
||||
"use_when": [
|
||||
"需要停止接收一个或多个已订阅事件时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"只是查看事件订阅时使用 dev app event list"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app event unsubscribe --unified-app-id <unifiedAppId> --event-codes bpms_task_change --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.unsubscribe_dev_app_events",
|
||||
"cobra-help:dws dev app event unsubscribe",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
},
|
||||
"dev.update_dev_app": {
|
||||
"agent_summary": "更新开放平台应用名称/描述/图标等基础信息",
|
||||
"use_when": [
|
||||
"已有 unifiedAppId，需要修改应用基础信息"
|
||||
],
|
||||
"avoid_when": [
|
||||
"创建新应用用 create；停用/启用用 disable/enable；改安全配置用 security config"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app update --unified-app-id <unifiedAppId> --name <新名称> --dry-run --format json"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.update_dev_app",
|
||||
"cobra-help:dws dev app update",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md",
|
||||
"live-dws-schema:dev app update",
|
||||
"helper:devAppRequireWriteGuard"
|
||||
]
|
||||
},
|
||||
"dev.update_dev_app_security_config": {
|
||||
"agent_summary": "更新应用 IP 白名单、回调和单点登录地址",
|
||||
"use_when": [
|
||||
"需要调整应用安全相关 URL 或白名单时"
|
||||
],
|
||||
"avoid_when": [
|
||||
"普通应用名称和描述更新使用 dev app update"
|
||||
],
|
||||
"examples": [
|
||||
"dws dev app security config --unified-app-id <unifiedAppId> --ip-whitelist 192.0.2.10 --redirect-urls https://callback.example.invalid/callback --dry-run"
|
||||
],
|
||||
"reviewed": true,
|
||||
"review_reason": "AI 生成并复核的 Agent 选择语义，依据精确 CommandRegistry identity、真实 Cobra help 与产品参考，不改写执行、安全或接口事实。",
|
||||
"source_refs": [
|
||||
"internal/cli/schema_command_registry.json#dev.update_dev_app_security_config",
|
||||
"cobra-help:dws dev app security config",
|
||||
"skills/mono/SKILL.md",
|
||||
"skills/mono/references/products/dev.md"
|
||||
]
|
||||
}
|
||||
},
|
||||
"products": {
|
||||
|
||||
@@ -526,9 +526,24 @@ func buildManualAgentExampleExecutionPlan(bound BoundCommandRegistry, typedTools
|
||||
plan := ManualAgentExampleExecutionPlan{
|
||||
ContractOnlyByReason: map[ManualAgentExampleReasonCode]int{},
|
||||
}
|
||||
canonicalPaths := make([]string, 0, len(hints.Tools))
|
||||
// Declared tools (Contract final overlay) take part without a hint-file
|
||||
// row: their examples come from the in-code declaration.
|
||||
declaredTools := map[string]bool{}
|
||||
for _, command := range bound.Commands {
|
||||
if HasRuntimeContractFinal(command.PrimaryCommand) {
|
||||
declaredTools[strings.TrimSpace(command.CanonicalPath)] = true
|
||||
}
|
||||
}
|
||||
canonicalPaths := make([]string, 0, len(hints.Tools)+len(declaredTools))
|
||||
seenCanonical := map[string]bool{}
|
||||
for canonical := range hints.Tools {
|
||||
canonicalPaths = append(canonicalPaths, canonical)
|
||||
seenCanonical[canonical] = true
|
||||
}
|
||||
for canonical := range declaredTools {
|
||||
if !seenCanonical[canonical] {
|
||||
canonicalPaths = append(canonicalPaths, canonical)
|
||||
}
|
||||
}
|
||||
sort.Strings(canonicalPaths)
|
||||
for _, canonical := range canonicalPaths {
|
||||
@@ -536,7 +551,10 @@ func buildManualAgentExampleExecutionPlan(bound BoundCommandRegistry, typedTools
|
||||
if !ok {
|
||||
return ManualAgentExampleExecutionPlan{}, fmt.Errorf("agent_hints example references unknown canonical tool %q", canonical)
|
||||
}
|
||||
hint := hints.Tools[canonical]
|
||||
hint, hintOK := hints.Tools[canonical]
|
||||
if !hintOK {
|
||||
hint = contractFinalSelectionHint(spec.PrimaryCommand)
|
||||
}
|
||||
var typedTool ToolSpec
|
||||
if typedTools != nil {
|
||||
var found bool
|
||||
@@ -629,7 +647,7 @@ func buildManualAgentExampleExecutionPlan(bound BoundCommandRegistry, typedTools
|
||||
}
|
||||
}
|
||||
for canonical := range typedTools {
|
||||
if _, ok := hints.Tools[canonical]; !ok {
|
||||
if _, ok := hints.Tools[canonical]; !ok && !declaredTools[canonical] {
|
||||
return ManualAgentExampleExecutionPlan{}, fmt.Errorf("final typed SchemaRegistry tool %q has no Manual Agent hint examples", canonical)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -991,6 +991,11 @@ func schemaSafetyFromDecl(risk Risk, decl SafetyDecl) *cli.SafetySpec {
|
||||
out.Confirmation = "not_required"
|
||||
}
|
||||
}
|
||||
}
|
||||
// effect_source is assembly-derived for every Contract-declared safety,
|
||||
// whether it came from the Risk shorthand or an explicit SchemaDecl; the
|
||||
// declaration in code is the source of truth.
|
||||
if out.Effect != "" && out.EffectSource == "" {
|
||||
out.EffectSource = "cmdcore.contract"
|
||||
}
|
||||
if out.Effect == "" && out.Risk == "" && out.Confirmation == "" && out.Idempotency == "" {
|
||||
|
||||
@@ -0,0 +1,166 @@
|
||||
// Copyright 2026 Alibaba Group
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
package agentmetadata
|
||||
|
||||
import (
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
// applyContractFinalDeclarations merges each registered Contract final
|
||||
// overlay (cmdcore.SchemaDecl pass-through) into the matching tool record as
|
||||
// the top-precedence candidate. Declared tools stop depending on selection
|
||||
// hint files: the in-code declaration is the single final source for every
|
||||
// field it carries. Non-declared tools are untouched.
|
||||
//
|
||||
// Runs after hint reconciliation so rank ordering decides the winner; the
|
||||
// contract rank outranks every file/manual source.
|
||||
func applyContractFinalDeclarations(file *File, opts Options) error {
|
||||
if file == nil || len(opts.BoundCommands.ByCanonical) == 0 {
|
||||
return nil
|
||||
}
|
||||
canonicals := make([]string, 0, len(opts.BoundCommands.ByCanonical))
|
||||
for canonical := range opts.BoundCommands.ByCanonical {
|
||||
canonicals = append(canonicals, canonical)
|
||||
}
|
||||
sort.Strings(canonicals)
|
||||
for _, canonical := range canonicals {
|
||||
bound := opts.BoundCommands.ByCanonical[canonical]
|
||||
metadata, ok := contractFinalToolMetadata(bound.PrimaryCommand)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
primary := normalizeCommandPath(opts.CanonicalToolPaths[canonical])
|
||||
if primary == "" {
|
||||
continue
|
||||
}
|
||||
merged, err := mergeToolMetadata(file.Tools[primary], metadata, primary)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file.Tools[primary] = merged
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// contractFinalToolMetadata maps a registered Contract final overlay to a
|
||||
// ToolMetadata candidate whose fields carry the contract_final rank/origin.
|
||||
// Absent payload sections stay absent (never authored-empty); declared
|
||||
// sections map field-by-field, preserving explicit empty-list authorship.
|
||||
func contractFinalToolMetadata(command *cobra.Command) (ToolMetadata, bool) {
|
||||
payload, ok := cli.RuntimeContractFinal(command)
|
||||
if !ok {
|
||||
return ToolMetadata{}, false
|
||||
}
|
||||
metadata := ToolMetadata{
|
||||
AgentSummarySource: "cmdcore.SchemaDecl",
|
||||
SourceRefs: []string{"cmdcore.SchemaDecl"},
|
||||
reviewedRank: selectionRankContractFinal,
|
||||
reviewedOrigin: contractFinalOrigin,
|
||||
}
|
||||
// Declarations live in reviewed code, so the Agent reviewed flag is
|
||||
// assembly-derived true (mirrors the catalog pass-through).
|
||||
reviewed := true
|
||||
metadata.Reviewed = &reviewed
|
||||
|
||||
if selection := payload.Selection; selection != nil {
|
||||
if summary := strings.TrimSpace(selection.AgentSummary); summary != "" {
|
||||
metadata.AgentSummary = summary
|
||||
metadata.agentSummaryPresent = true
|
||||
metadata.agentSummaryRank = selectionRankContractFinal
|
||||
metadata.agentSummaryOrigin = contractFinalOrigin
|
||||
}
|
||||
for _, list := range []struct {
|
||||
value []string
|
||||
out *[]string
|
||||
present *bool
|
||||
rank *int
|
||||
origin *string
|
||||
}{
|
||||
{selection.UseWhen, &metadata.UseWhen, &metadata.useWhenPresent, &metadata.useWhenRank, &metadata.useWhenOrigin},
|
||||
{selection.AvoidWhen, &metadata.AvoidWhen, &metadata.avoidWhenPresent, &metadata.avoidWhenRank, &metadata.avoidWhenOrigin},
|
||||
{selection.Prerequisites, &metadata.Prerequisites, &metadata.prerequisitesPresent, &metadata.prerequisitesRank, &metadata.prerequisitesOrigin},
|
||||
{selection.Tips, &metadata.Tips, &metadata.tipsPresent, &metadata.tipsRank, &metadata.tipsOrigin},
|
||||
{selection.WorkflowRefs, &metadata.WorkflowRefs, &metadata.workflowRefsPresent, &metadata.workflowRefsRank, &metadata.workflowRefsOrigin},
|
||||
{selection.Examples, &metadata.Examples, &metadata.examplesPresent, &metadata.examplesRank, &metadata.examplesOrigin},
|
||||
} {
|
||||
if list.value == nil {
|
||||
continue
|
||||
}
|
||||
*list.out = list.value
|
||||
*list.present = true
|
||||
*list.rank = selectionRankContractFinal
|
||||
*list.origin = contractFinalOrigin
|
||||
}
|
||||
}
|
||||
|
||||
if safety := payload.Safety; safety != nil {
|
||||
if effect := strings.TrimSpace(safety.Effect); effect != "" {
|
||||
metadata.Effect = effect
|
||||
metadata.EffectSource = contractFinalOrigin
|
||||
metadata.effectPresent = true
|
||||
metadata.effectRank = selectionRankContractFinal
|
||||
metadata.effectOrigin = contractFinalOrigin
|
||||
}
|
||||
if risk := strings.TrimSpace(safety.Risk); risk != "" {
|
||||
metadata.Risk = risk
|
||||
metadata.riskPresent = true
|
||||
metadata.riskRank = selectionRankContractFinal
|
||||
metadata.riskOrigin = contractFinalOrigin
|
||||
}
|
||||
if confirmation := strings.TrimSpace(safety.Confirmation); confirmation != "" {
|
||||
metadata.Confirmation = confirmation
|
||||
metadata.confirmationPresent = true
|
||||
metadata.confirmationRank = selectionRankContractFinal
|
||||
metadata.confirmationOrigin = contractFinalOrigin
|
||||
}
|
||||
if idempotency := strings.TrimSpace(safety.Idempotency); idempotency != "" {
|
||||
metadata.Idempotency = idempotency
|
||||
metadata.idempotencyPresent = true
|
||||
metadata.idempotencyRank = selectionRankContractFinal
|
||||
metadata.idempotencyOrigin = contractFinalOrigin
|
||||
}
|
||||
}
|
||||
|
||||
if iface := payload.Interface; iface != nil {
|
||||
if mode := strings.TrimSpace(iface.Mode); mode != "" {
|
||||
metadata.InterfaceMode = mode
|
||||
metadata.interfaceModePresent = true
|
||||
metadata.interfaceModeRank = selectionRankContractFinal
|
||||
metadata.interfaceModeOrigin = contractFinalOrigin
|
||||
}
|
||||
if availability := strings.TrimSpace(iface.Availability); availability != "" {
|
||||
metadata.Availability = availability
|
||||
metadata.availabilityPresent = true
|
||||
metadata.availabilityRank = selectionRankContractFinal
|
||||
metadata.availabilityOrigin = contractFinalOrigin
|
||||
}
|
||||
if reason := strings.TrimSpace(iface.Reason); reason != "" {
|
||||
metadata.InterfaceReason = reason
|
||||
metadata.interfaceReasonPresent = true
|
||||
metadata.interfaceReasonRank = selectionRankContractFinal
|
||||
metadata.interfaceReasonOrigin = contractFinalOrigin
|
||||
}
|
||||
if iface.Ref != nil {
|
||||
metadata.InterfaceRef = &InterfaceRef{ProductID: iface.Ref.ProductID, RPCName: iface.Ref.RPCName}
|
||||
metadata.interfaceRefPresent = true
|
||||
metadata.interfaceRefRank = selectionRankContractFinal
|
||||
metadata.interfaceRefOrigin = contractFinalOrigin
|
||||
}
|
||||
}
|
||||
return metadata, true
|
||||
}
|
||||
@@ -24,9 +24,11 @@ var reviewedSelectionFields = map[string]bool{
|
||||
"examples": true,
|
||||
}
|
||||
|
||||
// retainReviewedSelectionCandidates keeps only reviewed_explicit candidates for
|
||||
// Agent selection fields so metadata/skill/MCP prose cannot win after selection
|
||||
// files have been applied.
|
||||
// retainReviewedSelectionCandidates keeps only reviewed candidates
|
||||
// (reviewed_explicit or contract_final) for Agent selection fields so
|
||||
// metadata/skill/MCP prose cannot win after selection files have been
|
||||
// applied. contract_final candidates come from in-code Contract declarations
|
||||
// and outrank file sources for declared tools.
|
||||
func retainReviewedSelectionCandidates(file *File) {
|
||||
if file == nil {
|
||||
return
|
||||
@@ -54,13 +56,31 @@ func retainReviewedSelectionCandidates(file *File) {
|
||||
func onlyReviewedExplicitCandidates(candidates []FieldCandidateProvenance) []FieldCandidateProvenance {
|
||||
selected := make([]FieldCandidateProvenance, 0, len(candidates))
|
||||
for _, candidate := range candidates {
|
||||
if precedenceRank(candidate.Precedence) == selectionRankReviewedExplicit {
|
||||
if isReviewedSelectionRank(precedenceRank(candidate.Precedence)) {
|
||||
selected = append(selected, candidate)
|
||||
}
|
||||
}
|
||||
return selected
|
||||
}
|
||||
|
||||
// isReviewedSelectionRank reports whether a rank is a reviewed Agent selection
|
||||
// source: the reviewed selection files (reviewed_explicit) or an in-code
|
||||
// Contract final declaration (contract_final, the stronger reviewed source).
|
||||
func isReviewedSelectionRank(rank int) bool {
|
||||
return rank == selectionRankReviewedExplicit || rank == selectionRankContractFinal
|
||||
}
|
||||
|
||||
// isReviewedSelectionPrecedence mirrors isReviewedSelectionRank for provenance
|
||||
// precedence labels.
|
||||
func isReviewedSelectionPrecedence(precedence string) bool {
|
||||
switch strings.TrimSpace(precedence) {
|
||||
case selectionPrecedenceReviewedExplicit, selectionPrecedenceContractFinal:
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
func validateReviewedSelectionDelivery(file File, opts Options) error {
|
||||
problems := []string{}
|
||||
productIDs := sortedBoolKeys(opts.ProductIDs)
|
||||
@@ -107,23 +127,25 @@ func validateReviewedSelectionDelivery(file File, opts Options) error {
|
||||
name string
|
||||
valid bool
|
||||
}{
|
||||
{"agent_summary", strings.TrimSpace(metadata.AgentSummary) != "" && metadata.agentSummaryRank == selectionRankReviewedExplicit},
|
||||
{"use_when", len(metadata.UseWhen) > 0 && metadata.useWhenRank == selectionRankReviewedExplicit},
|
||||
{"avoid_when", len(metadata.AvoidWhen) > 0 && metadata.avoidWhenRank == selectionRankReviewedExplicit},
|
||||
{"examples", len(metadata.Examples) > 0 && metadata.examplesRank == selectionRankReviewedExplicit},
|
||||
{"reviewed", metadata.Reviewed != nil && *metadata.Reviewed && metadata.reviewedRank == selectionRankReviewedExplicit},
|
||||
{"agent_summary", strings.TrimSpace(metadata.AgentSummary) != "" && isReviewedSelectionRank(metadata.agentSummaryRank)},
|
||||
{"use_when", len(metadata.UseWhen) > 0 && isReviewedSelectionRank(metadata.useWhenRank)},
|
||||
{"avoid_when", len(metadata.AvoidWhen) > 0 && isReviewedSelectionRank(metadata.avoidWhenRank)},
|
||||
{"examples", len(metadata.Examples) > 0 && isReviewedSelectionRank(metadata.examplesRank)},
|
||||
{"reviewed", metadata.Reviewed != nil && *metadata.Reviewed && isReviewedSelectionRank(metadata.reviewedRank)},
|
||||
}
|
||||
for _, check := range checks {
|
||||
if !check.valid {
|
||||
problems = append(problems, canonical+" "+check.name+" is not reviewed_explicit")
|
||||
problems = append(problems, canonical+" "+check.name+" is not reviewed_explicit/contract_final")
|
||||
}
|
||||
}
|
||||
for _, field := range []string{"agent_summary", "use_when", "avoid_when", "examples"} {
|
||||
provenance, ok := metadata.FieldProvenance[field]
|
||||
if !ok || provenance.Precedence != selectionPrecedenceReviewedExplicit || selectedCandidateCount(provenance.Candidates) != 1 {
|
||||
problems = append(problems, canonical+" "+field+" provenance is not one reviewed_explicit winner")
|
||||
if !ok || !isReviewedSelectionPrecedence(provenance.Precedence) || selectedCandidateCount(provenance.Candidates) != 1 {
|
||||
problems = append(problems, canonical+" "+field+" provenance is not one reviewed_explicit/contract_final winner")
|
||||
}
|
||||
if ok && !strings.Contains(provenance.Source, "/selection/") {
|
||||
// File-based winners must come from a selection/ source file;
|
||||
// contract_final winners are declared in code (no file path).
|
||||
if ok && provenance.Precedence != selectionPrecedenceContractFinal && !strings.Contains(provenance.Source, "/selection/") {
|
||||
problems = append(problems, canonical+" "+field+" source is not selection/: "+provenance.Source)
|
||||
}
|
||||
}
|
||||
@@ -197,6 +219,16 @@ func validateSelectionAuthoringContracts(opts Options) error {
|
||||
return fmt.Errorf("load selection Agent hints: %w", err)
|
||||
}
|
||||
expectedTools := expectedCanonicalToolSet(opts)
|
||||
// Declared tools carry their selection fields in the Contract final
|
||||
// overlay (cmdcore.SchemaDecl); they are exempt from hint-file coverage.
|
||||
// Hint rows for them may still exist during migration, but are no longer
|
||||
// required and never win over the declaration.
|
||||
for canonical := range expectedTools {
|
||||
bound, ok := opts.BoundCommands.ByCanonical[canonical]
|
||||
if ok && cli.HasRuntimeContractFinal(bound.PrimaryCommand) {
|
||||
delete(expectedTools, canonical)
|
||||
}
|
||||
}
|
||||
if err := cli.ValidateManualAgentHintSet(hints, opts.ProductIDs, expectedTools); err != nil {
|
||||
return fmt.Errorf("validate selection Agent hints: %w", err)
|
||||
}
|
||||
|
||||
@@ -245,6 +245,10 @@ const (
|
||||
selectionRankExplicit = 300
|
||||
selectionRankReviewedExplicit = 400
|
||||
selectionRankReviewedManual = 500
|
||||
// Contract final declarations (cmdcore.SchemaDecl, registered in-process)
|
||||
// outrank every file/manual source: the declaration in reviewed code is
|
||||
// the final data source for declared tools.
|
||||
selectionRankContractFinal = 600
|
||||
|
||||
selectionPrecedenceDefault = "inference_or_default"
|
||||
selectionPrecedenceMCPFallback = "mcp_fallback"
|
||||
@@ -254,8 +258,14 @@ const (
|
||||
selectionPrecedenceExplicit = "explicit"
|
||||
selectionPrecedenceReviewedExplicit = "reviewed_explicit"
|
||||
selectionPrecedenceReviewedManual = "reviewed_manual"
|
||||
selectionPrecedenceContractFinal = "contract_final"
|
||||
)
|
||||
|
||||
// contractFinalOrigin labels every candidate sourced from an in-process
|
||||
// Contract final declaration. It is not a file path; the declaration lives in
|
||||
// reviewed command source code (cmdcore.SchemaDecl).
|
||||
const contractFinalOrigin = "cmdcore.contract"
|
||||
|
||||
type Options struct {
|
||||
Root string
|
||||
SkillPath string
|
||||
@@ -468,6 +478,9 @@ func generateFromSources(opts Options) (File, Stats, error) {
|
||||
if err := reconcileSurface(&out, opts, &stats, origins); err != nil {
|
||||
return File{}, Stats{}, err
|
||||
}
|
||||
if err := applyContractFinalDeclarations(&out, opts); err != nil {
|
||||
return File{}, Stats{}, err
|
||||
}
|
||||
seedEffectiveToolProjection(&out, opts.ToolPaths)
|
||||
if err := validateEffectiveToolProjection(out, opts); err != nil {
|
||||
return File{}, Stats{}, err
|
||||
@@ -1209,6 +1222,8 @@ func scalarIncomingWon(previousValue string, previousPresent bool, previousRank
|
||||
|
||||
func selectionPrecedence(rank int) string {
|
||||
switch rank {
|
||||
case selectionRankContractFinal:
|
||||
return selectionPrecedenceContractFinal
|
||||
case selectionRankReviewedManual:
|
||||
return selectionPrecedenceReviewedManual
|
||||
case selectionRankReviewedExplicit:
|
||||
@@ -1648,6 +1663,8 @@ func syncProductFieldProvenance(metadata *ProductMetadata) {
|
||||
|
||||
func precedenceRank(precedence string) int {
|
||||
switch strings.TrimSpace(precedence) {
|
||||
case selectionPrecedenceContractFinal:
|
||||
return selectionRankContractFinal
|
||||
case selectionPrecedenceReviewedManual:
|
||||
return selectionRankReviewedManual
|
||||
case selectionPrecedenceReviewedExplicit:
|
||||
|
||||
@@ -456,6 +456,14 @@ func validateSelectionHintInput(rootPath, hintsDir string, registry commandRegis
|
||||
for canonical := range registry.CanonicalToolPaths {
|
||||
expectedTools[canonical] = true
|
||||
}
|
||||
// Declared tools carry selection fields in the Contract final overlay
|
||||
// (cmdcore.SchemaDecl) and are exempt from hint-file coverage.
|
||||
for canonical := range expectedTools {
|
||||
bound, ok := registry.Bound.ByCanonical[canonical]
|
||||
if ok && cli.HasRuntimeContractFinal(bound.PrimaryCommand) {
|
||||
delete(expectedTools, canonical)
|
||||
}
|
||||
}
|
||||
if err := validateSelectionMetadataSet(agentHints, registry.ProductIDs, expectedTools); err != nil {
|
||||
return fmt.Errorf("validate selection Agent hints: %w", err)
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user