项目定位与设计原则

Claudoro 是一个面向 Claude Code 用户的本地优先（local-first）番茄钟插件，定位为"零运行时依赖、纯 Node 标准库"的 CLI 工具。其 package.json 将 claude-code、pomodoro、status-line、plugin 列为关键词，强调它是为 Claude Code 状态栏（statusLine）量身打造的专注计时器 资料来源：package.json:11-19。

项目的核心理念由 ROADMAP 明确表述：

• 本地优先：不做网络功能、账号体系、遥测或云同步，所有历史数据都落在本地状态目录
• 零依赖：核心保持仅使用 Node stdlib
• 无后台守护：调度由墙钟时间承担，daemonless（对应决策 D-006a）

资料来源：ROADMAP.md:13-20

所有架构决策集中记录在 specs/decisions.md，若想推翻或扩展某条决策，需要先开讨论 issue 并在决策日志中追加条目 资料来源：CONTRIBUTING.md:21-25。

命令架构与输出形态

Claudoro 的 CLI 围绕"动词（verb）+ 形式（modality）"组织。每个动词既能输出适合终端阅读的彩色面板，也能通过 --json 产出稳定的机器可读负载，或者通过 --web 落盘为自包含的 HTML 文件。src/output.js 中 pomo help 的命令索引按四组分类——TIMER、CONFIG、LOG & DATA、LEARN & SETUP——枚举了全部动词 资料来源：src/output.js:96-130。

三种输出形态各司其职：

这种"同一语义、三种外观"的模式由 src/render/html-shell.js 中的 htmlDocument() 统一提供 head、品牌头、页脚，页面专属 CSS 追加在 BASE_CSS 之后，确保 stats 仪表盘与 Pomodoro 指南在视觉上不会漂移 资料来源：src/render/html-shell.js:1-15, 36-60。

flowchart LR
  A[pomo <verb>] --> B{输出形式}
  B -- 默认 --> C[TTY 终端面板<br/>renderGuide / output]
  B -- --web --> D[HTML 文档<br/>html-shell.js]
  B -- --json --> E[稳定 JSON schema]
  D --> F[stats 仪表盘<br/>render/dashboard.js]
  D --> G[Pomodoro 指南<br/>render/guide-html.js]

快速上手流程

按照 README 与 output.js 中各命令的 next 指引，推荐的新人路径是：

1. 安装与接线：执行 pomo setup，它会安装命令文件、statusLine 配置与钩子，并保留用户原有的状态行（决策 D-005，通过组合而非覆盖实现） 资料来源：src/output.js:317-326
2. 启动第一个专注块：pomo start，可选 -t "text" 设置初始备注
3. 打标与备注：pomo note "..." 追加说明；pomo tag review 追加 #review（src/label.js 中的 normalizeTag 会自动去除前导 #、转小写、归一化为 kebab-case 并去重） 资料来源：src/label.js:18-30
4. 查看状态：pomo status 输出当前 phase、剩余时间、循环位置与今日统计（今日统计按 D-007 从日志派生，而非存储）
5. 复盘与可视化：pomo stats 在终端输出 streak、热力图、Top tags 等派生分析；pomo stats --web 落盘为自包含 HTML 并尝试打开浏览器；pomo guide --web 打开方法论页面 资料来源：README.md:60-78

若希望彻底卸载，pomo uninstall 仅恢复原状态线；若同时携带 --purge --yes，会永久删除整个数据目录（历史、stats、备份、状态文件） 资料来源：src/output.js:332-358。

关键约束与常见误区

• 数据目录位置：默认遵循 XDG_STATE_HOME，否则回落到 ~/.local/state/claudoro/。该路径会出现在 pomo help 的页脚 资料来源：src/output.js:138-140
• 标签的 # 前缀：在 shell 中裸 # 会被当作注释，因此 pomo tag review 更安全；脚本侧想直接带 # 也可，但会被 normalizeTag 同样处理 资料来源：src/output.js:67-72
• Web 页面含敏感数据：仪表盘会原样渲染用户标签，因此不适合"随手分享"；它是一个可重建的本地制品 资料来源：src/render/dashboard.js:8-16
• 本地下线原则：HTML 页面没有任何外部资源、无客户端 JS、参考链接为惰性锚点，因此离线永久可读 资料来源：src/render/guide-html.js:1-10

