人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载本文基于 CodePilotElectron Next.js 多模型 AI Agent 桌面客户端的 workspace-surface-sidebar-pin-and-inspector.md 执行计划展开结合仓库内 workspace-identity.ts、workspace-surfaces.ts、workspace-sidebar.ts 等源码与其单元测试系统讲解如何把文件树、Git、看板Widget、浏览器、Agents 等右侧模块收进单一侧栏外壳实现按项目 Pin Primary/Inspector 双栏 旧状态无损迁移。读完本文你将掌握canonical workspace identity 的解析契约、双层状态workspace preference 与 thread state的分离模型、Primary Inspector 布局合同、Pin 与当前 Tab 的分层语义以及 v13 旧双栏的迁移与删除门禁。背景一个外壳两种需求三条反转教训CodePilot 的右侧工作区长期存在FileTree Panel与Workspace Sidebar两个独立外壳一个负责文件树一个承载 Git/看板等模块。用户诉求是让文件树、Git、浏览器、看板、Diff、Agents 全部进入同一个侧边栏并能按项目 pin没有 pin 时只显示少量入口卡片避免双壳并存带来的割裂感。但执行计划明确记录了一条关键经验v13 的双栏叠加不是遗留代码而是来自真实使用反馈——它解决在文件树浏览同时在另一栏持续预览这一任务。因此直接把 Files 与 Preview 改成互斥 tabs将是对产品方向的第三次反转。本计划的答案是一个外壳内的 Primary Inspector——Files 保持可见Primary lane点击文件在 Inspector lane 打开预览真实用户路径验证通过前v13 一律保留。另一个核心问题是scope旧 sidebar key 使用原始workingDirectory sessionId拼接无法合并 symlink/大小写/尾斜杠等路径变体也不理解 Git worktree。项目 Pin 与 Browser partition 必须共享一个canonical workspace identity 合同这是 Phase 1 的独立主题。Canonical Workspace Identity让 worktree、symlink、clone 各归其位契约结构workspace-identity.ts 中的契约与计划文档完全一致export type CanonicalWorkspaceScope git-repository | directory; export interface CanonicalWorkspaceIdentity { id: string; // versioned hashrenderer/localStorage/partition 只消费这个值 scope: CanonicalWorkspaceScope; /** Server-only不得暴露给 renderer storage、telemetry、partition 名或用户可见诊断 */ comparisonKey: string; version: 1; }关键约束是id 是 opaque 的版本化哈希comparisonKey 仅存在于 server 侧。publicWorkspaceIdentity()在对外边界剥掉 comparisonKey只返回{ id, scope, version }单测workspace-identity.test.ts专门断言 public 输出中不包含绝对路径字样。解析顺序从路径到 Git common dir 的窄探针计划文档给出的解析顺序在源码中完整落地resolvePathIdentity(workingDirectory)只接受 existing directory非目录直接 throwWorkspace must be an existing directory用固定 executable argv、shell:false、短 timeout 执行 git 探针git -C absolutePath rev-parse --path-formatabsolute --git-common-dirworkspace-identity.ts成功则对 common dir 再做一次 path identity以 comparison key 作为 repository scope非 Git / git 不可用 / 明确 not-repository 时回退 directory comparison key权限 / timeout / 异常一律 fail closed 到已验证的目录 identity不回显动态路径或 git stderrid sha256(workspace-v1\0 scope \0 comparisonKey)workspace-identity.ts。值得注意的实现细节git 探针会剥离所有GIT_*环境变量workspaceGitProbeEnv()防止父进程的GIT_DIR/GIT_WORK_TREE把探针路由到错误仓库——workspace-identity.test.ts中专门有一条ignores repository-routing GIT_* variables用例验证这一点。此外maxBuffer: 64 * 1024、timeout: 2_000、stdio: [ignore, pipe, ignore]让探针保持窄、快、静默。PathIdentity三种身份分离resolvePathIdentitypath-identity.ts把一条路径拆成三种刻意分离的身份displayPath用户的原始拼写用于 UI 与诊断absolutePath/nativeRealPath宿主文件系统拼写symlink 经realpathSync.native归一comparisonKey仅用于 lookup/cache 的键Windows 下归一为小写反斜杠路径绝不替代安全边界上的 realpath containmentWindows 目录可启用大小写敏感语义、reparse point 可改变对象身份。同时支持 posix / windows_drive / unc / file_url / wsl / relative 六种路径方言的识别与转换覆盖 Windows drive case、UNC、WSL 挂载与 file:// URL。真实 Git fixture 验证workspace-identity.test.ts 用真实git init/worktree add/clonefixture 验证了四条核心不变量主 repo 与 linked worktree 的 identity相同git common dir一致独立 clone不按 remote URL 合并id 不同non-Git 文件夹落在directoryscopesymlink 尾斜杠拼写归一为同一 id。这也对应计划中 Phase 1 的退出门槛同 repo worktrees id 相同独立 clone / non-Git folder id 不同无 shell 字符串、无路径日志、无未界定 fallback。服务端 APIidentity 的窄入口identity 由 server 拥有src/app/api/workspace/identity/route.ts 提供两种能力GET /api/workspace/identity?sessionId...从 session 行派生 working directory新会话无 session 时只接受 renderer 提供的当前项目目录但 server 仍要求真实存在的绝对目录POST /api/workspace/identity迁移用批量解析器单次最多 50 个目录响应只回数组下标results: [{ index, identity }]server 从不回显 renderer 拥有的 legacy key 路径从源头避免绝对路径泄漏。renderer 侧 useWorkspaceSidebar.tsx 在 hydrate 阶段 fetch 该 APIsession 行优先拿到 workspace id 后若 v1 preference key 已存在则直接解析否则枚举 legacy key、批量映射目录到 identity、只迁移归属当前 id 的 bucket——全新 workspace 没有真实 legacy bucket 时必须落到无 Pin launcher不得由当前版本自产 legacy key 后触发 upgrade defaults这是计划不变量中的硬规则。Surface registry 与双层状态workspace 偏好 vs thread 状态Surface 注册表workspace-surfaces.ts 定义SurfaceKind与不可变的SURFACE_REGISTRYexport type SurfaceKind | files | git | widget | browser | agents | diff | artifact | file-preview; export type PrimarySurfaceKind files | git | widget | browser | agents; export interface SurfaceDescriptor { kind: SurfaceKind; titleKey: string; icon: files | git | chart | browser | agents | diff | artifact; pinnable: boolean; availabilitySource: string; // 单一事实来源可用性来自哪里 }Registry 是标题 / icon / pinnable / availability 的单一事实源Files/Git/Widget/Browser/Agents 是 pinnable 的 Primarydiff、artifact、file-preview是 thread 级临时 Inspector默认不可 pin若以后要 pin需另做可恢复 identity 设计。双层状态的两个 V1 结构export interface WorkspaceSurfacePreferencesV1 { version: 1; workspaceId: string; pinnedKinds: PrimarySurfaceKind[]; order: PrimarySurfaceKind[]; defaultActiveKind?: PrimarySurfaceKind; open: boolean; width: number; // 320–800默认 480 } export interface ThreadSurfaceStateV1 { version: 1; sessionId: string; activePrimary?: PrimarySurfaceKind; inspectorTabs: DynamicTab[]; activeInspectorId?: string; }二者分 key、分 version、分 parsermalformed data 一律 fail closed 到默认值不丢 appworkspace preference keycodepilot:workspace-surfaces:v1:workspaceId只含 opaque id无绝对路径thread state keycodepilot:thread-surfaces:v1:sessionId || globalparseWorkspaceSurfacePreferences会去重 pinnedKinds、宽度 clamp 到 [320, 800]、按 registry 补齐缺失的 order 项parseThreadSurfaceState只接受 sessionId 匹配的记录非法 activeInspectorId 被丢弃但合法 tabs 保留。运行时openPrimaryKindsPin 与当前打开的 Tab 彻底分层计划 2026-08-26 的决策日志特别强调pinnedKinds只决定项目下次打开时恢复什么openPrimaryKinds只描述当前 renderer/session 打开的 Primary tabs。语义如下hydrate 时openPrimaryKinds由pinnedKindsseed之后与 Pin 独立变化activate / pin 会打开unpin保持打开只有 Primary tab 自带的关闭按钮才将其移除关闭 pinned tab 不改 Pin重载 / 重开项目会恢复。对应 Hook 实现useWorkspaceSidebar.tsx 中activatePrimary只改openPrimaryKinds与 shell 状态、不动pinnedKindspinSurface/unpinSurface只改WorkspaceSurfacePreferencesV1.pinnedKinds并写回 localStorageclosePrimary从openPrimaryKinds移除后按preferences.order找下一个还开着的 Primary 作为 fallback全部关闭则closeInspector 回 launcher。计划文档中的activatePrimaryInteractively也在源码中实现workspace-sidebar.ts交互点击切换 Primary 时关闭当前 Inspector 展示但保留 preview tab而 hydrate 仍直接调用setActivePrimary以保留重载恢复出的 Inspector。这条差异来自用户实测 bugStandalone 网页预览通过添加 Widget 后无法切入根因是交互激活只改activePrimaryId、仍保留inspectorOpen:true窄栏 Inspector overlay 完全覆盖已切换的 Widget。Primary Inspector 布局合同一个 shell 不等于互斥 tabs布局规则计划 Phase 0 定义Primary laneFiles、Git、Widget、Browser、Agents 等 active moduleInspector lanefile / markdown / artifact / diff detail 等由 Primary 触发的临时预览宽度 320–800px、默认 480pxPOC 实测而非预设漂亮阈值宽度足够Primary Inspector 可调整分隔Files tree 有最低可用宽度宽度不足Inspector 在同一 shell 内成为 peek/overlay通过顶部同级 Tab返回 Files/看板不得创建第二个 CardFrame 或内容区返回栏用户手动扩宽 / 缩窄时active file、scroll、tree expansion、preview mode 保持。800px 宽度以下持久化 480px sidebar 会挤压 Composer因此 workspace CardFrame 在lg改为右侧有界 overlay、隐藏 ResizeGutterInspector 依据ResizeObserver测得的真实 shell 宽度在 split/peek 间切换不按持久化目标宽度猜测。状态模型与 reducerworkspace-sidebar.ts 是纯函数状态模型无 React 依赖可直接被单测驱动核心字段export interface WorkspaceSidebarState { open: boolean; // shell 是否渲染false 折叠 width: number; // 320–800默认 480同 workspace 跨 session 持久化 activeTabId: string; // 始终指向 tabs 中的某个 Tab activePrimaryId: git | widget | files-pinned | browser | agents; activeBrowserTabId?: string; // Browser 是可重复 Primary activeInspectorId?: string; // 当前临时 detailundefined 表示 Inspector lane 关闭 inspectorOpen: boolean; tabs: Tab[]; // fixed 在前dynamic 按插入序 }关键 reducer 行为openDynamicTab同 idkindkey 派生dynamicTabId(kind, key)存在则激活并原位替换元数据——这保证 PreviewPanel 把 trust tier 从 agent-referenced 升级为 user-selected 后持久化 tab 不会在 reload 后回到 confirm 卡否则追加并激活同时open: truecloseTabfixed Tab 不可关闭no-op关闭后激活左侧相邻 tab回退到第一个 fixed关闭 Browser 时维护activeBrowserTabId与剩余 browser tab 的替换选择关闭files-pinned时 activePrimary 回落到 gitcloseInspector把activeTabId切回 PrimaryBrowser 特判回activeBrowserTabId保留 preview tab 本体hydrateWorkspaceSidebarState恢复顺序固定为 active → width → 最后恢复 open防止持久化open:false被setActivePrimary重新写成truethread active 仍被 Pin 时优先失效时才回退 workspace defaultworkspace-sidebar.tscommitWorkspaceFileMutation文件删除/重命名后原子迁移所有文件型 tabid/key/filePath/title 一起改避免持久化与去重损坏。Tab 内容与 PreviewSource 互转TabPanel.tsx 动态挂载 GitPanel、DashboardPanel、PreviewPanel、FileTreePanel、BrowserPanelPrimaryContent按 kind 渲染 Files/Git/Widget/Agents。tabFromPreviewSource把PreviewSource派生为 Tab.md/.mdx→ markdown tabkeyed by filePath其他文件 → file tabinline-*→ artifact tab指纹 kind 内容 djb2 哈希同一代码栅栏多次点击复用同一 tab且 kind 前缀避免不同 inline 类型内容碰撞。previewSourceFromTab是其逆运算供 TabPanel 的 sync effect 在切换 dynamic tab 时切换内容避免所有 dynamic tab 共享全局单一 previewSource 的串台问题。Inspector tabs 按 kindkey 复用动态 tab 的稳定 id 由kind key派生同一.md打开两次只会聚焦已有 tab不会创建第二个。Inspector 的 trust tierworkspace | agent-referenced | user-selected等随 tab 持久化reload 后语义不丢——计划 Phase 3 明确trust tier、preview view mode、file path canonicalization 继续沿用现有合同本阶段不改变 HTML/local path trust 边界。Workspace Pin 与空态 Launcher按项目恢复无假状态Phase 4 的落地语义与源码一一对应launcher 默认候选 Files/Git/Browser有 dirty diff 加 Diff 卡消费真实gitDirtyCount并进入 Git 选择实际文件有 active sub-agent 加 Agents 卡无 Git 时 Git 卡显示 Initialize Git卡片 availability 必须来自真实状态Browser 在 WebContentsView POC GO 前只作为 disabled 卡片存在并解释真实禁用原因不得伪装成可浏览网页Agent 卡仅在当前 thread 有 liveagent-runtab 时出现不可用不显示假计数/假 0Tab 栏右侧只列出当前未打开的 Primary surface选择后瞬时打开但不自动 Pin与 launcher 共用同一 availability 口径Pin/unpin/reorder/default active/open/width 按 workspace id 持久化movePrimarySurface保证 registry 全量不丢失、去重、越界 no-op键盘 reorder/pin、aria-current、tooltip 与 icon semantic回归TabBar 中 PushPin/Plus/X 图标、aria-hidden 装饰、aria-current标记当前 Primary。升级策略上首次安装与升级用户分开initialWorkspaceSurfacePreferences对全新 workspace 返回pinnedKinds: []而migrateLegacyWorkspaceSidebarEntries对升级用户保留Git Widget 固定的历史语义Files 通过 monotonic OR 加入——升级迁移不覆盖用户显式 unpin。迁移与 v13 清理幂等、单调、双证据门禁迁移规则Phase 5新 key 按 opaque workspace id 版本化旧 key 保留一版只读 fallback 期新代码不得再setItemlegacy key——否则全新项目会被刚写出的空 legacy bucket 误判为升级用户凭空 Pin Git/Widget枚举 well-formedcodepilot:workspace-sidebar::wd::sidkey从最后一个::解析 session路径本身含::时仍可处理单测专门覆盖/tmp/a::b::session-1unique old working directories 经有界 batch resolver≤50/次转 workspace id不存在/不可信路径跳过并保留旧 key不猜同 workspace 任一 old bucket 含files-pinned→ newfilespin trueboolean OR跨 session 冲突单调不因后处理 bucket 反转dynamic markdown/artifact/file tabs 保持 thread/session scope迁入新ThreadSurfaceStateV1不提升为 workspace pinagent-run不在 serialized old state 中prompt/result 从 durable chat message 重建不复制进 localStorage验收只要求运行时行为与现状一致migration 不得因 localStorage malformed / path inaccessible 清空用户旧状态malformed bucket 跳过、原 key 保留。删除门禁三条真实点击路径v13 的删除是独立动作硬依赖 Inspector 真实 smoke不与新 shell 首次落地同批执行。门禁清单Primary Inspector 在默认宽度、窄宽度、800px app 宽度真实 UI smoke 通过FileTree → preview、Diff → preview、Artifact → preview 三条真实点击路径逐次断言 Files Primary 未被替换Playwright 在workspace-context-menu-actions.spec.ts三路径 1/1迁移 fixture 覆盖冲突、malformed、path variants、worktree、重复运行独立 FileTree Panel shell/入口重复路径与 v13 coexistence code 删除复审发现删除曾早于三路径门禁执行顺序违规补回聊天代码块 Artifact 入口后门禁通过才允许合并更新workspace-sidebar-tabs.md、refactor-phase-3-background-tasks-notifications.md、refactor-closeout.md加 superseding breadcrumb同步ARCHITECTURE.md与 AppShell.tsx 注释npm run test、npm run test:smoke必要时npm run test:e2e真实 UI 证据写入 Smoke Ledger。E2E 隔离教训2026-08-28 的现场教训值得记录左侧堆积 44 条 Workspace Sidebar E2E 项目根因是 PlaywrightreuseExistingServer把 session POST 发到日常 dev DB且三条用例 finally 只删除临时目录。修复方案Playwright 改为单 owner 临时 SQLite DB 独立.next-e2e-*server所有相关 fixture 增加 session DELETE直接npx playwright缺少隔离环境时 fail closed。最终真实库只读前后计数不变带双证据删除 44 条残留后总会话 627→582。不变量清单可直接当作设计评审 checklist计划文档给出的不变量在源码中均可验证一个 shell ≠ 互斥 tabsFiles → Preview 必须保留浏览上下文activePrimaryId与activeInspectorId分存worktree 共享 pin ≠ 共享 thread file pathsidentity 归 workspacepreview tab 归 thread同 remote 的独立 clone 不共享 workspace idclose pinned surface 不得隐式 unpinunpin 不得关闭 Primary tab也不得删除 thread inspector tabsPrimary tab 的关闭入口必须在它自己的标签内shell collapse 只收起整个侧栏不能冒充 tab close加号菜单只能打开当前未打开且真实可用的 Primary打开不等于 Pin全新 workspace 无真实 legacy bucket 时落到无 Pin launchermigration 不得因 malformed/path inaccessible 清空旧状态v13 清理晚于替代路径 smoke不以源码/单测冒充用户路径通过。测试与验证体系围绕该功能的测试分层清晰单元workspace-identity.test.ts真实 Git fixture、workspace-surfaces.test.tskey 格式、fail-closed、reorder、thread 归属、legacy OR 迁移、workspace-sidebar.test.tsreducer 行为、hydrate 顺序E2Eproject-panel.spec.tslauncher、pin/unpin、reload 恢复、Tab 栏加号、Browser gate、workspace-context-menu-actions.spec.ts三条 Inspector 点击路径Smoke Ledger计划文档以日期为行记录每轮验证——从 2026-08-25 的 interactive 1280/800/320 smoke、Playwright 4/4到 2026-08-26 的 full regressionnpm run test5384 pass / 0 fail / 1 skip、scoped Playwright 13/13、production build 137 pages再到 2026-08-28 的隔离审计full unit 5423 pass / 0 fail / 1 skip、真实库无新增。这为未跑真实布局路径不得标完成提供了可追溯的完成定义。关键文件索引关注点文件Canonical identity 纯函数 git 探针src/lib/workspace-identity.ts路径方言识别与 comparisonKeysrc/lib/path-identity.tsSurface registry 与双层状态 V1src/lib/workspace-surfaces.ts纯 reducer 状态模型src/lib/workspace-sidebar.tsReact Provider 与持久化编排src/hooks/useWorkspaceSidebar.tsxidentity APIGET/POSTsrc/app/api/workspace/identity/route.ts侧栏 UITabBar/TabPanelsrc/components/layout/WorkspaceSidebar/单测 / E2Esrc/tests/unit/workspace-identity.test.ts、src/tests/unit/workspace-surfaces.test.ts、src/tests/e2e/project-panel.spec.ts完成定义本计划的完成定义可作为验收标准单一 Workspace Surface shell 落地且同时保留 Files Preview 任务workspace/thread scope、worktree identity 与 migration 可解释、可测试、可重复执行Pin、当前 Tab 与 launcher 无假状态升级不丢现有 thread previews全新项目不被误判迁移v13 只在替代交互 Smoke passed 后删除并同步历史 breadcrumbTests pass UI Smoke passed Review passed 三者齐备才算完成。这套身份合同先行、状态双层分离、迁移幂等单调、删除双证据门禁的方法论对任何需要在多窗口/多会话桌面应用中统一工作区状态的项目都有直接借鉴价值。赞分享人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载相关推荐CodePilot Browser Surface MVP 深度解析基于 Hardened webview 的安全内置浏览器与 Workspace 隔离架构CodePilot Browser Surface MVP 深度解析基于 Hardened webview 的安全内置浏览器与 Workspace 隔离架构人工智能AI 应用AI Agent交互助手MCP Clients本地部署Bazel Bzlmod 迁移工具migrate_to_bzlmod实战指南从 WORKSPACE 平滑迁移到 MODULE.bazelBazel Bzlmod 迁移工具migrate_to_bzlmod实战指南从 WORKSPACE 平滑迁移到 MODULE.bazel 在 Bazel构建工具Loki 存储 Schema 配置全解时间分段索引模型、v13/tsdb 迁移与最佳实践Loki 存储 Schema 配置全解时间分段索引模型、v13/tsdb 迁移与最佳实践 Loki 通过一套可配置的存储 schemastorage sch可观测性日志分析后端微服务对象存储云原生上一篇加粗开关导致选区塌缩plate 富文本编辑器 Playwright RED 回归复现与选区保持验证指南下一篇Sapling 的 macOS 专用 WebViewwebview-sys FFI 绑定库源码解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考