dsh-workspace-merge
One DSH session, several project roots.
A DSH session is rooted at exactly one working directory — that directory is the
sandbox boundary, the workspace key, and the base for every relative path. That
default is right almost always, but it makes a very common layout awkward: the PC
and mobile clients of one product, an iOS and a HarmonyOS app that must stay in
step, a shared library and its consumers. They live in sibling directories, and
"change the same file in both places" degenerates into absolute paths and
repeated calls that quietly drift apart.
This bundle adds a named workspace group — an ordered set of local project
roots — and eight ws_* tools that treat one relative path across every root of
the group as a single operation, with a per-root outcome instead of one opaque
failure.
one call: ws_edit src/components/AmountInput.vue
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
[pc] ecam-ui [mobile] ecam-mobile [shared] lib-ui
changed · 1 replacement changed · 1 replacement not-found
Install
dsh plugin add dsh-workspace-merge
Or add it to a profile by hand: install the package under $DSH_HOME/profiles/web
and list dsh-workspace-merge in dsh.profile.bundles.
Configure
A group is a name plus roots. id is the short label every other tool uses;
path may be absolute or ~-prefixed.
// ws_group_set {group:"ecam", description:"PC + mobile", roots:[
// {id:"pc", path:"~/Desktop/JLXY/ecam-ui"},
// {id:"mobile", path:"~/Desktop/JLXY/ecam-mobile-ui"}
// ]}
That writes $DSH_HOME/workspace-groups.json:
{
"version": 1,
"groups": {
"ecam": {
"description": "PC + mobile",
"roots": [
{ "id": "pc", "path": "/Users/you/Desktop/JLXY/ecam-ui" },
{ "id": "mobile", "path": "/Users/you/Desktop/JLXY/ecam-mobile-ui" }
]
}
}
}
The file is plain JSON — hand-edit it if you prefer.
Group selection. A call may pass group explicitly. Otherwise the group
whose root contains the session directory wins (the longest matching root breaks
a tie between nested roots); with no match, a single defined group is
unambiguous, and any other count requires an explicit name.
Tools
| Tool | Purpose |
|---|
ws_groups | List groups, their root ids, and the active group for this session. |
ws_group_set / ws_group_remove | Maintain the registry (project files are never touched). |
ws_ls | List one relative directory across every root — locate the same component everywhere at once. |
ws_read | Read the same relative path from every root and return each copy. |
ws_diff | Line-diff the copies (first root is the baseline) before editing anything. |
ws_edit | Apply ONE literal replacement to every root, per-root outcome. |
ws_write | Write the SAME full content to every root — new shared file, or force copies back in sync. |
ws_edit follows the built-in edit rule: old_string must occur exactly once
unless replace_all is set. ws_edit and ws_write accept dry_run to preview,
and roots: ["pc"] to narrow a call to one project. Per-root statuses are
explicit — changed / unchanged / not-found / ambiguous / missing /
invalid / denied — so a partial application is visible, never silent.
Sandbox behaviour
Every mutation resolves the session's sandboxPolicy first, and this bundle does
not widen it:
danger-full-access — writes resolve unfenced, as everywhere else.workspace-write — each target is canonicalized (a missing file is re-anchored
under its nearest existing ancestor, so a symlinked parent cannot smuggle the
write out) and must fall inside the policy's writable roots.read-only — all mutations are refused.
A target outside the standing roots is refused with the official
[sandbox: file access denied under … mode] marker plus the escalation hint, and
can be retried once with sandbox_permissions + justification, exactly like the
built-in write and edit tools. The group registry itself (ws_group_set,
ws_group_remove) obeys the same policy — a read-only session cannot quietly
reconfigure groups.
Notes and limits
- A group is not a monorepo. It changes where the
ws_* tools point; it does
not change the session's working directory, so the built-in read / edit /
write / bash still resolve against the session root only. Use a group when
one change must land in several projects in the same step.
- Writes go through the harness filesystem service (
ctx.fs): the pre-write
version is registered with the official fs/observed event, so the
fs-observation policy issues replaceIfVersion rather than refusing the write
as FS_NOT_OBSERVED, and other plugins can veto through fs/write-intent.
When that service is not mounted, the plain node:fs path is used after the
same policy decision — and the result says so (via: node:fs (fs service failed: …)) instead of hiding it, so an integration problem is visible rather
than silent.
ws_ls skips .git and node_modules, and caps output at 200 paths per root.ws_diff aligns lines up to 4000 per side; larger files get a size summary
instead of a diff.
Test
npm test
31 assertions over a throwaway DSH home and two throwaway roots: registration,
registry CRUD, group selection, read/diff/list, dry-run, per-root mutation
statuses, path-escape refusal, root-id validation, and the sandbox cases
(danger-full-access, workspace-write deny, read-only deny, registry-write
policy). The test links the harness's own @deepseek-ai/dsh-tools and
@deepseek-ai/dsh-sandbox from the DevEco/DSH install (see node_modules), so
npm test expects a local DSH installation.
The stub context reproduces two cordis rules that cost this bundle a real boot
each, and fails loudly if a future edit breaks them again:
- a service not declared in
inject is not a readable property —
ctx.systemPrompt throws rather than returning undefined, which takes the
whole row (and every tool registered before the throw) down with it, silently;
optional services must be read with ctx.get(name);
- section placement is centrally allocated —
getSectionOrder() returns
undefined for a name the harness does not know, and a section with a
non-finite order throws. This bundle uses the TOOLS_SDK placement with a
numeric fallback.
Diagnostics
WSM_DEBUG=1 records the plugin's startup phases (module evaluated → apply →
tools service available → registration result) to stderr and
<tmpdir>/dsh-workspace-merge-debug.log. Use it when a row is in the composed
profile but its tools never appear in a session.
License
MIT © 宋朝阳
