DeepSeek Harness Superagent 部署与运维：安装、启动、检查、升级、排障

系列第 7 篇。本文覆盖账号、启动检查、升级和 troubleshooting，建立在第 1 到第 6 篇之上。

---

一、系统里实际会运行什么

• 一个专用的 DeepSeek Harness profile，本指南叫 superagent。从 Web profile template 创建。它加载 bundle，并在 127.0.0.1 上提供面板。与工作 profile 分开：插件会修改 process-wide PATH 和 git settings，而且它的进程需要独立重启和升级。
• 一个 agent GitHub account。 Agent 以这个账号评论、push branch、开 PR，通过一个只登录该账号的 GitHub CLI。
• 可选： 一个 Feishu bot 用于聊天请求。

Plugin configuration 持有 state directory 和 machine limits。其他都通过面板设置：Source 对应仓库和账号，Policy 对应允许名单，Execution 对应 worker 目录和命令。

权限与隔离

Bundle 定义 dsh-superagent-worker 给 Executor，dsh-superagent-router 给主 Session。它们出现在 DeepSeek Harness preset 列表中，但只用于 dsh-superagent。不要为 personal Session 选择它们，也不要禁用它们的 configuration rows。应用需要它们创建和恢复 Session。

Web UI 中打开空白 managed Session 可能选中 profile 默认 preset。dsh-superagent 会在第一轮前恢复角色专用 preset。

两个 preset 都以 danger-full-access 运行，作为操作者 OS 用户，并读取订阅 Thread 的消息。Account wrappers 默认选择 agent 凭据，但不会隔离进程。Worker 可以通过路径执行程序并读取操作者 home 目录。真正隔离应使用只含 agent 凭据的专用 OS account。

二、Prerequisites

• Node.js 22.19+ 或 24+、pnpm、git 2.32+、Python 3.8+、tmux
• GitHub CLI (gh) 2.48 或更高。Source CLI 字段必须指向 gh 或 lark-cli wrappers；host 依赖它们的 subcommands 与输出格式。
• 一个 github.com 仓库；不支持 GitHub Enterprise Server。为每个 Ticket 创建 checkout，需要保留一个本地 clone，prepare command 可以从中添加 worktree。仓库使用 Git LFS 时安装 git-lfs。
• 为 DeepSeek Harness 配置 model provider。dsh-superagent 使用 profile 默认模型，除非 Eval 或 Execution settings 指定另一个。
• Feishu 需要 lark-cli（测试版本 1.0.90）和带 bot 的 Feishu/Lark app。

三、Accounts

Agent GitHub account

1. 为 Agent 创建 GitHub 用户，并给仓库 write access。GitHub App 不能作为 Agent，因为 dsh-superagent 读取该账号 notifications。
2. 给它一个只使用自己凭据的 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 账号登录；最后命令打印 login。dsh-superagent 用同样方式读取 login。

Feishu bot（可选）

1. 创建带 bot capability 的自建应用。授予接收消息事件、读取和发送聊天消息、读取聊天成员的权限，然后发布应用版本。
2. 给 bot 一个只限制为 bot 身份的 lark-cli 配置，以及一个 wrapper：

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

第一条命令从 stdin 读取 app secret。使用独立配置目录：lark-cli 每个 app id 只允许一个 profile，你的个人配置可能已经有该 app 的用户登录。

Host 拒绝可以以用户身份行动的 CLI。它从 bot 配置读取 app id、Feishu/Lark brand、bot open_id。

两个配置共享 app secret 的 keychain entry。只删除 bot 配置时删除其目录；不要运行 lark-cli config remove，它会破坏共享 secret。

四、Install

在没有 superagent 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"

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

第四条命令从 DeepSeek Harness Web template 创建 ~/.dsh/profiles/superagent。第五条安装 bundle。设置 DSH_HOME 可移动默认 ~/.dsh 目录。

只在全新安装时运行 profile-creation 命令。如果 profile 已存在，该命令会替换它并删除其 cordis.patch.yml，包括机器配置。不要用于 upgrade。

五、Machine configuration

把 examples/profile.cordis.patch.yml 复制到 ~/.dsh/profiles/superagent/cordis.patch.yml，替换该文件，并替换每个 <placeholder>。Feishu 还需在那里启用 dsh-superagent-feishu entry。webserver entry 设置面板端口。

Key	Required	Meaning
stateDir	yes	绝对路径：database、lock、worker-bin 中的 command shims、agent git configuration，以及默认的 work 中 Ticket directories。升级前备份
promptMaxChars, admissionContextMaxPages, admissionContextTimeoutMs	no	最大保存 prompt 配置；一个 assessment 读多少 Thread pages、在什么时间内

首次启动后，在 Settings → Deployment 或 Plugin Manager 编辑 machine limits。修改无需 restart。stateDir 不能在那里修改。无效值或未知配置 key 阻止启动；日志会指出 key。

六、Start and stop

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

start 在 tmux session dsh-superagent 中运行 dsh --profile superagent，其他 profile 为 dsh-<profile>。它等待最多一分钟，直到 runtime ready 或报告 setup requirement。首次运行会打印缺少的 setup 信息。它拒绝重复实例，包括脚本外启动的实例。

