实施讨论稿 · 待接入验证

Skill 反馈收集闭环方案

版本:v0.3.0 · 2026-09-09
状态:Hermes 本地飞书 CLI 接入方案;配置校验已实现,真实收集链路待试点。
范围:仅覆盖使用记录与人工反馈的收集、入表、关联和异常补传,不包含优化排序、Skill 迭代和效果评估。

章节目录

一页结论

沿用 Skill 原编号;环境一次配置;Skill 调用本地 CLI;字段统一;飞书集中收集。

用户使用前,由前置部署流程帮助其在本地 Hermes 环境安装、配置和授权飞书 CLI,并部署统一反馈模块及收集目标。之后 Skill 需要访问飞书时直接复用本地 CLI,不自行安装、登录、改授权或重新配置;发现不可用时明确提醒。

决策 本版方案
Skill 身份 原样沿用交付清单中的正式 skill_id,例如 SK-28、SK-29;不另起反馈编号,不限制大小写、中文或连字符
执行路径 Skill → 共用本地反馈模块 → 已配置的本地飞书 CLI → 公司统一多维表格
一次性准备 部署维护者负责 CLI 环境、账号权限、统一模块和目标表/字段映射,不让每个 Skill 或每位用户重复填写
用户反馈 统一入口自动带入运行信息;2 道核心必填题,问题原因和其他项选填;附加题最多 1 道
失败边界 反馈上传失败不阻断不依赖飞书的业务结果;保留待上传记录并提醒,不伪报成功
当前能力 配置、引用和版本检查工具已实现;本地反馈执行模块、Hermes 触发/入口和真实 CLI 入表仍需部署验收

只配置 CLI 不等于已确定写入目标。公司收集表、字段映射和题库必须统一预置。只生成 JSON 也不等于运行触发、反馈界面或补传已经实现。本版不以另建独立收集服务作为默认前置,不要求各 Skill 自己实现一套 CLI 调用逻辑。

1. 范围与职责

1.1 三个阶段不要混在一起

阶段 要做什么 不应做什么
环境部署,一次完成 在 Hermes 实际运行环境中安装、配置、授权本地飞书 CLI;部署共用模块和目标映射;验证权限 只在终端登录成功就推断 Hermes 子进程也可使用
Skill 制作/迁移 读取原身份与旧快照,生成配置、候选题和共用模块调用位置,运行检查 索要应用密钥、为每个 Skill 新建表或复制一套收集实现
用户使用 共用模块读取配置,调用现有 CLI;可用就执行,不可用就提醒并保留状态 自动发起安装、登录、改授权、切换身份或以成功文案掩盖失败

本次方案修订不在当前电脑安装 CLI、不发起授权、不写入真实飞书数据,也不批量修改已交付 Skill。用户授权边界和公司告知应在部署时明确;用户的人工反馈始终自愿,不得由 AI 代填。

1.2 谁负责什么

角色/组件 责任
部署维护者 一次配置本地 Hermes 与飞书 CLI,预置支持的 CLI 版本、调用身份和共享配置
飞书管理员 一次建立统一业务表,配置字段、最小权限及试点人员访问范围
共用本地反馈模块 运行 ID、持久队列、固定题库、CLI 调用、返回值解析、回执、去重和补传;所有 Skill 复用同一版本
Skill 制作者与 AI 保留业务功能,补充本 Skill 元信息、配置及有来源的候选题,不自由改动公共协议
业务负责人 确认成功标准与题目语义;不承担各台电脑的 CLI 配置工作
收集运营负责人 查看已知积压、重复和关联异常;不能声称掌握一直离线的所有电脑
Skill 使用者 正常使用 Skill,自愿回答体验题;不手填 Skill/运行编号,不搬运本地记录

同一 Skill 的多台安装副本沿用相同 skill_id;不同 Skill 不得重号。它是稳定关联键,不是可随版本变化的显示名称。run_id、event_id、feedback_id 仍由公共程序生成,不能用 Skill 名称或本机流水号替代。

2. 用户使用路径

步骤 用户体验 本地执行
初次部署 安装流程协助完成 CLI 与共享目标配置 维护者在 Hermes 实际进程环境中验收,不交由每个 Skill 重复处理
开始使用 正常调用 Skill 共用模块固定版本、生成 run_id、持久保存开始事件,再执行业务
查看结果 得到结果或看到业务失败/取消状态 更新运行状态;有条件即通过本地 CLI 上传
打开反馈 看到本次 Skill 名称及运行时间,不填编号 本地统一反馈入口从该 run 的快照自动取题
填写提交 两道核心选择题,可选补充原因 用户明确提交后,模块保存真实答案并调用 CLI 写入公司反馈表
上传不可用 提醒“尚未上传”,不要求重新填写 本地保留数据,恢复后由同一模块补传并核对关联

如果只是反馈收集失败,已完成的非飞书业务仍正常交付;如果业务动作本身需要飞书,例如实际创建飞书文档,则该动作未成功时不能被标为完成。两者必须分别报告。

本地 CLI 未安装、未配置、登录失效或权限不足时,只提醒具体原因和前置维护入口,不在 Skill 执行中启动环境配置。网络或权限问题未恢复前,不能宣称已收集完成。正常运行不应反复弹出配置询问;同类异常去重提醒,但待上传状态持续可见。

“30 秒完成”仍为待实测目标。未填写反馈是正常状态,不等于满意、差评或数据丢失。

3. 本地 CLI 接入与执行路径

3.1 默认架构

共用本地反馈模块是随部署交付的本地程序/脚本,不是要求另建中央收集服务。Skill 只调用其稳定入口;模块再直接调用本地飞书 CLI,统一处理参数与返回值。实际模块不存在时,不能用 Prompt 声称已接入。

收集流程
前置部署(一次)
  → 配置 Hermes 可调用的飞书 CLI 与最小权限
  → 预置公司收集目标、字段映射、固定题库、共用模块

用户调用 Skill
  → 共用本地模块:运行开始、持久队列、版本快照
  → 本地飞书 CLI:按统一字段写入使用记录
  → 统一反馈入口:用户选择并提交真实答案
  → 同一模块与本地 CLI:写入反馈并关联运行
  → 飞书三张统一业务表 → 返回实际入表状态

共用模块使用结构化参数或标准输入传递 JSON,不把 Skill ID、题干、用户文本拼接成 shell 命令。编号命名放开不代表可以把任意编号直接用作路径或命令;涉及本地文件名时由程序独立编码。CLI 凭据由本地 CLI 管理,不复制到 Skill、反馈页面或输出报告。

3.2 统一反馈入口

默认入口由本地模块提供,展示本次运行的固定题库和已发布附加题,答案仍由用户主动填写;提交交给同一模块调用 CLI。可以使用本地表单;Hermes 如何打开或呈现入口、与本地模块如何通信,需要试点实际验证,不能假设客户端天然支持表单。

MVP 限制为发起运行的同一用户、同一本地安装提交或编辑反馈,避免多设备同时写同一逻辑记录。模块按固定 ID 取题,不让 AI 每次改写通用题或选项。若无法提供稳定的本地入口,标记为能力缺口,不能改成 AI 代答或伪造可用链接。

已有飞书原生表单可以作为后续可选入口,但必须单独验证预填、身份、运行关联、题目版本和重复提交;不能仅拼接网址就宣称完成自动关联。它不是本次 CLI 路线的额外前置。

3.3 调用约定与异常提醒

环节 共用模块的固定行为
环境探测 使用 Hermes 实际运行用户、PATH 和身份检查 CLI;必要时只读查询授权状态,不启动配置流程
目标定位 从共享目标配置取得真实 Base/table/字段映射及明确调用身份;禁止每个 Skill 自选目标或新建收集表
开始事件 生成 UUIDv4 run_id,先保存事件再上传;run 的边界是一次明确 Skill 调用,同次澄清沿用编号
状态更新 started → succeeded / failed / cancelled;无明确结局标 unknown,后来收到可信终态再纠正
事件顺序 event_id 与 sequence 由程序生成;同事件重试复用原 ID,迟到的开始事件不能覆盖终态
固定快照 保存 skill_id、各版本、题目和选项快照;用户晚些填写也不换成最新题目
成功判定 核对 CLI 退出状态与 JSON 成功信封、返回记录及必要字段;不能只因命令已发出就标成功
缺项提醒 CLI 缺失/未配置/登录失效/目标无权限/映射缺失分别报告;保留待上传,不主动安装、登录、改授权或换身份
业务边界 反馈问题不阻断已完成的独立业务;业务动作依赖飞书时,单独如实报告其失败

现有 lark-cli 的成功信封用 ok=true,不能用旧式顶层 code=0 规则判断;写入返回的 ignored_fields 也须核对。调用语法和返回契约应由部署时验证过的 CLI 版本固定,不由各 Skill 临时生成不同命令。

公司部署准备不等于每台电脑永远可用:权限可能失效,运行时仍需检查。无稳定开始/结束触发、进程恢复检查或持久队列时,只能标为“尽力记录”,不能保证每次使用均被收集。

4. 异常处理、去重与补传

4.1 本地保存与飞书入表分开

状态 含义 是否完成收集
local_pending 事件或用户提交的答案只保存在本地 否
feishu_persisted CLI 返回可信写入结果,并取得 record_id、核对必要字段 使用记录已入表;反馈仍需核对关联
link_pending 反馈已入表,但运行尚未入表或关联未写成功 否,等待补关联
collected 反馈已入表且关联到正确 run 是
needs_attention 环境/权限/映射故障,或写入结果无法确定 否,保留待处理

本地已保存不叫“飞书已接收”;本版没有默认中转服务,不再使用远端 accepted 作为执行阶段。只有取得对应记录的可信飞书确认后才清理该事件的 outbox 正文,保留必要回执。用户不应因上传失败而重复填写同一份答案。

4.2 单写入者与重复控制

