limps

limps

Local Intelligent MCP Planning Server（本地智能 MCP 规划服务）——面向 AI 助手的文档与规划层。无需订阅，无需云服务。将 limps 指向任意文件夹（本地、已同步或位于 git 仓库中）。让 Claude、Cursor、Codex 和任何兼容 MCP 的工具共享同一可信数据源。

目录

• 快速开始
• 功能特性
• 我如何使用 limps
• 健康检查与自动化
• 你可以如何使用
• 为什么选择 limps？
• 安装
• 从 v2 升级
• 项目设置
• 客户端设置
• 传输方式
• 守护进程管理
• CLI 命令
• 配置
• 环境变量
• 故障排除
• MCP 工具
• 技能与命令
• 扩展
• Obsidian 兼容性
• 开发
• 生产环境应用
• 创建功能规划
• 深入了解
• 什么是 MCP？
• 许可证

快速开始

# Install globally
npm install -g @sudosandwich/limps

# Initialize in your project
cd ~/Documents/my-planning-docs
limps init

# Start the HTTP daemon
limps server start
# → Daemon starts on http://127.0.0.1:4269/mcp
# → PID file written to OS-standard location
# → Ready for MCP client connections

# Generate MCP client config
limps config print --client claude-code
# Copy the output to your MCP client config file

就是这样。现在，你的 AI 助手可以通过 HTTP 传输访问你的文档。文件夹可以位于任何位置——本地、已同步或在代码仓库中；limps 不要求你使用 git 仓库，也不要求存在 plans/ 目录。

提示： limps server status 始终会发现系统范围内的守护进程。如果找到项目配置（或通过 --config 指定了配置），该命令还会将已配置的项目目标与全局列表进行协调。

功能特性

• 文档增删改查 + 全文搜索，可处理任意文件夹中的 Markdown 文件
• 规划 + Agent 工作流，支持状态跟踪和任务评分
• 下一任务建议，提供评分明细和偏好调整
• 沙盒化文档处理，通过 process_doc(s) 助手函数实现
• 多客户端支持，适用于 Cursor、Claude、Codex 等
• 扩展，支持特定领域的工具（例如 limps-headless）
• 知识图谱——实体提取、混合检索、冲突检测和基于图谱的建议
• 健康检查自动化——陈旧检测、代码偏离检查、状态推断和自动修复提议
• 高级任务评分——基于依赖关系的优先级排序，支持为每个规划/Agent 单独设置权重覆盖
• MCP Registry——已发布到官方 MCP Registry（registry.modelcontextprotocol.io）

开始前须知

• 仅限本地 — 您的数据保存在磁盘上（SQLite 索引 + 您的文件）。无需云服务，也无需订阅。
• 更改后重启 — 如果更改了索引文件夹或配置，请重启 MCP 服务（或依靠文件监视器），以便索引和工具反映当前状态。
• 守护进程管理 — HTTP 服务以后台进程运行。使用 limps server start、limps server stop 和 limps server status 管理守护进程的生命周期。PID 文件存储在操作系统标准目录中，以便全系统识别。
• 沙盒化用户代码 — process_doc 和 process_docs 会在 QuickJS 沙盒中运行您的 JavaScript，并设有时间和内存限制；无法访问网络或 Node API。
• 一次可选的网络调用 — limps version --check 会从 npm 注册表获取信息以比较版本。其他所有命令（serve、init、list、search、create/update/delete docs、process_doc 等）均不会连接互联网。如果希望完全不进行外部调用，请省略 version --check。

我如何使用 limps

我将 limps 用作多个 AI 工具之间的本地规划层，重点关注计划和任务的创建 → 读取 → 更新 → 关闭。MCP 服务指向我想要的目录（不一定是 git 仓库），因此任何客户端都能读取和更新同一个事实来源。

典型流程：

1. 将 limps 指向一个文档目录（任意文件夹，可以是本地目录或同步目录）。
2. 使用 CLI + MCP 工具创建计划/文档、读取当前状态、更新任务，并在完成后关闭工作。
3. 将 limps MCP 条目添加到每个客户端配置中，让 Cursor/Claude/Codex 都能看到相同的计划。

我最常用的命令和工具：

• 创建：limps init、create_plan、create_doc
• 读取：list_plans、list_agents、list_docs、search_docs、get_plan_status
• 更新：update_doc、update_task_status、manage_tags
• 关闭：update_task_status（例如 PASS），必要时使用 delete_doc
• 分析：graph health、graph search、graph check、health check

