编写程序，接受结果不完美，程序保存半成品创意，后续不定期迭代，慢慢打磨成完整作品。
DraftVault — 半成品创意保管库 × 渐进式打磨系统
一、实际应用场景描述
你手机备忘录里有这些：
- "一个关于失忆咖啡师的短篇小说开头"（写了 300 字，停在主角走进店门）
- "App 想法：帮人管理药品库存"（画了草图，没动代码）
- "播客选题：为什么年轻人不想上班"（列了 5 个要点，没录）
- "水彩画：窗台上的多肉"（线稿画完，颜色没敢上）
它们不是垃圾。但它们也不是"作品"。它们卡在一个尴尬的中间态——不够好到发布，又不至于烂到删除。所以你既没推进，也没放弃，只是让它们在文件夹里慢慢积灰。
然后某天你清理手机，看着它们，心里有两个声音在打架：
- "这些都没完成，我果然什么都做不成。"
- "万一哪天灵感来了呢？"
DraftVault 就是为这些"未完成"而生的工程化工具——它不催你"赶紧做完"，也不让你"干脆删掉"。它做一件很温柔的事：给每个半成品一个家，记录它现在的状态，然后在你准备好的时候，帮你一步步把它打磨成作品。
二、引入痛点
痛点 本质问题 本工具解法
半成品无处安放 不是成品没地方存，是"中间态"没容器 专门的 Draft 实体 + 状态追踪
完美主义瘫痪 要么完美要么不做 状态机：种子→草稿→雏形→打磨→完成
找不到上次进度 重拾成本高 → 放弃 自动记录 last_focus_area + next_step
不知道从哪继续 面对半成品只有焦虑 每次打开只显示 next_action
没有版本记忆 改着改着把好的改没了 轻量版本快照（before/after）
完成的没有仪式感 做完就扔，没有闭环 completion_report 自动生成
同类半成品堆积 看不到全貌，重复造轮子 标签聚类 + 关联建议
三、核心逻辑讲解
理论基础（工程化映射）
1. 迭代设计（Iterative Design, Norman）
- 好设计不是一次成型的，是反复打磨的
- 每个版本都比上一个好一点
- 本工具用状态机 + 版本快照实现"渐进式完善"
2. 创作心理学（Amabile, 1996）
- 内在动机 + 适度挑战 = 创造力
- 完美主义是创造力的最大敌人之一
- 本工具把"完成"定义为一个过程而非事件
3. 版本控制思想（Git 哲学）
- commit 不是"完成"，是"此刻的状态"
- 每次迭代都是一个 checkpoint
- 本工具借鉴：每次打磨 = 一次 commit
4. 蔡格尼克效应（Zeigarnik Effect）
- 未完成的事占据工作记忆
- 外部化（写下来）能释放认知资源
- 本工具让半成品"安全存放"，不再占用脑子
核心流程
💡 捕捉半成品（30 秒，不评判质量）
↓
📋 记录当前状态
类型 / 完成度 0-100 / 当前卡点 / 下一步动作
↓
🏷️ 自动标签 + 关联建议（有没有相似的草稿？）
↓
📂 存入 Vault（按状态分组）
↓
🔄 不定期迭代（每次打开只做一件事）
├─ 系统推荐 next_action（基于状态 + 卡点）
├─ 用户执行 → 更新进度
├─ 自动打版本快照
└─ 如果方向变了 → 记录 pivot
↓
🎉 达到完成态 → 生成 completion_report
↓
📊 仪表盘：各状态分布 / 迭代频率 / 完成率
状态机设计
┌─────────┐
│ 🌱种子 │ ← 只有一个想法/标题
└────┬────┘
↓ 写了第一稿
┌─────────┐
│ 📝草稿 │ ← 有内容但不连贯
└────┬────┘
↓ 结构完整
┌─────────┐
│ 🧱雏形 │ ← 能看懂但粗糙
└────┬────┘
↓ 细节打磨
┌─────────┐
│ 💎打磨 │ ← 接近成品
└────┬────┘
↓ 发布/展示
┌─────────┐
│ ✅完成 │ ← 阶段性终点
└─────────┘
关键设计决策
决策 原因
状态机而非百分比 百分比模糊，状态名有行动暗示
每次只显示 next_action 降低重拾成本，避免 overwhelm
版本快照而非全文历史 轻量、可读、不膨胀
不催完成 压力是创意的天敌
关联建议 让相似的半成品互相滋养
本地 JSON 隐私 + 零依赖 + 可审计
四、代码模块化（六层架构）
目录结构
draftvault/ ← 26 个 Python 文件 / ~2100 行
├── main.py ← 入口层：Application 容器 + CLI 调度
├── config.py ← 配置层：状态/类型/提示词/菜单
│
├── models/ ← 数据模型层（@dataclass，不可变）
│ ├── enums.py ← 枚举：状态/类型/迭代类型
│ ├── draft.py ← Draft 实体（半成品核心）
│ ├── iteration.py ← Iteration 实体（每次打磨记录）
│ ├── version_snapshot.py ← VersionSnapshot 实体（快照）
│ └── completion_report.py ← CompletionReport 实体
│
├── storage/ ← 持久化层（Repository 模式）
│ └── json_store.py ← CRUD + 原子写入 + 自动备份
│
├── services/ ← 业务层（6 个 Service，单一职责）
│ ├── capture_service.py ← 半成品捕捉（快速录入）
│ ├── draft_service.py ← Draft CRUD + 状态流转
│ ├── iterate_service.py ← ★ 迭代引擎（推进/快照/建议）
│ ├── version_service.py ← 版本管理（快照/回滚/对比）
│ ├── suggestion_engine.py ← 关联建议 + next_action 推荐
│ └── review_service.py ← 仪表盘 + 报告 + 导出
│
├── cognition/ ← 认知干预层
│ ├── perfectionism_guard.py← 完美主义检测 + 去灾难化
│ └── progress_framing.py ← 进度重构（不跟完美比）
│
├── utils/ ← 工具层（纯函数，零业务依赖）
│ ├── cli_helper.py ← 终端交互
│ ├── dashboard.py ← 终端可视化
│ ├── statistics.py ← 均值/频次/趋势
│ ├── date_util.py ← 日期差/间隔
│ ├── text_processor.py ← 关键词/摘要
│ └── validator.py ← 校验
│
├── README.md / USAGE.md / CHEATSHEET.md
└── demo.py ← 一键跑通全流程
各层职责边界
层 能做什么 不能做什么
"main.py" 组装系统、路由菜单 不写业务逻辑
"config.py" 集中管理常量/状态/提示词 不含逻辑
"models/" 数据结构、校验、序列化 不读写文件
"storage/" 读写 JSON、备份、查询 不知道数据含义
"services/" 核心业务逻辑 不直接操作文件
"cognition/" 完美主义干预、进度重构 不修改数据
"utils/" 纯函数工具 零业务依赖
核心模块代码展示
1️⃣ 数据模型（不可变 + 状态流转）
# models/draft.py
@dataclass(frozen=False) # 允许状态更新（有审计）
class Draft:
"""半成品创意 —— 核心实体"""
draft_id: str
title: str
content_type: str = "写作" # 写作/代码/视觉/音乐/想法/其他
current_state: str = "seed" # seed→draft→prototype→polish→done
completion: int = 0 # 0-100
core_idea: str = "" # 一句话核心
current_text: str = "" # 当前内容
stuck_point: str = "" # 卡在哪里
next_action: str = "" # 下一步唯一动作
tags: List[str] = field(default_factory=list)
created_at: date = field(default_factory=date.today)
updated_at: date = field(default_factory=date.today)
iteration_count: int = 0
last_session_summary: str = ""
def __post_init__(self):
if not self.title.strip(): raise ValueError("标题不能为空")
if not (0 <= self.completion <= 100): raise ValueError("完成度 0-100")
if self.current_state not in STATE_FLOW: raise ValueError("非法状态")
def advance_state(self) -> bool:
"""状态推进（有向图，不可逆）"""
flow = STATE_FLOW[self.current_state]
if flow["next"] and self.completion >= flow["threshold"]:
self.current_state = flow["next"]
self.updated_at = date.today()
return True
return False
设计意图：状态机有向流转 + 阈值检查，防止"还没写就标完成"。
2️⃣ 迭代引擎（核心：推进 + 快照 + 建议）
# services/iterate_service.py
def iterate_interactive(self, draft_id: str) -> Optional[Iteration]:
"""一次迭代会话：做一件事 → 记录 → 快照"""
draft = self.draft_svc.get(draft_id)
if not draft: return None
# 1. 显示当前状态 + 建议的下一步
print(f"\n 📌 当前: {draft.title} ({draft.current_state})")
print(f" 🎯 建议下一步: {draft.next_action or '（请设置）'}")
# 2. 用户描述这次做了什么
what_done = prompt_text("这次做了什么？", required=True)
new_completion = prompt_int("完成度 (0-100)", 0, 100, default=draft.completion)
# 3. 打了快照（before → after）
snapshot = self.version_svc.take_snapshot(draft, label=f"iter_{draft.iteration_count+1}")
# 4. 更新 Draft
draft.current_text = prompt_text("当前内容（可粘贴）", required=False) or draft.current_text
draft.completion = new_completion
draft.stuck_point = prompt_text("还卡在哪？（可留空）", required=False) or ""
draft.next_action = prompt_text("下次唯一一步：", required=False) or draft.next_action
draft.iteration_count += 1
draft.updated_at = date.today()
draft.advance_state() # 自动推进状态
# 5. 记录迭代日志
iteration = Iteration(
draft_id=draft_id,
what_done=what_done,
completion_before=snapshot.completion_before,
completion_after=new_completion,
...
)
self.iteration_store.append(iteration.to_dict())
self.draft_svc.save(draft)
return iteration
设计意图：每次迭代 = 一个 commit。轻量、可追溯、不膨胀。
3️⃣ 版本快照（轻量 Git 思想）
# services/version_service.py
def take_snapshot(self, draft: Draft, label: str = "") -> VersionSnapshot:
"""在修改前打快照"""
snapshot = VersionSnapshot(
draft_id=draft.draft_id,
label=label,
completion_before=draft.completion,
content_before=draft.current_text,
)
# 存入版本历史
self.version_store.append(snapshot.to_dict())
# 只保留最近 N 个（防膨胀）
self._trim_old_versions(draft.draft_id, keep=20)
return snapshot
def compare_versions(self, draft_id: str, idx1: int, idx2: int) -> str:
"""对比两个版本的差异（行级）"""
versions = self._get_versions(draft_id)
v1 = versions[idx1].content_before
v2 = versions[idx2].content_before
# 简单行级 diff（不用 difflib 也可）
diff = difflib.unified_diff(
v1.splitlines(), v2.splitlines(),
fromfile=f"v{idx1}", tofile=f"v{idx2}",
lineterm="",
)
return "\n".join(diff)
4️⃣ 完美主义守护器（认知层）
# cognition/perfectionism_guard.py
class PerfectionismGuard:
"""检测完美主义信号，给出去灾难化提示"""
def scan(self, draft: Draft, text: str) -> List[str]:
warnings = []
# 信号1：完成度停滞在 80-99 不动
if draft.completion >= 80 and draft.iteration_count > 5:
warnings.append(
"🛡️ 这个草稿在 80%+ 停留了很久。"
"完美主义的高原期——继续微调边际收益很小。"
"建议：要么发布，要么锁起来 2 周再看。"
)
# 信号2：卡点描述含"不够好"
if "不够好" in (draft.stuck_point or "").lower():
warnings.append(
"🛡️ 「不够好」是完美主义的标志语言。"
"问自己：对谁不够好？按什么标准？这个标准合理吗？"
)
# 信号3：迭代只改细节不动结构
recent = self._recent_iterations(draft.draft_id, n=3)
if all(it.what_done.startswith(("改了", "调了", "修���")) for it in recent):
warnings.append(
"🛡️ 最近几次迭代都在做微调。"
"可能该做结构性突破了——换个角度，而不是换个字。"
)
return warnings
设计意图：不是阻止追求质量，而是识别"为了完美而拖延发布"的模式。
5️⃣ 进度重构器（认知层）
# cognition/progress_framing.py
def reframe(self, draft: Draft) -> List[str]:
"""用不同框架看同一个半成品"""
lines = []
# 框架1：跟昨天的自己比
if draft.iteration_count > 0:
lines.append(
f"你已经在它上面花了 {draft.iteration_count} 次迭代。"
"它比第一版好多少？——这才是真实的进度。"
)
# 框架2：完成度 ≠ 价值
if draft.completion < 50:
lines.append(
"完成度低不代表没价值。"
"很多伟大作品的雏形看起来都很可笑。"
)
# 框架3：半成品是资产
lines.append(
"每一个半成品都是一颗种子。"
"你不需要现在就让所有种子发芽——有些是为明年准备的。"
)
return lines
6️⃣ 入口层（依赖注入）
# main.py
class Application:
def __init__(self):
# 5 个 Store
self.draft_store = JSONStore(DATA_DIR/"drafts.json", ...)
self.iter_store = JSONStore(DATA_DIR/"iterations.json", ...)
self.version_store = JSONStore(DATA_DIR/"versions.json", ...)
self.report_store = JSONStore(DATA_DIR/"reports.json", ...)
self.tag_store = JSONStore(DATA_DIR/"tags.json", ...)
# 认知层（2 个组件）
self.guard = PerfectionismGuard()
self.framer = ProgressFraming()
# 业务层（6 个 Service）
self.capture_svc = CaptureService(self.draft_store)
self.draft_svc = DraftService(self.draft_store, self.tag_store)
self.iterate_svc = IterateService(...)
self.version_svc = VersionService(self.version_store, self.draft_store)
self.suggest_svc = SuggestionEngine(self.draft_store, self.tag_store)
self.review_svc = ReviewService(...)
项目统计
指标 数值
Python 文件 26 个
总代码量 ~2100 行
架构层数 6 层
外部依赖 0（仅标准库）
状态数 5 个（种子→草稿→雏形→打磨→完成）
内容类型 6 种（写作/代码/视觉/音乐/想法/其他）
认知干预 完美主义检测 + 进度重构
数据持久化 本地 JSON + 自动备份
五、README 文件
完整 README.md 已包含在项目中，核心内容：
# DraftVault
给所有"写了一半就停了"的东西一个安全的家。
## 安装
python 3.8+，仅标准库
## 快速开始
python demo.py # 看演示
python main.py # 正式使用
## 核心理念
半成品不是失败，是未来的作品在等一个合适的时机。
## 状态流转
🌱种子 → 📝草稿 → 🧱雏形 → 💎打磨 → ✅完成
## 设计原则
- 不催完成
- 每次只做一步
- 版本可追溯
- 完美主义会被温柔地提醒
- 本地优先
六、使用说明（USAGE.md 节选）
什么时候该记录一个半成品：
- ✅ 写了一半的文章/小说/诗
- ✅ 画了草图没上色的画
- ✅ 搭了骨架没填内容的项目
- ✅ 录了一半的音频/视频
- ❌ 还没开始的想法（先用别的工具捕捉）
- ❌ 已经放弃且不打算捡回来的（不需要 vault）
如何有效迭代：
- 每次打开只做一件事（不要"继续写"）
- 具体动作 > 模糊意愿（"加一段对话" > "改改看"）
- 允许倒退（有些迭代会让完成度下降，那是探索）
next_action 怎么写：
好 不好
给主角起一个名字 继续写
画出第二根线条 完善一下
写出函数签名 写代码
录 30 秒人声测试 做播客
版本快照什么时候看：
- 改坏了想回退 → 对比两个版本
- 觉得自己没进步 → 看最早的快照
- 准备发布 → 看完整迭代历史
七、核心知识点卡片（CHEATSHEET.md）
# 理论 工具对应
1 迭代设计（Norman） 状态机 + 每次迭代
2 完美主义瘫痪 PerfectionismGuard 检测
3 蔡格尼克效应 外部化释放记忆
4 版本控制思想（Git） 快照 + 对比 + 回滚
5 心流理论（Csikszentmihalyi） 状态匹配难度
6 成长型思维（Dweck） 进度跟自己比
7 最小可行产品（Ries） 种子状态可发布
8 创作习惯（Pressfield） 每天打开做一步
9 认知卸载（Sweller） 外部记忆减负
10 完成偏见（Behavioral Econ） completion_report 仪式
八、总结
DraftVault 不是一个"帮你完成作品"的工具，是一个"让半成品不再折磨你"的工具。
技术上，它展示了：
- 如何用 6 层架构 组织一个中等复杂度的 Python 项目
- 如何用 状态机 管理创作生命周期
- 如何用 快照模式 实现轻量版本控制
- 如何用 Git 哲学 设计迭代流程（commit ≠ 完成）
- 如何用 认知检测 温柔地对抗完美主义
心理学上，它坚持几个原则：
不催——压力是创意的天敌，催促只会制造更多半成品。
不评判——种子的价值不亚于果实。
不遗忘——每个半成品都被安全存放，随时可回来。
不替代专业帮助——严重创作障碍请寻求专业支持。
最终，这个工具想传达一件事：
你那些"写了一半就停了"的东西，不是你的耻辱。
它们是你的创作指纹——证明你是一个会开始的人。
而"会开始"，已经是大部分人都做不到的事了。
把���们存好。时机到了，它们会自己喊你。
利用AI解决实际问题，如果你觉得这个工具好用，欢迎关注长安牧笛！
)
