Tasklog MCP

任务日志MCP

小 stdio MCP服务器，用于跨编码会话的工作优先连续性。

如果没有连续性层，会话恢复通常会变成临时回顾工作：告诉代理写一个摘要，记住哪个 .md 它进入的文件，在下一个会话中再次找到该文件，要求代理重新读取它，然后希望它从过时的笔记和原始日志中重建正确的范围。

Tasklog将其转化为可重复的工作流。它为一个编码工作区提供了一个轻量级的本地系统，用于跟踪当前工作、会话切换、下一步以及需要快速恢复时重要的一小部分工件。

它能快速回答一组狭窄的问题：

• 我现在在做什么？
• 哪些工作仍然开放？
• 上次会议有什么变化？
• 计划、规格和提醒应该放在哪里？
• 如果一项工作已经结束，正确的重新进入简报是什么？

Tasklog是故意先工作，而不是先日志，也不是一般的内存层。

为什么它存在

大多数人工智能辅助的工作流程仍然手动处理连续性。

在实践中，这通常意味着以下内容的混合：

• 要求代理将一次性摘要转储到markdown文件中
• 记住文件写在哪里
• 重新读取长日志，因为没有清晰地捕获工作边界
• 中断后从头开始重建下一步

然后，大多数会话日志记录工具都会走向两个极端之一：

• 一个按时间顺序排列的原始笔记本，重读成本很高
• 试图记住一切的广泛记忆系统

Tasklog比两者都窄，并试图使连续性成为正常工作循环的一部分，而不是额外的回顾杂务。

• work 是连续性的主要单位
• log 仅用于会话切换
• workdocs/ 保存耐用的人脸文物
• 封闭式工作 summary.md 存在只是为了加速重返工作岗位

目标是在不将Tasklog转换为通用内存层的情况下，使会话恢复成本低廉。

快速开始

与一起跑步 npx:

npx -y tasklog-mcp@0.3.0

或全局安装：

npm install -g tasklog-mcp
tasklog-mcp

将其添加到Codex：

codex mcp add tasklog -- npx -y tasklog-mcp@0.3.0

默认情况下，Tasklog使用当前工作目录作为 project_root.换言之：

npx -y tasklog-mcp@0.3.0 --project-root /path/to/workspace

真实工作流用例

当会话快速移动且连续性经常中断时，任务日志最有用。

常见案例：

• 您回到工作区，希望代理在选择下一个任务之前列出仍打开的内容
• 你想按以下方式对未完成的工作进行分类 impact 或 tag，例如找到机会 critical 项目优先
• 您突然退出了一个会话，需要清理过时的会话 active 恢复前的工作项
• 您大致知道自己在做什么，但希望代理在不重新读取长日志的情况下恢复范围、下一步和工件
• 你完成了一项有风险或昂贵的更改，并希望稍后为这项工作提供一份狭义的重新入门简报

这使得Tasklog更适合快速移动的单人工作、代理辅助迭代和“氛围编码”风格的工作流程，而不是广泛的知识管理。

简历工作流程

flowchart LR
    A[Start a new session] --> B[See what is still open]
    B --> C[Choose the right work]
    C --> D[Load scope, notes, and next steps]
    D --> E[Do the work]
    E --> F[Leave a clean handoff]

这是Tasklog试图降低成本的典型简历流程：恢复正确的工作，用最少的上下文重新输入，然后为下一个会话留下干净的交接。

此流程背后的典型工具：

• get_active_context
• list_works 或 resume_work
• read_work_context
• append_work_note, append_session_log, set_work_status

心理模型

Tasklog将连续性分为两层：

• 机器面对状态 .tasklog/
• 面向人的工作工件 workdocs/

主要对象是：

• work：一次连贯的努力
• log：一个会话切换条目
• design.md：目标、约束、权衡
• plan.md：执行顺序和目标路径
• spec.md：确切的行为或合同细节
• notes.md：轻量级提醒
• summary.md：所选封闭式工作的可选重返简报

在实践中：

• 活动工作由最近的日志和当前的工作文档驱动
• 小型封闭式工作可以保持原始状态
• 选定的已关闭工作可以先成为摘要

典型流量

1. 从...开始 get_active_context
2. 如果需要，使用 list_works(status="open") 和 resume_work
3. 呼叫 read_work_context
4. 根据意图使用工作文档和日志

推荐工具选择：

• 开始新的努力： start_work
• 继续现有的努力： resume_work
• 捕获方法： create_design_doc
• 捕获实施步骤： create_plan_doc
• 捕捉精确规则： create_spec_doc
• 记下一些事情： append_work_note
• 记录会话切换： append_session_log

基准

Tasklog的工作流声明得到了中场景驱动的重返基准的支持 scripts/benchmark-reentry.ts.

在一个真实的多仓库工作空间上进行测量，当前示例涵盖 15 跨活动工作发现以及活动和已完成工作重新输入的工作流场景。

该基准比较了四种恢复路径：

• no continuity：只检查工作区/代码库上下文和git状态，不检查 .tasklog 或 workdocs/
• markdown notebook scan：直接重新阅读会话笔记本/日志标记
• raw JSON state scan：阅读 .tasklog/active-context.json, .tasklog/works.json，以及 .tasklog/session-log.json 直接重建答案，无需更高级别的MCP流
• Tasklog path：使用工作优先的MCP工具，如 get_active_context, list_works, resume_work，以及 read_work_context

基准分为两个等级：

• coverage：有效载荷是否包含回答真实简历问题所需的证据
• structured-answer accuracy：重建的答案是否逐字段匹配地面真实值

