Skip to content
cflmyPublic

About

Marqdo — A Rust-based runtime for executable AI skills. Turn readable Markdown documents into verifiable, callable tools.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Marqdo — Your SKILL is now a TOOL.

Write it. Inspect it. Call it.

让 SKILL 真正成为工具:文档即知识,知识即可执行。

release Apache-2.0 Rust runtime Pure by default

Marqdo is a Rust-based, document-native runtime for executable AI skills and tools. Write human-readable prose, GFM tables, parameter contracts, and real functions in one .mq.md document. Call a function by its heading, inspect the implementation, and grant side effects explicitly.

Not a prompt wrapper. The document is interpreted as a program by Marqdo; its tool functions are not merely natural-language instructions.

56s film · Quickstart · Procurement demo · View · Guide · Website · Release notes

Marqdo 2.9.0 — Verified Knowledge Compiler

Knowledge statements and claims have stable addresses; verified pure contracts compose across static modules and produce independently replayable Lean certificates. Evidence distinguishes abstract model_proved from true runtime proved. Unsupported runtime effects and semantics are explicitly unverified. Proof scope and acceptance · Release notes.

One Markdown file. Three views. Real execution.

Watch Marqdo 2.7.1 — from Markdown to execution

▶ Watch the 56-second film · Bilingual captions · Reproducible video source

The point is not to invent a new document format. A .mq.md file uses Markdown headings, paragraphs and tables. Ordinary Markdown renderers still show a readable document. Marqdo adds explicit execution semantics and a View that can inspect functions, values and their relationships on the same document.

Three views, one source — source Markdown, rendered Markdown, executable View

Concept artwork showing the design principle: source → ordinary Markdown rendering → Marqdo View. Illustrative labels are not a live execution trace. The video includes a real View screenshot, a standard Markdown rendering produced from the actual procurement source, and a business example verified with the 2.7.1 CLI.

One .mq.md source, three ways to interact:

Source Standard Markdown Marqdo runtime + View
Edit the same Markdown text Read headings, prose and data tables Inspect the same document's calls, values and effects
No separate prompt or tool implementation specification needed Works as ordinary readable documentation Call named functions with marqdo call

Quickstart — one function, one command

Install the latest 2.9.0 CLI release for Windows or Linux, then run from this repository's root:

marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
# => 5

The function heading is the callable name. The function's explanation, parameters, return contract, and implementation live in the same source file. Use --json for machine-readable call results and diagnostics. No LLM key is needed for this quickstart.

A procurement skill with a ¥600 budget

Read the complete executable procurement document · How to run and verify the example

This is a seven-tool, offline demonstration. It knows the local supplier directory, queries a static price catalog, checks the budget, and conditionally creates a simulated work order. It also documents receipt handling, negotiation and supplier switching as unconnected stubs.

Animated results from real Marqdo 2.7.1 function calls

Real CLI results, edited into a short animation; the accepted order is explicitly simulated and never sent. Capture workflow · Passing checks.

# 1. Approve suppliers: paused or blacklisted entries are excluded.
marqdo call examples/procurement/index.mq.md 查询采购商 "采购商状态='正常'" --json

# 2. Quote: SUP_JN, 8 ball bearings × ¥36 = ¥288 (sample price).
marqdo call examples/procurement/index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" 数量=8 有效秒数=300 --json

# 3. Budget: ¥600 - ¥120 = ¥480.
marqdo call examples/procurement/index.mq.md 查询余额 已花费=120 --json

# 4. Recheck supplier, quote, delivery and budget before a local mock order.
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json

# 5. Over budget: ¥600 - ¥360 = ¥240 < ¥288. The mock work order must be denied.
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json
Case Budget check Expected business result
已花费=120 ¥480 available ≥ ¥288 ok: true, local simulation only, not sent
已花费=360 ¥240 available < ¥288 ok: false, budget denial
SUP_YY Supplier on blacklist Excluded from quote / order

Why this matters: The document doesn't merely tell an agent to obey a limit. The work-order function itself calls supplier validation, price lookup, and 查询余额 before returning an order record. Agent instructions and callable business logic can be inspected together.

Important limits: Price and supplier records are fixtures; 已花费 is caller supplied. No authoritative budget ledger, concurrent reservation, live supplier prices, ERP messaging, real receipt, or payment is implemented. A successful simulated order is not a real transaction. The demo is a testable starting point, not a financial safety guarantee.

