prompt-cache-optimizer

name	prompt-cache-optimizer
description	审计并优化 LLM 提示缓存命中率、输入 token、延迟与调用成本。用于用户要求“优化缓存命中”“降低 token 成本”“审计 LLM 调用”“提示词缓存优化”“优化 AI 调用费用”，或需要为可自动读取 API 调用指标的应用建立可观测性和固定回归样本时。

Prompt Cache Optimizer

以项目真实的提示构造、调用日志和回归样本为依据优化缓存；不要把缩短提示词或删除必要上下文误当成优化。

Resources

• 运行 scripts/prompt-cache-bootstrap.sh 安装或检查规则；只有已接通自动 usage 采集时才加 --with-observability 安装调用事件 schema 与回归样本模板。
• 需要接入指标或解释比较方式时，读取 references/measurement.md。
• 使用 assets/llm-usage-event.schema.json 作为调用日志字段合同。
• 使用 assets/prompt-cache-regression-cases.json 创建脱敏、稳定的回归样本。

Workflow

1. Establish Scope

1. Read the target project's entry instructions and check git status --short before editing.
2. Identify the LLM provider, request entry points, model settings, prompt templates, tool definitions, subagent prompts, and whether provider usage can be captured automatically.
3. Enable observability only when an existing structured log or an API request boundary can automatically record provider usage. For direct Codex use without a project API, do not create /.llm and do not ask the user to transcribe token or cost data.
4. Treat absent cache metrics as a data gap. Do not estimate a cache hit rate from prompt text alone.
5. Preserve user changes, secrets, output quality, and safety constraints. Do not commit or push unless explicitly requested.

2. Install and Inspect Foundation

1. Run a read-only check first:

bash scripts/prompt-cache-bootstrap.sh --check --platform both --target <target-project>

2. When the target lacks the foundation and the user authorizes changes, install it:

bash scripts/prompt-cache-bootstrap.sh --apply --platform both --with-skill --target <target-project>

3. For a single built-in profile, replace both with codex or claude.
4. For a custom agent profile, use --platform none --agent name,agent_dir,entry_file --with-skill; the skill is copied to <agent_dir>/skills.
5. After the agent has connected automatic usage collection, install or check its contracts with --with-observability. Do not use this option merely to create forms for manual entry.
6. Keep platform-specific rule entry files in their own profile directories; do not manually mirror generated files between profiles.

3. Audit High-Value Requests

1. Group requests by request_type, template_id, template_version, and model.
2. Prioritize groups with high call volume, long input, low cache-read token share, or high cost.
3. Check that stable role, output format, tool constraints, and safety rules appear first and remain byte-stable across the group.
4. Check that user input, file excerpts, timestamps, IDs, git status, task state, and runtime values appear only in the final parameter block.
5. Find unnecessary full-file loads, repeated history, mirrored directories, webpage bodies, and subagents returning raw source text.
6. Prefer paths, anchors, summaries, references, and structured intermediate artifacts over repeated long content.

4. Measure and Build Regression Coverage

1. Read references/measurement.md before adding telemetry or interpreting cache metrics.
2. Have the agent record template version, model, input/output token counts, cache read/write token counts when supplied, latency, and cost from the provider response or existing logs; never ask the user to fill these fields manually.
3. Replace the disabled regression example with 3-10 representative, stable, and sanitized high-frequency requests only when the agent can rerun them and collect their metrics automatically.
4. Define output quality checks before accepting a token or cache improvement.

5. Report, Change, and Validate

1. Report findings in descending expected impact with file evidence, risk, proposed change, and validation method.
2. When the user has not authorized edits, stop after the audit and plan.
3. When edits are authorized, make small isolated changes, preserve the stable prefix, and avoid unrelated refactors.
4. Run project checks and the same regression cases after each meaningful change.
5. Compare quality, input token, cache-read token, latency, and cost using the same request grouping. Clearly separate measured outcomes from expected outcomes.

Completion Criteria

• The target has a stable prompt-cache rule and entry-point reference for the selected platform.
• When automatic telemetry is supported, usage events use the schema or an explicitly documented compatible equivalent; otherwise /.llm is absent.
• When automatic regression runs are supported, regression cases cover representative high-frequency requests and include quality expectations.
• Findings and changes are traceable to files and measured metrics.
• No claim of savings is made without comparable before-and-after data.