precision-mastery

资源

scripts/
  validate-precision-usage.sh
references/
  tool-reference.md

精准掌控

精准引擎为原生工具（Read、Edit、Write、Grep、Glob、WebFetch）提供了节省 Token 的替代方案。正确使用时，文件操作可节省 75-95% 的 Token。本指南将教你如何实现最佳用法。

冗余度速查表

使用满足需求的最低冗余度。冗余度会直接影响 Token 消耗。

操作	默认值	建议值	原因
precision_write	standard	count_only	内容由你提供；只需确认成功
precision_edit	with_diff	minimal	确认已应用；除非正在调试，否则跳过差异
precision_read	standard	standard	你需要查看内容
precision_grep（发现）	standard	files_only，通过 output.format 设置	这是发现阶段，而非内容阶段
precision_grep（内容）	standard	matches，通过 output.format 设置	需要实际匹配的行
precision_glob	standard	paths_only，通过 output.format 设置	你需要文件路径，而非统计信息
precision_exec（验证）	standard	minimal	除非需要完整的 stdout/stderr
precision_exec（调试）	standard	standard	需要输出以进行诊断
precision_fetch	standard	standard	你需要查看内容
discover	files_only（verbosity 参数）	files_only	这是发现阶段，而非内容阶段
precision_symbols	locations（verbosity 参数）	locations	通常只需文件:行号

Token 倍数：

• count_only：约 0.05x Token
• minimal：约 0.2x Token
• standard：约 0.6x Token
• verbose：1.0x Token

黄金法则：对于不需要读回刚写入内容的写入/编辑操作，使用 count_only。

选择提取模式（precision_read）

读取文件前，先确定你需要从中获取什么。与读取完整内容相比，提取模式可减少 60-95% 的 Token 消耗。

模式	使用场景	Token 节省比例	示例用途
content	需要读取/理解完整文件	0%	读取配置文件、读取待编辑的代码
outline	需要了解结构，但不需要内容	60-80%	了解文件组织、查找函数
symbols	需要导入所需的导出符号	70-90%	构建导入语句、分析 API 表面
ast	需要结构模式	50-70%	重构、模式检测
lines	需要特定行范围	80-95%	grep 找到位置后读取特定函数

最佳实践：

1. 先用 outline 了解文件结构
2. 构建导入内容或了解 API 表面时使用 symbols
3. grep 找到位置后，使用 range: { start, end } 配合 lines
4. 只有在确实需要完整文件时才使用 content

# Step 1: Get structure
precision_read:
  files: [{ path: "src/components/Button.tsx", extract: outline }]
  verbosity: standard

# Step 2: If you need full content, read it
precision_read:
  files: [{ path: "src/components/Button.tsx", extract: content }]
  verbosity: standard

批处理模式

批处理是最重要的 Token 节省技巧。只要可行，就始终批处理操作。

1. 多文件读取（单次调用）

使用一次 precision_read 调用读取 5-10 个文件，而不是分 5-10 次调用。

# Bad (5 separate calls)
precision_read:
  files: [{ path: "file1.ts" }]
precision_read:
  files: [{ path: "file2.ts" }]
# ...

# Good (1 batched call)
precision_read:
  files: [
    { path: "file1.ts", extract: outline },
    { path: "file2.ts", extract: outline },
    { path: "file3.ts", extract: outline },
    { path: "file4.ts", extract: outline },
    { path: "file5.ts", extract: outline }
  ]
  verbosity: minimal

2. 多查询发现（单次调用）

在一次 discover 调用中同时运行 grep、glob 和 symbols 查询。这是最强大的发现模式。

discover:
  queries:
    - id: find_components
      type: glob
      patterns: ["src/components/**/*.tsx"]
    - id: find_api_routes
      type: glob
      patterns: ["src/api/**/*.ts", "src/app/api/**/*.ts"]
    - id: find_auth_usage
      type: grep
      pattern: "useAuth|getSession|withAuth"
      glob: "src/**/*.{ts,tsx}"
    - id: find_hooks
      type: symbols
      query: "use"
      kinds: ["function"]
  verbosity: files_only

这很重要的原因：并行执行意味着所有 4 个查询约 50ms 即可完成，而顺序执行则需要约 200ms。

3. 多编辑原子事务（单次调用）

在一次 precision_edit 调用中，使用原子事务跨文件应用多项编辑。如果任何一项编辑失败，所有更改都会回滚。