完整列表见下文的“CLI 命令”和“MCP 工具”。

如何使用

limps 旨在通用且可移植。将它指向任何包含 Markdown 文件的文件夹，然后通过任何兼容 MCP 的客户端使用。无需 git 仓库。 不局限于规划——规划（计划、Agent、任务状态）只是其中一种用途；同一层还可在任何已索引文件夹中提供文档 CRUD、全文搜索和可编程处理能力。

常见用法：

• 单个项目：为某个产品使用一个文档文件夹。
• 多个项目：每个项目都有自己的 .limps/config.json；传入 --config 以指定目标配置。
• 团队共享文件夹：将计划放在共享位置，并像审查代码一样审查更改。
• 本地优先：将所有内容保存在磁盘上，无需托管服务。

核心理念：

• 任意文件夹 — 路径由您选择；如果没有 plans/ 子目录，则会索引整个目录。使用通用工具（list_docs、search_docs、create_doc、update_doc、delete_doc、process_doc、process_docs），或使用专用的计划工具（create_plan、list_plans、list_agents、get_plan_status、update_task_status、get_next_task）。
• 单一事实来源 — MCP 工具提供结构化访问；多个客户端共享同一批文档。

为什么选择 limps？

问题： 每个 AI 助手都维护自己的上下文。规划文档、任务状态和决策分散在 Claude、Cursor、ChatGPT 和 Copilot 的对话中。

解决方案： limps 提供标准化的 MCP 接口，任何工具都可以访问。您的文档集中存放在一个由您选择的文件夹中。您可以根据需要使用 git（或任何同步方式）进行版本控制；limps 不与任何代码仓库绑定。

安装

npm install -g @sudosandwich/limps

从 v2 升级

v3 带来了重大变更：

HTTP 传输（重大变更）

v3 仅使用 HTTP 传输。stdio 传输已移除。

迁移步骤：

1. 为每个项目启动 HTTP 守护进程：

   limps server start --config /path/to/.limps/config.json
   

2. 更新 MCP 客户端配置——将 stdio 配置替换为 HTTP 传输：

   {
     "mcpServers": {
       "limps-planning-myproject": {
         "transport": {
           "type": "http",
           "url": "http://127.0.0.1:4269/mcp"
         }
       }
     }
   }
   

   使用 limps config print 生成正确的代码片段。

每个项目的配置（重大变更）

v3 移除了集中式项目注册表。如果你之前使用过 limps config add、config use 或 --project 标志：

1. 在每个项目目录中运行 limps init，以创建 .limps/config.json。
2. 更新 MCP 客户端配置——将 --project <name> 替换为 HTTP 传输配置（见上文）。
3. 移除环境变量——LIMPS_PROJECT 已不存在。使用 MCP_PLANNING_CONFIG 覆盖配置路径。

已移除的命令： config list、config use、config add、config remove、config set、config discover、config migrate、config sync-mcp、serve。

替代方案： limps init + limps server start + limps config print。

项目设置

初始化新项目

cd ~/Documents/my-planning-docs
limps init

此操作会在当前目录中创建 .limps/config.json，并打印 MCP 客户端设置说明。

你也可以指定路径：

limps init ~/Documents/my-planning-docs

如果目录中包含 plans/ 子目录，limps 会使用它；否则，它会为整个目录建立索引。

多个项目

每个项目都有自己的 .limps/config.json。使用 --config 指定目标项目：

limps plan list --config ~/docs/project-b/.limps/config.json

客户端设置

运行 limps init 后，你需要在 MCP 客户端的配置文件中添加 limps 条目。使用 limps config print 为你的客户端生成正确的代码片段，然后将其粘贴到相应的配置文件中：

limps config print --client cursor
limps config print --client claude-code
limps config print --client claude

输出会准确告知你要添加哪些 JSON（或 TOML）内容，以及配置文件所在的位置。

各客户端示例

所有客户端都连接到 HTTP 守护进程。先使用 limps server start 启动守护进程，然后配置客户端。

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

[mcp_servers.limps-planning-myproject.transport]
type = "http"
url = "http://127.0.0.1:4269/mcp"

limps config print --client chatgpt

传输

