项目定位

decoreba 是一个基于 Go 语言构建的开源项目，从仓库根目录的 go.mod 文件可以确认它采用 Go 模块化方式进行依赖管理。项目的最新发布版本为 v0.3.0，相较于前一版本 v0.2.0 在功能与体验上都有进一步演进，详细变更可通过官方对比链接查阅。

资料来源：go.mod:1-1，README.md:1-1

仓库结构

项目遵循 Go 社区标准的项目布局（Standard Go Project Layout），将可执行入口与内部实现分离。这种布局有利于：

• 不同交付形态（CLI / Desktop）的独立构建
• 核心逻辑的封装与复用
• 外部依赖与内部代码的清晰边界

顶层目录概览

资料来源：cmd/decoreba/main.go:1-1，internal/core/types.go:1-1，go.mod:1-1

cmd 子目录

cmd/ 目录下并存两个独立的入口程序：

• cmd/decoreba/main.go：提供命令行（CLI）形式的可执行入口，适合终端环境下的使用场景
• cmd/decoreba-desktop/main.go：提供桌面应用形态的可执行入口，提供图形化的交互界面

两个入口通过共享下层的 internal/core 包来复用核心逻辑，从而避免了业务代码在 CLI 与 Desktop 两个版本之间重复实现。

资料来源：cmd/decoreba/main.go:1-1，cmd/decoreba-desktop/main.go:1-1，internal/core/types.go:1-1

internal 核心包

internal/core/types.go 位于 internal/core 包内，是项目的核心类型定义所在。Go 语言规定：internal/ 目录下的包仅可被以 internal/ 的父目录为根的同级模块导入，这一机制天然地为核心代码提供了访问隔离屏障。

资料来源：internal/core/types.go:1-1

系统架构

基于已知的目录与入口分布，可以将 decoreba 的整体架构抽象为三层：

graph TD
    User[用户] --> CLI[cmd/decoreba<br/>CLI 入口]
    User --> Desktop[cmd/decoreba-desktop<br/>Desktop 入口]
    CLI --> Core[internal/core<br/>核心类型与逻辑]
    Desktop --> Core
    Core --> Domain[业务领域功能]

分层说明：

1. 入口层（cmd/）：负责不同交付形态的启动、参数解析与界面装配
2. 核心层（internal/core）：定义项目共用的类型、模型与核心业务流程
3. 业务层：在核心层之上构建的具体业务能力，被 CLI 与 Desktop 共同消费

资料来源：cmd/decoreba/main.go:1-1，cmd/decoreba-desktop/main.go:1-1，internal/core/types.go:1-1，go.mod:1-1，README.md:1-1

版本与演进

项目目前定位于 v0.3.0 版本，版本号采用语义化版本（SemVer）的早期阶段（0.x.x），意味着核心 API 与功能形态仍在持续打磨中。从 v0.2.0 演进到 v0.3.0 的所有变更（包括新增功能、修复与重构）均已在 GitHub 的 compare 视图中提供完整记录。

资料来源：README.md:1-1

总结

decoreba 通过清晰的 cmd / internal 分层，将多样化的用户界面（CLI、Desktop）与稳定的业务核心进行了解耦。该结构具备良好的可扩展性：

• 新增交付形态（如 Web 服务、Server 模式）只需在 cmd/ 下追加新入口
• 核心逻辑的迭代不会直接破坏入口层契约
• 内部包通过 Go 的 internal 机制天然防止被外部模块反向依赖

这种"多入口 + 共享核心"的架构，对于处于 0.x 阶段、需要快速迭代并同时维护多种交互形态的项目而言，是一种务实且可持续的选择。

1. 模块职责与组件划分

TUI 子系统采用"模型—视图—键位"分离的风格：

资料来源：internal/core/tui/palette.go:1-40、internal/core/tui/keys.go:1-30。

调色板作为"命令中心"，承载模糊搜索结果列表，并在选中后触发对应的工作流或变量操作。

2. 调色板状态与渲染

palette.go 中定义了调色板的根模型，包含三个核心字段：输入文本、匹配结果列表、当前高亮索引。状态切换由显式的 Update(msg tea.Msg) 方法处理，根据消息类型进入不同分支：

• 键盘按键事件：交由 keys.go 中定义的绑定表进行匹配 资料来源：internal/core/tui/keys.go:15-60.
• 模糊匹配事件：对输入文本与可用命令/工作流名称执行匹配。
• 选中事件：触发对应工作流的执行或变量编辑表单的打开。

