dsh-superagent 文档|006 部署

使用本指南来安装、配置和运行 dsh-superagent。它涵盖账号、安装检查、升级和故障排查，并建立在 001 领域模型 到 005 面板 的基础上。

运行着什么

• 一个专用的 DeepSeek Harness 配置（profile）
  ，本指南中称为 superagent。请从 Web 配置模板创建它。它加载插件包，并在 127.0.0.1 上提供其面板服务。请把它与你日常工作的配置分开：该插件会修改进程级的 PATH 和 git 设置，而且它的进程需要独立的重启和升级。
• 一个 agent 的 GitHub 账号。
   agent 以该账号进行评论、推送分支和开启拉取请求（pull request），所用的是一个仅以该账号登录的 GitHub CLI。
• 可选：
   一个用于聊天请求的飞书（Feishu）机器人。

插件配置里保存状态目录和机器限制。其余一切都在面板中完成：Sources 负责仓库与账号，Policy 负责允许列表，Execution 负责工作器目录和命令。

权限与隔离

插件包为执行器定义了 dsh-superagent-worker，为主会话定义了 dsh-superagent-router。它们出现在 DeepSeek Harness 的预设列表里，但仅供 dsh-superagent 使用。请不要为个人会话选择它们，也不要禁用它们的配置行。应用程序需要它们来创建并恢复自己的会话。

在 Web UI 中打开一个空白的托管会话，可能会选用该配置的默认预设。dsh-superagent 会在第一轮之前恢复其按角色划分的预设。

两个预设都以操作员（operator）的操作系统用户身份、使用 danger-full-access 运行，并从已订阅的对话线（thread）读取消息。账号封装脚本（wrapper）默认选择 agent 的凭据；它们并不会隔离进程。工作器可以按路径执行程序，并可以读取操作员的主目录。若要隔离，请使用一个专用的操作系统账号，其中只存放 agent 的凭据。

前置条件

• Node.js 22.19+ 或 24+、pnpm、git 2.32+、Python 3.8+ 和 tmux
• GitHub CLI（gh）2.48 或更高版本。来源的 CLI 字段必须指向 gh 或 lark-cli 封装脚本；宿主依赖它们的子命令和输出格式。
• github.com 上的一个仓库；不支持 GitHub Enterprise Server。若要为每个工单创建一份检出，请保留一个本地克隆，使准备命令能够从中添加工作树（worktree）。如果该仓库使用 Git LFS，请安装 git-lfs。
• 为 DeepSeek Harness 配置好一个模型提供方。除非 Eval 或 Execution 设置里指定了其他模型，dsh-superagent 使用该配置的默认模型。
• 使用飞书时：lark-cli（在 1.0.90 上测试过），以及一个带有机器人的飞书或 Lark 应用

账号

Agent 的 GitHub 账号

2. 为 agent 创建一个 GitHub 用户账号，并授予它对仓库的写权限。GitHub App 不能充当 agent，因为 dsh-superagent 会读取该账号的通知。
4. 给它一个只使用其自身凭据的 GitHub CLI：

mkdir -p ~/.local/bin cat > ~/.local/bin/gh-agent <<'EOF' #!/bin/sh GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@" EOF chmod +x ~/.local/bin/gh-agent gh-agent auth login gh-agent api user --jq .login 

以 agent 账号登录；最后一条命令会打印它的登录名。dsh-superagent 用同样的方式读取该登录名。

飞书机器人（可选）

2. 创建一个带有机器人能力的自建应用。授予它接收消息事件、读取和发送聊天消息、以及读取聊天成员的权限，然后发布该应用版本。
4. 给机器人一套它自己的 lark-cli 配置，限定为机器人身份，并做一个封装脚本：

LARKSUITE_CLI_CONFIG_DIR="$HOME/.lark-cli-dsh-superagent" lark-cli config init --app-id <cli_…> --app-secret-stdin LARKSUITE_CLI_CONFIG_DIR="$HOME/.lark-cli-dsh-superagent" lark-cli config strict-mode bot --global cat > ~/.local/bin/lark-bot <<'EOF' #!/bin/sh export LARKSUITE_CLI_CONFIG_DIR="$HOME/.lark-cli-dsh-superagent" exec lark-cli "$@" EOF chmod +x ~/.local/bin/lark-bot 

