@comate/zulu 1.2.1-beta.2 → 1.3.0

package/comate-engine/assets/skills/ku-operator-comate/examples.md

@@ -0,0 +1,190 @@
+# ku-operator 参考示例
+
+> 以下示例展示了各子命令的典型用法，供 agent 调用时参考。
+> 所有命令在 `ku-operator/` 目录下运行。
+
+---
+
+## 一、query-content（查询文档内容）
+
+### 通过 doc-id 查询
+
+```bash
+python3 scripts/ku_operator.py query-content --doc-id OQAehZAod_HVHC
+```
+
+输出 Markdown 格式的文档正文，可直接阅读。
+
+### 通过完整 URL 查询
+
+```bash
+python3 scripts/ku_operator.py query-content \
+  --url "https://ku.baidu-int.com/knowledge/HFVrC2hT9H/pKzYIZbmZx/B8wSneaLSC/OQAehZAod_HVHC"
+```
+
+效果同上，适用于用户直接给出链接的场景。
+
+---
+
+## 二、query-repo（查询知识库目录）
+
+### 查询根目录
+
+```bash
+python3 scripts/ku_operator.py query-repo --repo-guid Xw0t0FBvVy
+```
+
+示例输出：
+
+```
+知识库 Xw0t0FBvVy 根目录（共 3 项）：
+
+📄 欢迎使用 (GgD6PTVjSmZEC3)
+📁 浏览器相关 (gsrJkBZ6XlyGRl) [2 子文档]
+📄 接口说明 (vtUh01DEnyYDA6)
+```
+
+### 展开子目录
+
+看到 📁 图标表示该文档下有子文档，用其 docGuid 作为 `--parent-doc-guid` 继续展开：
+
+```bash
+python3 scripts/ku_operator.py query-repo \
+  --repo-guid Xw0t0FBvVy \
+  --parent-doc-guid gsrJkBZ6XlyGRl
+```
+
+### 大目录翻页
+
+当目录内容超过 100 项时，末尾会提示翻页：
+
+```bash
+python3 scripts/ku_operator.py query-repo --repo-guid Xw0t0FBvVy --page 2
+```
+
+---
+
+## 三、create-doc（新建文档）
+
+### 创建空文档
+
+```bash
+python3 scripts/ku_operator.py create-doc \
+  --repo-guid B8wSneaLSC \
+  --title "会议纪要-2026-02-09"
+```
+
+返回新文档的 `docGuid` 和 `url`。
+
+### 从本地文件创建带内容的文档
+
+先将内容写入本地 `.md` 文件，再通过 `--content-file` 传入：
+
+```bash
+python3 scripts/ku_operator.py create-doc \
+  --repo-guid B8wSneaLSC \
+  --title "接口说明" \
+  --content-file ./接口说明.md
+```
+
+### 在指定目录下创建文档
+
+```bash
+python3 scripts/ku_operator.py create-doc \
+  --repo-guid B8wSneaLSC \
+  --title "子文档" \
+  --parent-doc-guid OQAehZAod_HVHC
+```
+
+---
+
+## 四、move-doc（移动文档）
+
+### 移动到知识库根目录
+
+```bash
+python3 scripts/ku_operator.py move-doc \
+  --doc-id ABC123 \
+  --to-repo-guid B8wSneaLSC
+```
+
+### 移动到指定目录下
+
+```bash
+python3 scripts/ku_operator.py move-doc \
+  --doc-id ABC123 \
+  --to-repo-guid B8wSneaLSC \
+  --to-parent-guid XYZ789
+```
+
+---
+
+## 五、delete-doc（删除文档）
+
+### 删除指定文档
+
+```bash
+python3 scripts/ku_operator.py delete-doc --doc-id ABC123
+```
+
+> 删除操作不可恢复，执行前请确认目标文档无误。
+
+---
+
+## 六、典型组合流程
+
+### 流程1：用户给了一个文档 URL，要求分析内容
+
+```bash
+# 1. 读取文档内容
+python3 scripts/ku_operator.py query-content \
+  --url "https://ku.baidu-int.com/knowledge/HFVrC2hT9H/pKzYIZbmZx/B8wSneaLSC/OQAehZAod_HVHC"
+
+# 2. 检查该文档是否有子文档（文档即目录）
+#    从 URL 解析：repoGuid=B8wSneaLSC，docGuid=OQAehZAod_HVHC
+python3 scripts/ku_operator.py query-repo \
+  --repo-guid B8wSneaLSC \
+  --parent-doc-guid OQAehZAod_HVHC
+
+# 3. 如果有子文档，按需读取子文档内容进行分析
+python3 scripts/ku_operator.py query-content --doc-id <子文档docGuid>
+```
+
+### 流程2：用户给了一个知识库 URL（3 段路径），要求了解结构
+
+```bash
+# URL 只有 3 段：https://ku.baidu-int.com/knowledge/HFVrC2hT9H/pKzYIZbmZx/B8wSneaLSC
+# 这是一个知识库链接，repoGuid=B8wSneaLSC
+
+# 1. 查看根目录结构
+python3 scripts/ku_operator.py query-repo --repo-guid B8wSneaLSC
+
+# 2. 对感兴趣的目录（📁）逐层展开
+python3 scripts/ku_operator.py query-repo \
+  --repo-guid B8wSneaLSC \
+  --parent-doc-guid <目标目录docGuid>
+```
+
+### 流程3：创建文档 → 验证 → 移动
+
+```bash
+# 1. 在根目录创建文档
+python3 scripts/ku_operator.py create-doc \
+  --repo-guid B8wSneaLSC \
+  --title "待归档文档"
+# 记录返回的 docGuid
+
+# 2. 确认文档已创建
+python3 scripts/ku_operator.py query-repo --repo-guid B8wSneaLSC
+
+# 3. 移动到目标目录
+python3 scripts/ku_operator.py move-doc \
+  --doc-id <步骤1返回的docGuid> \
+  --to-repo-guid B8wSneaLSC \
+  --to-parent-guid <目标目录ID>
+
+# 4. 确认文档已移动到位
+python3 scripts/ku_operator.py query-repo \
+  --repo-guid B8wSneaLSC \
+  --parent-doc-guid <目标目录ID>
+```

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