对象 固定规则
本地队列 同一安装只允许一个队列写入者;进程间加锁,按逻辑记录串行执行,重启后恢复待处理状态
使用记录 run_id 全局随机唯一;记录本地 run_id → 飞书 record_id 映射,后续状态使用 record_id 更新
用户反馈 程序为同一 run 和提交者固定 feedback_id;编辑递增 submission_revision,不让旧修订覆盖新答案
超时/回执丢失 先按逻辑 ID 核对远端;找到唯一结果就补回执,多个结果或结果仍不确定时转人工核对,不盲目再创建
两类记录 run_id 用于关联;事件去重、使用记录与反馈去重分别处理,不能共用一个去重键
问卷归属 附加题按 skill_id + questionnaire_version + question_id 解释,不跨 Skill 合并同名 custom_success_01

lark-cli 的 record-upsert 不带 record_id 时是创建,带 record_id 才是更新,不会自动按 run_id 查重。因此 CLI 本身不提供整套幂等保证;共用模块必须管理回执、串行写入和故障对账。没有服务端唯一约束时,不宣称任意并发/多设备条件下“严格只写一次”。不得把同一待传队列复制到多台机器同时补传。

反馈先入表时,由本地受控运行上下文保留真实 run_id,暂记 link_pending;使用记录补到后取得 record_id 再写关联。不能信任用户手填的运行编号强行关联。

4.3 重试与长期离线

  • 网络、限流等明确可重试错误:建议最多 5 次短重试,间隔 5 秒、30 秒、2 分钟、10 分钟、30 分钟并加随机抖动;CLI/飞书返回等待要求时优先遵守。
  • 创建请求结果未知不是普通失败:先对账,不能直接套用重试新增。无法判断时转 needs_attention。
  • CLI 未安装/未配置、授权失效、权限不足或字段错误:停止密集重试,仅提醒维护;Skill 不自动安装、登录、改授权、建表或切换身份。
  • 联网恢复、共用模块启动、用户手动同步时补传;只有已部署并验收后台任务时,才承诺后台定时检查。不能因为写进 Prompt 就宣称进程退出后仍会补传。
  • 未获确认的 outbox 不自动过期删除;积压超过 24 小时提醒。容量不足时明确提示,不能静默删记录。
  • 设备关机、离线且不再运行模块时,本地数据不会自动到飞书。运营只掌握已上报的积压摘要,不能把未知电脑计为已收齐。

5. 题目设计与生成逻辑

5.1 固定题库 skill_common_v1

题目 ID 用户看到的内容与选项 展示与必填规则
task_completion 这次有没有帮你完成任务?完成 / 基本完成 / 没完成 / 尚未判断 必填单选
output_usability 这次产出或执行结果的可用情况?直接可用 / 小改可用 / 大改后可用 / 不能用 / 尚未查看或验证 / 不适用 必填单选;执行操作类可以选不适用
main_issue 这次遇到了哪些问题?没有明确问题 / 理解错需求 / 内容不准确 / 缺少关键信息 / 格式不符合 / 太空泛 / 太啰嗦 / 流程太复杂 / 结果不可用 / 其他 完成度为基本完成/没完成,或可用度为小改/大改/不能用时展示;选填多选
follow_up_allowed 是否愿意后续被追问细节?可以 / 不需要 选填;未选保存 null,不等于同意
additional_comment 补充说明 选填文本

“没有明确问题”与其他问题选项互斥,反馈界面和共用本地模块都校验。跳过问题原因或题目未展示时保存空数组,不能推断“没有问题”。本版删除满意度必填题;历史版本的满意度答案保留原含义,不迁移成新的完成度。

MVP 最多展示 5 项,其中只有 2 项必填。增强版附加题合计最多 1 道,选填,整体最多 6 项。填写时长仅统计实际填写样本,并同时记录提交率,避免只看完成最快的人。

5.2 从成功标准到专属题

  1. 读取来源明确的 Skill 信息卡。success_criteria 保留原文位置和是否经过负责人确认。
  2. 提取一个用户在查看结果后能快速判断的关键点,保留“小改后”“初稿”“辅助判断”等限定。
  3. 与通用完成度和可用度比对;同义重复时不出附加题。
  4. 有独立判断价值时,生成 0–1 道 Skill 专属题。无合适专属题时才考虑类型题,二者合计最多 1 道。
  5. 记录来源原文、选中的标准、门槛保持情况和去重结论。信息不足时留空,不能凭名称补充业务要求。
  6. 负责人确认候选题,发布流程固定问卷版本;运行时读取已发布题目,不每次重新问 AI 出题。
输入字段 用途 限制
skill_type 辅助选择类型题角度 类型本身不是成功标准
main_output / target_user 明确评价对象和用户能理解的措辞 不新增目标和验收门槛
success_criteria 产生题目的实际判断依据 无来源或需要猜测时不出题
common_failure_tags 映射到固定通用问题分类 不动态修改通用多选选项
risk_level 提醒负责人审查可判断性 不让普通用户替代专业正确性验证,不自动新增必答风险题

成功检查题使用同一选项集 success_check_v1:符合该标准 / 基本符合 / 不符合 / 尚不能判断 / 不适用。题干需明确“该标准”具体是什么;一次只问一个判断点。目标是用户查看结果后约 10 秒能作答,仍需试填验证。

5.3 示例与反例

以下为示意输入,不能当作本项目实际 Skill 的成功标准。

已明确给出的成功标准 处理结果 理由
客服回复小改后可发给客户 通用可用度已覆盖,可不生成专属题 不得改问“是否可以直接发”而提高门槛
周报小改后可发送 通用可用度已覆盖,可不生成专属题 不得自行新增“进展、风险、下周计划齐全”等标准
周报中的缺失数据必须明确标记 候选题:这次周报对缺失数据的标记是否符合“明确标记”的要求? 对应单一独立标准;没有缺失数据时可选不适用
数据分析结论可辅助业务判断,但没有明确验证标准 不出“结论是否可信”的专属题,标为待确认 用户未核实数据时不能把主观信任当正确性证据
同时要求事实可追溯、附件完整、风险清楚 根据负责人确认的优先级选一个判断点,或暂不出题 不把多个独立要求揉成一道题

6. 飞书表结构与版本追溯

三张业务表集中在同一公司飞书多维表格。对一条反馈,通用字段可直接筛选;附加题最多一题,采用固定列保存,避免每新增一个 Skill 就新增一批字段。

表 一行代表什么 必需字段
Skill 目录表 一个已发布 Skill 配置版本 skill_id、skill_name、skill_type、skill_version、owner、schema_version、config_version、questionnaire_version、配置快照、发布状态
Skill 使用记录表 一次 run run_id、skill_id、skill_version、config_version、questionnaire_version、actor_id、client_id、started_at、ended_at、execution_status、last_sequence、upload_status、feedback_offer_status、反馈入口生成时间
用户反馈表 一个 run 与提交者对应的有效反馈 feedback_id、run_id、skill_id、respondent_id、submission_revision、questionnaire_version、submitted_at、persisted_at、task_completion、output_usability、main_issue、follow_up_allowed、additional_comment、question_snapshot_json、关联状态、使用记录关联字段

用户反馈表还必须包含下列固定附加题列:extra_question_id、extra_question_kind(type/custom)、extra_question_text、extra_answer_id、extra_answer_label。未展示附加题时这些列为空;展示但跳过时保留题目身份,答案为空。

question_snapshot_json 保存该次问卷的完整题干、选项 ID/文案和显示条件。版本号用于定位,快照用于解释;仅保存最新版配置不足以解释历史反馈。Skill 目录按 skill_id + config_version 唯一,配置变更新增版本,不覆盖旧版。

6.1 字段映射与关联

  • 单个 Skill 的 usage_record_destination 和 feedback_table_destination 固定处于 feedback_config 同一层,不放进 feedback_form。
  • 抽象表引用 skill_usage / user_feedback 必须由部署时预置的公司共享目标解析到真实 Base token、table_id 和字段 ID/类型。资源标识不是访问授权凭据;不能把任意业务表当作公司反馈表。
  • 同名文本字段不会自动成为飞书关联。本地模块按 run_id 找到使用记录的飞书 record_id,再写入配置好的关联字段;匹配不到时保留 link_pending。
  • 日期、枚举、多选、人员与关联字段需要单独映射;企业 actor_id、respondent_id 与飞书人员标识不能默认相同。不能将抽象 JSON 原样作为 CLI 的写入字段;转换由共用模块完成,所有 Skill 复用同一映射。
  • follow_up_allowed 的 yes/no/null 均需保存;未同意追问不等于匿名,运行记录仍可能包含已验证的企业身份。页面明确说明谁能看见反馈。

飞书不同数据表相互独立,需要关联字段、查找引用等方式建立跨表联系。飞书数据表与视图说明

6.2 本地入口、身份与最小数据

使用者身份来自部署选定的 CLI 身份及其经过验证的返回结果;不得把 user 和 bot 混用,也不接受网址自报的 user_id 作为可信身份。所用身份对统一收集表的访问权限在前置部署时验收;普通用户不能因此获得不必要的他人反馈访问权限。

本地反馈入口由模块控制,绑定本次 run 和版本快照,不让用户修改 Skill/运行身份。若采用本地网页,必须限定本机来源并验证会话令牌,浏览器不能获得 CLI 凭据或任意命令执行接口;这些安全边界是本地模块的验收项。跨设备远程填写不属于 MVP,不能复用本地地址冒充远程反馈入口。

默认只收运行元信息、用户主动填写的答案与可选备注;不上传原始输入、输出正文、摘要或输出链接。CLI 凭据留在其本地凭据管理中,不存入 Skill 或共享目标文件。日志脱敏,不输出 accessToken、appSecret 或授权链接。

7. 统一配置标准

本版 schema_version=2.2:放开 Skill 编号的命名格式,增加显式 collection_transport=local_feishu_cli,并将运行策略改为 hermes_cli_collection_v1。配套 Skill反馈配置.schema.json 负责结构检查;编号全局唯一性、目标和权限可用性仍由部署目录及运行检查负责。

