产品开发中的胶囊和 AI 智能体

胶囊实战：集成AI代理实现开发自动化

产品开发中的AI代理需要严格的结构化上下文。胶囊以极简格式提供专家知识和即用工具，确保生成可预测的代码和架构工件。这消除了顺序任务中架构演进的混乱。

代理模式与结构的作用

代理用于原型设计和产品开发。在原型设计中，重点是快速获得结果，无需约束。在产品中，非功能性需求是强制性的：可维护性、可读性、可扩展性。

没有结构时，代理会做出任意选择，失去服务一致性。胶囊通过三个组件解决此问题：

• 专家知识：打包的经验，无需猜测。
• 极简主义：本质内容，无额外信息占用上下文窗口。
• 即用工具：代理的方法、技能、接口。

额外项目上下文存储在 AGENTS.md 和 CLAUDE.md 中——风格指南、提交格式。

通过MCP服务器传递知识

专家知识通过MCP服务器传递给代理，包含两个工具：

• 框架文档：原则、服务结构、BaseMethod模式、DI容器、事件。
• archland.json文档：格式、填充规则、C4图生成。

分离节省令牌：代理请求相关工具。文档面向代理——命令式风格、规则、算法。

来自nsc-toolkit框架文档的示例：

# nsc-toolkit框架：代码生成指南

本文档结构化为规则和模板集，用于自动生成正确代码。

## 框架核心：方法类（BaseMethod）

实现规则：
- 声明静态设置属性，从service.schema.json复制。
- 主逻辑在handler方法中实现。
- 通过构造函数注入依赖，使用@inject装饰器。
- 使用this.logger进行日志记录。
- 使用this.emitter生成事件。

规则：为service.schema.json中的每个RPC调用创建一个方法。
规则：只有当前和使用的依赖项应绑定到容器。

archland.json的算法：

每个服务的生成算法：

步骤1. 基本信息：
  - 读取service.schema.json → 名称、描述
  - 写入路径：describePath、folderPath

步骤2. DI容器分析：
  - 读取service.ts
  - 为每个container.bind()创建Dependency对象
  - 分析标签以确定类型和外部性

步骤3. 方法分析：
  - 对于methods/中的每个类：
    读取service.schema.json获取描述
    分析代码以获取依赖调用和事件生成

步骤4. 订阅分析：
  - 对于processing/中的每个类：
    从inversion.types.ts确定DI键
    分析start()方法以确定源服务

步骤5. 将所有数据收集到单个archland.json对象中

实践：添加ListOrders方法

场景：在@services/order服务中添加列出用户订单的方法，并暴露给HTTP API。

开发者描述数据格式。代理在service.schema.json中生成模式：

"ListOrders": {
  "action": "ListOrders",
  "description": "检索用户订单列表",
  "request": {
    "type": "object",
    "properties": {
      "credentials": {
        "type": "object",
        "properties": {
          "user_id":  { "type": "string" },
          "space_id": { "type": "string" }
        },
        "required": ["user_id", "space_id"]
      }
    },
    "required": ["credentials"]
  },
  "response": {
    "type": "object",
    "properties": {
      "result": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order_id":   { "type": "string" },
                "product_id": { "type": "string" },
                "quantity":   { "type": "number" },
                "created_at": { "type": "string" }
              },
              "required": ["order_id", "product_id", "quantity", "created_at"]
            }
          }
        }
      }
    },
    "required": ["result"]
  }
}

给代理的提示：

在@services/order服务中创建新的ListOrders方法。
方法接受：来自credentials的user_id。
返回：订单列表，每个包含字段order_id、product_id、quantity、created_at。
在@services/gate的@services/gate/routes/orders.ts端点集中暴露此方法。

代理操作序列：

• 读取CLAUDE.md → 请求MCP文档。
• 将模式添加到service.schema.json。
• 使用模板运行代码生成。
• 使用@inject、端口实现业务逻辑。
• 按照模式添加HTTP端点。
• 根据规则形成提交。

时间：10分钟。模板可重复用于类似任务。

生成架构相册

提示：生成archland.json和项目的架构相册。

代理从MCP检索文档，遍历服务，分析模式、DI、方法、订阅。将数据收集到archland.json中，包含问题区域的C4图。该过程基于文档中的算法是确定性的。

关键要点

• 胶囊为产品开发中的代理提供结构。
• MCP服务器通过极简工具传递专家知识。
• 文档是命令式的：规则、算法、代理模板。
• 任务自动化：代码生成、HTTP端点、架构相册在10分钟内完成。
• 可预测性：统一架构，无混乱变更。

— Editorial Team