# apes-sidebar 项目百科

> DeepSeek Harness（DSH）的**服务化右侧边栏工作台** + **apes 信息层**。
> 本项目是 [`dsh-better-sidebar`](https://github.com/omdsh-dev/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-开发与测试](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-部署指南](04-部署指南)。

## 三、文档地图

| 页面 | 内容 |
| --- | --- |
| [01-需求分析](01-需求分析) | **用户为什么会需要**：原生 / 上游 / 本 fork 三种供给对比、逐 tab「只有原生时他怎么办」、7 条需求变化洞察、U1–U6、已知限制 |
| [02-系统架构](02-系统架构) | host/client 拆分、三层接口面、面板宿主层级契约、关键不变量 |
| [03-功能说明](03-功能说明) | 全部标签页与预览器、信息层数据来源、i18n、主题令牌、安全边界 |
| [04-部署指南](04-部署指南) | 环境矩阵、选线、profile 接线、构建、验收清单、卸载 |
| [05-运维手册](05-运维手册) | 版本线与分支策略、回滚剧本、发布纪律、巡检、备份铁律 |
| [06-故障排查](06-故障排查) | 症状 → 根因 → 处置（含全部实机验证过的案例） |
| [07-开发与测试](07-开发与测试) | 工程约定、目录、门禁、测试体系、扩展点、上游 re-base 方法 |

## 四、快速开始（TL;DR）

```bash
# 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-部署指南](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` 这个仓库先后承载过同一产品族的三代实现：

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

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