psyclaw 0.25.1 → 0.26.0

package/README.md

@@ -1,60 +1,111 @@
-# psyclaw
-
-面向社会科学研究者的 Pi 科研智能体层。
-
-## 版本沿革
-
-`PsyClaw v0.25.1` 以 `psypi v0.4.1` 的完整实现为基线完成产品改名和源码迁移。`F:\Projects\psypi\psypi` 保留为历史仓库；此后的正式开发、发布和 `psyclaw` 命令均以本仓库为准。为避免中断已有模型、主题、扩展和 Skill 配置，运行时继续兼容既有 Pi profile；研究项目状态则统一写入 `.psyclaw/`。
-
-psyclaw 的目标不是再造一个重量级 Agent，而是在官方 Pi 之上提供少量、可审计、可组合的科研契约：研究项目状态、Claim-Evidence-Provenance 账本、完整性门禁、可恢复工作流、受控记忆和按需技能。统计计算交给成熟库或外接 MCP；Pi 的会话、模型、Skill、Package 和 TUI/RPC 能力继续由 Pi 提供。
-
-当前仓库已完成第一条 M1/MVP-0 可运行切片，并落地 M2 的技能注册与受限多智能体编排基础、M3 的只读并行契约、真实 stdio MCP transport（argv/显式 env/超时隔离）、Skill 恶意正文 preflight、许可证/SBOM 门与 M4 的 literature-review/analysis-delegation/writing-review 三个 workflow 包。官方 Pi 的 `AgentSession`、`SessionManager`、`DefaultResourceLoader`、模型网关和严格 JSONL RPC 已由 adapter 接入；完成项目级 package 安装后提供原生只读 `/agents` 多智能体入口，面板扩展可选安装。联网检索、统计计算和并行写入仍按规划后置。先阅读：
-
-- [开工纪要](docs/开工纪要.md)
-- [架构蓝图](docs/架构蓝图.md)
-- [多智能体开发与运行框架](docs/多智能体开发与运行框架.md)
-- [评测框架](docs/评测框架.md)
-- [技能与生态准入清单](docs/技能与生态准入清单.md)
-- [威胁模型](docs/威胁模型.md)
-
-代号：`psyclaw`。当前可用命令：
-
-```text
-pnpm install
-pnpm build
-pnpm exec pi install -l .       # 一次性把 psyclaw 作为项目级 Pi package 启用
-pnpm exec pi --approve           # 运行 Pi 时信任已审查的项目 package
-node dist/src/cli.js init "研究问题" --paradigm survey-observational
-node dist/src/cli.js evidence add notes/source.md --level user
-node dist/src/cli.js brief
-node dist/src/cli.js workflow literature-review
-node dist/src/cli.js serve --port 8787
-  node dist/src/cli.js agents
-  node dist/src/cli.js install claude-code --yes  # 当前 agent 全局命令仍为 discover-only
-  node dist/src/cli.js import claude-code --yes
-  node dist/src/cli.js shell
-  /skills                         # 查看推荐 Skill 的启用状态
-  /skills enable <skill-id>       # 启用项目级 Skill
-  /skills disable <skill-id>      # 禁用项目级 Skill
-  /mcp                            # 查看推荐 MCP 的启用状态
-  /mcp enable <mcp-id>            # 启用项目级 MCP
-  /mcp disable <mcp-id>           # 禁用项目级 MCP
-  /install skill|mcp <id>         # 生成安装预检计划
-  pnpm exec pi --extension ./dist/src/extension.js --approve  # 未安装 package 时的临时入口
-  pi --extension ./dist/src/panel/extension.js                # 可选：在 Pi 中启停 /panel
-```
-
-在 `pi-workbench` 中使用时，先在研究项目根目录安装 psyclaw package：
-
-```text
-pi install -l F:\Projects\psyclaw\psyclaw
-pi-workbench
-```
-
-workbench 启动的每个 Pi 会话都会加载 psyclaw 的 `/research`、`/brief`、`/agents` 和 `/panel` 命令。在 Pi 中执行 `/panel` 后，用浏览器打开提示的 `http://127.0.0.1:8787` 地址即可查看当前项目的只读运行状态。
-
-`brief` 与 `workflow` 在证据门禁失败时退出码为 `2`，并保留 manifest 与 HANDOFF，不生成貌似完成的正文。`serve` 启动本机面板：运行事实、Agent/Skill 和模型目录为只读；模型配置表单是唯一明确的本地写入入口，会将 provider 元数据写入 Pi `models.json`，API key 交给 Pi `auth.json` 管理。
-
-内置 agent 下载器/安装器：`agents`/`scan` 只读识别本机其他智能体（Claude Code、OpenAI Codex、Gemini CLI、opencode、Aider、Cursor、Windsurf、Continue、Orca、Copilot CLI）的配置与技能目录，绝不读取凭据内容；安装计划必须有来源、版本、artifact SHA、许可证/依赖审计和 SBOM，缺任何一项都会 `blocked`。当前 agent catalog 只有全局 npm/pipx 命令，尚未绑定可验证 staging artifact，因此即使人工确认也保持 `agent-staging-required`，不会执行全局安装；`import <id> --yes` 将其他 agent 的允许 Skill 文件以来源/SHA-256 溯源导入 `.psyclaw/imports/`；`shell` 启动 ink 交互式表格 TUI（↑/↓ 选择、`i` 安装、`m` 导入、`r` 重扫、`q` 退出）。
-
-Pi 集成分两层：完成一次 `pi install -l .` 后，项目级 package 默认加载 `src/extension.ts`，注册研究命令和原生只读 `/agents`；未安装时可用上面的 `--extension` 临时入口。worker 通过独立 Pi RPC 子进程、`read/grep/find/ls` 工具和结构化 WorkerReport 回传，但进程边界仍不是 OS sandbox。`src/panel/extension.ts` 是可选扩展，使用 `/panel [--port 8787]` 启停仅绑定 `127.0.0.1` 的只读可视化界面。面板的 Agents/Skills 下载页只展示发现结果、来源、版本、许可证、SHA、风险和审批前计划；模型页读取 Pi 本地模型注册表，并在没有对应注册项时显示 psyclaw 的 DeepSeek 模板元数据。页面只显示环境变量名称，不接收或显示 API key；`configured` 只表示环境变量存在，不代表实际认证成功。模型适配沿用 Pi `models.json`/`registerProvider` 契约，DeepSeek helper 只输出 `$DEEPSEEK_API_KEY` 引用。
+# PsyClaw
+
+PsyClaw 是面向社会科学研究的 Pi 工作台。它把研究项目、证据来源、Claim-Evidence 账本、完整性门禁、人工裁决、可恢复工作流和本地面板接到官方 Pi runtime 上；它不替代统计软件，也不会把未经核验的引用、结果或审稿意见写成事实。
+
+当前版本：`0.26.0`。本仓库以 `psypi v0.4.1` 的完整工作台为功能基线完成改名；`psypi` 仓库保留为历史仓库，正式命令和后续发布均使用 `psyclaw`。
+
+## 安装
+
+需要 Node.js `>=22.19.0`。官方 npm 源：
+
+```powershell
+npm install -g psyclaw@0.26.0
+```
+
+中国大陆网络较慢或无法访问官方源时：
+
+```powershell
+npm install -g psyclaw@0.26.0 --registry=https://registry.npmmirror.com
+```
+
+确认命令入口：
+
+```powershell
+psyclaw --help
+```
+
+直接运行 `psyclaw` 会启动交互研究工作台；首次没有模型配置时会进入配置向导。也可显式运行 `psyclaw wizard`，或使用 `psyclaw setup --provider deepseek`。不要把 API key 写进项目、README 或 Git 仓库。
+
+## 五分钟开始
+
+在新的研究目录中建立项目：
+
+```powershell
+mkdir my-study
+cd my-study
+psyclaw init "社交支持与研究生心理健康的关系" --paradigm survey-observational
+psyclaw
+```
+
+初始化会建立 `.psyclaw/`、`data/raw/`、`data/clean/`、`notes/` 和 `outputs/`。`data/raw/` 是只读保护区；把经确认可用于分析的派生数据放在 `data/clean/`。
+
+登记本地材料并生成离线证据简报：
+
+```powershell
+psyclaw evidence add notes\source.md --level user
+psyclaw brief
+```
+
+## 常用入口
+
+| 需求 | 命令或操作 |
+| --- | --- |
+| 启动研究对话 | `psyclaw` 或 `psyclaw chat` |
+| 创建研究项目 | `psyclaw init <goal> --paradigm <profile>` |
+| 登记本地证据 | `psyclaw evidence add <path> --level user\|fulltext` |
+| 生成离线简报 | `psyclaw brief` |
+| 创建人工裁决模板 | `psyclaw hitl init` |
+| 写研究移交记录 | `psyclaw handoff` |
+| 扫描本机其他 Agent | `psyclaw agents` |
+| 查看 Pi runtime 更新 | `psyclaw check-updates` |
+| 更新 Pi runtime | `psyclaw update --yes` |
+| 打开科研面板 | 在对话中输入 `/panel` |
+
+`psyclaw update` 只更新捆绑的 Pi runtime；它不是从 Git 拉取 PsyClaw 源码。全局安装用户通过 `npm install -g psyclaw@<version>` 获取 PsyClaw 新版本；本仓库开发者直接修改源码并构建。
+
+## 开发者本地安装
+
+```powershell
+pnpm install
+pnpm build
+npm link
+psyclaw --help
+```
+
+开发阶段不需要执行 `psyclaw update`。它会更新 Pi 依赖，不会同步本仓库代码。
+
+## 从旧 Python 版迁移
+
+如果启动时出现 `ModuleNotFoundError: No module named 'psyclaw.cli'`，终端仍解析到旧 Python 安装的 `psyclaw.exe`，而不是 npm 版本。先检查命令顺序：
+
+```powershell
+Get-Command psyclaw -All
+where.exe psyclaw
+```
+
+保留 npm 的 `psyclaw.cmd`，移除或下调旧 Python 入口所在目录后重新打开终端，再安装当前版本：
+
+```powershell
+npm uninstall -g psyclaw
+npm install -g psyclaw@0.26.0
+psyclaw --help
+```
+
+Python 的卸载器提示 `No files were found to uninstall` 时，不要手工删除不明目录；先用上述命令定位旧入口，再在对应 Python 环境中修复或移除它。
+
+## 文档
+
+- [PsyClaw v0.26.0 使用白皮书](docs/PsyClaw使用白皮书_v0.26.0.md)
+- [项目范围与里程碑](docs/开工纪要.md)
+- [架构蓝图](docs/架构蓝图.md)
+- [评测框架](docs/评测框架.md)
+- [文档与交付物规范](docs/文档规范.md)
+
+## 边界
+
+- PsyClaw 复用官方 Pi 的 session、model、skill、package 和 extension runtime，不维护 fork。
+- 统计计算委托 Python/R、SPSS/Stata/Mplus 或受信任 MCP；输出必须保存脚本、输入指纹和环境信息。
+- Skill、Plugin 和 MCP 默认只发现、不执行；启用前需要来源、版本/ref、哈希、许可证和依赖状态。
+- 没有可定位证据的事实性 Claim 必须是 `uncertain` 或被阻断；没有审批记录的副作用不能被当作完成。
+
+许可证：MIT。

