llm-wiki MCP 优化建议（2026-10-12 实测）

来源：2026-10-12 全天实测（39 个工具，完整跑通"推送同步到 wiki"全链路） 实测端点：https://llm-wiki.vyibc.chatgpt.site/api/mcp v4.3.0 身份：外部 AI 客户端（Muse），通过 Bearer token 调用

1. 文章发布流程不支持文件夹（folder）

现状：

• import_content 只接受 category，传 folder 报"不支持的参数"
• 没有 list_folders 工具（报 Unknown tool）
• create_folder / update_folder 存在，但跟文章发布流程没打通

影响： Wiki Web 端有完整的文件夹体系（"推送归档"、"GitHub热门"等），但 MCP 客户端只能把文章扔进 category，够不着文件夹。用户在网页端看到的文件夹和 MCP 发过去的文章是两套组织体系。

建议：

• import_content 增加可选参数 folder_id（或 folder 接受文件夹名/slug）
• 增加 list_folders 工具，返回 id/name/parent/文章数
• 或者文档里明确说明：MCP 只支持 category，folder 是 Web 专属

2. create_draft 和 import_content 参数不统一

现状：

• create_draft 需要 title + category + verification + request_id，不接受正文（试了 body/content/markdown/text 全报不支持）
• import_content 需要 format + content + title + category + request_id，不接受 verification

影响： 同一个"建草稿"动作有两套参数表，客户端要靠试错才能拼对。create_draft 建出来的是空草稿，还得再调 update_draft 填正文（而 update_draft 的正文参数名我到现在都没试出来）。

建议：

• 二选一：要么 create_draft 也接受 content，要么文档里写明"建带正文的草稿请用 import_content"
• 统一必填参数：request_id 在两个接口都必填，这个保持一致是好的，继续保持

3. publish_article 需要 6 个参数，太多

现状： 一次发布需要：document_id + expected_version + revision_id + confirm: true + change_summary + request_id，缺一个就报错。我是靠 5 轮试错才拼齐的。

建议：

• expected_version 和 revision_id 二选一即可（都是防并发覆盖，留一个）
• confirm 和 change_summary 可以合并：传了 change_summary 即视为确认
• 最简形态：document_id + request_id + change_summary 三个就够了

4. 错误信息不给正确参数名的提示

现状：

• 传错参数名只返回"不支持的参数：body"，不告诉你正确的是什么
• 缺参数只返回"缺少必填参数：category"，不告诉你还有哪些必填

建议：

• 错误信息里带上该工具的完整参数列表，例如：
  json复制

  {"code": "INVALID_ARGUMENT", "message": "不支持的参数：body", "valid_params": ["format", "content", "title", "category", "request_id", "tags", "source_url", "description"]}

• 缺参数时列出所有必填项，而不只报第一个缺的（我调 publish 时报了 5 次才集齐）

5. 缺少工具 schema 自省接口

现状： MCP 协议本身支持 tools/list 返回 inputSchema，但这个 server 的 tools/list 只返回了工具名列表，没有每个工具的参数定义。

建议：

• 在 tools/list 的返回里带上每个工具的 inputSchema（JSON Schema 格式）
• 这是 MCP 标准做法，客户端（Claude Desktop、各类 Agent 框架）都能自动适配，不用硬编码参数

6. tags / source_url / description 在 import_content 里可用但无文档

现状： 实测 import_content 接受 tags（数组）、source_url（字符串）、description，但：

• 传错时不报错（静默接受）
• 成功后 draft 状态下查不到是否生效（要 publish 后才能验证）
• 官方文档/工具描述里没提这些参数

建议：

• 在工具描述里列出所有可选参数
• import_content 的返回里带上已生效的 tags/source_url，让客户端当场确认

7. category 和 Web 端文件夹是两套体系，建议打通或明确边界

现状：

• API 侧：category（如 agent-engineering，英文 slug）
• Web 侧：文件夹（如"推送归档"，中文名）
• 两者无映射关系，客户端发的文章在 Web 端文件夹视图里找不到归属

建议：

• 短期：在文档里明确说明两者的关系（或无关系）
• 长期：考虑让 category 和文件夹打通，或在 API 返回里带上文章所属文件夹信息

8. 来源标识（provenance）建议标准化

场景： 多个 AI（Muse / Grok / Codex）都往同一个 wiki 推送，需要区分"这篇是谁发的"。

现状可用手段：

• tags：可打 ["muse", "每日推送"] 这样的标签（实测可用）
• source_url：可填原文链接（实测可用）
• description：可写来源说明

