bensz-collect-bugs

Files (14)

• CHANGELOG.md
• README.md
• SKILL.md
• config.yaml
• test_privacy_protection.py · qa/
• test_resolution_protocol.py · qa/
• DATA_MODEL.md · references/
• REPORTING_PROTOCOL.md · references/
• collect_bug.py · scripts/
• common.py · scripts/
• report_bugs.py · scripts/
• resolve_bug.py · scripts/
• BUG_REPORT_TEMPLATE.md · templates/
• RESOLUTION_TEMPLATE.md · templates/

SKILL.md (first lines)

# Bensz Collect Bugs

## 目标

这是一个用于 Bensz Agent Skill 与基础设施设计缺陷留痕和按需上报的 Agent Skill。当 Bensz Agent Skill 在真实用户环境中因设计缺陷而出现 bug，或用户明确说“我想 report bensz skills bugs”“帮我公开上报 bensz skills 的 bug”时使用。该 Skill 负责把 bug 规范化记录到 `~/.bensz-skills/bugs/`，并在用户明确要求公开报告时通过本地 `gh` 轻量上传到 `huangwb8/bensz-bugs`，全程严禁修改用户本地 Claude Code/Codex 中已安装 Skills 的源代码。

用于“先本地留痕，再按需公开上报”的 bug 管理 skill。

## 流程

### 输入

#### 输入契约

##### 本地记录时必需信息

- `skill_name`
- `skill_author`
- `bug_summary`
- `expected_behavior`
- `actual_behavior`

##### 强烈建议补充

- `reproduction_steps`
- `evidence`
- `workaround`
- `agent_runtime`
- `skill_source_path`

### 执行步骤

#### 只处理哪类问题

只处理这类 bug：

- 由于 **Bensz Agent Skill 或 Bensz 基础设施的设计缺陷** 导致其无法按契约工作
- 典型表现包括：流程漏判、输入契约不完整、环境假设错误、脚本/模板设计不健壮、输出规范不一致

不要把下列情况记为本 skill 的 bug：

- 用户数据本身有误
- 第三方服务临时不可用
- 用户主动修改了 skill 源码引入的问题
- 纯粹属于模型偶发发挥波动、但 skill 设计本身没有明显缺陷的情况

#### 标准工作流

##### 阶段一：判断是否属于“skill 设计缺陷”

至少回答清楚：

1. 出问题的 skill 是哪个
2. 它原本应该怎样工作
3. 实际发生了什么
4. 为什么这是 skill 设计缺陷，而不是用户输入问题或外部服务抖动

如果判断不足以支持“设计缺陷”结论，不要强行记录。

##### 阶段二：本地记录 bug

优先运行确定性脚本：

```bash
python3 bensz-collect-bugs/scripts/collect_bug.py \
  --skill-name "<skill_name>" \
  --skill-author "Bensz Conan" \
  --bug-summary "<一句话概括 bug>" \
  --expected-behavior "<预期行为>" \
  --actual-behavior "<实际行为>" \
  --reproduction-step "<步骤1>" \
  --reproduction-step "<步骤2>" \
  --evidence "<关键报错或关键现象>"
```

可选补充：

- `--workaround`
- `--severity`
- `--device-type`
- `--agent-runtime`
- `--skill-source-path`
- `--skill-source-repo`
- `--additional-note`
- `--software key=value`

脚本会自动：

- 收集当前设备 / OS / shell / 常见软件版本
- 对 bug 摘要、预期/实际行为、复现步骤、证据、补充说明等自由文本执行敏感信息清洗
- 按 `config.yaml:hashing.stable_fields` 计算稳定的 `bug_hash`
- 在 `~/.bensz-skills/bugs/{skill_name}/{reporter}/{bug_hash}/` 写入标准化记录
- 若同一 bug 已存在，则只更新 `occurrence_count`、`last_seen_at` 等追踪字段

说明：

- `reporter` 优先使用当前 GitHub 用户名
- 若没有 GitHub 用户名，报告展示名默认使用匿名占位，不再回退到本地用户名
- 若当前机器尚未配置 `gh`，则本地目录先落到 `pending-github-identity/`，公开上报时再改用真实 GitHub 用户名作为远端路径

##### 阶段三：让当前任务继续

记录 bug 并不意味着当前任务必须中断。

如果 AI 仍可通过临时 workaround 完成用户任务：

- 把 workaround 写进 bug 记录
- 继续完成用户眼前的任务

##### 阶段四：公开上报到 `bensz-bugs`

只有当用户明确说出类似意图时才做：

- “我想 report bensz skills bugs”
- “帮我公开上报这些 bensz skill 的 bug”

先检查 `gh`：

```bash

From huangwb8/skills, MIT.

More from huangwb8/skills