psyclaw 0.29.4 → 0.29.5

package/README.md

@@ -4,7 +4,7 @@ PsyClaw 是面向社会科学研究的智能体工作台。它把研究项目、
 
 PsyClaw 自有代码使用 MIT 许可证；随 npm 包内置的 Academic Research Skills 位于 `vendor/ars`，保持上游署名并单独遵循 CC BY-NC 4.0，仅限非商业用途。
 
-当前版本：`0.29.4`。正式命令、用户配置目录和后续发布统一使用 `psyclaw`。
+当前版本：`0.29.5`。正式命令、用户配置目录和后续发布统一使用 `psyclaw`。
 
 ## 发布流程
 
@@ -21,22 +21,37 @@ RELEASE_MESSAGE="release: describe the change" pnpm release:push
 需要 Node.js `>=22.19.0`。官方 npm 源：
 
 ```powershell
-npm install -g psyclaw@0.29.4
+npm install -g psyclaw@0.29.5
 ```
 
 如果本机 npm 配置把 registry 误写成带有 `~/` 的地址，请显式指定官方源：
 
 ```bash
-npm install -g psyclaw@0.29.4 --registry=https://registry.npmjs.org/
+npm install -g psyclaw@0.29.5 --registry=https://registry.npmjs.org/
 ```
 
 中国大陆网络较慢或无法访问官方源时：
 
 ```powershell
-npm install -g psyclaw@0.29.4 --registry=https://registry.npmmirror.com
+npm install -g psyclaw@0.29.5 --registry=https://registry.npmmirror.com
 ```
 
-PsyClaw 的 npm 发布包直接携带 Windows x64/arm64 版 `ripgrep` 和 `fd`，Windows 启动时直接使用包内可执行文件，不再联网下载。其他平台缺少这两个工具时仍由锁定的 Pi 原生工具管理器处理：代理环境走 GitHub 官方 API 与 Release，国内 npm registry 环境统一走国内镜像。
+或安装脚本：
+
+```bash
+PSYCLAW_CN=1 curl -fsSL https://exekiel179.github.io/psyclaw/install.sh | sh
+```
+
+检测到国内 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 启动时直接使用包内可执行文件，不再联网下载。
 
 确认命令入口：
 

package/dist/apps/panel/index.html

@@ -266,6 +266,85 @@
       font-size: 12.5px;
     }
 
