From 8d66097bf0bbf5f3e623b3d3b84c8b56ef3de00d Mon Sep 17 00:00:00 2001 From: figmar Date: Sun, 4 Oct 2026 01:18:58 +0800 Subject: [PATCH] Add "Home" --- Home.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 Home.md diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..07b5063 --- /dev/null +++ b/Home.md @@ -0,0 +1,82 @@ +# 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-需求分析) | 背景、五条核心需求(含验收标准与状态)、非目标与约束 | +| [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/` 可直接替换。