psyclaw 0.30.7 → 0.30.9

package/README.md

@@ -1,221 +1,116 @@
 # PsyClaw
 
-PsyClaw 是面向社会科学研究的智能体工作台。它把研究项目、证据来源、Claim-Evidence 账本、完整性门禁、可恢复工作流和本地面板接到内置运行时上；只有无法由证据和通行方法消解、且会实质改变研究设计或解释的分歧才交由研究者取舍。它不替代统计软件，也不会把未经核验的引用、结果或审稿意见写成事实。
+面向社会科学研究的智能体工作台：把研究项目、证据账本、完整性门禁、可恢复工作流和本地面板接到内置运行时上。它不替代统计软件，也不会把未经核验的引用、结果或审稿意见写成事实。
 
-PsyClaw 自有代码使用 MIT 许可证；随 npm 包内置的 Academic Research Skills 位于 `vendor/ars`，保持上游署名并单独遵循 CC BY-NC 4.0，仅限非商业用途。
-
-当前版本：`0.30.7`。正式命令、用户配置目录和后续发布统一使用 `psyclaw`。
-
-## 发布流程
-
-发布只提交已跟踪文件，并自动递增 patch 版本、创建版本标签，推送当前分支和标签；`.DS_Store`、论文附件、图形和其他未跟踪生成物不会被加入。GitHub Actions 随标签推送执行 Node 22 检查并发布 npm：
-
-```bash
-RELEASE_MESSAGE="release: describe the change" pnpm release:push
-```
-
-运行前请确认当前分支、工作区变更和 GitHub 权限。NPM 发布由 GitHub Actions 的 Trusted Publishing 完成，本机不需要 `npm login`。
+当前版本：`0.30.9` · 命令与用户目录：`psyclaw` / `~/.psyclaw` · 许可证：MIT
+内置 Academic Research Skills（`vendor/ars`）遵循上游 CC BY-NC 4.0，仅限非商业用途。
 
 ## 安装
 
-需要 Node.js `>=22.19.0`。官方 npm 源：
-
-```powershell
-npm install -g psyclaw@0.30.7
-```
-
-如果本机 npm 配置把 registry 误写成带有 `~/` 的地址，请显式指定官方源：
+需要 Node.js `>=22.19.0`。
 
 ```bash
-npm install -g psyclaw@0.30.7 --registry=https://registry.npmjs.org/
-```
-
-中国大陆网络较慢或无法访问官方源时：
-
-```powershell
-npm install -g psyclaw@0.30.7 --registry=https://registry.npmmirror.com
+npm install -g psyclaw@0.30.9
 ```
 
-或安装脚本：
+中国大陆可用镜像或安装脚本：
 
 ```bash
-# macOS / Linux
+npm install -g psyclaw@0.30.9 --registry=https://registry.npmmirror.com
+# 或
 PSYCLAW_CN=1 curl -fsSL https://exekiel179.github.io/psyclaw/install.sh | sh
 ```
 
 ```powershell
-# Windows PowerShell
+# Windows
 irm https://exekiel179.github.io/psyclaw/install.ps1 | iex
-# 可选：$env:PSYCLAW_CN = "1"；$env:PSYCLAW_VERSION = "0.30.7"
 ```
 
-检测到国内 npm registry（如 npmmirror）、`PSYCLAW_CN=1` 或 `PSYCLAW_GITHUB_MIRROR` 时，内置路径统一走国内可用路由：
+确认入口：
 
