Files

T

Ari 7828089081 feat: subcommand merging, schema pretty, IR overlays, v1.0.15 notes (#160 )

* feat(compat): merge same-name subcommands under shared parent

When multiple server entries attach to the same parent and their cli.command
collides with a subcommand already in the parent tree, the incoming subcommand's
children are merged recursively into the existing one instead of producing a
duplicate sibling. Leaf-name collisions resolve first-wins.

Fixes the duplicate `group` / `message` rows in `dws chat --help` that surfaced
when bot capabilities were distributed across chat.group.members and
chat.message subtrees.

* feat(ir): carry FlagOverlay and ToolAnnotations into canonical catalog

FlagOverlay mirrors the per-parameter CLI overlay (alias, transform,
transformArgs, env default, default value, hidden) sourced from
market.CLIToolOverride.Flags.

ToolAnnotations mirrors MCP 2025+ tool annotations with nullable hints
(destructive / read-only / idempotent / open-world) so absence means
"unknown" rather than "false".

BuildCatalog now propagates both through the canonical layer, with tests
covering group metadata and flag-overlay passthrough.

* feat(output): add -f pretty for schema-aware colored output

dws schema now supports -f pretty alongside json / raw. Pretty mode
partitions output by product / tool / parameter / enum and applies ANSI
color so humans can browse the catalog without piping through jq.
json / raw behaviour is unchanged.

docs/reference.md gains a Schema Introspection section documenting
dws schema and the new pretty format.

* feat(skills): refresh 13-product references; add devdoc / drive / oa

SKILL.md cli_version bumped to >=1.0.15; product index reordered to match
the v1.0.15 command surface.

New references:
- devdoc.md: Open Platform documentation search
- drive.md: DingTalk drive (promoted out of Coming soon)
- oa.md: OA approval end-to-end flow

Major rewrites for aitable (dashboard / chart share, import/export,
attachment flow), chat (bot capabilities merged into chat.message and
chat.group.members), calendar (event suggest / attachments), doc (comment
subtree, file create, upload/download flow), and minutes (list
mine/shared/all unified, record subcommands split).

Minor alignment touch-ups for contact / report / todo flag names.

* docs(release): sync v1.0.15 notes — 159 commands across 13 products

README Key Services fully refreshed: chat 23, calendar 14, aitable 41,
doc 21, minutes 19; drive promoted out of Coming soon; workbench and
standalone bot rows removed; Quick Start expanded to 7 examples spanning
doc / minutes / drive; Coming soon trimmed to mail / conference / aiapp /
live / wiki.

Adds docs/command-index.md, an auto-generated English listing of all 159
runtime commands with description and when-to-use guidance aimed at AI
agents. Replaces the ad-hoc command-index.pre.* / command-index.full.*
snapshots used during development.

CHANGELOG 1.0.15 records the compat subcommand-merging feature, the new
command index, and a flag-naming cleanup across chat / calendar / drive /
minutes / contact / devdoc.

2026-04-24 00:01:22 +08:00

4.4 KiB

Raw Blame History

Reference / 参考手册

Environment Variables / 环境变量

Variable	Purpose / 用途
`DWS_CONFIG_DIR`	Override default config directory / 覆盖默认配置目录
`DWS_SERVERS_URL`	Point discovery at a custom server registry endpoint / 将服务发现指向自定义端点
`DWS_CLIENT_ID`	OAuth client ID (DingTalk AppKey)
`DWS_CLIENT_SECRET`	OAuth client secret (DingTalk AppSecret)
`DWS_TRUSTED_DOMAINS`	Comma-separated trusted domains for bearer token (default: `.dingtalk.com`). `` for dev only / Bearer token 允许发送的域名白名单，默认 `.dingtalk.com`，仅开发环境可设为 ``
`DWS_ALLOW_HTTP_ENDPOINTS`	Set `1` to allow HTTP for loopback during dev / 设为 `1` 允许回环地址 HTTP，仅用于开发调试

Exit Codes / 退出码

Code	Category	Description / 描述
0	Success	Command completed successfully / 命令执行成功
1	API	MCP tool call or upstream API failure / MCP 工具调用或上游 API 失败
2	Auth	Authentication or authorization failure / 身份认证或授权失败
3	Validation	Invalid input, flags, or parameter schema mismatch / 输入参数校验失败
4	Discovery	Server discovery, cache, or protocol negotiation failure / 服务发现失败
5	Internal	Unexpected internal error / 未预期的内部错误

With -f json, error responses include structured payloads: category, reason, hint, actions.

使用 -f json 时，错误响应包含结构化字段：category、reason、hint、actions。

Output Formats / 输出格式

dws contact user search --keyword "Alice" -f table   # Table (default, human-friendly / 表格，默认)
dws contact user search --keyword "Alice" -f json    # JSON (for agents and piping / 适合 agent)
dws contact user search --keyword "Alice" -f raw     # Raw API response / 原始响应
dws schema -f pretty ding.send_ding_message          # Pretty (ANSI-colored, schema-aware / 彩色分区，专为 schema 设计)

Dry Run / 试运行

dws todo task list --dry-run    # Preview MCP call without executing / 预览但不执行

Output to File / 输出到文件

dws contact user search --keyword "Alice" -o result.json

Schema Introspection / Schema 查询

dws schema 查询已发现的 MCP 产品和工具元数据。不带参数列出所有产品，带路径输出单个工具的完整 schema。

路径写法

dws schema                                  # 列出所有产品 + 工具名
dws schema ding.send_ding_message           # canonical: product.rpc_name
dws schema ding.message.send                # CLI 点路径: product.group.cli_name
dws schema "ding message send"              # CLI 空格路径（同上）
dws schema --cli-path "ding message send"   # 显式 flag（脚本友好，免转义）
dws schema -f pretty ding.send_ding_message # ANSI 着色分区展示（人肉查看最舒服）

Canonical 路径先匹配；落空后走 CLI 路径（product → group.. → cli_name）。

单工具输出字段

字段	说明
`name` / `cli_name` / `canonical_path`	MCP RPC 名 / CLI 叶子名 / `product.rpc_name`
`group`	CLI 父级 group 路径（dot-separated）
`title` / `description`	工具名/说明（overlay 优先）
`parameters` / `required`	MCP 输入 JSON Schema 的 properties / required
`output_schema`	MCP 输出 Schema（上游下发时才有）
`sensitive`	敏感写操作，需 `--yes` 确认
`annotations.destructive_hint`	对齐 MCP 2025+ annotations，目前从 `sensitive` 映射
`flag_overlay[param]`	CLI 层对 MCP 参数的改写：`alias` / `transform` / `transform_args` / `env_default` / `default` / `hidden`

调试 --flag 行为的第一站是 flag_overlay —— 比如 --users 0232... 能不能直接用，看 receiverUserIdList.transform == "csv_to_array" 即可判断。

筛选输出

dws schema ding.send_ding_message --jq '.tool.flag_overlay'       # 只看 overlay
dws schema --jq '.products[] | {id, count: (.tools|length)}'      # 各产品工具数
dws schema aitable.delete_base --jq '.tool.annotations'           # 敏感操作提示

Shell Completion / 自动补全

# Bash
dws completion bash > /etc/bash_completion.d/dws

# Zsh
dws completion zsh > "${fpath[1]}/_dws"

# Fish
dws completion fish > ~/.config/fish/completions/dws.fish

4.4 KiB Raw Blame History Unescape Escape