@myagentroam/server 0.13.4 → 0.13.7

package/web/docs/assets/deployment_network.md.BarghfLt.js

@@ -1 +0,0 @@
-import{_ as e,o as d,c as o,a3 as r}from"./chunks/framework.BHjrhdiC.js";const l=JSON.parse('{"title":"网络、TLS 与 WebSocket","description":"","frontmatter":{"title":"网络、TLS 与 WebSocket","lastUpdated":"2026-10-29T00:00:00.000Z"},"headers":[],"relativePath":"deployment/network.md","filePath":"deployment/network.md"}'),a={name:"deployment/network.md"};function n(S,t,c,s,i,T){return d(),o("div",null,[...t[0]||(t[0]=[r('<h1 id="网络、tls-与-websocket" tabindex="-1">网络、TLS 与 WebSocket <a class="header-anchor" href="#网络、tls-与-websocket" aria-label="Permalink to &quot;网络、TLS 与 WebSocket&quot;">​</a></h1><table tabindex="0"><thead><tr><th>链路</th><th>方向</th><th>要求</th></tr></thead><tbody><tr><td>浏览器 → Server</td><td>入站 HTTPS/WSS</td><td>域名、证书、Origin 一致</td></tr><tr><td>Node → Server</td><td>出站 HTTPS/WSS</td><td>不需要 Node 公网入站端口</td></tr><tr><td>浏览器 → Node</td><td>局域网 UDP</td><td>文件、Git 与终端直连，默认 <code>49152-49215</code></td></tr><tr><td>Server → MySQL</td><td>内网 TCP</td><td>MySQL 不对公网开放</td></tr></tbody></table><p>Server 同一 HTTP listener 提供 Web、帮助、API 和 WebSocket；外部基础设施终止 TLS。反向代理必须保留 WebSocket Upgrade，并对长连接设置合理超时；<code>MAR_PUBLIC_ORIGIN</code> 必须是浏览器看到的 HTTPS Origin。不要混用 HTTP 页面和 HTTPS API/WSS。</p><p>Node 不提供浏览器 HTTP API，也不应开放任何公网入站端口。普通 Workspace 的文件、Git 和终端可按能力与授权使用局域网直连；托管对话不使用该路径。启用时，Node 启动后从私有配置 <code>directTransfer.udpPortRangeBegin..udpPortRangeEnd</code> 指定的范围内取得一个 UDP 端口，并通过 ICE UDP Mux 复用该端口；默认范围为 <code>49152-49215</code>。防火墙只应允许实际 Browser 局域网来源访问对应范围，不得向公网放行。需要精确防火墙规则时可把起止值设为同一个固定端口；同主机多个 Node 应分别配置不同端口。端口不可达时可使用 Server 中继，不会因此导致 Node 离线；已经开始的传输仍可能失败，需要重试。</p><p><strong>成功标志：</strong> 登录后实时状态会更新，Node 在线，终端可以连接并在短暂断网后重连。</p><p>常见现象：502 先查代理上游和容器健康；登录/CSRF 拒绝先查 Origin；Node 反复离线先查其出站 DNS、证书与代理限制。下一步：<a href="./../troubleshooting/node-offline">Node 注册失败或离线</a>。</p>',6)])])}const _=e(a,[["render",n]]);export{l as __pageData,_ as default};

package/web/docs/assets/deployment_network.md.BarghfLt.lean.js

@@ -1 +0,0 @@
-import{_ as e,o as d,c as o,a3 as r}from"./chunks/framework.BHjrhdiC.js";const l=JSON.parse('{"title":"网络、TLS 与 WebSocket","description":"","frontmatter":{"title":"网络、TLS 与 WebSocket","lastUpdated":"2026-10-29T00:00:00.000Z"},"headers":[],"relativePath":"deployment/network.md","filePath":"deployment/network.md"}'),a={name:"deployment/network.md"};function n(S,t,c,s,i,T){return d(),o("div",null,[...t[0]||(t[0]=[r("",6)])])}const _=e(a,[["render",n]]);export{l as __pageData,_ as default};

package/web/docs/assets/deployment_upgrade.md.BESOToM5.js