-- 首启 `fd` / `ripgrep`（macOS/Linux）：GitHub API 与 Release 经 `gh-proxy` 等镜像；Windows 仍用包内二进制，无需下载
-- `psyclaw update` / `check-updates`：读版本与安装命令使用 `PSYCLAW_REGISTRY` 或 npmmirror，不再写死官方 npm
-- 推荐 Skill 的托管 `git clone`：经 GitHub 镜像前缀
-- `fetch` 覆盖 `api.github.com`、`github.com`、`raw.githubusercontent.com`、`codeload.github.com`
-
-建议把 `registry=https://registry.npmmirror.com` 写入 `~/.npmrc`，以免下次启动检测不到国内源。已有 HTTP(S) 代理时优先走代理、保持官方 GitHub URL。
-
-PsyClaw 的 npm 发布包直接携带 Windows x64/arm64 版 `ripgrep` 和 `fd`，Windows 启动时直接使用包内可执行文件，不再联网下载。
-
-确认命令入口：
-
-```powershell
+```bash
 psyclaw --help
 ```
 
-直接运行 `psyclaw` 会启动交互研究工作台；首次没有模型配置时会自动进入配置流程。配置界面会检查当前进程、macOS `launchctl` 和已有用户凭据，也允许直接遮罩输入 Key。`launchctl` Key 只注入当前运行进程、不落盘；登录 shell 仅在用户明确按 `Ctrl+I` 后读取。直接输入或明确导入的 Key 只保存到 PsyClaw 用户级 `auth.json`，不会写入项目或 `models.json`。模型、凭据、会话和宿主资源统一保存在 `~/.psyclaw/agent`，PsyClaw 不创建或使用 `~/.pi`。不要把 API key 写进命令参数、项目、README 或 Git 仓库。
+直接运行 `psyclaw` 会启动交互工作台；首次无模型配置时会进入配置流程。API Key 只写入用户级 `~/.psyclaw/agent/auth.json`，不要写进命令参数、项目或 Git 仓库。
 
 ## 五分钟开始
 
-在新的研究目录中建立项目：
-
-```powershell
-mkdir my-study
-cd my-study
+```bash
+mkdir my-study && cd my-study
 psyclaw init "社交支持与研究生心理健康的关系" --paradigm survey-observational
 psyclaw
 ```
 
-初始化会建立 `.psyclaw/data/raw/`、`data/clean/`、`literature/pdfs/`、`notes/` 和 `outputs/`，不再把原始数据目录暴露在项目根目录。`.psyclaw/data/raw/` 是只读保护区；旧项目的 `data/raw/` 仍保持只读兼容，把经确认可用于分析的派生数据放在 `data/clean/`。
-
-在对话界面中，`/init <研究目标>` 初始化研究项目与工作区；随后用 Shift+Tab 切换到 `analysis` 或 `academic` 推进。没有单独的 `/run` 或 `/brief` 命令。未 `/init` 时保持普通对话，不强制研究门禁。
+初始化会创建 `.psyclaw/data/raw/`（只读保护区）、`data/clean/`、`literature/pdfs/`、`notes/`、`outputs/`。对话中也可用 `/init <研究目标>`；用 `Shift+Tab` 在 `chat` → `analysis` → `academic` 间切换。未 `/init` 时保持普通对话，不强制研究门禁。
 
