gather-plan-apply

资源

scripts/
  validate-gpa-compliance.sh
references/
  examples-and-checklists.md

收集-规划-应用协议（GPA 工作流）

GPA 循环强制执行每个阶段中每种工具类型最多调用一次的工作流，以避免因过度调用工具而浪费令牌。这不是建议，而是所有 GoodVibes Agent 必须遵循的执行模式。

确切工作流

0. LOAD SKILLS (once, before any GPA cycle)
   - Call get_skill_content for role-relevant skills
   - This is NOT part of the GPA cycle itself

1. G — GATHER (1-2 tool calls)
   - Check .goodvibes/memory/ files FIRST (failures, patterns, decisions)
   - Single `discover` call with ALL queries batched inside
   - Multiple query types (glob, grep, symbols, structural) in one call
   - Can search file content via grep/symbols queries
   - Batch any file reads that need full content alongside discover
   - Output: files_only or locations (minimal verbosity)

2. P — PLAN (0 tool calls, cognitive only)
   - Agent thinks about what it learned from GATHER
   - Plans which files to create/write/edit
   - Plans which commands to run for validation
   - Identifies ALL batch opportunities — same-type ops go in one call
   - Plans the EXACT apply call structure

3. A — APPLY (1-2 tool calls)
   - Writes and edits batched into one precision_write or precision_edit call
   - Validation commands batched into one precision_exec call
   - Key: one call per tool type, everything batched inside it

4. LOOP — Back to G if:
   - Results didn't match expectations
   - Scope changed
   - Validation failed

每个周期的调用预算

阶段	工具调用次数	类型	目的
G（收集）	1-2	discover + 可选的 precision_read	所有发现操作 + 读取记忆
P（规划）	0	认知	规划应用操作
A（应用）	1-2	precision_write/precision_edit + precision_exec	所有写入/编辑 + 验证
总计	2-4

核心规则：每个阶段中每种工具类型只调用一次。同一阶段绝不能调用两次 precision_read——应在一次调用中批量读取两个文件。

**关于顺序调用的说明：**当操作存在依赖关系时（例如，先写入再验证），可以顺序调用。始终优先通过内部精度工具数组（文件数组、编辑数组、命令数组）进行真正的批处理。

关键规则（不可妥协）

1. discover 将所有发现查询批量合并到一次调用中——发现时绝不要单独使用 precision_glob、precision_grep
2. 规划步骤不产生任何工具调用——规划属于认知活动（Agent 以文本思考）
3. 每个阶段中每种工具类型只调用一次——如果需要读取 3 个文件，应在一次 precision_read 调用中批量读取
4. 应用阶段的输出 = 1-2 次调用——对文件使用 precision_write/precision_edit，对命令使用 precision_exec
5. ToolSearch 不属于 GPA——在开始时加载工具，不要在周期中途搜索
6. 优先检查记忆——实施前始终读取 .goodvibes/memory/

阶段 1：收集（1-2 次调用）

初始设置：检查记忆

发现文件前，先检查已有信息。将记忆读取与 discover 调用批量处理，或作为单独的一次读取调用：

# GOOD: Memory reads batched with file content reads
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/patterns.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

discover 工具

discover 工具会并行运行多个 grep/glob/符号/结构查询，并按查询 ID 返回结果。这是主要的发现机制。

模式：批量处理所有发现查询

# GOOD: 1 discover call with everything
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"
    - id: exported_hooks
      type: symbols
      query: "use"
      kinds: ["function"]
    - id: console_logs
      type: structural
      structural_pattern: "console.log($$$ARGS)"
  verbosity: files_only

查询类型：

• glob - 按路径模式查找文件
• grep - 查找包含指定模式的文件
• symbols - 查找导出的函数/类型/类
• structural - 查找 AST 模式（例如，函数调用）

输出模式：

• count_only - 仅显示数量（用于评估范围）
• files_only - 仅显示文件路径（用于构建目标列表）← 使用此模式
• locations - 文件路径 + 行号（需要精确位置时使用）

读取完整文件内容

读取完整文件内容时，在收集阶段使用 precision_read，并将其与记忆读取批量处理；如果需要先查看 discover 结果，则作为第二次调用。

[BAD] 与 [GOOD] 收集模式

[BAD] — 顺序执行发现查询（多次工具调用）

# BAD: 4 separate tool calls for discovery
precision_glob:
  patterns: ["src/**/*.ts"]

precision_grep:
  queries:
    - id: exports
      pattern: "export function"

precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"

precision_grep:
  queries:
    - id: imports
      pattern: "import.*from"

[GOOD] — 单次 discover 调用 + 批量读取记忆（2 次工具调用）

