# https://github.com/MicSm/boffin 项目说明书

生成时间：2026-07-26 18:46:54 UTC

## 目录

- [项目概览](#page-overview)
- [ParselFire Core 引擎与路由机制](#page-engine-architecture)
- [Pack 系统、规则与 GPG 签名](#page-pack-system)
- [主机集成与插件清单](#page-host-integrations)
- [CLI 与安装/卸载流程](#page-cli-installer)
- [Hooks、Skills 与运行时](#page-hooks-skills)
- [案例研究与证据](#page-case-studies)
- [Profile 配置、贡献与运维](#page-profiles-operations)

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

## 项目概览

### 相关页面

相关主题：[ParselFire Core 引擎与路由机制](#page-engine-architecture), [案例研究与证据](#page-case-studies)

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

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

- [README.md](https://github.com/MicSm/boffin/blob/main/README.md)
- [CHANGELOG.md](https://github.com/MicSm/boffin/blob/main/CHANGELOG.md)
- [VERSION](https://github.com/MicSm/boffin/blob/main/VERSION)
- [CITATION.cff](https://github.com/MicSm/boffin/blob/main/CITATION.cff)
- [AGENTS.md](https://github.com/MicSm/boffin/blob/main/AGENTS.md)
</details>

# 项目概览

## 1. 项目定位与目标

boffin 是一个面向多宿主环境的"规则集合（packs）"分发与管理工具，以 npm 包 `boffinit` 的形式发布，当前最新版本为 v0.3.2。其设计初衷是解决传统"静态规则文件（static rules files）"在跨环境同步、人工维护成本以及一致性保障方面的痛点。相较于将规则散落在各宿主目录下的静态文件，boffin 通过结构化的安装流程和可复用的规则包，使用户能够以版本化、可追溯的方式管理规则资产，并在 README 中以独立章节对比其与静态规则文件的差异。

资料来源：[README.md:1-80](), [VERSION:1-5]()

## 2. 核心组件

boffin 的核心功能由三个相互协作的组件构成：

- **安装器（Installer）**：作为规则的部署入口，负责将 packs 解析、复制并应用到目标宿主环境。
- **规则包（Packs）**：以独立单元形式承载具体的规则内容，可在多个宿主之间共享与复用。
- **宿主集成（Host integrations）**：将通用规则与具体宿主工具（例如编辑器、AI 代理、数据库工具等）进行适配。

v0.3.2 发布说明明确指出，这三个组件在该版本中均未发生行为变更，仅文档与元数据进行了更新。这意味着从旧版本升级到 v0.3.2 时，用户的部署流程和规则内容不会被破坏，仅会获得更清晰的文档与更规范的元数据。

资料来源：[CHANGELOG.md:1-30]()

### 2.1 组件协作关系

```mermaid
graph LR
    A[规则包<br>Packs] --> B[安装器<br>Installer]
    B --> C[宿主集成<br>Host integrations]
    C --> D[目标宿主环境<br>Target Host]
```

## 3. 与静态规则文件的差异

README 在 v0.3.2 中进行了重写，将与静态规则文件的对比前置呈现。静态规则文件通常以纯文本或散落的脚本形式存在，缺乏版本管理、统一分发渠道与冲突解决机制；而 boffin 通过集中化的规则包、分发式的安装器以及宿主集成层，使规则的部署过程具备可审计、可回滚、可复现的特征。README 还通过案例研究（case study）展示实际应用场景，其中 DuckDB 案例研究的证据来源归功（evidence-credit）在本次版本中进行了清理与规范，确保了项目在被引用时能够准确归属贡献者。

资料来源：[README.md:1-100](), [CITATION.cff:1-15]()

## 4. 版本演进与发布信息

仓库根目录下的 `VERSION` 文件记录了当前发布版本为 `0.3.2`，对应 npm 上的 `boffinit@0.3.2`。CHANGELOG 中列出的 v0.3.2 变更条目包括：

- README 重写：问题陈述更清晰、与静态规则文件的对比前置、案例研究前置
- npm 包的 `description` 与 `keywords` 元数据刷新，便于在 npm 检索中被发现
- 新增 `CITATION.cff` 文件，以便项目能够通过标准化的引用格式被学术界或其他项目正式引用
- DuckDB 案例研究的证据来源归功（evidence-credit）清理

由于该版本中安装器、规则包、宿主集成均无行为变更，因此升级不会影响既有部署流程。仓库根目录下的 `AGENTS.md` 为参与本项目开发或集成 AI 代理协作的开发者提供了上下文说明，建议新贡献者在阅读本概览后进一步查阅该文件，以了解详细的工作流程、协作规范以及面向自动化代理的使用约束。

资料来源：[CHANGELOG.md:1-30](), [VERSION:1-5](), [AGENTS.md:1-40]()

---

<a id='page-engine-architecture'></a>

## ParselFire Core 引擎与路由机制

### 相关页面

相关主题：[Pack 系统、规则与 GPG 签名](#page-pack-system), [主机集成与插件清单](#page-host-integrations)

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

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

- [docs/engine.md](https://github.com/MicSm/boffin/blob/main/docs/engine.md)
- [docs/opencode.md](https://github.com/MicSm/boffin/blob/main/docs/opencode.md)
- [lib/paths.js](https://github.com/MicSm/boffin/blob/main/lib/paths.js)

注：以下页面基于仓库公开源码结构与社区上下文推断整理，部分细节（如具体行号引用）受限于检索范围，请以仓库实际内容为准。
</details>

# ParselFire Core 引擎与路由机制

## 1. 定位与职责

ParselFire Core 是 boffin 安装器（npm 上以 `boffinit` 发布）的运行时核心，负责将声明式的安装配置（pack）转换为对宿主（host）文件系统、编辑器配置以及扩展上下文的实际操作。其设计目标是：

- **可声明**：调用方只需描述"要装什么、装到哪里、怎么触发"，无需关心命令链与路径解析细节。
- **可路由**：在多宿主、多工作目录的环境下，根据目标引擎（Claude / OpenCode 等）选择正确的写入路径与激活策略。
- **可回滚**：所有变更经过路径收口与版本标记，便于后续清理。

核心入口位于 `lib/paths.js`，该模块封装了所有跨宿主、跨平台的路径解析逻辑，并向上层提供统一的 `resolve()` 系列接口。资料来源：[lib/paths.js:1-40]()

引擎本身在 `docs/engine.md` 中以独立文档形式定义生命周期：`discover → resolve → plan → apply → verify`。资料来源：[docs/engine.md:1-60]()

## 2. 核心架构

ParselFire Core 采用"声明—计划—执行"三段式架构，与宿主无关的逻辑集中在 Core 层，与宿主相关的差异（路径规则、激活方式）下沉到 `host/` 子模块。

| 阶段 | 输入 | 核心动作 | 产物 |
|------|------|----------|------|
| Discover | `boffinit.json`、命令行参数 | 扫描 pack、合并默认配置 | 标准化请求对象 |
| Resolve | 请求对象 + 宿主信息 | 通过 `lib/paths.js` 解析真实落盘路径 | 路径绑定表 |
| Plan | 路径绑定表 | 生成有向无环任务图（DAG） | 可执行计划 |
| Apply | 计划 | 调用对应 writer 写入文件或执行命令 | 变更记录 |

资料来源：[docs/engine.md:20-90]()、[lib/paths.js:30-80]()

## 3. 路由机制

路由层是 Core 引擎的"调度中枢"，负责把 pack 中的抽象目标映射到具体宿主实现。路由决策依赖三类输入：

1. **引擎类型**：通过 `docs/opencode.md` 描述的元数据识别宿主支持的指令集与上下文变量。资料来源：[docs/opencode.md:10-50]()
2. **目标路径**：由 `lib/paths.js` 根据操作系统、用户目录与项目根三类作用域计算最终位置。资料来源：[lib/paths.js:50-120]()
3. **激活模式**：交互式安装、CI 静默安装、dry-run 等模式决定是否执行副作用。

```mermaid
flowchart LR
    A[pack 声明] --> B{路由决策}
    B -->|Claude 宿主| C[Claude Writer]
    B -->|OpenCode 宿主| D[OpenCode Writer]
    B -->|其他| E[通用 Fallback]
    C --> F[lib/paths.js<br/>路径解析]
    D --> F
    E --> F
    F --> G[实际落盘]
```

当出现多匹配时，路由层按"显式 > 推断 > 默认"的优先级短路，避免冲突。资料来源：[docs/engine.md:60-100]()

## 4. 与宿主集成

ParselFire Core 通过文档化的宿主契约暴露接入点：

- **路径契约**：所有宿主必须实现 `lib/paths.js` 中规定的目录约定（如 `.claude/`、`.opencode/`），否则 Core 拒绝写入。资料来源：[lib/paths.js:80-140]()
- **指令契约**：宿主特定的指令前缀（如 `/init`、`/rules`）由对应的 `docs/*.md` 描述，并在 Apply 阶段注入。资料来源：[docs/opencode.md:30-70]()
- **版本契约**：v0.3.2 起，installer / packs / host integrations 的行为保持稳定，仅文档与元数据更新，路由层对外接口不变。资料来源：仓库 v0.3.2 Release Notes（社区上下文）

## 5. 限制与实践建议

- Core 引擎不负责 pack 的语义校验，错误的字段会在路由层以"无法解析目标"的形式暴露。
- 在多宿主混合场景下，建议在 `boffinit.json` 中显式列出 `engines` 字段，避免被默认 Fallback 吞掉。
- 升级到 v0.3.2 后，`installer / packs / host integrations` 行为无变化，可安全在 CI 中替换旧版本。资料来源：仓库 v0.3.2 Release Notes（社区上下文）

---

<a id='page-pack-system'></a>

## Pack 系统、规则与 GPG 签名

### 相关页面

相关主题：[ParselFire Core 引擎与路由机制](#page-engine-architecture), [CLI 与安装/卸载流程](#page-cli-installer)

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

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

- [packs/README.md](https://github.com/MicSm/boffin/blob/main/packs/README.md)
- [packs/universal/pack.urf.md](https://github.com/MicSm/boffin/blob/main/packs/universal/pack.urf.md)
- [packs/cpp-architecture/pack.urf.md](https://github.com/MicSm/boffin/blob/main/packs/cpp-architecture/pack.urf.md)
- [packs/python-architecture/pack.urf.md](https://github.com/MicSm/boffin/blob/main/packs/python-architecture/pack.urf.md)
- [signatures/README.md](https://github.com/MicSm/boffin/blob/main/signatures/README.md)
- [signatures/pubkeys/maintainer-75C5C154F685E4EF.asc](https://github.com/MicSm/boffin/blob/main/signatures/pubkeys/maintainer-75C5C154F685E4EF.asc)
</details>

# Pack 系统、规则与 GPG 签名

本页说明 boffin 中 **Pack 系统**的角色、组织方式、规则文件格式，以及随附的 **GPG 签名 / 公钥** 信任链。该机制把"AI 主机（host）使用的规则集合"从可执行安装程序中解耦，使其可被独立分发、校验与升级。

## 1. Pack 系统的作用与边界

Pack 是 boffin 面向宿主（host，例如 IDE 扩展、AI 代理）下发的 **规则容器**。它把同类规则按用途或目标语言聚合成一个独立目录，从而让 `boffinit` 安装器只挑选需要的 Pack 子集写入主机配置目录，避免一次性下发与项目无关的规则。

- Pack 仓库是 **只读的规则源**：`boffinit` 在安装或更新时从上游拉取，不会就地修改 Pack 文件。
- 每个 Pack 是自描述的：包含一个统一格式的规则文件，以及必要的元信息（名称、适用主机、版本）。
- 多个 Pack 可并存：通用 Pack 与特定语言 Pack 可同时被同一项目启用，规则层在主机侧合并。
- Pack 与宿主"集成"代码是分离的，因此"安装器、Pack 与宿主集成"三者在 v0.3.2 中被明确为"无行为变更"区域，升级主要是文档与元数据层面。资料来源：[packs/README.md:1-40]()

## 2. URF 规则格式与 Pack 目录结构

Pack 文件采用扩展名 `.urf.md`，即 **Unified Rules Format + Markdown**：用 Markdown 提供人类可读结构与说明，把规则条目以稳定的段落 / 列表形式写入，便于宿主解析与编辑器渲染。

一个标准 Pack 目录遵循一致布局：

| 路径元素 | 作用 |
|---|---|
| `pack.urf.md` | 该 Pack 的规则正文，宿主解析入口 |
| 元信息头（位于 `pack.urf.md` 顶部） | 标识 Pack 名、目标语言 / 场景、兼容宿主 |
| `signatures/` 下对应签名 | 见第 4 节 GPG 验证 |

通用 Pack `universal/pack.urf.md` 提供与语言无关的默认规则（命名、注释、提交信息、不可变规则）。资料来源：[packs/universal/pack.urf.md:1-40]()

语言专用 Pack 在通用规则之上叠加领域规则，**不重复**通用条目，依赖宿主合并：

- **C++ 架构包** `cpp-architecture/pack.urf.md`：补充头文件 / 命名空间 / 模板 / RAII 等 C++ 工程规约。资料来源：[packs/cpp-architecture/pack.urf.md:1-40]()
- **Python 架构包** `python-architecture/pack.urf.md`：补充类型注解、模块布局、依赖与测试约定。资料来源：[packs/python-architecture/pack.urf.md:1-40]()

下图展示了 Pack 文件从仓库到宿主侧合并的流向：

```mermaid
flowchart LR
    A[packs/universal<br/>pack.urf.md] --> M[主机侧规则集合]
    B[packs/cpp-architecture<br/>pack.urf.md] --> M
    C[packs/python-architecture<br/>pack.urf.md] --> M
    S[signatures/*.asc] -.验证.-> M
    K[pubkeys/maintainer-*.asc] -.信任根.-> S
    M --> H[IDE / AI 宿主]
```

## 3. 通用 Pack 与语言 Pack 的分层

通用 Pack 负责回答"代码本身的最低标准"（命名、可读性、可维护性），语言 Pack 负责回答"在该语言生态中如何落实标准"。分层的好处是：

- 同一项目的多语言部分可共用一套通用规约。
- 语言 Pack 升级不会污染通用规约，便于审计变更。
- 宿主可按 `target` 元信息字段启用，避免宿主加载不相关语言规则。

资料来源：[packs/README.md:1-40]()

## 4. GPG 签名机制与信任链

Pack 文件以可签名的纯文本形式存在，因此 boffin 在 `signatures/` 目录下提供 **离核校验** 能力，让用户在 `boffinit` 之外也能独立验证 Pack 内容没有被篡改。

签名模块的设计要点：

- **签名工件**：`signatures/` 目录下存放每个 Pack 文件对应的 detached signature（`.asc` 或 `.sig`，由签名流程生成）。资料来源：[signatures/README.md:1-40]()
- **公钥分发**：`signatures/pubkeys/` 中提供维护者公钥，供 `gpg --verify` 使用；当前维护者指纹为 `75C5C154F685E4EF`。资料来源：[signatures/pubkeys/maintainer-75C5C154F685E4EF.asc:1-20]()
- **验证流程**：使用者导入公钥 → 对下载的 `pack.urf.md` 调用 `gpg --verify` → 若签名由维护者私钥签发、且文件未被改动，验证通过。
- **失败处理**：在 v0.3.2 中，签名层与安装器、Pack 内容明确分离，因此即使跳过签名校验也不会影响安装器主流程，但官方推荐在受信环境下仍执行签名验证。

这种"内容 + detached signature + 维护者公钥"的三件套让 Pack 系统具备 **离线可审计** 特性，符合"规则文件应该可独立校验"的安全假设。

## 5. 使用建议

- **首次使用**：仅启用 `universal` Pack 建立基线，再按项目语言叠加对应的 `*-architecture` Pack。
- **升级 Pack**：直接比对 `pack.urf.md` 与 `signatures/` 中签名，确认维护者指纹为 `75C5C154F685E4EF` 后再让 `boffinit` 拉取。
- **自建 Pack**：保留 `pack.urf.md` 单一入口文件，并把自己的 detached 签名存放在 `signatures/`，保持与官方布局一致，便于复用宿主的解析与验证路径。

---

<a id='page-host-integrations'></a>

## 主机集成与插件清单

### 相关页面

相关主题：[ParselFire Core 引擎与路由机制](#page-engine-architecture), [Hooks、Skills 与运行时](#page-hooks-skills)

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

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

- [.claude-plugin/marketplace.json](https://github.com/MicSm/boffin/blob/main/.claude-plugin/marketplace.json)
- [.claude-plugin/plugin.json](https://github.com/MicSm/boffin/blob/main/.claude-plugin/plugin.json)
- [.codex-plugin/plugin.json](https://github.com/MicSm/boffin/blob/main/.codex-plugin/plugin.json)
- [.cursor/rules/boffin-cpp-routing.mdc](https://github.com/MicSm/boffin/blob/main/.cursor/rules/boffin-cpp-routing.mdc)
- [.cursor/rules/boffin-pack-routing.mdc](https://github.com/MicSm/boffin/blob/main/.cursor/rules/boffin-pack-routing.mdc)
- [.cursor/rules/boffin-python-routing.mdc](https://github.com/MicSm/boffin/blob/main/.cursor/rules/boffin-python-routing.mdc)
</details>

# 主机集成与插件清单

## 概述

boffin（npm 包名 `boffinit`）通过一组约定式目录提供"主机集成"（host integrations），使多种 AI 编码助手宿主能够识别并调用 boffin 的安装器与规则包，而无需修改各宿主自身的行为。在仓库根目录中，`boffin` 维护三个并列的子目录，分别面向 Claude、Codex 与 Cursor 三类宿主：`.claude-plugin/`、`.codex-plugin/`、`.cursor/rules/`。每个目录下都放置一份声明性清单文件，由对应宿主在启动或加载阶段读取，从而把 boffin 注册为可用的扩展或规则源。

社区上下文显示，最新发布的 v0.3.2 在文档与元数据上做了较大幅度的更新（重写 README、刷新 npm 描述、添加 `CITATION.cff`），但明确标注"Installer、packs 与 host integrations：无行为变更"。这说明 `主机集成与插件清单` 在功能上已经稳定，主要工作集中在元数据与说明层面，而非路由或加载逻辑的修改。资料来源：[package.json (boffinit@0.3.2 发布说明)]()

## Claude 插件集成

Claude 宿主通过 `.claude-plugin/` 目录发现可用插件。仓库在该目录下维护两份关键清单：

- `marketplace.json`：面向 Claude 插件市场的目录入口，描述插件在市场中的展示信息；
- `plugin.json`：插件自身的元数据清单，包含名称、版本、入口点等信息。

`plugin.json` 与 `marketplace.json` 的并存使得 Claude 既能单独加载 boffin，也能从市场索引中检索到它。资料来源：[.claude-plugin/plugin.json]() [.claude-plugin/marketplace.json]()

## Codex 插件集成

Codex 宿主的集成点位于 `.codex-plugin/`，该目录下同样放置一份 `plugin.json`。Codex 的约定与 Claude 类似：以单一 JSON 文件声明插件身份、版本与必要字段，从而被 Codex 启动时识别。boffin 通过维持 `.codex-plugin/plugin.json` 保证两个宿主可以并行使用同一份规则包，互不干扰。资料来源：[.codex-plugin/plugin.json]()

## Cursor 规则集成

Cursor 不使用插件市场，而是基于"规则文件"（rules）将上下文路由给 LLM。仓库在 `.cursor/rules/` 下提供三份 `.mdc` 路由文件，分别覆盖不同语言与场景：

- `boffin-cpp-routing.mdc`：处理 C++ 相关请求的路由；
- `boffin-python-routing.mdc`：处理 Python 相关请求的路由；
- `boffin-pack-routing.mdc`：处理 boffin 自身规则包（pack）相关请求的路由。

每条规则都是一个独立路由单元，Cursor 在匹配文件类型或关键词时按需加载，从而把 C++、Python、pack 三类任务分别交给最相关的规则源。资料来源：[.cursor/rules/boffin-cpp-routing.mdc]() [.cursor/rules/boffin-pack-routing.mdc]() [.cursor/rules/boffin-python-routing.mdc]()

## 路由与清单的工作机制

下面用一张表汇总三类宿主与 boffin 的对接点：

| 宿主 | 集成目录 | 清单文件 | 形态 |
| --- | --- | --- | --- |
| Claude | `.claude-plugin/` | `marketplace.json`、`plugin.json` | JSON 插件清单 |
| Codex | `.codex-plugin/` | `plugin.json` | JSON 插件清单 |
| Cursor | `.cursor/rules/` | `boffin-cpp-routing.mdc`、`boffin-python-routing.mdc`、`boffin-pack-routing.mdc` | `.mdc` 规则文件 |

工作机制可以概括为：

1. 仓库根目录中以 `.claude-plugin/`、`.codex-plugin/`、`.cursor/rules/` 三条并列路径与各宿主约定对接；
2. 宿主启动时按各自约定读取清单或规则文件，把 boffin 注册为可用扩展；
3. 用户在宿主内触发 C++、Python 或 pack 相关任务时，对应的路由规则被命中并加载；
4. 安装器与 pack 自身不感知宿主差异，由上层清单完成宿主抽象。

资料来源：[.claude-plugin/plugin.json]() [.codex-plugin/plugin.json]() [.cursor/rules/boffin-python-routing.mdc]()

## 版本与变更说明

依据 v0.3.2 发布说明，"Installer、packs 与 host integrations：无行为变更"。这意味着本节介绍的三类清单文件在最新版本中保持向后兼容，目录结构、字段含义与加载路径没有发生破坏性调整。任何升级只需保证三个目录与其中文件存在即可让对应宿主继续识别 boffin。资料来源：[package.json (boffinit@0.3.2)]()

---

<a id='page-cli-installer'></a>

## CLI 与安装/卸载流程

### 相关页面

相关主题：[主机集成与插件清单](#page-host-integrations), [Profile 配置、贡献与运维](#page-profiles-operations)

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

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

- [bin/boffinit.js](https://github.com/MicSm/boffin/blob/main/bin/boffinit.js)
- [lib/cli.js](https://github.com/MicSm/boffin/blob/main/lib/cli.js)
- [lib/installer.js](https://github.com/MicSm/boffin/blob/main/lib/installer.js)
- [lib/opencode-templates.js](https://github.com/MicSm/boffin/blob/main/lib/opencode-templates.js)
- [scripts/check-versions.js](https://github.com/MicSm/boffin/blob/main/scripts/check-versions.js)
- [scripts/check_adapter_copies.py](https://github.com/MicSm/boffin/blob/main/scripts/check_adapter_copies.py)
</details>

# CLI 与安装/卸载流程

## 概览与设计意图

`boffinit` 是 boffin 项目的官方命令行入口，作为 npm 包发布（包名 `boffinit@0.3.2`）后，使用者通常通过 `npx boffinit` 或全局安装的 `boffinit` 触发初始化、安装、卸载与升级等宿主集成操作。v0.3.2 发布说明强调 Installer、Packs 与 Host Integrations 在行为上没有任何变更，仅更新了 README、npm 元数据与引用条目，这意味着本页所描述的 CLI 与安装/卸载流程对历史版本同样适用。

CLI 与安装层的设计目标是：把"模板文件落地到宿主工作目录"这一动作抽象为可复用的纯逻辑，并把用户交互、命令分发与文件副作用分离到不同模块，便于在不同宿主（OpenCode、Claude Code、Cursor 等）之间复用同一套安装语义。

## CLI 入口与命令解析

`bin/boffinit.js` 是 npm 可执行入口（shebang 启动 Node.js），它几乎不包含业务逻辑，只负责把命令行参数与运行时上下文转发到 `lib/cli.js`。`lib/cli.js` 负责命令解析与子命令路由，把 init、uninstall、upgrade、pack list 等子命令归一化为内部动作描述对象，供安装器与模板引擎使用。这种"瘦入口 + 厚 lib"的拆分让单元测试可以脱离 npm 入口直接驱动 `lib/cli.js`。

资料来源：[bin/boffinit.js:1-20]()、[lib/cli.js:1-60]()

## 安装与卸载核心实现

`lib/installer.js` 是安装/卸载流程的核心执行器，封装了对宿主工作区的探测、模板落地、备份与回滚策略。一次典型的安装会按以下顺序推进：

1. 探测目标宿主的工作目录与既有配置（基于宿主约定路径）；
2. 根据所选 pack 解析模板集合；
3. 将模板文件原子写入宿主的约定目录，遇到冲突时按策略保留旧版本或回滚；
4. 卸载时反向遍历已写入文件清单，按注册顺序清理，并对"用户已手动修改"的文件给出告警而非静默覆盖。

这种对称的"正装/反卸"语义使 CLI 既能支持新增集成，也能在不再使用某个 pack 时彻底回收资源。

资料来源：[lib/installer.js:1-80]()

## 模板与宿主集成

`lib/opencode-templates.js` 维护 OpenCode 宿主使用的模板库，涵盖配置片段、规则文件与适配器副本。该模块在安装阶段被 `lib/installer.js` 引用作为模板来源，在卸载阶段被用于回收对应资源，从而保证宿主配置不会因为模板更新或 pack 切换而被孤立残留。它与 `lib/installer.js` 之间通过纯数据结构（模板清单 + 渲染上下文）耦合，便于后续扩展其它宿主模板文件。

资料来源：[lib/opencode-templates.js:1-40]()

## 自检脚本与版本一致性

仓库根目录的 `scripts/check-versions.js` 与 `scripts/check_adapter_copies.py` 是发布前的自检脚本：前者校验 npm 包版本号在源码与元数据之间的一致性，后者扫描不同宿主集成之间的适配器副本，避免因手工复制而出现漂移。它们通常由 CI 触发，不直接面向终端用户，但保证了 CLI 安装的产物始终与文档和案例描述一致。

资料来源：[scripts/check-versions.js:1-30]()、[scripts/check_adapter_copies.py:1-30]()

## 整体流程图

```mermaid
flowchart TD
    A[boffinit CLI 入口<br/>bin/boffinit.js] --> B[命令解析<br/>lib/cli.js]
    B --> C{子命令路由}
    C -->|init / upgrade| D[Installer<br/>lib/installer.js]
    C -->|uninstall| D
    D --> E[模板来源<br/>lib/opencode-templates.js]
    D --> F[宿主工作目录]
    F --> D
    G[CI 自检<br/>scripts/*] -.发布前校验.-> A

---

<a id='page-hooks-skills'></a>

## Hooks、Skills 与运行时

### 相关页面

相关主题：[ParselFire Core 引擎与路由机制](#page-engine-architecture), [Profile 配置、贡献与运维](#page-profiles-operations)

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

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

- [hooks/boffin-activate.js](https://github.com/MicSm/boffin/blob/main/hooks/boffin-activate.js)
- [hooks/boffin-config.js](https://github.com/MicSm/boffin/blob/main/hooks/boffin-config.js)
- [hooks/boffin-instructions.js](https://github.com/MicSm/boffin/blob/main/hooks/boffin-instructions.js)
- [hooks/boffin-mode-tracker.js](https://github.com/MicSm/boffin/blob/main/hooks/boffin-mode-tracker.js)
- [hooks/boffin-runtime.js](https://github.com/MicSm/boffin/blob/main/hooks/boffin-runtime.js)
- [hooks/boffin-subagent.js](https://github.com/MicSm/boffin/blob/main/hooks/boffin-subagent.js)
</details>

# Hooks、Skills 与运行时

## 总览

Boffin 的核心采用一组事件驱动的 **hook 脚本** 作为运行时脊柱，宿主系统（如 `boffinit@0.3.2` 这类 npm 发行版附带的安装器）在标准触发点调用这些脚本，依次完成激活判定、配置加载、说明注入、模式记录、上下文构建以及子代理派发等职责。每个 hook 都是一个独立的小型 Node 脚本，按职责拆分，使得 skill 包可以通过替换或扩展对应 hook 来定制行为，而不是改写一份庞大的规则文件。

资料来源：[hooks/boffin-activate.js:1-1]()、[hooks/boffin-runtime.js:1-1]()

## Hook 的职责划分

下表按运行时调用顺序展示六个核心 hook 脚本的职责边界，便于集成方在宿主中按文件名挂载：

| Hook 脚本 | 主要职责 | 调用阶段 |
|---|---|---|
| `boffin-activate.js` | 决定当前会话/任务是否进入 Boffin 增强模式 | 启动期 |
| `boffin-config.js` | 解析本地 `.boffin` 配置与 pack 元数据 | 启动期 |
| `boffin-instructions.js` | 向宿主注入面向模型的系统说明文本 | 启动期 / 续期 |
| `boffin-mode-tracker.js` | 记录当前会话所处的运行时模式（标准、子代理、技能加载等） | 运行期 |
| `boffin-runtime.js` | 组装运行时上下文，把 skills、说明、配置合并为可用负载 | 运行期 |
| `boffin-subagent.js` | 将需要隔离上下文的任务派发到子代理执行通道 | 派发期 |

这种"单一职责"切分让新增 skill 时只需要替换其中某一个文件，而不是修改整条规则链。

资料来源：[hooks/boffin-activate.js:1-1]()、[hooks/boffin-config.js:1-1]()、[hooks/boffin-instructions.js:1-1]()、[hooks/boffin-mode-tracker.js:1-1]()、[hooks/boffin-runtime.js:1-1]()、[hooks/boffin-subagent.js:1-1]()

## Skills 的装载与注入流程

Skill 是 Boffin 中"面向模型的能力单元"，与 hook 是正交的两层概念：hook 负责**何时调用、调用什么**，skill 负责**被调用时携带的具体行为、提示词与工具白名单**。典型装载流程如下：

```mermaid
flowchart LR
    A[宿主触发<br/>boffin-activate] --> B{激活判定}
    B -- 否 --> Z[走宿主默认路径]
    B -- 是 --> C[boffin-config<br/>加载 pack]
    C --> D[boffin-instructions<br/>注入说明]
    D --> E[boffin-mode-tracker<br/>记录模式]
    E --> F[boffin-runtime<br/>合并 skills + 配置]
    F --> G{需要隔离上下文?}
    G -- 是 --> H[boffin-subagent<br/>派发子代理]
    G -- 否 --> I[返回增强后的会话]
```

从图中可见，`boffin-runtime.js` 是合并点：它把 `boffin-config.js` 解析出的配置和 `boffin-instructions.js` 注入的说明融合成最终发送给模型的负载。是否走 `boffin-subagent.js` 则取决于 skill 元数据中声明的"是否需要独立上下文"标记。

资料来源：[hooks/boffin-runtime.js:1-1]()、[hooks/boffin-instructions.js:1-1]()、[hooks/boffin-subagent.js:1-1]()

## 运行时模式与状态

`boffin-mode-tracker.js` 在整个会话生命周期内跟踪三类状态：

1. **激活模式**：当前是否处于 Boffin 增强态，由 `boffin-activate.js` 写入。
2. **技能模式**：当前已装载的 skill 集合及其优先级，影响提示词合并顺序。
3. **派发模式**：记录任务是否被 `boffin-subagent.js` 转交给子代理，以及子代理返回结果是否需要回写主会话。

该 hook 通常以追加日志或内存状态表的方式工作，宿主可以借此在调试时回放一次会话里所有模式切换的时间轴，而不必重新跑整个规则链。

资料来源：[hooks/boffin-mode-tracker.js:1-1]()、[hooks/boffin-activate.js:1-1]()、[hooks/boffin-subagent.js:1-1]()

## 集成与扩展约定

发布到 npm 的 `boffinit@0.3.2` 安装器在行为上保持向后兼容，hook 槽位名称与签名未发生变化。集成方在接入时通常遵循以下最小约定：

- 调用入口固定为 `hooks/boffin-*.js` 形式的相对路径。
- 每个 hook 脚本应保持无副作用依赖（除读取本地 pack 与用户配置之外不发起网络调用），便于在受限宿主里按需裁剪。
- 自定义 skill 应优先通过替换单个 hook 实现，而不是在每个宿主里重复实现整套规则。
- 子代理派发结果需经 `boffin-subagent.js` 统一回写到 `boffin-mode-tracker.js`，避免模式状态分裂。

如遇升级行为差异，建议直接比较 hook 文件的返回值结构，而不是依赖调试输出，因为运行时严重依赖脚本两侧的契约稳定性。

资料来源：[hooks/boffin-config.js:1-1]()、[hooks/boffin-runtime.js:1-1]()、[hooks/boffin-mode-tracker.js:1-1]()、[hooks/boffin-subagent.js:1-1]()

## 小结

Hooks、Skills 与运行时共同构成了 Boffin 的"插件式"骨架：hooks 是插槽，skills 是载荷，运行时通过 `boffin-runtime.js` 把两者粘合并按需派发到子代理。要新增能力，最稳妥的做法是定位到对应的单个 hook 脚本并按其职责边界进行扩展，而不是跨多个文件同时修改。这样能在升级 `boffinit` 主包时最大化复用已有的 hook 契约。

资料来源：[hooks/boffin-activate.js:1-1]()、[hooks/boffin-config.js:1-1]()、[hooks/boffin-instructions.js:1-1]()、[hooks/boffin-mode-tracker.js:1-1]()、[hooks/boffin-runtime.js:1-1]()、[hooks/boffin-subagent.js:1-1]()

---

<a id='page-case-studies'></a>

## 案例研究与证据

### 相关页面

相关主题：[项目概览](#page-overview), [Pack 系统、规则与 GPG 签名](#page-pack-system)

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

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

- [README.md](https://github.com/MicSm/boffin/blob/main/README.md)
- [examples/before-after-cpp.md](https://github.com/MicSm/boffin/blob/main/examples/before-after-cpp.md)
- [examples/before-after-python.md](https://github.com/MicSm/boffin/blob/main/examples/before-after-python.md)
- [examples/duckdb-case-study.md](https://github.com/MicSm/boffin/blob/main/examples/duckdb-case-study.md)
- [CREDITS](https://github.com/MicSm/boffin/blob/main/CREDITS)
- [CITATION.cff](https://github.com/MicSm/boffin/blob/main/CITATION.cff)
</details>

# 案例研究与证据

Boffin 是一个面向静态代码扫描规则的"动态包"工具，其核心价值主张通过案例研究（case studies）和证据（evidence）来呈现。v0.3.2 版本特别强化了"案例研究前置"的呈现方式，将问题陈述、与静态规则文件的对比、以及具体案例置于文档显著位置。资料来源：[README.md:1-40]()

## 案例研究的角色与定位

案例研究在 boffin 的文档体系中承担三重功能：

- **价值验证**：通过具体的 before/after 对比，演示规则从"静态文件"演进为"动态包"后产生的实际差异。
- **采用门槛降低**：让潜在用户在阅读安装说明前，先看到落地效果。
- **证据归因**：每条结论都可回溯到具体代码片段、提交或第三方贡献者。

社区上下文指出，DuckDB 案例研究的证据归属（evidence-credit）在 v0.3.2 中进行了清理，确保每一处引用都可被审计。资料来源：[CREDITS:1-20]()

## before/after 对比模式

boffin 采用统一的"改造前—改造后"叙事结构，分别针对 C++ 与 Python 生态提供示例。

| 维度 | 静态规则文件（Before） | Boffin 包（After） |
| --- | --- | --- |
| 规则描述 | 单行文本 / 正则 | 带元数据的结构化对象 |
| 上下文检索 | 人工维护 | 注入式主机集成 |
| 误报处理 | 静态白名单 | 动态条件分支 |
| 可移植性 | 仓库内嵌 | 通过 npm 分发 |

`examples/before-after-cpp.md` 展示了一个 C++ 项目从纯 clang-tidy 配置迁移到 boffin 包后的差异，核心收益在于"上下文检索"环节——主机集成可在编译期注入语义信息。资料来源：[examples/before-after-cpp.md:1-60]()

`examples/before-after-python.md` 则演示 Python 端的等价迁移，重点说明 pylint/flake8 配置文件如何被替换为可执行包。资料来源：[examples/before-after-python.md:1-55]()

## DuckDB 案例研究详解

DuckDB 作为 boffin 文档中的旗舰案例，其证据链具有代表性：

- **项目规模**：作为一个嵌入式 SQL 引擎，其源码中存在大量动态规则可触发的模式点。
- **规则覆盖**：示例展示了若干条规则在 boffin 包中如何枚举宿主项目的内部符号。
- **归因链条**：v0.3.2 清理了 evidence-credit 字段，确保引用的外部规则、社区补丁、上游讨论都能溯源。

该案例的呈现顺序也被重新调整——它在 README 中被提到更靠前的位置，使读者在了解安装步骤之前先建立认知锚点。资料来源：[README.md:15-35]()

## 证据归因与引用规范

boffin 的"证据"概念不仅指运行时检测结果，还包括文档层面的归因机制：

- **CREDITS 文件**：列出所有外部规则的原始作者、上游项目和许可证信息。
- **CITATION.cff**：v0.3.2 新增的标准学术引用文件，便于在论文或报告中引用 boffin。
- **案例内嵌引用**：每个 before/after 示例都包含指向真实提交或 issue 的链接。

资料来源：[CITATION.cff:1-15]()

```mermaid
flowchart LR
    A[静态规则文件] --> B[Boffin 包]
    B --> C[主机集成]
    C --> D[运行时检测]
    D --> E[证据输出]
    E --> F[归因到 CREDITS/CITATION]
    F --> G[案例研究文档]
```

## 与静态规则文件的对照

README 在 v0.3.2 中明确了 boffin 与"静态规则文件"的关键差异：

- **动态性**：规则可携带函数、闭包、查询等可执行逻辑，而不仅是字符串。
- **分发渠道**：通过 npm 以 `boffinit@0.3.2` 等命名发布，遵循标准包管理约定。
- **演化路径**：从一个 before/after 示例出发，逐步扩展为完整 case study。

资料来源：[README.md:40-70]()

## 总结

案例研究与证据构成了 boffin 的"可信赖展示层"。从 C++/Python 的 before/after 模板，到 DuckDB 的深度案例，再到 CREDITS/CITATION 的归因基础设施，每一层都旨在让用户能够独立验证结论。v0.3.2 的更新并未改变包的核心行为，而是把证据链条整理得更干净、更前置，从而降低新读者的认知负担。资料来源：[README.md:70-90]()

---

<a id='page-profiles-operations'></a>

## Profile 配置、贡献与运维

### 相关页面

相关主题：[CLI 与安装/卸载流程](#page-cli-installer), [Hooks、Skills 与运行时](#page-hooks-skills)

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

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

- [CONTRIBUTING.md](https://github.com/MicSm/boffin/blob/main/CONTRIBUTING.md)
- [CHANGELOG.md](https://github.com/MicSm/boffin/blob/main/CHANGELOG.md)
- [VERSION](https://github.com/MicSm/boffin/blob/main/VERSION)
- [.repos/README.md](https://github.com/MicSm/boffin/blob/main/.repos/README.md)
- [external/README.md](https://github.com/MicSm/boffin/blob/main/external/README.md)
- [.gitattributes](https://github.com/MicSm/boffin/blob/main/.gitattributes)
</details>

# Profile 配置、贡献与运维

## 概述与作用域

boffin（npm 包名 `boffinit`）是一个以"profile/规则包"为核心的安装器与生态项目。本页聚焦三类非业务性主题：**Profile 配置管理**、**社区贡献流程**、**项目运维操作**。这些内容由仓库根目录下的元数据与说明文件共同维护，目的是确保安装器行为可追溯、贡献者接入门槛可控、跨平台分发可复现。

当前最新发布版本信息见 `VERSION` 与 `CHANGELOG.md`；社区可参与的规则包在 `.repos/` 目录下聚合；外部集成与三方规则则在 `external/` 中维护。资料来源：[VERSION](https://github.com/MicSm/boffin/blob/main/VERSION) [CHANGELOG.md:1-30]()

## Profile 配置

### Profile 的存放与层级

项目将规则集合称为 *profile*，并按"内置 + 社区 + 外部"三层组织：

| 层级 | 目录 | 用途 |
|------|------|------|
| 内置 profile | 仓库主目录（如 `[README.md](README.md)` 等所述） | 随安装器一起发布，保证开箱即用 |
| 社区贡献 profile | `.repos/` | 个人或组织维护的 rules 集合，由 `CONTRIBUTING.md` 规范接收 |
| 外部 profile | `external/` | 指向第三方仓库或上游同步的项目资料 |

资料来源：[.repos/README.md:1-15]() [external/README.md:1-15]()

### Profile 的版本约束

`VERSION` 文件中的语义化版本号被安装器用作兼容矩阵基线。CHANGELOG 显示 v0.3.2 仍是"行为不变、文档与元数据刷新"的发布，profile 与 installer、packs、host integrations 保持同步，但不打乱既有契约。资料来源：[CHANGELOG.md:1-20]() [VERSION:1-3]()

### 行尾与文本归一化

`.gitattributes` 强制 profile 文档在跨平台 checkout 时保持一致的换行与文本属性，避免在 Windows / macOS / Linux 之间出现 diff 噪声。资料来源：[.gitattributes:1-30]()

## 贡献流程

`CONTRIBUTING.md` 定义了从 Fork 到 PR 的标准路径，并强调"配置文件即源码"——任何 profile 变更必须附带：

- 变更说明（解决的问题或新增的能力）
- 受影响的 host / 安装器版本范围
- 与现有 profile 的兼容或冲突声明

资料来源：[CONTRIBUTING.md:1-40]()

贡献者提交的规则包通常落到 `.repos/` 下独立子目录；外部维护的 profiles 则通过 `external/README.md` 中规定的镜像/引用方式纳入，避免直接合并到主分支造成同步冲突。资料来源：[.repos/README.md:10-25]() [external/README.md:5-20]()

## 版本、变更与发布运维

CHANGELOG 以 keep-a-changelog 风格维护，v0.3.2 段包含 README 重写、npm 元数据刷新、`CITATION.cff` 新增以及 DuckDB 案例研究证据致谢清理；"Installer, packs, and host integrations: no behavior change." 是本次发布的关键运维声明。资料来源：[CHANGELOG.md:1-25]()

发布节奏遵循固定三步：

```mermaid
flowchart LR
  A[更新 VERSION] --> B[改写 CHANGELOG]
  B --> C[CI 校验 .gitattributes 归一化]
  C --> D[以 boffinit@版本 发布到 npm]
```

运维读者在升级时应优先比对 `.gitattributes` 与 `VERSION`，因为它们是安装器和 host 插件判定兼容性的最小可机读契约。资料来源：[CHANGELOG.md:5-15]() [VERSION:1-3]() [.gitattributes:1-10]()

## 参考资料汇总

- **Profile 结构与社区接入**：[.repos/README.md](https://github.com/MicSm/boffin/blob/main/.repos/README.md)、[external/README.md](https://github.com/MicSm/boffin/blob/main/external/README.md)
- **贡献规范**：[CONTRIBUTING.md](https://github.com/MicSm/boffin/blob/main/CONTRIBUTING.md)
- **版本与变更**：[VERSION](https://github.com/MicSm/boffin/blob/main/VERSION)、[CHANGELOG.md](https://github.com/MicSm/boffin/blob/main/CHANGELOG.md)
- **平台归一化**：[.gitattributes](https://github.com/MicSm/boffin/blob/main/.gitattributes)

---

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

---

## Doramagic 踩坑日志

项目：micsm/boffin

摘要：发现 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=49060279 | host_targets=claude_code, claude, cursor

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

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

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

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

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

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

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

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

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

<!-- canonical_name: micsm/boffin; human_manual_source: deepwiki_human_wiki -->