Back to Details

secondbrain-init

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Secondbrain Project Scaffolding

Secondbrain项目搭建

Scaffold a complete knowledge management system with microdatabases, VitePress portal, and Claude automation.
使用微数据库、VitePress门户和Claude自动化搭建完整的知识管理系统。

Overview

概述

Initialize a new secondbrain project with:
  • Microdatabase architecture (YAML + JSON Schema validation)
  • VitePress documentation portal (custom theme, Vue components)
  • Configurable entity types (ADRs, Discussions, Notes, Tasks, Custom)
  • Claude automation (hooks, maximum freedom settings)
初始化新的secondbrain项目，包含：
  • 微数据库架构（YAML + JSON Schema验证）
  • VitePress文档门户（自定义主题、Vue组件）
  • 可配置实体类型（ADRs、Discussions、Notes、Tasks、自定义）
  • Claude自动化（钩子、最大自由度设置）

Workflow

工作流程

Step 1: Gather Project Information

步骤1：收集项目信息

Ask the user for:
  1. Project name (kebab-case, e.g., 
    my-knowledge-base
    )
  2. Target directory (default: 
    ./<project-name>
    )
  3. Use case (optional context for customization):
    • Personal knowledge base
    • Project documentation
    • Team collaboration
向用户询问以下信息：
  1. 项目名称（短横线命名，例如 
    my-knowledge-base
    ）
  2. 目标目录（默认：
    ./<project-name>
    ）
  3. 使用场景（可选，用于自定义的上下文）：
    • 个人知识库
    • 项目文档
    • 团队协作

Step 2: Select Entity Types

步骤2：选择实体类型

Present entity selection with checkboxes:
undefined
展示带复选框的实体选择界面：
undefined

Entity Selection

实体选择

Which entities would you like to enable?
[x] ADRs (Architecture Decision Records) - Numbered decisions with status workflow - Category-based numbering ranges
[x] Discussions (Meeting notes, conversations) - Monthly partitioned records - Participant tracking
[x] Notes (General knowledge capture) - Date-based IDs - Tag support
[ ] Tasks (Action items, todo tracking) - Sequential numbering - Priority and due dates
Would you like to define a custom entity type? (y/n)
undefined
你想要启用哪些实体？
[x] ADRs（架构决策记录） - 带状态流程的编号决策 - 基于分类的编号范围
[x] Discussions（会议记录、对话内容） - 按月份分区的记录 - 参与者追踪
[x] Notes（通用知识捕获） - 基于日期的ID - 标签支持
[ ] Tasks（行动项、待办事项追踪） - 连续编号 - 优先级与截止日期
是否想要定义自定义实体类型？(y/n)
undefined

Step 3: Configure Semantic Search

步骤3：配置语义搜索

Present search configuration options:
undefined
展示搜索配置选项：
undefined

Search Configuration

搜索配置

Which semantic search would you like to enable?
[ ] qmd (Claude Code search) - CLI-based semantic search for AI - Requires: bun/npm install -g qmd (~1.5GB models) - Best for: Local development, Claude Code integration
[ ] Orama (VitePress browser search) - Client-side semantic search for humans - Adds ~30MB to browser (on-demand model loading) - Best for: Static sites, offline-capable portals
[x] Both (Recommended) - Dual index: qmd for Claude, Orama for browser - Same semantic search quality for AI and humans
[ ] None (Skip search) - Use basic VitePress search (keyword only) - Can add semantic search later with /secondbrain-search-init

**Based on selection:**

| Selection | Actions |
|-----------|---------|
| qmd | Create `.claude/search/`, generate `qmd.config.json`, add search hook |
| Orama | Add Orama deps to `package.json`, generate `SearchBox.vue`, generate build script |
| Both | All of the above |
| None | Skip search setup, use VitePress native search |
你想要启用哪种语义搜索？
[ ] qmd（Claude Code搜索） - 基于CLI的AI语义搜索 - 依赖：bun/npm install -g qmd（约1.5GB模型） - 最适合：本地开发、Claude Code集成
[ ] Orama（VitePress浏览器搜索） - 面向用户的客户端语义搜索 - 浏览器端增加约30MB（按需加载模型） - 最适合：静态站点、离线可用门户
[x] 两者都启用（推荐） - 双索引：qmd用于Claude，Orama用于浏览器 - AI与用户使用相同质量的语义搜索
[ ] 都不启用（跳过搜索） - 使用基础VitePress搜索（仅关键词） - 后续可通过/secondbrain-search-init启用语义搜索

**根据选择执行以下操作：**

