Lift ext/ai/llm from OpenAI HTTP client to an intelligence primitive; keep complete as compat. Add unified ai-stack roadmap linking agent + llm. Co-authored-by: Cursor <cursoragent@cursor.com>
17 KiB
llm框架存在问题,请你阅读给出好的方案。
我认真看了一遍。我的判断是:
你现在的
ext/ai/llm已经是一个能工作的 LLM Client,但还不是一个真正符合 Marqdo 哲学的 LLM 抽象。
它现在最像:
Marqdo
↓
llm.mq.md
↓
OpenAI HTTP API
而我认为 Marqdo 应该做到:
Marqdo Document
↓
LLM
↓
Prompt / Context / Model / Policy
↓
Structured Result
↓
Executable Knowledge
也就是说,OpenAI-compatible HTTP 应该退到最底层,用户在 Marqdo 层根本不应该感受到它。
一、你现在这份代码最大的问题
你的代码本身没有明显的工程性错误,真正的问题是抽象泄漏。
例如现在用户最终会写:
**answer = > llm.complete prompt=`prompt` stream=`stream` echo=`echo`**
而内部又出现:
url = [base_url](self) + [suffix](self)
auth = [bearer](self) + [api_key](self)
headers = > table.put ...
messages =
| @ | role | content |
...
body = > json.stringify ...
resp = > net.http_post ...
这实际上是在把:
- HTTP
- Authorization
- OpenAI endpoint
- JSON
- messages
- stream
- SSE
全部暴露给了 Marqdo 的 AI 编程层。
这和“代码即文档”是有冲突的。
因为用户真正想表达的是:
“请让这个模型回答这个问题。”
而不是:
“请构造一个 OpenAI Chat Completion HTTP 请求。”
二、我建议把 ext/ai/llm 重新定义成一个「LLM Object」
我会把整个设计提升一个抽象层:
┌────────────────────┐
│ Marqdo Document │
└─────────┬──────────┘
│
llm.ask()
│
┌────────────┴────────────┐
│ │
Context Policy
│ │
└────────────┬────────────┘
│
LLM Runtime
│
┌────────────┼────────────┐
│ │ │
OpenAI Ollama Other
Compatible Compatible Provider
然后整个 ext/ai/llm 应该分成 四层:
Layer 1:Semantic API
用户真正使用:
llm.ask
llm.generate
llm.stream
Layer 2:Conversation / Context
处理:
system
context
user
assistant
tools
Layer 3:Model abstraction
处理:
provider
model
temperature
max_tokens
Layer 4:Transport
才处理:
HTTP
JSON
SSE
Authorization
/chat/completions
第 4 层应该尽可能不可见。
三、最重要的变化:complete 不应该成为主要 API
我甚至建议把:
complete
降级成内部 primitive。
因为:
complete是 API Client 的语言,而ask是 AI-native language 的语言。
这是一个非常重要的区别。
用户应该看到:
**answer = > llm.ask prompt=`prompt`**
而不是:
**answer = > llm.complete prompt=`prompt`**
甚至进一步,我希望 Marqdo 最终能够做到:
**answer = > llm.ask**
然后让当前文档本身成为 prompt。
这样才真正开始出现“代码即文档”的味道。
四、我特别建议引入「Prompt = Document」
这是我认为这次重构里最有价值的一步。
现在:
prompt = "You are an AI assistant..."
本质上还是传统程序语言思维。
但 Marqdo 本身就是 Markdown-native。
所以应该允许:
# Task
Analyze the following data.
## Requirements
- Identify the important patterns.
- Explain the reasons.
- Return a concise summary.
## Data
...
直接成为一个 Prompt Artifact。
也就是说:
Prompt 不再只是字符串,而是 Knowledge Artifact。
这和你之前“Executable Document → Executable Knowledge Base”的方向是完全一致的。
五、因此我建议引入 llm.prompt
例如设计成:
**prompt = > llm.prompt**
# Task
Analyze the following customer feedback.
# Requirements
- Find the major problems.
- Group similar complaints.
- Explain the likely causes.
# Output
Return a structured summary.
然后:
**answer = > llm.ask prompt=`prompt`**
*answer*
这里就非常漂亮了。
因为:
prompt.mq.md
本身就是:
Document
↓
Prompt
↓
LLM Input
以后甚至可以:
Prompt
↓
Skill
↓
Agent
↓
Knowledge
这就开始形成 Marqdo 自己独有的体系。
六、甚至可以进一步:让 Document 本身就是 Prompt
这是我更推荐的最终方向。
比如:
---
type: prompt
model: gpt-4o-mini
---
# Analyze Customer Feedback
Analyze the following customer feedback.
## Requirements
1. Identify the major problems.
2. Group similar complaints.
3. Explain possible causes.
## Input
{{feedback}}
调用:
**answer = > llm.ask prompt=`this` feedback=`data`**
*answer*
或者未来进一步做到:
**answer = > llm.ask**
让当前 executable document 自动成为上下文。
这会非常符合 Marqdo 的设计哲学。
七、第二个重大变化:不要让 llm 既是 Factory 又是 Client
你现在:
**# llm**
Construct an LLM handle
然后:
self.complete
实际上 llm 同时承担:
LLM configuration
LLM factory
LLM instance
LLM API
这四个角色。
我建议明确分开。
llm = 默认模型
例如:
**model = > llm.create**
得到:
LLM Handle
然后:
**answer = > model.ask prompt=`prompt`**
这样对象关系非常清楚:
llm
│
├── create()
│ ↓
│ model
│ │
│ ├── ask()
│ ├── stream()
│ └── raw()
│
└── providers
八、我会把配置也从代码中拿出来
你现在:
api_key = > sys.env_get ...
base_url = > sys.env_get ...
model = > sys.env_get ...
这非常工程化,但不够优雅。
应该允许 .mq.md 自己描述模型:
---
type: llm
provider: openai-compatible
model: gpt-4o-mini
base_url: ${OPENAI_BASE_URL}
api_key: ${OPENAI_API_KEY}
---
于是:
import llm:ext/ai/llm.mq.md
之后:
**answer = > llm.ask prompt=`prompt`**
就够了。
环境变量只是 fallback。
九、我甚至建议支持 Named Model
这是对你后面 Agent Framework 非常重要的一步。
例如:
---
type: llm
name: fast
provider: openai-compatible
model: qwen3-0.6b
---
以及:
---
type: llm
name: reasoning
provider: openai-compatible
model: gpt-5.6
---
然后:
**answer = > fast.ask prompt=`prompt`**
或者:
**answer = > reasoning.ask prompt=`prompt`**
这样 Agent 就可以:
Agent
│
┌────────┴────────┐
↓ ↓
fast model reasoning model
│ │
routing exploration
这正好对应我们前面讨论的:
大模型负责探索,小模型/Jev 负责决策,Marqdo 负责执行。
而且不需要把 Jev 写死在 LLM 层。
十、第三个重大变化:不要让 stream 是一个 Boolean
你现在:
stream=False
这是典型 API Client 设计。
我建议把它提升成能力:
llm.ask
llm.stream
而不是:
llm.complete stream=True
所以:
**answer = > model.ask prompt=`prompt`**
表示:
一次性得到结果
而:
**events = > model.stream prompt=`prompt`**
表示:
得到事件流
然后:
**answer = > llm.reduce events=`events`**
把 stream 转换成最终结果。
这样语义非常清晰。
十一、你现在的 stream_result 也应该重新设计
现在:
## stream_result
其实是在做:
Transport Event → Text
这属于 transport / adapter 层。
我建议:
llm.stream
↓
LLM Event Stream
↓
llm.collect
↓
LLM Result
例如:
**events = > model.stream prompt=`prompt`**
**result = > llm.collect events=`events`**
*result*
而 events 不应该只是一些 OpenAI 特有的:
delta
done
error
reasoning
应该变成 Marqdo 自己定义的统一事件:
text
reasoning
tool_call
tool_result
done
error
于是 OpenAI、Anthropic、Ollama、Gemini、国产模型都可以映射到这个协议。
十二、第四个重大变化:Result 应该是对象,而不是裸字符串
现在:
*[content](...)
直接返回文本。
这对于最简单的调用很好,但对于 Agent 不够。
建议:
LLMResult
至少包含:
result.text
result.model
result.usage
result.finish
result.tool_calls
result.raw
例如:
**result = > model.ask prompt=`prompt`**
*result.text*
或者:
**result = > model.ask prompt=`prompt`**
**tokens = [total_tokens](result.usage)**
这样 Agent Framework 就可以直接获得:
cost
latency
tokens
model
reasoning
tool calls
这对你后面的:
Experience → Learning → Compilation
极其重要。
因为没有结构化 Result,就很难做经验学习。
十三、因此你的 LLM API 最终可以非常漂亮
我建议核心 API 就保持在下面这几个:
llm.create
llm.ask
llm.stream
llm.collect
llm.embed
llm.count
其中真正核心只有:
create
ask
stream
其他都是能力扩展。
十四、一个我认为非常漂亮的使用方式
普通程序:
import llm:ext/ai/llm.mq.md
**answer = > llm.ask prompt="Explain Marqdo."**
*answer*
已经比现在好很多。
但是我真正喜欢的是:
import llm:ext/ai/llm.mq.md
**answer = > llm.ask**
# Explain Marqdo
Explain Marqdo as an AI-native programming language.
## Requirements
- Explain the motivation.
- Explain executable documents.
- Explain executable knowledge.
- Give one concrete example.
*answer*
这里已经非常接近:
Executable Document
而不是传统意义上的:
Python + SDK + Prompt String。
十五、再往前一步:让 Prompt 自己可以成为函数
这会非常强。
例如:
**## explain**
Explain the concept of **[topic]**.
Requirements:
- Be concise.
- Give an example.
- Use Markdown.
那么:
**answer = > llm.explain topic="Marqdo"**
这里 explain 本身就是一个:
Prompt + Program + Knowledge
以后甚至可以:
explain.mq.md
↓
LLM Skill
↓
compiled skill
这就直接连接到你现在正在重新设计的 Agent Framework。
十六、我会把 llm.mq.md 的内部结构改成这样
不是让它直接变成 200 行 HTTP wrapper,而是:
ext/ai/llm.mq.md
├── Configuration
│
├── Model
│ ├── create
│ ├── ask
│ └── stream
│
├── Prompt
│ ├── create
│ └── render
│
├── Result
│ ├── text
│ ├── usage
│ └── metadata
│
├── Event
│ └── normalize
│
└── Transport
└── openai-compatible
其中:
Transport
应该是整个文件里最不重要的部分。
甚至我建议进一步拆:
ext/ai/
├── llm.mq.md
├── llm/
│ ├── openai.mq.md
│ ├── anthropic.mq.md
│ ├── ollama.mq.md
│ └── compatible.mq.md
这样:
llm
是抽象。
openai-compatible
只是实现。
十七、我尤其建议不要把 OpenAI 写死在 llm
你现在实际上:
llm = OpenAI-compatible
我认为这个命名应该反过来:
llm = abstract LLM
然后:
openai-compatible = backend
例如:
---
type: llm
backend: openai-compatible
model: gpt-5.6
---
或者:
---
type: llm
backend: ollama
model: qwen3
---
Marqdo 用户根本不需要改变:
**answer = > llm.ask prompt=`prompt`**
这才是真正的 abstraction。
十八、这会直接解决你 Agent Framework 的一个核心问题
你之前的 Agent 设计里有:
Large LLM
Small LLM
Jev
Marqdo
如果现在 llm.mq.md 设计得好,那么 Agent 根本不需要知道底层是什么:
Agent
│
└── Router
│
├── llm.fast
├── llm.reasoning
├── llm.local
├── jev
└── marqdo
甚至:
Router
↓
Policy
↓
LLM object
↓
Provider
这就形成了一个非常干净的层次。
十九、最终我建议 Marqdo 的 AI 层形成这样的结构
我觉得这甚至可以成为你整个 Marqdo AI architecture 的核心图:
MARQDO
│
Executable Document
│
┌──────────────┼──────────────┐
│ │ │
Program Prompt Knowledge
│ │ │
└──────────────┼──────────────┘
│
Agent
│
┌───────┴───────┐
│ │
Policy Skill
│ │
└───────┬───────┘
│
LLM API
│
┌───────────┼───────────┐
│ │ │
Large LLM Small LLM Jev
│ │ │
└───────────┼───────────┘
│
Backend
│
┌─────────────┼─────────────┐
│ │ │
OpenAI Ollama Compatible
然后随着学习:
Experience
↓
Pattern
↓
Skill
↓
Policy
↓
Marqdo Compilation
最终:
Large LLM
↓
Small LLM
↓
Policy
↓
Marqdo
↓
Deterministic Execution
这就和你之前提出的 “执行沉淀为 .mq.md,最终变成低能耗执行” 完全接起来了。
二十、我认为最值得坚持的一个设计原则
我会把它总结成一句话:
ext/ai/llm不应该是“如何调用模型”,而应该是“如何在 Marqdo 中表达一次智能”。
所以:
HTTP
JSON
SSE
Authorization
/messages
/chat/completions
这些全部属于:
Implementation
而:
ask
stream
prompt
context
result
model
skill
policy
才属于:
Marqdo Language
我建议你的下一版 API 最终长这样
最简单
import llm:ext/ai/llm.mq.md
**answer = > llm.ask prompt="What is Marqdo?"**
*answer*
文档原生
import llm:ext/ai/llm.mq.md
**answer = > llm.ask**
# What is Marqdo?
Explain Marqdo as an AI-native programming language.
## Requirements
- Explain the motivation.
- Explain executable documents.
- Explain executable knowledge.
- Give one example.
*answer*
指定模型
**answer = > llm.fast.ask prompt=`prompt`**
强推理
**answer = > llm.reasoning.ask prompt=`prompt`**
流式
**events = > llm.fast.stream prompt=`prompt`**
**result = > llm.collect events=`events`**
*result*
Agent
**result = > agent.run task=`task`**
而 Agent 内部:
agent
↓
policy
↓
llm.fast / llm.reasoning / jev / marqdo
↓
skill
↓
verification
↓
experience
这其实比单纯重构 llm.mq.md 更重要:我建议把 llm 定义成 Marqdo 的“智能原语(Intelligence Primitive)”,而不是 OpenAI SDK 的包装器。
这样 llm.mq.md、你现在正在重构的 agent.mq.md、未来的 skill.mq.md / policy.mq.md 就能形成一个统一体系:
Document → Prompt → LLM → Agent → Skill → Policy → Executable Knowledge
而这条链,恰好是 Marqdo 和普通“给 Python 加一个 LLM SDK”之间最有辨识度的区别。