智能体最近的智能体讨论已经从“模型能不能聊天”转向“模型能不能在边界内完成一段工作”。OpenAI Agents SDK 的公开文档把 Agent、工具、交接、Guardrails、人工介入和追踪列为核心积木MCP 官方文档则把它定义为连接 AI 应用与外部数据源、工具和工作流的开放标准。对个人项目来说最值得借鉴的不是堆概念而是把一段真实流程拆成可检查的步骤。本文用我正在维护的Personal Ledger做一次轻量实践把“记账、学习积累、知识整理和查询”看成几个工具由后端先识别意图再路由到对应服务涉及写入知识库时先生成草稿用户确认后才落库。它不是一个完全自主的 Agent也没有把项目包装成已经接入 MCP而是展示一条更容易维护的 Agent 化路线。先看一条完整链路输入、路由、工具、确认项目的入口保持为一个文本框。用户可以输入一段记录也可以直接问问题今天午餐 32 元晚上听英语 30 分钟 总结一下本周项目进展并整理成知识卡片 这个月餐饮大概花了多少后端先执行意图识别再选择处理路径输入文本 | v 意图路由 /api/intent |-- 记录写入 - /api/records/ingest |-- 统计查询 - /api/monthly-summary 或 /api/analytics |-- 知识整理 - /api/knowledge/summarize |-- 综合分析 - /api/analyze这一步的价值在于查询不会被误当成新记录知识整理也不会直接改写原始数据。它更像一个有明确边界的工作流控制器而不是把所有请求都交给模型自由发挥。意图路由先用规则挡住高确定性请求在app/main.py中分析请求会先经过_analysis_route。金额、日期、时长和常见查询词等高确定性信息优先由本地规则处理只有长文本或语义不明确的内容才交给可选的模型服务。这种“规则优先、模型补充”的方式有三个好处外部模型暂时不可用时基础记录仍能保存。重要字段的格式和类型由 Pydantic 校验错误更容易定位。每个路由都能单独测试不必用一条大提示词覆盖全部场景。示意代码如下实际项目还会继续做日期和金额的结构化校验def route_question(question: str) - str: text question.strip() if any(word in text for word in (花了多少, 支出, 收入, 账单)): return ledger_query if any(word in text for word in (总结, 复盘, 知识卡片, 项目进展)): return knowledge return general_analysis工具边界每个动作只负责一件事把后端接口当成工具时关键不是工具数量而是工具的职责要清晰。项目目前可以按下面的方式理解工具作用是否写入POST /api/records/ingest把口述内容解析为账目或积累记录是GET /api/monthly-summary返回月度汇总和趋势否GET /api/accumulation/summary查询学习、阅读和运动投入否POST /api/knowledge/summarize生成知识文档草稿只生成草稿POST /api/knowledge/drafts/{draft_id}/confirm用户确认后写入知识库是POST /api/analyze组合账目、积累和知识检索结果默认不写入工具接口的输入和输出都用 Pydantic schema 描述SQLite 负责保存原始记录、批次信息和知识全文索引。这样做的一个实际收益是以后即使接入 MCP也可以先把这些稳定接口包装成 MCP tools而不需要重写核心业务。知识整理把“自动生成”和“最终写入”分开Agent 最容易出问题的地方往往不是生成一段文字而是生成内容后直接覆盖数据。项目的知识整理接口采用两阶段流程/api/knowledge/summarize根据输入生成标题、正文、主题、标签和事件草稿。页面展示草稿用户可以修改日期、领域、主题和标签。/api/knowledge/drafts/{draft_id}/confirm只在确认后写入knowledge_notes。这就是一个很实用的人在回路Human-in-the-loop边界模型可以整理用户决定是否入库。对于个人复盘、项目笔记和工作记录这个确认按钮比“全自动写入”更重要因为它让错误可见、可撤回也方便之后追踪来源。数据层SQLite 适合小型、可自托管的 Agent 原型这个项目没有引入复杂的分布式存储而是使用 SQLite 保存交易、积累记录、知识草稿和批次信息知识检索使用 FTS5 全文索引。对于单用户或小团队的内部工具这种选择足够直接数据库文件可以随应用一起备份。Docker Compose 只需要挂载一个持久化目录。读写路径清晰调试时可以直接检查 SQL 和 schema。部署时把代码目录、数据目录和备份目录分开模型服务的密钥只放在环境变量中。文章截图使用的是脱敏演示数据不包含真实账号、地址或访问凭据。从 MCP 热点得到的一个工程启发MCP 官方文档的核心表述是“让 AI 应用连接到外部系统”并强调数据源、工具和工作流的标准化连接。这个项目暂时没有实现 MCP Server因此不能把它写成“MCP 实战”但它已经具备一个重要前提工具边界稳定、输入输出有 schema、写入动作有确认点。如果下一步要扩展可以按这个顺序做为月度汇总、知识搜索等只读接口补充稳定的 JSON schema。把只读接口包装成 MCP resources 或 tools先验证查询链路。对写入型工具增加权限、幂等键和审计日志。在真正接入外部系统前保留人工确认和失败回滚。本地运行与验证python -m venv .venv . .venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --reload启动后打开http://127.0.0.1:8000先用演示文本测试路由再查看历史、积累和知识页面。生产部署使用 Docker Compose并把 SQLite 数据目录挂载到宿主机。建议至少补三类测试意图路由测试、知识草稿确认测试、模型服务不可用时的降级测试。Agent 的可靠性不是靠一句“请谨慎回答”获得的而是靠接口边界、数据校验和可回滚流程积累出来的。事实来源与边界说明OpenAI Agents SDK 文档https://openai.github.io/openai-agents-python/Model Context Protocol 文档https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro本文项目D:\Desktop\app以当前代码和脱敏演示数据为依据。文中的官方能力描述来自上述公开页面项目部分是本地代码阅读和界面实测不代表项目已经具备文中提到的全部 SDK 或 MCP 能力。涉及个人数据时请先做备份、权限控制和脱敏处理。
智能体最近的智能体讨论已经从“模型能不能聊天”转向“模型能不能在边界内完成一段工作”。OpenAI Agents SDK 的公开文档把 Agent、工具、交接、Guardrails、人工介入和追踪列为核心积木MCP 官方文档则把它定义为连接 AI 应用与外部数据源、工具和工作流的开放标准。对个人项目来说最值得借鉴的不是堆概念而是把一段真实流程拆成可检查的步骤。本文用我正在维护的Personal Ledger做一次轻量实践把“记账、学习积累、知识整理和查询”看成几个工具由后端先识别意图再路由到对应服务涉及写入知识库时先生成草稿用户确认后才落库。它不是一个完全自主的 Agent也没有把项目包装成已经接入 MCP而是展示一条更容易维护的 Agent 化路线。先看一条完整链路输入、路由、工具、确认项目的入口保持为一个文本框。用户可以输入一段记录也可以直接问问题今天午餐 32 元晚上听英语 30 分钟 总结一下本周项目进展并整理成知识卡片 这个月餐饮大概花了多少后端先执行意图识别再选择处理路径输入文本 | v 意图路由 /api/intent |-- 记录写入 - /api/records/ingest |-- 统计查询 - /api/monthly-summary 或 /api/analytics |-- 知识整理 - /api/knowledge/summarize |-- 综合分析 - /api/analyze这一步的价值在于查询不会被误当成新记录知识整理也不会直接改写原始数据。它更像一个有明确边界的工作流控制器而不是把所有请求都交给模型自由发挥。意图路由先用规则挡住高确定性请求在app/main.py中分析请求会先经过_analysis_route。金额、日期、时长和常见查询词等高确定性信息优先由本地规则处理只有长文本或语义不明确的内容才交给可选的模型服务。这种“规则优先、模型补充”的方式有三个好处外部模型暂时不可用时基础记录仍能保存。重要字段的格式和类型由 Pydantic 校验错误更容易定位。每个路由都能单独测试不必用一条大提示词覆盖全部场景。示意代码如下实际项目还会继续做日期和金额的结构化校验def route_question(question: str) - str: text question.strip() if any(word in text for word in (花了多少, 支出, 收入, 账单)): return ledger_query if any(word in text for word in (总结, 复盘, 知识卡片, 项目进展)): return knowledge return general_analysis工具边界每个动作只负责一件事把后端接口当成工具时关键不是工具数量而是工具的职责要清晰。项目目前可以按下面的方式理解工具作用是否写入POST /api/records/ingest把口述内容解析为账目或积累记录是GET /api/monthly-summary返回月度汇总和趋势否GET /api/accumulation/summary查询学习、阅读和运动投入否POST /api/knowledge/summarize生成知识文档草稿只生成草稿POST /api/knowledge/drafts/{draft_id}/confirm用户确认后写入知识库是POST /api/analyze组合账目、积累和知识检索结果默认不写入工具接口的输入和输出都用 Pydantic schema 描述SQLite 负责保存原始记录、批次信息和知识全文索引。这样做的一个实际收益是以后即使接入 MCP也可以先把这些稳定接口包装成 MCP tools而不需要重写核心业务。知识整理把“自动生成”和“最终写入”分开Agent 最容易出问题的地方往往不是生成一段文字而是生成内容后直接覆盖数据。项目的知识整理接口采用两阶段流程/api/knowledge/summarize根据输入生成标题、正文、主题、标签和事件草稿。页面展示草稿用户可以修改日期、领域、主题和标签。/api/knowledge/drafts/{draft_id}/confirm只在确认后写入knowledge_notes。这就是一个很实用的人在回路Human-in-the-loop边界模型可以整理用户决定是否入库。对于个人复盘、项目笔记和工作记录这个确认按钮比“全自动写入”更重要因为它让错误可见、可撤回也方便之后追踪来源。数据层SQLite 适合小型、可自托管的 Agent 原型这个项目没有引入复杂的分布式存储而是使用 SQLite 保存交易、积累记录、知识草稿和批次信息知识检索使用 FTS5 全文索引。对于单用户或小团队的内部工具这种选择足够直接数据库文件可以随应用一起备份。Docker Compose 只需要挂载一个持久化目录。读写路径清晰调试时可以直接检查 SQL 和 schema。部署时把代码目录、数据目录和备份目录分开模型服务的密钥只放在环境变量中。文章截图使用的是脱敏演示数据不包含真实账号、地址或访问凭据。从 MCP 热点得到的一个工程启发MCP 官方文档的核心表述是“让 AI 应用连接到外部系统”并强调数据源、工具和工作流的标准化连接。这个项目暂时没有实现 MCP Server因此不能把它写成“MCP 实战”但它已经具备一个重要前提工具边界稳定、输入输出有 schema、写入动作有确认点。如果下一步要扩展可以按这个顺序做为月度汇总、知识搜索等只读接口补充稳定的 JSON schema。把只读接口包装成 MCP resources 或 tools先验证查询链路。对写入型工具增加权限、幂等键和审计日志。在真正接入外部系统前保留人工确认和失败回滚。本地运行与验证python -m venv .venv . .venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --reload启动后打开http://127.0.0.1:8000先用演示文本测试路由再查看历史、积累和知识页面。生产部署使用 Docker Compose并把 SQLite 数据目录挂载到宿主机。建议至少补三类测试意图路由测试、知识草稿确认测试、模型服务不可用时的降级测试。Agent 的可靠性不是靠一句“请谨慎回答”获得的而是靠接口边界、数据校验和可回滚流程积累出来的。事实来源与边界说明OpenAI Agents SDK 文档https://openai.github.io/openai-agents-python/Model Context Protocol 文档https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro本文项目D:\Desktop\app以当前代码和脱敏演示数据为依据。文中的官方能力描述来自上述公开页面项目部分是本地代码阅读和界面实测不代表项目已经具备文中提到的全部 SDK 或 MCP 能力。涉及个人数据时请先做备份、权限控制和脱敏处理。
