# 安装（本 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，自行清理）。