diff --git a/.gitignore b/.gitignore
index 3ef7aab..ffee6a0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,8 @@ __pycache__/
.vscode/
.idea/
*.log
+.logs/
+.pids/
# api
api/.venv/
diff --git a/.memory/worklog.json b/.memory/worklog.json
index e1be6c2..18395f6 100644
--- a/.memory/worklog.json
+++ b/.memory/worklog.json
@@ -1,19 +1,5 @@
{
"entries": [
- {
- "files_changed": 4,
- "hash": "aec7fda",
- "message": "auto-save 2026-05-13 18:57 (+1, ~3)",
- "ts": "2026-05-13T19:01:14+08:00",
- "type": "commit"
- },
- {
- "files_changed": 3,
- "hash": "6fb00da",
- "message": "auto-save 2026-05-13 19:06 (~3)",
- "ts": "2026-05-13T19:06:46+08:00",
- "type": "commit"
- },
{
"files_changed": 1,
"message": "Codex 会话活跃 · 最近命令:codex · 1 项未提交变更 · 最近提交:auto-save 2026-05-13 19:06 (~3)",
@@ -3250,6 +3236,19 @@
"message": "auto-save 2026-05-15 11:07 (~1)",
"hash": "9e5d853",
"files_changed": 1
+ },
+ {
+ "ts": "2026-05-15T11:12:45+08:00",
+ "type": "commit",
+ "message": "auto-save 2026-05-15 11:12 (~1)",
+ "hash": "4d66653",
+ "files_changed": 1
+ },
+ {
+ "ts": "2026-05-15T03:14:44Z",
+ "type": "session-heartbeat",
+ "message": "Codex 会话活跃 · 最近命令:codex · 1 项未提交变更 · 最近提交:auto-save 2026-05-15 11:12 (~1)",
+ "files_changed": 1
}
]
}
diff --git a/RULES.md b/RULES.md
index c5baa22..85c1e28 100644
--- a/RULES.md
+++ b/RULES.md
@@ -1,6 +1,8 @@
# SKG AI 素材管线 - TK 二创验证
## 启动
+- 后台启动(不弹 Terminal):`./scripts/start-dev-background.sh`(前端 4290 + 后端 4291,日志写入 `.logs/`)
+- 后台停止:`./scripts/stop-dev-background.sh`
- 前端 dev:`cd web && pnpm dev`(Next.js 16,端口 4290)
- 后端 dev:`cd api && uvicorn main:app --host 127.0.0.1 --port 4291`(FastAPI,端口 4291,重任务用)
- 注意:后端不要带 `--reload` 跑长下载 / 抽帧 / 音频任务;reload 会等待后台任务结束,导致 4291 端口占用但新请求卡住。
diff --git a/docs/source-analysis.html b/docs/source-analysis.html
index a9220a8..e3aa7f9 100644
--- a/docs/source-analysis.html
+++ b/docs/source-analysis.html
@@ -523,6 +523,16 @@
| 项目 | 命令 / 入口 | 说明 |
+
+ | 本地后台启动 |
+ ./scripts/start-dev-background.sh |
+ 不弹出 macOS Terminal 窗口;自动检查 4290 / 4291,缺哪个启动哪个,日志写入 .logs/,PID 写入 .pids/。 |
+
+
+ | 本地后台停止 |
+ ./scripts/stop-dev-background.sh |
+ 按 .pids/ 里的 PID 停止后台前端 / 后端进程。 |
+
| 前端开发服务 |
cd web && pnpm dev |
@@ -919,6 +929,17 @@ SubjectAsset {
变更记录
这个记录不是 git log 的替代品。它记录“产品理解发生了什么变化、影响了哪些源码、你以后描述需求时该怎么说”。后续每次改功能都要补一条。
+
+
+ 2026-05-15 · 本地启动改为后台不弹 Terminal
+ Runtime
+
+
+
问题:通过 macOS Terminal 启动后端会每次弹出一个终端窗口,打开页面时干扰使用。
+
改动:新增 scripts/start-dev-background.sh 和 scripts/stop-dev-background.sh。启动脚本自动检查前端 4290 和后端 4291,缺哪个后台启动哪个,日志写入 .logs/,PID 写入 .pids/,以后无需通过 osascript 打开 Terminal。
+
影响:scripts/start-dev-background.sh、scripts/stop-dev-background.sh、.gitignore、RULES.md、docs/source-analysis.html。
+
+
2026-05-14 · 产品融合按真实产品外置合成
diff --git a/scripts/start-dev-background.sh b/scripts/start-dev-background.sh
new file mode 100755
index 0000000..523d3ac
--- /dev/null
+++ b/scripts/start-dev-background.sh
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+API_DIR="$ROOT_DIR/api"
+WEB_DIR="$ROOT_DIR/web"
+LOG_DIR="$ROOT_DIR/.logs"
+PID_DIR="$ROOT_DIR/.pids"
+
+mkdir -p "$LOG_DIR" "$PID_DIR"
+
+port_is_listening() {
+ local port="$1"
+ lsof -tiTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1
+}
+
+start_api() {
+ if port_is_listening 4291; then
+ echo "api already running on 4291"
+ return
+ fi
+ if [[ ! -x "$API_DIR/.venv/bin/uvicorn" ]]; then
+ echo "missing api/.venv/bin/uvicorn" >&2
+ exit 1
+ fi
+ (
+ cd "$API_DIR"
+ nohup .venv/bin/uvicorn main:app --host 127.0.0.1 --port 4291 >> "$LOG_DIR/api.log" 2>&1 &
+ echo $! > "$PID_DIR/api.pid"
+ )
+ echo "api started on 4291, log: $LOG_DIR/api.log"
+}
+
+start_web() {
+ if port_is_listening 4290; then
+ echo "web already running on 4290"
+ return
+ fi
+ if ! command -v pnpm >/dev/null 2>&1; then
+ echo "missing pnpm in PATH" >&2
+ exit 1
+ fi
+ (
+ cd "$WEB_DIR"
+ nohup pnpm dev >> "$LOG_DIR/web.log" 2>&1 &
+ echo $! > "$PID_DIR/web.pid"
+ )
+ echo "web started on 4290, log: $LOG_DIR/web.log"
+}
+
+start_api
+start_web
+echo "open http://localhost:4290"
diff --git a/scripts/stop-dev-background.sh b/scripts/stop-dev-background.sh
new file mode 100755
index 0000000..717b691
--- /dev/null
+++ b/scripts/stop-dev-background.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PID_DIR="$ROOT_DIR/.pids"
+
+stop_pid_file() {
+ local name="$1"
+ local file="$PID_DIR/$name.pid"
+ if [[ ! -f "$file" ]]; then
+ echo "$name pid file not found"
+ return
+ fi
+ local pid
+ pid="$(cat "$file")"
+ if [[ -n "$pid" ]] && kill -0 "$pid" >/dev/null 2>&1; then
+ kill -TERM "$pid"
+ echo "$name stopped: $pid"
+ else
+ echo "$name already stopped"
+ fi
+ rm -f "$file"
+}
+
+stop_pid_file api
+stop_pid_file web