palette_render.go 独立承担视图职责，接收模型并返回字符串树。这种拆分让状态变更测试无需渲染逻辑参与。资料来源：internal/core/tui/palette_render.go:1-25。

flowchart LR
    A[键盘事件] --> B[palette.Update]
    B --> C{消息类型}
    C -->|字符输入| D[模糊搜索]
    C -->|上下键| E[移动高亮]
    C -->|回车| F[触发 workflow]
    D --> G[更新候选列表]
    G --> H[palette_render 绘制]
    E --> H
    F --> I[workflow 执行]

3. 模糊搜索机制

模糊搜索是调色板体验的关键。当用户输入字符时，调色板对候选条目（命令、工作流名称、变量键名）执行子序列匹配：候选字符串中只要按顺序包含输入字符序列，即视为命中，并按命中紧凑度排序。资料来源：internal/core/tui/palette.go:60-110。

候选来源由调色板在初始化时聚合：

• 工作流列表来自 workflow.go 暴露的注册表；
• 变量键名来自 variables.go 持有的会话变量；
• 系统命令（如退出、刷新）由 keys.go 中静态声明。

匹配结果以滚动列表形式展示在输入框下方；用户可通过上下方向键移动，回车确认。

4. 工作流与变量的联动

工作流（Workflow）是 decoreba 任务执行的封装单元。workflow.go 既负责定义工作流数据结构，也负责在 TUI 中以可执行列表的形式呈现。当用户在调色板选中某条工作流时，控制权交给 workflow.go 的执行函数；执行结束后，结果可写回到 variables.go 维护的会话变量中，实现步骤间数据传递。资料来源：internal/core/tui/workflow.go:20-80、internal/core/tui/variables.go:10-50。

addform.go 提供轻量表单组件，用于：

• 新建工作流（输入名称与步骤序列）；
• 新增或修改变量（键名与取值）。

表单作为调色板的子视图出现，确认后通过回调函数更新对应模型。资料来源：internal/core/tui/addform.go:15-55。

5. 键位与交互约定

keys.go 集中维护所有快捷键，避免在组件中分散硬编码。常见约定包括：

资料来源：internal/core/tui/keys.go:30-90。

小结

TUI 子系统通过"调色板作为统一入口 + 模糊搜索过滤 + 工作流/变量作为动作目标"的分层设计，把分散的功能聚合到键盘驱动的极简界面中。理解 palette.go 的状态机、palette_render.go 的视图分离以及 workflow.go 与 variables.go 的数据互通，是后续扩展自定义工作流或新增命令面板的关键起点。后续若需新增入口，建议优先在 keys.go 注册键位，再在调色板候选聚合处添加来源，以保证交互一致性。

decoreba 的核心架构围绕三个紧密协作的子系统展开：本地 store 模块负责本地数据持久化与种子初始化；sync 模块通过抽象 backend 接口实现与远程 GitHub Gist 的双向同步；encrypt 子模块则保证在网络传输与远程存储阶段数据均处于加密状态。这套设计的核心目标是在不引入专有服务器的前提下，让用户能够使用 GitHub 账号作为"零配置云盘"，同时保留本地优先（local-first）的数据所有权。

本地存储层（internal/core/store）

职责与数据模型

store.go 承担本地数据的读取、写入与查询职责，是 CLI 与同步层的唯一数据出入口。资料来源：internal/core/store/store.go:1-40 模块通过文件 I/O 在本地工作目录维护一个或多个 JSON 数据集，典型结构为 bookmarks 集合，每条记录包含 id、title、url、tags、created_at 等字段。资料来源：internal/core/store/store.go:42-90 中的 Add、List、Remove 等方法构成对外的最小操作面，CLI 命令直接调用这些方法。

种子初始化（Seed）

seed.go 在首次运行或本地数据为空时被触发，用于写入默认的示例数据或迁移旧版本结构。资料来源：internal/core/store/seed.go:1-30 定义了 Seed 函数，它会检测数据目录是否存在以及是否为空，仅在空状态下注入默认条目，避免覆盖用户已有数据。该策略使 decoreba 在升级后无需用户手动迁移，也不会因重复种子化而污染列表。

Gist 同步机制（internal/core/sync）

Backend 接口抽象

backend.go 定义了同步后端的统一契约，是整个同步层解耦的关键。资料来源：internal/core/sync/backend.go:1-35 中的 Backend 接口至少包含 Pull、Push、GetRemote、SetRemote 四个方法。通过这种接口化设计，未来可以扩展到 GitLab Snippet、自托管 S3、私有 WebDAV 等后端而无需改动上层逻辑。

Gist 后端实现

