# codex-plugin

**Repository Path**: hualia2009/codex-plugin

## Basic Information

- **Project Name**: codex-plugin
- **Description**: codex-plugin
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenAgent

## 修订记录

| 版本 | 日期 | 变更内容 | 作者 |
| --- | --- | --- | --- |
| V1.0 | 2026-07-26 | 切换到唯一远程 Owner OAuth MCP，删除插件本地 Node 运行时 | huangli |
| V1.1 | 2026-07-26 | Preview 改用插件固定 Bearer Token | huangli |
| V1.2 | 2026-07-27 | 插件远程环境切换到 HK Preview | huangli |
| V1.3 | 2026-07-27 | 插件品牌和技术标识完整重命名为 OpenAgent | huangli |
| V1.4 | 2026-07-27 | 安装认证切换为 Codex 原生 Google OAuth | huangli |
| V1.5 | 2026-07-27 | OAuth 登录前显式注册全局 MCP 登录目标 | huangli |
| V1.6 | 2026-07-29 | 删除旧交互 Tool，保留 Agent 搜索、探索与会话交接 | Codex |
| V1.7 | 2026-08-19 | 将用户选择绑定为可验证的立即试用授权。 | Codex |
| V1.8 | 2026-08-20 | 增加账户 Credits 与本月消费查询 Tool。 | Codex |
| V1.9 | 2026-08-21 | 将运行期能力重构为 9 个 Skill，增加统一入口和能力判断，合并停止能力，并固定单根 Invocation 多能力协作。 | huangli |
| V1.10 | 2026-08-21 | 将 capability 调整为宿主自动判断的一级入口，将 overview 调整为插件能力总览和业务路由的二级入口。 | huangli |
| V1.11 | 2026-08-21 | 调整为 capability 与 overview 双入口，引入 openagent-core 中枢，并将 plan-agent 下沉为 capability 的 plan.md reference。 | huangli |
| V1.12 | 2026-08-21 | 对齐安装、新人引导、发现规划、Agent 调用、运行期连接和账户查询固定文案。 | huangli |
| V1.13 | 2026-08-23 | 删除旧运行期 Skill，并将用户引导限定为 onboarding 模式。 | Codex |
| V1.14 | 2026-08-23 | 将普通 Agent 执行迁移到 v2 标准内容块，同时保留选择授权的旧版兼容链路。 | Codex |
| V1.15 | 2026-08-23 | capability 改为逐子任务自主选择 Codex 或 OpenAgent，并支持同一或不同 Agent 的顺序执行。 | Codex |

这是一个验证 Codex 插件安装、Owner OAuth、MCP Apps、App Card、App Panel
和双向 WebSocket 交互的远程示例。

插件本身不再包含 MCP Server、HTTP/WebSocket Server、Widget HTML、临时隧道或
Node 运行依赖。所有服务端能力统一由 OASN 的
`tools/mcp-streamable-http-demo` 模块提供。

## 安装

推荐让 Codex Desktop 读取公共安装契约：

```text
Read https://oasn-ow.haimawan.com/install-plugin and follow the instructions to install OpenAgent
```

完整插件 ID：

```text
openagent@openagent
```

## 唯一远程 MCP

插件只声明一个 MCP Server：

- 名称：`openagent`
- MCP URL：`https://oasn-test.haimawan.com/e/preview/mcp/v1/open-agent`
- OAuth Resource：`https://oasn-test.haimawan.com/e/preview/mcp/v1/open-agent`
- Scopes：`agent.discover`、`agent.invoke`、`artifact.read`
- Tool Call 超时：20 分钟

安装后必须执行：

```bash
"<bundled-codex>" mcp add openagent \
  --url https://oasn-test.haimawan.com/e/preview/mcp/v1/open-agent

"<bundled-codex>" mcp login openagent \
  --scopes agent.discover,agent.invoke,artifact.read
```

Google OAuth 令牌由 Codex 管理。插件、Skill 和安装文档不会读取密码、Cookie、Access
Token、Refresh Token、Authorization Code 或 PKCE Verifier。

## 运行期 Skill

| Skill | 职责 |
| --- | --- |
| `openagent-capability` | 拆分任务并读取 `references/plan.md`，逐项决定由 Codex 或 OpenAgent 执行 |
| `openagent-overview` | OpenAgent 上下文入口；不要求用户显式 `@OpenAgent` |
| `openagent-core` | 能力中枢；汇总能力、代理搜索并路由业务 Skill |
| `connect-agent` | 运行期登录、重新登录和认证恢复 |
| `guide-agent` | 新人引导和首个 Agent 选择授权 |
| `search-agent` | 接收 core 请求，完成 Agent 搜索、结构化发现结果和用户选择 |
| `run-agent` | 双轨 Agent 执行、停止与标准结果交付；顺序执行当前远端子任务或可选根编排 |
| `query-account` | 查询余额、本月消耗和账户详情 |
| `handle-exception` | 统一异常决策和日志上报 |