package/{apps → dist/apps}/panel/index.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>psyclaw 科研工作台 & 交互中心</title>
+<title>PsyClaw 科研工作台 & 交互中心</title>
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
@@ -19,24 +19,24 @@
     --bg-inner: #090d14;
     --line: rgba(255, 255, 255, 0.08);
     --line-highlight: rgba(46, 196, 182, 0.28);
-    
+
     --ink: #f0f4fc;
     --ink-muted: #8e9bb2;
     --ink-faint: #5a667d;
-    
+
     --accent: #2ec4b6;
     --accent-glow: rgba(46, 196, 182, 0.25);
     --accent-ink: #64e5d9;
     --accent-bg: rgba(46, 196, 182, 0.12);
-    
+
     --ok: #22c55e;
     --ok-bg: rgba(34, 197, 94, 0.12);
     --ok-ink: #4ade80;
-    
+
     --warn: #f59e0b;
     --warn-bg: rgba(245, 158, 11, 0.12);
     --warn-ink: #fbbf24;
-    
+
     --crit: #f43f5e;
     --crit-bg: rgba(244, 63, 94, 0.12);
     --crit-ink: #fb7185;
@@ -54,24 +54,24 @@
     --bg-inner: #f1f5f9;
     --line: rgba(0, 0, 0, 0.09);
     --line-highlight: rgba(13, 148, 136, 0.4);
