# OpenCode ↔ Research67 桥接说明

本目录让 OpenCode 客户端作为 Research67 的本地交互入口。OpenCode 侧只负责选择门面、调用 `agentpaas_run`，真正的科研模型、CEK、Guard、知识库、工具调用、预算和 workspace 都在 LambdaAgentPaaS / Research67 侧执行。

## 一句话架构

参赛版使用 PaaS 的 `agentexample/research67/competition.yml`，可只启动本机 API 和执行服务。
此配置执行证据检索、假设与计划检查、受限 Q124 模拟和反馈修订；下文完整编排流程仅适用于另外注册的完整科研配置。
科研门面统一使用百炼 `bailian/qwen3.8-flash`，需要向 OpenCode 进程提供 `DASHSCOPE_API_KEY`。
详细启动和验收方法见配套 PaaS 仓库的 `docs/research67-competition.md`。

`completed` 是执行状态。`research.science.status` 的 `needs_evidence`、`needs_revision`、
`needs_review` 分别表示证据不足、方案待修订、检查通过待人工审阅，不能表述成科学结论已成立。

```text
OpenCode CLI
→ .opencode/agent/research67.md
→ .opencode/tool/agentpaas_run.ts
→ AgentPaaS /api/v1/agents/{agent}/run/stream
→ Research67 统一科研闭环
```

Research67 统一工作流为：

```text
科学问题
→ 本体构建
→ 本体审计与知识补全
→ 可证伪假设生成
→ 研究计划与 Action DAG
→ 实验规划 / 授权包 / 可执行实验
→ 结果分析
→ 论文写作
→ 数据与主张核验
→ 论文评审
→ 反馈合成
→ 本体再审计与下一轮迭代
```

## 使用方式

在 `opencode-bridge` 根目录启动：

```bash
bun run --cwd packages/opencode dev -- --agent research67
```

之后直接在 OpenCode 中输入科学问题、125 Questions 题号或继续追问即可。同一 OpenCode session 会保留 AgentPaaS thread 和上一轮运行引用。配套版本的本地 PaaS 执行服务和 LocoStack 远程 Agent 均支持研究修订：在新工作区中复制上一轮选定成果，并保留父子版本关系。

## 推荐入口

- `research67`：完整 Research67 对话式入口，推荐默认使用。
- `research-67-orchestrator`：需要显式调用科研主编排器时使用。
- `research-67-pipeline`：旧三阶段 Lite 流水线。
- `research-67-ontology-auditor` / `research-67-ontology-enricher` / `research-67-hypothesis-builder`：本体飞轮相关门面。
- `research-67-plan-builder` / `research-67-action-reasoner`：研究计划和 Action DAG 推理门面。
- `research-67-exp-planner` / `research-67-exp-executor` / `research-67-result-analyzer`：实验规划、授权执行和结果分析门面。
- `research-67-paper-writer` / `research-67-data-verifier` / `research-67-paper-reviewer` / `research-67-review-feedback`：论文写作、核验、评审和反馈迭代门面。

## 配置

`agentpaas_run` 从以下位置读取 AgentPaaS 地址和租户 API Key：

```bash
export AGENTPAAS_URL=http://127.0.0.1:8000
export AGENTPAAS_API_KEY=你的_AgentPaaS_API_Key
```

或写入用户目录：

```json
{
  "server": "http://127.0.0.1:8000",
  "api_key": "你的 AgentPaaS API Key"
}
```

路径：`~/.agentpaas/config.json`

注意：这里是 AgentPaaS 租户凭证，不是 Qwen/DashScope token。Qwen/DashScope token 仍由 AgentPaaS 服务端配置管理，不应写入本目录或 Git。

## 边界

- OpenCode 不直接生成科研产物，只展示远端返回结果和实时进度。
- 每个门面单回合只调用一次 `agentpaas_run`，失败后不得自动重试或改调其他 Agent。
- 真实湿实验、人体/动物实验和硬件实验需要远端授权门禁；未授权时只能生成实验协议和 `external_authorization_package.json`，不能声称实验验证完成。

## 远程协议与研究修订

`agentpaas_run` 支持 `ag_...` 和 `locostack:<namespace>:<name>` 两种 Agent 身份。新增可选参数：

| 参数                 | 含义                                                             |
| -------------------- | ---------------------------------------------------------------- |
| `question_id`        | 1–125 的题号                                                     |
| `feedback_kind`      | `human`、`program_check`、`execution_result`、`evidence`         |
| `input_artifact_ids` | 从上一轮已登记成果中选择输入；省略时由 PaaS 选择全部             |
| `idempotency_key`    | 可选；默认从 OpenCode 消息及请求内容生成稳定键。显式重试保持原键 |

Bridge 在提交前保存原会话和父运行引用，因此重试不会因会话已推进而变成下一版研究。保存位置为 `~/.agentpaas/opencode-conversations/requests/`，可用 `AGENTPAAS_BRIDGE_STATE_DIR` 指定隔离目录。记录不含 API Key 或任务正文；写入失败会停止提交。任务中断时输出原 run ID 和提交键，先查询原状态再决定后续动作。

只运行 OpenCode 与本机 PaaS 时，需要同时启动 PaaS API 和它的 Local Agent Service 执行进程，并配置 `AGENTPAAS_LOCAL_SERVICE_URL` 及两端一致的服务 token。无需连接 LocoStack。配套 PaaS 的 `scripts/smoke_research_integration.py --backend local` 提供隔离的一键验收，详见其 `docs/opencode-local-integration.md`。

使用 `conversation: "continue"` 关联上一轮运行。服务端会检查用户、租户、Agent、session 和成果归属。单次调用出错仍不自动提交另一次研究；已有 run 可以通过 PaaS 快照和事件接口恢复读取。

远程人工确认携带 `approval_id`，走 `/agents/{agent_id}/runs/{run_id}/confirm`。本地 Agent 保留原 trace 确认路由。暂停、取消、跳过和未知状态分别显示，未报告的研究阶段不会自动标为完成。

结果 metadata 中包含 `research` 和登记成果信息。下载地址使用 PaaS API，仍需调用者鉴权，不能作为公开分享链接。`AGENTPAAS_BRIDGE_STATE_DIR` 可以覆盖默认会话状态目录，方便在隔离环境测试；不要在测试中复用真实用户状态。

这些改动需与配套 PaaS/Remote 的 `research-integration` 版本一起使用；尚未实现客户端重启后的全流程自动恢复，也未增加协议版本协商。

## 协议回归

先在仓库根目录和 `.opencode` 安装 Bun 依赖。测试从各包目录运行：

```bash
cd packages/opencode
bun test test/tool/agentpaas-run.test.ts test/tool/agentpaas-protocol.test.ts
bun typecheck
```

TUI 测试在 `packages/tui`：

```bash
bun test test/cli/tui/inline-tool-wrap-snapshot.test.tsx
bun typecheck
```

完整的本地 HTTP/Q124 验收入口在配套 PaaS 仓库的 `scripts/smoke_research_integration.py`。该测试使用真实 HTTP 和仿真执行器；Loco 发现目录为测试夹具，不代表真实 Kubernetes 已验收。