# FolioKit

我给自己的项目做了一个入口：可以直接读，也可以边问边看

Source: https://works.im0o.top/projects/foliokit/
Date: 2025-04-15
End date: present
Tags: 作品集, AI 问答, Astro, TypeScript, 全栈开发

## Project links

- [源代码](https://github.com/jz0ojiang/foliokit)


博客写了不少，项目介绍却散在文章和仓库里。发到简历里要放一串链接，别人点进去，也得自己找重点。用过一些链接聚合页之后，还是觉得不够，于是索性写了个自己的：FolioKit。

第一版只有一个 hello 动画和搜索框，下面接项目卡片。我喜欢暗色和比较空的页面，详情页后来也从卡片样式改成扁平排版。项目多起来之后，我更在意访问者能不能顺着一个问题，把相关项目和文章一起看下去。

## 边问边看

现在打开首页，可以直接浏览项目，也可以从输入框开始。问“最近在做什么”，助手可以找到近期项目；继续问某个设计，就打开对应正文。对话留在左边，正在读的内容放在右边，项目和博客都可以在这里继续读。

我不希望每次回答都把项目介绍复述一遍。适合直接看的内容就打开页面，适合比较的内容再组织成回答。推荐项目时，卡片使用项目自己的封面和地址；需要串起几篇介绍时，可以生成导览，在右侧页面里逐段讲解。

阅读栏也有自己的前进、后退和放大。比如从 Agentlog 点到相关项目，再回到 Agentlog，应该回到刚才读的位置，而不是重新打开页首。对话过程中换文档，不需要把正在输入的问题清掉。

![当前双栏阅读布局的脚本演示：左侧对话，右侧阅读项目](https://image.im0o.top/2026/20261117104150188.webp "当前双栏阅读布局的脚本演示：左侧对话，右侧阅读项目")

## 内容量不大，后来就不做向量检索了

最初的版本用 Nuxt 3 和 Nuxt Content 展示 Markdown，另外写了 Flask API，用 LlamaIndex 建本地向量索引。模型、缓存和服务地址放在配置里，Redis 是可选项。这一版也做了中英双语、流式回答和自动部署。

实际用下来，作品集就这些内容，为它维护独立后端和向量检索有些重。LlamaIndex 在 serverless 环境的冷启动也不理想。重写时，我换成 Astro 和纯 CSS，把问答 API 放回同一个项目，让模型通过工具搜索目录、读取正文和补充资料。

文章仍然是我自己维护的 Markdown。首页、项目详情、搜索、问答和纯文本导出都从这些文件取内容，中英文共用稳定的项目 ID。更新一个项目时，改的是同一份资料。

![FolioKit 的早期 Nuxt 版本](https://image.im0o.top/2026/20261117104147719.webp)

那时的重点还是搜索框和项目卡片，后来才逐渐发展成现在的对话与阅读布局。

## 回答里有页面，也有操作

引入问答以后，很多工作反而落在页面状态上。回答还没结束时追加的问题要留在队列里；停止一轮生成后，输入和已读页面要保留；复制回答时，要得到能继续使用的 Markdown，而不是一串按钮文字和活动提示。

博客接入也分成两部分：搜索与读取工具负责找文章，阅读栏负责展示文章。助手需要知道读者正在看哪一篇，所以侧栏会提供当前页面身份；引用则保留博客的公开链接，方便离开作品集后继续阅读。

连续读几篇长文章后，上下文也会变大。我把对话历史、已经读过的内容和当前页面分开管理，避免反复塞进同一篇正文；需要继续展开时再增加可用上下文。这样，访问者可以围绕一个项目追问，不必每次重新交代前面看过什么。

2026 年 11 月整理到 v3.2.0 后，个人内容单独放在 `personal` 分支，通用功能继续在开发分支维护。现在你看到的这个站，就是 FolioKit 的个人实例。

[最初的开发记录](https://blog.im0o.top/posts/aec1261f)