# GOOD: 1 discover call with all queries
discover:
  queries:
    - id: files
      type: glob
      patterns: ["src/**/*.ts"]
    - id: exports
      type: grep
      pattern: "export function"
      glob: "src/**/*.ts"
    - id: imports
      type: grep
      pattern: "import.*from"
      glob: "src/**/*.ts"
  verbosity: files_only

# GOOD: Memory reads in one batched call
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/patterns.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

阶段 2：规划（0 次调用，仅认知）

目的

规划属于认知工作，不是工具调用。你需要以文本思考以下内容：

• 要创建/写入哪些文件
• 要编辑哪些文件（使用精确的查找/替换内容）
• 要运行哪些命令进行验证
• 所有批处理机会——同类型操作必须批量处理

输出：书面计划，不进行任何工具调用

计划结构

Plan:
1. Create the following files:
   - src/features/auth/types.ts — User interface
   - src/features/auth/hooks.ts — useAuth hook
   - src/features/auth/index.ts — barrel export

2. Edit the following files:
   - src/app/layout.tsx — wrap App with AuthProvider

3. Validate:
   - npm run typecheck (expect exit 0)
   - npm run lint (expect exit 0)

4. Batch plan:
   - Call 1 (Apply): precision_write with 3 files + precision_edit with 1 edit
   - Call 2 (Apply): precision_exec with 2 commands

[BAD] 与 [GOOD] 规划模式

[BAD] — 含糊的计划会导致顺序调用

Plan:
- Create some files
- Maybe edit layout
- Run typecheck

这会导致：

precision_write: ...   # 1st call
precision_write: ...   # 2nd call! (should be batched)
precision_edit: ...    # 3rd call! (could combine with above pattern)

[GOOD] — 包含精确批处理结构的具体计划

Plan:
1. Write 3 files in 1 precision_write call:
   - src/features/auth/types.ts (symbols)
   - src/features/auth/hooks.ts (content)
   - src/features/auth/index.ts (content)

2. Edit 1 file in 1 precision_edit call:
   - src/app/layout.tsx — wrap with AuthProvider

3. Validate in 1 precision_exec call:
   - npm run typecheck
   - npm run lint

阶段 3：应用（1-2 次调用）

模式：批量处理所有写入/编辑

使用一次 precision_write 调用写入多个文件：

precision_write:
  files:
    - path: "src/features/auth/types.ts"
      content: |
        export interface User {
          id: string;
          email: string;
        }
    - path: "src/features/auth/hooks.ts"
      content: |
        import type { User } from './types';
        export function useAuth(): User | null { /*...*/ }
    - path: "src/features/auth/index.ts"
      content: |
        export * from './types';
        export * from './hooks';
  verbosity: count_only

或者使用一次 precision_edit 调用执行多项编辑：

precision_edit:
  edits:
    - path: "src/app/layout.tsx"
      find: "<App />"
      replace: "<AuthProvider><App /></AuthProvider>"
    - path: "src/middleware.ts"
      find: "export const config = {}"
      replace: "export const config = { matcher: ['/dashboard/:path*'] }"
    - path: "src/lib/api.ts"
      find: "headers: {}"
      replace: "headers: { Authorization: `Bearer ${token}` }"
  verbosity: minimal

通过 precision_exec 验证（应用阶段的第二次调用）：

precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
    - cmd: "npm run lint"
      expect:
        exit_code: 0
  verbosity: minimal

[BAD] 与 [GOOD] 应用批处理

[BAD] — 分别调用 precision_write 3 次

precision_write:
  files:
    - path: "file1.ts"
      content: "..."

precision_write:  # Second call!
  files:
    - path: "file2.ts"
      content: "..."

precision_write:  # Third call!
  files:
    - path: "file3.ts"
      content: "..."

[GOOD] — 一次 precision_write 调用写入 3 个文件

precision_write:
  files:
    - path: "file1.ts"
      content: "..."
    - path: "file2.ts"
      content: "..."
    - path: "file3.ts"
      content: "..."
  verbosity: count_only

阶段 4：循环（何时返回收集阶段）

循环触发条件

1. 结果与预期不符 — 类型检查失败、测试失败或行为异常
2. 范围发生变化 — 探索后发现实际情况与预期不同
3. 出现新信息 — 执行过程中明确了任务要求

循环模式

# Initial GPA cycle
discover: ...          # Gather call 1
precision_read: ...    # Gather call 2 (memory + key files)
precision_write: ...   # Apply call 1
precision_exec: ...    # Apply call 2 — FAILS typecheck

