dsh-superagent 部署跑不通？新手配置、权限与工具调用的排查指南

【免费下载链接】dsh-superagent-prototypeTowards a More Autonomous Agent System项目地址: https://gitcode.com/gh_mirrors/ds/dsh-superagent-prototype

dsh-superagent 是一个面向单个 GitHub 仓库的主动编码智能体：当被允许的账号在 Issue、评论或飞书群里 @ 它之后，它会自动创建任务、在独立的会话和目录里修改代码，然后回到原对话交付结果（通常是 Pull Request）。它打包在 DeepSeek Harness 框架上运行，并附带一个网页面板展示需要人工介入的事项。

这篇文章不讲解代码实现，只回答一个问题：为什么你配了之后它就是不工作。它写给三类人：有 GitHub 仓库、希望减少重复性开发流程、并且由几个人小团队协作的人。如果你只是想找一个写文案的聊天机器人，可以关掉本页。

下面把"跑不通"拆成可判断的信号，给你一套从现象到修复的标准动作。

先判断它适不适合你的场景

在排查之前先确认边界，能省掉大量无效调试。

适合：

• 你维护一个 GitHub 仓库（github.com 公有云，不支持 GitHub Enterprise Server），希望 Issue/评论里的需求能被自动接单并产出代码变更。
• 你有 Node（22.19+ 或 24+）、git、pnpm、Python 3.8+、tmux 这些基础设施，并且配置了可用的模型服务商账号——模型能力来自你配置的提供商，本地不需要 GPU 或大模型。
• 你接受"一个仓库、一个代理账号"的克制设计，飞书接入作为可选项（lark-cli+ 自建应用机器人）。

不适合：

• 需要同时处理多个仓库、或希望覆盖多个代码托管平台。
• 期望开箱即全自动：默认策略偏保守，先观察它"本会做什么"，再逐步放开授权。
• 把它当生产级软件：它是研究原型，README 明确提醒可能存在 bug、风格不一致，接入前需自行审查。

判断清楚之后，再往下排障。

新手最常卡住的三类信号

绝大多数报错可以归入"信号"的三个阶段：身份没通过、请求没触发、任务没执行。对号入座比逐个试错快得多。

身份信号：先确认代理账号和 CLI 本身可用

这一类现象是：请求明明发到了正确的地方，但系统表现为无反应或反复提示账号问题。根因几乎都在"它能不能以自己的身份干活"：

• GitHub 侧：面板提示代理的gh命令行未设置、找不到、或读不到账号时，依次确认三件事——CLI 包装脚本装好了没有、脚本是否已用自己的凭据登录、该账号对目标仓库是否有写权限。写权限缺失的典型提示是"某账号读不了/推不上去某仓库"。
• 飞书侧：它要求一个纯机器人身份的lark-cli配置。如果你把带个人登录的配置指过去，检查会直接拒绝，原因是"这个 CLI 能以人的身份发言"。给它一个独立的配置目录和只限机器人身份的 strict-mode 设置即可。
• 排查顺序固定为：先验身份，再验权限，最后验仓库地址是否写错。面板上这类"需要你动手"的提示一般会直接链到对应设置项，顺着点比翻日志快。

触发信号：没有生成任务时先查触发源

"没触发"和"参数不对"是两件事，面板上有没有生成工单（Ticket）是一秒区分法：没有工单，说明请求根本没被接收，查触发链路；有工单但失败，才去查执行链路。

没工单时，按顺序检查：

• 喊话方式：在 GitHub 上，编辑旧 Issue 正文追加 @ 不算触发，必须发一条新评论；轮询间隔默认一分钟，先稍等再看。
• 白名单：Policy 里对应来源的允许账号列表为空，或你的账号不在名单里，任何请求都无法变成任务。
• 来源开关：对应 Source 是否处于开启状态。
• 全局暂停：处理流程被暂停时，一切输入都会被挂起。

执行信号：任务失败时先看执行目录和依赖版本

工单已生成但卡在失败，通常落在执行环境。系统内部有几档完全不同的时间预算，"超时"的含义是耐心到了，而不是进程崩溃：

• 调用外部命令行工具约90 秒无响应即判超时；
• 为工单准备目录的操作，最长约10 分钟；
• 一轮任务结束后，后台仍在跑的任务最多再保留30 分钟，到点被回收；
• 判断"这条请求该不该接"的评估，超时可在30 秒到 10 分钟之间调整。

