AI Agent Engineer

AI Agent Engineer
个人学习进度

标记这门课程

课程正文公开可读；登录后可保存个人进度。

JSON 学习目录

10 min read

JSON 学习目录

知识库简介

JSON（JavaScript Object Notation）是一种文本数据交换格式。API 请求与响应、配置文件、LLM 结构化输出、Tool Calling 参数、MCP 消息和 Agent 状态经常使用它。会辨认大括号只是起点：工程系统还必须处理 UTF-8、重复键、数值范围、解析资源上限、Schema 方言、版本迁移、错误脱敏，以及“结构正确但动作未获授权”的边界。

本库采用三个逐层收紧的视角：

  1. JSON 语法回答“这段文本能否表示一个值”；
  2. 数据契约回答“这个值是否符合调用双方约定”；
  3. 业务与授权回答“这个值是否真实、可用，并允许触发动作”。

综合项目只处理本地教学数据，不访问网络、不使用密钥，也不会执行任何工具。它先用 Python 严格解析，再用 Draft 2020-12 Schema 验证，最后由可信代码判定工具建议是“仅验证”还是“需要审批”。

在总路线中的位置

本库位于 AI Agent Engineer 总路线 的“工程与数学基础”知识域，并进入四条角色路径。它先建立请求体、响应体与配置的数据表示和契约；随后可进入 API，再按需要学习 Markdown，并逐步进入 LLM、Tool Calling 与 MCP。

学习目标

  • 写出并判断六类 JSON 值，区分 JSON 文本、Python 对象与“装着 JSON 的字符串”。
  • 使用 load/loads/dump/dumps，正确处理 UTF-8、中文、错误行列号和序列化策略。
  • 解释 Python 默认 json 与 RFC 8259 严格互操作边界，并拒绝重复键、非有限数字、孤立 surrogate 和超限输入。
  • 区分单个 JSON 文档、JSON Lines、NDJSON 与 RFC 7464 JSON Text Sequences。
  • 使用 Draft 2020-12 的核心关键字，理解 $schema、$defs/$ref、组合、条件、default 和 format 的真实语义。
  • 为 Agent 配置与工具参数设计版本化契约、稳定错误路径和脱敏报告。
  • 说明结构化输出为何仍不能证明事实、权限、审批或工具执行成功。
  • 在普通与 python -O 模式下运行独立测试，验证失败路径而不是依赖裸 assert。

前置知识

  • 建议先完成 Python基础 中的字符串、字典、列表、异常、文件与虚拟环境。
  • 数据结构基础 有助于理解对象、数组和遍历成本。
  • 会在 Windows 11 + PowerShell 7 中运行 python；不需要 JavaScript、Web 服务或真实 API。

推荐学习顺序

  1. 语法与数据模型：从一个 JSON 文本走到六类值、空值语义与合法性判断。
  2. Python 解析、序列化与严格模式：掌握标准库，并认识默认行为并不等于严格 RFC profile。
  3. 互操作性、Unicode 与数字边界：处理重复键、对象顺序、Unicode、数值精度和 canonicalization。
  4. 文件、JSON Lines 与流式处理：安全读写文件、逐行处理记录并理解原子替换的能力边界。
  5. JSON Schema 基础契约：用 Draft 2020-12 表达对象、数组、必填、范围与未知字段策略。
  6. Schema 设计、版本与错误定位：学习复用、组合、条件、版本迁移与 RFC 6901 错误路径。
  7. API、LLM 与工具调用中的 JSON：把格式、Schema、事实、授权和执行结果分层。
  8. 实战：可靠 Agent 配置与事件管道：运行真实 Schema、严格 JSONL 管线、审批分流与脱敏报告。
  9. 练习、自测与掌握标准：完成故障修复、Schema 设计和项目扩展，再用清单验收。

动手实践入口

项目位于 examples/：

