开发与测试
claude-runner
Claude/Codex CLI execution layer — prompt loading, stream-json parsing, file output extraction, path sanitization, skill file writing, and skill rule generation
aspenkit · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add aspenkit/aspens --skill claude-runner技能说明
name: claude-runner description: Claude/Codex CLI execution layer — prompt loading, stream-json parsing, file output extraction, path sanitization, skill file writing, and skill rule generation triggers: files: - src/lib/runner.js - src/lib/timeout.js - src/lib/skill-writer.js - src/lib/skill-reader.js - src/prompts/**/*.md keywords: - runClaude - runCodex - runLLM - stream-json - codex exec - parseFileOutput - sanitizePath - loadPrompt - writeSkillFiles - skill-rules - mergeSettings - resolveTimeout
You are working on the CLI execution layer — the bridge between assembled prompts and the claude -p / codex exec CLIs, plus skill file I/O.
Key Concepts
- Stream-JSON protocol (Claude):
runClaude()always passes--verbose --output-format stream-json. Output is NDJSON:type: 'result'has final text + usage;type: 'assistant'has text/tool_use blocks;type: 'user'has tool_result blocks. - JSONL protocol (Codex):
runCodex()spawnscodex exec --json --sandbox read-only --ephemeral. The--ask-for-approval neverflag is conditionally included based on capability detection (see below). Prompt is passed via stdin ('-'placeholder arg) to avoid shell arg length limits. Stdin write happens after event handlers are attached so fast failures are captured. Events:item.completed/item.updatedwith normalized types. - Codex capability detection:
getCodexExecCapabilities()(internal, cached) runscodex exec --helpand checks if--ask-for-approvalappears in the help text. Result is cached in module-levelcodexExecCapabilitiesvariable. If the help check fails (e.g., codex not installed), capabilities default to{ supportsAskForApproval: false }.runCodex()only adds--ask-for-approval neverwhensupportsAskForApprovalis true. - Unified routing:
runLLM(prompt, options, backendId)is the shared entry point — dispatches torunClaude()orrunCodex()based onbackendId. Exported fromrunner.jsso command handlers no longer need local routing helpers. - Codex internals (private):
normalizeCodexItemType()converts PascalCase/kebab-case to snake_case.collectCodexText()recursively extracts text from nested event content. Both are internal to runner.js. - Prompt templating:
loadPrompt(name, vars)resolves{{partial-name}}fromsrc/prompts/partials/first, then substitutes{{varName}}fromvars. Target-specific vars (skillsDir,skillFilename,instructionsFile,configDir) are passed by command handlers. - File output parsing: Primary:
<file path="...">content</file>XML tags. Fallback:<!-- file: path -->comment markers.parseFileOutput(output, allowedPaths)accepts optional{ dirPrefixes, exactFiles }to override default allowed paths. - Path sanitization:
sanitizePath(rawPath, allowedPaths)(internal) blocks..traversal, absolute paths. Defaults:.claude/prefix +CLAUDE.mdexact. Multi-target callers pass expanded allowed paths viagetAllowedPaths()fromtarget.js. - Validation:
validateSkillFiles()checks for truncation (XML tag collisions), missing frontmatter, missing sections, bad file path references. - Skill rules generation:
extractRulesFromSkills()reads all skills viaskill-reader.js, producesskill-rules.json(v2.0) with file patterns, keywords, and intent patterns. - Domain patterns:
generateDomainPatterns()converts file patterns to bashdetect_skill_domain()function usingBEGIN/ENDmarkers. - Trigger parsing precedence:
parseTriggersFrontmatter(content)returns{ filePatterns, keywords, alwaysActivate }parsed from atriggers:block in YAML frontmatter (supports block lists, inline arrays, andalwaysActivate: truefor the base skill); returnsnullwhen notriggers:key exists.parseActivationPatternsandparseKeywordsprefer this frontmatter when present and fall back to legacy## Activation/Keywords:line parsing for older skills. - Settings merge:
mergeSettings()merges aspens hook config into existingsettings.json. Detects aspens-managed hooks byASPENS_HOOK_MARKERS(skill-activation-prompt,graph-context-prompt,post-tool-use-tracker,save-tokens-statusline,save-tokens-prompt-guard,save-tokens-precompact). Also handlesstatusLinemerging — replaces existing statusLine only if the current one is aspens-managed (detected byisAspensHook), preserving user-custom statusLine configs. After merging hooks,dedupeAspensHookEntries()removes duplicate aspens-managed entries per event type. - Directory-scoped writes:
writeTransformedFiles()handles files outside.claude/(e.g.,src/billing/AGENTS.md) with explicit path allowlist — onlyCLAUDE.md,AGENTS.mdexact files and.claude/,.agents/,.codex/prefixes are permitted. findSkillFilesmatching: Only matches the exactskillFilename(e.g.,skill.mdorSKILL.md), not arbitrary.mdfiles in the skills directory.
Critical Rules
- Both
--verboseand--output-format stream-jsonare required for Claude — omitting either breaks stream parsing. - Codex uses
--json --sandbox read-only --ephemeral—--sandbox read-onlyrestricts filesystem access,--ephemeralavoids persisting conversation.--ask-for-approval neveris added only ifgetCodexExecCapabilities()confirms support. Prompt goes via stdin, not as a CLI arg. - Codex stdin write order matters — event handlers (
stdout,stderr,close,error) must be attached before writing to stdin, so fast failures are captured. - Path sanitization is non-negotiable —
sanitizePath()blocks..traversal, absolute paths, and any path not in the allowed set. - Prompt partials resolve before variables —
{{skill-format}}resolves topartials/skill-format.mdfirst. If no file, falls through to variable substitution. - **Timeout resolut