psyclaw 0.29.18 → 0.29.19

package/docs/PsyClaw/344/275/277/347/224/250/347/231/275/347/232/256/344/271/246_v0.29.15.md

@@ -0,0 +1,907 @@
+# PsyClaw 使用白皮书
+
+**版本：v0.29.15**
+**发布日期：2026-09-08**
+**适用对象：社会科学研究者、教师和研究助理**
+
+PsyClaw
+
+社会科学研究智能体：用自然语言推进项目，留下可复现的分析、证据与人审记录
+
+—— 面向心理学、教育学、社会学及相关领域的研究者 ——
+
+可复现研究实践 · 证据可追溯 · 人工判断优先
+
+2026 年 9 月 · v0.29.15 版
+
+# 关于本白皮书
+
+本白皮书写给心理学、教育学、社会学及相关行为科学领域的研究者——包括研究生、青年教师、研究助理与课题负责人。读完之后，你应能独立完成：建仓、摸底数据、确认分析方案、委托可复现脚本、完成 AI 核查与人审、交接写作并推进初稿。
+
+**你将学到**：如何用自然语言指挥从「研究问题」到「可审计产物」的主路径；三种模式各自解决什么；按任务选用斜杠命令；以及如何用人审把关，让合作者六个月后仍能读懂同一条证据链。
+
+我们假定你熟悉常见研究设计与统计概念（相关、回归、组间比较、信度、效应量等），日常可能使用 SPSS、JASP、Excel、RStudio 或 Python，但不希望把「写代码」变成主业。阅读本白皮书不需要系统修习 TypeScript。
+
+宜将 PsyClaw 视为能力较强、执行较快、但须明确指令与例行检查的研究助理：你是课题负责人（PI），它是研究助理（RA）。统计数值由成熟外部库或受信任的模型上下文协议服务（MCP）计算；PsyClaw 负责组织过程、保存脚本与环境信息、推动核验，并在关键节点请你把关。模型会出错，且常以过高置信度呈现错误——因此「AI 产出必须核验」是默认工作方式，也是你获得可靠交付物的途径。
+
+### 如何使用本白皮书
+
+第一章：先建立「你现在能完成什么」的心智图——首次使用前建议通读。
+
+第二章：安装、登录与五分钟第一次对话——动手前必读。
+
+第三章：项目目录与三种模式——搭建项目时必读。
+
+第四章：斜杠命令按任务查阅——进行分析与定稿前重点看 `/plan`、`/handoff`、`/crosscheck`、`/verify`、`/ars`。
+
+第五章：四条可照做的端到端工作流——按任务类型择一跟做。
+
+第六章与第七章：人审节奏与证据规范——正式研究建议通读。
+
+第八章：排错与常见问题——遇到阻碍时查阅。
+
+附录：命令速查、提示词模板、目录约定与极短边界速览，供日常翻用。
+
+斜杠命令采用 Codex 风格：**单独命令**，或**命令 + 尾随自由文本**。确认方法用自然语言「可以」；人审在 Panel「核实」或唤醒选项中完成。
+
+文中「研究者可说」示例可直接改写后粘贴进 PsyClaw。
+
+# 执行摘要
+
+你现在可以：用自然语言指挥一项社会科学研究从建仓走到可审计交接；把方案、脚本、结果、核验清单与人审决定留在本地项目里——六个月后仍能回溯同一条证据链，更换数据后也能重跑。
+
+PsyClaw 与普通网页聊天机器人的差别在于：它在研究项目目录中工作——读取约定路径下的材料、起草并委托分析脚本、记录核对状态、将分析交接至写作模式。你的角色由「操作软件的人」转变为「指挥并审核助理的人」。
+
+全流程一览：
+
+1. **建仓与摸底**：`/init` 或 `/init <目标>` 建立目录与 `psyclaw.md`；原始数据放入 `data/raw/`（只读）。
+2. **澄清与方案**：`Shift+Tab` 进入 analysis；`/plan` 查看方案，或 `/plan <目标>` 创建方案。回复「可以」确认方法，再用自然语言请它生成并运行脚本。
+3. **委托与复现**：统计在本地成熟库或受信任 MCP 中完成；脚本落在 `analysis/scripts/`，结果落在 `analysis/results/`。
+4. **AI 核查与人审**：先 `/crosscheck`（过程：数据/引文存在/格式），再 `/verify`（实质：结果是否成立、方法与引文是否合理）；然后在 Panel「核实」或唤醒选项中完成人审。
+5. **交接与写作**：人审通过后 `/handoff` 写入 `analysis/HANDOFF.md`，再切到 academic；可用自然语言或 `/ars` 推进文献与初稿；定稿前再次两道 AI 核查 + 人审。
+6. **加压与评审**：定方案前用 `/brainstorm` / `/grill`；定稿前用 `/review` 收集模拟评审意见。
+
+读完本白皮书，你应能按第五章配方跑通至少一条完整工作流，并知道何时打开 Panel 完成人审。对课题组而言，这意味着：新人可按同一配方接手项目；合作者可对照 `analysis/scripts/`、`analysis/results/` 与 `HANDOFF.md` 复核；写作阶段有明确的数字来源，而不是聊天窗口里散落的截图。
+
+# 目录
+
+关于本白皮书
+
+执行摘要
+
+目录
+
+第一章　认识 PsyClaw：它能帮你完成什么
+
+第二章　安装与第一次运行
+
+第三章　项目结构与三种模式
+
+第四章　斜杠命令：按任务能做什么
+
+第五章　四条可复现工作流
+
+第六章　Panel 与人审核验
+
+第七章　证据与研究规范
+
+第八章　常见问题与排错
+
+附录 A　斜杠命令速查表
+
+附录 B　可复制提示词模板
+
+附录 C　项目目录约定
+
+附录 D　边界速览（选读）
+
+# 第一章　认识 PsyClaw：它能帮你完成什么
+
+## 1.1 你现在可以完成的事
+
+PsyClaw 0.29.15 是面向社会科学的研究智能体。安装并建仓之后，你通常可以做到：
+
+- **把研究问题变成可检查的项目**：目录、项目说明书、分析方案与进度都留在本地。
+- **用对话完成摸底与方案确认**：先看清数据与缺口，再确认主分析与敏感性分析。
+- **委托可复现脚本而非口头数字**：脚本、结果、表图路径可审、可重跑。
+- **分两层核查再定稿**：过程核对（表文、引文存在、格式）与实质验证（结果与解释是否站得住），再由你亲自核实。
+- **合法交接写作**：人审通过后生成 `analysis/HANDOFF.md`，在学术模式基于已有结果写结果部分与引言骨架。
+- **在动数据前加压、在定稿前模拟评审**：暴露混淆、过度声称与引文支撑缺口。
+
+捆绑的学术研究技能（Academic Research Skills，简称 ARS，以及 Nature / compose、analysis-plan、academic-grill 等）已随 npm 包提供，日常用自然语言即可触发，不必再单独安装。可选增强包括学者/期刊风格蒸馏（`distill-scholar` / `distill-journal`）与浏览器辅助文献（推荐目录中的 Kimi WebBridge）。
+
+典型使用场景举例：
+
+| 你想做的事 | 建议路径 |
+|---|---|
+| 问卷相关/回归，控制协变量 | analysis：`/plan` → 确认「可以」→ 脚本执行 → 两道核查 → 人审 → `/handoff` |
+| 动数据前打磨研究问题 | chat/analysis：`/brainstorm` → `/grill` → 再定 `/plan` |
+| 已有结果，写结果部分与引言 | academic：读 `HANDOFF.md`；自然语言或 `/ars` 推进；定稿前再核查 |
+| 投稿前找表述漏洞 | academic：`/review` → 挑必改项 → `/crosscheck` + `/verify` → 人审 |
+
+## 1.2 为什么值得用
+
+**可复现性落到脚本。** 半年后若需增加一个协变量，菜单记忆很难精确重现；脚本化分析通常只需改一行并重跑。PsyClaw 把「写脚本」的门槛降到对话，同时把脚本与结果留在约定路径——合作者打开项目即可对照。
+
+**机械劳动结构化。** 清理规则披露、方案确认、表文对照、引文字段核验、交接清单——这些耗时步骤被组织进同一工作流，你的时间可更多花在设计、解释与伦理判断上。对 RA 而言，这意味着「下一步该做什么」有清晰配方，而不是每次从零聊天。
+
+**完成标准可见。** 模型口头「已经核对」不够；核对清单、AI 核查状态与人审记录留在项目中，交接与定稿有明确门禁。你因此能回答审稿人或导师：「数字从哪份脚本来、谁核实过、还缺什么」。
+
+**写作与分析解耦但可衔接。** analysis 负责可运行结果与交接；academic 基于交接写稿。缺数字时切回补算，写作阶段专注叙事与文献支撑，减少「边写边改主方法」的混乱。
+
+## 1.3 心智模型：你是 PI，它是研究助理
+
+适宜的协作方式，是把它当作刚入组的高能力 RA：执行迅速、适于重复劳动、能按规范落盘；但对隐性约定了解有限，需要清晰指令与例行检查。四条实用原则：
+
+1. **指令具体。** 「分析一下数据」含糊；「用独立样本 t 检验比较两组抑郁得分，报告效应量与 95% CI，脚本写入 analysis/scripts/」可操作。
+2. **背景写入 `psyclaw.md`。** 设计、变量含义、缺失编码、报告规范写清楚后，每次会话可少解释一遍。
+3. **关键节点亲自把关。** 方法确认、主结果数字、引文与因果表述、导出/投稿意图——这些由你决定。
+4. **偏离就纠正并固化规则。** 发现反复错误时，请它把规则写回 `psyclaw.md`。
+
+把任务想成布置给 RA 的工单，往往比「随便聊聊」更快得到可用产物：说明输入路径、估计目标、输出位置与报告规范，再让它执行与自检。
+
+# 第二章　安装与第一次运行
+
+## 2.1 环境要求
+
+需要 Node.js `>=22.19.0`。在终端运行：
+
+```bash
+node --version
+```
+
+版本号应显示 22.19.0 或更高。支持 macOS、Windows 与 Linux。统计计算还需要本机或 MCP 侧具备相应引擎（如 Python/R）；不确定时可在启动后直接请 PsyClaw 协助检查。
+
+## 2.2 安装
+
+官方 npm 源：
+
+```bash
+npm install -g psyclaw@0.29.15
+```
+
+若本机 npm registry 配置异常，可显式指定官方源：
+
+```bash
+npm install -g psyclaw@0.29.15 --registry=https://registry.npmjs.org/
+```
+
+中国大陆网络较慢时：
+
+```bash
+npm install -g psyclaw@0.29.15 --registry=https://registry.npmmirror.com
+```
+
+确认入口：
+
+```bash
+psyclaw --help
+psyclaw
+```
+
+首次启动会引导配置模型服务。模型与凭据保存在用户侧配置目录（`~/.psyclaw/agent`）。请把 API Key 留在本地认证配置中，不要写进命令参数、项目文件或聊天导出。
+
+## 2.3 创建第一个项目
+
+每项研究使用独立目录：
+
+```bash
+mkdir social-support-study
+cd social-support-study
+psyclaw init "社会支持与研究生心理健康的关系" --paradigm survey-observational
+psyclaw
+```
+
+也可以先进入对话再初始化：
+
+```text
+/init 社会支持与研究生心理健康的关系
+```
+
+你会得到：约定工作区目录、根目录 `psyclaw.md` 与 `.psyclaw/` 状态目录。正式分析交接与定稿建议先建仓。
+
+## 2.4 五分钟上手：第一次对话
+
+假定练习数据已放入 `data/raw/`（真实被试数据请先完成伦理与去标识要求），可以说：
+
+```text
+请先不要修改任何文件，只做三件事：
+1. 描述 data/raw/ 里这份数据的规模与变量名猜测；
+2. 指出异常或缺失模式；
+3. 列出澄清研究问题前还缺什么信息。
+不要编造统计结果。
+```
+
+期望得到：数据概况、待澄清问题列表；此时尚无虚构的 p 值或效应量。
+
+当系统弹出「唤醒选项」或核对清单时，优先在弹窗中选择；也可以输入编号、选项名或自然语言。回应会被记录。
+
+快捷键：
+
+- `Shift+Tab`：在 chat → analysis → academic 间循环切换模式。
+- `Ctrl+Shift+T`：调整思考深度（多数终端比 Ctrl+Shift+Tab 更可靠）。
+
+续接会话：
+
+```bash
+psyclaw --continue
+# 或
+psyclaw -c
+```
+
+可选：启动时持续推进（非模式切换）：
+
+```bash
+psyclaw --continuously-work
+```
+
+该标志仅在 CLI 启动时生效。它会自动推进工作；日常正式研究更推荐手动逐步确认，以便控制质量与 token 消耗。
+
+# 第三章　项目结构与三种模式
+
+## 3.1 标准目录：你得到什么
+
+`/init` 之后，材料按生命周期落位。面向研究者的常用布局：
+
+```text
+my-study/
+├── psyclaw.md                 # 项目说明书：背景、码本要点、规范
+├── data/
+│   ├── raw/                   # 原始数据：只读保护区
+│   └── clean/                 # 经确认的派生/清洗数据
+├── analysis/
+│   ├── scripts/               # 可复现分析脚本（Python/R 等）
+│   ├── configs/               # 方案、变量字典、参数快照
+│   ├── results/               # 数值结果、表、机器可读摘要
+│   ├── outputs/               # 分析侧交付物
+│   ├── plans/                 # 分析方案记录
+│   └── HANDOFF.md             # analysis → academic 交接
+├── literature/pdfs/           # 合法取得并核验的全文 PDF
+├── paper/                     # 论文 Markdown 与导出意图产物
+├── notes/                     # 研究笔记与人工决策说明
+├── outputs/figures/           # 对用户交付的图（常含 PNG + 可编辑 SVG）
+└── .psyclaw/                  # 状态、证据、核对清单、运行与审计记录
+```
+
+你因此获得：原始数据可回溯、清洗可重跑、结果可对照脚本、写作可消费交接文件。清理、重编码、量表合成通过脚本写入 `data/clean/`，并保留输入关系——无论中间出现何种错误，都能从原始数据重新开始。
+
+实践上，建议养成「文件有家」的习惯：练习数据进 `data/raw/`；确认后的派生表进 `data/clean/`；可复现代码进 `analysis/scripts/`；表与机器可读摘要进 `analysis/results/`；对用户交付的图进 `outputs/figures/`；论文 Markdown 进 `paper/`。这样切会话、换电脑或交接给合作者时，路径约定仍然成立。
+
+兼容说明：部分新布局会把只读保护区放在 `.psyclaw/data/raw/`；旧项目根下的 `data/raw/` 仍兼容。日常示例优先使用 `data/raw/` / `data/clean/`。
+
+## 3.2 三种模式：各解决什么
+
+| 模式 | 你获得的能力 | 典型下一步 |
+|---|---|---|
+| chat | 轻量对话与资料整理，不强制研究流水线 | 摸底、澄清，或切到 analysis / academic |
+| analysis | 澄清 → 方案 → 脚本 → 两道 AI 核查 → 人审 → 报告 → 交接 | `/plan` → 自然语言执行 → `/crosscheck` → `/verify` → Panel → `/handoff` |
+| academic | 文献、初稿、格式、评审；定稿前再核查 + 人审 | 读 `HANDOFF.md` 写结果；`/ars` 或自然语言推进；`/review` |
+
+`Shift+Tab` 在三者间循环。analysis 优先产出可运行结果，再做人审；academic 消费 `analysis/HANDOFF.md` 与 `analysis/results/`——缺数字时切回 analysis 补算，而不是在写作模式重选主方法。
+
+如何选择：还在问「该不该做这项研究、设计有何风险」时，用 chat 或 analysis 的 `/brainstorm` / `/grill`；已经确定要跑数，就切到 analysis；已经有人审通过的交接，再切 academic 写稿。模式切换本身几乎零成本，真正节省时间的是「在正确模式里做正确的下一步」。
+
+## 3.3 `psyclaw.md` 写什么
+
+建议至少包含：研究概述与范式、数据说明与缺失编码、分析与报告规范（效应量、区间、探索/确证区分）、当前进度与遗留问题。写得越好，后续会话越少重复解释。每当纠正了助理的反复错误，可说一句「把这条规则写进 psyclaw.md」——这比在聊天里反复纠正同一类错误更省力。
+
+# 第四章　斜杠命令：按任务能做什么
+
+本章按研究者日常任务组织。每个命令给出：**能做什么**、**怎么用**、**你会得到什么**。斜杠表面为 Codex 风格：`/命令` 或 `/命令` + 尾随自由文本。
+
+小提示：方法确认用自然语言「可以」；人审只在 Panel「核实」或唤醒选项中完成。`/crosscheck` 管过程，`/verify` 管实质——二者分工不同。
+
+## 4.1 建仓：`/init [目标]`
+
+**能做什么**　搭建干净研究工作区：约定目录、`psyclaw.md` 与 `.psyclaw/` 状态目录。
+
+**怎么用**
+```text
+/init 睡眠质量与大学生学业倦怠的关系
+```
+命令行等价：
+```bash
+psyclaw init "睡眠质量与大学生学业倦怠的关系" --paradigm survey-observational
+```
+
+**你会得到什么**　可立即放入数据、开始摸底的脚手架；尾随文本成为研究目标记录。
+
+## 4.2 分析方案：`/plan [目标]`
+
+**能做什么**　查看或新建分析方案；创建时 soft-route 到捆绑的 analysis-plan 技能。
+
+**怎么用**
+```text
+/plan
+/plan 社交支持是否与心理健康相关，以及哪些变量可能解释这种关系
+```
+待确认时回复：
+```text
+可以
+```
+确认后再用自然语言执行，例如：
+```text
+请按已确认方案生成 analysis/scripts/ 下的可复现脚本并运行；结果写入 analysis/results/。不要发明数字。
+```
+
+**你会得到什么**　活跃 Plan 与可审的方法边界；单独 `/plan` 可随时查看状态。「可以」确认的是方法方案；分析完成后的人审仍走 Panel。
+
+## 4.3 分析交接：`/handoff`
+
+**能做什么**　人审通过后，把目标、完成项、限制与下一步写入 `analysis/HANDOFF.md`，作为 analysis → academic 交接真源之一。
+
+**怎么用**
+```text
+/handoff
+```
+
+**你会得到什么**　写作模式可直接消费的交接文件。若人审尚未完成，命令会提示你先到 Panel 核实。
+
+## 4.4 过程核对：`/crosscheck [焦点]`
+
+**能做什么**　过程性 AI 核对：数据/表格一致性、引文是否真实存在（如 DOI 可解析）、格式与报告要求、可复现痕迹。支持多视角合并。
+
+**怎么用**
+```text
+/crosscheck
+/crosscheck 主表与正文 N、效应量、CI 是否一致
+/crosscheck 引文 DOI 与参考文献字段
+```
+
+**你会得到什么**　相关清单项标记为 `ai-checked`，并标出无法核验之处。随后仍需 `/verify` 与人审，才能交接或定稿。
+
+## 4.5 实质验证：`/verify [焦点]`
+
+**能做什么**　实质性 AI 验证：结果是否站得住、引文是否足以支撑主张、方法是否匹配设计、解释边界是否过当。
+
+**怎么用**
+```text
+/verify
+/verify 主效应解释是否超出相关设计允许的边界
+/verify 引用是否支撑当前因果表述
+```
+
+**你会得到什么**　实质性问题清单与 AI 侧标记。定稿前建议顺序：先过程 `/crosscheck`，后实质 `/verify`，再人审。
+
+## 4.6 选题澄清：`/brainstorm [主题]`
+
+**能做什么**　显式启动研究方向头脑风暴：提出若干有理论意义、可回答的方向，比较价值与可行性，并推荐一个。
+
+**怎么用**
+```text
+/brainstorm 青少年社交媒体使用与睡眠
+```
+
+**你会得到什么**　可选方向、利弊比较与澄清问题——适合在写完整论文或跑主分析之前使用。
+
+## 4.7 方案加压：`/grill [主题]`
+
+**能做什么**　对研究问题、设计、方法与论证做逐题压力测试，暴露薄弱假设、混淆与过度声称。捆绑的 academic-grill 已随包提供。
+
+**怎么用**
+```text
+/grill 当前中介模型是否有反向因果与测量混淆风险
+```
+
+**你会得到什么**　尖锐问题与修订建议（默认不自动改稿）。研究者确认后，可将边界写回 `psyclaw.md` 或预注册笔记。
+
+## 4.8 模拟评审：`/review [说明]`
+
+**能做什么**　并发运行多角色模拟同行评审，收集结构化意见。
+
+**怎么用**
+```text
+/review
+/review 重点看方法与结果表述是否一致，以及因果语言是否过当
+```
+
+**你会得到什么**　可当作检查清单的评审意见；由你决定改哪些。通常需要已 `/init` 的项目。
+
+## 4.9 有界推进：`/loop [目标|stop]`
+
+**能做什么**　按计划有界推进当前研究阶段；需要停止时用 `/loop stop`。
+
+**怎么用**
+```text
+/loop
+/loop 完成主分析脚本与结果摘要
+/loop stop
+```
+
+**你会得到什么**　当前阶段的有界推进结果。若希望启动即持续推进，另见 `psyclaw --continuously-work`。
+
+## 4.10 科研工作台：`/panel [help]`
+
+**能做什么**　打开本地科研工作台：项目文件只读浏览、能力状态、核对清单、人审「核实」、配置与成本等视图。
+
+**怎么用**
+```text
+/panel
+/panel help
+```
+
+**你会得到什么**　可见的核对清单与人审入口——这是完成分析交接与学术定稿的主路径。
+
+## 4.11 使用速览：`/help`
+
+**能做什么**　打开 Panel「使用速览」页；Panel 不可用时回退为终端文字说明。
+
+**怎么用**
+```text
+/help
+```
+
+**你会得到什么**　当前版本的命令与流程速览（本白皮书提供更完整配方）。
+
+## 4.12 技能与扩展：`/skill`、`/skill:<name>`、`/mcp`、`/plugin`
+
+**能做什么**
+- `/skill`：查看、启用、停用或安装技能；捆绑研究技能已在包装内。
+- `/skill:<name>`：显式调用已启用技能（如 `/skill:analysis-plan`）。
+- `/mcp`：连接特殊统计或数据后端等外部工具服务。
+- `/plugin`：浏览推荐并管理 Plugin / Extension。
+
+**怎么用**
+```text
+/skill
+/skill:analysis-plan
+/mcp
+/plugin
+```
+
+**你会得到什么**　可发现的能力目录。启用前完成来源与依赖预检；统计经 MCP 时仍应留下可复现脚本或等价运行记录。可选推荐：`distill-scholar`、`distill-journal`；浏览器辅助文献可装 Kimi WebBridge。
+
+## 4.13 协作智能体：`/agents [任务]`
+
+**能做什么**　浏览或运行内置 / 项目级协作智能体，执行有界任务。
+
+**怎么用**
+```text
+/agents
+/agents 请只检查方法与结果表述是否一致
+```
+
+**你会得到什么**　分工互查结果；仍进入证据与人审流程后再定稿。
+
+## 4.14 学术流程：`/ars [任务|doctor|stop]`
+
+**能做什么**　学术模式入口与 ARS 流程控制：切换入口、启动完整流程、就绪诊断、停止。
+
+**怎么用**
+```text
+/ars
+/ars doctor
+/ars 社交支持与研究生抑郁：综述并形成引言草稿骨架
+/ars stop
+```
+
+**你会得到什么**　学术相关 UI/模式、诊断信息或有界文献/写作推进。许多写作任务也可自然语言 soft-route；定稿仍走两道 AI 核查 + 人审。
+
+## 4.15 模型与导出：`/provider [id]`、`/export`、`/pet`
+
+**能做什么**
+- `/provider`：查看、配置或切换模型服务提供方。
+- `/export`：导出会话或相关交付意图。
+- `/pet [on|off]`：管理启动横幅宠物显示。
+
+**怎么用**
+```text
+/provider
+/export
+/pet off
+```
+
+**你会得到什么**　后续生成所用的模型配置、会话导出，或界面偏好。论文 DOCX 等学术导出应在有稿件与人审之后按写作流程提出。
+
+## 4.16 项目级创建（非主路径）
+
+需要定制能力时可用：
+
+```text
+/create-skill <名称与需求>
+/create-hook <名称与需求>
+/create-rule <名称与需求>
+/create-subagent <名称与需求>
+```
+
+确认后落盘；先小范围验证再在团队复用。`/model` 属开发向命令，日常优先用 `/provider`。
+
+# 第五章　四条可复现工作流
+
+以下四条流程可按编号照做。示例主题可替换；配方骨架保持不变：建仓 → 方案 → 可复现执行 → 过程核对 → 实质验证 → 人审 → 交接/定稿。每一步都写出**期望产出**，便于你对照「这一步是否真的完成」。
+
+建议第一次完整跟做 5.1（问卷分析到交接），再按需要选用 5.2（文献与初稿）、5.3（动数据前加压）或 5.4（定稿核验）。四条配方可以串联：5.3 加压 → 5.1 分析交接 → 5.2 写稿 → 5.4 定稿前核验。
+
+## 5.1 问卷调查分析：从建仓到学术交接
+
+**目标**：完成一份可复现的问卷分析，并交接给写作模式。  
+**完成后你手中应有**：`analysis/scripts/` 中的脚本、`analysis/results/` 中的结果、人审记录，以及 `analysis/HANDOFF.md`。
+
+1. 建目录并进入项目：
+
+```bash
+mkdir sleep-burnout-study && cd sleep-burnout-study
+npm install -g psyclaw@0.29.15   # 若尚未安装
+psyclaw
+```
+
+2. 输入：
+
+```text
+/init 睡眠质量与大学生学业倦怠的关系
+```
+
+**期望产出**：出现 `data/`、`analysis/`、`paper/`、`psyclaw.md`、`.psyclaw/` 等约定结构。
+
+3. 将去标识后的练习数据放入 `data/raw/`。`Shift+Tab` 切到 analysis，然后输入：
+
+```text
+数据在 data/raw/。请先摸底：变量、缺失、反题项线索。
+提出可回答的研究问题与分析方案选项，不要编造结果。
+```
+
+**期望产出**：数据概况、澄清问题、可选方案；可能出现唤醒选项。
+
+4. 输入：
+
+```text
+/plan 睡眠质量与学业倦怠的相关及回归，控制年级与性别
+```
+
+或对推荐方案直接回复 `可以`。
+
+**期望产出**：活跃 Plan；可用单独 `/plan` 查看状态。
+
+5. 自然语言执行：
+
+```text
+请按已确认方案在 analysis/scripts/ 生成可复现脚本并运行；结果写入 analysis/results/。不要发明数字。
+```
+
+**期望产出**：脚本与结果摘要或表图路径。若缺 Python/R，系统应说明需要什么。
+
+6. 输入：
+
+```text
+/crosscheck 样本量、主效应、效应量与区间、表文一致性
+/verify 主结果是否成立、方法是否匹配相关/回归设计、解释有无过当
+```
+
+**期望产出**：相关项变为 `ai-checked`。此时打开 Panel 做人审，再宣称分析完成。
+
+7. 输入 `/panel`，在核对清单上对关键项点「核实」，或在唤醒选项中完成人审。
+
+**期望产出**：对应项为人审通过。
+
+8. 输入 `/handoff`。
+
+**期望产出**：写入 `analysis/HANDOFF.md`（目标、完成项、限制、下一步）。
+
+9. `Shift+Tab` 到 academic，输入：
+
+```text
+请阅读 analysis/HANDOFF.md 与 analysis/results/，起草结果部分提纲。
+不要重新选择主分析方法；缺数字就指出缺口。
+```
+
+**期望产出**：基于已有结果的写作提纲或 `paper/` 草稿起点。
+
+## 5.2 文献综述与初稿：academic + ARS + 可选 WebBridge
+
+**目标**：在已有分析交接或明确文献任务时，推进综述与初稿，并用模拟评审找漏洞。  
+**完成后你手中应有**：可核验的文献笔记或引言骨架、`paper/` 下初稿，以及一份你已筛选过的 `/review` 意见清单。
+
+1. 进入已建仓项目，`Shift+Tab` 到 academic（或 `/ars`）。
+
+2. 输入 `/ars doctor`，按提示处理缺失项。
+
+3. 输入：
+
+```text
+/ars 社交支持与研究生抑郁：有界文献梳理并形成引言草稿骨架
+```
+
+或自然语言：
+
+```text
+请基于我给出的研究问题做有界文献梳理：构念定义、主要理论、方法分歧与冲突证据。
+只使用可核验来源；不确定就标记 uncertain，不要编造文献。
+```
+
+**期望产出**：结构化文献笔记或研究简报草稿；冲突证据并列。
+
+可选：需要浏览器辅助检索或期刊前沿雷达时，可从推荐目录安装 **Kimi WebBridge**；合法全文放入 `literature/pdfs/`。可选蒸馏技能：`distill-scholar`、`distill-journal`。
+
+4. 长任务可 `/ars stop` 中止。
+
+5. 写作时输入：
+
+```text
+把已核验材料写入 paper/intro-draft.md。
+凡依赖文献的陈述必须可回溯。
+```
+
+**期望产出**：`paper/` 下 Markdown 初稿。
+
+6. 输入 `/review 重点检查引文支撑与因果语言`。
+
+**期望产出**：多角色模拟评审意见；你挑选必改项后再修订。
+
+7. 定稿前接 5.4：`/crosscheck` + `/verify` + Panel 人审。
+
+## 5.3 压力测试研究方案：先澄清加压，再定分析
+
+**目标**：在动数据之前暴露设计风险，减少「先跑完再找理由」。  
+**完成后你手中应有**：经比较的可选方向、压力测试问题清单，以及吸收了边界披露的 `/plan`。
+
+1. `/init` 后输入：
+
+```text
+/brainstorm 短期干预能否改善考试焦虑
+```
+
+**期望产出**：2–4 个可回答方向、利弊比较与推荐。
+
+2. 选定方向后输入：
+
+```text
+/grill 该准实验的选择偏倚、依从性与多重结局风险
+```
+
+**期望产出**：尖锐问题清单与文档更新建议；确认哪些写回 `psyclaw.md`。
+
+3. 进入 analysis，输入：
+
+```text
+根据刚才压力测试后的边界，提出主分析与敏感性分析方案。
+探索性与确证性分开。然后 /plan 按该边界创建方案
+```
+
+**期望产出**：带边界披露的 Plan。
+
+4. 再按 5.1：自然语言确认与执行 → `/crosscheck` + `/verify` → Panel 人审 → `/handoff`。
+
+## 5.4 定稿前核验：过程 + 实质 + 人审
+
+**目标**：在宣称全文完成或准备导出 Word 之前，走完收尾门禁。  
+**完成后你手中应有**：过程与实质两道 AI 核查记录、人审通过项，以及导出准备或明确的阻塞列表。
+
+1. academic 模式下输入：
+
+```text
+/crosscheck 正文关键主张与参考文献：DOI 可解析性、字段一致性、格式要求
+```
+
+**期望产出**：引文与格式相关清单项进入 AI 已核；无法核验的条目被标记。
+
+2. 输入：
+
+```text
+/verify 关键主张的文献支撑是否合理、解释边界是否过当、方法表述是否与交接一致
+```
+
+**期望产出**：实质性问题被标出。
+
+3. 输入 `/panel`，对必须通过的项点「核实」。
+
+**期望产出**：人审通过记录。
+
+4. 在人审通过的前提下提出导出意图，例如：
+
+```text
+将 paper/ 中的稿件按 APA 7 导出意图准备 DOCX。
+若仍有未核验引文或未下载全文，列出阻塞项。
+```
+
+**期望产出**：导出准备或明确阻塞列表。
+
+5. 若写作中发现数字缺口，切回 analysis 补算。
+
+# 第六章　Panel 与人审核验
+
+## 6.1 Panel 带来什么
+
+`/panel` 打开本机科研工作台，让你看见：项目文件投影、能力状态、核对清单，并完成人审「核实」。门禁因此可见——你不必依赖模型口头声称「已经核对」。`/help` 会打开 Panel 使用速览。
+
+## 6.2 三层检查，各自给你什么
+
+| 动作 | 谁做 | 你获得什么 | 能否完成交接/定稿 |
+|---|---|---|---|
+| `/crosscheck`（过程：数据/表、引文存在、格式、可复现痕迹） | AI | 过程一致性反馈，`ai-checked` | 还需后续步骤 |
+| `/verify`（实质：结果成立性、引文与方法合理性、解释边界） | AI | 实质问题清单，`ai-checked` | 还需人审 |
+| Panel「核实」或唤醒选项中的人审 | 你 | 人审通过记录 | 是（在门禁要求范围内） |
+
+推荐节奏：分析前用「可以」确认方案；分析后先 `/crosscheck`，再 `/verify`，最后 Panel 核实；写作定稿同样走过程 + 实质 + 人审。跳过（skip）的项不会被当作完成证据。
+
+## 6.3 唤醒选项
+
+当需要在多个方案中选择、确认下一步或勾选清单时，系统通过唤醒选项提供结构化选择。你也可以输入编号、名称或自由文本；系统会规范化并记录原文、最终选项、上下文、时间与来源。清单勾选可同步人审标记。
+
+## 6.4 你因此能安全收尾
+
+完成 analysis 交接与 academic 定稿前，走完「两道 AI 核查 + 人审」后，`/handoff` 与最终化才能通过。你得到的是可审计的收尾状态：哪些已核、哪些由你核实、还有哪些阻塞——而不是一句无法回溯的「做完了」。
+
+对人审节奏的实用建议：分析前把估计目标与排除规则说清楚（可用「可以」确认方案）；分析后重点核实 N、主效应与不确定性、表文一致、方法与脚本一致；写作定稿重点核实引文支撑与解释边界。每一次核实都在为未来的自己与合作者节省时间。
+
+# 第七章　证据与研究规范
+
+本章用「正向做法」说明如何让产出经得起合作者与审稿人追问——把规范理解成「你能交付什么质量」，而不是一串禁令。
+
+## 7.1 证据实践
+
+- **数值来自真实分析产物**：每次结果能回溯至输入、脚本、环境与证据来源；更换数据后可重跑同一脚本。
+- **引文可核验**：DOI 或题录用于定位文献；具体主张对照全文方法与结果后再写入正文。
+- **冲突证据并列披露**：综述与讨论同时呈现支持与反对方向，增强可信度。
+- **探索性与确证性分析分开表述**：读者能分辨「事先计划」与「数据驱动的后续发现」。
+- **质性研究保留轨迹**：编码轨迹、反身性与反例同样是证据；范式不同，可审计标准仍然适用。
+- **不确定就标记**：没有定位、来源或必要产物时，使用 `uncertain` 或列出阻塞项——这本身就是可发表级诚实。
+
+报告偏好（可写进 `psyclaw.md`）：主结果同时给出效应量与区间；相关设计避免因果措辞；多重比较与敏感性分析在结果或附录中可见。
+
+## 7.2 数据与隐私
+
+原始/敏感资料先去标识、最小化字段，再决定是否进入模型上下文。`data/raw/`（及兼容的 `.psyclaw/data/raw/`）保持只读，使你始终保有「从原始数据重来」的能力。机构订阅全文走合法访问；合法 PDF 放入 `literature/pdfs/` 后，写作阶段的引文核验更顺畅。
+
+## 7.3 能力扩展时的信任习惯
+
+Skill / MCP / Plugin 默认「发现但不执行」；启用前核验来源、版本/ref、哈希、许可与依赖。副作用应有结构化 receipt 与审批记录——这样扩展能力时，你仍能回答「谁批准、跑了什么、产物在哪」。捆绑学术技能已随包装提供；可选工具（如 Kimi WebBridge、`distill-scholar` / `distill-journal`）按需启用并完成预检。
+
+## 7.4 伦理与署名
+
+涉及人的研究遵守所在机构的伦理审查与知情同意要求。AI 辅助在适用披露规范下说明。PsyClaw 降低执行成本；作者责任仍由研究者承担——包括方法选择、结果解释与最终文稿。
+
+# 第八章　常见问题与排错
+
+## 8.1 排错速查
+
+| 现象 | 先做什么 |
+|---|---|
+| 找不到 `psyclaw` 命令 | `node --version`（需 `>=22.19.0`）；重开终端；检查 npm 全局 PATH |
+| 模型无法调用 | `/provider`；网络；凭据是否误写入项目 |
+| 学术模式异常 | `/ars doctor`；再单独 `/ars` 查看入口 |
+| 看不到核对清单 | 先发起 `/crosscheck` 与/或 `/verify`；打开 `/panel` |
+| `/handoff` 失败 | 到 Panel「核实」或唤醒选项补人审 |
+| 过程与实质混淆 | 分开做：`/crosscheck`（过程）→ `/verify`（实质）→ 人审 |
+| 统计无法运行 | 检查本机 Python/R 或 MCP；阅读脚本错误日志；请系统说明缺口 |
+| 会话中断 | `psyclaw --continue` 或 `psyclaw -c` |
+| 希望启动即持续推进 | `psyclaw --continuously-work`（非 Shift+Tab）；注意 token 与质量 |
+| 需要总览 | `/help` 或本白皮书第四章 |
+
+## 8.2 常见问题
+
+**Q：PsyClaw 能替代 SPSS / RStudio 吗？**  
+A：它组织对话式、可审计工作流，并委托成熟库或 MCP 完成计算。你仍可继续使用熟悉的统计引擎；PsyClaw 把方案、脚本、结果与核验留在同一项目结构中。
+
+**Q：第一次该从哪一章开始动手？**  
+A：先完成第二章安装与五分钟摸底，再按第五章 5.1 跑通「建仓到交接」。命令细节遇到再查第四章；人审节奏见第六章。
+
+**Q：AI 核查通过后，是否可以定稿？**  
+A：AI `/crosscheck` / `/verify` 把相关项标为已核；交接与定稿还须你在 Panel「核实」或唤醒选项中完成人审。两道 AI 核查帮你找问题；人审是你对关键主张负责的一步。
+
+**Q：`/crosscheck` 和 `/verify` 有何差别？**  
+A：前者侧重过程（数据/表一致、引文是否存在、格式与可复现痕迹）；后者侧重实质（结果是否站得住、方法与引文是否合理、解释是否过当）。建议都做，再人审。
+
+**Q：捆绑的 ARS / Nature / analysis-plan 还要再装吗？**  
+A：不必。它们已随 `psyclaw@0.29.15` 提供；日常用自然语言 soft-route 即可。可选增强（如 WebBridge、风格蒸馏）按需启用。
+
+**Q：如何续接昨天的工作？**  
+A：在项目目录运行 `psyclaw --continue`（或 `-c`）。关键背景写入 `psyclaw.md` 后，续接成本更低。
+
+**Q：通过门禁是否等于结论正确、可投稿？**  
+A：通过门禁表示通过当前产品合同检查。正式研究仍须研究者复核、方法学审查和适用的伦理程序。门禁帮你留下可审计状态；科学判断仍属于你。
+
+# 附录 A　斜杠命令速查表
+
+| 命令 | 能力一句话 |
+|---|---|
+| `/init [目标]` | 初始化工作区；尾随文本为研究目标 |
+| `/plan [目标]` | 查看或新建分析方案；确认用「可以」；执行用自然语言 |
+| `/handoff` | 人审通过后写入 `analysis/HANDOFF.md` |
+| `/crosscheck [焦点]` | 过程性 AI 核对（数据/引文存在/格式/可复现痕迹） |
+| `/verify [焦点]` | 实质性 AI 验证（结果成立性、引文与方法合理性） |
+| `/brainstorm [主题]` | 研究方向头脑风暴与澄清 |
+| `/grill [主题]` | 研究方案压力测试 |
+| `/review [说明]` | 多角色模拟同行评审 |
+| `/loop [目标\|stop]` | 有界推进；`/loop stop` 请求停止 |
+| `/panel [help]` | 打开科研工作台（含人审核实） |
+| `/help` | 打开 Panel 使用速览 |
+| `/skill` | Skill 管理页 |
+| `/skill:<name>` | 显式调用已启用技能 |
+| `/agents [任务]` | 浏览或运行 Subagent |
+| `/ars [任务\|doctor\|stop]` | 学术模式；尾随任务启动完整流程；`doctor` / `stop` |
+| `/provider [id]` | 查看或切换模型提供方 |
+| `/mcp` | MCP 发现与配置 |
+| `/plugin` | Plugin 推荐与管理 |
+| `/export` | 导出会话等 |
+| `/pet [on\|off]` | 启动横幅宠物 |
+| `/create-skill\|hook\|rule\|subagent <名称与需求>` | 项目级创建（需确认；非主路径） |
+| `/model` | （开发）列/切模型；日常用 `/provider` |
+
+快捷键：`Shift+Tab` 切换模式；`Ctrl+Shift+T` 思考深度。启动标志：`psyclaw --continuously-work`（非模式）。
+
+# 附录 B　可复制提示词模板
+
+**摸底（只读）**
+
+```text
+请先不要修改任何文件。描述 data/raw/ 中数据的规模、变量与异常，列出分析前必须澄清的问题。不要编造统计结果。
+```
+
+**形成方案**
+
+```text
+基于已澄清的研究问题，提出主分析与 1–2 个敏感性分析，区分探索/确证，说明输入、假设、输出与限制。用唤醒选项让我选择。然后 /plan <目标>
+```
+
+**确认执行**
+
+```text
+可以。请把确认的方法写入方案，在 analysis/scripts/ 生成可复现脚本并运行；结果写入 analysis/results/。不要发明数字。
+```
+
+**分析后核验（过程 + 实质）**
+
+```text
+请先 /crosscheck 样本量、主效应、效应量与置信区间、表文一致性、方法与脚本一致性；再 /verify 结果是否成立、解释有无过当。完成后暂停并等待人审。
+```
+
+**人审与交接**
+
+```text
+打开 /panel，对清单关键项点「核实」，或在唤醒选项中完成人审。人审通过后执行 /handoff，并基于 analysis/HANDOFF.md 起草 paper/ 结果与方法提纲。缺数字就指出缺口。
+```
+
+**压力测试**
+
+```text
+/grill 请追问测量效度、混淆、多重比较与因果表述风险；每轮一个实质问题，并给出你建议的边界披露。
+```
+
+**定稿前**
+
+```text
+/crosscheck 引文 DOI 与字段、格式与报告要求
+/verify 关键主张的文献支撑与解释边界
+完成后打开 /panel 做人审；人审完成后再准备导出。
+```
+
+# 附录 C　项目目录约定
+
+| 路径 | 约定 |
+|---|---|
+| `data/raw/` | 原始资料只读（教学与日常首选表述） |
+| `.psyclaw/data/raw/` | 部分新布局的只读保护区；与根下 `data/raw/` 兼容 |
+| `data/clean/` | 研究者确认后的派生数据 |
+| `analysis/scripts/` | 可复现脚本 |
+| `analysis/configs/` | 方案、码本、参数与预注册快照 |
+| `analysis/results/` | 数值结果与机器可读摘要 |
+| `analysis/outputs/` | 分析侧输出 |
+| `analysis/plans/` | Plan 记录 |
+| `analysis/HANDOFF.md` | analysis → academic 交接（由 `/handoff` 写入） |
+| `literature/pdfs/` | 合法取得并验证的全文 |
+| `paper/` | 论文 Markdown 与导出产物 |
+| `notes/` | 笔记、人工决策说明 |
+| `outputs/figures/` | 交付图；常需 PNG + 可编辑 SVG |
+| `psyclaw.md` | 项目说明书 |
+| `.psyclaw/` | 状态、证据账本、核对清单、运行与审计 |
+
+安装备忘：
+
+```bash
+npm install -g psyclaw@0.29.15
+psyclaw --help
+```
+
+运行要求：Node.js `>=22.19.0`。产品版本：**v0.29.15**。发布日期：2026-09-08。
+
+# 附录 D　边界速览（选读）
+
+以下内容帮助设定合理预期（全文仅此一处集中说明）：
+
+1. 统计计算委托成熟库或受信任 MCP；核心不内置统计算法，也不编造数值。
+2. `/crosscheck` 与 `/verify` 分工不同；人审走 Panel「核实」/唤醒选项，不是用户斜杠。
+3. 「可以」确认方法方案；`/handoff` 与定稿门禁认人审通过，`ai-checked` 与 skip 不够。
+4. DOI 证明文献可定位，不自动证明当前主张；模拟 `/review` 不等于期刊接收。
+5. 通过产品门禁 ≠ 结论真实、因果成立或可投稿；正式研究仍须复核、方法学审查与适用伦理程序。
+6. 应用层门禁不是操作系统级沙箱；高敏感数据与不可逆发布需更强隔离与制度审批。
+7. 斜杠为 Codex 风格（单独命令或命令 + 尾随自由文本），无子命令树。