From a85d576865b8f1e25145cfd3c57a62133b21dd47 Mon Sep 17 00:00:00 2001
From: qyh15 <qyh15@users.noreply.local>
Date: Wed, 27 May 2026 20:14:00 +0800
Subject: [PATCH] Document QQnote workflow boundary

---
 README.md | 145 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 99 insertions(+), 46 deletions(-)

diff --git a/README.md b/README.md
index a0d745d..7d50f84 100644
--- a/README.md
+++ b/README.md
@@ -1,83 +1,125 @@
-# MYwrite
+# QQnote-skill
 
-这是一个用于 Zotero 和 Obsidian 文献阅读流程的 Codex skill。普通使用者不需要手动运行脚本，只需要在 Codex 里用自然语言提出任务，AI 会根据 `SKILL.md` 和配套脚本完成检查、生成、批处理或维护工作。
+QQnote-skill is a Zotero + Obsidian literature-note tool for Codex. It generates
+AI literature notes from Zotero items, writes them as Zotero child notes, audits
+missing generated notes, and maintains Obsidian literature-note views.
 
-## 适合做什么
+QQnote is intentionally narrow: it prepares literature-note inputs. It does not
+decide manuscript novelty, target-journal positioning, strong/weak related-paper
+status, reviewer risk, or citation necessity. Those decisions belong to QQsci
+when QQnote is used inside the QQsci workflow.
 
-- 在 Zotero 中为文献生成 AI 阅读笔记。
-- 把生成结果写成 Zotero 子笔记，而不是直接写到 Obsidian 文件夹。
-- 检查哪些 Zotero 条目还没有生成 AI 笔记。
-- 按指定条目、指定集合或小批量方式继续生成笔记。
-- 维护 Obsidian 文献阅读库、模板和 Dataview 视图。
-- 在不暴露 Zotero、DeepSeek 或 AwesomeGPT 密钥的前提下完成自动化处理。
+## Core Workflows
 
-## 使用前准备
+### Initialize Private Config
 
-- 打开 Zotero Desktop。
-- 确认 Zotero Local API 可用。
-- 确认 Obsidian 文献库路径为 `C:\Users\qyh15\Documents\Obsidian Vault`。
-- 确认 Zotero Web API key 和 DeepSeek/AwesomeGPT 配置已经放在本地私有配置中。
-- 不要把真实 API key 发到聊天、README、日志或任何会提交到仓库的文件里。
+Use local-only config for Zotero and DeepSeek/AwesomeGPT keys:
 
-私有配置模板位于：
+```powershell
+py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\init_private_config.py"
+```
+
+The committed template is:
 
 ```text
 config/config.template.json
 ```
 
-真实配置应保存在本地忽略文件：
+The real local file is:
 
 ```text
 config/config.local.json
 ```
 
-## 对 AI 的常用指令
+Do not commit `config/config.local.json`, print secrets, or paste API keys into
+chat.
 
-可以直接在 Codex 里这样说：
+### Generate Zotero Child Notes
 
-```text
-使用 MYwrite skill，检查我的 Zotero 文库里哪些文献还没有生成 AI 阅读笔记。
+```powershell
+py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
 ```
 
-```text
-使用 MYwrite skill，为这个 Zotero 条目生成一条 AI 阅读笔记：SXAIQUJT。
+Use this when a Zotero item needs an AI-generated child note. For long runs,
+prefer small batches and rerun with `--skip-existing` after interruptions.
+
+For deeper notes, use the full-detail mode supported by the installed script,
+for example:
+
+```powershell
+py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --mode deep --fulltext-chars 80000 --max-tokens 12000 --replace-existing
 ```
 
