@jetcrab/pi-desk 1.1.5 → 1.1.8-dev

package/README.md

@@ -23,11 +23,11 @@ Pi powers the agent. Pi Desk provides the interface, with a lightweight core and
 ## Interface demo
 
 <p>
-  <a href="./docs/images/client-overview.webp">
-    <img src="./docs/images/client-overview.webp" alt="File preview" width="300" />
+  <a href="./docs/doc_asset/client-overview.webp">
+    <img src="./docs/doc_asset/client-overview.webp" alt="File preview" width="300" />
   </a>
-  <a href="./docs/images/multi-window.webp">
-    <img src="./docs/images/multi-window.webp" alt="Side-by-side conversations" width="300" />
+  <a href="./docs/doc_asset/multi-window.webp">
+    <img src="./docs/doc_asset/multi-window.webp" alt="Side-by-side conversations" width="300" />
   </a>
 </p>
 

package/README.zh-CN.md

@@ -23,11 +23,11 @@ Pi 负责代理运行，Pi Desk 提供围绕它的工作界面。核心保持轻
 ## 界面演示
 
 <p>
-  <a href="./docs/images/client-overview.webp">
-    <img src="./docs/images/client-overview.webp" alt="文件预览" width="300" />
+  <a href="./docs/doc_asset/client-overview.webp">
+    <img src="./docs/doc_asset/client-overview.webp" alt="文件预览" width="300" />
   </a>
-  <a href="./docs/images/multi-window.webp">
-    <img src="./docs/images/multi-window.webp" alt="多窗口会话" width="300" />
+  <a href="./docs/doc_asset/multi-window.webp">
+    <img src="./docs/doc_asset/multi-window.webp" alt="多窗口会话" width="300" />
   </a>
 </p>
 

package/docs/README.md

@@ -0,0 +1,8 @@
+# Pi Desk 文档
+
+Pi Desk 基于 Pi 开发，底层能力参照对应版本的 Pi 文档。
+
+| 任务                           | 文档                      |
+| ------------------------------ | ------------------------- |
+| 管理 Pi Desk、安装或重载插件   | [管理命令](./commands.md) |
+| 开发插件、应用、面板和消息视图 | [插件开发](./plugins.md)  |

package/docs/{pi-desk/plugins.md → plugins.md}

@@ -112,7 +112,114 @@ Push 可丢失、不持久化、不 ACK、不重放，也不创建聊天消息
 - 当前页面轻提示：`plugin.notify({ level: 'success', title: '保存成功' })` 或 `host.notify()`，只在当前页面短暂展示，离线可错过。
 - 服务端全局通知：Node `plugin.notifications.publish({ level: 'success', title: '处理完成', event: { name: 'open-result', data: {} } })`；用返回 ID 调用 `update/delete`。Browser Entry 通过 `plugin.notifications.onEvent('open-result', handler)` 处理点击，成功后宿主删除通知。Node 未重启时重连可恢复；Node 重启或插件释放后清空，不持久化。
 
