dingtalk-workspace-cli/internal/cli/schema_hints

DWS Agent Schema Hints

This directory contains versioned, structured Agent metadata. Hints belong to the CLI Schema subsystem rather than either installable Skill layout. They are excluded from embedded binaries and release Skill bundles. Files generate internal/cli/schema_agent_metadata/; generated runtime metadata must not be edited directly.

Layout

Human-authored inputs live in two blocks:

• index.json (format: dws-agent-hint-index) — maps product IDs to metadata and selection files, plus reference review
• metadata/<product>.json — command metadata: safety, interface, runtime_gate, and optional parameter overrides
• selection/<product>.json — Agent selection prose
• imported/ — sanitized baseline from a fixed external revision

When index.json is present, the generator loads imported/ plus the metadata and selection files listed in the index. Sibling review JSON files in this directory remain CI/audit inputs and are not applied as Agent metadata sources.

For the end-to-end Agent curation workflow, see AGENTS.md § “Agent curation workflow (Schema hints)”.

Source kinds

• reviewed_explicit: reviewed metadata or selection HintFiles under metadata/ / selection/ (reviewed: true). Selection prose is delivered only from selection/.
• explicit: explicit but not per-tool-reviewed DWS hints.
• imported: sanitized metadata from a fixed external revision. It fills missing Agent semantics but cannot redefine command paths or parameter contracts.

Skill Markdown and audit JSON in this directory remain authoring evidence. Normal generation does not semantically combine Markdown into the final Agent prose and never rewrites metadata/selection files.

The Agent metadata generator also reads the committed internal/cli/schema_mcp_metadata.json after Skill and Hint parsing. A sanitized MCP description can fill an otherwise empty agent_summary; it is marked reviewed: false, retains revision provenance, and cannot infer or override risk/effect fields.

Tool keys should use stable canonical_path values from internal/cli/schema_command_registry.json. CLI paths and aliases are also accepted and are reconciled to the canonical public tool during generation.

selection-review.json fixes the reviewed command-selection contract for every public tool: use_when, avoid_when, safe examples, and the ordinary direct interface disposition. Exceptional or formerly unmatched wrappers are owned by the interface-only reviewed source zz-interface-disposition-review.json. runtime-surface-completeness.json remains unreviewed selection evidence and must not promote its other fields merely to classify an interface. These values are build inputs; the generator must not derive them from the previous Catalog.

reference-review.json classifies every Skill command reference that is not a current public leaf. alias entries bind an old or cross-product path to an explicit current target. group, stale, and out_of_surface entries remain visible in the audit but are never fuzzy-matched to a leaf.

interface_ref is a separate interface binding. Use it when a public helper/canonical tool calls a differently named MCP RPC or another source product:

{
  "version": 1,
  "source": {"kind": "explicit", "name": "reviewed-interface-map"},
  "tools": {
    "chat.bot_search": {
      "interface_ref": {
        "product_id": "bot",
        "rpc_name": "search_my_robots"
      }
    }
  }
}

An entry containing only interface_ref participates in interface projection but does not count as Agent semantic coverage. It cannot add a command, change a flag, or expose a Wukong-only tool.

interface_mode and availability are orthogonal reviewed fields. interface_mode has exactly three values:

• mcp: exactly one pinned interface_ref implements the command, with an auditable parameter mapping and semantically equivalent execution contract.
• composite: multiple RPCs, conditional routing, local projection, or a reviewed remote adapter absent from pinned metadata implements the command; a singular ref would be misleading.
• local: the command is fully implemented by the local process, static data, or local policy. An unpinned remote RPC is never local.

availability is available or unavailable. An unavailable command keeps its real implementation mode, must not carry interface_ref, and must include an explicit interface_reason; unavailable is never an interface mode.

The missing notify MCP service is separately dispositioned in internal/cli/schema_mcp_service_review.json; it is outside the public command surface and must not trigger runtime discovery.

internal/cli/schema_mcp_metadata.json.coverage.surface_tools describes only the immutable MCP import at its declared source_revision; it is not the current CLI/Catalog tool count. Its coverage.surface_scope must remain source_revision, and policy verifies the snapshot's internal matched and unmatched arithmetic. Current Catalog interface coverage is instead proved for every generated tool: each tool must have one valid interface_mode / availability disposition and retain reviewed provenance to selection-review.json, zz-interface-disposition-review.json, or another reviewed interface source. This makes newly added CLI tools explicit without rewriting historical MCP evidence or promoting an unreviewed selection hint.

Interface metadata contributes lower-priority typed candidates, including required; source precedence is value-neutral for most fields, so a candidate may raise or lower the Agent-facing value when no higher-priority source wins. It cannot override reviewed manual hints, versioned bindings, typed/native metadata, or current Cobra/constraint facts for those fields. required is special: Cobra MarkFlagRequired is a hard floor that cannot be projected away as optional. cli_required remains the executable Cobra marker with its own provenance.

{
  "version": 1,
  "source": {
    "kind": "explicit",
    "name": "calendar-schema-review"
  },
  "products": {
    "calendar": {
      "agent_summary": "管理日程、参与人、会议室和闲忙信息"
    }
  },
  "tools": {
    "calendar.get_calendar_detail": {
      "agent_summary": "读取一个日程的完整详情",
      "use_when": ["已经取得 eventId，需要查看详情"],
      "effect": "read",
      "reviewed": true
    }
  }
}

Run make generate-schema after changing Hint or Skill sources. External Wukong metadata must be refreshed by the controlled offline import pipeline with an immutable revision, then committed together with its audit before regenerating the Catalog; runtime refresh is forbidden.

Metadata parameters and selection prose

Agent semantic hints in this directory do not change the executable CLI contract beyond reviewed parameter overlays on metadata tools.

Block	Owns
metadata/<product>.json	safety, interface, runtime_gate, optional parameters / cli_path
selection/<product>.json	agent_summary, use_when, avoid_when, examples

Parameter overlays may override Schema description, interface-property/type mapping, required, and required_when for flags that already exist on that command. They cannot create a command or flag, target a hidden/group command, define an interface, or mark an unknown RPC available. Missing commands and flags, wildcards, canonical conflicts, duplicate paths, and unreviewed entries fail generation.

Selection prose is committed as a reviewed source. go generate only reads, validates, and projects this data. It must never call a model, copy a previous Catalog, or overwrite metadata/selection files. Selection cannot change command identity, flags, parameters, safety, or interface facts.

Commands intentionally kept outside Schema remain in the separate exact reviewed exclusion file internal/cli/schema_command_exclusions.json. An included command cannot also remain excluded: completeness validation treats that exclusion as stale.

Agent editing workflow

1. Locate the real Cobra leaf and verify its exact path and current flags.

2. Edit only the owning block (metadata/ or selection/); do not mix fields.

3. Add only fields that need review. Do not copy generated Catalog fields into the input.

4. Use property and interface_type only for a real CLI-to-interface conversion. required and required_when describe the Schema projection; they do not modify Cobra execution validation.

5. Run:

   make generate-schema
   ./scripts/policy/check-generated-drift.sh
   ./scripts/policy/check-schema-catalog.sh
   ./scripts/policy/check-runtime-confirmation-truth.sh
   go test ./internal/cli ./internal/app
   

6. Review the generated Catalog diff. A parameter overlay should affect only the intended contract. A selection edit updates prose provenance to reviewed_explicit from selection/.