| 选择 | 操作 |
|-----------|---------|
| qmd | 创建`.claude/search/`，生成`qmd.config.json`，添加搜索钩子 |
| Orama | 向`package.json`添加Orama依赖，生成`SearchBox.vue`，生成构建脚本 |
| 两者都启用 | 执行以上所有操作 |
| 都不启用 | 跳过搜索设置，使用VitePress原生搜索 |

Step 5: Configure Maximum Freedom Settings

步骤5：配置最大自由度设置

CRITICAL: Always propose creating 
.claude/settings.local.json
with maximum permissions:
json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "_comment": "Secondbrain project - maximum freedom for knowledge management",

  "permissions": {
    "allow_web_search": true,
    "allow_web_fetch": ["*"],
    "allow_read": ["~/**", "/tmp/**"],
    "allow_bash": ["*"],
    "auto_approve_write": ["<project_path>/docs/**"]
  }
}
Show the settings and ask for confirmation before proceeding.
重要：始终建议创建拥有最高权限的
.claude/settings.local.json
：
json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "_comment": "Secondbrain project - maximum freedom for knowledge management",

  "permissions": {
    "allow_web_search": true,
    "allow_web_fetch": ["*"],
    "allow_read": ["~/**", "/tmp/**"],
    "allow_bash": ["*"],
    "auto_approve_write": ["<project_path>/docs/**"]
  }
}
展示该配置并在继续前请求用户确认。

Step 6: Generate Scaffolding

步骤6：生成项目骨架

Create the following structure:
<project-name>/
├── .claude/
│   ├── settings.local.json     # Max freedom permissions + hooks
│   ├── data/
│   │   ├── config.yaml         # Project configuration
│   │   ├── adrs/               # (if enabled)
│   │   │   ├── schema.yaml
│   │   │   └── records.yaml
│   │   ├── discussions/        # (if enabled)
│   │   │   ├── schema.yaml
│   │   │   └── YYYY-MM.yaml    # Current month
│   │   ├── notes/              # (if enabled)
│   │   │   ├── schema.yaml
│   │   │   └── records.yaml
│   │   └── tasks/              # (if enabled)
│   │       ├── schema.yaml
│   │       └── records.yaml
│   ├── lib/
│   │   └── tracking.py         # CRUD library with validation
│   ├── hooks/
│   │   ├── freshness-check.py
│   │   ├── sidebar-check.py
│   │   ├── session-context.py
│   │   └── search-index-update.py  # (if qmd enabled)
│   └── search/                     # (if qmd enabled)
│       └── (qmd index files)
├── docs/
│   ├── .vitepress/
│   │   ├── config.ts           # Navigation, sidebar, plugins
│   │   ├── theme/
│   │   │   ├── index.ts
│   │   │   ├── Layout.vue      # Giscus comments
│   │   │   ├── custom.css
│   │   │   └── components/
│   │   │       ├── EntityTable.vue
│   │   │       └── SearchBox.vue   # (if Orama enabled)
│   │   └── data/
│   │       └── <entity>.data.ts # Per enabled entity
│   ├── index.md                # Home page
│   ├── adrs/                   # (if enabled)
│   │   ├── index.md
│   │   └── TEMPLATE.md
│   ├── discussions/            # (if enabled)
│   │   ├── index.md
│   │   └── TEMPLATE.md
│   ├── notes/                  # (if enabled)
│   │   └── index.md
│   └── tasks/                  # (if enabled)
│       └── index.md
├── package.json                # VitePress dependencies
├── qmd.config.json             # (if qmd enabled)
├── CLAUDE.md                   # Project instructions
└── .gitignore
创建以下目录结构：
<project-name>/
├── .claude/
│   ├── settings.local.json     # 最高权限设置 + 钩子
│   ├── data/
│   │   ├── config.yaml         # 项目配置
│   │   ├── adrs/               # （若启用）
│   │   │   ├── schema.yaml
│   │   │   └── records.yaml
│   │   ├── discussions/        # （若启用）
│   │   │   ├── schema.yaml
│   │   │   └── YYYY-MM.yaml    # 当前月份
│   │   ├── notes/              # （若启用）
│   │   │   ├── schema.yaml
│   │   │   └── records.yaml
│   │   └── tasks/              # （若启用）
│   │       ├── schema.yaml
│   │       └── records.yaml
│   ├── lib/
│   │   └── tracking.py         # 带验证的CRUD库
│   ├── hooks/
│   │   ├── freshness-check.py
│   │   ├── sidebar-check.py
│   │   ├── session-context.py
│   │   └── search-index-update.py  # （若qmd启用）
│   └── search/                     # （若qmd启用）
│       └── (qmd索引文件)
├── docs/
│   ├── .vitepress/
│   │   ├── config.ts           # 导航、侧边栏、插件
│   │   ├── theme/
│   │   │   ├── index.ts
│   │   │   ├── Layout.vue      # Giscus评论
│   │   │   ├── custom.css
│   │   │   └── components/
│   │   │       ├── EntityTable.vue
│   │   │       └── SearchBox.vue   # （若Orama启用）
│   │   └── data/
│   │       └── <entity>.data.ts # 每个启用的实体对应文件
│   ├── index.md                # 首页
│   ├── adrs/                   # （若启用）
│   │   ├── index.md
│   │   └── TEMPLATE.md
│   ├── discussions/            # （若启用）
│   │   ├── index.md
│   │   └── TEMPLATE.md
│   ├── notes/                  # （若启用）
│   │   └── index.md
│   └── tasks/                  # （若启用）
│       └── index.md
├── package.json                # VitePress依赖
├── qmd.config.json             # （若qmd启用）
├── CLAUDE.md                   # 项目说明文档
└── .gitignore

