Knowledge Base Template

English | 简体中文

Markdown-first 个人知识库模板。内容以本地 Markdown 文件为源，Next.js 应用提供阅读、检索、知识图谱、生命周期视图、内容校验、内容流转、转录 intake 与可选 GitHub OAuth 访问控制。

适用范围

• 本地优先、Git 可追踪的个人知识库。
• 研究资料、音视频转录、问题研读、整理稿和稳定知识模型的统一管理。
• Markdown 内容源与 Web 阅读界面的组合。
• 需要明确内容生命周期、来源链路和归档状态的长期知识项目。

能力概览

• 内容源管理：正式内容位于 content/，通过 frontmatter 表达领域、类型、生命周期和关系。
• 生命周期视图：Inbox、Sources、Synthesis、Study、Collected、Output 对应不同内容成熟度。
• 阅读体验：Markdown 渲染、目录、阅读进度、GFM footnote 批注、来源链接、相关笔记、反向链接和上下文侧栏。
• 检索与图谱：全文搜索、domain 过滤、tag、内部引用关系和知识图谱探索。
• Domain 注册表：content/_meta/domains.json 统一管理知识领域，避免用目录表达领域。
• 内容 CLI：创建 Inbox、创建正式笔记、从 Inbox 提升、归档笔记、运行内容校验。
• 转录 intake：支持小宇宙 episode、Bilibili 视频和 b23.tv 短链，产出本地 transcript package。
• 访问控制：默认本地公开访问；设置 KB_AUTH_REQUIRED=true 后启用 GitHub OAuth allowlist。
• 质量门禁：内容校验、ESLint、TypeScript、Vitest、Next.js build 和 Playwright e2e。

技术栈

• Next.js 16、React 19、TypeScript 5
• Tailwind CSS 4
• unified、remark-gfm、rehype-sanitize、rehype-highlight
• gray-matter、zod、flexsearch
• NextAuth v5 beta
• Vitest、Playwright、ESLint

快速开始

git clone git@github.com:jiechen257/knowledge-base-template.git
cd knowledge-base-template
pnpm install
cp .env.example .env.local
pnpm dev

本地开发服务默认访问 http://localhost:3000。模板预览模式默认关闭登录要求。

初始化配置

1. 配置领域注册表：编辑 content/_meta/domains.json，保留当前知识库需要的 domain。
2. 配置环境变量：复制 .env.example 为 .env.local，按需填写 OAuth 和转录相关变量。
3. 建立首批内容：使用 pnpm content:new 创建 Inbox 或正式笔记。
4. 建立来源链路：通过 frontmatter 的 sources、related、questions、source_topic 连接笔记。
5. 提交前验证：至少运行 pnpm validate:content；代码、UI 或路由变更按验证矩阵补充检查。

内容模型

项目使用带编号的物理目录和不带编号的逻辑路由。编号只服务本地文件排序，页面路由和笔记引用保持稳定的无编号路径。

物理目录	含义	路由 / 逻辑路径
content/00-inbox/	临时收集区	/inbox
content/01-sources/	原文、资料、转录稿、证据材料	sources/...
content/02-synthesis/	整理稿	/synthesis、synthesis/...
content/03-study/	研读稿	/study、study/...
content/03-study/questions/	问题研读	/questions、questions/...
content/04-collected/domains/	稳定概念、模型、框架	/collected、domains/...
content/90-output/	输出物预留区	未来导出

Domain 由 frontmatter 的 domain 字段表达，并由 content/_meta/domains.json 注册。新增领域时更新该 registry。生命周期目录下保持扁平结构，不创建 programming、macro、investing 这类领域子目录。

文章类型与生命周期

正式笔记通过 type 和 workflow_status 共同表达位置。

type	workflow_status	目录	用途
source	source	content/01-sources/	保存原始材料、摘录、访谈、播客转录、视频转录、数据和证据。
synthesis	synthesis	content/02-synthesis/	将多个来源或研读结果整理为结构化草稿。
question	study	content/03-study/questions/	围绕问题、判断或决策展开研读。
study-note	study	content/03-study/	维护主题、概念或研究方向的结构化研读稿。
domain-note	collected	content/04-collected/domains/	保存稳定概念、模型、定义、边界和结论。

推荐内容成熟路径：

Inbox -> Sources -> Study -> Synthesis -> Collected -> Output

该路径用于表达内容成熟度。单篇内容可以按实际需要停留在任一阶段。

• Inbox：快速捕获临时材料。
• Sources：保留外部来源和原始上下文。
• Study：使用 question 或 study-note 拆解问题、建立研究结构。
• Synthesis：将多个来源或研读结果整理为可读草稿。
• Collected：沉淀长期稳定的概念、模型和框架。
• Output：承接博客、报告、网页或其他成品导出。

synthesis 和 study 阶段必须保留来源链路。可用链路包括 frontmatter 的 sources、frontmatter 的 source_topic 和正文中的 sources/... 内部链接。

归档状态通过 record_status: archived 表达。默认 UI、搜索、Dashboard、Todo 和导航计数只展示 record_status: active 的内容。content/01-sources/ 默认长期保留，删除或移动来源文件属于显式归档或清理动作。

Frontmatter 契约

---
title: Example source
domain: programming
type: source
workflow_status: source
record_status: active
tags: [ai, workflow]
lenses: []
sources:
  - title: Original source
    url: https://example.com
related: []
questions: []
source_topic:
created: 2026-05-02
updated: 2026-05-02
---

常用字段：

