wodistant-bridge

---
name: wodistant-bridge
description: Operate WOLF RPG Editor through the local Wodistant Bridge Python client or CLI to inspect, export canonical human-readable command text plus optional Event Code, analyze, and safely replace Common or Map Events; navigate maps and event commands; inspect UDB/CDB/SDB lists; and control supported Map Editor actions. Use when an agent must work with WOLF RPG Editor without manual Wodistant navigation while preserving auditable Git diffs, confirmations, backups, and hash verification.
---

# Wodistant Bridge

Use the bundled dependency-free Python client to control the Wodistant plugin.
Require Windows and Python 3.9 or newer. Read-only operations require plugin
version 0.3.1 or newer; replacement writes require plugin version 0.3.2 or
newer. Map navigation, database navigation, editor state, and toolbar commands
require plugin version 0.4.0 or newer. Prefer index-based map opening, which
requires plugin version 0.4.1 or newer.

Read [references/commands.md](references/commands.md) when constructing
commands or interpreting Event Code responses.

## Operation policy switches

Before any write or confirmation decision, read
[`../../wodistant-bridge-policy.md`](../../wodistant-bridge-policy.md)
(repo path `.agents/wodistant-bridge-policy.md`). Treat unknown or missing
switches as off (safer side).

- `auto_commit_on_clear_task`: when true and the user already gave a clear
  target event plus intended effect, skip the extra “確認寫入” prompt after
  a successful `prepare-replace`; commit immediately with `--confirm`.
  Still refuse to invent a target or auto-commit when the task is ambiguous.
- `auto_export_readable`: when true, after a verified commit with
  `commandAlignmentValid=true`, immediately `export-readable` over the
  existing canonical tracked text and report the Git diff. Do not wait for
  the user to say they pressed Update/Save.
- `remind_update_save`: when true, after auto-export still remind once that
  WOLF Update/Save is manual and needed to persist `.dat`.
- `require_confirm_map_open` / `require_confirm_toolbar` /
  `require_confirm_key_down`: when true, keep asking for action-time
  confirmation before those commands.

## Resolve the client

Prefer `scripts/wodistant_bridge.py` relative to this SKILL.md. Invoke it with
the available Python 3 interpreter. It communicates with the bridge directly;
the compiled CLI executable is not required.

Use the .NET CLI only as a fallback:
`cli\WodistantBridge.Cli.exe` in the Windows release package, or
`WodistantBridge\WodistantBridge.Cli\bin\Release\WodistantBridge.Cli.exe`
in a built source checkout. Resolve either path from its installation location.

Named-pipe access can fail inside a sandbox. If a request times out or is
denied despite Wodistant running, rerun the same client command with the
environment's escalation mechanism. Scope approval to Python plus the exact
`wodistant_bridge.py` path; never request a broad Python approval.

## Serialize bridge requests

Run only one bridge client request at a time. Never issue `ping`, `status`,
read, export, validation, prepare, commit, or verification requests in
parallel. The local named-pipe bridge may accept only one active client
request, causing otherwise valid concurrent requests to fail with a missing
pipe or connection error.

Wait for each command to finish before starting the next one. Treat a
concurrent connection failure as inconclusive: rerun the failed read-only
command once by itself before reporting the bridge unavailable. Never
automatically retry a write or `commit-replace`; inspect its result and current
event state first.

## Establish readiness

Run `ping` and `status` before event work.

- Require `pluginVersion >= 0.3.1` for reads.
- Require `pluginVersion >= 0.3.2` before any write.
- Require `woditorConnected=true`.
- Require `gamePlaying=false` before any write.
- Require `commonEventEditorAvailable=true` for Common Event operations.
- Require `mapEventEditorAvailable=true` for Map Event operations.
- Require the matching `userDatabaseEditorAvailable`,
  `changeableDatabaseEditorAvailable`, or `systemDatabaseEditorAvailable`
  status for database operations.

