← Vibe Researching 主页  ·  English version

如何使用本手册

本手册是两小时工作坊《Vibe Researching with Coding Agents》的学员配套材料。它不是讲稿的复刻版，而是一份你可以按自己节奏在自己电脑上完成的实操教程：从“Claude 还没装”开始，到产出一份基于真实 CFPS 数据、经过验证的 Social Forces 风格论文草稿结束。

每一节大致都包含五个固定要素：

1. 目标 — 学完本节你应该能做到什么。
2. 输入什么 — 完整的命令、提示词或代码，统一放在代码块中。如果一行以 $ 开头，就在终端中输入（不要带 $）；如果以 > 开头，就在已经启动的 Claude Code 会话中输入。
3. 应该看到什么 — 真实但精简过的终端输出，方便你判断有没有走对。
4. 检查什么 — 智能体跑完后你需要打开并读完的文件。
5. 停一下，自检 — 进入下一节之前你需要回答的问题。

贯穿全书的案例是真实的：基于六波 CFPS 微观数据（2010–2020）写作的 Social Forces 风格论文《中国数字鸿沟》。每一条命令、每一张图、每一个表、每一条验证发现，都来自 2026 年 5 月真实跑过的项目——包括最关键的七个 CRITICAL 错误，它们是这门工作坊存在的理由。

手册分为四部分：

• 第一部分：基础（工作坊第一小时） —— 安装智能体，开启第一个会话，理解项目结构，写出能让智能体执行的提示词，并速览 Claude Code 的新能力 —— 动态工作流、子智能体与自动化（§5A）。
• 第二部分：Open Scholar Skills 全流程（工作坊第二小时） —— 全部 44 个技能的完整参考：每一种模式、每一个参数、每一道关卡、每一份产出文件，按你真实使用的顺序编排，并全程以 CFPS 数字鸿沟为载体。§5B 是技能总表，先读它，之后随时回来查。
• 第三部分：编排器 —— 当你要写一篇真正认真的论文时（scholar-full-paper、scholar-auto-research）、如何找回自己的位置（scholar-resume）、如何无人值守地跑一整队想法（scholar-loop）、如何审计技能套件自身（scholar-auto-improve），以及如何拿到另一家厂商模型的独立第二意见（scholar-openai）。
• 第四部分：负责任的实践 —— 自查清单、常见错误、五条原则。

如果你已经在用 Claude 或 Codex，可以略读第一部分，从 §5B（技能总表）或第 6 节 scholar-init 直接开始；如果是零基础，每一步都要做。

把第二部分当参考手册用。 每个技能的小节结构都一样：逐字照抄自技能自身 frontmatter 的 argument-hint 参数语法、所有模式的表格、内部工作流、准确的产出文件路径、会拦住你的关卡、以及已记录在案的坑。凡是「某条规则之所以存在，是因为某次真实运行翻过车」的地方，都会写明是哪一次、哪一天 —— 这些段落即使你不用那个技能也值得读。

第一部分：基础

1. 什么是“氛围式研究”，以及不是什么

“AI 一旦碰到你的文件，我们就不再是在随便聊天，而是在设计研究工作流。”

氛围式研究（Vibe Researching）是指：在真实研究项目中调用编码型智能体（Claude Code 或 Codex CLI），让它执行有边界的研究任务、留下可检查的产物，而问题、标准、责任始终归你掌握。

氛围式研究 不是：

• “帮我写一篇关于 X 的论文。”（让智能体同时编造问题、数据和叙述——保证产出漂亮但空心的草稿。）
• “帮我找一个显著结果。”（同时外包假设和证据标准——本质是 p-hacking 的升级版。）
• “听起来挺有道理就直接信。”（流畅的散文不等于已验证的散文。）

氛围式研究 是：

• “这是允许读取的数据边界，这是要回答的研究困惑，这是证据标准，这是必须产出的产物，这是必须停下来问我的条件。”

智能体的三种力量

把权限当作研究方法，不是软件设置。智能体的读取边界 = 你的数据边界；联网边界 = 你的隐私边界；写入边界 = 你的可复现边界。

Claude 与 Codex 的分工

本手册有意使用两个智能体，因为我们不希望同一个模型既当作者又当分析者还当审稿人。

• Claude Code —— 编排者。多步骤技能、文字起草、计划模式、项目记忆都很强。我们用它当主流程引擎。
• Codex CLI —— 外部审查者。代码补丁、统计实现、独立审计很强。我们用它做第二把关人。

第一天不必两个都装。先用 Claude。

2. 安装 Claude Code 与 Codex

目标： 在终端里输入 claude 或 codex 时能进入一个可用的智能体。

2.1 前置依赖

• macOS、Linux 或 Windows（WSL2）
• Node.js ≥ 18（推荐 20 LTS），用于 Claude Code
• 一个终端（Terminal.app、iTerm2 或 Windows Terminal）
• 一个 Anthropic API key（或 Claude Pro/Max 订阅）+ 一个 OpenAI API key（用于 Codex）
• 可选：R 4.3+ 与 Python 3.11+，因为多数 scholar-skills 在它们上面跑分析

实验用的 notebook 找 key 的方式和 Claude Code 不一样，这一点常把人绊住。 Claude Code 和 Codex 各自登录各自的。四个实验 notebook 用的不是那两个登录， 它们按下面的顺序解析 provider，谁先能用就用谁：

	Provider	怎么找到它
1	OpenAI（本工作坊默认）	OPENAI_API_KEY，否则读单行的 labs/openai.txt
2	本地 Ollama	127.0.0.1:11434 上的服务 —— 免费、私密、不需要 key
3	Anthropic	ANTHROPIC_API_KEY
4	GLM / Z.ai	ZAI_API_KEY
5	离线	内置的 [OFFLINE FALLBACK] 答案，保证每个 cell 仍然能跑完

所以 notebook 里报 “The api_key client option must be set” 时，通常一行就能解决 （在仓库根目录执行）：

printf '%s' 'PASTE_YOUR_KEY_HERE' > labs/openai.txt
chmod 600 labs/openai.txt

labs/openai.txt 已被 gitignore，也必须一直保持如此。如果你一分钱都不想花， 那就跑 ollama serve，notebook 会直接用它，完全不需要 key。完整步骤见课前准备 指南（teaching/03-pre-workshop-setup.md）。

Windows 用户请注意： 本节命令默认你已经在 macOS、Linux 或类 Unix 的 shell 里。如果你用的是 Windows，不要直接在 PowerShell 或 cmd.exe 里跑这些命令。先翻到 附录 K —— Windows 安装指引，按它一步步把 WSL2（Windows Subsystem for Linux）与 Ubuntu 装好。等你在 WSL2 里有了一个能用的 Ubuntu shell，§2 与 §3 的所有命令都能直接照搬，无需修改。每台机器只需要读一次附录 K。

检查 Node 版本：

$ node --version
v20.11.0

如果没有或版本太低，装 nvm 然后 nvm install 20。

懒得手动装一堆东西？ 只要 Claude Code 或 Codex 跑起来了（哪怕你机器上只有 Node），就可以让智能体替你安装 Python、R、Git 以及社会科学常用包栈。具体提示词见 §2.7 ——「让智能体替你安装研究工具链」。

2.1A 账号、订阅、API key —— 最容易混淆的三件事

付费有两条完全不同的路，而且两者不能互相替代。这一点几乎每个人都会踩，所以最后一行请读两遍。

最后一行是最花时间的那一行。 ChatGPT Plus 订阅不会给你 API key；Claude Pro 订阅也 不会给实验 notebook 任何可用的东西。订阅是把你本人认证给某个 App；而 notebook 是 你自己的 Python 在调 API，那需要一个 key（或者一个本地模型，见 §2.1）。

开通 Claude 订阅（给 Claude Code 用）。 打开 claude.ai 注册，然后进 Settings → Plans。Pro 是入门档；Max 把用量上限抬高——第三天全班同时跑 agent 的时候，这个差别 很明显。之后运行 claude，选 Login with Anthropic Console，不需要 key。

申请 Anthropic API key（另一条路）。 打开 console.anthropic.com → API Keys → Create Key，立刻复制（只显示一次），然后到 Billing 里充值——新开的 console 余额为零，不充值调用会直接报计费错误。当前每 token 价格见 定价页；截至 2026 年 8 月，Claude Opus 5 是每百万 input / output token $5 / $25，Claude Haiku 4.5 是 $1 / $5。

让 Codex 跑起来。 要么用 ChatGPT Plus/Pro 账号登录（codex login，选浏览器登录），要么在 platform.openai.com/api-keys 建一个 OpenAI key 粘贴进去。 OpenAI 的 API 计费和 ChatGPT 订阅是分开的——余额为零的坑同样适用。

这个工作坊到底需要什么。 Claude Code，两条路都行。Codex，两条路都行，而且只有第四天做外部 review 时才用。实验 notebook 需要的是放在 labs/openai.txt 里的 OpenAI API key——或者干脆 什么都不需要：跑 ollama serve，本地、免费，如果你不想花钱，我们推荐这条。

成本，说实话。 四天的实验跑在默认的 gpt-4o-mini 上，总共远不到一美元。真正花钱的是第 三、四天的 agent，那才是 Max 订阅或充值 console 的用武之地。如果是自掏腰包，就把实验跑在 Ollama 上，把预算留给 agent 那两天。

2.2 安装 Claude Code

$ npm install -g @anthropic-ai/claude-code
$ claude --version
2.0.x

第一次启动会引导你认证：

$ cd ~/Documents/projects/digital-divide-china-cfps   # 先 cd 进项目目录
$ claude

 ┌──────────────────────────────────────────────────────┐
 │  Welcome to Claude Code                              │
 │  Choose authentication method:                       │
 │   1) Login with Anthropic Console                    │
 │   2) Use ANTHROPIC_API_KEY                           │
 └──────────────────────────────────────────────────────┘

永远从项目目录里启动 claude。 那个目录就是它的工作根目录，权限边界从此处划定。

2.3 安装 Codex CLI

$ npm install -g @openai/codex
$ codex --version
codex-cli 0.130.0   # 截至 2026-05 的版本，你的可能更新
$ codex login    # 输入 OpenAI API key

2.3A 桌面 App —— 比 CLI 更友好的另一条路

现在两家都出了桌面应用：同一个编码智能体，套在窗口式界面里，让你不碰 npm、不开终端也能上手。如果上面的 CLI 安装卡住了 —— 没装 Node、PATH 配不对、公司电脑权限被锁 —— 桌面 App 就是最快把一个能用的智能体摆到你面前的办法。

目标： 用对你这台机器最省事的那条路，先让一个能用的 Claude Code 或 Codex 智能体跑起来。

Claude Code 桌面版（macOS / Windows）。 从官方页面下载安装包：

• https://claude.com/download

桌面版自带 Claude Code —— 你不需要单独装 Node.js 或 CLI。像装普通应用一样安装（macOS 拖进 Applications；Windows 跑 .exe），打开后用你的 Anthropic 账号登录（Pro/Max 订阅，或 Console 登录）。需要 macOS 11（Big Sur）或更高版本。首次上手指引见 https://code.claude.com/docs/en/desktop-quickstart。

Codex App（macOS / Windows）。 从 OpenAI 官方页面下载：

• https://developers.openai.com/codex/app

选 macOS 版本（Apple 芯片或 Intel）或 Windows 版本；Windows 用户也可以在 Microsoft Store 里装。打开后用你的 ChatGPT 账号登录（Plus / Pro / Business / Edu / Enterprise 都含 Codex），或填 OpenAI API key。这个 App 能并行跑多个 Codex 线程，内置工作树（worktree）、自动化与 Git 支持。

你应当看到： 一个窗口式的智能体，能打开文件夹、读写文件、跑命令、操作 git —— 跟 CLI 一样的能力，只是用按钮代替了敲键。

第三个桌面智能体 —— ZCode（Z.ai）。 如果这两家的付费方式对你都不合适，Z.ai 出了 ZCode：一个基于 GLM-5.2 的桌面智能体，它能读取 Claude Code 的 skills，因此可以直接跑 open-scholar-skill 套件。这是另一家公司的产品，有自己的配置体系，也有自己的数据管辖含义，所以单独讲：见 §2.6.7。

让桌面 App 替你把 CLI 装上。 §2.2 里那几条 npm 命令，你不必自己敲。桌面 App 打开后，用大白话吩咐它 —— 「在我这台机器上装好 Claude Code CLI，再一步步带我登录」 —— 智能体会检查你的 Node 版本、跑安装程序、修好 PATH，最后把一个能用的 claude 命令交到你手里。这跟它后面替你搭整套研究工具链（§2.7）是同一个智能体；只不过这次，它先给自己搭好了终端的家。

…… 但这次工作坊，还是请你把 CLI 也装上、用起来。 桌面 App 用来「第一次接触」和日常工作都很棒，工作坊之后你尽可以继续用。要你也花十分钟去终端练手，不是因为桌面版弱 —— 到现在它也能读你的文件、跑代码、在一次会话里记住上下文、连上 MCP server，跟 CLI 一模一样。真正的理由，是有那么几件事，图形界面从结构上就做不到。桌面 App 需要一块屏幕、需要一个人点鼠标；而 CLI 只是文字进、文字出，凡是有 shell 的地方它都能跑：

• 无界面 / 远程。 CLI 能通过 SSH 跑在没接显示器的实验室服务器或 HPC 集群上。当受限数据不能离开一台安全机器时，你是把智能体带到数据跟前 —— 这对一个需要图形桌面会话的窗口 App 来说根本做不到。
• 可脚本化。 claude -p "……" 能塞进 shell 脚本、Makefile 或 cron 定时任务，于是智能体成了流水线里一个自动化步骤，而不是一个点按钮的人。
• 无人值守、可放大规模。 用 tmux/nohup 起的长任务或并行任务，会比你这次会话活得更久 —— 合上笔记本，两百次模型调用照跑一整夜。
• 能和 Unix 组合。 它的输入输出可以直接用管道、重定向接进 git、grep、R、awk —— 无缝落进你本来就在用的科研计算工具链。
• 文字即可复现。 每一个动作都是一条可记录、可版本管理、可重跑的命令，同事能原样复现你一模一样的流程；而点一下鼠标什么痕迹都不留。

还有两条工作坊层面的理由：在 CLI 上学到的一切都能原样搬回桌面 App（反过来则未必）；而且教材都默认终端 —— 插件安装（§2.4）要跑 shell 脚本 setup.sh，钩子（§5A）、.claude/settings.json、MCP 接线也全是可直接复制粘贴的命令。

所以：如果今天靠桌面 App 才能不卡壳，那很好 —— 用它，或者让它替你把 CLI 装上。但也请让 claude（最好连 codex）在终端里跑起来，因为从 §2.4 开始，后面都默认你能在 $ 提示符下敲命令、在会话里用 > 发提示词。

2.4 安装 open-scholar-skill 插件

技能不是 Claude Code 自带的，需要从仓库 clone 下来再跑安装脚本。仓库在 https://github.com/joshzyj/open-scholar-skill，里面带 .claude-plugin/ 清单和一个 setup.sh —— 由它把 skills、agents 与 PreToolUse 数据安全 hook 注册进 Claude Code。

两个版本 —— 你装的是哪个，决定了哪些技能存在。

版本	仓库	技能数	获取方式
公开版	github.com/joshzyj/open-scholar-skill	35	公开 —— §2.4 装的就是它
扩展版	openscholarskills	44	按需申请 —— 向作者索取

本手册按扩展版来写，因为它是超集。有九个技能只存在于扩展版：

scholar-full-paper · scholar-resume · scholar-loop · scholar-presentation · scholar-image · scholar-grant · scholar-teach · scholar-book · scholar-exemplar-curate

相关章节都标了 [扩展版]。第二部分其余内容在公开版上完全一样能用 —— 包括从分析到验证的整条核心链（scholar-init → scholar-design → scholar-analyze → scholar-write → scholar-verify → scholar-citation），而工作坊真正的论点就在这条链上。在公开版上，按第二部分的顺序逐个跑这些技能即可；§21 的编排器只是同一条链的便利封装，不是另一套方法。

随时可以查你装的是哪个：

$ ls ~/.claude/skills/ | grep -c scholar     # 公开版 35 · 扩展版 44

装的方式有两种。如果 git、SSH 钥匙、shell 脚本对你来说还陌生，用新手快捷路径（§2.4.0）—— 让 Claude Code 自己装。如果你想看每一条命令，用 §2.4.1–§2.4.5 的手动路径。

也可以按插件来装。 该仓库同时发布了 marketplace 清单，所以 claude plugin marketplace add joshzyj/open-scholar-skill 加上 claude plugin install open-scholar-skill@open-scholar 两条命令就能拿到 skills 和 agents；ZCode 走的也是这条路（§2.6.7）。但它不能替代 setup.sh：插件写不了那三样落在仓库之外的东西 —— 带 Zotero 与 CrossRef 配置的 .env、技能里 shell 脚本的可执行位，以及 ~/.claude/settings.json 里的 PreToolUse 数据安全 hook。工作坊请照常 clone 并跑 setup.sh；插件路线更适合当作「在第二台机器上先快速铺好、随后照样补跑 setup.sh」的捷径。

2.4.0 新手快捷路径——让 Claude Code 帮你装

装好 Claude Code（§2.2）并在任意目录启动后，把下面这段提示词贴进去：

> 请把 open-scholar-skill 插件从
>   https://github.com/joshzyj/open-scholar-skill
> 安装到本机的 Claude Code 里。把它 clone 到
>   ~/.claude/plugins/open-scholar-skill
> 然后运行它的 setup.sh，安装缺失的依赖（git、jq、python3），
> 装完后列出所有 scholar-* 命令做一次验证。
> 任何需要 sudo 或者要写到 ~/.claude 之外的地方，
> 都先停下来问我。

Claude 会读 repo 的 README，跑 git clone、执行 setup.sh、装缺的工具（每一步会向你要权限），装完用 /help 自检。任何失败都会把具体报错说出来——你读 transcript，不必背命令。最终状态与手动路径完全一致。

新手路径的安全规则

1. Claude Code 起在 default 权限模式（不是 bypassPermissions），这样每一步装的时候它仍会问你。Status line 看一眼是不是 default，不是的话按 Shift+Tab 切换。
2. agent 要用 sudo 的时候，读清楚它想装什么再点 y。插件本身不需要 sudo——只在 Linux 上装 jq / python3 才可能用到。
3. agent 报告连不上 github.com、或者某个依赖连试三次都装不上，就改走手动路径——这些失败通常需要人去看你本机的 shell、proxy、PATH。

Claude 装完后，跳到 §2.4.4 自检一下，再去 §3。

2.4.1 前置依赖：git

安装过程依赖 git。先确认装了并配置过：

$ git --version            # 任意 2.x 都行
$ git config --global user.name  "Your Name"
$ git config --global user.email "you@example.com"

如果没有 git：

• macOS： xcode-select --install（Apple 自带 git）或 brew install git
• Ubuntu / Debian / WSL： sudo apt install git

如果以后要 pull 私有仓库，再加一把 SSH key：

$ ssh-keygen -t ed25519 -C "you@example.com"
$ cat ~/.ssh/id_ed25519.pub
# 把输出粘进 github.com → Settings → SSH and GPG keys

2.4.2 安装：clone + 跑 setup

$ git clone https://github.com/joshzyj/open-scholar-skill.git
$ cd open-scholar-skill
$ bash setup.sh

setup.sh 会做六件事：

1. 建好 .claude/skills/ 与 .claude/agents/ 的内部 symlink。
2. 自动探测你的 Zotero 库；探测不到会提示你输入路径。
3. 可选地配置 BibTeX、EndNote 以及 CrossRef 邮箱（用于 API 的 polite pool）。
4. 把你这个版本里的全部技能（公开版 35 · 扩展版 44）与相应 agent 装成个人级 skills，落在 ~/.claude/skills/ 与 ~/.claude/agents/ —— 这样 /scholar-* 在任何目录、任何 Claude Code 会话里都能用，而不只是在 clone 出来的仓库里。
5. 把 scripts/gates/pretooluse-data-guard.sh 注册为 ~/.claude/settings.json 中的 PreToolUse hook —— 拦截每一次 Read、NotebookRead、NotebookEdit、Grep、Glob，对 NEEDS_REVIEW:* 或 HALTED 的文件直接拒绝。
6. 写一个 .env 文件记录你的配置。

依赖： bash、python3、jq。先装 jq —— 数据安全 hook 缺了它会 fail-closed，也就是说在你装上之前，每一次数据读取都会被拦。Presidio 是可选的（用于基于 NER 的 PII 检测）：python3 -m pip install presidio-analyzer presidio-anonymizer。

如果 setup.sh 报缺依赖，装上（macOS：brew install jq；Linux：sudo apt install jq python3）再重跑。

第 2 步是最常被跳过的一步，而它会悄无声息地拖垮半套工具。 这里探测到的文献库，正是 scholar-write 起草时要对着写的东西、scholar-citation 在 Tier 1 校验的依据、scholar-lit-review 在碰网络之前先搜的地方，也是 scholar-exemplar-curate 采集段落范例的来源。配错了不会报错 —— 你只会得到全部来自网络的引用和一堆平庸的行文。§14.0 讲怎么验证它真的生效了。

2.4.3 以后更新

$ cd open-scholar-skill
$ git pull
$ bash setup.sh    # 幂等；刷新 symlink 与 hook 注册

2.4.4 验证

任意项目目录里启动 Claude Code：

> /help

应该能看到一长串 scholar-* 命令。再做个快速检查：

> /scholar-init --help

能打印帮助即可进入 §3。

2.4.5 排错

• /help 里看不到 skills —— symlink 没装好。回到 clone 目录，重跑 bash setup.sh，看是否出现 ▸ Checking symlinks... 段落。
• PreToolUse hook 拦了一个本不该拦的文件 —— 这是数据安全闸门在工作。用 /scholar-init review 解决，不要禁用 hook。

• 公司代理后面 —— 用带 token 的 HTTPS：

  $ git clone https://<token>@github.com/joshzyj/open-scholar-skill.git
  

  或者下载 ZIP 解压后再跑 setup.sh。

2.5 setup.sh 到底做了什么 —— 逐步走一遍

目标： 在跑之前就知道会发生什么、七个提问分别在问什么、跑完怎么判断它真的成功了。

setup.sh 是交互式的。它会问六到七个问题，每一个都能直接回车跳过。它也是幂等的 —— 重跑是安全的，而且这正是官方推荐的修复方式。预留三分钟。

有一处设计值得先说，因为它解释了这个脚本的许多行为：脚本故意不用 set -e。它自己的头注释写了原因 —— 交互式 read 在 EOF 时会返回非零（比如把 /dev/null 管进去，或者在 CI 里跑），而在 set -e 下这会让安装中途夭折。于是每一步各自检查自己的退出状态，尽力往下走。对你的影响是：中途出现一条警告并不等于安装失败，你必须读最后的总结，而不能把「没报错」当成「成功了」。

2.5.1 七个步骤，按顺序

1 —— 符号链接。 ▸ Checking symlinks... 建两个仓库内的便捷链接：skills/ → .claude/skills/ 与 agents/ → .claude/agents/。如果链接存在但指向了意料之外的地方，会被修复；如果那个名字下坐着一个真实目录，脚本会拒绝删除它，并让你自己去挪。它不会为了腾地方而毁掉你的文件。

2 —— Zotero 自动探测。 ▸ Looking for Zotero library... 按顺序探测七个位置，找 zotero.sqlite（或 .sqlite.bak）：

~/Zotero                              ~/Library/CloudStorage/*/zotero
~/Documents/Zotero                    ~/Library/CloudStorage/*/Zotero
~/snap/zotero-snap/common/Zotero      ~/Google Drive/zotero
                                      ~/Google Drive/Zotero

然后它问：

  Auto-detected Zotero at: /Users/you/Zotero
  Use this path? [Y/n] or enter a different path:

三种有效回答：回车或 Y 表示接受；n 表示完全跳过 Zotero；或者你粘一个别的路径。如果你粘的路径不存在，它会警告并保留自动探测到的那个，而不是默默接受一个坏路径。如果一开始就什么都没找到，它会让你输一个路径，留空则跳过。

3 —— 可选的文献管理器。 连着四个提问，每个都能回车跳过：

4 —— 知识图谱目录。 默认 ~/.claude/scholar-knowledge，回车接受即可。这就是 §8C 里那个用户级、跨项目的图谱 —— 你所有论文共用一个，刻意不放在任何单个项目里面。

5 —— 先查 jq，再问 Presidio。 ▸ Checking jq... 这一段是真的要读的：

  ⚠ jq is NOT installed.
    ... the guard falls back to a minimal sed-based parser and fails CLOSED
    on data files — every Read of a .csv/.dta/.xlsx will be blocked
    with "install jq" until jq is available.

这不是一句软性提醒。没有 jq，数据守卫会拦掉每一次数据读取。装上再重跑。

接着会问是否装 Presidio，用于在内置正则之外做基于 NER 的 PII 检测（人名、地址、实体）。它大约需要 500 MB，默认是不装。如果你同意，脚本会装 presidio-analyzer、presidio-anonymizer 与 spaCy 的 en_core_web_lg，然后冒烟测试 presidio_anonymizer 是否真的能 import —— 因为 pip install 成功并不等于这个包在当前解释器上真的可用。不装也完全没问题，会退回正则检测，以后随时能补。

6 —— .env 文件。 写入之前，已有的 .env 会被拷成 .env.bak.<时间戳>，并提示你把手工加过的变量重新补回去。脚本绝不会默默覆盖一个你可能手改过的文件。结果长这样：

SCHOLAR_SKILL_DIR="/path/to/open-scholar-skills"
SCHOLAR_ZOTERO_DIR="/Users/you/Zotero"
SCHOLAR_BIB_PATH=""
SCHOLAR_ENDNOTE_XML=""
SCHOLAR_CROSSREF_EMAIL="you@university.edu"
HF_TOKEN=""
SCHOLAR_KNOWLEDGE_DIR="/Users/you/.claude/scholar-knowledge"

7 —— 装成个人级 skills。 这一步正是 /scholar-* 能在任何目录下可用的原因。它在 ~/.claude/skills/ 与 ~/.claude/agents/ 里为每个技能、每个 agent 各建一条符号链接 —— 而不是把整个目录换成一条指向仓库的链接。由此带来三个后果，都是好的：

• 你自己已有的 ~/.claude/skills/my-thing/ 不会被动；scholar-* 条目是并排装进去的。
• 如果某个 scholar-* 名字下已经坐着一个真实（非符号链接）目录，脚本会跳过并明确告诉你，而不是删掉你的内容。
• 卸载就是删掉那些 scholar-* 符号链接。

然后有三个小步骤会自动跑完，不再问你：

• 修复 chmod +x。 丢了可执行位的辅助脚本会被补回来 —— 这在云盘挂载和 ZIP 下载的情况下会发生，全新 git clone 则不会。只有以 #! shebang 开头的文件会被处理；供 source 用的辅助脚本是刻意保持不可执行的。
• PreToolUse 钩子。 scripts/gates/pretooluse-data-guard.sh 会用 jq 合并进 ~/.claude/settings.json —— 增量且幂等，保留你配过的所有其他键，遇到已有的 scholar 条目是替换而不是重复添加。命令是带引号写进去的，这正是它能在含空格的路径下仍然生效的原因（§6.4）。
• 引导文件。 ~/.claude/scholar-skills.path（一行绝对路径，chmod 600）以及一份 scholar-skill-bootstrap.sh 拷贝 —— 这样即使 SCHOLAR_SKILL_DIR 没设，技能也能从任意工作目录找到仓库。

最后它会询问是否把 export SCHOLAR_SKILL_DIR="..." 追加到你的 ~/.zshrc（或 ~/.bashrc / ~/.bash_profile），shell 类型是自动识别的。除非你用别的方式管理 profile，否则同意即可。

2.5.2 读总结 —— 真正要看的是哪一行

═══════════════════════════════════════════════════
  Setup Complete
═══════════════════════════════════════════════════

  SCHOLAR_SKILL_DIR=/path/to/open-scholar-skills
  Zotero:     /Users/you/Zotero

  Next steps:
  1. Source your shell profile or open a new terminal
  2. Try from any project: /scholar-idea "your research question"

如果安全钩子没能装上，横幅会换一种说法 —— 而且脚本会以非零退出：

  Setup Complete (WARNING: safety hook NOT installed)

  The PreToolUse data-safety hook could not be installed.
  Raw data files will NOT be automatically guarded.

那个退出码就是给机器读的信号。如果你要把安装写进脚本，就检查它：

$ bash setup.sh || echo "SAFETY HOOK MISSING —— 装上 jq 再重跑"

2.5.3 验证它真的生效了

$ ls ~/.claude/skills/ | grep -c scholar        # 44
$ ls ~/.claude/agents/ | wc -l                  # 22
$ cat ~/.claude/scholar-skills.path             # 仓库路径
$ jq '.hooks.PreToolUse' ~/.claude/settings.json | head    # 守卫
$ cat "$SCHOLAR_SKILL_DIR/.env"                 # 你的配置