skill_id 直接读取 Skill 的正式 manifest/交付清单,接受 SK-28、SK-29、大小写、中文及连字符等非空字符串;不自动改大小写、删字符或重新编号。只要求非空白、不同 Skill 不重号、同一 Skill 保持稳定。无现有身份时才列为待确认;不要求已经有正式编号的 Skill 再登记一套反馈身份。

公司统一维护共享目标、固定题库和本地模块。默认逻辑引用 company_skill_feedback 与 hermes_feedback_cli_v1 是本版协议约定的查找名称,不是实际资源已经部署的证据;安装流程负责把它们解析到真实配置/模块。已有有效公司引用可沿用。制作者不应为了每个 Skill 重复询问账号密钥和表地址;缺部署项统一交给维护者处理。

引用或固定项 由前置部署提供/落实的内容
collection_transport=local_feishu_cli 明确复用本地飞书 CLI,不走旧独立收集服务
collection_profile_ref,默认 company_skill_feedback 真实 Base 和三张业务表 ID、字段映射、选定 CLI 身份、固定题库、统一反馈入口配置;不含用户密钥
runtime_adapter_ref,默认 hermes_feedback_cli_v1 共用本地模块的稳定入口、版本、Hermes 触发方式、队列位置、锁和后台能力
runtime_policy_ref=hermes_cli_collection_v1 第 3–4 节的本地调用、回执、状态、去重和补传约定
privacy_policy_ref=metadata_only_v1 第 6.2 节默认允许字段及访问边界
common_question_set_id=skill_common_v1 固定通用题库,不由各 Skill 重生成
option_set_id=success_check_v1 固定成功检查选项集,候选题只引用

下面是首次建立配置时的空白草稿模板。模板中的 1.0.0 仅用于已确认没有历史配置的首次创建;已有配置必须按第 7.3 节计算版本,不能重置。null 和空数组表示尚未提供依据;这份模板本身不能上线。配置保持 enabled=false,直到发布流程完成全部门槛。

标准 JSON · 空白草稿模板
{
  "schema_version": "2.2",
  "skill_info_card": {
    "skill_id": null,
    "skill_name": null,
    "skill_type": "other",
    "skill_version": null,
    "owner": null,
    "target_user": null,
    "main_scenario": null,
    "main_output": null,
    "success_criteria": [],
    "non_goals": [],
    "risk_level": "unknown",
    "common_failure_tags": []
  },
  "feedback_config": {
    "config_version": "1.0.0",
    "questionnaire_version": "1.0.0",
    "release_status": "draft",
    "enabled": false,
    "collection_channel": "feishu", "collection_transport": "local_feishu_cli",
    "collection_profile_ref": "company_skill_feedback",
    "runtime_adapter_ref": "hermes_feedback_cli_v1",
    "usage_record_destination": {
      "type": "feishu_base",
      "table_ref": "skill_usage"
    },
    "feedback_table_destination": {
      "type": "feishu_base",
      "table_ref": "user_feedback"
    },
    "feedback_form": {
      "renderer": "unified_feedback_page",
      "question_mode": "common_only"
    },
    "relation_key": "run_id",
    "runtime_policy_ref": "hermes_cli_collection_v1",
    "privacy_policy_ref": "metadata_only_v1",
    "feedback_questions": {
      "common_question_set_id": "skill_common_v1",
      "type_specific_question": null,
      "custom_questions": []
    },
    "question_generation_logic": {
      "selected_criterion_id": null,
      "source_quote": null,
      "threshold_preserved": null,
      "duplicate_check": "pending",
      "skipped_reason": "尚未提供可核实的成功标准;本模板未生成附加题。",
      "requires_confirmation": ["补充有来源的成功标准,完成出题判断。"]
    }
  },
  "open_items": [
    "待从实际 Skill 填充信息和成功标准依据;公司统一接入引用须在部署阶段验证解析,不逐 Skill 配置飞书。当前为未启用模板。"
  ]
}

7.1 校验与发布门槛

层次 检查内容 谁执行
本地结构校验 配置规范 2.2、原编号非空白、本地 CLI 传输标识、固定字段层级、枚举、附加题合计≤1、有题/无题说明一致、就绪版本非空;所有模式就绪前均须清空两处待确认清单、去重结论非 pending 配套检查工具,严格模式运行
本地引用与版本校验 成功标准 ID 不重复、题目引用存在、题目/生成说明/标准的原文一致;读取可信旧配置逐项计算版本,拒绝重置和错误升版 配套检查工具,见第 7.4 节
外部引用校验 复用正式 Skill 编号且不重号、共享目标和本地模块可解析、部署试点中的 CLI 身份与表权限可用 部署/发布流程与制作者;不属于配置检查工具已实现能力
语义确认 依据真实、门槛未改变、一题一个判断点、不重复通用题、用户能判断 业务负责人
表单发布 题目可显示、字段可写、版本快照固定,草稿不被线上读取 公共组件维护者
链路验收 开始记录、入表、反馈、关联、失败与补传均通过第 9 节用例 试点负责人
启用 真实身份和配置补齐、负责人确认留痕、本地与外部检查均有报告,才可置 ready/true;不能只凭本地退出码为 0 启用 发布流程,AI 不自行置为就绪

question_mode=common_only 时候选附加题不展示;切换 extended 需附加题确认并按第 7.3 节生成新问卷版本。草稿不被线上读取;新生成草稿必须保留旧配置的实际模式,除非明确要求切换。修改已展示题目时同时更新问卷和配置版本,保持历史快照不变。

旧配置迁移时将嵌套的 feedback_table_destination 提升到 feedback_config 同层,将 question_generation_logic 统一放在该层;version 只有确实代表业务 Skill 版本时才映射为 skill_version。旧 5 题题库与答案保留旧版本。已有 SK-28 等正式编号直接沿用;旧反馈 ID 如果不同,应集中核实身份映射,不擅自覆盖历史键。缺失信息列为待确认,不能通过把 enabled 改为 true 来绕过接入检查。已有 Skill 需单独迁移验收,本次文档修订不自动改变它们的运行行为。

7.2 有题与无题的一致性

情况 必须保存的字段 校验约束
有附加题(无论是否已展示) selected_criterion_id 和 source_quote 非空,分别与题目引用的标准 ID、原文一致;threshold_preserved=true;duplicate_check=distinct;skipped_reason=null 不得同时保留“未生成附加题”说明;待负责人确认的内容进入 requires_confirmation
无题,尚缺资料或未完成判断 题目为空;selected_criterion_id、source_quote、threshold_preserved 均为 null;duplicate_check=pending;skipped_reason 为具体原因 requires_confirmation 至少一项;有“尚待判断”的真实原因,不伪装成已经检查完毕
无题,通用题已覆盖 题目为空;三个来源/门槛字段均为 null;duplicate_check=duplicate;skipped_reason 说明重复的通用题 不得声称 distinct;候选标准与原文可在原因和文字说明中交代
无题,确实没有合适附加判断点 题目为空;三个来源/门槛字段均为 null;duplicate_check=not_applicable;skipped_reason 说明不适用的原因 不能用此状态掩盖缺少资料或未完成检查

JSON Schema 校验字段组合和必要值;标准 ID 存在性、题目/说明/标准的原文一致性,以及与旧版的版本比较,由配套本地工具执行第二层检查。单独运行 Schema 仍不能代替完整工具。资料原文是否真实、语义门槛是否准确保留,仍须业务负责人确认。

无论 common_only 还是 extended,ready/true 均要求 open_items=[]、requires_confirmation=[],duplicate_check 不得为 pending。隐藏的候选题也不能绕过引用检查;引用未确认的标准时,草稿必须保留明确确认事项。

7.3 配置与问卷版本规则

schema_version 是本方案的结构版本;skill_version 来自 Skill 本身;config_version 标识接入配置;questionnaire_version 标识用户实际看到的问卷。四者不能相互代替。配置与问卷版本均采用无前导零的 X.Y.Z 非负整数格式;本方案的自动更新仅将 Z 加 1。

输入或变化 config_version questionnaire_version
明确确认没有旧配置,首次创建 1.0.0 1.0.0
有可读取旧配置,实质内容不变 保留旧值 保留旧值
仅变更接入档案、运行策略、Skill 信息或未展示的候选题 旧配置版本 Z 加 1 保留旧值
用户可见题干、题目 ID、题型、选项集版本、必填/显示规则或附加题开关发生变化 旧配置版本 Z 加 1 旧问卷版本 Z 加 1
2.0/2.1 迁移到 2.2 本地 CLI 协议,用户可见问卷未改变 旧配置版本 Z 加 1 保留旧值
旧配置未读到、旧值缺失/不规范或无法确认是否存在历史版本 不能确定的版本填 null,加入 open_items 不能确定的版本填 null,加入 open_items

排版变化、生成说明或待确认清单变化,以及为审阅暂置 draft/false,不单独触发升版。基准已有值有效且对应内容可比较时,仍按上述规则保留或递增该值;不能因为另一个版本未知,就重置这个已知值。版本未明确时只允许草稿,禁止 ready/true。

比较用户实际可见的题目包时,common_only 模式只考虑固定通用题库;未展示的候选附加题变化仅影响配置版本。extended 模式还比较实际附加题。题目来源说明变化不等于题干变化,不能据此误升问卷版本。

例如旧配置/问卷为 1.4.2 / 2.3.5:内容不变仍是 1.4.2 / 2.3.5;仅更换接入档案为 1.4.3 / 2.3.5;修改已展示题干为 1.4.3 / 2.3.6。再次对同一草稿执行且内容未变,保持该草稿版本,不反复加号。生成结果需在文字说明中列出旧值、变化项、新值和计算依据,不能覆盖已发布历史快照。

7.4 可执行检查与使用方法

配套文件:检查工具与使用说明。工具和测试已保存在项目中,不依赖本次对话或临时目录。当前结构协议为 2.2;旧 2.1 校验规则随工具保存在 schemas/2.1.schema.json,只用于检查历史基准,不把旧快照改写成新结构再比较。

制作者的实际路径:保留旧配置快照 → 生成独立的新草稿 JSON → 运行本地检查 → 根据错误定位修正 → 重新检查 → 提交负责人和接入维护者验收。工具只读文件,不修改配置、不上传、不发布。不要把 JSON 后的解释文字一起写进配置文件。