See Also

• 决策与架构原则（基于 specs/decisions.md 与 ROADMAP）
• CHANGELOG（了解每个版本新增的动词与修复，例如 v0.1.4 的周期点重置、v0.1.2 的 uninstall --purge）
• 社区反馈：Issue #5 "Create video asset"（社区请求的视频素材演示，与本概述互补，适合非阅读型用户）

1. 架构总览与设计原则

Claudoro 是一个面向 Claude Code 的番茄钟插件，定位为「本地优先、无后台守护进程、零运行时依赖」的 CLI 工具。核心定位包括：从 package.json 中可见，keywords 涵盖 claude-code / pomodoro / timer / cli / focus / productivity / status-line / plugin，并明确以 MIT 协议发布，仓库作者为 Ben Emson 资料来源：package.json。README.md 与 ROADMAP.md 中反复强调三条「Out of scope (by design)」原则：无网络与账号同步（local-first）、核心仅使用 Node 标准库（runtime 无依赖）、不引入后台守护进程（wall-clock 调度，D-006a）资料来源：ROADMAP.md。

整个代码库遵循「推导而非存储」（derive, don't store, D-007）、「内容即数据而非标记」（content as data）、「纯函数优先」（pure / total functions）等原则，使得终端面板与 HTML 页面在视觉与内容上能够保持一致而不会漂移。

2. 模块划分与职责

代码按 M1..M12 进行模块化编号，常见模块包括：

M1 在文件头注释中明确：「label 是一个自由文本字段，#tag 通过解析从同一字符串中还原，派生而非存储（D-007）」，这意味着撤销 (undo) 与恢复 (restore) 天然保持正确，无需独立 tags 字段资料来源：src/label.js。src/output.js 中的 phaseColor 仅 3 行实现，刻意复制于 render/segment.js 以避免 M6 反向依赖 M3 资料来源：src/output.js。

graph TD
  CLI[CLI 入口]
  Guide[GUIDE 数据模型 src/guide.js]
  Label[标签转换 src/label.js]
  Output[终端输出 src/output.js]
  Shell[HTML 共享壳 src/render/html-shell.js]
  Dashboard[仪表盘 src/render/dashboard.js]
  GuideHTML[指南 HTML src/render/guide-html.js]

  CLI --> Guide
  CLI --> Output
  CLI --> Label
  Guide --> GuideHTML
  Dashboard --> Shell
  GuideHTML --> Shell

3. 渲染层：终端与 HTML 双轨

Claudoro 将所有「静态、自包含、离线可读」的页面（指南、统计仪表盘）视为单一视觉语言的两面。src/render/html-shell.js 是该语言的唯一真实来源：导出 escapeHtml、BASE_CSS 与 htmlDocument()，其中 htmlDocument() 接受 { title, headline, body, css, generatedAt } 并返回完整 HTML 文档。模块头部注释明确指出「调用方必须对所有用户输入调用 escapeHtml」，从而以构造方式实现 XSS 防护资料来源：src/render/html-shell.js。

src/render/dashboard.js（M9）依赖 htmlDocument 与 derive.js 的 formatFocusMin 工具，渲染纯函数 (payload) => string，无客户端 JS、无 CDN，可永久离线渲染；标签与 #tag 全部 HTML 转义资料来源：src/render/dashboard.js。src/render/guide-html.js（M10）则把同一份冻结的 GUIDE 数据折叠为 HTML，注释同样强调「内容即数据，每种渲染器决定表现」资料来源：src/render/guide-html.js 与 src/guide.js。

4. 数据模型、决策记录与扩展路径

GUIDE 是一个 Object.freeze 后的纯数据结构，schema: 1 标注版本号；其章节 schema（heading / body / steps / bullets / examples / cases / body2）是 M10 模块化的契约，并由终端与 HTML 两个渲染器共用，确保「同一份内容绝不会两边漂移」资料来源：src/guide.js。

