Skip to content

deployment-guide.md

Latest commit

 

History

History
344 lines (232 loc) · 11 KB

deployment-guide.md

File metadata and controls

344 lines (232 loc) · 11 KB
Raw
title AI 知识库部署指南
date 2026-04-13
tags
部署
指南
知识库

AI 知识库部署指南

面向非技术用户。按顺序操作，大约 20 分钟完成。

这套方案是什么

一个 本地 AI 知识库，由三个组件组成：

组件 是什么 你需要做什么
Obsidian 笔记本软件 下载安装
OpenCode AI 助手（运行在终端里） 运行安装脚本
知识库规则 告诉 AI 怎么帮你管笔记 安装脚本自动配置

装好之后你能做什么：

  • 对 AI 说「帮我整理这个文章」，AI 自动存到知识库
  • 说「我之前写过关于 XX 的笔记吗」，AI 帮你搜
  • 把 PDF、网页、截图扔给 AI，自动消化成结构化笔记

前置准备

在开始之前，确保你有：

准备项 说明 如何检查
一台 Mac 电脑 macOS 12 或更高版本 点左上角 → 「关于本机」
能上网 需要下载软件和连接 AI 打开任意网页试试
10 分钟时间 一次性操作 —

先做只读检查

如果你还不确定要不要开始安装，或者只是想先确认仓库和本机环境，建议先运行：

git clone https://github.com/zxfccmm4/Obsidian-OpenCode-Knowledge.git ~/Desktop/Obsidian-OpenCode-Knowledge
cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/verify.sh

这一步不会安装依赖，也不会改你的配置文件。

安装步骤

第 1 步：安装 Obsidian

  1. 打开浏览器，访问 obsidian.md
  2. 点击 「下载」（选择 macOS 版本）
  3. 下载完成后，把 Obsidian 拖入「应用程序」文件夹
  4. 打开 Obsidian，看到欢迎界面即可（先不要创建仓库）

如果你已经安装了 Obsidian，跳过此步。

第 2 步：获取 AI 的 API Key

知识库需要一个 AI 大脑。脚本支持以下 AI 服务（任选其一）：

服务 注册地址 特点
智谱 GLM ⭐ open.bigmodel.cn 国内服务，中文好，推荐国内用户
Anthropic console.anthropic.com Claude 系列模型
OpenAI platform.openai.com GPT 系列模型
Google Gemini aistudio.google.com Gemini 系列模型
OpenRouter openrouter.ai 多模型网关，一个 Key 用多个模型
DeepSeek platform.deepseek.com 国内服务，性价比高

以智谱 GLM 为例：

  1. 打开浏览器，访问 open.bigmodel.cn
  2. 点击 「注册」，用手机号注册
  3. 登录后，点击左侧 「API Keys」
  4. 点击 「创建 API Key」
  5. 复制生成的 Key（格式类似 xxxxx.xxxxx），粘贴保存到备忘录

⚠️ 这个 Key 只会出现一次，请务必保存好。

第 3 步：运行安装脚本

  1. 打开 终端（在「启动台」→「其他」里找到「终端」，或按 ⌘ 空格 搜索「Terminal」）

  2. 获取仓库文件：

    • 会用 Git：运行 git clone https://github.com/zxfccmm4/Obsidian-OpenCode-Knowledge.git ~/Desktop/Obsidian-OpenCode-Knowledge
    • 不会用 Git：在 GitHub 页面点击 Code → Download ZIP，解压后把文件夹放到桌面

  3. 在终端里输入以下命令，然后按回车：

cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash setup.sh

如果你只是想先预演、不真正安装，也可以运行：

cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash setup.sh --dry-run --non-interactive --provider skip

  1. 按照脚本提示操作：

    • 选择知识库位置：直接回车 = 放在桌面
    • 目录已存在（重装时会遇到）：选 1，保留你的笔记，只更新规则和技能
    • 安装 Node.js：如果提示没装，选 1 自动安装
    • 安装 OpenCode：自动进行
    • 选择 AI 服务：输入数字选择你的 AI 服务提供商（1-6），然后粘贴 API Key

  2. 看到 🎉 部署完成！ 就表示成功了

第 4 步：在 Obsidian 中打开知识库

  1. 打开 Obsidian
  2. 点击 「打开文件夹作为仓库」
  3. 选择脚本创建的文件夹（默认是桌面上的「我的知识库」）
  4. 点击「确定」

第 5 步：安装 OpenCode 插件

这是让 AI 在 Obsidian 里工作的桥梁。

通过 BRAT 安装

  1. 在 Obsidian 设置 → 第三方插件 → 浏览 → 搜索 「BRAT」 → 安装并启用
  2. 按 ⌘ P 打开命令面板，输入 「BRAT: Add a plugin」
  3. 输入仓库地址：mtymek/opencode-obsidian
  4. 点击安装并启用

第 6 步：开始使用

  1. 在 Obsidian 左侧边栏找到 OpenCode 图标（一个终端图标）
  2. 点击打开 OpenCode 面板
  3. 等 AI 连接上（第一次可能需要 30 秒）
  4. 试试和 AI 说第一句话：
帮我在 Obsidian 里创建一篇笔记，标题是《我的第一篇 AI 笔记》

插件安装清单与排障工具