@@ -1 +0,0 @@
-import{_ as r,o,c as a,a3 as d}from"./chunks/framework.BHjrhdiC.js";const u=JSON.parse('{"title":"升级 MyAgentRoam","description":"","frontmatter":{"title":"升级 MyAgentRoam","lastUpdated":"2026-11-05T00:00:00.000Z"},"headers":[],"relativePath":"deployment/upgrade.md","filePath":"deployment/upgrade.md"}'),i={name:"deployment/upgrade.md"};function t(l,e,n,p,s,c){return o(),a("div",null,[...e[0]||(e[0]=[d('<h1 id="升级-myagentroam" tabindex="-1">升级 MyAgentRoam <a class="header-anchor" href="#升级-myagentroam" aria-label="Permalink to &quot;升级 MyAgentRoam&quot;">​</a></h1><p>升级前先完成可恢复备份。Server/Web、EE、公共 Core、Node、Agent、Protocol 统一使用同一主版本，当前基线为 <code>0.10.1</code>。公共二进制包与 Computer Use Runtime 从 <code>0.10.1</code> 起步并保留独立修订；Code Navigation 不独立发布，marctl 随 Node 交付。</p><h2 id="步骤" tabindex="-1">步骤 <a class="header-anchor" href="#步骤" aria-label="Permalink to &quot;步骤&quot;">​</a></h2><p>统一产品沿用现有企业数据库结构、迁移账本、License 激活事实和私有数据目录。社区与企业使用同一安装，激活不触发数据库迁移；不提供已删除个人产品的数据迁移。</p><p>Server 与 Web 必须配套，Server 版本必须大于等于 Node；最低支持 Node <code>0.11.39</code>。先升级 Server/Web，再升级 Node，不能反向操作。切换后刷新已打开的浏览器页面，以加载匹配的 Web。wire v2 Node 不再支持连接或推送升级，必须先在主机上手工更新 Node。低于当前业务基线的已登记 wire v3 Node 不能继续处理工作区、会话等业务；支持推送升级时仍可连接，并由有权用户发起或取消升级。升级完成前不要依赖旧 Node 执行业务。升级会沿用 Node SQLite 和 Server MySQL 的既有迁移链；迁移前仍需备份，数据库不会自动降级。</p><h3 id="旧数据库格式" tabindex="-1">旧数据库格式 <a class="header-anchor" href="#旧数据库格式" aria-label="Permalink to &quot;旧数据库格式&quot;">​</a></h3><p>首次从一体化 Server 切换到拆分构建不属于普通自动升级。必须先停服、验证可恢复备份，并由运维按目标版本提供的操作手册在隔离恢复副本中完成预演。旧数据库需准备到一体化 v49，再校验表结构、迁移记录及引用完整性，执行经审核的转换 SQL，并核对数据和 License 激活事实。不要直接修改版本标记或清除 License 状态。</p><p>新 Server 拒绝旧格式 ledger 时会报告 <code>SERVER_DATABASE_LEDGER_UNSUPPORTED</code>；这不是连接配置错误，不能通过删除迁移表绕过。不得将企业数据库降级为仅 Core 的结构。切换后的受支持版本继续自动执行 Core/Enterprise 增量迁移；失败时保持停服，恢复匹配版本的备份。</p><h3 id="常规升级" tabindex="-1">常规升级 <a class="header-anchor" href="#常规升级" aria-label="Permalink to &quot;常规升级&quot;">​</a></h3><ol><li>备份 MySQL、每台 Node 的私有配置与 SQLite、必要工作区，以及各 Agent 官方要求备份的配置和历史目录。</li><li>选择维护窗口，确认没有关键运行中的 Agent 或终端。</li><li>更新 Server/Web 容器或发布产物，启动后确认数据库迁移与 <code>/health</code> 成功。</li><li>Server 使用运行账号的 npm 配置查询 <code>@myagentroam/node</code> 的已发布版本，选择不超过当前 Server 版本且达到当前业务基线的最高稳定版本作为 Node 升级目标。Server 同版本尚未发布时，只有符合这两个条件的较低版本才可使用；不直接推送浮动的 <code>latest</code>，也不升级到比 Server 更新的版本。Server 检测与 Supervisor 安装都会自动读取各自运行账号的 npm 配置，不另设 Registry 配置项。</li><li>已部署 Supervisor 的 Node 可在“管理 → 节点管理”打开节点详情并点击“推送升级”；系统不会自动升级，也不会降级。推送给 Supervisor 的始终是查询后确定的精确版本，而不是浮动的 <code>latest</code>。旧 Node 首次启用该能力时仍需手工更新 npm 包并按 <a href="./node-linux">Linux</a>、<a href="./node-windows">Windows</a>或<a href="./node-macos">macOS</a>文档把自启动入口改为 <code>mar-node supervise</code>。</li><li>确认弹窗会说明目标版本、Run 排空和 Terminal 断开影响。推送后 Node 等待活动 Run 完成，并在等待期间拒绝新 Run、队列派发和 Terminal；“等待 Run”阶段可在节点详情取消，进入“准备重启”后不可取消。</li><li>Supervisor 使用固定包名安装精确版本，在目标平台重建 <code>node-pty</code>，验证入口后切换 Node 子进程。安装失败时保留旧入口并上报失败；修复 npm 网络、Registry、磁盘、权限或安全软件问题后再重新推送。</li><li>确认本次升级完成且目标 Node 重新认证上线，再执行一次新会话、文件读取和终端的冒烟验证，并验证重启服务或主机后仍能自动上线。</li></ol><h2 id="节点管理中的升级状态" tabindex="-1">节点管理中的升级状态 <a class="header-anchor" href="#节点管理中的升级状态" aria-label="Permalink to &quot;节点管理中的升级状态&quot;">​</a></h2><ul><li>“可升级到 X.Y.Z”：Node 版本低于 npm 中不超过当前 Server 版本的最高稳定版本，且已声明 Supervisor 能力；实际推送还要求 Node 在线且未禁用。</li><li>“当前无需升级”：Node 已达到或高于当前可升级目标，无需操作且不会降级。</li><li>“版本未知或不受支持”：Node 上报的版本缺失、非法或不是稳定版本，先手工确认并修复 Node 安装。</li><li>“需手工启用 Supervisor”：按平台文档手工安装支持版本并把自启动入口改为 <code>supervise</code>。</li><li>“目标 npm 包暂不可用”：无法查询已发布版本、没有同时满足 Server 版本上限与业务基线的稳定包或 Server 版本非法；等待包发布/同步，或检查 Server 版本及其运行账号的 npm 配置和网络。</li><li>“等待 Run”：请求已受理，已有 Run 正在排空；交接前可取消，此时不能创建新 Run 或 Terminal。请求结果待确认不表示 Node 已受理，也不要盲目重复推送。</li><li>“升级中”：显示关闭旧节点、安装版本或等待上线。安装完成不代表上线；进度更新中断只表示结果待确认，不代表安装失败。等待上线时间较长时检查主机，不要并发重推。</li><li>“完成”：本次目标版本已经通过 Node 控制连接认证上线。之后离线不会改变本次成功记录。</li><li>“失败”：查看页面原因、Node/Supervisor 服务日志和 <code>dataDirectory</code> 下的升级结果。只有旧操作已结束且 Node 在线时才重新推送；否则先在主机上排查。切换入口前安装失败保留旧入口，切换后启动失败不会自动回滚。</li></ul><p>实时进度和退出超时兜底需要 Server、Node 及其实际运行的 Supervisor 均支持新能力。仅升级 Node 子进程不会更新正在运行的 Supervisor；首次启用时先升级 Server，再在维护窗口按平台文档更新 Supervisor 启动入口并重启服务。旧 Supervisor 管理的 Node 仍使用原有升级流程，不显示实时进度；已卡住的旧进程需单独处理。</p><p>如果页面没有“推送升级”按钮，先确认当前账号具有该 Node 的管理写权限、企业 License 未冻结、Node 在线且未禁用，并检查上述状态。远程升级只负责 Node npm 包和子进程，不会远程安装 Node.js、创建 systemd/计划任务、提升权限或修改 Server/Web。Server 和 Node 若使用不同运行账号，应分别保证两个账号的 npm 配置都能访问同一包版本。</p><p><strong>成功标志：</strong> 所有组件版本与能力正常，Node 重连后可打开既有 Workspace。</p><p>迁移失败应停止继续升级并从备份恢复，不要手工修改数据库结构。下一步：<a href="./backup-restore">备份与恢复</a>。</p>',16)])])}const S=r(i,[["render",t]]);export{u as __pageData,S as default};

package/web/docs/assets/deployment_upgrade.md.BESOToM5.lean.js

@@ -1 +0,0 @@
-import{_ as r,o,c as a,a3 as d}from"./chunks/framework.BHjrhdiC.js";const u=JSON.parse('{"title":"升级 MyAgentRoam","description":"","frontmatter":{"title":"升级 MyAgentRoam","lastUpdated":"2026-11-05T00:00:00.000Z"},"headers":[],"relativePath":"deployment/upgrade.md","filePath":"deployment/upgrade.md"}'),i={name:"deployment/upgrade.md"};function t(l,e,n,p,s,c){return o(),a("div",null,[...e[0]||(e[0]=[d("",16)])])}const S=r(i,[["render",t]]);export{u as __pageData,S as default};

package/web/docs/assets/en-US_deployment_network.md.DdOgOLns.js

@@ -1 +0,0 @@
-import{_ as t,o,c as r,a3 as a}from"./chunks/framework.BHjrhdiC.js";const f=JSON.parse('{"title":"Network, TLS, and WebSocket","description":"","frontmatter":{"title":"Network, TLS, and WebSocket","lastUpdated":"2026-10-29T00:00:00.000Z"},"headers":[],"relativePath":"en-US/deployment/network.md","filePath":"en-US/deployment/network.md"}'),n={name:"en-US/deployment/network.md"};function s(i,e,d,c,l,p){return o(),r("div",null,[...e[0]||(e[0]=[a('<h1 id="network-tls-and-websocket" tabindex="-1">Network, TLS, and WebSocket <a class="header-anchor" href="#network-tls-and-websocket" aria-label="Permalink to &quot;Network, TLS, and WebSocket&quot;">​</a></h1><p>Browsers and Nodes use the same HTTPS origin. <code>MAR_PUBLIC_ORIGIN</code> must exactly match its scheme, host, and port. Server serves Web, help, API, and WebSocket traffic on one HTTP listener. External infrastructure terminates TLS. The reverse proxy must present a trusted certificate, forward the complete site, and support WebSocket Upgrade for Workbench and terminal relays.</p><p>Nodes initiate outbound HTTPS/WSS connections and expose no browser HTTP API. Ordinary Workspace files, Git, and terminals can use an authorized LAN connection when their respective capabilities are available; hosted conversations do not use this path. When enabled, WebRTC ICE obtains one UDP port from <code>directTransfer.udpPortRangeBegin..udpPortRangeEnd</code>, which defaults to <code>49152-49215</code>, and ICE UDP Mux reuses that port. Permit the configured range only from the actual browser LAN and never expose it to the public Internet. Set both values to the same port for an exact firewall rule, and use different ports for multiple Nodes on one host. If the port is blocked, traffic can use the Server relay without taking the Node offline; a transfer already in progress can still fail and need a retry.</p><p>Allow long-lived Server connections and timeouts suitable for Agent runs. Disable caching for authenticated API responses and upgraded traffic.</p><p>When connections fail, test DNS, system time, certificate chains, proxy headers, and outbound firewall policy from both the browser network and Node host.</p>',5)])])}const u=t(n,[["render",s]]);export{f as __pageData,u as default};

package/web/docs/assets/en-US_deployment_network.md.DdOgOLns.lean.js

@@ -1 +0,0 @@
-import{_ as t,o,c as r,a3 as a}from"./chunks/framework.BHjrhdiC.js";const f=JSON.parse('{"title":"Network, TLS, and WebSocket","description":"","frontmatter":{"title":"Network, TLS, and WebSocket","lastUpdated":"2026-10-29T00:00:00.000Z"},"headers":[],"relativePath":"en-US/deployment/network.md","filePath":"en-US/deployment/network.md"}'),n={name:"en-US/deployment/network.md"};function s(i,e,d,c,l,p){return o(),r("div",null,[...e[0]||(e[0]=[a("",5)])])}const u=t(n,[["render",s]]);export{f as __pageData,u as default};

