内容
# okffs
**okffs** 是一个 TypeScript/Node.js [模型上下文协议](https://modelcontextprotocol.io) (MCP) 服务器，连接 Claude Code 到 GitHub，实现完整的 **问题 → 分支 → 合并 → 关闭** 工作流程。在 Claude.ai 上讨论任务，然后通过 Claude Code 将它们推送到 GitHub 作为问题和分支。
## 技术栈
- TypeScript / Node.js MCP 服务器
- GitHub 个人访问令牌（PAT）身份验证（支持 GitHub 应用程序）
- 发布到 [npm](https://www.npmjs.com/) 和 [MCP 注册表](https://registry.modelcontextprotocol.io)
## 状态
该项目正在分阶段开发。查看 [CLAUDE.md](CLAUDE.md) 以获取完整的路线图。
| 阶段 | 范围 | 状态 |
|------|-------|--------|
| 1 | 核心 MCP 服务器 — `create_issue`, `list_issues`, `close_issue`, `delete_issue`, `delete_branch`, `get_issue`, `comment_issue`, `link_issues` | **完成** |
| 2 | 批量创建 — `create_issues_from_list` | **完成** |
| 3 | Claude.ai 桥接 | 跳过 — 不需要 |
| 4 | 合并后自动关闭 — `create_pull_request`, `commit_and_update` | **完成** |
| 5 | GitHub 项目 v2（可选） | 计划中 |
| 6 | 项目站点 — `okffs.g2mk.dev` | 计划中 |
## 更新日志
查看 [发行版本](https://github.com/neturely/okffs/releases) 获取每个版本的发行说明，或查看 [CHANGELOG.md](CHANGELOG.md) 获取完整的历史记录。
## 与 Claude Code 一起使用
通过在项目根目录创建 `.mcp.json` 将 okffs 添加到任何项目中：
```json
{
"mcpServers": {
"okffs": {
"command": "npx",
"args": ["@neturely/okffs@latest"]
}
}
}
```
### 身份验证和仓库
okffs 需要 GitHub 令牌和目标仓库。它通过合理的回退机制解析两者，因此大多数用户需要很少或没有配置：
**令牌**（按优先级顺序）：
1. `.env` 文件中的 `GITHUB_TOKEN`。创建令牌的两种方法：
- **细粒度 PAT（推荐，权限最小）** — [在此处创建](https://github.com/settings/personal-access-tokens/new)，在目标仓库上具有 **问题**、**内容**、**拉取请求**（读写）、**元数据**（读）和**管理**（读写）权限。查看 [前提条件](#前提条件)。
- **经典 PAT（最快）** — 一键预范围链接：[github.com/settings/tokens/new?scopes=repo&description=okffs](https://github.com/settings/tokens/new?scopes=repo&description=okffs)。注意，这授予 **广泛的 `repo` 范围**，适用于您所有仓库；如果您想限制访问，请优先使用上述细粒度选项。
2. 如果 `GITHUB_TOKEN` 未设置，okffs 将回退到 **GitHub CLI** — 如果您已运行 `gh auth login`，它将直接生效，无需设置令牌。
**仓库**（按优先级顺序）：
1. `.env` 中的 `GITHUB_OWNER` / `GITHUB_REPO`。
2. 如果未设置，okffs 将从它运行的目录的 `origin` Git 远程自动检测它们。
因此，最少的设置通常只需要上述 `.mcp.json` — 如果您已登录 `gh` 并在要管理的仓库中运行 okffs，则无需 `.env`。要显式配置，请在同一目录中创建 `.env`:
```env
GITHUB_TOKEN=ghp_your_personal_access_token_here
# 可选 — 如果省略，则从 Git `origin` 远程自动检测：
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-repo-name
```
okffs 从其启动目录自动加载 `.env` — 无需 `--env-file` 标志。
配置完成后，Claude Code 将自动拾取工具。您可以询问 Claude：
- *"创建名为 'Fix login button' 的问题，描述为 '...'"*
- *"列出所有开放问题"*
- *"从此任务列表创建问题：..."*
- *"规划添加用户身份验证的工作并创建问题"*
- *"发布评论到问题 #12，说已完成什么"*
- *"将问题 #5 标记为由问题 #3 阻止"*
- *"完成问题 #42，关闭它并打开一个 PR"*
Claude 从问题标题和描述中推断出适当的标签（`bug`、`enhancement` 等），并将它们与您的 `OKFFS_DEFAULT_LABELS` 合并。
## 入门指南
### 前提条件
- Node.js（LTS）和 npm
- GitHub 个人访问令牌。**细粒度（推荐，权限最小）** — [在此处创建](https://github.com/settings/personal-access-tokens/new)，在目标仓库上具有：
- 所需权限：问题（读写）、内容（读写）、元数据（读）、拉取请求（读写）、管理（读写）
- 经典 PAT 具有 `repo` 范围也有效，但授予所有仓库的广泛访问权限 — 优先使用细粒度。
### 快速入门（推荐）
无需安装。添加 `.mcp.json` 和 `.env` 到您的项目中，如上所述的 [与 Claude Code 一起使用](#usage-with-claude-code) — `npx` 将在首次使用时自动获取 okffs。
### 本地开发设置
1. 克隆仓库并安装依赖项：
```bash
git clone https://github.com/neturely/okffs.git
cd okffs
npm install
```
2. 复制环境模板并填写您的凭证：
```bash
cp .env.example .env
```
身份验证和仓库（如果使用 `gh` CLI 并在目标仓库中运行，则两者均为可选）：
```env
GITHUB_TOKEN=ghp_your_personal_access_token_here # 或使用 `gh auth login` 登录
GITHUB_OWNER=your-github-username # 如果省略，则从 Git `origin` 远程自动检测
GITHUB_REPO=your-repo-name # 如果省略，则从 Git `origin` 远程自动检测
```
3. 可选地，设置应用于每个新问题的默认值：
```env
OKFFS_DEFAULT_ASSIGNEES=your-github-username # 以逗号分隔
OKFFS_DEFAULT_LABELS=okffs # 与推断的标签合并
OKFFS_PROMPT_METADATA=true # 设置为 false 以隐藏提示
OKFFS_BASE_BRANCH=main # 创建问题的分支；默认为仓库默认分支
OKFFS_IDENTIFIER=okffs # 可选前缀：分支变为 {number}-{identifier}-{slug}
OKFFS_UPDATE_DOCS=false # 设置为 true 以在工作流事件上自动更新项目文档
OKFFS_AUTO_PR=false # 设置为 true 以在创建新问题分支时打开草稿 PR
OKFFS_RESOLVE_THREADS=false # 设置为 true 以让 okffs 自动解决 PR 审查线程
OKFFS_UPDATE_GUIDANCE=false # 提示保持 CLAUDE.md 与功能更改同步
OKFFS_EXCLUDE_DOCS=SECURITY.md # 以逗号分隔 — 有效选项：CHANGELOG.md, SECURITY.md
```
4. 构建并将您的 `.mcp.json` 指向本地构建：
```bash
npm run build
```
```json
{
"mcpServers": {
"okffs": {
"command": "node",
"args": ["dist/index.js"]
}
}
}
```
## 工具
| 工具 | 描述 |
|------|-------------|
| `create_issue` | 创建一个 GitHub 问题和一个匹配的分支。自动推断标签；与 `OKFFS_DEFAULT_LABELS` 合并。支持可选的 `assignees`、`labels` 和 `milestone`。如果 `OKFFS_AUTO_PR=true`，则立即推送一个空的初始化提交并打开一个草稿 PR。 |
| `create_issues_from_list` | 从任务列表中创建多个问题和分支。确认后执行。每个任务支持 `labels`、`assignees` 和 `milestone`。 |
| `plan` | 接受工作的自由文本描述和 Claude 生成的问题分解（标题、描述、标签、任务间关系），并一次性创建所有问题 + 分支。两步确认。连接新问题之间的关系；当 `OKFFS_AUTO_PR=true` 时，为每个分支打开一个草稿 PR。 |
| `list_issues` | 列出所有开放问题，每个问题都有其问题 URL、分支 + URL、任何链接的开放/草稿 PR（按头部分支匹配），及其关系（父、子、被阻止、阻止）作为树显示。 |
| `get_issue` | 获取问题的完整详细信息 — 标题、正文、标签、分配者、分支和状态。 |
| `comment_issue` | 向问题发布评论。有助于记录分支上的工作。 |
| `link_issues` | 将两个问题链接到关系 — `blocked_by`、`blocking` 或 `parent`。存储在问题正文的 `## Relationships` 部分下。 |
| `close_issue` | 按编号关闭 GitHub 问题。返回提示在 Claude Code 中运行 `/clear` 以开始下一个问题。 |
| `create_pull_request` | 为问题分支创建 PR。从问题生成标题和正文，提交并评论。如果 `OKFFS_UPDATE_DOCS=true`，则提交更新的 CHANGELOG 到分支；打开 PR 前推送分支。始终包含 `Closes #N`。向问题发布摘要评论。 |
| `commit_and_update` | 暂存所有更改，从提供的 `hint`（或更改的文件列表）生成提交消息，提交，推送到问题分支，并向链接的问题发布丰富的进度评论。 |
| `list_pr_review_comments` | 获取 PR 的审查反馈：内联评论线程（带有评论 ID、文件/行、作者、正文、解决状态）和审查摘要。 |
| `reply_to_review_comment` | 通过 ID 回复内联 PR 审查评论线程。 |
| `resolve_review_thread` | 标记 PR 审查线程已解决。由 `OKFFS_RESOLVE_THREADS` 控制 — 如果未启用，则拒绝除非启用，否则留下线程由您解决。 |
| `prepare_release` | 升级版本（`package.json` + `package-lock.json`），滚动 CHANGELOG（`[Unreleased]` → 带日期的版本部分），在发布分支上提交，并打开 PR。两步确认；接受显式 `version` 或 `bump` 级别（如果省略则推断）。**不**标记或发布。 |
| `delete_issue` | 关闭问题 **和** 删除其匹配的分支。破坏性 — 需要 `confirmed: true`。 |
| `delete_branch` | 删除分支 **和** 关闭其匹配的问题。破坏性 — 需要 `confirmed: true`。 |
破坏性工具（`delete_issue`、`delete_branch`）遵循两步确认模式：调用一次显示警告，然后再次调用 `confirmed: true` 以继续。评论发布到采取任何操作前的问题上。
## 响应 PR 审查
okffs 开箱即用提供了一套处理拉取请求审查反馈的工作流程。只需用自然语言询问 Claude，例如：
- *"解决 PR #42 的审查评论"*
- *"您可以修复 PR 中评论的问题吗？"*
Claude 读取审查线程（`list_pr_review_comments`），修复有效的评论，提交并推送（`commit_and_update`），回复每个线程（`reply_to_review_comment`），并发布总体摘要（`comment_issue`）。Claude 提供判断和代码修复；okffs 提供 GitHub 管道。
还有一个现成的提示，作为斜杠命令公开 — **`/okffs:address_pr_review`**（接受 PR 编号）— 运行相同的循环。
仅当 `OKFFS_RESOLVE_THREADS=true` 时，才会自动解决审查线程；默认情况下，它们会为您留下开放的线程以供阅读和解决。
## 保持 CLAUDE.md 同步
**`/okffs:update_guidance`** 斜杠命令（可选接受问题编号）审查当前分支上的更改，并维护 `CLAUDE.md` 的单个 okffs 所有部分 — `## Project Guidance (okffs usage)`，由 `<!-- okffs:guidance:start -->` / `<!-- okffs:guidance:end -->` 标记（如果不存在则创建）。它策划 **仅限于该区域**（工具、环境变量、提示、约定）并且 **从不触摸** 您在其他地方编写的内容。它是 **智能** 的指导维护，而不是更改日志追加（这是 `CHANGELOG.md` 的工作），并且如果没有实质性更改，则不会执行任何操作。
设置 `OKFFS_UPDATE_GUIDANCE=true` 以使 `create_pull_request` 在 PR 时提示代理运行它，以便 CLAUDE.md 更新落在同一个 PR 中。斜杠命令无论哪种方式都可用。
## 自动文档更新
当 `.env` 中为 `OKFFS_UPDATE_DOCS=true` 时，okffs 在创建拉取请求时（`create_pull_request`）自动更新本地项目文档。更改写入本地文件 — 提交由您负责。评论或关闭问题 **不会** 触发文档更新，以保持 CHANGELOG 免受噪音和重复条目的影响。
相关时更新的文件：
- `CHANGELOG.md` — 始终更新，创建时如果丢失。条目遵循 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) 格式，添加到 `## [Unreleased]` 下。`create_pull_request` 在打开 PR 前更新它并将其提交到分支，以便它包含在差异中。
- `SECURITY.md` — 在检测到安全、漏洞或 CVE 关键词时更新（前提是文件存在）。
`CLAUDE.md` 和 `CONTRIBUTING.md` **不** 自动更新 — 它们以前接收了截断的、类似更改日志的追加，这些追加了 `CHANGELOG.md` 并需要手动清理。`README.md` 也故意排除在外 — 请手动维护。
使用 `OKFFS_EXCLUDE_DOCS` 排除特定文件每个仓库（有效选项：`CHANGELOG.md`、`SECURITY.md`）：
```env
OKFFS_EXCLUDE_DOCS=SECURITY.md
```
## 约定
**分支命名：** `{issue-number}-{kebab-title-slug}`（标题截断为 ~5 个单词）
```
42-add-hero-section-to-homepage
```
**拉取请求：
- 标题：`Close #42 - Add hero section to homepage`
- 正文始终包含 `Closes #42`，因此当 PR 合并到仓库的 **默认分支**（通常为 `main`）时，GitHub 会自动关闭问题。如果您将 `OKFFS_BASE_BRANCH` 设置为非默认分支（例如 `develop`），GitHub 不会在合并时自动关闭 — 请手动关闭问题。
**操作原则：
- 破坏性工具需要 `confirmed: true` — 调用一次警告，重新调用以继续。批量创建工具在执行前确认。
- GitHub 始终是问题的真实来源 — 永远不会是本地。
- 保持工具界面最小：每个工具做好一件事。
## 发布到 npm
需要具有 `@neturely/okffs` 包的 npm 帐户的维护者访问权限（公开发布通过 `publishConfig.access`）。
1. **准备发布** 使用 `prepare_release` 工具（询问 Claude，例如 *"prepare a release"* 或 *"prepare release 0.2.0"*）。它会升级 `package.json` + `package-lock.json`，滚动 CHANGELOG，并打开发布 PR。审查并合并它（然后合并到 `main`）。
2. **标记和推送** 版本：
```bash
git tag v0.2.0
git push origin v0.2.0
```
GitHub Actions 工作流在 semver 标签（`v*.*.*`）上自动发布到 npm，因此 **不要手动运行 `npm publish`**（它会与 CI 冲突）。存储库设置中必须设置 `NPM_TOKEN` 秘密。
> `prepare_release` 故意在标记/发布之前停止，将不可逆步骤（触发 CI 发布）作为手动决定。您仍然可以手动升级，如果您愿意。
## 代码库搜索
该项目使用 [semble](https://github.com/MinishLab/semble) 通过 MCP 进行语义代码搜索。子代理配置位于 `.claude/agents/semble-search.md` 并由 Claude Code 自动拾取。
要手动搜索（需要 `uv`）：
```bash
uvx --from "semble[mcp]" semble search "your query" .
```
