DanielCardonaRojas/codemark

**Codemark** 是一个用于代码的结构化书签系统。与插入一个换行符就会失效的脆弱的 `file:line` 引用不同，Codemark 使用 **[tree-sitter](https://tree-sitter.github.io/tree-sitter/)** 来捕获你标记内容的*语义结构*——因此书签可以在重命名、重构和重新格式化过程中**自我修复**。 这使得它们足够持久，适用于长时间运行的 AI agent 会话、代码审计和个人知识管理。 🌐 **官网与文档:** [danielcardonarojas.github.io/codemark](https://danielcardonarojas.github.io/codemark/) ## 📑 目录 - [与 Claude Code 配合使用](#-use-it-with-claude-code) - [原生仪表盘 (TUI)](#-native-dashboard-tui) - [功能](#-features) - [安装说明](#-installation) - [快速开始](#-quick-start) - [支持的语言](#-supported-languages) - [自定义 Markdown 输出](#-customizing-markdown-output) - [文档](#-documentation) - [构建工具](#-built-with) - [许可证](#-license) ## ⚡ 与 Claude Code 配合使用 Codemark 是专为 AI 编程 agent 构建的。只需一条命令即可教会你的 agent 创建和检索结构化书签，因此上下文可以**在会话之间保留**，而无需每次打开聊天时都从头重新推导。 ``` codemark install-skill --agent claude --scope user ``` 然后在任意会话中直接询问即可： 之后——即使代码已被重构，或者在一个全新的会话中——你（或另一个 agent）都能瞬间重新加载该上下文： 因为书签是**结构化**的，所以即使底层代码被移动或修改，它们仍然可以正确解析。支持 **Claude Code**、**GitHub Copilot**、**Gemini CLI** 以及任何加载 `.agents/skills` 的 agent。 ### 你可以提出的要求 一旦某个流程被捕获为集合，这些知识就变得可重复利用——供你、你的队友以及未来的 agent 会话使用： - 🧭 **新工程师入职** — - 🔎 **解释代码流程** — - 🐞 **在已知流程中排查 bug** — - 🔗 **关联两个流程** — 📘 详细教程：[**Agent 工作流指南**](./dev-docs/guides/agent-workflow-walkthrough.md) · [**Agent Skill 源码**](./extras/skills/codemark/SKILL.md) ## 🖥️ 原生仪表盘 (TUI) Codemark 具有一个内置的、受 `lazygit` 启发的键盘驱动仪表盘。这是管理结构化书签、集合和导览的主要界面。 ``` codemark tui ```  #### 🎬 更多演示

Settings overlay

FTS & semantic search

Filter pane contents

请访问 [**演示库**](./dev-docs/guides/demo-gallery.md) 查看完整尺寸的动画演示。 ### 主题 TUI 自带可重新调整整个界面主题的内置配色方案。在你的配置 (`tui.theme`) 或通过 `CODEMARK_TUI_THEME` 环境变量设置一个主题；运行 `codemark-tui --list-schemes` 查看可用选项。 | Catppuccin Mocha | Everforest Dark | | --- | --- | |  |  | ### 仪表盘功能 - **⌨️ 键盘驱动、Vim 风格的导航** — 类似 `lazygit` 的、完全键盘优先的界面。使用 `j`/`k`（或方向键）移动，使用 `Tab` 切换面板，使用 `[` / `]` 切换标签页，并使用 `+` / `-` 调整面板大小。随时按 `?` 获取上下文相关的帮助覆盖层。 - **🔄 推送 / 拉取同步** — 使用 `P` (push) 将集合和导览发布到远程 [codetours](./crates/codetours-server) 服务器，并使用 `p` 拉取共享的导览。在团队中共享精心整理的演示指南。 - **🔍 语义与全文本搜索** — 按 `/` 进行搜索，然后在 **FTS** (SQLite 全文) 和 **语义** (本地向量嵌入) 模式之间切换。FTS 查找精确的词语；语义根据含义查找书签——无需 API key。 - **📝 可自定义的 Markdown 预览** — 详情和集合概览面板通过 [Handlebars 模板](./dev-docs/templates.md) 渲染。将你自己的 `details_panel.md` 或 `codemark_collection_overview.md` 放入配置目录，即可重塑显示内容。 - **🎨 配色方案与主题** — 在你的配置中设置 `[tui].theme`。内置选项包括 `OneHalfDark` (默认)、`Dracula`、`Nord`、`gruvbox-dark`、`Solarized`、`Catppuccin Mocha` 等等。Base16/base24 方案可以同时为主题化代码预览*和*周围的 UI 界面；将你自己的 `.tmTheme` 或 base16 `.yaml` 文件放入 `themes/` 配置子目录即可添加自定义主题。请参阅[配置](./dev-docs/configuration.md)。 - **✏️ 在任何编辑器中打开** — 在书签上按 `o` 即可直接在你配置的编辑器（终端或 GUI）中跳转到代码。通过 `[open]` 配置部分为每个文件扩展名配置命令——请参阅[配置](./dev-docs/configuration.md)。 ## 🛠️ 功能 - 🧠 **智能解析**：通过分层匹配（精确 → 宽松 → 哈希回退），书签可以在重命名和结构更改后保留。 - 🖥️ **交互式仪表盘**：Lazygit 风格的 TUI，实现高效的、键盘优先的交互。 - 📑 **丰富的元数据**：捕获 AST 结构、git 上下文、内容哈希以及只增不改的笔记/标签。 - 🔍 **语义搜索**：使用本地嵌入通过意图查找代码（例如，*“身份验证在哪里处理？”*）——无需 API key。 - 🗃️ **集合**：将书签分组为用于特定任务的逻辑集合。 - 📦 **Git 集成**：跨提交和分支跟踪书签。 - 🧩 **Agent 技能**：一个可安装的技能，教会 AI 编程 agent 为你添加书签——适用于 Claude Code、GitHub Copilot、Gemini CLI 以及任何加载 `.agents/skills` 的 agent。 ## 💻 安装说明 已为 **macOS** (Apple Silicon 和 Intel)、**Linux** (x86_64, glibc) 和 **Windows** (x86_64) 发布了预构建的二进制文件。你可以选择任何你喜欢的方法。 ### Homebrew (macOS / Linux) ``` brew install DanielCardonaRojas/codemark/codemark ``` ### 安装脚本 (macOS / Linux) ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/DanielCardonaRojas/codemark/releases/latest/download/codemark-cli-installer.sh | sh ``` ### PowerShell (Windows) ``` powershell -ExecutionPolicy Bypass -c "irm https://github.com/DanielCardonaRojas/codemark/releases/latest/download/codemark-cli-installer.ps1 | iex" ``` ### mise ``` mise use -g github:DanielCardonaRojas/codemark ``` ### Cargo (从源码构建) ``` cargo install --git https://github.com/DanielCardonaRojas/codemark codemark-cli ``` *需要 Rust 1.85+ (2024 版)。SQLite 已内置。* ### 终端 UI (可选) `codemark tui` 会打开交互式仪表盘，这是一个独立的配套二进制程序。**Homebrew 会自动将其与 CLI 一起安装**。其他预构建方法（脚本、PowerShell、mise）仅安装 `codemark` CLI；请使用以下命令添加仪表盘： ``` cargo install --git https://github.com/DanielCardonaRojas/codemark codemark-tui ``` ## 🚦 快速开始 更喜欢自己通过命令行而不是通过 agent 来操作吗？CLI 就是你所需要的。 ### 1. 为范围添加书签 ``` codemark add --file src/auth.rs --range 42-67 --tag auth --note "token validation entrypoint" ``` ### 2. 再次找到它——即使代码被移动了 ``` codemark list # see everything you've marked codemark resolve # re-locate a single bookmark codemark search "auth" # full-text + semantic search ``` ### 3. 使用仪表盘浏览 ``` codemark tui ``` 请参阅[**完整命令参考**](./dev-docs/CLI.md)了解每个子命令和标志——包括集合、导览、代码片段匹配和多仓库查询。 ## 🌐 支持的语言 Codemark 支持以下语言的 AST： - 🦀 **Rust** - 🍎 **Swift** - 🔷 **TypeScript / TSX** - 🐍 **Python** - 🐹 **Go** - ☕ **Java** - 🎯 **Dart** - ♯ **C#** ## 🎨 自定义 Markdown 输出 Codemark 使用 [Handlebars](https://handlebarsjs.com/) 模板格式化命令输出和 TUI 预览。在配置目录中放入你自己的模板，即可覆盖 `codemark show`（以及 TUI 面板）的默认设置： ``` mkdir -p ~/.config/codemark/templates cp ./templates/codemark_show.md ~/.config/codemark/templates/ $EDITOR ~/.config/codemark/templates/codemark_show.md ``` 有关完整的模板规范——每个可用的变量、循环、条件语句、辅助函数以及默认模板——请参阅 **[模板参考](./dev-docs/templates.md)**。 ## 📖 文档 - [**完整命令参考**](./dev-docs/CLI.md) — 详细的标志和子命令指南。 - [**配置**](./dev-docs/configuration.md) — 编辑器设置、主题、全局/本地配置以及语义搜索。 - [**模板**](./dev-docs/templates.md) — 自定义 Markdown 输出和 TUI 预览。 - [**Agent 工作流指南**](./dev-docs/guides/agent-workflow-walkthrough.md) — 与 AI agent 配合使用 Codemark 的端到端指南。 - [**Agent 技能**](./extras/skills/codemark/SKILL.md) — 由 `codemark install-skill` 安装的技能（适用于 Claude Code、Copilot、Gemini 等）。 ## 🏗️ 构建工具 Codemark 是一个**本地优先**的 Rust workspace——任何核心功能都不需要云服务、账户或 API key。 | 层级 | 技术 | |-------|------------| | **语言** | [Rust](https://www.rust-lang.org) (workspace: `codemark-core`, `codemark-cli`, `codemark-tui`, `codetours-server`) | | **结构化解析** | [tree-sitter](https://tree-sitter.github.io/tree-sitter/) | | **存储** | 通过 `rusqlite` (内置) 使用 [SQLite](https://www.sqlite.org)，并使用 [`sqlite-vec`](https://github.com/asg017/sqlite-vec) 进行向量搜索和使用 FTS5 进行全文搜索 | | **嵌入** | 在 [`candle`](https://github.com/huggingface/candle) 上运行的本地模型——无需 API key 的语义搜索 | | **TUI** | [`ratatui`](https://ratatui.rs) + `crossterm`，使用 [`syntect`](https://github.com/trishume/syntect) 进行语法高亮 | | **模板引擎** | [Handlebars](https://handlebarsjs.com/) | | **同步服务器** | [`axum`](https://github.com/tokio-rs/axum) + `tokio`，JWT 认证 (`codetours` 服务器) | | **Git 集成** | [`git2`](https://github.com/rust-lang/git2-rs) (libgit2) | ## 🛡️ 许可证 基于 [MIT 许可证](LICENSE) 发布。

标签：AI辅助编程, IPv6支持, Rust, SOC Prime, Tree-sitter, 代码书签, 可视化界面, 开发工具, 网络流量审计, 通知系统