DeepSeek Harness Headless 模式：把 AI Agent 写进 CI/CD 流水线

DeepSeek Harness Headless 模式：把 AI Agent 写进 CI/CD 流水线

系列导航：本篇是 DeepSeek Harness 实战系列第 4 篇。前面讲了编码实战、框架对比、会话日志。本文聚焦一个把 DSH "产品化"的关键能力------Headless（无头）模式，也就是让 Agent 不依赖浏览器、不被人盯着，乖乖跑在脚本和流水线里。

引言：Agent 不止能"聊天"，还能"被调用"

前面几篇，我们都是"人坐在浏览器前面，和 Agent 对话"。这很好，但只发挥了 Agent 一半的威力。真正让它变成团队基础设施的，是另一半------让别的程序调用它。

DeepSeek Harness 的 Headless 模式干的就是这个。它启动一个 Agent，给它一个任务，它跑完把答案打印到 stdout，然后退出。没有浏览器、没有交互、没有"人"。这条命令本身就是一段可被脚本消费的程序：

dsh --profile headless "把本仓库的测试跑一遍，用中文总结失败原因并给出修复建议"

本文我会讲清：Headless 到底是什么、退出码怎么用、环境变量怎么配，以及------重点------如何把它接进 GitHub Actions、GitLab CI、pre-commit、定时任务，最终让你拥有"AI 审 PR""AI 跑测试""AI 值守"的自动化能力。

---

一、Headless 是什么：一次性、脚本化、退出码

用三句话定义 Headless：

1. 一次性（one-shot）：你给一个任务，它跑完就结束，不保持会话等待下一条消息。
2. 脚本化（scriptable）：它从命令行启动，答案走 stdout，适合被 shell/CI 调用。
3. 有退出码（exit code）：成功退 0，失败退非 0，天然适配 CI 的"非零即失败"语义。

这三点决定了它和 Web 模式的本质区别：Web 模式是"常驻服务 + 人交互"，Headless 是"短暂进程 + 程序调用"。前者像"你雇的个人助理随时待命"，后者像"你写的一个定时任务"。

---

二、最小可用：跑起来再说

最朴素的用法：

# 先设密钥
export DEEPSEEK_API_KEY=sk-xxx

# 跑一条任务
dsh --profile headless "Create fizz.py that prints FizzBuzz for 1..15 and run it; reply with the program output only."

社区实测输出：

1 2 Fizz 4 Buzz ... FizzBuzz

echo $?   # 0

六秒，文件创建、程序运行、答案打印、退出码 0。它只写你启动所在文件夹内的内容（默认 workspace-write 权限），stdout 只打印最终消息，并且把每一次运行都持久化------你之后能在 Web UI 里打开它，逐条读到它做了什么。

---

三、退出码语义：CI 的眼睛

退出码是 Headless 接入 CI 的关键。DSH 遵循 UNIX 惯例：

• exit 0：任务成功完成，stdout 是最终答案。
• 非 0：任务失败（模型报错、工具异常、超时、被权限拦截等）。

在 CI 里，一条非零退出会让整个 job 标红失败。这意味着你可以写：

- name: AI 跑测试
  run: dsh --profile headless "跑测试，失败就总结原因"
  # 若非零，CI 直接失败，阻断合并

比"人工看日志"靠谱------Agent 成了流水线的"守门员"，且失败时自动留下 transcript 供复盘。

---

四、环境变量：把配置从命令行解耦

Headless 的配置主要靠环境变量，避免把密钥/端点写进命令或仓库：

变量	作用	必填
DEEPSEEK_API_KEY	模型密钥	是（用 DeepSeek 时）
DEEPSEEK_BASE_URL	自定义 API 地址（走代理/网关）	否
DSH_MODEL	指定模型	否（用 settings 默认）
DSH_SYSTEM_PROMPT	注入系统提示	否
DSH_TELEMETRY_MODE	遥测开关（默认 disabled）	否

示例：走公司网关、用特定模型、关闭遥测：

