luvus

Luvus

使用 Luvus 的语义 CLI 和 UHP 来委派工作、控制实时工作区，并构建明确的工具集成。该技能不会添加服务、事件循环或轮询进程。

优先处理 =target 委派

只有当 =target message 中的 = 是一行中第一个非空白字符、target 不含空格，且其后有消息时，才将其视为 Luvus 委派。不要将方程式、赋值或正文中的 = 视为委派。Codex 技能调用仍使用 $skill-name 语法。

示例：

• =reviewer inspect this diff 会将 inspect this diff 发送给名为 reviewer 的 Agent。
• =7 run the migration 会将消息发送到窗格 7。
• =codex add tests 会将消息发送给名称或类型唯一匹配 codex 的 Agent。

对于每一条委派行：

1. 直接运行 luvus agent send <target> "<message>"，不要使用 --wait。agent send 会权威地解析实时名称、数字窗格 ID 和唯一的 Agent 类型。不要先运行 agent list。
2. 如果成功，接受返回的窗格、Agent、名称和状态，告知用户工作已发送到何处，然后结束本轮。不要重新读取或轮询。
3. 仅在出现 not_found 或 ambiguous_target 后，才运行一次 luvus agent list，以显示当前可选项。未经用户选择，绝不要猜测或重试其他目标。
4. 对于任何其他错误，直接报告，不要列出 Agent。发送失败后，绝不要接手或在本地执行已委派的任务。只有用户明确提出请求时，才启动 Agent。

自然语言委派请求遵循相同的流程。不要仅仅因为其他 Agent 可能有所帮助就进行委派。

只选择一个会话

绝不要直接运行 luvus，因为它会启动或连接到 TUI。为便于阅读，以下示例使用 luvus。请替换为此处选定的客户端。

在 Luvus 窗格内

当 LUVUS_ENV=1 时，控制继承的会话：

• 必须提供 LUVUS_BIN_PATH、LUVUS_SOCKET_PATH 和 LUVUS_PANE_ID。
• 调用指定的 LUVUS_BIN_PATH。让它使用继承的套接字。
• 将 LUVUS_PANE_ID 保留为调用方和默认分屏锚点。
• 绝不要用默认值、PATH 查找结果或其他 Luvus 会话替换继承的套接字或二进制文件。

只有在用户已经处于该会话中，并明确要求委派或控制时，才能操作继承的会话。

Luvus 外部操作

使用已安装的生产版 Luvus 客户端：

• 使用当前 shell 的命令查找机制解析一次 luvus，例如在 Unix 上使用 command -v luvus，或在 PowerShell 中使用 (Get-Command luvus).Source。
• 本次请求后续操作都调用该解析出的确切路径。这支持通过 Cargo、Homebrew、install.sh 或其他由 PATH 管理的方式安装的 Luvus。
• 保留显式配置的 LUVUS_HOME 或 LUVUS_SOCKET_PATH。 同样保留 LUVUS_SESSION。如果用户明确指定了服务器会话，则在每条相关的 Luvus 命令中直接传入 --session <name>。 如果这会选择另一台服务器，Luvus 会丢弃继承的窗格 ID，因为窗格标识仅在创建它的会话中有效。 不要先列出会话，也不要静默回退到 default。 否则，让已安装的发布版二进制文件使用其生产环境默认路径 $HOME/.luvus/luvus.sock。
• 如果缺少已安装的命令，绝不要用 LUVUS_BIN_PATH 或仓库构建版本替代。
• 只有在尝试执行 Luvus 操作时，命令查找未找到 luvus 客户端，才报告未安装 Luvus 并停止。提供以下任一受支持的命令：curl -fsSL https://luvus.dev/install.sh | sh、brew install RizRiyz/luvus/luvus 或 cargo install luvus。不要提前显示此指引，也不要在套接字、权限、服务器或其他命令失败时显示。只有后续查找成功后，才能表示 Luvus 可用。
• 仅当用户要求启动或使用 Luvus，且启动是正常的必要步骤时，才启动生产服务器。

