npm package: @openfinclaw/findoo-deepagent-plugin
Description: Bridge to Findoo DeepAgent — 58 professional financial analysis skills via async SSE relay
Latest version: 2026.4.9

# Findoo DeepAgent Plugin

Bridge between OpenClaw Gateway (AI Fund Manager) and Findoo DeepAgent (58 professional financial analysis skills) + Rust Trading Engine (backtest + paper trading).

## Architecture

```
OpenClaw Gateway (Fund Manager Agent)
  └─ findoo-deepagent-plugin (13 tools)
       ├─ DeepAgent Client (11 async tools) ──→ Findoo DeepAgent API
       │   └─ ExpertManager + StreamRelay        (58 skills, 6 expert agents)
       │       • Async SSE relay (submit <1s, result 3-10 min)
       │       • SQLite task persistence + crash recovery
       │       • Concurrency control (max 3)
       │
       └─ Paper Engine Client (2 sync tools) ──→ Rust Trading Engine
           • Session query/stop/delete (<500ms)
```

## Tools

### DeepAgent Analysis (11 tools, async SSE relay)

| Tool                             | Purpose                                                     |
| -------------------------------- | ----------------------------------------------------------- |
| `fin_deepagent_research`         | Submit deep research task (async, 3-10 min)                 |
| `fin_deepagent_status`           | Query task status/progress                                  |
| `fin_deepagent_cancel`           | Cancel a running analysis (thread_id + run_id)              |
| `fin_deepagent_skills`           | List all 58 analysis skills                                 |
| `fin_deepagent_packages`         | List generated strategy packages (FEP format)               |
| `fin_deepagent_package_meta`     | View strategy package details                               |
| `fin_deepagent_download_package` | Download strategy ZIP                                       |
| `fin_deepagent_threads`          | Manage conversation threads (list/get/create/delete)        |
| `fin_deepagent_messages`         | View thread message history                                 |
| `fin_deepagent_backtests`        | List backtest result summaries                              |
| `fin_deepagent_backtest_result`  | View full backtest result (metrics + trades + equity curve) |

### Paper Trading (2 tools, direct Rust Engine)

| Tool                 | Purpose                                                    |
| -------------------- | ---------------------------------------------------------- |
| `fin_paper_sessions` | Query paper trading session status                         |
| `fin_paper_control`  | Control sessions: stop (with performance report) or delete |

## Configuration

| Config Key           | Env Var                            | Default                             |
| -------------------- | ---------------------------------- | ----------------------------------- |
| `deepagentApiUrl`    | `FINDOO_DEEPAGENT_URL`             | `https://api.openfinclaw.ai/agent`  |
| `deepagentApiKey`    | `FINDOO_DEEPAGENT_API_KEY`         | `""`                                |
| `paperEngineUrl`     | `OPENFINCLAW_PAPER_REMOTE_URL`     | `https://api.openfinclaw.ai/engine` |
| `paperEngineApiKey`  | `OPENFINCLAW_PAPER_REMOTE_API_KEY` | `""`                                |
| `sseTimeoutMs`       | `FINDOO_DEEPAGENT_SSE_TIMEOUT`     | `900000` (15 min)                   |
| `requestTimeoutMs`   | `FINDOO_DEEPAGENT_REQUEST_TIMEOUT` | `30000`                             |
| `maxConcurrentTasks` | `FINDOO_DEEPAGENT_MAX_CONCURRENT`  | `3`                                 |

Priority: `pluginConfig` (openclaw.json) > env var > default.

## Source Files

| File                         | LOC | Purpose                                                                      |
| ---------------------------- | --- | ---------------------------------------------------------------------------- |
| `index.ts`                   | 691 | Plugin entry: 13 tool registrations, health check, service exposure          |
| `src/deepagent-client.ts`    | 299 | HTTP+SSE client: Thread CRUD, Run stream/cancel, Skills/Packages/Backtests   |
| `src/expert-manager.ts`      | 283 | Task orchestration: submit, relay, concurrency, crash recovery               |
| `src/stream-relay.ts`        | 199 | SSE relay: event routing, silent text accumulation, stall detection, timeout |
| `src/task-store.ts`          | 150 | SQLite persistence: task CRUD, status updates, cleanup                       |
| `src/paper-engine-client.ts` | 122 | Rust engine client: session query/stop/delete                                |
| `src/config.ts`              | 69  | Config resolution with priority chain                                        |
| `src/types.ts`               | 99  | TypeScript type definitions for 7 SSE event types                            |

## Key Design Decisions

1. **Async SSE Relay** -- Solves the mismatch between 5s LLM tool timeout and 3-10 min DeepAgent execution. Submit returns in <1s, results push via SystemEvent.

2. **Dual-Channel TEXT_DELTA** -- When streaming APIs are available, TEXT_DELTA events are streamed in real-time to the Control UI via `emitAgentEvent`. When unavailable (legacy gateways), only milestone events (TOOL_START, AGENT_HANDOFF, RUN_FINISHED) generate SystemEvent pushes. Full results always available via `fin_deepagent_messages`.

3. **LLM Context Protection** -- `jsonCapped()` truncates tool responses to 2,000 chars (~15% of 16K token budget). SSE final results capped at 24,000 chars.

4. **Crash Recovery** -- SQLite persists running tasks. On gateway restart, polls Findoo for latest run status with 3s initial delay, 15s intervals, max 3 retries, 20-min lifetime cap.

5. **Graceful Shutdown** -- `process.beforeExit` hook calls `expertManager.dispose()` to clear timers, abort relays, and close SQLite connection.

## Testing

```bash
# L1 + L2 (mock tests)
pnpm test -- tests/findoo-deepagent-plugin

# E2E (real API)
FINDOO_DEEPAGENT_API_KEY=xxx npx vitest run tests/findoo-deepagent-plugin/e2e/
```

## Documentation

- [Architecture Design](../../dev/插件架构/findoo-deepagent-plugin-架构设计.md) -- Complete architecture doc (v1.1)
- [Usage & Testing Guide](test/场景使用和测试指南.md) -- 6 scenarios, 5 E2E journeys
- [E2E Test Plan](../../dev/测试计划/E2E测试方案-findoo-deepagent-plugin全能力打通验证.md) -- 23 test cases across 5 tiers
- [Test Questions](../../dev/交易系统/06-质量审计/deepagent-plugin-测试问题集.md) -- 65 verification questions
- [58 Skills Signal Chains](../../dev/交易系统/01-架构设计/基金经理54skills信号链与决策原则.md) -- 5 signal chains + 5 decision principles