企业官网建设流程全解析

1. 项目概述：从51.2万行代码中提炼的AI智能体工程实践

如果你正在构建一个AI智能体系统，特别是那种需要调用工具、处理复杂任务、并且要在生产环境中稳定运行的AI助手，那么你肯定遇到过这样的困境：模型本身的推理循环很简单，但要让整个系统真正可用，你需要处理记忆持久化、权限控制、上下文管理、多智能体协调等一系列“外围”问题。Anthropic的工程师们把这些外围系统统称为“Harness”——你可以理解为智能体的“缰绳”或“控制框架”。

最近我深度研究了一个开源项目keli-wen/agentic-harness-patterns-skill，它系统地分析了Anthropic开源的Claude Code运行时——那个支撑着51.2万行TypeScript代码库的生产级AI编程助手。这个项目没有简单地复制代码，而是从工程实践中提炼出了6个核心设计模式和11个深度参考文档，形成了一套可移植的、运行时无关的设计原则。无论你用的是Claude Code、Codex CLI、Gemini CLI还是自建的系统，这些模式都能给你带来直接的启发。

2. 智能体工程的核心挑战与Harness的价值

2.1 为什么模型循环简单，工程实现却复杂？

任何一个基础的AI智能体循环都可以用一句话描述：用户输入 -> LLM推理 -> 工具调用 -> 执行结果 -> 循环反馈。这个循环本身确实简单，但当你把它放到真实的生产环境中，问题就接踵而至。

我见过太多团队在初期只关注模型提示词和工具定义，结果系统上线后暴露出各种问题：智能体在两次会话间“失忆”，需要用户反复解释相同的工作流程；工具权限控制不严，导致潜在的安全风险；上下文窗口无节制增长，最终拖垮整个系统；多智能体协作时陷入混乱，各自为政。这些问题都不是模型本身的问题，而是工程系统设计的问题。

2.2 Harness的六个核心层次

agentic-harness-patterns项目将Harness分解为六个相互关联但又相对独立的层次，每个层次解决一类特定的工程问题：

1. 记忆（Memory）：解决“我的智能体在会话间忘记一切”的问题
2. 技能（Skills）：解决“我需要每次对话都重新解释工作流程”的问题
3. 工具与安全（Tools & Safety）：解决“我想要工具强大但不危险”的问题
4. 上下文工程（Context Engineering）：解决“我的智能体看到太多、太少或错误的东西”的问题
5. 多智能体协调（Multi-agent Coordination）：解决“我需要并行但不混乱”的问题
6. 生命周期与扩展性（Lifecycle & Extensibility）：解决“我需要钩子、后台任务、启动序列”的问题

这六个层次构成了一个完整的智能体控制系统。接下来我会逐一拆解每个层次的核心设计思想、实现要点以及我从实际工程中总结的经验教训。

3. 记忆系统设计：三种记忆类型与四级持久化策略

3.1 记忆不是单一概念

很多初代智能体系统把“记忆”简单理解为一个向量数据库，所有内容都往里塞。这在实际运行中会带来严重问题：用户的手动指令、智能体自动生成的内容、从会话中提取的背景信息，这三者的信任级别、持久化需求和审查机制完全不同。

Claude Code的实践给出了一个清晰的分类：

• 指令记忆（Instruction Memory）：由人类手动编写和审核的长期记忆，比如项目规范、团队约定、最佳实践。这类记忆需要最高级别的信任，通常存储在版本控制的配置文件中。
• 自动记忆（Auto-memory）：由智能体在运行过程中自动生成和写入的记忆，比如“用户偏好使用双引号”、“上次重构时移除了某个过时的模块”。这类记忆需要可审查、可回滚的机制。
• 会话提取（Session Extraction）：从对话历史中自动提取的结构化信息，比如“本次会话主要讨论了用户认证模块的重构”。这类记忆通常作为背景信息，为后续会话提供上下文。

注意：千万不要让智能体直接修改指令记忆。自动记忆和会话提取应该有独立的存储通道，并且要有明确的生命周期管理策略——有些记忆可能只需要保留24小时，有些则需要持久化数周。

3.2 四级持久化层次

在实际实现中，记忆系统需要分层处理：

