安装 / 卸载 / 冲突解决指引

September 11, 2026 · View on GitHub

本文是给用户看的使用指引：讲清安装原理、两条安装路径、冲突解决功能怎么用、卸载怎么用。内部设计规格见 dsh-native-refactor.md。

0. 一句话原理

dsh-math-memory 由两层组成，安装方式不同：

  • 能力层（bundle）：preset「数学笔记助手」、笔记工具、记忆引擎、面板路由、工作区自动注册。这一层用 dsh 原生命令 dsh plugin 安装，符合 dsh 设计理念。
  • 姿态层（posture）：fail-closed 沙箱、审批策略、权限表、默认 preset、工作区根目录。这一层是「部署姿态」，由安装程序写入 profile 的 cordis.patch.yml。

一句话：能力走 dsh plugin，姿态由安装程序落盘。 因为「能力」是可复用的插件，「姿态」是这台机器/这个用户的部署选择，二者不该混在一个可复用包里。

1. 安装方式

方式 A：把 bundle 加进已有 web profile（只装能力）

dsh plugin --profile web add dsh-math-memory

把我们的 bundle 加进已存在的 web profile（它自带 in-box 的 dsh-base + dsh-web-app）。装完后重启 dsh，bundle 宿主插件会在启动时把 preset 同步进 ~/.dsh/.agent-presets/，新建会话即可选「数学笔记助手」。

注意：@deepseek-ai/dsh-web-app 是 dsh 的 in-box bundle（随 dsh 安装自带），不能 dsh plugin add（会去注册表拉一个版本对不上的副本）。新建专用 profile 请用方式 B（安装程序会写骨架），方式 A 只适合往已有 web profile 里加 bundle。方式 A 也没有 fail-closed 沙箱（沿用 web 的沙箱）。

方式 B：安装程序（能力 + 姿态 + 模板，CLI/npm 用户）

dsh-math-memory install --vault /path/to/你的Obsidian库