-消息适配需要时读 `/entry` 的 `declareMessage` 与 `/browser` 的 Message View 类型：Node 投影原始 Pi 消息，Browser 按最终 `viewKey + priority` 选择 View。首屏必需数据放 Summary，大内容按 Detail 获取；View 失败只影响相应消息，不自行解析 Pi 原始类型或切换到另一个低优先级 View。
+## 消息展示
+
+Node Entry 的 Declaration 把已有 Pi 消息转换为 `{ viewKey, summary, detail }`；Browser 的 Message View 按 `viewKey` 展示。`viewKey` 使用小写 kebab-case 的 `namespace/view-name` 形式，标识展示数据协议，不是消息 ID。Declaration 不创建消息，也不管理消息身份。
+
+以原生插件产生的 `customType = 'example-status'` 消息为例，在 Node Entry 的 `setup(plugin)` 中注册：
+
+```ts
+plugin.declareMessage('status', {
+  priority: 100,
+  match({ message }) {
+    return message.kind === 'custom' && message.customType === 'example-status'
+  },
+  project({ defaultProjection }) {
+    return {
+      viewKey: 'example/status',
+      summary: defaultProjection.summary,
+      detail: null
+    }
+  }
+})
+```
+
+此例复用默认自定义消息的 `summary.text`。在 Browser Entry 同步注册对应视图：
+
+```js
+plugin.registerContribution('message-view', 'status', {
+  viewKey: 'example/status',
+  priority: 100,
+  load: () => import('./status-view.js').then((module) => module.default)
+})
+```
+
+同目录的 `status-view.js`：
+
+```js
+export default {
+  mount({ container, target }) {
+    const element = document.createElement('p')
+    container.append(element)
+
+    function render() {
+      const { text } = target.message.getSnapshot().summary
+      if (typeof text !== 'string') {
+        target.reportError(new Error('消息摘要缺少 text'))
+        return
+      }
+      element.textContent = text
+    }
+
+    const unsubscribe = target.message.subscribe(render)
+    render()
+    return () => {
+      unsubscribe()
+      element.remove()
+    }
+  }
+}
+```
+
+- `match/project` 必须同步、快速、无副作用；每次返回完整投影，不自行计算或传输增量。自定义数据的结构由对应 `viewKey` 的 Declaration/View 约定，不扩充通用消息类型。
+- 首屏和实时必需内容放 `summary`；大内容或用户展开后才用的数据放 `detail`。需要详情时，仅在消息已有 `entryId` 且 `fixed.hasDetail` 为真后调用 `target.message.loadDetail()`；异步结果须检查挂载的 `signal`，不能写回失效视图。
+- 视图从 `getSnapshot()` 读取完整当前状态，并通过 `subscribe()` 跟随更新；同 `viewKey` 的消息更新不重新挂载，Temporary 转 Durable 保持同一 Handle，`viewKey` 改变时会重挂。释放时解除订阅并清理自有资源。
+- Declaration 和 View 分别按 `priority` 选择，数值越大越优先；同最高优先级冲突会报错。声明、加载或展示失败不自动尝试低优先级实现；异步展示错误通过 `target.reportError(error)` 交给宿主处理。
+- 刷新后仍需展示的数据必须存在于最终 Pi Entry，仅通过 Tool `onUpdate()` 提供的数据不会自动持久化。更新插件时兼容已有消息结构，不靠自动重载旧会话解决兼容问题。
+
+## 任务
+
+Task Center 用于当前 Session 的真实任务，通过 `bindSessionPlugin()` 返回的 `plugin` 上报；Global 插件的任务由自身运行态管理，不创建 Session Task。
+
+在真实操作开始时创建任务，完成后上报结果。以下 `runTask()` 是插件已有的业务函数：
+
+```ts
+const task = plugin.startTask({
+  title: '处理文件',
+  activity: '正在执行'
+})
+
+try {
+  await runTask()
+  task.complete('处理完成')
+} catch (error) {
+  task.fail(error instanceof Error ? error.message : String(error))
+  throw error
+}
+```
+
+- 进度使用 `task.update({ activity, info })`；`info` 是 `{ label, value }[]`，整体替换，`[]` 清空，不放日志正文。
+- 有停止能力时，给 `startTask()` 的 `interrupt` 传入真实停止函数，签名为 `() => Promise<void>`。回调返回不代表任务已经结束；确认实际停止后调用 `task.stopped()`，会话关闭等中断使用 `task.interrupted()`。
+- 一个任务只进入一次终态，终态后不能 `update()` 或再次结束；`remove()` 只移除上报记录，不停止真实操作。
+- `detailSource` 可选：文本日志用 `{ kind: 'text-file', path: logPath }`；活动子会话用 `{ kind: 'pi-conversation', session: childSession }`；历史会话用 `{ kind: 'pi-conversation', sessionFile }`。文件路径均为服务端绝对路径，活动实例和文件来源二选一。
+- 宿主只观察详情，不接管插件创建的资源。会话关闭时停止自有任务、上报终态并释放子会话等资源，不关闭父会话；需要随分支结束的任务在树导航前收敛。
+- 任务列表是运行态，不是持久历史；宿主保留全部运行中任务和最近 100 条终态，不能依赖更早记录一直存在。
+
+## 日志
+
+命令、构建等任务的完整输出由插件写入日志文件，并负责容量与清理。界面复用宿主日志能力，不自行读取文件或实现监听、重连。
+
+从 `@jetcrab/pi-desk-sdk/react/base` 导入 `PluginLogViewer`，在已有 `PluginHostProvider` 内使用：
+
+```tsx
+<PluginLogViewer path={logPath} />
+```
+
+`logPath` 是服务端可访问的绝对文本文件路径。文件未创建时继续等待；组件处理追加、重写、重连与读取重试，最多显示末尾 128KB、1000 行，不修改原文件。
+
+非 React 界面使用 `host.logs.open(logPath)`，通过返回句柄的 `getSnapshot()`、`subscribe()` 和 `retry()` 读取与观察，释放时调用 `dispose()`。Session Task 可使用 `detailSource: { kind: 'text-file', path: logPath }` 展示同一日志。
+
+业务数据只传递必要的日志摘要和路径，不把日志正文放入 Method 返回、Plugin Push、状态槽位或 Pi JSONL。
 
 ## 更新生效
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetcrab/pi-desk",
-  "version": "1.1.5",
+  "version": "1.1.8-dev",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   },
   "files": [
     "bin",
-    "docs/pi-desk",
+    "docs",
     "next.config.ts",
     "package.json",
     "src",

package/src/client/l2_biz/project-preview/l2-project-preview-dialog.tsx

@@ -221,6 +221,8 @@ export function L2ProjectPreviewDialog({
   const code = (
     <div className="flex size-full min-h-0 min-w-0 flex-col">
       <L3ProjectFileTabs
+        cwd={cwd}
+        gitRuntime={git}
         paths={state.tabs}
         activePath={state.activePath}
         diffPath={diffPath}
@@ -230,6 +232,7 @@ export function L2ProjectPreviewDialog({
       />
       <L3ProjectDocumentView
         runtime={files}
+        gitRuntime={git}
         compact={size.width < 1100 || narrow}
         onEscape={onClose}
       />

package/src/client/l2_biz/workbench/file-workspace/l2-file-workspace-view.tsx

@@ -207,6 +207,8 @@ export function L2FileWorkspaceView({
         ) : null}
         <div className="flex min-h-0 min-w-0 flex-1 flex-col">
           <L2FileWorkspaceTabs
+            cwd={cwd}
+            gitRuntime={gitRuntime}
             paths={workspace.tabs}
             activePath={activePath}
             diffPath={diffPath}
@@ -217,6 +219,12 @@ export function L2FileWorkspaceView({
           <L3ProjectDocumentView
             ref={documentRef}
             runtime={runtime.getFileRuntime(workId)}
+            gitRuntime={gitRuntime}
+            visible={
+              expanded ||
+              (workspace.windowOpen &&
+                (presentation === 'split' || workspace.activePane === 'files'))
+            }
             compact={compact}
             onEscape={escape}
             onSwitchPane={onSwitchPane}

package/src/client/l2_biz/workbench/hooks/l2-workbench-chat-viewport.ts

@@ -1,7 +1,7 @@
 'use client'
 
-import { useEffect, useLayoutEffect, useRef } from 'react'
-import { useStickToBottomContext } from 'use-stick-to-bottom'
+import { useEffect, useLayoutEffect, useRef, useSyncExternalStore } from 'react'
+import { useStickToBottomContext, type StickToBottomState } from 'use-stick-to-bottom'
 import {
   L3_CONVERSATION_TOP_GUTTER_PX,
   clearL3ConversationTailSpacer,
@@ -14,6 +14,24 @@ import type { L2WorkbenchChatViewportSnapshot } from '../l2-workbench-chat'
 
 const BOTTOM_THRESHOLD_PX = 2
 
+function subscribePageVisibility(listener: () => void): () => void {
+  document.addEventListener('visibilitychange', listener)
+  return () => document.removeEventListener('visibilitychange', listener)
+}
+
+function pageIsVisible(): boolean {
+  return document.visibilityState === 'visible'
+}
+
+function serverPageIsVisible(): boolean {
+  return true
+}
+
+function markProgrammaticScroll(scrollState: StickToBottomState, scrollElement: HTMLElement): void {
+  // 库的命令式 setter 同时标记程序滚动，避免把锚点定位误判为手动回底。
+  scrollState.scrollTop = scrollElement.scrollTop
+}
+
 interface L2WorkbenchChatViewportManagerProps {
   visible?: boolean
   running: boolean
@@ -21,6 +39,7 @@ interface L2WorkbenchChatViewportManagerProps {
   containsTail: boolean
   latestUserAnchor: string | null
   entrySnapshot: L2WorkbenchChatViewportSnapshot | null
+  onResetToTail: () => void
   onSaveSnapshot: (snapshot: L2WorkbenchChatViewportSnapshot) => void
   onClearSnapshot: () => void
 }
@@ -61,10 +80,17 @@ export function L2WorkbenchChatViewportManager({
   containsTail,
   latestUserAnchor,
   entrySnapshot,
+  onResetToTail,
   onSaveSnapshot,
   onClearSnapshot
 }: L2WorkbenchChatViewportManagerProps): null {
   const { isAtBottom, scrollRef, scrollToBottom, state, stopScroll } = useStickToBottomContext()
+  const pageVisible = useSyncExternalStore(
+    subscribePageVisibility,
+    pageIsVisible,
+    serverPageIsVisible
+  )
+  const previousPageVisibleRef = useRef(pageVisible)
   const positioningRef = useRef(false)
   const initializedRef = useRef(false)
   const positionedUserAnchorRef = useRef<string | null>(null)
@@ -98,6 +124,14 @@ export function L2WorkbenchChatViewportManager({
       return
     }
     if (suspendedScrollTopRef.current === null) return
+    if (!running) {
+      initializedRef.current = false
+      entrySnapshotRef.current = null
+      suspendedSnapshotRef.current = null
+      suspendedScrollTopRef.current = null
+      logL3ConversationScroll('viewport:reenter-ended', scrollElement)
+      return
+    }
     stopScroll()
     const snapshot = suspendedSnapshotRef.current
     const target = snapshot
@@ -106,21 +140,31 @@ export function L2WorkbenchChatViewportManager({
     if (snapshot && target)
       positionL3ConversationMessage(scrollElement, target, snapshot.offset, containsTail)
     else scrollElement.scrollTop = suspendedScrollTopRef.current
-    // 隐藏期间的新消息不能覆盖用户离开前的阅读位置。
+    // 仍在运行时，隐藏期间的新消息不能覆盖离开前的阅读位置。
     initializedRef.current = true
     positionedUserAnchorRef.current = latestUserAnchor
     suspendedSnapshotRef.current = null
     suspendedScrollTopRef.current = null
-  }, [containsTail, latestUserAnchor, scrollRef, stopScroll, visible])
+  }, [containsTail, latestUserAnchor, running, scrollRef, stopScroll, visible])
 
   useLayoutEffect(() => {
-    if (!ready || !visible) return
+    const returnedToPage = pageVisible && !previousPageVisibleRef.current
+    previousPageVisibleRef.current = pageVisible
+    if (returnedToPage && visible && !running) {
+      initializedRef.current = false
+      entrySnapshotRef.current = null
+    }
+    if (!ready || !visible || !pageVisible) return
     if (!running) onClearSnapshot()
 
     const initializing = !initializedRef.current
     const hasNewUser =
       latestUserAnchor !== null && latestUserAnchor !== positionedUserAnchorRef.current
     if (!initializing && !hasNewUser) return
+    if (initializing && !running && !containsTail) {
+      onResetToTail()
+      return
+    }
 
     const currentScrollElement = scrollRef.current
     if (hasNewUser) {
@@ -130,6 +174,7 @@ export function L2WorkbenchChatViewportManager({
 
     let positionFrame: number | null = null
     let releaseFrame: number | null = null
+    let releaseEntryAnchor: (() => void) | null = null
     positioningRef.current = true
 
     const position = (): void => {
@@ -148,7 +193,7 @@ export function L2WorkbenchChatViewportManager({
 
       let target: HTMLElement | null = null
       let targetOffset = L3_CONVERSATION_TOP_GUTTER_PX
-      const snapshot = initializing ? entrySnapshotRef.current : null
+      const snapshot = initializing && running ? entrySnapshotRef.current : null
       if (snapshot) {
         const savedTarget = findL3ConversationMessage(
           scrollElement,
@@ -201,10 +246,34 @@ export function L2WorkbenchChatViewportManager({
       initializedRef.current = true
       positionedUserAnchorRef.current = latestUserAnchor
       entrySnapshotRef.current = null
+      if (initializing && !running && target) {
+        // 首屏的懒布局仍会改变高度；用户开始操作后立即交还阅读位置。
+        const entryTarget = target
+        markProgrammaticScroll(state, scrollElement)
+        const observer = new ResizeObserver(() => {
+          stopScroll()
+          positionL3ConversationMessage(scrollElement, entryTarget, targetOffset, containsTail)
+          markProgrammaticScroll(state, scrollElement)
+        })
+        observer.observe(scrollElement)
+        if (scrollElement.firstElementChild) observer.observe(scrollElement.firstElementChild)
+        const interactionElement = scrollElement.parentElement!
+        const events = ['wheel', 'touchstart', 'pointerdown', 'keydown', 'click'] as const
+        const release = (): void => {
+          observer.disconnect()
+          for (const event of events) interactionElement.removeEventListener(event, release, true)
+          releaseEntryAnchor = null
+          positioningRef.current = false
+        }
+        for (const event of events) {
+          interactionElement.addEventListener(event, release, { passive: true, capture: true })
+        }
+        releaseEntryAnchor = release
+      }
       releaseFrame = window.requestAnimationFrame(() => {
         if (followAfterPosition) void scrollToBottom({ animation: 'instant' })
         else if (target) stopScroll()
-        positioningRef.current = false
+        positioningRef.current = releaseEntryAnchor !== null
       })
     }
 
@@ -215,15 +284,20 @@ export function L2WorkbenchChatViewportManager({
     return () => {
       if (positionFrame !== null) window.cancelAnimationFrame(positionFrame)
       if (releaseFrame !== null) window.cancelAnimationFrame(releaseFrame)
+      releaseEntryAnchor?.()
+      positioningRef.current = false
     }
   }, [
     containsTail,
     latestUserAnchor,
     onClearSnapshot,
+    onResetToTail,
+    pageVisible,
     ready,
     running,
     scrollRef,
     scrollToBottom,
+    state,
     stopScroll,
     visible
   ])

package/src/client/l2_biz/workbench/l2-workbench-chat-view.tsx

@@ -134,7 +134,7 @@ function L2WorkbenchChatViewComponent({
           turns={turns}
           active={visible}
           focusTurnIdentity={latestUserTurn?.identity ?? null}
-          initialAnchor={entrySnapshot?.messageId ?? null}
+          initialAnchor={viewportRunning ? (entrySnapshot?.messageId ?? null) : null}
         >
           {(turnWindow) => (
             <>
@@ -146,6 +146,7 @@ function L2WorkbenchChatViewComponent({
                 containsTail={turnWindow.containsTail}
                 latestUserAnchor={latestUserAnchor}
                 entrySnapshot={entrySnapshot}
+                onResetToTail={turnWindow.resetToTail}
                 onSaveSnapshot={saveViewportSnapshot}
                 onClearSnapshot={clearViewportSnapshot}
               />

package/src/client/l3_modules/project-files/l3-project-document-git.ts

@@ -0,0 +1,82 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useSyncExternalStore, type RefObject } from 'react'
+import type { L3ProjectFileRuntime } from './l3-project-file-runtime'
+import type { L3ProjectGitBrowser } from './l3-project-git-runtime'
+import { findL3GitFile } from './l3-project-git-model'
+
+export function useL3ProjectDocumentGit(
+  runtime: L3ProjectFileRuntime,
+  git: L3ProjectGitBrowser,
+  host: RefObject<HTMLDivElement | null>,
+  savePosition: () => void,
+  active: boolean
+): { refresh: () => void; unavailable: boolean } {
+  useSyncExternalStore(git.subscribe, git.getRevision, git.getRevision)
+  const snapshot = git.getWorkspace(runtime.cwd)?.snapshot
+  const path = runtime.state.activePath
+  const diffActive = Boolean(runtime.state.activeDiff)
+  const document = path ? runtime.state.documents.get(path) : undefined
+  const save = useRef(savePosition)
+  useEffect(() => {
+    save.current = savePosition
+  }, [savePosition])
+  const refresh = useCallback((): void => {
+    if (!path || diffActive) return
+    save.current()
+    runtime.reloadFile(path)
+    void git.refreshSnapshot(runtime.cwd)
+  }, [diffActive, git, path, runtime])
+
+  useEffect(() => {
+    if (!active || !path || diffActive) return
+    const visible = (): boolean =>
+      window.document.visibilityState === 'visible' &&
+      Boolean(host.current?.getClientRects().length) &&
+      !host.current?.closest('[inert], [aria-hidden="true"]')
+    let lastRefresh = Date.now()
+    if (visible()) {
+      // 已打开的标签重新展示时重读；首次打开仍复用正在进行的正文请求。
+      if (runtime.state.documents.get(path)?.status === 'text') {
+        save.current()
+        runtime.reloadFile(path)
+      }
+      void git.refreshSnapshot(runtime.cwd)
+    }
+    const onFocus = (): void => {
+      if (!visible() || Date.now() - lastRefresh < 1000) return
+      lastRefresh = Date.now()
+      refresh()
+    }
+    window.addEventListener('focus', onFocus)
+    window.document.addEventListener('visibilitychange', onFocus)
+    return () => {
+      window.removeEventListener('focus', onFocus)
+      window.document.removeEventListener('visibilitychange', onFocus)
+    }
+  }, [active, diffActive, git, host, path, refresh, runtime])
+
+  useEffect(() => {
+    if (!active || !path || diffActive || document?.status !== 'text') return
+    const controller = new AbortController()
+    const file =
+      snapshot?.status === 'ready' ? findL3GitFile(runtime.cwd, path, snapshot.repositories) : null
+    void runtime.compareFile(
+      path,
+      file?.repository.state === 'ready' && file.change
+        ? { repositoryRoot: file.repository.root, path: file.change.path }
+        : null,
+      controller.signal
+    )
+    return () => controller.abort()
+  }, [active, diffActive, document, path, runtime, snapshot])
+
+  const file =
+    path && snapshot?.status === 'ready'
+      ? findL3GitFile(runtime.cwd, path, snapshot.repositories)
+      : null
+  return {
+    refresh,
+    unavailable: snapshot?.status === 'error' || file?.repository.state === 'unavailable'
+  }
+}