maxforge-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maxforge MCP

Control a live Max patch through

maxforge-mcp

and the native

maxforge.sync

external. Treat the DSL as complete desired state and preserve revision safety.

通过

maxforge-mcp

和原生

maxforge.sync

外部控件控制实时Max补丁。将DSL视为完整的目标状态，并确保版本修订安全。

Mandatory version preflight

强制版本预检

On the first maxforge-related task in an Agent session, refresh the tracked skills before checking runtime versions:

bash

node <skill-directory>/scripts/refresh-skills.mjs --json
node <skill-directory>/scripts/check-version.mjs --json

If refresh reports

reloadRequired: true

, read the newly installed skill and this preflight again before continuing. The Skills CLI has no check-only mode, so changed tracked skills are updated. A failed upstream check remains

unknown

; never cache or report it as current. Do not repeat the preflight in the same session unless the user asks, configuration/package state changes, or an update is being prepared. Successful skill checks and remote GitHub/npm data are cached for 24 hours, while local configuration and package metadata are read on every run. Do not run it for an unrelated Max/MSP question.

```
update-available
```
: report the exact coherent version once. A check does not authorize replacement. Do not silently replace a working exact set; continue unless the user requested an update or the task requires the newer release.
```
blocked
```
: published-version or release-asset incoherence blocks upgrading.
```
LOCAL_VERSION_MISMATCH
```
or
```
MCP_MOVING_VERSION
```
blocks live mutation.
```
unknown
```
or
```
stale
```
: continue offline diagnosis without claiming a latest version.

After the stdio server is available,

maxforge_status

and

maxforge_list_patches

remain authoritative for the running broker and loaded external. A local file scan cannot establish what Max actually loaded.

When the user requests an update, read and follow

references/update-workflow.md

. The required order is refreshed skill instructions, one coherent release target, MCP pin, detached broker, complete Max package, conditional restart prompts, then live version verification. Never omit the broker merely because the config changed.

在Agent会话中的首个maxforge相关任务中，先刷新已跟踪的技能，再检查运行时版本：

bash

node <skill-directory>/scripts/refresh-skills.mjs --json
node <skill-directory>/scripts/check-version.mjs --json

如果刷新报告

reloadRequired: true

，请在继续前重新阅读新安装的技能和本预检说明。技能CLI没有仅检查模式，因此已更改的跟踪技能会被更新。上游检查失败会保持

unknown

状态；请勿将其缓存或报告为当前版本。除非用户要求、配置/包状态变更或正在准备更新，否则同一会话中请勿重复执行预检。成功的技能检查和远程GitHub/npm数据会缓存24小时，而本地配置和包元数据会在每次运行时读取。请勿针对无关的Max/MSP问题执行此操作。

```
update-available
```
：仅报告一次确切的一致性版本。检查并不授权替换操作。请勿静默替换正常运行的精确版本集；除非用户请求更新或任务需要新版本，否则继续使用当前版本。
```
blocked
```
：发布版本或发布资产不一致会阻止升级。
```
LOCAL_VERSION_MISMATCH
```
或
```
MCP_MOVING_VERSION
```
会阻止实时变更。
```
unknown
```
或
```
stale
```
：继续离线诊断，请勿声称使用最新版本。

当stdio服务器可用后，

maxforge_status

和

maxforge_list_patches

仍是运行中代理和已加载外部控件的权威信息来源。本地文件扫描无法确定Max实际加载了哪些内容。

当用户请求更新时，请阅读并遵循

references/update-workflow.md

。所需顺序为：刷新技能说明、选择一个一致性发布版本、固定MCP版本、分离代理、完成Max包安装、条件性重启提示，然后进行实时版本验证。请勿仅因配置变更而省略代理步骤。

Tool availability and setup

工具可用性与设置

For Codex, a typical stdio entry is:

toml

[mcp_servers.maxforge]
command = "npx"
args = ["-y", "--package=maxforge@X.Y.Z", "maxforge-mcp"]

This starts only the Node.js side. Max must separately load the matching native

maxforge.sync

external in a controller patch. Replace

X.Y.Z

with one intended release; never copy a version number from this skill. Do not keep live MCP configuration on npm's moving

latest

dist-tag. The skill may align a mismatched native package from the exact versioned GitHub Release, or perform an explicitly requested coherent-set update. Merely discovering a newer release does not authorize configuration or package mutation. The automated exact-asset alignment contract starts with

v0.5.0

. Releases through

v0.4.4

use the legacy unversioned Max-package asset and cannot be repaired by this installer. Do not fall back silently: upgrade the npm runtime, broker, and native package together to one release with versioned assets, or report that legacy installation remains a manual migration.

The detached broker can outlive the frontend that started it. During an update, inspect and restart it with the package version being installed:

bash

npx -y --package=maxforge@X.Y.Z maxforge broker status \
  --config /absolute/path/maxforge.config.json
npx -y --package=maxforge@X.Y.Z maxforge broker restart \
  --config /absolute/path/maxforge.config.json

Replace

X.Y.Z

with the intended installed version; it is not a literal package specifier to copy unchanged.

restart

refuses connected MCP/Max clients and pending native operations. Close clients for a non-disruptive update. Use

--force

only after the human accepts disconnection; it still cannot interrupt a pending operation. After replacement, reconnect this MCP server entry to negotiate the full tool inventory. Do not restart the outer Agent host merely to replace the broker.

