用途
lmstudio-subagents 的核心用途是把工作卸载到本地 LM Studio 模型上执行，以减少来自付费提供商的 token 使用量，从而降低成本。资料明确指出，应在质量足够时使用本地模型，并避免用于网页、专有或高风险任务。
主要能力
- 列出本地可用模型并检查其加载状态。
- 根据任务需求选择模型，考虑因素包括视觉能力（capabilities.vision）、嵌入类型（type=embedding）、上下文长度（max_context_length）等。
- 可选地显式加载模型，或依赖首次对话时的即时加载（JIT）。
- 调用聊天 API 执行任务，支持温度、最大输出 token 等参数。
- 支持有状态对话：聊天返回 response_id，可作为 previous_response_id 传入以维持状态。
- 可选地卸载模型，使用 instance_id（来自 loaded_instances[].id 或聊天返回的 model_instance_id）。
使用方式
前置条件：LM Studio 0.4+，服务器运行在 :1234，模型已存于磁盘；可通过 API 加载/卸载（JIT 可选）；脚本需要 Node（使用 curl 也可以）。
完整工作流：
- 步骤 0：预检。执行 GET /api/v1/models，非 200 或连接错误表示服务器未就绪。示例命令： curl -s -o /dev/null -w '%{http_code}' -H 'Authorization: Bearer lmstudio' http://127.0.0.1:1234/api/v1/models
- 步骤 1：列出模型并检查加载状态。执行 GET /api/v1/models，解析 models[]（key、type、loaded_instances、max_context_length、capabilities、params_string）。若某模型的 loaded_instances.length > 0 且适合任务，可跳到步骤 5；否则选择 key 用于聊天（以及可选加载）。记录 loaded_instances[].id 以备可选卸载。
- 步骤 2：模型选择。从 GET 响应中选择 key，作为聊天中的 model（可选加载）。约束：视觉任务看 capabilities.vision；嵌入任务看 type=embedding；上下文看 max_context_length。优先选择已加载的模型（loaded_instances 非空），追求速度选较小模型，追求推理选较大模型；可回退到主模型。可选执行 POST 加载；否则首次聊天时 JIT。
- 步骤 3：加载模型（可选）。可选执行 POST /api/v1/models/load { model, context_length?, ... }。JIT 会在首次聊天时加载；仅在需要特定选项时才显式加载。
- 步骤 4：验证加载（可选）。若显式加载：GET models，确认 loaded_instances。若 JIT：无需验证；首次聊天会返回 model_instance_id、stats.model_load_time_seconds。
- 步骤 5：调用 API。在技能文件夹中执行：node scripts/lmstudio-api.mjs <model> '<task>' [options]。示例： node scripts/lmstudio-api.mjs <model> '<task>' --temperature=0.7 --max-output-tokens=2000 有状态：添加 --previous-response-id=<response_id>。使用 curl：POST /api/v1/chat，请求体包含 model、input、store、temperature、max_output_tokens；可选 previous_response_id。解析：output（type message）-> content；response_id、model_instance_id、stats。脚本输出 content、model_instance_id、response_id、usage。
- 步骤 6：卸载（可选）。可选执行 POST /api/v1/models/unload { instance_id }。instance_id 来自 loaded_instances[].id 或聊天返回的 model_instance_id。JIT+TTL 会自动卸载；需要时再显式卸载。示例命令： curl -s -X POST http://127.0.0.1:1234/api/v1/models/unload -H 'Content-Type: application/json' -H 'Authorization: Bearer lmstudio' -d '{"instance_id": "<instance_id>"}'
适用场景
资料给出的适用场景是：在质量足够时，将任务卸载到本地模型，例如摘要等；同时明确建议避免用于网页、专有或高风险任务。
限制与错误处理
- 模型未找到：从 GET 响应中选择另一个模型。
- API/服务器错误：GET models，检查 URL。
- 输出无效：重试。
- 内存问题：卸载或使用更小的模型。
- 卸载失败：instance_id 必须与 loaded_instances[].id 匹配。
API 细节
- 认证：Bearer lmstudio。
- 列出模型：GET /api/v1/models。
- 加载模型：POST /api/v1/models/load（可选）。
- 卸载模型：POST /api/v1/models/unload { instance_id }。
- 聊天：POST /api/v1/chat，请求体包含 model、input、store、temperature、max_output_tokens；可选 previous_response_id。
- 输出：content、model_instance_id、response_id、usage。
备注
- 需要 LM Studio 0.4+。
- JIT：首次聊天时加载；stats 中包含 model_load_time_seconds。
- 有状态：response_id / previous_response_id。