fp-review

FP Review 技能

确保提交正确关联到问题，并提供评审反馈。

前置条件

使用 fp 命令前，请检查设置：

# Check if fp is installed
fp --version

如果未安装 fp，请告知用户：

尚未安装 fp CLI。请使用以下命令安装：

curl -fsSL https://setup.fp.dev/install.sh | sh -s

# Check if project is initialized
fp tree

如果项目尚未初始化，请询问用户是否要初始化：

此项目尚未使用 fp 初始化。是否要初始化？

如果是：

fp init

---

核心目的

1. 验证提交是否分配给了正确的问题
2. 在问题上留下评审评论
3. 在桌面应用中打开交互式评审
4. 创建故事——带领读者了解代码变更的叙述性文档

---

将提交分配给问题

检查当前分配情况

fp issue files <PREFIX>-X

如果结果为空，说明该问题尚未分配任何提交。

查找相关提交

jj log --limit 20        # Jujutsu
git log --oneline -20    # Git

查看提交详情

jj show <commit-id>      # Jujutsu
git show <hash> --stat   # Git

将提交与问题匹配

请比较：

• 提交中变更的文件与问题描述
• 提交消息内容与问题标题
• 代码变更与问题要求

分配提交

分配提交前，请先向用户确认。 有些用户更喜欢等工作完成后再提交，也可能不希望将提交关联到问题。

使用 AskUserTool 询问：

我发现以下提交似乎与 <PREFIX>-X 相关：

• abc123 - 添加用户模型
• def456 - 实现身份验证中间件

是否要将它们分配给该问题？（如果你更希望评审未提交的变更，可以运行 fp review 来评审工作副本。）

如果用户确认：

# Single commit
fp issue assign <PREFIX>-X --rev abc123

# Multiple commits
fp issue assign <PREFIX>-X --rev abc123,def456,ghi789

# Current HEAD
fp issue assign <PREFIX>-X

# Reset and reassign
fp issue assign <PREFIX>-X --reset
fp issue assign <PREFIX>-X --rev abc123,def456

验证分配情况

fp issue files <PREFIX>-X
fp issue diff <PREFIX>-X --stat

---

留下评审评论

使用 fp comment 提供评审反馈。请注明文件和行号，以便明确指出问题。

针对特定文件的评论

fp comment <PREFIX>-X "**src/utils/parser.ts**: Consider extracting the validation logic into a separate function for testability."

fp comment <PREFIX>-X "**src/api/handler.ts:45-60**: This error handling could swallow important exceptions. Suggest re-throwing after logging."

严重程度前缀

使用前缀表示重要性：

fp comment <PREFIX>-X "[blocker] **src/auth.ts**: Missing input sanitization creates SQL injection risk."

fp comment <PREFIX>-X "[suggestion] **src/utils.ts:23**: Could use optional chaining here for cleaner code."

fp comment <PREFIX>-X "[nit] **README.md**: Typo in setup instructions."

• [blocker] - 合并前必须修复
• [suggestion] - 建议改进
• [nit] - 细微或表面问题

一般评论

fp comment <PREFIX>-X "Overall looks good. Main concern is the error handling in the API layer - see specific comments above."

---

交互式评审（桌面应用）

fp review 会打开 Fiberplane 桌面应用，进行交互式差异评审。

需要桌面应用。 如果尚未安装，请访问：https://setup.fp.dev/desktop/latest/

评审工作副本（无需提交）

如果用户尚未提交（或更喜欢在工作进行期间不提交）：

fp review

这会显示工作目录中所有未提交的变更。无需分配提交。

按问题评审

fp review <PREFIX>-X

注意： 要使用基于问题的评审，必须先为该问题分配提交。如果尚未分配提交，请选择以下任一方式：

1. 先使用 fp issue assign 分配提交，或
2. 使用 fp review 评审工作副本

使用故事进行评审

fp review <PREFIX>-X --with-story

