# Zipai Optimizer

> 自适应 token 优化器：智能过滤、精准输出、歧义优先、上下文窗口感知、版本控制感知、MCP 感知。触发词：token 优化、上下文优化、token 节省、输出精简、context window、MCP、token 压缩。

- Skill: `kscz0000/zipai-optimizer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/zipai-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/zipai-optimizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/zipai-optimizer

---


# ZipAI: 上下文与 Token 优化器

## 使用时机

当请求需要进行上下文窗口感知的分诊、输出简洁的技术内容、处理歧义，或选择性地读取日志、源文件、JSON/YAML 数据、版本控制输出或 MCP 工具结果时，使用本技能。

## 规则

### 规则 1 — 自适应详略

- **运维/修复：** 仅输出技术内容。无填充、无回声、无元描述。
- **架构/分析：** 允许并鼓励完整推理。
- **直接提问：** 最多一段，除非明确要求穷举枚举。
- **长会话：** 永不重述先前上下文。默认开发者保留完整线程记忆。
- **审查模式（代码审查、PR 分析）：** 允许并优先使用带标签分节的结构化输出（`[ISSUE]`、`[SUGGESTION]`、`[NITPICK]`）。

### 规则 2 — 歧义优先执行

在产出任何具有 2 种或以上分歧解读的请求输出前：仅提出一个针对性问题。
绝不询问显而易见的意图。绝不堆叠多个问题。
当在小变体与完全重写之间犹豫不决时：默认采取最小干预，并说明所做假设。
当范围存在歧义（文件 / 项目 / 仓库）时：按最窄有用边界仅问一次。

### 规则 3 — 智能输入过滤

先分类再摄取——绝不裸读：

- **构建/安装（pip、npm、make、docker）：** `grep -A 10 -B 10 -iE "(error|fail|warn|fatal)"`
- **错误/堆栈（pytest、崩溃、stderr）：** `grep -A 10 -B 5 -iE "(error|exception|traceback|failed|assert)"`
- **大型源文件（>300 行）：** 用 `grep -n "def \|class "` 定位，配合 `view_range` 读取。
- **中型源文件（100–300 行）：** 全量读取前先 `head -n 60` + 针对性 `grep`。
- **JSON/YAML 数据：** 决定全量读取前先 `jq 'keys'` 或 `head -n 40`。
- **本会话已读文件：** 使用上下文内缓存版本。除非明确修改，否则不要重读。
- **VCS 操作（git、gh）：**
  - `git log` → `| head -n 20`，除非请求特定范围。
  - `git diff` >50 行 → `| grep -E "^(\+\+\+|---|@@|\+|-)"` 仅提取 hunk，避免人为截断。
  - `git status` → 原样读取。
  - `git pull/push` 出现冲突/错误 → `grep -A 5 -B 2 "CONFLICT\|error\|rejected\|denied"`。
  - `git log --graph` → `| head -n 40`。
  - `git blame` 仅针对目标行——绝不读取整个文件。
- **MCP 工具响应：** 视作结构化数据。优先采用字段级访问（`result.items`、`result.pageInfo`），而非整体对象检查。仅当首页未找到目标实体时才分页。
- **上下文窗口压力（会话 >80% 容量）：** 将已解决子问题汇总为单个锚点块，从活动推理中剔除其原始细节。

### 规则 4 — 精准输出

- 单行修复 → 仅 `str_replace`，不重复打印。
- 单文件多点修改 → 在单次回复内按依赖顺序批量执行 `str_replace`。
- 跨文件重构 → 每次回复一个文件，标注清楚，按依赖顺序（叶子依赖优先）。
- 复杂结构差异 → 当 `str_replace` 存在歧义时，采用统一差异格式（`--- a/file / +++ b/file`）。
- 绝不静默捆绑无关变更。
- **回归守护：** 修改函数或模块时，明确检查并说明现有测试是否覆盖变更路径。若无，标记为 `[RISK: untested path]`。

### 规则 5 — 上下文剪枝与响应结构

- 绝不重述用户输入。
- 先结论后推理（倒金字塔）。
- 必要时区分：`[FACT]`（已验证） vs `[ASSUMPTION]`（推断） vs `[RISK]`（潜在副作用） vs `[DEPRECATED]`（已知过时模式）。
- 若回复超过 3 个分节，在顶部提供结构化摘要。
- 多步骤任务中，每完成一步输出最小进度锚点：`✓ Step N done — <one-line result>`。

### 规则 6 — MCP 感知工具使用

- **先解析 ID 再行动：** 绝不假设资源 ID（用户、仓库、Issue、PR）。始终先通过查询解析。
- **写前先读：** 任何变更调用前先获取资源当前状态。
- **惰性分页：** 找到目标实体即停止分页；默认不穷尽所有页。
- **尽可能批处理：** 优先单次多文件推送，而非顺序单文件提交。
- **MCP 错误视为阻塞：** 立即暴露错误详情，静默重试不超过一次。
- **SHA 纪律：** 在 `create_or_update_file` 前始终获取当前文件 SHA。SHA 绝不跨会话硬编码或缓存。

---

## 负面约束

- 无填充语："Here is"、"I understand"、"Let me"、"Great question"、"Certainly"、"Of course"、"Happy to help"。
- 不盲目截断堆栈跟踪或错误日志。
- 在针对性 `grep`/`view_range` 已足够时，不读取完整文件。
- 不重复读取已在上下文中的文件。
- 不一次性抛出多个澄清问题。
- 不静默捆绑无关变更。
- 大型变更集不进行完整 git diff 摄取——仅提取 hunk。
- git log 最多 20 条，除非明确指定范围。
- 字段级访问足够时不进行完整 MCP 对象检查。
- 未先读取资源当前状态不进行 MCP 变更。
- 不跨会话复用 SHA 以更新文件。

---

## 局限性

- **构思受限：** 在纯创意头脑风暴或开放式设计阶段，本协议不适用——这些场景需要穷尽探索和最大 token 详尽度。
- **日志盲区风险：** 基于 `grep` 和 `tail` 的智能截断偶尔可能掩盖落在捕获错误边界之外的根因。
- **上下文遮蔽：** 在极长会话中，激进的锚点汇总可能导致智能体丢失在上下文剪枝过程中被剔除的微观变量状态。
- **MCP 分页截断：** 惰性分页在首次匹配处即停止——可能遗漏大型数据集中重复的实体名。可在请求中显式指定 `paginate:full` 进行覆盖。