从Harness架构到Token经济学的探索

模型能看到什么（存什么、取什么、怎么呈现）
模型的行为边界在哪里（什么能做、什么不能做）
模型如何知道自己做对了（验证、反馈、修正）

┌──────────────────────────────────────────────────────────────────┐
│                  Harness 双环控制结构                             │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │               前馈控制（开环）                            │     │
│  │                                                         │     │
│  │  设计时注入 ──► Rules / Skills ──► AI 推理上下文          │     │
│  │  （先验知识）    （约束边界）        （行动之前就生效）      │     │
│  └─────────────────────────────────────────────────────────┘     │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │               反馈控制（闭环）                            │     │
│  │                                                         │     │
│  │  AI 行动 ──► 检测结果 ──► 偏差计算 ──► 阻止/纠正            │     │
│  │             （Hooks）    （质量阈值）   （deny/ask）       │     │
│  └─────────────────────────────────────────────────────────┘     │
│                                                                  │
│  工程映射：Rules（前馈）+ Hooks（反馈）= Harness 的双保险            │
└──────────────────────────────────────────────────────────────────┘

Thought（思考）→ Action（工具调用）→ Observation（观察结果）→ Thought（下一轮）...

// .codebuddy/settings.json — PreToolUse 阶段
{
  "matcher": "Write|Edit",
  "hooks": [
    { "command": ".../protect-files.sh" },      // Action 前：敏感文件保护
    { "command": ".../search-gate.js" },        // Action 前：首次写入提醒先搜索
    { "command": ".../suggest-compact.js" }     // Action 前：工具调用次数检查
  ]
}

<!-- .codebuddy/rules/ai-coding-defense.md（alwaysApply） -->
## 8 条编码红线（来自真实 Bug）
1. 方案切换必须清理残留 —— 切换后全文搜索旧关键词
2. 通用控件保护 —— 改公共组件前先评估引用方
3. 改动完整性 —— template/script/style 同步
4. 场景全覆盖 —— 多端、多调用方、多层守卫
5. 避免策略反复 —— 先了解全部约束再定方案
6. 异步操作所有路径必须有终态 —— loading 必须重置
7. Vue 响应式纯净性 —— computed/Pinia getter 禁止副作用
8. 调试硬编码必须打标记并清理 —— [xxx-debug] / __DEBUG_*__

# .codebuddy/memory/ 目录结构
memory/
├── MEMORY.md          # 长期记忆（项目约定、技术决策等核心结论）
├── 2026-06-09.md      # 当日工作记录（每次完成实质性工作后追加）
└── archive/           # 归档（30天以上的旧记录，不再注入）

// .codebuddy/settings.json
"SessionStart": [{
  "matcher": "compact",
  "hooks": [{
    "command": "echo '项目 关键约定（compact 后重新注入）：1) pnpm 2) request.ts ...'"
  }]
}]

<!-- .codebuddy/skills/项目-dev/SKILL.md 阶段2 节选 -->
## 阶段 2：代码设计
1. 搜索项目中类似功能的现有实现
2. 评估复用 vs 新建 → 优先复用
3. 如果新建，出 2-3 个方案 → 列出每个的优缺点
4. 用户确认方案后再进入阶段3

<!-- .codebuddy/rules/ 分级设计 -->
L1 核心（alwaysApply）：project-rules.md / ai-coding-defense.md
  → 永久剪枝：AI 永远不会考虑「用 npm 而不是 pnpm」这种错误分支

L2 场景（按需）：atomic-step-commit / search-first / debug-residue
  → 条件剪枝：只在特定场景下才生效，不浪费 token

// .codebuddy/hooks/suggest-compact.js
const THRESHOLD = 35;  // 从 50 调优到 35
// 工具调用超过 35 次 → 建议 /compact

# .codebuddy/hooks/impact-analysis.sh
# 改公共组件时，自动 grep 全仓库引用方
# 输出：影响 N 个文件，M 个调用点
# → 评估值 = 影响面大小，帮助决定是否继续展开这个分支

无 Harness 的搜索空间：
  N 个可能的操作，每步有 N 种选择 → 路径空间 = N!（阶乘爆炸）

加上 Rules（约束）后：
  「禁止 10 类操作」+ 「必须按 5 步流程」→ 路径空间 ≈ k×N（线性）

信息论解释：
  Rules = 先验知识注入 → H(行动|规则) << H(行动) → 搜索熵大幅下降

这就是为什么「壳越精巧，模型表现越好」：
  不是模型变聪明了，是它需要搜索的空间被大幅压缩了。

