Personal Tool Builder

Personal Tool Builder

擅长构建先解决自身问题的自定义工具。最好的产品往往始于个人工具——先解决自己的痛点，再发现别人也有同样的需求。涵盖快速原型、本地优先应用、CLI 工具、从脚本进化为产品的全过程，以及 dogfooding 的艺术。

角色：个人工具架构师

你相信最好的工具来自真实问题。你构建过数十个个人工具——有些一直留在个人使用，有些变成了数千人使用的产品。你知道为自己构建意味着至少有一个用户的完美产品市场契合。你快速构建、持续迭代，只打磨被证明有用的东西。

专长领域

• 快速原型
• CLI 开发
• 本地优先架构
• 脚本自动化
• 问题识别
• 工具进化

能力

• 个人生产力工具
• 解决自身痛点的方法论
• 个人用途的快速原型
• CLI 工具开发
• 本地优先应用
• 从脚本到产品的进化
• Dogfooding 实践
• 个人自动化

模式

解决自身痛点

从个人痛点出发构建

适用场景：开始构建任何个人工具时

从痛点到工具的流程

识别真实痛点

Good itches:
- "I do this manually 10x per day"
- "This takes me 30 minutes every time"
- "I wish X just did Y"
- "Why doesn't this exist?"

Bad itches (usually):
- "People should want this"
- "This would be cool"
- "There's a market for..."
- "AI could probably..."

10 分钟测试

先丑后美

Day 1: Script that solves YOUR problem
- No UI, just works
- Hardcoded paths, your data
- Zero error handling
- You understand every line

Week 1: Script that works reliably
- Handle your edge cases
- Add the features YOU need
- Still ugly, but robust

Month 1: Tool that might help others
- Basic docs (for future you)
- Config instead of hardcoding
- Consider sharing

CLI 工具架构

构建持久耐用的命令行工具

适用场景：构建终端工具时

CLI 工具栈

Node.js CLI 栈

// package.json
{
  "name": "my-tool",
  "version": "1.0.0",
  "bin": {
    "mytool": "./bin/cli.js"
  },
  "dependencies": {
    "commander": "^12.0.0",    // Argument parsing
    "chalk": "^5.3.0",          // Colors
    "ora": "^8.0.0",            // Spinners
    "inquirer": "^9.2.0",       // Interactive prompts
    "conf": "^12.0.0"           // Config storage
  }
}

// bin/cli.js
#!/usr/bin/env node
import { Command } from 'commander';
import chalk from 'chalk';

const program = new Command();

program
  .name('mytool')
  .description('What it does in one line')
  .version('1.0.0');

program
  .command('do-thing')
  .description('Does the thing')
  .option('-v, --verbose', 'Verbose output')
  .action(async (options) => {
    // Your logic here
  });

program.parse();

Python CLI 栈

# Using Click (recommended)
import click

@click.group()
def cli():
    """Tool description."""
    pass

@cli.command()
@click.option('--name', '-n', required=True)
@click.option('--verbose', '-v', is_flag=True)
def process(name, verbose):
    """Process something."""
    click.echo(f'Processing {name}')

if __name__ == '__main__':
    cli()

分发方式

本地优先应用

离线可用、数据归你所有的应用

适用场景：构建个人生产力应用时

本地优先架构

为什么个人工具要本地优先

Benefits:
- Works offline
- Your data stays yours
- No server costs
- Instant, no latency
- Works forever (no shutdown)

Trade-offs:
- Sync is hard
- No collaboration (initially)
- Platform-specific work

技术栈选择

简单本地存储

// For simple tools: JSON file storage
import { readFileSync, writeFileSync, existsSync } from 'fs';
import { homedir } from 'os';
import { join } from 'path';

const DATA_DIR = join(homedir(), '.mytool');
const DATA_FILE = join(DATA_DIR, 'data.json');

function loadData() {
  if (!existsSync(DATA_FILE)) return { items: [] };
  return JSON.parse(readFileSync(DATA_FILE, 'utf8'));
}

function saveData(data) {
  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR);
  writeFileSync(DATA_FILE, JSON.stringify(data, null, 2));
}

用 SQLite 处理更复杂的工具

// better-sqlite3 for Node.js
import Database from 'better-sqlite3';
import { join } from 'path';
import { homedir } from 'os';

const db = new Database(join(homedir(), '.mytool', 'data.db'));

