@comate/zulu 1.2.1-beta.1 → 1.3.0

package/comate-engine/assets/skills/ku-operator-comate/references/query_content.md

@@ -0,0 +1,83 @@
+# query-content — 查询文档内容
+
+查询知识库文档内容，自动转换为 Markdown 格式输出，并可自动下载文档中引用的图片和附件。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py query-content --doc-id <文档ID>
+python3 scripts/ku_operator.py query-content --url <文档URL>
+
+# 禁用自动下载资源
+python3 scripts/ku_operator.py query-content --doc-id <文档ID> --no-download-assets
+
+# 指定资源保存目录
+python3 scripts/ku_operator.py query-content --doc-id <文档ID> --save-assets-dir ./my_assets
+
+# 输出原始 JSON（含 blockId，用于 edit-content 操作）
+python3 scripts/ku_operator.py query-content --doc-id <文档ID> --raw-json
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 与 `--url` 二选一 | 文档 ID |
+| `--url` | 与 `--doc-id` 二选一 | 文档 URL |
+| `--save-assets-dir` | 否 | 图片/附件保存目录，默认 `./ku_assets` |
+| `--no-download-assets` | 否 | 禁用自动下载图片/附件（默认会自动下载） |
+| `--raw-json` | 否 | 输出原始 JSON block 结构（含 blockId），不转换为 Markdown |
+
+## 输出说明
+
+### 默认模式（Markdown 输出）
+
+- 直接输出 **Markdown 格式** 的文档内容（通过内部 jsonToMd 服务自动转换），可直接阅读
+- **自动资源下载**：脚本会自动提取 Markdown 中的远程图片和附件 URL，下载到本地 `{save-assets-dir}/{doc_id}/` 目录，并将 Markdown 中的远程 URL 替换为本地路径。下载摘要会输出到 stderr
+
+> **重要**：读取文档后，请关注 stderr 中输出的资源下载摘要。如果文档包含图片，这些图片已下载到本地，在分析文档时应结合图片内容（使用 Read 工具读取图片文件）进行理解，不要忽略图片中的信息。
+
+### --raw-json 模式
+
+- 输出文档内容的 **原始 JSON block 数组**，每个 block 包含 `blockId`、`type` 等完整字段
+- 不经过 jsonToMd 转换，不下载资源
+- 主要用于获取 `blockId` 以配合 `edit-content` 命令进行精确编辑（如表格替换、定点插入/删除）
+
+输出格式示例：
+
+```json
+[
+  {
+    "type": "heading",
+    "level": 2,
+    "blockId": "docyg-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "children": [{"text": "标题内容"}]
+  },
+  {
+    "type": "paragraph",
+    "blockId": "docyg-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+    "children": [{"text": "段落内容"}]
+  },
+  {
+    "type": "table",
+    "blockId": "docyg-zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
+    "data": {"headless": true, "width": [150, 150]},
+    "children": [...]
+  }
+]
+```
+
+## 使用示例
+
+### 通过 doc-id 查询
+
+```bash
+python3 scripts/ku_operator.py query-content --doc-id OQAehZAod_HVHC
+```
+
+### 通过完整 URL 查询
+
+```bash
+python3 scripts/ku_operator.py query-content \
+  --url "https://ku.baidu-int.com/knowledge/HFVrC2hT9H/pKzYIZbmZx/B8wSneaLSC/OQAehZAod_HVHC"
+```

package/comate-engine/assets/skills/ku-operator-comate/references/query_flowchart.md

