#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
zhiku — 随身智库 · AI 组件市场 CLI（零依赖，python3 stdlib）

    zhiku "我要写一篇公众号长文"      # 中文任务匹配（内置中→英领域词映射）
    zhiku -t mcps "database"          # 限定类型 (skills/agents/commands/mcps/settings/hooks)
    zhiku -n 20 "video"               # 取 top 20
    zhiku --deep "elevenlabs"         # 附深度索引（触发场景/依赖/需配置 env/风险信号）
    zhiku --json "feishu"             # JSON 输出（给脚本/Agent 消费; 配合 --deep 含 deep 子对象）
    zhiku --refresh "..."             # 强制刷新本地缓存
    zhiku --max "desktop build"       # MAX 模式: 置信度/三法印/下一步
    zhiku operate --recipe task.json --dry-run
    zhiku operate --executor ego-browser --recipe task.json --apply
    zhiku skill discover             # 发现本地/任务/GitHub Skill 变化
    zhiku skill inbox                # 最多显示 5 个治理决策
    zhiku skill capture ...          # 显式沉淀当前成功工作
    zhiku route human-review         # 生成30个真实历史任务的脱敏人工评审板
    zhiku route human-review-record  # 记录一项脱敏人工路由决策
    zhiku route human-review-import  # 严格导入驾驶舱导出的最多10项决策
    zhiku route shadow-readiness     # 只读检查14日影子计时前置条件
    zhiku instrumentation audit      # 只读核验四客户端本地回执链
    zhiku instrumentation plan       # 生成需授权、可回滚的启用计划
    zhiku install-suite yuanli-health --host codex --version 0.1.0
    zhiku install-suite yuanli-health --host codex --version 0.1.0 --dry-run
    zhiku install-suite yuanli-health --host codex --version 0.1.0 --verify-only
    zhiku install-suite yuanli-health --host codex --rollback-version <version>
    zhiku wechat preflight           # 私有本机微信 Agent 通道预检
    zhiku wechat status              # 私有控制面状态（公开包仅安全委派）
    zhiku use <skill>                # 安装到 Codex + Claude
    zhiku forge status               # 兼容别名（已弃用）
    zhiku --base http://127.0.0.1:8902/zhiku-api "..."   # 自定义 API base（调试）

数据源: https://os-zk.84000.art/zhiku-api/catalog.json + deep/*.json (匿名静态 JSON·canonical)
缓存:   ~/.cache/zhiku/ (TTL 24h)
安装:   curl -fsSL https://os-zk.84000.art/zhiku-skill/zhiku -o /usr/local/bin/zhiku && chmod +x /usr/local/bin/zhiku

