Agent Harness 性能调优系统：技能注册表、本能层、持久化记忆与安全边界的设计与实现

在 AI Agent 系统的工程实践中，harness（运行时框架）的性能调优往往决定了 agent 在生产环境中的实际表现。不同于单纯的任务执行层，harness 承担着工作流编排、上下文管理、安全审计与持续学习等多重职责。everything-claude-code 项目经过 10 个月以上的日常高强度使用迭代，形成了一套完整的 agent harness 性能优化体系，涵盖技能注册表、本能层、持久化记忆与安全边界四大核心模块。本文将深入解析其架构设计与可落地的工程参数。

技能注册表：SKILL.md 的可移植性契约

everything-claude-code 的技能系统以 SKILL.md 为核心原子单元，每个技能本质上一份声明式的行为契约，其价值在于跨项目、跨 harness 的复用能力。该项目的技能注册表经历了从版本迭代到选择性安装的架构演进，目前支持 182 个技能，覆盖前端、后端、测试、安全、运维等多个领域。

SKILL.md 的结构规范

一个合格的 SKILL.md 文件必须在文件头部包含 YAML frontmatter，明确声明技能的名称、描述与来源：

---
name: continuous-learning-v2
description: Instinct-based learning system that observes sessions via hooks...
origin: ECC
version: 2.1.0
---

这一设计的核心价值在于技能的自我描述性。当 agent 被调度时，harness 可以通过解析 frontmatter 快速判断技能的适用范围，而无需读取完整的技能内容。skills 目录下采用 skills/<skill-name>/SKILL.md 的目录结构，使得技能成为自包含的单元，可以独立安装或移除。

技能热加载与选择式安装

v1.9.0 引入的 manifest 驱动安装管线是技能注册表的关键架构改进。通过 install-plan.js 与 install-apply.js，系统实现了细粒度的选择性安装：

# 仅安装核心开发技能
npx ecc consult "code review patterns" --target claude

# 按需选择性安装特定领域技能
./install.sh --target claude --modules hooks-runtime,tdd-workflow,security-review

这一机制解决了传统插件一刀切安装带来的上下文污染问题。每个技能占用的 token 数、执行的 hook 触发频率都可以独立控制，使得在低上下文窗口或本地模型环境下也能保持系统可用性。

技能与子 agent 的协同

技能（skill）与子 agent（agent）在 everything-claude-code 中承担不同角色。技能描述工作流程和约束规范，例如 TDD workflow 规定了「先写失败测试、再实现最小代码、最后重构」的循环模式；子 agent 则是具体任务的执行委托对象，例如 typescript-reviewer 专注于 TypeScript 代码的质量审查。两者的协同通过 harness 的编排层实现：当 /plan 命令生成实现蓝图后，TDD workflow 技能接管开发节奏，code-reviewer 子 agent 则在关键节点执行质量门禁检查。

本能层：Instinct-Based 的增量学习架构

本能层是 everything-claude-code v2 版本的核心创新，它将传统的「从会话中提取模式」升级为「基于置信度的本能进化系统」。与 GenericAgent 的 skill-tree 自演进不同，本能层更强调原子化观察与跨项目隔离机制。

本能的数据模型

本能（Instinct）是比技能更小的学习单元，每个本能仅包含单一触发条件与单一行为建议：

---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# Prefer Functional Style

## Action
Use functional patterns over classes when appropriate.

## Evidence
- Observed 5 instances of functional pattern preference
- User corrected class-based approach on 2025-01-15

这一模型的核心设计原则是原子性 —— 每个本能只描述一个观察结果，避免了传统 skill 过于宽泛导致的上下文混淆。置信度（confidence）字段采用 0.3 到 0.9 的评分体系，其中 0.3 表示试探性建议，0.9 表示近乎确定的行为规范。

项目级隔离与全局提升

v2.1 版本引入的项目级作用域是本能层的重要演进。项目检测机制按优先级使用 CLAUDE_PROJECT_DIR 环境变量、git remote URL 哈希或仓库根路径，确保同一代码库在不同机器上获得一致的项目 ID：

