Establish author baseline fixtures and offline tests, make SemanticProject the sole authority for graph edges, classify named steps, and tighten local reuse so unknown effects are not pure and MLSP binds by SymbolId. Co-authored-by: Cursor <cursoragent@cursor.com>
3.9 KiB
Engineering Knowledge Compiler(EKC)
| 状态 | Accepted(v1 已落地) |
| 日期 | 2026-09-28 |
| 提案 | next/008.md |
| 相关 | okf.md · catalog-cli.md · ext-agent.md |
1. 定位
Marqdo 把仓库投影为 可查询、可验证、可复用 的工程知识系统。Source of Truth 仍是 *.mq.md;.marqdo/** 是 GENERATED 投影。
.mq.md ──► EKC ──► Executable + Catalog L0–L4 + Graph + Context Pack
│
▼
Agent preflight (REUSE → ADAPT → CREATE)
Engineering First Information (EFI):生成代码前先获得已有能力、约束、决策、失败经验与推荐复用。
2. 五层 Catalog
| 层 | 内容 | 落盘 |
|---|---|---|
| L0 Repository | 语言/规模 | .marqdo/catalog/repository.mq.md |
| L1 Module | imports/exports/responsibility | .marqdo/catalog/modules/ |
| L2 Symbol | signature/calls/fingerprint | .marqdo/catalog/symbols/ |
| L3 Capability | 工程能做什么 | .marqdo/catalog/capabilities/ |
| L4 Knowledge | Decision/Constraint/Failure/… | .marqdo/knowledge/{decisions,constraints,…}/ |
既有 marqdo catalog 根级 catalog.yaml / index.md / modules/ / concepts/ 保留;catalog 成功后默认再跑 EKC(--no-knowledge 可关)。
3. 知识类型(OKF type)
| type | 含义 |
|---|---|
Capability / Function |
能力与符号投影 |
Decision |
为什么这样做 |
Constraint |
必须/禁止 |
Failure / AntiPattern |
负面知识 |
Pattern / Migration / Fact |
模式、迁移、事实 |
Marqdo Context Pack |
Agent 上下文制品 |
Marqdo Policy |
复用决议编译结果 |
Marqdo Engineering Knowledge |
总览 / engineering.yaml |
未知 type 优雅降级(可读,不专属逻辑)。
4. 图边
implements · uses · depends_on · tested_by · documented_by · constrained_by · decided_by · supersedes · conflicts_with · deprecated_by · derived_from · failed_by · related_to
落盘(G01 分离后):
- 权威语义图:
.marqdo/graph/edges.json·nodes.json(SemanticProject,含authority字段)·steps.json - EKC 检索投影(非执行依据):
.marqdo/ekc/graph/graph.json·edges.json·index.json
5. CLI
marqdo knowledge [PATH] -o .marqdo # compile(默认)
marqdo knowledge preflight "task"
marqdo knowledge record REUSE
marqdo knowledge learn --task ... --failure ...
marqdo find "authentication"
marqdo reuse "implement oauth login"
marqdo impact path/to/file.mq.md
marqdo conflicts | stale | duplicate [--fail] | verify
统一 --json。duplicate 默认阈值 0.75;--fail 作 CI Gate。
6. Reuse 协议
三态:REUSE → ADAPT → CREATE(硬顺序)。Reuse budget:min_candidates / allow_create_after。仅 create_allowed: true 时允许盲生成。
7. Context Pack
.marqdo/agent/contexts/task-<id>.mq.md:Task / Existing Capabilities / APIs / Constraints / Decisions / Failures / Recommended / Forbidden。
8. Agent
- Plugin:
agent_eng_preflight/agent_eng_reuse/agent_eng_record - Facade:
agent.preflight·agent.eng_reuse·agent.eng_record agent.plan … eng_preflight=True在 agent-kb 之前跑 EFI;缺知识图时missing_knowledge放行(兼容纯 agent-kb 测试)
9. 指标
.marqdo/agent/episodes/reuse_metrics.json:reuse_ratio / adapt_ratio / novel_ratio / duplication_rate。
10. 原则(五条)
- Discover before Create
- Reuse before Adapt
- Adapt before Duplicate
- Verify before Promote
- Code changes update knowledge
不做:以向量库为知识模型;embedding 仅可选检索实现,默认关闭。Hybrid = lexical + symbol + capability + graph。