Promptling (Bearish Sun)

Promptling.gif

提示-Claude代码的任务管理

轻量级任务/项目管理应用程序（想想Jira，但更简单），旨在通过MCP（模型上下文协议）与Claude Code一起工作。

我如何使用它

• 创建工作项 -使用web UI将您的所有想法记录到工作项中（任务、功能、错误）。
• 计划 -使用 /plan 用于复杂的功能/任务。没有到处都是难以跟踪的.md文件，计划附在工作项上。
• 实施 - /implement 读取工作项详细信息，包括计划和任何附件（如图像），然后开始编码。

主要特点

• 复制按钮，用于快速将工作项ID复制到Claude Code
• 从Claude自动生成工作项
• 更改历史跟踪
• 集成markdown查看器
• 附件支持（图像和其他文档）
• 多项目支持
• 章节（功能和错误，自定义章节）
• 将功能分解为子任务
• 用于对项目进行分组的类别
• 拖放重新排序
• 项目状态跟踪（打开→ 进行中→ Done)
• 项目优先级、复杂性、自定义标签
• 亮/暗/系统主题
• 基于文件的存储（不需要数据库）
• 在您的计算机上本地运行

快速开始

先决条件

• v18或更高版本

一键启动

1. 窗户： 双击 start-promptling.bat
2. macOS/Linux： 跑 ./start-promptling.sh （可能需要 chmod +x start-promptling.sh 第一）

启动器将自动：

• 安装依赖项（仅限首次运行）
• 构建客户端（仅限首次运行）
• 启动服务器并打开浏览器http://localhost:3001

手动设置

如果您更喜欢手动设置或启动器不起作用：

# Install dependencies
npm install

# Build the client
cd client && npm run build && cd ..

# Start the server
cd server && node index.js

然后打开http://localhost:3001在您的浏览器中。

重建脚本（PM2工作流）

如果您在PM2下运行Promptling，并希望首先重建所有内容：

# Windows
rebuild-promptling.bat

# Or via npm
npm run rebuild

然后重新启动PM2：

pm2 restart promptling

将MCP工具添加到Claude代码中

添加Promptling MCP服务器，以便Claude可以与您的任务交互：

claude mcp add --transport http promptling http://localhost:3001/api/mcp

提示使用单个MCP端点(/api/mcp)具有流式HTTP支持和传统JSON-RPC POST兼容性。 如果Claude已配置为 http://localhost:3001/api/mcp，更新后不需要更改端点。

重新启动克劳德代码。您现在可以使用以下工具 search, get, create, update, list，以及 read 用于管理项目。

安装自定义命令

将自定义命令复制到您的Claude配置中：

# Windows
xcopy /E /I /path/to/promptling/.claude/commands %USERPROFILE%\.claude\commands

# macOS/Linux
cp -r /path/to/promptling/.claude/commands ~/.claude/commands

可用命令：

• /plan -创建/更新实施计划
• /implement -从计划中实现一个功能/错误

______________________________________________________________________

详细设置指南

从头开始设置Promptling的分步说明。

第一步：安装Node.js

1. 从下载Node.js LTShttps://nodejs.org/
2. 运行安装程序（使用默认设置）
3. 重新启动终端/命令提示符
4. 验证安装：

   node --version   # Should show v18+ or v20+
   npm --version    # Should show 9+ or 10+

第二步：获取项目

从git克隆或将项目文件夹复制到所需位置（例如。， D:\Projects\Promptling).

步骤3：安装依赖项

cd D:\Projects\Promptling
npm install

这将安装根、客户端和服务器的依赖关系。

步骤4：构建客户端

cd D:\Projects\Promptling\client
npm run build

步骤5：启动服务器

选项A：简单启动（终端关闭时停止）

cd D:\Projects\Promptling\server
node index.js

选项B:PM2的持久服务（推荐）

# Install PM2 globally
npm install -g pm2

# Start the server
cd D:\Projects\Promptling\server
pm2 start index.js --name "promptling"

# Save process list so PM2 remembers it
pm2 save

# (Optional) Install PM2 Windows service for auto-start on boot
npm install -g pm2-windows-startup
pm2-startup install

步骤6：访问应用程序

打开http://localhost:3001在您的浏览器中。

______________________________________________________________________

技术栈

• 前端： React 19+Vite
• 后端： Express 5+Node.js
• 拖放： @dnd套件
• Markdown： 反应降价

项目结构

Promptling/
├── client/           # React frontend
│   ├── src/
│   └── dist/         # Built files (after npm run build)
├── server/           # Express backend
│   ├── index.js
│   └── routes/
├── .promptling/      # Data storage (created automatically)
│   ├── data.json
│   └── attachments/
└── package.json      # Root workspace

发展模式

对于热重载的主动开发：

cd D:\Projects\Promptling
npm run dev

这将通过热重新加载启动客户端（端口5173）和服务器（端口3001）。

• 前端：http://localhost:5173
• APIhttp://localhost:3001/api

生产部署

建立客户

cd D:\Projects\Promptling\client
npm run build

这将在中创建优化的静态文件 client/dist/.

启动服务器

服务器同时为API和构建的React前端提供服务。

cd D:\Projects\Promptling\server
node index.js

访问应用程序：http://localhost:3001

作为持久服务运行（Windows）

使用PM2（推荐）

# Install PM2 globally
npm install -g pm2

# Start the server
cd D:\Projects\Promptling\server
pm2 start index.js --name "promptling"
pm2 save

# Install as Windows service (run as Administrator)
npm install -g pm2-windows-startup
pm2-startup install

PM2命令

替代方案：Windows任务计划程序

1. 按 Win+R，类型 taskschd.msc
2. 创建基本任务→ 名称：“提示服务器”
3. 触发器：“计算机启动时”
4. 操作：“启动一个程序”

- 程序： C:\Program Files\nodejs\node.exe - 论据： index.js - 开始时间： D:\Projects\Promptling\server

1. 启用“无论用户是否登录都运行”

代码更改后的更新

# Rebuild client
cd D:\Projects\Promptling\client
npm run build

# Restart server
pm2 restart promptling

API终点

数据存储

所有数据都存储在 .promptling 默认目录：

• projects.json -项目元数据
• settings.json -全局设置
• `projects/

/data.json` -项目数据（项目、任务、类别）

• `projects/

/attachments/` -文件附件

配置

数据目录位置

默认情况下，Promptling将所有数据存储在 .promptling 项目文件夹中的目录。您可以通过创建 promptling.config.json 项目根目录中的文件：

{
  "dataDir": ".promptling"
}

这 dataDir 可以是：

• 相对路径 （相对于项目根）： ".promptling", "../my-data", "data/promptling"
• 绝对路径: "D:\\MyData\\promptling", "/home/user/promptling-data"

当您想要：

• 将数据存储在项目文件夹之外（例如，用于备份目的）
• 在多个Promptling实例之间共享数据
• 将数据与应用程序代码分开

看 promptling.config.example.json 作为示例配置。

服务器端口

可以通过环境变量更改服务器端口：

set PORT=8080 && node index.js

故障排除

端口已在使用中

# Find what's using the port
netstat -ano | findstr ":3001"

# Kill the process
taskkill /PID 
 /F

检查服务器是否正在运行

打开http://localhost:3001/api/health在浏览器中或运行：

curl http://localhost:3001/api/health

应返回： {"status":"ok","timestamp":"..."}

安装后无法识别PM2

关闭并重新打开终端，或运行：

refreshenv

git克隆后缺少依赖项

一定要跑 npm install 在项目根目录中：

cd D:\Projects\Promptling
npm install