如果你想进一步确认 opencode-obsidian 插件的推荐配置，或者面板显示 Error / 连接失败，优先看这份补充说明：

仓库里还附带了一个快速诊断脚本：

cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/opencode-obsidian-doctor.sh --vault "$HOME/Desktop/我的知识库"

以及一个只读检查脚本：

cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/verify.sh --vault "$HOME/Desktop/我的知识库"

它会帮你检查：

  • node 和 opencode 是否安装成功
  • 14096 端口是否被旧进程占用
  • http://127.0.0.1:14096/global/health 是否正常
  • 插件 data.json 是否存在
  • 最近的 opencode 日志里是否有明显报错

日常使用

录入素材（Ingest）

把这个加到 wiki：

[粘贴文章内容 / 贴网页链接 / 描述你想记录的内容]

AI 会自动：

  • 保存原始素材到 raw/ 目录
  • 消化成结构化笔记存入 wiki/
  • 更新索引和日志

查询知识（Query）

我的 wiki 里关于 XX 有什么？

根据我的笔记，总结一下 XX

体检（Lint）

每周一次：

lint wiki

AI 会检查索引一致性、链接有效性、孤岛页面等问题。

常见问题

Q1：OpenCode 面板显示「连接失败」

  1. 确认你的 Mac 联网了
  2. 确认 API Key 配置正确（检查 ~/.config/opencode/opencode.json 里的 apiKey）
  3. 在终端里手动测试：opencode，看能否正常启动

Q2：AI 回复很慢

  • 可能是网络问题，稍等一下
  • 智谱 GLM 的 glm-4.5-air 模型更快（但质量稍低），可以在配置文件里切换

Q3：想换一个 AI 服务

编辑配置文件：

open ~/.config/opencode/opencode.json

按照 OpenCode 官方文档 修改 provider 部分。

Q4：数据安全吗？

  • 笔记文件保存在你自己的电脑上，本项目本身不额外托管你的笔记数据
  • 使用 AI 时，当前对话内容会发送给你配置的模型服务商（如 OpenAI、Anthropic、GLM 等）
  • raw/ 目录里的原始素材永远不会被 AI 修改
  • Obsidian 的笔记就是普通的 Markdown 文件，随时可以复制备份

Q5：脚本运行出错

先运行：

cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/verify.sh --vault "$HOME/Desktop/我的知识库"

再把终端里的错误信息截图，发给帮你部署的人。

Q6：OpenCode 面板显示 Error 或 Process exited unexpectedly (exit code 1)

按这个顺序排查：

  1. 运行：
cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/opencode-obsidian-doctor.sh --vault "$HOME/Desktop/我的知识库"
  1. 如果看到端口被占用，再运行：
cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/opencode-obsidian-doctor.sh --vault "$HOME/Desktop/我的知识库" --kill-port
  1. 如果想手动验证服务能不能启动，再运行：
cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/opencode-obsidian-doctor.sh --vault "$HOME/Desktop/我的知识库" --start-test
  1. 仍然不行时，继续参考：

文件说明

安装完成后，你的知识库结构如下：

我的知识库/
├── AGENTS.md               # AI 规则（不要手动改）
├── AI_CONFIG.md            # ⚙️ AI 配置（可自定义，修改后自动生效）
├── raw/                   # 原始素材（你扔进来的东西）
├── wiki/                  # AI 整理好的笔记
│   ├── index.md           # 全局索引（AI 自动维护）
│   ├── log.md             # 操作日志（AI 自动记录）
│   └── 使用指南.md         # 使用说明
├── assets/                # 配图
└── .opencode/
    └── skill/             # AI 技能（已预装 9 个核心技能）
        ├── obsidian-cli/  # Obsidian 操作能力
        ├── obsidian-markdown/  # Markdown 生成能力
        ├── defuddle/      # 网页内容提取能力
        ├── opencli-usage/ # OpenCLI 命令参考（100+ 适配器）
        ├── smart-search/  # 智能搜索路由
        ├── opencli-browser/  # 浏览器自动化
        ├── opencli-autofix/  # 适配器自动修复
        ├── opencli-explorer/ # 适配器开发指南
        └── opencli-oneshot/  # 单点快速 CLI 生成

进阶：可选增强功能

基础版已经能用了。以下功能按需添加：

功能 怎么加 说明
PDF 导出 在 OpenCode 里说「安装 minimax-pdf 技能」 AI 帮你把笔记导出为专业 PDF
Word 导出 在 OpenCode 里说「安装 minimax-docx 技能」 AI 帮你生成 Word 文档
Excel 读取 在 OpenCode 里说「安装 minimax-xlsx 技能」 AI 帮你读取 Excel 数据
PPT 生成 在 OpenCode 里说「安装 pptx-generator 技能」 AI 帮你把笔记变成演示文稿
图片分析 在 OpenCode 里说「安装 vision-analysis 技能」 AI 帮你分析图片和截图

致谢

本方案的知识库架构灵感来自 helloianneo/obsidian-ai-second-brain（Ian 出品的 Obsidian + Claude AI 个人知识库指南，基于 Karpathy LLM Wiki 方法论）。在此基础上，我们将 AI 引擎从 Claudian（Claude Code）替换为 OpenCode，并对部署流程做了简化和本地化适配。

本文档最后更新：2026-04-14