@@ -0,0 +1,49 @@
+# add-member — 添加文档成员
+
+为指定文档添加一个或多个成员，并设置其角色。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py add-member --doc-id <文档ID> --usernames <用户名列表> [--role <角色>]
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 文档 ID |
+| `--usernames` | 是 | 用户名，多个用逗号分隔（如 `user1,user2`） |
+| `--role` | 否 | 角色，可选 `DocReader` / `DocEditor`（或 `DocMember`） / `DocAdmin`，默认 `DocReader`。`DocEditor` 会自动映射为 API 实际值 `DocMember` |
+
+## 输出说明
+
+返回 JSON 格式结果，操作成功时返回 JSON 中不包含 `error` 字段。
+
+## 使用示例
+
+### 添加单个只读成员
+
+```bash
+python3 scripts/ku_operator.py add-member \
+  --doc-id OQAehZAod_HVHC \
+  --usernames zhangsan
+```
+
+### 添加多个编辑成员
+
+```bash
+python3 scripts/ku_operator.py add-member \
+  --doc-id OQAehZAod_HVHC \
+  --usernames zhangsan,lisi,wangwu \
+  --role DocEditor
+```
+
+### 添加管理员
+
+```bash
+python3 scripts/ku_operator.py add-member \
+  --doc-id OQAehZAod_HVHC \
+  --usernames admin_user \
+  --role DocAdmin
+```

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

@@ -0,0 +1,38 @@
+# change-scope — 修改文档公开范围
+
+修改指定文档的公开/私密范围。需要环境变量 `COMATE_USERNAME` 作为操作者身份。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py change-scope --doc-id <文档ID> --scope <范围值>
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 文档 ID |
+| `--scope` | 是 | 公开范围：`5`=公开可读, `6`=公开可编辑, `20`=私密 |
+
+## 输出说明
+
+返回 JSON 格式结果，包含操作状态。
+
+## 使用示例
+
+### 设为公开可读
+
+```bash
+python3 scripts/ku_operator.py change-scope \
+  --doc-id OQAehZAod_HVHC \
+  --scope 5
+```
+
+### 设为私密
+
+```bash
+python3 scripts/ku_operator.py change-scope \
+  --doc-id OQAehZAod_HVHC \
+  --scope 20
+```

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

