--- type: discussion status: superseded-by-design formal: doc/design/ext-web-artifact.md adr: doc/adr/0007-web-document-endpoint.md --- > **正式规范已落地**:讨论收敛见 [ext-web-artifact.md](../design/ext-web-artifact.md) 与 [ADR 0007](../adr/0007-web-document-endpoint.md)。下文保留为设计推演,**勿**按未收敛的备选目录(§三 `ext/db`)实现。 我看完这份 `ext/web/web.mq.md` 后,结论比较明确: > **它已经是一个功能非常丰富的 Web Runtime,但从 Marqdo 的“代码即文档”哲学来看,目前最大的风险不是功能不够,而是“功能不断堆叠后,语言抽象开始被实现细节反向塑形”。** 尤其是你之前刚刚确定的 `llm.mq.md` 重构方向,我认为这份 `web.mq.md` 也应该做同等级别的重新抽象。 目前它已经不只是一个“网络扩展库”,而实际上混合了: ```text 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 等。 这说明它**功能成熟度很高,但架构边界已经开始变模糊**。 下面我分层讲。 --- # 一、先给它一个总体诊断 我会把现在的架构画成: ```text 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` 的职责边界已经失控 现在: ```text # page # style # db # txn # form # app # rbac # auth # cache # storage # media # ws ``` 都在一个模块里。 尤其是: ```text db txn form auth rbac cache storage ``` 它们本质上都可以独立存在。 例如 DB 有自己的: ```text init insert select paginate get update delete exec query count migrate fts search transaction ``` 这已经完全是一套数据库扩展,而不是 Web 的一个小功能。 --- # 三、我的第一条重大建议:把 `ext/web` 拆成“协议层 + 应用层” 不要: ```text ext/web/web.mq.md ``` 承载整个世界。 建议最终: ```text 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 ``` 然后: ```text ext/web/web.mq.md ``` 只做一个 facade: ```text web ├── request ├── response ├── route └── page ``` --- # 四、但是这里还有一个更深的问题 即使拆文件,你现在的设计思维仍然是: ```text Object ↓ Method ↓ Native Plugin ``` 例如: ```text page ↓ compose_main ↓ web_compose_main ``` ```text db ↓ select ↓ web_db_select ``` ```text app ↓ route ↓ web_app_route ``` 这种设计实际上非常接近: > Python class wrapper / SDK wrapper。 这就是我认为当前网络库最值得改变的地方。 --- # 五、Marqdo 不应该只是“把 Web Framework API 翻译成 Marqdo” 应该变成: > **Web 本身就是 Marqdo Document 的一种结构。** 这才是你真正的优势。 现在: ```marqdo **page = > web.page** **page.route path="/about"** **page.compose_main main=`main`** ``` 还是典型 imperative API。 我更希望: ```markdown --- type: web route: /about --- # About Marqdo Marqdo is an executable document language. ## Features - Executable documents - Executable knowledge - AI-native programming ``` 这本身就已经是一个 Web Page。 然后: ```text .mq.md ↓ Artifact ↓ Web Page ↓ HTTP Route ``` 这才是: > **代码即文档** 真正开始发挥作用的地方。 --- # 六、你现在其实已经有这个方向,只是没有彻底贯彻 比如 `compose_intro`: ```text |属性|值|样式| ``` 以及: ```text kicker title lede claim step mount html ``` 这些已经明显是在尝试: > **用 Markdown Table 描述页面结构。** 这个方向我认为是对的。 但是现在的问题是: > **Table 只是输入参数,而不是 Web 的真正声明式 AST。** --- # 七、这是整个网络库最大的“代码即文档”问题之一 例如: ```text compose_main(main) ``` 要求: ```text |属性|值|样式| ``` 或者: ```text |front|back|css| ``` 而: ```text compose_intro ``` 又有: ```text |属性|值|样式| ``` 或者: ```text |front|back|style| ``` 再加: ```text kicker title lede claim step mount html ``` 然后样式还会解析: ```text shell.* ``` 这实际上形成了一个**隐藏 DSL**。 问题是这个 DSL 并没有成为 Marqdo 的正式语言结构。 于是作者必须记: ```text compose_main 的 table 是什么形状? compose_intro 有哪些 slot? style 怎么解析? claim 怎么分组? mount 怎么工作? ``` 这就是: > **代码表面很短,语义实际上很复杂。** 这是代码即文档最应该避免的情况。 --- # 八、我的建议:Table 应该成为“数据”,而不是“半隐藏 DSL” 你之前说: > network extension library 使用 table 作为 syntax。 这个方向我其实仍然支持。 但应该有一个原则: > **Table 表达“数据结构”;不要让每个函数自己创造一套 Table 语法。** 比如: ```markdown | slot | text | style | |------|------|-------| | kicker | AI Native | eyebrow | | title | Marqdo | title | | lede | Executable Documents | lede | ``` 这很好。 因为 schema 是稳定的。 但: ```text |front|back|css| ``` 再: ```text |属性|值|样式| ``` 再: ```text |src|style| ``` 再: ```text |组件|样式| ``` 就开始碎片化。 --- # 九、我建议建立统一的 `View` / `Node` 数据模型 例如: ```text Web Node ``` 统一: ```text |type|slot|value|attrs|style| ``` 例如: ```markdown | 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 | ``` 然后: ```text page.render nodes ``` 而不是: ```text compose_main compose_intro compose_list compose_nav_brand ... ``` 这会大幅降低 API 数量。 --- # 十、第二个非常严重的问题:`page` 已经开始承担太多状态 现在: ```text 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` 已经同时知道: ```text Content Presentation Data Routing SEO Assets Forms Client Runtime Database Query Authentication ``` 这是未来维护最大的风险之一。 --- # 十一、建议把 Page 变成纯 Artifact 理想: ```text Page ├── document ├── metadata ├── view ├── data └── route ``` 而不是: ```text Page ├── 20+ mutation methods ``` 例如: ```markdown --- type: page route: /posts/{slug} data: source: posts where: slug: "{slug}" view: layout: article title: "{title}" --- ``` 正文就是: ```markdown # {{title}} {{body}} ``` 这比: ```text page.query page.order page.detail page.compose_main page.compose_intro page.link_prefix ``` 更符合 Marqdo。 --- # 十二、第三个问题:Route 设计太弱 现在 route: ```text app.route path page ``` 但真正 Web Route 应该是: ```text Route ├── path ├── method ├── handler ├── middleware ├── auth ├── input ├── output └── errors ``` 而现在这些能力被拆到了: ```text route invoke gate auth json proxy route_ws mount_form ``` 于是一个完整 endpoint 需要去多个地方寻找语义。 --- # 十三、我建议统一成 Endpoint 这是我认为整个网络库最值得重构的 API。 例如: ```markdown ## get_post --- route: /post/{slug} method: GET --- **post = > db.posts.get slug={slug}** *post* ``` 或者: ```markdown ## create_post --- route: /api/posts method: POST body: json return: json auth: member --- **post = > db.posts.insert body** *post* ``` 于是: ```text Endpoint ``` 本身就是: ```text Documentation + Route + Handler + Input schema + Output schema + Authorization ``` 这才是真正的: > **代码即文档。** --- # 十四、现在的 `invoke` 其实已经暴露出正确方向 你现在: ```text ## invoke path fn method body return ``` 并且: ```text fn must be lib.member ``` 这其实已经很接近我说的 Endpoint。 问题是: > 它被设计成 `app.configure(invoke=table)` 的一项功能,而不是 Web 的一等公民。 应该反过来。 --- # 十五、第四个问题:`configure()` 太重 现在: ```text app.configure( cors security compress body_limit json access_log cache_control proxy invoke ) ``` 这在工程上很方便。 但在语言设计上非常危险。 因为它成为: > **“所有没有地方放的 Web 功能都放进去的垃圾抽屉。”** 今天: ```text cors security compress ``` 明天可能: ```text rate_limit csrf metrics tracing gzip brotli timeout upload webhook grpc ... ``` 最终: ```text configure(...) ``` 会变成一个 30 参数函数。 --- # 十六、建议:Middleware 应该成为一等对象 应该: ```text app ↓ middleware ↓ route ``` 例如: ```markdown ## security | header | value | |--------|-------| | X-Content-Type-Options | nosniff | | Referrer-Policy | strict-origin | ``` 然后: ```text app.use security ``` 或者: ```text route.use auth route.use cors ``` 这样: ```text Middleware ``` 本身是可组合 Artifact。 --- # 十七、第五个问题:大量“隐式路由”破坏代码即文档 例如 `listen` 自动提供: ```text / _/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` 例如: ```yaml --- type: web routes: - / - /post/{slug} --- ``` Runtime 可以自动生成: ```text /_part /_form ``` 但这些应该属于: ```text system routes ``` 而用户 route: ```text declared routes ``` 两者在 introspection 中明确区分: ```text web.inspect() ``` 返回: ```text declared: GET / GET /post/{slug} system: GET /_part/* GET /_form/* ``` 这样既保留便利,又保持可解释性。 --- # 十九、第六个问题:`db` 和 Web 的绑定太紧 现在: ```text page.query page.order page.paginate compose_list form.submit json route ``` 都直接知道 DB。 这让: ```text Web ↔ DB ``` 高度耦合。 但 Marqdo 应该允许: ```text Web ↓ Data Source ├── DB ├── File ├── API ├── Knowledge Base └── Agent ``` 例如: ```text page.data = posts ``` 至于: ```text posts ``` 到底来自: ```text db ``` 还是: ```text knowledge ``` 不应该由 page 决定。 --- # 二十、这和你的 AI-native 方向尤其重要 未来很可能出现: ```text Page ↓ Data ↓ Agent ↓ Knowledge ``` 例如: ```markdown --- type: page data: agent.search --- ``` 所以应该抽象: > **Data Provider** 而不是: > `page.query` = SQL database query。 --- # 二十一、第七个问题:DB 的 `exec/query` 破坏了高级抽象 你有: ```text db.select db.insert db.update ... ``` 同时又: ```text db.exec sql db.query sql ``` 从工程角度这很好,因为 escape hatch 很重要。 但在“代码即文档”的语言设计里: ```text db.query sql="SELECT ..." ``` 又退回: > “请让我写数据库实现细节。” 我建议保留,但明确为: ```text db.raw.query db.raw.exec ``` 这样 API 语义就很清楚: ```text db.query ``` = declarative data query ```text db.raw.query ``` = escape hatch 这非常重要。 --- # 二十二、第八个问题:事务设计不像一个语言原语 现在: ```text db.事务 ↓ txn ↓ insert select update ... ↓ 提交 回滚 ``` 它是典型数据库 SDK。 但 Marqdo 可以做得漂亮很多: ```text **transaction** **db.insert ...** **db.update ...** ``` 或者: ```text **txn = > db.transaction** **txn.insert ...** **txn.update ...** *txn.commit* ``` 甚至最终: ```text **db.transaction** ... ``` 让事务成为代码块/执行上下文,而不是用户管理一个 opaque handle。 --- # 二十三、第九个问题:WebSocket API 还是传统 API 现在: ```text route_ws path echo mode room_key on_message presence require_auth ``` 这其实已经相当丰富。 但: ```text echo broadcast room drain ``` 都是 runtime mode。 我建议统一成: ```text channel ``` 例如: ```markdown ## live --- type: channel path: /live mode: broadcast auth: member --- ``` 然后: ```text ## on_message ... ``` 于是 WebSocket 不再是 `route_ws` 的特殊 API,而成为: > **Realtime Endpoint** 以后还可以自然扩展: ```text SSE WebSocket WebTransport ``` 都属于: ```text stream endpoint ``` --- # 二十四、第十个问题:`storage`、`cache` 其实已经证明你需要统一 Resource 抽象 你现在: ```text # cache ``` 支持: ```text memory: redis:// ``` 以及: ```text # storage ``` 支持: ```text file: s3:// ``` 这里其实已经非常接近你之前讨论的: > **Metadata + Binding** 我建议以后统一: ```text Resource ``` 例如: ```yaml --- type: storage backend: s3 url: ${env.STORAGE_URL} --- ``` 或者: ```yaml --- type: cache backend: redis url: ${secret.REDIS_URL} --- ``` 这和我们刚才设计的 Binding 完美结合。 --- # 二十五、第十一个问题:中英文 API 混用会伤害语言一致性 例如: ```text db.paginate ``` 但参数: ```text 跳过 ``` 事务: ```text 事务 提交 回滚 ``` 同时又有: ```text auth session_ttl login_redirect ``` 我理解为什么这么设计: > Marqdo 希望自然语言友好。 这个方向没问题。 但我建议: ### 核心语义只有一个 canonical name 例如: ```text transaction commit rollback offset ``` 中文可以作为: ```text alias ``` 而不是让底层 ABI 同时拥有两套概念。 即: ```text 提交 → commit 回滚 → rollback 跳过 → offset ``` 这样: ```text AST IR Plugin ABI Documentation ``` 全都只有一个 canonical vocabulary。 --- # 二十六、第十二个问题:`ensure_plugin` 重复暴露了 Runtime 边界 文件里大量: ```text > ensure_plugin ``` 然后: ```text plugin.native_path plugin.load ``` 例如 DB、Form、App 等都依赖这个模式。 这说明: > Native plugin lifecycle 正在侵入 extension language。 用户其实不应该关心: ```text ABI v2 native_path plugin.load ``` 这应该由: ```text import ext:web ``` 自动处理。 --- # 二十七、建议:Import 就意味着 Capability 例如: ```marqdo import web:ext/web/web.mq.md ``` Runtime 自动: ```text resolve ↓ load ↓ initialize ↓ bind ``` 如果缺插件: ```text CapabilityError web backend unavailable install: ... ``` 而不是 extension 自己每个对象调用: ```text ensure_plugin ``` 这样才符合: > **import 是声明依赖,不是调用初始化函数。** --- # 二十八、第十三个问题:Raw HTML/CSS 是一个必要的逃生舱,但现在太容易成为第二套语言 例如: ```text page.css ``` 直接接收 raw CSS。 以及: ```text chrome(nav_html, footer_html) ``` 直接允许 raw HTML。 这当然需要。 但是我建议严格分层: ```text Declarative HTML ↓ Marqdo DOM ↓ raw HTML escape hatch ``` 而不是: ```text Marqdo tables + raw HTML + CSS ``` 三种并列模式。 --- # 二十九、建议正式建立 DOM Artifact 比如: ```text node ├── element ├── attrs ├── children └── text ``` 那么: ```markdown # Hello ``` 天然可以变成: ```text Document ↓ DOM ``` 然后: ```text web.render ``` 负责: ```text DOM → HTML ``` 这样未来: ```text SSR Browser WASM Email PDF Accessibility tree ``` 都可以复用。 --- # 三十、你的 `client_embed` 也值得重新设计 现在: ```text client_embed bridge wasm source boot ``` 并且生成: ```html