-登记本地材料：
-
-```powershell
-psyclaw evidence add notes\source.md --level user
+```bash
+psyclaw evidence add notes/source.md --level user
 ```
 
-## 常用入口
+## 常用命令
 
-| 需求 | 命令或操作 |
+| 需求 | 命令 |
 | --- | --- |
-| 启动研究对话 | `psyclaw` 或 `psyclaw chat` |
-| 续接当前项目最近一次会话 | `psyclaw --continue` 或 `psyclaw -c` |
-| 创建研究项目 | `psyclaw init <goal> --paradigm <profile>` 或对话 `/init <goal>` |
-| 推进分析 / 写作 | Shift+Tab 切换 analysis / academic；可选 `/loop`、`/review` |
-| 模拟同行评审 | 论文完成后在对话中输入 `/review` |
-| 登记本地证据 | `psyclaw evidence add <path> --level user\|fulltext` |
-| 写研究移交记录 | `psyclaw handoff` |
-| 扫描本机其他 Agent | `psyclaw agents` |
-| 查看 PsyClaw 和内置运行时更新 | `psyclaw check-updates` |
-| 更新 PsyClaw 和内置运行时 | `psyclaw update` |
-| 导出会话 | 使用 Pi 内置的 `/export` |
-| 匿名产品遥测 | `psyclaw telemetry status`、`psyclaw telemetry off`、`psyclaw telemetry on`（默认开启；对话中 `/telemetry`） |
-| 打开科研面板 | 在对话中输入 `/panel`（Provider 页可选填 Base URL，指向 OpenAI 兼容网关） |
-| 查看或切换 Provider | 在对话中输入 `/provider` 或 `/provider <id>` |
-| 管理启动横幅宠物 | `/pet`、`/pet on`、`/pet off`（默认关闭） |
-| 管理 Skill | `/skill`（未安装→安装并默认启用；已启用→停用） |
-| 创建项目能力 | `/create-skill`、`/create-hook`、`/create-rule`、`/create-subagent`（附带需求文本） |
-| 运行只读 Subagent | `/agents` 浏览，或 `/agents <task>` 运行 |
-| 调用已加载 Skill | `/skill:<name>` |
-| 使用模式 | `Shift+Tab`：`chat` → `analysis` → `academic`；thinking 用 `Ctrl+Shift+T` |
-| 搭建仓库 | `/init` 或 `/init <研究目标>` |
-| 分析方案 / 交接 | `/plan`、`/plan <目标>`；人审后 `/handoff` |
-| AI 过程核对 / 实质验证 | `/crosscheck [焦点]`；`/verify [焦点]`。人审由收尾门禁自动要求（Panel/唤醒选项） |
-| 使用 PsyClaw ARS | `/ars` 开学术模式，或 `/ars <任务>`；`/ars doctor`、`/ars stop` |
-| 管理 Plugin | `/plugin`；终端使用 `psyclaw plugin install|remove|list` |
-| 调用已配置 MCP | `/mcp` 管理；模型通过 `psyclaw_mcp` 调用已启用服务器 |
-
-`psyclaw update` 会更新 PsyClaw 整包，并同时安装该版本锁定的内置运行时。在源码仓库中运行时，命令会停止并提示通过 Git 更新，不会覆盖本地修改。
-仅查看更新计划而不执行时，使用 `psyclaw update --check`。旧的 `--yes` 参数仍兼容，但不再需要。
-
-### 导出使用路径
-
-```bash
-/export
-```
+| 启动 / 续接会话 | `psyclaw` · `psyclaw -c` |
+| 初始化项目 | `psyclaw init <goal> --paradigm <profile>` 或 `/init` |
+| 登记证据 | `psyclaw evidence add <path> --level user\|fulltext` |
+| 更新 | `psyclaw check-updates` · `psyclaw update` |
+| 科研面板 | 对话中 `/panel` |
+| 模式切换 | `Shift+Tab`（chat / analysis / academic） |
+| 学术 ARS | `/ars` · `/ars <任务>` · `/ars doctor` |
+| Skill / Plugin / MCP | `/skill` · `/plugin` · `/mcp` |
+| 遥测 | `psyclaw telemetry off\|on\|status`（默认开启，可关） |
+
+更多对话命令见 `psyclaw --help` 与 [使用白皮书](docs/使用白皮书.md)。
 
-`/export` 由 Pi 内置命令提供。PsyClaw 不重复实现会话导出或 Trace 运行时。
+## 文档
 
-## 开发者本地安装
+**研究者**
 
-```powershell
-pnpm install
-pnpm build
-npm link
-psyclaw --help
-```
+- [使用白皮书](docs/使用白皮书.md)（正文：[v0.30.1](docs/PsyClaw使用白皮书_v0.30.1.md)）
+- [PsyClaw ARS 模式](docs/PsyClaw-ARS模式.md)
+- [遥测说明](docs/telemetry.md)
+- [文档与产物目录规范](docs/文档规范.md) · [产物目录规范](docs/产物目录规范.md)
 
-开发阶段不需要执行 `psyclaw update`。请通过 Git 同步仓库，再运行 `pnpm install` 和 `pnpm build`。
+**贡献者**（实现契约，非日常使用说明）
 
-## 从旧 Python 版迁移
+- [开工纪要](docs/开工纪要.md) · [架构蓝图](docs/架构蓝图.md) · [评测框架](docs/评测框架.md)
+- [技能与生态准入清单](docs/技能与生态准入清单.md) · [威胁模型](docs/威胁模型.md)
+- [AGENTS.md](AGENTS.md)
 
-如果启动时出现 `ModuleNotFoundError: No module named 'psyclaw.cli'`，终端仍解析到旧 Python 安装的 `psyclaw.exe`，而不是 npm 版本。先检查命令顺序：
+## 边界
 
-```powershell
-Get-Command psyclaw -All
-where.exe psyclaw
-```
+- 复用官方 Pi runtime，不维护 fork。
+- 统计计算委托 Python/R、SPSS/Stata/Mplus 或受信任 MCP；须保存脚本、输入指纹与环境信息。
+- Skill / Plugin / MCP 默认只发现、不执行；启用前核对来源与信任状态。
+- 无证据的事实性 Claim 须标为 `uncertain` 或阻断；无 receipt / 审批的副作用不算完成。
 
-保留 npm 的 `psyclaw.cmd`，移除或下调旧 Python 入口所在目录后重新打开终端，再安装当前版本：
+## 从源码开发
 
-```powershell
-npm uninstall -g psyclaw
-npm install -g psyclaw@0.27.5
+```bash
+pnpm install && pnpm build && npm link
 psyclaw --help
 ```
 
