⚡

导航标记技能 nav-marker

创建上下文保存点，以保留对话状态，方便后续恢复工作，避免重复劳动。适用于软件开发过程中的关键节点，如午餐休息前、风险重构前、一天结束时或上下文压缩前。

DevOps 0 次安装 0 次浏览 更新于 3/4/2026

导航标记技能

创建上下文标记 - 保存点，以保留对话状态，以便您以后可以恢复工作，而无需重新解释一切。

何时调用

当用户：

  • 说“保存我的进度”，“创建检查点”，“标记这一点”
  • 说“在我休息之前”，“午餐前保存”
  • 提到“风险重构即将到来”，“尝试新方法”
  • 说“一天结束”，“今天停止”
  • 在压缩上下文之前

不要调用如果：

  • 用户询问现有标记（使用列表，而不是创建）
  • 上下文是新鲜的（<5条消息交换）

执行步骤

第1步：检查导航器结构

验证 .agent/.context-markers/ 目录是否存在：

mkdir -p .agent/.context-markers

第2步：确定标记名称

如果用户提供名称：

  • 使用他们的名称（清理：小写，空格替换为连字符）
  • 示例：“Before Big Refactor”→“before-big-refactor”

如果没有提供名称：

  • 自动生成时间戳：marker-{YYYY-MM-DD}-{HHmm}
  • 示例：marker-2025-10-16-1430

询问用户可选备注：

创建标记：[name]

添加备注？（可选 - 帮助以后记住上下文）
示例：“OAuth工作，需要添加测试”

备注：

第3步：生成标记内容 [执行]

重要：您必须积极捕获ToM部分（用户意图，更正，信念状态）。

创建标记文档，结构如下：

# 上下文标记：[name]

**创建**：[YYYY-MM-DD HH:MM]
**备注**：[用户提供的备注或“未提供备注”]

---

## 对话摘要

[总结最后10-15条消息：
- 用户正在做什么
- 做出的关键决定
- 解决的问题
- 当前进度状态
]

## 加载的文档

[列出会话期间读取的文档：
- 导航器：✅ .agent/DEVELOPMENT-README.md
- 任务：TASK-XX-feature.md
- 系统：project-architecture.md
- SOPs：[如果有]
]

## 修改的文件

[列出文件的写入/编辑调用：
- src/auth/login.ts（实现OAuth）
- src/routes/auth.ts（添加端点）
- tests/auth.test.ts（创建测试）
]

## 当前焦点

[用户现在正在做什么：
- 功能：使用OAuth进行身份验证
- 阶段：集成完成，测试待定
- 阻塞：[如果有]
]

## 技术决策

[关键架构选择：
- 使用passport.js而不是next-auth（更好的控制）
- JWT令牌在httpOnly cookies中（XSS保护）
- Redis用于会话存储（可扩展性）
]

## 下一步

[恢复后要做的事情：
1. 完成OAuth流程的测试编写
2. 为登录失败添加错误处理
3. 在README中记录设置
]

## 用户意图和目标（ToM）[积极捕获]

[理论思维部分 - 捕获用户的心理状态以更好地恢复]

**⚠️ 重要：分析对话以提取这些 - 不要留空！**

**本次会议的主要目标**：
[用户最终想要实现的目标 - 不仅仅是表面任务]
- 回顾对话以查找“我想...”，“目标是...”，“我们需要...”
- 如果没有明确说明，从任务上下文中推断

**表达的偏好**：
[会话期间表达的任何偏好：
- 沟通风格（简洁/详细）
- 首选代码模式
- 想要的确认行为
]
- 查找“我更喜欢...”，“不要做...”，“总是使用...”

**更正**：
[应该持续的重要更正：
- “应该是/users而不是/user（复数约定）”
- “首选功能组件而不是类”
- “始终使用TypeScript严格模式”
]
- 查找“不，我的意思是...”，“实际上...”，“不是X，使用Y”
- 这些必须被捕获以避免重复错误

## 信念状态 [积极捕获]

[捕获相互理解状态以准确恢复]

**⚠️ 重要：从对话中推断 - 不要留空！**

**用户知道什么**：
[用户展示的知识水平：
- 熟悉Express，新到Passport
- 知道JWT，不熟悉刷新令牌
- 高级开发人员，跳过基础知识
]