1. 运行时缓存：当前会话的临时记忆，会话结束即消失
2. 会话持久化存储：完整的会话历史，可供后续检索
3. 结构化记忆库：从会话中提取的关键信息，按主题分类存储
4. 配置化知识库：手动维护的权威知识，变更需要人工审核

这种分层设计的关键在于隔离变更风险。智能体可以自由操作运行时缓存和会话存储，但对结构化记忆库的写入需要经过验证，对配置化知识库则只有读取权限。

3.3 实操心得：记忆系统的实现要点

我在自己的项目中实现类似系统时，总结了几个关键点：

第一，记忆的索引策略不能只依赖向量相似度。纯向量检索在遇到专业术语、缩写、同义词时会失效。Claude Code采用了混合索引：向量检索负责语义相似性，关键词倒排索引负责精确匹配，再加上基于时间的衰减权重。比如搜索“用户认证”，既会找到语义相近的“auth模块”，也会精确匹配“user authentication”，并且最近讨论过的内容权重更高。

第二，记忆的写入需要原子性保证。当多个智能体实例同时运行时，可能会并发写入记忆。你需要一个类似数据库事务的机制，或者至少要有乐观锁检测。我见过一个团队因为没有处理并发写入，导致记忆条目被重复存储，最终污染了整个记忆库。

第三，记忆的失效机制必不可少。不是所有记忆都需要永久保存。我建议为每类记忆设置明确的TTL（生存时间），并定期清理。更精细的做法是引入“记忆强度”概念——每次被检索到就增强一点，长期不被访问就逐渐衰减，低于阈值后自动归档或删除。

4. 技能系统：懒加载与成本控制的艺术

4.1 技能不是工具别名

很多人容易混淆“技能”和“工具”的概念。在我的理解中，工具是原子操作——读取文件、执行命令、调用API。而技能是工作流程的封装，它可能组合多个工具，包含特定的提示词模板，甚至有自己的记忆上下文。

Claude Code的技能系统设计有几个精妙之处：

技能发现必须廉价。如果每次会话开始都要加载所有技能的完整描述，上下文窗口很快就会被占满。他们的解决方案是：技能列表只包含最精简的元信息——技能名称、触发关键词、简短描述，这些内容加起来只占上下文窗口的1%左右。只有当智能体真正决定使用某个技能时，才加载其完整实现。

触发语言需要前置。技能的描述文档中，最重要的部分——触发条件、输入参数、预期输出——必须放在最前面。因为当上下文窗口不足时，系统会从尾部开始截断。如果你把核心信息藏在文档末尾，被截断后技能就无法正常工作了。

4.2 技能的四源发现机制

从代码分析来看，Claude Code的技能可以从四个来源发现：

1. 内置技能：运行时自带的技能，通常是最稳定、最通用的
2. 项目本地技能：存储在项目目录中的技能，针对特定代码库定制
3. 用户全局技能：用户个人目录中的技能，跨项目共享
4. 远程技能库：从技能市场动态安装的技能

这种多源设计既保证了灵活性，又维护了可控性。项目本地技能可以覆盖用户全局技能，而内置技能通常作为兜底方案。

4.3 实操中的技能管理经验

技能版本兼容性是隐形的坑。我早期的一个项目里，技能A依赖工具X的v1接口，技能B依赖工具X的v2接口。当工具X升级到v2后，技能A就 silently failed了——没有报错，只是产出结果不对。现在的做法是：每个技能明确声明其依赖的工具版本，运行时检查兼容性，不匹配就警告或自动寻找替代方案。

技能的热重载能力很重要。在开发调试阶段，你肯定不想每次修改技能定义都重启整个智能体系统。我现在的实现是：监控技能目录的文件变化，检测到更新后，先在新会话中验证技能语法，通过后再替换内存中的旧版本。对于正在使用该技能的活跃会话，可以选择继续使用旧版本直到会话结束，或者优雅地终止并提示用户重新开始。

技能间的依赖关系需要管理。有些高级技能会调用基础技能。如果基础技能被禁用或修改，依赖它的高级技能应该如何处理？我现在的方案是：技能注册时声明依赖，运行时检查依赖可用性。如果依赖不可用，可以选择降级到简化模式，或者直接告知用户该技能当前不可用。

5. 工具安全与权限控制：从“默认允许”到“默认拒绝”

5.1 权限管道的副作用设计

