77 lines
4.8 KiB
Markdown
77 lines
4.8 KiB
Markdown
# 安装（本 fork，中文速查）
|
||
|
||
把本仓库作为 DSH 插件栈装上手的完整步骤。英文版见 [docs/006-deployment.md](docs/006-deployment.md)（Install / Machine configuration / Start and stop）。
|
||
|
||
## 前置条件
|
||
|
||
- Node `^22.19.0 || >=24.0.0`（`package.json` engines）与 pnpm。
|
||
- dsh CLI：`npm install -g @deepseek-ai/dsh`，版本需满足 `package.json` 的 `engines.dsh`（`^0.2.1-alpha.2`）。
|
||
- git：Windows 上用 Git for Windows（实测 2.39 正常）；MSYS/ucrt64 自带的 git 2.56 与 Gitea 的 http/2 智能协议交互挂起（clone 卡死），不要用。
|
||
|
||
## 安装主插件
|
||
|
||
```sh
|
||
git clone <本仓库> dsh-superagent && cd dsh-superagent
|
||
pnpm install && pnpm build
|
||
dsh superagent --from-default-profile web --dump-config > /dev/null # 仅首次建 profile；profile 已存在会连旧配置一起清掉！
|
||
dsh plugin --profile superagent add "link:$PWD"
|
||
```
|
||
|
||
Windows 上把 `$PWD` 换成本目录绝对路径（如 `"link:D:/Code/AI/dsh-superagent"`）；`dsh` 即 PATH 里的 `dsh.cmd`。
|
||
|
||
## 机器配置
|
||
|
||
把 [examples/profile.cordis.patch.yml](examples/profile.cordis.patch.yml) 的内容写入 `~/.dsh/profiles/superagent/cordis.patch.yml`：
|
||
|
||
- `webserver.port`：面板端口。
|
||
- `stateDir`：必填，数据库/工单目录/命令 shim 都在这下面。Windows 支持盘符路径，YAML 用单引号包单反斜杠：`stateDir: 'C:\Users\me\.dsh\state\superagent'`。
|
||
- 用 Gitea：取消 `dsh-superagent-gitea` 段的注释（`disabled: false`）；用 GitHub 则不动。
|
||
|
||
## Gitea 侧准备
|
||
|
||
1. 给机器人建一个专用账号，加为目标仓库的协作者（write 即可；建 PR 需要）或 admin。
|
||
2. 生成**细粒度访问令牌**：scope 按最小需要，本 fork 实跑用的组合是 `write:issue` + `write:notification` + `read:user` + `write:repository`。注意：Gitea 1.25 的部分实例 token 校验有问题（读 200 写 401），那种情况下可先用「登录名:密码」Basic（本 fork 支持）；**1.26 起写路由一律拒绝密码 Basic**，必须 token。
|
||
3. 启动服务前导出令牌环境变量：变量名与 Source 设置里 `tokenEnv` 填的一致（如 `GITEA_TOKEN`）。同一个 token 也用作 git push 的密码，两处一体。
|
||
4. 启动后在面板 Sources → Gitea 填：`url`（实例直连地址；反代可能吞 Authorization 导致 401）、`repository`（owner/name）、`tokenEnv`；把不再用的 GitHub Source 置 `enabled: false`；在 policy 里把你自己加入 allowlist（填 Gitea 登录名）。
|
||
|
||
## 模型来源（必装其一）
|
||
|
||
bundle 不自带 LLM。装一个 provider 插件并配好，例如 OpenAI 兼容端点：
|
||
|
||
```sh
|
||
dsh plugin --profile superagent add dsh-llm-pi-ai
|
||
```
|
||
|
||
在 profile 的 `cordis.patch.yml` 里给 `dsh-llm-pi-ai` 配 providers（baseUrl/model/上下文长度，API key 用 `apiKeyEnv` 指到环境变量），然后在面板 Settings → 研判/执行 里选角色模型；顶栏也可以一键切部署默认模型（含思考强度）。
|
||
|
||
## 可选配套（本部署同款）
|
||
|
||
```sh
|
||
dsh plugin --profile superagent add dsh-pocket # 远程访问面板（PIN 登录，Tailscale 内网可用）
|
||
dsh plugin --profile superagent add dsh-ws-deflate # WebSocket 压缩
|
||
dsh plugin --profile superagent add dsh-session-keepwarm # 会话保温
|
||
dsh plugin --profile superagent add dsh-cost-meter # 用量成本账本
|
||
```
|
||
|
||
若走 WorkBuddy 额度搜索/模型，另装 `workbuddy-to-dsh`（桥进程）。
|
||
|
||
服务常驻（开机自启、崩溃拉起）请自行用系统机制托管 `dsh --profile superagent --no-open`；本机用的是 Windows 计划任务每分钟健康检查，属部署侧策略，不随仓库分发。
|
||
|
||
### 插件升级纪律
|
||
|
||
- 插件不自动升级：装时锁版本，之后一直用那个版本；升级=手动 `dsh plugin --profile superagent add <pkg>@<新版>`。
|
||
- **一次升一个**：升级前看 changelog，升级后跑门禁（tsc/测试/build）+ 重启 + 验 overview `problems: []`，再升下一个。
|
||
- **带本地热补丁的插件（如 `workbuddy-to-dsh` 的桥脚本本地修改）**：升级会盖掉补丁——升完必须重新打补丁，并核对两个 profile 的桥脚本哈希一致（不一致时 buildDiff 判 stale，桥进程会互杀重启）。上游合入该补丁的版本落地前，保持现版本不动。
|
||
- 重度依赖在跑的插件（上下文管理、模型 provider、桥）没有明确收益时不升级。
|
||
|
||
## 启动与验证
|
||
|
||
```sh
|
||
dsh --profile superagent --no-open
|
||
curl -H "x-orchestrator-request: 1" http://127.0.0.1:<port>/orchestrator/api/overview
|
||
```
|
||
|
||
`problems` 为空、`liveness.polling` 为 true 即就绪。到已监听仓库的 Issue 里 `@机器人 <需求>`，面板出现 Trigger → 工单 → Worker 干活 → 回写评论即全链路通。
|
||
|
||
卸载：`dsh plugin --profile superagent remove dsh-superagent`（配置与会话数据留在 stateDir，自行清理）。
|