架构决策集中记录于 specs/decisions.md，决策编号 D-001..D-012 横跨：HTML 共享壳（D-011）、废弃时间处理（D-012）等；CHANGELOG.md 中可见 pomo uninstall --purge（M7, 0.1.2）、pomo version（0.1.4）、README 截图与外链修复（0.1.3）等演进节点，且所有版本遵守 SemVer 与 Keep a Changelog 规范资料来源：CHANGELOG.md。贡献流程则通过 CONTRIBUTING.md 指明：决策变更需先开讨论 issue，再写入 decisions.md；路线图仅在 GitHub Milestones 中维护，ROADMAP.md 仅保留「意图而非承诺」资料来源：CONTRIBUTING.md 与 ROADMAP.md。

5. 常见失败模式与约束

• 写错颜色常量：因 phaseColor 在 output.js 与 segment.js 中各自维护，新增阶段需同步两边资料来源：src/output.js。
• 添加 HTML 标签时漏转义：所有用户输入必须经 escapeHtml，否则即使内容受信任也可能引发回归资料来源：src/render/html-shell.js。
• 新增 pomo 子命令时遗漏 help 索引：每个 cmdEntry 都在 output.js 的命令列表中手工登记，需保持同步。
• 跨平台脚本执行：$EDITOR 为多词命令（如 code -w）时，pomo log open 需降级为打印路径（0.1.4 已修复）资料来源：CHANGELOG.md。

See Also

• 标签与 #tag 文本转换：见 src/label.js 与 pomo tag 帮助章节。
• 渲染层共享壳与 XSS 防护：见 src/render/html-shell.js。
• 自包含 HTML 仪表盘：见 src/render/dashboard.js 与 pomo stats --web。
• 终端双栏指南：见 src/guide.js 与 src/render/guide-html.js。
• 决策记录与路线图：specs/decisions.md、ROADMAP.md、GitHub Milestones。
• 社区反馈：参见 Issue #5 Create video asset 与 最新发布说明 v0.1.5。

概述

Claudoro 是一个本地优先的番茄钟命令行工具，强调「零运行时依赖、终端优先、状态行集成」。其数据管理围绕一条不可变的 JSONL 日志展开:每一次开始、暂停、跳过、停止都被追加为一条记录,而所有统计 — 连续天数、专注热力图、按小时分布、Top 标签、循环完成度 — 都在读取时由 derive.js 重新计算得出,而不是落库存储,从而天然具备可重建、可回滚、可手工修正的能力 资料来源：CHANGELOG.md:32-48。

仪表盘的呈现有两条平行的渲染路径:终端面板(默认,纯文本着色,适用于 NO_COLOR 与管道场景)与自包含 HTML 仪表盘(pomo stats --web),后者由 src/render/dashboard.js 实现,使用 src/render/html-shell.js 中的共享主题与文档外壳,确保与 Pomodoro 指南页面在视觉上完全一致 资料来源：src/render/dashboard.js:1-18。

数据模型与标签系统

每一条已完成的番茄钟块都拥有一个自由文本 label 字段,标签以 #kebab-case token 的形式嵌入该字符串中,而非独立字段。这样做的好处是撤销(pomo undo)与恢复(pomo restore)始终能精确还原,且仪表盘只需通过解析 label 字符串即可分组归类。src/label.js 中的 appendText 用于追加纯文本(无人为空格污染),而标签归一化函数会将 Code Review、code_review、#code-review 都收敛到 #code-review 资料来源：src/label.js:1-25。

flowchart LR
  A[history.jsonl<br/>单一日志] --> B[derive.js<br/>读取时计算]
  B --> C[stats payload]
  C --> D[终端面板<br/>--默认--]
  C --> E[HTML 仪表盘<br/>--web]
  B --> F[连续天数 / 热力图<br/>按时段分布 / Top 标签<br/>阶段结果分布]
  A --> G[备份 / 撤销 / 恢复]

该派生规则直接落实设计决策 D-007:任何手编辑过的记录都会在下次读取时自然重新统计,无需迁移脚本 资料来源：README.md:107-127。