@@ -0,0 +1,50 @@
+# copy-doc — 复制文档
+
+在指定目录复制出一篇文档的副本。支持跨知识库复制和自定义新标题。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py copy-doc --doc-id <源文档ID> [--to-repo-guid <目标知识库ID>] [--to-parent-guid <目标父目录ID>] [--new-title "新标题"]
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 待复制的源文档 ID |
+| `--to-repo-guid` | 否 | 目标知识库 ID，不传则复制到源文档所在知识库 |
+| `--to-parent-guid` | 否 | 目标父目录 ID。不传则与源文档同级；`00000000000000` 表示知识库根目录；不能复制到源文档的下级目录 |
+| `--new-title` | 否 | 新文档标题，不传则为原标题 + "的复制" |
+
+## 前置条件
+
+- 数字员工需有源文档的**管理员**权限
+- 数字员工需有目标位置的**创建**权限
+- 操作者用户名自动从环境变量 `COMATE_USERNAME` 读取
+
+## 输出说明
+
+返回 JSON 格式结果，关键字段：
+- `docInfo.docGuid` — 新文档 ID
+- `docInfo.url` — 新文档访问 URL
+- `docInfo.name` — 新文档标题
+
+## 使用示例
+
+### 在同知识库同目录复制文档
+
+```bash
+python3 scripts/ku_operator.py copy-doc \
+  --doc-id OQAehZAod_HVHC
+```
+
+### 复制到指定知识库根目录并自定义标题
+
+```bash
+python3 scripts/ku_operator.py copy-doc \
+  --doc-id OQAehZAod_HVHC \
+  --to-repo-guid B8wSneaLSC \
+  --to-parent-guid 00000000000000 \
+  --new-title "接口说明-副本"
+```

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

@@ -0,0 +1,61 @@
+# create-doc — 新建文档
+
+在知识库中新建文档或目录。支持从本地 Markdown 文件读取内容，自动上传本地图片/附件到 BOS。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py create-doc --repo-guid <知识库ID> --title "文档标题"
+python3 scripts/ku_operator.py create-doc --repo-guid <知识库ID> --title "文档标题" --content-file ./doc.md
+python3 scripts/ku_operator.py create-doc --repo-guid <知识库ID> --title "子文档" --parent-doc-guid <父文档ID>
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--repo-guid` | 是 | 知识库 ID |
+| `--title` | 否 | 文档标题 |
+| `--content-file` | 否 | 从本地文件读取文档内容（Markdown 格式）；不传则创建空文档 |
+| `--parent-doc-guid` | 否 | 父文档 ID，不传则创建在根目录 |
+
+## 输出说明
+
+返回 JSON 格式结果，关键字段：
+- `docGuid` — 新建文档的 ID
+- `url` — 新建文档的访问 URL（可直接提供给用户）
+
+## 注意事项
+
+- 创建者用户名自动从环境变量 `COMATE_USERNAME` 读取，无需手动传入
+- 如需创建带内容的文档，先将内容写入本地 `.md` 文件，再通过 `--content-file` 传入
+- **自动资源上传**：使用 `--content-file` 时，脚本会自动扫描 Markdown 中引用的本地图片和附件，通过 `bos` 工具上传到 BOS 并替换为远程 URL
+- **重要：撰写 Markdown 时，图片和附件引用必须使用绝对路径**（如 `![图片](/home/user/ku_assets/doc_id/image.png)`），不要使用相对路径
+
+## 使用示例
+
+### 创建空文档
+
+```bash
+python3 scripts/ku_operator.py create-doc \
+  --repo-guid B8wSneaLSC \
+  --title "会议纪要-2026-02-09"
+```
+
+### 从本地文件创建带内容的文档
+
+```bash
+python3 scripts/ku_operator.py create-doc \
+  --repo-guid B8wSneaLSC \
+  --title "接口说明" \
+  --content-file ./接口说明.md
+```
+
+### 在指定目录下创建文档
+
+```bash
+python3 scripts/ku_operator.py create-doc \
+  --repo-guid B8wSneaLSC \
+  --title "子文档" \
+  --parent-doc-guid OQAehZAod_HVHC
+```

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

@@ -0,0 +1,31 @@
+# delete-doc — 删除文档
+
+删除指定的知识库文档。
+
+## CLI 用法
+
+```bash
+python3 scripts/ku_operator.py delete-doc --doc-id <文档ID>
+```
+
+## 参数表
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc-id` | 是 | 要删除的文档 ID |
+
+## 输出说明
+
+返回 JSON 格式结果，关键字段：
+- `docGuid` — 被删除文档的 ID
+- 操作成功时返回 JSON 中不包含 `error` 字段
+
+> 操作者用户名自动从环境变量 `COMATE_USERNAME` 读取，无需手动传入。
+>
+> **注意**：删除操作不可恢复，执行前请确认目标文档无误。
+
+## 使用示例
+
+```bash
+python3 scripts/ku_operator.py delete-doc --doc-id ABC123
+```