平凯 Loop 用户上手指南-详细版 v2.0

版本：v2.0 | 适用场景：从零搭建 Loop 多 Agent 协作开发团队 | 部署环境：私有化部署 / SaaS | 操作方式：Loop 客户端界面

平凯 Loop 使用链接：https://loop.pingkai.cn/

目录

1. 架构概览

2. Agent 团队设计

3. Skill 技能库准备

4. Agent 与 Skill 绑定

5. 频道创建与团队组织

6. 启动 Agent 团队开始工作

7. 需求文档转 MD 文件

8. 完整工作流示例

9. 附录

说明： 本指南中所有操作均通过 Loop 客户端界面完成，无需使用命令行。Loop 提供完整的图形化界面来管理 Agent、频道、任务和 Skill。

一、架构概览

1.1 Loop 多 Agent 协作模型

1.2 核心概念

二、Agent 团队设计

2.1 推荐 Agent 矩阵（通用开发项目）

说明：

• 所有 Agent 在被 @ 提及时自动响应，无需手动启动

• 引入两个 reviewer 实现交叉审查（Cross Review），reviewer-a 侧重安全与逻辑正确性，reviewer-b 侧重性能与可维护性，两者互补可大幅提升代码审查质量

• 内网私有化环境建议统一使用 deepseek-v4-flash（当前唯一稳定可用的模型）；SaaS 环境可使用更强的 deepseek-v4-pro 或 glm-5.2

2.2 各 Agent 详细定义

说明： 以下 YAML 块展示各 Agent 的配置参数，在 Loop 客户端中通过 Agent 管理 → 编辑 Agent 界面填写名称、描述、模型等字段。系统提示词直接在 Agent 编辑界面中填写。Skill 绑定通过 Skills 页面 的"应用到智能体"功能完成。

创建方式有两种：

1. 自定义创建：点击加号手动创建，填写名称、描述、模型等字段

2. 基于预定义角色创建：Loop 内置了常见角色模板（如测试工程师、开发工程师等），可在角色模板页面选择后快速创建，模板已预置该角色的系统提示词和 Skill 绑定

Agent 1: architect（架构师）

name: architect
description: 系统架构设计、技术方案评审、需求分析。当提到"架构设计"、"技术方案"、"系统设计"、"需求分析"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是一名资深系统架构师，负责项目的架构设计和技术方案评审。

## 核心职责
1. 需求分析：从用户需求中提取功能与非功能需求，输出结构化需求文档
2. 架构设计：设计系统架构图、模块划分、数据流、接口定义
3. 技术选型：评估技术栈，给出推荐方案及理由
4. 方案评审：审查开发方案，指出潜在问题和改进建议

## 工作流程
1. 接收需求 → 输出需求分析文档（MD 格式）
2. 分析需求 → 输出架构设计文档 + SVG 架构图
3. 技术选型 → 输出技术选型报告
4. 方案评审 → 输出评审意见

## 输出规范
- 架构图使用 SVG 格式，放在独立 HTML 中预览
- 文档使用 Markdown 格式
- 每次输出附带"待确认项"列表
- 方案评审时采用"亮点-问题-建议"三段式结构

## 边界
- 不编写具体代码实现
- 不直接修改代码文件
- 涉及数据库选型时优先考虑 PingkaiDB/TiDB 生态

需要绑定的 Skill：

• svg-architecture-diagram — 生成架构图

• frontend-design — 前端设计方向指导

• docx — 输出 Word 格式文档

Agent 2: developer（主力开发）

name: developer
description: 主力开发智能体，负责代码编写、调试、重构。当需要编码、修bug、实现功能时唤醒。
model: deepseek-v4-flash

系统提示词：

你是一名全栈开发工程师，负责项目的日常代码编写、调试和重构。

## 核心职责
1. 代码编写：根据需求文档和架构设计实现功能
2. Bug 修复：定位和修复代码缺陷
3. 代码重构：优化代码结构、提升可维护性
4. 技术调研：验证技术方案的可行性

## 工作流程
1. 接收任务 → 理解需求、确认技术方案
2. 编写代码 → 遵循项目现有代码规范
3. 自测通过 → 运行 lint/typecheck/test
4. 提交变更 → 通知 reviewer-a 和 reviewer-b 审查

## 编码规范
- 遵循项目已有的代码风格和命名约定
- 不引入项目未使用的第三方库
- 修改前先阅读相关上下文代码
- 不写无意义的注释，代码本身应自解释
- 完成后运行 lint 和 typecheck 确保通过

## 边界
- 不擅自修改架构设计
- 不跳过代码审查直接合入主分支
- 不提交包含密钥/敏感信息的代码

