05. Coding Agent 与代码元能力：通用 Agent 的内核

前几篇把上下文、记忆与工具拆开讲。本篇对应书的第 5 章，回答：开放任务型通用 Agent，骨架长什么样？

工业界反复验证的一条路径：Coding Agent 运行时 + 文件系统，再叠加搜索、浏览器等模块。PPT 底层是 OOXML，报表是脚本，调研是请求与解析，成功的 GUI 操作也可沉淀为可复用脚本。代码在成本、可复用性与可验证性上，往往压过纯 Computer Use。

边界先说清：垂直客服、封闭语音助手可以不以 Coding 为架构中枢，但精确计算、规则校验、数据处理仍需要 coding 底线能力。

七个核心工具：极简动作空间

整理仓库 TODO、改 bug、跑测试，动作可收成：

有的实现把 1 与 2 合并。它们主要覆盖感知与执行；协作、事件、用户沟通多在框架层。可用 MCP 暴露，也可用内置工具。

# 示意：用 grep + write 整理 TODO（真实 Agent 由模型决定调用序列）
from pathlib import Path
import re


def collect_todos(root: str, pattern: str = r"TODO") -> list[str]:
    """在 root 下递归扫描 .py，返回 'path:lineno: line' 列表。"""
    hits: list[str] = []
    for path in Path(root).rglob("*.py"):
        for i, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
            if re.search(pattern, line):
                hits.append(f"{path}:{i}: {line.strip()}")
    return hits


def write_todo_list(root: str, out_name: str = "TODO_LIST.md") -> str:
    """生成 Markdown 清单文件，返回写入路径。"""
    lines = collect_todos(root)
    body = "# TODO 清单\n\n" + "\n".join(f"- `{h}`" for h in lines) + "\n"
    out = Path(root) / out_name
    out.write_text(body, encoding="utf-8")
    return str(out)


if __name__ == "__main__":
    # 在空项目上自测：创建临时文件后收集
    demo = Path("/tmp/todo_demo")
    demo.mkdir(exist_ok=True)
    (demo / "a.py").write_text("# TODO: add rate limiting\nprint(1)\n", encoding="utf-8")
    path = write_todo_list(str(demo))
    print(Path(path).read_text(encoding="utf-8"))
    # 典型输出含：- `/tmp/todo_demo/a.py:1: # TODO: add rate limiting`

文件系统是中枢，不只是磁盘

OpenClaw 一类架构里，工作区同时承载：

• 记忆——MEMORY.md 高层事实与偏好；按日 Markdown 日志
• 身份与规则——SOUL.md / 项目级 AGENTS.md、CLAUDE.md（每次会话注入的项目指令，对 KV Cache 友好的稳定前缀）
• 产物与经验——报告、脚本、可复用 Skill
• 审计——Git 版本与回滚

选 Markdown 而非默认可向量库，工程理由具体：人可直接改正误记；时间序清晰；Git 可回滚；Agent 的 write_file 能外化学习（接第 8 章）。向量检索仍可作加速层，不必当唯一真相源。

对远程协作友好的团队往往也对 Agent 友好：决策写在文档与 PR 里，而不是只在工位口头传递——Agent 读得到前者，读不到后者。

Sessionless：随时一条消息，状态怎么活

Sessionless（无会话感）：用户不必「打开 App / 登录工作区」，在已有消息渠道发一句即达。前提是模型充当统一智能抽象，框架侧 Gateway 路由多渠道事件（见 04）。

Coding 场景的难点是跨消息状态：

持久化的是可审计描述（文件、清单、脚本），不是无限挂起的不透明进程。每次唤醒仍要加载轨迹与工作状态，因此更依赖第 2 章的压缩与状态栏。

安全：缩小攻击面，而不是幻想滤净所有注入

Simon Willison 概括的高危组合（常称「三要素」）：

1. 能读私有数据
2. 会接触不可信内容（网页、邮件、issue）
3. 能对外通信或执行命令

三者齐备即可闭合「注入 → 窃取 → 外传」。持久记忆是放大器：恶意指令写入 MEMORY.md 后跨会话潜伏。

Coding Agent 增量防线：

• 网络出口：默认断网，白名单代理放行包源与任务 API——切断外传比识别每一句注入更确定。
• 文件系统：源码只读挂载或补丁审查后落盘；凭证目录不进沙盒。
• 资源限额：CPU/内存/磁盘 + 挂钟超时；超时返回结构化错误供纠正。
• 命令语义解析：关键字黑名单挡不住 $(echo rm) 与 find -exec；要理解参数消费关系。
• 推测式 UX：UI 先显示进度，Sidecar 并行门控；多数情况用户无感，仅不确定时升级确认。
• 忠诚对象：主人指令优先；外部内容降为数据。提示注入本质是策反。
• 信任下移：高危数据不变量写在人类审查过的 schema / 存储层强制执行，而不是只写在可被模型改写的 handler 里。

闭源产品偏保守权限，往往不是做不到全开，而是全开后的损失半径不可接受。

搜索工具：从粗到细

