SpecStory 是一个 Cursor / VS Code 扩展，用于自动保存、搜索和分享 AI 对话历史。本文涵盖 SpecStory 的完整使用教程，以及在 Remote SSH 场景下路径构建 Bug 的根因分析与修复方案。

一、SpecStory 是什么

SpecStory 是一个 AI 对话历史管理扩展，解决 Cursor 原生存在的三个痛点：

问题 Cursor 原生行为 SpecStory 解决方案
对话不持久 聊天记录存在本地 SQLite 中，换电脑就丢失 自动保存为 Markdown 文件到项目目录
不可搜索 无法跨项目搜索历史对话 本地搜索 + 云端全文搜索
不可分享 没有导出或分享功能 一键生成分享链接

二、工作原理

2.1 数据流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Cursor AI 对话
    │
    │  Cursor 将对话写入内部 SQLite 数据库（state.vscdb）
    ▼
SpecStory 扩展（监听 SQLite 数据库变化）
    │
    ├──► 本地保存：<项目>/.specstory/history/*.md
    │       ↑ 保存在项目目录中（Remote SSH 场景下保存在远程服务器上）
    │
    ├──► 云端同步（可选）：cloud.specstory.com
    │       ↑ 跨设备搜索和备份
    │
    └──► 规则派生（可选）：.cursor/rules/derived-cursor-rules.mdc
            ↑ 从对话中提取你的编码偏好，反馈给 AI

2.2 触发时机

  • 自动保存：当 Cursor 将对话数据刷入 SQLite 后触发，通常在 AI 回复完成后延迟几秒
  • 安全网：每 2 分钟检查一次是否有未保存的变化
  • 云同步：根据配置，可在自动保存后自动触发或手动触发

2.3 Remote SSH 场景

在 Remote SSH 模式下：

  • SpecStory 扩展本身安装在本地 Windows Cursor 客户端上
  • .specstory/ 数据目录保存在远程 Linux 的项目目录中
  • 换电脑后：扩展需要重新安装，但历史 Markdown 文件仍在远程服务器上

三、安装与配置

3.1 安装

  1. 在 Cursor 内部打开扩展面板（Ctrl+Shift+X）
  2. 搜索 “SpecStory”
  3. 点击 Install

注意：必须从 Cursor 内部安装，不要从 Visual Studio Marketplace 网站安装。网站安装会导致扩展装到 VS Code 而非 Cursor。

3.2 验证安装成功

  1. 与 Cursor AI 进行一次对话
  2. 检查项目根目录下是否出现 .specstory/history/ 目录
  3. 目录中应有一个以时间戳命名的 .md 文件

3.3 登录账号（Cloud Sync 和 Share 需要）

  1. 在侧边栏找到 SpecStory 面板
  2. 点击 ACCOUNT 区域的登录按钮
  3. 使用邮箱注册/登录

3.4 配置项速查表

打开 Settings（Ctrl+,）→ 搜索 specstory：

设置项 设置键 类型 默认值 建议
Cloud Sync specstory.cloudSync 下拉 ask 保持 ask
Auto Save specstory.autoSave 复选框 启用 保持启用
Output Path specstory.outputPath 文本 .specstory/history 保持默认
Derived Rules specstory.derivedRules 复选框 禁用 按需开启
Derived Rules Headers specstory.fileHeaders 多行文本 默认 8 个标题 开启派生后按需调整
UTC Timezone specstory.utcTimezone 复选框 启用 保持启用
Help Us Improve specstory.analytics 复选框 启用 按隐私偏好决定
Show Developer Tools specstory.debug 复选框 禁用 排查问题时开启

各配置项详细说明：

  • Cloud Sync：always 每个新项目自动启用云同步；ask 打开新项目时弹窗询问；never 默认不启用
  • Auto Save：核心功能，控制是否自动将 AI 对话保存到 .specstory/history/
  • Output Path：历史文件存储路径（相对于项目根目录），所有生态工具默认查找 .specstory/history
  • Derived Rules：启用后自动从对话中提取编码规则写入 .cursor/rules/derived-cursor-rules.mdc，需同时启用 Auto Save 并登录账号
  • UTC Timezone：勾选使用 UTC 时区（如 2026-03-10_14-10Z），取消勾选使用本地时区
  • Show Developer Tools：启用后在 Output 面板出现 “SpecStory” 频道，显示详细日志

四、核心功能

4.1 Auto Save（自动保存）

SpecStory 最核心的功能。工作方式：

  1. 你与 Cursor AI 进行对话
  2. Cursor 将对话数据写入内部 SQLite 数据库
  3. SpecStory 检测到数据库变化，提取对话内容
  4. 格式化为 Markdown 并保存到 .specstory/history/ 目录
  5. 文件随对话进展实时更新（不是对话结束后才保存）

特点：在后台静默运行，支持 Remote SSH / Dev Containers / WSL 环境，保留完整内容（用户提问、AI 回复、工具调用、代码 diff），每个对话独立一个文件。

4.2 Manual Save（手动保存）

通过命令面板（Ctrl+Shift+P）→ SpecStory: Save AI Chat History，可以手动保存对话或将多个相关对话合并为一个文件。

4.3 Share（分享对话）

通过命令面板 → SpecStory: Share AI Chat History：

  • 生成 share.specstory.com/<id> 私有链接，对方无需注册账号即可查看
  • 可以隐藏/显示特定对话轮次、编辑标题、删除敏感内容、添加 Markdown 注释
  • 随时可撤销分享

4.4 Search（搜索历史）

侧边栏点击 Search AI Chat History 或通过命令面板运行，搜索范围为本地 .specstory/history/ 中的所有 Markdown 文件。也可以直接使用 Cursor 全局搜索（Ctrl+Shift+F）。

4.5 Cloud Sync（云同步）

会话以原始 JSON + Markdown 两种格式存储在云端。同步方式包括：

方式 操作
扩展自动同步 侧边栏 Cloud Sync 设为 On，保存对话后自动触发
扩展手动同步 命令面板 → SpecStory: Sync with Cloud
CLI 同步 终端运行 specstory sync（需先 specstory login）

登录 cloud.specstory.com 后可跨项目全文搜索、按项目/时间过滤、查看完整对话。

4.6 Derive AI Rules（规则派生）

SpecStory 分析对话历史，识别带有规则性语义的语句（含 “always”、”never”、”must” 等信号词），将其提取并组织为项目级 AI 规则，写入 .cursor/rules/derived-cursor-rules.mdc。旧版本自动备份到 .specstory/ai_rules_backups/。

如果你… 建议
已手动维护 Skills + User Rules 体系 暂不开启，避免冲突
新项目，想让 AI 自动学习你的偏好 可以尝试开启
团队项目，想自动积累编码规范 适合开启，将派生规则提交 git

4.7 侧边栏与命令面板

SpecStory 在侧边栏提供三个区域：功能按钮区（Save / Share / Search / Settings）、自动化区域（Cloud Sync / Auto-save / Derive AI rules 的开关状态和最近保存时间）、账号区域（登录状态和登出按钮）。

命令面板快捷命令汇总：

命令 功能
SpecStory: Save AI Chat History 手动保存对话
SpecStory: Share AI Chat History 生成分享链接
SpecStory: Search AI Chat History 搜索历史对话
SpecStory: Sync with Cloud 手动触发云同步
SpecStory: Open Cloud Sync Configuration 打开项目云同步配置

五、目录结构与文件格式

5.1 .specstory 目录结构

.specstory/ 是 SpecStory 在每个项目根目录下自动创建的数据目录。以一个典型项目为例：

1
2
3
4
5
6
7
8
9
10
11
12
/path/to/project/
└── .specstory/
    ├── .what-is-this.md              # 目录说明文档（自动生成）
    ├── .project.json                 # 项目标识文件（云同步用）
    │
    ├── history/                      # 对话历史目录（核心）
    │   ├── 2026-01-14_12-43Z-mcp-to-cursor-format-conversion.md
    │   ├── 2026-03-10_14-10Z-some-long-conversation.md
    │   └── ...
    │
    └── ai_rules_backups/             # 规则派生备份（开启 Derived Rules 后才出现）
        └── ...

关键理解：

  • 每个项目独立一个 .specstory/ 目录，保存在项目所在位置（Remote SSH 场景下即远程服务器上）
  • 换电脑后只要打开同一个远程项目，对话历史仍然完整可用

5.2 各文件说明

.project.json — 项目标识文件：

1
2
3
4
5
6
7
{
  "workspace_id": "xxxx-xxxx-xxxx-xxxx",
  "workspace_id_at": "2026-03-10T14:38:36.617Z",
  "project_name": "my-project",
  "cloud_sync": true,
  "user_id": "user@example.com"
}

workspace_id 是云同步的身份凭证，即使项目文件夹被移动或重命名，云端仍能通过此 ID 识别同一个项目。不要手动修改此字段。

history/ — 对话历史目录，文件命名规则：<日期>_<时间>Z-<对话标题slug>.md

5.3 history 文件的 Markdown 格式

每个对话文件由以下部分组成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<!-- Generated by SpecStory, Markdown v2.1.0 -->
<!-- cursor Session <session-uuid> (2026-01-14 12:43Z) -->

# 对话标题 (2026-01-14 12:43Z)

_**User**_

用户的完整提问内容...

---
_**Agent (model claude-4.6-opus-max-thinking, mode Agent)**_

Agent 的完整回复文本...

<think><details><summary>Thought Process</summary>
思考过程...
</details></think>

<tool-use data-tool-type="read" data-tool-name="read_file_v2">
<details><summary>Tool use: **read_file_v2** • Read file: /path/to/file</summary>
</details>
</tool-use>

常见工具类型：

data-tool-type 含义 常见工具名
read 文件读取 read_file_v2
write 文件写入/编辑 edit_file_v2、apply_patch
generic 搜索/通用操作 glob_file_search、ripgrep_raw_search
unknown 其他工具 shell_command

5.4 版本控制建议

内容 是否提交 git 原因
.specstory/history/ 推荐提交 让队友在 PR 中审查 AI 的推理过程
.specstory/ai_rules_backups/ 不提交 已有 git 管理规则文件版本
.specstory/.project.json 不提交 含个人账号信息
.specstory/.what-is-this.md 不提交 说明文档，自动生成

推荐的 .gitignore 配置：

1
2
3
.specstory/ai_rules_backups
.specstory/.what-is-this.md
.specstory/.project.json

六、Remote SSH 路径 Bug 分析与修复

6.1 问题现象

通过 Cursor SSH 插件连接 Linux 服务器，打开远程文件夹（如 /path/to/project）后，Windows 本地 C 盘根目录下凭空出现了镜像目录：

1
2
3
4
C:\path\to\project\
├── .specstory\
│   └── .gitignore
└── .cursorindexingignore

而远程 Linux 上的 .specstory/history/*.md（对话历史文件）是正常存在的，说明核心功能在工作，但 .cursorindexingignore 和 .specstory/.gitignore 被错误地写到了本地。

6.2 探索过程摘要

修复过程中尝试了多种方案，以下是关键结论：

方案 结果 原因
remote.extensionKind 用户设置覆盖 失败 Cursor 未正确尊重此设置
修改 package.json 的 extensionKind 为 ["workspace"] 有副作用 强制远程运行后无法读取本地 state.vscdb，auto-save 失效
在远程端安装 SpecStory 部分改善 远程端能正确创建文件，但本地端仍会写错误路径
修改 extension.js 中的 URI 构建方式 成功 根因修复

6.3 源码级根因分析

对 extension.js 进行分析，还原了 SpecStory 的路径服务架构：

1
2
3
4
5
6
7
8
9
10
11
12
// 正确的方式（用于 history 文件）— 使用 Uri.joinPath 保留远程 scheme
getSpecStoryHistoryUri() {
    let workspaceFolder = vscode.workspace.workspaceFolders[0];
    return vscode.Uri.joinPath(workspaceFolder.uri, ...outputPath.split('/'));
    // → vscode-remote://ssh-remote+<host>/path/to/project/.specstory/history
}

// 有 bug 的方式（用于 .cursorindexingignore）— 使用 path.join 丢失远程 scheme
getCursorIndexingIgnorePath() {
    return path.join(this.getWorkspacePath(), ".cursorindexingignore");
    // Windows 上 → "C:\path\to\project\.cursorindexingignore"（错误！）
}

Bug 的本质：

1
2
3
4
5
6
7
8
9
10
// history 文件（正确）
let uri = vscode.Uri.joinPath(workspaceFolder.uri, ".specstory", "history", filename);
// → URI scheme 保留为 vscode-remote://
// → workspace.fs.writeFile() 正确路由到远程

// .cursorindexingignore（bug）
let uri = vscode.Uri.file(this.pathsService.getCursorIndexingIgnorePath());
// → path.join() 在 Windows 上产生本地路径
// → Uri.file() 强制生成 file:///C:/path/to/project/.cursorindexingignore
// → workspace.fs.writeFile() 路由到本地 Windows

在 extension.js 中共发现 4 处使用了错误的 Uri.file(path.join(...)) 模式：

# Bug 代码 所在服务 创建的文件
1 <var>.Uri.file(this.pathsService.getCursorIndexingIgnorePath()) AutoSaveService .cursorindexingignore
2 <var>.Uri.file(this.pathsService.getGitIgnorePath()) AutoSaveService .specstory/.gitignore
3 <var>.Uri.file(this.pathsService.getGitIgnorePath()) ProjectIdentityService .specstory/.gitignore
4 <var>.Uri.file(this.pathsService.getGitIgnorePath()) RulesService .specstory/.gitignore

为什么是 C 盘根目录？因为 Windows 上以 / 开头的路径（如 /path/to/project）被解析为当前驱动器根目录下的路径。Cursor 进程运行在 C 盘，所以 /path/to/project 被解析为 C:\path\to\project。

6.4 修复详情

修复原理：将 4 处 Uri.file(path.join(...)) 替换为 Uri.joinPath(workspaceUri, ...)，使 URI 保留 vscode-remote:// scheme。

修改文件（Windows 本地端）：

1
2
C:\Users\<用户名>\.cursor\extensions\
  specstory.specstory-vscode-<版本号>-universal\dist\extension.js

只需修改 Windows 本地端的扩展。远程 Linux 端的扩展运行在 Linux 上，path.join 天然产生正确的 Unix 路径，不存在此 bug。

修复 1：AutoSaveService — .cursorindexingignore

1
2
3
4
// 修复前
let o = <var>.Uri.file(this.pathsService.getCursorIndexingIgnorePath())
// 修复后
let o = <var>.Uri.joinPath(this.pathsService.getWorkspaceUri(), ".cursorindexingignore")

修复 2：AutoSaveService — .specstory/.gitignore

1
2
3
4
// 修复前
let o = <var>.Uri.file(this.pathsService.getGitIgnorePath())
// 修复后
let o = <var>.Uri.joinPath(this.pathsService.getSpecStoryDirUri(), ".gitignore")

修复 3：ProjectIdentityService — .specstory/.gitignore

1
2
3
4
// 修复前
let r = <var>.Uri.file(this.pathsService.getGitIgnorePath())
// 修复后
let r = <var>.Uri.joinPath(this.pathsService.getSpecStoryDirUri(), ".gitignore")

修复 4：RulesService — .specstory/.gitignore

1
2
3
4
// 修复前
let s = <var>.Uri.file(this.pathsService.getGitIgnorePath())
// 修复后
let s = <var>.Uri.joinPath(this.pathsService.getSpecStoryDirUri(), ".gitignore")

6.5 修复后的架构分工

1
2
3
4
5
6
7
8
9
10
11
12
Windows 本地 SpecStory (UI 扩展)
├── 读取 state.vscdb（对话数据库，仅存在于本地）
├── 生成 Markdown 对话历史
├── 通过 vscode.workspace.fs（支持远程路由）写入远程
│   ├── .specstory/history/*.md    → Uri.joinPath（原本就正确）
│   ├── .cursorindexingignore      → Uri.joinPath（已修复）
│   └── .specstory/.gitignore      → Uri.joinPath（已修复）
└── 所有写入操作正确路由到远程 Linux

Linux 远程 SpecStory (安装在 cursor-server)
├── 作为补充，处理某些远程端初始化操作
└── 无法读取 state.vscdb（不在远程端），不负责 auto-save

七、更新后快速修复教程

SpecStory 扩展自动更新时，extension.js 会被替换为未修复版本，Bug 会再次出现。判断标志：C 盘根目录出现了 C:\mnt、C:\home 等不该存在的目录。以下是可重复执行的修复步骤。

7.1 确认问题是否存在

1
Test-Path "C:\mnt"
  • 返回 True → 问题存在，需要修复
  • 返回 False → 当前无此问题

7.2 确认扩展版本和路径

1
2
3
4
cursor --list-extensions | Select-String "specstory"

Get-ChildItem "$env:USERPROFILE\.cursor\extensions" -Directory |
    Where-Object { $_.Name -match "specstory" }

记下扩展目录名（如 specstory.specstory-vscode-0.32.3-universal），以下用 <EXT_DIR> 代指完整路径。

7.3 确认远程端也已安装 SpecStory

1
ssh <SSH配置名> "ls ~/.cursor-server/extensions/ | grep specstory"

如果无输出，需先在 Cursor SSH 连接远程后，在扩展面板点击 SpecStory 旁的”Install in SSH: …”按钮。

7.4 确认 Bug 是否存在于当前版本

1
2
3
Select-String -Path "<EXT_DIR>\dist\extension.js" `
    -Pattern "Uri\.file\(this\.pathsService\.(getGitIgnorePath|getCursorIndexingIgnorePath)\(\)\)" |
    Measure-Object | Select-Object Count
  • Count > 0 → bug 存在，需要修复
  • Count = 0 → 已修复，无需操作

7.5 执行修复

步骤 1：完全关闭 Cursor（包括托盘图标）。

步骤 2：备份原始文件：

1
Copy-Item "<EXT_DIR>\dist\extension.js" "<EXT_DIR>\dist\extension.js.bak"

步骤 3：执行 4 处替换（PowerShell）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$file = "<EXT_DIR>\dist\extension.js"
$content = [System.IO.File]::ReadAllText($file)

# 修复 1：.cursorindexingignore（1 处）
$content = $content -replace `
    '([\w]+)\.Uri\.file\(this\.pathsService\.getCursorIndexingIgnorePath\(\)\)', `
    '$1.Uri.joinPath(this.pathsService.getWorkspaceUri(),".cursorindexingignore")'

# 修复 2/3/4：.specstory/.gitignore（3 处）
$content = $content -replace `
    '([\w]+)\.Uri\.file\(this\.pathsService\.getGitIgnorePath\(\)\)', `
    '$1.Uri.joinPath(this.pathsService.getSpecStoryDirUri(),".gitignore")'

[System.IO.File]::WriteAllText($file, $content)
Write-Host "Done. 4 replacements applied."

正则表达式自动匹配任意变量前缀，即使新版本中变量名发生变化也能正确替换。

手动替换（备选）：用文本编辑器打开 extension.js，分两次查找替换：

查找 替换为 命中数
Uri.file(this.pathsService.getCursorIndexingIgnorePath()) Uri.joinPath(this.pathsService.getWorkspaceUri(),".cursorindexingignore") 1
Uri.file(this.pathsService.getGitIgnorePath()) Uri.joinPath(this.pathsService.getSpecStoryDirUri(),".gitignore") 3

7.6 清理 C 盘残留

1
2
3
4
5
6
@("C:\mnt", "C:\home", "C:\home_zfs", "C:\users_home") | ForEach-Object {
    if (Test-Path $_) {
        Remove-Item -Recurse -Force $_ -ErrorAction SilentlyContinue
        Write-Host "已清理: $_"
    }
}

7.7 验证修复

  1. 启动 Cursor → SSH 连接远程 → 打开远程项目 → 与 AI 进行一次对话
  2. 检查 C 盘：Test-Path "C:\mnt" 应返回 False
  3. 检查远程文件：
1
2
ssh <SSH配置名> "cat /path/to/project/.cursorindexingignore"
ssh <SSH配置名> "cat /path/to/project/.specstory/.gitignore"
  1. 确认 bug 完全消除：
1
2
3
4
Select-String -Path "<EXT_DIR>\dist\extension.js" `
    -Pattern "Uri\.file\(this\.pathsService\.(getGitIgnorePath|getCursorIndexingIgnorePath)\(\)\)" |
    Measure-Object | Select-Object Count
# Count 应为 0

7.8 一键修复脚本

将以下内容保存为 fix-specstory.ps1，每次 SpecStory 更新后运行即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# SpecStory Remote SSH Path Bug Hotfix Script

$extDir = Get-ChildItem "$env:USERPROFILE\.cursor\extensions" -Directory |
    Where-Object { $_.Name -match "specstory\.specstory-vscode" } |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 1

if (-not $extDir) {
    Write-Host "[ERROR] 未找到 SpecStory 扩展目录" -ForegroundColor Red
    exit 1
}

$jsFile = Join-Path $extDir.FullName "dist\extension.js"
$bakFile = "$jsFile.bak"

if (-not (Test-Path $jsFile)) {
    Write-Host "[ERROR] 未找到 extension.js: $jsFile" -ForegroundColor Red
    exit 1
}

$content = [System.IO.File]::ReadAllText($jsFile)
$bugCount = ([regex]::Matches($content,
    'Uri\.file\(this\.pathsService\.(getGitIgnorePath|getCursorIndexingIgnorePath)\(\)\)')).Count

if ($bugCount -eq 0) {
    Write-Host "[INFO] 当前版本无需修复（bug 不存在或已修复）" -ForegroundColor Green
    exit 0
}

Write-Host "[INFO] 扩展目录: $($extDir.FullName)" -ForegroundColor Cyan
Write-Host "[INFO] 检测到 $bugCount 处 bug，开始修复..." -ForegroundColor Yellow

Copy-Item $jsFile $bakFile -Force
Write-Host "[INFO] 已备份至 $bakFile"

$content = $content -replace `
    '([\w]+)\.Uri\.file\(this\.pathsService\.getCursorIndexingIgnorePath\(\)\)', `
    '$1.Uri.joinPath(this.pathsService.getWorkspaceUri(),".cursorindexingignore")'

$content = $content -replace `
    '([\w]+)\.Uri\.file\(this\.pathsService\.getGitIgnorePath\(\)\)', `
    '$1.Uri.joinPath(this.pathsService.getSpecStoryDirUri(),".gitignore")'

[System.IO.File]::WriteAllText($jsFile, $content)

$remainingBugs = ([regex]::Matches($content,
    'Uri\.file\(this\.pathsService\.(getGitIgnorePath|getCursorIndexingIgnorePath)\(\)\)')).Count

if ($remainingBugs -eq 0) {
    Write-Host "[SUCCESS] 修复完成！$bugCount 处 bug 已全部消除" -ForegroundColor Green
} else {
    Write-Host "[WARN] 仍有 $remainingBugs 处未修复，可能代码结构已变化，请手动检查" -ForegroundColor Yellow
}

$cleaned = @()
@("C:\mnt", "C:\home", "C:\home_zfs", "C:\users_home") | ForEach-Object {
    if (Test-Path $_) {
        Remove-Item -Recurse -Force $_ -ErrorAction SilentlyContinue
        $cleaned += $_
    }
}
if ($cleaned.Count -gt 0) {
    Write-Host "[INFO] 已清理 C 盘残留: $($cleaned -join ', ')" -ForegroundColor Cyan
} else {
    Write-Host "[INFO] C 盘无残留目录" -ForegroundColor Cyan
}

Write-Host "`n请重启 Cursor 使修复生效。" -ForegroundColor White

使用方法：发现 C:\mnt 再次出现时，先完全关闭 Cursor，打开 PowerShell 执行 .\fix-specstory.ps1，看到 [SUCCESS] 后重启 Cursor。

八、实用技巧与最佳实践

8.1 在新对话中引用历史

在 Cursor 聊天中用 @ 引用历史文件，将历史对话作为上下文注入新对话：

1
2
@.specstory/history/2026-03-10_14-10Z-some-conversation.md
请继续上次的讨论...

Agent 会读取这个历史文件，了解之前的完整上下文，而不需要你重新解释背景。这是 SpecStory 的核心价值之一：历史对话成为可复用的上下文。

8.2 排除搜索干扰

全局搜索（Ctrl+Shift+F）时，在 “files to exclude” 中添加 .specstory/*，避免历史对话内容出现在代码搜索结果中。

8.3 Cursor 代码索引排除

在项目根目录的 .cursorindexingignore 文件中添加：

1
.specstory/

防止 SpecStory 历史文件影响 Cursor 的代码库索引质量。

8.4 让 Agent 搜索历史

直接在对话中说：

1
搜索 .specstory/history/ 下的文件，找到关于 XXX 的对话

8.5 换电脑后恢复工作

内容 新电脑上的可用性 原因
.specstory/history/ 中的 Markdown 文件 完整可用 存在远程 Linux 项目目录中
cloud.specstory.com 上的对话 完整可用 登录同一账号即可搜索
Cursor Agent 面板中的聊天记录列表 不可见 Cursor 的 UI 索引存在本地（SpecStory 无法解决）

恢复步骤：在新电脑的 Cursor 中安装 SpecStory → Remote SSH 打开同一个远程项目 → .specstory/history/ 中所有历史文件立刻可见 → 用 @ 引用或搜索回顾。

九、故障排查

没有出现 .specstory 文件夹

  • 确认已打开一个项目文件夹（不是单个文件）
  • 确认 Auto Save 设置已启用
  • 尝试与 AI 进行一次对话后再检查
  • .specstory/ 只在项目存在对话记录时才会创建，打开项目时会一次性追溯导入所有历史对话

扩展安装后不可用

  • 确认从 Cursor 内部安装（不是 VS Marketplace 网站）
  • 如果从网站安装了，在 Cursor 中卸载后重新从内部安装

云同步不工作

  • 确认已登录 SpecStory 账号
  • 确认项目中存在 .specstory/history/ 目录
  • 检查 .specstory/.project.json 中 cloud_sync 是否为 true

修复后 C:\mnt 仍然出现

可能是 SpecStory 新版本新增了其他使用 Uri.file 的位置：

1
2
3
Select-String -Path "<EXT_DIR>\dist\extension.js" `
    -Pattern "Uri\.file\(this\.pathsService\.\w+\(\)\)" |
    ForEach-Object { $_.Line.Substring([Math]::Max(0, $_.Matches[0].Index - 20), 100) }

找到新的 bug 位置后，按照同样的原理替换为 Uri.joinPath。

修复后 auto-save 不工作

确认 package.json 中 extensionKind 仍为 ["ui"]：

1
Select-String -Path "<EXT_DIR>\package.json" -Pattern "extensionKind" -Context 0,2

如果被意外改为 "workspace"，本地 SpecStory 无法读取 state.vscdb，导致 auto-save 失效。恢复为 ["ui"] 即可。

扩展加载报错

可能是替换时引入了语法错误，恢复备份：

1
Copy-Item "<EXT_DIR>\dist\extension.js.bak" "<EXT_DIR>\dist\extension.js"

查看详细日志

  1. 开启 Settings → specstory.debug（Show Developer Tools）
  2. 打开 Output 面板（Ctrl+Shift+U）
  3. 从下拉菜单选择 “SpecStory”

项目路径变更后找回旧对话

Cursor 的对话记录绑定工作区路径，路径变更后旧对话在新路径下不可见。解决方案：

  1. 复制 agent-transcripts：将旧路径映射目录（~/.cursor/projects/<旧路径映射>/agent-transcripts/）复制到新路径映射目录下，重新打开项目后 SpecStory 会自动导入
  2. **复制 .specstory/history/**：如果旧项目移动前已有此目录，它会随项目一起移动
  3. Cloud Sync 恢复：登录 cloud.specstory.com 搜索旧项目的对话

预防措施：安装 SpecStory 并开启 Cloud Sync、在移动项目前确保已生成 .specstory/history/、避免频繁变更项目路径。

参考链接