limps v3 通过持久守护进程仅使用 HTTP 传输。这样多个 MCP 客户端可以共享同一个服务实例，避免多个 stdio 进程造成文件描述符膨胀。

启动 HTTP 守护进程

# Start the daemon
limps server start

# Check status (shows uptime, sessions, PID)
limps server status

# Stop the daemon
limps server stop

守护进程默认运行在 http://127.0.0.1:4269/mcp。使用 limps config print 生成正确的 MCP 客户端配置：

limps config print --client claude-code

有关生命周期管理的详细说明，请参阅守护进程管理。

MCP 客户端配置

所有客户端均使用 HTTP 传输。配置示例：

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

服务配置选项

在 config.json 中添加 "server" 部分，以自定义 HTTP 服务：

自定义服务配置示例：

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0"
  }
}

注意： PID 文件存储在操作系统标准的应用目录中：

• macOS：~/Library/Application Support/limps/pids/
• Linux：$XDG_DATA_HOME/limps/pids/ 或 ~/.local/share/limps/pids/
• Windows：%APPDATA%/limps/pids/

这样，无论身处哪个目录，都可以通过 limps server status 在整个系统范围内发现守护进程。如果在当前目录中找到 limps 配置（或通过 --config 指定配置），CLI 还会报告并协调该项目配置的目标。

• 远程客户端：远程客户端（例如 ChatGPT）请使用兼容 MCP 的 HTTPS 代理。

守护进程管理

limps v3 使用具备系统级感知能力的持久 HTTP 守护进程。PID 文件存储在操作系统标准目录中，因此你可以从系统中的任意目录管理和发现守护进程。

PID 文件位置

PID 文件存储在各平台专用的应用数据目录中：

macOS：

~/Library/Application Support/limps/pids/

Linux：

$XDG_DATA_HOME/limps/pids/
# or if XDG_DATA_HOME is not set:
~/.local/share/limps/pids/

Windows：

%APPDATA%/limps/pids/

每个 PID 文件都以端口号命名（limps-{port}.pid），以便在整个系统范围内进行发现。PID 文件结构示例：

{
  "pid": 12345,
  "port": 4269,
  "host": "127.0.0.1",
  "startedAt": "2026-02-08T12:00:00.000Z",
  "configPath": "/path/to/project/.limps/config.json",
  "logPath": "/Users/you/Library/Application Support/limps/logs/limps-4269.log"
}

基于端口的命名方式使 limps server status 无需配置文件即可查找不同项目中运行的所有守护进程。

守护进程日志写入操作系统标准的应用日志目录：

macOS：

~/Library/Application Support/limps/logs/

Linux：

$XDG_DATA_HOME/limps/logs/
# or if XDG_DATA_HOME is not set:
~/.local/share/limps/logs/

Windows：

%APPDATA%/limps/logs/

守护进程日志仅记录运行信息：limps 会对未捕获的异常和拒绝负载进行脱敏，不会持久保存原始 AI 提示词或响应内容。 守护进程日志文件采用仅追加写入方式，不会自动轮转；如果守护进程长期运行，请使用系统工具轮转或截断这些文件。

启动守护进程

后台模式（默认）：

limps server start
# → Daemon starts on http://127.0.0.1:4269/mcp
# → PID file written to OS-standard location
# → Logs written to OS-standard log file (append mode)
# → Process detaches and runs in background

前台模式（调试）：

limps server start --foreground
# → Runs in foreground (blocks terminal)
# → Logs appear in stderr
# → Useful for debugging startup issues
# → Still creates PID file for discovery

自定义端口/主机（通过配置）：

在 .limps/config.json 中配置 server.port 和 server.host：

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0"
  }
}

然后正常启动：

limps server start
# → Starts using server.port/server.host from config
# → PID file: limps-8080.pid

start 命令会通过轮询 /health 端点进行健康检查，最长持续 5 秒，并重复发送 HTTP 请求。每个健康检查请求都有各自较短的超时时间（例如，约 1000 ms）。如果此时间窗口内有任何请求失败，你会看到以下错误代码之一：

• TIMEOUT — 单个健康检查 HTTP 请求超过了其单次请求超时时间（例如，约 1000 ms）。守护进程可能启动较慢，或系统资源受限。请尝试运行 limps server start --foreground 查看日志。
• NETWORK_ERROR — 无法连接到守护进程。端口可能被阻止，或已被其他进程占用。
• NON_200_STATUS — 健康检查端点返回了非 200 状态码。请以前台模式检查守护进程日志。
• INVALID_RESPONSE — 健康检查端点已响应，但响应无效或无法按预期解析（例如，格式错误或缺少必需字段）。

