- 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。
7.7 KiB
Executable File
官方扩展: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=…:
- 递归枚举
DIR下*.mq.md(跳过data/、隐藏目录、node_modules)。 - 解析文件头 Metadata;无
type/类型或非 web/endpoint → 跳过。 - Document → declared route(缺
route则相对root的路径映射,index.mq.md→/)。 - Endpoint → declared path+method(
path/路径必需)。 - System routes(
/_part/*、/_form/*、静态等)由 runtime 挂载,仅出现在inspect.system。 - 调用 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 为准。