MediaCrawler/mac-agent-os-main/90_archive/docs/AgentOS-完整说明文档_副本.v2.1-history.md

AgentOS 完整说明文档

版本：v2.1.0 | 最后更新：2026-04-28 | 作者：ghai 系统环境：macOS 26.4 / Apple M1 / 16GB RAM / 245GB SSD 运行时平台：WorkBuddy 桌面客户端 + 坚果云 + Obsidian

说明：本文件保留为扩展历史说明与细节备忘，不再作为 AgentOS v2.0 的唯一基准。 当前正式口径请优先查看 README.md、CORE-ARCHITECTURE.md、REVIEW-V2.0.md。

---

目录

1. 系统概述
2. 整体架构与目录结构
3. 核心配置文件详解
4. 初始化与部署
5. 技能体系详解
6. 知识库结构详解
7. 记忆体系统详解
8. 工具脚本目录
9. 运行时与缓存
10. 迁移与备份
11. 自动化任务配置
12. 同步策略详解
13. 本地/远程使用方式
14. 数据流全景
15. 环境依赖清单
16. 当前运行状态
17. 已知问题与待解决项
18. 附录：根目录文档索引

---

一、系统概述

1.1 是什么

AgentOS 是一套运行在个人 Mac 上的智能体外骨骼系统（AI Agent Operating System），为 AI Agent（Claw 🦀）提供四大基础能力：

能力	说明
记忆管理	L0-L3 五级分层记忆，含关键词索引、向量检索、结构化事实库、原始对话存档
知识管理	基于 Obsidian 的本地知识库，9 种属性分类 × 16 个领域，自动提纯归档
内容采集	多平台自动监控采集（RSS/小红书/抖音/B站/网页），AI 提炼后入库
多设备协作	坚果云实时同步 + Git 版本控制，双轨保障数据安全

1.2 核心设计理念

• 本地优先：所有数据存储在本地，坚果云只做同步通道
• 四级记忆截断：L0→L1→L2→L3，每层不无限 fallback，避免 token 浪费
• 技能驱动：所有能力封装为技能（Skill），按触发词路由，即插即用
• 结构化输出：去文学化，先结论后步骤
• 软链接隔离：本机大文件（向量库/素材/缓存）通过软链接指向独立目录，不进同步

1.3 技术栈

层级	技术选型
AI 运行时	WorkBuddy 桌面客户端（CodeBuddy）
本地 LLM	oMLX v0.3.6（Apple MLX 框架）
主力模型	Qwen3-8B-MLX-4bit（4.26GB，Q4_K_M 量化）
多模态	Qwen2.5-VL-3B-Instruct-8bit（3.9GB，图文理解）
向量模型	Qwen3-Embedding-0.6B（1.19GB，1024维）
向量数据库	ChromaDB 1.5.8
知识库	Obsidian（Markdown + Frontmatter）
同步	坚果云（实时文件同步） + Gitee（Git 版本控制）
Python	3.13.12（WorkBuddy managed + agent-os venv）
Node.js	22.12.0（WorkBuddy managed）

---

二、整体架构与目录结构

2.1 双目录架构

AgentOS 采用同步目录 + 本机目录的双轨架构：

~/                          用户主目录
├── agent-os/               ← 坚果云同步 + Git 版本控制（核心仓库）
│   ├── 00_bootstrap/           初始化与部署脚本
│   ├── 01_core/                核心配置（部署到 ~/.workbuddy/）
│   ├── 02_skills/              技能包（9个自定义技能 + 1个模板）
│   ├── 03_knowledge/           Obsidian 知识库
│   ├── 04_memory/              四级记忆体
│   ├── 05_tools/               工具脚本
│   ├── 06_runtime/             运行时（缓存通过软链接指向本地）
│   ├── 07_migration/           迁移打包/还原脚本
│   ├── .gitignore
│   ├── README.md / CHANGELOG.md / CORE-ARCHITECTURE.md ...
│   └── requirements.txt
│
├── agent-os-local/         ← 本机专属，不同步，不进 Git
│   ├── memory/                 记忆体数据
│   │   ├── raw/                    L3 对话原文（隐私数据）
│   │   └── vector_db/              ChromaDB + 关键词索引
│   ├── runtime/                运行时数据
│   │   └── cache/                  临时缓存
│   └── materials/              采集的原始素材
│       ├── web/                    网页保存
│       ├── video/                  视频下载
│       ├── audio/                  录音文件
│       ├── screenshots/            截图
│       └── refined_for_inbox/      已提炼待投递的 MD
│
└── .workbuddy/              ← WorkBuddy 运行时配置
    ├── SOUL.md                  L0 最高约束（从 01_core/ 部署）
    ├── IDENTITY.md              身份档案
    ├── USER.md                  用户画像
    ├── mcp.json                 MCP 服务器配置
    ├── skills/                  技能目录（从 02_skills/ 导入）
    ├── binaries/                Python/Node 运行时
    │   ├── python/
    │   │   ├── versions/3.13.12/       Python 二进制
    │   │   └── envs/agent-os/          agent-os 虚拟环境
    │   └── node/
    │       ├── versions/22.12.0/       Node 二进制
    │       └── workspace/node_modules/  全局 npm 包
    ├── automations/             定时自动化任务
    └── memory/                  WorkBuddy 工作记忆

2.2 软链接映射

agent-os/ 内通过软链接指向 agent-os-local/ 中的实际目录，脚本无需改路径：

~/workbuddy-agent-os/agent-sync/04_memory/long_term/raw     → ~/workbuddy-agent-os/agent-sync/agent-local/memory/raw
~/workbuddy-agent-os/agent-sync/04_memory/vector_db         → ~/workbuddy-agent-os/agent-sync/agent-local/memory/vector_db
~/workbuddy-agent-os/agent-sync/06_runtime/cache            → ~/workbuddy-agent-os/agent-sync/agent-local/runtime/cache

为什么用软链接：大文件（向量库 ~1MB+、L3 原文、视频素材）不应进入坚果云同步和 Git 仓库，通过软链接在逻辑上保持路径一致，物理上存储在本机目录。

2.3 完整目录树（agent-os/ 内部）

