# agent-study **Repository Path**: memorin/agent-study ## Basic Information - **Project Name**: agent-study - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-14 - **Last Updated**: 2026-09-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Agent 开发学习记录这个仓库记录 Agent / LLM 应用开发的实际学习过程。每条记录尽量对应一个可以运行、测试或复盘的产物，重点回答三个问题：当天理解了什么、完善了哪个模块、如何证明它确实可用。 ## 学习目标当前目标是补齐 Python 工程能力，独立完成一个可测试、可评测的 Code Agent；之后再把可复用的 Agent Kernel 迁移到本地优先的数学学习笔记 Agent。学习产物需要能够证明： - 能用 Python 组织 CLI、配置、HTTP、测试和错误边界。 - 能解释并实现模型、控制程序、工具与环境之间的职责划分。 - 能为成功与失败路径建立确定性测试，并记录可复现的验证命令。 - 能逐步实现安全执行、运行轨迹、评测数据和效果对照。 ## 学习主线 ```text Python工程基础与API CLI → 手写最小Agent Loop → 工具契约、安全执行与轨迹 → Code Agent MVP与评测 → 数学学习笔记Agent ``` 当前已经完成带环境变量、认证、超时和错误分类的 HTTP JSON CLI，以及具有显式工具契约、模型适配、退出原因、步数预算和 JSONL 运行轨迹的最小 Agent Loop。独立 Code Agent Kernel 已接入 `deepseek-v4-pro` 原生工具调用，完成 Token 预留、失败消费语义和第一版 EventStore；下一步继续闭合正式 Agent Loop 与完整 trace。 ## 克隆与配置项目使用 Python 3.12 和 [uv](https://docs.astral.sh/uv/) 管理解释器、虚拟环境与依赖。依赖声明位于 `practice/agent-foundations/pyproject.toml`，`uv.lock` 固定了可复现的依赖版本，`.python-version` 固定为 Python 3.12。 ### 1. 安装 Git 和 uv 先确认 Git 已安装： ```powershell git --version ``` Windows 可以使用 WinGet 安装 uv： ```powershell winget install --id=astral-sh.uv -e uv --version ``` 其他系统参见 [uv 官方安装说明](https://docs.astral.sh/uv/getting-started/installation/)。如果 `uv --version` 失败，应先修复 uv 安装或重启终端，再继续后面的步骤。 ### 2. 克隆仓库并同步环境 ```powershell git clone https://gitee.com/memorin/agent-study.git cd agent-study\practice\agent-foundations uv sync --frozen ``` `uv sync --frozen` 会根据 `.python-version`、`pyproject.toml` 和 `uv.lock` 创建 `.venv` 并安装运行、测试和类型检查所需的依赖。首次执行可能需要联网下载 Python 3.12 和依赖包；之后不需要手动激活虚拟环境。 ### 3. 运行本地 CLI 本地姓名模式不需要网络或 API key： ```powershell cd cli-rebuild uv run --project .. python -m profile_cli --name " Ada Lovelace " ``` 预期输出： ```text Welcome, Ada Lovelace! ``` ### 4. 配置远程 API（可选）只有使用 `--profile-id` 时才需要远程配置。服务应接受 `GET /profile/{id}`，通过 `Authorization: Bearer ` 验证身份，并返回包含字符串 `name` 字段的 JSON 对象，例如 `{"name": "Ada"}`。在当前 PowerShell 会话中设置环境变量： ```powershell $env:PROFILE_API_URL = "https://your-api.example.com" $env:PROFILE_API_KEY = "replace-with-your-real-key" uv run --project .. python -m profile_cli --profile-id 42 ``` Linux 或 macOS 使用： ```bash export PROFILE_API_URL="https://your-api.example.com" export PROFILE_API_KEY="replace-with-your-real-key" uv run --project .. python -m profile_cli --profile-id 42 ``` `PROFILE_API_KEY` 必填且不能是空白字符串；`PROFILE_API_URL` 未设置时会使用代码中的演示地址，因此连接真实服务时应显式设置。不要把真实密钥写进 README、源码、`.env` 示例值或命令行参数，也不要提交到 Git。 PowerShell 使用完毕后可以清除本次会话中的秘密： ```powershell Remove-Item Env:PROFILE_API_KEY Remove-Item Env:PROFILE_API_URL ``` ### 5. 运行验证 CLI 测试和严格类型检查： ```powershell # 当前目录：practice/agent-foundations/cli-rebuild uv run --project .. python -m pytest -q -p no:cacheprovider uv run --project .. python -m mypy profile_cli tests uv run --project .. python verify_profile_cli.py ``` 最小 Agent Loop 测试和严格类型检查： ```powershell cd ..\agent-loop-lab uv run --project .. python -m pytest -q -p no:cacheprovider uv run --project .. python -m mypy minimal_agent tests ``` 自动测试使用临时文件、假模型和 HTTPX `MockTransport`，不要求真实 API key，也不会请求远程服务。若出现 `No module named profile_cli`，请确认当前目录是 `cli-rebuild`；若出现 `No module named minimal_agent`，请确认当前目录是 `agent-loop-lab`。 ## 当前项目主要练习项目位于 [`practice/agent-foundations/cli-rebuild`](./practice/agent-foundations/cli-rebuild/)： | 模块 | 当前职责 | | --- | --- | | `profile_cli/__main__.py` | 承接 `python -m profile_cli`，把返回值交给操作系统 | | `profile_cli/cli.py` | 解析本地或远程输入，组装HTTP客户端，处理输出与退出码 | | `profile_cli/core.py` | 规范化姓名并构造业务数据 | | `profile_cli/file_input.py` | 读取UTF-8 JSON文件并验证输入结构 | | `profile_cli/config.py` | 从环境变量读取API地址与密钥，验证配置且隐藏密钥展示 | | `profile_cli/http_client.py` | 发送请求、检查状态码、解析JSON并验证远程响应 | | `tests/test_cli_remote.py` | 从CLI公开接口验证远程成功、超时、状态错误和坏响应 | 当前CLI支持两种互斥输入。完成上面的 `uv sync --frozen` 后，在 `cli-rebuild` 目录运行： ```powershell # 本地姓名 uv run --project .. python -m profile_cli --name " Ada Lovelace " # 远程资料 $env:PROFILE_API_KEY = "replace-with-your-key" $env:PROFILE_API_URL = "https://api.example.com" uv run --project .. python -m profile_cli --profile-id 42 ``` ## 学习记录 ### 2026-08-12｜环境、控制流与Agent边界完成内容： - 建立 Python 3.12 + `uv` 虚拟环境，确认项目解释器与全局解释器可以并存。 - 记录 Windows、Git、Docker和WSL状态，明确暂不让环境阻塞基础练习。 - 从初始定义出发区分 LLM、固定工作流、Agent系统和Agent控制程序。 - 建立 `任务 → 模型提议 → 控制程序校验 → 工具执行 → observation → 下一步` 的职责模型。 - 闭卷重建带最大步数、错误停止和结果累积的 Python 控制流。主要产物： - [`environment-check.md`](./practice/agent-foundations/environment-check.md) - [`2026-08-12-concept-baseline.md`](./practice/agent-foundations/2026-08-12-concept-baseline.md) - [`0004-agent-control-boundary-and-loop.md`](./learning-records/0004-agent-control-boundary-and-loop.md) - [`0005-bounded-python-control-flow.md`](./learning-records/0005-bounded-python-control-flow.md) ### 2026-08-13｜模块化CLI 完成内容： - 闭卷重建可通过 `python -m profile_cli` 启动的 Python 包。 - 将入口、命令行适配和业务逻辑拆分到 `__main__.py`、`cli.py` 与 `core.py`。 - 实现 `text`、`json`、`compact-json` 三种输出格式。 - 区分函数返回值、stdout、stderr和进程退出码。 - 使用 subprocess 黑盒测试和 `main(argv)` 函数测试覆盖正常与错误路径。 - 发现并修复空白姓名测试复用了错误输入而产生的假绿。完善模块： - `profile_cli/__main__.py` - `profile_cli/cli.py` - `profile_cli/core.py` - `verify_profile_cli.py` 验证结果：CLI黑盒路径 `7/7` 通过，函数级路径 `5/5` 通过。 ### 2026-08-14｜包执行、类型与文件输入完成内容： - 比较导入包、导入子模块、`python -m package` 和直接执行模块的差异。 - 理解 `__name__`、`__package__` 与相对导入的解析条件。 - 在 `__init__.py` 中显式暴露公共API，并亲手完成 Git 的暂存与提交闭环。 - 复盘固定工作流与Agent：关键差异是模型是否根据 observation 决定下一步行动内容。 - 从 `build_profile()` 中提取纯函数 `normalize_name()`。 - 使用 `TypedDict` 建模返回结构，并为项目开启 `mypy --strict`。 - 使用 `pathlib` 与 `json` 实现文件输入，处理缺失文件、非法编码、非法JSON和错误字段类型。 - 抽样整理 Agent / LLM 应用实习岗位要求，确认项目经历是当前主要缺口。完善模块： - [`module-execution-lab`](./practice/agent-foundations/module-execution-lab/) - `profile_cli/core.py` - `profile_cli/file_input.py` - `pyproject.toml` - [`2026-08-14-agent-internship-jd-sample.md`](./research/2026-08-14-agent-internship-jd-sample.md) 验证结果：严格类型检查通过，文件输入的6条成功与失败路径通过。 ### 2026-08-16｜HTTP、配置、秘密与远程CLI 完成内容： - 从零梳理HTTP请求与响应，区分方法、URL、headers、body和状态码。 - 区分连接错误、读取超时、HTTP状态错误、JSON解析错误和业务数据错误。 - 使用 HTTPX 实现可注入客户端的远程资料读取函数。 - 配置连接与读取超时，使用 `MockTransport` 在不访问互联网的情况下测试远程响应。 - 使用环境变量读取API地址和密钥，区分 `None`、空字符串和空白字符串。 - 使用冻结的 `Settings` 保存配置，通过 `repr=False` 降低意外打印密钥的风险。 - 定义 `ConfigurationError` 与 `ProfileResponseError`，让错误来源可以被调用层识别。 - 将 `.env` 加入 Git 忽略规则，并在提交前扫描真实密钥。 - 为CLI增加 `--profile-id` 远程模式，与 `--name` 形成必选且互斥的输入来源。 - 使用 TDD 完成远程成功、缺少配置、读取超时、`401`、`500`、非法JSON和空白远程姓名等路径。 - 使用 `pytest` 的 `capsys`、`parametrize` 与 HTTPX `MockTransport` 验证公开CLI行为。 - 增加 `--verbose` 安全日志，保持 stdout 数据与 stderr 诊断信息分离。 - 使用 subprocess 从真实进程边界验证模块入口、输出流和退出码。完善模块： - `profile_cli/config.py` - `profile_cli/http_client.py` - `profile_cli/cli.py` - `test_config.py` - `test_http_client.py` - `tests/test_cli_remote.py` - `tests/test_cli_subprocess.py` - [`从零搭建 Code Agent：HTTP、配置与日志`](./blogs/from-zero-code-agent-http.md) - [`从零搭建 Code Agent：pytest 与进程级测试`](./blogs/from-zero-code-agent-testing.md) 当前验证结果： ```text pytest: 18 passed mypy --strict: no issues found 原有CLI黑盒验证: 7/7 passed ``` ### 2026-08-17｜最小Agent Loop 完成内容： - 使用冻结的 dataclass 定义 `Task`、`ToolCall`、`Observation` 与 `Finish`。 - 使用结构化参数实现 calculator，拒绝未知操作、错误类型、缺失字段和除零。 - 建立工具 registry，由控制程序拒绝未知工具并把预期工具错误转换成 observation。 - 使用 `Protocol` 定义模型接口，并实现按预设顺序返回动作的 `FakeModel`。 - 实现带最大步数限制的 Agent Loop，跑通“计算 `12 × 7` 并判断是否大于 `80`”。 - 覆盖正常结束、工具失败反馈、未知工具、假模型耗尽和最大步数等路径。完善模块： - [`agent-loop-lab/minimal_agent`](./practice/agent-foundations/agent-loop-lab/minimal_agent/) - [`agent-loop-lab/tests`](./practice/agent-foundations/agent-loop-lab/tests/) 验证结果：pytest `15 passed`，mypy 严格检查 `11` 个源文件无问题。 ### 2026-08-23｜周验收与理解复盘完成内容： - 对 CLI 与最小 Agent Loop 进行周验收，确认可运行产物和自动验证达到本周要求。 - 复盘参数错误、配置错误、HTTP 状态错误、网络错误和程序异常的产生位置与处理边界。 - 明确下一阶段采用“理解优先”模式，重点解释模块职责、调用链、错误边界和测试证据。 - 保留原学习主线，不把自行维持两天一次频率的算法练习列入 Agent 学习计划。学习记录与产物： - [`0007-2026-08-23-weekly-review.md`](./learning-records/0007-2026-08-23-weekly-review.md) - [`cli-rebuild/README.md`](./practice/agent-foundations/cli-rebuild/README.md) - [`agent-loop-lab/README.md`](./practice/agent-foundations/agent-loop-lab/README.md) 验证结果：CLI 测试 `18 passed`，Agent Loop 测试 `15 passed`；两组 `mypy --strict` 均通过。周验收结论为“有条件完成”，后续需要继续巩固代码理解。 ### 2026-08-24｜Agent Loop 契约、适配与轨迹完成内容： - 明确模型只负责提出 `ToolCall` 或 `Finish`，runtime 掌握工具执行权、终止权和步数预算。 - 将可恢复的工具失败转换为 `Observation` 返回模型，把代码缺陷等意外异常继续向上抛出。 - 使用 `ToolSpec` 描述模型可见契约，并用 `ToolDefinition` 将契约与 runtime-only handler 绑定。 - 实现 `JsonModelAdapter`，把不同模型的原始 JSON 输出统一转换为内部 `ToolCall | Finish`。 - 使用 `RunResult` 区分正常完成、预算耗尽和非法模型输出，并保留意外程序异常的真实失败语义。 - 实现追加式 JSONL 轨迹，记录模型动作、工具观察、模型反馈与退出原因，同时对文本、参数值和秘密采取脱敏或不记录策略。学习记录与产物： - [`0008-2026-08-24-agent-loop-runtime-boundaries.md`](./learning-records/0008-2026-08-24-agent-loop-runtime-boundaries.md) - [`0009-2026-08-24-explicit-tool-contract.md`](./learning-records/0009-2026-08-24-explicit-tool-contract.md) - [`0010-2026-08-24-model-adapter-and-exit-reasons.md`](./learning-records/0010-2026-08-24-model-adapter-and-exit-reasons.md) - [`0011-2026-08-24-jsonl-agent-trace.md`](./learning-records/0011-2026-08-24-jsonl-agent-trace.md) - [`agent-loop-lab`](./practice/agent-foundations/agent-loop-lab/) 最终验证结果：pytest `33 passed`，mypy 严格检查 `17` 个源文件无问题。 ### 2026-08-26｜独立 Agent Kernel 与 Model Adapter 完成内容： - 在独立 `Issue-to-Patch-Code-Agent` 仓库中定义 provider 无关的消息、工具调用、工具结果与最终答案类型。 - 建立统一 `ModelAdapter`、单次调用预算、Token usage、Fake Model 与严格 JSON action parser。 - 明确 Provider 处理外部协议，Adapter 归一化 Kernel Action，具体工具参数留给 Registry 和 Runtime 校验。 - 使用 `call_id` 连接工具调用与工具结果，拒绝空白标识和不完整 Action。学习记录与产物： - [`0012-2026-08-26-code-agent-kernel-and-model-adapter.md`](./learning-records/0012-2026-08-26-code-agent-kernel-and-model-adapter.md) - [`从零搭建 Code Agent：JSON 文本模型 Adapter`](./blogs/from-zero-code-json-adapter.md) - [`Issue-to-Patch-Code-Agent`](https://github.com/Mem0rin/Issue-to-Patch-Code-Agent) 当日验证结果：pytest `33 passed`，mypy 检查 7 个源文件无错误。 ### 2026-08-31｜数学项目调整为学习笔记 Agent 完成内容： - 将 2027 年数学方向项目从特定教材伴读调整为本地优先的数学学习笔记 Agent。 - 以 Markdown 文件作为事实来源，AI 只生成可预览、可确认和可撤销的候选内容。 - 把数学结构、LaTeX 保真和局部解释作为能力重点，不再以复制完整 Obsidian 功能为目标。 - 长期计划改为阶段规划，项目启动后再按周滚动生成任务。学习记录： - [`0013-2026-08-31-math-learning-notes-agent-direction.md`](./learning-records/0013-2026-08-31-math-learning-notes-agent-direction.md) ### 2026-09-01｜RunBudget、DeepSeek 与 EventStore 完成内容： - 实现模型调用前 Token 预留，以及成功、非法输出、无消费、实际消费和未知消费的结算语义。 - 增加预算约束下的 Provider / 非法输出重试，每次重试都重新计入模型调用并预留预算。 - 接入 `deepseek-v4-pro` 原生 tool calling，保留 Provider `call_id`，用安全 calculator 跑通两轮真实闭环。 - 修复 DeepSeek 工具调用伴随空字符串 `content` 时被误判为最终文本的问题。 - 区分 Model Context、Run History、Run Event Trace 与 Cross-run Memory。 - 完成 `JsonlEventStore.append/read_all` 第一切片和写盘前递归敏感字段脱敏。学习记录与产物： - [`0014-2026-09-01-run-budget-deepseek-event-store.md`](./learning-records/0014-2026-09-01-run-budget-deepseek-event-store.md) - [`DeepSeek V4 Pro API 接入核查`](./research/2026-09-01-deepseek-v4pro-api.md) - [`公开 Agent 框架 Token 预算调研`](./research/2026-09-01-public-agent-framework-token-budgets.md) - [`09-10 Agent Kernel 与论文硬验收`](./milestones/2026-09-10-agent-kernel-and-paper-review.md) 当前验证结果：pytest `124 passed`，mypy 检查 32 个源文件无错误；真实烟测为 2 次模型调用、747 input / 66 output Token、2.953 秒，最终预留为 0。 ## 运行验证完成“克隆与配置”后，在 `practice/agent-foundations/cli-rebuild` 中执行： ```powershell uv run --project .. python -m pytest -q -p no:cacheprovider uv run --project .. python -m mypy profile_cli tests uv run --project .. python verify_profile_cli.py ``` 在 `practice/agent-foundations/agent-loop-lab` 中执行： ```powershell uv run --project .. python -m pytest -q -p no:cacheprovider uv run --project .. python -m mypy minimal_agent tests ``` ## 仓库导航 - [`blogs/`](./blogs/)：按专题整理的技术文章。 - [`learning-records/`](./learning-records/)：通过检索或实践确认后的能力记录。 - [`lessons/`](./lessons/)：交互课程与可视化材料。 - [`practice/`](./practice/)：可以运行和测试的练习项目。 - [`research/`](./research/)：岗位、项目与技术资料调研。 - [`ROADMAP.md`](./ROADMAP.md)：长期阶段目标与验收门。 - [`DAILY-PLAN.md`](./DAILY-PLAN.md)：逐日任务索引和时间缩水规则。