# Yuque Group Smart Search

> Search group Yuque knowledge bases with natural language queries and provide summarized answers with key points and source links. For group use — searches within team/group repositories. Requires group Token.

- Skill: `yuque/yuque-group-smart-search` (Agent Skill)
- Install (CLI): `npx skillmds add yuque/yuque-group-smart-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuque/yuque-group-smart-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: yuque (https://skillmd.com/u/yuque)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/yuque/yuque-group-smart-search

---


# Smart Search — Yuque Team Knowledge Base Search & Q&A

Search across group Yuque knowledge bases using natural language, read relevant documents, and synthesize a clear answer with references. Scoped to team/group repositories.

## When to Use

- User asks a question that might be answered by their team's Yuque docs
- User wants to find specific information in group knowledge bases
- User says "搜一下团队文档", "search group Yuque", "团队知识库里有没有..."

## Required MCP Tools

All tools are from the `yuque-mcp` server:

- `yuque_list_repos` — List group knowledge bases to determine search scope
- `yuque_search` — Search documents by keyword
- `yuque_get_doc` — Read full document content by slug/id

## Workflow

### Step 1: Identify Team Scope

First, get the list of group knowledge bases to understand the search scope:

```
Tool: yuque_list_repos
Parameters:
  login: "<group_login>"
  type: "group"
```

If the user hasn't specified a group login, ask: "请告诉我团队的语雀团队标识（group login），我来搜索团队知识库。"

### Step 2: Extract Search Keywords

From the user's natural language query, extract 1-3 concise Chinese keywords. Yuque search works best with short, specific terms.

Examples:
- "团队的部署流程是什么？" → keywords: `部署流程`
- "我们的 API 规范文档" → keywords: `API 规范`
- "上次技术评审的结论" → keywords: `技术评审`

### Step 3: Search Documents

Call `yuque_search` with the extracted keywords:

```
Tool: yuque_search
Parameters:
  query: "<keywords>"
  type: "doc"
```

If the search returns no results:
1. Try alternative keywords (synonyms, broader terms)
2. Try splitting compound terms (e.g., "部署流程" → "部署" or "流程")
3. If still no results, tell the user honestly: "在团队语雀知识库中未找到相关文档，建议尝试其他关键词或确认文档是否存在。"

### Step 4: Filter and Rank Results

From the search results, select the top 3-5 most relevant documents based on:
- Title relevance to the query
- Document update time (prefer recent)
- Repository context (prioritize results from group repos identified in Step 1)

Filter out results that don't belong to the team's knowledge bases.

### Step 5: Read Document Content

For each selected document, fetch the full content:

```
Tool: yuque_get_doc
Parameters:
  repo_id: "<namespace>"    # e.g., "my-team/tech-docs" (from search result's book.namespace)
  doc_id: "<slug>"          # e.g., "api-spec" (from search result's target.slug)
```

Note: The search result contains nested data. Extract these key fields:
- `target.slug` → use as `doc_id`
- `target.book.namespace` → use as `repo_id`
- `target.title` → document title
- `target.updated_at` → last update time

Read up to 3 documents. If the first document fully answers the question, you may skip the rest.

### Step 6: Synthesize and Respond

Compose the answer in the following format:

```markdown
## 回答

[直接回答用户的问题，2-4 句话，简洁明了]

## 关键要点

- **要点 1**：[从文档中提取的关键信息]
- **要点 2**：[从文档中提取的关键信息]
- **要点 3**：[从文档中提取的关键信息]

## 参考文档

1. [文档标题](文档链接) — 来自「知识库名称」，更新于 YYYY-MM-DD
2. [文档标题](文档链接) — 来自「知识库名称」，更新于 YYYY-MM-DD
```

## Guidelines

- Always answer in the same language the user used (Chinese or English)
- Quote specific content from documents when relevant — use `>` blockquotes
- If documents contain conflicting information, note the discrepancy and mention which doc is more recent
- If the answer is only partially found, say what you found and what's missing
- Never fabricate information not present in the documents
- Include document links so the user can read the full source
- Only return results from group knowledge bases — filter out personal docs
- This skill searches group knowledge bases — for personal docs, use the `smart-search` skill in the `yuque-personal` plugin

## Error Handling

| Situation | Action |
|-----------|--------|
| `yuque_list_repos` fails | Check if group login is correct and group Token is configured |
| `yuque_search` returns empty | Try alternative keywords, then inform user |
| `yuque_get_doc` fails (404) | Skip this doc, note it may have been deleted |
| `yuque_get_doc` fails (403) | Tell user they may lack permission; check group Token scope |
| API timeout | Retry once, then inform user of connectivity issue |
| Too many results | Focus on top 3 by relevance, mention there are more results available |
| Team Token not configured | Inform user that group search requires a team-level Token |