~/workbuddy-agent-os/agent-sync/
├── .gitignore                          (846 B)  Git 忽略规则
├── README.md                           (7.71 KB) 项目主文档
├── CHANGELOG.md                        (3.75 KB) 变更日志
├── CORE-ARCHITECTURE.md                (6.14 KB) 系统架构"宪法"
├── QUICKSTART.md                       (2.87 KB) 5分钟快速上手
├── REQUIREMENTS.md                     (4.85 KB) 环境要求说明
├── SKILLS-CATALOG.md                   (11.38 KB) 技能清单与部署手册
├── requirements.txt                    (2.01 KB) Python 依赖清单
│
├── 00_bootstrap/                       初始化与部署
│   ├── init.sh                         (12.45 KB) 一键初始化脚本
│   ├── apply-config.sh                 (3.31 KB) 核心配置部署
│   ├── export_skills.sh                (1.74 KB) 技能导出为压缩包
│   └── import_skills.sh                (2.60 KB) 技能导入到 WorkBuddy
│
├── 01_core/                            核心配置（部署目标：~/.workbuddy/）
│   ├── CHANGELOG.md                    (331 B) 配置变更日志
│   ├── SOUL.md                         (7.74 KB) L0 最高约束
│   ├── IDENTITY.md                     (1.70 KB) AI 身份档案
│   ├── USER.md                         (1.11 KB) 用户画像
│   └── mcp.json                        (261 B) MCP 服务器配置
│
├── 02_skills/                          技能包（9个技能 + 1个模板）
│   ├── _template/                          技能开发模板
│   │   ├── SKILL.md                        (438 B)
│   │   ├── skill.py                        (518 B) 模板脚本
│   │   └── version.json                    (136 B)
│   ├── memory_manager/                     记忆管理（v1.2.0）
│   │   ├── SKILL.md                        (5.07 KB)
│   │   ├── daily_digest.py                 (20.30 KB) 每日对话提炼
│   │   ├── semantic_search.py              (23.75 KB) BM25+向量混合检索
│   │   ├── bootstrap_from_memory.py        (14.49 KB) 冷启动全量导入
│   │   ├── memory_cleanup.py               (3.91 KB) 冲突消解
│   │   ├── agent_memory_init.py            (3.30 KB) 首次初始化
│   │   ├── export_memories.py              (3.64 KB) 记忆导出
│   │   ├── import_memories.py              (7.33 KB) 记忆导入
│   │   └── version.json                    (214 B)
│   ├── inbox_refine/                       收件箱提纯归档（v1.0.0）
│   │   ├── SKILL.md                        (3.89 KB)
│   │   ├── inbox_refine.py                 (14.70 KB) 主脚本
│   │   ├── llm_classifier.py               (15.19 KB) LLM 分类器
│   │   ├── llm_classifier_broken.py        (15.02 KB) 旧版备份
│   │   └── version.json                    (694 B)
│   ├── collect_to_inbox/                   分类目录汇聚收件箱（v1.0.0）
│   │   ├── SKILL.md                        (4.12 KB)
│   │   ├── collect_to_inbox.py             (10.24 KB) 主脚本
│   │   └── version.json                    (98 B)
│   ├── kb_manager/                         知识库管理（v1.1.0）
│   │   ├── SKILL.md                        (3.25 KB)
│   │   ├── kb_ingest.py                    (9.15 KB) 知识入库
│   │   └── version.json                    (192 B)
│   ├── auto_collector/                     24h自动监控收集（v1.0.0）
│   │   ├── SKILL.md                        (3.61 KB)
│   │   └── version.json                    (116 B)
│   ├── content_processor/                  统一内容处理路由（v1.0.0）
│   │   ├── SKILL.md                        (4.26 KB)
│   │   └── version.json                    (119 B)
│   ├── web_crawler/                        网页抓取+反爬（v1.1.0）
│   │   ├── SKILL.md                        (1.76 KB)
│   │   └── version.json                    (151 B)
│   └── sync_manager/                       同步管理（v1.1.0）
│       ├── SKILL.md                        (1.09 KB)
│       └── version.json                    (172 B)
│
├── 03_knowledge/                       Obsidian 知识库
│   ├── .obsidian/                        Obsidian 配置
│   ├── README.md                         (4.19 KB) 知识库首页
│   ├── CHANGELOG.md                      (499 B) 知识库变更日志
│   ├── 00_inbox/                         📥 收件箱（待提纯内容）
│   ├── 01_daily/                         📅 日记
│   ├── 10_concepts/                      💡 概念层（16个子领域目录）
│   │   ├── cs/ ai/ finance/ law/ ...
│   │   └── 2026-04-28_测试_LLM_分类器.md
│   ├── 20_methods/                       🔧 方法层
│   ├── 30_facts/                         📋 事实层
│   ├── 40_references/                    📎 参考层（papers/ + docs/）
│   ├── 50_resources/                     🛠 资源层
│   ├── 60_opinions/                      💭 观点层
│   ├── 90_archive/deprecated/            🗄 归档层
│   └── 99_system/                        ⚙️ 系统层
│       ├── templates/                        4种知识卡片模板
│       ├── taxonomies/                       分类体系
│       ├── prompts/                           分类 Prompt
│       └── timelines/                         版本时间线
│
├── 04_memory/                          四级记忆体
│   ├── .obsidian/                        Obsidian 配置（可视化浏览）
│   ├── .workbuddy/memory/                WorkBuddy 运行记忆
│   ├── CHANGELOG.md                      (313 B) 记忆体变更日志
│   ├── daily_summaries/                  每日对话摘要
│   │   ├── 2026-04-25.md                 (33.58 KB)
│   │   ├── 2026-04-26.md                 (411.56 KB)
│   │   ├── 2026-04-27.md                 (4.12 KB)
│   │   └── 2026-04-28.md                 (1.94 KB)
│   ├── long_term/                        L2 结构化事实 + L3 原文
│   │   ├── facts.db                      (40 KB) SQLite 事实库（52条）
│   │   └── raw/ → ~/workbuddy-agent-os/agent-sync/agent-local/memory/raw/  [软链接]
│   │       ├── 2026-04-25.md ~ 2026-04-28.md
│   │       └── bootstrap_*.md
│   ├── vector_db/ → ~/workbuddy-agent-os/agent-sync/agent-local/memory/vector_db/  [软链接]
│   │   ├── keyword_index.json            (24.78 KB) BM25 关键词索引
│   │   └── chroma/                       ChromaDB 向量库
│   │       └── chroma.sqlite3            (536 KB)
│   ├── logs/                             操作日志
│   └── memory_backup/                    记忆备份
│
├── 05_tools/                           工具脚本（底层公共工具）
│   ├── README.md                         (1.11 KB)
│   ├── 00_setup/                         环境安装工具
│   ├── 01_system/                        系统诊断脚本
│   │   ├── check_automation_env.py       (4.38 KB) 自动化环境检查
│   │   ├── check_facts.py                (1.45 KB) facts.db 查询
│   │   ├── test_omlx_embedding.py        (5.32 KB) oMLX Embedding 测试
│   │   └── reports/                      系统检查报告存档
│   │       └── system-check-report-20260427.md
│   ├── 02_browser/                       浏览器工具
│   ├── 03_ocr/                           OCR 工具
│   ├── 04_media/                         媒体处理工具
│   ├── 05_crawl/                         爬虫工具
│   │   └── content-inspiration/          🎬 口播素材系统 v1.0
│   │       ├── SKILL.md                  (4.82 KB)
│   │       ├── README.md                 (13.49 KB)
│   │       ├── config.yaml               (1.64 KB)
│   │       ├── schema.sql                (3.54 KB)
│   │       ├── collect.py                (9.76 KB) 多平台采集
│   │       ├── analyze.py                (8.25 KB) AI 分析
│   │       ├── downloader.py             (5.93 KB) yt-dlp 下载
│   │       ├── app.py                    (10.45 KB) Gradio Web 界面
│   │       ├── utils.py                  (4.86 KB) 工具函数
│   │       ├── requirements.txt          (255 B)
│   │       ├── data/raw/                 原始采集数据
│   │       └── logs/                     运行日志
│   └── 06_mobile/                        移动端工具
│
├── 06_runtime/                         运行时
│   ├── tasks/                            任务执行记录
│   └── cache/ → ~/workbuddy-agent-os/agent-sync/agent-local/runtime/cache/  [软链接]
│
└── 07_migration/                       迁移与打包
    ├── backup.sh                         (1.43 KB) 手动备份
    ├── pack.sh                           (1.17 KB) 全量打包
    └── unpack.sh                         (1.11 KB) 解包还原