Step 7: Generate Files

步骤7：生成文件

For each enabled entity, generate from templates in 
${CLAUDE_PLUGIN_ROOT}/templates/
:
  1. Microdatabase files:
    • config.yaml
      from 
      scaffolding/microdatabase/config.yaml.tmpl
    • Entity 
      schema.yaml
      from 
      entities/<entity>/schema.yaml
    • Entity 
      records.yaml
      initialized empty
  2. VitePress files:
    • config.ts
      from 
      scaffolding/vitepress/config.ts.tmpl
    • Theme files from 
      scaffolding/vitepress/theme/
    • Data loaders from 
      scaffolding/vitepress/data/
  3. Documentation:
    • Home page from 
      scaffolding/docs/index.md.tmpl
    • Entity index pages from 
      scaffolding/docs/entity-index.md.tmpl
    • Templates from 
      entities/<entity>/TEMPLATE.md
  4. Automation:
    • settings.local.json
      from 
      scaffolding/claude/settings.local.json.tmpl
    • tracking.py
      from 
      scaffolding/lib/tracking.py.tmpl
    • Hooks from 
      hooks/
      (copy to project)
  5. Search (if enabled):
    • qmd: 
      qmd.config.json
      from 
      scaffolding/search/qmd.config.json.tmpl
    • qmd: Copy 
      search-index-update.py
      hook
    • Orama: 
      SearchBox.vue
      from 
      scaffolding/vitepress/theme/components/SearchBox.vue.tmpl
    • Orama: 
      build-search-index.ts
      from 
      scaffolding/vitepress/search/build-search-index.ts.tmpl
    • Orama: Add dependencies to 
      package.json
对于每个启用的实体，从
${CLAUDE_PLUGIN_ROOT}/templates/
中的模板生成：
  1. 微数据库文件：
    • config.yaml
      来自 
      scaffolding/microdatabase/config.yaml.tmpl
    • 实体
      schema.yaml
      来自 
      entities/<entity>/schema.yaml
    • 实体
      records.yaml
      初始化为空
  2. VitePress文件：
    • config.ts
      来自 
      scaffolding/vitepress/config.ts.tmpl
    • 主题文件来自 
      scaffolding/vitepress/theme/
    • 数据加载器来自 
      scaffolding/vitepress/data/
  3. 文档：
    • 首页来自 
      scaffolding/docs/index.md.tmpl
    • 实体索引页来自 
      scaffolding/docs/entity-index.md.tmpl
    • 模板来自 
      entities/<entity>/TEMPLATE.md
  4. 自动化文件：
    • settings.local.json
      来自 
      scaffolding/claude/settings.local.json.tmpl
    • tracking.py
      来自 
      scaffolding/lib/tracking.py.tmpl
    • 钩子文件来自 
      hooks/
      （复制到项目中）
  5. 搜索文件（若启用）：
    • qmd： 
      qmd.config.json
      来自 
      scaffolding/search/qmd.config.json.tmpl
    • qmd： 复制
      search-index-update.py
      钩子
    • Orama： 
      SearchBox.vue
      来自 
      scaffolding/vitepress/theme/components/SearchBox.vue.tmpl
    • Orama： 
      build-search-index.ts
      来自 
      scaffolding/vitepress/search/build-search-index.ts.tmpl
    • Orama： 向
      package.json
      添加依赖

Step 8: Show Summary

步骤8：展示总结

undefined
undefined

Secondbrain Created Successfully!

Secondbrain创建成功！

Project: my-knowledge-base Location: /path/to/my-knowledge-base Entities: ADRs, Discussions, Notes
项目： my-knowledge-base 位置： /path/to/my-knowledge-base 实体： ADRs、Discussions、Notes

Structure Created

已创建的结构

