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

1174 lines
17 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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”之间最有辨识度的区别。