技术同事首次在 feedback-validation 目录安装锁定依赖并运行回归测试(Node.js 20 或以上;当前实测 Node.js 24):

检查工具 · 运行命令
npm ci --ignore-scripts --no-audit --no-fund
npm test

已有配置时,传入两个独立文件;以下文件名是使用示例,不是已经创建的正式配置:

检查工具 · 运行命令
node feedback-validation/validate.cjs candidate.json --previous previous.json

只有制作者明确确认没有旧配置时才使用首次创建模式;找不到旧文件不构成首次创建证据:

检查工具 · 运行命令
node feedback-validation/validate.cjs candidate.json --first-run
结果 意义与处理
draft_valid,退出码 0 草稿结构、引用和版本计算通过;仍可存在明确列出的待确认事项,不能上线
local_checks_passed,退出码 0 ready 配置的本地检查通过;外部登记、审批和飞书链路仍需独立验证
invalid,退出码 1 结构/引用/版本检查失败,或历史基准未知;按 errors 中的字段位置修正,不得绕过
input_error,退出码 2 文件缺失、JSON 损坏、参数冲突或误用同一文件作新旧配置;修正输入后重跑

报告始终包含 release_authorized=false、external_checks=not_run,以及当前内容指纹;有旧基准时还记录旧内容指纹。指纹用于核对报告对应哪份文件,不是审批签名。部署/发布流程必须自行重跑本地检查,并校验前置部署与试点证据,不能信任 AI 写出的“通过”文字、客户端上传的检查结果或手改的 ready 字段。

支持当前 2.2、符合留存旧规范的 2.1,以及与留存 2.1 字段层级兼容且校验通过的 2.0 历史快照。旧结构不兼容、缺字段、引用损坏或版本格式不规范时明确阻断,交由维护者保留原件并人工迁移确认,不暗中替历史数据补值。旧基准只有一个版本未知时,已知版本仍正常计算,但整体不能报告版本校验通过。

这解决的是配置执行前的检查缺口,不会自动安装或配置 CLI。Hermes 共用本地反馈模块、入口、权限和异常补传仍按第 9 节部署验收。发布就绪是配置及部署试点验收;某用户当天登录失效属于运行环境异常,不应要求重新生成 Skill 配置。

8. Prompt 使用与选择

两段 Prompt 都在完整 Skill 制作完成后使用,但适用对象不同。已经置入过旧版反馈收集方案的 Skill,请使用第 8.2 节“旧版迁移 Prompt”,不要当作首次接入重新生成。

Skill 当前状态 应使用的 Prompt
Skill 已完整交付,尚未加入反馈收集部分 8.1 初次补充反馈配置
已按之前的方案或 Prompt 加入反馈配置、反馈说明或相关脚本,无论是否实际启用 8.2 旧版反馈收集方案迁移(自包含)
不确定是否已经加入反馈收集部分 先读取现有交付物确认,不能仅因找不到文件就按首次创建处理

8.1 初次补充反馈配置 Prompt

使用时机是“完整 Skill 已经生成并交付之后”,不是制作 Skill 的开场指令。推荐在制作该 Skill 的那个对话里,直接追加下面整个 Prompt,让 AI 为刚交付的 Skill 补充反馈配置和候选题,不重新制作 Skill。

粘贴位置 需要提供什么 AI 应如何处理
制作该 Skill 的原对话 通常无需重复介绍;对话中已有可读取的完整交付内容或文件即可 读取本次指定的最终交付版本,执行追加配置任务
新开的对话 提供已完成的 Skill 文件包、可访问目录,或完整 SKILL.md 及必要附属说明 先读取交付物;不能假设能看见其他对话
目标不明确或交付物不可读取 补充 Skill 名称/路径或上传文件 先明确目标与材料,不凭名称猜测,不生成貌似完成的空白配置

完整自动检查还需要配套检查工具和 Schema 能被当前 AI 访问。仅有 Prompt 和 Skill 内容可以生成待检草稿,不代表具备程序校验或飞书接入能力。“Skill 已完整交付”也不自动等于成功标准已获业务确认、已有配置不存在或已接通飞书。

配置阶段与使用阶段分开: 两段 Prompt 都应直接完成能完成的文件和候选接入修改,不为 SK-28 这类现有编号另行索要命名,不要求每个 Skill 重新提供飞书登录配置。保留 draft 是发布审核边界,不是每次使用都要等用户确认;正式部署并发布后,运行时按固定配置自动执行,只在异常时提醒。共用模块和公司写入目标尚未部署时,任何 Prompt 都不能凭空完成真实接入。

初次补充反馈配置 Prompt · 完整可复制
你是公司 Skill 反馈配置助手。本条消息是“完整 Skill 已生成并交付之后”的追加任务,不是重新制作 Skill 的指令。请为我本次指定的已完成 Skill 补充“反馈配置草稿”和有依据的候选反馈题,用于接入公司统一收集系统。范围仅包括使用记录和人工反馈的收集。

开始前先确定本次交付物:
- 如果本条消息追加在制作该 Skill 的原对话中,请读取该对话当前可见、刚完成的完整交付版本及其可访问文件。信息已存在时直接使用,不要求我重复介绍。
- 如果本条消息出现在新对话中,请读取我提供的 Skill 文件包、可访问目录,或完整 SKILL.md 及必要附属说明。不能假设你能读取其他对话,也不能把当前工作目录中的任意 Skill 当作目标。
- 若存在多个可能的目标、交付版本冲突,或交付物不可读取,请先只询问最少必要的名称/路径/文件,暂停生成配置。目标明确且交付物可读取后,再按后文格式输出;个别业务字段缺失则按 null 和待确认规则处理,不要求重新制作整个 Skill。

一、职责和边界
- 本次生成配置和待确认清单,不创建飞书表,不提交任何反馈,不替用户评价结果。
- 保留原 Skill 的业务目标、指令、脚本、输出格式与版本,不覆盖原交付包。直接生成独立反馈配置草稿和检查说明;已有可读取的共用模块接口时,同时交付仅涉及反馈章节/调用位置的候选修改。不要只给建议或因基础设施未就绪停止其他可完成的工作;不得自行重写业务逻辑、启用草稿或为此 Skill 新造一套执行模块。
- 默认环境是已完成飞书 CLI 部署的本地 Hermes。共用本地反馈模块负责开始记录、状态更新、调用本地 CLI、回执、去重和补传;统一本地反馈界面负责题目展示;飞书集中存储。配置生成不代表这些组件已部署。
- 不把“生成 JSON”报告为“已接通飞书”。输出始终保持 release_status="draft"、enabled=false。
- 如有旧配置,先读取并迁移;保留有依据的 Skill ID、skill_version 及负责人。config_version 和 questionnaire_version 必须按下面的版本规则处理,记录迁移差异,不直接覆盖已发布配置。
- 新旧配置必须保留为独立文件;先读取旧快照再生成新草稿,不得先覆盖旧文件再把新内容当旧基准。

二、输入与证据
- 使用本次指定交付版本的 SKILL.md、相关附属说明、可见的交付确认信息,以及本轮明确提供的补充信息。先读取再提取业务身份和事实;当前对话说明与文件不一致且无法确定最终版本时,先确认,不混用不同版本。
- “Skill 已完整生成”不代表其中的成功标准已经由业务负责人确认,也不代表反馈配置一定首次创建。继续按来源证据、旧配置和版本规则分别判断。
- skill_id 原样沿用该 Skill 的正式 manifest/交付清单编号,例如 SK-28、SK-29;不另起反馈编号,不因格式索要新编号。确实没有现有身份或来源冲突时才填 null 并说明;不能仅凭本地信息宣称全公司唯一。
- skill_version、owner 未提供则为 null。接入引用优先沿用公司已经明确提供且符合本地 CLI 路线的正式引用;否则使用本协议默认逻辑引用 collection_profile_ref="company_skill_feedback"、runtime_adapter_ref="hermes_feedback_cli_v1"。它们是部署时统一解析的别名,不是实际表 ID、密钥或已部署证明。无需为每个 Skill 重新询问这些环境配置;如当前无法解析,标记“部署待验证”,继续完成候选稿。
- 每条 success_criteria 必须包含 id、statement、source、confirmed。
  source 写“文件或消息位置 + 原文依据”;confirmed 只有来源中明确经过负责人确认时才能为 true。
- 不根据 Skill 名称推断新成功标准;可提出建议,但仅放入 open_items,未经确认不作为出题依据。
- common_failure_tags 每项包含 tag、source、mapped_common_issue_id,映射到固定通用问题分类,不能修改通用题选项。
- 公司接入档案统一保存真实 Base/表/字段映射、显式调用身份和反馈入口;凭据由本地 CLI 管理。单个 Skill 只引用档案,不复制凭据、不自动配置环境。

字段取值与选择规则(以下英文值必须原样写入 JSON,不用中文替代):
- schema_version 固定为 "2.2";collection_channel="feishu"、collection_transport="local_feishu_cli"、runtime_policy_ref="hermes_cli_collection_v1"。
- skill_type 只能是 document(文档)、data_analysis(数据分析)、workflow(流程执行)、customer_service(客服)、code(代码)、other(其他或无法明确分类)。根据主要目标选择;无法确定时用 other 并说明待确认点。
- risk_level 只能是 low、medium、high、unknown。优先沿用有来源且适用于当前 Skill 的风险等级;无法确认时用 unknown,不凭名称指定等级。
- duplicate_check 只能是 pending(缺资料/待检查)、distinct(与通用题不同且保留附加题)、duplicate(被通用题覆盖而不出题)、not_applicable(已检查,确实无适用判断点)。必须按后文有题/无题分支填写。
- question_mode 只能是 common_only 或 extended;首次默认 common_only,已有配置保留实际值,除非明确要求切换。renderer 固定为 unified_feedback_page。
- release_status 的规范值为 draft/ready,但本次输出只能为 draft;enabled 只能为 false。
- mapped_common_issue_id 只能是 misunderstood、inaccurate、missing_info、format、too_generic、too_verbose、complex_flow、unusable、other;无法精确映射时用 other。no_issue 是用户答案选项,不能作为失败标签。
- skill_id 接受任何非空白的正式字符串,不限制大小写、中文、连字符或下划线。只要求不同 Skill 不重号、同一 Skill 跨版本保持稳定;不自动改大小写、删字符、转拼音或重新编号。此放宽只针对 skill_id,run_id、event_id、feedback_id 仍由共用模块生成唯一 ID,题目 ID 和固定枚举仍按协议。
- config_version、questionnaire_version 使用无前导零的 X.Y.Z 非负整数格式;只有无法确定旧基准时可为 null,必须列明待确认原因。skill_version 则保留 Skill 源信息的实际格式。
- success_criteria 的 id 在本信息卡内唯一;题目与生成说明必须引用实际存在的同一标准 ID。布尔字段使用 true/false,不写“是/否”。

