fix-llm-artifacts

修复 LLM 产物

应用先前运行 review-llm-artifacts 后发现的问题，并自动对安全/风险进行分类。如果 .beagle/llm-artifacts-verification.json 存在，跳过标记为 false_positive 的问题，并将 inconclusive 视为风险修复（根据用户选择提示或跳过）。

用法

调用 fix-llm-artifacts 技能，可选择传入以下标志：

fix-llm-artifacts [--dry-run] [--all] [--category <name>]

标志：

• --dry-run - 显示将要修复的内容，但不更改文件
• --all - 修复整个代码库（如果没有审查 JSON，则先运行 review-llm-artifacts --all）
• --category <name> - 仅修复指定类别：tests|dead-code|abstraction|style

指令

硬性门槛

顺序很重要。只有满足每个通过条件后才能应用修复（这些步骤不是“内部验证”）。

1. 工作树 — git status --porcelain 为空，或已创建消息为 beagle-core: pre-fix-llm-artifacts backup 的 stash，且 git stash list 中能看到它。如果用户拒绝 stash/备份，停止，或在报告中记录用户明确接受风险后再编辑。
2. 磁盘上的审查产物 — .beagle/llm-artifacts-review.json 存在，或 --all 已完成 review-llm-artifacts 运行并写入该文件。否则停止（不得凭记忆或猜测修复）。 2a. 回显 + ID 锁定（防止虚构） — 加载审查结果（第 3 节）后，回显来自已解析 JSON 的问题表（id | category | file:line | description），并将确切的 ID 集记录为锁定 ID 集。只能修复此集合中的问题；绝不能修复根据分支名称、目录或记忆推断出的问题。应用或跳过的每项修复都必须与一个锁定 ID 一一对应。参见 review-verification-protocol 技能 → 防止虚构（门槛 0）。 2b. 逐项修复的存在性前置条件 — 编辑任何问题之前，确认 (i) 其 id 在锁定集合中，且 (ii) 所引用的 file 存在，并且所引用的代码确实位于 file:line（现在读取）。如果文件或代码不存在，不要编辑 — 该问题已过时或系虚构；将其标记为跳过并说明原因，然后继续。绝不要为了匹配某个问题而创建或改写文件。
3. 过时的审查结果 — 如果 jq -r '.git_head' .beagle/llm-artifacts-review.json ≠ git rev-parse HEAD，提示重新运行审查。y → 重新运行审查，然后继续。n → 中止修复流程（不得针对过时的问题应用修复）。
4. 验证覆盖文件 — 如果 .beagle/llm-artifacts-verification.json 存在，则必须能解析；在划分问题前先构建排除/待定集合（第 4 节）。解析失败时，停止并报告错误。
5. 风险修复 — 未经第 6 节中的交互式选择（或选择 s 跳过所有剩余风险项），不得执行 code_removal、logic_change、mock_boundary、abstraction_change 或 test_refactor 工作。

编辑后： 只有在调用的工具均成功退出时，第 7–8 节才算通过（非零退出码 = 失败；按清理要求保留 JSON 产物）。

1. 解析参数

从 $ARGUMENTS 中提取标志：

• --dry-run - 仅预览模式
• --all - 扫描整个代码库
• --category <name> - 筛选指定类别

2. 执行前安全检查

# Check for uncommitted changes
git status --porcelain

如果工作目录有未提交更改，发出警告：

Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.

如果有未提交更改，创建 stash：

git stash push -m "beagle-core: pre-fix-llm-artifacts backup"

3. 加载审查结果

检查是否存在审查文件：

cat .beagle/llm-artifacts-review.json 2>/dev/null

如果文件不存在：

• 如果指定了 --all 标志：先运行 review-llm-artifacts --all，生成完整项目审查结果
• 否则：失败并提示："未找到审查结果。请先运行 review-llm-artifacts 技能。"