在 Codex 应用中，访问本地套接字可能需要工作区沙箱外的权限。请为选定的 Luvus 客户端请求该权限。不要将未经批准的沙箱访问失败描述为服务器离线。只有在获批的命令无法连接后，才报告生产服务器离线。

整个请求期间使用同一个选定的二进制文件和套接字。

管理命名服务器会话

命名会话是独立的 Luvus 服务器和 PTY 树，并非工作区。仅当用户明确要求检查或管理服务器会话时，才使用以下命令：

luvus session list
luvus session attach <name>
luvus session stop <name>
luvus session delete <name>
luvus --session <name> pane list

pane list 会发现该会话中所有工作区和标签页的窗格 ID，且不会更改焦点。添加 --current-tab 可将结果限制为活动标签页。

session attach 会启动或连接到 TUI。绝不要仅为测试会话是否存在而运行它。session stop 会结束该命名服务器中的所有窗格。删除前，先列出一次会话，要求提供确切的已停止会话名称，并取得明确授权。绝不要删除 default，也绝不要用工作区命令替代服务器会话命令。

管理已保存的 SSH 机器

已保存的机器是一个 SSH 配置，由选定的本地命名会话拥有，并选择一个远程命名会话。它不是工作区，打开远程工作区不得创建更多配置或会话。切换本地命名会话会重新加载该会话独立的工作区树和机器目录。

即使当前处于远程机器工作区，TUI 标题栏中的会话控件始终管理所属的本地命名会话。不要将其解读为机器会话选择器，也不要声称切换本地会话会改变已保存机器的远程会话首选项。

提出更改前，先进行只读检查：

luvus machine list
luvus machine show <id>
luvus machine status <id>
luvus machine sessions <id>

machine status 会验证已在运行的选定服务及其工作区映射；它不会安装或启动任何内容。machine add 和 machine enable 是前台变更操作，可能会连接主机并启动尚未运行的选定服务。切勿将密码或密钥作为 CLI 数据传入。使用用户的 OpenSSH 目标地址或配置别名，并且仅在用户明确授权时使用 --install。使用 machine add ... --session <name> 选择非默认远程会话。

除非用户明确启动 uhp access --machines，否则不会提供机器 UHP 方法；变更操作还需要 --control。不要根据普通会话的 UHP 访问权限推断机器管理权限。

使用快速命令路径

• 直接运行用户请求的语义命令。不要在前面例行添加 help、ping、状态或列表调用。
• 委派任务时，直接调用 agent send。仅在出现 not_found 或 ambiguous_target 后，才将 agent list 用作恢复手段。
• 仅在语法不确定或命令不受支持时使用 help。
• 复用线程中已返回的有效 ID、名称和结果。
• 若成功的变更响应明确指出目标，就信任该响应。除非响应不完整，否则不要立即重新读取相同状态。
• 优先使用一次范围较广的列表，而不是对每个项目分别调用状态命令。
• 使用有时限的 Luvus 等待，不要使用 shell 休眠或轮询循环。

大多数命令会返回包含 .result 或 .error 的 JSON。从这些结果中解析确切的 ID、索引、路径、名称和状态。切勿根据侧边栏中的位置推断目标。

有意识地选择 CLI 或 UHP

对于常规的 Luvus 控制和委派，请使用语义 CLI。它是执行单个操作的最短路径，不应被原始协议或终端输入取代。

仅当用户明确要求 Luvus API、harness 集成、能力或架构发现、带序列的事件、带边界的快照、修订版本安全自动化、委派访问权限或终端后端流式传输时，才使用 Universal Harness Protocol 1.0。对于这类工作，应发现已安装的服务，而不是根据文档或发行版本号假定其受支持：

luvus uhp capabilities
luvus uhp schema
luvus uhp snapshot

这些发现调用是无预检规则的例外，因为它们定义了实时协议契约。常规 CLI 操作之前不要运行这些调用。 luvus uhp proxy 会将一条以换行符分隔的 JSON 请求从标准输入转发到所选的本地服务。发送前，请根据已安装的架构验证方法和参数。