文件用途
strict_json.pyUTF-8 严格解析、唯一键、有限数字、资源限制、JSONL 与原子替换。
agent_config.schema.jsonDraft 2020-12 Agent 配置契约。
validate_agent_config.py依次执行语法、Schema 和业务不变量验证。
tool_call.schema.json两类本地工具建议的联合 Schema。
tool_calls.jsonl只读搜索与需审批写操作的虚构记录。
validate_tool_calls.py生成脱敏状态；不会动态分派或执行工具。
demo.py在临时目录中完成读、验、原子写、读回闭环。
test_*.py普通与 -O 模式均有效的 unittest。

先看 项目说明，不要直接复制复杂 helper 而跳过前七节的契约推导。

掌握标准

  • 能不运行代码判断常见 JSON 语法错误，并解释顶层标量为何合法。
  • 能区分字段缺失、字段为 null、空字符串和空数组的业务含义。
  • 能写出 UTF-8 读写代码，并解释 ensure_ascii=False、allow_nan=False 和双重编码。
  • 能证明 Python 默认解析器会接受哪些非标准扩展，并按契约收紧。
  • 能为重复键、超大输入、深层嵌套、JSONL 损坏行设计失败测试。
  • 能读懂并修改 Draft 2020-12 Schema，知道验证器支持的方言与子集必须核对。
  • 能用 JSON Pointer 定位错误，同时不把完整载荷或敏感值写入日志。
  • 能说明 Schema 通过后仍需业务校验、可信工具注册表、授权、审批、幂等和结果确认。
  • 能运行项目及全部测试，并独立增加一个字段、一个失败样例和一条迁移规则。

与其他知识库的关系

知识库边界与连接点
Python基础提供字符串、容器、异常、文件和测试；本库只聚焦 JSON 契约。
API解释 HTTP 方法、媒体类型、超时和重试；本库解释 payload 结构与验证。
LLM API集成厂商端点、SDK 字段和响应生命周期会变化，放在该库核对。
Tool Calling（含 Function Calling）Schema 约束参数形状；工具选择、执行循环和副作用控制在该库展开。
MCPMCP 使用 JSON-RPC 与 JSON Schema；协议版本和生命周期在 MCP 库学习。
Agent 核心Agent 状态可序列化为 JSON，但记忆、规划和控制循环不等于数据格式。
工作流自动化JSON 可承载步骤输入输出；并发、事务、补偿和恢复需要工作流层设计。

本轮验收记录

验收日期：2026-07-22。

  • 结构：10 篇 Markdown（1 个目录 + 9 节课程），examples/ 11 个文件，总计 21 个文件；无公开完整复刻材料。
  • 导航：44 个内部 wikilink 均使用完整限定路径；短路径 0、断链 0、旧课程路径残留 0。
  • 文档代码：16 个 Python fenced block 通过 AST 解析，28 个 JSON fenced block 均可解析。
  • 项目文件：6 个 Python 文件通过 AST；3 个单文档 JSON/Schema 通过 python -m json.tool；JSONL 样例逐行可解析。
  • 运行：普通模式与 python -O 模式各 42 项 unittest 全部通过，并把 ResourceWarning 视为错误。
  • 闭环：demo.py 实际得到 1 条 validated_not_executed、1 条 approval_required，未执行工具，临时报告自动清理。
  • 边界：读写 exact-limit/limit+1、LF/CRLF/EOF、重复键、非有限数字、Unicode、资源上限、原子替换失败和报告脱敏均有测试。
  • 卫生：无 .venv、缓存、模型文件、大文件、真实凭据或持久生成报告；git diff --check 通过。
  • 审查：内容结构、动态事实/来源、代码/安全三项独立只读复审均为 PASS。

Obsidian Reading View 未在本轮自动化环境中人工打开；已完成 frontmatter、Markdown 结构、wikilink 目标和代码块静态验证。

主要参考资料

资料复核日期：2026-07-22。

截至复核日，JSON Schema 官方站仍将 Draft 2020-12 作为当前正式发布方言；本机项目实际使用 Python 3.11.9 与 jsonschema 4.26.0。厂商结构化输出只支持完整规范的某个 profile 或子集时，应以该厂商当日官方文档为准，不能把实现限制写成通用 JSON Schema 规则。

Backlinks