---

name: llmcmd description: Use when handling terminal-first LLM workflows for text generation, image generation, audio understanding via chat references, text-to-speech generation, video generation, YAML batch tasks, persistent chat sessions, or file-based prompt and reference inputs.

llmcmd

shellus-llmcmd 是一个统一的 LLM 命令行工具，入口命令是 llm。

本手册面向直接调用本项目的 Agent 或终端用户，覆盖当前可用能力、常见参数、配置方法与高频示例。

适用场景

在以下场景使用本技能：

• 需要把文本、图片、音频理解、文本转语音、视频能力统一接入 shell、脚本、自动化流程或 CI
• 需要读取本地文本、图片、文档、音频作为 prompt 或参考输入
• 需要用 chat --edit 按要求直接修改文本文件
• 需要在终端里持久化会话并继续同一轮对话
• 需要通过 YAML 一次编排多条 chat / image / tts / video 任务

安装

pip install shellus-llmcmd

安装后命令名是：

llm

能力概览

模式	用途	常用输入	常用输出
llm chat	文本生成、分析、问答、改写、编辑文件、持久对话、音频理解、视频理解	prompt、@文件、-r 附件、会话文件	stdout、文本文件、会话文件
llm agent	启动 pi coding agent，并复用当前 chat 配置	prompt、--thinking、--session、--tools	pi 交互会话
llm image	图片生成、参考图编辑	prompt、@文件、-r 附件	图片文件
llm tts	文本转语音	prompt、@文件、--voice	wav 文件
llm video	异步视频生成、恢复等待、自动下载	prompt、首帧参考图、任务 ID	视频文件
llm batch	YAML 批量任务编排	tasks.yaml	输出目录内多个结果

常用输入规则

1. 直接写 prompt

llm chat "写一段产品介绍"
pi --help | llm chat "翻译它"
llm image "生成横版海报"
llm tts "请朗读这段欢迎词"
llm video "生成一段海边航拍视频"

2. 使用 @文件

@文件 会把文本文件内容直接读入 prompt，适合长提示词或模板化输入。

llm chat @prompt.txt -o result.md
llm image @prompt.md -o result.jpg
llm tts @script.txt -o speech.wav

3. 使用 -r/--reference

-r/--reference 用于提供参考输入。可传多次。

llm chat "总结这个附件的重点" -r report.pdf
llm chat "对比两张参考图后总结共同特征" -r photo-a.jpg -r photo-b.jpg
llm chat "请转写这段录音" -r meeting.mp3
llm chat "总结这个视频的关键情节" -r demo.mp4
llm image "融合两张参考图的风格生成图片" -r person.jpg -r style.jpg -o result.jpg
llm video "生成产品展示短片" -r first-frame.jpg --seconds 8 -o demo.mp4

补充规则：

• chat 中，图片参考会作为图片输入，文本类附件优先内联为文本，音频与视频附件按 file 发送
• 非交互 chat 会读取管道 stdin，并作为 [标准输入] 文本块发送；命令行 prompt 作为处理指令
• image 中，参考输入按文件附件处理
• video 当前仅使用第一张参考图作为首帧参考

llm chat

用于文本生成、分析、问答、改写、结构化提取、文件编辑、持久化对话，以及音频理解、视频理解。

基本示例

llm chat "写一段产品介绍"
llm chat @prompt.txt -o result.md
pi --help | llm chat "翻译它"
llm chat "总结重点" -r article.md -r notes.pdf
llm chat "请转写这段录音并输出标准 SRT 字幕" -r demo.wav -o demo.srt
llm chat "总结这个视频的关键情节并列出时间线" -r demo.mp4
llm chat "根据参考图修正人物外貌描述" --edit prompt.md -r ref.jpg

文件编辑

chat --edit 会按要求修改目标文本文件。

llm chat "把人物脸型改成偏瘦，不要改动其他描述" --edit prompt.md
llm chat "按要求改写" --edit prompt.md -o prompt.v2.md