export DEEPSEEK_API_KEY=sk-xxx
export DEEPSEEK_BASE_URL=https://gateway.internal/v1
export DSH_MODEL=deepseek-v4-pro
export DSH_TELEMETRY_MODE=disabled
dsh --profile headless "审查这个 PR 的 diff"

把密钥放进 CI 的 secret（而非明文），是基本安全纪律。

---

五、接进 GitHub Actions

最常见的落地：PR 创建时，让 Agent 跑测试并评论结果。一个 yml 骨架：

name: AI Test Runner
on: [pull_request]
jobs:
  ai-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '24' }
      - run: npm install -g @deepseek-ai/dsh
      - name: Run DSH headless
        env:
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        run: |
          dsh --profile headless "跑本仓库测试，用中文总结失败原因" \
            > result.txt
      - name: Comment result
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('result.txt','utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body
            });

这里 Agent 的 stdout 被重定向到 result.txt，再由 github-script 贴回 PR 评论。整条链路零人工：提交 → CI 触发 → Agent 跑测试 → 结果自动评论。

---

六、GitLab CI 示例

GitLab 同理，gitlab-ci.yml：

ai-review:
  image: node:24
  script:
    - npm install -g @deepseek-ai/dsh
    - dsh --profile headless "审查当前 MR 的改动，指出风险" | tee review.txt
  artifacts:
    paths: [review.txt]
  only: [merge_requests]

artifacts 把结果存档，评审人直接下载看。两条流水线的思路一致：Headless 的 stdout 就是 CI 的产出物。

---

七、本地 pre-commit 守卫

不想等 CI 红？把 Headless 塞进 pre-commit hook，本地就拦：

#!/bin/bash
# .git/hooks/pre-commit
dsh --profile headless "检查本次暂存的改动是否有明显回归风险，只回答 通过/不通过+原因"
# 非零则提交被拒

注意只做"快且确定"的检查（比如静态风险扫描），重活留给 CI------否则提交卡半天，团队会绕过 hook。

---

八、AI 审 PR 机器人

把第五节升华一下，做一个"AI 审查 bot"：监听 PR 事件 → 取 diff → 拼成任务给 Headless → 把审查意见贴回。伪代码：

on PR opened/updated:
  diff = get_pr_diff()
  task = f"你是资深 reviewer，审查以下 diff，按 风险/建议/必须改 三类给意见：\n{diff}"
  review = dsh --profile headless task
  post_comment(review)

比人工 review 快，且 24 小时在线。关键是把 diff 作为任务上下文喂进去------DSH 的上下文能力会妥善处理长 diff（配合 compaction）。

---

九、定时任务：cron + headless

让 Agent 定期值守，比如每天凌晨跑"依赖安全扫描"：

0 3 * * * cd /srv/proj && DEEPSEEK_API_KEY=xxx dsh --profile headless "检查依赖是否有已知漏洞，输出报告" >> /var/log/dsh-audit.log

cron 的 stdout 重定向 + Headless 的持久化，给你一份"每天自动审计、且随时可回放"的日志。

---

十、与 ACP（Agent Client Protocol）的关系

DSH 自带 acp 包------自动化专用的 Agent Client Protocol server。Headless 是"一次性 CLI 调用"，ACP 是"标准化的程序间通信协议"。区别：Headless 适合"丢一个任务等答案"，ACP 适合"需要持续交互、流式事件、多轮控制"的集成。简单自动化用 Headless 就够了；要深度嵌入你自己的 Agent 编排系统，上 ACP。

---

十一、systemd 常驻 + 队列

高并发场景（多个任务同时来），别每次起一个 Headless 进程（冷启动慢）。做法：把 dsh web 跑成 systemd 用户服务常驻，前面加一个队列，任务来了塞队列，worker 调 Web 的 headless 式接口执行。laserlloyd 的实测就是这么干的：systemd 服务 + iframe 嵌入聊天应用 + 队列化 headless 任务。

---

