Files
marqdo/doc/design/engineering-knowledge.md
T
cflmyandCursor ecbdd18303 feat: executable-knowledge S0–S1 gate plus effect and MLSP reuse subset
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>
2026-10-23 22:52:06 +08:00

3.9 KiB
Raw Blame History

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. 原则(五条)

  1. Discover before Create
  2. Reuse before Adapt
  3. Adapt before Duplicate
  4. Verify before Promote
  5. Code changes update knowledge

不做:以向量库为知识模型;embedding 仅可选检索实现,默认关闭。Hybrid = lexical + symbol + capability + graph。