深度索引(deep-v1)是从组件正文启发式蒸馏的结构化摘要(无原文): MCP 命中即使不带 --deep
也会自动附「需 env:」行——装前就知道要不要 API key。私有组件(★)无公开深度数据。
"""
import datetime as dt
import base64, hashlib, json, math, os, re, subprocess, sys, time, urllib.error, urllib.parse, urllib.request, uuid, zlib
from pathlib import Path


# Governed, hash-bound copy of systems/zhiku/release/install_public_suite.py.
# Public distributions contain this CLI, so install-suite remains available
# without a private repository checkout. The payload is static release code;
# no manifest or downloaded archive content is ever compiled or executed.
_EMBEDDED_INSTALLER_SHA256 = "36c43e0baf45f07906727f8b782f342b875e7826a6b7c60def15175af3ca1e72"
_EMBEDDED_INSTALLER_B85 = (
    'c-p-^{d3#Mt-t%P;PG|dNf$}B(_DH_Q(woII6b$?Ib%C*uZ|vvmMDuCid0F;iR1cze*pG_*bhpSlh>QMSR%1lEEbCeuvqB7zS&<_'
    '<^FY=?<e_fu)3=kMgIG}FbrSCX*Qf@MU~8gs-9)(b&%#&9cNim2J@l}R_p65trqb5pNsUvT6~`d)rU08f@+=CNi_mIdwcV;SO!rv'
    'U)Sq0iJ~A~u8Oh_;yf?vxK4|_+S^ml%9~YOR*Cw4^Eq9q&x^QP02S(MTBuLIRYk5o7nS-{Y9!TSU8kA;27Ri}bzIKVOas=*a>c)|'
    '%M3akC1qKZ*0VDC*E*?cF}77)FNi+^<Sl$11aD!mZ;LAZgkJ?*eYZ;U8wGZp-wlEnz|Z&^y4>4)dGhM`-RsNf`0Z)*?)-Id6!i82'
    '_%B@4^{N{0?-$kZ^M}z7&kha_MsZp1e@3<s<5jvZSU(g@-w#DI@tVIH-abX}5i%^?>+iie{zvqei?d&%pMJeOxquFz2HypT2Tz~L'
    'KLl`m{^IA;zny59-}``GoxW}$e((TXo?RZl))0r!Js>YnUYxyodwz0paq_aE=-CF6-kiMo>ExUc9z?*Ey^G^lC($p*Z%(4~6L?xC'
    'qiL~R!Ho9G@PDu3;pc<l|4iiH;pF~c@cj1=zYF_&e*-M1zz1I|Z1Uv&$o$*;)A(xmWP)FghyMhGqv7O9|4)bu2Jz<fvJF){oKNnb'
    '9Z;_qKOaB+{`p48=g$c8#qrzYpH5$&UjDjiU_=!VqQCdQ!^Y<)e?GmqJa?Otm_YkqUk{;!;T4R8nhj};_dh%gdw=={*n050zIcMf'
    'fY@A|y*qz#5?#DIz4S5~@X<Sk5jcG~_(6>M&!?9^zx%0`6ea36X}wrqzsL9cy(__Dz!VXi-6urW-rh8et137ZTIvEN{sfn9?|hxt'
    '=~8^@kEyQ}KthXIG7q9M`7N2&(QLhfl@ixU^dY&cdaF1st8oA-uD+__RdQ9;<p5XhWYQ0YKL)dOS~t%G+A^uuSv|Ji!C3Df=soI9'
    'z&;3W<7}OPLJdSW^b-F|=lC99NL2a_p^wul3I2v{#mMGiLp82yBz=4j|2zP%bt}Sj1y7L@>RA#C3R!hzF(WVXd71+UdjvlQwOP`r'
    'e<|`rj@2bbw-UtU>*aM)j_(NtQY8Awig+dfuJ1r!sUGOdAOLlkWKDlQE(4RYBp2=a!H<Ed#~PLi3SD`ahtzvr6j25{PBOlyP8HAU'
    '@~*)_+tCd8hD}CDdet-Lgs2$Jl4&tZdf~dB4}S;;K?o!R<zatd02kN9U7GZ0Q4}AJ{L*K(A{wG;fdk3wBWI2pXfc4~(==JtLGN9j'
    'B2_f#ffxX?>1D#6HuKjH;tHE~=3kn_*wb0Vy?}N(K%r&{HuxZ|$ZW``Nl)-{Ky%vf+>PWJ?zm~0%&f_hLM%`#A#NlLxAPwE&tthQ'
    'cMvaQ{>4H)qCFmVeZVV(*5LHn1yQ^M1G8cpXE3H|QO=@u9^Znsg?2z2GvzS7OGge$Ew8AG=SdWo(?xolL`ZipkC$u-Gi^2+jhZ!u'
    'vxSfWj0FFVfb6oaK7uaph5JAeJP+T$4^cZQxbXd_g9H6!`^ZC17YrO}l{1M?fYFBCM3naxfiwqc6~)(8k*z^D5lL}=hmutz5xo%C'
    '-iZDgArH|`mG7uEeyRFjM5mTGh0fr6nPgzoD#ka;(~&&yEZC~2u7D$+2^Ff3i=Z=v&cY~!$Gdikg02{><*4~WN&*#IhU72fJe`B('
    'ER?AFX788-;Xp{v-6mxPZUTMV+q5en&D;hY&DUABjO*#5NBBry5U4Tu7>Mkqi*!iyKT2l_m=^V&(uJX#lNG2e+BWVrvap&il4Tr@'
    'rD+}s(>x-|qT8ntnC9VtfzxxqIS%IG=MQ7Sk$d{{zyWcM01&-kkL7USjr_#kP2+qfCI#IgY#mB!05+Yc$;_an1B~<yBdN*K47h?#'
    'v}WVL+I0ko%W}=BE|VLuxXQaIo-Nb5_JPcjRaV?Bf%EP=Nroh#p_BtQrWm}+U_bf@yDCf;=m<4&BVgqcl)Pb>DPbMmBz2FP_JePZ'
    'WNV+H=2QF%39N>BGQFE-Nwbd<PPMTqaW;)@F41+_Ge`=nVqH#?NDGe8*kQkmL~FV%B$i~`YzP-?_#TzQ!iK%NO3K>=yG|>j|5cn-'
    'v{RVPiggXPJs34v4DD?AUFanY(RH!TXK{JwlG|8oCIz=(m`E|DX_UepYH)|<846~4y~dD5M81Y>nS82~GKc+~ujmbk04B++M7BO&'
    '#h@65Pe%tEn!vV_#9#zo$5pDjt?u%Ak<`%Pzt%A3Ihv11T9IdW0@Y3vZw#+tqtMd{TJpFVnPkc5ZNed5gXIe1A&3UgU#ehc7fLJx'
    'a<)il(Y%*WWwTvI!n?HuLP~c!Q?4D18NH&biQK-V_Gtq^tx*;qQCCR%3>9Gw3?QYoi-W3wCGdm>bZ@8&wQ{HNN@=c?Ygbb<wn05~'
    '(?JfOOb!`bLNC4eXlNI+ckX3s*6~&?RQES<P4_+!#*!2mBM8FvpaSpjI)2}XJlyciYcp1pMiy&f6f*FgY4r1N)0|bKc(qFM8DorZ'
    'k~A2nj=R?lLXuc|1T)GW>!r%k8o<Vj{v+0~Hn6mRtW=Vq!_i3MvAKsjvenrIb!5fldzq}jQ>lyc4(JdNO6t{%XkBKl)HGnG80jdP'
    'Aw&vxC%PFW&elk)N`)&e%Yu&vc51N2zQ~*qC@d0u9+TZSY>pq|8}U+80PdacfCD^!hzd(xCduOl$}#xq(DB|5bW95{Dq;7k7BRH>'
    'GK%ov#HFadTP5DEF=V2)Y;BgMd98%=F!-Yq_A6hb3BLD)=^sOSgVr5@x!#sVjiLmmlw<qrL7)q;+u9+l0+BSXmT3j+_eN<UX_q-_'
    'NIu`N^69;89f+rvg~0Yuu@DV+N!W#+H$|3R0~_VDhusD)u$nyA9+QZ)I8-^*^c~x%Z7Irz+_Q27zN23yy(n8#OK#AyL(^BorPhg('
    '0FE6e9@|s3DwEr^SXYtqz6YLn-bveSf@JsBC|6}#l&Wj8!UULH;5Kc%k)Wl$jXky6y)yfRm4+t-#Fn0cS-pAWF!7`)OKP^FoQ`qk'
    'u!|thXUy%hgV4O0*mk+w)fyc#+Br>}4#cSa_<gH@x9aciytN2~496)j6{)<=itDIIXU5SB1=i@(n75V3?jzWV4tv)jHVwky2@b5+'
    'oWk@+NiI%6;%b_vpmU!D*WvpEgcJ~?S$czUKOLr~jS`7y!t*u>umhH9VxGduV<PKMQDhV5rWtY6=_1W$Wr7O=@$^I(8C>>RTK4*1'
    '6v#L1hG?DR0RaWOtavJ_P9g(Ur=q7pZ;(skozDv(mmo(O#@~946m6mPYtT#U21ERc209N=Q|ugaaW#J(?i(irLJHUefiSJ2>Ta2('
    '`G;PAN7_*;?#!6HG6{fDql@VD;^pai4|zC3PXcJRx{z|EJRmw{Ac5V7QC)|aVQ~PT8WAO$!R$l}qR(a`<DG)@x2aQSl1Vm&ou~Qi'
    'oG|S$>7AHI7S-m7r+^R84@6yuhX)6L`2PD4xy#2E{C99r93CD53!py&d;aWMxRuKT!aQIqNOAy}OQAo5yF3!OgJ_^>8^MyhPG{gg'
    'N)fp(W_L8AP_M|UDC>w*RiHl)k_n0-nUY%va*I&OtS3h^!1MW|EM8vEVvKT(@t>=M37hO$TCKA9E|LpK_i{BJ9!`jnya!^ShS5lf'
    '+$Tq3B2Y9*=^CgT4GVN{P}wNOhRR0V8#OioI0~DKPz4rHQ8TUGoXFs#)^rGZ+2lh2GZ2rV4b(2FUXYgFK^0>=kL9X4KF}X&I&n0}'
    '&I;$cs74>->;nxBUcshXd_=0MBO#n@Q(2d#Sh#dfsj)ZWJD10(h?n&^wvP7c&{JXC4-6r&&OKWcW+$#-LuXCcWNKb~4I<S%suy$='
    '{}|FYEb1n%C1ME8LA{JA)CJ9De-u{{20}hrYSkBlP~TvKGlC1wj-w=4b>5P-(`k^@0}pbU!=nry)zL%_vptJPpSe;trjY>A9IRUT'
    'JjVW1C!cB~>j5A1NMnHadn8Q&Gu=e)O@n~vopjGC32EUH!OimZ9!n!FMsmV%IDDUn{YUm8O-&426XtmeyH)r;7gz_uGwpI9&>w??'
    'FX>098ZcBf4p=S82-JEC?$#K(JM3Q_PDW^2t$OA%MMxAfr1I+77^s<uhWLUT3>d*Btc*vLpCO5uXl@cU;HzDcSWI>tnF`J>(~7*9'
    'knI(ivQ({?mFr_Py8)i9v<u&s%qlK>T;jS5oCvNVkzE81*ezMvQPzCuTed}c$i%V)`CJ>5JZ9&az;cmC$-=~8k7tkegP=Eh(hmoO'
    '&^gnfHXUuO*5OzRm~f76%3{6hJ#8SiXj+EduWY%ZJvs_P5ly{#_vRwRoo1U7?lP<<2M=6v*s#~&>)$4BCMDOye6)xCR*kF`veNh3'
    'U|@#Spfw++HR*+HG0YKijkCW0nB+<wkxcku4>hBx&8Eoi4ptb8+%oN;k5FYYpNJ%0{Ppzp>(O$CtD8+Ld_(7;jHh+AFA~@VaYG$z'
    'rA&4+%&1X|u(jY&*C?X4Ate$q3>ots->b(eN5kG{sjsVMJd*)qJEiGN)aez<8>vK?8r7^B`owhvVQ9>*2f$u~qd!_CpOm@on?&n4'
    'VV8+Co7$6!Gzjt2`ks+xBtzj_THDy5qChXn+%UN3L)VT09X0|k8jy=*Hw8@d2pIjssI-vo1vyQ=AGG!60$EcbW>D(|WA>cMF?#7L'
    'nQSa{o}<QrLMeKEFi%ExrX7a8thCX_st}UbX_=X$;^|>LV@S1;QEeGwR{36$n@Dn{lSn28^%}6Tl)5BM2!GuFZqhBIVoXLc%d0Sq'
    'Fq!?~42c<5jj%d1;Y|nhGJSY^7`8E)h_n@Y^KN2f`hh4FH!Tf)Eo3^Ot+>3Ig$<B;#^H?gpK);boV`;yP#lMPHt`&AiNq%kZN72)'
    'MQBr)c>13{Kx}5mP&4McF3QHY3Jl9w#rtrjMXNHIr=LI~*y7V-nCe?x`lTT|YRQiqH_%mP<h82}P$@B=ImO)si@rXcrD(v$1eQB5'
    'W2k1GpX7OXZ{dEp$Cdi6Z>4@ad61XXI<LG3Zp~;CSk4)4C+2gP;w~pHN~Yyl+V+$dTE}fUR&6TFXJPwzsnOY-Q;?o*K##j+=Ndpy'
    '3TDiDFs*V0A@gs9RudVDizLqK#gL4np@Kuj*7;P|<~Ct(GG^OoGOy@Z6ngX68mlRi!Blo=XCi1zY2#;*&5fML4%Kn4t<mm@`$Qt&'
    'mQE_r4$~(VBI*T}M`J#kz#c1+l3ymfo_bl*FTEdrCeG21O)>^9m}RSuJDR;7Ow4r|GcQMN1Hv-{|C;y>imox|<z)*YM(XB;IG9vN'
    'j_p?$X7Du4DP2VPb$i=xvKc+78*RqL+Z}GKWGQA^;dwcDpjE;$W*A{D;pA52tf^|}1Y<e+<p&JggI54ESshXCJ#ZS9O;miKubL>l'
    'zGD!k4`z2H3zlA#ELWJ%&0{wPZ~0bt9lrl`IDh}?hwE^c3qgvpW|p)Q!@@4;`ugb4@XsrZeWUah*S{U5#pov_=Jd>(cySDM6qY~{'
    'MzNYXG?fU3#MB#%%j++sy?ZT}sh<RgW`qy~k7H7D=QiyaNihYGqh`uk0%5FGT)rO_E4eZ)-WarL){Mi=*Pg7IGy>E#9Y4i0H6w%I'
    '<m{D<Su1KT<5E76;p`m(*opxy!NexiFYa|wK10vE@8(8nuFMq3NnhS!6V6hS;I*j4xT1{L$tKdr?wdW6u|UE9;NK!w=BU}ODln+g'
    '9x~D`7++5Fc`>l>tr=Mt1#l#)($9$Yz+DrKPbWEr`>A}`b7WKJ|Npo-n{Wr2G_NZtTTMLmru1*Qh9}@h%_T+SJPey*3?bpE9-S$c'
    '_CVW_5Mmw0vssTx1HY>zC`&6));k@#sqWj9yswXJ$1_RQ$09Cg+d4rN-qStN#t`T^gC}5&_4<$Lyu+ztGe(l>KL!V^YkDL^v#EaZ'
    '2s(sh;u^DhXR8VG0GeKH8X2IVhZWm+G(m*a<p(ZIA#uTv;90?@BAzhKCVWPr+~~p8;n)v2>0>0{c;?beONpy5l}YG=x~h(jFp-3V'
    'i33f^I~Mpi4ZI(Hhx@`DVH7W~)0=g%t}Iqs9-YB0FR#XvzK=DOD50VOUW(O8kFkXOpgRrFlV;&dZc6iY;=EKljZO^`)D84d`o?bH'
    'pMRBKptr5PM~$ON=(eeoapvvYtGSU3jI$^|byn7Z)#KiyCuQrV!TX`@Lv!5JJy;e4Lk8S3|E)-K+V;L{Y2-_A6PS#I42IL2<JOd<'
    '*geh7xVE2E;GwssxbYpVWl>1tJ32F4MPH&5h<3#avX{h5W;;p8mC|a&Kpbr?+q5dot!#9%1^4{Pi=v~({b2Q=47bCI(P7>n>Ri61'
    '$}461^;g(p#o-Siw__E0@n-Q2ns`MuI*a~(e)h}jU%@`6Z!gYIjxW`hlYhK;ZI5LUS8-jJy`mZf;aT*{*{ieHuh0G-dc;X|^KaRY'
    'g517_V8KkwbX5aus4aO+LYM{u=^!{Lo*x{za!76{G?~w+QG*GH{V3hcVqLG+wSP+x??xX>ECr<I#DRnkrVDV;G*Jh|AHM&dtuQxb'
    '6zF~S?CYkuYRgVWbmlS4yW@q;LG@%A<FZ;$RO_y11hF=p+A}5A#DY}%3;Z9iGoT;=S(DM!b(yI`AZTEX@k*7Q?{3V#tT6#oZq}R|'
    'or}MSaS$wE$$`sqbRWK}l5%)_Bg!Jk>Tlv?N!RV$KMWuGW{ASV4PQx6<acoQ(q#fdaP;(mWCh&uRgv3yxvEHxdMgwGjk8(*PMR1m'
    'uQz&k{(4t;J5TD5MfpK;*+1KMsVKqw4uPfOV@~06T_h^BC1aiFn+zoNWD)fi1%?D^o~Kx!>1K^Jizo~zU2d9m{H{ZQ*oNZen8Wlb'
    '>_8s2pnzAkUacrUxe0nT-MWfjO%yEHB)?5d*wrbd{m-9I|N1U^arW}$AJNZeZ%)L8LmP^}=jRKmJDCeB?|USlR^SM%K`OyzOXsq0'
    'TKot$S`<sH;IkiuBQb7yQLCVAc#YM-Giplz$h%9$H3=THq6Z%rAO#}r6km;KL#=wkCutrVd8+tIAVTw>-iuwCmEw{8@VCu9BpYLg'
    '36vt!=4GoCA{>@kn9Xch8QDYDMVgk>&aJt!d);iYZDZSDf;Gw0dg4%U#nZ3MN?rm=A7om-W<yVt<BTB2G1o@w9!sH~+*KA&RaP9E'
    'QV|7I-<*>LYo5a}JWs?u8}N_Bg`;cGl1Y+-46G}xa>G*5X$Ju1E)(6cHmNj6sc>t<J#moST%PB9pS*@E8XE89GsdM&LM+5r&KbAI'
    '&R?QEw&ypuUY?$xytq6&|CQTYrk$lh_PSea8!R<rEy)wP`HUH67DEVCzx}EgKf*BZxSVv5wOWjTLyA<-Yt~5`>F$dcfOp;wRh3gT'
    'iGc1S&50I#RA7c6%>ldMmT7LAYux4}i_OHxJaS)4-AdE@W%vK$x>%-Dy?$LIMCU_;!`<UW%{m$iBJdzf3S0lGTQ*|Lbj%QrSe{TR'
    'x1O57&PylrRR|x6G;s`o)xH?a$ZJZPZ8k4#@wDFolKSpjdxRheC{Zf7NpRSVO~N}{s-j5trvcSuP2;@CQ!LPkJ*fnCPe!hLTee44'
    'HfQVQN*8BL@(Sx-(=97;jc6e5dtsqZ>G!8Op7tL-#Y<R}UT)pB)EkAAH=>K*>S(92*&S5H!X1JS++W1%*hPsow&cY&RW2KlRrt9l'
    ';&VsyaCA?7A>0ENV}!nrSnpC86+UG*njN&Ascvy*MI>VE37tqM);qg>U#w*`&(_t#x-f*@S9kfer(p2PRMBGy8fRFI$MMdYdS*b)'
    '{wKB33H`y%o?VTQ;G=a;Hi!&gx-lbh{Hg7WX#$+;wI?m`A{Xvkt*kawKDN_7>~e=nb<9-7!$YUq;pVhMBm&bxP_^xzjA#_1@uW}U'
    'NvnK0X)mzhNkGJg7Sv?Wn*GB0Y-iqdNrv&axAVKVCByi!@Kk@EPN`CQo57nYG)>-&E^ABDCIy4OY_9OB<*PkaMrZ3$eUHkUOFK|<'
    'G?3CVXyjvHi@=5|D%PwGTIXXkpIMor(8@h^%E1tmoN_Sq)J#?s!|!047$t_ygBn&LM06obA{uo;Sk|%urHAAxv1kAqser9IfEULw'
    'o6}5+#5`?i_yB392@XGPsLZi@(T}!rAMJH)_y7!X(-mzVh089#@<qt}#jb2rZRM)GsM_jPaimmn%G<iF<kW__)S5^vna&kcHmnM}'
    '?zgXManr3Rw;MPTvhBi^ziJfQO^jfvGlD_z*W^xqx&(%PK^gZJUN`|%XL(;)qCMfsr0SVxxw`u#Hk8lYmtG9!j@h2Yy0NjnU3R%L'
    'wGp9F{%p%7y00Os`iddZ(O7x$ERw!V%bo9TrW|2Km(o*6f1v#^la@9kKyPhw!C?Q|ogq8qPQgkyPM#tu;#&-eR`R)RBW@A5o#7}i'
    'P*11c+9uwLXI+f~uQ6cWA2SRv>O!uCMmvf+XkF9C4Pmivh#7UI)d2=0Ko_vj<5jhww2oQw=?f%CmyZXRPetH)09v>Tj)x#@0!2kd'
    '9)dRD@H)@^gD{}fF-D7gY79OT1q~~C9E7FYnCYlHdf;na+(K_NXgnluGC&$!y0iYSJD533o=PX$%n{OnvP&IbHJwhpmm1AjVJG8h'
    'X9LR57(prL1cQ~PFaW42lN=Bw2WiEyIos5OoJZBZ?;p)uaW@?sTs6RxJ_R)7GPU0A(7U3zZx6TYal%FcuoQT^Ql<eYS|*lyZWRix'
    'Dz%G^{E%O4Cb(=u;CXm2;U9+g3g5R}w|+Z$2)`~@Jg2tm2McK2J$ac~D>?e!glM_f#GbH-s}Z@CS=9pQJMkx8rIE@3@PV;hfwBHs'
    'xGSMq!4#gzT6Ysl%5u^R1ddsGho$((R1XgTMYOTqr`{9{jbzmy9=aCdG2r7C{DpyGW|A19@90<@FpFO?kUwxIoCNDv?`+T0zOrUz'
    'R1B=&e!|MYhQY2J-p5$;+bnsNZz2W{VlAz{Z_Vn@AkF&{bYFuA8yD|60xw55pTj-#as(eI>u2EJ3~Fxo$jLXur8-D^sUn9jwf)25'
    'wc=MrMu1}oIEEsYs)LPIwufn8ZNEUp|C2A8oSA_Y{57?4-?19ZE8N8g=Qlv~PnN9FWC#^Wvq&<?uB)#ikJj&}w1*tG{kjS*`tLZG'
    '_+9e<uk(^eB^P#~!wA|#hc_5*7SF^jo(6`4@Tk5#C79W#1XAjxDjv#{0<({PQ}9_lABl39Sc!0!+>*CtG%(+@vs(HY&{4U>Ev6^i'
    'fNs6Xi!zBQ3#szO(7l_D>=8Ohr%qbovcT(&4IfAidqNC5tRv5|k@y>G^W<a1wthS2Z^rmNJH4Dr*I;KRJ>MK!AU86Onjq)Y_Pfr3'
    'KG^u}9P;M)&va`!0WC(0sLZm#v$ReITa6t?hZP{jdka3JhcsM1Gh12VHqo^85MVn#JFa-NA^764pjwsbHl^xOu5pHwbJxUm!?q^v'
    'N_M-l?W%OQDPOms2i*bbAk*DqG%}q=aYJ3w-c8}}r1VLzY3EZ~Z2G)hzp+XJG%Y~gdK-jYNiq8F@7xOdXDSE{ce-e2#v#m3S{6Ok'
    '&vt%z)xG4%$M3V*J1a!$@UiMik5C?^gYiiCuD+Fm4VK|hJ!*B0I3}D%V_NskPMoU&^5tWcxJIm&zrYdt$N0$m4&6k^Fiu!gE1ixx'
    'IkMq~j4WSsZ7$eL)wkc{U`&iWZNn51wrRUpNJ+%(%JzE3*$dCLIb1qC;&UaWsd3yV!BN`=pdI#c!|3)bFdao03yL=>TrWrL1x~a('
    '_0DxRg!g8E$h?Yp=(uHJcUjyH#vQC#(QczL+u99Sr*sv`<<|z0HZb(t7J923ZD4_SCCFy}rQnm=@#fh#*8{b7aGG<m5w~gP8x1!b'
    '`?4z*wF4m=xcaY6Q+B+5C`PW#U;nLzFY$NVOtJs8pX*J*RF_e?!nAU=x_fD|vZgTf^|1c~p}fwaItxW>9B!6m9I0^4n*|;{E+}XC'
    'g57Ntx|{0D3Sp7n4#yNts)uZ2d&!pjyTxNO_DDC`%(E_d49NGRw*KX?HOtId2EHYrGNbg*vUHC!>n4wo(QOBE-Xj{j!)|4?%{I=j'
    'Eq$f9@@~FOSHEU=pJr!&=Fz^4JhMA;4LDkj&SbSGlr;xx-4D@rnR>i_CNS#YjqTR>58YH|aVqYNdC$h&b6fj|9C=r6Mi&`t2268$'
    '=l6@;Lpw>LeN2bHB_ZB;^rJmLolkXjLvOwZ_wrn!_WF9=MAn{+wgW@W3rApE^mbz=%BFT!|4w_-F5x_dYJ+Et1r!C8>2T|ZUYDDN'
    'iZ<BJ+h<tM6<*KCnp*aoY<#<8PsZAA#`*>m+?X)0FF9Hjs}@z{_dOM3H+i4j>vZ_+dY{bel+eD4y<Ppxtv=>9k8!t{LpM=s!)rI)'
    'X?C5^_al5B)8E;8IZ6qN-`UyKm_u}6RkGi<{33hK7UTBReYr0DS^H@5(Qm>B7j?Ow)_CdaxV%{}f!A-bIC|NGIifP@BlCG*`2h2P'
    '+?!sNWb;9=OsWbx@%>VZav3DZ_KBEgX%x#&`L8z!BXt?4Sc3BAmjB|pVOdiDsk#tNgFySLb)@QM4zTkmie|+$iu$Z67M{`c=tS>!'
    'fZ<Rk^Q-#%%yVyPVEx3UA4pAoH)we_4rIhr8X3qW`lP^wE!2z6Ygpvj-6L9ywLQe853MnY`bgyDEs|_?q=o9@-CHW!xDi*pN{9G^'
    ')SDX{+X}!`qKp<I6m|ab8A*(xMeym!abN8C3PGt02zb>JzssX}{atSN$gv&b(kSLwX~f=G&7bdJzj4alGBZg5Xplw-eHQMCcYyLS'
    'b6r{z7~G$;(-lfhj`R$cV5rXKN&hP{g-yu@mMhNrqb<AeuN&Lki@+}X48lC=TpOrrf8T!kXi(n{!A8^qC9<TB2wHw=xil?A;E2mZ'
    '+kNS_dZ>;evnoN6^J}X2V!xF)Q=5$z?|MMX{)2s8weKY5JoVh6engKU)n~rL%cN1UN=kXBTUZU9$#A+8GSbpqHa&p75LQA&{!<ju'
    'FAPNy?u=0+3$ln6c0uHwd`dB~0`^Tn^M6k)t78'
)


def _embedded_installer_main(arguments):
    try:
        source = zlib.decompress(base64.b85decode(_EMBEDDED_INSTALLER_B85))
    except (ValueError, zlib.error):
        print(json.dumps({"ok": False, "status": "installer_integrity_failed"}, sort_keys=True))
        return 2
    if hashlib.sha256(source).hexdigest() != _EMBEDDED_INSTALLER_SHA256:
        print(json.dumps({"ok": False, "status": "installer_integrity_failed"}, sort_keys=True))
        return 2
    namespace = {
        "__name__": "zhiku_embedded_suite_installer",
        "__file__": str(Path(__file__).resolve()),
        "__package__": None,
    }
    try:
        exec(compile(source, "<zhiku-install-suite>", "exec"), namespace)
        entrypoint = namespace["main"]
    except (KeyError, SyntaxError, TypeError, ValueError):
        print(json.dumps({"ok": False, "status": "installer_integrity_failed"}, sort_keys=True))
        return 2
    return int(entrypoint(arguments))


BASE = os.environ.get("ZHIKU_API_BASE", "https://os-zk.84000.art/zhiku-api")
BEACON_URL = os.environ.get("ZHIKU_BEACON_URL", "https://os-zk.84000.art/zhiku-mcp/event")
PROOF_URL = os.environ.get("ZHIKU_EVENT_PROOF_URL", "https://os-zk.84000.art/zhiku-mcp/event-proof")
# match.py / H5 / CLI must move together. The deploy generator refuses drift.
SCORE_FORMULA_VERSION = "lex-v3-suite-usage"
CACHE_DIR = os.path.expanduser("~/.cache/zhiku")
CACHE = os.path.join(CACHE_DIR, "catalog.json")
PROFILE_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "profiles")
WORKSPACE = Path(os.environ.get("ZHIKU_WORKSPACE", Path.home() / ".local" / "share" / "zhiku"))
MAX_ROOT = Path(os.environ.get("ZHIKU_MAX_ROOT", WORKSPACE / "strategic-projects" / "zhiku-market-max"))
GOVERNOR_HOME = Path(
    os.environ.get(
        "ZHIKU_GOVERNOR_HOME",
        os.environ.get(
            "ZHIKU_SKILL_HOME",
            Path.home() / ".local" / "share" / "zhiku-skill-governor",
        ),
    )
)
OPERATE_RECEIPTS = Path(
    os.environ.get(
        "ZHIKU_OPERATE_RECEIPTS",
        GOVERNOR_HOME / "receipts" / "operate",
    )
)
TTL = 24 * 3600
TYPES = ("skills", "agents", "commands", "mcps", "settings", "hooks")
FLAGS = {"skills": "--skill", "agents": "--agent", "commands": "--command",
         "mcps": "--mcp", "settings": "--setting", "hooks": "--hook"}
TYPE_HINTS = {
    "mcps": ("mcp", "mcps", "connector", "连接器"),
    "hooks": ("hook", "hooks", "钩子"),
    "settings": ("setting", "settings", "配置", "设置"),
    "agents": ("agent", "agents", "subagent", "智能体", "子代理", "代理"),
    "commands": ("command", "commands", "slash command", "斜杠命令", "命令", "指令"),
    "skills": ("skill", "skills", "技能"),
}
PERMISSION_LEVELS = ("inspect", "draft", "apply", "publish_or_pay")
AUTHORING_CORE_BLOCKER = "blocked_authoring_core_untrusted"
SKILL_CANONICAL_ID = re.compile(
    r"^zk:(?:skill:[a-z0-9]+(?:-[a-z0-9]+)*|skills:[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*)$"
)


def _file_sha256(path):
    try:
        return hashlib.sha256(path.read_bytes()).hexdigest()
    except OSError:
        return ""


def _git_read(root, *args):
    result = subprocess.run(
        ["git", "-C", str(root), *args],
        check=False,
        text=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
    )
    return {
        "returncode": result.returncode,
        "stdout": result.stdout.strip(),
        "stderr": result.stderr.strip(),
    }


def _block_authoring_core(reason):
    raise SystemExit(f"{AUTHORING_CORE_BLOCKER}:{reason}")


def _trusted_authoring_core(runtime_root):
    governor_home = Path(
        os.environ.get(
            "ZHIKU_GOVERNOR_HOME",
            Path.home() / ".local/share/zhiku-skill-governor",
        )
    ).expanduser()
    receipt_path = governor_home / "automation/daily-install-receipt.json"
    try:
        receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
        metadata = json.loads((runtime_root / "runtime-metadata.json").read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError):
        _block_authoring_core("install_receipt_or_runtime_metadata_missing")
    if not (
        receipt.get("schema") == "zhiku_skill_governor_daily_install_receipt_v2"
        and receipt.get("status") == "installed"
        and receipt.get("source_dirty") is False
        and receipt.get("external_writes") is False
    ):
        _block_authoring_core("install_receipt_not_trusted")
    commit = str(metadata.get("commit") or "")
    if not commit or receipt.get("commit") != commit:
        _block_authoring_core("install_receipt_commit_mismatch")
    try:
        installed_runtime = Path(str(receipt.get("runtime") or "")).expanduser().resolve()
    except OSError:
        _block_authoring_core("install_receipt_runtime_invalid")
    if installed_runtime != runtime_root.resolve():
        _block_authoring_core("install_receipt_runtime_mismatch")
    core_root = Path(str(receipt.get("core_root") or "")).expanduser()
    engine = core_root / "systems/zhiku/forge/skill_governor.py"
    runtime_engine = runtime_root / "systems/zhiku/forge/skill_governor.py"
    if not engine.is_file() or not runtime_engine.is_file():
        _block_authoring_core("authoring_engine_missing")
    head = _git_read(core_root, "rev-parse", "HEAD")
    if head["returncode"] != 0:
        _block_authoring_core("authoring_commit_query_failed")
    if head["stdout"] != commit:
        _block_authoring_core("authoring_commit_mismatch")
    status = _git_read(
        core_root,
        "status",
        "--porcelain",
        "--untracked-files=all",
    )
    if status["returncode"] != 0:
        _block_authoring_core("authoring_status_query_failed")
    if status["stdout"]:
        _block_authoring_core("authoring_worktree_dirty")
    engine_hash = _file_sha256(engine)
    if not engine_hash or engine_hash != _file_sha256(runtime_engine):
        _block_authoring_core("authoring_engine_hash_mismatch")
    if receipt.get("engine_hash") != engine_hash or metadata.get("engine_hash") != engine_hash:
        _block_authoring_core("authoring_engine_attestation_mismatch")
    return core_root.resolve()


def private_core_root():
    try:
        runtime_or_core = Path(__file__).resolve().parents[4]
    except IndexError:
        _block_authoring_core("entrypoint_root_unknown")
    configured = os.environ.get("ZHIKU_CORE_ROOT")
    if configured:
        root = Path(configured).expanduser().resolve()
        if not (root / "systems/zhiku/forge/skill_governor.py").is_file():
            _block_authoring_core("configured_core_invalid")
        if (runtime_or_core / "runtime-metadata.json").is_file():
            trusted = _trusted_authoring_core(runtime_or_core)
            if root != trusted:
                _block_authoring_core("configured_core_not_attested")
        return root
    if (runtime_or_core / "runtime-metadata.json").is_file():
        return _trusted_authoring_core(runtime_or_core)
    if not (runtime_or_core / "systems/zhiku/forge/skill_governor.py").is_file():
        _block_authoring_core("private_control_plane_unavailable")
    return runtime_or_core

# 中→英领域词映射（与网页版 AI 助理同源算法）
ZH2EN = {
"视频": ["video", "clip"], "剪辑": ["video", "edit", "clip", "cut"], "剪映": ["capcut", "jianying"],
"短视频": ["video", "tiktok", "short"], "抖音": ["douyin", "tiktok", "video"],
"小红书": ["xiaohongshu", "xhs", "rednote", "social"], "微博": ["weibo", "social"], "推特": ["twitter", "social"],
"公众号": ["wechat", "article", "writing", "content"], "微信": ["wechat"],
"写作": ["writing", "writer", "article"], "文章": ["article", "writing", "content"],
"长文": ["article", "writing", "longform"], "文案": ["copywriting", "copy", "marketing"],
"营销": ["marketing", "growth", "seo"], "推广": ["marketing", "promotion"],
"飞书": ["feishu", "lark"], "多维表": ["bitable", "lark", "base"],
"表格": ["spreadsheet", "excel", "sheet", "xlsx"], "文档": ["document", "docx", "doc"],
"幻灯": ["slides", "pptx", "presentation"], "演示": ["presentation", "slides", "pptx"],
"简历": ["resume", "cv"], "邮件": ["email", "mail", "gmail"],
"日历": ["calendar", "schedule"], "日程": ["calendar", "schedule", "planning"],
"提醒": ["reminder", "notification"], "定时": ["cron", "schedule", "timer"],
"爬虫": ["scrape", "crawler", "scraping", "spider"], "抓取": ["scrape", "fetch", "crawl", "extract"],
"浏览器": ["browser", "chrome", "playwright"], "自动化": ["automation", "workflow", "automate"],
"工作流": ["workflow", "automation", "n8n", "pipeline"], "流程": ["workflow", "process"],
"数据库": ["database", "sql", "postgres", "sqlite"], "数据分析": ["data", "analysis", "analytics"],
"可视化": ["visualization", "chart", "dashboard"], "图表": ["chart", "diagram", "graph"],
"仪表盘": ["dashboard", "cockpit"], "看板": ["dashboard", "kanban", "board"], "报告": ["report", "reporting"],
"海报": ["poster", "canvas", "design", "image"], "封面": ["cover", "image", "thumbnail"],
"图片": ["image", "photo", "picture"], "配图": ["image", "illustration"],
"画图": ["diagram", "drawing", "draw"], "插画": ["illustration", "art", "image"],
"设计": ["design", "ui", "frontend"], "审美": ["design", "taste", "aesthetic"],
"前端": ["frontend", "react", "vue", "web", "ui"], "后端": ["backend", "api", "server"],
"网页": ["web", "html", "page", "website"], "网站": ["website", "web", "site"],
"落地页": ["landing", "page", "web"], "部署": ["deploy", "deployment", "hosting"],
"上线": ["deploy", "launch", "release"], "发布": ["release", "publish", "deploy"],
"测试": ["test", "testing", "qa", "e2e"], "调试": ["debug", "debugging", "troubleshoot"],
"重构": ["refactor", "refactoring"], "审查": ["review", "audit"], "代码审查": ["code-review", "review"],
"盘点": ["inventory", "audit"], "治理": ["governance", "governor", "audit"],
"生态": ["skill", "ecology", "catalog"], "蒸馏": ["distill", "distillation", "extract"],
"调用": ["usage", "invocation", "route", "routing"],
"安全": ["security", "vulnerability", "audit"], "漏洞": ["vulnerability", "security", "exploit"],
"性能": ["performance", "optimize", "speed"], "优化": ["optimize", "optimization", "performance"],
"翻译": ["translate", "translation", "i18n"], "多语言": ["i18n", "localization", "translation"],
"语音": ["speech", "voice", "audio"], "转写": ["transcribe", "transcription", "whisper"],
"转录": ["transcribe", "transcription", "whisper"], "音频": ["audio", "sound"], "音乐": ["music", "audio"],
"播客": ["podcast", "audio"], "字幕": ["subtitle", "caption", "srt"], "直播": ["live", "stream", "streaming"],
"研究": ["research", "analysis"], "调研": ["research", "survey", "investigate"],
"产品": ["product"], "产品战略": ["product", "strategy", "strategist", "roadmap", "positioning"],
"战略": ["strategy", "strategist", "roadmap", "planning"], "路线图": ["roadmap", "planning"],
"优先级": ["priority", "prioritization"], "市场分析": ["market", "analysis", "research"],
"竞争分析": ["competitive", "analysis", "intelligence"],
"论文": ["paper", "academic", "research", "arxiv"], "总结": ["summary", "summarize"],
"摘要": ["summary", "abstract"], "笔记": ["note", "notes", "obsidian"],
"知识库": ["knowledge", "wiki", "notebook"], "记忆": ["memory", "recall"],
"提示词": ["prompt", "prompting"], "智能体": ["agent", "agents"],
"股票": ["stock", "trading", "finance"], "投资": ["investment", "finance", "trading"],
"财务": ["finance", "financial", "accounting"], "财报": ["financial", "earnings", "report"],
"量化": ["quant", "trading", "backtest"], "加密货币": ["crypto", "blockchain"], "区块链": ["blockchain", "crypto", "web3"],
"法律": ["legal", "law", "contract"], "合同": ["contract", "legal"],
"招聘": ["recruiting", "hiring", "hr"], "面试": ["interview", "hiring"],
"课程": ["course", "education", "teaching"], "教学": ["teaching", "education", "tutorial"],
"学习": ["learning", "education", "study"], "游戏": ["game", "gaming"],
"地图": ["map", "location", "geo"], "天气": ["weather"], "新闻": ["news", "feed"],
"订阅": ["rss", "subscription", "feed"], "下载": ["download", "fetch"], "上传": ["upload"],
"备份": ["backup", "sync"], "同步": ["sync", "synchronize"], "监控": ["monitor", "monitoring", "alert"],
"告警": ["alert", "alerting", "notification"], "通知": ["notification", "notify", "push"],
"任务管理": ["task", "todo", "project"], "项目管理": ["project", "management", "jira"],
"文件": ["file", "files"], "整理": ["organize", "cleanup", "tidy"], "重命名": ["rename"],
"格式化": ["format", "formatting", "lint"], "提交": ["commit", "git"], "分支": ["branch", "git"],
"合并": ["merge", "git"], "仓库": ["repo", "repository", "github"], "接口": ["api", "endpoint"],
"文档生成": ["documentation", "docs"], "架构": ["architecture", "diagram", "system"],
"图标": ["icon", "logo"], "商标": ["logo", "brand"], "品牌": ["brand", "branding"],
"选品": ["product", "sourcing", "ecommerce"], "电商": ["ecommerce", "shop", "product"],
"客服": ["support", "customer", "service"], "问卷": ["survey", "form"], "表单": ["form", "input"],
"密码": ["password", "auth", "credential"], "登录": ["auth", "login", "oauth"], "权限": ["permission", "auth", "access"],
}
STOP = re.compile(r"^(我要|我想|想要|帮我|请帮|帮忙|给我|怎么|如何|有没有|哪个|什么|一个|一份|一篇|一条|需要|用来|可以|能不能|做个|做一个|搞个|弄个|请问)")


def fetch_json(base, name, refresh):
    cache = os.path.join(CACHE_DIR, name.replace("/", "-"))
    has_cache = os.path.exists(cache)
    if not refresh and has_cache and time.time() - os.path.getmtime(cache) < TTL:
        with open(cache, encoding="utf-8") as f:
            return json.load(f)
    url = base.rstrip("/") + "/" + name
    headers = {"User-Agent": "zhiku-cli/0.4"}
    if has_cache:
        headers["If-Modified-Since"] = time.strftime(
            "%a, %d %b %Y %H:%M:%S GMT", time.gmtime(os.path.getmtime(cache))
        )
    req = urllib.request.Request(url, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=60) as r:
            data = json.loads(r.read().decode("utf-8"))
    except urllib.error.HTTPError as exc:
        if exc.code == 304 and has_cache:
            os.utime(cache, None)
            with open(cache, encoding="utf-8") as f:
                return json.load(f)
        raise
    os.makedirs(CACHE_DIR, exist_ok=True)
    with open(cache, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False)
    return data


def fetch_catalog(base, refresh):
    return fetch_json(base, "catalog.json", refresh)


def fetch_usage(base, refresh):
    """Return aggregate usage weights; missing endpoints fail open to zero."""
    try:
        return (fetch_json(base, "usage.json", refresh) or {}).get("usage", {}) or {}
    except Exception:
        return {}


def _client_id():
    """自愿代号（ZHIKU_CLIENT_ID env，slug 2-24 位）；不设/非法 = 匿名如旧。"""
    cid = (os.environ.get("ZHIKU_CLIENT_ID") or "").strip().lower()
    return cid if re.fullmatch(r"[a-z0-9][a-z0-9_-]{1,23}", cid) else ""


def send_beacon(query, returned_paths, tool="search", selected=None):
    """Send a best-effort anonymous usage signal after results are printed."""
    if os.environ.get("ZHIKU_NO_TELEMETRY") == "1":
        return
    try:
        q_hash = hashlib.sha256((query or "").strip().lower().encode("utf-8")).hexdigest()[:12]
        proof_req = urllib.request.Request(PROOF_URL + "?source=cli", headers={"User-Agent": "zhiku-cli/0.5"})
        proof = json.loads(urllib.request.urlopen(proof_req, timeout=3).read().decode("utf-8")).get("proof")
        if not proof:
            return
        payload = {
            "tool": tool,
            "source": "cli",
            "q_hash": q_hash,
            "returned": [p for p in (returned_paths or [])[:20] if p],
            "proof": proof,
        }
        if selected:
            payload["selected"] = selected           # 强信号：CLI 侧的采纳/安装目标 path
        cid = _client_id()
        if cid:
            payload["client_id"] = cid
        body = json.dumps(payload).encode("utf-8")
        req = urllib.request.Request(
            BEACON_URL,
            data=body,
            headers={"Content-Type": "text/plain", "User-Agent": "zhiku-cli/0.5"},
        )
        urllib.request.urlopen(req, timeout=3)
    except Exception:
        pass


def _routing_receipt_root():
    configured = os.environ.get("ZHIKU_USAGE_RECEIPT_HOME")
    if configured:
        return Path(configured).expanduser()
    governor_home = Path(
        os.environ.get(
            "ZHIKU_GOVERNOR_HOME",
            Path.home() / ".local/share/zhiku-skill-governor",
        )
    ).expanduser()
    return governor_home / "usage-inbox"


def _routing_canonical_id(t, it, profiles):
    if t != "skills":
        return ""
    profile = profile_for(t, it, profiles)
    canonical_id = str(
        profile.get("canonical_id") or it.get("canonical_id") or ""
    )
    if SKILL_CANONICAL_ID.fullmatch(canonical_id):
        return canonical_id
    name = re.sub(
        r"[^a-z0-9]+",
        "-",
        str(it.get("name") or "").strip().lower(),
    ).strip("-")
    fallback = f"zk:skill:{name}" if name else ""
    return fallback if SKILL_CANONICAL_ID.fullmatch(fallback) else ""


def write_routing_receipts(query, hits, profiles, evolution_note=None):
    """Persist privacy-minimized local recommendation exposure receipts.

    The query and task identifiers are hashed and never stored. A caller may
    provide ``ZHIKU_USAGE_EVENT_ID`` to make retries of the same routing event
    idempotent; otherwise each CLI invocation is a new recommendation event.

    ``evolution_note`` is the optional third ring of the SOUL evidence loop
    (no Evolution Note -> no Done): a short reusable lesson from this routing
    event. It is written into every receipt of the event when provided and
    omitted otherwise. Returns the receipt file paths written (or already
    present, for idempotent retries), so callers can honestly verify evidence
    backflow per candidate from the receipts on disk.
    """
    if os.environ.get("ZHIKU_NO_LOCAL_USAGE_RECEIPTS") == "1":
        return []
    event_source = os.environ.get("ZHIKU_USAGE_EVENT_ID") or (
        f"route:{utc_now()}:{os.getpid()}:{uuid.uuid4().hex}"
    )
    task_source = os.environ.get("ZHIKU_TASK_ID") or re.sub(
        r"\s+", " ", str(query or "").strip().lower()
    )
    task_hash = hashlib.sha256(task_source.encode("utf-8")).hexdigest()[:16]
    occurred_at = utc_now()
    root = _routing_receipt_root()
    written = []
    for rank, (_, t, it) in enumerate(hits, 1):
        canonical_id = _routing_canonical_id(t, it, profiles)
        if not canonical_id:
            continue
        event_hash = hashlib.sha256(
            f"{event_source}|{canonical_id}".encode("utf-8")
        ).hexdigest()[:16]
        receipt_key = json.dumps(
            {
                "canonical_id": canonical_id,
                "client": "zhiku_cli",
                "event_hash": event_hash,
            },
            sort_keys=True,
            separators=(",", ":"),
        )
        receipt_id = "zkur2-" + hashlib.sha256(
            receipt_key.encode("utf-8")
        ).hexdigest()[:16]
        receipt = {
            "schema": "skill_usage_receipt_v2",
            "receipt_id": receipt_id,
            "occurred_at": occurred_at,
            "canonical_id": canonical_id,
            "client": "zhiku_cli",
            "event_hash": event_hash,
            "task_hash": task_hash,
            "task_type": "skill-routing",
            "event": "recommended",
            "note": f"router recommendation rank={rank}",
            "duration_ms": None,
            "raw_conversation_stored": False,
        }
        if evolution_note:
            receipt["evolution_note"] = str(evolution_note)[:500]
        target = root / f"{receipt_id}.json"
        try:
            root.mkdir(parents=True, exist_ok=True)
            with target.open("x", encoding="utf-8") as stream:
                json.dump(receipt, stream, ensure_ascii=False, indent=2)
                stream.write("\n")
        except FileExistsError:
            # Idempotent retry: the receipt already exists on disk, so the
            # evidence backflow for this candidate is still real.
            written.append(str(target))
            continue
        except OSError:
            continue
        written.append(str(target))
    return written


def _telemetry_client():
    """Return the consent-gated private client without affecting routing."""
    try:
        core_root = private_core_root()
        if str(core_root) not in sys.path:
            sys.path.insert(0, str(core_root))
        from systems.zhiku.telemetry.client import TelemetryClient
        client = TelemetryClient()
        return client if client.enabled() else None
    except (Exception, SystemExit):
        return None


def write_component_telemetry(query, hits):
    """Record the all-component eligibility/recommendation funnel privately."""
    client = _telemetry_client()
    if client is None:
        return
    type_map = {
        "skills": "skill", "agents": "agent", "commands": "command",
        "mcps": "mcp", "settings": "setting", "hooks": "hook",
    }
    try:
        from systems.zhiku.telemetry.client import classify_task_locally
        task_type = classify_task_locally(query)
        candidates = [
            (type_map[t], str(it.get("name") or it.get("path") or "unknown"))
            for _, t, it in hits if t in type_map
        ]
        client.record_eligibility(
            task_source=query, task_type=task_type, candidates=candidates,
            completeness="complete", reason="observed" if candidates else "no_applicable_component",
            client="zhiku_cli", client_version="0.5",
        )
        for component_type, canonical_id in candidates:
            client.record_usage(
                component_type=component_type, canonical_id=canonical_id,
                task_source=query, task_type=task_type, event="recommended",
                client="zhiku_cli", client_version="0.5",
            )
    except Exception:
        pass


def write_cli_action_telemetry(command, target, outcome=None):
    client = _telemetry_client()
    if client is None:
        return
    try:
        task_source = f"zhiku:{command}:{target}"
        event = outcome or "invoked"
        client.record_usage(
            component_type="command", canonical_id=f"zhiku/{command}",
            task_source=task_source, task_type="operations", event=event,
            result_evidence="technical_execution" if event == "success" else "none",
            error_class="client_error" if event == "failure" else None,
            client="zhiku_cli", client_version="0.5",
        )
        if command == "install" and target:
            skill_events = ["selected", "invoked"] if outcome is None else [event]
            for skill_event in skill_events:
                client.record_usage(
                    component_type="skill", canonical_id=target,
                    task_source=task_source, task_type="operations", event=skill_event,
                    result_evidence="technical_execution" if skill_event == "success" else "none",
                    error_class="client_error" if skill_event == "failure" else None,
                    client="zhiku_cli", client_version="0.5",
                )
    except Exception:
        pass


def fetch_deep(base, t, refresh):
    """deep/<type>.json → {path: 深度记录}; 端点不可用时静默退化（老服务器无 deep 也能跑）。"""
    try:
        data = fetch_json(base, "deep/" + t + ".json", refresh)
        return {r.get("path"): r for r in data.get("items", [])}
    except Exception:
        return {}


def load_profiles():
    """Load local capability_profile_v1 dossiers if the skill package has them."""
    maps = {}
    for t in TYPES:
        p = os.path.join(PROFILE_DIR, t + ".json")
        try:
            data = json.load(open(p, encoding="utf-8"))
            maps[t] = {r.get("path"): r for r in data.get("items", [])}
        except Exception:
            maps[t] = {}
    return maps


def profile_for(t, it, profiles):
    return (profiles.get(t) or {}).get(it.get("path")) or {}


def profile_bonus(profile):
    """Governance-aware tie-breaker.

    Semantic match must dominate routing. Local availability, validation, and
    usage make a close candidate better; they should not lift a weak semantic
    hit above a clearly relevant remote component.
    """
    if not profile:
        return 0.0
    bonus = 0.0
    status = ((profile.get("how_to_use") or {}).get("status") or "")
    if status == "local_installed":
        bonus += 2.0
    elif status == "private_channel":
        bonus += 0.6
    usage = profile.get("usage") or {}
    calls = usage.get("local_calls") or 0
    try:
        bonus += min(1.5, float(calls) * 0.15)
    except Exception:
        pass
    validation = profile.get("validation") or {}
    if validation.get("state") in ("validated", "pass", "green"):
        bonus += 1.5
    risk = profile.get("risk_signals") or []
    if isinstance(risk, list):
        bonus -= min(2.0, len(risk) * 0.5)
    elif risk:
        bonus -= 0.5
    return bonus


def confidence_for(score, profile):
    base = min(0.88, 0.35 + float(score) / 120.0)
    if profile:
        rc = profile.get("routing_confidence")
        if isinstance(rc, (int, float)):
            base = (base + float(rc)) / 2
    return round(max(0.05, min(0.98, base)), 2)


def max_mode_for(t, it, profile):
    risk = (profile or {}).get("risk_signals") or []
    status = ((profile or {}).get("how_to_use") or {}).get("status") or ("private_channel" if it.get("mine") else "remote_install")
    if t in ("hooks", "settings") or risk:
        return "govern"
    if "dashboard" in (it.get("description") or "").lower() or "cockpit" in (it.get("description") or "").lower():
        return "cockpit"
    if status == "local_installed":
        return "route"
    return "route"


def confidence_grade(profile):
    """Dual-track confidence label aligned with canon: 🟢 direct vs 🟡 inferred.

    🟢 (直证) requires observed evidence on the profile: a green validation
    state or recorded local usage. Everything else is 🟡 (推断). The 0-1
    decimal ranks candidates; the grade governs decision display. Never
    present a bare decimal behind a green badge without this check.
    """
    profile = profile or {}
    validation = ((profile.get("validation") or {}).get("state") or "")
    usage = profile.get("usage") or {}
    try:
        observed = float(usage.get("local_calls") or 0) > 0
    except (TypeError, ValueError):
        observed = False
    if validation in ("validated", "pass", "green") or observed:
        return "🟢"
    return "🟡"


# Canonical Three Seals (yuanli-os-greenbook A01/A07): recursive evolution /
# skill commander (先 search 再 call) / human friendliness. "Global optimum"
# is NOT a seal; it remains the internal ordering principle of route mode.
GLOBAL_OPTIMUM_ORDERING_NOTE = (
    "全局最优不是三法印；它是 route 模式内部的排序原则："
    "最小可靠路由优先，本地可用 > 远程安装 > 无证据不推荐。"
)
_GATE_WORDS = ("人工", "审批", "确认", "权限", "approval", "review")


def _seal(status, detail):
    return {"status": status, "detail": detail}


def three_seals_for(t, it, profile, context=None):
    """Per-candidate real check of the canonical Three Seals.

    ``context`` records what the caller actually did for this recommendation:
      - ``search_performed``: {"catalog": bool, "local_profiles": bool} —
        whether the catalog / local profiles were really searched first;
      - ``receipts_written``: iterable of canonical ids that received a
        usage receipt in this routing event;
      - ``canonical_id``: this candidate's canonical id;
      - ``next_step``: the exact next-step text emitted to the user.

    Missing context means unverified, which reports ``warn`` — fail-closed,
    never a decorative green template. Returns one dict per seal with
    ``status`` in {"pass", "warn"} plus an ``overall`` rollup.
    """
    context = context or {}
    profile = profile or {}
    status = ((profile.get("how_to_use") or {}).get("status")
              or ("private_channel" if it.get("mine") else "remote_install"))
    validation = ((profile.get("validation") or {}).get("state") or "unknown")
    risk = profile.get("risk_signals") or []
    usage = profile.get("usage") or {}
    try:
        local_calls = float(usage.get("local_calls") or 0)
    except (TypeError, ValueError):
        local_calls = 0.0

    # Seal 2 — skill commander: search before call.
    search = context.get("search_performed")
    if isinstance(search, dict):
        catalog_searched = bool(search.get("catalog"))
        profiles_searched = bool(search.get("local_profiles"))
        if catalog_searched or profiles_searched:
            commander = _seal(
                "pass",
                f"推荐前已检索：目录={'是' if catalog_searched else '否'}，"
                f"本地 profiles={'是' if profiles_searched else '否'}（先 search 再 call）",
            )
        else:
            commander = _seal("warn", "已记录检索上下文但目录与本地 profiles 均未命中检索；先 search 再 call 未达成")
    else:
        commander = _seal("warn", "无检索证据记录；无法核实是否先 search 再 call")

    # Seal 1 — recursive evolution: evidence backflow for this candidate.
    canonical_id = str(context.get("canonical_id") or "")
    receipt_ids = set(context.get("receipts_written") or [])
    if canonical_id and canonical_id in receipt_ids:
        evolution = _seal("pass", f"本次路由已为 {canonical_id} 写入 usage receipt，证据回流成立")
    elif validation in ("validated", "pass", "green"):
        evolution = _seal("pass", f"profile 已有验证证据（state={validation}），使用后应刷新")
    elif local_calls > 0:
        evolution = _seal("pass", f"profile 已有本地调用记录（{int(local_calls)} 次），使用后应刷新")
    else:
        evolution = _seal("warn", "本候选无 receipt/验证/用量回流；按 internal-dry-run 对待，禁止呈现为已验证")

    # Seal 3 — human friendliness: only human-decision items, gates intact.
    needs_gate = (
        t in ("hooks", "settings")
        or status == "private_channel"
        or (bool(risk) and status != "local_installed")
    )
    next_step = str(context.get("next_step") or "")
    if needs_gate:
        if next_step and any(word in next_step for word in _GATE_WORDS):
            friendly = _seal("pass", f"高暴露面（{status}）已挂人工门，仅呈现需人决策项")
        else:
            friendly = _seal("warn", "高暴露面候选的对外文案未核实人工门；不得直接呈现安装/执行指令")
    else:
        burden = "本地已装，直接调用" if status == "local_installed" else "远程候选，安装前给出一项人工确认"
        friendly = _seal("pass", f"低负担路由：{burden}；无不可逆外部写入")

    seals = {
        "recursive_evolution": evolution,
        "skill_commander": commander,
        "human_friendliness": friendly,
    }
    seals["overall"] = (
        "pass"
        if all(seal["status"] == "pass" for seal in seals.values())
        else "warn"
    )
    return seals


def backwrite_for(t, it, profile, context=None):
    """Required MAX output field 回流 (backwrite): where evidence must flow.

    The contract is fail-closed: the field is always present, and when no
    backwrite target exists it says so explicitly with a reason instead of
    omitting the field or inventing one.
    """
    context = context or {}
    profile = profile or {}
    canonical_id = str(context.get("canonical_id") or "")
    receipt_ids = set(context.get("receipts_written") or [])
    if canonical_id and canonical_id in receipt_ids:
        return {
            "target": "usage_receipt",
            "reason": f"本次路由已为 {canonical_id} 写入 skill_usage_receipt_v2",
        }
    validation = ((profile.get("validation") or {}).get("state") or "")
    usage = profile.get("usage") or {}
    try:
        local_calls = float(usage.get("local_calls") or 0)
    except (TypeError, ValueError):
        local_calls = 0.0
    if validation in ("validated", "pass", "green") or local_calls > 0:
        return {
            "target": "profile",
            "reason": "profile 已有验证/用量证据；本次使用结果应回流刷新该 profile",
        }
    if t in ("hooks", "settings") or (profile.get("risk_signals") or []):
        return {
            "target": "risk_item",
            "reason": "高暴露面且零用量证据；安装前应在风险/决策板登记一项人工复核",
        }
    return {
        "target": "none",
        "reason": "无回流目标：候选无 profile 验证、无用量、本次未写入 receipt；先完成真实检索与试用再推荐",
    }


def next_step_for(t, it, profile):
    status = ((profile or {}).get("how_to_use") or {}).get("status") or ("private_channel" if it.get("mine") else "remote_install")
    if status == "local_installed":
        return "直接使用本地已装能力，并把结果写入 receipt 或 profile 回流。"
    if status == "private_channel":
        return "先确认私有共享权限；只读元数据可用于判断，不公开安装。"
    if t in ("hooks", "settings"):
        return "先人工复核事件、matcher、权限和风险，再决定是否安装。"
    return "如确认需要，按安装命令安装；安装后运行最小 smoke test。"


def utc_now():
    return dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat()


def short_slug(value, limit=36):
    value = re.sub(r"[^a-zA-Z0-9\u4e00-\u9fff]+", "-", str(value or "operate")).strip("-")
    return (value or "operate")[:limit].strip("-") or "operate"


def load_json_file(path, default):
    try:
        return json.loads(Path(path).read_text(encoding="utf-8"))
    except Exception:
        return default


def write_json_file(path, data):
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")


def normalize_recipe(recipe):
    if not isinstance(recipe, dict):
        raise ValueError("operation_recipe_v1 must be a JSON object")
    out = dict(recipe)
    out.setdefault("schema", "operation_recipe_v1")
    out.setdefault("executor", "ego-browser")
    out.setdefault("permission_level", "inspect")
    out.setdefault("planned_steps", [])
    out.setdefault("checkpoints", [])
    out.setdefault("rollback_note", "No external write should be made without a fresh human gate.")
    out.setdefault("risk_tags", [])
    out.setdefault("component_path", None)
    missing = [k for k in ("intent", "target_url") if not out.get(k)]
    if missing:
        raise ValueError("recipe missing required field(s): " + ", ".join(missing))
    if out.get("executor") != "ego-browser":
        raise ValueError("only executor=ego-browser is supported in v1")
    if out.get("permission_level") not in PERMISSION_LEVELS:
        raise ValueError("permission_level must be one of: " + ", ".join(PERMISSION_LEVELS))
    if not re.match(r"^https?://", str(out.get("target_url"))):
        raise ValueError("target_url must be an http(s) URL")
    if not isinstance(out.get("planned_steps"), list):
        raise ValueError("planned_steps must be a list")
    if not isinstance(out.get("checkpoints"), list):
        raise ValueError("checkpoints must be a list")
    if not isinstance(out.get("risk_tags"), list):
        raise ValueError("risk_tags must be a list")
    return out


def _sensitive_hash(value):
    return hashlib.sha256(str(value or "").encode("utf-8")).hexdigest()


def _safe_url_origin(value):
    try:
        parsed = urllib.parse.urlsplit(str(value or ""))
        if not parsed.scheme or not parsed.hostname:
            return "redacted"
        host = parsed.hostname
        if ":" in host and not host.startswith("["):
            host = f"[{host}]"
        port = f":{parsed.port}" if parsed.port else ""
        return f"{parsed.scheme}://{host}{port}"
    except Exception:
        return "redacted"


def receipt_safe_recipe(recipe):
    target = recipe.get("target_url")
    intent = recipe.get("intent")
    component_path = recipe.get("component_path")
    source_intent_hash = str(recipe.get("source_intent_hash") or "")
    if not re.fullmatch(r"[0-9a-f]{64}", source_intent_hash, re.I):
        source_intent_hash = _sensitive_hash(source_intent_hash) if source_intent_hash else None
    safe = {
        "schema": "operation_recipe_v1",
        "executor": recipe.get("executor"),
        "permission_level": recipe.get("permission_level"),
        "allow_apply": recipe.get("allow_apply") is True,
        "apply_implemented": recipe.get("apply_implemented") is True,
        "static_h5_executes_browser": recipe.get("static_h5_executes_browser") is True,
        "receipt_redaction": "wechat_agent" if recipe.get("receipt_redaction") == "wechat_agent" else "default",
        "source_intent_hash": source_intent_hash,
        "planned_step_count": len(recipe.get("planned_steps") or []),
        "checkpoint_count": len(recipe.get("checkpoints") or []),
        "risk_tag_count": len(recipe.get("risk_tags") or []),
        "component_ref_hash": _sensitive_hash(component_path) if component_path else None,
    }
    safe["target_url"] = _safe_url_origin(target)
    safe["target_url_hash"] = _sensitive_hash(target)
    safe["intent_hash"] = _sensitive_hash(intent)
    safe["intent_length"] = len(str(intent or ""))
    fields = recipe.get("draft_fields") or []
    if fields:
        safe["draft_field_hashes"] = [
            {"selector_hash": _sensitive_hash(field.get("selector")), "value_hash": _sensitive_hash(field.get("value"))}
            for field in fields if isinstance(field, dict)
        ]
    return safe


def _safe_blocker(value):
    text = str(value or "")
    if re.fullmatch(r"[a-z0-9_:-]{1,120}", text):
        return text
    return "opaque_error:" + _sensitive_hash(text)[:16]


def redact_operation_receipt(receipt):
    receipt["target_url_hash"] = _sensitive_hash(receipt.get("target_url"))
    receipt["target_url"] = _safe_url_origin(receipt.get("target_url"))
    intent = receipt.pop("intent", "")
    receipt["intent_hash"] = _sensitive_hash(intent)
    receipt["intent_length"] = len(str(intent or ""))
    component_path = receipt.pop("component_path", None)
    receipt["component_ref_hash"] = _sensitive_hash(component_path) if component_path else None
    task_space_id = receipt.pop("task_space_id", None)
    receipt["task_space_id_hash"] = _sensitive_hash(task_space_id) if task_space_id else None
    receipt["observations"] = [
        {
            "type": _safe_blocker(row.get("type") or "observation"),
            "value_hash": _sensitive_hash(row.get("value")),
            "value_length": len(str(row.get("value") or "")),
        }
        for row in (receipt.get("observations") or []) if isinstance(row, dict)
    ]
    cleaned_actions = []
    for row in receipt.get("actions_taken") or []:
        if not isinstance(row, dict):
            continue
        clean = {
            "type": _safe_blocker(row.get("type") or "action"),
            "submitted": row.get("submitted") is True,
            "keep": row.get("keep") is True,
        }
        if row.get("selector"):
            clean["selector_hash"] = _sensitive_hash(row["selector"])
        cleaned_actions.append(clean)
    receipt["actions_taken"] = cleaned_actions
    receipt["blockers"] = [_safe_blocker(value) for value in receipt.get("blockers") or []]
    receipt["handoff_events"] = [
        {
            "type": _safe_blocker(row.get("type") or "handoff"),
            "reason_hash": _sensitive_hash(row.get("reason")),
        }
        for row in receipt.get("handoff_events") or []
        if isinstance(row, dict)
    ]
    receipt["evidence_paths"] = [f"operate:{receipt.get('run_id')}"]
    receipt["raw_observations_stored"] = False
    receipt["local_paths_stored"] = False
    receipt["raw_conversation_stored"] = False
    return receipt


def default_receipt(recipe, mode, run_id):
    return {
        "schema": "operation_run_receipt_v1",
        "run_id": run_id,
        "executor": recipe.get("executor", "ego-browser"),
        "mode": mode,
        "permission_level": recipe.get("permission_level"),
        "component_path": recipe.get("component_path"),
        "target_url": recipe.get("target_url"),
        "intent": recipe.get("intent"),
        "task_space_id": None,
        "status": "created",
        "observations": [],
        "actions_taken": [],
        "handoff_events": [],
        "blockers": [],
        "evidence_paths": [],
        "started_at": utc_now(),
        "finished_at": None,
        "recipe": receipt_safe_recipe(recipe),
    }


def update_operate_governance(receipt):
    OPERATE_RECEIPTS.mkdir(parents=True, exist_ok=True)
    latest_receipts = sorted(OPERATE_RECEIPTS.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)[:10]
    status = receipt.get("status")
    run_id = receipt.get("run_id")

    action_path = MAX_ROOT / "action-ledger.json"
    action_doc = load_json_file(action_path, {"project_id": "zhiku-market-max", "items": []})
    actions = action_doc.setdefault("items", [])
    action = {
        "id": "A6",
        "title": "Operate with Ego 网页端 AI 自动操作任务包与本地执行层",
        "owner": "Codex",
        # Execution receipts alone never prove that the current H5/CLI
        # distribution still exposes Operate. build_max_cockpit.py promotes
        # this to done only after the hash-bound surface smoke gate passes.
        "status": "review",
        "priority": "P0",
        "evidence_refs": [f"operate:{run_id}"],
        "last_receipt": f"operate:{run_id}",
    }
    actions[:] = [a for a in actions if a.get("id") != "A6"] + [action]
    write_json_file(action_path, action_doc)

    risk_path = MAX_ROOT / "risk-register.json"
    risk_doc = load_json_file(risk_path, {"project_id": "zhiku-market-max", "items": []})
    risks = risk_doc.setdefault("items", [])
    risk = {
        "id": "R4",
        "title": "网页自动操作必须维持 ego task space 隔离与人工门",
        "level": "amber",
        "mitigation": "H5 只生成 operation_recipe_v1；本地 zhiku operate 执行，apply 默认阻断，publish_or_pay 永远 handoff。",
        "last_receipt": f"operate:{run_id}",
    }
    risks[:] = [r for r in risks if r.get("id") != "R4"] + [risk]
    write_json_file(risk_path, risk_doc)

    dashboard_path = MAX_ROOT / "dashboard-data.json"
    dashboard = load_json_file(dashboard_path, {})
    if dashboard:
        dashboard.setdefault("automation_status", {})["operate_with_ego"] = {
            "status": "receipt_recorded_surface_rebuild_required",
            "last_execution_status": status,
            "executor": receipt.get("executor"),
            "last_receipt": f"operate:{run_id}",
            "receipt_count": len(latest_receipts),
            "permission_level": receipt.get("permission_level"),
            "static_h5_executes_browser": False,
            "surface_gate": "rebuild_required",
        }
        dashboard.setdefault("metrics", {})["operate_receipts"] = len(latest_receipts)
        actions_data = dashboard.setdefault("actions", [])
        actions_data[:] = [a for a in actions_data if a.get("id") != "A6"] + [action]
        risks_data = dashboard.setdefault("risks", [])
        risks_data[:] = [r for r in risks_data if r.get("id") != "R4"] + [risk]
        write_json_file(dashboard_path, dashboard)


def write_receipt(receipt):
    receipt["finished_at"] = utc_now()
    OPERATE_RECEIPTS.mkdir(parents=True, exist_ok=True)
    out = OPERATE_RECEIPTS / f"{receipt['run_id']}.json"
    write_json_file(out, receipt)
    receipt["evidence_paths"] = [f"operate:{receipt['run_id']}"]
    write_json_file(out, receipt)
    update_operate_governance(receipt)
    return out


def run_ego_operation(recipe, receipt):
    permission = recipe.get("permission_level")
    if permission == "publish_or_pay":
        receipt["status"] = "blocked_human_gate"
        receipt["blockers"].append("publish_or_pay_requires_manual_handoff")
        receipt["handoff_events"].append({
            "type": "required_before_execution",
            "reason": "publish/pay/delete/external-send operations are never automated in v1",
        })
        return receipt
    if permission == "apply":
        receipt["status"] = "blocked_apply_not_implemented"
        receipt["blockers"].append("apply_requires_typed_actions_reversible_executor_and_verification_receipt")
        return receipt

    draft_fields = recipe.get("draft_fields") if isinstance(recipe.get("draft_fields"), list) else []
    task_name = f"zhiku:{receipt['run_id']}:{short_slug(recipe.get('intent'))}"
    js_recipe = json.dumps(recipe, ensure_ascii=False)
    js = f"""