@@ -0,0 +1,84 @@
+# query-flowchart — 查询流程图
+
+查询文档中嵌入的流程图数据。支持自动发现文档中的所有流程图，无需提前知道流程图 ID。
+
+## CLI 用法
+
+```bash
+# 自动发现文档中所有流程图并查询（推荐）
+python3 scripts/ku_operator.py query-flowchart --doc-id <文档ID>
+
+# 指定流程图 ID 查询
+python3 scripts/ku_operator.py query-flowchart --doc-id <文档ID> --flowchart-id <流程图ID>
+
+# 保存到文件
+python3 scripts/ku_operator.py query-flowchart --doc-id <文档ID> --output out.xml
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 文档 ID |
+| `--flowchart-id` | 否 | 流程图 ID。不传时自动调用 queryContent 从文档正文中发现所有 `type=diagram` 的节点并逐一查询 |
+| `--output` | 否 | 输出文件路径。多个流程图时自动添加序号后缀（如 `out_1.xml`、`out_2.xml`） |
+
+## 自动发现机制
+
+当 `--flowchart-id` 未指定时，脚本会：
+
+1. 调用 `queryContent` API 获取文档正文的 block 列表
+2. 筛选 `type=diagram` 的 block，提取其 `id` 字段作为流程图 ID
+3. 逐一调用 `queryFlowchart` API 查询每个流程图的数据
+4. 输出 agent 友好的结构化结果
+
+## 输出说明
+
+输出包含以下信息：
+
+- **流程图元信息**：文档 ID、流程图 ID、格式
+- **节点列表**：每个节点的 ID、形状类型（菱形=判断、矩形=处理、椭圆=开始/结束等）、文字内容
+- **连线列表**：每条连线的源节点、目标节点、标签
+- **原始 XML**：mxGraph 格式的完整流程图数据
+
+## 使用示例
+
+### 自动发现并查询所有流程图（推荐）
+
+```bash
+python3 scripts/ku_operator.py query-flowchart \
+  --doc-id D5JiZRULjdEJHR
+```
+
+输出示例：
+```
+## 流程图 #1
+- 文档 ID: D5JiZRULjdEJHR
+- 流程图 ID: 5282101654e6424c9c6d8e483c856afc
+- 格式: mxGraph XML
+
+### 节点 (2 个)
+  - [2] diamond (判断): 条件判断
+  - [3] process (处理): 执行任务
+### 连线 (1 个)
+  - [4] 2 → 3 (是)
+
+### 原始 XML
+...
+```
+
+### 指定流程图 ID 查询
+
+```bash
+python3 scripts/ku_operator.py query-flowchart \
+  --doc-id D5JiZRULjdEJHR \
+  --flowchart-id 5282101654e6424c9c6d8e483c856afc
+```
+
+### 保存到文件
+
+```bash
+python3 scripts/ku_operator.py query-flowchart \
+  --doc-id D5JiZRULjdEJHR \
+  --output flowchart.xml
+```

package/comate-engine/assets/skills/ku-operator-comate/references/query_permission.md

@@ -0,0 +1,38 @@
+# query-permission — 查询文档权限
+
+查询指定用户对某文档的权限信息。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py query-permission --doc-id <文档ID> --usernames <用户名列表>
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 文档 ID |
+| `--usernames` | 是 | 用户名，多个用逗号分隔（如 `user1,user2`） |
+
+## 输出说明
+
+返回 JSON 格式结果，包含每个用户对该文档的权限角色信息。
+
+## 使用示例
+
+### 查询单个用户权限
+
+```bash
+python3 scripts/ku_operator.py query-permission \
+  --doc-id OQAehZAod_HVHC \
+  --usernames zhangsan
+```
+
+### 查询多个用户权限
+
+```bash
+python3 scripts/ku_operator.py query-permission \
+  --doc-id OQAehZAod_HVHC \
+  --usernames zhangsan,lisi,wangwu
+```

package/comate-engine/assets/skills/ku-operator-comate/references/query_recent_view.md

@@ -0,0 +1,67 @@
+# query-recent-view — 查询文档浏览记录
+
+查询指定文档的最近浏览记录，输出格式化文本。可按时间范围过滤，支持分页。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py query-recent-view --doc-id <文档ID> [--begin-time TIME] [--end-time TIME] [--page N] [--page-size N] [--raw-json]
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 文档 ID |
+| `--begin-time` | 否 | 起始时间，支持格式：`YYYY-MM-DD`、`YYYY-MM-DD HH:MM`、`YYYY-MM-DD HH:MM:SS` |
+| `--end-time` | 否 | 结束时间，格式同上 |
+| `--page` | 否 | 页码，默认 1 |
+| `--page-size` | 否 | 每页条数，默认 100 |
+| `--raw-json` | 否 | 输出原始 JSON（不做格式化） |
+
+## 输出说明
+
+默认输出格式化文本，包含浏览统计和记录列表：
+
+```
+文档 D5JiZRULjdEJHR 浏览记录（共 24 次，3 位访客）
+
+- 王哲 (wangzhe12) · 2026-03-20 18:00
+- 张三 (zhangsan) · 2026-03-20 17:30
+- 李四 (lisi) · 2026-03-20 16:00
+```
+
+传 `--raw-json` 时输出原始 API 响应 JSON。
+
+## 使用示例
+
+### 查询最近浏览
+
+```bash
+python3 scripts/ku_operator.py query-recent-view \
+  --doc-id D5JiZRULjdEJHR
+```
+
+### 按时间范围查询
+
+```bash
+python3 scripts/ku_operator.py query-recent-view \
+  --doc-id D5JiZRULjdEJHR \
+  --begin-time "2026-03-20" \
+  --end-time "2026-03-21"
+```
+
+```bash
+python3 scripts/ku_operator.py query-recent-view \
+  --doc-id D5JiZRULjdEJHR \
+  --begin-time "2026-03-20 09:00" \
+  --end-time "2026-03-20 18:00"
+```
+
+### 输出原始 JSON
+
+```bash
+python3 scripts/ku_operator.py query-recent-view \
+  --doc-id D5JiZRULjdEJHR \
+  --raw-json
+```

package/comate-engine/assets/skills/ku-operator-comate/references/query_repo.md

@@ -0,0 +1,57 @@
+# query-repo — 查询知识库目录
+
+查询知识库的目录结构，以文本树形格式输出，支持分页。
+
+## CLI 用法
+
+```bash
+# 查询根目录（默认行为）
+python3 scripts/ku_operator.py query-repo --repo-guid <知识库ID>
+
+# 查询某个目录下的直接子文档
+python3 scripts/ku_operator.py query-repo --repo-guid <知识库ID> --parent-doc-guid <父文档ID>
+
+# 大目录翻页
+python3 scripts/ku_operator.py query-repo --repo-guid <知识库ID> --page 2
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--repo-guid` | 是 | 知识库 ID |
+| `--parent-doc-guid` | 否 | 父文档 ID，不传则默认查询**根目录**下的直接子文档 |
+| `--page` | 否 | 页码，默认 1（每页固定 100 条） |
+
+## 输出说明
+
+以文本树形格式输出，示例：
+
+```
+知识库 Xw0t0FBvVy 根目录（共 3 项）：
+
+📄 欢迎使用 (GgD6PTVjSmZEC3)
+📁 浏览器相关 (gsrJkBZ6XlyGRl) [2 子文档]
+📄 接口说明 (vtUh01DEnyYDA6)
+```
+
+- `📁` 表示有子文档（可通过其 docGuid 作为 `--parent-doc-guid` 进一步展开查看）
+- `📄` 表示叶子文档
+- 括号内为 `docGuid`，可直接用于后续的 `query-content`、`create-doc`、`move-doc` 等操作
+- 当目录内容超过一页时，末尾会提示使用 `--page` 翻页
+
+## 使用示例
+
+### 查询根目录
+
+```bash
+python3 scripts/ku_operator.py query-repo --repo-guid Xw0t0FBvVy
+```
+
+### 展开子目录
+
+```bash
+python3 scripts/ku_operator.py query-repo \
+  --repo-guid Xw0t0FBvVy \
+  --parent-doc-guid gsrJkBZ6XlyGRl
+```

package/comate-engine/assets/skills/ku-operator-comate/references/query_user_info.md

@@ -0,0 +1,37 @@
+# query-user-info — 查询当前用户信息
+
+查询当前登录用户的知识库信息，包括个人知识库 ID 和 URL。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py query-user-info
+```
+
+## 参数表
+
+无需任何参数，用户名自动从环境变量 `COMATE_USERNAME` 读取。
+
+## 输出说明
+
+以 JSON 格式输出当前用户的关键信息，示例：
+
+```json
+{
+  "username": "wangzhe12",
+  "nickname": "王哲",
+  "email": "wangzhe12@baidu.com",
+  "personalRepoGuid": "yxin2LKp-R",
+  "personalRepoUrl": "https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/pKzJfZczuc/yxin2LKp-R"
+}
+```
+
+返回结果关键字段：
+- `personalRepoGuid` — 个人知识库 ID，可直接用于 `--repo-guid` 参数
+- `personalRepoUrl` — 个人知识库 URL
+
+## 使用示例
+
+```bash
+python3 scripts/ku_operator.py query-user-info
+```