检查守护进程状态

使用项目配置（与全局发现结果协调）：

# From within a project directory with .limps/config.json
limps server status
# Project target:
# limps server is running
# PID: 12345 | 127.0.0.1:4269
# Uptime: 2h 15m
# Sessions: 3
# Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log
# Project target is present in system-wide daemon discovery.
# System-wide daemons:
# 127.0.0.1:4269 (PID 12345) [project target]
#   Uptime: 2h 15m | Sessions: 3
#   Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log

# Or specify config explicitly
limps server status --config /path/to/.limps/config.json

不使用项目配置（仅全局发现）：

# From a directory without a limps config
cd /tmp
limps server status
# Found 2 running daemons:
# 127.0.0.1:4269 (PID 12345)
#   Uptime: 2h 15m | Sessions: 3
#   Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log
# 127.0.0.1:8080 (PID 67890)
#   Uptime: 45m 30s | Sessions: 1
#   Log: /Users/you/Library/Application Support/limps/logs/limps-8080.log

当 limps server status 无法在当前目录中解析配置文件（且未提供 --config）时，它只会报告全局守护进程发现结果。找到配置文件时，它会同时报告已配置的项目目标和全局守护进程列表。

停止守护进程

# From the project directory (where your .limps config lives):
limps server stop
# → Gracefully shuts down daemon
# → Closes all MCP sessions
# → Stops file watchers
# → Removes PID file
# → Process exits

# Or from any directory, by specifying the config explicitly:
limps server stop --config /path/to/.limps/config.json

stop 命令针对特定项目，并会解析配置以确定要停止哪个守护进程。守护进程会通过以下步骤进行优雅关闭：

1. 关闭所有活动的 MCP 会话
2. 关闭文件监视器
3. 移除 PID 文件
4. 退出进程

端口冲突

如果尝试在已被占用的端口上启动守护进程，limps 会检测到冲突并提供解决建议：

limps server start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)
# Command: /usr/local/bin/node /usr/local/bin/limps server start
#
# To stop the process: kill 12345
# Or use a different port: limps server start --port <port>

在可使用 lsof 的系统上（macOS、Linux），limps 可以识别占用端口的进程并显示其命令行。如果无法使用 lsof，则会显示更简短的错误消息，建议更换端口。

前台模式

调试、Docker 部署或 CI/CD 流水线中可使用前台模式：

limps server start --foreground

使用场景：

• 调试 — 实时查看服务日志，以诊断启动问题
• Docker — 让守护进程作为主进程运行，以保持容器运行
• CI/CD — 在不使用后台进程的情况下，针对 limps 守护进程运行测试

与后台模式的行为差异：

• 将日志写入 stderr，而不是保持静默
• 阻塞终端（按 Ctrl+C 停止）
• 仍会创建 PID 文件，供其他进程发现
• 响应 SIGINT（Ctrl+C）和 SIGTERM，以进行优雅关闭

健康检查端点

HTTP 守护进程会公开 /health 端点，用于监控和健康检查：

curl http://127.0.0.1:4269/health

响应示例：

{
  "status": "ok",
  "sessions": 3,
  "uptime": 8145,
  "pid": 12345,
  "sessionTimeoutMs": 1800000
}

HTTP 状态码：

• 200 — 守护进程运行正常并接受连接
• 429 — 超出速率限制（速率限制器可能会在请求到达 /health 前返回此状态码）

会话管理与重新连接

会话在闲置 30 分钟后会自动过期（可通过 sessionTimeoutMs 配置）。会话过期时，MCP 客户端会收到特定错误响应，提示其重新连接。

会话过期响应：

会话过期或关闭后，后续使用该会话 ID 的请求会返回：

{
  "error": "Session expired",
  "code": "SESSION_EXPIRED",
  "message": "Session expired due to timeout. Please reconnect without session ID.",
  "expiredAt": "2026-02-11T10:30:00.000Z"
}

标头：

• X-Session-Expired: true
• X-Session-Expired-Reason: timeout（或 closed、deleted）

MCP 客户端重新连接流程：

收到 SESSION_EXPIRED 时，客户端应：

