name: dex-update description: 一键安全更新Dex（自动处理所有内容）

此命令的作用

对于非技术用户： 自动更新Dex到最新版本。无需命令行知识——只需运行命令并按照提示操作。

何时使用：

当 /dex-whats-new 显示有新版本可用时
当您想要最新的功能和错误修复时

它处理的内容：

自动下载更新
保护您的数据（从不触碰您的笔记、任务、项目）
保留受保护的用户块和用户拥有的MCP条目
通过引导选择解决冲突（无需手动合并编辑器）
显示清晰的进度和确认信息

时间： 2-5分钟

过程

步骤 1: 预检查

A. 检查Git是否可用

尝试运行基本git命令：

git --version

如果未找到Git：

❌ 未检测到Git

Dex更新需要Git。以下是安装方法：

**Mac：** 
1. 打开终端（Cmd+Space，输入“Terminal”）
2. 运行：xcode-select --install
3. 提示时点击安装
4. 完成后返回这里

**Windows：**
1. 下载自：https://git-scm.com/download/win
2. 运行安装程序，使用默认选项
3. 重启Cursor
4. 再次尝试 /dex-update

[跳过更新] — 我稍后再做

如果用户跳过，优雅退出。

B. 检查当前设置

运行：git remote -v

场景 1: 以ZIP下载（无Git）

❌ 不是Git仓库

看起来您以ZIP文件下载了Dex，而不是克隆它。

**更新方法：**
1. 下载最新版本：https://github.com/davekilleen/dex/archive/refs/heads/main.zip
2. 解压到新文件夹
3. 从当前Dex复制这些文件夹到新文件夹：
   • System/user-profile.yaml
   • System/pillars.yaml
   • 00-Inbox/
   • 01-Quarter_Goals/
   • 02-Week_Priorities/
   • 03-Tasks/
   • 04-Projects/
   • 05-Areas/
   • 07-Archives/
4. 删除旧Dex文件夹
5. 重命名新文件夹为'dex'
6. 在Cursor中打开

[显示详细指南] — 打开逐步说明
[取消] — 我稍后再做

如果选择详细指南，打开 06-Resources/Dex_System/Updating_Dex.md（手动更新部分）。

场景 2: 已克隆但无上游远程

如果 git remote -v 仅显示“origin”指向 github.com/davekilleen/dex：

✓ 检测到Git仓库

设置自动更新...

运行：

git remote rename origin upstream

继续到步骤2。

场景 3: 已配置

如果上游存在，继续到步骤2。

步骤 2: 检查更新

调用更新检查器：

check_for_updates(force=True)

如果没有可用更新：

✅ 您已经在最新版本 (v1.2.0)

无需更新！

退出。

如果有可用更新，显示摘要：

🎁 Dex v1.3.0 可用

您当前版本：v1.2.0
最新版本：v1.3.0

新功能：
- 职业教练改进
- 任务去重修复  
- 会议智能增强

[查看完整发布说明]
[立即更新]
[取消]

步骤 3: 更新前安全检查

A. 检查未提交的更改

运行：git status --porcelain

如果有更改：

💾 正在保存您的工作...

Dex在您的保险库中发现了未保存的更改。
让我在更新前保存它们。

运行：

git add .
git commit -m "Auto-save before Dex update to v1.3.0"

显示：

✓ 您的工作已保存

B. 创建备份引用（安全网）

运行：

git tag backup-before-v1.3.0

这创建了一个快照，用户可以回滚如果需要。

步骤 4: 下载更新

⬇️ 正在从GitHub下载更新...

运行：

git fetch upstream

如果网络错误：

❌ 无法连接到GitHub

请检查您的互联网连接并重试。

[重试]
[取消]

成功：

✓ 更新已下载

步骤 5: 检查破坏性更改

解析步骤2的更新响应。

如果 breaking_changes: true：

⚠️ 重要：此更新包含重大更改

Dex v2.0.0 包含破坏性更改，需要额外步骤：

[显示更改内容]

可以安全进行，但：
• 一些文件夹可能被重命名
• 配置格式可能更改  
• 迁移将自动运行

[继续更新]
[取消 — 我先阅读详情]

如果取消：

显示发布说明链接
优雅退出
用户可以准备好时再次运行 /dex-update

步骤 6: 应用更新

🔄 正在应用更新...

A. 合并更新

运行：

git merge upstream/main --no-edit

B. 处理合并结果

情况 1: 干净合并（无冲突）

