用自然语言在选定文件或 JSONL 记录中找原文，沿用 grep 的行、文件、管道和退出码习惯。已知符号、字符串或正则表达式时，直接用 grep／rg；需要按意思找线索时，再用 intentgrep。
intentgrep -rn --context-lines 2 '哪些代码在取消后停止后台工作？' src
intentgrep -n -C 2 '记录数据库迁移决定的内容' notes.md
intentgrep --task filter --input jsonl --json '记录明确描述一次失败部署' records.jsonl它把所选原文交给 TypeSafe Jev 判断，返回原文与评分，不生成答案，不要求先建 embedding 索引或 AST。默认逐行搜索；代码需要邻近行时，用 --context-lines 给模型补充上下文。
包名：@shareai-lab/intentgrep；命令：intentgrep。 当前版本为 0.1.0 预览。源码与完整评估记录在 shareAI-lab/intentgrep。同时保留 jevgrep 兼容命令；npm 上的无 scope 包 jevgrep 是其他项目。
需要 Node.js 22 或更新版本，运行时没有第三方依赖。直接运行固定版本，无需全局安装：
npx --yes --package=@shareai-lab/intentgrep@0.1.0 intentgrep --help先对合成数据做一次离线计划：
printf '%s\n' 'The deployment failed.' 'The deployment succeeded.' | \
npx --yes --package=@shareai-lab/intentgrep@0.1.0 intentgrep \
--plan --task filter --max-requests 8 --max-input-bytes 80000 \
'The line explicitly describes a failed deployment.'计划读取本地输入，展示候选数、请求体字节与判断方式，不需要 API key，也不调用模型。准备好 TYPESAFE_API_KEY 环境变量后，把 --plan 换成 --json，在相同范围执行真实查询。不要把 key 写进命令参数、示例文件或日志。
默认模型固定 jev-1.13.0；--model 可以改动。--base-url／TYPESAFE_BASE_URL 用于兼容端点，支持 HTTPS 或本机 loopback HTTP，不跟随重定向。真实查询会发送所选原文、metadata、模型上下文与额外判断指引。 如果不允许远程处理这些材料，使用离线计划或获准的端点。
长期反复使用的人或 Agent 可以安装到自己的 Node 环境：
npm install -g @shareai-lab/intentgrep@0.1.0
intentgrep --version
intentgrep --help后文为简洁使用 intentgrep；没有全局安装时，继续使用上面的 npx 前缀。团队工具可作为项目依赖固定在 lockfile 中，用 npm script 调用。全局安装不等于给 Node 应用安装 SDK。
需要本地构建时，克隆仓库，运行 npm ci && npm pack，再把 npx 的 --package 改为生成的 .tgz 绝对路径。
形式是 intentgrep [OPTIONS] PATTERN [FILE...]。PATTERN 是非空自然语言查询或条件，不是正则表达式。
- 默认单位是物理行，保留输入文件／记录顺序，不自动带行号或分数。
-n显示行号，--score显示附加评分。 - 单个文件或 stdin 默认不带文件名前缀；多个输入操作数或递归搜索显示文件名。
-H强制显示，-h隐藏；--label给 stdin 命名。 - 目录需要
-r；-r没有文件操作数时搜索当前目录。没有文件操作数且没有-r时读取 stdin；-也表示 stdin，终端输入以 EOF 结束。 -e可重复提供条件，-f从文件逐行读取条件；多条件按 OR 选择。查询文本内的换行也分隔条件。空白条件会报错；空的-f文件不选任何记录，配合-v则选择所有记录，无需模型调用。--结束选项解析，适用于以-开头的查询或文件名。-rn等短选项组合可用。
intentgrep -n '描述请求失败后的重试' client.ts
intentgrep -rnl '定义了取消处理' src
intentgrep -e '描述限流' -e '描述退避重试' client.ts worker.ts
printf '%s\n' 'Retries after a timeout.' | intentgrep --label example '描述重试'| 选项 | 行为 |
|---|---|
-v |
反转阈值选择；不是对相反命题的证明 |
-c |
按文件输出选中单位的数量，包括 0 |
-l / -L |
列出有选中记录／没有选中记录的文件；空文本文件参与判断，跳过的二进制文件不算空文件 |
-q |
不输出，发现首个选中记录后停止继续判断 |
-m N |
每个来源最多选中前 N 个；-m 0 不调用模型，不是取最高分 N 个 |
-A N / -B N / -C N |
输出命中行之后／之前／前后的原文，相邻组会合并 |
-Z |
文件名后使用 NUL 分隔，适合继续传入其他工具 |
-s |
不打印错误信息，错误退出码仍为 2 |
-q 优先于其它输出方式；文件列表优先于计数；JSON／JSONL 不与计数、文件列表或 quiet 混用。输出上下文中，选中行和上下文行分别使用 : 与 - 分隔前缀，不相连的组之间输出 --。普通管道保留原文字符；终端可见输出会处理控制字符，NUL 文件名输出保持真实文件名。
这里没有复用正则模式选项的含义；-E/-F/-P/-i/-w/-x/-o/-R 不受支持，需要精确匹配时使用 grep／rg。
CLI 默认 --task search；SDK 默认 task: 'filter'。 这是两种不同的判断问题：
| task | 模型需要判断什么 | 适合的输入 |
|---|---|---|
search |
这一段是否为调查当前问题提供具体有用的证据，不要求它独自证明整个答案 | 代码、文档、决策记录中的线索 |
filter |
这条记录本身是否满足给定条件 | 要归类或筛选的 JSONL／应用记录 |
寻找“用户是否批准迁移”的证据时，用户的拒绝、延期和撤回也可能是有用结果。若用 filter 问“记录明确包含批准”，它们通常不满足这个条件。任何一种分数都不能把助手提议变成用户确认。
--profile auto|generic|code|docs|memory 调整判断关注点。CLI 默认 auto，只把文件扩展名当作弱提示；SDK 默认 generic。memory 关注说话人、时间和证据状态，code 关注代码证据，显式 profile 覆盖自动选择。它们不会自动加载项目内的提示文件。
可以用 --instructions '额外判断准则' 或 --instructions-file rubric.txt 补充领域规则，二者互斥。它们补充现有任务，不替换整个协议，也不执行代码。-f 与 --instructions-file 的文件输入限 1 MiB、合法 UTF-8 普通文件，拒绝末级符号链接、FIFO 和设备；-f - 仍可显式读取 stdin。例子：
intentgrep --task search --profile memory \
--instructions '批准、延期和撤回都可能是相关证据；保留说话人和时间。' \
'关于数据库迁移，用户作过哪些决定？' decisions.md--layout isolated|shared 用于可复现地比较提示布局。默认 isolated 把每条候选放入自己的问题；shared 把本批候选放入公共 state，问题再指向目标候选。布局会改变请求与效果，需要对目标后端实测，不保证某个布局始终更快或更准。
离线计划的 prompt 字段记录提示版本、task、profile、layout、实际 profiles 以及额外指引的哈希，便于检查这次到底怎么判断。
--context-lines N 把目标行前后的 N 行作为模型输入，帮助理解目标行；默认 0，邻近行不因为附带进入模型就自动算作命中。-A/-B/-C 只增加结果输出中的原文，不改变模型看到的材料。
# 模型看到每个候选两侧 3 行；只输出选中行。
intentgrep -n --context-lines 3 '处理任务取消' worker.ts
# 模型仍只看到目标行；结果另外显示相邻 3 行。
intentgrep -n -C 3 '处理任务取消' worker.ts如需判断一个完整段落或代码窗口，显式选择 --unit paragraph|window|document。window 使用 --lines 12 --overlap 2；这些扩展单位下，文本输出按源行合并，-c 计数仍是选中单位，不能当作不重复的物理行数量。line 模式保留空白行，不把一个长行拆成多个计数单位；超长行会失败，提示改用合适的扩展单位或调整长度限制。
所有本地输入先完整预检，再开始付费请求。即使 -q 已有可能很快命中，未知路径、格式或大小错误也会在模型调用前失败。这是有意保留的差异，不采用 GNU grep 某些场景下“已有匹配盖过输入错误”的退出语义。
模型判断阶段，-q/-l/-m 可以停止后续工作；-L 在某文件出现首个选中记录后可跳过其余记录。已经发出的请求无法保证从远端撤回。JSON 中的 complete: false 与 stopReason: 'match-limit' 表示提前停止；summary.evaluated 是实际判断数，未判断记录不被当作 false。
默认按来源顺序输出。--sort score 按分数排序；--top N 同时使用评分排序并限制返回数，仍需要判断整个候选范围。排名不能与 -q/-l/-L/-c/-m 或输出上下文混用。--sort source 与 --top 也不能一起用。
relevance 是本次问题的模型评分。多条件时，它是各条件评分的最大值，不是经过校准的“至少一个条件成立”的联合概率。默认阈值为 0.6；-v 只反转是否过阈值。低分可能是证据不足或漏判，不意味着相反事实已经成立。
退出码：0 存在选中记录，1 没有选中记录，2 输入、预算、网络或响应失败；--help/--version/--plan 成功返回 0。-L 同样按是否存在选中记录计算退出码，不按是否打印了文件名；只打印无匹配文件名时可能返回 1。SIGINT／SIGTERM 分别返回 130／143。查询错误不输出已完成的小部分结果冒充成功；下游关闭管道不会产生 EPIPE 堆栈。
--json 输出 {schemaVersion, scope, plan, result}；--jsonl 输出 match 行与最终 summary。结果包含原记录、源路径／行号／SHA-256 和评分；result.results 只含已判断记录，保留输入顺序。文件变化后应重新检查，不用旧哈希冒充当前内容。
递归发现包含隐藏文件，--no-hidden 可关闭。支持重复 --include、--exclude、--exclude-dir；glob 只支持 *、**、?，不承诺完整 .gitignore 语义。明显凭据和常见依赖／产物目录仍有可见的范围保护；显式给定的非敏感根不因发现规则被静默跳过。这不是秘密扫描器，普通文件也可能含敏感内容。
发现的 symlink 不遍历，显式末级 symlink 也被拒绝；输入祖先中的目录别名解析后再检查真实路径。跳过项与排除规则在 scope 中可查，不能把省略范围称作“搜索了全部仓库”。
| 限制 | 默认 |
|---|---|
单候选 --chunk-chars |
2000 个 Unicode 码点 |
--max-candidates / --max-files |
500 / 1000 |
--max-file-bytes / --max-bytes |
1 MiB / 10 MiB |
--batch-size / --concurrency |
8 / 4 |
单请求 --max-request-bytes |
24000 字节 |
全查询 --max-requests / --max-input-bytes |
100 次尝试 / 1000000 字节 |
每次 --timeout / 额外 --retries |
30000 ms / 2 |
请求次数与字节包含重试和指引／metadata／模型上下文。提前停止的计划会标记 stopEarly 与 canCompleteWithinBudget；完整扫描计划可能超预算，但实际运行仍逐次强制预算，耗尽时失败。字节不是精确 token 或金额估计；token usage 只累加成功响应，无法知道失败或超时请求的远端收费。
仓库提供 intentgrep 和 intent-memory 两份 Skill。它们是宿主的操作指引，不是 CLI 的子命令；npm 安装也不会通过生命周期脚本安装 Skill。
在要使用 Skill 的项目里运行。skills@1.7.0 本身需要 Node >=22.20.0：
npx --yes skills@1.7.0 add shareAI-lab/intentgrep --list
npx --yes skills@1.7.0 add shareAI-lab/intentgrep \
--skill intentgrep intent-memory --agent codex --copy --yes这使用 Vercel Skills CLI，默认安装到当前项目；跨项目使用时显式加 --global。--skill 在这里属于 Skills 安装器。也可以将仓库名换成本地 checkout 的绝对路径。
Skill 与 CLI 分开准备：长期 Agent 可使用前面的全局安装，团队也可固定项目依赖。宿主根据任务选择精确搜索、读文件或语义搜索，不必每一步都调用 intentgrep。memory Skill 允许把有界检索委派给宿主已有的轻量 Agent，默认至多 3 轮，共用尝试／字节预算；它不会常驻运行、自动写记忆或把评分升级为授权。
应用先依据调用者身份从自己的数据库挑选获准记录，再调用查询核心。SDK 只是同一包的 @shareai-lab/intentgrep/sdk 子路径；不需要第二个包，也不连接数据库或替代业务认证。
npm install --save-exact @shareai-lab/intentgrep@0.1.0import { JevClient, planQuery, queryRecords } from '@shareai-lab/intentgrep/sdk';
const records = [
{ id: 'r1', text: 'The deployment exited with code 1 before changing production.' },
{ id: 'r2', text: 'The deployment finished successfully.' }
];
const predicate = 'The record explicitly describes a failed deployment';
const options = { task: 'filter', maxRequests: 8, maxInputBytes: 80000 };
console.log(planQuery(records, predicate, options));
// Actual query requires TYPESAFE_API_KEY in the server environment.
const result = await queryRecords(new JevClient(), records, predicate, options);
console.log(result.matches);SDK 默认 filter/generic/isolated，而 CLI 默认 search/auto/isolated；调查问题时显式选择 task: 'search'。instructions 提供额外判断准则；SDK 的 context 提供共享背景，记录的 context.before/after 可提供邻近原文。
checks 为每条记录增加独立 filter 判断，即使主 task 是 search，也不会把这些检查改为线索搜索。它们不自动排除记录，由调用者解释并验证。queryRecords 接受多个 OR 条件、AbortSignal 与 Evaluator，共享 CLI 的分批和预算；自定义 evaluator 如有重试，必须在每次尝试前调用 beforeAttempt。
examples/sdk.mjs 演示寻找记忆证据与附加检查，默认只打印计划；显式 --live 才请求模型。低层 JevClient.evaluate() 可使用 typed questions，但不是入门必需，也不承诺替代官方 TypeSafe SDK 的全部能力。
每行是 {id?, text, metadata?}；--text-field 可改文本字段。JSONL 的一个对象是一个语义记录，物理文件行只用于来源定位。metadata 同样进入模型，应用须先完成访问范围过滤。
生产流水线可在部署时将固定版本安装到自己的工具目录，随后直接调用固定 bin，不必每个请求都经 npx 获取包：
npm install --prefix .intentgrep-tools --save-exact @shareai-lab/intentgrep@0.1.0import json
import subprocess
records = [{"id": "r1", "text": "The deployment exited with code 1."}]
proc = subprocess.run(
[".intentgrep-tools/node_modules/.bin/intentgrep", "--plan", "--task", "filter",
"--input", "jsonl", "--max-requests", "8", "--max-input-bytes", "80000",
"The record explicitly describes a failed deployment"],
input="".join(json.dumps(row) + "\n" for row in records),
text=True, capture_output=True, timeout=150,
)
if proc.returncode not in (0, 1):
raise RuntimeError(proc.stderr)
result = json.loads(proc.stdout)示例先运行计划；把 --plan 换成 --json 才是实际查询。真实查询的退出码 1 仍是有效 JSON 的无匹配结果，不能与错误混淆。传参数数组而非拼接 shell 字符串；API key 通过进程环境继承。完整可运行例子见 examples/python_pipeline.py，当前不另发 Python SDK。
npm test
npm run check
node examples/sdk.mjs
python3 examples/python_pipeline.py2026-09-22 使用官方 jev-1.13.0 实测：100/100 确定性测试、28/28 CLI 场景通过。三个 Agent 独立设计并交叉审查代码、文档／日志／业务、记忆场景：开发集两轮 179/180，独立留出集两轮 174/180；附加 checks 共 110/110。重复运行不增加独立样本数，模型判断仍有错误。
新版提示词把直接问题与候选放在一起，避免主查询进入独立 checks 的共享背景。仍需注意：调用重试函数可能被误认成定义重试循环；dry-run、审批和计划可能被误认成实际完成。前者应明确要求候选自身包含什么实现，后者应先用代码过滤固定 metadata 字段，再做语义判断。metadata 流水线示例 默认离线，--live 才调用模型。
完整方案、保留的失败、对照实验、成本和复现方式见 官方评估记录。这是合成场景评估，不是生产准确率或全语言保证；确定性测试验证输入输出和预算，不能替代模型质量测试。
历史上使用 Qwen3.5-4B 复现服务的 smoke 曾发现高置信误命中，以及共享 state 带来的重复输入开销；这些是旧提示与旧窗口设置的诊断，不是当前默认布局的性能或精度结论。
类型约束不保证判断正确。结果可能受上下文不足、提示注入、漏判或误判影响；不要以分数授予访问权、批准外部动作或替代原文核验。工具只处理 UTF-8 文本和 JSONL，没有 PDF／Office 解析、持久索引或缓存。大量重复检索可先建索引召回候选，再交给同一查询核心判断。