suriyel / longtaskforagent

语言 / Language **中文** | **English** --- 快速开始 • 安装 方式一：Claude Code 原生命令（推荐） 在 Claude Code 中，首先注册市场： 然后从该市场安装插件： 方式二：一键安装脚本 **macOS / Linux：** **Windows（PowerShell）：** 脚本会自动： • Clone 仓库到 • 更新 注册信息 安装完成后，使用 Claude Code 安装插件： 方式三：OpenCode 用户 如果您使用 OpenCode： **macOS / Linux：** **Windows（PowerShell，需开发者模式或管理员权限）：** 安装完成后重启 OpenCode 即可激活。完整说明请参阅 OpenCode 安装指南。 • 快速开始 启动 Claude Code 后，只需告诉它您想构建什么： 系统将自动进入**需求阶段**，通过结构化提问帮助您完善需求，最终生成标准化的 SRS 文档。后续工作流程完全自动化： 点击查看样例项目 --- Long-Task Agent **一款 Claude Code 技能插件，将单会话 AI 编码转变为严谨的多会话软件工程工作流。** 大多数 AI 编程助手在一次对话后会丢失上下文。Long-Task Agent 通过实现七阶段架构和持久状态桥接解决了这个问题——使 Claude Code 能够以专业工程团队的纪律，跨无限会话构建复杂项目。 为什么选择 Long-Task Agent？ | 问题 | Long-Task Agent 如何解决 | |---------|-------------------------------| | AI 在 后忘记所有内容 | 持久化产物（ 、 、git 历史）自动桥接会话 | | AI 不理解需求就生成代码 | 符合 ISO/IEC/IEEE 29148 的需求收集在编写任何代码前产生经批准的 SRS | | AI 跳过测试或编写浅层测试 | 严格的 TDD（红→绿→重构）配合覆盖率门禁（≥90% 行覆盖，≥80% 分支覆盖）和变异测试（≥80% 得分） | | AI 产生不一致的 UI | 带令牌化设计系统的 UCD 风格指南确保所有功能的视觉一致性 | | AI 验收测试覆盖不全 | ATS（验收测试策略）在设计后前置规划每个需求的测试类别和最低用例数，独立 subagent 审核确保无覆盖盲区 | | AI 偏离批准的设计 | 每个功能后自动进行规范和设计合规性审查 | | 无法安全地向现有项目添加功能 | 增量技能执行影响分析，就地更新 SRS/设计/UCD，用波次跟踪变更 | | "在我机器上能跑"综合症 | 系统测试阶段（IEEE 829）包含回归、集成、端到端和 NFR 验证 | 核心理念 • 需求驱动，而非代码优先 每个项目都从结构化的需求收集开始——而不是编码。SRS 捕获*做什么*，UCD 捕获*外观*，设计文档捕获*怎么做*。三者全部批准后才会编写代码。 • 持久状态桥接会话 十多个持久化产物确保会话间零知识丢失： | 产物 | 用途 | |----------|---------| | | 带状态跟踪的结构化任务清单（JSON 防止模型损坏） | | | 逐会话日志，带当前状态标题 | | | 已批准的软件需求规格说明书 | | | 已批准的技术设计文档 | | | 已批准的验收测试策略（需求→场景映射，独立 subagent 审核） | | | 已批准的 UCD 风格指南（UI 项目） | | | 工作会话指南，含环境激活 + 工具命令 | | | 每功能的 ST 测试用例文档（ISO/IEC/IEEE 29119） | | | 带 RTM 的系统测试计划 | | | 带 Go/No-Go 结论的系统测试报告 | | | Keep a Changelog 格式的活态变更日志 | | Git 历史 | 带描述性提交的完整变更历史 | • 质量不可妥协 每个功能都要通过一系列自动化质量门禁——无例外，无捷径： • **TDD 红→绿→重构** — 先写测试，总是如此 • **覆盖率门禁** — 行覆盖 ≥90%，分支覆盖 ≥80% • **变异门禁** — 变异得分 ≥80%（捕获那些通过但实际没测试任何东西的测试） • **规范和设计合规性审查** — 每个功能都要对照 SRS 和设计文档检查 • **UCD 合规** — UI 功能要验证是否符合风格令牌 • 每个周期一个功能 每个工作会话专注于恰好一个功能。这防止上下文耗尽，确保干净的提交，并使每个功能独立可验证。 七阶段架构 阶段 0a：需求收集 • 符合 ISO/IEC/IEEE 29148 的结构化提问 • EARS 需求模板（Given/When/Then 验收标准） • 反模式检测：模糊词、复合需求、设计泄漏 • 产出一份已批准的 **SRS**（ ） 阶段 0b：UCD 风格指南 • 定义视觉方向、颜色令牌、排版、间距 • 为组件模型生成文本转图像提示词 • 非UI项目自动跳过 • 产出一份已批准的 **UCD**（ ） 阶段 0c：设计 • 提出带有权衡分析的 2-3 种方案 • 每功能的 Mermaid 图（类图、序列图、流程图） • 第三方依赖版本及兼容性验证 • 产出一份已批准的 **设计文档**（ ） 阶段 0d：验收测试策略（ATS） • 将每个 FR/NFR/IFR 映射到验收场景，标注必须的测试类别（FUNC、BNDRY、SEC、PERF、A11Y、UI）和最低用例数 • NFR 测试方法矩阵（工具 + 阈值 + 负载参数） • 跨功能集成场景预规划 • 风险驱动测试优先级排序 • 独立 ATS 审核 subagent（7 维度：覆盖完整性、类别多样性、场景充分性、可验证性、NFR 可测性、集成覆盖、风险一致性），支持自定义审核模板 • 小项目（≤5 FR）自动跳过，Tiny 项目嵌入设计文档 • 产出一份已批准的 **ATS**（ ） • 约束下游 Init（verification_steps）和 feature-st（用例派生） 阶段 1：初始化 • 读取 SRS + 设计 + ATS，脚手架项目骨架 • 将需求分解为 10-200+ 个可验证功能 • 生成环境引导脚本（ / ） • 创建初始 git 提交 阶段 2：工作循环 每个循环遵循严格纪律： 阶段 3：系统测试 • 每功能 ST（ISO/IEC/IEEE 29119）—— 通过 Chrome DevTools MCP 进行黑盒验收测试 • 符合 IEEE 829 的系统级测试计划，带需求追溯矩阵 • 回归、集成、端到端、NFR 验证、探索性测试 • Go/No-Go 结论——缺陷循环回工作会话进行修复 阶段 1.5：增量（发布后变更） • 放置 信号文件 → 技能自动检测 • 对现有功能的影响分析 • 就地更新 SRS、设计、ATS、UCD（git 跟踪历史） • 带波次元数据追加新功能以实现可追溯性 13 技能超能力架构 Long-Task Agent 使用**按需技能加载**模式——只有引导路由器在会话开始时加载；阶段技能按需加载，保持上下文精简。 | 技能 | 角色 | |-------|------| | | 引导路由器——检测项目状态，调用正确阶段 | | | ISO 29148 需求收集 → SRS | | | 带设计令牌的 UCD 风格指南 | | | 带权衡分析的技术设计 | | | 验收测试策略 — 需求→场景映射 + 独立 subagent 审核 | | | 项目脚手架和功能分解 | | | 工作编排器（每周期一个功能） | | | TDD 红→绿→重构纪律 | | | 覆盖率门禁 + 变异门禁 | | | 每功能黑盒验收测试（Chrome DevTools MCP + ISO/IEC/IEEE 29119） | | | 规范、设计和 UCD 合规性审查 | | | 带影响分析的发布后功能添加 | | | 带 Go/No-Go 结论的 IEEE 829 系统测试 | --- 多语言支持 Long-Task Agent 与语言无关。它通过可配置的工具设置支持任何技术栈： | 语言 | 测试框架 | 覆盖率 | 变异测试 | |----------|---------------|----------|------------------| | Python | pytest | pytest-cov | mutmut | | Java | JUnit | JaCoCo | PIT (pitest) | | TypeScript | Vitest / Jest | c8 / istanbul | Stryker | | C/C++ | Google Test | gcov + lcov | Mull | | *自定义* | *任意* | *任意* | *任意* | 中的 字段驱动所有工具命令——使用 消除每种语言的查找： --- 自动化工作流脚本 auto_loop.py - 不间断执行保障 是确保长时间任务能**不间断执行**的核心脚本，通过重复调用 Claude Code 自动化多特性开发流程，直到所有活动特性通过或达到终止条件。 **核心价值：** • 🔄 **自动化迭代** - 无需手动重复执行，脚本自动推进工作流 • ⏸️ **优雅中断** - 支持两级 Ctrl+C 中断，确保当前工作不丢失 • 🛡️ **错误检测** - 自动识别上下文限制、速率限制等不可恢复错误 • 📊 **状态跟踪** - 实时显示特性通过情况 **使用方法：** **参数说明：** • : feature-list.json 的路径（必需） • : 最大迭代次数（默认：50） • : 迭代之间的等待秒数（默认：5） • : 每次迭代发送的提示（默认：继续） **中断处理：** • **第1次 Ctrl+C**: 优雅停止 - 完成当前迭代，然后停止 • **第2次 Ctrl+C**: 强制终止 - 立即终止子进程 **退出代码：** • 0: 所有特性通过 • 1: 错误或达到最大迭代次数 • 2: claude 命令失败 • 3: 检测到不可恢复的错误（上下文限制、速率限制等） • 130: 用户中断（Ctrl+C） --- 验证和安全脚本 插件包含一套验证脚本以防止常见故障： | 脚本 | 用途 | |------|------| | | 验证 模式和数据完整性 | | | 验证 结构完整性 | | | 在功能工作前验证所需的环境配置 | | | 验证 UI 功能的 Chrome DevTools MCP 可用性 | | | 在系统测试前确认所有功能通过 | | | 验证增量请求信号文件 | | | 验证 ST 测试用例文档（ISO/IEC/IEEE 29119） | | | 将技术栈映射到 CLI 命令 | | | 验证真实测试存在性和 mock 检测 | | | 验证 ATS 文档结构完整性 + SRS 交叉验证 | | | ATS↔功能列表↔ST 用例覆盖率检查 | | | 从生成的图像分析 UCD 设计令牌 | --- 模板自定义指南 Long-Task Agent 提供五个可自定义的文档模板，用于生成符合行业标准的需求、设计、测试策略和测试文档。 内置模板 | 模板 | 路径 | 用途 | 标准 | |------|------|------|------| | SRS 模板 | | 软件需求规格说明书 | ISO/IEC/IEEE 29148 | | 设计模板 | | 技术设计文档 | - | | ATS 模板 | | 验收测试策略文档 | - | | ATS 审核模板 | | ATS 审核规范（7 维度） | - | | ST 测试用例模板 | | 系统测试用例文档 | ISO/IEC/IEEE 29119-3 | 自定义方式 SRS 模板自定义 在**需求阶段**（ ），通过对话指定自定义模板路径： **要求**：模板必须是 文件，且包含至少一个 级别的标题。 设计模板自定义 在**设计阶段**（ ），通过对话指定自定义模板路径： **要求**：模板必须是 文件，且包含至少一个 级别的标题。 ATS 模板自定义 通过 根级别字段配置（或在 ATS 阶段通过对话指定）： | 字段 | 说明 | |------|------| | | 自定义 ATS 文档模板路径（定义文档结构） | | | 自定义审核规范模板路径（定义维度、严重级别、通过条件） | | | 示例文件路径（定义风格、语言、详细程度） | 审核模板可自定义：增删维度（如添加 GDPR 数据测试覆盖）、修改严重级别定义、调整通过条件。 ST 测试用例模板自定义 通过 根级别字段配置： | 字段 | 说明 | |------|------| | | 自定义模板路径（定义文档结构） | | | 示例文件路径（定义风格、语言、详细程度） | **配置组合效果**： | 配置 | 效果 | |------|------| | 两者都提供 | 使用模板的**结构** + 示例的**风格** | | 仅提供模板 | 使用模板结构 + 默认风格 | | 仅提供示例 | 从示例推断结构 + 使用示例风格 | | 都不提供 | 使用内置默认模板（ISO/IEC/IEEE 29119-3） | 模板优先级规则 • **用户指定路径** > **内置默认模板** • 模板文件必须存在，否则回退到默认模板 • 模板必须通过验证（ 文件 + 至少一个 标题） 最佳实践 • **复制内置模板作为起点**：保留原有的章节结构，只修改指导文字 • **保持标准合规性**：SRS 模板建议保留 ISO 29148 核心章节；ST 模板建议保留 29119-3 必需字段 • **版本控制**：将自定义模板提交到 git，便于团队协作 • **ST 示例文件**：提供一个已填写的 ST 测试用例文档作为示例，可统一团队的风格和详…