工具安全是智能体系统中最敏感的部分。一个常见的误区是只关注“是否允许调用”，但真正的生产系统需要考虑更多维度。

Claude Code的权限管道设计有一个关键洞察：权限检查应该有副作用。这听起来有点反直觉——权限检查通常被认为是无副作用的纯函数。但仔细想想，权限系统需要：

• 记录拒绝日志，用于安全审计
• 在某些情况下转换执行模式（比如从“写入”降级为“只读模拟”）
• 更新工具的使用计数和频率限制状态

这些都需要在权限检查过程中产生副作用。他们的实现采用了严格的分层评估：先检查最基本的权限（如“该用户是否被禁止使用此工具”），再检查上下文相关权限（如“在当前目录下是否允许执行shell命令”），最后检查参数级权限（如“是否允许删除根目录文件”）。

5.2 并发控制：每个调用都是独立的

另一个重要设计是：并发控制是每个工具调用级别的，而不是工具级别的。这意味着同一个工具的不同实例可以并行执行，只要系统资源允许。这比简单的“同一时间只允许一个实例运行”要灵活得多。

实现这种细粒度并发控制的关键是工具调用标识符。每个工具调用都有一个唯一ID，包含会话ID、时间戳、调用链信息。并发控制器基于这个ID进行调度和限制，而不是基于工具名称。

5.3 实操中的安全加固技巧

实现权限的“故障关闭”原则。我的经验是：当权限系统遇到不确定的情况时，应该默认拒绝而不是允许。比如网络故障导致无法查询权限策略时，工具调用应该被阻止，并记录详细的错误信息供后续审查。

工具调用的沙盒化执行。即使权限检查通过了，工具执行也应该在受控环境中进行。对于文件操作，可以使用覆盖文件系统（overlayfs）或写时复制；对于命令执行，可以使用容器或命名空间隔离。我现在的做法是：根据工具的危险等级分配不同的执行环境，从完全沙盒到半隔离再到完全信任。

参数验证与净化。很多安全漏洞不是来自工具本身，而是来自参数注入。比如一个“读取文件”工具，如果文件名参数包含../../../etc/passwd，就可能越权访问。我现在的参数验证流程是：1) 类型检查，2) 范围/格式验证，3) 路径规范化与边界检查，4) 敏感模式匹配（如检测到rm -rf模式则告警）。

6. 上下文工程：选择、压缩、写入、隔离的四维操作

6.1 上下文管理的四个核心操作

上下文窗口是智能体系统的稀缺资源。如何高效利用这有限的token空间，是工程上的关键挑战。Claude Code的实践将上下文管理抽象为四个基本操作：

选择（Select）：按需加载，而不是一次性加载所有可能相关的上下文。这需要建立高效的索引系统，能够快速定位哪些文档、代码片段、记忆条目与当前任务相关。

压缩（Compress）：当上下文接近窗口限制时，智能地压缩或摘要内容。关键是要保留“恢复指针”——如果后续需要详细信息，可以通过指针重新加载完整内容。

写入（Write）：智能体生成的新内容如何进入上下文？这不仅仅是追加，还包括结构化、打标签、建立关联索引。

隔离（Isolate）：在多智能体或复杂任务中，不同的子任务可能需要不同的上下文视图。隔离确保一个任务的噪声不会污染另一个任务的上下文。

6.2 渐进式披露的三层策略

在“选择”操作中，Claude Code采用了三层渐进式披露策略：

1. 元数据层：只显示文档的标题、类型、修改时间等基本信息，帮助智能体判断相关性
2. 摘要层：显示关键段落、函数签名、类定义等核心内容
3. 完整层：加载完整的文档内容

这种策略大幅减少了不必要的上下文占用。在我的实测中，对于大型代码库，元数据层通常只需要完整内容10%的token，就能让智能体做出80%准确的相关性判断。

6.3 压缩策略的实践经验

压缩不是简单的截断。直接截断长文档会丢失关键信息。我现在的压缩策略包括：

• 结构化摘要：对于代码文件，提取函数/类定义，省略实现细节
• 差异聚焦：对于多次修改的文件，只显示最近变更的部分
• 引用折叠：将长篇引用替换为“[详见文档X]”，需要时再展开

