DeepSeek Harness 插件：dsh-agent-project-sync

前言¶

DeepSeek Harness (DSH) 采用插件化架构。开发者在本地开发时，常需要在 Codex、Claude Code 等智能体工具间切换。尽管各工具保存会话的方式不同，但它们通常都会记录当前的工作目录 (cwd)。本插件通过读取这些元数据，将分散在各个工具中的项目目录汇聚到 DSH 的管理下，注册为原生的 Workspace，以便在 DSH 中统一管理和使用。

核心功能¶

harzva/dsh-agent-project-sync 是一个工作流插件，主要实现以下功能：

自动发现：自动发现 Codex 和 Claude Code 的项目目录。
注册 Workspace：将发现的目录注册为 DeepSeek Harness 原生 Workspace。
清单管理：管理共享项目清单 ($DSH_HOME/agent-project-sync/projects.json)，支持通过公开的 ctx.workspaceRegistry API 注册。
CLI 工具：提供本地命令行工具 (dsh-agent-project-sync)，用于扫描、列表和手动登记项目。
安全边界：
- 只读取每个 JSONL 文件开头最多 128 KiB，并仅提取 cwd 元数据。
- 默认全部写操作均为 dry-run。
- 同步仅新增或复用 Workspace，绝不删除现有数据、会话或项目目录。
- 清单使用原子写入、进程锁和用户私有文件权限，包含本机绝对路径，不应提交到公开仓库。

安装与启用¶

通过官方安装命令添加插件：

dsh plugin --profile web add https://github.com/Harzva/dsh-agent-project-sync/releases/latest/download/dsh-agent-project-sync-0.1.0.tgz

安装完成后，重新启动对应的 profile 即可使用。

典型用法¶

插件提供了本地 CLI 和 DSH 内置工具两种方式来操作项目清单。

本地 CLI 工具¶

本地 CLI 工具用于扫描目录并管理清单文件。

只读扫描：
查看当前发现的 Codex 和 Claude 项目，以及哪些已是 Workspace。

    dsh-agent-project-sync scan

扫描并写入清单：
将扫描结果保存到共享清单文件中。

    dsh-agent-project-sync scan --save --confirm

读取清单：
查看当前 DSH home 的共享项目清单。

    dsh-agent-project-sync list

手动登记项目：
手动添加一个目录到清单中。不加 --confirm 时仅预览。

    dsh-agent-project-sync add /path/to/project --confirm

DSH 工具¶

在 DSH 环境中，可以通过内置工具直接操作 Workspace 注册。

agent_projects_scan：只读扫描，显示发现的项目。
agent_projects_list：只读读取当前 DSH home 的共享项目清单。
agent_projects_sync：合并发现结果并注册缺失的 Workspace（默认 dry-run）。
agent_projects_add：手动添加一个现有目录（默认 dry-run）。

若要执行真实写入，需在调用时设置参数：

{
  "dryRun": false,
  "confirm": true
}

配置说明¶

插件支持通过配置文件或环境变量调整行为。

字段	默认值	说明
`sources`	`codex, claude`	启用的发现适配器列表
`codexHome`	`CODEX_HOME` 或 `~/.codex`	Codex 数据根目录
`claudeHome`	`CLAUDE_CONFIG_DIR` 或 `~/.claude`	Claude Code 数据根目录
`dshHome`	`DSH_HOME` 或 `~/.dsh`	共享清单所属的 DSH home
`excludePaths`	空	不导入的目录根及其子目录
`maxFilesPerSource`	`20000`	每个来源最多检查的 JSONL 文件数
`maxHeaderBytes`	`131072`	每个 JSONL 最多读取的开头字节数

注意事项与兼容性¶

权限与安全：插件通过当前 DSH 进程运行，需确保 DSH 进程有权限读取源智能体（如 Codex、Claude Code）的数据目录。
数据保留：卸载插件不会删除已有的 Workspace、项目目录或共享清单文件。
清单安全：清单文件包含本机绝对路径，属于机器本地数据，不应提交到公开代码仓库。
兼容基线：DeepSeek Harness / dsh 0.1.0-rc.8、Cordis ^4.0.1、Node.js ^22.19 || >=24。