第一条命令从标准输入读取应用密钥（app secret）。请使用一个独立的配置目录：lark-cli 每个 app id 只允许一个配置文件，而你个人配置里可能已经包含了该应用的一个用户登录。

宿主会拒绝一个能够以用户身份行事的 CLI。它从机器人配置里读取 app id、飞书/Lark 品牌以及机器人的 open_id。

两套配置共用钥匙串（keychain）里存放应用密钥的条目。若只想移除机器人配置，删除它的目录即可；不要运行 lark-cli config remove，那会影响共用的密钥。

安装

在尚未拥有 superagent 配置的一台机器上，运行下面这一块一次：

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" 

上面锁定的版本是公开的；其他版本必须满足 package.json 中的 engines.dsh。

第四条命令从 DeepSeek Harness Web 模板创建 ~/.dsh/profiles/superagent。第五条安装这个插件包。设置 DSH_HOME 可以改变默认的 ~/.dsh 目录位置。

请只对新安装运行创建配置的那条命令。如果该配置已经存在，那条命令会替换它并删除其 cordis.patch.yml，其中也包括机器配置。升级时不要用它。

机器配置

把 examples/profile.cordis.patch.yml 复制到 ~/.dsh/profiles/superagent/cordis.patch.yml 并替换掉那个文件，然后替换每一个 <placeholder>。使用飞书时，还要在那里启用 dsh-superagent-feishu 条目。webserver 条目设置面板的端口。

首次启动之后，可在「设置 → 部署（Settings → Deployment）」或 DeepSeek Harness 插件管理器里修改机器限制。更改无需重启即可生效。stateDir 在那里无法修改。无效的值或未知的配置键会阻止启动；日志会指明那个键。

启动与停止

scripts/dsh-superagent start scripts/dsh-superagent status 

start 在名为 dsh-superagent 的 tmux 会话里运行 dsh --profile superagent，若是其他配置则为 dsh-<profile>。它最多等待一分钟，让运行时就绪或报告某项安装检查要求。首次运行时，它会打印缺失的安装检查信息。它拒绝重复的实例，包括在本脚本之外启动的实例。

stop 和 restart 请求优雅关闭，并为执行器最多等待五分钟。它们绝不会强杀进程，也不会触碰其他 tmux 会话。

status 打印进程 id、健康状态和安装检查问题。对于不同的配置或端口，使用 --profile 和 --url，或设置 DSH_SUPERAGENT_PROFILE 和 DSH_SUPERAGENT_URL。

status、start 和 restart 会以四种退出码之一退出：

仍在启动过程中的来源算作正常运行。安装检查无法检查到的飞书机器人也算作正常运行。

status 在 errors 下返回失败的部分及其详情，在 setup 下返回安装检查要求。start 和 restart 把这些问题打印成行；若服务始终未能起来，它们退出码为 1。只有一次有意为之的 stop 才会暂停自动恢复。

每个配置都在 .artifacts/ 下存储日志和控制文件：

• 启动日志：dsh-superagent-<profile>-<date>-<time>-<pid>.log，其中 pid 属于该脚本。保留最新的 20 个。
• 控制文件：control/profiles/<profile>/，内含停止标记、锁和进程 id。

打开日志里打印的 URL，然后在侧边栏选择 Superagent。

每小时检查

请在你平时使用的那个 DeepSeek Harness 配置里创建每小时检查，而不是在 superagent 里。当 agent 服务宕掉时它也必须继续运行。用下面这段提示（把检出路径填好）让该配置里的一个 agent 创建一个每小时计划任务：

