长任务后台化 xv-xiong/fast-long-task

fast-long-task

给 DeepSeek Harness 用的技能：让超过 60 秒的 Shell 任务不再阻塞会话。

它解决什么问题

在 DSH 里同步跑一条长命令（构建、全量测试、训练、批处理），会话会被卡住：模型只能等它返回，期间什么也做不了，而且一旦超时，输出还容易丢。

fast-long-task 把这套动作固化成规范：

- > 60 秒 → 一律后台跑（run_in_background: true）
- > 5 分钟 → 拆成可独立验收的子任务
- 每 30 秒 → 用 job_output(wait: true, timeout_ms: 30000) 检查，而不是 sleep 空转
- 终态后 → 才做验收（退出码 / 产物 / 结果）
- 失败时 → 先读报错，只重跑最小子任务
- 同时 ≤ 10 个 → 后台任务并发上限

效果（本机实测）

工作负载：scripts/bench-workload.ps1 -Shards 8 -Seconds 5（8 个分片，每片 5 秒），同一台机器、同一批次跑基线（前台同步）与技能模式（8 个后台分片）。

| 指标 | 基线（同步执行） | 技能模式（后台） | 变化 |
| 会话阻塞时长 | 41.65 s | 0.24 s | -99.4% |
| 等待期间可完成的独立步骤 | 0 | 1 | +1 |
| 总墙钟 | 40.14 s | 11.38 s | -71.6% |
| 后台任务并发峰值 | 0 | 8 | ≤ 10 上限内 |

阻塞时长取自 DSH 会话日志的 tool/call → tool/result 间隔，可用 scripts/bench-analyze.ps1 复算。完整协议见 docs/efficiency.md，原始数据见 bench/results.json。

总墙钟下降是因为分片可并行；若任务不可并行（如训练），总墙钟应基本持平，收益只体现在会话阻塞上。详见 skills/fast-long-task/examples/training-run.md。

安装

技能就是一组 Markdown 文件，无运行时依赖。

推荐：装一份到用户级技能根 ~/.agents/skills，任意工作区都生效（单副本，无同步问题） pwsh -File scripts/install.ps1

先看会做什么，不落盘 pwsh -File scripts/install.ps1 -DryRun

只读检查：各处候选根装了哪些副本 pwsh -File scripts/install.ps1 -Verify

手动安装等价于把 skills/fast-long-task/ 整个目录复制到 ~/.agents/skills/fast-long-task/。

本项目只推荐用户级单副本。默认装 rank 500 的 ~/.agents/skills，因为 ~/.dsh/skills（rank 400）在部分 profile 的 preset 组合下实测未被扫描——详见 docs/installation.md。-Scope Project / -Scope Both 仅为特殊场景保留，同时装两份时必须手工同步。

使用

模型侧：skill(name: "fast-long-task")
用户侧：输入 /fast-long-task

加载后按正文的 6 步流程执行即可；需要查参数、排障或看场景示例时，再按"按需查阅"表加载 references/、examples/。

仓库结构

fast-long-task/
├── skills/fast-long-task/
│ ├── SKILL.md # 技能入口（frontmatter + 正文） │ ├── references/ # 细节附录：速查表、故障排查 │ └── examples/ # 场景示例：构建测试、数据分片、训练 ├── scripts/ │ ├── install.ps1 # 安装到用户级/项目级技能根 │ ├── verify-skill.ps1 # 规范校验（7 类检查） │ ├── bench-workload.ps1 # 基准工作负载 │ ├── export-session.ps1 # 导出 DSH 会话日志（多帧 zstd） │ ├── bench-analyze.ps1 # 统计会话阻塞时长 │ └── bench-report.ps1 # 生成对比表 ├── bench/ │ ├── README.md # 基准复现说明 │ └── results.json # 本机实测数据 ├── docs/ # 定位、安装、验证、效率、发布 ├── .github/ # CI + Issue/PR 模板 ├── CHANGELOG.md ├── CONTRIBUTING.md └── LICENSE # MIT

验证

规范校验（结构 / frontmatter / 正文预算 / 引用可达 / 占位符 / 开源配套） pwsh -File scripts/verify-skill.ps1

安装并自检 pwsh -File scripts/install.ps1 -Force

确认单副本（只读）

pwsh -File scripts/install.ps1 -Verify

在 DSH 中确认可用：见 docs/verification.md。

兼容性

- DSH：0.2.0-rc.2（当前桌面版，已实测）。技能只用 pwsh + job_output/job_list/job_kill，不调内部 API，对版本不敏感。
- PowerShell：7.x（脚本依赖 pwsh）
- 运行时依赖：无

范围

只覆盖长耗时 Shell 任务的后台化执行。不做任务调度框架、不接管其他 harness、不引入额外依赖。

许可证

MIT © 2026 xv-xiong