luvus uhp access 是面向显式远程提供方或客户端的、与传输方式无关的前台边界。它会为经过身份验证的环回端点输出一条机器可读描述符，且不会创建公共监听器。仅当用户明确授权了文档所述的有限控制面时，才使用 --control。仅在请求的访问时段内保持命令运行，绝不要在没有可信加密传输的情况下暴露其环回端点。

对于有状态的 UHP 自动化：

1. 读取能力和限制。
2. 从已知事件序列开始订阅，并获取带边界的快照。
3. 按顺序仅应用后续事件。
4. 出现序列缺口、溢出、重新连接、服务代次变更或 resync_required 事件后，重新获取快照。
5. 对可能冲突的变更，使用已公布的修订版本或 if_revision。
6. 当实时能力公布了 agent.start、agent.prompt、layout.apply、workspace.move_block 和 diff.note.apply 等原子方法时，优先使用这些方法。

默认端点信任本地所有者，不是公共 TCP 服务。仅为明确委派的 harness 创建范围受限且会过期的 UHP 令牌。绝不要打印、持久化或记录令牌密钥，也绝不要授予超出集成所需范围的权限。终端观察和控制流仅用于明确的 harness 或远程客户端工作。控制权具有排他性、时限限制，任务结束时必须释放。对于常规自动化，优先使用 agent prompt、pane read 和其他语义路由。

有关方法族、事件恢复、令牌、修订版本、布局操作和终端流，请在已安装时阅读 uhp-control.md。如果 luvus skill show 是唯一可用的文件，上述规则仍然足够。

委派和管理 Agent

通过以下方式解析活动 Agent：

luvus agent list
luvus agent get <target>

目标可以是实时名称、窗格 ID 或唯一的 Agent 类型。如果某个类型对应多个目标，请让用户选择或指出窗格。绝不要猜测。

要从受管理的窗格启动并命名同级 Agent：

luvus agent start reviewer --kind codex --timeout 30

从外部终端操作时，先选择一个实时锚点：

luvus agent start reviewer --kind codex --anchor <pane-id> --timeout 30

直接尝试带锚点启动。只有当返回的语法或用法错误表明不支持 --anchor 时，才使用兼容的两命令路径，并传入 pane split 返回的新窗格 ID。不要预先运行帮助命令：

luvus pane split <anchor-pane-id> --no-focus
luvus agent start reviewer --kind codex --pane <new-pane-id> --timeout 30

省略方向标志可沿锚点窗格较长的一侧拆分。在拆分命令或带锚点的启动命令中传入 --right 或 --down 可指定方向。绝不要同时使用 --anchor 和 --pane。

使用 agent send 发送工作内容，不要直接向窗格发送文本并按 Enter：

luvus agent send reviewer "Review the current diff"

除非用户明确要求等待，或下一步操作必须依赖结果，否则不要添加 --wait。在受管理的窗格中，请说明调用者身份，并在异步交付有帮助时要求工作 Agent 完成后回复：

luvus agent name lead
luvus agent send reviewer "Review the diff. When done, run: luvus agent send lead 'done: <summary>'"

