@youweichen/pi-harness 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 xing-shuyin
+Copyright (c) 2026 Youwei Chen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -40,6 +40,18 @@ pi-harness --port 9000 --cwd /path/to/project
 - 中文和英文界面、声音提醒、可选插件及 pi 扩展。
 - CLI、开机自启服务、Docker 与 Electron 桌面版。
 
+## 文档转换与 OKF Wiki
+
+内置 PDF 转 Markdown 扩展支持扫描件 OCR、表格、代码和来源定位；OKF 扩展让当前 Agent 整理 PDF、Markdown、文本和 Office 文件，提取候选知识、核对重复与冲突，再生成带原文证据的 OKF Wiki。结果可在现有文档工作台中打开。
+
+```text
+/pdf-md setup
+/pdf-md convert ./raw/技术说明.pdf
+/okf ingest ./raw，输出到 ./knowledge
+```
+
+PDF 与 Office 解析需要单独的本机 Python 3.12 环境，首次运行 `setup` 会安装依赖并下载模型；可用 `/pdf-md cancel` 取消、`/pdf-md doctor` 检查。MD/TXT 不需要此环境。知识整理使用当前会话选定的模型，疑点与冲突保留草稿，原文快照随知识目录保存。设置、恢复与资料移交见 [文档知识扩展说明](https://github.com/youweichen0208/pi-harness/blob/develop/docs/architecture-document-knowledge.md)。
+
 ## 运行与部署
 
 ```bash
@@ -68,6 +80,8 @@ npm run test:smoke
 
 pi-harness is an independently maintained web and Electron interface for the pi coding agent SDK. It includes chat, file browsing and editing, attachments, a local terminal, model management, and a built-in SSH node workbench with grouped hosts, multiple PTY tabs, SFTP files, and a separate Agent conversation for each node.
 
+Built-in document extensions provide local PDF-to-Markdown conversion and an Agent-driven OKF Wiki workflow for PDF, Markdown, text and Office files. Run `/pdf-md setup` to prepare the separate local parser, `/pdf-md convert <path>` to convert a PDF, or `/okf ingest <directory>` to organize sourced knowledge with the current conversation's model. See the [document extensions guide](https://github.com/youweichen0208/pi-harness/blob/develop/docs/architecture-document-knowledge.md).
+
 Requires Node.js **>= 22.19.0** and a configured pi model provider. Install with `npm install -g @youweichen/pi-harness`, then run `pi-harness`. See the [SSH workbench guide](https://github.com/youweichen0208/pi-harness/blob/develop/docs/ssh-workbench.md), [Xshell guide](https://github.com/youweichen0208/pi-harness/blob/develop/docs/xshell.md), and [deployment guide](https://github.com/youweichen0208/pi-harness/blob/develop/docs/deployment.md).
 
 ## License

package/dist/server/agent-service.js

@@ -504,7 +504,7 @@ export class ClientSession {
      * (the model choice is client-wide), so later conversations reuse the
      * instance created with the first one.
      */
-    makeRuntimeFactory() {
+    makeRuntimeFactory(refreshResources = false, state) {
         return async ({ cwd, sessionManager }) => {
             const services = await createAgentSessionServices({
                 cwd,
@@ -513,7 +513,12 @@ export class ClientSession {
                 settingsManager: conversationSettings(cwd, this.agentDir),
                 resourceLoaderOptions: { extensionFactories: nativeToolExtensions() },
             });
-            const created = await createAgentSessionFromServices({ services, sessionManager });
+            // A second native reload invalidates the process-wide extension factory cache.
+            if (refreshResources) {
+                await services.resourceLoader.reload();
+                refreshResources = false;
+            }
+            const created = await createAgentSessionFromServices({ services, sessionManager, model: state?.model, thinkingLevel: state?.thinkingLevel });
             return { ...created, services, diagnostics: services.diagnostics };
         };
     }
@@ -1366,6 +1371,7 @@ export class ClientSession {
         cwd: () => this.cwd,
         getSession: () => this.session,
         startNewSession: () => this.startNewSession(),
+        restartSession: (conversationId) => this.restartSession(conversationId),
         treeCommand: async (name, args, context) => {
             const conv = this.conv;
             if (conv.id !== context.conversationId)
@@ -1523,13 +1529,17 @@ export class ClientSession {
             onAccepted?.(ok);
         };
         try {
+            if (this.restartingSession)
+                throw new Error("当前会话正在重启，请稍后重试。");
             if (!["tree", "fork"].includes(parseSlash(text)?.name ?? ""))
                 await conv.tree?.waitForVerification();
             const s = conv.session;
-            await flushPromptReload(s);
-            const promptReloadError = promptReloadStatus(s).reloadError;
-            if (promptReloadError)
-                throw new Error(`Native prompt reload failed: ${promptReloadError}`);
+            if (parseSlash(text)?.name !== "restart") {
+                await flushPromptReload(s);
+                const promptReloadError = promptReloadStatus(s).reloadError;
+                if (promptReloadError)
+                    throw new Error(`Native prompt reload failed: ${promptReloadError}`);
+            }
             if (this.conv !== conv || conv.session !== s)
                 throw new Error("Conversation changed");
             const extensionCommand = text.startsWith("/") && s.extensionRunner.getCommand(text.slice(1).split(" ", 1)[0]);
@@ -1841,8 +1851,59 @@ export class ClientSession {
             });
         }
     }
+    restartingSession = false;
+    /** Recreate only this conversation's native runtime; retain its exact branch and PTYs. */
+    async restartSession(conversationId) {
+        const conv = this.conv;
+        if (conv.id !== conversationId || this.switchingWorkspace || this.creatingConversation)
+            throw new Error("对话正在切换或重启，请稍后重试。");
+        if (this.quiesceBlocked())
+            throw new Error("服务暂停接收新操作。");
+        conv.tree?.assertWritable();
+        if (!conv.session.isIdle || isRecovering(conv.recovery))
+            throw new Error("请先停止当前任务，再重启会话。");
+        this.restartingSession = true;
+        let replacement;
+        try {
+            const previous = conv.runtime, model = conv.session.model, thinking = conv.session.thinkingLevel;
+            replacement = await createAgentSessionRuntime(this.makeRuntimeFactory(true, { model, thinkingLevel: thinking }), {
+                cwd: conv.cwd, agentDir: this.agentDir, sessionManager: conv.session.sessionManager,
+            });
+            if (this.disposed || this.conv !== conv)
+                throw new Error("对话已切换。");
+            await previous.dispose();
+            conv.unsubscribe?.();
+            conv.unsubscribe = undefined;
+            conv.tree?.dispose();
+            conv.tree = undefined;
+            conv.runtime = replacement;
+            replacement = undefined;
+            conv.recovery = {};
+            conv.treeProjectionRevision = undefined;
+            conv.uiMessageCache.clear();
+            conv.lastMessagesSig = "";
+            await this.bindSession(conv);
+            await this.pushSlashCommands();
+            this.pushSettings();
+            this.emitConversations();
+            this.flushSnapshot(true);
+            this.emit({ type: "notice", conversationId: conv.id, level: "info", text: "当前会话已重启，历史记录已保留。" });
+        }
+        finally {
+            try {
+                await replacement?.dispose();
+            }
+            finally {
+                this.restartingSession = false;
+            }
+        }
+    }
     /** /new delegates session creation and history persistence to the SDK; the Web slot is reused. */
     async startNewSession() {
+        if (this.restartingSession) {
+            this.emitNotice("warning", "当前会话正在重启，请稍后重试。");
+            return;
+        }
         if (this.conv.tree?.busy) {
             this.emitNotice("warning", "等待当前切换完成。");
             return;
@@ -1876,6 +1937,10 @@ export class ClientSession {
         void this.pushSlashCommands();
     }
     async newChat(fresh = false, wiki = false) {
+        if (this.restartingSession) {
+            this.emitNotice("warning", "当前会话正在重启，请稍后重试。");
+            return false;
+        }
         if (this.conv.tree?.busy) {
             this.emitNotice("warning", "等待当前切换完成。");
             return false;
@@ -2058,6 +2123,10 @@ export class ClientSession {
     }
     /** Switch the ACTIVE conversation without interrupting any other chat. */
     async switchConversation(id) {
+        if (this.restartingSession) {
+            this.emitNotice("warning", "当前会话正在重启，请稍后重试。");
+            return;
+        }
         if (this.conv.tree?.busy) {
             this.emitNotice("warning", "等待当前切换完成。");
             return;
@@ -2286,6 +2355,10 @@ export class ClientSession {
      * user opened history while it was streaming.
      */
     async switchSession(path) {
+        if (this.restartingSession) {
+            this.emitNotice("warning", "当前会话正在重启，请稍后重试。");
+            return;
+        }
         if (this.conv.tree?.busy) {
             this.emitNotice("warning", "等待当前切换完成。");
             return;
@@ -2553,8 +2626,15 @@ export class ClientSession {
     }
     cwdQueue = null;
     cwdSwitchRunning = false;
-    get switchingWorkspace() { return this.cwdSwitchRunning; }
+    get switchingWorkspace() { return this.cwdSwitchRunning || this.restartingSession; }
     async setCwd(path, id, source) {
+        if (this.restartingSession) {
+            if (id)
+                this.emit({ type: "cwd_result", requestId: id, cwd: this.cwd, ok: false, error: "当前会话正在重启，请稍后重试。" });
+            else
+                this.emitNotice("warning", "当前会话正在重启，请稍后重试。");
+            return;
+        }
         if (this.conv.tree?.busy) {
             this.emitNotice("warning", "等待当前切换完成。");
             return;

package/dist/server/control-socket.js

@@ -87,6 +87,7 @@ export function startControlServer(opts) {
                 switch (req.cmd) {
                     case "status":
                         resp = { ok: true, ...service.serviceStatus() };
+                        resp.activeConversations = (resp.activeConversations ?? 0) + (opts.additionalActiveConversations?.() ?? 0);
                         break;
                     case "quiesce":
                         service.quiesce();

package/dist/server/document-conversion/extension.js

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { lstat, realpath, stat } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { Type } from "typebox";
+import { convertDocument } from "./service.js";
+import { doctorRuntime, setupRuntime } from "./runtime.js";
+import { getDocumentSettings, updateDocumentSettings } from "./settings.js";
+const pathParameter = Type.String({ minLength: 1, maxLength: 4096 });
+let activeSetup;
+export const pdfMarkdownParameters = Type.Object({
+    inputPath: pathParameter,
+    outputDir: Type.Optional(Type.String({ minLength: 1, maxLength: 4096, description: "Output directory inside the current workspace. Defaults to converted/<filename>-<path hash>. Existing edited files are never overwritten." })),
+});
+export const pdfMarkdownOutput = Type.Object({
+    status: Type.Union([Type.Literal("complete"), Type.Literal("partial")]),
+    markdownPath: Type.String(), structurePath: Type.String(), sourceMapPath: Type.String(), assetsDir: Type.String(),
+    sourceHash: Type.String(), parserVersion: Type.String(), warnings: Type.Array(Type.String()),
+});
+/** Output files must remain accessible through the workspace's existing file UI. */
+async function outputDirectory(cwd, input, requested) {
+    const root = await realpath(cwd);
+    const hash = createHash("sha256").update(input).digest("hex").slice(0, 8);
+    const destination = resolve(root, requested ?? `converted/${basename(input, extname(input))}-${hash}`);
+    const within = (target) => { const rel = relative(root, target); return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel); };
+    if (!within(destination) || destination === root)
+        throw Error("Choose an output directory inside the current workspace.");
+    let ancestor = destination;
+    while (true) {
+        try {
+            await lstat(ancestor);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = dirname(ancestor);
+            if (parent === ancestor)
+                throw error;
+            ancestor = parent;
+            continue;
+        }
+        // A dangling symlink exists according to lstat: its failed realpath must not
+        // be mistaken for a missing directory and skipped to the parent.
+        if (!within(await realpath(ancestor)) || !(await stat(ancestor)).isDirectory())
+            throw Error("Output directory leaves the workspace or is not a directory.");
+        return destination;
+    }
+}
+async function pdfSettings(args, ctx) {
+    if (!ctx.isIdle()) {
+        ctx.ui.notify("请等待当前任务结束后修改扩展设置。", "warning");
+        return;
+    }
+    const current = getDocumentSettings();
+    let action = args.trim();
+    if (!action && ctx.hasUI)
+        action = await ctx.ui.select("PDF 转 Markdown 设置", ["启用", "停用", "Python 路径"]) ?? "";
+    if (["on", "启用"].includes(action))
+        await updateDocumentSettings({ pdfEnabled: true });
+    else if (["off", "停用"].includes(action))
+        await updateDocumentSettings({ pdfEnabled: false });
+    else if (action === "Python 路径" || action.startsWith("python ")) {
+        const path = action.startsWith("python ") ? action.slice(7).trim() : await ctx.ui.input("Python 可执行文件路径（留空恢复自动发现）", current.pythonPath ?? "");
+        if (path === undefined)
+            return;
+        await updateDocumentSettings({ pythonPath: path.trim() || undefined });
+    }
+    else {
+        ctx.ui.notify(`PDF 转 Markdown：${current.pdfEnabled ? "启用" : "停用"}；Python：${current.pythonPath ?? "自动发现"}。用 /pdf-md settings on|off|python <路径> 修改。`, "info");
+        return;
+    }
+    ctx.ui.notify("设置已保存。请使用 /reload 或新建会话更新工具列表；停用后现有工具调用会立即被拒绝。", "info");
+}
+export const createPdfMarkdownExtension = () => pi => {
+    pi.registerTool({
+        name: "pdf_to_markdown", label: "PDF to Markdown",
+        description: "Convert a local PDF, including scans, to structured Markdown with local Docling OCR, tables, code, images and source locations. Uses the local parser without extra chat model calls. Returns file paths and quality warnings. Read the Markdown and warnings before reporting quality; do not invent missing content. Link the resulting workspace-relative Markdown file in your final answer.",
+        exposure: getDocumentSettings().pdfEnabled ? "deferred" : "hidden", executionMode: "sequential",
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        parameters: pdfMarkdownParameters, outputSchema: pdfMarkdownOutput,
+        async execute(_id, args, signal, onUpdate, ctx) {
+            if (!getDocumentSettings().pdfEnabled)
+                throw Error("PDF conversion is disabled. Enable it with /pdf-md settings on.");
+            signal?.throwIfAborted();
+            const cwd = await realpath(ctx.cwd);
+            const inputPath = await realpath(resolve(cwd, args.inputPath));
+            if (extname(inputPath).toLowerCase() !== ".pdf")
+                throw Error("pdf_to_markdown accepts PDF files; use okf_ingest for other document formats.");
+            const outputDir = await outputDirectory(cwd, inputPath, args.outputDir);
+            const result = await convertDocument({ inputPath, outputDir, signal, onProgress: text => onUpdate?.({ content: [{ type: "text", text }], details: {} }) });
+            const localPath = (path) => relative(cwd, path).split(sep).join("/");
+            const data = { status: result.status, markdownPath: localPath(result.markdownPath), structurePath: localPath(result.structurePath), sourceMapPath: localPath(result.sourceMapPath), assetsDir: localPath(result.assetsDir), sourceHash: result.sourceHash, parserVersion: result.parserVersion, warnings: result.warnings };
+            return { content: [{ type: "text", text: `${JSON.stringify(data, null, 2)}\nRead the generated Markdown and conversion warnings. In your final reply, link [converted document](${data.markdownPath}).` }], structuredContent: data, details: {} };
+        },
+    });
+    pi.registerCommand("pdf-md", {
+        description: "PDF 转 Markdown；convert、setup、cancel、doctor、settings",
+        async handler(args, ctx) {
+            const [, action = "", rest = ""] = /^(\S+)?\s*([\s\S]*)$/.exec(args.trim()) ?? [];
+            if (action === "settings") {
+                await pdfSettings(rest, ctx);
+                return;
+            }
+            if (action === "cancel") {
+                if (!activeSetup) {
+                    ctx.ui.notify("没有正在安装的文档解析环境。", "info");
+                    return;
+                }
+                if (activeSetup.ownerSessionId !== ctx.sessionManager.getSessionId()) {
+                    ctx.ui.notify("解析环境正在其他会话中安装，请在发起安装的会话中运行 /pdf-md cancel。", "warning");
+                    return;
+                }
+                activeSetup.controller.abort();
+                ctx.ui.notify("已请求取消解析环境安装，正在清理安装进程。", "info");
+                return;
+            }
+            if (action === "doctor" || action === "setup") {
+                if (!ctx.isIdle()) {
+                    ctx.ui.notify("请等待当前任务结束后检查或安装解析环境。", "warning");
+                    return;
+                }
+                if (activeSetup) {
+                    ctx.ui.notify("文档解析环境已经在安装中。可在发起安装的会话运行 /pdf-md cancel 取消。", "warning");
+                    return;
+                }
+                const setup = action === "setup" ? { ownerSessionId: ctx.sessionManager.getSessionId(), controller: new AbortController() } : undefined;
+                if (setup)
+                    activeSetup = setup;
+                const run = async () => {
+                    try {
+                        const signal = setup ? (ctx.signal ? AbortSignal.any([setup.controller.signal, ctx.signal]) : setup.controller.signal) : ctx.signal;
+                        const result = setup ? await setupRuntime({ signal, onProgress: text => ctx.ui.setStatus("document-runtime", text) }) : await doctorRuntime({ signal });
+                        ctx.ui.notify(JSON.stringify(result, null, 2), result.ready ? "info" : "warning");
+                    }
+                    catch (error) {
+                        ctx.ui.notify(error.message, "error");
+                    }
+                    finally {
+                        if (setup && activeSetup === setup)
+                            activeSetup = undefined;
+                        ctx.ui.setStatus("document-runtime", undefined);
+                    }
+                };
+                if (setup) {
+                    // Acknowledge this explicit command immediately so the same WebUI
+                    // input remains available for /pdf-md cancel during installation.
+                    ctx.ui.notify("已开始安装文档解析环境。进度显示在状态栏；可用 /pdf-md cancel 取消。", "info");
+                    setup.task = run();
+                }
+                else
+                    await run();
+                return;
+            }
+            if (action !== "convert" || !rest) {
+                ctx.ui.notify("用法：/pdf-md convert <PDF 路径及可选输出要求>；/pdf-md setup；/pdf-md cancel；/pdf-md doctor；/pdf-md settings", "info");
+                return;
+            }
+            if (!getDocumentSettings().pdfEnabled) {
+                ctx.ui.notify("PDF 转换已停用，请先用 /pdf-md settings on 启用。", "warning");
+                return;
+            }
+            pi.sendUserMessage(`Convert the PDF described below with the native pdf_to_markdown tool. Use tool_search to discover it if needed. Preserve the source document, inspect the conversion warnings, and give a clickable relative link to the resulting Markdown. Do not install dependencies unless I explicitly request setup.\n\n${rest}`, ctx.isIdle() ? undefined : { deliverAs: "followUp" });
+        },
+    });
+};