十分钟跑通第一条自动化链路:原型上手的最小可复现步骤
十分钟跑通第一条自动化链路:原型上手的最小可复现步骤
把 agent 从"能聊天"推到"能交付",中间差的不是模型能力,而是一条可观测、可复现的链路。dsh-superagent 这个仓库做的正是这件事:它是一个挂在 DeepSeek Harness(下称 DSH)上的 bundle,只盯着一个 GitHub 仓库,把别人 @ 它的一句话,变成一条工单、一个独立 Session、一次真实提交和一份 PR。
社区里对 DSH 的讨论已经从"什么是 harness"转向"怎么装插件、怎么串起一条自动化"——"一切皆插件"的叙事说清了架构,但没说清第一次跑通要看哪几个输出。本文只解决后者:用仓库里真实存在的命令、真实的退出码和真实的健康字段,给出一次可复现的最小链路,以及一套不靠感觉判断"这次到底成没成"的验收标准。
需要先把话说在前面:标题里的"十分钟",计时的起点是你已经有 DSH、有一个可用的模型 provider、一个能推送的 GitHub 仓库。创建智能体专用 GitHub 账号、给仓库授权这类只有人能做的事,被仓库作者有意排除在自动流程之外(见 SETUP.md 的 "Never ask for a secret in the chat"),本文会把它单独列成清单,但不计入十分钟。
一、最小依赖集合:把"能跑"和"能开工"分开
仓库把依赖分成两层,这个划分很实用:一层是进程能起来,一层是能真正开工。
第一层的硬性下限写在 package.json 的 engines 里,setup 前置检查又补了 shell 工具:
| 依赖 | 版本下限 | 为什么是这个数 |
|---|---|---|
| Node.js | ^22.19.0 || >=24.0.0 |
直接用 node:sqlite 存状态,不引第三方数据库 |
| pnpm | 11.7.0(packageManager 固定) |
lockfile 格式与 pnpm build 一致 |
| DSH | ^0.2.1-alpha.2 |
宿主 API 处于 alpha,跨版本必炸 |
| git | 2.32 | 低于它 git 不读仓库写入的 credential.https://github.com.helper,对应 setup.ts 里的 gitTooOld |
| GitHub CLI | 2.48 | 代码依赖 gh api 的子命令与输出格式,不做兼容层 |
| Python 3.8+ | — | scripts/dsh-superagent 是 Python 实现的服务控制脚本 |
| tmux | 任意 | 服务跑在独立 session 里,不干扰你现有的终端 |
第二层是运行时才暴露的"开工条件",缺了不会启动失败,但会让整条链路静默停摆:一个能推送到目标仓库的 GitHub 账号(GitHub App 不行,因为实现要读该账号的通知),以及 DSH profile 里的一个模型 provider。
一条命令就能把第一层的事实拿全,这也是 SETUP.md 让 agent 在问任何问题之前先跑的那次 probe:
node -v; pnpm -v; git --version; tmux -V; python3 --version; gh --version | head -1; dsh --version
gh api user --jq .login
command -v lark-cli
grep -l -E 'id: dsh-superagent\b' "${DSH_HOME:-$HOME/.dsh}"/profiles/*/cordis.patch.yml 2>/dev/null
最后两行的作用容易被忽略:command -v lark-cli 决定要不要开飞书这条链路(不开也能完整跑通 GitHub 链路),而那条 grep 是在探测"是不是以前装过"——只要命中,就说明存在一个旧 profile,后续必须走升级路径,而不是重新创建。scripts/dsh-superagent 的守卫逻辑同样苛刻:发现同名 profile 已有进程时,它会直接拒绝再起一个实例,避免两个进程同时写同一个 SQLite。
二、四步安装:profile 隔离不是洁癖,是正确性要求
安装本身是四行,但每一行都有它不能挪动的位置:
npm install -g @deepseek-ai/dsh@0.2.1-rc.3
git clone <this repository> dsh-superagent && cd dsh-superagent
pnpm install && pnpm build
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"
第四行会从 DSH 的 Web 模板复制出一个名为 superagent 的新 profile。为什么必须新开一个而不是加到你日常用的 profile 里?答案在 src/infra/environment.ts:插件会在进程级别重写 PATH、GIT_CONFIG_GLOBAL、GIT_ASKPASS,并清掉 GH_TOKEN、GITHUB_TOKEN 与 GIT_DIR 一类变量,再把 worker-bin 插到 PATH 最前面。这些改动如果发生在你日常使用的 profile 里,会连带影响你自己敲的每一条 git。所以 docs/006-deployment.md 的要求是"独立重启、独立升级"。
第五行的 link:$PWD 也很关键:它把当前 checkout 以 link 方式挂进 profile,于是你改代码后只需 pnpm build + restart,不必重新发版。
接下来是最容易漏的一步——profile 配置。把 examples/profile.cordis.patch.yml 复制到 ~/.dsh/profiles/superagent/cordis.patch.yml,并把占位符换成真实绝对路径:
- id: webserver
config:
host: 127.0.0.1
port: 3082
- id: dsh-superagent
config:
stateDir: /home/me/.dsh/state/superagent
stateDir 是唯一的必填项,它同时承载数据库、锁、worker-bin 命令垫片、智能体的 git 配置和默认的工单目录,插件没有它会直接拒绝启动(src/deployment.ts 中 stateDir 标记为 required())。port: 3082 则决定了后面所有管理 API 请求的地址。
装完先做一次自检,这一步比直接启动更省时间:
pnpm check # typecheck + vitest + tsdown 构建
三、一条两工具串联任务:从 mention 到 PR 的完整命令序列
这里的"两工具串联"有两层含义,分清它们才能读懂输出。应用层是两个工具:主 Session 用 orchestrator_route 把候选变成工单,执行器用 orchestrator_report 把结果交回来。进程层同样是两个工具:执行器真正调用的是 worker-bin 里的 gh 和 git 两个垫片——WORKER_COMMANDS 明确规定 gh、git、lark-cli 不可被 blockedCommands 屏蔽,因为它们是执行器唯一的外部出口。
3.1 启动,并读懂那个整数
scripts/dsh-superagent start
scripts/dsh-superagent status
start 会在 tmux 里执行 dsh --profile superagent --no-open,然后最多等 60 秒,直到运行时进入 ready 或 paused。status 的输出是 JSON,退出码有四种含义,这张表是本文后半段验收的基础:
| 退出码 | 含义 | 重启有用吗 |
|---|---|---|
| 0 | 正常 | — |
| 1 | 没跑、跑了两份、不响应,或 runtime 报错 | 可能有用 |
| 2 | 在跑,但某个组件(Source、sync:<id>)报错 |
无用,需要人处理 |
| 3 | 在跑,但在等 setup | 无用,需要人处理 |
判断逻辑就在 scripts/dsh-superagent 的 outcome() 里:先看进程数是否恰好为 1、health.runtime 是否属于 ready/paused,再看 setup.problem 是否为空,最后才检查非 runtime 组件是否有错误。所以 exit 0 本身只说明"进程健康",不说明"业务成功"——这一点后面还要再拆。
3.2 用管理 API 写三块配置
面板能做的事,curl 也能做,而且更适合复制粘贴。所有请求都要带 x-orchestrator-request: 1,且 Host 必须是 127.0.0.1:<port> 或 localhost:<port>,否则直接 403。
写入顺序不是随意的,它对应 Trigger → Policy → Ticket 的漏斗:
api=http://127.0.0.1:3082/orchestrator/api
# 1. Source:哪个仓库、用哪个账号的 CLI
rev=$(curl -s -H 'x-orchestrator-request: 1' $api/settings | jq '.sources[] | select(.id == "github") | .revision')
curl -s -X PUT -H 'x-orchestrator-request: 1' -H 'content-type: application/json' \
$api/settings/source:github \
-d "{\"value\": {\"enabled\": true, \"config\": {\"repository\": \"acme/widgets\", \"cli\": \"$HOME/.local/bin/gh-agent\"}}, \"revision\": $rev}"
# 2. Policy:谁可以发号施令(空名单 = 永远不会有工单)
rev=$(curl -s -H 'x-orchestrator-request: 1' $api/settings | jq '.policy.revision')
curl -s -X PUT -H 'x-orchestrator-request: 1' -H 'content-type: application/json' \
$api/settings/policy \
-d "{\"value\": {\"rules\": [], \"sources\": {\"github\": {\"allowed\": [{\"id\": \"your-login\"}]}}}, \"revision\": $rev}"
第二步最值得强调:overview 视图里有一个 no-allowed 问题类型,含义是"允许名单为空,任何请求都不可能变成工单"。这是原型在代码层面就承认的一个静默失败点——链路看起来一切正常,触发评论也收到了,但永远不会出现 Ticket。第一次跑之所以"什么都没发生",八成是这里。
第三步是 Execution,也就是"两工具"真正落地的地方:
rev=$(curl -s -H 'x-orchestrator-request: 1' $api/settings | jq '.executor.revision')
curl -s -X PUT -H 'x-orchestrator-request: 1' -H 'content-type: application/json' \
$api/settings/executor \
-d "{\"value\": {\"maxWorkers\": 1, \"directory\": \"/home/me/agent/work\", \"prepare\": \"git -C /home/me/src/widgets fetch --no-tags \\\"https://github.com/\$DSH_SUPERAGENT_GITHUB_REPOSITORY.git\\\" \\\"\${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/\$DSH_SUPERAGENT_TICKET\\\" && git -C /home/me/src/widgets worktree add -b \\\"agent/\$DSH_SUPERAGENT_NAME\\\" \\\"\$DSH_SUPERAGENT_DIR\\\" \\\"refs/dsh-superagent/\$DSH_SUPERAGENT_TICKET\\\"\"}, \"revision\": $rev}"
这段 prepare 是仓库文档里给出的标准写法,它的每个变量都能在 src/app/execution-environment.ts 中找到登记来源:DSH_SUPERAGENT_DIR、DSH_SUPERAGENT_NAME、DSH_SUPERAGENT_TICKET 由执行器提供,DSH_SUPERAGENT_GITHUB_REPOSITORY、DSH_SUPERAGENT_GITHUB_PR_HEAD 由 GitHub Source 提供。它用 git worktree 而不是完整 clone,正是为了让每个工单共享同一个对象库,fetch 只拉一个 ref。
有几个默认值第一次不必改,但要知道它们存在:maxWorkers 默认 3(表示同时最多 3 个执行器 Session,首次验证建议压到 1,输出更好读);eval.timeoutSeconds 默认 120;eval.mode 默认 observe,即"只记录不接单"。也就是说,默认配置下推断类工作永远不会被自动接受,显式 @ 不受影响。
3.3 抛出触发器
gh issue comment 42 --repo acme/widgets --body "@agent-login 把设置页的‘保存更改’按钮文案改成‘保存’"
一个必须记住的细节:通过编辑已有 Issue 正文来加 @ 是收不到的。GitHub Source 走的是通知接口,只有新评论、新 Issue、新 PR 会产生通知;正文编辑不会。想触发就别编辑,发新评论。
时间线大致是这样:下一个轮询周期(pollSeconds 下限 60 秒,默认也是 60)拉取通知;主 Session 判定为 explicit 请求并生成候选;接受后原子性地写入工单、Mandate、订阅和确认回复;launch 效应执行 prepare(上限 10 分钟,src/executor/dsh.ts 中的 PREPARE_TIMEOUT_MS);执行器 Session worker-<ticket id> 启动,用 gh 读上下文、用 git 提交并推送,最后用 orchestrator_report progress 把 PR 绑到工单上。
四、如何判断这次运行真的成功了
这是全文最该被复制的部分。成功要分四层验证,任何一层都不能用"看起来在跑"代替。
第一层:进程健康。 scripts/dsh-superagent status 退出码为 0,且 health.runtime 是 ready 或 paused。
第二层:setup 已解开。 GET state 返回的 setup.problem 必须是 null。只要它非空,status 就会给 3,而 3 是"在等人",不是"在干活":
curl -s -H 'x-orchestrator-request: 1' $api/state \
| jq '{setup: .setup.problem, runtime: .health.runtime.state, paused: .paused, workers: .load.maxWorkers}'
第三层:Source 真的在收消息。 GET sources 会给出每个 Source 的 state,并用 filtered 和 dropped(24 小时内)解释"消息去哪了"。这两个数组是排查静默失败的关键:
curl -s -H 'x-orchestrator-request: 1' $api/sources \
| jq '.sources // . | map({id, state, problem, stats, filtered: (.filtered | length), dropped: (.dropped | length)})'
如果评论发出去了、state 是 ready,但 filtered 里出现了你那条消息,说明它被策略挡在门外(没在允许名单、Source 未监听该范围),而不是模型没跑。
第四层:工单进入正确的 stage。 工单状态不跟随 Session 状态,而是由 src/core/stage.ts 的 ticketStage() 按固定顺序判定,第一条命中的规则即结果。这张对照表比任何日志都直接:
| 你看到的状态 | 代码条件 | 含义 |
|---|---|---|
Queued |
无 Assignment 或 Assignment 为 pending |
已经接单,在等执行槽位 |
Working |
其余情况 | 执行器正在干 |
Waiting for a Trigger |
最新报告是 waiting,或 Assignment 已结束 |
这一轮结束,等后续消息 |
Awaiting review |
最新报告是 ready |
有可评审的交付物 |
Blocked / Failed |
最新报告是 blocked / failed 且此后没有人类消息 |
需要人介入 |
Input undelivered |
失败过一次投递 | 传输问题,不是业务问题 |
所以"成功"的严格定义是:工单进入 person / review,且回复里出现了对原评论的确认、PR 链接可点。顺带一个可观测的约束:确认消息受 IM_WORDS = 100 的硬上限约束(src/infra/text.ts),超过会被拒绝并要求重写成一句话——如果你看到确认消息特别短,那不是偷懒,是规则。
反向判据同样重要。 下面这些"看起来像成功"的现象,实际都是失败:
status给 2:Source 或 Policy 同步报错,重启无效,必须看errors里的 detail;status给 3:setup 还卡着,链路根本没通电;GET state里health.github.state是paused:Source 被关掉了;- 工单停在
Queued很久:maxWorkers被占满,或者prepare在跑(它有 10 分钟上限,超时会失败而不是挂住)。
五、真实错误串:原型里写死的那些提示
这个仓库把失败信息当成产品的一部分在做——SetupError 带 place、code、values,面板按语言渲染,日志和 API 返回英文原文。所以遇到问题时,别猜,直接对表(节选自 src/setup.ts 与 docs/006-deployment.md):
| 错误串 | 真实原因 | 修法 |
|---|---|---|
The agent GitHub CLI is not set. |
没填 CLI 路径 | 在 GitHub 卡片填 gh-agent 的绝对路径 |
The agent GitHub CLI cannot read its account |
垫片没登录 | 对该包装脚本执行 auth login |
@xxx cannot push to yyy |
账号只有读权限 | 给智能体账号写权限 |
git does not read the github.com credential configuration |
git 太旧 | 升到 2.32+ |
… was not written by dsh-superagent |
worker-bin 或 worker-gitconfig 里有别人的文件 |
移走该文件,或换 stateDir |
The prepare command failed: … |
克隆路径错、分支已存在、凭证提示 | 看输出定位;修好后点 Retry |
倒数第二条值得单独说。writeEnvironment() 在写 worker-bin 前会先扫一遍目录,发现不是自己写的文件就直接抛 foreignFile 并中止启动。这是"不做安全边界,但绝不覆盖别人的东西"的折中:仓库自己也承认 worker 以操作者的 OS 用户身份、danger-full-access 运行,垫片只是默认值而非隔离(docs/006-deployment.md 的 Permissions and isolation 一节说得很直白)。真要隔离,用独立的 OS 账号,别指望 blockedCommands。
结语
这条链路的真正价值不在于"能自动改一行文案",而在于它把三个常被含糊处理的东西写成了代码:谁能发起工作(Policy 与允许名单,空名单就是零)、这次运行是否成立(四个退出码 + stage 判定表)、失败在哪里(结构化 SetupError 加 filtered/dropped 的可解释记录)。十分钟够跑通一次,但够不够放心把它留在团队仓库里,取决于你有没有读完那张 stage 对照表——毕竟这个仓库给自己的定位写得很清楚:研究原型,别直接上生产。