Require

maxforge_help

and

maxforge_status

for diagnosis. A normal mutation session must expose all of these tools:

```
maxforge_help
```
```
maxforge_status
```
```
maxforge_catalog
```
```
maxforge_reload_catalog
```
```
maxforge_list_patches
```
```
maxforge_create_patch
```
```
maxforge_open_patch
```
```
maxforge_save_patch
```
```
maxforge_close_patch
```
```
maxforge_inspect_patch
```
```
maxforge_inspect_pending_apply
```
```
maxforge_recover_pending_apply
```
```
maxforge_get_live_edit_history
```
```
maxforge_get_patch_history_identity
```
```
maxforge_resolve_patch_history_identity
```
```
maxforge_erase_project_history
```
```
maxforge_review_live_changes
```
```
maxforge_adopt_live_changes
```
```
maxforge_prepare_change
```
```
maxforge_apply_prepared_change
```
```
maxforge_get_working_source
```

If only

maxforge_help

and

maxforge_status

are available, inspect status before giving setup advice.

VERSION_MISMATCH

and

RECONNECT_REQUIRED

are intentional diagnostic-only states, not evidence that the command is missing. If status is unavailable, stop and verify the stdio entry above. If the full inventory is available but no patch is registered, Max must load a controller patch containing

maxforge.sync

. Do not imitate this workflow with screenshots, accessibility automation, Max JavaScript,

node.script

, or invented

thispatcher

messages.

对于Codex，典型的stdio配置项如下：

toml

[mcp_servers.maxforge]
command = "npx"
args = ["-y", "--package=maxforge@X.Y.Z", "maxforge-mcp"]

这仅启动Node.js端。Max必须在控制器补丁中单独加载匹配的原生

maxforge.sync

外部控件。将

X.Y.Z

替换为目标版本；请勿直接复制本技能中的版本号。请勿将实时MCP配置依赖于npm的

latest

浮动标签。本技能可从确切版本的GitHub Release中对齐不匹配的原生包，或执行明确请求的一致性版本集更新。仅发现新版本并不授权变更配置或包。自动精确资产对齐协议从

v0.5.0

开始。

v0.4.4

及之前的版本使用未版本化的Max包资产，无法通过本安装程序修复。请勿静默回退：将npm运行时、代理和原生包一起升级到带有版本化资产的版本，或告知用户旧版安装仍需手动迁移。

分离的代理可以比启动它的前端存活更久。更新期间，请使用要安装的包版本检查并重启代理：

bash

npx -y --package=maxforge@X.Y.Z maxforge broker status \
  --config /absolute/path/maxforge.config.json
npx -y --package=maxforge@X.Y.Z maxforge broker restart \
  --config /absolute/path/maxforge.config.json

将

X.Y.Z

替换为目标安装版本；这不是可直接复制的字面包说明符。

restart

会拒绝已连接的MCP/Max客户端和待处理的原生操作。为了无中断更新，请关闭客户端。仅在用户接受断开连接后使用

--force

；它仍无法中断待处理操作。替换完成后，重新连接此MCP服务器条目以协商完整工具清单。请勿仅为替换代理而重启外部Agent主机。

诊断时需使用

maxforge_help

和

maxforge_status

。正常变更会话必须暴露以下所有工具：

```
maxforge_help
```
```
maxforge_status
```
```
maxforge_catalog
```
```
maxforge_reload_catalog
```
```
maxforge_list_patches
```
```
maxforge_create_patch
```
```
maxforge_open_patch
```
```
maxforge_save_patch
```
```
maxforge_close_patch
```
```
maxforge_inspect_patch
```
```
maxforge_inspect_pending_apply
```
```
maxforge_recover_pending_apply
```
```
maxforge_get_live_edit_history
```
```
maxforge_get_patch_history_identity
```
```
maxforge_resolve_patch_history_identity
```
```
maxforge_erase_project_history
```
```
maxforge_review_live_changes
```
```
maxforge_adopt_live_changes
```
```
maxforge_prepare_change
```
```
maxforge_apply_prepared_change
```
```
maxforge_get_working_source
```

如果仅

maxforge_help

和

maxforge_status

可用，请先检查状态再提供设置建议。

VERSION_MISMATCH

和

RECONNECT_REQUIRED

是故意设置的仅诊断状态，并非命令缺失的证据。如果状态不可用，请停止操作并验证上述stdio条目。如果完整工具清单可用但未注册任何补丁，则Max必须加载包含

maxforge.sync

的控制器补丁。请勿使用截图、无障碍自动化、Max JavaScript、

node.script

或自定义

thispatcher

消息模仿此工作流。

Live mutation workflow

实时变更工作流

