@casatwy/deyo 0.1.7 → 0.2.0

package/README.md

@@ -1,8 +1,12 @@
 # deyo
 
-`deyo` 是 [https://deyo.miaobi.fun](https://deyo.miaobi.fun) 的命令行工具。你可以直接在终端里提交音视频链接进行转写，并把结果输出到终端或保存到本地文件。
+`deyo` 是 [https://deyo.miaobi.fun](https://deyo.miaobi.fun) 的命令行工具。你可以直接在终端里提交音视频链接或本地音视频文件进行转写，并把结果输出到终端或保存到本地文件。
 
-当前支持的来源包括小宇宙单集、喜马拉雅单集、B 站单视频、抖音单视频、小红书单视频笔记、YouTube 单视频、Apple Podcasts 单集和 Twitter/X 单条推文。其中 Twitter/X 只有视频推文可转写，文本 / 图片推文会返回 422，不会扣分钟或创建转写任务。
+CLI `0.2.0` 新增可选的稳定正文事件。默认不会把正文写入进度日志；只有显式使用 `--stream-transcript --progress-format jsonl`，且最终格式为 `text` 时，才会在 stderr JSONL 中输出稳定的 Whisper 正文增量。stdout 或 `-O` 始终只接收最终 Whisper 原稿，CLI 本身不做 AI 整理。
+
+当前支持 8 类链接来源 + 本地音视频上传。链接来源包括小宇宙单集、喜马拉雅单集（含 `xima.tv` 短链）、B 站单视频、抖音单视频、小红书单视频笔记、YouTube 单视频、Apple Podcasts 单集和 Twitter/X 单条推文。其中 YouTube 如果命中可直接使用的字幕，会直接输出字幕或文本结果，不进入完整转写、不扣分钟；喜马拉雅合集链接会返回 422 并提示选择单集，不会扣分钟或创建转写任务；抖音图文内容、小红书图文笔记、Twitter/X 文本或图片推文会返回不支持转写的提示。B 站支持普通 BV 链接、`b23.tv` 短链、带 `bvid` 的 `player.bilibili.com/player.html` 嵌入播放器链接，以及可由 Whisper 解出 BV 页面的 `bilibili://video/...` App 分享视频链接；CLI 会识别并透传 App 链接，不在本地解码或推导 BV。
+
+本地文件转写只支持单个普通音频或视频文件，固定作为 `upload` 来源提交。你可以直接传文件路径，也可以显式使用 `--file`；如果文件扩展名或系统识别不可靠，可以用 `--mime-type` 指定媒体类型。当前不支持目录、glob、stdin、批量队列或断点续传。
 
 ## 安装
 
@@ -22,6 +26,48 @@ pnpm add -g @casatwy/deyo
 deyo --help
 ```
 
+## 安装 Deyo Skill
+
+Deyo CLI 和 Deyo Skill 是两个独立产物：CLI 负责登录、上传、转写、结构化进度和 Whisper 原稿；Skill 负责让 Codex、Claude、Gemini 或 OpenClaw 正确调用 CLI，并在普通 text 场景按约束整理正文。它们独立安装、独立版本、独立更新，版本号不要求相同。当前 Skill 要求 CLI 至少为 `0.2.0`。
+
+先确认 CLI 版本，再交给 Deyo CLI 调用各平台的原生管理器安装 Skill：
+
+```bash
+deyo --version
+deyo skill install --platform codex
+deyo skill install --platform claude
+deyo skill install --platform gemini
+deyo skill install --platform openclaw
+```
+
+默认 scope 为：Codex、Claude、Gemini 使用 `user`，OpenClaw 使用 `global`。Claude 也支持 `--scope workspace`，会映射到 Claude 的 project scope；OpenClaw 也支持 `--scope workspace`。Codex plugin 和 Gemini extension 的原生安装器没有对应的 workspace 安装能力，因此 CLI 会明确拒绝不支持的 scope，不会手写或覆盖平台 cache / lockfile。
+
+四个平台的安装行为如下：
+
+- Codex：添加 `casatwy/deyo-skill` Git marketplace 并安装 `deyo@deyo-official`；新会话生效，后续由宿主刷新 marketplace。
+- Claude：合并同名官方 marketplace 配置、设置 `autoUpdate: true`，再安装 `deyo@deyo-official`；运行 `/reload-plugins` 或开始新会话后生效。
+- Gemini：从 Deyo 官方 Git 仓库安装 extension 并启用 `--auto-update`；不会添加固定 `--ref` 或跳过来源确认的 `--consent`，更新后重启 Gemini CLI。
+- OpenClaw：使用 owner-qualified 的 `@casatwy/deyo`；默认只处理 global scope，workspace 安装时只处理当前 workspace。已有官方安装只会执行同一 scope 的单项 update，不使用 `--all` 或 `--force`。
+
+离线查看本地安装状态：
+
+```bash
+deyo skill status
+deyo skill status --platform codex
+deyo skill status --platform claude --json
+```
+
+`status` 只读取本地设置、安装 metadata 和 manifest；它不会启动平台 CLI、访问网络或触发更新。
+
+如果检测到旧版手工复制的 `deyo` Skill 目录，安装会停止并显示完整目录树 SHA-256。只有目录路径、文件、内容、类型、模式和 symlink 都与已知官方历史版本完全一致时，才允许把该摘要原样传回：
+
+```bash
+deyo skill install --platform codex \
+  --replace-legacy sha256:<deyo-skill-status-显示的摘要>
+```
+
+迁移会先原子备份旧目录并复算摘要，再调用平台原生安装器；安装失败会恢复旧目录。只要存在本地修改、额外文件、未知来源或 symlink，CLI 都会保留现场并拒绝自动覆盖。
+
 ## 使用前准备
 
 在使用 CLI 之前，你需要先创建一个 Deyo API Key：
@@ -30,7 +76,20 @@ deyo --help
 2. 创建一个新的 API Key
 3. 复制这个 Key，后面登录 CLI 时会用到
 
-`deyo` 默认连接正式服务 `https://deyo.miaobi.fun`，普通用户不需要额外配置服务地址。
+`deyo` 默认连接正式服务 `https://deyo.miaobi.fun`，普通用户不需要额外配置服务地址。只有你明确要连接本地或开发环境时，才需要临时传 `--base-url http://deyo.mac-studio`，或把同样的地址写入环境变量 / 本地配置。
+
+API key 读取优先级：
+
+1. 命令行参数 `--api-key`
+2. 环境变量 `DEYO_API_KEY`
+3. 本地配置文件，也就是先执行 `deyo auth login` 保存的 key
+
+服务地址读取优先级：
+
+1. 命令行参数 `--base-url`
+2. 环境变量 `DEYO_BASE_URL`
+3. 本地配置文件，也就是 `deyo auth login --api-key ... --base-url ...` 保存的地址
+4. CLI 默认生产地址 `https://deyo.miaobi.fun`
 
 ## 首次登录
 
@@ -60,12 +119,19 @@ deyo auth logout
 deyo 'https://www.youtube.com/watch?v=xxxx'
 ```
 
-这条命令会：
+也可以直接给一个本地音视频文件：
+
+```bash
+deyo ./audio.mp3
+```
+
+这类命令会：
 
 1. 使用你本地已保存的 API Key
-2. 提交一个转写任务
-3. 在终端里持续显示任务进度
-4. 完成后直接把结果输出到终端
+2. 提交一个链接转写或文件上传任务
+3. 对本地文件显示上传百分比，并在服务端完成媒体检查
+4. 在终端里持续显示任务创建、状态切换和转写进度
+5. 完成后直接把结果输出到终端
 
 如果你希望把结果保存到文件：
 
@@ -73,6 +139,12 @@ deyo 'https://www.youtube.com/watch?v=xxxx'
 deyo -O ./transcript.txt 'https://www.bilibili.com/video/BVxxxx'
 ```
 
+显式使用文件参数并指定 MIME type：
+
+```bash
+deyo --file ./audio.mp3 --mime-type audio/mpeg -O ./audio.txt
+```
+
 ## 常见用法
 
 处理小宇宙单集并保存为文本：
@@ -87,6 +159,8 @@ deyo -O ./episode.txt 'https://www.xiaoyuzhoufm.com/episode/xxxx'
 deyo -O ./ximalaya.txt 'https://www.ximalaya.com/sound/963656969'
 ```
 
+也可以传入会跳转到单集页的 `xima.tv` 短链；合集链接会直接提示需要选择具体单集链接后再提交。
+
 处理 Twitter/X 视频推文并保存为文本：
 
 ```bash
@@ -95,12 +169,45 @@ deyo --source twitter -O ./tweet.txt 'https://x.com/historyinmemes/status/179063
 
 如果传入 Twitter/X 文本或图片推文，CLI 会提示当前不支持转写；这类内容不会进入支付或分钟扣减链路。
 
+处理本地音频文件并保存为文本：
+
+```bash
+deyo ./audio.mp3 -O ./audio.txt
+```
+
+等价地，也可以显式写成：
+
+```bash
+deyo --file ./audio.mp3 -O ./audio.txt
+deyo -O ./audio.txt -- ./audio.mp3
+```
+
+如果需要覆盖自动识别出的媒体类型：
+
+```bash
+deyo --file ./recording.m4a --mime-type audio/mp4 -O ./recording.txt
+```
+
+本地文件上传同样使用 API key 鉴权。文件通过媒体检查并创建完整转写任务后，会按账号分钟余额扣减；如果分钟不足，需要先充值分钟包。
+
 保存为普通文本：
 
 ```bash
 deyo -O ./transcript.txt 'https://www.bilibili.com/video/BVxxxx'
 ```
 
+处理 B 站嵌入播放器链接时，需要链接里带有 `bvid`。CLI 会把它保存为标准 BV 页面 URL；`p` 优先、`page` 兜底选择分 P，`cid` 会被忽略：
+
+```bash
+deyo -O ./bilibili.txt 'https://player.bilibili.com/player.html?bvid=BVxxxx&page=2&cid=123456'
+```
+
+处理 B 站 App 分享的视频链接时，可以直接传 `bilibili://video/...`。CLI 只负责识别为 B 站来源并提交原始 App 链接；`h5awaken.open_app_url`、`h5awaken` base64 内 `open_app_url` 和路径 BV 号的解析由 Whisper 服务端完成。如果只有纯数字 aid 且服务端无法解出 BV 页面，请改用普通 BV 页面 URL：
+
+```bash
+deyo -O ./bilibili-app.txt 'bilibili://video/BVxxxx?page=2'
+```
+
 导出为 `srt` 字幕文件：
 
 ```bash
@@ -113,6 +220,14 @@ deyo --format srt -O ./transcript.srt 'https://www.youtube.com/watch?v=xxxx'
 deyo --progress-format jsonl -O ./transcript.txt 'https://www.youtube.com/watch?v=xxxx'
 ```
 
+让 AI 在转写过程中读取稳定正文事件（最终原稿仍只写入 `./transcript.txt`）：
+
+```bash
+deyo --format text --progress-format jsonl --stream-transcript -O ./transcript.txt 'https://www.youtube.com/watch?v=xxxx'
+```
+
+`--stream-transcript` 默认关闭，只能与最终 `text` 和 `--progress-format jsonl` 一起使用。它不会给正文加标点、分段或纠错；如需整理，应由调用 CLI 的 AI 在独立文件中处理，不能把整理能力描述成 CLI 能力。
+
 如果输出文件名本身就是 `.srt`，也可以省略 `--format srt`，CLI 会自动识别格式。
 
 指定输出英文转写结果：
@@ -137,6 +252,14 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 
 把结果写入文件。如果不传这个参数，结果会直接打印到终端。
 
+`--file <path>`
+
+显式指定一个本地音频或视频文件。也可以直接把文件路径作为位置参数传给 `deyo`，例如 `deyo ./audio.mp3`。
+
+`--mime-type <value>`
+
+可选。覆盖 CLI 自动识别出的文件媒体类型，例如 `audio/mpeg`、`audio/mp4`、`video/mp4`。一般不需要传，只有扩展名不明确或自动识别不符合预期时再使用。
+
 `--format <value>`
 
 指定结果格式，支持：
@@ -144,13 +267,19 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 - `text`
 - `srt`
 - `vtt`
+- `json`
+- `verbose_json`
 
 如果你已经通过 `-O` 指定了输出文件名，CLI 会根据扩展名自动推断常见格式：
 
+- `.txt` 会自动使用 `text`
 - `.srt` 会自动使用 `srt`
 - `.vtt` 会自动使用 `vtt`
+- `.json` 会自动使用 `json`
 - 其他情况默认使用 `text`
 
+`verbose_json` 不会通过文件扩展名自动推断；需要这个格式时请显式传 `--format verbose_json`。
+
 `--progress-format <value>`
 
 指定进度输出格式，支持：
@@ -164,18 +293,65 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 - 当 stderr 是 TTY 时，会保留当前的单行原地刷新进度体验
 - 当 stderr 不是 TTY 时，会退化成逐行文本进度，避免控制字符污染日志或代理输出
 
-如果你希望 AI 或脚本稳定读取进度事件，建议使用 `--progress-format jsonl`。此时 CLI 会继续把最终结果输出到 stdout 或文件，只把进度事件按 JSON Lines 写到 stderr。
+如果你希望 AI 或脚本稳定读取进度事件，建议使用 `--progress-format jsonl`。此时 CLI 会继续把最终结果输出到 stdout 或文件，只把进度事件按 JSON Lines 写到 stderr。AI 代跑上传或长转写任务时，应读取 JSONL 后用自然语言转述上传百分比、媒体检查、任务创建、状态变化和关键转写百分比，不要把原始 JSONL 直接贴给用户。
+
+本地文件上传会额外输出这些上传事件：`upload.hashing`、`upload.started`、`upload.progress`、`upload.completed`、`upload.checking`、`upload.ready`、`upload.aborted`、`upload.failed`。事件不会包含签名 URL、文件 hash 或分片 ETag。
+
+任务阶段会输出这些事件：`task.created`、`task.status_changed`、`task.progress`、`task.completed`、`task.failed`、`task.cancelled`、`task.result_written`、`task.notice`。如果 `task.created` 里出现 `mode: "subtitles"` 或 `resultReady: true`，通常表示命中字幕直出，不需要等待长时间完整转写。
+
+`--stream-transcript`
+
+可选，默认关闭。只允许最终结果格式为 `text`，并且必须同时使用 `--progress-format jsonl`；非法组合会在任务启动前报错。开启后，stderr JSONL 会增加三类正文事件：
+
+- `task.transcript.delta`：`{ event, taskId, sequence, source, startOffset, endOffset, text }`，其中 `source` 为 `sse`、`preview` 或 `result`。
+- `task.transcript.reset`：`{ event, taskId, sequence, source, reason, text, characterCount }`，其中 `source` 同样为 `sse`、`preview` 或 `result`，`reason` 为 `non_prefix_snapshot` 或 `final_result_mismatch`，`text` 是完整修正版。
+- `task.transcript.completed`：`{ event, taskId, sequence, source: "result", characterCount, sha256 }`。
+
+`sequence` 在单次 CLI 进程内递增；`startOffset`、`endOffset` 和 `characterCount` 都按 Unicode code point 计数。`sha256` 是最终原稿精确 UTF-8 字节的 lowercase SHA-256。delta 只包含相对上一份稳定完整快照新增的文本；可变的 `pendingText` 不会进入这些事件。上游快照发生非前缀修正时会发送 reset，最终结果会重新对齐并以 completed 收尾。
+
+这些事件可能包含敏感正文，因此默认关闭。即使开启，stdout 或 `-O` 仍只包含最终 Whisper 原稿；JSONL 正文事件只写 stderr，CLI 不会在本地自动整理或覆盖用户目标文件。
 
 `--api-key <key>`
 
 为当前这一次命令临时指定 API Key。  
 如果你已经执行过 `deyo auth login`，平时通常不需要再传。  
-当它和本地已保存配置同时存在时，会优先使用这次命令里传入的 `--api-key`。
+当它和环境变量、本地已保存配置同时存在时，会优先使用这次命令里传入的 `--api-key`。
+
+`DEYO_API_KEY`
+
+可选。通过环境变量临时指定 API Key。它的优先级低于 `--api-key`，高于本地配置。
+
+`--base-url <url>`
+
+可选。普通使用不需要传，默认使用生产服务和 CLI 默认配置。只有你明确要连接本地或开发环境时，才传 `--base-url http://deyo.mac-studio`。
+
+`DEYO_BASE_URL`
+
+可选。通过环境变量临时指定服务地址。它的优先级低于 `--base-url`，高于本地配置和默认生产地址。
+
+## 能力边界
+
+- 支持输入：8 类单条链接来源，或一个本地音频/视频文件。
+- 不支持输入：目录、glob、stdin、多个文件批量队列、断点续传。
+- 本地文件固定作为 `upload` 来源提交，不需要传 `--source`；如果强行传其他来源，CLI 会直接报错。
+- API key 是 CLI 鉴权入口；没有 API key 时不能创建任务。
+- 完整转写会按账号分钟余额扣减；YouTube 字幕直出、喜马拉雅合集、抖音图文、小红书图文、Twitter/X 文本 / 图片推文等不进入完整转写的分支不会扣分钟或创建转写任务。
 
 `-v, --version`
 
 打印当前 CLI 版本号并退出，适合快速确认本机装的是哪个版本。
 
+## 常见排查
+
+- `缺少 API key。请传 --api-key、设置 DEYO_API_KEY，或先执行 deyo auth login`：先在 `https://deyo.miaobi.fun/me/api-keys` 创建 key，再执行 `deyo auth login --api-key '...'`。
+- `API key 无效或不存在`：重新创建新的 API key 后再登录。
+- `剩余分钟不足`：完整转写会扣减分钟余额，需要先补充分钟包；YouTube 字幕直出不会走完整转写扣减。
+- 本地文件无法识别 MIME：确认是单个普通音频或视频文件；必要时用 `--mime-type audio/mpeg`、`--mime-type video/mp4` 这类 `audio/*` 或 `video/*` 类型覆盖。
+- 媒体检查失败、没有音频轨、ffprobe 失败：换一个包含可转写音轨的普通音视频文件后重试。
+- 上传分片遇到签名过期或 403：CLI 会重新请求签名并重试；如果持续失败，重新运行命令。
+- 任务创建后中断本地 CLI：这只会停止本地等待，不等于取消服务端转写任务；稍后可通过同一任务或历史记录继续查看结果。
+- `--stream-transcript` 组合错误：确认最终格式是 `text`，并同时传入 `--progress-format jsonl`；SRT、VTT、JSON 和 `verbose_json` 不支持正文事件。
+
 ## 在 AI 工具中使用
 
 如果你希望让 AI 助手在你的本机环境里调用 `deyo`，可以参考官方安装页：
@@ -189,7 +365,9 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 2. 如何向你索取一次 API Key
 3. 如何在你的本地环境执行 `deyo auth login`
 
-完成后，你就可以让 AI 直接帮你调用 `deyo` 提交转写任务。对于需要在对话里持续同步进度的场景，AI 应优先使用 `--progress-format jsonl`，读取 stderr 里的结构化事件，再把任务创建、状态切换、关键百分比和最终结果转述给你。
+完成后，你就可以让 AI 直接帮你调用 `deyo` 提交链接转写或本地文件上传任务。对于需要在对话里持续同步进度的场景，AI 必须优先使用 `--progress-format jsonl`，读取 stderr 里的结构化事件，再把上传百分比、媒体检查、任务创建、状态切换、关键转写百分比和最终结果转述给你，不要粘贴原始 JSONL。
+
+如果你要求普通 `text` 整理稿，AI 应额外使用 `--stream-transcript`：让 CLI 把最终 Whisper 原稿写入权限受限的临时文件，仅从 stderr 读取稳定正文事件，按自然边界逐段整理和展示，并在终态重新基于完整原稿生成最终 cleaned `.txt`。明确要求 raw，或输出 SRT、VTT、JSON、`verbose_json` 时，不应启用正文整理。
 
 ## 更多帮助