Start web skill=tools migration with in-package layout law.

Add root/index and layout skills that force file-partitioned pages and ban
HTML/CSS injection as the default path; wire ext add, docs, and call coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-11-08 21:50:01 +08:00
1 parent 24dcb97354
commit bb06dad134
17 files changed
+1065 -41

No files matched your search

+4 -2
View File
@@ -186,8 +186,10 @@ Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifa
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
- EN: `import web:ext/web/web.mq.md`
- ZH: `导入 网页:ext/web/网页.mq.md`
- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页.mq.md`](../../ext/web/网页.mq.md)
- **Layout law (in-package):** file-partition pages (nav/sidebar/footer/…) until simple; no HTML/CSS injection as default — [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) · [ext-web-layout-paradigm.md](../../doc/design/ext-web-layout-paradigm.md)
- EN author facade: `import web:ext/web/web.mq.md`
- Agent: `marqdo call ext/web/layout/index.mq.md rules --json` then facade tools with `--effects plugin`
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
+1 -1
View File
@@ -93,7 +93,7 @@ web.plugin # absolute path hint
|----|-----------------------------|
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
| `web` | `web/index.mq.md` + facade/modules + `layout/` · `布局/` + `网页.mq.md`, **native `web`** |
| `quantum` | `quantum/`(含 `量子/` 中文树), **native `quantum`** |
## Release assets (native)
+6 -4
View File
@@ -6,7 +6,7 @@
| 日期 | 2026-11-06 |
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
| 契约摘要 | [ext-index-skill-tools.md](ext-index-skill-tools.md) |
| 试点 | [`ext/quantum/`](../../ext/quantum/) |
| 试点 | [`ext/quantum/`](../../ext/quantum/)(完成)· [`ext/web/`](../../ext/web/)(迁移中,含[布局范式](ext-web-layout-paradigm.md)) |
| 相关 | [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) |
---
@@ -208,10 +208,12 @@ MARQDO_EXT_SOURCE=/path/to/repo/ext \
## 13. 推广顺序(建议)
1. **已完成试点**:`ext/quantum/`(含 `量子/`)
2. **下一优先**:结构已分文件、且强依赖 `marqdo call` 的包(如 `linalg` 公式面、`ai` agent 面)
3. **较大包**(`web`):先拆根 skill + 明确系统路由/`web.inspect`,再按模块补 For AI 段;勿回退 compose 碎片 DSL
2. **进行中**:`ext/web/` — 根 `index` + `layout` 布局铁律(文件划分、反 HTML 注入)已入库;facade 路径保持兼容;模块叙述与 call 金样继续补齐
3. **下一优先**:`linalg` 公式面、`ai` agent 面
4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade
每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。
每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。
**Web 特有**:布局工程必须写进包内 skill(见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md)),不能只放在外部 README。
---
+7 -2
View File
@@ -7,7 +7,7 @@
| ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) |
| 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) |
| 安装 | `marqdo ext add web`(`web` / `网页`) |
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md) · [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
---
@@ -33,13 +33,17 @@
```text
ext/web/
web.mq.md · 网页.mq.md # facade: page route serve render inspect
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-paradigm.md);包内 `ext/web/layout/index.mq.md`。
作者入口通常:
```text
@@ -191,6 +195,7 @@ Middleware 一等:`web.use` / `route.use`,表驱动;**禁止** `configure(
| A6 | 禁止恢复 `compose_*` / `app.configure` / god page 变异堆 |
| A7 | 能力只许迁移/提升;删除须本设计明示 + tests 同步 |
| A8 | 设计未锁定处停工提问,禁止自行发明 DSL |
| A9 | **文件划分布局**:页面拆到简单组件文件为止;默认禁止整页 HTML/CSS 注入(`dom.raw`/`page.css` 仅逃逸舱) |
---
+124
View File
@@ -0,0 +1,124 @@
# Web 布局工程范式:文件划分 · 直到简单 · 禁止注入
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-11-06 |
| 包内落地 | [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) |
| 上位 | [ext-web-artifact.md](ext-web-artifact.md) · ADR [0007](../adr/0007-web-document-endpoint.md) |
| 扩展范式 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) |
---
## 0. 一句话
> **页面不是一整块 HTML。页面是目录树上的若干 Document / 组件文件;每个文件只描述一层简单布局,复杂处继续拆文件,直到 View 表与 Markdown 都可读、可绑、可维护。**
值绑定、数据库绑定、样式绑定(`|type|slot|value|attrs|style|`)是默认语言。
**禁止**把「能跑」建立在 `dom.raw` / 大段 HTML 字符串 / 随意 CSS 注入上——那是逃逸舱,不是工程方法。
---
## 1. 为什么 AI 会走偏
网络扩展提供了绑定与 View 表,但代理常觉得「写 HTML/CSS 更快」,于是:
| 偏航 | 后果 |
|------|------|
| 首页一个文件塞满结构 | 无法复用导航/页脚;改一处炸全站 |
| `dom.raw` / `set_html` 拼页面 | 绕过绑定与主题;不可检视、不可 i18n 对齐 |
| 私有表方言 / `compose_*` | 与 ADR 0007 冲突;回归神对象 |
| 样式写进巨大 `<style>` | 与 `style` 列、主题表脱节 |
本范式把**正确拆法写进扩展 skill 本身**,让冷启动代理先读规则再动手。
---
## 2. 文件划分布局(强制心智)
以站点首页为例,**先划文件,再写内容**:
```text
site/
index.mq.md # type: web · route: / · 只编排「壳」与主区意图
pages/about.mq.md # 其它 Document
api/*.mq.md # Endpoint
components/
nav.mq.md # 顶栏(简单:品牌 + 链接表)
sidebar.mq.md # 侧栏(简单:列表或 TOC)
footer.mq.md # 底栏入口(若仍复杂 → 再拆)
footer/
brand.mq.md # 底栏左:品牌/版权
links.mq.md # 底栏右:链接双栏之一
styles/
theme.mq.md # 具名样式表(供 style 列引用)
data/ # 运行时库(gitignore)
```
### 2.1 划分判据
| 若出现… | 则… |
|---------|-----|
| 一个文件里同时有导航 + 主列 + 页脚 | 拆成 `components/*` + 页面正文 |
| 页脚已是「左品牌右双栏链接 + 复杂样式」 | 再拆 `footer/brand` · `footer/links`,各文件只保留一张简单 View 表或短 Markdown |
| View 表超过约一屏且多段语义 | 按槽位/区域拆文件,用 `component.merge` 或页面级 import 组合 |
| 想写 `<div class=…>` 才能对齐 | 先问能否用 `type/slot/style`;不能再考虑逃逸舱并注明原因 |
### 2.2 简单的定义
一个组件文件「够简单」当且仅当:
- 人一眼能说出**单一职责**(例如「仅顶栏链接」);
- 主数据是 **一张** View 表或短 Markdown,而不是嵌套 HTML;
- 样式只通过 **具名 style**(主题表)或 `style` 列引用,不内嵌大段 CSS。
---
## 3. 合法装配面(唯一主路径)
| 允许 | 禁止(默认路径) |
|------|------------------|
| Document Metadata:`type: web` · `route` · `data_source` … | 隐式用户路由;`configure` 垃圾抽屉 |
| 正文 Markdown | 把整页写成 HTML 字符串 |
| View 表 `\|type\|slot\|value\|attrs\|style\|`(ZH 别名可) | `compose_*`;`\|属性\|值\|样式\|` 等废止方言当主装配 |
| `component.nodes` / `component.merge` | `json.set` 袋胶水拼 DOM |
| `web.render` / `page.render` | 作者 `ensure_plugin` / `host_*` |
| `dom.raw` / `page.css` **仅逃逸舱**(须注释「为何不能表驱动」) | 用 raw/css 作为首页主实现 |
数据与鉴权在 `ext/data` · `ext/security`;实时在 `ext/net`——不要塞回 `ext/web` facade。
---
## 4. 智能体操作顺序
冷启动只读 [`ext/web/index.mq.md`](../../ext/web/index.mq.md):
| 若你需要 | 这样做 |
|----------|--------|
| 理解怎么拆页面 | 打开 `ext/web/layout/index.mq.md`,先 `marqdo call … rules` |
| 预览 Document HTML | `web.render` / `网页.渲染`(`--effects plugin`) |
| 起站 | 站点 `serve.mq.md` → `web.serve`;或 call facade `serve` |
| 检视路由 | `web.inspect` |
写站时循环:
1. 列出区域(导航 / 侧栏 / 主区 / 底栏…)→ 各建文件
2. 每个文件只做简单 View 或 Markdown
3. 复杂区域继续拆,直到简单
4. 页面 Document 只保留路由、数据源与主区意图;壳由组件组合
5. 绝不先写 HTML 再「补绑定」
---
## 5. 与 skill=tools 迁移
`ext/web` 按 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 迁移:根 `index` = SKILL,`layout` = 布局工程工具面,原有 `page`/`route`/… 补齐 For AI agents 与叙述占比。
**布局范式是 web 包特有硬约束**,与 quantum 试点并列写入扩展内,而不是只写在外部 README。
---
## 6. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-11-06 | 初版:文件划分布局、反 HTML/CSS 注入、与 Artifact / skill=tools 对齐 |
+19 -8
View File
@@ -1,20 +1,31 @@
# ext/web — Document / Endpoint / Resource
Official dynamic site extension (**ADR 0007**). Design: [`doc/design/ext-web-artifact.md`](../../doc/design/ext-web-artifact.md).
Official dynamic site extension (**ADR 0007**).
| Surface | Import |
|---------|--------|
| English | `import web:ext/web/web.mq.md` |
| Chinese | `导入 网页:ext/web/网页.mq.md` |
| Doc | Link |
|-----|------|
| Artifact model | [`doc/design/ext-web-artifact.md`](../../doc/design/ext-web-artifact.md) |
| **Layout engineering** | [`doc/design/ext-web-layout-paradigm.md`](../../doc/design/ext-web-layout-paradigm.md) |
| skill=tools paradigm | [`doc/design/ext-skill-tools-paradigm.md`](../../doc/design/ext-skill-tools-paradigm.md) |
| Surface | Path |
|---------|------|
| EN root skill (agents first) | `ext/web/index.mq.md` |
| EN author facade | `import web:ext/web/web.mq.md` |
| ZH root / facade | `导入 网页:ext/web/网页.mq.md` |
| Layout tools | `ext/web/layout/index.mq.md` · `ext/web/布局/索引.mq.md` |
**Facade:** `page` · `route` · `serve` · `render` · `inspect` · `use`
**Related modules:** `ext/data` (db/cache/storage) · `ext/security` (auth/oidc/rbac) · `ext/net` (http/websocket/url)
**Layout law:** partition pages into files (nav / sidebar / main / footer / …) until each piece is simple; bind via `|type|slot|value|attrs|style|`. Do **not** build sites by HTML/CSS injection (`dom.raw` is escape hatch only).
**Related modules:** `ext/data` · `ext/security` · `ext/net`
```bash
bash scripts/build-web-plugin.sh
marqdo ext add web # optional install
marqdo ext add web
marqdo call ext/web/layout/index.mq.md rules --json
marqdo run examples/marqdo-blog/serve.mq.md
```
Hard rules: no author `ensure_plugin` / `compose_*` / `configure` junk drawer; View schema `|type|slot|value|attrs|style|` only; declared vs system routes via `inspect`.
Hard rules: no author `ensure_plugin` / `compose_*` / `configure` junk drawer; View schema only; declared vs system routes via `inspect`; no `MARQDO_EXT=repo/ext` self-install.
+37 -2
View File
@@ -1,15 +1,40 @@
---
markup: occlusion
title: ext/web/component
description: Reusable Document fragments as View node tables (ADR 0007).
description: >-
Reusable Document fragments as View node tables (ADR 0007). One file, one duty;
merge simple parts instead of writing HTML.
import:
table: lib/table.mq.md
---
Components are how file-partitioned layouts stay simple. Each component file
should expose one View table (or short Markdown consumed elsewhere). When a
footer needs two columns, use two component files and `merge` — do not embed a
mini-HTML layout in one cell.
## For AI agents
Call example (plain text):
marqdo call ext/web/layout/index.mq.md accept_component name="footer-links" duty="right link column only" --json
Prefer authoring separate tables then merge. No plugin required for nodes/merge.
*None*
## nodes
+ `table`
Identity helper — a component is a View table `|type|slot|value|attrs|style|`.
Keep the table small enough that a human sees a single region.
| 参数 | 类型 | 说明 |
|------|------|------|
| table | any | View table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | same table |
*table*
@@ -17,6 +42,16 @@ Identity helper — a component is a View table `|type|slot|value|attrs|style|`.
+ `a`
+ `b`
Concatenate two View node lists (list-of-maps or column tables). Prefer authoring one table.
Concatenate two View node lists (list-of-maps or column tables). Use after
splitting regions into files. Prefer many small tables over one private dialect.
| 参数 | 类型 | 说明 |
|------|------|------|
| a | any | first nodes |
| b | any | second nodes |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | concatenated nodes |
*> table.concat a=`a` b=`b`*
+49 -3
View File
@@ -1,16 +1,39 @@
---
markup: occlusion
title: ext/web/dom
description: DOM Artifact — Markdown/body to structure; raw HTML is escape hatch only (ADR 0007).
description: >-
DOM Artifact — Markdown/body to structure; raw HTML is escape hatch only
(ADR 0007). Never use raw as the default homepage method.
import:
cap: ext/web/_capability.mq.md
table: lib/table.mq.md
---
## For AI agents
Prefer `from_markdown` and View tables from `ext/web/layout` / `component`.
`raw` is an escape hatch: if you call it for a whole page shell, you are
violating the layout law in `ext/web/index.mq.md`. Always `--effects plugin`
for render paths.
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
*None*
## from_markdown
+ `text`
Turn Markdown text into a simple DOM map `{kind:"markdown", text}` for `page.render` / `web.render`.
This is the default body path for Document prose.
| 参数 | 类型 | 说明 |
|------|------|------|
| text | text | Markdown source |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | DOM map |
> cap.load
**`out` = > table.put in=None at="kind" value="markdown"**
@@ -19,7 +42,17 @@ Turn Markdown text into a simple DOM map `{kind:"markdown", text}` for `page.ren
## raw
+ `html`
Escape hatch — wrap a raw HTML string. Prefer Markdown / View nodes.
Escape hatch — wrap a raw HTML string. Prefer Markdown / View nodes. Allowed only
when table-driven layout cannot express a host constraint; document the why next
to the call. Forbidden as the primary implementation of nav/sidebar/footer/home.
| 参数 | 类型 | 说明 |
|------|------|------|
| html | text | raw HTML (escape hatch) |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | DOM map kind=raw |
> cap.load
**`out` = > table.put in=None at="kind" value="raw"**
@@ -28,7 +61,20 @@ Escape hatch — wrap a raw HTML string. Prefer Markdown / View nodes.
## render
+ `dom`
Render a DOM Artifact (markdown or raw) to HTML via native plugin.
Render DOM Artifact `dom` to HTML via the native plugin. When kind is markdown,
the plugin turns Markdown text into HTML for Document preview. When kind is raw,
the stored HTML string is returned unchanged — that path exists only for the
escape hatch documented on raw, not for assembling a full site shell. Prefer
feeding markdown DOM produced by from_markdown, or skip this helper and use
page.render / web.render on View tables from file-partitioned components.
| 参数 | 类型 | 说明 |
|------|------|------|
| dom | any | DOM map from from_markdown or raw |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML text |
> cap.load
**kind = [kind](access(dom, "kind"))**
+134
View File
@@ -0,0 +1,134 @@
---
markup: occlusion
title: ext/web
description: >-
Web Artifact root skill (ADR 0007). Read this first. Layout is file-partitioned;
tools run with marqdo call. No HTML/CSS injection as the default page method.
import:
layout: ext/web/layout/index.mq.md
page: ext/web/page.mq.md
route: ext/web/route.mq.md
component: ext/web/component.mq.md
dom: ext/web/dom.mq.md
client: ext/web/client.mq.md
web: ext/web/web.mq.md
---
This file is the root skill for the Marqdo web package. If you are an AI agent
with no other Marqdo context, follow Choose a path, then Layout law, then How to
execute any tool. Do not invent MCP wrappers, raw HTML homepages, or a second
API. The Markdown ## headings are the tools. Author programs may still
`import web:ext/web/web.mq.md` for the facade; agents should start here.
## Choose a path
Pick one row. Do not mix English and Chinese tool names or trees.
| If you need | Do this |
|-------------|---------|
| Layout rules before writing files | Call `layout.rules` on `ext/web/layout/index.mq.md` (command below). |
| Preview HTML for a Document / View table | Call `web.render` via facade path or import `web` tools with `--effects plugin`. |
| Serve a site root | Author `serve.mq.md` calling `web.serve`, or call serve with `root=` · `port=`. |
| Chinese tool names | Open `ext/web/网页.mq.md` and stay in Chinese names. |
Agents use `##` tools with `marqdo call`. `# page` / `# route` / `# app` objects
are for author programs. Escape hatches `dom.raw` and `page.css` are not the
default path for building a homepage.
*None*
## Layout law
Web pages are built by file partition, not by injecting HTML. Split a homepage
into files for navigation, sidebar, main, and footer. If a region is still
complex (two-column footer, dense styles), split again until each file is
simple: one duty, one View table or short Markdown. Bind values, database
fields, and named styles through the unified View columns type, slot, value,
attrs, and style only. Forbidden as the default method: whole-page HTML
strings, CSS injection bags, restored compose fragments, and json.set DOM glue.
Escape hatch only: dom.raw / page.css, and only with a written reason.
Full text: doc/design/ext-web-layout-paradigm.md. In-package tools live at
ext/web/layout/index.mq.md.
Minimal commands to load the law (no plugin required):
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/layout/index.mq.md view_schema --json
*None*
## How to execute any tool
Call example (plain text):
marqdo call FILE FUNCTION name=value name=value --effects plugin --json
FILE is under `ext/web/`, usually `index.mq.md` or a module path. FUNCTION is the
exact ## heading. Nested ### use `parent.child`. Pass `--effects plugin` for
anything that loads the native web plugin (`render`, `serve`, `inspect`, …).
Layout helpers `rules` / `view_schema` / `accept_component` are pure and may omit
plugin effects. Use `--session` / `--toget` / `$name` to chain handles. Do not
call `ensure_plugin` or `host_*`; facades load the plugin.
Verify layout skill (no plugin):
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
*None*
## Package layout
| Path | Role |
|------|------|
| `ext/web/index.mq.md` | This root skill |
| `ext/web/layout/index.mq.md` | File-partition layout engineering tools |
| `ext/web/web.mq.md` | Author facade: page · route · serve · render · inspect · use |
| `ext/web/page.mq.md` | Document handle · render |
| `ext/web/route.mq.md` | Declared routes |
| `ext/web/component.mq.md` | View fragments · merge |
| `ext/web/dom.mq.md` | Markdown DOM; raw is escape hatch |
| `ext/web/client.mq.md` | WASM embed · patches |
| `ext/web/_capability.mq.md` | Plugin load only |
| `ext/web/网页.mq.md` | Chinese facade / skill mirror |
Related packages (not this facade): `ext/data`, `ext/security`, `ext/net`.
*None*
## layout module
File path: `ext/web/layout/index.mq.md`
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/layout/index.mq.md accept_component name="nav" duty="top links only" --json
Main ## tools: rules, view_schema, merge_nodes, accept_component.
*None*
## facade module
File path: `ext/web/web.mq.md`
Author import: `web: ext/web/web.mq.md`. Agent call examples:
Call example (plain text):
marqdo call ext/web/web.mq.md inspect --effects plugin --json
Main ## tools: page, route, render, use, inspect, serve, client_embed, …
*None*
## layout_rules
Root convenience: same payload as `layout.rules` so agents who only opened this
file can still fetch the law.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | layout rule map |
*> layout.rules*
+119
View File
@@ -0,0 +1,119 @@
---
markup: occlusion
title: ext/web/layout
description: >-
Web layout engineering skill — partition pages into files until every piece is
simple. View tables only; HTML/CSS injection is escape hatch, not the method.
import:
component: ext/web/component.mq.md
---
Layout is how Marqdo web stays maintainable. A homepage is not one HTML blob. It
is a directory of Documents and component files: nav, sidebar, main, footer.
When a region is still complex (for example a two-column footer with brand and
link groups), split again until each file has one job and one simple View table
or short Markdown. Bind values, data, and named styles through
`|type|slot|value|attrs|style|`. Do not reach for `dom.raw` or giant CSS strings
to "finish faster" — that bypasses binding and becomes unreadable.
Canonical design: `doc/design/ext-web-layout-paradigm.md`.
## For AI agents
If you were given only this file, load the rules before writing any site file.
Always pass `--effects plugin` when a later step needs the native web plugin;
these tools are pure documentation helpers and need no plugin.
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/layout/index.mq.md view_schema --json
When authoring: create `components/*.mq.md` (and nested folders) first, then a
thin `type: web` page that states route and main intent. Prefer
`component.merge` to concatenate View tables. Never make `dom.raw` the home
page implementation.
*None*
## rules
Return the layout engineering rules as a readable map for agents and checklists.
No parameters. This tool does not load the plugin.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | rule map |
`out` =
| key | value |
|-----|-------|
| paradigm | file-partitioned layout |
| partition | homepage splits into nav, sidebar, main, footer files |
| until_simple | split again when a file has multiple jobs or dense styles |
| view_schema | only type slot value attrs style columns |
| forbid_default | HTML string pages; CSS injection; compose_*; json.set DOM bags |
| escape_hatch | dom.raw / page.css only with a written why |
| data_bind | values, db, and named styles via tables |
*out*
## view_schema
Return the only allowed View table column names (English). Chinese aliases are
`类型|槽|值|属性|样式`. No parameters.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | column list |
`cols` =
| col |
|-----|
| type |
| slot |
| value |
| attrs |
| style |
*cols*
## merge_nodes
Concatenate View node tables `a` and `b`. Use after splitting regions into files
so a page can assemble simple parts without HTML.
| 参数 | 类型 | 说明 |
|------|------|------|
| a | any | first View table |
| b | any | second View table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | concatenated View nodes |
*> component.merge a=`a` b=`b`*
## accept_component
Documentary gate for authors and agents. Pass component `name` (file stem) and
single-duty `duty` (one short sentence). Returns an accept map reminding that
the file must stay single-duty. Does not write disk.
| 参数 | 类型 | 说明 |
|------|------|------|
| name | text | component name, for example nav |
| duty | text | one-job description |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | accept checklist row |
`row` =
| ok | name | duty | must | reject_if |
|----|------|------|------|-----------|
| True | `name` | `duty` | one View table or short Markdown; named styles only | mixes nav+footer · embeds raw HTML as main body · private table dialects |
*row*
+44 -3
View File
@@ -1,12 +1,26 @@
---
markup: occlusion
title: ext/web/page
description: Document → View. Sole compose path is render(nodes=) with unified View schema (ADR 0007).
description: >-
Document → View. Sole compose path is render(nodes=) with unified View schema
(ADR 0007). File-partition layouts; no HTML injection as default.
import:
cap: ext/web/_capability.mq.md
table: lib/table.mq.md
---
## For AI agents
Build Documents with Metadata (`type: web`) and thin pages. Put chrome in
`components/*.mq.md` files. View schema is only `|type|slot|value|attrs|style|`.
Call `ext/web/layout/index.mq.md` `rules` before inventing structure. Always
`--effects plugin` for render.
Call example (plain text):
marqdo call ext/web/layout/index.mq.md view_schema --json
*None*
# page
+ `title`=""
+ `route`="/"
@@ -19,6 +33,7 @@ import:
Web Document handle. Prefer constructing from Artifact Metadata via `web.page` facade.
View tables use only `|type|slot|value|attrs|style|` (ZH `|类型|槽|值|属性|样式|`).
Do not pass a raw HTML string as the primary `body` for a full site shell.
> cap.load
`out` =
@@ -33,7 +48,22 @@ View tables use only `|type|slot|value|attrs|style|` (ZH `|类型|槽|值|属性
+ `nodes`=None
+ `db`=None
Render Document to HTML. `nodes` is the unified View table; when omitted, uses `self.nodes` or Markdown `body`.
Render this Document to HTML for preview or response. Optional `nodes` is the
unified View table (type/slot/value/attrs/style). When `nodes` is None, the
method uses self.nodes if present, otherwise Markdown body. Optional `db`
supplies bound rows for data_source pages. Prefer assembling `nodes` from
file-partitioned components via component.merge — do not pass a handmade HTML
string as the page shell. This is the sole compose path (ADR 0007); there is no
compose_main or fragment DSL.
| 参数 | 类型 | 说明 |
|------|------|------|
| nodes | any | View table or None |
| db | any | optional database handle |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML or render payload |
> cap.load
**n = nodes**
@@ -50,7 +80,18 @@ Render Document to HTML. `nodes` is the unified View table; when omitted, uses `
## css
+ `css`
Escape hatch — append raw CSS (not a second primary language).
Escape hatch — append raw CSS string `css` to this page. Named style tables and
the View style column remain the default theme path. Use this only when a host
constraint cannot be expressed as a named style row, and write that reason next
to the call. Forbidden as the primary way to style nav, sidebar, or footer.
| 参数 | 类型 | 说明 |
|------|------|------|
| css | text | raw CSS (escape hatch) |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | updated page handle |
> cap.load
*> web_page_css page=`self` css=`css`*
+239 -10
View File
@@ -4,6 +4,7 @@ title: ext/web/web
description: >-
Web Artifact facade (ADR 0007) — page · route · serve · render · inspect · use.
Document/Endpoint first-class. No compose_* / configure / author ensure_plugin.
Agents: read ext/web/index.mq.md first (layout file-partition law).
import:
cap: ext/web/_capability.mq.md
page_mod: ext/web/page.mq.md
@@ -13,7 +14,24 @@ import:
table: lib/table.mq.md
---
Importing this module is the web **capability** (native plugin loads on first facade call).
Importing this module is the web capability (native plugin loads on first facade
call). Cold-start agents should open ext/web/index.mq.md before calling tools
here. Pages are file-partitioned View/Markdown assemblies — not HTML injection.
Layout skill: ext/web/layout/index.mq.md.
## For AI agents
Every ## below is a tool. Prefer --effects plugin. For how to split nav /
sidebar / footer into files, call layout rules first:
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/web.mq.md inspect --effects plugin --json
Do not use dom_patch / raw HTML to build a whole Document homepage. Prefer
type: web Artifact files under a site root and web.serve.
*None*
## page
+ `title`=""
@@ -25,7 +43,26 @@ Importing this module is the web **capability** (native plugin loads on first fa
+ `data_order`=""
+ `data_where`=""
Construct a Document handle. Prefer `type: web` Artifact files discovered by `serve`.
Construct a Document handle with title, route, method, Markdown body, optional
View nodes, and flat data_source / data_order / data_where keys. Prefer
discovering type: web Artifact files via serve rather than hand-building every
page in memory. nodes must be the unified View schema, never a private dialect
or an HTML string shell.
| 参数 | 类型 | 说明 |
|------|------|------|
| title | text | document title |
| route | text | path |
| method | text | HTTP method |
| body | text | Markdown body |
| nodes | any | View table or None |
| data_source | text | table name |
| data_order | text | order key |
| data_where | text | filters |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | page handle |
*> page_mod.page title=`title` route=`route` method=`method` body=`body` nodes=`nodes` data_source=`data_source` data_order=`data_order` data_where=`data_where`*
@@ -40,8 +77,27 @@ Construct a Document handle. Prefer `type: web` Artifact files discovered by `se
+ `auth`=""
+ `class`=""
Register a declared Document page or Endpoint (`fn` = `lib.member`).
Optional `class`: `execute` | `short` | `read` | `control`.
Register a declared Document page or Endpoint on app. path and method identify
the HTTP surface. page holds a Document; fn names an Endpoint lib.member.
request / response / auth / class document the contract. Optional class values
include execute, short, read, control. User routes must be declared — never
implicit. After building the route object this tool registers it on the app.
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | app handle |
| path | text | URL path |
| method | text | HTTP method |
| page | any | Document or None |
| fn | text | endpoint member |
| request | text | request kind |
| response | text | response kind |
| auth | text | auth tag |
| class | text | route class |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | registration result |
**r = > route_mod.route app=`app` path=`path` method=`method` page=`page` fn=`fn` request=`request` response=`response` auth=`auth` class=`class`**
*> `r`.register app=`app`*
@@ -53,7 +109,23 @@ Optional `class`: `execute` | `short` | `read` | `control`.
+ `title`=""
+ `db`=None
Render a Document or View nodes to HTML (offline / preview).
Render a Document or View nodes to HTML for offline preview. Prefer nodes from
file-partitioned components. When doc is set, delegates to page.render. When
only nodes are set, renders that View table. Otherwise renders Markdown body.
Requires the native plugin. Do not treat this as permission to paste a full HTML
homepage — keep using View tables and Markdown.
| 参数 | 类型 | 说明 |
|------|------|------|
| doc | any | Document or None |
| nodes | any | View table or None |
| body | text | Markdown |
| title | text | title |
| db | any | optional db |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML or payload |
> cap.load
1. `doc`
@@ -67,7 +139,18 @@ Render a Document or View nodes to HTML (offline / preview).
+ `app`
+ `middleware`
First-class middleware — pass a GFM table (security headers, cors row, etc.). Replaces `configure(...)` junk drawer.
Attach first-class middleware to app. Pass a GFM table (security headers, cors
row, and similar). This replaces the old configure(...) junk drawer with an
explicit table authors can read.
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | app handle |
| middleware | any | middleware table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
> cap.load
*> web_app_use app=`app` middleware=`middleware`*
@@ -75,7 +158,17 @@ First-class middleware — pass a GFM table (security headers, cors row, etc.).
## inspect
+ `app`=None
Return `{declared, system}` route tables for introspection (code-as-documentation).
Return declared versus system route tables for introspection. System routes such
as /_part and /_form must appear here. Use this to verify a site after serve or
manual registration. Optional app selects which application to inspect.
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | app or None |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | {declared, system} |
> cap.load
*> web_inspect app=`app`*
@@ -88,7 +181,23 @@ Return `{declared, system}` route tables for introspection (code-as-documentatio
+ `static_dir`=""
+ `middleware`=None
Scan `root/**/*.mq.md` for `type: web|endpoint` (ZH `类型: 网页|端点`), register declared routes, attach system routes, listen.
Scan root for type web or endpoint Artifacts, register declared routes, attach
system routes, and listen on host:port. The site directory should already follow
the layout law (components split until simple). Optional db and middleware bind
resources without stuffing them into this facade as author APIs.
| 参数 | 类型 | 说明 |
|------|------|------|
| root | text | site root |
| host | text | bind host |
| port | number | port |
| db | any | optional db |
| static_dir | text | static files |
| middleware | any | optional middleware |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | serve result |
> cap.load
*> web_serve_root root=`root` host=`host` port=`port` db=`db` static_dir=`static_dir` middleware=`middleware`*
@@ -99,12 +208,40 @@ Scan `root/**/*.mq.md` for `type: web|endpoint` (ZH `类型: 网页|端点`), re
+ `source`=""
+ `boot`=True
Describe WASM bridge embed tags for a page that needs client Marqdo. This is not
a substitute for Document layout: still partition nav and main in files, then
embed the bridge where interaction needs it.
| 参数 | 类型 | 说明 |
|------|------|------|
| bridge | text | bridge script URL |
| wasm | text | wasm URL |
| source | text | optional source |
| boot | bool | auto boot |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | embed descriptor |
*> client_mod.embed bridge=`bridge` wasm=`wasm` source=`source` boot=`boot`*
## text_patch
+ `sel`
+ `text`
Client patch: set text content for CSS selector sel. Use for small interactive
updates after a Document is already laid out with View tables — not for building
the initial homepage shell.
| 参数 | 类型 | 说明 |
|------|------|------|
| sel | text | CSS selector |
| text | text | new text |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | patch descriptor |
*> client_mod.text_patch sel=`sel` text=`text`*
## dom_patch
@@ -113,6 +250,21 @@ Scan `root/**/*.mq.md` for `type: web|endpoint` (ZH `类型: 网页|端点`), re
+ `attrs`=None
+ `remove`=False
Client patch for selector sel with optional html, attrs, or remove. Treat html
here as a surgical update, never as the primary way to author nav, sidebar, or
footer. Layout law still applies to the Document that hosts the selector.
| 参数 | 类型 | 说明 |
|------|------|------|
| sel | text | CSS selector |
| html | text | optional HTML fragment |
| attrs | any | optional attrs |
| remove | bool | remove node |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | patch descriptor |
*> client_mod.dom_patch sel=`sel` html=`html` attrs=`attrs` remove=`remove`*
## make_style
@@ -120,7 +272,19 @@ Scan `root/**/*.mq.md` for `type: web|endpoint` (ZH `类型: 网页|端点`), re
+ `table`
+ `strict`=False
Style table → CSS (data, not hidden page DSL).
Compile a named style table into CSS. Styles remain data next to content; this
is not a hidden page DSL. Prefer referencing style names from View style columns
after file-partitioned components define their look.
| 参数 | 类型 | 说明 |
|------|------|------|
| name | text | style name |
| table | any | property table |
| strict | bool | strict mode |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | CSS / style handle |
> cap.load
*> web_style name=`name` table=`table` strict=`strict`*
@@ -128,12 +292,34 @@ Style table → CSS (data, not hidden page DSL).
## make_images
+ `table`
Build image descriptors from a readable table of sources and alts. Keep media
declarations in Markdown tables beside the Document that uses them.
| 参数 | 类型 | 说明 |
|------|------|------|
| table | any | images table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | images payload |
> cap.load
*> web_images table=`table`*
## make_head
+ `table`
Build head resource rows (link, script, icon) from a table. Prefer declaring
head needs as data rather than injecting opaque HTML head strings.
| 参数 | 类型 | 说明 |
|------|------|------|
| table | any | head table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | head payload |
> cap.load
*> web_head table=`table`*
@@ -148,7 +334,13 @@ Style table → CSS (data, not hidden page DSL).
+ `layout`=None
+ `asset_version`=None
Low-level app handle for advanced mounts. Prefer `web.serve` for Artifact sites.
Low-level app handle for advanced mounts. Prefer web.serve for Artifact sites
that already follow file-partition layout. Optional page, db, host, port, admin
flags, shell_css, layout, and asset_version configure the runtime without a
configure junk drawer of unrelated kwargs. Authors who need only Document
discovery should stay on serve; agents should not invent HTML shells on this
object. Methods static, listen, and gate hang off the returned handle for
mounts that remain table- and Metadata-driven.
> cap.load
*> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port` admin_prefix=`admin_prefix` login_redirect=None logout_redirect=None shell_css=`shell_css` layout=`layout` asset_version=`asset_version`*
@@ -157,10 +349,30 @@ Low-level app handle for advanced mounts. Prefer `web.serve` for Artifact sites.
+ `dir`
+ `mount`=/static
Mount static files from dir at mount path on this app. Use for bridge scripts and
assets referenced by Documents — not for dumping an HTML-only site tree that
bypasses Artifact Documents.
| 参数 | 类型 | 说明 |
|------|------|------|
| dir | text | filesystem directory |
| mount | text | URL mount |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
*> web_app_static app=`self` dir=`dir` mount=`mount`*
## listen
Start listening with the already configured app host and port. Prefer serve for
root scanning; listen is for advanced app handles after manual route setup.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | listen result |
*> web_listen app=`self`*
## gate
@@ -171,4 +383,21 @@ Low-level app handle for advanced mounts. Prefer `web.serve` for Artifact sites.
+ `on_deny`=forbid
+ `exclude`=None
Attach an authorization gate on path for this app. roles, permissions, match,
on_deny, and exclude document who may enter. Auth resources live in ext/security;
this method only wires the gate onto the web app surface.
| 参数 | 类型 | 说明 |
|------|------|------|
| path | text | gated path |
| roles | any | roles |
| permissions | text | permissions |
| match | text | match mode |
| on_deny | text | deny behavior |
| exclude | any | exclusions |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
*> web_app_gate app=`self` path=`path` roles=`roles` permissions=`permissions` match=`match` on_deny=`on_deny` exclude=`exclude`*
+82
View File
@@ -0,0 +1,82 @@
---
markup: occlusion
title: ext/web/布局
description: >-
Web 布局工程 skill — 用文件划分布局,拆到简单为止。只用 View 表;HTML/CSS 注入是逃逸舱。
import:
layout: ext/web/layout/index.mq.md
component: ext/web/component.mq.md
---
布局决定 Marqdo 网站是否可维护。首页不是一整块 HTML,而是目录上的 Document 与
组件文件:导航、侧栏、主区、底栏。若某一区仍复杂(例如底栏双栏品牌+链接),继续
拆文件,直到每个文件单一职责、一张 View 表或短 Markdown。值、库字段、具名样式
只通过 `|类型|槽|值|属性|样式|`(或英列名)绑定。不要用 `dom.raw` 或大段 CSS
「先做完」——那会绕过绑定,事后不可读。
设计正文:`doc/design/ext-web-layout-paradigm.md`。
## 给智能体
若你只拿到本文件,写站前先拉取规则。布局规则工具本身是纯函数,可不加
`--effects plugin`;后续渲染/服务必须加。
调用示例(纯文本):
marqdo call ext/web/布局/索引.mq.md 规则 --json
marqdo call ext/web/布局/索引.mq.md 视图契约 --json
撰写时先建 `components/*.mq.md`(可再嵌套),再写瘦的 `类型: 网页` 页面声明路由
与主区意图。用合并节点拼接 View。禁止把 `dom.raw` 当作首页主实现。
*None*
## 规则
返回布局工程规则映射,供智能体与验收清单使用。无参数。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 规则表 |
*> layout.rules*
## 视图契约
返回唯一允许的 View 列名(英文)。中文别名为 `类型|槽|值|属性|样式`。无参数。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 列名列表 |
*> layout.view_schema*
## 合并节点
拼接 View 节点表 `甲` 与 `乙`。区域拆文件后,用本工具组装而不写 HTML。
| 参数 | 类型 | 说明 |
|------|------|------|
| 甲 | any | 第一张 View 表 |
| 乙 | any | 第二张 View 表 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 合并后的节点 |
*> layout.merge_nodes a=`甲` b=`乙`*
## 验收组件
文档门:传入组件 `名`(文件名)与单一职责 `职责`(一句话)。返回验收行,提醒
必须保持单一职责。不写磁盘。
| 参数 | 类型 | 说明 |
|------|------|------|
| 名 | text | 组件名,如 导航 |
| 职责 | text | 单一职责描述 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 验收行 |
*> layout.accept_component name=`名` duty=`职责`*
+159 -2
View File
@@ -2,12 +2,69 @@
markup: occlusion
title: ext/web/网页
description: >-
Web Artifact 中文 facade(ADR 0007)— 页面 · 路由 · 服务 · 渲染 · 检视 · 使用。
禁止 compose_* / configure / 作者侧确保插件。
Web Artifact 中文根 skill(ADR 0007)— 文件划分布局;页面 · 路由 · 服务 · 渲染 · 检视。
禁止 compose_* / configure / 作者侧确保插件;禁止默认 HTML/CSS 注入。
import:
web: ext/web/web.mq.md
布局: ext/web/布局/索引.mq.md
---
本文件是 Marqdo 网络(web)扩展的中文根 skill。若你是没有其它上下文的智能体,
请先读「选哪条路」与「布局铁律」,再按 call 形状执行。不要发明 MCP、整页 HTML
或第二套 API。`##` 标题就是工具。
## 选哪条路
只选一行。不要混用中英工具名。
| 若你需要 | 这样做 |
|----------|--------|
| 写站前的布局规则 | 调用本包 `布局.规则`(或 `ext/web/布局/索引.mq.md` 的 `规则`) |
| 预览 Document / View | `渲染`,加 `--effects plugin` |
| 启动站点 | 作者程序 `服务`,或 call `服务` 并传 `根=` · `端口=` |
| 英文工具名 | 改开 `ext/web/index.mq.md`,留在英文树 |
智能体默认 `##` + `marqdo call`。`# page` 等对象给作者程序。`dom.raw` /
`page.css` 不是首页默认做法。
*None*
## 布局铁律
网页靠文件划分建造,不靠注入 HTML。首页拆成导航、侧栏、主区、底栏等文件。某一
区仍复杂(双栏底栏、密样式)时再拆,直到每文件单一职责、一张 View 或短
Markdown。值、库与具名样式只走统一 View 列(类型、槽、值、属性、样式,或英列
名)。默认禁止整页 HTML 字符串、CSS 注入袋、compose 碎片与 json.set 拼 DOM。
逃逸舱仅限 dom.raw / page.css,且必须写明为何不能表驱动。
详见 doc/design/ext-web-layout-paradigm.md。包内工具:ext/web/布局/索引.mq.md。
调用示例(纯文本):
marqdo call ext/web/布局/索引.mq.md 规则 --json
marqdo call ext/web/网页.mq.md 布局规则 --json
*None*
## 如何执行任意工具
调用示例(纯文本):
marqdo call FILE FUNCTION 名=值 --effects plugin --json
FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`。布局规则类
工具可纯 call。不要调用 `确保插件` 或 `host_*`。
*None*
## 布局规则
与 `布局.规则` 相同,便于只打开本文件的智能体。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 布局规则映射 |
*> 布局.规则*
## 页面
+ `标题`=""
+ `路由`="/"
@@ -18,6 +75,24 @@ import:
+ `排序`=""
+ `条件`=""
构造 Document 句柄。站点页面优先用 `类型: 网页` Artifact,由 `服务` 发现;本工具
供预览或程序化构造。节点必须是统一 View 表,不是 HTML。
| 参数 | 类型 | 说明 |
|------|------|------|
| 标题 | text | 文档标题 |
| 路由 | text | 路径 |
| 方法 | text | HTTP 方法 |
| 正文 | text | Markdown 正文 |
| 节点 | any | View 表或 None |
| 数据源 | text | 表名 |
| 排序 | text | 如 -created_at |
| 条件 | text | col=val 列表 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 页面句柄 |
*> web.page title=`标题` route=`路由` method=`方法` body=`正文` nodes=`节点` data_source=`数据源` data_order=`排序` data_where=`条件`*
## 路由
@@ -30,6 +105,23 @@ import:
+ `响应`="json"
+ `鉴权`=""
注册已声明的 Document 或 Endpoint。不要隐式注册用户路由。
| 参数 | 类型 | 说明 |
|------|------|------|
| 应用 | any | 应用句柄 |
| 路径 | text | URL 路径 |
| 方法 | text | HTTP 方法 |
| 页面 | any | Document 或 None |
| 函数 | text | Endpoint lib.member |
| 请求 | text | 请求体类型 |
| 响应 | text | 响应类型 |
| 鉴权 | text | 鉴权标签 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 路由结果 |
*> web.route app=`应用` path=`路径` method=`方法` page=`页面` fn=`函数` request=`请求` response=`响应` auth=`鉴权`*
## 渲染
@@ -39,17 +131,53 @@ import:
+ `标题`=""
+ `数据库`=None
把 Document 或 View 节点渲染为 HTML(预览)。输入应来自 Markdown/View,而不是
手写 HTML 大字符串。
| 参数 | 类型 | 说明 |
|------|------|------|
| 文档 | any | Document 或 None |
| 节点 | any | View 表或 None |
| 正文 | text | Markdown |
| 标题 | text | 标题 |
| 数据库 | any | 可选 db |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML 或渲染结果 |
*> web.render doc=`文档` nodes=`节点` body=`正文` title=`标题` db=`数据库`*
## 使用
+ `应用`
+ `中间件`
一等中间件(表驱动)。禁止 `configure(...)` 垃圾抽屉。
| 参数 | 类型 | 说明 |
|------|------|------|
| 应用 | any | 应用句柄 |
| 中间件 | any | 中间件表 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 应用句柄 |
*> web.use app=`应用` middleware=`中间件`*
## 检视
+ `应用`=None
返回 `{declared, system}` 路由表。
| 参数 | 类型 | 说明 |
|------|------|------|
| 应用 | any | 应用或 None |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 路由检视 |
*> web.inspect app=`应用`*
## 服务
@@ -60,6 +188,22 @@ import:
+ `静态目录`=""
+ `中间件`=None
扫描 `根/**/*.mq.md` 中 `类型: 网页|端点`,注册声明路由并监听。站点目录应已按
布局铁律拆好组件文件。
| 参数 | 类型 | 说明 |
|------|------|------|
| 根 | text | 站点根目录 |
| 主机 | text | 绑定主机 |
| 端口 | number | 端口 |
| 数据库 | any | 可选 db |
| 静态目录 | text | 静态资源 |
| 中间件 | any | 可选中间件 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 服务结果 |
*> web.serve root=`根` host=`主机` port=`端口` db=`数据库` static_dir=`静态目录` middleware=`中间件`*
## 客户端挂载
@@ -68,4 +212,17 @@ import:
+ `源`=""
+ `启动`=True
嵌入 WASM 桥。不是用 HTML 字符串拼整页的借口。
| 参数 | 类型 | 说明 |
|------|------|------|
| 桥 | text | bridge 脚本路径 |
| wasm | text | wasm 路径 |
| 源 | text | 可选源 |
| 启动 | bool | 是否自动 boot |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 挂载描述 |
*> web.client_embed bridge=`桥` wasm=`wasm` source=`源` boot=`启动`*
+4 -2
View File
@@ -186,8 +186,10 @@ Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifa
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
- EN: `import web:ext/web/web.mq.md`
- ZH: `导入 网页:ext/web/网页.mq.md`
- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页.mq.md`](../../ext/web/网页.mq.md)
- **Layout law (in-package):** file-partition pages (nav/sidebar/footer/…) until simple; no HTML/CSS injection as default — [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) · [ext-web-layout-paradigm.md](../../doc/design/ext-web-layout-paradigm.md)
- EN author facade: `import web:ext/web/web.mq.md`
- Agent: `marqdo call ext/web/layout/index.mq.md rules --json` then facade tools with `--effects plugin`
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
+14 -2
View File
@@ -37,8 +37,20 @@ pub const CATALOG: &[ExtPackage] = &[
},
ExtPackage {
id: "web",
description: "Dynamic website toolkit (ext/web) — Go libweb (page/db/bind/admin)",
mq_files: &["web/web.mq.md", "web/网页.mq.md"],
description: "Dynamic website toolkit (ext/web) — Document/Endpoint + layout skill",
mq_files: &[
"web/index.mq.md",
"web/web.mq.md",
"web/网页.mq.md",
"web/_capability.mq.md",
"web/page.mq.md",
"web/route.mq.md",
"web/component.mq.md",
"web/dom.mq.md",
"web/client.mq.md",
"web/layout/index.mq.md",
"web/布局/索引.mq.md",
],
native_crate: Some("marqdo_plugin_web"),
},
ExtPackage {
+23
View File
@@ -243,6 +243,29 @@ fn plugin_effects_flag_allows_quantum_ensure() {
assert_eq!(body["ok"], true, "{body}");
}
#[test]
fn web_layout_rules_via_call() {
let file = root().join("ext/web/layout/index.mq.md");
let out = run(&["call", "--json", file.to_str().unwrap(), "rules"]);
assert_eq!(out.status.code(), Some(0), "{}", text(&out.stdout));
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap();
assert_eq!(body["ok"], true, "{body}");
let keys = body["result"]["key"].as_array().expect("key list");
assert!(
keys.iter().any(|k| k.as_str() == Some("paradigm")),
"{body}"
);
}
#[test]
fn web_zh_layout_rules_via_call() {
let file = root().join("ext/web/网页.mq.md");
let out = run(&["call", "--json", file.to_str().unwrap(), "布局规则"]);
assert_eq!(out.status.code(), Some(0), "{}", text(&out.stdout));
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap();
assert_eq!(body["ok"], true, "{body}");
}
#[test]
fn quantum_index_bell_via_call() {
let file = root().join("ext/quantum/index.mq.md");