✓ 更新应用成功

继续到步骤7。

情况 2: 合并冲突

检查哪些文件有冲突：

git status | grep "both modified"

自动冲突解决（受保护块 + 引导选择）：

受保护用户块（原样保留）：

CLAUDE.md 包含用户块：
- USER_EXTENSIONS_START … USER_EXTENSIONS_END

自定义MCP服务器（按名称保留）：

任何以 custom- 开头的MCP服务器名称被保留
例如：custom-gmail、custom-hubspot

自定义技能（按名称保留）：

任何以 -custom 结尾的技能文件夹被保留
例如：meeting-prep-custom、daily-plan-custom

当冲突发生时：

如果文件是用户数据 (00-07, System/user-profile.yaml, System/pillars.yaml)：
- 保留用户版本
- 运行：git checkout --ours <file>
如果文件包含受保护用户块 (CLAUDE.md)：
- 采用上游版本
- 重新插入保留的用户块原样
- 验证标记仍存在
如果文件是 .mcp.json：
- 保留任何名为 custom-* 的MCP条目
- 继续所有其他MCP的Dex核心更新
如果技能文件夹以 -custom 结尾：
- 完全保留，永不修改
- 这些是用户的个人技能
如果文件是核心Dex (技能, 核心MCP, 脚本) 并且用户编辑过它：
- 使用AskUserQuestion解决，而不是合并编辑器

AskUserQuestion流程（通用，参数化）：

标题：Dex更新冲突：{{item_name}}

您的更改：
{{user_change_summary}}
启用：{{user_use_case_summary}}

Dex更新：
{{dex_change_summary}}
启用：{{dex_use_case_summary}}

选项：
1) 保留我的版本（保留我的更改）
2) 使用Dex版本（采用上游更改）
3) 保留两者（重命名一个）
4) 让我告诉您怎么做（我会写指令）

如果AskUserQuestion不可用（非Claude Code）：

使用简单的CLI提示，具有相同4个选项。
为每个选项添加一行权衡（您保留什么vs失去什么）。
如果用户输入无效选择，重新提示一次并默认为“使用Dex版本”。

如果用户选择“保留两者”：

MCP：name → name-custom
技能文件夹：name/ → name-custom/

解决所有冲突后：

git add <file>
git commit --no-edit

显示给用户：

✓ 更新应用成功

处理的冲突：
• 保留了您的受保护块
• 更新了核心Dex功能
• 根据您的选择解决了重叠更改

[查看更改内容]

情况 3: 合并失败（罕见）

❌ 更新无法自动完成

这很罕见，但有时更新需要手动审查。

**发生了什么：**
[错误消息]

**选项：**
[恢复到更新前] — 使用我们创建的备份
[获取帮助] — 打开GitHub问题模板

如果恢复：

git merge --abort
git reset --hard backup-before-v1.3.0

步骤 7: 更新后步骤

A. 检查迁移需求

如果breaking_changes为真，检查迁移脚本：

ls core/migrations/v*-to-v*.sh

如果找到：

🔧 正在运行迁移...

此更新需要一次性迁移以更新您的数据结构。
这是安全且自动的。

运行：

./core/migrations/v1-to-v2.sh --auto

显示迁移输出。

B. 更新依赖项

📦 正在更新依赖项...

运行：

npm install
pip3 install -r core/mcp/requirements.txt

C. 同步MCP配置（自动）

通过比较 .mcp.json.example 条目与用户的实时 .mcp.json（或 System/.mcp.json）检查更新中是否添加了新MCP服务器。

对于每个在 .mcp.json.example 中但不在用户的 .mcp.json 中的条目：

从 .mcp.json.example 读取条目
用实际保险库路径替换 {{VAULT_PATH}}
添加到用户的 .mcp.json
记录：“✓ 添加了新MCP服务器：[名称]”

永不删除或修改现有用户MCP条目。 仅添加缺失的。

示例： 如果 .mcp.json.example 有 dex-analytics 但用户配置中没有：

"dex-analytics": {
  "type": "stdio",
  "command": "python",
  "args": ["<vault_path>/core/mcp/analytics_server.py"],
  "env": { "VAULT_PATH": "<vault_path>" }
}

如果添加了新MCP，添加到摘要：“✓ 添加了新MCP服务器：dex-analytics”

D. 同步使用日志功能（自动）

将新功能条目从模板 System/usage_log.md 合并到用户的现有 System/usage_log.md。

