Lister：为智能体工作流打造的轻量级列表管理工具

Lister 是一个专为 OpenClaw 智能体工作流设计的原生插件，提供类型安全的列表管理能力，支持任务、习惯、购物、健康日志等多种预定义类型，并允许自定义列表结构。

在智能体（Agent）工作流日益普及的今天，开发者们面临一个共同挑战：如何高效地管理结构化数据？传统的数据库方案过于沉重，而简单的文本文件又缺乏类型安全和查询能力。Lister 项目正是为了解决这一痛点而生——它提供了一个简单、快速、且带有明确观点的列表管理方案，专为 agentic 工作流优化。

Lister 是一个原生 OpenClaw 插件包，采用 TypeScript 编写，提供确定性的 JSON 结果输出。它的设计理念是「约定优于配置」——通过预定义的列表类型和严格的模式验证，让开发者能够快速上手，同时保证数据的一致性和可靠性。

该项目的核心定位是「per-machine tooling」，即每台机器上的独立工具，不依赖外部服务，数据以本地 JSON 文件形式存储，既保证了隐私性，又实现了零配置部署。

Lister 作为 OpenClaw 原生插件，提供了完整的集成方案：

• 插件清单：openclaw.plugin.json 定义插件元数据
• 技能目录：openclaw/skills/ 存放可复用的工作流技能
• 工具清单：openclaw/tools/lister.tool.json 描述工具接口
• 包元数据：package.json 支持原生插件发现

运行时通过 ./dist/index.js 注册为原生 OpenClaw 工具，可直接在 Claude Code 等环境中调用。

Lister 内置了七种精心设计的列表类型，覆盖常见使用场景：

类型	用途	字段结构
general	通用列表	text (string)
todos	任务管理	text, due (datetime), status (string)
people	联系人管理	nickname, name, email, phone, relation, birthday, additional
habits	习惯追踪	habit, frequency, target, progress, last_completed, streak, notes
shopping-items	购物清单	item, quantity, category, store, budget, status
health-log	健康记录	metric, value, unit, recorded_at, context, notes
waiting-on	等待事项追踪	subject, owner, requested_at, due_by, status, next_follow_up

每种类型都有严格的模式验证，确保数据完整性。

Lister 暴露了一组直观的 TypeScript 函数 API：

// 查看支持的命令
const commands = await showCommands();

// 查看可用列表类型
const supported = await showListTypes();

// 获取特定类型的模式定义
const todoSchema = await listTypeSchema({ listTypeName: "todos" });

// 创建新列表
await create({
  list: "tasks",
  listType: "todos",
  description: "Delivery commitments"
});

// 查询所有列表
const knownLists = await lists();

// 添加条目
await add({
  list: "tasks",
  data: { text: "ship v1", due: "2026-05-01T09:00:00Z", status: "open" }
});

// 查询条目
const openItems = await items({ list: "tasks", limit: 20 });

// 更新条目
await update({
  list: "tasks",
  id: 1,
  data: { text: "ship v1.1", due: "2026-05-03T09:00:00Z", status: "open" }
});

// 查看状态摘要
const summary = await status();

除了内置类型，Lister 还支持通过配置文件定义自定义类型。在 lister-store/_config/custom-list-types.json 中，开发者可以声明新的列表结构：

{
  "types": [
    {
      "name": "vendors",
      "purpose": "Track suppliers and commercial contacts.",
      "fields": [
        { "name": "name", "type": "string", "description": "Vendor name" },
        { "name": "owner", "type": "string", "description": "Internal owner" },
        { "name": "renewal_date", "type": "datetime", "description": "Renewal date" }
      ]
    }
  ]
}

这种设计让 Lister 能够适应各种特定领域的需求，而不需要修改核心代码。

Lister 采用纯 JSON 文件存储，每个列表独立存储在一个文件中，结构清晰：

{
  "version": "0.2.0",
  "description": "A description of the list",
  "list_type": "general",
  "items": []
}

关键设计决策：

1. 基于位置的 ID：条目使用 1-based 数字 ID，按文件中的顺序排列。这种设计简化了排序和分页逻辑。
2. 自动重索引：删除条目时，下方所有条目自动重新编号，保持连续性。
3. 时间戳追踪：每个条目自动记录 createdAt 和 updatedAt。
4. 安全删除：clear 操作需要显式确认（confirm: true），防止误删。
5. 可配置的存储路径：通过 LISTER_STORE_FOLDER 环境变量可自定义存储位置，默认为 ./lister-store。

列表名称限制为 1-64 字符，仅允许小写字母、数字、连字符和下划线，且必须以字母或数字开头。这种限制避免了文件系统兼容性问题。