jarvis-agent-factory 4.7.39 → 4.7.40

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-agent-factory",
-  "version": "4.7.39",
+  "version": "4.7.40",
   "description": "Jarvis Agent Factory CLI — Claude Code 多智能体 AI 编程助手配置安装器 | Multi-agent AI coding assistant config installer for Claude Code",
   "keywords": [
     "jarvis",

package/dist/src/templates/platforms/claude/plugins/jarvis-agent-factory/plugin.json

@@ -7,6 +7,6 @@
   "repository": "https://github.com/Wjl1224734792/Jarvis-Agent-Factory",
   "license": "MIT",
   "keywords": ["jarvis", "agent", "multi-agent", "orchestration", "pipeline"],
-  "skills": ["./skills/jarvis-reference/"],
+  "skills": ["./skills/"],
   "commands": ["./commands/"]
 }

package/dist/src/templates/platforms/claude/plugins/jarvis-agent-factory/skills/behavioral-guidelines/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: behavioral-guidelines
+description: "所有智能体的通用行为准则——减少 LLM 编码常见错误。以谨慎为默认姿态，在编码前先思考、保持简洁、精准修改、目标驱动执行。"
+version: "4.3.8"
+updated: "2026-05-14"
+---
+
+此技能面向所有智能体（编排者、实现者、审查者、规划者、探索者），无论角色，均须遵守。
+
+**权衡：以下准则偏向谨慎而非速度。对简单任务可自行判断。**
+
+---
+
+## 何时使用 / 何时不使用
+
+**何时使用：** 此技能适用于一切涉及代码修改、决策、审查或规划的任务。无论复杂度。
+
+**何时不使用：** 纯信息查询（"这个函数怎么用？"）、现状确认（"现在有几个模块？"）——但仍需遵守"先思考再编码"的精神。对于真正简单单一行的修改，准则 3（精准修改）依然适用。
+
+---
+
+## 准则 1：先思考，再编码
+
+**不假设。不隐藏困惑。主动暴露权衡。**
+
+实现前：
+- 明确陈述你的假设。如有疑问，立即提出。
+- 若存在多种理解，全部列出——不要默默选择一个。
+- 若存在更简单的方案，直接指出。在合理时提出异议。
+- 若某事不清晰，立即停止。明确说出困惑所在。主动询问。
+
+**反模式：** 看到一个模棱两可的需求后，不提问就挑选一个看似合理的解释去实现。
+
+### 常见合理化借口
+
+| 合理化借口 | 现实 |
+|-----------|------|
+| "我大概理解了，先开始做" | 模糊的理解 = 代码不符合预期 = 重写。10 秒确认比 10 分钟重写划算。 |
+| "已经有很多上下文了，我能推断" | 推断 = 猜测。用户没说出来的，默认不存在。 |
+| "问太多显得不专业" | 不问就实现错才不专业。澄清问题是专业工程师的标志。 |
+| "这只是一种可能的理解，我按最常见的做" | 列出其他理解。让用户选择。不要替用户做假设。 |
+
+---
+
+## 准则 2：简单优先
+
+**用最少代码解决问题。不做投机性工作。**
+
+- 不添加需求之外的功能。
+- 不为单一用途代码创建抽象。
+- 不实现未被要求的"灵活性"或"可配置性"。
+- 不为不可能发生的场景做错误处理。
+- 如果写了 200 行但 50 行就够了，重写它。
+
+自问：**"高级工程师会说这是过度设计吗？"** 若是，简化。
+
+**反模式：** 为了"将来可能需要"而添加一个扩展点、配置项或抽象层。
+
+### 常见合理化借口
+
+| 合理化借口 | 现实 |
+|-----------|------|
+| "加个配置选项，以后可能会用到" | YAGNI。没被要求的功能 = 没有价值。加代码容易删代码难。 |
+| "抽象出来以后好扩展" | 单一用途的抽象 = 过度设计。只有在第二种用途出现时才抽象。 |
+| "这样子更'灵活'" | 灵活性不是免费的。每条 if 分支都是测试成本和维护成本。 |
+| "200 行也没关系，分得很清楚" | 如果 50 行能说清楚，200 行就是过度。清晰 ≠ 冗长。 |
+
+---
+
+## 准则 3：精准修改
+
+**只动必须动的。只清理自己造成的混乱。**
+
+编辑现有代码时：
+- 不"优化"相邻代码、注释或格式。
+- 不重构没有问题的东西。
+- 遵循现有风格，即使你个人会写得不一致。
+- 若发现无关的遗留死代码，提及它——但不要删除。
+
+当你的改动造成孤儿代码时：
+- 移除因你的改动而变得无用的 import/变量/函数。
+- 不要删除预先存在的死代码，除非被要求。
+
+**检验标准：** 每个改动行都应能直接追溯到用户的请求。
+
+**反模式：** 在修复一个 bug 时顺手"重构"了所在文件的导入风格。
+
+### 常见合理化借口
+
+| 合理化借口 | 现实 |
+|-----------|------|
+| "顺便把格式对齐一下，不耽误事" | 无关改动 = 增加 review 噪声 = 掩盖真正的问题。格式问题另外提 PR。 |
+| "这个 import 没用了，顺便删了" | 如果这个 import 不是你的改动造成的，提及它但不要动手。 |
+| "这个文件风格和项目不一致，我统一一下" | 风格一致性是好事——但不在这个 PR 里。另开一个纯粹的风格 PR。 |
+| "只是改了一个变量名，很安全" | 变量名变更可能破坏外部引用、序列化、或文档。确认安全后再改。 |
+
+---
+
+## 准则 4：目标驱动执行
+
+**定义成功标准。循环验证直至通过。**
+
+将任务转化为可验证的目标：
+| 用户说的 | 转化为 |
+|---------|--------|
+| "添加验证" | 为无效输入编写测试，然后使其通过 |
+| "修复 bug" | 编写能复现它的测试，然后使其通过 |
+| "重构 X" | 确保重构前后测试均通过 |
+
+对于多步骤任务，陈述简要计划：
+```
+1. [步骤] → 验证: [检查项]
+2. [步骤] → 验证: [检查项]
+3. [步骤] → 验证: [检查项]
+```
+
+强的成功标准让你能独立循环迭代。弱的标准（"让它能工作"）则需要持续澄清。
+
+**反模式：** 说"已完成"但没有运行任何验证命令来证明。
+
+### 常见合理化借口
+
+| 合理化借口 | 现实 |
+|-----------|------|
+| "测试待会再跑，我先改了再说" | 先写测试确保你理解了需求。先改代码再补测试 = 测试适配代码而非需求。 |
+| "我看输出就知道对不对了" | 人工检查不可靠、不可重复。自动化验证 = 事实。 |
+| "步骤很简单，不需要列计划" | 不写下来 = 可能漏步骤。3 步计划 30 秒写完。 |
+| "我跑过测试了，都通过了" | 跑的是什么测试？展示结果。没有证据 = 没有完成。 |
+
+---
+
+## 红线
+
+以下是危险信号——当你冒出这些想法时立即停止：
+
+| 危险信号 | 检查 |
+|---------|------|
+| "这个很简单，我不需要..." | 这几乎总是需要。检查行为准则。 |
+| "我顺便也修一下..." | 不是你的任务范围。停下来，只做被要求的。 |
+| "这样写更灵活，虽然没被要求..." | YAGNI 违规。删除未要求的灵活性。 |
+| "我觉得已经对了..." | "觉得"不够。有什么证据？ |
+| "就改一行，不会出问题..." | 一行也能引入 bug。改了就要验证。 |
+| "不用看现有代码，我知道怎么实现..." | 项目有历史。现有模式是你最好的指南。先读再写。 |
+| "这看起来是死代码，删掉..." | 切斯特顿之栏。你不知道为什么它在那里。先问再删。 |
+| "我都快做完了，补个测试就行..." | 测试不是补丁。在编码之前或同时写测试，不是之后。 |
+
+---
+
+---
+
+## 生效标志
+
+**这些准则生效的标志：**
+
+- diff 中不必要的改动减少（非用户请求的变更行 < 总变更行的 5%）
+- 因过度设计导致的重写减少（不会出现"这个抽象层太复杂了，重写吧"）
+- 澄清性问题在实现前提出，而非出错后（问题数量在编码前 > 编码后）
+- 每个改动都能说清楚对应哪个用户请求
+- code review 不再标注大量"行为准则违规"类 finding
+- 不会出现"我顺便也做了个功能但没说要"的情况
+
+---
+
+## 实施指令
+
+### 对于编排者（Jarvis）
+
+1. 在开始任何编排会话时加载此技能。
+2. 在调用 Task 工具向子代理传递 Execution Packet 时，附上上述四项准则摘要。
+3. 若有子代理的回传显示可能违反了某项准则（例如改动了无关文件），在 Gate 检查时予以纠正。
+
+### 对于子代理
+
+1. 在执行任何分配任务前，回顾并确认自己已理解上述四项准则。
+2. 在输出 `Execution Acknowledgement` 时确认："我已理解并遵守 behavioral-guidelines 各项准则。"
+3. 若判断简单任务且准则中某项可能带来不必要的开销，可以在 acknowledge 中说明理由后简化——但必须显式说明。
+
+### 对于审查类代理
+
+1. 在 `Findings` 中额外标注违反行为准则的改动（标记为行为准则违规）：
+   - 准则 2 违规：不必要的抽象、过度配置化
+   - 准则 3 违规：相邻代码被无关修改、无故删除死代码
+2. 准则级违规不替代功能级缺陷——分别列出。
+
+## 相关技能
+
+- **[code-simplification](../code-simplification/SKILL.md)** — 准则 2 的深度实践：结构化代码简化流程、切斯特顿之栏
+- **[context-engineering](../context-engineering/SKILL.md)** — 准则 1 的深度实践：上下文管理、混淆处理、内联规划模式
+- **[code-standards](../code-standards/SKILL.md)** — 准则 1-4 的编码落地：注释、嵌套、不可变、模块化、设计原则、DDD、TDD、数据库外键
+
+---
+
+## 准则 5：注释语言约定
+
+代码注释跟随项目已有语言：中文项目用中文注释，英文项目用英文注释。不确定时检查已有代码文件的注释语言。
+
+此约定适用于所有智能体，无需在各 agent 中重复声明。
+
+---
+
+## 准则 6：多模态回退
+
+**当模型缺乏多模态能力时，使用截图 + 文字描述作为回退方案。**
+
+当任务涉及图像、截图或视频分析时，若当前模型不支持多模态能力：
+1. 使用 Playwright MCP 工具 (`browser_take_screenshot`) 截取页面截图
+2. 结合 `browser_snapshot` 获取页面可访问性快照（含元素结构和文本）
+3. 通过页面 DOM 状态和文本内容推断视觉问题
+
+**适用场景：** 审查 UI 布局、检查设计稿、分析浏览器截图等需要视觉理解的场景。
+
+此约定适用于所有智能体，无需在各 agent 中重复声明。