无等待地交接后，结束本轮。回复消息会开启新一轮。外部终端没有调用者窗格，因此不要凭空编造一个。 使用 --wait 时，agent prompt（以及 agent send）要求先出现新的 working 或 blocked 状态转换，之后请求的 --until 状态才能结束等待。 状态未变、标题闪烁或仅输出安静，都不能结束等待。 observed_state 记录首次活动状态转换；status 是当前状态。 绝对超时时间 --timeout 覆盖这两个阶段（默认 300 秒）。如果未观察到状态转换，超时将返回 matched:false、evidence:"timeout" 和 null observed_state。如果窗格或终端退出，将返回 agent_not_running，并在 error.data 中包含 pane、queued、submitted、observed_state、reason:"pane_closed"、baseline_revision 和 content_revision。等待期间发生超时或窗格退出时，CLI 退出码为 2。取消、超时和退出都会释放待处理的等待所有权。 不使用 --wait 时，即时响应 submitted:true、evidence:"queued" 保持不变，并省略 observed_state。提交仍仅表示输入已进入队列；状态转换不能确认提示词文本已被处理。超时或响应丢失后不要自动重发，因为已排队的输入可能会执行。 对于 agent.send 和 agent.prompt，检测到提示词被阻塞的证据时，会返回 agent_not_ready，且不排队任何输入。Claude 和 Codex 还要求有明确证据表明其输入编辑器处于活动状态。使用 --strict（UHP strict:true）可要求任何 Agent 都必须有明确的输入编辑器证据；没有检测器的 Agent 将返回 agent_not_ready。不启用严格模式时，其他 Agent 保留其原有的 Unknown 证据回退行为。请先读取可见屏幕，再判断是否获准执行明确的 agent keys 操作。

请求等待时，请设置有界等待时间并读取有界结果：

luvus agent send reviewer "Review the diff" --wait --timeout 300
luvus agent read reviewer --lines 120

对于 agent start 的身份识别，将 idle、done、working 和 blocked 视为已识别状态；这些状态本身不能证明提示词已就绪。 unknown 不能证明任务已完成，但不会推翻匹配的身份。当 agent start 返回 ready: true 时，无需再次查询状态，即可接受其 名称、窗格和类型。发送工作后如需等待指定的生命周期状态转换，请使用 wait agent-status，而不要用它来识别启动身份。 如果多个终止状态中的任意一个都应解除工作流阻塞，请重复使用 --status，或传入以逗号分隔的状态集合。未知选项和位置参数会被拒绝，而不是忽略。

对于被阻塞的 Agent：

1. 运行 luvus agent get <target>。
2. 运行 luvus agent read <target> --source visible --lines 120。
3. 找出确切的审批请求或问题。
4. 仅当用户请求授权此操作时，才发送 agent keys。

agent keys 仅接受已识别的 Agent 窗格和由已知键名组成的非空列表。 它会在将一个有序操作加入队列前验证整个列表；如果有任何条目无效，就不会发送任何内容；如果目标已关闭，则返回 send_failed。

对于必须与已检查屏幕相匹配的 UHP 交互，请将 agent.read 与 source:"visible" 配合使用，并在 agent.keys 参数中将其 content_revision 作为 if_content_revision 传入，同时传入其 terminal_id。visible 读取的是实时屏幕，而非窗格的回滚视口，因此即使有人滚动查看较早的轮次，它仍然有效。版本号是非负整数；终端 ID 必须恰好由 32 个小写十六进制字符组成。这两个字段可以成对省略；如果只提供其中一个或格式错误，则返回 invalid_request。延迟窗格的 terminal_id:null，无法进行围栏校验。无法获取的读取快照将返回空文本和 null 坐标。 服务端会检查这对坐标，并在用于捕获文本的同一引擎锁下将按键加入队列。content_revision_conflict 表示没有按键加入队列：请重新读取并评估已授权的操作，切勿重试同一对坐标。通用响应中的 revision / 请求中的 if_revision 是全局事件坐标，而非窗格的内容计数器。不提供这对坐标时，行为保持不变。较旧的服务端会省略这些坐标或拒绝新字段；只有在可以接受不设栅栏的旧式准入时，才省略这对坐标。这些是 UHP 参数，不是 CLI 标志。

此栅栏仅覆盖队列准入。已加入队列的输入以及尚未被观察到的子进程端变更不在其覆盖范围内。光标/SGR 输出可能会使这对坐标失效，即使对话文本看起来没有变化。

控制窗格、标签页和工作区

在目标尚未确定的写入操作之前，使用以下读取路由：

• luvus workspace list
• luvus tab list
• luvus pane list
• luvus pane status <id>
• luvus pane read <id> --lines 120
• luvus search <query>