If Map Event availability is false, instruct the user to keep the Map Event
Editor open and restart Wodistant. Wodistant 1.4.6.5 captures that window only
during connection initialization.

## Read and analyze events

### Common Events

The Common Event Editor window must be open. It does not need to show the
target event. `common-events read INDEX` calls `OpenCommonEvent(INDEX)` and
therefore changes the editor selection automatically.

Prefer this sequence:

1. Record `common-events current`.
2. Read the requested index. Use `export` when a temporary Event Code backup
   is needed.
3. Check `eventCodeAvailable`, `hash`, and `commandAlignmentValid`.
4. Use structured `commands` entries to associate each `index`,
   `displayName`, and `rawCode`.

## Keep one canonical readable audit export

Git is the user's before/after comparison. Do not create readable `.before`
and `.after` copies in the workspace.

Use `export-readable` after verified changes to overwrite the one canonical
tracked text export. Keep Event Code in a temporary or ignored path. The
readable file
preserves the WOLF-style `■`, branch, and leading `|` nesting markers. Resolve
the existing canonical file from the current project's instructions and stable
event identity; do not assume a game-specific directory layout.

Do not use Woditor's `Q`/`W` clipboard-copy commands, low-level `key-down`, or
Computer Use to create readable exports. `export-readable` and the optional
`export-pair` derive text from the structured Bridge read response and never
read or change the Windows clipboard.

For an edit:

1. compare the Bridge read with the existing canonical export;
2. keep replacement Event Code in a temporary or ignored path;
3. after verification, overwrite the canonical tracked text with
   `export-readable` at the time specified by `auto_export_readable` (otherwise
   wait for WOLF Update/Save confirmation);
4. inspect that one file with Git.

Explain the human-readable Git differences to the user. Do not claim
that an uncommitted replacement has a readable Woditor rendering; that
rendering is available only after Woditor accepts and reads the replacement.

### Map Events

Map Event operations apply to the map and Map Event Editor currently open in
WOLF RPG Editor.

Wodistant 1.4.6.5 may return an empty event list. When the read response says
`usingCurrentEditorFallback=true`, access only the already-open event. Never
assume another Map Event index can be opened safely.

## Navigate editors and databases

Record the current selection before changing editor state. Selection, focus,
visibility, list-top, and database type/data navigation are reversible UI
operations, but they still change what the user sees.

Ask for explicit action-time confirmation before adding `--confirm` to the
following, unless the matching policy switch is off:

- `maps open-index` (preferred) or `maps open` when
  `require_confirm_map_open` is true, because switching maps may interact
  with unsaved editor state;
- `maps update-data` because it invokes WOLF RPG Editor's data update
  (always confirm; no policy bypass);
- `map-editor click-toolbar` when `require_confirm_toolbar` is true,
  because items include Save, Undo, database editors, TestPlay, and
  map-generation actions;
- any `key-down` command when `require_confirm_key_down` is true, because
  the virtual key's effect depends on focus.

Use `maps list` to resolve the target and prefer `maps open-index INDEX`.
Wodistant 1.4.6.5 can return mojibake and trailing full-width spaces in map
names, while `maps current` returns a different display string. Never derive
the open name from `maps current`.

After opening a map, verify `maps current` and `map-editor status`. A
previously open Map Event Editor may no longer refer to a usable event; recheck
`map-events editor-state` before reading or writing.

Database commands expose type and data names plus selection/page navigation.
The Plugin API does not expose database field values or field writes, so never
claim that UDB, CDB, or SDB contents were edited.

Event-command commands can list and select individual commands. The Plugin API
does not expose safe mutation of one command. Continue to perform writes by
replacing the complete Event Code through the protected prepare/commit flow.

Map Editor support exposes status, focus, and documented toolbar clicks. It
does not expose tile coordinates or direct map drawing.

## Prepare a replacement