package/web/docs/assets/en-US_deployment_upgrade.md.DZiDDiLn.js

@@ -1 +0,0 @@
-import{_ as t,o as a,c as r,a3 as n}from"./chunks/framework.BHjrhdiC.js";const h=JSON.parse('{"title":"Upgrade MyAgentRoam","description":"","frontmatter":{"title":"Upgrade MyAgentRoam","lastUpdated":"2026-11-05T00:00:00.000Z"},"headers":[],"relativePath":"en-US/deployment/upgrade.md","filePath":"en-US/deployment/upgrade.md"}'),o={name:"en-US/deployment/upgrade.md"};function s(i,e,d,l,c,p){return a(),r("div",null,[...e[0]||(e[0]=[n('<h1 id="upgrade-myagentroam" tabindex="-1">Upgrade MyAgentRoam <a class="header-anchor" href="#upgrade-myagentroam" aria-label="Permalink to &quot;Upgrade MyAgentRoam&quot;">​</a></h1><p>Server, Web, EE, shared cores, Node, Agent, and Protocol share one version, starting at <code>0.10.1</code>. The shared binaries package and Computer Use Runtime start at <code>0.10.1</code> and retain independent patch releases. Code Navigation is internal, and marctl ships with Node.</p><p>The unified product preserves the existing enterprise schema, migration history, License activation, and private data directory. Community and Enterprise use the same installation; activation does not migrate the database. No migration from the retired personal product is provided.</p><p>Deploy matching Server and Web versions, with the Server version at least as new as Node. The minimum supported Node version is <code>0.11.39</code>. Upgrade Server/Web before Node, never the reverse. After switching versions, refresh open browser pages to load the matching Web. Nodes using wire v2 can no longer connect or receive pushed upgrades; update them manually on their hosts first. A registered wire v3 Node below the current business baseline cannot continue Workspace, session, or other business operations. If it supports push upgrades, it can still connect so an authorized user can request or cancel an upgrade. Do not rely on it for business operations until the upgrade completes. Node SQLite and Server MySQL retain their existing migration chains; back up before migration, since databases are not automatically downgraded.</p><h2 id="legacy-database-formats" tabindex="-1">Legacy database formats <a class="header-anchor" href="#legacy-database-formats" aria-label="Permalink to &quot;Legacy database formats&quot;">​</a></h2><p>The first transition from the combined Server is not a routine automatic upgrade. Stop all writers, verify that backups can be restored, and rehearse the target version&#39;s operations procedure on an isolated restored copy. Prepare the old database to combined schema v49, validate its tables, migration history and references, apply reviewed conversion SQL, then verify data and License activation history. Never replace version markers or clear License state to bypass checks.</p><p><code>SERVER_DATABASE_LEDGER_UNSUPPORTED</code> means the new Server does not accept the old ledger format; deleting the migration table is not a remedy. Do not downgrade an enterprise database to a Core-only schema. Supported upgrades after this transition apply incremental Core/Enterprise migrations automatically. On failure, keep services stopped and restore a backup with its matching application version.</p><h2 id="routine-upgrades" tabindex="-1">Routine upgrades <a class="header-anchor" href="#routine-upgrades" aria-label="Permalink to &quot;Routine upgrades&quot;">​</a></h2><ol><li>Back up MySQL, every Node&#39;s private configuration and SQLite data, required Workspaces, and Agent-specific configuration/history.</li><li>Choose a maintenance window without critical runs or terminals.</li><li>Upgrade Server and Web first; confirm migrations and <code>/health</code>.</li><li>Server queries the published <code>@myagentroam/node</code> versions using its service account&#39;s npm configuration and selects the highest stable version that does not exceed the current Server version and meets the current business baseline. If the exact Server version is unpublished, a lower published version is eligible only if it meets both conditions. It never upgrades beyond Server or sends a floating <code>latest</code> tag to Supervisor. Checks and installation use each service account&#39;s own npm configuration; no separate registry setting is required.</li><li>Supervisor-managed Nodes can receive <strong>Push Upgrade</strong> from Node details. The Node drains active runs and rejects new runs, queue dispatch, and terminals while preparing. You may cancel while waiting for runs, but not after installation starts. On an older Node, first upgrade the npm package manually and configure <code>mar-node supervise</code> through <a href="./node-linux">Linux systemd</a>, <a href="./node-windows">Windows Task Scheduler</a>, or <a href="./node-macos">macOS launchd</a>.</li><li>Supervisor installs the exact package, rebuilds <code>node-pty</code> for the target platform, validates the entry point, and switches the child process. A failed installation retains the previous entry.</li><li>After reconnection, verify a new session, file read, terminal, and automatic startup after a service or host restart.</li></ol><p>The system does not automatically upgrade or downgrade Nodes. <strong>Target npm package unavailable</strong> means the published versions cannot be queried, no stable package satisfies both the Server ceiling and business baseline, or the Server version is invalid. Check the Server version, registry access, network, and publication status, then refresh.</p><h2 id="upgrade-status-and-recovery" tabindex="-1">Upgrade status and recovery <a class="header-anchor" href="#upgrade-status-and-recovery" aria-label="Permalink to &quot;Upgrade status and recovery&quot;">​</a></h2><ul><li><strong>Upgrade available</strong> identifies an eligible target for a Node with Supervisor support. The Node must also be online and enabled before a push.</li><li><strong>No upgrade needed</strong> means the Node has reached or exceeded the selected target; the system does not downgrade it. An unknown or unsupported version requires checking the Node installation. If Supervisor is not enabled, follow the platform instructions above to configure it manually.</li><li><strong>Waiting for runs</strong> means the request was accepted and active runs are draining; cancellation is available before handoff. A request whose result is unconfirmed is not proof of acceptance: do not blindly push it again.</li><li><strong>Upgrading</strong> shows closing the old Node, installing, or waiting for it to come online. Installation alone is not success. An interrupted progress stream means the result is unconfirmed, not that installation failed. If reconnection takes a long time, inspect the host rather than starting an overlapping upgrade.</li><li><strong>Completed</strong> means the target Node authenticated on its control connection for this attempt. A later disconnect does not undo that result.</li><li><strong>Failed</strong> provides the reason. Inspect Node and Supervisor logs and the result in the Node data directory. Retry only after the old operation has ended and the Node is online; otherwise investigate on the host. Installation failure before the entry switch retains the old entry; a subsequent startup failure does not automatically roll back.</li></ul><p>Live progress and the exit-timeout fallback require support from Server, Node, and the Supervisor actually running on the host. Updating only the Node child does not update an already running Supervisor. To enable the capability initially, update Server first, then update the Supervisor startup entry and restart the service in a maintenance window using the platform instructions. An older Supervisor continues the existing upgrade flow without live progress; a previously stuck old process requires separate intervention.</p><p>If the push action is absent, check that your account can manage that Node, the enterprise License is not frozen, and the Node is online and enabled. Remote upgrade only installs the Node package and switches its child process: it does not install Node.js, configure a system service, elevate permissions, or update Server/Web. Server and Node service accounts must each be able to access the selected npm package.</p><p>If a database migration fails, stop the upgrade and restore a matching backup rather than modifying the schema by hand. See <a href="./backup-restore">Backup and restore</a>.</p>',15)])])}const g=t(o,[["render",s]]);export{h as __pageData,g as default};

package/web/docs/assets/en-US_getting-started_npm-quick-start.md.CLCHq7k_.js

