Files
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

5.4 KiB
Executable File
Raw Permalink Blame History

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