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:
1 parent
24dcb97354
commit
bb06dad134
17 files changed
+1065
-41
No files matched your search
@@ -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/).
|
||||
|
||||
|
||||
@@ -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,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,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` 仅逃逸舱) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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"))**
|
||||
|
||||
@@ -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*
|
||||
@@ -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
@@ -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
@@ -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`*
|
||||
@@ -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
@@ -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=`启动`*
|
||||
@@ -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
@@ -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 {
|
||||
|
||||
@@ -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");
|
||||
|
||||
Reference in new issue
Block a user