---

三、核心配置文件详解

3.1 SOUL.md — L0 最高约束

路径：~/workbuddy-agent-os/agent-sync/01_core/SOUL.md → 部署到 ~/.workbuddy/SOUL.md 大小：7.74 KB | 优先级：最高（不可被任何技能或用户指令绕过）

这是 AgentOS 的"宪法"文件，定义了 AI Agent 的硬约束和软约束：

层级	内容	说明
L0 硬约束	禁止操作列表	删除安全备份、关闭约束本身、暴露 L3 原文等
L0 硬约束	需确认操作	修改知识文件、执行系统命令、修改配置、发起网络请求
L0 硬约束	必须操作	每次对话读取身份文件、L0 安全检查、MCP 协议接入
L1 行为准则	编码原则	思考优先、简单优先、精准修改、目标驱动
L1 行为准则	职责边界	职权检查、明确拒绝
L1 行为准则	规则检查	冲突检查、规则优先
L1 行为准则	复用优先	技能复用三步走、方案复用
L1 行为准则	输出要求	去文学化、可执行性、自行检查、精简提问
L2 学习规则	知识审查	入库必审、冲突处理、过期清理（技术 180 天）
L2 学习规则	自学习	错误日志、知识修补、进化阈值（3 次触发改进）
L2 学习规则	性能优化	按需加载、记忆截断、回复控制

记忆读取策略（核心流程）：

用户提问 → L0 安全过滤 → L1 关键词索引匹配
  ├─ 无匹配 → 直接回答（不翻记忆）
  └─ 有匹配 → L2 置信度检查
       ├─ ≥ 0.7 → 返回摘要作为上下文
       └─ < 0.7 → 终止，直接回答（不 fallback 到 L3）
L3 仅在用户明确要求"调出原文"时按行号加载

3.2 IDENTITY.md — AI 身份档案

路径：~/workbuddy-agent-os/agent-sync/01_core/IDENTITY.md → 部署到 ~/.workbuddy/IDENTITY.md 大小：1.70 KB

Name: Claw
Creature: AI 外骨骼（智能体操作系统内核）
Vibe: 精准、高效、无废话、有主见
Emoji: 🦀

包含：

• 角色定位（个人智能体外骨骼，非聊天机器人）
• 能力边界（擅长/不擅长/绝对不做）
• 交互风格（先结论后步骤，能验证不问）
• 当前设备信息（由 init.sh 自动填充：主机名、系统、Python 路径、Node 路径、oMLX 模型列表、初始化时间）

3.3 USER.md — 用户画像

路径：~/workbuddy-agent-os/agent-sync/01_core/USER.md → 部署到 ~/.workbuddy/USER.md 大小：1.11 KB

Name: ghai
City: 苏州
Language: 中文（默认），英文（技术术语保留）

记录用户的工作背景、个人偏好（结构化输出、决策果断、注重 token 效率）、当前关注领域和近期动态。此文件随使用持续更新。

3.4 mcp.json — MCP 服务器配置

路径：~/workbuddy-agent-os/agent-sync/01_core/mcp.json → 部署到 ~/.workbuddy/mcp.json 大小：261 B

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/workbuddy-agent-os/agent-sync"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

两个 MCP 服务器：

• filesystem：让 AI Agent 通过标准协议读写 ~/workbuddy-agent-os/agent-sync/ 目录下的文件
• memory：提供持久化记忆存储能力

注意：apply-config.sh 部署 mcp.json 时，如果目标已存在 mcp.json，会提示手动合并而非覆盖，避免破坏用户已有配置。

---

四、初始化与部署

4.1 一键初始化（init.sh）

路径：~/workbuddy-agent-os/agent-sync/00_bootstrap/init.sh（12.45 KB，366 行）

使用方式：

cd ~/workbuddy-agent-os/agent-sync/00_bootstrap && bash init.sh

自动完成的操作（按顺序）：

步骤	操作	说明
1	检测操作系统	macOS/Linux，提取版本信息和主机名
2	检测 Python	优先使用 agent-os venv → managed Python → 系统 python3
3	检测 Node.js	WorkBuddy managed Node 22.12.0
4	创建本机专属目录	~/workbuddy-agent-os/agent-sync/agent-local/ 下的 8 个子目录
5	重建软链接	raw → agent-os-local/memory/raw 等 3 个链接
6	创建 agent-os 内部目录	42 个目录（含知识库 16 个领域子目录）
7	添加 .gitkeep	空目录添加占位文件（确保坚果云能同步空目录）
8	安装 Python 依赖	自动创建 venv 并 pip install -r requirements.txt
9	填充设备信息	sed 替换 IDENTITY.md 中的占位符
10	初始化记忆体	创建 L1 keyword_index.json 和 L2 facts.db
11	检测坚果云	自动搜索常见坚果云路径
12	检测 oMLX	curl 检查 localhost:8000 是否响应

输出：换机还原检查清单（5 项）和目录边界说明。

4.2 配置部署（apply-config.sh）

路径：~/workbuddy-agent-os/agent-sync/00_bootstrap/apply-config.sh（3.31 KB，112 行）

使用方式：

cd ~/workbuddy-agent-os/agent-sync/00_bootstrap && bash apply-config.sh

操作：

1. 备份旧配置：将 ~/.workbuddy/ 下已有的 SOUL.md、IDENTITY.md、USER.md 备份到带时间戳的目录
2. 部署配置：复制 01_core/ 下的 4 个文件到 ~/.workbuddy/
3. mcp.json 特殊处理：已存在时提示手动合并，不覆盖
4. BOOTSTRAP.md 清理：检测到 BOOTSTRAP.md 时提示删除（需 AUTO_DELETE_BOOTSTRAP=yes 环境变量确认）

