GhostPaw Questlog

@ghostpaw/questlog

将 Agent 任务变成任务日志，只有写下结果后才算完成。

npm install @ghostpaw/questlog

基于 SQLite 构建的 Node.js 统一任务与日历模型。

Questlog 将任务、事件、截止日期、周期性承诺和待处理事项统一到一个连贯的数据模型中，而不是拆分成多个系统。它以单个预打包文件的形式提供，运行时依赖为零，同时面向两类用户：直接编写代码的人类开发者，以及通过结构化工具接口操作的大模型 Agent。

MCP 服务

以下每种客户端配置都会启动同一个 stdio 服务：npx -y @ghostpaw/questlog mcp。 除非通过 GHOSTPAW_QUESTLOG_DB 环境变量（绝对路径）或 --db <path> 指定其他位置，否则数据存储在 ~/.ghostpaw/questlog.db。

Claude Code

claude mcp add ghostpaw-questlog -- npx -y @ghostpaw/questlog mcp

也可以作为插件使用，它还会安装技能：

/plugin marketplace add GhostPawJS/questlog
/plugin install ghostpaw-questlog@ghostpaw-questlog

Codex CLI（~/.codex/config.toml）

[mcp_servers.ghostpaw-questlog]
command = "npx"
args = ["-y", "@ghostpaw/questlog", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json） 或项目中的 .mcp.json：

{
  "mcpServers": {
    "ghostpaw-questlog": {
      "command": "npx",
      "args": ["-y", "@ghostpaw/questlog", "mcp"]
    }
  }
}

Claude Desktop 用户也可以从 最新的 GitHub 发布版本安装 server.mcpb。 项目还包含供容器主机使用的 Dockerfile： docker build -t ghostpaw-questlog . && docker run -i --rm -v questlog:/data ghostpaw-questlog。

该服务支持 MCP 2026-07-28（无状态，server/discover）以及基于 initialize 的版本 2025-11-25、2025-06-18、2025-03-26 和 2024-11-05。

CLI

npx -y @ghostpaw/questlog tools
npx -y @ghostpaw/questlog call capture_rumor '{"title":"Review release notes"}'
npx -y @ghostpaw/questlog call search_questlog '{"query":"release notes"}'

全局安装以使用 ghostpaw-questlog 二进制文件：npm i -g @ghostpaw/questlog。 ghostpaw-questlog mcp 会启动 stdio 服务。

Agent 技能

（仓库根目录中的）SKILL.md 和 skills/questlog/SKILL.md 遵循 Agent Skills 格式，并包含在 npm 包中。 将 skills/questlog/ 复制到 Agent 的技能文件夹，或打印其内容：

npx -y @ghostpaw/questlog skill > SKILL.md

安装

npm install @ghostpaw/questlog

需要 Node.js 24+（使用内置的 node:sqlite 模块）。

快速开始

import { DatabaseSync } from 'node:sqlite';
import { initQuestlogTables, read, write } from '@ghostpaw/questlog';

const db = new DatabaseSync(':memory:');
initQuestlogTables(db);

// Capture incoming work as a rumor before committing to shape
const rumor = write.captureRumor(db, {
  title: 'Legal says the vendor terms changed',
  details: 'Need to understand pricing delta and termination clause.',
});

// Settle the rumor into real work once the shape is clear
write.settleRumor(db, rumor.id, {
  settledAt: Date.now(),
  questline: {
    title: 'Vendor Renewal',
    description: 'Commercial, legal, and approval work.',
  },
  quests: [
    { title: 'Collect redlines', objective: 'Obtain the latest legal markup.' },
    { title: 'Review pricing delta', objective: 'Compare current vs. proposed cost.' },
  ],
});

// Drive the day from derived views, not from memory
const available = read.listAvailableQuests(db);
const dueSoon = read.listDueSoonQuests(db, 7 * 24 * 60 * 60 * 1000);
const results = read.searchQuestlog(db, 'vendor');

模型

七个概念，职责严格分离：

概念	用途
传闻	可能会也可能不会成为实际工作的输入信号
任务线	一组相关任务的共享上下文和汇总信息
任务	一项具体承诺，具有生命周期、时间安排和结果
可重复任务	按计划生成新任务的周期性模板
解锁项	硬性前置条件：任务 A 成功前，任务 B 一直处于阻塞状态
奖励	附加到已完成工作的描述性结果，具有领取生命周期
标签	用于筛选和报告的横向标签

统一模型意味着，一种实体类型即可涵盖所有时间意图：

表现形式	实际含义
待办事项	没有时间元数据的任务
截止日期	含有 dueAt 的任务
日历事件	含有 scheduledStartAt 和 scheduledEndAt 的任务
周期性承诺	含有 RRULE 的可重复任务
已完成的操作	通过 finishQuest 结项的任务

状态是派生出来的，而不是切换出来的。任务是否可执行，由其生命周期、时间字段和解锁关系图决定——在读取时计算，绝不存储为状态标记。

生命周期一览

Questlog 会在每次读取时计算 WoW 风格的标记。随着工作在生命周期中推进，这些标记也会变化：

 

收集

$\color{Goldenrod}{\textsf{❗}}$	法务称供应商条款已变更	rumor · open
	↓   整理为任务线和任务

任务进度

$\color{Goldenrod}{\textsf{❗}}$	审核定价差异	open · available
$\color{Gray}{\textsf{❓}}$	审核定价差异	in progress
$\color{Goldenrod}{\textsf{❓}}$	审核定价差异	done · reward unclaimed
✓	审核定价差异	done · reward claimed

其他标记

$\color{CornflowerBlue}{\textsf{❗}}$	每周站会笔记	repeatable · due
$\color{Gray}{\textsf{❗}}$	规划 Q3 路线图	open · deferred
$\color{Gray}{\textsf{❓}}$	获得财务审批	open · blocked

 

标记 ID 是语义字符串（attention.available、progress.complete 等），在读取时计算，绝不存储。markers 命名空间会将每个标记映射到其符号、颜色、标签和 CSS 类，以便在 HTML、TTY 和纯文本中保持一致的呈现。

两类受众

人类开发者

使用 read 和 write 命名空间，直接通过代码访问每项领域操作：

import { read, write } from '@ghostpaw/questlog';

write.createQuest(db, { title: 'Ship release notes', objective: 'Draft and publish.' });
write.startQuest(db, questId);
write.finishQuest(db, questId, 'Published to blog and changelog.');

const blocked = read.listBlockedQuests(db);
const overdue = read.listOverdueQuests(db);

请参阅 HUMAN.md，了解面向人类的完整指南和示例。

LLM Agent

使用 tools、skills 和 soul 命名空间，访问专为降低 LLM 认知负担而设计的结构化运行时接口：

import { tools, skills, soul } from '@ghostpaw/questlog';

// 12 intent-shaped tools with JSON Schema inputs and structured results
const allTools = tools.questlogTools;
const searchTool = tools.getQuestlogToolByName('search_questlog')!;
const result = searchTool.handler(db, { query: 'vendor', mode: 'browse' });

// 25 reusable workflow skills for common multi-step scenarios
const allSkills = skills.questlogSkills;

// Thinking foundation for system prompts
const prompt = soul.renderQuestlogSoulPromptFoundation();

每个工具都会返回一个带有区分标记的结果，其中包含 outcome: 'success' | 'no_op' | 'needs_clarification' | 'error'、结构化实体、后续步骤提示以及可执行的恢复建议。无需解析抛出的异常，也不会遇到含糊不清的文字说明。

请参阅 LLM.md，了解涵盖 soul、工具和技能的完整 AI 指南。

工具

十二个工具围绕操作意图设计，而非原始存储操作：

工具	功能
search_questlog	跨实体全文搜索
review_questlog	筛选列表视图（可用、已逾期、即将到期等）
inspect_questlog_item	详细检查任意单个实体
capture_rumor	记录新收到的工作，暂不确定其形式
shape_work	创建任务、任务线，并将传闻整理成结构化内容
plan_quest	设置时间安排：截止日期、延后日期、计划时间段
run_quest	开始、完成、放弃任务，记录投入时间
organize_work	在任务线之间移动任务，管理任务线生命周期
manage_repeatable	创建和维护重复任务模板
tag_work	为任务和重复任务添加分类标签
reward_work	附加、更新、领取或移除奖励
retire_work	软删除或归档不应再显示在活动界面中的内容

每个工具都会导出运行时元数据——名称、描述、JSON Schema、输入说明、副作用级别——因此 Agent 框架无需阅读文档即可接入这些工具。

run_quest 工具会拒绝开始尚未满足解锁前置条件的任务，并返回阻塞任务及检查提示。设置 force: true 可在收到警告后仍然开始。库函数 startQuest 则仍允许直接开始。

主要特性

• 零运行时依赖。 仅使用 node:sqlite（内置于 Node 24+）。
• 单一预打包文件。 dist/ 中只有一个 ESM 和一个 CJS 入口。无子路径导出，不进行代码拆分。
• 纯 SQLite 存储。 使用 FTS5 全文搜索、通过 CHECK 约束状态转换、由触发器维护索引。自行提供 DatabaseSync 实例。
• 派生状态。 可用性、阻塞、延后、逾期和标记都在读取时根据字段和关系计算，绝不作为标志存储。
• 按意图设计的写入。 captureRumor、settleRumor、startQuest、finishQuest、abandonQuest——描述实际发生情况的操作，而非通用 CRUD。
• RFC 5545 重复规则。 重复工作的标准 RRULE 字符串。无自定义重复格式。
• WoW 风格标记。 语义化标记 ID（attention.available、progress.complete 等）在每次读取时计算，可渲染到任何渠道。
• 测试与模块并置。 每个非类型模块都有一个并置的 .test.ts 文件。文档所述行为均有可执行测试覆盖。

性能

在 Node 24.14.0、Linux、Intel Xeon（共享云 vCPU）上，使用文件数据库中的 10,000 个任务，通过 npm run bench 测得：

操作	p50	p95
search_questlog（工具）	0.06 ms	0.07 ms
MCP tools/call 搜索（含 stdio 分帧）	0.07 ms	0.08 ms
read.searchQuestlog，匹配一个任务	0.07 ms	0.08 ms
read.searchQuestlog，匹配全部 10,000 个任务	26.6 ms	41.9 ms
write.createQuest	0.22 ms	0.69 ms

库的搜索会返回每个匹配项及其高亮片段，因此，匹配整个日志的查询需要耗时构建所有这些行。冷启动（从进程启动到首次响应的中位数）方面，--version 和 MCP 服务约需 30 ms。

包接口

import {
  initQuestlogTables,  // schema setup
  read,                // all query functions
  write,               // all mutation functions
  tools,               // LLM tool definitions + registry
  skills,              // LLM workflow skills + registry
  soul,                // thinking foundation for system prompts
  markers,             // marker derivation and lookup
} from '@ghostpaw/questlog';

所有领域类型也可通过根入口供 TypeScript 使用者使用：

import type {
  QuestlogDb,
  QuestState,
  QuestDetail,
  CreateQuestInput,
  QuestlogSearchResult,
  QuestlogToolDefinition,
  QuestlogSkill,
  QuestlogSoul,
} from '@ghostpaw/questlog';

文档

文档	适用对象
HUMAN.md	使用底层 read/write API 的开发者
LLM.md	在大模型系统中接入工具、技能和灵魂的 Agent 构建者
docs/README.md	架构概览：模型、不变量、生命周期、标记
docs/entities/	各实体的手册，包含精确的公开 API 列表

开发

npm install
npm test            # node:test runner
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # ESM + CJS + declarations via tsup

仓库通过 .nvmrc / .node-version / .tool-versions / mise.toml / Volta 固定使用 Node 24.14.0。可使用你喜欢的版本管理器。

支持

如果这个软件包对你的项目有帮助，可以考虑赞助其维护工作：

---

Anonyfox • MIT License