合并逻辑：

读取上游模板 System/usage_log.md（来自刚刚更新的dex-core文件）
读取用户的现有 System/usage_log.md
对于模板中的每个 - [ ] 或 - [x] 行：
- 提取功能描述（复选框后的文本）
- 在用户文件中搜索包含相同功能描述的行
- 如果找到： 保留用户版本（保留他们的 [x] 状态）
- 如果未找到： 这是新功能—将其添加到用户文件的相同部分
保留所有用户状态：勾选的复选框、同意决定、旅程元数据、日期
更新 功能采用得分：X/Y 中的功能计数（Y = 新总数）

部分匹配： 通过 ## 部分名称 标题（例如，“## 核心工作流”、“## 高级”）匹配新条目到正确的部分。如果模板中有新部分但用户文件中没有，添加整个部分。

永不：

取消勾选用户的复选框
更改同意或元数据值
移除用户有的条目

记录：“✓ 添加了N个新功能到usage_log.md”（如果未添加任何内容，则“✓ 使用日志是最新的”）

E. 启用新后台自动化（自动）

检查需要安装的自动化脚本。这些静默运行，无需提示。

会议同步（如果检测到Granola）：

检查Granola是否安装：

ls "$HOME/Library/Application Support/Granola/cache-v3.json" 2>/dev/null

如果Granola缓存存在且会议自动化尚未安装：

# 检查是否已安装
launchctl list | grep com.dex.meeting-intel

如果未安装：

cd .scripts/meeting-intel && ./install-automation.sh 2>/dev/null

如果安装，添加到摘要：“✓ 启用了自动会议同步（每30分钟运行）”

未来自动化： 此模式扩展到其他后台服务。检查先决条件（例如，应用安装、API密钥存在），然后静默运行安装程序。

步骤 8: 验证

✓ 更新完成！现在测试...

快速冒烟测试：

检查关键文件存在：
- 03-Tasks/Tasks.md
- System/user-profile.yaml
- .claude/skills/daily-plan/SKILL.md
检查MCP配置：
- .mcp.json 存在且是有效的JSON
- 自定义MCP条目（custom-*）仍存在
检查CLAUDE.md：
- USER_EXTENSIONS_START/END 标记仍存在
尝试加载用户配置文件：
- 读取 System/user-profile.yaml

如果全部通过：

✅ 更新成功！

如果某些失败：

⚠️ 更新完成但发现问题

[失败内容的详情]

您的数据是安全的，但您可能想：
[恢复到先前版本]
[报告此问题]
[继续]

步骤 9: 摘要

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Dex已更新：v1.2.0 → v1.3.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

新功能：
• 职业教练改进
• 任务去重修复
• 会议智能增强

您的数据：
✓ 所有笔记保留
✓ 所有任务保留
✓ 所有自定义保留

[查看完整变更日志]
[开始使用新功能]

如果启用了新自动化：

🤖 新自动化已启用：
✓ 自动会议同步（每30分钟运行）

如果有冲突：

🔍 应用的更改：
• 更新了12个核心文件
• 保留了5个您的自定义文件
• 保护了所有您的数据文件夹

[查看详细更改列表]

步骤 9b: 检查新集成（成功后）

成功更新后，检查是否有新集成功能可用：

from core.integrations import get_post_update_integration_message, should_show_integration_prompt

if should_show_integration_prompt():
    msg = get_post_update_integration_message()
    if msg:
        print(msg)

如果集成可用但未配置：

---

## 🔌 新：生产力集成

此更新包括您喜爱工具的集成：

- **Notion** — 搜索您的工作空间，将文档拉入会议准备
- **Slack** — 搜索对话，获取人员上下文
- **Google** — Gmail搜索，个人页面中的电子邮件上下文

**现在设置？** 这些是可选的，但解锁强大功能如：
- “Sarah关于Q1预算说了什么？” → 搜索Slack
- 会议准备从Notion拉取相关文档
- 个人页面显示电子邮件/Slack历史

运行 `/integrate-notion`、`/integrate-slack` 或 `/integrate-google` 来设置。

如果用户有可升级的集成：

---

## 🔄 集成升级可用

您有一些集成可以升级到Dex推荐的包：

### Notion
- **当前：** custom-notion-mcp
- **推荐：** @notionhq/notion-mcp-server
- **好处：** 来自Notion官方，维护最佳，完整API覆盖

