- 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.4 KiB
Executable File
markup, title, description
| markup | title | description |
|---|---|---|
| occlusion | Code as documentation, documentation as knowledge — OKF and EKC | How Marqdo keeps one executable source of truth while projecting it into OKF-style knowledge and Engineering Knowledge Compiler artifacts |
main
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
Marqdo's constitution is code as documentation and documentation as knowledge. A .mq.md file is not a screenshot of a program: it is the readable source, the executable unit and the knowledge page at the same time.
That claim matters only if the knowledge stays derived from the source. OKF gives us the shape of a portable knowledge bundle; EKC gives us the engineering projection. Neither becomes a second source of truth.
OKF shape, Marqdo meaning.
OKF (Open Knowledge Format) describes knowledge as Markdown pages with YAML frontmatter: one concept per page, path as identity, links as graph, a deliberately small required surface. Marqdo borrows that shape, but its body is executable.
A concept page can therefore point at the exact file that proves it:
type: Capability
title: Persistent foreign kernels
description: Run an explicitly declared local kernel with native data
resource: public/features/19-foreign-view-cells.mq.md
status: stable
verified:
by: marqdo-knowledge/verify
tags:
- foreign
- view-cells
The same page can be opened in an editor, linked from a catalog, queried by an agent, and executed. Unknown fields are preserved; unknown types degrade to readable prose. The page is a concept, not a copy of one.
What is generated, and what is not.
| Layer | Author | Role |
|---|---|---|
| Source | person or coding agent | .mq.md; the only semantic authority |
| Catalog | marqdo catalog | module, symbol, capability and graph projection |
| Task knowledge | plan promotion | task, skill and executable resource bundle |
| Static site | marqdo view output | human-readable HTML, never an authority |
Generated artifacts are marked GENERATED and can be deleted and rebuilt. The source tree still runs without them. A catalog is an index, not a language feature.
EKC: the Engineering Knowledge Compiler.
EKC projects the repository into an engineering knowledge system, then exposes it through a preflight before an agent writes new code:
.mq.md ──► EKC ──► catalog L0–L4
├─ graph
├─ context pack
└─ Agent preflight
| Layer | Knowledge | Example |
|---|---|---|
| L0 Repository | language, size, roots | repository summary |
| L1 Module | imports, exports, responsibility | a foreign kernel module |
| L2 Symbol | signature, calls, fingerprint | a function in external source code |
| L3 Capability | what the project can do | run a persistent foreign kernel |
| L4 Knowledge | decisions, constraints, failures | why the bridge is explicit |
The graph records relations such as implements, uses, depends_on, tested_by, documented_by, constrained_by, decided_by, supersedes, conflicts_with and deprecated_by. That graph is how an agent discovers existing capability before inventing a duplicate.
Engineering First Information: discover before create.
The reuse protocol is a hard order:
REUSE → ADAPT → CREATE
A preflight can return existing capabilities, APIs, constraints, decisions and failure notes before a new implementation starts. If the knowledge graph is missing, the result is an explicit missing_knowledge state, not a silent fabrication.
The five principles are:
| # | Principle |
|---|---|
| 1 | Discover before Create |
| 2 | Reuse before Adapt |
| 3 | Adapt before Duplicate |
| 4 | Verify before Promote |
| 5 | Code changes update knowledge |
The commands.
# Project the repository into catalog + EKC artifacts
marqdo catalog .
# Ask what already exists before writing code
marqdo knowledge preflight "add a persistent foreign kernel"
marqdo find "foreign session"
marqdo reuse "implement JSON fan-out"
# See what a change would touch
marqdo impact public/features/19-foreign-view-cells.mq.md
# Validate the knowledge projection
marqdo knowledge verify
marqdo catalog keeps the human-readable index.md and module pages; EKC adds L0–L4 files under .marqdo/. Both are generated from the same source tree.
Every claimed capability has an executable resource.
A knowledge page that says “this project can analyze orders” must point to a .mq.md resource that actually runs. That is the difference between an OKF-shaped note and an executable knowledge system.
The foreign example computes its order report in native Marqdo and uses Node Intl for locale-aware presentation. Explicit imports point to the shared callable report handbook, while the page declares the actual view kernels, values and cells. Inspect the real per-cell results; a serialized plan alone does not establish that its cells ran successfully.
Read more.
OKF design: OKF design
Engineering Knowledge Compiler: Engineering Knowledge Compiler
Catalog CLI: Catalog CLI
OKF and Marqdo research: OKF and Marqdo research
Foreign view-cells example: Foreign view-cells example