Files
marqdo/doc/next/008.md
T
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

43 KiB
Executable File
Raw Blame History

https://github.com/cflmy/marqdo这是marqdo的仓库链接现在有了最新的变更,我需要你仔细阅读一下和OKF相关的内容,我觉得marqdo的真正优势在大规模工程化的代码生成方面,OKF能够让AI在工程中更快的得到相关工程的第一信息,尤其是现在的AI喜欢重复性造轮子,将功能类似的函数重复性的撰写这样的问题,我认为marqdo有解决这个问题的潜质,但是还不够还要继续开发,请你仔细思考,从工程的角度上,给我一份详细的优雅的方案,充分发挥marqdo代码即文档,文档即知识库的潜力

实现状态(2026-09-28):本文方案已落地为 Marqdo Engineering Knowledge v1。
规范见 doc/design/engineering-knowledge.md;
核心实现 src/knowledge/;CLI:marqdo knowledge|find|reuse|impact|conflicts|stale|duplicate|verify;
Agent:agent.preflight / agent_eng_*。下文保留为设计叙事与动机,勿当作未实现清单。

我重新看了现在仓库主线的定位之后,我认为你的判断是对的,而且我想把这个判断再往前推一步:

Marqdo 真正有机会形成差异化的地方,不是“AI 可以用 Markdown 写代码”,甚至也不只是“Markdown 是可执行知识库”,而是:让一个大型工程本身成为 AI 可查询、可验证、可复用、可演化的“可执行知识系统”,从而在代码生成前就知道“工程里已经有什么、应该复用什么、为什么不能重新造”。

这比“RAG + Coding Agent”要更深一层。

