智能体工具调用批次最近秩耗时分位器：边界规则、可运行源码与验收-育师

项目编号：20261021-002。需求方向来自当日公开产品简介；所有示例均为独立合成数据，不是产品真实日志。

要解决的具体问题

对导出耗时使用最近秩定义计算P50/P95/P99、最小值、最大值与均值，不估计未观测请求。本工具只处理主动输入的JSON，不连接账户、不抓取服务，也不宣称能够替代热点产品。离线导出场景往往需要先给数据一个明确口径：时间是毫秒还是秒，右边界是否包含，空集合要返回零还是无统计值。若这些约定没有写清，报告看起来一致，实际含义却可能不同。这里把规则直接写入核心函数和测试，界面只负责调用同一实现。

输入契约

耗时是非负有限数；P值取排序后ceil(p*n)-1下标，不插值。空集合所有统计为null。

{"id":"string","callMs":"number"}

调用者应先脱敏，去掉密钥、账号与个人资料。标识使用字符串，不进行自动类型转换；重复id会拒绝整个请求，避免一个实体在统计中被重复累计。数值先检查Number.isFinite，带Ms后缀的时刻还必须是安全整数，不能让精度丢失悄悄改变边界判断。

合成样本与可核对输出

{"records":[{"id":"sample-0","callMs":1},{"id":"sample-1","callMs":2},{"id":"sample-2","callMs":9},{"id":"sample-3","callMs":10}]}

{"count":4,"metric":"callMs","definition":"nearest-rank","min":1,"max":10,"mean":5.5,"p50":2,"p95":10,"p99":10}

实现原理与源码

项目采用零第三方运行依赖的ES模块。validated函数统一处理输入结构、字段类型、重复标识与数值范围；analyze只保留本项目的一种算法，而不是将无关模式藏在同一个演示入口。结果排序有稳定的标识兜底，同样的记录即使顺序改变也得到同样的JSON结果。输入对象不被修改，便于在脚本或流水线里复用。

exportconstMETA={"id":"20261021-002","title":"智能体工具调用批次最近秩耗时分位器","focus":"对导出耗时使用最近秩定义计算P50/P95/P99、最小值、最大值与均值，不估计未观测请求"};exportconstCFG={"kind":"quantile","metric":"callMs","time":"calledMs","ref":"toolId","lane":"executor","start":"startedMs","end":"finishedMs"};exportconstSCHEMA={"id":"string","callMs":"number"};exportconstSAMPLE={"records":[{"id":"sample-0","callMs":1},{"id":"sample-1","callMs":2},{"id":"sample-2","callMs":9},{"id":"sample-3","callMs":10}]};functionvalidated(input){if(!input||typeofinput!=='object'||Array.isArray(input)||!Array.isArray(input.records)||input.records.length>10000)thrownewTypeError('输入必须含records数组，最多10000条');constseen=newSet();returninput.records.map(r=>{if(!r||typeofr!=='object'||Array.isArray(r))thrownewTypeError('记录必须是对象');for(const[k,t]ofObject.entries(SCHEMA)){if(typeofr[k]!==t||(t==='string'&&!r[k].trim())||(t==='number'&&(!Number.isFinite(r[k])||r[k]<0)))thrownewTypeError('字段错误：'+k);if(t==='number'&&k.endsWith('Ms')&&!Number.isSafeInteger(r[k]))thrownewRangeError('毫秒必须为安全整数');}if(seen.has(r.id))thrownewRangeError('重复id：'+r.id);seen.add(r.id);returnr;});}exportfunctionanalyze(input){constrows=validated(input),values=rows.map(r=>r[CFG.metric]).sort((a,b)=>a-b),n=values.length;constrank=p=>n?values[Math.max(0,Math.ceil(p*n)-1)]:null;return{count:n,metric:CFG.metric,definition:'nearest-rank',min:n?values[0]:null,max:n?values[n-1]:null,mean:n?values.reduce((a,b)=>a+b,0)/n:null,p50:rank(.5),p95:rank(.95),p99:rank(.99)};}

运行步骤与实际测试

需要Node.js 18+。进入project文件夹，执行npm test运行node --test，执行npm run report生成dist/report.json与dist/report.html。网页使用python3 -m http.server 8080启动静态服务，然后访问http://localhost:8080并点击“运行分析”。不要直接双击HTML，因为ES模块在file协议下可能受浏览器限制；本地静态服务不需要注册外部账号。

本项目实际执行8项测试全部通过：专用样本的具体数字、边界与空集合口径、错误顶层、缺失字段、字段类型、重复标识、输入不可变，以及记录倒序后的结果一致性。测试文件可以直接打开复查，docs/测试输出.txt保存本次真实命令输出。测试通过只证明这些已覆盖场景，不代表生产日志已经核验。新增规则时应该先补一个会失败的反例，再修改实现，避免功能描述先于真实代码。

真实运行截图说明

完成本地服务启动后，浏览器打开项目，点击“运行分析”，逐项比对结果与dist/report.json，然后保存screenshots/运行效果.jpg。截图同时展示项目编号、输入和结果，浏览器运行回执记录源码与截图的SHA-256。它不是绘制的摘要图，也不是热点产品官方界面；如果源码、样本或算法改变，需要重新测试和捕获，旧截图不再证明新版本。

限制与使用建议

耗时是非负有限数；P值取排序后ceil(p*n)-1下标，不插值。空集合所有统计为null。本项目只做离线计算，不读取时钟自动刷新、不联网查询真实父项、不运行真实任务，也不对任何产品的SLA、准确率或生产容量作背书。输入最多10000条，区间两两比较为O(n²)，很大规模应改成扫描线并增加压力测试；分位数需要排序，窗口与引用工具也有显式规模限制。JavaScript浮点数不适合未经设计的高精度账务累计，这里不处理支付或结算。

报告和界面均使用textContent或HTML转义显示输入，避免将用户数据当成可执行HTML；这不是完整安全审计，部署到公网之前仍需设计访问控制和数据保留策略。当前最适合开发、教学及导出预检，不应让示例阈值直接触发业务处罚或生产动作。