.claude/ ├── settings.local.json ✓ Maximum freedom permissions ├── data/ ✓ Microdatabases with schemas ├── lib/tracking.py ✓ CRUD operations └── hooks/ ✓ Automation hooks
docs/ ├── .vitepress/ ✓ Custom theme with EntityTable ├── adrs/ ✓ Decision records ├── discussions/ ✓ Meeting notes └── notes/ ✓ Knowledge capture
.claude/ ├── settings.local.json ✓ 最高权限设置 ├── data/ ✓ 带Schema的微数据库 ├── lib/tracking.py ✓ CRUD操作 └── hooks/ ✓ 自动化钩子
docs/ ├── .vitepress/ ✓ 带EntityTable的自定义主题 ├── adrs/ ✓ 决策记录 ├── discussions/ ✓ 会议记录 └── notes/ ✓ 知识捕获

Next Steps

下一步操作

  1. Navigate to project: cd my-knowledge-base
  2. Install dependencies: npm install
  3. Start development server: npm run docs:dev
  4. Create your first decision: /secondbrain-adr infrastructure my-first-decision
  5. Add a note: /secondbrain-note my-first-note
  1. 进入项目目录： cd my-knowledge-base
  2. 安装依赖： npm install
  3. 启动开发服务器： npm run docs:dev
  4. 创建你的第一条决策： /secondbrain-adr infrastructure my-first-decision
  5. 添加一条笔记： /secondbrain-note my-first-note

Available Commands

可用命令

  • /secondbrain-search <query> — Semantic search (if enabled)
  • /secondbrain-adr <category> <title> — Create ADR
  • /secondbrain-note <title> — Create note
  • /secondbrain-discussion <who> <topic> — Document discussion
  • /secondbrain-freshness — Check what needs attention
  • /secondbrain-entity <name> — Add custom entity type
  • /secondbrain-search-init — Enable semantic search later
undefined
  • /secondbrain-search <query> — 语义搜索（若启用）
  • /secondbrain-adr <category> <title> — 创建ADR
  • /secondbrain-note <title> — 创建笔记
  • /secondbrain-discussion <who> <topic> — 记录讨论内容
  • /secondbrain-freshness — 检查需要关注的内容
  • /secondbrain-entity <name> — 添加自定义实体类型
  • /secondbrain-search-init — 后续启用语义搜索
undefined

Template Variables

模板变量

When generating files, replace these variables:
VariableDescription
{{project_name}}
Project name (kebab-case)
{{project_path}}
Absolute path to project
{{description}}
Project description
{{date}}
Current date (YYYY-MM-DD)
{{timestamp}}
Current ISO timestamp
{{year_month}}
Current year-month (YYYY-MM)
{{entities}}
Array of enabled entity configs
生成文件时，替换以下变量：
变量描述
{{project_name}}
项目名称（短横线命名）
{{project_path}}
项目绝对路径
{{description}}
项目描述
{{date}}
当前日期（YYYY-MM-DD）
{{timestamp}}
当前ISO时间戳
{{year_month}}
当前年月（YYYY-MM）
{{entities}}
已启用实体配置的数组

Entity Configuration

实体配置

Each entity has standard configuration:
yaml
<entity_slug>:
  enabled: true
  label: "Entity Label"
  singular: "Entity"
  doc_path: docs/<entity_slug>
  freshness:
    stale_after_days: 30
每个实体都有标准配置：
yaml
<entity_slug>:
  enabled: true
  label: "实体标签"
  singular: "实体"
  doc_path: docs/<entity_slug>
  freshness:
    stale_after_days: 30

Additional Resources

额外资源

Reference Files

参考文件

For detailed entity schemas and templates:
  • references/entity-schemas.md
     — Predefined entity schema definitions
如需详细的实体Schema和模板：
  • references/entity-schemas.md
     — 预定义的实体Schema定义

Related Skills

相关Skill

  • secondbrain-search — Semantic search your knowledge base
  • secondbrain-search-init — Enable search on existing project
  • secondbrain-entity — Add custom entity types
  • secondbrain-adr — Create Architecture Decision Records
  • secondbrain-note — Create notes
  • secondbrain-task — Create tasks
  • secondbrain-discussion — Document discussions
  • secondbrain-freshness — Freshness report
  • secondbrain-search — 语义搜索你的知识库
  • secondbrain-search-init — 在现有项目中启用搜索
  • secondbrain-entity — 添加自定义实体类型
  • secondbrain-adr — 创建架构决策记录
  • secondbrain-note — 创建笔记
  • secondbrain-task — 创建任务
  • secondbrain-discussion — 记录讨论内容
  • secondbrain-freshness — 新鲜度报告