Confirm the compact tool trio
```
maxforge_prepare_change
```
,
```
maxforge_apply_prepared_change
```
, and
```
maxforge_get_working_source
```
exists. Call
```
maxforge_help
```
only when this contract is unavailable or unfamiliar; a skill-guided normal edit does not need a redundant help round trip.
Call
```
maxforge_status
```
when registration or process state is uncertain.
Before using a custom external or abstraction, call
```
maxforge_catalog
```
and require its configured definition. If it is absent, stop and tell the user to set
```
MAXFORGE_CONFIG
```
. If configured files changed after startup, call
```
maxforge_reload_catalog
```
and verify the new digest. A rejected reload leaves the old catalog active. Do not substitute
```
--allow-unknown
```
in a live mutation. Confirm
```
catalog.project.id
```
when edit history must survive broker restart; without it, persistent edit evidence is deliberately disabled.
Call
```
maxforge_list_patches
```
. Copy
```
patcherId
```
and
```
scope
```
exactly; titles and filenames are display metadata, not target identities. Before any mutation, require the target's
```
versionCompatible
```
to be
```
true
```
. Its
```
externalVersion
```
is embedded in the binary Max actually loaded and must exactly match
```
maxforge_status.bridge.expectedExternalVersion
```
. If it does not, stop mutation and follow
```
references/native-version-alignment.md
```
. Align the complete Max package from the exact
```
vX.Y.Z
```
release, back up the replaced package outside Max search paths, remove confirmed stale copies, restart Max, reopen the patch, and list it again. A patch
```
filepath
```
and a nearby external do not prove which binary Max resolved. Never fall back to a moving latest release or overwrite multiple candidate copies by guesswork.
If a separate window is required, call
```
maxforge_create_patch
```
with a unique
```
patcherId
```
, scope, and title. To manage an existing
```
.maxpat
```
, use
```
maxforge_open_patch
```
with an absolute path on the Max host. Opening injects one bridge object and refuses files that already contain
```
maxforge.sync
```
. Both operations require exactly one controller.
Call
```
maxforge_inspect_patch
```
for the selected target with summary detail. Read its revision, structure token, counts, and changes. Request full detail only when complete surrounding topology is needed; never infer state from the screen.
If the order of recent edits could change the interpretation, call
```
maxforge_get_live_edit_history
```
. Check
```
supported
```
,
```
droppedEvents
```
, and
```
comparisonBasis
```
; treat
```
latestSequence
```
only as an
```
afterSequence
```
polling cursor. Inspect
```
persistence
```
,
```
sessionId
```
,
```
instanceId
```
, and
```
sessionSequence
```
. The 75 ms observations are structural evidence, not undo actions, gestures, selection, causality, or proof of human intent. History is bounded; project-scoped NDJSON may survive bridge restart, while reconnect starts a new session baseline.
```
observedAt
```
is snapshot-arrival time. Treat
```
patchMetadata.filepath
```
as a locator only, never as target identity. If path warnings are ambiguous, call
```
maxforge_get_patch_history_identity
```
for each candidate. Do not resolve them from path similarity. Only after the human confirms the relationship and the source patch is closed may you call
```
maxforge_resolve_patch_history_identity
```
:
```
rekey
```
requires an unused target,
```
merge
```
requires a known target, and
```
forget
```
only hides Agent-facing history. These operations neither rewrite live
```
maxforge.sync
```
routing nor physically erase append-only evidence. If the human explicitly requests physical history deletion, close every Max client, verify
```
maxforge_status.bridge.connectedClients
```
is zero, and call
```
maxforge_erase_project_history
```
with the exact project ID and confirmation phrase. Never present it as secure overwrite: it excludes Max/DSL/config files and desired-state cache, and SSD/filesystem remnants are not guaranteed. Persistent history allows one project broker writer per directory. Multiple
```
maxforge-mcp
```
stdio frontends attach to that broker. If startup reports
```
writer-v1.lock
```
, do not bypass it: dead valid leases recover automatically, while a live or malformed lease requires diagnosis rather than deletion.
Preserve complete desired-state semantics while minimizing source transfer:
- For a new target or broad rewrite, send complete
```
desiredDsl
```
  once to
```
maxforge_prepare_change
```
  .
- For a local edit, retain the latest
```
sourceRef
```
  . Call
```
maxforge_get_working_source
```
  with default
```
metadata
```
  , or
```
detail: "matches"
```
  plus semantic names/text to fetch only bounded snippets. Use
```
detail: "full"
```
  only for a broad rewrite or recovery.
- Submit local edits as
```
baseSourceRef
```
  plus
```
edits
```
  . Ranges are 1-based, half-open
```
[startLine, endLine)
```
  , and
```
startLine == endLine
```
  inserts. Every range refers to the original retained source and ranges must not overlap. The broker reconstructs and compiles the complete next DSL; this is a compact transport, not imperative patch syntax. A stale ref fails closed. Omitted managed objects and cords are deletions. Use real Max object names; signal subpatch ports are
```
inlet signal
```
  and
```
outlet signal
```
  , never invented
```
inlet~
```
  /
```
outlet~
```
  names. Give every object a contextual semantic DSL name, which becomes its managed varname suffix. When the user did not provide a name, inspect the surrounding patch context before naming it: use topology, object text, comments, and established vocabulary. Never use
```
obj1
```
  ,
```
thing
```
  ,
```
new_object
```
  , or
```
temp
```
  merely because the user omitted a name.