仪表盘渲染

pomo stats --web 调用 src/render/dashboard.js(模块标记 M9,对应设计决策 D-011 的「自包含 HTML 页面」分支)。该渲染器是纯函数:接受统计数据 payload,返回一段完整的 HTML 文档字符串,不引用任何客户端 JS、不加载 CDN、不发起网络请求,因此可以离线永远渲染。出于「构造即安全」原则,所有用户可编辑的字符串(标签、备注、备注中混入的备注)都会通过 escapeHtml 转义,这意味着手工改写过的 JSONL 不会因此注入额外的标记 资料来源：src/render/dashboard.js:1-14。

视觉一致性来自 src/render/html-shell.js:CSS 变量 --tomato: #e4572e 定义品牌色,htmlDocument 接收 {title, headline, body, css, generatedAt},统一输出 <!doctype html>、<head>、番茄头(🍅 Claudoro)与底部站点链接;相同的页面外壳也被 src/render/guide-html.js 复用,因此统计仪表盘与指南页不可能在视觉上漂移 资料来源：src/render/html-shell.js:50-77。

热力图的强度梯度(0..4 五个等级)使用品牌番茄色调的渐变,空轨道以浅色底纹标识;时间戳 fmtWhen 将 epoch 秒转换成本地时间(示例输出 12 Jun 09:00),而日志本身仍以 UTC 存储 — 这同时照顾了「数据可迁移」与「视图友好」两个目标 资料来源：src/render/dashboard.js:23-44。

命令、配置与边界情况

pomo stats 提供三个互斥渲染形态:--web 打开浏览器,--json 输出 schema 带版本号的稳定 JSON 供脚本与代理使用,默认则为终端面板。pomo log 暴露逐条账本以核对原始数据,pomo undo 与 pomo restore 提供带备份的撤销/恢复通路。完整的命令索引与状态文件路径(XDG_STATE_HOME 或 ~/.local/state/claudoro/)由 src/output.js 输出 资料来源：src/output.js:154-218。

值得关注的边界情况:

• 被遗弃的番茄钟(D-012):若一个焦点块因为睡眠或离开而被数小时后才 stop / next 结束,只有 planned + max_overtime(默认 30 分钟)会被计入专注时间,记录会标记为 abandoned,真实跨度保留在 started / ended 字段。聚合在读取时应用同样的封顶,所以历史数据无需回填 资料来源：CHANGELOG.md:50-67。
• 当日循环点数(v0.1.4):循环中的「已完成/未完成」小圆点每日基于本地午夜重新派生,长休息会重置当日集合,而跨午夜的块按开始时间归入当日,因此不会出现跨日残留 资料来源：CHANGELOG.md:72-90。
• 缺日志的稳健性:dateOf 已是全函数,即使 started 字段缺失或被破坏,记录也会被划入 epoch 日而非抛错,保障手动编辑过的 JSONL 不会让仪表盘崩溃 资料来源：CHANGELOG.md:88-101。

路线图与原则

