# https://github.com/matheuzgomes/decoreba 项目说明书

生成时间：2026-07-21 17:46:53 UTC

## 目录

- [项目概述与系统架构](#page-overview)
- [TUI 调色板、模糊搜索与工作流](#page-tui-search-workflows)
- [数据存储、Gist 同步与加密](#page-storage-sync)
- [MCP 服务器、Shell 集成与桌面应用](#page-mcp-shell-desktop)

<a id='page-overview'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[TUI 调色板、模糊搜索与工作流](#page-tui-search-workflows)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/matheuzgomes/decoreba/blob/main/README.md)
- [cmd/decoreba/main.go](https://github.com/matheuzgomes/decoreba/blob/main/cmd/decoreba/main.go)
- [cmd/decoreba-desktop/main.go](https://github.com/matheuzgomes/decoreba/blob/main/cmd/decoreba-desktop/main.go)
- [internal/core/types.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/types.go)
- [go.mod](https://github.com/matheuzgomes/decoreba/blob/main/go.mod)
</details>

# 项目概述与系统架构

## 项目定位

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/` | 各类可执行程序的入口 |
| `internal/` | 仅项目内部可见的核心包 |
| `go.mod` | Go 模块依赖声明 |

资料来源：[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 的整体架构抽象为三层：

```mermaid
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 阶段、需要快速迭代并同时维护多种交互形态的项目而言，是一种务实且可持续的选择。

---

<a id='page-tui-search-workflows'></a>

## TUI 调色板、模糊搜索与工作流

### 相关页面

相关主题：[项目概述与系统架构](#page-overview), [MCP 服务器、Shell 集成与桌面应用](#page-mcp-shell-desktop)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/core/tui/palette.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/tui/palette.go)
- [internal/core/tui/palette_render.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/tui/palette_render.go)
- [internal/core/tui/addform.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/tui/addform.go)
- [internal/core/tui/workflow.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/tui/workflow.go)
- [internal/core/tui/variables.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/tui/variables.go)
- [internal/core/tui/keys.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/tui/keys.go)
</details>

# TUI 调色板、模糊搜索与工作流

`decoreba` 的 TUI 层位于 `internal/core/tui` 目录，是终端界面的核心交互模块。它围绕"调色板（Palette）"组织功能入口，结合模糊搜索过滤命令，并联动工作流（Workflow）执行预设步骤。本页基于 v0.3.0 的源码梳理这三者的协作方式。

## 1. 模块职责与组件划分

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

| 文件 | 主要职责 |
| --- | --- |
| `palette.go` | 调色板状态机：维护打开/关闭、输入缓冲、选中项索引 |
| `palette_render.go` | 负责将调色板绘制到终端，处理高亮与布局 |
| `addform.go` | 嵌入式表单，用于录入新工作流或新变量 |
| `workflow.go` | 工作流模型的执行引擎与 TUI 列表渲染 |
| `variables.go` | 变量面板的渲染与编辑交互 |
| `keys.go` | 全局与各组件的键盘绑定表 |

资料来源：[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]()。

```mermaid
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` 集中维护所有快捷键，避免在组件中分散硬编码。常见约定包括：

| 按键 | 作用 | 作用域 |
| --- | --- | --- |
| `Ctrl+P` / `Ctrl+K` | 打开调色板 | 全局 |
| `Esc` | 关闭调色板或表单 | 全局 |
| `↑` / `↓` | 列表项移动 | 调色板、表单 |
| `Enter` | 确认选择 | 调色板、表单 |
| `Ctrl+N` | 打开新建工作流表单 | 全局 |

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

## 小结

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

---

<a id='page-storage-sync'></a>

## 数据存储、Gist 同步与加密

### 相关页面

相关主题：[项目概述与系统架构](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/core/store/store.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/store/store.go)
- [internal/core/store/seed.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/store/seed.go)
- [internal/core/sync/sync.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/sync/sync.go)
- [internal/core/sync/gist.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/sync/gist.go)
- [internal/core/sync/encrypt.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/sync/encrypt.go)
- [internal/core/sync/backend.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/sync/backend.go)
</details>

# 数据存储、Gist 同步与加密

`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）进行身份认证。同步流程大致如下：

| 阶段 | 操作 | 说明 |
| --- | --- | --- |
| Pull | 拉取远程 Gist 内容 | 解密后与本地合并 |
| Diff | 比较本地与远程差异 | 基于 `id` 与 `updated_at` 字段 |
| Push | 上传加密数据 | 仅加密后的密文离开本机 |

`资料来源：[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 仅保存加密后的业务数据。

## 数据流总览

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

```mermaid
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]()`

---

<a id='page-mcp-shell-desktop'></a>

## MCP 服务器、Shell 集成与桌面应用

### 相关页面

相关主题：[TUI 调色板、模糊搜索与工作流](#page-tui-search-workflows), [数据存储、Gist 同步与加密](#page-storage-sync)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/core/mcp/mcp.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/mcp/mcp.go)
- [internal/core/mcp/search.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/mcp/search.go)
- [internal/core/mcp/manage.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/mcp/manage.go)
- [internal/core/mcp/execute.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/mcp/execute.go)
- [internal/core/mcp/blocklist.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/mcp/blocklist.go)
- [internal/core/mcp/backup.go](https://github.com/matheuzgomes/decoreba/blob/main/internal/core/mcp/backup.go)
</details>

# MCP 服务器、Shell 集成与桌面应用

## 概述与定位

`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` 内部按"功能即文件"的方式拆分，每个文件对应一类工具或一种横切关注点。下表概述了主要文件与它们承担的职责。

| 文件 | 主要职责 | 典型工具/能力 |
|---|---|---|
| `mcp.go` | MCP 服务器初始化、工具注册表与生命周期管理 | 注册所有 MCP 工具、监听客户端请求 |
| `search.go` | 提供本地文件/内容的检索能力 | 关键字搜索、路径匹配 |
| `manage.go` | 对工作区或资源进行 CRUD 管理 | 列出/创建/删除条目 |
| `execute.go` | 执行受控的 Shell 命令并返回结果 | 调用外部进程、解析 stdout/stderr |
| `blocklist.go` | 安全策略：阻止危险命令 | 黑名单匹配、危险模式拦截 |
| `backup.go` | 对关键文件或目录进行备份与恢复 | 快照生成、回滚 |

资料来源：[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`，而无需改动执行逻辑本身。

```mermaid
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 前端留出了清晰的演进路径。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: matheuzgomes/decoreba; human_manual_source: deepwiki_human_wiki -->