构建本地 AI Agent 工作台：从 Obsidian 到 Software 2.0 的工程实践一、引言：为什么需要本

基于 Karpathy LLM Knowledge Bases 理念的本地 Agent 系统构建指南

一、引言：为什么需要本地 Agent 工作台？

随着 Claude Code、Cursor 等 AI 编程工具的兴起，开发者们逐渐意识到：AI 的能力不仅在于生成代码，更在于持续积累和复用知识。

但这里有一个核心问题：

AI 的会话会结束，上下文会丢失
每次新开对话，都要重新解释项目背景和个人习惯
有效的协作经验无法沉淀，重复造轮子

解决方案： 构建一个本地 Agent 工作台，让 AI 参与到能持续积累资产的系统中。

二、核心理念：把知识库当代码仓库，把 LLM 当编译器

这个理念来自 Andrej Karpathy 的 LLM Knowledge Bases 方法论：

"原始资料不是最终知识，就像源码不是可以直接跑的程序。它需要经过整理、抽取、索引，才能变成真正可用的东西。"

类比理解：

传统开发	Agent 系统
源码	原始资料 (raw/)
编译器	LLM
编译产物	提炼后的知识 (wiki/)
构建工具	脚本 (scripts/)
运行时环境	Agent 配置 (agent/)

三、分层架构设计：每一层只回答一个问题

基于上述理念，我设计了一个七层架构：

workspace/
├── raw/              # 原始输入 → "我收集了什么"
├── wiki/             # 知识编译层 → "我知道了什么"
├── projects/         # 项目推进层 → "我正在推进什么"
├── writing/          # 稳定输出层 → "我准备输出什么"
├── outputs/          # 运行时产物 → "我产生了什么"
├── agent/            # Agent 配置 → "我是谁、该怎么协作"
└── scripts/          # 本地工具 → "我能做什么"

3.1 raw/ - 原始输入层

作用： 存放未经处理的原始资料

内容示例：

网页剪藏
会议记录
临时笔记
代码片段

关键原则：

不要试图在这里保持整洁
允许混乱，因为这里是"源码"
定期通过脚本"编译"到 wiki/

3.2 wiki/ - 知识编译层

作用： 存放经过 LLM 整理后的结构化知识

内容示例：

概念解释
最佳实践
常见问题 (FAQ)
技术决策记录 (ADR)

与 raw/ 的区别：

raw/ 是"我收集了什么"（原始）
wiki/ 是"我理解了什么"（提炼）

3.3 projects/ - 项目推进层

作用： 存放正在进行的项目、研究、实验

内容示例：

项目计划
实验记录
阶段性结论
待办事项

为什么从 wiki/ 分离出来？

知识积累 ≠ 项目推进
研究一个主题时，有目标、假设、实验记录，这些不适合放在 wiki/

3.4 writing/ - 稳定输出层

作用： 存放即将发布或已发布的内容

内容示例：

博客草稿
选题池
已发布文章归档

3.5 outputs/ - 运行时产物

作用： 存放脚本运行产生的临时文件

内容示例：

生成的图表
导出的数据
临时报告

3.6 agent/ - Agent 配置层

这是整个系统的核心，回答"我是谁、最近在做什么、该怎么协作"。

子目录设计：

agent/
├── AGENTS.md       # 启动导航页（不是记忆！）
├── memory/         # 长期记忆
│   ├── profile.md  # 个人画像
│   ├── preferences.md  # 偏好设置
│   └── context.md  # 当前上下文
├── sessions/       # 会话历史
├── qa/             # 高价值问答
├── prompts/        # 常用 Prompt 模板
└── playbooks/      # 标准操作流程

AGENTS.md 的定位：

很多人第一反应是：把什么都塞进 AGENTS.md。但正确的做法是：

AGENTS.md 是导航页，不是记忆库
它应该告诉 Agent：这个仓库是什么、有哪些层、新会话先读什么
真正的记忆分散在 memory/、sessions/、qa/、projects/、wiki/

3.7 scripts/ - 本地工具层

作用： 把高频动作固化成脚本，让 Agent 也能调用

核心脚本：

# recall.py - 新会话开始时读取本地记忆
def recall():
    """读取 agent/memory/ 和 agent/context.md"""
    pass

# capture_session.py - 把有价值的会话落成 session
def capture_session(session_content):
    """保存到 agent/sessions/YYYY-MM-DD-HH-MM.md"""
    pass

# archive_qa.py - 把高价值问答沉淀成 QA 卡片
def archive_qa(question, answer):
    """保存到 agent/qa/ 并更新索引"""
    pass

# search_qa.py - 先检索已有经验
def search_qa(query):
    """检索 agent/qa/ 中的相关内容"""
    pass

