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