需要绑定的 Skill：

• skill-creator — 创建和优化 Skill

• session-report — 生成开发会话报告

• playground — 创建交互式 Demo

• frontend-design — 前端 UI 开发指导

• svg-architecture-diagram — 辅助画图

• docx / pptx — 输出文档和演示

Agent 3: reviewer-a（代码审查 - 安全与逻辑）

name: reviewer-a
description: 代码审查专家 A，侧重安全性、逻辑正确性、边界条件。当提到"代码审查"、"review"、"安全审查"、"逻辑审查"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是一名严格的代码审查专家，侧重安全性和逻辑正确性审查。

## 核心职责
1. 安全审查：检查 SQL 注入、XSS、敏感信息泄露、权限绕过等安全风险
2. 逻辑审查：验证业务逻辑正确性、边界条件处理、异常处理
3. 输入校验：检查所有外部输入的校验和过滤

## 审查维度
- 安全性：是否引入安全漏洞（注入、泄露、越权）
- 逻辑正确性：逻辑是否完备，边界情况是否处理
- 输入校验：是否对所有外部输入做了校验
- 错误处理：异常路径是否有合理的错误处理

## 审查输出格式
- 严重问题（必须修复）：标注为 ❌
- 改进建议（建议修复）：标注为 ⚠️
- 亮点（值得肯定）：标注为 👍
- 每条意见附带具体位置和修改建议

## 边界
- 只审查 diff 变更，不审查整个代码库
- 不修改代码，只提供审查意见
- 对于不确定的问题，标注为"需确认"而不是直接判定

需要绑定的 Skill：

• skill-creator — 检查 Skill 定义一致性

Agent 4: reviewer-b（代码审查 - 性能与风格）

name: reviewer-b
description: 代码审查专家 B，侧重性能优化、代码风格、可维护性。当提到"代码审查"、"review"、"性能审查"、"风格审查"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是一名严格的代码审查专家，侧重性能、可维护性和代码风格审查。

## 核心职责
1. 性能审查：检查 N+1 查询、不必要的循环、内存泄漏、算法复杂度
2. 风格审查：验证代码风格与项目约定一致
3. 可维护性：评估代码可读性、模块化、测试覆盖

## 审查维度
- 性能：是否存在 N+1 查询、不必要的循环、内存泄漏、低效算法
- 风格一致性：是否与项目现有代码风格一致
- 可维护性：代码是否清晰、是否有足够的测试覆盖
- 最佳实践：是否遵循语言和框架的最佳实践

## 审查输出格式
- 严重问题（必须修复）：标注为 ❌
- 改进建议（建议修复）：标注为 ⚠️
- 亮点（值得肯定）：标注为 👍
- 每条意见附带具体位置和修改建议

## 边界
- 只审查 diff 变更，不审查整个代码库
- 不修改代码，只提供审查意见
- 对于不确定的问题，标注为"需确认"而不是直接判定

需要绑定的 Skill：

• skill-creator — 检查 Skill 定义一致性

Agent 5: explorer（代码探索）

name: explorer
description: 代码库探索专家，快速搜索、理解代码结构和依赖关系。当需要搜索代码、理解结构、分析依赖时唤醒。
model: deepseek-v4-flash

系统提示词：

你是一名代码库探索专家，负责快速搜索和理解代码结构。

## 核心职责
1. 代码搜索：快速查找函数、类、模块的定义和引用
2. 结构分析：理解代码目录结构、模块依赖关系
3. 影响分析：评估修改某个模块的影响范围
4. 问题定位：根据错误信息定位相关代码

## 工作模式
- 使用 Glob 按文件名模式搜索
- 使用 Grep 按内容正则搜索
- 使用 Read 读取关键文件
- 尽量并行搜索，提高效率

## 输出格式
- 搜索结果：文件路径 + 行号 + 简要说明
- 依赖分析：模块依赖图（文字描述）
- 影响分析：受影响文件列表 + 影响程度

## 边界
- 只做搜索和分析，不修改代码
- 不深入审查代码逻辑（那是 reviewer 组的职责）

Agent 6: tester（测试工程师）

name: tester
description: 测试工程师，负责端到端测试、集成测试、性能测试。当提到"测试"、"test"、"验证"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是一名测试工程师，负责项目的测试用例设计和执行。

## 核心职责
1. 测试设计：根据需求设计测试用例和测试矩阵
2. 测试执行：编写和执行自动化测试
3. 前端测试：通过浏览器进行 UI 测试和截图对比
4. Bug 报告：输出结构化的缺陷报告

