阶段性大项目：构建 CLI 书签管理器

忘掉 todo 应用。你要做一个你真正会用的东西：一个命令行书签管理器，带模糊搜索（Fuzzy Search）、标签和 Markdown 导出。

为什么不做 Todo App？

每个教程都以 todo 应用结尾。很无聊，你不会用它，也没法拉伸你的技能。相反，你要构建 bm -- 一个 CLI 书签管理器：

保存 URL，带标题、标签和笔记
用模糊搜索查找书签
导出收藏为 Markdown
所有数据存在本地 JSON 文件
可以真正替代你浏览器里那堆从来不整理的书签

这个项目会用到 Ch1-4 的所有内容：工具调用、CLAUDE.md、上下文管理和 Git 工作流。

前置技能

[x] Ch1：Claude Code 已安装，理解工具调用和权限
[x] Ch2：会写 CLAUDE.md，理解记忆系统
[x] Ch3：会监控上下文并在需要时 compact
[x] Ch4：能用 Claude 完成 Git 工作流

项目规格

命令

bm add https://example.com --title "Example" --tags web,reference
bm add https://github.com/anthropics/claude-code --tags tools,ai --note "The CLI itself"
bm list
bm list --tag ai
bm search "claude"          # 跨标题、URL、笔记、标签的模糊搜索
bm open 3                   # 用默认浏览器打开第 3 条书签
bm delete 5
bm export                   # 导出所有书签为 Markdown
bm export --tag ai          # 导出筛选后的书签
bm stats                    # 显示总数、热门标签、最近添加

技术要求

语言：Python 3.10+
存储：JSON 文件（~/.bm/bookmarks.json）
CLI 解析：argparse 或 click
模糊搜索：简单的子串匹配就行，用 fuzzywuzzy/thefuzz 是加分项
测试：pytest
代码规范：你在 CLAUDE.md 中定义的

导出格式

markdown

# Bookmarks

