尧图网页设计 
为什么是33个工具notebooklm-py MCP工具粒度取舍与Studio表面设计指南【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-pynotebooklm-py 是一款非官方的 Google NotebookLMGemini 笔记本Python API它把 NotebookLM 的完整能力通过 MCP 服务器开放给 Claude Code、Cursor 等 AI 智能体。当前 MCP 表面被刻意收敛在 33 个工具、8 个功能域管理笔记本、导入来源、智能问答、生成播客/视频/报告等 Studio 内容、深度研究与分享。这篇文章讲清楚一个关键设计问题为什么是 33 个而不是 40 个或 10 个先认识这个MCP服务器33个工具管什么MCPModel Context Protocol可以理解为AI 智能体与外部能力之间的标准插座装好 notebooklm-py 的 MCP 服务器后你的 AI 助手就能直接调用 NotebookLM 的 33 个工具——建笔记本、加资料、提问、生成播客、下载文件。33 个工具被组织成 8 个清晰的域每个域对应 NotebookLM 的一项核心能力域工具数代表工具干什么Notebooks 笔记本5notebook_list、notebook_create笔记本的增删改查Sources 来源10source_add、source_wait导入网页/文本/文件/YouTube 等资料Chat 问答4chat_ask、chat_status基于资料提问、慢速生成轮询Notes 笔记1note_save创建或更新笔记一次调用两用Studio 工作室7studio_generate、studio_download生成播客/视频/报告并下载Research 研究4research_start、research_import深度研究并导入结论Sharing 分享4share_set_user、share_set_access协作与权限管理Server 服务器1server_info版本、登录状态自检一个值得新手记住的通用约定所有引用都支持名字或ID——你传量子计算或Scientific唯一前缀都能命中对应笔记本歧义时工具会列出候选项让你重试。这让 AI和人都不必先记住一长串 UUID。33这个数字怎么来的合并而不是拆分如果打开项目的架构决策记录 ADR-0025MCP工具粒度你会看到完整的历史工具表面一度增长到 37 个然后团队用两次反向操作把它收回来了。第一次合并source_add_and_wait添加并等待和source_upload_bytes通道内传字节文件本质都是添加来源这一件事的不同侧面于是折叠回source_add的waittrue和bytes_base64参数——净减 2 个工具schema 少 3,099 字符。第二次合并studio_get_prompt查询单个产物的生成提示词与studio_list功能重复——列表工具本来就返回每个产物的generation_prompt。删掉它、并入studio_list(item…)——净减 1 个工具schema 再减 367 字符。合并到 33 后团队没有再往下压因为少不是目的边界清晰才是。拆分与合并的判断标准返回形状是否不同这是整篇 ADR 里最有复用价值的经验。团队的判断不是这个功能是不是同一件事而是——同一个工具会不会因为一个开关返回两种完全不同的结构source_add的添加等待只是多返回一个聚合统计返回形状兼容→ 合并为参数但chat_start发起慢速问答立即返回task_id与chat_ask同步等待答案返回的是两套无关结构如果合成一个detach 开关同一个工具名会有两种成功形态 →拆成独立工具与studio_generate/studio_status、research_start/research_status的启动器轮询器模式保持同构。对新手来说这套标准翻译成人话就是返回一样就合并返回不一样就拆开。为什么不拆大工具MCP协议的限制33 个工具里有两个典型的大工具source_add15 个参数和studio_generate20 个参数参数合法性要靠运行时校验器保证JSON Schema 表达不了完整契约。直觉上应该拆成source_add_url、source_add_file……但 ADR-0025 明确决定不拆原因有两个拆分 工具变多。业界证据Anthropic 的工具写作指南、GitHub 把 Copilot 工具从 40 个砍到 13 个都指向工具越少agent 选错率越低。拆分会把表面推破 40 的上限。MCP 协议2025-06-18 版没有服务端按需加载机制服务器必须把完整工具清单一次性交给客户端无法强制客户端延迟加载。所以拆细了再靠懒加载补救这条路在协议层走不通。替代方案很务实不拆但把文档字符串写得更精简、附每类示例并用自动化护栏盯着不让大工具继续长大。护栏长这样工具清单测试 test_manifest.py 钉死精确的工具名集合 40 的上限——任何增删改工具名都必须显式更新测试Schema 字符预算棘轮全表面 schema 总长度只能减不能增当前预算从 42,450 一路收紧到 39,050MAX_PARAMS_PER_TOOL 22单工具参数上限外加大工具不许再长大的专项测试。Studio表面把笔记和产物统一成一块面板Studio 是 NotebookLM 界面里笔记 生成产物合一的面板。最初的 MCP 设计把它拆成了 8 个artifact_*工具加 4 个note_*工具——这违背了产品自己的心智模型AI 必须先知道这个东西到底算笔记还是产物才能动手而笔记支持的心智图这种跨界实体以笔记创作、以产物呈现尤其别扭。ADR-0026MCP Studio表面 的解法是把两条读/删/改名路径统一studio_list把笔记和产物合并进同一个items列表用统一的连字符类型note | audio | video | report | quiz | mind-map | …区分studio_delete、studio_rename跨类型路由解析出是note就走笔记系统是产物就走产物系统笔记支持的心智图会被正确引回笔记路径笔记创作保留独立的note_saveupsert 语义不传引用创建传了引用更新。收益是 AI 不再需要预知领域一个解析器resolve_studio_item支持完整 ID、十六进制前缀、精确标题三种查找方式。实现代码在 tools/studio.py 等 18 个模块里每个模块都是核心业务逻辑之上的薄适配器与 CLI 共用同一套逻辑行为完全一致。33个工具如何保证AI用得安全、省心这套表面有几个对 AI 特别友好的设计细节见 docs/mcp-guide.md 的 Core concepts 一节安全标签只读工具带readOnlyHint宿主可自动放行notebook_delete、source_delete、studio_delete、share_remove_user四个危险工具带destructiveHint且必须有confirmtrue才真正执行——不带确认只返回预览什么都不删。统一变更信封所有同步变更工具返回顶层status字符串created/renamed/deleted/added…AI 用一套分支逻辑处理所有结果不用逐个工具学成功格式。长任务非阻塞studio_generate→studio_status→studio_download、research_start→research_status→research_import、chat_start→chat_status三种长任务同构拿到task_id轮询即可。结构化错误失败统一为CODE: message (retriable…)格式AUTH → run notebooklm login这类提示直接告诉 AI和人下一步该做什么。新手上手路径与延伸阅读跑起来pip install notebooklm-py[mcp]然后notebooklm login登录一次notebooklm mcp install claude-code或claude-desktop/cursor一条命令把配置写进客户端。读文档从 docs/mcp-guide.md 开始工具参考表覆盖了全部 33 个工具及其后续新增的参数说明。读设计ADR-0025 讲粒度取舍ADR-0026 讲 Studio 统一ADR-0024 讲远程文件传输的签名 URL 旁路。看代码工具实现在 src/notebooklm/mcp/tools/ 下按域分文件护栏在 tests/unit/mcp/test_manifest.py。一句话总结33 不是拍脑袋的数字而是合并优先、按返回形状决策、护栏兜底这三条原则作用后的结果。工具少而边界清晰AI 的调用准确率才会高——这正是 notebooklm-py MCP 表面最值得借鉴的设计经验。【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为什么是33个工具？notebooklm-py MCP工具粒度取舍与Studio表面设计指南
为什么是33个工具notebooklm-py MCP工具粒度取舍与Studio表面设计指南【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-pynotebooklm-py 是一款非官方的 Google NotebookLMGemini 笔记本Python API它把 NotebookLM 的完整能力通过 MCP 服务器开放给 Claude Code、Cursor 等 AI 智能体。当前 MCP 表面被刻意收敛在 33 个工具、8 个功能域管理笔记本、导入来源、智能问答、生成播客/视频/报告等 Studio 内容、深度研究与分享。这篇文章讲清楚一个关键设计问题为什么是 33 个而不是 40 个或 10 个先认识这个MCP服务器33个工具管什么MCPModel Context Protocol可以理解为AI 智能体与外部能力之间的标准插座装好 notebooklm-py 的 MCP 服务器后你的 AI 助手就能直接调用 NotebookLM 的 33 个工具——建笔记本、加资料、提问、生成播客、下载文件。33 个工具被组织成 8 个清晰的域每个域对应 NotebookLM 的一项核心能力域工具数代表工具干什么Notebooks 笔记本5notebook_list、notebook_create笔记本的增删改查Sources 来源10source_add、source_wait导入网页/文本/文件/YouTube 等资料Chat 问答4chat_ask、chat_status基于资料提问、慢速生成轮询Notes 笔记1note_save创建或更新笔记一次调用两用Studio 工作室7studio_generate、studio_download生成播客/视频/报告并下载Research 研究4research_start、research_import深度研究并导入结论Sharing 分享4share_set_user、share_set_access协作与权限管理Server 服务器1server_info版本、登录状态自检一个值得新手记住的通用约定所有引用都支持名字或ID——你传量子计算或Scientific唯一前缀都能命中对应笔记本歧义时工具会列出候选项让你重试。这让 AI和人都不必先记住一长串 UUID。33这个数字怎么来的合并而不是拆分如果打开项目的架构决策记录 ADR-0025MCP工具粒度你会看到完整的历史工具表面一度增长到 37 个然后团队用两次反向操作把它收回来了。第一次合并source_add_and_wait添加并等待和source_upload_bytes通道内传字节文件本质都是添加来源这一件事的不同侧面于是折叠回source_add的waittrue和bytes_base64参数——净减 2 个工具schema 少 3,099 字符。第二次合并studio_get_prompt查询单个产物的生成提示词与studio_list功能重复——列表工具本来就返回每个产物的generation_prompt。删掉它、并入studio_list(item…)——净减 1 个工具schema 再减 367 字符。合并到 33 后团队没有再往下压因为少不是目的边界清晰才是。拆分与合并的判断标准返回形状是否不同这是整篇 ADR 里最有复用价值的经验。团队的判断不是这个功能是不是同一件事而是——同一个工具会不会因为一个开关返回两种完全不同的结构source_add的添加等待只是多返回一个聚合统计返回形状兼容→ 合并为参数但chat_start发起慢速问答立即返回task_id与chat_ask同步等待答案返回的是两套无关结构如果合成一个detach 开关同一个工具名会有两种成功形态 →拆成独立工具与studio_generate/studio_status、research_start/research_status的启动器轮询器模式保持同构。对新手来说这套标准翻译成人话就是返回一样就合并返回不一样就拆开。为什么不拆大工具MCP协议的限制33 个工具里有两个典型的大工具source_add15 个参数和studio_generate20 个参数参数合法性要靠运行时校验器保证JSON Schema 表达不了完整契约。直觉上应该拆成source_add_url、source_add_file……但 ADR-0025 明确决定不拆原因有两个拆分 工具变多。业界证据Anthropic 的工具写作指南、GitHub 把 Copilot 工具从 40 个砍到 13 个都指向工具越少agent 选错率越低。拆分会把表面推破 40 的上限。MCP 协议2025-06-18 版没有服务端按需加载机制服务器必须把完整工具清单一次性交给客户端无法强制客户端延迟加载。所以拆细了再靠懒加载补救这条路在协议层走不通。替代方案很务实不拆但把文档字符串写得更精简、附每类示例并用自动化护栏盯着不让大工具继续长大。护栏长这样工具清单测试 test_manifest.py 钉死精确的工具名集合 40 的上限——任何增删改工具名都必须显式更新测试Schema 字符预算棘轮全表面 schema 总长度只能减不能增当前预算从 42,450 一路收紧到 39,050MAX_PARAMS_PER_TOOL 22单工具参数上限外加大工具不许再长大的专项测试。Studio表面把笔记和产物统一成一块面板Studio 是 NotebookLM 界面里笔记 生成产物合一的面板。最初的 MCP 设计把它拆成了 8 个artifact_*工具加 4 个note_*工具——这违背了产品自己的心智模型AI 必须先知道这个东西到底算笔记还是产物才能动手而笔记支持的心智图这种跨界实体以笔记创作、以产物呈现尤其别扭。ADR-0026MCP Studio表面 的解法是把两条读/删/改名路径统一studio_list把笔记和产物合并进同一个items列表用统一的连字符类型note | audio | video | report | quiz | mind-map | …区分studio_delete、studio_rename跨类型路由解析出是note就走笔记系统是产物就走产物系统笔记支持的心智图会被正确引回笔记路径笔记创作保留独立的note_saveupsert 语义不传引用创建传了引用更新。收益是 AI 不再需要预知领域一个解析器resolve_studio_item支持完整 ID、十六进制前缀、精确标题三种查找方式。实现代码在 tools/studio.py 等 18 个模块里每个模块都是核心业务逻辑之上的薄适配器与 CLI 共用同一套逻辑行为完全一致。33个工具如何保证AI用得安全、省心这套表面有几个对 AI 特别友好的设计细节见 docs/mcp-guide.md 的 Core concepts 一节安全标签只读工具带readOnlyHint宿主可自动放行notebook_delete、source_delete、studio_delete、share_remove_user四个危险工具带destructiveHint且必须有confirmtrue才真正执行——不带确认只返回预览什么都不删。统一变更信封所有同步变更工具返回顶层status字符串created/renamed/deleted/added…AI 用一套分支逻辑处理所有结果不用逐个工具学成功格式。长任务非阻塞studio_generate→studio_status→studio_download、research_start→research_status→research_import、chat_start→chat_status三种长任务同构拿到task_id轮询即可。结构化错误失败统一为CODE: message (retriable…)格式AUTH → run notebooklm login这类提示直接告诉 AI和人下一步该做什么。新手上手路径与延伸阅读跑起来pip install notebooklm-py[mcp]然后notebooklm login登录一次notebooklm mcp install claude-code或claude-desktop/cursor一条命令把配置写进客户端。读文档从 docs/mcp-guide.md 开始工具参考表覆盖了全部 33 个工具及其后续新增的参数说明。读设计ADR-0025 讲粒度取舍ADR-0026 讲 Studio 统一ADR-0024 讲远程文件传输的签名 URL 旁路。看代码工具实现在 src/notebooklm/mcp/tools/ 下按域分文件护栏在 tests/unit/mcp/test_manifest.py。一句话总结33 不是拍脑袋的数字而是合并优先、按返回形状决策、护栏兜底这三条原则作用后的结果。工具少而边界清晰AI 的调用准确率才会高——这正是 notebooklm-py MCP 表面最值得借鉴的设计经验。【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考