Table of Contents

apes-sidebar 项目百科

一、项目速览
二、两条版本线（重要）
三、文档地图
四、快速开始（TL;DR）
五、仓库内的事实源
六、谱系说明（如实交代）

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

apes-sidebar 项目百科

DeepSeek Harness（DSH）的服务化右侧边栏工作台 + apes 信息层。本项目是 dsh-better-sidebar（MIT）的 fork，在其「文件 / 文件变动 / 任务 / 侧边对话 / 终端 / 浏览器」工作台之上，追加三个信息层标签页： 智能体（agents）/ 应用（apps）/ 画像（profile）。

一、项目速览

项	值
仓库	`figmar/apes-sidebar`（公开）
默认分支	`main`
许可证	MIT（fork 自 `omdsh-dev/DSH-better-sidebar`）
语言 / 构建	TypeScript（strict）· `tsdown`（rolldown）· `pnpm`
宿主	DSH Desktop（Electron 壳）或 DSH Web profile
上游跟随方式	不合并上游提交，而是测量式 re-base（见 07-开发与测试）

二、两条版本线（重要）

本仓库同时维护两条互相独立、不能同时挂载的版本线（两条线都注册 ctx.betterSidebar， cordis entry id 冲突，第二个会被丢弃）：

分支	版本	上游基线	peer / 宿主要求	状态
`main`	1.2.0	`dsh-better-sidebar` v0.19.1（`8753096`）	`^0.1.5-rc.1`（DSH 0.1.5-rc.1+）	已在本机 DSH Desktop 2.0.10（`dsh 0.1.5-rc.2`）实机运行
`sync/v0.24.1`	1.3.0	`dsh-better-sidebar` v0.24.1（`a2751cf`）	`^0.2.0-rc.1`（DSH 0.2.0-rc.1+）	构建与测试全绿，待具备 0.2.0 宿主实机验证

⚠️ 宿主的兼容性预检是「静默禁用」，不报错、不加载、无日志。 宿主用 semver.satisfies(host, peerRange, { includePrerelease: true }) 判定；caret 范围跨 minor 不成立（^0.1.5-rc.1 在 0.2.0 宿主上为 false），于是整行被跳过。 现象 = 插件"好像没装"。选线请先看宿主版本，见 04-部署指南。

三、文档地图

页面	内容
01-需求分析	官方原生 vs 装了本包：官方右列只有「文件树 + 只读文本预览」（附官方包证据），九个 tab 是一个整体需求；7 条需求变化洞察、U1–U6、已知限制
02-系统架构	host/client 拆分、三层接口面、面板宿主层级契约、关键不变量
03-功能说明	全部标签页与预览器、信息层数据来源、i18n、主题令牌、安全边界
04-部署指南	环境矩阵、选线、profile 接线、构建、验收清单、卸载
05-运维手册	版本线与分支策略、回滚剧本、发布纪律、巡检、备份铁律
06-故障排查	症状 → 根因 → 处置（含全部实机验证过的案例）
07-开发与测试	工程约定、目录、门禁、测试体系、扩展点、上游 re-base 方法

四、快速开始（TL;DR）

# 1) 构建（Node ≥ 20，pnpm）
pnpm install && pnpm typecheck && pnpm build && pnpm test

# 2) 接到 DSH profile（以桌面 profile 为例，使用 file: 链接依赖）
#    在 ~/.dsh/profiles/desktop/package.json 中：
#      "dsh-apes-sidebar": "file:/绝对路径/dsh-apes-sidebar"
#    并在 dsh.profile.bundles 列表里加入 "dsh-apes-sidebar"

# 3) 让 profile 重新安装依赖，然后 ⌘Q 完整退出 DSH 再启动

完整步骤与坑见 04-部署指南。

五、仓库内的事实源

位置	说明
`README.md`	面向用户的功能与安装说明（主体沿用上游文档，顶部有 fork notice）
`AGENTS.md`	面向 agent/协作者的工程约定（构建、布局、硬性规则、测试约定）⚠️ 注意：本文件当前描述的是另一套 from-scratch 实现，与 `main` 的 fork 树不一致，以源码为准
`docs/external-plugin-guide.md`	插件接入指南：`ctx.betterSidebar.registerTab / registerFileViewer` 的对外契约
`docs/plans/`	上游历史设计文档（保持上游原样，未随 fork 改名）
`docs/wiki/`	本百科的源文件（Gitea wiki 页面的可版本化副本，由 `scripts/push-wiki.sh` 推送）
`scripts/switch.sh`	两线切换脚本（`aps` ↔ `upstream`），含 `--status`

六、谱系说明（如实交代）

figmar/apes-sidebar 这个仓库先后承载过同一产品族的三代实现：

v1：早期 JS bundle 版侧边栏插件（仓库描述里提到的「可配置显示名 / 预设 feyOS」即出自那一代）；
v2：from-scratch 重写（src/index.ts + src/client/index.tsx 结构，五个 apes:* tab），即 AGENTS.md 所描述的那一套，其产物不在当前 main 上；
当前线（v0.19.1 / v0.24.1 fork）：即 main 与 sync/v0.24.1 上的代码——本百科描述的对象。

若需要把本百科改写成描述 v2 重写版，请告知，源文件在 docs/wiki/ 可直接替换。