dingtalk-wiki · diff

git:20260814.596bdce to git:20260818.edbb175

68 added, 62 removed. Audit A to A.

---
name: dingtalk-wiki
- description: 钉钉知识库与空间管理。Use when 用户说 知识库/wiki/创建知识库/搜索知识库空间/我的文档/团队空间/空间成员/在指定知识库内的节点创建/列出/搜索/复制/移动/删除/知识库动态。知识库空间与空间内节点管理走本 skill（节点操作需 workspace）；未指定空间的全局文件管理与搜索走 dingtalk-drive，空间内单文档内容读写先用本 skill 定位再切到 dingtalk-doc。命令前缀：dws wiki。
+ description: 钉钉知识库与空间管理。Use when 用户明确说 知识库/wiki/创建、查找或列出知识库/命名的团队知识空间/个人知识库/知识库成员/库内节点创建、列表、搜索、复制、移动、删除或知识库动态。仅说“文档空间/我的文档”不触发：普通存储管理与全局文件搜索走 dingtalk-drive；节点正文读写走 dingtalk-doc。命令前缀：dws wiki。
metadata:
cli_version: ">=0.2.14"
category: product
requires:
bins:
- dws
---
# 钉钉知识库 Skill
- ## 前置条件 — 执行操作前必读
-
- > **CRITICAL — 执行任何 `dws` 操作前，MUST 先用 Read 工具完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。**该轻量文件包含全局执行契约、安全底线及 shared references 的按需加载导航；不要预加载其全部 references。
+ <!-- DWS_RUNTIME_CONTRACT_START -->
+ ## 最小 DWS 执行契约
- > 命令参考：[wiki.md](references/wiki.md)。
+ - 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。
+ - 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。
+ - 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
+ - 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
+ - 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
+ - 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。
+ - 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
+ - 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
+ - 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。
+ <!-- DWS_RUNTIME_CONTRACT_END -->
<!-- VISIBLE_SHORTCUTS_START -->
## Shortcuts（无专用脚本/recipe 时优先）
以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "wiki +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws wiki <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service wiki --format json` 批量发现。
| Shortcut | 风险 | 适用场景 |
|---|---|---|
| `dws wiki +resolve-space` | read | 按名称搜索知识空间并解析出唯一 spaceId（只读） |
| `dws wiki +wiki-new-doc` | write | 在指定名称的知识库下新建一个文档节点（自动按空间名解析 workspaceId） |
<!-- VISIBLE_SHORTCUTS_END -->
- ## 意图表
-
- | 用户说 | 命令 |
- |--------|------|
- | "创建知识库" | `dws wiki space create --name "<名称>" [--desc "<描述>"]` |
- | "搜索组织知识库空间" | `dws wiki space search --type orgWikiSpace --query "<关键词>"` |
- | "我的文档 / 个人知识库" | `dws wiki space search --type myWikiSpace` |
- | "列出知识库" | `dws wiki space list` |
- | "列出我的文档空间" | `dws wiki space list --type myWikiSpace` |
- | "列出知识库里的文件/节点" | `dws wiki node list --workspace <WS_ID>` |
- | "在知识库里搜" | `dws wiki node search --workspace <WS_ID> --query "<关键词>"` |
- | "在知识库里创建文档节点" | `dws wiki node create --workspace <WS_ID> --type adoc --name "<名称>"` |
- | "知识库动态 / 最近有什么更新 / 谁改了什么" | `dws wiki feed list --workspace <WS_ID>` |
-
- ## 标准 SOP（必遵流程）
-
- > 命中以下意图**必须**按对应 SOP 顺序执行；**禁止**跳步、替换命令、编造 workspaceId/nodeId。每条命令必须带 `--format json`。`workspaceId`/`nodeId` 一律先查后用。
-
- ### SOP-1 找知识库（find-space）
-
- **触发**：找知识库/列表空间/某知识库在哪。
-
- 1. **执行（必须）**：`dws wiki space list --format json`（列所有知识库/钉盘空间）；按名称找 `dws wiki space search --type orgWikiSpace --query "<名称>" --format json`。
- 2. **解析（必须）**：取真实 `workspaceId`；多候选让用户确认，**禁止**默认取第一个。`hasMore=true` 用 `nextPageToken` 翻页。
-
- **禁止**：编造 workspaceId、把空间名当 ID。
-
- ### SOP-2 浏览 / 查节点（list-nodes）
-
- **触发**：知识库里有哪些文档/列节点/看某节点。
-
- 1. **前置（必须）**：先按 SOP-1 拿 `workspaceId`。
- 2. **执行（必须）**：`dws wiki node list --workspace <workspaceId> --format json`（按需 `--folder <nodeId>` 看子节点）；按内容找 `dws wiki node search --workspace <workspaceId> --query "<关键词>" --format json`。
- 3. **解析（必须）**：取真实 `nodeId` + `nodeType`/`type`；锁定目标后按需切 `dingtalk-doc` 读写节点内容。
+ ## Golden Route
- **禁止**：跳过 SOP-1 直接猜 workspaceId、用 `node list` 替代 `node search` 做关键词查找。
+ | 用户意图 | 唯一推荐入口 | 关键边界 |
+ |---|---|---|
+ | 按名称解析唯一知识库 | `dws wiki +resolve-space --name <名称>` | 0 条或多条停止；只想看候选用 `+space-search` |
+ | 搜索或列出知识库 | `+space-search --query <关键词>` / `+space-list [--type orgWikiSpace\|myWikiSpace]` | 用户要求全部时加 `--page-all`；个人知识库必须明确语义 |
+ | 已知 workspace 查看详情 | `dws wiki +space-get --workspace <ID或URL>` | 已知 ID 不重复搜索 |
+ | 创建或删除知识库 | `+space-create --name <名称>` / `+delete-space --workspace <ID>` | 创建会读回；删除整个空间是高风险操作 |
+ | 浏览或搜索库内节点 | `+node-list --workspace <ID> [--folder <ID>]` / `+node-search --workspace <ID> --query <词>` | 列目录与关键词搜索分开；全量列表加 `--page-all` |
+ | 查看节点元数据 | `dws wiki +node-get --node <ID或URL>` | 正文读写随后切 Doc |
+ | 已知 workspace 创建节点 | `+node-create --workspace <ID> --name <名称> [--type <类型>]` | 支持 adoc/axls/able/appt/adraw/amind/folder；创建后读回 |
+ | 只有知识库名称时新建空文档 | `+wiki-new-doc --space <名称> --title <标题>` | 内部唯一解析空间；正文另走 Doc |
+ | 复制、移入知识库或移出到我的文档 | `+node-copy` / `+move` / `+move-to-drive` | 使用真实 nodeId/workspaceId/folderId；按 Runtime confirmation |
+ | 删除库内节点 | `+node-delete --workspace <ID> --node <ID>` | 删除前核对归属并确认 |
+ | 列出或修改知识库成员 | `+member-list` / `+member-add` / `+member-update` / `+member-remove` | userId 1-30 个；角色必须显式 |
+ | 查看知识库动态 | `+feed-list --workspace <ID>` | 要全部动态加 `--page-all`，否则只是一页 |
- ### SOP-3 建节点（create-node）
+ ## 当前最短路径
- **触发**：在知识库建文档/页面。
+ - 已知 workspaceId：直接执行 space/node/member/feed 目标命令，不再 resolve。
+ - 只有知识库名称：需要唯一 ID 用 `+resolve-space`；只需创建空 adoc 用 `+wiki-new-doc`；需要候选列表用 `+space-search`。
+ - 已知 nodeId/URL：元数据直接 `+node-get`；正文直接切 Doc，不先 list/search。
+ - 创建节点后返回的 nodeId 直接传给 Doc；不通过同名搜索重新定位。
+ - move/copy/delete 已含预检或读回时，不由 Agent 重复拼装原子命令。
+ - 普通“文档空间/我的文档”不先调用 Wiki 获取默认位置，按存储意图走 Drive。
- 1. **执行（必须）**：`dws wiki node create --workspace <workspaceId> --type adoc --name "<名称>" --format json`（按需 `--parent-id <父节点>`）；返回取 `nodeId`。
- 2. **写内容（必须）**：节点内容编辑切 `dingtalk-doc`，用 `dws doc update --node <nodeId> --mode overwrite|append --content-file <tmp.md> --yes`；写后 `doc read` 回读。
- 3. **验证（必须）**：`dws wiki node list --workspace <workspaceId> --format json` 复核节点已建。
+ ## 关键结果语义
- **禁止**：在 wiki 内直接拼内容（应切 doc 写）、建后不回读。
+ - `+space-list/+node-list/+feed-list` 默认单页；全量请求显式加 `--page-all`，并检查 `autoPageComplete/autoPageStopReason/pagesFetched` 与分页元数据。
+ - `+space-search/+node-search` 缺少业务数组不是零命中；只有显式空数组才可报告空结果。
+ - `+resolve-space` 只有 `resolved=true` 才提供唯一空间；多候选必须返回候选让用户消歧。
+ - 创建空间/节点和复制节点必须取得新 ID 并读回；移动必须验证 workspace/folder；删除必须有 `success=true`。
+ - 成员列表服务端没有续页游标且最多 50，不能把上限内结果宣称为全量；成员写只具备终态响应证据，不虚构精确读回。
+ - `partial_failure`、分页未完成或写入效果未知都不是成功。
- ### SOP-4 移动 / 复制 / 删节点（mutate-node）
+ ## 参数与安全边界
- **触发**：移动节点/复制节点/删节点。
+ - workspaceId、nodeId、folderId、userId 不互相替代；名称不能当 ID。
+ - 写操作只按精确 leaf Runtime 判定确认；已明确授权具体空间/节点/成员、动作与影响时，首次正式执行直接带 `--yes`，否则先确认。参数变化重新确认；禁止用缺少 `--yes` 的失败探测。
+ - `+member-list --limit` 为 1-50；成员写 `--users` 为 1-30 个，角色仅 `MANAGER|EDITOR|DOWNLOADER|READER`。
+ - `+node-create --type` 决定内容产品；建好后 adoc→Doc、axls→Sheet、able→AITable。
+ - Profile/组织在空间解析、节点操作和验证期间保持一致。
- 1. **执行（必须）**：移动 `dws wiki node move --workspace <workspaceId> --node <nodeId> --folder <目标文件夹nodeId> --format json`；复制 `dws wiki node copy --workspace <workspaceId> --node <nodeId> --folder <目标文件夹nodeId> --format json`；删除 `dws wiki node delete --workspace <workspaceId> --node <nodeId>`（**必须**先与用户确认，再加 `--yes`）。
- 2. **验证（必须）**：移动/复制后执行 `dws wiki node list --workspace <workspaceId> --folder <目标文件夹nodeId> --format json`，从真实返回确认目标节点；删除后回查确认节点已不存在或进入回收站。
+ ## 按需加载
- **禁止**：未确认就删除、编造 nodeId/folder、把 `--node-id` / `--target-parent-id` 当作公开参数。
+ Golden Route 参数足够时不读 reference；否则最多读取一个：
- ## 高频硬约束
+ | 触发条件 | Reference |
+ |---|---|
+ | 文档空间、知识库、Drive/Doc 边界不明 | [intent-guide](references/intent-guide.md) |
+ | 节点类型、复制、移动、移出或删除细节 | [node-ops](references/wiki-node-ops.md) |
+ | 成员角色、上限与验证语义 | [members](references/wiki-members.md) |
+ | 分页、空间、动态及低频错误 | [wiki reference](references/wiki.md) |
+ | 跨产品创建/写正文短流程 | [lite-recipes](references/lite-recipes.md) |
- - `space search` 用 `--query`，不要用 `--keyword`；组织知识库显式加 `--type orgWikiSpace`。
- - 用户说"我的文档/个人空间/my workspace"时必须用 `dws wiki space search --type myWikiSpace --format json`；该模式不需要 keyword。
- - 用户给空关键词时，不要构造空 `--query ""`；若语义是我的文档则用 `--type myWikiSpace`，否则请用户补关键词。
- - 搜到空间后复用返回的 `workspaceId/id`；空间内节点创建/列表/搜索用 `wiki node`，具体文档内容读写切到 `dingtalk-doc`，复制/移动切到 `dingtalk-drive`。
- - 所有 `dws wiki` 命令加 `--format json`。
+ ## 错误最短路径
- ## 跨产品协作
+ 1. 空响应、缺失集合、零/多候选或分页不完整：停止后续写入并返回证据，不把异常投影为空成功。
+ 2. workspace/node 归属不一致：停止，不尝试换一个 ID 或 profile。
+ 3. 写响应缺少新 ID 或 `success=true`：效果未知，按名称/ID定向回读，不盲目重放。
+ 4. `unknown flag` 只查当前 leaf Help；`unknown command` 只查一次 Wiki Shortcut 清单。
+ 5. 正文、普通存储或 Base 记录误路由时切回对应产品，不在 Wiki 内试探近似命令。
- - 知识库内具体文档读写 → 切到 `dingtalk-doc`
- - 普通钉盘文件存储及复制移动 → 切到 `dingtalk-drive`
- ## 局部意图与短流程
+ ## 跨产品边界
- - [局部意图消歧](references/intent-guide.md)；[短流程](references/lite-recipes.md)。
+ - 明确知识库容器、成员、库内层级与动态 → Wiki。
+ - 锁定库内 adoc 节点后的正文读写/导出 → Doc；axls 内容 → Sheet；able 记录/字段 → AITable。
+ - 普通文件、文件夹、“我的文档/文档空间”的存储搜索、传输和整理 → Drive。
+ - Wiki 节点移入/移出使用 `+move/+move-to-drive`；不要把 workspaceId 当普通 Drive folderId。