内部依次做：调 dsh plugin add 装能力 → 写 profile 姿态 → 写 owner marker → 种 vault 模板（AGENTS.md + .deepseek/**）。这是完整安装，需要 pnpm + 网络。

方式 C：离线扁平拷贝（无 pnpm）

dsh-math-memory install --direct --vault /path/to/你的Obsidian库

把随包发布的 preset/profile 文件直接写进 ~/.dsh（不需要 pnpm / 网络），并写同样的 owner marker。功能与方式 B 等价，只是「能力」不是由 bundle 在启动时同步，而是命令式落盘。

Obsidian 插件安装

Obsidian 插件内置直写流程（等价于方式 C 的 --direct 逻辑，因为插件必须离线可用、不依赖 node/pnpm），并写同样的 owner marker。三种方式功能等价，靠 owner marker 避免互相覆盖。

装进已有 web profile？

可以，但会失去 fail-closed 沙箱（沿用 web profile 自己的沙箱策略）。安装程序检测到非专用 profile 时会打印醒目警告。想保证安全边界，请用专用的 notes-assistant profile。

2. 升级

# 能力层升级（preset/工具/引擎/面板）
dsh plugin --profile notes-assistant update dsh-math-memory

升级后重启 dsh，宿主插件会把新版 preset 同步进 .agent-presets/（字节比对，只更新变化的部分，不碰用户自建的其它 preset）。vault 模板属于「种子」，只在 install 时种一次、之后归用户，升级不会覆盖你改过的模板。

3. 冲突解决怎么用

系统在多个位置写入时，用 owner marker（归属标记） 判定所有权，避免两条通道（npm bundle 同步 vs direct 直写）互相覆盖。owner 取值只有两个：npm（bundle 在启动时同步）和 direct（--direct 或 Obsidian 内置直写）。

先诊断：

dsh-math-memory status

会列出：bundle 是否登记、preset 同步状态、姿态是否在位、当前 owner 是谁、vault 模板清单。

遇到「归属冲突」报错时：

preset .agent-presets/notes-assistant is owned by "direct" (v0.7.0),
but this installer is "npm" (v0.7.1). Refusing to overwrite.

意思是：之前用 --direct（或 Obsidian 内置直写）装的（owner=direct），现在又用 bundle 装（owner=npm）。这是保护，不是故障。两个选择：

  • 切回原通道：用回之前那套（direct / Obsidian）继续维护，不要混用。

  • 切换到新通道（接管）：确认后加 --force：

    dsh-math-memory install --force

    --force 会重写 marker，把所有权接管到 npm 通道，之后以 npm 包为准。

双向保护：这套拒绝是双向的——--direct/Obsidian 直写遇到 owner=npm 会拒绝；bundle 在启动时同步遇到 owner=direct 也会跳过并告警。任何一方都不会静默覆盖另一方的安装。

全局 patch：本系统写进 $DSH_HOME/cordis.patch.yml 的条目都用 # dsh-math-memory:begin / # dsh-math-memory:end 包裹，卸载只摘除自己这一块，不碰其它插件。

4. 卸载怎么用

dsh-math-memory uninstall            # 先看计划，不做任何改动（默认 dry-run）
dsh-math-memory uninstall --yes      # 执行「自动删」级别
dsh-math-memory uninstall --purge --yes          # 加删脚手架模板
dsh-math-memory uninstall --purge --purge-data --yes   # 加删记忆内容（需确认短语）

卸载按「可重建性」分三级：

记忆默认保留：卸载不会删除你的记忆内容（records/topics/theorems/templates/episodes/strategy 卡片、inbox、archive 等），除非你显式加 --purge-data 并输入确认短语 DELETE MY MATH MEMORY。不传 --vault 时 .deepseek/** 完全不被触碰。

级别内容何时删
自动删bundle 登记、同步出的 preset 副本、机器缓存 .deepseek/cache/**、工作区注册--yes
骨架index.md、_README.md（纯索引骨架，重装可逐字重建）--purge
内容AGENTS.md、profile.md、notation.md、capture-policy.md、config.md、working.md、records/topics/theorems/templates/episodes/strategy 卡片、inbox/*.md、archive/**--purge-data + 输入 DELETE MY MATH MEMORY

安全设计：

  1. 默认 dry-run：不带 --yes 时只打印「将删 / 将保留」清单，不写任何东西。
  2. 记忆内容（不可重建）只有在 --purge-data 且输入确认短语 DELETE MY MATH MEMORY 时才删，删除前会提示你先备份。
  3. 执行结束打印三份清单：已删 / 已保留（列路径）/ 需手动（如 Obsidian 插件本体，交给 Obsidian 自己禁用/卸载）。

示例输出：

$ dsh-math-memory uninstall
[dry-run] will remove bundle: dsh-math-memory, @deepseek-ai/dsh-web-app (profile notes-assistant)
[dry-run] will remove preset copy: ~/.dsh/.agent-presets/notes-assistant (owner=npm)
[dry-run] will remove cache: <vault>/.deepseek/cache
[keep]    skeletons (use --purge): .deepseek/**/index.md, _README.md
[keep]    memory content (use --purge-data): AGENTS.md, .deepseek/memory/records/**, ...
Run with --yes to execute the "自动删" tier.

5. 常见问题

  • 装完看不到「数学笔记助手」preset？ bundle 在 dsh 启动时才同步 preset，dsh plugin add 后请重启 dsh。
  • status 显示 owner 是 direct，我想改用 npm？ 见 §3，用 install --force 接管。
  • 只想删缓存、保留所有记忆？ uninstall --yes（只动「自动删」级别，记忆内容默认保留）。
  • 卸载会删我的笔记吗？ 不会。本系统只管理 .deepseek/** 下的记忆文件与模板；你的普通笔记（.md）从不被安装/卸载触碰。记忆内容也只在 --purge-data + 确认短语时才删。
  • 为什么装能力用 dsh plugin、装姿态要用安装程序？ 见 §0 与 dsh-native-refactor.md §2：dsh plugin 是 dsh 原生的 bundle 安装通道；「种安全姿态」这类部署操作 dsh 没有原生命令，只能由安装程序落盘。