Superpower 仓库定位

• Repo: oldwinter/superpower-practice（private）
• 技术栈：TypeScript + Node.js + Vitest
• 主题：一个 Todo CLI 的完整工程化实现
• 关键思想：用“计划驱动 + TDD”把需求稳定落地

目标（docs/plans）

• JSON 持久化
• Priority（high/medium/low）
• 完成/删除/过滤/搜索/排序
• 最终交付可运行 CLI，而不是只写函数

核心原理（你要的“Superpower 原理”）

把系统拆成 4 层能力并做增量闭环：

1. 类型约束（types）
2. 持久化抽象（store）
3. 业务编排（service）
4. 命令入口（cli）

每次功能都走： 计划 -> 先写失败测试 -> 最小实现 -> 通过 -> commit。

证据文件

• 设计：docs/plans/2026-02-26-todo-cli-design.md
• 执行计划：docs/plans/2026-02-26-todo-cli-plan.md
• 增量计划：docs/plans/2026-02-26-search-sort-plan.md
• 运行层：src/types.ts | store.ts | service.ts | cli.ts
• 质量层：tests/*.test.ts
• 演进轨迹：git log --oneline

types.ts（数据契约）

• Priority 联合类型：high/medium/low
• Todo 结构： id, title, completed, priority, createdAt
• 价值：业务行为先被类型边界约束

store.ts（持久层）

• TodoStore.load()：不存在文件 => []
• TodoStore.save()：整表覆盖写入 JSON
• 默认文件：./todos.json
• 价值：CLI/Service 不直接碰 fs 细节

service.ts（业务层核心）

• add/list/complete/remove/search
• list 支持 filter + sort(priority)
• complete/remove 对不存在 id 抛错
• search 大小写不敏感
• 价值：把“规则”从 CLI 分离出来

cli.ts（交互层）

• 解析 process.argv
• 命令：add/list/search/done/remove
• 参数校验与 usage 提示
• 仅做“薄封装”
• 真正业务都委托给 service

单一事实来源（State）

todos.json 就是唯一持久化状态

所有命令本质： 读取数组 -> 变换数组 -> 覆盖写回

ID 生成策略

Date.now().toString(36) + randomSuffix

含义：

• 可读且够轻量
• 通过随机后缀降低同毫秒碰撞风险
• 不引入外部 UUID 依赖

分层契约

CLI -> Service -> Store -> JSON

上层依赖下层接口， 下层不关心上层输入方式。

架构本质

这是典型“Transaction Script + Repository”模型：

• 每个命令对应一次事务脚本
• Store 作为超轻量仓储
• 通过 TypeScript 类型和测试把隐式规则显式化

add 命令

1. 解析标题 + -p
2. service.add() 创建 Todo
3. 默认 priority=medium
4. 持久化并打印 [id] title (priority)

list 命令

• 支持 --filter all|done|pending
• 支持 --sort priority
• 非法 sort 直接报错退出
• 输出格式含状态：done/pending

search 命令

• 输入关键字
• service.search() 执行 contains 匹配
• 大小写不敏感
• 空关键字返回空结果（防误检）

done 命令

• 根据 id 标记 completed=true
• 找不到直接抛 Todo not found
• CLI 负责展示“Completed: ...”

remove 命令

• 根据 id 删除
• 未找到同样抛错
• 持久化后返回 Removed.

filter + sort 的执行顺序

1. 先 filter（done/pending/all）
2. 后 sort(priority)

priority 规则：high(0) < medium(1) < low(2) => 保障“高优先级先看到”

search 算法

title.toLowerCase().includes(keyword.toLowerCase())

特点：

• 简单稳定
• O(n) 扫描
• 无索引，适合小规模 todo

错误语义

• 参数缺失 -> CLI usage + exit(1)
• 非法 sort -> 明确报错
• 业务对象不存在 -> Service 抛错

=> 输入错误和业务错误职责清晰

状态机视角

Todo 状态：pending -> done（单向） 集合操作：add / remove / search / list(filter/sort)

每条命令都可视为对 Todo[] 的确定性变换。 这就是该仓库“可解释、可测试、可被 AI 管理”的核心基础。

Plan-First

先写设计与实施计划（docs/plans）

• 定义目标、架构、约束
• 把功能拆为任务与步骤
• 明确每步的“失败预期”与“通过条件”

Superpower 指令化开发

计划文档里有明确提示：

• superpowers:executing-plans
• superpowers:subagent-driven-development

本质：把 AI 从“自由发挥”收敛到“有约束执行”。

TDD 循环（每个任务重复）

1. 写失败测试
2. 运行并确认失败原因
3. 写最小实现
4. 再跑测试确认通过
5. commit

=> 这让每个改动可验证、可回滚、可审查。

演进轨迹（git log）

init -> 设计文档 -> types -> store -> service(add/list) -> service(complete/remove/filter) -> cli -> search -> sort -> cli扩展 -> review修复

这条时间线体现“从骨架到能力，再到质量补丁”的增量式构建原理。

为什么这种方法对 AI 时代有效

• 计划把上下文结构化，减少模型跑偏
• 测试把正确性外包给机器
• 小步提交降低回归半径
• 可把任务继续外包给 agent 协同执行

测试矩阵

• types.test.ts：类型契约
• store.test.ts：持久化读写与覆盖行为
• service.test.ts：业务规则 + 异常 + filter/sort/search 组合

策略：真实临时文件，不用 mock，覆盖真实 I/O 路径

当前验证结果

执行 npm test：

• 3 个测试文件通过
• 24 个测试用例全部通过

=> 功能与回归基线处于健康状态

能力保证（What is guaranteed）

• 数据结构一致（TypeScript strict）
• 操作语义一致（Service）
• 命令入口行为可预期（CLI）
• 核心回归可自动检测（Vitest）

这四项共同构成“可维护性超能力”。

当前权衡（Trade-offs）

• 单文件 JSON：简单，但并发与规模能力弱
• 同步 fs：实现直观，但吞吐有限
• 手写 argv 解析：轻量，但可扩展性一般
• includes 搜索：够用，但无全文索引能力

演进方向（如果继续做）

1. 替换持久层：SQLite / Postgres
2. CLI 框架化：commander/yargs
3. 更强查询：标签、截止日、全文索引
4. 多端同步：API 层 + Auth
5. 接入 MCP：让 AI 直接 CRUD 任务

对你当前场景的意义

这套 Superpower 原理已经具备“AI 可控任务系统”的骨架：

• 规则集中在 service，便于 AI 调用
• 状态结构稳定，便于审计和自动化
• 测试先行，便于持续迭代而不炸

所以它非常适合作为“滴答清单替代路线”的底层方法论模板。