# ClipTalk Agent Instructions

本文件是仓库级 Agent 约定。安装与部署任务必须继续阅读
[`docs/AI_INSTALL.md`](docs/AI_INSTALL.md)，不要根据经验另写一套安装流程。

This file defines repository-wide instructions for coding agents. For setup or
deployment work, also read [`docs/AI_INSTALL.md`](docs/AI_INSTALL.md). Do not
invent a parallel installation procedure.

## Installation workflow / 安装流程

- Start with read-only discovery. Identify the operating system, architecture,
  Python and Node.js versions, FFmpeg capabilities, free disk space, Docker,
  and visible NVIDIA hardware before choosing an installation route.
- Run `python3 tools/setup.py --check --profile auto` and
  `python3 tools/setup.py --dry-run --profile auto` before an actual local
  installation. Use the repository scripts instead of reproducing their work
  as ad-hoc shell commands.
- Prefer the supported local installer on x86-64 Linux or WSL2. Use Docker when
  the user requests isolation or the host cannot reasonably satisfy the local
  prerequisites. Do not claim native macOS or ARM support.
- Explain large downloads, expected disk use, and the chosen CPU/GPU route
  before starting an installation.
- Treat runtime installation and model configuration as separate milestones.
  A healthy web service is not the same as a fully configured editing system.
  Model credentials are configured by the user in the product settings.

- 安装前先执行只读探测，再选择本机或 Docker 路径。
- x86-64 Linux/WSL2 默认优先使用仓库统一安装器；用户要求隔离或本机依赖
  不适合时再使用 Docker。不要宣称原生支持 macOS 或 ARM。
- 下载大型依赖或模型前，先说明 CPU/GPU 方案、磁盘占用和网络影响。
- “运行环境安装完成”和“模型能力配置完成”必须分别汇报，不能混为一谈。

## Safety boundaries / 安全边界

- Do not overwrite `.env`, saved credentials, `data/`, model caches, uploads,
  outputs, or manually managed TalkNet directories.
- Never print, commit, or copy API keys and access tokens into documentation or
  command logs. A loopback-only local installation does not require an access
  token. Remote exposure requires explicit user intent, a strong token, and an
  HTTPS reverse proxy.
- Ask before using `sudo`, changing system packages, exposing a network port,
  switching an existing installation between local and Docker management, or
  deleting data. Never run `docker compose down -v` as routine cleanup.
- Do not stop unrelated processes to reclaim a port. Report the owning process
  or offer a different port.
- Preserve `README.md`, `README_zh.md`, and `LICENSE` unless the user explicitly
  asks to modify them. Do not publish local tests, screenshots, videos, secrets,
  or runtime data when preparing a release.

- 不覆盖 `.env`、已有密钥、任务数据、素材、输出、模型缓存或手动维护的
  TalkNet 目录。
- 使用 `sudo`、修改系统软件、开放远程端口、切换部署方式或删除数据前，
  必须先取得用户确认。
- 不要为了释放端口而结束不属于本次启动的进程。
- 未经明确要求，不修改 `README.md`、`README_zh.md` 和 `LICENSE`。

## Verification and handoff / 验证与交付

- Local verification: run `bash -n start.sh`, `bash start.sh --check`, and the
  appropriate `.venv/bin/python tools/doctor.py` profile after installation.
- Docker verification: render both CPU and GPU Compose configurations before
  building; after startup inspect `docker compose ps`, bounded recent logs, and
  `/api/health`.
- Run `python3 tools/check_repository.py --mode deployment` after changing
  installation or deployment files.
- Report the exact route used, checks that passed, unresolved warnings, the
  local URL, whether the process remains running, and the next user action.
  Never hide a failed optional capability behind a generic success message.

- 本机安装后检查启动脚本、Doctor 和健康接口；Docker 安装先验证 CPU/GPU
  Compose 配置，再检查容器状态、有限范围日志和健康接口。
- 最终说明安装方式、通过项、剩余告警、本地访问地址、服务是否仍在运行，
  以及用户下一步需要在界面完成的模型配置。

## Real-video acceptance / 真实验收脚本（opt-in，CI 不跑）

- `tests/real_video_acceptance.py` 是真实视频端到端验收 runner，**不被 pytest 收集**（文件名非 `test_` 开头），
  因为它会新建任务、调用已配置的模型并保留产物 —— 只应在本地开发环境按需执行。
- 三个脚本的分工：主脚本跑 `highlight/topic/shorter/anchor/speaker`；
  `real_automatic_followup_acceptance.py` 基于已完成的 isolated 报告续跑
  `shorter/audio/motion/cover/cover_default`（需 automatic_delivery）；
  `real_voice_acceptance.py` 做参考声纹验收。
- 常用顺序：先 `--check`（会探活 `/api/health`），再 `--dry-run` 看计划，最后 `--run`；
  `--total-timeout` 可限制全部用例的总耗时（`--timeout` 只是单个 plan 的）。
- `speaker` 用例必须传 `--speaker-video`（多人素材），否则标记 blocked —— 不会用主视频冒充。
- `audio/motion/cover/cover_default` 不在主脚本执行，需走 followup 脚本并指向 isolated 报告。
- 结果恒定 `semanticVerdict="manual_review_required"`：内容准确性、人脸与声纹仍需人工审核。