⚡

ChronicleAssistantGuideSkill chronicle-assistant-guide

为使用Chronicle的AI助手提供项目无关的指导，包含搜索优先指令、最佳实践和工作流程模式，适用于所有Chronicle跟踪的项目。

AI应用 0 次安装 0 次浏览 更新于 3/3/2026

Chronicle Assistant Guide

目的: 使用Chronicle的AI助手通用指令 适用范围: 适用于所有项目（有MCP服务器或仅CLI） 优先级: 当Chronicle可用时首先加载此技能

自动激活

这项技能自动激活！（里程碑#13）

类似“我该如何使用Chronicle？”的提示会自动触发此技能。优先级低于其他技能。

**触发模式：**如何使用Chronicle，Chronicle帮助，Chronicle指南 参见：docs/HOOKS.md了解更多详情

⚡ 重要：飞行前检查清单

在开始任何与Chronicle相关的任务之前，先过一遍这个清单：

  1. ✅ 搜索第一：搜索Chronicle的历史

    • 有MCP：mcp__chronicle__search_sessions(query="相关关键词", limit=5)
    • 无MCP：chronicle search "相关关键词" --limit 5
    • 以前做过吗？
    • 关于这个功能/问题有什么上下文？
    • 什么方法失败了或成功了？

  2. ✅ 检查技能：有Chronicle技能可用于此任务吗？

    • chronicle-workflow - 会话工作流指导
    • chronicle-session-documenter - 文档到Obsidian
    • chronicle-context-retriever - 搜索过去的工作
    • chronicle-project-tracker - 路线图和里程碑

  3. ✅ 优先使用MCP而不是CLI：使用最佳可用工具

    • MCP可用？ → 快速（<10ms），结构化JSON，无子进程开销
    • 仅CLI？ → 仍然有效，稍慢（~100ms），解析格式化输出
    • 两者提供相同的数据，根据环境选择

  4. ✅ 检查路线图：查看当前的里程碑和下一步行动

    • 有MCP：mcp__chronicle__get_roadmap(days=7)
    • 无MCP：chronicle roadmap --days 7
    • 这已经是跟踪的里程碑了吗？
    • 有相关的下一步行动吗？

**为什么这很重要：**Chronicle自我实践。我们犯的每个错误都被记录下来。从历史中学习！

🎯 核心指令

1. 实施前总是先搜索Chronicle

规则（使用可用的）：

选项1：MCP（如果可用）

# 实施任何功能前：
mcp__chronicle__search_sessions(query="功能名称", limit=5)

# 调试前：
mcp__chronicle__search_sessions(query="错误或症状", limit=5)

# 用户提问时：
mcp__chronicle__search_sessions(query="主题关键词", limit=5)

选项2：CLI（总是有效）

# 实施任何功能前：
chronicle search "功能名称" --limit 5

# 调试前：
chronicle search "错误或症状" --limit 5

# 用户提问时：
chronicle search "主题关键词" --limit 5

Chronicle自身历史的真实例子：

例子1：第21次会议记录清理混乱

用户："我不敢相信第21次会议没有需要清理的地方"
❌ 没有搜索：花费时间调试，困惑为什么0%减少
✅ 有搜索：会找到第13次会议实施了记录清理
→ 结果：立即明白清理是在存储时进行的
→ 节省时间：15+分钟的调试

例子2：第30和31次会议 - 重复的MCP优化

第30次会议（10月24日）：通过从get_sessions()中排除摘要来修复MCP响应大小
第31次会议（10月24日）：同一个问题 - MCP响应过大，需要相同的修复

❌ 发生了什么：第31次会议没有搜索"MCP响应大小"
✅ 应该发生什么：搜索立即找到第30次会议的解决方案
→ 结果：可以引用第30次会议的方法而不是重新发现
→ 节省时间：10+分钟的诊断和实施

例子3：技能文档更新（第32次会议）