十二、输出解析：从 stdout 抽取答案

Headless 默认只打印最终消息，但你可能要结构化输出（比如 JSON）。两种办法：

1. 让模型输出 JSON：任务里写"只输出 JSON，字段为 {passed: bool, reason: str}"。简单但依赖模型听话。
2. 从 transcript 取：运行后从会话日志（transcript）里取结构化事件，比解析 stdout 稳。适合要求严谨的场景。

生产建议：需要机器消费的结果，优先从 transcript/事件流取，别只信 stdout 文本。

---

十三、失败重试与幂等

CI 里网络抖动能让 Headless 偶发失败。加重试：

for i in 1 2 3; do
  dsh --profile headless "..." && break
  sleep 5
done

但重试要求任务幂等------同一条任务跑两次不产生副作用（比如别让 Agent 重复提交两次 PR）。让 Agent 的任务描述带"若已存在则跳过"的指令，或在外部用锁防重入。

---

十四、成本与配额控制

Headless 批量跑，成本要管：

• 模型分级：CI 用 V4-Flash（便宜快），关键审查用 V4-Pro。
• 上下文压缩：长任务开 compaction，避免 token 爆炸。
• 限流：用队列 + 并发上限，别一窝蜂打爆 API 配额。
• 预算告警：统计每日 token，超阈值告警。

DSH 的 telemetry 默认关，但你可以自己埋点统计------毕竟日志都在你手里。

---

十五、安全：Headless 的权限边界

Headless 跑在 CI/服务器，权限更要收紧：

• 用 Workspace Write 而非 danger-full-access，且 CI 工作区是临时 checkout，影响面小。
• 密钥走 CI secret，绝不进仓库。
• 让 Agent 碰生产前必须过审批 seam------Headless 下可设"需要人工确认才执行危险操作"，避免静默破坏。
• 沙箱照常生效（Linux bwrap/Landlock），即使无人值守也框在工作区。

"无人值守"不等于"无防护"。越是自动化，越要把权限和审批钉死。

---

十六、调试 Headless

Headless 没界面，调试靠两招：

1. --dump-config ：先 dsh --profile headless --dump-config 看最终配置，确认模型/provider/插件组合正确，再跑任务。
2. 看持久化会话 ：每次运行都存进 $DSH_HOME/sessions，跑完打开 Web UI 找那条会话，看完整轨迹。Headless 不是"黑盒跑完就没了"，它的日志和 Web 模式同源。

"跑挂了不知道为什么"在 DSH 里不该发生------因为答案全在日志里。

---

十七、与 Web 模式的取舍

什么时候用哪个？

• Web 模式：人要交互、要实时看轨迹、要中途纠偏。适合探索、复杂调试、你坐前面的场景。
• Headless 模式：任务明确、要自动化、要被程序调用、要接 CI。适合批处理、值守、守门员。

两者共享同一套能力（工具、沙箱、日志），只是"交互方式"不同。你甚至可以先在 Web 里调通一个任务，再把它原样搬进 Headless 脚本------因为轨迹是可复现的。

---

十八、真实案例：自动跑测试 + 总结

某团队把"每次 push 跑测试"升级为"每次 push 让 Agent 跑测试并总结"：CI 里 Headless 执行 dsh --profile headless "跑 pytest，失败则用中文总结原因并给出最小修复建议"，结果贴 PR。效果：review 人只看 Agent 总结，定位快了一倍；偶发失败由 Agent 先初判，减少"假红"打扰。成本：每次约几美分。ROI 极高。

---

十九、常见坑

• 把密钥写进命令 ：用 env/secret，别 dsh ... --key sk-xxx。
• 任务描述太模糊：Headless 没人纠偏，任务要写得像"给同事的工单"------目标、约束、产出格式全说清。
• 忘了持久化：以为 Headless 跑完就没了，其实日志在，出事先翻日志。
• 冷启动慢就狂起进程：高并发用常驻 + 队列，别每次起新进程。
• 非幂等导致重复副作用：重试前确认任务可重入。

