SelfLore 是一个个人卡片笔记应用，用来收纳外部资料、整理事实知识、记录自己的观点，并用备忘和清单安排待办与待学内容。
未登录时可浏览独立的只读演示空间，内容与统计均为示例；登录后管理自己的真实数据。
| 入口 | 用途 |
|---|---|
| 卡片 | 统一收纳资料、事实知识和原子观点，支持搜索、分类、标签及关联引用 |
| 备忘 | 随手记、待办与待学清单；条目可标记完成并关联卡片 |
| 合集 | 将不同类型卡片编排在一起，集中浏览与翻阅 |
| 我的 | 个人资料、内容积累与学习足迹 |
- 资料卡：保存外部摘录或图片，粘贴普通网页或X链接后尝试补全来源；原材料与自己的说明分开，收录不代表认同。
- 事实知识：用问答或填空组织知识，支持 FSRS 间隔复习。
- 原子观点：记录自己的想法，通过稳定编号和双向链接连接其他卡片。
- 备忘：记录行动和学习安排；资料卡、观点及备忘均不进入知识复习。
截图来自当前开发版本的只读演示空间，内容均为合成示例，线上版本可能暂未包含最新改动。截图来源与更新说明。
桌面：统一卡片库
手机：备忘与待学清单
| 部分 | 实现 |
|---|---|
| 前端 | React、TypeScript、Vite、React Router、TanStack Query；pnpm 锁定依赖 |
| 后端 | Python 3.13+、FastAPI、psycopg；uv 锁定依赖 |
| 数据 | PostgreSQL 18、不可变 SQL 增量迁移；图片保存到独立私有文件目录 |
| 验证 | GitHub Actions基础CI：文档、前端和后端；pytest、Vitest、Playwright、Oxlint；前端展示变更另需浏览器视觉审查 |
需要 Python 3.13+、uv、Node.js 22.12+、pnpm 10.33.0 和 PostgreSQL 18。以下为 Windows PowerShell 的固定启动方式，在仓库根目录执行：
-
按数据库初始化准备
dev数据库、角色及完整迁移链。固定启动入口使用127.0.0.1:6171；通用文档中的5432示例应替换为6171。 -
配置应用角色密码并启动：
.\start-local.cmd -Configure .\start-local.cmd
-
打开 http://127.0.0.1:24566，按
Ctrl+C停止。
启动脚本会同步锁定依赖、构建前端并由 API 提供页面；不会安装 PostgreSQL 或自动迁移数据库。图片上传还需按图片存储说明初始化媒体目录。详细配置与排障见本地启动说明。
需要前端热更新时，按 API 配置与运行启动后端，再在 apps/web 执行 pnpm install --frozen-lockfile、pnpm dev，访问 http://127.0.0.1:24567。其他环境可参考通用数据库与 API 配置说明；一键脚本依赖 Windows。
apps/
web/ React 前端：src/features、components、lib；e2e 浏览器测试
api/ FastAPI 后端：app、migrations、tests
scripts/ 本地启动、备份、媒体诊断及CI辅助脚本
assets/screenshots/ README使用的公开演示截图及来源说明
handbook/ 公开操作手册：启动、维护、备份、媒体与资料收录
openspec/
specs/ 当前能力规格
changes/ 活跃变更与 archive 历史记录
后端业务主要位于 app/routers、schemas、services，数据库访问辅助函数位于 repositories。前后端分别在各自目录管理依赖。
本机的 docs/、deploy/、local-deployment/、备份及缓存被 Git 忽略，不随仓库交付；具体服务器接入和自动发布工具属于维护者本机资料。克隆后运行应用可使用下列公开说明。
产品功能与技术概览统一维护在本页；专项操作手册集中在 handbook/，应用开发说明保留在各自目录，历史验收保留在 OpenSpec 变更记录中。根目录的 CONTRIBUTING.md 和 AGENTS.md 分别说明贡献流程与代理工作约定。
| 需要了解 | 文档 |
|---|---|
| 本地启动与诊断 | Windows 本地启动 |
| 数据库首次准备与后续迁移 | 数据库初始化 · 迁移说明 |
| 认证配置、首位管理员及手动运行 | 认证配置 |
| 接口与数据交互 | 工作区 API |
| 仓库CI、测试与前端视觉审查 | 自动CI · 本地验证 |
| 图片上传、存储及排查 | 媒体存储 |
| 资料链接补全、失败回退及平台扩展 | 资料快速收录 |
| 从文件或粘贴 JSON 创建卡片 | JSON 导入 |
| 开发库备份与恢复演练 | 备份与隔离恢复 |
| 日常维护与排障 | 项目维护卡 |
问题反馈和功能建议请使用GitHub Issues。准备修改代码或文档时，先阅读贡献指南，其中说明了开发入口、验证要求及PR流程。
SelfLore采用Apache License 2.0。第三方依赖和引用材料适用各自许可；用户自行保存的笔记、图片及来源材料不因使用本项目而自动获得此许可。
在“我的”页面按JSON规范与AI提示词生成内容，选择JSON／ZIP预检并确认批量导入；导出包含全类型及归档、回收站。图片使用ZIP携带原图。导入仅新建，不覆盖既有卡片；同批次重试不重复创建。内容包不含合集、账号资料和复习历史，不能替代数据库媒体联合备份。启用前按迁移说明应用0009迁移。