

ChineseASR · 功能说明
这里讲的是本地转写任务这条路:云端用不了、要交叉核对,或者不经 AI 直接转写时才走这里;AI 处理选定录音默认先上云,见运行与边界。已有短语音、长录音或文件夹先返回稳定任务身份,后续按同一项查进度、恢复或取消,不因等待超时另开重复任务。本地转完若发现疑点,还会留下一笔“等 AI 接手云复核”的标记,本地稿照样先交。桌面听写有独立的小窗和输入流程,微信实时语音有提前热好的会话,都不进入这里的文件任务队列。
当前情况:已有录音任务提交、进度查询、取消与结果复用功能;任务历史写不进去时会先停收新任务,而不是假装成功。能否成功转写仍要看这份录音和本次实际结果。11 月 4 日查本机服务没在监听(两次连接被拒绝),这只说明当时没开;它是用到时才启动的,下一次启动后能不能就绪未核实。
项目技术事实核对于 2026-11-04(北京时间),按当时的 main(4598696)只读核对;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库

ChineseASR · 功能说明
这里讲的是本地转写任务这条路:云端用不了、要交叉核对,或者不经 AI 直接转写时才走这里;AI 处理选定录音默认先上云,见运行与边界。已有短语音、长录音或文件夹先返回稳定任务身份,后续按同一项查进度、恢复或取消,不因等待超时另开重复任务。本地转完若发现疑点,还会留下一笔“等 AI 接手云复核”的标记,本地稿照样先交。桌面听写有独立的小窗和输入流程,微信实时语音有提前热好的会话,都不进入这里的文件任务队列。
当前情况:已有录音任务提交、进度查询、取消与结果复用功能;任务历史写不进去时会先停收新任务,而不是假装成功。能否成功转写仍要看这份录音和本次实际结果。11 月 4 日查本机服务没在监听(两次连接被拒绝),这只说明当时没开;它是用到时才启动的,下一次启动后能不能就绪未核实。
项目技术事实核对于 2026-11-04(北京时间),按当时的 main(4598696)只读核对;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库


用途与实际影响
录音处理可能需要几分钟;如果一次等待结束就重交同一文件,会有两份任务抢资源、覆盖结果。项目先保存这次任务,再让人按原任务查进度。结果文件写出来了,也不代表这次任务记录已经安全存下,两件事要分开看。
比如我问“服务重启后,这段录音会不会自己重新跑?”系统会明确告诉我:原来排队或运行中的任务会留下“服务已重启”的失败终态,不会在后台偷偷复活。我确认需要继续后再显式重试,新任务仍按同一音频内容与请求指纹找到稳定输出目录,并复用长音频里已经验证有效的分段。
得到这段录音当前在等、在跑、已完成还是失败,以及已经生成的文件和继续入口。服务重启不会偷偷重跑;本次等待超时也不代表底层任务已结束。本地标出疑点的文件另有云复核状态:已复核、等 AI 接手,或者没排上及原因。
录音和服务可用时返回一个可继续查询的任务,完成后交回正文及对应证据;有疑点时另留“等 AI 接手”的云复核提示。
等待结束时先查原任务;任务本身失败则保留真实错误和已完成部分。任务历史写不进去时,服务先拒收新任务、健康检查标成降级,直到写入恢复;模型跑完但终态存不下,不报告成功(结果文件可能已经在)。
音频、服务或指定模型无法启动时说明原因,不生成假任务,也不暗换另一模型。

用途与实际影响
录音处理可能需要几分钟;如果一次等待结束就重交同一文件,会有两份任务抢资源、覆盖结果。项目先保存这次任务,再让人按原任务查进度。结果文件写出来了,也不代表这次任务记录已经安全存下,两件事要分开看。
比如我问“服务重启后,这段录音会不会自己重新跑?”系统会明确告诉我:原来排队或运行中的任务会留下“服务已重启”的失败终态,不会在后台偷偷复活。我确认需要继续后再显式重试,新任务仍按同一音频内容与请求指纹找到稳定输出目录,并复用长音频里已经验证有效的分段。
得到这段录音当前在等、在跑、已完成还是失败,以及已经生成的文件和继续入口。服务重启不会偷偷重跑;本次等待超时也不代表底层任务已结束。本地标出疑点的文件另有云复核状态:已复核、等 AI 接手,或者没排上及原因。
录音和服务可用时返回一个可继续查询的任务,完成后交回正文及对应证据;有疑点时另留“等 AI 接手”的云复核提示。
等待结束时先查原任务;任务本身失败则保留真实错误和已完成部分。任务历史写不进去时,服务先拒收新任务、健康检查标成降级,直到写入恢复;模型跑完但终态存不下,不报告成功(结果文件可能已经在)。
音频、服务或指定模型无法启动时说明原因,不生成假任务,也不暗换另一模型。