If inspection reports live changes, call
```
maxforge_review_live_changes
```
. The default summary deliberately omits the full snapshot, raw change rows, duplicate signal rows, and proposed full DSL. Request
```
detail: "full"
```
only when exact before/after values are needed. Treat edit clusters and risks as evidence, not certainty about intent; ask only when competing interpretations imply different actions.
Choose one drift path. Adopt an accepted current managed graph with
```
maxforge_adopt_live_changes
```
and the exact reviewed structure token, then retain its returned
```
sourceRef
```
. If a concrete next desired state already exists, prepare it with
```
manualChanges: "merge"
```
and require
```
canApply: true
```
. Do not claim unmanaged additions or force conflicts.
Call
```
maxforge_prepare_change
```
in exactly one source mode: complete
```
desiredDsl
```
, or
```
baseSourceRef
```
plus
```
edits
```
. Pass the latest
```
expectedStructureToken
```
when available; omission performs a fresh inspect. If a previous result says
```
workingDslRequiredAsCurrent
```
, pass its exact
```
sourceRef
```
as
```
currentSourceRef
```
for inline DSL, or use it as
```
baseSourceRef
```
for line edits. Review operation counts, every destructive operation, replacements, warnings, and conflicts. A receipt exists only when
```
canApply
```
is true. The full create/connect/rollback plan stays in the broker instead of entering agent context.
State the target, operation count, destructive operations, and stop condition before mutation.
Call
```
maxforge_apply_prepared_change
```
with only
```
receiptId
```
. A receipt is bound to catalog digest, target revisions, and inspected native structure; it is one-time, process-local, bounded, and consumed before native mutation. Never retry it after timeout, rejection, or warning. Inspect current state and prepare a new receipt instead. Concurrent human edits fail at the native structure-token check before mutation.
Count success only when
```
acknowledgement.revision
```
equals
```
targetRevision
```
.
```
baselineCaptured: false
```
is a warning after a successful apply, not an apply failure.
When
```
verification
```
is present, require its revision to equal
```
targetRevision
```
and check its box/cord counts. Inspect again when verification is absent, baseline capture failed, or complete post-apply topology is needed. If the workflow is slow, compare the returned
```
timings
```
stages rather than guessing which component is responsible.
After every apply or adoption, retain
```
sourceRef
```
and
```
sourceCharacters
```
, not full source text. Ordinary no-merge apply preserves authored
```
for
```
/
```
if
```
source in broker state. Adoption and merge may retain explicit graph-derived DSL because direct Max edits cannot be mapped safely back into macros. Fetch only the regions needed for the next edit. Prepared receipts do not survive broker restart; retained working source does when state persistence succeeds.
Apply does not persist the Max document. Call
```
maxforge_save_patch
```
only when persistence is intended. Omit
```
path
```
only for an already-saved patch; save-as requires an absolute Max-host path and explicit
```
overwrite: true
```
to replace a file.
Use
```
maxforge_close_patch
```
only when closure is intended. Dirty state is rejected unless
```
discard: true
```
is explicit; save first otherwise.

确认
```
maxforge_prepare_change
```
、
```
maxforge_apply_prepared_change
```
和
```
maxforge_get_working_source
```
这三个核心工具存在。仅当此协议不可用或不熟悉时才调用
```
maxforge_help
```
；技能引导的正常编辑无需冗余的帮助往返。
当注册或进程状态不确定时，调用
```
maxforge_status
```
。
在使用自定义外部控件或抽象前，调用
```
maxforge_catalog
```
并确认其已配置定义。如果缺失，请告知用户设置
```
MAXFORGE_CONFIG
```
。如果启动后配置文件发生变更，请调用
```
maxforge_reload_catalog
```
并验证新的摘要。如果重载被拒绝，则旧目录仍保持激活状态。实时变更中请勿使用
```
--allow-unknown
```
。当编辑历史需要在代理重启后保留时，请确认
```
catalog.project.id
```
；若无此ID，持久化编辑证据会被故意禁用。
调用
```
maxforge_list_patches
```
。精确复制
```
patcherId
```
和
```
scope
```
；标题和文件名仅为显示元数据，并非目标标识。在任何变更前，要求目标的
```
versionCompatible
```
为
```
true
```
。其
```
externalVersion
```
嵌入在Max实际加载的二进制文件中，必须与
```
maxforge_status.bridge.expectedExternalVersion
```
完全匹配。如果不匹配，请停止变更并遵循
```
references/native-version-alignment.md
```
。从确切的
```
vX.Y.Z
```
版本中对齐完整的Max包，将替换的包备份到Max搜索路径之外，移除已确认的过期副本，重启Max，重新打开补丁，然后再次列出补丁。补丁的
```
filepath
```
和附近的外部控件无法证明Max加载了哪个二进制文件。请勿盲目依赖浮动的最新版本，也不要猜测覆盖多个候选副本。
如果需要单独窗口，请使用唯一的
```
patcherId
```
、作用域和标题调用
```
maxforge_create_patch
```
。要管理现有的
```
.maxpat
```
文件，请使用Max主机上的绝对路径调用
```
maxforge_open_patch
```
。打开操作会注入一个桥接对象，并拒绝已包含
```
maxforge.sync
```
的文件。这两个操作都需要恰好一个控制器。
调用
```
maxforge_inspect_patch
```
获取所选目标的摘要信息。读取其修订版本、结构令牌、计数和变更。仅当需要完整的周边拓扑时才请求详细信息；请勿从屏幕推断状态。
如果近期编辑的顺序可能影响解读，请调用
```
maxforge_get_live_edit_history
```
。检查
```
supported
```
、
```
droppedEvents
```
和
```
comparisonBasis
```
；仅将
```
latestSequence
```
视为
```
afterSequence
```
轮询游标。检查
```
persistence
```
、
```
sessionId
```
、
```
instanceId
```
和
```
sessionSequence
```
。75毫秒的观测是结构证据，并非撤销操作、手势、选择、因果关系或人工意图的证明。历史记录是有限的；项目范围的NDJSON可能在桥接重启后保留，而重新连接会启动新的会话基线。
```
observedAt
```
是快照到达时间。仅将
```
patchMetadata.filepath
```
视为定位符，而非目标标识。如果路径警告不明确，请为每个候选对象调用
```
maxforge_get_patch_history_identity
```
。请勿通过路径相似性解析它们。仅在用户确认关系且源补丁已关闭后，才可调用
```
maxforge_resolve_patch_history_identity
```
：
```
rekey
```
需要未使用的目标，
```
merge
```
需要已知目标，
```
forget
```
仅隐藏Agent可见的历史记录。这些操作既不会重写实时
```
maxforge.sync
```
路由，也不会物理擦除仅追加的证据。如果用户明确请求物理删除历史记录，请关闭所有Max客户端，确认
```
maxforge_status.bridge.connectedClients
```
为零，然后使用确切的项目ID和确认短语调用
```
maxforge_erase_project_history
```
。请勿将其表述为安全覆盖：它不包含Max/DSL/配置文件和目标状态缓存，且无法保证SSD/文件系统中无残留。持久化历史记录允许每个目录有一个项目代理写入器。多个
```
maxforge-mcp
```
stdio前端可连接到该代理。如果启动时报告
```
writer-v1.lock
```
，请勿绕过它：失效的有效租约会自动恢复，而活跃或格式错误的租约需要诊断而非删除。
在最小化源传输的同时保留完整的目标状态语义：
- 对于新目标或大范围重写，向
```
maxforge_prepare_change
```
  发送一次完整的