版本处理(模板中的 1.0.0 不是每次生成的默认回填值):
1. 先读取本次指定 Skill 的旧配置,或取得明确“首次创建、没有旧配置”的证据。读不到文件不等于没有历史配置。
2. 确认首次创建时,config_version 和 questionnaire_version 才初始化为 1.0.0。
3. 有旧配置且实质内容不变时,两个版本保留旧值。排版、生成说明、待确认清单变化,或为审阅置 draft/false,不单独触发升版。
4. 仅接入档案、运行策略、Skill 信息、结构版本或未展示候选题变化:config_version 的第三段加 1,questionnaire_version 不变。
5. 用户实际可见的题干、题目 ID、题型、选项集版本、必填/显示规则或 question_mode 开关变化:两个版本的第三段均加 1。
6. common_only 下候选附加题不进入用户实际可见的题目包,其变化不升问卷版本;extended 下须比较所展示的附加题。只改变题目来源说明,不升问卷版本。
7. 旧版本缺失、不符合 X.Y.Z,或无法取得可信旧配置时,将无法确定的版本填 null 并列入 open_items;不得猜测、倒退或回填为 1.0.0。有效且能比较的另一个版本仍正常保留或递增。
8. 从 2.0/2.1 旧结构迁移到 2.2 本地 CLI 协议算配置变化;若实际题目包未改,问卷版本保留。再次处理同一已生成草稿且内容未变,不继续加号。
9. skill_version 始终引用当前 Skill 的实际版本,不随配置自动加号。四种版本各自独立。
10. 在文字检查结果中写出“是否首次/旧配置来源、旧值、变化项、新值、依据”。缺乏基准时写“版本待确认”,不报告版本校验已通过。
11. 配套工具支持当前 2.2,以及通过留存旧版 Schema 检查的 2.1/兼容 2.0 历史快照;不能将旧快照改写成 2.2 再当作旧基准。不兼容旧结构、旧版本格式错误或引用损坏时,保留历史原件并列入人工迁移事项;不能为绕过错误改用首次创建模式。


三、固定的通用题库 skill_common_v1
题库由公司统一发布并随共用本地反馈模块提供,配置只引用 ID,不重复生成、不改题、不改选项。
- task_completion,必填单选:这次有没有帮你完成任务?
  completed=完成;partial=基本完成;not_completed=没完成;unsure=尚未判断。
- output_usability,必填单选:这次产出或执行结果的可用情况?
  direct=直接可用;minor_edits=小改可用;major_edits=大改后可用;unusable=不能用;not_reviewed=尚未查看或验证;not_applicable=不适用。
- main_issue,条件展示且选填多选:这次遇到了哪些问题?
  当 task_completion 为 partial/not_completed,或 output_usability 为 minor_edits/major_edits/unusable 时展示。
  no_issue=没有明确问题;misunderstood=理解错需求;inaccurate=内容不准确;missing_info=缺少关键信息;format=格式不符合;too_generic=太空泛;too_verbose=太啰嗦;complex_flow=流程太复杂;unusable=结果不可用;other=其他。
  no_issue 与所有其他项互斥;不展示或跳过时保存空数组,不能自动填成 no_issue。
- follow_up_allowed,选填单选:是否愿意后续被追问细节?yes=可以;no=不需要。未选保存 null,不等于同意。
- additional_comment,选填文本:补充说明。
- 本版不收满意度评分;不得擅自加回必填。旧版满意度数据保留原题目版本。

四、附加题生成逻辑
1. 先检查有来源的 success_criteria,从中选一个用户看过结果后可快速判断的关键点。缺依据时不出题,记录原因。
2. 比较通用完成度、可用度是否已经覆盖该判断。相同则不重复出题。
3. 优先生成 0-1 道单个 Skill 专属题;只有没有合适专属题时,才考虑 0-1 道类型题。两者合计最多 1 道,均选填。
4. 类型题以 skill_type 确定角度,但仍需 main_output、success_criteria 等明确来源支撑,不能仅凭类型编造要求。
5. 不改变原成功门槛。输入为“小改后可发”,不能问“能否直接发”;输入只写“可发送”,不能新增“覆盖风险和下周计划”等要求。
6. 一题只检验一个判断点;不把多个独立要求合并为一个无法解释的选择题。
7. 题干写明标准;选项固定引用 success_check_v1:
   met=符合该标准;mostly_met=基本符合;not_met=不符合;unsure=尚不能判断;not_applicable=不适用。
8. 必须允许未判断或不适用。不要要求用户在未核实数据时确认真实性、法律正确性等。
9. 在 question_generation_logic 中记录选中的标准 ID、原文、是否保留门槛、去重结论及待确认点。没有题目时明确 skipped_reason。
10. AI 只能生成草稿;业务负责人确认题目及成功标准、系统校验和端到端验收后,由发布流程启用。
11. 首次创建默认 question_mode="common_only";已有配置按版本规则保留实际模式。候选附加题可以保存在草稿中,但草稿不发布展示;通过确认后才能启用或切换为 "extended"。运行时按已发布版本取题,不每次重生成。

附加题对象必须且仅包含:
{"id":"custom_success_01","type":"single_choice","question":"根据有依据的标准填写具体题干","option_set_id":"success_check_v1","required":false,"source_field":"success_criteria","source_criterion_id":"引用实际存在的标准 ID","source_quote":"该条标准的原文"}
类型题使用 id="type_success_01"、source_field="skill_type",仍引用实际标准 ID 和原文。
没有合适专属题时 custom_questions=[];没有合适类型题时 type_specific_question=null。

question_generation_logic 必须按实际出题结果填写,不能沿用空白模板:
- 有题:selected_criterion_id = 该题的 source_criterion_id;source_quote = 该题的 source_quote = 对应标准 statement 原文;threshold_preserved=true;duplicate_check="distinct";skipped_reason=null。来源未获负责人确认时,在 requires_confirmation 明确列出确认事项,但不伪造 confirmed=true。
- 无题:type_specific_question=null、custom_questions=[];selected_criterion_id、source_quote、threshold_preserved 均为 null;skipped_reason 必须是具体非空原因。
- 无题且缺资料/尚未完成判断:duplicate_check="pending",requires_confirmation 至少一项,说明需要什么信息才能判断。
- 无题且通用题已覆盖:duplicate_check="duplicate",skipped_reason 点明重复的通用题及理由。
- 无题且已检查但没有合适判断点:duplicate_check="not_applicable",说明不适用原因;不得将缺资料伪装为已经检查完毕。
- 如果不能确认门槛保留或无法完成去重,先按无题 pending 分支输出,不保留一个依据未清的题目。
- 输出前检查:有题就不能写“未生成”;无题就不能保留题目引用或 distinct;来源 ID/原文在题目、生成说明、信息卡中逐项一致。
- 所有模式都必须在 open_items 和 requires_confirmation 清空、duplicate_check 非 pending 后才可能进入发布验收;隐藏候选题不免于引用检查。本次仍始终输出 draft/false。


五、收集约定
- 飞书 CLI 的安装、登录授权、选定身份,以及共用模块、目标表和字段映射,由公司部署人员在本地 Hermes 上一次性完成。本次及 Skill 日常运行都不安装、不登录、不重新授权、不自动切换身份、不建表、不改权限;不索取密钥。默认无需另建独立收集服务。
- 所有 Skill 复用同一个本地反馈模块和公司档案,模块直接调用本地飞书 CLI。允许不同的仅是有来源的 Skill 信息、成功标准及最多一道附加题;通用题、存储字段、回执和重试逻辑不得各自生成。没有真实模块入口时不虚构可执行命令,只交付候选调用说明并标记模块尚未部署。
- runtime_policy_ref="hermes_cli_collection_v1":开始时生成 UUIDv4 run_id,先原子持久保存事件再尝试上传;完成、失败、取消均更新,异常中断暂记 unknown。事件有独立 event_id 和顺序号;使用记录以 run_id 为业务键,反馈以独立 feedback_id 和修订号为业务键,旧状态/答案不能覆盖新修订。
- 只有实际 CLI 写入成功、关键字段未被忽略、收到有效 record_id 并保存回执,才标记 feishu_persisted。按本地已验证 CLI 版本解析退出码和 JSON;本方案依据的 lark-cli 使用 ok:true,不把顶层 code:0 当通用成功条件。原生 +record-upsert 没有 record_id 时是新增,不会按 run_id 自动去重;共用模块保存 ID→record_id 映射,同一 outbox 单写入者,超时且写入结果不明时先查询对账,禁止盲目再次新增,不能保证去重时转 needs_attention。
- 本地队列保存成功只代表 local_pending。明确可重试故障采用有上限的退避;认证/权限/字段错误提醒后等待修复,不无限重试。飞书入表及回执落盘后才清理对应事件;反馈已入表但关联未完成时保留 link_pending 补关联任务。长期离线或没有后台进程时不能保证自动补齐,不复制同一 outbox 到多台机器同时补传。
- collection_profile_ref 由部署流程解析到公司统一的 Skill 目录表、使用记录表、用户反馈表及真实字段类型/映射。CLI 已登录不代表目标已存在或可写;缺 CLI、未配置、授权过期、目标不明或权限不足时仅提醒,保留可保存的待传数据。反馈链路故障不阻断无关业务产出;业务本身必须写飞书才能完成时,不能把失败操作报成已完成。
- feedback_form.renderer="unified_feedback_page" 表示共用本地模块的统一反馈界面协议,不要求中央网页服务,也不假设 Hermes 原生支持动态表单。部署时验证实际界面;未实现时不得造一个看似可提交的链接。入口只带随机可过期的关联凭证,模块从本地记录取 Skill/版本/题目;验证本机来源和会话,不信任网址自报身份,不开放任意 CLI 执行能力。MVP 仅支持运行所在设备;跨设备提交另行验收。
- privacy_policy_ref 固定为 metadata_only_v1:默认仅记录运行元信息和用户主动提交的回答;不上传输入输出正文、摘要或输出链接,不在 JSON 内放飞书应用密钥。
- 题目、选项和版本随提交保存快照,后续改题不能改写旧反馈。

