# Technical Documentation: Innei/Shiro

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/Innei/Shiro)

### Overview (`README.md`)

# Shiro

> [!IMPORTANT]
> **Shiro 已进入维护模式，将停留在当前版本，不再添加新功能，仅修复关键 Bug。**
>
> 如果你正在寻找一个全新的个人博客前端，请关注 **[余白 / Yohaku](https://github.com/Innei/Yohaku)** — 一个独立的新项目，拥有全新的设计语言与视觉体系。完整代码需 [赞助](https://github.com/sponsors/Innei) 获取访问权限。
>
> **Shiro 要求 Mix Space Core 版本 == 10.x**，不兼容更高版本。

一个极简主义的个人网站主题，如纸的纯净，似雪的清新。

专为 [Mix Space](https://github.com/mx-space) 生态系统设计的现代化个人站点前端。

## :sparkles: 示例站点

以下是一些使用 Shiro 主题的精美站点：

- [静かな森](https://innei.in)
- [可愛い松](https://blog.wibus.ren/)


欢迎体验 Shiro 带来的极简之美！

## :rocket: 核心特性

- **:zap: 极致性能**：在 LightHouse 测试中表现卓越，Performance 和 Best Practice 均超过 90%
- **:art: 现代设计**：简洁而不简单的用户界面，提供流畅优雅的用户体验
- **:gem: 细节至上**：采用符合物理学的 Spring 弹性动画，每一帧都如自然般舒适
- **:bell: 实时通知**：通过 WebSocket 连接，访客可实时接收最新文章推送
- **:computer: 活动状态**：结合 [ProcessReporter](https://github.com/Innei/ProcessReporter)，在主页展示实时活动状态
- **:pencil: 扩展语法**：支持丰富的 Markdown 扩展语法，满足多样化写作需求
- **:house: 精美首页**：Hero 区域、活动流、时间线展示、风向标导航
- **:bulb: 思考系统**：独立的思考（Recently）页面，支持评论、点赞、RSS Feed
- **:clock3: 时间线**：按年份、类型筛选的文章/手记时间线
- **:globe_with_meridians: 多语言**：基于 next-intl 的国际化支持

## :gear: 技术架构

基于现代化的前端技术栈构建：

- **NextJS 16** (App Router) - React 全栈框架
- **Jotai** - 原子化状态管理
- **Motion** - 流畅动画库
- **Radix UI** - 无障碍组件库
- **Socket.IO** - 实时通信
- **TailwindCSS v4** - 原子化 CSS 框架
- **DaisyUI v5** - 组件库
- **TanStack Query** - 服务端状态管理

## 📖 部署指南

详细的部署教程请参考：https://mx-space.js.org/docs/themes/shiro/deploy

感谢 @wibus-wee、@wuhang2003 等社区贡献者编写的详细文档。

## :camera: 界面预览

<img width="1471" alt="Live Demo" src="https://github.com/Innei/Shiro/assets/41265413/bf8af4ec-0f0c-441a-8c06-4b44e1649597">

<details>
<summary>
点击查看更多完整页面截图
</summary>




</details>

## :zap: 性能测试

在 M2 MacBook Air 环境下对重负载页面的性能测试结果：



## :whale: 快速开始

### :package: 预构建版本

从 [Releases](https://github.com/Innei/Shiro/releases) 页面下载最新的 `release.zip` 压缩包并解压：

```bash
cd standalone
vim .env # 配置环境变量
export PORT=2323
node server.js
```

### :docker: Docker Compose（推荐）

```bash
mkdir shiro && cd shiro
wget https://raw.githubusercontent.com/Innei/Shiro/main/docker-compose.yml
wget https://raw.githubusercontent.com/Innei/Shiro/main/.env.template .env

vim .env # 配置环境变量
mkdir public # 放置自定义 Favicon
docker compose up -d

# 后续更新
docker compose pull
```

## :memo: Markdown 扩展

了解更多 Markdown 扩展语法，请访问：https://shiro.innei.in/#/markdown

## :star: 余白 / Yohaku

**[余白 / Yohaku](https://github.com/Innei/Yohaku)** 是一个全新的个人博客项目，拥有独立的设计语言与视觉体系。如果你希望获得持续更新的体验，推荐关注 Yohaku。

[](https://github.com/sponsors/Innei)

## :star: 白い (Shiroi) - 赞助版

[白い](https://github.com/innei-dev/Shiroi) 是 Shiro 的付费赞助版本，包含更多高级功能：

### :robot: AI 智能功能

- AI 智能摘要生成
- AI 内容翻译系统（支持实时翻译推送）
- AI 生成标记系统（支持标记翻译、摘要、自动生成等内容来源）

### :sparkles: 高级视觉效果

- WebGPU 雪花背景效果（高级粒子物理系统）
- 萤火虫粒子效果
- 纹理背景系统
- 页面渐变色背景
- 噪声背景生成

### :busts_in_silhouette: 实时协作

- Socket.IO 房间管理
- 在线用户实时展示（Presence 组件）
- 访客信息追踪

### :lock: 认证系统

- Passkey 无密码认证支持
- Passkey 管理页面（创建、列表）

### :speech_balloon: 评论系统增强

- Lexical 富文本评论编辑器
- 评论内联编辑功能
- 评论操作按钮组（编辑/回复）

### :bar_chart: 后台系统

- 完整的仪表盘界面
- Lexical 富文本编辑器
- 文章/笔记编辑器增强
- 每日诗词展示（今日诗词 API）

### :chart_with_upwards_trend: 分析集成

- OpenPanel 用户行为分析
- 屏幕视图追踪
- 外链点击追踪

## :heart: 致谢与许可

**© 2026 Innei** - 本项目采用 AGPLv3 许可证，并附加特定的商业使用条件。

使用本项目需要遵循 [附加条款和条件](ADDITIONAL_TERMS.md)。

---

> [个人网站](https://innei.in/) · GitHub [@Innei](https://github.com/innei/)

---

### Plans 2026 02 27 Shiro Monorepo Migration (`docs/plans/2026-02-27-shiro-monorepo-migration.md`)

# Shiro Monorepo Migration & Feature Stripping Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Reset Shiro OSS to mirror Shiroi's monorepo structure, then remove all Shiroi-exclusive premium features.

**Architecture:** Copy Shiroi's full monorepo layout (apps/web + packages/types) into Shiro, excluding rich-* packages. Then systematically strip 12 categories of premium features: i18n, AI, visual effects, presence, thinking enhancements, categories/tags, home enhancements, passkey auth, comment enhancements, dashboard, analytics, and translation.

**Tech Stack:** Next.js 16, pnpm + Turborepo monorepo, Tailwind CSS v4, Jotai, TanStack Query, React 19

---

### Task 1: Clear Shiro Source Files

**Files:**
- Remove: All source files except `.git/`, `README.md`, `LICENSE`, `ADDITIONAL_TERMS.md`, `CHANGELOG.md`

**Step 1: Remove existing source**

```bash
# Keep .git, README, LICENSE, ADDITIONAL_TERMS, CHANGELOG
cd /Users/innei/git/innei-repo/Shiro
# Remove all tracked source files/configs
rm -rf src/ public/ .github/ scripts/
rm -f next.config.mjs tsconfig.json tailwind.config.ts postcss.config.cjs
rm -f eslint.config.mjs .prettierrc.mjs .prettierignore .npmrc
rm -f docker-compose.yml Dockerfile .dockerignore .drone.yml
rm -f vercel.json ecosystem.config.cjs ecosystem.standalone.config.cjs
rm -f renovate.json .gitmodules turbo.json pnpm-lock.yaml
rm -f package.json global.d.ts next-env.d.ts tsconfig.tsbuildinfo
rm -f NOTE.md TODO.md SAY.md setup-git.sh taze.config.js
rm -f .env.template app.config.ts
rm -rf reporter-assets/
```

**Step 2: Verify clean state**

Only `.git/`, `README.md`, `LICENSE`, `ADDITIONAL_TERMS.md`, `CHANGELOG.md`, `docs/` should remain.

---

### Task 2: Copy Shiroi Monorepo Root Structure

**Files:**
- Copy from Shiroi: Root config files

**Step 1: Copy root configs**

```bash
SHIROI=/Users/innei/git/innei-repo/Shiroi
SHIRO=/Users/innei/git/innei-repo/Shiro

cp "$SHIROI/package.json" "$SHIRO/"
cp "$SHIROI/turbo.json" "$SHIRO/"
cp "$SHIROI/pnpm-workspace.yaml" "$SHIRO/"
cp "$SHIROI/eslint.config.mjs" "$SHIRO/"
cp "$SHIROI/.prettierrc.mjs" "$SHIRO/"
cp "$SHIROI/.prettierignore" "$SHIRO/"
cp "$SHIROI/.npmrc" "$SHIRO/"
cp "$SHIROI/.gitignore" "$SHIRO/"
cp "$SHIROI/taze.config.js" "$SHIRO/"
cp "$SHIROI/renovate.json" "$SHIRO/"
cp "$SHIROI/docker-compose.yml" "$SHIRO/"
cp "$SHIROI/Dockerfile" "$SHIRO/"
cp "$SHIROI/.dockerignore" "$SHIRO/"
cp "$SHIROI/.drone.yml" "$SHIRO/"
cp "$SHIROI/NOTE.md" "$SHIRO/"
cp "$SHIROI/SAY.md" "$SHIRO/"
cp "$SHIROI/setup-git.sh" "$SHIRO/"
cp "$SHIROI/bump.config.ts" "$SHIRO/"
```

**Step 2: Copy .github directory**

```bash
cp -R "$SHIROI/.github" "$SHIRO/"
```

**Step 3: Copy .vscode directory**

```bash
cp -R "$SHIROI/.vscode" "$SHIRO/"
```

---

### Task 3: Copy apps/web from Shiroi

**Step 1: Copy entire apps/web**

```bash
mkdir -p "$SHIRO/apps"
cp -R "$SHIROI/apps/web" "$SHIRO/apps/"
```

---

### Task 4: Copy packages/types from Shiroi

**Step 1: Copy types package only**

```bash
mkdir -p "$SHIRO/packages"
cp -R "$SHIROI/packages/types" "$SHIRO/packages/"
```

---

### Task 5: Clean Root package.json

**Files:**
- Modify: `package.json`

**Step 1: Remove rich-* related scripts**

Remove `build:rich`, `publish:rich`, `release:rich` scripts from root package.json. Keep `build`, `dev`, `lint`, `prepare`, `release`, `release:dry`.

**Step 2: Rename project**

Change `"name": "shiroi"` to `"name": "shiro"`.

---

### Task 6: Remove i18n System

This is the most complex removal. All routes live under `[locale]/`.

**Files:**
- Remove: `apps/web/src/i18n/` (entire directory)
- Remove: `apps/web/src/messages/` (entire directory)
- Remove: `apps/web/src/atoms/translation.ts`
- Remove: `apps/web/src/components/layout/footer/LocaleSwitcher.tsx`
- Remove: `apps/web/src/components/common/DayjsLocaleSync.tsx`
- Remove: `apps/web/src/providers/root/intl-provider.tsx`
- Remove: `apps/web/src/providers/root/lang-sync-provider.tsx`
- Modify: `apps/web/next.config.mjs` - remove next-intl plugin
- Modify: `apps/web/package.json` - remove `next-intl` dependency

**Step 1: Remove i18n directories**

```bash
rm -rf "$SHIRO/apps/web/src/i18n"
rm -rf "$SHIRO/apps/web/src/messages"
```

**Step 2: Flatten [locale] routes**

Move all contents from `apps/web/src/app/[locale]/` up to `apps/web/src/app/`:

```bash
# Move contents up, merging with existing app/ files
cp -R "$SHIRO/apps/web/src/app/[locale]/"* "$SHIRO/apps/web/src/app/"
rm -rf "$SHIRO/apps/web/src/app/[locale]"
```

**Step 3: Remove i18n components and providers**

```bash
rm -f "$SHIRO/apps/web/src/atoms/translation.ts"
rm -f "$SHIRO/apps/web/src/components/layout/footer/LocaleSwitcher.tsx"
rm -f "$SHIRO/apps/web/src/components/common/DayjsLocaleSync.tsx"
rm -f "$SHIRO/apps/web/src/providers/root/intl-provider.tsx"
rm -f "$SHIRO/apps/web/src/providers/root/lang-sync-provider.tsx"
```

**Step 4: Remove next-intl from next.config.mjs and package.json**

Remove `next-intl` plugin wrapping and dependency.

**Step 5: Search and replace all `useTranslations`/`getTranslations`/`useLocale` usages**

Replace i18n function calls with hardcoded Chinese strings or remove the translated text.

---

### Task 7: Remove AI Features

**Files:**
- Remove: `apps/web/src/components/modules/ai/` (entire directory)
- Remove: `apps/web/src/components/modules/shared/SummarySwitcher.tsx`
- Modify: Post/note pages to remove AI summary references

**Step 1: Delete AI module directory**

```bash
rm -rf "$SHIRO/apps/web/src/components/modules/ai"
rm -f "$SHIRO/apps/web/src/components/modules/shared/SummarySwitcher.tsx"
```

**Step 2: Remove AI imports from post/note pages**

Search for and remove AI-related imports and component usages.

---

### Task 8: Remove Visual Effects

**Files:**
- Remove: `apps/web/src/components/ui/background/` (entire directory)
- Remove: `apps/web/src/workers/` (if exists, for WebGPU workers)
- Remove: `apps/web/src/lib/noise.ts`
- Remove: `apps/web/src/types/webgpu-shim.d.ts`

```bash
rm -rf "$SHIRO/apps/web/src/components/ui/background"
rm -rf "$SHIRO/apps/web/src/workers"
rm -f "$SHIRO/apps/web/src/lib/noise.ts"
rm -f "$SHIRO/apps/web/src/types/webgpu-shim.d.ts"
```

---

### Task 9: Remove Presence/Activity System

**Files:**
- Remove: `apps/web/src/components/modules/activity/` (entire directory)
- Remove: `apps/web/src/atoms/activity.ts`
- Remove: `apps/web/src/atoms/hooks/activity.ts`
- Remove: `apps/web/src/models/activity.ts`
- Remove: `apps/web/src/queries/definition/activity.ts`
- Remove: `apps/web/src/socket/handlers/activity.ts`
- Remove: `apps/web/src/components/layout/header/internal/Activity.tsx`

```bash
rm -rf "$SHIRO/apps/web/src/components/modules/activity"
rm -f "$SHIRO/apps/web/src/atoms/activity.ts"
rm -f "$SHIRO/apps/web/src/atoms/hooks/activity.ts"
rm -f "$SHIRO/apps/web/src/models/activity.ts"
rm -f "$SHIRO/apps/web/src/queries/definition/activity.ts"
rm -f "$SHIRO/apps/web/src/socket/handlers/activity.ts"
rm -f "$SHIRO/apps/web/src/components/layout/header/internal/Activity.tsx"
```

---

### Task 10: Remove Thinking System Enhancements

**Files:**
- Remove: `apps/web/src/app/thinking/` (flattened from [locale]) - detail page, feed, comments
- Remove: `apps/web/src/socket/handlers/recently.ts`

```bash
rm -rf "$SHIRO/apps/web/src/app/thinking"
rm -f "$SHIRO/apps/web/src/socket/handlers/recently.ts"
```

---

### Task 11: Remove Categories & Tags Pages

**Files:**
- Remove: `apps/web/src/app/categories/` (flattened from [locale])
- Remove: `apps/web/src/app/posts/tag/`

```bash
rm -rf "$SHIRO/apps/web/src/app/categories"
rm -rf "$SHIRO/apps/web/src/app/posts/tag"
```

---

### Task 12: Remove Home Page Enhancements

**Files:**
- Remove/simplify: `apps/web/src/app/(home)/` - strip Hero, Windsock, Timeline, ActivityScreen etc.

Remove enhanced home components (Hero, Windsock, HomePageTimeLine, ActivityCard, ActivityScreen, ActivityRecent, ActivityPostList, TwoColumnLayout).

---

### Task 13: Remove Timeline

**Files:**
- Remove: `apps/web/src/app/timeline/` (flattened)
- Remove: `apps/web/src/components/modules/timeline/`

```bash
rm -rf "$SHIRO/apps/web/src/app/timeline"
rm -rf "$SHIRO/apps/web/src/components/modules/timeline"
```

---

### Task 14: Remove Passkey Auth

**Files:**
- Remove: `apps/web/src/routes/passkey/`
- Remove: `apps/web/src/lib/authn.ts`

```bash
rm -rf "$SHIRO/apps/web/src/routes/passkey"
rm -f "$SHIRO/apps/web/src/lib/authn.ts"
```

---

### Task 15: Remove Comment Enhancements

**Files:**
- Modify: `apps/web/src/components/modules/comment/` - remove inline editing, action button group enhancements

Remove `CommentActionButtonGroup.tsx` enhanced features (edit functionality). Keep basic comment display and reply.

---

### Task 16: Remove Dashboard

**Files:**
- Remove: `apps/web/src/app/(dashboard)/` (entire directory)
- Remove: `apps/web/src/components/modules/dashboard/` (entire directory)

```bash
rm -rf "$SHIRO/apps/web/src/app/(dashboard)"
rm -rf "$SHIRO/apps/web/src/components/modules/dashboard"
```

---

### Task 17: Remove OpenPanel Analytics

**Files:**
- Remove: `apps/web/src/lib/openpanel.ts`
- Remove: `apps/web/src/components/common/OpenPanelInit.tsx`
- Remove: `apps/web/src/app/analyze.tsx` (flattened)

```bash
rm -f "$SHIRO/apps/web/src/lib/openpanel.ts"
rm -f "$SHIRO/apps/web/src/components/common/OpenPanelInit.tsx"
rm -f "$SHIRO/apps/web/src/app/analyze.tsx"
```

---

### Task 18: Remove Translation System

**Files:**
- Remove: `apps/web/src/components/modules/translation/` (entire directory)
- Remove: `apps/web/src/socket/handlers/translation.ts`

```bash
rm -rf "$SHIRO/apps/web/src/components/modules/translation"
rm -f "$SHIRO/apps/web/src/socket/handlers/translation.ts"
```

---

### Task 19: Cleanup Dependencies

**Files:**
- Modify: `apps/web/package.json`

Remove unused dependencies:
- `next-intl` (i18n)
- `@openpanel/nextjs` (analytics)
- `@simplewebauthn/browser` (passkey)
- `@lexical/*` (dashboard rich editor)
- Any other deps only used by removed features

---

### Task 20: Fix Broken Imports & Build

**Step 1: Search for broken imports**

Grep for imports referencing removed modules and fix them.

**Step 2: Remove references to removed components from layout files, providers, etc.**

**Step 3: Attempt build**

```bash
cd "$SHIRO" && pnpm install && pnpm build
```

Fix any build errors iteratively.

---

### Task 21: Final Cleanup

- Remove `apps/web/src/app/(dashboard)/` references from any navigation
- Remove Shiroi-specific branding (if any)
- Ensure all `useTranslations` calls are replaced
- Remove unused provider wrappers
- Clean up socket handler registrations

---

--- METRICS ---
- Files Extracted: 2
- Estimated Token Budget: ~3536 tokens
- Canonical Reference: https://codewiki.google/github.com/Innei/Shiro