持久化会话

新增会话参数：

• -s/--session：加载并持久化对话历史，值可为会话名或 .jsonl 路径
• -I/--interactive：进入交互式连续对话；默认仅保存在内存中，配合 -s 才会加载并持久化

示例：

llm chat "继续上一轮结论" -s worklog
llm chat -I
llm chat -I "你是什么模型？"
llm chat -I -s ./sessions/product-review.jsonl

说明：

• --provider 可临时覆盖当前 chat 模式使用的 provider
• --model 与 --provider 同时使用时，会优先在该 provider 下解析模型别名；未命中时直接按原始模型名发送
• -s product-review 会写到当前目录下的 product-review.jsonl
• 单次模式和 -I -s ... 交互模式可共享同一个会话文件
• llm chat -I "首轮问题" 会先发送首轮消息，再进入连续对话
• -I 模式下只有配合 -s 才会回放历史并持续写回；不带 -s 时为纯内存会话
• 当前持久会话聚焦连续文本对话，不与 -r/--edit 组合
• chat -s ... --system ... 与 chat -I -s ... --system ... 会把 system prompt 写入会话历史；再次带 --system 启动同一会话时，只覆盖会话开头连续的 system 消息
• audio 子命令已删除；音频理解与视频理解附件统一使用 llm chat -r

交互式内置命令：

• /clear：清空当前会话
• /model <name>：切换当前模型，并写回 ~/.llm/.env 中的 CHAT_MODEL
• /save <name-or-path>：将当前会话保存到指定文件

交互细节：

• 基于 Textual 全屏 TUI
• Enter 发送
• Shift+Enter 或 Ctrl+J 换行
• 如需终端原生鼠标拖选复制历史消息，需按住终端模拟器修饰键；当前环境实测为按住 Shift

输出行为

• 非交互 chat 会实时把流式文本写到 stdout
• 若 chat 使用图片模型并返回图片，会自动写入文件并显示图片路径

llm agent

用于启动外部 pi coding agent，并复用当前 llmcmd 的 chat 模型、BASE_URL 与 API_KEY 配置。

基本示例

llm agent
llm agent "审查当前仓库里最危险的改动"
llm agent --model qwen3-coder --thinking high
llm agent --session ./pi-session.jsonl --tools read,grep,find,ls

说明

• --provider 可临时覆盖当前 agent 复用的 chat provider
• --model 与 --provider 同时使用时，会优先在该 provider 下解析模型别名；未命中时直接按原始模型名发送
• 这是独立入口，不替换现有 chat -I
• 运行时会在 ~/.llm/pi-agent/ 下生成 pi 所需的 models.json
• models.json 只写 base_url 与 API key 的环境变量名，真实 key 通过子进程环境变量注入
• agent 当前使用 chat 模式配置作为上游来源
• --thinking 会透传给 pi；当值不是 off 时，默认把该模型标记为 reasoning
• --pi-bin 可指定 pi 可执行文件路径
• --session、--session-dir、--no-session、--tools、--no-tools 会原样透传给 pi

llm image

用于图片生成或参考图编辑，支持多图生成。

基本示例

llm image "生成三张海报方案" -n 3 -o poster.jpg
llm image "融合两张参考图的风格生成情侣自拍" -r person.jpg -r style.jpg -o couple.jpg
llm image @prompt.md -r ref.jpg -o output.jpg
llm image @prompts/couple-photo.md -r refs/person-a.jpg -r refs/person-b.jpg -o outputs/couple-photo/result.jpg -n 4
llm image "生成横版海报" --size 2K --aspect 16:9 -o banner.jpg

输出结果示例：

• poster.jpg
• poster_1.jpg
• poster_2.jpg

常用参数

• -n/--count：生成数量
• --provider：临时覆盖当前 image 模式使用的 provider
• --model：临时覆盖当前 image 模式使用的模型
• --size：支持 512 / 1K / 2K / 4K
• --aspect：支持 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 4:5 / 5:4 / 21:9