六、输出格式与结构自检
先输出一份完整 JSON,严格采用下面模板的字段层级,禁止改名、遗漏、擅自增加字段。按实际信息填充所有字段,并按有题/无题分支及版本规则替换模板默认值;只有允许缺失的字段才能用 null,不能把允许值列表替换成 null,也不能用占位字符串冒充真实 ID。
success_criteria 的元素格式:
{"id":"sc_01","statement":"来源中的成功标准","source":"文件或消息位置 + 原文","confirmed":false}
common_failure_tags 的元素格式:
{"tag":"来源中的失败描述","source":"文件或消息位置","mapped_common_issue_id":"固定通用分类 ID"}

JSON 模板:
{
  "schema_version": "2.2",
  "skill_info_card": {
    "skill_id": null,
    "skill_name": null,
    "skill_type": "other",
    "skill_version": null,
    "owner": null,
    "target_user": null,
    "main_scenario": null,
    "main_output": null,
    "success_criteria": [],
    "non_goals": [],
    "risk_level": "unknown",
    "common_failure_tags": []
  },
  "feedback_config": {
    "config_version": "1.0.0",
    "questionnaire_version": "1.0.0",
    "release_status": "draft",
    "enabled": false,
    "collection_channel": "feishu", "collection_transport": "local_feishu_cli",
    "collection_profile_ref": "company_skill_feedback",
    "runtime_adapter_ref": "hermes_feedback_cli_v1",
    "usage_record_destination": {
      "type": "feishu_base",
      "table_ref": "skill_usage"
    },
    "feedback_table_destination": {
      "type": "feishu_base",
      "table_ref": "user_feedback"
    },
    "feedback_form": {
      "renderer": "unified_feedback_page",
      "question_mode": "common_only"
    },
    "relation_key": "run_id",
    "runtime_policy_ref": "hermes_cli_collection_v1",
    "privacy_policy_ref": "metadata_only_v1",
    "feedback_questions": {
      "common_question_set_id": "skill_common_v1",
      "type_specific_question": null,
      "custom_questions": []
    },
    "question_generation_logic": {
      "selected_criterion_id": null,
      "source_quote": null,
      "threshold_preserved": null,
      "duplicate_check": "pending",
      "skipped_reason": "尚未提供可核实的成功标准;本模板未生成附加题。",
      "requires_confirmation": ["补充有来源的成功标准,完成出题判断。"]
    }
  },
  "open_items": [
    "待从实际 Skill 填充信息和成功标准依据;公司统一接入引用须在部署阶段验证解析,不逐 Skill 配置飞书。当前为未启用模板。"
  ]
}

JSON 后输出三部分:
1. 题目生成说明:输入原文 → 选中的判断点 → 通用题去重 → 保留/放弃理由 → 门槛是否一致。
2. 待确认清单:缺失字段、负责确认的角色、会阻断出题还是阻断上线。
3. 检查结果:标准枚举、结构、附加题总数≤1、有题/无题分支、来源 ID/原文一致性、选项不变、版本对比表、未伪造事实或基础设施、草稿未启用,以及实际工具报告。

七、实际执行检查
- 配套文件为整个 feedback-validation/ 目录(含 validate.cjs、package.json/package-lock.json、schemas/2.1.schema.json)与上一级 Skill反馈配置.schema.json。工具运行需要 Node.js 20 或以上及已安装的锁定依赖;缺少任一项时明确写“未运行完整本地检查”,不伪造工具输出、不静默关闭严格模式,不因生成配置任务自行安装环境。
- 先确认配套工具的实际可访问位置;它可能与 Skill 不在同一目录。下面命令的相对路径以方案所在目录为基准,必要时改用核实后的工具绝对路径,不在其他对话中照抄一个未经确认的路径。
- 有文件写入能力时,将完整 JSON 单独写到本次指定 Skill 的独立草稿文件,解释文字不写入 JSON,不覆盖历史快照。无法写文件或运行工具时,输出待检草稿并明确交接事项。
- 已有可信旧配置时运行:node feedback-validation/validate.cjs <新草稿路径> --previous <独立旧快照路径>。
- 只有制作者明确确认首次创建、没有旧配置时运行:node feedback-validation/validate.cjs <新草稿路径> --first-run。替换尖括号占位为真实路径,有空格时加引号。不得仅因找不到文件就选择首次模式。
- 根据错误修正草稿后重跑;缺来源、历史基准不明或工具不可用时停止自动修复,保留待确认项。不要删除真实缺口、伪造 confirmed=true 或擅自修改公共 Schema 来获取通过。
- 检查结果必须引用实际运行的退出码、status、checks 和 versions。缺乏旧基准时填“版本待确认”;仅执行 Schema 时填“仅结构校验,引用与新旧版本未验证”。
- 退出码为 0 也不等于可发布:draft_valid 仅为合法草稿;local_checks_passed 仅为本地检查通过。报告中的 release_authorized=false、external_checks=not_run 必须保留。工具不创建表、不上传、不发布;正式启用仍由发布流程重跑检查并核验审批和真实飞书链路。

注意:以上检查均不代表真实飞书链路已验证,也不代表题目已经通过业务负责人确认。
材料可读取且目标明确后,直接完成草稿、可完成的候选接入修改及检查;将“文件已完成”“部署未验证”“待业务确认”分别说明,不因为缺环境配置只回复追问。

8.2 旧版反馈收集方案迁移 Prompt(自包含)

专门适用于:之前已经按照旧版反馈收集方案或旧版 Prompt,在 Skill 中加入了反馈收集部分,现在需要迁移为本版方案的 Skill。 包括仅生成了旧配置/说明、已有反馈脚本,以及已实际启用的情况;“已置入”不自动等于“已接通飞书”。从未加入反馈部分的 Skill 使用第 8.1 节。

推荐在原来制作该 Skill 的对话中追加下面整段 Prompt。它已内置字段规则、题库、迁移约束、JSON 模板及检查要求,不需要再附其他方案文档或让 AI 去其他对话查找规则;但原 Skill 和旧反馈配置仍须可以读取。目标不明或原文件缺失时,先补充目标/文件,不凭名称猜测。

迁移生成独立候选草稿、可完成的反馈接入修改和检查说明,保留旧快照,不自动切换已启用流程。缺少程序运行能力或公司校验工具时可以生成待检草稿,但必须注明“未运行完整程序校验”;自包含 Prompt 不等于内置了本地执行模块或完成飞书部署。

旧版迁移 Prompt · 自包含 · 完整可复制
这个 Skill 已经制作完成,也已按旧版 Prompt 生成反馈收集部分。请依据本条消息中的完整规则,将反馈部分迁移为新版候选方案,不要重新制作整个 Skill。本条消息已包含迁移所需规范,不需要另行查找方案文档。

**一、读取目标并保护原交付物**
- 读取本对话中已完成的 Skill、旧反馈配置、相关说明和反馈脚本。若目标不明确或文件不可读取,只询问最少必要的名称、路径或文件;不要假设能读取其他对话。
- 区分“仅生成配置”“已有执行组件”“已实际启用”,没有证据时标为待确认。先保存独立旧快照,再生成新草稿;不能先覆盖旧文件再拿新内容当旧基准。
- 只处理反馈收集部分,不修改业务目标、业务代码或输出格式。不得覆盖已发布配置、历史记录或原交付包,不自动停用或切换现有流程。需调整原 Skill 的反馈章节或运行接入位置时,交付候选修改并说明影响,等待确认后切换。

**二、新版字段与证据规则**
- 结构版本 schema_version="2.2";collection_channel="feishu"、collection_transport="local_feishu_cli"、runtime_policy_ref="hermes_cli_collection_v1"。本次候选配置始终 release_status="draft"、enabled=false。Skill 已完整交付不等于业务标准已确认、没有旧配置或已接通飞书。
- skill_id 原样沿用正式 manifest/交付清单中的编号,例如 SK-28、SK-29;接受任意非空白字符串,不限制大小写、中文、连字符或下划线。只要求不同 Skill 不重号、同一 Skill 跨版本稳定;不能因旧正则不接受就填 null 或另要一个反馈编号。不做大小写转换、删字符或重新编号;确实缺失或来源冲突时才填 null 并说明。全局唯一性由公司目录核验。旧反馈已经使用另一非空 ID 时,保留历史快照,列出身份冲突及别名映射迁移待办,不能静默改号混淆历史。skill_name、skill_version、owner、target_user、main_scenario、main_output 依据实际来源填写,缺失填 null;不改变原 Skill 版本。放宽命名仅针对 skill_id,运行/事件/反馈的唯一 ID 和题目 ID 仍按协议。
- skill_type 只能是 document、data_analysis、workflow、customer_service、code、other;按主要目标选择,不能确定时用 other 并说明。risk_level 只能是 low、medium、high、unknown;没有依据用 unknown。
- success_criteria 是数组,每项且仅含 id、statement、source、confirmed:id 为卡内唯一非空字符串,statement 保留来源中的成功标准,source 写文件/消息位置及依据;confirmed 只有明确业务确认的证据才为 true。无依据时不编造标准,建议仅放 open_items。non_goals 为有依据的非空字符串数组。
- common_failure_tags 是数组,每项且仅含 tag、source、mapped_common_issue_id;前两项为有来源的非空字符串,后者只能使用下方问题类型中的九种问题 ID,不能使用 no_issue。无法准确归类时用 other;无依据则为空数组。所有文本不得仅为空白。

