Files
marqdo/doc/design/ext-web-artifact.md
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

7.7 KiB
Executable File
Raw Permalink Blame History

官方扩展:Web Artifact(Document / Endpoint / Resource)

状态 Accepted · 破坏性(取代 page/app God Object 作者面)
日期 2026-09-28
ADR 0007-web-document-endpoint.md
讨论稿 doc/next/007.md(superseded)
安装 marqdo ext add web(web / 网页)
相关 binding.md · ext-web.md · ext-web-layout-paradigm.md · ext-skill-tools-paradigm.md · stdlib-i18n.md · layers.md

0. 一句话

Document describes the page. Table describes the data. Endpoint describes the interaction. Metadata describes the runtime. Marqdo executes all of them.


1. 三原语

Artifact Metadata type / 类型 含义
Document web / 网页 Markdown 正文 + View → HTML;route/路由 注册 declared HTTP
Endpoint endpoint / 端点 可执行正文为 handler;path+method 注册 API
Resource (绑定/导入) ext/data · ext/security · 未来 LLM 等,经 metadata / import 声明

核心装载识别 type/类型(见 src/artifact/);渲染与 listen 在 ext/web + plugins/web。


2. 目录

ext/web/
  index.mq.md · 网页.mq.md   # 根 skill(智能体先读;含布局铁律)
  layout/ · 布局/            # 文件划分布局工程 tools
  web.mq.md                  # EN facade: page route serve render inspect
  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

布局工程(反 HTML/CSS 注入):见 ext-web-layout-paradigm.md;包内 ext/web/layout/index.mq.md。

作者入口通常:

site/
  index.mq.md          # type: web · route: / · 或 # main → web.serve
  pages/*.mq.md        # type: web
  api/*.mq.md          # type: endpoint
  data/                # sqlite runtime (gitignore)

3. Document(type: web)

---
type: web
title: Marqdo Blog
route: /
method: GET
data_source: posts
data_order: -created_at
import:
  web: ext/web/web.mq.md
  data: ext/data/db.mq.md
---

# Marqdo

Welcome to the executable web.
键 (EN) 键 (ZH) 说明
type 类型 web / 网页
route 路由 路径,可含 {param}
method 方法 默认 GET
view 视图 可选 main:启动时执行主程序,返回递归 View 节点;不与自动 data_source 绑定混用
title 标题 文档标题 / <title>
data_source 数据源 表名
data_order 排序 如 -created_at
data_where 条件 col=val,col2=val2

正文 Markdown 经 dom 变为 DOM Artifact,再 web.render。可选 View 表:

`nodes` =

| type | slot | value | attrs | style |
|------|------|-------|-------|-------|
| text | kicker | AI Native | | eyebrow |
| title | title | Marqdo | | title |

2026-11-08:View 已支持 row/column 容器与 markdown 叶子,容器值保持子表;显式 view: main Document 通过普通函数装配。

2026-11-10:同一五列 View 可放置具型 Resource 节点;结构仍只在启动时装配,数据查询、已挂载表单与会话导航在请求期间解析。无新增 frontmatter 或核心标记;见 请求资源。普通离线渲染缺少请求上下文时明确报错,不伪造动态内容。完整工程见布局实践,实现边界见优化说明。

page.render nodes= 是唯一主装配路径。禁止 compose_main / compose_intro 等碎片 DSL。


4. Endpoint(type: endpoint)

---
type: endpoint
method: POST
path: /api/posts
request: json
response: json
auth: member
import:
  data: ext/data/db.mq.md
---

**post = > data.db.insert …**

*post*
键 (EN) 键 (ZH) 说明
type 类型 endpoint / 端点
path 路径 URL
method 方法 GET/POST/…
request 请求 json / form / none
response 响应 json / text / html / sse(text/event-stream)
auth 鉴权 角色名或 none;bearer / api_key = 不要求 cookie,把 Authorization / X-Api-Key 注入 payload 由 # main 校验

正文在请求时执行;返回值按 response 序列化。Result 协议见 §8。

Handler 约定(锁定):Endpoint 文件用 # main 作为请求处理器。请求体/query/path 参数经 run_artifact 以 Metadata Binding 覆盖注入(与 --bind 同源),正文用已提升的普通变量名。无 # main 时返回 Artifact Result 摘要(ok/value/error),适合作文档型 ping。


5. Facade API(EN / ZH)

EN ZH 作用
web.page 网页.页面 从 metadata/正文/nodes 构造 Document 句柄
web.route 网页.路由 注册 declared Document 或 Endpoint
web.serve 网页.服务 root= 扫描注册 + listen
web.render 网页.渲染 Document → HTML(离线/预览)
web.inspect 网页.检视 {declared, system} 路由表

Middleware 一等:web.use / route.use,表驱动;禁止 configure(cors, security, …) 垃圾抽屉。


6. 发现算法(锁定)

web.serve root=DIR host=… port=…:

  1. 递归枚举 DIR 下 *.mq.md(跳过 data/、隐藏目录、node_modules)。
  2. 解析文件头 Metadata;无 type/类型 或非 web/endpoint → 跳过。
  3. Document → declared route(缺 route 则相对 root 的路径映射,index.mq.md → /)。
  4. Endpoint → declared path+method(path/路径 必需)。
  5. System routes(/_part/*、/_form/*、静态等)由 runtime 挂载,仅出现在 inspect.system。
  6. 调用 native listen。

7. Table 规则

  • View:仅 |type|slot|value|attrs|style|(及列名 ZH 别名:类型|槽|值|属性|样式)。
  • Resource schema:|字段|类型|可空| 等 — 专用且文档化,不是函数私有方言。
  • 禁止 |属性|值|样式| / |front|back|css| / |组件|样式| 作为页面主装配(已删除)。
  • Raw HTML/CSS = escape hatch(dom.raw / page.css),不是默认语言。

8. Result

所有易失败的 Resource / Endpoint 边界返回 map:

键 类型 说明
ok bool 成功
value any 成功载荷
error text | None 失败信息

9. 硬约束(取代旧 C1–C7 作者面)

# 约束
A1 Document/Endpoint 由核心识别 type;装配在 ext(ADR 0007)
A2 禁止 json.set 袋胶水;Table = Data
A3 中英分文件;同文件禁止混 API
A4 禁止作者 ensure_plugin / host_*
A5 禁止隐式用户 route;system 须 inspect 可见
A6 禁止恢复 compose_* / app.configure / god page 变异堆
A7 能力只许迁移/提升;删除须本设计明示 + tests 同步
A8 设计未锁定处停工提问,禁止自行发明 DSL
A9 文件划分布局:页面拆到简单组件文件为止;默认禁止整页 HTML/CSS 注入(dom.raw/page.css 仅逃逸舱)

10. 与旧 ext-web.md

旧「页面表 + compose_* + app.route」作者面 废止。历史能力矩阵见 web-net-capabilities.md;迁移后以本文件与 ADR 0007 为准。