OpenLore 是一个面向 AI Agent 的极简知识仓库，其核心能力之一是文件夹规则（Folder Rules）：一套声明式检查，在文件落盘前和lore validate时自动拦截超标文件（行数、字节、token 超限）与坏格式知识（缺 YAML frontmatter、断链、bundle 结构错误）。本指南用最短路径讲清楚三层规则如何叠加、如何收紧单文件夹标准，以及被拦截时该怎么处理。

一、文件夹规则是什么：写入前的质量门禁 🚧

OpenLore 默认只读。一旦启用写入，规则引擎会在每个写入操作生效前完成两件事：

1. 逐文件检查：用规则标准库成员（size/lines、size/kilobytes、size/tokens、okf）校验目标文件，enforce: true的规则一旦命中，整个写入批次被拒绝；
2. 整包检查：okf/bundle、link/resolves、link/alias等 bundle 级规则不干预写入，而是由lore validate统一扫描。

规则本身是纯声明式的：每条规则用 glob 圈定一组文件，再指定一个标准库成员去检查它们。标准库全部成员及其参数见 docs/rules-stdlib.md，引擎实现位于 pkg/rules/。

二、三层规则结构：从全局到文件夹自治

对任意目标路径，引擎会把所有覆盖它的层合并成一份有效规则集。三层分别是：

lore.json rules: 全局规则，适用于所有 docset lore.json docsets.X.rules: docset X 的显示根目录下适用 <目录>/.lore/config.yaml 该目录及其子树适用

H3 层 1：lore.json全局层与 docset 层

lore.json顶层rules作用于每个 docset；docsets.<name>.rules只作用于该 docset 的显示根（paths声明的目录）。两层共用同一规则形状。仓库自带配置样例可直接参考 lore.json.example：

{ "rules": { "doc-size": { "match": ["**/*.md"], "use": "size/kilobytes", "with": { "max": 60 }, "default": true } } }

注意"default": true——它表示这条规则允许子文件夹用同名规则替换，是后续收紧标准的关键开关。

H3 层 2：.lore/config.yaml文件夹自治层

在内容树任意目录放一个.lore/config.yaml，即可给"该目录及一切子目录"追加规则：

version: 1 rules: adr-length: # 规则名，本文件内唯一 match: ["decisions/*.md"] # glob，相对本目录；支持 ** exclude: ["decisions/draft-*.md"] use: size/lines # 标准库成员 with: { max: initial, growth: 1.1 } enforce: true

规则级键只有match、exclude、use、with、enforce、default六个，成员参数一律放在with内，拼错参数名会直接报错并给出建议（如did you mean "max"?）。glob 相对所在层的作用目录匹配：*匹配单级路径，**匹配任意级。

H3 层 3：openlore.yml全局默认

openlore.yml中可设rules.growth（默认 1.25，必须 ≥ 1），作为所有max: initial规则的全局默认增长系数，详见 docs/openlore-yml.md。

三、规则如何叠加：同名替换、新名收紧、永不放宽

合并逻辑是整个机制里最容易踩坑的部分，记住三条口诀：

冲突时的报错长这样，一眼能看出该改哪一层：

.lore/config.yaml: rules.doc-size: conflicts with doc-size @ lore.json (max: 400 vs 60); use a new rule name to tighten

要点：子文件夹永远不能放宽它自己没写的规则。想给某个目录收紧标准，二选一：父层标了default: true就同名替换；否则用新规则名追加一条更严的检查。想豁免文件，则在规则所属层加exclude:，或利用嵌套 docset 的影子作用域。系统没有inherit键，目录下的配置天然覆盖其子树。合并算法可参考 pkg/rules/compile.go 中的Unify函数。

四、拦截超标文件：size 规则与增长上限 🔒

三个 size 成员分别限制行数、KiB、估算 token 数，参数相同：max（固定值或initial）加可选growth。

固定上限：简单直接

with: { max: 800 }表示永远不能超过 800 行，越界即被拒绝。

增长上限：max: initial的 baseline 机制

max: initial让文件相对自身限长：首次写入记录 baseline（KiB/行数/token 三项），之后文件不得超过baseline × growth。baseline 的生命周期很讲究：

