DeepSeek Superagent 教程：观察 CI 并授权修复

什么是 DeepSeek Superagent？

DeepSeek Superagent 通过 DeepSeek Harness 监控一个 GitHub 仓库。团队规则决定某个事件是否值得处理；被接受的工作会进入单独的会话。本教程涵盖的是已发布的原型，而非仅停留在设计层面的想法。

Harness 提供运行时；Superagent 增加了事件监控与授权。我们的代理 harness 说明介绍了工具、记忆与控制。

DeepSeek Superagent 如何工作？

新的 GitHub 事件可经历四个阶段。这些阶段将“决策”与“代码变更”分离：

• 来源与触发：GitHub 轮询将每个事件转换为 Issue、PR 或 main 上的 Trigger。

• 准入：网关将其标注为明确请求、推断候选或忽略。

• 评估与决策：推断出的 CI 会根据规则进行判断。明确请求会被路由到“接受”决策，原因 explicitRouted。

• 工单与执行器：被接受的工作会获得授权、工作会话与目录。

在该 Ticket 自有线程上的后续评论会直接交给其工作进程，不再进行新的评估。下图展示了三条 GitHub 路径：默认分支 CI、一次明确请求以及该请求的评审。在 CI 路径中，观察与自动离开处于匹配规则的不同端点。

CI 被评判；请求启动工作。作者制图。

观察模式与自动模式有什么区别？

接受模式仅适用于 Superagent 从事件中推断出的工作。从以下三种设置中择一：

• off 丢弃推断的候选。

• observe 对其进行评估，但将正向结果记录为 “would accept”。

• auto 在正向评估后开始工作。

来自获准人员的请求在任意模式下都有效，并会创建独立 Ticket。请在本教程中将 auto 保持关闭。

在观察模式下构建 CI 修复工作流

该管道使用 pytest 和两个 GitHub Actions 任务，将事件转化为每日收入。Superagent 在工作开始前插入一个决策。我们的 Claude Code Routines 教程介绍了另一个事件驱动工作流。

追踪每日收入中的重放缺陷

该缺陷会将一笔重放的付款计入两次。每行包含 event_id、order_id、时间戳与金额。一个订单可能包含多笔有效付款。

因此，基于 order_id 去重可能通过重放测试，却会删除真实付款；正确的键是 event_id。在授权代理前用 Python 的 csv 模块计算期望总额，避免代理输出成为答案来源。

界定一次成功的 CI 修复

成功取决于工作流的行为，而不仅是代理的说法。在修改仓库前设定以下条件：

• 忽略仅限文档的故障。

• 匹配 revenue-integrity 而不启动工作。

• 仅在收到明确请求后打开拉取请求。

• 保留断言并通过预构建的保留集。

在 Superagent 获得访问前准备好保留集。这能将期望行为排除在工作进程的开发输入之外。

DeepSeek Superagent 的前置条件与隔离

您需要一个 DeepSeek API 密钥、两个 GitHub 账户，以及一个一次性 Linux 环境。关于 Harness 基础，请参阅我们的 基础设置指南。

所需软件与账户

固定软件版本，避免升级改变工作流。下一列记录了文中结果所用的设置：

代理需要自有的具写入权限的 GitHub 用户，因为 Superagent 会读取该账户的通知。仅将可授权工作的人工维护者加入允许列表。

将代理与个人文件隔离

两种预设都会赋予操作系统（OS）用户完全访问权限，而 gh 封装并不会隔离进程。使用一个全新的 WSL 发行版，并关闭自动挂载与互操作：

如果您已有一次性 Linux 虚拟机，可跳过 WSL 配置，改用该虚拟机。请勿在其上存放无关凭据与文件。

# /etc/wsl.conf inside the disposable distribution
[automount]
enabled = false
mountFsTab = false
[interop]
enabled = false
appendWindowsPath = false
[user]
default = superagent技术支持

专用的 superagent 用户应仅持有 DeepSeek 密钥与代理令牌。这可降低意外访问，但不构成安全边界；微软的 WSL 安全模型 建议将不受信任代码运行在 WSL 之外的独立虚拟机中。

