psyclaw 0.27.7 → 0.27.12

package/README.md

@@ -1,21 +1,21 @@
 # PsyClaw
 
-PsyClaw 是面向社会科学研究的 Pi 工作台。它把研究项目、证据来源、Claim-Evidence 账本、完整性门禁、人工裁决、可恢复工作流和本地面板接到官方 Pi runtime 上；它不替代统计软件，也不会把未经核验的引用、结果或审稿意见写成事实。
+PsyClaw 是面向社会科学研究的智能体工作台。它把研究项目、证据来源、Claim-Evidence 账本、完整性门禁、人工裁决、可恢复工作流和本地面板接到内置运行时上；它不替代统计软件，也不会把未经核验的引用、结果或审稿意见写成事实。
 
-当前版本：`0.27.7`。本仓库以 `psypi v0.4.1` 的完整工作台为功能基线完成改名；`psypi` 仓库保留为历史仓库，正式命令和后续发布均使用 `psyclaw`。
+当前版本：`0.27.12`。正式命令、用户配置目录和后续发布统一使用 `psyclaw`。
 
 ## 安装
 
 需要 Node.js `>=22.19.0`。官方 npm 源：
 
 ```powershell
-npm install -g psyclaw@0.27.7
+npm install -g psyclaw@0.27.12
 ```
 
 中国大陆网络较慢或无法访问官方源时：
 
 ```powershell
-npm install -g psyclaw@0.27.7 --registry=https://registry.npmmirror.com
+npm install -g psyclaw@0.27.12 --registry=https://registry.npmmirror.com
 ```
 
 确认命令入口：
@@ -24,7 +24,7 @@ npm install -g psyclaw@0.27.7 --registry=https://registry.npmmirror.com
 psyclaw --help
 ```
 
-直接运行 `psyclaw` 会启动交互研究工作台；首次没有模型配置时会进入配置向导。向导会检查当前进程、macOS `launchctl` 和已有用户凭据，也允许直接遮罩输入 Key。`launchctl` Key 只注入当前运行进程、不落盘；登录 shell 仅在用户明确按 `Ctrl+I` 后读取。直接输入或明确导入的 Key 只保存到 Pi 用户级 `auth.json`，不会写入项目或 `models.json`。也可显式运行 `psyclaw wizard`，或使用 `psyclaw setup --provider deepseek` 写入仅引用环境变量的预设。不要把 API key 写进命令参数、项目、README 或 Git 仓库。
+直接运行 `psyclaw` 会启动交互研究工作台；首次没有模型配置时会进入配置向导。向导会检查当前进程、macOS `launchctl` 和已有用户凭据，也允许直接遮罩输入 Key。`launchctl` Key 只注入当前运行进程、不落盘；登录 shell 仅在用户明确按 `Ctrl+I` 后读取。直接输入或明确导入的 Key 只保存到 PsyClaw 用户级 `auth.json`，不会写入项目或 `models.json`。也可显式运行 `psyclaw wizard`，或使用 `psyclaw setup --provider deepseek` 写入仅引用环境变量的预设。不要把 API key 写进命令参数、项目、README 或 Git 仓库。
 
 ## 五分钟开始
 
@@ -37,7 +37,7 @@ psyclaw init "社交支持与研究生心理健康的关系" --paradigm survey-o
 psyclaw
 ```
 
-初始化会建立 `.psyclaw/`、`data/raw/`、`data/clean/`、`literature/pdfs/`、`notes/` 和 `outputs/`，不再生成通用 `artifacts/` 目录。`data/raw/` 是只读保护区；把经确认可用于分析的派生数据放在 `data/clean/`。
+初始化会建立 `.psyclaw/data/raw/`、`data/clean/`、`literature/pdfs/`、`notes/` 和 `outputs/`，不再把原始数据目录暴露在项目根目录。`.psyclaw/data/raw/` 是只读保护区；旧项目的 `data/raw/` 仍保持只读兼容，把经确认可用于分析的派生数据放在 `data/clean/`。
 
 在对话界面中，`/init <研究目标>` 只初始化研究项目和规格，随后使用 `/run [本轮目标]` 才启动受控研究流程。没有依次运行 `/init` 和 `/run` 时，PsyClaw 保持普通对话模式，不强制加入研究门禁或阶段式询问。
 
@@ -61,16 +61,19 @@ psyclaw brief
 | 创建人工裁决模板 | `psyclaw hitl init` |
 | 写研究移交记录 | `psyclaw handoff` |
 | 扫描本机其他 Agent | `psyclaw agents` |
-| 查看 PsyClaw 和内置 Pi 更新 | `psyclaw check-updates` |
-| 更新 PsyClaw 和内置 Pi | `psyclaw update` |
+| 查看 PsyClaw 和内置运行时更新 | `psyclaw check-updates` |
+| 更新 PsyClaw 和内置运行时 | `psyclaw update` |
 | 导出完整使用路径 | 在对话中输入 `/export` |
 | 打开科研面板 | 在对话中输入 `/panel` |
 | 查看或切换 Provider | 在对话中输入 `/provider` 或 `/provider <id>` |
 | 管理启动横幅宠物 | `/pet status`、`/pet on`、`/pet off`（默认关闭） |
