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 从成功标准到专属题
- 读取来源明确的 Skill 信息卡。success_criteria 保留原文位置和是否经过负责人确认。
- 提取一个用户在查看结果后能快速判断的关键点,保留“小改后”“初稿”“辅助判断”等限定。
- 与通用完成度和可用度比对;同义重复时不出附加题。
- 有独立判断价值时,生成 0–1 道 Skill 专属题。无合适专属题时才考虑类型题,二者合计最多 1 道。
- 记录来源原文、选中的标准、门槛保持情况和去重结论。信息不足时留空,不能凭名称补充业务要求。
- 负责人确认候选题,发布流程固定问卷版本;运行时读取已发布题目,不每次重新问 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 的原配置。跨模型出题、实际界面、权限隔离、写入未知状态对账、断网补传和端到端关联仍需按本章验证。