Ari
109ad13844
* fix: honor global --jq/--fields on product commands; round-2 QA fixes
Make the global --jq / --fields output filters actually work for the
product (MCP) commands. The helper Formatter used by every product
command ignored them, so they were silent no-ops there (they already
worked for `dws api`). Expose Fields()/JQ() on the ToolCaller interface
and apply the existing output.WriteFiltered path in the helper
Formatter's PrintJSON. The handful of bespoke utility commands
(auth/config/profile/...) still encode directly and are documented as
such.
Additional CLI fixes surfaced by the second real-machine QA pass:
- sheet write-image: emit clean JSON under --format json (suppress the
progress lines that leaked onto stdout, same as media-upload/export)
- sheet range batch-set-style: under --format json, collect per-item
results into a single JSON object instead of printing N separate ones
- chat download-media: create the output directory when missing and
strip URL-encoded path separators from the inferred filename so the
file actually lands instead of failing on a missing subdirectory
- pat chmod, aitable, sheet, chat, attendance: correct --help text
(real scope names, non-existent subcommands, flag requiredness,
alxs -> axls typo)
Helper scripts (mono and multi):
- minutes_extract_todos: parse dingtalkTodoList/actions (there is no
todos key), so todos are no longer silently dropped
- sync the multi copies of chat_export_messages / chat_history_with_user
(were crashing with AttributeError), minutes_list_parse /
minutes_recent_summary, and calendar_free_slot_finder to the fixed
mono versions
Skill docs (mono and multi): correct return-structure keys, flag names,
deprecated command routing (doc download -> drive download), enum values
and server-side limitations across products; update the global
reference to note --jq/--fields now apply to product commands.
* fix(skill): make skill setup --dry-run a no-op preview; doc/help fixups
skill setup ignored the global --dry-run flag and always wrote the skill
files (overwriting an existing install). Short-circuit into a preview
that lists the source, target dirs and selected sub-skills without
touching the filesystem.
Also correct a few doc/help mismatches found in the round-3 health check:
- attendance vacation balance/records quick-reference examples were
missing the required --leave-code flag
- mail mailbox list --help described the returned field as "mailboxes"
but the real field is "emailAccounts"
* docs: clarify --fields projects top-level/list keys, use --jq for nested
* docs: drop QA voice ("真机") and don't state env-specific quirks as absolute rules
The QA-driven doc/comment edits leaked test-process narration ("真机实测")
and this environment/account's quirks stated as universal rules into the
skill files, which are general-purpose instructions for any org/account.
Strip the "真机" narration everywhere; reword environment-specific findings
(PUBLIC sharing disabled by org policy, transient 1002, sender-open-dingtalk-id
behaviour) from absolute bans into conditional hints; keep genuinely
universal command behaviour, just without the QA voice.
50 lines
2.0 KiB
Markdown
50 lines
2.0 KiB
Markdown
# 开放平台文档 (devdoc) 命令参考
|
|
|
|
搜索钉钉**开放平台**开发文档，用于回答开发者关于 OpenAPI、字段、错误码、接入指南、配额等技术问题。
|
|
|
|
## 命令总览
|
|
|
|
### 搜索开发文档
|
|
```
|
|
Usage:
|
|
dws devdoc article search [keyword] [flags]
|
|
Example:
|
|
dws devdoc article search "MCP" # 关键词可作位置参数，等价于 --query
|
|
dws devdoc article search --query "OAuth2 接入"
|
|
dws devdoc article search --query "消息卡片" --page 2 --size 5
|
|
dws devdoc article search --query "机器人" --size 10
|
|
Flags:
|
|
--query string 搜索关键词 (必填；也可用位置参数 [keyword] 传)
|
|
--page string 分页页码 (从 1 开始，default "1")
|
|
--size string 分页大小 (default "10")
|
|
```
|
|
|
|
## 意图判断
|
|
|
|
用户问开放平台 API / 字段 / 错误码 / SDK / 鉴权 / 回调 / 配额相关的技术细节:
|
|
- 走 `devdoc article search`，把用户问的关键短语作为 `--query`
|
|
|
|
关键区分:
|
|
- devdoc(钉钉**开放平台**开发者文档，面向研发) vs doc(钉钉在线文档，面向普通用户内容)
|
|
- devdoc 只做搜索，不做读取；命中条目返回标题、摘要、文档链接，由 Agent 引用链接或进一步浏览
|
|
|
|
## 核心工作流
|
|
|
|
```bash
|
|
# 开发者问"OAuth2 怎么接"
|
|
dws devdoc article search --query "OAuth2 接入" --format json
|
|
|
|
# 命中结果多时翻页
|
|
dws devdoc article search --query "消息卡片" --page 2 --size 5 --format json
|
|
|
|
# 查错误码 / 字段含义
|
|
dws devdoc article search --query "errcode 40078" --format json
|
|
```
|
|
|
|
## 注意事项
|
|
|
|
- `--query` 必填；建议传用户原话里的关键名词（API 名、错误码、能力名），不要过度改写
|
|
- 返回按相关性排序，默认 `--size 10`；要拿更多结果时先翻页，再考虑换关键词
|
|
- 命中结果里的链接是钉钉开放平台公开文档，可直接给用户做参考
|
|
- 不要把 devdoc 用来查业务数据（那是 aitable / doc / report 的事）；devdoc 只查**官方开发者文档**
|