-Python 的卸载器提示 `No files were found to uninstall` 时，不要手工删除不明目录；先用上述命令定位旧入口，再在对应 Python 环境中修复或移除它。
+源码树中请用 Git 同步，不要跑 `psyclaw update`（会拒绝覆盖本地修改）。
 
-## 卸载
-
-仅卸载 PsyClaw 程序，保留用户配置和历史会话：
+发布（维护者）：
 
 ```bash
-npm uninstall -g psyclaw
+RELEASE_MESSAGE="release: describe the change" pnpm release:push
 ```
 
-完全卸载 PsyClaw（同时删除模型配置、用户设置和历史会话）：
+标签推送后由 GitHub Actions（Node 22 + Trusted Publishing）发布 npm。
 
-```bash
-npm uninstall -g psyclaw
-```
+## 迁移与卸载
 
-```powershell
-# 删除用户配置目录 ~/.psyclaw（不会删除研究项目）
-Remove-Item -Recurse -Force "$HOME\.psyclaw" -ErrorAction SilentlyContinue
-```
+若出现 `ModuleNotFoundError: No module named 'psyclaw.cli'`，说明仍指向旧 Python 入口。用 `Get-Command psyclaw -All` / `which -a psyclaw` 定位后移除旧入口，再安装当前 npm 包：
 
 ```bash
-# macOS / Linux
-rm -rf ~/.psyclaw
+npm uninstall -g psyclaw
+npm install -g psyclaw@0.30.9
 ```
 