说明：

• --size 和 --aspect 的实际生效情况取决于图片后端
• -r/--reference 用于提供参考图片或文件
• 图片模型协议选择见 README.md 的 llm image 小节
• --provider 与 --model 同时使用时，会优先在该 provider 下解析模型别名；未命中时直接按原始模型名发送

Agent 判断规则：

• 图片生成或编辑优先使用 llm image
• 图片理解、描述、转写或分析使用 llm chat -r
• 只返回文字时，先检查模型能力、protocol 与网关 endpoint 渠道

llm tts

用于文本转语音，输出 wav 文件。

基本示例

llm tts "请用温和语气朗读这段话" -o demo.wav
llm tts @prompt.txt --voice Kore -o demo.wav

说明：

• --provider 可临时覆盖当前 tts 模式使用的 provider
• --model 与 --provider 同时使用时，会优先在该 provider 下解析模型别名；未命中时直接按原始模型名发送
• --voice 用于指定 Gemini 预置音色名，例如 Kore
• 当前通过 Gemini 原生 generateContent 返回音频 PCM，再封装为 wav

llm video

用于异步视频生成。默认会创建任务、等待完成并自动下载，也支持按任务 ID 恢复等待并下载。

基本示例

llm video "生成一段海边航拍视频"
llm video "生成产品展示短片" -r first-frame.jpg --seconds 8 --size 720x1280 -o demo.mp4
llm video --resume vid_123 -o demo.mp4

说明：

• --provider 可临时覆盖当前 video 模式使用的 provider
• --model 与 --provider 同时使用时，会优先在该 provider 下解析模型别名；未命中时直接按原始模型名发送
• video 默认先创建异步任务，再持续等待完成并自动下载
• 创建成功后会先打印任务 ID，便于中断后用 --resume 恢复
• -r/--reference 当前仅取第一张图作为 input_reference
• 下载固定走 GET /v1/videos/{id}/content

常用参数：

• --seconds：支持 4 / 8 / 12 / 16 / 20
• --size：当前支持 720x1280 / 1280x720 / 1024x1024

llm batch

用于 YAML 批量任务编排。

基本示例

llm batch tasks.yaml

说明：

• --provider 可统一覆盖 batch 内各任务默认使用的 provider

示例：

mode: chat
concurrency: 4
output_dir: outputs

tasks:
  - prompt: "总结下面内容"
    input: article.md
    output: summary.md

  - mode: image
    prompt: "为产品主页生成三张极简横幅图"
    count: 3
    aspect: "16:9"
    output: hero.jpg

完整可复制模板见：examples/batch/full-template.yaml

说明：

• batch YAML 内的相对路径按当前工作目录解析，而不是按 YAML 文件所在目录解析
• 顶层 mode 可为任务提供默认模式
• 顶层 concurrency 控制 batch 内 task 级并发
• 单个任务可通过 mode 覆盖默认值
• 如果定义了 output，始终以 output 为准
• 图片、语音、视频任务未定义 output 时，会按任务序号自动命名为 image-1.jpg、tts-2.wav、video-3.mp4
• aspect 建议写成带引号的字符串，例如 "16:9"，避免 YAML 误解析

配置

配置专题的唯一事实来源是 CONFIGURATION.md。Agent 处理配置相关任务时，应优先读取该文件，再执行命令或修改配置。

默认配置文件：

~/.llm/.env
~/.llm/config.yaml

核心概念：

概念	含义	Agent 处理要点
mode	CLI 任务类型	对应 chat / image / tts / video / batch 等命令入口
provider	上游服务或兼容网关	决定 base_url 与 api_key
model	发给上游的模型名	--model 可能同时切换 provider
protocol	请求协议	完整可选值和解释见 CONFIGURATION.md
reference_transport	参考文件预上传配置	视频或部分网关链路常用

常用运行时覆盖：