---

二十、给团队的落地清单

1. 先在 Web 调通你想自动化的任务。
2. 写成 Headless 命令，验证退出码和 stdout。
3. 接进一条 CI（GitHub Actions / GitLab），用 secret 管密钥。
4. 加重试 + 幂等保护。
5. 建成本看板，设预算告警。
6. 逐步扩到"AI 审 PR""定时审计"等场景。

一步步来，别一上来就全自动化------先验证 ROI。

---

二十一、Headless 的冷启动账与优化

Headless 每次启动都是"冷启动"------要加载 Cordis 内核、组装插件树、连模型。社区实测 warm 运行约 25 秒，cold 安装首跑 1--3 分钟。这意味着：如果你有 100 个任务，别各起 100 个 Headless 进程（冷启动会拖死），而要用"常驻 Web + 队列"或"批量合并任务"。冷启动成本是 Headless 架构的天然代价，设计自动化时要把它算进 SLA。

---

二十二、把 Headless 当成"可组合命令"

Headless 命令可以像 Unix 管道一样组合。比如：

dsh --profile headless "列出 src 下所有 TODO" > todos.txt
dsh --profile headless "根据 todos.txt 生成一份处理计划" 

第一条产出文件，第二条消费它。你用 shell 的重定向/管道，把多个 Agent 任务串成流水线，每个任务职责单一、便于测试和复用。这比"一个 super-prompt 干所有事"稳得多------任务越小，失败越好定位。

---

二十三、多步骤任务的 Headless 编排模式

Headless 是 one-shot，但复杂任务多步。两种编排思路：

1. 外层编排：你在 shell/CI 里分步调多个 Headless，用文件/变量传中间结果。编排逻辑在你手里，可控。
2. 内层编排：给一条大任务，让 Agent 自己在内部用 plan/todo 拆多步。适合步骤间强依赖、不便外拆的。

经验：步骤能独立验证的，用外层编排（更稳、可重试单步）；步骤强耦合的，用内层编排（更省事）。别硬拆强耦合的步骤，也别把能独立验证的步骤塞进一个大 prompt。

---

二十四、Headless 与 Code Mode 的协同

Code Mode（模型把多步操作写成 TS 一次执行）在 Headless 下尤其香：一条 Headless 任务 + Code Mode 预设，让 Agent 把"读 A 改 B 跑 C"编译成一段程序一次跑完，效率提升 3--8 倍。适合批处理（比如"给 50 个文件统一加 license header"）。代价是轨迹更整块、单步可观测性弱------所以探索性任务用标准模式，批量确定性任务用 Code Mode。

---

二十五、从日志视角看一次 Headless 运行

别以为 Headless "跑完就完了"。它和 Web 模式共享同一套会话日志：每次运行都作为一条会话事件流存进 $DSH_HOME/sessions。所以"无人值守"不等于"无迹可查"------你随时能打开 Web UI 找到那条 Headless 会话，看完整轨迹。这是 Headless 能进生产的关键：自动化跑挂了，复盘材料和人工跑的一样全。

---

二十六、成本精细核算（真实账单拆解）

以社区 benchmark 为参照，算一笔账：5 个编码任务，V4-Flash 约 3 美分、V4-Pro 约 7 美分。换算到团队：假设每天 200 次 Headless 任务（审 PR + 跑测试 + 值守），用 Flash 约 1.2 美元/天，一个月约 36 美元。对比一个中级工程师一天的人力成本，ROI 极高。大头不在 token，而在"省下的人力时间"和"更快的反馈闭环"。但前提是任务设计合理------别用 Pro 跑本该 Flash 的活，那是纯浪费。

---

二十七、失败模式全景与应对

Headless 常见的失败：

• 模型报错：prompt 越界、上下文超长。应对：缩写任务、开 compaction。
• 工具异常：命令不存在、权限不足。应对：镜像里预装依赖、提权前过审批。
• 超时：任务太长。应对：拆小、设 deadline、用 guard 强断。
• 网络抖动：API 偶发 5xx。应对：重试 + 幂等。
• 误判成功：Agent 说"完成"但实际没。应对：让任务要求"验证步骤"（比如跑测试确认），而非只说"做了"。