目前仓库 README 已经明确把目标定义为“代码即文档、文档即代码、文档即知识库”,并且已经有 catalog/sync、自动生成 catalog.yaml / index.md / modules/*.md 的基础设施。(GitHub) 同时,新的 Agent 设计也已经明确:源码、调用位置、Skill、工作簿和写回结果都应该进入 Agent 上下文,而且成功/失败结果应该沉淀,而不是只存在于 chat transcript。(GitHub)

现在真正缺的,是把这两个方向合成一个“工程知识编译器”。


一、我先给出我认为 Marqdo 应该最终形成的核心模型

我建议不要再把 Marqdo 简单理解成:

Markdown
   ↓
Programming Language
   ↓
AI Agent

而应该是:

                    Git Repository
                         │
             ┌───────────┴───────────┐
             │                       │
          Source                  Documents
             │                       │
             └───────────┬───────────┘
                         ↓
                  Marqdo Compiler
                         │
          ┌──────────────┼──────────────┐
          ↓              ↓              ↓
      Executable      Knowledge       Catalog
       Program         Graph          / Index
          │              │              │
          └──────────────┼──────────────┘
                         ↓
                  Engineering KB
                         │
                         ↓
                    Coding Agent
                         │
              ┌──────────┼──────────┐
              ↓          ↓          ↓
           Search      Reuse      Generate
              │          │          │
              └──────────┼──────────┘
                         ↓
                  Verified Change
                         │
                         ↓
                  Knowledge Update
                         │
                         └──────→ Git

也就是说:

Marqdo 不应该只是帮助 AI “写代码”,而应该帮助 AI 在写代码之前理解工程。

这才是大型工程场景真正困难的事情。


二、为什么“大规模工程 AI”真正的问题不是生成能力

现在的 Coding Agent 最大的问题往往不是:

“AI 不会写这个函数。”

而是:

“AI 不知道这个函数已经存在。”

或者更隐蔽:

“AI 知道有类似函数,但不知道哪个才是应该复用的。”

再进一步:

“AI 找到了一个类似函数,但不知道这个函数为什么这样设计。”

再进一步:

“AI 找到了正确函数,但是不知道它有哪些隐含约束。”

例如一个大型工程里可能已经存在:

parseConfig()
loadConfig()
resolveConfig()
normalizeConfig()
mergeConfig()
validateConfig()
readConfigFile()

用户让 AI:

“实现一个配置加载功能。”

普通 Coding Agent 很可能:

搜索几个文件
↓
发现没完全一样
↓
写一个新的 load_configuration()
↓
加 300 行代码
↓
测试通过

从局部看:

成功。

从工程看:

失败。

因为真正正确的行为可能是:

resolveConfig()
    +
validateConfig()
    +
已有错误处理

AI 的核心问题其实是:

工程知识缺失
        ↓
无法识别已有能力
        ↓
重复实现
        ↓
代码碎片化
        ↓
维护成本上升

三、所以我建议 Marqdo 提出一个非常明确的概念

Engineering First Information

我会把它定义成:

Engineering First Information(工程第一信息)

也就是:

AI 在修改/生成代码之前,首先获得关于当前工程中已有能力、约束、依赖、约定、历史决策和可复用实现的最小充分信息。

这个概念非常适合成为 Marqdo 的核心论文/产品概念。

因为普通 RAG 是:

query
 ↓
retrieve documents
 ↓
LLM

而 Marqdo 应该是:

engineering task
 ↓
understand intent
 ↓
retrieve engineering first information
 ↓
reuse analysis
 ↓
existing capability candidates
 ↓
architecture constraints
 ↓
only then generate

区别非常大。


四、目前 Marqdo 已经走到了哪里?

现在仓库已经有几个非常重要的基础。

1. .mq.md 已经是 executable artifact

README 明确把:

叙述
代码
返回
对象
函数
表格

都统一在 Markdown 中。(GitHub)

这意味着 Marqdo 天生拥有:

Source
+
Documentation

的共址关系。


2. 已经有自动 Catalog

当前已经存在:

marqdo catalog
marqdo sync

并生成:

catalog.yaml
index.md
modules/*.md

而且 README 特别强调这些是从源码自动派生的,而不是手工维护。(GitHub)

这个非常重要。

因为:

不要让 AI 再去“猜”项目有什么。

Catalog 就应该成为第一层事实来源。


3. Agent 已经开始把源码作为上下文

新的 Agent 设计明确要求:

源码
调用位置
Skill
相关写回块
工作簿

进入模型上下文。(GitHub)

而且新的设计已经放弃“隐藏 chat history 作为真相”,转向:

文档写回 + 工作簿 = 真相。

(GitHub)

这个方向我认为是非常正确的。


五、但这里有一个关键缺口

现在的系统更接近:

Task
 ↓
Agent
 ↓
查源码 / Skill / 写回

而我要推动它成为:

Task
 ↓
Engineering Intent
 ↓
Engineering Knowledge Resolution
 ↓
Reuse Gate
 ↓
Generate / Modify
 ↓
Verify
 ↓
Knowledge Update

也就是说:

“知识检索”不能只是 Agent 的一个上下文增强功能,而应该成为代码生成的强制前置阶段。

这是非常重要的架构变化。


六、我建议新增一个核心层:Engineering Knowledge Compiler

可以简称:

EKC
Engineering Knowledge Compiler

或者更 Marqdo 一点:

Marqdo Knowledge Compiler

职责:

Source
Document
History
Tests
Interfaces
Examples
Architecture
Execution
        ↓
Knowledge Extraction
        ↓
Knowledge Graph
        ↓
Engineering Catalog
        ↓
Agent Context

七、它和普通 OKF 有什么区别?

这里要特别注意。

OKF 本身是一个开放的知识包装格式:Markdown + YAML frontmatter,强调人和 Agent 都能读、能版本控制、能交换。官方规范刻意保持简单,不要求 schema registry 或特定工具。(GitHub)

所以:

不要把 Marqdo 做成“另一个 OKF”。

应该:

OKF
 ↓
Knowledge Packaging Layer

Marqdo
 ↓
Engineering Knowledge Execution Layer

也就是:

OKF
    ↓
Marqdo Engineering Profile
    ↓
Executable Engineering Knowledge

这是我认为最优雅的关系。


八、Marqdo 应该在 OKF 上增加“工程知识类型”

例如:

Marqdo OKF

里面不只是:

Module
Document
Concept

而应该出现:

Function
Type
API
Capability
Pattern
Decision
Constraint
Example
Test
Workflow
Error
Dependency
Migration
Deprecated

例如一个函数:

---
type: Function
name: resolve_config
module: config
symbol: resolve_config
status: stable
visibility: public
---

# resolve_config

Resolve configuration from:

- environment
- config file
- defaults

## Use when

The caller needs the final normalized configuration.

## Do not use when

Only raw configuration should be inspected.

## Related

- [validate_config](...)
- [normalize_config](...)

## Tests

- [test_resolve_config](...)

这就不再只是:

“这里有一个函数。”

而是:

“这个函数在工程里的语义是什么。”


九、这是解决“AI 重复造轮子”的关键

AI 不应该只搜索:

函数名字

而应该搜索:

Capability

例如用户:

“我要把配置文件加载出来。”

Agent 首先构造:

intent:
  domain: configuration
  capability: resolve
  input: configuration_source
  output: normalized_config
  constraints:
    - existing architecture
    - existing error handling

然后查:

Capability Index

得到:

Candidate #1
resolve_config
score: 0.96
status: stable
reuse: recommended

Candidate #2
load_config
score: 0.83
status: internal

Candidate #3
parse_config
score: 0.71
scope: parser-only

于是模型不再:

“我要写一个 config loader。”

而是:

“工程里已经有 resolve_config,我应该调用它。”


十、所以 Catalog 不能只做“目录”

这是我认为 Marqdo 下一阶段非常重要的改造。

现在:

catalog

容易理解成:

“项目里有哪些文件。”

但真正应该是:

Engineering Capability Catalog

也就是:

文件
模块
对象
函数
类型
接口
能力
关系
约束
示例
测试

全部进入 Catalog。


十一、建议建立 5 层 Catalog

L0:Repository

repository

知道:

语言
模块
目录
依赖
构建系统
测试系统

L1:Module

module

知道:

exports
imports
responsibility
dependencies
public API

L2:Symbol

function
class
type
constant
endpoint

知道:

signature
location
visibility
calls
called_by
tests

L3:Capability

这是最重要的一层:

capability

例如:

"parse configuration"
"validate JWT"
"retry HTTP request"
"serialize JSON"
"resolve dependency"

它不等于函数。

一个 Capability 可以映射到:

1 function
3 functions
1 module
1 workflow

L4:Engineering Knowledge

再往上:

Decision
Constraint
Pattern
Anti-pattern
Reason
Migration
Failure

例如:

为什么不能直接调用 foo()?

因为:

foo()
 ↓
必须先 initialize_context()

这个信息对 AI 极其重要。


十二、我建议把“复用”从搜索升级成一个正式协议

新增:

agent.reuse

或者:

knowledge.reuse

它不是:

search("foo")

而是:

reuse(task)

返回:

{
  "decision": "reuse",
  "confidence": 0.94,
  "capability": "config.resolve",
  "symbol": "resolve_config",
  "source": "src/config.mq.md",
  "reason": [
    "same input semantics",
    "same output semantics",
    "same error model"
  ]
}

如果没有合适的:

{
  "decision": "create",
  "reason": "no existing capability satisfies constraints"
}

十三、这一步非常重要:AI 必须允许“证明不存在”

否则会出现另一个问题:

AI 搜索了一遍没找到,就自己写。

所以应该有:

Reuse Resolution

三个结果:

REUSE
ADAPT
CREATE

而不是:

FOUND
NOT FOUND

十四、三个状态分别代表什么

REUSE

已有能力满足需求。

直接调用

ADAPT

存在相近能力。

包装
组合
参数化
扩展

例如:

A
 +
B
 →
新的 capability

而不是复制 A。


CREATE

经过检索和分析确认:

工程中不存在合适能力。

才允许生成。

这个顺序应该成为 Marqdo Agent 的硬规则:

REUSE
  ↓
ADAPT
  ↓
CREATE

而不是:

CREATE
  ↓
maybe reuse

十五、再进一步:把“重复代码”变成可检测知识

这一步我认为会非常有意思。

Marqdo Compiler 可以生成:

symbol fingerprint

例如:

function:
  normalize_config

fingerprint:
  inputs:
    map<string, any>
  output:
    normalized_config
  operations:
    parse
    merge
    validate

另一个函数:

normalize_settings

可能得到:

semantic similarity: 0.91

于是 Catalog 标记:

possible_duplicate

十六、于是可以出现一个非常强的命令

marqdo reuse-check

输出:

Possible duplicate capabilities

1. src/a.mq.md::normalize_config
   src/b.mq.md::normalize_settings
   similarity: 0.91

2. src/x.mq.md::parse_user
   src/y.mq.md::decode_user
   similarity: 0.87

这就不再只是 AI 功能。

而是:

工程治理工具。


十七、甚至可以成为 CI Gate

例如:

knowledge:
  reuse:
    required: true
    duplicate_threshold: 0.90

PR 中新增:

normalize_settings()

CI:

⚠ Potential duplicate capability

Existing:
config.normalize_config

New:
settings.normalize_settings

Similarity: 0.93

Recommendation:
REUSE existing capability

然后:

marqdo check

直接失败或者 warning。


十八、这会产生一个非常漂亮的工程闭环

Human asks feature
        ↓
Agent resolves intent
        ↓
Knowledge Catalog
        ↓
Existing Capability?
     /        \
   yes         no
    ↓           ↓
 REUSE       CREATE
    ↓           ↓
 Execute     Generate
    ↓           ↓
 Verify      Verify
    ↓           ↓
    └──────┬────┘
           ↓
      Update Knowledge
           ↓
      Update Catalog
           ↓
        Git Commit

下一次:

同类需求
 ↓
直接找到上一轮能力

这就是你说的:

工程越大,Marqdo 越有价值。


十九、但还有一个更大的问题:Knowledge 必须知道“为什么”

这是很多 RAG 系统做不到的。

例如:

use redis_cache

只是事实。

真正有价值的是:

# Redis Cache

Use for:

- cross-process cache
- TTL cache

Do not use for:

- durable state

Reason:

Redis cache is intentionally disposable in this project.
Persistent state belongs to PostgreSQL.

这就是:

Engineering Decision Knowledge

AI 非常需要这种东西。


二十、所以我建议增加一种核心知识:Decision

例如:

---
type: Decision
id: ADR-023
status: accepted
---

# Cache is not persistence

## Decision

Redis is only used for ephemeral cache.

## Reason

The application must remain correct when Redis is unavailable.

## Consequence

Do not introduce Redis as the source of truth.

## Applies to

- api/*
- worker/*

这比单纯把代码 embedding 给 AI 有价值很多。


二十一、再增加一种:Constraint

例如:

---
type: Constraint
---

# Database access

All database access must go through `repository/*`.

Direct SQL from HTTP handlers is prohibited.

于是 Agent 搜索:

"how should I access the database?"

得到:

Constraint
+
Repository capability
+
Example

这就是第一信息。


二十二、再增加一种极其重要的知识:Negative Knowledge

我认为这是 Marqdo 可以做得非常漂亮的地方。

传统知识库主要记录:

应该做什么

但大型工程更需要:

不要做什么

例如:

---
type: AntiPattern
---

# Do not parse JWT manually

Never decode JWT directly in application code.

Use:

`auth.verify_token`

Reason:

- key rotation
- issuer validation
- expiry validation
- audit logging

这能直接阻止 AI 造轮子。


二十三、我甚至建议把知识分成四种

FACT
  ↓
工程里有什么

RULE
  ↓
工程要求怎么做

DECISION
  ↓
为什么这样做

FAILURE
  ↓
什么东西以前做错过

于是:

Engineering Knowledge
├── Facts
├── Rules
├── Decisions
└── Failures

这四类东西结合起来,才是真正的工程知识。


二十四、失败经验尤其适合你现在的 Agent

目前 Agent 设计已经强调:

成功和失败都写回文档,失败块成为可读的“避坑记录”。(GitHub)

我建议把它正式升级成:

Failure Knowledge

例如:

---
type: Failure
task: add_cache_layer
status: resolved
---

# Do not cache authorization result

## Failed approach

Caching `check_permission(user, resource)` by user only.

## Failure

Permissions changed during role update.

## Correct approach

Cache by:

user_id
resource_id
permission_version

## Introduced by

commit abc123

未来 AI 遇到:

“我要缓存权限判断。”

第一条知识就可能是:

⚠ Historical failure detected.

这比一般 RAG 强得多。


二十五、然后你会得到一个很漂亮的 Knowledge Graph

例如:

Capability
   │
   ├── implemented_by → Function
   │
   ├── tested_by → Test
   │
   ├── constrained_by → Constraint
   │
   ├── decided_by → Decision
   │
   ├── related_to → Capability
   │
   ├── conflicts_with → Capability
   │
   ├── failed_by → Failure
   │
   └── documented_by → Document

这样 .mq.md 不只是:

一堆 Markdown。

而是:

一个可以执行的 Engineering Knowledge Graph。


二十六、而 Marqdo 的特殊优势在于:这个 Graph 不是另建的

这是最关键的一点。

普通系统:

Code
 ↓
Vector DB
 ↓
Knowledge Graph
 ↓
RAG

会出现:

Code ≠ Knowledge

最终:

代码改了
知识没改

然后:

AI 得到旧信息。


二十七、Marqdo 应该做到反过来

.mq.md
   │
   ├── executable AST
   ├── documentation
   ├── knowledge
   ├── symbol graph
   └── catalog

一个源头,多个投影。

也就是说:

Source of Truth
      │
      ├── Execution
      ├── Documentation
      ├── OKF
      ├── Search Index
      ├── Symbol Graph
      └── Agent Context

这才是:

代码即文档,文档即知识库

真正有技术含量的地方。


二十八、因此 Catalog 不应该被看成“生成出来的 Markdown”

它应该是:

Marqdo AST 的 Knowledge Projection。

例如:

Marqdo AST
    ↓
Knowledge Extractor
    ↓
Knowledge IR
    ↓
┌────────────────────────────┐
│                            │
├── catalog.yaml             │
├── index.md                 │
├── modules/*.md             │
├── symbols/*.md             │
├── capabilities/*.md        │
├── graph.json               │
└── search index              │

OKF 是其中的一个可移植输出格式。


二十九、这会直接解决大规模工程的 Context Window 问题

这是另一个非常重要的价值。

假设工程:

5 million lines

不可能:

把整个 repo 给 GPT

也不应该:

向量搜索 top 20 chunks

因为 top 20 chunks 经常没有结构。

Marqdo 应该做:

Task
 ↓
Intent
 ↓
Catalog
 ↓
Module
 ↓
Capability
 ↓
Symbol
 ↓
Source

这是:

Hierarchical Retrieval

而不是:

flat vector retrieval。


三十、我建议采用 Progressive Disclosure

第一层:

What exists?

返回:

20 candidates

第二层:

What are their responsibilities?

返回:

5 capabilities

第三层:

Which one applies?

返回:

2 candidates

第四层:

How do I use it?

返回:

signature
example
constraints

第五层:

Show implementation.

才打开源码。


三十一、这样模型看到的上下文会非常小

例如用户:

添加 OAuth 登录。

模型首先只看到:

AUTH CAPABILITY CATALOG

Existing:
auth.oauth
auth.session
auth.user
auth.csrf

OAuth providers:
Google
GitHub

Existing route:
POST /auth/callback

Existing session implementation:
auth.session.create()

Constraints:
Do not create another session store.

Relevant decisions:
ADR-014

然后模型才决定:

REUSE auth.oauth
REUSE auth.session
ADAPT callback

它根本没有机会先写一个新的 OAuth 系统。

这就是你要解决的问题。


三十二、所以我建议 Agent 增加一个“工程前置协议”

现在:

agent.step
agent.plan

我建议最终变成:

agent.step
     ↓
knowledge.preflight
     ↓
reuse.resolve
     ↓
agent.step

复杂任务:

agent.plan
     ↓
knowledge.preflight
     ↓
architecture.resolve
     ↓
reuse.resolve
     ↓
plan

三十三、可以把它正式设计成:

## preflight

输入:

task

输出:

status: ready

intent:
  capability: authentication

existing:
  - auth.oauth
  - auth.session

constraints:
  - ADR-014
  - Constraint-07

decisions:
  - Decision-003

failures:
  - Failure-019

recommended:
  - reuse: auth.oauth
  - reuse: auth.session

create_allowed: false

只有:

create_allowed: true

才能进入生成阶段。


三十四、这里我甚至建议加入“Reuse Budget”

例如:

agent:
  reuse:
    min_candidates: 3
    require_preflight: true
    require_reason: true
    allow_create_after: 2

意思:

AI 至少分析两个已有候选之后,才能说“工程里没有”。

这会非常有效。


三十五、再进一步:生成的代码必须声明它复用了什么

例如:

---
type: Function
name: create_session
reuse:
  - auth.session
  - crypto.token
---

这样 Catalog 可以反向建立:

create_session
 ├── reused auth.session
 └── reused crypto.token

三十六、这会产生一个极有价值的指标

Reuse Ratio

例如:

Generated functions: 1000

Reused existing capability: 730
Adapted existing capability: 180
New capability: 90

得到:

Reuse Ratio = 73%
Adapt Ratio = 18%
Novel Ratio = 9%

这比:

“AI 写代码很快”

更有工程意义。


三十七、再进一步,可以衡量 AI 的“重复造轮子率”

定义:

Duplication Rate
=
new implementations
that semantically duplicate existing capabilities
/
all new implementations

目标:

越低越好

这就是 Marqdo 非常适合做实验的数据。


三十八、再进一步:Reasoning Amortization + Reuse

你之前的 Agent 思路里面已经有:

大模型探索 → 小模型/Jev 决策 → Marqdo 执行 → 逐渐编译。

现在可以再加一个:

Knowledge Amortization

也就是:

第一次:
LLM + repo exploration

第二次:
Catalog + small model

第三次:
Capability match

第四次:
Deterministic reuse

于是:

Task #1
  20k tokens
       ↓
Knowledge generated

Task #2
  5k tokens
       ↓
Reuse

Task #10
  500 tokens
       ↓
Compiled policy

Task #100
  0 LLM
       ↓
Direct execution

这就是非常漂亮的 Marqdo Agent story。


三十九、最终形成三个“编译”

我建议把你之前 Agent 的 Skill Compilation 再升级成:

1. Knowledge Compilation
2. Policy Compilation
3. Code Compilation

1. Knowledge Compilation

Source
 ↓
Fact
Decision
Constraint
Capability
Failure

↓

OKF

2. Policy Compilation

Task
 ↓
Which capability?
 ↓
Which module?
 ↓
Which function?

↓

policy.mq.md

3. Code Compilation

Capability
+
Policy
+
Constraints

↓

Executable Marqdo

四十、最终形成:

                 Human / AI Task
                       │
                       ↓
              ┌─────────────────┐
              │ Knowledge Layer │
              │  What exists?   │
              └────────┬────────┘
                       ↓
              ┌─────────────────┐
              │ Policy Layer    │
              │ What to reuse?  │
              └────────┬────────┘
                       ↓
              ┌─────────────────┐
              │ Execution Layer │
              │ What to run?    │
              └────────┬────────┘
                       ↓
                    Result
                       │
                       ↓
               Verification
                       │
                       ↓
              Knowledge Update

这就是我认为 Marqdo 最值得做的 Agent 架构。


四十一、我还建议增加一个特别重要的概念:Knowledge Lifecycle

因为工程知识一定会过期。

OKF 本身强调开放、可版本控制的 Markdown 知识包,但当前生态讨论也已经暴露出几个更高层的问题:时间有效性、信任/来源、冲突与 supersession 都不是简单的 Markdown packaging 能解决的。(GitHub)

Marqdo 做工程知识时尤其需要:

draft
 ↓
verified
 ↓
stable
 ↓
deprecated
 ↓
superseded

四十二、每个 Capability 都应该有“新鲜度”

例如:

status: stable
introduced: v2.3
verified: 2026-09-20
last_used: 2026-09-28
last_tested: 2026-09-28

这样 Agent 可以知道:

这个能力存在

和:

这个能力现在还可靠

是两个问题。


四十三、再加入 Evidence

例如:

evidence:
  source:
    - src/auth/session.mq.md

  tests:
    - tests/auth/session.mq.md

  executions:
    - run-192
    - run-204

  commits:
    - a82fd1

这就可以让 Agent 判断:

“这是文档里说的,还是代码和测试都证明过的?”

这和当前 OKF 社区正在讨论的“citation 与 reliability 不是同一件事”也是一致的:引用证明来源,不能自动证明内容可靠。(GitHub)


四十四、甚至可以引入非常轻量的 Confidence

例如:

confidence: high
evidence:
  implementation: verified
  tests: verified
  runtime: verified

而不要只:

confidence: 0.97

因为:

0.97

对 Agent 来说没有解释能力。


四十五、再解决一个非常大的问题:知识冲突

例如:

A.md:
Redis is source of truth.

B.md:
Redis is cache only.

普通 RAG:

retrieve A
retrieve B
LLM 自己猜

Marqdo:

Conflict detected
        ↓
A ↔ B
        ↓
same capability
        ↓
different claims
        ↓
Decision/Authority resolution

最终:

Decision-014 supersedes A

而不是让模型自己选择。


四十六、因此我建议增加 Knowledge Graph Edge

最重要的几种:

implements
uses
depends_on
tested_by
documented_by
constrained_by
decided_by
supersedes
conflicts_with
deprecated_by
derived_from
failed_by

这会让工程知识从:

文件集合

变成:

关系系统

四十七、然后 Catalog 查询就会非常强

例如:

marqdo knowledge find "authentication"

得到:

Capability
  auth.session

Implementation
  ext/auth/session.mq.md

Constraints
  C-014

Decisions
  ADR-023

Tests
  tests/auth/session.mq.md

Failures
  F-009

Related
  auth.oauth
  auth.rbac

四十八、Agent 不应该直接访问整个知识库

这里我非常赞同当前 Agent 设计里的一个思想:

context 应该由框架组装,而且可审计。(GitHub)

但下一步应该进一步:

Agent
 ↓
Knowledge Resolver
 ↓
Context Pack

而不是:

Agent
 ↓
自己搜索几十个 md

四十九、Context Pack 应该有固定结构

例如:

# Engineering Context

## Task

Add OAuth login.

## Existing Capabilities

- auth.oauth
- auth.session

## Relevant APIs

- auth.oauth.authorize
- auth.oauth.callback
- auth.session.create

## Constraints

- ADR-014
- C-021

## Decisions

- ADR-014

## Known Failures

- F-019

## Recommended Reuse

1. auth.oauth
2. auth.session

## Forbidden

Do not implement:
- JWT parsing
- session storage

这个东西本身又是:

.mq.md

于是:

Agent Context 本身也是 Marqdo Artifact。

这一步我非常推荐。


五十、这就是我认为真正优雅的地方

不要让:

RAG

成为一个黑盒:

query → vector db → prompt

而是:

Task
 ↓
Knowledge Query
 ↓
Context Artifact
 ↓
Agent

例如:

.marqdo/context/
    task-183.mq.md

里面记录:

用了哪些知识
为什么选这些知识
哪些候选被排除
哪些约束生效

于是 Agent 的上下文也可以:

view
debug
git diff
review
replay

这完全符合 Marqdo 的哲学。


五十一、这还能解决“AI 为什么这样写”的问题

未来代码 review 可以直接问:

为什么这里调用 resolve_config?

Marqdo 可以回答:

Because:

Task T-192
  ↓
Capability: resolve configuration
  ↓
Candidate:
resolve_config (0.96)
  ↓
Constraint:
C-012 requires centralized config resolution
  ↓
Decision:
ADR-022
  ↓
Selected:
resolve_config

这比普通 AI Code Review 强很多。


五十二、最终你的 PR 甚至可以自动生成“知识影响”

例如:

Changed:
src/config/resolve.mq.md

系统自动告诉 Agent:

Affected capabilities:
  config.resolve
  app.bootstrap

Affected decisions:
  ADR-012

Affected tests:
  tests/config/*
  
Affected documentation:
  docs/configuration.mq.md

Potential stale knowledge:
  knowledge/configuration.md

这就是:

Knowledge-aware software engineering。


五十三、这也是 Marqdo 真正适合“大型工程”的原因

小项目:

10 files

这个东西意义有限。

但是:

1000 modules
10000 functions
100000 tests

以后:

AI context

真正的瓶颈不再是模型能力。

而是:

工程知识的组织。

这恰恰是 Marqdo 可以解决的。


五十四、我建议最终形成一个 .marqdo/ 目录

我会设计成:

.marqdo/
│
├── index.mq.md
│
├── catalog/
│   ├── repository.mq.md
│   ├── modules/
│   ├── symbols/
│   └── capabilities/
│
├── knowledge/
│   ├── facts/
│   ├── decisions/
│   ├── constraints/
│   ├── patterns/
│   ├── failures/
│   └── migrations/
│
├── graph/
│   ├── graph.json
│   └── edges.json
│
├── agent/
│   ├── policies/
│   ├── skills/
│   ├── contexts/
│   └── episodes/
│
└── tests/
    ├── reuse/
    ├── knowledge/
    └── retrieval/

注意:

这些绝大部分应该是 generated / derived artifacts,不应该成为第二个 source tree。

Source of Truth 仍然是:

*.mq.md

五十五、最关键的几个命令

我建议未来 Marqdo CLI 出现这样一组能力:

marqdo catalog

生成工程目录。

marqdo knowledge

生成/维护知识。

marqdo find

找工程能力。

marqdo reuse

判断是否应该复用。

marqdo impact

分析修改影响。

marqdo conflicts

检查知识冲突。

marqdo stale

检查过期知识。

marqdo duplicate

检查重复能力。

marqdo verify

验证代码 + 知识一致性。


五十六、其中最重要的是 marqdo reuse

我甚至认为它可以成为 Marqdo 的“杀手级命令”。

例如:

marqdo reuse "implement oauth login"

输出:

Engineering First Information

Existing capabilities:
  auth.oauth                 0.97
  auth.session               0.95

Relevant constraints:
  C-014
  C-027

Relevant decisions:
  ADR-019

Known failures:
  F-008

Recommended:
  REUSE auth.oauth
  REUSE auth.session

New implementation:
  NOT REQUIRED

这就是你说的:

AI 不要再重复造轮子。


五十七、然后 Agent API 就会自然变成

agent.preflight
agent.resolve
agent.reuse
agent.adapt
agent.create
agent.verify
agent.record
agent.learn

而不是只有:

agent.step
agent.plan

这也与现在已有的 step / plan / writeback / agent-kb 很自然地衔接。当前 Agent 已经有工作簿、任务复用、写回和 OKF agent-kb 的方向,所以我不建议推翻重来,而是在前面增加 Engineering Knowledge Resolution 层。(GitHub)


五十八、我会特别避免一个坑:不要把它做成“更大的向量数据库”

这一点非常重要。

不要:

Marqdo
=
Markdown
+
Embedding
+
Vector DB

这会把 Marqdo 的优势毁掉。

应该:

Marqdo
=
Executable Source
+
Structured Knowledge
+
Symbol Graph
+
Capability Graph
+
Versioned Evidence
+
Deterministic Retrieval
+
Semantic Retrieval

Embedding 只是:

retrieval implementation

而不是:

knowledge model

五十九、检索最好采用 Hybrid + Graph

例如:

Query
 │
 ├── lexical
 ├── symbol
 ├── semantic
 ├── capability
 └── graph
       ↓
    rerank
       ↓
   context pack

而不是:

embedding(query)
 ↓
top K

当前 OKF 生态本身也已经在往搜索、图关系、context selection 等方向发展;这说明“Markdown 只是包装,真正困难的是知识检索与上下文组织”这个判断是成立的。(Open Knowledge)


六十、我认为最重要的工程规则可以只有五条

最终我甚至建议把 Marqdo 的 Agent 工程纪律写成:

Rule 1 — Discover before Create

先发现,再创建。

Rule 2 — Reuse before Adapt

先复用,再适配。

Rule 3 — Adapt before Duplicate

能组合,不复制。

Rule 4 — Verify before Promote

验证之后,才能进入知识库。

Rule 5 — Code changes update knowledge

代码改变,知识必须重新验证。

这五条非常适合成为 Marqdo 的核心工程原则。


六十一、最终我认为 Marqdo 可以形成一个非常漂亮的闭环

             ┌─────────────────────┐
             │       Human         │
             │  "实现一个功能"      │
             └──────────┬──────────┘
                        ↓
                Engineering Intent
                        ↓
              ┌──────────────────┐
              │ Knowledge Resolve│
              └────────┬─────────┘
                       ↓
          ┌────────────┼────────────┐
          ↓            ↓            ↓
       Existing     Constraint    Decision
       Capability      │             │
          │            └──────┬──────┘
          │                   ↓
          └──────────────→ Context
                             ↓
                          Agent
                             ↓
                    REUSE / ADAPT / CREATE
                       /       |       \
                      /        |        \
                  reuse       adapt     create
                    \          |         /
                     └─────────┼────────┘
                               ↓
                           Verify
                               ↓
                       Knowledge Update
                               ↓
                      Catalog / Graph
                               ↓
                        Git / OKF Bundle
                               ↓
                    下一次任务直接受益

这时候 Marqdo 的价值就不是:

“我有一个比 Python 更适合 LLM 的语言。”

而是:

“我把软件工程项目本身变成了 AI 可以理解、执行、验证和持续学习的知识系统。”

这两个命题的战略价值完全不同。


六十二、我尤其建议你把论文/项目叙事也往这里移动

你以前的:

From Executable Documents to Executable Knowledge Bases

现在其实可以进一步变成:

From Executable Documents to Executable Engineering Knowledge

或者更强一点:

Executable Knowledge for AI-Native Software Engineering

核心研究问题变成:

How can a software repository become an executable, versioned, and queryable knowledge system that prevents redundant code generation by AI agents?

这个问题比:

“如何设计一种 LLM-native programming language?”

我认为更有工程问题意识。

因为它直接击中了当前 AI Coding Agent 的一个非常实际的问题:

AI can generate code.
But does AI understand what the project already knows?

Marqdo 的回答应该是:

Yes — because the knowledge is not maintained beside the code. The knowledge is the code's executable document representation itself.


我建议你下一阶段不要继续无边界地给 agent-kb 加功能

而是直接做一个 Marqdo Engineering Knowledge v1。

优先级我会这样排:

阶段 要做的东西 目标
P0 Symbol Catalog AI 知道工程里有什么
P0 Capability Catalog AI 知道工程能做什么
P0 reuse/preflight 生成前强制检查已有能力
P0 Context Pack 给模型第一信息,而不是整个 repo
P1 Decision / Constraint / Failure 让 AI 知道为什么、禁止什么、过去错过什么
P1 Dependency / Call / Test Graph 建立工程知识图
P1 Duplicate Detection 检测 AI 新造的重复能力
P1 Knowledge Lifecycle stale / deprecated / superseded
P2 Policy Compilation 将复用判断编译成 .mq.md
P2 Knowledge Compilation 从执行经验自动生成知识
P2 Reuse CI Gate PR 阶段阻止重复造轮子
P3 Knowledge-aware Agent Agent 原生依赖 Engineering Knowledge
P3 Benchmark 用重复率、检索召回、token amortization 衡量优势

其中我认为真正的 P0 只有三个核心组件:

Capability Catalog
        +
Reuse Preflight
        +
Engineering Context Pack

这三个做出来,Marqdo 就第一次真正开始具备你说的:

“让 AI 在大型工程中获得第一信息,并减少重复造轮子”的能力。

而且这条路线并不需要抛弃现在的 OKF、catalog、agent-kb、writeback 和 plan;恰恰相反,它们可以全部成为这个架构的基础设施。

官方仓库目前已经明确把自动 Catalog、可执行 .mq.md、OKF 风格清单和 Agent 工作簿放在同一条产品主线上。(GitHub) 我认为下一步最重要的不是再增加一个功能,而是把这些东西正式统一成一个“Engineering Knowledge Compiler”架构。

如果这个方向成立,Marqdo 最终真正独特的东西可能不是 .mq.md 这个语法本身,而是:

一个大型代码仓库在 Marqdo 中可以同时作为程序、文档、知识图谱、Agent 上下文和可复用能力目录存在,而且这些视图全部由同一份可执行源代码派生。

这才是我认为你现在最值得押注的核心。 Marqdo GitHub 仓库