# Framework Feedback

> 框架反馈打包 — 把下游项目使用 CataForge 时发现的问题 / 改进建议 / 偏离上游基线的纠偏，打包成 upstream-ready 的 markdown bundle，回流到 CataForge 仓库。区别于下游项目自身的用户反馈渠道：本 skill 仅针对 CataForge 框架本体（CLI / scaffold / agents / skills / hooks / docs）。当用户提到反馈框架问题、提交 CataForge issue、上游 baseline 不准确、累积 upstream-gap 想批量回报时使用。

- Skill: `lync-cyber/framework-feedback` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lync-cyber/framework-feedback`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lync-cyber/framework-feedback/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: lync-cyber (https://skillmd.com/u/lync-cyber)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lync-cyber/framework-feedback

---


# 框架反馈打包 (framework-feedback)

## 能力边界
- 能做: 聚合 `cataforge --version` + `doctor` + 最近 N 条 EVENT-LOG + `CORRECTIONS-LOG deviation=upstream-gap` + `framework-review` Layer 1 FAIL 摘要；渲染为 markdown；脱敏路径；通过 `--print` / `--out` / `--clip` / `--gh` 四选一发出
- 不做: 修复发现的问题（仅打包反馈）；处理下游项目自身的产品反馈（与本 skill 无关）；自动发起 GitHub issue（除非显式 `--gh`，且需本机已装并登录 `gh`）

## 输入规范
- kind: `bug` | `suggest` | `correction-export`
- 项目根下的 `.cataforge/` + `docs/EVENT-LOG.jsonl` + `docs/reviews/CORRECTIONS-LOG.md`（任一缺失都降级为部分 bundle，不阻断）
- `cataforge.core.feedback`（assembler；CLI 与本 skill 共用同一份逻辑）

## 输出规范
- 默认: stdout 渲染 markdown body
- `--out PATH`: 写到指定文件（相对路径解析在项目根下）
- 上游 issue 模板: `.github/ISSUE_TEMPLATE/feedback-from-cli.yml`（字段与本 bundle 一一对应，方便上游分诊）
- EVENT-LOG: 每次运行写一条 `state_change` 事件（`record-to-event-log: true`），ref=`skill:framework-feedback/framework_feedback`

## 推荐触发路径

framework-feedback 是按需触发的反馈打包 skill，**不进入业务流程主循环**。推荐的合规触发面：

- **用户手动**: `cataforge feedback bug --gh`（或 `suggest` / `correction-export`）
- **orchestrator 自动**: 当累计 `upstream-gap` 数 ≥ `RETRO_TRIGGER_UPSTREAM_GAP_DEFAULT` 时，orchestrator 调起 `cataforge skill run framework-feedback -- correction-export --out docs/feedback/<ts>.md`（reflector 只读，本 skill 需要 `shell_exec`，故由 orchestrator 持有）。落盘后由用户决定是否上报
- **doctor 报告 FAIL 后**: `cataforge feedback bug --print | tee docs/feedback/doctor-fail-<ts>.md`
- **不要**: 让 reviewer / implementer 在业务流程内自动调起（与业务 review 报告不是同一资源）

## 操作指令: 上游反馈打包 (feedback)

### Step 1: 触发选择 kind
- 出现可复现 bug / 异常退出 / 部署后失败 → `bug`
- 框架行为符合预期但流程笨重 / 缺特性 → `suggest`
- 累计多条 `deviation=upstream-gap` 纠偏 → `correction-export`

### Step 2: 调用 Layer 1 打包脚本
**调用约定（单一入口）**: 一律通过 `cataforge skill run framework-feedback -- <kind> [--summary ...]` 触发，由框架解析 SKILL.md 元数据并派发到 builtin 脚本。**不得**直接 `python .cataforge/skills/.../scripts/*.py`——该路径为框架内部实现细节，不保证存在。

执行示例:

```bash
# bug 反馈到 stdout
cataforge skill run framework-feedback -- bug --summary "deploy 后 hook 不触发"

# 建议写盘等待复核
cataforge skill run framework-feedback -- suggest \
    --summary "希望支持 --dry-run 预览" \
    --out docs/feedback/suggest-$(date +%Y%m%d).md

# 上游反馈聚合 (仅当 upstream-gap 数 ≥ threshold；缺省 threshold = RETRO_TRIGGER_UPSTREAM_GAP_DEFAULT)
cataforge skill run framework-feedback -- correction-export
```

### Step 3: 上游通道选择
推荐使用 CLI 同等命令直接触发上游通道（skill 仅产 markdown，不直接发 issue）:

```bash
cataforge feedback bug --gh        # 通过 gh 直接开 issue
cataforge feedback bug --clip      # 拷剪贴板，手动粘贴到 GitHub
cataforge feedback bug --out feedback.md  # 落盘
```

#### `--gh` label 解析

label 由 `framework.json#feedback.gh.labels` 配置（`bug` / `suggest` / `correction-export` 三键各映射到一组 label），不在代码里硬编码。`fallback_on_missing_label: true`（默认）让上游 label 缺失时自动丢掉 `--label` 重试并 stderr WARN；要给上游加自定义 label 先跑 `cataforge feedback ensure-labels`（需 push 权限）；空列表等价于不传 `--label`，由 issue 模板的 `labels:` 字段兜底。

### Step 4: 隐私
- 默认会把 `<project>` 与 `~` 路径替换占位符
- 仅在内部反馈 / 自托管 GitHub 时考虑加 `--include-paths`

## Layer 1 检查项

权威清单见 `cataforge.runtime.skill.builtins.framework_feedback.CHECKS_MANIFEST`。

## Anti-Patterns
- 禁止: 把下游项目自身的用户反馈走这条 skill —— 应走下游产品反馈渠道；本 skill 仅打包"对 CataForge 框架"的反馈
- 禁止: 在没有 `gh` CLI 时强行 `--gh` —— 会直接 ExternalToolError；应回退 `--clip` 或 `--print`
- 禁止: 用 `--include-paths` 输出后直接贴公开 issue —— 会泄漏本机目录结构；公开前先脱敏或去掉路径
- 禁止: 没有 `upstream-gap` 纠偏时跑 `correction-export` —— 该子命令会拒绝（exit 1）以防止空 bundle；应先积累纠偏记录
- 避免: 在 `framework.json#feedback.gh.labels` 里写上游不存在的 label 而不先 `cataforge feedback ensure-labels` —— fallback 兜得住但 issue 缺分类标签，影响上游分诊