-    
+
     --ink: #0f172a;
     --ink-muted: #475569;
     --ink-faint: #94a3b8;
-    
+
     --accent: #0d9488;
     --accent-glow: rgba(13, 148, 136, 0.2);
     --accent-ink: #0f766e;
     --accent-bg: rgba(13, 148, 136, 0.1);
-    
+
     --ok: #16a34a;
     --ok-bg: rgba(22, 163, 74, 0.1);
     --ok-ink: #15803d;
-    
+
     --warn: #d97706;
     --warn-bg: rgba(217, 119, 6, 0.1);
     --warn-ink: #b45309;
-    
+
     --crit: #e11d48;
     --crit-bg: rgba(225, 29, 72, 0.1);
     --crit-ink: #be123c;
@@ -89,24 +89,24 @@
     --bg-inner: #ece4d2;
     --line: rgba(80, 60, 40, 0.12);
     --line-highlight: rgba(180, 83, 9, 0.38);
-    
+
     --ink: #2b261f;
     --ink-muted: #665c4e;
     --ink-faint: #9c907e;
-    
+
     --accent: #b45309;
     --accent-glow: rgba(180, 83, 9, 0.2);
     --accent-ink: #92400e;
     --accent-bg: rgba(180, 83, 9, 0.1);
-    
+
     --ok: #2e7d32;
     --ok-bg: rgba(46, 125, 50, 0.1);
     --ok-ink: #1b5e20;