```
desiredDsl
```
  。
- 对于本地编辑，保留最新的
```
sourceRef
```
  。使用默认的
```
metadata
```
  调用
```
maxforge_get_working_source
```
  ，或使用
```
detail: "matches"
```
  加上语义名称/文本仅获取有限片段。仅在大范围重写或恢复时使用
```
detail: "full"
```
  。
- 将本地编辑提交为
```
baseSourceRef
```
  加
```
edits
```
  。范围是1-based、半开区间
```
[startLine, endLine)
```
  ，
```
startLine == endLine
```
  表示插入。每个范围都引用原始保留的源，且范围不得重叠。代理会重建并编译完整的下一个DSL；这是一种紧凑传输方式，而非命令式补丁语法。过期的引用会失败关闭。省略的托管对象和连线会被视为删除。使用真实的Max对象名称；信号子补丁端口为
```
inlet signal
```
  和
```
outlet signal
```
  ，请勿使用自定义的
```
inlet~
```
  /
```
outlet~
```
  名称。为每个对象赋予上下文相关的语义DSL名称，该名称会成为其托管变量名的后缀。如果用户未提供名称，请先检查补丁的上下文再命名：使用拓扑结构、对象文本、注释和已建立的词汇表。请勿仅因用户未提供名称而使用
```
obj1
```
  、
```
thing
```
  、
```
new_object
```
  或
```
temp
```
  。
如果检查报告存在实时变更，请调用
```
maxforge_review_live_changes
```
。默认摘要会故意省略完整快照、原始变更行、重复信号行和建议的完整DSL。仅当需要确切的前后值时才请求
```
detail: "full"
```
。将编辑集群和风险视为证据，而非对意图的确定；仅当不同解读意味着不同操作时才询问用户。
选择一个漂移处理路径。使用
```
maxforge_adopt_live_changes
```
和确切的已审查结构令牌适配已接受的当前托管图，然后保留返回的
```
sourceRef
```
。如果已有具体的下一个目标状态，请使用
```
manualChanges: "merge"
```
进行准备，并要求
```
canApply: true
```
。请勿声称未托管的新增内容或强制解决冲突。
以恰好一种源模式调用
```
maxforge_prepare_change
```
：完整的
```
desiredDsl
```
，或
```
baseSourceRef
```
加
```
edits
```
。如果有最新的
```
expectedStructureToken
```
，请传递该值；省略则会执行新的检查。如果之前的结果显示
```
workingDslRequiredAsCurrent
```
，请将其确切的
```
sourceRef
```
作为
```
currentSourceRef
```
传递给内联DSL，或作为
```
baseSourceRef
```
用于源编辑。检查操作计数、每个破坏性操作、替换、警告和冲突。仅当
```
canApply
```
为true时才会生成回执。完整的创建/连接/回滚计划保留在代理中，不会进入Agent上下文。
在变更前说明目标、操作计数、破坏性操作和停止条件。
仅使用
```
receiptId
```
调用
```
maxforge_apply_prepared_change
```
。回执绑定到目录摘要、目标修订版本和已检查的原生结构；它是一次性的、进程本地的、有界的，会在原生变更前被消耗。超时、拒绝或警告后请勿重试。请检查当前状态并准备新的回执。并发的人工编辑会在变更前的原生结构令牌检查中失败。
仅当
```
acknowledgement.revision
```
等于
```
targetRevision
```
时才视为成功。
```
baselineCaptured: false
```
是应用成功后的警告，而非应用失败。
如果存在
```
verification
```
，要求其修订版本等于
```
targetRevision
```
并检查其框/连线计数。当验证缺失、基线捕获失败或需要完整的应用后拓扑时，请再次检查。如果工作流缓慢，请比较返回的
```
timings
```
阶段，而非猜测哪个组件出了问题。
每次应用或适配后，保留
```
sourceRef
```
和
```
sourceCharacters
```
，而非完整的源文本。普通无合并应用会在代理状态中保留已编写的
```
for
```
/
```
if
```
源。适配和合并可能保留显式的图派生DSL，因为直接的Max编辑无法安全映射回宏。仅获取下一次编辑所需的区域。准备好的回执不会在代理重启后存活；当状态持久化成功时，保留的工作源会存活。
应用操作不会持久化Max文档。仅当需要持久化时才调用
```
maxforge_save_patch
```
。仅对已保存的补丁可省略
```
path
```
；另存为需要Max主机上的绝对路径和显式的
```
overwrite: true
```
才能替换文件。
仅当需要关闭时才调用
```
maxforge_close_patch
```
。除非显式设置
```
discard: true
```
，否则会拒绝脏状态；否则请先保存。

