| 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 步 · 采集前价值契约——动手前回答以下问题并记录：
- 这篇文章要解决什么问题？与已有知识的关系是什么？（补充/对比/延伸）
- 什么条件下算「有价值」？至少满足一个：引入新概念、提供对比视角、有直接实操参考
- 预期归入目录.md 哪一层？（基础理论/架构范式/工程实践/工具资源/社区动态）
- （重要主题必答）是否存在反方证据或批评者视角？重要且缺失时先补采再判定
第 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 步 · 蒸馏评估——该条目是否包含可直接指导智能体行为的原子规则？先过质量过滤器，再标落地状态。
质量过滤器（两问）——借鉴三重验证精神、改写为规则场景：
- 排他性：没有这条规则，智能体的决策会有什么不同？（滤掉「任何聪明人都这么想」的常识）
- 生成力：这条规则能否推断新类似场景下的行为断言？（滤掉一次性描述）
标 🟢 时蒸馏卡须为两问各记一条具体断言（如生成力推断出的新场景），使自答可证伪，第 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（查询）
- 先读
知识库/目录.md 定位相关页面
- 深入阅读相关文件，综合答案
- 好答案回填为新页面——让探索本身也产生复利
- 追加操作日志：
## [日期] query | 问题
- 产生新页面后：
git add -A && git commit -m "query: 问题"
Lint（体检）
优先运行项目校验治具（本仓提供零依赖示例：python scripts/validate.py <知识库根目录>），治具裁定优先于人工判断。无治具时按结构层七维逐项核查：
- 元数据完整性 — 必需字段（URL、采集时间、采集命令）是否齐全
- 编码正确性 — 双重编码乱码、BOM、替换字符（U+FFFD）
- 格式规范性 — Markdown 须以 H1 开头且元数据与正文以
--- 分隔；JSON 须有 _metadata 字段
- 命名规范 — 是否遵循
{source}_{topic}_{date} 模式
- 交叉引用 — 目录.md 链接是否指向实际文件；孤儿页面检测
- 来源校验 — URL 是否属于来源白名单
- 蒸馏卡规范性 — 蒸馏卡必含非空「适用边界」「来源指针」章节（validate.py 裁定）
判断层（validate.py 不覆盖，人工或独立智能体执行）：
- 蒸馏回测 — 每次 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，适用边界/来源指针必填