**三、固定通用题库 skill_common_v1**
- task_completion,必填单选:“这次有没有帮你完成任务?”选项:completed=完成;partial=基本完成;not_completed=没完成;unsure=尚未判断。
- output_usability,必填单选:“这次产出或执行结果的可用情况?”选项:direct=直接可用;minor_edits=小改可用;major_edits=大改后可用;unusable=不能用;not_reviewed=尚未查看或验证;not_applicable=不适用。
- main_issue,条件展示、选填多选:“这次遇到了哪些问题?”仅在 task_completion 为 partial/not_completed,或 output_usability 为 minor_edits/major_edits/unusable 时展示。选项:no_issue=没有明确问题;misunderstood=理解错需求;inaccurate=内容不准确;missing_info=缺少关键信息;format=格式不符合;too_generic=太空泛;too_verbose=太啰嗦;complex_flow=流程太复杂;unusable=结果不可用;other=其他。no_issue 与其他项互斥;隐藏或跳过时保存空数组,不能自动填 no_issue。
- follow_up_allowed,选填单选:“是否愿意后续被追问细节?”yes=可以;no=不需要。未选保存 null,不等于同意。additional_comment 为选填文本:“补充说明。”
- 配置只引用题库 ID,不另造通用题字段。本版不收满意度评分;旧答案和旧题库版本保留,不把历史数据改成新问卷答案。固定题库和选项集的同一 ID 下不得悄悄改题。

**四、专属题与类型题**
- 从有来源的 success_criteria 中选用户能快速判断的关键点,先检查通用完成度/可用度是否已覆盖。优先保留或生成一道 Skill 专属题;没有合适专属题时才考虑类型题。二者合计最多一道,均选填,也允许没有附加题。类型题仍需成功标准支撑,不能仅凭 Skill 类型出题。
- 一题只检验一个判断点,题干写明标准,不提高原门槛。例如“小改后可发”不能改问“能否直接发”。选项固定引用 success_check_v1:met=符合该标准;mostly_met=基本符合;not_met=不符合;unsure=尚不能判断;not_applicable=不适用。不能强迫用户在未验证时判断真实性。
- 附加题对象且仅含:{"id":"custom_success_01","type":"single_choice","question":"依据实际成功标准填写题干","option_set_id":"success_check_v1","required":false,"source_field":"success_criteria","source_criterion_id":"实际标准ID","source_quote":"该标准statement原文"}。类型题使用 type_success_01、source_field="skill_type"。旧题 ID 符合 ^(custom|type)_[a-z0-9_]+$ 且属于对应题类时可保留,不能无故改号。无专属题用 [],无类型题用 null。
- 有题时,question_generation_logic.selected_criterion_id 必须等于题目的 source_criterion_id;说明的 source_quote、题目的 source_quote、被引用标准的 statement 必须完全一致;threshold_preserved=true、duplicate_check="distinct"、skipped_reason=null。来源未经确认时 requires_confirmation 必须明确列项,不伪造确认。
- 无题时,selected_criterion_id、source_quote、threshold_preserved 均为 null,skipped_reason 写具体原因。缺资料或判断未完成用 duplicate_check="pending",requires_confirmation 至少一项;通用题已覆盖用 "duplicate" 并点明重复项;已检查但确无适合判断点用 "not_applicable"。不能用“不适用”掩盖缺资料;门槛或去重无法确定时,不保留题目,退回无题 pending。
- question_mode 只能为 common_only 或 extended,沿用有依据的旧模式,不擅自切换。旧模式未知时,候选稿暂用 common_only 并列入待确认。common_only 不展示候选附加题,但仍须检查其引用;extended 正式发布必须有已确认附加题。运行时读取固定已发布题目,不在每次使用时重生成。

**五、迁移与版本**
- 新配置必须采用下方完整层级;旧嵌套反馈表目标迁到 feedback_config.feedback_table_destination,出题说明统一到 feedback_config.question_generation_logic。旧 version 只有确实表示 Skill 版本时才映射到 skill_version;不能将用途不明的版本猜作配置版或问卷版。
- 本次是已有配置迁移,不允许直接初始化为 1.0.0。config_version、questionnaire_version 使用无前导零的 X.Y.Z;内容不变保留旧值;仅接入配置、结构版本、Skill 信息或隐藏候选题变化,配置版本第三段加 1;用户可见题干、题目 ID、题型、选项集、必填/显示规则或问卷模式变化,两者第三段都加 1。旧通用题改为本条的新题库属于问卷变化。
- 排版、生成说明、待确认清单和暂置 draft/false 不单独升版。题目来源元数据变化只影响配置版本,不自动影响问卷版本;对象字段顺序不影响版本判断。再次处理同一内容不重复加号。说明旧值、实际变化、新值和计算依据。
- 缺乏可信旧快照、旧值不规范或语义无法比较时,将不能确定的版本填 null 并加入 open_items,另一个可确定的版本仍正常处理。不重置、不猜测、不修改历史快照来获得通过。
- 从 2.0/2.1 迁移到 2.2,增加本地 CLI 传输字段、更换运行策略和接入引用属于配置变化;可见问卷未变时不升问卷版。配套工具支持当前 2.2、通过留存旧版 Schema 检查的 2.1 及字段兼容的 2.0;保留旧快照原文,不将旧快照改成 2.2 再比较。历史结构不兼容时明确需人工迁移,不伪报校验通过。

**六、收集执行与飞书约定**
- 默认部署环境是本地 Hermes + 已配置的飞书 CLI;安装、登录授权、选定身份、共用模块和目标映射由公司部署人员一次性完成。Skill 使用共用本地反馈模块,由模块直接调用本地 CLI;不以另建中央收集服务为前置。本次和日常运行都不安装、不登录、不重新授权、不自动切换身份、不建表、不改权限、不索取密钥;本次不上传测试数据、不替用户填写反馈。
- 所有 Skill 共用同一套接口、固定题库、字段映射和回执/重试逻辑,不能各自造脚本。只有有依据的 Skill 信息、成功标准与最多一道附加题允许差异。旧 Prompt 要求 AI 写日志不算已有执行组件;能读取真实模块接口时直接交付反馈章节/调用位置的候选修改,不能读取时标明缺少执行入口,不虚构命令。
- collection_profile_ref 优先沿用公司明确提供且支持本地 CLI 的正式档案引用,否则使用本协议默认逻辑别名 company_skill_feedback;runtime_adapter_ref 同理,默认 hermes_feedback_cli_v1。别名由部署流程统一解析,不是实际表 ID 或已部署证明。无需逐 Skill 追问飞书配置;缺少解析证据时标记“部署待验证”,继续完成候选稿。档案应包含公司统一 Skill 目录表、使用记录表、用户反馈表、真实字段 ID/类型、固定题库、入口和显式 CLI 身份,凭据仅留在本地 CLI。
- runtime_policy_ref="hermes_cli_collection_v1":开始时生成 UUIDv4 run_id,先原子持久保存事件;完成、失败、取消均更新,不确定中断暂记 unknown。事件有独立 event_id 和顺序号;运行按 run_id、反馈按独立 feedback_id 和修订号处理,旧请求不能覆盖新状态/答案。
- 本地保存只代表 local_pending;需实际 CLI 写入成功、关键字段未被忽略、有效 record_id 及回执落盘后才标记 feishu_persisted。按本地已验证 CLI 版本解析退出码和 JSON,本方案依据的 lark-cli 使用 ok:true,不假定顶层 code:0。原生 +record-upsert 没有 record_id 时只会新增,不会自动按 run_id 去重;共用模块维护 ID→record_id 映射和同一 outbox 单写入者。超时且写入结果不明先查询对账,禁止盲目再次新增,不能确定去重时转 needs_attention;不要复制同一 outbox 到多台机器同时写入。
- 明确可重试故障采用有上限的退避;认证/权限/字段错误提醒后等待修复,不无限重试。确认飞书入表且回执落盘才清理对应事件;反馈先到时保留 link_pending 补关联任务。长期离线、没有可运行后台进程时不保证自动补齐;未填写反馈不能当满意。
- 已登录 CLI 不等于目标可写;缺 CLI、未配置、授权过期、目标不明或权限不足,只提醒并保存可保存的待传数据,不处理环境配置。反馈故障不阻断无关业务产出;业务本身依赖飞书写入时,不得把失败操作说成完成。
- feedback_form.renderer="unified_feedback_page" 是共用本地反馈界面协议,不要求中央网页服务,不假设 Hermes 原生支持动态表单。部署时验证实际界面;未实现时不提供虚假可提交链接。入口只带随机可过期关联凭证,模块从本地记录读取 Skill/版本/题目,验证本机来源和会话,不信任网址自报身份,不提供任意 CLI 执行能力。MVP 仅支持运行所在设备,跨设备提交另行验收。
- privacy_policy_ref="metadata_only_v1":默认只收运行元信息和用户主动提交的回答,不上传输入输出正文、摘要或输出链接,不把密钥写入配置或迁移报告。题目 ID、题干、选项、questionnaire_version 和专属答案随提交保存快照;后续改题不改历史数据。

