405 lines
12 KiB
JSON
405 lines
12 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/blob/main/internal/cli/schema_manual_hints.schema.json",
|
|
"title": "DWS Manual Schema Hints",
|
|
"description": "The single Agent-editable, reviewed manual input for existing Cobra command/parameter overrides and product/tool Agent-selection prose. This file never creates commands, flags, parameters, safety facts, or interfaces.",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"$schema",
|
|
"version",
|
|
"commands",
|
|
"agent_hints"
|
|
],
|
|
"properties": {
|
|
"$schema": {
|
|
"const": "./schema_manual_hints.schema.json",
|
|
"description": "Keep this relative reference so editors and coding agents can discover this contract without network access."
|
|
},
|
|
"version": {
|
|
"const": 1,
|
|
"description": "Manual Schema Hint format version."
|
|
},
|
|
"commands": {
|
|
"type": "array",
|
|
"description": "Exact, reviewed Cobra leaves to expose or refine. Go validation rejects duplicate cli_path values and stale command or flag references.",
|
|
"items": {
|
|
"$ref": "#/$defs/commandHint"
|
|
},
|
|
"default": []
|
|
},
|
|
"agent_hints": {
|
|
"$ref": "#/$defs/agentHintSet"
|
|
}
|
|
},
|
|
"$defs": {
|
|
"agentHintSet": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"revisions",
|
|
"products",
|
|
"tools"
|
|
],
|
|
"properties": {
|
|
"revisions": {
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"propertyNames": {
|
|
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
|
|
},
|
|
"additionalProperties": {
|
|
"$ref": "#/$defs/agentHintRevision"
|
|
}
|
|
},
|
|
"products": {
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"propertyNames": {
|
|
"pattern": "^[A-Za-z0-9_-]+$"
|
|
},
|
|
"additionalProperties": {
|
|
"$ref": "#/$defs/agentProductHint"
|
|
}
|
|
},
|
|
"tools": {
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"propertyNames": {
|
|
"pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_.-]+$"
|
|
},
|
|
"additionalProperties": {
|
|
"$ref": "#/$defs/agentToolHint"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"agentHintRevision": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"generated_by",
|
|
"reason"
|
|
],
|
|
"properties": {
|
|
"generated_by": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Authoring mechanism, normally ai for the initial offline batch or human for a later hand revision."
|
|
},
|
|
"model": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"prompt_version": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"properties": {
|
|
"generated_by": {
|
|
"const": "ai"
|
|
}
|
|
},
|
|
"required": [
|
|
"generated_by"
|
|
]
|
|
},
|
|
"then": {
|
|
"required": [
|
|
"model",
|
|
"prompt_version"
|
|
]
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"agentProductHint": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/$defs/agentHintCommon"
|
|
}
|
|
],
|
|
"unevaluatedProperties": false
|
|
},
|
|
"agentToolHint": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/$defs/agentHintCommon"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"required": [
|
|
"examples"
|
|
],
|
|
"properties": {
|
|
"examples": {
|
|
"$ref": "#/$defs/nonEmptyStringArray",
|
|
"maxItems": 2,
|
|
"description": "Executable examples using a reviewed primary/alias path and real Cobra flags and required arguments. Do not include --yes or a help-only example."
|
|
},
|
|
"example_dispositions": {
|
|
"type": "array",
|
|
"uniqueItems": true,
|
|
"items": {
|
|
"$ref": "#/$defs/agentExampleDisposition"
|
|
},
|
|
"description": "Exact reviewed exceptions by zero-based example index. An omitted index always defaults to dry_run; runtime failures must never create an implicit exception."
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"unevaluatedProperties": false
|
|
},
|
|
"agentExampleDisposition": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"index",
|
|
"mode",
|
|
"reason_code",
|
|
"reason",
|
|
"reviewed"
|
|
],
|
|
"properties": {
|
|
"index": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Zero-based index into the enclosing tool's examples array. Go validation rejects duplicate and out-of-range indexes."
|
|
},
|
|
"mode": {
|
|
"const": "contract_only",
|
|
"description": "The only explicit override. dry_run is the default and is never stored as a disposition."
|
|
},
|
|
"reason_code": {
|
|
"enum": [
|
|
"local_state",
|
|
"stateful_preflight"
|
|
],
|
|
"description": "Narrow manual exception taxonomy for genuinely unavoidable local-state or stateful-preflight requirements. High-risk/user-confirmed operations still require fail-closed runtime dry-run without --yes; runtime errors, MCP resolution errors, and missing required arguments are never valid exceptions."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Concrete reviewed explanation of why isolated dry-run execution is unsafe or nondeterministic."
|
|
},
|
|
"reviewed": {
|
|
"const": true
|
|
}
|
|
}
|
|
},
|
|
"agentHintCommon": {
|
|
"type": "object",
|
|
"required": [
|
|
"agent_summary",
|
|
"use_when",
|
|
"avoid_when",
|
|
"reviewed",
|
|
"revision",
|
|
"reason",
|
|
"evidence"
|
|
],
|
|
"properties": {
|
|
"agent_summary": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"use_when": {
|
|
"$ref": "#/$defs/nonEmptyStringArray",
|
|
"description": "Reviewed positive Agent-selection scenarios. For tools, each entry becomes an eval case whose expected result is the enclosing canonical tool."
|
|
},
|
|
"avoid_when": {
|
|
"$ref": "#/$defs/nonEmptyStringArray",
|
|
"description": "Reviewed negative Agent-selection scenarios. For tools, each entry becomes an eval case that must not choose the enclosing canonical tool."
|
|
},
|
|
"reviewed": {
|
|
"const": true
|
|
},
|
|
"revision": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Key in agent_hints.revisions."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"evidence": {
|
|
"$ref": "#/$defs/nonEmptyStringArray"
|
|
}
|
|
}
|
|
},
|
|
"nonEmptyStringArray": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"uniqueItems": true,
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
}
|
|
},
|
|
"commandHint": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"cli_path",
|
|
"canonical_path",
|
|
"reason",
|
|
"reviewed"
|
|
],
|
|
"properties": {
|
|
"cli_path": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"pattern": "^(?:dws\\s+)?[^*?\\[\\]\\s]+(?:\\s+[^*?\\[\\]\\s]+)*$",
|
|
"description": "Exact path of an existing public runnable Cobra leaf, without flags or wildcard characters. Prefer omitting the leading 'dws'.",
|
|
"examples": [
|
|
"chat category create-smart"
|
|
]
|
|
},
|
|
"canonical_path": {
|
|
"type": "string",
|
|
"pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_.-]+$",
|
|
"description": "Stable product.tool identity exposed by dws schema. It must not conflict with an identity already attached to the Cobra command.",
|
|
"examples": [
|
|
"chat.create_smart_conv_category"
|
|
]
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Reviewable explanation of why this command or parameter projection belongs in the stable Agent Schema. Describe intent, not implementation mechanics."
|
|
},
|
|
"reviewed": {
|
|
"const": true,
|
|
"description": "Must be true. Unreviewed entries fail generation."
|
|
},
|
|
"parameters": {
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"description": "Optional Schema-only corrections keyed by an existing Cobra flag name without '--'. These values do not change Cobra help, flag types, or execution validation.",
|
|
"propertyNames": {
|
|
"pattern": "^[A-Za-z0-9][A-Za-z0-9-]*$"
|
|
},
|
|
"additionalProperties": {
|
|
"$ref": "#/$defs/parameterHint"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"parameterHint": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"minProperties": 1,
|
|
"properties": {
|
|
"description": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Agent-facing CLI parameter description. State accepted input and conditions concisely; do not copy secrets or runtime-discovered content."
|
|
},
|
|
"property": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Interface payload property populated by this existing CLI flag."
|
|
},
|
|
"interface_type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"string",
|
|
"array",
|
|
"object",
|
|
"integer",
|
|
"number",
|
|
"boolean"
|
|
],
|
|
"description": "Type after CLI-to-interface conversion. This does not change the real Cobra flag type."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether the flag is unconditionally required in the Agent-facing CLI contract. This does not add or remove Cobra execution validation."
|
|
},
|
|
"required_when": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Concise condition under which the flag is required. Use this instead of required=true for conditional requirements."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": [
|
|
{
|
|
"$schema": "./schema_manual_hints.schema.json",
|
|
"version": 1,
|
|
"commands": [
|
|
{
|
|
"cli_path": "chat category create-smart",
|
|
"canonical_path": "chat.create_smart_conv_category",
|
|
"reason": "Expose the existing smart-category helper and preserve its reviewed CLI-to-interface parameter projection.",
|
|
"reviewed": true,
|
|
"parameters": {
|
|
"name": {
|
|
"description": "分组名称 (必填)",
|
|
"property": "categoryName",
|
|
"required": true
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"agent_hints": {
|
|
"revisions": {
|
|
"ai-agent-contract-v1": {
|
|
"generated_by": "ai",
|
|
"model": "gpt-5",
|
|
"prompt_version": "dws-agent-contract-v1",
|
|
"reason": "Generate one reviewed Agent-selection baseline from Registry, Cobra Help, and Skill evidence."
|
|
}
|
|
},
|
|
"products": {
|
|
"chat": {
|
|
"agent_summary": "管理会话、群聊和消息",
|
|
"use_when": [
|
|
"需要查询或管理钉钉会话和消息时"
|
|
],
|
|
"avoid_when": [
|
|
"邮件操作使用 mail"
|
|
],
|
|
"reviewed": true,
|
|
"revision": "ai-agent-contract-v1",
|
|
"reason": "Reviewed product routing guidance.",
|
|
"evidence": [
|
|
"skills/mono/references/products/chat.md"
|
|
]
|
|
}
|
|
},
|
|
"tools": {
|
|
"chat.create_smart_conv_category": {
|
|
"agent_summary": "按条件创建智能会话分组",
|
|
"use_when": [
|
|
"需要自动归集符合名称、成员或关键词条件的会话时"
|
|
],
|
|
"avoid_when": [
|
|
"只需查看现有分组时不要使用"
|
|
],
|
|
"examples": [
|
|
"dws chat category create-smart --name 项目群"
|
|
],
|
|
"reviewed": true,
|
|
"revision": "ai-agent-contract-v1",
|
|
"reason": "Reviewed tool-selection guidance.",
|
|
"evidence": [
|
|
"dws chat category create-smart --help"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|