CHAT_MODEL=gpt-5.4 llm chat "用更强模型重写这段文案"
IMAGE_MODEL=gpt-image-1 llm image "生成一张横版海报" -o banner.jpg
TTS_MODEL=gemini-3.1-flash-tts-preview llm tts "请朗读一句欢迎词" -o welcome.wav
BASE_URL=https://gateway.example.com/v1 API_KEY=sk-test CHAT_MODEL=gpt-5.4 llm chat "输出一句自检文本"

配置排查顺序：

1. 检查 ~/.llm/config.yaml 是否存在且为合法 YAML。
2. 检查 ${ENV_NAME} 是否能在当前环境或 ~/.llm/.env 中展开。
3. 检查最终 provider 是否有 base_url 与 api_key。
4. 检查 --model 是否命中 alias 或模型名，并确认是否切换了 provider。
5. 检查 protocol 是否属于 CONFIGURATION.md 中列出的可选值，并确认是否适用于当前 mode。
6. 图片任务只返回文字时，优先确认模型是否具备图片生成能力；llm image 不等于任意模型都会返回图片。

最小配置示例：

default_provider: openai
concurrency: 4

modes:
  chat:
    provider: openai
    model: gpt-4.1
  image:
    provider: openai
    model: gpt-image-1
  tts:
    provider: gemini
    model: gemini-3.1-flash-tts-preview
  video:
    provider: reverse-video
    model: sora_t2v_turbo

providers:
  openai:
    base_url: https://api.openai.com/v1
    api_key: ${OPENAI_API_KEY}
    models:
      gpt-4.1:
        type: chat
      gpt-image-1:
        type: image
        protocol: openai-images
      gpt-image-2:
        type: image
        protocol: openai-responses

  gemini:
    base_url: https://generativelanguage.googleapis.com
    api_key: ${OPENAI_API_KEY}
    models:
      gemini-3-pro-image-preview:
        type: image
        protocol: gemini-generate-content
      gemini-3.1-flash-tts-preview:
        type: tts
        protocol: gemini-generate-content

  reverse-video:
    base_url: https://your-newapi.example.com/v1
    api_key: ${REVERSE_VIDEO_KEY}
    models:
      sora_t2v_turbo:
        type: video
        protocol: unified-video

完整字段说明、protocol 表格、优先级、alias 解析和 reference_transport 配置见 CONFIGURATION.md。

常见工作流

1. 总结文档

llm chat "总结下面内容" -r article.md -o summary.md

2. 基于参考图修正文案

llm chat "根据参考图修正人物外貌描述" --edit prompt.md -r ref.jpg

3. 生成多张图片方案

llm image "生成三张海报方案" -n 3 -o poster.jpg

4. 转写录音并输出字幕

llm chat "请输出标准 SRT 字幕" -r demo.wav -o demo.srt

5. 生成配音音频

llm tts "请朗读这段欢迎词" --voice Kore -o welcome.wav

6. 创建并恢复视频任务

llm video "生成产品展示短片" -r first-frame.jpg --seconds 8 -o demo.mp4
llm video --resume vid_123 -o demo.mp4

7. 继续同一轮对话

llm chat "继续上次方案" -s worklog
llm chat -I -s worklog

常见错误

• 把长文本直接硬编码到命令里，而不是用 @文件
• 需要多轮对话却没用 -s，导致上下文无法复用
• 在 YAML 里把 aspect 写成未加引号的 16:9，被 YAML 误解析
• 期待字幕输出，但 prompt 没明确要求字幕格式
• 在 llm image 中使用只支持理解或文本输出的模型，导致响应只有文字说明而没有图片
• 忘记 video 是异步任务，未记录任务 ID
• 把域名、密钥、账号写进版本控制文件，而不是放进 .env

包信息

• PyPI 包名：shellus-llmcmd
• CLI 命令名：llm
• Python 要求：>=3.10

相关文档

• 项目主文档：README.md
• 配置说明：CONFIGURATION.md
• 开发参考：DEVELOPING.md