Files
marqdo/doc/next/005.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

17 KiB
Executable File
Raw Blame History

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”之间最有辨识度的区别。