然后开一个新终端（好让 profile 里的 export 生效），在一个不是仓库的目录下：

> /scholar-idea 户口身份是否影响中国城市居民的互联网使用？

如果技能能在一个无关目录下跑起来，说明个人级安装成功了。如果 /help 里看不到 scholar 技能，重跑 bash setup.sh，盯着 ▸ Checking symlinks... 那一段看有没有报错（§2.4.5）。

自检： 打开 ~/.claude/settings.json，找到 PreToolUse 那一条。脚本路径有没有被引号包起来？如果你的安装位置路径里带空格 —— My Drive、Application Support —— 没加引号的命令会静默地永远不触发，于是你会在自以为有守卫的情况下，其实一道守卫都没有。

2.6 用 GLM、DeepSeek 或本地模型跑这套流程 —— 以及 Z.ai 的 ZCode

目标： 继续使用同一个 Claude Code CLI、同一套 open-scholar-skill 插件、同一种项目结构，只是把模型调用切到 Z.ai/GLM、DeepSeek，或者你自己机器上跑的本地模型。

你不需要装新的 CLI，也不需要替换脚本，更不应该每次会话前手动改 JSON。Claude Code 只看两个环境变量——ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN——只要对方暴露 Anthropic-compatible endpoint，Claude Code 就能直接对话。GLM（Z.ai 国际站和国内 BigModel）以及 DeepSeek 都已经提供这类入口。对真正本地的模型（DeepSeek-R1 蒸馏版、Qwen2.5-Coder、Llama、GLM），Claude Code 仍然需要一个 Anthropic-compatible 的前端：Ollama、vLLM、llama.cpp 暴露的都是 OpenAI 风格的接口，所以要在前面加一层小转换层——claude-code-router 或 litellm——把响应重写成 Anthropic schema。其余流程完全一致。

下面的方案 A–C 都是保留 Claude Code、只换底下的模型。§2.6.7 讲的是另一个方向：ZCode —— Z.ai 自己出的、以 GLM-5.2 为核心的智能体应用，它换掉的是模型加外壳；而由于它能读取 Claude Code 的 skills，open-scholar-skill 套件同样可以在里面跑起来。

2.6.1 提供商速查表

完整 ANTHROPIC_BASE_URL：Z.ai 为 https://api.z.ai/api/anthropic，BigModel 为 https://open.bigmodel.cn/api/anthropic，DeepSeek 为 https://api.deepseek.com/anthropic。后缀 /anthropic 是让 endpoint 走 compatibility shim 的关键，漏掉它是最常见的配置错误。

模型名变得很快。 本节里的模型 ID（glm-5.2、glm-4.7、deepseek-v4-pro 等）只是示例。开工前先查 provider 当前的模型列表——Z.ai/BigModel 和 DeepSeek 各自都有——用你账号能调用的确切名字；粘一个已下线的 tag，是仅次于漏掉 /anthropic 后缀的第二常见错误。GLM 尤其快：本手册第一版写作时旗舰还是 glm-5.1，2026 年 6 月已被 glm-5.2 取代，上下文窗口升到 100 万 token。如果你之前照抄过旧的那三行进 settings.json，记得更新。

2.6.2 方案 A —— 在 ~/.claude/settings.json 里写死后端

最简单的设置：把 Claude Code 指向一个后端，保存文件，之后每次会话都用它，直到你改回来为止。

GLM 示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_zai_key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "API_TIMEOUT_MS": "3000000"
  }
}

这是 Z.ai 官方推荐的映射：Opus 与 Sonnet 两档都走 GLM-5.2，Claude Code 用来跑后台小调用的 Haiku 档走更便宜的 glm-4.7。CLAUDE_CODE_AUTO_COMPACT_WINDOW 是告诉 Claude Code：可以把 GLM-5.2 的 100 万 token 窗口填满再自动压缩上下文 —— 不设这一项，你会比实际需要早得多地触发 compact；当智能体同时抱着一本代码本和三个脚本时，这个差别很明显。

DeepSeek 示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_deepseek_key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash"
  }
}

重启 Claude Code；触发任意一次工具调用或 /usage，确认后端已切换。

2.6.3 方案 B —— 把 key 放到项目外，用 shell 函数切换

每次工作坊前改 settings.json 既痛苦又容易把 key 误推到 git。更好的做法：把所有 provider key 放到 ~/.api-keys（chmod 600），由 ~/.zshrc 或 ~/.bashrc source 进来，再定义几个 shell 函数；每个函数 export 自己那套环境变量，然后启动 claude：

# ~/.api-keys（绝对不要提交到任何仓库）
export ANTHROPIC_API_KEY="sk-ant-..."
export ZAI_API_KEY="..."
export DEEPSEEK_API_KEY="..."

# ~/.zshrc
[ -f ~/.api-keys ] && source ~/.api-keys

glm() {
  export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
  export ANTHROPIC_AUTH_TOKEN="$ZAI_API_KEY"
  export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5.2"
  export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5.2"
  export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7"
  export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
  export API_TIMEOUT_MS=3000000
  claude "$@"
}

deepseek() {
  export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
  export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
  export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro"
  export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro"
  export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
  claude "$@"
}

claude-anthropic() {
  unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN
  unset ANTHROPIC_DEFAULT_SONNET_MODEL
  unset ANTHROPIC_DEFAULT_OPUS_MODEL
  unset ANTHROPIC_DEFAULT_HAIKU_MODEL
  unset CLAUDE_CODE_AUTO_COMPACT_WINDOW API_TIMEOUT_MS
  claude "$@"
}

之后 glm 在 Z.ai 上启动 Claude Code，deepseek 在 DeepSeek 上启动，claude-anthropic 回到原版 Anthropic。PATH 里的二进制 claude 始终是同一个你信任的 CLI。

2.6.4 方案 C —— CC Switch：一键切换 provider 的图形界面

方案 A、B 都要手动改配置。如果你要在多个 provider 或多个账号之间来回切 —— 一个项目用 Anthropic 登录，另一些用 GLM 和 DeepSeek，还有个合作者的仓库用 Kimi key —— 那么用一个替你改这些配置的图形界面会更不容易出错。CC Switch 是一个跨平台桌面应用，在一个窗口里管理 Claude Code（以及 Codex、Gemini CLI、Claude Desktop 等）的 provider 配置，内置 50+ provider 预设，还带一个系统托盘菜单可即时切换。它是开源的第三方工具，不是 Anthropic 官方产品。

安装。

# macOS（Homebrew）—— 已签名并经 Apple 公证
brew install --cask cc-switch

# Linux（Arch）
paru -S cc-switch-bin

Windows 下载 .msi 安装包（Windows 10+）；其它 Linux 发行版用 .deb、.rpm 或通用的 .AppImage。所有安装包都在官方发布页：

• 官网：https://ccswitch.io
• 下载：https://github.com/farion1231/cc-switch/releases

工作原理。 CC Switch 把你的 provider 定义存在本地 SQLite 数据库 ~/.cc-switch/cc-switch.db 里；切换时，它把对应的值写进各工具的实时配置 —— 也就是方案 A 里你手动改的那些 ~/.claude/settings.json 环境变量 —— 采用原子写入，并在 ~/.cc-switch/backups/ 里滚动备份。Claude Code 支持热切换、无需重启；其它 CLI 切换后需要重启终端。

四步：添加与切换。

1. Add Provider（添加） → 选一个预设（Anthropic 官方、GLM/Z.ai、DeepSeek、Kimi/Moonshot ……）或填自定义 base URL + key。
2. 选中该 provider 点 Enable（启用） —— 或直接从托盘菜单里选，即时切换。
3. 重启终端（Claude Code 不需要），触发任意工具调用或 /usage 确认后端已切换。
4. 想切回 Anthropic 登录：启用 “Official Login” 预设，重启，再正常登录。

两条提醒 —— 工作坊的数据边界规则依然适用。

• 它把你的 API key 明文存在 ~/.cc-switch/cc-switch.db 里。把这个文件当凭据库对待：不要放在共用的实验室机器上，不要放进你无法掌控的同步 / 备份目录，永远不要提交进 git。在借来的电脑上，宁可用方案 B（key 放 ~/.api-keys，chmod 600），或用完清理干净。
• 很多预设是社区中转（relay），不是厂商自己的 endpoint。 中转方能看到你发给它的每一条 prompt —— 包括受访者文本。在把含敏感数据的项目路由到任何非官方后端之前，先做 §2.6.6 的信任检查；受限数据请优先用官方通道或你已核验过的 provider。

CC Switch 不替代方案 A/B —— 它只是把它们收进一个界面。工作流的其它部分（插件、CLAUDE.md、权限门）都不变。

2.6.5 在本机跑本地模型

如果机构禁止把数据发到云端 API，或者你需要可离线复现的实验，可以在本机跑一个 checkpoint，再把 Claude Code 路由过去。注意：Claude Code 说的是 Anthropic Messages API，而本地服务（Ollama、vLLM、llama.cpp）说的是 OpenAI 风格的 chat completions，所以中间要垫一层薄薄的转换层。claude-code-router（CCR）最省事：它对 provider 说的是 OpenAI 风格的 chat completions，所以这三者都当作普通的 OpenAI-compatible 后端接入即可——不需要为每个本地服务单独配 transformer。

路径 A —— 用 CCR 在前面接住 Ollama（最简单的本地路线）。 Ollama 暴露的是 OpenAI 风格的接口（/v1/chat/completions）和它自己的原生 API——不是 Claude Code 期望的 Anthropic /v1/messages 格式——所以和 vLLM、llama.cpp 一样，前面要垫一层 shim：

# 1. 安装 Ollama（macOS / Linux / WSL）
$ curl -fsSL https://ollama.com/install.sh | sh
$ ollama --version

# 2. 按显存 / 内存拉一个本地模型。当前 tag 见
#    https://ollama.com/library ，下面这些现在就有：
$ ollama pull qwen2.5-coder:32b   # 偏代码的强力本地模型
$ ollama pull deepseek-r1:14b     # 蒸馏推理模型
#    GLM 系列也在库里 —— 在该页搜 "glm"。

# 3. 用 CCR 接住 Ollama（CCR 安装见路径 B）。在 ccr ui 里加一个
#    "ollama" provider，base URL 填 http://localhost:11434/v1/chat/completions，模型填你拉的 tag，然后：
$ ccr code
#    会话里：/model ollama,qwen2.5-coder:32b

直接把 ANTHROPIC_BASE_URL 指到 http://localhost:11434 是不行的：Claude Code 会去 POST /v1/messages，而 Ollama 并不提供这个端点。是这层转换把两种 schema 接起来的。

路径 B —— claude-code-router（CCR），安装与路由。 CCR 既是单个本地模型的 shim（路径 A），也是混合 provider 的方式——给不同档位走不同路由（Opus 走 Z.ai、Sonnet 走 DeepSeek、Haiku 走本地 Ollama），并可在会话中途用 /model provider,model 手动切换（要做故障回退可自己写一段 router.js 自定义路由）：

$ npm install -g @musistudio/claude-code-router
$ ccr ui          # 打开浏览器配置界面，并创建
                  # ~/.claude-code-router/config.json
$ ccr start       # 启动路由服务
$ ccr code        # 通过 CCR 启动 Claude Code

没有 ccr config init 这个命令；配置文件在你第一次跑 ccr ui（或 ccr start/ccr code）时自动创建，位于 ~/.claude-code-router/config.json。在那里或用 ccr ui 编辑 default 与各档位路由，改完跑 ccr restart 生效。在 CCR 会话里，/model deepseek,deepseek-v4-pro 或 /model ollama,qwen2.5-coder:32b 可在对话中途切换路由 —— provider,model 这种写法是 CCR 的特性，不是原版 Claude Code 的。

vLLM / llama.cpp。 如果你已经用 vLLM（vllm serve <model>）或 llama.cpp（llama-server）提供服务，它们暴露的是 OpenAI 风格的 chat completions，不是 Anthropic 风格。vLLM 自带一份 Claude Code 接入指引；否则在前面套一层 litellm、anthropic-proxy 或 CCR 转换 OpenAI ↔ Anthropic schema 即可。Claude Code 这一侧保持不变。

2.6.6 信任新后端前必做的三项检查

Open Scholar 技能不是 model-agnostic 的。它们依赖长上下文阅读、tool use 和结构化 JSON 输出。在用非 Anthropic 后端跑 CFPS 流水线之前，必须先过下面三步冒烟测试：

1. Tool-use round-trip。 在沙盒项目里说：“读取 grades.csv，跑一段 Python 计算平均值，把结果写入 out.txt”。如果后端悄悄跳过 Bash 调用、自己编造文件内容、或者只用文字给出答案而没有生成 out.txt，那么所有依赖产物的 scholar-skill 都会失败。
2. 长 prompt 稳定性。 粘贴一段 30 页的 CFPS 代码本节选，让 agent 抽出变量名与对应波次。有效上下文窗口偏小的后端会在后面几页静默丢内容。
3. 技能调用。 跑一遍 /scholar-init --slug smoke-test 和 /scholar-safety scan。如果模型拒绝调用 skill、返回错误路径、或者“忘记”了 PreToolUse hook，就不要用它处理真实数据。

把每一项的结果用一行写到 logs/backend-test.md。不要对外宣称任何模型与 open-scholar-skill 套件“完全兼容” —— 你只能说：在某月某日跑过冒烟测试，列出的几个 skill 通过。

工作坊纪律： 工作坊现场，一台笔记本只用一个后端。在流水线中途换 provider，是让一篇论文前后两半对同一个 CFPS 变量定义打架的最快方法。

2.6.7 方案 D —— ZCode：用 Z.ai 自家的智能体应用跑 scholar 技能

方案 A–C 都是保留 Claude Code CLI、只把底下的模型换掉。ZCode 走的是另一条路：它是 Z.ai 自己出的智能体应用，以 GLM-5.2 为核心，换掉的是模型连同外壳。Z.ai 把它叫做 Agentic Development Environment（ADE）—— 一个桌面应用，带 Goal 模式来跑多步长任务，还有浏览器自动化、远程开发、手机远程操控等通道。它不是 Anthropic 的产品，也不是 Claude Code，而是另一个程序，配置目录在 ~/.zcode/。

它值得写进本手册，是因为 Z.ai 做了一个设计决定：ZCode 能读取 Claude Code 的 skills、plugins、commands 和 hooks。 也就是说，你在 §2.4 装好的 open-scholar-skill 套件可以在它里面跑，干活的是 GLM-5.2。如果你所在的院系没法报销 Anthropic 订阅，或者你需要一条国内可付费的通道，这就是从「没有 Claude 预算」到「scholar 流水线能在我笔记本上跑起来」的最短路径。

你到底该选哪个？

本手册第 II–IV 部分默认你面对的是 $ 提示符和 /scholar-* 命令。在 ZCode 里，技能文件是同一批，但调用方式、项目记忆、hook 三处都不一样。开始在 ZCode 里跑 CFPS 之前，先读完下面三个「差异」段落 —— 第三个是安全问题。

安装。 ZCode 是桌面应用 —— macOS（Apple 芯片与 Intel）、Windows（x64 与 ARM64）、Linux（x64 AppImage）。没有 npm install 这一说。从官方安装页下载，那里始终是当前版本：

• 中文文档：https://zcode.z.ai/cn/docs/install
• English docs: https://zcode.z.ai/en/docs/install

# macOS —— 打开 .dmg，把 ZCode.app 拖进 /Applications。
# 首次启动如果被 Gatekeeper 拦住：
$ xattr -dr com.apple.quarantine /Applications/ZCode.app

# Linux —— 给 AppImage 加执行权限后运行
$ chmod +x ZCode-*.AppImage && ./ZCode-*.AppImage

Windows 直接跑 .exe 安装程序，按向导走完。

接上模型。 首次启动会让你选一个工作区目录，并配置模型连接。三条路，选哪条取决于你人在哪里：

• Z.ai 账号（国际站）—— 登录即可，用量走 GLM Coding Plan 权益。Coding endpoint 为 https://api.z.ai/api/coding/paas/v4（OpenAI 风格）与 https://api.z.ai/api/anthropic（Anthropic 风格）。
• BigModel（中国大陆）—— 智谱开放平台，同样的 GLM 模型：https://open.bigmodel.cn/api/coding/paas/v4 与 https://open.bigmodel.cn/api/anthropic。
• API Key —— 任何 Anthropic 或 OpenAI 兼容的 provider。ZCode 自带的清单里包括 Anthropic、OpenRouter、Moonshot、OpenAI、MiniMax 以及自定义 endpoint，所以你也可以让 ZCode 这个界面去跑 Claude 模型，从而在模型不变的前提下比较两个外壳。

可选的 GLM 模型是 GLM-5.2（旗舰，100 万 token 上下文）和 GLM-5-Turbo；其余取决于你账号的权限。不要把 coding endpoint 换成通用 endpoint —— 它们按区域和计费区分，不可互换。这相当于 §2.6.1 里漏掉 /anthropic 后缀：同一类一行之差的错误，症状也一样 —— 什么都跑不通，而且没有有用的报错。

确认连接的办法，照 Z.ai 自己的快速开始来：让智能体列一下当前目录的文件。如果它报出来的是你真实的文件名，说明模型和工具循环都活着。

把 open-scholar-skill 装进 ZCode。 一共三条路线。用第一条；另外两条是留给两种情况的：你已经有一套 Claude Code 安装、想直接复用；或者哪里没注册上，你想亲眼把每个文件放到位。

路线 1 —— 插件商店（就用这条）。 该仓库已经发布了 marketplace 清单，ZCode 一步就能装上；而且以 plugin 方式安装会一次性注册它的全部组件类型 —— skills/、commands/、agents/、.mcp.json、hooks/hooks.json —— 这也正是为什么只有这条路线能把同行评审、代码审查、结果核验那批 subagents 一并带进来，不用额外操作。

打开 Settings → Plugins，点右上角 Create → Add marketplace，填：

joshzyj/open-scholar-skill

ZCode 会先校验清单再添加。之后这个 marketplace 会以 open-scholar 的名字出现在 Personal 分段里；找到 open-scholar-skill 那张卡片，点 Install。新装的插件默认启用，启用会立即重载智能体运行时 —— 不用重启。以后上游发新版，用搜索框上方的齿轮图标打开 Marketplace sources 刷新一下，就能拿到新技能。

同一份清单在 Claude Code 里也能用 —— 如果你更愿意用插件方式而不是 setup.sh：

$ claude plugin marketplace add joshzyj/open-scholar-skill
$ claude plugin install open-scholar-skill@open-scholar

即便用插件装好了，bash setup.sh（§2.4.2）仍然要跑一次。 插件给你的是技能和 agents，但不包括 setup.sh 写在仓库之外的那三样：带有 Zotero、BibTeX、CrossRef 配置的 .env（§2.5.1）；技能里那些 shell 脚本的可执行位；以及 PreToolUse 数据安全守卫。而最后这一样，无论如何你都得在 ZCode 里手动声明一遍 —— 见下面的差异 3。

路线 2 —— 从已有的 Claude Code 安装导入。 如果你已经跑过 setup.sh，ZCode 会自动检测已经装给 Claude Code 的 skills —— 以及 Codex CLI、OpenClaw、Augment、Windsurf 的 —— 并提示导入。进 Settings → Skills → import，选 symlink（符号链接）模式，这样以后在技能仓库里 git pull，ZCode 这边也跟着更新；选 copy（复制）则是冻结一份快照。导入进来的技能，和你自己在 ~/.zcode/skills/<name>/SKILL.md 手写的完全等价。注意这条路线只管 skills —— subagents 要靠路线 1 或路线 3。

路线 3 —— 手动建符号链接。 当注册出问题、你想自己把每个文件放到位时的兜底方案：