录音和服务可用时返回一个可继续查询的任务,完成后交回正文及对应证据。
等待结束时先查原任务;任务本身失败则保留真实错误和已完成部分。
音频、服务或指定模型无法启动时说明原因,不生成假任务,也不暗换另一模型。

录音和服务可用时返回一个可继续查询的任务,完成后交回正文及对应证据。
等待结束时先查原任务;任务本身失败则保留真实错误和已完成部分。
音频、服务或指定模型无法启动时说明原因,不生成假任务,也不暗换另一模型。

需要本地转写时,把已有录音文件交给 ChineseASR,并按同一任务查看进度。
- 要转写的音频或文件夹
- 快看或重要复核等用途


需要本地转写时,把已有录音文件交给 ChineseASR,并按同一任务查看进度。
- 要转写的音频或文件夹
- 快看或重要复核等用途






- scripts/asr-smart.ps1 负责本地入口、轻量健康检查、提交和有界等待,并把云复核状态投影给调用方。
- src/zh_asr/service.py 维护 job(任务记录) 状态、队列、期限、状态查询与 observer projection;serve 只允许 127.0.0.1,HTTP Host 必须是本机,带 Origin 时必须同源,提交任务必须是 application/json。
- job(任务记录) key 绑定音频绝对路径、内容 SHA-256、模式、已解析引擎、模型配置、设备、切片参数和调用方绑定,缓存命中前验证关键制品。
- jobs.json 持久化有界任务历史(最多 200 条终态加活动/排队任务);服务启动时保留已完成终态,把遗留 queued / running 记录转换为明确的 service_restarted 失败。历史写入失败时 /health 的 persistence.status=degraded、ready=false,拒收新任务直到后续写入恢复;模型命令完成但终态不能落盘时不报告 job 成功(9 月 24 日修复,666d06d)。
- long-strict 输出目录由稳定 request fingerprint 派生;失败或取消后的显式重试不会换目录,旧 manifest(清单) 和收据仍须重新验证。
- process_control.py 维护子进程树和终止边界,避免只结束父进程留下 GPU worker。
- 状态投影不反射调用方任意标识,也不暴露提示、音频或转写正文。
- 任务成功且有疑难证据时,service.py 写 cloud.review.json(pending_ai_session 和 next_command),由 AI 接手跑自动云复核,本地服务自己不上传。提示准备或写入失败时 cloud_review 记为 failed/cloud_review_not_scheduled,主本地结果照常保留;即使提示文件写不出,这条失败也随 jobs.json 保存、重启后可查;之后恢复的有效提示文件胜过旧失败记录,新旧按文件身份判断而不是只看时间(1014970、024a212、73fdfda)。

- scripts/asr-smart.ps1 负责本地入口、轻量健康检查、提交和有界等待,并把云复核状态投影给调用方。
- src/zh_asr/service.py 维护 job(任务记录) 状态、队列、期限、状态查询与 observer projection;serve 只允许 127.0.0.1,HTTP Host 必须是本机,带 Origin 时必须同源,提交任务必须是 application/json。
- job(任务记录) key 绑定音频绝对路径、内容 SHA-256、模式、已解析引擎、模型配置、设备、切片参数和调用方绑定,缓存命中前验证关键制品。
- jobs.json 持久化有界任务历史(最多 200 条终态加活动/排队任务);服务启动时保留已完成终态,把遗留 queued / running 记录转换为明确的 service_restarted 失败。历史写入失败时 /health 的 persistence.status=degraded、ready=false,拒收新任务直到后续写入恢复;模型命令完成但终态不能落盘时不报告 job 成功(9 月 24 日修复,666d06d)。
- long-strict 输出目录由稳定 request fingerprint 派生;失败或取消后的显式重试不会换目录,旧 manifest(清单) 和收据仍须重新验证。
- process_control.py 维护子进程树和终止边界,避免只结束父进程留下 GPU worker。
- 状态投影不反射调用方任意标识,也不暴露提示、音频或转写正文。
- 任务成功且有疑难证据时,service.py 写 cloud.review.json(pending_ai_session 和 next_command),由 AI 接手跑自动云复核,本地服务自己不上传。提示准备或写入失败时 cloud_review 记为 failed/cloud_review_not_scheduled,主本地结果照常保留;即使提示文件写不出,这条失败也随 jobs.json 保存、重启后可查;之后恢复的有效提示文件胜过旧失败记录,新旧按文件身份判断而不是只看时间(1014970、024a212、73fdfda)。