压缩需要可逆性。任何时候压缩内容，都必须保留足够的信息以便恢复。我的做法是：为每个压缩块生成一个唯一ID，并记录原始内容的存储位置和版本。当智能体请求“查看更多细节”时，可以通过ID快速加载完整内容。

压缩时机的选择。我最初实现的是定时压缩——每N轮对话压缩一次。但这不够智能：有时前几轮就耗尽了上下文，有时几十轮后还有充足空间。现在的策略是：监控上下文使用率，当超过阈值（如80%）时触发压缩；同时预测下一轮可能需要的token数，提前进行预防性压缩。

7. 多智能体协调：三种模式应对不同场景

7.1 协调器模式：零继承的顶层指挥

当任务需要高度协调、各子任务间依赖复杂时，协调器模式最合适。在这种模式下：

• 一个主协调器智能体负责任务分解和结果合成
• 多个工作者智能体执行具体子任务
• 关键设计：工作者之间没有直接通信，所有信息都通过协调器中转
• 零继承：工作者的上下文只包含分配给它的具体任务，不继承协调器的完整上下文

这种模式的优点是控制力强，避免了工作者间的混乱交互。缺点是协调器可能成为瓶颈，特别是当子任务需要频繁协调时。

我在实现中的一个重要经验：协调器必须合成理解，而不是简单委托。这意味着协调器不能只是把任务分出去就等待结果，它需要理解每个工作者的进展、遇到的问题、产生的中间结果，并基于这些信息调整整体策略。

7.2 分叉模式：完全继承的单层分解

对于可以相对独立执行的子任务，分叉模式更高效：

• 主智能体创建多个子智能体，每个获得完整的上下文副本
• 子智能体并行执行，完成后将结果返回给主智能体
• 完全继承：子智能体拥有和父智能体相同的上下文、技能、工具权限

这种模式的优点是子智能体有完整的上下文，可以做出更自主的决策。缺点是资源消耗大（每个子智能体都有完整的上下文副本），且可能产生不一致的状态。

我的优化经验：实现分叉缓存。当多个子智能体需要相同的底层数据时（比如读取同一个配置文件），不要让每个都独立读取。而是由父智能体预先读取并缓存，子智能体共享这个缓存。这大幅减少了IO操作和上下文重复。

7.3 集群模式：扁平化的对等网络

当任务需要多个智能体紧密协作、频繁交互时，集群模式更合适：

• 多个智能体组成扁平化的对等网络
• 每个智能体有特定的专长领域
• 智能体间可以直接通信，协商任务分配和结果整合

这种模式最灵活，但也最难控制。我现在的实现加入了通信协议约束：定义标准的消息格式、交互协议、冲突解决机制。比如当两个智能体都想修改同一个文件时，采用“先声明者优先”的锁机制。

7.4 多智能体系统的调试技巧

调试多智能体系统比单智能体复杂得多。我总结了几条实用技巧：

实现交互可视化。记录每个智能体的输入输出、工具调用、内部状态变化，并生成交互图。这能帮你理解智能体间的协作模式，发现死锁或循环依赖。

设置超时和回退机制。智能体间的通信可能因为各种原因失败。我的做法是：每个请求都有超时设置，超时后尝试重试（最多3次），仍然失败则触发回退到更简单的协作模式。

设计降级策略。当多智能体系统出现问题时，不应该完全崩溃，而应该优雅降级。比如协调器故障时，工作者可以切换到独立模式继续执行基本任务；网络分区时，智能体可以基于本地信息做出保守决策。

8. 生命周期管理与扩展性设计

8.1 钩子系统的信任模型

钩子（Hooks）是扩展智能体行为的主要方式，但也是安全风险的主要来源。Claude Code的钩子系统采用了一个严格的原则：钩子信任是全有或全无的。

这意味着：如果一个钩子被标记为“可信”，它就可以访问系统的所有能力；如果不可信，它的访问就受到严格限制。没有中间状态。这听起来有些极端，但实际工程中很合理：部分信任的钩子很难保证安全，一个小的权限漏洞就可能导致整个系统被攻破。

在我的实现中，钩子根据信任级别被分配到不同的执行环境：

• 可信钩子：在主进程中执行，可以访问所有API
• 沙盒钩子：在隔离的Worker中执行，只能通过定义良好的接口与主进程通信
• 不可信钩子：完全拒绝加载

8.2 任务的两阶段回收机制

