MOSSPersonal Context Hub

Project

MOSS

MOSS

Personal Context Hub Local-first 个人内容、兴趣与上下文工作台

MOSS 的长期目标是把个人关心的内容、订阅、日程、图片、资产和反馈汇聚为可查询、可理解、可逐步自动化的个人上下文系统。

当前交付的是 MOSS v2 的本地可运行子集：把分类 X Bookmarks Markdown 导入通用内容模型，记录 Feedback，使用五条本地规则生成可追溯信号，并通过 Today、Knowledge、Governance、Calibration 四个页面形成闭环。

当前能力

data/phase-1a-input/*.md
  → content_items + import_runs
  → Calibration + Feedback
  → signal_runs + signals
  → Today / Knowledge / Governance
  → audit_events
  • 通用 content_items 模型，以 (source, source_id) 保证来源内幂等。
  • 旧 bookmarks 数据库自动、事务化迁移到 schema v2。
  • X 日期严格解析；非法日期会使迁移整体回滚。
  • 导入、Feedback、信号发布与 Audit Event 同事务提交。
  • 五条本地声明式规则、输入自动失效、强制刷新和最后稳定批次回退。
  • /today、/knowledge、/governance、/calibration 四个共享工作台路由。
  • 桌面三栏、平板 Inspector Sheet、移动端导航，以及浅色/深色主题。

尚未实现：

  • X.com 在线采集、RSS 等第二个真实连接器。
  • 云端模型、摘要、向量数据库、语义搜索或统一 Ask。
  • Action、Context、Self、Asset 的真实业务模块。
  • 多用户、账号系统、公网访问或外部写操作。

快速启动

要求 Node.js 20 LTS 或更高版本、npm。当前验收使用 Node.js v24.14.0。

npm ci
npm run import:content
npm run dev

打开 http://127.0.0.1:3000。标准开发和生产命令只监听 loopback；当前 API 没有认证，不要通过公网网卡、反向代理或隧道暴露。

旧命令 npm run import:bookmarks 仍作为兼容别名保留。

验证代码：

npm test
npm run verify:v2
npm run build

静态资料站

原型、架构图和技术文档可以构建为不含运行数据的静态资料站：

npm run site:build
npm run site:check
npm run site:preview

构建产物位于 dist/moss/。npm run site:sync 会把这份产物复制到同级 alivps/www/moss/，由 alivps 仓库的独立 GitHub Actions 工作流发布到 imshengli.com/moss。

静态站使用明确白名单，只发布 docs/、prototypes/、Design System 和品牌资源。它不会复制 data/phase-1a-input/、SQLite、环境文件或本地运行日志；原始文件不会被移动或改写。

数据与隐私

  • 默认数据库为 data/moss.sqlite，运行时文件已被 Git 忽略。
  • 可用 MOSS_DATABASE_PATH=/absolute/path/to/copy.sqlite 在隔离副本上测试。
  • Feedback、信号和审计只保存在本机 SQLite；当前不会上传到云端模型。
  • 原始 Markdown 不会在导入时修改。
  • data/phase-1a-input/*.md 是仓库跟踪文件，包含正文、作者和链接；推送或复制前应确认可见范围。
  • SQLite 使用 WAL。运行中备份应使用 SQLite .backup，不要只复制主文件。

完整启动、迁移、备份和恢复步骤见本地工作台运行手册。

主要命令

命令 作用
npm run import:content 解析 Markdown，并事务化 upsert 内容、Import Run 和 Audit Event。
npm run import:bookmarks import:content 的兼容别名。
npm run dev 在 127.0.0.1 启动开发服务器。
npm test 执行解析、迁移、事务、API、缓存、规则阈值和恢复测试。
npm run verify:v2 在临时数据库上执行 996 条迁移、索引和性能验收。
npm run build 生成生产构建并检查 TypeScript 与路由。
npm run site:build 从白名单源文件生成 /moss/ 静态资料站。
npm run site:check 检查静态站死链、文件数量和敏感内容。
npm run site:sync 把构建产物复制到同级 alivps/www/moss/。
npm run start 在 127.0.0.1 启动已构建的生产服务。

项目结构

data/phase-1a-input/  受控的 X Bookmarks Markdown 输入
data/moss.sqlite      本地 SQLite v2 数据库（运行时生成，不提交）
scripts/              通用导入入口与兼容脚本
src/app/              四个页面、共享布局与本地 API
src/components/       工作台、Inspector 和交互组件
src/lib/parsers/      来源解析与严格日期协议
src/lib/rules/        五条规则及 append-and-publish 引擎
src/lib/db.ts         schema、迁移、事务与查询
docs/moss/            产品、架构、实施与验收文档
tests/                单元、集成与 Route Handler 测试

文档入口

开发约束

  • 原始 Markdown 是 source of truth；画像、信号和评分均为可重算加工数据。
  • Feedback 保持独立事件流，不改写原始内容。
  • 规则变更必须提升集中维护的 signalRuleVersion。
  • Audit Event 当前由应用保证只追加，不宣称数据库层绝对不可变。
  • X 后续接入只允许读取用户已授权的数据；不执行点赞、转发、关注、发消息或修改书签等写操作。