4.3 技能导入导出

import_skills.sh — 技能导入

路径：~/workbuddy-agent-os/agent-sync/00_bootstrap/import_skills.sh（2.60 KB）

# 导入全部技能
bash import_skills.sh

# 导入指定技能
bash import_skills.sh memory_manager

操作：

• 扫描 02_skills/ 下所有子目录
• 跳过 _template/ 和缺少 SKILL.md 的目录
• 复制到 ~/.workbuddy/skills/（用户级技能目录）
• 已存在的技能会先删除再覆盖

export_skills.sh — 技能导出

路径：~/workbuddy-agent-os/agent-sync/00_bootstrap/export_skills.sh（1.74 KB）

bash export_skills.sh memory_manager
# 输出：07_migration/exports/memory_manager_v1.2.0.zip

4.4 冷启动记忆体

~/.workbuddy/binaries/python/envs/agent-os/bin/python3 \
  ~/workbuddy-agent-os/agent-sync/02_skills/memory_manager/bootstrap_from_memory.py \
  --root ~/workbuddy-agent-os/agent-sync

将已有工作记忆（MEMORY.md + 工作日志 + 系统画像）全量导入 L1/L2/L3 记忆体。仅在首次运行，之后每日自动提炼。

---

五、技能体系详解

5.1 技能分类

AgentOS 将技能分为两类：

system 技能（后台自动运行，也可手动触发）：

技能	版本	用途	自动化时间
memory_manager	v1.2.0	记忆提炼/去重/语义检索	每日 2:00
collect_to_inbox	v1.0.0	知识库目录扫描→收件箱	每日 2:30
inbox_refine	v1.0.0	收件箱提纯→知识库归档	每日 3:00
auto_collector	v1.0.0	24h 多平台自动信息收集	持续运行
kb_manager	v1.1.0	知识入库/分类/检索	按需
sync_manager	v1.1.0	备份/导出/同步状态	按需

user 技能（对话触发）：

技能	版本	用途	触发词示例
content_processor	v1.0.0	统一内容处理路由	转笔记/剪藏/语音摘要/采集
web_crawler	v1.1.0	网页抓取+反爬	抓取/crawl/fetch

5.2 快速指令对照表

指令	路由	动作
转笔记	content_processor → bilinote	视频→结构化笔记
摘字幕	content_processor → bilinote	仅语音转文字
视频摘要	content_processor → bilinote	提炼核心观点
剪藏	content_processor → web-clipper	网页→Markdown
摘抄	content_processor → web-clipper	保存全文
文章摘要	content_processor → web-clipper	3句话概括
提炼	content_processor → web-clipper	方法论/步骤/结论
翻译	content_processor → web-clipper	翻译成中文
语音摘要	content_processor → voice-summary	语音→核心要点
转文字	content_processor → voice-summary	逐字稿
采集	content_processor → social-collector	小红书/抖音→笔记
开始收集	auto_collector	启动 24h 监控
停止收集	auto_collector	暂停监控
收集报告	auto_collector	今日采集摘要
记忆更新	memory_manager	手动触发记忆提炼
查记忆	memory_manager	语义检索记忆
入库	kb_manager	知识入库（→ 00_inbox/）
归集	collect_to_inbox	分类目录→收件箱
提纯	inbox_refine	收件箱提纯归档
抓取	web_crawler	网页抓取+反爬
备份知识库	sync_manager	全量备份

5.3 memory_manager（记忆管理）详解

版本：v1.2.0 | 脚本数：7 个 Python 脚本

核心脚本说明

脚本	大小	用途	使用方式
daily_digest.py	20.30 KB	每日对话提炼主脚本	--root ~/workbuddy-agent-os/agent-sync --date YYYY-MM-DD
semantic_search.py	23.75 KB	BM25 + 向量语义混合检索	search --query "内容" --top-k 5
bootstrap_from_memory.py	14.49 KB	冷启动全量导入历史记忆	--root ~/workbuddy-agent-os/agent-sync
memory_cleanup.py	3.91 KB	冲突消解与过期记忆清理	--root ~/workbuddy-agent-os/agent-sync
agent_memory_init.py	3.30 KB	首次初始化记忆体	--root ~/workbuddy-agent-os/agent-sync
export_memories.py	3.64 KB	记忆导出为 JSON+MD 压缩包	--output ~/backup/
import_memories.py	7.33 KB	从压缩包恢复记忆（智能去重）	--input ~/backup/memories.zip

每日对话提炼流程

1. 读取 Claw 工作日志（~/WorkBuddy/Claw/.workbuddy/memory/YYYY-MM-DD.md）
2. 提取关键事实（who/what/when/where/decision）
3. 去重：对比 L2 已有事实，相似度 > 0.9 则跳过
4. 冲突检测：新事实与旧事实矛盾？→ 标记 OVERRIDE 或提示用户确认
5. 生成摘要（100-200 字/条）
6. 更新 L1 关键词索引（keyword_index.json）
7. 更新 L1_vec 向量索引（ChromaDB + oMLX embedding）
8. 关键对话原文 → 压缩后写入 L3（long_term/raw/）

语义检索能力

• BM25 关键词检索 + ChromaDB 向量检索 + RRF（Reciprocal Rank Fusion）加权融合
• 向量权重 0.6 / BM25 权重 0.4
• 向量引擎：ChromaDB 持久化 + oMLX Qwen3-Embedding-0.6B（1024 维）
• CLI：

  # 检索
  python3 semantic_search.py search --root ~/workbuddy-agent-os/agent-sync --query "查询内容" --top-k 5
  # 回填（向量化所有 L2 事实）
  python3 semantic_search.py backfill --root ~/workbuddy-agent-os/agent-sync
  # 重建索引
  python3 semantic_search.py rebuild --root ~/workbuddy-agent-os/agent-sync
  # 测试 embedding
  python3 semantic_search.py embed --root ~/workbuddy-agent-os/agent-sync --text "测试"
  

5.4 inbox_refine（收件箱提纯）详解

版本：v1.0.0 | 脚本数：3 个（含 LLM 分类器）

分类决策逻辑

内容特征	nature	目标目录
已验证的客观事实	fact	30_facts/
可操作的步骤/教程	method	20_methods/
原子概念/基础原理	concept	10_concepts/
公认基础原理	axiom	10_concepts/
法律法规/制度	regulation	30_facts/
论文/文档/外部资料	reference	40_references/
测试数据/基准结果	data	30_facts/
主观看法/推测	opinion	60_opinions/
他人原话/语录	quote	60_opinions/

置信度评分

source_type	confidence
official_doc	0.9
literature	0.8
experiment	0.7
personal_exp	0.5
social_media	0.3
unknown	0.4

LLM 分类器

