`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>
86 lines
2.9 KiB
Markdown
86 lines
2.9 KiB
Markdown
# Official extensions (`ext/`) — LLM
|
|
|
|
| | |
|
|
|---|---|
|
|
| Status | Accepted (v0.1.x) |
|
|
| Date | 2026-08-06 |
|
|
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
|
|
|
## Scope
|
|
|
|
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
|
|
|
|
```markdown
|
|
---
|
|
import llm:ext/ai/llm.mq.md
|
|
---
|
|
```
|
|
|
|
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
|
|
|
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](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](../roadmap/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` / `打印增量` |
|
|
|
|
```markdown
|
|
---
|
|
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):
|
|
|
|
```env
|
|
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`)
|
|
|