Treat Event Code as UTF-8 text without BOM. Preserve
`WoditorEvCOMMAND_START`, `WoditorEvCOMMAND_END`, command nesting, and every
unrelated raw command.

Before any write:

1. Use `export` to save target Event Code to a temporary or ignored path.
2. Create the replacement as a separate file.
3. Check the replacement bytes before validation:
   - the file is UTF-8 without a BOM;
   - the exact first line is `WoditorEvCOMMAND_START`;
   - the exact last non-empty line is `WoditorEvCOMMAND_END`.
4. Validate it with the matching `validate-code` command.
5. Read both original and replacement and explain the exact intended
   differences.
6. Run `prepare-replace INDEX`.
7. Report target identity, current hash, backup path, and proposed changes.
8. If `auto_commit_on_clear_task` is true and the current user task already
   clearly authorized this exact change, proceed to commit. Otherwise ask
   for explicit action-time confirmation and do not commit until answered.

## Commit and verify

Prepared operations expire after 10 minutes and do not survive a Wodistant
restart. After confirmation (or policy auto-commit), re-run
`prepare-replace` if the operation may be stale, then commit with its new
operation ID and exact original hash.

The bridge replaces a whole event: select all commands, Delete, paste the full
replacement through Unicode clipboard data, then read back and hash it. It is
not a cut operation and it restores the user's prior clipboard.

Large events and Woditor modal error dialogs can keep `commit-replace` running
longer than an ordinary shell timeout. Run large commits with a sufficiently
long timeout or as one hidden background client process whose stdout and
stderr are captured to unique temporary files. Continue to serialize all
bridge clients while that process is alive.

Treat a client or shell timeout as an unknown result, not as a failed write:

1. Do not start another bridge request or retry the commit while the original
   client process is still alive.
2. If Woditor shows an error dialog, record its exact text and dismiss only
   that dialog so the bridge can finish verification or rollback.
3. Wait for the original client process to exit and inspect its captured
   response when available.
4. Run `status`, then independently read the target and compare its hash with
   both the original and desired hashes.
5. Prepare and retry only after the previous process ended, the bridge
   recovered, and the target was read successfully. Do not request new
   confirmation when target and replacement are unchanged; request it again
   if either changed.

After a successful commit:

1. Independently read the same event again.
2. Require the resulting hash to match the desired replacement hash.
3. Recheck command alignment and the specifically changed commands.
4. If `auto_export_readable` is true and alignment is valid, immediately
   `export-readable` over the existing canonical tracked text, inspect its
   Git diff, and report the Event Code backup path. If
   `remind_update_save` is true, remind once that WOLF Update/Save is still
   manual for `.dat` persistence.
5. If `auto_export_readable` is false, ask the user to Update/Save, then
   `export-readable`, inspect the Git diff, and report the backup path.

The bridge changes the open editor state but does not press WOLF RPG Editor's
Update/Save controls.

## Handle failures

- `source_changed` or `map_changed`: stop and inspect the newly selected or
  edited target; never force the stale operation.
- `operation_not_found`: prepare again, then request confirmation again if the
  proposed content or target changed.
- `verification_failed_rolled_back`: report that rollback succeeded and keep
  the backup path.
- `verification_and_rollback_failed`: stop all writes, tell the user not to
  save or close the editor, read the current state only, and surface the exact
  backup path for recovery.
- Woditor says the first line must begin with `WoditorEvCOMMAND_START`: do not
  assume the replacement file is malformed. Inspect its first bytes, BOM, and
  boundary lines. If they are correct, classify this as a clipboard delivery
  failure, let the current commit finish or rollback, and follow the
  unknown-result procedure above.
- Empty or unavailable Event Code: do not delete anything and do not bypass
  validation.

• SKILL.md 13 KB
• agents/openai.yaml 1 KB
• references/commands.md 8 KB
• scripts/wodistant_bridge.py 18 KB