super_agent_bot/dsh-superagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: translate SETUP.md to Chinese

Browse Source
This commit is contained in:
Wanderingss
2026-11-02 23:41:34 +08:00
parent 2077e46a87
commit 6df83f6bdf
1 changed files with 54 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SETUP.md
+54 -67
View File
@@ -1,103 +1,90 @@
# SETUP # SETUP
Instructions for an agent that sets up dsh-superagent with its operator. If you are a person, ask your coding agent to read this file and follow it. 给负责与操作者一起部署 dsh-superagent 的 agent 看的说明。如果你是操作者本人，让你的编码 agent 读这个文件并按它执行。
## How to run the setup ## 部署流程怎么走
The setup follows [docs/000-philosophy.md](docs/000-philosophy.md): it takes as little of the operator's attention as possible. 部署遵循 [docs/000-philosophy.md](docs/000-philosophy.md)：尽量少的占用操作者的注意力。
- **Before the first question,** read only this file and `docs/000-philosophy.md`, and run the probe below once. Read nothing else until every answer is collected. - **问第一个问题之前**，只读这个文件和 `docs/000-philosophy.md`，并把下面的探测跑一遍。在所有答案收齐之前，不要读其它任何东西。
- **Ask one question per message,** about one thing. Wait for the answer before the next one. Skip a question the probe already answers. - **一条消息只问一个问题**，只问一件事。等回答到了再问下一个。探测已经能回答的问题就跳过。
- **Keep each message under 300 words,** unless the operator asks for more. Give each question a recommended answer the operator can accept with one word, and one sentence on why it matters. - **每条消息不超过 300 词**，除非操作者要求更多。每个问题给出一个操作者可以一句话同意的推荐答案，并一句话说明它为什么重要。
- **Do not execute while asking.** Collect every answer, then send one message with the full plan, and execute only after the operator confirms it. - **问的时候不要动手**。收齐所有答案后，发一条包含完整计划的消息，等操作者确认了才执行。
- **Never ask for a secret in the chat.** Steps that need the operator's hands, such as creating an account, signing a CLI in or entering an app secret, go into one message with the exact commands to run in their own terminal. - **绝不在聊天里索要密钥**。需要操作者动手的步骤（建账号、登录 CLI、填应用密钥等），放进一条消息里，附上要在他自己终端里运行的准确命令。
- **Teach the philosophy through the questions,** one sentence at a time, not as a lecture. - **在提问中传递理念**，一次一句话，不要开讲座。
## 1. Probe ## 1. 探测
Run from this checkout, once, and keep the result to yourself: 在本仓库里跑一次，结果自己掌握：
```sh ```sh
node -v; pnpm -v; git --version; tmux -V; python3 --version; gh --version | head -1; dsh --version node -v; pnpm -v; git --version; tmux -V; python3 --version; gh --version | head -1; dsh --version
gh api user --jq .login gh api user --jq .login
command -v lark-cli command -v lark-cli
grep -l -E 'id: dsh-superagent\b' "${DSH_HOME:-$HOME/.dsh}"/profiles/*/cordis.patch.yml 2>/dev/null grep -l -E 'id: dsh-superagent\\b' "${DSH_HOME:-$HOME/.dsh}"/profiles/*/cordis.patch.yml 2>/dev/null
``` ```
- **Prerequisites:** Node.js 22.19+ or 24+, pnpm, git 2.32+, tmux, Python 3.8+, GitHub CLI 2.48+, and DSH within the `engines.dsh` range of `package.json`. A missing one becomes an item of the plan, not a question. DSH also needs a model provider; if the operator has never run DSH with a model, configuring one is an operator step. - **前置条件**：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，配置它属于操作者的步骤。
- **Operator login:** the `gh api user` result is the operator's own GitHub login, used as the recommendation in question 5. - **操作者登录名**：`gh api user` 的结果是操作者自己的 GitHub 登录名，作为第 5 问的推荐值。
- **Existing profile:** a profile with a `dsh-superagent` entry is an earlier setup: ask whether to continue it, keep its configuration, and read Upgrade in `docs/006-deployment.md`. - **已有 profile**：某个 profile 里已有 `dsh-superagent` 条目，说明是早前的部署：问是继续它、保留它的配置，并去读 `docs/006-deployment.md` 的升级一节。
## 2. Questions ## 2. 提问
Ask in this order, one per message, following the flow of work in [docs/001-domain.md](docs/001-domain.md): first where Triggers come from, then who may ask for work there, then what the Executor does with a Ticket. Recommendations are in brackets. 按这个顺序问，一条消息一个，跟着 [docs/001-domain.md](docs/001-domain.md) 的工作流走：先问 Trigger 从哪来，再问谁可以在那里提工作，最后问 Executor 拿到工单后要做什么。推荐值放在方括号里。
**Sources: where requests come from.** **来源：请求从哪里来。**
1. **Sources.** Should the agent take requests from GitHub only, or also from Feishu chats? [GitHub only, unless the team works in Feishu.] 1. **Sources。** agent 只从 GitHub 接收请求，还是也从飞书聊天接？[只 GitHub，除非团队在飞书里办公。]
2. **Repository.** Which github.com repository should the agent work on, as `owner/name`? 2. **仓库。** agent 要操作的 github.com 仓库是哪个，格式 `owner/name`？
3. **Agent account.** Which GitHub user account will the agent act as? [A dedicated account, never the operator's own: everything the agent writes appears under this name.] It may not exist yet; creating it is an operator step. 3. **agent 账号。** agent 以哪个 GitHub 用户身份行动？[专用账号，绝不用操作者自己的：agent 写出的所有东西都挂在这个名下。] 账号可以还不存在；建它属于操作者的步骤。
4. With Feishu: **which chats,** by name? The agent looks up their ids after the bot is configured. 4. 用飞书时：**哪些聊天**，按名字说。agent 在 bot 配置好之后查它们的 id。
**Policy: who may ask for work.** **策略：谁可以派活。**
5. **On GitHub.** Which GitHub logins may ask the agent for work? [Only `<operator login>`: the agent acts only for people on this list, and a short list keeps the team's noise low while the operator learns how the agent behaves.] 5. **GitHub 上。** 哪些 GitHub 登录名可以要求 agent 干活？[只 `<操作者>`：agent 的工作对操作者负责。]
6. With Feishu: **who may ask in Feishu?** [Everyone in the first chat, kept in sync with its members.] 6. 用飞书时：**哪些聊天**可以派活？[默认只操作者所在的聊天，名单与成员同步。]
**Execution: what the agent does with a Ticket.** **执行：agent 拿到工单做什么。**
7. **Checkout.** Which local clone of the repository should each Ticket check out from? [A new clone under `~/src/<name>`.] 7. **检出。** 每个工单从哪个本地 clone 检出仓库？[在 `~/src/<name>` 下新建 clone。]
8. **Commit identity.** Who should the agent's commits name as author? [The agent account, so its work is visibly its own.] Another identity, such as the operator's, goes into the Delivery requirements prompt section. 8. **提交署名。** agent 的 commit 作者写谁？[agent 账号，让它的工作看得出是它干的。] 另一个身份（比如操作者的）写进 Delivery requirements 提示词一节。
9. **Auto-merge.** Should the agent enable auto-merge on its own pull requests once they are ready and approved? [No: people merge until the agent's pull requests have been right for a while.] The agent never enables it as the agent account, so with yes it needs the GitHub CLI of another account that may merge: ask the operator to sign one in among the operator steps, and name it in Delivery requirements. With no, remove the auto-merge paragraph from Delivery requirements. 9. **自动合并。** agent 自己的 PR 就绪且批准后，要不要开自动合并？[不要：人的合并是对的，就保持人合并，直到 agent 的 PR 长期都对。] agent 账号自己永远不开自动合并，所以选「要」就需要另一个有合并权限账号的 GitHub CLI：让操作者在操作者步骤里登录它，并在 Delivery requirements 里点名。选「不要」就把 Delivery requirements 里的自动合并段落删掉。
Do not ask about values with a good default; list them in the plan instead: 不要问有合理默认值的项；把它们列进计划：
- profile `superagent`, a copy of DSH's Web profile kept apart from the profile the operator works in, so it restarts without closing their Sessions; port `3082`; state directory `<home>/.dsh/state/superagent` as an absolute path; - profile 名 `superagent`：一份从 DSH Web profile 复制出来、与操作者工作用的 profile 分开的副本，所以它重启时不会关掉操作者的会话；端口 `3082`；状态目录 `<home>/.dsh/state/superagent`，用绝对路径；
- an hourly check from the operator's own profile, which repairs dsh-superagent when it is not running; - 每小时一次检查，从操作者自己的 profile 发起，dsh-superagent 没在跑时把它修起来；
- branch prefix `agent/`; - 分支前缀 `agent/`；
- accept mode `observe`, which records proactive work without doing it, and the default rules and prompt sections; - 接受模式 `observe`：记录主动工作但不执行；默认规则与默认提示词各节；
- with Feishu: the bot reads only mentions, and direct messages are on. - 用飞书时：bot 只读 @ 提及，私聊开关打开。
## 3. Plan ## 3. 计划
Send one message, under 300 words: what will be installed, the accounts and CLIs, the settings to save, the operator steps, and the defaults. Ask for one confirmation. 发一条消息，不超过 300 词：将安装什么、哪些账号和 CLI、要保存哪些设置、操作者步骤是什么、默认值是什么。要一次确认。
## 4. Execute ## 4. 执行
1. **Operator steps first.** Read the Accounts section of `docs/006-deployment.md`, write the CLI wrappers yourself, then send one message with what only the operator can do: create the agent account and, with auto-merge, sign a CLI in as the account that enables it, accept the repository invitation as the agent account, run `auth login` for each wrapper, and for Feishu create and publish the bot app and run the `config init` command with its secret. Wait until the operator says it is done, then check each login with `<wrapper> api user --jq .login`. 1. **操作者步骤先行。** 读 `docs/006-deployment.md` 的 Accounts 一节，自己写好 CLI wrapper，然后发一条消息列出只有操作者能做的事：建 agent 账号；开了自动合并的话，用有权开它的账号登录一个 CLI；以 agent 账号接受仓库邀请；每个 wrapper 跑 `auth login`；用飞书的话，创建并发布 bot 应用，带着它的密钥跑 `config init`。等操作者说做完了，再用 `<wrapper> api user --jq .login` 逐个核对登录。
2. **Install and start.** Follow the Install, Machine configuration, and Start and stop sections of `docs/006-deployment.md`. Skip the `git clone` of this repository: you are in its checkout. Clone the repository of question 2 if question 7 asked for a new clone. With an existing profile, skip the `dsh superagent --from-default-profile` command, which would replace the profile and delete its `cordis.patch.yml`, and edit that file instead of replacing it. 2. **安装并启动。** 按 `docs/006-deployment.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. **Settings.** Save them through the Management API of `docs/006-deployment.md`, in this order: the `github` Source, the `feishu` Source if used, the `policy` block with the allowed lists (for Feishu, look up the chat ids with the bot's CLI first), and the `executor` block with a prepare command from the answer to question 7. Then save the prompts with the commit identity of question 8 and the auto-merge answer of question 9 in Delivery requirements. A save that returns `restarting: true` restarts dsh-superagent: wait until `scripts/dsh-superagent status` no longer exits 1 before the next request, and read the revisions again from `GET settings`. 3. **保存设置。** 按 `docs/006-deployment.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. **Failures.** A refused save names the setup problem in its response body. Find it in the Troubleshooting table of `docs/006-deployment.md`, fix it, and continue. Ask the operator only for what you cannot fix yourself. 4. **失败。** 被拒的保存会在响应体里点名 setup 问题。去 `docs/006-deployment.md` 的 Troubleshooting 表里找它，修好再继续。只有你自己修不了的才问操作者。
## 5. Verify and hand over ## 5. 验证与交接
`scripts/dsh-superagent status` exits 0 with no setup problem. If you run in the operator's own DSH profile, create the hourly check of the Hourly check section of `docs/006-deployment.md` with your schedule tool; otherwise give the operator its prompt to schedule there. Then send one message, under 300 words: `scripts/dsh-superagent status` 以 0 退出且没有 setup 问题。如果你运行在操作者自己的 DSH profile 里，用你的日程工具建 `docs/006-deployment.md` Hourly check 一节里的那个每小时检查；否则把那条 prompt 交给操作者，让他在自己的地方排期。然后发一条消息，不超过 300 词：
- The panel URL, and that the **Superagent** entry in the sidebar is where to look. - 面板 URL，以及侧边栏里 **Superagent** 条目是看哪里。
- How to try it: from an account on the allowed list, comment `@<agent login> <request>` on an issue in the repository. A Ticket appears on the overview within about a minute. - 怎么试：用允许名单里的账号，在仓库的某个 issue 下评论 `@<agent 登录名> <请求>`。大约一分钟内，overview 上会出现工单。
- Three rules for the operator, from the Responsibility section of `docs/000-philosophy.md`: start narrow, tune for less noise, own what the agent says. - 给操作者的三条规则，来自 `docs/000-philosophy.md` 的 Responsibility 一节：从小开始、往少噪音调、为 agent 说的话负责。
- Where to read more: the numbered documents in `docs/`, in order. - 想读更多：`docs/` 里编号的文档，按顺序读。
## Gitea Source 配置要点（本 fork） ## Gitea Source 配置要点（本 fork）
替代或并存于 GitHub 的自建 Gitea 来源。设计决策见 `GITEA-DESIGN.md`，逐提交说明见 `CHANGES.md`。 替代或并存于 GitHub 的自建 Gitea 来源。设计决策见 `GITEA-DESIGN.md`，逐提交说明见 `CHANGES.md`。
- **启用与 sourceId**：bundle 的 `cordis.patch.yml` 里插件 `dsh-superagent-gitea` 默认 - **启用与 sourceId**：bundle 的 `cordis.patch.yml` 里插件 `dsh-superagent-gitea` 加 `disabled: false`，Source 的 `sourceId` 用 `gitea`。
`disabled: true`，部署 profile 需启用它；设置保存在 `Settings.sources.gitea`（sourceId - **凭据**：Gitea 1.26 起 API 写路由拒绝 Basic，必须用 token；token 同时是 git push 的密码（凭据 store 同一规则），一个变量全链路。
`gitea`），字段为 `url`、`repository`（owner/name）、`tokenEnv`、`pollSeconds`、 - **轮询**：`pollSeconds` 默认 60，可选 `observeIssues` / `observePulls` / `observeComments` 三个附加流。
`failuresBeforeError` 与三个观察开关。 - **bots 名单**：Gitea 没有 `is_bot` 字段，防自激靠 `login` 名单手工维护。
- **url 直连实例**，不要套反向代理——部分反代会吞掉 `Authorization` 头，表现为一切 401。 - **git 兼容性**：MSYS bash 自带 git 2.56 与 Gitea http/2 协议不兼容（clone 卡死），用 Git for Windows 2.39。
地址不带末尾斜杠（`^https?://[^/]+$`）；Gitea 走 http 也可以，凭据行按部署 URL 自身的 - **看板**：Gitea 1.28 之前没有 Projects REST API，卡片同步用仓库内的 `scripts/gitea-kanban-sync.mjs` 直写数据库；约定随 Source 提示词注入（`DSH_SUPERAGENT_GITEA_KANBAN`）。
scheme 写（见 `e8b91ab`）。
- **tokenEnv 存的是环境变量的名字**（默认 `GITEA_TOKEN`），凭据本体绝不进 Settings。惯常做
法：写入 `~/.dsh/.credentials.yaml`，由 DSH 注入 orchestrator 进程环境。同一个 token 两用：
既做 API 认证（`token <x>`）也做 git 的 HTTPS 密码（worker 的 `gitea-git-credentials`
store）。1.26+ 的实例写路由必须 token；`login:password` Basic 仅作 token 校验损坏时的临时
兜底（见 `589b5a6`）。
- **三条可选仓库流**：`observeIssues` / `observePulls` / `observeComments`，全部默认 false；
通知流（`/notifications`）始终在轮询，这三条按团队需要再开。轮询间隔 `pollSeconds` 默认
60 s（最小 60，实例给了 `X-Poll-Interval` 更长时以实例为准）。
- **allowlist**：Policy 的 `allowed` 列 Gitea login（`^[A-Za-z0-9._-]+$`）；`bots` 名单要手工
维护——Gitea API 没有 `is_bot`，不在名单里的账号一律按 human 处理。
- **彩排**：可以用 SQLite 后端的单机 Gitea 实例试跑整套配置，不必先上生产。用 CLI 建管理员
账号时带 `--must-change-password=false`，否则首次登录强制改密会让 API 建 token 返回 403。