前言¶
在 DeepSeek Harness（DSH）里切换工程，依赖侧栏的工作区注册表。若你同时在 Cursor、Claude Code、Codex 等工具里开过大量项目，那些工具各自会记下「最近打开的路径」，而 DSH 侧栏不会自动对齐这份清单。手工把路径逐条加入侧栏，成本高，也容易漏。
更早的社区插件 Workspace Hub 曾做多工具扫描、账本与定时同步，但长期维护成本高，产品被收束为「用户最常要的一次性导入」。dsh-import-once 只保留扫描配方与这一动作：只读读取各工具本地状态，把尚未出现在 DSH 侧栏的项目文件夹登记进去，不做后台同步、不写独立账本。
下面介绍插件定位、能力边界、安装方式与典型用法。事实以仓库 README 与 package.json 为准。
这是什么¶
dsh-import-once 是 DSH 的客户端插件（维护者 dongsheng123132），版本 0.1.0，许可证 MIT。它通过一次模型工具调用（或你直接调用同名工具），把其他 AI 工具已在本地记录的项目目录导入 DSH 侧栏。
调用形态在 README 中写明：
dsh_import_once({ dryRun = false, maxAdd = 50 })
→ { dryRun, tools: [{ id, found }], scanned, missing, added, skipped, errors }
插件安装后不会自行扫描；只有调用 dsh_import_once 时侧栏才会变化。它是 Workspace Hub 的「一次性导入壳」，Hub 侧长期同步已不再维护，本仓库只保留扫描配方与实际有用的单一动作。
核心功能¶
单一动作，无附带状态机¶
README 明确列出「不是什么」：无账本文件、无间隔定时器、无后台队列、无 Git 同步、无 pin/排除列表、无状态目录、无 CLI 子命令。每次调用自给自足，不依赖插件自己的持久化状态。
只读扫描¶
各适配器只只读打开对应 AI 工具自己的状态文件（如 ~/.claude.json、VS Code 系 state.vscdb、Codex SQLite 等），提取项目文件夹路径与展示标题。不复制项目内容、不上传、无网络代码。
个别适配器会把正在使用的 SQLite 库复制到系统临时目录再读，读后立即删除，不修改原工具状态文件。
只增不改¶
唯一写操作是对缺失路径调用与官方侧栏相同的 workspaceRegistry.create(path, title)。不重命名、不重排、不删除已有工作区；误导入只能手工在侧栏移除。
无状态幂等¶
DSH 已拥有的文件夹按真实路径匹配，第二次调用应得到 added: 0。调用之间插件不记任何东西，侧栏注册表即权威状态。
真实 dry-run¶
dryRun: true 时按真实逻辑规划并返回与正式执行一致的数字，不写任何工作区。
多工具适配器¶
README 表格列出可读来源，涵盖 dsh、codex-app、claude-code、claude-desktop、trae / cursor / antigravity、workbuddy、kimi、uking、qwenwork、codebuddy、pi、qoder、deepseek-tui、hermes 等；doubao / doubao-work 仅探测且无本地工作目录。各平台路径由适配器自行解析（例如 Windows 上 WorkBuddy 使用 %USERPROFILE%\.workbuddy）。未出现在表中的工具不会被导入。
扫描后会过滤：仅仍存在于磁盘上的目录；跳过 app-managed 类临时(scratch)目录；跨工具重复路径会去重。因此 sum(tools.found) 可以远大于 scanned。
安装与启用¶
在 DSH 中安装（README 原文命令）：
dsh plugin --profile desktop add dsh-import-once # or --profile web
安装后重启 DSH。安装本身只注册一个工具，不触发扫描。
若使用 DSH 0.2.2 实验性插件市场 Discover，可把本仓库索引加入后再搜索 import-once（README 给出的索引 URL）：
https://raw.githubusercontent.com/dongsheng123132/dsh-import-once/main/plugin-index.json
路径：Plugins → Discover → Add index source，粘贴 URL。
package.json 标明运行需 Node >= 22，并与 @deepseek-ai/dsh-tools、@deepseek-ai/dsh-workspace 0.2.2-rc.1 等 peer 依赖对齐；你本机 DSH 版本应与插件声明兼容。
典型用法¶
参数¶
| 参数 | 类型 | 默认 | 含义 |
|---|---|---|---|
dryRun |
boolean | false |
仅规划；汇报数字且不写入 |
maxAdd |
integer | 50 |
本次调用最多创建工作区数；0 表示不限制 |
建议流程¶
1、先 dry-run，确认 missing、skipped 与 errors。
2、再正式调用，按需设置 maxAdd 分批导入。
可对模型说（README 示例）：
Import my projects from other AI tools into DSH. Dry run first.
或直接在对话里让模型调用 dsh_import_once。
返回字段¶
| 字段 | 含义 |
|---|---|
dryRun |
本次是否仅规划 |
tools[] |
每个适配器一行：id 与 found（该工具上报的原始记录数；0 表示未安装、无文件或不适用） |
scanned |
过滤与真实路径去重后的不重复项目目录数 |
missing |
其中侧栏尚未登记的数量 |
added |
本次创建数（dry-run 下为「将会创建」数） |
skipped |
因超 maxAdd、中止或失败而留待下次的缺失数 |
errors[] |
适配器错误 { tool, message } 与创建失败 { path, message } |
恒等式：missing = added + skipped；sum(tools.found) ≥ scanned（差额来自跨工具重复、scratch 与已不存在目录）。
README 在 2026-11-09、macOS、DSH 0.2.2-rc.1 上对 live store 的一次 dry-run：约 1.2 s 读完 18 个适配器，1304 条原始记录归并为 364 个不重复项目目录，其中 349 已在侧栏，故 missing: 28；maxAdd: 50 的正式调用可一次补全这 28 个。该数字随你本机工具与历史记录变化，仅作量级参考。
适用场景与注意¶
适合谁： 刚接入 DSH、已在多种 AI 客户端里积累项目路径，希望侧栏一次对齐「磁盘上仍存在的工程」，且不需要 Hub 式账本与定时同步的用户。
能力边界（README Limits）：
- 本版本说明中仅在 macOS 26.2 + DSH 0.2.2-rc.1 上实测；Windows / Linux 分支代码来自 Hub 同源适配器，但本 release 未在真机跑通。
- 只导入仍存在的文件夹；陈旧记录会被静默丢掉。
- 新工作区在注册表中 prepended，侧栏顺序跟扫描顺序有关，不一定等于其他工具里的「最近活跃」顺序。
- 工具描述与界面渲染文本以英文为主；本地化以仓库
README.zh-CN.md等为补充。
安全与权限： 插件在当前 DSH 进程权限下读你家目录下的各工具状态文件，并向 DSH 工作区注册表写入。安装前宜浏览 GitHub 仓库 源码与 MIT 许可证；适配器实现部分自 Workspace Hub 逐字节复制（见 vendor/README.md）。
社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态以「一切皆插件」为方向，Discover 亦无官方固定目录，需用户自行添加索引源。
结尾¶
dsh-import-once 把「多工具本地项目清单 → DSH 侧栏」收敛成一次只读扫描加只增登记：无账本、无定时、无跨设备同步，靠 dry-run 和 maxAdd 控制风险。需要持续对齐时，应另选方案或手工维护侧栏。
- 目录页：https://www.skillhub.cn/plugins/dongsheng123132/dsh-import-once
- 源码与完整说明：https://github.com/dongsheng123132/dsh-import-once
