@hutusi/amytis 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0] - 2026-03-25
+
+### Added
+- **Slug Rename Redirects**: Added `redirectFrom` support for post slug renames within the same URL prefix so renamed content can keep resolving from legacy paths.
+- **Series Slug Migration**: Added `redirectFrom` support for series slug renames, preserving access to older series URLs after route changes.
+
+### Changed
+- **Series Routing Defaults**: `series.autoPaths` now defaults to `true`, making `/<series-slug>/<post-slug>` the standard route shape for series posts.
+- **README Positioning**: Updated the English README to match the latest Chinese version, including the project backstory and refreshed documentation structure.
+
+### Fixed
+- **Route Conflict Handling**: Prevented auto-path series slugs from colliding with configured `series.customPaths` values during route generation.
+
 ## [1.12.0] - 2026-03-08
 
 ### Added

package/README.md

@@ -2,22 +2,37 @@
 
 [English](README.md) | [简体中文](README.zh.md)
 
-**Amytis** is an elegant, open-source framework for building a personal digital garden: a living knowledge space where ideas grow from raw notes to refined writing. It is built with Next.js 16, React 19, and Tailwind CSS v4, with a strong focus on readability, structure, and long-term content ownership.
+**Amytis** is a powerful, elegant, and user-friendly open-source digital garden framework for building knowledge spaces, blogs, showcase sites, or internal knowledge bases. It is built with Next.js 16, Tailwind CSS v4, and Bun, emphasizing a Markdown-first, plain-text-first workflow that preserves long-term content ownership while pursuing simplicity, elegance, and performance.
 
 [**Live Demo**](https://amytis.vercel.app/)
 
 ![Amytis Screenshot](public/images/amytis-screenshot.jpg)
 
-## The Knowledge Ladder
+## Why Amytis?
 
-Amytis is built around a simple path from rough to refined:
+I have been [blogging for twenty years](https://hutusi.com/archive), starting from early blogging platforms such as MSN Space (MS Live Space) and Sina Blog, then moving to self-hosted WordPress and Drupal, and later fully adopting static blogging frameworks after GitHub Pages became available. I tried Jekyll, Hugo, and several of their themes, but none of them truly satisfied me. The feature-rich ones were often not simple or elegant enough, while the elegant ones usually lacked flexibility and customization. I kept wondering whether a blogging or knowledge platform framework could balance functionality, performance, aesthetics, and UX. That idea stayed with me for years. When I finally decided to build one myself, I found it much harder than I had expected.
 
-- **Flow**: Capture raw daily thoughts and fragments.
-- **Articles**: Refine one idea into a clear essay.
-- **Series**: Connect related articles into a curated narrative.
-- **Books**: Distill mature knowledge into structured chapters and parts.
+Fortunately, AI coding changed that equation. With the help of Claude Code, Gemini CLI, and Codex, it became much easier than before to turn the idea into reality. After more than 700 commits of iteration, Amytis finally took shape as the idealized knowledge platform framework I had been aiming for. It was first used in the geek community platform I built at work, and I also replaced the framework behind my Hutusi blog with it. Amytis is now open source. Independent bloggers and knowledge managers are welcome to use it, and contributions, bug reports, and pull requests are all appreciated. If you are using Amytis, feel free to leave a note in [this issue](https://github.com/hutusi/amytis/issues/49).
 
-Each stage builds on the previous one, so your garden can evolve naturally.
+### The Knowledge Ladder
+
+Amytis is built around a path from fragmented thoughts to refined knowledge, helping individuals or teams build a complete digital garden system:
+
+- **Flow**: Capture daily thoughts and brainstorming fragments.
+- **Articles**: Refine a single idea into a clear article.
+- **Series**: Connect related articles into a thematic narrative.
+- **Books**: Distill mature knowledge into structured, chapter-based books.
+
+Each stage builds on the one before it, so the garden can grow naturally.
+
+### Design Philosophy
+
+- **Elegance by default**: Typography, spacing, and color should feel polished out of the box and remain visually consistent.
+- **Content and plain text first**: Writing and publishing should happen through file-based workflows rather than a heavyweight CMS. Content lives in Markdown/MDX, can be versioned with Git, and remains portable over time.
+- **Markdown-first, not markdown-limited**: Markdown and common extensions are supported by default, while math, diagrams, code, and bidirectional links remain first-class.
+- **Ship what you need**: `site.config.ts` provides modular switches so you only enable the capabilities you actually need.
+
+Further reading: [How to Get AI to Write Better Code](https://hutusi.com/weeklies/25) (Chinese)
 
 ## Features
 
@@ -65,14 +80,6 @@ Each stage builds on the previous one, so your garden can evolve naturally.
 - **Content CLI Tools:** Create posts, series, and import from PDFs or image folders.
 - **Modern Stack:** Next.js 16, React 19, Tailwind CSS v4, TypeScript 5, Bun.
 
-## Design Philosophy
-
-- **Elegance by default**: Typography, spacing, and color should feel intentional out of the box.
-- **Content over configuration**: Writing and publishing should be simple file-based workflows, not CMS-heavy setup.
-- **Markdown-first, not markdown-limited**: Keep authoring portable while supporting rich output (math, diagrams, code, wikilinks).
-- **Ship what you need**: Features are modular through `site.config.ts`; disable sections you do not use.
-- **Plain text, long-term ownership**: Content stays in Markdown/MDX so it remains versionable and portable.
-
 ## Quick Start
 
 ### New Project (Recommended)

package/README.zh.md

@@ -2,73 +2,89 @@
 
 [English](README.md) | [简体中文](README.zh.md)
 
-**Amytis** 是一个优雅的开源数字花园框架，用于构建个人知识空间。它基于 Next.js 16、React 19 和 Tailwind CSS v4，强调可读性、结构化表达与长期内容所有权。
+**Amytis** 是一个功能强大、设计优雅、交互友好的开源数字花园框架，用于构建知识空间、博客、展示页面或企业知识库等。它基于 Next.js 16、Tailwind CSS v4 和 Bun 构建，强调 Markdown 优先、文本优先，保障作者对内容的长期所有权，在不损失功能和性能的前提下追求极致简洁与优雅。
 
 [**在线演示**](https://amytis.vercel.app/)
 
 ![Amytis 截图](public/images/amytis-screenshot.jpg)
 
-## 知识阶梯
+## 为什么要做 Amytis ?
 
-Amytis 围绕一条从粗糙到精炼的知识路径构建：
+我写[博客有二十年](https://hutusi.com/archive)了，从最早的博客平台，如 MSN Space (MS Live Space)、新浪博客，到自己搭建 Wordpress、Drupal, 再到 GitHub Pages 推出后全面采用静态博客框架，折腾过 Jekyll、Hugo 及其多个主题，但没有一个框架或主题能让自己真正满意。功能复杂的不够简洁或优雅，简洁优雅的又缺少功能定制。能不能有一款兼顾功能、性能、美观、UX 的博客或知识平台框架呢？这个想法最近几年一直萦绕在我的脑海，实在找不到那就做一个，等到准备付诸实践，才发现难度比想象中的要大得多。
 
-- **Flow（随笔）**：记录每日想法与碎片。
-- **Articles（文章）**：将单个想法打磨成清晰文章。
+好在有 AI 编程，在 Claude Code/Gemini CLI/Codex 的帮助下，比以往要更容易实现自己的想法，在经过 700 多次 Commit 的打磨后，理想化的知识平台框架 —— Amytis 终于交付成稿，我在公司搭建的极客社区平台首次应用，并将胡涂说博客网站框架也进行了替换。同时，也将 Amytis 开源，欢迎更多的独立博主/知识管理者使用，更欢迎帮忙发现问题、提 PR 添砖加瓦。如果你也在使用 Amytis, 欢迎在[此 issue 留言](https://github.com/hutusi/amytis/issues/49)。
+
+### 知识阶梯
+
+Amytis 围绕一条从碎片想法到精炼知识的路径来帮助个人或组织构建完整的数字花园体系：
+
+- **Flow（心流）**：记录每日想法与头脑风暴的灵感碎片。
+- **Articles（文章）**：将单个想法打磨成清晰的文章。
 - **Series（系列）**：把相关文章串联为一条主题叙事。
-- **Books（书籍）**：将成熟知识沉淀为章节化结构。
+- **Books（书籍）**：将成熟知识沉淀为章节化结构的书籍。
 
-每个阶段都建立在上一阶段之上，花园会自然生长。
+每个阶段都建立在上一阶段之上，数字花园会自然生长。
 
-## 功能特性
+### 设计理念
 
-- **数字花园体验**：通过标签、系列、作者、书籍、Flow 和归档进行非线性导航。
-- **互联知识网络**：
-  - **双向链接**：支持 `[[Slug]]` 跨内容类型关联。
-  - **反向链接**：在笔记页自动显示“Linked References”。
-  - **知识图谱**：以可视化方式展示内容连接关系。
-- **全文搜索**：基于 Pagefind 的静态搜索，支持 Cmd/Ctrl+K 快捷键。
-- **结构化内容体系**：
-  - **Series**：支持手动或自动排序的多篇集合。
-  - **Books**：支持章节与分部的长篇阅读界面。
-  - **Notes**：原子化常青笔记。
-  - **Flows**：流式日记/微记录。
-- **富文本 MDX 能力**：
-  - GitHub Flavored Markdown（表格、任务列表等）
-  - 代码高亮
-  - Mermaid 图表
-  - KaTeX 数学公式
-  - 原生 HTML 支持
-- **阅读体验与设计**：
-  - 高可读排版与响应式布局
-  - 自动系统主题检测（明/暗）
-  - 四套配色主题：default、blue、rose、amber
-  - 吸顶目录与阅读进度跟踪
-- **作者生态**：每位作者有独立主页，包含简介、头像与社交链接。文章支持按作者筛选，并可在文末显示作者卡片。
-- **性能与 SEO**：
-  - 全静态导出与 WebP 优化
-  - 每种内容类型均有完整的 Open Graph 与 Twitter Card 元数据
-  - JSON-LD 结构化数据（`BlogPosting`、`Book`、`Article`），支持 Google 富媒体搜索结果
-  - RSS/Atom 订阅源，格式（`rss` | `atom` | `both`）与内容深度（`full` | `excerpt`）可配置
-  - `<head>` 自动注入 Feed 发现链接，原生 sitemap 生成
-  - 支持 Latin/CJK 的多语言阅读时长估算
-- **集成能力**：
-  - 统计：Umami / Plausible / Google Analytics
-  - 评论：Giscus / Disqus
-  - i18n：`site.config.ts` 中配置多语言（en / zh）
-
-## 设计理念
-
-- **默认优雅**：排版、间距、色彩开箱即用且有审美一致性。
-- **内容优先**：通过文件化写作与发布流程完成创作，不依赖重型 CMS。
-- **Markdown 优先但不受限**：保持可迁移写作体验，同时支持数学、图表、代码和双向链接。
+- **简洁优雅**：排版、间距、配色开箱即用，且遵循审美一致性。
+- **内容及文本优先**：通过文本文件化写作与发布流程完成创作，不依赖重型 CMS，内容存储于 Markdown/MDX 文本，结合 Git 进行版本管理，使作者拥有长期所有权并便于平台迁移。
+- **Markdown 优先**：默认支持 Markdown 及常用扩展语法，同时支持数学、图表、代码和双向链接。
 - **按需启用**：`site.config.ts` 提供模块化开关，仅启用你需要的能力。
-- **纯文本长期所有权**：内容存储于 Markdown/MDX，便于版本管理与长期迁移。
+
+延伸阅读：[《如何让 AI 写好代码》](https://hutusi.com/weeklies/25)（中文）
+
+## 功能特性
+
+- **数字花园理念:** 通过标签、系列、作者、书籍、Flow 和时间归档实现非线性导航。
+- **互联知识网络:**
+  - **Wiki 链接:** 支持在所有内容类型之间使用 `[[Slug]]` 建立双向关联。
+  - **反向链接:** 在笔记页面自动展示 “Linked References”。
+  - **知识图谱:** 以交互式可视化方式展示内容之间的连接关系。
+- **全文搜索:** 基于 Pagefind 的快速静态客户端全文搜索，支持 Cmd/Ctrl+K。
+- **结构化内容体系:**
+  - **Series:** 支持手动或自动排序的多篇内容组织方式。
+  - **Books:** 支持明确章节、分部以及专用阅读界面的长篇内容。
+  - **Notes:** 面向个人知识管理的原子化常青概念。
+  - **Flows:** 用于快速记录想法的流式日记或微博客。
+- **丰富的 MDX 内容能力:**
+  - GitHub Flavored Markdown（表格、任务列表、删除线）。
+  - 语法高亮代码块。
+  - Mermaid 图表（流程图、时序图等）。
+  - 通过 KaTeX 支持 LaTeX 数学公式。
+  - 支持原生 HTML 以实现自定义布局。
+- **优雅设计:**
+  - 极简审美与高对比度排版。
+  - 明暗主题，自动跟随系统设置。
+  - 四套配色方案: default（emerald）、blue、rose、amber。
+  - 针对阅读优化的响应式布局。
+  - 首页精选内容支持横向滚动。
+- **目录:** 吸顶目录支持滚动跟踪、阅读进度指示和当前标题高亮。
+- **灵活的内容结构:**
+  - 支持平铺文件（`post.mdx`）或嵌套文件夹（`post/index.mdx`）。
+  - 资源可与文章共置: 将图片保存在文章目录内（`./images/`）。
+  - 支持带日期前缀的文件名: `2026-01-01-my-post.mdx`。
+  - 支持文章、系列、书籍和 Flows 的草稿状态。
+- **作者生态:** 每位作者都有独立主页，包含简介、头像和社交链接。文章可按作者筛选，文末可选显示作者卡片。
+- **性能与 SEO:**
+  - 全静态导出，并生成优化后的 WebP 图片。
+  - 为所有内容类型生成 Open Graph 和 Twitter Card 元数据。
+  - 提供 JSON-LD 结构化数据（`BlogPosting`、`Book`、`Article`），支持 Google 富媒体结果。
+  - RSS/Atom 订阅源支持可配置的格式（`rss` | `atom` | `both`）和内容深度（`full` | `excerpt`）。
+  - 在 `<head>` 中自动注入 Feed 自动发现链接，并原生生成 sitemap。
+  - 多语言阅读时长估算，支持 Latin 和 CJK。
+- **集成能力:**
+  - 分析统计: Umami、Plausible 或 Google Analytics。
+  - 评论系统: Giscus（GitHub Discussions）或 Disqus。
+  - 国际化: 通过本地化的 `site.config.ts` 支持多语言（en、zh）。
+- **内容 CLI 工具:** 支持创建文章、系列，以及从 PDF 或图片文件夹导入内容。
+- **现代技术栈:** Next.js 16、React 19、Tailwind CSS v4、TypeScript 5、Bun。
 
 ## 快速开始
 
 ### 新建项目（推荐）
 
-一条命令创建新的 Amytis 站点：
+用一条命令创建新的 Amytis 站点:
 
 ```bash
 bun create amytis my-garden
@@ -76,30 +92,36 @@ cd my-garden
 bun dev
 ```
 
-该脚手架会下载最新发布版 Amytis，自动安装依赖，并根据你的项目信息更新 `site.config.ts` 和 `package.json`。
+脚手架命令会下载最新打标签发布的 Amytis 版本，安装依赖，并根据你的项目信息更新 `site.config.ts` 和 `package.json`。
 
-### 克隆运行
+### 克隆并运行
+
+1. **安装依赖:**
 
-1. **安装依赖**
    ```bash
    bun install
    ```
 
-2. **启动开发环境**
+2. **启动开发服务器:**
+
    ```bash
    bun dev
    ```
-   打开 [http://localhost:3000](http://localhost:3000)。
 
-   > **本地搜索说明：** Pagefind 索引是在执行 `bun run build:dev` 时生成的。本地测试 Cmd/Ctrl+K 前先运行一次；内容更新后也需要重新生成。
+   访问 [http://localhost:3000](http://localhost:3000)。
+
+   > **开发环境中的搜索:** Pagefind 索引会在执行 `bun run build:dev` 时生成。本地测试 Cmd/Ctrl+K 前请先运行一次；内容更新后也需要重新生成。
+
+3. **生产构建（静态导出）:**
 
-3. **生产构建（静态导出）**
    ```bash
    bun run build
    ```
-   产物位于 `out/` 目录。
 
-4. **开发构建（更快，无图片优化）**
+   静态站点会生成到 `out/` 目录，并包含优化后的图片资源。
+
+4. **开发构建（更快，无图片优化）:**
+
    ```bash
    bun run build:dev
    ```
@@ -117,7 +139,7 @@ bun run validate
 bun run build
 bun run build:dev
 bun run clean
-bun run deploy                 # 部署到 Linux/nginx 服务器（需要 .env.local 配置）
+bun run deploy                 # 部署到 Linux/nginx 服务器（需要 .env.local）
 
 ## Test
 bun test
@@ -144,81 +166,137 @@ bun run series-draft "series-slug"
 bun run add-series-redirects --dry-run
 ```
 
-### 导入聊天记录到 Flows
+### 将聊天记录导入为 Flows
 
-将 `.txt` 或 `.log` 文件放入 `imports/chats/` 后执行：
+将 `.txt` 或 `.log` 文件放入 `imports/chats/`，然后执行:
 
 ```bash
 bun run new-flow-from-chat
 ```
 
-常用参数：`--all`、`--dry-run`、`--author "Name"`、`--append`、`--timestamp`。  
-导入历史记录位于 `imports/chats/.imported`。
+常用参数: `--all`、`--dry-run`、`--author "Name"`、`--append`、`--timestamp`。  
+导入历史会记录在 `imports/chats/.imported` 中。
 
 ## 配置
 
-主要站点配置集中在 `site.config.ts`，`site.config.example.ts` 则是更完整的参考模板，适合查看可选项和默认写法。
+主要站点配置位于 `site.config.ts`。`site.config.example.ts` 是脚手架所使用的参考模板，查看新选项时很有用:
+
+```typescript
+export const siteConfig = {
+  // ...
+  nav: [
+    { name: "Home", url: "/", weight: 1 },
+    { name: "Flow", url: "/flows", weight: 1.1 }, // 在导航中添加 Flows
+    { name: "Series", url: "/series", weight: 1.5 },
+    { name: "Books", url: "/books", weight: 1.7 },
+    { name: "Archive", url: "/archive", weight: 2 },
+    // ...
+  ],
+  // ...
+  flows: {
+    recentCount: 5,
+  },
+};
+```
 
-优先关注这些配置区块：
+优先自定义这些高影响配置区块:
 
-- 站点信息：`title`、`description`、`baseUrl`、`ogImage`、`logo`
-- 导航与页脚：`nav`、`footer`、`subscribe`、`social`
-- 内容路由：`posts.basePath`、`posts.includeDateInUrl`、`series.autoPaths`、`series.customPaths`
-- 首页结构：`hero`、`homepage.sections`
-- 集成能力：`analytics`、`comments`、`feed`、`i18n`
+- 站点标识: `title`、`description`、`baseUrl`、`ogImage`、`logo`
+- 导航与页脚: `nav`、`footer`、`subscribe`、`social`
+- 内容行为: `posts.basePath`、`posts.includeDateInUrl`、`series.autoPaths`、`series.customPaths`
+- 首页组成: `hero`、`homepage.sections`
+- 集成能力: `analytics`、`comments`、`feed`、`i18n`
 
-如果你部署到 nginx，可直接从 `nginx.conf.example` 开始调整。
+如果是通过 nginx 进行静态托管，可以从 `nginx.conf.example` 开始配置。
 
 ## 静态导出路由规则
 
-Amytis 基于 Next.js 静态导出，核心约束是 `output: "export"` 和 `trailingSlash: true`。
+Amytis 基于 Next.js 静态导出构建，关键配置为 `output: "export"` 和 `trailingSlash: true`。
 
-- 在 `generateStaticParams()` 中返回原始路径片段，不要手动用 `encodeURIComponent`
-- 链接必须指向真实路径，例如 `/posts/中文测试文章`，不要写 `/posts/[slug]`
-- 文章默认路径是 `/<posts.basePath>/<slug>`，其中 `posts.basePath` 默认值为 `/posts`
-- 启用 `series.autoPaths` 后，系列文章会切换到 `/<series-slug>/<post-slug>`
-- 配置了 `series.customPaths` 时，会优先使用自定义前缀覆盖 `autoPaths`
-- 如果准备把系列文章从默认 `/posts/...` 路径迁走，先执行 `bun run add-series-redirects --dry-run`，确认后再执行 `bun run add-series-redirects`
+- 在 `generateStaticParams()` 中返回原始 segment 值，不要预先用 `encodeURIComponent` 编码。
+- 链接应指向真实 URL，例如 `/posts/中文测试文章`，而不是 `/posts/[slug]` 这样的路由占位符。
+- 文章默认路径为 `/<posts.basePath>/<slug>`，其中 `posts.basePath` 默认值为 `/posts`。
+- 启用 `series.autoPaths` 后，系列文章会移动到 `/<series-slug>/<post-slug>`。
+- 如果配置了 `series.customPaths`，则会以这些自定义前缀覆盖 `autoPaths`。
+- 在把系列文章从默认的 posts 路径迁走之前，先运行 `bun run add-series-redirects --dry-run`，再执行 `bun run add-series-redirects`，以确保旧链接仍然可访问。
 
 ## 内容写作
 
-- **Posts**：写入 `content/posts/`，支持单文件、日期前缀和文件夹模式。文件夹模式可将图片放在同目录的 `images/` 中。CLI：`bun run new "Post Title"` 或 `bun run new "Post Title" --folder`
-- **Flows**：写入 `content/flows/YYYY/MM/DD.md` 或 `.mdx`。CLI：`bun run new-flow`
-- **Series**：创建 `content/series/<slug>/index.mdx`，系列内文章可作为同级文件或子目录。CLI：`bun run new-series "Series Name"`
-- **Books**：写入 `content/books/<slug>/`，通常用 `index.mdx` 存元数据，其余章节文件与其并列
-- **Notes**：写入 `content/notes/`，支持 `[[wiki-links]]`。CLI：`bun run new-note "Concept"`
-- **Unicode slug**：文章和笔记支持有意使用 Unicode slug，修改动态路由时要一起验证 ASCII 和 Unicode 路径
+### Posts
+
+在 `content/posts/` 中创建 `.md` 或 `.mdx` 文件。
+
+- 平铺文件: `content/posts/my-post.mdx`
+- 日期前缀文件: `content/posts/2026-01-01-my-post.mdx`
+- 带共置资源的文件夹文章: `content/posts/my-post/index.mdx`，并配合 `content/posts/my-post/images/*`
+- CLI: `bun run new "Post Title"` 或 `bun run new "Post Title" --folder`
+
+### Flows
+
+在 `content/flows/YYYY/MM/DD.md` 或 `.mdx` 中创建日记内容。
+
+- CLI: `bun run new-flow` 会创建今天的记录
+- 聊天导入: 将导出文件放入 `imports/chats/`，然后运行 `bun run new-flow-from-chat`
+
+### Series
+
+在 `content/series/<slug>/` 下创建目录和 `index.mdx`，然后将系列文章作为同级文件或文件夹加入其中。
+
+- CLI: `bun run new-series "Series Name"`
+- 也可以直接将文章创建到已有系列中: `bun run new "Post Title" --series <series-slug>`
+
+### Books
+
+书籍是位于 `content/books/<slug>/` 下的长篇结构化内容。
+
+- 使用 `index.mdx` 保存书籍元数据
+- 在同目录添加章节文件，例如 `introduction.mdx` 或 `setup.mdx`
+- 与书籍相关的工作流可使用 `bun run import-book` 和 `bun run sync-book`
+
+### Notes
+
+在 `content/notes/` 中创建常青笔记（例如 `concept.mdx`），并使用 `[[wiki-links]]` 将它们连接起来。
+
+- CLI: `bun run new-note "Concept"`
+- 在需要时，Notes 和 Posts 都支持有意使用 Unicode slug
 
 ## 项目结构
 
 ```text
 amytis/
   content/
-    posts/
-    series/
-    books/
-    notes/
-    flows/
-  docs/
-  imports/
-  public/
-  scripts/
+    posts/              # 博客文章
+    series/             # 系列集合
+    books/              # 长篇书籍
+    notes/              # 数字花园笔记
+    flows/              # 日记内容（YYYY/MM/DD）
+    about.mdx           # 静态页面
+  docs/                 # 架构、部署、排障文档
+  imports/              # 仅本地使用的导入源文件
+  public/               # 静态资源
+  scripts/              # Bun 编写/构建/导入工具
   src/
-    app/
-    components/
+    app/                # Next.js App Router 页面
+      books/            # 书籍路由
+      notes/            # 笔记路由
+      graph/            # 知识图谱
+      flows/            # Flow 路由
+    components/         # React 组件
     lib/
-  tests/
+      markdown.ts       # 数据访问层
+  tests/                # 单元、集成、e2e、工具测试
   packages/
-    create-amytis/
-  site.config.ts
+    create-amytis/      # `bun create amytis` 脚手架 CLI
+  site.config.ts        # 站点配置
 ```
 
 ## 文档
 
-- [架构说明](docs/ARCHITECTURE.md)
+- [架构总览](docs/ARCHITECTURE.md)
 - [部署指南](docs/deployment.md)
 - [数字花园指南](docs/DIGITAL_GARDEN.md)
 - [贡献指南](docs/CONTRIBUTING.md)
+- [故障排查](docs/TROUBLESHOOTING.md)
 
 ## 许可证
 

package/content/books/notes-on-thinking/cost-of-certainty.mdx

@@ -0,0 +1,9 @@
+---
+title: "The Cost of Certainty"
+---
+
+Certainty feels good. It reduces anxiety and speeds up decisions. But it comes at a cost: when you are certain, you stop looking for disconfirming evidence.
+
+Most mistakes in reasoning come not from ignorance but from misplaced confidence. The antidote is not permanent doubt — that is paralyzing — but calibrated uncertainty. Ask: how confident am I, and what would change my mind?
+
+Holding beliefs loosely is not weakness. It is the posture of someone who cares more about being right than about being consistent.

package/content/books/notes-on-thinking/index.mdx

@@ -0,0 +1,16 @@
+---
+title: "Notes on Thinking"
+excerpt: "A collection of short essays on mental models, decision-making, and the habits that sharpen how we reason about hard problems."
+date: "2026-03-01"
+coverImage: "text:NT"
+featured: true
+draft: false
+authors: ["Amytis"]
+chapters:
+  - title: "Mental Models Are Maps"
+    id: "mental-models"
+  - title: "The Cost of Certainty"
+    id: "cost-of-certainty"
+---
+
+**Notes on Thinking** is a short collection of essays on how to reason more clearly. Each chapter is self-contained and can be read in any order.

package/content/books/notes-on-thinking/mental-models.mdx

@@ -0,0 +1,9 @@
+---
+title: "Mental Models Are Maps"
+---
+
+A mental model is a simplified representation of how something works. Like a map, it is useful precisely because it leaves things out. A map that showed every detail would be as large and complex as the territory itself — useless for navigation.
+
+The best mental models are wrong in the right ways. They omit the details that don't matter for the decision at hand, while preserving the structure that does.
+
+Collecting mental models from many fields — physics, economics, biology, psychology — gives you a richer toolkit for making sense of new situations.

package/content/books/the-pragmatic-writer/finding-your-voice.mdx

@@ -0,0 +1,9 @@
+---
+title: "Finding Your Voice"
+---
+
+Voice is not something you invent — it is something you stop suppressing. Most people who feel they lack a writing voice are simply trying too hard to sound like someone else.
+
+The quickest path to your own voice is to write the way you explain things to a friend: directly, without jargon, without hedging every sentence. Read it back. Does it sound like you? If not, cut the parts that don't.
+
+Over time, patterns emerge. Certain words recur. Certain sentence structures feel natural. That accumulation is your voice.

package/content/books/the-pragmatic-writer/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "The Pragmatic Writer"
+excerpt: "A practical guide to writing clearly, consistently, and with purpose — for developers, makers, and anyone who thinks in public."
+date: "2026-02-01"
+coverImage: "text:PW"
+featured: true
+draft: false
+authors: ["Amytis"]
+chapters:
+  - title: "Why Writing Matters"
+    id: "why-writing-matters"
+  - title: "Finding Your Voice"
+    id: "finding-your-voice"
+  - title: "The Editing Loop"
+    id: "the-editing-loop"
+---
+
+**The Pragmatic Writer** is a short, opinionated guide to writing as a craft and a habit. It is aimed at people who write to think, share, and build — not to become novelists, but to communicate better.

package/content/books/the-pragmatic-writer/the-editing-loop.mdx

@@ -0,0 +1,9 @@
+---
+title: "The Editing Loop"
+---
+
+First drafts are for getting ideas out. Editing is where writing actually happens.
+
+A simple loop that works: write a rough draft without stopping, then read it aloud. Your ear will catch what your eye misses — the sentence that trails off, the paragraph that repeats itself, the word that almost means what you intended.
+
+Cut ruthlessly. If a sentence does not add information or move the reader forward, remove it. Good writing is not about saying everything; it is about saying the right things.

package/content/books/the-pragmatic-writer/why-writing-matters.mdx

@@ -0,0 +1,9 @@
+---
+title: "Why Writing Matters"
+---
+
+Writing is thinking made visible. When you write, you are forced to clarify vague ideas, spot contradictions, and fill gaps you didn't know existed.
+
+For developers and makers, writing is also a multiplier. A well-written README, a clear design document, or a concise post about something you learned can save hours for your future self and for everyone else who encounters your work.
+
+The goal of this book is not to make you a better stylist. It is to make writing feel less like a chore and more like a useful tool you reach for naturally.

package/content/flows/2026/03/01.md

@@ -0,0 +1,9 @@
+---
+tags: ["react", "performance"]
+---
+
+Spent the afternoon profiling a React app with too many unnecessary re-renders. The culprit was a context provider wrapping the entire tree that updated on every keystroke.
+
+The fix was straightforward — split the context into a read context and a dispatch context. Components that only consume state no longer re-render when actions are dispatched. Dropped re-render count from ~80 to ~12 per interaction.
+
+Worth revisiting `useMemo` and `useCallback` placement as well. They are often added too eagerly before profiling, and sometimes removed too eagerly after.

package/content/flows/2026/03/03.md

@@ -0,0 +1,9 @@
+---
+tags: ["writing", "note-taking"]
+---
+
+Tried a new approach to note-taking today: writing a one-paragraph summary immediately after reading something, without looking back at the source.
+
+If you can't summarize it from memory, you haven't understood it yet. The constraint forces you to identify the actual core idea rather than collecting sentences that sound important.
+
+Been doing this for a week. The notes are shorter, less polished, and far more useful.

package/content/flows/2026/03/05.md

@@ -0,0 +1,9 @@
+---
+tags: ["typescript", "tooling"]
+---
+
+Finally moved a mid-sized project from JSDoc type comments to proper TypeScript. The migration took about half a day — less than expected.
+
+The biggest win is not autocompletion or error catching (though those matter). It is that the types act as documentation that stays in sync with the code. Prose comments lie; types don't compile if they do.
+
+One friction point: `strict: true` surfaces a lot of implicit `any` that was quietly hiding real assumptions. Fixing each one forced me to think about what the code actually expected — which is the point.

package/content/flows/2026/03/07.md

@@ -0,0 +1,9 @@
+---
+tags: ["ai", "workflow"]
+---
+
+Been using Claude Code for a week now as a daily coding assistant. A few observations so far.
+
+It is most useful for tasks where the shape of the solution is clear but the execution is tedious — refactoring, writing tests, tracking down why a CSS rule isn't applying. For genuinely novel design problems, talking through the approach matters more than generating code.
+
+The most important habit: read every diff before accepting it. Not because the code is wrong (it usually isn't), but because understanding what changed keeps you in the loop on your own codebase.

package/content/posts/welcome-to-amytis.mdx

@@ -5,12 +5,15 @@ excerpt: "The first seeds of our digital garden."
 category: "General"
 tags: ["introduction", "digital garden", "nextjs"]
 author: "Amytis Team"
+coverImage: "images/vibrant-waves.jpg"
 ---
 
 # Welcome to Amytis
 
 This is your new digital garden. Built with **Next.js**, **Tailwind CSS**, and **Bun**.
 
+![](images/vibrant-waves.jpg)
+
 ## Why Amytis?
 
 Amytis of Media was the wife of Nebuchadnezzar II, for whom the Hanging Gardens of Babylon were reportedly built. This digital garden is a space for thoughts to grow and flourish.

package/content/series/markdown-showcase/index.mdx

@@ -5,7 +5,8 @@ date: "2026-02-13"
 coverImage: "/images/lake.jpg"
 featured: true
 sort: "manual"
-posts: ["visuals-and-diagrams", "mathematical-notation", "syntax-highlighting"]
+redirectFrom:
+  - /series/markdown-showcase-old
 ---
 
 Amytis supports a wide range of MDX features. This series serves as both a reference and a demonstration.

package/content/series/markdown-showcase/mathematical-notation.mdx

@@ -1,9 +1,13 @@
 ---
-title: "Mathematical Notation"
-date: "2026-02-14"
-category: "Science"
-tags: ["math", "latex"]
+title: Mathematical Notation
+date: '2026-02-14'
+category: Science
+tags:
+  - math
+  - latex
 latex: true
+redirectFrom:
+  - /posts/mathematical-notation-demo
 ---
 
 Amytis uses `rehype-katex` to render beautiful mathematical formulas.