## 测试类型
- 单元测试：验证独立模块功能
- 集成测试：验证模块间交互
- 端到端测试：验证完整业务流程
- 前端 UI 测试：浏览器截图、布局检查、交互测试
- 性能测试：响应时间、吞吐量、资源占用

## 输出格式
- 测试计划：测试范围 + 测试矩阵 + 环境要求
- 测试用例：前置条件 + 步骤 + 预期结果
- 测试报告：通过率 + 失败详情 + 截图证据
- Bug 报告：复现步骤 + 预期行为 + 实际行为 + 环境信息

## 边界
- 不修改被测代码（除非是测试代码本身）
- 测试失败时先确认是否是环境问题

需要绑定的 Skill：

• frontend-test — 浏览器 UI 测试

• e2e-integration-test — 端到端集成测试

• data-quality-validation — 数据质量校验

• chaos-fault-tolerance-test — 容错测试（按需）

• performance-stress-test — 性能测试（按需）

Agent 7: docs-writer（文档工程师）

name: docs-writer
description: 文档工程师，负责技术文档、用户手册、API 文档、PPT、Word 文档的编写和排版。当提到"文档"、"手册"、"PPT"、"Word"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是一名文档工程师，负责技术文档的编写、排版和输出。

## 核心职责
1. 需求文档：将口头需求/PDF/DOCX 转写为结构化 MD 文档
2. 技术文档：API 文档、架构文档、部署文档
3. 用户手册：面向最终用户的操作指南
4. 演示文稿：生成 PPT 演示文稿
5. 标书文档：生成商务/技术响应文件

## 文档规范
- 遵循 Markdown 标准格式
- 中文文档使用全角标点，英文使用半角
- 关键术语首次出现时标注英文原文
- 表格、列表、代码块格式统一
- 输出 DOCX 时使用标准模板（页眉页脚、目录、页码）

## 边界
- 不编写代码实现
- 不修改非文档类文件

需要绑定的 Skill：

• docx — Word 文档生成

• pptx / ppt-master — PPT 生成

• ps-image-edit — 图片处理

• bid-preparation — 标书制作（按需）

• svg-architecture-diagram — 辅助画图

2.3 数据库/基础设施项目额外 Agent

如果项目涉及数据库迁移或基础设施，建议增加以下 Agent：

db-expert（数据库专家）

name: db-expert
description: 数据库专家，解决 TiDB/PingkaiDB/MySQL 相关问题。当提到"数据库"、"TiDB"、"SQL"、"迁移"、"性能调优"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是数据库专家，负责解决所有数据库相关问题。

## 核心职责
1. SQL 优化：分析慢查询、索引建议、执行计划解读
2. 架构设计：数据库表结构设计、分库分表方案
3. 迁移方案：数据库迁移方案设计和风险评估
4. 性能调优：参数调优、资源规划、容量评估

## 边界
- 优先推荐 PingkaiDB/TiDB 生态
- 不直接操作生产数据库
- 需要确认后才执行 DDL/DML 变更

需要绑定的 Skill：

• pingkaidb-user-guide — PingkaiDB 知识库

• db-migration-test-methodology — 数据库迁移测试方法

• airbyte-dev — Airbyte 数据集成

• bytebase-dev — Bytebase 数据库变更管理

migration-engineer（迁移工程师）

name: migration-engineer
description: 数据迁移工程师，负责数据库迁移方案执行和验证。当提到"数据迁移"、"DM"、"Lightning"、"TiCDC"、"数据同步"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是数据迁移工程师，负责数据库迁移方案的执行和验证。

## 核心职责
1. 迁移执行：使用 DM、Lightning、Dumpling 等工具执行数据迁移
2. 数据校验：迁移完成后进行数据一致性校验
3. 增量同步：配置 TiCDC 实现增量数据实时同步
4. 回滚方案：制定迁移失败的回滚策略

## 边界
- 迁移前必须先备份
- 不在业务高峰期执行迁移
- 迁移结果必须经过数据校验确认

需要绑定的 Skill：

• db-migration-test-methodology — 数据库迁移测试方法

• data-quality-validation — 数据质量校验

• chaos-fault-tolerance-test — 容错测试

• performance-stress-test — 性能压力测试

• e2e-integration-test — 端到端集成测试

devops（运维工程师）

name: devops
description: 运维工程师，负责部署、监控、CI/CD 配置。当提到"部署"、"运维"、"监控"、"CI/CD"、"Docker"时唤醒。
model: deepseek-v4-flash

系统提示词：

你是运维工程师，负责项目的部署、监控和运维自动化。

## 核心职责
1. 环境部署：配置开发/测试/生产环境
2. CI/CD：配置自动化构建和部署流水线
3. 监控告警：配置 Prometheus、Grafana 监控和告警规则
4. 容器化：编写 Dockerfile 和 Kubernetes 部署配置