在 GitHub 上，为 main 启用受保护分支、至少一次独立批准与两个 CI 检查必需。赋予代理写入权限，但不要允许管理员绕过。这些措施都不能阻止通过 Issue 文本进行的提示注入。

步骤 1：构建 Python 收入管道与 CI 基线

已发布的教程仓库目前在 main 上已合并修复，因此不要以其当前分支作为起点。用以下提交划分三阶段：

下方的管道与测试基于绿色基线（a6d2036）的简化版本，并非取自当前 main。请先从该提交创建一个一次性仓库，再继续 CI 步骤：

git clone https://github.com/KhalidAbdelaty/superagent-revenue-lab.git revenue-lab
cd revenue-lab
git switch -C main a6d2036
git remote remove origin

export EXPERIMENT_REPO="YOUR_LOGIN/superagent-revenue-lab"
gh repo create "$EXPERIMENT_REPO" --private --source=. --remote=origin --push技术支持

使用这个新仓库来制造可控故障与承载代理分支。保持已发布仓库不变；其中的事件与解决提交可作为对照参考。

"""Daily revenue report built from payment events."""
import pandas as pd


def load_events(path):
    """Read payment events; amounts are integer cents."""
    return pd.read_csv(path, parse_dates=["occurred_at", "received_at"])


def daily_revenue(events):
    """Return one row per UTC day with total revenue in cents."""
    days = events["occurred_at"].dt.strftime("%Y-%m-%d")
    report = (
        events.assign(day=days)
        .groupby("day", as_index=False)["amount_cents"]
        .sum()
        .rename(columns={"amount_cents": "revenue_cents"})
    )
    return report技术支持

基线数据集跨两天，且包含某一订单的多笔真实付款。Pytest 校验已知总额与“同一订单多笔付款”这一情形，目前尚未测试重放：

import pandas as pd


def test_daily_totals_match_known_values():
    report = daily_revenue(load_events(DATA))
    assert report["revenue_cents"].tolist() == [20398, 27550]


def test_events_on_the_same_order_are_all_counted():
    t = pd.Timestamp(0, unit="s", tz="UTC")
    events = pd.DataFrame({
        "event_id": ["evt_a", "evt_b"],
        "order_id": ["ord_1", "ord_1"],
        "occurred_at": [t, t],
        "received_at": [t, t + pd.Timedelta(seconds=1)],
        "amount_cents": [1000, 250],
    })
    assert daily_revenue(events)["revenue_cents"].tolist() == [1250]技术支持

将每个作业命名为其所检查的行为。这样同样的名称会出现在 GitHub 和 Superagent 的 Trigger 文本中：

name: ci
on:
  push:
    branches: [main]
  pull_request:

jobs:
  revenue-integrity:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt   # pandas==2.3.3, pytest==8.4.2
      - run: pytest -v

  docs-check:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python scripts/check_docs.py      # fails if README links a missing file技术支持

如果裸 pytest 无法导入 revenue，请添加 pytest.ini 并设置 pythonpath = .。在安装 Superagent 前确认两个作业均在 main 上通过。

已发布的 experiment/holdout 目录记录了原始运行，但在公共克隆中可见。对于新的实验，请在每个检出与工作进程可读的所有文件系统之外创建全新测试集。

在发送修复请求前对该测试集进行哈希。覆盖以下情形：

• 同一事件的重复投递。
• 不同事件共享同一订单 ID。
• 必须保持不变的输入 DataFrame。
• 期望的输出列与排序。

在评审前保持该测试集隐藏。第 6 步会在工作进程结束后，从独立的人类环境运行该测试集。

下图将工作进程的开发输入与维护者的最终检查分离。

保留数据保留在工作进程之外。作者制图。

步骤 2：安装 DeepSeek Superagent 并连接 GitHub

在专用的 Harness 配置中安装该捆绑，与日常工作配置分离。将代理账户的令牌载入 AGENT_GH_TOKEN，但不要写入仓库。然后以 superagent 用户执行以下命令：

npm install -g @deepseek-ai/[email protected] [email protected]

git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git ~/dsh-superagent
cd ~/dsh-superagent
git checkout --detach 8c32a9dc5d72c033816c6a8110b37f40cf94fba4
pnpm install && pnpm build

