PinableAgents
智能体系统概述
在 PinableAgents 的架构中，智能体（Agent）是执行具体任务的最小单元。每个智能体拥有独立的系统提示词、模型参数和工具权限，它们通过工作流的阶段（Phase）被编排调用。自定义智能体允许你创建具有特定领域专业知识的预设角色，使 AI 在特定任务上表现得更加精准和可靠。
PinableAgents 的智能体系统遵循"专家分工"理念：与其让一个通用 AI 处理所有事务，不如创建多个专精的智能体，每个只负责自己擅长的领域。一个安全审查智能体专注于代码安全漏洞检测，一个数据库迁移智能体专注于 SQL 脚本的正确性和向后兼容性，而一个 API 设计智能体则专注于 RESTful 规范和接口一致性。
智能体定义支持 YAML 和 JSON 两种格式。YAML 格式因其对多行文本（如系统提示词）的友好支持而被推荐使用。
智能体定义格式
智能体配置文件定义了一个智能体的完整行为规范。以下是完整的 YAML 格式说明：
# agents/my-agent.yaml
name: my-agent
display_name: 我的自定义智能体
description: 用于特定任务的专业智能体
model:
backend: claude # AI 后端：claude / codex / gemini
name: claude-opus-4-6 # 具体模型名称
temperature: 0.3 # 生成温度 (0.0 - 2.0)
top_p: 0.95 # 核采样参数 (0.0 - 1.0)
max_tokens: 8192 # 最大输出 token 数
stop_sequences: ["---END---"] # 停止序列（可选）
system_prompt: |
你是一位专业的 [角色描述]。
你的核心职责是 [职责说明]。
## 工作规范
1. [规范条目一]
2. [规范条目二]
## 输出格式
请始终按照以下格式输出结果：
[格式说明]
tools:
- file_read # 读取项目文件
- file_write # 写入/创建文件
- file_search # 搜索文件内容
- codebase_explore # 探索代码库结构
- shell_execute # 执行 shell 命令
- git_operations # Git 操作
constraints:
max_file_edits: 20 # 单次任务最大文件修改数
allowed_paths: ["src/", "tests/"] # 允许修改的路径前缀
forbidden_paths: [".env", "secrets/"] # 禁止访问的路径
require_explanation: true # 每次修改必须附带说明
metadata:
author: "团队名称"
version: "1.0.0"
tags: ["security", "review"]| 字段 | 必填 | 说明 |
|---|---|---|
name |
是 | 智能体唯一标识符，在工作流中引用 |
display_name |
否 | 显示名称，用于 UI 展示 |
model |
是 | 模型配置，指定后端和参数 |
system_prompt |
是 | 系统提示词，定义智能体的角色和行为 |
tools |
否 | 授予智能体的工具列表 |
constraints |
否 | 安全约束，限制智能体的操作范围 |
系统提示词工程
系统提示词是智能体定义中最关键的部分，它决定了智能体的专业能力边界和输出质量。编写高质量的系统提示词需要遵循以下原则：
结构化原则
一个有效的系统提示词应当包含四个层次：角色定义、职责范围、工作规范和输出格式。
- 角色定义：明确告诉模型它扮演的角色。使用"你是一位有 10 年经验的安全工程师"比"你帮忙做安全审查"效果更好。
- 职责范围：明确列出智能体应该做什么和不应该做什么。边界越清晰，输出越可靠。
- 工作规范：定义具体的工作流程和标准。例如，安全审查智能体应该列出它检查的安全漏洞类别清单。
- 输出格式：指定期望的输出结构。使用 Markdown、JSON 或特定模板可以大幅提升输出的可解析性和一致性。
领域知识注入
对于需要特定领域知识的智能体，可以在系统提示词中注入关键的领域规则和约束。
system_prompt: |
你是一位专业的 PostgreSQL 数据库架构师。
## 核心原则
- 所有表必须包含 id (BIGSERIAL), created_at, updated_at 字段
- 外键必须添加索引
- 使用 snake_case 命名约定
- 所有迁移脚本必须包含 UP 和 DOWN 操作
- 永远不要在迁移中使用 DROP COLUMN，使用标记废弃列
## OWASP SQL 注入防护
- 所有动态查询必须使用参数化语句
- 禁止字符串拼接构造 SQL
## 输出格式
对于每个变更，输出：
1. 迁移文件（SQL）
2. 回滚脚本（SQL）
3. 影响分析（Markdown）系统提示词的长度应当在 500 到 2000 token 之间。太短无法提供足够的上下文，太长会占用过多的上下文窗口空间并可能导致模型"遗忘"关键指令。
模型参数调优
不同类型的智能体需要不同的模型参数配置。以下是经过实践验证的参数推荐：
| 智能体类型 | temperature | top_p | max_tokens | 说明 |
|---|---|---|---|---|
| 代码实现 | 0.2 | 0.95 | 8192 | 低温度确保代码语法正确性 |
| 代码审查 | 0.1 | 0.90 | 4096 | 极低温度确保审查评判的一致性 |
| 架构设计 | 0.5 | 0.95 | 8192 | 适度温度允许创造性方案 |
| 需求分析 | 0.4 | 0.95 | 4096 | 平衡准确性和发散思维 |
| 安全审查 | 0.1 | 0.85 | 4096 | 高确定性，不遗漏漏洞 |
| 文档生成 | 0.6 | 0.95 | 8192 | 较高温度使文档更自然流畅 |
关于后端选择，不同的 AI 后端在不同任务上有各自优势。Claude 在推理和代码审查方面表现优异，Codex 在大规模代码生成方面有优势，Gemini 在多模态和长上下文场景中表现出色。你可以为不同的智能体指定不同的后端，充分发挥各自的优势。
工作流中的智能体角色
在工作流定义中，每个阶段（Phase）绑定一个智能体。智能体通过 agent 字段引用。阶段之间可以通过输入输出管道传递数据，实现智能体间的协作。
# workflows/full-review.yaml
name: full-review
description: 完整的代码审查工作流
phases:
- name: security-scan
agent: security-reviewer # 安全审查智能体
description: 扫描安全漏洞
timeout: 180
output:
- security_report
- name: quality-review
agent: code-reviewer # 代码质量审查智能体
description: 检查代码质量
depends_on: [security-scan]
input:
- security_report
timeout: 180
output:
- quality_report
- name: fix-issues
agent: implementer # 代码实现智能体
description: 修复发现的问题
depends_on: [quality-review]
input:
- security_report
- quality_report
timeout: 300
condition: "security_report.critical_count > 0 || quality_report.issues_count > 0"注意 condition 字段的使用：它允许根据前序阶段的输出动态决定是否执行当前阶段。在上面的例子中，只有当安全审查或质量审查发现问题时，才会触发修复阶段。
团队智能体协作模式
PinableAgents 支持三种智能体协作模式：
- 流水线模式（Pipeline）：智能体按顺序执行，每个智能体的输出作为下一个智能体的输入。适用于明确的阶段性任务，如"分析 → 设计 → 实现 → 审查"。
- 并行模式（Parallel）：多个智能体同时执行独立的子任务，所有子任务完成后合并结果。适用于可分解的独立任务，如同时进行安全审查和性能分析。
- 迭代模式（Iterative）：智能体之间形成反馈循环，一个智能体的输出触发另一个智能体的修正，直到满足退出条件。适用于需要多轮打磨的任务，如代码审查和修复循环。
# 并行模式示例
phases:
- name: security-scan
agent: security-reviewer
parallel_group: review # 同一 parallel_group 中的阶段并行执行
- name: performance-check
agent: perf-analyzer
parallel_group: review
- name: synthesize
agent: lead-reviewer
depends_on: [security-scan, performance-check] # 等待并行阶段完成跨团队共享智能体
自定义智能体配置可以打包到模块中跨团队共享。推荐的共享实践：
- 将智能体定义文件放在模块的
agents/目录下。 - 将提示词模板放在
prompts/目录下，支持变量替换以适应不同项目。 - 在
module.json中声明智能体列表，便于其他模块引用。 - 为每个智能体编写使用文档，说明其适用场景和限制。
实战：安全审查智能体
以下是一个完整的安全审查智能体定义。该智能体专注于检测 OWASP Top 10 安全漏洞。
# agents/security-reviewer.yaml
name: security-reviewer
display_name: 安全审查专家
description: 基于 OWASP Top 10 的代码安全审查
model:
backend: claude
name: claude-opus-4-6
temperature: 0.1
max_tokens: 4096
system_prompt: |
你是一位资深的应用安全工程师，专注于代码层面的安全审查。
## 审查清单（基于 OWASP Top 10 2025）
1. 注入漏洞：SQL 注入、命令注入、LDAP 注入
2. 身份认证缺陷：弱密码策略、会话管理不当
3. 敏感数据泄露：硬编码密钥、日志中的敏感信息
4. XML 外部实体：XXE 攻击向量
5. 访问控制缺陷：越权访问、IDOR
6. 安全配置错误：默认凭据、调试模式
7. 跨站脚本（XSS）：反射型、存储型、DOM 型
8. 不安全的反序列化
9. 使用含已知漏洞的组件
10. 日志和监控不足
## 输出格式
对每个发现的问题，输出：
- 严重性：Critical / High / Medium / Low
- 文件和行号
- 漏洞类型（OWASP 分类）
- 问题描述
- 修复建议（含代码示例）
tools:
- file_read
- file_search
- codebase_explore
constraints:
max_file_edits: 0
require_explanation: true实战：数据库迁移智能体
数据库迁移智能体专注于生成安全、可回滚的数据库变更脚本。
# agents/db-migrator.yaml
name: db-migrator
display_name: 数据库迁移专家
description: 生成安全的数据库迁移脚本
model:
backend: claude
name: claude-opus-4-6
temperature: 0.2
max_tokens: 8192
system_prompt: |
你是一位专业的数据库架构师，精通 PostgreSQL。
## 迁移规范
- 每个迁移文件命名格式：{timestamp}_{description}.sql
- 必须包含 UP（正向迁移）和 DOWN（回滚）两个部分
- 新增列时必须指定 DEFAULT 值
- 永远不要直接 DROP TABLE 或 DROP COLUMN
- 大表变更必须使用 CONCURRENTLY 选项
- 所有外键必须添加对应的索引
- 数据迁移必须是幂等的
## 安全检查
- 评估迁移对现有数据的影响
- 估算锁定时间，大表操作需要分批执行
- 确保迁移脚本可以在事务中安全执行
tools:
- file_read
- file_write
- shell_execute
constraints:
allowed_paths: ["migrations/", "database/", "db/"]
forbidden_paths: [".env", "config/production/"]实战：API 设计智能体
API 设计智能体专注于 RESTful API 的规范设计和接口一致性。
# agents/api-designer.yaml
name: api-designer
display_name: API 设计架构师
description: RESTful API 设计与规范审查
model:
backend: claude
name: claude-opus-4-6
temperature: 0.4
max_tokens: 8192
system_prompt: |
你是一位资深的 API 架构师，精通 RESTful 设计原则。
## 设计规范
- 遵循 REST 语义：GET 读取、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除
- URL 使用复数名词：/users, /orders（非 /user, /order）
- 嵌套资源不超过两层：/users/{id}/orders（非 /users/{id}/orders/{oid}/items）
- 分页使用 cursor-based pagination，响应包含 next_cursor 字段
- 错误响应遵循 RFC 7807 Problem Details 格式
- 所有响应包含 request_id 用于追踪
- 版本号放在 URL 前缀：/v1/users
## 输出内容
1. OpenAPI 3.0 规范文件（YAML）
2. 请求/响应示例
3. 错误码清单
4. 变更影响分析（如涉及现有 API 修改）
tools:
- file_read
- file_write
- file_search
- codebase_explore智能体测试与验证
创建智能体后，应当通过系统化的测试验证其行为符合预期。PinableAgents 提供了智能体测试框架，允许你定义测试用例并自动化执行。
# tests/security-reviewer.test.yaml
agent: security-reviewer
test_cases:
- name: 检测 SQL 注入
input:
files:
- path: "app.py"
content: |
def get_user(name):
query = f"SELECT * FROM users WHERE name = '{name}'"
return db.execute(query)
expect:
severity: "Critical"
category: "injection"
contains: "参数化查询"
- name: 通过安全代码
input:
files:
- path: "app.py"
content: |
def get_user(name):
query = "SELECT * FROM users WHERE name = %s"
return db.execute(query, (name,))
expect:
issues_count: 0# 运行智能体测试
pinable-agents agent test security-reviewer
# 输出：
# 测试 security-reviewer (2 个用例)
# [通过] 检测 SQL 注入 (2.3s)
# [通过] 通过安全代码 (1.8s)
# 全部通过 (2/2)建议在修改智能体的系统提示词后始终运行测试套件，确保修改没有引入回归问题。即使是微小的提示词变更也可能显著影响输出行为。
性能监控
PinableAgents 为每个智能体收集运行时指标，帮助你评估和优化智能体的表现。
| 指标名称 | 说明 | 优化方向 |
|---|---|---|
| 平均响应时间 | 从发送请求到收到完整响应的时间 | 减少 max_tokens 或优化提示词 |
| Token 使用量 | 每次调用的输入/输出 token 数 | 精简系统提示词，减少冗余上下文 |
| 任务成功率 | 验证通过的任务占总任务的比例 | 改进系统提示词的精确度 |
| 重试率 | 需要重试的请求占总请求的比例 | 检查超时设置和网络稳定性 |
| 成本估算 | 基于 token 用量计算的 API 费用 | 选择性价比更高的模型或后端 |
# 查看智能体的性能指标
pinable-agents agent stats security-reviewer --period 7d
# 输出：
# 智能体：security-reviewer
# 时间范围：最近 7 天
# 调用次数：47
# 平均响应时间：3.2s
# 平均输入 tokens：2,340
# 平均输出 tokens：1,890
# 任务成功率：93.6%
# 重试率：4.3%
# 估算费用：$12.40通过持续监控这些指标，你可以识别表现不佳的智能体并针对性优化。常见的优化手段包括：精简系统提示词以降低 token 使用量、调整温度参数以提高成功率、以及切换到更适合的模型版本。当成功率低于 85% 时，建议优先检查系统提示词是否足够清晰和具体。