| 名词 | 意思 |
|---|---|
| Smart API | 把预检、任务提交、短等待和状态观察组合成一个稳定入口。 |
| job key | 绑定输入与请求语义的幂等键,防止同一重任务重复运行。 |
| request fingerprint(请求指纹) | 由音频内容 SHA-256、模型与请求参数等组成;不是只看文件大小或修改时间。 |
| terminal history(终态历史) | 把 succeeded、failed、canceled、blocked 等任务保存到 jobs.json 供重启后查询(最多 200 条终态加活动任务),但不把旧队列重新执行。 |
| stable recovery directory(稳定恢复目录) | long-strict 按请求指纹固定的输出目录;显式重试可验证并复用其中已完成分段。 |
| observer projection | 只返回上层决策所需状态,不暴露私人正文和内部实现细节。 |
| lease(租约) | 证明当前 worker 仍拥有任务的短时状态;丢失后不能继续写结果。 |

已有录音把提交、查进度、取消、超时和服务重启后的续作收进同一任务入口,避免因为等得久就把一段大录音重复跑好几份;任务记录存不下时宁可停收,也不报假成功。
解决什么
解决重模型任务阻塞调用方、重复提交、任务身份丢失、缓存错配、调用端超时被误判为服务端失败、结果文件已在但任务记录没存下却报成功、可选的云复核交接失败连带丢掉本地稿,以及后台进程失联后无法恢复的问题。



已有录音把提交、查进度、取消、超时和服务重启后的续作收进同一任务入口,避免因为等得久就把一段大录音重复跑好几份;任务记录存不下时宁可停收,也不报假成功。
解决什么
解决重模型任务阻塞调用方、重复提交、任务身份丢失、缓存错配、调用端超时被误判为服务端失败、结果文件已在但任务记录没存下却报成功、可选的云复核交接失败连带丢掉本地稿,以及后台进程失联后无法恢复的问题。

- 客户端等待超时: 返回 job(任务记录) id 和查询入口;先读任务状态,不立即重发。
- 服务在 queued 或 running 时重启: 持久记录转成 service_restarted 终态并注明自动重跑关闭;用户或调用方核对后才显式提交新的 job(任务记录)。
- long-strict 失败或取消后重试: 创建新 job(任务记录) id,但复用同一 request fingerprint 对应的稳定输出目录;manifest(清单) 与收据验证通过的分段才跳过。
- 缓存文件缺失或指纹不一致: 缓存失效并重新执行,不返回部分旧结果。

- 客户端等待超时: 返回 job(任务记录) id 和查询入口;先读任务状态,不立即重发。
- 服务在 queued 或 running 时重启: 持久记录转成 service_restarted 终态并注明自动重跑关闭;用户或调用方核对后才显式提交新的 job(任务记录)。
- long-strict 失败或取消后重试: 创建新 job(任务记录) id,但复用同一 request fingerprint 对应的稳定输出目录;manifest(清单) 与收据验证通过的分段才跳过。
- 缓存文件缺失或指纹不一致: 缓存失效并重新执行,不返回部分旧结果。

- worker 超期、取消或租约丢失: 结束任务进程树并记录终态,保留可安全恢复的任务证据。worker 自己先退出(不论退出码)后,显卡服务按设计回收租约,之后查不到租约(lease_not_found)算正常回收,不再盖掉真实错因:命令行保留 worker 的 stdout/stderr,服务失败记录保留 returncode、stdout_tail、stderr_tail,失败提示带退出码和报错末行,asr-smart.ps1 直接显示,能说出音频解码失败这类实际原因;只有运行中真丢租约才停掉 worker 并报租约丢失(10 月 28 日 8b6980c;11 月 4 日只读源码,未执行)。
- 服务端口被其他程序占用: 明确报告身份冲突,不结束未知进程也不抢端口。
- 任务历史写不进去: 健康检查标成 degraded、ready=false,拒收新任务;已跑完但终态存不下的任务不报成功,结果文件可能已经在,写入恢复后再继续。
- 云复核交接提示写不出: 本地结果照常交付,云复核记为 failed/cloud_review_not_scheduled 并随任务历史保存;之后补上有效提示即以新提示为准。