-上述命令不会删除研究项目目录，因为其中可能包含论文、证据、原始数据和分析产物。如需删除某个项目，应单独确认该项目的准确路径后处理。单独全局安装的 `@earendil-works/pi-coding-agent` 不属于 PsyClaw 用户数据，上述命令不会删除它。
-
-## 文档
-
-### 使用（面向研究者）
-
-- [使用白皮书](docs/使用白皮书.md)（当前版同步说明；带版本号的副本见 `docs/PsyClaw使用白皮书_v*.md`）
-- [PsyClaw ARS 模式与保护边界](docs/PsyClaw-ARS模式.md)
-- [遥测（匿名产品遥测，默认开启，可关闭）](docs/telemetry.md)
-- [文档与交付物规范](docs/文档规范.md)（研究项目内目录约定）
-
-### 开发（面向贡献者 / 维护者）
-
-下列文件是仓库与实现契约，**不是**日常使用说明；贡献或改核心前再读：
-
-- [项目范围与里程碑](docs/开工纪要.md)
-- [架构蓝图](docs/架构蓝图.md)
-- [评测框架](docs/评测框架.md)
-- [技能与生态准入清单](docs/技能与生态准入清单.md)
-- [威胁模型](docs/威胁模型.md)
-- [AGENTS.md](AGENTS.md)（贡献行为约束）
-
-历史审计、分模块测评报告、会话复盘等仍在 `docs/` 下，按文件名识别；勿与使用白皮书混读。
-
-## 边界
-
-- PsyClaw 复用官方 Pi 的 session、model、skill、package 和 extension runtime，不维护 fork。
-- 统计计算委托 Python/R、SPSS/Stata/Mplus 或受信任 MCP；输出必须保存脚本、输入指纹和环境信息。
-- Skill、Plugin 和 MCP 默认只发现、不执行；启用前需要来源、版本/ref、哈希、许可证和依赖状态。
-- 没有可定位证据的事实性 Claim 必须是 `uncertain` 或被阻断；没有审批记录的副作用不能被当作完成。
-- 遥测默认开启（匿名产品使用与错误，不含研究正文）。首次启动会说明如何关闭：`psyclaw telemetry off`。详见 [docs/telemetry.md](docs/telemetry.md)。
-
-许可证：MIT。
-
+仅卸载程序：`npm uninstall -g psyclaw`  
+同时清除用户配置与会话：再删除 `~/.psyclaw`（不会删除研究项目目录）。

package/agents/recommended/catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "psyclaw/recommended-agents/v1",
-  "documentVersion": "0.29.2",
-  "syncedAt": "2026-09-07",
+  "documentVersion": "0.30.6",
+  "syncedAt": "2026-09-21",
   "sourceDocument": "bundled literature/review subagents",
   "sourceRef": "bundled",
   "repositoryHint": "对齐 Claude Code：Subagent = md 提示合订本。外仓可后续以 GitHub 源加入 installPrep；当前内置 8 个无需安装。",

package/dist/src/adapters/pi/extension.js

@@ -726,12 +726,20 @@ function modelMcpInstallTask(root, row, plan) {
         "成功后确保 .psyclaw/recommendations.json 的 mcp 列表包含该 id（安装时已默认写入启用），说明写入了哪些配置，并提醒用户执行 /reload。若安装命令本身失败，直接诊断并修复；只有遇到必须由用户提供的凭据或外部软件许可证时才向用户说明。",
     ].join("\n");
 }