llm_classifier.py（15.19 KB）使用 oMLX + Qwen2.5-VL-3B-Instruct-8bit 进行 AI 辅助分类（因 Qwen3-8B Chat API 存在 500 错误，降级使用 VLM 模型），包含降级机制：LLM 失败时自动回退到启发式规则，分类信心度阈值降至 0.4。

5.5 collect_to_inbox（分类目录汇聚收件箱）详解

版本：v1.0.0 | 脚本：collect_to_inbox.py（10.24 KB）

扫描目录配置

源目录	来源技能	提取策略
50_resources/视频笔记/	bilinote	提取核心摘要 + 关键结论
50_resources/字幕存档/	bilinote	提取前 500 字摘要
50_resources/阅读笔记/	web-clipper	提取标题 + 核心观点
50_resources/全文存档/	web-clipper	提取前 500 字摘要
50_resources/翻译存档/	web-clipper	提取标题 + 3 句话概括
50_resources/灵感素材/	social-collector	提取核心内容 + 互动数据
50_resources/语音转写/	voice-summary	提取关键要点
20_methods/	web-clipper 提炼	提取方法名 + 步骤
01_daily/闪念笔记/	voice-summary	提取要点 + 标签
40_references/	content_processor	提取标题 + 核心观点

5.6 content_processor（统一内容处理路由）详解

版本：v1.0.0

本技能不替代子技能，而是作为统一调度层：

用户输入（触发词 + URL/文件）
  ↓
content_processor 解析触发词
  ↓ 路由
  ├─ 视频 → 加载 bilinote 技能
  ├─ 文章 → 加载 web-clipper 技能
  ├─ 语音 → 加载 voice-summary 技能
  └─ 社交 → 加载 social-collector 技能
  ↓ 执行
子技能完成处理 → 输出 Markdown 笔记到对应分类目录

5.7 web_crawler（网页抓取+反爬）详解

版本：v1.1.0

三引擎自适应选择：

反爬级别	引擎	说明
低（静态页面）	Scrapling 静态模式	最快，无需浏览器
中（动态渲染）	Scrapling 动态模式	Camoufox 隐身浏览器
高（Cloudflare 等）	Playwright + Stealth	完整浏览器模拟+反检测

失败自动重试最多 3 次，引擎自动降级。

---

六、知识库结构详解

6.1 目录结构与命名规则

知识库路径：~/workbuddy-agent-os/agent-sync/03_knowledge/，同时作为 Obsidian Vault。

编号	目录	中文名	知识属性	说明
00	00_inbox/	📥 收件箱	—	待提纯内容暂存
01	01_daily/	📅 日记	—	每日日记、闪念笔记
10	10_concepts/	💡 概念层	concept/axiom	16 个子领域目录
20	20_methods/	🔧 方法层	method	可操作的步骤/教程
30	30_facts/	📋 事实层	fact/regulation/data	已验证的客观事实
40	40_references/	📎 参考层	reference	论文/文档/外部资料
50	50_resources/	🛠 资源层	resource	视频笔记/阅读笔记/灵感素材等
60	60_opinions/	💭 观点层	opinion/quote	主观看法/他人原话
90	90_archive/	🗄 归档层	—	已弃用的知识
99	99_system/	⚙️ 系统层	—	模板/分类/配置

6.2 领域分类体系

10_concepts/ 下按 16 个一级领域分子目录：

编号	英文目录	中文	典型子领域
01	cs	计算机科学	数据库、前端、后端、运维、安全
02	ai	人工智能	NLP、CV、强化学习、RAG、Agent
03	finance	金融	量化交易、价值投资、宏观经济
04	law	法律	民法、商法、知识产权
05	medicine	医学	中医、西医、营养学
06	physics	物理	量子力学、相对论、热力学
07	math	数学	线性代数、概率统计、微积分
08	psychology	心理学	认知心理学、社会心理学
09	philosophy	哲学	认识论、伦理学、美学
10	history	历史	中国史、世界史、科技史
11	engineering	工程	机械、电子、土木
12	design	设计	UI/UX、平面设计、建筑设计
13	business	商业	创业、管理、营销、战略
14	personal-management	个人管理	GTD、番茄工作法、精力管理
15	personal-insight	个人洞见	决策模型、价值观、反思
16	other	其他	待新增领域

当"其他"类别超过总知识 5% 时，memory_manager 会提示新增领域。

6.3 知识卡片模板

99_system/templates/ 下有 4 种标准化模板：

模板文件	适用类型	核心字段
concept-card.md	概念/公理	一句话定义、核心原理、与相关概念区别、主流选择
method-card.md	方法/教程	适用场景、步骤、注意事项、示例
fact-card.md	事实/数据	事实陈述、数据来源、可信度
personal-insight-card.md	个人洞见	背景、思考过程、结论、行动项

所有知识卡片使用标准 Frontmatter：

---
id: KB-YYYYMMDD-NNN
title: "知识标题"
type: concept|method|fact|reference|resource|opinion
status: draft|review|published|archived
nature: fact|opinion|method|regulation|reference|data|quote|axiom
domain: [领域1, 领域2]
tags: [标签列表]
confidence: 0.0-1.0
source: "原始来源 URL"
source_type: official_doc|literature|experiment|personal_exp|social_media|unknown
date_created: YYYY-MM-DD
date_modified: YYYY-MM-DD
version: 1
previous_version: ""
superseded_by: ""
---

6.4 分类体系配置文件

文件	路径	说明
domains.md	99_system/taxonomies/domains.md	16 个一级领域定义
nature-types.md	99_system/taxonomies/nature-types.md	9 种 nature 类型 + 决策树
folder-aliases.json	99_system/taxonomies/folder-aliases.json	英文目录 ↔ 中文映射
classify-knowledge.md	99_system/prompts/classify-knowledge.md	知识分类 Prompt

---

七、记忆体系统详解

7.1 五级分层架构

