前言¶
在 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。