# LOOP: Start new GPA cycle with refined discovery
discover:              # Gather call 1 (new cycle)
  queries:
    - id: find_missing_import
      type: grep
      pattern: "export.*User"
      glob: "src/**/*.ts"
  verbosity: locations  # Need exact location

precision_edit: ...    # Apply call 1 (new cycle) - fix the issue
precision_exec: ...    # Apply call 2 (new cycle) - re-validate

完整示例：实现身份验证功能

第 1 轮：初始实现

步骤 1 — GATHER（2 次调用）

# Call 1: Check memory
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

# Call 2: Discover landscape
discover:
  queries:
    - id: existing_auth
      type: glob
      patterns: ["src/features/auth/**/*.ts", "src/**/auth*.ts"]
    - id: auth_patterns
      type: grep
      pattern: "(useAuth|getSession|AuthProvider)"
      glob: "src/**/*.{ts,tsx}"
    - id: user_types
      type: symbols
      query: "User"
      kinds: ["interface", "type"]
  verbosity: files_only

步骤 2 — PLAN（0 次调用，认知工作）

Gather results:
- No memory failures for auth
- No existing auth files
- No auth patterns in use
- User type exists in src/types/user.ts

Plan:
Apply Call 1 (precision_write): Create 3 auth files
Apply Call 2 (precision_exec): typecheck + lint

步骤 3 — APPLY（2 次调用）

# Call 1: Create files
precision_write:
  files:
    - path: "src/features/auth/provider.tsx"
      content: |
        import { ClerkProvider } from '@clerk/nextjs';
        export function AuthProvider({ children }: { children: React.ReactNode }) {
          return <ClerkProvider>{children}</ClerkProvider>;
        }
    - path: "src/features/auth/hooks.ts"
      content: |
        import { useUser } from '@clerk/nextjs';
        import type { User } from '@/types/user';
        export function useAuth(): User | null {
          const { user } = useUser();
          if (!user) return null;
          return { id: user.id, email: user.emailAddresses[0].emailAddress, name: user.fullName };
        }
    - path: "src/features/auth/index.ts"
      content: |
        export { AuthProvider } from './provider';
        export { useAuth } from './hooks';
  verbosity: count_only

# Call 2: Validate
precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
    - cmd: "npm run lint"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: typecheck FAILS — missing @clerk/nextjs

第 1 轮调用总数：4（precision_read + discover + precision_write + precision_exec）

第 2 轮：修复缺失的依赖项

步骤 1 — GATHER（1 次调用）

discover:
  queries:
    - id: package_json
      type: glob
      patterns: ["package.json"]
    - id: clerk_usage
      type: grep
      pattern: "@clerk/nextjs"
      glob: "src/**/*.{ts,tsx}"
  verbosity: files_only

步骤 2 — PLAN（0 次调用，认知工作）

Discovery: @clerk/nextjs not in package.json
Plan:
Apply Call 1 (precision_exec): npm install @clerk/nextjs, then typecheck

步骤 3 — APPLY（1 次调用）

precision_exec:
  commands:
    - cmd: "npm install @clerk/nextjs"
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: PASSES

第 2 轮调用总数：2（discover + precision_exec）

常见违规及修复方法

违规行为	工具调用次数	修复方法
顺序调用 precision_read	5+	将所有文件合并到 1 次 precision_read 调用中
顺序调用 precision_write	5+	将所有文件合并到 1 次 precision_write 调用中
分别使用 precision_glob + precision_grep	2+	在 1 次 discover 调用中使用两种查询类型
先读取大纲，再读取内容	2	如果之后需要内容，就一次性读取内容
通过工具调用进行规划	1+	以文本形式规划（认知工作 = 0 次调用）
跳过内存读取	-	在 Gather 阶段始终检查 .goodvibes/memory/

执行规范

如果你发现自己在一个阶段中两次使用同一种工具类型，就违反了协议。请停止并重新组织：

1. 找出用于探索的调用 → 合并到 1 次 discover 调用中
2. 找出用于读取内存/文件的调用 → 合并到 1 次 precision_read 调用中
3. 找出用于写入/编辑的调用 → 将同类型调用合并（写入合并在一起，编辑合并在一起）
4. 确保以文本而非工具调用的方式进行规划

目标：每个阶段中每种工具类型只调用一次。

总结

• G（Gather）：检查内存 + discover + 可选的 precision_read 读取关键文件
• P（Plan）：0 次调用（认知工作）
• A（Apply）：使用 precision_write/precision_edit + precision_exec 进行验证
• LOOP：需要时开始新一轮

规则：每个阶段中每种工具类型只调用一次。尽可能在每次调用中批量处理。

将此作为你的默认工作模式。