CodeSmith元能力：Agent的基因组复制与自举

Agent能否修复自身，甚至从零构建新的Agent？CodeSmith项目在v0.5.0版本中给出了一套分层的工程答案。这并非科幻式的"AI自我意识觉醒"，而是一系列务实的技术选择：用确定性规则兜底常见故障，用大模型分析疑难杂症，再用"范例修改"替代"从零生成"来引导Agent编写Agent。

自我诊断：doctor的双层架构

CodeSmith内置了codesmith doctor命令（run_doctor，位于crates/tui/src/main.rs:2310），一次性完成版本与更新状态、配置文件解析、API密钥来源、网络连通性（包括区分DNS失败的提示）、MCP服务器健康度、外部依赖解析以及平台沙箱可用性检查。

需要先泼一盆冷水：doctor的主体是一堆纯确定性检查，不应被夸大为"AI自愈"。但确定性检查本身也有讲究。crates/agent-runtime/src/dependencies.rs中的注释记录了一个真实教训——历史上工具直接调用python3，Windows用户（启动器是py或python）只看到一句干巴巴的"program not found"，没有任何关于缺失内容或安装位置的提示。

修复方案是"先探测，再决策"：候选命令按顺序探测，结果缓存在进程生命周期的OnceLock中（每个候选仅执行一次Command::output，避免每轮模型交互都重复付出代价）：

// crates/agent-runtime/src/dependencies.rs:41
pub const PYTHON_CANDIDATES: &[&str] = &["python3", "python", "py -3"];

顺序是刻意的——python3歧义最少（排除Python 2残留），python覆盖Windows和Homebrew，py -3是Windows启动器。探测使用--version而非which，以保证在Unix、Windows和容器间的可移植性。doctor随后将解析结果转化为各平台的安装建议（macOS上brew install python@3.12，Debian上apt install python3，Windows上winget）。

对比一个更激进的样本：OpenClaw^广告的doctor分三层检测问题（配置异常、状态问题、服务健康），分两级修复（安全修复自动执行，有风险的需用户确认）；对于确定性规则覆盖不了的疑难杂症，交给LLM分析日志、推断原因、生成修复计划。确定性检查确保常见问题可靠修复，LLM兜底长尾谜题。CodeSmith v0.5.0的doctor补齐了这第二层（crates/tui/src/doctor_llm.rs）：确定性检查完成后，收集到的警告/错误被序列化为结构化findings，交给单次咨询式LLM调用推断根因并建议后续操作。确定性结果始终优先，LLM只分析不执行，失败或超时（30秒）则静默跳过。

OnceLock 是 Rust 标准库中的一次性初始化原语（std::sync::OnceLock），它允许一个值在整个进程生命周期内只被写入一次，之后所有访问都是只读的、线程安全的。在这个场景里，CodeSmith 用它缓存“候选解释器探测结果”：第一次需要 Python 时依次执行 python3 --version、python --version 等命令，把最先成功的路径存进 OnceLock；后续无论多少次模型交互、多少轮工具调用，都直接读取缓存，不再 fork 子进程。这样做既省去了重复的进程创建开销（在工具密集的 Agent 循环中这一开销会成倍放大），又保证了同一进程内解析结果一致，避免出现“这一轮找到 python、下一轮又找不到”的非确定性行为。代价是缓存不感知运行期环境变化——若用户在 Agent 运行中途新装了 Python，需要重启进程才能生效。

Agent写Agent：难点在哪里

比自我修复更进一步的是让Agent创建新Agent。先泼第二盆冷水：创建一个高质量Agent远比生成普通应用代码复杂，常见缺陷可以一一映射到CodeSmith自身的模块上。

上下文管理草率：轨迹被压平成纯文本塞进上下文，丢弃了结构化消息的KV Cache优化（价格差距可达百倍），工具调用循环存在边界bug——CodeSmith为此专门维护prompt_zones.rs和tool_parser.rs模块，而生成的Agent未必知道这些。

工具设计缺乏纪律：描述过于简略、没有负向清单、参数缺少示例。

技术选型过时：训练数据中最常见但已废弃的模型和API——模型每六个月就迭代一轮，训练记忆注定过期。

与活跃生态脱节：已弃用的API、无人维护的库。

后两个问题源于同一个病根：知识截止。解药是维护SOTA知识库或给Agent搜索能力，让参考答案保持新鲜。前两个问题的最佳解法并非在prompt中枚举每一条规则——那是打地鼠——而是提供一个高质量Agent实现作为范例，让生成器修改范例而非从零开始。

KV Cache（键值缓存）是当前大模型推理服务降低成本的核心机制。Transformer 在自回归生成时，每一层注意力都需要历史 token 的 Key 和 Value 向量；若每生成一个 token 都重算全部历史，算力开销随上下文长度平方增长。KV Cache 把这些中间结果缓存下来，使增量解码只需计算新 token。但缓存能否命中，高度依赖请求前缀是否逐字节一致：结构化消息（带明确的 role、tool_call、content 分段）通常能与服务端模板对齐，命中率高、缓存价廉；而把轨迹压平成一大段纯文本，会破坏前缀稳定性，每轮都近乎全量重算。这在按 token 计费的商业 API 上可造成百倍级的价格差异，也解释了为什么 CodeSmith 要专门维护 prompt_zones.rs 来划分稳定区与变化区——它是为缓存命中率而做的工程约束。

