> **来源：[研报客](https://pc.yanbaoke.cn)** # AI AGENT 技术与实践蓝皮书总结 ## 核心内容 《AI AGENT 技术与实践蓝皮书》是一本关于 WorkBuddy 的技术解析手册，旨在揭示其内部架构、运行机制与扩展系统。本书以“Harness”为核心概念，介绍其如何通过本地文件与数据库的协同工作，实现复杂任务的自动化处理与执行。书中通过拆解一次对话流程，引出五层心智模型与文件地图，帮助读者理解 WorkBuddy 的工作原理与可定制性。 ## 主要观点 1. **Harness 的概念** - Harness 是一套让 AI 能力落地的工程系统，不是模型本身。 - 它分为五层：运行环境层、引导层、反馈层、编排层、迭代层。 2. **WorkBuddy 的结构** - 所有配置、记忆、插件、技能、会话记录等都存储在 `~/.workbuddy` 目录中。 - 本地文件负责存储，SQLite 数据库负责调度状态管理。 3. **五环对话模型** - 一次对话被拆解为五个环节：上下文拼装、模型处理、工具执行、留痕、交付与沉淀。 - 每个环节都有对应的文件证据，且可逆操作，便于排查问题。 4. **系统提示词的拼装机制** - 系统提示词是模板、片段与插槽的组合，由本地文件控制。 - 交互模式与专家模式通过不同的片段组合实现，可实现灵活切换。 5. **记忆系统** - 记忆分为三层：云端记忆、用户级本地记忆、工作区记忆。 - 每一层有不同存储位置、读写权限与限额。 6. **身份系统** - 包含 SOUL.md、IDENTITY.md、USER.md 三个文件，分别定义助手的人格、身份和用户画像。 - 身份与专家人设存在冲突风险，需通过明确的优先级规则避免。 7. **专家系统** - 专家是带有 UI 的 SubAgent 插件，包含人设提示词、技能、快捷按钮等。 - 专家与专家团的区别在于：专家是单 Agent，专家团是多个 Agent 的协作机制。 8. **插件系统** - 插件分为五类市场：codebuddy-plugins-official、cb_teams_marketplace、workbuddy-builtin、experts、knowledge-community。 - 插件可注入技能、智能体、规则、MCP 和工具，具备不同侵入度。 9. **安全与隐私** - WorkBuddy 有安全机制，包括权限模式、敏感数据隔离、文件快照、审计日志等。 - 提供安全自查方法，确保用户数据安全。 10. **生态与兼容性** - WorkBuddy 所有内容均基于 CodeBuddy 生态，保持格式统一，便于复用。 - 产品定位清晰，支持从代码助手到通用助手的扩展。 ## 关键信息 ### 1. **文件与数据库的分工** - **SQLite 数据库**：管理定时任务、会话统计、工作空间等运行时状态。 - **文件系统**：存储提示词模板、身份文件、技能、插件、记忆等。 ### 2. **五层 Harness 模型** | 层级 | 职责 | 本地证据 | 对应章节 | |------|------|----------|----------| | 运行环境层 | 确定 Agent 执行边界 | 沙箱白名单、连接器、自带运行时 | 第11、12章 | | 引导层 | 任务开始前的前置条件 | 提示词模板、身份文件、技能、规则文件 | 第4、5、6、9章 | | 反馈层 | 提供执行错误反馈 | 工具报错、审计日志、文件快照 | 第10章 | | 编排层 | 多能力组织方式 | 专家、插件、技能、模型路由 | 第7、8章 | | 迭代层 | 系统自我进化 | 版本日志、更新机制 | 附录 D、第13章 | ### 3. **数据目录结构** - `~/.workbuddy` 目录包含六个家族：身份与记忆、扩展系统、配置、会话与证据、调度、运行时杂项。 - 每个目录都有明确的职责与内容，便于定位与管理。 ### 4. **身份与专家人设冲突** - 身份文件（SOUL、IDENTITY、USER）在常规对话中注入，但在专家模式下会优先人设提示词。 - 身份文件可安全修改，但需注意不存储敏感信息。 ### 5. **专家插件结构** - 专家插件包含四件套：`plugin.json`（清单）、`agents/*.md`（人设）、`skills/*.md`（技能）、`avatars/*`（头像）。 - 专家可有 rules 目录，用于注入常驻规则，影响模型行为。 ### 6. **插件注入内容分类** - **技能**：方法论文档，按需调用。 - **智能体**：人设提示词，替代或叠加默认人格。 - **规则**：常驻约束，影响模型行为。 - **MCP 与工具**：连接外部服务，执行具体任务。 - **Hook**：插件可拦截指定事件，如文件删除、支付等。 ### 7. **安全机制** - 提示词注入、本地凭证、文件系统权限、数据出域等是主要风险点。 - 提供安全自查方法，建议用户定期检查并清理敏感数据。 ### 8. **实战与排查** - 五步排查法：定位问题、检查配置、查看日志、验证文件、评估版本。 - 可进行第一次安全定制，包括身份修改、插件筛选、规则注入等。 ### 9. **教学与复用** - 本书内容可作为教学材料，用于视频课、认证课、图书写作。 - 提供教学资产清单，便于课程设计与教学复用。 ## 附录信息 - **附录 A**：`~/.workbuddy` 目录速查表，列出每个目录与文件的职责。 - **附录 B**：五步排查卡（打印版），方便用户快速排查问题。 - **附录 C**：术语表，解释关键概念与文件结构。 - **附录 D**：版本快照与取证方法，提供版本对比与文件证据标注。 ## 结语 本书为 WorkBuddy 的用户与开发者提供了全面的系统理解与操作指南，强调从“UI 按钮”到“磁盘文件”的翻译路径，以及如何通过文件与配置实现定制与安全。它不仅是技术手册，更是理解和掌控 AI Agent 的工具书。