Skip to content

feat: updateNote API 应支持 body 参数,与 createNote 保持一致 #60

Description

@renshen052

背景

在使用 MCP Server 的 yuque_update_note 工具时,发现更新小记的 API 参数与创建小记不一致,导致无法用相同方式传入内容。

问题

创建小记 (POST /api/v2/notes) 接受 body 字段:

{ "body": "# 标题\n\n正文内容" }

更新小记 (PUT /api/v2/notes/{id}) 不接受 body,必须传入 sourcehtmlabstract 三个字段:

{
  "source": "# 标题\n\n正文内容",
  "html": "<h1>标题</h1><p>正文内容</p>",
  "abstract": "# 标题\n\n正文内容"
}

这意味着调用方必须自行将 markdown 转换为 HTML,否则接口返回 html,source,abstract invalid 错误。

尝试过的方案

方案一:直接传 body(失败)

尝试让 updateNotecreateNote 一样只传 body

await client.updateNote(noteId, { body: args.body });
// → API 返回: html,source,abstract invalid

API 不接受此参数,直接报错。

方案二:自行将 markdown 转为 HTML(放弃)

在 MCP Server 端实现 markdown → HTML 转换:

const html = markdownToHtml(args.body);
await client.updateNote(noteId, {
  source: args.body,
  html,
  abstract: args.body.substring(0, 200),
});

放弃原因:

  1. 转换不可靠:完整的 markdown 规范非常复杂(嵌套列表、表格、代码块、数学公式等),在 MCP Server 端用正则实现无法保证与语雀渲染结果一致
  2. 维护负担:语雀支持的 markdown 扩展语法会变化,MCP Server 端的转换逻辑需要持续跟进
  3. 重复劳动:语雀服务端本身已有完善的 markdown 解析能力,客户端再实现一遍毫无意义
  4. abstract 截断粗暴:直接 substring(0, 200) 可能截断在 UTF-8 多字节字符中间,或截断 markdown 语法标记

期望

希望 PUT /api/v2/notes/{id} 接口也能像创建接口一样支持 body 参数:

{ "body": "# 标题\n\n正文内容" }

由语雀服务端负责 markdown → HTML 的转换,与创建接口行为保持一致。这样 MCP Server(以及所有第三方集成)可以统一用 body 传入内容,无需自行处理 HTML 转换。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions