@myagentroam/server 0.13.6 → 0.13.8

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_administration_license.md.Dmg8rNEl.js

@@ -1 +0,0 @@
-import{_ as t,o as n,c as i,a3 as r}from"./chunks/framework.BHjrhdiC.js";const p=JSON.parse('{"title":"Community and Enterprise Licenses","description":"","frontmatter":{"title":"Community and Enterprise Licenses","lastUpdated":"2026-11-10T00:00:00.000Z"},"headers":[],"relativePath":"en-US/administration/license.md","filePath":"en-US/administration/license.md"}'),a={name:"en-US/administration/license.md"};function o(s,e,d,c,l,m){return n(),i("div",null,[...e[0]||(e[0]=[r('<h1 id="community-and-enterprise-licenses" tabindex="-1">Community and Enterprise Licenses <a class="header-anchor" href="#community-and-enterprise-licenses" aria-label="Permalink to &quot;Community and Enterprise Licenses&quot;">​</a></h1><p>Community Edition provides the default single-user experience without a limit on registered Nodes. An Enterprise license enables organizations, additional users, resource sharing, SSO, and audit management.</p><p>The fixed Community administrator can also manage deployment settings under <strong>Admin → System Configuration</strong> without an Enterprise license. Configuring audit retention does not grant access to audit queries or exports. A frozen Enterprise license still blocks system configuration changes.</p><p>A System Administrator opens <strong>Admin → System Information</strong>, copies the request code, and sends it privately to the issuer. Paste the complete returned License document into <strong>License Authorization</strong>, import it, and verify enterprise name and expiry before creating enterprise resources.</p><p>An expired or frozen license restricts enterprise management writes while preserving configured resources and normal work according to the displayed state. Import a valid replacement to restore management. Treat request codes and License documents as administrative data and do not publish them.</p><p>Formal deployments use the same program and image set; activation does not replace the installation. Both formal license states require the real host UUID; containers must mount it read-only, and startup fails if it is unavailable or invalid. The local-only <a href="./../getting-started/npm-quick-start">npm Quick Start</a> uses fixed Community capabilities without a UUID and cannot be activated; System Information does not generate request codes or show License import controls. License capabilities do not replace user and resource authorization.</p><h2 id="why-does-formal-community-deployment-require-a-host-uuid" tabindex="-1">Why does formal Community deployment require a host UUID? <a class="header-anchor" href="#why-does-formal-community-deployment-require-a-host-uuid" aria-label="Permalink to &quot;Why does formal Community deployment require a host UUID?&quot;">​</a></h2><p>In formal deployments, Community and Enterprise use the same Server startup and host-identity mechanism. Server derives a host fingerprint locally from the real UUID; Enterprise License validation uses it to bind a License to that Server host. Community does not require an Enterprise activation request or an online license-validation service.</p><p>This host-identity check is not an analytics upload. License verification is local; to request Enterprise activation, an administrator deliberately sends the request code (which contains the host fingerprint) to the issuer. Do not publish that code. This does not imply that the entire product is offline: model providers, configured integrations, and other network features have their own data flows.</p><p>Containers must mount the real host UUID read-only. A VM must expose a valid UUID; missing or invalid identity blocks startup rather than falling back to a generated ID. Moving Server to a host with a different UUID requires a replacement Enterprise License bound to the new host. Community still requires the new host&#39;s valid UUID but no Enterprise activation. Community is single-user and does not limit registered Nodes.</p><h2 id="source-licensing-and-permitted-use" tabindex="-1">Source licensing and permitted use <a class="header-anchor" href="#source-licensing-and-permitted-use" aria-label="Permalink to &quot;Source licensing and permitted use&quot;">​</a></h2><p>The EE author and licensor is <strong>aCHAOS (<a href="mailto:achaosxyz@gmail.com" target="_blank" rel="noreferrer">achaosxyz@gmail.com</a>)</strong>. <code>ee/LICENSE</code> contains the full English MyAgentRoam Enterprise Source-Available License 1.0 (<code>MAR-ESAL-1.0</code>); the product root <code>LICENSING.md</code> explains its scope. It is not an OSI-approved open-source license. Independent Apache components and third-party materials retain their own licenses.</p><p>Community features are free for internal use, including a company&#39;s own commercial work and deployment on cloud infrastructure it controls. Enterprise features include organization and multi-user administration, enterprise roles and organizational permissions, shared-resource authorization, SSO, enterprise operation auditing and associated governance. Production use requires an Enterprise license, except for the limited frozen-state continuation specified in the terms; isolated non-production development and testing are also permitted.</p><p>An Enterprise license activates features, not redistribution, resale, third-party hosting, SaaS/API operation, OEM or white-label rights. Unactivated or activated status, free third-party access and source modifications do not create exceptions; there is no separate commercial or hosting authorization to purchase. Internal hosted conversations are not third-party hosting services. Your own independent code and output are not subject to the EE license merely because You use MAR. The full scope, exceptions and contribution terms are in <code>ee/LICENSE</code>.</p>',14)])])}const h=t(a,[["render",o]]);export{p as __pageData,h 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.Dwsi-ffA.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"}'),r={name:"en-US/getting-started/npm-quick-start.md"};function s(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>The terminal dependency is pinned to <code>node-pty@1.2.0-beta.18</code>, which includes prebuilt files for Linux x64/arm64, macOS x64/arm64 and Windows x64/arm64. On the verified Linux x64 target, its default installation does not require GCC, make or Python, including program and HOME paths with spaces. Do not set <code>npm_config_build_from_source=true</code> or globally skip installation scripts: the former forces compilation, while the latter may leave other dependencies unprepared. Other native dependencies or targets without matching prebuilds may still need build tools. Included prebuilds do not establish full Quick Start validation for those platforms.</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><p>After an unsuccessful first registration, stop and restart <code>run</code>. If <code>node.json</code> contains only a registration token and no identity, Quick Start reuses an unused valid token or replaces an expired unused token while preserving allowed roots and data settings. <code>QUICK_START_NODE_BOOTSTRAP_RECOVERY_REQUIRED</code> means the token was consumed or its state cannot be confirmed; Quick Start will not register another Node automatically. Keep <code>node-data/node.json</code> and restore the existing identity from a backup, or first inspect and resolve the previous registration in the management page. Do not simply delete the configuration or data directory. Partial identity fields produce a configuration error rather than an automatic identity reset.</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>`,19)])])}const m=a(r,[["render",s]]);export{u as __pageData,m as default};

package/web/docs/assets/en-US_getting-started_npm-quick-start.md.Dwsi-ffA.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"}'),r={name:"en-US/getting-started/npm-quick-start.md"};function s(i,e,d,c,l,p){return t(),o("div",null,[...e[0]||(e[0]=[n("",19)])])}const m=a(r,[["render",s]]);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_file-reference-and-attachment.md.Xzbr8MRS.js

@@ -1 +0,0 @@
-import{_ as t,o as a,c as s,a3 as n}from"./chunks/framework.BHjrhdiC.js";const m=JSON.parse('{"title":"References, Folders, and Attachments","description":"","frontmatter":{"title":"References, Folders, and Attachments","lastUpdated":"2026-10-30T00:00:00.000Z"},"headers":[],"relativePath":"en-US/workbench/file-reference-and-attachment.md","filePath":"en-US/workbench/file-reference-and-attachment.md"}'),r={name:"en-US/workbench/file-reference-and-attachment.md"};function o(i,e,c,d,l,h){return a(),s("div",null,[...e[0]||(e[0]=[n('<h1 id="references-folders-and-attachments" tabindex="-1">References, Folders, and Attachments <a class="header-anchor" href="#references-folders-and-attachments" aria-label="Permalink to &quot;References, Folders, and Attachments&quot;">​</a></h1><p>Type <code>@</code> to search Workspace files and folders. Selecting a result adds a removable Composer tag rather than inserting a path into the message body. References are sent to the Agent as resource inputs and hidden in the sent message. The Agent reads the original resources through its normal tools and permissions; references are not uploaded, copied, or subject to attachment cleanup.</p><p>In regular work mode, the same <code>@</code> picker also offers registered main Sessions in the current Node and Workspace. Matching Sessions appear before files, without type-switching tabs. Type <code>@session</code> or <code>@session keyword</code> to search only Sessions. A bare <code>@</code> shows the first Sessions; enter a path to search files. Each source shows only its first results, so refine the query when more are available. The current Session and child Sessions are excluded. Hosted conversations and shared-session entries do not expose the ordinary Session directory.</p><p>Selecting a Session works like selecting a file: it removes the query at the caret and adds a removable Session reference tag without inserting markup into the body. The tag retains the Session ID and its name at selection time. Session and file references are sent together as XML resource inputs and hidden in the displayed message. Selecting the same Session twice does not duplicate it; different Sessions with matching names remain distinct by ID. Up to 128 Session, file, and folder references can be selected together and restored with the current Workspace draft. Click a tag to remove it, or press Backspace with an empty body to remove the last reference. Editing a queued message&#39;s body preserves reference metadata. References do not import history, send collaboration messages, or automatically read the source Session. Any actual read still uses the Agent&#39;s existing tools and permissions.</p><p>Use the attachment action for files outside the Workspace. The first message accepts up to five files, each larger than zero and no larger than 5 MiB, with a combined limit of 10 MiB. Wait for every upload to complete before sending.</p><p>When pasted clipboard text reaches either 100 lines or 10,000 characters, Composer automatically creates a TXT attachment while preserving the existing draft.</p><p>In regular Workspaces and hosted conversations, BMP attachments are converted to PNG in the browser before upload, preserving their resolution. The attachment name changes to <code>.png</code>; your local source file is unchanged. Both the source and the converted file must fit within 5 MiB, and the image must not exceed 16 megapixels. Images are not automatically resized. If conversion fails or exceeds a limit, save a smaller PNG and add it again. PNG, JPEG, GIF, and WebP are not converted.</p><p>Sent image attachments appear as thumbnail cards without filename text or filename tooltips; other attachments appear as file icons and names. Click an image to enlarge it in a dialog, or Ctrl/Cmd+Click to open a separate window. If a thumbnail cannot load, it falls back to an image placeholder; clicking still checks whether the attachment is available. Other files use the normal Workspace preview. Supported images are also supplied through the Agent&#39;s native visual input, not just as paths.</p><h2 id="attachment-retention" tabindex="-1">Attachment retention <a class="header-anchor" href="#attachment-retention" aria-label="Permalink to &quot;Attachment retention&quot;">​</a></h2><ul><li>Sent files remain available while the Session is preparing, queued, or executing work, then for 30 minutes after it becomes idle.</li><li>An accepted follow-up message pauses cleanup and starts a fresh interval when the Session becomes idle again. Viewing history, switching Sessions, or opening previews does not extend retention.</li><li>The message&#39;s file list remains after cleanup, but clicking reports &quot;File has expired&quot;. Upload the file again if needed. Normal Node shutdown also removes temporary attachments, so old preview URLs are not guaranteed across restarts. In regular Workspaces, MAR Agent <a href="./sessions#automatic-continuation-after-orderly-shutdown">orderly shutdown handoffs</a> retain unsent attachment content and prepare it again during recovery.</li><li>Completed uploads that have not been sent expire after one hour. Removing an attachment deletes its temporary upload early.</li></ul><p>References and attachments never grant additional access. Check the selected tags before sending, verify missing paths in the Workspace file tree, and do not upload credentials or secret files. Next: <a href="./files">Browse, search, and manage files</a>.</p><p>Attachments are stored under <code>temp-files/</code> in the Node private data directory, without creating a Workspace <code>.mar</code> directory or changing Git ignore rules. Message attachments remain available for preview and download while retained, but cannot be edited as Workspace files.</p>',12)])])}const f=t(r,[["render",o]]);export{m as __pageData,f as default};

package/web/docs/assets/en-US_workbench_file-reference-and-attachment.md.Xzbr8MRS.lean.js

@@ -1 +0,0 @@
-import{_ as t,o as a,c as s,a3 as n}from"./chunks/framework.BHjrhdiC.js";const m=JSON.parse('{"title":"References, Folders, and Attachments","description":"","frontmatter":{"title":"References, Folders, and Attachments","lastUpdated":"2026-10-30T00:00:00.000Z"},"headers":[],"relativePath":"en-US/workbench/file-reference-and-attachment.md","filePath":"en-US/workbench/file-reference-and-attachment.md"}'),r={name:"en-US/workbench/file-reference-and-attachment.md"};function o(i,e,c,d,l,h){return a(),s("div",null,[...e[0]||(e[0]=[n("",12)])])}const f=t(r,[["render",o]]);export{m as __pageData,f as default};

package/web/docs/assets/en-US_workbench_files.md.C5byBZOZ.js

@@ -1 +0,0 @@
-import{_ as t,o as a,c as o,a3 as i}from"./chunks/framework.BHjrhdiC.js";const f=JSON.parse('{"title":"Browse, Search, and Manage Files","description":"","frontmatter":{"title":"Browse, Search, and Manage Files","lastUpdated":"2026-11-05T00:00:00.000Z"},"headers":[],"relativePath":"en-US/workbench/files.md","filePath":"en-US/workbench/files.md"}'),r={name:"en-US/workbench/files.md"};function n(s,e,l,d,c,h){return a(),o("div",null,[...e[0]||(e[0]=[i('<h1 id="browse-search-and-manage-files" tabindex="-1">Browse, Search, and Manage Files <a class="header-anchor" href="#browse-search-and-manage-files" aria-label="Permalink to &quot;Browse, Search, and Manage Files&quot;">​</a></h1><p>Files shows the selected Workspace as a lazily loaded tree. Files and folders are clickable, and more actions appear when you hover over a row.</p><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><p>The Workspace must be online and readable. Creating, renaming, moving, or deleting also requires file-system permission for the Node service account and run access to the resource.</p><h2 id="steps" tabindex="-1">Steps <a class="header-anchor" href="#steps" aria-label="Permalink to &quot;Steps&quot;">​</a></h2><ol><li>Select <strong>Files</strong>, expand a folder, and select a file. Text, Diff, images, PDF, Office, video, and audio open in one file-tab strip; every tab shows its file name with a full-path tooltip, while its content page keeps independent state. The × in a tab closes that file only. <strong>Close file window</strong> in the upper-right corner closes all file tabs and returns to the workbench, or closes the browser window in a companion file window. Unsaved edits require confirmation first; canceling any confirmation keeps all tabs open. <code>Ctrl+W</code> / <code>Alt+W</code> closes the active file tab; <code>Esc</code> / <code>Ctrl+Shift+W</code> / <code>Alt+Shift+W</code> closes the whole file window. Esc first dismisses the topmost find panel, menu, or settings dialog. Mobile browser Back also closes the whole window; canceling an unsaved-change confirmation keeps it open. Companion file pages and tab-free rendered previews use the same behavior. Ctrl combinations require the browser to deliver the key event; use Alt as an alternative. Additional entries load automatically near the bottom of an expanded directory; retry in place if loading fails. Use <strong>Filter displayed items</strong> to filter currently loaded files and folders by name or relative path; clear it to restore the tree. Filtering does not read folders that have not been expanded.</li><li>Use the <strong>All</strong>, <strong>Workspace</strong>, <strong>Session</strong>, <strong>File</strong>, and <strong>Symbol</strong> tabs in Quick Open. Workspaces match display names only, not paths or Node names; Sessions match the titles of loaded sessions in the current Workspace. All results are ranked by match strength first, with ties ordered as Workspace, Session, File, then Symbol; definitions precede references when Symbol scores tie. Enter a complete name to find a symbol: definitions can appear before references finish loading. Selecting a Session opens it in the current Workspace. Selecting a symbol or file immediately opens its preview without switching the Aside tool. The file tree expands its ancestors and selects the target in the background, then reveals it when Files is shown. Selecting a Workspace switches to or opens its tab. For duplicate file names, add space-separated terms to match the relative path, such as <code>app src</code> for <code>src/app.ts</code>; term order does not matter. You can enter <code>foo.ts:12</code> for a root-level file to jump to a line. The current Workspace&#39;s path index is built on demand; the first use may show “Preparing the index”. Each result type shows its own progress, failure, or timeout. If results are incomplete, refine the query; failure details and Retry are available. <strong>Search</strong> finds file contents and can open the matching line. It searches plain text by default; select <strong>Use Regular Expression</strong> above the search box before running a pattern search. Invalid patterns show an error.</li><li>Long file and folder names are abbreviated in the tree. Hover a row to see its complete relative path. The open file remains selected in the tree.</li><li>Hover over a row and select <code>…</code>. A file can be downloaded, copied as a relative or absolute path, renamed, or deleted. A folder also supports creating files or folders and uploading files. <strong>Copy absolute path</strong> copies the full path on the Node host; for the root, it copies the actual Workspace root path. This action is unavailable until the root path is known. When an authenticated loopback direct connection confirms that the browser and current Node are on the same device, <strong>Open in local file manager</strong> also appears. Windows opens a folder or selects a file, macOS opens a folder or reveals a file in Finder, and Linux opens the containing folder for a file. The Node must run in a session with access to the user&#39;s desktop; an unavailable desktop or file manager produces an error.</li><li>Drag a file or folder onto another folder to move it. Existing destinations cannot be overwritten, and a folder cannot be moved into itself.</li><li>A capable Node opens a complete UTF-8 text file in edit mode by default. Change the default to read-only under <strong>Settings &gt; Appearance</strong>, or switch the current preview from its title bar. Use <code>Ctrl/Cmd+S</code> or Save to write, <code>Ctrl/Cmd+F</code> to find, <code>Ctrl/Cmd+H</code> to find and replace in the same panel, and <code>Alt+M</code> to open symbols and jump to a class, function, or heading. Completion uses only the current document and basic language syntax; it is not a project language service. Text larger than 1 MiB remains editable and saveable, but uses plain-text mode without syntax parsing, symbols, or completion to keep browser memory bounded.</li><li>On a Node with code navigation, hold <code>Ctrl/Cmd</code> over a code symbol to identify a jump target. Candidates list definitions before references. Selecting a target opens a new tab at the top of the file preview, focuses and selects the target line. Within the file preview, use <code>Alt+Left</code> / <code>Alt+Right</code> to go back and forward through code jumps and manual file-tab switches, restoring the cursor position; closed tabs are removed from navigation history. The first source preview builds a local index in the background, and a jump waits for that same build if it is still running. TypeScript/JavaScript, Python, Java/Kotlin, Go, Rust, C/C++, and C# are formally supported; other Ctags parsers are best effort. If the symbol index reaches its size limit or code-navigation resources are unavailable on the Node, the navigation area shows a local notice instead of a global error or a misleading no-match result. File browsing, editing, and saving remain available.</li><li>Ctrl/Cmd-click a file to open it in one reusable companion Console window while keeping the conversation visible. The window automatically selects the target Workspace and uses the same full-screen file tabs, editing, saving, find, and code-navigation capabilities as the main window. Later opens accumulate or activate files in that Console without reloading it or creating more windows; <code>Ctrl+R</code> keeps it in file-window mode and opens the most recently opened file. Right-click text or Git Diff content for Copy, Paste, and Reload; Paste is unavailable for read-only content, and reloading unsaved edits requires confirmation. Rendered Markdown uses a separate page without file tabs, while ordinary Markdown opens as source text first.</li><li>For a Markdown file, use the preview icon in its title bar to open a rendered page. The independent page always uses a light appearance, regardless of the console theme, with a print-friendly A4 body; refresh the browser to update its content. Preview settings can enable a browser-wide text watermark; its enabled state and text are stored only in this browser. There is no theme selector. Mermaid diagrams are supported; relative links and images remain limited to the current Workspace, while <code>http</code>/<code>https</code> images load directly in the browser.</li><li>HTML/HTM files still open as source by default. Use <strong>Preview</strong> in the file menu, the source preview button, or <code>Ctrl/Cmd+Shift+V</code> to show the saved version in the Aside browser; this does not save drafts. The source window is temporarily hidden while its tabs and drafts remain available via <strong>Open source</strong>. Wait for any save to finish before previewing. A Workspace HTML link in a conversation opens in the browser; Ctrl/Cmd-click opens a rendered page in a new window. Ctrl/Cmd-click in Files still opens the source window. The first preview opens a closable Browser tab alongside sessions to the right of the fixed tools; no Browser tab appears before that. It shows one file at a time, replacing the previous page. The header keeps the file name, with icons to reload, open source, or open in an external browser. Close the tab with × without discarding source drafts; reopen the source from Files. Preview from a companion source window remains a separate page. HTML can run scripts, load resources in its directory and descendants, and send files externally. Preview trusted files only. An administrator can configure a separate HTTPS preview origin; otherwise the Console origin is used and <strong>HTML runs with your signed-in permissions, without isolation from the workbench</strong>. A separate origin requires DNS, TLS, and a reverse proxy to the Server preview route. Cross-origin content cannot deliver keyboard events to the Console; focus the preview header before using close shortcuts.</li></ol><p>Standalone rendered Markdown/HTML pages retain the browser&#39;s native context menu instead of the Copy, Paste, and Reload menu used by ordinary file pages.</p><p>File and Diff read failures show a short reason and <strong>Retry</strong> inside their content area, keeping the file title and close action without a duplicate global error message. Retry reads the same target without adding a file tab. Files and Git list failures likewise stay in their own lists with a retry action. Unsupported or failed previews offer download instead; a binary Diff or a Diff without displayable text can open the file preview when available.</p><p>The unified preview supports code and text, common images, PDF, DOCX, XLSX, PPTX, common video, and audio. The workbench renders PDF pages itself and does not depend on the browser&#39;s built-in PDF viewer. PDF and media are read on demand. Modern Office files are parsed locally in the browser and are not sent to an external preview service. PPTX previews are constrained by both available width and height, preserving the complete slide ratio in very wide or short windows. Legacy DOC, XLS, and PPT files and other unsupported formats keep a download action. A damaged or oversized Office file may also fall back to download.</p><p>Legacy text previews recognize BOM-marked UTF-16 and automatically try GB18030 for known text files when UTF-8 decoding fails. Damaged text can fall back to UTF-8 with replacement characters. The preview identifies fallback decoding and always remains read-only; it does not convert or overwrite the source file. Unknown binary formats still fall back to download. Git Diff displays the patch returned by Git rather than recomputing differences from decoded previews; a non-UTF-8 worktree does not suppress a text patch, but Git-reported binary differences remain unsupported for text comparison.</p><p>In ordinary Work mode, chat file and image links support absolute paths readable by the Node service account, including session image directories outside the Workspace. Relative paths still resolve within the current Workspace. Absolute paths are for read-only preview and download; they do not expand the file tree, search, or write scope and do not apply to hosted conversations. <strong>Users with Workspace access can read other host files available to the Node service account by their absolute paths; Workspaces and allowed roots are not file confidentiality boundaries.</strong> When sharing a Node, isolate sensitive data through the service account and operating-system file permissions.</p><p><strong>Success:</strong> The preview title matches the selected tree path, and refreshing the tree shows the real file-system state.</p><h2 id="troubleshooting" tabindex="-1">Troubleshooting <a class="header-anchor" href="#troubleshooting" aria-label="Permalink to &quot;Troubleshooting&quot;">​</a></h2><ul><li>If canceling or removing a task reports that temporary upload cleanup could not be confirmed, the task stays visible instead of silently disappearing. Retry or ask an administrator to check the Node&#39;s temporary uploads. Refreshing the page does not confirm cleanup.</li><li>Workspace direct uploads verify the complete file&#39;s SHA-256; a mismatch leaves the target unchanged. An interruption after upload starts reports an error, without automatic retry, reauthorization, or a new upload through the Server. Click Retry yourself; after refreshing the page, select the same unchanged source file with the same name and size. Fresh authorization then resumes from the continuous offset confirmed by the Node. Expired temporary uploads and Node restarts require a new upload. Server upload fallback remains available before direct upload starts; existing download and preview fallback behavior is unchanged.</li><li>Operation denied: check the Node service account permissions, Workspace boundary, and resource authorization.</li><li>Regular-expression search unavailable: regular-expression mode requires the Node-bundled <code>rg</code> resource. Reinstall or upgrade that Node, then try again; plain-text search can still fall back when the resource is missing.</li><li>Long file name: hover the tree row to confirm its full relative path before moving or deleting it.</li><li>Read-only preview: write-incompatible Nodes, truncated text, Diff, and Git History content remain read-only. Nodes below the business baseline must first be <a href="./../deployment/upgrade">upgraded</a>.</li><li>Save conflict: an Agent, terminal, or another window changed the file. Discard the local edit, reopen the file, review the latest content, and edit again; the workbench does not force an overwrite.</li><li>A Diff opens instead of a file: chat file changes and Git text changes open Diff by default. Supported images, audio, video, PDF, and Office formats in Git Changes / Git History open directly in a preview of the corresponding worktree or selected commit. Unknown binary files and unsupported formats retain fallback actions.</li><li>Office preview fails: verify that the file is DOCX, XLSX, or PPTX rather than a legacy file with a renamed extension, then use Download if needed.</li><li>Dragging has no effect: refresh the tree and confirm the destination is writable and inside the Workspace.</li><li>A new tab is blocked: allow pop-ups for MyAgentRoam. Executable HTML on the Console origin may use the current account&#39;s existing permissions.</li></ul><p>File operations act on the real Node directory. There is no hidden recycle bin. Check Git Changes or create a backup before renaming, moving, overwriting, or deleting. Next: <a href="./git-changes">Git Changes and Diff</a>.</p>',15)])])}const u=t(r,[["render",n]]);export{f as __pageData,u as default};

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

@@ -1,3 +0,0 @@
-import{_ as o,o as a,c as d,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"}'),s={name:"getting-started/npm-quick-start.md"};function n(r,e,c,i,p,l){return a(),d("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>终端依赖固定为 <code>node-pty@1.2.0-beta.18</code>，随包提供 Linux x64/arm64、macOS x64/arm64 和 Windows x64/arm64 预编译文件；已验证的 Linux x64 默认安装无需为 node-pty 安装 GCC、make 或 Python，程序目录和 HOME 含空格也可使用。不要设置 <code>npm_config_build_from_source=true</code> 或全局跳过安装脚本；前者会强制源码编译，后者可能使其他依赖未正确准备。其他原生依赖或无匹配预编译文件的平台仍可能需要构建工具；包内有预编译文件不代表该平台的完整 Quick Start 已验证。</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><p>首次注册失败后，可停止并重新 <code>run</code>：若 <code>node.json</code> 只有注册令牌、尚无身份，系统会复用未使用的有效令牌，或替换已过期但未使用的令牌，保留允许目录和数据配置。若报告 <code>QUICK_START_NODE_BOOTSTRAP_RECOVERY_REQUIRED</code>，说明令牌已使用或状态无法确认，系统不会自动重复登记。请保留 <code>node-data/node.json</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>`,19)])])}const k=o(s,[["render",n]]);export{u as __pageData,k as default};

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

@@ -1 +0,0 @@
-import{_ as o,o as a,c as d,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"}'),s={name:"getting-started/npm-quick-start.md"};function n(r,e,c,i,p,l){return a(),d("div",null,[...e[0]||(e[0]=[t("",19)])])}const k=o(s,[["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_file-reference-and-attachment.md.CSLMm-nL.js

@@ -1 +0,0 @@
-import{_ as a,o,c as t,a3 as c}from"./chunks/framework.BHjrhdiC.js";const f=JSON.parse('{"title":"@ 引用文件、文件夹与附件","description":"","frontmatter":{"title":"@ 引用文件、文件夹与附件","lastUpdated":"2026-10-30T00:00:00.000Z"},"headers":[],"relativePath":"workbench/file-reference-and-attachment.md","filePath":"workbench/file-reference-and-attachment.md"}'),r={name:"workbench/file-reference-and-attachment.md"};function i(l,e,d,n,s,p){return o(),t("div",null,[...e[0]||(e[0]=[c('<h1 id="引用文件、文件夹与附件" tabindex="-1">@ 引用文件、文件夹与附件 <a class="header-anchor" href="#引用文件、文件夹与附件" aria-label="Permalink to &quot;@ 引用文件、文件夹与附件&quot;">​</a></h1><p><code>@</code> 引用和附件不同：引用告诉 Agent 使用当前工作区中的文件或文件夹；附件随当前消息上传独立内容。</p><h2 id="步骤" tabindex="-1">步骤 <a class="header-anchor" href="#步骤" aria-label="Permalink to &quot;步骤&quot;">​</a></h2><ol><li>在 Composer 输入 <code>@</code>，从快速索引选择文件或文件夹；键盘上下选择时列表会保持当前定位。选中后显示可删除的文件标签，不把路径写入正文。</li><li>引用文件夹时确认它确实是本次任务所需范围，避免给 Agent 无关的大目录。</li><li>需要发送工作区外内容、图片或独立文本时使用附件按钮，而不是伪造路径引用。</li><li>发送前检查引用标签与附件列表；删除错误项后再发送。</li></ol><p>普通工作模式的同一 <code>@</code> 列表还可选择当前 Node 和 Workspace 中已登记的主会话，匹配会话排在文件之前，不设置类型切换 Tab；输入 <code>@session</code> 或 <code>@session 关键词</code> 可只查会话。裸 <code>@</code> 显示首批会话，文件搜索需要输入路径；每种来源只显示首批结果，结果过多时请细化关键词。当前会话与子会话不列入候选，托管对话和分享入口不提供普通会话目录。</p><p>选择会话与选择文件一样：移除光标处的查询词，显示可删除的会话引用标签，不把标记写入正文。标签保存会话 ID 和选择时的名称，发送时与文件引用统一作为 XML 资源输入交给 Agent，消息回显不显示引用块。相同会话不会重复添加，同名会话按 ID 区分；会话、文件与文件夹引用合计最多 128 项，并随当前工作区草稿恢复。点击标签可以移除；正文为空时按 Backspace 移除最后一个引用。编辑排队消息的正文会保留引用元数据。引用不会导入历史、发送协作消息或自动读取来源会话；是否读取仍由 Agent 及其原有工具和权限决定。</p><p>从剪贴板粘贴达到 100 行或 10000 字符的长文本时，Composer 会自动生成 TXT 附件；输入框原有正文保持不变。</p><p>普通工作区和托管对话上传 BMP 图片时，浏览器会保持原分辨率转换为 PNG，附件名变为 <code>.png</code>，本地原文件不变。源文件及转换结果均不能超过 5 MiB，图片不能超过 1600 万像素；不会自动缩小。转换失败或超限时，请另存为较小的 PNG 后重新添加。PNG、JPEG、GIF、WebP 不受此转换影响。</p><p><strong>成功标志：</strong> Composer 显示文件引用标签或上传附件列表。发送后，<code>@</code> 引用不在消息中回显；图片附件以不带文件名文字或文件名悬停提示的缩略图卡片回显，其他附件以文件类型图标和文件名列出。点击图片直接在弹窗中放大预览，Ctrl/Cmd+Click 可在独立窗口打开；缩略图加载失败时回退为图片占位提示，点击后仍会重新检查附件是否可用。其他文件使用普通文件预览。图片同时作为视觉输入交给支持图片的 Agent，不只是路径引用。</p><h2 id="附件保留" tabindex="-1">附件保留 <a class="header-anchor" href="#附件保留" aria-label="Permalink to &quot;附件保留&quot;">​</a></h2><ul><li>已发送附件按当前会话保留：准备、排队和执行期间不会清理；会话空闲后保留 30 分钟。</li><li>在期限内继续发送有效消息会暂停清理，再次空闲后重新计时。查看历史、切换会话或打开预览不会延长时间。</li><li>过期后消息中的文件列表保留，但点击提示“文件已过期”；需要继续使用时请重新上传。Node 正常停止也会清理临时附件，不保证原预览地址在重启后保留；普通 Workspace 的 MAR Agent 在<a href="./sessions#正常停止后的自动续作">正常停止交接</a>中会保留尚待发送的附件内容，恢复时重新准备。</li><li>未发送的已完成上传保留 1 小时，移除附件会提前删除暂存文件。<code>@</code> 引用不上传、不复制、不参与附件清理，仍指向工作区中的原文件。</li></ul><h2 id="失败排查" tabindex="-1">失败排查 <a class="header-anchor" href="#失败排查" aria-label="Permalink to &quot;失败排查&quot;">​</a></h2><ul><li>找不到文件：先在当前 Workspace 文件树确认路径；只能引用已授权目录内的内容。</li><li>附件上传失败：检查浏览器网络和提示，重新选择文件；不要把密钥文件作为附件发送。</li></ul><p>安全提示：<code>@</code> 引用不是权限提升，附件也不应包含凭据或应提交到 Git 的秘密。</p><p>下一步：<a href="./files">浏览、搜索与管理文件</a>。</p><p>附件保存在 Node 私有数据目录的 <code>temp-files/</code>，不会在 Workspace 中创建 <code>.mar</code> 或修改 Git 忽略规则。消息中的附件仍可预览和下载，但不能作为 Workspace 文件编辑；预览只在附件保留期间有效。</p>',16)])])}const m=a(r,[["render",i]]);export{f as __pageData,m as default};

package/web/docs/assets/workbench_file-reference-and-attachment.md.CSLMm-nL.lean.js

@@ -1 +0,0 @@
-import{_ as a,o,c as t,a3 as c}from"./chunks/framework.BHjrhdiC.js";const f=JSON.parse('{"title":"@ 引用文件、文件夹与附件","description":"","frontmatter":{"title":"@ 引用文件、文件夹与附件","lastUpdated":"2026-10-30T00:00:00.000Z"},"headers":[],"relativePath":"workbench/file-reference-and-attachment.md","filePath":"workbench/file-reference-and-attachment.md"}'),r={name:"workbench/file-reference-and-attachment.md"};function i(l,e,d,n,s,p){return o(),t("div",null,[...e[0]||(e[0]=[c("",16)])])}const m=a(r,[["render",i]]);export{f as __pageData,m as default};

package/web/docs/assets/workbench_files.md.B5xE7YGc.js

@@ -1 +0,0 @@
-import{_ as o,o as a,c as i,a3 as t}from"./chunks/framework.BHjrhdiC.js";const h=JSON.parse('{"title":"浏览、搜索与管理文件","description":"","frontmatter":{"title":"浏览、搜索与管理文件","lastUpdated":"2026-11-05T00:00:00.000Z"},"headers":[],"relativePath":"workbench/files.md","filePath":"workbench/files.md"}'),d={name:"workbench/files.md"};function l(r,e,c,s,n,p){return a(),i("div",null,[...e[0]||(e[0]=[t('<h1 id="浏览、搜索与管理文件" tabindex="-1">浏览、搜索与管理文件 <a class="header-anchor" href="#浏览、搜索与管理文件" aria-label="Permalink to &quot;浏览、搜索与管理文件&quot;">​</a></h1><p>文件面板以懒加载树展示当前 Workspace。文件和文件夹可点击，鼠标悬停可展开更多操作。</p><h2 id="前置条件" tabindex="-1">前置条件 <a class="header-anchor" href="#前置条件" aria-label="Permalink to &quot;前置条件&quot;">​</a></h2><p>当前 Workspace 在线可读；创建、重命名、移动和删除还需要 Node 服务账号文件权限及当前用户的资源运行权。</p><h2 id="步骤" tabindex="-1">步骤 <a class="header-anchor" href="#步骤" aria-label="Permalink to &quot;步骤&quot;">​</a></h2><ol><li>在右侧选择“文件”，展开文件夹并点击文件。文本、Diff、图片、PDF、Office、视频和音频都会在同一文件 Tab 条中打开；每个 Tab 显示文件名和完整路径提示，内容页可以独立切换并保留自己的状态。Tab 内的 × 只关闭对应文件，顶部右侧的“关闭文件窗口”会关闭全部文件 Tab 并返回工作台；在独立文件窗口中则关闭该浏览器窗口。存在未保存修改时会先确认，取消任一确认会保留全部 Tab。<code>Ctrl+W</code>／<code>Alt+W</code> 关闭当前文件 Tab，<code>Esc</code>／<code>Ctrl+Shift+W</code>／<code>Alt+Shift+W</code> 关闭整个文件窗口；Esc 优先关闭最上层查找、菜单或设置弹窗。移动端浏览器返回同样关闭整个文件窗口，取消未保存确认后保持当前窗口。独立文件页与无 Tab 的独立渲染预览沿用相同逻辑；Ctrl 组合只在浏览器交付按键时生效，可使用 Alt 替代。文件树按目录逐层加载；滚动接近已展开目录的底部时自动继续读取，失败可在原位重试。使用顶部“显示过滤”可按名称或相对路径筛选当前已加载的文件和目录，清空输入即可恢复原树；该过滤不会读取尚未展开的目录。</li><li>使用“快速打开”的“全部 / 工作区 / 会话 / 文件 / 符号”页签查找目标。工作区只按展示名称匹配，不匹配路径或 Node 名称；会话只匹配当前工作区已加载会话的标题。所有结果先按匹配度排序，仅在同分时按工作区、会话、文件、符号排列；同为符号时定义先于引用。符号需输入完整名称；定义可先出现，引用稍后补充。选择会话会在当前工作区打开该会话；选择符号或文件后会立即打开预览，不会切换右侧工具；文件树在后台展开上级目录并选中目标，显示“文件”时会定位到该位置。选择工作区会切换或打开对应标签。文件名重复时，可以输入空格分隔的词进一步匹配相对路径，例如 <code>app src</code> 定位 <code>src/app.ts</code>，词的顺序不限；根目录文件也可输入 <code>foo.ts:12</code> 跳到指定行。当前工作区的路径索引按需建立，第一次使用可能显示“正在准备索引”。不同结果类型独立显示进度、失败或超时；结果不完整时可缩小查询，有失败详情和重试入口。使用“搜索”页签可按文件内容查找，并从结果跳到命中行。默认按普通文本搜索；需要模式匹配时，勾选搜索框上方的“使用正则表达式”后再搜索。无效模式会提示错误。</li><li>文件或文件夹名称过长时，会在文件树中省略显示；将鼠标悬停在行上可查看完整相对路径。当前预览文件会在树中保持选中样式。</li><li>将鼠标移到文件或文件夹行上，点击 <code>…</code>：文件可下载、复制相对路径、复制绝对路径、重命名或删除；文件夹可新建文件、新建文件夹、上传、复制相对路径、复制绝对路径、重命名或递归删除。“复制绝对路径”复制 Node 主机上的完整路径，根目录复制 Workspace 的实际根路径；根路径尚未取得时该项不可用。当浏览器与当前 Node 通过已认证回环直连确认位于同一台设备时，菜单还会显示“在本机文件管理器中打开”：Windows 打开文件夹或选中文件，macOS 打开文件夹或在访达中显示文件，Linux 对文件打开其所在目录。此操作要求 Node 运行在可访问用户桌面的会话中，无桌面或系统文件管理器不可用时会显示错误。</li><li>把文件或文件夹拖到另一个文件夹可移动；不能覆盖同名目标，也不能把文件夹移动到自身或其下级目录。</li><li>支持写入的 Node 会让完整 UTF-8 文本默认以编辑模式打开；可在“设置 &gt; 外观”改为默认只读，也可在预览标题栏临时切换。按 <code>Ctrl/Cmd+S</code> 或保存按钮写入，按 <code>Ctrl/Cmd+F</code> 查找，按 <code>Ctrl/Cmd+H</code> 在相同工具栏中查找替换，按 <code>Alt+M</code> 打开符号表并跳到类、函数或章节。补全只使用当前文件和语言基础语法，不是项目级语言服务。超过 1 MiB 的文本仍可编辑和保存，但会使用纯文本模式并关闭语法解析、符号表和补全，以控制浏览器内存占用。</li><li>支持代码导航的 Node 中，按住 <code>Ctrl/Cmd</code> 悬停代码符号可识别可跳转项；单击后候选先显示定义，再显示引用。选择目标会在文件预览顶部新增标签页、定位并选中目标行。在文件预览内按 <code>Alt+Left</code> / <code>Alt+Right</code> 可在代码跳转位置及手动切换的文件 Tab 之间后退、前进，并恢复光标位置；关闭的 Tab 不再进入历史导航。首次打开源码会在后台建立本地索引，构建期间的跳转会等待同一次构建完成。正式支持 TypeScript/JavaScript、Python、Java/Kotlin、Go、Rust、C/C++ 和 C#；其他 Ctags 内置语言仅尽力支持。 符号索引达到容量上限或 Node 的代码导航资源不可用时，导航区域会显示轻量说明，不弹全局错误，也不会显示为“未找到定义”；文件浏览、编辑和保存仍可使用。</li><li>按 Ctrl/Cmd 点击文件可在同一个复用的独立 Console 窗口中打开文件，便于同时保留聊天窗口；窗口会自动选择对应 Workspace，并使用与主窗口完全相同的全屏文件 Tab、编辑、保存、查找和代码导航能力。后续打开直接在该 Console 的文件 Tab 条中累计或激活，不刷新窗口，也不会持续创建新窗口；在独立窗口按 <code>Ctrl+R</code> 刷新仍保持文件窗口并打开最近打开的文件。文本正文和 Git Diff 正文右键提供复制、粘贴、重新加载；只读内容不可粘贴，重新加载未保存的编辑内容需先确认。Markdown 的渲染预览使用另一个无文件 Tab 的独立页面，普通打开仍以源码文本页开始。</li><li>打开 Markdown 文件后，使用标题栏的预览图标在新页面查看渲染结果。独立页固定使用浅色，不跟随控制台主题，正文采用适合打印的 A4 排版，可通过浏览器刷新更新内容。预览设置可开启全浏览器共用的文本水印，启用状态和文本只保存在本浏览器，不提供主题选择。Markdown 支持 Mermaid 图表；相对链接和图片只能访问当前 Workspace 内的文件，<code>http</code>/<code>https</code> 外部图片会由浏览器直接加载。</li><li>HTML/HTM 文件普通打开仍显示源码；文件菜单“预览”、源码页预览图标或 <code>Ctrl/Cmd+Shift+V</code> 在侧栏浏览器显示已保存的版本，不会自动保存草稿。源码窗口暂时收起，文件 Tab 与草稿保留；使用“打开源码”返回。保存进行中请等待完成后再预览。会话中的工作区 HTML 链接直接在浏览器预览，Ctrl/Cmd 点击在新页面渲染；文件树的 Ctrl/Cmd 点击仍打开独立源码窗口。首次预览时，浏览器会与会话一样出现在固定工具右侧，未预览时不显示该标签。浏览器每次只显示一个文件，切换文件会替换页面；标题栏保留文件名，右侧图标可重新加载、打开源码或在外部浏览器中打开。点击标签的 × 关闭预览，不丢弃源码草稿；可从文件面板再次打开源码。独立源码窗口的预览仍在独立页面打开。页面可运行脚本、加载所在目录及下级资源，亦可向外网发送文件。仅预览信任的文件。管理员可配置独立 HTTPS 预览域名；未配置时使用控制台域名，<strong>HTML 脚本以当前登录权限运行，不与工作台隔离</strong>。独立域名需要 DNS、证书及指向 Server 预览路由的反向代理。跨域正文不能向控制台交付按键；预览页面关闭快捷键需先聚焦标题区。</li></ol><p>Markdown/HTML 独立渲染页保留浏览器原生右键菜单，不使用普通文件页的复制、粘贴和重新加载菜单。</p><p>文件或 Diff 读取失败会在对应内容区内显示简短原因和“重试”，保留文件标题与关闭入口，不重复弹出全局错误消息。重试会重新读取同一个目标，不新增文件 Tab；Files 或 Git 列表读取失败也在各自列表内提示并重试。不支持预览或渲染失败时使用下载入口；二进制或没有可显示文本的 Diff 可在允许时打开文件预览。</p><p>统一预览窗口支持代码与文本、常见图片、PDF、DOCX、XLSX、PPTX、常见视频和音频。PDF 由工作台自身渲染，不依赖浏览器是否启用内置 PDF 阅读器；PDF 与媒体按需读取，现代 Office 文件在浏览器本地解析，不会发送到第三方预览服务。PPTX 会同时受可用宽度和高度约束，在超宽或较矮的窗口中保持完整幻灯片比例。旧版 DOC、XLS、PPT 及其他不支持的格式会保留下载入口。单个 Office 文件过大或内容损坏时也会提示改为下载。</p><p>旧编码文本预览会识别带 BOM 的 UTF-16；已知文本文件无法按 UTF-8 解码时，自动尝试 GB18030，损坏的文本可回退为带替换字符的 UTF-8 显示。预览会标明回退解码且始终只读，不转换或覆盖源文件；未知二进制格式仍降级为下载。Git Diff 展示 Git 实际返回的 patch，不根据解码后的预览重新计算差异；工作树不是 UTF-8 不会阻止已有文本 patch 展示，但 Git 判定为二进制的差异仍不做文本比较。</p><p>普通工作模式中的聊天文件链接和图片链接支持 Node 服务账号可读的绝对路径，包括 Workspace 外的会话图片目录；相对路径仍指向当前 Workspace。绝对路径仅用于只读预览和下载，不扩大文件树、搜索或写入范围，也不适用于托管对话。<strong>拥有 Workspace 访问权的用户可通过绝对路径读取 Node 服务账号可读的其他宿主文件；Workspace 和允许根目录不是文件保密边界。</strong> 共享 Node 时应使用合适的服务账号和操作系统文件权限隔离敏感数据。</p><p><strong>成功标志：</strong> 预览标题与树中选中路径一致，刷新树后仍显示真实文件系统结果。</p><h2 id="失败排查" tabindex="-1">失败排查 <a class="header-anchor" href="#失败排查" aria-label="Permalink to &quot;失败排查&quot;">​</a></h2><ul><li>若取消或移除时提示未能确认临时上传已清理，任务会保留而不是静默消失。请重试或联系管理员核查 Node 临时上传状态；刷新页面不会确认清理结果。</li><li>Workspace 文件直传会校验完整文件的 SHA-256，校验失败不会替换目标。已开始的上传中断会报错，不会自动重试、重新授权或改走 Server 从零重传。请主动点击重试；刷新页面后需重新选择同名、同大小且内容未变的源文件，再经新授权从 Node 确认的连续进度恢复。临时上传过期或 Node 重启后需重新上传。开始直传前不可用时仍可回退 Server 上传；下载与预览的既有回退行为不变。</li><li>操作被拒绝：检查 Node 服务账号权限、Workspace 边界和资源授权。不支持写入的 Node、截断文本、Diff 和 Git 历史内容会自动保持只读；低于业务基线的 Node 需先<a href="./../deployment/upgrade">升级</a>。</li><li>正则内容搜索不可用：正则模式依赖 Node 随包提供的 <code>rg</code> 资源。重新安装或升级该 Node 后重试；普通文本搜索仍可在资源缺失时回退执行。</li><li>保存冲突：文件已被 Agent、终端或另一窗口修改。关闭当前修改并重新打开文件，确认最新内容后再编辑；工作台不会强制覆盖。</li><li>预览是 Diff：聊天内文件更改和 Git 文本变更默认进入 Diff；Git Changes / Git History 中支持的图片、音视频、PDF 和 Office 格式直接预览对应工作树或选定提交中的文件。未知二进制及不支持的格式保留降级入口。</li></ul><p>删除和覆盖外的文件操作直接作用于 Node 上的真实目录，没有隐藏回收站；执行重命名、移动或删除前先确认 Git 状态或备份。下一步：<a href="./git-changes">查看 Git Changes 与 Diff</a>。</p><h2 id="常见失败" tabindex="-1">常见失败 <a class="header-anchor" href="#常见失败" aria-label="Permalink to &quot;常见失败&quot;">​</a></h2><ul><li>拖动后无变化：目标目录可能无写权限、属于边界外路径或在拖动过程中发生变更；刷新树后重新选择。</li><li>文件名很长：将鼠标悬停在树行上查看完整相对路径，再执行删除或移动。</li><li>新标签无法打开：允许浏览器弹出新标签。执行型 HTML 在当前域名运行时可能使用当前登录用户已有的权限。</li><li>Office 预览失败：确认文件是 DOCX、XLSX 或 PPTX，而不是仅修改了扩展名的旧格式；仍可使用下载按钮在本机应用中打开。</li></ul>',17)])])}const T=o(d,[["render",l]]);export{h as __pageData,T as default};