编写程序，接受结果不完美，程序保存半成品创意，后续不定期迭代，慢慢打磨成完整作品。

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解决实际问题，如果你觉得这个工具好用，欢迎关注长安牧笛！