Replace the monolithic compose_*/configure author surface with file-level
web|endpoint artifacts, split ext/{web,data,security,net}, and lock
no-degrade rules so the model cannot regress to God-object APIs.
Co-authored-by: Cursor <cursoragent@cursor.com>
2183 lines
28 KiB
Markdown
2183 lines
28 KiB
Markdown
---
|
||
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 的“代码即文档 / 文档即程序 / 执行即知识”这个核心语言模型里。**
|