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

2183 lines
28 KiB
Markdown
Executable File
Raw 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.
---
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
<script type="module" ...>
```
这实际上已经不是简单 Web Server,而是在做:
> **Marqdo Browser Runtime**
我建议不要把它藏在 `web` 的一个 helper 里。
应该明确:
```text
ext/browser
```
或者:
```text
runtime/browser
```
形成:
```text
Marqdo
├── Server Runtime
└── Browser Runtime
```
这会比现在清晰得多。
---
# 三十一、一个非常关键的问题:API 返回值没有统一的 Result 模型
例如:
```text
db.select
```
返回 rows。
```text
count
```
直接返回 number。
```text
auth.login
```
返回:
```text
{ok, session_id, username, role}
```
```text
storage.put
```
又是另一种。
```text
websocket
```
又是另一种。
这种设计在普通 SDK 里没问题。
但 Marqdo 要成为:
> AI-native programming language
就需要让 Agent 能理解:
```text
what did this operation produce?
```
---
# 三十二、建议建立统一的 `Result`
不是说所有东西都必须包成:
```text
{ok, value, error}
```
而是建立标准 Result protocol:
```text
Result
├── value
├── error
├── metadata
└── status
```
例如:
```text
db.select
→ rows
HTTP
→ response
LLM
→ result
Storage
→ object
```
它们都可以有统一的:
```text
result.status
result.value
result.error
```
这样 Agent、日志、trace、writeback 可以统一处理。
---
# 三十三、我认为你这份库最大的“隐性问题”是:它在不断制造“特殊情况”
从代码可以看到很多:
```text
如果 detail
如果 target
如果 mount
如果 shell_css
如果 layout
如果 media
如果 when
如果 auth
如果 guest
如果 hide
如果 form
如果 client
如果 route param
如果 dynamic route
如果 db
如果 admin
...
```
例如 `compose_components` 本身就包含:
```text
media
when
auth
guest
hide
```
这说明 API 的核心抽象还不够强。
当抽象不够强时,框架就会:
> 每增加一个需求 → 增加一个 flag。
这就是未来最大的技术债。
---
# 三十四、所以我建议从“Feature API”转成“Composable Artifact”
这是我认为最关键的重构方向。
现在:
```text
page.compose_intro()
page.compose_main()
page.compose_list()
page.compose_form()
page.compose_nav_brand()
page.compose_client()
```
应该逐渐变成:
```text
page
├── head
├── body
│ ├── node
│ ├── list
│ ├── form
│ └── component
└── client
```
即:
> **结构组合,而不是功能函数堆积。**
---
# 三十五、我会重新设计整个 `ext/web`
最终结构建议:
```text
ext/web/
│
├── web.mq.md
│
├── page.mq.md
├── route.mq.md
├── component.mq.md
├── dom.mq.md
│
└── client.mq.md
```
然后依赖:
```text
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 可以缩到非常少
我甚至认为:
```text
web.page
web.route
web.serve
web.render
```
已经可以覆盖绝大部分。
---
# 三十七、理想的 Marqdo Web 应用
我希望用户最终能写成:
```markdown
---
type: web
title: Marqdo Blog
route: /
data:
source: posts
order: -created_at
---
# Marqdo
Welcome to the executable web.
## Posts
| title | href | date |
|-------|------|------|
| ... | ... | ... |
```
然后:
```text
marqdo run site.mq.md
```
直接得到:
```text
Document
↓
Data
↓
Page
↓
Route
↓
HTTP Server
```
用户不需要理解:
```text
web_page_new
web_compose_main
web_page_query
web_page_order
web_app_route
web_app_listen
```
---
# 三十八、Dynamic Route 也可以自然成为文档
例如:
```markdown
---
type: web
route: /post/{slug}
method: GET
data:
source: posts
where:
slug: "{slug}"
---
# {title}
{body}
```
这已经同时表达:
```text
Route
Query
View
Content
```
而现在这些能力分散在:
```text
route
page.query
page.detail
compose_main
```
中。
---
# 三十九、API Endpoint 更应该成为 `.mq.md` 本身
例如:
```markdown
---
type: endpoint
method: POST
path: /api/posts
request: json
response: json
auth: member
---
**post = > db.posts.insert row=`body`**
*post*
```
这就是我认为真正属于 Marqdo 的 Web API。
它同时是:
```text
Documentation
+
Implementation
+
Schema
+
Route
+
Authorization
```
而这恰恰就是你一直强调的:
> **代码即文档。**
---
# 四十、最后给你一个我认为比较卓越的整体架构
我会把现在的:
```text
ext/web/web.mq.md
```
重构成:
```text
MARQDO
│
Executable Document
│
┌──────────────┼──────────────┐
│ │ │
Document Endpoint Resource
│ │ │
↓ ↓ ↓
DOM HTTP Route DB/Cache
│ │ Storage/LLM
│ │ │
└──────────────┼──────────────┘
↓
Web Runtime
│
┌─────────────┼─────────────┐
↓ ↓ ↓
SSR HTTP Browser
│ │ │
└─────────────┼─────────────┘
↓
Native Backend
```
而核心原则只有几个:
### ① Document 是第一等公民
不是:
```text
page object
```
而是:
```text
.mq.md → Page
```
### ② Endpoint 是第一等公民
不是:
```text
app.route + app.invoke + app.gate
```
而是:
```text
endpoint.mq.md
```
### ③ Resource 是第一等公民
统一:
```text
db
cache
storage
llm
```
通过 metadata + binding 描述。
### ④ Table 是 Data,不是隐藏 DSL
表格描述结构化数据。
不要每个函数再发明一套 table 方言。
### ⑤ Raw HTML/CSS 是 Escape Hatch
不是第二套主要语言。
### ⑥ Runtime 自动处理 Native Plugin
作者只写:
```text
import web
```
不写:
```text
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.**
这样你前面刚刚确定的:
```text
${env.OPENAI_API_KEY}
${config.llm.model}
${secret.REDIS_URL}
```
也可以统一成为:
> **Artifact Binding**
最终 Marqdo 会形成非常漂亮的一套统一模型:
```text
.mq.md
│
┌─────────────┼─────────────┐
↓ ↓ ↓
Metadata Document Tables
│ │ │
Binding View Data
│ │ │
└─────────────┼─────────────┘
↓
Artifact
│
┌────────────┼────────────┐
↓ ↓ ↓
LLM Agent Web
│ │ │
└────────────┼─────────────┘
↓
Execution
↓
Knowledge Artifact
```
**这才真正把你前面 `llm`、`agent`、`network` 三个看似独立的扩展,统一到了 Marqdo 的“代码即文档 / 文档即程序 / 执行即知识”这个核心语言模型里。**