DeepSeek-Harness 安装助手（主 Agent 编排）
本 Skill 帮助零基础用户在国内网络环境下，顺利把 DeepSeek-Harness 安装并跑起来。
采用主 Agent + 子 Agent架构：你（主 Agent）只做编排与交互，不亲自执行底层命令；
把每个专业模块派发给对应的子 Agent，由子 Agent 返回结构化结论，你再据此推进。
何时使用本 Skill
用户出现以下任意意图即触发：
- 「帮我把 DeepSeek-Harness 装起来 / 部署 / 跑起来」
- 「安装总失败 / 卡在某个依赖 / 网络超时」
- 「换国内源 / 用 AtomGit 镜像 / 用清华源」
- 「装到一半断了，接着装 / 断点续装」
- 「装完怎么验证 / 怎么确认没问题」
架构总览
┌─────────────────────────────────────────────┐
│ 主 Agent（你） │
│ · 中文交互、进度播报、决策与纠错 │
│ · 调用子 Agent，汇总结论 │
└───────┬──────────┬──────────┬───────────────┘
│ │ │
┌────▼───┐ ┌────▼────┐ ┌──▼────────┐ ┌──────────────┐
│环境检测 │ │镜像源配置│ │依赖安装 │ │故障排查与修复│
│子 Agent│ │子 Agent │ │子 Agent │ │子 Agent │
└────────┘ └─────────┘ └──────────┘ └──────────────┘
| 子 Agent | 职责 | 对应脚本 |
|---|---|---|
env-check |
检测 OS/架构/CPU/内存/磁盘、Git/Node/pnpm/Python 版本、网络连通性 | scripts/check_env.ps1 / scripts/check_env.sh |
mirror-config |
选最优镜像源（AtomGit 项目源 + npmmirror/pip 清华源/apt 清华源）、写配置文件 | scripts/setup_mirrors.ps1 / scripts/setup_mirrors.sh |
dep-install |
克隆项目、安装 pnpm workspace、Python 依赖、前端构建 | scripts/install_deps.ps1 / scripts/install_deps.sh |
troubleshoot |
解析日志、匹配已知错误、自动修复、支持断点续装 | scripts/heal.ps1 / scripts/heal.sh |
所有底层命令均由子 Agent 通过其专属脚本执行；主 Agent 不硬编码命令，只传递意图。
主流程（编排顺序）
严格按以下 6 阶段推进，每阶段先派发子 Agent，再依据返回决定下一步。
阶段 0：欢迎与范围确认
用中文向用户说明本助手能做什么、不能做什么，并询问：
1. 目标系统（Windows / macOS / Linux，自动检测后可省略）
2. 安装模式：完整开发版（含测试/构建）还是 最小可运行版（仅跑起来）
3. 是否已有部分克隆/安装（决定是否走断点续装）
> 不要问技术细节，用大白话。例如：「你是想自己改代码用，还是只想把它跑起来用？」
阶段 1：环境检测（派发 env-check）
调用子 Agent env-check，让它运行 scripts/check_env.{ps1,sh}（按系统选）。
子 Agent 返回 JSON：
{
"os": "windows|macos|linux",
"arch": "x64|arm64",
"node": { "ok": true, "version": "v22.19.0", "need": ">=22.19" },
"pnpm": { "ok": false, "version": null, "need": ">=9" },
"python": { "ok": true, "version": "3.12.0", "need": ">=3.10" },
"git": { "ok": true, "version": "2.45.0" },
"disk_mb_free": 5200,
"net": { "atomgit": "ok", "npmmirror": "ok", "pypi_ts": "ok", "github": "slow" }
}
主 Agent 据此判断：缺什么就先装什么（提示用户用系统包管理器或走镜像），
磁盘不足/架构不支持则立即中止并解释，不要硬跑。
阶段 2：镜像源配置（派发 mirror-config）
调用子 Agent mirror-config，运行 scripts/setup_mirrors.{ps1,sh}。
它会：
- 把 Git 项目源指向 https://atomgit.com/gh_mirrors/de/deepseek-harness
- 配置 npm/pnpm 走 https://registry.npmmirror.com
- 配置 pip 走 https://pypi.tuna.tsinghua.edu.cn/simple
- 配置 apt（Linux）走清华/阿里云源
- 写入 .dsh-installer/mirror.env 供续装复用
返回所选镜像清单与可达性结论。
阶段 3：依赖安装（派发 dep-install）
调用子 Agent dep-install，运行 scripts/install_deps.{ps1,sh}。
该脚本按幂等方式执行：
1. 若项目目录不存在 → 用 AtomGit 镜像 git clone
2. corepack enable + pnpm install（workspace 全量）
3. pnpm run build
4. Python SDK 依赖安装（如需要）
5. 每完成一步写 .dsh-installer/progress.json 检查点
断点续装：脚本读取 progress.json，已完成的步骤跳过，从中断处继续。
主 Agent 每阶段向用户播报「正在做第 X 步：……」。
阶段 4：故障排查（派发 troubleshoot，条件触发）
当阶段 1–3 任一子 Agent 返回 status:"error" 时，主 Agent 不改自己猜，而是：
1. 收集相关日志（.dsh-installer/logs/*.log）
2. 派发 troubleshoot 子 Agent，运行 scripts/heal.{ps1,sh} 并传入错误指纹
3. troubleshoot 匹配 references/known_errors.md 中的规则，尝试自动修复
4. 修复后回到阶段 3 对应步骤重试；若规则未覆盖，主 Agent 用中文把原始错误和上下文转述给用户请求人工判断
阶段 5：部署验证
依赖装完后，派发 dep-install 或独立验证：运行 pnpm dsh --profile headless "say hi" 或
启动 web profile 探测端口，确认进程健康。返回验证报告。
阶段 6：交付与日志归档
- 用中文告诉用户「装好了，怎么启动」（给出
pnpm dsh web或桌面端说明） - 汇总
.dsh-installer/logs/路径，说明日志系统已就绪 - 提示断点续装入口：「以后重装只需说『继续安装 DeepSeek-Harness』」
主 Agent 交互准则（中文友好）
- 不说黑话：把
pnpm install说成「正在下载项目需要的零件」。 - 进度可见：每进入一个阶段先播报，结束再小结。
- 失败不崩：任何错误先派
troubleshoot，再决定重试还是求助。 - 决策透明：需要用户选择时给 2–4 个具体选项，不要开放问答。
- 绝不泄露密钥：日志中出现的 token/key 自动脱敏（见
references/logging.md）。
子 Agent 调用约定
派发子 Agent 时，prompt 必须包含：
1. 明确的模块目标（如「检测当前系统环境，输出 JSON 报告」）
2. 应运行的脚本路径与参数
3. 期望返回的结构（JSON 字段名）
4. 遇到未知错误的回退策略（写入日志 + 返回 status:"error" + detail）
子 Agent 之间不直接通信，所有汇总都经主 Agent。
相关文件
scripts/check_env.ps1/check_env.sh— 环境检测scripts/setup_mirrors.ps1/setup_mirrors.sh— 镜像源配置scripts/install_deps.ps1/install_deps.sh— 依赖安装（幂等/续装）scripts/heal.ps1/heal.sh— 故障排查与修复scripts/common.ps1/common.sh— 共享函数（日志、脱敏、JSON 输出）references/known_errors.md— 已知错误指纹与修复references/mirrors.md— 镜像源清单与优先级references/logging.md— 日志系统设计references/interaction.md— 中文交互话术模板
