用途
luvus-module 是 luvus（AI 编程代理的任务控制台）的模块开发规范。模块是 luvus 的插件，用于扩展侧边栏停靠面板（dock）、Luvus Bar 小组件、事件钩子、右键菜单动作、独立窗格、模块设置以及 worktree 提供者等能力。
主要能力
模块是一个目录，内含 luvus-module.toml 清单。清单可声明以下表项，每项对应一个 argv 命令（列表形式，按原样执行，工作目录为模块目录）：
[[docks]]：预留侧边栏停靠区，通过ui dock push填充内容。[[bars]]：预留一行 Luvus Bar 小组件，通过luvus bar push发布结构化分段内容。[[startup]]：会话启动且套接字监听后执行一次（以及启用时执行），用于在重启后重绘 dock/bar 内容。[[events]]：在 luvus 事件触发时运行，支持的 on 值包括 workspace.created/closed、tab.created/closed/moved、pane.created/closed/forked/moved、pane.agent_status_changed、agent.hook 以及 task./lease. 等。[[actions]]：可运行动作，带 contexts 时可出现在窗格/工作区/节点/代理/标签页的右键菜单中，否则仅限 CLI 调用。[[panes]]：运行命令的真实窗格，通过luvus module pane open <id> <entrypoint>打开。[[settings]]：在设置→模块中渲染的配置项，支持 bool/string/number/enum 类型，值通过环境变量传给命令。[worktree_provider]：可选的固定创建/移除命令，从 stdin 读取版本化 JSON 请求，创建时须在 stdout 输出{"path":"/absolute/worktree/path"}，移除时须无输出且成功退出。
命令通过扁平化的 LUVUS_* 环境变量接收上下文（如 LUVUS_MODULE_ID、LUVUS_MODULE_ROOT、LUVUS_WORKSPACE_ID、LUVUS_PANE_*、LUVUS_SETTING_<KEY> 等），无需解析 JSON；也可读取 LUVUS_MODULE_CONTEXT_JSON 获取完整快照。
使用方式
命令内部可调用 luvus CLI（使用 "$LUVUS_BIN_PATH" 保证同一二进制），通过 $LUVUS_SOCKET_PATH 与运行中的服务器通信。模块可用的方法包括：
luvus ui dock push --id <dock> --rows <json>：填充停靠区，行支持 text、dot、tone、spans、action、value、menu。luvus bar push --id <widget> --content <json>：发布结构化分段（text、symbol、state、badge、progress、spacer、separator）。luvus ui notification push、luvus ui toast：发布通知或提示。luvus ui agent-title push --titles <json>：发布代理侧边栏标题。luvus ui sidebar、ui dock list/move、tab rename/list、module settings等。- 以及完整 CLI，如
luvus pane split/run/send、luvus agent ...、luvus git ...。
本地测试流程：
luvus module link <path-to-module-dir>
luvus module list
luvus module log [<id>]
luvus module run <id> <action>
luvus module enable <id> | disable <id>
分享模块可通过 luvus module install <owner>/<repo> 从 GitHub 克隆、构建并注册；仓库打上 luvus-module 主题标签后可通过 luvus module search 找到。
适用场景
最适合需要为 luvus 构建或调试模块的开发者，例如创建侧边栏停靠面板、Luvus Bar 小组件、事件钩子、右键菜单动作、自定义窗格或 worktree 提供者。
限制
- 无 SDK 和脚本引擎，模块仅通过清单声明命令实现。
- 每个命令输出上限 64 KiB，同时最多运行 32 个命令。
- 身份环境变量（LUVUS_MODULE_ID、LUVUS_MODULE_TOKEN、套接字路径）由 luvus 注入且不可覆盖，令牌不得记录或持久化。
- worktree_provider 命令同步执行，不得在服务器等待期间回调 luvus CLI/API；stdout 仅支持规定的 JSON 格式，人类可读日志应写入 stderr。