检查 dsh-superagent：在 <检出路径> 中运行 `scripts/dsh-superagent --profile superagent status`。退出 0：什么都不做，什么都不说。退出 2：不要重启；把 `errors` 下的每个部分连同其细节告诉我，除非关于同样的这些我已经被告知过。退出 3：不要重启；把 `setup` 所说的安装检查需要什么告诉我，除非我已经被告知过。如果它报告 manually_stopped: true，就让它保持停止。否则（退出 1）运行 `scripts/dsh-superagent --profile superagent --respect-stop restart`，它以同样的方式退出：0 意味着它已恢复，所以什么都不说；2 和 3 按上面所述上报；如果它退出 1 或以其他方式失败，阅读最新的 .artifacts/dsh-superagent-superagent-*.log 以及 docs/006-deployment.md 的故障排查一节，修好你能修的，并告诉我哪里出了问题、你做了什么。 

--respect-stop 会保留一次有意为之的停止。只有 stop 会写入该标记；start 会清除它。restart 不写标记，因此该检查能够恢复一次关闭超时的重启。

设置

在轮询或工作开始之前，安装检查（setup）必须先成功。概览（Overview）会列出缺失的要求并链接到相应的设置。一次设置更改会重新运行安装检查。如果你在应用之外修复了某些东西，例如 CLI 认证，请选择「再检查一次（Check again）」。

2. Sources（来源）。
    设置 GitHub 仓库（owner/name）和 agent CLI，例如 /home/me/.local/bin/gh-agent。请求通常经由 agent 账号的通知到达。一个新的议题或提到该账号的评论会在下一次轮询时到达；通过编辑已有议题正文来添加一次 mention 是不会到达的。请改发一条新评论。使用飞书时，设置机器人 CLI、各个聊天、每个聊天的「接收全部」或「仅提及」模式，以及是否接收私信。
4. Policy（策略）。
    两条示例规则可以编辑或删除。在「每个来源上（On each Source）」下，添加可以请求工作的 GitHub 账号和飞书用户；在某个列表填入某人之前，任何请求都不会变成工单。使用飞书时，可以选择一个聊天从中同步该列表，在启动时以及点「立即同步（Sync now）」时进行。
6. Execution（执行）。
    目录根和一条准备命令。若要为每个工单提供一份仓库检出：

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" 

把个人 CLI 列为被屏蔽命令，例如某个登录到你自己账号的 CLI。 4. Prompts（提示词）。 设置团队各节：GitHub 披露行、评审机器人、提交作者以及自动合并条件。

管理 API

面板使用一个本地 HTTP API，agent 也可以调用它。SETUP.md 用它来保存设置，而服务脚本读取 GET state。

向 http://127.0.0.1:<port>/orchestrator/api/ 发送请求，并带上 x-orchestrator-request: 1。Host 必须是 127.0.0.1:<port> 或 localhost:<port>。缺少请求头，或带有来自其他站点的 Origin，都会收到 403。

通过 API 进行的保存拥有面板的权限。它们可以修改执行环境以及安装检查的账号字段——这与通过主会话的工具所做的保存不同。

agent 可以依赖这些路由和字段。src/app/api.ts 里的其他路由只服务于面板，并随面板而变。

健康条目按职责分组：

一次拒绝（refusal）带有一个状态码和 error（其英文文本）：

• 400：一个无效的值（issues，每项带其 path）、一次失败的账号检查（setup）、一个固定的拒绝（code 和 values），或一个不是 JSON 或过大的请求体。
• 404：某个不存在的东西。
• 409：一个过期的版本号（revision）。
• 500：其他任何情况。

各区块如下：

• source:github
  、source:feishu：{"enabled": true, "config": {…}}。GitHub 的 config 有 repository 和 cli，以及默认关闭的开关 observeIssues、observePulls、observeComments 和 observeCi——它们接收仓库里每一个新议题、新拉取请求和评论，以及默认分支的 CI；飞书的 config 有 cli、形如 [{"chatId": "oc_…", "name": "…", "listen": "mentions"}]（或 "all"）的 chats、directMessages，以及取值为 "none" 或 "mentions" 的 otherChats。