当前 0.1.x 阶段的重点是打磨跨平台细节并扩展统计/指南表面,不引入运行时依赖(核心仅使用 Node 标准库),也不引入后台守护进程 — 调度完全依赖本地系统时钟(D-006a),这与工具的本地优先哲学一致 资料来源：ROADMAP.md:11-19;资料来源：package.json:1-34。社区讨论追踪通过 GitHub Issues 与里程碑进行(参见社区热度最高的 #5「创建视频素材」,即为本主题相关的视觉化补充请求),而插件元数据 plugin.json 与版本号保持联动 资料来源：CHANGELOG.md:18-35。

另请参阅

• docs/decisions.md — D-007、D-011、D-012 等架构决策的权威记录
• CONTRIBUTING.md — 提交规范与模块地图
• SECURITY.md — 出处签名的发布流程
• README.md — 用户视角的命令速查与截图

一、定制化

Claudoro 提供多种维度的定制能力，涵盖状态栏视图、自动切换模式、标签与备忘、颜色主题等。

1. 视图与切换模式

pomo view 与 pomo mode 是两个核心配置命令，可在 src/output.js 中找到其默认与可选项：

• 视图（view）：minimal | classic | full 三种状态栏布局，默认为 classic（src/output.js:54-60）。
• 模式（mode）：auto | balanced | manual 三种阶段切换模式，默认为 auto，决定 next、back、skip 等动作的自动行为（src/output.js:48-53）。

修改持久化保存至 $XDG_STATE_HOME/claudoro/ 下的偏好文件，提示行底部会显示该路径（src/output.js:90-95）。

2. 标签（Tags）与标签规范化

src/label.js 中的 normalizeTag 实现了一套确定性的标签规范化规则：去除前导 #、转为小写、非字母数字字符折叠为单个 -、去除首尾短横。这意味着 Code Review、code_review、#code-review 在分组统计时都会归并到 #code-review（src/label.js:14-29）。

addTags 在追加新标签时会先调用 parseTags 提取已存在的标签集合并做大小写无关的去重，避免重复写入（src/label.js:46-67）。

3. 主题与渲染层

所有 HTML 文档（统计仪表盘、教程页）共享 src/render/html-shell.js 中的 BASE_CSS 主题与 htmlDocument 文档外壳，包含 --tomato 主题色、统一的字体、卡片样式与页脚链接（src/render/html-shell.js:1-80）。dashboard.js 与 guide-html.js 仅追加各自特有的 CSS 与 widget，保证两页视觉一致性（src/render/dashboard.js:1-30）。

终端渲染器则通过 bold、dim、tomato、cyan 等辅助函数在 TTY/管道场景间自动降级，符合 NO_COLOR 规范（src/guide.js:30-55）。

二、运维

1. 数据与备份

所有状态、日志、偏好存放在 $XDG_STATE_HOME/claudoro/（默认 ~/.local/state/claudoro/），由 pomo log 系列命令读写与展示：

• pomo log open：使用 $EDITOR 打开日志文件，编辑器缺失或多词（如 code -w）时安全降级为仅打印路径，不会崩溃（CHANGELOG.md:34-38）。
• pomo log backups 与 pomo restore <id> 提供备份点回滚。
• pomo undo [N] 支持撤销最近 N 条记录，并提供 --today、--dry-run、--yes 等安全标志（src/output.js:78-83）。

2. 安装与卸载

首次安装后执行 pomo setup 完成初始化。卸载可通过 pomo uninstall 完成；--purge 会额外删除数据目录（历史、统计、备份、计时器状态），--yes 跳过交互确认（CHANGELOG.md:72-73）。

3. 发布与版本

pomo version（亦可通过 --version / -v）打印已安装版本号，便于在脚本中判断能力（CHANGELOG.md:25-27）。当前最新发布为 v0.1.5（CHANGELOG.md:11-13）。

三、故障排查

下表汇总了 v0.1.0–v0.1.5 期间修复过的典型故障与对应缓解手段：

排查建议：

1. 数据异常：若 pomo stats 显示异常长时长，先用 pomo log 检查原始记录，确认是否触发了 D-012 abandoned 规则（CHANGELOG.md:80-88）。
2. 编辑器启动失败：通过 echo $EDITOR 验证环境变量值；遇到多词命令时降级行为已被覆盖。
3. 跨日统计：cycle dots 按本地午夜分桶，跨越午夜的块按开始时间归属，预期在长休息后自动重置为 ○○○○（CHANGELOG.md:28-33）。
4. 设计与权衡：路线图与意图说明在 ROADMAP.md 中明示，网络、账户、遥测、云同步、后台守护进程被刻意排除（ROADMAP.md:18-25），任何相关诉求需先在 issue 讨论。

See Also

• 项目主页与快速上手
• 架构决策日志（D-001..D-012）
• 贡献指南
• 发布运维手册
• 安全策略

Pitfall Log / 踩坑日志

项目：emson/claudoro

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://news.ycombinator.com/item?id=48745590 | host_targets=claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://news.ycombinator.com/item?id=48745590 | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48745590 | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48745590 | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48745590 | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48745590 | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48745590 | release_recency=unknown