- worker 超期、取消或租约丢失: 结束任务进程树并记录终态,保留可安全恢复的任务证据。worker 自己先退出(不论退出码)后,显卡服务按设计回收租约,之后查不到租约(lease_not_found)算正常回收,不再盖掉真实错因:命令行保留 worker 的 stdout/stderr,服务失败记录保留 returncode、stdout_tail、stderr_tail,失败提示带退出码和报错末行,asr-smart.ps1 直接显示,能说出音频解码失败这类实际原因;只有运行中真丢租约才停掉 worker 并报租约丢失(10 月 28 日 8b6980c;11 月 4 日只读源码,未执行)。
- 服务端口被其他程序占用: 明确报告身份冲突,不结束未知进程也不抢端口。
- 任务历史写不进去: 健康检查标成 degraded、ready=false,拒收新任务;已跑完但终态存不下的任务不报成功,结果文件可能已经在,写入恢复后再继续。
- 云复核交接提示写不出: 本地结果照常交付,云复核记为 failed/cloud_review_not_scheduled 并随任务历史保存;之后补上有效提示即以新提示为准。

- 日常智能提交、短等待、状态与云复核状态入口
- 异步 job(任务记录)、状态、期限、缓存、历史写入状态和 observer projection
- 子进程树生命周期与终止
- 服务、缓存、状态、本机请求检查和失败路径回归
- 2026-08-31 的全量 345 项单元测试通过,其中 service、process control、observer projection 和 scripts 均进入回归;之后另有 9 月 17 日运行 482 项(1 跳过)、9 月 24 日运行 495 项(1 跳过)、9 月 29 日运行 531 项(20 跳过)的具名历史记录,各自保留日期。
- service 回归明确覆盖终态 jobs.json 持久化、遗留未完成任务转 service_restarted 且不自动重跑、long-strict 失败/取消后复用稳定目录,以及同大小同修改时间但内容不同仍产生不同 fingerprint;历史写入失败停收与本机请求检查另有 test_service.py、test_service_http_guard.py 的测试定义(11 月 4 日只读,未执行)。
- 2026-10-11 13:33 记录本机服务健康检查为 ok,当时没有记下历史写入状态字段,截至 14:00 没有它是否就绪的记录。
- 2026-11-04 09:05–09:15 两次只读 GET http://127.0.0.1:18666/health 都连接被拒绝,没有去启动服务:这只说明当时没在监听,不能证明下一次 asr-smart 按需启动会失败;启动后能否 ready 未核实。
- 本次未运行真实 strict smoke,因此模块保持 mixed,不把单测冒充 E2E(端到端验证)。
本模块决定任务是否被正确创建和监管;模型与模式模块决定跑什么,长音频模块决定怎样分段,审计模块决定怎样解释结果。

- 日常智能提交、短等待、状态与云复核状态入口
- 异步 job(任务记录)、状态、期限、缓存、历史写入状态和 observer projection
- 子进程树生命周期与终止
- 服务、缓存、状态、本机请求检查和失败路径回归
- 2026-08-31 的全量 345 项单元测试通过,其中 service、process control、observer projection 和 scripts 均进入回归;之后另有 9 月 17 日运行 482 项(1 跳过)、9 月 24 日运行 495 项(1 跳过)、9 月 29 日运行 531 项(20 跳过)的具名历史记录,各自保留日期。
- service 回归明确覆盖终态 jobs.json 持久化、遗留未完成任务转 service_restarted 且不自动重跑、long-strict 失败/取消后复用稳定目录,以及同大小同修改时间但内容不同仍产生不同 fingerprint;历史写入失败停收与本机请求检查另有 test_service.py、test_service_http_guard.py 的测试定义(11 月 4 日只读,未执行)。
- 2026-10-11 13:33 记录本机服务健康检查为 ok,当时没有记下历史写入状态字段,截至 14:00 没有它是否就绪的记录。
- 2026-11-04 09:05–09:15 两次只读 GET http://127.0.0.1:18666/health 都连接被拒绝,没有去启动服务:这只说明当时没在监听,不能证明下一次 asr-smart 按需启动会失败;启动后能否 ready 未核实。
- 本次未运行真实 strict smoke,因此模块保持 mixed,不把单测冒充 E2E(端到端验证)。
本模块决定任务是否被正确创建和监管;模型与模式模块决定跑什么,长音频模块决定怎样分段,审计模块决定怎样解释结果。
复制 AI 续作说明
项目:录音文件入口与可恢复任务;仓库:wlyaaaaa/ChineseASR;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。