1. 清除存储的会话 ID — 移除缓存的 mcp-session-id
2. 创建新会话 — 向 /mcp 发送 POST 请求，不包含会话 ID 标头
3. 存储新的会话 ID — 从响应标头中保存新的 mcp-session-id
4. 重试原始请求 — 使用新的会话 ID 重新提交请求

配置：

在 .limps/config.json 中调整会话超时时间：

{
  "server": {
    "sessionTimeoutMs": 3600000  // 1 hour (default: 1800000 = 30 min)
  }
}

设为 0 可禁用超时（会话会一直保留，直到服务器重启）。

过期会话跟踪：

服务器会跟踪过期会话 24 小时，帮助客户端区分“会话已过期”和“会话从未存在”：

• SESSION_EXPIRED — 会话之前存在，但已超时（客户端应重新连接）
• SESSION_NOT_FOUND — 会话 ID 从未有效（可能是服务器重启或 ID 无效）

此端点可用于：

• 在脚本或仪表板中监控守护进程健康状态
• 连接 MCP 客户端前验证守护进程是否正在运行
• 在编排工具（Kubernetes、Docker Compose）中执行自动健康检查

多个守护进程

你可以在不同端口上运行多个 limps 守护进程，以服务不同的项目：在每个项目的配置中设置不同的端口：

# Project A with default port (4269)
cd ~/projects/project-a
# .limps/config.json has server.port: 4269 (or uses default)
limps server start
# → Running on http://127.0.0.1:4269/mcp

# Project B with custom port (8080)
cd ~/projects/project-b
# .limps/config.json has server.port: 8080
limps server start
# → Running on http://127.0.0.1:8080/mcp

每个守护进程都有自己的 PID 文件：

• limps-4269.pid — 项目 A
• limps-8080.pid — 项目 B

发现所有正在运行的守护进程（在没有 limps 配置的目录中运行）：

cd /tmp
limps server status
# Found 2 running daemons:
# 127.0.0.1:4269 (PID 12345)
#   Uptime: 2h 15m | Sessions: 3
# 127.0.0.1:8080 (PID 67890)
#   Uptime: 45m 30s | Sessions: 1

每个 MCP 客户端都可以通过在各自的配置文件中设置不同的 URL，连接到不同的守护进程。

CLI 命令

推荐的分组命令

limps plan list                              # List all plans with status
limps plan agents <plan>                     # List agents in a plan
limps plan status <plan>                     # Show plan progress summary
limps plan next <plan>                       # Get highest-priority available task
limps plan score --plan <plan> --agent <n>  # Score a single task
limps plan scores --plan <plan>              # Score all available tasks in a plan
limps docs list [path]                       # List files/directories
limps docs search <query>                    # Search indexed docs
limps docs process [path] --code "<js>"      # Process docs with JavaScript
limps server start                           # Start HTTP daemon
limps server status                          # Show daemon status
limps server stop                            # Stop HTTP daemon

项目管理

limps init [path]             # Initialize new project
limps config show             # Display current config
limps config print            # Print MCP client config snippets
limps completion zsh          # Generate Zsh tab-completion script

健康检查与自动化

limps health check              # Aggregate all health signals
limps health staleness [plan]   # Find stale plans/agents
limps health inference [plan]   # Suggest status updates
limps proposals [plan]           # List auto-fix proposals
limps proposals apply <id>       # Apply a proposal
limps proposals apply-safe       # Apply all safe proposals

知识图谱

limps graph reindex              # Build/rebuild graph
limps graph health               # Graph stats and conflicts
limps graph search <query>       # Search entities
limps graph trace <entity>       # Trace relationships
limps graph entity <id>          # Entity details
limps graph overlap              # Find overlapping features
limps graph check [type]         # Run conflict detection
limps graph suggest <type>       # Graph-based suggestions
limps graph watch                # Watch and update incrementally

评分与修复

limps plan scores --plan <plan>                # Score all agents in a plan
limps plan score --plan <plan> --agent <n>   # Score a single task
limps plan repair [--fix]                   # Check/fix agent frontmatter

配置

配置文件位于项目目录下的 .limps/config.json，由 limps init 创建。

配置选项