长时间运行的任务需要妥善管理，避免资源泄漏。我借鉴的两阶段回收机制：

1. 软回收：通知任务需要结束，给它机会清理资源、保存状态
2. 硬回收：如果任务在超时后仍未结束，强制终止

关键是要区分不同类型的任务：

• 可中断任务：如文件处理，可以在任意点安全停止
• 原子任务：如数据库事务，必须完成当前原子操作
• 关键任务：如数据备份，不允许中断

为每类任务定义适当的回收策略，并在任务注册时声明其类型。

8.3 启动序列的依赖排序

智能体系统的启动不是简单的“加载所有组件”。组件间有复杂的依赖关系，加载顺序错误可能导致启动失败。Claude Code的启动序列设计有几个亮点：

依赖图解析：每个组件声明其依赖，启动器解析依赖图，确定正确的加载顺序。当检测到循环依赖时，启动失败并给出详细错误信息。

信任分割的环境变量：敏感配置（如API密钥）和普通配置（如超时设置）分开管理。只有通过信任检查的组件才能访问敏感配置。

记忆化并发调用：当多个组件依赖同一个初始化较慢的服务（如数据库连接）时，确保该服务只初始化一次，所有组件共享同一个实例。

8.4 扩展性设计的实践经验

插件系统的版本兼容性。我早期的一个错误是：插件接口一旦发布就永不改变。结果当系统需要新功能时，要么无法支持，要么通过丑陋的变通方案实现。现在的设计是：插件接口有明确的版本号，系统可以同时支持多个版本的接口，新插件用新接口，旧插件继续用旧接口，通过适配层转换。

配置的热重载。生产环境中的智能体系统需要在不重启的情况下更新配置。我的实现是：配置文件变更时，先在新会话中验证配置的有效性，通过后逐步应用到现有会话。对于无法热更新的配置（如信任模型变更），则标记现有会话为“过时”，在其自然结束后应用新配置。

监控与遥测的侵入性控制。监控是必要的，但过度的监控会影响性能甚至泄露敏感信息。我现在的监控系统是分层的：基础指标（如响应时间、错误率）默认开启；详细调试信息（如完整的提示词、工具调用参数）需要显式启用，且只保留短期。

9. 从Claude Code中学到的工程哲学

9.1 设计原则的普适性

研究Claude Code的代码库给我最大的启发是：好的工程原则是普适的。虽然这些模式是从一个具体的TypeScript代码库中提取的，但它们背后的思想适用于任何智能体系统，无论使用什么编程语言、什么AI模型。

比如“故障关闭”的安全原则，在Python、Go、Java的实现中同样重要。比如“渐进式披露”的上下文管理策略，无论底层是GPT、Claude还是Gemini，都能显著提升效率。

9.2 抽象与具体的平衡

Claude Code的代码在抽象层次上把握得很好。一方面，核心模式被抽象成可重用的组件；另一方面，具体实现又足够详细，可以直接参考。

我在自己的项目中借鉴了这种平衡：定义清晰的接口和抽象类，但同时也提供“开箱即用”的默认实现。这样其他开发者既可以直接使用，也可以基于接口实现自己的版本。

9.3 文档与代码的同步

Claude Code的另一个优点是文档和代码保持同步。每个重要组件都有详细的注释，解释设计决策、使用场景、注意事项。这大大降低了理解和扩展系统的难度。

我现在要求团队：每次提交代码时，如果修改了接口或核心逻辑，必须同时更新相关文档。我们甚至建立了自动化检查，如果检测到代码变更但没有相应的文档更新，CI会失败。

10. 实际应用中的调整与优化

10.1 根据团队规模调整复杂度

Claude Code的设计面向的是大规模、长期维护的项目。如果你的团队较小，或者项目处于早期阶段，可能不需要实现所有模式。

我的建议是：从最痛点开始。如果你的智能体总是忘记重要信息，先实现记忆系统。如果上下文管理混乱，先实现选择与压缩。如果安全问题让你夜不能寐，先强化权限控制。

逐步演进，而不是一次性构建完整系统。每个阶段都解决实际存在的问题，而不是预测未来可能的问题。

10.2 性能与功能的权衡

有些设计模式会增加系统复杂度，影响性能。比如细粒度的权限检查会增加每次工具调用的延迟；完整的记忆索引会占用更多内存。