┌─────────────────────────────────────────────────┐
│ L0: SOUL.md（硬约束）                             │ 不存储，直接注入 prompt
├─────────────────────────────────────────────────┤
│ L1: 关键词索引（keyword_index.json）               │ 52 条条目
│     + 向量索引（ChromaDB + embedding）             │ 52 条向量
├─────────────────────────────────────────────────┤
│ L2: 结构化事实库（facts.db, SQLite）               │ 52 条事实
├─────────────────────────────────────────────────┤
│ L3: 对话原文（long_term/raw/*.md）                 │ 6 个文件
└─────────────────────────────────────────────────┘

7.2 L2 facts.db 表结构

CREATE TABLE facts (
    id TEXT PRIMARY KEY,
    subject TEXT NOT NULL,        -- 主语
    predicate TEXT NOT NULL,      -- 谓语
    object TEXT NOT NULL,         -- 宾语
    confidence REAL DEFAULT 0.7,  -- 置信度
    nature TEXT DEFAULT 'fact',   -- 属性
    domain TEXT,                  -- 领域
    source TEXT,                  -- 来源
    date_created TEXT,            -- 创建时间
    date_modified TEXT,           -- 修改时间
    previous_version TEXT,        -- 前一版本
    superseded_by TEXT,           -- 被谁取代
    version INTEGER DEFAULT 1     -- 版本号
);

索引：subject / domain / confidence

7.3 记忆体文件说明

路径	类型	说明
04_memory/vector_db/keyword_index.json (24.78 KB)	L1	BM25 关键词索引
04_memory/vector_db/chroma/chroma.sqlite3 (536 KB)	L1_vec	ChromaDB 向量索引
04_memory/long_term/facts.db (40 KB)	L2	SQLite 结构化事实
04_memory/long_term/raw/YYYY-MM-DD.md	L3	当日对话原文
04_memory/daily_summaries/YYYY-MM-DD.md	摘要	每日提炼结果
04_memory/logs/	日志	错误日志、冲突日志、入库日志
04_memory/memory_backup/	备份	记忆备份存档

---

八、工具脚本目录

8.1 05_tools/ 与 02_skills/ 的区别

• 02_skills/：可被 WorkBuddy 对话触发的技能，有 SKILL.md 身份证
• 05_tools/：底层公共工具，被技能调用或手动执行，不暴露给对话

8.2 系统诊断脚本

脚本	路径	大小	用途
check_automation_env.py	05_tools/01_system/	4.38 KB	检查自动化运行环境配置
check_facts.py	05_tools/01_system/	1.45 KB	查询 facts.db 中的事实
test_omlx_embedding.py	05_tools/01_system/	5.32 KB	测试 oMLX Embedding API 连通性

调用方式：

~/.workbuddy/binaries/python/envs/agent-os/bin/python3 ~/workbuddy-agent-os/agent-sync/05_tools/01_system/check_automation_env.py

8.3 口播素材系统（content-inspiration）

路径：~/workbuddy-agent-os/agent-sync/05_tools/05_crawl/content-inspiration/ 版本：v1.0.0 | 独立项目，包含完整 Web 界面

解决的核心问题：口播创作者的素材灵感管理。

组件	脚本	大小	用途
采集	collect.py	9.76 KB	多平台元数据采集
分析	analyze.py	8.25 KB	oMLX + Qwen2.5-VL AI 分析
下载	downloader.py	5.93 KB	yt-dlp 视频下载
界面	app.py	10.45 KB	Gradio Web 界面
工具	utils.py	4.86 KB	公共工具函数
配置	config.yaml	1.64 KB	运行时配置
数据	schema.sql	3.54 KB	SQLite 数据库表结构

数据流：

collect.py → JSONL 存档（data/raw/）
    ↓
analyze.py → oMLX Qwen2.5-VL 分析 → SQLite 索引
    ↓
app.py → Gradio Web 界面统一检索
    ↓
downloader.py → yt-dlp → ~/workbuddy-agent-os/agent-sync/agent-local/materials/video/

启动方式：

~/.workbuddy/binaries/python/envs/agent-os/bin/python3 ~/workbuddy-agent-os/agent-sync/05_tools/05_crawl/content-inspiration/app.py

---

九、运行时与缓存

9.1 06_runtime/ 结构

目录	用途	存储位置
06_runtime/tasks/	任务执行记录	agent-os（同步）
06_runtime/cache/	临时缓存	agent-os-local（本地）

9.2 agent-os-local/ 完整结构

~/workbuddy-agent-os/agent-sync/agent-local/
├── memory/
│   ├── raw/                       L3 对话原文（隐私数据）
│   │   ├── 2026-04-25.md          (6.82 KB)
│   │   ├── 2026-04-26.md          (6.29 KB)
│   │   ├── 2026-04-27.md          (4.78 KB)
│   │   ├── 2026-04-28.md          (4.54 KB)
│   │   └── bootstrap_*.md         启动时导入的历史记忆
│   └── vector_db/                 向量数据库（ChromaDB + 关键词索引）
│       ├── keyword_index.json     (24.78 KB)
│       └── chroma/                ChromaDB 持久化数据
├── runtime/
│   └── cache/                     临时缓存
└── materials/                     采集的原始素材
    ├── web/                       网页保存
    ├── video/                     视频下载（yt-dlp 输出）
    ├── audio/                     录音文件
    ├── screenshots/               截图
    └── refined_for_inbox/         已提炼待投递的 MD

---

十、迁移与备份

10.1 备份脚本（backup.sh）

路径：~/workbuddy-agent-os/agent-sync/07_migration/backup.sh（1.43 KB）

bash backup.sh [backup_dir]
# 默认备份到 04_memory/memory_backup/

操作：

• 备份核心配置（01_core/）
• 备份记忆体（long_term/、vector_db/、daily_summaries/）
• 备份技能包（02_skills/）
• 自动清理 30 天以上的旧备份

10.2 全量打包（pack.sh）

路径：~/workbuddy-agent-os/agent-sync/07_migration/pack.sh（1.17 KB）

bash pack.sh
# 输出：07_migration/exports/agent-os_YYYYMMDD_HHMMSS.tar.gz

排除项：缓存、虚拟环境、__pycache__、.DS_Store、node_modules

10.3 解包还原（unpack.sh）

路径：~/workbuddy-agent-os/agent-sync/07_migration/unpack.sh（1.11 KB）

bash unpack.sh <archive_path> [target_dir]
# 解压后按提示运行 init.sh → apply-config.sh → import_skills.sh

10.4 换机还原流程（3步）

# 1. 等坚果云同步完成，agent-os 目录出现在本机
# 2. 一键初始化（自动完成所有配置）
cd ~/workbuddy-agent-os/agent-sync/00_bootstrap && bash init.sh

# 3. 部署核心配置
bash apply-config.sh

# 4. 导入技能
bash import_skills.sh

# 5. 手动安装 oMLX（Apple MLX 框架，硬件依赖）

init.sh 自动完成：创建本地目录、重建软链接、创建 venv 安装依赖、填充设备信息、检测坚果云和 oMLX。

---

十一、自动化任务配置

11.1 WorkBuddy 自动化任务

任务	时间	脚本	说明
每日记忆提炼	每日 02:00	memory_manager/daily_digest.py	对话→L2 事实
收件箱汇聚	每日 02:30	collect_to_inbox/collect_to_inbox.py	知识库扫描→inbox
收件箱提纯	每日 03:00	inbox_refine/inbox_refine.py	inbox→分类归档
RSS 检查	每小时	auto_collector	检查所有 RSS 源
社交平台检查	每 2 小时	auto_collector + TikOmni	小红书/抖音博主
网页变化检查	每小时	auto_collector + Crawl4AI	指定网页监控
采集日报	每日 23:00	auto_collector	今日采集汇总

11.2 自动化任务存储

自动化任务配置存储在：

• ~/.workbuddy/automations/<automation-id>/automation.toml — 运行时配置
• ~/workbuddy-agent-os/agent-sync/.codebuddy/automations/<automation-id>/memory.md — 执行记录

---

十二、同步策略详解

12.1 双轨同步

轨道	工具	同步范围	优势
实时同步	坚果云客户端	整个 ~/workbuddy-agent-os/agent-sync/ 目录	即时、增量、无感
版本控制	Git（Gitee 私有仓库）	代码/配置/知识文件	历史追溯、分支管理、冲突解决

12.2 不同步的内容

以下内容通过软链接指向 ~/workbuddy-agent-os/agent-sync/agent-local/，天然不会进入坚果云同步和 Git：

• L3 对话原文（04_memory/long_term/raw/）
• ChromaDB 向量库（04_memory/vector_db/chroma/）
• 临时缓存（06_runtime/cache/）
• 原始素材（agent-os-local/materials/）

12.3 Git 排除规则（.gitignore）

# 系统文件
.DS_Store / __pycache__ / *.pyc

# 虚拟环境
.venv/ / venv/

# 运行时缓存（已软链接）
06_runtime/cache/

# 大媒体文件
*.mp4 / *.mp3 / *.mov / *.zip / *.tar.gz

# WorkBuddy 运行时
.codebuddy/ / .workbuddy/

# Obsidian 插件（各设备自行安装）
.obsidian/plugins/

# 备份和报告
backup_*/ / system-check-report-*.md

