@comate/zulu 1.2.1-beta.2 → 1.3.0

package/comate-engine/assets/skills/comate-docs-comate/scripts/ku_operator.py

@@ -0,0 +1,1575 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+知识库（Ku）文档操作 CLI 工具
+
+支持的操作：
+1.  query-content          - 查询文档内容
+2.  query-repo             - 查询知识库目录
+3.  create-doc             - 新建文档/目录
+4.  move-doc               - 移动文档
+5.  delete-doc             - 删除文档
+6.  query-user-info        - 查询当前用户信息
+7.  copy-doc               - 复制文档
+8.  edit-content           - 编辑文档正文
+9.  upload-attachment      - 上传附件到文档正文
+10. query-flowchart        - 查询文档流程图数据
+11. add-member             - 添加文档成员
+12. update-member          - 更新文档成员角色
+13. change-scope           - 修改文档公开/私密范围
+14. query-permission       - 查询用户文档权限
+15. query-comment          - 查询文档评论
+16. query-recent-view      - 查询文档浏览记录
+
+依赖：pip install requests
+
+认证方式：通过 ugate-auth skill 获取个人身份 token
+环境变量：
+- COMATE_USERNAME: 当前用户的百度用户名（必填）
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse, unquote
+
+
+try:
+    import requests
+except ImportError:
+    print("错误: 缺少 requests 库，请执行 pip install requests", file=sys.stderr)
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# 常量
+# ---------------------------------------------------------------------------
+
+DEFAULT_API_BASE = "https://apigo.baidu-int.com/wiki/so"
+JSON_TO_MD_URL = "http://10.11.153.100:8001/jsonToMd"
+
+
+# ---------------------------------------------------------------------------
+# API 客户端
+# ---------------------------------------------------------------------------
+
+class KuApiClient:
+    """知识库 REST API 客户端"""
+
+    def __init__(self, base_url: str, ugate_token: str):
+        """初始化知识库 API 客户端。"""
+        self.base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+        self._session.headers["Ugate-Token"] = ugate_token
+        self._session.headers["access-key"] = "mYUuWUsFKk7e/oAjCKC8CA=="
+        self._session.headers["Content-Type"] = "application/json"
+
+    def _post(self, path: str, payload: Dict[str, Any], timeout: int = 30) -> Dict[str, Any]:
+        """发送 JSON POST 请求并返回响应。"""
+        url = f"{self.base_url}{path}"
+        try:
+            resp = self._session.post(url, json=payload, timeout=timeout)
+        except requests.exceptions.Timeout:
+            print(f"错误: 请求超时 ({timeout}s)，URL: {path}", file=sys.stderr)
+            print("建议: 可能是服务端处理耗时较长，请稍后重试。", file=sys.stderr)
+            sys.exit(1)
+        if resp.status_code in (401, 403):
+            msg = f"错误: 认证失败 (HTTP {resp.status_code})，" \
+                  "ugate token 可能已过期或无效。"
+            print(msg, file=sys.stderr)
+            print("请重新发起当前操作，系统将自动触发 ugate-auth 授权流程。",
+                  file=sys.stderr)
+            sys.exit(2)
+        if resp.status_code == 504:
+            print(f"错误: 网关超时 (HTTP 504)，URL: {path}", file=sys.stderr)
+            print("建议: 服务端处理超时，请稍后重试。如果操作涉及大量内容，"
+                  "可尝试拆分为多次小批量操作。", file=sys.stderr)
+            sys.exit(1)
+        if resp.status_code >= 500:
+            print(f"错误: 服务端错误 (HTTP {resp.status_code})，URL: {path}",
+                  file=sys.stderr)
+            print("建议: 服务端暂时不可用，请稍后重试。", file=sys.stderr)
+            sys.exit(1)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _post_multipart(
+        self, path: str, form_data: Dict[str, Any],
+        files: Dict[str, Any], timeout: int = 120,
+    ) -> Dict[str, Any]:
+        """发送 multipart/form-data POST 请求并返回响应。"""
+        url = f"{self.base_url}{path}"
+        headers = dict(self._session.headers)
+        if 'Content-Type' in headers:
+            del headers['Content-Type']
+        try:
+            resp = requests.post(url, headers=headers, data=form_data, files=files, timeout=timeout)
+        except requests.exceptions.Timeout:
+            print(f"错误: 请求超时 ({timeout}s)，URL: {path}", file=sys.stderr)
+            print("建议: 文件上传超时，请检查文件大小或稍后重试。", file=sys.stderr)
+            sys.exit(1)
+        if resp.status_code in (401, 403):
+            msg = f"错误: 认证失败 (HTTP {resp.status_code})，" \
+                  "ugate token 可能已过期或无效。"
+            print(msg, file=sys.stderr)
+            print("请重新发起当前操作，系统将自动触发 ugate-auth 授权流程。",
+                  file=sys.stderr)
+            sys.exit(2)
+        if resp.status_code >= 500:
+            print(f"错误: 服务端错误 (HTTP {resp.status_code})，URL: {path}",
+                  file=sys.stderr)
+            print("建议: 服务端暂时不可用，请稍后重试。", file=sys.stderr)
+            sys.exit(1)
+        resp.raise_for_status()
+        return resp.json()
+
+    # ----- 1. 查询文档内容 -----
+
+    def query_content(
+        self,
+        doc_id: Optional[str] = None,
+        url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        查询文档内容。
+        :param doc_id: 文档 ID（与 url 二选一）
+        :param url:    文档 URL（与 doc_id 二选一）
+        """
+        if not doc_id and not url:
+            raise ValueError("必须提供 --doc-id 或 --url 中的至少一个")
+        payload: Dict[str, Any] = {}
+        if doc_id:
+            payload["docId"] = doc_id
+        if url:
+            payload["url"] = url
+        return self._post("/ku/openapi/queryContent", payload)
+
+    # ----- 2. 查询知识库目录 -----
+
+    REPO_PAGE_SIZE = 100  # 固定每页数量，不对外暴露
+    ROOT_DOC_GUID = "00000000000000"  # 根目录标识
+
+    def query_repo(
+        self,
+        repo_guid: str,
+        parent_doc_guid: str = "00000000000000",
+        page_num: int = 1,
+    ) -> Dict[str, Any]:
+        """
+        查询知识库目录列表。
+        :param repo_guid:        知识库 ID（必填）
+        :param parent_doc_guid:  父文档 ID（默认 00000000000000 即根目录）
+        :param page_num:         页码，默认 1
+        """
+        payload: Dict[str, Any] = {
+            "repoId": repo_guid,
+            "parentDocGuid": parent_doc_guid,
+            "pageNum": page_num,
+            "pageSize": self.REPO_PAGE_SIZE,
+        }
+        return self._post("/ku/openapi/queryRepo", payload)
+
+    # ----- 3. 新建文档/目录 -----
+
+    def create_doc(
+        self,
+        repository_guid: str,
+        title: Optional[str] = None,
+        content: Optional[str] = None,
+        parent_doc_guid: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        新建文档或目录。
+        :param repository_guid:  知识库 ID（必填）
+        :param title:            文档标题
+        :param content:          文档内容（Markdown 格式）
+        :param parent_doc_guid:  父文档 ID（不传则创建在根目录）
+        """
+        creator_username = os.environ.get("COMATE_USERNAME", "")
+        if not creator_username:
+            print("警告: 未设置环境变量 COMATE_USERNAME，将使用空用户名", file=sys.stderr)
+        payload: Dict[str, Any] = {
+            "repositoryGuid": repository_guid,
+            "creatorUsername": creator_username,
+        }
+        if title:
+            payload["title"] = title
+        if content:
+            payload["content"] = content
+        if parent_doc_guid:
+            payload["parentDocGuid"] = parent_doc_guid
+        return self._post("/ku/openapi/createDoc", payload)
+
+    # ----- 4. 移动文档 -----
+
+    def move_doc(
+        self,
+        doc_id: str,
+        to_repo_guid: str,
+        to_parent_guid: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        移动文档到目标位置。
+        :param doc_id:          文档 ID（必填）
+        :param to_repo_guid:    目标知识库 ID（必填）
+        :param to_parent_guid:  目标父目录 ID（不传则移动到根目录）
+        """
+        operator_username = os.environ.get("COMATE_USERNAME", "")
+        if not operator_username:
+            print("警告: 未设置环境变量 COMATE_USERNAME，将使用空用户名", file=sys.stderr)
+        payload: Dict[str, Any] = {
+            "docId": doc_id,
+            "toRepoGuid": to_repo_guid,
+            "operatorUsername": operator_username,
+        }
+        if to_parent_guid:
+            payload["toParentGuid"] = to_parent_guid
+        return self._post("/ku/openapi/moveDoc", payload)
+
+    # ----- 5. 删除文档 -----
+
+    def delete_doc(self, doc_id: str) -> Dict[str, Any]:
+        """
+        删除文档。
+        :param doc_id: 文档 ID（必填）
+        """
+        operator_username = os.environ.get("COMATE_USERNAME", "")
+        if not operator_username:
+            print("警告: 未设置环境变量 COMATE_USERNAME，将使用空用户名", file=sys.stderr)
+        payload: Dict[str, Any] = {
+            "docId": doc_id,
+            "operatorUsername": operator_username,
+        }
+        return self._post("/ku/openapi/deleteDoc", payload)
+
+    # ----- 6. 查询用户信息 -----
+
+    def query_user_info(self, username: str) -> Dict[str, Any]:
+        """
+        查询用户信息。
+        :param username: 用户名（必填）
+        """
+        return self._post("/ku/openapi/queryUserInfo", {"username": username})
+
+    # ----- 7. 复制文档 -----
+
+    def copy_doc(
+        self,
+        doc_id: str,
+        to_repo_guid: Optional[str] = None,
+        to_parent_guid: Optional[str] = None,
+        new_title: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """复制文档到目标位置。"""
+        operator_username = os.environ.get("COMATE_USERNAME", "")
+        payload: Dict[str, Any] = {
+            "docId": doc_id,
+            "operatorUsername": operator_username,
+        }
+        if to_repo_guid:
+            payload["toRepoGuid"] = to_repo_guid
+        if to_parent_guid:
+            payload["toParentGuid"] = to_parent_guid
+        if new_title:
+            payload["newTitle"] = new_title
+        return self._post("/ku/openapi/copyDoc", payload)
+
+    # ----- 8. 编辑文档正文 -----
+
+    def edit_content(
+        self,
+        doc_id: str,
+        operations: List[Dict[str, Any]],
+        publish: bool = False,
+    ) -> Dict[str, Any]:
+        """编辑文档正文内容。"""
+        username = os.environ.get("COMATE_USERNAME", "")
+        payload: Dict[str, Any] = {
+            "docGuid": doc_id,
+            "editorUsername": username,
+            "operations": operations,
+        }
+        if publish:
+            payload["publish"] = True
+        return self._post("/ku/openapi/editContent", payload)
+
+    # ----- 9. 上传附件 -----
+
+    def upload_attachment(self, doc_id: str, file_path: str) -> Dict[str, Any]:
+        """上传附件到指定文档。"""
+        with open(file_path, 'rb') as f:
+            file_content = f.read()
+        file_name = os.path.basename(file_path)
+        form_data = {"docGuid": doc_id}
+        files = {"file": (file_name, file_content)}
+        return self._post_multipart("/ku/openapi/uploadAttachment", form_data, files)
+
+    # ----- 10. 查询流程图 -----
+
+    def query_flowchart(self, doc_id: str, flowchart_id: str) -> Dict[str, Any]:
+        """查询文档中的流程图数据。"""
+        return self._post("/ku/openapi/queryFlowchart", {
+            "docGuid": doc_id,
+            "flowchartId": flowchart_id,
+        })
+
+    # ----- 14. 添加成员 -----
+
+    def add_member(
+        self,
+        doc_id: str,
+        usernames: List[str],
+        role: str = "DocReader",
+    ) -> Dict[str, Any]:
+        """添加文档成员。"""
+        return self._post("/ku/openapi/addMember", {
+            "docId": doc_id,
+            "usernames": usernames,
+            "roleName": role,
+        })
+
+    # ----- 15. 更新成员角色 -----
+
+    def update_member(
+        self,
+        doc_id: str,
+        username: str,
+        role: str,
+    ) -> Dict[str, Any]:
+        """更新文档成员角色。"""
+        return self._post("/ku/openapi/updateMember", {
+            "docId": doc_id,
+            "username": username,
+            "roleName": role,
+        })
+
+    # ----- 16. 修改文档范围 -----
+
+    def change_scope(self, doc_id: str, scope: int) -> Dict[str, Any]:
+        """修改文档公开/私密范围。"""
+        operator_username = os.environ.get("COMATE_USERNAME", "")
+        return self._post("/ku/openapi/changeScope", {
+            "docId": doc_id,
+            "scope": scope,
+            "operatorUsername": operator_username,
+        })
+
+    # ----- 17. 查询权限 -----
+
+    def query_permission(
+        self,
+        doc_id: str,
+        usernames: List[str],
+    ) -> Dict[str, Any]:
+        """查询用户对文档的权限。"""
+        return self._post("/ku/openapi/queryPermission", {
+            "docId": doc_id,
+            "usernames": usernames,
+        })
+
+    # ----- 18. 查询评论 -----
+
+    def query_comment(
+        self,
+        doc_id: str,
+        bottom: bool = True,
+        side: bool = False,
+        page: int = 1,
+        page_size: int = 100,
+    ) -> Dict[str, Any]:
+        """查询文档评论。"""
+        payload: Dict[str, Any] = {
+            "docId": doc_id,
+            "queryBottomComment": bottom,
+            "querySideComment": side,
+            "pageNum": page,
+            "pageSize": page_size,
+        }
+        return self._post("/ku/openapi/queryComments", payload)
+
+    # ----- 19. 查询浏览记录 -----
+
+    def query_recent_view(
+        self,
+        doc_id: str,
+        begin_time: Optional[int] = None,
+        end_time: Optional[int] = None,
+        page: int = 1,
+        page_size: int = 100,
+    ) -> Dict[str, Any]:
+        """查询文档浏览记录。"""
+        payload: Dict[str, Any] = {
+            "docId": doc_id,
+            "pageNum": page,
+            "pageSize": page_size,
+        }
+        if begin_time is not None:
+            payload["beginTime"] = begin_time
+        if end_time is not None:
+            payload["endTime"] = end_time
+        return self._post("/ku/openapi/queryRecentView", payload)
+
+
+# ---------------------------------------------------------------------------
+# 内容转换工具
+# ---------------------------------------------------------------------------
+
+def convert_blocks_to_markdown(blocks: List[Dict[str, Any]]) -> str:
+    """调用 jsonToMd 服务将知识库文档的 block 结构转换为 Markdown 格式。"""
+    try:
+        resp = requests.post(
+            JSON_TO_MD_URL,
+            json={"data": blocks},
+            headers={"Content-Type": "application/json"},
+            timeout=60,
+        )
+        resp.raise_for_status()
+        result = resp.json()
+        if result.get("code") == 200:
+            return result.get("data", "")
+        print(f"警告: jsonToMd 服务返回异常: {result}", file=sys.stderr)
+        return ""
+    except Exception as e:
+        print(f"错误: 调用 jsonToMd 服务失败: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# 资源处理工具（图片/附件下载与上传）
+# ---------------------------------------------------------------------------
+
+# Markdown 图片引用正则：![alt](url)
+_MD_IMAGE_PATTERN = re.compile(r'(!\[[^\]]*\])\(([^)]+)\)')
+
+# Markdown 链接引用正则：[text](url)
+_MD_LINK_PATTERN = re.compile(r'(?<!!)(\[[^\]]*\])\(([^)]+)\)')
+
+
+def _format_file_size(size_bytes: int) -> str:
+    """格式化文件大小为人类可读格式。"""
+    if size_bytes < 1024:
+        return f"{size_bytes}B"
+    elif size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f}KB"
+    else:
+        return f"{size_bytes / (1024 * 1024):.1f}MB"
+
+
+# MIME 类型 → 文件扩展名映射
+_MIME_TO_EXT: Dict[str, str] = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/jpg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "image/svg+xml": ".svg",
+    "image/bmp": ".bmp",
+    "image/tiff": ".tiff",
+    "image/x-icon": ".ico",
+}
+
+
+def _ext_from_mime(mime_type: str) -> str:
+    """根据 MIME 类型返回文件扩展名，未知类型返回 '.bin'。"""
+    if not mime_type:
+        return ".bin"
+    return _MIME_TO_EXT.get(mime_type.lower().split(";")[0].strip(), ".bin")
+
+
+def download_assets_from_blocks(
+    markdown: str,
+    blocks: List[Dict[str, Any]],
+    doc_id: str,
+    save_dir: str = "./ku_assets",
+) -> Tuple[str, List[Dict[str, Any]]]:
+    """
+    从原始 content blocks 中提取图片和附件信息，下载图片到本地，
+    并在 markdown 中替换图片 URL 为本地路径、替换附件占位符为详细元信息。
+
+    jsonToMd 服务将 type=image 转为 ![](url)、type=attachment 转为 [附件] 占位符，
+    会丢失附件的文件名/大小/类型等关键信息。本函数直接从原始 blocks 提取完整元数据。
+
+    :param markdown:  jsonToMd 转换后的 markdown 文本
+    :param blocks:    queryContent API 返回的原始 content block 列表
+    :param doc_id:    文档 ID，用于创建子目录
+    :param save_dir:  资源保存根目录
+    :return:          (修改后的 markdown, 下载/识别的资源清单列表)
+    """
+    # 从 blocks 中提取图片和附件
+    images: List[Dict[str, Any]] = []
+    attachments: List[Dict[str, Any]] = []
+    for block in blocks:
+        btype = block.get("type", "")
+        if btype == "image":
+            src = block.get("src", "")
+            if src:
+                images.append({
+                    "url": src,
+                    "mimeType": block.get("mimeType", ""),
+                })
+        elif btype == "attachment":
+            file_info = block.get("fileInfo") or {}
+            attachments.append({
+                "fileId": block.get("fileId", ""),
+                "docId": block.get("docId", doc_id),
+                "name": file_info.get("name", "未知文件"),
+                "extension": file_info.get("extension", ""),
+                "size": file_info.get("size", 0),
+                "mimeType": file_info.get("type", ""),
+            })
+
+    if not images and not attachments:
+        return markdown, []
+
+    # 下载图片
+    downloaded: List[Dict[str, Any]] = []
+    failed: List[Dict[str, str]] = []
+
+    if images:
+        asset_dir = os.path.join(save_dir, doc_id)
+        os.makedirs(asset_dir, exist_ok=True)
+
+        for i, img in enumerate(images):
+            ext = _ext_from_mime(img["mimeType"])
+            filename = f"image_{i + 1:03d}{ext}"
+            local_path = os.path.join(asset_dir, filename)
+            try:
+                resp = requests.get(img["url"], timeout=30)
+                resp.raise_for_status()
+                # 如果 block 没有 mimeType，从 Content-Type 推断
+                if ext == ".bin":
+                    ct = resp.headers.get("Content-Type", "")
+                    header_ext = _ext_from_mime(ct)
+                    if header_ext != ".bin":
+                        ext = header_ext
+                        filename = f"image_{i + 1:03d}{ext}"
+                        local_path = os.path.join(asset_dir, filename)
+                with open(local_path, 'wb') as f:
+                    f.write(resp.content)
+                downloaded.append({
+                    'type': 'image',
+                    'url': img['url'],
+                    'local_path': local_path,
+                    'filename': filename,
+                    'size': len(resp.content),
+                    'mimeType': img['mimeType'] or ct if ext != ".bin" else "",
+                })
+            except Exception as e:
+                failed.append({'type': 'image', 'url': img['url'], 'error': str(e)})
+
+    # 替换 markdown 中的图片 URL 为本地路径
+    modified_markdown = markdown
+    for item in downloaded:
+        modified_markdown = modified_markdown.replace(item['url'], item['local_path'])
+
+    # 替换 [附件] 占位符为详细元信息
+    attach_idx = 0
+
+    def _replace_attachment_placeholder(match: re.Match) -> str:
+        nonlocal attach_idx
+        if attach_idx >= len(attachments):
+            return match.group(0)
+        att = attachments[attach_idx]
+        attach_idx += 1
+        size_str = _format_file_size(att['size'])
+        return (f"[附件: {att['name']} | {size_str} | "
+                f"{att['mimeType']} | fileId={att['fileId']}]")
+
+    modified_markdown = re.sub(
+        r'\[附件\]', _replace_attachment_placeholder, modified_markdown,
+    )
+
+    # 在 stderr 输出资源摘要
+    summary_lines: List[str] = []
+    if images:
+        ok = len(downloaded)
+        fail = len(failed)
+        summary_lines.append(f"图片: 发现 {len(images)} 个，成功下载 {ok} 个")
+        for item in downloaded:
+            size_str = _format_file_size(item['size'])
+            summary_lines.append(
+                f"  ✓ {item['local_path']} ({size_str}, {item['mimeType']})")
+        for item in failed:
+            summary_lines.append(f"  ✗ {item['url']} (原因: {item['error']})")
+    if attachments:
+        summary_lines.append(f"附件: 发现 {len(attachments)} 个")
+        for att in attachments:
+            size_str = _format_file_size(att['size'])
+            summary_lines.append(
+                f"  - {att['name']} ({size_str}, {att['mimeType']})")
+
+    if summary_lines:
+        print("\n[资源摘要]", file=sys.stderr)
+        for line in summary_lines:
+            print(f"  {line}", file=sys.stderr)
+
+    return modified_markdown, downloaded
+
+
+def upload_local_assets_in_markdown(
+    markdown: str,
+    base_dir: str,
+) -> Tuple[str, List[Dict[str, str]]]:
+    """
+    解析 markdown 中的本地图片/附件引用，通过 dodo_cli bos upload 上传到 BOS，
+    并替换为远程 URL。
+
+    :param markdown:  原始 markdown 文本
+    :param base_dir:  本地文件的基准目录（content-file 所在目录）
+    :return:          (修改后的 markdown, 上传清单列表)
+    """
+    # original_ref -> resolved_absolute_path
+    local_refs: Dict[str, str] = {}
+
+    def _collect_local_ref(ref: str) -> Optional[str]:
+        """判断引用是否为本地文件，返回绝对路径。"""
+        ref = ref.strip()
+        # 跳过远程 URL、锚点、数据 URI
+        if ref.startswith(('http://', 'https://', '#', 'data:')):
+            return None
+        if ref in local_refs:
+            return local_refs[ref]
+        # 解析为绝对路径
+        if os.path.isabs(ref):
+            abs_path = ref
+        else:
+            abs_path = os.path.normpath(os.path.join(base_dir, ref))
+        # 检查文件是否存在
+        if not os.path.isfile(abs_path):
+            return None
+        local_refs[ref] = abs_path
+        return abs_path
+
+    # 扫描图片引用
+    for m in _MD_IMAGE_PATTERN.finditer(markdown):
+        ref = m.group(2).strip()
+        _collect_local_ref(ref)
+
+    # 扫描链接引用（只要本地文件存在就上传，不限制扩展名）
+    for m in _MD_LINK_PATTERN.finditer(markdown):
+        ref = m.group(2).strip()
+        if ref.startswith(('http://', 'https://', '#', 'data:')):
+            continue
+        _collect_local_ref(ref)
+
+    if not local_refs:
+        return markdown, []
+
+    # 上传资源
+    uploaded: List[Dict[str, str]] = []
+    failed: List[Dict[str, str]] = []
+
+    for original_ref, abs_path in local_refs.items():
+        try:
+            result = subprocess.run(
+                ["dodo_cli", "bos", "upload", abs_path],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if result.returncode != 0:
+                raise RuntimeError(
+                    f"dodo_cli bos upload 返回非零退出码 {result.returncode}: {result.stderr.strip()}"
+                )
+            # 从 dodo_cli 多行输出中解析 URL，格式如：
+            #   Uploaded: local.txt -> uploads/...
+            #   Bucket: dodo-dev
+            #   Size: 1.2KB
+            #   URL: https://...
+            bos_url = ""
+            for line in result.stdout.splitlines():
+                line = line.strip()
+                if line.startswith("URL:"):
+                    bos_url = line[len("URL:"):].strip()
+                    break
+            if not bos_url:
+                raise RuntimeError(
+                    f"dodo_cli bos upload 输出中未找到 URL 行，完整输出:\n{result.stdout.strip()}"
+                )
+            uploaded.append({
+                'original_ref': original_ref,
+                'abs_path': abs_path,
+                'bos_url': bos_url,
+            })
+        except Exception as e:
+            failed.append({'original_ref': original_ref, 'error': str(e)})
+
+    # 替换 markdown 中的本地路径为 BOS URL
+    modified_markdown = markdown
+    for item in uploaded:
+        modified_markdown = modified_markdown.replace(item['original_ref'], item['bos_url'])
+
+    # 在 stderr 输出上传摘要
+    total_found = len(local_refs)
+    total_ok = len(uploaded)
+    total_fail = len(failed)
+
+    print(f"\n[资源上传] 共发现 {total_found} 个本地资源，成功上传 {total_ok} 个：", file=sys.stderr)
+    for item in uploaded:
+        print(f"  - {item['original_ref']} -> {item['bos_url']}", file=sys.stderr)
+    if failed:
+        print(f"  上传失败 {total_fail} 个：", file=sys.stderr)
+        for item in failed:
+            print(f"  - {item['original_ref']} (原因: {item['error']})", file=sys.stderr)
+
+    return modified_markdown, uploaded
+
+
+# ---------------------------------------------------------------------------
+# 目录格式化工具
+# ---------------------------------------------------------------------------
+
+def format_recent_views(
+    doc_id: str,
+    views: List[Dict[str, Any]],
+    total: int,
+    total_viewers: int,
+    page_num: int,
+    page_size: int,
+) -> str:
+    """将浏览记录格式化为 agent 友好的文本输出。"""
+    from datetime import datetime, timezone, timedelta
+
+    tz = timezone(timedelta(hours=8))
+
+    lines: List[str] = []
+    lines.append(f"文档 {doc_id} 浏览记录（共 {total} 次，{total_viewers} 位访客）")
+
+    if not views:
+        lines.append("")
+        lines.append("（暂无浏览记录）")
+        return "\n".join(lines)
+
+    lines.append("")
+
+    for v in views:
+        nickname = v.get("nickname", "")
+        username = v.get("username", "")
+        view_time = v.get("viewTime", 0)
+        time_str = datetime.fromtimestamp(view_time / 1000, tz=tz).strftime("%Y-%m-%d %H:%M")
+        lines.append(f"- {nickname} ({username}) · {time_str}")
+
+    # 分页提示
+    total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+    if page_num < total_pages:
+        lines.append("")
+        lines.append(f"提示：还有更多记录，使用 --page {page_num + 1} 查看下一页。")
+
+    return "\n".join(lines)
+
+
+def format_comments(
+    doc_id: str,
+    bottom_comments: List[Dict[str, Any]],
+    side_comments: List[Dict[str, Any]],
+    bottom_total: int,
+    side_total: int,
+    page_num: int,
+    page_size: int,
+) -> str:
+    """将评论查询结果格式化为 agent 友好的文本输出。"""
+    from datetime import datetime, timezone, timedelta
+
+    tz = timezone(timedelta(hours=8))
+
+    def _fmt_time(ts_ms: int) -> str:
+        return datetime.fromtimestamp(ts_ms / 1000, tz=tz).strftime("%Y-%m-%d %H:%M")
+
+    def _fmt_comment(comment: Dict[str, Any], index: int, indent: str = "") -> List[str]:
+        user = comment.get("commentUserInfo") or {}
+        nickname = user.get("nickname", "")
+        username = user.get("username", "")
+        text = comment.get("text", "").strip()
+        created = comment.get("created", 0)
+        quote = comment.get("quote")
+
+        lines: List[str] = []
+        header = f"{indent}{index}. {nickname} ({username}) · {_fmt_time(created)}"
+        lines.append(header)
+        if quote:
+            lines.append(f'{indent}   引用: "{quote}"')
+        if text:
+            for tl in text.split("\n"):
+                lines.append(f"{indent}   {tl}")
+
+        children = comment.get("childrenComments") or []
+        for ci, child in enumerate(children, 1):
+            c_user = child.get("commentUserInfo") or {}
+            c_nick = c_user.get("nickname", "")
+            c_uname = c_user.get("username", "")
+            c_text = child.get("text", "").strip()
+            c_time = child.get("created", 0)
+            is_last = ci == len(children)
+            prefix = "└─" if is_last else "├─"
+            cont = "  " if is_last else "│ "
+            lines.append(f"{indent}   {prefix} {c_nick} ({c_uname}) · {_fmt_time(c_time)}")
+            if c_text:
+                for tl in c_text.split("\n"):
+                    lines.append(f"{indent}   {cont} {tl}")
+        return lines
+
+    lines: List[str] = []
+
+    # 标题
+    parts: List[str] = []
+    if bottom_total >= 0:
+        parts.append(f"底部 {bottom_total} 条")
+    if side_total >= 0:
+        parts.append(f"划线 {side_total} 条")
+    total_str = "，".join(parts)
+    lines.append(f"文档 {doc_id} 评论（{total_str}）")
+
+    if bottom_total == 0 and side_total == 0:
+        lines.append("")
+        lines.append("（暂无评论）")
+        return "\n".join(lines)
+
+    # 底部评论
+    if bottom_comments:
+        lines.append("")
+        lines.append(f"## 底部评论（{bottom_total} 条）")
+        lines.append("")
+        for i, c in enumerate(bottom_comments, 1):
+            lines.extend(_fmt_comment(c, i))
+            lines.append("")
+
+    # 划线评论
+    if side_comments:
+        lines.append("")
+        lines.append(f"## 划线评论（{side_total} 条）")
+        lines.append("")
+        for i, c in enumerate(side_comments, 1):
+            lines.extend(_fmt_comment(c, i))
+            lines.append("")
+
+    # 分页提示
+    total = max(bottom_total, side_total)
+    total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+    if page_num < total_pages:
+        lines.append(f"提示：还有更多评论，使用 --page {page_num + 1} 查看下一页。")
+
+    return "\n".join(lines)
+
+
+def format_repo_tree(
+    repo_guid: str,
+    data: List[Dict[str, Any]],
+    page_num: int,
+    total: int,
+    parent_doc_guid: str,
+) -> str:
+    """将知识库目录查询结果格式化为文本树形输出。"""
+    lines: List[str] = []
+
+    # ---- 标题行 ----
+    is_root = (parent_doc_guid == KuApiClient.ROOT_DOC_GUID)
+    location = "根目录" if is_root else f"目录 {parent_doc_guid}"
+    page_size = KuApiClient.REPO_PAGE_SIZE
+    total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+
+    if total <= page_size:
+        lines.append(f"知识库 {repo_guid} {location}（共 {total} 项）：")
+    else:
+        lines.append(
+            f"知识库 {repo_guid} {location}"
+            f"（第 {page_num} 页，当前 {len(data)} 项"
+            f" / 共 {total} 项）："
+        )
+    lines.append("")
+
+    # ---- 文档列表 ----
+    if not data:
+        lines.append("（空目录）")
+    else:
+        for doc in data:
+            child_count = doc.get("childCount", 0)
+            icon = "📁" if child_count > 0 else "📄"
+            name = doc.get("name", "未命名")
+            doc_guid = doc.get("docGuid", "")
+            line = f"{icon} {name} ({doc_guid})"
+            if child_count > 0:
+                line += f" [{child_count} 子文档]"
+            lines.append(line)
+
+    # ---- 翻页提示 ----
+    if total > page_size and page_num < total_pages:
+        lines.append("")
+        lines.append(f"提示：还有更多内容，使用 --page {page_num + 1} 查看下一页。")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _get_ugate_token(username: str) -> str:
+    """调用 ugate-auth skill 获取 ugate token。"""
+    script_path = Path(__file__).parent.parent.parent / "ugate-auth" / "scripts" / "getUgateToken.py"
+    if not script_path.exists():
+        print(f"错误: 未找到 ugate-auth 脚本: {script_path}", file=sys.stderr)
+        sys.exit(1)
+    result = subprocess.run(
+        [sys.executable, str(script_path), username],
+        capture_output=True, text=True, timeout=30,
+    )
+    if result.returncode == 0:
+        return result.stdout.strip()
+    if result.returncode == 2:
+        # 需要用户授权
+        print(result.stderr, file=sys.stderr, end="")
+        sys.exit(2)
+    # 其他错误
+    print(result.stderr, file=sys.stderr, end="")
+    sys.exit(1)
+
+
+def _get_client() -> KuApiClient:
+    """通过 ugate-auth 获取 token 并构造 API 客户端。"""
+    username = os.environ.get("COMATE_USERNAME", "")
+    if not username:
+        print("错误: 未设置环境变量 COMATE_USERNAME", file=sys.stderr)
+        sys.exit(1)
+    token = _get_ugate_token(username)
+    return KuApiClient(DEFAULT_API_BASE, token)
+
+
+def _output_json(data: Any) -> None:
+    """将结果以格式化 JSON 输出到 stdout。"""
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def _check_result(response: Dict[str, Any], allow_empty: bool = False) -> Dict[str, Any]:
+    """从 API 响应中提取 result 字段，处理 null / 错误情况。
+
+    API 响应格式: {"returnCode": 200, "result": {...}, "success": true}
+    当 API 返回错误时 result 可能为 null，此时 .get("result", {}) 返回 None 而非 {}。
+
+    :param response:    API 原始响应字典
+    :param allow_empty: 若为 True，result 为 None 时返回空字典而不退出
+    :return:            result 字典（保证非 None）
+    """
+    inner = response.get("result")
+    if inner is None:
+        if allow_empty:
+            return {}
+        msg = (response.get("returnMessage")
+               or response.get("msg")
+               or f"API 返回错误 (returnCode={response.get('returnCode')})")
+        print(f"错误: {msg}", file=sys.stderr)
+        sys.exit(1)
+    return inner
+
+
+def cmd_query_content(args: argparse.Namespace) -> None:
+    """
+    查询知识库文档内容
+    """
+    client = _get_client()
+    result = client.query_content(doc_id=args.doc_id, url=args.url)
+    inner = _check_result(result)
+    content_blocks = inner.get("content", [])
+
+    if args.raw_json:
+        _output_json(content_blocks)
+        return
+
+    markdown = convert_blocks_to_markdown(content_blocks)
+
+    # 资源下载处理
+    if not args.no_download_assets:
+        # 确定文档 ID（优先用 doc_id，否则从 URL 提取最后一段）
+        doc_id = args.doc_id
+        if not doc_id and args.url:
+            doc_id = args.url.rstrip('/').split('/')[-1]
+        if not doc_id:
+            doc_id = "unknown"
+        markdown, _ = download_assets_from_blocks(
+            markdown, content_blocks, doc_id,
+            save_dir=args.save_assets_dir,
+        )
+
+    print(markdown)
+
+
+def cmd_query_repo(args: argparse.Namespace) -> None:
+    """
+    查询 repo 目录结构
+    """
+    client = _get_client()
+    parent_doc_guid = args.parent_doc_guid or KuApiClient.ROOT_DOC_GUID
+    page_num = args.page or 1
+    result = client.query_repo(
+        repo_guid=args.repo_guid,
+        parent_doc_guid=parent_doc_guid,
+        page_num=page_num,
+    )
+    # 从响应中提取数据
+    result_body = _check_result(result, allow_empty=True)
+    if not result_body:
+        print("数据不存在")
+    else:
+        data = result_body.get("data", [])
+        total = result_body.get("total", 0)
+        output = format_repo_tree(
+            repo_guid=args.repo_guid,
+            data=data,
+            page_num=page_num,
+            total=total,
+            parent_doc_guid=parent_doc_guid,
+        )
+        print(output)
+
+
+def cmd_create_doc(args: argparse.Namespace) -> None:
+    """
+    创建一个文档
+    """
+    client = _get_client()
+    # 从文件读取内容
+    content = None
+    if args.content_file:
+        with open(args.content_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        # 自动上传本地图片/附件到 BOS，替换为远程 URL
+        base_dir = os.path.dirname(os.path.abspath(args.content_file))
+        content, _ = upload_local_assets_in_markdown(content, base_dir)
+    result = client.create_doc(
+        repository_guid=args.repo_guid,
+        title=args.title,
+        content=content,
+        parent_doc_guid=args.parent_doc_guid,
+    )
+    _output_json(result)
+
+
+def cmd_move_doc(args: argparse.Namespace) -> None:
+    """
+    移动文档的位置
+    """
+    client = _get_client()
+    result = client.move_doc(
+        doc_id=args.doc_id,
+        to_repo_guid=args.to_repo_guid,
+        to_parent_guid=args.to_parent_guid,
+    )
+    _output_json(result)
+
+
+def cmd_delete_doc(args: argparse.Namespace) -> None:
+    """
+    删除文档
+    """
+    client = _get_client()
+    result = client.delete_doc(doc_id=args.doc_id)
+    _output_json(result)
+
+
+def cmd_query_user_info(args: argparse.Namespace) -> None:
+    """
+    查询当前用户信息
+    """
+    username = os.environ.get("COMATE_USERNAME", "")
+    if not username:
+        print("错误: 未设置环境变量 COMATE_USERNAME", file=sys.stderr)
+        sys.exit(1)
+    client = _get_client()
+    result = client.query_user_info(username=username)
+    inner = _check_result(result)
+    repo = inner.get("userPersonalRepo") or {}
+    output = {
+        "username": inner.get("username", ""),
+        "nickname": inner.get("nickname", ""),
+        "email": inner.get("email", ""),
+        "personalRepoGuid": repo.get("repositoryGuid", ""),
+        "personalRepoUrl": repo.get("url", ""),
+    }
+    _output_json(output)
+
+
+def cmd_copy_doc(args: argparse.Namespace) -> None:
+    """复制文档。"""
+    client = _get_client()
+    result = client.copy_doc(
+        doc_id=args.doc_id,
+        to_repo_guid=args.to_repo_guid,
+        to_parent_guid=args.to_parent_guid,
+        new_title=args.new_title,
+    )
+    _output_json(result)
+
+
+def cmd_edit_content(args: argparse.Namespace) -> None:
+    """编辑文档正文。"""
+    with open(args.operations_file, "r", encoding="utf-8") as f:
+        operations = json.load(f)
+    client = _get_client()
+    result = client.edit_content(
+        doc_id=args.doc_id,
+        operations=operations,
+        publish=args.publish,
+    )
+    _output_json(result)
+
+
+def cmd_upload_attachment(args: argparse.Namespace) -> None:
+    """上传附件到文档正文。"""
+    if not os.path.isfile(args.file):
+        print(f"错误: 文件不存在: {args.file}", file=sys.stderr)
+        sys.exit(1)
+    client = _get_client()
+    result = client.upload_attachment(doc_id=args.doc_id, file_path=args.file)
+
+    # 默认自动插入正文
+    if not args.no_insert:
+        attach_result = _check_result(result, allow_empty=True)
+        attach_id = attach_result.get("attachId", "")
+        attach_name = attach_result.get("name", "")
+        attach_ext = attach_result.get("extension", "")
+        attach_size = attach_result.get("size", 0)
+        if attach_id:
+            import mimetypes
+            mime_type = mimetypes.guess_type(args.file)[0] or "application/octet-stream"
+            view_type = args.view_type or "attachment"
+            operations = [{
+                "mode": "sibling",
+                "json": [{
+                    "type": "attachment",
+                    "children": [{"text": ""}],
+                    "fileId": attach_id,
+                    "docId": args.doc_id,
+                    "fileInfo": {
+                        "name": attach_name,
+                        "extension": attach_ext,
+                        "size": attach_size,
+                        "type": mime_type,
+                    },
+                    "url": "",
+                    "invalid": False,
+                    "viewType": view_type,
+                }],
+            }]
+            client.edit_content(doc_id=args.doc_id, operations=operations)
+            print(f"附件已上传并插入文档正文 (attachId={attach_id})", file=sys.stderr)
+
+    _output_json(result)
+
+
+def _discover_diagrams(client: KuApiClient, doc_id: str) -> List[Dict[str, Any]]:
+    """从文档正文中发现所有流程图节点。
+
+    调用 queryContent 获取文档 block 列表，筛选 type=diagram 的节点，
+    返回 [{id, blockId, boxSize}, ...] 列表。
+    """
+    result = client.query_content(doc_id=doc_id)
+    inner = _check_result(result)
+    blocks = inner.get("content", [])
+    diagrams = []
+    for idx, block in enumerate(blocks):
+        if block.get("type") == "diagram":
+            diagrams.append({
+                "index": idx,
+                "flowchartId": block.get("id", ""),
+                "blockId": block.get("blockId", ""),
+                "boxSize": block.get("boxSize"),
+            })
+    return diagrams
+
+
+def _parse_mxgraph_xml(xml_str: str) -> List[Dict[str, str]]:
+    """从 mxGraph XML 中提取节点和边的信息，返回简要描述列表。"""
+    import xml.etree.ElementTree as ET
+    items: List[Dict[str, str]] = []
+    try:
+        root = ET.fromstring(xml_str)
+    except ET.ParseError:
+        return items
+    for cell in root.iter("mxCell"):
+        cell_id = cell.get("id", "")
+        # 跳过根容器节点（id=0 或 id=1）
+        if cell_id in ("0", "1"):
+            continue
+        value = cell.get("value", "")
+        style = cell.get("style", "")
+        source = cell.get("source")
+        target = cell.get("target")
+        if source and target:
+            item = {"type": "edge", "id": cell_id,
+                    "source": source, "target": target}
+            if value:
+                item["label"] = value
+            items.append(item)
+        else:
+            # 解析形状类型
+            shape = "node"
+            if "rhombus" in style:
+                shape = "diamond (判断)"
+            elif "process" in style:
+                shape = "process (处理)"
+            elif "ellipse" in style:
+                shape = "ellipse (开始/结束)"
+            elif "rounded" in style and "edge" not in style:
+                shape = "rounded-rect"
+            item = {"type": "node", "id": cell_id, "shape": shape}
+            if value:
+                item["label"] = value
+            items.append(item)
+    return items
+
+
+def _format_flowchart_output(
+    doc_id: str,
+    flowchart_id: str,
+    content_xml: str,
+    index: int = 0,
+) -> str:
+    """将流程图数据格式化为 agent 友好的文本输出。"""
+    lines: List[str] = []
+    lines.append(f"## 流程图 #{index + 1}")
+    lines.append(f"- 文档 ID: {doc_id}")
+    lines.append(f"- 流程图 ID: {flowchart_id}")
+    lines.append(f"- 格式: mxGraph XML")
+    lines.append("")
+
+    # 解析节点和边
+    items = _parse_mxgraph_xml(content_xml)
+    nodes = [it for it in items if it["type"] == "node"]
+    edges = [it for it in items if it["type"] == "edge"]
+
+    if nodes:
+        lines.append(f"### 节点 ({len(nodes)} 个)")
+        for n in nodes:
+            label = n.get("label", "(无文字)")
+            lines.append(f"  - [{n['id']}] {n.get('shape', 'node')}: {label}")
+    if edges:
+        lines.append(f"### 连线 ({len(edges)} 个)")
+        for e in edges:
+            label = f" ({e['label']})" if e.get("label") else ""
+            lines.append(f"  - [{e['id']}] {e['source']} → {e['target']}{label}")
+
+    if not nodes and not edges:
+        lines.append("（流程图为空或格式无法解析）")
+
+    lines.append("")
+    lines.append("### 原始 XML")
+    lines.append("```xml")
+    lines.append(content_xml)
+    lines.append("```")
+
+    return "\n".join(lines)
+
+
+def cmd_query_flowchart(args: argparse.Namespace) -> None:
+    """查询文档流程图数据。
+
+    当 --flowchart-id 未指定时，自动从文档正文中发现所有流程图并逐一查询。
+    """
+    client = _get_client()
+    doc_id = args.doc_id
+
+    # 确定要查询的流程图列表
+    if args.flowchart_id:
+        targets = [{"flowchartId": args.flowchart_id, "index": 0}]
+    else:
+        diagrams = _discover_diagrams(client, doc_id)
+        if not diagrams:
+            print(f"文档 {doc_id} 中未发现流程图（type=diagram 的内容块）。",
+                  file=sys.stderr)
+            sys.exit(0)
+        print(f"发现 {len(diagrams)} 个流程图，正在查询...", file=sys.stderr)
+        targets = diagrams
+
+    # 逐一查询并输出
+    outputs: List[str] = []
+    for i, target in enumerate(targets):
+        fid = target["flowchartId"]
+        result = client.query_flowchart(doc_id=doc_id, flowchart_id=fid)
+        inner = _check_result(result, allow_empty=True)
+        content_xml = inner.get("content", "") if isinstance(inner, dict) else ""
+
+        if args.output:
+            # 多个流程图时文件名加序号
+            out_path = args.output
+            if len(targets) > 1:
+                base, ext = os.path.splitext(args.output)
+                out_path = f"{base}_{i + 1}{ext}"
+            with open(out_path, "w", encoding="utf-8") as f:
+                f.write(content_xml)
+            print(f"流程图 #{i + 1} (id={fid}) 已保存到: {out_path}")
+        else:
+            outputs.append(
+                _format_flowchart_output(doc_id, fid, content_xml, index=i)
+            )
+
+    if outputs:
+        print("\n---\n".join(outputs))
+
+
+def cmd_add_member(args: argparse.Namespace) -> None:
+    """添加文档成员。"""
+    usernames = [u.strip() for u in args.usernames.split(",") if u.strip()]
+    role = "DocMember" if args.role == "DocEditor" else args.role
+    client = _get_client()
+    result = client.add_member(
+        doc_id=args.doc_id,
+        usernames=usernames,
+        role=role,
+    )
+    _output_json(result)
+
+
+def cmd_update_member(args: argparse.Namespace) -> None:
+    """更新文档成员角色。"""
+    role = "DocMember" if args.role == "DocEditor" else args.role
+    client = _get_client()
+    result = client.update_member(
+        doc_id=args.doc_id,
+        username=args.username,
+        role=role,
+    )
+    _output_json(result)
+
+
+def cmd_change_scope(args: argparse.Namespace) -> None:
+    """修改文档公开/私密范围。"""
+    client = _get_client()
+    result = client.change_scope(doc_id=args.doc_id, scope=args.scope)
+    _output_json(result)
+
+
+def cmd_query_permission(args: argparse.Namespace) -> None:
+    """查询用户文档权限。"""
+    usernames = [u.strip() for u in args.usernames.split(",") if u.strip()]
+    client = _get_client()
+    result = client.query_permission(doc_id=args.doc_id, usernames=usernames)
+    _output_json(result)
+
+
+def cmd_query_comment(args: argparse.Namespace) -> None:
+    """查询文档评论。"""
+    client = _get_client()
+    query_type = args.type
+    bottom = query_type in ("all", "bottom")
+    side = query_type in ("all", "side")
+    result = client.query_comment(
+        doc_id=args.doc_id,
+        bottom=bottom,
+        side=side,
+        page=args.page,
+        page_size=args.page_size,
+    )
+
+    if args.raw_json:
+        _output_json(result)
+        return
+
+    inner = _check_result(result, allow_empty=True)
+    bottom_result = inner.get("bottomCommentResult") or {}
+    side_result = inner.get("sideCommentResult") or {}
+
+    output = format_comments(
+        doc_id=args.doc_id,
+        bottom_comments=bottom_result.get("comments", []),
+        side_comments=side_result.get("comments", []),
+        bottom_total=bottom_result.get("totalCount", 0) if bottom else -1,
+        side_total=side_result.get("totalCount", 0) if side else -1,
+        page_num=args.page,
+        page_size=args.page_size,
+    )
+    print(output)
+
+
+def cmd_query_recent_view(args: argparse.Namespace) -> None:
+    """查询文档浏览记录。"""
+    from datetime import datetime, timezone, timedelta
+
+    tz = timezone(timedelta(hours=8))
+
+    def _parse_time(s: Optional[str]) -> Optional[int]:
+        if not s:
+            return None
+        for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"):
+            try:
+                dt = datetime.strptime(s, fmt).replace(tzinfo=tz)
+                return int(dt.timestamp() * 1000)
+            except ValueError:
+                continue
+        print(f"错误: 无法解析时间 '{s}'，支持格式: YYYY-MM-DD, YYYY-MM-DD HH:MM, YYYY-MM-DD HH:MM:SS",
+              file=sys.stderr)
+        sys.exit(1)
+
+    client = _get_client()
+    result = client.query_recent_view(
+        doc_id=args.doc_id,
+        begin_time=_parse_time(args.begin_time),
+        end_time=_parse_time(args.end_time),
+        page=args.page,
+        page_size=args.page_size,
+    )
+
+    if args.raw_json:
+        _output_json(result)
+        return
+
+    inner = _check_result(result, allow_empty=True)
+    output = format_recent_views(
+        doc_id=args.doc_id,
+        views=inner.get("data", []),
+        total=inner.get("total", 0),
+        total_viewers=inner.get("totalViewers", 0),
+        page_num=args.page,
+        page_size=args.page_size,
+    )
+    print(output)
+
+
+def main() -> None:
+    """
+    主入口函数
+    """
+    parser = argparse.ArgumentParser(
+        description="知识库（Ku）文档操作 CLI 工具",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="可用子命令")
+
+    # ---- query-content ----
+    p_qc = subparsers.add_parser("query-content", help="查询文档内容（输出 Markdown 格式）")
+    p_qc.add_argument("--doc-id", help="文档 ID")
+    p_qc.add_argument("--url", help="文档 URL")
+    p_qc.add_argument("--save-assets-dir", default="./ku_assets",
+                       help="资源保存目录（默认 ./ku_assets）")
+    p_qc.add_argument("--no-download-assets", action="store_true",
+                       help="禁用自动下载图片/附件")
+    p_qc.add_argument("--raw-json", action="store_true",
+                       help="输出原始 JSON block 结构（含 blockId），不转换为 Markdown")
+    p_qc.set_defaults(func=cmd_query_content)
+
+    # ---- query-repo ----
+    p_qr = subparsers.add_parser("query-repo", help="查询知识库目录（文本树形输出）")
+    p_qr.add_argument("--repo-guid", required=True, help="知识库 ID（必填）")
+    p_qr.add_argument("--parent-doc-guid", help="父文档 ID（默认查询根目录）")
+    p_qr.add_argument("--page", type=int, default=1, help="页码（默认 1，每页 100 条）")
+    p_qr.set_defaults(func=cmd_query_repo)
+
+    # ---- create-doc ----
+    p_cd = subparsers.add_parser("create-doc", help="新建文档/目录")
+    p_cd.add_argument("--repo-guid", required=True, help="知识库 ID（必填）")
+    p_cd.add_argument("--title", help="文档标题")
+    p_cd.add_argument("--content-file", help="从本地文件读取文档内容（Markdown 格式）")
+    p_cd.add_argument("--parent-doc-guid", help="父文档 ID（不传则创建在根目录）")
+    p_cd.set_defaults(func=cmd_create_doc)
+
+    # ---- move-doc ----
+    p_md = subparsers.add_parser("move-doc", help="移动文档")
+    p_md.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_md.add_argument("--to-repo-guid", required=True, help="目标知识库 ID（必填）")
+    p_md.add_argument("--to-parent-guid", help="目标父目录 ID（不传则移动到根目录）")
+    p_md.set_defaults(func=cmd_move_doc)
+
+    # ---- delete-doc ----
+    p_dd = subparsers.add_parser("delete-doc", help="删除文档")
+    p_dd.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_dd.set_defaults(func=cmd_delete_doc)
+
+    # ---- query-user-info ----
+    p_qui = subparsers.add_parser("query-user-info", help="查询当前用户信息")
+    p_qui.set_defaults(func=cmd_query_user_info)
+
+    # ---- copy-doc ----
+    p_cp = subparsers.add_parser("copy-doc", help="复制文档")
+    p_cp.add_argument("--doc-id", required=True, help="源文档 ID（必填）")
+    p_cp.add_argument("--to-repo-guid", help="目标知识库 ID")
+    p_cp.add_argument("--to-parent-guid", help="目标父目录 ID")
+    p_cp.add_argument("--new-title", help="新文档标题")
+    p_cp.set_defaults(func=cmd_copy_doc)
+
+    # ---- edit-content ----
+    p_ec = subparsers.add_parser("edit-content", help="编辑文档正文")
+    p_ec.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_ec.add_argument("--operations-file", required=True, help="JSON 操作文件路径（必填）")
+    p_ec.add_argument("--publish", action="store_true", help="编辑后同步发布")
+    p_ec.set_defaults(func=cmd_edit_content)
+
+    # ---- upload-attachment ----
+    p_ua = subparsers.add_parser("upload-attachment", help="上传附件到文档正文")
+    p_ua.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_ua.add_argument("--file", required=True, help="本地文件路径（必填）")
+    p_ua.add_argument("--no-insert", action="store_true", help="只上传不插入正文")
+    p_ua.add_argument("--view-type", choices=["attachment", "preview"], help="显示方式（默认 attachment）")
+    p_ua.set_defaults(func=cmd_upload_attachment)
+
+    # ---- query-flowchart ----
+    p_qf = subparsers.add_parser("query-flowchart", help="查询文档流程图数据")
+    p_qf.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_qf.add_argument("--flowchart-id", help="流程图 ID（不传则自动从文档正文中发现所有流程图）")
+    p_qf.add_argument("--output", help="输出文件路径（多个流程图时自动添加序号后缀）")
+    p_qf.set_defaults(func=cmd_query_flowchart)
+
+    # ---- add-member ----
+    p_am = subparsers.add_parser("add-member", help="添加文档成员")
+    p_am.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_am.add_argument("--usernames", required=True, help="用户名，多个用逗号分隔（必填）")
+    p_am.add_argument("--role", default="DocReader",
+                       choices=["DocReader", "DocEditor", "DocMember", "DocAdmin"],
+                       help="角色：DocReader=可读, "
+                            "DocEditor/DocMember=可编辑, "
+                            "DocAdmin=管理员（默认 DocReader）")
+    p_am.set_defaults(func=cmd_add_member)
+
+    # ---- update-member ----
+    p_um = subparsers.add_parser("update-member", help="更新文档成员角色")
+    p_um.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_um.add_argument("--username", required=True, help="用户名（必填）")
+    p_um.add_argument("--role", required=True,
+                       choices=["DocReader", "DocEditor", "DocMember", "DocAdmin"],
+                       help="新角色：DocReader=可读, DocEditor/DocMember=可编辑, DocAdmin=管理员")
+    p_um.set_defaults(func=cmd_update_member)
+
+    # ---- change-scope ----
+    p_cs = subparsers.add_parser("change-scope", help="修改文档公开/私密范围")
+    p_cs.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_cs.add_argument("--scope", required=True, type=int, choices=[5, 6, 20],
+                       help="范围：5=公开可读, 6=公开可编辑, 20=私密")
+    p_cs.set_defaults(func=cmd_change_scope)
+
+    # ---- query-permission ----
+    p_qp = subparsers.add_parser("query-permission", help="查询用户文档权限")
+    p_qp.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_qp.add_argument("--usernames", required=True, help="用户名，多个用逗号分隔（必填）")
+    p_qp.set_defaults(func=cmd_query_permission)
+
+    # ---- query-comment ----
+    p_qcm = subparsers.add_parser("query-comment", help="查询文档评论")
+    p_qcm.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_qcm.add_argument("--type", default="all", choices=["all", "bottom", "side"],
+                        help="评论类型：all=全部（默认）, bottom=底部评论, side=划线评论")
+    p_qcm.add_argument("--page", type=int, default=1, help="页码（默认 1）")
+    p_qcm.add_argument("--page-size", type=int, default=100, help="每页条数（默认 100）")
+    p_qcm.add_argument("--raw-json", action="store_true", help="输出原始 JSON")
+    p_qcm.set_defaults(func=cmd_query_comment)
+
+    # ---- query-recent-view ----
+    p_qrv = subparsers.add_parser("query-recent-view", help="查询文档浏览记录")
+    p_qrv.add_argument("--doc-id", required=True, help="文档 ID（必填）")
+    p_qrv.add_argument("--begin-time", help="起始时间（如 2026-03-20、2026-03-20 17:00）")
+    p_qrv.add_argument("--end-time", help="结束时间（如 2026-03-21、2026-03-21 09:00）")
+    p_qrv.add_argument("--page", type=int, default=1, help="页码（默认 1）")
+    p_qrv.add_argument("--page-size", type=int, default=100, help="每页条数（默认 100）")
+    p_qrv.add_argument("--raw-json", action="store_true", help="输出原始 JSON")
+    p_qrv.set_defaults(func=cmd_query_recent_view)
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()