+    .help-grid {
+      display: grid;
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+      gap: 12px;
+      margin-bottom: 22px;
+    }
+    .help-mode-card {
+      border: 1px solid var(--border-subtle);
+      background: var(--bg-surface);
+      border-radius: var(--radius-md);
+      padding: 14px 16px;
+      box-shadow: var(--shadow-xs);
+    }
+    .help-mode-card .mode-id {
+      font-family: var(--font-mono);
+      font-size: 11px;
+      color: var(--accent);
+      letter-spacing: 0.04em;
+      text-transform: uppercase;
+      margin-bottom: 6px;
+    }
+    .help-mode-card p {
+      margin: 0;
+      font-size: 13px;
+      line-height: 1.55;
+      color: var(--text-secondary);
+    }
+    .help-block {
+      margin-bottom: 22px;
+    }
+    .help-block h2 {
+      margin: 0 0 10px;
+      font-size: 14px;
+      font-weight: 650;
+      color: var(--text-main);
+    }
+    .help-steps {
+      margin: 0;
+      padding-left: 1.2rem;
+      color: var(--text-secondary);
+      font-size: 13px;
+      line-height: 1.7;
+    }
+    .help-commands {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 8px;
+    }
+    .help-cmd {
+      display: flex;
+      gap: 10px;
+      align-items: baseline;
+      border: 1px solid var(--border-subtle);
+      border-radius: var(--radius-sm);
+      padding: 10px 12px;
+      background: var(--bg-surface-subtle);
+    }
+    .help-cmd code {
+      font-family: var(--font-mono);
+      font-size: 12px;
+      color: var(--text-main);
+      white-space: nowrap;
+    }
+    .help-cmd span {
+      font-size: 12.5px;
+      color: var(--text-muted);
+      line-height: 1.45;
+    }
+    .help-notes {
+      margin: 0;
+      padding-left: 1.2rem;
+      color: var(--text-muted);
+      font-size: 12.5px;
+      line-height: 1.65;
+    }
+    @media (max-width: 960px) {
+      .help-grid, .help-commands { grid-template-columns: 1fr; }
+    }
+
     .button {
       display: inline-flex;
       align-items: center;
@@ -1174,6 +1253,10 @@
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="14" rx="2" ry="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
           模型与成本
         </button>
+        <button data-view="help">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+          使用速览
+        </button>
         <button data-view="checklist">
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 11l3 3L22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>
           核对清单
@@ -1382,6 +1465,28 @@
         </div>
       </section>
 
+      <section id="view-help" class="view">
+        <div class="page-head">
+          <div>
+            <h1 id="help-title">使用速览</h1>
+            <p id="help-thinking">加载中…</p>
+          </div>
+        </div>
+        <div class="help-grid" id="help-modes"></div>
+        <div class="help-block">
+          <h2>建议流程</h2>
+          <ol id="help-steps" class="help-steps"></ol>
+        </div>
+        <div class="help-block">
+          <h2>常用命令</h2>
+          <div id="help-commands" class="help-commands"></div>
+        </div>
+        <div class="help-block">
+          <h2>说明</h2>
+          <ul id="help-notes" class="help-notes"></ul>
+        </div>
+      </section>
+
       <section id="view-checklist" class="view">
         <div class="page-head">
           <div>
@@ -1533,6 +1638,9 @@ async function json(url, options) {
 
 function setView(view) {
   state.view = view;
+  if (location.hash.replace(/^#/, "") !== view) {
+    history.replaceState(null, "", `#${view}`);
+  }
   document.querySelectorAll(".nav button").forEach(button => {
     button.classList.toggle("active", button.dataset.view === view);
   });
@@ -1542,10 +1650,32 @@ function setView(view) {
   if (view === "ecosystem") loadEcosystem();
   if (view === "provider") loadProvider();
   if (view === "checklist") loadChecklist();
+  if (view === "help") loadHelp();
   if (view === "chat") mountConsoleInChat();
   else restoreConsoleDrawer();
 }
 
+async function loadHelp() {
+  try {
+    const doc = await json("/api/help");
+    $("help-title").textContent = doc.title || "使用速览";
+    $("help-thinking").textContent = doc.thinking || "";
+    $("help-modes").innerHTML = (doc.modes || []).map(mode => `
+      <article class="help-mode-card">
+        <div class="mode-id">${esc(mode.label || mode.id)}</div>
+        <p>${esc(mode.blurb)}</p>
+      </article>
+    `).join("");
+    $("help-steps").innerHTML = (doc.steps || []).map(step => `<li>${esc(step)}</li>`).join("");
+    $("help-commands").innerHTML = (doc.commands || []).map(row => `
+      <div class="help-cmd"><code>${esc(row.cmd)}</code><span>${esc(row.blurb)}</span></div>
+    `).join("");
+    $("help-notes").innerHTML = (doc.notes || []).map(note => `<li>${esc(note)}</li>`).join("");
+  } catch (error) {
+    $("help-thinking").textContent = `加载失败: ${error.message}`;
+  }
+}
+
 function mountConsoleInChat() {
   const host = $("chat-console-host");
   const drawer = $("console-drawer");
@@ -2252,6 +2382,14 @@ loadProject().catch(error => {
   $("viewer-body").textContent = `加载失败: ${error.message}`;
 });
 loadProjectStatus();
+
+const initialView = decodeURIComponent((location.hash || "").replace(/^#/, "").trim());
+const knownViews = new Set(["project", "ecosystem", "provider", "checklist", "chat", "help"]);
+if (knownViews.has(initialView)) setView(initialView);
+window.addEventListener("hashchange", () => {
+  const next = decodeURIComponent((location.hash || "").replace(/^#/, "").trim());
+  if (knownViews.has(next) && next !== state.view) setView(next);
+});
 </script>
 </body>
 </html>

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

@@ -29,7 +29,8 @@ import { arsRoot } from "../../ars/pi-panel-executor.js";
 import { ArsModeEditor, isArsModeEditorText } from "../../ars/mode-editor.js";
 import { MODE_STATUS, nextSessionMode, parseSessionMode, sessionModePrompt, } from "../../session/modes.js";
 import { formatVerifyChecklist, isNaturalPlanConfirm, loadVerifyChecklist, markVerifyItem, skipUnverifiedItems } from "../../verify/checklist.js";
-import { formatSessionHelp } from "../../session/help.js";
+import { formatSessionHelp, formatSessionHelpBrief } from "../../session/help.js";
+import { openResearchWorkbench } from "../../panel/workbench.js";
 const PARADIGMS = new Set([
     "survey-observational",
     "qualitative-thematic",
@@ -1137,7 +1138,18 @@ export default function psyclawExtension(pi) {
                 return { action: "handled" };
             }
             if (/^\/help(?:\s|$)/i.test(event.text.trim())) {
-                ctx.ui.notify(formatSessionHelp(), "info");
+                try {
+                    const { url, opened } = await openResearchWorkbench({
+                        cwd: ctx.cwd,
+                        isProjectTrusted: () => ctx.isProjectTrusted(),
+                        isIdle: () => ctx.isIdle(),
+                        sendUserMessage: (message, options) => pi.sendUserMessage(message, options ?? {}),
+                    }, { view: "help" });
+                    ctx.ui.notify(formatSessionHelpBrief(url) + (opened ? "" : "\n（未能自动打开浏览器时请手动访问）"), opened ? "info" : "warning");
+                }
+                catch (error) {
+                    ctx.ui.notify(`${formatSessionHelp()}\n\n（Panel 未启动：${error instanceof Error ? error.message : String(error)}）`, "info");
+                }
                 return { action: "handled" };
             }
             const mode = arsModeEditor?.getMode() ?? sessionMode;
@@ -1307,9 +1319,20 @@ export default function psyclawExtension(pi) {
         handler: async (args, ctx) => handleCrosscheck(args, ctx),
     });
     pi.registerCommand("help", {
-        description: "三种模式速览与常用命令",
+        description: "打开 Panel 使用速览",
         handler: async (_args, ctx) => {
-            ctx.ui.notify(formatSessionHelp(), "info");
+            try {
+                const { url, opened } = await openResearchWorkbench({
+                    cwd: ctx.cwd,
+                    isProjectTrusted: () => ctx.isProjectTrusted(),
+                    isIdle: () => ctx.isIdle(),
+                    sendUserMessage: (message, options) => pi.sendUserMessage(message, options ?? {}),
+                }, { view: "help" });
+                ctx.ui.notify(formatSessionHelpBrief(url) + (opened ? "" : "\n（未能自动打开浏览器时请手动访问）"), opened ? "info" : "warning");
+            }
+            catch (error) {
+                ctx.ui.notify(`${formatSessionHelp()}\n\n（Panel 未启动：${error instanceof Error ? error.message : String(error)}）`, "info");
+            }
         },
     });
     pi.registerCommand("plan", {