@@ -1,3 +0,0 @@
-import{_ as a,o as t,c as o,a3 as n}from"./chunks/framework.BHjrhdiC.js";const u=JSON.parse('{"title":"Local npm Quick Start","description":"","frontmatter":{"title":"Local npm Quick Start","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"en-US/getting-started/npm-quick-start.md","filePath":"en-US/getting-started/npm-quick-start.md"}'),s={name:"en-US/getting-started/npm-quick-start.md"};function r(i,e,d,c,l,p){return t(),o("div",null,[...e[0]||(e[0]=[n(`<h1 id="local-npm-quick-start" tabindex="-1">Local npm Quick Start <a class="header-anchor" href="#local-npm-quick-start" aria-label="Permalink to &quot;Local npm Quick Start&quot;">​</a></h1><p>Quick Start runs a fixed Community Server on your own computer for local evaluation. It uses loopback HTTP, a private MySQL instance and, by default, a local Node and SearXNG where managed search is supported. It does not install an operating-system service, require a host UUID or support license activation. For a shared or internet-facing installation, use the <a href="./server-installation">Docker Compose deployment</a> with HTTPS instead.</p><p>The verified installer targets are Linux x64 with glibc 2.28 or later, <code>tar</code> and <code>dpkg-deb</code> (such as a supported Debian or Ubuntu system), and Windows x64 with <code>tar</code> available. Use Node.js 24.12 or later and npm. Installing native dependencies may require an existing build toolchain; installation and setup never install system packages or request elevated privileges. Browser preparation and the selected components require network access. Other native platforms have not been verified for this Quick Start.</p><p>On Linux, <code>node-gyp</code> may fail to build native dependencies when the Node.js header cache path contains spaces. The program installation and deployment data paths may contain spaces. As an optional workaround, set <code>XDG_CACHE_HOME</code> to a writable absolute directory without spaces before running npm install; this changes the cache location used by that command.</p><h2 id="install-and-start" tabindex="-1">Install and start <a class="header-anchor" href="#install-and-start" aria-label="Permalink to &quot;Install and start&quot;">​</a></h2><p>After the Server package and its required dependencies are available in your npm registry, run as a normal user:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @myagentroam/server</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mar-server</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mar-server</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span></span></code></pre></div><p>Server depends normally on the matching Node. npm installs its native dependencies and prepares Chromium through Node&#39;s normal lifecycle, even if you later use <code>--no-node</code>. Installation and <code>mar-server --help</code> do not configure, register or start a local Node. Setup downloads the selected fixed components and initializes its own database; it does not use an existing MySQL server or accept <code>MAR_DATABASE_URL</code>. To skip local search, use <code>--no-searxng</code>; both options can be combined. Search preparation is optional, and failure is reported without discarding the other components.</p><p><code>--no-node</code> persists the disabled choice but does not remove Node dependencies from the Server package. To enable the local Node later, stop run, set <code>node.enabled</code> to <code>true</code> in <code>server.json</code>, preserve its identity, and rerun setup.</p><p>Run stays in the foreground and prints the local browser address. Stop it with Ctrl+C and wait for its children to exit. Run never downloads missing components. Setup and run for the same data directory cannot run concurrently. Do not expose the local HTTP endpoint to other machines; it is not a substitute for HTTPS or a production service.</p><p>The managed Node in Windows Quick Start uses IPv4 for direct connections. When only IPv6 connectivity is available, file and terminal traffic falls back to the Server relay.</p><h2 id="sign-in-and-start-work" tabindex="-1">Sign in and start work <a class="header-anchor" href="#sign-in-and-start-work" aria-label="Permalink to &quot;Sign in and start work&quot;">​</a></h2><p>Follow <a href="./first-login">First Sign-in and Password Change</a>. Change the initial administrator password immediately. Wait for the local Node to report online, then <a href="./register-workspace">register a Workspace</a> under the deployment&#39;s <code>workspace</code> directory. Local Node access is restricted to that directory by default; hosted conversations are not enabled automatically. Configure a model and credentials before <a href="./first-agent-session">starting a session</a>; an online Node or <code>/health</code> alone does not prove an Agent can execute.</p><p>The local Node initially allows only this deployment&#39;s <code>workspace/</code> directory. To use other projects, stop run and edit only the <code>allowedRoots</code> array in <code>node-data/node.json</code> under the deployment data directory. Supply one or more absolute paths, then start run again. For example, use <code>&quot;allowedRoots&quot;: [&quot;/home/alice/project&quot;, &quot;/srv/work&quot;]</code> on Unix or <code>&quot;allowedRoots&quot;: [&quot;C:\\\\Projects&quot;, &quot;D:\\\\Work&quot;]</code> on Windows. Do not replace the whole file or remove identity fields such as <code>nodeId</code>, credentials, or <code>serverUrl</code>. Allowed roots do not grant operating-system permissions; the account still needs access to those files. The npm program directory is separate from the deployment data directory, which defaults to <code>~/.myagentroam/quick-start/</code> and can be selected with <code>--config</code>.</p><h2 id="data-and-optional-search" tabindex="-1">Data and optional search <a class="header-anchor" href="#data-and-optional-search" aria-label="Permalink to &quot;Data and optional search&quot;">​</a></h2><p>By default, private configuration, credentials and component data are under <code>~/.myagentroam/quick-start/</code>. To use another private location, pass the same <code>--config /path/to/server.json</code> to setup and run. Protect and back up this directory. Repeating setup preserves credentials, Node data, Workspace and other component versions. The managed Node program follows Server dependency updates rather than using a separate upgrade or active entrypoint.</p><p>The <code>search</code> object in <code>server.json</code> has one mode: <code>managed</code>, <code>disabled</code>, or <code>external</code>. Managed SearXNG is not supported on Windows; use an external service if search is needed. To use an existing SearXNG service, stop run, change only <code>search.mode</code> to <code>&quot;external&quot;</code> and <code>search.url</code> to the service URL, preserve any existing <code>search.installation</code> record, then restart. The endpoint must allow JSON searches. A failed JSON check disables client search for that run; it does not fall back to another endpoint. <code>web_fetch</code> and model-hosted search remain separate. <code>--no-searxng</code> does not erase an external address.</p><p>To retry local search after disabling it, stop run, set the search mode to <code>managed</code>, preserve any existing <code>installation</code> record, and rerun setup. On an unsupported platform, leave it disabled and use an external endpoint instead. See <a href="./../deployment/node-installation">Node installation</a> for separately managed Nodes and <a href="./../deployment/production">production deployment</a> for operational guidance.</p>`,18)])])}const m=a(s,[["render",r]]);export{u as __pageData,m as default};

package/web/docs/assets/en-US_getting-started_npm-quick-start.md.CLCHq7k_.lean.js

@@ -1 +0,0 @@
-import{_ as a,o as t,c as o,a3 as n}from"./chunks/framework.BHjrhdiC.js";const u=JSON.parse('{"title":"Local npm Quick Start","description":"","frontmatter":{"title":"Local npm Quick Start","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"en-US/getting-started/npm-quick-start.md","filePath":"en-US/getting-started/npm-quick-start.md"}'),s={name:"en-US/getting-started/npm-quick-start.md"};function r(i,e,d,c,l,p){return t(),o("div",null,[...e[0]||(e[0]=[n("",18)])])}const m=a(s,[["render",r]]);export{u as __pageData,m as default};

package/web/docs/assets/en-US_getting-started_prerequisites.md.Bpx_AQD1.js

