@comate/zulu 1.2.1-beta.2 → 1.3.1

package/comate-engine/assets/skills/comate-docs-comate/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: "comate-docs"
+description: "Use when the user asks how to use Comate (百度 AI 编程智能体), needs up-to-date documentation from the internal knowledge base, wants to understand Comate's Agent modes/Skills/Context system/MCP/CLI, or seeks guidance on models, billing, or troubleshooting. Load reference files only as supplementary context."
+metadata:
+  enableWhen:
+    - isInternal
+---
+
+# Comate Docs
+
+## Quick Start
+
+## 前置依赖
+
+- **Skill 依赖 `get-ugate-token`**：认证通过 get-ugate-token skill 自动获取个人身份 token
+- **Python 依赖**：`requests` 库
+- **当前用户名**: ${COMATE_USERNAME}，即`COMATE_USERNAME=${COMATE_USERNAME}`
+
+
+## 认证说明
+
+本 skill 依赖 `get-ugate-token` skill 进行个人身份认证。调用时自动获取 ugate token：
+
+- 若本地已有有效的 token 缓存文件，直接使用，无需用户介入
+- 若 token 不存在或已过期，`get-ugate-token` 会向用户询问授权token
+- 用户完成授权后，重新发起操作即可
+
+## 质量原则
+
+- 必须以知识库实时内容为准。
+- 回答时引用具体页面 URL。
+
+## 知识库 URL 与 ID 解析（重要）
+
+```
+https://ku.baidu-int.com/knowledge/{spaceGuid}/{groupGuid}/{repoGuid}/{docGuid}
+```
+
+| URL 段       | 含义         | 说明                        |
+|-------------|------------|---------------------------|
+| `spaceGuid` | 空间 ID      | 一般不需要使用                   |
+| `groupGuid` | 分组 ID      | 一般不需要使用                   |
+| `repoGuid`  | **知识库 ID** | 用于 `--repo-guid` 参数       |
+| `docGuid`   | **文档 ID**  | 用于 `--doc-id` 参数，URL 最后一段 |
+
+**路径段数判断链接类型：**
+
+- **4 段**（含 docGuid）→ 文档链接，可直接 `query-content` 读取
+- **3 段**（仅到 repoGuid）→ 知识库链接，需先 `query-repo` 查询目录
+
+## 重要概念：文档即目录
+
+知识库中**文档和目录是同一个概念**——任何文档都可以拥有子文档。读取文档后应通过 `query-repo --parent-doc-guid <该文档ID>`
+检查是否有子文档，按需加载以提供完整结果。
+
+## CLI 子命令一览
+
+统一入口：`python3 scripts/ku_operator.py <子命令> [参数]`
+
+| 子命令                 | 功能                  | 必填参数                                  | 常用可选参数                                                    |
+|---------------------|---------------------|---------------------------------------|-----------------------------------------------------------|
+| `query-content`     | 查询文档内容（Markdown 输出） | `--doc-id` 或 `--url`（二选一）             | `--save-assets-dir`, `--no-download-assets`, `--raw-json` |
+| `query-repo`        | 查询知识库目录（文本树形输出）     | `--repo-guid`                         | `--parent-doc-guid`, `--page`                             |
+
+**关键用法说明：**
+
+- `query-content` 默认自动下载远程图片/附件到 `./ku_assets/{doc_id}/`，并替换 Markdown 中的 URL。读取文档后注意 stderr
+  资源下载摘要，按需用 Read 工具查看已下载的图片。
+
+## API 详细文档
+
+各子命令的详细参数、输出格式、使用示例见 `references/` 目录：
+
+| 文档                                | 内容          |
+|-----------------------------------|-------------|
+| `references/query_content.md`     | 文档内容查询详细说明  |
+| `references/query_repo.md`        | 知识库目录查询详细说明 |
+
+## 错误处理
+
+**可自行修复（重试）：** 参数缺失、ID 格式错误（repoGuid/docGuid 搞反）、页码超出范围
+
+**需告知用户（不重试）：**
+
+- 认证失败（401/403）→ 提示用户重新发起操作以触发 ugate-auth 授权
+- 文档不存在（404）→ 告知用户检查文档是否已被删除
+- 无操作权限 → 告知用户联系知识库管理员
+- 服务端错误（5xx）→ 告知用户稍后再试
+
+## Comate Product Snapshot
+
+1. **Agent 模式（One Agent, Three Modes）**：Ask（问答/解释）、Plan（复杂任务规划，含澄清表单和 Human-in-the-loop
+   审核）、Build（直接生成实现）
+2. **Context 系统**：Skills（可移植技能包）、Subagents（并行子智能体）、Rules（项目/个人规范）、Commands（`/` 指令）、MCP（Model
+   Context Protocol）、`@` 关联上下文
+3. **并行执行**：工具级 + Subagent 级并行；异步执行（Worktree、云端沙盒）
+4. **Skills 市场**：内置 `/find-skills` 指令，从远端 Skills 中心搜索并安装 skill；内置 `/create-skill` 一键创建项目级或个人级
+   skill
+5. **Zulu CLI**：命令行工具，可在终端、iPipe CI/CD 流水线中运行 Comate Agent
+6. **Jinx Code**：Web 端 Vibe Coding 产品，云端沙盒执行，网址 `https://web-agent-next.baidu-int.com/`
+7. **MCP 渐进式加载**：以 MCP Server 为粒度按需加载工具定义，大幅节省上下文 Tokens
+8. **兼容性**：兼容 Claude Code、Codex、Cursor 等 20+ Agent 工具的 Skills 目录格式
+
+## Workflow
+
+1. 明确用户问题属于哪个类别：功能使用、模型选择/计费、Skills/Context、CLI、故障排除、最新动态。
+2. 按需加载 `references/` 中对应的参考文件（见下方 Reference Map）。
+3. 用 playwright-cli 抓取对应文档页面（见下方 Doc Map）。
+4. 综合文档内容和参考文件回答，并给出知识库页面链接作为引用。
+5. 对于 Skills 安装问题，优先引导用户使用 `/find-skills` 指令，其次提供手动目录路径。
+
+## Doc Map
+
+所有页面均在同一知识空间，基础路径：`https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/`
+
+| 章节                  | URL 页面 ID（`jyGhbHUQQG/` 后缀） | 说明                                           |
+|---------------------|-----------------------------|----------------------------------------------|
+| 知识库首页/目录            | `WBcj3KdE3ATpQR`            | 36 篇子页面的总目录                                  |
+| 开始使用                | `CAu-Eo5qijd3xY`            | 开始使用章节入口                                     |
+| Agent               | `rEVzf39R6KVKXM`            | Agent 章节入口（模式说明）                             |
+| Mission Mode               | 独立连接`https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/mcV1ZM02Cz/laPtUbdW5yJsbo`                      | Mission Mode 用户手册                             |
+| Context             | `Pn9zCxdoUeQ-SC`            | Context 章节入口                                 |
+| Skills（Context 子页）  | `BAD2sU4Yqs1kCP`            | Skills 完整说明：格式、目录、/create-skill、/find-skills |
+| 账户                  | `XOEDtioqXFa5zg`            | 账户章节入口                                       |
+| 使用账单（账户子页）          | `cMPrc68gwEX1Hs`            | 多模型列表、按 Token 计价、资源账户绑定                      |
+| 数据度量（账户子页）          | `iSLaMIFKeD7Pmy`            | 个人/团队 Coding Agent 使用数据视图                    |
+| 故障排除                | `sEQ16HgwkyDc_H`            | 故障排除章节                                       |
+| Changelog           | `6Ft3QPJ87cXqek`            | 版本更新历史                                       |
+| 周边生态                | `XLL_Zhb2ruCp4l`            | 周边生态章节入口                                     |
+| Zulu CLI（周边生态子页）    | `amicnOzxkkzxiQ`            | CLI 安装、参数、iPipe 用法、Docker 镜像                 |
+| Jinx Code（周边生态子页）   | `jor-aKcmbLwRKv`            | Web 端云沙盒 Vibe Coding 产品介绍                    |
+| 团队动态                | `9y6h0rTC3Bdg8V`            | 团队动态章节入口                                     |
+| 【动态】Comate 4.0 升级情况 | `Hb6OQz5Jc7/mhBWPhoBv258Ve` | 4.0 架构详解、SWE-Bench 评分、使用数据分析                 |
+| 【实践】打通如流知识库         | `Nrj3-AWvt1DPt-`            | 使用 ku-doc-manage Skill 直接读写知识库文档             |
+| 【实践】内网资源大集合         | `Np0ZvForjkgRBz`            | baidu-intranet-access Skill 安装和使用指南          |
+| 【实践】拆卡提码一条龙         | `hbAL01OPSL9LMU`            | create-cr Skill：从 PRD 建 iCafe 卡片到提交代码        |
+| 【研究】MCP 渐进式加载       | `EpzgIaNtaVAHf-`            | MCP 上下文优化原理，对比 Claude Code、Cursor 方案         |
+
+## Reference Map
+
+按需读取，不要一次性全部加载：
+
+- `references/product-overview.md` → 产品架构、模式说明、Context 系统、并行执行机制
+- `references/models-and-billing.md` → 支持的模型列表、按密级的模型权限、计费规则
+- `references/doc-map-extended.md` → 完整 URL 索引（含所有已知子页面）
+
+
+

