SETUP

给负责与操作者一起部署 dsh-superagent 的 agent 看的说明。如果你是操作者本人，让你的编码 agent 读这个文件并按它执行。

部署流程怎么走

部署遵循 docs/000-理念.md：尽量少的占用操作者的注意力。

问第一个问题之前，只读这个文件和 docs/000-理念.md，并把下面的探测跑一遍。在所有答案收齐之前，不要读其它任何东西。
一条消息只问一个问题，只问一件事。等回答到了再问下一个。探测已经能回答的问题就跳过。
每条消息不超过 300 词，除非操作者要求更多。每个问题给出一个操作者可以一句话同意的推荐答案，并一句话说明它为什么重要。
问的时候不要动手。收齐所有答案后，发一条包含完整计划的消息，等操作者确认了才执行。
绝不在聊天里索要密钥。需要操作者动手的步骤（建账号、登录 CLI、填应用密钥等），放进一条消息里，附上要在他自己终端里运行的准确命令。
在提问中传递理念，一次一句话，不要开讲座。

1. 探测

在本仓库里跑一次，结果自己掌握：

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

前置条件：Node.js 22.19+ 或 24+、pnpm、git 2.32+、tmux、Python 3.8+、GitHub CLI 2.48+，以及 DSH 版本在 package.json 的 engines.dsh 范围内。缺哪个就把它变成计划里的一项，而不是一个问题。DSH 还需要一个模型 provider；如果操作者从没配过模型的 DSH，配置它属于操作者的步骤。
操作者登录名：gh api user 的结果是操作者自己的 GitHub 登录名，作为第 5 问的推荐值。
已有 profile：某个 profile 里已有 dsh-superagent 条目，说明是早前的部署：问是继续它、保留它的配置，并去读 docs/006-部署.md 的升级一节。

2. 提问

按这个顺序问，一条消息一个，跟着 docs/001-领域模型.md 的工作流走：先问 Trigger 从哪来，再问谁可以在那里提工作，最后问 Executor 拿到工单后要做什么。推荐值放在方括号里。

来源：请求从哪里来。

Sources。 agent 只从 GitHub 接收请求，还是也从飞书聊天接？[只 GitHub，除非团队在飞书里办公。]
仓库。 agent 要操作的 github.com 仓库是哪个，格式 owner/name？
agent 账号。 agent 以哪个 GitHub 用户身份行动？[专用账号，绝不用操作者自己的：agent 写出的所有东西都挂在这个名下。] 账号可以还不存在；建它属于操作者的步骤。
用飞书时：哪些聊天，按名字说。agent 在 bot 配置好之后查它们的 id。

策略：谁可以派活。

GitHub 上。 哪些 GitHub 登录名可以要求 agent 干活？[只 <操作者>：agent 的工作对操作者负责。]
用飞书时：哪些聊天可以派活？[默认只操作者所在的聊天，名单与成员同步。]

执行：agent 拿到工单做什么。

检出。 每个工单从哪个本地 clone 检出仓库？[在 ~/src/<name> 下新建 clone。]
提交署名。 agent 的 commit 作者写谁？[agent 账号，让它的工作看得出是它干的。] 另一个身份（比如操作者的）写进 Delivery requirements 提示词一节。
自动合并。 agent 自己的 PR 就绪且批准后，要不要开自动合并？[不要：人的合并是对的，就保持人合并，直到 agent 的 PR 长期都对。] agent 账号自己永远不开自动合并，所以选「要」就需要另一个有合并权限账号的 GitHub CLI：让操作者在操作者步骤里登录它，并在 Delivery requirements 里点名。选「不要」就把 Delivery requirements 里的自动合并段落删掉。

不要问有合理默认值的项；把它们列进计划：