precision_edit:
  edits:
    - path: "src/components/Button.tsx"
      find: "export default Button"
      replace: "export { Button as default }"
    - path: "src/components/index.ts"
      find: "export { default as Button } from './Button'"
      replace: "export { Button } from './Button'"
  transaction:
    mode: "atomic"
  verbosity: minimal

4. 多文件写入（单次调用）

使用一次 precision_write 调用创建多个文件。

precision_write:
  files:
    - path: "src/features/user/index.ts"
      content: |
        export * from './types';
        export * from './api';
        export * from './hooks';
    - path: "src/features/user/types.ts"
      content: |
        export interface User {
          id: string;
          email: string;
          name: string;
        }
    - path: "src/features/user/api.ts"
      content: |
        import type { User } from './types';
        export const getUser = async (id: string): Promise<User> => { /* ... */ };
  verbosity: count_only

5. 批量使用精确工具（最佳）

最高效的批处理方式：将多个精确调用封装在单个事务中。

每种操作类型（read、write、exec、query）都使用对应的 precision_engine 工具架构。例如：

• read 操作使用 precision_read 架构（带有 files 数组）
• write 操作使用 precision_write 架构（带有 files 数组）
• exec 操作使用 precision_exec 架构（带有 commands 数组）
• query 操作使用 precision_grep/precision_glob 架构

batch:
  operations:
    read:
      - files:
          - path: "src/types.ts"
            extract: symbols
    write:
      - files:
          - path: "src/features/auth/types.ts"
            content: |
              export interface User {
                id: string;
                email: string;
                name: string;
              }
    exec:
      - commands:
          - cmd: "npm run typecheck"
            expect:
              exit_code: 0
  config:
    transaction:
      mode: atomic
  verbosity: minimal

Token 预算与分页

对于大型文件或批量读取，使用 token_budget 控制输出大小。

# Read up to 20 files, but cap total output at 5K tokens
precision_read:
  files: [
    { path: "file1.ts" },
    { path: "file2.ts" },
    # ...
  ]
  token_budget: 5000
  page: 1  # Start with page 1
  verbosity: standard

如果结果被截断，请递增 page 以获取下一批结果。

输出格式选择（precision_grep）

precision_grep 有多种输出格式：count_only、files_only、locations、matches、context。

格式	使用场景	Token 成本
count_only	评估范围	很低
files_only	发现阶段	低
locations	查找内容所在位置	中
matches	需要实际匹配的行	高
context	需要周边代码	很高

渐进式披露：先使用 count_only 评估范围，再用 files_only 建立目标列表，然后用 matches 获取内容。

探索工具编排

discover 工具是一个元工具，可并行运行多个查询（grep、glob、symbols）。实现前务必先使用它。

探索模式：

1. 使用多个查询运行 discover
2. 分析结果以了解范围
3. 根据探索结果规划工作
4. 使用批处理执行

# Step 1: Discover
discover:
  queries:
    - id: existing_files
      type: glob
      patterns: ["src/features/auth/**/*.ts"]
    - id: existing_patterns
      type: grep
      pattern: "export (function|const|class)"
      glob: "src/features/**/*.ts"
  verbosity: files_only

# Step 2: Read key files with outline based on discovery
precision_read:
  files: [{ path: "src/features/auth/index.ts", extract: outline }]
  verbosity: minimal

# Step 3: Execute based on what was discovered
precision_write:
  files:
    - path: "src/features/auth/middleware.ts"
      content: "..."
  verbosity: count_only

precision_exec 模式

1. 后台进程

在后台运行长时间进程，以避免阻塞。

precision_exec:
  commands:
    - cmd: "npm run dev"
      background: true
  verbosity: minimal

2. 重试模式

自动重试不稳定的命令。

precision_exec:
  commands:
    - cmd: "npm install"
      retry:
        max: 3
        delay_ms: 1000
  verbosity: minimal

3. 持续检查模式

轮询，直到满足条件。

precision_exec:
  commands:
    - cmd: "curl http://localhost:3000/api/health"
      until:
        pattern: "ok"
        timeout_ms: 30000
  verbosity: minimal

precision_fetch 模式

1. 批量 URL

在一次调用中获取多个 URL。

precision_fetch:
  urls:
    - url: "https://api.example.com/users"
    - url: "https://api.example.com/posts"
    - url: "https://api.example.com/comments"
  verbosity: standard

2. 提取模式

从 JSON 响应中提取特定数据。