## ai
- [Claude Code CLI](https://github.com/anthropics/claude-code) - The CLI itself
- [Anthropic Docs](https://docs.anthropic.com) - Official API documentation

## web
- [Example](https://example.com)

## reference
- [MDN Web Docs](https://developer.mozilla.org)

---
*Exported on 2026-04-10 | 42 bookmarks | 8 tags*

分步指南

第一步：项目搭建 (Ch1 + Ch2)

bash

mkdir -p ~/claude-demos/capstone-bm && cd ~/claude-demos/capstone-bm
git init

创建 CLAUDE.md：

bash

cat > CLAUDE.md << 'EOF'
# bm -- CLI Bookmark Manager

## Key Commands
- Run: python -m bm <command>
- Test: pytest
- Test single: pytest tests/test_service.py -v

## Tech Stack
- Python 3.10+
- Testing: pytest
- CLI: argparse
- Storage: JSON file at ~/.bm/bookmarks.json

## Code Standards
- Type hints on all functions
- Docstrings in Google style
- File names: snake_case
- Constants: UPPER_SNAKE_CASE
- No bare except clauses
- Return types on all public functions

## Project Structure
- src/bm/ -- main source
- tests/ -- test files, mirror src/ structure
- Data: ~/.bm/bookmarks.json

## Commit Convention
- Conventional Commits (feat:, fix:, test:, refactor:)
- One logical change per commit
- English commit messages

## Voice
- Be direct. Skip the preamble.
- No filler. When done, say "Done."
EOF

启动 Claude：

bash

claude

Set up the project structure:
- src/bm/ directory with __init__.py and __main__.py
- tests/ directory
- pyproject.toml with pytest config and a console_scripts entry point for "bm"
- A .gitignore for Python projects

Then commit to main.

第二步：数据模型和存储 (Ch1 + Ch4)

Create feature/core branch.

Implement src/bm/models.py:
- Bookmark dataclass: id (auto-increment), url, title, tags (list[str]), note (optional), created_at (ISO datetime)

Implement src/bm/storage.py:
- BookmarkStore class that loads/saves from ~/.bm/bookmarks.json
- Methods: add, get_by_id, delete, list_all, search, filter_by_tag
- search should do case-insensitive substring matching across url, title, note, and tags
- Handle the case where ~/.bm/ doesn't exist yet

Commit.

第三步：业务逻辑 (Ch1)

Implement src/bm/service.py:
- BookmarkService wrapping BookmarkStore
- add_bookmark(url, title=None, tags=None, note=None) -- auto-fetch title from URL if not provided (use urllib)
- delete_bookmark(id)
- search_bookmarks(query)
- get_stats() -- total count, tag frequency, last 5 added
- export_markdown(tag_filter=None) -- generate the markdown export format

Commit.

第四步：CLI 界面 (Ch1)

Implement src/bm/cli.py with argparse:
- bm add <url> [--title] [--tags comma,separated] [--note "text"]
- bm list [--tag filter]
- bm search <query>
- bm open <id>  (use webbrowser.open)
- bm delete <id>
- bm export [--tag filter]
- bm stats

Wire it up in __main__.py so "python -m bm" works.
Commit.

第五步：测试 (Ch1 + Ch3)

Write comprehensive tests:
- test_models.py: Bookmark creation, serialization
- test_storage.py: CRUD operations, file handling, empty state
- test_service.py: search, stats, export format
- test_cli.py: CLI argument parsing (mock the service layer)

Use a tmp_path fixture for storage tests so we don't touch real ~/.bm/

Run all tests. Fix anything that fails.
Commit.

在这里检查 /context。如果超过 50%，compact 一下：/compact keep the project structure, all file paths, and test results

第六步：合并和收尾 (Ch4)

Switch to main, merge feature/core.
Show the full git log.
Then run the tool manually:
  python -m bm add "https://github.com/anthropics/claude-code" --title "Claude Code" --tags tools,ai --note "CLI for Claude"
  python -m bm add "https://docs.python.org" --title "Python Docs" --tags python,reference
  python -m bm list
  python -m bm search "claude"
  python -m bm stats
  python -m bm export

第七步：验证

退出 Claude，手动测试：

bash

python -m bm list
python -m bm search "python"
python -m bm export --tag reference

验收标准

项目	要求	怎么检查
CLAUDE.md	完整且针对项目	看文件内容
项目结构	src/bm/ + tests/	`ls -R`
所有命令能用	add、list、search、delete、export、stats	每个都跑一遍
数据持久化	书签在进程退出后还在	添加，退出，再 list
搜索能用	跨所有字段匹配	`bm search "python"`
导出能用	生成有效的 Markdown，按标签分组	`bm export`
测试通过	全部绿色	`pytest -v`
Git 历史	4 次以上有意义的原子提交	`git log --oneline`
功能分支	使用并合并了	`git log --graph --oneline`
代码质量	有类型注解、docstring、没有裸 except	看源码

进阶挑战

基础功能完成后，在新的功能分支里尝试这些：

浏览器导入：解析 Chrome/Firefox 的书签导出（HTML 格式）并导入到 bm
重复检测：添加已存在的 URL 时发出警告
交互模式：bm interactive 打开一个带方向键导航的 TUI 界面
链接检查：bm check 验证所有书签 URL 是否还能访问（返回 200）
彩色输出：用 ANSI 颜色高亮标签、状态指示和搜索匹配

每一个都是分支策略和原子提交的好练习。

备选项目：Git 统计分析器

如果书签不是你的菜，可以做一个 git 统计分析器：

gitstats ~/my-project

Analyzing 1,247 commits across 18 months...

Top Contributors:
  alice    587 commits (47%)
  bob      412 commits (33%)
  charlie  248 commits (20%)

Most Productive Hours:
  10:00-11:00  ████████████████ 23%
  14:00-15:00  ████████████ 18%
  16:00-17:00  ██████████ 15%

Language Distribution:
  TypeScript   ████████████████████ 62%
  Python       ████████ 24%
  Shell        ████ 14%

Commit Patterns:
  Mon ████████████ 18%
  Tue ████████████████ 22%
  Wed ████████████████ 21%
  Thu ██████████████ 19%
  Fri ████████████ 18%
  Sat ██ 2%
  Sun ██ 0%

Hot Files (most changed):
  src/api/routes.ts         142 changes
  src/utils/helpers.ts       98 changes
  tests/api.test.ts          87 changes

同样的项目结构，同样的 CLAUDE.md 方法，同样的 Git 工作流。不同的输出而已。

你做出了什么

这不是教程练习。这是一个真实的工具。真的有人在用这样的书签管理器。如果你完整做了这个大项目：

你用 CLAUDE.md 配置了项目规范，Claude 遵守了这些规范
你在多步骤实现中管理了上下文
你用了功能分支和原子提交
你写了测试，让 Claude 修复了失败项
你做了一个你可能真的会继续用的东西

这就是入门阶段。后面的所有内容都建立在这些基础之上。

准备好了吗？ 阶段二：进阶篇解锁 Hooks、MCP 集成、子 agent，以及把 Claude Code 从助手变成自主开发系统的工具。

阶段性大项目：构建 CLI 书签管理器 ​

为什么不做 Todo App？ ​

前置技能 ​

项目规格 ​

命令 ​

技术要求 ​

导出格式 ​

分步指南 ​

第一步：项目搭建 (Ch1 + Ch2) ​

第二步：数据模型和存储 (Ch1 + Ch4) ​

第三步：业务逻辑 (Ch1) ​

第四步：CLI 界面 (Ch1) ​

第五步：测试 (Ch1 + Ch3) ​

第六步：合并和收尾 (Ch4) ​

第七步：验证 ​

验收标准 ​

进阶挑战 ​

备选项目：Git 统计分析器 ​

你做出了什么 ​

阶段性大项目：构建 CLI 书签管理器

为什么不做 Todo App？

前置技能

项目规格

命令

技术要求

导出格式

分步指南

第一步：项目搭建 (Ch1 + Ch2)

第二步：数据模型和存储 (Ch1 + Ch4)

第三步：业务逻辑 (Ch1)

第四步：CLI 界面 (Ch1)

第五步：测试 (Ch1 + Ch3)

第六步：合并和收尾 (Ch4)

第七步：验证

验收标准

进阶挑战

备选项目：Git 统计分析器

你做出了什么