@@ -1 +0,0 @@
-import{_ as t,o,c as r,a3 as a}from"./chunks/framework.BHjrhdiC.js";const p=JSON.parse('{"title":"Before You Deploy","description":"","frontmatter":{"title":"Before You Deploy","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"en-US/getting-started/prerequisites.md","filePath":"en-US/getting-started/prerequisites.md"}'),n={name:"en-US/getting-started/prerequisites.md"};function i(s,e,c,l,d,u){return o(),r("div",null,[...e[0]||(e[0]=[a('<h1 id="before-you-deploy" tabindex="-1">Before You Deploy <a class="header-anchor" href="#before-you-deploy" aria-label="Permalink to &quot;Before You Deploy&quot;">​</a></h1><p>Use this checklist to confirm host, network, and Agent requirements.</p><h2 id="requirements" tabindex="-1">Requirements <a class="header-anchor" href="#requirements" aria-label="Permalink to &quot;Requirements&quot;">​</a></h2><ul><li>A Server host that can run Docker Compose, or an environment where you manage MySQL 8.4, Server, and Web yourself.</li><li>An HTTPS hostname for browsers. Production deployments should terminate TLS at a reverse proxy.</li><li>Node.js <code>&gt;=22.13</code> on every Windows, Linux, or macOS work host, plus a Workspace writable by the Node service account. Hosted conversations require a Linux Node with Bubblewrap.</li><li>For built-in MAR Agent, no external Agent CLI is required. An administrator must <a href="./../runners/mar-agent">configure, enable, and authorize a model</a>, and the user must be within its bound credential scope.</li><li>For Codex, Claude Code, or OpenCode, install only the required Agent CLI and complete authentication or provider configuration under the same Node service account.</li></ul><h2 id="checklist" tabindex="-1">Checklist <a class="header-anchor" href="#checklist" aria-label="Permalink to &quot;Checklist&quot;">​</a></h2><ol><li>Choose <code>MAR_PUBLIC_ORIGIN</code>, such as <code>https://mar.example.com</code>. It must exactly match the browser-facing origin.</li><li>Prepare strong, separate passwords for the MySQL root and application accounts.</li><li>Confirm that Server can serve HTTPS and every Node can make outbound HTTPS/WSS connections to it.</li><li>Under the final Node service account, check <code>node --version</code> and <code>npm --version</code>. For MAR Agent, test the model in management; for external Agents, also check the corresponding CLI version.</li><li>Record the exact Workspace paths. Never use an entire disk as <code>allowedRoots</code>.</li></ol><p><strong>Success:</strong> every Node resolves and reaches the Server hostname, and its service account can enter the target Workspace.</p><p>If an Agent works in an interactive shell but not as a service, the service account likely has a different home directory or <code>PATH</code>. Follow <a href="./../deployment/node-installation">Install and Register a Node</a>.</p><p>Next: <a href="./server-installation">Deploy Server and Web</a>.</p><p>Formal deployments require a valid real host UUID in both Community and Enterprise states. Containers must mount <code>/sys/class/dmi/id/product_uuid</code> read-only at <code>/license-host/product_uuid</code>; the source must exist. Native formal deployments may use <code>MAR_LICENSE_HOST_PATH</code> to select the real UUID file. The local-only <a href="./npm-quick-start">npm Quick Start</a> does not require a UUID and cannot be activated.</p>',10)])])}const m=t(n,[["render",i]]);export{p as __pageData,m as default};

package/web/docs/assets/en-US_getting-started_prerequisites.md.Bpx_AQD1.lean.js

@@ -1 +0,0 @@
-import{_ as t,o,c as r,a3 as a}from"./chunks/framework.BHjrhdiC.js";const p=JSON.parse('{"title":"Before You Deploy","description":"","frontmatter":{"title":"Before You Deploy","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"en-US/getting-started/prerequisites.md","filePath":"en-US/getting-started/prerequisites.md"}'),n={name:"en-US/getting-started/prerequisites.md"};function i(s,e,c,l,d,u){return o(),r("div",null,[...e[0]||(e[0]=[a("",10)])])}const m=t(n,[["render",i]]);export{p as __pageData,m as default};

package/web/docs/assets/en-US_workbench_skills.md.C4xlXyjC.js

@@ -1 +0,0 @@
-import{_ as t,o as n,c as a,a3 as s}from"./chunks/framework.BHjrhdiC.js";const p=JSON.parse('{"title":"Favorite and Install Skills","description":"","frontmatter":{"title":"Favorite and Install Skills","lastUpdated":"2026-11-06T00:00:00.000Z"},"headers":[],"relativePath":"en-US/workbench/skills.md","filePath":"en-US/workbench/skills.md"}'),o={name:"en-US/workbench/skills.md"};function r(i,e,l,d,c,g){return n(),a("div",null,[...e[0]||(e[0]=[s('<h1 id="favorite-and-install-skills" tabindex="-1">Favorite and Install Skills <a class="header-anchor" href="#favorite-and-install-skills" aria-label="Permalink to &quot;Favorite and Install Skills&quot;">​</a></h1><p>Configurable and added catalog lists request 20 entries per page from the Server. Search, ordering and categories cover the complete visible catalog; category tags do not shrink to the current page or search results. Source definitions and the current target’s installed Skill/MCP entries are complete configuration snapshots and are shown without pagination. An installation remains visible if its catalog reference disappears, but only its existing permitted operations remain available; this does not grant reinstallation or changes to inherited configuration.</p><p>Open <strong>Admin &gt; Skill Configuration</strong> to browse Skill and MCP entries made available from enabled sources. Skill Configuration, Skill Sources, and Secrets are consecutive flat Admin entries; there is no separate top-level Skills or Skill Center entry.</p><p>Choose the Node and, when required, the Workspace before installing. Review version, source, and target status. Updating replaces the installed copy with the selected catalog version; reinstalling restores the same version. If files conflict, inspect the target before approving an overwrite.</p><p>Skill Configuration shows installed state and environment checks. Removing an installation does not remove the catalog favorite or its source. Authorized users administer external sources under <strong>Admin &gt; Skill Sources</strong> and configure referenced secrets under <strong>Admin &gt; Environment Secrets</strong>.</p><h2 id="skill-sources-and-installation" tabindex="-1">Skill sources and installation <a class="header-anchor" href="#skill-sources-and-installation" aria-label="Permalink to &quot;Skill sources and installation&quot;">​</a></h2><p>Skills provide reusable instructions; MCP servers connect Agents to tools and services. Node-level configuration applies to its Workspaces, while a same-named Workspace configuration takes precedence. In <strong>Skill Sources</strong>, choose an enabled source and add a Skill to the available personal, organization, or enterprise catalog. Check its source and version before adding it. Catalog updates do not automatically update installed copies: check for updates, confirm the new version, and install it on each intended target.</p><p>Repository sources require a recognizable Git revision. Public GitHub and compatible GitLab repositories can use HTTPS; SSH sources use <code>git@host:owner/repo.git</code> and the Server deployment account&#39;s SSH configuration. SSH Skill sources skip host fingerprint verification, so use only trusted networks and sources; see <a href="./../getting-started/server-installation">Server deployment</a>. Source addresses are checked against local and private targets. TLS verification is enabled by default; disabling it for a self-signed source is a separate, high-risk administrator setting and does not relax address checks.</p><p>Choose an online Node and optionally its Workspace in <strong>Skill Configuration</strong>. Check the environment, then install, update, or reinstall. Node installations use the service account&#39;s <code>~/.agents/skills</code>; Workspace installations maintain <code>.agents/skills</code> and <code>.claude/skills</code>, with managed local Git exclusions rather than changes to the tracked <code>.gitignore</code>. A Node or browser interruption does not automatically retry an installation. If confirmation times out, refresh the target&#39;s actual status before deciding whether to retry. Unknown installed versions can be reinstalled; inspect permission, target path, and environment errors before trying again.</p><p>To see a Workspace&#39;s shared skills, open the Workspace and choose <strong>Loaded Skills</strong> from the menu next to <strong>New Session</strong>. This list and the Composer&#39;s <code>/</code> skill list read only the Node account&#39;s <code>~/.agents/skills</code> and the Workspace&#39;s <code>.agents/skills</code>, not the <code>.claude/skills</code> compatibility directories. Entries show their source, and a same-named Workspace skill takes precedence. Installation and removal remain in <strong>Skill Configuration</strong>; removing a Workspace override can expose a same-named Node entry again.</p><h2 id="mcp-servers" tabindex="-1">MCP servers <a class="header-anchor" href="#mcp-servers" aria-label="Permalink to &quot;MCP servers&quot;">​</a></h2><p>In <strong>MCP Sources</strong>, search an enabled Registry, inspect the server and pinned version, and add it to the available catalog. In <strong>Skill Configuration</strong>, switch to the MCP tab, select the online Node or Workspace, and install the intended entry. Node installation uses the Node account&#39;s command environment: npm-based entries may download a pinned package via <code>npx</code>. MAR validates initialization and reads at least one tool before saving the configuration. Resolve network, authentication, package, or system dependency errors on that Node before retrying.</p><p>Changes affect new or reopened Agent sessions, not an already running session. Removing the configuration does not clear npm caches. Environment variables and request headers refer to names in <strong>Environment Secrets</strong>, not secret values; add a missing referenced secret before using the MCP. Use <strong>Loaded MCP</strong> beside <strong>New Session</strong> to inspect the effective Workspace and Node configuration.</p><p>For Playwright, add a pinned Registry version and install it on the intended target. Its default browser is headless, each Agent session has an isolated browser context, and browser state is not retained after the session. The Node must be able to run the package and access the target site. If tools are unavailable, verify the target and installation and start a new session.</p>',14)])])}const u=t(o,[["render",r]]);export{p as __pageData,u as default};