当用户提供稳定的从 0 开始的工作区索引时，直接执行请求的变更操作。只有在需要将名称、路径或侧边栏位置解析为索引，或收到 not_found 后需要显示当前选项时，才运行 workspace list。复用线程中已有的当前列表结果，不要在这些已记录的命令之前运行 help。重命名只会更改标签，不会更改文件夹；固定只会更改侧边栏显示顺序，不会更改 API 索引：

luvus workspace rename <workspace-index> <name>
luvus workspace pin <workspace-index>
luvus workspace unpin <workspace-index>

关闭最后一个项目不会停止客户端，也不会使其失去 shell。Luvus 会立即在用户的主目录中创建一个中性工作区和终端。其侧边栏路径仍是已存储的主目录根路径，而 terminal_cwd 则跟随当前聚焦的窗格。因此，workspace list 返回空列表表示发生了异常的恢复或启动失败，并不能证明服务端已离线。用户指定了特定项目时，请使用 workspace open <path>。

从受管理的窗格操作时，将 LUVUS_PANE_ID 用作调用方或拆分锚点。从外部终端操作时，请选择实时状态返回的明确窗格。

若要在明确指定的窗格旁运行普通命令而不抢占焦点：

luvus pane split <anchor-pane-id> --no-focus
luvus pane run <new-pane-id> "cargo test"
luvus wait output <new-pane-id> --match "test result" --timeout 300
luvus pane read <new-pane-id> --lines 120

只有在通过 agent get 确认支持的实时 Agent 后，才对其进行原生分叉。分叉会继承源对话，但会获得自己的新会话：

luvus agent get <target>
luvus agent fork <target> [--name <alias>] [--no-focus]

目前原生分叉支持 Claude、Grok、Codex、Kilo Code、Pi 和 OMP。返回时，请原样报告 unsupported_agent、session_unknown 或 spawn_failed。不要用 pane split、agent start 或 resume 近似替代失败的分叉，因为这些路径无法保证对话副本独立。

只有在解析出窗格 ID 后，才可转置拆分布局：

luvus pane transpose <pane-id>

这只会切换紧邻该窗格的拆分布局，同时保留焦点、缩放状态、比例和实时终端。单窗格标签页会返回 changed:false。响应丢失后，请先检查布局再重试：此切换操作不是幂等的，转置两次会恢复原状。

只有在解析出现有窗格的 id，并列出该窗格所在工作区中的目标标签页后，才可移动该窗格。标签页编号从 1 开始：

luvus pane move <pane-id> --tab <tab-number>
luvus pane move <pane-id> --new-tab

只有在 luvus tab list 确认了源位置和最终位置后，才可在当前工作区中重新排序标签页：

luvus tab move <from> <to>

安全控制高级功能界面

即使单独安装 SKILL.md，本节内容也仍然完整。如果可以使用 advanced-control.md，请阅读该文件以查看精简的命令索引。缺少该文件并不构成阻碍，也绝不意味着可以猜测或降低安全检查要求。

使用以下读取路由来解析状态和精确目标：

• 文件和 Git：luvus files tree、luvus git status、 luvus git branches、luvus git log
• DIFF：luvus diff list、luvus diff get <path>、 luvus diff note list
• 工作树：luvus worktree list
• 编排：luvus task list、luvus task get <id>、 luvus lease list
• 模块：luvus module list、luvus module info <id>、 luvus module actions、luvus module settings <id>、 luvus module log <id>
• 主题和 UI：luvus theme list、luvus bar list、 luvus ui dock list

仅当不确定所请求的变更语法时，才运行 luvus help all。 这与较旧版本的 Luvus 兼容。在更改高级功能界面之前：

