TlAgent —— 多时间线 Agent 剪辑工具（v17.100000.plus 自举页, 机读）
================================================================

【状态声明 · 必读】
- 本项目处于 测试版（BETA）。更新是破坏性的：工程文件与接口都可能在版本间不兼容。
- 官网只提供最新版本。你必须自己维护一个"可用版本"目录作为回退：
  更新前把现有安装目录改名为 <目录>-bak-<日期>，新版本验证可用后再删旧目录。

【这是什么】
- C# WPF GUI + Go 闭源核心的多时间线视频剪辑工具。
- 本项目不内置 agent：你（agent）是无状态管道，通过 HTTP 接口读写工程，
  与人共同精准可视化地完成剪辑。操作标准: https://v17.100000.plus/api/protocol（由运行中的后端提供）
  与 https://v17.100000.plus/AGENT_PROTOCOL.md。

【第一步 · 检测系统里是否已安装】
按顺序检查，命中即跳到【第三步】：
1) 进程/端口: GET http://127.0.0.1:8617/healthz 与 http://127.0.0.1:19130/healthz
2) 命令: where tlagent  或  where TlAgentGui
3) 常见目录: %LOCALAPPDATA%\TlAgent  D:\TlAgent  X:\TlAgent（存在 scripts\start_all.cmd 即安装）

【第二步 · 从 0 下载安装（未检测到时）】
1) 取最新版元数据: GET https://v17.100000.plus/latest.json
   → {version, url, size, sha256, note, updated}（官网只有最新版）
2) 下载: GET https://v17.100000.plus/download/latest  （zip）
3) 校验: sha256 必须等于 latest.json 的 sha256
4) 解压到纯英文路径（安装路径必须英文；模型/素材目录可中文）
5) 依赖部署 → 见【第二步半】，全部由你（agent）自行完成

【第二步半 · 依赖部署（分发不含任何依赖，全部由你自行部署/对接）】
分发包只含核心程序与说明。下载、部署、安装、测试都是你的事。
以下依赖逐项部署并逐项验证；某项失败不影响其余能力，按需取舍。

(1) ffmpeg / ffprobe（必须——媒体探测/缩略图/波形/场景检测/渲染全靠它）
    装: winget install --id Gyan.FFmpeg -e
        或 https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip
        解压后把 bin 目录加入 PATH（setx PATH "%PATH%;<bin 目录>"）
    验: ffmpeg -version 且 ffprobe -version 能输出

(2) .NET 8 Desktop Runtime（必须——GUI 需要）
    装: winget install Microsoft.DotNet.DesktopRuntime.8 -e
        或 https://dotnet.microsoft.com/download/dotnet/8.0 （Desktop Runtime x64）
    验: dotnet --list-runtimes 包含 Microsoft.WindowsDesktop.App 8.x

(3) HEVC 视频扩展（播放 HEVC 素材需要；H.264 素材可跳过）
    装: ms-windows-store://pdp/?ProductId=9n4wgh0z6vhq （Microsoft Store）
        或转码素材为 H.264: ffmpeg -i in.mp4 -c:v libx264 -crf 20 out.mp4
    验: powershell Get-AppxPackage Microsoft.HEVCVideoExtension

(4) ASR 语音索引（可选能力接口——由你自行部署，或对接现成同契约服务）
    本项目只定义 HTTP 契约: POST {ASR_URL}/asr?lang=zh&itn=1  body=原始音频字节
      → {text, segments:[{start,end,text}]}（秒）
    无此服务时语音检索不可用，其余功能全部正常。
    方式 A 对接现成同契约服务: 配 TLA_ASR_URL 即可
    方式 B 自行部署: Python 3.12 + pip install sherpa-onnx soundfile numpy
      模型（公开可下）: HuggingFace csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue
      （model.onnx + tokens.txt）+ silero_vad.onnx
      启动: python asr_server.py --port 8082 --model-dir <模型目录>
      （包内 servicessrsr_server.py 即该契约的参考实现）
    验: GET http://127.0.0.1:8082/healthz → {"ok":true}
    OCR 等其余能力接口同理：契约化，由你部署或对接，本项目不含实现。

