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

2819 lines
43 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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`](../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][1])
同时,新的 Agent 设计也已经明确:源码、调用位置、Skill、工作簿和写回结果都应该进入 Agent 上下文,而且成功/失败结果应该沉淀,而不是只存在于 chat transcript。([GitHub][2])
**现在真正缺的,是把这两个方向合成一个“工程知识编译器”。**
---
# 一、我先给出我认为 Marqdo 应该最终形成的核心模型
我建议不要再把 Marqdo 简单理解成:
```text
Markdown
↓
Programming Language
↓
AI Agent
```
而应该是:
```text
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 找到了正确函数,但是不知道它有哪些隐含约束。”
例如一个大型工程里可能已经存在:
```text
parseConfig()
loadConfig()
resolveConfig()
normalizeConfig()
mergeConfig()
validateConfig()
readConfigFile()
```
用户让 AI:
> “实现一个配置加载功能。”
普通 Coding Agent 很可能:
```text
搜索几个文件
↓
发现没完全一样
↓
写一个新的 load_configuration()
↓
加 300 行代码
↓
测试通过
```
从局部看:
> 成功。
从工程看:
> **失败。**
因为真正正确的行为可能是:
```text
resolveConfig()
+
validateConfig()
+
已有错误处理
```
AI 的核心问题其实是:
```text
工程知识缺失
↓
无法识别已有能力
↓
重复实现
↓
代码碎片化
↓
维护成本上升
```
---
# 三、所以我建议 Marqdo 提出一个非常明确的概念
## Engineering First Information
我会把它定义成:
> **Engineering First Information(工程第一信息)**
也就是:
> AI 在修改/生成代码之前,首先获得关于当前工程中已有能力、约束、依赖、约定、历史决策和可复用实现的最小充分信息。
这个概念非常适合成为 Marqdo 的核心论文/产品概念。
因为普通 RAG 是:
```text
query
↓
retrieve documents
↓
LLM
```
而 Marqdo 应该是:
```text
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 明确把:
```text
叙述
代码
返回
对象
函数
表格
```
都统一在 Markdown 中。([GitHub][1])
这意味着 Marqdo 天生拥有:
```text
Source
+
Documentation
```
的共址关系。
---
### 2. 已经有自动 Catalog
当前已经存在:
```text
marqdo catalog
marqdo sync
```
并生成:
```text
catalog.yaml
index.md
modules/*.md
```
而且 README 特别强调这些是从源码自动派生的,而不是手工维护。([GitHub][1])
这个非常重要。
因为:
> **不要让 AI 再去“猜”项目有什么。**
Catalog 就应该成为第一层事实来源。
---
### 3. Agent 已经开始把源码作为上下文
新的 Agent 设计明确要求:
```text
源码
调用位置
Skill
相关写回块
工作簿
```
进入模型上下文。([GitHub][2])
而且新的设计已经放弃“隐藏 chat history 作为真相”,转向:
> **文档写回 + 工作簿 = 真相。**
([GitHub][2])
这个方向我认为是非常正确的。
---
# 五、但这里有一个关键缺口
现在的系统更接近:
```text
Task
↓
Agent
↓
查源码 / Skill / 写回
```
而我要推动它成为:
```text
Task
↓
Engineering Intent
↓
Engineering Knowledge Resolution
↓
Reuse Gate
↓
Generate / Modify
↓
Verify
↓
Knowledge Update
```
也就是说:
> **“知识检索”不能只是 Agent 的一个上下文增强功能,而应该成为代码生成的强制前置阶段。**
这是非常重要的架构变化。
---
# 六、我建议新增一个核心层:Engineering Knowledge Compiler
可以简称:
```text
EKC
Engineering Knowledge Compiler
```
或者更 Marqdo 一点:
```text
Marqdo Knowledge Compiler
```
职责:
```text
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][3])
所以:
> **不要把 Marqdo 做成“另一个 OKF”。**
应该:
```text
OKF
↓
Knowledge Packaging Layer
Marqdo
↓
Engineering Knowledge Execution Layer
```
也就是:
```text
OKF
↓
Marqdo Engineering Profile
↓
Executable Engineering Knowledge
```
这是我认为最优雅的关系。
---
# 八、Marqdo 应该在 OKF 上增加“工程知识类型”
例如:
```text
Marqdo OKF
```
里面不只是:
```text
Module
Document
Concept
```
而应该出现:
```text
Function
Type
API
Capability
Pattern
Decision
Constraint
Example
Test
Workflow
Error
Dependency
Migration
Deprecated
```
例如一个函数:
```markdown
---
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 不应该只搜索:
```text
函数名字
```
而应该搜索:
```text
Capability
```
例如用户:
> “我要把配置文件加载出来。”
Agent 首先构造:
```yaml
intent:
domain: configuration
capability: resolve
input: configuration_source
output: normalized_config
constraints:
- existing architecture
- existing error handling
```
然后查:
```text
Capability Index
```
得到:
```text
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 下一阶段非常重要的改造。
现在:
```text
catalog
```
容易理解成:
> “项目里有哪些文件。”
但真正应该是:
> **Engineering Capability Catalog**
也就是:
```text
文件
模块
对象
函数
类型
接口
能力
关系
约束
示例
测试
```
全部进入 Catalog。
---
# 十一、建议建立 5 层 Catalog
## L0:Repository
```text
repository
```
知道:
```text
语言
模块
目录
依赖
构建系统
测试系统
```
---
## L1:Module
```text
module
```
知道:
```text
exports
imports
responsibility
dependencies
public API
```
---
## L2:Symbol
```text
function
class
type
constant
endpoint
```
知道:
```text
signature
location
visibility
calls
called_by
tests
```
---
## L3:Capability
这是最重要的一层:
```text
capability
```
例如:
```text
"parse configuration"
"validate JWT"
"retry HTTP request"
"serialize JSON"
"resolve dependency"
```
它不等于函数。
一个 Capability 可以映射到:
```text
1 function
3 functions
1 module
1 workflow
```
---
## L4:Engineering Knowledge
再往上:
```text
Decision
Constraint
Pattern
Anti-pattern
Reason
Migration
Failure
```
例如:
> 为什么不能直接调用 `foo()`?
因为:
```text
foo()
↓
必须先 initialize_context()
```
这个信息对 AI 极其重要。
---
# 十二、我建议把“复用”从搜索升级成一个正式协议
新增:
```text
agent.reuse
```
或者:
```text
knowledge.reuse
```
它不是:
```text
search("foo")
```
而是:
```text
reuse(task)
```
返回:
```json
{
"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"
]
}
```
如果没有合适的:
```json
{
"decision": "create",
"reason": "no existing capability satisfies constraints"
}
```
---
# 十三、这一步非常重要:AI 必须允许“证明不存在”
否则会出现另一个问题:
AI 搜索了一遍没找到,就自己写。
所以应该有:
```text
Reuse Resolution
```
三个结果:
```text
REUSE
ADAPT
CREATE
```
而不是:
```text
FOUND
NOT FOUND
```
---
# 十四、三个状态分别代表什么
### REUSE
已有能力满足需求。
```text
直接调用
```
---
### ADAPT
存在相近能力。
```text
包装
组合
参数化
扩展
```
例如:
```text
A
+
B
→
新的 capability
```
而不是复制 A。
---
### CREATE
经过检索和分析确认:
> 工程中不存在合适能力。
才允许生成。
这个顺序应该成为 Marqdo Agent 的**硬规则**:
```text
REUSE
↓
ADAPT
↓
CREATE
```
而不是:
```text
CREATE
↓
maybe reuse
```
---
# 十五、再进一步:把“重复代码”变成可检测知识
这一步我认为会非常有意思。
Marqdo Compiler 可以生成:
```text
symbol fingerprint
```
例如:
```text
function:
normalize_config
fingerprint:
inputs:
map<string, any>
output:
normalized_config
operations:
parse
merge
validate
```
另一个函数:
```text
normalize_settings
```
可能得到:
```text
semantic similarity: 0.91
```
于是 Catalog 标记:
```text
possible_duplicate
```
---
# 十六、于是可以出现一个非常强的命令
```bash
marqdo reuse-check
```
输出:
```text
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
例如:
```yaml
knowledge:
reuse:
required: true
duplicate_threshold: 0.90
```
PR 中新增:
```text
normalize_settings()
```
CI:
```text
⚠ Potential duplicate capability
Existing:
config.normalize_config
New:
settings.normalize_settings
Similarity: 0.93
Recommendation:
REUSE existing capability
```
然后:
```text
marqdo check
```
直接失败或者 warning。
---
# 十八、这会产生一个非常漂亮的工程闭环
```text
Human asks feature
↓
Agent resolves intent
↓
Knowledge Catalog
↓
Existing Capability?
/ \
yes no
↓ ↓
REUSE CREATE
↓ ↓
Execute Generate
↓ ↓
Verify Verify
↓ ↓
└──────┬────┘
↓
Update Knowledge
↓
Update Catalog
↓
Git Commit
```
下一次:
```text
同类需求
↓
直接找到上一轮能力
```
这就是你说的:
> **工程越大,Marqdo 越有价值。**
---
# 十九、但还有一个更大的问题:Knowledge 必须知道“为什么”
这是很多 RAG 系统做不到的。
例如:
```text
use redis_cache
```
只是事实。
真正有价值的是:
```markdown
# 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
例如:
```markdown
---
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
例如:
```markdown
---
type: Constraint
---
# Database access
All database access must go through `repository/*`.
Direct SQL from HTTP handlers is prohibited.
```
于是 Agent 搜索:
```text
"how should I access the database?"
```
得到:
```text
Constraint
+
Repository capability
+
Example
```
这就是**第一信息**。
---
# 二十二、再增加一种极其重要的知识:Negative Knowledge
我认为这是 Marqdo 可以做得非常漂亮的地方。
传统知识库主要记录:
```text
应该做什么
```
但大型工程更需要:
```text
不要做什么
```
例如:
```markdown
---
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 造轮子。
---
# 二十三、我甚至建议把知识分成四种
```text
FACT
↓
工程里有什么
RULE
↓
工程要求怎么做
DECISION
↓
为什么这样做
FAILURE
↓
什么东西以前做错过
```
于是:
```text
Engineering Knowledge
├── Facts
├── Rules
├── Decisions
└── Failures
```
这四类东西结合起来,才是真正的工程知识。
---
# 二十四、失败经验尤其适合你现在的 Agent
目前 Agent 设计已经强调:
> 成功和失败都写回文档,失败块成为可读的“避坑记录”。([GitHub][2])
我建议把它正式升级成:
```text
Failure Knowledge
```
例如:
```markdown
---
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 遇到:
> “我要缓存权限判断。”
第一条知识就可能是:
```text
⚠ Historical failure detected.
```
这比一般 RAG 强得多。
---
# 二十五、然后你会得到一个很漂亮的 Knowledge Graph
例如:
```text
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 不是另建的
这是最关键的一点。
普通系统:
```text
Code
↓
Vector DB
↓
Knowledge Graph
↓
RAG
```
会出现:
```text
Code ≠ Knowledge
```
最终:
```text
代码改了
知识没改
```
然后:
> AI 得到旧信息。
---
# 二十七、Marqdo 应该做到反过来
```text
.mq.md
│
├── executable AST
├── documentation
├── knowledge
├── symbol graph
└── catalog
```
**一个源头,多个投影。**
也就是说:
```text
Source of Truth
│
├── Execution
├── Documentation
├── OKF
├── Search Index
├── Symbol Graph
└── Agent Context
```
这才是:
> **代码即文档,文档即知识库**
真正有技术含量的地方。
---
# 二十八、因此 Catalog 不应该被看成“生成出来的 Markdown”
它应该是:
> **Marqdo AST 的 Knowledge Projection。**
例如:
```text
Marqdo AST
↓
Knowledge Extractor
↓
Knowledge IR
↓
┌────────────────────────────┐
│ │
├── catalog.yaml │
├── index.md │
├── modules/*.md │
├── symbols/*.md │
├── capabilities/*.md │
├── graph.json │
└── search index │
```
OKF 是其中的一个**可移植输出格式**。
---
# 二十九、这会直接解决大规模工程的 Context Window 问题
这是另一个非常重要的价值。
假设工程:
```text
5 million lines
```
不可能:
```text
把整个 repo 给 GPT
```
也不应该:
```text
向量搜索 top 20 chunks
```
因为 top 20 chunks 经常没有结构。
Marqdo 应该做:
```text
Task
↓
Intent
↓
Catalog
↓
Module
↓
Capability
↓
Symbol
↓
Source
```
这是:
> **Hierarchical Retrieval**
而不是:
> flat vector retrieval。
---
# 三十、我建议采用 Progressive Disclosure
第一层:
```text
What exists?
```
返回:
```text
20 candidates
```
第二层:
```text
What are their responsibilities?
```
返回:
```text
5 capabilities
```
第三层:
```text
Which one applies?
```
返回:
```text
2 candidates
```
第四层:
```text
How do I use it?
```
返回:
```text
signature
example
constraints
```
第五层:
```text
Show implementation.
```
才打开源码。
---
# 三十一、这样模型看到的上下文会非常小
例如用户:
> 添加 OAuth 登录。
模型首先只看到:
```text
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
```
然后模型才决定:
```text
REUSE auth.oauth
REUSE auth.session
ADAPT callback
```
**它根本没有机会先写一个新的 OAuth 系统。**
这就是你要解决的问题。
---
# 三十二、所以我建议 Agent 增加一个“工程前置协议”
现在:
```text
agent.step
agent.plan
```
我建议最终变成:
```text
agent.step
↓
knowledge.preflight
↓
reuse.resolve
↓
agent.step
```
复杂任务:
```text
agent.plan
↓
knowledge.preflight
↓
architecture.resolve
↓
reuse.resolve
↓
plan
```
---
# 三十三、可以把它正式设计成:
```text
## preflight
```
输入:
```text
task
```
输出:
```yaml
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
```
只有:
```text
create_allowed: true
```
才能进入生成阶段。
---
# 三十四、这里我甚至建议加入“Reuse Budget”
例如:
```yaml
agent:
reuse:
min_candidates: 3
require_preflight: true
require_reason: true
allow_create_after: 2
```
意思:
> AI 至少分析两个已有候选之后,才能说“工程里没有”。
这会非常有效。
---
# 三十五、再进一步:生成的代码必须声明它复用了什么
例如:
```markdown
---
type: Function
name: create_session
reuse:
- auth.session
- crypto.token
---
```
这样 Catalog 可以反向建立:
```text
create_session
├── reused auth.session
└── reused crypto.token
```
---
# 三十六、这会产生一个极有价值的指标
## Reuse Ratio
例如:
```text
Generated functions: 1000
Reused existing capability: 730
Adapted existing capability: 180
New capability: 90
```
得到:
```text
Reuse Ratio = 73%
Adapt Ratio = 18%
Novel Ratio = 9%
```
这比:
> “AI 写代码很快”
更有工程意义。
---
# 三十七、再进一步,可以衡量 AI 的“重复造轮子率”
定义:
```text
Duplication Rate
=
new implementations
that semantically duplicate existing capabilities
/
all new implementations
```
目标:
```text
越低越好
```
这就是 Marqdo 非常适合做实验的数据。
---
# 三十八、再进一步:Reasoning Amortization + Reuse
你之前的 Agent 思路里面已经有:
> 大模型探索 → 小模型/Jev 决策 → Marqdo 执行 → 逐渐编译。
现在可以再加一个:
> **Knowledge Amortization**
也就是:
```text
第一次:
LLM + repo exploration
第二次:
Catalog + small model
第三次:
Capability match
第四次:
Deterministic reuse
```
于是:
```text
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 再升级成:
```text
1. Knowledge Compilation
2. Policy Compilation
3. Code Compilation
```
---
## 1. Knowledge Compilation
```text
Source
↓
Fact
Decision
Constraint
Capability
Failure
```
↓
```text
OKF
```
---
## 2. Policy Compilation
```text
Task
↓
Which capability?
↓
Which module?
↓
Which function?
```
↓
```text
policy.mq.md
```
---
## 3. Code Compilation
```text
Capability
+
Policy
+
Constraints
```
↓
```text
Executable Marqdo
```
---
# 四十、最终形成:
```text
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][4])
Marqdo 做工程知识时尤其需要:
```text
draft
↓
verified
↓
stable
↓
deprecated
↓
superseded
```
---
# 四十二、每个 Capability 都应该有“新鲜度”
例如:
```yaml
status: stable
introduced: v2.3
verified: 2026-09-20
last_used: 2026-09-28
last_tested: 2026-09-28
```
这样 Agent 可以知道:
```text
这个能力存在
```
和:
```text
这个能力现在还可靠
```
是两个问题。
---
# 四十三、再加入 Evidence
例如:
```yaml
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][5])
---
# 四十四、甚至可以引入非常轻量的 Confidence
例如:
```yaml
confidence: high
evidence:
implementation: verified
tests: verified
runtime: verified
```
而不要只:
```yaml
confidence: 0.97
```
因为:
```text
0.97
```
对 Agent 来说没有解释能力。
---
# 四十五、再解决一个非常大的问题:知识冲突
例如:
```text
A.md:
Redis is source of truth.
B.md:
Redis is cache only.
```
普通 RAG:
```text
retrieve A
retrieve B
LLM 自己猜
```
Marqdo:
```text
Conflict detected
↓
A ↔ B
↓
same capability
↓
different claims
↓
Decision/Authority resolution
```
最终:
```text
Decision-014 supersedes A
```
而不是让模型自己选择。
---
# 四十六、因此我建议增加 Knowledge Graph Edge
最重要的几种:
```text
implements
uses
depends_on
tested_by
documented_by
constrained_by
decided_by
supersedes
conflicts_with
deprecated_by
derived_from
failed_by
```
这会让工程知识从:
```text
文件集合
```
变成:
```text
关系系统
```
---
# 四十七、然后 Catalog 查询就会非常强
例如:
```bash
marqdo knowledge find "authentication"
```
得到:
```text
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][2])
但下一步应该进一步:
```text
Agent
↓
Knowledge Resolver
↓
Context Pack
```
而不是:
```text
Agent
↓
自己搜索几十个 md
```
---
# 四十九、Context Pack 应该有固定结构
例如:
```markdown
# 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
```
这个东西本身又是:
```text
.mq.md
```
于是:
> **Agent Context 本身也是 Marqdo Artifact。**
这一步我非常推荐。
---
# 五十、这就是我认为真正优雅的地方
不要让:
```text
RAG
```
成为一个黑盒:
```text
query → vector db → prompt
```
而是:
```text
Task
↓
Knowledge Query
↓
Context Artifact
↓
Agent
```
例如:
```text
.marqdo/context/
task-183.mq.md
```
里面记录:
```text
用了哪些知识
为什么选这些知识
哪些候选被排除
哪些约束生效
```
于是 Agent 的上下文也可以:
```text
view
debug
git diff
review
replay
```
这完全符合 Marqdo 的哲学。
---
# 五十一、这还能解决“AI 为什么这样写”的问题
未来代码 review 可以直接问:
> 为什么这里调用 `resolve_config`?
Marqdo 可以回答:
```text
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 甚至可以自动生成“知识影响”
例如:
```text
Changed:
src/config/resolve.mq.md
```
系统自动告诉 Agent:
```text
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 真正适合“大型工程”的原因
小项目:
```text
10 files
```
这个东西意义有限。
但是:
```text
1000 modules
10000 functions
100000 tests
```
以后:
```text
AI context
```
真正的瓶颈不再是模型能力。
而是:
> **工程知识的组织。**
这恰恰是 Marqdo 可以解决的。
---
# 五十四、我建议最终形成一个 `.marqdo/` 目录
我会设计成:
```text
.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 仍然是:
```text
*.mq.md
```
---
# 五十五、最关键的几个命令
我建议未来 Marqdo CLI 出现这样一组能力:
```bash
marqdo catalog
```
生成工程目录。
```bash
marqdo knowledge
```
生成/维护知识。
```bash
marqdo find
```
找工程能力。
```bash
marqdo reuse
```
判断是否应该复用。
```bash
marqdo impact
```
分析修改影响。
```bash
marqdo conflicts
```
检查知识冲突。
```bash
marqdo stale
```
检查过期知识。
```bash
marqdo duplicate
```
检查重复能力。
```bash
marqdo verify
```
验证代码 + 知识一致性。
---
# 五十六、其中最重要的是 `marqdo reuse`
我甚至认为它可以成为 Marqdo 的“杀手级命令”。
例如:
```bash
marqdo reuse "implement oauth login"
```
输出:
```text
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 就会自然变成
```text
agent.preflight
agent.resolve
agent.reuse
agent.adapt
agent.create
agent.verify
agent.record
agent.learn
```
而不是只有:
```text
agent.step
agent.plan
```
这也与现在已有的 `step / plan / writeback / agent-kb` 很自然地衔接。当前 Agent 已经有工作簿、任务复用、写回和 OKF agent-kb 的方向,所以我不建议推翻重来,而是**在前面增加 Engineering Knowledge Resolution 层**。([GitHub][2])
---
# 五十八、我会特别避免一个坑:不要把它做成“更大的向量数据库”
这一点非常重要。
不要:
```text
Marqdo
=
Markdown
+
Embedding
+
Vector DB
```
这会把 Marqdo 的优势毁掉。
应该:
```text
Marqdo
=
Executable Source
+
Structured Knowledge
+
Symbol Graph
+
Capability Graph
+
Versioned Evidence
+
Deterministic Retrieval
+
Semantic Retrieval
```
Embedding 只是:
```text
retrieval implementation
```
而不是:
```text
knowledge model
```
---
# 五十九、检索最好采用 Hybrid + Graph
例如:
```text
Query
│
├── lexical
├── symbol
├── semantic
├── capability
└── graph
↓
rerank
↓
context pack
```
而不是:
```text
embedding(query)
↓
top K
```
当前 OKF 生态本身也已经在往搜索、图关系、context selection 等方向发展;这说明“Markdown 只是包装,真正困难的是知识检索与上下文组织”这个判断是成立的。([Open Knowledge][6])
---
# 六十、我认为最重要的工程规则可以只有五条
最终我甚至建议把 Marqdo 的 Agent 工程纪律写成:
### Rule 1 — Discover before Create
```text
先发现,再创建。
```
### Rule 2 — Reuse before Adapt
```text
先复用,再适配。
```
### Rule 3 — Adapt before Duplicate
```text
能组合,不复制。
```
### Rule 4 — Verify before Promote
```text
验证之后,才能进入知识库。
```
### Rule 5 — Code changes update knowledge
```text
代码改变,知识必须重新验证。
```
这五条非常适合成为 Marqdo 的核心工程原则。
---
# 六十一、最终我认为 Marqdo 可以形成一个非常漂亮的闭环
```text
┌─────────────────────┐
│ 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 的一个非常实际的问题:
```text
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 只有三个核心组件**:
```text
Capability Catalog
+
Reuse Preflight
+
Engineering Context Pack
```
这三个做出来,Marqdo 就第一次真正开始具备你说的:
> **“让 AI 在大型工程中获得第一信息,并减少重复造轮子”的能力。**
而且这条路线并不需要抛弃现在的 OKF、`catalog`、`agent-kb`、`writeback` 和 `plan`;恰恰相反,**它们可以全部成为这个架构的基础设施。**
官方仓库目前已经明确把自动 Catalog、可执行 `.mq.md`、OKF 风格清单和 Agent 工作簿放在同一条产品主线上。([GitHub][1])
我认为下一步最重要的不是再增加一个功能,而是把这些东西**正式统一成一个“Engineering Knowledge Compiler”架构**。
如果这个方向成立,Marqdo 最终真正独特的东西可能不是 `.mq.md` 这个语法本身,而是:
> **一个大型代码仓库在 Marqdo 中可以同时作为程序、文档、知识图谱、Agent 上下文和可复用能力目录存在,而且这些视图全部由同一份可执行源代码派生。**
这才是我认为你现在最值得押注的核心。 [Marqdo GitHub 仓库](https://github.com/cflmy/marqdo?utm_source=chatgpt.com)
[1]: https://github.com/cflmy/marqdo "GitHub - cflmy/marqdo: Marqdo — A literate programming language built on Markdown. Code is document, document is executable. 中文配套:基于 Markdown 文法的文学编程语言,代码即是文档,文档可直接运行。 · GitHub"
[2]: https://github.com/cflmy/marqdo/blob/main/doc/design/ext-agent.md "marqdo/doc/design/ext-agent.md at main · cflmy/marqdo · GitHub"
[3]: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md?utm_source=chatgpt.com "knowledge-catalog/okf/SPEC.md at main · GoogleCloudPlatform/knowledge-catalog · GitHub"
[4]: https://github.com/GoogleCloudPlatform/knowledge-catalog/discussions/87?utm_source=chatgpt.com "KCP's production experience with OKF's three open problems — and a bridge command · GoogleCloudPlatform knowledge-catalog · Discussion #87 · GitHub"
[5]: https://github.com/GoogleCloudPlatform/knowledge-catalog/issues/151?utm_source=chatgpt.com "Proposal: graded confidence — an epistemic-reliability axis, distinct from integrity (#140) and citation (#92/#94) · Issue #151 · GoogleCloudPlatform/knowledge-catalog · GitHub"
[6]: https://openknowledge.sh/wiki/changelog/cli.html?utm_source=chatgpt.com "Cli - Open Knowledge"