• 在打开文件、展示路径、刷新文件树或打开 Git 视图之前，先检查文件和 Git。
• 在打开或添加、编辑、解决、移除、应用或发送评审备注之前，先检查确切的 DIFF 层和文件。移除备注和向 Agent 发送反馈都需要明确授权。
• 在创建、打开或移除 worktree 之前，先列出 worktree。移除需要明确授权和确切路径。如果移除返回 worktree_in_use，报告其窗格、任务和租约。除非用户明确授权停止列出的工作，否则绝不使用 --force 重试。
• 在认领、启动、更新、完成、释放、删除或合并之前，先检查任务和租约的所有权、依赖项、门控条件、受分配者以及路径租约。task merge 会串行进入 luvus/integration：等待其响应，将 merged 视为终态，并在重试前解决报告的冲突。基于分支的依赖项只有在合并后才会解除其依赖任务的阻塞。task start 默认使用隔离的 mode=worktree；显式指定 mode=workspace 会在共享检出中创建无分支的任务标签页，且无法合并。task start 会在创建任一工作进程前检查租约，因此重试前先解决返回的 lease_conflict。租约用于协调声明的路径，但不会对共享检出进行沙箱隔离。task release 会将活动任务重新排入队列并释放其路径租约；它不会停止工作进程窗格。暂存工作进程时，若要保留操作员当前的工作区、标签页、窗格焦点和缩放状态，请使用 task start ... --no-focus。 task retry <id> 是对 done、failed、review 或 blocked 工作进行明确重新尝试的操作。它会保留旧窗格、worktree、分支、输出和备注。先检查依赖任务，因为任何依赖任务离开队列后，重试都会被拒绝。自动化拥有的任务会根据原始运行快照创建新的不可变运行。 task add --prompt <text> 或 --prompt-file <path> 会存储详细的工作进程说明；只有手动任务仍在队列中且未分配时，task update 才能替换该说明。启动工作进程前，先检查已存储的提示词。 创建任务时，会将其绑定到所选工作区的项目。在 Luvus 窗格内执行命令时，会自动提供该工作区。在窗格外执行时，如果有多个仓库或多个非 Git 项目处于打开状态，请传入 --workspace-id。若聚焦的 Git 项目只有一个，即使旁边有非 Git 启动目录工作区，也仍然明确无歧义。task next 会留在该项目内；租约只会在同一项目内发生冲突，包括该项目的 Git worktree 之间。 仅使用 task update --note 报告工作进度。task heartbeat --context-used <0..1> 表示已消耗的大模型上下文窗口比例，而不是任务完成进度；0.6 表示已消耗 60%。上下文窗口使用情况未知时，请省略心跳。
• 更改 Agent 日程安排之前，先检查 automation.list、automation.get 和 automation.history。创建、更新、启用、禁用、删除或手动运行自动化都需要明确授权。先预览日历触发条件，保留用户的 IANA 时区，对可重试的创建/运行请求使用幂等键，绝不要将自动化变成任意的定时 shell 命令。禁用只会阻止未来的触发；不会停止正在运行的 ORCH 任务或窗格。 变更成功后需等待账本检查点。在出现 persistence_failed 或响应丢失后，先检查状态，并使用相同的幂等键重试；不要假定定义不存在，也不要创建重复日程。存储恢复后，不会自动重新启动启动前失败的触发实例。 target=new_worker 是持久化默认值。只有在目标窗格、终端生命周期、Agent 和工作区身份均已准确发现时，才使用 active_agent；将 delivered 视为输入队列证据，而非工作已完成的证据；窗格关闭或服务重启后，不要重复使用绑定到进程的目标。标示为 binding=durable 的目标，只能恢复同一私有原生对话。收到 needs_rebind 时，先检查预期窗格，再使用 automation.rebind；绝不要替换为其他会话。
• 更改模块状态之前，先检查模块元数据、操作、设置和日志。安装、卸载和会造成重大影响的设置变更都需要明确授权。
• 安装主题前，先验证主题来源。没有明确授权时，不要卸载当前主题或获取远程主题。
• CLI 小组件命令使用 luvus bar ...；UHP 方法系列为 ui.bar.*。更改位置或内容之前，先检查小组件和停靠栏。除非能满足用户请求，否则避免更改侧边栏、停靠栏、通知、toast、bar 或焦点。
• 用户要求打开 Mission Control 时，直接使用 luvus mission open [<workspace>]。可选的工作区索引从 0 开始；省略索引则以当前活动工作区为目标。对于 UHP 自动化，使用工作区范围（默认值）或显式的所有工作区范围调用 mission.snapshot，在不更改 UI 的情况下检查数据；使用 mission.refresh 显式刷新用量；仅使用 mission.open 更改可见标签页。保留 mission.refresh 返回的 refresh_id，并读取 mission.snapshot，直至同一 server_generation 中的 refresh.completed_id 达到该 ID。usage:null 表示未知，而不是零；使用 usage_status 和 summary.usage_coverage 说明部分结果。scope:"all" 仍仅限于所选的具名会话。
• Luvus 内置 Agent 检测功能。luvus integration install 用于管理可选的原生会话恢复钩子，不得仅为让 Agent 显示在侧边栏中而使用。仅在用户明确要求集成的生命周期管理时，才安装或移除集成。
• 对于 Antigravity CLI，luvus integration install antigravity 会添加精确的对话身份，以便恢复。它仅对会话有效；Agent 状态仍以原生屏幕检测为准。
• 对于 OpenCode，luvus integration install opencode 会检测 V1 或 V2，并通过匹配的集成契约添加精确的 TUI 本地根会话所有权。 opencode2 是规范 Agent opencode 的兼容别名。绝不要从其实时数据库推断 V2 会话 ID。
• 对于 Devin，luvus integration install devin 会添加一个会话启动钩子，该钩子仅报告用于重启恢复的精确会话 ID。检测仍由原生功能负责。不要从其私有数据库推断会话 ID； luvus agent resume <id> 无法找到 Devin 会话，因此如果没有该集成，则在确切 ID 已知时，使用 luvus pane report --agent devin --session <id> 绑定窗格。
• 对于 Hermes，luvus integration install hermes 会添加精确的逐窗格会话所有权，以便重启恢复。检测仍由原生功能负责，但 Luvus 不会扫描 Hermes 的私有历史记录存储。
• 对于 Letta Code，luvus integration install letta 会添加一个不产生额外输出的会话启动钩子，该钩子仅报告确切的对话 ID。检测仍由原生功能负责。Luvus 不会检查 Letta 的记忆、凭据、对话或云状态，也不会宣称 Letta 支持原生分支或计划自动化。
• 仅在需要实时监控时订阅事件。条件满足后即停止，绝不保留无界事件流。