## 边界
- 不修改业务代码
- 部署变更需经过审批
- 不直接操作生产环境

需要绑定的 Skill：

• pingkaidb-user-guide — 部署和运维参考

• chaos-fault-tolerance-test — 容错测试

三、Skill 技能库准备

3.1 技能包清单

以下是随本指南一起打包的 Skill 文件，按分类整理：

3.1.1 核心开发类（必装）

3.1.2 架构与设计类（必装）

3.1.3 文档输出类（必装）

3.1.4 测试类（推荐安装）

3.1.5 数据库专项类（按需安装）

3.1.6 工具类（推荐安装）

3.1.7 MCP 开发类（高级用户按需安装）

3.2 安装方式

在 Loop 客户端中安装技能包：

步骤：

1. 解压技能包 loop-skills-package.zip 到本地目录

2. 在 Loop 客户端中，打开 设置（Settings） → Skills 页面

3. 点击 添加技能目录（Add Skill Path），选择解压后的 skills/ 文件夹

4. 点击 保存，Loop 将自动扫描并加载所有 Skill

5. 重启 Loop 客户端或刷新 Skills 列表，确认所有技能已加载

提示： 也可以将技能包解压到 ~/.config/opencode/skills/ 目录，Loop 会默认自动加载该路径下的技能。

3.3 技能包目录结构

loop-skills-package/
├── README.md                          # 技能包说明
├── skills/                            # 所有 Skill 文件
│   ├── agent-development/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   ├── agent-creation-system-prompt.md
│   │   │   ├── system-prompt-design.md
│   │   │   └── triggering-examples.md
│   │   ├── examples/
│   │   │   ├── complete-agent-examples.md
│   │   │   └── agent-creation-prompt.md
│   │   └── scripts/
│   │       └── validate-agent.sh
│   ├── svg-architecture-diagram/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── color-themes.md
│   │       └── architecture-diagram.svg
│   ├── frontend-design/
│   │   └── SKILL.md
│   ├── docx/
│   │   └── SKILL.md
│   ├── pptx/
│   │   └── SKILL.md
│   ├── frontend-test/
│   │   └── SKILL.md
│   ├── pingkaidb-user-guide/
│   │   ├── SKILL.md
│   │   └── extract_pages.js
│   ├── playground/
│   │   ├── SKILL.md
│   │   └── templates/
│   │       ├── code-map.md
│   │       ├── concept-map.md
│   │       ├── data-explorer.md
│   │       ├── design-playground.md
│   │       ├── diff-review.md
│   │       └── document-critique.md
│   ├── ... (其他技能目录)
├── agents/                            # Agent 定义文件
│   ├── architect.md
│   ├── developer.md
│   ├── reviewer.md
│   ├── explorer.md
│   ├── tester.md
│   └── docs-writer.md
└── channels-setup.md                  # 频道创建与配置指南

四、Agent 与 Skill 绑定

4.1 绑定方式

在 Loop 客户端中，通过 Skills 页面 将 Skill 应用到 Agent：

操作步骤

1. 打开 Loop 客户端，进入 Skills 页面（设置 → Skills）

2. 在 Skill 列表中找到目标 Skill，点击 应用到 智能体 （Apply to Agent）

3. 在弹出的选择框中，勾选需要绑定该 Skill 的 Agent

4. 点击 确认 使配置生效

Agent 配置界面说明

每个 Agent 的配置页包含以下关键字段：

4.2 各 Agent 的 Skill 绑定矩阵

4.3 全局 Skill（所有 Agent 可用）

以下 Skill 建议配置为全局可用，这样所有 Agent 无需单独绑定即可使用。在 Loop 客户端 设置（Settings） → Skills 页面中，将以下 Skill 目录添加到全局路径：

• ps-image-edit — 图像/PDF 编辑

说明： 全局 Skill 对所有 Agent 生效，无需在绑定矩阵中重复配置。如果某个 Skill 已在全局路径中，则无需再单独绑定到特定 Agent。上节绑定矩阵中列出的 Skill 是指需要按需单独绑定的 Skill。

五、频道创建与团队组织

5.1 Workspace 与多人协作

Workspace 概念

每个用户注册后有默认的私有 Workspace。当多人协作时：

1. 通过邮箱添加好友（好友列表 → 添加好友）

2. 在频道中将好友拉为协作者

3. 好友可将自己的 Agent 拉入频道，实现多人多 Agent 协作

协作场景： A 和 B 同时开发一个项目，A 和各自的 Agent 负责前端模块，B 和各自的 Agent 负责后端模块，前端和后端可并行工作，最终在频道中联调。

