模块管理 - PinableAgents Wiki

模块系统架构

PinableAgents 的模块系统是整个平台的扩展基础。模块（Module）是一个包含工作流定义、智能体配置和辅助脚本的独立包，它通过标准化的接口与核心编排引擎集成。模块系统的设计遵循两个核心理念：组合优于继承和约定优于配置。

从技术角度看，每个模块是一个独立的目录，包含一个 module.json 清单文件和一组按约定命名的子目录。编排引擎在启动时扫描模块目录，解析清单文件，注册模块提供的工作流和智能体，并建立依赖关系图。

模块之间通过两种方式交互：依赖引用（一个模块声明依赖另一个模块的特定能力）和扩展点（一个模块为其他模块提供可插入的接口）。这种设计使得模块可以在不修改核心代码的情况下扩展系统能力。

模块定义格式：module.json

module.json 是每个模块的核心清单文件，定义了模块的元数据、依赖关系、提供的工作流和智能体以及配置选项。以下是完整的 Schema 说明：

{
  "name": "do",
  "version": "1.2.0",
  "description": "核心交付工作流，从需求分析到代码实现的完整流程",
  "author": "PinableLab",
  "license": "MIT",
  "homepage": "https://pinableagents.dev/modules/do",
  "repository": "https://github.com/pinablelab/module-do",
  "keywords": ["workflow", "delivery", "implementation"],
  "category": "core",
  "engine": ">=1.0.0",
  "dependencies": {
    "essentials": ">=1.0.0"
  },
  "conflicts": ["legacy-do"],
  "workflows": [
    {
      "name": "do",
      "entry": "workflows/do.yaml",
      "description": "标准交付工作流"
    }
  ],
  "agents": [
    {
      "name": "architect",
      "config": "agents/architect.yaml"
    },
    {
      "name": "implementer",
      "config": "agents/implementer.yaml"
    }
  ],
  "config_schema": "config-schema.json",
  "hooks": {
    "post_install": "scripts/setup.sh",
    "pre_activate": "scripts/check-deps.sh"
  }
}

字段	类型	必填	说明
`name`	string	是	模块唯一标识符，全小写，支持连字符
`version`	string	是	遵循语义化版本规范（SemVer）
`engine`	string	是	兼容的 PinableAgents 引擎版本范围
`dependencies`	object	否	依赖的其他模块及版本范围
`conflicts`	array	否	与之冲突的模块列表，不能同时安装
`workflows`	array	否	模块提供的工作流定义
`agents`	array	否	模块提供的智能体配置
`hooks`	object	否	生命周期钩子脚本路径

安装流程详解

模块的安装遵循四步流水线：下载 → 验证 → 注册 → 激活。每一步都有明确的成功条件和失败处理。

步骤一：下载（Download）

系统从模块注册中心或指定的 URL 下载模块压缩包。下载过程支持断点续传和带宽限制。对于本地模块，直接从指定路径复制。

# 从注册中心安装
pinable-agents modules install do

# 从本地路径安装
pinable-agents modules install --local ./my-custom-module

# 从 Git 仓库安装
pinable-agents modules install --git https://github.com/user/module.git

步骤二：验证（Validate）

下载完成后，系统执行以下验证：

校验 SHA256 哈希确保文件完整性
验证 module.json 符合 Schema 规范
检查 engine 版本兼容性
检查依赖是否满足，冲突是否存在

步骤三：注册（Register）

将模块信息写入系统的模块注册表（位于 ~/.pinable-agents/registry.json）。注册表记录每个模块的安装路径、版本、状态和配置。

步骤四：激活（Activate）

执行模块的 pre_activate 钩子（如有），然后将模块的工作流和智能体注册到编排引擎中。激活后模块即可使用。

如果安装过程中任一步骤失败，系统会自动回滚已完成的步骤，确保不会留下不完整的安装状态。

模块依赖与冲突解决

模块依赖管理采用与 npm 类似的语义化版本匹配策略。当安装一个模块时，系统会递归解析其依赖树，自动安装所有缺失的依赖模块。

冲突解决遵循以下规则：

版本冲突：当两个模块依赖同一模块的不同版本时，系统选择满足所有约束的最高版本。如果无法找到兼容版本，安装会失败并提示具体冲突信息。
互斥冲突：通过 conflicts 字段声明的互斥模块不能同时安装。系统在安装前检查互斥约束，如果发现冲突，提示用户先卸载冲突模块。
循环依赖：系统通过拓扑排序检测循环依赖。如果发现循环，安装会失败并以图形方式展示依赖环。

# 查看模块的依赖树
pinable-agents modules deps do

# 输出：
# do@1.2.0
# └── essentials@1.1.0

# 检查依赖冲突
pinable-agents modules check --conflicts

内置模块清单

PinableAgents 提供了一系列官方维护的内置模块，覆盖从日常开发到企业级协作的各种场景。

