dsh-agent-project-sync
把 Codex、Claude Code 等本地智能体使用过的项目目录汇总到一个 DSH home，并注册为 DeepSeek Harness 原生 Workspace。不同智能体继续操作同一份源码；插件不复制项目、不迁移聊天记录，也不建立第二份项目文件。
它解决什么
一个项目可能先在 Codex 中打开，又在 Claude Code 中继续，最后希望从 DSH 接管。各工具保存会话的方式不同，但都记录了工作目录 cwd。本插件只读取 JSONL 开头的这项元数据，按真实目录路径去重，然后：
- 生成当前机器的共享项目清单：
$DSH_HOME/agent-project-sync/projects.json。
- 通过公开的
ctx.workspaceRegistry API，把存在的目录注册为 DSH Workspace。
- 提供本地 CLI，让其他智能体读取或手动补充同一清单。
当前内置 Codex 与 Claude Code 适配器；结构允许以后添加 Cursor、Kimi、OpenCode 等来源。
安全边界
- 只读取每个 JSONL 文件开头最多 128 KiB，并只提取
cwd；不保存或返回聊天正文。
- 默认全部写操作都是 dry-run；DSH 工具真实写入必须
confirm=true 且 dryRun=false。
- 同步只新增或复用 Workspace，绝不删除 Workspace、会话、项目目录或源智能体数据。
- 清单使用原子写入、进程锁和用户私有文件权限；它包含本机绝对路径，属于机器本地数据，不应提交到公开仓库。
- 指定另一个 DSH home 时，通过
DSH_HOME 或插件的 dshHome 配置选择；插件不会直接改写其他 home 的内部 Workspace 数据。要同步哪个 home，就在那个 home 的 profile 中加载插件。
安装
从 GitHub Release 安装：
dsh plugin --profile web add https://github.com/Harzva/dsh-agent-project-sync/releases/latest/download/dsh-agent-project-sync-0.1.0.tgz
开发目录链接安装：
npm install
npm run check
dsh plugin --profile web add -w link:/absolute/path/to/dsh-agent-project-sync
安装后重新启动对应 profile。若使用单独的 DSH home：
DSH_HOME=/path/to/selected-home dsh plugin --profile web add -w link:/absolute/path/to/dsh-agent-project-sync
DSH_HOME=/path/to/selected-home dsh web
也可以把 bundle 行直接加入 profile：
- insert:
- id: agent-project-sync
name: dsh-agent-project-sync
config:
sources: [codex, claude]
maxFilesPerSource: 20000
maxHeaderBytes: 131072
excludePaths: []
DSH 工具
| 工具 | 默认行为 | 用途 |
|---|
agent_projects_scan | 只读 | 发现 Codex/Claude 项目并显示哪些已是 Workspace |
agent_projects_list | 只读 | 读取当前 DSH home 的共享项目清单 |
agent_projects_sync | dry-run | 合并发现结果并注册缺失 Workspace |
agent_projects_add | dry-run | 手动加入一个现有目录 |
真实同步示例参数：
{
"dryRun": false,
"confirm": true
}
可以先用 agent_projects_scan 得到稳定项目 id，再把 ids 传给 agent_projects_sync 只处理选中的目录。
给 Codex、Claude 等使用的 CLI
# 只读扫描
dsh-agent-project-sync scan
# 扫描并写入共享清单
dsh-agent-project-sync scan --save --confirm
# 读取同一清单
dsh-agent-project-sync list --json
# 手动登记一个项目；不加 --confirm 时只预览
dsh-agent-project-sync add /path/to/project --confirm
CLI 只管理共享清单。原生 DSH Workspace 写入必须在加载插件的 DSH Host 内完成，以免绕过 DSH 的存储与生命周期约束。
配置
| 字段 | 默认值 | 说明 |
|---|
sources | codex, claude | 启用的发现适配器 |
codexHome | CODEX_HOME 或 ~/.codex | Codex 数据根 |
claudeHome | CLAUDE_CONFIG_DIR 或 ~/.claude | Claude Code 数据根 |
dshHome | DSH_HOME 或 ~/.dsh | 共享清单所属 DSH home |
registryPath | DSH home 下的默认清单 | 仅覆盖共享清单文件位置 |
excludePaths | 空 | 不导入的目录根；其子目录也跳过 |
maxFilesPerSource | 20000 | 每个来源最多检查的 JSONL 文件数 |
maxHeaderBytes | 131072 | 每个 JSONL 最多读取的开头字节数 |
开发与验证
npm run check
pnpm run pack:dsh
npm run preflight
npm run verify:dsh-offline
npm pack --dry-run
verify:dsh-offline 创建临时隔离的 DSH_HOME，安装刚打包的 tarball 并检查配置组合；不会触碰日常 profile。
兼容基线：DeepSeek Harness / dsh 0.1.0-rc.8、Cordis ^4.0.1、Node.js ^22.19 || >=24。
卸载
从目标 profile 移除包并重启：
dsh plugin --profile web remove dsh-agent-project-sync
卸载不会删除已有 Workspace、项目目录或共享清单。若要清理清单，请由用户单独确认并删除该机器本地文件。
License
MIT
