章末自测

题目 1:为什么 Coding Agent 进入陌生项目以后应该优先扫描 Workspace 和读取 AGENTS.md,而不是直接修改代码?

因为陌生项目的目录结构、测试方式、运行版本和修改约束都未知。直接改代码意味着模型在猜。先扫描 Workspace 可以知道真实文件和目录,读取 AGENTS.md 可以知道不能修改 tests/、是否允许新增依赖、测试命令是什么。这样后续 Tool Call 才有明确边界,也能避免“技术上修好了、项目规则却违反了”的情况。

题目 2:为什么 Coding Agent 的 Completion Criteria 不能只有“模型说完成了”或“局部测试通过”?

模型可能提前结束,也可能没有执行证据却声称成功;局部测试通过也不代表整个项目没有回归。更可靠的 Completion Gate 应检查目标 Bug 是否解决、要求的相关测试和全量测试是否通过、AGENTS.md 与用户约束是否满足、是否还有 pending approval。只有这些条件都满足,Run 才应该进入 COMPLETED。

题目 3:编程实现——定义一个最小 CodingState,包含 run_id、goal、modified_files 与 full_tests_passed。

from dataclasses import (
    dataclass,
    field,
)


@dataclass
class CodingState:
    run_id: str
    goal: str
    modified_files: list[str] = field(
        default_factory=list
    )
    full_tests_passed: bool = False


if __name__ == "__main__":
    state = CodingState(
        run_id="run_demo",
        goal="修复 pytest 失败",
    )

    state.modified_files.append(
        "calculator.py"
    )

    state.full_tests_passed = True

    print(state)
#真实系统还会继续保存 step、status、current_error、project_rules、tool_history 和 Working Memory。

题目 4:为什么 read_file、edit_file、run_pytest 这种窄 Tool 通常比万能 run_shell 更适合 Coding Agent?

窄 Tool 的能力边界更清晰,可以单独做 Path Validation、权限判断、参数 Schema、风险等级和 Trace。比如 edit_file 可以明确保护 tests/,run_pytest 可以固定执行 pytest 而不开放任意 Shell。万能 run_shell 虽然灵活,但能读写文件、联网、启动任意程序,攻击面更大,也更难审计。生产 Agent 更适合默认使用窄 Tool。

题目 5:测试错误从 ImportError 变成 TypeError,Agent 应如何理解这种变化?

错误类型变化通常意味着系统状态发生了进展:原来的 ImportError 可能已经被解决,执行继续深入后暴露新的 TypeError。Agent 不应该简单认为“修改失败了”,而应更新 Working Memory 中的 current_error,读取新的 traceback,重新定位相关代码。Trace 也应该保留错误签名变化,帮助后续判断每次修改是否产生实质进展。

题目 6:为什么 Flask Route 不应该直接承载完整 Agent Main Loop?

Flask Route 应主要负责 HTTP 请求解析、参数校验和调用 AgentService。真正 Main Loop、Tool Registry、ContextBuilder、Memory、Trace 等逻辑如果全塞在 Route 中,会难以复用到 CLI、定时任务、飞书或其他入口,也不利于测试。更成熟的架构是 Flask → AgentService → AgentEngine → Harness,各层职责清晰。

题目 7:如何把一次 Coding Agent 失败转化成长期系统能力?

先通过 Trace 找到 First Bad Step,判断属于 Context、Decision、Arguments、Tool、Recovery、Policy 或 Termination 哪一层;修复对应模块后,把失败任务加入 Regression Benchmark,并定义明确 Success Criteria,例如 tests/ 不得变化、pytest 必须通过。以后每次更换模型、Prompt、Skill 或 Tool,都自动重跑这个任务,防止问题回归。

进一步阅读

  • Coding Agent Architecture:理解 Agent Engine、Tool Registry、Workspace 与 Test Runner 的组合。
  • Patch Validation:代码修改以后如何做静态检查、单测和全量测试。
  • Git Diff Analysis:未来如何让 Agent 用结构化 Diff 做修改审计。
  • Sandboxed Code Execution:真实代码执行为什么应该放在更强隔离环境。
  • Regression Benchmark:把真实 Bug Case 变成长期测试任务。
  • Project Rules:AGENTS.md 如何约束真实 Coding Agent。
  • AgentOps:Tracing、Metrics 和 Evaluation 如何进入完整项目。
  • Background Execution:长时间 Agent Run 如何从同步 Flask 升级为异步 Worker。