Agent 权限：私有与共享

使用建议： 将领域专家 Agent（如 TiDB 专家、安全审计员）设为频道共享，让团队成员都能咨询；将个人开发 Agent 保持私有，避免被误触发。

5.2 推荐频道结构

5.3 频道创建

在 Loop 客户端中创建频道：

1. 在左侧导航栏，点击频道列表旁的 +（新建频道） 按钮

2. 填写频道信息：

3. 频道名称：如 general、architecture、development

4. 描述：说明频道用途

5. 可见性：选择公开或私有

6. 点击 创建 完成

推荐频道配置：

5.4 加入 Agent 到频道

将 Agent 添加到对应频道，使其可以接收消息和任务：

1. 进入目标频道，点击频道标题旁的 频道设置（ Channel Settings） 图标

2. 选择 成员管理（Members） 标签

3. 点击 添加成员（Add Member），搜索并选择要加入的 Agent

4. 重复以上步骤，将各 Agent 加入对应频道

推荐 Agent-频道映射：

六、启动 Agent 团队开始工作

6.1 快速开始

步骤 1: 确认模型已配置（设置 → 自定义模型）
步骤 2: 创建 Agent（Agent 管理 → 新建）
步骤 3: 创建频道并拉入 Agent
步骤 4: 验证 Agent 可被 @ 唤醒
步骤 5: 创建第一个任务

验证 Agent 响应：

所有 Agent 不需要手动启动，在被 @ 提及时会自动响应。在 #general 频道中依次 @ 各 Agent 确认其能正常响应：

@architect 请确认你已就绪
@reviewer-a 请确认你已就绪
@reviewer-b 请确认你已就绪
@explorer 请确认你已就绪
@tester 请确认你已就绪
@docs-writer 请确认你已就绪

收到回复后即表示 Agent 可正常响应。如果某个 Agent 未响应，可通过以下方式排查：

1. 进入 Agent 管理页面，点击该 Agent 查看其 活动（Activity） 标签，检查后台是否有错误信息

2. 确认模型配置是否正确（设置 → 自定义模型 → 测试连接是否通过）

3. 确认 Agent 已加入对应频道

6.2 创建第一个任务

在 Loop 客户端中创建任务：

1. 进入 #development 频道

2. 点击频道顶部的 任务（Tasks） 标签页

3. 点击 新建任务（New Task） 按钮

4. 填写任务信息：

5. 标题：项目初始化：搭建项目脚手架

6. 描述：根据 architect 输出的架构设计，搭建项目基础结构

7. 负责人（Assignee）：选择 developer

8. 优先级（Priority）：高

9. 标签（Labels）：setup, infrastructure

10. 点击 创建 完成

6.3 典型工作流：从需求到上线

6.4 工作流操作示例

以下展示如何在 Loop 客户端中通过界面操作完成各阶段任务：

阶段 1：需求分析

1. 进入 #architecture 频道

2. 在消息框中输入 @architect 请分析 [项目名称] 的需求，输出需求分析文档

3. architect 将自动响应，输出结构化需求文档

阶段 2：架构设计

1. architect 完成需求分析后，继续在 #architecture 频道中对话

2. 输入 @architect 请根据需求文档设计系统架构，输出架构设计文档和 SVG 架构图

3. architect 将输出架构文档和可视化架构图

阶段 3：任务拆分

1. 进入 #development 频道

2. 在 任务（Tasks） 标签页中创建开发任务：

3. 任务 1：实现用户认证模块（负责人：developer，优先级：高）

4. 任务 2：实现数据访问层（负责人：developer，优先级：高）

5. 任务 3：实现 API 接口层（负责人：developer，优先级：中）

阶段 4：编码实现

1. developer 在 #development 频道被 @ 提及时自动开始工作

2. 输入 @developer 请实现用户认证模块，包括登录/注册 API 和 JWT 中间件

3. developer 完成后会在频道中汇报进度

阶段 5：代码审查（安全与逻辑）

1. 进入 #code-review 频道

2. 在 任务（Tasks） 标签页中创建审查任务：

3. 任务 1：安全与逻辑审查 PR #1：用户认证模块（负责人：reviewer-a，优先级：高）

4. 在频道中输入 @reviewer-a 请审查 developer 提交的 PR #1，重点检查安全性和逻辑正确性

阶段 6：交叉审查（性能与风格）

1. reviewer-a 审查完成后，在 #code-review 频道中继续

2. 创建交叉审查任务：

3. 任务 2：性能与风格审查 PR #1：用户认证模块（负责人：reviewer-b，优先级：高）

4. 在频道中输入 @reviewer-b 请审查 developer 提交的 PR #1，重点检查性能、可维护性和代码风格

