背景

使用腾讯 IMA（智能工作台）管理健康数据时，长生孙思邈 agent 需要将每日体重记录追加到 IMA 笔记。在调试过程中遇到了一系列 API 写入失败的问题，本文完整记录调试过程与最终解决方案。

问题描述

• append_doc 和 import_doc 均返回：code: 210003, msg: "AppendDoc Markdown2Json fail"
• 读取操作（list_note_by_folder_id、get_doc_content）完全正常，但写入操作全部失败
• 内容无论是纯文本、中文、带 # 标题语法，均报同样错误

调试过程

Step 1：抓包分析响应头

发现写入 API 响应头包含浏览器专属字段：From_browser_ima、X-Ima-Bkn、Extension_version。误以为写 API 需要额外的浏览器会话 token。

Step 2：分析 X-Ima-Bkn 猜测

加上 X-Ima-Bkn header 后，错误从 Markdown2Json fail 变成了 skill auth failed，说明该 header 参与了 auth 校验但不是根本原因。

Step 3：换新 Key 测试

在 IMA Agent Interface 页面重新生成 API Key。使用新 Key 测试 import_doc — 结果全部成功！关键发现：旧 key 在生成新 key 时被 revoke 了。

Step 4：验证 append_doc 与 Markdown 表格限制

新 key 的 import_doc 完全正常。但 append_doc 对体重笔记写入 Markdown 表格时报 Markdown2Json fail。用不同内容测试：plain text / bold / heading — 均成功。最终确认：append_doc 不支持 Markdown pipe table 语法。

根因总结

• append_doc 不支持 Markdown 表格语法（| col1 | col2 |）。支持的格式：标题、段落、列表、bold 等行内样式
• 列表格式可以正常写入，列表项前加序号可实现类表格效果
• 旧 API Key 在生成新 Key 时被服务器端 revoke，所以写入全部失败（旧 key 测试返回 500 + skill auth failed）
• 响应字段名 note_id 不等于请求参数 doc_id（容易混淆）