入口路由：普通任务由宿主加载 `openagent-capability`，不需要插件时由本地完成，需要时读取 `references/plan.md` 并进入 `openagent-core`。用户主动 `@OpenAgent`，或上下文已明确使用插件时，进入 `openagent-overview`，再进入 `openagent-core`。两个入口不直接调用业务 Skill。

## 远程工具

### 模型可见工具

| 工具 | 用途 |
| --- | --- |
| `openagent_search_agents` | 按用户任务搜索 Agent，遵从服务端路由结果 |
| `openagent_user_guide` | 启动 Agent 新人引导与首个 Agent 试用（onboarding 模式） |
| `openagent_get_account_credits` | 返回当前 Credits、本月消费和官网账户详情入口 |
| `openagent_wait_agent_selection` | 在同一 Turn 等待并消费 Agent 选择结果 |
| `openagent_render_agent_progress` | 展示单 Agent 实时进度卡 |
| `openagent_upload_file` | 上传 v2 调用所需附件 |
| `openagent_run_agent` | 仅执行服务端 action 绑定的选择授权，保留旧版兼容结果 |
| `openagent_agent_run` | 执行普通首次执行、Session 续接、顺序远端子任务或可选单根计划，返回 v2 标准内容块 |
| `openagent_stop_invocation` | 停止正在执行的 Agent 调用 |

### App-only 工具

App-only 工具由远程 App Card 或 Bridge 按协议使用，模型不得调用。

## 交互流程

### Agent 搜索

1. `openagent-capability/references/plan.md` 将搜索 query 提交给 `openagent-core`；显式搜索请求也先进入 core。
2. `openagent-core` 路由 `search-agent` 调用 `openagent_search_agents`，再将结构化 `discovery_result` 原样返回请求方。
3. `selection_id` 非空且人类发现开关开启时，同一 Turn 调用 `openagent_wait_agent_selection`。
   - `selected`：用户选择即授权立即试用，不要求聊天回复；将可信选择授权返回 `openagent-core`，由中枢路由 `run-agent`。
   - `more_requested`：用 `handoff_url` 打开内置浏览器，再次 `wait_agent_selection`。
   - `cancelled` / `timed_out`：结束搜索。
4. `plan.md` 可调整 query 后再次请求 core 代理搜索；最多 5 轮，不直接调用 `search-agent`。
5. 计划稳定后仍由 `openagent-core` 逐项路由 `run-agent`；多个远端子任务可顺序使用同一或不同 Agent，也可在可信根 Agent 具备编排能力时合并为一个根 Invocation。

### Agent 引导与探索

1. 调用 `openagent_user_guide(mode=”onboarding”)`，返回 Welcome App Card。
2. 读取 `structuredContent.handoff_url` 和 `selection_id`。
3. 内置浏览器打开 `handoff_url`。
4. 立即调用 `openagent_wait_agent_selection`（同一 Turn）。
5. `selected` → 将可信执行授权返回 `openagent-core`，由中枢路由 `run-agent`；`more_requested` → 打开浏览器重新等待。

完整 Handoff URL、Boot Token 和 Cookie 不得输出到聊天或日志。

### Agent 执行

1. 新人引导或人工选择返回 `action.tool_name=openagent_run_agent` 时，只原样提交 action 中的 `selection_id` 和绑定幂等键。
2. 普通首次执行、Session 续接、充值后继续、顺序远端子任务和可选根编排使用 `openagent_agent_run`，任务放入结构化 `data`；本地附件先通过 `openagent_upload_file` 上传。
3. v2 先检查 `isError` 和 `structuredContent.view=invocation_result`，再按顺序处理 `text`、`resource_link`、`image`、`audio` 与可选 `views`。
4. v2 不依赖 `_meta`；`structuredContent.error` 按 Preview 服务版本作为可选兼容字段。
5. `content` 与 `views` 均为空时，只能报告执行终态，不得声称已经交付可用业务结果。

## Codex 中的使用示例

```text
@OpenAgent 帮我找一个能分析股票的 Agent
@OpenAgent 打开 OpenAgent 探索更多 Agents
@OpenAgent 停止当前执行的 Agent
```

不得调用 App-only 工具；它们只由远程 App Card 或 Bridge 按协议使用。

## 本地验证

插件契约测试不需要安装任何 npm 依赖：

```bash
npm run check
```

服务端 Maven 测试、HK Preview 部署和端到端协议验证位于 OASN 仓库：

```text
/Users/huangli/project/oasn/tools/mcp-streamable-http-demo
```

## 适用范围

当前 HK Preview 运行时使用固定 HTTPS/WSS 与单实例内存状态。服务重启后旧 Session、
Boot Token 和 Socket Token 会失效，客户端必须重新调用 `openagent_user_guide`。