package/comate-engine/assets/skills/comate-docs-comate/references/doc-map-extended.md

@@ -0,0 +1,78 @@
+# Comate 文档 URL 完整索引
+
+> 所有 URL 均基于前缀：`https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/`
+
+## 主知识库（jyGhbHUQQG/ 路径）
+
+### 顶层目录
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| Comate使用说明书（首页） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/WBcj3KdE3ATpQR` |
+
+### 开始使用
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| 开始使用（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/CAu-Eo5qijd3xY` |
+
+### Agent
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| Agent（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/rEVzf39R6KVKXM` |
+
+### Context
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| Context（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/Pn9zCxdoUeQ-SC` |
+| Skills | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/BAD2sU4Yqs1kCP` |
+| @关联上下文 | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/XLL_Zhb2ruCp4l` |
+
+### 账户
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| 账户（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/XOEDtioqXFa5zg` |
+| 使用账单（模型价格/配额） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/cMPrc68gwEX1Hs` |
+| 数据度量（个人/团队用量） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/iSLaMIFKeD7Pmy` |
+
+### 故障排除
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| 故障排除（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/sEQ16HgwkyDc_H` |
+
+### Changelog
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| Changelog（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/6Ft3QPJ87cXqek` |
+
+### 周边生态
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| 周边生态（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/XLL_Zhb2ruCp4l` |
+| Zulu CLI（命令行工具） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/amicnOzxkkzxiQ` |
+| Jinx Code（Web 端 Vibe Coding） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/jor-aKcmbLwRKv` |
+
+### 团队动态
+
+| 页面标题 | 完整 URL |
+|----------|----------|
+| 团队动态（章节入口） | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/9y6h0rTC3Bdg8V` |
+| 【研究】MCP 渐进式加载节省 Tokens | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/EpzgIaNtaVAHf-` |
+| 【实践】使用 Comate 打通如流知识库 | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/Nrj3-AWvt1DPt-` |
+| 【实践】「我们搞了一个Skill」之 拆卡提码一条龙 | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/hbAL01OPSL9LMU` |
+| 【实践】「我们搞了一个Skill」之 内网资源大集合 | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/Np0ZvForjkgRBz` |
+| 【动态】Comate 4.0 升级情况及效果 | `https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/Hb6OQz5Jc7/mhBWPhoBv258Ve` |
+
+## 外部工具链接
+
+| 工具 | URL |
+|------|-----|
+| 资源账户绑定/提额 | `https://oneapi-comate.baidu-int.com/mine` |
+| Jinx Code Web | `https://web-agent-next.baidu-int.com/` |
+| OneTool 个人 Token（Zulu CLI） | `https://console.cloud.baidu-int.com/onetool/auth-manage/my-services` |

