WorkBuddy 缓存位置迁移 / WorkBuddy Cache Relocate

Overview

Move the WorkBuddy data root (default %USERPROFILE%\.workbuddy on Windows, ~/.workbuddy on macOS/Linux)
to another drive or folder, and keep skills, plugins and settings loading correctly afterwards.

The non-obvious part is why this is not simply an environment variable change. WorkBuddy resolves its
root from WORKBUDDY_CONFIG_DIR / CODEBUDDY_CONFIG_DIR, so setting those variables does redirect
new writes. But the app also persists absolute paths into several live state files - every plugin's
installPath, marketplace locations, skill metadata, the skill picker index, and the threat database.
After a naive variable change the app reads its manifests from the new location while those manifests
still point at the old one, which silently loads stale copies or fails outright.

The fix is to keep the old path valid by turning it into a directory junction (Windows) or
symlink (macOS/Linux) that points at the new location. Both mechanisms then agree, every historical
absolute path keeps resolving, and only one physical copy of the data exists.

When to use

• The system drive is nearly full and WorkBuddy's data root is a major consumer
• The user wants skills, plugins, logs or config stored on another drive
• The user asks how to change CODEBUDDY_CONFIG_DIR / WORKBUDDY_CONFIG_DIR
• The user asks to move or migrate .workbuddy

Preconditions

• Sufficient free space on the target drive, confirmed in Step 1
• Ability to create user-level environment variables
• Steps 1 and 2 run safely while WorkBuddy is open
• Step 3 requires WorkBuddy to be fully closed - including the tray icon. Never attempt it live.

Workflow

Run the steps in order. Do not skip Step 1: it decides whether the junction is required and surfaces
blockers before anything is changed.

Step 1 - Diagnose (safe, runs live)

python <skill-dir>/scripts/diagnose.py

Reports the persisted and in-process environment variables, the resolved root, whether that root is
already a junction, per-directory sizes, free space on both drives, and every live state file holding
an absolute path into the old root.

Stop and report instead of continuing if the root is already a junction - the migration has been done.
Stop if free space on the target is less than the reported root size plus 20%.

Step 2 - Prepare: full copy and environment variables (safe, runs live)

python <skill-dir>/scripts/prepare_migration.py --target D:\workbuddydata

Perform a full copy, then set WORKBUDDY_CONFIG_DIR and CODEBUDDY_CONFIG_DIR at user scope to the
target. Files locked by the running app are expected to be skipped here; Step 3 syncs them.

This step is non-destructive: it writes to the target and to the registry (or shell profile), and
never modifies or deletes the original directory. Report what was copied and which files were skipped.

Step 3 - Finalize: delta sync and junction (WorkBuddy MUST be closed)

Hand this step to the user rather than executing it.

Two things must happen before the script can run, and both are easy to get wrong:

1. The script ships as plain text. It is scripts/finalize_migration.cmd.txt because SkillHub's
   upload whitelist does not include .cmd. Copy it to a location the user controls and save it as
   finalize_migration.cmd - the user's Desktop is a good choice. Windows will ask whether to change
   the extension; that prompt must be confirmed.
2. That location must be outside the data root. The script renames the data root, so it cannot
   live inside it. That rules out running it straight from the skill folder at
   <root>\skills\workbuddy-cache-relocate\scripts\. The script checks this itself and refuses with a
   clear message, but copying it out first is the intended flow.

Then instruct the user to quit WorkBuddy completely - tray icon included - confirm that no
WorkBuddy.exe remains in Task Manager, and double-click the script (or run it from a terminal):

finalize_migration.cmd <target>
finalize_migration.cmd <target> <source>      (optional 2nd arg)

No Python is needed for this step - it is pure cmd. That matters: the interpreter bundled with
WorkBuddy is not on the persisted PATH, so python does not resolve once the app is closed. Never
tell the user to run a .py at this point.

The source defaults to %USERPROFILE%\.workbuddy. Pass the second argument only when the data lives
somewhere else, which is the state left behind by setting the environment variables by hand without a
junction.

The script:

• refuses to run if it detects that it is sitting inside the data root
• self-tests the process-detection mechanism first, and refuses to continue if it cannot read the
  process list, rather than risk a rename while the app is still writing
• refuses to run while WorkBuddy is alive
• verifies that the source is a real directory and that the target already holds settings.json
• performs the delta sync
• renames the original folder to <source>.old
• creates the junction and verifies that settings.json and skills are reachable through it

Any failure after the rename is rolled back automatically, leaving the original folder in place. It is
safe to re-run: an existing junction is detected and reported rather than acted on.

On macOS or Linux use the symlink procedure in references/internals.md instead.

Step 4 - Verify

After the user restarts WorkBuddy, confirm all of the following:

• The skill list and plugin list load normally
• C:\Users\<user>\.workbuddy\skills resolves to the target drive
• No new files appear under the old path other than through the junction
• The app still reports the same account and settings

If plugins or skills fail to load, check references/internals.md before rolling back.

Step 5 - Cleanup

The old data is retained as .workbuddy.old next to the original path. Advise the user to keep it
until WorkBuddy has run without problems for several days, then delete it to reclaim the space. Deleting
it is the step that actually frees the system drive. Never delete it automatically.

Rollback

• Before Step 3: delete the target directory. The original is untouched.
• After Step 3: remove the junction with rmdir "C:\Users\<user>\.workbuddy" (no /s, so only the link
  is removed), rename .workbuddy.old back, and clear the two environment variables.
• The finalize script performs the rollback automatically when a step fails.

Resources

• scripts/diagnose.py - read-only inspection of root, sizes, free space and stale absolute paths
• scripts/prepare_migration.py - full copy plus user-level environment variables
• scripts/finalize_migration.cmd.txt - delta sync plus junction, with automatic rollback. Shipped as
  .txt because .cmd is outside the SkillHub upload whitelist; copy it outside the data root,
  rename it to .cmd and run it with WorkBuddy closed
• references/internals.md - how the root is resolved, the state files that hold absolute paths, the
  macOS/Linux symlink procedure, sizing reference and troubleshooting