# Log Fix Branch

> 当用户希望根据应用日志直接排查问题并修复当前 git 分支时使用。适用于日志在本地、挂载目录、SSH 可访问的远端机器，或者用户直接给出可执行的读日志命令的场景。典型触发语包括“日志在...，帮我修当前分支”“ssh 到某台机器读日志并修这个仓库里的 bug”“根据 /var/log/app.log 排查并修复当前分支”。

- Skill: `reaperhero/log-fix-branch` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add reaperhero/log-fix-branch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reaperhero/log-fix-branch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: reaperhero (https://skillmd.com/u/reaperhero)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/reaperhero/log-fix-branch

---


# Log Fix Branch

## 概述

当用户要的是“直接执行并修复”，而不是“只给建议”时，使用这个 skill。

目标是完成一整条闭环：

1. 读取相关日志样本
2. 把日志里的失败信号和当前已检出的代码仓库关联起来
3. 直接在当前分支上修复问题
4. 用尽量小但可靠的方式完成验证

这个 skill 适合“先看日志，再修当前分支”这一类任务，而不是只做高层分析。

## 期望输入

优先接受以下任一输入：

- 本地日志文件路径，例如 `/var/log/app/error.log`
- 一个包含日志文件的本地目录
- 远端日志路径，例如 `user@host:/path/to/log`
- 远端日志路径，例如 `ssh://user@host/path/to/log`
- 用户明确给出的读取命令，例如 `ssh api-prod 'journalctl -u my-service -n 300 --no-pager'`
- 辅助线索，例如请求 ID、时间戳、接口名、panic 文本、异常名、用户侧症状

如果日志来源缺失或有歧义，只询问最小必要信息，不要一次问很多。

## 工作流

### 1. 建立当前仓库上下文

先确认当前仓库状态，而不是立刻改代码：

- 运行 `git branch --show-current`
- 运行 `git status --short`
- 先看项目结构和可能的测试入口
- 把已有但不相关的 worktree 改动视为用户已有工作，不要误改或回退

### 2. 安全读取日志

读取日志时优先稳妥、收敛、只读：

- 对本地文件路径或 SSH 路径，优先使用 `scripts/read_log_sample.py`
- 如果用户给的是远端命令，远端动作保持只读，不要直接修改线上环境
- 从小样本开始，通常先读 `100-300` 行
- 尽早按时间戳、请求 ID、`ERROR`、`WARN`、`panic`、`exception`、接口名等关键字缩小范围
- 如果给的是目录，优先检查最近更新、最可能相关的日志文件

### 3. 形成明确假设

在改代码前，先把日志信号收敛成一个具体判断：

- 把日志证据对应到一个具体代码路径或失败模式
- 用一句话说清“怀疑的根因是什么”
- 明确区分哪些是日志直接证明的，哪些只是推断

没有形成具体假设之前，不要贸然修改代码。

### 4. 直接修当前分支

当日志和代码路径已经能对应上时：

- 直接修改当前已检出的仓库
- 优先做最小、聚焦、可解释的修复
- 如果存在清晰切口，就补充或更新测试
- 如果问题属于纯转换逻辑、边界条件或解析逻辑，优先提炼成一个小的纯函数再测试

目标不是顺手重构整个模块，而是优先修掉日志已经证明的问题。

### 5. 用最小验证闭环

验证时遵循“足够证明即可”：

- 运行最小的命令来证明修复是否有效
- 优先跑仓库原生的单元测试或包级测试
- 如果完整复现条件不可得，至少要验证触发失败的分支、解析逻辑、保护条件或边界条件

### 6. 清晰汇报结果

最终输出应说明：

- 日志里出现了什么关键信号
- 怀疑的根因是什么
- 改了什么代码
- 做了什么验证
- 还剩哪些假设或风险

## 远端日志规则

- 远端访问只用于读取和排查，不用于修改线上系统
- 优先使用当前环境中已经可用的 SSH alias 或主机访问方式
- 如果日志来自 `journalctl`，而服务名不明确，就询问准确的服务名或读取命令，除非上下文里已经很清楚
- 如果问题根因只存在于远端配置或基础设施，不在当前仓库里，就停止并明确说明边界
- 如果 SSH 需要未知密码、OTP、跳板机流程，而当前环境没有现成配置，就暂停并询问准确访问方式

## 推荐命令

对于本地或远端文件路径：

```bash
python3 /Users/edy/.codex/skills/log-fix-branch/scripts/read_log_sample.py \
  "/path/or/user@host:/path" \
  --lines 200 \
  --grep 'ERROR|panic|exception'
```

对于用户直接给出的远端命令：

```bash
ssh api-prod 'journalctl -u my-service -n 300 --no-pager'
```

然后根据日志内容去检查仓库、定位失败路径并修复当前分支。

## 决策规则

以下情况可以自主继续：

- 日志里的失败明显可以映射到当前仓库
- 有一条合理且具体的修复路径
- 可以用较小范围的验证来证明修复

以下情况才暂停并询问用户：

- 用户没有给出可用的日志来源
- 日志证据明显指向另一个仓库
- 唯一修复方式是线上配置或基础设施变更
- 存在多个互相冲突、同样合理的根因，当前证据不足以区分

如果被阻塞，只问一个简短、具体的问题。

## 提示词示例

- `Use $log-fix-branch. 日志在 /var/log/myapp/app.log，帮我直接修复当前分支。`
- `Use $log-fix-branch. 日志在 deploy@10.0.0.8:/data/logs/api/error.log，按日志修当前分支。`
- `Use $log-fix-branch. 先执行 ssh api-prod 'journalctl -u billing -n 300 --no-pager'，然后修这个仓库里的 bug。`

## 资源

- 查看 [references/log-source-formats.md](references/log-source-formats.md) 了解支持的日志来源格式与示例
- 使用 `scripts/read_log_sample.py` 从本地或 SSH 可访问的日志文件中读取紧凑样本