12.4 Git 远程仓库

• 平台：Gitee 私有仓库
• 地址：[email protected]:babycalf/mac-agent-os.git
• 分支策略：main 分支，单线开发
• SSH 密钥：~/.ssh/id_ed25519a（个人公钥）

12.5 索引卡片命名规范（多机协作）

多台电脑采集的素材通过索引卡片共享，避免大文件同步冲突：

{hostname}_{YYYYMMDD}_{slug}.md
示例：Redmi-12C_20260428_douyin-普通人逆袭.md
      MBP-M3_20260428_bilibili-科普冷知识.md

卡片模板：

---
title: 素材标题
source_url: https://...
local_path: ~/workbuddy-agent-os/agent-sync/agent-local/materials/video/xxx.mp4
type: video|audio|web|image
platform: douyin|xiaohongshu|bilibili|web
collected_by: Redmi-12C    ← 标明采集机器
collected_at: 2026-04-28
tags: [标签1, 标签2]
---

---

十三、本地/远程使用方式

13.1 本地使用（当前配置）

本机环境：

• 设备：MacBook Air M1（Redmi-12C） / macOS 26.4
• Python：3.13.12（~/.workbuddy/binaries/python/envs/agent-os/bin/python3）
• Node.js：22.12.0（~/.workbuddy/binaries/node/versions/22.12.0/bin/node）
• 本地 LLM：oMLX v0.3.6（localhost:8000，API Key: omlx）

使用流程：

1. 打开 WorkBuddy 桌面客户端
2. 在 Claw 工作区对话，AI 自动加载 SOUL.md/IDENTITY.md/USER.md
3. 使用触发词（转笔记/剪藏/采集/提纯 等）调用技能
4. 自动化任务在后台按时执行

关键路径速查：

# Python（所有脚本用这个）
~/.workbuddy/binaries/python/envs/agent-os/bin/python3

# Node.js
~/.workbuddy/binaries/node/versions/22.12.0/bin/node

# 知识库（Obsidian Vault）
~/workbuddy-agent-os/agent-sync/03_knowledge/

# 本地 LLM API
http://localhost:8000/v1/chat/completions  (Authorization: Bearer omlx)
http://localhost:8000/v1/embeddings        (Authorization: Bearer omlx)

# 坚果云同步目录
~/Nutstore Files/

13.2 远程/换机使用

前提条件：

1. 新机器已安装 WorkBuddy 桌面客户端
2. 新机器已安装坚果云客户端，且同步完成

还原步骤：

# 1. 确认 agent-os 目录已通过坚果云同步到本机
ls ~/workbuddy-agent-os/agent-sync/README.md

# 2. 一键初始化（自动创建本地目录、重建软链接、安装依赖）
cd ~/workbuddy-agent-os/agent-sync/00_bootstrap && bash init.sh

# 3. 部署核心配置到 WorkBuddy
bash apply-config.sh

# 4. 导入技能
bash import_skills.sh

# 5. 冷启动记忆体（首次）
~/.workbuddy/binaries/python/envs/agent-os/bin/python3 \
  ~/workbuddy-agent-os/agent-sync/02_skills/memory_manager/bootstrap_from_memory.py --root ~/workbuddy-agent-os/agent-sync

# 6. 安装 oMLX（从 https://omlx.ai 下载）

# 7. 配置 Obsidian Vault → ~/workbuddy-agent-os/agent-sync/03_knowledge/

# 8. 重启 WorkBuddy

换机注意事项：

• ~/workbuddy-agent-os/agent-sync/agent-local/ 不会通过坚果云同步，每台机器独立
• 向量库和 L3 原文需要在新机器上重新生成（bootstrap_from_memory.py 或 semantic_search.py backfill）
• 设备信息会由 init.sh 自动更新到 IDENTITY.md
• Python/Node 路径可能因 WorkBuddy 版本不同而变化，init.sh 会自动检测

13.3 跨平台兼容性

平台	说明
macOS	直接运行，无需额外配置
Linux	直接运行，部分系统命令可能需要 sudo
Windows	需通过 WSL2 运行，路径使用 /mnt/c/Users/xxx/

所有路径使用 $HOME 或相对路径，不硬编码绝对路径，确保跨平台兼容。

---

十四、数据流全景

14.1 内容采集→知识归档 完整流程

用户输入 / 自动监控
  ↓
┌──────────────────────────────────────────┐
│  content_processor（统一路由层）          │
│  ├─ 视频 → bilinote                     │
│  ├─ 文章 → web-clipper                  │
│  ├─ 语音 → voice-summary                │
│  └─ 社交 → social-collector             │
└────────────┬─────────────────────────────┘
             ↓
     各分类目录（视频笔记/阅读笔记/灵感素材/...）
             ↓
     collect_to_inbox（每日 2:30 自动 / 手动"归集"）
             ↓
     00_inbox/（收件箱，标准化 MD）
             ↓
     inbox_refine（每日 3:00 自动 / 手动"提纯"）
             ↓
     分类写入 03_knowledge/ 对应目录 + 更新首页

14.2 记忆提炼流程

每日对话记录（~/WorkBuddy/Claw/.workbuddy/memory/YYYY-MM-DD.md）
  ↓
memory_manager/daily_digest.py（每日 2:00 自动）
  ↓
