@casatwy/deyo 0.1.9 → 0.2.1

package/README.md

@@ -2,9 +2,11 @@
 
 `deyo` 是 [https://deyo.miaobi.fun](https://deyo.miaobi.fun) 的命令行工具。你可以直接在终端里提交音视频链接或本地音视频文件进行转写，并把结果输出到终端或保存到本地文件。
 
-当前支持 8 类链接来源 + 本地音视频上传。链接来源包括小宇宙单集、喜马拉雅单集（含 `xima.tv` 短链）、B 站单视频、抖音单视频、小红书单视频笔记、YouTube 单视频、Apple Podcasts 单集和 Twitter/X 单条推文。其中喜马拉雅合集链接会返回 422 并提示选择单集，不会扣分钟或创建转写任务；Twitter/X 只有视频推文可转写，文本 / 图片推文会返回 422。B 站支持普通 BV 链接、`b23.tv` 短链、带 `bvid` 的 `player.bilibili.com/player.html` 嵌入播放器链接，以及可由 Whisper 解出 BV 页面的 `bilibili://video/...` App 分享视频链接；CLI 会识别并透传 App 链接，不在本地解码或推导 BV。
+CLI `0.2.1` 在保留可选稳定正文事件的同时，改为在省略 `--language` 时请求服务端自动检测转写语言；只有用户明确指定语言时，CLI 才会把 `language` 字段发送给链接或本地文件任务。默认不会把正文写入进度日志；只有显式使用 `--stream-transcript --progress-format jsonl`，且最终格式为 `text` 时，才会在 stderr JSONL 中输出稳定的 Whisper 正文增量。stdout 或 `-O` 始终只接收最终 Whisper 原稿，CLI 本身不做 AI 整理。
 
-本地文件转写只支持单个音频或视频文件。你可以直接传文件路径，也可以显式使用 `--file`；如果文件扩展名或系统识别不可靠，可以用 `--mime-type` 指定媒体类型。当前不支持目录、glob、stdin、批量队列或断点续传。
+当前支持 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、批量队列或断点续传。
 
 ## 安装
 
@@ -24,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.1`。
+
+先确认 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：
@@ -32,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`
 
 ## 首次登录
 
@@ -163,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 会自动识别格式。
 
 指定输出英文转写结果：
@@ -181,7 +246,7 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 
 `--language <value>`
 
-指定转写语言。默认是 `zh`，也就是中文输出。也可以写 `en`，英文输出。
+显式指定转写语言，例如 `zh` 或 `en`。省略该参数时，CLI 不会在链接任务或本地文件任务的请求体里发送 `language` 字段，由服务端和 Whisper 自动检测；不要根据终端语言或内容标题自行推断。
 
 `-O, --output <path>`
 
@@ -202,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>`
 
 指定进度输出格式，支持：
@@ -226,23 +297,61 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 
 本地文件上传会额外输出这些上传事件：`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 时不能创建任务。
-- 完整转写会按账号分钟余额扣减；喜马拉雅合集、Twitter/X 文本 / 图片推文等不进入转写的分支不会扣分钟或创建转写任务。
+- 完整转写会按账号分钟余额扣减；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`，可以参考官方安装页：
@@ -258,6 +367,8 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 
 完成后，你就可以让 AI 直接帮你调用 `deyo` 提交链接转写或本地文件上传任务。对于需要在对话里持续同步进度的场景，AI 必须优先使用 `--progress-format jsonl`，读取 stderr 里的结构化事件，再把上传百分比、媒体检查、任务创建、状态切换、关键转写百分比和最终结果转述给你，不要粘贴原始 JSONL。
 
+如果你要求普通 `text` 整理稿，AI 应额外使用 `--stream-transcript`：让 CLI 把最终 Whisper 原稿写入权限受限的临时文件，仅从 stderr 读取稳定正文事件，按自然边界逐段整理和展示，并在终态重新基于完整原稿生成最终 cleaned `.txt`。明确要求 raw，或输出 SRT、VTT、JSON、`verbose_json` 时，不应启用正文整理。
+
 ## 更多帮助
 
 查看完整参数说明：