| name | funasr-task-manager-init |
| description | Bootstrap the funasr-task-manager development environment from scratch. Use when: first-time setup, checking if repo is cloned, installing dependencies (Python/Unicorn or Docker), or starting backend/frontend services for the first time.
|
适配项目版本：V0.4.28-Build0476-20260518
环境初始化与启动
funasr-task-manager-init 负责所有前期环境准备工作：检查仓库是否已克隆、判断后端/前端是否已启动、根据用户选择的环境方式完成安装并启动服务。
触发条件
自动触发
- Agent 首次接触本项目时
- 用户执行任何需要后端运行的操作（如转写、benchmark），但后端不可达时
GET /health 返回连接失败或非 200 时
用户显式触发
- 用户说"初始化环境""安装项目""启动后端""setup""init"
- 用户说"换 Docker 部署""重新安装"
关键词
初始化 / 安装 / 部署 / 启动 / setup / init / bootstrap / docker / unicorn / 环境
执行流程
Phase 1：检查仓库状态
- 检查当前工作目录是否为
funasr-task-manager 仓库
Phase 2：检查后端运行状态
-
检查后端是否已启动（核心判断条件，Agent 工作流仅依赖后端 API）
- 请求
GET http://localhost:15797/health
- 返回
{"status": "ok"} → 后端已运行，进入 Step 2（版本一致性校验）
- 连接失败或非 200 → 后端未启动，跳过版本校验，直接进入 Phase 3
-
版本一致性校验（后端可达时必须执行）
从 /health 响应中提取 version、git_sha、started_at，与本地仓库比对：
HEALTH=$(curl -sf http://localhost:15797/health)
RUNNING_VERSION=$(echo "$HEALTH" | python3 -c "import sys,json; print(json.load(sys.stdin)['version'])")
RUNNING_SHA=$(echo "$HEALTH" | python3 -c "import sys,json; print(json.load(sys.stdin)['git_sha'])")
RUNNING_STARTED=$(echo "$HEALTH" | python3 -c "import sys,json; print(json.load(sys.stdin)['started_at'])")
REPO_VERSION=$(grep -m1 '^version' 3-dev/src/backend/pyproject.toml | sed 's/.*"\(.*\)".*/\1/')
REPO_SHA=$(git rev-parse --short HEAD)
比对规则（两项都必须检查，任一不匹配即视为版本不一致）：
| 检查项 | 运行中 | 仓库 | 一致？ |
|---|
| app_version | {RUNNING_VERSION} | {REPO_VERSION} | ✅/❌ |
| git_sha | {RUNNING_SHA} | {REPO_SHA} | ✅/❌ |
-
两项均一致 → 报告"环境就绪，版本一致"
-
任一不一致 → 输出告警并询问用户是否重启：
⚠️ 后端版本与仓库不一致：
| 运行中 | 仓库 |
|---|
| version | {RUNNING_VERSION} | {REPO_VERSION} |
| git_sha | {RUNNING_SHA} | {REPO_SHA} |
| 启动时间 | {RUNNING_STARTED} | |
后端正在运行旧版本代码，可能缺少最新功能或修复。
- 重启后端服务（推荐） — 让后端加载最新代码
- 跳过 — 继续使用当前运行的版本
-
用户选择重启 → 执行重启逻辑：
if systemctl --user is-active funasr-task-manager-backend &>/dev/null; then
systemctl --user restart funasr-task-manager-backend
echo "⏳ 正在通过 systemd 重启后端..."
else
PID=$(lsof -ti:15797 2>/dev/null)
if [ -n "$PID" ]; then
kill "$PID"
sleep 2
fi
cd 3-dev/src/backend
nohup uvicorn app.main:app --host 0.0.0.0 --port 15797 --reload &
echo "⏳ 正在重新启动后端..."
fi
sleep 5
-
重启后重新校验：再次请求 /health，确认 git_sha 与仓库一致
-
校验通过 → 报告"环境就绪，版本已更新"
-
仍不一致 → 警告但不阻断，记录问题后继续
-
判断结果：
- 后端已运行且版本一致 → 报告"环境就绪"，询问是否执行后续可选阶段：
环境已就绪。是否还需要：
- 安装/更新 Skills 到 Agent 平台（Phase 6）
- 配置渠道凭据（Phase 7）
- 注册后端为 systemd 服务（Phase 8，仅 Linux）
- 不需要，退出
- 后端未启动 → 进入 Phase 3
注意：前端（http://localhost:15798）是 Web UI，供人类操作员使用，Agent 工作流不依赖前端。不检查、不启动前端。
Phase 3：选择安装方式
向用户询问（二选一）：
检测到服务未启动，请选择安装方式：
- Python 环境（推荐开发）— 使用 Unicorn 管理 Python 3.13 环境
- Docker 环境（推荐部署）— 使用 Docker Compose 一键启动
用户选择后进入对应分支。
Phase 4A：Python 环境安装
按顺序执行以下步骤：
Step 1：检查现有 Python 环境是否已满足
先检查系统 Python 是否已经具备运行后端的全部依赖：
python3 -c "import fastapi; import sqlalchemy; import uvicorn; print('OK')" 2>/dev/null
- 输出
OK → 跳过 Step 2-3，直接进入 Step 4（现有环境已可用）
- 失败 → 继续 Step 2
Step 2：尝试 Unicorn 环境（优先但非必选）
which unicorn && unicorn --version
Step 3：安装后端依赖
cd 3-dev/src/backend
pip install -e ".[dev]"
如果 pyproject.toml 不存在 .[dev]，则回退到：
pip install -r requirements.txt
验证核心依赖：
python3 -c "import fastapi; import sqlalchemy; import uvicorn; print('OK')"
Step 4：检查 ffmpeg / ffprobe
VAD 分段并行转写（长音频自动切分）依赖 ffprobe 获取精确时长，ffmpeg 用于静音检测和物理切段。缺少时分段功能会静默 fallback 到整文件转写，性能大幅下降。
ffprobe -version
ffmpeg -version
- 两者均可用 → 继续
- 不可用 → 按平台安装：
- 安装后再次验证
ffprobe -version
Step 5：初始化数据库
cd 3-dev/src/backend
python -m alembic upgrade head
Step 6：启动后端
cd 3-dev/src/backend
uvicorn app.main:app --host 0.0.0.0 --port 15797 --reload
启动后等待 5 秒，验证 GET http://localhost:15797/health 返回 {"status": "ok"}。
Step 7：验证 CLI 配置
后端启动后，必须确认 CLI 指向正确的后端地址。CLI 默认从 ~/.asr-cli.yaml 读取 server 字段，如果残留旧配置（如端口 28000），CLI 会静默连接到错误地址并报告空错误。
cd 3-dev/src/backend
python -m cli config get server
验证 CLI 可达后端：
python -m cli health
应返回 {"status": "ok"} 或类似健康信息。如果报 无法连接到服务器，检查上一步的地址设置和后端运行状态。
后端启动 + CLI 配置验证后即可进入 Phase 5。 前端（Vue Web UI）是可选的，Agent 工作流不依赖前端。
Phase 4B：Docker 环境安装
Step 1：检查 Docker 是否可用
docker --version
docker compose version
- 两者均可用 → 继续
- Docker 不可用 → 引导安装：
Step 2：检查 Docker 运行状态
docker info
- 正常输出 → 继续
- 报错"Cannot connect to the Docker daemon" → 提示启动 Docker Desktop 或
sudo systemctl start docker
Step 3：检查系统资源
- 可用内存 >= 4GB（推荐 8GB）
- 可用磁盘 >= 5GB
- 不满足 → 警告但不阻断
Step 4：构建并启动
docker compose up -d --build
等待容器启动，验证：
docker compose ps
验证 GET http://localhost:15797/health 返回 {"status": "ok"}。
Phase 5：启动验证与报告
所有步骤完成后，输出验证报告：
✅ funasr-task-manager 后端已就绪
安装方式: {python/docker}
后端地址: http://localhost:15797
健康检查: ✅ 通过
版本校验: ✅ version={版本号} git_sha={SHA}
CLI 配置: ✅ server = http://localhost:15797
数据库: ✅ 已迁移到最新版本
ffprobe: ✅ 可用（版本 x.x.x）
下一步:
- 注册 FunASR 服务器: python -m cli server register <ws://...>
- 上传并转写: python -m cli transcribe <audio-file>
输出报告后，必须询问用户是否执行 Phase 6/7/8（不可跳过此询问）：
是否需要执行以下可选配置？
- 安装/更新 ASR Skills 到 Agent 平台（推荐）
- 配置飞书/企微/Slack 渠道凭据
- 注册后端为 systemd 用户级服务（仅 Linux，无需 sudo，开机自启 + 崩溃重启）
- 全部执行
- 跳过
Phase 5.5：创建批量转写运行时目录
目的：为 funasr-task-manager-local-batch-transcribe Skill 幂等创建运行时目录结构。后端健康检查通过后自动执行，无需用户确认。
幂等创建逻辑（Linux/macOS）：
BATCH_ROOT="{repo_root}/runtime/agent-local-batch"
for dir in inbox processing outputs manifests logs archive; do
mkdir -p "$BATCH_ROOT/$dir"
touch "$BATCH_ROOT/$dir/.gitkeep"
done
echo "✅ 批量转写运行时目录已就绪: $BATCH_ROOT"
Windows PowerShell：
$BatchRoot = "{repo_root}\runtime\agent-local-batch"
@("inbox","processing","outputs","manifests","logs","archive") | ForEach-Object {
$dir = Join-Path $BatchRoot $_
New-Item -ItemType Directory -Force -Path $dir | Out-Null
$gitkeep = Join-Path $dir ".gitkeep"
if (-not (Test-Path $gitkeep)) { New-Item -ItemType File -Path $gitkeep | Out-Null }
}
Write-Host "✅ 批量转写运行时目录已就绪: $BatchRoot"
验证：确认 6 个子目录存在且各含 .gitkeep。
目录用途说明：
| 子目录 | 用途 |
|---|
inbox/ | 待处理的源音视频文件（默认扫描入口） |
processing/ | 正在处理中的文件暂存（防止重复提交） |
outputs/ | 转写结果归档（按 batch_id 分目录） |
manifests/ | 批次清单 JSON 文件（状态持久化） |
logs/ | 批次执行日志 |
archive/ | 历史已完成批次的归档 |
注意：此步骤为自动执行，无需用户选择。如果目录已存在则幂等跳过。
Phase 6：安装 Skills 到 Agent 平台
目的：将 6-skills/ 下的所有 Skill 安装到 Agent 平台的自动加载目录，使 Agent 启动时即具备 ASR 转写能力，不需要用户手动指挥"去 repo 里学一下 skill"。
向用户询问：
是否需要将 ASR Skills 安装到 Agent 平台？安装后 Agent 启动时会自动加载这些技能，可以自主识别文件并完成转写。
请问你使用的是哪个 Agent 平台？
- OpenClaw — Skills 安装到
~/.openclaw/workspace-{name}/skills/
- Hermes — Skills 安装到
~/.hermes/skills/
- Cursor — Skills 安装到
{project}/.cursor/skills/ 或 ~/.cursor/skills-cursor/
- 其他 / 不安装 — 跳过此步骤
用户选择后进入对应分支。
6A：OpenClaw
先确定 workspace 名称（向用户询问或自动检测当前活跃 workspace）：
ls ~/.openclaw/workspace-*/
WORKSPACE_NAME="<用户确认的 workspace 名>"
WORKSPACE_SKILLS="$HOME/.openclaw/workspace-$WORKSPACE_NAME/skills"
REPO_SKILLS="{repo_root}/6-skills"
mkdir -p "$WORKSPACE_SKILLS"
for skill_dir in "$REPO_SKILLS"/funasr-task-manager-*/; do
skill_name=$(basename "$skill_dir")
rm -rf "$WORKSPACE_SKILLS/$skill_name"
cp -r "$skill_dir" "$WORKSPACE_SKILLS/$skill_name"
echo "✅ $skill_name"
done
WORKSPACE_ROOT="$HOME/.openclaw/workspace-$WORKSPACE_NAME"
cp "$REPO_SKILLS/_shared/ASR-WORKFLOW.md" "$WORKSPACE_ROOT/ASR-WORKFLOW.md"
echo "✅ ASR-WORKFLOW.md"
if grep -q "BEGIN:funasr-task-manager" "$WORKSPACE_ROOT/AGENTS.md" 2>/dev/null; then
sed '/<!-- BEGIN:funasr-task-manager/,/<!-- END:funasr-task-manager/d' "$WORKSPACE_ROOT/AGENTS.md" > "$WORKSPACE_ROOT/AGENTS.md.tmp"
mv "$WORKSPACE_ROOT/AGENTS.md.tmp" "$WORKSPACE_ROOT/AGENTS.md"
fi
cat "$REPO_SKILLS/_shared/AGENTS-asr-section.md" >> "$WORKSPACE_ROOT/AGENTS.md"
echo "✅ AGENTS.md 已追加 ASR 转写段落"
验证：
ls "$WORKSPACE_SKILLS"/funasr-task-manager-*/SKILL.md | wc -l
test -f "$WORKSPACE_ROOT/ASR-WORKFLOW.md" && echo "✅ ASR-WORKFLOW.md 已安装"
6B：Hermes
HERMES_SKILLS="$HOME/.hermes/skills"
REPO_SKILLS="{repo_root}/6-skills"
mkdir -p "$HERMES_SKILLS"
for skill_dir in "$REPO_SKILLS"/funasr-task-manager-*/; do
skill_name=$(basename "$skill_dir")
rm -rf "$HERMES_SKILLS/$skill_name"
cp -r "$skill_dir" "$HERMES_SKILLS/$skill_name"
echo "✅ $skill_name"
done
HERMES_ROOT="$HOME/.hermes"
cp "$REPO_SKILLS/_shared/ASR-WORKFLOW.md" "$HERMES_ROOT/ASR-WORKFLOW.md"
echo "✅ ASR-WORKFLOW.md"
if grep -q "BEGIN:funasr-task-manager" "$HERMES_ROOT/AGENTS.md" 2>/dev/null; then
sed '/<!-- BEGIN:funasr-task-manager/,/<!-- END:funasr-task-manager/d' "$HERMES_ROOT/AGENTS.md" > "$HERMES_ROOT/AGENTS.md.tmp"
mv "$HERMES_ROOT/AGENTS.md.tmp" "$HERMES_ROOT/AGENTS.md"
fi
cat "$REPO_SKILLS/_shared/AGENTS-asr-section.md" >> "$HERMES_ROOT/AGENTS.md"
echo "✅ AGENTS.md 已追加 ASR 转写段落"
6C：Cursor
Cursor 的 skill 目录分为用户级和项目级：
- 用户级（所有项目共享）：
~/.cursor/skills-cursor/
- 项目级（仅当前项目）：
{project}/.cursor/skills/
推荐安装到项目级目录：
Linux / macOS：
PROJECT_SKILLS="{repo_root}/.cursor/skills"
REPO_SKILLS="{repo_root}/6-skills"
mkdir -p "$PROJECT_SKILLS"
for skill_dir in "$REPO_SKILLS"/funasr-task-manager-*/; do
skill_name=$(basename "$skill_dir")
rm -rf "$PROJECT_SKILLS/$skill_name"
ln -sfn "$(cd "$skill_dir" && pwd)" "$PROJECT_SKILLS/$skill_name"
echo "✅ $skill_name"
done
Windows PowerShell：
$ProjectSkills = "{repo_root}\.cursor\skills"
$RepoSkills = "{repo_root}\6-skills"
New-Item -ItemType Directory -Force -Path $ProjectSkills | Out-Null
Get-ChildItem -Directory "$RepoSkills\funasr-task-manager-*" | ForEach-Object {
$target = Join-Path $ProjectSkills $_.Name
if (Test-Path $target) { Remove-Item $target -Recurse -Force }
# 符号链接需要管理员权限，降级为目录拷贝
Copy-Item -Recurse $_.FullName $target
Write-Host "✅ $($_.Name)"
}
6D：跳过
记录日志，提示用户可以稍后手动安装：
ℹ️ 已跳过 Skill 安装。如需后续安装，请将 6-skills/funasr-task-manager-*/ 目录
复制或链接到你的 Agent 平台的 skills 加载目录。
安装后验证
输出已安装的 8 个 Skill 清单 + ASR-WORKFLOW.md 状态，确认安装目录和数量。
Phase 7：配置渠道凭据与实时通知（可选）
如果 Agent 需要通过聊天渠道（飞书、企业微信、Slack 等）接收用户文件或发送实时进度通知，必须预配置渠道 API 凭据。否则 Agent 在收到文件时会花数分钟探索鉴权路径，通知功能也无法正常工作。
向用户询问：
Agent 是否需要从聊天渠道接收文件 / 发送实时通知？
- 飞书/Lark — 需要
app_id + app_secret
- 企业微信 — 需要
corpid + corpsecret
- Slack — 需要 Bot OAuth Token
- 不需要 / 仅 CLI — 跳过
各渠道的详细配置步骤、环境变量写入方式和验证命令见 references/channel-credentials.md。
7.1 配置实时通知凭据（飞书选项额外步骤）
当用户选择飞书时，除了配置文件下载凭据外，还需配置 notify 子系统以支持 send_user_notice() 的 CLI fallback：
cd 3-dev/src/backend
python -m cli config set notify.feishu_app_id "cli_xxxxxxxxxxxx"
python -m cli config set notify.feishu_app_secret "xxxxxxxxxxxxxxxxxxxxxxxx"
python -m cli config set notify.default_chat_id "oc_xxxxxxxxxxxxxxxxxxxxxxxx"
说明：
notify.feishu_app_id / notify.feishu_app_secret：与文件下载使用相同的飞书应用凭据即可notify.default_chat_id：CLI 本地手动调试的默认群聊 ID（从飞书群设置中获取）；Agent/Skill 自动通知仍应显式传入本轮会话的 --chat-id- 这些值存储在
~/.asr-cli.yaml 的 notify: 段落中
验证配置是否正确：
python -m cli notify auth-check
发送测试消息：
python -m cli notify send --text "🔔 通知系统测试：如果你看到这条消息，说明 notify 配置成功"
这条测试命令用于验证刚配置的默认 notify.default_chat_id。Agent/Skill 工作流中的正式通知必须显式传入 --chat-id；私聊还必须传入 --receive-id-type open_id。
注意：
- 如果 Agent 运行在 OpenClaw 环境中，
send_user_notice() 会优先使用平台自带的 message tool，CLI notify 仅作为 fallback
- 即使在 OpenClaw 环境中，也建议配置 CLI notify 凭据作为降级保障
- 环境变量
FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_CHAT_ID 可覆盖配置文件中的值；FEISHU_CHAT_ID 仅作为本地默认路由，不作为 Agent/Skill 自动通知的隐式目标
Phase 7.5：OpenClaw 部署同步检查（OpenClaw 环境强制）
当 Phase 6 选择了 OpenClaw 平台时，必须执行部署同步检查，确保 OpenClaw workspace 中的 CLI 工具和 Skill 版本与源仓库一致。
7.5a：检查 cli notify 是否可用
WORKSPACE_ROOT="$HOME/.openclaw/workspace-$WORKSPACE_NAME"
cd "$WORKSPACE_ROOT"
if [ -d "3-dev/src/backend/cli" ] || [ -f "3-dev/src/backend/pyproject.toml" ]; then
cd 3-dev/src/backend
CLI_NOTIFY_OUTPUT=$(python -m cli notify send --help 2>&1)
CLI_NOTIFY_STATUS=$?
if [ $CLI_NOTIFY_STATUS -eq 0 ] && ! echo "$CLI_NOTIFY_OUTPUT" | grep -q "\-\-receive-id-type"; then
CLI_NOTIFY_STATUS=1
echo "⚠️ cli notify send 缺少 --receive-id-type 参数，需要更新 CLI"
else
echo "$CLI_NOTIFY_OUTPUT" | head -3
fi
else
CLI_NOTIFY_STATUS=1
echo "⚠️ OpenClaw workspace 中未发现 CLI 代码（3-dev/src/backend/cli 不存在）"
fi
7.5b：检查 Skill 版本一致性
REPO_SKILLS="{repo_root}/6-skills"
WORKSPACE_SKILLS="$HOME/.openclaw/workspace-$WORKSPACE_NAME/skills"
for skill_dir in "$REPO_SKILLS"/funasr-task-manager-*/; do
skill_name=$(basename "$skill_dir")
if [ ! -d "$WORKSPACE_SKILLS/$skill_name" ]; then
echo "❌ $skill_name 未安装到 workspace"
else
diff_count=$(diff -rq "$skill_dir" "$WORKSPACE_SKILLS/$skill_name" 2>/dev/null | wc -l)
if [ "$diff_count" -gt 0 ]; then
echo "⚠️ $skill_name 与源仓库有 $diff_count 处差异"
else
echo "✅ $skill_name 一致"
fi
fi
done
7.5c：版本声明检查
if grep -q "cli_min_version" "$WORKSPACE_ROOT/ASR-WORKFLOW.md" 2>/dev/null; then
echo "✅ CLI 最低版本声明存在"
else
echo "⚠️ ASR-WORKFLOW.md 中缺少 CLI 最低版本声明"
fi
7.5d：输出同步报告
| 检查项 | 状态 | 说明 |
|---|
| CLI notify | ✅/❌ | 是否可执行 python -m cli notify |
| Skill 版本 | ✅/⚠️ | 各 Skill 是否与源仓库一致 |
| CLI 最低版本 | ✅/⚠️ | ASR-WORKFLOW.md 是否声明最低版本 |
如果存在 ❌ 或 ⚠️ 项，向用户提示：
⚠️ OpenClaw 部署环境存在不一致：
- {问题列表}
建议执行部署同步：重新运行 Phase 6 安装 Skills，并将 CLI 代码同步到 workspace。
详见 DEPLOY-SYNC.md。
Phase 8：systemd 用户级服务守护（可选，仅 Python 环境 + Linux）
仅适用于 Python 环境安装的后端（无论 Unicorn venv 还是系统 Python）。Docker 安装应使用 docker compose 的 restart: always，不需要本流程。
⚠️ 必须使用用户级服务（systemctl --user），不要使用系统级服务（/etc/systemd/system/）。
理由：后端以普通用户身份运行，所有文件在用户目录下，监听 15797 非特权端口，不需要 root 权限。使用用户级服务可以：
- 无需
sudo，Agent 可直接管理服务生命周期
- 与 OpenClaw、Hermes、Cursor 等同样运行在用户空间的 Agent 工具统一管理
- 避免系统级权限纠缠（之前系统级服务导致需要 sudo 的问题就此消除）
前置检查：uname -s 返回 Linux 且 which systemctl 成功且后端非 Docker 运行。非 Linux → 告知"仅适用于 Linux"，macOS 建议 nohup 或 launchd。
如果检测到旧的系统级服务：
if systemctl list-unit-files funasr-task-manager-backend.service | grep -q funasr; then
echo "⚠️ 检测到旧的系统级服务，需要先迁移"
fi
交互流程：
- 逐个候选 Python 执行
import uvicorn，仅验证通过的才可选定（路径存在 ≠ 可用），全部失败则中止
- 生成 service 文件内容，展示完整内容后请求用户确认再写入
- service 文件写入位置：
~/.config/systemd/user/funasr-task-manager-backend.service
- unit 文件关键差异（与系统级对比）：
- 不要包含
User= 行（用户级服务自动以当前用户运行）
WantedBy=default.target（而非 multi-user.target）
- 已有同名 service → 先展示 diff 让用户选择覆盖/跳过
systemctl --user daemon-reload && systemctl --user enable --now funasr-task-manager-backend- 等待 5 秒后验证
systemctl --user is-active funasr-task-manager-backend + curl /health
- 版本一致性校验（与 Phase 2 相同逻辑）：
- 从
/health 提取 git_sha，与 git rev-parse --short HEAD 比对
- 不一致 → 告警并询问是否
systemctl --user restart funasr-task-manager-backend
- 重启后重新校验直到一致
- 确保
loginctl enable-linger $USER（使服务在用户未登录时也能运行）
安全规则：写入 ~/.config/systemd/user/ 不需要 sudo。唯一可能需要 sudo 的操作是清理旧的系统级服务，此时必须展示完整命令让用户确认。
详细的 unit 文件模板、参数收集流程、验证输出和故障排查见 references/systemd-setup.md。
错误处理
| 场景 | Agent 应做的事 | 不应做的事 |
|---|
| CLI 报"无法连接到服务器"或错误信息为空 | 执行 python -m cli config get server 检查地址，确认是否指向正确的 http://localhost:15797；如不正确则 config set server 修正 | 假设后端未启动而反复重启；忽略空错误信息 |
| Unicorn 安装失败 | 回退到直接使用系统 Python，提示手动创建 venv | 放弃安装 |
| pip install 报错 | 展示完整错误日志，建议检查网络或 Python 版本 | 静默跳过 |
| ffprobe 安装失败 | 展示错误，提示手动安装方法；标记 warning 但不阻断后续步骤 | 跳过不报告（会导致分段功能静默失效） |
| Docker build 失败 | 展示 build 日志最后 30 行，分析原因 | 反复重试 |
| 端口被占用 | 提示杀掉占用进程或换端口 | 强制 kill |
| 数据库迁移失败 | 展示错误，建议 alembic downgrade base && alembic upgrade head | 删除数据库文件 |
| Skill 目录不存在 | 创建目录后重试 | 跳过 Skill 安装 |
| Agent 平台无法识别 | 提供通用说明，让用户手动复制到对应目录 | 猜测平台路径 |
| systemctl 不可用 | 提示替代方案（nohup、screen、tmux）或展示命令让用户手动执行 | 强行写入 |
| 已有系统级服务 | 引导用户先 sudo systemctl disable --now 旧服务再创建用户级服务 | 直接覆盖或同时运行两个实例 |
与其他 Skill 的关系
- 前置 Skill：本 Skill 是所有其他 Skill 的前置条件——后端不可达时，其他 Skill 均无法运行
- 被
funasr-task-manager-channel-intake 引用：intake 在 Phase 2 检查后端健康时，如果失败可引导用户进入本 Skill
- 被
funasr-task-manager-local-batch-transcribe 引用：batch-transcribe 在 Phase 0 检查后端时，如不可达则触发本 Skill；Phase 5.5 为其创建运行时目录
- 被
funasr-task-manager-server-benchmark 引用：benchmark 需要后端运行
相关文件
3-dev/src/backend/pyproject.toml 或 requirements.txt：后端依赖3-dev/src/frontend/package.json：前端依赖docker-compose.yml：Docker 编排 / 3-dev/src/backend/alembic/：数据库迁移