Desired DSL rule

目标DSL规则

Use DSL as full scope ownership, not command syntax:

For direct consecutive port mapping, use inclusive equal-length ranges such as
```
src[0..3] -> dst[2..5]
```
; do not mix a range with a scalar or chain ranges.

maxdsl

patch "Generated controls"

for i in 0..7 {
  button_${i} = button at(${40 + i * 90}, 80)
  value_${i} = number at(${40 + i * 90}, 130)
  button_${i} -> value_${i}
}

When changing this graph, retain every managed object and connection that should survive. Do not send only the new line.

DSL names are durable managed identities. For example,

filter_cutoff

in scope

synth

becomes managed varname

maxforge_synth_obj_filter_cutoff

; renaming it causes an identity replacement rather than a cosmetic label change. If a human creates or edits an object without assigning a managed varname, inspect its object text, comments, neighbors, routing, and the surrounding naming scheme before proposing a semantic name. Do not silently claim an unmanaged human-created box. Only incorporate it after the user's intent to manage it is established, then use the context-derived DSL name consistently in the complete desired state.

将DSL视为完整的范围所有权，而非命令语法：

对于直接连续的端口映射，使用等长的包含范围，例如
```
src[0..3] -> dst[2..5]
```
；请勿将范围与标量混合或链式使用范围。

maxdsl

patch "Generated controls"

for i in 0..7 {
  button_${i} = button at(${40 + i * 90}, 80)
  value_${i} = number at(${40 + i * 90}, 130)
  button_${i} -> value_${i}
}

修改此图时，保留所有应保留的托管对象和连接。请勿仅发送新行。

DSL名称是持久的托管标识。例如，作用域

synth

中的

filter_cutoff

会成为托管变量名

maxforge_synth_obj_filter_cutoff

；重命名会导致标识替换，而非 cosmetic 标签变更。如果人工创建或编辑了一个对象但未分配托管变量名，请先检查其对象文本、注释、邻居、路由和周围的命名方案，再提出语义名称。请勿静默获取未托管的人工创建框。仅在确定用户有托管意图后才将其纳入，然后在完整的目标状态中一致地使用上下文派生的DSL名称。

Recovery rules

恢复规则

Call

maxforge_help

with

topic: "recovery"

before responding to an ambiguous failure.

在响应模糊故障前，请调用

maxforge_help

并指定

topic: "recovery"

。

Broker restarted

代理已重启

Restarting one stdio frontend does not restart shared broker state. After an actual broker restart, call

maxforge_status

and verify the persistence path, restored revision, and pending scopes. Normal broker restarts restore state automatically. A missing default v2 state is migrated from the matching v1 file only when every graph has a lossless DSL representation; migration failure is a startup error, not permission to treat the patch as unmanaged. Explicit custom state paths are not searched for guessed legacy siblings. If persistence was disabled or its file is unavailable, provide the exact previous complete DSL as

currentDsl

once. Never guess it, reset the revision, or claim the scope is empty. A pending scope must reconnect so Maxforge can compare its recorded base and target revisions.

If a frontend initialized in diagnostic mode because of

VERSION_MISMATCH

, repeat

maxforge_status

after replacing the broker. Diagnostic status is live, not a cached startup snapshot.

RECONNECT_REQUIRED

means the new broker is compatible; reconnect only that MCP server entry to negotiate the full tool set. Do not restart the outer Agent host.

If Max reports a third revision, stop ordinary prepare/review calls. Call

maxforge_inspect_pending_apply

and preserve its base, target, intent, and live DSL evidence. If it returns

supersededApply

, preserve that original unresolved target/intent evidence as well; the active target is a durable recovery transition and ordinary tools must remain blocked. Call

maxforge_recover_pending_apply

with

rebase_live

only when trusted complete

currentDsl

compiles to the exact returned live revision, and pass the unchanged structure token. A stale token, guessed DSL, state-file deletion, or fabricated empty graph is not recovery.

重启一个stdio前端不会重启共享代理状态。实际代理重启后，请调用

maxforge_status