Explore the View

Marqdo 2.7.1 improves the interactive reading experience: implementation details stay open when manually expanded, structured values are presented more clearly, and function/source links are easier to inspect. It does not introduce new language syntax or APIs.

marqdo view examples/procurement --no-open

Marqdo View — original detailed screenshot provided by the project author

Original View screenshot provided by the project author. Notice the natural document typography, values in the margins, and curved connections originating from function calls in the prose. Additional automated View capture · Static Markdown rendering.

One document, multiple uses

Prompt-oriented agent skill Marqdo executable skill
Natural-language tool instructions Natural-language guidance and executable functions
Description and code often separated Heading, parameter table, return table and implementation in one .mq.md
Validation may require separate wiring Named function calls can be checked, executed and tested
Prompts ask a model to comply Runtime permissions control declared effects of a function call
Hard to follow implementation through files View links readable content and implementation details

Agent Skills already support scripts; Marqdo's claim is one document-native language surface for authoring, inspecting, executing and reusing functions. This is not a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior.

Resources: Release v2.8.0 · Ext pack 2.8.1 · Procurement example · Executable library authoring · Function calling · Link syntax · Website


Deep dive · 语言、设计与执行系统

标准库单文件本身就是手册:直接阅读文件库、集合库等源码,按函数标题下的参数表、返回契约和动作说明调用;工程实践演示文件整理、CSV 汇总与文档维护。 开发标准库和拓展库请直接阅读可执行库开发指南:契约表、叙述式实现、遮蔽调用与多文件工程组织均有可运行示范。

当前 CLI 2.8.0 新增 marqdo prove:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见发布说明。

独立拓展包 2.8.1(CLI 仍为 2.8.0):ext/ai 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / inspect)。marqdo ext add agent → CDN latest。参见拓展包说明。

CLI 2.8.0 adds marqdo prove: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available.