const recipe = {js_recipe};
const task = await useOrCreateTaskSpace({json.dumps(task_name)});
const receipt = {{
  task_space_id: task.id,
  observations: [],
  actions_taken: [],
  handoff_events: [],
  blockers: []
}};
try {{
  await openOrReuseTab(recipe.target_url, {{ wait: true, timeout: 30 }});
  const info = await pageInfo();
  receipt.observations.push({{type: "page_info", value: info}});
  if (info && info.dialog) {{
    receipt.blockers.push("browser_dialog_open");
  }} else {{
    const snap = await snapshotText();
    receipt.observations.push({{type: "snapshot_head", value: String(snap || "").slice(0, 1800)}});
  }}
  if (recipe.permission_level === "draft" && Array.isArray(recipe.draft_fields)) {{
    for (const field of recipe.draft_fields) {{
      if (!field || !field.selector || field.value == null) continue;
      await fillInput(String(field.selector), String(field.value));
      receipt.actions_taken.push({{type: "fillInput", selector: String(field.selector), submitted: false}});
    }}
    const after = await snapshotText();
    receipt.observations.push({{type: "draft_verify_snapshot_head", value: String(after || "").slice(0, 1200)}});
  }}
  await completeTaskSpace(task.id, {{ keep: false }});
  receipt.actions_taken.push({{type: "completeTaskSpace", keep: false}});
  cliLog(JSON.stringify(receipt));
}} catch (err) {{
  receipt.blockers.push(String(err && err.message || err));
  try {{ await completeTaskSpace(task.id, {{ keep: false }}); }} catch (closeErr) {{}}
  cliLog(JSON.stringify(receipt));
}}
"""
    proc = subprocess.run(["ego-browser", "nodejs"], input=js, text=True, capture_output=True, timeout=90)
    combined_output = "\n".join(x for x in (proc.stdout, proc.stderr) if x)
    if proc.returncode != 0:
        receipt["status"] = "failed"
        receipt["blockers"].append(combined_output.strip() or f"ego-browser exited {proc.returncode}")
        return receipt
    lines = [ln.strip() for ln in combined_output.splitlines() if ln.strip()]
    payload = None
    for line in reversed(lines):
        try:
            payload = json.loads(line)
            break
        except Exception:
            continue
    if not payload:
        receipt["status"] = "failed"
        receipt["blockers"].append("ego_browser_no_json_receipt")
        if combined_output.strip():
            receipt["observations"].append({"type": "ego_output", "value": combined_output[-2000:]})
        return receipt
    receipt["task_space_id"] = payload.get("task_space_id")
    receipt["observations"].extend(payload.get("observations") or [])
    receipt["actions_taken"].extend(payload.get("actions_taken") or [])
    receipt["handoff_events"].extend(payload.get("handoff_events") or [])
    receipt["blockers"].extend(payload.get("blockers") or [])
    receipt["status"] = "completed" if not receipt["blockers"] else "blocked_needs_user"
    return receipt


def operate_main(args):
    recipe_path, executor, mode = None, "ego-browser", "dry_run"
    i = 0
    while i < len(args):
        a = args[i]
        if a == "--recipe":
            recipe_path = args[i + 1]; i += 2
        elif a == "--executor":
            executor = args[i + 1]; i += 2
        elif a == "--dry-run":
            mode = "dry_run"; i += 1
        elif a == "--apply":
            mode = "apply"; i += 1
        elif a in ("-h", "--help"):
            print("usage: zhiku operate --recipe operation_recipe_v1.json [--executor ego-browser] [--dry-run|--apply]")
            return
        else:
            sys.exit(f"未知 operate 参数: {a}")
    if not recipe_path:
        sys.exit("operate requires --recipe <operation_recipe_v1.json>")
    recipe = normalize_recipe(load_json_file(recipe_path, {}))
    recipe["executor"] = executor or recipe.get("executor") or "ego-browser"
    recipe = normalize_recipe(recipe)
    run_id = "op-" + dt.datetime.now().strftime("%Y%m%d-%H%M%S") + "-" + uuid.uuid4().hex[:6]
    receipt = default_receipt(recipe, mode, run_id)
    if mode == "dry_run":
        receipt["status"] = "dry_run"
        receipt["observations"].append({
            "type": "planned_task_space",
            "value": f"zhiku:{run_id}:{short_slug(recipe.get('intent'))}",
        })
        receipt["actions_taken"].append({
            "type": "no_browser_action",
            "reason": "dry-run only; static H5 never controls local browser directly",
        })
    else:
        receipt = run_ego_operation(recipe, receipt)
    receipt = redact_operation_receipt(receipt)
    out = write_receipt(receipt)
    print(json.dumps({
        "ok": receipt["status"] in ("dry_run", "completed", "blocked_apply_not_implemented", "blocked_human_gate", "blocked_needs_user"),
        "status": receipt["status"],
        "run_id": run_id,
        "receipt": str(out),
        "task_space_id": receipt.get("task_space_id"),
        "blockers": receipt.get("blockers"),
    }, ensure_ascii=False, indent=2))


def tokenize(q):
    en = [w for w in re.findall(r"[a-z0-9][a-z0-9_\-.]+", q.lower()) if len(w) >= 2]
    zh = re.sub(r"[a-zA-Z0-9_\-./]+", " ", q)
    segs = []
    for s in re.split(r"[^一-鿿]+", zh):
        if not s:
            continue
        prev = None
        while prev != s and s:
            prev, s = s, STOP.sub("", s)
        if len(s) >= 2:
            segs.append(s)
    grams = sorted({s[i:i + 2] for s in segs for i in range(len(s) - 1)})
    ex = sorted({w for s in segs for k, ws in ZH2EN.items() if k in s for w in ws} - set(en))
    return en, segs, grams, ex


def infer_type(q):
    """Infer component type from explicit user wording. Explicit -t still wins."""
    ql = q.lower()
    matches = []
    for t, hints in TYPE_HINTS.items():
        if any(h in ql for h in hints):
            matches.append(t)
    return matches[0] if matches else None


def strip_type_terms(q):
    """Remove explicit type words before semantic scoring so "database MCP" scores database."""
    out = q
    for hints in TYPE_HINTS.values():
        for h in hints:
            out = re.sub(re.escape(h), " ", out, flags=re.I)
    return re.sub(r"\s+", " ", out).strip() or q


def score_all(q, catalog, only_type=None, profiles=None, usage=None):
    profiles = profiles or {}
    usage = usage or {}
    en, segs, grams, ex = tokenize(q)
    res = []
    for t in TYPES:
        if only_type and t != only_type:
            continue
        for it in catalog.get(t, []):
            name = (it.get("name") or "").lower()
            suite = f"{it.get('suite_name') or ''} {it.get('suite_id') or ''}".lower()
            cat = (it.get("category") or "").lower()
            desc = (it.get("description") or "").lower()
            sc, hits = 0.0, 0
            for words, w in ((en, 1), (grams, 1), (segs, 1.5), (ex, 0.8)):
                for tok in words:
                    h = (
                        (5 if tok in name else 0)
                        + (5 if tok in suite else 0)
                        + (2 if tok in cat else 0)
                        + (1 if tok in desc else 0)
                    )
                    if h:
                        sc += h * w
                        hits += 1
            if sc <= 0:
                continue
            sc += hits * 2
            if it.get("mine"):
                sc *= 1.5
            sc += math.log10((it.get("downloads") or 0) + 1) * 0.3
            sc += math.log10((usage.get(it.get("path")) or 0) + 1) * 0.4
            sc += profile_bonus(profile_for(t, it, profiles))
            res.append((sc, t, it))
    res.sort(key=lambda x: -x[0])
    return res


def install_cmd(t, it):
    if it.get("install"):
        return str(it["install"])
    p = re.sub(r"\.(md|json)$", "", it.get("path") or it.get("name") or "")
    return f"npx claude-code-templates@latest {FLAGS[t]} {p} --yes"


def use_instruction(t, it, profile=None):
    status = ((profile or {}).get("how_to_use") or {}).get("status")
    if it.get("mine"):
        if status == "local_installed":
            return "本地已装：直接按当前 Codex skill 路由调用；不输出公开安装命令"
        return "私有共享通道：需仓库/共享权限后再安装；不输出公开安装命令"
    return install_cmd(t, it)


COMPONENT_ENDPOINT = os.environ.get("ZHIKU_COMPONENT_ENDPOINT", "https://os-zk.84000.art/zhiku-mcp/c/")


def deep_record(t, it, deepmaps):
    if it.get("mine"):
        return None
    record = (deepmaps.get(t) or {}).get(it.get("path"))
    if record:
        return record
    try:
        req = urllib.request.Request(
            COMPONENT_ENDPOINT + (it.get("path") or ""),
            headers={"User-Agent": "zhiku-cli/0.4"},
        )
        full = json.loads(urllib.request.urlopen(req, timeout=3).read().decode("utf-8"))
        return full.get("deep") or None
    except Exception:
        return None


def deep_text_lines(t, it, deepmaps, want_deep):
    """深度索引输出行: 不带 --deep 时只给 mcps 附「需 env:」; 带 --deep 时全量。"""
    if it.get("mine"):
        return ["    深度: 私有组件无公开深度信息（安装需 yuanli-os-starter 仓权限）"] if want_deep else []
    r = deep_record(t, it, deepmaps)
    if not r:
        return []
    out = []
    ek = r.get("env_required") or r.get("env_keys")
    if ek and (want_deep or t == "mcps"):
        out.append("    需 env: " + ", ".join(ek))
    if want_deep:
        if r.get("runner"):
            out.append("    运行方式: " + str(r["runner"]))
        if r.get("deps"):
            out.append("    依赖: " + ", ".join(r["deps"]))
        if r.get("allowed_tools"):
            out.append("    工具: " + r["allowed_tools"])
        if r.get("triggers"):
            out.append("    触发: " + r["triggers"][0])
        if r.get("usage"):
            out.append("    用法: " + r["usage"][0])
        if r.get("events"):
            out.append("    事件: " + ", ".join(r["events"]))
        if r.get("risk"):
            out.append("    风险信号: " + ", ".join(r["risk"]))
    return out


def normalize_governance_aliases(args):
    """Map human-facing governance commands onto the private control plane."""
    if len(args) < 2:
        return args
    aliases = {
        ("task", "contract"): "task-contract",
        ("route", "plan"): "route-plan",
        ("route", "verify"): "route-verify",
        ("route", "human-review"): "route-human-review",
        ("route", "human-review-record"): "route-human-review-record",
        ("route", "human-review-import"): "route-human-review-import",
        ("route", "shadow-record"): "route-shadow-record",
        ("route", "shadow-status"): "route-shadow-status",
        ("route", "shadow-readiness"): "route-shadow-readiness",
        ("agent", "gap"): "agent-gap",
        ("skill", "rerank"): "skill-rerank",
        ("adapter", "audit"): "adapter-audit",
        ("hook", "audit"): "hook-audit",
        ("instrumentation", "audit"): "instrumentation-audit",
        ("instrumentation", "plan"): "instrumentation-plan",
        ("instrumentation", "activate"): "instrumentation-activate",
        ("ecology", "report"): "ecology-report",
    }
    command = aliases.get((args[0], args[1]))
    return ["skill", command, *args[2:]] if command else args


def main():
    args = normalize_governance_aliases(sys.argv[1:])
    if args and args[0] == "install-suite":
        raise SystemExit(_embedded_installer_main(args[1:]))
    if args and args[0] == "telemetry":
        core_root = private_core_root()
        module = core_root / "systems/zhiku/telemetry/__main__.py"
        if not module.exists():
            sys.exit("blocked_private_control_plane_unavailable: set ZHIKU_CORE_ROOT to yuanli-os-starter")
        env = os.environ.copy()
        env["PYTHONPATH"] = str(core_root) + (os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else "")
        raise SystemExit(subprocess.call(
            [sys.executable, "-m", "systems.zhiku.telemetry", *args[1:]],
            cwd=str(core_root), env=env,
        ))
    if args and args[0] == "wechat":
        core_root = private_core_root()
        module = core_root / "systems/zhiku/wechat_agent/__main__.py"
        if not module.exists():
            sys.exit("blocked_private_control_plane_unavailable: set ZHIKU_CORE_ROOT to yuanli-os-starter")
        env = os.environ.copy()
        env["ZHIKU_CORE_ROOT"] = str(core_root)
        raise SystemExit(subprocess.call(
            [sys.executable, "-m", "systems.zhiku.wechat_agent", "--core-root", str(core_root), *args[1:]],
            cwd=str(core_root),
            env=env,
        ))
    if args and args[0] in {"skill", "use"}:
        core_root = private_core_root()
        governor = core_root / "systems/zhiku/forge/skill_governor.py"
        if not governor.exists():
            sys.exit("blocked_private_control_plane_unavailable: set ZHIKU_CORE_ROOT to yuanli-os-starter")
        forwarded = args[1:] if args[0] == "skill" else ["install", *args[1:]]
        telemetry_command = forwarded[0] if forwarded else "unknown"
        telemetry_target = forwarded[1] if len(forwarded) > 1 else ""
        write_cli_action_telemetry(telemetry_command, telemetry_target)
        rc = subprocess.call(
            [
                sys.executable,
                str(governor),
                "--core-root",
                str(core_root),
                *forwarded,
            ]
        )
        if (
            rc == 0
            and forwarded
            and forwarded[0] == "install"
            and len(forwarded) > 1
            and os.environ.get("ZHIKU_INSTALL_BEACON") == "1"
        ):
            send_beacon(forwarded[1], [], tool="install")   # 安装成功回流（q_hash=组件名）
        write_cli_action_telemetry(
            telemetry_command, telemetry_target, "success" if rc == 0 else "failure"
        )
        raise SystemExit(rc)
    if args and args[0] == "forge":
        core_root = private_core_root()
        forge = core_root / "systems/zhiku/forge/zhiku_forge.py"
        if not forge.exists():
            sys.exit("blocked_private_control_plane_unavailable: set ZHIKU_CORE_ROOT to yuanli-os-starter")
        raise SystemExit(subprocess.call([sys.executable, str(forge), *args[1:]]))
    if args and args[0] == "operate":
        operate_main(args[1:])
        return
    base, only_type, top, as_json, refresh, want_deep, max_mode = BASE, None, 10, False, False, False, False
    q = []
    i = 0
    while i < len(args):
        a = args[i]
        if a in ("-t", "--type"):
            only_type = args[i + 1]; i += 2
        elif a in ("-n", "--top"):
            top = int(args[i + 1]); i += 2
        elif a == "--base":
            base = args[i + 1]; i += 2
        elif a == "--json":
            as_json = True; i += 1
        elif a == "--max":
            max_mode = True; want_deep = True; i += 1
        elif a == "--refresh":
            refresh = True; i += 1
        elif a in ("-d", "--deep"):
            want_deep = True; i += 1
        elif a in ("-h", "--help"):
            print(__doc__); return
        else:
            q.append(a); i += 1
    if not q:
        print(__doc__); sys.exit(1)
    if only_type and only_type not in TYPES:
        sys.exit(f"未知类型 {only_type}，可选: {'/'.join(TYPES)}")
    query = " ".join(q)
    if not only_type:
        only_type = infer_type(query)
    score_query = strip_type_terms(query) if only_type else query
    catalog = fetch_catalog(base, refresh)
    profiles = load_profiles()
    usage = fetch_usage(base, refresh)
    hits = score_all(score_query, catalog, only_type, profiles, usage)[:top]
    # deep 索引按需懒加载: --deep 拉命中的全部类型; 默认只拉 mcps(装前 env 需求最关键且文件最小)
    need = {t for _, t, it in hits if not it.get("mine") and (want_deep or t == "mcps")}
    deepmaps = {t: fetch_deep(base, t, refresh) for t in need}
    # Evidence first: write routing receipts before presenting results so the
    # Three Seals can honestly report per-candidate evidence backflow.
    evolution_note = (os.environ.get("ZHIKU_EVOLUTION_NOTE") or "").strip() or None
    receipt_paths = write_routing_receipts(query, hits, profiles, evolution_note=evolution_note)
    # Derive the per-candidate backflow set from the receipts on disk: a
    # canonical id counts only when its receipt file is readable, so a failed
    # or skipped write can never masquerade as evidence.
    receipt_ids = set()
    for receipt_path in receipt_paths:
        try:
            payload = json.loads(Path(receipt_path).read_text(encoding="utf-8"))
        except (OSError, ValueError):
            continue
        canonical_id = payload.get("canonical_id")
        if canonical_id:
            receipt_ids.add(canonical_id)
    search_ctx = {
        "catalog": bool(catalog),
        "local_profiles": any(bool(profiles.get(t)) for t in TYPES),
    }
    if as_json:
        rows = []
        for s, t, it in hits:
            p = profile_for(t, it, profiles)
            row = {"score": round(s, 2), "type": t, "name": it.get("name"),
                   "category": it.get("category"), "mine": it.get("mine", 0),
                   "description": it.get("description", ""), "install": None if it.get("mine") else install_cmd(t, it),
                   "use": use_instruction(t, it, p)}
            if p:
                row["profile"] = {
                    "status": (p.get("how_to_use") or {}).get("status"),
                    "validation": (p.get("validation") or {}).get("state"),
                    "usage": p.get("usage"),
                    "risk_signals": p.get("risk_signals"),
                    "routing_confidence": p.get("routing_confidence"),
                    "max_recommendation_tier": p.get("max_recommendation_tier"),
                    "governance_flags": p.get("governance_flags"),
                }
            if max_mode:
                confidence = confidence_for(s, p)
                next_step = next_step_for(t, it, p)
                seal_ctx = {
                    "search_performed": search_ctx,
                    "receipts_written": receipt_ids,
                    "canonical_id": _routing_canonical_id(t, it, profiles),
                    "next_step": next_step,
                }
                row["max"] = {
                    "confidence": confidence,
                    "confidence_grade": confidence_grade(p),
                    "mode": max_mode_for(t, it, p),
                    "three_seals": three_seals_for(t, it, p, seal_ctx),
                    "backwrite": backwrite_for(t, it, p, seal_ctx),
                    "next_step": next_step,
                }
            r = deep_record(t, it, deepmaps)
            if r:
                row["deep"] = {k: v for k, v in r.items() if k not in ("name", "path")}
            rows.append(row)
        print(json.dumps(rows, ensure_ascii=False, indent=1))
        write_component_telemetry(query, hits)
        send_beacon(query, [it.get("path") for _, _, it in hits])
        return
    if not hits:
        print("没匹配到组件——换个说法试试（中文领域词或英文关键词，如 video / wechat / database）")
        return
    built = (catalog.get("_meta") or {}).get("built", "?")
    title = "随身智库-MAX" if max_mode else "随身智库 · 组件市场"
    print(f"{title} — \"{query}\" top {len(hits)}（数据 {built}）\n")
    for s, t, it in hits:
        star = " ★私有(需仓权限)" if it.get("mine") else ""
        p = profile_for(t, it, profiles)
        status = ((p.get("how_to_use") or {}).get("status") or ("private_channel" if it.get("mine") else "remote_install"))
        risk = p.get("risk_signals") or []
        desc = re.sub(r"\s+", " ", it.get("description") or "").strip()[:100]
        print(f"  {it.get('name')}  〔{t}·{it.get('category','—')}·{status}〕{star}")
        print(f"    {desc}")
        for ln in deep_text_lines(t, it, deepmaps, want_deep):
            print(ln)
        if risk:
            print("    profile 风险: " + ", ".join(risk if isinstance(risk, list) else [str(risk)]))
        if max_mode:
            confidence = confidence_for(s, p)
            grade = confidence_grade(p)
            grade_label = "直证" if grade == "🟢" else "推断"
            next_step = next_step_for(t, it, p)
            seal_ctx = {
                "search_performed": search_ctx,
                "receipts_written": receipt_ids,
                "canonical_id": _routing_canonical_id(t, it, profiles),
                "next_step": next_step,
            }
            print(f"    MAX 置信度: {confidence:.2f} {grade}{grade_label} · 模式: {max_mode_for(t, it, p)} · tier: {p.get('max_recommendation_tier', 'unknown')}")
            seals = three_seals_for(t, it, p, seal_ctx)
            print("    三法印:")
            print(f"      递归进化: [{seals['recursive_evolution']['status']}] {seals['recursive_evolution']['detail']}")
            print(f"      技能统帅: [{seals['skill_commander']['status']}] {seals['skill_commander']['detail']}")
            print(f"      人类友好: [{seals['human_friendliness']['status']}] {seals['human_friendliness']['detail']}")
            print("    " + GLOBAL_OPTIMUM_ORDERING_NOTE)
            backwrite = backwrite_for(t, it, p, seal_ctx)
            print(f"    回流: {backwrite['target']} — {backwrite['reason']}")
            print("    下一步: " + next_step)
        instruction = use_instruction(t, it, p)
        if it.get("mine"):
            print(f"    {instruction}\n")
        else:
            print(f"    $ {instruction}\n")
    write_component_telemetry(query, hits)
    send_beacon(query, [it.get("path") for _, _, it in hits])


if __name__ == "__main__":
    main()