┌─ 提取关键事实 → 去重 → 冲突检测
├─ 更新 L2 facts.db（SQLite）
├─ 更新 L1 keyword_index.json（BM25）
├─ 更新 L1_vec ChromaDB（向量）
└─ 关键原文 → L3 raw/（压缩存储）

14.3 语义检索流程

用户查询 → memory_manager/semantic_search.py
  ↓
BM25 关键词检索（keyword_index.json）
  + 向量语义检索（ChromaDB + oMLX Embedding）
  ↓
RRF 加权融合（BM25:0.4 + 向量:0.6）
  ↓
返回 Top-K 结果

14.4 多机协作数据流

本机采集 → ~/workbuddy-agent-os/agent-sync/agent-local/materials/（本机专属，不同步）
  ↓ AI 提炼
~/workbuddy-agent-os/agent-sync/03_knowledge/00_inbox/（标准化 MD）
  ↓ 坚果云实时同步
其他电脑收到的 inbox 内容
  ↓
inbox_refine → 归档到知识库 → Git commit → Gitee

---

十五、环境依赖清单

15.1 必需环境

软件	最低版本	安装方式	状态
WorkBuddy 桌面客户端	最新版	codebuddy.cn	✅
Python	3.10+	WorkBuddy 自动管理	✅ 3.13.12
Node.js	18+	WorkBuddy 自动管理	✅ 22.12.0

Python 和 Node.js 由 WorkBuddy 自带，不需要手动安装。

15.2 Python 依赖库

包	版本要求	用途	使用者	安装状态
trafilatura	≥2.0.0	网页正文提取	kb_ingest, web-clipper	✅
sqlite-utils	≥3.35	SQLite 增强	facts.db 操作	✅
feedparser	≥6.0.0	RSS 解析	auto_collector	✅
schedule	≥1.2.0	定时任务	auto_collector	✅
chromadb	≥1.0.0	向量数据库	semantic_search	✅ 1.5.8
scrapling	≥0.1.0	三引擎反爬	web_crawler	✅
crawl4ai	≥0.1.0	智能结构化抓取	web_crawler	✅
playwright	≥1.50.0	浏览器自动化	web_crawler	✅
playwright-stealth	latest	反检测	web_crawler	✅
openai-whisper	latest	语音转文字	voice-summary	✅
gradio	latest	Web 界面	content-inspiration	✅ 6.13
yt-dlp	latest	视频下载	content-inspiration	✅ 2026.3

安装命令（全部在 agent-os venv 中）：

~/.workbuddy/binaries/python/envs/agent-os/bin/pip install -r ~/workbuddy-agent-os/agent-sync/requirements.txt

15.3 Node.js 依赖

包	用途	安装状态
@tikomni/skills	小红书/抖音数据采集	✅

安装命令：

cd ~/.workbuddy/binaries/node/workspace && \
  ~/.workbuddy/binaries/node/versions/22.12.0/bin/npm install @tikomni/skills

15.4 系统软件

软件	用途	安装状态
oMLX v0.3.6	本地 LLM 运行	✅ 已安装
Obsidian v1.12.7	知识库管理	✅ 已安装
坚果云	文件同步	✅ 已安装
Playwright Chromium	浏览器引擎	✅ headless shell 已安装
Ollama	本地 LLM（已停用）	⚠️ 已停用，改用 oMLX

---

十六、当前运行状态

16.1 模块状态总览

模块	状态	说明
核心配置（SOUL/IDENTITY/USER）	✅	已部署到 ~/.workbuddy/
Python 环境	✅	venv 3.13.12 + 全部依赖
Node.js 环境	✅	22.12.0 + TikOmni
记忆系统	✅	L2 有 52 条事实，L1 52 条索引，L1_vec 52 条向量（三方一致）
知识库	✅	目录就绪 + 首页 + 模板 + 分类体系
收件箱提纯	✅	inbox_refine 每日 3:00 自动
收件箱汇聚	✅	collect_to_inbox 每日 2:30 自动
记忆提炼	✅	daily_digest 每日 2:00 自动
技能包	✅	8 个自定义技能 + 多个插件技能
坚果云同步	✅	已配置
Git 版本控制	✅	Gitee 私有仓库
oMLX	✅	v0.3.6 运行中
Obsidian	✅	Vault 已绑定 03_knowledge/
口播素材系统	✅	v1.0 已部署（Gradio + yt-dlp + AI 分析）

16.2 本地 LLM 状态

模型	类型	大小	用途	Chat API	Embedding API
Qwen3-8B-MLX-4bit	LLM	4.26GB	中文理解/生成	❌ 500 错误	—
Qwen2.5-VL-3B-Instruct-8bit	VLM	3.9GB	多模态理解	✅ 正常	—
Qwen3-Embedding-0.6B	Embedding	1.19GB	向量嵌入（1024维）	—	✅ 正常

关键发现（2026-04-27）：Qwen3-8B-MLX-4bit Chat API 返回 500 错误，已将 inbox_refine 降级使用 VLM 模型，添加降级机制。

16.3 磁盘空间

总量 228GB，已用 12GB，可用 161GB（截至 2026-04-25）

---

十七、已知问题与待解决项

17.1 已解决问题

问题	日期	解决方案
Qwen3-8B Chat API 500 错误	2026-04-27	inbox_refine 降级使用 VLM 模型 + 启发式回退
Ollama→oMLX 迁移	2026-04-27	更新所有 .md/.sh/.py 文件中的引用
旧路径 /Users/5kecheng/ → /Users/chengzige/	2026-04-25	全面清理，零残留
根目录散落脚本	2026-04-28	移入 05_tools/01_system/
目录隔离	2026-04-28	引入 agent-os-local + 软链接机制

17.2 待解决项

项目	优先级	说明
Homebrew 安装	中	可选，安装后可装 yt-dlp/ffmpeg/screenpipe
BiliNote Docker	低	视频转笔记依赖，需 Docker Desktop
Qwen3-8B Chat API 修复	中	oMLX 侧问题，等待更新

---

十八、附录：根目录文档索引

文件	大小	说明
README.md	7.71 KB	项目主文档（架构、技能、状态）
CORE-ARCHITECTURE.md	6.14 KB	系统架构"宪法"（目录职责、软链接、同步策略）
QUICKSTART.md	2.87 KB	5 分钟快速上手指南
REQUIREMENTS.md	4.85 KB	环境要求详细说明
SKILLS-CATALOG.md	11.38 KB	技能清单与部署手册
CHANGELOG.md	3.75 KB	版本变更日志
requirements.txt	2.01 KB	Python 依赖清单（含安装命令）
.gitignore	846 B	Git 忽略规则

---

文档版本：v2.1.0 | 生成时间：2026-04-28 16:18 生成者：Claw 🦀（AgentOS 智能体外骨骼） 数据来源：agent-os 实际文件结构和内容分析