用途与实际影响
这项功能怎样使用
为什么需要它
录音处理可能需要几分钟；如果一次等待结束就重交同一文件，会有两份任务抢资源、覆盖结果。项目先保存这次任务，再让人按原任务查进度。
举个实际例子
比如我问“服务重启后，这段录音会不会自己重新跑？”系统会明确告诉我：原来排队或运行中的任务会留下“服务已重启”的失败终态，不会在后台偷偷复活。我确认需要继续后再显式重试，新任务仍按同一音频内容与请求指纹找到稳定输出目录，并复用长音频里已经验证有效的分段。
最后我会得到什么
得到这段录音当前在等、在跑、已完成还是失败，以及已经生成的文件和继续入口。服务重启不会偷偷重跑；本次等待超时也不代表底层任务已结束。
正常时
录音和服务可用时返回一个可继续查询的任务，完成后交回正文及对应证据。
发现问题时
等待结束时先查原任务；任务本身失败则保留真实错误和已完成部分。
入口不可用或证据不足时
音频、服务或指定模型无法启动时说明原因，不生成假任务，也不暗换另一模型。
从哪里开始
把已有录音文件交给 ChineseASR，并按同一任务查看进度。
需要准备什么
- 要转写的音频或文件夹
- 快看或重要复核等用途
从开始到拿到结果
- 1
系统核对并处理
核对音频与请求，同一任务复用身份；短音频等待结果，长音频复用已验片段。
- 2
交付与接续
交回状态和输出位置；本次等待结束不等于任务超时，服务重启后的失败须明确重试。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
文件 Smart API（智能任务接口）、任务生命周期和缓存完整性保留既有证据；真实转写仍按具体输入验收关键规则与设计选择
先查询任务状态，再决定等待、恢复或重新提交。
request fingerprint（请求指纹）包含音频内容 SHA-256 与请求语义；只改修改时间不改变它，内容改变即使大小和时间相同也会改变它。
相同输入和请求复用验证过的结果；输入内容、模型或请求身份改变时必须新建任务。
客户端 Timeout（等待超时）与服务端失败分开表达。
terminal（终态）任务写入持久历史；重启时未完成记录被标成 interrupted / service_restarted，不自动重新排队。
long-strict 失败或取消后的显式重试产生新 job（任务记录） id，但复用同一稳定输出目录，让 manifest（清单） 验证后只补缺失分段。
取消、期限和租约丢失会回收完整子进程树。
外部观察只返回有界状态，不公开私人正文或内部目录扫描结果。
本模块用到的名词
- Smart API
- 把预检、任务提交、短等待和状态观察组合成一个稳定入口。
- job key
- 绑定输入与请求语义的幂等键，防止同一重任务重复运行。
- request fingerprint（请求指纹）
- 由音频内容 SHA-256、模型与请求参数等组成；不是只看文件大小或修改时间。
- terminal history（终态历史）
- 把 succeeded、failed、canceled、blocked 等任务保存到 jobs.json 供重启后查询，但不把旧队列重新执行。
- stable recovery directory（稳定恢复目录）
- long-strict 按请求指纹固定的输出目录；显式重试可验证并复用其中已完成分段。
- observer projection
- 只返回上层决策所需状态，不暴露私人正文和内部实现细节。
- lease（租约）
- 证明当前 worker 仍拥有任务的短时状态；丢失后不能继续写结果。
专业定义
已有录音把提交、查进度、取消、超时和服务重启后的续作收进同一任务入口，避免因为等得久就把一段大录音重复跑好几份。
解决什么
解决重模型任务阻塞调用方、重复提交、任务身份丢失、缓存错配、调用端超时被误判为服务端失败，以及后台进程失联后无法恢复的问题。
当前怎样实现
- scripts/asr-smart.ps1 负责本地入口、轻量健康检查、提交和有界等待。
- src/zh_asr/service.py 维护 job（任务记录） 状态、队列、期限、状态查询与 observer projection。
- job（任务记录） key 绑定音频绝对路径、内容 SHA-256、模式、已解析引擎、模型配置、设备、切片参数和调用方绑定，缓存命中前验证关键制品。
- jobs.json 持久化有界任务历史；服务启动时保留已完成终态，把遗留 queued / running 记录转换为明确的 service_restarted 失败。
- long-strict 输出目录由稳定 request fingerprint 派生；失败或取消后的显式重试不会换目录，旧 manifest（清单） 和收据仍须重新验证。
- process_control.py 维护子进程树和终止边界，避免只结束父进程留下 GPU worker。
- 状态投影不反射调用方任意标识，也不暴露提示、音频或转写正文。
执行流程
- 1
规范并验证输入路径，计算输入身份和请求语义。
- 2
检查服务健康和当前活跃任务，不以进程名代替 job（任务记录） 状态。
- 3
计算 job（任务记录） key；命中已验证完成结果时返回 cache hit。
- 4
未命中则先把新 job（任务记录） 写入持久任务历史，再启动对应 CLI（命令行工具） 子进程。
- 5
调用方在 WaitSec 内轮询，超时只返回 job（任务记录） 身份。
- 6
服务持续监管期限、取消和子进程退出。
- 7
完成后校验输出并把状态原子更新为 succeeded、failed、canceled 或 blocked。
- 8
若服务重启，回读终态供查询；遗留未完成记录只标 interrupted，不恢复执行，长音频必须由调用方显式重试后在稳定目录内续跑。
边界
- 只监听本机回环地址，不作为带认证的远程服务。
- cache hit 只复用相同输入与请求的已验证制品。
- 调用端超时不自动复制任务。
- 状态接口不返回私人转写正文或声纹数据。
失败与恢复
- 客户端等待超时
- 返回 job（任务记录） id 和查询入口；先读任务状态，不立即重发。
- 服务在 queued 或 running 时重启
- 持久记录转成 service_restarted 终态并注明自动重跑关闭；用户或调用方核对后才显式提交新的 job（任务记录）。
- long-strict 失败或取消后重试
- 创建新 job（任务记录） id，但复用同一 request fingerprint 对应的稳定输出目录；manifest（清单） 与收据验证通过的分段才跳过。
- 缓存文件缺失或指纹不一致
- 缓存失效并重新执行，不返回部分旧结果。
- worker 超期、取消或租约丢失
- 结束任务进程树并记录终态，保留可安全恢复的任务证据。
- 服务端口被其他程序占用
- 明确报告身份冲突，不结束未知进程也不抢端口。
真实入口
E:\Projects\Tools\ChineseASR\scripts\asr-smart.ps1日常智能提交、短等待与状态入口
E:\Projects\Tools\ChineseASR\src\zh_asr\service.py异步 job（任务记录）、状态、期限、缓存和 observer projection
E:\Projects\Tools\ChineseASR\src\zh_asr\process_control.py子进程树生命周期与终止
E:\Projects\Tools\ChineseASR\tests\test_service.py服务、缓存、状态和失败路径回归
如何验证
- 2026-08-31 的全量 345 项单元测试通过，其中 service、process control、observer projection 和 scripts 均进入回归。
- service 回归明确覆盖终态 jobs.json 持久化、遗留未完成任务转 service_restarted 且不自动重跑、long-strict 失败/取消后复用稳定目录，以及同大小同修改时间但内容不同仍产生不同 fingerprint。
- Doctor 当前确认代理环境干净、GPU 与模型配置可读。
- 本次未运行真实 strict smoke，因此模块保持 mixed，不把单测冒充 E2E（端到端验证）。
与其他模块的关系
本模块决定任务是否被正确创建和监管；模型与模式模块决定跑什么，长音频模块决定怎样分段，审计模块决定怎样解释结果。