package/comate-engine/assets/skills/comate-docs-comate/references/models-and-billing.md

@@ -0,0 +1,51 @@
+# Comate 模型列表与计费
+
+> 辅助参考文件。模型上线情况随产品迭代变化，以知识库「使用账单」页面的实时内容为准。
+
+## 模型选择方式
+
+- **Auto 模式**：根据用户 Query 自动选择最合适的模型（推荐日常使用）
+- **Max 模式**：更大上下文窗口，适合复杂/长程任务，但消耗 Tokens 较多
+- 切换路径：打开 Agent → 模型下拉选择 / 开启 Max 模式
+
+## 按代码库密级的模型权限
+
+| 密级 | 是否允许海外模型 | 可用模型（示例） |
+|------|-----------------|-----------------|
+| 保密 L1 / 个人库 / GitHub 代码库 | ❌ | GLM-4.7、MiniMax M2.5、Kimi K2.5 |
+| 保密 L0 | ✅ | MiniMax、DeepSeek-V3.1、GLM-4.7、Claude 4.5 Sonnet、Claude Opus 4.5、Gemini 3 Pro Preview |
+| 开源、三方、基础库 | ✅ | 同上 + 更多 |
+
+## 当前模型价格（人民币/百万 Tokens，仅供参考）
+
+| 模型 | 输入 | 输出 | 缓存命中 |
+|------|------|------|----------|
+| DeepSeek V3.1（千帆） | 8元 | 32元 | 3.2元 |
+| GLM 4.6/4.7 | 3元 | 12元 | 0.6元 |
+| GLM 5 | 6元 | 22元 | 1.5元 |
+| MiniMax 2.1/2.5 | 2.1元 | 8.4元 | 2.625元 |
+| Kimi K2 | 4元 | 16元 | 0.8元 |
+| Kimi K2.5 | 4.4元 | 23.1元 | 0.77元 |
+| Claude Haiku 4.5 | 7.7元（1.1$） | 38.5元（5.5$） | 9.625元 |
+| Claude 4.5/4.6 Sonnet | 23.1元（3.3$） | 115.5元（16.5$） | 28.875元 |
+| Claude 4.5/4.6 Opus | 38.5元（5.5$） | 192.5元（27.5$） | 48.125元 |
+| Gemini 3 Pro Preview | 14元（2$） | 84元（12$） | 1.4元 |
+
+> 账单显示逻辑：1 Request = 0.3元（折算）
+
+## 使用额度
+
+| 用户类型 | 额度 |
+|----------|------|
+| 无资源账户 | 全局总计 600元 |
+| 有资源账户 | 每人每月 1500元 |
+
+- 资源账户绑定/提额入口：`https://oneapi-comate.baidu-int.com/mine`
+- 注意：未绑定资源账户的用户无法使用海外模型
+
+## Zulu CLI 额度
+
+| 用户类型 | 额度 |
+|----------|------|
+| 有资源账户 | 每人每月 5000 requests |
+| 无资源账户 | 全局总计 2000 requests |

