TrustedKnowledge：一个把知识、Todo、博客和 AI 串起来的个人工作台

TrustedKnowledge 不是单一的笔记工具，而是一个围绕“可信知识沉淀”和“AI 辅助生产”搭建的个人平台。它把日常学习、工作记录、待办事项、英语素材、AI 加工结果和博客发布流程统一放进 Oracle 数据库，再通过 Web 工作台完成录入、检索、加工、发布和复盘。

01 | 它解决的核心问题

这个项目的核心目标很明确：让知识不要散落在聊天记录、文档、待办和博客草稿里，而是形成一条可追踪的生产链路。

在可信知识模块里，可以录入问题、答案、来源、标签和发布状态，形成结构化知识库。知识加工模块会选择未发布知识和 Skill 指令，调用 Codex 生成可发布内容。博客工厂继续保存加工任务、编辑 Markdown 文章，并通过 MetaWeblog API 发布到博客平台。

Todo 模块也不是孤立存在的。知识可以转为 Todo，Todo 也可以转回知识；完成 Todo 后，还能追加到当前学习记录中。这样，任务、学习进度、历史沉淀和内容发布之间形成了闭环。

项目还包含英语素材管理、AI 问数、AI 编程、用户权限管理和 AI 用量查看。它更像一个面向个人长期积累的工作台，而不是一次性内容生成器。

02 | 技术架构如何分层

前端层使用 React 19、TypeScript、Vite 6、Tailwind CSS 和 lucide-react。页面没有使用 React Router，而是通过 activeView 控制当前工作区。主题、筛选、分页、草稿和侧边栏状态会保存在浏览器本地存储中，移动端通过顶部按钮展开导航，保证核心入口可达。

后端层使用 FastAPI 和 Pydantic。Router 负责接口，Schema 负责输入输出结构，Repository 负责 SQL 查询、表结构初始化和状态转换。认证上下文 AuthContext 会贯穿请求过程，携带用户 ID、管理员标记和可见用户范围。

数据层以 Oracle Database 为核心，保存知识、Todo、博客任务、用户、历史记录、英语素材和用量视图。长文本使用 Oracle CLOB，例如知识答案、文章 Markdown 和任务正文。后端通过 python-oracledb 异步连接池访问数据库。

工具层包括 Shell 脚本、Conda、npm、Uvicorn、Git、CHANGELOG.md 和前端概览文档。服务启动、状态检查和停止由 scripts/start-all.sh、scripts/status.sh、scripts/stop-all.sh 管理。

03 | 一次请求背后的运行流程

用户启动服务后，脚本分别拉起后端和前端，并把 PID 写入 .run/，日志写入 logs/。后端进入 FastAPI 生命周期后，会初始化 Oracle 异步连接池，并补齐用户表、会话表、关系表等结构。

前端由 Vite 提供页面，浏览器加载 frontend/src/main.tsx 后先恢复主题，再挂载 React App。用户登录时，前端请求 /api/auth/login。登录成功后，前端保存 API Key 和用户信息，后续请求统一携带 X-API-Key。

业务请求进入 FastAPI Router 后，通过依赖注入拿到 AuthContext，再调用 Repository。Repository 使用绑定变量访问 Oracle，并根据用户可见范围追加权限条件。返回数据再由 Pydantic 序列化为 JSON，前端更新 React state，页面重新渲染列表、表单、弹窗或 Dashboard。

对于 Codex、博客发布、GitHub 同步等外部动作，后端会额外调用子进程、XML-RPC 或脚本，并把结果回写数据库或返回前端。

04 | 设计亮点与当前短板

这个项目比较稳的地方，是前后端边界清晰，后端 Router、Schema、Repository 分层明确。权限设计也比较完整，普通用户、家长用户、超级管理员都有不同的数据可见范围。

SQL 安全性上，查询条件使用绑定变量，排序字段使用白名单映射。AI 问数也没有让模型直接生成任意 SQL，而是先由后端提取确定性条件，再基于受控查询结果让 LLM 总结。

但它也有明显的成长空间。frontend/src/App.tsx 过大，导航、状态、数据加载、弹窗和业务逻辑集中在一个文件中，后续维护风险较高。多个前端 API 文件重复处理请求头、错误解析和缓存逻辑。后端 Repository 也存在 count、分页、筛选、权限拼接等重复模式。

另外，运行时 DDL 虽然方便迭代部署，但长期会让数据库结构演进不够可追踪。搜索大量依赖 like '%关键词%' 和 CLOB 截取，对大表会有性能隐患。Codex job 状态保存在内存中，后端重启后会丢失，也不适合长任务和多实例部署。

05 | 后续最值得优先做什么

短期可以先做低风险拆分：把 App.tsx 中的格式化函数、本地存储读写、Codex 输出清洗和博客发布辅助函数移动到 frontend/src/utils/。再把页面大小、导航配置、状态枚举等展示配置抽到统一文件，降低主组件复杂度。

API 层可以新增统一 client，集中封装认证请求、错误解析、查询参数和缓存读写。写操作完成后，再按接口前缀清理缓存，减少页面短时间显示旧数据的问题。

长期看，前端可以引入路由层，把 overview、todos、history 等视图映射为 URL。后端可以增加 Service 层，把知识转 Todo、博客发布状态同步、AI 问数编排等业务流程从 API 和 Repository 中抽离。

数据库迁移也值得版本化管理，把散落在 Repository 中的 DDL 逐步迁移到统一 SQL 迁移流程。搜索能力可以从 Oracle Text 起步。Codex、博客发布、GitHub 同步这类任务，也更适合迁移到独立 worker 或队列中执行。

TrustedKnowledge 的价值不在于某一个单点功能，而在于它把“记录、加工、行动、发布、复盘”放进了同一条链路。对个人知识系统来说，这种闭环比单纯多一个页面或多一个 AI 按钮更重要。

关注我，和AI一起成长~