English | 简体中文

Open ETF Agent

The v0.9 standalone CLI Worker implementation was selected for XERJ Corpus Hub.

Read an Agent architecture article. Run its corresponding implementation. Open a report and trace it back to sources, fixed code and evidence.

A runnable learning project for Agent developers. Start with an offline report over synthetic documents, then explore the modules and evidence. No model key required; not a live fund-research, trading or investment-advice service.

Quickstart · Read all articles

Latest modules · Architecture · Scope and safety · Full documentation · Contribute

What is here, and how far does it go?

Interactive module map: open articles by card · Open full-size module matrix (zoomable) · Per-module text and source index

GitHub treats embedded SVG as one image, so its cards are not individually clickable here. Each module name below opens its corresponding article.

Current map: v0.30.0 · Modules, source & evidence · Six-layer article (Chinese original)

Article links are reading navigation, not implementation parity or coverage qualification. This maps public implementation, not completion percentages. Live-model evidence qualifies only the paths in version records, not financial accuracy, production or browser experience.

Start with a question, not a version number

Recently updated reading

Subagent Panorama · Start with a Report You Can Read Back · Spec-Driven Agent Development

Quickstart

Requires Node.js 26.8.1–26.x and npm. Default examples need no model key. Dependency installation may access npm; the installed examples run offline.

# Clone main for current development; use a release tag for a fixed version
git clone https://github.com/hpoenixf/open-etf-agent.git
cd open-etf-agent

npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run demo -- --case document-compare

build checks and copies native ESM and example data; it is not a TypeScript typecheck. The comparison keeps all four questions. Each Run creates a separate directory under runs/ with report.md, manifest.json and run.jsonl. The CLI prints the actual directory. Inspect a Run with node src/cli.mjs --observe runs/<run-id>, replacing the placeholder with that ID.

Try seven more mechanism examples →

What should you inspect? Open report.md in the directory printed by the CLI, then trace sources and execution through manifest.json and the observe command. A readable report, a completed task and a correct conclusion are different outcomes.

Ready to use a real model? Do not add --live to the demo command. Use the research project entry: first import and submit without model calls, then configure your authorized provider and budget. The report review entry also distinguishes fixture lifecycle runs from real model judgment.

Releases and development status

The latest verified formal Release is v0.30.0 · Child lifecycle, published from merge commit 8b940515. Ten independently frozen live-model workflows over synthetic evidence passed; Runtime completion is not answer-quality certification. Evidence and quality limits.

All fixed versions and commands · Version lineage · All releases · Verification records

Architecture: follow one execution path

Question → Runtime ⇄ Gateway
              │ Context: the next bounded input
              ▼
           Tool Host → read / calculate / save
              ├─ ResultStore: original sources and exact references
              └─ Artifact / Revision: report, files and receipts
                       └─ Reader: reopen the delivered bytes

The model proposes; code checks authority and executes. Session, Publication and the single-Run Worker extend this path rather than adding a second executor. Original sources, working notes and explicitly authorized Memory remain separate.

Owner responsibilities and limitations · Design evolution

Scope and safety

• Use it to learn and reproduce: local, single-user synthetic examples. Default demos use scripted Gateway fixtures, not live model judgment, real holdings or market data. No trading or investment advice.
• Read the qualification literally: completed means execution finished; model quality remains unreviewed. Offline tests and CI are not production, security, financial-semantic or live-recovery certification.
• Keep authority explicit: trusted Plugins run local JavaScript and are not sandboxed. The PDF parser is not a hostile-file security sandbox; no OCR, visual/table interpretation or active-PDF recovery is offered. Python isolation and broader Web capabilities are not implied by the examples.
• Respect original identity and effects: unknown dispatched requests are not automatically retried; host stop is not user cancellation. SQLite fencing does not provide general external exactly-once effects. Finish or isolate incompatible active Runs before upgrade.

Qualification is separate from demos: the v0.28 real-model review record over fixed synthetic material qualifies only its stated Runtime paths and retains judgment limitations. It is not financial accuracy or production certification. Earlier successes, failures and unknowns remain in the evidence index.

Choose the right execution entry: the demo CLI rejects --live; the project CLI can use an explicitly authorized provider. The separate validation runner is for fixed-input verification, not the default product entry. Other operators' keys, data and cost authorization are not inherited.

Go deeper

• Full module commands and version history
• Verification evidence index
• Article-to-code mapping

Roadmap: planned is not shipped. v0.26 ships explicit public static-page acquisition; broader Web capabilities, isolated Python and richer PDF support remain separate candidates, not bundled promises.

Author

By hpoenixf: 10 years of software development experience, including 5 years building financial business systems. A frontend-leaning full-stack developer focused on Agent engineering, connecting system design with runnable implementations and verification evidence. Personal blog · Engineering articles

License

Original code and accompanying original documentation are MIT, Copyright © 2026 Huang Pengfei. Third-party dependencies, the accompanying Evidence Kit and NOTICE retain their own licenses and attribution. This license does not cover external private source, manuscripts or other outside content. private: true prevents accidental npm publication; it does not restrict MIT rights.

Feedback and contributions

See the repository maintenance acceptance requirements.

Open an issue with the stage/commit, Node version, minimal reproduction, expected behavior and actual result. Do not include keys, private material, databases, real holdings or unsanitized logs. For improvements, explain the concrete problem and how the change can be verified.