# 项目 ID 生成逻辑（伪代码）
if (env.CLAUDE_PROJECT_DIR) {
  project_id = hash(env.CLAUDE_PROJECT_DIR)
} else if (git_remote = `git remote get-url origin`) {
  project_id = hash(git_remote)  # 跨机器一致
} else {
  project_id = hash(git rev-parse --show-toplevel)  # 机器相关
}

项目级隔离解决了跨项目本能污染问题：React 项目的函数式编程偏好不会泄漏到 Python 数据科学项目中。当同一本能模式在两个以上项目以 0.8 以上平均置信度被重复观测时，系统会建议将其提升为全局本能，这一过程通过 /promote 命令或 instinct-cli.py promote 脚本执行。

观察机制：从技能驱动到 Hook 驱动

v1 版本的观察机制依赖 Stop hook 触发技能执行，这种方式在 Claude Code 会话结束时概率性运行，可靠性约 50-80%。v2 将观察下沉到 PreToolUse 与 PostToolUse 级别的 hook，确保每一次工具调用都被捕获：

// observe.sh 的核心逻辑
const observation = {
  timestamp: new Date().toISOString(),
  tool_name: input.tool_name,
  tool_input: sanitize(input.tool_input),  // 移除敏感信息
  project_id: detectProject(),
  outcome: input.tool_output ? 'success' : 'failure'
};
appendToFile(`projects/${project_id}/observations.jsonl`, observation);

这种确定性观察带来了一个关键优势：所有训练数据都被系统性地覆盖，不会因为会话提前结束或 agent 中断而丢失观察窗口。

持久化记忆：Hook 驱动的上下文管理

持久化记忆系统解决的核心问题是：agent 在多次会话之间如何保持上下文连续性。everything-claude-code 通过多层 hook 机制构建了完整的会话生命周期管理体系。

会话生命周期 Hook 架构

系统在会话的四个关键节点注入持久化逻辑：

SessionStart hook 是记忆恢复的关键环节。它通过 session-start.js 脚本实现上下文注入：

// session-start.js 核心流程
async function loadSessionContext() {
  const sessionHistory = readRecentSessions();
  const pendingTasks = loadPendingTasks();
  const projectState = loadProjectMetadata();
  
  const contextBlock = [
    "Recent session summary:",
    sessionHistory.map(s => `• ${s.date}: ${s.summary}`).join('\n'),
    "",
    "Pending tasks:",
    pendingTasks.map(t => `• ${t}`).join('\n')
  ];
  
  // 输出到 Claude 的初始上下文
  console.log(contextBlock.join('\n'));
}

会话启动时注入的上下文被限制在 8000 字符以内，通过 ECC_SESSION_START_MAX_CHARS 环境变量可调；对于低上下文或本地模型环境，可直接设置 ECC_SESSION_START_CONTEXT=off 完全禁用该功能。

战略压缩与上下文管理

Strategic Compact 技能是上下文管理的核心指导模块。它建议在逻辑断点处执行手动压缩，而非依赖 auto-compaction 在 95% 上下文时自动触发。压缩决策矩阵如下：

• 立即压缩：研究 / 探索完成后、实施开始前；里程碑完成、下一阶段开始前
• 禁止压缩：实现中途（会丢失变量名、文件路径、部分状态）；调试过程中（会丢失堆栈上下文）

# 设置 auto-compaction 阈值为 50%（默认 95%）
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

# 建议的日常压缩时机
# - 上午开始新任务前
# - 每次代码评审通过后
# - 每次 PR 合并后
/claude compact

记忆存储的分层设计

持久化记忆采用三层存储架构以平衡访问速度与存储成本：