了解配置和不熟悉的界面

使用 luvus help <topic> 查看已安装版本的命令语法，使用 luvus uhp capabilities 和 luvus uhp schema 查看所选服务当前的 自动化契约。若要了解此处未涵盖的配置、安装、概念或界面，请先阅读 https://luvus.dev/agent-readme.md，再通过 https://luvus.dev/llms.txt 仅打开相关文档页面。

Luvus 的偏好设置位于 ~/.luvus/ 下的 config.json 中，或位于明确指定的 LUVUS_HOME 下。调试构建使用 ~/.luvus-dev/。优先通过 Settings 界面进行经过验证的实时更改；手动编辑时保留未知字段，且绝不要替换为生产、 开发或命名会话路径。当网站描述的版本较新时，以已安装的二进制文件和当前选定的 运行中服务为准。

安全

• 写入时使用明确的目标。当前聚焦的窗格可能属于另一个客户端。
• 除非收到更改要求，否则保留焦点和非活动窗格的滚动位置。
• 将提示词、路径、Unicode、引号、美元符号、等号和换行符作为参数原样保留。避免不必要地通过 sh -c 增加一层插值。
• 未获得明确授权并进行只读目标检查前，不要关闭窗格、标签页或工作区，不要移除 worktree、删除或合并任务、卸载模块，也不要覆盖影响重大的设置。
• 切勿将停止或重启 Luvus 服务作为常规控制步骤。仅在收到明确请求，并警告对方这会影响所有受管理的窗格后，才可执行。