package/comate-engine/assets/skills/ku-operator-comate/references/update_member.md

@@ -0,0 +1,41 @@
+# update-member — 更新文档成员角色
+
+更新文档中已有成员的角色。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py update-member --doc-id <文档ID> --username <用户名> --role <新角色>
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 文档 ID |
+| `--username` | 是 | 用户名（单个） |
+| `--role` | 是 | 新角色，可选 `DocReader` / `DocEditor`（或 `DocMember`） / `DocAdmin`。`DocEditor` 会自动映射为 API 实际值 `DocMember` |
+
+## 输出说明
+
+返回 JSON 格式结果，操作成功时返回 JSON 中不包含 `error` 字段。
+
+## 使用示例
+
+### 将成员升级为编辑者
+
+```bash
+python3 scripts/ku_operator.py update-member \
+  --doc-id OQAehZAod_HVHC \
+  --username zhangsan \
+  --role DocEditor
+```
+
+### 将成员降级为只读
+
+```bash
+python3 scripts/ku_operator.py update-member \
+  --doc-id OQAehZAod_HVHC \
+  --username zhangsan \
+  --role DocReader
+```

package/comate-engine/assets/skills/ku-operator-comate/references/upload_attachment.md

@@ -0,0 +1,52 @@
+# upload-attachment — 上传附件并插入文档正文
+
+上传本地文件作为附件到指定文档，默认自动插入文档正文。使用 multipart/form-data 方式上传，超时时间 120 秒。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py upload-attachment --doc-id <文档ID> --file <本地文件路径> [--no-insert] [--view-type attachment|preview]
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 文档 ID |
+| `--file` | 是 | 本地文件路径 |
+| `--no-insert` | 否 | 只上传不插入正文 |
+| `--view-type` | 否 | 显示方式：`attachment`=附件卡片（默认）, `preview`=内嵌预览 |
+
+## 输出说明
+
+返回 JSON 格式结果，包含上传成功后的附件信息（attachId、name、extension、size 等）。上传成功后默认自动调用 edit-content 将附件 block 插入文档末尾。
+
+> 上传超时时间为 120 秒，适合大文件上传。
+
+## 使用示例
+
+### 上传 PDF 并自动插入正文
+
+```bash
+python3 scripts/ku_operator.py upload-attachment \
+  --doc-id OQAehZAod_HVHC \
+  --file ./report.pdf
+```
+
+### 只上传不插入正文
+
+```bash
+python3 scripts/ku_operator.py upload-attachment \
+  --doc-id OQAehZAod_HVHC \
+  --file ./data.xlsx \
+  --no-insert
+```
+
+### 以内嵌预览方式插入
+
+```bash
+python3 scripts/ku_operator.py upload-attachment \
+  --doc-id OQAehZAod_HVHC \
+  --file ./screenshot.png \
+  --view-type preview
+```