package/comate-engine/assets/skills/comate-docs-comate/references/product-overview.md

@@ -0,0 +1,73 @@
+# Comate 产品概览
+
+> 辅助参考文件，以知识库实时内容为准。当前快照反映 Comate 4.0（2026年3月全量）情况。
+
+## 产品定位
+
+Comate（内部研发代号 Zulu）是百度内部 AI 编程智能体，基于 VSCode IDE 插件形态，支持厂内部署、SaaS、VPC 等多种环境，面向研发全流程提供 AI 辅助。
+
+## 核心架构：One Agent, Three Modes
+
+| 模式 | 英文 | 适用场景 |
+|------|------|----------|
+| 问答模式 | Ask | 代码解释、问题解答、轻量查询 |
+| 计划模式 | Plan | 复杂任务：表单式澄清 → 计划创建/修改 → Human-in-the-loop 审核 → 执行 |
+| 构建模式 | Build | 直接生成实现，适合明确的开发需求 |
+
+## Context 系统
+
+### Skills
+
+- **定义**：可移植、受版本控制的技能包，每个 Skill 是一个包含 `SKILL.md` 的文件夹
+- **自动加载目录**：
+  - 项目级：`.agents/skills/` 或 `.comate/skills/`
+  - 个人级（全局）：`~/.comate/skills/`
+- **发现与安装**：在 Comate 输入框输入 `/find-skills`，从远端 Skills 市场搜索并安装
+- **创建**：使用内置 `/create-skill` 指令，支持项目级或个人级
+- **兼容**：同时兼容 `.claude/skills/`、`.codex/skills/`、`~/.claude/skills/` 等目录
+
+### Subagents
+
+- 并行执行子任务的独立 Agent 实例
+- Comate 接收用户 Query 后会自动发出多个并行子任务，提升执行速度和效果
+
+### Rules
+
+- 项目或个人级编码规范文件
+- 支持通过 `/create-skill` 将已有 Rules 迁移为 Skills
+
+### Commands
+
+- 使用 `/` 在输入框中调用（如 `/find-skills`、`/create-skill`、`/ku-doc-manage`）
+- 支持显式指定 Skill、Subagent 或 Command
+
+### MCP（Model Context Protocol）
+
+- 支持自定义安装 MCP Server，连接外部工具
+- **渐进式加载**：以 MCP Server 为粒度按需加载，避免全量 400+ 工具塞满上下文
+- 加载流程：Server 摘要（轻量）→ 模型判断是否需要 → 实时拉取完整工具定义 → 调用
+
+### @ 关联上下文
+
+- 使用 `@` 在输入框中关联文件、代码、文档等上下文
+- 支持 `/` 和 `@` 多选搭配
+
+### Semantic Search
+
+- 全代码库语义检索，支持精准定位相关代码片段
+
+## 并行化策略
+
+| 级别 | 说明 |
+|------|------|
+| 工具级并行 | 同一轮推理中多个工具并发调用 |
+| Subagent 级并行 | 多个子 Agent 并发执行不同子任务 |
+| 异步执行（规划中） | Automations（定时/Webhook 触发）、Worktree、云端沙盒 |
+
+## 性能数据（4.0，2026年3月）
+
+- SWE-Bench 评分稳定在 70 分以上
+  - GLM-5：Comate（76.4）> Claude Code（72.5）
+  - GLM-4.7：Comate（71.3）> Claude Code（70.7）
+- 周活跃用户 > 1万，人均 Query 次数 > 38
+- 线上任务采纳率 94.06%

package/comate-engine/assets/skills/comate-docs-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/comate-docs-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
+```