# compile_note.py - 把 raw 编译成 wiki
def compile_note(raw_file):
    """调用 LLM 整理 raw/ 中的笔记到 wiki/"""
    pass

# refresh_indexes.py - 刷新知识索引
def refresh_indexes():
    """更新 wiki/ 和 agent/qa/ 的索引"""
    pass

# consolidate_memory.py - 压缩短期记忆到长期记忆
def consolidate_memory():
    """整合 agent/sessions/ 到 agent/memory/"""
    pass

# health_check.py - 定期体检
def health_check():
    """检查各层健康状态"""
    pass

四、工作流程：人 + Agent + 仓库的协作闭环

4.1 新会话启动流程

Agent 读取 AGENTS.md - 了解仓库结构
执行 recall.py - 加载长期记忆和当前上下文
检索相关 QA - 查看是否有类似问题的历史记录
开始协作 - 基于已有上下文进行对话

4.2 会话中沉淀流程

产生有价值的问答 → 执行 archive_qa.py
完成项目里程碑 → 更新 projects/
整理 raw 笔记 → 执行 compile_note.py
会话结束 → 执行 capture_session.py

4.3 定期维护流程

每日 - refresh_indexes.py 刷新索引
每周 - consolidate_memory.py 压缩记忆
每月 - health_check.py 系统体检

五、实践案例：用这套系统写技术博客

场景描述

我要写一篇关于"Redis 高级用法"的博客文章。

传统方式

打开 ChatGPT/Claude
从零开始解释：我是谁、要写什么主题、目标读者是谁
生成大纲
逐段生成内容
会话结束，所有上下文丢失
下次想写续集，重新解释一遍

使用本地 Agent 工作台

第一步：在 projects/ 创建项目

# projects/redis-advanced-usage/README.md

## 目标
写一篇关于 Redis 10种高级用法的博客

## 目标读者
后端开发者，有一定 Redis 基础

## 大纲
1. 布隆过滤器
2. 分布式锁
3. 延迟队列
4. ...

## 参考资料
- [链接1]
- [链接2]

第二步：Agent 读取上下文

[Agent 自动加载]
- AGENTS.md: 了解仓库结构
- agent/memory/profile.md: 了解我的写作风格
- projects/redis-advanced-usage/: 了解项目背景

第三步：协作写作

我：帮我写第一段，介绍布隆过滤器
Agent：好的，基于你的风格（简洁、有代码示例），这里是草稿...

我：不错，但例子太简单了，加个电商场景
Agent：已更新，加入了防止缓存穿透的电商场景...

第四步：沉淀经验

会话结束，执行 capture_session.py
→ 保存到 agent/sessions/2026-04-08-redis-blog.md

有价值的问题"如何防止缓存穿透"
→ 执行 archive_qa.py 保存到 agent/qa/

第五步：下次续写

新会话自动加载：
- 项目背景（projects/redis-advanced-usage/）
- 上次写到哪了（agent/sessions/）
- 已有问答（agent/qa/）

Agent：我们继续写第5点 HyperLogLog？

六、工具推荐

6.1 笔记工具

Obsidian - 本地优先，强大的链接和插件生态
Logseq - 大纲式笔记，适合快速记录

6.2 Agent 工具

Claude Code - 最强编程 Agent
OpenClaw - 本地 Agent 框架，支持自定义 Skill

6.3 脚本语言

Python - 丰富的库，适合数据处理
Bash - 系统级操作，轻量快速

七、常见问题

Q1: 这和直接用 ChatGPT 有什么区别？

区别：

ChatGPT：会话结束，上下文清零
本地工作台：上下文持续积累，越用越懂你

Q2: 需要多少技术门槛？

门槛：

基础：会用 Obsidian 或类似工具
进阶：会写简单 Python 脚本
高级：能设计适合自己工作流的架构

Q3: 投入产出比如何？

前期： 需要 1-2 天搭建系统 后期： 每次会话节省 5-10 分钟解释时间，长期收益巨大

八、总结

构建本地 Agent 工作台的核心思想：

分层 - 每层只回答一个问题，避免混乱
导航 - AGENTS.md 是入口，不是记忆库
脚本 - 把高频动作固化，让 Agent 也能调用
沉淀 - 每次有效协作都要保存下来
复利 - 系统越用越智能，上下文越积越丰富

最终目标： 不是"我在用一个 Agent"，而是"我在维护一个更大的 Agent 系统"。

参考来源：

Karpathy LLM Knowledge Bases 方法论
掘金《Software 2.0 落地：把 Obsidian 仓库改造成本地 Agent 工作台》
OpenClaw 官方文档

标签： #AIAgent #Obsidian #知识管理 #Software2.0 #本地优先 #Agent工作台

本文基于实际工程实践整理，代码示例可直接使用。