# Stagent：终结"差不多完成了"循环的Claude Code工作流插件

> Stagent是一个Claude Code插件，通过声明式工作流配置和状态机执行机制，解决AI编程助手常见的"无限接近完成"问题，支持实时Web监控、跨设备恢复和模板共享。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-04T12:44:44.000Z
- 最近活动: 2026-05-04T12:49:48.879Z
- 热度: 141.9
- 关键词: Claude Code, AI编程, 工作流, 状态机, 自动化测试, 代码审查, 开发者工具, 插件
- 页面链接: https://www.zingnex.cn/forum/thread/stagent-claude-code
- Canonical: https://www.zingnex.cn/forum/thread/stagent-claude-code
- Markdown 来源: ingested_event

---

## 问题背景

使用AI编程助手（如Claude Code）进行开发时，许多开发者都遇到过这样的困境：AI反复声称"快完成了"、"这次应该可以了"，但实际上代码仍然无法通过测试或存在明显问题。这种"almost done"循环不仅浪费时间，还会消耗大量API调用额度。

问题的根源在于：AI助手缺乏结构化的工作流约束和明确的完成标准。当AI自行决定"完成"时，往往只是主观判断而非客观验证。

## Stagent简介

**Stagent**是由WorldStateLabs开发的开源Claude Code插件，它通过引入声明式工作流和状态机执行模型，从根本上解决了上述问题。用户只需在`workflow.json`中定义阶段、转换条件和输入输出，插件就会驱动一个自动重试循环，直到所有测试通过、代码审查合格、用户旅程测试完成为止。

该项目的核心特性包括：

- **声明式工作流**：通过JSON配置文件定义开发阶段和验收标准
- **状态机执行**：每个阶段有明确的进入和退出条件，确保流程可控
- **自动重试循环**：测试失败时自动返回执行阶段修复，而非简单报告错误
- **实时Web监控**：提供浏览器可访问的实时状态面板
- **跨设备恢复**：支持在不同机器上继续未完成的会话
- **模板中心**：可共享和复用工作流模板

## 双模式架构

Stagent支持两种运行模式，适应不同使用场景：

### 云端模式（默认）

- 状态同步到托管Web应用
- 提供实时浏览器查看器
- 支持跨机器会话恢复
- 不在本地项目目录留下任何痕迹
- 无需配置或API密钥即可匿名使用

### 本地模式

- 状态和产物存储在`/.stagent/`目录下
- 完全离线运行，无需网络连接
- 适合对数据隐私有严格要求的场景

## 内置工作流解析

Stagent捆绑的默认工作流实现了完整的开发周期：

### 1. 规划阶段（可中断）

系统通过内联问答与用户澄清需求，生成计划文件。用户确认后才进入下一阶段。这种设计避免了AI"擅自"实现错误需求的问题。

### 2. 执行阶段

子代理（默认使用Opus模型）根据计划实现功能。当指定了测试优先时，会采用测试驱动开发（TDD）模式，只做最小必要改动。

### 3. 验证阶段

运行快速测试（单元测试/集成测试）。
- **失败**：自动回退到执行阶段
- **通过/跳过**：进入审查阶段

### 4. 审查阶段

子代理对代码进行对抗性审查，与基线提交对比。
- **通过**：进入QA阶段
- **失败**：回退到执行阶段

### 5. QA阶段

子代理运行真实用户旅程测试（Playwright、XcodeBuildMCP等）。系统能区分测试代码bug和应用代码bug，只有确认的应用bug才会阻塞流程。
- **通过**：进入部署阶段
- **失败**：回退到执行阶段

### 6. 部署阶段（可中断）

内联Vercel CLI流程：身份验证、项目关联、环境变量同步、生产部署、URL冒烟测试。该阶段设计为可中断，因为首次运行可能需要用户在另一个终端登录或提供环境变量值。

## 循环终止机制

执行→验证→审查→QA循环在计划批准后自主运行，但有三种方式可以终止：

1. **正常完成**：部署成功，达到终端完成状态
2. **达到最大轮次**：默认20轮（可在`workflow.json`的`.max_epoch`配置），防止无限循环
3. **人工干预**：使用`/stagent:interrupt`暂停或`/stagent:cancel`取消

所有三种终端状态（完成、升级、取消）都在`workflow.json`的`.terminal_stages`中声明。

## 使用示例

### 启动默认工作流

```
/stagent:start --flow=cloud://demo "Build a journaling app with MBTI insights inferred from journal entries"
```

插件会输出实时UI URL（如`https://stagent.worldstatelabs.com/s/<session_id>`），用户可在浏览器中查看阶段时间线、渲染产物和git diff的实时更新。

### 本地离线运行

```
/stagent:start --mode=local "Build a journaling app..."
```

### 从自然语言创建自定义工作流

```
/stagent:create "plan, implement, critique & score UX"
```

这会启动内部Stagent代理，通过访谈用户、编写`workflow.json`和阶段指令文件、在重试循环中验证，最终发布到模板中心（云端模式）。

### 使用自定义工作流

```
/stagent:start --flow=cloud://<username>/<workflow-name> <task>
```

## 模板生态系统

Stagent官方提供12个经过实战检验的工作流模板，涵盖常见的Claude Code失败场景：

- 快速原型开发
- API优先设计
- 遗留代码重构
- UI/UX专项优化
- 性能调优
- 安全加固
- 文档生成
- 测试覆盖率提升

用户可以在[cookbook页面](https://stagent.worldstatelabs.com/cookbook)浏览这些模板，直接fork或混编使用。

## 技术架构

Stagent的插件架构具有高度通用性：只要遵循JSON Schema定义阶段结构，任何形状的阶段都可以工作。这种设计使得社区可以贡献各种专业领域的工作流（如数据科学实验、移动应用发布、基础设施即代码等）。

工作流定义文件包含：
- 阶段列表及其指令文件引用
- 阶段间的转换条件
- 输入输出Schema
- 终端阶段定义
- 最大迭代次数限制

## 适用场景

Stagent特别适合：

- **复杂多步骤任务**：需要多个验证点的开发工作
- **团队协作**：实时Web监控便于团队成员了解进度
- **长周期项目**：跨设备恢复支持在多台机器上断续工作
- **标准化流程**：通过模板确保团队遵循一致的开发规范
- **质量敏感项目**：多重验证关卡确保交付质量

## 局限与考量

使用Stagent时需要注意：

- 需要安装Claude Code、jq、curl、git等依赖工具
- 云端模式依赖WorldStateLabs的托管服务，对数据主权敏感的组织可能需要选择本地模式
- 复杂工作流的配置需要一定学习成本
- 自动重试循环可能消耗较多API调用额度（虽然这比手动反复尝试更高效）

## 总结

Stagent通过引入结构化的状态机工作流，将AI编程助手从"自由发挥"模式转变为"约束执行"模式。这种转变不仅提高了开发效率，更重要的是建立了可预测、可审计、可复现的AI辅助开发流程。对于希望将AI编程助手整合到正式开发工作流的团队来说，Stagent提供了一个值得探索的解决方案。