- 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。
28 KiB
Executable File
type, status, formal, adr
| type | status | formal | adr |
|---|---|---|---|
| discussion | superseded-by-design | doc/design/ext-web-artifact.md | doc/adr/0007-web-document-endpoint.md |
正式规范已落地:讨论收敛见 ext-web-artifact.md 与 ADR 0007。下文保留为设计推演,勿按未收敛的备选目录(§三
ext/db)实现。
我看完这份 ext/web/web.mq.md 后,结论比较明确:
它已经是一个功能非常丰富的 Web Runtime,但从 Marqdo 的“代码即文档”哲学来看,目前最大的风险不是功能不够,而是“功能不断堆叠后,语言抽象开始被实现细节反向塑形”。
尤其是你之前刚刚确定的 llm.mq.md 重构方向,我认为这份 web.mq.md 也应该做同等级别的重新抽象。
目前它已经不只是一个“网络扩展库”,而实际上混合了:
Web UI
HTTP Server
Routing
HTTP API
WebSocket
Database
Transaction
Form
Authentication
OIDC
RBAC
Tenant
Cache
Object Storage
Upload
Static Assets
RSS
Sitemap
Proxy
MCP-ish invoke
例如 # db 已经拥有完整 CRUD、事务、迁移、FTS;# app 又包含 route、static、middleware、proxy、invoke、WebSocket、auth 等。
这说明它功能成熟度很高,但架构边界已经开始变模糊。
下面我分层讲。
一、先给它一个总体诊断
我会把现在的架构画成:
ext/web/web.mq.md
│
┌────────────┬───────┼────────┬──────────┐
↓ ↓ ↓ ↓ ↓
Page App DB Form Auth
│ │ │ │ │
CSS/HTML Route SQL Validate OIDC
Image Proxy Txn Submit RBAC
Head WS FTS
Client Cache
Storage
问题不是它不能用。
问题是:
web已经变成了一个“小型 Web Framework”,而不是一个清晰的 Marqdo 网络抽象。
这两个东西在语言设计上是完全不同的。
二、我认为最严重的问题:web 的职责边界已经失控
现在:
# page
# style
# db
# txn
# form
# app
# rbac
# auth
# cache
# storage
# media
# ws
都在一个模块里。
尤其是:
db
txn
form
auth
rbac
cache
storage
它们本质上都可以独立存在。
例如 DB 有自己的:
init
insert
select
paginate
get
update
delete
exec
query
count
migrate
fts
search
transaction
这已经完全是一套数据库扩展,而不是 Web 的一个小功能。
三、我的第一条重大建议:把 ext/web 拆成“协议层 + 应用层”
不要:
ext/web/web.mq.md
承载整个世界。
建议最终:
ext/
├── net/
│ ├── http.mq.md
│ ├── ws.mq.md
│ └── url.mq.md
│
├── web/
│ ├── request.mq.md
│ ├── response.mq.md
│ ├── route.mq.md
│ ├── page.mq.md
│ └── html.mq.md
│
├── db/
│ ├── db.mq.md
│ └── txn.mq.md
│
├── auth/
│ ├── auth.mq.md
│ ├── oidc.mq.md
│ └── rbac.mq.md
│
├── storage/
│ └── storage.mq.md
│
└── cache/
└── cache.mq.md
然后:
ext/web/web.mq.md
只做一个 facade:
web
├── request
├── response
├── route
└── page
四、但是这里还有一个更深的问题
即使拆文件,你现在的设计思维仍然是:
Object
↓
Method
↓
Native Plugin
例如:
page
↓
compose_main
↓
web_compose_main
db
↓
select
↓
web_db_select
app
↓
route
↓
web_app_route
这种设计实际上非常接近:
Python class wrapper / SDK wrapper。
这就是我认为当前网络库最值得改变的地方。
五、Marqdo 不应该只是“把 Web Framework API 翻译成 Marqdo”
应该变成:
Web 本身就是 Marqdo Document 的一种结构。
这才是你真正的优势。
现在:
**page = > web.page**
**page.route path="/about"**
**page.compose_main main=`main`**
还是典型 imperative API。
我更希望:
---
type: web
route: /about
---
# About Marqdo
Marqdo is an executable document language.
## Features
- Executable documents
- Executable knowledge
- AI-native programming
这本身就已经是一个 Web Page。
然后:
.mq.md
↓
Artifact
↓
Web Page
↓
HTTP Route
这才是:
代码即文档
真正开始发挥作用的地方。
六、你现在其实已经有这个方向,只是没有彻底贯彻
比如 compose_intro:
|属性|值|样式|
以及:
kicker
title
lede
claim
step
mount
html
这些已经明显是在尝试:
用 Markdown Table 描述页面结构。
这个方向我认为是对的。
但是现在的问题是:
Table 只是输入参数,而不是 Web 的真正声明式 AST。
七、这是整个网络库最大的“代码即文档”问题之一
例如:
compose_main(main)
要求:
|属性|值|样式|
或者:
|front|back|css|
而:
compose_intro
又有:
|属性|值|样式|
或者:
|front|back|style|
再加:
kicker
title
lede
claim
step
mount
html
然后样式还会解析:
shell.*
这实际上形成了一个隐藏 DSL。
问题是这个 DSL 并没有成为 Marqdo 的正式语言结构。
于是作者必须记:
compose_main 的 table 是什么形状?
compose_intro 有哪些 slot?
style 怎么解析?
claim 怎么分组?
mount 怎么工作?
这就是:
代码表面很短,语义实际上很复杂。
这是代码即文档最应该避免的情况。
八、我的建议:Table 应该成为“数据”,而不是“半隐藏 DSL”
你之前说:
network extension library 使用 table 作为 syntax。
这个方向我其实仍然支持。
但应该有一个原则:
Table 表达“数据结构”;不要让每个函数自己创造一套 Table 语法。
比如:
| slot | text | style |
|------|------|-------|
| kicker | AI Native | eyebrow |
| title | Marqdo | title |
| lede | Executable Documents | lede |
这很好。
因为 schema 是稳定的。
但:
|front|back|css|
再:
|属性|值|样式|
再:
|src|style|
再:
|组件|样式|
就开始碎片化。
九、我建议建立统一的 View / Node 数据模型
例如:
Web Node
统一:
|type|slot|value|attrs|style|
例如:
| type | slot | value | attrs | style |
|-------|--------|------------------------|-------|---------|
| text | kicker | AI Native | | eyebrow |
| title | title | Marqdo | | title |
| text | lede | Executable Documents | | lede |
| link | action | Read More | /docs | button |
然后:
page.render nodes
而不是:
compose_main
compose_intro
compose_list
compose_nav_brand
...
这会大幅降低 API 数量。
十、第二个非常严重的问题:page 已经开始承担太多状态
现在:
page
├── title
├── intro
├── shell_css
├── layout
├── asset_version
├── components
├── main
├── query
├── order
├── link_prefix
├── css
├── detail
├── chrome
├── meta
├── head
├── images
├── paginate
├── form
├── client
...
这实际上是一个:
God Object
page 已经同时知道:
Content
Presentation
Data
Routing
SEO
Assets
Forms
Client Runtime
Database Query
Authentication
这是未来维护最大的风险之一。
十一、建议把 Page 变成纯 Artifact
理想:
Page
├── document
├── metadata
├── view
├── data
└── route
而不是:
Page
├── 20+ mutation methods
例如:
---
type: page
route: /posts/{slug}
data:
source: posts
where:
slug: "{slug}"
view:
layout: article
title: "{title}"
---
正文就是:
# {{title}}
{{body}}
这比:
page.query
page.order
page.detail
page.compose_main
page.compose_intro
page.link_prefix
更符合 Marqdo。
十二、第三个问题:Route 设计太弱
现在 route:
app.route
path
page
但真正 Web Route 应该是:
Route
├── path
├── method
├── handler
├── middleware
├── auth
├── input
├── output
└── errors
而现在这些能力被拆到了:
route
invoke
gate
auth
json
proxy
route_ws
mount_form
于是一个完整 endpoint 需要去多个地方寻找语义。
十三、我建议统一成 Endpoint
这是我认为整个网络库最值得重构的 API。
例如:
## get_post
---
route: /post/{slug}
method: GET
---
**post = > db.posts.get slug={slug}**
*post*
或者:
## create_post
---
route: /api/posts
method: POST
body: json
return: json
auth: member
---
**post = > db.posts.insert body**
*post*
于是:
Endpoint
本身就是:
Documentation
+
Route
+
Handler
+
Input schema
+
Output schema
+
Authorization
这才是真正的:
代码即文档。
十四、现在的 invoke 其实已经暴露出正确方向
你现在:
## invoke
path
fn
method
body
return
并且:
fn must be lib.member
这其实已经很接近我说的 Endpoint。
问题是:
它被设计成
app.configure(invoke=table)的一项功能,而不是 Web 的一等公民。
应该反过来。
十五、第四个问题:configure() 太重
现在:
app.configure(
cors
security
compress
body_limit
json
access_log
cache_control
proxy
invoke
)
这在工程上很方便。
但在语言设计上非常危险。
因为它成为:
“所有没有地方放的 Web 功能都放进去的垃圾抽屉。”
今天:
cors
security
compress
明天可能:
rate_limit
csrf
metrics
tracing
gzip
brotli
timeout
upload
webhook
grpc
...
最终:
configure(...)
会变成一个 30 参数函数。
十六、建议:Middleware 应该成为一等对象
应该:
app
↓
middleware
↓
route
例如:
## security
| header | value |
|--------|-------|
| X-Content-Type-Options | nosniff |
| Referrer-Policy | strict-origin |
然后:
app.use security
或者:
route.use auth
route.use cors
这样:
Middleware
本身是可组合 Artifact。
十七、第五个问题:大量“隐式路由”破坏代码即文档
例如 listen 自动提供:
/
_/part/{id}
{path}/_part/{id}
_/form/{id}
static
admin
upload
download
WebSocket
RSS
sitemap
robots
redirect
proxy
invoke
404
这对框架用户很方便。
但对 Marqdo 来说有一个问题:
打开一个
.mq.md,你无法完全从源码看出它暴露了哪些 HTTP surface。
这和:
Code is Documentation
直接冲突。
十八、我的建议:区分 implicit 和 declared
例如:
---
type: web
routes:
- /
- /post/{slug}
---
Runtime 可以自动生成:
/_part
/_form
但这些应该属于:
system routes
而用户 route:
declared routes
两者在 introspection 中明确区分:
web.inspect()
返回:
declared:
GET /
GET /post/{slug}
system:
GET /_part/*
GET /_form/*
这样既保留便利,又保持可解释性。
十九、第六个问题:db 和 Web 的绑定太紧
现在:
page.query
page.order
page.paginate
compose_list
form.submit
json route
都直接知道 DB。
这让:
Web
↔ DB
高度耦合。
但 Marqdo 应该允许:
Web
↓
Data Source
├── DB
├── File
├── API
├── Knowledge Base
└── Agent
例如:
page.data = posts
至于:
posts
到底来自:
db
还是:
knowledge
不应该由 page 决定。
二十、这和你的 AI-native 方向尤其重要
未来很可能出现:
Page
↓
Data
↓
Agent
↓
Knowledge
例如:
---
type: page
data: agent.search
---
所以应该抽象:
Data Provider
而不是:
page.query= SQL database query。
二十一、第七个问题:DB 的 exec/query 破坏了高级抽象
你有:
db.select
db.insert
db.update
...
同时又:
db.exec sql
db.query sql
从工程角度这很好,因为 escape hatch 很重要。
但在“代码即文档”的语言设计里:
db.query sql="SELECT ..."
又退回:
“请让我写数据库实现细节。”
我建议保留,但明确为:
db.raw.query
db.raw.exec
这样 API 语义就很清楚:
db.query
= declarative data query
db.raw.query
= escape hatch
这非常重要。
二十二、第八个问题:事务设计不像一个语言原语
现在:
db.事务
↓
txn
↓
insert
select
update
...
↓
提交
回滚
它是典型数据库 SDK。
但 Marqdo 可以做得漂亮很多:
**transaction**
**db.insert ...**
**db.update ...**
或者:
**txn = > db.transaction**
**txn.insert ...**
**txn.update ...**
*txn.commit*
甚至最终:
**db.transaction**
...
让事务成为代码块/执行上下文,而不是用户管理一个 opaque handle。
二十三、第九个问题:WebSocket API 还是传统 API
现在:
route_ws
path
echo
mode
room_key
on_message
presence
require_auth
这其实已经相当丰富。
但:
echo
broadcast
room
drain
都是 runtime mode。
我建议统一成:
channel
例如:
## live
---
type: channel
path: /live
mode: broadcast
auth: member
---
然后:
## on_message
...
于是 WebSocket 不再是 route_ws 的特殊 API,而成为:
Realtime Endpoint
以后还可以自然扩展:
SSE
WebSocket
WebTransport
都属于:
stream endpoint
二十四、第十个问题:storage、cache 其实已经证明你需要统一 Resource 抽象
你现在:
# cache
支持:
memory:
redis://
以及:
# storage
支持:
file:
s3://
这里其实已经非常接近你之前讨论的:
Metadata + Binding
我建议以后统一:
Resource
例如:
---
type: storage
backend: s3
url: ${env.STORAGE_URL}
---
或者:
---
type: cache
backend: redis
url: ${secret.REDIS_URL}
---
这和我们刚才设计的 Binding 完美结合。
二十五、第十一个问题:中英文 API 混用会伤害语言一致性
例如:
db.paginate
但参数:
跳过
事务:
事务
提交
回滚
同时又有:
auth
session_ttl
login_redirect
我理解为什么这么设计:
Marqdo 希望自然语言友好。
这个方向没问题。
但我建议:
核心语义只有一个 canonical name
例如:
transaction
commit
rollback
offset
中文可以作为:
alias
而不是让底层 ABI 同时拥有两套概念。
即:
提交 → commit
回滚 → rollback
跳过 → offset
这样:
AST
IR
Plugin ABI
Documentation
全都只有一个 canonical vocabulary。
二十六、第十二个问题:ensure_plugin 重复暴露了 Runtime 边界
文件里大量:
> ensure_plugin
然后:
plugin.native_path
plugin.load
例如 DB、Form、App 等都依赖这个模式。
这说明:
Native plugin lifecycle 正在侵入 extension language。
用户其实不应该关心:
ABI v2
native_path
plugin.load
这应该由:
import ext:web
自动处理。
二十七、建议:Import 就意味着 Capability
例如:
import web:ext/web/web.mq.md
Runtime 自动:
resolve
↓
load
↓
initialize
↓
bind
如果缺插件:
CapabilityError
web backend unavailable
install: ...
而不是 extension 自己每个对象调用:
ensure_plugin
这样才符合:
import 是声明依赖,不是调用初始化函数。
二十八、第十三个问题:Raw HTML/CSS 是一个必要的逃生舱,但现在太容易成为第二套语言
例如:
page.css
直接接收 raw CSS。
以及:
chrome(nav_html, footer_html)
直接允许 raw HTML。
这当然需要。
但是我建议严格分层:
Declarative HTML
↓
Marqdo DOM
↓
raw HTML escape hatch
而不是:
Marqdo tables
+
raw HTML
+
CSS
三种并列模式。
二十九、建议正式建立 DOM Artifact
比如:
node
├── element
├── attrs
├── children
└── text
那么:
# Hello
天然可以变成:
Document
↓
DOM
然后:
web.render
负责:
DOM → HTML
这样未来:
SSR
Browser WASM
Email
PDF
Accessibility tree
都可以复用。
三十、你的 client_embed 也值得重新设计
现在:
client_embed
bridge
wasm
source
boot
并且生成:
<script type="module" ...>
这实际上已经不是简单 Web Server,而是在做:
Marqdo Browser Runtime
我建议不要把它藏在 web 的一个 helper 里。
应该明确:
ext/browser
或者:
runtime/browser
形成:
Marqdo
├── Server Runtime
└── Browser Runtime
这会比现在清晰得多。
三十一、一个非常关键的问题:API 返回值没有统一的 Result 模型
例如:
db.select
返回 rows。
count
直接返回 number。
auth.login
返回:
{ok, session_id, username, role}
storage.put
又是另一种。
websocket
又是另一种。
这种设计在普通 SDK 里没问题。
但 Marqdo 要成为:
AI-native programming language
就需要让 Agent 能理解:
what did this operation produce?
三十二、建议建立统一的 Result
不是说所有东西都必须包成:
{ok, value, error}
而是建立标准 Result protocol:
Result
├── value
├── error
├── metadata
└── status
例如:
db.select
→ rows
HTTP
→ response
LLM
→ result
Storage
→ object
它们都可以有统一的:
result.status
result.value
result.error
这样 Agent、日志、trace、writeback 可以统一处理。
三十三、我认为你这份库最大的“隐性问题”是:它在不断制造“特殊情况”
从代码可以看到很多:
如果 detail
如果 target
如果 mount
如果 shell_css
如果 layout
如果 media
如果 when
如果 auth
如果 guest
如果 hide
如果 form
如果 client
如果 route param
如果 dynamic route
如果 db
如果 admin
...
例如 compose_components 本身就包含:
media
when
auth
guest
hide
这说明 API 的核心抽象还不够强。
当抽象不够强时,框架就会:
每增加一个需求 → 增加一个 flag。
这就是未来最大的技术债。
三十四、所以我建议从“Feature API”转成“Composable Artifact”
这是我认为最关键的重构方向。
现在:
page.compose_intro()
page.compose_main()
page.compose_list()
page.compose_form()
page.compose_nav_brand()
page.compose_client()
应该逐渐变成:
page
├── head
├── body
│ ├── node
│ ├── list
│ ├── form
│ └── component
└── client
即:
结构组合,而不是功能函数堆积。
三十五、我会重新设计整个 ext/web
最终结构建议:
ext/web/
│
├── web.mq.md
│
├── page.mq.md
├── route.mq.md
├── component.mq.md
├── dom.mq.md
│
└── client.mq.md
然后依赖:
ext/net/
├── http.mq.md
├── websocket.mq.md
└── url.mq.md
ext/data/
├── db.mq.md
├── cache.mq.md
└── storage.mq.md
ext/security/
├── auth.mq.md
├── oidc.mq.md
└── rbac.mq.md
三十六、最核心的 web API 可以缩到非常少
我甚至认为:
web.page
web.route
web.serve
web.render
已经可以覆盖绝大部分。
三十七、理想的 Marqdo Web 应用
我希望用户最终能写成:
---
type: web
title: Marqdo Blog
route: /
data:
source: posts
order: -created_at
---
# Marqdo
Welcome to the executable web.
## Posts
| title | href | date |
|-------|------|------|
| ... | ... | ... |
然后:
marqdo run site.mq.md
直接得到:
Document
↓
Data
↓
Page
↓
Route
↓
HTTP Server
用户不需要理解:
web_page_new
web_compose_main
web_page_query
web_page_order
web_app_route
web_app_listen
三十八、Dynamic Route 也可以自然成为文档
例如:
---
type: web
route: /post/{slug}
method: GET
data:
source: posts
where:
slug: "{slug}"
---
# {title}
{body}
这已经同时表达:
Route
Query
View
Content
而现在这些能力分散在:
route
page.query
page.detail
compose_main
中。
三十九、API Endpoint 更应该成为 .mq.md 本身
例如:
---
type: endpoint
method: POST
path: /api/posts
request: json
response: json
auth: member
---
**post = > db.posts.insert row=`body`**
*post*
这就是我认为真正属于 Marqdo 的 Web API。
它同时是:
Documentation
+
Implementation
+
Schema
+
Route
+
Authorization
而这恰恰就是你一直强调的:
代码即文档。
四十、最后给你一个我认为比较卓越的整体架构
我会把现在的:
ext/web/web.mq.md
重构成:
MARQDO
│
Executable Document
│
┌──────────────┼──────────────┐
│ │ │
Document Endpoint Resource
│ │ │
↓ ↓ ↓
DOM HTTP Route DB/Cache
│ │ Storage/LLM
│ │ │
└──────────────┼──────────────┘
↓
Web Runtime
│
┌─────────────┼─────────────┐
↓ ↓ ↓
SSR HTTP Browser
│ │ │
└─────────────┼─────────────┘
↓
Native Backend
而核心原则只有几个:
① Document 是第一等公民
不是:
page object
而是:
.mq.md → Page
② Endpoint 是第一等公民
不是:
app.route + app.invoke + app.gate
而是:
endpoint.mq.md
③ Resource 是第一等公民
统一:
db
cache
storage
llm
通过 metadata + binding 描述。
④ Table 是 Data,不是隐藏 DSL
表格描述结构化数据。
不要每个函数再发明一套 table 方言。
⑤ Raw HTML/CSS 是 Escape Hatch
不是第二套主要语言。
⑥ Runtime 自动处理 Native Plugin
作者只写:
import web
不写:
ensure_plugin
native_path
plugin.load
⑦ Route / Middleware / Auth 都是可组合 Artifact
而不是 configure() 的参数集合。
四十一、我对现有版本的评价
如果从工程产品成熟度来看,这个网络库已经很强:功能覆盖非常广,而且很多地方明显经过实际使用迭代,比如分页、表单 mount、SSE proxy、OIDC、RBAC、tenant、storage 等。
但如果从你现在真正想打造的 Marqdo 语言设计 来看,我认为它已经到了一个非常关键的节点:
继续往里面加功能,会越来越像 Flask/FastAPI/Next.js 一类框架;现在停下来做一次“语言级抽象重构”,才有机会让它真正成为 Marqdo 的 Web Model。
尤其是这几个我认为必须优先解决:
| 优先级 | 问题 | 建议 |
|---|---|---|
| P0 | web 职责过度膨胀 |
拆 net/web/data/security |
| P0 | Endpoint 被拆成多个 API | 引入 Endpoint Artifact |
| P0 | Page 是 God Object | Page → Document + View + Data |
| P0 | Table DSL 碎片化 | 建立统一 Schema/Data Table |
| P0 | 隐式 route 太多 | declared/system route 分离 |
| P1 | configure() 变垃圾抽屉 |
Middleware 一等公民 |
| P1 | DB 与 Web 强耦合 | Data Provider 抽象 |
| P1 | raw HTML/CSS 与 DSL 并存 | DOM Artifact + escape hatch |
| P1 | Native plugin 生命周期泄漏 | import 自动加载 |
| P1 | Result 不统一 | Result protocol |
| P2 | 中英文 API 混杂 | canonical English + alias |
| P2 | WebSocket 特殊化 | Realtime/Channel 抽象 |
| P2 | Browser WASM 混在 web | 独立 Browser Runtime |
最后一个我特别想强调的判断
你之前提出:
“表格作为 network extension 的 syntax。”
我现在看完这份完整实现以后,我认为这个想法本身没有问题,甚至很可能是 Marqdo 很漂亮的设计之一;真正的问题是现在“表格是数据”与“表格是隐藏 DSL”之间没有划清边界。
我会把整个网络扩展的下一代设计目标定成:
Document describes the page. Table describes the data. Endpoint describes the interaction. Metadata describes the runtime. Marqdo executes all of them.
这样你前面刚刚确定的:
${env.OPENAI_API_KEY}
${config.llm.model}
${secret.REDIS_URL}
也可以统一成为:
Artifact Binding
最终 Marqdo 会形成非常漂亮的一套统一模型:
.mq.md
│
┌─────────────┼─────────────┐
↓ ↓ ↓
Metadata Document Tables
│ │ │
Binding View Data
│ │ │
└─────────────┼─────────────┘
↓
Artifact
│
┌────────────┼────────────┐
↓ ↓ ↓
LLM Agent Web
│ │ │
└────────────┼─────────────┘
↓
Execution
↓
Knowledge Artifact
这才真正把你前面 llm、agent、network 三个看似独立的扩展,统一到了 Marqdo 的“代码即文档 / 文档即程序 / 执行即知识”这个核心语言模型里。