Files
marqdo/doc/design/ext-llm.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

3.6 KiB
Executable File
Raw Blame History

Official extensions (ext/) — LLM

Status Accepted · v0.3 semantic(005:Intelligence Primitive)
Date 2026-09-24
Related objects.md · ext-agent.md · ext-cli.md · ai-stack.md · doc/next/005.md

Scope

ext/ai/llm is Marqdo’s intelligence primitive, not an OpenAI SDK wrapper.

Author surface:  ask / stream / collect / create / fast / reasoning / prompt_load
Transport:       ext/ai/llm/openai.mq.md  (+ ollama defaults)
Compat:          complete / chat

Import:

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

Public API

English Chinese Role
## load_env ## 加载环境 Load .env
## create ## 创建 Factory → LLM handle
## fast / ## reasoning ## 快速 / ## 推理 Named handles
## prompt_load / ## prompt / ## prompt_body ## 加载提示 / ## 提示 / ## 提示正文 Prompt artifacts (type: prompt → body)
## ask (module) ## 提问 Convenience → text (prompt= or path=)
## collect ## 收集 Events → text
## stream_result ## 流式结果 Alias of collect
# llm # 大模型 Handle ctor (backend= openai-compatible | ollama)
## ask (method) ## 提问 → LLMResult map
## stream ## 流式 → event list
## complete / ## chat ## 运行 / ## 聊天 Compat / transport primitive

Preferred

**answer = > llm.ask prompt="What is Marqdo?"**
*answer*

**model = > llm.create**
**result = > `model`.ask prompt=`prompt`**
*[text](result)*

**fast = > llm.fast**
**events = > `fast`.stream prompt=`prompt`**
**text = > llm.collect events=`events`**

**body = > llm.prompt path="fixtures/prompt-marqdo.md"**
**body2 = > llm.prompt text=`raw`**

LLMResult

Field Meaning
text Answer string
model Model id
finish Finish reason (stop, …)
backend e.g. openai-compatible / ollama
usage {prompt_tokens,completion_tokens,total_tokens}
tokens Alias of usage.total_tokens (agent metrics)
name Optional handle tag (fast / reasoning)
llm_calls 1 per ask
tool_calls List of OpenAI-shaped tool call objects (empty when none)

Compat

complete / chat still return a bare string (or event list when stream=True) so ext/ai/agent and older runbooks keep working. New code should use ask / stream / collect.

Environment

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
MARQDO_LLM_FAST_MODEL=...
MARQDO_LLM_REASONING_MODEL=...
OLLAMA_HOST=http://127.0.0.1:11434/v1

Fallbacks: MARQDO_LLM_API_KEY, MARQDO_LLM_BASE_URL, MARQDO_LLM_MODEL. Ctor also accepts api_key= / base_url= / model= / backend=.

Backends

backend= Module Notes
openai-compatible (default) ext/ai/llm/openai.mq.md Chat Completions HTTP + SSE
ollama defaults in ctor + same transport Key defaults to ollama; host from OLLAMA_HOST

Tests

  • tests/ext/llm-import.mq.md
  • tests/ext/llm-ctor-offline.mq.md
  • tests/ext/llm-ask-offline.mq.md (create + collect)
  • tests/ext/llm-stream-offline.mq.md
  • tests/ext/llm-named-offline.mq.md (fast/reasoning + prompt_load)
  • tests/ext/llm-tool-calls-offline.mq.md (tool_calls_from / Result field)
  • tests/ext/llm-meta-offline.mq.md · llm-entry-prompt-offline.mq.md
  • Live: llm-complete.mq.md · llm-stream-live.mq.md