并验证持久化路径、恢复的修订版本和待处理作用域。正常代理重启会自动恢复状态。仅当每个图都有无损DSL表示时，缺失的默认v2状态才会从匹配的v1文件迁移；迁移失败是启动错误，而非将补丁视为未托管的许可。不会为猜测的旧版兄弟文件搜索显式的自定义状态路径。如果持久化已禁用或其文件不可用，请一次性提供确切的先前完整DSL作为

currentDsl

。请勿猜测、重置修订版本或声称作用域为空。待处理作用域必须重新连接，以便Maxforge可以比较其记录的基准和目标修订版本。

如果前端因

VERSION_MISMATCH

以诊断模式初始化，请在替换代理后重复调用

maxforge_status

。诊断状态是实时的，而非缓存的启动快照。

RECONNECT_REQUIRED

表示新代理兼容；仅重新连接该MCP服务器条目以协商完整工具集。请勿重启外部Agent主机。

如果Max报告了第三个修订版本，请停止普通的准备/检查调用。调用

maxforge_inspect_pending_apply

并保留其基准、目标、意图和实时DSL证据。如果返回

supersededApply

，请同时保留原始未解决的目标/意图证据；活跃目标是持久的恢复过渡，普通工具必须保持阻塞状态。仅当可信的完整

currentDsl

编译为确切返回的实时修订版本，并传递未更改的结构令牌时，才调用

maxforge_recover_pending_apply

并指定

rebase_live

。过期令牌、猜测的DSL、状态文件删除或虚构的空图都不属于恢复操作。

Managed manual edit detected

检测到托管人工编辑

Inspection alone does not accept or reset a baseline. First call

maxforge_review_live_changes

. Its summary describes structural evidence and must not be presented as a certain explanation of human intent. Request

detail: "full"

only when exact raw changes referenced by cluster

changeIndexes

are necessary; the default avoids loading the complete snapshot, duplicate signals, raw rows, and proposed DSL into agent context.

If the reviewed managed graph is the state that should survive, adopt it using the exact returned structure token. Adoption re-inspects, rejects stale review, reconstructs the managed graph, and advances native revision with zero structural operations because the edit is already live. Retain the returned

sourceRef

; do not recreate source from summaries. Managed patch-cord metadata is not represented by protocol v1 and therefore blocks adoption rather than being silently discarded.

If the agent already has a next desired state, call

maxforge_prepare_change

with

manualChanges: "merge"

. Preparation performs the three-way merge of the previous agent intent, current Max graph, and next desired graph while retaining the acknowledged graph for native revision safety. An added reserved managed identity can be recovered only when complete desired DSL explicitly defines the exact live box and all managed cords involving it. Expect a zero-operation revision acknowledgement when the structure is already live. Duplicate identity, field/layout/configuration mismatch, cord mismatch, unmanaged cord, and unrepresentable graph cases remain fail-closed conflicts. When

canApply

is true, apply only the returned receipt. Resolve same-field, change-vs-delete, new-managed-identity, and unmanaged-cord conflicts explicitly. Do not force a winner or fall back to ordinary apply.

After success, retain the returned

sourceRef

. This identifies the merged working source because the pre-merge DSL may no longer hash to Max's acknowledged revision. When

workingDslRequiredAsCurrent

is true, use

currentSourceRef

for inline preparation or

baseSourceRef

for source edits until a successful apply clears the flag.

Unmanaged standalone edits remain outside the managed graph. A cord touching a managed box is preserved only while that box is not deleted or structurally recreated; reconciliation reports the destructive case as a conflict. Reparenting a managed box into another patcher path is a delete/add operation, not a mergeable move. Resolve it explicitly in the complete DSL.

仅检查不会接受或重置基线。首先调用

maxforge_review_live_changes

。其摘要描述了结构证据，不得作为对人工意图的确定解释呈现。仅当需要集群

changeIndexes

引用的确切原始变更时才请求

detail: "full"

；默认设置会避免将完整快照、重复信号、原始行和建议DSL加载到Agent上下文。

如果已审查的托管图是应保留的状态，请使用确切返回的结构令牌适配它。适配会重新检查、拒绝过期的审查、重建托管图，并推进原生修订版本，且无需任何结构操作，因为编辑已处于实时状态。保留返回的

sourceRef

；请勿从摘要重新创建源。协议v1不表示托管补丁连线元数据，因此会阻止适配而非静默丢弃。

如果Agent已有下一个目标状态，请调用

maxforge_prepare_change

并设置

manualChanges: "merge"

。准备操作会对先前的Agent意图、当前Max图和下一个目标图进行三方合并，同时保留已确认的图以确保原生修订版本安全。仅当完整目标DSL明确定义了确切的实时框和所有涉及它的托管连线时，才能恢复添加的保留托管标识。当结构已处于实时状态时，预期会有零操作的修订确认。重复标识、字段/布局/配置不匹配、连线不匹配、未托管连线和不可表示的图情况仍会导致闭合失败冲突。当

canApply

为true时，仅应用返回的回执。明确解决同字段、变更与删除、新托管标识和未托管连线冲突。请勿强制选择胜者或回退到普通应用。

成功后，保留返回的

sourceRef

。这标识了合并后的工作源，因为合并前的DSL可能不再与Max的已确认修订版本哈希匹配。当

workingDslRequiredAsCurrent

为true时，在成功应用清除该标志前，使用

currentSourceRef

进行内联准备或

baseSourceRef

进行源编辑。

