agent-wiki

name	agent-wiki
description	按 Karpathy LLM Wiki 模式运营智能体知识库：Ingest 采集入库（价值契约、价值判定与中止、质量过滤器、蒸馏落地状态标记）、Query 检索回填、Lint 体检（结构层七维+判断层回测），并执行 Planner/Generator/Evaluator 角色分离。核心流程与采集工具解耦，可跨平台移植。当用户要求采集文章/素材入库、摄入新知识、查询知识库、知识库体检/lint、蒸馏知识为 Memory/规范/Skill，或运营任何 LLM Wiki 式知识库时使用。

知识库运营工作流（LLM Wiki 模式）

定位与适用

本 Skill 是平台无关的方法论：把外部知识转化为智能体运行时可调用的行为规则（Memory/规范/Skill）。知识库不是收藏夹，是智能体的能力增长引擎——每条入库知识都必须经过蒸馏，判断价值的唯一标准是：它能否直接改变智能体在具体场景下的行为决策。

• 若项目已有自己的知识库规范文件（如 项目规范.md），以该文件为权威参照，冲突时以项目规范为准
• 在不同平台/项目应用时，按本 Skill 的三层架构与流程落地，目录名可本地化；本仓 examples/ 提供可直接跑通的最小样本
• 本方法论当前蒸馏对象为命题知识（规则）；蒸馏卡模板的「认知结构扩展」可选区为认知结构蒸馏（心智模型/决策启发式层）预留接口，需要时再启用，不预建管线

三层架构

层	推荐目录	性质
Raw Sources	原始采集/（文章/讨论/视频）	只读，采集后不可变
The Wiki	知识库/（目录.md、采集经验.md、操作日志.md）	LLM 维护的派生内容
The Schema	项目规范.md + 程序文件/配置/	人与 LLM 共同维护

关键原则：原始文件始终留在 Raw Sources，不移动到 Wiki；校验通过后在目录.md 中建立引用即视为"入库"。

角色分离（必须遵守）

角色	实体	职责	禁忌
Planner	人工	定采集目标、定价值契约、引导分析方向	不直接操作文件
Generator	LLM	执行采集、补元数据、写摘要、维护目录与日志	禁止自评产出质量
Evaluator	校验治具（如 scripts/validate.py）	独立校验格式、编码、元数据、交叉引用	不参与生成

核心规则：模型不得给自己打分。 价值评估由 Generator 记录在操作日志，校验通过与否由 Evaluator 裁定；人工有异议时以人工判断为准。项目无治具时，按 Lint 结构层七维与判断层逐项人工核查，但结论仍不得由生成者自证。

Ingest（摄入）

复制此清单跟踪进度：

- [ ] 1. 采集前价值契约（四问，第 4 问重要主题必答）
- [ ] 2. 采集并补充元数据
- [ ] 3. 读取内容、提取关键信息
- [ ] 4. 价值判定（不达标则中止）
- [ ] 5. 更新目录.md（摘要 + 交叉引用）
- [ ] 6. 追加操作日志
- [ ] 7. 蒸馏评估并标记落地状态
- [ ] 8. Git 提交

第 1 步 · 采集前价值契约——动手前回答以下问题并记录：

1. 这篇文章要解决什么问题？与已有知识的关系是什么？（补充/对比/延伸）
2. 什么条件下算「有价值」？至少满足一个：引入新概念、提供对比视角、有直接实操参考
3. 预期归入目录.md 哪一层？（基础理论/架构范式/工程实践/工具资源/社区动态）
4. （重要主题必答）是否存在反方证据或批评者视角？重要且缺失时先补采再判定

第 2 步 · 采集与元数据——用当前平台的采集引擎获取原文（见「采集引擎抽象」），存入 Raw Sources 对应子目录，文件名遵循 {source}_{topic}_{date}.{ext}（如 github_karpathy_llm_wiki_20260630.md）。元数据必需字段：URL、采集时间、采集命令；建议字段：By、Site、Published、原始来源。采集引擎通常只能自动提取部分字段，其余必须补齐。

第 4 步 · 价值判定（含中止）——对照第 1 步契约评估。明显不满足任何价值条件（内容空洞、严重重复、与知识库定位无关）时，显式记录中止原因到操作日志后退出，不强行完成入库流程。

第 5 步 · 矛盾处理协议——新知识与既有条目或已落地 Memory 冲突时，按三型处理；禁止悄悄覆盖、强行调和或假装矛盾不存在：

• 时间性演化（早期 A、近期 B）：记录演化轨迹，标「早期/近期」，以近期观点为主；
• 领域性差异（不同领域各持一端）：分领域记录，不强求统一；
• 本质性张力（价值观内在冲突）：并列呈现，显式标注「核心张力」，并记当前默认立场（何语境下默认取哪端），供 Lint 审视。

第 6 步 · 操作日志格式：## [日期] ingest | 标题（append-only）。

第 7 步 · 蒸馏评估——该条目是否包含可直接指导智能体行为的原子规则？先过质量过滤器，再标落地状态。

质量过滤器（两问）——借鉴三重验证精神、改写为规则场景：

1. 排他性：没有这条规则，智能体的决策会有什么不同？（滤掉「任何聪明人都这么想」的常识）
2. 生成力：这条规则能否推断新类似场景下的行为断言？（滤掉一次性描述）

标 🟢 时蒸馏卡须为两问各记一条具体断言（如生成力推断出的新场景），使自答可证伪，第 8 维回测以此为靶。

过滤器决定标记上限（三色原义不变）：

