WorkBuddy_Harness技术与实践指南_60页_40mb

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 模型

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 的工具书。