figmar
40a05af9ba
用户纠正：editor/git/subagent/sidechat/terminal/browser 也是 apes-sidebar 打包进来的，对外是一个完整需求整体，对比的另一端只能是 DSH 官方原生。 - 用官方包自带 README 取证：原生右列 = 容器(sidebar-right) + 唯一页「文件」 (sidebar-files, 只读) + 唯一查看器(documentpreview, kind=text, 纯文本兜底) - 新增官方原生做不到的九件事表，作为 user 处境的 before - 洞察 0 改为「官方假设你只是看，而真实使用是在这儿干活」(只读→可写) - 新增洞察 6：官方只有一个入口→罗盘不出现；入口一多罗盘才登场(单一工具→工作台) - 附录补官方证据引文；上游/fork 的区别降为对内维护说明
5.0 KiB
5.0 KiB
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/ 可直接替换。