first commit
This commit is contained in:
@@ -0,0 +1,14 @@
|
||||
# wiki 局部意图消歧
|
||||
|
||||
本文件从单 Skill `intent-guide.md` 拆分而来，仅保留与本产品相关的跨产品消歧规则。
|
||||
|
||||
| 用户说... | 真实意图 | 应该用 | 不要用 | 理由 |
|
||||
|---|---|---|---|---|
|
||||
| "帮我看看知识库里的文件" | 知识库节点列表 | `dws wiki +node-list --workspace <ID>` | `dws drive +list` | 明确“知识库”上下文，使用 Wiki 层级 |
|
||||
| "浏览已知钉盘/文档空间目录" | 普通存储目录 | `dws drive +list` | `dws wiki +node-list` | 已有 space/folder 目标，文件层级属于 Drive |
|
||||
| "列出/发现钉盘企业空间或我的文件空间" | Drive 存储空间发现 | `dws wiki space list --type orgSpace|mySpace`，取 spaceId/rootFolderId 后回 Drive | `dws wiki +space-list --type orgWikiSpace|myWikiSpace` | managed Wiki leaf 兼容存储空间发现；Drive ID 不能当 workspaceId |
|
||||
| "列出组织知识库" | 列出组织知识库容器 | `dws wiki +space-list --type orgWikiSpace --page-all` | `dws drive +list` | 明确知识库容器，使用当前 Wiki 类型枚举 |
|
||||
| "在知识库里搜方案" | 空间内搜索 | `dws wiki +node-search --workspace <ID> --query <词>` | `dws drive +search` | 指定知识库上下文，使用 Wiki 节点搜索 |
|
||||
| "搜一下有没有叫XX的文件" | 全局搜索 | `dws drive +search --query <词>` | `dws wiki +node-search` | 未指定知识库，使用 Drive 全局聚合搜索 |
|
||||
| "在知识库里创建一个文档" | 创建空文件实体 | `dws wiki +node-create --workspace <ID> --name <名称> --type adoc` | `dws doc create` | 空间内创建节点归 Wiki；正文写入才切 Doc |
|
||||
| "整理一下XX项目的所有讨论" | 跨源主题归档 | #5 generate-topic-report | #4 write-doc | #4 侧重单篇文档创作；按主题跨听记/群消息汇总属于工作汇报 |
|
||||
@@ -0,0 +1,44 @@
|
||||
# wiki Lite Recipe
|
||||
|
||||
本文件从单 Skill `lite-recipes.md` 拆分而来，仅保留与本产品相关的轻量流程。
|
||||
|
||||
## #4 文档知识
|
||||
|
||||
### query-doc
|
||||
|
||||
1. 全局搜索：`drive search --query "<关键词>"` → `nodeId`（聚合钉盘+文档空间）
|
||||
2. 空间内搜索：`wiki node search --workspace <WS_ID> --query "<关键词>"` → `nodeId`
|
||||
3. `doc read --node <nodeId>`（按需；大文档只抽章节）
|
||||
|
||||
### list-folder-docs
|
||||
|
||||
`drive list --workspace <WS_ID>` 或 `wiki node list --workspace <WS_ID>`
|
||||
|
||||
### import-file
|
||||
|
||||
将本地文件导入为钉钉在线文档。**一条命令完成上传+格式转换+创建**，无需先读取文件内容。
|
||||
|
||||
```bash
|
||||
dws doc import --file ./report.docx --format json
|
||||
```
|
||||
|
||||
1. 确认文件路径（用户提供的本地文件路径）
|
||||
2. 执行：`dws doc import --file <文件路径> --format json`（可选 `--folder <文件夹ID>` / `--workspace <知识库ID>` / `--name "文档名"`）
|
||||
3. 从返回中提取 `documentUrl`，告知用户导入完成并提供链接
|
||||
4. 超时或中断时 CLI 返回 `taskId`，用 `dws doc import get --task-id <taskId> --format json` 手动查询
|
||||
|
||||
**`--folder` 参数传值规则**：
|
||||
- 首选路径：用户提供 alidocs URL 时，直接将完整 URL 传入 `--folder`，无需先调 `drive info`
|
||||
- 预检路径：若需确认 URL 指向的是文件夹，可先调 `dws drive info --node <URL>`：
|
||||
- `nodeType == "folder"` → 使用 `nodeId` 或原始 URL 作为 `--folder` 值
|
||||
- `nodeType` 不是 folder → 提示用户：该链接指向的不是文件夹
|
||||
- 禁止：不得使用 `drive info` 返回的 `folderId` 字段作为 `--folder` 的值（`folderId` 是父文件夹 ID，非当前节点 ID）
|
||||
|
||||
格式与文档类型映射：
|
||||
- `.docx` / `.doc` → 文字文档（DOC）
|
||||
- `.xlsx` / `.xls` → 电子表格（SHEET）
|
||||
- `.xmind` / `.mark` → 脑图（MIND）
|
||||
- `.md` / `.txt` → 文字文档（DOC）
|
||||
|
||||
> **禁止先 Read 文件再 `doc create` + `doc update`**。`doc import` 是服务端格式转换，客户端无需解析文件内容。
|
||||
> 详见 [./doc/doc-import.md](../../dingtalk-doc/references/doc/doc-import.md)。
|
||||
@@ -0,0 +1,32 @@
|
||||
# Wiki 成员管理
|
||||
|
||||
## 入口
|
||||
|
||||
```bash
|
||||
dws wiki +member-list --workspace <workspaceId> --limit 30 --format json
|
||||
dws wiki +member-add --workspace <workspaceId> --users <userId> --role READER --format json
|
||||
dws wiki +member-update --workspace <workspaceId> --users <userId> --role EDITOR --format json
|
||||
dws wiki +member-remove --workspace <workspaceId> --users <userId> --format json
|
||||
```
|
||||
|
||||
- `--users` 接受 1-30 个真实 userId；姓名先由联系人/人员搜索产品解析，不能直接当 userId。
|
||||
- 角色仅 `MANAGER|EDITOR|DOWNLOADER|READER`，修改前必须由用户明确角色。
|
||||
- workspaceId 来自当前 profile 下真实知识库；不能跨组织复用。
|
||||
- 成员接口仅用于组织知识库。`myWikiSpace` 是个人空间，不支持容器级成员管理；若用户只想分享其中某个节点，改走 Drive 节点级权限。
|
||||
- `OWNER` 不在成员角色枚举中，不能通过 add/update/remove 创建、降级或移除所有者；所有权变更必须走对应所有者转移能力并遵守其独立确认约束。
|
||||
- 调用者需要知识库 OWNER 或 MANAGER 权限；权限不足时如实返回，不切账号或改用节点权限绕过容器规则。
|
||||
|
||||
## 列表完整性
|
||||
|
||||
成员列表服务端单次上限为 50（`--limit` / pageSize 最大 50）。快捷命令 `+member-list` 适合单页列表，但**不支持游标翻页**；超过 50 人必须改用原生 `dws wiki member list` 的 `--next-token` 翻页：首次调用不传，后续把上一次响应中的 `nextToken` 传入 `--next-token`，直到 `hasMore` 为 false。出参 `totalCount` 为全量成员总数，可用于核对是否拉全。不要伪造 `--page-all` 或不断提高 limit 超过 50。
|
||||
|
||||
```bash
|
||||
dws wiki member list --workspace <workspaceId> --limit 50 --format json
|
||||
dws wiki member list --workspace <workspaceId> --next-token <上次返回的 nextToken> --format json
|
||||
```
|
||||
|
||||
## 写入验证
|
||||
|
||||
成员 add/update/remove 当前只能以写接口 `success=true` 作为终态证据，并显式返回 `verification.status=terminal_response_only`；成员列表受上限限制，不能被包装成精确读回验证。
|
||||
|
||||
若 add/update 写响应丢失，先用 `dws wiki +member-list --workspace <workspaceId> --filter-role <MANAGER|EDITOR|DOWNLOADER|READER> --limit 50 --format json` 做有限核对；remove 按写前已知的原角色过滤，原角色不确定时省略 `--filter-role`。成员列表仍不能证明完整结果；无法证明时报告未知效果，不自动重放批量成员写入。
|
||||
@@ -0,0 +1,45 @@
|
||||
# Wiki 节点操作
|
||||
|
||||
## 创建与内容交接
|
||||
|
||||
```bash
|
||||
dws wiki +node-create --workspace <workspaceId> --name "新文档" --type adoc --format json
|
||||
```
|
||||
|
||||
`--type` 可用 `adoc|axls|able|appt|adraw|amind|folder`，父目录加 `--folder <nodeId>`。创建成功从结果取新 nodeId，并按类型交给 Doc/Sheet/AITable；不要靠同名搜索重新定位。
|
||||
|
||||
只有空间名称时，先明确组织/个人范围，用 `+space-list --type <orgWikiSpace|myWikiSpace> --limit 50 --page-all` 取完并按完整名称唯一匹配；再将真实 workspaceId 传给 `+node-create`。当前不要用 `+wiki-new-doc` 直接写入，因为其内部名称搜索不暴露分页完成证据。正文仍切 Doc。
|
||||
|
||||
## 读取、搜索与列表
|
||||
|
||||
- 已知 nodeId/URL：`+node-get --node <值>`。
|
||||
- 浏览目录：`+node-list --workspace <ID> [--folder <ID>]`；全量加 `--page-all`。
|
||||
- 关键词检索：`+node-search --workspace <ID> --query <词>`；不拿 list 代替 search。
|
||||
|
||||
## 复制与移动
|
||||
|
||||
```bash
|
||||
dws wiki +node-copy --workspace <目标库ID> --node <源nodeId> [--folder <目标folderId>]
|
||||
dws wiki +move --workspace <目标库ID> --node <nodeId> [--folder <目标folderId>]
|
||||
dws wiki +move-to-drive --node <nodeId> [--folder <我的文档folderId>]
|
||||
```
|
||||
|
||||
- copy 产生新 nodeId，必须读回副本；源 ID 不能当新 ID。
|
||||
- move 保持 nodeId，但必须验证目标 workspace/folder。
|
||||
- move-to-drive 必须验证 workspace 已改变；workspaceId 不能当普通 folderId。
|
||||
- 这些命令按 Runtime confirmation 执行；dry-run 与正式执行使用同一目标。
|
||||
|
||||
## 删除
|
||||
|
||||
```bash
|
||||
dws wiki +node-delete --workspace <workspaceId> --node <nodeId>
|
||||
```
|
||||
|
||||
删除前读取节点并核对其 workspace；不匹配立即停止。确认后只接受 `success=true`，不因列表暂时未刷新而重复删除。
|
||||
|
||||
## 恢复原则
|
||||
|
||||
- create/copy 缺少新 ID：提交效果未知，先按目标库和精确名称定向查询。
|
||||
- move 响应异常：按原 nodeId 读回 workspace/folder 决定终态。
|
||||
- delete 响应异常：检查节点详情或回收状态；不能盲重放。
|
||||
- 读回与请求不一致时返回结构化失败并保留真实目标信息。
|
||||
@@ -0,0 +1,65 @@
|
||||
# Wiki 空间、分页与动态参考
|
||||
|
||||
只在根 Skill 的 Golden Route 不足时读取相关章节。节点写操作和成员管理分别读取对应 operation reference。
|
||||
|
||||
## 空间定位
|
||||
|
||||
| 已知条件 | 入口 |
|
||||
|---|---|
|
||||
| 精确 workspaceId 或知识库 URL | `+space-get --workspace <值>` |
|
||||
| 名称且必须得到唯一 ID | `+space-list --type <orgWikiSpace\|myWikiSpace> --limit 50 --page-all` 后按完整名称精确匹配 |
|
||||
| 关键词且需要浏览候选 | `+space-search --query <关键词>` |
|
||||
| 明确要列出组织/个人知识库 | `+space-list --type orgWikiSpace|myWikiSpace` |
|
||||
|
||||
名称解析前先明确组织知识库还是个人知识库；范围未知时向用户消歧。只有 `+space-list` 返回 `autoPageComplete=true`，并且完整结果中恰好一个名称精确相等的空间时，才可把其 workspaceId 交给后续写操作。0 条、多条、分页未完成都停止，不选择第一项。
|
||||
|
||||
`+space-search` 用于候选发现，但当前没有可执行的续页 flag；`+resolve-space` 和 `+wiki-new-doc` 的内部名称搜索也不暴露分页完成证据。因此这三个入口的单页结果都不能证明全局唯一，当前不用于写入前的权威身份解析。空关键词不能构造 `--query ""`。
|
||||
|
||||
## Runtime 确认与首次执行
|
||||
|
||||
- 先唯一解析 workspace、node、目标父节点或成员，再以精确 leaf Schema 和 Runtime gate 判断是否需要确认；不要通过一次缺少 `--yes` 的失败调用探测确认要求。
|
||||
- Runtime 要求确认且当前请求已明确授权具体空间/节点/成员、动作、目标位置或角色及影响时，首次正式远端写调用直接追加 `--yes`。只有“整理知识库”“调整成员”等宽泛意图时必须先补齐范围。
|
||||
- Runtime 不要求确认时不添加 `--yes`。需要询问时，确认后必须保持同一 profile、对象、动作、范围和关键参数；移动目标、成员列表、角色或其他影响范围变化时重新确认。
|
||||
- 只读定位和检查不加 `--yes`。收到 `confirmation_required` 仅表示尚未通过预执行门禁，不代表业务写入成功，也不能据此盲目重放。
|
||||
|
||||
## 全量分页
|
||||
|
||||
`+space-list`、`+node-list`、`+feed-list` 支持自动翻页：
|
||||
|
||||
```bash
|
||||
dws wiki +space-list --page-all --page-limit 20 --format json
|
||||
dws wiki +space-list --type orgWikiSpace --limit 50 --page-all --format json
|
||||
dws wiki +node-list --workspace <ID> --page-all --max-items 500 --format json
|
||||
dws wiki +feed-list --workspace <ID> --page-all --format json
|
||||
```
|
||||
|
||||
- `--page-all` 才启用自动翻页；`--page-limit/--max-items/--page-delay` 不能单独使用。
|
||||
- `autoPageComplete=true` 且 endpoint exhausted 才表示端点取完；达到 page/items 上限必须保留 continuation/stop reason。
|
||||
- 游标缺失、停滞、循环或后续页失败均不能返回“全部”。
|
||||
- `+node-search` 当前保留服务端单页 cursor；需要续页时使用真实 `nextCursor`，不手工猜 token。
|
||||
|
||||
## 空间创建与删除
|
||||
|
||||
```bash
|
||||
dws wiki +space-create --name "产品文档库" --desc "团队资料" --format json
|
||||
dws wiki +delete-space --workspace <workspaceId> --format json
|
||||
```
|
||||
|
||||
- 名称最多 32 字符，描述最多 500 字符；本地校验失败不能产生远端调用。
|
||||
- 创建必须返回 workspaceId，并通过 `get_wikiSpace` 读回同一 ID。
|
||||
- 删除整个知识库前先读取目标，经 Runtime 确认后只接受 `success=true`。
|
||||
|
||||
## 知识库动态
|
||||
|
||||
```bash
|
||||
dws wiki +feed-list --workspace <workspaceId> --limit 20 --format json
|
||||
```
|
||||
|
||||
动态用于回答“谁在何时创建、更新或评论了什么”。需要排除普通文件时加 `--exclude-file`；需要完整范围时加 `--page-all`。节点正文或历史版本不从 feed 推断，锁定 nodeId 后切 Doc。
|
||||
|
||||
## 响应与错误
|
||||
|
||||
- 空响应、`success=false`、畸形 wrapper、缺失业务数组都属于失败，不是零条数据。
|
||||
- 集合结果检查 `count` 与对应 `spaces/nodes/feeds`；分页检查 `nextCursor/hasMore` 及 meta.pagination。
|
||||
- 读写始终保持同一 profile。权限失败不能通过切换账号或退回 Drive 猜测解决。
|
||||
- 写入提交后连接中断时先用返回/已知 ID 读取；无法证明是否提交则报告未知效果，不自动重试非幂等创建。
|
||||
Reference in New Issue
Block a user