回显并锁定 ID（门控 2a）： 文件存在后，打印解析所得 JSON 中的每条发现，并在划分之前锁定 ID 集合：

python3 - <<'PY'
import json
r = json.load(open('.beagle/llm-artifacts-review.json'))
f = r['findings']
if not isinstance(f, list) or not f:
    raise SystemExit("No findings to lock; aborting.")
ids = [x.get('id') for x in f]
if any(not isinstance(i, int) for i in ids):
    raise SystemExit("All finding ids must be integers; aborting.")
if len(set(ids)) != len(ids):
    raise SystemExit("Duplicate finding ids detected; aborting.")
print("| id | category | file:line | description |")
print("|----|----------|-----------|-------------|")
for x in f:
    desc = (x.get('description') or '').replace('|', '\\|')[:80]
    print(f"| {x['id']} | {x.get('category')} | {x.get('file')}:{x.get('line')} | {desc} |")
print("Locked ids: {" + ", ".join(str(i) for i in sorted(set(ids))) + "}")
PY

仅裁定并修复上述 ID。如果你认为应该修复的内容与此表不同，以表为准。

可选的验证覆盖层——如果 .beagle/llm-artifacts-verification.json 存在：

• 将 status: false_positive 的发现 ID 构建为集合 → 从所有修复列表中排除这些 ID。
• status: inconclusive 的发现 ID → 始终按第 6 节处理高风险修复，即使审查中的 fix_safety 为 Safe。
• status: confirmed_issue 的发现 ID → 照常使用审查 JSON 中的 fix_safety / risk。

如果缺少验证文件，在应用删除或 dead-code 修复时发出警告："如需减少误报，请先运行 verify-llm-artifacts 技能。"

如果文件存在，验证时效性：

# Get stored git HEAD, scope, and target from JSON
stored_head=$(jq -r '.git_head'   .beagle/llm-artifacts-review.json)
stored_scope=$(jq -r '.scope // "all"'  .beagle/llm-artifacts-review.json)
stored_target=$(jq -r '.target // "."'  .beagle/llm-artifacts-review.json)
current_head=$(git rev-parse HEAD)

if [ "$stored_head" != "$current_head" ]; then
  echo "Warning: Review was run at commit $stored_head, but HEAD is now $current_head"
fi

如果结果已过时，提示："审查结果已过时。是否重新运行审查？（y/n）"。

• y → 使用过时 JSON 中读取的原始范围和目标重新运行 review-llm-artifacts，然后重新加载。这会保留用户的原始意图；不要悄悄扩大或缩小范围，否则可能应用与用户差异内容无关的修复（或遗漏用户关注的文件）。具体来说：
  • scope == "changed" → 调用 review-llm-artifacts "$stored_target"（默认范围已是变更文件）。
  • scope == "all" → 调用 review-llm-artifacts --all "$stored_target"。
  • 如果 JSON 中缺少 scope 或 target（早于当前 schema 的审查结果），不要中止。 假定 scope = "all" 且 target = "."，然后警告：

    "此审查 JSON 早于 scope/target schema；将作为完整项目扫描重新运行（--all）。如果你原本想使用较窄的范围（默认的变更文件差异或某个子目录），请立即取消，并明确重新运行 review-llm-artifacts 技能。" 只有在用户未取消的情况下才继续。

• n → 中止（不要应用修复；过时的发现不可信）。

4. 按安全级别划分发现

解析 JSON 中的发现，并根据 fix_safety 字段分类（应用第 3 步中的验证覆盖层之后）：

安全修复（自动应用）：

• unused_import - 未使用的导入
• todo_comment - 过时的 TODO/FIXME 注释
• dead_code_obvious - 明显不可达的代码
• verbose_comment - 过于冗长、类似 LLM 风格的注释
• redundant_type - 冗余的类型注解

高风险修复（需要确认）：