• 新建文件：首次被接受的写入即 baseline；若该写入被其他规则拒绝，baseline 不生效，下次写入重新算"新建"；
• 给存量文件加规则：baseline 取规则生效前已有内容的大小——冻结现状，不会因为文件已经很大而拒绝下一次编辑；
• rm清空 baseline，mv把 baseline 带到新路径；
• 状态存在<dir>/.lore/size/<文件名>.jsonl，跟随内容树走，tree/ls不显示，也无法通过 VFS 读写。

查看与重置 baseline 用lore size baseline子命令（实现见 pkg/shell/cmds/lore_size.go）：

lore size baseline /docs/backend/decisions/adr-001.md # current cap: 893 lines lore size baseline reset /docs/backend/decisions/adr-001.md --note "ADR grew after review"

每条记录都署名操作者并保留完整历史，reset 还会写入服务端审计日志（rules.baseline.reset）。

读懂一次拒绝：拦截输出是给 Agent 看的说明书

被拒写入退出码非零，并打印四段式诊断：测到什么/上限是多少 → 不能做什么 → 建议怎么做 → 特权人工如何覆盖：

rules: /docs/backend/decisions/adr-001.md: size/lines (adr-length @ /docs/backend/.lore/config.yaml) 812 lines exceeds the limit of 800 (baseline 640 lines × growth 1.25, set 2026-08-30 on create) this file cannot grow past 800 lines under this rule suggested: keep adr-001.md under 800 lines; move the new material into a sibling file such as adr-001-details.md ... override: a role in config.edit can run `lore size baseline reset /docs/backend/decisions/adr-001.md` see: lore package doc size/lines

size/*的补救建议是"渐进披露"：把新材料拆到同级文件并从原文件加链接，而不是反复小幅度删减。规则引擎源码分别在 pkg/rules/size/ 与 pkg/rules/okfrule/。

五、拦截坏格式知识：okf 与 link 规则 📐

坏格式知识的拦截分 file 与 bundle 两个作用域，运行时机完全不同：

• okf（坏格式的第一道闸）：每个概念文件必须以---分隔的 YAML frontmatter 开头，写入时即拒绝：

okf: /docs/bad.md: missing YAML frontmatter block (a concept must open with a '---' delimited block) see: lore package doc okf

• bundle 规则为何不在写入时跑：一次合法写入可能暂时破坏整包一致性（新增概念要等index.md后续更新、链接目标可能下一步才写入），写入路径拒绝或告警都是噪音，所以交给lore validate。

这带来一个关键结论：**退出码为 0 的写入是"已保存"，不是"已验证"。**含断链的文件会被所有写入动词接受，只有lore validate <docset 根>才报告。因此推荐"写 → 验 → 完"闭环：一次变更的最后一笔写入后运行lore validate，以其退出状态作为完成条件（完整工作流见 docs/writing.md）。注意要在每个 docset 或文件夹下运行，不能在/下运行——否则 bundle 规则会静默缺席，命令会直接拒绝并提示。

六、权限控制：谁能改规则，谁来兜底 🔐

规则文件本身就是被治理对象，编辑门槛是双条件：

1. 对目标目录拥有该 docset 下的写权限；
2. 角色列在该 docset 的config.edit名单中。

"config": { "edit": ["engineer"] }

没有配置config.edit的 docset，没有任何人能写它的文件夹配置；可读文件夹的人即可读其配置。删除同样受此闸门约束：rm配置文件需双条件；rm -r一棵含多个配置的目录树，则每一棵配置都要满足双条件，否则整个删除失败——否则普通rw角色就能靠"删了重建"甩掉一整套治理。lore size baseline reset因为是"给单个文件松绑"，走同一权限通道。

七、最佳实践清单 ✅

1. 全局只留宽松默认（如size/kilobytes: max 60并标default: true），让子文件夹可以放心同名替换；
2. 收紧标准用新规则名，避免与未标default的外层规则冲突；
3. 决策记录等"冻结型"文档用max: initial + growth，天然防止知识文件无限膨胀；
4. 每次变更收尾跑lore validate，把 bundle 级坏格式挡在合并前；
5. token 上限留余量：size/tokens使用内置估算器estimate/v1（ceil(bytes / 4)），是近似值；
6. 遇到拒绝按suggested:执行，或向人工索要override:命令，不要盲目重试。

完整机制、错误信息格式与真实案例的权威出处是 docs/folder-rules.md；会话内随时可用lore package list查看成员作用域、lore package doc <member>查阅单条成员文档，无需离开终端。