ohos-scrcpy-app: Instructions file for Codex

AGENTS.md

本文档用于约束在本仓库中工作的 AI 编码代理。所有操作应以当前代码、构建配置和用户要求为准；README.md 与 docs/ 用于补充背景。当文档与代码不一致时，先核对实际配置和实现，不要直接照搬历史结论。

沟通与交付

• 始终使用简体中文沟通，包括回复、代码注释、文档和提交信息。
• 开始修改前先阅读相关实现、配置和设计文档，避免凭经验猜测 OpenHarmony 或平台 API。
• 只修改任务所需文件，保留用户已有的未提交改动，不清理或覆盖无关变更。
• 完成后说明修改内容、验证命令与验证结果；未执行的验证及原因也要明确说明。
• 未经用户明确要求，不提交、不推送、不发布、不部署，也不改签名材料和版本号。

项目概览

鸿镜（HongJing）是 OpenHarmony 设备投屏与 HDC 调试工具，由两个子工程组成：

1. scrcpy_server/：运行在 OpenHarmony 设备上的系统 HAP。
2. scrcpy_client_flutter/：运行在 macOS/Windows 上的 Flutter 桌面客户端，Linux 为后续目标。

客户端通过系统或应用内置的 hdc 执行设备发现、安装、卸载、shell 和端口转发。投屏连接固定使用：

客户端 -> hdc fport tcp:<本机端口> tcp:53535
       -> 127.0.0.1:<本机端口>
       -> 设备端 127.0.0.1:53535

视频流、心跳、设备状态和控制消息均复用该 TCP 通道，不增加设备 LAN 直连方案。

目录与职责

.
├── scrcpy_server/
│   ├── AppScope/app.json5                 # bundle、版本、keepAlive
│   ├── build-profile.json5                # SDK、产品与签名配置
│   └── entry/
│       ├── build-profile.json5            # NAPI/CMake、ABI、产物名
│       └── src/main/
│           ├── module.json5               # Ability、权限、mainElement
│           ├── ets/
│           │   ├── scrcpyservice/         # 服务生命周期、协议、输入和应用列表
│           │   ├── hapinstaller/          # HAP 安装 Ability
│           │   ├── entryability/          # 调试/授权 UI 入口
│           │   └── pages/                 # ArkUI 页面
│           └── cpp/                       # TCP、截屏、编码、NAPI 桥接
├── scrcpy_client_flutter/
│   ├── lib/
│   │   ├── hdc/                           # hdc 路径解析与命令封装
│   │   ├── net/                           # TCP 客户端与协议编解码
│   │   ├── decoder/                       # MethodChannel 解码抽象
│   │   ├── state/app_state.dart           # 客户端中央状态与业务编排
│   │   ├── terminal/                      # PTY 终端
│   │   └── ui/                            # Flutter UI
│   ├── macos/Runner/VideoDecoderPlugin.swift
│   ├── windows/runner/                    # D3D11/MFT/CPU 解码与纹理插件
│   ├── bundled_tools/                     # 打包时内置的 hdc 及依赖
│   ├── third_party/xterm/                 # 本地依赖，非任务需要不改
│   └── scripts/                           # macOS/Windows 打包脚本
├── docs/                                  # 架构、平台方案和踩坑记录
├── spec_doc/                              # 需求与开发过程记录
└── openspec/                              # OpenSpec 配置