• test_refactor - 测试结构变更
• abstraction_change - 提取类/函数
• code_removal - 删除功能性代码
• mock_boundary - 测试 mock 范围变更
• logic_change - 任何行为修改

5. 应用安全修复

如果指定了 --dry-run：

## Safe Fixes (would apply automatically)

| File | Line | Type | Description |
|------|------|------|-------------|
| src/api.py | 15 | unused_import | Remove `from typing import List` |
| src/models.py | 42 | verbose_comment | Remove 23-line docstring |
...

否则，按类别应用安全修复。**如果 Agent 支持子 Agent，**则为每个类别并行分派一个；否则，自行依次处理各类别，针对每条发现应用相同的下述契约，并生成相同的逐项修复报告。

Apply safe fixes for category "{category}"
Files: [list of files with findings in this category]
Instructions: For EACH finding, first confirm it is in the locked id set and that the
cited code exists at file:line (read it). If the file or code is absent, skip the finding
with a reason — do NOT create or rewrite a file to match the finding. Then apply each
confirmed fix, preserving surrounding code. Report success/failure/skip per fix by id.

类别（支持时通过子 Agent 并行处理，否则依次处理）：

• style - 注释、格式
• dead-code - 导入、不可达代码
• tests - 与测试相关的安全修复
• abstraction - 安全重构

6. 处理高风险修复

对于每项高风险修复，交互式提示：

[src/services/auth.py:156] Remove seemingly unused authenticate_legacy() method?
This method has no callers in the codebase but may be used externally.
(y)es / (n)o / (s)kip all risky:

记录用户选择：

• y - 应用此修复
• n - 跳过此修复
• s - 跳过剩余所有高风险修复

7. 修复后验证

检测项目类型并运行相应的代码检查工具：

Python：

# Check if ruff config exists
if [ -f "pyproject.toml" ] || [ -f "ruff.toml" ]; then
    ruff check --fix .
    ruff format .
fi

# Check if mypy config exists
if [ -f "pyproject.toml" ] || [ -f "mypy.ini" ]; then
    mypy .
fi

TypeScript/JavaScript：

# Check for eslint
if [ -f "eslint.config.js" ] || [ -f ".eslintrc.json" ]; then
    npx eslint --fix .
fi

# Check for TypeScript
if [ -f "tsconfig.json" ]; then
    npx tsc --noEmit
fi

Go：

if [ -f "go.mod" ]; then
    go vet ./...
    go build ./...
fi

8. 运行测试

# Python
if [ -f "pyproject.toml" ] || [ -f "pytest.ini" ]; then
    pytest
fi

# JavaScript/TypeScript
if [ -f "package.json" ]; then
    npm test 2>/dev/null || yarn test 2>/dev/null || true
fi

# Go
if [ -f "go.mod" ]; then
    go test ./...
fi

9. 报告结果

## Fix Summary

### Applied Fixes
- [x] src/api.py:15 - Removed unused import `List`
- [x] src/models.py:42-64 - Removed verbose docstring
- [x] src/auth.py:156-189 - Removed dead method (user confirmed)

### Skipped Fixes
- [ ] src/services/cache.py:23 - User declined risky fix
- [ ] tests/test_api.py:45 - Test refactor skipped

### Verification Results
- Linter: PASSED
- Type check: PASSED
- Tests: PASSED (42 passed, 0 failed)

### Diff Summary
```bash
git diff --stat

清理

成功完成时（所有验证均通过）：

rm -f .beagle/llm-artifacts-review.json .beagle/llm-artifacts-verification.json

如果任何验证失败，则保留文件并报告：

Review file preserved at .beagle/llm-artifacts-review.json
Fix issues and re-run, or restore with: git stash pop

示例

# Preview all fixes without applying
fix-llm-artifacts --dry-run

# Fix only dead code issues
fix-llm-artifacts --category dead-code

# Full codebase scan and fix
fix-llm-artifacts --all

# Fix style issues only, preview first
fix-llm-artifacts --category style --dry-run