# 在 OpenCode 中使用 PaaS

OpenCode 是用户入口；PaaS 管理智能体、模型、资源、执行记录和服务端工作区。本套桥接适用于本仓库的 OpenCode fork，支持返回带 metadata/attachments 的自定义工具。尚未对其他发行版作兼容性承诺。

## 仓库重构操作手册

从环境准备、OCPP 测试仓库到候选选择、人工审查及交付，见配套 PaaS 分支的
[重构平台操作手册](https://gogs.seec.seecoder.cn/LiuQin/lambdagentpaas/src/paas-branch-merge/docs/refactor-operation-manual.zh.md)。
代码位于 `paas-branch-merge` 与本仓库 `bridge-zjc`，请配套更新。看板为只读展示，主操作入口是 `/refactor`。

## 安装和连接

在本仓库运行，目标可以是任意用户项目，不必从桥接源码目录启动：

```bash
bun script/install-agentpaas.ts --target /absolute/path/to/project
```

安装只复制清单中的桥接工具、辅助模块、门面和命令，不修改项目的模型配置或凭证。替换文件前自动备份；重复安装相同内容不写入。用 `--check` 检查安装是否一致。

配置 PaaS 地址及租户凭证：

```bash
export AGENTPAAS_URL=http://127.0.0.1:8010
export AGENTPAAS_API_KEY=你的租户APIKey
```

也可使用 `~/.agentpaas/config.json` 的 `server`、`api_key` 字段；环境变量优先。未指定地址时默认端口为 8000；8010 仅是本地启动示例。不要把凭证提交到 Git。OpenCode 自己的入口模型由用户现有配置选择；执行任务的模型由 PaaS 智能体配置决定，这两份配置不同。

在目标项目中用本 fork 启动 `--agent paas`，或输入 `/paas`。科研专项仍可选择 `research67`。新安装后重新启动 OpenCode，使其加载工具。

## 日常操作

| 用户要做的事 | 客户端操作 |
| --- | --- |
| 检查智能体资源 | `/paas-check` → `agentpaas_check`；默认不调用模型，可按需探测模型与知识检索 |
| 找回跨会话任务 | `/paas-tasks` → `agentpaas_tasks`，刷新本机此账号最近登记的任务，默认最多 20 个 |
| 查看有哪些智能体 | `agentpaas_agents`：返回实际目录、ID、运行位置和发现状态 |
| 处理本机 PDF/CSV 等材料 | `agentpaas_upload` 上传明确选择的文件，再将 `file_id` 交给 `agentpaas_run.input_file_ids` |
| 新建任务或修订方案 | `agentpaas_run`，长任务使用 `background=true`；每回合最多新建一次，默认复用该智能体的远端会话 |
| 查看之前的任务 | `agentpaas_task` 的 `history`、`status`；`/paas-status` 是查询快捷入口 |
| 接着某个历史任务修改 | `agentpaas_task` 的 `select` 指定 run_id，再按原任务状态恢复或提交修订；仅查看不切换上下文 |
| 断线后继续查看 | `agentpaas_task` 的 `watch`，重放原任务事件，不重新执行 |
| 暂停、恢复或停止 | `pause`、`resume`、`cancel`；恢复使用原 checkpoint |
| 审批 | 展示材料后用 `approve` 或 `reject`，仅按用户的明确决定操作 |
| 获取结果文件 | `agentpaas_download`：带鉴权下载并返回本机文件链接 |

同名智能体用目录中的 `agent_id` 精确选择。未完成远端发现时只重试目录查询，绝不自动重试任务提交或控制操作。任务目录返回空列表，不代表执行服务或模型健康；后台 PaaS 和执行服务都必须运行。

上传需用户授权所选路径。客户端先读取 `/files/capabilities`，按服务端限制与客户端 256 MiB 上限中的较小值检查。默认服务端同为 256 MiB，可通过 `AGENTPAAS_FILE_MAX_SIZE_BYTES` 调低；过大的文件在上传前即被拒绝。下载默认放在当前项目 `.agentpaas-artifacts/`，校验可用的大小/摘要并拒绝覆盖文件；重复查看已下载文件时复用已有链接。将该目录加入项目的忽略规则，避免提交研究数据。`work_dir` 始终是服务端可见目录，不能拿客户端路径代替上传。

## 运行状态与断线

`completed` 表示执行结束；`partial` 是部分完成；`needs_clarification` 表示需要补充信息；`paused` 和等待审批均不等于失败。科研状态另行保留，模拟已执行也不代表现实结论已验证。

`status` 独立读取运行快照；`watch` 的事件接口故障不会丢掉已取得的结果和产物，会返回明确提示。每次普通工具确认也有独立 `approval_id`，迟到、重复或缺少编号的决定被拒绝。两端与执行服务需配套更新；旧服务没有确认编号时，客户端不会批准未绑定的操作。

提交采用持久化幂等键；网络响应不明确时保留任务 ID/幂等键，先查原任务，不换键重跑。传输断开不自动取消后台任务；前台等待模式（`background` 省略或 false）在提交工具中按停止会请求取消原任务；后台模式按停止仅结束当前客户端等待，服务端仍可能已受理，要停止必须查询原任务再用 `cancel`。关闭进度观察 `watch` 不取消执行，真正停止要用 `cancel`。

`watch` 每次观察默认最多 30 秒，可设为 0–120 秒；到期返回当前状态，再次调用仍查询同一任务。客户端重启后用 `/paas-tasks` 查询当前服务与账号在本机登记的任务，再用 select 选择 run_id。索引不等于全平台任务列表；更早、其他机器或更换 API Key 前的任务需用 history 查询。任务索引写入失败会明确返回编号，请保留该编号。`AGENTPAAS_BRIDGE_STATE_DIR` 可指定独立客户端状态目录；默认状态目录不存任务正文或 API Key。

## 执行前检查与通用状态卡片

每次提交先检查能力。目录提供版本号时，同一服务、账号、智能体版本的非阻断预检查可缓存 5 秒；版本变化、未知版本或显式 `/paas-check` 会重新调用 PaaS `/agents/{id}/verify`。缓存不包含模型/知识探测，资源仍可能在短窗口内变化。必需资源已确认失败时不提交；可选依赖失败会提示；模型/知识未验证会明确列出，不误报失败，也不声称全链路已验证。自动检查不调用模型、不发送知识查询；`agentpaas_check(check_model=true, knowledge_query="用户查询")` 才做对应探测。探测不能保证后续运行不受服务变化影响。旧 PaaS 缺少检查接口时应配套升级，不能静默绕过。

后台模式收到服务端已受理的 run_id 后保存索引并断开 SSE，再查询一次真实状态。OpenCode 工具完成不代表任务完成。此 fork 的 TUI 为 run/task 显示实际运行状态、阶段、待处理动作、产物 ID、科研版本及已报告用量；费用缺失显示“未报告”。卡片可点击展开全文和审批材料。安装脚本只复制桥接文件，使用卡片需运行包含本次 TUI 更新的 fork。

四类固定输入验收用例与脚本位于 OpenCode 源仓库 `evals/agentpaas-acceptance/` 和 `script/accept-agentpaas.ts`。默认只预览，一次用 `--run` 启动一个真实模型任务，`--resume` 只恢复观察；不自动批准或重跑。自动文件/数值检查、人工质量检查、耗时与用量分开记录，不把任务完成率当科学质量总分。

## 维护与验证

OpenCode 仓库是桥接源码来源，PaaS 中的副本通过其 `scripts/sync_opencode_bridge.py --source /path/to/opencode-bridge` 同步；加 `--check` 检测不同步。修改时须同时带上 lib、tool、agent、plugin 和命令，不能只拷贝一个工具文件。

```bash
# 在 OpenCode packages/opencode 目录中
bun test test/tool/agentpaas-run.test.ts test/tool/agentpaas-protocol.test.ts test/tool/agentpaas-admission.test.ts test/tool/agentpaas-client.test.ts test/tool/agentpaas-background.test.ts test/tool/agentpaas-acceptance.test.ts
bun typecheck

# 在 PaaS 仓库中，使用已安装依赖的 Python
python scripts/smoke_opencode_client.py --bridge-root /path/to/opencode-bridge --output /path/to/empty-output
python scripts/smoke_research_integration.py --backend remote --bridge-tool /path/to/opencode-bridge/.opencode/tool/agentpaas_run.ts --output /path/to/another-empty-output
```

这些 smoke 使用临时 PaaS/执行服务和确定性执行器，不调用真实模型；远程目录是模拟环境，不代替真实 Kubernetes/LocoStack 部署验收。

## 文件删除与回收（PaaS 维护）

`DELETE /files/{file_id}` 只有在存储对象已清理后才返回成功，重复删除已清理文件仍成功。删除失败返回 `FILE_DELETE_PENDING`，普通下载接口停止提供该文件，可重试相同 DELETE。之前签发的对象存储直链仍受其原有效期约束。

旧版只删元数据的文件及删除失败记录，可在 PaaS 服务环境中运行 `python scripts/reclaim_deleted_files.py` 检查；确认目标数据库与存储配置后加 `--apply` 清理，`--limit` 控制每批数量。已清理记录标记为 `purged`，不会反复扫描；脚本不会选择仍在使用的文件。


## 断线恢复、提醒与费用边界

提交前保存原请求键。受理阶段等待最多 30 秒；收到 started 后不以此限制整个任务时长。未收到 run_id 就断线时，客户端会按原请求键查询，不重新提交。重启后 `/paas-tasks` 也会检查未确认的提交；可用 `agentpaas_task(action="recover", agent_id="…", idempotency_key="…")` 明确查询。服务端按租户、用户与智能体隔离查询，必要时修复运行索引。查不到只表示“未观察到”，不能据此断言没运行；找回后需继续修订可用 select 选择原任务。

取消只发送一次控制请求，并在最多 6 秒的观察窗口内核对服务端状态。`confirmed` 才表示已确认取消；`requested`/`unconfirmed` 表示任务仍可能运行；`already_terminal` 表示已经结束。后续 status 会重新核对。本机记录写入失败不妨碍发送取消请求。watch 保存事件游标，省略 after 从已保存位置继续；显式 after=0 重放。无新事件时逐步放慢轮询，最长间隔 5 秒。

安装清单包含 `plugin/agentpaas-notify.ts`。OpenCode 运行时每 20 秒检查当前账号在本机最近登记的最多 50 个任务，每批最多 5 个并发只读请求；待审批、距截止不足 60 秒、到期时分别提示一次。同一审批不重复提示，新审批重新提示。关闭 OpenCode 后不发送提醒；不是系统通知服务。提醒只提示，不自动批准，终态任务停止轮询。

用量和费用分别显示完整性；未知或不完整的 0 不表示免费。`max_cost_usd` 仅在执行服务明确声明支持的 CEK simple/react 单智能体上可用；pipeline、科研专用工作流、子智能体和 native 不支持，不能携带其他运行参数覆盖一起使用。预算与更严格的服务端上限取较小值，并在暂停恢复后保留。它依据服务端估算、在调用结算后检查，可能超出一次调用费用，**不是供应商账单硬上限**。其他执行器传入此参数会拒绝，不能声称已限额。