**七、完整 JSON 输出模板**
严格保留以下字段,不擅自增删或改名;根据实际资料替换模板,尤其是版本、旧模式和出题说明。允许缺失的字段才用 null;数组用 []。模板中的待确认文字不是事实,须替换为实际检查发现。
```json
{
  "schema_version": "2.2",
  "skill_info_card": {"skill_id": null, "skill_name": null, "skill_type": "other", "skill_version": null, "owner": null, "target_user": null, "main_scenario": null, "main_output": null, "success_criteria": [], "non_goals": [], "risk_level": "unknown", "common_failure_tags": []},
  "feedback_config": {
    "config_version": null, "questionnaire_version": null, "release_status": "draft", "enabled": false,
    "collection_channel": "feishu", "collection_transport": "local_feishu_cli", "collection_profile_ref": "company_skill_feedback", "runtime_adapter_ref": "hermes_feedback_cli_v1",
    "usage_record_destination": {"type": "feishu_base", "table_ref": "skill_usage"},
    "feedback_table_destination": {"type": "feishu_base", "table_ref": "user_feedback"},
    "feedback_form": {"renderer": "unified_feedback_page", "question_mode": "common_only"},
    "relation_key": "run_id", "runtime_policy_ref": "hermes_cli_collection_v1", "privacy_policy_ref": "metadata_only_v1",
    "feedback_questions": {"common_question_set_id": "skill_common_v1", "type_specific_question": null, "custom_questions": []},
    "question_generation_logic": {"selected_criterion_id": null, "source_quote": null, "threshold_preserved": null, "duplicate_check": "pending", "skipped_reason": "尚未完成对实际来源的判断。", "requires_confirmation": ["读取实际来源并完成判断。"]}
  },
  "open_items": ["模板占位:待读取实际交付物并确认历史版本,生成时替换为真实缺口。"]
}
```
**八、检查与最终交付**
- 逐项检查字段层级、类型、枚举、附加题数量、标准 ID 唯一性、引用存在性、三处原文一致性、有题/无题分支、新旧版本计算及未伪造事实。不能通过删去真实待确认项或伪造 confirmed=true 来获取通过。
- 若当前环境已有公司校验器和执行能力,实际运行完整检查并根据错误修正、重跑;需整个 feedback-validation/ 目录(含 validate.cjs、锁定依赖、schemas/2.1.schema.json)、上一级 Skill反馈配置.schema.json 和 Node.js 20 或以上。核实工具实际路径后,运行 node feedback-validation/validate.cjs <新草稿路径> --previous <独立旧快照路径>;路径有空格须加引号,不把历史迁移当 --first-run。不要关闭严格模式、改写公共规则或自行安装环境。仅有 JSON 解析、临时脚本或文字自检时,明确覆盖范围;工具不可用不阻止生成待检草稿,但必须标注“未运行完整程序校验”。
- 任何模式正式启用前,open_items 和 requires_confirmation 都须清空、duplicate_check 非 pending;基础信息、有效版本、接入引用及至少一条经确认的成功标准齐全,并完成外部登记、业务审批和真实链路验收。本次不执行启用;本地检查通过不等于允许上线。
- 交付:独立新版 JSON 草稿、旧新差异及版本计算表、候选题依据与取舍、实际检查结果、待确认事项及负责人角色、候选接入修改和切换条件。分别说明“文件已完成”“部署未验证”“待业务确认”;不因缺少环境配置只回复追问。真实链路还须验证正常运行、失败/取消、中断、CLI 不可用、断网恢复、写入结果未知与去重、反馈先到、历史问卷及权限,不把设计目标写成已实现能力。
材料可读取且目标明确后,直接完成上述迁移草稿和检查,不要只给建议。

9. 试点、验收与待确认事项

9.1 最小落地顺序

阶段 工作 退出条件
接入准备 指定维护者与 Hermes/CLI 版本,统一完成 CLI 安装授权;部署共用本地模块、反馈界面、三张飞书业务表和接入档案 本机调用身份、真实表映射及权限可验证;稳定触发、队列与回执可用
单 Skill 试点 只用通用题,跑通一次运行到人工反馈的链路,再执行异常用例 下表必测项通过,缺口有明确记录
差异化试点 扩展到 3 类 Skill、2 位用户;加入经确认的最多一题附加题 不串题、不串版本、不重复;填写时长和提交情况有样本
内部推广 统一发布模块和配置,执行一次性用户环境部署,设置积压查看和对账职责 只推广已验收的 Hermes/CLI 组合和 Skill;后续 Skill 复用已部署环境,运行时不再安装授权

9.2 端到端验收清单

用例 操作 必须观察到的结果
现有 Skill 编号 分别接入 SK-28、SK-29;同一 Skill 换版本 原编号完整保留且不串 Skill;不要求另起反馈编号,版本变化不改 ID
正常使用 启动并完成一次 Skill,用户提交反馈 一条正确运行记录、一条有效反馈、关联到正确 Skill 与版本
主动失败/取消 人为触发失败或取消 开始记录仍存在,终态正确;不要求一定有业务输出才能反馈
异常中断 开始后退出进程,不发终态 在配置的识别时限后标为 unknown;迟到可信终态可恢复
开始时断网 运行并完成,随后联网 队列可恢复,开始和终态按序合并;无重复使用记录
CLI 不可用 分别模拟未安装、未配置、授权过期及权限不足 提醒并保留可保存的待传数据,不自行安装/登录/换身份;反馈故障不阻断无关业务产出
业务本身依赖飞书 模拟业务所需飞书写入失败 明确该业务步骤未完成,不能借用“反馈不阻断”规则假报成功
目标或字段错误 档案指向错误表,或关键字段被忽略 明确目标/映射异常,不自动新建表字段,不因 CLI 返回成功就标记收齐
飞书故障 本地模块可运行、飞书不可用 标记 local_pending,不显示已入表;恢复后补齐并保存实际回执
写入成功但响应丢失 在同一安装实例模拟飞书写入成功、CLI 回执丢失 先对账再决定重试,不盲目新增;可确认时恢复原 record_id,无法确认时转 needs_attention
同机并发与重复请求 两个本地进程同时处理同一 outbox 单写入者锁生效,运行/反馈分别去重;不把原生 upsert 当业务键去重
不再运行 Skill 产生积压后不调用新任务 已部署且运行中的后台模块可补传;无后台/关机/长期离线明确未收齐,不宣称中央服务已接管
反馈先到 延迟使用记录入表,先提交有效反馈 link_pending 被保留,运行入表后补关联,不丢反馈
题目与历史版本 新旧配置各生成一次运行,再打开本机旧入口 每次展示正确题目;旧答案的题干、选项及版本仍可解释;过期入口不悄悄改用新问卷
重复或编辑提交 重试相同提交,再修改答案提交新修订 重试不重复,新修订更新同一 feedback_id,旧请求不覆盖新答案
本地入口安全 篡改凭证、从其他网页跨源调用、转发到另一设备 不能改成他人运行、伪造身份或调用任意 CLI;跨设备入口明确不可用,不能泄露凭据
表单边界 同选无问题与其他项,选择尚未判断/不适用 冲突被校验;不强迫猜测,不自动代填答案
普通员工权限 用部署时显式指定的调用身份提交 本人可完成流程;验证不能越权查看/改写他人数据。直接 CLI 写入若无法满足权限隔离,须记录限制并阻断不符合要求的推广,不能自动换高权限身份
真实填写 在运行所在电脑的实际反馈界面完成样本 无文字重叠、可操作、2 道核心必答;用时和中途退出被实际记录。汇报 HTML 的手机适配不代表跨设备反馈已实现

建议使用预先登记的脚本化运行清单核对数量,包含成功、失败、取消和离线场景。正常网络下建议目标:记录/反馈 60 秒内入表;恢复网络后积压 10 分钟内补齐;试点样本关联正确率 100%、逻辑重复 0。以上为待试点确认的验收目标,不是无限量生产承诺。

9.3 只衡量收集的指标

指标 计算口径与边界
运行覆盖率 试点预登记实际调用中,有开始记录的比例;不拿“已上报数”自己当分母。生产全量分母不可得时明确覆盖限制
入表成功率 已知本地队列中的有效事件,最终取得飞书回执的比例;试点汇总预登记设备核对。中央表无法看见从未上传的本地积压,不能据此自称全量收齐
反馈提交率 已发出有效反馈入口的运行中,至少有一份用户提交的比例;不要求人人必填
关联正确率 已入表反馈中,关联到正确 run 与版本的比例
积压与重复 超过处理时限的数量、最长积压时间、重复逻辑记录数、link_pending 数
填写负担 实际提交样本的中位用时、较慢样本用时及退出比例;30 秒目标待测

这些指标用于判断有没有收齐、收对,不用于给 Skill 排优化优先级。

9.4 上线前待落实与验证

落实事项 需要的决定或证据
Hermes 与 CLI 版本 确定试点版本及平台;验证 Skill 开始/终态触发、调用方式、返回格式和后台补传。路线已确定为本地 CLI,不再逐 Skill 选集成方式
维护人员 共用本地模块、一次性 CLI 部署、公司表映射、业务题目和收集异常分别由谁负责
公司接入档案 默认逻辑引用解析到真实资源、表字段和固定调用身份;核验权限及使用者可见范围,不在 Skill 内存密钥
本地反馈界面 验证实际 Hermes 环境中可打开并提交的本地统一入口;先支持运行所在设备,跨设备能力不在默认 MVP 内
策略参数 按任务长度确认超时、退避次数、未知写入对账、积压告警、凭证期限及数据保留设置
试点与时间 首个 Skill、3 类扩展样本、2 位用户、试点日期及验收负责人
发布证据 结构/语义校验报告、运行与飞书对账、异常用例和真实填写结果

汇报表述与当前验证边界

建议汇报:“本方案沿用 Skill 现有编号,通过本地 Hermes 中预先配置好的飞书 CLI,将使用记录与人工反馈集中到公司统一表。Skill 只引用统一配置并调用共用本地模块,不负责安装授权。已明确配置、题目与异常处理规范;完成共用模块部署和真实链路试点后,再确认可推广范围。”

当前文件包含实施设计、两段可复用 Prompt、2.2 配置模板和可执行本地检查工具。严格模式、就绪门槛、引用核对、新旧版本计算、放宽编号及本地 CLI 协议已有自动化回归覆盖;程序检查不证明模型每次都会遵守 Prompt,也不代表共用收集模块、Hermes 触发器或真实飞书链路已实现。本次未安装/授权 CLI、未写入飞书、未修改单个 Skill 的原配置。跨模型出题、实际界面、权限隔离、写入未知状态对账、断网补传和端到端关联仍需按本章验证。