过滤结果	标记上限	动作
两问全过	🟢 已落地	提取原子规则写入 Memory/规范/Skill，在目录.md 条目注明 Memory 标题；适用边界为必填字段
仅过一问	🟡 部分落地	按场景受限规则落地，注明局限、已落地与未落地的具体内容及原因
两问全不过	🔵 参考索引	操作日志中简述原因

适用边界：规则的前提条件与「何时不适用」，随规则正文一同写入。不声明边界的规则不值得信任——脱离适用前提的规则即制造负担。Planner 覆盖过滤器上限标记时，须在操作日志与蒸馏卡显式记录覆盖理由，接受 Lint 审视；禁止静默覆盖。

蒸馏标准：规则必须能改变智能体在具体场景下的行为决策，而非抽象理念或参考信息。 蒸馏卡格式见 references/rule-template.md；其结构层（适用边界/来源指针必填）由 validate.py 裁定。

跨平台蒸馏适配：在 Qoder 中蒸馏产物写入 Memory 系统（方法论→task_experience、踩坑→common_pitfalls_experience、架构决策→important_decision_experience 等分类）；在其他智能体平台，映射到该平台自身的持久记忆/行为规则机制，判定标准与三色标记保持不变。

第 8 步：git add -A && git commit -m "ingest: 标题"。

Query（查询）

1. 先读 知识库/目录.md 定位相关页面
2. 深入阅读相关文件，综合答案
3. 好答案回填为新页面——让探索本身也产生复利
4. 追加操作日志：## [日期] query | 问题
5. 产生新页面后：git add -A && git commit -m "query: 问题"

Lint（体检）

优先运行项目校验治具（本仓提供零依赖示例：python scripts/validate.py <知识库根目录>），治具裁定优先于人工判断。无治具时按结构层七维逐项核查：

1. 元数据完整性 — 必需字段（URL、采集时间、采集命令）是否齐全
2. 编码正确性 — 双重编码乱码、BOM、替换字符（U+FFFD）
3. 格式规范性 — Markdown 须以 H1 开头且元数据与正文以 --- 分隔；JSON 须有 _metadata 字段
4. 命名规范 — 是否遵循 {source}_{topic}_{date} 模式
5. 交叉引用 — 目录.md 链接是否指向实际文件；孤儿页面检测
6. 来源校验 — URL 是否属于来源白名单
7. 蒸馏卡规范性 — 蒸馏卡必含非空「适用边界」「来源指针」章节（validate.py 裁定）

判断层（validate.py 不覆盖，人工或独立智能体执行）：

8. 蒸馏回测 — 每次 Lint 抽 2 条落地超两周的 🟢 规则，用 1 个历史真实任务回测：当时若有此规则，决策会否不同、方向是否正确？失败 → 降级或补适用边界标注，记入操作日志；回测失败的规则不得静默保留。

追加操作日志：## [日期] lint | 检查范围；有修复则 git commit -m "lint: 检查范围"。

Harness 递减：治具与流程是补偿模型弱点的辅助机制，应随模型进步单调递减。每次 Lint 时审视：哪些校验规则已不再触发？哪些步骤模型已内化？删掉它。新增机制同样受递减约束：质量过滤器与蒸馏回测若连续 3 次 Lint 未产生真实信号（未滤掉常识、未触发降级或边界补注），应审视简化或删除。

成功指标（量化）

成功与否由可机验的验收线裁定，Generator 不得自报达标（角色分离原则在验收环节的延伸）：

操作	验收线（全部满足才算成功）
Ingest	① 治具对新入库文件裁定零 ERROR；② 目录.md 条目建成且交叉引用无断链；③ 蒸馏评估产出明确三色标记（价值判定中止并留痕同样算完成）
Query	答案有目录.md 条目指针支撑；若回填新页面，页面须过治具校验
Lint	结构层七维全过（治具报告 0 ERROR）+ 判断层完成 2 条回测抽样并写入蒸馏卡

期望校准：单次 Ingest 首轮返工 1–2 次（元数据补全、编码修复）属正常区间；治具裁定通过即止，禁止对摘要与元数据无限打磨——门禁既防坏产物放行，也防完美主义空转。

反 Goodhart：蒸馏产出率（🟢 占比）仅作观察指标，不得设为目标——为提高产出率而抬高三色标记属典型古德哈特反模式，由 Lint 回测审视。

采集引擎抽象（跨平台适配）

核心流程不绑定任何采集工具，采集引擎按平台可用性选择：

平台环境	采集方式
Windows + Edge 浏览器	AutoCLI：autocli read "URL" -f markdown -o "输出路径"，自动提取 By/Site/URL；注意 PowerShell 下 stderr 进度信息会误报 ExitCode=1，输出含 "Saved to ..." 即成功
具备网页读取能力的智能体平台	网页读取工具（WebFetch 等）直接抓取并转 Markdown
公开 API 来源	Hacker News、Lobsters 等无需浏览器，直接 API 请求
无网络工具	用户粘贴原文，手动落盘并如实记录 采集命令 为"手动粘贴"

无论何种引擎，入库后的元数据、校验、蒸馏要求完全一致。采集命令 字段如实记录实际使用的引擎与命令（含降级切换），保证可复现。

约定速查

• 文件名：{source}_{topic}_{date}.{ext}，source 小写
• 操作日志：append-only，格式 ## [日期] {ingest|query|lint} | 简述
• commit message：{ingest|query|lint}: {简述}；初始化：init: 知识库基线
• 踩坑教训结构化记入 采集经验.md，不混入操作日志
• 蒸馏卡：蒸馏卡_{topic}_{date}.md，格式见 references/rule-template.md，适用边界/来源指针必填