first commit

文档润色Agent.md

@@ -0,0 +1,287 @@
+# 文档润色 Agent 与 Claude Scholar 学术插件快速索引
+
+问题开始时间：2026-06-11-03-26-41
+
+资料来源：
+- GitHub 仓库：<https://github.com/Galaxy-Dawn/claude-scholar>
+- 本地下载目录：`文档润色流和知识库构建流/claude-scholar`
+- 本次核对的 GitHub HEAD：`34d0cdb48a03080c7243841e19ff03ef30967d97`
+- 重点阅读文件：`README.zh-CN.md`、`CLAUDE.zh-CN.md`、`MCP_SETUP.zh-CN.md`、`OBSIDIAN_SETUP.zh-CN.md`、`agents/*.md`、`skills/*/SKILL.md`、`commands/*.md`、`rules/*.md`
+
+## 1. 总体定位
+
+`claude-scholar` 是面向学术研究和软件开发的半自动研究助手插件。它的核心路线是：
+
+```text
+问题 -> 证据 -> 实验 -> 分析 -> 论断 -> 写作
+```
+
+它不负责替代研究者做最终判断，而是把文献整理、证据台账、项目知识库、论文或标书写作、引用核验、审稿回复、结果分析等重复但高要求的环节结构化。
+
+对“文档润色流”的价值主要有五点：
+- 把模糊主题拆成研究问题、证据需求、假设和下一步动作；
+- 用 Zotero 和 Obsidian 把资料沉淀成可追溯知识库；
+- 用 claim-evidence gate 防止无证据论断进入正式文本；
+- 用 paper-miner、writing-anti-ai、nature-polishing 等技能辅助润色；
+- 用 paper-self-review、citation-verification 做提交前自审。
+
+## 2. 安装与使用入口
+
+### 2.1 完整安装
+
+```bash
+git clone https://github.com/Galaxy-Dawn/claude-scholar.git /tmp/claude-scholar
+bash /tmp/claude-scholar/scripts/setup.sh
+```
+
+说明：
+- `main` 分支面向 Claude Code；
+- Codex CLI 应参考仓库的 `codex` 分支；
+- Kimi Code CLI 和 OpenCode 也分别有对应分支；
+- 完整安装会安装 skills、commands、agents、rules、hooks 等组件，并尽量保留用户已有配置。
+
+### 2.2 插件市场安装
+
+```text
+/plugin marketplace add Galaxy-Dawn/claude-scholar
+/plugin install claude-scholar@claude-scholar
+```
+
+注意：
+- 插件市场会加载 skills、commands、agents 和 hooks；
+- `rules/` 需要手动复制；
+- 插件不会自动合并已有 `CLAUDE.md` 或自动配置 `settings.json`；
+- Zotero MCP、Obsidian vault 等外部集成仍需手动配置。
+
+### 2.3 手动选择性安装
+
+适合只需要文档润色与学术写作能力时：
+
+```bash
+cp -r /tmp/claude-scholar/skills/research-ideation ~/.claude/skills/
+cp -r /tmp/claude-scholar/skills/ml-paper-writing ~/.claude/skills/
+cp -r /tmp/claude-scholar/skills/citation-verification ~/.claude/skills/
+cp -r /tmp/claude-scholar/skills/writing-anti-ai ~/.claude/skills/
+cp -r /tmp/claude-scholar/skills/paper-self-review ~/.claude/skills/
+cp -r /tmp/claude-scholar/skills/doc-coauthoring ~/.claude/skills/
+cp /tmp/claude-scholar/agents/paper-miner.md ~/.claude/agents/
+cp /tmp/claude-scholar/agents/literature-reviewer.md ~/.claude/agents/
+```
+
+## 3. Agent 快速索引
+
+Agent 通常由 Claude Code 根据触发描述自动调度。用户侧最稳妥的调用方式是自然语言明确说明任务，或使用相应 slash command 间接触发。
+
+| Agent | 主要功能 | 何时使用 | 典型调用 |
+|---|---|---|---|
+| `literature-reviewer` | 检索论文、导入 Zotero、创建主题 collection、读取全文、综合文献、识别 research gap | 新研究主题、文献综述、研究空白分析、proposal 前期 | “请围绕 X 做系统文献综述”；`/research-init "topic" focused both`；`/zotero-review "collection" deep` |
+| `paper-miner` | 从 PDF、DOCX、arXiv 或论文网页中提炼写作模式、段落结构、venue-specific signals、rebuttal 策略 | 学习优秀论文、获批标书、Nature/NeurIPS 写法 | `/mine-writing-patterns path/to/paper.pdf introduction`；“请从这篇论文中提炼可复用写作结构” |
+| `rebuttal-writer` | 解析审稿意见，分类 Major/Minor/typo/misunderstanding，选择 Accept/Defend/Clarify/Experiment 策略，写逐点回复 | 审稿回复、修改说明、专家意见答复 | `/rebuttal review-comments.md`；“请帮我逐条回应评审意见” |
+| `kaggle-miner` | 从 Kaggle 竞赛和优胜方案中抽取工程路线、模型策略、best practices、代码模板 | 需要从竞赛方案学习技术路径 | “Learn from this Kaggle competition: URL” |
+| `code-reviewer` | 审查 git diff 中的安全、质量、性能、测试覆盖、硬编码密钥等问题 | 修改代码后、提交前 | `/code-review`；“请 review 当前改动” |
+| `tdd-guide` | 以 RED -> GREEN -> REFACTOR 推进测试驱动开发 | 明确要求 TDD 或风险较高功能 | `/tdd 实现 X`；“请先写失败测试再实现” |
+
+## 4. 学术写作与文档润色 Skill 索引
+
+| Skill | 功能 | 文档润色中的用法 |
+|---|---|---|
+| `research-ideation` | 5W1H、研究问题定义、gap analysis、method selection、research planning | 把标题或方向拆成科学问题、研究假设、证据需求、证伪条件和最小下一步 |
+| `doc-coauthoring` | 大型文档协作写作，包含上下文收集、结构搭建、逐节打磨、读者测试 | 用于标书、proposal、技术方案、决策文档的分节共写 |
+| `ml-paper-writing` | 面向顶会论文的写作、相关工作、引用核验和 claim ledger | 借用其 claim-evidence 纪律，避免把计划、动机或猜测写成已证实结论 |
+| `nature-writing` | 根据 claims、figures、results、notes 或中文草稿重建 Nature 风格章节 | 起草 abstract、introduction、results narrative、discussion |
+| `nature-polishing` | 将稿件润色、重组或翻译为更接近 Nature 风格的精炼英文 | 中英文学术段落精炼、hedging、逻辑顺序调整 |
+| `nature-response` | Nature 系修回逐点回复 | 处理 editor letter、reviewer comments、revision notes |
+| `nature-data` | Data Availability、repository plan、FAIR metadata | 写数据可用性、数据仓库方案和受限数据说明 |
+| `citation-verification` | 核验 DOI、arXiv、CrossRef、Semantic Scholar、Zotero 元数据和论断-引用对齐 | 写作时逐条核查参考文献是否真实、是否支撑对应论断 |
+| `writing-anti-ai` | 去除中英文 AI 写作痕迹，减少空泛套话、机械排比和过度连接词 | 标书和论文润色最后一轮使用，使表达自然但不过度口语化 |
+| `paper-self-review` | 投稿或提交前结构、逻辑、引用、图表、合规性、过度声称检查 | 提交标书或论文前做 claim audit 和结构自审 |
+| `review-response` | 审稿意见分析与 rebuttal 工作流 | 对评审意见、专家修改建议做分类和逐条回应 |
+| `publication-chart-skill` | 论文级图表和表格工作流 | 机制图、技术路线图、实验结果图表的质量控制 |
+| `latex-conference-template-organizer` | 整理会议 LaTeX 模板为 Overleaf-ready 结构 | 论文投稿模板整理 |
+| `zotero-obsidian-bridge` | 把 Zotero 作为文献源，向 Obsidian KB 写入 `Sources/Papers`、`Knowledge`、`Writing` | 文献笔记、证据记录、相关工作草稿联动 |
+
+## 5. Slash Command 快速索引
+
+### 5.1 研究启动与文献
+
+| Command | 用途 | 示例 |
+|---|---|---|
+| `/research-init` | 初始化研究主题，创建或审计 Zotero collection，生成 research question card，证据足够时才生成 proposal | `/research-init "static magnetic field exosome macrophage polarization" focused both` |
+| `/zotero-review` | 读取 Zotero collection，生成文献综述、方法分类、研究空白、相关工作草稿 | `/zotero-review "ATC-MagneticField" deep` |
+| `/zotero-notes` | 批量读取 Zotero collection 并写详细论文笔记 | `/zotero-notes "ATC-MagneticField" detailed` |
+| `/mine-writing-patterns` | 从论文或标书中抽取写作模式并更新 paper-miner 全局写作记忆 | `/mine-writing-patterns path/to/grant.pdf proposal` |
+
+### 5.2 写作、润色与回复
+
+| Command | 用途 | 示例 |
+|---|---|---|
+| `/rebuttal` | 生成带证据锚点的逐点审稿回复 | `/rebuttal review-comments.md` |
+| `/presentation` | 生成会议报告结构和讲解指导 | `/presentation paper.md 20min` |
+| `/poster` | 整理论文内容并生成海报版式与内容指导 | `/poster paper.md` |
+| `/promote` | 起草社交媒体、博客或外部传播摘要 | `/promote paper.md` |
+
+### 5.3 Obsidian 项目知识库
+
+| Command | 用途 |
+|---|---|
+| `/kb-init` | 初始化 `Research/{project-slug}/` 项目知识库 |
+| `/kb-status` | 汇总当前 KB 绑定、registry 和关键路径 |
+| `/kb-ingest` | 将新资料路由到 `Sources/Papers`、`Sources/Web`、`Sources/Docs` 等 |
+| `/kb-log` | 更新当天 `Daily/`、必要时更新 plan/hub/project memory |
+| `/kb-sync` | 确定性刷新 scaffold、registry、index、daily、绑定状态 |
+| `/kb-links` | 修复或增强 canonical notes 之间的 wikilink |
+| `/kb-promote` | 将稳定内容从 Daily 或 source note 提升到 `Knowledge`、`Writing` 等 |
+| `/kb-index` | 刷新 `02-Index.md` 自动索引块 |
+| `/kb-lint` | 检查断链、registry 覆盖、index 覆盖、canvas 有效性 |
+| `/kb-archive` | archive、detach、purge、rename KB 对象 |
+| `/kb-map` | 生成或修复 literature canvas、可选 Bases 或其他显式图谱 |
+| `/kb-literature-review` | 从 `Sources/Papers` 生成证据门槛下的文献综合和 `Maps/literature.canvas` |
+
+### 5.4 代码、验证与项目维护
+
+| Command | 用途 |
+|---|---|
+| `/analyze-results` | blocker-first 实验分析，证据足够时生成统计、图表和结果报告 |
+| `/verify` | 类型检查、lint、测试、安全扫描、git 状态 |
+| `/code-review` | 对未提交改动做安全和质量审查 |
+| `/tdd` | 测试驱动开发 |
+| `/commit` | 本地 Conventional Commit，不推送 |
+| `/update-github` | commit 并推送到远程 |
+| `/checkpoint` | 创建或验证工作流 checkpoint |
+
+## 6. Zotero MCP 调用方法
+
+Zotero MCP 是 `literature-reviewer`、`/research-init`、`/zotero-review`、`/zotero-notes` 的核心外部能力。
+
+Codex CLI 配置示例：
+
+```toml
+[mcp_servers.zotero]
+command = "zotero-mcp"
+args = ["serve"]
+enabled = true
+
+[mcp_servers.zotero.env]
+ZOTERO_API_KEY = "your-api-key"
+ZOTERO_LIBRARY_ID = "your-user-id"
+ZOTERO_LIBRARY_TYPE = "user"
+UNPAYWALL_EMAIL = "your-email@example.com"
+UNSAFE_OPERATIONS = "all"
+NO_PROXY = "localhost,127.0.0.1"
+```
+
+常用工具：
+- 导入：`zotero_add_items_by_identifier`、`zotero_add_items_by_doi`、`zotero_add_items_by_arxiv`、`zotero_add_item_by_url`
+- 读取：`zotero_get_collections`、`zotero_get_collection_items`、`zotero_search_items`、`zotero_get_item_metadata`、`zotero_get_item_fulltext`
+- 更新：`zotero_create_collection`、`zotero_move_items_to_collection`、`zotero_reconcile_collection_duplicates`
+- PDF：`zotero_find_and_attach_pdfs`、`zotero_add_linked_url_attachment`
+
+默认导入策略：
+1. 优先抽取 DOI、arXiv ID、publisher landing page 或 PDF URL；
+2. 使用 `zotero_add_items_by_identifier` 导入；
+3. 导入时尝试自动附加 PDF；
+4. 导入后运行 collection 去重；
+5. abstract-only 或 webpage-placeholder 不能支撑稳定写作论断。
+
+## 7. 推荐的文档润色流程
+
+### 7.1 标书或论文初稿前
+
+```text
+research-ideation
+  -> Research Question Card
+  -> Evidence Records
+  -> Gap Analysis
+  -> Proposal Readiness Gate
+```
+
+建议口令：
+
+```text
+请使用 research-ideation，把这个题目拆成研究问题、研究假设、证据需求、证伪条件、研究内容和最小下一步。
+```
+
+### 7.2 资料与文献入库
+
+```text
+Zotero / local PDFs / web sources
+  -> Sources/Papers 或 Sources/Docs
+  -> Evidence Record
+  -> Knowledge synthesis
+  -> Writing draft
+```
+
+建议口令：
+
+```text
+请把这些论文作为 Sources/Papers 入库，逐篇生成 Evidence Record。只有证据足够的论断才能提升到 Knowledge 或 Writing。
+```
+
+### 7.3 学习优秀文本
+
+```text
+paper-miner
+  -> structure signals
+  -> reusable phrasing
+  -> venue-specific signals
+  -> global writing memory
+```
+
+建议口令：
+
+```text
+请用 paper-miner 分析这份获批标书，提炼可迁移的章节结构、论证节奏和常用表达。不要复制具体疾病背景或未核实数据。
+```
+
+### 7.4 段落润色
+
+先做证据检查，再做语言润色：
+
+```text
+paper-self-review / citation-verification
+  -> claim audit
+  -> writing-anti-ai / nature-polishing
+  -> final wording
+```
+
+建议口令：
+
+```text
+请先检查这段话中哪些论断需要证据，给出 keep / weaken / revise / remove，再用 writing-anti-ai 风格润色，保留学术严谨性。
+```
+
+## 8. 对本项目的使用建议
+
+- 不要直接把 `claude-scholar` 当成“医学标书自动生成器”；它原生偏 CS/AI 研究，更适合借用流程纪律。
+- 对标书写作，最重要的是 `research-ideation`、`doc-coauthoring`、`citation-verification`、`paper-self-review`、`writing-anti-ai`、`paper-miner`。
+- 任何疾病背景、材料性能、实验结论、政策数据或文献事实都应进入 Evidence Record，再进入正文。
+- 可以复用优秀标书的结构、论证顺序、段落功能和语气，但不要复用未经核实的事实性论断。
+- 文档最终提交前至少做三轮检查：引用核验、claim audit、AI 痕迹润色。
+
+## 9. 最小调用清单
+
+```text
+1. 新主题：
+   /research-init "topic" focused both
+
+2. 文献集合综述：
+   /zotero-review "collection-name" deep
+
+3. 批量论文笔记：
+   /zotero-notes "collection-name" detailed
+
+4. 学习优秀写法：
+   /mine-writing-patterns path/to/source.pdf proposal
+
+5. 知识库入库：
+   /kb-ingest path/to/source.pdf
+
+6. 文献综合：
+   /kb-literature-review
+
+7. 标书/论文自审：
+   请使用 paper-self-review 做 claim audit。
+
+8. 去除 AI 痕迹：
+   请使用 writing-anti-ai 润色以下段落。
+```