package/web/docs/assets/getting-started_npm-quick-start.md.B9varoSe.js

@@ -1,3 +0,0 @@
-import{_ as o,o as a,c as s,a3 as t}from"./chunks/framework.BHjrhdiC.js";const u=JSON.parse('{"title":"本机 npm 快速开始","description":"","frontmatter":{"title":"本机 npm 快速开始","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"getting-started/npm-quick-start.md","filePath":"getting-started/npm-quick-start.md"}'),d={name:"getting-started/npm-quick-start.md"};function n(r,e,i,c,p,l){return a(),s("div",null,[...e[0]||(e[0]=[t(`<h1 id="本机-npm-快速开始" tabindex="-1">本机 npm 快速开始 <a class="header-anchor" href="#本机-npm-快速开始" aria-label="Permalink to &quot;本机 npm 快速开始&quot;">​</a></h1><p>Quick Start 在自己的电脑上启动固定社区版 Server，供本机体验。它使用回环 HTTP、专用 MySQL，默认准备本机 Node，并在支持受管搜索的平台准备 SearXNG；不安装系统常驻服务，不要求主机 UUID，也不支持激活 License。共享或面向互联网的安装应改用带 HTTPS 的 <a href="./server-installation">Docker Compose 正式部署</a>。</p><p>目前实际验证的安装目标是带 glibc 2.28 或更高版本、<code>tar</code> 和 <code>dpkg-deb</code> 的 Linux x64（例如受支持的 Debian 或 Ubuntu 系统），以及可使用 <code>tar</code> 的 Windows x64。需要 Node.js 24.12 或更高版本以及 npm。安装包时原生依赖可能要求系统已有可用的构建工具；安装和 setup 均不安装系统包，也不请求提权。浏览器和所选组件的准备需要网络。其他原生平台尚未完成此 Quick Start 的验证。</p><p>在 Linux 上，原生依赖构建使用的 Node.js 头文件缓存路径包含空格时，<code>node-gyp</code> 可能构建失败；安装程序目录和部署数据目录可以包含空格。可选的解决方法是在安装前将 <code>XDG_CACHE_HOME</code> 设为当前用户可写、无空格的绝对目录，再执行 npm 安装；这会改变该命令使用的缓存位置。</p><h2 id="安装与启动" tabindex="-1">安装与启动 <a class="header-anchor" href="#安装与启动" aria-label="Permalink to &quot;安装与启动&quot;">​</a></h2><p>当 npm Registry 中已有 Server 包及其所需依赖后，以普通用户运行：</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @myagentroam/server</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mar-server</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mar-server</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span></span></code></pre></div><p>Server 以普通依赖使用同版本 Node；npm 安装会按 Node 原有生命周期安装原生依赖并准备 Chromium，即使之后使用 <code>--no-node</code>。安装或查看 <code>mar-server --help</code> 不配置、注册或启动本机 Node。setup 下载所选固定组件并初始化专用数据库，不使用已有 MySQL，也不接受 <code>MAR_DATABASE_URL</code>。跳过本地搜索使用 <code>--no-searxng</code>；两个参数可以组合。搜索准备是可选步骤，失败会报告但不会丢弃其他组件。</p><p><code>--no-node</code> 会持久保存禁用选择，但不会从 Server 包移除 Node 依赖。之后如需启用本机 Node，先停止 run，在 <code>server.json</code> 中将 <code>node.enabled</code> 设为 <code>true</code>，保留身份，再运行 setup。</p><p>run 在前台运行并打印本机浏览器地址。使用 Ctrl+C 停止并等待子进程退出；run 不会下载缺失组件。同一数据目录不能并发执行 setup 和 run。不要将本机 HTTP 入口暴露给其他设备；它不能替代 HTTPS 或生产服务。</p><p>Windows 本机 Quick Start 的受管 Node 使用 IPv4 直连；如果只能通过 IPv6 连接，文件和终端流量会回退到 Server 中继。</p><h2 id="登录并开始工作" tabindex="-1">登录并开始工作 <a class="header-anchor" href="#登录并开始工作" aria-label="Permalink to &quot;登录并开始工作&quot;">​</a></h2><p>按<a href="./first-login">首次登录与修改密码</a>立即修改初始管理员密码。等待本机 Node 显示在线，再在部署目录的 <code>workspace</code> 下<a href="./register-workspace">登记 Workspace</a>。本机 Node 默认只能访问该目录，不会自动启用托管对话。<a href="./first-agent-session">开始会话</a>前还需配置模型和凭据；Node 在线或 <code>/health</code> 成功并不代表 Agent 已能执行。</p><p>本机 Node 的默认允许目录仅为本部署的 <code>workspace/</code>。如需使用其他项目，先停止 run，只编辑部署数据目录内 <code>node-data/node.json</code> 的 <code>allowedRoots</code> 数组，填写一个或多个绝对路径，然后重新 run。例如 Unix 可用 <code>&quot;allowedRoots&quot;: [&quot;/home/alice/project&quot;, &quot;/srv/work&quot;]</code>，Windows 可用 <code>&quot;allowedRoots&quot;: [&quot;C:\\\\Projects&quot;, &quot;D:\\\\Work&quot;]</code>。不要覆盖整个文件或删除 <code>nodeId</code>、凭据及 <code>serverUrl</code> 等身份字段。允许目录不会提升操作系统账号权限；账号仍需有相应文件权限。npm 程序安装目录与部署数据目录不同，后者默认为 <code>~/.myagentroam/quick-start/</code>，也可由 <code>--config</code> 指定。</p><h2 id="数据与可选搜索" tabindex="-1">数据与可选搜索 <a class="header-anchor" href="#数据与可选搜索" aria-label="Permalink to &quot;数据与可选搜索&quot;">​</a></h2><p>默认私有配置、凭据和组件数据位于 <code>~/.myagentroam/quick-start/</code>。如需其他私有位置，setup 和 run 均传入相同的 <code>--config /path/to/server.json</code>。请保护并备份该目录。重复 setup 保留凭据、Node 数据、Workspace 及其他组件版本。受管 Node 程序随 Server 依赖更新，不使用独立升级或活动入口。</p><p><code>server.json</code> 的 <code>search</code> 对象只有 <code>managed</code>、<code>disabled</code>、<code>external</code> 三种模式。Windows 不支持受管 SearXNG；如需搜索，可使用外部服务。如需使用已有 SearXNG，停止 run，只将 <code>search.mode</code> 改为 <code>&quot;external&quot;</code>、将 <code>search.url</code> 改为服务地址，保留已有的 <code>search.installation</code> 记录，再重新启动。该服务必须允许 JSON 搜索。JSON 检查失败时，本次运行不提供客户端搜索，也不会回退到其他地址；<code>web_fetch</code> 和模型托管搜索是独立能力。<code>--no-searxng</code> 不会清除外部地址。</p><p>禁用后如需重试本地搜索，停止 run，将搜索模式设为 <code>managed</code>，保留已有 <code>installation</code> 记录，再运行 setup。不受支持的平台请保持禁用并改用外部地址。独立管理 Node 参见 <a href="./../deployment/node-installation">Node 安装</a>，正式运维参见<a href="./../deployment/production">生产部署</a>。</p>`,18)])])}const k=o(d,[["render",n]]);export{u as __pageData,k as default};

package/web/docs/assets/getting-started_npm-quick-start.md.B9varoSe.lean.js

@@ -1 +0,0 @@
-import{_ as o,o as a,c as s,a3 as t}from"./chunks/framework.BHjrhdiC.js";const u=JSON.parse('{"title":"本机 npm 快速开始","description":"","frontmatter":{"title":"本机 npm 快速开始","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"getting-started/npm-quick-start.md","filePath":"getting-started/npm-quick-start.md"}'),d={name:"getting-started/npm-quick-start.md"};function n(r,e,i,c,p,l){return a(),s("div",null,[...e[0]||(e[0]=[t("",18)])])}const k=o(d,[["render",n]]);export{u as __pageData,k as default};