关键技法：范例驱动生成

范例代码本身就是最佳实践的载体：好的架构选择自然存活，因为它们已经在范例中；而把每条规则的"为什么"写进prompt需要千言万语，放进范例里只需一个diff。

CodeSmith将这条路线做成了内置机制。参见crates/agent-runtime/src/skills/system.rs：

// crates/agent-runtime/src/skills/system.rs
const SKILL_CREATOR_BODY: &str = include_str!("../../assets/skills/skill-creator/SKILL.md");
const DELEGATE_BODY: &str = include_str!("../../assets/skills/delegate/SKILL.md");
const V4_BEST_PRACTICES_BODY: &str = include_str!("../../assets/skills/v4-best-practices/SKILL.md");
const PLUGIN_CREATOR_BODY: &str = include_str!("../../assets/skills/plugin-creator/SKILL.md");
const MCP_BUILDER_BODY: &str = include_str!("../../assets/skills/mcp-builder/SKILL.md");

首次启动时，这整套"范例技能"会自动安装（通过BUNDLED_SKILL_VERSION进行版本管理和升级时的增量更新）。其中最典型的是skill-creator——一个教Agent创建技能的技能——本质是一份高质量范例加上写作规范。mcp-builder和plugin-creator同理：与其在系统prompt里写一百条"如何编写MCP服务器"的规则，不如交出一个可运行的范例让模型修改。这是通向自举的门户。

Subagent系统是"复制加变异"的另一面。crates/agent-runtime/src/subagent.rs:32定义了subagent类型：

pub enum SubAgentType {
    /// General purpose - full tool access for multi-step tasks.
    General,
    /// Fast exploration - read-only tools for codebase search.
    Explore,
    /// Planning - analysis tools only for architectural planning.
    Plan,
    /// Code review - read + analysis tools.
    // ......
}

翻译成白话：所有subagent共享同一运行时（架构框架不动），类型只决定两件事——角色和工具面（变异的部分）。这就是"复制自己、调整prompt、增删工具、保留框架"的现成实现。General是全量复制，Explore是去掉写权限的变体，Plan是只保留分析的变体。生物学类比在此闭合：基因组（运行时）被复制，表型（prompt和工具面）分化，变异是小步的——每次一两个维度，而非从零重写。

include_str! 是 Rust 的编译期宏：它在编译时把指定文件的完整内容读取为一个 &'static str 常量嵌入二进制，运行时不再访问文件系统。CodeSmith 用它把 skill-creator/SKILL.md、mcp-builder/SKILL.md 等范例技能直接编译进产物，因此无论用户从哪个目录启动、是否联网，范例都一定存在且版本固定。配合 BUNDLED_SKILL_VERSION 常量，程序可以在启动时比较内置版本与用户已安装技能的版本，决定是全新安装还是做增量补丁。这套“资源随二进制分发”的做法，是自举机制可信的基础：范例不是从某个可能被篡改或缺失的路径临时读取，而是与运行时同源、同版本、同一次构建的产物，任何回滚或升级都天然同步。

代价与安全边界

把元能力系列串成一条线索：元能力是"创造能力的能力"，代码精确、可执行、可组合，能现场产生新工具、新约束和新表达。其目标从核心向外移动：思考→行为→自我。自我修复是分层配方，写Agent靠范例而非规则清单，subagent等于基因组复制加变异。

代价一如既往：自举会放大一切。范例中的好架构被复制，坏架构同样被复制，缺陷成为每个后代的遗传病。这就是为什么内置技能带有BUNDLED_SKILL_VERSION版本管理并随每次发布更新——最后一层harness，套在基因组之上。

自举之后的下一个课题是进化，而进化的第一条安全边界恰好埋在这里：安全机制必须不可自我修改。Agent可以改变自己的prompt、技能和工具，但绝不能触碰审批自身更新的验证器、测试用例和审计日志——否则它只需降低测试阈值，退化就能伪装成进步。

而在进化课程开启前，一笔更根本的账单到期了：当模型说"测试全绿"时，这句话本身值多少？答案只有回放之后才算数。

Harness 一词源自软件测试，指包裹被测对象的脚手架：输入注入、环境准备、结果断言、清理回收。在 Agent 语境下，harness 扩展为“围绕模型的一切非模型代码”——系统提示词模板、工具 schema、执行沙箱、审批门、审计日志、测试套件。它决定模型能看见什么、能做什么、做完如何被验证。CodeSmith 把内置技能的版本管理称作“套在基因组之上的最后一层 harness”，含义是：基因组（Agent 运行时与范例）可以自我复制和变异，但负责判定变异是否合格的这层脚手架必须由外部、由人控制。一旦这层也被 Agent 修改，自我改进就失去了外部裁判，退化与进步将无法区分。因此安全边界的工程落点，本质上就是明确划定哪些模块属于可变异区、哪些属于受保护的 harness 区。