figmar
63bcb47ed0
Gitea 的 wiki 此前是空的。本次把百科的**源文件版本化进仓库**（docs/wiki/）， 再用脚本发布到 wiki——文档因此与代码同源、可 review、可回溯，而不是只存在于网页上。 八页（Home 作为导航与项目速览）： Home 项目速览 / 两条版本线的宿主兼容性差异 / 文档地图 / 谱系说明 01-需求分析 五条核心需求（现象·根因·验收标准·状态）+ 非目标与约束 + 需求→实现→锚点 02-系统架构 host/client 分层与产物、三层接口面、面板宿主层叠契约与 isolate 陷阱、关键不变量 03-功能说明 面板/预览器总表、信息层三 tab 数据来源、HTML 预览交付方式、i18n 与令牌、配置面 04-部署指南 宿主版本矩阵与选线决策、profile 接线（file: + bundles）、构建、验收清单、卸载与切换 05-运维手册 分支/tag 策略与回滚剧本、发布纪律（版本三元组/非确定性产物）、巡检、备份铁律、诊断 06-故障排查 8 类症状 → 根因 → 处置（含本会话实机定位过的全部案例）+ 定位手法 07-开发与测试 工程约定、目录、门禁基线、测试分层与契约 spec、扩展点、测量式 re-base 方法 脚本 scripts/push-wiki.sh：幂等发布（POST 新建 / PATCH 覆盖），凭据走 git credential helper （临时 netrc，600，退出即删），不落盘、不进 argv。已实测：8 页全部发布成功，复推为更新。 内容纪律：只写**本次会话实证过**的事实（提交号、行数、层级取值、产物大小、宿主版本矩阵、 静默禁用机制、re-base 步骤），未验证的部分明确标注为待验证或已知限制；并如实说明本仓库 历代承载过 v1 / v2 / 当前 fork 三代实现，本百科描述的是 main 上的 fork 线。
4.8 KiB
4.8 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-需求分析 | 背景、五条核心需求（含验收标准与状态）、非目标与约束 |
| 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/ 可直接替换。