Files
marqdo/doc/design/ext-llm.md
T
cflmyandCursor ecc92f473a Unify frontmatter imports as import bind:target and drop > imports.
`import json:lib/json.mq.md` binds file libraries; `import fmt:time.format`
binds member short names (replaces `> use`). Legacy `> path.mq.md` / `> use`
now hard-error with a hint. Migrates repo docs, skills, ext, lib, public, examples,
man-test and tests; adds a negative gold and updates view/catalog rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-13 10:03:21 +08:00

2.9 KiB

Official extensions (ext/) — LLM

Status Accepted (v0.1.x)
Date 2026-08-06
Related objects.md · ext-abi.md · ext-agent.md · ext-cli.md

Scope

ext/ai/ holds official LLM + agent extensions. Import paths:

---
import llm:ext/ai/llm.mq.md
---

Resolution: MARQDO_EXT/ai/…, repo ext/ai/…, cwd ext/ai/… (see ext-cli.md).

Other official ext: ext-agent.md / ext-agent-plan.md (document-driven agent — step with default writeback / plan workbook; thin TOOL: loop superseded). Installer: ext-cli.md. Native plugins: ext-abi.md.

Streaming: complete stream=True returns an event list (reasoning / delta / done / error); echo=True prints thinking (reasoning_content) and answer tokens as they arrive. See agent-streaming.md. Default (stream=False) is unchanged (answer string).

Note: Prefer marqdo ext add llm. Import import llm:ext/ai/llm.mq.md from repo or install root.

Platform prerequisites

Capability Surface
HTTPS + headers lib/net → http_post / headers= map
Dotenv ## load_env in ext (or load_dotenv / lib/sys)
JSON quote lib/json → quote

ext/ai/llm / ext/ai/大模型 (object handles)

English Chinese Role
## load_env ## 加载环境 Free function: load .env
## stream_result ## 流式结果 Collapse event list → final text
# llm # 大模型 Object ctor → handle map
## complete / ## chat ## 运行 / ## 聊天 Methods; optional stream / 流式, echo / 打印增量
---
import llm:ext/ai/llm.mq.md
---

# main

> load_env

*`model` = > llm *
*`reply` = > `model`.complete prompt=Say hi in one word *
> print text=`reply`

*`events` = > `model`.complete prompt=Say hi stream=True *
- [`ev`](`events`)
  *`t` = > json.get value=`ev` key=type *
  1. `t` == "delta"
    *`chunk` = > json.get value=`ev` key=text *
    > print text=`chunk`
  2. *
    *`_` = 1*

Environment (create a project-local .env; do not commit secrets):

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

Fallbacks: MARQDO_LLM_API_KEY, MARQDO_LLM_BASE_URL, MARQDO_LLM_MODEL.

Tests

  • Import smoke: tests/ext/llm-import.mq.md
  • Offline stream: tests/ext/llm-stream-offline.mq.md + tests/lib/net-openai-sse.mq.md
  • Live complete (local): tests/ext/llm-complete.mq.md + tests/ext/.env
  • Live agent ## step: tests/ext/agent-run-live.mq.md (DeepSeek; gold: ext_agent_run_live)
  • Agent smoke (real llm handle): tests/ext/agent-smoke.mq.md (gold: ext_agent_framework_smoke)
  • Live complete: tests/ext/llm-complete.mq.md (gold: ext_llm_complete_live)