[Feature Request] 建议增强原文读取、字段语义说明和 AI Agent 批量调用体验

[Sqiaow]

你好，我是 Get笔记 CLI 的真实用户，最近在用 Codex / AI Agent 通过 Get笔记 CLI 读取和整理自己的笔记、录音卡、知识库内容。整体感觉这个 CLI 对 AI Agent 场景很有价值，尤其是 API Key 登录、JSON 输出、搜索、知识库读取这些能力。

在实际测试中，我遇到了一些和“原文读取 / AI 总结 / 批量读取 / Agent 稳定调用”相关的问题，想反馈给官方，供后续迭代参考。

使用环境

• 系统：Windows
• CLI 版本：v1.1.8
• 使用方式：通过 getnote auth login --api-key ... --client-id ... 持久化登录
• 使用场景：让 AI Agent 通过 CLI 搜索、读取、总结、整理 Get笔记中的笔记、录音卡、知识库内容

1. 建议增强“原文”读取能力，尤其是录音类笔记

目前测试中，录音类笔记通过：

getnote note <note_id> -o json

可以拿到 content 和 attachments，但 content 更像是 AI 智能总结，attachments 是音频文件信息。

但在实际 Agent 场景里，用户经常会明确要求：

不要读 AI 总结，要读音频转文字后的原文。

目前 CLI 输出中似乎没有稳定暴露录音转写原文字段。我们通过底层接口测试发现，部分录音笔记中存在类似：

audio.original

这样的字段，里面是完整转写原文。

建议：

1. 在 getnote note <note_id> -o json 中暴露 audio.original，或提供等价字段。
2. 增加一个统一的原文读取命令，例如：

getnote note <note_id> --field original

或：

getnote note <note_id> --original

3. 对不同类型笔记统一返回：
   • original
   • original_source
   • original_length
   • summary
   • summary_source

这样 AI Agent 可以明确区分“原文”和“总结”。

2. 建议在文档中明确区分 content、web_content、post_media_text、audio.original

目前 README 中有示例：

getnote note 1234567890 --field content

这容易让用户或 Agent 误以为 content 一定是正文。

但实测中，不同内容类型的字段语义可能不同：

内容类型	原文可能字段	总结字段
普通文字笔记	content	content
链接/网页笔记	web_content	content
录音笔记	audio.original	content
知识库直播/文章	post_media_text	post_summary

建议在 README 或 docs 中增加“字段语义说明表”，明确告诉用户和 Agent：

• content 不一定是原文；
• 用户要求“原文”时，应优先读取哪个字段；
• 如果原文字段不存在，应如何处理。

3. 建议增加 inspect / metadata-only 这类 Agent 友好命令

在 AI Agent 场景下，直接读取完整正文可能会非常长，容易浪费上下文，也可能误读 AI 总结。

建议增加类似：

getnote note <note_id> --inspect

或：

getnote note <note_id> --metadata-only

返回：

{
  "note_id": "...",
  "title": "...",
  "note_type": "...",
  "has_original": true,
  "original_source": "audio.original",
  "original_length": 23854,
  "has_summary": true,
  "summary_length": 5315,
  "has_audio_attachment": true
}

这样 Agent 可以先判断字段可用性，再决定是否读取完整内容。

4. 建议优化知识库批量读取体验

测试知识库内容时，发现列表接口可能会返回较长的 content，而这些内容很多时候是 AI 总结，不适合作为 Agent 的第一步输入。

建议知识库列表命令支持：

getnote kb <topic_id> --metadata-only
getnote kb <topic_id> --preview 200
getnote kb <topic_id> --no-content

这样可以先列出标题、类型、ID、时间、标签，再由 Agent 按需读取详情。

另外建议确保：

• --limit 严格生效；
• 返回中明确包含 count、total、has_more、next_cursor 或 offset 信息；
• 文档中说明分页机制。

5. 建议提供批量读取的限速 / 重试机制说明

在 Agent 批量读取多个笔记详情时，如果请求过快，可能会触发限流。

建议：

