模块系统架构

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

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

模块管理方式

模块管理在 pinable-desktop 中通过图形界面完成，不支持命令行安装。

通过 GUI 管理模块

在 pinable-desktop 左侧导航栏点击 Modules 进入模块管理中心。

功能	操作方式
查看已安装模块	模块页面以卡片网格展示所有已安装模块
安装模块	点击模块卡片上的"安装"按钮
卸载模块	在模块详情面板中点击"卸载"
查看模块详情	点击模块卡片展开详情面板
批量操作	多选模块后进行批量启用、禁用或卸载
检查更新	当已安装模块有新版本时，卡片右上角显示更新徽章

模块安装流程（GUI 触发）

当你在 Modules 页面点击安装一个模块时，后台自动完成以下步骤：

1. 下载：从模块注册中心下载模块压缩包
2. 验证：校验 SHA256 哈希，验证 module.json Schema
3. 注册：将模块信息写入 ~/.pinable/registry.json
4. 激活：执行 pre_activate 钩子（如有），注册工作流和智能体

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

模块定义格式：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	否	模块提供的智能体配置
config_schema	string	否	配置项的 JSON Schema 文件路径
hooks	object	否	生命周期钩子脚本路径

模块模板

导出模块模板

模块模板导出（workflow_export 功能，需 License 支持）：在 Pro/Team License 下，可将已安装的模块导出为可复用的模板文件。

操作方式：

1. 点击模块卡片右侧菜单（... 按钮）
2. 选择"Export Template"
3. 选择导出路径
4. 系统生成模块模板文件（包含 module.json、workflows、agents 等目录）

导出的模板可在其他环境或团队成员之间共享。

导入模块模板

两种导入方式：

• 从文件导入：选择导出的模板 ZIP/JSON 文件
• 从文件夹导入：直接选择模块目录路径

导入流程：

1. 点击页面中的"Import"按钮
2. 选择文件或文件夹
3. 系统验证模板结构和 module.json
4. 验证通过后安装到本地模块目录

配置 Schema 与配置值

Config Schema

每个模块可选择提供 config-schema.json，定义模块支持的所有配置项及其约束：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "default_backend": {
      "type": "string",
      "description": "默认使用的 AI 后端",
      "enum": ["claude", "codex", "gemini", "opencode"]
    },
    "max_tokens": {
      "type": "integer",
      "description": "单次请求最大 Token 数",
      "minimum": 100,
      "maximum": 100000
    },
    "timeout_seconds": {
      "type": "integer",
      "description": "超时时间（秒）",
      "default": 120
    }
  },
  "required": ["default_backend"]
}

Config Schema 功能：

• 表单驱动的配置编辑界面（而不是原始 JSON 编辑）
• 输入验证和约束检查
• 默认值自动填充
• 配置项文档说明

Config Values

每个模块的实际配置值存储在模块目录的 config-values.json 中（或由用户自定义路径）。

查看配置值：点击模块详情中的"Config Values"标签页，查看模块当前的运行配置。

编辑配置值：在模块详情面板中可直接编辑配置值，保存后自动写入 config-values.json。

Config Status：每个模块卡片右下角显示配置状态徽章：

• 绿色 "configured"：所有必需配置项已填写
• 橙色 "N missing"：缺少 N 个必需配置项

模块使用量分析

Usage Counts（使用量统计）

Modules 页面显示每个模块被引用的次数（usage counts），反映模块在当前工作流中的活跃程度。

查看方式：在模块列表中，每张卡片底部显示 usage count 数字。

usage count 的含义：模块被工作流定义引用的次数。count = 0 表示模块未被任何工作流使用，属于"孤岛模块"。

模块分析（Module Analysis）

点击模块卡片的菜单，选择"Analyze"，系统对模块进行静态分析，产出模块质量报告：

分析内容：

• 模块结构完整性（workflows/agents/prompts 目录是否齐全）
• 依赖完整性（所有依赖模块是否已安装）
• 配置完整性（必需的配置项是否已填写）
• 潜在问题检测

分析结果标记：已分析的模块在卡片上显示"analyzed"徽章。

内置模块清单

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

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

模块生命周期钩子

模块通过钩子（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

模块过滤器

Modules 页面提供三种过滤器帮助定位模块：

过滤器	选项
安装状态	All / Installed / Not Installed
分析状态	All / Analyzed / Not Analyzed
使用情况	All / Used / Unused

结合搜索框，可以快速找到特定模块。

创建自定义模块

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

目录结构

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

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

模块来源与分发

当前版本的模块分发方式以本地安装与仓库分享为主：

• GUI 安装：通过 pinable-desktop 的模块管理页面安装/卸载
• 本地路径导入：从本地目录导入模块包
• 仓库分享：通过 GitHub 仓库共享团队模块

社区模块可参考 pinablelab/community-modules 仓库。