• policy
  ：{"rules": […], "sources": {"github": {"allowed": [{"id": "<login>"}], "bots": [{"id": "dependabot[bot]"}]}, "feishu": {"allowed": [{"id": "ou_…", "name": "…"}], "syncChat": "oc_…", "admission": {"oc_…": {"unlistedAddressed": "explicit"}}}}}。bots 列出其消息可以成为推断候选项的那些机器人。一条 admission 行以聊天 id 为键——对飞书而言用 other 或 direct，对 GitHub 而言用 issues、pulls、comments 或 ci；一个未设置的单元格取其默认值（见 002 授权）。
• eval
  ：mode、timeoutSeconds 和 model。
• executor
  ：model、maxWorkers、directory、prepare 和 blockedCommands。那个处理暂停是它自己的一个设置项 paused，由 POST executor/pause 设置。

更改一个仓库或一个 CLI，会先运行相应的安装检查。一次失败的检查返回 400，细节在 setup 中。一次成功的账号更改，或在安装检查仍待完成时进行的任何保存，都返回 restarting: true。应用重启期间该 API 暂时不可用。

api=http://127.0.0.1:3082/orchestrator/api 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}" 

安装检查

安装检查使用 DeepSeek Harness 的子进程服务，正如工作器 shell 那样。它会移除名字中包含 KEY、PASSWORD、SECRET 或 TOKEN 的环境变量。

安装检查会验证 GitHub 仓库以及 agent 的推送权限，写入工作器环境，并检查 git 对 github.com 是否只使用 agent 的凭据。一次飞书安装检查失败只会禁用飞书 Source。

安装检查所写入的进程环境：

• 位于 <stateDir>/worker-bin 的命令 shim，排在 PATH 最前：gh 运行 agent 的 CLI；lark-cli 运行机器人的 CLI；被屏蔽的命令会失败。一个 shim 在运行其目标之前会先从 PATH 中移除它自己所在的目录。
• 位于 <stateDir>/worker-gitconfig 的 git 配置：取代操作员的全局与系统 git 配置。它选择 agent CLI 作为 github.com 的凭据助手，把 GitHub 的 SSH 地址改写为 HTTPS，并定义 Git LFS 过滤器。个人的 git 设置（例如某个 HTTP 代理）不适用。这里不设提交身份，git 从不弹出凭据提示，而 GH_TOKEN 和 GITHUB_TOKEN 会被移除。

一个位于 worker-bin 或 worker-gitconfig 中、并非由 dsh-superagent 写入的文件会使安装检查停止。一个位于某个 git 仓库之内、而该仓库自身配置添加了凭据的工单目录，会使该工单失败。

试一试

从一个允许的 GitHub 账号，开一个议题或发一条包含 @<agent 登录名> <请求> 的评论。在一个轮询间隔之内（默认一分钟），概览应当显示出一个工单。agent 会确认该请求，在它自己的会话和目录里工作，并在原对话中交付。使用飞书时，在一个配置好的聊天里 @ 该机器人。

升级

2. 等到没有执行器正处于某一轮中间。
4. 备份 <stateDir>/orchestrator.sqlite。
6. 运行 git pull && pnpm install && pnpm build。
8. 运行 scripts/dsh-superagent restart 并检查它的状态。

一次重启会结束正在运行的 Assignment，并带着恢复说明（recovery notes）启动替代者。团队文本和被覆盖的提示词部分会保留；没有覆盖的部分跟随新的默认值。升级后请检查那些标为「默认值已更新（Default updated）」的部分。

一个被更新版本迁移过的数据库无法被更旧的版本打开。因此回滚需要升级前的备份。升级 DeepSeek Harness 本身之后，重启正在运行的实例，以便面板加载相匹配的构件（artifacts）。

Agent 预设

工作器和路由器预设会在 5 秒之后把 shell 命令放到后台。一个会话若没有它的预设就无法加载。在这些会话仍在使用期间，请在 cordis.patch.yml 中保留 dsh-superagent-worker 和 dsh-superagent-router 两行；否则恢复会失败并报出 agent-preset/not-found。

故障排查

安装检查问题会以面板所用语言出现在概览上，并附上通往修复方法的链接；日志和 API 显示下面这些英文文本。