前言¶
在 DeepSeek Harness（DSH）里做智能体与 AI 项目，常见情况是：仓库散落在多个磁盘目录，SKILL.md 和技能目录分散在 Agent 工具链里，DSH 与 Codex 的会话又各自落在本地数据文件中。用文件管理器或命令行逐个打开，很难一眼看到「有哪些项目、处于什么阶段、最近跑了什么、产出在哪」。
Project Atlas 是 DSH 生态里的一款客户端插件（维护者 ruide92），把本机项目、技能、会话、运行状态与产物收进一个可缩放的可视化工作台。它默认只读，不会擅自改写你的项目；是否把项目交给 Agent，由你在项目页里明确操作。下面介绍它的定位、能力与从零配置到日常使用的步骤。
这是什么¶
Project Atlas（仓库 ruide92/dsh-project-atlas）的定位是：local-first 的可视化工作台——projects、skills、sessions、runtimes、artifacts 集中呈现在一张「地图」里，而不是依赖云端账号或同步服务。
与「只在 IDE 里打开单个仓库」相比，它侧重跨目录索引与总览：项目生命周期、本地备注、技能图谱、会话索引、运行与产物预览、磁盘与 AI 软件概览等，都在插件界面内完成。数据与隐私上，插件强调没有账号、没有云端同步、没有遥测；项目内容仅在本机读取。
核心功能¶
以下能力均来自仓库 README 与说明文档的表述。
四个场景¶
工作台提供四个场景：地球、工作室、图书馆、时间庭。不同场景承载不同的浏览与导航方式；例如在地球上可为项目设置地图锚点（仅用于布局，不代表项目真实地理位置）。
项目与生命周期¶
- 项目总览、生命周期状态与本地备注（写在工作台本地数据，不修改项目仓库内文件）。
- 支持扫描配置下的根目录，识别工作区容器、排除常见依赖与构建目录（可通过配置调整）。
技能与会话¶
- SKILL.md 图谱：在配置的
skillRoots下扫描技能文档。 - DSH / Codex 会话索引：读取 DSH 会话目录与 Codex 数据库（若存在）；OpenCode 数据库路径可选手动配置。
运行、产物与系统概览¶
- 运行状态、产物预览。
- 磁盘与 AI 相关软件概览（只读索引）。
安全与删除策略¶
- 默认不允许在界面删除项目；
allowDelete为true时，也仅针对标记为「已弃用」的顶层项目，且走回收站并需二次确认。 - 插件自身、DSH 数据目录、用户主目录及常见个人目录始终受保护；可额外配置
protectedPaths。
安装与启用¶
DSH 采用「一切皆插件」的扩展方式；社区插件目录见 SkillHub 条目，与 DeepSeek / 幻方无官方从属关系，安装前建议自行查看源码与 MIT 许可证。
从插件市场安装¶
在 DSH 插件市场搜索 Project Atlas 或 项目工作台，安装后按桌面端提示重启。若市场条目尚未收录，可使用下面的手动安装（仓库与 Release 已可直接下载）。
手动安装¶
将 <profile> 换成你实际使用的 DSH profile 名称：
dsh plugin --profile <profile> add github:ruide92/dsh-project-atlas
若 dsh 不在 PATH 中，使用桌面端内置的完整 CLI 路径。也可在 ~/.dsh/profiles/<profile>/package.json 的 dsh.profile.bundles 中加入 dsh-project-atlas，然后重启桌面端；具体路径以你的 DSH 安装为准，或从 GitHub 仓库的 tarball 地址安装。
环境与权限：插件以当前 DSH 进程的权限读取本机目录与会话数据；安装前应确认你信任该仓库源码，并理解其读取范围（详见仓库内 隐私与安全 文档）。
第一次使用与配置¶
插件不会猜测硬盘、用户名或项目目录。首次打开为空状态，属于有意的安全默认值。需要先写入扫描配置，再在工作台点击「重新扫描」。
配置文件位置（优先级从高到低）¶
- 环境变量
DSH_WORKBENCH_CONFIG指向的 JSON 文件 - 插件目录下的
workbench.config.json（开发时使用） ~/.dsh/data/dsh-workbench/config.json（推荐，升级插件不会丢失）
最小示例¶
下面示例表示：扫描 D:/work 下最多 4 层深度，显示标签为 Work。路径请改为你本机实际目录。
{
"roots": [
{ "path": "D:/work", "depth": 4, "label": "Work" }
]
}
保存配置后回到工作台，点击「重新扫描」。
常用配置项摘要¶
完整字段见仓库 配置参考。下表为 README 中的核心项：
| 字段 | 默认值 | 说明 |
|---|---|---|
roots |
[] |
要扫描的根目录；为空则不扫描任何目录。 |
excludeGlobs |
常见依赖/构建目录 | 扫描时排除的 glob。 |
workspaceNames |
Projects / Workspace / Code 等 |
视为「工作区容器」的目录名。 |
skillRoots |
常见 Agent 目录 | SKILL.md 扫描根；设为 [] 可关闭技能扫描。 |
dshHome |
~/.dsh |
DSH 数据目录。 |
dshSessionsDir |
<dshHome>/sessions |
DSH 会话目录。 |
codexDb |
自动探测 ~/.codex/state_5.sqlite |
Codex 会话数据库；不存在时静默跳过。 |
allowDelete |
false |
是否允许删除已弃用项目。 |
运行产生的缓存、备注、交接记录等写在 ~/.dsh/data/dsh-workbench/，不会被打进 npm 包或 Git 仓库。
调整地球上的项目锚点¶
从地球场景的项目索引选中项目，在项目卡片或落点中点击「设置地图位置」。可「地图选点」或输入经纬度后「保存位置」，也可恢复自动位置。锚点仅用于工作台布局，保存在工作台本地数据中。
适用场景与注意¶
适合谁：在本机维护多个 AI / Agent 相关仓库，希望在一个 DSH 客户端界面里总览项目、技能、会话与运行产物的开发者。
需要注意：
- 必须自行配置
roots等项，否则长期为空状态是预期行为。 - 只读默认为主；删除与 Agent 交接类操作均有边界，详见官方故障排查文档（空状态、配置、会话、端口与双工作台冲突等）。
- 开发该插件要求 Node.js >= 22.18（使用
node:sqlite读取 Codex 会话）与 DSH >= 0.2.0-rc.1；普通用户通过 DSH 安装插件即可，无需单独 clone 仓库。
结尾¶
Project Atlas 把分散在本机的 AI 项目、技能文档、DSH/Codex 会话与运行信息，收进一个本地优先、无遥测的可视化工作台；配置扫描根目录后即可「重新扫描」建立索引，再在地球、工作室、图书馆、时间庭等场景中浏览与备注。
- 插件目录页：https://www.skillhub.cn/plugins/ruide92/dsh-project-atlas
- 源码与文档：https://github.com/ruide92/dsh-project-atlas
版本变更见仓库 CHANGELOG.md；当前 package 版本为 1.2.0。