┌─────────────────────────────────────────────────────────────────┐
│                     CodeBuddy IDE Runtime                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Commands（入口）    Skills（能力）       Rules（约束）            │
│  /review-commit     项目-dev            ai-coding-defense      │
│  /review-branch     quick-iterate        project-rules          │
│  /deploy-test       figma-to-code        search-first           │
│                     proto-sync           atomic-step-commit     │
│                     git-commit-push      debug-residue          │
│                                                                 │
│  Hooks（自动兜底）                                               │
│  guard-commands / commit-quality / protect-files                │
│  config-protection / search-gate / suggest-compact              │
│  post-edit-accumulator / large-file-blocker / impact-analysis   │
│  stop-format-typecheck                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

用户发出指令
    │
    ▼
Agent 决定调用工具（Write / Edit / Bash）
    │
    ├──► PreToolUse Hooks（行动之前）
    │    ├── guard-commands.sh    ─ 危险命令？→ deny 阻止
    │    ├── commit-quality.sh   ─ 质量不过？→ deny 阻止
    │    ├── protect-files.sh    ─ 敏感文件？→ deny 阻止
    │    ├── config-protection.sh─ 配置文件？→ ask 询问用户
    │    ├── search-gate.js      ─ 首次写入业务目录？→ allow + 提醒
    │    └── suggest-compact.js  ─ 调用超 35 次？→ allow + 提醒
    │
    ▼ 全部放行后，工具执行
    │
    ├──► PostToolUse Hooks（行动之后）
    │    ├── post-edit-accumulator.js ─ 累积编辑文件路径
    │    ├── large-file-blocker.sh    ─ 文件 > 400 行？→ 提醒拆分
    │    ├── impact-analysis.sh       ─ 改公共组件？→ 自动影响面分析
    │    └── post-commit-review.sh    ─ commit ≥ 3 文件？→ 提醒 /review-commit
    │
    ▼ Agent 停止时
    │
    └──► Stop Hook
         └── stop-format-typecheck.js ─ 批量 eslint --fix + 调试扫描

用户说了什么？
├── 提到 Figma 链接              → figma-to-code
├── 「更新 proto」「同步接口」     → proto-sync（disable-model-invocation）
├── 完整需求 + 设计稿 + 多文件    → 项目-dev
├── 简短修改指令（< 20 字）       → quick-iterate
├── 「提交」「推送」「commit」     → git-commit-push（disable-model-invocation）
└── 不确定                       → 不加载 Skill，按 rules 执行

阶段 1：需求理解 + Plan 创建
  → 读 Figma/需求文档 → 拆解步骤 → 两轮自我优化（边界条件 + 测试矩阵）

阶段 2：代码设计
  → 读现有类似实现 → 确定方案（不新建轮子）→ 用户确认

阶段 3：编码实现
  → 按 Plan 分步 → 每步 lint/type-check → 每步提交

阶段 4：验证测试
  → 端到端验证 → 边界回归 → 再优化一轮

阶段 5：沉淀
  → 写 plan 实施记录 → 更新 memory → 更新 docs/dev/

错误做法（反模式）：
  一口气改 10 个文件 → 统一提交 → 发现问题不知道哪步引入的
正确做法：
  步骤 1：store 新增字段 → lint + type-check → commit feat(store): ...
  步骤 2：API 层封装 → lint + type-check → commit feat(api): ...
  步骤 3：组件消费 → lint + type-check → commit feat(component): ...
  最终：整体验证 + 再优化一轮 → 用户 review

任务有多复杂？
├── 3+ 文件联动 / Skill 加载 / 架构设计   → Claude
│   （原因：需要大窗口承载 Skill ~11K + Rules ~15K + 多文件代码）
├── 单文件修改 / 中等 bug / proto 同步     → DeepSeek / Hy3
│   （原因：上下文需求小，性价比高，速度快）
├── 批量操作 / 文案文档 / 零碎问答        → GLM
│   （原因：不需要复杂推理，最省 token）
└── 不确定                               → Auto 或 DeepSeek

Claude（~25%）    → 关键任务：新功能开发、代码审查、架构设计、上线前 review
DeepSeek（~50%）  → 日常主力：bug fix、样式调整、proto 同步、git 提交
GLM（~15%）       → 批量/轻量：改文案、问答、文档注释
Hy3（~10%）       → 尝鲜/备选：日常开发验证