(5) 端口约定: 后端 8617 / 授权与日志 19130 / ASR 8082（都可用参数/env 改）

6) 启动: 运行 scripts\start_all.cmd（授权服务 + 后端 + GUI；ASR 独立启动）
7) 验证: GET http://127.0.0.1:8617/healthz → {"ok":true}

【第二步尾 · 服务器分工（校验/日志 ≠ 分发，线路必须分开）】
- 分发线路（官网/下载）：https://v17.100000.plus —— 只负责 latest.json / download/latest，线路差，不要用它做校验。
- 校验/日志线路（国内）：默认 http://101.42.45.250:19130 （与 V9 校验机同一台国内腾讯云；端口/env 可改）。
  校验: POST <校验地址>/v17/check      日志: POST <校验地址>/v17/log/up
- 客户端配置（workspace/.env，缺省走 127.0.0.1:19130 本地开发）:
    TLA_LIC_URL=http://101.42.45.250:19130
    TLA_DIAG_URL=http://101.42.45.250:19130
- 两块可同机也可分机：V17_ROLE=lic（只跑校验/日志）| web（只跑官网/下载）| all（本地开发，默认）。
- 安装完成后必须验证校验可达：GET <校验地址>/healthz → role=lic；不通时写通道会被门禁锁（HTTP 402）。

【第二步终 · 维护留档（必须，用于强制更新前回放你的操作）】
- 你的每一步安装/配置/升级/回退/测试都要留档：POST http://127.0.0.1:8617/api/agentlog
    体: {"source":"install|config|update|rollback|test", "level":"INFO|WARN|ERROR", "message":"<做了什么 + 命令 + 结果>"}
- 落盘 workspace/agentlog/<source>-YYYYMMDD.log（append-only），与后端 logs/ 一起加密上传。
- 目的：强制更新后若 agent 不可用，能凭这些留档回放"哪一步弄坏的"，避免下次重踩。
- 本地调试期若后端未起，可先把日志写进 workspace/agentlog/ 目录（同名格式），后端启动后照常上传。

【维护文档集（跨会话/跨 agent 无缝维护的保证）】
workspace/docs/ 下有四份 agent 公共维护文档（随工程走，升级/换 agent 不丢；HTTP 读写 GET/POST /api/docs）：
- ENVIRONMENT.md 部署机环境台账：本机端口/路径/依赖版本/能力接口对接（ASR 等）/环境变量。环境一变就必须更新。
- SCRIPTS.md     辅助脚本台账：随包脚本用法 + 你自写脚本的登记处。
- PITFALLS.md    踩坑经验（append-only）：现象→原因→解决→预防，只追加不修改。
- PROGRESS.md    工程进度：宏观状态/已完成/进行中/下一步/决策记录（与 /api/brief 配合）。
规则：每次会话开始先读这四份；凡 环境变更/脚本变更/踩坑/里程碑，立即 POST /api/docs 回写。
这是硬规则（R11）：不维护文档 = 下一会话/下一个 agent 重复踩坑。
另有 R12（留档硬规则）：安装/配置/升级/回退的每一动作都 POST /api/agentlog（见【第二步终 · 维护留档】）。

【第三步 · 接入（成为本项目的外部 agent）】
- 读操作标准: GET http://127.0.0.1:8617/api/protocol （机读，权威；含 R1–R12 行为规则）
- 每次被调用: GET /api/brief 读增量（人的新消息+有效操作）；人只说"继续"时用 GET /api/brief?full=1 完整重放
- 提交操作: POST /api/ops （计划顶层 author="agent"）
- 回复人并记录讨论: POST /api/messages {author:"agent", text:...} （对话即工程记录）
- 完整历史在 workspace/journal.jsonl（append-only）——你无需自己记任何状态

【回退策略】
- 测试版更新破坏性：升级前保留 <目录>-bak-<日期>；升级后验证 /healthz + 打开工程
  （workspace\workspace.json 完整保留），不兼容则回退到旧目录继续服务。
- 工程文件（workspace/）独立于程序目录：升级程序时不要动 workspace/。

【官网（人读）】 https://v17.100000.plus/  （教程/工具手册/FAQ/下载）