---
name: stale-detector
description: "Scan a Yuque knowledge base for stale or outdated documents and recommend updates or archiving. Use when the user is cleaning up, maintaining, or periodically reviewing a knowledge base; trigger phrases include “帮我检查哪些文档过期了”, “知识库体检”, and “find stale docs”."
license: MIT
compatibility: Requires the yuque-mcp MCP server connected with a personal Yuque token
metadata:
  author: yuque
  version: "1.0"
---

# Stale Detector — Knowledge Base Freshness Audit

Scan a Yuque knowledge base to discover documents that haven't been updated in a long time, analyze whether their content may be outdated, and generate a maintenance report with actionable recommendations.

## When to Use

- User wants to clean up or maintain their knowledge base
- User says "帮我检查哪些文档过期了", "find stale docs", "知识库体检"
- User wants to identify documents that need updating or archiving
- User is doing a periodic knowledge base review

## Required MCP Tools

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

- `yuque_list_books` — List user's knowledge bases
- `yuque_list_docs` — List all documents in a knowledge base with metadata
- `yuque_get_doc` — Read document content for staleness analysis
- `yuque_get_toc` — Get knowledge base structure

## Workflow

### Step 1: Identify the Target Knowledge Base

**Case A — User specifies a knowledge base:**
Extract `repo_id` (namespace) from the provided link or name.

**Case B — User wants to scan all knowledge bases:**
List all repos first:

```
Tool: yuque_list_books
Parameters:
  user_id: "<user_id>"
```

Present the list and let the user choose, or scan them one by one if the user confirms.

**Case C — User is vague:**
Ask: "你想检查哪个知识库？我可以先列出你的所有知识库。"

### Step 2: Fetch Document List

Get all documents in the target knowledge base:

```
Tool: yuque_list_docs
Parameters:
  repo_id: "<namespace>"
```

Extract key metadata for each document:
- `title` — Document title
- `slug` — Document identifier
- `updated_at` — Last update timestamp
- `created_at` — Creation timestamp
- `word_count` — Document length
- `status` — Publication status

If the knowledge base is empty (no documents), inform the user: "这个知识库目前没有文档。"

### Step 3: Classify Documents by Freshness

Calculate the age of each document (days since last update) and classify:

| Category | Criteria | Label |
|----------|----------|-------|
| 🟢 **Fresh** | Updated within 90 days | 活跃 |
| 🟡 **Aging** | Updated 90-180 days ago | 老化中 |
| 🟠 **Stale** | Updated 180-365 days ago | 陈旧 |
| 🔴 **Dormant** | Not updated for 365+ days | 休眠 |

### Step 4: Deep Analysis of Stale Documents

For documents classified as 🟠 Stale or 🔴 Dormant, read the content of up to 10 documents (prioritize the oldest and most important-looking ones by title):

```
Tool: yuque_get_doc
Parameters:
  repo_id: "<namespace>"
  doc_id: "<slug>"
```

For each document, analyze:

1. **Time-sensitive content** — Does it reference specific dates, versions, or events that may have passed?
   - Software version numbers (e.g., "React 16", "Node 12")
   - Date references (e.g., "2023年计划", "Q3 目标")
   - Links that may be broken
   - Policies or processes that may have changed

2. **Evergreen content** — Is the content timeless?
   - Conceptual explanations, principles, personal reflections
   - These may be old but still valid

3. **Recommendation:**
   - **Update** — Content is valuable but contains outdated information
   - **Archive** — Content is no longer relevant, move to archive
   - **Keep** — Content is evergreen, no action needed despite age
   - **Review** — Uncertain, needs human judgment

If `yuque_get_doc` fails (404/403), note the document as inaccessible and skip.

### Step 5: Generate Maintenance Report

```markdown
## 🔍 知识库健康报告

**知识库**：[知识库名称](知识库链接)
**扫描时间**：YYYY-MM-DD HH:MM
**文档总数**：X 篇

### 📊 整体健康度

| 状态 | 数量 | 占比 |
|------|------|------|
| 🟢 活跃（90 天内更新） | X | XX% |
| 🟡 老化中（90-180 天） | X | XX% |
| 🟠 陈旧（180-365 天） | X | XX% |
| 🔴 休眠（365 天以上） | X | XX% |

**健康评分**：X/100
（计算方式：🟢×100 + 🟡×70 + 🟠×30 + 🔴×0，加权平均）

### 🔴 需要关注的文档

#### 建议更新

| 文档 | 上次更新 | 原因 |
|------|----------|------|
| [文档标题](链接) | YYYY-MM-DD | [e.g., 引用了 Node 12，当前已是 Node 22] |
| [文档标题](链接) | YYYY-MM-DD | [e.g., 包含 2023 年的计划，需要更新] |

#### 建议归档

| 文档 | 上次更新 | 原因 |
|------|----------|------|
| [文档标题](链接) | YYYY-MM-DD | [e.g., 已完成的项目记录，可归档] |

#### 建议保留（虽旧但有效）

| 文档 | 上次更新 | 原因 |
|------|----------|------|
| [文档标题](链接) | YYYY-MM-DD | [e.g., 通用方法论，内容不过时] |

#### 需要人工判断

| 文档 | 上次更新 | 原因 |
|------|----------|------|
| [文档标题](链接) | YYYY-MM-DD | [e.g., 无法确定内容是否仍然有效] |

### 💡 维护建议

1. [具体建议 1：e.g., 建议每季度审查一次「技术文档」分类下的文档]
2. [具体建议 2：e.g., 考虑创建一个「归档」知识库，将不再维护的文档迁移过去]
3. [具体建议 3：e.g., 有 X 篇文档超过 2 年未更新，建议集中处理]
```

### Step 6: Offer Follow-up Actions

After presenting the report, offer:

- "需要我帮你把建议归档的文档移到归档知识库吗？"
- "需要我帮你逐篇查看需要更新的文档，给出具体的更新建议吗？"
- "需要我定期（比如每月）帮你做一次知识库体检吗？"

These are suggestions only — do not take action without user confirmation.

## Guidelines

- Always answer in the same language the user used (Chinese or English)
- Be conservative with "archive" recommendations — when in doubt, suggest "review" instead
- Don't read every document in a large knowledge base — sample strategically
- The health score is a rough indicator, not a precise metric — present it as such
- Evergreen content (personal reflections, principles, methodologies) should not be flagged as stale just because of age
- Focus on actionable recommendations, not just listing old documents
- If the knowledge base has fewer than 5 documents, simplify the report format

## Error Handling

| Situation | Action |
|-----------|--------|
| Knowledge base not found | Inform user and suggest listing their repos with `yuque_list_books` |
| Knowledge base is empty | Inform user: "这个知识库目前没有文档，无需体检" |
| `yuque_list_docs` returns error | Inform user of the issue, suggest checking the knowledge base link |
| Too many documents (100+) | Analyze metadata for all, but only deep-read the top 10 stalest documents |
| All documents are fresh | Congratulate the user: "知识库状态很健康！所有文档都在活跃维护中 🎉" |
| API rate limiting | Slow down requests, inform user if the scan takes longer than expected |