- 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。
43 KiB
Executable File
实现状态(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 仓库