- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
5.8 KiB
Executable File
markup, title, description, 导入
| markup | title | description | 导入 | ||||
|---|---|---|---|---|---|---|---|
| occlusion | 欢迎使用 Marqdo | 用户文档首页 — 代码即文档(中文版) |
|
main
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套?于是有了 marqdo。为了让文件既能当文档渲染又能执行,后缀定为 .mq.md。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT;眼下它至少已经是个不错的博客工具——对,这个站点就是 Marqdo 生成的。AI 写 .mq.md 时往往更省 token,钱包也会轻松一点。
语言仍在起步:结构标记、中英内核双名(打印 / print …)、可导入的标准库(见本站 stdlib/)、本地 view 与静态导出。欢迎到 GitHub 一起做。
English docs: 00-welcome.mq.md(English prose and English builtins).
想先打个招呼?marqdo run 会运行入口 # main。比如:问候 谁="marqdo"。名字里可以带空格:问候 谁="marqdo user"。
从这一版起,不必为了试用一个函数再包一层入口。marqdo call 直接运行文件里的某个函数,参数写在命令上。同一页仍然是给人读的文档。作用和价值写在 features/22-函数调用.mq.md。
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
比方说,直接写一块公式,并用 TeX 注释标上变量名:
% marqdo: var=f
x^2 - 2
接着画出来:_svg = 数学.绘图 formula=f var="x" min=-3 max=3
外联则允许嵌一段别的语言。把hi绑成下面这样即可:
hi =
console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
一份文件,三个面。
| 面 | 是什么 |
|---|---|
| 文档 | 普通 Markdown:叙述、表格、链接、围栏代码 |
| 程序 | 同一批标记可执行:赋值、调用、返回 |
| 知识 | frontmatter、链接与生成的 catalog 条目,Agent 可查询 |
你正在读的静态站就是由这些文件生成的,所以示例不是截图。运行同一份源,会得到同一页。
外联 v2 是个好例子。先探测 Node,再运行绑定围栏:
我们先node = 检查本地化展示所需的解释器,供下一步使用。
- ok)
我们先问候 = 通过 Intl 展示原生金额,供下一步使用。
随后我们**[显示当前步骤的结果](> 打印 内容=
问候)**。 -
随后我们**[显示当前步骤的结果](> 打印 内容="(未找到 node — 安装 Node 后可运行此单元)")**。
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 stdlib/外联.mq.md 与原生分析与 Intl 示例 features/19-外联视图单元.mq.md。
view 仍然是一篇文档。命名内核与单元顺序就是普通绑定表:
`分析内核` =
| 名称 | 语言 | 说明 |
|------|------|------|
| 分析 | node | 共享状态 |
| 复核 | node | 隔离状态 |
`分析单元` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 准备数据 | 分析 | 写入 |
| 计算指标 | 分析 | 读取 |
| 独立复核 | 复核 | 校验 |
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
marqdo view 消费 foreign 拥有的 会话 句柄,变成 Run All、Step、每单元内核、journal 与状态面板。没有 会话 时,单元是无状态的一次性运行。没有单独的交互模式或命令;marqdo run 仍然把文件当单个程序运行。
文档能被发现、验证和复用时,才成为知识。OKF 提供可移植的 Markdown + YAML 形态;EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 .mq.md 始终是唯一权威,生成物有标记、可重建。
| 循环 | 问题 |
|---|---|
| OKF | 人和 Agent 如何共享一页可读知识? |
| EKC | 创建之前,应该复用哪些已有能力、决策、约束与失败? |
| Preflight | REUSE → ADAPT → CREATE |
概念与命令见 features/20-OKF与EKC.mq.md。
最后,再次欢迎你,尽情体验 marqdo 吧!
安装方式。
解释器(CLI)任选其一:
| 方式 | 说明 |
|---|---|
| Ubuntu PPA | sudo add-apt-repository ppa:cflmy/marqdo 后 sudo apt install marqdo |
| GitHub Releases | releases 下载 Windows / Linux 预编译包 |
| 源码 | cargo build --release(需本机 Rust) |
官方扩展与 CLI 可分开更新。安装扩展:
marqdo ext add web
marqdo ext add quantum
ext add 下载顺序:CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 features/05-扩展.mq.md。
问候
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 谁 | any | 必填 | 要显示在问候中的称呼 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 空值;本函数通过上述操作产生效果,不返回业务数据。 |
见到访客谁时,我们 打印 内容="欢迎,谁!",然后收束为None。