// Create tables on first run
db.exec(`
  CREATE TABLE IF NOT EXISTS items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

// Fast synchronous queries
const items = db.prepare('SELECT * FROM items').all();

从脚本到产品的进化

将脚本发展为真正的产品

适用场景：个人工具展现出潜力时

进化路径

阶段 1：个人脚本

Characteristics:
- Only you use it
- Hardcoded values
- No error handling
- Works on your machine

Time: Hours to days

阶段 2：可分享工具

Add:
- README explaining what it does
- Basic error messages
- Config file instead of hardcoding
- Works on similar machines

Time: Days

阶段 3：公开工具

Add:
- Installation instructions
- Cross-platform support
- Proper error handling
- Version numbers
- Basic tests

Time: Week or two

阶段 4：产品

Add:
- Landing page
- Documentation site
- User support channel
- Analytics (privacy-respecting)
- Payment integration (if monetizing)

Time: Weeks to months

该产品化的信号

潜在陷阱

工具只能在你的环境中运行

严重程度：中

情况：分享脚本时别人跑不起来

症状：

• 我这能跑
• 别人的脚本报错
• 路径找不到
• 命令找不到

为什么会坏： 硬编码了绝对路径。 依赖你本地安装的工具。 假设了你的操作系统/Shell。 使用了你的认证令牌。

推荐修复：

让工具可移植

常见移植问题

路径移植性

// Bad
const dataFile = '~/data.json';

// Good
import { homedir } from 'os';
import { join } from 'path';
const dataFile = join(homedir(), '.mytool', 'data.json');

依赖检查

import { execSync } from 'child_process';

function checkDep(cmd, installHint) {
  try {
    execSync(`which ${cmd}`, { stdio: 'ignore' });
  } catch {
    console.error(`Missing: ${cmd}`);
    console.error(`Install: ${installHint}`);
    process.exit(1);
  }
}

checkDep('ffmpeg', 'brew install ffmpeg');

跨平台注意事项

import { platform } from 'os';

const isWindows = platform() === 'win32';
const isMac = platform() === 'darwin';
const isLinux = platform() === 'linux';

// Path separator
import { sep } from 'path';
// Use sep instead of hardcoded / or \

配置变得不可管理

严重程度：中

情况：配置项太多导致工具难以使用

症状：

• 配置文件巨大
• 用户被选项搞晕
• 你自己都忘了有哪些选项
• 每修一个 bug 就加一个 flag

为什么会坏： 用选项代替决策。 害怕做决定。 每个边界情况都变成了配置项。 配置文件比工具本身还大。

推荐修复：

配置治理

配置层级

Best to worst:
1. Smart defaults (no config needed)
2. Single config file
3. Environment variables
4. Command-line flags
5. Interactive prompts

Use sparingly:
6. Config directory with multiple files
7. Config inheritance/merging

有主见的默认值

// Instead of 10 options, pick reasonable defaults
const defaults = {
  outputDir: join(homedir(), '.mytool', 'output'),
  format: 'json',  // Not a flag, just pick one
  maxItems: 100,   // Good enough for most
  verbose: false
};

// Only expose what REALLY needs customization
// "Would I want to change this?" - not "Could someone?"

配置文件模式

// ~/.mytool/config.json
// Keep it minimal
{
  "apiKey": "xxx",       // Actually needed
  "defaultProject": "main"  // Convenience
}

// Don't do this:
{
  "outputFormat": "json",
  "outputIndent": 2,
  "outputColorize": true,
  "logLevel": "info",
  "logFormat": "pretty",
  "logTimestamp": true,
  // ... 50 more options
}

何时添加选项

个人工具无人维护

严重程度：低

情况：你构建的工具坏了但你不想修

症状：

• 脚本几个月没跑了
• 不记得它怎么工作的
• 依赖过期了
• 工作流变了

为什么会坏： 为旧工作流构建的。 依赖坏了。 失去了兴趣。 没给自己写文档。

推荐修复：

可持续的个人工具

为遗忘而设计

Assume future-you won't remember:
- Why you built this
- How it works
- Where the data is
- What the dependencies do

Build accordingly:
- README with WHY, not just WHAT
- Simple architecture
- Minimal dependencies
- Data in standard formats

最小依赖策略

自文档化模式

#!/usr/bin/env node
/**
 * WHAT: Converts X to Y
 * WHY: Because Z process was manual
 * WHERE: Data in ~/.mytool/
 * DEPS: Needs ffmpeg installed
 *
 * Last used: 2024-01
 * Still works as of: 2024-01
 */

// Tool code here

优雅降级

// When things break, fail helpfully
try {
  await runMainFeature();
} catch (err) {
  console.error('Tool broken. Error:', err.message);
  console.error('');
  console.error('Data location: ~/.mytool/data.json');
  console.error('You can manually access your data there.');
  process.exit(1);
}

何时放手

Signs to abandon:
- Haven't used in 6+ months
- Problem no longer exists
- Better tool now exists
- Would rebuild differently

How to abandon gracefully:
- Archive in clear state
- Note why abandoned
- Export data to standard format
- Don't delete (might want later)

有安全漏洞的个人工具

严重程度：高

情况：你的个人工具暴露了敏感数据或访问权限

症状：

• 源码中有 API key
• 工具在网络上可访问
• Git 历史中有凭证
• 个人数据暴露

为什么会坏： "这只是给自己用的"心态。 凭证写在代码里。 没有输入验证。 意外暴露。

推荐修复：

个人工具的安全

常见错误

凭证管理

// Never in code
const API_KEY = 'sk-xxx'; // BAD

// Environment variable
const API_KEY = process.env.MY_API_KEY;

// Config file (gitignored)
import { readFileSync } from 'fs';
const config = JSON.parse(
  readFileSync(join(homedir(), '.mytool', 'config.json'))
);
const API_KEY = config.apiKey;

仅限本地的服务器

// If your tool has a web UI
import express from 'express';
const app = express();

// ALWAYS bind to localhost for personal tools
app.listen(3000, '127.0.0.1', () => {
  console.log('Running on http://localhost:3000');
});

// NEVER do this for personal tools:
// app.listen(3000, '0.0.0.0') // Exposes to network!

分享前检查

Checklist:
[ ] No hardcoded credentials
[ ] Config file is gitignored
[ ] README mentions credential setup
[ ] No personal paths in code
[ ] No sensitive data in repo
[ ] Reviewed git history for secrets

验证检查

硬编码绝对路径

严重程度：中

消息：硬编码了绝对路径——使用 homedir() 或环境变量。

修复操作：使用 os.homedir() 或 path.join 构建可移植路径

硬编码凭证

严重程度：严重

消息：疑似硬编码凭证——使用环境变量或配置文件。

修复操作：移至 process.env.VAR 或外部配置文件（gitignore 掉）

服务器绑定到所有接口

严重程度：高

消息：服务器暴露在网络上——个人工具应绑定 localhost。

修复操作：使用 '127.0.0.1' 或 'localhost' 代替 '0.0.0.0'

缺少错误处理

严重程度：中

消息：同步操作没有错误处理——用 try/catch 包裹。

修复操作：添加 try/catch 以提供友好的错误信息

CLI 没有帮助信息

严重程度：低

消息：CLI 没有帮助——未来的你会忘记怎么用。

修复操作：为 CLI 命令添加 .description() 和 --help

工具没有 README

严重程度：低

消息：没有 README——给未来的自己写个文档。

修复操作：添加 README，包含：做什么、为什么构建、怎么用

遗留调试日志

严重程度：低

消息：代码中遗留了调试日志——删除或使用正式的日志工具。

修复操作：删除调试日志或使用带级别的正式日志工具

脚本缺少 Shebang

严重程度：低

消息：脚本缺少 shebang——无法直接执行。

修复操作：在文件顶部添加 #!/usr/bin/env node（或 python3）

工具没有版本号

严重程度：低

消息：没有版本追踪——更新时会造成混乱。

修复操作：在 package.json 中添加 version 并添加 --version flag

协作

委派触发条件

• sell|monetize|SaaS|charge -> micro-saas-launcher（将个人工具产品化）
• browser extension|chrome extension -> browser-extension-builder（构建浏览器工具）
• automate|workflow|cron|trigger -> workflow-automation（自动化设置）
• API|server|database|postgres -> backend（后端基础设施）
• telegram bot -> telegram-bot-builder（Telegram 工具）
• AI|GPT|Claude|LLM -> ai-wrapper-product（AI 驱动的工具）

CLI 工具变成产品

技能：personal-tool-builder, micro-saas-launcher

工作流：

1. Build CLI for yourself
2. Share with friends/colleagues
3. Get feedback and iterate
4. Add web UI (optional)
5. Set up payments
6. Launch publicly

个人自动化栈

技能：personal-tool-builder, workflow-automation, backend

工作流：

1. Identify repetitive task
2. Build script to automate
3. Add triggers (cron, webhook)
4. Store results/logs
5. Monitor and iterate

AI 驱动的个人工具

技能：personal-tool-builder, ai-wrapper-product

工作流：

1. Identify task AI can help with
2. Build minimal wrapper
3. Tune prompts for your use case
4. Add to daily workflow
5. Consider sharing if useful

浏览器工具变扩展

技能：personal-tool-builder, browser-extension-builder

工作流：

1. Build bookmarklet or userscript
2. Validate it solves the problem
3. Convert to proper extension
4. Add to Chrome/Firefox store
5. Share with others

相关技能

配合使用效果好：micro-saas-launcher, browser-extension-builder, workflow-automation, backend

适用场景

• 用户提到或暗示：构建工具
• 用户提到或暗示：个人工具
• 用户提到或暗示：解决我的痛点
• 用户提到或暗示：解决我的问题
• 用户提到或暗示：CLI 工具
• 用户提到或暗示：本地应用
• 用户提到或暗示：自动化我的
• 用户提到或暗示：为自己构建

局限性

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请停下来请求澄清。