psyclaw 0.30.6 → 0.30.8

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.6`。正式命令、用户配置目录和后续发布统一使用 `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.8` · 命令与用户目录：`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.6
-```
-
-如果本机 npm 配置把 registry 误写成带有 `~/` 的地址，请显式指定官方源：
+需要 Node.js `>=22.19.0`。
 
 ```bash
-npm install -g psyclaw@0.30.6 --registry=https://registry.npmjs.org/
-```
-
-中国大陆网络较慢或无法访问官方源时：
-
-```powershell
-npm install -g psyclaw@0.30.6 --registry=https://registry.npmmirror.com
+npm install -g psyclaw@0.30.8
 ```
 
-或安装脚本：
+中国大陆可用镜像或安装脚本：
 
 ```bash
-# macOS / Linux
+npm install -g psyclaw@0.30.8 --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.6"
 ```
 
-检测到国内 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.8
 ```
 
-上述命令不会删除研究项目目录，因为其中可能包含论文、证据、原始数据和分析产物。如需删除某个项目，应单独确认该项目的准确路径后处理。单独全局安装的 `@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

@@ -38,7 +38,37 @@ import { continuouslyWorkWarningText, isContinuouslyWorkEnabled, } from "../../s
 import { assertHumanVerifyGate, formatVerifyChecklist, isNaturalPlanConfirm, isPlanRitualConfirm, PLAN_RITUAL_PHRASE, ensureDefaultVerifyChecklist, loadVerifyChecklist } from "../../verify/checklist.js";
 import { formatSessionHelp, formatSessionHelpBrief } from "../../session/help.js";
 import { openResearchWorkbench } from "../../panel/workbench.js";
-import { captureAgentError, initNodeObservability, readTelemetryPreference, shutdownObservability, trackGateWaiting, trackSkillInstall, withAgentSpan, writeTelemetryPreference, } from "../../observability/index.js";
+import { captureAgentError, extractPiGeneration, finishAgentSpan, initNodeObservability, lastPiGeneration, readTelemetryPreference, shutdownObservability, startAgentSpan, trackGateWaiting, trackLlmGeneration, trackSkillInstall, withAgentSpan, writeTelemetryPreference, } from "../../observability/index.js";
+function ctxProviderModel(ctx) {
+    const provider = typeof ctx.model?.provider === "string" ? ctx.model.provider : undefined;
+    const model = typeof ctx.model?.id === "string" ? ctx.model.id : undefined;
+    return {
+        ...(provider === undefined ? {} : { provider }),
+        ...(model === undefined ? {} : { model }),
+    };
+}
+function piTurnSpanAttributes(extras = {}) {
+    return {
+        phase: "pi_turn",
+        ...(extras.provider ? { provider: extras.provider.slice(0, 80) } : {}),
+        ...(extras.model ? { model: extras.model.slice(0, 120) } : {}),
+    };
+}
+async function emitPiTurnGeneration(generation, extras) {
+    if (!generation)
+        return false;
+    const provider = generation.provider ?? extras.provider;
+    const model = generation.model ?? extras.model;
+    await trackLlmGeneration({
+        ...generation,
+        ...(provider === undefined ? {} : { provider }),
+        ...(model === undefined ? {} : { model }),
+        ...(extras.latencyMs === undefined ? {} : { latencyMs: extras.latencyMs }),
+        surface: "cli",
+        spanName: "pi-turn",
+    });
+    return true;
+}
 /** Codex-style slash surface: bare command, or command + trailing free text. No subcommand trees. */
 function parseInitArgs(args) {
     const goal = args.trim();
@@ -1119,6 +1149,9 @@ export default function psyclawExtension(pi) {
     let arsModeEditor;
     let arsUiContext;
     let sessionMode = "chat";
+    let turnStartedAt;
+    let llmTurnSpan;
+    let capturedTurnGeneration = false;
     const applySessionMode = (mode, opts) => {
         sessionMode = mode;
         arsModeEditor?.setMode(mode);
@@ -1163,9 +1196,55 @@ export default function psyclawExtension(pi) {
         });
     if (!legacyTestApi && typeof pi.on === "function")
         pi.on("session_shutdown", () => {
+            finishAgentSpan(llmTurnSpan);
+            llmTurnSpan = undefined;
             runtimeMcps.close();
             void shutdownObservability();
         });
+    if (!legacyTestApi && typeof pi.on === "function")
+        pi.on("agent_start", () => {
+            capturedTurnGeneration = false;
+        });
+    if (!legacyTestApi && typeof pi.on === "function")
+        pi.on("turn_start", async (event, ctx) => {
+            finishAgentSpan(llmTurnSpan);
+            turnStartedAt = typeof event.timestamp === "number" && Number.isFinite(event.timestamp)
+                ? event.timestamp
+                : Date.now();
+            llmTurnSpan = await startAgentSpan("cli.llm_call", piTurnSpanAttributes(ctxProviderModel(ctx)));
+        });
+    if (!legacyTestApi && typeof pi.on === "function")
+        pi.on("turn_end", async (event, ctx) => {
+            const fallback = ctxProviderModel(ctx);
+            const generation = extractPiGeneration({ type: "message", message: event.message });
+            const latencyMs = turnStartedAt === undefined ? undefined : Math.max(0, Date.now() - turnStartedAt);
+            const provider = generation?.provider ?? fallback.provider;
+            const model = generation?.model ?? fallback.model;
+            finishAgentSpan(llmTurnSpan, piTurnSpanAttributes({
+                ...(provider === undefined ? {} : { provider }),
+                ...(model === undefined ? {} : { model }),
+            }));
+            llmTurnSpan = undefined;
+            if (await emitPiTurnGeneration(generation, { ...fallback, ...(latencyMs === undefined ? {} : { latencyMs }) })) {
+                capturedTurnGeneration = true;
+                turnStartedAt = undefined;
+            }
+        });
+    if (!legacyTestApi && typeof pi.on === "function")
+        pi.on("agent_end", async (event, ctx) => {
+            const fallback = ctxProviderModel(ctx);
+            finishAgentSpan(llmTurnSpan, piTurnSpanAttributes(fallback));
+            llmTurnSpan = undefined;
+            const latencyMs = turnStartedAt === undefined ? undefined : Math.max(0, Date.now() - turnStartedAt);
+            turnStartedAt = undefined;
+            if (capturedTurnGeneration) {
+                capturedTurnGeneration = false;
+                return;
+            }
+            capturedTurnGeneration = false;
+            const generation = lastPiGeneration([event]);
+            await emitPiTurnGeneration(generation, { ...fallback, ...(latencyMs === undefined ? {} : { latencyMs }) });
+        });
     if (!legacyTestApi && typeof pi.on === "function")
         pi.on("before_agent_start", async (event, ctx) => {
             if (!(await readActiveProject(ctx?.cwd ?? process.cwd())))
@@ -1408,6 +1487,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) => {