-| 调用本机 Skill | `/skill <name> [任务]` 或 Pi 原生 `/skill:<name>` |
+| 安装本地 Skill | `/skill install <本地目录>` |
+| 管理或安装 Skill | `/skill` 或 `/skill install <本地目录>` |
+| 调用已加载 Skill | `/skill:<name>` |
+| 管理 Plugin | `/plugin`；终端使用 `psyclaw plugin install|remove|list` |
 | 调用已配置 MCP | 模型通过 `psyclaw_mcp` 自动发现并调用 `.psyclaw/mcp/*.json` 中启用的服务器 |
 
-`psyclaw update` 会更新 PsyClaw 整包，并同时安装该版本锁定、验证过的内置 Pi；它不会更新或删除系统中单独安装的 `pi` 命令。在源码仓库中运行时，命令会停止并提示通过 Git 更新，不会覆盖本地修改。
+`psyclaw update` 会更新 PsyClaw 整包，并同时安装该版本锁定的内置运行时。在源码仓库中运行时，命令会停止并提示通过 Git 更新，不会覆盖本地修改。
 仅查看更新计划而不执行时，使用 `psyclaw update --check`。旧的 `--yes` 参数仍兼容，但不再需要。
 
 ### 导出使用路径
@@ -79,7 +82,7 @@ psyclaw brief
 /export
 ```
 
-该斜杠命令直接在 PsyClaw 对话界面中使用，从当前项目的工作流日志和对应 Pi 会话中生成 `outputs/psyclaw-export.otlp.json`，用于通过 OpenTelemetry Collector 导入 Langfuse 或 LangSmith。导出文件包含对话正文、工具参数、研究内容、原始 ID 与绝对路径，只写入本地，不会自动上传；不要将其提交到公开仓库。终端入口为 `psyclaw export`。Panel 不再读取实时 Trace，只展示 `outputs/` 下已经显式生成的 Export 文件。
+该斜杠命令直接在 PsyClaw 对话界面中使用，从当前项目的工作流日志和对应会话中生成 `outputs/psyclaw-export.otlp.json`，用于通过 OpenTelemetry Collector 导入 Langfuse 或 LangSmith。导出文件包含对话正文、工具参数、研究内容、原始 ID 与绝对路径，只写入本地，不会自动上传；不要将其提交到公开仓库。终端入口为 `psyclaw export`。Panel 不再读取实时 Trace，只展示 `outputs/` 下已经显式生成的 Export 文件。
 
 ## 开发者本地安装
 

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

@@ -1,20 +1,20 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { asProject, bootstrapProject, exportTraces, projectPaths, runOfflineBrief, runInstitutionalFulltext, runLiteratureReview, runExpertReview, runAnalysisDelegation, runWritingReview, runMetaAnalysis, createStageRunner, exportAcademicDocument, recordCitationUse, runParallelPeerReview, writeHandoff } from "../../index.js";
+import { appendApproval, approvalInputDigest, approvePrimaryDocument, asProject, bootstrapProject, DEFAULT_RUN_APPROVAL_NODES, exportTraces, PRIMARY_PLAN_DOCUMENTS, primaryPlanApprovalStatus, projectPaths, runOfflineBrief, runInstitutionalFulltext, runLiteratureReview, runExpertReview, runAnalysisDelegation, runWritingReview, runMetaAnalysis, createStageRunner, exportAcademicDocument, recordCitationUse, runParallelPeerReview, writeHandoff } from "../../index.js";
 import { runPlanWithPi } from "../../orchestration/pi-executor.js";
 import { atomicWriteFile } from "../../project/jsonl.js";
 import { RunEventLog } from "../../panel/events.js";
 import { readProject } from "../../research/ledger.js";
 import { join } from "node:path";
 import { lstat, mkdir, readFile } from "node:fs/promises";
-import { PROVIDER_PRESETS, saveProviderConfig } from "../../setup.js";
+import { PROVIDER_PRESETS, providerCredentialSource, saveProviderConfig } from "../../setup.js";
 import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { coreSkillNames, enabledRecommendedSkillPaths, normalizeRecommendedSkillId, readRecommendationState, readRecommendedCatalog, recommendedSkillTarget, saveRecommendationState, validateModelInstalledRecommendedSkill, } from "../../skills/recommended.js";
 import { SkillManagerComponent } from "../../tui/skill-manager.js";
-import { enabledLocalSkillPaths, enabledLocalPromptPaths, readUserSkillState, scanLocalSkills, setLocalSkillEnabled, setLocalSkillsEnabled, skillNamesInPaths, userSkillId, } from "../../skills/user-skills.js";
+import { enabledLocalSkillPaths, enabledLocalPromptPaths, readUserSkillState, scanLocalSkills, setLocalSkillEnabled, setLocalSkillsEnabled, skillNamesInPaths, installLocalSkill, userSkillId, } from "../../skills/user-skills.js";
 import { RuntimeMcpRegistry, setUserMcpConfigEnabled, } from "../../integrations/mcp-runtime.js";
-import { ProviderPickerComponent, SecretInputComponent, } from "../../tui/provider-picker.js";
+import { SecretInputComponent, } from "../../tui/provider-picker.js";
 const PARADIGMS = new Set([
     "survey-observational",
     "qualitative-thematic",
@@ -47,7 +47,17 @@ function parseInitArgs(args) {
 async function notifyError(ctx, error) {
     ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
 }
+async function runPluginCommand(args) {
+    const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+    const modulePath = join(dirname(entry), "package-manager-cli.js");
+    const { handlePackageCommand } = await import(pathToFileURL(modulePath).href);
+    const handled = await handlePackageCommand(args);
+    if (!handled)
+        throw new Error(`不支持的 Plugin 操作：${args[0] ?? ""}`);
+}
 const activeAgentRuns = new Set();
+const pendingInitApprovals = new Set();
+const activeApprovalDialogs = new Set();
 const CORE_SKILLS = new Set(["academic-grill", "research-intake", "evidence-capture", "citation-audit", "research-brief"]);
 function coreSkillPath(name) {
     return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "skills", "core", name, "SKILL.md");
@@ -110,8 +120,10 @@ async function saveDefaultModel(provider, model) {
     await atomicWriteFile(path, `${JSON.stringify({ ...settings, defaultProvider: provider, defaultModel: model }, null, 2)}\n`);
 }
 async function pickProviderItem(ctx, title, items) {
-    const result = await ctx.ui.custom((tui, theme, keybindings, done) => new ProviderPickerComponent(title, items, tui, theme, keybindings, done));
-    return result.type === "select" ? result.id : undefined;
+    const labels = items.map((item) => `${item.current ? "* " : ""}${item.label} (${item.id})`);
+    const selected = await ctx.ui.select(title, labels, { timeout: 60_000 });
+    const index = selected === undefined ? -1 : labels.indexOf(selected);
+    return index < 0 ? undefined : items[index].id;
 }
 async function promptProviderKey(ctx, providerName, envName) {
     const result = await ctx.ui.custom((tui, theme, keybindings, done) => new SecretInputComponent(`配置 ${providerName}`, envName, tui, theme, keybindings, done));
@@ -154,7 +166,7 @@ function academicGrillRequest(subject, mode) {
         "从最上游、影响最大的未决问题开始。每一轮只问一个问题，同时给出你的推荐答案或推荐决策及主要取舍。",
         "明确区分探索性与确证性研究，不把规划内容当作已有证据。直到关键分支已经解决或明确交由研究者决定后，再整理研究规格。",
         mode === "init"
-            ? "持久化模式：init。追问完成后直接更新 academic-grill Skill 规定的全部项目文档，不再询问是否更新；写入后列出实际更新的文件。"
+            ? "持久化模式：init。追问完成后直接更新 academic-grill Skill 规定的全部项目文档，不再询问是否更新；写入后列出实际更新的文件，并把 notes/research-spec.md 与 notes/plan.md 的 Status 统一写为 awaiting-human-approval。"
             : "持久化模式：review。追问完成后先展示拟更新摘要和受影响文件，并询问我是否写回；得到明确确认前不得修改项目文档。",
     ].join("\n");
 }
@@ -165,32 +177,37 @@ async function readControlledRun(root) {
     try {
         const value = JSON.parse(await readFile(await controlledRunPath(root), "utf8"));
         return value.schemaVersion === "psyclaw/controlled-run/v1" && value.status === "active" && typeof value.projectId === "string" && typeof value.objective === "string" && typeof value.activatedAt === "string"
-            ? { ...value, selectedSkills: Array.isArray(value.selectedSkills) ? value.selectedSkills.filter((item) => typeof item === "string") : [] }
+            ? { ...value, runId: typeof value.runId === "string" ? value.runId : `legacy_${value.projectId}`, mode: value.mode === "auto" ? "auto" : "human", selectedSkills: Array.isArray(value.selectedSkills) ? value.selectedSkills.filter((item) => typeof item === "string") : [] }
             : null;
     }
     catch {
         return null;
     }
 }
-async function activateControlledRun(root, projectId, objective, selectedSkills) {
+async function activateControlledRun(root, runId, projectId, objective, selectedSkills, mode) {
     const state = {
         schemaVersion: "psyclaw/controlled-run/v1",
+        runId,
         projectId,
         objective,
         selectedSkills: [...new Set(selectedSkills)],
+        mode,
         activatedAt: new Date().toISOString(),
         status: "active",
     };
     await atomicWriteFile(await controlledRunPath(root), `${JSON.stringify(state, null, 2)}\n`);
     return state;
 }
-function controlledRunRequest(objective, selectedSkills) {
+function controlledRunRequest(objective, selectedSkills, mode) {
     return [
-        "PsyClaw 受控研究流程已由用户通过 /run 明确启动。先读取 .psyclaw/project.json、.psyclaw/controlled-run.json、notes/research-spec.md 和 notes/plan.md。",
+        `PsyClaw ${mode === "auto" ? "自动" : "人在环路"}研究流程已由用户通过 /run 明确启动。先读取 .psyclaw/project.json、.psyclaw/controlled-run.json、.psyclaw/approvals.jsonl、notes/research-spec.md 和 notes/plan.md。`,
         `本次目标：${objective}`,
         selectedSkills.length > 0
             ? `本次运行由用户选择的优化 Skill：${selectedSkills.join(", ")}。在相关任务中优先加载并遵循这些 Skill；同名 Skill 只加载一次。`
             : "本次运行未指定额外 Skill，使用 PsyClaw 默认研究流程。不要删除、停用或改写已安装的其他 Skill。",
+        mode === "auto"
+            ? "自动模式：计划内普通步骤连续推进，不再逐项询问；运行时会自动记录审批。原始数据、凭据、破坏性命令、伦理决定、未经核验的事实与外部发布仍必须停止并请求用户决定。"
+            : "人在环路模式：每个有副作用或关键方法决策的步骤都必须通过交互审批；拒绝或超时立即停止，不得绕过审批。",
         "实际推进当前尚未完成的研究任务；先形成或更新符合学术规范的 Markdown 分析报告，不能只描述计划。分析报告必须清楚区分数据来源、统计结果、文献证据、限制与尚未核验内容。",
         "分析报告完成后，下一步不是直接询问是否导出 DOCX，而是询问用户是否据此撰写论文。",
         "若用户选择撰写论文，再单独询问是否先进行文献调研，并说明该阶段可能花费较长时间；提示用户可以指定已启用的 Skill，或者选择 PsyClaw 默认的文献调研方式。不要在获得答复前自动开始长时调研。",
@@ -202,16 +219,92 @@ function controlledRunRequest(objective, selectedSkills) {
 }
 function parseRunArgs(args) {
     const value = args.trim();
-    if (!value.startsWith("--skills"))
-        return { objective: value };
-    const match = value.match(/^--skills(?:=|\s+)([^\s]+)(?:\s+([\s\S]*))?$/);
+    const auto = value === "auto" || value.startsWith("auto ");
+    const rest = auto ? value.slice(4).trim() : value;
+    if (!rest.startsWith("--skills"))
+        return { objective: rest, mode: auto ? "auto" : "human" };
+    const match = rest.match(/^--skills(?:=|\s+)([^\s]+)(?:\s+([\s\S]*))?$/);
     if (!match)
-        throw new Error("Usage: /run [--skills skill-a,skill-b] [objective]");
+        throw new Error("Usage: /run [auto] [--skills skill-a,skill-b] [objective]");
     return {
         objective: (match[2] ?? "").trim(),
         requestedSkills: [...new Set(match[1].split(",").map((item) => item.trim()).filter(Boolean))],
+        mode: auto ? "auto" : "human",
     };
 }
+async function planDocumentsReady(root) {
+    try {
+        const [spec, plan] = await Promise.all([
+            readFile(join(root, "notes", "research-spec.md"), "utf8"),
+            readFile(join(root, "notes", "plan.md"), "utf8"),
+        ]);
+        return /Status:\s*awaiting-human-approval/i.test(spec) && /Status:\s*awaiting-human-approval/i.test(plan);
+    }
+    catch {
+        return false;
+    }
+}
+async function reviewPrimaryDocuments(ctx) {
+    if (!ctx.hasUI || activeApprovalDialogs.has(ctx.cwd))
+        return false;
+    if (!(await planDocumentsReady(ctx.cwd))) {
+        ctx.ui.notify("主要计划文档尚未生成完成；请先完成 /init 的学术追问。", "warning");
+        return false;
+    }
+    activeApprovalDialogs.add(ctx.cwd);
+    try {
+        for (const document of PRIMARY_PLAN_DOCUMENTS) {
+            const choice = await ctx.ui.select(`审批${document.title}：${document.path}`, ["批准当前版本", "拒绝并返回修改"], { timeout: 120_000 });
+            const approved = choice === "批准当前版本";
+            await approvePrimaryDocument(ctx.cwd, document, approved ? "approved" : "rejected");
+            if (!approved) {
+                ctx.ui.notify(`${document.title}未批准；修改后运行 /approve 重新审批。`, "warning");
+                return false;
+            }
+        }
+        ctx.ui.notify("主要计划文档已批准。文档内容变化后审批会自动失效。", "info");
+        return true;
+    }
+    finally {
+        activeApprovalDialogs.delete(ctx.cwd);
+    }
+}
+async function approveRunNodes(ctx, runId, mode) {
+    for (const node of DEFAULT_RUN_APPROVAL_NODES) {
+        if (mode === "auto") {
+            await appendApproval(ctx.cwd, { kind: "step", nodeId: node.id, decision: "auto-approved", actor: "auto", runId, summary: node.summary });
+            continue;
+        }
+        const options = node.required ? ["批准", "拒绝并停止"] : ["批准", "本次跳过", "拒绝并停止"];
+        const choice = await ctx.ui.select(`${node.title}\n${node.summary}`, options, { timeout: 120_000 });
+        const decision = choice === "批准" ? "approved" : choice === "本次跳过" ? "skipped" : "rejected";
+        await appendApproval(ctx.cwd, { kind: "step", nodeId: node.id, decision, actor: "human", runId, summary: node.summary });
+        if (decision === "rejected" || (node.required && decision !== "approved"))
+            return false;
+    }
+    return true;
+}
+function toolApprovalSummary(toolName, input) {
+    const record = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+    const target = [record.path, record.file_path, record.command, record.action, record.server, record.tool]
+        .find((value) => typeof value === "string");
+    return `${toolName}${target ? `: ${target.slice(0, 240)}` : ""}`;
+}
+function toolNeedsApproval(toolName, input) {
+    if (["write", "edit", "bash", "powershell", "psyclaw_workbench", "psyclaw_mcp"].includes(toolName))
+        return true;
+    const action = input && typeof input === "object" && !Array.isArray(input) ? input.action : undefined;
+    return typeof action === "string" && /write|save|publish|install|download|execute|call/i.test(action);
+}
+function autoApprovalBlocked(toolName, input) {
+    const text = JSON.stringify(input ?? {}).toLocaleLowerCase();
+    if (/data[\\/]raw|credential|secret|auth\.json|api[_ -]?key/.test(text))
+        return "自动模式不能批准原始数据或凭据路径操作";
+    if (["bash", "powershell"].includes(toolName) && /\b(rm|rmdir|del|remove-item|format|shutdown|reboot|git\s+reset\s+--hard)\b/i.test(text)) {
+        return "自动模式不能批准破坏性命令";
+    }
+    return undefined;
+}
 async function selectableRunSkills(root) {
     const state = await readRecommendationState(root);
     const rows = await skillManagerRows(root, state);
@@ -244,7 +337,7 @@ function resolveRunSkills(requested, available) {
             selected.push(name);
     }
     if (unknown.length > 0)
-        throw new Error(`本次运行不可用的 Skill：${unknown.join(", ")}。请先通过 /skills 安装或启用。`);
+        throw new Error(`本次运行不可用的 Skill：${unknown.join(", ")}。请先通过 /skill 安装或启用。`);
     return selected;
 }
 async function recommendedItems(kind) {
@@ -597,12 +690,12 @@ function modelSkillInstallTask(root, row, scope) {
         ...(row.installHint ? [`仓库入口提示：${row.installHint}`] : []),
         `安装位置：${skillScopeLabel(scope)}。`,
         `唯一允许的最终目标目录：${target}`,
-        "用户已通过 Skill 管理页授权本次安装。请使用当前会话的联网、文件和命令工具读取来源仓库，并直接下载、安装所需依赖和完成 Skill 安装；不要再次要求安装权限。不要写入其他 Skill 目录，不要修改 data/raw、.git 或研究产物。",
+        "用户已通过 Skill 管理页授权本次安装。请使用当前会话的联网、文件和命令工具读取来源仓库，并直接下载、安装所需依赖和完成 Skill 安装；不要再次要求安装权限。不要写入其他 Skill 目录，不要修改 .psyclaw/data/raw、data/raw、.git 或研究产物。",
         row.collection
             ? "这是多 Skill 套件：目标目录自身无需 SKILL.md，但其子目录必须包含一个或多个有效 SKILL.md。保留套件内共享目录和相对路径，不得包含 .git、符号链接或凭据。"
             : "目标目录最终必须直接包含有效 SKILL.md（YAML frontmatter 至少包含 name 和 description），不得包含 .git、符号链接、凭据或二进制大文件。",
         "如果仓库包含多个 Skill，只安装与此推荐项相符的部分；如果它不是 Skill 或无法合理适配，停止并说明原因，不要伪造 SKILL.md。",
-        "安装完成后检查目标目录结构，并提醒用户执行 /skills 启用该项，再执行 /reload。",
+        "安装完成后检查目标目录结构，并提醒用户执行 /skill 启用该项，再执行 /reload。",
     ].join("\n");
 }
 async function chooseSkillScope(ctx) {
@@ -628,17 +721,17 @@ async function queueModelSkillInstall(pi, ctx, row) {
     state.skillScopes = { ...(state.skillScopes ?? {}), [row.id]: scope };
     await saveRecommendationState(ctx.cwd, state);
     pi.sendUserMessage(modelSkillInstallTask(ctx.cwd, row, scope), ctx.isIdle() ? {} : { deliverAs: "followUp" });
-    ctx.ui.notify(`已将 ${row.name} 的安装任务交给当前模型，目标为${skillScopeLabel(scope)}。安装完成后请在 /skills 中启用，再执行 /reload。`, "info");
+    ctx.ui.notify(`已将 ${row.name} 的安装任务交给当前模型，目标为${skillScopeLabel(scope)}。安装完成后请在 /skill 中启用，再执行 /reload。`, "info");
 }
 async function showSkillManager(pi, args, ctx) {
     const action = args.trim().split(/\s+/).filter(Boolean);
     const verb = action[0];
     const id = action[1];
     if (verb && !["status", "enable", "disable", "enable-all", "disable-all", "install"].includes(verb)) {
-        throw new Error("Usage: /skills [status|enable <id>|disable <id>|enable-all|disable-all|install <id>]");
+        throw new Error("Usage: /skill [status|enable <id>|disable <id>|enable-all|disable-all]");
     }
     if ((verb === "enable" || verb === "disable" || verb === "install") && !id) {
-        throw new Error(`Usage: /skills ${verb} <id>`);
+        throw new Error(`Usage: /skill ${verb} <id>`);
     }
     if (verb === "install") {
         const row = (await skillManagerRows(ctx.cwd, await readRecommendationState(ctx.cwd))).find((candidate) => candidate.id === normalizeRecommendedSkillId(id));
@@ -858,17 +951,14 @@ export default function psyclawExtension(pi) {
     const legacyTestApi = typeof pi.registerTool !== "function";
     const runtimeMcps = new RuntimeMcpRegistry();
     if (!legacyTestApi && typeof pi.on === "function")
-        pi.on("resources_discover", async (event, ctx) => {
+        pi.on("resources_discover", async (event) => {
             const enabled = await enabledRecommendedSkillPaths(event.cwd);
-            for (const warning of enabled.warnings)
-                ctx.ui.notify(`PsyClaw Skill: ${warning}`, "warning");
             const local = await enabledLocalSkillPaths(event.cwd, {
                 excludedNames: [...coreSkillNames(), ...await skillNamesInPaths(enabled.paths)],
             });
-            for (const warning of local.warnings)
-                ctx.ui.notify(`PsyClaw Skill: ${warning}`, "warning");
             // Return only existing Skill directories. Same-name local/core candidates
-            // are resolved before Pi sees them, so harmless collisions stay silent.
+            // are resolved before Pi sees them. Discovery warnings belong in /skill;
+            // they should not interrupt every startup.
             return {
                 skillPaths: [...enabled.paths, ...local.paths],
                 promptPaths: await enabledLocalPromptPaths(event.cwd),
@@ -876,6 +966,47 @@ export default function psyclawExtension(pi) {
         });
     if (!legacyTestApi && typeof pi.on === "function")
         pi.on("session_shutdown", () => runtimeMcps.close());
+    if (!legacyTestApi && typeof pi.on === "function")
+        pi.on("tool_call", async (event, ctx) => {
+            const run = await readControlledRun(ctx.cwd);
+            if (!run || !toolNeedsApproval(event.toolName, event.input))
+                return;
+            const summary = toolApprovalSummary(event.toolName, event.input);
+            if (run.mode === "auto") {
+                const blockedReason = autoApprovalBlocked(event.toolName, event.input);
+                await appendApproval(ctx.cwd, {
+                    kind: "tool",
+                    nodeId: event.toolCallId,
+                    decision: blockedReason ? "rejected" : "auto-approved",
+                    actor: "auto",
+                    runId: run.runId,
+                    sha256: approvalInputDigest({ toolName: event.toolName, input: event.input }),
+                    summary: blockedReason ?? summary,
+                });
+                return blockedReason ? { block: true, terminate: true, reason: blockedReason } : undefined;
+            }
+            if (!ctx.hasUI)
+                return { block: true, terminate: true, reason: "该步骤需要人在环路审批，但当前没有交互界面" };
+            const choice = await ctx.ui.select(`审批执行步骤\n${summary}`, ["批准本次执行", "拒绝并停止"], { timeout: 120_000 });
+            const approved = choice === "批准本次执行";
+            await appendApproval(ctx.cwd, {
+                kind: "tool",
+                nodeId: event.toolCallId,
+                decision: approved ? "approved" : "rejected",
+                actor: "human",
+                runId: run.runId,
+                sha256: approvalInputDigest({ toolName: event.toolName, input: event.input }),
+                summary,
+            });
+            return approved ? undefined : { block: true, terminate: true, reason: "用户拒绝该执行步骤或审批超时" };
+        });
+    if (!legacyTestApi && typeof pi.on === "function")
+        pi.on("agent_end", async (_event, ctx) => {
+            if (!pendingInitApprovals.has(ctx.cwd) || !(await planDocumentsReady(ctx.cwd)))
+                return;
+            pendingInitApprovals.delete(ctx.cwd);
+            await reviewPrimaryDocuments(ctx);
+        });
     pi.registerCommand("init", {
         description: "初始化可追溯的研究项目",
         handler: async (args, ctx) => {
@@ -883,8 +1014,9 @@ export default function psyclawExtension(pi) {
                 const parsed = parseInitArgs(args);
                 const project = await bootstrapProject({ root: ctx.cwd, ...parsed });
                 if (typeof pi.sendUserMessage === "function") {
+                    pendingInitApprovals.add(ctx.cwd);
                     pi.sendUserMessage(academicGrillRequest(project.goal, "init"), ctx.isIdle() ? {} : { deliverAs: "followUp" });
-                    ctx.ui.notify(`研究项目已初始化：${project.id}（${project.paradigm}）。现在开始学术追问；准备好后使用 /run 启动受控研究流程。`, "info");
+                    ctx.ui.notify(`研究项目已初始化：${project.id}（${project.paradigm}）。学术追问完成并生成主要计划文档后会进入审批；全部批准后才能 /run。`, "info");
                 }
                 else {
                     ctx.ui.notify(`研究项目已初始化：${project.id}（${project.paradigm}）。使用 /run 启动受控研究流程。`, "info");
@@ -895,6 +1027,18 @@ export default function psyclawExtension(pi) {
             }
         },
     });
+    if (!legacyTestApi)
+        pi.registerCommand("approve", {
+            description: "审批 /init 生成的主要研究计划文档",
+            handler: async (_args, ctx) => {
+                try {
+                    await reviewPrimaryDocuments(ctx);
+                }
+                catch (error) {
+                    await notifyError(ctx, error);
+                }
+            },
+        });
     if (!legacyTestApi)
         pi.registerCommand("run", {
             description: "启动受控研究流程，可用 --skills a,b 选择本次优化 Skill",
@@ -919,8 +1063,16 @@ export default function psyclawExtension(pi) {
                         }
                         ctx.ui.notify("检测到合规的分析文档，已自动补齐研究项目记录并启动受控流程。", "info");
                     }
+                    const planApproval = await primaryPlanApprovalStatus(ctx.cwd);
+                    if (!planApproval.ok) {
+                        const missing = planApproval.documents.filter((item) => !item.approved).map((item) => item.path);
+                        ctx.ui.notify(`主要计划尚未批准或批准后已修改：${missing.join("、")}。请运行 /approve。`, "warning");
+                        return;
+                    }
                     const available = await selectableRunSkills(ctx.cwd);
                     let requestedSkills = parsed.requestedSkills;
+                    if (parsed.mode === "auto" && requestedSkills === undefined)
+                        requestedSkills = [];
                     if (requestedSkills === undefined && ctx.hasUI && typeof ctx.ui.input === "function") {
                         const answer = await ctx.ui.input("选择本次 Run 使用的 Skill（逗号分隔，可留空）", available.map((skill) => skill.name).join(", "));
                         if (answer === undefined) {
@@ -931,10 +1083,24 @@ export default function psyclawExtension(pi) {
                     }
                     const selectedSkills = resolveRunSkills(requestedSkills ?? [], available);
                     const objective = parsed.objective || project.goal;
-                    await activateControlledRun(ctx.cwd, project.id, objective, selectedSkills);
-                    pi.appendEntry("psyclaw:controlled-run", { projectId: project.id, objective, selectedSkills, activatedAt: new Date().toISOString() });
-                    pi.sendUserMessage(controlledRunRequest(objective, selectedSkills), ctx.isIdle() ? {} : { deliverAs: "followUp" });
-                    ctx.ui.notify(`受控研究流程已启动${selectedSkills.length > 0 ? `；本次使用 Skill：${selectedSkills.join(", ")}` : "；使用默认 Skill"}。分析完成后会先询问是否撰写论文。`, "info");
+                    const runId = `run_${Date.now()}`;
+                    await appendApproval(ctx.cwd, {
+                        kind: "run-mode",
+                        nodeId: "run-mode",
+                        decision: parsed.mode === "auto" ? "auto-approved" : "approved",
+                        actor: parsed.mode === "auto" ? "auto" : "human",
+                        runId,
+                        sha256: approvalInputDigest({ projectId: project.id, objective, selectedSkills, mode: parsed.mode }),
+                        summary: parsed.mode === "auto" ? "用户选择自动运行模式" : "用户选择人在环路模式",
+                    });
+                    if (!(await approveRunNodes(ctx, runId, parsed.mode))) {
+                        ctx.ui.notify("运行审批被拒绝或超时，未启动。", "warning");
+                        return;
+                    }
+                    await activateControlledRun(ctx.cwd, runId, project.id, objective, selectedSkills, parsed.mode);
+                    pi.appendEntry("psyclaw:controlled-run", { runId, projectId: project.id, objective, selectedSkills, mode: parsed.mode, activatedAt: new Date().toISOString() });
+                    pi.sendUserMessage(controlledRunRequest(objective, selectedSkills, parsed.mode), ctx.isIdle() ? {} : { deliverAs: "followUp" });
+                    ctx.ui.notify(`${parsed.mode === "auto" ? "自动" : "人在环路"}研究流程已启动${selectedSkills.length > 0 ? `；本次使用 Skill：${selectedSkills.join(", ")}` : "；使用默认 Skill"}。`, "info");
                 }
                 catch (error) {
                     await notifyError(ctx, error);
@@ -1072,27 +1238,73 @@ export default function psyclawExtension(pi) {
             },
         });
     if (!legacyTestApi)
-        pi.registerCommand("skills", {
-            description: "打开 Skill 安装与启用管理页",
+        pi.registerCommand("skill", {
+            description: "管理和安装 Skill",
             handler: async (args, ctx) => {
-                try {
-                    await showSkillManager(pi, args, ctx);
+                const [name, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+                if (!name) {
+                    try {
+                        await showSkillManager(pi, "", ctx);
+                    }
+                    catch (error) {
+                        await notifyError(ctx, error);
+                    }
+                    return;
                 }
-                catch (error) {
-                    await notifyError(ctx, error);
+                if (name === "install") {
+                    const source = rest.join(" ").trim();
+                    if (!source) {
+                        ctx.ui.notify("Usage: /skill install <local-directory>", "info");
+                        return;
+                    }
+                    try {
+                        const installed = await installLocalSkill(source, ctx.cwd);
+                        ctx.ui.notify(`已安装本地 Skill ${installed.name}：${installed.target}。请执行 /reload。`, "info");
+                    }
+                    catch (error) {
+                        await notifyError(ctx, error);
+                    }
+                    return;
                 }
+                if (["status", "enable", "disable", "enable-all", "disable-all"].includes(name)) {
+                    try {
+                        await showSkillManager(pi, args, ctx);
+                    }
+                    catch (error) {
+                        await notifyError(ctx, error);
+                    }
+                    return;
+                }
+                ctx.ui.notify("Usage: /skill [status|enable <id>|disable <id>|enable-all|disable-all|install <local-directory>]", "info");
             },
         });
     if (!legacyTestApi)
-        pi.registerCommand("skill", {
-            description: "调用任意已加载 Skill（/skill <name> [任务]）",
+        pi.registerCommand("plugin", {
+            description: "管理 Plugin / Extension",
             handler: async (args, ctx) => {
-                const [name, ...rest] = args.trim().split(/\s+/).filter(Boolean);
-                if (!name || !/^[a-z0-9-]+$/.test(name)) {
-                    ctx.ui.notify("Usage: /skill <name> [task]；也可直接使用 /skill:<name>", "info");
-                    return;
+                try {
+                    const [action, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+                    if (!action) {
+                        ctx.ui.notify("Usage: /plugin list | install <source> [-l] | remove <source> [-l]", "info");
+                        return;
+                    }
+                    if (!["list", "install", "remove"].includes(action)) {
+                        throw new Error("Usage: /plugin list | install <source> [-l] | remove <source> [-l]");
+                    }
+                    if (action !== "list" && rest.length === 0)
+                        throw new Error(`Usage: /plugin ${action} <source> [-l]`);
+                    if (action !== "list") {
+                        const approved = await ctx.ui.confirm(`${action === "install" ? "安装" : "移除"} Plugin？`, `${rest.join(" ")}\nPlugin 与宿主进程同权限，操作完成后需要重启 PsyClaw。`);
+                        if (!approved)
+                            return;
+                    }
+                    await runPluginCommand([action, ...rest]);
+                    if (action !== "list")
+                        ctx.ui.notify("Plugin 配置已更新，请重启 PsyClaw。", "info");
+                }
+                catch (error) {
+                    await notifyError(ctx, error);
                 }
-                pi.sendUserMessage(`/skill:${name}${rest.length ? ` ${rest.join(" ")}` : ""}`, ctx.isIdle() ? {} : { deliverAs: "followUp" });
             },
         });
     if (!legacyTestApi)
@@ -1118,7 +1330,7 @@ export default function psyclawExtension(pi) {
                         const skillLines = skills.items.slice(0, 8).map((item) => `Skill: ${String(item.id)} — ${String(item.name)}`);
                         const mcpLines = mcps.items.slice(0, 8).map((item) => `MCP: ${String(item.id)} — ${String(item.name)}`);
                         const toolLines = skills.externalTools.slice(0, 8).map((item) => `外部工具: ${String(item.name)} — ${String(item.sourceRef ?? "请查看项目文档")}`);
-                        ctx.ui.notify(["推荐安装入口", "", ...skillLines, ...mcpLines, "", ...toolLines, "", "安装：/install skill|mcp <id>", "管理：/skills 或 /mcp", "外部工具不通过 Skill 安装器安装", "也可以打开 /panel 查看推荐页面"].join("\n"), "info");
+                        ctx.ui.notify(["推荐安装入口", "", ...skillLines, ...mcpLines, "", ...toolLines, "", "安装：/install skill|mcp <id>", "管理：/skill 或 /mcp", "外部工具不通过 Skill 安装器安装", "也可以打开 /panel 查看推荐页面"].join("\n"), "info");
                         return;
                     }
                     if (kind !== "skill" && kind !== "mcp")
@@ -1202,11 +1414,19 @@ export default function psyclawExtension(pi) {
                         selectedId = choice;
                     }
                     if (preset && ctx.hasUI && typeof ctx.ui.custom === "function") {
-                        const key = await promptProviderKey(ctx, preset.name, preset.apiKeyEnv);
+                        const credential = await providerCredentialSource(preset);
+                        const key = credential === "missing" ? await promptProviderKey(ctx, preset.name, preset.apiKeyEnv) : "";
                         if (key === undefined)
                             return;
                         await saveProviderConfig({ ...preset, ...(key ? { apiKey: key } : {}) });
-                        await ctx.modelRegistry.refresh();
+                        const refreshed = await Promise.race([
+                            ctx.modelRegistry.refresh().then(() => true),
+                            new Promise((resolve) => setTimeout(() => resolve(false), 5_000)),
+                        ]);
+                        if (!refreshed) {
+                            ctx.ui.notify("Provider 配置已保存；模型目录刷新超时，请重新启动 PsyClaw 后使用。", "warning");
+                            return;
+                        }
                         models = ctx.modelRegistry.getAll().filter((model) => model.provider === requested);
                     }
                     const selected = models.find((model) => model.id === selectedId);
@@ -1529,7 +1749,10 @@ export default function psyclawExtension(pi) {
                 }
             },
         });
-    if (developerCommands || legacyTestApi)
+    // Read-only multi-agent research is a user-facing capability.  Keep the
+    // destructive/developer commands gated, but do not hide the bounded agent
+    // runner behind PSYCLAW_DEVELOPER_COMMANDS in published builds.
+    if (!legacyTestApi)
         pi.registerCommand("agents", {
             description: "运行经批准的只读研究 Agent",
             handler: async (args, ctx) => {
@@ -1556,7 +1779,7 @@ export default function psyclawExtension(pi) {
                     ctx.ui.notify("请先使用 /init 初始化研究项目，再运行 /agents", "warning");
                     return;
                 }
-                const approved = await ctx.ui.confirm("Run read-only research worker?", "The worker runs in a separate Pi process with extensions, skills, context files, and mutating tools disabled.");
+                const approved = await ctx.ui.confirm("Run read-only research worker?", "The worker runs in a separate PsyClaw process with extensions, skills, context files, and mutating tools disabled.");
                 if (!approved) {
                     ctx.ui.notify("Agent run canceled", "info");
                     return;