{
  "plansPath": "./plans",
  "docsPaths": ["."],
  "fileExtensions": [".md"],
  "dataPath": ".limps/data",
  "extensions": ["@sudosandwich/limps-headless"],
  "tools": {
    "allowlist": ["list_docs", "search_docs"]
  },
  "scoring": {
    "weights": { "dependency": 40, "priority": 30, "workload": 30 },
    "biases": {}
  }
}

环境变量

优先级： config.tools 的优先级高于环境变量。设置了允许列表时，将忽略拒绝列表。

故障排除

守护进程无法启动

“端口已被占用”错误：

如果看到此错误，说明另一个进程正在使用该端口：

limps server start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)

解决方法：

1. 终止现有进程：kill 12345
2. 或使用其他端口：limps server start --port 8080
3. 检查它是否是另一个 limps 守护进程：limps server status（如果是，请先使用 limps server stop）

“守护进程可能启动失败”错误：

如果守护进程已启动，但无法通过健康检查：

limps server start
# Error: Daemon may have failed to start. Check logs or try: limps server start --foreground

解决方法：

1. 检查守护进程日志路径：limps server status（或以前台模式运行：limps server start --foreground）
2. 检查权限问题：确保你对 PID 目录拥有写入权限
3. 确认端口可访问：尝试运行 curl http://127.0.0.1:4269/health
4. 启用调试日志：DEBUG=1 limps server start --foreground

PID 目录权限问题：

如果无法创建 PID 文件：

# macOS
ls -la ~/Library/Application\ Support/limps/pids/

# Linux
ls -la ~/.local/share/limps/pids/

# Windows
dir %APPDATA%\limps\pids

确保目录存在且你拥有写入权限。如果没有，请手动创建：

# macOS
mkdir -p ~/Library/Application\ Support/limps/pids

# Linux
mkdir -p ~/.local/share/limps/pids

# Windows
mkdir %APPDATA%\limps\pids

健康检查失败

TIMEOUT 错误：

守护进程未在配置的超时时间内响应。每个健康检查请求都有各自的超时时间（例如，最终 limps server start 检查为 1000ms，limps server status 为 3000ms），启动期间 limps 会持续轮询约 5 秒，然后报告“守护进程可能未能启动”。

常见原因：

• 系统资源受限（CPU／内存使用率过高）
• 文件系统速度较慢（尤其是在初始化索引时）
• 文档库较大，索引所需时间较长

解决方法：

1. 检查系统资源：top 或“活动监视器”
2. 稍等片刻后重试：limps server status
3. 在前台运行以查看进度：limps server start --foreground

NETWORK_ERROR：

无法与守护进程建立连接。

常见原因：

• 防火墙阻止了端口
• 守护进程启动后崩溃
• 主机／端口配置错误

解决方法：

1. 确认守护进程正在运行：limps server status
2. 检查防火墙中端口 4269 的设置
3. 尝试手动运行 curl http://127.0.0.1:4269/health
4. 检查守护进程日志：查看 limps server status 输出中的 Log: 路径

过期的 PID 文件

limps 会自动清理过期的 PID 文件，具体情况如下：

• 运行 limps server status 时（发现并移除过期文件）
• 运行 limps server start 时（移除目标端口对应的过期文件）
• 守护进程通过 limps server stop 正常关闭时

如果需要手动清理 PID 文件：

# macOS
rm ~/Library/Application\ Support/limps/pids/limps-*.pid

# Linux
rm ~/.local/share/limps/pids/limps-*.pid

# Windows
del %APPDATA%\limps\pids\limps-*.pid

需要手动清理的情况：

• 系统崩溃或强制关机后
• 如果 limps server start 报告守护进程正在运行，但实际上并未运行
• 卸载 limps 之前

多个守护进程冲突

如果意外尝试在同一端口启动第二个守护进程：

limps server start
# Error: limps daemon already running (PID 12345 on 127.0.0.1:4269). Run 'limps server stop' first.

这是预期行为——limps 使用基于 PID 的锁定机制，防止在同一端口运行多个守护进程。

解决方法：

1. 检查所有正在运行的守护进程：limps server status
2. 停止现有守护进程：limps server stop
3. 或者在其他端口启动：limps server start --port 8080

调试连接问题

如果 MCP 客户端无法连接到守护进程，请逐步验证连接情况：

1. 检查守护进程状态：

limps server status
# Should show daemon running with healthy status

2. 验证健康检查端点：

curl http://127.0.0.1:4269/health
# Should return JSON with status "ok"

