llmdoc / docs / concepts

核心概念

真正有用的问题不是“模型能装多少上下文”，而是“什么上下文足以解决当前任务”。

Context Floor

Context Floor 是 Agent 解决当前问题所需的上下文丰富度。工具调用数量、Token 占用和关键信息密度，共同决定到达这条线需要多久。

llmdoc 在广泛探索源码前提高信息密度，但不替代源码。它收窄工作集后，原生工具继续核对实现文本、行号、测试与 Git 状态等实时事实。

设计模型：语义路由图

llmdoc 不是仓库的压缩副本，而是最小且连通的持久工程知识图：让 Agent 找到正确 owner，理解约束当前任务的设计决策，再进入权威源码核对实时事实。

• 决策优先于观察：文档保存理由、边界、不变量、契约、失败语义与高风险工作流；源码、测试、schema 和 manifest 保存实时事实。
• 所有权优先于目录：知识跟随稳定职责与 review 边界，而不是机械映射 package 或文件夹。
• 渐进披露：地图、路由元数据、选中正文与源码构成逐层加深的读取路径。
• 复核耦合：code.paths 把代码变化连到可能需要复核的文档，而不是制造文件覆盖率。

渐进读取

检索面逐层披露：先给地图或元数据，再按搜索或源码所有权定位，最后读取选中的正文。调用者可以在任一层停止。

tree / index  →  search / context  →  show

三道知识门

Retrieval Gate

首次广泛探索前，以及进入新子系统时，选择一个符合当前意图的 CLI 入口。

Reflection Gate

用户纠正、验证失败和重大返工可以形成隐私安全的临时候选；完整会话与偶发错误不会。

Stable Knowledge Gate

只有足够持久、会改变未来选择、归属清晰且难以从真相源快速还原的候选，才进入跟踪知识。

文档模型

V3 使用带 YAML front matter 的纯 Markdown .mdx 文档。路径就是文档 ID。文档树由根 singleton 和一层 topic 目录组成，topic 不需要 index.mdx。

llmdoc/
├── architecture.mdx
├── api-client/
│   └── retry-policy.mdx
└── meta.json

从 domain 到 topic 再到 document

Domain 是分析边界：一组稳定职责、权威归属、不变量、失败模型和变更词汇。Topic 是它在 llmdoc/ 下的持久检索邻域。Document 是一个完整问题、契约、不变量簇或工作流的 canonical owner。

Package 边界只是证据。所有权、失败语义或常见查询能够独立稳定时才拆 topic；跨 package 的代码若共同实现一个契约，则应归入同一语义域。根文档只承载真正跨 topic 的知识。

architecture 用于边界、流程、设计因果与不变量；guide 用于带验证和恢复步骤的可重复工作流；reference 用于稳定契约、精确查表与决策矩阵。

两道独立门

Stable Knowledge Gate 决定哪些正文值得长期保存；Routing Gate 则检查自然语言概念查询和代表性决策源码能否到达正确 owner。正文精炼不能掩盖路由缺失，映射源码也不等于要在正文逐文件复述。

validate 只检查结构。Context Floor 验收还要用自然语言 search、逐个入口与叶子文件的 context --files、宽 glob 的无关兄弟负例，以及必读关系做验证。每个 first-class 子系统都必须被归类为“已文档化”“有意由源码重建”，或作为阻塞缺口报告。

有效性以 Git 为基础

llmdoc/meta.json 跟踪经过验证的 Git revision。工作树 dirty 是额外信号，不会被伪装成 revision。delta 命中意味着必须复核，并不自动意味着正文需要改写。