HelixHarness feedback

反馈边界（本 skill 的硬约束，来源 reference/feedback-protocol.md）：反馈是用户显式提交的实时上报，与 usage telemetry 完全解耦——不读取对话之外的任何数据、不创建 eval entry、不消费 telemetry consent（已配置反馈目的地时，telemetry 关闭不影响反馈；默认没有平台地址，未配置时仅保留入口，不能发送。未注册宿主以 host=unknown 上报）。用户明确要求附带时，会话上下文（对话文本 + 工具调用轨迹）随反馈一并发送，发送前经过裁剪（不含工具原始输出、thinking、宿主注入内容）、脱敏（密钥/手机号/邮箱/内网地址替换）与本地标识剥离；绝不写入用户仓库，绝不自动外发任何未经确认的内容。

Runtime 硬门禁：在任何 python3 调用前，必须读取并执行 {plugin_root}/reference/runtime-preflight.md（本文所有 reference/ 相对路径均指 plugin 根下的 reference/，不是本 skill 所在目录旁的 reference/）。runtime preflight 返回 runtime_unavailable 时按其 fallback 规则处理，不得静默跳过运行时检查。

参数宽容规则：解析 $ARGUMENTS 时先按 shell token 分词；每个 token 仅去除尾部常见中英文句读（, . ; : ! ? ，。；：！？、 及右侧闭合括号）后，再对 flag 做精确匹配。不得使用任意子串匹配，例如 --category-bug 不能视为 --category。

使用前提

接收地址默认由发布方在 scripts/reporting_config.py 的 DEFAULT_FEEDBACK_ENDPOINT 统一配置，当前默认值为空，后续需要时再填写。用户可以创建或修改 ~/.helixharness/feedback/config.json，用非空 endpoint 覆盖发布默认值：

{
  "endpoint": "http://127.0.0.1:7860/feedback/report"
}

发布脚本与用户配置文件是仅有的两种地址来源，不读取地址环境变量。HELIXHARNESS_FEEDBACK_HOME 仍可覆盖配置、草稿和队列目录。缺少文件、字段或值为空时使用发布默认值；文件损坏、字段类型错误或非空地址无效时停止准备，不回退到其他接收方。

接收端必须是实际运行的 helixharness-platform；本机可运行 helixharness-server --port 7860，远程平台替换为可访问的完整地址，127.0.0.1 指插件所在机器。发布地址已有效时无需用户再配置。不猜测接收方，不复用统计的 /report 地址；两种来源均为空时停止发送准备并说明配置方法，不声称“已上报”。

触发形态与同意语义

本 skill 支持三种触发形态。终确认必须覆盖准备好的实际接收地址和完整脱敏内容，不跟着触发形态走：

• 图形选择定型（AskUserQuestion）：收集用户原文、分类与 feature 后进入 Step 3 准备草稿；完整内容和接收地址已明确确认时直接发送，不重复确认。
• 文本口头定型（降级路径）：口头回答可能有映射歧义，进入 Step 3 后连同实际地址和脱敏内容一并回显确认。

自动触发的引导规则（识别到用户受挫信号后，何时开口、怎么开口）：

• 时机：先完成自救（重试/修复）。若已恢复且用户全程无感，不开口；若仍失败、需要向用户交代失败时，在交代失败的同一句话里顺带引导，不单独成段、不重复追问
• 开口话术三要素：说明检测到了什么（哪个环节出的问题）、问一句是否提交反馈、说明"后续会先跟你确认分类和关联 feature"
• 两段式确认（硬约束）：用户同意提交 ≠ 完成收集。同意后必须继续走 Step 2 的分类与 feature 收集，不得在用户说"好/可以"的那一刻跳过收集直接发送；收集完成后按 Step 3 准备草稿并确认实际接收地址与内容
• 节制：同一问题一个会话只引导一次；用户拒绝 → 本会话不再就同一问题二次引导（同会话节流）；自救成功且用户无感 → 不引导
• 非交互 / loop（autopilot）上下文禁止自动上报：该场景下本 skill 直接以错误终止并说明原因，不收集、不发送

User Input

$ARGUMENTS

参数说明

执行流程

本 skill 是轻量反馈工具，不做插件版本快速检查（不同于业务工作流命令）：用户带着问题来，升级提示会打断反馈，且上报内容对插件版本零耦合。runtime preflight 硬门禁（python3 可用性）仍然保留。

Step 1: 读取反馈协议

读取 {plugin_root}/reference/feedback-protocol.md（字段语义、transcript 裁剪与脱敏边界、服务端消费契约的唯一权威定义）；读取失败时停止准备和发送，并说明反馈组件不完整。

Step 2: 输入收集（描述先行）

$ARGUMENTS 带反馈内容时：解析出正文与可选 --category / --feature，进入本步收集，随后按 Step 3 准备。正文以用户原话为准，不得改写、总结或补充。--category / --feature 缺哪项就只按本步规则补哪项。

$ARGUMENTS 为空或模型自动触发时：先问一句开放问题（如"说说遇到的问题吧"），拿到描述后再收集分类与 feature——描述是分类推断和 feature 定位的依据，必须先行。

分类推断：从用户描述推断分类并映射到枚举 bug / docs_unclear / process_stuck / suggestion，映射不上即 uncategorized。推断结果只作为推荐项呈现，由用户最终确认。

分类与 feature 的收集——按宿主能力分派。判定规则是确定性的，不得自行裁量：当前会话工具列表里有 AskUserQuestion 就必须走首选路径，没有才走降级路径；禁止在有该工具时降级为纯文本提问。