3. 验证 MCP 端点：

curl -X POST http://127.0.0.1:4269/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'
# Should return MCP initialize response

4. 启用调试日志：

DEBUG=1 limps server start --foreground
# Watch for connection attempts and errors

5. 检查 MCP 客户端配置：

确保客户端配置中的 URL 与守护进程一致：

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

配置解析问题

问题：limps 使用了错误的配置文件

如果 limps config path 显示的配置与预期不同，请使用诊断命令了解原因：

limps config show-resolution

此命令会显示配置解析的全部三个优先级：

1. CLI --config 参数（优先级最高）
2. MCP_PLANNING_CONFIG 环境变量（优先级第二）
3. 本地 .limps/config.json（从 cwd 开始向上搜索）

常见原因：

• 已设置环境变量：检查 shell 或 IDE 中是否设置了 MCP_PLANNING_CONFIG。它的优先级高于本地配置文件。

  # Check if set
  echo $MCP_PLANNING_CONFIG
  
  # Unset if needed
  unset MCP_PLANNING_CONFIG
  

• 工作目录错误：配置搜索从当前工作目录开始。运行 limps 命令时，请确保处于正确的目录。

  # Check current directory
  pwd
  
  # Navigate to your project
  cd /path/to/your/project
  

• 缺少 .limps/config.json：配置文件必须位于 .limps 子目录中，而不是项目根目录。

  # Correct location
  /path/to/project/.limps/config.json
  
  # Wrong - won't be found
  /path/to/project/config.json
  

快速修复：

# Override with explicit path
limps plan list --config /path/to/project/.limps/config.json

# Or set environment variable
export MCP_PLANNING_CONFIG=/path/to/project/.limps/config.json

# Or initialize a new config in current directory
limps init

MCP 工具

limps 为 AI 助手提供 MCP 工具：

知识图谱

知识图谱会构建规划文档的结构化、可查询表示。它会提取 6 种实体类型（plan、agent、feature、file、tag、concept）及其关系（归属、依赖、修改、标记和概念链接）。可用它来查找冲突、追踪依赖，并获取基于图谱的建议。

# Build the graph from plan files
limps graph reindex

# Check graph health and conflicts
limps graph health --json

# Search entities
limps graph search "auth" --json

# Trace relationships
limps graph trace plan:0042 --direction down

# Detect conflicts (file contention, circular deps, stale WIP)
limps graph check --json

# Get graph-based suggestions
limps graph suggest dependency-order

详情请参阅知识图谱架构和 CLI 参考。

健康检查与自动化

limps 包含自动健康检查，可检测问题并建议修复方法：

• 过时检查——标记在可配置的时间阈值内未更新的计划/Agent
• 代码偏移——检测 Agent frontmatter 引用的文件是否已不存在
• 状态推断——根据依赖项完成情况和正文内容建议更改状态
• 提案——汇总所有建议，形成可供审核和应用的修复方案

limps health check --json        # Run all checks
limps proposals apply-safe       # Auto-apply safe fixes

技能与命令

此仓库提供 Claude Code 斜杠命令，位于 .claude/commands/，以及一个 Vercel Skills 技能，位于 skills/limps-planning。

Claude Code 命令（将 limps 设为工作目录后即可自动使用）：

Vercel Skills（适用于其他 AI IDE）：

安装 limps 规划技能，以获取 AI 驱动的计划创建、Agent 工作流和任务管理指导：

# Install only the limps planning skill (recommended for consumers)
npx skills add https://github.com/sudosandwich/limps/tree/main/.claude/skills/limps-plan-operations

# Or install all available skills
npx skills add sudosandwich/limps

可用技能：

有关通过上方 npx skills add 安装的 .claude/skills 软件包的完整清单，请参阅 skills.yaml；此仓库中单独的 skills/limps-planning/ 软件包属于旧版分发方式，新用户应优先使用 .claude/skills 方法。

扩展

扩展会添加 MCP 工具和资源。请从 npm 安装：

npm install -g @sudosandwich/limps-headless

添加到配置中：

{
  "extensions": ["@sudosandwich/limps-headless"],
  "limps-headless": {
    "cacheDir": "~/Library/Application Support/limps-headless"
  }
}

可用扩展：

• @sudosandwich/limps-headless — 无头 UI 契约提取、语义分析和偏差检测（Radix UI 和 Base UI 迁移）。