$ SRC="${SCHOLAR_SKILL_DIR:-$HOME/open-scholar-skill}"   # 你 clone 到哪儿就写哪儿
$ mkdir -p ~/.zcode/skills ~/.zcode/agents
$ for d in "$SRC"/.claude/skills/*/;   do ln -sfn "$d" ~/.zcode/skills/"$(basename "$d")"; done
$ for f in "$SRC"/.claude/agents/*.md; do ln -sfn "$f" ~/.zcode/agents/"$(basename "$f")"; done
$ ls ~/.zcode/skills | wc -l      # 应当等于：ls ~/.claude/skills | wc -l

然后 Settings → Skills → Refresh。无论走哪条路线都请注意：ZCode 的 subagents 只有用户级，没有按工作区分的 agents 目录 —— 这台机器上所有项目共用同一套审稿人面板。

差异 1 —— 怎么调用技能。 在 Claude Code 里你敲 /scholar-init。在 ZCode 里，/ 是给命令用的（/goal、/compact，以及 ~/.zcode/commands/ 下你自己写的），技能用 $ 引用：

$scholar-init 为 CFPS 数字鸿沟这篇论文初始化一个项目

敲 $ 会弹出技能选择器，或者用斜杠菜单里的 Skills 分组。subagents 用 @ 引用，也可以由主智能体自行派发。第 II–IV 部分里每一个 /scholar-* 命令，在这里都写成 $scholar-*；提示词的其余部分一个字都不用改。

差异 2 —— 它不读 CLAUDE.md。 ZCode 的项目指令来自 AGENTS.md：先是用户全局的 ~/.zcode/AGENTS.md，再是工作区根目录下的 AGENTS.md，按这个顺序拼接。CLAUDE.md 只在初次接入时被用作一次性迁移来源，运行时不会再读。所以你在 §3.3 写的项目简报必须复制一份过去：

$ cp CLAUDE.md AGENTS.md     # 在项目根目录 —— 之后两份要保持同步

ZCode 不会跨目录层级合并多个 AGENTS.md，不扫描子目录，也不展开 @import。把数据边界规则 —— §3.3 里那段 Forbidden（禁止） —— 放在工作区 AGENTS.md 的最上面，放在不可能被漏看的位置。

差异 3 —— 安全 hook 必须重新声明。这一条会真的伤到你。 setup.sh 把 PreToolUse 数据守卫注册在 ~/.claude/settings.json 里。ZCode 根本不读那个文件。 在你自己声明之前，ZCode 是完全没有数据守卫在跑的，而且失败是静默的：智能体读了一个受限文件，没有任何东西拦它，你可能很久之后才发现，也可能永远不会发现。

好消息是，ZCode 的 hook 约定足够接近，同一个脚本可以原样复用。ZCode 会往 hook 的 stdin 写一行 JSON，而按 Z.ai 自己的说法，这个 payload「同时带有 ZCode 的 camelCase 字段和 Claude Code 的 snake_case 别名，好让既有插件继续读 snake_case」—— 这正是 pretooluse-data-guard.sh 解析的那几个字段（.tool_name、.tool_input.file_path、.cwd）。退出码 2 表示拦截，与 Claude Code 的约定一致。

在 ~/.zcode/cli/config.json（对所有项目生效）或 <workspace>/.zcode/config.json（只对一个项目生效）里声明：

{
  "hooks": {
    "enabled": true,
    "events": {
      "PreToolUse": [
        {
          "matcher": "Read|NotebookRead|NotebookEdit|Grep|Glob|Bash|Edit|Write|MultiEdit",
          "hooks": [
            {
              "type": "command",
              "command": "bash '/Users/you/open-scholar-skill/scripts/gates/pretooluse-data-guard.sh'",
              "timeoutMs": 10000
            }
          ]
        }
      ]
    }
  }
}

"hooks.enabled": true 是必需的 —— 没有它什么都不会触发。脚本路径里若有空格一定要加引号；§2.5.3 里关于 My Drive 的那条警告，在这里一字不差地适用。

然后验证它真的会触发，因为一个写错了工具名的 matcher 会「失败即放行」（fail open），外观上和正常工作的守卫完全一样：

> 读取 data/raw/cfps2020_adult.dta，把前五行给我看看

你要看到的是一次明确引用守卫的拒绝。如果文件被读出来了，说明 hook 没接上。就停在这里，先修好；在你亲眼看到一次故意的读取被拦下来之前，不要把受限数据放到 ZCode 面前。把结果写进 logs/backend-test.md，和 §2.6.6 的检查记在一起。

在交给它跑整条流水线之前。 ZCode 同时换掉了外壳和模型，所以 §2.6.6 的两半都适用：跑那三步冒烟测试（tool-use round-trip、长 prompt 稳定性、技能调用 —— 这里用 $scholar-init 而不是 /scholar-init），外加上面那条 hook 测试。记下日期，以及具体哪几个技能通过了。不要凭一次冒烟测试就对外说这套件「兼容 ZCode」 —— 只说你跑了什么、什么时候跑的。

两条数据边界提醒，都不是可选项。 第一，无论你选 Z.ai 还是 BigModel，GLM 的调用都在中国法律下处理。对于受限数据、受 IRB 管辖的数据、或有数据使用协议（DUA）约束的受访者数据，这是要问你的 IRB 和 DUA 的问题，不是个人偏好 —— 与 §2.6.4 对社区中转（relay）适用的是同一条标准。第二，ZCode 的那些增值能力 —— 浏览器自动化、远程开发、手机与机器人通道 —— 都在扩大能伸进你项目目录的面。只开你真正需要的那些，并保持 §4 的目录布局，让原始数据待在任何自动化默认够不到的地方。

2.7 让智能体替你安装研究工具链

目标： 只要 claude（或 codex）能启动，剩下的安装工作 —— Python、R、Git、系统编译工具、社会科学常用包栈（tidyverse、pandas、statsmodels、scikit-learn 等）—— 都交给智能体。你只需要逐条审核它给出的命令，逐条点批准，最终在 transcript 里留下一份可在另一台电脑复用的安装日志。

让智能体干这件事有三个好处：它会自动挑对操作系统对应的包管理器（macOS 用 brew、Debian/Ubuntu 用 apt、Windows 用 winget 或 choco），它会按正确顺序处理依赖（先系统库，再语言运行时，最后包），并且每条执行过的命令都会留在对话里。

2.7.1 开始之前 —— 先把安全规则讲清楚

系统级安装会动到共享状态。先告诉智能体规矩，再让它动手：

> 请帮我在这台机器上装一套社会科学研究工具链。开始之前，请遵守以下规则：
>
>   1. 先识别系统与包管理器，把结果告诉我；
>   2. 每一条安装命令先告诉我再跑；任何 sudo 命令都必须逐条经我批准；
>   3. 优先用用户级安装方式（rustup、pyenv、rbenv、conda --user、renv、
>      R 用户库），不要去改系统自带的 Python 或 R；
>   4. 每一步装完都跑一次 --version 确认成功，再进下一步；
>   5. 把你执行过的每一条命令追加写入当前目录下 logs/install.md，
>      方便我换台电脑时复用。
>
> 先识别一下我的操作系统、shell，以及 {python3, R, git, make, pandoc,
> quarto, jq} 中哪些已经在 PATH 里。把结果给我，然后等我下一步指示。

这一段全程用 default 权限模式。不要切到 acceptEdits 或 bypassPermissions —— 每一次 sudo、brew install、apt install、npm install -g 都应该是一次单独的批准。

2.7.2 覆盖 90% 场景的四条提示词

智能体把机器情况摸清楚之后，按顺序发下面四条提示词。每条都足够小，便于你逐条审核。

(1) Git、SSH 与系统编译工具。

> 请把版本控制与源码编译需要的基础组件装好：
>
>   - git（系统包管理器里的最新稳定版）
>   - 一个 SSH client 和一对 ed25519 key（~/.ssh/id_ed25519）；
>     如果我已经有 key，绝对不要覆盖
>   - GNU make、C/C++ 编译器、pkg-config、curl
>   - jq（open-scholar-skill 的 PreToolUse hook 必须用到）
>
> macOS 走 Homebrew（没装就先装上）。Debian/Ubuntu/WSL 走 sudo apt update
> && sudo apt install。每条命令先给我看再跑。
>
> 装完跑一遍 git --version、make --version、cc --version、jq --version，
> 再 cat ~/.ssh/id_ed25519.pub 把公钥打印出来，我好贴到 GitHub。

(2) Python：pyenv + 项目级虚拟环境。

我们刻意不走 sudo pip，也不动系统自带的 Python。用户级 pyenv + 项目级 .venv，是唯一能在系统升级后仍然不坏的方案。

> 帮我装 pyenv（Windows 上用 pyenv-win），用它装 Python 3.11.x 并设为
> 用户默认版本。然后在当前项目目录建一个 .venv，把社会科学标准包栈装进去：
>
>   numpy, pandas, scipy, statsmodels, scikit-learn, matplotlib, seaborn,
>   pyarrow, jupyterlab, ipykernel, linearmodels, pyreadstat, openpyxl,
>   tqdm, requests, beautifulsoup4, lxml, plotnine, great_tables, ruff,
>   black, mypy, pytest
>
> 把版本固定到 requirements.txt。再把这个 venv 注册成名为 "vibe-py311"
> 的 Jupyter kernel。最后打印 python --version、pip list | head 和
> kernel 列表。

如果还要做计算社会科学（NLP、嵌入、LLM 标注、网络分析、地理空间），追加一段：

> 再装：transformers, sentence-transformers, datasets, accelerate,
> tiktoken, openai, anthropic, spacy, nltk, gensim, networkx, igraph,
> geopandas, shapely, pyproj, rasterio, contextily, folium。
> 没有 NVIDIA GPU 时不要拉 CUDA 版 torch，默认用 CPU wheel。

(3) R + 社会科学包栈。

R 在各操作系统上的安装路径差异较大，让智能体自己选路线比死记四套命令省事。关键提示词是：「装到用户库里，不要每个包都 sudo。」

> 装 R 4.4.x 和 RStudio Desktop（免费版）。macOS 走 CRAN 官方 .pkg；
> Debian/Ubuntu/WSL 走 CRAN apt 源（cran.r-project.org/bin/linux/ubuntu）。
> R 进 PATH 后，在 ~/R/library 建一个用户库（如不存在），在 ~/.Renviron
> 里把 R_LIBS_USER 指过去，然后把以下包装进用户库：
>
>   tidyverse, data.table, lubridate, janitor, haven, readxl, writexl,
>   here, fs, glue, scales, broom, modelsummary, gt, gtsummary, kableExtra,
>   flextable, officer, knitr, rmarkdown, quarto, tinytex,
>   fixest, lme4, sandwich, lmtest, marginaleffects, estimatr, sjPlot,
>   ggplot2, ggdist, ggrepel, patchwork, ggeffects, plotly, DT,
>   survey, srvyr, lavaan, psych, mice, naniar, VIM, future, furrr,
>   renv, usethis, devtools, remotes, languageserver, lintr, styler, testthat
>
> 做计算社会科学的（等我确认后）再加：tidytext, stm, quanteda, text2vec,
> conText, igraph, tidygraph, ggraph, sf, terra, tmap, leaflet, gganimate。
>
> 装完跑 R -e 'sessionInfo()'，把已安装的包列表（含版本号）写到
> logs/r-pkgs.md。

(4) Quarto + 最小 LaTeX，保证 PDF 渲染能跑通。

很多流水线在最后一步翻车：「论文写完了但渲染不出 PDF。」早一点把这个搞定：

> 装 Quarto 最新稳定版，再装一套最小的 TeX。macOS 与 Linux/WSL 上
> 推荐 quarto install tinytex（约 200MB），不要装完整 MacTeX/TeXLive
> （30GB 那种）。装完跑 quarto check，再写一份 10 行的 hello.qmd 渲染
> 成 hello.pdf，确认整条链路通了。

2.7.3 Codex 风格的提示词

同样的提示词换到 codex 上几乎可以照搬，只要在每段最前面加一句 "在跑每一条命令前先告诉我它是干什么的" —— Codex 默认解释得偏少。Codex 偏好 python -m venv，在干净机器上没问题，但和系统已有 Python 冲突时容易出错；上面 pyenv 那条提示词更稳。

2.7.4 把安装日志固化下来

四条提示词都跑完之后，再追加一条：

> 把这次会话里的所有安装行为整理成 logs/install.md，按四步分节
> （系统工具 → Python → R → Quarto/LaTeX）。每一步写明确切命令、--version
> 输出，以及一开始检测到的操作系统、shell 和架构。我明天要在另一台
> 笔记本上把这套环境复刻一遍。

这份日志就是产物。下次同事问「我该怎么把环境搭起来？」，把 logs/install.md 丢给他，让 Claude（或 Codex）在他机器上复跑一遍即可。

2.7.5 不要让智能体动的几类东西

少数几类软件最好你自己装，不要交给智能体：

• 系统级数据库（Postgres、MySQL）—— 太容易覆盖现有实例、清掉本地数据。
• 替换 shell / 终端模拟器 —— 智能体没法重启自己所在的 shell，半路换会出诡异错误。
• GPU 驱动、CUDA 工具链 —— 牵涉重启与厂商特定决策。
• 任何需要改 /etc/hosts、防火墙、VPN 客户端的事。

除此之外 —— 语言运行时、包、命令行工具、编译依赖、文档工具链 —— 让智能体逐条批准式安装，比你自己装更快、更可复现、还顺手留下了纸面记录。

3. 你的第一次智能体会话

目标： 60 秒内走完一遍“请求 → 提议 → 批准 → 产物 → 验证”循环。

建一个沙盒：

$ mkdir -p ~/sandbox-vibe && cd ~/sandbox-vibe
$ printf "subject,score\nAnna,0.81\nBen,0.74\nCara,0.92\n" > grades.csv
$ claude

会话里：

> 读 grades.csv，告诉我平均分，以及哪些人高于平均分。

Claude 会先提出工具调用。先读再批准。 一个典型界面：

 Claude wants to use Read on /Users/you/sandbox-vibe/grades.csv
 ───────────────────────────────────────────────────────────
   path: /Users/you/sandbox-vibe/grades.csv
 ───────────────────────────────────────────────────────────
   [a] approve once   [s] always allow this dir   [n] deny

按 a。它可能再提议跑一段 Python 或 R，再批准一次。结果：

 Mean score: 0.823
 Above mean: Cara (0.92)

整个工作坊里所有的 scholar-skill 会话都是这个循环的放大版：

1. 请求 —— 你用自然语言提的需求
2. 提议 —— 智能体打算执行的工具调用
3. 批准 / 拒绝 —— 你的选择
4. 产物 —— 落到磁盘上的文件
5. 验证 —— 你打开文件检查

记住一句话：屏幕上打印的答案不重要，留在磁盘上的产物和痕迹才重要。

3.1 权限模式——快速入门

Claude Code 共有六种权限模式：default、acceptEdits、plan、auto、dontAsk、bypassPermissions。并非每个会话都能用到全部六种：auto 需要符合条件的账户和较新的模型，dontAsk 只能用 --permission-mode dontAsk 设定——用 /help 看你装的版本暴露了哪些。新手最常用的两种是：

• default —— 每个工具 / 路径首次使用都弹出确认。敏感数据、首跑某项目，留在这里。
• plan —— 只读“探查”模式，智能体必须先写计划，未获批准前不能编辑、不能跑命令。任何破坏性或昂贵的多步操作之前先进。

按 Shift+Tab 循环切换 default → acceptEdits → plan（账户符合条件时还会进入 auto），再按继续循环。完整的六种模式及各自的安全含义见 §3.2：acceptEdits 自动通过编辑，auto 在后台安全分类器的审查下自动执行一切，dontAsk 只允许预先批准的工具，bypassPermissions 跳过所有检查。

/sandbox 不是第七种权限模式。 很容易把它归到这一类，但两者回答的是不同问题：权限模式决定一次工具调用是否执行，而沙箱决定一条 Bash 命令跑起来之后能够到什么。它们是叠加的，对受限数据你两个都要。沙箱自己的 auto-allow 模式同样不是权限系统的 auto 模式 —— auto-allow 跳过提示，是因为 OS 边界已经把命令圈住了；auto 跳过提示，是因为一个分类器判断它安全。面板和两种模式见 §5A。

3.2 高频命令

关于命令准确性。 下面的命令对照 Claude Code v2.1.154（与 Opus 4.8 同日发布，2026-05-28）核对。Claude Code 的发布节奏很快——你装的版本可能比本手册更新，或更旧。装好后随时 /help 看实时命令列表。”自治与多会话”小节包含 2.x 周期新加的命令，包括 Dynamic Workflows 研究预览（/workflows）和后台会话工作链（claude --bg、/resume <bg-id>）；如果某个命令在你装的版本里识别不出来，就当它还没进你的版本。括号里的第二个名字是别名，效果一致。

项目设置 / 记忆

/init                  生成 CLAUDE.md 项目记忆文件
/permissions           查看或调整工具权限
/doctor                环境与配置诊断
/usage   (或 /cost)    显示本会话 token 与美元消耗。
                       v2.1.149+：/usage 现在按 skills、subagents、plugins、
                       MCP servers 分类拆账，便于你在给整条流水线
                       开 /effort xhigh 之前先看哪个 scholar-skill
                       是最大成本项。
/reload-skills         v2.1.152+：扫描 ~/.claude/skills/ 与本项目
                       .claude/skills/ 目录，不用重启会话就能加载新技能。
                       适用：刚改完一个 SKILL.md、或刚拉了一版新的
                       open-scholar-skills。SessionStart hook 可以设
                       "reloadSkills": true，让新技能在本会话内可用。

会话控制

/compact                          压缩历史以释放上下文
/rewind  (或 /undo)               回滚到更早的检查点
/resume  (或 /continue) [id]      继续上一次会话
/recap                            一句话总结本会话
/rename <name>                    给当前会话起名（之后 /resume <name>）
/clear   (或 /reset, /new)        开新对话（CLAUDE.md 不动）
/exit    (或 /quit)               干净退出
连按 Ctrl+C                       取消当前正在执行的操作

移动端 / 远程操控

/remote-control  (别名: /rc)   把当前本地会话开放给 claude.ai/code
                                与手机 App。执行仍然在你本机，远端
                                只是同步对话视图。适合：办公室开了
                                一个长流水线，想去咖啡店继续盯。

关掉远端标签页不会停掉本机会话；除非你在本地 /exit，agent 会一直跑。

自治与多会话 —— Claude Code 2.x 新增

下列功能是 Opus 4.6 / 4.7 / 4.8 周期里加进来的，它们改变了研究者”让 agent 自己跑、同时管多个会话”的方式。

/goal <条件>                  设定完成条件。智能体跨多个回合自动工作，
                              不再每步问你，同时跟踪已用时间、轮次、
                              token 成本，直到条件达成。例子：
                                /goal "全部预分析诊断通过且 pre-mortem
                                       返回 LOW-RISK"
                              适用：边界清晰、不需要人介入中间步的多步任务。

/workflows                    v2.1.154+（Opus 4.8）：Dynamic Workflows
                              研究预览。让 Claude 设计一套多步工作流，
                              它会写出编排脚本，在后台同时调度数十到
                              上百个子智能体，共享一份可恢复状态。
                              `/workflows` 打开仪表盘，列出所有运行
                              （排队 / 运行中 / 完成 / 失败），可以挑
                              一个 peek 看进度。社会科学的典型用法：
                              一篇论文一个 workflow，每一步是一个
                              scholar-* 技能，scholar-respond 的审稿团
                              是 fan-out 节点，scholar-verify 是
                              fan-in 节点。仅 Max / Team / Enterprise
                              方案和 API 可用。

/bg   (别名: /background)     把当前会话切换到后台 agent 模式。终端
                              回到 shell 提示符；agent 在你机器上继续
                              无头运行。稍后从 `agent view` 重新接管，
                              或用 `/resume <session-name>` 直接接回。
                              从 shell 起的 `claude --bg` 后台会话现在
                              也会出现在 `/resume` 列表里，标记为 `bg`。

/effort                       速度 vs. 推理深度的滑块。Opus 4.8 你常用的几档：
                                  low | high（默认）| xhigh | max
                              （还有其他档位；跑 /effort 看完整列表）
                              `xhigh` 适合识别策略备忘、理论稿、对抗性
                              审稿；`max` 留给"最难的那一次 verify
                              复跑、不计 token 也要把它对上"的场合。
                              日常编辑回到 `high`（或 `low`）——
                              `xhigh` / `max` 又慢又贵。

/focus                        在普通紧凑视图与详细 transcript 视图之间
                              切换。详细视图会展示每个工具的输入 / 输出，
                              是 /scholar-verify 和 scholar-code-review
                              跑的时候应该开的。

/code-review [--fix]          v2.1.152+：审当前 diff。`--fix` 会在审完
                              之后直接把建议的修改写到工作树里，把
                              复用、化简、效率改进直接做成"待提交"。
                              要 6-agent 大盘子用 `scholar-code-review`；
                              提交前的轻量 pass 用 `/code-review --fix`。

/simplify                     v2.1.154+：只做清理的审查，自动把
                              重复代码 DRY 掉、死分支砍掉、命名收紧。
                              建议在 `scholar-replication` 打包前跑一遍，
                              避免把第一版脚手架带进发布包。

要同时管多个后台会话，先从任何一个 Claude 会话退出（/exit 或关掉标签页），然后在 shell 里跑：

$ claude agents       # 如果你装的 Claude Code 版本带这个命令

这就是 Agent View —— 一个单屏仪表盘，列出你机器上所有 Claude Code 后台会话，按状态分组：Needs Input / Working / Completed。在里面你可以新建会话、不接管就 peek 看输出、接管会话继续追问、重命名、关闭。每个后台会话都是一个完整的 Claude Code 对话，由 supervisor 进程托管，跨终端重启都不丢；关 iTerm 不会让 agent 停。macOS 上的后台 agent 现在还能跨 Claude Code 升级活下来（v2.1.153+）。若你装的版本识别不出 claude agents，就退回到每个会话各开一个终端标签页。

从 shell 起一个新的后台会话时，可以直接预配置好它需要的一切，不用接管进去再改：

$ claude agents \
    --add-dir ../shared-cache \
    --settings ./.claude/settings.bg.json \
    --mcp-config ./.claude/mcp.json \
    --plugin-dir ~/.claude/plugins/open-scholar-skill \
    --permission-mode acceptEdits \
    --model claude-opus-4-8 \
    --effort xhigh \
    --dangerously-skip-permissions   # 只在 worktree 里用

多数工作坊参与者不会用到完整的 flag 集——但 --model + --effort 让你能在前台用 claude-sonnet-4-6 做日常编辑的同时，在后台开一个”高 effort 的 Opus 4.8 + xhigh”会话专门跑理论那一段。

工作坊用例：

• 用 /goal 跑无人值守的技能链（scholar-eda → scholar-analyze → scholar-code-review）。
• 用 /workflows 做端到端论文编排：一个分派出去的 workflow 把 scholar-init → scholar-lit-review-hypothesis → scholar-design → scholar-eda → scholar-analyze → scholar-verify 全部跑完，你正好回邮件。
• 用 /bg + agent view 同时跑两篇论文（一篇 CFPS、一篇 CGSS），不必同时盯两个终端。
• 仅在写理论 / 识别 memo 时用 /effort xhigh；当 scholar-verify 反复纠同一处数字对不上、需要最深一档复查时才上 max；写 Results 之前调回 high。
• 任何分析脚本改动之后跑 /code-review --fix；打包 replication 之前跑 /simplify。
• 任何 scholar-verify 跑之前开 /focus（详细视图），方便看每个验证 agent 实际读了什么。

权限模式

Claude Code 有六种权限模式，都通过同一个 Shift+Tab 循环或 --permission-mode <name> CLI flag 切换。下方模式名是 Claude Code 内部使用的精确标识符。

关于可用性。 六种模式都有文档记载，但某个会话里你能用到哪些取决于你的账户和启动方式。auto 只有当账户符合条件（所有套餐、较新的模型如 Opus 4.6+/Sonnet 4.6，且在 Team/Enterprise 上管理员已开启）时才出现在 Shift+Tab 循环里；dontAsk 从不出现在循环里，只能用 --permission-mode dontAsk 设定。做工作坊演示前先用 /help 确认你装的版本暴露了哪些。

Shift+Tab            循环切换 default → acceptEdits → plan，再循环回来。
                     auto 仅在账户符合条件时进入循环；bypassPermissions
                     需以启用 flag 启动后才加入；dontAsk 从不出现在循环里。
                     当前模式名显示在状态栏。

/permissions         打开交互权限 UI，查看 / 编辑各模式所读取的
                     allow / ask / deny 规则。

也可以启动时直接进入某模式：

$ claude --permission-mode plan        # 进入 plan mode 启动
$ claude --permission-mode auto        # 进入 auto mode 启动
$ claude --dangerously-skip-permissions
# 等价于 --permission-mode bypassPermissions

Auto mode 与 bypass mode —— 高级模式，请先读完再用

auto 与 bypassPermissions 改变了“是否需要你确认”的契约。开启之前先看清安全规则。

• auto —— 智能体可以自主执行一串低风险任务，但遇到破坏性 / 影响共享状态的操作仍会停下问你（git push、rm、PR 评论、跨项目网络调用）。本项目内的文件编辑、工具调用自动通过。
• bypassPermissions（即 --dangerously-skip-permissions CLI flag）—— 每一个工具调用都自动通过，包括破坏性的：rm -rf（在 circuit-breaker 限度内）、git reset --hard、git push …… 都不再问你。

安全规则——开启前必读。

1. 绝不要在你输不起的项目里用 bypassPermissions。 它适合 sandbox repo、临时 worktree、CI 容器，不适合你的博士论文目录。
2. bypassPermissions 要在 git worktree 里跑，不要在主 checkout 上跑。 安全模板：

   $ git worktree add ../sandbox-experiment -b experiment
   $ cd ../sandbox-experiment
   $ claude --dangerously-skip-permissions
   

   智能体把 sandbox 弄坏了，删 worktree 重来；主分支毫发无损。

3. 绝不要在 scholar-safety 标了 LOCAL_MODE 的文件上用 bypassPermissions。 LOCAL_MODE 的意义就是逐次确认；bypass 把这个机制吃掉了。敏感数据会话只用 default 或 acceptEdits。
4. auto 是更安全的折中。 它允许智能体把任务链起来不打断你，但破坏性 / 对外效果操作仍会停下。日常实现工作用 auto；首次接触敏感项目不要用。
5. 长跑后必看 /usage。 auto 与 bypassPermissions 是“突然账单”出现的主要场景。

总规则：给 Claude 的自主性越高，你的项目结构、权限、安全扫描就越重要。 Bypass mode 不是 scholar-init 的替代品；它是已有规范的放大器。

3.3 CLAUDE.md —— 项目的持久简报

项目 CLAUDE.md 有两个写入源，互相合作不冲突：

1. Claude Code 内置 /init —— 写用户作者的项目简报：自己的约定、禁止动作、目标期刊、项目特定说明。
2. /scholar-init 和 /scholar-full-paper Phase 0 各自写入一个用 <!-- scholar-full-paper:BEGIN auto-rules vN --> … <!-- END auto-rules --> 包裹的自动管理区块。该区块幂等且非破坏 —— 标记外的用户内容原样保留。

自动管理区块有两种 profile：

• Lean（v2-lean，约 50 行） —— 由 /scholar-init Step 1.2.5 写入。仅承载跨 scholar-* 技能的通用规则：稿件文件禁用破坏性正则、客观性 Mandate、数据安全栈 + LOCAL_MODE 范围、引用规则、跨技能工作流（xelatex、viz_setting.R、文件版本控制、验证协议）。
• Full（v2-full，约 230 行） —— 由 /scholar-full-paper Phase 0 写入。lean profile 加上：Pacing Discipline（10 条规则 + ASK / DO-NOT 列表）、G3 诚实停止模板、G4 决策点记忆表、real-agent dispatch heuristic、各 Phase 契约（Phase 11/5.5/10/10.5）、稿件实质规则（Abstract + Limitations）、dispatch manifest 来源链。

升级方向单向：第一次跑 /scholar-full-paper 时 lean 自动升级为 full。Full → lean 不允许 —— 一旦编排器规则装上，后续 /scholar-init 不会把它们抹掉。这样保证用过完整流水线的项目不会被无意中降级。

顺序无所谓：先 /init 再 /scholar-init 或反过来，结果一样（一个用户区块 + 一个自动管理区块，用标记隔开）。每次 scholar-init 或 scholar-full-paper 运行时自动管理区块都刷新一遍，插件规则迭代时你的 CLAUDE.md 自动跟上。

这个文件以后每次在该目录下开会话都会被读进上下文。用户作者区块（标记外）适合写：

# CLAUDE.md — digital-divide-china-cfps

## 数据
- CFPS 原始 .dta 在 data/raw/，永不手工修改。
- 处理后的面板：data/processed/cfps-panel-long.rds，
  仅由 01-build-sample.R 生成。

## 规范
- R 包统一用 tidyverse + fixest + marginaleffects；不用 data.table。
- 图：ggplot2 + viz_setting.R；PDF + PNG，7×4.5 inch，300 dpi。
- 目标期刊：Social Forces；描述/分解设计。

## 禁止
- 永不把 hukou 称作 "treatment"；这是描述性论文。
- 未经我批准不要 git push。
- 当前会话不读 data/raw/*.dta 原始行。

把它当实验室手册。不要放密钥、原始私人数据或几百页的长文档。

3.4 把内容塞进会话的几种轻量办法

新手最容易忽略的事：Claude Code 有三种比“打字喂给 agent”轻得多的方式，把文件、命令、截图带入对话。每种都只差一个按键。

@路径/文件 —— 文件引用。 输入框里敲 @，Claude 弹出路径补全器，Tab 接受。文件像贴进上下文那样被读入，但提示词本身保持短，路径被原样记录。这是把代码本、初稿、CSV 表头塞给 agent 最干净的方式：

> 读 @data/raw/cfps-2020-codebook.pdf，列出所有衡量上网行为的变量。

@dir/ 一次附整个目录（agent 收到的是递归列表，不是全部内容）。

!command —— shell 直通。 提示词以 ! 开头，整行去到你的 shell 跑，结果回插到对话里。不会弹工具权限框 —— 你自己的 shell，你自己负责：

> !wc -l data/processed/*.csv
> !git status -s
> !Rscript scripts/01-build-sample.R

想顺手扔个 ls、git diff、head -n 5 file.csv 进对话，这是最快的路 —— 不必让 agent 提议一次 Bash 调用。

拖放（与粘贴）。 把文件从访达 / 文件管理器拖到 Claude Code 终端窗口，绝对路径会落到光标处。一次性附件（审稿意见的截图、刚下的 PDF）特别合适。macOS 上 Cmd+V 直接粘图，Claude Code 会把图写到临时路径再引用。

自检： 试一下 @CLAUDE.md —— Claude 应该悄悄读完，而不弹出 Read 工具调用提示。如果看到了，那是因为你敲的是 > 而不是 @。

3.5 选对模型 —— 也选对工具

/model 在会话内打开模型切换器，不必重启会话。默认 /model 只对当前会话生效——按 d 把它设成未来会话的默认（v2.1.144+）。取舍很直接：一轴是速度与成本，另一轴是推理深度。

4.8 改了什么。 Opus 4.8 把 SWE-bench Verified 拉到 88.6%（4.7 是 87.6%）、SWE-bench Pro 拉到 69.2%（4.7 是 64.3%）；USAMO 2026 数学从 69.3% 跳到 96.7%；1M-token 长上下文检索几乎翻倍（GraphWalks 1M：68.1% vs. 40.3%）。对”氛围式研究”最关键的变化是代码诚实度：Anthropic 报告 Opus 4.8”大约比 Opus 4.7 少四倍地让自己写的代码瑕疵静默通过”——意味着 scholar-analyze 与 scholar-compute 的输出里更少出现你看不见的回归。注意点：提示词注入的稳健性略有回退（Opus 4.8 攻击成功率 9.6%，4.7 是 6.0%），所以数据敏感项目不要因此放松 safety-status 关卡。

Fable 5 —— 新的天花板。 2026-06-09，Anthropic 发布了 Claude Fable 5（claude-fable-5），这是其最强（Mythos 级）模型家族里第一个公开可用的成员，也是你现在能调用的最强模型。它在几乎所有测过的基准上都是 state-of-the-art——软件工程（在 Cognition 的 FrontierCode 上即便用 medium effort 也居首）、知识工作（Hebbia Finance Benchmark 最高分）、科研，尤其是视觉：它能从密集的科学图表里读出精确数字，还能从截图重建一个 Web app 的源码。定价为每百万 input / output token $10 / $50——大约是 Opus 4.8 的两倍，也是 Anthropic 通用可用模型里最贵的。内置防护会把高风险提示（网络安全、生物/化学、模型蒸馏）改由 Opus 4.8 回答，触发率不到 5% 的会话。可用性：2026 年 6 月 9–22 日在 Pro、Max、Team、按席位计费的 Enterprise 套餐上免费包含；6 月 23 日后改走 credits，直到容量允许时才完全恢复到套餐内。（其无防护的同胞 Mythos 5 是同一底座、放开了部分防护，仅限受信任访问——工作坊项目用不上。）做”氛围式研究”时，只在 Opus 4.8 配 /effort max 仍不够、或任务确实重视觉时才动用 Fable 5；Opus 4.8 仍是日常旗舰，而 Fable 在 6 月 23 日后按 credits 计费，一直挂着很容易超支。

Fast 模式（Claude Code 的 --fast flag 与 /fast 开关）现在默认用 Opus 4.7（v2.1.138 之前默认是 Opus 4.6）。配 Opus 4.8 的 Fast 模式以 2× 标准价拿 2.5× 速度——每 token-秒大约比之前 Opus 4.7 的 Fast 模式便宜三倍。Fast 模式适合大批量的 scholar-monitor 抓取、scholar-eda 重跑、以及任何”agent 要跟得上你打字”的场合。

常见的成本失误：整条 CFPS 流水线一直挂着 Opus。scholar-monitor、安装步骤、大规模机械编辑切到 Haiku；多数分析与写作切到 Sonnet 4.6；理论部分、识别 memo、pre-mortem、最终对抗性审稿才切到 Opus 4.8 配 /effort xhigh。第一次端到端跑完后用 /usage（v2.1.149+ 的”按 skills / subagents / plugins / MCP 拆账”视图）确认最大的成本项在哪，再决定要不要给那一步上 /effort max。

最常见的成本错误是整条 CFPS 流水线都开 Opus。scholar-monitor、安装步骤、大块机械改写换成 Haiku；只有理论段、识别 memo、pre-mortem、最终对抗性审稿才上 Opus。

/agents —— 管理与启动子智能体。 子智能体（subagent）不等于 skill。

• Skill（所有 scholar-*）是命名工作流：一份 SKILL.md 加上 assets/references；通过 /skill-name args 调用。
• Subagent 是带独立上下文窗口的轻量工作者，有自己的工具和提示词，返回单个答案。Skill 内部会调 subagent（例如 scholar-code-review 并发起六个 reviewer subagent）。

工作坊里你大概率不会自己写 subagent。但如果想跨项目复用比如一个”citation-fact-checker” subagent，/agents 就是列出、编辑、新建它的命令。

WebFetch 与 WebSearch —— 你最先碰到的两个 web 工具。 Claude Code 既能抓取已知 URL，也能跑搜索 —— 这正是 scholar-lit-review、scholar-monitor、scholar-citation 背后用的工具。

• WebFetch(url) —— 下载单页面，把渲染后的文本喂给 Claude。每个新域名首次使用时弹权限框。
• WebSearch(query) —— 跑搜索返回结果列表。首次弹框；结果链接可被 WebFetch 接力。

权限含义：处理敏感数据的项目，往往应该把 WebFetch 限制在学术域名白名单内（crossref.org、openalex.org、*.gov 等），防止 agent 把含参与者文本的 query 发到陌生站点。配置位置：/permissions 或 .claude/settings.json。

3.6 MCP —— 接入外部数据源

Model Context Protocol（MCP） 是 Claude Code 跟外部系统对话用的开放协议，省去你写自定义插件的工夫。一个 MCP server 暴露 tools（Claude 可调用的函数）与 resources（Claude 可读的文件），走小型 JSON 协议；Claude Code 是 client。装一次 server，它的工具从此和内置工具并列。

每个 MCP server 都通过三种原语（primitives）之一暴露内容；某样东西属于哪个原语，决定了由谁来触发它：

这就是为什么有些 MCP 行为在你已授权的权限下自动流转（model-controlled tools），另一些则要等显式的用户触发（user-controlled prompts）。原语的名字告诉你谁来决定 —— 模型、应用，还是用户。

社会科学研究者最先回本的两个 MCP server：

• Zotero MCP —— 把你的 Zotero 库暴露给 Claude。agent 能搜你的 collection、拉论文 PDF + 元数据、自动写进对应 collection。scholar-lit-review 之所以能“读完整本地论文”而不是凭空捏造引文，靠的就是它。
• GitHub MCP —— 把你的仓库、issue、PR 暴露给 Claude。scholar-replication（“根据最近 12 个 commit 写发行说明”，“用这组改动开个 PR”）特别用得上，也是管 output/ 仓库的好帮手。

其他值得一装：处理本地数据库的 Postgres / SQLite MCP；想让 Claude 受控访问项目根目录之外的目录（例如 ~/data/ 共享缓存）的 Filesystem MCP。

添加一个 server。 最简单的路径：

# Zotero：本地 stdio server（zotero-mcp 这个 Python 包，用 uvx 跑）
$ claude mcp add zotero -- uvx zotero-mcp

# GitHub：官方远程 server。旧的 npm 包 server-github 已弃用；
# 改用托管 endpoint，把细粒度 PAT 放到 header 里。
$ claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
    --header "Authorization: Bearer $GITHUB_PAT"

$ claude mcp list

先从 CLI 查看某个 server 的配置与连接状态，再进会话里看它真正暴露了哪些工具：

$ claude mcp get zotero      # 查看单个 server 的配置与连接状态

> /mcp                       # 在 Claude Code 会话里：列出每个已连接 server，
                             # 带工具数量与登录状态

（没有 claude mcp tools 这个子命令；要看每个 server 的工具清单，用 /mcp。）

大多数 server 要凭证（Zotero API key、GitHub PAT）。按 §2.6.3 的做法存进 ~/.api-keys，从 server 配置里引用；永远不要硬编码到 settings.json。

工作坊纪律： 只在替代方案是“agent 反复编造引文 / PR 描述 / 数据行”时才加 MCP server。MCP 不是免费升级 —— 每多一个 server 就多一处可能把数据送到你没打算去的地方的表面。

3.7 在编辑器里跑 Claude Code

多数学员最终是在编辑器里、而不是裸终端里用 Claude Code。三种集成最要紧：

• VS Code 扩展（发布者 Anthropic）。从 Marketplace 装；它会加一个 Claude 面板，把编辑器的当前选区、Problems 面板、git diff 绑到对话里。在 WSL2 / SSH-remote / devcontainer 窗口里，它会跟着 remote root 走。
• Cursor 与 JetBrains 系列。 Cursor 是 VS Code 的分支，装的是同一个扩展，行为一致。JetBrains 系列用的是 JetBrains Marketplace 上另一个独立的 Claude Code 插件；它在 IDE 终端里跑 Claude Code，所以模式循环和 --permission-mode 跟 CLI 一样——工作流相同，包不同。
• JupyterLab。 目前没有原生 Claude 扩展，但 JupyterLab 的 terminal 标签页和普通 shell 一样 —— 在里面跑 claude 即可。RStudio 同理：打开 Terminal 面板，运行 claude；项目根目录自动是 RStudio 的工程目录。

IDE 接入的会话里会变的：

1. agent 拿得到 IDE 的当前选区与打开文件作为隐式上下文 —— 你可以说“这个函数”而不必贴代码。
2. 诊断信息（linter、类型错误）自动流入对话，“修一下下面这些类型错”这种提示无须粘贴。
3. diff 视图是 IDE 原生 diff，不是 CLI diff —— 大改动时可读性强多了。

不变的：项目根、CLAUDE.md、.claude/settings.json、PreToolUse hook、权限模式。IDE 只是前端；agent 与其安全边界跟终端模式完全一致。

3.8 Headless 模式、定时任务、团队配置

下面这三件事，是你信任 Claude Code 到愿意让它脱离手动监督之后才用得上。

Headless / 非交互模式。 从 shell 脚本或 cron 跑一条提示词：

$ claude -p "用一段话总结今天 scripts/ 下的提交；保存到 logs/daily-$(date +%F).md"

加 --output-format json 拿机器可读输出再管道给下游工具。-p 模式里没有交互批准循环，所以提示词需要的每一个工具都必须事先在项目的 .claude/settings.json 里允许。敏感数据上不要在没白名单的情况下开 headless。

GitHub Actions。 Anthropic 官方发布了 claude-code-action，可以在每个 PR 上跑 claude -p。最简工作流：

# .github/workflows/claude-review.yml
name: Claude review on PR
on: [pull_request]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "审查 diff 是否出现不当因果语言。"

研究中的用法不是发功能 —— 是把 CLAUDE.md 里声明的“禁止主张”清单，在每一次动到稿子的 PR 上自动执行一遍。

settings.json 三层 —— user / project / local。 Claude Code 按下面顺序合并三份配置（后者覆盖前者）：

这种分层很重要：你提交的（project 层）是 IRB / 复制包记录的一部分；你不提交的（local 层）只属于你的笔记本。secrets 进 local 层；团队规则进 project 层。

OAuth 与 API key 两种登录路径。

• OAuth via Anthropic Console —— 跑 claude login 打开浏览器，以你的 Anthropic 账号认证，Claude Code 保存刷新 token。结算走你的 Claude Pro / Max / Team 订阅。个人研究者首选。
• console.anthropic.com 的 API key —— 粘贴 key，结算走 API console。适合机构持有 Anthropic 账号、给你发项目级 key、想能按项目撤销访问的场景。

如果机构要求每项目独立审计轨迹，优先 API key —— 可以按项目轮换 / 撤销，Anthropic Console 也能按 key 看用量。

自检： 三层 settings 配完之后跑一次 /doctor，再跑 claude mcp list 看注册了哪些 server。如果 /doctor 报三层之间不一致，先解决再进 §4。

4. 最小安全项目结构

digital-divide-china-cfps/
├── CLAUDE.md                  ← 持久项目简报
├── .claude/
│   └── safety-status.json     ← 哪些文件 CLEARED / LOCAL_MODE / HALTED
├── data/
│   ├── raw/                   ← 原始 CFPS .dta，永不手工修改
│   ├── interim/               ← 可再生的中间文件
│   └── processed/             ← 由脚本生成的处理后数据
├── materials/                 ← 中英文问卷与代码本
├── output/
│   └── digital-divide-china-cfps/
│       ├── design/            ← idea、blueprint、变量字典
│       ├── scripts/           ← 所有 R / Python 脚本
│       ├── tables/            ← 回归表、描述表
│       ├── figures/           ← PDF / PNG 图
│       ├── drafts/            ← 各版手稿
│       ├── verify/            ← 验证报告
│       ├── citations/         ← refs.bib、引用日志
│       ├── replication-package/
│       └── logs/              ← 时间戳日志
├── logs/
│   └── init-report.md
└── README.md

要点：

• data/raw/ 是圣域，所有变换都必须由 output/<slug>/scripts/ 里的脚本完成；如果不能从 data/raw/ 一键再生 data/processed/，项目就坏了。
• output/<slug>/ 是工作区，每个技能写到固定子目录，让你随时能找到 verify/、drafts/、tables/。
• logs/ 是证据。验证发现问题时，第一句话永远是“那次跑的时候到底干了什么？”

如果你目前的项目是桌面一堆 final_v3_REAL.xlsx，智能体救不了你；它只会让混乱跑得更快。先做 scholar-init。

5. 练习 1 —— 把模糊请求改写成智能体任务

用时： 5 分钟。继续学习前先做。

模糊版（不要）：

“用 CFPS 数据写点关于中国数字鸿沟的东西。”

智能体级别（要这样写）：

INPUTS（允许读取）
  - data/raw/cfps2010adult_*.dta 至 cfps2020person_*.dta
  - materials/ 下的代码本
  - design/variable-dictionary.csv
TASK（任务）
  - 构建个人–波次面板，限制 16+ 岁；harmonize：
    互联网接入、每周使用小时、户口、教育、世代、性别、家庭规模、省份。
OUTPUTS（产出）
  - data/processed/cfps-panel-long.rds
  - logs/01-build-sample-<timestamp>.log
  - 仅打印一份摘要：按 wave × hukou 的行数。
QUALITY STANDARD（标准）
  - 所有样本限制写在脚本头部。
  - CFPS 缺失代码（-1, -2, -8, -9, -10）一律转 NA。
  - 一条命令可端到端运行：`Rscript 01-build-sample.R`。
AUDIT（审计）
  - 打印每个被读文件的路径，给输出 rds 计算 SHA256。
STOP RULE（停止规则）
  - 任意一波缺超过 3 个预期变量则停下并报告，不要插补。
  - 处理后面板少于 150,000 行则停下。

第一版让智能体写论文；第二版让智能体执行一个可测、有边界、可检查、能停下的任务。

六个组成部分：

提示词里最重要的一句话：“如果无法验证，就明确标记。” 这一行能改变智能体行为——它允许“不完整”，而不是装作“很有信心”。

5A. Claude Code 2026 新特性：动态工作流、子智能体与自动化

目标： 搞清楚 Claude Code 近一年新增的能力里，哪些真正改变了你做研究的方式、哪些只是顺手——这样你才能挑对工具，而不是把所有事都硬塞进一个聊天窗口里去硬抗。

第一部分一直把 Claude Code 当成“一个会话里的一个助手”。这个心智模型现在依然成立，但它把 2026 年的大半套能力都晾在了一边。过去一年的版本更新，给智能体加上了把任务铺开、放到后台跑、按时间表重复、并自动执行你设定规则的能力。用得好，它能把“写一篇论文的流程”升级成“一个小型研究流水线”；用得糙，它只会让“未经验证的结论”多出更多藏身之处。本手册反复强调的纪律——任务有边界、产物可检查、标准由人把关——在自主性升高时只会更重要，而不是更不重要。

下面这些特性变化很快。请把具体的命令名和默认值当成 2026 年年中的一张快照；当某个东西行为不一样时，在会话里敲 /help、并查阅更新日志（claude changelog 或官方文档）。概念是稳定的，写法会漂移。

先给一张速查表，告诉你什么时候该用什么：

计划模式 —— 动文件之前先看计划

按 Shift+Tab 在多个权限模式之间切换，其中之一就是计划模式。在这个模式下，智能体可以读取、搜索、推理，但在你批准之前不能改文件、不能跑 shell 命令。它会产出一份书面计划然后停下来等你。

> Shift+Tab  （切到提示栏显示 “plan mode” 为止）
> 读一下建样本脚本和变量字典，然后给我一份方案：加一个省级固定效应的稳健性
  检验。先别写任何东西。

对研究者来说，这是最便宜的一份保险：你在自己的分析改动一行之前，就读到了它打算怎么做——改哪些文件、用什么估计量、产出什么。批准它，智能体就切到执行；否决它，则一个字都没动过。

子智能体 —— 把一个有边界的活儿交给全新上下文

子智能体是主会话委派出去的一个独立 Claude 实例。它在自己的上下文窗口里运行，有自己的系统提示词、可选的受限工具清单，甚至可以用不同的模型。主对话拿回来的只是这个子智能体的总结——而不是它为了得出结论读过的那 30 个文件。

你其实早就在依赖它了：scholar-code-review（“六位评审、一份报告”，第 13 节）和 scholar-verify 系列（第 15 节、附录 F–J）就是靠并行派发专职子智能体来工作的。你也可以自定义。往 .claude/agents/ 里放一个文件：

---
name: lit-triage
description: 针对给定的研究问题给论文做相关性初筛，返回一句话判定加引文。
  用于批量文献初筛。
model: haiku
tools: Read, WebSearch, WebFetch
---
你一次只筛一篇论文，对照研究问题判断。
返回：RELEVANT / MAYBE / NOT、一段话理由、以及引文。
绝不编造发现；如果拿不到论文，就直说。

然后用大白话提需求（“把这 20 条摘要按数字鸿沟这个问题做初筛”），Claude 就会把每一条路由给 lit-triage 这个工作体。把快、重复的活儿派给 haiku 还能省钱。第 1 节的规矩依然成立：子智能体的总结描述的是它打算做什么——抽查产物，别盲信总结。

动态工作流 —— 铺开、协调、并放到后台

这是最受关注的新增能力，也是工作坊被问得最多的一个。动态工作流是智能体替你规划并运行一支子智能体队伍：Claude 根据你的任务描述写出一段简短的编排脚本，再由运行时执行它——派出许多工作体（任务的独立单元）、同时只跑限定数量的几个、并把中间结果存在脚本变量里，而不是一股脑全塞进你的对话。它跑的时候，你的会话仍然能用。

如果说单个子智能体是“做这一件有边界的活儿”，那动态工作流就是“把这件事跨数百个单元做完，再把汇总结果端给我”：

> 用一个工作流：对 analysis/ 下的每个 .R 脚本，检查在拟合任何模型之前，是否
  已把缺失值代码（-1,-2,-8,-9,-10）转成 NA。返回一张表：脚本、行号、状态。
  并行跑、再汇总。

适合这种模式的研究场景：

• 全仓 / 全语料审计 —— 每个脚本、每个变量、每条图注，用同一把尺子查一遍。
• 批量转换 —— 把 500 个文件拆成独立单元做重编码或重新协调。
• 交叉核验式综述 —— 让几个工作体从相互独立的角度调查同一个论断，再做对账，而不是只信一次结果。

成本与告诫。 工作流会把 token 开销乘以它派出的工作体数量。务必先在一小片上试——一个目录、一个波次、一个问题——确认输出形态对了，再铺开。而且因为运行途中没有人把关，第 5 节的“停止规则”纪律不是可选项：把“如果无法验证，就明确标记”直接写进任务里。

自定步调循环与目标驱动

两种让智能体“干到完为止”而不用你盯着的办法：

• /loop 重复一条提示词。给它一个间隔（/loop 5m 检查任务跑完没有）用来轮询，或者让它自定步调（/loop 一直修失败的测试，按需迭代）由智能体自己决定何时进入下一轮。
• 完成目标让智能体跨多轮自动连续推进，直到一个可度量的条件达成——“直到 Rscript 11-analyze.R 干净跑通、且头条表格与附录 G 对得上”。

它们在分析的“机械尾巴”上最好用：复现一张表、把脚本一条命令跑通、把 linter 清到零。但它们不擅长模糊目标（“把论文写得更好”）——那种永远不会干净收敛，所以把条件设成可二元判定、可核对的。

后台任务与监控

长任务——整条流水线、一大批模型调用、慢编译——可以在同一个会话里丢到后台跑，你继续干别的。智能体把活儿交出去，跑完通知你，你也可以查看中间输出，而不必盯着一个卡死的终端。对研究来说，这意味着那个 40 分钟的数据构建，和你现在正在做的稿件修订，不再互相挡道。

定时任务 —— /schedule

/schedule 创建按时钟运行的周期性任务（在云端 / 远程配置下，关掉终端也能持续）。你用大白话描述节奏和活儿：

> /schedule  每个工作日早 8 点，搜索关于 “digital inequality” 的 arXiv 新论文，
  把每篇的一句话摘要追加到 lit/inbox.md

自然的研究用法：早晨的新论文摘要、周五晚上的数据质量巡检、每月一次的日志归档。它会计入你的用量、并以你授予的文件权限运行，所以像对待任何智能体任务一样去框定它的范围。

钩子 —— 把数据边界从“指望”变成“强制”

第 1 节说过：智能体的读取边界就是你的数据边界。钩子（Hooks）让你用机械的方式来强制执行它。钩子是 Claude 在某个事件上自动运行的 shell 命令——工具调用之前（PreToolUse）、之后（PostToolUse）、会话开始时，等等——而一个 PreToolUse 钩子可以拦截某个动作。在 .claude/settings.json 里配置：

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard.sh" }] }
    ]
  }
}

脚本检查待执行的命令，以非零退出（或返回拒绝决定）来回绝它——比如回绝任何 rm -rf，或任何写到 data/processed/ 之外的操作。这就是你把“请别动原始数据”从 CLAUDE.md 里一句礼貌请求，变成一条被强制执行的规则的办法。

被强制执行，但仍然是协作式的：harness 跑你的脚本并服从它的裁决，而一条铁了心的命令可以把自己编码绕过任何黑名单（§6.4）。真正不协作的那个东西，是沙箱。

Bash 沙箱 —— /sandbox 及其两种模式

Claude Code 为 Bash 工具自带一个 OS 级沙箱。钩子是请求，沙箱是强制：操作系统直接拒绝那次 open()，对该命令及它派生的每一个子进程都生效，无论路径是怎么拼出来的。macOS 用 Seatbelt，Linux 与 WSL2 用 bubblewrap。原生 Windows 不支持 —— Windows 学员请在 WSL2 里跑 Claude Code（附录 K）；WSL1 同样不行。

你不必手写 JSON 才能打开它。/sandbox 会打开一个带三个标签页的面板：

第四个标签页 Dependencies 只在缺东西时才出现，并指明你的平台缺的是 ripgrep、bubblewrap、socat 还是那个可选的 seccomp 过滤器。在 Linux/WSL2 上先 sudo apt-get install bubblewrap socat 再重启 —— 依赖检查在启动时跑一次，所以你不重启，面板就发现不了你刚装好的包。

两种模式，逐一说清。 两者强制的文件系统与网络隔离完全相同，唯一的差别是会不会问你。

Auto-allow 不等于“什么都不问”。有四件事照样会拦住你：显式的 deny 规则，永远生效；瞄准 /、你的 home 目录或关键系统路径的 rm/rmdir；内容维度的 ask 规则，比如 Bash(git push *)；以及计划模式（plan mode）下，只读集合之外的命令一律提示。只有裸的 Bash（或 Bash(*)）ask 规则会对沙箱内命令跳过 —— 而且在计划模式下连它也不跳过。

在面板里选模式，会写进 .claude/settings.local.json，所以只对那一个项目生效。想让你做的一切都在沙箱里，就在 ~/.claude/settings.json 里设 "sandbox": {"enabled": true}。

那个会让你意外的默认值 —— 而且它对受限数据很要紧。 沙箱默认的写范围是工作目录加会话临时目录；默认的读范围却是整台电脑，只减去少数被拒目录 —— 其中仍然包含 ~/.ssh 与 ~/.aws/credentials。把沙箱打开并不会保护你的微观数据。那堵墙只能靠你自己加 sandbox.filesystem.denyRead，或者一个 sandbox.credentials 块（文件用 "mode": "deny"；环境变量用 "deny" 或 "mask"）。网络的默认值恰好相反：没有任何域名被预先允许，命令第一次需要某个域名时会提示你，批准之后在本次会话剩余时间内有效。

在你把它当成一项安全控制来依赖之前，还有两个行为值得知道：

• 逃生舱。 当一条命令是因为沙箱限制而失败时，Claude 可能带上 dangerouslyDisableSandbox 重试它 —— 那次重试在沙箱外跑，走常规权限流程。设 "allowUnsandboxedCommands": false 会让这个参数被彻底忽略，这正是 Overrides 标签页所说的 Strict sandbox mode。
• 它默认是 fail-open 的。 如果沙箱压根起不来（缺依赖、平台不支持），Claude Code 打印一条警告，然后不带沙箱地跑你的命令。设 "failIfUnavailable": true 才会把它变成硬失败。对一个受 DUA 约束的项目，你要的就是这个设置。

最后是一个文档反复强调、而且很容易搞反的区分：/sandbox 不是一种权限模式（§3.1）。权限模式决定一次调用是否执行；沙箱决定它一旦跑起来能碰到什么。两者叠加使用 —— 而且沙箱的 auto-allow 与权限系统的 auto 模式是不同的机制，后者靠的是一个分类器。

这也正是 /scholar-safety level lockdown 替你配置的那套机器（§6.6）—— lockdown 生成的就是对 data/ 做 denyRead 的 OS 沙箱配置，这既是它成为套件里唯一真正隔离边界的原因，也是它连你自己的 Rscript 一起挡住的原因。

技能与插件 —— 把一套流程打包一次

技能（Skill）是 .claude/skills/<名字>/ 下的一个文件夹，里面的 SKILL.md 装着一套流程；它的全文只有在技能被调用时（/<名字>）才加载，所以不用时不占上下文。open-scholar-skill 正是如此——它是一包技能（scholar-init、scholar-design、scholar-verify……）。插件（Plugins）则把技能、子智能体、钩子、MCP 服务器打包到一起，让一个实验室一次安装就能共享整套工具。给学员的启示是：当你发现自己在不同项目里反复敲同一套多步指令时，那就是一个等着被写出来的技能。

MCP 服务器 —— 接入 Zotero、数据库与网络

模型上下文协议（MCP）让智能体把外部工具和数据源当成一等公民的工具来调用。用 claude mcp add … 添加（或在 .mcp.json 里声明），然后 /mcp 查看状态并处理登录。

$ claude mcp add --transport stdio zotero -- uvx zotero-mcp

对研究来说，这是通往你的文献管理器、结果数据库、笔记服务或可信网络检索工具的桥梁——让智能体直接拉取结构化数据，而不必你手动复制粘贴（从而引入正是第 15 节存在意义所在的那类转录错误）。

工作树 —— 不打架的并行实验

工作树（worktree）是位于自己分支上的一个独立工作目录。Claude Code 可以在其中跑一个会话——或隔离一个子智能体——这样两条工作线就永远不会覆盖彼此的文件。用 claude --worktree try-province-fe 开一个；智能体在那里开发，只有当这个实验值回票价时你才合并它的分支。非常适合“把分析跑两种做法再对比”，而不污染你的主检出。

模型、思考强度与快速模式

三个值得知道的旋钮：/model 在 Opus（推理最深）、Sonnet（均衡）、Haiku（又快又省——适合子智能体和初筛）之间切换；思考强度（effort）设置用思考深度换速度和成本；/fast（在较新的 Opus 4.x 上）让日常活儿的回答明显更快。一个合理的默认：设计、分析、验证用 Opus，批量机械的子智能体活儿用 Haiku。此外还有 /ultrareview——一个由你手动触发、计费的多智能体评审，针对你当前分支或某个 PR，比 scholar-code-review 更重、更独立的第二意见。

关于自主性与验证的一点提醒

本节里的每一项能力，都把工作从那个“被盯着的单一会话”里挪了出去，挪向队伍、时间表和后台运行。这是实打实的效率提升，也是实打实的风险集中：智能体无人值守地做得越多，一个错数字在被人看到之前就能跑得越远。所以工作坊的核心一课（第 15 节）会随着这些工具一起放大——你授予的自主性越多，验证与可检查产物就越是不可妥协。新能力，同一份契约：问题和标准由你把关，执行由智能体负责。

有一样产物让这一切可检查。 现在每次 /scholar-* 运行都会留下一条 推理–行动–观察（RAO）轨迹——一个只追加的 logs/trace-<skill>-<date>.ndjson，每一步一条 {reasoning, action, observation, refs, status} 记录。你看的 process-log-*.md 是它的渲染视图；覆盖检查会让任何没留下轨迹的 phase 直接 RED 失败。被派出的子 agent（评审、验证）会写一个 .trace.ndjson 边车，由编排器汇入。隐私规则：轨迹只记结论、计数和文件引用——绝不记原始行、引文或 PII，LOCAL_MODE 下只记派生的聚合量。

第二部分：Open Scholar Skills 全流程

这是工作坊的核心。我们只用 open-scholar-skills 这一套技能，搭一篇 Social Forces 风格的中国数字鸿沟论文。这一部分里每一段代码都来自 2026 年 5 月 4–5 日的真实运行。项目 slug：digital-divide-china-cfps。

技能按你实际使用的顺序出场。但在走流程之前，有三样东西要一直摆在手边：完整清单（§5B.1）、所有技能共享的参数语法（§5B.2）、以及让整条链条成立的产物契约（§5B.3）。

5B. 套件全景 —— 清单、语法、契约

5B.1 全部 44 个技能，按阶段排列

§ 那一列指向本手册中完整记录该技能的章节 —— 每个模式、每个参数、每道关卡、它写下的每个文件。

◆ 标记的是只在扩展版里才有的九个技能（§2.4）。公开版上这些命令不存在；没标记的在两个版本上完全一样。

套件安装到 ~/.claude/skills/<skill-name>/SKILL.md。这个目录里的任何东西都能以 /<skill-name> 调用。装完先验一下：

$ ls ~/.claude/skills/ | grep -c scholar           # 公开版 35 · 扩展版 44
$ ls ~/.claude/skills/scholar-full-paper/          # SKILL.md, references/, scripts/

阶段 0 —— 建项目、护数据

阶段 1 —— 找问题、磨问题

阶段 2 —— 数据之前先有设计

阶段 3 —— 分析

阶段 4 —— 写作与验证

阶段 5 —— 投稿、共享、复用

阶段 6 —— 下游产品

编排器（第三部分）

5B.2 所有技能共享的参数语法

每个技能都在 frontmatter 里声明一个 argument-hint。第一次跑之前先读它：

$ head -8 ~/.claude/skills/scholar-design/SKILL.md

---
name: scholar-design
description: Plan a rigorous research design, run power analysis, ...
argument-hint: "[quant|qual|mixed|experiment|power|methods-section|pap|
                computational|NLP|ML|network|ABM|premortem|blueprint]
                [research question] [optional: data source, design type,
                journal target]"
---

从这条语法能推出三条规则：

1. 第一个 token 几乎总是模式。 [a|b|c] 的意思是「恰好挑一个」。省略了，技能会从你的散文里猜 —— 通常猜对，但猜要花掉一轮，偶尔还会挑错分支。把模式说出来。
2. 方括号里的 optional: 项是关键词式的，不是位置式的。 journal=Social Forces 和 target Social Forces 都能用，技能解析得很松。优先用 key=value —— 复制粘贴进脚本也不会坏。
3. 文件路径是字面量。 相对路径是相对 Claude Code 的启动目录解析的，不是相对 output/<slug>/。拿不准就贴绝对路径。

一次成形的调用会点明五样东西：模式、对象、数据、期刊、约束。

> /scholar-analyze data=data/processed/cfps-panel-long.rds
                  outcome=y2_hours
                  predictors=hukou_rural,cohort,female,eduy
                  fe=province_x_wave
                  journal=Social Forces

一次没成形的调用只点明一样：> /scholar-analyze 把模型跑一下。

5B.3 产物契约 —— 链条为什么不散

技能之间不在对话里传信息。它们通过 output/<slug>/ 里磁盘上的文件传。这就是全部的诀窍，也是你可以停下来、合上电脑、三天后接着干的原因。

现在就该内化两条推论：

• 删掉一个文件会静默地折断链条。 你要是 rm 了 design/results-lock-*.md，scholar-write 不会报错 —— 它会凭想象起草。能抓住这件事的只有验证，所以 §15 不是可选项。
• 每个技能都能单独跑。 这一部分里的每个技能都能独立工作，只依赖磁盘上碰巧存在的文件。第三部分的编排器加的是关卡和顺序，它们不提供单个技能没有的能力。

5B.4 轨迹契约 —— 每一步都写下来

第一部分讲过 agent 的那个 loop：Thought → Action → Observation。现在套件里的每个技能都会把那个 loop 写下来，每一个有意义的步骤追加一条记录，落在 logs/trace-<skill>-<date>.ndjson：reasoning（为什么）、action（做了什么）、observation（返回了什么），外加 refs、status 和派发它的 agent 的 id。第二部分里到处引用的那份可读的 process-log-*.md，是这个文件的渲染视图，绝不手写。一个产生不出有效轨迹的阶段，会被它的关卡判 RED。

诚实的那部分 —— 这段请仔细读。 外壳没法记录模型隐藏的思维链。被记下来的是陈述出来的理由 —— 一句简短、能说清楚的“为什么”。

所以轨迹不是模型当时在想什么的证据。它是模型声称自己在做什么的证据，旁边并排放着它实际做了什么、以及返回了什么。那才是你能审的部分，也是从来就唯一可查的部分。任何比这更强的读法，都是你撑不住的主张。

两条规则让轨迹可以拿出去共享：

• 只放聚合量。 reasoning 和 observation 里装的是指标、判定、计数和文件路径 —— 绝不放数据行、引文或 PII。记的是你看到了什么、它是什么形状，而不是具体的值。
• 那引文放哪？ 放在 evidence/ —— 也就是 §8A.6 那个账本。捕获了锚的轨迹步骤只按 anchor_id 引它，绝不把原文内联进来。两份产物，一次运行，一次刻意的切分。

子智能体没有自己的 shell，所以它们各自吐一个 .trace.ndjson 边车文件，由编排方折叠进主轨迹 —— 并与派发清单交叉核对，因此一个 agent 没法被悄悄从记录里抹掉。

同一份契约也归档代码：每一个被执行的 R/Python/Stata/Julia 脚本 —— 包括 LOCAL_MODE 下的 Rscript -e 与 python3 -c heredoc —— 都会带着该技能的编号前缀和一段运行头，逐字写进项目的 scripts/ 目录。正是这一条，让 §13.7 那句“被审的字节必须就是被执行的字节”在事后仍然可查，而不是只在运行的那一刻成立。

项目会自动获得这套规则：scholar-init 把它写进项目 CLAUDE.md 的自动规则块（精简档是 §F，完整档是 §14），已有项目在下一次运行时刷新。在这条规则存在之前，一个跑独立技能的精简档项目，加载的 CLAUDE.md 里关于可追溯性一条规则都没有，全靠每个技能自己记得自己的协议。

6. scholar-init + scholar-safety —— 从安全开始

目标： 创建标准项目结构、对每个文件分类、装好强制执行这些分类的守卫，并写下后续所有技能都会查阅的安全契约。

这两个技能共用同一套机器 —— 同一个扫描器、同一个匿名器、同一个 sidecar 文件、同一个 PreToolUse 钩子。分工很简单：scholar-init 管项目和文件分类；scholar-safety 管操作、协议和强制力度。

6.0 scholar-init 的四个模式

argument-hint: "[init <slug> <file1> <file2> ...] | [review] | [add <file1> ...]
                | [status] — defaults to init if a slug-looking argument is
                provided, review otherwise"

slug 必须匹配 ^[a-z][a-z0-9]*(-[a-z0-9]+)*$，2–64 个字符。如果你丢给技能的是一句主题描述（”digital divide in China”），它会替你 slugify —— 转小写、去停用词、连字符化、截到 48 字符 —— 并在动手建任何东西之前要求你确认。

6.1 跑 scholar-init

> /scholar-init init digital-divide-china-cfps \
                ~/data/cfps/raw \
                --materials ~/data/cfps/materials

底层 scripts/init-project.sh 接受的 flag：

--force 会销毁此前的 review 决定。 重建会用一次全新扫描重写 sidecar，于是你做过的每一条 OVERRIDE 理由、每一个 LOCAL_MODE 选择都没了。除非你是真心想从头来过，否则请增量地修一个坏掉的 init。

它按顺序做的事：

1. 创建 <dest>/<slug>/，内含 data/{raw,interim,processed}/、materials/、output/、logs/、.claude/ —— 外加 corpus/，但只在你传了 --corpus 时才建，免得不用语料的项目多出一个空目录。
2. 把原始文件拷贝（或加 --link 时软链）进 data/raw/，材料进 materials/，文本语料进 corpus/。重名的加数字后缀。
3. 通过 scripts/gates/safety-scan.sh 对每个 ingest 进来的文件跑一次纯本地安全扫描 —— 只用 file、wc、grep、awk。Claude 看到的是计数和模式类别，绝不是匹配到的值。
4. 写 .claude/safety-status.json、logs/init-report.md、README.md、.gitignore。
5. 把自动托管的项目记忆块写进 CLAUDE.md（Claude Code 宿主）、AGENTS.md（Codex 宿主），或者两个都写（宿主未识别时）。
6. 只要有任何文件回来是 YELLOW 或 RED，立刻转入 review 模式，不再多问。

真实运行的终端输出（节选）：

[scholar-init] Creating project: digital-divide-china-cfps
[scholar-init] Ingesting 38 raw files from data/raw ... ok
[scholar-init] Ingesting 19 materials files ... ok
[scholar-init] Running safety scan ...
  cfps2010adult_201906.dta            : CLEARED        (de-identified PIDs)
  cfps2018crossyearid_202104.dta      : CLEARED        (cross-year ID file)
  cfps2020person_202306.dta           : NEEDS_REVIEW   (location items, COVID)
  CFPS_2020_QnrAdult_EN.pdf           : CLEARED        (codebook)
  ...
[scholar-init] Wrote .claude/safety-status.json
[scholar-init] Wrote logs/init-report.md
[scholar-init] DONE — 35 CLEARED, 3 NEEDS_REVIEW, 0 HALTED

init-project.sh 的退出码，写脚本时值得记住：0 成功，1 用法错误（slug 不合法或文件不存在），2 项目目录已存在且没给 --force，3 找不到 safety-scan.sh（你的安装坏了 —— 到技能仓库里跑 bash setup.sh）。

6.1.1 init 写下的项目 CLAUDE.md

上面的第 5 步很容易被忽略，但要紧得很。scholar-init 写的是一份精简版项目记忆 profile —— 五个小节、约 50 行：客观性 Mandate、数据安全栈与 LOCAL_MODE 范围、引用规则、工作流规则。之后在该目录里开的每一次 Claude Code 会话都会自动读它。

如果你之后跑 /scholar-full-paper，编排器会把这个文件升级成完整的 13 节、约 230 行的 profile。升级是单向的：在已升级的项目上重跑 /scholar-init 会打印 already at v2-full ... lean request ignored，什么都不改。这是故意的 —— 一次精简的 re-init 绝不能静默地剥掉编排器赖以运转的关卡约定。

你可能看到的幂等性提示：created <path> (v2-lean)、appended auto-rules block to <path>、migrated <path> from v1 to v2-lean、already at v2-lean, no-op。

6.1.2 文本语料 —— --corpus，以及目录名为什么是承重的

语言学和 text-as-data 项目通常把语料放在 data/ 之外，而在此之前，这也意味着它落在守卫之外。现在不会了：corpus/ 和 corpora/ 是被守卫的路径段，所以它们底下的一切都按数据处理，不看扩展名 —— 包括没有扩展名的文件，也包括任何扩展名规则都抓不住的语言学格式（.eaf、.TextGrid、.trs、.cha）。

请通过技能 ingest 语料，而不是手工拷进去。ingest 才能让这些文件在 safety-status.json 里拿到一条已审定的条目；你手工拷进去的语料，每次读都要重新现场扫描一遍。

> /scholar-init init hanyu-metalinguistic-corpus \
                --corpus ~/data/hanyu/videos \
                --corpus ~/data/hanyu/comments

语料不是一种东西，里面装的是什么，政策就该不同：

之所以成立，是因为分类器匹配的是路径段：定性研究的那些段（transcripts/、interviews/、field-notes/、participants/、subjects/、respondents/）嵌套在 corpus/ 里时，仍然保持它们严格的待遇：

corpus/news/article.txt        受守卫，OVERRIDE 允许
corpus/transcripts/i01.txt     受守卫，OVERRIDE 拒绝
corpus/recordings/s1.wav       受守卫，OVERRIDE 拒绝（扩展名规则）

名字是精确的路径段匹配。 mycorpus/、corpus-2024/、texts/、speeches/、tweets/ 都不受守卫。目录就叫 corpus/ 或 corpora/，或者把材料留在 data/raw/ 下。这条规则看着像抠字眼，直到某天你发现一个叫 transcripts-2024/ 的目录，离受保护只差一次重命名。

6.2 用 scholar-init review 解决 NEEDS_REVIEW

在每个文件都被解决之前，你不能推进到头脑风暴或分析。守卫会把读操作挡下来。

> /scholar-init review

Claude 逐条走完每个 NEEDS_REVIEW 项 —— 重跑扫描器拿实时细节，并且绝不为了「帮你决定」而去读文件本身。

File: cfps2020person_202306.dta
Reasons flagged:
  - Contains community-level codes (ck01, ck02) below-county granularity
  - Contains COVID-related items that may be sensitive
Options:
  [c] CLEARED          - Claude 可以直接读
  [l] LOCAL_MODE       - Claude 可以调用 R/Python 加载器算汇总，
                          但原始行永不进入上下文
  [a] ANONYMIZED       - 先换成派生 / 聚合文件再读
  [o] OVERRIDE         - Claude 可以直接读；你要留一条书面理由
  [h] HALTED           - 本项目内该文件禁读
Choice [c/l/a/o/h]:

选项集不是每个文件都一样。 技能会把每个文件判为结构化或质性 —— 按扩展名（.wav .mp3 .flac .m4a .mp4 .mov .eaf .textgrid .cha ……），或按路径（住在 transcripts/、interviews/、field-notes/、participants/、respondents/、materials/ 下面的 .txt/.docx/.md）：

质性文件拒绝 OVERRIDE 这一条被强制执行了两次 —— 一次在这个菜单里，一次在 PreToolUse 守卫内部，所以手改 sidecar 也绕不过去。

选 OVERRIDE 需要你手打至少 20 个字符的理由。光写 “n/a”、”ok”、”false positive” 会被拒；提示会一直卡住，直到你写点真东西或者取消。理由会落到 logs/init-report.md 的 Decision history 段，连同原状态、新状态和决定人。

选 ANONYMIZE 会跑 python3 scripts/gates/anonymize-presidio.py anonymize <file>。三件事要知道：

• 输出去 output/qual/anonymized/ANON_<basename> —— 绝不放在原文件旁边 —— 并附一份 pseudonym-key-DO-NOT-SHARE.csv。
• 如果 Presidio 没找到 PII，它会退出 0 但不写文件。原文件仍是 NEEDS_REVIEW；不会有任何东西被自动放行。
• ANON_ 文件会被重新扫描。只有当它回来是 GREEN，原文件才变成 HALTED、匿名副本才变成 ANONYMIZED。还是 YELLOW 或 RED 的话，你就回到循环里。
• Presidio 对扫描是可选的（有正则回退），但对匿名化是必需的。没装 presidio-analyzer、presidio-anonymizer、spacy + en_core_web_lg，这个选项会以 ImportError 死掉，你唯一有效的选择只剩 LOCAL_MODE 或 HALT。

CFPS 的话，我们对任何波次的个人层文件通常选 LOCAL_MODE：脚本可以加载数据、产出汇总计数、回归表和图，但原始行的取值永远到不了 Claude 的上下文窗口。这是一条真实的隐私边界，不是口号 —— §6.5 会一字一句写清 LOCAL_MODE 到底允许什么。

改完要重启。 Claude Code 在会话启动时就把钩子配置拍了快照。做完一轮改动状态的 review 之后，先重启 Claude Code，再指望守卫认新值。在 Codex 下，项目必须先被 trusted，钩子才会激活；在那之前，AGENTS.md 会指示智能体自行对照 sidecar 自我约束。

6.3 检查 safety-status.json

$ jq . .claude/safety-status.json | head -30

{
  "_safety_level": "standard",
  "/Users/you/digital-divide-china-cfps/data/raw/cfps2010adult_201906.dta": "LOCAL_MODE",
  "/Users/you/digital-divide-china-cfps/data/raw/cfps2018crossyearid_202104.dta": "CLEARED"
}

sidecar 是一个扁平映射 —— 绝对文件路径 → 状态字符串 —— 外加唯一的元键 _safety_level。完整的状态词表由 scripts/gates/sidecar-schema.sh 校验：

有两种 schema 违规会让守卫 fail-closed，所以值得避开：值是对象的条目（值必须是裸字符串），以及相对路径的键。查找没有相对路径回退，也没有 basename 回退。 手写的 {"foo.csv": "OVERRIDE"} 会被静默忽略；把项目目录挪个地方，文件里每一条都会失效。

后面每一个技能在动数据之前都会读这份文件。状态是 LOCAL_MODE 时，分析脚本必须强制只做汇总式加载 —— 而 scholar-analyze 会拒绝打印原始行。

6.4 守卫 —— 真正把这件事执行下去的东西

分类只有跟执行它的东西一样可靠。那个东西是 scripts/gates/pretooluse-data-guard.sh，在 ~/.claude/settings.json 里注册为 Claude Code 的 PreToolUse 钩子（对 Codex 宿主则镜像进 <proj>/.codex/config.toml）。它拦截 Read、NotebookRead、NotebookEdit、Grep、Glob、Bash、Edit、Write、MultiEdit。退出 0 放行；退出 2 阻断，并把拒绝理由交回给 Claude。

逐个通道看它做什么：

• Read 通道。 先规范化路径（解开软链），拒绝任何解析到系统目录（/etc、/dev、/proc、/sys、/System、/var/db、/var/log）的东西，然后查 sidecar：CLEARED/ANONYMIZED/OVERRIDE → 放行；LOCAL_MODE/HALTED → 阻断，并提示改用 Bash 加载器；NEEDS_REVIEW* → 阻断，并叫你去跑 /scholar-init review。
• Bash 通道。 是一道协作式减速带，不是一堵墙。当目标是敏感路径时，它拦下那些明显的倾倒命令 —— cat、head、tail、less、od、xxd、strings、base64、sqlite3、jq、sed、awk、perl，以及不带 -c/-l/-q 的 grep。遇到模棱两可的情况它 fail-open，因为把 shell 搞瘫比它能挡住的那点边际泄漏更糟。
• Bash 通道怎么判断「目标」是谁。 两条规则，都是 2026 年 7 月加的 —— 此前那个只看路径形状的分类器在两个方向上都出过错。（a）一个 token 只有在解析到某个真实存在的东西时才会被分类，文件或目录都算。这一下干掉了一整类误报：交给 grep 的正则（grep -nE "data/raw|materials/" script.sh）不再被当成敏感目标，而此前这类误拦甚至挡住过那条用来检查该目录是否存在的命令本身。不去分类一个不存在的路径不会开口子，因为这是一道读的关卡，倾倒命令指向虚空时什么也倒不出来。glob 会被改写成它的字面目录前缀 —— glob 只能够到它下面的文件。（b）分类之前先展开变量。 含 $ 的 token 过去被当成无法解析而跳过，于是 SP=/abs/proj; grep x "$SP/corpus/transcripts/i01.txt" 直接绕过了关卡。现在有一遍分词会把同一条命令里赋的 $VAR 与 ${VAR} 解析出来，外加一小份环境变量白名单。这个范围恰好是对的：Claude Code 每次 Bash 调用都起一个全新的 shell，所以一个既没在命令内赋值、也没有 export 的变量会展开成空，根本指不到任何文件。
• Grep/Glob 通道。 阻断对原始数据路径的搜索或枚举，以及任何带数据扩展名的直接目标。
• 哪些路径算数据。 匹配的是路径段，不是扩展名：data/raw/、data/interim/、data/processed/，以及自 2026 年 7 月起的 corpus/ 与 corpora/（§6.1.2），再加上定性研究的那几段 —— transcripts/、interviews/、field-notes/、participants/、subjects/、respondents/ —— 后者还额外拒绝 OVERRIDE。
• Edit/Write/MultiEdit。 只守一样东西：对 .claude/safety-status.json 的写入。除非 logs/init-report.md 里存在 /scholar-init review 的溯源记录，否则它拒绝把 RED 或 HALTED 路径提升为 CLEARED/OVERRIDE。其余一律 fail-open。
• 图像。 像素没法 grep，所以图像按路径分类：在 data/raw/ 里 → 阻断；在 output/figures/ 里 → 放行。

失败行为是故意不对称的：jq 缺失时，read 通道 fail-closed（阻断，并给一条装 jq 的提示），而 Bash/Edit/Write 通道 fail-open。脚本异常终止时，只要目标此前已被判定为数据风险，EXIT trap 就会把它转成一次阻断。

那个会静默废掉一切的坑。 如果钩子的 command 路径里含空格 —— 而你要是装在 ~/Library/CloudStorage/GoogleDrive-…/My Drive/… 下面，它一定含 —— Claude Code 和 Codex 都执行不了它，而且没有任何可见报错。守卫就此全局失效。注册时用引号包起来：

{ "command": "bash '/Users/you/My Drive/open-scholar-skills/scripts/gates/pretooluse-data-guard.sh'" }

用一次故意的探针来验证：让 Claude 去 Read 一个你确知是 HALTED 的文件。如果读成功了，你的钩子根本没接上。

6.5 LOCAL_MODE 契约

LOCAL_MODE 是处理真实调查数据时的主力状态，所以它的规则要学会。分析以每次分析一个 Rscript -e 或 python3 -c heredoc 的方式运行，而且只有聚合结果可以回来：

LOCAL_MODE 脚本写出的中间文件必须存到 data/interim/ 或 data/processed/，并会被自动登记为 sidecar 里的 LOCAL_MODE —— 派生数据继承约束，而不是逃出约束。

6.6 scholar-safety —— 六个模式

argument-hint: "[scan|gate|protocol|status|level] [file path / operation
                description / level name] [optional: data type, project name,
                journal target]"

> /scholar-safety scan data/raw/cfps2020person_202306.dta
> /scholar-safety gate "about to read data/interviews.txt for coding"
> /scholar-safety protocol digital-divide-china-cfps journal="Social Forces"
> /scholar-safety status
> /scholar-safety level strict

技能自己写明的关键操作规则：在用户明确选择 PROCEED 或 OVERRIDE 之前，绝不 Read 被标记的文件 —— 并且注意，LOCAL MODE 是 Read 权限的反面，永远不该触发一次 Read。

6.6.1 扫描器到底在找什么

扫描会统计这些模式的命中数：SSN；姓名；邮箱；电话；街道地址；邮编；IP 地址；健康与 HIPAA 标记；心理健康条目；法律与移民条目；财务字段；受限数据集标记（NHANES、PSID、NLSY、IPUMS、Census RDC、DUA、”confidential”）；国际受限数据集标记（UK Biobank、ALSPAC、NHS Digital、SOEP、EU-SILC、CFPS、CHARLS、CGSS、CLHLS、IHDS、JGSS、Understanding Society、KLoSA，以及区分大小写匹配的 SHARE / HILDA / Add Health）；IRB 与参与者标记；以及细粒度地理信息。

分类矩阵，压缩到你实际会撞上的那几行：

有两条 fail-closed 规则让这套东西值得信。目标文件缺失、不可读或是目录时，返回 SCAN-ERROR 并判 🔴 HIGH —— 绝不是 LOW。而二进制文件的下限是 🟡：对一个 .dta、.sav、.rds、.xlsx、.parquet 或 .sqlite 文件跑一遍干净的正则，不是安全的证据，因为扫描器读不进那个容器。这正是为什么 CFPS 的 .dta 文件会落进 review，而不是一路放行。

6.6.2 三个安全级别 —— 以及每一级到底保证了什么

> /scholar-safety level lockdown

技能会先核实脱敏器确实注册了，才敢声称 strict 保护 —— 而不是报一个它兑现不了的级别。

lockdown 有一处需要提前规划的锋利边缘：对 data/ 的 denyRead 会阻断该目录的所有读取 —— 包括那个被认可的 LOCAL_MODE Rscript/python3 加载器。要么先跑完分析再上锁，要么用 --allow-escalation 生成配置，好让经人工批准的非沙箱命令仍然能跑。

lockdown 底下究竟是什么。 它写的就是 Claude Code 自带 Bash 沙箱的配置（§5A）—— 和你用 /sandbox 手动驱动的是同一套 Seatbelt/bubblewrap 机器。由此有两个推论。其一，--allow-escalation 是套件对「保持 allowUnsandboxedCommands 开启」的叫法；不加它，就是 /sandbox Overrides 标签页所说的 Strict sandbox mode。其二，沙箱默认不做的事在这里同样成立：读权限默认覆盖整台机器，所以真正干活的是那条对 data/ 的 denyRead；而如果沙箱根本起不来，除非设了 failIfUnavailable，Claude Code 会警告一声然后不带沙箱地跑。如果你的 DUA 要求隔离，就去验证这个级别，而不是假定它 —— 先 /scholar-safety status，再拿一个你确知是 HALTED 的文件做一次故意的探针测试。

lockdown 以下的一切在原理上都可绕过 —— 换个解释器（ruby、node）、换种编码（base64、gzip、十六进制）、用 shell 变量拼出路径，或者把文件拷到一个无害路径再读。套件把这一点公开写出来，而不是假装不存在。把你的工作流设计成诚实的路径同时也是最省事的路径，并把 lockdown 留给 DUA 真正要求隔离的数据。

6.7 你自己就能跑的脚本

每一道关卡都是一个普通的 shell 或 Python 脚本。用它们不需要 Claude 参与，而亲手跑一遍是建立对这套系统信任的最快方式：

6.8 检查

1. logs/init-report.md —— ingest 文件表、扫描级别计数，以及只追加的 Decision history。
2. .claude/safety-status.json —— 每个键都是绝对路径，每个值都是七个状态字符串之一。
3. README.md —— 自动生成，而且真的值得读一遍：里面有决策流程图和每个状态的效果表。
4. CLAUDE.md —— 确认自动托管块在，且写着 v2-lean（编排器跑过之后是 v2-full）。

停下来检查。 指着一个标了 LOCAL_MODE 的文件，出声说出：(a) 它为什么被标；(b) 脚本仍然可以从它算出什么；(c) 你要是让 Claude head 一下它会发生什么。三条答不全，就先别 brainstorm。

7. scholar-brainstorm —— 拓宽问题菜单

目标： 产出一份排序过的候选研究问题清单，每个带变量、方法草图、风险。不要让它替你决定博士论文；让它拓宽菜单。

7.0 三种模式 —— 由输入自动判定

scholar-brainstorm 有三种模式，会根据你给的输入自动选：

自动判定看文件后缀，对 PDF 还会看内容——”Abstract / Introduction / Methods / References“判定为 PAPER；”Variable / Codebook / Questionnaire”判定为 MATERIALS。

三种模式共享下游流水线：文献扫描 → Top-10 短列表 → 五角色评估面板（五个 Task 调度的评估 prompt —— 理论家、方法学家、领域专家、编辑、devil’s advocate —— scholar-brainstorm 内部角色，不是 .claude/agents/ 中的具名 agent）→ 精修 Top-10 → 研究计划概览 → 执行摘要。差异只在 Step 0–4。

CFPS 数字鸿沟例子用的是 MATERIALS 模式。下面先讲 MATERIALS，再分别展示同一个项目在 DATA 与 PAPER 模式下会是什么样。

7.1 MATERIALS 模式 —— 从代码本起步

适用：有代码本/问卷但还没拿到原始数据——可能是申请待批，或者你刻意先要一份理论驱动菜单再碰数据。

7.1.1 运行

> /scholar-brainstorm materials top 5 RQs on digital divide in China,
                       target Social Forces, descriptive/decomposition

它检测到 MATERIALS 模式（仅有代码本，没有打开 data/raw/），基于问卷与变量字典推理并查证外部来源。一般 4–7 分钟，本次成本约 $1.20。

7.1.2 真实输出（节选）

来自 output/.../scholar-brainstorm-...top5-summary-2026-05-05.md：

# 研究问题头脑风暴 — 执行摘要
## 中国数字鸿沟（CFPS 材料）
*由 /scholar-brainstorm 于 2026-05-05 生成*
*运行模式：MATERIALS*

## Top 5 RQs

### #1：接入趋同，使用分化
**RQ：** 2010–2020 年中国，户口、教育、世代在互联网接入上的差距是否
缩小，而生产性使用、使用强度、使用广度的差距持续或扩大？
**变量：** U201, U202, U250M, U701-U705, hukou, education, cohort,
gender, income, household composition.
**为什么最强：** 最适合做旗舰论文；利用 CFPS 面板结构区分第一层接入
与第二层生产性使用。
**方法草图：** 面板模型，wave/省控制，可行处加入 individual FE，对农
业户口和世代差距做 Oaxaca 分解。

### #2：疫情期间的远程工作鸿沟  […]
### #3：在线学习产出鸿沟          […]
### #4：老年群体数字健康与社会连接鸿沟  […]
### #5：信息信任、隐私关切与平台依赖    […]

## 推荐
以 RQ1 作为主论文。[...]

7.1.3 写入磁盘的文件（MATERIALS 模式）

output/<slug>/
├── scholar-brainstorm-<slug>-<date>.md         ← 完整报告（15–20 个候选）
├── scholar-brainstorm-<slug>-summary-<date>.md ← 执行摘要（Top 5 + 推荐）
└── logs/process-log-scholar-brainstorm-<date>.md

外加每份的 .docx、.tex 与 .pdf（pandoc 渲染）。

7.1.4 检查

打开完整文件，查四件事：

1. 变量是否真实存在 —— U201、U250M 在代码本里能找到吗？
2. 外部引用是否可解析 —— 点开链接，看能否打开。
3. 风险是否具体 —— RQ5 正确指出“部分 2020 年题项是受限数据”。
4. 是否有过宽的问题 —— RQ4 “互联网使用是否改善老年人健康”过宽，输出已诚实标出。

自检： 选定一个 RQ 往下走。本手册接下来选 RQ1：可行、与理论相关、可测量。

7.2 DATA 模式 —— 从数据本身起步

适用：原始数据已经在磁盘上、且 scholar-init 已经分类。DATA 模式比 MATERIALS 模式多两件事：

1. 安全闸门 —— 在读任何文件前，先查 .claude/safety-status.json（scholar-init 写下的 sidecar）。任意输入文件状态为 NEEDS_REVIEW:* 或 HALTED，技能直接拒绝运行，要求你跑 /scholar-init review。如果 sidecar 不存在，则退化为本地 grep 扫描，只返回 PII / HIPAA / 受限数据标记的计数，不返回匹配值本身。
2. 经验信号检验 —— 对 15–20 个候选 RQ，技能写一个 R 脚本（scripts/brainstorm-signal-tests.R），先送 3 个智能体做执行前代码审查，然后才跑。每个候选拿到一个真实双变量效应量（连续结果用 Cohen’s d，方差分析用 η²，列联表用 Cramér’s V，相关用 Pearson’s r）和一个信号等级：STRONG、MODERATE、WEAK、NULL、MECHANISM PLAUSIBLE、MODERATION DETECTED 或 UNTESTABLE。

Top-10 评分按 6 个维度加权——新颖 20%、数据可得 15%、理论 20%、识别 15%、发表潜力 10%、经验信号 20%——而不是 MATERIALS / PAPER 的 5 维度。

7.2.1 运行（如果 CFPS 例子走 DATA 模式会是这样）

> /scholar-brainstorm data/raw/cfps_panel_long.rds
                     top 5 RQs on digital divide in China,
                     target Social Forces

如果 scholar-init 已把这个文件标为 LOCAL_MODE，技能会继承这个决定（“scholar-init 握手”），所有经验检验都通过 Rscript brainstorm-signal-tests.R 跑——Claude 自己从不Read 数据。

7.2.2 你会看到 —— 信号表

DATA 模式典型的信号表长这样：

EMPIRICAL SIGNAL TABLE  (sample sizes from cfps_panel_long.rds)

| RQ | x_var       | y_var       | test   | n     | effect_size      | p       | signal   |
|----|-------------|-------------|--------|-------|------------------|---------|----------|
| 1  | hukou_rural | y2_hours    | t-test | 119k  | d = -0.42 (med.) | 1.4e-5  | STRONG   |
| 1  | cohort      | y1_access   | χ²     | 148k  | V = 0.31 (med.)  | <1e-60  | STRONG   |
| 2  | mobile_only | covid5      | t-test | 34k   | d = +0.18        | 4.2e-3  | MODERATE |
| 4  | u703_social | sf12_mh     | r      | 41k   | r = +0.11        | 7.8e-4  | WEAK     |
| 5  | u11_wechat  | u13_trust   | r      | 26k   | r = +0.08        | 0.04    | WEAK     |

技能在表旁打印的提醒（原话）：

• 信号是双变量的——这里没处理混杂。
• 本阶段不做多重检验校正；任何单一 p 都不能当作确证检验。
• NULL ≠ “没意思”；可能是被其它变量中介。

7.2.3 执行前代码审查

任何 Rscript 真正跑起来之前，技能并行派出三个评审智能体审查信号检验脚本：

• review-code-correctness —— 变量引用、NA 处理、off-by-one
• review-code-statistics —— 检验类型与变量类型是否匹配，是否正确使用 effectsize 包
• review-code-data-handling —— 样本限制、缺失值代码、与代码本对齐

输出汇总到 scripts/brainstorm-signal-tests-review.md，带严重等级。执行闸门有四种结局：

• PROCEED —— 无 CRIT/MAJOR；运行脚本。
• FIX-AND-RERUN —— 修复被指出的问题，重新审查，再跑。
• OVERRIDE —— 用户输入 ≥20 字符的理由；进 process log。
• HALT —— 停止技能；没有候选值得照原样跑。

也就是说，DATA 模式在数据被碰之前就留下了完整审计轨迹——这正是工作坊要教的纪律。

7.2.4 写入磁盘的文件（DATA 模式）

除了 MATERIALS 模式的两份文件，DATA 模式还会写：

output/<slug>/scripts/
├── brainstorm-signal-tests.R                  ← 真实 R 脚本（可审计）
├── brainstorm-signal-tests.log                ← 运行 stdout
├── brainstorm-signal-tests-review.md          ← 三智能体审查汇总
├── brainstorm-signal-tests-review-correctness.md
├── brainstorm-signal-tests-review-statistics.md
└── brainstorm-signal-tests-review-data-handling.md

这些文件天然适合 replication ——scholar-replication 后面会自动捡起来。

7.2.5 检查（DATA 模式额外两条）

在 MATERIALS 模式四条之外，再核对：

1. 信号检验脚本必须是真 R，不是伪代码。 打开 scripts/brainstorm-signal-tests.R，head -40 看看。每个测试都必须包在 tryCatch() 里——一个候选失败不能拖垮整轮。
2. 效应量必须用正经包。 脚本必须用 effectsize::cohens_d()、effectsize::eta_squared()、effectsize::cramers_v()，不能手写公式。

自检： 看上面那张信号表。RQ5 的 WEAK 信号意味着“假设死了”吗？不是——它可能只是说“双变量不够，需要协变量”。信号是 Top-10 评分的一个输入，不是判决。

7.3 PAPER 模式 —— 从一篇论文起步

适用：你刚读完一篇论文，想要一份结构化的后续选题菜单——方法扩展、人群迁移、机制深化、局限解决、计算升级。

PAPER 模式三种触发方式：

# (a) 磁盘上的 PDF
> /scholar-brainstorm ~/papers/li-ouyang-hu-2025-digital-divide-aging.pdf

# (b) DOI 字符串
> /scholar-brainstorm 10.1038/s41746-025-02076-1

# (c) 粘贴摘要（直接在对话里贴 "Title: ... Abstract: ..." 块）
> /scholar-brainstorm
> Title: A ten-year analysis of digital divides among older Chinese adults
> Abstract: Using six waves of CFPS we document persistent age-related gaps in [...]

7.3.1 技能在做什么

1. 抽取种子论文要素 —— 标题、摘要、核心发现、所用方法、作者承认的局限、作者建议的未来方向、理论框架、人群/语境、数据源。（DOI 走 CrossRef API；PDF 走 pdftotext；粘贴摘要直接解析。）
2. （可选）SciThinker 选题 —— 环境里设了 HF_TOKEN 时，技能会调用 HuggingFace 上的 OpenMOSS-Team/SciThinker-30B，用结构化提示要求一篇 follow-up 论文的 title + abstract。HF_TOKEN 缺失或调用失败时，这步记为 SKIPPED，继续走 Claude-only 选题。
3. Claude 扩展 —— 基于种子要素（+ SciThinker 提案，如有）生成 15–20 个候选 follow-up RQ，覆盖 8 个维度：

| 维度         | 策略                                          |
|------------|---------------------------------------------|
| 方法扩展      | 用更强 / 不同的方法回答同一个问题                  |
| 人群迁移      | 同一问题，不同人群或语境                       |
| 机制深化      | 直接检验作者假设的机制                         |
| 局限解决      | 攻克作者承认的某个局限                         |
| 范围扩展      | 推到一个相邻现象                              |
| 反向证伪      | 设计一个能证伪原发现的研究                     |
| 计算升级      | 用 NLP/ML 揭示原方法看不到的模式               |
| SciThinker 提案 | 把 AI 生成的想法在社会科学理论里 ground       |

1. 共享流水线 —— 每个候选走文献扫描 → Top-10 短列表 → 五智能体评估组 → 精修 Top-10 → 研究计划概览，与 MATERIALS / DATA 完全一致。

7.3.2 拿 CFPS 数字鸿沟当种子的话会看到什么

如果对 Li, Ouyang, & Hu (2025) 跑 PAPER 模式，可期的 follow-up RQ 例如：

#1（机制深化）—— 家户内数字传递（同住青年人）能否削弱 Li 等人指出
   的年龄数字鸿沟？CFPS family-conf + intra-household FE。

#2（人群迁移）—— 同样的"年龄 × 数字排斥"模式在农村流动人口里成立吗？
   户口与年龄叠加。CFPS 流动人口子样本。

#3（局限解决）—— 种子论文承认无法分离世代与年龄。对同一面板用 HAPC
   + Deaton-Paxson bounds。

#4（方法扩展）—— 种子论文用描述趋势。对城乡 Y2 差距跑 Oaxaca-Blinder
   分解，把禀赋部分与系数部分分开。

#5（计算升级）—— 对 CFPS 互联网开放题项跑 STM 主题模型，揭示封闭题
   看不到的使用类型异质性。

（数字鸿沟焦点论文实际上正是这么定的位——把 Li 等人当种子，识别第二层 / 制度差距是空白车道。）

7.3.3 写入磁盘的文件（PAPER 模式）

output/<slug>/
├── scholar-brainstorm-<slug>-<date>.md          ← 完整报告
├── scholar-brainstorm-<slug>-summary-<date>.md  ← 执行摘要
└── logs/
    ├── process-log-scholar-brainstorm-<date>.md
    └── scithinker-response-<date>.txt           ← 调过 SciThinker 的原始输出

7.3.4 检查（PAPER 模式）

四条 MATERIALS 通用检查之外，再加：

1. 与种子的连接。 每个候选必须明确写出它扩展的是种子的哪个要素（哪条发现？哪条局限？哪条建议方向？）。如果某个候选没法 cite 种子里的具体锚点，那就是幻觉，不是扩展。
2. SciThinker 落地。 如果调过 SciThinker，它的提案会被标出来。把它当作种子想法，不是成品 RQ——像 Claude 处理它一样：精修、理论化、再打分。

自检： PAPER 模式最容易被滥用——很容易拿了榜首 follow-up 就开始写。别这么做。把选中的候选送回 scholar-idea（§8）和 scholar-design（§9）再决定——PAPER 模式是菜单生成器，不是设计。

8. scholar-idea —— 把困惑磨锐

目标： 把领域变成具体困惑：机制、范围条件、假设、致命缺陷筛查。

8.1 运行

> /scholar-idea broad puzzle: "China's digital divide — access converging
  while use intensity persists by hukou, cohort, and gender"
  data: CFPS 2010-2020 long panel
  target: Social Forces

8.2 真实输出节选（来自 idea/scholar-idea-...md）

## Step 1 — 困惑

中国 2024 年互联网用户已达 10.7 亿（CNNIC），却仍是分层数字不平等的
教科书案例。第一层接入差距自 2015 年起迅速缩小，但第二层（技能、使用
自主性）和第三层（使用回报）差距似乎扩大，尤其沿 hukou、世代、性别、
教育线分布。

## Step 2 — 候选角度

| # | 框架            | 机制                    | 替代解释          |
|---|----------------|-------------------------|-------------------|
| A | 户口为持久轴   | 制度排序                | 纯 SES 吸收户口  |
| B | 世代即原因     | 出生世代社会化          | 时期效应          |
| C | 家户作为技能单位| 家户内溢出              | 选择              |
| D | 性别×年龄×户口 | 三重惩罚                | 仅可加性          |
| E | 使用回报       | 资本转换 (Bourdieu)     | 回报相同          |

A、B、D 在 CFPS 中可行；E 降级到讨论。

## Step 5 — 假设

H1（户口持久）。控制 X3、X4、地区基础设施后，农业户口降低 Y1 接入概率
和 Y2 周使用小时。Y1 上的户口效应跨波次缩小（接入趋同），Y2 上的户口
效应不缩小（技能-使用分化）。

H2（世代分层）。1985 后出生世代在 Y1 与 Y2 上系统性更高，控制时期与
年龄。在世代内，Y2 的年龄轨迹近乎平坦——鸿沟靠世代替代，不是个人学习。

H3（交叉三重惩罚）。三向交互（农业户口 × 女性 × 1965 年前出生）的
使用强度惩罚超过三个边际效应之和。

H4（家户溢出，次要）。与至少一名"数字原住民"（≥1990 出生）同住，与
年长成员更高的 Y1、Y2 相关。

8.3 关键观察

• 假设是预先指明的：H1 既有方向，又有“Y1 缩小但 Y2 不缩小”的微妙性，意味着分析可以证伪制度账户，而不只是确证。
• 禁止语言已写明：备忘里记下禁止的因果语言与描述性设计（“不对户口做因果解释；描述性设计”）。
• 一个假设是高风险的：H3 是交叉性主张。现在就要决定：如果数据显示三重惩罚只是可加，你愿不愿意把这个 null 发出去？（剧透：在我们的运行里 H3 真的是 null，我们把它留在论文里。）

自检： 不看文档，能不能用一句话说出每个假设的方向预测？说不出就再磨。

8A. scholar-lit-review-hypothesis —— 一次性整合文献综述、理论与假设

目标： 在一个工作流里完成：摸清现有文献 → 找到未解决的缺口 → 选定能填这个缺口的理论框架 → 指明机制 → 推导可检验假设——直接产出可发表的“文献综述 + 理论”章节。

这个技能取代分别跑 /scholar-lit-review 和 /scholar-hypothesis。在 /scholar-idea（§8）之后用最合适。CFPS 数字鸿沟那篇论文里 1,400 字的“理论框架 + 假设”段，就是它写的。

8A.1 内部五步逻辑

技能强制单一五步论证——每一步喂下一步，文字不能漂离这条链：

8A.2 运行

> /scholar-lit-review-hypothesis
   RQ: In CFPS 2010-2020, did hukou/cohort gaps in internet access narrow
       while gaps in weekly use hours persisted?
   target: Social Forces
   anchor theories: layered digital divide; hukou as institutional sorting;
                    cumulative advantage; cohort-as-cause

技能跑分层文献检索：

• Tier 0 —— 知识图谱 —— 跨项目 scholar-knowledge 图谱，配置后优先查询
• Tier 1 —— 本地文献库（Zotero / Mendeley / BibTeX / EndNote）—— 命中即已验证
• Tier 2 —— 外部 API —— CrossRef、Semantic Scholar、OpenAlex、Google Scholar
• Tier 3 —— WebSearch —— 仅用于剩余空缺

然后跑反抄袭 + 主张验证小组：三个 Task 调度的评估 prompt 并行（originality-auditor、claim-verifier、attribution-analyst —— skill 内部角色，并非 .claude/agents/ 中的具名 agent），逐句核对 paraphrase 是否过界、效应方向是否与原文一致、引用是否对得上本地库。一致性矩阵附在输出里。

8A.3 真实输出（CFPS 运行节选）

下面这段“假设”块技能直接产出，原封不动进了最终手稿：

## Hypotheses

H1 (Hukou persistence and access-intensity divergence). Net of education,
household income, occupation, and province-level infrastructure, agricultural-
hukou status reduces both the probability of internet access and the weekly
hours of internet use among users. The hukou coefficient on internet access
narrows monotonically across the 2010-2020 panel waves, consistent with
access convergence. The hukou coefficient on weekly internet hours does not
narrow, and may widen, consistent with the institutional-sorting mechanism
producing a durable second-level divide.

H2 (Cohort layering, not within-person learning). Birth cohorts born after
1985 exhibit systematically higher internet access, weekly internet hours,
and use breadth than earlier cohorts, net of period and chronological age.
Within cohort, the within-person age trajectory of weekly internet hours is
approximately flat. Aggregate population-level growth in weekly internet
hours across waves is therefore primarily driven by cohort replacement.

H3 (Intersectional triple penalty). The use-intensity penalty associated
with the joint condition rural-hukou × female × born ≤ 1965 exceeds the
sum of the three additive marginal effects.

H4 (Household spillover, secondary). Co-residence with at least one
digital-native household member (born 1990 or later) is associated with
higher internet access and weekly internet hours for older co-residents,
with the spillover larger for women and rural residents.

注意因果语言校准 —— H1 用 “is associated with” / “reduces the probability of“，不是 ”causes”。这是技能的明确规则：观测设计、未做 IV / RD 识别的假设，必须用关联语言。

8A.4 写入磁盘的文件

output/<slug>/
├── drafts/scholar-lrh-<slug>-<date>.md             ← 文献综述 + 理论 + 假设（+ .docx/.tex/.pdf）
├── drafts/scholar-lrh-<slug>-<date>.bib            ← 由 /scholar-citation MODE 6b 生成（非人工撰写）
├── logs/
│   ├── process-log-scholar-lit-review-hypothesis-<date>.md
│   └── scholar-search-log-<slug>-<date>.md         ← 每次查询 + 命中数
└── reports/
    ├── source-integrity-panel-<date>.md            ← 三 agent 验证
    ├── source-integrity-originality-<date>.md
    ├── source-integrity-claim-<date>.md
    └── source-integrity-attribution-<date>.md

8A.5 检查

1. 每句 paraphrase 都必须能追到 refs.bib 里的已验证条目。 打开 source-integrity 面板看哪些句子被标。
2. 每条假设都必须从命名机制推出。 假设上方没有机制段就是断链。
3. 因果语言审计。 在草稿里搜 “causes”、”leads to”、”effect of”。观测设计、未做识别的，每一处命中都是修订候选。

8A.6 证据账本 —— 你真正读到的，和你写下的，并排放（v5.28）

§8A.1 那张层级表说的是一条引用可以从哪来。它没说你在写下那句话之前到底读了什么。从 v5.28 起，那是一个单独的文件，也正是本节“每句 paraphrase 都能追到源头”这个承诺背后的产物。

每当一段原文成为某条已定稿主张的依据，就往 evidence/claim-anchors.ndjson 追加一条记录：逐字引文（≤ 60 词）、一个定位符、取到它的工具，以及对这份证据实际有多硬的一个诚实标签。

真正干活的是两条规则：

1. 检索不等于采集。 一次命中 25 条的搜索产生零个锚。采集发生在一条主张定稿的时候 —— 一格 landscape map、一个效应量、一条假设前提、一句已写进草稿的话。搜过，不算读过。
2. 采集要对层级诚实。 用你手头已有的最好证据去锚定。摘要片段是合法的锚（T3_abstract）。当没有任何可引的东西时，这条记录写 evidence_quote: null —— 这让“只凭元数据就引了”变得可见，而不是静悄悄。

账本里的 tier 标签要仔细读 —— 它不是上面那套 Tier 0–2。 账本的 access_tier 回答的是我读到的证据有多硬：T1_fulltext（一份 PDF，或一次 rag_search 命中）> T2_oa_fulltext > T3_abstract > T4_none。引用层级回答的是这条引用可以从哪来。同一个词，两个轴。一篇文章完全可以是 Tier-1 已验证，同时锚在 T3_abstract —— 你确认了它存在，但你从头到尾只读过摘要。

往下游，这会产出一份证据档案（Evidence Dossier），把“原文说了什么”和“我们写了什么”并排放；以及一行必需的日志 Evidence anchors: N created / M reused。scholar-write 和 scholar-citation 是消费这个账本，而不是重新推一遍（§14、§16），Phase 7 还带一道 tag 关卡来查它。

引文只存在 evidence/ 下，并且默认被排除在 replication 包之外 —— 逐字的第三方文本，正是你最不想一不小心随包分发出去的东西。

自检： 在草稿里指一处引用，打开 BibTeX，找得到对应 key 吗？找不到就先跑 /scholar-citation verify（§16）再走。然后打开 evidence/claim-anchors.ndjson，数一数你已定稿的主张里有多少锚在 T3_abstract 或 T4_none。那个数字，就是你没真读过就引了的部分的诚实大小。

8B. scholar-conceptual —— 造理论“对象”，不是写理论文字

目标： 产出一篇论文真正立足的理论对象——类型学、机制链、多层次框架、范围条件、过程模型——并把它们渲染成发表级图（TikZ → PDF，Mermaid 作 fallback）。

这不是假设推导（/scholar-hypothesis 干这个），也不是识别（/scholar-causal 干这个 —— 十四种识别策略以及它自带的 DAG / 潜在结果脚手架见 §8D）。scholar-conceptual 在理论建构层面：理论由什么构成？这些部件怎么连起来？

8B.1 两种模式

argument-hint: "[theorize|diagram] [topic], e.g., 'theorize a framework for
                digital labor precarity' or 'diagram mechanism model for
                segregation and health'"

> /scholar-conceptual theorize a typology of immigrant civic incorporation
> /scholar-conceptual diagram multi-level model for algorithmic management
> /scholar-conceptual full framework with figure for cumulative disadvantage

THEORIZE 进一步把任务分八类——类型学构建（Lazarsfeld property-space）、过程理论化、机制说明（Coleman’s boat / Hedström DBO）、范围条件映射、多层次模型、abductive 异常 → 解释、综合框架、概念澄清。

有两件事这条技能故意不做。它不会做识别主张 —— 那些一律路由到 /scholar-causal。而且它是这一部分技能里唯一完全不派子智能体的一条：工具清单很窄，没有验证面板，所以它的输出要么你自己检查，要么事后交给 /scholar-auto-improve observe。

HARKing 披露关卡。 scholar-conceptual 携带整套技能的“理论转向协议”，在以下三个条件同时成立时触发：（a）项目有预注册假设；（b）至少一个焦点假设跑出零结果或反号；（c）Discussion 现在引入了一个原始解释清单里没有的理论概念 —— 或者用了“reinterpret as”“post-hoc explanation”“in retrospect”这类改述信号词。

一旦触发，你必须产出 design/theoretical-pivot.md，逐假设记录预注册解释及其状态、转向后的解释及其推断地位、什么变了什么没变、以及给读者的提示 —— 并把受影响的手稿章节打上 [REGISTERED] 或 [EXPLORATORY] 标签。

请特别注意这不是什么：它不是禁止事后改述，事后改述是研究里正常且常常有价值的一环。它要求的是把改述披露出来、圈定边界。零结果之后重新框定是正当的；把重新框定说得像你早就预测到了，则不正当。

8B.2 运行（数字鸿沟例子）

> /scholar-conceptual build mechanism model: access convergence,
                    persistent intensive-use stratification,
                    hukou and cohort sorting
                    target: Social Forces
                    diagram type: Coleman's boat

技能写出：

• output/<slug>/theory/mechanism-memo-<date>.md —— 1,500 字备忘，命名每个机制步骤（制度排序 → 基础设施差异暴露 → 技能形成 → 使用强度分层），明确列出对手解释，逐条箭头给出反证证据。
• output/<slug>/figures/fig-mechanism-coleman.tex —— Coleman’s-boat 图的 TikZ 源（宏观条件 → 个体情境 → 个体行为 → 宏观结果）。
• output/<slug>/figures/fig-mechanism-coleman.pdf —— 编译后的矢量 PDF，可直接放进 LaTeX。
• output/<slug>/figures/fig-mechanism-coleman.mmd / .svg —— Mermaid fallback（迭代时渲染快）。

8B.3 编译后的真图 —— 我们 CFPS 案例的 Coleman’s boat

技能产出可直接编译的 TikZ，latexmk / xelatex 把它编成独立 PDF，可直接拖进手稿。下面是这条技能在 digital-divide 项目上真实编译出来的图 —— 不是重画的示意图：

下面是技能写出的 TikZ 源（节选 —— 全新运行时完整文件在 output/<slug>/figures/fig-mechanism-coleman.tex；本手册这份产物落在 output/theory/fig-mechanism-coleman.tex，因为那次运行早于 figures/ 目录规范化）：

\begin{tikzpicture}[
  box/.style={draw=primary, rounded corners=3pt,
              minimum width=3.6cm, minimum height=1.1cm,
              align=center, font=\small, fill=white},
  macrobox/.style={box, fill=lightbg, font=\small\bfseries},
  arrow/.style={-{Stealth[length=7pt]}, primary},
  microarrow/.style={-{Stealth[length=7pt]}, accent},
  label/.style={font=\scriptsize\itshape, muted}]

% 宏观层
\node[macrobox] (M1) at (0, 3) {Hukou system\\(institutional sorting)};
\node[macrobox] (M2) at (10, 3) {Population-level\\use-intensity gap (Y2)};

% 微观层
\node[box] (m1) at (2.6, 0) {Differential digital\\infrastructure exposure};
\node[box] (m2) at (7.4, 0) {Differential\\skill conversion};

% Coleman 船的四条腿
\draw[arrow]      (M1) -- (M2) node[midway, above, label] {Observed gap (descriptive)};
\draw[microarrow] (M1.south) -- (m1.north) node[midway, left,  label] {(1) Situational};
\draw[microarrow] (m1) -- (m2) node[midway, below, label] {(2) Action-formation};
\draw[microarrow] (m2.north) -- (M2.south) node[midway, right, label] {(3) Transformational};
\end{tikzpicture}

技能同时写一个 figure caption 块（可以直接贴在手稿图下）以及一份 Rival explanations to test: 检查清单（编译图底部可见的那段）—— 这是论文稳健性章节必须回应的经验性可证伪点。

8B.4 八种可渲染的图

8B.5 检查

• 每条箭头都要有标签的机制。 打开图，无标签的箭头是装饰，不是理论。
• 每个 box 都要有反证。 备忘里要写：什么样的观察会削弱这个 box / 这条箭头。学员说不出“什么证据能证伪这条箭头”——这条就还没成熟。

自检： 把图给一个没看备忘的同事，让他从图里复述出机制故事。复述不出来，说明图过度装饰、信息不足——加标签重做。

8C. scholar-knowledge —— 跨项目记忆层

目标： 维护单一、用户作用域、跨项目的知识图谱：你 ingest 过的每篇论文、抽取过的每条发现、记下的每条方法、标过的每条论文-论文关系，都能在下一项目里复用。它就是让智能体不再每次重新发现同一片文献的那一层。

这是技能套件里最被低估却最有价值的一个。审计语料里，CFPS 数字鸿沟、CFPS 户口-婚姻、十几个其它项目都在同一个智识邻域里——Wu & Treiman 2004、Xie & Jin 2015、van Deursen & Helsper 2015、DiMaggio et al. 2004 ……。没有 scholar-knowledge 时，每个项目从零开始。有了它，ingest 是一次性投资，永远在还利息。

8C.0 SELECT 的三条路 —— 为什么用 wiki，而不只是 RAG

把对的文本送进模型窗口（也就是”SELECT”这一步），有三种截然不同的策略，而 scholar-knowledge 是第三种：

• RAG —— 把语料切块、做 embedding，查询时按向量相似度取回最近的 top-K 块。快、可扩展，但取回的是按表面相似度排序的不透明片段；源文件一改，索引就过期；而且你很难读出某个块为什么被选中。
• 智能体式搜索（agentic search） —— 没有索引；智能体在循环里 grep 并直接读活文件（Claude Code 读你的仓库就是这么干的）。永远是最新、完全可审计，但受限于少数几次搜索够得着的范围，而且每次会话都要从头再读一遍。
• 知识 wiki（”LLM-wiki”路线） —— 模型把每篇源文献读一次，抽取发现、机制与关系，写成人类可读、互相链接的 markdown wiki。要回答问题时，它读 index 页、顺着 [[链接]] 走到真正相关的那几页。这正是 /scholar-knowledge compile 和 ask 做的事。

对于一个你会反复回来查的语料，wiki 为什么可能胜过 RAG：综合是预先算好的（主题综述、contradictions.md、gaps.md），而不是每次查询都重新推导一遍；关系是可遍历的显式链接（extends、contradicts、same-dataset），不是隐含的向量邻居；它就是 markdown —— 可审计、可编辑，不需要 embedding 模型、也不需要向量库；而且它会滚雪球 —— 你把自己的产出 file 回去，于是第 5 篇论文站在第 1–4 篇的肩膀上。代价是：抽取是前期一次性投入且有损（wiki 是模型对源文献的阅读，不是源文献本身 —— 所以 raw/ 会保留原件），而且 wiki 必须保持最新（由 LLM 维护，你几乎不用手动改）。这就是 Andrej Karpathy 的”LLM wiki”想法：模型自己写、自己维护这个知识库，你把产出 file 回去，让它为将来的查询变得更好。

三者是互补，不是对手。把 wiki 当作持久记忆，把活的检索器（OpenAlex、Zotero）包成 MCP 工具来延伸触达（Lab 3 §4b），让智能体自己决定该伸手去拿哪一个。从 v5.27 起，套件把第一种也一并给了你 —— scholar-rag（§8F）在同一个文献库上建一个真正的本地向量数据库，并把它作为 MCP 工具暴露出来，于是你不必再二选一：wiki 存综合，向量索引存原文段落，两边用同一套论文身份对齐。想看完整机制 —— ingest → 图谱 → compile → 导航 —— 只用约 250 行零依赖 Python，跑一下 Day 3 的 demo：

cd demo/day3-claude-code/llm-wiki
python3 build_wiki.py     # 7 篇论文 -> 图谱 -> 34 个互链 wiki 页
python3 ask.py "why doesn't closing the access gap close the divide?"

ask.py 会打印出确切的导航路径（index.md → topics/… → concepts/… → papers/…），把它与 RAG 不透明的 top-K 之间的差别摆到明面上。

这张图谱同时也是 scholar-rag GraphRAG 的**种子**（见 §8F）。 rag_py graphrag.py seed 会在任何 LLM 抽取跑起来之前，先把这里的概念和引用边导进去 —— 这是那一步快速、不用 LLM 的 起跑优势。在一个 5.5k 篇的文献库上，光靠种子边只覆盖了约 12% 的语料，这正是 §8F.6 里 citations 与 semantic 两个阶段存在的理由。两个技能是互补的：scholar-knowledge 回答 *这个领域主张什么*，scholar-rag 回答*把那一段原文带出处给我看*。

8C.1 文件长什么样

~/.claude/scholar-knowledge/                （可用 $SCHOLAR_KNOWLEDGE_DIR 覆盖）
├── papers.ndjson         ← 每行一个 JSON，描述一篇论文（含抽取出的丰富内容）
├── concepts.ndjson       ← 命名概念、理论、机制
├── edges.ndjson          ← 论文间关系（cites、contradicts、extends ……）
├── meta.json
└── raw/                  ← **append-only** 原始档案
    ├── pdfs/             ← 软链到 Zotero PDF（不复制大文件）
    ├── abstracts/        ← 抽取的文本
    ├── api-responses/    ← 原始 CrossRef / Semantic Scholar JSON
    ├── web/              ← 抓取的预印本、NBER WP、博客
    └── images/           ← 从 PDF 抽出的图（每篇一个子目录）

一个 paper 节点（真实 schema，简化版）：

{
  "id": "fiel-zhang-2017",
  "doi": "10.1007/s13524-017-0632-9",
  "title": "Three Dimensions of Change in School Segregation: A Grade-Period-Cohort Analysis",
  "authors": ["Fiel, Jeremy E.", "Zhang, Yongjun"],
  "year": 2017,
  "journal": "American Sociological Review",
  "findings": ["School segregation decreased along racial lines but increased along socioeconomic lines between 1999 and 2010."],
  "mechanisms": ["compositional change (demographic shifts)"],
  "theories": [{"name": "spatial assimilation", "role": "tests"}],
  "methods": ["decomposition analysis", "multilevel models"],
  "populations": ["K-12 students in US public schools"],
  "data_sources": ["Common Core of Data (CCD)"],
  "limitations": ["Data limited to public schools"],
  "future_directions": ["Within-district heterogeneity at the classroom level"],
  "projects": ["segregation-paper-2026", "digital-divide-china-cfps"],
  "raw_path": "abstracts/fiel-zhang-2017.txt"
}

重点是 findings、mechanisms、methods、limitations、future_directions——你的文献管理器不存这些，可你天天要用。

边长这样：

8C.2 八种模式 —— 具体命令

模式 1 —— INGEST：从 Zotero 批量导入

> /scholar-knowledge ingest from zotero collection "digital divide"
> /scholar-knowledge ingest from zotero tag "hukou"
> /scholar-knowledge ingest from zotero keyword "second-level digital divide" 30

对每篇命中：

1. 读 Zotero SQLite 拿到书目元数据
2. 把 PDF 软链（不复制）到 raw/pdfs/<slug>.pdf
3. pdftotext 抽前 400 行
4. 装了 poppler 时还可以 pdfimages 抽图
5. 抽 findings / mechanisms / theories / methods / populations / data sources / limitations / future directions / key quotes（带页码，如有）
6. 把 paper 节点 append 到 papers.ndjson
7. 新理论 / 新机制 append 到 concepts.ndjson
8. 按 DOI / 标题 hash 去重——重复 ingest 是幂等的

模式 1 —— INGEST：从 PDF / DOI / URL / 自己作品

> /scholar-knowledge ingest from pdf ~/papers/li-ouyang-hu-2025.pdf
> /scholar-knowledge ingest from doi 10.1038/s41746-025-02076-1
> /scholar-knowledge ingest from url https://www.nber.org/papers/w29234
> /scholar-knowledge ingest from output output/digital-divide-china-cfps/drafts/manuscript-final-2026-05-04.md

最后一条——from output——是反馈闭环。每写完一篇论文，把自己的论文 ingest 回图谱。论文类型变成 "own_work"，发现就能在下一个项目里被检索到。

模式 2 —— SEARCH

> /scholar-knowledge search "second-level digital divide China"
> /scholar-knowledge search papers using-method "Oaxaca-Blinder"
> /scholar-knowledge search papers contradicts spatial-assimilation

返回论文 ID、题目、相关性排序、每条命中一句解释。它直接喂 scholar-lit-review-hypothesis（§8A）—— lit-review 技能查外部 API 之前先读 papers.ndjson。

模式 3 —— RELATE：由你亲自断言的那些边

导入阶段抽的是发现，它不会替你判断两篇论文**互相矛盾**。那条边是一个学术判断，所以得你来下 —— 下完之后它就变成可查询的了。

> /scholar-knowledge relate [论文 A] contradicts [论文 B]
> /scholar-knowledge relate [论文 A] extends [论文 B]
> /scholar-knowledge relate show relationships for [论文 A]
> /scholar-knowledge relate show all contradicts
> /scholar-knowledge relate map residential segregation

两篇论文都必须已经在图谱里；缺一篇的话，技能会先问你要不要导入，而不是凭空造一个节点。 真正值得花力气的是 contradicts —— 一篇能把自己领域的分歧一条条列出来的综述，做到了摘要做不到的事。

模式 4 —— STATUS（仪表盘）

> /scholar-knowledge status

真实输出：

Knowledge graph at ~/.claude/scholar-knowledge
  Papers:   1,142
  Concepts: 287
  Edges:    3,901
  Raw archive: 4.2 GB across 1,142 PDFs and 318 web fetches

Top theories (by paper count):
  1. cumulative advantage / Matthew effect            (87 papers)
  2. spatial assimilation                             (54 papers)
  3. layered (three-level) digital divide             (41 papers)
  4. hukou as institutional sorting                   (33 papers)
  5. second-demographic transition                    (29 papers)

Coverage gaps (theories with <3 papers):
  - distributed cognition + digital practice (1 paper — extend)
  - intersectional algorithmic harm           (2 papers — extend)
  - capability approach × digital inclusion   (0 papers — gap)

Project tags:
  digital-divide-china-cfps    (76 papers)
  hukou-marriage-cfps           (94 papers)
  segregation-paper-2026       (108 papers)
  …

模式 5 —— EXPORT：只导出一个子集，给一个项目或一份参考文献

> /scholar-knowledge export for project digital divide
> /scholar-knowledge export for collection [zotero 分类]
> /scholar-knowledge export by author [作者名]
> /scholar-knowledge export all as bibtex

默认是 markdown；as bibtex 会写出一个 .bib。用它把与某一篇论文相关的那一小片图谱交给合作者， 而不必把整个文献库都交出去。

模式 6 —— COMPILE：把图谱编译成 Obsidian wiki

> /scholar-knowledge compile

在 ~/.claude/scholar-knowledge/wiki/ 产出一份完整链接的 markdown wiki：每篇论文一页、每个理论 / 机制一页、[[wiki-link]] 互相引用。Obsidian（或任意 markdown 阅读器）打开后图谱视图可浏览。每次 ingest 之后跑一次。

模式 7 —— ASK：跨图谱问研究问题

> /scholar-knowledge ask what are the main theories of the second-level digital divide?
> /scholar-knowledge ask compare the mechanisms in van Deursen & Helsper 2015 vs Hargittai 2002
> /scholar-knowledge ask which CFPS papers in my graph use Oaxaca-Blinder decomposition?

技能读已编译的 wiki，回答时带论文级引用。所有主张都被你 ingest 过的内容约束住，幻觉空间被锁死。

模式 8 —— RE-EXTRACT：升级 schema

给 paper 节点加新字段（比如 “data-availability statement“ 或 ”preregistration link”）后跑：

> /scholar-knowledge re-extract all abstract_only
> /scholar-knowledge re-extract field=data_availability

技能遍历 raw/，按更新后的 schema 重新抽取——不重新抓网络。这正是 raw 档案 append-only 的意义：schema 可以变，源不能变。

8C.3 这件事对 CFPS 工作坊为什么重要

工作坊流水线里，scholar-lit-review-hypothesis（§8A）先查 papers.ndjson，再查 WebSearch。如果你已经 ingest 过 Wu & Treiman 2004、Xie & Jin 2015、van Deursen & Helsper 2015 等，lit-review 直接拿全字段已验证书目去引用，不会留下 “[CITATION NEEDED]” 占位。scholar-citation verify（§16）也一样——本地命中是 Tier 1，免费且即时。

正确的节奏：

每写完一篇论文：
   /scholar-knowledge ingest from output drafts/manuscript-final-...md
   /scholar-knowledge compile

每开一个新项目：
   /scholar-knowledge ask what do I already know about <topic>?
   /scholar-knowledge export for project <new-slug>

8C.4 检查

• raw/ 是 append-only。 永远不要 rm。审计轨迹靠它。
• 边数应该是概念数的 ~10 倍。 400 篇论文却只有 12 条边——你 ingest 了，但没连——跑 relate 模式。
• 重抽很便宜。 加新 schema 字段了？re-extract 是朋友；不要从源重新 ingest。

自检： 每月跑一次 /scholar-knowledge status。”Coverage gaps” 里出现你正引用的理论——下次写综述前先 ingest 5–10 篇锚点论文。

8C.5 Obsidian wiki —— 安装、配置、浏览

/scholar-knowledge compile 在 ~/.claude/scholar-knowledge/wiki/ 生成一份 Obsidian 兼容 vault。Obsidian 免费、本地优先，是真正能让你读和导航这张图的最顺手工具。本节走一遍技能预期的配置。

8C.5.1 compile 写出什么

~/.claude/scholar-knowledge/wiki/
├── index.md                ← 仪表盘：统计、近期 ingest、快捷链接
├── knowledge-map.png       ← 渲染好的网络图（如生成）
├── contradictions.md       ← 争议发现（图中带 contradicts 边的论文）
├── gaps.md                 ← 研究空白与未被填的 future-direction
├── papers/                 ← 每篇论文一页
│   ├── fiel-zhang-2017.md
│   ├── li-ouyang-hu-2025.md
│   ├── van-deursen-helsper-2015.md
│   └── …                                       （通常是几百个文件）
├── concepts/               ← 每个理论 / 方法 / 机制一页
│   ├── spatial-assimilation.md
│   ├── layered-digital-divide.md
│   ├── oaxaca-blinder-decomposition.md
│   └── hukou-as-institutional-sorting.md
├── topics/                 ← 自动聚类的主题页
│   ├── digital-inequality-china.md
│   └── residential-segregation.md
└── answers/                ← Q&A 存档（每次 /scholar-knowledge ask 都增加一条）
    └── second-level-digital-divide-mechanisms-2026-05-08.md

一篇论文页（papers/li-ouyang-hu-2025.md）渲染成这样：

# Li, Ouyang & Hu (2025) — Ten-Year Analysis of Digital Divides Among Older Chinese Adults

**Journal:** npj Digital Medicine
**DOI:** 10.1038/s41746-025-02076-1
**Data:** [[CFPS]] 2010–2020

## Findings
- Persistent age-related gap in healthy-aging outcomes attributable to digital exclusion.
- Gap does not narrow across the decade despite access growth.

## Mechanisms
- [[skill-conversion]] — older cohorts' lower marginal returns to use.

## Theories used
- [[layered-digital-divide]]  (role: applies)
- [[cumulative-advantage]]    (role: extends)

## Methods
- [[OLS-with-fixed-effects]]
- [[descriptive-decomposition]]

## Limitations (per authors)
- Cannot separate cohort from age in single panel — [[APC-identification]] is non-identified without restriction.

## Future directions (per authors)
- Within-household digital transmission — see [[household-spillover]].

## Edges
- This paper **uses-theory** [[van-deursen-helsper-2015]]
- This paper **extends** [[ren-zhu-2024]]
- This paper is **cited-by** [[zhang-2026-digital-divide-china-cfps]]   (own-work)

---
*Ingested: 2026-04-12 from Zotero. Raw: `raw/pdfs/li-ouyang-hu-2025.pdf`.*

一个概念页（concepts/layered-digital-divide.md）：

# Layered (Three-Level) Digital Divide

A theoretical framework distinguishing access (Level 1), skill / use intensity
(Level 2), and conversion of online activity into offline returns (Level 3).

## Anchor papers
- [[dimaggio-hargittai-celeste-shafer-2004]] — original five-dimension formulation
- [[hargittai-2002]] — coined "second-level digital divide"
- [[van-deursen-helsper-2015]] — named the third level
- [[robinson-et-al-2015]] — life-course / gender / race consolidation

## Papers using this framework      (41 in graph)
- [[li-ouyang-hu-2025]]
- [[ren-zhu-2024]]
- [[zhang-2026-digital-divide-china-cfps]]   (own-work)
- …

## Mechanisms
- [[skill-formation]]
- [[content-sorting]]
- [[opportunity-matching]]

## Empirical predictions in this graph
- Access gaps narrow as penetration saturates.
- Use-intensity gaps **persist or widen** under cumulative advantage.
- Returns gaps depend on cultural and economic capital.

## Contradictory evidence (in graph)
- [[zhao-et-al-2022]] — finds narrowing intensity gap among rural Chinese students under online learning.

[[双方括号]] 是 wiki-link——Obsidian 渲染成可点链接，Cmd+Click 跳转，Backlinks 侧栏会自动告诉每页“哪些其他页链向了我”，你不用手工维护反向指针。

8C.5.2 安装 Obsidian、打开 vault

# macOS
$ brew install --cask obsidian

# Linux（从 obsidian.md 下 AppImage）
$ # 下载 Obsidian-1.x.AppImage、chmod +x、运行

# Windows（WSL 学员：在 Windows 侧装 Obsidian，指向 WSL 路径）

打开 vault：

1. 启动 Obsidian
2. 点击 Open folder as vault

3. 按 Cmd+Shift+G（macOS）或 Ctrl+L（Linux），粘贴：

   ~/.claude/scholar-knowledge/wiki
   

4. 确认。Obsidian 索引 vault——1,000 篇论文图谱首次大约 30–60 秒。

便利软链：

$ ln -s ~/.claude/scholar-knowledge/wiki ~/Desktop/scholar-wiki

之后从 Finder 直接打开 ~/Desktop/scholar-wiki 就行。

8C.5.3 推荐 Obsidian 设置

Files & Links：

• Detect all file extensions → ON
• Default location for new notes → “In the folder specified below” → answers/
• Use [[Wikilinks]] → ON（默认）

Editor：

• Readable line length → ON

核心插件（Settings → Core plugins，全部开启）：

• Graph view (Cmd+G) —— papers ↔ concepts ↔ topics 的可视化网络
• Backlinks —— 每页侧栏显示“谁 [[…]] 引用了我”
• Outgoing links —— 每页侧栏显示“我链向了哪些”
• Quick switcher (Cmd+O) —— 输入页名跳转
• Search (Cmd+Shift+F) —— 全文搜索整个 vault
• Tags —— 你给页面加 #topic/segregation 之类的话用

社区插件（Settings → Community plugins → Browse）：

• Dataview —— 把 wiki 当数据库查询：

  TABLE journal, year FROM "papers"
  WHERE contains(theories, "layered-digital-divide") AND year >= 2020
  SORT year DESC
  

  实时渲染：你图谱里 2020 年后用 layered framework 的所有论文。

• Graph Analysis —— 在 wiki 图上算 centrality、clustering、betweenness
• Breadcrumbs —— paper → concept → topic 层级导航
• Calendar —— 按 ingest 日期看论文

8C.5.4 Graph View 配置

Cmd+G 打开。默认视图无差别，按下面配：

Filters 面板：

• Tags —— 按标签显示 / 隐藏
• Orphans 开关 —— 切到只看孤立论文（relate 模式候选）

Groups（按节点类型上色） —— 点 “+ Add group” 五次：

Display 面板：

• Node size → “By number of links”——突出连接最多的论文（通常是子领域的锚点引用）
• Arrow → ON——[[…]] 引用方向可见
• Line thickness → “By number of connections”

效果：密集红簇是有大量支持论文的理论；密集蓝簇是子领域；连两簇的桥节点是整合性论文，最值得仔细读。

8C.5.5 四种浏览模式

(a) 浏览研究地图。

打开 index.md。点一个主题（如 [[digital-inequality-china]]），看到这个主题下的论文与概念清单。点任意论文看 findings、theories、methods。Backlinks 侧栏告诉你谁引用 / 扩展了它。

(b) 找连接。

Cmd+G 打开 Graph View。在搜索框里输概念名（如 hukou-as-institutional-sorting）。它在图里高亮，邻居就是用了这概念的论文。注意找桥节点——连接两个原本独立簇的节点。这些论文最可能给你一个新颖的框架。

(c) 在 wiki 上问问题。

在 Claude Code 里跑 /scholar-knowledge ask <问题>。答案存到 wiki/answers/<问题-slug>-<日期>.md，并附上它咨询过的所有 wiki 页的引用。在 Obsidian 里打开答案文件——Backlinks 侧栏列出所有“喂”过这个答案的论文。一年之后，answers/ 文件夹本身就是一份可搜索的 Q&A 档案。

(d) 跟踪研究进展。

• wiki/gaps.md —— 图谱说哪些方向你还没研究（STATUS 模式里覆盖度低）
• wiki/contradictions.md —— 有争议的发现（图里有 contradicts 边）
• wiki/answers/ —— 你已经探索过的问题
• Graph View —— 密集簇是研究充分的领域，稀疏区是空白

8C.5.6 让 wiki 保持最新

wiki 自动更新：

• 每次 ingest 之后 —— paper 页、concept 页、index.md 只对新条目增量重生。
• 全量重建 —— 跑 /scholar-knowledge compile full 重生主题聚类、contradictions.md、gaps.md、可视化。每月一次或大批 ingest 之后跑。
• 手工编辑 —— 你可以手改某页（比如在 Findings 段加私人笔记），增量重建会保留。但全量重建可能覆盖——想留永久私注，建一个独立的 notes/ 文件夹自己管，别写在自动生成页里。

自检： 在 Obsidian → Graph View 中过滤到当前项目的论文（path:papers/ + 项目标签）。看到的簇就是你实际拥有的文献。STATUS 模式标过 “Coverage gap” 而这个簇里又看不到的——那就是你下一次 ingest 应该瞄准的方向。

8D. scholar-causal —— 有意识地挑一个识别策略

目标： 在写设计蓝图之前，先决定这个问题是不是因果问题；如果是，再决定数据到底支持十四种识别策略中的哪一种。本技能位于 /scholar-hypothesis 与 /scholar-design 之间，是你把要捍卫的假设写下来、提交在案的地方。

最近一次更新大幅拓宽了它的覆盖面。早期版本只处理 OLS、DiD、RD、IV、FE、matching、合成控制。现在的版本覆盖十四种识别策略，每一种都自带假设、诊断、R 与 Stata 代码、以及一份期刊级的写作模板：

1. OLS 在 selection-on-observables 下（配 Oster δ）。
2. 2×2 双重差分。
3. 断点回归 —— Sharp 与 Fuzzy。
4. 工具变量 / 2SLS。
5. 面板固定效应（TWFE）。
6. 匹配 / 重加权 —— PSM、CEM、IPW、doubly robust。
7. 合成控制 / SynthDiD。
8. 因果中介（ACME） 在序列可忽略性下。
9. 交错 DiD —— Callaway-Sant’Anna、Sun-Abraham、de Chaisemartin-D’Haultfœuille、Borusyak-Jaravel-Spiess（附一份可直接跑的 CS 工作流模板 references/did-cs-workflow.R）。
10. Double Machine Learning 与 causal forests，用于高维混杂。
11. Bunching estimation，在 kink/notch 处。
12. Shift-share / Bartik IV，地方层面对总量冲击的暴露。
13. 分布与分位数方法 —— 分位数回归、RIF-OLS、changes-in-changes。
14. 析因 DiD（Factorial DiD, FDID） —— 用于全体同时暴露、没有干净对照组、但存在事件前基线因子 G 的情形；区分效应修饰与因果调节，配有可运行的工作流模板 references/fdid-workflow.R。

8D.1 运行

> /scholar-causal 农业户口对每周上网时长的效应，
                  CFPS 2010-2020 面板；候选混杂：
                  家庭收入、教育、父母职业、村基础设施

技能开场会问三件事：（1）因果问题（X 对 Y 的效应）；（2）数据结构（截面、面板、自然实验）；（3）候选混杂与机制。下游的一切都取决于这三个回答。

8D.2 技能产出什么

一次典型运行会在项目目录里写下四份产物：

design/
  ├─ causal-dag.tex             # dagitty + TikZ DAG，含调整集
  ├─ identification-memo.md     # 选哪个策略、为什么、假设是什么
  ├─ diagnostic_plan.json       # Tier 1：始终生成 —— 设计前要跑的检查清单
  └─ sensitivity-registry.md    # Oster δ / E-value / HonestDiD / Rosenbaum / Manski
logs/process-log-scholar-causal-<日期>.md

identification-memo.md 是最关键的一份。它命名所选策略，按“估计对象 → 识别假设 → 估计量 → 威胁”四步走，并列出禁止主张清单 —— 这份清单后续会被 scholar-write、scholar-verify、scholar-polish 拿去强制执行。（CFPS 流水线之所以能在 Abstract 用 “reduces“ 而 Methods 只允许 ”is associated with” 时把它拦下来，靠的就是这个机制。）

8D.3 方法选择决策表

技能内置一张决策表，agent 会牵着你过一遍。压缩版本：

8D.4 敏感性分析套件

挑出策略只完成一半工作。技能还会写一份敏感性登记表，把稳健性检查在你看到结果之前就锁定：

• Oster (2019) δ —— 用于 selection-on-observables 下的 OLS。
• E-values (VanderWeele & Ding 2017) —— 把效应“解释干净”所需的最小未观测混杂强度。
• Rosenbaum bounds —— 匹配估计量对隐藏偏倚的敏感性。
• HonestDiD (Rambachan & Roth 2023) —— 在有限的平行趋势违反下做边界推断。
• Manski bounds —— 弱化假设下的部分识别。
• 安慰剂 / 证伪检验 —— 处理前结果、永远未处理组的引领项、时间安慰剂。
• 溢出敏感性 —— 在传染或干扰下违反 SUTVA。
• Specification curve / multiverse —— 把所有合理的设定都排出来。

8D.5 Tier 1 与 Tier 2 —— 哪些真的会跑你的数据

技能分两层执行。Tier 1 始终生成 diagnostic_plan.json —— 一份机器可读的检查清单，规定设计锁定前要跑哪些诊断。Tier 2 默认关，需要显式打开，直接执行少量预设计诊断：

• 面板预览 用 panelview + fect —— 检查处理时序与前趋势。
• 合成控制预览 用 gsynth（Xu 2017）—— 评估 synth / SynthDiD 在你案例上的可行性。
• 交互效应诊断 用 interflex（Hainmueller, Mummolo, Xu 2019）—— 看你的调节变量到底是不是线性的。
• 析因 DiD 预览 用 fdid（Xu, Zhao & Ding 2026）—— 用于交叉处理 / 析因 DiD 设计。

Tier 2 受闸门控制：你必须在提示词里明确写「在这份数据上跑诊断」。Tier 2 不会估计焦点效应、不会拟合最终模型、不会产出会进论文的数字。它产出的诊断图，是用来辅助 §9（scholar-design）里你要提交的那个选择。

8D.6 为什么 CFPS 工作坊故意绕开 scholar-causal

本手册里的数字鸿沟案例故意不是一个因果设计。户口出生时分配、几乎不变；没有可操纵的“处理”。我们既没有工具变量，也没有断点。正确的做法 —— 也是工作坊演示的做法 —— 是拒绝采用因果识别策略，改写一份描述性/分解设计。在那种情况下 scholar-causal 仍然有用：它产出的 DAG 论证了你的协变量调整集，并在 identification memo 里盖上 causal_status: descriptive 戳记，下游技能据此强制执行正确的语言上限。

如果你的项目确有因果杠杆 —— CCT 风格的 RCT、政策冲击、断点、可信的 IV —— 项目就从 scholar-causal 开局，然后再跑 scholar-design。决策的是策略；纪律是在分析跑起来之前，把假设写下来。

8D.7 自检

进入 §9 之前，打开三个产物各问自己一句：

• causal-dag.tex —— 调整集够不够？DAG 漏没漏 back-door 路径？
• identification-memo.md —— 一个敌意审稿人能不能把每条假设都打掉？其中是否有一条经验上可检验？
• sensitivity-registry.md —— 焦点效应若能挺过 Oster δ > 1 与高于最强控制变量的 E-value，标题主张就站得住。

自检： 如果 identification memo 写着 causal_status: descriptive，在动笔写正文之前先回到 §9.3 的“禁止主张”段读一遍 —— 你的语言上限从此被锁死。

8E. scholar-lit-review 与 scholar-hypothesis —— 什么时候单独用它们

§8A 讲的是合体技能。两半也各自独立存在，而且确实有理由单独取用：一片你还没准备好转成假设的文献地景，或者一批从你已经熟悉的文献里推出来的假设。

8E.1 scholar-lit-review —— 三种深度

argument-hint: "[topic or research question] [optional: landscape|targeted|rapid]
                [optional: target journal] [optional: population, time period,
                geographic scope]"

> /scholar-lit-review "digital divide in China" landscape "Social Forces" 2010-2025
> /scholar-lit-review "remote work and the gender wage gap" rapid

各轮是累加的：第 1 轮核心主题 · 第 2 轮机制与理论 · 第 3 轮方法与数据（定向与全景） · 第 4 轮近期前沿（仅全景） · 第 5 轮争议地带与零结果（仅全景）。

有三个特性把它和“搜索并总结”区分开：

• Annual Reviews 检查点永远会跑。 技能会搜 site:annualreviews.org，优先 Annual Review of Sociology，并从任何相关综述里至少抽出五篇被引论文。一篇好综述抵二十条搜索结果。
• 引文链扩展（全景模式必做）：从三到五篇关键论文的参考文献表往回追，再对最基础的那几篇用 “cited by” 往前追。
• 第 3 轮专门找点名批评者。 在跑方法搜索之前，技能会加载一份方法批评者参考表，按名字去搜你计划用的每个方法的主要批评者 —— age-period-cohort 找 Bell & Jones，交错 DiD 找 Goodman-Bacon。在你押注之前就找到针对你方法的反对意见，比在评审阶段才发现便宜得多。

输出是一张八维度的地景图：领域演化时间线 · 理论地景（框架、核心主张、支持者、预测、证据支持、现状） · 已确立发现 · 有争议发现（配证据权重表） · 零结果与缺席结果，二者严格分开 · 机制清单（提出过的 vs. 真正被检验过的） · 方法地景 · 排序过的缺口分析。全景模式还会产出一张 PRISMA 流程图。

第九个维度是一张理论交接表 —— 缺口 → 理论含义 → 候选框架 → 为什么对手框架不够 —— 外加一段可直接粘给 /scholar-hypothesis 的段落。

两条硬行为：检测不到本地文献库时技能直接硬停，而不是悄悄退化成纯网页搜索；以及它在第一次查询之前就把搜索日志写到磁盘，并在每一次查询之后追加，因为上下文压缩会无声地毁掉内存里的命中计数。

全文那一层（v5.27）。 Phase 1 先搜你的文献库、再搜网页，而且顺序是固定的：知识图谱（预抽取的发现）→ scholar-rag → Zotero（书目元数据）→ 网页。中间那一层是新加的。当 /scholar-rag status 报告 embedded > 0 时，技能会去查你自己 PDF 里的全文段落 —— MCP 服务器已注册的话走 rag_search("<topic>", k=8, hybrid=true)（§8F.4），否则走 query.py CLI。回来的是带页码的引文段落，这和它两边的邻居是不同种类的证据：图谱给你发现，Zotero 给你元数据，这一层给你句子。取回的段落是待核实的线索，本身绝不是引文；每一条参考文献仍要过 Tier 0–2 验证。

还有一道理论关卡：如果你的提示词提到假设或理论章节，技能会停下来，把你转到 /scholar-lit-review-hypothesis（§8A），而不是只给你一半你需要的东西。

8E.2 scholar-hypothesis —— 把预测形式化

argument-hint: "[phenomenon or RQ] — optionally: [design type: quant/qual/comp/
                computational] [journal: ASR/AJS/Demography/NHB/NCS/SciAdv]
                [theory hint]"

> /scholar-hypothesis "why cumulative disadvantage widens the wealth gap" quant ASR
> /scholar-hypothesis "language shift among heritage speakers" qualitative \
                      "Language in Society" Fishman

八个步骤：把谜题框起来（异常、矛盾、拓展、机制或范围条件）→ 选框架（一个主框架，最多一个辅框架）→ 确定假设摆放模式 → 说明机制链 → 推导并形式化 → 映射竞争性预测 → 建一张文本 DAG → 写理论章节。

摆放模式由期刊决定，不由偏好决定：

这一步搞错，技能自己的存盘前检查就通不过。

推导链表是核心机制。 每条假设都必须把每一列填满：

| H# | 文献缺口 | 缺口类型 | 框架预测 | 机制链环节 | 假设 | |—|—|—|—|—|—|

填不满每一列，这条假设就被删掉。 被点名的失败模式是：假设只对上了框架的一般性预测，却没有指向机制里的某个具体环节 —— 读起来像理论，实际上什么都没检验。

机制通过 Coleman’s boat（情境 → 行为形成 → 转换）或 Hedström 的 DBO（欲望、信念、机会）来说明，按 Elster 的类型分类（认知、动机、互动、制度、物质），并由一张必填的范围条件矩阵划定边界。

支持七种假设形式：主效应 · 调节（扇形展开 vs. 交叉） · 中介 · 曲线或阈值 · 比较/组层面 · 边界条件 · 零结果即发现。交叉性假设有自己的必需形式：必须以乘性方式写成一个待检验的交互项，而不是拆成两条独立的主效应假设。

每条假设还配一条竞争性预测：对手理论预测什么、如果对手是对的数据会长什么样、以及能区分二者的那个具体检验。外加一份替代解释清单 —— 选择性、反向因果、遗漏变量、测量假象、构成差异 —— 每一条都要写成一句“我们通过 [设计特征] 处理 [替代解释]”。

因果语言的校准在这里和在别处一样被强制执行：没有识别策略的观测数据只能用 “is positively associated with” 和 “predicts”，绝不能用 “causes” 或 “the effect of”。

理论章节字数预算：ASR/AJS 1,000–1,500 · Demography 600–1,000 · NHB/Science Advances 300–600（嵌在引言里） · NCS 200–400。

技能自带一个 25+ 框架的参考库 —— 分层、网络与资本、文化、同化、生命历程、Coleman’s boat、DBO、种族形成、地位特征、社会运动、信号、理性选择、接触假说、标签理论、交叉性、新制度主义、组织生态学、实践理论、女性主义立场论、劳动过程、行动者网络理论，以及非西方传统包括殖民性、世界体系、后殖民理论、Ubuntu 和儒家/关系框架 —— 每个都附核心主张、机制、最佳适用场景、关键论文和现成的起句。

自检： 拿你自己研究里的一条假设，把推导链表填一遍。如果“机制链环节”那一列最难填，这就是诊断结果：你手上是一条预测，还不是一个理论。

8F. scholar-rag —— 建在你自己文献库上的本地向量数据库

目标： 把你拥有的每一个 PDF 变成可检索、带引文的段落 —— 并把这套检索作为工具交给 Claude Code 和 Codex，于是一次文献综述会话能引用你的文献库，而不是转述它对文献库的记忆。

argument-hint: "[setup|ingest|query|mcp|graph|status] [args], e.g. 'ingest' or
                'query how does segregation affect mobility' or 'graph run'"

这是套件里最新的技能（v5.27，2026 年 7 月），也是最直接改变文献工作手感的一个。§8C.0 摆出了把对的文本送进模型窗口的三条路 —— RAG、智能体式搜索、知识 wiki —— 并说它们互补。scholar-rag 就是其中第一条，而且是认真做出来的：

两者共享论文身份（doc_id = 规范化 DOI 或标题的 sha256），所以一次段落命中能交叉链接到同一篇论文的抽取结果；而 GraphRAG 层直接从知识图谱给自己的实体图播种，不必冷启动。

一切都在本地。 embedding 用 bge-m3，GraphRAG 的 LLM 用 ollama，向量库用 LanceDB，接口是一个 stdio MCP 服务器。唯一的网络流量是可选的开放获取 PDF 抓取。这件事比听上去更要紧：另一条路 —— 把整个 Zotero 库上传到托管向量服务 —— 是一次你必须披露的数据传输；而对任何处于禁运期或 IRB 限制下的材料，那是一次你根本做不了的传输。

它是自包含的。 引擎用 uv 自建 CPython 3.12 虚拟环境，直接读 Zotero，自带日志。它对插件其余部分没有硬依赖，scholar-knowledge 不在时也能优雅降级。

8F.1 九个模式

full 跑 0 → 1 → 3。GraphRAG（模式 4）故意不在 full 里 —— 它是那个漫长的、受 LLM 限速的阶段，在真实规模的文献库上是数小时的本地推理。

8F.2 把它建起来

# 一次性
> /scholar-rag setup

# 整个 Zotero 库（自动探测）；先加 --limit 拿一个子集试跑
> /scholar-rag ingest

底层就是 run-ingest.sh，长跑时值得直接驱动它：

$ bash "$RAG_ASSETS/run-ingest.sh" --batch 64                  # 前台，盯着跑
$ bash "$RAG_ASSETS/run-ingest.sh" --batch 64 --background     # 脱离；tail 打印出来的日志
$ bash "$RAG_ASSETS/run-ingest.sh" --source folder --folder ~/pdfs
$ bash "$RAG_ASSETS/run-ingest.sh" --ocr                       # 扫描版 PDF，走 llama3.2-vision

三个阶段，每份文档带着一个 status 走完 —— new → extracted → embedded，或者 no_pdf / failed：

Zotero/PDFs ──ingest──▶ documents(new)
   PDF ──extract（PyMuPDF → pdftotext → 视觉 OCR）──▶ raw/text + documents(extracted)
   text ──chunk（按章节，约 500 token，带重叠）+ bge-m3──▶ LanceDB + documents(embedded)

每个阶段只处理尚未推进的行，所以被杀掉的运行会从断点继续 —— 你一定会用上，因为整库构建是 embedding 受限的：几千个 PDF 即便在 Apple 芯片的 MPS 上也要数小时。请脱离终端跑。

抽取阶梯值得了解，因为它决定质量：先 PyMuPDF（快，保留页码映射），退到 pdftotext，最后对扫描件用视觉 OCR。抽出来的文本按页缓存在 raw/text/<doc_id>.json —— 这正是换一个模型重新切块或重新 embedding 很便宜的原因：你不必重新抽取。

8F.3 查询它

> /scholar-rag query how does residential segregation affect intergenerational mobility?

# 或者直接跑，带过滤与重排：
$ rag_py query.py "identification strategy" -k 6 \
         --section methods,results --year-min 2010 --rerank --json

每条命中都带着作者-年份引文、章节、页码范围、DOI 和相似度回来。页码才是重点：它让你用十秒钟核实一条主张，而不是重读一篇论文；也正是 scholar-citation 用来把主张对回源文献的东西（§16.5）。

8F.4 把它交给智能体 —— MCP 服务器

> /scholar-rag mcp

$ bash "$RAG_ASSETS/mcp-setup.sh"              # 注册进每一个探测到的宿主
$ bash "$RAG_ASSETS/mcp-setup.sh" --print-only # 只打印 .mcp.json / config.toml 片段

这会注册一个 stdio MCP 服务器（§3.6），暴露四个工具：

要重启会话才能加载这些工具。

8F.4.1 它被接进了哪三个技能

这一节讲的正是那个你什么都不用做、工作流就变了的部分。索引一旦存在，就有三个技能会自己去调它 —— 你不需要在文献综述过程中调用 scholar-rag，你只是得到了一次更好的文献综述。每一个都先查 /scholar-rag status，没有索引就静默退回原来的行为。

它不做什么。 rag_search 浮出的是文本，它不生成引文。每一条参考文献仍然要走 Verified Citation Pool 和 /scholar-citation（§16）。把检索到的段落当作待核实的线索，而不是已经确认的来源 —— 索引只能和它切的那个 PDF 一样诚实，而一段被从章节里撕下来的文字照样可能被读错。分工值得说一次并记住：scholar-rag 拥有文本，/scholar-citation 拥有书目记录。

8F.5 GraphRAG —— 那根长杆

向量检索能找到离查询最近的段落。它回答不了”这片文献里主要有哪几个理论阵营”，因为没有任何单独一块里装着这个答案。GraphRAG 建的就是能回答它的结构：

$ rag_py graphrag.py seed        # 导入 scholar-knowledge 的概念与引用边（快，不用 LLM）
$ rag_py graphrag.py extract     # 逐篇论文做 LLM 实体/关系抽取 —— 最长的阶段，可续跑
$ rag_py graphrag.py build       # 实体去重 → Leiden 社区
$ rag_py graphrag.py summarize   # LLM 社区摘要（global 检索的语料）
$ rag_py graphrag.py run --limit 50                                     # 整条链，带上限

run 是那条**短**链，而这是个坑。 它执行的正好是 seed → extract → build → summarize， 不包含 citations、keywords、semantic —— 而这三个阶段必须落在 build 之前，因为 build 正是做实体去重和算 Leiden 社区的那一步。build 跑早了，社区就是在一张没有文献 引用边、没有关键词节点、没有实体合并的图上算出来的；事后补救意味着 build 和 summarize 都要重跑，而后者正是最贵的 LLM 阶段。请用 §8F.6 里的顺序。

$ rag_py graphrag.py local  "mechanisms linking neighborhood to health" # 实体锚定的段落
$ rag_py graphrag.py global "what are the major theoretical camps here?" # 在社区上 map-reduce
$ rag_py graphrag.py neighbors <doc_id>

会咬你的是选模型。 抽取默认用 deepseek-r1:32b：它能跑，也遵守 format=json，但那是个推理模型 —— 做批量抽取很慢。gpt-oss:20b 是更快的理想选择，但在较老的 ollama 构建上会以 tensor "blk.0.ffn_down_exps.weight" size overflow 失败；brew upgrade ollama、重启服务，然后 export RAG_GRAPH_MODEL=gpt-oss:20b。要是拿不到它，务实的答案是一个快的 instruct 模型：ollama pull qwen2.5:7b-instruct。抽取按章节截断（默认 12k 字符），并且逐文档可续跑 —— 脱离终端跑，让它跨会话继续。

8F.6 真正让这张图值钱的三个阶段

实体共现回答的是”哪些论文用了同样的词”。下面这三个回答的是”哪些论文真的在互相接力”、 “这个领域本来管它叫什么”、以及”哪些论文明摆着在讲同一件事”。三个都是本手册第一版之后 才加的，而且 graph run 一个都不跑。

$ rag_py citations.py fetch      # 每个 DOI 一次 OpenAlex 调用 —— 可续跑、带缓存
$ rag_py citations.py build      # 直接引用 + 耦合 + 共被引 → 论文社区
$ rag_py keywords.py load        # Zotero 标签 + OpenAlex 主题 + 正文 Keywords 行
$ rag_py semantic.py entities    # 连接归一化\*\*做不到\*\*的实体同义词
$ rag_py semantic.py docs        # 论文↔论文 kNN —— 能覆盖到压根没有 DOI 的论文
$ rag_py semantic.py duplicates  # 同一篇被导入了两次

每一个为什么值得它的运行时间：

• citations —— 光靠 seed，在一个 5.5k 篇的语料上只覆盖了约 12%。文献耦合（A 和 B 引了同一篇）能触达的配对远多于直接引用，而且对”还没人引”的新论文依然有效。
• keywords —— 它天然是跨文档的：一个标签盖住几十篇论文，而这恰恰是逐篇构建的实体图 最缺的东西。而且没有幻觉风险。
• semantic —— 一篇没有 DOI 的论文根本不会进 OpenAlex 缓存，所以它对整个文献计量层 是隐形的。在同一个语料上，加了语义边之后论文图覆盖率从 72% 升到 95%（3,923 → 5,189 篇）。 它还能把 residential segregation / neighborhood segregation / spatial segregation 合成一个概念 —— 这三个归一化之后是三个不同的 key，实际上是同一件事。

顺序不是随便排的 —— 后面的阶段要吃前面的产物，keywords 需要 OpenAlex 缓存，而所有 图谱阶段都必须排在 build 前面：

setup → ingest → mcp → citations fetch → citations build
      → graph seed → graph extract → keywords load → semantic entities
      → graph build → graph summarize

docs 和 entities 的阈值不能互换。 文档相似度整体比短语相似度高得多：论文的 top-10 近邻中位数是 0.886，所以 0.55 这个下限基本等于全留（每篇 10 条边，包括一本 历史社会学专著紧挨着一篇 LLM benchmark 论文）。默认的 0.90 给出每篇 3.5 条边。 在相信任何一个阈值之前，先看看分布。

8F.7 它存在哪里

~/.claude/scholar-rag/                      （用 $SCHOLAR_RAG_DIR 覆盖）
├── corpus.sqlite       ← 文档 + 块清单（status 的唯一真相来源）
├── raw/text/<doc_id>.json   ← 按页映射的抽取文本（缓存；使重新切块成为可能）
├── raw/meta/<doc_id>.json   ← 完整书目记录
├── index/              ← LanceDB 表 `chunks`（向量 + 元数据 + BM25 全文索引）
├── graph/              ← 实体、关系、文档边、社区、摘要
├── manifest.json       ← embedding 模型 + 维度 + 切块参数 + 构建统计
├── logs/               ← trace-scholar-rag.ndjson、ingest-run-*.log
└── .venv/              ← 自包含的 CPython 3.12

它是用户级的，不是项目级的 —— 同一个库服务于每一个项目，和 scholar-knowledge 完全一样。这是对的：文献库是研究者的属性，不是某一篇论文的属性。

回到 §8C 的反馈回路。 抽取是两个技能里都最贵的那一步，而现在只有一个需要付这笔钱。构建跑完之后跑一次 /scholar-knowledge re-extract：那些只从摘要 ingest 进来的节点，可以用 scholar-rag 已经抽好的全文升级。索引一次文献库，wiki 就白白变深一层。

配置全部通过 .env 或环境变量：SCHOLAR_RAG_DIR · SCHOLAR_ZOTERO_DIR（自动探测）· EMBED_MODEL（默认 BAAI/bge-m3）· RAG_CHUNK_CHARS / RAG_CHUNK_OVERLAP · RAG_GRAPH_MODEL / RAG_SUMMARY_MODEL · RAG_OCR_MODEL · OLLAMA_HOST。

8F.8 检查

$ rag_py ingest.py status      # 按阶段统计文档、块数、no_pdf 覆盖
$ rag_py graphrag.py status    # 实体 / 关系 / 社区 / 摘要

信任它之前查四件事：

1. setup-venv.sh 报告每一个 import 都 ok，并告诉你 torch 有没有 MPS。（没有 MPS 意味着构建慢得多 —— 据此安排时间。）
2. ingest.py status 显示 embedded > 0，并且 no_pdf 数目合理。no_pdf 一大片，说明那些 Zotero 条目的附件从没同步到本地；去 Zotero 里修，或者让开放获取抓取去补。
3. 拿一个你熟悉的主题查一下，返回的是你预期的那篇论文，作者-年份对，页码你能翻过去核对。
4. MCP 握手列出全部四个工具。一个都没列出，说明你没重启会话。

数据安全。 语料是已发表论文，通常是 CLEARED。但 folder 模式会毫不犹豫地 ingest 一整个装着未发表草稿或同事共享 PDF 的目录。如果项目 sidecar 把任何输入标成 NEEDS_REVIEW 或 HALTED，先走 /scholar-safety 或 /scholar-init（§6）—— embedding 在本地跑，并不等于 ingest 不需要授权。

9. scholar-design —— 数据之前先有设计

目标： 锁住估计对象、模型阶梯、样本限制、禁止语言。本节之后，分析脚本基本就是模板填空。

这是整套技能里最大的一条（指令约 16,000 字），也是最值得你在敲键盘之前先读一遍它的分派表的一条。

argument-hint: "[quant|qual|mixed|experiment|power|methods-section|pap|
                computational|NLP|ML|network|ABM|premortem|blueprint]
                [research question] [optional: data source, design type,
                journal target]"

9.0 十六种设计模式

> /scholar-design quant "did hukou/cohort gaps in internet access narrow while
                  use-hours gaps persisted?" CFPS 2010-2020 "Social Forces"
                  descriptive/decomposition
> /scholar-design power "MDES for a 2,000-respondent survey experiment"
> /scholar-design computational NLP "polarization in news coverage with BERT"
                  "Science Advances"
> /scholar-design premortem digital-divide-china-cfps
> /scholar-design blueprint digital-divide-china-cfps

9.1 十二个步骤

Step 0 —— 建场。 推导项目根目录、打开 RAO 追踪、和你确认 RQ、数据约束、目标期刊。

Step 1 —— 设计选择决策树。 一张十四行的表，把（目标 × 数据结构 × 分配机制）映射到推荐设计与期刊匹配度。任何 DiD / FE / RD / IV / matching / 中介 / 自然实验主张都会触发因果关卡，交给 /scholar-causal（§8D），带着一个识别策略回来。

Step 1.5 —— 多重比较政策声明。 只要某个预注册假设族带 K ≥ 3 个检验，这一步就是强制的。它产出一个 YAML 块，写明族名、K、校正方法、alpha 和判定规则 —— 并且它让 peer-reviewer-demographics 成为后续每一次评审面板的必需成员。

这一步为什么存在。 本语料里一次真实运行（cohab-fertility-cfps）对一个九检验的族给出了 “PARTIAL support”，而没有做任何校正。在设计阶段——在你看到任何一个 p 值之前——就把校正方法声明出来，是这件事唯一不算 p-hacking 的版本。

Step 1.6 —— 数据源要求。 产出一个 ## Data-Source Requirements YAML 块（unit_of_analysis、geographic_scope、time_window、design_structure、required_n、required_constructs[]、excluded_designs[]），供 scholar-data（§9A）拿去给候选数据集打分。

Step 2 —— 实验设计模块。 七个子模块，每个都带设计模板、R 分析代码、假设检查清单和写作模板：2a RCT · 2b 调查/情景实验 · 2c list experiment · 2d 整群 RCT · 2e 审计/通信实验 · 2f 阶梯楔形 · 2g SMART。

Step 3 —— 功效分析。 十一个子模块：

用二手数据时你的 N 是固定的，所以 3c 才是诚实的那一步：你不是在选样本量，你是在报告你这个固定样本本来能探测到的最小效应。

Step 4 —— 变量说明。 变量字典表（角色 · 名称 · 构念 · 操作化 · 来源 · 类型 · 取值范围 · 备注）、一份测量效度检查清单，以及一张 DAG 草图。

Step 5 —— 分析策略。 按结果变量类型选模型；标准误与聚类的选择；呈现顺序（Model 1→4 加附录稳健性）。注意技能强制执行的那条社会学期刊规则：在 ASR/AJS 这类刊物上，任何二值、有序或 GLMM 结果一律报告平均边际效应，不报 odds ratio，也不报原始 log-odds。

Step 6 —— 稳健性计划。 一份预先承诺的敏感性登记表。每一条到分析阶段都变成阻塞项，除非标了 optional: true 并给出理由。局限章节里写一条 bullet 不能满足这道关卡 —— 只有后来真的出现在 spec 登记表里的 spec_id 才算。

Step 7 —— 预分析计划。 十个部分 —— RQ 与假设、设计、主要结果变量、协变量、主分析、亚组/异质性、稳健性、多重比较校正、偏离政策、样本量 —— 外加一份 OSF 注册检查清单。

Step 8 —— 写 Data and Methods 章节，按目标期刊的字数预算和结构来校准。

Step 9 —— 计算方法设计。 主张类型分类法（测量 / 描述 / 预测 / 因果）；语料与抽样设计，带各方法的最小 N 对照表；标注设计，带代码本模板和评分者间信度目标（κ ≥ 0.70 为底线，≥ 0.80 更好，另加 Krippendorff’s α 与 ICC）；训练/测试/验证集划分及 no-peek 规则；预先指定的评估指标；网络边界界定与 ERGM/SAOM 数据要求；ODD 协议下的 ABM 设计，配 SALib Sobol/Morris 敏感性分析。

Step 10 —— 贝叶斯设计。 先验引出、brms 拟合、收敛诊断、贝叶斯样本量与 assurance、报告模板。

9.2 design/ 里会出现什么

来自真实 CFPS 运行 —— 注意其中一部分由 scholar-design 写，另一部分由编排器后续阶段写，这就是这个文件夹会不断累积的原因：

design/
├── design-blueprint-digital-divide-china-cfps-2026-05-04.md  ← scholar-design
├── data-blueprint-digital-divide-china-cfps-2026-05-04.md    ← scholar-data
├── pre-mortem-quant-2026-05-04.md                            ← Step 11 面板
├── pre-mortem-demographics-2026-05-04.md
├── pre-mortem-senior-2026-05-04.md
├── limitations-accepted.md         ← 你接受下来的 RED 维度，附理由
├── variable-dictionary.csv
├── model-specs.json
├── coef-map.csv
├── test-inventory.json
├── project-brief.md
└── results-lock-2026-05-04.md      ← 后来才写，在结果锁定阶段

9.3 估计对象与模型阶梯（真实蓝图节选）

## 0. Headline finding (locked at Phase 3.5)

This design commits to Y2 (weekly hours of internet use among users) as the
focal outcome for the headline table and abstract sentence.

> Net of education, income, occupation, household composition, and
> province × wave fixed effects, the rural-hukou penalty on weekly internet
> hours among Chinese adults who use the internet (Y2) in 2018 is
> statistically indistinguishable from the penalty in 2014 — Y2 being
> measured only in CFPS waves 2014, 2016, and 2018 — even as the binary
> access gap (Y1, observed across CFPS 2010–2020) closed from approximately
> 40 to 15 percentage points between 2010 and 2020 […].

## 1.1 Estimation strategies in correspondence with hypotheses

| H  | Estimator                       | Identifying assumption                |
|----|---------------------------------|---------------------------------------|
| H1 | Logit (Y1) + OLS with province×    | Conditional indep. of hukou and       |
|    | wave FE on Y2|Y1=1                 | unmeasured infra within province×wave |
|    | (Tobit MLE cross-check in          | (cross-check adds censoring + tail-   |
|    | robustness section)                | distribution assumptions)             |
| H2 | Person FE within-changes;       | HAPC: cohort & period exchangeable    |
|    | HAPC; Deaton-Paxson bounds      | given age                             |
| H3 | Three-way interaction;          | Common support; linearity within      |
|    | threefold Oaxaca-Blinder        | group                                 |
| H4 | Person FE on co-residence       | No third unmeasured time-varying      |
|    | changers                        | confounder                            |

## 1.3 What we explicitly do NOT claim
- No causal interpretation of hukou
- No causal interpretation of cohort
- No third-level (returns) claim in this paper

这份蓝图里有一行是承重的，而且很容易一眼扫过去：

outcome_mechanism_alignment: prevalence-stock

允许的取值是 entry-process、prevalence-stock、dissolution、multi-state。这一行缺失，设计验证就不通过。 它之所以存在，是因为 2026 年 4 月的一次审计发现有个设计把进入过程的机制故事套在了存量流行率的结果变量上 —— 一个无声的错配，产出的论文听起来自洽，回答的却是数据根本处理不了的问题。

9.4 Step 11 —— pre-mortem 评审组

scholar-design 在任何数据被读取之前就派出一个同行评审面板。名单由设计类型决定：

每位评审对十三个维度打 RED / YELLOW / GREEN 并给理由：RQ 清晰度 · 理论↔假设衔接 · 操作化效度 · 识别策略 · 样本充分性 · 内部效度 · 外部效度 · 伦理 · 测量与缺失 · 分析计划具体度 · 可行性 · 期刊匹配 · 多重比较政策。每份备忘以 OVERALL:、TOP-3 FATAL CONCERNS:、RECOMMENDED ACTIONS: 收尾。

面板必派，但裁决是建议性的：你逐条接受或修改每个 RED 维度，最多 3 轮，design-review-check.sh 会因任何未接受的 RED 而拦住下一阶段。退出码：0 GREEN 放行，1 RED 未接受 → 停，2 YELLOW → 经批准可继续。三轮之后硬停，理由是：持续的 RED 是结构性设计问题，需要人的判断，不是再来一轮自动批判。

溯源要求 —— 这一条是最该刻进脑子里的。 每份 pre-mortem 备忘都必须带一张评审溯源表，列是实打实的：reviewer_agent | task_invocation_id | dispatched_at | model。写 TBD 或 — 这种占位符一律不过关，而且 design-review-check.sh 会交叉检查过程日志里是不是零次 peer-reviewer-* 派发。技能把「内联扮演的评审」—— 模型用自己的口气写一份“评审”，而不是真的派出子智能体 —— 点名为整条流水线的头号无声失败。一次事后复盘把大约 71% 的手稿缺陷追溯到了被跳过或被伪造的评审。§13 的代跑披露就是同一个失败模式，被抓到并声明出来的版本。

我们这次实际运行中，senior 评审标出：“Y1（接入二值）不该是 headline 结果。Y2（使用强度）才是理论上真正独特的贡献，应该作为摘要句的焦点。” 这一条评论在任何分析跑起来之前就改掉了焦点结果，省掉一整轮修改。

9.5 Step 12 —— 章节蓝图

跑得很晚 —— 在结果锁定之后、动笔之前 —— 值得注意的是它是确定性的：generate-section-blueprint.sh 读取结果锁定、设计蓝图和假设，产出这份契约，整个过程没有 LLM 参与。写作技能没法跟它讨价还价。

> /scholar-design blueprint digital-divide-china-cfps

写出 drafts/section-blueprint.json（权威版本，schema v5），外加一份人类可读的 .md 陪同件，页脚写得很实在：“Hand-edits will be overwritten.”

逐章节 —— abstract、introduction、theory、methods、results、discussion —— 契约携带 target_words_min/max、required_hypotheses[]、required_tokens[]、reader_outcomes[]、exemplar_paths[]、derived_moves、structural_moves[] 和 forbidden_patterns[]。这些字段处在一条 scholar-write 必须服从的优先级阶梯上：

退出码：0 GREEN（JSON 与 MD 已写出），1 RED（缺 results-locked/LATEST.txt、清单或设计蓝图）。下游的 blueprint-completeness-check.sh 会在允许动笔之前重新校验 schema。

9.6 检查

• limitations-accepted.md —— 你接受下来的每一个 RED，格式是 [RED-N: dimension] rationale。如果这个文件是空的而面板确实提了 RED，说明有东西被放水过去了。
• model-specs.json —— 焦点结果、焦点表、焦点样本。
• pre-mortem 备忘 —— 读每一份的 TOP-3 FATAL CONCERNS，并检查溯源表里是不是真的 invocation ID。
• outcome_mechanism_alignment 那一行 —— 机制故事和结果变量类型对得上吗？

自检： 不看资料，说出焦点结果、焦点表、焦点样本。然后说出设计里写明你不可以做的一条主张。两件事做不到，就别往下走。

9A. scholar-data —— 找数据、取数据、管数据

目标： 找到真正契合设计的数据集，能下就下下来，并产出流水线后续环节默认已经存在的变量字典、IRB 材料与数据管理计划。

CFPS 演练里看不见这个技能，因为我们是带着数据来的。但对大多数从新项目起步的参与者来说，它是整套技能里最有用的一个：它内置 14 大类、100+ 个数据集的目录，其中 57 个可机器评分，42 个能自动下载。

argument-hint: "[dataset|survey|interview|irb|manage|vignette|scrape|web|api|
                social media] [topic or research question]
                [optional: population, journal, design]"

9A.1 八条工作流

> /scholar-data dataset "童年贫困与成年健康" US NHB
> /scholar-data survey "种族与犯罪记录带来的招聘歧视" vignette
> /scholar-data irb "抓取移民政策相关的公开推文"
> /scholar-data manage "为 NSF 申请书准备代码本与 DMP"

9A.2 数据集目录

十四大类，每一类都是一张数据集表格，列出覆盖范围、分析单位、N、关键变量与获取层级：

1. 社会学 / 分层 / 劳动力市场 —— GSS, PSID, NLSY79/97, Add Health, SIPP, ACS, CPS
2. 人口学 / 家庭 / 健康 —— HRS, NHANES, NHIS, NCHS Vital Statistics, CDC PLACES, UN World Population Prospects
3. 教育 —— NELS/ELS/HSLS, NAEP, College Scorecard, IPEDS
4. 政治行为 —— ANES, CCES, Pew datasets
5. 移民 / 族群 / 语言 —— CPS-ASEC, New Immigrant Survey, ISSP, WVS/EVS, Luxembourg Income Study
6. 社区 / 空间 / 行政 —— Census tract, HMDA, TIGER/Line, HOLC redlining maps, Opportunity Atlas
7. 文本 / 数字 / 计算 —— Congressional Record, Common Crawl, Google Trends, Twitter/X historical
8. 犯罪与刑事司法 —— NCVS, UCR/NIBRS, NSDUH, NCRP, Sentencing Commission
9. 国际调查 —— WVS/EVS, ISSP, ESS, Eurobarometer, Afrobarometer, Latinobarómetro, Asian Barometer, LIS/LWS, PISA, TIMSS/PIRLS, DHS, MICS
10. 经济 / 劳动 / 宏观 —— FRED, Penn World Table, EU-KLEMS, LEHD, OECD, Eurostat, ILO
11. 全球健康 / 环境 —— WHO GHO, Global Burden of Disease, IPUMS International, NASA SEDAC, FAOSTAT
12. 科学学 —— OpenAlex, Semantic Scholar, Dimensions, ORCID, NSF SED, Crossref, Web of Science
13. 通用数据仓库 —— Harvard Dataverse, ICPSR, Zenodo, OSF, Figshare, QDR, Roper iPoll, Data.gov, UK Data Service, GESIS, Google Dataset Search, Kaggle
14. 受限联邦 / 链接数据 —— 经 FSRDC 的 SSA 收入数据、IRS/Treasury 链接微观数据、州行政记录、CMS claims

另有一份国际／纵向补充清单：UKHLS、German SOEP、IHDS、CFPS、EVS、UK Biobank、Fragile Families。

9A.3 数据集评分器：一条推荐究竟怎么来的

Step 0c.5 跑的是一个确定性的 Python 评分器，不是凭感觉：

$ python3 scripts/gates/dataset-suggester.py "$PROJ" --top 3 --auto

它读 design/data-requirements.yml（scholar-design Step 1.6 产出的那份 YAML），读不到就退回蓝图，再退回 project-state.md，然后给 references/datasets-index.json 里每一条打分——57 个数据集，字段包括 unit_of_analysis、geographic_scope、time_window、design_structure、key_constructs[]、access_tier、auto_fetch{}。

决策规则：≥ 6.0 自动选中 · < 6.0 需要你确认 · 没有任何候选通过硬过滤则以 3 退出——这时编排器必须回过头来请你放宽某个约束，或者往目录里补一个数据集。此外还有一个自带数据审计模式：如果你带了自己的数据集，而目录里有比它得分更高的，你会收到一条 YELLOW 提示，明白告诉你这件事。

9A.4 自动取数

Step 0d 会对所有处在「Immediate」获取层级的数据做真实下载——18 个走 R 包，24 个走直链。完全不需要 key 的来源（因此也是跑通一个项目最快的路径）：World Bank、NHANES、CDC PLACES、GSS、Google Trends、BLS v1、College Scorecard、Opportunity Atlas、GDELT、OpenAlex、Eurostat、WHO GHO、Penn World Table、FAOSTAT、Harvard Dataverse、Zenodo、Semantic Scholar、Crossref、Data.gov。

你可能需要的 key 与注册：

把它们存进 .Renviron 或 .env，两者都要 gitignore。绝不要写进脚本。

取数成功后，技能会写出 data/raw/download-manifest.md（File · Source · Date fetched · N rows · Variables），并把 PROJECT STATE 从 data-status: no-data 翻成 existing-data，从而解锁下游的「有数据」模式。如果缺某个 API key，技能被要求主动向你索要，而不是悄悄降级成一段代码模板。

9A.5 工作流 7：真正要紧的网络数据规则

法律与伦理框架排在任何代码之前：robots.txt、服务条款、速率限制、CFAA、GDPR、IRB。网络数据的 IRB 判定表把公开推文映射为 Exempt，Reddit 映射为 Exempt/Expedited，私密群组映射为 Full board。总的原则是技能里引用的 AoIR 2019：法律上可获取 ≠ 伦理上可使用。

技能记录下来的平台现实（截至本次构建）：

• Twitter/X —— Academic Research 通道已于 2025 年 1 月停用。全档案检索现在需要 Pro（约每月 5,000 美元）或 Enterprise；免费的 Basic 层每月上限 10,000 条推文读取。新项目可以考虑 Bluesky（AT Protocol，免费 firehose）或 Meta Content Library。
• Reddit —— Pushshift 档案获取在 2023 年被限制；改用 PRAW 打实时 API。
• 绝不要分享原始推文文本。 只分享推文 ID。

API 优先的顺序是：平台 API → GDELT / MediaCloud / Internet Archive → rvest + polite（R）或 requests + BeautifulSoup（Python）→ JavaScript 页面用 chromote / playwright。所有动作都记进 docs/scraping-log.md，含 robots.txt 状态、ToS 审阅、IRB 判定、限速与记录数。

9A.6 写出的文件

output/<slug>/data/scholar-data-<topic>-<date>.md   ← 数据计划
<proj>/data/dataset-selection.json                  ← 评分器输出 + 取数参数
data/raw/download-manifest.md                       ← 取了什么、什么时候取的
data/raw/<source>-<params>.{rds,csv,parquet}        ← 真正的数据
data/codebooks/                                     ← var_name | var_label | type |
                                                       values | missing_codes | source
docs/scraping-log.md · docs/data_cleaning_log.md
.gitignore                                          ← 排除原始数据与凭证

目录脚手架会把 data/raw/ 设成只读（chmod -w）。原始数据是输入，永远不是输出。

9A.7 坑

• scholar-data 是 Tier B 技能：它会检查安全 sidecar，但没有实现完整的 LOCAL_MODE 分派契约。LOCAL_MODE 的文件必须改走 /scholar-analyze 或 /scholar-eda。
• 列表实验（list experiment）统计效率低——每臂按 N ≥ 500 规划。
• 联合分析（conjoint）设计要检出 0.05 的 AMCE，大致需要 N ≥ 500 × 5 个任务。
• 概率性记录链接（fastLink）必须报告匹配率，并刻画匹配上与没匹配上的案例特征；选择性链接本身就是一种效度威胁。

自检： 拿你自己的研究问题跑一次 /scholar-data dataset。看看得分最高的三个候选和分数拆解。如果最高分不到 6.0，诚实的读法是：你的设计与现有数据还没对上——现在就修，别拖到 Phase 5。

10. scholar-eda —— 上模型之前先看清楚

目标： 建分析样本、诊断缺失、做出 Table 1、检查分布假设——在跑任何模型之前。

argument-hint: "[dataset path or 'paste data below'] [outcome variable(s)]
                [optional: key predictor, causal design, journal,
                panel/cross-sectional]"

10.1 运行

> /scholar-eda data/processed/cfps-panel-long.rds
              outcomes=y1_access,y2_hours,y3_breadth
              focal=hukou_rural,cohort,female,eduy
              panel
              journal="Social Forces"

覆盖三种输入模式的更多例子：

> /scholar-eda data/gss2022.dta happiness education income
> /scholar-eda NHANES 2017-2018 systolic_bp age race cross-sectional
> /scholar-eda paste data below wage education, tenure for ASR panel

10.2 三种输入模式，以及挡在它们前面的那道关卡

在这一切之前，Phase 0a——数据安全关卡会对每一个输入跑 safety-scan.sh，设定 SAFETY_STATUS，遇 YELLOW 或 RED 就卡住等你决定。如果 scholar-full-paper 已经在 Phase −1 设过状态，scholar-eda 继承它，且绝不下调。

Phase 0c 是因果关卡。 技能会扫描你的提示词里有没有 DiD、difference-in-differences、FE、RD、regression discontinuity、IV、instrumental variable、matching、synthetic control、mediation、propensity score。命中就打印一条跳转到 /scholar-causal（§8D）的提示，然后再从 Phase 1 继续。这是建议性的，不是硬停——但接受这个跳转几乎总是对的，因为协变量的选择取决于 DAG。

10.3 十一个阶段