完整示例摘要：

在整个示例中，Tasklog在覆盖率和结构化答案准确性方面与原始JSON路径相匹配，同时使用约 91.54% 比markdown注释更少的上下文 93.93% 与直接的原始状态重建相比，上下文更少。

对于实际的重新输入，Tasklog是在整个样本中仍然保持完全可回答的最低上下文路径。

此基准衡量的是重新进入时暴露的有效载荷，而不是端到端模型令牌的总使用量。它使用真实的工作空间和真实的工作项，但它仍然不是一项盲目的人类研究。

要重新运行，请执行以下操作：

npm run bench:reentry -- --project-root /path/to/workspace --manifest docs/benchmark-candidates.json

您仍然可以使用一个或多个 --work-id 当你想要更窄的支票时，会打上标记。

封闭式工作总结

可以附加任务日志 summary.md 选择已关闭的工作项。

本摘要有意缩小范围：

• 这是该作品的经典重返大气层简报
• 它不是任意项目事实的通用检索层
• 它不会取代项目文档、代码搜索或架构工具
• 它不会在工作项之外创建自由浮动的内存对象

对于 closed/consolidated 工作：

• read_work_context 是摘要优先，路径优先
• summary.md 是默认入口点
• include_summary=true 仅在需要时内联摘要正文
• include_recent_logs=true 仅在需要时加载原始日志证据

默认情况下，合并工作不会内联摘要正文或最近的日志。

工作记录

每 work 有：

• work_id：6个字符的基62 id
• title
• slug
• status: active, blocked，或 done
• 可选的 impact: low, medium, high，或 critical
• start_dir
• scope_paths
• 可选的 summary
• 可选的 tags
• created_at
• updated_at

impact 是工作元数据。它有助于决定一个封闭的作品是否值得一个规范的重新进入简报。它不是一个单独的内存对象。

范围模型

Tasklog将整体工作范围与一次实施过程的较窄范围分开：

• 工作范围在 start_dir 和 scope_paths
• 计划范围存在 target_paths 里面 plan.md

一 project_root 可以是：

• 单一回购
• 或包含多个存储库的父工作区

Tasklog每次跟踪一个工作区根，而不是一次跟踪一个git repo。

存储布局

/
  .tasklog/
    works.json
    active-context.json
    session-log.json
    session-log.md
  workdocs/
    -/
      design.md
      plan.md
      spec.md
      summary.md
      notes.md

权威来源：

• .tasklog/works.json：机器面向工作状态
• .tasklog/session-log.json：面向机器的会话日志
• workdocs/：面向人类的工作工件
• active_work：会话提示，不是真相的来源

兼容性说明：

• 规范日志写入被镜像到旧版 .ai-history.json
• 规范的markdown日志写入被镜像到旧版 .ai-session-log.md
• 如果规范JSON还不存在，Tasklog仍然可以读取旧版 .ai-history.json

刀具表面

工作发现：

• get_active_context
• list_works
• start_work
• resume_work
• set_work_impact
• set_work_status
• read_work_context

工件创建：

• create_design_doc
• create_plan_doc
• create_spec_doc
• create_summary_doc
• append_work_note

日志：

• get_recent_logs
• append_session_log
• update_log_status
• amend_log_metadata

不推荐的兼容性：

• get_open_threads

更喜欢 list_works(status="open") 新的流量。

界限

任务日志不是：

• 完整的日记
• 通用存储器MCP
• 存放任意事实的笔记库
• 项目文档、代码搜索或架构工具的替代品
• 保证每个中断的会话都会留下完美的活动工作状态

设计目标：

• 保持小
• 保持明确
• 保持低阻力
• 使其易于切换
• 保持苗条

电流摩擦

任务日志故意很小，所以一些清理仍然是显式的。

• 如果会话突然结束，工作项仍可能被标记 active 直到下一个会话关闭或更新它
• 这通常很便宜 list_works 加 set_work_status，但今天仍然是手动状态清理
• 如果您的工作流需要自动长期内存、语义检索或项目范围内的推理，请将Tasklog与文档、代码搜索和架构工具配对，而不是将Tasklog扩展到其范围之外

可靠性注意事项

• 写入在一个服务器进程内序列化
• 使用临时文件替换，每个文件的写入都是原子性的
• 多文件操作不是事务原子性的
• 所有机器和文档路径都保留在所选路径内 project_root
• 指向同一根的多个服务器进程不是受支持的协调模式

资源

MCP服务器公开：

• tasklog://usage
• tasklog://schema
• tasklog://examples

这些是工作流规则、模式和示例的详细参考。

本地开发

cd tasklog-mcp
npm install
npm test
npm run build

针对特定项目根运行：

node dist/index.js --project-root /Users/Lab/Desktop/WebWay/CodeWebway

或者在开发过程中：

npm run dev -- --project-root /Users/Lab/Desktop/WebWay/CodeWebway

如果 --project-root 如果省略，服务器将使用当前工作目录。

MCP配置

通用stdio配置：

{
  "mcpServers": {
    "tasklog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tasklog-mcp@0.3.0"],
      "env": {}
    }
  }
}

如果你想明确地指向其他地方，请添加 --project-root 到 args.

仍然支持传统兼容性环境变量：

• LOGBOOK_PROJECT_ROOT
• LOGBOOK_JSON_FILE
• LOGBOOK_MARKDOWN_FILE

Claude Desktop和Cursor可以使用相同的stdio命令模式。如果为每个客户端保留单独的配置文件，请固定相同的配置文件 tasklog-mcp@0.3.0 包版本也在那里，所以Codex和Claude解决了同一个版本。