Zotero Code Execution

Zotero代码执行

使用代码执行模式的高效多策略Zotero搜索


技能安装

克劳德代码

1. 克隆或下载此存储库
2. 复制 skill/ 文件夹到您的Claude Code技能目录：

   cp -r skill ~/.claude/skills/zotero-mcp-code

1. 重启Claude Code加载技能

快速开始

import sys
sys.path.append('/path/to/zotero-code-execution')
import setup_paths
from zotero_lib import SearchOrchestrator, format_results

# Single comprehensive search - fetches 100+ items, returns top 20
orchestrator = SearchOrchestrator()
results = orchestrator.comprehensive_search("embodied cognition", max_results=20)
print(format_results(results))

就是这样！ 这会自动：

• ✅ 执行语义+关键字+标签搜索
• ✅ 消除重复结果
• ✅ 按相关性排名
• ✅ 将大型数据集保存在代码中（无崩溃）

多词搜索

对于OR风格的搜索（例如，多种拼写或语言），分别搜索每个词并合并：

# Search for "Atayal" OR "泰雅族"
all_results = {}

for term in ['Atayal', '泰雅族']:
    results = orchestrator.comprehensive_search(term, max_results=50)
    for item in results:
        all_results[item.key] = item  # Deduplicate by key

# Re-rank combined results
ranked = orchestrator._rank_items(list(all_results.values()), 'Atayal 泰雅族')
print(format_results(ranked[:25]))

为什么？ Zotero将多词查询视为AND条件。搜索“泰雅族泰雅族“查找与两个术语都匹配的项目，而不是任何一个术语。

为什么存在

问题

直接MCP工具调用有局限性：

• 🚫 崩盘风险 结果集较大（>15-20个项目）
• 🚫 代币膨胀 -所有结果都加载到LLM上下文中
• 🚫 手动编排 -多次搜索、手动重复数据删除
• 🚫 没有排名 -结果未按相关性排序

解决方案

代码执行将大型数据集保存在执行环境中：

• ✅ 无碰撞 -只有经过筛选的结果才能返回上下文
• ✅ 代币高效 -处理100+个项目，返回前20个
• ✅ 自动编排 -一次通话中的多策略搜索
• ✅ 自动排名 -按相关性排序的结果

特性

多策略搜索

一个函数调用执行：

• 语义搜索（多种变体）
• 关键字搜索（多种模式）
• 基于标签的搜索
• 自动重复数据删除
• 相关性排名

安全大搜索

# ❌ Old way: Crash risk
results1 = zotero_semantic_search("query", limit=10)  # Limited to 10
results2 = zotero_search_items("query", limit=10)     # Another 10
# Manual deduplication, manual ranking...

# ✅ New way: Safe and comprehensive
orchestrator = SearchOrchestrator()
results = orchestrator.comprehensive_search("query", max_results=20)
# Fetches 100+, processes in code, returns top 20

高级过滤

# Fetch broadly, filter in code
library = ZoteroLibrary()
items = library.search_items("machine learning", limit=100)  # Safe!

# Filter to recent journal articles
filtered = orchestrator.filter_by_criteria(
    items,
    item_types=["journalArticle"],
    date_range=(2020, 2025)
)

安装

需求

• Python 3.8+
• Zotero MCP 通过pipx安装
• Claude Code或类似的代码执行环境

设置

1. 克隆此存储库：

git clone https://github.com/yourusername/zotero-code-execution.git
cd zotero-code-execution

1. 安装依赖项（可选-通常已与Zotero MCP一起安装）：

pip install -r requirements.txt

1. 在代码中使用：

import sys
sys.path.append('/path/to/zotero-code-execution')
import setup_paths  # Adds zotero_mcp to path
from zotero_lib import SearchOrchestrator, format_results

使用示例

基本搜索

orchestrator = SearchOrchestrator()
results = orchestrator.comprehensive_search("neural networks", max_results=20)
print(format_results(results))

按作者筛选

library = ZoteroLibrary()
results = library.search_items("Kahneman", qmode="titleCreatorYear", limit=50)
sorted_results = sorted(results, key=lambda x: x.date, reverse=True)
print(format_results(sorted_results))