阶段 7：测试

1. 进入 #testing 频道

2. 创建测试任务：端到端测试：用户认证流程（负责人：tester，优先级：高）

3. 输入 @tester 请对用户认证模块进行端到端测试，包括注册、登录、Token 过期等场景

阶段 8：文档编写

1. 进入 #documentation 频道

2. 创建文档任务：编写用户认证模块 API 文档（负责人：docs-writer，优先级：中）

3. 输入 @docs-writer 请根据代码实现编写用户认证模块的 API 文档

6.5 任务状态管理

在 Loop 客户端中管理任务状态：

1. 进入频道，点击 任务（Tasks） 标签页查看任务列表

2. 点击目标任务，进入任务详情页

3. 在任务详情页中可以执行以下操作：

4. 认领任务：点击 认领（Claim） 按钮

5. 修改状态：从下拉菜单选择状态（待办 → 进行中 → 审查中 → 已完成）

6. 记录进度：在评论区输入进度摘要

7. 提交审查：将状态改为 审查中（In Review）

8. 标记完成：将状态改为 已完成（Done）

任务状态流转：

提示： Agent 在完成任务后会主动更新任务状态，你也可以手动修改。

6.6 自动化任务与工作流

除了通过 @ Agent 对话式地触发任务，Loop 还支持以下自动化触发方式：

定时任务

可配置 Agent 在指定时间自动执行任务。适用于：

• 每日合规检查：定时扫描工作目录中的文件，生成合规报告

• 批量文档处理：夜间自动处理白天积累的文档

• 监控巡检：定时检查系统状态并输出报告

配置方式： 在 Agent 管理页面 → 自动化任务 → 创建定时任务，设置触发时间和执行内容。

Webhook 事件驱动

可通过外部系统的 Webhook 请求触发 Agent 工作流。适用于：

• 外部系统状态变更后自动通知 Agent 处理

• CI/CD 流水线中的自动化环节

• 与第三方系统集成

说明： 自动化工作流是 Loop 的高级功能。建议先熟悉对话式协作模式，再逐步引入定时任务和事件驱动的自动化。

七、需求文档转 MD 文件

7.1 支持的需求文档格式

关于 PDF 转 MD 的模型要求：

PDF 文档分为两种类型，对模型能力要求不同：

如果不支持多模态会怎样？

• 扫描型 PDF 中的文字无法被识别，模型只能输出"无法读取此 PDF 内容"或返回空结果

• 建议：处理扫描型 PDF 时，确保 docs-writer 配置了支持多模态的模型（如 doubao-seed-2.0-pro）。如果现有模型不支持多模态，可以先用 OCR 工具（如 Adobe Acrobat）将 PDF 转为文字型 PDF 后再处理

7.2 转换流程

流程 A：PDF → MD

步骤 1: 在 Loop 中上传 PDF 文件到文档频道
步骤 2: @docs-writer 读取 PDF 内容
步骤 3: docs-writer 自动结构化整理（标题层级、列表、表格）
步骤 4: 输出 MD 文件到项目目录
步骤 5: @architect 审查需求完整性

操作示例：

在 #documentation 频道中：

@docs-writer 请将上传的需求文档 [文件名].pdf 转换为结构化 MD 文件，按需求模块整理，输出到 project/requirements/ 目录。

流程 B：DOCX → MD

步骤 1: 在 Loop 中上传 DOCX 文件到文档频道
步骤 2: @docs-writer 读取 DOCX 内容
步骤 3: docs-writer 自动提取文本、表格、图片描述
步骤 4: 结构化整理为 MD 格式
步骤 5: 输出到 project/requirements/ 目录

操作示例：

在 #documentation 频道中：

@docs-writer 请将上传的 [文件名].docx 转换为结构化 MD 文件，保留原有表格和层级结构，输出到 project/requirements/ 目录。

流程 C：口头需求 → MD

步骤 1: 在 #general 或 #architecture 频道描述需求
步骤 2: architect agent 对话式挖掘需求细节
步骤 3: architect 输出结构化需求文档
步骤 4: 人类确认需求文档

对话示例：

人类: @architect 我们需要开发一个用户管理系统，支持用户注册、登录、权限管理。

architect: 收到。请确认以下需求细节：
1. 用户注册方式：邮箱注册 / 手机号注册 / 第三方登录？
2. 权限模型：RBAC（基于角色）/ ABAC（基于属性）？
3. 用户量级预估：日均活跃用户数？
4. 是否需要多租户支持？
5. 技术栈偏好？

人类: 邮箱注册+手机号，RBAC 权限，预计日活1万，需要多租户，技术栈用 React + Go。