# A gh wrapper that only ever sees the agent account
mkdir -p "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
cat > ~/.local/bin/gh-agent <<'W'
#!/bin/sh
GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@"
W
chmod +x ~/.local/bin/gh-agent
printf '%s' "$AGENT_GH_TOKEN" | gh-agent auth login --hostname github.com --with-token
gh-agent api user --jq .login            # your dedicated agent account

# Dedicated profile, then the bundle
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"技术支持

注意：本教程运行使用的提交为 6337fc8，DeepSeek 之后将其压缩为 8c32a9d。

使用克隆仓库中的配置示例来设置状态目录，并将面板绑定到 127.0.0.1:3082。然后在 tmux 中启动服务：

scripts/dsh-superagent start
scripts/dsh-superagent status技术支持

该配置将服务重启与个人 Harness 会话隔离。也避免将插件的 PATH 与 Git 设置混入常规配置。

status 可能在您于第 3 步保存 GitHub 来源前报告 setup pending 或 repositoryUnset。此时仅需确认运行时有响应、且 Superagent 面板可打开；尚不应期待 Source 或 CI 基线。

在专用配置中打开 Settings → Models 并选择 deepseek-flash。在 Superagent → Settings → Eval 与 Execution 中确认两个角色继承了该配置模型，或显式指定 deepseek-flash。

步骤 3：在观察模式下配置 GitHub Actions 监控

在保存 Source、策略、规则与执行器设置期间，先关闭默认分支 CI 观察。仅在新仓库的 main 为绿色后再开启，以便首次读取记录干净的基线。

配置 GitHub Source

在 Settings → Sources 中，将仓库设置为 EXPERIMENT_REPO，将 CLI 字段指向专用的 gh-agent 封装，并保持默认分支 CI 观察关闭。保存 Source 并等待任何重启完成后再修改策略。

配置 CI 准入策略

CI 结果没有发送者。其准入行只有一个单元格，默认是 ignore。如果保持不变，Eval 将永远看不到 CI。

定义一条聚焦的 revenue-integrity 规则

用一条以检查命名的规则替换示例规则。告诉评估器不要猜测原因：

{
  "rules": [{
    "id": "revenue-integrity",
    "name": "Revenue integrity CI failures",
    "enabled": true,
    "instruction": "A default-branch CI result in which the check named revenue-integrity newly fails. That check executes the pytest suite guarding the daily revenue totals. Judge only from the check names and results you can read for that commit; do not guess a root cause. Failures limited to other checks, such as docs-check (README links), do not match. A recovery where every check passes does not match. Work, if accepted: investigate the failing revenue-integrity tests, fix the pipeline without weakening or deleting any assertion, add a regression test, and open a pull request for human review. Never merge."
  }],
  "sources": {"github": {
    "allowed": [{"id": "<human-login>"}],
    "bots": [],
    "admission": {"ci": {"unlistedUnaddressed": "inferred"}}
  }}
}技术支持

添加一条 prepare 命令，为每个 Ticket 创建一个 Git worktree。每个工作进程都将从一次仓库检出开始：

C=/home/superagent/src/superagent-revenue-lab
git -C $C 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 $C worktree add -b "agent/$DSH_SUPERAGENT_NAME" "$DSH_SUPERAGENT_DIR" "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"技术支持

Superagent 会为每个 Ticket 填充这些变量。在授权工作前，检查生成的目录是否包含预期的检出。

可选的 配置辅助脚本会写入相同的 Source、策略、评估与执行器块。它在第一遍保持 CI 观察关闭；务必显式设置实验仓库与允许的请求者：

export REPO="$EXPERIMENT_REPO"
export ALLOWED="YOUR_GITHUB_LOGIN"
bash /path/to/configure.sh all技术支持

保持禁用主动执行

让 Eval 保持在 observe，并使用该配置的默认模型。每次事件后，请在 Eval 选项卡查看 Decision，在 Execution 选项卡查看是否有 Ticket。

开启 CI 观察并记录基线

在两个 GitHub Actions 作业均在 main 上通过后，开启默认分支 CI 观察。若使用辅助脚本，执行其第二遍：

