下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/org-odeahxzi--shennong-code.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md，安装 @org-odeahxzi/shennong-code。神农云码生成与解析——农产品溯源码的签发、校验、状态管理与码谱系维护。当用户说"给这批货生成溯源码""帮我赋码""一物一码怎么给柑橘做""这个码帮我解析一下""校验位对不对""这批码要作废""包装破了要换码""混批拼装怎么办"时使用。
本技能按《溯源码规范》构造码值（版本位 + 主体识别码 + 品类码 + 国标同源校验位），校验位算法逐字采用《食用农产品追溯码编码技术规范》附录 A，可完全离线复算——拿到任何一串码都能当场判定格式与完整性，无需联网、无需查库。码分三档粒度（一品一码 / 一批一码 / 一物一码），带五态生命周期（未签发 / 已签发 / 已激活 / 已作废 / 异常锁定）与父子码谱系；已作废码不可复活（吸收态铁律，因为"作废码复活"是"一码多贴"的核心手法），混批与重包装强制换码并列全来源批次（否则召回范围无法确定）。
产出：码签发单 + 机读码册（供查询端消费）+ 标签版式说明。
阅读全文 （展开查看完整说明）
概述
定位
溯源码不是"印在包装上的二维码"。 二维码只是载体，随便什么字符串都能生成一个二维码。
一道溯源码的本质是：把物理世界的一批农产品，映射成一串可以离线验证、可以跨系统互认、可以判定真伪的数字身份。 而行业里三件事一直没做好：
- 各平台自造编码规则、无统一结构 → 换服务商数据迁移困难，同一批货在不同系统里是不同东西
- 静态码无校验、随手生成随机串 → 无法离线判别合法性，只能在线查库，库一挂全瘫
- 码只有出生没有一生 → 发出去就不管了，"作废"不可表达，"克隆"无信号
本技能反过来：码值按规范构造、能离线验、并且管到底。 它是「认养农业管家」技能族的溯源信任链 · 生成端（全局编号 #47，零底座——码册库由技能自持），是 #35 agri-trace-query 的上游供方——没有它发的码，#35 就没有可查的对象。
三条不可退让的底线：码值必可离线验（不能离线验的码不是码，只是排版）、作废不可复活（可逆的作废等于没作废）、归属必须可查（答不出"出问题找谁"的码，在纠纷中零价值）。
交互与引导（族级公共层）
遵循 references/interaction-protocol.md 的四回合骨架（T0 握手 → T1 收敛 → T2 交付 → T3 交接）：
- T0 握手：复述用户原话（≤3 行）；有歧义先确认意图——禁止直接开跑。
- T1 收敛：缺项最多问 2 个且每个都能改变结论，一律给选项；不得开放式追问、不得连环追问。
- T2 交付：默认只给首屏卡（≤12 行）：结论第一句 + 唯一行动项 + 缺口总账 + 把握度；展开本按需给。
- T3 交接：给出下一步动作 + 族内可接着问清单 + 落盘前确认门。
话术一律取 templates/交互话术包.md，口语稿须过 5 条硬规则（单句 ≤25 字 / 无符号 / 结论前置 / 数字用汉字 / 用「您」）。
本技能裁剪：适用 G1/G2/G3/G5/G7/G8；G4 不适用（赋码是操作型任务，无候选速判场景）。G1 特殊性：本技能的握手以意图判别为主——「发码」与「管码」产出物不同，判不准必须先问一句（既有纪律已明确要求）。G7：三件事不齐不发码，缺口总账要转成人话。
三条能力承诺（天花板能力）
| # | 能力 | 对标基准 | 可量化超越点 |
|---|---|---|---|
| 一 | 国标同源校验位 + 完全离线可验 | 市面上绝大多数赋码工具生成自造随机串或无校验的顺号，合法性只能在自家库里查——库挂即瘫，跨平台不互认 | 校验位算法逐字采用《食用农产品追溯码编码技术规范》附录 A（与 GB 32100 校验码同源），加权因子 W_i = MOD(3^(i-1), 31)、字符集 31 位安全集（排除 I O S V Z 五个易混淆字符）；拿到任何一串码，跑 --verify 即刻复算校验位，不联网、不查库；随机串命中校验的概率仅约 1/31，抄录错一位有极大概率被检出 |
| 二 | 五态生命周期 + 「作废不可复活」吸收态 | 竞品多是"码 = 一个标识符"，发出去就不管；作废通常只是删掉记录或改状态位，可被改回 | 状态机 ISSUED → UNBOUND → ACTIVE → VOID/LOCKED，每条迁移都有前置条件（激活须附依据、作废须附合法原因码、锁定须附异常信号 ID、解锁须附查证结论）；VOID 是吸收态——VOID→ACTIVE、VOID→UNBOUND、任意态 →ISSUED 一律硬阻断，因为"作废码复活"正是"一码多贴"的核心手法；history 只增不删 |
| 三 | 码谱系 + 混批强制换码（召回范围可确定） | 国标要求"混批出售或重新包装时生成新追溯码"，但市面上普遍漏做——因为这条不产生新的业务价值，却直接决定召回范围 | 父子码关系分 split/aggregate/repack，带父子同源约束（子码主码必须与父码一致，跨主体拼货不得用父子关系表达）与深度上限 4 级；混批强制换码并完整列出 source_batches（全部来源批次，不是"主要来源"）；混批批次号取 YYMM+M+序号——混批没有单一采收日，硬填一个日期就是伪造信息 |
砍掉测试：去掉能力一 → 退化成"批量生成随机串的工具"，与 Excel 拖拽无差别；去掉能力二 → 码发出去就失控，作废可被改回，防伪价值归零；去掉能力三 → 混批货只贴一个来源的码，一旦该批次出问题，召回范围无法确定——只能全召或全不召，前者损失巨大、后者可能放过风险产品。三条互为前提，缺一即平庸。
🔌 零底座：码册库由技能自持（V1.1.0）
上一版标称依赖平台底座 P15 数据资产目录与元数据服务——本版取消该依赖，技能独自闭环。
复盘当时的推理链，问题出在把「需要索引与关联查询」错读成「需要平台服务」。码册是本技能独占的资产：没有第二个技能要读它、没有跨技能血缘要做、权限就是"本地文件谁拿到谁能看"。为一份独占资产引入平台服务，是把简单问题放到架子上。
自闭环手段：Python 标准库 sqlite3 + 单文件 .db（零第三方依赖、零网络请求、可整体拷贝分发）。同时顺手把能力三从"写对"变成"算得出来"：
| 新增 | 它回答的问题 | 命令 |
|---|---|---|
| 召回范围反查 | 这批货出问题，要召回的到底是哪些 | --recall CODE |
| 码资产目录 | 码资产怎么构成的（主体/品类/状态/粒度切片） | --catalog |
| 谱系遍历 | 父子码链路（顺带校验同源约束与深度上限） | --lineage CODE |
| 存证审计 | 谁在什么时候改过什么 | --audit CODE |
| 主体资产 | 这个主体名下有哪些码、处于什么状态 | --subject ID9 |
接口不变地换存储：主脚本 --registry 同时接受 .json 与 .db，行为等价。JSON 仍是契约，.db 是派生视图——删了 --build-db 重建即可，权威源永远是 JSON。
详细口径（数据模型 / 召回范围的两类边 / 三条纪律 / 已知限制）见
references/self-hosted-catalog.md。
什么时候用（触发与边界）
用：给农产品批次签发溯源码 / 解析任意码值 / 离线校验校验位 / 变更码的生命周期状态 / 记录父子码谱系 / 处理混批与重包装的换码。
不用：
- 查询码背后的溯源档案、检出异常信号 →
agri-trace-query（#35） - 判定扫码是否为假货 → 本技能只判码值合法性；物理真伪靠标签工艺与流程（见
references/carrier-and-label-guide.md§1） - 向国家追溯平台申报或直连 → 须另行核验平台技术指南（规范 §14.2 仅作映射预留）
执行步骤
Step 0 · 先判定这是"发码"还是"管码"
| 用户意图 | 走哪条路 | 对应命令 |
|---|---|---|
| 发新码 | 赋码流程 | --issue |
| 看这串码合不合法 / 是什么结构 | 解析与校验 | --verify / --parse |
| 码的状态要变（激活/作废/锁定/解锁） | 状态机 | --state |
| 父子码关系要记录 | 谱系 | --lineage |
| 要看整体情况 | 码册报告 | --registry --report |
| 出了问题要召回 | 召回范围反查 | registry_catalog.py --recall <码> --db <库> |
| 要看码资产构成 / 谱系 / 变更留痕 | 自持码册库 | registry_catalog.py --catalog/--lineage/--audit |
判不准就问一句"你是要给这批货发码，还是要管已经发出去的码？"——不要在意图不明时直接开工，发码与管码的产出物不同。
Step 1 · 赋码前先确认三件事（不齐不发码）
- 粒度：一品一码 / 一批一码 / 一物一码 → 按风险承压面选（一批一起召回 → 批次级够；单件出问题 → 必须单品级）。不得为"看起来高级"而全量上物码，维护成本与单价不匹配时会不可持续。
- 主体信息：全称 + 9 位主体识别码 + 可达联系方式 + 产地（到县级 + 基地名）。主体识别码取自统一社会信用代码第 9–17 位；无该代码的个体农户按规范 §4.5 分配内部主体号（首位固定 9，终身不变，须书面留档）。
- 批次：采收日（普通批次取
YYMMDD）；同日多批次改用流水号且同一主体内不得重复；混批则走 Step 4 的专用规则。
⚠️ 主体名称不得为"某某""待定"等占位——脚本会告警并不给通过码（退出码 2）。理由：答不出"找谁"的码在纠纷中零价值。
Step 2 · 签发码值
# 一品一码（品牌级稳定标识，一次赋码长期用）
python scripts/code_forge.py --issue --subject 123123123 --category 001 --grain main
# 一批一码（同批同源风险共担）
python scripts/code_forge.py --issue --subject 123123123 --category 001 --grain batch
--date 2026-10-15 --subject-name 随州香稻种植专业合作社 --out registry.json
# 一物一码（高价值单品，批量 50 件）
python scripts/code_forge.py --issue --subject 123123123 --category 004 --grain unit
--date 2026-10-15 --count 50 --subject-name 寿光蔬菜种植合作社 --out registry.json品类码是受控字典（规范 §4.3，与 #28 工序库作物集一致）：001 水稻 / 002 小麦 / 003 玉米 / 004 番茄 / 005 马铃薯 / 006 大豆 / 007 柑橘 / 008 茶叶 / 009 其他种植业 / 010 生猪 / 011 家禽 / 012 水产 / 013 食用菌 / 014 蜂产品 / 999 其他。不在表内一律用 999，不得自造（--crops 可列出全表）。
Step 3 · 校验与解析（离线，随时可做）
python scripts/code_forge.py --verify 0123123123001Y # 离线复算校验位
python scripts/code_forge.py --parse 0123123123001Y-B261015-S00137 # 解析结构输出必须同时给出边界提示（脚本已固定携带）：校验通过只证明码值合法，不证明实物真实。是否正品、是否已作废，必须查码册状态。
贴标前卡点：全部码
--verify必须通过。算错一位就印出去 = 整批标签报废。
Step 4 · 混批与重包装（最容易漏做，必须显式处理）
触发换码的四类动作：混批拼装（必须换码）、初加工后分装（必须换码）、拆箱分装（发子码，不换主码）、换箱且批次未变（可用原码 + repack 谱系）。
python scripts/code_forge.py --issue --subject 123123123 --category 001 --grain batch
--date 2026-10-20 --subject-name 随州香稻种植专业合作社 --mixed
--source-batch 0123123123001Y-B261015
--source-batch 0123123123001Y-B261013 --out registry.json- 混批批次号 =
YYMM + M + 序号（如2610M1）——混批无单一采收日，不填YYMMDD source_batches必须列出全部来源批次；缺失即告警（退出码 2）- 来源不足 2 个 → 告警："单批次不构成混批，无需换码"
为什么这条不能省：一旦任一来源批次出质量问题，召回范围无法确定。这才是重包装规则存在的真正原因——不是为了流程好看。
Step 5 · 生命周期管理
# 激活（须附依据）——建议绑定在出库环节：货真在手上，扫码即绑定，成本最低证据最强
python scripts/code_forge.py --state <码> --to ACTIVE --reason "2026-10-15 包装出库扫码绑定"
--operator 包装组 --registry registry.json
# 作废（须用合法原因码：quality_event / repack_recycle / subject_request / expiry）
python scripts/code_forge.py --state <码> --to VOID --reason quality_event --registry registry.json
# 异常锁定（须附异常信号 ID：A1-A7，见规范 §12）
python scripts/code_forge.py --state <码> --to LOCKED --reason A2 --registry registry.json
# 解锁（须附查证结论，无依据一律拒绝）
python scripts/code_forge.py --state <码> --to ACTIVE --reason "已核查：一家三人轮流扫码，非克隆"
--registry registry.json被阻断时的正确反应：不要想办法绕过。特别是 VOID → ACTIVE 被拒时，用户真实需求通常是"包装破了想复用"，正确做法是发新码 + 记录 repack 谱系（见 Step 6），把情况解释清楚后重做。
Step 6 · 记录谱系
python scripts/code_forge.py --lineage --parent 0123123123001Y-B261015
--children 0123123123001Y-B261015-S00001 0123123123001Y-B261015-S00002
--relation split --operator 包装组父子同源约束：子码主码必须与父码一致。跨主体拼货（如合作社把 5 户社员的柑橘拼一箱）不得用父子关系表达——各持各码，在物流层（订单号/运单号）做关联。
Step 7 · 交付与留档
产出三件，缺一不可：
- 码签发单（按
templates/code-issue-sheet.md填充）——含贴标前三项卡点核查 - 机读码册（
--out registry.json，schemashennong-code-registry/1.0.0）——交给 #35 消费 - 标签版式说明（引用
references/carrier-and-label-guide.md）——含载体选型与六项硬约束
留档还须包含：未使用标签的去向（销毁记录）、承印方信息、内部主体号分配簿（如本次有分配）。
未使用标签的去向直接关系到"未激活码是否会被滥用"——这不是可选项。
输出规范
- 全部产出附离线自验方式（
--verify命令 + 期望结果），让使用方能独立复核 - 时间戳一律含时区（如
2026-10-15T09:00:00+08:00） - 校验通过时必须同时给边界提示（码值合法 ≠ 实物真实）
- 告警不得吞掉：有告警就退出码 2 并在产出物中逐条列出与处理方式
- 中文字段名中英分列（平台字段按官方要求）
异常兜底（20 条）
| 情况 | 处置 |
|---|---|
| 主体名称缺失或为占位 | 告警（退出码 2），提示补全后才能贴标；不代填 |
| 主体识别码长度不是 9 位 | 阻断并提示正确来源（统一社会信用代码第 9–17 位） |
| 品类码不在受控字典 | 阻断，提示改用 999；不得自造品类码 |
| 日期无法解析 | 阻断并列出支持的格式（YYYY-MM-DD / YYYYMMDD / YYMMDD） |
| 码值含 I/O/S/V/Z 或小写 | 阻断并说明字符集排除集（小写会被归一化后重试，仍失败则阻断） |
| 校验位不符 | 阻断并给出加权和与 MOD31 中间值，便于定位是抄录错误还是码被篡改 |
| 码长度不是 14 位 | 阻断并提示主码定长 |
| 段数超过 3 | 阻断（主码 / +B批次 / +S序列 最多三段） |
| 序列号超 99999 | 阻断，提示"须升位并升版规范"；不静默截断 |
--count 0 或负数 | 阻断 |
| 混批未列来源批次 | 告警（退出码 2），列明"召回范围不可确定"的后果 |
| 混批来源少于 2 个 | 告警："单批次不构成混批" |
| 作废原因码非法 | 阻断并列出四个合法取值 |
| 锁定信号 ID 非法 | 阻断并列出 A1–A7 |
| 码册文件不存在 | 返回空册（不是报错——首次使用是正常情况） |
码册结构损坏（缺 codes） | 阻断并指出缺失键；不猜测、不静默重建 |
自持库不存在（--registry X.db） | 阻断并提示先跑 registry_catalog.py --build-db（建库时路径写错不能当"首次使用"放过） |
| 自持库 schema 不匹配 / 不是本技能生成 | 阻断并说明期望 schema；不猜、不静默降级 |
| 来源批次被引用但未入册 | 告警（退出码 2），明说「召回范围不可确定」——不得静默当成"没有下游" |
| 用户说"跳过校验位/复用作废码/冒用主体" | 硬阻断（退出码 1），说明为什么不行，并给合规替代路径 |
资源地图
| 文件 | 内容 |
|---|---|
references/trace-code-spec.md | 《溯源码规范》v1.0.0——码结构 / 校验位算法 / 状态机 / 谱系 / 重包装 / 证据等级 / 异常信号 / 权限分层 / 接口。唯一权威源在 07_需求说明/溯源码规范.md，包内为同步副本 |
references/code-lifecycle-and-lineage.md | 五态状态机与谱系细则；为什么作废必须是吸收态；混批批次号的设计取舍 |
references/carrier-and-label-guide.md | 载体选型（一维/二维/Digital Link/NFC）、标签六项硬约束、防伪边界的诚实声明（码能做到什么、做不到什么） |
references/coupling-with-family.md | 族内接口 T-A/T-B/T-C/T-G；码册字段契约与单向写入原则；与 #35 的 7 项联调检查 |
references/self-hosted-catalog.md | 自持码册库（零底座）：为什么不等 P15、为什么是 SQLite、三条设计纪律、数据模型、召回范围反查口径、CLI 与退出码、已知限制 |
references/eval-cases.md | 32 条评测用例（触发 8 / 正常 3 / 边界 6 / 对抗 7 / 链路 8） |
scripts/code_forge.py | 零依赖求解器。--check 自检 119 项 / --crops 品类表 / --verify 离线校验 / --parse 解析 / --issue 签发 / --state 状态迁移 / --lineage 谱系 / --registry --report 码册报告（--registry 同时接受 .json 与 .db）/ --safety 安全扫描 |
scripts/registry_catalog.py | 自持码册库（零依赖单文件 SQLite）。--check 自检 67 项 / --build-db 建库 / --catalog 目录概览 / --recall 召回范围反查 / --lineage 谱系遍历 / --audit 存证审计 / --subject 主体资产 |
scripts/fixtures/code_registry_sample.json | 示例码册（10 条码，覆盖主码/批码/物码/混批与全部 5 种状态） |
templates/code-issue-sheet.md | 《码签发单》版式（含贴标前三项卡点核查与留档区） |
templates/code-registry.json | 机读码册版式 + 完整字段字典 |
安全与合规边界
硬阻断（退出码 1，不因任何理由放行）：冒用他人主体发码 / 复用已作废码 / 为未检测产品生成合格记录 / 生成无归属信息的码 / 批量造假码 / 篡改码册历史 / 绕过校验位构造。
权限与隐私：码册不含个人敏感信息（农户只记工号/代号，不记姓名与证件号）；--issue 不联网、不写外部系统，只落本地指定路径。
不做：不查证码（#35 职责）、不定证据等级（档案层职责）、不检异常信号（依赖核验行为数据）、不直连国家追溯平台、不做物理防伪、不代办 GTIN 申请。
时效声明：引用的标准（食用农产品追溯码编码技术规范 / GB 32100 / SB/T 11268-2026 / GS1 Sunrise 2027 / 商品条码管理办法）以 2026-09 公开信息为准，标准可能修订，接入前须复核现行有效版本。
快速开始
python scripts/code_forge.py --check # 自检 119 项（零依赖）
python scripts/code_forge.py --safety "用户原话" # 安全语义扫描
python scripts/code_forge.py --crops # 品类码表
python scripts/code_forge.py --verify 0123123123001Y # 离线校验
# 自持码册库（零底座 · 单文件 SQLite）
python scripts/registry_catalog.py --check # 自检 67 项
python scripts/registry_catalog.py --build-db
--registry scripts/fixtures/code_registry_sample.json --db /tmp/catalog.db
python scripts/registry_catalog.py --catalog --db /tmp/catalog.db
python scripts/registry_catalog.py --recall 0123123123001Y-B2610M1 --db /tmp/catalog.db退出码语义：0 通过 ｜ 1 阻断（不得继续）｜ 2 告警（需人工确认）