基于标签的搜索

library = ZoteroLibrary()
results = library.search_by_tag(["learning", "cognition"], limit=50)
print(format_results(results[:20]))

近期论文

library = ZoteroLibrary()
results = library.get_recent(limit=20)
print(format_results(results))

自定义筛选

library = ZoteroLibrary()
orchestrator = SearchOrchestrator(library)

items = library.search_items("AI", limit=100)

# Only recent papers with DOI
recent_with_doi = [
    item for item in items
    if item.doi and item.date and int(item.date[:4]) >= 2020
]
print(format_results(recent_with_doi))

看 examples.py 8个完整的工作示例。

克劳德代码技能

此存储库包含一个Claude Code技能，便于集成。

安装

将技能复制到您的Claude技能目录：

cp -r claude-skill ~/.claude/skills/zotero-mcp-code

用法

在Claude Code中，搜索将自动使用代码执行模式：

“查找关于具身认知的论文”

Claude将使用此库编写代码，而不是直接调用MCP。

看 claude技能/技巧.md 获取完整的技能文档。

API 参考

SearchOrchestrator

自动多策略搜索的主类。

comprehensive_search(query, max_results=20, use_semantic=True, use_keyword=True, use_tags=True, search_limit_per_strategy=50)

通过自动重复数据删除和排名执行全面搜索。

退货： 列表 ZoteroItem 物体

filter_by_criteria(items, item_types=None, date_range=None, required_tags=None, excluded_tags=None)

按各种条件筛选项目。

退货： 筛选列表 ZoteroItem 物体

ZoteroLibrary

Zotero的底层接口。

• search_items(query, ...) -关键字搜索
• semantic_search(query, ...) -语义/矢量搜索
• search_by_tag(tags, ...) -基于标签的搜索
• get_recent(limit) -最近添加的项目
• get_tags() -所有库标签

辅助函数

• format_results(items, include_abstracts=True, max_abstract_length=300) -格式为markdown

看 README_LIBRARY.md 获取完整的API文档。

建筑

基于 Anthropic使用MCP执行代码:

1. Claude编写Python代码 （非直接MCP呼叫）
2. 代码获取大型数据集 （100+项目）来自Zotero
3. 执行环境中的代码进程 （去噪、排序、筛选）
4. 仅筛选结果 返回LLM上下文（20个项目）

结果： 大型数据集脱离上下文，防止崩溃并节省令牌。

演出

预期效益

基于Anthropic的模式和实现设计：

• 代币减少： 50-90%（确切数量取决于搜索大小）
• 函数调用： 5-10x→ 1x（经设计确认）
• 搜索限制： 10-15 → 100+ 项目（代码安全）
• 防撞： 可能有效（未经测试）

状态

⚠️ 概念验证 -性能声明是理论预测，而不是测量结果。

看 荣誉_状态.md 了解详细的状态和验证需求。

文档

• README_LIBRARY.md -完整的图书馆文档
• 快速启动.md -快速参考指南
• CLAUDE_INSTRUCTIONS.md -克劳德代码说明
• examples.py -8个工作示例
• 实施\_ SUMMARY.md -技术细节
• 荣誉_状态.md -实施情况
• claude技能/技巧.md -Claude代码技能文档

贡献

欢迎投稿！需要改进的地方：

1. 性能验证 -衡量实际代币节省
2. 更好的排名 -结合语义相似性得分
3. 缓存 -缓存无效搜索结果
4. 并行处理 -同时执行搜索策略
5. 导出函数 -批量BibTeX生成，CSV导出

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

学分

• 基于 Zotero MCP
• 灵感源自 Anthropic使用MCP执行代码

相关项目

• Zotero MCP -底层MCP服务器
• 克劳德代码 -代码执行环境
• FastMCP -MCP服务器框架

引用

如果你在研究中使用这个，请引用：

@software{zotero_code_execution,
  title = {Zotero Code Execution: Efficient Multi-Strategy Search},
  year = {2025},
  url = {https://github.com/kerim/zotero-code-execution}
}