Obsidian 集成

@sudosandwich/limps-obsidian-plugin 软件包提供深度 Obsidian 集成：

• 持久 MCP 会话 — 连接到 limps 守护进程，支持自动重连、保活和 CLI 回退
• 文档管理 — 在 Obsidian 中创建、更新和删除计划文档
• 任务管理 — 获取下一个任务，更新任务状态（GAP/WIP/PASS/BLOCKED）
• 搜索与提案 — 全文搜索、提案审查，以及自动应用安全修复类型
• 健康中心 — 在侧边栏查看守护进程、图谱、链接和 MCP 状态
• 有向图视图 — 可交互的 2D/3D 力导向图，节点可点击
• 定期健康检查 — 定期检测过时、偏差和冲突
• 库自动化 — 计划文件变更时自动重新索引，并根据事件刷新
• 编辑器诊断 — 行内链接验证
• 图谱同步到 Obsidian 界面（.md、.canvas、.base）

全面支持 YAML frontmatter、标签管理（frontmatter 和行内 #tag），并自动排除 .obsidian/、.git/、node_modules/。

请参阅 packages/limps-obsidian-plugin/README.md，了解设置说明、命令和设置参考。

开发

git clone https://github.com/paulbreuler/limps.git
cd limps
npm install
npm run build
npm test

这是一个包含以下内容的 monorepo：

• packages/limps — 核心 MCP 服务
• packages/limps-headless — 无头 UI 扩展（Radix/Base UI 契约提取与审计）

在生产环境中使用

limps 使用单独的文件夹（本例中是一个 git 仓库）来管理 runi 的规划。

创建功能计划

最快的方法是使用 /create-feature-plan 斜杠命令（Claude Code）——它会通过 MCP 工具自动处理编号、文档创建和 Agent 提炼。完整规范请参阅 .claude/commands/create-feature-plan.md。

你也可以手动使用 MCP 工具执行相同步骤：

1. list_plans → 确定下一个计划编号
2. create_plan → 创建计划目录框架
3. create_doc → 添加计划、接口、README 和 Agent 文件
4. update_task_status → 跟踪进度

计划采用以下布局：

NNNN-descriptive-name/
├── README.md
├── NNNN-descriptive-name-plan.md
├── interfaces.md
└── agents/
    ├── 000_agent_infrastructure.agent.md
    ├── 001_agent_feature-a.agent.md
    └── ...

带编号的前缀可确保计划和 Agent 按字典序排列。get_next_task 会使用 Agent 编号（以及依赖项和工作量评分）建议接下来要处理的任务。

深入了解

plans/
├── 0001-feature-name/
│   ├── 0001-feature-name-plan.md    # Main plan with specs
│   ├── interfaces.md                 # Interface contracts
│   ├── README.md                     # Status index
│   └── agents/                       # Task files
│       ├── 000-setup.md
│       ├── 001-implement.md
│       └── 002-test.md
└── 0002-another-feature/
    └── ...

---
status: GAP | WIP | PASS | BLOCKED
persona: coder | reviewer | pm | customer
depends_on: ["000-setup"]
files:
  - src/components/Feature.tsx
---

{
  "scoring": {
    "biases": {
      "plans": { "0030-urgent-feature": 20 },
      "personas": { "coder": 5, "reviewer": -10 },
      "statuses": { "GAP": 5, "WIP": -5 }
    }
  }
}

await process_doc({
  path: "plans/0001-feature/plan.md",
  code: `
    const features = extractFeatures(doc.content);
    return features.filter(f => f.status === 'GAP');
  `,
});

await process_doc({
  path: "plans/0001/plan.md",
  code: "extractFeatures(doc.content)",
  sub_query: "Summarize each feature",
  allow_llm: true,
  llm_policy: "force", // or 'auto' (skips small results)
});

# Run Agent

Start work on the next available task.

## Instructions

1. Use `get_next_task` to find the highest-priority task
2. Use `process_doc` to read the agent file
3. Use `update_task_status` to mark it WIP
4. Follow the agent's instructions

什么是 MCP？

Model Context Protocol 是一种标准化协议，用于让 AI 应用连接外部系统。该协议最初由 Anthropic 于 2024 年 11 月推出，现已成为 Linux Foundation 的 Agentic AI Foundation 的一部分。

• MCP 规范
• MCP 文档

许可证

MIT