cuaderno

# Cuaderno [](https://github.com/agustinvalencia/cuaderno/actions/workflows/ci.yml) [](https://codecov.io/gh/agustinvalencia/cuaderno) [](https://opensource.org/licenses/MPL-2.0) [](https://agustinvalencia.github.io/cuaderno) 一款实施**研究日志方法（RLM）**的笔记本管理工具，该方法是一种知识、任务和生活组织系统，专为实验研究人员设计，并特别适应多动症（ADHD）。 **命令**：`cdno`（别名：`cdrn`） **全名**：cuaderno（西班牙语意为“笔记本”或“日志”） **文档**：<https://agustinvalencia.github.io/cuaderno> — 完整的用户指南（概念、教程、CLI + MCP 参考）。源代码位于 [`docs-site/`](docs-site/)。 ## 快速入门 ### 安装 **Homebrew**（macOS + Linux，推荐）： ```bash brew install agustinvalencia/tap/cuaderno ``` 这会安装两个二进制文件 — `cdno`（用于日常循环的 CLI）和 `cdno-mcp`（用于 Claude / Kiro / Gemini CLI 的 MCP 服务器）。预构建的瓶子适用于 macOS arm64 + intel 和 Linux x86_64 + aarch64。 **桌面应用**（macOS，Apple Silicon）： ```bash # 因为应用是临时签名的，而不是经过公证的 — # 没有它，Gatekeeper 会阻止第一次启动。 brew install --cask agustinvalencia/tap/cuaderno-app xattr -dr com.apple.quarantine /Applications/cuaderno.app ``` 然后从应用程序启动 cuaderno。第一次启动时，应用会使用本地选择器询问你的笔记本文件夹，并记住它。`CUADERNO_VAULT_PATH` 仍然覆盖终端和开发环境，但对于 Finder 启动不再需要。完整的安装说明（手动 `.dmg`，注意事项）请参阅 [桌面应用指南](https://agustinvalencia.github.io/cuaderno/getting-started/desktop-app.html)。 **从源代码**（其他地方，或如果你想跟踪 `main`）： ```bash git clone https://github.com/agustinvalencia/cuaderno cd cuaderno cargo build --release --bins # 二进制文件位于 target/release/cdno 和 target/release/cdno-mcp。 # 将两者符号链接到某个 PATH 目录，例如： ln -s "$PWD/target/release/cdno" /usr/local/bin/cdno ln -s "$PWD/target/release/cdno-mcp" /usr/local/bin/cdno-mcp ``` 验证： ```bash cdno --version ``` ### 初始化笔记本 ```bash cdno init ~/notebook # 创建文件夹树 + .cuaderno/ 配置 cd ~/notebook ``` `init` 构建完整的笔记本结构（日志、项目、承诺、行动、投资组合……），并在 `.cuaderno/config.toml` 处写入本地配置。从任何子目录中，`cdno` 会自动发现笔记本根目录。 ### 五个命令的日常循环 捕获项目、排队行动、承诺截止日期、运行晨间视图、标记某事完成： ```bash # 1. 启动新项目。无标志时，在 TTY 中，cdno 会提示标题和上下文； # 输入或 `--no-interactive` 需要明确每个标志。相同的标志或提示模式适用于 # 每个变更动词 — 请参阅 docs/cli-ergonomics.md。 cdno project create --title "Surrogate model" --context work # 2. 添加下一个行动。 `--note` 创建一个显式行动笔记 # 以及用于多日工作的项目符号。 cdno action add --project surrogate-model \ --title "Run feature set B on full geometry mesh" \ --energy deep # 3. 承诺某事带有截止日期。 cdno commit create --title "Pay rent" --due 2026-06-01 --context personal # 4. 晨间定位：未来 48 小时内到期的承诺 + # 任何逾期的、活跃的项目及其下一个行动， # 以及建议的起点。 `--energy` 偏向于顶级行动匹配的项目。 cdno orient --energy deep # 5. 标记行动完成。维基链接的项目符号存档 # 其附带的笔记到 actions/_done/<year>/ 自动， # 文件因追加 lint 而被锁定前缀编辑。 cdno action complete --project surrogate-model --query "feature set B" ``` 有关完整动词列表，请参阅：`cdno --help`，然后 `cdno <verb> --help`。 ### 连接到 Claude（MCP 服务器） Cuaderno 配备了一个 MCP 服务器，因此 Claude Desktop / Claude Code / 任何 MCP 感知代理都可以读写笔记本。该服务器是一个单独的二进制文件，`cdno-mcp`，它通过 stdio 进行 JSON-RPC 通信。如果您通过 Homebrew 安装或符号链接上述源代码构建，则它已经在您的 PATH 中。 将其连接到 Claude Desktop / Claude Code： ```json { "mcpServers": { "cuaderno": { "command": "cdno-mcp", "env": { "CUADERNO_VAULT_PATH": "/Users/you/notebook" } } } } ``` 笔记本路径也可以省略；然后服务器打开工作目录所属的笔记本。 **今日工具表面。** 所有 42 个工具都连接到领域 — 上下文收集读取、每日/每周笔记访问、写入操作、结构创建和生命周期转换；请参阅 [`STATUS.md`](STATUS.md) 获取每个工具的列表。 ### 下一步 - **[`STATUS.md`](STATUS.md)** — 当前开发状态，按阶段划分，并附有 PR 链接。 - **[`docs/design.md`](docs/design.md)** — 笔记类型、文件夹结构、RLM 理念和 CLI / MCP / UI 表面的完整规范。 - **[`docs/cli-ergonomics.md`](docs/cli-ergonomics.md)** — 每个变更动词遵循的标志和提示约定。在脚本、CI 或交互式提示不是预期之处时很有用。 - **[`docs/implementation-plan.md`](docs/implementation-plan.md)** — 架构、特征景观和分阶段构建序列。 - **[`CHANGELOG.md`](CHANGELOG.md)** — 自开始以来每个 PR 的更新记录。 ## 研究日志方法 RLM 从法拉第、达尔文、哈明、克努斯和陶等实践中提炼出六个支柱： 1. **时间日志** — 按日期、追加、单一事实来源 2. **证据投资组合** — 按问题划分的档案，长期积累 3. **重要问题** — 哈明武器化，经常重读 4. **项目地图** — 轻量级概览（不是甘特图） 5. **责任制** — 小型、有界、长期责任 6. **承诺登记册** — 带有日期的独立承诺（不是待办事项列表） ## 架构 五箱 Rust 工作区： ``` cuaderno/ ├── Cargo.toml ← 工作区根目录 ├── crates/ │ ├── cdno-core/ ← 文件 I/O、markdown 解析、SQLite 索引、文件监视 │ ├── cdno-domain/ ← 笔记类型、业务规则、查询、状态转换 │ ├── cdno-cli/ ← 终端命令 (`cdno`) │ ├── cdno-mcp/ ← MCP 服务器 — stdio + Streamable HTTP 二进制文件 │ └── cdno-tauri/ ← 桌面应用的 Tauri 后端（已发货，所有 8 个视图 + 捕获） ├── ui/ ← React + Tailwind 前端（已发货） └── skills/ ← Claude 技能定义（第 4 阶段技能适配，尚未创建） ``` ``` cdno-core → cdno-domain → cdno-cli → cdno-mcp → stdio 传输 (`cdno-mcp`, 已发货) → Streamable HTTP 传输 (`cdno-mcp-server`, 已发货) → cdno-tauri（第 5 阶段）→ React UI ``` **cdno-core** 没有领域知识 — 它处理带有 YAML 前置元数据的 markdown 文件、部分操作、SQLite 索引和文件监视。可在任何 markdown 笔记本工具中重用。 **cdno-domain** 包含所有 RLM 业务逻辑。定义笔记类型、强制执行规则（5 个项目上限、必填前置元数据、强制链接）、实现查询（承诺聚合、投资组合健康状况）和处理状态转换。纯逻辑 — 无文件 I/O，无联网。 **cdno-cli**、**cdno-mcp** 和 **cdno-tauri** 是调用领域方法的薄翻译层，分别通过其协议。 ## 设计原则 - **Markdown 文件是事实来源。** SQLite 索引是缓存。如果除了笔记本文件夹之外的所有内容都被删除，系统可以通过重新索引来重建。 - **所有内容都在一个地方，以开放格式存储。** 没有专有格式，没有云依赖。 - **有偏见的强制执行优于灵活性。** 按笔记类型要求必填前置元数据、自动脚手架、验证、强制链接模式。 - **多动症友好型情感设计。** 引导人们关注已有内容，而不是缺失的内容。没有愧疚引擎。没有愤怒的红色逾期计数。允许停放或放弃事物。 - **最小维护开销。** 如果维护系统需要每天超过五分钟（每周审查除外），则说明有问题。 ## 笔记类型 | 类型 | 描述 | 位置 | |------|-------------|----------| | `daily` | 时间日志条目（追加） | `journal/daily/` | | `weekly` | 每周审查制品（追加） | `journal/weekly/` | | `project` | 可变项目仪表盘（最多 5 个活跃） | `projects/` | | `portfolio` | 证据文件夹的索引笔记 | `portfolios/*/` | | `evidence` | 投资组合内的单个捕获 | `portfolios/*/` | | `stewardship` | 永久责任的仪表盘 | `stewardships/` | | `tracking` | 责任的 structured log 条目 | `stewardships/*/tracking/` | | `question` | 重要研究或生活问题 | `questions/` | | `commitment` | 带有硬截止日期的独立承诺 | `commitments/` | | `inbox` | 未分类捕获，等待分类 | `inbox/` | ## 消费者 该工具有四个消费者： - **研究人员** 通过终端中的 CLI - **研究人员** 通过 Cuaderno 桌面 UI（Tauri 2.0） - **Claude** 通过 MCP 服务器（本地 stdio；自托管/远程 Streamable HTTP，通过 OAuth 终止代理） - **Claude 技能** 作为结合 MCP 调用和多动症友好交互模式的编排工作流 ## 状态 第 1-5 阶段的[构建顺序](docs/implementation-plan.md) 已完成（第 4 阶段的技能适配仍在进行中）。**CLI 每天都可用端到端** — 所有笔记类型（项目、行动、承诺、投资组合 + 证据、问题、责任制 + 跟踪 + 定期承诺）都可以通过终端使用标志和提示的符合人体工程学的方式访问。聚合的 `cdno orient` / `cdno status` / `cdno commitments` 视图跨所有来源组成。 MCP 服务器（第 4 阶段）已准备好投入生产，所有 42 个工具都连接到领域，通过 stdio 和 Streamable HTTP 传输。Tauri 桌面 UI（第 5/6 阶段）已完成：所有八个视图以及应用壳、全局 `⌘⇧C` 捕获、菜单栏托盘和来自外部编辑的实时刷新 — 可通过上面的 Homebrew cask 安装。延迟了：公证、自动更新器、NSPanel 捕获叠加层和 Intel `.dmg`。 请参阅 **[`STATUS.md`](STATUS.md)** 获取按阶段和问题划分的明细，以及 **[`CHANGELOG.md`](CHANGELOG.md)** 获取每个 PR 的更新记录。 ## 致谢 - 任务管理的规划大部分由 Claude 使用 `gh cli` 完成 - 软件的大部分架构由我完成，Claude 提供第二意见 - 当然，一些实现任务将委托给 Claude，但它永远不会自动推送。所有代码都将由我审查和评估。 ## 许可证 [MPL-2.0](LICENSE)