把这张表贴进你的运维手册，Headless 出问题时照着查。

---

二十八、权限最小化在无人值守下的实操

无人值守时没人兜底，权限要更狠地收紧：

• CI 工作区用临时 checkout，跑完即焚，即使 Agent 乱写也只污染临时目录。
• 默认 Workspace Write，绝不开 danger-full-access。
• 危险操作（部署、删数据）必须过审批 seam，且审批人不能是"自动通过"------否则就失去审批意义。
• 沙箱照常（Linux bwrap），把 Agent 框死在边界内。

"无人值守"的正确含义是"无人盯梢但有人设防"，不是"完全放手"。

---

二十九、与 Web 模式共享能力带来的工程红利

Headless 和 Web 共享同一套插件树、工具、沙箱、日志。这意味着：你在 Web 里调通的工具/插件，Headless 直接能用；你在 Headless 跑出的 transcript，Web 里能复盘。你只维护一套能力，两种入口共用。对比那些"CLI 一套、API 一套、UI 一套"各自为战的框架，DSH 的"一套内核多入口"省了大量重复工程------这是它架构层面的红利，不是功能清单上的一个点。

---

三十、团队落地 Headless 的三阶段路线

1. 试点（第 1 月）：选一个低风险场景（如"PR 自动跑测试总结"），接进一条 CI，验证 ROI。
2. 推广（第 2--3 月）：扩展到"AI 审 PR""定时审计"，建成本看板和重试/幂等规范。
3. 平台化（半年+）：把 Headless 封装成内部"Agent 任务服务"，业务方提交任务即可，不用每人写 CI。

别一上来平台化------前期复杂度会劝退团队。小步快跑，用 ROI 说话。

---

三十一、一个踩坑复盘

某团队第一次接 Headless 审 PR，没设幂等，Agent 在重试时重复提交了两遍相同的审查评论，刷屏惹恼评审人。根因：任务描述没说"若已评论则跳过"，且外层没去重。修复：任务加"先查是否已评论"的指令 + 外层用 PR 评论 ID 去重。教训：自动化里的"重复副作用"，比人工时更隐蔽也更烦人，必须在设计和外层双重防重。

---

三十二、给不同角色的行动项

• 开发者：今天起，把一个你每天手跑的命令（跑测试/生成变更说明）改成 Headless 脚本。
• DevOps/SRE：把 Agent 接进现有 CI，用 secret 管密钥，加成本看板。
• 技术负责人：定"哪些环节允许无人值守 Agent"，列清权限和审批红线。
• 管理者：把"AI 值守节省的人力"量化成报表，用数据推动更大投入。

---

结语：让 Agent 成为流水线的一员

Headless 模式是 DSH 从"玩具"变"基础设施"的开关。当 Agent 能被 CI 调用、能被 cron 调度、能被你的系统编排，它就不再是"你聊天的对象"，而是"你团队里 24 小时在线的同事"。

下一篇 我们讲自定义工具（Tools）------Headless 跑的任务、Web 里 Agent 调的能力，底层都来自 ctx.tools 注册表。学会写自己的工具，你就真正能"教 Agent 干你特有的活"。

如果这篇帮你把 Agent 接进了流水线，点个关注。DeepSeek Harness 实战系列（概念 / 教程 / 架构 / 插件 / 编码实战 / 框架对比 / 会话日志 / 本文 / 自定义工具 / 模型适配 / Web 协同 / 安全沙箱 / 多 Agent / 二次开发）持续更新。有问题评论区交流。

本文基于 deepseek-ai/deepseek-harness 官方文档、官方 packages/acp README、社区实测（laserlloyd 等）及 CI 平台公开文档整理，截至 2026-08。dsh 处于开发者预览阶段，命令以你安装版本为准。