stop 与 restart 请求 graceful shutdown，并等待 Executors 最多五分钟。它们永不 force-kill 进程，也不碰其他 tmux sessions。

status 打印 process ids、health 和 setup problems。不同 profile 或端口使用 --profile 和 --url，或设置 DSH_SUPERAGENT_PROFILE、DSH_SUPERAGENT_URL。

status、start、restart 以四种 code 之一退出：

Code	Meaning
0	服务正常运行
1	不运行、运行两份、不响应，或 runtime 报告 error；restart 可能修复
2	运行中，但 runtime 以外的 part（例如 Source 或 Policy sync sync:<source id>）报告 error；restart 不能修复
3	运行中并等待 setup；restart 不能修复

仍处 starting 状态的 Source 算正常运行。setup 无法检查的 Feishu bot 也算。

status 在 errors 下返回 failed parts 与详情，在 setup 下返回 setup requirements。start 和 restart 以行打印这些问题；如果服务始终无法启动，exit 1。只有主动 stop 会暂停自动恢复。

每个 profile 在 .artifacts/ 下存日志和控制文件：

• Startup logs：dsh-superagent-<profile>-<date>-<time>-<pid>.log，pid 属于脚本。保留最新 20 个。
• Control files：control/profiles/<profile>/，包含 stop marker、lock、process id。

打开日志中打印的 URL，在侧栏选择 Superagent。

Hourly check

在平时使用的 DeepSeek Harness profile 中创建 hourly check，不要在 superagent 中。Agent 服务 down 时它必须继续运行。请该 profile 中的 Agent 创建 hourly schedule，并填入 checkout path：

Check dsh-superagent: run `scripts/dsh-superagent --profile superagent status` in <checkout>. Exit 0: do nothing and say nothing. Exit 2: do not restart; tell me each part under `errors` with its detail, unless you already told me about the same ones. Exit 3: do not restart; tell me what `setup` says setup needs, unless you already told me. If it reports manually_stopped: true, leave it stopped. Otherwise (exit 1) run `scripts/dsh-superagent --profile superagent --respect-stop restart`, which exits the same way: 0 means it recovered, so say nothing; 2 and 3 are reported as above; if it exits 1 or fails otherwise, read the newest .artifacts/dsh-superagent-superagent-*.log and the Troubleshooting section of docs/006-deployment.md, fix what you can, and tell me what was wrong and what you did.

--respect-stop 保留主动 stop。只有 stop 写 marker；start 清除它。restart 不写 marker，因此 check 可以恢复 shutdown 超时的 restart。

七、Settings

Polling 或 work 开始前 setup 必须成功。Overview 列出缺失要求并链接到设置。设置变化会再次运行 setup。如果修复了应用外的东西，例如 CLI 认证，选择 Check again。

1. Sources. 设置 GitHub repository（owner/name）和 agent CLI，例如 /home/me/.local/bin/gh-agent。请求通常通过 agent account notifications 到达。新 Issue 或提到账号的 comment 在下次 poll 到达；编辑已有 Issue body 添加 mention 不会。请发新 comment。Feishu 设置 bot CLI、chats、每个 chat 的 receive-all 或 mentions-only mode、是否接收私聊。
2. Policy. 两个 example rules 可编辑或删除。在 On each Source 下添加可以发起工作的 GitHub accounts 和 Feishu users；名单为空前，任何请求都不能成为 Ticket。Feishu 可以选择一个 chat，在 startup 和 Sync now 时同步名单。
3. Execution. Directory root 和 prepare command。给每个 Ticket 一个仓库 checkout：

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）列为 blocked commands。

4. Prompts. 设置 team sections：GitHub disclosure line、review bots、commit author、auto-merge condition。

Management API

面板使用本地 HTTP API，Agent 也可以调用。SETUP.md 用它保存设置，service script 读 GET state。

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

API saves 具有面板权限。它们可以修改执行环境和 setup account fields，这与通过主 Session tools 的 saves 不同。

Agent 可以依赖这些 routes 和 fields。src/app/api.ts 中其他 routes 服务面板，并随面板变化。

Request	Answer
GET state	每页读取的内容：setup，含 problem 和 feishuProblem；health；load；paused；masterId
GET settings	blocks、sources、policyVersion、environment
GET sources	每个 Source status：state、health、setup problem、last day stats、filtered/dropped messages
PUT settings/<block>	保存一个 block：saved、新 revision、policy_changed、restarting
POST executor/pause	暂停或恢复处理
POST setup/check	重启 dsh-superagent 再次运行 setup
POST policy-sync/<source id>	同步该 Source 的允许名单
GET prompts, PUT prompts	读取或保存 prompt configuration
POST tickets/<id>/retry, POST tickets/<id>/stop	Retry 或 stop Ticket

Health entries 按责任分组：

