diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md
index 44fe326..8b0f024 100644
--- a/.cursor/skills/marqdo/SKILL.md
+++ b/.cursor/skills/marqdo/SKILL.md
@@ -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`.
-- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页.mq.md`](../../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)(作者门面仍为 `网页.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)
+- **Recursive practice:** home → nav/main/footer → footer brand/links → links docs/community; continue until a leaf is plain Markdown. Parents import children and declare one relationship. Use `component.markdown`, `component.wrap`, `layout.stack`, and `layout.columns`; merge alone gives siblings, not columns.
+- **Runnable reference:** [web-layout-handbook](../../../examples/web-layout-handbook/index.mq.md) and [Chinese reference](../../../examples/web-layout-handbook-zh/index.mq.md). A composed Document declares `view: main` and returns node rows at startup; ordinary Documents keep their Markdown/data-source path. Use `inspect root=...` for disk routes, and `run` for a live server.
- 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`
diff --git a/.cursor/skills/marqdo/reference.md b/.cursor/skills/marqdo/reference.md
index cae83c6..6481ab8 100644
--- a/.cursor/skills/marqdo/reference.md
+++ b/.cursor/skills/marqdo/reference.md
@@ -55,7 +55,7 @@ Import one file; use **that** file’s function names.
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
-| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
+| `ext/web/index.mq.md` · `web.mq.md` | `ext/web/网页/索引.mq.md` · `网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/quantum/index.mq.md` + modules | `ext/quantum/量子/索引.mq.md` + modules | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
@@ -64,6 +64,14 @@ Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names
Install: `marqdo ext add web` (`网页`). Native: `bash scripts/build-web-plugin.sh`.
+Layout practice: split home into nav/main/footer; split footer into brand/links,
+then links into docs/community until content leaves are ordinary Markdown.
+Use `component.markdown|wrap`, `layout.stack|columns`, and @ record lists.
+A parent value holds child rows of the same five-column View schema.
+Explicit `view: main` Documents assemble once at startup; `inspect root=...`
+scans disk declarations. See the Web root handbook and reference layout site.
+
+
| EN import | ZH import | Surface |
|-----------|-----------|---------|
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | facade: `page` · `route` · `serve` · `render` · `inspect` · `use` |
diff --git a/doc/design/ext-skill-tools-paradigm.md b/doc/design/ext-skill-tools-paradigm.md
index eae482e..e9d6482 100644
--- a/doc/design/ext-skill-tools-paradigm.md
+++ b/doc/design/ext-skill-tools-paradigm.md
@@ -210,7 +210,7 @@ Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08
## 13. 推广顺序(建议)
1. **已完成试点**:`ext/quantum/`(含 `量子/`)
-2. **进行中**:`ext/web/` — 根 `index` + `layout` 布局铁律(文件划分、反 HTML 注入)已入库;facade 路径保持兼容;模块叙述与 call 金样继续补齐
+2. **进行中**:`ext/web/` — 根 `index` + `layout` + 模块树 `page|route|…/index.mq.md` + 中文 `网页/`;作者门面 `web.mq.md`/`网页.mq.md` 保持兼容;call 金样与站点示例对齐继续补齐
3. **下一优先**:`linalg` 公式面、`ai` agent 面
4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade
@@ -223,4 +223,5 @@ Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08
| 日期 | 说明 |
|------|------|
+| 2026-11-06 | web:模块树 + `网页/` 镜像 + page session call 金样推进 |
| 2026-11-06 | 初版:由 quantum 试点归纳的整包开发范式与验收清单 |
diff --git a/doc/design/ext-web-artifact.md b/doc/design/ext-web-artifact.md
index f5a039a..01cb5f7 100644
--- a/doc/design/ext-web-artifact.md
+++ b/doc/design/ext-web-artifact.md
@@ -81,6 +81,7 @@ Welcome to the executable web.
| `type` | `类型` | `web` / `网页` |
| `route` | `路由` | 路径,可含 `{param}` |
| `method` | `方法` | 默认 `GET` |
+| `view` | `视图` | 可选 main:启动时执行主程序,返回递归 View 节点;不与自动 data_source 绑定混用 |
| `title` | `标题` | 文档标题 / `
` |
| `data_source` | `数据源` | 表名 |
| `data_order` | `排序` | 如 `-created_at` |
@@ -97,6 +98,8 @@ Welcome to the executable web.
| title | title | Marqdo | | title |
```
+2026-11-08:View 已支持 row/column 容器与 markdown 叶子,容器值保持子表;显式 `view: main` Document 通过普通函数装配。完整工程见[布局实践](ext-web-layout-paradigm.md),实现边界见[优化说明](ext-web-handbook.md)。
+
`page.render nodes=` 是**唯一**主装配路径。禁止 `compose_main` / `compose_intro` 等碎片 DSL。
---
diff --git a/doc/design/ext-web-handbook.md b/doc/design/ext-web-handbook.md
new file mode 100644
index 0000000..da7ec6c
--- /dev/null
+++ b/doc/design/ext-web-handbook.md
@@ -0,0 +1,71 @@
+# Web:可执行手册与递归布局工程
+
+| 项目 | 内容 |
+|------|------|
+| 日期 | 2026-11-08 |
+| 使用与开发入口 | [英文 index](../../ext/web/index.mq.md) · [中文索引](../../ext/web/网页/索引.mq.md) |
+| 工程规范 | [布局拆分](ext-web-layout-paradigm.md) |
+| 参考工程 | [英文](../../examples/web-layout-handbook/index.mq.md) · [中文](../../examples/web-layout-handbook-zh/index.mq.md) |
+| 自动验收 | [源手册与活站点](../../tests/web_handbook.rs) · [浏览器布局](../../tests/web/layout.browser.cjs) |
+| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) · [Quantum 优化](ext-quantum-handbook.md) |
+
+## 原有规范为什么没有落实
+
+原有 Web skill 已写「拆到简单」,但缺少可沿着文件树复现的工程。原生 `RenderNodes` 仅渲染平面 title/text/link/html;拼接两张表只产生兄弟节点,不会产生双栏。`serve` 又只把 Document 正文当 Markdown,没有执行文档里的组件装配。只加强口头禁止 HTML,无法补上这些实际缺口。
+
+本轮以一个完整首页检验规范:导航、主体、页脚分开;页脚拆品牌与链接;链接再拆文档与社区。所有末端 content.md 都是普通 Markdown。每个父 index.mq.md 只负责其下一层排列关系。
+
+## 使用同一份 View 表表示父与叶
+
+沿用 `type | slot | value | attrs | style`,不新增核心语法、不建立第二套布局方言:
+
+| 类型 | 值列 | 含义 |
+|------|------|------|
+| markdown / 正文 | Markdown 文本 | 内容叶子 |
+| row / 横排 | 子节点列表 | 响应式分栏 |
+| column / 纵排 | 子节点列表 | 上下排列 |
+| nav/header/footer/section/aside | 子节点列表 | 语义区域 |
+| 既有 title/text/link/html | 兼容原值 | 保留旧节点行为;html 为显式兼容边界 |
+
+纯 `component.markdown` / `正文` 与 `component.wrap` / `包裹` 构造节点,`layout.stack` / `纵排` 和 `layout.columns` / `分栏` 声明几何。`merge` 接受 @ 记录列表,确定兄弟顺序并保留嵌套值;不再声称它会自动归一化所有列式表或把平面表变成双栏。
+
+递归渲染保留节点类型,不把子表转成 `map[...]` 字符串。原生渲染器诊断无效子节点、列长不等和过深嵌套。运行时固定的布局样式提供基础响应式几何,样式列继续是类名引用,并非 CSS 编译器。叶子正文经过既有 Markdown 渲染器。
+
+## 显式 Document 装配
+
+普通 `type: web` 保留既有 Markdown/数据源路径。需要结构化页面时显式增加 `view: main`(中文 `视图: main`),普通 `# main` 返回 View 节点列表。`serve` 在启动时通过已有 `run_artifact` 回调执行装配,用与离线预览相同的渲染器生成文档,不再套入旧站点的另一份导航/页脚壳。
+
+这是启动时装配,修改内容后重启;不声称具备自动请求期模板绑定。装配函数不再次调用渲染器或启动服务器。请求期业务仍用 Endpoint。自动 `data_source` 绑定使用普通 Document;与 `view: main` 混用会明确报错,避免静默忽略数据源。
+
+`web.inspect root=...` / `网页.检视 根=...` 新增离线扫描入口,不启动进程也不执行组件。空应用的新进程无法读取另一个活进程的私有路由;手册不再将此作为活站点检视方法。检视结果加入 `_type: web_inspection`,使不同长度的 declared/system 列表保持对象语义,而不被 JSON 边界当作列式表。
+
+## 手册与工具一致
+
+另修复既有元数据型 Endpoint 在 Bytecode 没有函数时误报编译错误的问题:与 Tree 共用声明摘要路径,普通无入口程序仍然拒绝执行。
+
+全部 Web 模块清理说明性伪函数,参数和返回契约均放在执行前;对象 API 保留。纯 DOM 构造与客户端描述不再无故加载插件。命令示例保护文本引号与会话美元引用。布尔/数字默认值与相邻标点分开,保证真正省略参数时仍符合契约。
+
+原 `accept_component` 仅根据名称和职责就返回 ok=True,无法代表实际验收。现在返回明确的 checklist 状态,实际验收依据源码职责、渲染结构和运行结果。`site_playbook` 讲流程,`preview_markdown` / `preview_nodes` 给真实预览,不再把增加叙述字数当作完成指标。
+
+## 验证
+
+```bash
+bash scripts/build-web-plugin.sh
+cargo test --locked --test web_handbook
+cargo test --locked --test call_cli web_
+cargo test --locked --test gold ext_web -- --test-threads=1
+```
+
+手册门禁直接执行 18 份包内入口的双语 sh 围栏,在 Tree/Bytecode 共执行 80 次命令;同样执行根手册的作者程序。参考工程的双语双后端检查实际预览、启动服务,核对首页与预览相同、关于页仍走普通 Document、API 正常返回 JSON;不把路由声明误当作已经监听。
+
+浏览器检查可对参考预览或活站点执行,按环境指定现有 Playwright 模块和 Chromium:
+
+```bash
+node tests/web/layout.browser.cjs /absolute/path/to/preview.html
+```
+
+它测量 1440px 下的外层与内层双栏、390px 下的两层纵向折叠,并检查无横向溢出。无需外部资源或业务 JavaScript。Go 单元测试覆盖递归 Markdown、顺序、带类型列式表、错误形状与 Document 显式执行边界。
+
+既有 Anlian 渲染测试已从硬编码个人数据库改为临时目录建表并注入已知数据,使完整 Go 套件无需个人站点状态。
+
+全库 Rust 库级回归为 436 通过、25 失败,失败集中于外联内核与验证策略/回放;在隔离源码副本还原本轮三个核心文件后,失败集合完全一致,没有新增失败。Web 专项、全部 Web Go 测试、浏览器几何与 Quantum 手册回归通过。本轮没有把这些既有策略/回放失败混入布局修复。
diff --git a/doc/design/ext-web-layout-paradigm.md b/doc/design/ext-web-layout-paradigm.md
index 953e9eb..27122ab 100644
--- a/doc/design/ext-web-layout-paradigm.md
+++ b/doc/design/ext-web-layout-paradigm.md
@@ -1,124 +1,65 @@
-# Web 布局工程范式:文件划分 · 直到简单 · 禁止注入
+# Web 布局工程:先拆布局,直到 Markdown 叶子
-| | |
-|---|---|
-| 状态 | **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 冲突;回归神对象 |
-| 样式写进巨大 ``)
+ if err := renderNodes(&b, nodes, 0); err != nil {
+ return "", err
+ }
+ b.WriteString(`
`)
+ return b.String(), nil
+}
+
+// Fixed runtime geometry, shared by offline previews and served Documents.
+// Authors choose row/column instead of embedding CSS or HTML in content cells.
+const LayoutCSS = `.mq-view{max-width:72rem;margin:auto;padding:1.5rem;line-height:1.6;font-family:system-ui,sans-serif}.mq-view *{box-sizing:border-box}.mq-view .mq-row{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,16rem),1fr));gap:1.5rem}.mq-view .mq-column{display:flex;flex-direction:column;gap:1.5rem}.mq-view .mq-node{min-width:0}.mq-view nav,.mq-view footer{padding-block:1rem}.mq-view footer{border-top:1px solid #d5dce5}.mq-view a{color:#2457a7}.mq-view img{max-width:100%;height:auto}.mq-view pre{overflow:auto}`
+
+// Preserve typed value cells when normalizing column tables. General AsRows
+// treats @ cells as text, which would stringify nested component tables.
+func viewRows(nodes any) ([]any, error) {
+ switch v := nodes.(type) {
+ case nil:
+ return nil, nil
+ case []any:
+ return v, nil
+ case map[string]any:
+ if _, ok := v["type"].(string); ok {
+ return []any{v}, nil
+ }
+ if _, ok := v["类型"].(string); ok {
+ return []any{v}, nil
+ }
+ n := -1
+ for _, cell := range v {
+ col, ok := cell.([]any)
+ if !ok {
+ return nil, fmt.Errorf("View: expected a row or column table")
+ }
+ if n < 0 {
+ n = len(col)
+ } else if n != len(col) {
+ return nil, fmt.Errorf("View: column lengths differ")
+ }
+ }
+ rows := []any{}
+ for i := 0; i < n; i++ {
+ row := map[string]any{}
+ for key, cell := range v {
+ row[key] = cell.([]any)[i]
+ }
+ rows = append(rows, row)
+ }
+ return rows, nil
+ default:
+ return nil, fmt.Errorf("View: expected rows, got %T", nodes)
+ }
+}
+
+func renderNodes(b *strings.Builder, nodes any, depth int) error {
+ if depth > 64 {
+ return fmt.Errorf("View: nesting exceeds 64 levels")
+ }
+ rows, err := viewRows(nodes)
+ if err != nil {
+ return err
+ }
+ for i, item := range rows {
row, ok := item.(map[string]any)
if !ok {
- continue
+ return fmt.Errorf("View row %d: expected a map", i+1)
}
- ty := first(row, "type", "类型")
+ ty := strings.ToLower(first(row, "type", "类型"))
slot := first(row, "slot", "槽")
val := first(row, "value", "值")
attrs := first(row, "attrs", "属性")
@@ -116,23 +173,92 @@ func RenderNodes(nodes any) (string, error) {
if slot != "" {
class += " slot-" + html.EscapeString(slot)
}
- switch strings.ToLower(ty) {
+ tag := ""
+ switch ty {
+ case "row", "横排":
+ tag = "div"
+ class += " mq-row"
+ case "column", "纵排":
+ tag = "div"
+ class += " mq-column"
+ case "nav", "导航":
+ tag = "nav"
+ case "header", "页头":
+ tag = "header"
+ case "footer", "页脚":
+ tag = "footer"
+ case "section", "区域":
+ tag = "section"
+ case "aside", "侧栏":
+ tag = "aside"
+ }
+ if tag != "" {
+ children := row["value"]
+ if children == nil {
+ children = row["值"]
+ }
+ if children == nil {
+ return fmt.Errorf("View row %d (%s): missing child rows in value", i+1, ty)
+ }
+ b.WriteString(`<` + tag + ` class="` + class + `">`)
+ if err := renderNodes(b, children, depth+1); err != nil {
+ return fmt.Errorf("View %s/%s: %w", ty, slot, err)
+ }
+ b.WriteString(`` + tag + `>`)
+ continue
+ }
+ switch ty {
+ case "markdown", "正文":
+ b.WriteString(`` + render.MarkdownToHTML(val) + `
`)
case "title", "标题":
b.WriteString(`` + inline(val) + `
`)
case "link", "链接":
- href := attrs
- if href == "" {
- href = "#"
+ if attrs == "" {
+ attrs = "#"
}
- b.WriteString(`` + inline(val) + ``)
+ b.WriteString(`` + inline(val) + ``)
case "html", "原文":
b.WriteString(`` + val + `
`)
- default: // text
+ default:
+ value := row["value"]
+ if value == nil {
+ value = row["值"]
+ }
+ switch value.(type) {
+ case []any, map[string]any:
+ return fmt.Errorf("View row %d: unknown structural type %q", i+1, ty)
+ }
b.WriteString(`` + inline(val) + `
`)
}
}
- b.WriteString(``)
- return b.String(), nil
+ return nil
+}
+
+// RenderFile explicitly opts a Document into startup-time component assembly.
+// Documents without view: main retain their existing Markdown/data-source path.
+func RenderFile(f ArtifactFile, run func(string, map[string]any) (any, error)) (string, bool, error) {
+ view := metaString(f.Meta, "view", "视图")
+ if view == "" {
+ return MarkdownHTML(f.Body), false, nil
+ }
+ if view != "main" {
+ return "", false, fmt.Errorf("%s: view/视图 must be main", f.Rel)
+ }
+ if metaString(f.Meta, "data_source", "数据源") != "" {
+ return "", false, fmt.Errorf("%s: view main is startup assembly; use an ordinary Document for automatic data_source binding", f.Rel)
+ }
+ nodes, err := run(f.Path, nil)
+ if err != nil {
+ return "", false, fmt.Errorf("%s: view main: %w", f.Rel, err)
+ }
+ if nodes == nil {
+ return "", false, fmt.Errorf("%s: view main must return View rows", f.Rel)
+ }
+ html, err := RenderNodes(nodes)
+ if err != nil {
+ return "", false, fmt.Errorf("%s: %w", f.Rel, err)
+ }
+ return html, true, nil
}
func inline(s string) string {
@@ -159,7 +285,7 @@ func RenderHTMLPage(title, innerHTML string) string {
if t == "" {
t = "Marqdo"
}
- return "" + t +
+ return "" + t +
"" + innerHTML + ""
}
@@ -313,6 +439,7 @@ func InspectBag(app map[string]any, declared []ArtifactFile) map[string]any {
}
}
return map[string]any{
+ "_type": "web_inspection",
"declared": dec,
"system": SystemRoutes(),
}
diff --git a/plugins/web/internal/artifact/artifact_test.go b/plugins/web/internal/artifact/artifact_test.go
index ca1cf99..4a0e8d7 100644
--- a/plugins/web/internal/artifact/artifact_test.go
+++ b/plugins/web/internal/artifact/artifact_test.go
@@ -1,6 +1,9 @@
package artifact
-import "testing"
+import (
+ "strings"
+ "testing"
+)
func TestMetaType(t *testing.T) {
if MetaType(map[string]string{"type": "web"}) != "web" {
@@ -53,3 +56,89 @@ func contains(s, sub string) bool {
return false
})())
}
+
+func TestNestedLayoutKeepsMarkdownLeavesAndSiblingOrder(t *testing.T) {
+ leaf := func(slot, text string) any { return map[string]any{"type": "markdown", "slot": slot, "value": text} }
+ nodes := []any{map[string]any{"type": "footer", "value": []any{
+ map[string]any{"type": "row", "slot": "footer", "value": []any{
+ leaf("brand", "### Marqdo\n\nReadable **documents**."),
+ map[string]any{"类型": "横排", "槽": "links", "值": []any{
+ leaf("docs", "### Docs\n\n[Guide](/guide)"),
+ leaf("community", "### Community\n\n[About](/about)"),
+ }},
+ }},
+ }}}
+ got, err := RenderNodes(nodes)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, want := range []string{"