OBSERVE_CI=true bash /path/to/configure.sh source
bash /path/to/configure.sh show技术支持

首次读取会记录状态而不创建工作。请核实四项条件：

• 设置不显示任何待处理要求。

• GitHub Source 报告为 ready。

• Source 记录了干净的 CI 基线。

• Trigger 与 Execution 选项卡未显示任何基线 Trigger 或 Ticket。

若上述任一检查失败，请在创建文档故障前停下。下方截图展示了最终的 Source 与 Eval 配置。

带 CI 观察的 GitHub Source 卡片。作者制图。

Eval 设置：一条规则，观察模式。作者制图。

步骤 4：测试一个无关的 GitHub Actions 故障

使用 README 断链来制造一个无关故障。由于受保护分支会拒绝失败检查，因此仅在这个一次性仓库中使用人工管理员绕过；绝不要将该绕过授权给代理。

sed -i 's|^- Tests: .*|&\n- Data dictionary: [docs/data-dictionary.md](docs/data-dictionary.md)|' README.md
git commit -am "docs: link the data dictionary from the README" && git push技术支持

当 GitHub Actions 完成后，docs-check 失败，revenue-integrity 通过。这与我设置的规则相符：Superagent 忽略了该候选，因为未匹配到收入规则。

该决策使用了 ignoredFromCard，这是一个针对与活动规则无关候选的快捷标记。因此该检查覆盖的是路由，而非规则本身。

还原 README 变更并等待两个作业通过。Superagent 应忽略此次恢复并保持空闲。

步骤 5：触发一次收入完整性 CI 故障

使用同样的仅限人工路径，将教程仓库中的事件数据加入。以下摘要展示了重放与同一订单下的多笔付款（不含时间戳列）：

event_id,order_id,amount_cents,delivery
evt_1009,ord_507,5000,first
evt_1010,ord_508,6400,first
evt_1011,ord_508,1600,first
evt_1009,ord_507,5000,replay
evt_1012,ord_509,2100,first技术支持

仓库会保留完整的时间戳列；此处省略，因为它们不决定事件身份。此前准备的独立计算结果为 15,100 分（cents），据此在测试中设置该值，并添加 test_replayed_event_is_counted_once()。

E       actual daily total: 20100
E       expected daily total: 15100
E       replay total: 8000 != 4000
FAILED tests/test_revenue.py::test_daily_totals_match_known_values
FAILED tests/test_revenue.py::test_replayed_event_is_counted_once
2 failed, 1 passed技术支持

多出的 5,000 分来自一笔付款被计入两次。将 15100 改为 20100，或删除重放测试，同样会令 CI 变绿，但两者都不算修复。

失败的 GitHub Actions 工作流仅显示 revenue-integrity 失败。其 Trigger 在约一个轮询间隔后到达。

Eval 将该候选标记为 "would accept"，而 Execution 选项卡保持为空。评估器能看到检查名称与结论，而非 pytest 日志，所以它知道哪个护栏失败，但不知道原因。

观察模式仅记录 "would accept"。作者制图。

步骤 6：授权修复并验证拉取请求

此前介绍的明确请求路径现在用于授权执行。GitHub 通知可能存在延迟。

处理遗漏的 GitHub Issue 提及

在 Superagent 6337fc8 版本下，GitHub Source 以 5 秒重叠进行轮询，并从更晚的游标读取已通知的线程。提及通知在 21 至 23 秒后才到达，因此轮询可能越过了该消息。

这一时序解释了为何新的 Issue 正文与部分评论从未成为 Trigger。社区报告也描述了相同的失败模式。

用 GitHub 评论授权修复

再次以新评论发布请求，并确认其 Trigger 出现。Superagent 应将其视为明确请求并启动工作进程。

评论提及创建了已授权的 Ticket。作者制图。

检查代理的事件去重修复

相应的拉取请求 将修复锚定在 event_id 上。请审阅 diff，而不要仅依赖其描述：

 def daily_revenue(events):
     """Return one row per UTC day with total revenue in cents."""