术语表

  • Coding Agent:围绕代码理解、修改、测试和验证形成闭环的 Agent,不只是一次代码生成,而是多步受控执行系统。
  • Project Scan:Agent 进入陌生项目后读取目录结构、配置文件和项目规则的初始阶段。
  • Baseline Test:在修改代码之前先运行测试,用于复现当前错误并建立修复前基线。
  • Completion Gate:Run 进入 COMPLETED 前进行的确定性检查,例如全量测试、项目规则和审批状态是否满足。
  • Modified Files:当前 Run 中真正发生修改的文件集合,应进入 Working Memory、Trace 和最终报告。
  • Error Signature:用于表示当前失败类型和关键错误信息的结构,可用于判断失败是否重复或发生变化。
  • Project Policy:由 AGENTS.md 等项目规则解析得到的可执行约束,例如禁止修改 tests/、禁止新增依赖。
  • Coding Harness:围绕 LLM 决策层提供 Tool、Workspace、Memory、Trace、Safety、Run 和 Evaluation 的完整执行框架。

本章总结

这一章,我们终于把整门课程前面学到的组件真正组装成了一个完整的 Coding Agent。

任务非常清楚,给 Agent 一个陌生 Python 项目,让它自动定位并修复 Bug。

完整链路是:

用户提交任务
 ↓
扫描项目
 ↓
读取 AGENTS.md
 ↓
查找相关文件
 ↓
读取代码
 ↓
运行测试
 ↓
分析报错
 ↓
修改代码
 ↓
再次测试
 ↓
测试通过
 ↓
输出修改报告

这一章最重要的第一条原则是,陌生项目先观察,再行动。

Coding Agent 进入 Workspace 后,第一件事不是改代码。

而是:

确认 Workspace
读取 AGENTS.md
扫描项目
复现错误

只有拿到真实 Observation,后续修改才有依据。

第二条原则是,LLM 负责决策,Harness 负责执行。

模型可以说:

下一步读 calculator.py。

真正读取文件的是:

read_file Tool。

模型可以说:

把 return a - b 改成 return a + b。

真正修改的是:

edit_file Tool。

模型可以判断:

应该运行测试。

真正执行的是:

run_pytest。

这就是 Agent 与纯代码生成的核心区别。

第三条原则是,Coding Agent 必须有项目规则意识。

AGENTS.md 不是装饰。

像:

禁止修改 tests/
禁止新增依赖
必须 pytest

会直接决定:

什么动作允许
什么动作禁止
什么条件才算完成

第四条原则是,测试不是最后的附加动作,而是 Main Loop 的核心 Observation。

Coding Agent 的执行链其实非常像:

修改
↓
测试
↓
观察
↓
再修改

测试结果会不断改变 Agent 的下一步策略。

如果错误从:

ImportError

变成:

TypeError

说明系统状态已经发生变化。

Agent 应该基于新的 Error Signature 继续,而不是机械重复旧策略。

第五条原则是,最终完成必须经过 Completion Gate。

不能只听模型说:

“我完成了。”

Harness 至少应该检查:

全量测试通过
项目规则满足
没有未决审批
没有明显违规修改

只有通过以后:

Run → COMPLETED

第六条原则是,真正可维护的 Coding Agent 一定要有 Trace。

用户最终不只需要:

修好了。

还需要知道:

根因是什么
改了哪些文件
为什么这样改
测试跑了什么
结果是什么
有没有违反项目规则

所以最终报告应该建立在真实 Trace 和 Tool Result 上。

第七条原则是,Flask 只是服务入口,不是 Agent 本身。

成熟架构应该是:

Client
 ↓
Flask
 ↓
AgentService
 ↓
AgentEngine
 ↓
ContextBuilder
 ↓
LLM Provider
 ↓
Tool Registry
 ↓
Middleware / Sandbox
 ↓
Workspace
 ↓
Trace / Memory

这样同一个 AgentEngine 才可以未来同时服务:

Web
CLI
飞书
定时任务
内部平台

到这里,我们已经拥有一个真正完整的 Coding Agent 设计。

它不再只是:

LLM
+
Shell

而是:

Python
+
Flask
+
LLM
+
Tool Registry
+
Memory
+
Tracing
+
Workspace
+
AGENTS.md
+
Safety
+
Evaluation

组成的完整 Harness。

下一节,我们会做第二个完整项目,从 0 打造 Data Analysis Agent。

它和 Coding Agent 最大区别是:

Coding Agent
→ 围绕代码、测试、修改形成闭环

Data Analysis Agent
→ 围绕指标、查询、Observation、下钻形成闭环

用户只需要问,“为什么昨天收入突然下降?”

Agent 就要自己:

理解问题
查询整体指标
判断异常
选择下钻方向
再次查询
收集证据
判断是否继续
输出结论

这会让我们真正看到,Agent 相比传统 Text-to-SQL,多出来的到底是什么。

© 版权声明
THE END
喜欢就支持一下吧
点赞5 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容