- 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。
2819 lines
43 KiB
Markdown
Executable File
2819 lines
43 KiB
Markdown
Executable File
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"
|