package/web/docs/assets/getting-started_prerequisites.md.D26KU42D.js

@@ -1 +0,0 @@
-import{_ as o,o as a,c as t,a3 as r}from"./chunks/framework.BHjrhdiC.js";const _=JSON.parse('{"title":"部署前准备","description":"","frontmatter":{"title":"部署前准备","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"getting-started/prerequisites.md","filePath":"getting-started/prerequisites.md"}'),i={name:"getting-started/prerequisites.md"};function d(l,e,n,s,c,p){return a(),t("div",null,[...e[0]||(e[0]=[r('<h1 id="部署前准备" tabindex="-1">部署前准备 <a class="header-anchor" href="#部署前准备" aria-label="Permalink to &quot;部署前准备&quot;">​</a></h1><p>这篇文档帮助你在部署前确认主机、网络和 Agent 条件。</p><h2 id="前置条件" tabindex="-1">前置条件 <a class="header-anchor" href="#前置条件" aria-label="Permalink to &quot;前置条件&quot;">​</a></h2><ul><li>一台可运行 Docker Compose 的 Server 主机，或能自行提供 MySQL 8.4、Server 和 Web 的运行环境。</li><li>一个供浏览器访问的 HTTPS 域名；生产环境应由反向代理终止 TLS。</li><li>每台 Windows、Linux 或 macOS 工作主机安装 Node.js <code>&gt;=22.13</code>，并为 Node 运行账号准备可读写的 Workspace；托管对话仅部署在具备 Bubblewrap 的 Linux Node。</li><li>使用内置 MAR Agent：不需要外部 Agent CLI，管理员须先<a href="./../runners/mar-agent">配置、启用并授权模型</a>，且当前用户处于所绑定凭据的作用域内。</li><li>使用 Codex、Claude Code 或 OpenCode：仅安装需要的 Agent CLI，并在同一 Node 服务账号下完成登录或模型服务配置。</li></ul><h2 id="检查清单" tabindex="-1">检查清单 <a class="header-anchor" href="#检查清单" aria-label="Permalink to &quot;检查清单&quot;">​</a></h2><ol><li>为 Server 准备 <code>MAR_PUBLIC_ORIGIN</code>，例如 <code>https://mar.example.com</code>；它必须与浏览器实际访问地址完全一致。</li><li>准备两个强密码：MySQL root 密码和 MySQL 应用账号密码。</li><li>确认 Server 可对外提供 HTTPS，Node 主机可向该地址发起 HTTPS/WSS 出站连接。</li><li>在每台 Node 主机用最终服务账号执行 <code>node --version</code>、<code>npm --version</code>。使用 MAR Agent 时，在管理页测试模型；使用外部 Agent 时再检查对应 CLI 版本。</li><li>记录需要登记的真实 Workspace 路径，不要将整个磁盘作为 <code>allowedRoots</code>。</li></ol><p><strong>成功标志：</strong> 所有 Node 主机都能解析并访问 Server 域名，且服务账号能进入目标 Workspace。</p><h2 id="常见问题" tabindex="-1">常见问题 <a class="header-anchor" href="#常见问题" aria-label="Permalink to &quot;常见问题&quot;">​</a></h2><ul><li>浏览器与 <code>MAR_PUBLIC_ORIGIN</code> 不一致：登录或 WebSocket 可能被 Origin 校验拒绝；先统一协议、域名和端口。</li><li>Agent 在交互终端可用、服务中不可用：通常是服务账号的用户目录或 <code>PATH</code> 不同，按<a href="./../deployment/node-installation">Node 安装与注册</a>配置。</li></ul><p>下一步：<a href="./server-installation">部署 Server 与 Web</a>。</p><p>正式部署的社区与企业状态都要求有效的真实主机 UUID。容器必须将宿主 <code>/sys/class/dmi/id/product_uuid</code> 只读挂载到 <code>/license-host/product_uuid</code>，源文件必须存在；原生正式部署可用 <code>MAR_LICENSE_HOST_PATH</code> 指定真实 UUID 文件。仅供本机体验的 <a href="./npm-quick-start">npm 快速开始</a>无需 UUID，也不支持激活。</p>',11)])])}const h=o(i,[["render",d]]);export{_ as __pageData,h as default};

package/web/docs/assets/workbench_skills.md.rWZ_VuoB.js

