DeepSeek Harness Headless 模式把 AI Agent 写进 CI/CD 流水线系列导航本篇是 DeepSeek Harness 实战系列第 4 篇。前面讲了编码实战、框架对比、会话日志。本文聚焦一个把 DSH 产品化的关键能力——Headless无头模式也就是让 Agent 不依赖浏览器、不被人盯着乖乖跑在脚本和流水线里。引言Agent 不止能聊天还能被调用前面几篇我们都是人坐在浏览器前面和 Agent 对话。这很好但只发挥了 Agent 一半的威力。真正让它变成团队基础设施的是另一半——让别的程序调用它。DeepSeek Harness 的 Headless 模式干的就是这个。它启动一个 Agent给它一个任务它跑完把答案打印到 stdout然后退出。没有浏览器、没有交互、没有人。这条命令本身就是一段可被脚本消费的程序dsh--profileheadless把本仓库的测试跑一遍用中文总结失败原因并给出修复建议本文我会讲清Headless 到底是什么、退出码怎么用、环境变量怎么配以及——重点——如何把它接进 GitHub Actions、GitLab CI、pre-commit、定时任务最终让你拥有AI 审 PR“AI 跑测试”AI 值守的自动化能力。一、Headless 是什么一次性、脚本化、退出码用三句话定义 Headless一次性one-shot你给一个任务它跑完就结束不保持会话等待下一条消息。脚本化scriptable它从命令行启动答案走 stdout适合被 shell/CI 调用。有退出码exit code成功退 0失败退非 0天然适配 CI 的非零即失败语义。这三点决定了它和 Web 模式的本质区别Web 模式是常驻服务 人交互Headless 是短暂进程 程序调用。前者像你雇的个人助理随时待命后者像你写的一个定时任务。二、最小可用跑起来再说最朴素的用法# 先设密钥exportDEEPSEEK_API_KEYsk-xxx# 跑一条任务dsh--profileheadlessCreate fizz.py that prints FizzBuzz for 1..15 and run it; reply with the program output only.社区实测输出1 2 Fizz 4 Buzz ... FizzBuzzecho$?# 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否示例走公司网关、用特定模型、关闭遥测exportDEEPSEEK_API_KEYsk-xxxexportDEEPSEEK_BASE_URLhttps://gateway.internal/v1exportDSH_MODELdeepseek-v4-proexportDSH_TELEMETRY_MODEdisabled dsh--profileheadless审查这个 PR 的 diff把密钥放进 CI 的 secret而非明文是基本安全纪律。五、接进 GitHub Actions最常见的落地PR 创建时让 Agent 跑测试并评论结果。一个yml骨架name:AI Test Runneron:[pull_request]jobs:ai-test:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-uses:actions/setup-nodev4with:{node-version:24}-run:npm install-g deepseek-ai/dsh-name:Run DSH headlessenv:DEEPSEEK_API_KEY:${{secrets.DEEPSEEK_API_KEY}}run:|dsh --profile headless 跑本仓库测试用中文总结失败原因 \ result.txt-name:Comment resultuses:actions/github-scriptv7with: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.ymlai-review:image:node:24script:-npm install-g deepseek-ai/dsh-dsh--profile headless 审查当前 MR 的改动指出风险|tee review.txtartifacts:paths:[review.txt]only:[merge_requests]artifacts把结果存档评审人直接下载看。两条流水线的思路一致Headless 的 stdout 就是 CI 的产出物。七、本地 pre-commit 守卫不想等 CI 红把 Headless 塞进 pre-commit hook本地就拦#!/bin/bash# .git/hooks/pre-commitdsh--profileheadless检查本次暂存的改动是否有明显回归风险只回答 通过/不通过原因# 非零则提交被拒注意只做快且确定的检查比如静态风险扫描重活留给 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_KEYxxx dsh --profile headless 检查依赖是否有已知漏洞输出报告 /var/log/dsh-audit.logcron 的 stdout 重定向 Headless 的持久化给你一份每天自动审计、且随时可回放的日志。十、与 ACPAgent 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。两种办法让模型输出 JSON任务里写只输出 JSON字段为 {passed: bool, reason: str}。简单但依赖模型听话。从 transcript 取运行后从会话日志transcript里取结构化事件比解析 stdout 稳。适合要求严谨的场景。生产建议需要机器消费的结果优先从 transcript/事件流取别只信 stdout 文本。十三、失败重试与幂等CI 里网络抖动能让 Headless 偶发失败。加重试foriin123;dodsh--profileheadless...breaksleep5done但重试要求任务幂等——同一条任务跑两次不产生副作用比如别让 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即使无人值守也框在工作区。“无人值守不等于无防护”。越是自动化越要把权限和审批钉死。十六、调试 HeadlessHeadless 没界面调试靠两招--dump-config先dsh --profile headless --dump-config看最终配置确认模型/provider/插件组合正确再跑任务。看持久化会话每次运行都存进$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 跑完就没了其实日志在出事先翻日志。冷启动慢就狂起进程高并发用常驻 队列别每次起新进程。非幂等导致重复副作用重试前确认任务可重入。二十、给团队的落地清单先在 Web 调通你想自动化的任务。写成 Headless 命令验证退出码和 stdout。接进一条 CIGitHub Actions / GitLab用 secret 管密钥。加重试 幂等保护。建成本看板设预算告警。逐步扩到AI 审 PR定时审计等场景。一步步来别一上来就全自动化——先验证 ROI。二十一、Headless 的冷启动账与优化Headless 每次启动都是冷启动——要加载 Cordis 内核、组装插件树、连模型。社区实测 warm 运行约 25 秒cold 安装首跑 1–3 分钟。这意味着如果你有 100 个任务别各起 100 个 Headless 进程冷启动会拖死而要用常驻 Web 队列或批量合并任务。冷启动成本是 Headless 架构的天然代价设计自动化时要把它算进 SLA。二十二、把 Headless 当成可组合命令Headless 命令可以像 Unix 管道一样组合。比如dsh--profileheadless列出 src 下所有 TODOtodos.txt dsh--profileheadless根据 todos.txt 生成一份处理计划第一条产出文件第二条消费它。你用 shell 的重定向/管道把多个 Agent 任务串成流水线每个任务职责单一、便于测试和复用。这比一个 super-prompt 干所有事稳得多——任务越小失败越好定位。二十三、多步骤任务的 Headless 编排模式Headless 是 one-shot但复杂任务多步。两种编排思路外层编排你在 shell/CI 里分步调多个 Headless用文件/变量传中间结果。编排逻辑在你手里可控。内层编排给一条大任务让 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 跑出的 transcriptWeb 里能复盘。你只维护一套能力两种入口共用。对比那些CLI 一套、API 一套、UI 一套各自为战的框架DSH 的一套内核多入口省了大量重复工程——这是它架构层面的红利不是功能清单上的一个点。三十、团队落地 Headless 的三阶段路线试点第 1 月选一个低风险场景如PR 自动跑测试总结接进一条 CI验证 ROI。推广第 2–3 月扩展到AI 审 PR“定时审计”建成本看板和重试/幂等规范。平台化半年把 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/acpREADME、社区实测laserlloyd 等及 CI 平台公开文档整理截至 2026-08。dsh 处于开发者预览阶段命令以你安装版本为准。