-```text
-使用 MYwrite skill，为这个 Zotero 条目重新生成满血版深度阅读笔记：SXAIQUJT。覆盖已有 AI 子笔记，不要新建重复笔记。
+### Audit Missing Generated Notes
+
+```powershell
+py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
 ```
 
-```text
-使用 MYwrite skill，给这些 Zotero 条目批量生成 AI 阅读笔记：SXAIQUJT、X7GJZ627、ZCZXGRAM。
-```
+Use deterministic audit scripts for library state. Do not ask DeepSeek to decide
+which Zotero items are missing notes.
+
+## Relationship With QQsci
+
+When used by QQsci:
+
+1. QQsci identifies which literature inputs are needed.
+2. QQnote generates or refreshes Zotero child notes.
+3. QQsci performs keyword extraction, strong/weak related-paper screening,
+   target-journal positioning, comparative audit, manuscript revision, and Word
+   DOI-only citation comments.
+
+QQnote should not decide whether a paper is strongly related, weakly related,
+required for citation, or sufficient as reviewer evidence.
+
+QQsci may call QQnote through a wrapper that injects QQsci-level DeepSeek and
+Zotero configuration into QQnote's expected environment variables.
+
+## Standalone Configuration
+
+QQnote must also remain usable independently. In standalone mode it reads:
+
+- process environment variables
+- local private config
+- vault `.env`, if supported by the installed script
+- AwesomeGPT/Zotero profile preferences
+
+Expected environment variables include:
+
+- `AWESOMEGPT_API_KEY`
+- `AWESOMEGPT_BASE_URL`
+- `AWESOMEGPT_MODEL`
+- `ZOTERO_API_KEY` for Zotero Web API writes
+- `ZOTERO_USER_ID` when needed
+
+Never store API keys in `SKILL.md`, references, committed files, zip files,
+terminal output, or chat. If keys appear in chat or logs, rotate them.
+
+## Obsidian Notes
+
+Read these references before modifying Obsidian behavior:
+
+- `references/obsidian-integration.md`
+- `references/obsidian-literature-maintenance.md`
+
+Default vault:
 
 ```text
-使用 MYwrite skill，从上次中断的位置继续生成文献笔记，跳过已经生成过的条目。
+C:\Users\qyh15\Documents\Obsidian Vault
 ```
 
-```text
-使用 MYwrite skill，帮我检查 Obsidian 文献阅读库的 Dataview 页面是否能正确展示 Zotero 笔记。
-```
+Default organization includes:
 
-```text
-使用 MYwrite skill，整理我的文献阅读模板，让后续生成的 Zotero 子笔记更适合 Obsidian Dataview 使用。
-```
+- `00 Templater`: source templates, prompts, and audit cache
+- literature-note folders exported or linked from Zotero
+- Dataview dashboards for browsing literature
 
-## 批处理建议
-
-整库生成会向 Zotero 写入大量子笔记。除非已经明确确认目标文库和写入范围，否则不要要求 AI 直接处理整个 Zotero 文库。
-
-更稳妥的方式是每次处理 20-30 篇文献，并要求 AI 跳过已经生成过笔记的条目。这样即使中途失败，也可以继续执行而不会重复写入。
-
-如果需要和手动 AwesomeGPT 生成结果接近的详细笔记，请明确告诉 AI 使用“满血版”或“深度精读”模式。该模式会读取更多全文内容，并要求模型输出更完整的结构化笔记。
-
-重新生成笔记时，默认应覆盖已有 AI 子笔记，不要新建重复笔记。只有在明确需要对比两个版本时，才让 AI 另存为新的 Zotero 子笔记。
-
-## 仓库内容
+## Repository Contents
 
 ```text
 .
 |-- SKILL.md
+|-- README.md
 |-- agents/
 |   `-- openai.yaml
 |-- config/
@@ -92,3 +134,14 @@ config/config.local.json
     |-- generate_zotero_ai_note.py
     `-- init_private_config.py
 ```
+
+## Installed Location
+
+For Codex discovery, install under:
+
+```text
+C:\Users\qyh15\.codex\skills\QQnote-skill
+```
+
+Keep source and installed copies synchronized when updating scripts or
+documentation.