# SETUP

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

## 部署流程怎么走

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

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

## 1. 探测

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

```sh
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](docs/001-领域模型.md) 的工作流走：先问 Trigger 从哪来，再问谁可以在那里提工作，最后问 Executor 拿到工单后要做什么。推荐值放在方括号里。

**来源：请求从哪里来。**

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

**策略：谁可以派活。**

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

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

7. **检出。** 每个工单从哪个本地 clone 检出仓库？[在 `~/src/<name>` 下新建 clone。]
8. **提交署名。** agent 的 commit 作者写谁？[agent 账号，让它的工作看得出是它干的。] 另一个身份（比如操作者的）写进 Delivery requirements 提示词一节。
9. **自动合并。** 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. 执行

1. **操作者步骤先行。** 读 `docs/006-部署.md` 的 Accounts 一节，自己写好 CLI wrapper，然后发一条消息列出只有操作者能做的事：建 agent 账号；开了自动合并的话，用有权开它的账号登录一个 CLI；以 agent 账号接受仓库邀请；每个 wrapper 跑 `auth login`；用飞书的话，创建并发布 bot 应用，带着它的密钥跑 `config init`。等操作者说做完了，再用 `<wrapper> api user --jq .login` 逐个核对登录。
2. **安装并启动。** 按 `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`；改为编辑那个文件，不要替换。
3. **保存设置。** 按 `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。
4. **失败。** 被拒的保存会在响应体里点名 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`）。