使用说明

人工智能会话跟踪器mcp

MCP服务器，用于跟踪AI编码会话和衡量开发人员的生产力。

📖 阅读博客文章： 我停止了对人工智能生产力的争论，开始衡量它

🧭 意图

人工智能生产力的争论停留在意见上。此工具存在的原因是 如果你不能衡量它，你就无法改进它。

大多数团队采用人工智能编码工具，并希望最好的结果。希望不是一种策略。测量是。你跟踪的每个会话都会产生数据——节省的时间、摩擦点、有效性评级——这些数据会形成对人工智能如何真正改变你的工作流程的真正洞察。

设计遵循人工智能意图转移原理：使人工智能系统能够识别人类意图的八项原则。核心思想很简单-- 意图引领，测量紧随其后。 你声明你想要完成什么，人工智能会对其采取行动，工具会捕捉到实际发生的事情。意图和结果之间的差距是改进的所在。

这些原则塑造了发展的每个阶段：项目计划记录每个阶段的目标和风险状况，日记账条目记录了探索的每个设计备选方案及其被拒绝的原因，第4阶段删除内置S3备份是一种明确的意图重新调整——将数据收集与数据存储分离。

这不是为了证明人工智能是有效的。这是关于了解 多么好 它适用于你的工作流程，并随着时间的推移变得更好。

✨ 特性

📊 会话跟踪 --使用完整上下文启动、记录交互和结束编码会话
📈 投资回报率指标 --计算节省的时间、成本节约和生产率乘数
🎯 有效性评级 --对AI响应进行1-5级评分，以跟踪随时间推移的质量
🔍 代码度量 --分析修改代码的复杂性和文档质量
🌐 Web仪表板 --通过FastAPI+htmx进行实时图表和分析
🤖 代理文件 --VS Code的预配置聊天模式和指令文件

📦 安装

来自Git仓库

# Install directly from GitHub
pip install git+https://github.com/mgrandau/ai-session-tracker-mcp.git

# Or with pipx for isolated installation
pipx install git+https://github.com/mgrandau/ai-session-tracker-mcp.git

配置VS代码

安装后，在项目目录中运行install命令：

# Navigate to your project
cd /path/to/your/project

# Install MCP configuration and agent files
ai-session-tracker install

这将创建：

.vscode/mcp.json --MCP服务器配置
.github/instructions/ --AI指令文件
.github/agents/ --VS Code自定义代理定义

完整MCP配置模板

对于手动配置或启用所有功能，请在中使用此模板 .vscode/mcp.json:

{
  "servers": {
    "ai-session-tracker": {
      "command": "ai-session-tracker",
      "args": [
        "server",
        "--dashboard-host", "127.0.0.1",
        "--dashboard-port", "8050"
      ]
    }
  }
}

可用的服务器参数：

参数	描述	默认值
`--dashboard-host`	嵌入式web仪表板主机	（残疾）
`--dashboard-port`	嵌入式web仪表板端口	（残疾）
`--max-session-duration-hours`	自动关闭上限会话结束前的最长小时数	`4.0`

环境变量：

通过配置 env 在你的 mcp.json 或系统环境：

变量	描述	默认值
`AI_MAX_SESSION_DURATION_HOURS`	最大会话持续时间（小时）	`4.0`
`AI_OUTPUT_DIR`	将会话数据重定向到自定义目录	`.ai_sessions`

有关备份和同步模式（云同步、S3、rsync、git），请参阅备份和同步指南.

环境变量示例：

{
  "servers": {
    "ai-session-tracker": {
      "command": "ai-session-tracker",
      "args": ["server"],
      "env": {
        "AI_MAX_SESSION_DURATION_HOURS": "8.0",
        "AI_OUTPUT_DIR": "/home/jsmith/OneDrive/ai-metrics/my-project"
      }
    }
  }
}

💡 提示： 这 --max-session-duration-hours 该设置可防止隔夜会议扭曲指标。当会话超过此限制时，其end_time的上限为 start_time + max_duration 而不是实际的关闭时间。

💡 提示： 启用 --dashboard-host 和 --dashboard-port 要获取实时网络仪表板，请访问 http://127.0.0.1:8050 当MCP服务器运行时。

