diff --git a/docs/task/54-修复实时监看按需拉流循环等待.md b/docs/task/54-修复实时监看按需拉流循环等待.md
new file mode 100644
index 0000000..add68f8
--- /dev/null
+++ b/docs/task/54-修复实时监看按需拉流循环等待.md
@@ -0,0 +1,67 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-54-修复实时监看按需拉流循环等待
+wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-54-%E4%BF%AE%E5%A4%8D%E5%AE%9E%E6%97%B6%E7%9B%91%E7%9C%8B%E6%8C%89%E9%9C%80%E6%8B%89%E6%B5%81%E5%BE%AA%E7%8E%AF%E7%AD%89%E5%BE%85.-
+wiki_revision: 3b3a0a211aa7ed8209799a09818b7901c290f750
+synchronized_at: 2026-08-13T07:01:47Z
+<!-- gitea-wiki-mirror:end -->
+
+# 54 修复实时监看按需拉流循环等待
+
+- 类型：缺陷
+- 所属 Epic：#7
+- 所属 MVP / 版本：#8
+- 状态：待验收
+- 日期：2026-08-13
+- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/54
+- Wiki 页面：Task-54-修复实时监看按需拉流循环等待
+- Wiki revision：见本地镜像头
+
+## 背景与目标
+
+MediaMTX 使用按需拉流时，必须先有播放器读取路径才会连接摄像机。原实时监看页面只在状态变为“可播放”后才加载播放器，导致“等待拉流 → 没有读取者 → 始终等待”的循环。目标是在保持按需拉流和安全边界的前提下，让监看页主动成为读取者，并让会话状态收敛到真实媒体状态。
+
+## 最终方案
+
+- 实时监看收到有效播放地址且状态为“等待拉流”或“可播放”时都加载播放器；“等待拉流”保留明确状态提示，同时触发 MediaMTX 按需连接。
+- 会话查询通过只读媒体端口刷新控制器状态，把等待状态安全收敛为可播放或需要处理，不重新应用路径配置。
+- 继续保持 `sourceOnDemand`，无人观看时不占用摄像机连接与转码资源。
+- 真实环境验证过程中发现已保存的 RTSP 凭据被摄像机拒绝（401）；已通过现有 Sense 接口使用本地已获授权配置修正运行数据，未把凭据写入仓库、工单、Wiki 或日志证据。
+
+## 修改文件
+
+- `Sense/server/app/sense/media/service.go`、`route_port.go`：增加只读状态刷新能力。
+- `Sense/server/app/sense/media/service_test.go`：验证刷新状态且不重复配置路径。
+- `Sense/server/app/sense/liveview/service.go`：查询会话时刷新媒体状态。
+- `Sense/server/app/sense/liveview/service_test.go`：验证等待状态收敛到可播放。
+- `Sense/ui/src/components/sense/liveview/StreamPlayer.vue`：等待拉流时即加载播放器。
+- Wiki 架构、业务规则与排错页面。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 等待拉流时主动创建播放器读取者 | 通过，真实 MediaMTX 路径观察到 1 个读取者 |
+| 会话状态从 waiting 收敛为 ready | 通过，真实 API 轮询由 waiting 变为 ready |
+| 实际媒体源可解码 | 通过，探测到 H.264 1920×1080 视频和 AAC 音频 |
+| 不重复应用路径配置 | 通过，单元测试验证刷新仅调用状态查询 |
+| 不泄露摄像机凭据和源地址 | 通过 |
+
+## 测试
+
+- `go test ./...`：通过。
+- `corepack pnpm lint`：0 error，806 个既有格式 warning。
+- `corepack pnpm build`：通过，存在 3 个既有 webpack 体积 warning。
+- Go 1.26.5 Windows 打包：通过。
+- 真实媒体链路：MediaMTX `sourceReady=true`、`readers=1`、收到媒体字节且包含 2 个轨道；Sense 会话由 `waiting` 收敛为 `ready`。
+- **未验证部分**：最终浏览器中的可视画面需要用户在当前浏览器验收；自动化已验证媒体源、读取者与会话状态收敛。
+
+## 遗留问题
+
+- 严格 Harness 仍受既有 #44 归档缺少“最终方案”章节影响。
+
+## 相关提交
+
+- `8d4e4c2` 修复实时监看按需拉流循环等待。
+- `b3dfd23` 更新按需拉流长期 Wiki 镜像。
+