precision_fetch:
  urls:
    - url: "https://api.example.com/users"
      extract: json  # Extract mode: raw, text, json, markdown, structured, etc.
  verbosity: standard

3. 服务注册表身份验证

使用预配置服务自动进行身份验证。

precision_fetch:
  urls:
    - url: "https://api.openai.com/v1/models"
      service: "OpenAI"  # Auto-applies bearer token from config
  verbosity: standard

反模式（绝对不要这样做）

1. 使用原生工具：应避免使用 Read、Edit、Write、Glob、Grep、WebFetch。请使用对应的 precision 工具。

2. 为写入/编辑设置 verbosity 为 "verbose"：这会浪费 Token。你刚写完内容，为什么还要读回来？

3. 只需要大纲/符号时却读取整个文件：请使用提取模式。

4. 一次只运行一个 discover 查询：应批量运行。

5. 明明 precision_grep 更快却使用 precision_read：Grep 针对搜索进行了优化。

6. 读取刚写入的文件：你已经知道内容。

7. 实现前不使用 discover：盲目实现会导致模式不匹配。

8. 连续多次调用本可批处理的 precision 工具：如果要对同一工具调用 3 次或更多次，请批处理。

9. 默认使用 verbosity: verbose：仅在调试时使用。

10. 批量读取大型内容时忽略 token_budget：不设预算可能会导致结果被截断。

升级处理流程

如果精确工具失败：

1. 检查错误：是用户错误（路径错误、语法错误）吗？修正后重试。

2. 如果工具确实失败：仅针对该特定任务使用原生工具。

3. 返回使用精确工具：处理下一个操作时继续使用。

4. 记录失败情况：写入 .goodvibes/memory/failures.json。

示例：

• precision_read 读取特定文件失败 => 仅对该文件使用 Read，其他文件继续使用 precision_read。
• precision_edit 执行特定编辑失败 => 仅对该编辑使用 Edit，其他编辑继续使用 precision_edit。

绝对不要：因为一次调用失败就完全放弃精确工具。

决策树：使用哪个工具？

Do I know the exact file paths?
  |-- Yes -- precision_read (with appropriate extract mode)
  +-- No -- Do I know a pattern?
      |-- Yes -- precision_glob
      +-- No -- Am I searching for content?
         |-- Yes -- precision_grep
         +-- No -- Am I searching for symbols?
            |-- Yes -- precision_symbols
            +-- No -- Use discover with multiple query types

专用工具（不在上方的树中）：

• precision_notebook — Jupyter 笔记本单元格操作（通过 cell_id 定位进行替换／插入／删除）
• precision_agent — 通过基于档案的上下文注入启动无头 Claude 会话
• precision_config — 运行时配置（获取／设置／重新加载）

性能基准

节省令牌：

• outline 与 content 相比：节省 60-80%
• symbols 与 content 相比：节省 70-90%
• count_only 与 verbose 相比：节省 95%
• 批量处理 5 个文件与分 5 次单独调用相比：节省 40-60%（减少开销）
• 并行 discover（4 倍）与顺序执行相比：提速 75%，令牌成本相近

节省时间：

• 并行 discover（4 个查询）：约 50 毫秒，顺序执行约 200 毫秒
• 批量写入（5 个文件）：约 80 毫秒，分开处理约 400 毫秒
• 使用事务批量编辑：失败时原子回滚

快速参考

最常见的模式：

# 1. Discover before implementing
discover:
  queries:
    - id: files
      type: glob
      patterns: ["pattern"]
    - id: patterns
      type: grep
      pattern: "regex"
  verbosity: files_only

# 2. Read with outline first
precision_read:
  files: [{ path: "file.ts", extract: outline }]
  verbosity: minimal

# 3. Batch writes with count_only
precision_write:
  files:
    - { path: "file1.ts", content: "..." }
    - { path: "file2.ts", content: "..." }
  verbosity: count_only

# 4. Batch edits with atomic transaction
precision_edit:
  edits:
    - { path: "f1.ts", find: "...", replace: "..." }
    - { path: "f2.ts", find: "...", replace: "..." }
  transaction: { mode: "atomic" }
  verbosity: minimal

# 5. Verify with minimal output
precision_exec:
  commands:
    - { cmd: "npm run typecheck", expect: { exit_code: 0 } }
  verbosity: minimal

---

请记住：precision 引擎可以节省令牌，但前提是选择合适的详细程度、提取模式和批处理模式。将此技能作为高效使用工具的速查表。