**我做的假设**：
[会话期间的关键假设：
- 使用Redis进行会话（用户确认）
- Auth端点遵循/api/auth/*模式
- 使用Jest + React Testing Library进行测试
]

**不确定领域**：
[没有完全解决的问题：
- 不确定用户是否想要Google以外的社交登录
- 速率限制要求不明确
- 错误消息格式偏好未知
]

## 循环状态（如果在循环模式）

[恢复时捕获循环模式状态 - 如果不在循环模式则跳过]

**迭代**：[N]/[MAX]（例如，3/5）
**阶段**：[INIT|RESEARCH|IMPL|VERIFY|COMPLETE]
**状态哈希**：[6字符哈希以保持连续性]
**完成指标**：
- [ ] 代码提交
- [ ] 测试通过
- [ ] 文档更新
- [ ] 工单关闭
- [ ] 创建标记

**EXIT_SIGNAL**：[true/false]
**停滞计数**：[N]/[THRESHOLD]

## 知识图谱状态（v6.0.0+）

[恢复时捕获图谱状态 - 如果没有知识图谱则跳过]

**检查图谱是否存在**：
```bash
if [ -f ".agent/knowledge/graph.json" ]; then
  python3 skills/nav-graph/functions/graph_manager.py --action stats --graph-path .agent/knowledge/graph.json
fi

本会话中出现的记忆： [列出本会话中查询或创建的记忆：

  • mem-001：“Auth更改会破坏会话测试”（出现）
  • mem-002：“使用复数REST端点”（从更正中创建） ]

活跃概念： [与当前工作相关的

  • 身份验证
  • 测试
  • api ]

本会话中进行的图谱查询： [本会话的知识图谱查询：

  • “我们对身份验证了解什么？”→3个任务，1个记忆 ]

这允许恢复时重新出现相关记忆。

恢复说明

要恢复此标记： ```bash Read .agent/.context-markers/[filename] ```

或使用：/nav:markers并选择此标记


### 第4步：保存标记文件

将标记写入文件：

Write( file_path: “.agent/.context-markers/[timestamp]_[name].md”, content: [生成的标记内容] )


文件名格式：`{YYYY-MM-DD-HHmm}_{name}.md`
示例：`2025-10-16-1430_before-big-refactor.md`

### 第4.5步：验证标记创建

创建标记后，验证它是否成功写入：

```bash
# 验证文件存在且非空
if [ -f ".agent/.context-markers/[filename]" ] && [ -s ".agent/.context-markers/[filename]" ]; then
  # 计算校验和以进行验证
  checksum=$(md5 -q ".agent/.context-markers/[filename]" 2>/dev/null || md5sum ".agent/.context-markers/[filename]" | cut -d' ' -f1)

  # 记录到中央标记日志
  echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] ✅ Marker created: [filename] (checksum: $checksum)" >> .agent/.marker-log

  echo "✅ Marker verified successfully"
else
  echo "❌ Marker creation failed - file missing or empty"
  exit 1
fi

标记验证确保：

  • 文件存在于磁盘上
  • 文件有内容（非空）
  • 记录校验和以进行完整性验证
  • 创建事件记录到中央日志

第5步：确认创建

显示成功消息及验证详情：

✅ 上下文标记创建成功！

标记：[name]
文件：.agent/.context-markers/[filename]
大小：[X] KB（~[Y]个标记）
校验和：[md5-hash]
已验证：✅

此标记捕获：
- 对话的最后[N]条消息
- 您正在处理的文件
- 做出的技术决策
- 继续的下一步

以后恢复：
- 开始新会话
- 说“加载标记 [name]”
- 或使用 /nav:markers列出所有标记

记录到：.agent/.marker-log

脚本

create_marker.py：从对话分析生成标记内容

  • 输入：对话历史（来自Claude）
  • 输出：格式化的标记

常见用例

午餐休息前

用户：“保存我的进度，午餐休息”
→ 创建标记：“lunch-break-2025-10-16”
→ 捕获当前状态
→ 用户午餐后恢复：“加载我的午餐标记”

风险重构前

用户：“标记这一点，重构路由前”
→ 创建标记：“before-routing-refactor”
→ 如果重构失败，恢复标记
→ 如果重构成功，删除标记

一天结束时

用户：“一天结束检查点”
→ 创建标记：“eod-2025-10-16”
→ 备注：“OAuth完成，明天测试”
→ 第二天早上：“加载昨天的标记”

上下文压缩前

自动（通过nav-compact技能）：
→ 创建标记：“before-compact-2025-10-16-1500”
→ 压缩清除对话
→ 标记保留知识
→ 下一个会话：自动提供恢复

标记最佳实践

好的标记名称：

  • lunch-break（清楚何时/为什么）
  • before-api-refactor（指示目的）
  • feature-complete（标记里程碑）
  • eod-friday（特定时间）

不好的标记名称：

  • temp（不描述性）
  • marker1（无意义）
  • test（令人困惑）

何时创建标记：

  • ✅ 休息前（午餐，EOD）
  • ✅ 风险更改前
  • ✅ 上下文压缩前
  • ✅ 里程碑（功能完成）
  • ❌ 每条消息后（噪音）
  • ❌ 当上下文是新鲜的（<5条消息）

错误处理

标记目录缺失：

创建 .agent/.context-markers/目录...
✅ 准备保存标记

重复标记名称：

⚠️  标记“[name]”已存在

选项：
1. 覆盖（替换现有）
2. 添加时间戳（创建“[name]-v2”）
3. 选择不同的名称

您的选择[1-3]：

上下文不足：

⚠️  要保存的上下文很少（<5条消息）

标记在有重要进度要保留时效果最佳。
继续吗？[y/N]：

成功标准

当标记文件在 .agent/.context-markers/ 中创建时，标记创建成功：

  • [ ] 文件名唯一且描述性
  • [ ] 内容包含：摘要，加载的文档，修改的文件，下一步
  • [ ] 用户知道以后如何恢复标记
  • [ ] 标记是2-5k标记（全面但高效）

注释

  • 标记是 git-ignored（个人会话保存点）
  • 团队成员看不到彼此的标记
  • 标记可以随时用 /nav:markers clean 删除
  • 典型的标记大小：2-5k标记（从130k对话中压缩97.7%）

此技能提供与 /nav:marker 命令相同的功能，但使用自然语言调用。