模块名	分类	说明	核心能力
`do`	工作流	核心交付工作流	需求分析、架构设计、代码实现、代码审查
`omo`	工作流	信号驱动路由工作流	智能路由、动态阶段、信号触发
`bmad`	工作流	企业级敏捷工作流	Scrum 团队模拟、Sprint 管理、验收标准
`sparv`	工作流	轻量级快速修复工作流	快速 bug 修复、小型变更
`essentials`	智能体	基础智能体集合	代码探索、架构设计、代码审查、测试编写
`develop`	智能体	开发增强智能体	调试辅助、性能分析、重构建议
`requirements`	工具	需求管理工具	需求解析、用户故事生成、验收条件
`webchat`	接口	Web 聊天界面	浏览器端交互、会话管理
`memorys`	工具	记忆与上下文管理	跨会话记忆、项目上下文持久化

创建自定义模块

自定义模块允许团队将特定的工作流程和智能体配置打包为可复用的模块。以下是创建自定义模块的完整步骤。

目录结构

一个标准的模块目录结构如下：

my-module/
├── module.json          # 模块清单（必需）
├── config-schema.json   # 配置项的 JSON Schema（可选）
├── workflows/
│   └── my-workflow.yaml # 工作流定义
├── agents/
│   ├── analyzer.yaml    # 智能体配置
│   └── executor.yaml
├── prompts/
│   ├── analyze.md       # 提示词模板
│   └── execute.md
├── scripts/
│   ├── setup.sh         # 安装后脚本
│   └── check-deps.sh    # 激活前检查
└── README.md            # 模块文档

编写工作流定义

工作流以 YAML 格式定义，描述任务执行的阶段序列和每个阶段使用的智能体。

# workflows/my-workflow.yaml
name: my-workflow
description: 自定义工作流示例
phases:
  - name: analyze
    agent: analyzer
    description: 分析任务需求
    timeout: 120
    output:
      - analysis_report

  - name: execute
    agent: executor
    description: 执行具体任务
    depends_on: [analyze]
    input:
      - analysis_report
    timeout: 300
    validation:
      - command: "npm test"
        expect: exit_code_0

配置智能体

每个智能体通过 YAML 文件定义其行为参数。

# agents/analyzer.yaml
name: analyzer
display_name: 需求分析师
model:
  backend: claude
  name: claude-opus-4-6
  temperature: 0.3
  max_tokens: 4096
system_prompt: |
  你是一位经验丰富的软件需求分析师。
  你的任务是分析用户需求，产出结构化的分析报告。
  报告应包含：功能需求、技术约束、风险评估。
tools:
  - file_read
  - file_search
  - codebase_explore

打包与发布

# 验证模块结构
pinable-agents modules validate ./my-module

# 打包为可分发的压缩包
pinable-agents modules pack ./my-module
# 输出：my-module-1.0.0.tar.gz

# 本地安装测试
pinable-agents modules install --local ./my-module-1.0.0.tar.gz

模块生命周期钩子

模块通过钩子（Hooks）在生命周期的关键节点执行自定义逻辑。系统支持以下四个钩子：

钩子名称	触发时机	典型用途
`post_install`	模块文件解压完成后	下载额外资源、编译本地依赖
`pre_activate`	模块激活前	检查运行环境、验证外部依赖
`pre_deactivate`	模块停用前	保存状态、清理临时资源
`pre_uninstall`	模块卸载前	清理配置、移除注册数据

钩子脚本在模块目录上下文中执行，拥有访问模块文件的完整权限。脚本的退出码决定生命周期操作是否继续：退出码 0 表示成功，继续执行；非零退出码表示失败，操作回滚。

#!/bin/bash
# scripts/check-deps.sh - pre_activate 钩子示例
# 检查 Python 3 是否可用（本模块的依赖）

if ! command -v python3 &> /dev/null; then
    echo "错误：此模块需要 Python 3，请先安装"
    exit 1
fi

PYTHON_VERSION=$(python3 --version | cut -d' ' -f2)
echo "检测到 Python $PYTHON_VERSION"
exit 0

版本管理与更新

模块版本遵循语义化版本规范（SemVer）：MAJOR.MINOR.PATCH。版本号的变更含义如下：

MAJOR：不兼容的 API 变更，升级可能需要修改配置
MINOR：向后兼容的新功能
PATCH：向后兼容的 bug 修复

更新操作默认只安装 MINOR 和 PATCH 更新，MAJOR 更新需要用户明确确认。

# 检查可用更新
pinable-agents modules outdated

# 更新特定模块
pinable-agents modules update do

# 更新所有模块（仅 minor/patch）
pinable-agents modules update --all

# 强制更新到 major 版本
pinable-agents modules update do@2.0.0 --allow-major

建议在更新模块前先运行 pinable-agents modules outdated 查看可用更新及其变更日志，评估更新影响后再执行。

模块市场概念

PinableAgents 正在规划模块市场（Module Marketplace）功能，它将提供一个中心化的模块发现和分发平台。计划中的功能包括：

模块搜索与发现：按分类、评分、下载量浏览和搜索模块。
用户评价：安装者可以对模块进行评分和评论。
自动兼容性检查：市场会标注模块与当前引擎版本的兼容性。
团队私有仓库：企业用户可以搭建私有模块仓库，托管内部模块。
模块模板：提供脚手架工具快速创建新模块项目。

在市场功能正式上线前，你可以通过 Git 仓库或本地路径的方式分享和安装自定义模块。社区贡献的模块可以在 GitHub 上的 pinablelab/community-modules 仓库中找到。