// ~/.claude/homunculus/ 目录结构
{
  "identity.json":      // 用户画像：技术栈熟练度、偏好设置
  "projects.json":      // 项目注册表：项目哈希到元数据的映射
  "observations.jsonl": // 全局观察日志（fallback）
  "instincts/": {
    "personal/":        // 全局自动学习的本能
    "inherited/":       // 全局导入的本能
  },
  "evolved/": {
    "agents/":          // 从本能进化而来的 agent
    "skills/":          // 从本能进化而来的 skill
    "commands/":        // 从本能进化而来的命令
  },
  "projects/": {
    "<project-hash>/":  // 项目级隔离存储
  }
}

项目级存储在 v2.1 中成为默认行为，而 SQLite 状态存储（v1.9.0 引入）则为大规模数据的查询提供了结构化支持。

安全边界：AgentShield 与运行时防护

安全边界模块确保 agent 的行为在可控范围内执行。everything-claude-code 的安全体系包含静态分析与运行时防护两层机制。

AgentShield 的静态扫描能力

AgentShield 是 Anthropic Hackathon 的获奖作品，提供 1282 项测试用例覆盖与 102 条静态分析规则。扫描范围涵盖五大类别：

# 快速安全扫描
npx ecc-agentshield scan

# 自动修复安全级别问题
npx ecc-agentshield scan --fix

# 深度分析模式（使用三 Opus 4.6 agents）
npx ecc-agentshield scan --opus --stream

--opus 标志启动红队 / 蓝队 / 审计员三 agent 流水线：攻击者 agent 寻找漏洞利用链，防御者 agent 评估现有防护措施，审计员 agent 综合两方输出生成优先级风险评估报告。这种对抗性推理模式超越了传统的模式匹配安全扫描。

Hook 层的安全执行控制

Hook 系统本身也承担安全边界职责。PreToolUse hook 可以通过 exit code 2 阻断危险操作：

// 敏感文件访问阻断示例
if (tool_name === 'Read') {
  const blockedPatterns = [
    /\.env$/,           // 环境变量文件
    /\.key$/,           // 私钥文件
    /\.pem$/,           // 证书文件
    /credentials/        // 凭证目录
  ];
  
  if (blockedPatterns.some(p => p.test(file_path))) {
    console.error('[Hook] BLOCKED: Access to sensitive file denied');
    process.exit(2);  // 阻断工具执行
  }
}

beforeTabFileRead hook 在 Cursor IDE 中专门防止 Tab 工具读取敏感文件，同样通过 exit code 2 实现阻断。

MCP 服务的风险隔离

每个 MCP 工具描述在 200k 上下文窗口中消耗约 15k token，当启用超过 10 个 MCP 服务时，实际可用上下文可能降至 70k 以下。ECC 提供 ECC_DISABLED_MCPS 环境变量用于过滤安装时生成的 MCP 配置：

# 禁用可能引入安全风险的 MCP 服务
export ECC_DISABLED_MCPS="github,context7,exa,playwright,sequential-thinking,memory"

运行时 MCP 的启用 / 禁用则通过 Claude Code 的 /mcp 命令管理，该选择被持久化到 ~/.claude.json 中。

运行时配置参数速查表

以下是在实际生产环境中调优 everything-claude-code harness 的核心参数：

总结：Harness 性能优化的工程层级

everything-claude-code 的架构设计体现了 agent harness 性能调优的工程层级差异。在技能注册表层，通过 SKILL.md 的可移植性契约实现跨项目、跨 harness 的知识复用；在本能层，通过原子化观察与项目级隔离实现持续学习而不引入跨域污染；在持久化记忆层，通过多层 hook 驱动的会话生命周期管理实现上下文跨会话延续；在安全边界层，通过静态分析与运行时防护的结合确保 agent 行为在可控范围内。

这套体系的工程化价值在于：每个模块都可以独立调参、独立禁用、独立升级，而无需重新设计上层抽象。当团队在 AI-Trader 交易流水线或 UI-TARS-desktop 多模态 agent 等应用层面工作时，harness 性能调优系统提供了底层的运行时保障，使上层业务逻辑可以专注于任务本身的实现而非基础设施的维护。

资料来源：GitHub affaan-m/everything-claude-code，v2.0.0-rc.1 版本架构文档与持续学习 v2.1 技能规范。

ai-systems