我的经验法则是：先保证正确性，再优化性能。在系统稳定运行后，通过性能分析找到真正的瓶颈。很多时候，80%的性能问题来自20%的代码路径。集中优化这些热点，而不是全面优化。

10.3 测试策略的特别考虑

智能体系统的测试比传统软件更复杂，因为涉及非确定性的AI模型。我现在的测试策略包括：

单元测试：测试工具函数、权限检查、上下文管理等确定性组件。这些测试应该快速、稳定。

集成测试：测试多个组件的协作。使用固定的提示词和模拟的模型响应，确保系统流程正确。

模糊测试：用随机但合法的输入测试系统，发现边界情况的问题。

回归测试集：记录历史上出现过的错误场景，确保修复后不再复发。

人工验收测试：定期让真实用户测试系统，发现自动化测试无法覆盖的问题。

10.4 监控与告警的实践经验

监控智能体系统需要特别关注几个指标：

上下文使用率：监控平均和峰值token使用量，预测何时需要扩容或优化。

工具调用成功率：不同工具的成功率可能差异很大。低成功率的工具可能需要优化或替换。

用户满意度：通过直接反馈或间接指标（如任务完成率、会话长度）衡量。

异常模式检测：智能体系统可能产生“表面正常但实际错误”的输出。需要设计专门的检测逻辑，比如代码风格检查、安全规则验证等。

告警策略也要分层：轻微问题记录日志，中等问题发送通知，严重问题自动降级或停止服务。

11. 常见问题与排查实录

11.1 记忆系统问题

问题：智能体重复学习相同的内容，记忆库中有大量重复条目。

排查：检查记忆去重逻辑。可能是向量检索的相似度阈值设置过高，导致相似但不完全相同的内容被重复存储。

解决：实现多级去重：先精确匹配（哈希值），再相似度匹配（向量检索），最后人工规则匹配。为不同类型的记忆设置不同的相似度阈值。

问题：记忆检索返回不相关的结果。

排查：检查索引策略。纯向量检索在专业领域可能效果不佳。

解决：实现混合检索：向量检索 + 关键词检索 + 时间衰减。为不同内容类型配置不同的权重，代码片段更依赖结构匹配，自然语言更依赖语义匹配。

11.2 上下文管理问题

问题：上下文窗口很快耗尽，即使启用了压缩。

排查：检查压缩策略。可能是压缩过于激进，丢失了关键信息，导致智能体反复请求完整内容。

解决：调整压缩算法，保留更多结构化信息。实现“压缩质量”反馈循环：如果智能体频繁请求展开某个压缩块，说明该内容压缩过度，下次压缩时保留更多细节。

问题：智能体忽略了重要的上下文信息。

排查：检查选择策略。相关的内容可能没有被正确索引或检索。

解决：改进内容索引，不仅索引全文，还索引关键概念、实体、关系。实现检索结果的重排序，基于当前对话内容动态调整相关性评分。

11.3 工具调用问题

问题：工具调用超时，但不确定是工具本身慢还是网络问题。

排查：实现详细的工具调用追踪。记录每个阶段的耗时：权限检查、参数验证、实际执行、结果处理。

解决：为每个工具设置独立的超时配置。对于已知较慢的工具，提前告知用户预期等待时间。实现超时后的优雅降级，比如返回缓存结果或提供简化功能。

问题：工具权限检查通过，但执行时失败。

排查：权限系统可能没有覆盖所有失败场景。比如允许读取文件，但文件实际不存在；允许调用API，但API返回错误。

解决：区分“权限失败”和“执行失败”。权限失败应该阻止执行，执行失败应该返回详细错误信息。实现执行前的预检查，比如检查文件是否存在、API端点是否可达。

11.4 多智能体协调问题

问题：协调器成为性能瓶颈，任务整体执行时间反而比单智能体更长。

排查：检查协调器的任务分配和结果合成逻辑。可能是协调器过于细致地控制每个步骤，没有充分利用工作者的自主性。

解决：实现更粗粒度的任务分解。让工作者处理更大的子任务，减少与协调器的交互次数。允许工作者在遇到小问题时自主解决，而不是每次都请示协调器。

问题：工作者间状态不一致，导致最终结果矛盾。

排查：检查状态同步机制。可能是工作者基于不同时间点的快照工作。