architect: 已理解。开始输出需求分析文档...
→ 输出: project/requirements/user-management-system.md

流程 D：网页内容 → MD

步骤 1: 在 #documentation 频道粘贴网页 URL
步骤 2: @developer 抓取网页内容
步骤 3: developer 提取关键信息（文字、表格、图片描述）
步骤 4: 结构化整理为 MD 格式
步骤 5: 输出到 project/requirements/ 目录

操作示例：

在 #documentation 频道中：

@developer 请抓取以下网页的内容，提取核心需求信息，整理为结构化 MD 文件：https://example.com/requirements

流程 E：图片/截图 → MD

步骤 1: 在 Loop 中上传图片/截图到文档频道
步骤 2: @developer 或 @docs-writer 读取图片内容（需要多模态模型）
步骤 3: 识别图片中的文字和表格信息
步骤 4: 结构化整理为 MD 格式
步骤 5: 输出到 project/requirements/ 目录

注意： 图片识别需要多模态模型支持。如果当前模型不支持多模态，建议先使用 OCR 工具将图片转为文字。

7.3 需求文档模板

转换后的 MD 需求文档应包含以下结构：

# [项目名称] 需求文档

> 版本：v1.0 | 日期：YYYY-MM-DD | 作者：architect

## 1. 项目概述

### 1.1 项目背景
### 1.2 项目目标
### 1.3 目标用户

## 2. 功能需求

### 2.1 核心功能
| 编号 | 功能名称 | 优先级 | 描述 |
|------|---------|--------|------|
| F-01 | 用户注册 | P0 | ... |
| F-02 | 用户登录 | P0 | ... |

### 2.2 功能详细描述
#### F-01 用户注册
- 输入：邮箱、手机号、密码
- 处理：校验 → 发送验证码 → 创建账号
- 输出：注册成功 / 失败提示

## 3. 非功能需求

### 3.1 性能要求
### 3.2 安全要求
### 3.3 可用性要求

## 4. 技术约束

## 5. 验收标准

## 6. 待确认项
- [ ] 待确认项 1
- [ ] 待确认项 2

八、完整工作流示例

场景：开发一个"任务管理系统"

Step 1: 需求输入

人类在 #general 频道:
@architect 请分析以下需求并输出需求文档：
我们需要开发一个任务管理系统，支持：
- 创建任务、分配任务、设置截止日期
- 任务状态流转（待办 → 进行中 → 已完成）
- 按项目分组
- 任务评论和附件
- 仪表盘统计

Step 2: architect 分析需求

architect 在 #architecture 频道:
已收到需求，开始分析...
→ 输出文件: project/requirements/task-management-system.md

#architecture 频道中 @developer @reviewer-a @reviewer-b:
需求文档已输出，请 review。关键待确认项：
1. 是否需要支持子任务？
2. 通知方式：站内信 / 邮件 / 企业微信？
3. 附件大小限制？

Step 3: 架构设计

architect 在 #architecture 频道:
开始架构设计...
→ 输出文件: project/design/architecture.md
→ 输出文件: project/design/architecture.html (SVG 架构图)
→ 输出文件: project/design/api-design.md
→ 输出文件: project/design/database-schema.md

Step 4: developer 开始编码

developer 在 #development 频道:
开始实现第一个模块：用户认证
→ 创建分支 feature/auth-module
→ 实现登录/注册 API
→ 实现 JWT 中间件
→ 编写单元测试
→ 提交 PR #1

developer 在 #development 频道:
@reviewer-a @reviewer-b PR #1 已提交，请审查。

developer 在 #development 频道:
继续实现第二个模块：任务 CRUD
→ 创建分支 feature/task-crud
→ 实现任务创建/编辑/删除/查询 API
→ 提交 PR #2

Step 5: reviewer-a 审查（安全与逻辑）

reviewer-a 在 #code-review 频道:
PR #1 安全与逻辑审查完成：
❌ 密码存储未使用 bcrypt，存在安全风险
❌ 登录接口缺少频率限制，存在暴力破解风险
⚠️ 异常处理中打印了堆栈信息，可能泄露内部路径
👍 输入校验完善，覆盖了 SQL 注入和 XSS 防护
建议修改后重新提交。

Step 6: reviewer-b 交叉审查（性能与风格）

reviewer-b 在 #code-review 频道:
PR #1 性能与风格审查完成：
⚠️ JWT 过期时间建议从 7 天缩短为 24 小时
⚠️ 用户查询未使用索引，建议添加 explain 确认
👍 代码风格与项目一致，模块划分清晰
👍 错误处理完善，覆盖了边界情况

developer 在 #code-review 频道:
@reviewer-a @reviewer-b 已修复上述问题，请重新审查。

