任务日志MCP
小 stdio MCP服务器,用于跨编码会话的工作优先连续性。
如果没有连续性层,会话恢复通常会变成临时回顾工作:告诉代理写一个摘要,记住哪个 .md 它进入的文件,在下一个会话中再次找到该文件,要求代理重新读取它,然后希望它从过时的笔记和原始日志中重建正确的范围。
Tasklog将其转化为可重复的工作流。它为一个编码工作区提供了一个轻量级的本地系统,用于跟踪当前工作、会话切换、下一步以及需要快速恢复时重要的一小部分工件。
它能快速回答一组狭窄的问题:
- 我现在在做什么?
- 哪些工作仍然开放?
- 上次会议有什么变化?
- 计划、规格和提醒应该放在哪里?
- 如果一项工作已经结束,正确的重新进入简报是什么?
Tasklog是故意先工作,而不是先日志,也不是一般的内存层。
为什么它存在
大多数人工智能辅助的工作流程仍然手动处理连续性。
在实践中,这通常意味着以下内容的混合:
- 要求代理将一次性摘要转储到markdown文件中
- 记住文件写在哪里
- 重新读取长日志,因为没有清晰地捕获工作边界
- 中断后从头开始重建下一步
然后,大多数会话日志记录工具都会走向两个极端之一:
- 一个按时间顺序排列的原始笔记本,重读成本很高
- 试图记住一切的广泛记忆系统
Tasklog比两者都窄,并试图使连续性成为正常工作循环的一部分,而不是额外的回顾杂务。
work是连续性的主要单位log仅用于会话切换workdocs/保存耐用的人脸文物- 封闭式工作
summary.md存在只是为了加速重返工作岗位
目标是在不将Tasklog转换为通用内存层的情况下,使会话恢复成本低廉。
快速开始
与一起跑步 npx:```bash
npx -y tasklog-mcp@0.3.0
或全局安装:```bash
npm install -g tasklog-mcp
tasklog-mcp
将其添加到Codex:```bash
codex mcp add tasklog -- npx -y tasklog-mcp@0.3.0
默认情况下,Tasklog使用当前工作目录作为 `project_root`.换言之:```bash
npx -y tasklog-mcp@0.3.0 --project-root /path/to/workspace
真实工作流用例
当会话快速移动且连续性经常中断时,任务日志最有用。
常见案例:
- 您回到工作区,希望代理在选择下一个任务之前列出仍打开的内容
- 你想按以下方式对未完成的工作进行分类
impact或tag,例如找到机会critical项目优先 - 您突然退出了一个会话,需要清理过时的会话
active恢复前的工作项 - 您大致知道自己在做什么,但希望代理在不重新读取长日志的情况下恢复范围、下一步和工件
- 你完成了一项有风险或昂贵的更改,并希望稍后为这项工作提供一份狭义的重新入门简报
这使得Tasklog更适合快速移动的单人工作、代理辅助迭代和“氛围编码”风格的工作流程,而不是广泛的知识管理。
简历工作流程```mermaid
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`
1. 如果需要,使用 `list_works(status="open")` 和 `resume_work`
1. 呼叫 `read_work_context`
1. 根据意图使用工作文档和日志
推荐工具选择:
- 开始新的努力: `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`:重建的答案是否逐字段匹配地面真实值
完整示例摘要:
|简历路径|它模拟什么|覆盖率|结构化答案准确性|重新输入上下文表面|
| --- | --- | ---: | ---: | ---: |
|无连续性|仅代码库/工作区扫描| `32.43%` | `n/a` | `38,638` 字节|
|Markdown笔记|自由形式笔记重读| `63.06%` | `n/a` | `942,822` 字节|
|原始JSON状态|直接状态文件重建| **`100%`** | **`100%`** | `1,314,527` 字节|
| **任务日志** | **工作第一MCP再入流** | **`100%`** | **`100%`** | **`79,781` 字节** |
在整个示例中,Tasklog在覆盖率和结构化答案准确性方面与原始JSON路径相匹配,同时使用约 `91.54%` 比markdown注释更少的上下文 `93.93%` 与直接的原始状态重建相比,上下文更少。
对于实际的重新输入,Tasklog是在整个样本中仍然保持完全可回答的最低上下文路径。
此基准衡量的是重新进入时暴露的有效载荷,而不是端到端模型令牌的总使用量。它使用真实的工作空间和真实的工作项,但它仍然不是一项盲目的人类研究。
要重新运行,请执行以下操作:```bash
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 idtitleslugstatus:active,blocked,或done- 可选的
impact:low,medium,high,或critical start_dirscope_paths- 可选的
summary - 可选的
tags created_atupdated_at
impact 是工作元数据。它有助于决定一个封闭的作品是否值得一个规范的重新进入简报。它不是一个单独的内存对象。
范围模型
Tasklog将整体工作范围与一次实施过程的较窄范围分开:
- 工作范围在
start_dir和scope_paths - 计划范围存在
target_paths里面plan.md
一 project_root 可以是:
- 单一回购
- 或包含多个存储库的父工作区
Tasklog每次跟踪一个工作区根,而不是一次跟踪一个git repo。
存储布局```text
/
.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`
这些是工作流规则、模式和示例的详细参考。
## 本地开发```bash
cd tasklog-mcp
npm install
npm test
npm run build
针对特定项目根运行:```bash
node dist/index.js --project-root /Users/Lab/Desktop/WebWay/CodeWebway
或者在开发过程中:```bash
npm run dev -- --project-root /Users/Lab/Desktop/WebWay/CodeWebway
如果 --project-root 如果省略,服务器将使用当前工作目录。
MCP配置
通用stdio配置:json
{
"mcpServers": {
"tasklog": {
"type": "stdio",
"command": "npx",
"args": ["-y", "tasklog-mcp@0.3.0"],
"env": {}
}
}
}
如果你想明确地指向其他地方,请添加 --project-root 到 args.
仍然支持传统兼容性环境变量:
LOGBOOK_PROJECT_ROOTLOGBOOK_JSON_FILELOGBOOK_MARKDOWN_FILE
Claude Desktop和Cursor可以使用相同的stdio命令模式。如果为每个客户端保留单独的配置文件,请固定相同的配置文件 tasklog-mcp@0.3.0 包版本也在那里,所以Codex和Claude解决了同一个版本。