-    
+
     --warn: #c2410c;
     --warn-bg: rgba(194, 65, 12, 0.1);
     --warn-ink: #9a3412;
-    
+
     --crit: #b91c1c;
     --crit-bg: rgba(185, 28, 28, 0.1);
     --crit-ink: #991b1b;
@@ -124,24 +124,24 @@
     --bg-inner: #0b1120;
     --line: rgba(148, 163, 184, 0.14);
     --line-highlight: rgba(56, 189, 248, 0.38);
-    
+
     --ink: #f8fafc;
     --ink-muted: #94a3b8;
     --ink-faint: #64748b;
-    
+
     --accent: #38bdf8;
     --accent-glow: rgba(56, 189, 248, 0.25);
     --accent-ink: #7dd3fc;
     --accent-bg: rgba(56, 189, 248, 0.12);
-    
+
     --ok: #22c55e;
     --ok-bg: rgba(34, 197, 94, 0.12);
     --ok-ink: #4ade80;
-    
+
     --warn: #f59e0b;
     --warn-bg: rgba(245, 158, 11, 0.12);
     --warn-ink: #fbbf24;
-    
+
     --crit: #f43f5e;
     --crit-bg: rgba(244, 63, 94, 0.12);
     --crit-ink: #fb7185;
@@ -316,6 +316,28 @@
     font-size: 0.75rem;
     font-weight: 600;
   }
