kangshifu-board/docs/workshop-dedup-20261102.md

工作坊采集资料查重升级

经理的问题成立：新批次或换业务键原本仍可新增相同来源/实体。已有requestId幂等只解决原请求重放。本升级在现有Skill增加workshop-dedup，并在workshop-import自动预检，服务端实际提交再次在事务锁内检查。

判断规则

情况	行为
同一requestId、同一请求	原回执复用
不同批次、相同owner/模式/来源类型/URL/平台与内容SHA	sourceId复用，保留首次来源元数据
同源结构化资料完整字段相同	objectId复用，operation=unchanged
原始平台记录真实上游ID相同，完整载荷及业务内容相同	可跨来源批次复用；不覆盖已有人工判断
缺真实上游ID	仅同源同索引同载荷复用，不将不同人的相同短评合并
同名但规格、正文、价格、观察时间或原始载荷变化	不自动合并；不同业务键保留独立快照，同键冲突停止核查
相似内容、不同来源URL、不同授权身份	不做语义合并/跨权限去重
历史已有重复	不自动删库，不修引用，不回填伪造身份

无sourceRef的基础分类等按完整字段比较；有sourceRef的普通实体限定同源。原始记录忽略批次runRef、recordIndex、collectedAt及服务端噪声状态，但原始载荷内变化仍保留。合同limits.maxReadScan超限明确失败，不把未查完说成无重复。暂未建立全库语义去重或任意并发写入防线：同表新版导入用数据库事务咨询锁串行，绕过这些函数的旧脚本/直接数据库写入不受保护。

重复资料实体可复用，新的采集执行、操作回执和导入日志仍保留。因此数据库会因新资料和审计增长，这种增长合理；不能承诺完全不增长。原件上传发生在来源登记之前，文件字节已经上传的审计/文件对象不在此升级删除范围。

交付与执行顺序（运维001）

这是新增需求的独立补丁。旧v4与集成ZIP原件保持不变，不在旧清单上改hash。补丁含升级后十文件Skill和自己的清单；插件/适配器/身份登记工具不改，r7和credential-binding.json不改。

1. 解压到独立目录，核外层FILES.sha256与内层Skill十文件；本包不得覆盖旧交付解压目录。读本说明和实际五函数manifest。
2. 先按既定身份方案完成两个身份函数部署，再运行本包server/scripts/deploy-dedup.mjs只读预检。使用运维既有私有KSF_CONNECTION_CONFIG，不向聊天传配置。新版更新四个现有Function代码，并新增ksfCheckDuplicates一个Function。UNKNOWN_FUNCTION_VERSION/身份冲突停，不改manifest放行。
3. 同一已授权部署任务运行node server/scripts/deploy-dedup.mjs --apply。备份、回读、/schemas不变校验由脚本执行；仅写Function代码/定义，无业务数据写入。回退校验当前仍为本版本；新建函数只有已知objectId且代码吻合才可移除，响应丢失需人工核对，不能盲删。
4. 身份部署工具不要在查重补丁之后再次覆盖ksfGetIngestContract；它仍锁旧版目标指纹，覆盖会被拒绝，不能放宽旧工具。执行顺序固定“身份升级→查重升级”。新合同同时支持identitySchema、channelIdentitySchema与deduplication.schema。
5. 目标Skill安装改用本包十文件和scripts/install-workshop-skill.mjs，hermes(uid10000)、HOME/HERMES_HOME=/opt/data；支持既有expectedWorkshop和已核验集成版本。本包安装器保留状态与凭据，运行后按既定流程备份/复制/回读FILES.sha256并核权限。不要再用旧集成ZIP把新Skill覆盖回去。必要重启仍并入同一次既定服务窗口。
6. 真实消息登记与K轮完整链路用原已核验执行包继续，不改K键，不在运维身份冒跑，不因查重额外造身份。新workshop-import会检查查重合同，服务未升级则在登记来源前停。

如原安装任务已经开始，先报告已执行步骤和实际版本，切勿一边覆盖一边让王刚跑导入。可在首次真实业务导入前完成这份补丁；已完成身份安装无需重做登记。只有任务尚未开始时才按完整合并顺序一次实施。

查重验收（王刚001任务内执行，sample）

K轮原任务不重放。在单独稳定的去重验收键下准备一份注明sample的原料资料；第一轮workshop-dedup→workshop-import保存实际sourceId/objectId，再使用同一原文/URL/结构化字段、不同requestId和externalKey重复导入。预期第二轮sourceOperation=unchanged、counts.created=0、counts.unchanged=1，sourceId/objectId相同。保存两层真实invocationId与回执。

保持业务键和记录数据一致只换requestId的测试仅证明原有幂等；本轮必须换externalKey证明新跨批查重。改规格/原文/价格的测试使用另一个明确版本键，不覆盖先前对象；原料名称相同不能单独视为重复。测试记录正常保留，不自动删除。

只读命令形状：

node /opt/data/skills/ksf-workshop-runtime/scripts/ksf-secure.mjs workshop-dedup --input /绝对路径/任务.json --request-id 本轮稳定查询键

任务JSON与workshop-import同source/records形状。复用、未命中、依赖待解析分别汇报，不把预检当完整校验或真正入库。公开页面验收及完整S1–S5要求仍适用。

本地验证与实际状态

测试覆盖跨requestId来源复用、URL/模式/owner隔离、跨业务键复用、原始上游ID跨批次、同短评不同人、数据变化保留、人工噪声判断保留、只读预检无写、扫描上限、服务未升级停、独立部署只读/回退/创建响应丢失，以及完整S1–S5回归。此文和交付不是远端安装证明；生产验收需运维与王刚实际回执。