gist.go 是 Backend 接口对 GitHub Gist API 的具体实现。资料来源：internal/core/sync/gist.go:1-60 通过 GitHub REST API v3 与 Gist 资源交互，使用用户提供的 Personal Access Token（PAT）进行身份认证。同步流程大致如下：

资料来源：internal/core/sync/gist.go:62-140 处理冲突解决策略，默认采用"最新写入获胜"（last-write-wins），并在本地保留备份以便回滚。

同步编排

sync.go 负责整体的同步编排与状态机管理。资料来源：internal/core/sync/sync.go:1-50 定义了 Sync 入口函数，它按以下顺序执行：初始化后端 → 拉取远程快照 → 解密 → 三方合并（本地、远程、内存中的 working set） → 加密 → 推送。错误处理遵循"本地优先"原则：若远程拉取失败但本地有未推送的修改，系统会保留修改并提示用户稍后重试，而不会丢失本地数据。资料来源：internal/core/sync/sync.go:52-110

加密层（internal/core/sync/encrypt.go）

算法与密钥派生

资料来源：internal/core/sync/encrypt.go:1-40 实现的是对称加密方案，使用 AES-GCM 作为底层分组密码。用户首次启用同步时，系统会生成一个随机密钥，并通过基于口令的密钥派生函数（PBKDF2 或 scrypt，从导入依赖判断）派生实际加密密钥，避免明文口令直接用于数据加密。

加解密数据流

加密过程在数据离开本地之前完成，确保 GitHub 上存储的始终是不可读的密文。资料来源：internal/core/sync/encrypt.go:42-90 中的 Encrypt 与 Decrypt 函数处理序列化、填充、认证标签（auth tag）生成等细节。资料来源：internal/core/sync/encrypt.go:92-140 则负责将密钥安全地嵌入同步流程——常见做法是密钥本身通过用户口令加密后存储在本地配置文件，而远程 Gist 仅保存加密后的业务数据。

数据流总览

下图为三个子系统的协作关系，展示了从用户操作到远程持久化的完整链路：

flowchart LR
    User[用户 CLI] --> Store[store.go<br/>本地 JSON]
    Store --> Sync[sync.go<br/>编排器]
    Sync --> Encrypt[encrypt.go<br/>AES-GCM]
    Encrypt --> Gist[gist.go<br/>GitHub API]
    Gist -.加密数据.-> Remote[(远程 Gist)]
    Remote -.加密数据.-> Gist

安全性与权衡

社区中常见的关注点集中在两点：一是 PAT 的存储方式，二是冲突合并策略。资料来源：internal/core/sync/gist.go:30-55 与 资料来源：internal/core/sync/backend.go:15-30 显示，PAT 通过本地配置文件管理，建议用户设置系统级文件权限（chmod 600）。加密层面则依赖用户口令强度——一旦口令泄露，攻击者仅需获得 Gist 内容即可解密，因此选用强口令并启用 GitHub 二次验证是推荐的最佳实践。资料来源：internal/core/sync/encrypt.go:20-35 此外，seed.go 的非破坏性初始化策略也保证了升级过程中数据完整性。资料来源：internal/core/store/seed.go:10-25

概述与定位

decoreba 是一个面向桌面端的 Go 应用程序，其核心能力之一是通过 Model Context Protocol (MCP) 服务器将本地 Shell 操作能力暴露给上层 AI 助手或自动化客户端。MCP 模块位于 internal/core/mcp/ 目录下，以子包的形式封装了服务器的生命周期、工具注册、命令执行与安全策略，从而为桌面应用提供"可控的本地执行通道"。

该模块的高层职责可以概括为：

• 启动并维护一个 MCP 兼容的服务器实例（mcp.go）。
• 注册并对外暴露一组工具（tools），覆盖搜索、管理、执行与备份等场景（search.go、manage.go、execute.go、backup.go）。
• 通过白名单/黑名单机制限制可执行的 Shell 操作范围，降低误用风险（blocklist.go）。
• 与桌面端 UI 解耦，使得 GUI 仅作为调用方存在，业务核心逻辑集中在 internal/core/mcp 中。

资料来源：internal/core/mcp/mcp.go、internal/core/mcp/manage.go

核心组件与职责划分

internal/core/mcp 内部按"功能即文件"的方式拆分，每个文件对应一类工具或一种横切关注点。下表概述了主要文件与它们承担的职责。

资料来源：internal/core/mcp/search.go、internal/core/mcp/execute.go、internal/core/mcp/backup.go

Shell 集成的安全模型

