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