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 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"