Ext pack 2.8.1 (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and inspect.

核心优势:可执行知识(Executable Knowledge)

Knowledge That Can Run —— 知识即可执行。 Marqdo 不是「用 Markdown 写程序」这么简单:它让一个 .mq.md 文档同时是文稿、知识与程序——同一份结构,同时服务于人、解释器、工具与 AI。

         .mq.md(同一份文件)
        ┌─────────┼─────────┐
       文稿      知识       程序
        └─────────┼─────────┘
                  ▼
           Marqdo 运行时
                  ▼
        可执行知识(Executable Knowledge)
真正的核心优势 说明
知识-代码一致性
Knowledge-Code Coherence
说明、数据、示例与实现同一份源文件:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的知识不一致——知识陈述本身可以被测试。
函数即工具
marqdo call
最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 marqdo call 文件 函数 名字=值 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。
默认安全,AI 友好 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥不会污染文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。
multi-view artifact
.mq.md 双后缀即开放接口
.mq 告诉解释器「可执行」,.md 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。Marqdo 不占有知识,只是给 Markdown 增加执行语义。
表格即数据结构 程序的数据结构直接就是文档的数据结构:单列竖表 → List;横表(1 数据行)→ Map;横表(多数据行)→ Map of List(列向聚合);首列写 @ / 行 / row → 行向记录 List of Map。取元使用 access(集合, "键"),链接 [描述](表达式) 只承载叙述与执行体。这是 literate programming 的下一步。
语义干净 返回是架构,打印只是函数:*…* 改变控制流,print 只是副作用函数;分支与循环长在 Markdown 结构上(1. 2. 递增 = 分支,- = 循环),不是所有列表都被粗暴当成 if。
AI 的可靠上下文与长期记忆 一个 .mq.md 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的世界模型——比 RAG 更接近 Executable RAG。
链接即调用
Link as Call
文档里的 [描述](类.函数) 不是装饰,是跨文档类调用;编译器解析类/函数并返回 LinkInfo,view 显示调用点,EKC 建边,links.lock 可选复现。v2.1 已实现可执行知识基础设施。
完整工程,不是玩具 Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。

链接语法:链接即调用(v2.1 设计声明)

这是 v2.1 的可执行知识模型。 []() 不新增语法:[] 是 Markdown 链接的描述;() 是已有代码,与 **代码** 同权。 # 是类,## 是函数;类.函数 是类调用。 链接只是给这次调用一个名字;view 显示调用信息,编译器返回 LinkInfo,EKC 建边。

两文档,一次类调用

知识文档 libai.mq.md:

# 李白

这个文档存储了李白的信息。

## 李白的出生年份

*701*
  • # 李白 = 类;
  • ## 李白的出生年份 = 函数;
  • *701* = 返回值。

调用文档 main.mq.md:

# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)

[] 是描述,() 是已有调用 李白.李白的出生年份——类 李白 调用函数 李白的出生年份。 不需要 print:view 模式天然显示 () 的调用信息(类、函数、签名、值)。 要终端输出,就把同一段代码放进代码链接并加 print:

**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`

输出:701。

四条语义

  1. [] 永不执行:描述只给人读、给检索/诊断/展示用。
  2. () 与 **代码** 同权:同一套 parser/evaluator;类.函数 是类调用,obj.函数 是实例调用。
  3. # 是类,## 是函数:不使用 self/自 的函数是类函数,可直接 类.函数 调用;使用 self/自 的是实例函数。
  4. 链接 = 描述 + 调用:view 显示调用点;编译器返回 LinkInfo;EKC 建边;links.lock 可选复现。

现状与目标

能力 v2.0.0 v2.1
本地表达式链接(遮蔽) ✅ markup: occlusion ✅
() 与 **代码** 同权 ✅ 表达式/调用 ✅
类调用 类.函数 ❌ 需先构造实例 ✅ 直接调用
跨文档类索引 ❌ 需 import + 实例 ✅ 项目类索引
正文链接 view 信息 ❌ ✅ 目标/签名/值
LinkInfo / check ❌(check 只查契约) ✅ link.*
链接图边(EKC) ❌ ✅ calls / references
links.lock 可复现 ❌ ✅ 可选

知识分层:本体 → 知识个体 → 调用面

层 写法 语义
L1 本体 # 诗人 + 字段/类型表 类/模式
L2 知识个体 # 李白 = > 诗人 + ## 出生年份 + *701* 单体知识类(不是运行时实例)
L3 调用面 [出生年份](李白.出生年份) 类调用/链接

# 李白 = > 诗人 语法上是继承/特化,语义上是「李白是诗人」的知识个体; 运行时实例仍是 > 诗人 / > 李白。详见 knowledge-layers.md。

兼容迁移示例见 examples/link-syntax/main.compat.mq.md。

设计宪法:doc/design/link-syntax.md · 链接示例:examples/link-syntax/ · 知识分层示例:examples/knowledge-layers/ · 证据复核:occlusion-vs-executable-knowledge-2026-10.md


愿景与期许

不把「AI 能写 Marqdo」当终点,而是 「AI 能可靠地生成可验证的 Marqdo」:

  1. AI 可验证语言:LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
  2. Marqdo Schema / Language Server for AI:机器可读的语言 Schema(get_syntax / validate / repair …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
  3. 程序即 AI 长期记忆:.mq.md 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
  4. 链接即调用 / 可执行知识图:[描述](类.函数) 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;view 显示调用点;.mq.md 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
  5. 知识可测试:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
  6. 知识可证明:知识文件内的定理表 → Lean 4 定理 → 自动判定(marqdo prove);离线符号执行与 Lean 单调一致,分歧显式报错——Trusted Knowledge,判定器缺陷优先于任何绿灯。
  7. 可靠性基准:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。

为什么重要

痛点 Marqdo 的答案
文档过期、示例跑不通 一份源文件:叙述、结构与执行结果同源
知识散落在 Wiki / 注释 / 脚本里 .mq.md 即知识单元,可浏览、可运行、可检索
人写给人看,AI / 工具另起一套 人机同读同写同构:标记语言对人类友好,对解释器确定
大仓里「文档站」与「代码仓」脱节 view 文档站 + debug 调试面 + catalog 清单,同一棵树长大

这不是「再做一个 Markdown 渲染器」,而是:把文档升格为可解释的程序与可生长的知识库,让协作在大型项目里依然站得住。


语法速览

标记 含义
无标记行 叙述(注释);行内 `名` 可声明
**…** 代码(赋值 / 调用 / 表达式)
[描述](表达式) 链接(本地):描述 + 代码;() 与 **…** 同权(默认语义)
[描述](类.函数) 链接(跨文档/类调用):描述 + 已有类函数调用;可解析、可执行(v2.1 目标)
[描述](url) 普通 Markdown 导航链接(惰性,不执行)
*…* 返回值(整行、返回*n*、或表达式形)
**** / 整行 ** / *None* 空返回(None),并结束本函数体
> print … 等 输出等副作用 = 普通函数,非架构标记
# 类 / 类型(知识命名空间;# main = 入口)
## … 函数(类下函数;使用 self/自 时为实例方法)
类.函数 类调用(不使用 self 的函数;v2.1 目标)
> `obj`.method … 方法调用(obj 为带 _type 的 map)
叙述 `名` / `名`=默认 形参由体推断(+ `名` 仍可用)
1. … 体内 1. 2. … = 分支(N. * = else)
- 循环(- `条件` 或 - [项](遍历 集合 为 项))
表格 集合(几何即类型,见下);取元使用 access(集合, "键")
单独一行 --- / *** 叙述分隔(跳过;不是函数收束)

[键](集合) / - [项](集合) 是旧取元/循环形;迁移后使用 access(集合, "键") 与 - [描述](遍历 集合 为 项)。旧形只在显式 markup: classic 或 --legacy-markup 过渡入口中保留,见 link-syntax.md。

# main

> 问候 谁=World

## 问候

向`谁`问好。

**print text="Hello " + 谁**
*None*

## 加一

对于输入变量`n`,执行**n=n+1**接着返回*n*。

表格几何即类型:单列竖表 → List;横表(1 数据行)→ Map;横表(多数据行)→ Map of List(列向聚合);首列写 @ / 行 / row → 行向记录 List of Map。详见 tables-maps-footnotes.md。

完整约定:markdown-mapping-v0.3.md。


理念

  1. 叙述默认安全(无标记 = 注释)。
  2. 返回是架构;打印只是函数。
  3. 代码即文档即知识库:文稿可执行,执行可回看结构,结构可导航与调试。
  4. 对齐 OKF(Open Knowledge Format)方向:清单由工具从 .mq.md 自动生成,不是手填配置——见下节与 catalog-cli.md。
  5. 正经解释器(Rust):词法/行分类 → 语法 → 语义 → 树遍历(及字节码);不用 Flex/Bison。见 路线图。
  6. 语言核心保持小:Language(标记映射 / AST / 语义 / 类型)、Runtime(stdlib / 插件 ABI / WASM / agent)、Document(知识 + 代码 + UI + AI)三层分明——生态功能不淹没语言身份。

工程习惯:允许申报未完成,但不允许假装完成

Marqdo 允许你写出"还没接通"的代码——只要写在描述里。这样文档整体仍能跑, 而欠账是可见、可数、可结算的(而不是假装完成):

## 检索资料

| 返回 | 类型 | 说明 |
|------|------|------|
|  | list | 命中列表(当前未接) |

[按关键词检索,接口未接,待开发](None)

[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})

[] 里是自由描述(不执行);() 里是目标(唯一执行)。这条语法叫链接语法: 目标是本地表达式时,就是遮蔽(把代码折叠在括号里);目标是 类.函数 时,就是跨文档类调用。 v2.1 实现了文件级链接语义与可执行知识投影(见 link-syntax.md)。

四条约定

  1. 桩必须能跑:不得报错,否则整篇文档被阻断。
  2. 桩必须写明返回值:写 None 也比空着好;空 () 会报 label.empty_payload(warning)。
  3. 申报用词有范例:内置词表(待开发 未实现 开发中 模拟 桩 示例 实验 废弃 …) 是推荐用词与默认检索集,不是语法——写别的说法同样合法。
  4. 接不了就申报,别声称完成:这条已写进 ext/ai 的 agent 提示词。

盘点与门禁

marqdo labels --count                              # 内置口径:还有多少未完成
marqdo labels --grep "接口未联调,联调中" --count    # 用你自己的说法
marqdo labels --grep 联调 --also-builtin --count  # 自定义 + 内置一起数
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase

最后一条是棘轮:只拦"新增未完成",不追旧账。

设计依据:link-syntax.md · occlusion-syntax.md · occlusion-description-and-search.md


OKF 风格清单(自动生成)

从源码派生 YAML / Markdown 知识包(勿手改生成物):

marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR          # catalog 的别名

# Engineering Knowledge Compiler(L0–L4 能力目录 / 复用门闩)
marqdo knowledge [PATH] -o OUT_DIR
marqdo find "authentication"
marqdo reuse "implement oauth login"
marqdo duplicate [--fail]
marqdo verify
参数 默认 说明
PATH . 工程根或含 .mq.md 的目录
-o / --out .marqdo 输出目录

catalog 成功后默认再跑 EKC(--no-knowledge 可关)。产物示例:catalog.yaml、engineering.yaml、catalog/capabilities/、graph/graph.json。设计见 engineering-knowledge.md · catalog-cli.md · 调研 okf-and-marqdo.md。

智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):agent-frameworks-and-marqdo.md · 优化路线 ext-agent-optimize.md。

cargo run -- catalog public -o .marqdo
# 或已安装二进制时:
marqdo catalog public -o .marqdo

现状(v2.7.0)

  • 实际工程与可执行 SKILL(v2.7.0):中英文用户站点使用递归 View、普通 Markdown、当前数据/表单/会话资源并保留原始主题。开发与发版手册通过 marqdo call 执行,固有文件能力负责读写,工程插件承接进程、认证与格式边界。旧独立浏览器演示已收敛到实际可运行的工程;详见 2.7.0 发布说明。

  • 标准库与拓展库手册(v2.6.0):61 份公开标准库、650 个函数;源码内参数/返回契约、叙述形参、句中遮蔽调用与真实工程。新增文件/字节/集合/Result/文档/HTTP/任务/TOML/时区工作流;多文件拓展库以 index 组织。

  • View 可读动作与知识(v2.6.0):正文读动作,侧注看实现,运行标注看实际结果;空逻辑明确提示待补。知识说明先看输入、返回、依赖和依据,技术身份按需展开。

  • Quantum / Web 工程实践(v2.6.0):可执行实验、会话句柄与双语门面;网页先递归拆布局,直到叶子可以直接用 Markdown 表达。CLI · wasm · ext · VS Code 扩展同步 2.7.0。

  • View 连线与工具栏(v2.5.1):真实源码锚点、连续 S 形曲线、错落标注与连线避让;底部工具栏增加文字标签。深浅色配色保持一致。CLI · wasm · ext 同步 2.5.1。

  • View 阅读界面(v2.5.0):暖白金色主题、新 Logo 与花枝装饰;真实执行信息左右引出、窄屏内联;导航/搜索/阅读设置/工具栏;重跑同步刷新与离线公式。CLI · wasm · ext 同步 2.5.0。

  • Oracle journal 语言值(v2.4.0):foreign.oracle_journal / foreign.replay_check 作普通值;handle/code 拒入 journal;bytecode/frontend 硬化;扩展包同步 2.4.0

  • Foreign Strong(v2.3.0):会话 handle(不可过桥)· 仿射 close · replay_check/oracle journal · 表 arity refuse · Ω∈(V_{\mathsf{safe}})。扩展包同步 2.3.0

  • (V_{\mathsf{safe}}) JSON 整数(v2.2.2):外联与 lib/json 拒绝 |n| > 2^{53}-1 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node BigInt。

  • view 大纲侧栏(v2.2.1):修复 occlusion 文档与中等宽度下 Functions / Variables 掉到正文下方的问题;静态 view output 同源。

  • 函数级调用(v2.2.0):marqdo call <文件.mq.md> <函数> 名字=值。同一份文档给人读,也按函数执行;Tree 与 Bytecode 都跑被点名的函数,不回退到 # main。默认只执行纯函数。--json 给 Agent 读取结果或诊断。说明与价值见 22-函数调用。示例:marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 → 5。扩展包同步 2.2.1

  • Agent 可靠工作台(v2.1.5):ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC ir.json 暖机与 --refresh · Web 短读/控制与 execute 槽隔离;扩展包同步 2.1.5

  • 默认隔离 HTTP execute(v2.1.4 · ADR 0009):execute / sse-live / stream:true → Supervisor worker 池(--call-lib-path);父进程不再占 INVOKE_LOCK;/_runtime/*;runtime.isolated_execution=1;MR-01 金样例

  • 知识工作台运行时(v2.1.3):ModelSelection / RunContext / usage null≠0 · view document 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke(设计 Partial:原生适配器 unavailable)

  • 可执行知识生产链(v2.1.2):证据/闭包失效 · verify/adjudicate · reuse_execute / eng_bind_execute+publish_gate · document.extract · View KnowledgePresentation+SSE page_token · 上传限流 · 门禁 45 项(100/1000 单元)

  • 可执行知识主链(v2.1.1):BoundCall 双后端 · NarrativeRef · 来源/适用期 · artifact.patch / extract_pure · 整代 CURRENT + closure · 发票示例 113

  • 链接语法(v2.1.0):[描述](目标) 描述不执行 · () 与 **代码** 同权(加(1) / 加一 号(31))· access 取元与 遍历 链接循环 · marqdo labels 两级检索 / --baseline 债务棘轮 · migrate labels --mark · 诊断 label.* · view 描述正文 + 代码片 + 桩徽章 · 可执行知识 link-syntax.md(项目索引、LinkInfo、链接图与 lock)

  • 外联 v3 P0/P1(v1.5.2):raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · view capture · Persist 按钮 · 扩展包同步 1.5.2

  • view 静态/动态统一 + 外联值传递(v1.5.1):静态导出与 live view 共用 foreign_doc 执行路径 · 构建时运行注入 stdout · foreign.session 值传递 · cell stdin;扩展包同步 1.5.0

  • 裸自增升参(v1.4.6):首次粗体赋值左值即声明;**n = n + 1** 无反引号也升为必选形参。扩展包仍为 1.4.5

  • Streamable HTTP MCP + web invoke 鉴权(v1.4.5):agent_mcp_serve transport=http · Bearer/X-Api-Key 注入 · unauthorized→401 · openai/agent json.get 硬化

  • LLM 传输软失败 + ext/ai 表优先(v1.4.4):上游不可达 → status=error(不 abort);agent/llm 去 json.set 胶水 · agent-llm-transport-soft-2026-10.md

  • Ext pack 1.4.3:修复 agent.run cold EFI(`self`.preflight + miss resolve llm_free);已并入 ≥1.4.4 · agent-run-efi-resolve-bugs-2026-10.md

  • Agent/LLM 优化 O1–O5(v1.4.2):ext/ai/sandbox CoW · agent.trial / sandbox= · promote sandbox proof · step_route / EFI / cost · style lint · quarantine · ext-ai-optimize.md

  • view 标注连线(v1.4.1):underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · view-prose-annot-gaps.md

  • 叙述统一 / 公式 meta / 图片自写回(v1.4.0):% marqdo: var= 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · ![marqdo-out](…) 图片自写回 · view 推断形参实值 · fence-meta-and-control-prose.md · stdlib-writeback.md

  • view 文档面(v1.3.3):Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI #mq-view-trace · 静态 view output / gh-pages 同源 · view-document-annotations.md

  • Engineering Knowledge(v1.3.0):EKC L0–L4 · marqdo knowledge|find|reuse|duplicate|verify|… · Agent preflight / REUSE→ADAPT→CREATE · engineering-knowledge.md

  • Web Artifact(v1.2.0 · ADR 0007):Document/Endpoint 一等公民(type: web|endpoint)· facade page/route/serve/render/inspect/use · Resource 拆到 ext/data/security/net · 统一 View 表 · 破坏性移除 compose_*/configure

  • AI 栈(v1.1.1):ext/ai/llm 语义 ask/stream/collect · Artifact Metadata Binding(${env|arg|sys|secret})· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 plugins/llm Transport ABI

  • AI 原生闭环(v1.1.0):核心表面守卫(19 构造,单边改动 CI 必红)· 渐进式契约(文档内嵌 参数/返回/字段 表 + 四边界校验 + marqdo check 防漂移)· MLSP for AI(marqdo mlsp:locate/syntax/validate/repair_targets/repair_apply/schema,AI 按需查语法而非背诵)· 结构化诊断(run --json,错误即数据);验证见 perf-validation-report-2026-09-23.md

  • 映射与解释器:v0.3 语法宪法(** 代码 / * 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 tests/ 与 tests/markup-v03/

  • 对象:# = 类型/构造,##+ = 函数/方法;见 objects.md

  • marqdo view:文档浏览器(文档面 Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;view output 同构)

  • marqdo debug:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)

  • marqdo catalog / sync:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)

  • marqdo knowledge / find / reuse / impact / conflicts / stale / duplicate / verify:Engineering Knowledge Compiler(engineering-knowledge.md)

  • marqdo version --check:与 GitHub 最新 release 对比

  • 标准库:内置于二进制(v0.1.2+);磁盘 lib/ 或 MARQDO_LIB 可覆盖。模块含文本、表、浏览器效应、文件、系统、时间、JSON、网络、数学、外联、插件、自写回、子任务;中层 Mid M1–M6 + Mid2 M7–M10(datetime/url/toml/html/fs++/stats/log.fields 等,见 stdlib-mid.md · stdlib-mid2.md)

  • 官方扩展库 ext/(非 stdlib,本版收口):

  • 原生插件 ABI:include/marqdo_abi.h · ext-abi.md;plugins/{demo,agent,web,quantum,linalg,llm}(web 为 Go;其余为 Rust)

  • 用户静态站:public/ → view output → CI 发布 gh-pages

  • VS Code 扩展:分支 vscode-extension(main 不跟踪源码;见 vscode-extension-commit.md);Release 附带 .vsix

  • 浏览器 Marqdo(WASM):marqdo wasm build + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);lib/browser + GFM;web.client_embed;示例 browser-app · web-spa-app · web-collab-doc(ADR 0002 · D · E · F)

  • 选型:ADR 0001 — Rust · ADR 0002 — 浏览器 WASM(C0–C5 完结,见 roadmap/browser-wasm.md)· ADR 0003 — 异步效应

如何使用最新 Marqdo(v2.7.0)

安装解释器(任选其一)

方式 适用 命令 / 链接
Ubuntu PPA Ubuntu 24.04+(noble 等) sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
GitHub Releases Windows / Linux 预编译 zip https://github.com/cflmy/marqdo/releases
源码 需本机 Rust 见下方 git clone + cargo build --release

安装官方扩展(与 CLI 可分开发版):marqdo ext add … 默认下载顺序为 CDN https://ext.marqdo.com → GitHub Releases → proxy.cflmy.top 镜像。

# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v2.7.0   # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
marqdo version --check

# 2) 跑整个文件,或只调用其中一个函数
marqdo run tests/structure/hello.mq.md
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
marqdo run tests/structure/hello.mq.md --backend bytecode
marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo

# 2b) AI 原生闭环(v1.1.0+):契约检查 / 结构化诊断 / MLSP 查询
marqdo check tests/contracts/ok_contract.mq.md        # 静态契约防漂移
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp

# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
marqdo ext add web      # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
marqdo ext add agent    # 或:智能体
marqdo ext add quantum  # 或:量子
marqdo ext add linalg   # 或:线性代数
marqdo ext add llm      # 或:大模型(.mq.md + 可选 native llm)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg,llm}
#         bash ./scripts/build-web-plugin.sh   # 需 Go + cgo → libweb
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1

# 4) 动态站示例(扩展装好后)
marqdo run examples/web-site-zh/index.mq.md   # 表驱动引言 Demo
marqdo run examples/marqdo-blog/serve.mq.md
marqdo call examples/web-site/index.mq.md serve --effects plugin,fs.write,network.write --fs-root examples/web-site --json
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8

# 5) 浏览器 WASM(可选)
marqdo wasm build
# → dist/wasm/ … 实际工程见 examples/browser-app/

# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
#    https://github.com/cflmy/marqdo/releases/tag/v2.7.0

开发期也可用 cargo run -- … 代替已安装的 marqdo:

cargo run -- run tests/structure/hello.mq.md
cargo run -- view public --no-open
cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1

发布包:GitHub Releases 的单独二进制 已内置官方 lib/。Ubuntu 用户优先 PPA 装 CLI。扩展库用 marqdo ext add …(CDN → GitHub);设计见 ext-cdn.md · ubuntu-ppa.md · ext-cli.md。

文档:用户站 public/ · 设计 doc/ · OKF / catalog catalog-cli.md · 调试 view-debug.md · 变更 CHANGELOG.md

命名

Marqdo = Marq(Markdown)+ do(执行)

许可

Apache License 2.0

About

Marqdo — A Rust-based runtime for executable AI skills. Turn readable Markdown documents into verifiable, callable tools.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages