Use when the user wants to write current discussion, reading notes, quotes, questions, or AI summaries back into an existing Zotero item, including cases where the target item must first be resolved from title, author, quote, attachment, or source Markdown hints, and including optional requests to keep a local Markdown copy of the same note at the same time.
把 Agent Workspace 里的讨论结果整理成结构化 Zotero note，并尽量安全地写回到正确的 Zotero 条目下面。
核心策略是 search-first, cache-later：
source_markdown_path -> parent_item_key这版支持：
不要在这些情况下用：
zotero-cli-cc 可用ZOT_DATA_DIRZOT_LIBRARY_IDZOT_API_KEY脚本路径：
scripts/writeback_tool.pyscripts/writeback_from_search.pyscripts/save_local_copy.pyscripts/replay_runner.py优先整理成结构化 JSON，再执行搜索与写回。推荐字段：
titlefocussummarytagssource_quoteuser_pointsai_responsecollaborationlocatornote_granularitypoint_count_hint默认粒度规则：
atomiclocator 不再只是自由文本备注，默认按结构化字段处理。
最小可用形状：
{
"locator": {
"attachment_key": "ATTFAK01",
"library_scope": "library",
"group_id": null,
"page": 24,
"page_label": "24",
"annotation_key": null,
"attachment_type": "pdf",
"source_markdown_path": "C:/path/to/source.md"
}
}
字段含义：
attachment_key: PDF 附件 key。生成 PDF deep link 的必需字段library_scope: library 或 groupsgroup_id: 仅群组库需要page: 页码级跳转的页码page_label: 可选，控制链接展示文本annotation_key: 若已有 Zotero annotation，则升级为 annotation 级跳转attachment_type: 展示用，建议对 PDF 写 pdfsource_markdown_path: 溯源用默认使用 Zotero deep link，不使用本地文件绝对路径。
个人库：
zotero://select/library/items/<ITEM_KEY>zotero://open-pdf/library/items/<ATTACHMENT_KEY>?page=<PAGE>zotero://open-pdf/library/items/<ATTACHMENT_KEY>?page=<PAGE>&annotation=<ANNOTATION_KEY>群组库：
zotero://select/groups/<GROUP_ID>/items/<ITEM_KEY>zotero://open-pdf/groups/<GROUP_ID>/items/<ATTACHMENT_KEY>?page=<PAGE>zotero://open-pdf/groups/<GROUP_ID>/items/<ATTACHMENT_KEY>?page=<PAGE>&annotation=<ANNOTATION_KEY>降级规则：
annotation_key：写 annotation 级 PDF 链接annotation_key 但有 attachment_key + page：写页码级 PDF 链接page：只写条目链接attachment_key：只写条目链接第一阶段不要做：
保存模式：
zotero_onlybothlocal_only默认：
zotero_onlybothboth 模式下：
writeback_from_search.py 搜索目标条目writeback_tool.py 负责把 payload 渲染成 HTML notelocator 提供了页码或 annotation 信息，则在 note 中写入 Zotero deep linkboth 模式，先保存本地副本，再写回 Zotero搜索与预览：
python scripts/writeback_from_search.py `
"<source_markdown_path>" `
"<raw_query>" `
--cache-path "<cache.json>" `
--data-dir "C:\Zotero" `
--title "<title_hint>" `
--author "<author_hint>" `
--payload-path "<payload.json>" `
--writeback-script "scripts/writeback_tool.py"
正式写回：
python scripts/writeback_from_search.py `
"<source_markdown_path>" `
"<raw_query>" `
--cache-path "<cache.json>" `
--data-dir "C:\Zotero" `
--title "<title_hint>" `
--author "<author_hint>" `
--payload-path "<payload.json>" `
--writeback-script "scripts/writeback_tool.py" `
--auto-first `
--run-writeback `
--library-id "<library_id>" `
--api-key "<api_key>"
--auto-first 只在恰好 1 个候选时使用point_count_hint > 1，先拆分library_scope=groups，必须显式提供 group_id当前与新的 quote-to-annotation 流程协调时，默认直接使用上游返回的完整 locator，不再由 note-writeback 阶段重新推算坐标，也不只拆单个字段。
推荐的 locator 形状：
{
"locator": {
"attachment_key": "ATTFAK01",
"annotation_key": "ANNFAK01",
"attachment_type": "pdf",
"library_scope": "library",
"group_id": null,
"page": 135,
"page_number": 135,
"page_index": 134,
"page_label": "135",
"strategy": "ft-cache+tsv",
"coordinate_space": "pdf-bottom-left",
"source_coordinate_space": "pdftotext-top-origin",
"rects": [[216.7, 240.283, 524.89, 253.253]],
"raw_rects": [[216.7, 633.3, 524.89, 646.27]],
"match_quality": {
"exact_text": true,
"has_extra_text": false,
"extra_character_count": 0
},
"source_markdown_path": "C:/path/to/source.md"
}
}
协调规则：
attachment_key、page、annotation_key 以 locator 为准rects / raw_rects 是上游证据，note-writeback 不重算 rectsmatch_quality.exact_text=false 时，应标记为待审，而不是默认视为精确命中--locator-path <result.json>--locator-json <json> 注入locator.page 或 locator.annotation_key示例：
python scripts/writeback_from_search.py `
"<source_markdown_path>" `
"<raw_query>" `
--cache-path "<cache.json>" `
--payload-path "<payload.json>" `
--writeback-script "scripts/writeback_tool.py" `
--locator-path "C:\path\to\annotation-result.json" `
--auto-first `
--run-writeback `
--library-id "<library_id>" `
--api-key "<api_key>"
回复里至少说明：
search 还是 cache