十分钟跑通第一条自动化链路:原型上手的最小可复现步骤

原创2026-11-01 11:54:322,229 阅读
文章标签:人工智能AI Agent代码智能体AI 应用dsh-plugin后端前端Agent 工作流认证鉴权

十分钟跑通第一条自动化链路:原型上手的最小可复现步骤

把 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 对照表——毕竟这个仓库给自己的定位写得很清楚:研究原型,别直接上生产。

登录后查看全文
dsh-superagent-prototype