1. 文档中说明推荐 QPS 或限速策略。
2. CLI 支持自动 retry/backoff。
3. 批量命令支持参数，例如：

getnote kb <topic_id> --all --delay-ms 1200

或在遇到 429 时自动等待并重试。

6. Windows 安装体验建议

我在 Windows 上安装官方 CLI 时，遇到过 Expand-Archive 相关问题，最后通过 npm ignore scripts + 手动放置 Windows 二进制解决。

建议：

1. README 中补充 Windows 常见安装问题排查。
2. postinstall 遇到 Expand-Archive 不可用时，提供 fallback。
3. 或明确推荐 Windows 用户直接下载 Release 中的 exe。

7. README 与 help 命令建议保持一致

测试中注意到 README 中提到过一些命令，但本地 getnote --help / getnote kb --help 中不一定都能看到。

建议后续版本保持：

• README 命令参考；
• getnote --help；
• getnote <subcommand> --help；

三者一致，方便 AI Agent 根据帮助文档自动调用。

[PemZhipengXie]

+1，补一些纯 OpenAPI 侧的实测细节帮 OP 加压。

针对录音类笔记（audio / meeting / local_audio）跑了一遍完整 schema：

getnote note <id> -o json 返回的 47KB JSON 里，逐字段翻完只有：

• content → AI 智能总结
• attachments[0].url → 带签名的 MP3 链接
• ref_content → 空字符串

没有任何字段暴露转写文字。OP 提到的 audio.original 在 OpenAPI 上没复现，怀疑是另一条底层接口。

但 share + /original 公开端点是存在的：

```bash

1. POST /open/api/v1/resource/note/sharing → 拿到 share_id

2. GET get-notes.luojilab.com/voicenotes/web/share/notes/{share_id}/original?acode=

→ 返回 c.content（嵌套 JSON），内含 sentence_list[{start_time, end_time, text}]

```

这条 endpoint 正是分享页"文字记录" tab 的数据源 —— 也就是说数据并非不可暴露，是 OpenAPI 没放出来。

最低诉求（和 OP 的方向一致）：

• 把 `share + /original` 的逻辑直接收进 OpenAPI 标准接口
• 或者 CLI 加 `getnote note --field original` / `getnote note transcript ` 封装这条路径

目前的状态是：用户要拿"自己音频的转写"必须做 3 步跨域名调用，其中第 3 步走的还是个未文档化的公开端点。希望能尽快规范化。

[PemZhipengXie]

自我纠错 — 上一条评论里 host 写错了，今天复测才发现。

我之前写的 https://www.biji.com/open/api/v1/resource/note/sharing 是 403。但 CLI 真实 baseURL 是 https://openapi.biji.com（在 internal/config/config.go 的 DefaultAPIBaseURL 里），换成这个 host 后 sharing 端点用 API Key 直接 200 通过。

完整可工作的两步流程：

# 1. 申请 share_id —— OpenAPI 端，需 API Key
curl -X POST "https://openapi.biji.com/open/api/v1/resource/note/sharing" \
  -H "Authorization: ${API_KEY}" \
  -H "X-Client-ID: ${CLIENT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"note_id":"<note_id>"}'
# → {"success":true,"data":{"share_id":"AgM79VdN5r8np","share_url":"https://..."}}

# 2. 拉逐字稿 —— 公开端点，无需鉴权
curl "https://get-notes.luojilab.com/voicenotes/web/share/notes/<share_id>/original"
# → c.content (嵌套 JSON) → sentence_list[{start_time, end_time, text}]

也就是说 sharing 端点 API Key 已有权限，问题完全在 CLI 没暴露这个端点，而不是 scope 缺失。

给维护者的诉求依旧成立：CLI 加一个 getnote note transcript <id> 命令封装这两步，对齐 getnote note --field content 的体验。现在用户要拉自己音频的逐字稿必须自己拼 HTTP 调用，对 Agent 集成场景不够友好。

50 行 Python 的本地实现可作为 PR 参考起点，已在 macOS 真机端到端跑通（152 句 / 33382 字逐字稿正常拉到）。