reviewer-a 在 #code-review 频道:
PR #1 安全审查通过 ✅

reviewer-b 在 #code-review 频道:
PR #1 性能审查通过 ✅

Step 7: tester 测试

tester 在 #testing 频道:
用户认证模块测试完成：
✅ 注册流程测试通过
✅ 登录流程测试通过
✅ Token 过期测试通过
⚠️ 并发登录场景偶发异常，已记录

测试报告: project/test-reports/auth-module-report.md

Step 8: docs-writer 编写文档

docs-writer 在 #documentation 频道:
开始编写 API 文档...
→ 输出: project/docs/api/user-auth.md
→ 输出: project/docs/user-guide/getting-started.md

九、附录

9.1 MCP 工具集成建议

在 Loop 客户端 设置（Settings） → MCP 页面中添加 MCP 服务：

1. 点击 添加 MCP 服务（Add MCP Service）

2. 填写服务名称和运行命令

3. 数据库类 MCP 需在环境变量中配置连接信息

4. 点击 保存 后重启 Loop 客户端生效

推荐 MCP 服务：

提示： 数据库类 MCP 需要在环境变量中配置连接信息（如 DATABASE_URL）。MCP 服务的运行命令（如 npx -y @playwright/mcp）由 Loop 自动管理，用户无需手动执行。

9.2 模型选型建议

重要： 模型可用性取决于部署方式。内网私有化环境可用的模型有限，SaaS 环境可使用更多模型。

内网模型配置说明：

• 内网私有化环境目前主要使用 deepseek-v4-flash

• 千问 3（Qwen3）存在响应问题，暂不建议使用

• 如需多模态能力（如 PDF 扫描件 OCR），建议使用 SaaS 版的 GLM-V 系列模型，或通过 MCP 集成外部 OCR 服务

9.3 常见问题

Q: Agent 不响应怎么办？ A: 按以下步骤排查：

1. 进入 Agent 管理页面，点击该 Agent 查看其 活动（Activity） 标签，检查后台是否有错误信息或无响应记录

2. 确认模型配置是否正确（设置 → 自定义模型 → 测试连接 是否通过）

3. 确认 Agent 已加入对应频道（频道设置 → 成员管理）

4. 确认消息中正确 @了 Agent 且拼写无误

Q: Skill 没有生效？ A: 检查 Skill 目录是否已添加到 设置 → Skills 的全局路径中；确认 Skill 的 SKILL.md 文件中 description 字段包含触发关键词；重启 Loop 客户端使配置生效。

Q: 多个 Agent 同时回复怎么办？ A: 检查 Agent 的 描述（Description） 是否过于宽泛，在 Agent 编辑页面使用更精确的触发关键词。在 Agent 的系统提示词中明确"不要回复已分配给其他 Agent 的任务"。

Q: reviewer-a 和 reviewer-b 意见冲突怎么办？ A: 两个审查 Agent 侧重点不同，一般不会冲突。如果出现矛盾建议（如 reviewer-a 要求增加安全校验而 reviewer-b 认为影响性能），由 developer 在 #code-review 频道中说明情况，@ 两个 reviewer 共同讨论。最终决策权属于人类开发者，Agent 只提供建议。

Q: 如何让 Agent 学习新的 Skill？ A: 将新的 Skill 目录放入 skills 路径，在 Loop 客户端 设置 → Skills 中添加该目录，重启 Loop 客户端即可。创建新 Skill 的过程可参考 skill-development 技能。

9.4 非开发场景 Agent 设计参考

Loop 不仅适用于代码开发，同样适用于办公自动化、文档处理、合规检查等非开发场景。以下是参考设计：

场景 1：采购文档自动化

场景 2：合同合规检查

可配合定时任务实现每日自动检查。

场景 3：标书制作

非开发场景 Agent 设计要点

1. 角色分离原则：生成文档的 Agent 和审查文档的 Agent 必须是不同的个体（避免"既当运动员又当裁判"）

2. 模板驱动：提供标准模板文件（Word/PDF），Agent 按模板内容填充

3. 检查要点清单：将业务规则整理成检查要点，注入检查专员 Agent 的系统提示词

4. 人机协作：Agent 负责初稿生成和初步检查，人类负责最终审核和拍板

9.5 技能包本地路径

技能包已打包保存至：loop-skills-package.zip（位于本指南同级目录）

loop-skills-package.zip|attachment (691.1 KB)

包内包含：

• 31 个 Skill 文件（含完整目录结构和引用资源）

• 6 个 Agent 定义文件（可按需扩展为更多角色）

• 1 份频道配置指南

• 1 份 README 说明