解决：实现乐观锁或版本控制。每个工作者在开始任务时获取当前状态版本，提交结果时检查版本是否变化。如果状态已更新，需要重新基于新状态计算。

11.5 系统扩展性问题

问题：添加新插件后系统不稳定，但插件本身测试正常。

排查：插件可能在系统启动顺序的早期被加载，但依赖的服务还未就绪。

解决：实现更精细的启动阶段管理。将启动过程分为多个阶段，插件声明其所需的最低启动阶段。确保依赖服务在其依赖的插件之前就绪。

问题：系统在高负载下内存持续增长，最终崩溃。

排查：检查资源泄漏。可能是上下文缓存、记忆存储、会话状态等没有正确清理。

解决：实现资源使用监控和自动回收。设置内存使用阈值，超过时触发垃圾回收。为缓存实现LRU（最近最少使用）淘汰策略。定期检查并终止僵尸会话。

12. 从理论到实践：构建你自己的Harness系统

12.1 起步建议：最小可行Harness

如果你从零开始构建智能体系统，我建议先实现一个最小可行的Harness，包含以下核心组件：

1. 基础工具调用框架：定义工具接口，实现简单的权限检查（至少要有“允许/拒绝”两级）
2. 会话上下文管理：维护当前会话的对话历史，实现基本的长度限制和截断
3. 错误处理与重试：工具调用失败时的基本重试逻辑
4. 日志与监控：记录关键操作，便于调试

这个最小系统可能只有几百行代码，但已经能解决80%的基础问题。在此基础上，再根据实际需求逐步添加记忆、技能、多智能体等高级功能。

12.2 技术选型考虑

编程语言：选择你的团队最熟悉的语言。智能体系统的复杂性主要在架构设计，不在语言特性。TypeScript/JavaScript、Python、Go、Rust都是不错的选择，各有优劣。

向量数据库：如果需要语义搜索，需要选型向量数据库。对于中小规模项目，pgvector（PostgreSQL扩展）或Chroma可能足够；大规模项目可以考虑Weaviate或Qdrant。

缓存策略：内存缓存（如Redis）用于高频访问数据，磁盘存储用于持久化数据。考虑数据的访问模式和一致性要求。

监控系统：至少要有基本的日志和指标收集。开源方案如Prometheus + Grafana，或云服务商提供的监控工具。

12.3 迭代开发节奏

不要试图一次性构建完美的Harness系统。我建议的迭代节奏：

第一周：实现最小可行系统，能够完成最简单的任务（如回答基于文档的问题）。

第一个月：添加记忆系统和基础技能，让智能体能够记住用户偏好，执行简单的工作流程。

第三个月：完善权限控制和上下文管理，准备将系统提供给更多用户测试。

第六个月：实现多智能体协调和高级生命周期管理，支持复杂任务。

每个迭代周期都要有明确的目标和验收标准，并且留出时间处理技术债务。

12.4 团队协作建议

智能体系统开发需要跨领域的知识：AI/ML、软件工程、系统设计、用户体验。如果可能，组建跨职能团队：

• AI工程师：负责模型集成、提示词优化
• 后端工程师：负责系统架构、性能优化
• 前端工程师：负责用户界面、交互设计
• 安全工程师：负责权限控制、漏洞防护
• 产品经理：负责需求分析、用户体验

定期进行知识分享，确保团队成员理解系统的各个方面。特别是安全考虑，需要全员有基本的安全意识。

12.5 长期维护考虑

智能体系统不是一次构建就完成的，需要持续维护和演进：

API稳定性：公共接口要保持向后兼容。如果必须破坏性变更，提供迁移路径和足够长的过渡期。

依赖管理：AI模型、工具库、第三方服务的更新可能影响系统行为。建立完善的测试套件，在更新前充分测试。

技术债务：定期评估架构设计，重构过时的组件。但要注意平衡，不要为了重构而重构。

社区贡献：如果项目开源，建立清晰的贡献指南、代码审查流程、发布管理流程。

构建生产级的AI智能体系统确实充满挑战，但看到系统从简单原型成长为能够可靠处理复杂任务的助手，这种成就感是无可替代的。Harness系统的价值在于，它让AI的能力变得可控、可靠、可扩展——这才是AI技术真正落地应用的关键。