profile 名 superagent：一份从 DSH Web profile 复制出来、与操作者工作用的 profile 分开的副本，所以它重启时不会关掉操作者的会话；端口 3082；状态目录 <home>/.dsh/state/superagent，用绝对路径；
每小时一次检查，从操作者自己的 profile 发起，dsh-superagent 没在跑时把它修起来；
分支前缀 agent/；
接受模式 observe：记录主动工作但不执行；默认规则与默认提示词各节；
用飞书时：bot 只读 @ 提及，私聊开关打开。

3. 计划

发一条消息，不超过 300 词：将安装什么、哪些账号和 CLI、要保存哪些设置、操作者步骤是什么、默认值是什么。要一次确认。

4. 执行

操作者步骤先行。 读 docs/006-部署.md 的 Accounts 一节，自己写好 CLI wrapper，然后发一条消息列出只有操作者能做的事：建 agent 账号；开了自动合并的话，用有权开它的账号登录一个 CLI；以 agent 账号接受仓库邀请；每个 wrapper 跑 auth login；用飞书的话，创建并发布 bot 应用，带着它的密钥跑 config init。等操作者说做完了，再用 <wrapper> api user --jq .login 逐个核对登录。
安装并启动。 按 docs/006-部署.md 的 Install、Machine configuration、Start and stop 三节做。跳过本仓库的 git clone：你就在它的 checkout 里。第 7 问要新 clone 的，去 clone 第 2 问的那个仓库。已有 profile 时，跳过 dsh superagent --from-default-profile 命令——它会替换 profile 并删掉它的 cordis.patch.yml；改为编辑那个文件，不要替换。
保存设置。 按 docs/006-部署.md 的 Management API 保存，顺序：github Source、（如用）feishu Source、policy 块。然后按 Delivery requirements 存提示词（第 8、9 问的答案）。返回 restarting: true 的保存会重启 dsh-superagent：等 scripts/dsh-superagent status 不再以 1 退出再发下一个请求，并从 GET settings 重新读 revision。
失败。 被拒的保存会在响应体里点名 setup 问题。去 docs/006-部署.md 的 Troubleshooting 表里找它，修好再继续。只有你自己修不了的才问操作者。

5. 验证与交接

scripts/dsh-superagent status 以 0 退出且没有 setup 问题。如果你运行在操作者自己的 DSH profile 里，用你的日程工具建 docs/006-部署.md Hourly check 一节里的那个每小时检查；否则把那条 prompt 交给操作者，让他在自己的地方排期。然后发一条消息，不超过 300 词：

面板 URL，以及侧边栏里 Superagent 条目是看哪里。
怎么试：用允许名单里的账号，在仓库的某个 issue 下评论 @<agent 登录名> <请求>。大约一分钟内，overview 上会出现工单。
给操作者的三条规则，来自 docs/000-理念.md 的 Responsibility 一节：从小开始、往少噪音调、为 agent 说的话负责。
想读更多：docs/ 里编号的文档，按顺序读。

Gitea Source 配置要点（本 fork）

替代或并存于 GitHub 的自建 Gitea 来源。设计决策见 GITEA-DESIGN.md，逐提交说明见 CHANGES.md。

启用与 sourceId：bundle 的 cordis.patch.yml 里插件 dsh-superagent-gitea 加 disabled: false，Source 的 sourceId 用 gitea。
凭据：Gitea 1.26 起 API 写路由拒绝 Basic，必须用 token；token 同时是 git push 的密码（凭据 store 同一规则），一个变量全链路。
轮询：pollSeconds 默认 60，可选 observeIssues / observePulls / observeComments 三个附加流。
bots 名单：Gitea 没有 is_bot 字段，防自激靠 login 名单手工维护。
git 兼容性：MSYS bash 自带 git 2.56 与 Gitea http/2 协议不兼容（clone 卡死），用 Git for Windows 2.39。
看板：Gitea 1.28 之前没有 Projects REST API，卡片同步用仓库内的 scripts/gitea-kanban-sync.mjs 直写数据库；约定随 Source 提示词注入（DSH_SUPERAGENT_GITEA_KANBAN）。

8.1 KiB Raw Blame History Unescape Escape