Listspace

面向编码 Agent 的 Listspace

让 Agent 能将 Listspace 看板用作项目记忆的组件。此文件夹公开于 github.com/listspace/agent，CLI 在 npm 上的名称为 listspace。安装并登录：

npx listspace login     # paste a personal token from Listspace: Settings > Your AI > API tokens
npx listspace boards

路径	说明
skills/listspace/	技能：SKILL.md（工作循环）以及 reference/（工具、Agent 访问方式、CLI），仅在需要时加载。遵循 Agent Skills 格式，因此可通过 npx skills add 安装。这是源副本。
cli/	listspace，供未使用 MCP 服务的 Agent 使用的轻量 Node CLI：通过 REST API（https://api.listspace.app/v1）执行简短命令，并通过 call 调用 MCP 服务上的所有 MCP 工具（https://mcp.listspace.app）。TypeScript 打包为单个 ESM 文件，无运行时依赖，需要 Node 20 或更高版本。
claude-code-plugin/	Claude Code 插件：技能（复制的文件集）和 .mcp.json，后者用于注册远程 MCP 服务 https://mcp.listspace.app。
.claude-plugin/marketplace.json	列出该插件的市场文件，因此现在可将此文件夹添加为本地市场，之后也可作为 GitHub 市场添加。
AGENTS.md.snippet	用户粘贴到仓库的 AGENTS.md 或 CLAUDE.md 中、用于引导 Agent 找到正确看板的内容。
scripts/	sync-skill.mjs 将技能复制到插件中；check-agent.mjs（在 CI 中运行）检查副本、frontmatter、版本和 MCP 条目。

该 MCP 服务也已作为 app.listspace/listspace 列入 MCP Registry，并列于 Smithery。

编辑技能

只编辑 skills/listspace/，然后运行：

node agent/scripts/sync-skill.mjs
node agent/scripts/check-agent.mjs

插件使用的是实际副本，而不是符号链接，因此单独复制或下载插件文件夹后仍可正常使用。如果两者不一致，CI 会失败。保持 SKILL.md 简短：步骤和规则放在那里，详细信息放在 reference/ 中。

版本统一通过 cli/package.json、cli/src/version.ts、plugin.json 和技能的 metadata.version 管理；如果这些版本不一致，检查就会失败。

本地试用

CLI

cd agent/cli
npm ci
npm run build
node dist/listspace.mjs login            # paste a token from Listspace: Settings > Your AI > API tokens
node dist/listspace.mjs whoami
node dist/listspace.mjs session "<board title or id>"
node dist/listspace.mjs add "<board>" ideas "Try dark mode" --description "Seen in **settings**"

在 agent/cli 中运行 npm link，即可将 listspace 添加到 PATH。LISTSPACE_TOKEN 可在单次运行中覆盖已保存的令牌；LISTSPACE_API_URL 和 LISTSPACE_MCP_URL 可让 CLI 指向其他服务。每条命令都支持 --json。令牌以 credentials.json 的形式保存在操作系统配置目录中（Windows 上为 %APPDATA%\listspace，macOS 上为 ~/Library/Application Support/listspace，其他系统上为 ~/.config/listspace），权限模式为 600。

测试：npm test（使用模拟 fetch 的 node:test，无需网络）。npm run typecheck 会运行严格类型检查。

单独使用技能

任何能读取 Agent Skills 的 Agent：

npx skills add ./agent -s listspace     # the skills CLI reads skills/ in a local folder

或者将 agent/skills/listspace 复制到 ~/.claude/skills/listspace，以供 Claude Code 使用。需单独连接 MCP 服务（claude mcp add --transport http listspace https://mcp.listspace.app），也可以使用上文的 CLI。

Claude Code 插件

用于单次会话：

claude --plugin-dir ./agent/claude-code-plugin

也可以将其添加为本地市场，以保持安装状态：

claude plugin marketplace add ./agent
claude plugin install listspace@listspace

然后运行 /mcp，选择 listspace 服务并登录（通过 Listspace 进行 OAuth）。当项目有看板时，技能会显示为 /listspace:listspace，Claude 会自行加载。claude plugin validate ./agent/claude-code-plugin 可检查清单。

如果你已经自行添加了 Listspace MCP 服务，Claude Code 可能会显示两个；请移除其中一个。

决策检查

插件还会在 Claude 每轮对话结束时运行一个小型检查（hooks/hooks.json、hooks/decision-check.mjs）。当用户选择某个选项、同意一项提议或纠正一条事实，而 Claude 在该轮对话中没有记录决策时，系统会让 Claude 再回复一次，并只发送一行提示：如果这是会影响后续工作的决策，就用 record_decision 将其记录为 Proposed；否则，不作评论，直接结束本轮对话。

规则倾向于保持沉默。对行动提议的肯定（“要我提交吗？”“好”）、“也许”，以及 bug 报告或代码中的位置（“不，还在失败”“bug 在解析器里”）都不算决策。只有当 Claude 的上一条消息提供了选项或提出了建议（推荐、建议、提议、选项、选哪个、带字母编号的列表）时，肯定才算数。

