feat(view): show inferred param values; migrate welcome to v0.3 prose

Param chips carry call-frame values (and refresh with the call picker).
Welcome pages and the marqdo skill prefer body-inferred, conversational markup.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-10-15 14:32:50 +08:00
1 parent 7d49c358c1
commit f99d552d87
6 files changed
+124 -53

No files matched your search

+6 -8
View File
@@ -138,20 +138,19 @@ Chinese builtins (same functions, no import):
## Functions, calls, end-body
Prefer **body-inferred params** and **prose-unified** wording (v0.3). `` + `name` `` still works, but teach the inferred form first:
```markdown
# main
> greet who=Marqdo
**greet who="Marqdo"**
## greet
+ `who`
> print text=Hello, `who`!
*None*
When we meet`who`, we **print text="Hello, `who`!"** and close with*None*.
```
- Call: `> name key=value` or `> name value`.
- Call: `**fn key="text"**` (bold; quote text literals) or `> fn key=text` (standalone `>`; bare words are text).
- Nested helpers use deeper `#` (`##`, `###`, …).
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
@@ -163,9 +162,8 @@ Chinese builtins (same functions, no import):
**y = x + 2**
## add_one
+ `n`
*n + 1*
For input`n`, do **n = n + 1** and return*n*.
```
```markdown
+8 -19
View File
@@ -7,7 +7,7 @@ import foreign:lib/foreign.mq.md
# main
Hello — and welcome. I built Marqdo so that *code is documentation and documentation is code*: Markdown markers are the program structure, so what you read is what runs.
Hello — and welcome. I built Marqdo so that code is documentation and documentation is code: Markdown markers are the program structure, so what you read is what runs.
AI systems already favor Markdown-shaped output. That raised a simple question: why keep docs and programs as two separate artifacts? Marqdo is the answer. The `.mq.md` suffix exists so a file stays renderable as Markdown while remaining executable. Richer OKF-style YAML catalogs and even slide decks are on the roadmap; for now this site itself is generated by Marqdo — and that often saves tokens when an AI is writing with you.
@@ -15,44 +15,33 @@ The language is still early: structural markers, English/Chinese builtin aliases
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
A small function to say hello (calls in entry `# main` actually run; `##` children are methods and do not auto-run):
Want a quick hello? Calls only run when they sit in the entry `# main` — `##` children are methods until something calls them. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**.
> greet who=marqdo
Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.
Named args can include spaces:
> greet who=marqdo user
Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more.
Math and foreign deserve a special mention. With the math library you can bind a formula like this:
Bind a formula to `f` like this:
`f` =
$$
x^2 - 2
$$
Then plot it:
Then plot it: **_svg = math.plot formula=`f` var="x" min=-3 max=3**
**`_svg` = > math.plot formula=`f` var="x" min=-3 max=3**
The foreign library lets you call external code, for example:
Foreign lets you embed another language. Bind `hi` to a small Python block:
`hi` =
```python
print("hello-from-python")
```
Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code.
Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.
Welcome again — enjoy exploring Marqdo.
## greet
+ `who`
> print text=Welcome, `who`!
*None*
When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*.
## install
+11 -23
View File
@@ -7,53 +7,41 @@ description: 用户文档首页 — 代码即文档(中文版)
# main
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门*代码即文档,文档即代码*的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,token烧的太多,钱包会可怜的饿瘦的。
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套?于是有了 marqdo。为了让文件既能当文档渲染又能执行,后缀定为 `.mq.md`。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT;眼下它至少已经是个不错的博客工具——对,这个站点就是 Marqdo 生成的。AI 写 `.mq.md` 时往往更省 token,钱包也会轻松一点。
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
English docs: [`00-welcome.mq.md`](00-welcome.mq.md)(English prose and English builtins).
用一个小函数打个招呼(入口 `# main` 里的调用会真正执行;`##` 子标题是方法,不会自动跑):
想先打个招呼?调用写在入口 `# main` 里才会真的跑——子标题里的方法要等你叫到它。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
> 问候 谁=marqdo
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
具名实参可以带空格:
> 问候 谁=marqdo user
除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。
其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用:
比方说,先给公式起个名字`f`:
`f` =
$$
x^2 - 2
$$
之后让我们画个图像吧!
接着画出来:**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3**
**`_svg` = > 数学.绘图 formula=`f` var="x" min=-3 max=3**
外联库则允许你调用外部代码,例如:
外联则允许嵌一段别的语言。把`hi`绑成下面这样即可:
`hi` =
```python
print("hello-from-python")
```
这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档,
文档即代码。
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
最后,再次欢迎你,尽情体验marqdo吧!
最后,再次欢迎你,尽情体验 marqdo 吧!
## 问候
+ `谁`
> 打印 内容=欢迎,`谁`!
*None*
见到访客`谁`时,我们 **打印 内容="欢迎,`谁`!"**,然后收束为*None*。
## 安装
+53 -1
View File
@@ -633,6 +633,11 @@ fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String {
}
s.push_str("</div>");
if !fun.params.is_empty() {
// Default SSR values = last call frame (matches picker default = last option).
let default_args = call_labels
.last()
.map(|a| parse_args_brief(&a.value))
.unwrap_or_default();
s.push_str(r#"<div class="params">"#);
for p in &fun.params {
let cls = if p.inferred {
@@ -645,11 +650,19 @@ fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String {
} else {
"explicit + param"
};
let val = default_args
.get(p.name.as_str())
.filter(|v| !v.is_empty())
.map(|v| format!("={}", escape(v)))
.unwrap_or_default();
// Always emit chip-val so call-picker JS can refresh per frame.
s.push_str(&format!(
r#"<span class="{cls}" title="{title}">{name}</span>"#,
r#"<span class="{cls}" data-param-name="{name}" data-fn="{fn}" title="{title}">{name}<span class="chip-val">{val}</span></span>"#,
cls = cls,
title = title,
name = escape(&p.name),
fn = escape(&fun.name),
val = val,
));
}
s.push_str("</div>");
@@ -658,6 +671,22 @@ fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String {
s
}
/// Parse `args_brief` (`谁=marqdo, n=37`) into name → value.
fn parse_args_brief(brief: &str) -> HashMap<String, String> {
let mut m = HashMap::new();
if brief.trim().is_empty() {
return m;
}
for part in brief.split(", ") {
if let Some((k, v)) = part.split_once('=') {
if !k.is_empty() {
m.insert(k.to_string(), v.to_string());
}
}
}
m
}
fn render_line_block(
line_no: u32,
text: &str,
@@ -1163,6 +1192,29 @@ mod tests {
);
}
#[test]
fn inferred_param_chip_shows_call_value() {
let src = include_str!("../../tests/markup-v03/inc-prose.mq.md");
let module = crate::parse::parse_source(src).unwrap();
let add = module
.functions
.iter()
.find(|f| f.name == "加一函数")
.expect("加一函数");
assert!(add.params.iter().any(|p| p.name == "n" && p.inferred));
let cap = crate::run_source(src, &crate::RunOptions::default()).unwrap();
let annots = build_view_annots(&module, src, &cap);
let html = render_module_document(&module, src, &annots);
assert!(
html.contains(r#"data-param-name="n""#) && html.contains("chip inferred"),
"inferred param chip missing: {html}"
);
assert!(
html.contains(r#"class="chip-val">=37"#) || html.contains("chip-val\">=37"),
"expected param chip value from call frame: {html}"
);
}
#[test]
fn document_frame_pickers_and_all_arms() {
let src = include_str!("../../tests/view/document-annot-demo.mq.md");
+42
View File
@@ -593,6 +593,15 @@ ul.doc-loop, ol.doc-branch {
font-size: 0.65em;
opacity: 0.7;
}
.chip .chip-val {
font-weight: 500;
opacity: 0.78;
font-family: var(--mono);
font-size: 0.92em;
}
.chip .chip-val:empty {
display: none;
}
.nested {
margin: 0.45rem 0 0.15rem 0.15rem;
padding-left: 0.85rem;
@@ -2185,11 +2194,43 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
try {{ return JSON.parse(el.textContent || "{{}}"); }} catch (e) {{ return null; }}
}}
function parseArgsBrief(brief) {{
var out = {{}};
if (!brief) return out;
String(brief).split(", ").forEach(function (part) {{
var i = part.indexOf("=");
if (i <= 0) return;
out[part.slice(0, i)] = part.slice(i + 1);
}});
return out;
}}
function applyParamChipValues(fnName, callId, trace) {{
if (!trace || !Array.isArray(trace.calls)) return;
var brief = "";
for (var i = 0; i < trace.calls.length; i++) {{
var c = trace.calls[i];
if (String(c.call_id) === String(callId) && String(c.fn || "") === String(fnName)) {{
brief = c.args_brief || "";
break;
}}
}}
var args = parseArgsBrief(brief);
document.querySelectorAll('.chip[data-fn="' + fnName + '"][data-param-name]').forEach(function (chip) {{
var name = chip.getAttribute("data-param-name") || "";
var slot = chip.querySelector(".chip-val");
if (!slot) return;
var v = args[name];
slot.textContent = v ? ("=" + v) : "";
}});
}}
/** Source structure always stays visible; only chips + arm classes follow the frame. */
function initCallPickers() {{
document.querySelectorAll(".call-picker").forEach(function (sel) {{
function apply() {{
var callId = String(sel.value || "");
var fnName = String(sel.getAttribute("data-fn") || "");
var allowed = {{}};
Array.prototype.forEach.call(sel.options, function (o) {{
allowed[String(o.value)] = true;
@@ -2202,6 +2243,7 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
chip.hidden = cid !== callId;
}});
var trace = readViewTrace();
applyParamChipValues(fnName, callId, trace);
if (trace && Array.isArray(trace.events)) {{
var takenByLine = {{}};
trace.events.forEach(function (ev) {{
+4 -2
View File
@@ -971,10 +971,11 @@ fn render_fun(
("chip", "explicit + param")
};
s.push_str(&format!(
"<span class=\"{cls}\" title=\"{title}\">{name}</span>",
"<span class=\"{cls}\" data-param-name=\"{name}\" data-fn=\"{fn}\" title=\"{title}\">{name}<span class=\"chip-val\"></span></span>",
cls = cls,
title = title,
name = escape(&p.name),
fn = escape(&fun.name),
));
}
s.push_str("</div>");
@@ -1750,7 +1751,8 @@ mod tests {
assert!(add.params.iter().any(|p| p.name == "n" && p.inferred));
let html = render_module_structure(&module, src);
assert!(
html.contains("chip inferred") && html.contains(">n<"),
html.contains("chip inferred")
&& (html.contains(">n<") || html.contains(r#"data-param-name="n""#)),
"expected inferred chip for n: {html}"
);
let outline = render_function_outline(&module);