建议：

• 官方推荐一种标准做法（比如约定 tag 命名规范：source:muse）
• 或在文章元数据里加一个正式的 origin / author 字段，而不是靠 tags 约定

# 1. 建草稿（带正文）
import_content({
    "format": "markdown",
    "content": "# 标题\n\n正文...",
    "title": "晚报 2026-10-11",
    "category": "agent-engineering",
    "request_id": "uuid",
    "tags": ["推送", "晚报"],
    "source_url": "https://resource.vyibc.com/evening_2026-10-11.html",
    "description": "每日推送归档",
})
# → 返回 {id, revision_id, state: "draft", preview_url}

# 2. 查版本
get_document({"document_id": id})
# → {version, draft_revision_id}

# 3. 发布
publish_article({
    "document_id": id,
    "expected_version": version,
    "revision_id": draft_revision_id,
    "confirm": True,
    "change_summary": "...",
    "request_id": "uuid",
})
# → {state: "published", url: "/articles/..."}

文档生成：2026-10-12 · 测试客户端：Muse（via vyibc-wiki-editor skill）

9. import_content 不能指定 slug

现状： 三篇推送发过去，slug 被自动生成为 note-a33405b8、note-fb470a94 这种无意义的 uuid 缩写。而 wiki 里已有的推送文章 slug 是 push-2026-10-10-flash-noon 这种可读的。

建议：

• import_content 增加可选参数 slug，不传则自动生成（保持现状）
• slug 冲突时返回明确错误，而不是静默覆盖或生成随机后缀

10. update_draft 的正文参数名至今没试出来

现状： create_draft 建的是空草稿，理论上应该用 update_draft 填正文。但我试了 body/content/markdown/text 全都不认。最后被迫全用 import_content 一步到位。

建议：

• 要么文档写明 update_draft 的正文参数名
• 要么直接废弃 create_draft 的空草稿模式，统一走 import_content

11. 缺少批量操作接口

现状： 同步 3 篇推送 = 3 次 import_content + 3 次 get_document + 3 次 publish_article = 9 次 HTTP 调用。每天 4-5 次推送就是 20+ 次调用。

建议：

• 增加 batch_import：一次传多篇文章，返回 id 列表
• 或 publish_article 支持数组，一次发布多篇

12. 缺少幂等/去重机制

现状： request_id 是 per-request 的幂等，不是 per-content 的。如果定时任务重跑一次（网络超时重试、cron 重叠），会产生重复文章。没有"按 slug 查询是否存在"的便捷方法（get_article 需要确切 slug，search_articles 是模糊搜索）。

建议：

• import_content 增加 dedupe_by 参数（如按 slug 或 title+date 去重），已存在则返回现有 id 而不是新建
• 或在 request_id 语义上明确：同一个 request_id 重复调用返回上次的结果（真正的幂等）

13. 正文长度限制没有前置文档

现状： 报错才知道"正文需为 1–100000 个字符"。10 万字符对推送归档够用，但事先不知道。

建议：

• 在工具描述里写明限制
• 超限时考虑自动截断 + 警告，而不是直接报错（或提供分块上传）

14. verification 字段语义不明

现状： create_draft 必填 verification，我传了 "review" 通过了。但可选值有哪些？"review" 和 "auto" 有什么区别？对发布流程有什么影响？全靠猜。

建议：

• 文档列出枚举值和语义
• 如果 import_content 不需要它，说明为什么两个接口不一致

15. 预览链接需要登录，API 客户端看不到渲染效果

现状： import_content 返回的 preview_url 是 /studio/documents/.../review/，需要 wiki 登录态才能看。API 客户端发完后无法确认渲染是否正常（markdown 表格、代码块有没有炸）。

建议：

• 返回里带一个 rendered_html_preview（前 N 个字符），或
• 提供一个带 token 的免登录预览链接（有时效性）

16. 多 AI 推送的命名空间建议

场景： Muse / Grok / Codex 都往同一个 wiki 同步推送，需要避免 slug 冲突、分类混乱、互相覆盖。

建议：

• 约定 slug 前缀规范：muse-晚报-2026-10-11、grok-xxx、codex-xxx
• 或在 category 下再分一层：pushes/muse、pushes/grok
• 或文章元数据加正式的 origin 字段（见 P2-8），查询时可按来源过滤
• list_recent_articles 建议支持按 origin/来源过滤

第二批补充：2026-10-12 12:40 · 仍在实测中，想到就加

尚未填写外部来源；内容由作者自行整理。