+/** Queue an install/setup prompt for the model without rendering the long text as a user bubble. */
+function queueHiddenInstallTask(pi, ctx, task) {
+    if (typeof pi.sendMessage === "function") {
+        pi.sendMessage({ customType: "psyclaw-install-task", content: task, display: false }, ctx.isIdle() ? { triggerTurn: true } : { deliverAs: "followUp" });
+        return;
+    }
+    pi.sendUserMessage(task, ctx.isIdle() ? {} : { deliverAs: "followUp" });
+}
 async function queueModelMcpInstall(pi, ctx, row, plan) {
     if (!row.sourceRef)
         throw new Error(`推荐 MCP 没有来源网址: ${row.id}`);
     await setRecommendedMcpEnabled(ctx.cwd, row.id, true);
-    pi.sendUserMessage(modelMcpInstallTask(ctx.cwd, row, plan), ctx.isIdle() ? {} : { deliverAs: "followUp" });
-    ctx.ui.notify(`已将 ${row.name} 的下载、安装和配置任务交给当前模型（默认启用）。完成后请执行 /reload。`, "info");
+    queueHiddenInstallTask(pi, ctx, modelMcpInstallTask(ctx.cwd, row, plan));
+    ctx.ui.notify(`已将 ${row.name} 的安装任务交给当前模型（指令不展示在对话中；默认启用）。完成后请执行 /reload。`, "info");
 }
 async function showMcpManager(pi, ctx, runtime) {
     const catalog = await recommendedItems("mcp");
@@ -829,8 +837,8 @@ async function queueModelSkillInstall(pi, ctx, row) {
             return;
         }
         void trackSkillInstall("queued", { skill_id: row.id, scope, status: "queued" });
-        pi.sendUserMessage(modelSkillInstallTask(ctx.cwd, row, scope), ctx.isIdle() ? {} : { deliverAs: "followUp" });
-        ctx.ui.notify(`已将 ${row.name} 的安装任务交给当前模型（默认启用），目标为${skillScopeLabel(scope)}。完成后请执行 /reload。`, "info");
+        queueHiddenInstallTask(pi, ctx, modelSkillInstallTask(ctx.cwd, row, scope));
+        ctx.ui.notify(`已将 ${row.name} 的安装任务交给当前模型（指令不展示在对话中；默认启用），目标为${skillScopeLabel(scope)}。完成后请执行 /reload。`, "info");
     });
 }
 function modelBiosignalPackInstallTask(root, plan, skillRows, mcpRows, mcpPlans, skillScope) {
@@ -943,8 +951,8 @@ async function queueBiosignalPackInstall(pi, ctx, plan, runtime) {
     if (!approved)
         return;
     await markBiosignalPackDesired(ctx.cwd, plan, scope);
-    pi.sendUserMessage(modelBiosignalPackInstallTask(ctx.cwd, plan, skillRows, selectedMcp, mcpCatalog.installPrep, scope), ctx.isIdle() ? {} : { deliverAs: "followUp" });
-    ctx.ui.notify("已将生理信号能力包安装任务交给当前模型。完成后请执行 /reload，并 Shift+Tab 切到 analysis 使用。", "info");
+    queueHiddenInstallTask(pi, ctx, modelBiosignalPackInstallTask(ctx.cwd, plan, skillRows, selectedMcp, mcpCatalog.installPrep, scope));
+    ctx.ui.notify("已将生理信号能力包安装任务交给当前模型（指令不展示在对话中）。完成后请执行 /reload，并 Shift+Tab 切到 analysis 使用。", "info");
 }
 async function showBiosignalPack(pi, ctx, runtime) {
     const catalog = await readBiosignalPackCatalog();
@@ -1315,6 +1323,7 @@ export default function psyclawExtension(pi) {
                         isProjectTrusted: () => ctx.isProjectTrusted(),
                         isIdle: () => ctx.isIdle(),
                         sendUserMessage: (message, options) => pi.sendUserMessage(message, options ?? {}),
+                        sendHiddenInstallTask: (task) => queueHiddenInstallTask(pi, ctx, task),
                     }, { view: "help" });
                     ctx.ui.notify(formatSessionHelpBrief(url) + (opened ? "" : "\n（未能自动打开浏览器时请手动访问）"), opened ? "info" : "warning");
                 }
@@ -1487,6 +1496,12 @@ export default function psyclawExtension(pi) {
             });
             return undefined;
         });
+    pi.registerCommand("exit", {
+        description: "完整退出 PsyClaw（等同 /quit）",
+        handler: async (_args, ctx) => {
+            ctx.shutdown();
+        },
+    });
     pi.registerCommand("init", {
         description: "搭建干净工作仓库（目录 + psyclaw.md），不自动追问",
         handler: async (args, ctx) => {
@@ -1591,6 +1606,7 @@ export default function psyclawExtension(pi) {
                     isProjectTrusted: () => ctx.isProjectTrusted(),
                     isIdle: () => ctx.isIdle(),
                     sendUserMessage: (message, options) => pi.sendUserMessage(message, options ?? {}),
+                    sendHiddenInstallTask: (task) => queueHiddenInstallTask(pi, ctx, task),
                 }, { view: "help" });
                 ctx.ui.notify(formatSessionHelpBrief(url) + (opened ? "" : "\n（未能自动打开浏览器时请手动访问）"), opened ? "info" : "warning");
             }