• 对于未使用过 Listspace 工具的会话，它不会执行任何操作；同一轮中也绝不会拦截两次（stop_hook_active），因此不会陷入循环。
• 它只根据用户输入执行纯规则判断，不调用模型，也不联网，因此不产生费用，且能在几毫秒内给出响应（超时时间为 5 秒）。
• 计算机上需要安装 Node.js 18 或更高版本（Windows、macOS 或 Linux）。每条命令都以 ; exit 0 结尾，因此没有 Node.js 时，该检查不会执行任何操作，Claude Code 也不会显示钩子错误（sh、Git Bash 和 PowerShell）。
• 它会在插件的数据文件夹（CLAUDE_PLUGIN_DATA，仅用户可读取）中为每个会话保存几个小文件，并在一周后删除。普通提示不会写入任何内容。看起来像决策的提示会仅在该轮对话中保留其首行，最多 80 个字符。对于 Claude 的上一条消息，它只保留是否提供了选项这一信息。没有数据文件夹时，该检查不会执行任何操作。
• 测试：node --test agent/scripts/decision-check.test.mjs。check-agent.mjs 会检查 hooks.json。

进度检查

每轮对话结束时运行的第二个检查（hooks/progress-check.mjs）会让看板进度与工作保持同步。当某轮对话修改了文件（Edit、Write、MultiEdit、NotebookEdit），通过 git 提交、推送或合并，使用 gh 创建或合并了拉取请求，或进行了部署，而 Claude 在这些操作之后没有写入 Listspace 时，系统会让 Claude 再回复一次，并发送一行提示：“更新 Listspace 看板：这轮开始或完成了什么？移动事项，添加简短评论。”

• 对于未使用过 Listspace 工具的会话，它不会执行任何操作；也绝不会连续拦截两次（stop_hook_active），因此不会陷入循环。
• 提示一次后，至少会等待 3 轮才会再次提示，并且只有出现新的工作时才会再次提示，因此不会反复催促。
• 任何 Listspace 写入操作都算作更新（move_item、add_comment、complete_item、record_decision、capture 等）；读取操作不算。
• 它只会在插件的数据文件夹中保留事实信息（完成的工作、看板是否已更新、上次提示所在轮次），不会保留命令或文件名，并在一周后删除。Node.js 和 ; exit 0 的要求与决策检查相同。
• 测试：node --test agent/scripts/progress-check.test.mjs。

看板上下文

会话开始时，Listspace 服务会随说明一并发送看板规则；长会话尤其是对话经过压缩的会话可能会丢失这些规则。hooks/board-hooks.mjs 会在关键时刻将这些规则补充到 Claude 的上下文中。它只添加上下文：从不阻止任何操作，也不会更改命令或其输出。

• 会话开始时（SessionStart：startup、resume、clear）：用一行文字指出项目的看板，并说明先调用 get_account 和 start_session，优先更新 unfinished_from_last_sessions 中的事项，并保持看板更新。
• 压缩之后（SessionStart，来源为 compact）：补充看板规则，并要求继续操作前先调用 get_account（或 start_session），因为 claimed_by_you 和 started_by_you 列出了 Claude 正在处理的事项。
• 创建拉取请求或部署之后（Bash 和 PowerShell 上的 PostToolUse）：成功执行 gh pr create、gh pr merge 或部署命令后，用一行文字提示将对应事项移至相应状态（新建拉取请求移至 Doing，合并或部署后移至 Done），并添加简短评论。
• 只有当项目的 CLAUDE.md 或 AGENTS.md 中包含 Listspace board: 行（位于当前文件夹或其上层目录，最多到仓库根目录），或当前会话使用过 Listspace 工具（进度检查中的备注），它才会执行此操作。它只会从文件中提取 Listspace 看板链接，不会提取其他文本。
• 它不会写入任何内容，也不会发起网络请求。与决策检查使用相同的 Node.js 和 ; exit 0 规则。
• 测试：node --test agent/scripts/board-hooks.test.mjs。

未包含的内容及原因

• login 的设备配对：API 已支持（POST /auth/device），但 CLI 尚未使用。login 已将“获取令牌的方式”与保存令牌分开；cli/src/cli.ts 中的 TODO 标记了添加配对功能的位置。脚本仍可使用 --token 和管道传入的令牌。
• 插件中的令牌：.mcp.json 按设计不包含请求头。令牌会随插件分发给每位用户；通过 /mcp 登录则是每位用户各自进行。检查脚本会拒绝其中的请求头。
• 插件中的 CLI（bin/）：未包含，因为 claude.ai 和 Cowork 不会安装带有顶层 bin/ 的插件，而且 MCP 服务已覆盖 Claude Code。

发布

1. 通过 npx skills add 发布 Skill：已发布。公开仓库 listspace/agent 将此文件夹放在根目录，因此 npx skills add listspace/agent 可以正常使用。
2. 在 npm 上发布 CLI：已作为无作用域的 listspace 发布（0.5.0）。发布新版本时：更新一个版本号（见“编辑 Skill”），用 npm pack --dry-run 检查包内容，然后在 agent/cli 目录下使用启用了 2FA 的 npm 账号运行 npm publish。prepublishOnly 会运行类型检查、测试和构建。
3. Claude Code 插件：公开仓库同时也是一个市场（.claude-plugin/marketplace.json），因此用户可以运行 /plugin marketplace add listspace/agent 和 /plugin install listspace@listspace。要在 Anthropic 的插件目录中上架，需单独提交申请；是否提交由所有者决定，且该目录要求提供隐私政策和条款 URL。

参考资料：Claude Code 插件清单参考（https://code.claude.com/docs/en/plugins-reference）、插件加载与 --plugin-dir（https://code.claude.com/docs/en/plugins/loading）、市场参考（https://code.claude.com/docs/en/plugins/marketplace-reference）、skills（https://code.claude.com/docs/en/skills）、Agent Skills 规范（https://agentskills.io/specification）、skills CLI（https://github.com/vercel-labs/skills），以及作为范例的 Postiz Agent 仓库（https://github.com/gitroomhq/postiz-agent）。