+    # The payment webhook may deliver the same event more than once, with a
+    # different received_at but the same event_id. One event_id is one payment
+    # event, so keep only its first delivery before aggregating.
+    events = events.drop_duplicates(subset="event_id", keep="first")
     days = events["occurred_at"].dt.strftime("%Y-%m-%d")技术支持

它新增了重放测试且未删除任何内容。第一次测试命令因缺少依赖而失败；在工作进程创建虚拟环境后，可见测试集通过。

测试共享同一订单的付款

在不提及代理的情况下请求更改：证明同一订单的两笔付款（除 event_id 外完全相同）都会计入，且其中一笔的重放只计一次。评审应回到同一 Ticket 而无新的评估。

工作进程以仅新增测试、不改动管道的提交作出响应。在批准前，核对精确的 head SHA，并针对该修订运行独立测试集。

评审反馈会继续同一 Ticket。作者制图。

用独立数据检查修复

在独立的人类环境中针对精确的拉取请求 head 运行保留集。在 a43c541 上，两个测试集均 5/5 通过，且未移除任何断言；62bac08 保持了相同的树。

仅由代理编写的测试只覆盖代理自行选择的情形。

步骤 7：合并修复并衡量 CI 恢复

合并后，检查 main 是否恢复为绿色，并确认恢复不会启动新工作。随后审查事件轨迹、耗时与供应商计费。

合并修复并确认 CI 恢复

在人工批准并合并后，两个默认分支检查均通过。Superagent 忽略了恢复、未启动更多工作，并以 merged 结果关闭了现有 Ticket。

评估事件取件与决策

按照我们的 AI 代理评估指南所述，从取件到结果追踪每个事件。三次重复中，进入 Eval 的事件都走了预期路径；遗漏发生在取件阶段，而非模型决策。

衡量修复正确性、耗时与成本

同一场景在三个全新仓库与 WSL 发行版上以 Superagent 6337fc8、Harness 0.2.1-rc.3、deepseek-flash 与同一策略重复执行。成本使用 DeepSeek 的低峰时段费率；这些是复现，不是基准测试。

三次修复均使用 event_id；所有保留集测试通过。取件差异更大：Issue 正文的提及每次都被遗漏，第三次复现还在两条评论被遗漏后才有一条到达。

第二次复现重写了提交，且在保留集重新运行前就收到了批准。后续检查通过，但更安全的顺序是：确认 head SHA、运行保留集、然后批准。

DeepSeek Superagent 的限制与排障

此处的若干失败表现为“无声”，因此先找出事件停止的位置。令人沮丧的是：遗漏通知与被正确忽略看起来可能相同。

未产生 Trigger 的 CI 故障

Superagent 跟踪失败集合的变化，因此基线读取、持续失败的检查与仍在运行的检查不会产生任何内容。一个没有决策的 Trigger 通常指向 CI 准入单元格，而非模型本身。

从未到达的 GitHub 请求

当发送者未获准、Source 关闭、处理暂停或 GitHub 通知延迟时，请求可能失败。若这些检查都通过，请发布一条新评论；编辑 Issue 正文不会产生事件。

自主 CI 修复的局限

该原型不提供安全边界。工作进程拥有完整的 OS 用户访问权限，披露规则仅是提示文本。请隔离代理账户，并将其限制在一次性仓库中。

在切换到 auto 前，收集数周的观察决策，同时统计误接收与误忽略，并将工作进程从 WSL 迁移到独立虚拟机。

总结

开头的对比得以保持：两个红色 CI 状态不应导致相同操作。Superagent 忽略了 docs-check，并将 revenue-integrity 标记为 "would accept"，而观察模式在有人发出修复请求前保持代码不变。

基于 event_id 的补丁很直接。通知取件不够可靠：Issue 正文的提及从未到达 Eval，因此再正确的规则也无能为力。

我不会将此结果泛化到自主 CI 修复。该仓库很小、规则很窄、合并受人控制。在其他场景中，请从绿色开始、检查决策、明确授权、将保留数据分离，并在独立检查后合并。

下一步，我会先修复 GitHub 通知路径，再用更多故障类型重复该工作流。在得到这类证据前，我会保持 auto 模式关闭。