🚀 快速开始

1.开始会话

使用“会话跟踪代理”聊天模式时，MCP工具可在VS Code Copilot Chat中使用（请参阅启用代理模式).

启用后，只需描述您的任务，代理就会自动处理会话跟踪：

Implement user authentication

2.日志交互

当您工作时，代理会自动记录交互。每个提示/响应对都会与上下文一起捕获。

3.结束会话

当你完成时，代理会以适当的结果结束会话。您还可以明确地请求：

End the session as success

4.查看仪表板

# Open the web dashboard
ai-session-tracker dashboard

# Then visit http://localhost:8050

🤖 启用代理模式

安装后，启用会话跟踪代理以启动自动会话跟踪：

GitHub副本（VS代码和Visual Studio）

打开Copilot聊天
单击代理下拉列表（聊天面板顶部）
选择 “会话跟踪代理”

您的聊天会话仍将保持代理模式。

Codex插件（仅VS代码）

重要提示： Codex不会像VS Code那样自动启动MCP服务器或加载代理指令 mcp.json。您需要在每次对话开始时告诉Codex采用会话跟踪代理。

第一步： 启用IDE上下文访问：

在Codex聊天输入中，确保 “包含IDE上下文” 已转动开
寻找a 蓝色图标 --这证实了Codex可以看到您的IDE上下文（文件、选择、工作区结构）

如果不启用IDE上下文，代理将无法访问您的工作区，会话跟踪可能无法正常运行。

第二步： 在谈话开始时，告诉Codex使用代理：

Use the Session Tracked Agent as the default for the rest of the conversation.

这使得Codex：

启动MCP服务器（创建 .ai_sessions/ 如果它不存在）
按照中的会话跟踪说明进行操作 .github/instructions/
自动跟踪会话以进行所有后续交互

⚠️ 没有这一步，Codex不会知道启动MCP服务器，你会得到“sessions.json不存在”这样的错误。这是Codex最常见的设置问题。

🛠️ 命令行命令

# Start MCP server (for VS Code integration)
ai-session-tracker server

# Start MCP server with embedded dashboard
ai-session-tracker server --dashboard-host 0.0.0.0 --dashboard-port 8050

# Start MCP server with custom max session duration (8 hours)
ai-session-tracker server --max-session-duration-hours 8.0

# Start standalone web dashboard
ai-session-tracker dashboard [--host HOST] [--port PORT]

# Generate text report to stdout
ai-session-tracker report

# Install MCP config and agent files to current project
ai-session-tracker install

# Install as a system service (auto-start on login)
ai-session-tracker install --service

📝 会话跟踪CLI

无需MCP服务器即可从命令行跟踪会话：

# Start a session - returns session_id
ai-session-tracker start \
  --name "Implement login feature" \
  --type code_generation \
  --model claude-opus-4-20250514 \
  --mins 60 \
  --source manual

# Log an interaction
ai-session-tracker log \
  --session-id "SESSION_ID" \
  --prompt "Create login form component" \
  --summary "Generated React component with validation" \
  --rating 5

# Flag an issue
ai-session-tracker flag \
  --session-id "SESSION_ID" \
  --type hallucination \
  --desc "AI referenced non-existent library" \
  --severity high

# List active sessions
ai-session-tracker active

# End a session
ai-session-tracker end \
  --session-id "SESSION_ID" \
  --outcome success \
  --notes "Feature completed successfully"

命令参考

命令	描述	必填参数
`start`	开始新会话	`--name`, `--type`, `--model`, `--mins`, `--source`
`log`	记录交互	`--session-id`, `--prompt`, `--summary`, `--rating`
`end`	结束会话	`--session-id`, `--outcome`
`flag`	标记一个问题	`--session-id`, `--type`, `--desc`, `--severity`
`active`	列出活动会话	（无）

任务类型

code_generation, debugging, refactoring, testing, documentation, analysis, architecture_planning, human_review

输出格式

所有命令支持 --json 机器可读输出标志：

ai-session-tracker start --name "Test" --type testing --model gpt-4 --mins 30 --source manual --json
# Output: {"success": true, "message": "Session started", "data": {"session_id": "..."}}

执行上下文隔离