• 首选路径（会话工具列表含 AskUserQuestion，如 Claude Code）——必须使用：一次调用同时问两问——

  • "反馈分类"：4 个选项（bug / docs_unclear / process_stuck / suggestion，label 用枚举值、description 一句话释义），推断项放第一位并在 label 标"（推荐）"；用户经 Other 自由输入时映射枚举，映射不上按 uncategorized
  • "关联 feature"：选项 = 不关联 + docs/specs/active/ 下的 feature（最多再列 3 个，推断项或最近活跃优先并标"（推荐）"）；active 超出 3 个时经 Other 输入，输入值必须校验存在于 active 列表，不存在则提示重选；docs/specs/active/ 不存在或为空时该问整体跳过（feature=null）
  • 选择完成后进入 Step 3 准备草稿；收集选项本身不替代对实际地址和完整脱敏内容的确认。

• 降级路径（仅当会话无 AskUserQuestion，如 Codex）：对话式收集（下为摘要格式示例，实际值以本轮收集结果为准；在 Step 3 连同实际地址和完整脱敏内容确认后才发送）——

  当前收集的反馈信息（可直接说要改哪项）：
  - 分类：流程卡住
  - 描述：propose 到 P2 卡在确认项清理（你的原话）
  - 关联 feature：early-repayment
  

  无推断依据时相应项写"未分类"/"不关联"；用户口头改 feature 名同样必须校验在 active 列表内，不在则提示可选项。

红线不变：feature 值只允许来自 docs/specs/active/ 实际列表 + 用户确认，任何情况下不得猜测或编造；用户显式传 --feature 时使用该值；"不关联"是有效答案，不二次确认、不暗示次优；非交互/loop（autopilot）上下文不收集、不自动上报；用户所选 feature 没有 eval-log 时 related_entry_ids=[]，合法。

Step 3: 准备、确认并发送

{plugin_root} 必须来自当前 plugin skill resource（Claude 可用 ${CLAUDE_PLUGIN_ROOT}，Codex 使用当前 plugin resource root），不得搜索安装目录。{current_platform} 必须使用 canonical host ID：Claude Code 固定为 claude-code，Codex 固定为 codex。

先准备草稿，不发送。参数必须安全转义：

python3 "{plugin_root}/scripts/feedback_submit.py" prepare --repo-root "{repo_root}" --platform "{current_platform}" --text "{反馈正文}" --category "{分类}"

按用户选择追加 --feature "{feature}"。默认不附带会话；只有用户明确要求附带当前会话时追加 --include-transcript，不搜索历史会话替代。

展示返回的实际 endpoint、完整 item.document 和附带的 item.transcript_md（如有），取得对地址和内容的明确发送确认。已有对同一完整内容及地址的明确授权时不重复确认；内容修改后重新准备。

python3 "{plugin_root}/scripts/feedback_submit.py" send --draft "{draft_path}" --digest "{digest}" --confirmed

--confirmed 必须由真实用户授权支持。脚本失败（exit 1）时向用户原样展示 stderr 中的错误 JSON 并终止，不得重试改写内容。非交互/loop（autopilot）上下文不得自动上报。

Step 4: 回执输出（逐字使用 prepare/send 返回值，禁止手工编造字段）

实时送达（send 的 status: "delivered"）：编号与状态取 send 回执，document 和 transcript_stats 取同一已确认的 prepare 草稿 item，未附带会话时如实说明。

## HelixHarness feedback 已发送

- 反馈编号: {feedback_id}
- 状态: 已实时送达配置的平台看板（{endpoint}）
- 会话上下文: user {transcript_stats.user_messages} / assistant {transcript_stats.assistant_messages}，
  工具调用 {transcript_stats.tool_calls} 次，脱敏 {transcript_stats.redactions} 处
  （transcript_stats.supported 为 false 时，改为如实说明原因，如 codex 会话暂不支持采集）

### 本次发送的完整字段
{逐项列出 document 中的全部字段与值；这是透明披露，不得省略}

进入本地队列（status: "queued"）：如实说明看板暂不可达（delivery 字段），报告已进入本地待发队列（queue_path），下次提交反馈时自动补投，最长保留 30 天，只向原接收地址补投；如本次顺带补投了历史队列消息（queue_flushed.flushed），一并说明。

平台拒绝（status: "rejected"）：尚未送达，保留草稿并报告原因，不改写内容重发。用户要求重试时可执行 feedback_submit.py retry --confirmed，仅补投已确认且与当前配置地址一致的待发记录。

双宿主说明

• Claude Code 与 Codex 使用同一 CLI（feedback_submit.py），反馈流程本身无 hook 参与、无 consent 流程
• 会话上下文采集当前仅支持 claude-code 会话；Codex 宿主仍可上报反馈元数据（transcript_stats.supported=false），不是错误
• 未注册宿主（{current_platform} 无法给出 canonical ID 时）：--platform unknown 仍可上报，文档中 host 记为 unknown

注意事项

• 过程静默 — 内部动作（读取协议/preflight 文件、列出 feature 目录、校验路径与枚举值）不向用户逐条汇报；用户视角只出现业务话术（提问、选项、复述、回执）。读取必需协议失败时停止发送并说明反馈组件不完整
• 正文即用户原话 — 只做 shell 转义，不改写、不翻译、不截断；超 4000 字符时提示用户精简后重试
• 不读会话之外的数据 — 会话上下文仅取当前会话的对话文本与工具调用轨迹；工具原始输出、thinking、宿主注入内容一律排除
• 幂等 — 同一 feedback_id 与相同内容重复上报由服务端去重；相同 ID 的不同内容被拒绝，skill 侧不改写 ID 绕过
• 失败即止 — 校验失败（超长、非法分类、非法 feature 名）原样展示错误，不降级发送
• 不写仓库 — 反馈与上下文不落盘到业务仓库，不执行任何 git 操作