opencode/.opencode

在 OpenCode 中使用 PaaS

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

安装和连接

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

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

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

配置 PaaS 地址及租户凭证：

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 和命令，不能只拷贝一个工具文件。

# 在 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 不支持，不能携带其他运行参数覆盖一起使用。预算与更严格的服务端上限取较小值，并在暂停恢复后保留。它依据服务端估算、在调用结算后检查，可能超出一次调用费用，不是供应商账单硬上限。其他执行器传入此参数会拒绝，不能声称已限额。