build(ports): 本地开发改用 7380/7381 避开端口冲突

AGENTS.md

@@ -138,3 +138,73 @@
 - Git 提交说明使用 `<type>(<scope>): <业务模块> - <变更摘要>`，`type` 为 `feat|fix|refactor|perf|docs|test|build|ci|chore|revert`。
 
 交付前至少检查：改动是否聚焦、调用方和类型是否同步、错误/权限/数据归属是否完整、必要文档是否同步、验证是否如实说明、是否留下密钥或本地数据。
+
+---
+
+# 本项目附加约定
+
+以上第 1–9 章继承自上游 `ddcat-ai/open-ai-canvas`。以下为本仓库（`ttstd-infinite-canvas`）在底座之上叠加的约定；**与上游冲突时以本章为准**。
+
+## A. 底座与上游同步
+
+本仓库以 `ddcat-ai/open-ai-canvas` 为底座，通过 Git remote 保持可追溯的上游关系：
+
+- `upstream` → `https://github.com/ddcat-ai/open-ai-canvas.git`（开发机上另存有一份克隆，可作离线 fetch 源）。
+- 同步新功能：`git fetch upstream && git merge upstream/main`。冲突优先保留上游实现，本仓库的差异应集中在 B~D 三项。
+- **功能一律优先使用上游源码实现**，不要在本仓库另起一套。确需偏离上游时，先在本章登记原因再改代码。
+- `libtv.html` 与 `libtv-前端技术分析.md` 是竞品运行时快照与分析资料，属于本地参考，不要当作上游代码改动。
+- 分支：本仓库工作分支为 `master`，上游为 `main`；`git pull upstream` 后按需合并。
+
+## B. 端口约定
+
+**不要改回上游默认的 3000 / 8080**——同机上 `infinite-canvas`、`open-ai-canvas`、`open-canvas` 都占用 3000，会互相抢占。
+
+| 场景 | 前端 | 后端 |
+| --- | --- | --- |
+| 本地开发（宿主机） | **7380** | **7381** |
+| Docker（宿主机映射） | **7380** → 容器 3000 | 不暴露（容器内仍 8080） |
+
+容器内部端口保持上游原样（nginx `listen 3000`、后端 `:8080`），以减小与上游的差异面。改端口时必须同步：
+
+- `web/package.json` — `dev` / `start` 的 `--port`
+- `web/vite.config.ts` — `apiProxyTarget` 默认值
+- `backend/cmd/server/main.go` — `CANVAS_BACKEND_ADDR` 默认值
+- `scripts/start-local.ps1` — 后端地址、代理目标、提示文案
+- `docker-compose.yml`、`docker-compose.local.yml` — 宿主机端口映射与 `CANVAS_CORS_ORIGINS`
+- `.env.example` — `CANVAS_CORS_ORIGINS`、`CANVAS_HTTP_PORT`
+- `README.md` 快速开始
+
+`docker-compose.deploy.yml` / `docker-compose.server.yml` 与 `scripts/install-server*.sh` 面向独立服务器部署，保留上游的 3000 默认值，不做本地化改动。
+
+`scripts/launch-canvas.ps1` 是上游维护者的个人脚本（硬编码 `D:\yingce\...`、`Administrator`、cloudflared 隧道），在本机不可用，**保持原样不要改**。
+
+## C. 许可与商标红线
+
+- 本仓库与上游均为 **MIT**。复制上游代码必须保留其版权声明与 `NOTICE`（声明 fork 自 `basketikun/infinite-canvas`，上游作者权利保留）。
+- **`tldraw` 许可非 MIT**：生产环境商用需购买 license key，否则必须保留 "Made with tldraw" 水印。上游已预留 `VITE_TLDRAW_LICENSE_KEY`（构建期）与 `tldraw_license_key`（运行时设置），对外商用前必须就此明确决策。
+- **不得新增他人 logo / 商标**：`web/public/icons/` 下的模型厂商图标、根 README 的赞助商与社群素材仅在上游语境下存在，对外分发前必须清理或替换为纯文字。
+- **禁止把带 GPL 组件的 ffmpeg 打进分发镜像**：服务端 ffmpeg 使用 LGPL 构建或由用户挂载（`CANVAS_FFMPEG_PATH`）。
+- 面向国内公众提供服务时，需处理 AI 生成内容标识、生成式 AI 服务备案与深度合成管理要求。
+
+## D. 进程清理（强制）
+
+验收或调试结束后清理进程时，**只允许按精确 PID 操作**，严禁用命令名、路径片段或宽正则批量匹配后终止。
+
+正确做法：
+
+1. `netstat -ano | Select-String 'LISTENING' | Select-String ':<端口>'` 拿到占用端口的 PID；
+2. `Get-Process -Id <pid>` 确认进程名与可执行文件路径确属本项目；
+3. `Stop-Process -Id <pid> -Force`；需要连带子进程时用 `taskkill /PID <pid> /T /F`。
+
+禁止的做法（已有实际事故）：
+
+- ❌ `Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'server\.exe' } | Stop-Process`
+  曾匹配到 IDE 的 `embeddings-server.exe`，导致误杀开发环境进程。
+- ❌ `-match 'vite'` / `-match 'node'` / `-match 'concurrently'` / `-match 'go'`
+  这些字符串同样会命中编辑器本体、语言服务器，以及同机上其它工程。
+
+补充要求：
+
+- 需要批量清理时，**先只打印**匹配结果（PID、进程名、完整命令行）供人工确认，确认后另起一步执行终止；不要在同一条命令里「查完即杀」。
+- 无法确认归属的进程一律不动，交回用户处理。同机存在多个同类工程时尤其要区分（例如 `infinite-canvas/web/.../vite.js` 与本项目的 `vite.js`）。
+- 误杀非本项目进程时，必须立即如实告知用户，说明进程名、可能影响与恢复方式，不要轻描淡写。