• domain：领域 ID，必须存在于 content/_meta/domains.json。
• type：笔记类型，决定模板和逻辑路径。
• workflow_status：生命周期阶段。
• record_status：active 或 archived，控制默认展示范围。
• tags：用于搜索、图谱和列表筛选。
• sources：外部来源或内部 source note。
• related：相关笔记。
• questions：study note 下挂的问题。
• source_topic：草稿或发布候选对应的 study note。
• publish：发布意图；在 study 或 collected 阶段文章中使用 publish.target: blog。

示例数据

模板内置一组最小关联样例，用于验证路由、引用、图谱和生命周期视图。

类型	路由
Source	/sources/macro/2026-q1-global-capital-markets-review
Question	/questions/macro/rate-cut-stock-market
Study note	/study/macro/macro-cycle
Synthesis draft	/synthesis/macro/knowledge-workflow-summary
Publish candidate	/study/macro/liquidity-cycle-essay
Collected model	/domains/macro/liquidity
Inbox capture	/inbox/quick-capture

示例内容保留框架测试所需的路由形态、媒体 ID、内部链接和引用关系。正式使用时可按自己的 domain 和材料替换。

内容 CLI

pnpm content:new
pnpm content:new -- --domain programming
pnpm content:transition
pnpm content:transition -- --domain programming

CLI 能力：

• 创建 Inbox 笔记。
• 创建 source、synthesis、question、study-note、domain-note。
• 从 Inbox 提升为正式笔记。
• 将正式笔记或 Inbox 标记为 record_status: archived。
• 写入 created 和 updated。
• 写入后按需运行 pnpm validate:content。

模板文件位于 templates/。

转录 Intake

转录工作流将音视频来源转换为本地 transcript package，产物默认写入 tmp/transcripts/。该能力面向 source ingestion。

支持链接：

• 小宇宙 episode：https://www.xiaoyuzhoufm.com/episode/...
• Bilibili 视频：https://www.bilibili.com/video/BV.../
• Bilibili 短链：https://b23.tv/...

常用命令：

# 默认使用本地 faster-whisper，产物写入 tmp/transcripts/
pnpm transcript:intake "https://www.xiaoyuzhoufm.com/episode/..." --engine local

# Bilibili 视频，使用浏览器 cookie 获取需要登录上下文的视频信息
pnpm transcript:intake "https://www.bilibili.com/video/BV.../" --engine local --cookies-from-browser chrome

# 使用 OpenAI 转录
OPENAI_API_KEY=... pnpm transcript:intake "https://www.bilibili.com/video/BV.../" --engine openai

# 只抓取元数据
pnpm transcript:intake "https://www.bilibili.com/video/BV.../" --metadata-only

# 保留下载媒体文件，并生成 organized.md
pnpm transcript:intake "https://www.xiaoyuzhoufm.com/episode/..." --keep-media --organize

# 整理已有 transcript package
pnpm transcript:organize tmp/transcripts/<package-dir>

处理逻辑：

• 自动识别平台。
• 小宇宙：抓取公开 episode 页面，提取标题、作者、发布时间、时长和音频 URL，下载音频并转录。
• Bilibili：使用 yt-dlp 获取元数据；平台字幕可用时优先解析字幕，字幕不可用时下载音频并转录。
• 输出 metadata.json、transcript.md、transcript.segments.json、source.txt、run.log。
• 使用 --organize 时调用 Codex 生成 organized.md。

依赖矩阵：

场景	依赖
Bilibili metadata only	yt-dlp
本地转录	ffmpeg、ffprobe、python3、faster-whisper；Bilibili 额外需要 yt-dlp
OpenAI 转录	ffmpeg、ffprobe、OPENAI_API_KEY；Bilibili 额外需要 yt-dlp
结构化整理	codex CLI，或设置 TRANSCRIPT_AGENT_COMMAND

macOS 常用安装：

brew install yt-dlp ffmpeg python
python3 -m venv .venv-transcript
. .venv-transcript/bin/activate
pip install faster-whisper

可选环境变量：

TRANSCRIPT_PYTHON=/absolute/path/to/.venv-transcript/bin/python
TRANSCRIPT_WHISPER_MODEL=small
TRANSCRIPT_AGENT_COMMAND=codex
TRANSCRIPT_AGENT_MODEL=gpt-5.4
OPENAI_API_KEY=...

进入知识库的标准路径：

1. 运行 pnpm transcript:intake <url> --organize。
2. 检查 tmp/transcripts/<package-dir>/metadata.json 和 organized.md。
3. 使用 pnpm content:new 创建 source 类型笔记。
4. 将整理后的内容写入 content/01-sources/ 对应 source note。
5. 在 sources frontmatter 中保留原始 URL。

GitHub 鉴权

模板默认公开访问。设置 KB_AUTH_REQUIRED=true 后启用 GitHub OAuth allowlist。

KB_AUTH_REQUIRED=true
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
AUTH_SECRET=
ALLOWED_GITHUB_IDS=

ALLOWED_GITHUB_IDS 使用 GitHub 数字用户 ID，多个 ID 用英文逗号分隔。

验证

场景	命令
内容变更	pnpm validate:content
代码质量	pnpm lint
类型检查	pnpm typecheck
单元测试	pnpm test
生产构建	pnpm build
布局、鉴权、路由或页面渲染变更	pnpm e2e

完整验证：

pnpm validate:content
pnpm lint
pnpm typecheck
pnpm test
pnpm build

部署

模板按标准 Next.js 项目部署到 Vercel。

pnpm build
vercel deploy . --target=preview

部署说明见 Vercel deployment。

提交流程

pnpm validate:content
pnpm lint
pnpm typecheck
pnpm test
pnpm build
git status
git add .
git commit -m "docs: update knowledge base content"

Commit message 使用英文，格式为 <type>(optional-scope): <summary>，例如 docs(readme): refine project documentation。