会话跟踪 执行上下文 (foreground 或 background)为了实现独立操作：

MCP会话 以...身份运行 foreground --通过VS Code Copilot聊天进行交互式使用
CLI会话 以...身份运行 background --批处理脚本、CI管道或后台进程

为什么这很重要： 当你开始一个新的会话时，任何以前的会话 活跃的 会议与相同执行上下文随结果自动关闭 partial不同上下文的会话不受影响。

这使您能够：

通过CLI运行后台批处理，同时交互式地使用MCP
避免在开始交互式工作时意外关闭自动化会话
将前景和背景指标分开

🔄 后台服务

将MCP服务器作为系统服务安装，以便在登录时自动运行：

# Install as service (creates systemd user service on Linux, launchd agent on macOS, Task Scheduler on Windows)
ai-session-tracker install --service

# Manage the service
ai-session-tracker service start     # Start the service
ai-session-tracker service stop      # Stop the service
ai-session-tracker service status    # Check service status
ai-session-tracker service uninstall # Remove the service

平台支持

平台	服务类型	位置
Linux	systemd用户服务	`~/.config/systemd/user/ai-session-tracker.service`
macOS	启动用户代理	`~/Library/LaunchAgents/com.ai-session-tracker.mcp.plist`
Windows	任务计划程序	`AISessionTracker` 预定任务

🔧 MCP工具

工具	说明
`start_ai_session`	开始新的跟踪会话
`log_ai_interaction`	记录提示/响应交换
`end_ai_session`	完成会议并取得成果
`flag_ai_issue`	报告问题以供分析
`log_code_metrics`	分析修改后的代码质量
`get_ai_observability`	检索分析报告
`get_active_sessions`	列出尚未结束的会话

📁 项目结构

ai-session-tracker-mcp/
├── src/ai_session_tracker_mcp/    # Main package
│   ├── server.py                  # MCP server implementation
│   ├── models.py                  # Domain models
│   ├── storage.py                 # JSON persistence
│   ├── statistics.py              # Analytics engine
│   ├── presenters.py              # Dashboard view models
│   ├── cli.py                     # Command-line interface
│   ├── web/                       # FastAPI dashboard
│   └── agent_files/               # VS Code integration files
├── tests/                         # Test suite (564 tests)
└── utils/                         # Development utilities

📚 架构文档

每个组件的详细AI可读架构文档：

组件	文档
主包装	src/ai_session_tracker_mcp/README.md
测试套件	测试/README.md

🧪 发展

设置

# Clone repository
git clone https://github.com/mgrandau/ai-session-tracker-mcp.git
cd ai-session-tracker-mcp

# Install with PDM
pdm install

# Run tests
pdm run test

# Run all checks (lint, typecheck, security, test-cov)
pdm run check-all

可用脚本

命令	描述
`pdm run test`	运行pytest
`pdm run test-cov`	运行覆盖率测试
`pdm run lint`	运行褶边过梁
`pdm run format`	带褶皱的格式代码
`pdm run typecheck`	运行mypy类型检查器
`pdm run security`	运行土匪安全扫描
`pdm run check-all`	运行所有检查

📊 数据存储

会话数据存储在 .ai_sessions/ 在项目根目录中（或任何地方 AI_OUTPUT_DIR 分数）：

.ai_sessions/
├── sessions.json      # Session metadata
├── interactions.json  # Logged interactions
├── issues.json        # Flagged issues
└── charts/            # Generated chart images

有关备份、同步和团队聚合模式（云同步、NAS、git、S3、rsync），请参阅备份和同步指南.

🔒 稳定性

MCP工具 — 🔒 ABI冻结，突破性更改需要大幅版本升级
命令行命令 — 🔒 ABI冷冻
核心课程 — 🔒 ABI冻结（会话、交互、问题等）
内部API — ⚠️ 可能会发生变化（演示者、ViewModel）

📄 许可证

MIT许可证——见许可证了解详情。

💬 社区

💬 加入Discord社区

🤝 贡献

欢迎投稿！请确保：

所有测试均通过(pdm run test)
代码已格式化(pdm run format)
无棉绒错误(pdm run lint)
类型检查通过(pdm run typecheck)