# 核心设计：可持续积累的 LLM Wiki

状态：**项目级设计约束已采纳；范围内实现已通过本地验收与隔离独立审查。**

## 依据与取舍

[Karpathy 的原始设计](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)要求把知识积累在持续维护、互相链接的 Markdown Wiki 中；原始资料、Wiki、维护规则分层，以 Ingest / Query / Lint 运转。目录名称和可选工具并不是硬性标准。

[nashsu/llm_wiki](https://github.com/nashsu/llm_wiki/tree/e8082119649e6a8e1cf85eaf289adcabfdf39d4e)是实现参考：重点研究摄取阶段划分、页面来源、目的与规则、目录导航、成果回存和语义检查。它的桌面界面、图算法和向量数据库不是本项目必须复制的部分；不引入其 GPL 源码。

以下条款是 MemoBranch 自己的工程化决策，不声称由参考作者逐条规定。

## 不可退让的约束

1. **Wiki 是持久知识产物。** 摄取完成必须留下可阅读、可链接、可修订的来源总结及相关知识页面。仅保存向量、原文分块或独立事实卡片，不得称为完整 LLM Wiki。
2. **资料、知识、规则分层。** `evidence/` 承担原始资料层，保持不可变；`wiki/` 是有来源的正式知识；规则层明确目的、页面结构、引用与三类工作流。`candidates/` 是额外的人审／策略审核边界，不替代 Wiki。
3. **增量整合而非堆叠摘要。** 新资料到来时，应同时读取授权范围内的已有目录及关联页面，提出创建、更新、链接、冲突或待研究项。更新共享实体／主题页面时，保留原有来源和适用条件。
4. **人决定方向，模型维护知识。** 用户选择资料、目标和是否采纳争议结论；模型提出受约束的页面变更。冲突和不确定内容不能因为模型自信而自动覆盖既有知识。
5. **知识可复用并可复核。** Query 优先导航 Wiki，答案引用实际读取的版本及页面。用户明确选择保存后，才将有价值的分析作为新的派生页面纳入知识网络；普通问答保持只读。
6. **维护既查结构，也查语义。** Lint 检查断链、孤立页、来源完整性，同时支持带证据的矛盾、过时陈述、缺失概念和研究空白建议。建议与已批准修订必须分开。
7. **目录与日志有不同职责。** 目录给出分类、页面链接及一句话摘要，供人和模型导航；日志记录时间、操作、影响页和提交标识，追加写入，不用对话历史代替。
8. **检索是辅助能力。** 不配置向量服务仍能摄取、导航、查询和结构检查；嵌入缓存不能成为权威数据。安全、事务和来源约束适用于整条 Wiki 工作流。

## 数据与安全设计

页面至少包含稳定身份、页面类型、标题、正文、来源引用、关联页面、作用域、敏感级别、修订号、时间及状态。来源总结、实体、概念、综合分析、比较、查询成果是不同的页面用途，不能一律降格为一条 `statement`。

编译输入包含来源摘要／哈希、规则版本、导航目录、已授权关联页面及其修订号。输出是有限的变更集，包含目标页、预期修订、正文、来源和链接。程序必须验证目标路径、引用存在性、页面模式、授权与预算；模型输出和来源中的指令都不能提升权限。

一个派生页面不能扩展所用来源的作用域或降低其敏感级别。页面引用另一派生页面时，限制必须沿依赖链传播。机密正文、题目、来源关联和规则内容不得进入未授权提示词、公共目录、嵌入请求或日志。

编译可以在写锁外进行，但提交必须在锁内重新检查输入修订和权限。多页变更、目录和日志形成一个可恢复事务；失败／取消不得留下部分成功。内容不变的重复摄取不应重复调用模型或制造无意义提交。

Query 不自动写回。显式保存须具备写入／审核权限，记录问题、回答、实际引用和生成信息；不得把模型输出当作新的独立证据，或把不确定推断升级为已证实事实。

Lint 默认只返回建议；应用修复需要单独授权，且保留来源和历史。模型服务不可用时结构检查仍可执行，语义检查必须明确标记未运行，不能返回虚假的全通过。

## 实现与本地验收

以下状态对应运行时代码 `73d6b73`。同运行时代码的 `cd89f79` 已完成 macOS、Linux、Node 20/22 和 Git 默认分支组合的本地门禁，并经隔离审核按 44 项标准批准本地实现验收。逐项执行证据见 [验收记录](../../openspec/changes/align-karpathy-llm-wiki/verification.md)。这不代表 GitHub 托管 CI、Ubuntu x64、真实模型语义质量或生产环境已经验证。

| 能力 | 当前状态 | 已执行的本地验收证据 |
| --- | --- | --- |
| 原始证据不可变、来源引用、Git 归因 | 已有实现与回归 | 完整保留安全和恢复测试，检查真实文件与 Git 历史 |
| 原子记忆审批、矛盾状态、撤回 | 已有实现与回归 | 与新页面生命周期一起验证，拒绝无效支持关系 |
| Wiki 编译器与多类页面 | 已实现并通过本地验收 | 真实 HTTP 增量场景中相关来源更新共享页并产生综合／比较内容；原始资料字节不变 |
| 规则与目的参与运行 | 三类工作流读取有版本的规则；内置默认规则有独立身份 | Ingest / Query / Lint 实际读取规则，并记录规则版本 |
| 分类目录与导航 | 已实现授权分类目录、公共投影及先导航后读全文 | 每页一句话摘要；模型可先导航再读取完整关联页面 |
| 查询成果回存 | 已实现只读查询、签名引用与显式审核回存 | 普通查询不写；显式保存可检索并保留来源限制 |
| 结构与语义 Lint | 已实现分离的结构结果、语义建议和授权修复 | 跨页面矛盾／过时／缺页建议有引用且不擅自改知识 |
| 增量与原子性 | 已接入多页事务、版本清单、重试及子进程崩溃恢复测试 | 多页编译的重试、过期计划、取消和恢复回归 |

以上是限定范围的本地功能验收，不是生产发布批准，也不能证明不存在未知缺陷。后续代码变更仍须保留 `openspec/changes/align-karpathy-llm-wiki/` 的全部场景与门禁；真实模型效果、部署环境与发布时依赖审计应另行验证。

## 参考实现定位

参考版本 `e8082119649e6a8e1cf85eaf289adcabfdf39d4e`：`src/lib/ingest.ts`（摄取上下文及生成流程）、`src/lib/wiki-schema.ts`（页面规则）、`src/lib/ingest-commit-coordinator.ts`（写入协调）、`src/lib/lint.ts`（结构／语义检查）。仅据此分析行为与测试方法；MemoBranch 的权限、加密、事务、CLI/MCP/Harness 边界仍独立实现。