dsh-personal

https://github.com/ChengqianHuang/dsh-personal · topic: dsh-plugin

个人助理 bundle：让 dsh 用自然语言记录/查询/回顾你的个人数据（经历——电影/书/专辑/展览等任意类别、项目日志、任务、博客、网站、想法、每日记录），全部落在一个 SQLite 文件（~/.dsh/personal/personal.db）里。LLM 只负责理解和总结，事实全部来自 SQLite，重启后依旧可查。

安装与使用见 dsh 用户文档 docs/user/develop/basic/publish.md。设计决策见 DESIGN.md。

安装（dsh 源码运行模式下）

本仓库 clone（或 link）到任意位置后，在 dsh 仓库根目录安装进 profile：

# 从本仓库的本地 clone 安装（link 模式，源码即生效）
pnpm dsh plugin --profile web add /path/to/dsh-personal
pnpm dsh --profile web --dump-config               # 验证出现 "# == dsh-personal" 层
pnpm dsh web                                       # 启动后直接对话

卸载：pnpm dsh plugin --profile web remove dsh-personal。

配置（可选，写进 profile 的 cordis.patch.yml 或由 bundle 默认值兜底）：

- id: personal
  name: dsh-personal
  config:
    timezone: Asia/Shanghai     # 日期分桶时区，默认进程时区
    # databasePath: ~/.dsh/personal/personal.db
    # enableDailyReview: true
    # enableWeeklyReview: true

构建 / 测试

(cd dsh-personal && pnpm install --ignore-workspace --config.auto-install-peers=false)
(cd dsh-personal && pnpm exec tsdown)                    # 产出 lib/index.mjs
pnpm exec vitest run --config dsh-personal/vitest.config.ts
pnpm exec tsc -p dsh-personal/tsconfig.json --noEmit

修改源码后重新 pnpm exec tsdown 即可（profile 里是 link，指向本目录）。 类型检查读取 DSH 各依赖包的声明文件；首次运行前需先构建上层 DSH 仓库。

当前数据库 schema 版本为 4。旧 v1–v3 数据库无法直接打开；如不需要旧数据，移走或删除旧 personal.db 后再启动。插件不会自动删除数据库文件。

工具（22 个）

• 记录：record_experience（类别可新增，如 movie/book/album/exhibition）create_project record_project_log create_task update_task complete_task create_blog_post update_blog_post create_idea record_daily_log register_website
• 查询：query_experiences query_tasks query_project_logs query_blog_posts query_websites search_personal_data
• 纠错：get_personal_record update_personal_record delete_personal_record
• 回顾：generate_daily_review generate_weekly_review

用法示例：直接说「今天看了《灵媒》，7.5 分」「读了半本《失控》」「Forge 今天定位了中文错位问题」「周末检查博客证书」「我有哪些事情没做？」「本周回顾」。

关键词检索

search_personal_data 使用 Jieba 中文分词和 SQLite FTS5，跨八类记录按 BM25 相关性统一排序。标题、名称、域名默认比备注和正文权重更高；标签也参与检索。比如「博客证书」可以找到「检查博客的 HTTPS 证书」，「streaming 中文错位」可以组合中英文关键词。

• text：主题关键词。模型从问题中提取关键词，把时间和类型分别填进日期窗口与 types。
• match：默认 all，要求全部关键词；any 返回至少命中一个词的记录。
• types、from、to、period：按记录类型与日期过滤；项目、网站也使用创建日期过滤。
• limit：跨类型的总条数，默认 20，上限 200。返回 { terms, hits }，每条 hit 包含 type、score 和完整 row，保持相关性顺序；分数只在本次查询内可比。同分时按日期倒序、类型、id 排列。
• query_experiences 的 text 和 match 使用同一检索引擎，还能组合类别、动作、日期和标签。不带 text 时仍按日期列出经历。

搜索索引只存在于连接的内存 TEMP 表中，不改变 v4 数据库格式。首次搜索从现有记录建立索引，本连接的写入、修改和删除通过 TEMP trigger 同步；其他连接提交变更后，下次搜索在一致的读取事务里重建。关闭连接会释放索引，重启后从数据库恢复。大量记录或频繁跨进程写入时，重建会增加首次搜索延迟。

权重可在插件配置中调整，均须为正的有限数：

searchTitleWeight: 5
searchTagWeight: 3
searchBodyWeight: 1

这是词法检索，支持中文复合词的子词，但不保证任意字符片段或同义词匹配；「看展」与「参观展览」仍可能需要模型换关键词查询。没有向量检索或自动语义扩展。

修改与删除已有记录

直接说「刚才那部电影评分改成 8 分」「这条记重复了，删掉」「证书检查已经完成」「把那个想法关联到博客项目」。模型使用会话中的记录 id 或先查询定位；多个候选都符合时先询问，不用相关性排名代替用户选择。记录与查询结果显示 id，get_personal_record 按精确类型和 id 返回完整行及 revision。

update_personal_record 和 delete_personal_record 必须传入读取结果的 expected_revision。服务在 BEGIN IMMEDIATE 事务里核对内容指纹再写入；其他连接或工具已改动记录时拒绝操作，模型需重新读取并核对意图。指纹不是历史版本序号：内容完全恢复后可恢复同一指纹。任务和博客的专用修改工具，以及 complete_task，也要求该参数。updateTask、completeTask 和 updateBlogPost Service API 同样要求传入读取到的 revision。

修改使用行字段的 camelCase 名称，只提交需要改变的字段；省略保留原值，空字符串清空允许为空的文本，[] 清空标签。null 可清空评分、任务截止日期、可空项目/网站链接及任务来源字段。项目和网站引用使用已有精确 id；任务的 sourceType 与 sourceId 在修改时必须同时有值或同时为 null。任务进入 DONE 自动记录完成日期，再次标记完成保留原日期，改成其他状态则清空完成日期。经历的类别、动作、评分和发生日期沿用记录时的校验；id 和创建时间不可修改。相对截止日期可使用 dueIn，显式 dueAt 优先（包括 null）。

删除是永久删除，没有撤销入口。项目日志、任务、博客和想法的外键引用，以及任务中类型/id 精确匹配的来源引用，会阻止删除并返回引用记录列表。用户决定解除或重新关联这些引用后再删；不级联删除其他记录。只移除目标自身及其两端的显式 relations，整个操作失败时一起回滚。修改、删除和回滚同步到检索索引；schema 保持 v4，现有数据无需迁移。