Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { basenameRemotePath } from './filePreview.js';
/**
* 命令「意图」解析(issue #450 codex 人话摘要)。
*
* Claude Code 的 Bash 有模型自写的 `description`,codex 的 shell 工具 schema
* 没有等价字段 —— 本模块用两条**纯代码确定性**路径(规则 9)为 command 描述符
* 补上结构化意图,供各端渲染成「读取 index.ts」「搜索 "logger"」这类人话:
*
* 1. `commandIntentFromActions`:消费 codex app-server v2 CommandExecution 自带的
* `commandActions`(codex 侧 parse_command 的确定性产物,read / listFiles /
* search / unknown 四类)。
* 2. `commandIntentFromCommand`:本地规则表解析命令原文,兜底 codex 的 unknown
* 命令与 Claude 漏填 description 的场景。
*
* 安全不变量(review 逐条钉死的口径):**有副作用的命令绝不能被贴上无害的
* 人话动词**(「读取 / 搜索 / 列出」),必须回退原文可见。所有形态级安全检查
* 统一收在 `analyzeCommandShape`:非展示型管道尾(tee / xargs …)、写文件重定向
* (含紧贴形态 `a>b`)、子命令替换 / heredoc,任一命中即整体放弃解析。
* `&&` / `||` / `;` / 换行只在每一段都能独立通过同一道闸、且属于明确的同类
* 动作时才归纳;后台 `&` 仍整体拒绝。`commandActions` 路径在采纳任何 action 前也
* 必须先过同一道闸(防止「首个 action 无害、后段有副作用」的组合绕过),并
* 对 read / search / listFiles action 各自再做语义门控(executable-read、
* sed 就地编辑、破坏性 find)。`rm` 等破坏性命令**刻意不进规则表**。
*
* 与 toolUseDescriptor 一致:只输出结构化数据,不拼面向用户的句子;任意残缺
* 输入不抛异常。
*/
// ── 类型 ─────────────────────────────────────────────────────────────────────
export type CommandIntentAction =
| 'read'
| 'list'
| 'search'
| 'inspect'
| 'inspectRepository'
| 'inspectEnvironment'
| 'modifyRepository'
| 'verify'
| 'fetch'
| 'install'
| 'test'
| 'build'
| 'lint'
| 'typecheck'
| 'runScript'
| 'runNodeScript'
| 'runPythonScript'
| 'runPerlScript'
| 'runSwiftScript'
| 'checkSyntax'
| 'showVersion'
| 'checkFormatting'
| 'parseJson'
| 'count'
| 'showCurrentDirectory'
| 'showDateTime'
| 'locateCommand'
| 'inspectProcesses'
| 'inspectPorts'
| 'queryDatabase'
| 'gitStatus'
| 'gitDiff'
| 'gitLog'
| 'gitShow'
| 'gitAdd'
| 'gitCommit'
| 'gitFetch'
| 'gitPull'
| 'gitPush'
| 'gitRebase'
| 'gitMerge'
| 'gitCherryPick'
| 'gitStash'
| 'gitRestore'
| 'gitSubmodule'
| 'gitRemote'
| 'gitRevParse'
| 'gitBranch'
| 'gitGrep'
| 'gitMergeBase'
| 'gitLsFiles'
| 'gitRevList'
| 'gitLsRemote'
| 'gitWorktreeList'
| 'gitWorktreeAdd'
| 'gitWorktreeRemove'
| 'gitWorktreeMove'
| 'gitWorktreePrune'
| 'ghPrList'
| 'ghPrView'
| 'ghPrChecks'
| 'ghPrStatus'
| 'ghPrDiff'
| 'ghPrCreate'
| 'ghPrEdit'
| 'ghPrComment'
| 'ghPrReview'
| 'ghPrMerge'
| 'ghPrClose'
| 'ghPrReopen'
| 'ghPrCheckout'
| 'ghIssueList'
| 'ghIssueView'
| 'ghIssueStatus'
| 'ghIssueCreate'
| 'ghIssueEdit'
| 'ghIssueComment'
| 'ghIssueClose'
| 'ghIssueReopen'
| 'ghAuthStatus'
| 'ghAuthLogin'
| 'ghAuthLogout'
| 'ghAuthRefresh'
| 'ghAuthSwitch'
| 'ghRunList'
| 'ghRunView'
| 'ghRunWatch'
| 'ghSearch'
| 'ghRepoList'
| 'ghRepoView'
| 'ghApiQuery'
| 'ghApiMutation'
| 'ghApiCall';
export interface CommandIntent {
action: CommandIntentAction;
/** 意图参数(文件名 / 搜索词 / URL / 包名等);缺省时消费端回退命令原文。 */
target?: string;
/** 作用范围路径(读取的完整路径 / 搜索目录),只进 hover 细节不进主文案。 */
path?: string;
}
/**
* tokenize 产物:text 已去引号;unquotedMeta 标记 token 是否含**未引号**的
* shell 元字符(< / > / ()。按字符粒度记录,`cat a>"b"`(未引号 > + 引号
* 目标)与 `rg ">" src`(元字符整体在引号里)才能被正确区分 —— token 级
* 「是否带引号」布尔分不清这两种形态。
*/
interface ShellWord {
text: string;
unquotedMeta: boolean;
/** token 是否含引号部分 —— `>"&2"` 里被引号的 `&2` 是文件名而非 fd 复制。 */
hasQuoted: boolean;
}
// ── codex commandActions → intent ────────────────────────────────────────────
/** read action 门控:action.command 的首 token 必须是这些已知读文件命令。 */
const READ_COMMAND_BINS = new Set(['cat', 'head', 'tail', 'less', 'more', 'sed', 'bat', 'nl']);
/**
* find 的副作用 action 家族 —— 命中即不解析,保持原文可见(与 rm / sed -i 同理)。
* 除执行/删除类外,-fprint 家族(-fprint / -fprint0 / -fprintf / -fls)会
* 创建/截断输出文件,同样不能贴「搜索」动词。
*/
const FIND_DESTRUCTIVE_FLAGS = new Set([
'-exec', '-execdir', '-ok', '-okdir', '-delete',
'-fprint', '-fprint0', '-fprintf', '-fls',
]);
/**
* 解析 codex `commandActions`(v2 协议 CommandAction[],serde camelCase tag:
* read / listFiles / search / unknown)。保留所有可安全展示的结构化动作,
* 供工作过程按动作拆行;单行摘要入口再取第一个主意图。
*
* 传入 `fullCommand` 时(describeToolUse 的 exec 路径总是传),先对完整命令
* 过 `analyzeCommandShape` 形态闸:`cat a | tee b` 这类首个 action 无害、
* 后段有副作用的组合会被整体拒绝,不给 commandActions 绕过本地检查的机会。
*
* 单个 action 也不盲信:
* - read:codex 在某些路径(如 zsh-fork 审批)会给**被执行的二进制**也报
* `Read { name: "rm" }`,要求 action.command 首 token 是已知读文件命令
* (sed 另须只读形态)才接受;
* - search / listFiles:codex 会把 `find … -delete/-exec` 的 -name 过滤归类
* 成 search,对 action.command 做破坏性 find 检查。
*/
export function commandIntentsFromActions(raw: unknown, fullCommand?: string): CommandIntent[] {
if (!Array.isArray(raw)) return [];
const intents: CommandIntent[] = [];
for (const entry of raw) {
if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
const action = entry as Record<string, unknown>;
switch (action.type) {
case 'read': {
if (!isKnownReadCommand(readNonEmptyString(action.command))) continue;
const path = readNonEmptyString(action.path);
const name = readNonEmptyString(action.name) ?? (path ? basenameRemotePath(path) : undefined);
if (!name) continue;
intents.push({ action: 'read', target: name, ...(path ? { path } : {}) });
break;
}
case 'listFiles': {
if (searchCommandHasSideEffects(readNonEmptyString(action.command))) continue;
const path = readNonEmptyString(action.path);
intents.push({ action: 'list', ...(path ? { target: path } : {}) });
break;
}
case 'search': {
if (searchCommandHasSideEffects(readNonEmptyString(action.command))) continue;
const query = readNonEmptyString(action.query);
const path = readNonEmptyString(action.path);
if (query) {
intents.push({ action: 'search', target: query, ...(path ? { path } : {}) });
} else if (path) {
intents.push({ action: 'search', target: path });
}
break;
}
default:
continue;
}
}
if (
fullCommand !== undefined
&& analyzeCommandShape(fullCommand) === undefined
&& !structuredActionsMatchSafeComposite(fullCommand, intents)
) {
return [];
}
return intents;
}
/**
* `analyzeCommandShape` deliberately rejects top-level command chains. For
* multi-row presentation, allow the narrow subset whose complete local parse
* proves that every sequential branch is read/list/search. `||` remains
* rejected because only one branch may actually execute.
*/
function structuredActionsMatchSafeComposite(
fullCommand: string,
intents: readonly CommandIntent[],
): boolean {
if (intents.length === 0 || fullCommand.includes('||')) return false;
if (!intents.every((intent) => (
intent.action === 'read' || intent.action === 'list' || intent.action === 'search'
))) {
return false;
}
const composite = commandIntentFromCompositeCommand(fullCommand);
return composite?.action === 'inspect'
|| composite?.action === 'read'
|| composite?.action === 'list'
|| composite?.action === 'search';
}
/**
* 单行命令摘要的兼容入口。需要逐动作展示的消费方调用
* `commandIntentsFromActions`;既有调用方继续只取第一个主意图。
*/
export function commandIntentFromActions(raw: unknown, fullCommand?: string): CommandIntent | undefined {
return commandIntentsFromActions(raw, fullCommand)[0];
}
// ── 命令原文 → intent(本地规则表) ──────────────────────────────────────────
/** 管道尾段允许的纯展示型过滤器;出现其它命令(如 tee / xargs)就放弃解析。 */
const PIPE_FILTERS = new Set([
'head', 'tail', 'wc', 'sort', 'uniq', 'less', 'more', 'cat', 'column', 'nl', 'sed',
'cut', 'tr', 'grep', 'egrep', 'fgrep', 'rg',
]);
const PIPE_SEARCH_FILTERS = new Set(['grep', 'egrep', 'fgrep', 'rg']);
const CUT_VALUE_FLAGS = new Set([
'-b', '-c', '-d', '-f',
'--bytes', '--characters', '--delimiter', '--fields', '--output-delimiter',
]);
/**
* 单条命令长度上限。Git add 文件清单与 gh GraphQL 查询经常超过 1k;8k 仍能
* 在线性 tokenizer 内低成本处理,同时把真正的大段内联脚本留在原文回退。
*/
const COMMAND_MAX_CHARS = 8192;
/**
* 形态安全分析:整条命令通过全部检查时返回首段 argv(已去引号、剥 env/sudo
* 前缀与无害重定向),任何不安全 / 解析不了的形态返回 undefined。
*
* 检查项:
* - 子命令替换($( / 反引号)、heredoc、多行、`||` 分支 → 放弃;
* - 顶层命令链(&& / ; / 后台 `&`)→ 剥掉前导 cd 后仍多于一段就放弃
* (`cat foo & rm -rf bar` 不能渲染成「读取 foo」);
* - 管道尾段必须全是展示型过滤器,且每段同样过写文件重定向检查;
* - 首段命中写文件重定向(含紧贴形态 `a>b`)→ 放弃。
*/
function analyzeCommandShape(command: string): string[] | undefined {
if (typeof command !== 'string') return undefined;
const trimmed = command.trim();
if (!trimmed || trimmed.length > COMMAND_MAX_CHARS) return undefined;
if (/[`\n]|\$\(|<</.test(trimmed)) return undefined;
const chain = splitTopLevel(trimmed, ['&&', ';', '&']);
if (chain === undefined) return undefined;
// 剥掉前导的 cd(agent 常见形态:cd <dir> && <真实命令>)。丢弃前必须
// 验证该段真的只是 `cd <dir>` —— `cd repo > touched && cat a` 的 cd 段
// 带写文件重定向,不能无检查跳过。
while (chain.length > 1 && /^cd(\s|$)/.test(chain[0])) {
if (!isCleanCdSegment(chain[0])) return undefined;
chain.shift();
}
if (chain.length !== 1) return undefined;
const pipeline = splitTopLevel(chain[0], ['|']);
if (pipeline === undefined || pipeline.length === 0) return undefined;
for (let index = 1; index < pipeline.length; index += 1) {
const tailWords = tokenize(pipeline[index]);
if (!tailWords || tailWords.length === 0) return undefined;
// 尾段同样过副作用检查:`| head -5 > out` 的写文件重定向不能藏进管道尾。
const tail = stripPrefixTokens(tailWords);
if (!tail || tail.length === 0) return undefined;
const tailBin = binaryName(tail[0]);
if (!PIPE_FILTERS.has(tailBin)) return undefined;
if (tailBin === 'sed') {
if (!sedPipelineFilterIsReadOnly(tail.slice(1))) return undefined;
continue;
}
if (PIPE_SEARCH_FILTERS.has(tailBin)) {
// grep/rg 只允许真正消费 stdin 的纯搜索形态。带路径会改读其它文件,
// --files / --pre 等形态也不能被当成首段命令的展示过滤器。
const filterIntent = grepIntent(tail.slice(1));
if (
filterIntent?.action !== 'search' ||
filterIntent.path ||
searchCommandHasSideEffects(pipeline[index])
) {
return undefined;
}
continue;
}
if (tailBin === 'cut') {
// cut 允许额外 file operand;管道摘要只接受消费 stdin 的形态,避免
// `cat a | cut -f1 b` 被误写成只读取 a。写重定向已由 stripPrefixTokens 拦截。
if (positionals(tail.slice(1), CUT_VALUE_FLAGS).length > 0) return undefined;
continue;
}
// tr 的 positional 都是字符集,不接受输入文件,只会转换 stdin → stdout。
if (tailBin === 'tr') continue;
// 白名单过滤器自身的写文件形态也要拒:sort -o FILE / uniq IN OUT。
// 展示型过滤器在管道里正常不接文件参数,positional 只放行行数类数字
// (head -n 50 / tail -n +10);-o / --output 一律拒(column -o 是分隔符,
// 误杀代价只是回退原文)。
const tailRest = tail.slice(1);
// 大小写不敏感匹配:sort -o、less -o/-O(--log-file/--LOG-FILE)都写文件。
if (
tailRest.some((token) => {
const lower = token.toLowerCase();
return lower.startsWith('-o') || lower.startsWith('--output') || lower.startsWith('--log-file');
})
) {
return undefined;
}
if (positionals(tailRest, new Set(['-n', '-c'])).some((token) => !/^[+-]?\d+$/.test(token))) {
return undefined;
}
}
const words = tokenize(pipeline[0]);
if (!words || words.length === 0) return undefined;
const argv = stripPrefixTokens(words);
if (!argv || argv.length === 0) return undefined;
return argv;
}
const COMPOSITE_CONTENT_ACTIONS = new Set<CommandIntentAction>([
'read', 'list', 'search', 'parseJson', 'count',
]);
const COMPOSITE_REPOSITORY_ACTIONS = new Set<CommandIntentAction>([
'gitStatus', 'gitDiff', 'gitLog', 'gitShow', 'gitRemote', 'gitRevParse', 'gitBranch',
'gitGrep', 'gitMergeBase', 'gitLsFiles', 'gitRevList', 'gitLsRemote', 'gitWorktreeList',
'ghPrList', 'ghPrView', 'ghPrChecks', 'ghPrStatus', 'ghPrDiff',
'ghIssueList', 'ghIssueView', 'ghIssueStatus', 'ghAuthStatus',
'ghRunList', 'ghRunView', 'ghRunWatch', 'ghSearch', 'ghRepoList', 'ghRepoView', 'ghApiQuery',
]);
const COMPOSITE_REPOSITORY_MUTATION_ACTIONS = new Set<CommandIntentAction>([
'gitAdd', 'gitCommit', 'gitFetch', 'gitPull', 'gitPush',
'gitRebase', 'gitMerge', 'gitCherryPick', 'gitStash', 'gitRestore', 'gitSubmodule',
'gitWorktreeAdd', 'gitWorktreeRemove', 'gitWorktreeMove', 'gitWorktreePrune',
]);
const COMPOSITE_ENVIRONMENT_ACTIONS = new Set<CommandIntentAction>([
'inspectEnvironment', 'showVersion', 'locateCommand', 'ghAuthStatus',
]);
const COMPOSITE_VERIFICATION_ACTIONS = new Set<CommandIntentAction>([
'test', 'build', 'lint', 'typecheck', 'checkSyntax', 'checkFormatting',
]);
function isCleanCdSegment(segment: string): boolean {
const words = tokenize(segment);
if (!words) return false;
const argv = stripPrefixTokens(words);
return !!argv && argv.length <= 2 && binaryName(argv[0] ?? '') === 'cd';
}
function sameIntent(left: CommandIntent, right: CommandIntent): boolean {
return left.action === right.action && left.target === right.target && left.path === right.path;
}
/** 顶层单 `&` 会把命令放到后台;不能把前半段当成整条命令的摘要。 */
function hasTopLevelBackgroundOperator(input: string): boolean {
let quote: '"' | "'" | null = null;
for (let index = 0; index < input.length; index += 1) {
const ch = input[index];
if (quote) {
if (ch === quote && (quote !== '"' || input[index - 1] !== '\\')) quote = null;
continue;
}
if (ch === '\\' && input[index + 1] !== undefined) {
index += 1;
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
continue;
}
if (
ch === '&' &&
input[index - 1] !== '&' &&
input[index + 1] !== '&' &&
input[index - 1] !== '>' &&
input[index + 1] !== '>'
) {
return true;
}
}
return false;
}
/** echo / printf / true 只给复合检查排版或吞掉非零退出码,不改变主意图。 */
function isCompositePresentationSegment(segment: string): boolean {
const argv = analyzeCommandShape(segment);
if (!argv || argv.length === 0) return false;
const bin = binaryName(argv[0]);
if (bin === 'true' || bin === 'echo') return true;
return bin === 'printf' && !argv.slice(1).some((token) => token === '-v' || token.startsWith('-v'));
}
/**
* Codex 常把一次查阅拆成 `rg ... && sed ... && sed ...`。每一段都先走单命令
* 解析与副作用闸;只有整组落在同一类可归纳动作时才返回友好摘要。任一段未知、
* 写盘或无法准确描述,整条链仍回退「运行命令」,不拿首段掩盖后续动作。
* `;` / 换行 / `||` 只有在每一支都能识别时才接受;mutation 只归纳成诚实的
* 「修改仓库」,不会贴「检查仓库」这类只读标签。
*/
function commandIntentFromCompositeCommand(command: string): CommandIntent | undefined {
if (typeof command !== 'string') return undefined;
const trimmed = command.trim();
if (!trimmed || trimmed.length > COMMAND_MAX_CHARS) return undefined;
if (/[`]|\$\(|<</.test(trimmed) || hasTopLevelBackgroundOperator(trimmed)) return undefined;
const chain = splitTopLevel(trimmed, ['&&', '||', ';', '\n']);
if (!chain || chain.length < 2) return undefined;
while (chain.length > 1 && /^cd(\s|$)/.test(chain[0])) {
if (!isCleanCdSegment(chain[0])) return undefined;
chain.shift();
}
if (chain.length < 2) return undefined;
const resolved: CommandIntent[] = [];
for (const segment of chain) {
if (isCompositePresentationSegment(segment)) continue;
const intent = commandIntentFromSingleCommand(segment);
if (!intent) return undefined;
resolved.push(intent);
}
if (resolved.length === 0) return undefined;
// pwd 常作为后续检查的上下文前导;有真实动作时不让它稀释摘要。
const meaningful = resolved.length > 1
? resolved.filter((intent) => intent.action !== 'showCurrentDirectory')
: resolved;
if (meaningful.length === 0) return resolved[0];
if (meaningful.length === 1) return meaningful[0];
const hasRepositoryMutation = meaningful.some((intent) =>
COMPOSITE_REPOSITORY_MUTATION_ACTIONS.has(intent.action));
if (
hasRepositoryMutation &&
meaningful.every((intent) =>
COMPOSITE_REPOSITORY_ACTIONS.has(intent.action) ||
COMPOSITE_REPOSITORY_MUTATION_ACTIONS.has(intent.action))
) {
return { action: 'modifyRepository' };
}
const groups: Array<[ReadonlySet<CommandIntentAction>, CommandIntentAction]> = [
[COMPOSITE_CONTENT_ACTIONS, 'inspect'],
[COMPOSITE_REPOSITORY_ACTIONS, 'inspectRepository'],
[COMPOSITE_ENVIRONMENT_ACTIONS, 'inspectEnvironment'],
[COMPOSITE_VERIFICATION_ACTIONS, 'verify'],
];
const summary = groups.find(([actions]) => meaningful.every((intent) => actions.has(intent.action)));
if (!summary) return undefined;
const first = meaningful[0];
if (meaningful.every((intent) => sameIntent(first, intent))) return first;
// 多个不同搜索词仍可准确概括为「搜索」,无需泛化成「查阅内容」。
if (meaningful.every((intent) => intent.action === 'search')) return { action: 'search' };
return { action: summary[1] };
}
/**
* 从命令原文解析意图。可靠性优先:形态安全检查见 `analyzeCommandShape`;
* 通过后按首段 argv 的二进制名走规则表,握不准一律返回 undefined 回退原文。
*/
export function commandIntentFromCommand(command: string): CommandIntent | undefined {
return commandIntentFromCompositeCommand(command) ?? commandIntentFromSingleCommand(command);
}
function commandIntentFromSingleCommand(command: string): CommandIntent | undefined {
const argv = typeof command === 'string' ? analyzeCommandShape(command) : undefined;
if (!argv) return undefined;
const bin = binaryName(argv[0]);
const rest = argv.slice(1);
if (/^python(?:\d+(?:\.\d+)?)?$/.test(bin)) return pythonIntent(rest);
switch (bin) {
case 'cat': {
const file = positionals(rest, new Set([]))[0];
if (!file) return undefined;
return { action: 'read', target: basenameRemotePath(file) || file, path: file };
}
case 'less':
case 'more': {
// less 的 + 启动命令可执行 shell / 写文件(`less '+!touch x' f` /
// `+s`),含 + 参数一律拒。
if (rest.some((token) => token.startsWith('+'))) return undefined;
const file = positionals(rest, new Set([]))[0];
if (!file) return undefined;
return { action: 'read', target: basenameRemotePath(file) || file, path: file };
}
case 'head':
case 'tail': {
// head/tail 的 -n/-c 是取值型(`head -n 50 file`);cat 的 -n 是布尔,分开处理。
const file = positionals(rest, new Set(['-n', '-c']))[0];
if (!file) return undefined;
return { action: 'read', target: basenameRemotePath(file) || file, path: file };
}
case 'nl': {
const file = positionals(rest, NL_VALUE_FLAGS)[0];
if (!file) return undefined;
return { action: 'read', target: basenameRemotePath(file) || file, path: file };
}
case 'sed': {
// 只认只读形态 `sed -n '<range>p' <file>`(agent 常用来看文件片段);
// -i / --in-place 的就地编辑不解析,保持原文可见。
if (!sedTokensAreReadOnly(rest)) return undefined;
const pos = positionals(rest, new Set(['-e']));
const file = pos[1];
if (!file) return undefined;
return { action: 'read', target: basenameRemotePath(file) || file, path: file };
}
case 'ls':
case 'tree': {
// tree 的 -o FILE 输出到文件、-R 写 00Tree.html;短 flag 可能捆绑,
// 含 o/R 字符即拒(--noreport 被误杀的代价只是回退原文)。ls 不受影响。
if (bin === 'tree' && rest.some((token) => token.startsWith('-') && /[oR]/.test(token))) {
return undefined;
}
// tree 的 -L(层数)/--filelimit 是取值型,别把值当路径。
const pos = positionals(rest, bin === 'tree' ? new Set(['-L', '--filelimit']) : new Set([]));
return { action: 'list', ...(pos[0] ? { target: pos[0] } : {}) };
}
case 'grep':
case 'egrep':
case 'fgrep':
case 'rg':
case 'ag':
return grepIntent(rest);
case 'find': {
// -exec / -delete 家族是破坏性形态,与 rm / sed -i 同理刻意不解析,
// 保持原文可见,不贴无害的「搜索」动词。
if (rest.some((token) => FIND_DESTRUCTIVE_FLAGS.has(token))) {
return undefined;
}
const nameIndex = rest.findIndex((token) => token === '-name' || token === '-iname');
const pattern = nameIndex >= 0 ? rest[nameIndex + 1] : undefined;
const path = rest[0] && !rest[0].startsWith('-') ? rest[0] : undefined;
if (!pattern) return { action: 'list', ...(path ? { target: path } : {}) };
return { action: 'search', target: pattern, ...(path ? { path } : {}) };
}
case 'fd': {
// -x/--exec 会对每个结果执行命令(`fd '*.tmp' . -x rm {}`),不解析。
if (rest.some((token) => hasFdExecFlag(token))) return undefined;
const pos = positionals(rest, new Set(['-e', '-t', '-E', '--extension', '--type', '--exclude']));
if (!pos[0]) return undefined;
return { action: 'search', target: pos[0], ...(pos[1] ? { path: pos[1] } : {}) };
}
case 'curl': {
// 写盘 / 变更类 flag(-o/-O 输出文件、-X/-d/-F 非只读请求)不能只
// 渲染成「访问 <url>」,回退原文。wget 不在此列:它默认就把响应写成
// 本地文件,裸 wget 也不解析(见 default 分支)。
if (hasMutatingCurlFlag(rest)) return undefined;
const url = rest.find((token) => /^https?:\/\//.test(token));
if (!url) return undefined;
return { action: 'fetch', target: url };
}
case 'node':
return nodeIntent(rest);
case 'perl':
return perlIntent(rest);
case 'swiftc':
return swiftCompilerIntent(rest);
case 'swift':
return swiftIntent(rest);
case 'xcrun':
return xcrunIntent(rest);
case 'jq':
return jqIntent(rest);
case 'wc':
return countIntent(rest);
case 'pwd':
return rest.every((token) => ['-L', '-P', '--logical', '--physical'].includes(token))
? { action: 'showCurrentDirectory' }
: undefined;
case 'date':
return dateIntent(rest);
case 'command':
return locateCommandIntent(rest);
case 'which': {
const targets = positionals(rest, new Set([]));
return targets[0] ? { action: 'locateCommand', target: targets.join(' ') } : undefined;
}
case 'ps':
case 'pgrep':
return { action: 'inspectProcesses' };
case 'lsof':
return lsofIntent(rest);
case 'sqlite3':
return sqliteIntent(rest);
case 'test':
return { action: 'inspectEnvironment' };
case '[':
return rest.at(-1) === ']' ? { action: 'inspectEnvironment' } : undefined;
case 'stat':
case 'du':
return { action: 'inspect' };
case 'file':
// file -C / --compile 会在当前目录生成 magic.mgc,不是纯检查。
return rest.some((token) => token === '-C' || token === '--compile')
? undefined
: { action: 'inspect' };
case 'plutil':
return plutilIntent(rest);
case 'defaults':
return rest[0] === 'read' ? { action: 'inspectEnvironment' } : undefined;
case 'tailscale':
return rest[0] === 'status' ? { action: 'inspectEnvironment' } : undefined;
case 'git':
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'Git' };
return gitIntent(rest);
case 'gh':
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'GitHub CLI' };
return githubCliIntent(rest);
case 'pnpm':
case 'npm':
case 'yarn':
case 'bun':
return packageManagerIntent(bin, rest);
case 'npx':
case 'pnpx':
case 'bunx': {
const tool = positionals(rest, new Set([]))[0];
return tool ? toolBinaryIntent(tool, argsAfter(rest, tool)) : undefined;
}
case 'make': {
// GNU make 会执行**全部** target,多 target(make test deploy)只标
// 首个会隐藏后续动作,回退原文。
const goals = positionals(rest, new Set(['-C', '-j', '-f']));
if (goals.length === 0) return { action: 'build' };
if (goals.length > 1) return undefined;
return scriptIntent(goals[0]);
}
case 'cargo':
return cargoIntent(rest[0], rest.slice(1));
case 'go': {
if (rest[0] === 'test') {
// -c 只编译不跑、-o 写测试二进制,不能标「运行测试」。
if (rest.some((token) => token === '-c' || token === '-o' || token.startsWith('-o='))) {
return undefined;
}
return { action: 'test' };
}
if (rest[0] === 'build') return { action: 'build' };
if (rest[0] === 'vet') return { action: 'lint' };
return undefined;
}
default:
return toolBinaryIntent(bin, rest);
}
}
// ── 各命令族的意图规则 ───────────────────────────────────────────────────────
/**
* curl 的写盘 / 变更类长 flag 前缀(startsWith 匹配,覆盖 `--data-raw` /
* `--form-string` 等派生形态;前缀命中偏保守,代价只是回退原文)。
*/
const CURL_MUTATING_LONG_FLAGS = [
'--output', '--remote-name', '--request', '--data', '--form', '--upload-file', '--json',
'--dump-header', '--cookie-jar', '--trace', '--stderr', '--config', '--etag-save', '--libcurl',
'--alt-svc', '--hsts', '--write-out',
];
/**
* curl 写盘 / 变更类短选项字符(大小写敏感)。o/O 写响应文件,X 改方法,
* d/F/T 非只读请求,D dump-header 写文件,c cookie-jar 写文件,
* K 从配置文件读参数(可注入 output= / -O 等任意写盘选项,静态不可判定),
* w write-out 可经 %output{FILE} 写文件。
*/
const CURL_MUTATING_SHORT_CHARS = new Set(['o', 'O', 'X', 'd', 'F', 'T', 'D', 'c', 'K', 'w']);
/**
* curl 变更形态判定。短选项必须**拆字符**查:curl 允许捆绑短选项,写盘的
* -O 常见于 `curl -sO` / `curl -fsSLO`,整体 startsWith 会漏掉捆绑在其它
* flag 之后的写盘字符。`-XPOST` / `-d@file` 这类带值紧贴形态由前缀分支兜住。
*/
function hasMutatingCurlFlag(rest: string[]): boolean {
return rest.some((token) => {
if (CURL_MUTATING_LONG_FLAGS.some((flag) => token.startsWith(flag))) return true;
// 短选项捆绑可混非字母字符(`-#O`),对整个短 token 逐字符扫描;
// 附带值形态(`-XPOST` / `-AMozilla`)的值字符也会命中 —— 偏保守,
// 误杀代价只是回退原文。
if (token.startsWith('-') && !token.startsWith('--')) {
return [...token.slice(1)].some((ch) => CURL_MUTATING_SHORT_CHARS.has(ch));
}
return false;
});
}
/** nl options whose value may be passed as the following argv token. */
const NL_VALUE_FLAGS = new Set([
'-b', '-d', '-f', '-h', '-i', '-l', '-n', '-s', '-v', '-w',
'--body-numbering', '--section-delimiter', '--footer-numbering', '--header-numbering',
'--line-increment', '--join-blank-lines', '--number-format', '--number-separator',
'--starting-line-number', '--number-width',
]);
function isVersionRequest(rest: string[]): boolean {
return rest.length === 1 && (rest[0] === '-v' || rest[0] === '--version' || rest[0] === '-V');
}
const NODE_VALUE_FLAGS = new Set([
'-r', '--require', '--import', '--loader', '--experimental-loader', '--conditions', '-C',
]);
function nodeIntent(rest: string[]): CommandIntent | undefined {
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'Node.js' };
if (rest.some((token) => token === '-e' || token === '--eval' || token === '-p' || token === '--print')) {
return { action: 'runNodeScript' };
}
const syntaxFlag = rest.findIndex((token) => token === '-c' || token === '--check');
const files = positionals(rest, NODE_VALUE_FLAGS);
const script = files[0];
if (!script || script === '-') return undefined;
const target = basenameRemotePath(script) || script;
return syntaxFlag >= 0 ? { action: 'checkSyntax', target } : { action: 'runScript', target };
}
function pythonIntent(rest: string[]): CommandIntent | undefined {
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'Python' };
if (rest.some((token) => token === '-c' || token === '-m')) return { action: 'runPythonScript' };
const script = positionals(rest, new Set(['-W', '-X']))[0];
if (!script || script === '-') return undefined;
return { action: 'runScript', target: basenameRemotePath(script) || script };
}
function perlIntent(rest: string[]): CommandIntent | undefined {
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'Perl' };
if (rest.includes('-c')) {
const script = positionals(rest, new Set(['-I', '-M', '-m']))[0];
return script ? { action: 'checkSyntax', target: basenameRemotePath(script) || script } : undefined;
}
if (rest.some((token) => /^-[^\s]*[eE]/.test(token))) return { action: 'runPerlScript' };
const script = positionals(rest, new Set(['-I', '-M', '-m']))[0];
if (!script || script === '-') return undefined;
return { action: 'runScript', target: basenameRemotePath(script) || script };
}
function swiftCompilerIntent(rest: string[]): CommandIntent | undefined {
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'Swift' };
const source = rest.find((token) => token.toLowerCase().endsWith('.swift'));
if (!source) return undefined;
const target = basenameRemotePath(source) || source;
if (rest.includes('-typecheck')) return { action: 'typecheck', target };
if (rest.includes('-parse')) return { action: 'checkSyntax', target };
return { action: 'build', target };
}
function swiftIntent(rest: string[]): CommandIntent | undefined {
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'Swift' };
if (rest.includes('-e')) return { action: 'runSwiftScript' };
const script = rest.find((token) => token.toLowerCase().endsWith('.swift'));
return script ? { action: 'runScript', target: basenameRemotePath(script) || script } : undefined;
}
function xcrunIntent(rest: string[]): CommandIntent | undefined {
const command = cliSubcommand(rest, new Set(['--sdk', '--toolchain']));
if (!command) return undefined;
if (command.name === 'swiftc') return swiftCompilerIntent(command.args);
if (command.name === 'swift') return swiftIntent(command.args);
if (command.name === 'simctl' && command.args[0] === 'list') {
return { action: 'inspectEnvironment' };
}
return undefined;
}
function plutilIntent(rest: string[]): CommandIntent | undefined {
if (rest.includes('-p')) return { action: 'inspect' };
if (rest.includes('-lint')) return { action: 'checkSyntax' };
return undefined;
}
const JQ_VALUE_FLAGS = new Set(['-L', '--indent', '-f', '--from-file']);
const JQ_TWO_VALUE_FLAGS = new Set(['--arg', '--argjson', '--slurpfile', '--rawfile', '--argfile']);
function jqIntent(rest: string[]): CommandIntent | undefined {
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'jq' };
if (rest.includes('-h') || rest.includes('--help')) return undefined;
if (rest.some((token) => JQ_TWO_VALUE_FLAGS.has(token))) return { action: 'parseJson' };
const files = positionals(rest, JQ_VALUE_FLAGS);
const filterComesFromFile = rest.includes('-f') || rest.includes('--from-file');
const input = filterComesFromFile ? files[0] : files[1];
return {
action: 'parseJson',
...(input ? { target: basenameRemotePath(input) || input } : {}),
};
}
function countIntent(rest: string[]): CommandIntent | undefined {
if (rest.includes('--help')) return undefined;
if (isVersionRequest(rest)) return { action: 'showVersion', target: 'wc' };
const files = positionals(rest, new Set(['--files0-from']));
const target = files[0];
return {
action: 'count',
...(target ? { target: basenameRemotePath(target) || target } : {}),
};
}
/** `date` can set the system clock; only known display-only forms get a friendly label. */
function dateIntent(rest: string[]): CommandIntent | undefined {
if (
rest.every(
(token) =>
token === '-u' ||
token === '--utc' ||
token === '--universal' ||
token === '-R' ||
token === '--rfc-email' ||
token.startsWith('+'),
)
) {
return { action: 'showDateTime' };
}
return undefined;
}
function locateCommandIntent(rest: string[]): CommandIntent | undefined {
if (rest.length < 2 || (rest[0] !== '-v' && rest[0] !== '-V')) return undefined;
const targets = rest.slice(1).filter((token) => token && !token.startsWith('-'));
return targets[0] ? { action: 'locateCommand', target: targets.join(' ') } : undefined;
}
function lsofIntent(rest: string[]): CommandIntent {
for (let index = 0; index < rest.length; index += 1) {
const token = rest[index];
if (token === '-i') {
const target = rest[index + 1];
return { action: 'inspectPorts', ...(target && !target.startsWith('-') ? { target } : {}) };
}
if (token.startsWith('-i') && token.length > 2) {
return { action: 'inspectPorts', target: token.slice(2) };
}
}
return { action: 'inspectProcesses' };
}
const SQLITE_VALUE_FLAGS = new Set(['-separator', '-newline', '-vfs']);
const SQLITE_UNSAFE_OPTIONS = ['-cmd', '-init'];
const SQLITE_MUTATING_SQL = /\b(?:insert|update|delete|replace|create|drop|alter|vacuum|attach|detach|reindex|load_extension|writefile)\b/i;
const SQLITE_READ_ONLY_DOT_COMMANDS = new Set([
'.tables', '.schema', '.indexes', '.databases', '.dbinfo', '.show', '.headers', '.mode', '.width',
]);
function sqliteIntent(rest: string[]): CommandIntent | undefined {
if (rest.some((token) => SQLITE_UNSAFE_OPTIONS.some((flag) => token === flag || token.startsWith(`${flag}=`)))) {
return undefined;
}
const pos = positionals(rest, SQLITE_VALUE_FLAGS);
const database = pos[0];
if (!database) return undefined;
if (!rest.includes('-readonly') && !/[?&]mode=ro(?:&|$)/i.test(database)) return undefined;
const statements = pos.slice(1);
if (
statements.some((statement) => {
const trimmed = statement.trim();
if (!trimmed.startsWith('.')) return false;
return !SQLITE_READ_ONLY_DOT_COMMANDS.has(trimmed.split(/\s+/, 1)[0]);
}) ||
SQLITE_MUTATING_SQL.test(statements.join(' '))
) {
return undefined;
}
return { action: 'queryDatabase', target: basenameRemotePath(database) || database };
}
interface CliSubcommand {
name: string;
args: string[];
}
/** Find the first non-option argv and return it with the untouched tail. */
function cliSubcommand(tokens: string[], valueFlags: Set<string>): CliSubcommand | undefined {
for (let index = 0; index < tokens.length; index += 1) {
const token = tokens[index];
if (token === '--') return undefined;
if (token.startsWith('-') && token.length > 1) {
if (valueFlags.has(token)) index += 1;
continue;
}
return { name: token.toLowerCase(), args: tokens.slice(index + 1) };
}
return undefined;
}
const GIT_GLOBAL_VALUE_FLAGS = new Set([
'-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env',
]);
function hasGitOutputFileFlag(args: string[]): boolean {
return args.some((token) => token === '--output' || token.startsWith('--output='));
}
const GIT_BRANCH_MUTATING_FLAGS = [
'-d', '-D', '-m', '-M', '-c', '-C', '-f', '-u',
'--delete', '--move', '--copy', '--force', '--edit-description', '--set-upstream-to', '--unset-upstream',
];
function gitBranchIsReadOnly(args: string[]): boolean {
if (
args.some((token) =>
GIT_BRANCH_MUTATING_FLAGS.some((flag) => token === flag || token.startsWith(`${flag}=`)) ||
(/^-[^-]/.test(token) && /[dDmMcCfu]/.test(token.slice(1))),
)
) {
return false;
}
if (args.includes('--list')) return true;
const valueFlags = new Set([
'--contains', '--no-contains', '--merged', '--no-merged', '--points-at', '--sort', '--format',
]);
return positionals(args, valueFlags).length === 0;
}
function gitRemoteIsReadOnly(args: string[]): boolean {
const operation = cliSubcommand(args, new Set([]));
return operation === undefined || operation.name === 'show' || operation.name === 'get-url';
}
function gitGrepIsReadOnly(args: string[]): boolean {
return !args.some(
(token) => token.startsWith('-O') || token.startsWith('--open-files-in-pager'),
);
}
function gitRebaseInvokesShell(args: string[]): boolean {
for (const token of args) {
if (token === '--') return false;
if (
token === '--exec' ||
token.startsWith('--exec=') ||
token === '-x' ||
token.startsWith('-x')
) {
return true;
}
}
return false;
}
function gitSubmoduleInvokesShell(args: string[]): boolean {
return cliSubcommand(args, new Set([]))?.name === 'foreach';
}
function gitIntent(rest: string[]): CommandIntent | undefined {
const subcommand = cliSubcommand(rest, GIT_GLOBAL_VALUE_FLAGS);
if (!subcommand) return undefined;
switch (subcommand.name) {
case 'status':
return { action: 'gitStatus' };
case 'diff':
return hasGitOutputFileFlag(subcommand.args) ? undefined : { action: 'gitDiff' };
case 'log':
return hasGitOutputFileFlag(subcommand.args) ? undefined : { action: 'gitLog' };
case 'show':
return hasGitOutputFileFlag(subcommand.args) ? undefined : { action: 'gitShow' };
case 'add':
return { action: 'gitAdd' };
case 'commit':
// Amend rewrites existing history rather than creating an ordinary commit;
// keep the exact command as the only description in that less-common case.
return subcommand.args.includes('--amend') ? undefined : { action: 'gitCommit' };
case 'fetch':
return { action: 'gitFetch' };
case 'pull':
return { action: 'gitPull' };
case 'push':
// Force/deletion forms deserve the raw fallback instead of the neutral
// "push changes" title, which would hide their destructive semantics.
if (
subcommand.args.some(
(token) =>
token === '-f' ||
token === '--force' ||
token.startsWith('--force=') ||
token.startsWith('--force-with-lease') ||
token === '-d' ||
token === '--delete' ||
token === '--mirror' ||
token === '--prune',
)
) {
return undefined;
}
return { action: 'gitPush' };
case 'rebase':
return gitRebaseInvokesShell(subcommand.args) ? undefined : { action: 'gitRebase' };
case 'merge':
return { action: 'gitMerge' };
case 'cherry-pick':
return { action: 'gitCherryPick' };
case 'stash':
return { action: 'gitStash' };
case 'restore':
return { action: 'gitRestore' };
case 'submodule':
return gitSubmoduleInvokesShell(subcommand.args) ? undefined : { action: 'gitSubmodule' };
case 'remote':
return gitRemoteIsReadOnly(subcommand.args) ? { action: 'gitRemote' } : undefined;
case 'rev-parse':
return { action: 'gitRevParse' };
case 'branch':
return gitBranchIsReadOnly(subcommand.args) ? { action: 'gitBranch' } : undefined;
case 'grep':
return gitGrepIsReadOnly(subcommand.args) ? { action: 'gitGrep' } : undefined;
case 'merge-base':
return { action: 'gitMergeBase' };
case 'ls-files':
return { action: 'gitLsFiles' };
case 'rev-list':
return { action: 'gitRevList' };
case 'ls-remote':
return subcommand.args.some((token) => token === '-u' || token.startsWith('--upload-pack'))
? undefined
: { action: 'gitLsRemote' };
case 'worktree': {
const worktree = cliSubcommand(subcommand.args, new Set([]));
switch (worktree?.name) {
case 'list':
return { action: 'gitWorktreeList' };
case 'add':
return { action: 'gitWorktreeAdd' };
case 'remove':
return { action: 'gitWorktreeRemove' };
case 'move':
return { action: 'gitWorktreeMove' };
case 'prune':
return { action: 'gitWorktreePrune' };
default:
return undefined;
}
}
default:
return undefined;
}
}
const GH_GLOBAL_VALUE_FLAGS = new Set(['-R', '--repo', '--hostname']);
const GH_PR_ACTIONS: Readonly<Record<string, CommandIntentAction>> = {
list: 'ghPrList',
view: 'ghPrView',
checks: 'ghPrChecks',
status: 'ghPrStatus',
diff: 'ghPrDiff',
create: 'ghPrCreate',
edit: 'ghPrEdit',
comment: 'ghPrComment',
review: 'ghPrReview',
merge: 'ghPrMerge',
close: 'ghPrClose',
reopen: 'ghPrReopen',
checkout: 'ghPrCheckout',
};
const GH_ISSUE_ACTIONS: Readonly<Record<string, CommandIntentAction>> = {
list: 'ghIssueList',
view: 'ghIssueView',
status: 'ghIssueStatus',
create: 'ghIssueCreate',
edit: 'ghIssueEdit',
comment: 'ghIssueComment',
close: 'ghIssueClose',
reopen: 'ghIssueReopen',
};
const GH_AUTH_ACTIONS: Readonly<Record<string, CommandIntentAction>> = {
status: 'ghAuthStatus',
login: 'ghAuthLogin',
logout: 'ghAuthLogout',
refresh: 'ghAuthRefresh',
switch: 'ghAuthSwitch',
};
const GH_RUN_ACTIONS: Readonly<Record<string, CommandIntentAction>> = {
list: 'ghRunList',
view: 'ghRunView',
watch: 'ghRunWatch',
};
const GH_SEARCH_GROUPS = new Set(['code', 'commits', 'issues', 'prs', 'repos']);
function githubCliIntent(rest: string[]): CommandIntent | undefined {
const group = cliSubcommand(rest, GH_GLOBAL_VALUE_FLAGS);
if (!group) return undefined;
if (group.name === 'api') return githubApiIntent(group.args);
const operationCommand = cliSubcommand(group.args, GH_GLOBAL_VALUE_FLAGS);
const operation = operationCommand?.name;
if (!operation) return undefined;
switch (group.name) {
case 'pr':
return GH_PR_ACTIONS[operation] ? { action: GH_PR_ACTIONS[operation] } : undefined;
case 'issue':
return GH_ISSUE_ACTIONS[operation] ? { action: GH_ISSUE_ACTIONS[operation] } : undefined;
case 'auth':
return GH_AUTH_ACTIONS[operation] ? { action: GH_AUTH_ACTIONS[operation] } : undefined;
case 'run':
return GH_RUN_ACTIONS[operation] ? { action: GH_RUN_ACTIONS[operation] } : undefined;
case 'search':
return GH_SEARCH_GROUPS.has(operation) ? { action: 'ghSearch' } : undefined;
case 'repo':
if (operation === 'list') return { action: 'ghRepoList' };
if (operation === 'view') {
const target = positionals(operationCommand?.args ?? [], GH_GLOBAL_VALUE_FLAGS)[0];
return { action: 'ghRepoView', ...(target ? { target } : {}) };
}
return undefined;
default:
return undefined;
}
}
function readCliOptionValue(tokens: string[], short: string, long: string): string | undefined {
for (let index = 0; index < tokens.length; index += 1) {
const token = tokens[index];
if (token === short || token === long) return tokens[index + 1];
if (token.startsWith(`${long}=`)) return token.slice(long.length + 1);
if (token.startsWith(short) && token.length > short.length) return token.slice(short.length);
}
return undefined;
}
function collectGithubApiFields(tokens: string[]): string[] {
const fields: string[] = [];
for (let index = 0; index < tokens.length; index += 1) {
const token = tokens[index];
if (token === '-f' || token === '-F' || token === '--raw-field' || token === '--field') {
if (tokens[index + 1] !== undefined) fields.push(tokens[index + 1]);
index += 1;
continue;
}
for (const flag of ['--raw-field=', '--field=', '-f', '-F']) {
if (token.startsWith(flag) && token.length > flag.length) {
fields.push(token.slice(flag.length));
break;
}
}
}
return fields;
}
const GH_API_VALUE_FLAGS = new Set([
'-H', '--header', '--hostname', '--input', '-q', '--jq', '-X', '--method',
'-f', '--raw-field', '-F', '--field', '-t', '--template', '--cache',
]);
function githubApiIntent(args: string[]): CommandIntent {
const method = readCliOptionValue(args, '-X', '--method')?.toUpperCase();
const hasInput = args.some((token) => token === '--input' || token.startsWith('--input='));
const fields = collectGithubApiFields(args);
const endpoint = positionals(args, GH_API_VALUE_FLAGS)[0]?.toLowerCase();
// --input may contain either a GraphQL query or a mutation; without reading
// another file the semantic operation is intentionally left unspecified.
if (hasInput && (method === undefined || endpoint === 'graphql')) return { action: 'ghApiCall' };
if (endpoint === 'graphql') {
const queryField = fields.find((field) => field.startsWith('query='));
const operation = queryField?.slice('query='.length).trim();
if (operation && /^mutation\b/i.test(operation)) return { action: 'ghApiMutation' };
if (operation && /^(?:query\b|\{)/i.test(operation)) return { action: 'ghApiQuery' };
if (method === undefined) return { action: 'ghApiCall' };
}
if (method === 'GET' || method === 'HEAD') return { action: 'ghApiQuery' };
if (method && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
return { action: 'ghApiMutation' };
}
if (method !== undefined) return { action: 'ghApiCall' };
if (!endpoint) return { action: 'ghApiCall' };
if (fields.length > 0) return { action: 'ghApiMutation' };
return { action: 'ghApiQuery' };
}
/** grep/rg 家族里「取值型」flag —— 解析 positional 时要连着跳过它的值。 */
const GREP_VALUE_FLAGS = new Set([
'-A', '-B', '-C', '-m', '-d', '-g', '-t', '-T', '-f',
'--type', '--glob', '--include', '--exclude', '--exclude-dir', '--max-count', '--context',
]);
function grepIntent(rest: string[]): CommandIntent | undefined {
// rg 的 --pre* 预处理器会为每个文件 spawn 进程(`rg --pre=rm ...`),不解析。
if (rest.some((token) => token.startsWith('--pre'))) return undefined;
// rg --files 是列文件模式(不搜索),按「列出」处理,别把路径当搜索词。
if (rest.includes('--files')) {
const pos = positionals(rest, new Set([...GREP_VALUE_FLAGS, '-e', '--regexp']));
return { action: 'list', ...(pos[0] ? { target: pos[0] } : {}) };
}
// -f/--file 时 pattern 来自文件,剩余 positional 全是搜索路径 —— 硬把
// 首个路径当 pattern 会渲染出错误的「搜索 src」,直接回退原文。覆盖紧贴
// (`-fpatterns.txt`)与捆绑(`-rf`)形态:非 `--` 短 token 含小写 f 即拒
// (-F fixed-strings 大小写有别,不受影响)。
if (
rest.some(
(token) =>
token === '--file' ||
token.startsWith('--file=') ||
token.startsWith('-f') ||
// 捆绑扫描豁免 -e* / --regexp*(pattern 载体,值里的 f 是搜索词)。
(/^-[a-zA-Z]/.test(token) &&
!token.startsWith('--') &&
!token.startsWith('-e') &&
token.includes('f')),
)
) {
return undefined;
}
// -e/--regexp 显式给 pattern 时优先;紧贴值形态(--regexp=X / -eX)同样认。
let pattern: string | undefined;
for (let index = 0; index < rest.length; index += 1) {
const token = rest[index];
if (token === '-e' || token === '--regexp') {
pattern = rest[index + 1];
break;
}
if (token.startsWith('--regexp=')) {
pattern = token.slice('--regexp='.length);
break;
}
if (token.startsWith('-e') && token.length > 2 && token !== '-e') {
pattern = token.slice(2);
break;
}
}
const pos = positionals(rest, new Set([...GREP_VALUE_FLAGS, '-e', '--regexp']));
pattern ??= pos[0];
if (!pattern) return undefined;
const path = pattern === pos[0] ? pos[1] : pos[0];
return { action: 'search', target: pattern, ...(path ? { path } : {}) };
}
/** pnpm/npm/yarn/bun 里「取值型」flag。 */
const PM_VALUE_FLAGS = new Set(['--filter', '-F', '--dir', '-C', '--cwd', '--prefix']);
const PACKAGE_MANAGER_BUILTINS = new Set([
'access', 'add', 'allow-builds', 'approve-builds', 'audit', 'bin', 'bugs', 'cache', 'catalog', 'ci',
'completion', 'config', 'constraints', 'create', 'dedupe', 'delete', 'deploy', 'deprecate', 'diff',
'dist-tag', 'dlx', 'doctor', 'docs', 'edit', 'env', 'exec', 'explain', 'explore', 'fetch', 'find-dupes',
'fund', 'get', 'help', 'help-search', 'hook', 'ignored-builds', 'import', 'info', 'init', 'install',
'install-ci-test', 'install-test', 'i', 'link', 'list', 'licenses', 'login', 'logout', 'ls', 'node',
'npm', 'org', 'outdated', 'owner', 'pack', 'patch', 'patch-commit', 'ping', 'pkg', 'plugin', 'pm',
'prefix', 'profile', 'prune', 'publish', 'query', 'rebuild', 'remove', 'repo', 'root', 'run', 'sbom',
'search', 'self-update', 'server', 'set', 'setup', 'shrinkwrap', 'stage', 'star', 'stars', 'store',
'team', 'token', 'uninstall', 'unlink', 'unplug', 'unpublish', 'update', 'up', 'upgrade-interactive',
'version', 'view', 'whoami', 'why', 'workspace', 'workspaces', 'x',
]);
function packageManagerIntent(manager: string, rest: string[]): CommandIntent | undefined {
if (isVersionRequest(rest)) return { action: 'showVersion', target: manager };
const pos = positionals(rest, PM_VALUE_FLAGS);
const sub = pos[0];
if (!sub) return undefined;
switch (sub) {
case 'install':
case 'i':
case 'ci': {
const pkgs = pos.slice(1).join(' ');
return { action: 'install', ...(pkgs ? { target: pkgs } : {}) };
}
case 'add': {
const pkgs = pos.slice(1).join(' ');
return { action: 'install', ...(pkgs ? { target: pkgs } : {}) };
}
case 'run': {
if (!pos[1]) return undefined;
// 转发参数可携带写文件 flag(`pnpm run lint -- --fix`),先查再分类。
if (hasMutatingForwardedArg(argsAfter(rest, pos[1]))) return undefined;
return scriptIntent(pos[1]) ?? { action: 'runScript', target: pos[1] };
}
case 'test':
// `npm test -- --updateSnapshot` 会改写快照,不能标「运行测试」。
if (hasMutatingForwardedArg(argsAfter(rest, sub))) return undefined;
return { action: 'test' };
case 'exec':
case 'dlx':
return pos[1] ? toolBinaryIntent(pos[1], argsAfter(rest, pos[1])) : undefined;
default: {
// 先按 package.json script 名认,再按直调本地工具二进制认
// (`pnpm vitest run` / `pnpm eslint .` 这种形态)。args 传原始 token
// 序列(positionals 会丢 flag,--fix 这类检查必须看得到)。
const forwarded = argsAfter(rest, sub);
const script = scriptIntent(sub);
if (script) return hasMutatingForwardedArg(forwarded) ? undefined : script;
const tool = toolBinaryIntent(sub, forwarded);
if (tool) return tool;
if (KNOWN_TOOL_BINARIES.has(binaryName(sub))) return undefined;
return PACKAGE_MANAGER_BUILTINS.has(sub)
? undefined
: { action: 'runScript', target: sub };
}
}
}
/** 转发给 script / 工具的已知写文件 flag(eslint --fix[=true]、快照更新)。 */
function hasMutatingForwardedArg(args: string[]): boolean {
return args.some(
(token) => token === '--fix' || token.startsWith('--fix=') || token === '-u' || token.startsWith('--update'),
);
}
/** rest 中 anchor(必存在)之后的原始 token 序列 —— 保留 flag 供写文件形态检查。 */
function argsAfter(rest: string[], anchor: string): string[] {
return rest.slice(rest.indexOf(anchor) + 1);
}
/** package.json script 名 → 意图(只认 test/build/lint/typecheck 前缀族)。 */
function scriptIntent(script: string): CommandIntent | undefined {
if (/^test([:.-]|$)/.test(script)) return { action: 'test' };
if (/^build([:.-]|$)/.test(script)) return { action: 'build' };
if (/^lint([:.-]|$)/.test(script)) return { action: 'lint' };
// 'tsc' 是二进制不是 script 名,交给 toolBinaryIntent 做 --noEmit 检查。
if (/^typecheck([:.-]|$)/.test(script)) return { action: 'typecheck' };
return undefined;
}
const KNOWN_TOOL_BINARIES = new Set([
'vitest', 'jest', 'pytest', 'eslint', 'tsc', 'prettier', 'node',
]);
/** 直接调用的工具二进制 → 意图(vitest / eslint / tsc …),args 用于拒绝写文件形态。 */
function toolBinaryIntent(bin: string | undefined, args: string[] = []): CommandIntent | undefined {
if (!bin) return undefined;
switch (binaryName(bin)) {
case 'vitest':
case 'jest':
case 'pytest':
// 快照更新形态(-u / --update*)会改写测试文件,不解析。
if (args.some((token) => token === '-u' || token.startsWith('--update'))) return undefined;
return { action: 'test' };
case 'eslint':
// --fix 会改写源码(含 --fix=true 取值形态);--fix-dry-run 不落盘,放行。
if (args.some((token) => token === '--fix' || token.startsWith('--fix='))) return undefined;
return { action: 'lint' };
case 'tsc': {
// 裸 tsc 会产出 JS、--init 写 tsconfig —— 只有 --noEmit 是纯类型检查,
// 且布尔取值不能显式为 false(`tsc --noEmit false a.ts` 仍会产出)。
const idx = args.indexOf('--noEmit');
if (idx === -1) return undefined;
if ((args[idx + 1] ?? '').toLowerCase() === 'false') return undefined;
return { action: 'typecheck' };
}
case 'prettier':
if (args.includes('--check') || args.includes('-c')) return { action: 'checkFormatting' };
return undefined;
case 'node':
return nodeIntent(args);
default:
return undefined;
}
}
function cargoIntent(sub: string | undefined, args: string[] = []): CommandIntent | undefined {
switch (sub) {
case 'test':
// --no-run 只编译不跑,不能标「运行测试」。
return args.includes('--no-run') ? undefined : { action: 'test' };
case 'build':
return { action: 'build' };
case 'check':
return { action: 'typecheck' };
case 'clippy':
// clippy --fix 会自动改写源码,不能标「代码检查」。
return args.includes('--fix') ? undefined : { action: 'lint' };
case 'add':
return { action: 'install' };
default:
return undefined;
}
}
// ── action 门控实现 ──────────────────────────────────────────────────────────
/**
* sed 只读形态判定:-n 存在、无 -i* / --in-place[=SUFFIX] 就地编辑,且脚本
* 是**纯打印形态**(如 `1,120p` / `5p` / `$p`)。sed 脚本自身就能写文件
* (`1w out.txt`)/ 执行命令(GNU `e`),非纯打印一律拒,回退原文。
*/
const SED_PRINT_ONLY_SCRIPT = /^[0-9,$;~\s]*p$/;
function sedTokensAreReadOnly(rest: string[]): boolean {
if (!rest.includes('-n')) return false;
if (rest.some((token) => token.startsWith('-i') || token === '--in-place' || token.startsWith('--in-place='))) {
return false;
}
// -f/--file 从脚本文件加载 sed 脚本,内容不可静态判定(可含 w / e),拒。
if (rest.some((token) => token.startsWith('-f') || token === '--file' || token.startsWith('--file='))) {
return false;
}
// 多段脚本(多个 -e)不在「看文件片段」的目标形态内,保守拒。
const expressionFlags = rest.filter((token) => token === '-e' || token === '--expression');
if (expressionFlags.length > 1) return false;
const eIndex = rest.findIndex((token) => token === '-e' || token === '--expression');
const script = eIndex >= 0 ? rest[eIndex + 1] : positionals(rest, new Set([]))[0];
return script !== undefined && SED_PRINT_ONLY_SCRIPT.test(script);
}
/** A pipeline filter must consume stdin; an extra file operand would change the displayed source. */
function sedPipelineFilterIsReadOnly(rest: string[]): boolean {
if (!sedTokensAreReadOnly(rest)) return false;
const usesExpressionFlag = rest.some((token) => token === '-e' || token === '--expression');
const pos = positionals(rest, new Set(['-e', '--expression']));
return usesExpressionFlag ? pos.length === 0 : pos.length === 1;
}
/**
* read action 门控:action.command 过 `analyzeCommandShape` 完整归一化
* (剥 cd 前缀 / 验证命令链、管道尾、重定向)后,首 token 需在
* READ_COMMAND_BINS(sed 另须只读形态)。与本地路径共用同一套归一化 ——
* `cd repo && sed -i ...` 这类带前缀的 action.command 不能拿 `cd` 当 bin
* 绕过检查。
*/
function isKnownReadCommand(command: string | undefined): boolean {
if (!command) return false;
const argv = analyzeCommandShape(command);
if (!argv || argv.length === 0) return false;
const bin = binaryName(argv[0]);
if (!READ_COMMAND_BINS.has(bin)) return false;
// codex 可能给 `sed -i` 就地编辑(或 /usr/bin/sed 的 executable-read)也报 read action。
if (bin === 'sed') return sedTokensAreReadOnly(argv.slice(1));
// less/more 的 + 启动命令可执行 shell,与本地解析同口径拒。
if ((bin === 'less' || bin === 'more') && argv.slice(1).some((token) => token.startsWith('+'))) {
return false;
}
return true;
}
/**
* search / listFiles action 门控:action.command 含副作用形态时拒绝 ——
* 破坏性 find、`fd -x/--exec[-batch]`(逐结果执行命令)、grep 家族的
* `--pre*` 预处理器(rg 会为每个文件 spawn 进程)。tokenize / strip 失败
* (未闭合引号、写文件重定向等)同样保守拒绝 —— 代价只是回退原文,零风险。
*/
function searchCommandHasSideEffects(command: string | undefined): boolean {
if (!command) return false;
// 与 read 门控同理:先过 analyzeCommandShape 完整归一化,`cd repo &&
// find ... -delete` 不能拿 `cd` 当 bin 绕过下面的副作用检查。
const argv = analyzeCommandShape(command);
if (!argv || argv.length === 0) return true;
const bin = binaryName(argv[0]);
const rest = argv.slice(1);
if (bin === 'find') return rest.some((token) => FIND_DESTRUCTIVE_FLAGS.has(token));
if (bin === 'fd') return rest.some((token) => hasFdExecFlag(token));
if (bin === 'rg' || bin === 'grep' || bin === 'egrep' || bin === 'fgrep' || bin === 'ag') {
return rest.some((token) => token.startsWith('--pre'));
}
// tree 的写文件 flag(-o FILE / -R 写 00Tree.html)—— 与本地解析同口径,
// codex 把 `tree -o x` 归成 listFiles 时不能被贴「列出」。
if (bin === 'tree') return rest.some((token) => token.startsWith('-') && /[oR]/.test(token));
return false;
}
/**
* fd 的逐结果执行 flag(-x / --exec / -X / --exec-batch)。短选项可紧贴值
* (`-xrm`)或捆绑(`-Hx`),短 token 含 x/X 字符即拒 —— 偏保守,误杀代价
* 只是回退原文。
*/
function hasFdExecFlag(token: string): boolean {
if (token.startsWith('--exec')) return true;
return /^-[a-zA-Z]/.test(token) && !token.startsWith('--') && /[xX]/.test(token);
}
// ── 词法辅助 ─────────────────────────────────────────────────────────────────
/**
* 顶层分割(引号内的分隔符不算)。未闭合引号返回 undefined;`||` 只有调用方
* 明确把它列为分隔符时才接受,否则保持旧的保守回退。分隔符按传入列表顺序
* 匹配 —— 调用方须把 `&&` 排在 `&` 前,避免拆成两个 `&`;`>&`(fd 复制,
* 如 2>&1)里的 `&` 不算分隔符。
*/
function splitTopLevel(input: string, separators: string[]): string[] | undefined {
const segments: string[] = [];
let current = '';
let quote: '"' | "'" | null = null;
for (let index = 0; index < input.length; index += 1) {
const ch = input[index];
if (quote) {
current += ch;
if (ch === quote && (quote !== '"' || input[index - 1] !== '\\')) quote = null;
continue;
}
if (ch === '\\' && input[index + 1] !== undefined) {
current += ch + input[index + 1];
index += 1;
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
current += ch;
continue;
}
if (ch === '|' && input[index + 1] === '|' && !separators.includes('||')) return undefined;
const matched = separators.find((sep) => input.startsWith(sep, index));
if (
matched === '&' &&
((index > 0 && input[index - 1] === '>') || input[index + 1] === '>')
) {
current += ch; // 2>&1 / >&2 / &>/dev/null 是重定向,不是后台操作符
continue;
}
if (matched) {
segments.push(current);
current = '';
index += matched.length - 1;
continue;
}
current += ch;
}
if (quote) return undefined;
segments.push(current);
return segments.map((segment) => segment.trim()).filter((segment) => segment.length > 0);
}
/**
* 引号感知的 token 化;text 去引号取内容,unquotedMeta 按字符粒度标记该
* token 是否含未引号的 < / > / ((重定向 / 进程替换判定只看未引号部分,
* `rg ">" src` 的引号元字符是普通搜索词)。未闭合引号返回 undefined。
*/
function tokenize(input: string): ShellWord[] | undefined {
const tokens: ShellWord[] = [];
let current = '';
let hasToken = false;
let unquotedMeta = false;
let hasQuoted = false;
let quote: '"' | "'" | null = null;
for (let index = 0; index < input.length; index += 1) {
const ch = input[index];
if (quote) {
if (ch === quote) {
quote = null;
} else if (quote === '"' && ch === '\\' && input[index + 1] === '"') {
current += '"';
index += 1;
} else {
current += ch;
}
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
hasToken = true;
hasQuoted = true;
continue;
}
if (ch === '\\' && input[index + 1] !== undefined) {
const escaped = input[index + 1];
if (/\s|["'\\<>();&|]/.test(escaped)) {
current += escaped;
hasToken = true;
index += 1;
continue;
}
}
if (/\s/.test(ch)) {
if (hasToken) tokens.push({ text: current, unquotedMeta, hasQuoted });
current = '';
hasToken = false;
unquotedMeta = false;
hasQuoted = false;
continue;
}
if (ch === '<' || ch === '>' || ch === '(') unquotedMeta = true;
current += ch;
hasToken = true;
}
if (quote) return undefined;
if (hasToken) tokens.push({ text: current, unquotedMeta, hasQuoted });
return tokens;
}
/**
* 剥掉 env 前缀赋值(FOO=bar cmd)、sudo 与无害重定向 token。
* 命中**写文件**重定向时返回 undefined —— 这类命令有创建 / 覆盖文件的副作用,
* 意图解析必须整体放弃,不能把 `cat a > b` 渲染成无害的「读取 a」。按 shell
* 语义,重定向不要求空格:未引号 token 中间出现 `>` / `<`(如 `a>b`)同样
* 视为重定向处理;引号包裹的 `>`(如搜索 "=>")不受影响。丢弃流(>/dev/null)
* 与 fd 复制(2>&1 / >&2)无副作用,照常剥掉;输入重定向(< file)只读,同样剥掉。
*/
function stripPrefixTokens(words: ShellWord[]): string[] | undefined {
let start = 0;
// env 前缀 / sudo 只在**不含未引号元字符**时才可无害跳过 ——
// `LOG=x>secret.txt cat a` 的赋值段黏着写文件重定向,不能白丢。
while (
start < words.length &&
!words[start].unquotedMeta &&
(/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[start].text) || words[start].text === 'sudo')
) {
start += 1;
}
if (words[start]?.text === 'env' && !words[start].unquotedMeta) {
start += 1;
while (start < words.length) {
const word = words[start];
if (word.unquotedMeta) return undefined;
const token = word.text;
if (token === '--') {
start += 1;
break;
}
if (token === '-u' || token === '--unset' || token === '-C' || token === '--chdir') {
const value = words[start + 1];
if (!value || value.unquotedMeta) return undefined;
start += 2;
continue;
}
if (
token === '-i' || token === '--ignore-environment' || token === '-0' || token === '--null' ||
token === '-v' || token === '--debug' || token.startsWith('--unset=') ||
token.startsWith('--chdir=') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(token)
) {
start += 1;
continue;
}
if (token.startsWith('-')) return undefined;
break;
}
}
const out: string[] = [];
for (let index = start; index < words.length; index += 1) {
const word = words[index];
// 无未引号元字符 → 普通参数(引号里的 > / < / ( 是内容,如搜索 "=>")。
if (!word.unquotedMeta) {
out.push(word.text);
continue;
}
const token = word.text;
// 未引号元字符 + 引号部分混排(`>"&2"`):去引号后的 text 会把引号里的
// 文件名伪装成 fd 复制 / 无害目标,无法可靠区分,一律保守拒。
if (word.hasQuoted) return undefined;
// 进程替换 <(cmd) / >(cmd) / zsh =(cmd) 内嵌任意命令(`cat <(rm -rf build)`),
// 必须在输入重定向剥除之前拒绝,不能当成无害 `<` 丢掉。
if (token.includes('<(') || token.includes('>(') || token.includes('=(')) return undefined;
// <> 读写重定向会创建目标文件(`cat <> created.txt`),同样不能当无害输入丢掉。
if (token.includes('<>')) return undefined;
if (token === '<') {
// 输入重定向:消费目标前必须检查 —— `cat < <(rm -rf build)` /
// `cat < =(rm ...)` 的目标是进程替换,含未引号元字符的目标一律整体放弃。
const target = words[index + 1];
index += 1;
if (target?.unquotedMeta) return undefined;
continue;
}
if (token.startsWith('<') && !token.slice(1).includes('<') && !token.slice(1).includes('>')) {
continue; // 纯附加输入重定向 `<file`,只读无害
}
const redirect = token.match(/^(?:\d?|&)(>>?)(.*)$/);
if (redirect) {
const targetWord = redirect[2] === '' ? words[index + 1] : undefined;
const target = redirect[2] !== '' ? redirect[2] : targetWord?.text ?? '';
if (redirect[2] === '') index += 1; // 目标是下一个 token,一并消费
// fd 复制只放行 &数字 / &-(关闭):bash 的 `>&word`(word 非 fd)等价
// `>word 2>&1`,会创建/截断文件 word,不能当无害 fd 复制放过。
// 目标带引号(`> "&2"`)时是字面文件名,不享受 fd/devnull 豁免。
if (
!targetWord?.hasQuoted &&
(target === '/dev/null' || /^&(\d+|-)$/.test(target))
) {
continue;
}
return undefined;
}
// 其余含未引号元字符的形态(紧贴重定向 `a>b`、混合引号 `a>"b"`、
// 裸 `(` 等)一律保守放弃 —— shell 重定向不要求空格。
return undefined;
}
return out;
}
/** 取 positional 参数:跳过 flag,以及 valueFlags 里 flag 携带的下一个值。 */
function positionals(tokens: string[], valueFlags: Set<string>): string[] {
const out: string[] = [];
for (let index = 0; index < tokens.length; index += 1) {
const token = tokens[index];
if (token === '--') {
out.push(...tokens.slice(index + 1));
break;
}
if (token.startsWith('-') && token.length > 1) {
if (valueFlags.has(token)) index += 1;
continue;
}
out.push(token);
}
return out;
}
/** 去掉路径前缀取二进制名(/usr/bin/grep → grep,大小写不敏感平台统一小写)。 */
function binaryName(token: string): string {
const base = basenameRemotePath(token) || token;
return base.toLowerCase();
}
function readNonEmptyString(value: unknown): string | undefined {
if (typeof value !== 'string') return undefined;
const trimmed = value.trim();
return trimmed.length > 0 ? trimmed : undefined;
}