Roo Activity Logger

Roo Activity Logger

日本語版はこちら | 中文版

概要

• 这是什么？ — 这是一个 MCP 服务，可自动记录 AI 编码助手的活动，例如命令执行和代码生成（支持 Roo Code、Cline、Claude Code 等）。
• 它能做什么？ — 它将活动历史保存为 JSON 文件，你之后可以搜索和分析这些文件。
• 我该如何使用？ — 将其添加到你的 Claude Code、Cline 或 Roo-Code 设置中，即可启用自动活动记录。

概述

Roo Activity Logger 是一个 MCP（Model Context Protocol）服务，可自动记录 AI 编码助手的开发活动 — 包括命令执行、代码生成、文件操作等。它支持 Claude Code、Cline、Roo-Code 以及其他兼容 MCP 的 AI 助手。 所有日志均以 JSON 格式保存，便于随时搜索、分析并恢复上下文。

活动记录的工作原理

flowchart TD
    A[Roo's Action] --> B[Select Activity Type]
    B --> C[Log via log_activity]
    C --> D[Provide Log Info<br>- Summary<br>- Details<br>- Intention<br>- Context]
    D --> E[Specify Save Directory]
    E --> F[Save as JSON file]

如何搜索日志并在恢复任务时还原上下文

flowchart TD
    G[Resume Task] --> H[Search with search_logs]
    H --> I[Set Search Filters<br>- Type<br>- Date Range<br>- Text]
    I --> J[Retrieve Related Activities<br>- Parent/Child<br>- Sequence<br>- Related IDs]
    J --> K[Restore Context & Resume<br>- Review Past Intentions<br>- Understand Progress]

日志条目示例

以下是以 JSON 保存的 file_operation 日志条目示例：

{
  "id": "75add15d-8d5b-4e60-b327-fde785050c86",
  "timestamp": "2025-04-10T01:58:02.905Z",
  "type": "file_operation",
  "level": "info",
  "summary": "Inserted mermaid diagram into README.md",
  "details": {
    "file": "README.md",
    "operation": "insert_content",
    "insertedLines": "mermaid code block",
    "position": "after overview section"
  },
  "intention": "To visually explain the flow of saving and retrieving activities",
  "context": "Improving documentation for Roo Activity Logger",
  "parentId": "98280366-1de1-48e0-9914-b3a3409599b4"
}

每条日志包含：

• 日志级别（debug、info、warn、error）
• 摘要
• 详细信息（任意结构化数据）
• 意图 / 目的
• 上下文信息
• 父活动 ID（用于表示层级关系）
• 序号（用于排序）
• 相关活动 ID（用于分组）

日志会：

• 保存为按日期划分的 JSON 文件
• 可按类型、级别、日期、文本等进行搜索
• 可自定义 — 你可以为不同活动指定不同的保存目录

功能

• 记录多种活动类型：

  • 命令执行（command_execution）
  • 代码生成（code_generation）
  • 文件操作（file_operation）
  • 错误（error_encountered）
  • 决策（decision_made）
  • 对话（conversation）

• 每条活动日志包含：

  • 唯一 ID
  • 时间戳
  • 活动类型
  • 摘要、详细信息、意图、上下文以及可选的元数据

用法（推荐：通过 npx）

你可以使用 npx 直接运行 Roo Activity Logger，无需克隆仓库。

将以下内容添加到你的 Cline、Roo-Code 或 Claude Code 配置中：

{
  "mcpServers": {
    "roo-activity-logger": {
      "command": "npx",
      "args": ["-y", "github:annenpolka/roo-logger"],
      "env": {},
      "disabled": false
    }
  }
}

然后，将提示词添加到你的规则文件（适用于 Cline/Roo-Code）或 CLAUDE.md（适用于 Claude Code）中，以确保进行记录，例如：

## Important

Always log activities using roo-activity-logger according to the logging rules.

## Preparation

Check the current context with `git status`.

Then, use roo-activity-logger's `search_logs` to review existing logs and identify current tasks.

Be sure to perform the logging steps.

## Logging

- Always use roo-activity-logger for all logs
- Include stack traces and execution context
- Record intention and context

---

面向开发者：本地设置

要在本地开发或自定义，请克隆仓库并构建：

# Clone the repo
git clone https://github.com/annenpolka/roo-logger.git
cd roo-logger

# Install dependencies
npm install

# Build
npm run build

使用本地构建的配置示例：

{
  "mcpServers": {
    "roo-activity-logger": {
      "command": "node",
      "args": ["/path/to/your/local/roo-logger/dist/index.js"], // adjust path accordingly
      "env": {},
      "disabled": false
    }
  }
}

注意事项

• 如果指定的目录不存在，将自动创建。

---

MCP 工具

log_activity — 记录活动

用于记录活动的工具。

基本示例

{
  "type": "command_execution",
  "summary": "Run npm command",
  "intention": "Update project dependencies",
  "context": "Preparing for new feature development",
  "logsDir": "/absolute/path/to/logs/activity"
}

参数

名称	必填	类型	描述
type	是	string	活动类型（command_execution、code_generation、file_operation、error_encountered、decision_made、conversation）
summary	是	string	活动简短摘要
intention	是	string	目的或意图
context	是	string	上下文信息
logsDir	是	string	保存目录（仅限绝对路径）
level	否	string	日志级别（debug、info、warn、error）。默认：info
details	否	object	附加详情（任意 JSON）
parentId	否	string	父活动 ID
sequence	否	number	序号
relatedIds	否	string[]	相关活动 ID

详细示例

{
  "type": "file_operation",
  "summary": "Update README file",
  "intention": "Clarify documentation and improve usability",
  "context": "Improvements based on user feedback",
  "level": "info",
  "details": {
    "file": "README.md",
    "operation": "update",
    "changedLines": 15
  },
  "logsDir": "/absolute/path/to/logs/activity",
  "sequence": 3,
  "relatedIds": ["11223344-5566-7788-99aa-bbccddeeff00"]
}

---

get_log_files — 列出已保存的日志文件

递归列出已保存的日志文件。你可以指定最大搜索深度。

基础示例

{
  "logsDir": "/absolute/path/to/logs"
}

参数

名称	必填	类型	描述
logsDir	是	string	要搜索的目录（仅限绝对路径）
limit	否	number	最多检索的文件数（默认：10）
offset	否	number	跳过的文件数（默认：0）
logFilePrefix	否	string	日志文件前缀（默认："roo-activity-"）
logFileExtension	否	string	日志文件扩展名（默认：".json"）
maxDepth	否	number	最大目录深度（默认：3）

---

search_logs — 搜索已保存的日志

使用各种筛选条件搜索已保存的日志。

基础示例

{
  "logsDir": "/absolute/path/to/logs"
}

{
  "logsDir": "/absolute/path/to/logs",
  "type": "command_execution"
}

参数

名称	必需	类型	描述
logsDir	是	string	日志目录（仅限绝对路径）
logFilePrefix	否	string	日志文件前缀（默认："roo-activity-"）
logFileExtension	否	string	日志文件扩展名（默认：".json"）
type	否	string	按活动类型过滤（command_execution、code_generation、file_operation、error_encountered、decision_made、conversation）
level	否	string	按日志级别过滤（debug、info、warn、error）
startDate	否	string	开始日期（YYYY-MM-DD）
endDate	否	string	结束日期（YYYY-MM-DD）
searchText	否	string	在摘要或详情中搜索文本
limit	否	number	最多检索的日志数量（默认：50）
offset	否	number	跳过的日志数量（默认：0）
parentId	否	string	按父活动 ID 过滤
sequenceFrom	否	number	序列号下限
sequenceTo	否	number	序列号上限
relatedId	否	string	按相关活动 ID 过滤
relatedIds	否	string[]	按任意相关活动 ID 过滤

---

许可证

MIT