任务：使用MCP工具更新chronicle-session-documenter技能文档
❌ 我做了什么：没有搜索直接编辑SKILL.md
✅ 我应该做什么：先搜索"技能文档更新"
→ 结果：可能找到关于技能格式标准的内容
→ 教训：即使搜索没有找到任何东西，这个习惯可以防止未来的错误

成本计算器：

搜索时间：        <1秒
节省时间（平均）：  每次事件10-20分钟
事件至今：      3+记录案例
总共浪费的时间：     ~45+分钟本可以节省
跳过的成本：      45分钟 / 1秒 = 2,700倍回报率搜索！

**让它成为反射：**1秒的搜索总是值得的。没有例外。

2. 优先使用MCP工具，退而求其次CLI

优先顺序：

  1. ✅ Chronicle技能（最好 - 处理复杂工作流）
  2. ✅ MCP工具（最快 - 如果MCP服务器可用）
  3. ✅ CLI命令（便携 - 任何安装Chronicle的地方都有效）

为什么MCP在可用时更受青睐：

  • 速度：MCP直接查询数据库（<10ms），CLI生成子进程（~100ms）
  • 程序化：返回结构化JSON，而不是格式化文本
  • 可靠：不需要解析人类可读的输出
  • 高效：没有终端格式开销

何时使用CLI：

  • MCP服务器未配置（例如，最小安装，FreeBSD，远程系统）
  • 用户明确要求CLI输出
  • 测试CLI功能

示例：

有MCP可用：

# 快速，结构化响应
roadmap = mcp__chronicle__get_roadmap(days=7)
sessions = mcp__chronicle__search_sessions(query="storage", limit=5)
summary = mcp__chronicle__get_session_summary(session_id=16)

没有MCP（CLI备用）：

# 便携，到处都有效
chronicle roadmap --days 7
chronicle search "storage" --limit 5
chronicle session 16

决策模式：

需要Chronicle数据
├─ MCP可用？ → 使用mcp__chronicle__<tool>()
└─ MCP不可用？ → 使用chronicle <command>

📚 可用工具（MCP + CLI）

注意：以下所有操作都适用于MCP工具和CLI命令。MCP可用时优先选择速度，CLI便携。

会议和提交跟踪：

MCP方法：

# 列出会议（默认排除摘要以提高性能）
mcp__chronicle__get_sessions(limit=10, tool="claude-code", repo_path="/path", days=7)
mcp__chronicle__get_sessions(limit=10, include_summaries=True)  # 可选：包括摘要

# 获取单个会议详细信息及完整摘要
mcp__chronicle__get_session_summary(session_id=16)

# 批量检索多个会议摘要
mcp__chronicle__get_sessions_summaries(session_ids=[15, 16, 17])

# 搜索和其他查询
mcp__chronicle__search_sessions(query="MCP server", limit=10)
mcp__chronicle__get_commits(limit=20, repo_path="/path", days=7)
mcp__chronicle__search_commits(query="retry logic", limit=20)
mcp__chronicle__get_timeline(days=1, repo_path="/path")
mcp__chronicle__get_stats(days=7)

CLI等效：

# 列出和查看会议
chronicle sessions --limit 10 --tool claude-code
chronicle session 16  # 获取详细信息及摘要

# 搜索
chronicle search "MCP server" --limit 10

# 提交和时间线
chronicle show today --limit 20
chronicle timeline today

# 统计
chronicle stats --days 7

项目跟踪：

MCP方法：

mcp__chronicle__get_milestones(status="in_progress", milestone_type="feature", limit=20)
mcp__chronicle__get_milestone(milestone_id=1)
mcp__chronicle__get_next_steps(completed=False, milestone_id=1, limit=20)
mcp__chronicle__get_roadmap(days=7)
mcp__chronicle__update_milestone_status(milestone_id=1, new_status="completed")
mcp__chronicle__complete_next_step(step_id=1)

CLI等效：

# 里程碑
chronicle milestones --status in_progress
chronicle milestone 1