未托管的独立编辑仍处于托管图之外。仅当托管框未被删除或结构重建时，接触托管框的连线才会被保留；协调会将破坏性情况报告为冲突。将托管框重新父化到另一个补丁路径是删除/添加操作，而非可合并的移动。请在完整DSL中明确解决。

Timeout or transport error

超时或传输错误

Do not retry blindly. Protocol v1 is not transactional and an ambiguous failure may leave partial mutation. Call

maxforge_status

, then inspect the live target before deciding whether a newly prepared desired-state receipt is safe. The old receipt was consumed before native mutation and must not be retried.

请勿盲目重试。协议v1不支持事务，模糊故障可能导致部分变更。调用

maxforge_status

，然后检查实时目标，再决定新准备的目标状态回执是否安全。旧回执已在原生变更前被消耗，不得重试。

Baseline warning

基线警告

If apply returns

baselineCaptured: false

, the acknowledged mutation already succeeded. Do not repeat it merely to capture a baseline. Inspect explicitly; change comparison remains unavailable until a later successful baseline.

如果应用返回

baselineCaptured: false

，则已确认的变更已成功。请勿仅为捕获基线而重复操作。请明确检查；在后续成功捕获基线前，变更比较仍不可用。

No registered patch

无已注册补丁

Use

maxforge_status

to distinguish no WebSocket client from an unregistered client. Ask the user to open the controller patch or verify the native external; do not guess a target.

使用

maxforge_status

区分无WebSocket客户端和未注册客户端。请用户打开控制器补丁或验证原生外部控件；请勿猜测目标。

Report reproducible defects

报告可复现缺陷

When tool evidence shows a maxforge defect rather than stale input, missing catalog configuration, an expected fail-closed rejection, or a Max limitation, search existing issues first. If no duplicate exists and authenticated GitHub issue creation is available, open an issue at

bbb-max-externals/maxforge

. Include maxforge/broker/Node/OS/Max versions, MCP transport and client, exact tool sequence, minimal DSL and patch state, actual and expected behavior, and bounded responses/logs with tokens and private paths removed. Link the created issue in the response. Do not file ambiguous timeout speculation before status and live inspection establish the failure. If write access is unavailable, return a ready-to-file issue body and the repository issue URL instead of claiming it was created.

当工具证据显示maxforge缺陷而非过期输入、缺失目录配置、预期的闭合失败拒绝或Max限制时，请先搜索现有问题。如果没有重复问题且可创建已认证的GitHub问题，请在

bbb-max-externals/maxforge

创建问题。包含maxforge/代理/Node/OS/Max版本、MCP传输和客户端、确切的工具序列、最小化的DSL和补丁状态、实际与预期行为，以及已移除令牌和私有路径的有限响应/日志。在回复中链接创建的问题。在状态和实时检查确定故障前，请勿提交模糊的超时推测问题。如果无写入权限，请返回可直接提交的问题正文和仓库问题URL，而非声称已创建问题。

Safety boundaries

安全边界

Operate only on targets returned by
```
maxforge_list_patches
```
.
Mutate only targets with
```
versionCompatible: true
```
; status/list/inspection are diagnostic when the external version is unknown or mismatched.
Manage only exact
```
maxforge_<scope>_obj_...
```
scripting names.
Preview nontrivial changes before apply.
Review managed human edits before interpreting them. Adopt an accepted live baseline or prepare a concrete next state with merge enabled; both paths are opt-in.
Never remove or fabricate
```
baseStructureToken
```
; it prevents stale inspected state from being mutated after a concurrent human edit.
Keep the default unauthenticated WebSocket bridge on loopback. For trusted-LAN use, require matching
```
MAXFORGE_WS_TOKEN
```
and
```
maxforge.sync @token
```
; never treat the plaintext token mode as safe for direct Internet exposure.
Never treat a timeout, process exit, or missing acknowledgement as success.
```
maxforge_catalog
```
is compiler metadata, not a runtime probe. It does not prove the external binary or abstraction search path exists on the Max host.
Do not save, close, or discard a Max window unless the user asks. Never turn a save/close rejection into
```
overwrite: true
```
or
```
discard: true
```
implicitly.

仅对
```
maxforge_list_patches
```
返回的目标进行操作。
仅变更
```
versionCompatible: true
```
的目标；当外部版本未知或不匹配时，状态/列表/检查仅用于诊断。
仅管理确切的
```
maxforge_<scope>_obj_...
```
脚本名称。
应用前预览非 trivial 变更。
在解读前审查托管的人工编辑。适配已接受的实时基线或启用合并准备具体的下一个状态；两条路径均需用户选择。
请勿移除或伪造
```
baseStructureToken
```
；它可防止在并发人工编辑后使用过期的检查状态进行变更。
在环回接口上使用默认的未认证WebSocket桥接。对于可信LAN使用，要求匹配的
```
MAXFORGE_WS_TOKEN
```
和
```
maxforge.sync @token
```
；请勿将明文令牌模式视为可直接暴露于互联网的安全模式。
请勿将超时、进程退出或缺失确认视为成功。
```
maxforge_catalog
```
是编译器元数据，而非运行时探测。它无法证明Max主机上存在外部二进制文件或抽象搜索路径。
除非用户要求，否则请勿保存、关闭或丢弃Max窗口。请勿将保存/关闭拒绝隐式转换为
```
overwrite: true
```
或
```
discard: true
```
。