**选项：**
1. **保留现有** — 您当前的设置正常工作
2. **升级** — 运行 `/integrate-notion` 切换到推荐

步骤 10: 跟踪使用（静默）

更新 System/usage_log.md 以标记Dex更新为已使用。

分析（静默）：

调用 track_event，事件名称 dex_update_completed 和属性：

from_version
to_version

这仅在用户选择加入分析时触发。如果返回“analytics_disabled”，则无需操作。

清除更新通知：

从更新检查器MCP调用 dismiss_update() 以移除 System/.update-available 文件。这会停止未来会话中出现每日更新提醒。

错误恢复

如果在任何点更新失败

用户总有逃生舱口：

🔙 正在恢复到更新前...

运行：

git merge --abort 2>/dev/null || true
git reset --hard backup-before-v1.3.0
git clean -fd

✓ 已恢复到 v1.2.0

未更改任何内容。您的Dex完全如之前。

[重试更新]
[报告问题]
[取消]

迁移支持（对于破坏性更改）

自动迁移标志

如果迁移脚本支持 --auto 标志，以非交互方式运行：

./core/migrations/v1-to-v2.sh --auto

迁移脚本必须：

接受 --auto 标志
跳过确认提示
成功时返回退出代码0
记录到 System/.migration-log

需要手动迁移

如果脚本不支持 --auto：

⚠️ 需要手动步骤

此更新需要您运行迁移脚本。

别担心—只需一个命令，耗时30秒。

**在Cursor的终端（底部面板）中，运行：**

./core/migrations/v1-to-v2.sh

**完成后返回这里。**

[我已运行迁移—继续]
[显示迁移作用]
[取消更新]

替代：ZIP下载路径

对于不能或不想使用Git的用户，提供手动指令：

📥 手动更新方法

如果自动更新不工作，您可以手动更新：

1. **下载最新Dex：**
   https://github.com/davekilleen/dex/archive/refs/heads/main.zip

2. **复制您的数据和自定义块：**
   从旧Dex文件夹，复制这些到新Dex文件夹：
   
   ✓ System/user-profile.yaml
   ✓ System/pillars.yaml
   ✓ 00-Inbox/ (整个文件夹)
   ✓ 01-Quarter_Goals/ (整个文件夹)
   ✓ 02-Week_Priorities/ (整个文件夹)
   ✓ 03-Tasks/ (整个文件夹)
   ✓ 04-Projects/ (整个文件夹)
   ✓ 05-Areas/ (整个文件夹)
   ✓ 07-Archives/ (整个文件夹)
   ✓ .env (如果存在)
   ✓ 您的 `USER_EXTENSIONS` 块从 `CLAUDE.md`
   ✓ 任何名为 `custom-*` 的自定义MCP条目从 `.mcp.json`
   ✓ 任何以 `-custom` 结尾的自定义技能

3. **不要复制：**
   ✗ .claude/skills/ (使用新版本)
   ✗ core/mcp/ (使用新版本)
   ✗ README.md (使用新版本)

4. **在Cursor中打开新文件夹**

5. **运行 /setup 验证**

[现在下载]
[复制逐步指令到剪贴板]

设置

用户可以在 System/user-profile.yaml 中配置更新行为：

updates:
  auto_check: true              # 在 /daily-plan 期间检查
  check_interval_days: 7        # 检查频率
  auto_update: false            # 未经询问永不自动更新
  backup_before_update: true    # 更新前始终创建备份标签

非技术用户体验

用户在每日计划中看到：

🎁 Dex v1.3.0 可用。运行 /dex-whats-new 查看详情。

用户运行：

/dex-update

用户看到：

✓ 检测到Git
✓ 更新已下载
✓ 无冲突
✓ 依赖项已更新
✅ 更新完成！v1.2.0 → v1.3.0

总点击次数： 1（只需运行命令） 总时间： 2分钟 所需技术知识： 零

理念

尽可能自动：

Git命令静默运行
冲突自动解决
依赖项自动更新
迁移自动运行（安全时）

必要时交互：

破坏性更改：确认理解
手动迁移：清晰指令
错误：始终提供恢复选项

始终安全：

任何更改前创建备份
用户数据永无风险（gitignored）
一键回滚如果问题
每个步骤清晰状态

无术语：

不说“合并冲突”—说“重叠更改”
不说“上游”—说“主Dex仓库”
不说“git fetch”—说“下载更新”
不说“rebase”—只是不使用rebase

Dex一键更新Skill dex-update