+  @media (max-width: 430px) {
+    .header { padding: 0.65rem 0.75rem; }
+    .header-inner {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      gap: 0.6rem;
+      width: 100%;
+    }
+    .brand { min-width: 0; gap: 0.5rem; }
+    .brand-tag { display: none; }
+    .nav-tabs {
+      grid-column: 1 / -1;
+      grid-row: 2;
+      min-width: 0;
+      width: 100%;
+    }
+    .header-status { gap: 0.35rem; }
+    .theme-btn { padding-inline: 5px; }
+    .pulse-indicator { padding-inline: 0.45rem; }
+    #heartbeat-text { display: none; }
+    main { padding: 1rem 0.75rem 4rem; }
+  }
   .pulse-dot {
     width: 7px;
     height: 7px;
@@ -1100,9 +1122,9 @@
     <a href="#" class="brand">
       <div class="brand-logo">ψ</div>
       <div>
-        <div class="brand-title">psyclaw</div>
+        <div class="brand-title">PsyClaw</div>
       </div>
-      <span class="brand-tag">工作台 v0.3.2</span>
+      <span class="brand-tag">工作台 v0.24.0</span>
     </a>
 
     <!-- Main Navigation Tabs -->
@@ -1166,7 +1188,7 @@
           <div class="msg-bubble assistant">
             <div class="msg-avatar">ψ</div>
             <div class="msg-content">
-              <strong>您好，我是 psyclaw 科研智能助手。</strong><br>
+              <strong>您好，我是 PsyClaw 科研智能助手。</strong><br>
               我基于严密的证据链（Claim-Evidence Ledger）工作。您可以直接向我提问、委托文献综述核验、审查统计方案，或点击上方的快速快捷指令开始。
             </div>
           </div>
@@ -1421,7 +1443,7 @@
           <span class="pill neutral" id="probe-status-pill"><span class="dot"></span> 尚无论断</span>
           <span class="detail-key mono" id="probe-claim-id">—</span>
         </div>
-        
+
         <div>
           <h4 style="font-size:1.02rem;color:var(--ink);margin-bottom:0.3rem;" id="probe-source-title">（从真实证据账本加载）</h4>
           <div class="mono" style="font-size:0.78rem;color:var(--ink-muted);" id="probe-doi-link">DOI: —</div>
@@ -2653,11 +2675,11 @@ function applyClaimProbe(idx) {
   });
   const data = PANEL_CLAIMS[idx];
   document.getElementById("probe-claim-id").textContent = data.id;
-  
+
   const statusPill = document.getElementById("probe-status-pill");
   statusPill.className = data.statusClass;
   statusPill.innerHTML = `<span class="dot"></span> ${data.status}`;
-  
+
   document.getElementById("probe-source-title").textContent = data.title;
   const doiEl = document.getElementById("probe-doi-link");
   if (data.doiUrl !== "#") {
@@ -2789,7 +2811,7 @@ function selectAuditorClaim(idx) {
   document.getElementById("audit-input-doi").value = d.doi;
   document.getElementById("audit-input-quote").value = d.quote;
   document.getElementById("audit-select-status").value = d.status.includes("缺口") || d.status.includes("不足") ? "uncertain" : "verified";
-  
+
   const pill = document.getElementById("auditor-status-pill");
   pill.className = d.statusClass;
   pill.textContent = d.status;

package/dist/src/adapters/pi/extension.d.ts

@@ -0,0 +1,19 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+type ToolTextContent = {
+    type: "text";
+    text: string;
+};
+interface ToolResultShape {
+    content: ToolTextContent[];
+    details: Record<string, unknown>;
+}
+/**
+ * Explicit workflow dispatch shared by the workbench's direct (`workflow`
+ * parameter) and natural-language routed paths, so every workflow result has
+ * the same `psyclaw/workflow-result/v1` contract.
+ */
+export declare function runWorkflowTool(root: string, workflow: string, target?: string, nStudies?: number): Promise<ToolResultShape>;
+/** Turn a natural-language meta-analysis request into a searchable target. */
+export declare function cleanMetaTarget(request: string): string;
+export default function psyclawExtension(pi: ExtensionAPI): void;
+export {};