两个高频误判：

• 输出被截断不等于结果不全。命令行输出有上限（超出会直接提示打印内容过多），上下文读取要分页，提示词配置也有字数上限、超了拒存。对策是分次读取、先要摘要再要细节，这是使用智能体类工具的基本功。
• 很多"超时"背后是一个卡住的交互提示，比如在等登录确认。用同一个账号、同一套环境手动执行一遍那条命令，真实报错会立刻显形。把慢操作放到后台执行，不要让它们堵在关键路径上。

从报错到修复的标准动作

拿到现象后，按"看现象 → 归类 → 执行动作 → 避开误区"走，不要先重启。

第一步：看面板和状态。scripts/dsh-superagent status的退出码是一张体检表：

• 0：服务正常运行，别动它。
• 1：没跑起来、跑了两个实例、无响应、或运行时报错——只有这一档重启才有意义。
• 2：服务活着，但某个部件（如某个来源同步）报错——重启无效，要修那个部件；errors字段会点名具体部件。
• 3：服务在等你的配置补齐——重启更无效，补完设置它自己恢复。

第二步：给报错归类。

第三步：改对地方。身份和权限问题改账号与配置；路径问题改执行环境设置；版本问题对齐依赖；接口问题改请求。只有第 1 档状态适合重启——对 2 和 3 反复重启属于无效操作。

常见误区：把"重启"当万能药；用编辑正文的方式 @ 代理；拿着个人账号配置去配机器人来源；看到超时就断定服务坏了。

版本、配置与接口边界

这三类问题看起来"毫无逻辑"，实际都有确定解法。

版本不对齐。典型症状：git 太旧读不到代理凭据配置；dsh版本超出package.json里engines.dsh声明的范围，日志提示插件与运行框架不兼容；升级 DeepSeek Harness 后面板加载不出插件；会话恢复时报agent-preset/not-found。共同点是代码和配置都没错，只是版本没对齐。处理办法两条：依赖版本装进项目声明的范围；升级框架后重启运行中的实例，让它重新加载对应产物。另外，被新版本迁移过的数据库无法被旧版本打开，回滚必须依赖升级前的备份。

占位符没替换。示例配置 examples/profile.cordis.patch.yml 里所有<placeholder>必须逐一替换。两个硬约束：stateDir必须是绝对路径；出现任何系统不认识的配置键会直接阻止启动（日志会指出键名）。还有一类隐蔽拦截：如果它发现自己管理的worker-bin、worker-gitconfig目录里存在非它写入的文件，会停止设置流程——这是防止更新时覆盖你的手写内容。解法是把文件移走或换一个stateDir。

接口状态码不是服务器故障。管理 API 限定从本机访问（127.0.0.1或localhost），且请求需携带约定头x-orchestrator-request: 1：

• 403：请求方式不合规——不是从本机地址发出，或缺少约定请求头、Origin来自其他站点。它不是"你没权限"，而是敲门姿势不对。
• 409：你提交时携带的是旧版本号（revision），服务端已有更新。重新拉取最新 revision 再提交即可。
• 400：值不合法（响应会列出具体字段路径）、账号检查未通过、或请求体不是合法 JSON / 过大。

读懂状态码指向的约束，比盲目重试有用得多。

收尾：三条行动清单

1. 先让看板变绿，再谈效果。依次完成：CLI 安装与登录 → 仓库写权限 → 白名单与来源开关 → 执行目录与准备命令。状态码为 0 之前，任何"它不聪明"的结论都不成立。
2. 报错先分类再动手。没听见（查触发）、没权限（查账号）、没参数（查目录与命令）、没等到（查超时与交互卡点）、版本不对（查依赖范围）——分类错了，努力全白费。
3. 先窄后宽。保持默认的低主动策略，观察它"本来会做什么"，确认靠谱后再逐步放开授权；让服务状态稳定，比追求全自动更重要。

它只盯一个仓库、只接一个平台、飞书可选项——这种克制反而让配置问题都有确定的排查路径。如果你部署时卡在了某个状态码或某条提示上，欢迎在留言里贴出现象和面板状态，也许正好能帮到下一个遇到同样问题的人。

【免费下载链接】dsh-superagent-prototypeTowards a More Autonomous Agent System项目地址: https://gitcode.com/gh_mirrors/ds/dsh-superagent-prototype