fix: add size-based reading strategy and ban web-search fallback
sites/tacit0924/v1/urls.md: 新增"读取警告",标注文档 853K 字 - 禁止 get_content - doc.resolve_document_structure 为唯一可行方案 - 注明超时处理方式(重试一次,不行就停) sources/tencent-doc/v1/usage.md: 重写为"文档大小分级" - 顶部增加策略表(<1万/1万-50万/>50万/未知) - 超大文档单独标注禁止 get_content - 增加超时处理步骤(重试一次,禁止 web search) SKILL.md: 优先级规则第 4 条改为"禁止降级到 web search" Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -79,7 +79,7 @@ media-center/
|
||||
1. 找"每日更新" → 优先走 Tencent Doc 路线(Tacit0924 文档)
|
||||
2. 找"特定资源" → 先在 Tacit0924 文档搜,找不到再走 PanSou search
|
||||
3. 通用搜索 → 走 PanSou search(需配置 PANSOU_URL)
|
||||
4. PanSou 不可用 → 降级到 web search 获取信息,或告知用户配置
|
||||
4. 某个渠道不可用(MCP 超时 / PanSou 未配)→ 告知用户,**禁止降级到 web search**
|
||||
```
|
||||
|
||||
## 端到端示例
|
||||
@@ -93,8 +93,11 @@ Step 0: 确定数据源
|
||||
|
||||
Step 1: 读取文档搜关键词
|
||||
sources/tencent-doc/v1/usage.md
|
||||
→ doc.resolve_document_structure → 提取全文
|
||||
→ grep "2026.05.16" + "动漫/动画" → 找到分享链接
|
||||
→ 先查 urls.md 确认文档大小(853K字,超大文档)
|
||||
→ 确定读取策略:doc.resolve_document_structure
|
||||
→ 执行读取,如超时则等 3 秒重试一次
|
||||
→ 仍超时则告知用户"后端暂不可用"
|
||||
→ 提取全文 → grep "2026.05.16" + "动漫/动画" → 找到分享链接
|
||||
|
||||
Step 2: 转存到夸克
|
||||
storage/quark/v1/usage.md
|
||||
|
||||
+12
-12
@@ -8,10 +8,19 @@
|
||||
| URL | https://docs.qq.com/doc/DR2xUcFdrSVhJTkZu?dver= |
|
||||
| file_id | `DR2xUcFdrSVhJTkZu` |
|
||||
| 文档类型 | tencentdoc(传统文档) |
|
||||
| 总字数 | ~853,231 字 / 28,449 段落 |
|
||||
| 总字数 | **~853,231 字 / 28,449 段落** |
|
||||
| 估算 JSON 体积 | ~8MB(完整结构) |
|
||||
| 读取策略 | 见下方"读取警告" |
|
||||
| 授权方式 | 只能查看(只读模式) |
|
||||
|
||||
> 该文档需要腾讯文档 OAuth 授权才能通过 MCP 读取,参见 `sources/tencent-doc/v1/install.md`
|
||||
## 读取警告
|
||||
|
||||
> ⚠️ **此文档为超大文档(853K 字)**,读取方式受文档大小影响显著:
|
||||
>
|
||||
> 1. 禁止使用 `get_content` — 5 秒后端固定超时,必失败
|
||||
> 2. `doc.resolve_document_structure` 是唯一可行方案,但返回 ~8MB JSON
|
||||
> 3. 后端服务不稳定时,`doc.resolve_document_structure` 也可能超时
|
||||
> 4. 超时后重试一次,仍失败则告知用户"后端暂不可用"
|
||||
|
||||
## file_id 提取方法
|
||||
|
||||
@@ -19,13 +28,4 @@ URL `https://docs.qq.com/doc/DR2xUcFdrSVhJTkZu` 中 `/doc/` 后面的部分即
|
||||
|
||||
## 关联文档
|
||||
|
||||
文档中还引用了其他腾讯文档子文档:
|
||||
- https://docs.qq.com/doc/DQlVGenVJVE9j...
|
||||
- https://docs.qq.com/doc/DQkRORUNmUUN5...
|
||||
- https://docs.qq.com/doc/DQmJCdG56a0hEa1Np...
|
||||
- https://docs.qq.com/doc/DQmx1WEdTRXpGe...
|
||||
- https://docs.qq.com/doc/DQnZaEFjYUpnV...
|
||||
- https://docs.qq.com/doc/DQmdjdHp4dUdEWGJp...
|
||||
- https://docs.qq.com/doc/DR3ZyaVd1dXNuZW5L...
|
||||
|
||||
这些子文档为跳转分流页,主文档包含了全部实际内容。
|
||||
文档中还引用了其他腾讯文档子文档,这些子文档为跳转分流页,主文档包含全部实际内容。
|
||||
|
||||
@@ -1,12 +1,33 @@
|
||||
# 腾讯文档 — 使用
|
||||
|
||||
## 读取文档内容
|
||||
## 文档大小分级读取策略
|
||||
|
||||
**读取方法由文档大小决定**,先查数据源信息确认文档大小,再选对应策略:
|
||||
|
||||
| 文档大小 | 推荐方法 | 说明 |
|
||||
|---------|---------|------|
|
||||
| < 1 万字 | `get_content` | 一次性读取全文 |
|
||||
| 1万 ~ 50万字 | `doc.resolve_document_structure` | 返回全部节点(含 text_preview) |
|
||||
| > 50万字 | `doc.resolve_document_structure` | 超大文档,后端可能超时 |
|
||||
| 未知大小 | 先 `doc.get_outline` 探测结构 → 判断大小 | 不要直接试 |
|
||||
|
||||
> **已知超大文档**:Tacit0924 资源文档(853K 字),见 `sites/tacit0924/v1/urls.md`。禁止对其使用 `get_content`,5 秒后端超时必失败。
|
||||
|
||||
### 超时处理
|
||||
|
||||
`doc.resolve_document_structure` 对于 >50 万字的文档可能因后端不稳定而超时:
|
||||
|
||||
```
|
||||
第一次超时 → 等待 3 秒重试一次 → 仍超时则告知"后端暂不可用"
|
||||
```
|
||||
|
||||
**禁止降级到 web search**。告知用户稍后重试即可。
|
||||
|
||||
### 从 URL 提取 file_id
|
||||
|
||||
URL 格式:`https://docs.qq.com/doc/DR2xUcFdrSVhJTkZu`
|
||||
URL 格式 `https://docs.qq.com/doc/DR2xUcFdrSVhJTkZu`,`/doc/` 后面部分即 file_id。
|
||||
|
||||
提取 `DR2xUcFdrSVhJTkZu` 部分即为 file_id。
|
||||
## 读取步骤
|
||||
|
||||
### 第一步:判断文档类型
|
||||
|
||||
@@ -17,7 +38,7 @@ mcporter call tencent-docs smartcanvas.read file_id=<FILE_ID> size=10
|
||||
- 报错 `file is tencentdoc, not smartcanvas` → 传统文档,走第二步 A
|
||||
- 返回正常 JSON → smartcanvas 文档,走第二步 B
|
||||
|
||||
### 第二步 A:tencentdoc 类型(大文档推荐)
|
||||
### 第二步 A:tencentdoc 类型
|
||||
|
||||
```bash
|
||||
# 获取完整文档结构
|
||||
@@ -39,7 +60,7 @@ with open('doc_content.txt','w',encoding='utf-8') as f:
|
||||
print(f'Done: {len(texts)} paragraphs')
|
||||
"
|
||||
|
||||
# 清理中间文件(可选)
|
||||
# 清理中间文件
|
||||
rm doc_raw.json
|
||||
```
|
||||
|
||||
@@ -53,19 +74,16 @@ mcporter call tencent-docs smartcanvas.read file_id=<FILE_ID> size=50
|
||||
mcporter call tencent-docs smartcanvas.read file_id=<FILE_ID> next_token=<TOKEN> size=50
|
||||
```
|
||||
|
||||
## 搜索关键字获取资源链接
|
||||
## 搜索关键字
|
||||
|
||||
```bash
|
||||
# 在导出的文本中搜索
|
||||
grep -n "关键词" doc_content.txt
|
||||
```
|
||||
|
||||
链接格式参考:
|
||||
- `[普通链接: https://pan.quark.cn/s/xxx]` — 夸克分享链接
|
||||
- `[腾讯文档链接: https://docs.qq.com/doc/...]` — 其他腾讯文档
|
||||
链接格式:`[普通链接: https://pan.quark.cn/s/xxx]` → 用中间的 URL。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **超大文档**(>10万字)不要用 `get_content`,必超时
|
||||
- **Windows 编码**:带 emoji 的文档必须用 `python -X utf8`
|
||||
- **链接格式**:提取出的链接在 `text_preview` 中带 `[普通链接: ...]` 包裹,直接用中间的真实 URL
|
||||
- **超大文档(>10万字)禁止 `get_content`**,必超时
|
||||
- 后端不稳定时重试一次,不行就告知用户,**不要 web search**
|
||||
- Windows 编码:带 emoji 的文档用 `python -X utf8`
|
||||
|
||||
Reference in New Issue
Block a user