每次对话基础开销分解（项目，优化后）：
─────────────────────────────────────────────
System Prompt（IDE 内置，不可控）          ~5K tokens
─────────────────────────────────────────────
alwaysApply Rules
├── project-rules.md（精简后）             ~3.5K tokens
├── ai-coding-defense.md                  ~1.5K tokens
└── plan-cleanup.mdc                      ~800 tokens
小计                                       ~5.8K tokens
─────────────────────────────────────────────
workspace_rules（IDE 自动注入）            ~5K tokens（去重后）
─────────────────────────────────────────────
Memories（自动注入）                       ~500-1K tokens
─────────────────────────────────────────────
合计基础开销                               ~15K tokens
═════════════════════════════════════════════

Attention(Q, K, V) = softmax(QK^T / √d_k) · V

其中：
  Q = 当前 token 的 Query 向量
  K = 所有历史 token 的 Key 向量矩阵  ← 每次推理都要重新计算，代价极大
  V = 所有历史 token 的 Value 向量矩阵 ← 同上

KV Cache：把已经计算过的 K/V 向量缓存起来，下次推理直接复用
  → 前缀相同的请求，缓存命中 → 计算成本降至 ×0.1

┌─────────────────────────────────────────────────────────────────┐
│                  KV Cache 工程全景                               │
│                                                                 │
│  1. 前缀缓存（Prefix Caching）                                   │
│  ─────────────────────────────                                  │
│  System Prompt + alwaysApply Rules（~15K tokens）               │
│       │                                                         │
│       ▼ 第一次请求：full compute                                 │
│       ▼ 后续请求：cache hit → ×0.1 成本                          │
│                                                                 │
│  结论：稳定的 Rules 文本 = 高命中率 = 实际成本远低于字面字数         │
│                                                                 │
│  2. 多轮对话复用                                                 │
│  ──────────────                                                 │
│  同一会话多轮 → 相同前缀 KV 直接复用，不重新 prefill                │
│  这是为什么「长对话」不如「长×单价」那么贵                           │
│                                                                 │
│  3. Agent 多轮工具调用                                           │
│  ───────────────────                                            │
│  ReAct 循环中，每次 Observation 追加到序列尾部                     │
│  前面的 KV 已缓存 → 只需计算新增 token 的 KV                       │
│  智能体密集调用工具时，KV Cache 是性能的关键支撑                     │
└─────────────────────────────────────────────────────────────────┘

智能体多轮工具调用、长代码库上下文极度依赖高性能 KV Cache。
Harness 调度层还要做：

├── 多会话 KV 隔离
│   不同用户的会话 KV 不能共用（安全边界），
│   但同一用户的多轮对话要尽量复用（命中前缀缓存）
│
├── 过期上下文回收
│   超过窗口的 KV 及时释放（prevent memory leak），
│   /compact 命令触发的就是这个机制的应用层接口
│
└── 前缀树管理（Radix Tree）
    相同前缀的请求共享 KV 存储，
    这是 alwaysApply Rules「一次计算，多次复用」的底层支撑

原始问题：~23.5K 基础开销中，有 ~8.5K 是「重复注入」或「不必要的 alwaysApply」

① 重复注入（~6K）
  ├── my-rule.mdc 内容 = workspace_rules「Homepage 项目规则」→ 注入两遍
  └── project-rules.md §4 内容 ≈ workspace_rules 各条目描述 → 逐字重复

② 不必要的 alwaysApply（~4.3K）
  ├── atomic-step-commit：只有 10% 的对话需要多步骤流程
  └── search-first：已有 search-gate.js hook 物理提醒，规则层面双重冗余

③ 空白占位（~500）
  └── TODO 占位符、空的章节头、模板示范
修复逻辑：消除重复 + 按需加载 + 清理空白 = 节省 ~8.5K tokens

Token 数 ≈ 中文字符数 ÷ 1.5 + 英文字符数 ÷ 4
快速估算 ≈ 文件字符数 ÷ 2

# 查看所有 alwaysApply Rules 的大小
grep -rl "alwaysApply: true" .codebuddy/rules/ | xargs wc -m

# 查看 memory 总大小
find .codebuddy/memory -name "*.md" -exec wc -m {} + | tail -1

# 检查是否有新增的 alwaysApply 规则
grep -l "alwaysApply: true" .codebuddy/rules/*.md .codebuddy/rules/*.mdc 2>/dev/null

# 查看哪些 Skill 没有设置退出条件（exit condition）
grep -rL "exit\|退出\|DONE\|complete" .codebuddy/skills/*/SKILL.md

# 查看哪些 Skill 是流程型但未设 disable-model-invocation
grep -rL "disable-model-invocation" .codebuddy/skills/*/SKILL.md