Entry	Reports
runtime	应用本身
models	等待 model-budget retry 的 Sessions
evals	过去一小时内无后续 judgement 或 dismissal 的 unavailable Evals
assessment, launch, delivery, relay, notice, reply	第 4 篇描述的 stored work
worker	Executor Session event handling
github, feishu, history	Source polling、events、history recovery
sync:<source id>	Allowed-list synchronization

Refusal 有 status 和英文 error：

• 400：无效值、账号检查失败、固定 refusal、非 JSON 或 body 过大。
• 404：不存在。
• 409：stale revision。
• 500：其他。

Blocks 的结构在原文中有完整 JSON 形状。下面是一个最小更新示例：

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}"

八、Setup checks

Setup 使用 DeepSeek Harness subprocess service，和 worker shells 一样。它移除名称含 KEY、PASSWORD、SECRET、TOKEN 的环境变量。

Setup 验证 GitHub repository 和 agent push access，写 worker environment，并检查 git 只使用 agent 凭据访问 github.com。Feishu setup failure 只禁用 Feishu Source。

Setup 写入的 process environment：

• Command shims 在 <stateDir>/worker-bin，位于 PATH 最前：gh 运行 agent CLI；lark-cli 运行 bot CLI；blocked commands fail。Shim 在运行目标前从 PATH 移除自己的目录。
• git configuration 在 <stateDir>/worker-gitconfig：替换操作者 global 和 system git config。它选择 agent CLI 作为 github.com credential helper，重写 GitHub SSH 地址为 HTTPS，并定义 Git LFS filters。个人 git settings（如 HTTP proxy）不适用。这里不设置 commit identity，git 永不提示凭据，GH_TOKEN、GITHUB_TOKEN 被移除。

worker-bin 或 worker-gitconfig 中非 dsh-superagent 写入的文件会阻止 setup。Ticket directory 在自带 credentials 的 git repo 内，会导致 Ticket 失败。

九、Try it

从允许的 GitHub 账号打开 Issue 或发评论，包含 @<agent login> <request>。在默认一分钟的 polling interval 内，Overview 应显示 Ticket。Agent 确认请求，在自己的 Session 和目录中工作，并在原会话交付。Feishu 则在配置 chat 中 @ bot。

十、Upgrade

1. 等到没有 Executor 在 turn 中。
2. 备份 <stateDir>/orchestrator.sqlite。
3. 运行 git pull && pnpm install && pnpm build。
4. 运行 scripts/dsh-superagent restart 并检查 status。

Restart 结束 running Assignments 并启动带 recovery note 的 replacements。Team text 和 overridden prompt parts 保留；没有 override 的 parts 跟随新默认值。升级后检查标记 Default updated 的 parts。

新版本迁移的 database 不能被旧版本打开。Rollback 需要升级前备份。升级 DeepSeek Harness 本身后，restart 运行实例，使面板加载匹配 artifacts。

Agent presets

Worker 和 router presets 在 5 秒后把 shell 命令移到后台。Session 没有 preset 就无法加载。Session 使用期间保留 dsh-superagent-worker 和 dsh-superagent-router rows；否则 resume 会失败并显示 agent-preset/not-found。

十一、Troubleshooting

Setup problems 出现在 overview，并链接到修复位置，以面板语言显示；日志和 API 显示英文文本。

Symptom	Cause and fix
The agent GitHub CLI is not set.	在 GitHub card 设置 agent CLI
The agent GitHub CLI was not found.	设置 wrapper 绝对路径，或 PATH 上的命令名
The agent GitHub CLI cannot read its account	用 auth login 登录 wrapper
@… cannot read … 或 @… cannot push to …	给 agent 账号仓库 write access
The GitHub Source names no repository.	设置 owner/name
Ticket fails The prepare command failed: …	输出说明原因；修好命令后 retry Ticket
git does not read the github.com credential configuration dsh-superagent writes	安装 git 2.32+
Ticket fails The git configuration of the repository in … sets …	从 clone .git/config 删除 credentials 或 http.*.extraheader
… was not written by dsh-superagent	移动 <stateDir>/worker-bin 或 worker-gitconfig 中的文件，或换 stateDir
The bot lark-cli allows user identities	把 Feishu Source 指向 bot-only 配置
The bot lark-cli does not work. 或 The bot identity of app … is …	检查 app id 和 secret
The Feishu bot is not a member of the chat.	在 chat settings 添加 bot
status exits 2	part 报告 error，restart 不修复；errors 指明每个 part
status exits 3	setup 等待；setup 说明缺少什么
status exits 1	服务不运行、运行两份、不响应，或 runtime error
CLI timeout/stopped/exited/could not run	以操作者用户手动运行命名程序，看它自己的消息
Panel 说 dsh-superagent 不响应	正在 restart，或因配置未启动；DeepSeek Harness log 说明原因
dsh-superagent configuration has keys it does not use	删除命名 keys
plugin incompatible	安装 engines.dsh 范围内的 DeepSeek Harness 版本
Panel shows “Failed to load plugins” after upgrade	restart 运行实例
Mention 后无反应	检查作者在允许名单、Source 开启、处理未暂停。GitHub 上编辑 Issue body 添加 mention 不会收到；请在 comment 中 @ Agent