@@ -1 +0,0 @@
-import{_ as l,o as a,c as i,a3 as o}from"./chunks/framework.BHjrhdiC.js";const P=JSON.parse('{"title":"添加与安装技能","description":"","frontmatter":{"title":"添加与安装技能","lastUpdated":"2026-11-06T00:00:00.000Z"},"headers":[],"relativePath":"workbench/skills.md","filePath":"workbench/skills.md"}'),r={name:"workbench/skills.md"};function t(s,e,c,d,n,p){return a(),i("div",null,[...e[0]||(e[0]=[o('<h1 id="查找与配置-skill、mcp" tabindex="-1">查找与配置 Skill、MCP <a class="header-anchor" href="#查找与配置-skill、mcp" aria-label="Permalink to &quot;查找与配置 Skill、MCP&quot;">​</a></h1><p>可配置目录和已加入目录每页向服务端读取 20 条，搜索、排序和分类覆盖完整可见目录；标签分类不随当前页或搜索结果缩小。来源定义和当前目标的已安装 Skill/MCP 是完整配置快照，直接全部展示，不分页。已安装项即使失去目录引用仍保留，但只能使用原有合法操作，不能借此重新安装或更改继承配置。</p><p>“管理”菜单中的“技能配置”同时提供 Skill 与 MCP 两类 Agent 扩展。Skill 为 Agent 提供可复用的操作说明和工作流；MCP Server 让 Agent 连接浏览器、业务系统或其他工具。两者都可以配置到节点或工作区：节点配置对该节点上的工作区生效，工作区同名配置优先。</p><p>技能配置直接展示当前用户可用的企业、组织和个人目录，并用于将目录项安装到节点用户目录或工作区。页面默认在“可配置技能”Tab 选择并安装 Skill，“当前目标中的技能”Tab 用于查看、更新、重新安装或删除目标目录中的 Skill。</p><p>打开 Workspace 后，可点击会话栏“新建会话”右侧的“更多”按钮，再选择“已加载技能”，只读查看该 Workspace 的公共技能。此列表和 Composer 的 <code>/</code> 技能列表只读取节点用户目录 <code>~/.agents/skills</code> 与 Workspace 的 <code>.agents/skills</code>，不读取 <code>.claude/skills</code> 兼容目录；列表标注来源，名称相同时以 Workspace 技能为准。安装、更新和删除仍在“管理 → 技能配置”中完成。</p><h2 id="管理来源与可用技能" tabindex="-1">管理来源与可用技能 <a class="header-anchor" href="#管理来源与可用技能" aria-label="Permalink to &quot;管理来源与可用技能&quot;">​</a></h2><ol><li>打开“管理 → 技能源管理”。下方默认进入“源内技能”Tab，在下拉框选择已启用的来源；页面会自动加载该来源的技能，skills.sh 默认显示缓存 24 小时的 Hot 热门榜，也可在下方输入名称或描述后搜索。“已加入的技能”Tab 用于维护已经加入可用目录的技能。</li><li>点击技能卡片的“加入可用目录”，选择个人、组织或企业范围；可同时启用星标推荐并添加最多 10 个 Tag 标签。标签下拉提供当前账号有权查看的已有标签，也可以直接输入新标签。加入后可按名称、描述和分类标签筛选，可查看详情，或编辑星标和标签。</li><li>已加入目录的技能显示当前 Commit 短版本和更新时间。“检查更新”只比较原仓库最新 Commit，发现新版本后再由用户确认更新；目录更新后，Node 或 Workspace 不会自动变化。</li></ol><p>星标技能会优先出现在技能配置的可配置目录中，Tag 用于说明技能用途。更新技能内容不会改变已有星标和 Tag。</p><p>仓库源必须具备可识别的 Git 版本，不接受直接下载地址。公开仓库可使用 HTTPS，支持 GitHub，以及使用标准接口的 GitLab.com/自托管 GitLab；SSH 仓库使用 <code>git@host:owner/repo.git</code> 格式。Compose 部署会把独立部署账号的完整 <code>.ssh</code> 目录只读提供给 Server，具体配置见<a href="./../reference/configuration">配置项参考</a>；连接时跳过主机指纹校验。仓库根目录或标准技能目录均可，系统会拒绝指向本机、私网或链路本地地址的来源。每个用户都可以添加自己的个人源，而且只有本人能查看和管理；企业或组织源需要相应管理权限。默认 <code>skills.sh</code> 源可停用但不能删除。</p><p>TLS 证书校验默认启用。企业管理员可在“管理 → 系统配置”打开高风险的关闭开关，以兼容自签名来源；该设置不会放宽来源地址校验。</p><h2 id="安装到节点或工作区" tabindex="-1">安装到节点或工作区 <a class="header-anchor" href="#安装到节点或工作区" aria-label="Permalink to &quot;安装到节点或工作区&quot;">​</a></h2><ol><li>打开“管理 → 技能配置”，直接在页面中选择在线节点以及安装位置；安装到工作区时再选择该节点下的工作区。</li><li>节点或工作区切换后会自动检查环境，也可手动点击“检查环境”，随后执行“安装”“更新”或“重新安装”。页面选择独立于工作台资源树，不会切换当前打开的工作区。</li><li>节点以 <code>~/.agents/skills</code> 为主目录，并在首次安装时检查或创建 <code>.claude/skills</code> 兼容链接；若已有目录不能安全链接，则维护兼容副本。</li><li>工作区同时维护 <code>.agents/skills</code> 和 <code>.claude/skills</code> 两份副本，并将受管目录写入本地 <code>.git/info/exclude</code>，不会修改版本化 <code>.gitignore</code>。</li></ol><p>安装由节点在后台下载、校验并写入目录；页面会等待完成后刷新状态，耗时较长时在对应卡片显示进度，无需重复点击或刷新。安装失败会释放当前目标，处理错误原因后可以再次安装；状态确认超时时应先刷新目录确认真实结果，再决定是否重试。浏览器断开或服务重启不会自动重复安装。</p><p>系统不会覆盖人工修改的判断结果；无法识别已安装版本时会显示“版本未知”，可以从技能配置重新安装。</p><p>技能配置提供名称/描述搜索和“全部 + 分类标签”筛选，技能卡片可查看详情并在页面内容区内独立滚动。手动“检查环境”会弹窗显示兼容模式、技能数量和待修复项；Workspace 环境检查发现 Git 本地排除规则异常时，可点击带工具图标的“修正环境”，确认后重新生成 MAR 维护的规则块，取消不会修改 Workspace。</p><h2 id="平台与失败处理" tabindex="-1">平台与失败处理 <a class="header-anchor" href="#平台与失败处理" aria-label="Permalink to &quot;平台与失败处理&quot;">​</a></h2><p>Linux 与 Windows 均支持节点和工作区技能；Windows 不能创建目录链接时会使用受管副本。节点离线、版本过旧、目录权限不足、技能根目录指向 Workspace 外部，或工作区 Git 排除文件不可写时，界面会禁用操作或显示明确错误。单个技能名称位置若为链接，重新安装会原子替换该链接且不会修改链接指向的外部内容；MAR 不会跟随或覆盖越界的技能根目录。</p><h2 id="使用-mcp-server" tabindex="-1">使用 MCP Server <a class="header-anchor" href="#使用-mcp-server" aria-label="Permalink to &quot;使用 MCP Server&quot;">​</a></h2><h3 id="将-mcp-server-加入中心" tabindex="-1">将 MCP Server 加入中心 <a class="header-anchor" href="#将-mcp-server-加入中心" aria-label="Permalink to &quot;将 MCP Server 加入中心&quot;">​</a></h3><ol><li>打开“管理 → MCP 源管理”。系统已提供官方 MCP Registry；也可以新增兼容 Registry，并选择个人、组织或企业范围。</li><li>选择一个已启用来源，按名称或说明搜索 MCP Server。可先点击“详情”核对 Server 名称、连接方式和固定版本，再点击“加入可用目录”，设置可见范围、推荐状态和标签；标签可以从当前已有标签中选择，也可以直接输入新标签。</li><li>在“已加入的 MCP”中可查看详情、编辑推荐和标签、检查 Registry 更新、确认更新或移除。更新可用目录不会自动改变已经配置到节点或工作区的版本。</li><li>返回“管理 → 技能配置”，切换到“MCP”Tab，即可浏览当前账号可用的 MCP Server；可按名称或说明搜索，也可使用“全部 + 标签”切换分类，并可在选择目标后直接安装。</li></ol><p>目录只保存固定版本，不使用会在未来自动变化的 <code>latest</code>。新增或升级版本不会自动改变节点与工作区中的现有配置，需要用户明确安装。</p><h3 id="配置到节点或工作区" tabindex="-1">配置到节点或工作区 <a class="header-anchor" href="#配置到节点或工作区" aria-label="Permalink to &quot;配置到节点或工作区&quot;">​</a></h3><ol><li>打开“管理 → 技能配置”，切换到“MCP”Tab。</li><li>选择“节点”或“工作区”，然后选择在线目标。节点配置适合多个工作区共用；仅某个项目需要的 MCP 应配置到对应工作区。目标离线、停用、版本不支持、工作区缺失或权限不足时，页面会保留具体原因，不再只显示笼统的不可用提示。</li><li>在“可配置 MCP”Tab 可查看详情并点击“安装”；已经安装旧版本时按钮显示“更新”。安装由目标 Node 使用其运行账号的本地命令环境执行：<code>npx</code> 可按用户自己的 npm 配置下载和缓存固定版本，MAR 每次都会完成 MCP 初始化和工具读取验证，并至少确认一个可用工具，耗时较长时卡片会显示进度。只有验证完成才会保存配置并提示成功；失败时可先在 Node 终端修正 npm、网络、鉴权或系统依赖后重试。安装成功后只影响随后新建或重新打开的 Agent 会话，不修改已经运行的会话；删除配置不会清理用户的 npm/npx 缓存。</li><li>在“当前目标中的 MCP”Tab 可查看详情、启用、停用、更新、重新安装或删除。工作区删除同名配置后，若节点仍配置了该 MCP，新会话会继续使用节点配置。</li><li>在节点工作台中，点击“新建会话”右侧的“…”并选择“已加载 MCP”，可以在创建会话前确认该 Workspace 最终启用的 MCP 及其来自 Workspace 还是 Node。被 Workspace 同名配置停用的 Node MCP 不会出现在这里。</li></ol><p>MCP Server 的环境变量和请求头只引用“环境密钥”中已有的环境变量名，页面和保存记录不会包含密钥值。引用的环境密钥不存在时，该 MCP 不会注入 Agent 会话，应先在“管理 → 环境密钥”补齐。</p><h3 id="使用-playwright" tabindex="-1">使用 Playwright <a class="header-anchor" href="#使用-playwright" aria-label="Permalink to &quot;使用 Playwright&quot;">​</a></h3><p>在官方 MCP Registry 中搜索 Playwright，将需要的固定版本加入可用目录并安装到目标后，Agent 即可在浏览器中打开页面、交互、截图和验证 Web 功能。Playwright 不是不可删除的内置目录项，可从可用目录、节点或工作区移除。默认配置具有以下边界：</p><ul><li>使用无头浏览器，不弹出本机浏览器窗口；</li><li>每个 Agent 会话使用独立浏览器上下文，不共享 Cookie、登录态或页面；</li><li>会话结束后不保留浏览状态；需要登录时，应在当前会话内完成；</li><li>Node 主机需要能够执行该 MCP Server 的固定 npm 包版本并访问待测页面。</li></ul><p>如果 Agent 无法调用 Playwright，先确认目标节点在线、Node 版本支持 MCP、Playwright 已安装到正确的节点或工作区，并新建一个会话重试。运行中的旧会话不会热加载刚安装的 MCP。</p>',28)])])}const k=l(r,[["render",t]]);export{P as __pageData,k as default};