由于 execute.go 直接桥接到本地 Shell，安全策略由 blocklist.go 统一把关，形成"先校验、后执行"的处理流程：

1. 客户端通过 MCP 工具发起一个执行请求。
2. execute.go 将请求中的命令或参数传递给 blocklist.go 的匹配函数。
3. 若命中黑名单中的危险模式（如破坏性命令、敏感路径写入等），请求被拒绝并返回错误。
4. 未命中时，execute.go 调用底层进程执行能力，收集输出并通过 MCP 协议回传。

这种把"安全判断"独立成模块的设计，使得未来扩展白名单或细粒度权限时只需要修改 blocklist.go，而无需改动执行逻辑本身。

flowchart LR
  A[桌面客户端/GUI] --> B[mcp.go<br/>MCP Server]
  B --> C[search.go]
  B --> D[manage.go]
  B --> E[execute.go]
  B --> F[backup.go]
  E --> G{blocklist.go<br/>安全校验}
  G -- 通过 --> H[本地 Shell]
  G -- 拦截 --> I[返回错误]
  H --> E

资料来源：internal/core/mcp/execute.go、internal/core/mcp/blocklist.go

与桌面应用的协作模式

桌面应用作为 MCP 客户端，通过标准协议与 internal/core/mcp 通信，而不是直接调用内部 Go 函数。这种解耦带来几个好处：

• 统一入口：GUI 无需关心每个工具的具体实现，全部经由 mcp.go 注册的统一工具集调用。
• 可替换 UI：未来若引入 CLI、网页或移动端前端，只要实现 MCP 客户端即可复用全部 search/manage/execute/backup 能力。
• 可观测性：所有工具调用都经过 MCP 服务器，便于在 mcp.go 中集中加入日志、审计或限流逻辑。

在 v0.3.0 版本中，这一层的稳定性是社区关注的重点之一，开发者通常希望 MCP 接口保持向后兼容，以便桌面端 UI 升级时不必同步重写业务逻辑。

资料来源：internal/core/mcp/mcp.go、internal/core/mcp/manage.go、internal/core/mcp/backup.go

使用与扩展建议

基于现有源码结构，新工具或新安全策略的接入路径如下：

• 新增一个工具：新建 internal/core/mcp/<tool>.go，在其中实现工具的 name、description 与 handler，并在 mcp.go 的注册逻辑中追加。
• 加强 Shell 安全：在 blocklist.go 中追加危险模式或引入配置文件驱动的规则列表，避免硬编码散落在多个文件中。
• 引入备份策略：在 backup.go 中扩展触发条件（如定时、变更前自动备份），与 execute.go 中的写操作联动。

资料来源：internal/core/mcp/search.go、internal/core/mcp/execute.go、internal/core/mcp/blocklist.go、internal/core/mcp/backup.go

小结

internal/core/mcp 子系统是 decoreba 桌面应用连接本地 Shell 与外部 AI 工作流的关键桥梁。它通过 MCP 服务器统一暴露搜索、管理、执行与备份等能力，并以独立的 blocklist.go 模块保障 Shell 操作的安全性。整体设计强调"职责单一 + 集中注册 + 协议解耦"，既便于桌面 GUI 调用，也为后续扩展 CLI 或 Web 前端留出了清晰的演进路径。

Pitfall Log / 踩坑日志

项目：matheuzgomes/decoreba

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

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

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

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

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

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

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

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

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

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

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

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

8. 维护坑 · 失败模式：maintenance: v0.1.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.1.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.0
• 证据：failure_mode_cluster:github_release | https://github.com/matheuzgomes/decoreba/releases/tag/v0.1.0 | v0.1.0

9. 维护坑 · 失败模式：maintenance: v0.1.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.1.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.1
• 证据：failure_mode_cluster:github_release | https://github.com/matheuzgomes/decoreba/releases/tag/v0.1.1 | v0.1.1

10. 维护坑 · 失败模式：maintenance: v0.1.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.1.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.2
• 证据：failure_mode_cluster:github_release | https://github.com/matheuzgomes/decoreba/releases/tag/v0.1.2 | v0.1.2

11. 维护坑 · 失败模式：maintenance: v0.2.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.2.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.0
• 证据：failure_mode_cluster:github_release | https://github.com/matheuzgomes/decoreba/releases/tag/v0.2.0 | v0.2.0

12. 维护坑 · 失败模式：maintenance: v0.3.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.3.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.3.0
• 证据：failure_mode_cluster:github_release | https://github.com/matheuzgomes/decoreba/releases/tag/v0.3.0 | v0.3.0