路线之争：Claude Code 等终端 Agent 可坚持 agentic grep+glob、不建嵌入索引（无陈旧索引、少外发）；Cursor 类 IDE 愿为跨文件语义召回付索引成本。按仓库规模、合规、基础设施选，不是道德判断。

组合策略通常是：语义或 glob 定范围 → grep 钉行 → 符号追踪调用链。

文件编辑：让模型说清「改哪里」

常见方案：

工程上 old→new 采用面广，前提是读工具与写工具对空白、引号、换行一致（第 4 章保真）。编辑后应用 即时 linter 反馈 写入 tool 结果，把语法错误消灭在下一轮，而不是拖到用户跑测试。

读文件应带行号前缀、支持按行范围；终端输出头尾截断并落盘。

推荐工作流（可按任务裁剪）

复杂任务的工程化骨架：

1. 项目文档化——读 README / 架构；缺失则生成；维护 Agent 指令文件
2. 需求澄清——模糊目标先问优化指标与约束
3. 设计文档——模块、方案权衡、影响面；人类低成本卡点
4. 实现 + 测试——完成标准是测试通过，不是「代码写完」
5. 自审与交付——lint、可读性、安全；架构变更同步文档

简单修 bug 可跳过设计文档；不可跳过的是验证闭环。

Harness 在 Coding 场景最「合身」

代码任务天然靠近「目标明确 + 结果可自动验证」象限：测试、类型检查、CI、Git 回滚都是现成 Harness。

可迁移原则：

1. 约束优先于指导——Linter/CI 强制，优于提示词里「请不要……」
2. 验证自动化——人审是吞吐量上限
3. 反馈快且结构化——错误越靠近引入时刻越好修
4. 回退可靠——分支、沙盒、快照，让试错可逆
5. 约束过程，不只约束结果——删库「修好」故障在结果指标上可能为真，过程上不可接受

故障分层：API（限流、超时）、工具（幻觉名、坏参数、重复同一错误）、上下文（溢出、配对缺失）、控制流（死循环、恢复逻辑再次调模型形成死亡螺旋）。检测先分类再计数；恢复静默重试 → 降级接续 → 暴露用户；每条恢复路径有熔断上限。

实现技巧提速：流式解析下，首个 tool call 参数完整即执行；并行调用声明并发安全与故障边界；状态栏注入 cwd/分支/变更；默认持久 shell 会话。

代码作为元能力：六种用法

元能力（meta-capability）：能在运行时创造其他能力的能力——新工具、新约束、新表达形式，而不必预制所有动作。

1. 思考工具

自然语言心算集合问题易错；模型负责形式化，解释器负责精确。

# 班有 40 人：60% 数学，45% 物理，25% 都选；只选物理人数？
math = int(40 * 0.60)   # 24
phys = int(40 * 0.45)   # 18
both = int(40 * 0.25)   # 10
only_phys = phys - both
print(only_phys)  # 典型输出：8

符号计算（SymPy 等）与约束求解同理：LLM 译问题，求解器给确定性答案。脚手架厚度应随模型能力调节——弱模型上代码辅助增益大，强推理模型上增益可能收敛。

2. 业务规则约束

「购买后 7 天可退」在自然语言里仍有自然日/工作日、下单/收货歧义。代码化规则作守门员：

• 提示词保留可读政策，便于解释与协商
• 工具参数作 checklist，迫使调用前查单
• 服务端以数据库真值为准，不采信模型自报的舱位、保险、时间

不可逆操作（取消、转账、删除）前，真值校验的价值高于省 token。

3. 多媒体与内容生成

用 Markdown/HTML/Slidev 等生成演示与文档，绕开 GUI 像素点击。Proposer 写代码，Reviewer 看渲染截图（模态切换），迭代布局问题——单一 Agent 同时扛代码与长截图易爆上下文。

4. 系统适配器

异构 API、字段变更、临时 ETL：现场写胶水脚本，比等待预置连接器覆盖长尾更快。脚本可沉淀为仓库内 Skill。

5. 生成式 UI

动态生成表单、配置页、审批卡片（HTML/组件代码），把结构化交互从纯文本对话里解放出来。

6. 自举

用代码生成新的工具封装、评测脚本、甚至子 Agent 配置，扩展动作空间。与第 8 章「不改权重的自我进化」衔接：经验外化为文件与脚本，而不是只留在对话里。

与系列主线的接口

模型越强，越能内化部分脚手架；新的能力前沿会要求新的 Harness——01 的「方向认同，节奏务实」在编码场景同样适用。

本篇收束

1. 开放任务通用 Agent 的高性价比内核，常是 Coding 运行时 + 文件系统。
2. 七个通用工具组合空间大；Sessionless 依赖状态分层持久化。
3. 安全默认假设注入会发生，靠出口、隔离、语义检查与信任下移收损。
4. 搜索从粗到细，编辑保真 + 即时验证；完成标准绑定自动化检查。
5. 代码的元能力：推理、规则、适配、UI、产物生成与自举——把「不会的工具」变成「写得出来的工具」。

下一篇进入第 6 章：Agent 评估——没有可重复的评测，Harness 与提示词迭代都只能靠感觉。