打开评审时，会在差异旁显示故事面板。必须先为该问题创建故事。

其他评审目标

fp review git:abc123           # Specific git commit
fp review jj:abc123            # Specific jj revision
fp review git:abc123..def456   # Range of commits

---

评审工作流

步骤 1：检查分配情况

fp issue files <PREFIX>-X

步骤 2：分配缺失的提交

jj log --limit 20
fp issue assign <PREFIX>-X --rev abc,def

步骤 3：查看差异

fp issue diff <PREFIX>-X --stat   # Overview
fp issue diff <PREFIX>-X          # Full diff
fp review <PREFIX>-X              # Open in desktop app

步骤 4：留下评论

fp comment <PREFIX>-X "**file.ts:line**: feedback"

---

故事

故事是带领评审者了解代码变更的叙述性文档。它们将 Markdown 文本与嵌入的差异、文件摘录和聊天记录结合起来。

需要启用 experimental_story 功能标志：

fp feature enable experimental_story

创建故事

# From a file
fp story create <PREFIX>-X --file story.md

# From stdin
cat story.md | fp story create <PREFIX>-X

Markdown 中第一个 ## 标题会成为故事标题。

故事格式

故事是使用指令嵌入代码内容的 Markdown 文档：

差异指令

显示问题已分配提交中的文件变更：

## Moved validation to a shared module

The old approach duplicated validation in each handler.

:::diff{file="src/validation.ts"}
Extracted from handler.ts and api.ts into a single module.
:::

• file（必填）：变更文件的相对路径
• :::diff 与 ::: 之间的文本是注释——请控制在 1-2 句话

文件指令

显示文件内容（或其中一段内容）：

:::file{path="src/config.ts" lines="10-25"}
The new defaults that drive the behavior change.
:::

• path（必填）：文件的相对路径
• lines（可选）：行范围，例如 "10-25"

聊天指令

嵌入 AI 编码会话的摘录：

:::chat{source="claude" session="/path/to/session.jsonl" messages="msg1,msg2"}
The key design discussion that led to this approach.
:::

• source："claude"、"pi" 或 "opencode"
• session：会话文件的完整路径
• messages：以逗号分隔的消息 ID

撰写指南

• 标题使用过去时动词 — 描述已经完成的工作，而不是要做什么（例如，“将验证移至共享模块”）
• 从用户遇到的问题开始 — 开篇文字应说明此变更的原因
• 先展示差异，再进行说明 — 以 :::diff 指令开头，随后添加注释
• 注释限为 1-2 句 — 简要说明背景，不要展开完整解释

UI 支持

目前只有 :::diff 能在桌面应用中完整呈现。:::file 可以使用，但 collapsed 属性会被忽略。:::diff 上的 hunks 属性也会被忽略。

管理故事

fp story list                    # List all stories in the project
fp story get <story-id>          # Get story details (supports ID prefix)
fp story get <PREFIX>-X          # Get story by issue ID
fp story delete <story-id>       # Delete a story (supports ID prefix)
fp story delete <story-id> --yes # Skip confirmation

每个问题对应一个故事。为某个问题创建新故事会替换之前的故事。

---

快速参考

命令

# Check assignments
fp issue files <PREFIX>-X

# Assign commits
fp issue assign <PREFIX>-X --rev <commits>

# View changes
fp issue diff <PREFIX>-X --stat
fp issue diff <PREFIX>-X

# Leave comments
fp comment <PREFIX>-X "message"

# Interactive review (desktop app)
fp review <PREFIX>-X

# Stories
fp story create <PREFIX>-X --file story.md
fp story list
fp story get <PREFIX>-X
fp story delete <story-id>
fp review <PREFIX>-X --with-story

注释格式

**filepath**: general comment about file
**filepath:line**: comment about specific line
**filepath:start-end**: comment about line range
[severity] **filepath**: prefixed comment

严重程度级别

• [blocker] - 必须修复
• [suggestion] - 建议考虑
• [nit] - 小问题