# https://github.com/emson/claudoro 项目说明书 生成时间：2026-07-02 13:47:42 UTC ## 目录 - [概述与快速上手](#page-1) - [系统架构与核心模块](#page-2) - [数据管理与统计仪表盘](#page-3) - [定制化、运维与故障排查](#page-4) ## 概述与快速上手 ### 相关页面 相关主题：[系统架构与核心模块](#page-2), [定制化、运维与故障排查](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/emson/claudoro/blob/main/README.md) - [package.json](https://github.com/emson/claudoro/blob/main/package.json) - [ROADMAP.md](https://github.com/emson/claudoro/blob/main/ROADMAP.md) - [CHANGELOG.md](https://github.com/emson/claudoro/blob/main/CHANGELOG.md) - [src/guide.js](https://github.com/emson/claudoro/blob/main/src/guide.js) - [src/output.js](https://github.com/emson/claudoro/blob/main/src/output.js) - [src/render/html-shell.js](https://github.com/emson/claudoro/blob/main/src/render/html-shell.js) - [src/render/dashboard.js](https://github.com/emson/claudoro/blob/main/src/render/dashboard.js) - [src/render/guide-html.js](https://github.com/emson/claudoro/blob/main/src/render/guide-html.js) - [src/label.js](https://github.com/emson/claudoro/blob/main/src/label.js) - [CONTRIBUTING.md](https://github.com/emson/claudoro/blob/main/CONTRIBUTING.md)
# 概述与快速上手 ## 项目定位与设计原则 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]()。 三种输出形态各司其职： | 输出形态 | 触发方式 | 用途 | 共享基础设施 | | --- | --- | --- | --- | | 终端面板 | 默认 | TTY 内彩色的 `🍅 Claudoro` 标题块 | `src/guide.js` 中的 `renderGuide`、`src/output.js` 中的 ANSI 助手 | | HTML 页面 | `--web` | 离线可读、可重建、可分享的仪表盘 | `src/render/html-shell.js` 中的 `BASE_CSS` 与 `htmlDocument()` | | JSON | `--json` | 给 Agent 或脚本消费的稳定 schema | 命令各自的序列化函数 | 这种"同一语义、三种外观"的模式由 `src/render/html-shell.js` 中的 `htmlDocument()` 统一提供 head、品牌头、页脚，页面专属 CSS 追加在 `BASE_CSS` 之后，确保 stats 仪表盘与 Pomodoro 指南在视觉上不会漂移 资料来源：[src/render/html-shell.js:1-15, 36-60]()。 ```mermaid flowchart LR A[pomo <verb>] --> B{输出形式} B -- 默认 --> C[TTY 终端面板
renderGuide / output] B -- --web --> D[HTML 文档
html-shell.js] B -- --json --> E[稳定 JSON schema] D --> F[stats 仪表盘
render/dashboard.js] D --> G[Pomodoro 指南
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）](https://github.com/emson/claudoro/blob/main/ROADMAP.md) - [CHANGELOG](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)（了解每个版本新增的动词与修复，例如 v0.1.4 的周期点重置、v0.1.2 的 `uninstall --purge`） - 社区反馈：[Issue #5 "Create video asset"](https://github.com/emson/claudoro/issues/5)（社区请求的视频素材演示，与本概述互补，适合非阅读型用户） --- ## 系统架构与核心模块 ### 相关页面 相关主题：[概述与快速上手](#page-1), [数据管理与统计仪表盘](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/emson/claudoro/blob/main/package.json) - [src/label.js](https://github.com/emson/claudoro/blob/main/src/label.js) - [src/output.js](https://github.com/emson/claudoro/blob/main/src/output.js) - [src/guide.js](https://github.com/emson/claudoro/blob/main/src/guide.js) - [src/render/html-shell.js](https://github.com/emson/claudoro/blob/main/src/render/html-shell.js) - [src/render/dashboard.js](https://github.com/emson/claudoro/blob/main/src/render/dashboard.js) - [src/render/guide-html.js](https://github.com/emson/claudoro/blob/main/src/render/guide-html.js) - [README.md](https://github.com/emson/claudoro/blob/main/README.md) - [CHANGELOG.md](https://github.com/emson/claudoro/blob/main/CHANGELOG.md) - [ROADMAP.md](https://github.com/emson/claudoro/blob/main/ROADMAP.md) - [CONTRIBUTING.md](https://github.com/emson/claudoro/blob/main/CONTRIBUTING.md)
# 系统架构与核心模块 ## 1. 架构总览与设计原则 Claudoro 是一个面向 Claude Code 的番茄钟插件，定位为「本地优先、无后台守护进程、零运行时依赖」的 CLI 工具。核心定位包括：从 `package.json` 中可见，`keywords` 涵盖 `claude-code / pomodoro / timer / cli / focus / productivity / status-line / plugin`，并明确以 MIT 协议发布，仓库作者为 Ben Emson 资料来源：[package.json](https://github.com/emson/claudoro/blob/main/package.json)。`README.md` 与 `ROADMAP.md` 中反复强调三条「Out of scope (by design)」原则：无网络与账号同步（local-first）、核心仅使用 Node 标准库（runtime 无依赖）、不引入后台守护进程（wall-clock 调度，D-006a）资料来源：[ROADMAP.md](https://github.com/emson/claudoro/blob/main/ROADMAP.md)。 整个代码库遵循「推导而非存储」（derive, don't store, D-007）、「内容即数据而非标记」（content as data）、「纯函数优先」（pure / total functions）等原则，使得终端面板与 HTML 页面在视觉与内容上能够保持一致而不会漂移。 ## 2. 模块划分与职责 代码按 `M1..M12` 进行模块化编号，常见模块包括： | 模块编号 | 文件 | 职责 | |---------|------|------| | M1 | `src/label.js` | 标签与 #tag 文本的纯函数转换，负责 `appendText`、`normaliseTag` 等工具 | | M6 | `src/output.js` | 终端 ANSI 着色、`pomo help` 命令索引、状态输出助手（`phaseWord`、`phaseColor`） | | M9 | `src/render/dashboard.js` | `pomo stats --web` 的自包含 HTML 仪表盘渲染器 | | M10 | `src/guide.js` + `src/render/guide-html.js` | 指南内容模型 `GUIDE`（冻结对象）及终端/HTML 双渲染 | | M7 | `pomo uninstall [--purge]` | 反向卸载与数据目录清理 | `M1` 在文件头注释中明确：「`label` 是一个自由文本字段，#tag 通过解析从同一字符串中还原，派生而非存储（D-007）」，这意味着撤销 (`undo`) 与恢复 (`restore`) 天然保持正确，无需独立 tags 字段资料来源：[src/label.js](https://github.com/emson/claudoro/blob/main/src/label.js)。`src/output.js` 中的 `phaseColor` 仅 3 行实现，刻意复制于 `render/segment.js` 以避免 M6 反向依赖 M3 资料来源：[src/output.js](https://github.com/emson/claudoro/blob/main/src/output.js)。 ```mermaid 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](https://github.com/emson/claudoro/blob/main/src/render/html-shell.js)。 `src/render/dashboard.js`（M9）依赖 `htmlDocument` 与 `derive.js` 的 `formatFocusMin` 工具，渲染纯函数 `(payload) => string`，无客户端 JS、无 CDN，可永久离线渲染；标签与 #tag 全部 HTML 转义资料来源：[src/render/dashboard.js](https://github.com/emson/claudoro/blob/main/src/render/dashboard.js)。`src/render/guide-html.js`（M10）则把同一份冻结的 `GUIDE` 数据折叠为 HTML，注释同样强调「内容即数据，每种渲染器决定表现」资料来源：[src/render/guide-html.js](https://github.com/emson/claudoro/blob/main/src/render/guide-html.js) 与 [src/guide.js](https://github.com/emson/claudoro/blob/main/src/guide.js)。 ## 4. 数据模型、决策记录与扩展路径 `GUIDE` 是一个 `Object.freeze` 后的纯数据结构，`schema: 1` 标注版本号；其章节 schema（`heading / body / steps / bullets / examples / cases / body2`）是 M10 模块化的契约，并由终端与 HTML 两个渲染器共用，确保「同一份内容绝不会两边漂移」资料来源：[src/guide.js](https://github.com/emson/claudoro/blob/main/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](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)。贡献流程则通过 `CONTRIBUTING.md` 指明：决策变更需先开讨论 issue，再写入 `decisions.md`；路线图仅在 GitHub Milestones 中维护，`ROADMAP.md` 仅保留「意图而非承诺」资料来源：[CONTRIBUTING.md](https://github.com/emson/claudoro/blob/main/CONTRIBUTING.md) 与 [ROADMAP.md](https://github.com/emson/claudoro/blob/main/ROADMAP.md)。 ## 5. 常见失败模式与约束 - **写错颜色常量**：因 `phaseColor` 在 `output.js` 与 `segment.js` 中各自维护，新增阶段需同步两边资料来源：[src/output.js](https://github.com/emson/claudoro/blob/main/src/output.js)。 - **添加 HTML 标签时漏转义**：所有用户输入必须经 `escapeHtml`，否则即使内容受信任也可能引发回归资料来源：[src/render/html-shell.js](https://github.com/emson/claudoro/blob/main/src/render/html-shell.js)。 - **新增 `pomo` 子命令时遗漏 `help` 索引**：每个 `cmdEntry` 都在 `output.js` 的命令列表中手工登记，需保持同步。 - **跨平台脚本执行**：`$EDITOR` 为多词命令（如 `code -w`）时，`pomo log open` 需降级为打印路径（0.1.4 已修复）资料来源：[CHANGELOG.md](https://github.com/emson/claudoro/blob/main/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](https://github.com/emson/claudoro/issues/5) 与 [最新发布说明 v0.1.5](https://github.com/emson/claudoro/compare/v0.1.4...v0.1.5)。 --- ## 数据管理与统计仪表盘 ### 相关页面 相关主题：[系统架构与核心模块](#page-2), [定制化、运维与故障排查](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/render/dashboard.js](https://github.com/emson/claudoro/blob/main/src/render/dashboard.js) - [src/render/html-shell.js](https://github.com/emson/claudoro/blob/main/src/render/html-shell.js) - [src/label.js](https://github.com/emson/claudoro/blob/main/src/label.js) - [src/derive.js](https://github.com/emson/claudoro/blob/main/src/derive.js) - [src/output.js](https://github.com/emson/claudoro/blob/main/src/output.js) - [src/render/guide-html.js](https://github.com/emson/claudoro/blob/main/src/render/guide-html.js) - [README.md](https://github.com/emson/claudoro/blob/main/README.md) - [CHANGELOG.md](https://github.com/emson/claudoro/blob/main/CHANGELOG.md) - [package.json](https://github.com/emson/claudoro/blob/main/package.json) - [ROADMAP.md](https://github.com/emson/claudoro/blob/main/ROADMAP.md)
# 数据管理与统计仪表盘 ## 概述 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]()。 ```mermaid flowchart LR A[history.jsonl
单一日志] --> B[derive.js
读取时计算] B --> C[stats payload] C --> D[终端面板
--默认--] C --> E[HTML 仪表盘
--web] B --> F[连续天数 / 热力图
按时段分布 / Top 标签
阶段结果分布] 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}`,统一输出 ``、``、番茄头(🍅 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`](https://github.com/emson/claudoro/blob/main/specs/decisions.md) — D-007、D-011、D-012 等架构决策的权威记录 - [`CONTRIBUTING.md`](https://github.com/emson/claudoro/blob/main/CONTRIBUTING.md) — 提交规范与模块地图 - [`SECURITY.md`](https://github.com/emson/claudoro/blob/main/SECURITY.md) — 出处签名的发布流程 - [`README.md`](https://github.com/emson/claudoro/blob/main/README.md) — 用户视角的命令速查与截图 --- ## 定制化、运维与故障排查 ### 相关页面 相关主题：[概述与快速上手](#page-1), [数据管理与统计仪表盘](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/emson/claudoro/blob/main/README.md) - [CHANGELOG.md](https://github.com/emson/claudoro/blob/main/CHANGELOG.md) - [ROADMAP.md](https://github.com/emson/claudoro/blob/main/ROADMAP.md) - [CONTRIBUTING.md](https://github.com/emson/claudoro/blob/main/CONTRIBUTING.md) - [package.json](https://github.com/emson/claudoro/blob/main/package.json) - [src/output.js](https://github.com/emson/claudoro/blob/main/src/output.js) - [src/label.js](https://github.com/emson/claudoro/blob/main/src/label.js) - [src/guide.js](https://github.com/emson/claudoro/blob/main/src/guide.js) - [src/render/html-shell.js](https://github.com/emson/claudoro/blob/main/src/render/html-shell.js) - [src/render/dashboard.js](https://github.com/emson/claudoro/blob/main/src/render/dashboard.js)
# 定制化、运维与故障排查 本页围绕 Claudoro 的**定制化配置、运维操作、故障排查**三大主题展开。Claudoro 是一个基于 Node.js 标准库构建的零运行时依赖番茄钟 CLI 工具（[`package.json`](https://github.com/emson/claudoro/blob/main/package.json)），所有数据本地存储，用户可通过环境变量、配置命令、文件编辑完成定制与维护。 ## 一、定制化 Claudoro 提供多种维度的定制能力，涵盖状态栏视图、自动切换模式、标签与备忘、颜色主题等。 ### 1. 视图与切换模式 `pomo view` 与 `pomo mode` 是两个核心配置命令，可在 `src/output.js` 中找到其默认与可选项： - **视图（view）**：`minimal | classic | full` 三种状态栏布局，默认为 `classic`（[`src/output.js:54-60`](https://github.com/emson/claudoro/blob/main/src/output.js)）。 - **模式（mode）**：`auto | balanced | manual` 三种阶段切换模式，默认为 `auto`，决定 `next`、`back`、`skip` 等动作的自动行为（[`src/output.js:48-53`](https://github.com/emson/claudoro/blob/main/src/output.js)）。 修改持久化保存至 `$XDG_STATE_HOME/claudoro/` 下的偏好文件，提示行底部会显示该路径（[`src/output.js:90-95`](https://github.com/emson/claudoro/blob/main/src/output.js)）。 ### 2. 标签（Tags）与标签规范化 `src/label.js` 中的 `normalizeTag` 实现了一套确定性的标签规范化规则：去除前导 `#`、转为小写、非字母数字字符折叠为单个 `-`、去除首尾短横。这意味着 `Code Review`、`code_review`、`#code-review` 在分组统计时都会归并到 `#code-review`（[`src/label.js:14-29`](https://github.com/emson/claudoro/blob/main/src/label.js)）。 `addTags` 在追加新标签时会先调用 `parseTags` 提取已存在的标签集合并做大小写无关的去重，避免重复写入（[`src/label.js:46-67`](https://github.com/emson/claudoro/blob/main/src/label.js)）。 ### 3. 主题与渲染层 所有 HTML 文档（统计仪表盘、教程页）共享 `src/render/html-shell.js` 中的 `BASE_CSS` 主题与 `htmlDocument` 文档外壳，包含 `--tomato` 主题色、统一的字体、卡片样式与页脚链接（[`src/render/html-shell.js:1-80`](https://github.com/emson/claudoro/blob/main/src/render/html-shell.js)）。`dashboard.js` 与 `guide-html.js` 仅追加各自特有的 CSS 与 widget，保证两页视觉一致性（[`src/render/dashboard.js:1-30`](https://github.com/emson/claudoro/blob/main/src/render/dashboard.js)）。 终端渲染器则通过 `bold`、`dim`、`tomato`、`cyan` 等辅助函数在 TTY/管道场景间自动降级，符合 `NO_COLOR` 规范（[`src/guide.js:30-55`](https://github.com/emson/claudoro/blob/main/src/guide.js)）。 ## 二、运维 ### 1. 数据与备份 所有状态、日志、偏好存放在 `$XDG_STATE_HOME/claudoro/`（默认 `~/.local/state/claudoro/`），由 `pomo log` 系列命令读写与展示： - `pomo log open`：使用 `$EDITOR` 打开日志文件，编辑器缺失或多词（如 `code -w`）时安全降级为仅打印路径，不会崩溃（[`CHANGELOG.md:34-38`](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)）。 - `pomo log backups` 与 `pomo restore ` 提供备份点回滚。 - `pomo undo [N]` 支持撤销最近 N 条记录，并提供 `--today`、`--dry-run`、`--yes` 等安全标志（[`src/output.js:78-83`](https://github.com/emson/claudoro/blob/main/src/output.js)）。 ### 2. 安装与卸载 首次安装后执行 `pomo setup` 完成初始化。卸载可通过 `pomo uninstall` 完成；`--purge` 会额外删除数据目录（历史、统计、备份、计时器状态），`--yes` 跳过交互确认（[`CHANGELOG.md:72-73`](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)）。 ### 3. 发布与版本 `pomo version`（亦可通过 `--version` / `-v`）打印已安装版本号，便于在脚本中判断能力（[`CHANGELOG.md:25-27`](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)）。当前最新发布为 **v0.1.5**（[`CHANGELOG.md:11-13`](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)）。 ## 三、故障排查 下表汇总了 v0.1.0–v0.1.5 期间修复过的典型故障与对应缓解手段： | 故障场景 | 触发条件 | 修复版本 / 缓解手段 | 来源 | |---|---|---|---| | `pomo log open` 在 `$EDITOR` 缺失或多词（如 `code -w`）时崩溃 | 环境变量解析错误 | 降级为打印文件路径；v0.1.4 | [CHANGELOG.md:34-38]() | | 跨天循环点累计不清零 | 跨午夜计算 cycle dots | 改为仅统计当日记录（本地午夜界定）；v0.1.4 | [CHANGELOG.md:28-33]() | | `dateOf` 对缺失或损坏的 `started` 字段抛错 | 手工编辑或部分字段丢失 | 改为 total 函数，回退至 epoch；v0.1.4 | [CHANGELOG.md:38-42]() | | Release workflow 固定到不存在的 `actions/checkout@v7` | CI 配置漂移 | 修正为 `@v4`；v0.1.5 | [CHANGELOG.md:18-21]() | | `pomo guide` 引用 404 的 URL | 外部链接失效 | 指向官方站点 `pomodorotechnique.com`；v0.1.3 | [CHANGELOG.md:60-63]() | | 遗忘计时器（abandoned）时长被全额计入专注时长 | 用户长时间离开后 `stop`/`next` | 引入 D-012 上限策略 `planned + max_overtime`（默认 30 分钟）；v0.1.0 | [CHANGELOG.md:80-88]() | 排查建议： 1. **数据异常**：若 `pomo stats` 显示异常长时长，先用 `pomo log` 检查原始记录，确认是否触发了 D-012 abandoned 规则（[`CHANGELOG.md:80-88`](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)）。 2. **编辑器启动失败**：通过 `echo $EDITOR` 验证环境变量值；遇到多词命令时降级行为已被覆盖。 3. **跨日统计**：cycle dots 按本地午夜分桶，跨越午夜的块按开始时间归属，预期在长休息后自动重置为 ○○○○（[`CHANGELOG.md:28-33`](https://github.com/emson/claudoro/blob/main/CHANGELOG.md)）。 4. **设计与权衡**：路线图与意图说明在 [`ROADMAP.md`](https://github.com/emson/claudoro/blob/main/ROADMAP.md) 中明示，**网络、账户、遥测、云同步、后台守护进程被刻意排除**（[`ROADMAP.md:18-25`](https://github.com/emson/claudoro/blob/main/ROADMAP.md)），任何相关诉求需先在 issue 讨论。 ## See Also - [项目主页与快速上手](README.md) - [架构决策日志](specs/decisions.md)（D-001..D-012） - [贡献指南](CONTRIBUTING.md) - [发布运维手册](RELEASING.md) - [安全策略](SECURITY.md) --- --- ## Doramagic 踩坑日志 项目：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