# 路线图和下一步行动
chronicle roadmap --days 7
chronicle next-steps --pending

# 更新
chronicle milestone-status 1 completed
chronicle complete-step 1

🔄 典型工作流

开始新任务

有MCP：

# 1. 搜索相关过去的工作
results = mcp__chronicle__search_sessions(query="authentication", limit=5)

# 2. 检查路线图
roadmap = mcp__chronicle__get_roadmap(days=7)

# 3. 如有需要，检查特定会议
if results:
    session = mcp__chronicle__get_session_summary(session_id=results[0]["id"])

# 4. 现在用完整上下文实施

有CLI：

# 1. 搜索相关过去的工作
chronicle search "authentication" --limit 5

# 2. 检查路线图
chronicle roadmap --days 7

# 3. 查看特定会议详情
chronicle session <id>

# 4. 现在用完整上下文实施

调试问题

有MCP：

# 1. 搜索错误消息或症状
results = mcp__chronicle__search_sessions(query="hang freeze stuck", limit=5)

# 2. 从相关会议获取完整上下文
if results:
    session = mcp__chronicle__get_session_summary(session_id=results[0]["id"])
    # 阅读它是如何解决的

有CLI：

# 1. 搜索错误消息或症状
chronicle search "hang freeze stuck" --limit 5

# 2. 查看相关会议
chronicle session <id>
# 阅读它是如何解决的

了解项目历史

有MCP：

# 获取概览
stats = mcp__chronicle__get_stats(days=30)
timeline = mcp__chronicle__get_timeline(days=7)

# 查找特定工作
sessions = mcp__chronicle__search_sessions(query="optimization", limit=10)

有CLI：

# 获取概览
chronicle stats --days 30
chronicle timeline week

# 查找特定工作
chronicle search "optimization" --limit 10

🚫 常见错误

❌ 不要：

  • 跳过搜索直接实施
  • MCP不可用时忽略CLI
  • 忘记检查路线图
  • 忽略搜索结果中的相关会议

✅ 要做：

  • 先搜索，后实施（MCP或CLI）
  • 使用最佳可用工具（优先MCP，CLI备用）
  • 创建新里程碑前检查路线图
  • 阅读相关会议摘要以获取上下文

🎓 Chronicle快速参考

会议组织（第6阶段）：

# 组织会议（使用CLI进行这些操作）
chronicle rename-session 32 "Feature Implementation"
chronicle tag-session 32 optimization,phase-6
chronicle link-session 32 --related-to 30,31
chronicle auto-title 31  # AI生成的标题
chronicle graph --sessions 28-32  # 可视化关系

当前状态：

  • 数据库：~/.ai-session/sessions.db（SQLite）
  • 记录：~/.ai-session/sessions/*.cleaned（基于文件）
  • 配置：~/.ai-session/config.yaml
  • MCP服务器：提供15+工具用于查询Chronicle

存储：

  • 摘要：会议结束后自动生成
  • 标题：可以手动设置或AI生成
  • 标签：用于分类的JSON数组
  • 关系：parent_session_id, related_session_ids

💡 专业提示

  1. 总是先搜索再实施 - Chronicle有100+小时的记录工作
  2. 使用批量操作 - get_sessions_summaries()一次获取多个会议
  3. 积极过滤 - 使用repo_path, days, tool过滤器缩小结果
  4. 检查会议组织 - 查找标题/标签以了解会议目的
  5. 跟随图表 - 使用chronicle graph查看会议关系
  6. 信任摘要 - 它们由AI生成，通常准确
  7. 更新路线图 - 完成下一步行动和里程碑，边工作

🔗 相关资源

  • 项目CLAUDE.md：可能有项目特定指令
  • Chronicle技能：使用chronicle-workflow, chronicle-context-retriever等
  • MCP文档：见Chronicle仓库中的MCP_SERVER.md

**记住：**此技能适用于所有使用Chronicle的项目。这里的指令是AI助手的通用最佳实践。