@jetcrab/pi-desk 1.1.6-dev → 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.6-dev",
+  "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/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'
+  }
+}

package/src/client/l3_modules/project-files/l3-project-document-view.tsx

@@ -6,13 +6,21 @@ import {
   CopyIcon,
   FileCode2Icon,
   FoldVerticalIcon,
+  GitCompareArrowsIcon,
   ListOrderedIcon,
   LoaderCircleIcon,
   RefreshCwIcon,
   SearchIcon,
   WrapTextIcon
 } from 'lucide-react'
-import { useEffect, useImperativeHandle, useRef, useSyncExternalStore, type Ref } from 'react'
+import {
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type Ref
+} from 'react'
 import { useTranslation } from 'react-i18next'
 import { copyL4BrowserText } from '@client/l4_foundation/lib/l4-browser-clipboard'
 import {
@@ -25,6 +33,8 @@ import { L4ImageViewer } from '@client/l4_foundation/ui/l4-image-viewer'
 import { useL4AppToast } from '@client/l4_foundation/ui/l4-app-toast'
 import { Button } from '@client/l4_foundation/ui/shadcn/button'
 import type { L3ProjectFileRuntime } from './l3-project-file-runtime'
+import type { L3ProjectGitBrowser } from './l3-project-git-runtime'
+import { useL3ProjectDocumentGit } from './l3-project-document-git'
 import { L3CodeSurfaceToolbarButton } from './l3-code-surface-toolbar-button'
 import { buildL3FilePreviewHtml } from './l3-file-preview-html'
 
@@ -38,13 +48,17 @@ export interface L3ProjectDocumentHandle {
 export function L3ProjectDocumentView({
   ref: handleRef,
   runtime,
+  gitRuntime,
   compact,
+  visible = true,
   onEscape,
   onSwitchPane
 }: {
   ref?: Ref<L3ProjectDocumentHandle>
   runtime: L3ProjectFileRuntime
+  gitRuntime: L3ProjectGitBrowser
   compact: boolean
+  visible?: boolean
   onEscape: () => void
   onSwitchPane?: () => void
 }): React.JSX.Element {
@@ -55,6 +69,7 @@ export function L3ProjectDocumentView({
   const document = !activeDiff && activePath ? runtime.state.documents.get(activePath) : null
   const isHtml = Boolean(activePath && /\.html?$/i.test(activePath))
   const showSource = document?.status === 'text' && (!isHtml || document.viewMode === 'source')
+  const hostRef = useRef<HTMLDivElement>(null)
   const previewRef = useRef<L4CodePreviewHandle>(null)
   const diffRef = useRef<L4CodeDiffHandle>(null)
   const iframeRef = useRef<HTMLIFrameElement>(null)
@@ -83,6 +98,42 @@ export function L3ProjectDocumentView({
     if (activePath && previewRef.current)
       runtime.saveEditorState(activePath, previewRef.current.getViewState())
   }
+  const { refresh, unavailable } = useL3ProjectDocumentGit(
+    runtime,
+    gitRuntime,
+    hostRef,
+    savePosition,
+    visible
+  )
+  const comparison = document?.status === 'text' ? document.comparison : undefined
+  const [computed, setComputed] = useState<{
+    original: string
+    modified: string
+    count: number | null
+  } | null>(null)
+  const count =
+    comparison?.status === 'ready' &&
+    document?.status === 'text' &&
+    computed?.original === comparison.original.content &&
+    computed.modified === document.content
+      ? computed.count
+      : undefined
+  const openDiff = (line?: number): void => {
+    if (!activePath) return
+    savePosition()
+    runtime.openFileDiff(activePath, line)
+  }
+  const gitStatus =
+    unavailable || comparison?.status === 'error'
+      ? t('gitMarkersFailed')
+      : comparison?.status === 'unavailable' || (comparison?.status === 'ready' && count === null)
+        ? t('gitMarkersUnavailable')
+        : comparison?.status === 'loading' ||
+            (comparison?.status === 'ready' && count === undefined)
+          ? t('gitMarkersLoading')
+          : comparison?.status === 'ready'
+            ? t('gitChangesCount', { count })
+            : null
   const copyText = (): void => {
     if (document?.status !== 'text') return
     const selection = previewRef.current?.getSelectionText() ?? ''
@@ -93,6 +144,7 @@ export function L3ProjectDocumentView({
   }
   return (
     <div
+      ref={hostRef}
       className="flex size-full min-h-0 min-w-0 flex-col outline-none"
       tabIndex={-1}
       onFocus={(event) => {
@@ -181,6 +233,41 @@ export function L3ProjectDocumentView({
                   ))}
                 </div>
               ) : null}
+              {showSource && gitStatus ? (
+                <span
+                  data-testid="file-git-status"
+                  role="status"
+                  className="mr-auto min-w-0 truncate text-xs text-muted-foreground"
+                  title={comparison?.status === 'error' ? comparison.error : gitStatus}
+                >
+                  {compact && comparison?.status === 'ready' && typeof count === 'number'
+                    ? t('gitChangesCompact', { count })
+                    : gitStatus}
+                </span>
+              ) : null}
+              {showSource && comparison?.status === 'ready' ? (
+                <>
+                  {typeof count === 'number' && count > 0 ? (
+                    <>
+                      <L3CodeSurfaceToolbarButton
+                        label={t('previousChange')}
+                        onClick={() => previewRef.current?.previousChange()}
+                      >
+                        <ArrowUpIcon className="size-4" />
+                      </L3CodeSurfaceToolbarButton>
+                      <L3CodeSurfaceToolbarButton
+                        label={t('nextChange')}
+                        onClick={() => previewRef.current?.nextChange()}
+                      >
+                        <ArrowDownIcon className="size-4" />
+                      </L3CodeSurfaceToolbarButton>
+                    </>
+                  ) : null}
+                  <L3CodeSurfaceToolbarButton label={t('viewDiff')} onClick={() => openDiff()}>
+                    <GitCompareArrowsIcon className="size-4" />
+                  </L3CodeSurfaceToolbarButton>
+                </>
+              ) : null}
               {showSource && activePath ? (
                 <>
                   <L3CodeSurfaceToolbarButton
@@ -210,10 +297,7 @@ export function L3ProjectDocumentView({
                 </>
               ) : null}
               {activePath ? (
-                <L3CodeSurfaceToolbarButton
-                  label={t('reloadCurrentFile')}
-                  onClick={() => runtime.reloadFile(activePath)}
-                >
+                <L3CodeSurfaceToolbarButton label={t('reloadCurrentFile')} onClick={refresh}>
                   <RefreshCwIcon className="size-4" />
                 </L3CodeSurfaceToolbarButton>
               ) : null}
@@ -231,6 +315,7 @@ export function L3ProjectDocumentView({
               modified={activeDiff.modified}
               viewMode={compact ? 'inline' : diffViewMode}
               savedState={activeDiff.editorState}
+              initialLine={activeDiff.initialLine}
               onSaveState={(position) => runtime.saveDiffState(activeDiff, position)}
               onEscape={escape}
             />
@@ -302,6 +387,18 @@ export function L3ProjectDocumentView({
             path={activePath}
             content={document.content}
             size={document.size}
+            originalContent={
+              comparison?.status === 'ready' ? comparison.original.content : undefined
+            }
+            onChanges={(count) => {
+              if (comparison?.status === 'ready')
+                setComputed({
+                  original: comparison.original.content,
+                  modified: document.content,
+                  count
+                })
+            }}
+            onOpenDiff={openDiff}
             savedState={document.editorState}
             onSaveState={(path, state) => runtime.saveEditorState(path, state)}
             onEscape={escape}

package/src/client/l3_modules/project-files/l3-project-file-browser.tsx

@@ -39,6 +39,7 @@ import {
 import type { L3ProjectGitBrowser } from './l3-project-git-runtime'
 import {
   getL3GitChangeBadge,
+  getL3GitChangeClass,
   getL3GitHeadLabel,
   getL3GitRepositoryName,
   joinL3GitProjectPath,
@@ -118,12 +119,7 @@ function fileIcon(path: string): React.JSX.Element {
 
 function changedFileNameClass(change: L3GitProjectChange | null): string | undefined {
   if (!change) return undefined
-  const badge = getL3GitChangeBadge(change.change)
-  if (badge === 'D') return 'text-muted-foreground'
-  if (badge === '?') return 'text-red-600 dark:text-red-400'
-  if (badge === 'A') return 'text-emerald-600 dark:text-emerald-400'
-  if (badge === '!') return 'text-violet-600 dark:text-violet-400'
-  return 'text-blue-600 dark:text-blue-400'
+  return getL3GitChangeClass(change.change)
 }
 
 function DirectoryFeedback({

package/src/client/l3_modules/project-files/l3-project-file-runtime.ts

@@ -22,6 +22,16 @@ export type L3DirectoryState =
   | { status: 'idle' | 'loading' }
   | { status: 'ready'; entries: L4ProjectFileEntry[]; truncated: boolean }
   | { status: 'error'; error: string }
+export type L3FileComparison =
+  | { status: 'loading' }
+  | {
+      status: 'ready'
+      repositoryRoot: string
+      path: string
+      original: { path: string; content: string }
+    }
+  | { status: 'unavailable' }
+  | { status: 'error'; error: string }
 export type L3FileDocument =
   | { status: 'unloaded' }
   | { status: 'loading' }
@@ -31,6 +41,7 @@ export type L3FileDocument =
       size: number
       editorState: L4CodePreviewState | null
       viewMode: 'source' | 'preview'
+      comparison?: L3FileComparison
     }
   | { status: 'image'; mimeType: L4ProjectFileImageMimeType; size: number; objectUrl: string }
   | { status: 'error'; error: string }
@@ -47,6 +58,7 @@ interface DiffOptions {
   comparison?: L4GitHistoricalDiff
   editorState?: L4CodeDiffState | null
   label?: string
+  initialLine?: number
 }
 export type L3FileDiff = DiffOptions &
   (
@@ -492,6 +504,71 @@ export class L3ProjectFileRuntime {
     }
     this.publish()
   }
+  async compareFile(
+    path: string,
+    target: { repositoryRoot: string; path: string } | null,
+    signal: AbortSignal
+  ): Promise<void> {
+    const document = this.state.documents.get(path)
+    if (this.disposed || signal.aborted || document?.status !== 'text') return
+    if (!target) {
+      if (document.comparison) {
+        delete document.comparison
+        this.publish()
+      }
+      return
+    }
+    const loading: L3FileComparison = { status: 'loading' }
+    document.comparison = loading
+    this.publish()
+    const current = (): boolean =>
+      !this.disposed &&
+      !signal.aborted &&
+      this.state.documents.get(path) === document &&
+      document.comparison === loading
+    try {
+      const result = await this.reader.diff(target.repositoryRoot, target.path, signal)
+      if (!current()) return
+      if (result.kind === 'text') {
+        // 比较结果的工作区正文与基线一起替换，不能把新行号画在缓存正文上。
+        document.content = result.modified.content
+        document.size = new TextEncoder().encode(result.modified.content).length
+        document.comparison = {
+          status: 'ready',
+          repositoryRoot: target.repositoryRoot,
+          path: target.path,
+          original: result.original
+        }
+      } else {
+        document.comparison = { status: 'unavailable' }
+      }
+    } catch (cause) {
+      if (!current()) return
+      console.warn('[Pi Desk][ProjectFile] 读取行变更失败', {
+        cwd: this.cwd,
+        path,
+        error: message(cause)
+      })
+      document.comparison = { status: 'error', error: message(cause) }
+    }
+    this.publish()
+  }
+  openFileDiff(path: string, initialLine?: number): void {
+    const document = this.state.documents.get(path)
+    if (this.disposed || document?.status !== 'text' || document.comparison?.status !== 'ready')
+      return
+    const comparison = document.comparison
+    this.clearDiff()
+    this.state.activeDiff = {
+      status: 'text',
+      repositoryRoot: comparison.repositoryRoot,
+      path: comparison.path,
+      original: comparison.original,
+      modified: { path: comparison.path, content: document.content },
+      initialLine
+    }
+    this.publish()
+  }
   openDiff(
     repositoryRoot: string,
     path: string,
@@ -616,7 +693,12 @@ export class L3ProjectFileRuntime {
   private invalidateDocument(path: string): void {
     this.documentRequests.get(path)?.abort()
     this.documentRequests.delete(path)
-    this.releaseDocument(this.state.documents.get(path))
+    const document = this.state.documents.get(path)
+    if (document?.status === 'text') {
+      if (document.editorState) this.restoredEditorStates.set(path, document.editorState)
+      this.restoredFileViewModes.set(path, document.viewMode)
+    }
+    this.releaseDocument(document)
     this.state.documents.set(path, { status: 'unloaded' })
   }
   private releaseDocument(document: L3FileDocument | undefined): void {