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:

Project name (kebab-case, e.g.,
```
my-knowledge-base
```
)
Target directory (default:
```
./<project-name>
```
)
Use case (optional context for customization):
- Personal knowledge base
- Project documentation
- Team collaboration

向用户询问以下信息：

项目名称（短横线命名，例如
```
my-knowledge-base
```
）
目标目录（默认：
```
./<project-name>
```
）
使用场景（可选，用于自定义的上下文）：
- 个人知识库
- 项目文档
- 团队协作

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/

Microdatabase files:

config.yaml

from

scaffolding/microdatabase/config.yaml.tmpl

Entity

schema.yaml

from

entities/<entity>/schema.yaml

Entity
```
records.yaml
```
initialized empty

VitePress files:

config.ts

from

scaffolding/vitepress/config.ts.tmpl

Theme files from
```
scaffolding/vitepress/theme/
```
Data loaders from
```
scaffolding/vitepress/data/
```

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
```

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)

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/

中的模板生成：

微数据库文件：

config.yaml

来自

scaffolding/microdatabase/config.yaml.tmpl

实体

schema.yaml

来自

entities/<entity>/schema.yaml

实体
```
records.yaml
```
初始化为空

VitePress文件：

config.ts

来自

scaffolding/vitepress/config.ts.tmpl

主题文件来自
```
scaffolding/vitepress/theme/
```
数据加载器来自
```
scaffolding/vitepress/data/
```

文档：

首页来自
```
scaffolding/docs/index.md.tmpl
```
实体索引页来自
```
scaffolding/docs/entity-index.md.tmpl
```
模板来自
```
entities/<entity>/TEMPLATE.md
```

自动化文件：

settings.local.json

来自

scaffolding/claude/settings.local.json.tmpl

tracking.py

来自

scaffolding/lib/tracking.py.tmpl

钩子文件来自
```
hooks/
```
（复制到项目中）

搜索文件（若启用）：

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

下一步操作

Navigate to project: cd my-knowledge-base
Install dependencies: npm install
Start development server: npm run docs:dev
Create your first decision: /secondbrain-adr infrastructure my-first-decision
Add a note: /secondbrain-note my-first-note

进入项目目录： cd my-knowledge-base
安装依赖： npm install
启动开发服务器： npm run docs:dev
创建你的第一条决策： /secondbrain-adr infrastructure my-first-decision
添加一条笔记： /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:

Variable	Description
`{{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定义

secondbrain-init

Original

Translation

Secondbrain Project Scaffolding

Secondbrain项目搭建

Overview

概述

Workflow

工作流程

Step 1: Gather Project Information

步骤1：收集项目信息

Step 2: Select Entity Types

步骤2：选择实体类型

Entity Selection

实体选择

Step 3: Configure Semantic Search

步骤3：配置语义搜索

Search Configuration

搜索配置

Step 5: Configure Maximum Freedom Settings

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

Step 6: Generate Scaffolding

步骤6：生成项目骨架

Step 7: Generate Files

步骤7：生成文件

Step 8: Show Summary

步骤8：展示总结

Secondbrain Created Successfully!

Secondbrain创建成功！

Structure Created

已创建的结构

Next Steps

下一步操作

Available Commands

可用命令

Template Variables

模板变量

Entity Configuration

实体配置

Additional Resources

额外资源

Reference Files

参考文件

Related Skills

相关Skill