package/dist/src/templates/platforms/claude/plugins/jarvis-agent-factory/skills/browser-testing/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: browser-testing
+description: "浏览器自动化测试方法论——混合模式测试：agent-browser（看清）+ Playwright MCP（操作）。精确获取页面结构 + 稳定执行交互操作。用于 /browser-test 和 /bug-fix 命令的执行。"
+version: "4.7.25"
+updated: "2026-05-25"
+---
+
+# 浏览器自动化测试
+
+## 概述
+
+**混合模式：agent-browser（看清）+ Playwright MCP（操作）**
+
+本质：**精确获取 + 稳定执行**——agent-browser snapshot -i 以极低成本获取页面结构（DOM 快照 + 元素引用），Playwright MCP 负责可靠的交互操作（点击/填写/导航/截图）。
+
+- **agent-browser snapshot -i**：廉价页面结构获取，返回元素引用（@ref），token 消耗极低
+- **Playwright MCP**：稳定执行交互——browser_click / browser_type / browser_navigate / browser_take_screenshot 等，CI 可重复
+- **agent-browser CLI**：补充操作——console 日志、network 请求、viewport 调整等诊断能力
+
+**前置条件：** `agent-browser` 已安装（`npm i -g agent-browser && agent-browser install`），Playwright MCP 已配置。
+
+## 测试用例格式
+
+每条用例输出到 `.jarvis/YYYY-MM-DD/testing/<topic>-browser-test-cases.md`：
+
+```markdown
+### TC-001: <用例名称>
+- **前置条件**：<URL、登录状态、数据准备>
+- **操作步骤**：
+  1. 导航到 <页面>
+  2. 点击/输入 <元素>
+  3. 验证 <结果>
+- **预期结果**：<具体可验证的结果>
+- **验证方式**：截图 / 状态检查 / 元素文本匹配
+- **优先级**：P0（阻塞）/ P1（重要）/ P2（次要）
+```
+
+## 执行流程
+
+按优先级从高到低逐条执行。
+
+### 初始化：打开浏览器
+
+```bash
+agent-browser open <url>          # 默认无头，加 --headed 可见
+agent-browser profile list        # 若需复用 Chrome 登录态，先查 profile
+agent-browser --profile "Default" open <url>  # 使用现有 Chrome 登录态
+```
+
+### 每条用例的标准操作序列（混合模式）
+
+```bash
+# 1. 获取页面快照（agent-browser 精确获取元素引用）
+agent-browser snapshot -i
+
+# 2. 交互操作（Playwright MCP 稳定执行）
+mcp__playwright__browser_click({target: "<element-ref>"})       # 点击元素
+mcp__playwright__browser_type({target: "<ref>", text: "..."})   # 输入文本
+mcp__playwright__browser_press_key({key: "Enter"})              # 按键
+mcp__playwright__browser_navigate({url: "<URL>"})               # 导航
+mcp__playwright__browser_hover({target: "<ref>"})               # 悬停
+
+# 3. 截图留证（Playwright MCP）
+mcp__playwright__browser_take_screenshot({type: "png"})         # 截图
+mcp__playwright__browser_take_screenshot({fullPage: true})      # 全页截图
+
+# 4. 验证（agent-browser 诊断 + Playwright 快照）
+agent-browser snapshot -i                                        # 确认元素引用变化
+mcp__playwright__browser_snapshot()                              # Playwright 无障碍快照
+agent-browser console                                            # 检查控制台日志
+agent-browser errors                                             # 检查 JS 异常
+agent-browser network requests --filter api                      # 检查 API 请求
+agent-browser get url                                            # 确认当前 URL
+```
+
+**执行规则：**
+- agent-browser snapshot -i 获取元素引用（看清），Playwright MCP 执行操作（执行）
+- 每次关键交互后截图（点击按钮、提交表单、页面跳转后）
+- 失败立即记录，截图保存失败状态
+- 前置条件不满足则标记"跳过"，写明原因
+- 页面异常时 `agent-browser close` 清理后重试
+- 不用硬等待；用 `agent-browser wait "<selector>"` 或 Playwright `browser_wait_for` 确认页面状态
+
+## Bug 复现模式
+
+接到 Bug 报告后：
+
+1. 读取复现步骤
+2. `agent-browser open <url>` → `agent-browser snapshot -i` → 逐步执行操作
+3. 异常发生时立即截图：`agent-browser screenshot bug-xxx.png` + `agent-browser screenshot --annotate`
+4. 收集证据：
+   - `agent-browser console` — JS 错误
+   - `agent-browser errors` — 未捕获异常
+   - `agent-browser network requests` — 失败的网络请求
+   - `agent-browser get text @eN` — 页面异常文本
+5. 尝试至少 1 个变体确认触发边界
+6. 输出复现证据：截图路径、操作步骤、实际 vs 预期
+
+## 响应式/多视口测试
+
+对于需要验证响应式的页面：
+
+```bash
+agent-browser set viewport 375 812   # 移动端
+agent-browser screenshot mobile.png
+agent-browser set viewport 768 1024  # 平板
+agent-browser screenshot tablet.png
+agent-browser set viewport 1280 800  # 桌面
+agent-browser screenshot desktop.png
+```
+
+## 本地开发环境测试
+
+### 工具可用性矩阵
+
+| 平台/环境 | Preview MCP | agent-browser CLI | Playwright MCP | Chrome DevTools MCP |
+|-----------|------------|-------------------|----------------|---------------------|
+| Claude Code（桌面版） | ✅ 可用 | ✅ 可用 | ✅ 可用 | ✅ 可用 |
+| Claude Code（终端/CLI） | ❌ 不可用 | ✅ 可用 | ✅ 可用 | ✅ 可用 |
+| OpenCode | ❌ 不可用 | ✅ 可用 | ✅ 可用 | ✅ 可用 |
+| Codex | ❌ 不可用 | ✅ 可用 | ✅ 可用 | ✅ 可用 |
+
+> **混合模式**：agent-browser snapshot -i 精确获取页面结构（看清），Playwright MCP 稳定执行交互操作（操作）。Chrome DevTools MCP 用于前端调试（性能追踪/渲染分析/网络诊断/控制台调试）。
+
+### 方案 A：有 Preview MCP 时（Claude Code 桌面版）
+
+1. `mcp__Claude_Preview__preview_list` — 检查是否已有运行中的预览服务器
+2. 若未运行且 `.claude/launch.json` 已配置：
+   ```
+   mcp__Claude_Preview__preview_start({name: "<config-name>"})
+   ```
+3. 获取本地 URL 后使用 `agent-browser open <url>` 或 `preview_screenshot` 进行测试
+4. 测试完成后可保留服务器供后续使用
+
+### 方案 B：无 Preview MCP 时（Claude Code 终端 / OpenCode / Codex）
+
+1. 通过 Bash 启动 dev server（后台运行）：
+   ```bash
+   npm run dev &
+   ```
+2. 用 agent-browser 打开页面：
+   ```bash
+   agent-browser open http://localhost:<port>
+   ```
+3. 页面快照 + 截图验证：
+   ```bash
+   agent-browser snapshot -i
+   agent-browser screenshot
+   ```
+4. 响应式多视口测试：
+   ```bash
+   agent-browser set viewport 375 812   # 移动端
+   agent-browser screenshot mobile.png
+   agent-browser set viewport 768 1024  # 平板
+   agent-browser screenshot tablet.png
+   agent-browser set viewport 1280 800  # 桌面
+   agent-browser screenshot desktop.png
+   ```
+
+## 报告模板
+
+`.jarvis/YYYY-MM-DD/testing/<topic>-browser-test-report.md`：
+
+```markdown
+# 浏览器自动化测试报告
+
+## 测试概览
+| 总用例 | 通过 | 失败 | 跳过 | 通过率 |
+|--------|------|------|------|--------|
+| N      | N    | N    | N    | XX%    |
+
+## 环境信息
+- 测试 URL：<URL>
+- 测试时间：<timestamp>
+- 浏览器视口：<尺寸>
+
+## 详情
+### TC-001: <名称> — ✅ 通过
+- 截图：<路径>
+
+### TC-002: <名称> — ❌ 失败
+- 预期：<结果> / 实际：<结果>
+- 截图：<路径>
+- 控制台错误：<错误信息>
+- 网络异常：<失败请求>
+- 疑似原因：<分析>
+
+## 失败汇总
+| 用例 | 严重度 | 故障类型 | 疑似根因 |
+|------|--------|---------|---------|
+```
+
+## 修复闭环
+
+1. 全部通过 → ✅ 闭环完成
+2. 存在失败 → Browser Test Findings → `/review-fix` 修复 → 仅重跑失败用例 → 更新报告
+3. 最多 2 轮，第 3 轮仍失败标记 BLOCKED
+
+## 红线
+
+- 不写用例直接操作浏览器（缺少可追溯的测试计划）
+- 失败不截图、不记录控制台/网络错误（缺少证据）
+- 跳过用例不标注原因
+- 伪造测试结果
+- 执行破坏性操作（删除数据、发起支付等）
+- 用硬等待（sleep/wait）替代 `agent-browser wait` 轮询确认页面状态
+
+## 职责分工
+
+### 测试文档编写 vs 测试执行
+- **test-doc-writer Agent**：负责在测试执行前根据需求文档和前端变更编写结构化测试用例文档，输出到 `.jarvis/YYYY-MM-DD/testing/<topic>-test-cases.md`
+- **browser-test-expert**：负责读取已有测试文档中的用例并逐条执行，输出测试报告到 `.jarvis/YYYY-MM-DD/testing/<topic>-browser-test-report.md`
+- **职责边界**：测试执行 Agent 不得自行编写或修改测试用例文档，测试文档编写 Agent 不得执行浏览器测试。测试用例必须在测试执行前由 test-doc-writer 编写完成。
+
+## 测试报告模板
+
+执行完成后按以下模板输出测试报告（输出到 `.jarvis/YYYY-MM-DD/testing/<topic>-browser-test-report.md`）：
+
+### 汇总
+
+| 指标 | 数值 |
+|------|------|
+| 总计 | N |
+| 通过 | N ✅ |
+| 失败 | N ❌ |
+| 阻塞 | N ⚠️ |
+
+### 详细结果
+
+#### TC-XXX: 用例标题 — ✅/❌
+- **预期:** ...
+- **实际:** ...
+- **截图证据:** <路径>
+- **可能原因:** （仅失败时）
+- **关联代码:** <文件:行号>（仅失败时）
+
+### 失败用例清单
+- [ ] TC-XXX: 简短描述
+
+## 失败用例交接格式
+
+测试失败后，向修复 Agent 传递以下信息：
+
+```json
+{
+  "failedCases": [
+    {
+      "id": "TC-XXX",
+      "title": "用例标题",
+      "expected": "预期结果",
+      "actual": "实际结果",
+      "screenshot": "截图路径",
+      "possibleCause": "可能原因分析",
+      "relatedCode": "关联代码位置"
+    }
+  ]
+}
+```
+
+或 markdown 格式：
+
+```markdown
+## 失败用例交接
+### TC-XXX: 用例标题
+- **预期:** ...
+- **实际:** ...
+- **截图证据:** <路径>
+- **可能原因:** <分析>
+- **关联代码:** <文件:行号>
+```