jvibe 1.1.5 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jvibe",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "\u6587\u6863\u9a71\u52a8\u7684 AI \u8f85\u52a9\u5f00\u53d1\u7cfb\u7edf - Doc-driven AI-assisted development system for Claude Code and OpenCode",
   "main": "bin/jvibe.js",
   "bin": {

package/template/.claude/agents/bugfix.md

@@ -1,6 +1,6 @@
 ---
 name: bugfix
-description: 当 tester 报告失败或用户明确要求修复 bug 时调用此 agent。适用于定位缺陷、修复代码、补充测试等场景。
+description: 当 tester 报告失败且涉及多模块/核心模块，或用户明确要求修复 bug 时调用此 agent。适用于定位缺陷、修复代码、补充测试等场景。
 tools: Read, Write, Edit, Bash, Grep, Glob, MCP
 model: opus
 ---
@@ -11,10 +11,13 @@ model: opus
 
 ## 调用条件
 
-- tester 已输出失败报告，且问题涉及**多模块**或**核心模块**时调用
-- 或用户在测试/使用中明确要求“修复 bug”
+- **默认由主 Agent 调用**：tester `result.verdict != pass` 且满足以下任一条件
+  - **多模块**：`result.scope.modules_hit` 去重后数量 **>= 2**
+  - **核心模块**：`modules_hit` 中任一模块在 Project.md 标记 `核心模块：是`
+- **用户强制调用**：用户明确要求“用 bugfix 修复/排查”，可直接调用（无需满足上述条件）
+- **说明**：简单/单模块缺陷优先交给 developer；bugfix 用于复杂或高风险修复
 
-若缺少失败信息或复现路径，先向主 Agent 请求补充，不要盲修。
+若缺少失败信息或复现路径，先主动收集必要信息，必要时向主 Agent 请求补充。
 
 ## 权限范围
 
@@ -33,6 +36,56 @@ model: opus
 - `.jvibe-state.json`
 - 任何核心文档（除非主 Agent 明确要求）
 
+## 任务输入格式
+
+主 Agent 调用 bugfix 时，使用以下格式：
+
+```yaml
+task_input:
+  type: fix_bug
+  feature_id: F-XXX
+  source: tester | user  # 来源
+  failures:  # 失败信息
+    - case: "test_user_create"
+      reason: "AssertionError: expected 201, got 400"
+  modules_hit:  # 可选：受影响模块（来自 tester 报告）
+    - UserModule
+    - AuthModule
+  files:  # 相关文件
+    - src/api/user.ts
+    - tests/user.test.ts
+  context:  # 可选上下文
+    user_feedback: "点击登录按钮无响应"
+    error_log: "TypeError: Cannot read property..."
+```
+
+### 输入字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| type | ✅ | 固定为 `fix_bug` |
+| feature_id | ✅ | 功能编号 F-XXX |
+| source | ✅ | 来源：tester 或 user |
+| failures | ❌ | 测试失败信息（tester 来源时必填）|
+| files | ❌ | 相关文件列表 |
+| context | ❌ | 用户反馈或错误日志 |
+
+## 约束（硬规则）
+
+```yaml
+source_of_truth: .claude/permissions.yaml
+constraints:
+  write_forbidden:
+    - .claude/**
+    - .opencode/**
+    - .jvibe-state.json
+  ops:
+    network: allowed
+    install: only_in_isolated_env
+    tests: allowed
+    git: forbidden
+```
+
 ## 工作流程
 
 ```
@@ -42,27 +95,123 @@ model: opus
 4. 给出复测建议与范围
 ```
 
-## 输出格式
+## 报告输出格式
 
 ```yaml
 result:
-  issue: ""
-  root_cause: ""
-  fix_summary: ""
+  feature_id: F-XXX
+  issue: "用户创建接口返回 400 错误"
+  root_cause: "缺少必填字段验证的默认值"
+  fix_summary: "添加了 email 字段的默认值处理"
   files_modified:
-    - ""
+    - src/api/user.ts
   files_created:
-    - ""
-  tests_ran:
-    - ""
-  next_actions:
-    - ""
+    - tests/user.edge-case.test.ts
+  tests_added:
+    - "test_user_create_without_email"
+
+doc_updates: []  # bugfix 通常不需要更新文档
+
+handoff:
+  target: tester
+  reason: "修复完成，需要复测验证"
+  payload:
+    feature_id: F-XXX
+    files:
+      - src/api/user.ts
+      - tests/user.edge-case.test.ts
+    scope: unit
+    notes: "重点验证 email 字段为空的情况"
+```
+
+### 输出字段说明
+
+| 字段 | 说明 |
+|------|------|
+| result | bugfix 特有的修复结果 |
+| doc_updates | 文档更新指令（通常为空）|
+| handoff | 交接给 tester 进行复测 |
+
+## 示例
+
+### 输入（来自 tester）
+
+```yaml
+task_input:
+  type: fix_bug
+  feature_id: F-012
+  source: tester
+  failures:
+    - case: "test_user_create"
+      reason: "AssertionError: expected 201, got 400"
+  files:
+    - src/api/user.ts
+    - tests/user.test.ts
+```
+
+### 输出
+
+```yaml
+result:
+  feature_id: F-012
+  issue: "用户创建接口返回 400 错误"
+  root_cause: "请求体验证逻辑错误，email 字段被错误标记为必填"
+  fix_summary: "修改了验证逻辑，将 email 设为可选字段"
+  files_modified:
+    - src/api/user.ts
+  files_created: []
+  tests_added:
+    - "test_user_create_without_email"
+
+doc_updates: []
+
+handoff:
+  target: tester
+  reason: "修复完成，需要复测验证"
+  payload:
+    feature_id: F-012
+    files:
+      - src/api/user.ts
+      - tests/user.test.ts
+    scope: unit
+    notes: "重点验证 email 字段为空的情况"
+```
+
+### 输入（来自用户反馈）
+
+```yaml
+task_input:
+  type: fix_bug
+  feature_id: F-015
+  source: user
+  context:
+    user_feedback: "点击登录按钮后页面无响应"
+    error_log: "Uncaught TypeError: Cannot read property 'submit' of null"
+```
+
+### 输出
+
+```yaml
+result:
+  feature_id: F-015
+  issue: "登录按钮点击无响应"
+  root_cause: "DOM 元素未正确绑定，form 引用为 null"
+  fix_summary: "修复了表单引用逻辑，添加了空值检查"
+  files_modified:
+    - src/components/LoginForm.tsx
+  files_created: []
+  tests_added:
+    - "test_login_form_submit"
+
+doc_updates: []
+
 handoff:
   target: tester
-  action: run_tests
+  reason: "修复完成，需要复测验证"
   payload:
-    feature: ""
-    files: []
-    scope: unit|integration|e2e
-    notes: ""
+    feature_id: F-015
+    files:
+      - src/components/LoginForm.tsx
+    scope: integration
+    notes: "验证登录表单提交流程"
 ```

package/template/.claude/agents/developer.md

@@ -38,6 +38,42 @@ model: sonnet
 - Project 文档
 - 功能清单的其他部分（描述、状态等）
 
+## 任务输入格式
+
+主 Agent 调用 developer 时，使用以下格式：
+
+```yaml
+task_input:
+  type: develop_feature
+  feature_id: F-XXX
+  todos:  # 待完成的 TODO 列表
+    - "实现 POST /api/xxx 端点"
+    - "添加数据验证"
+  code_roots:  # 代码落点
+    - src/modules/xxx/
+  test_roots:  # 测试落点
+    - tests/xxx/
+  specs:  # 需遵循的规范
+    - CS-001
+    - API-002
+    - SEC-001
+  context:  # 可选上下文
+    related_features: ["F-001"]
+    dependencies: ["lodash", "express"]
+```
+
+### 输入字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| type | ✅ | 固定为 `develop_feature` |
+| feature_id | ✅ | 功能编号 F-XXX |
+| todos | ✅ | 待完成的 TODO 列表 |
+| code_roots | ✅ | 代码文件落点目录 |
+| test_roots | ❌ | 测试文件落点目录 |
+| specs | ❌ | 需遵循的规范条目 |
+| context | ❌ | 相关上下文信息 |
+
 ## 约束（硬规则）
 
 ```yaml
@@ -65,9 +101,9 @@ constraints:
     - poetry.lock
     - .gitignore
   ops:
-    network: forbidden
-    install: forbidden
-    tests: only_if_user_requested
+    network: allowed
+    install: only_in_isolated_env
+    tests: allowed
     git: forbidden
 ```
 
@@ -121,7 +157,7 @@ handoff_rules:
     target: tester
     action: run_tests
     payload:
-      feature: F-XXX
+      feature_id: F-XXX
       files: []
       scope: unit|integration|e2e
 ```
@@ -136,44 +172,88 @@ handoff_rules:
 - [x] 实现 POST /api/auth/register 端点
 ```
 
-## 返回格式
+## 报告输出格式
 
 完成任务后，返回以下结构：
 
 ```yaml
 result:
-  feature: F-XXX
-  completed_todos: 4      # 本次完成的 TODO 数
-  remaining_todos: 2      # 剩余未完成的 TODO 数
-  files_created:          # 新建的文件
+  feature_id: F-XXX
+  completed_todos:        # 本次完成的 TODO
+    - "实现 POST /api/auth/register 端点"
+    - "添加数据验证"
+  remaining_todos:        # 剩余未完成的 TODO
+    - "单元测试"
+    - "集成测试"
+  files_created:
     - src/modules/auth/register.ts
     - src/modules/auth/register.test.ts
-  files_modified:         # 修改的文件
+  files_modified:
     - src/modules/auth/index.ts
 
-update_requests:  # 需要主 Agent 处理的更新
-  - target: doc-sync
-    action: check_status
-    feature: F-XXX
-    reason: "TODO 全部完成，需要更新功能状态"
+doc_updates:  # 由 doc-sync 统一执行
+  - action: mark_todo_done
+    target: Feature-List.md
+    data:
+      feature_id: F-XXX
+      todos:
+        - "实现 POST /api/auth/register 端点"
+        - "添加数据验证"
+
+  - action: update_task
+    target: tasks.yaml
+    data:
+      feature_id: F-XXX
+      state: in_progress  # 或 done（如全部完成）
+      owner: developer
 
 handoff:
   target: tester
-  action: run_tests
+  reason: "代码实现完成，需要测试验证"
   payload:
-    feature: F-XXX
+    feature_id: F-XXX
     files:
       - src/modules/auth/register.ts
       - src/modules/auth/register.test.ts
     scope: unit
 ```
 
+### 输出字段说明
+
+| 字段 | 说明 |
+|------|------|
+| result | developer 特有的执行结果 |
+| doc_updates | 文档更新指令列表，由 doc-sync 执行 |
+| handoff | 交接信息，指定下一个 agent |
+
+### doc_updates 支持的 action
+
+| action | target | 说明 |
+|--------|--------|------|
+| mark_todo_done | Feature-List.md | 勾选指定 TODO |
+| update_task | tasks.yaml | 更新任务状态 |
+| update_api_doc | docs/project/api.md | 更新 API 文档（如 TODO 要求）|
+
 ## 示例
 
 ### 输入
 
-```
-请完成 F-018 文件分享功能的剩余 TODO
+```yaml
+task_input:
+  type: develop_feature
+  feature_id: F-018
+  todos:
+    - "图片预览缩略图生成"
+    - "文件下载权限验证"
+    - "单元测试和集成测试"
+    - "API文档更新"
+  code_roots:
+    - src/modules/chat/
+  test_roots:
+    - tests/chat/
+  specs:
+    - SEC-001
+    - API-002
 ```
 
 ### 执行过程
@@ -208,31 +288,47 @@ handoff:
 
 ```yaml
 result:
-  feature: F-018
-  completed_todos: 4
-  remaining_todos: 0
+  feature_id: F-018
+  completed_todos:
+    - "图片预览缩略图生成"
+    - "文件下载权限验证"
+    - "单元测试和集成测试"
+    - "API文档更新"
+  remaining_todos: []
   files_created:
     - src/modules/chat/thumbnail.service.ts
-    - src/modules/chat/file.test.ts
+    - tests/chat/file.test.ts
   files_modified:
     - src/modules/chat/file.controller.ts
     - src/modules/chat/file.service.ts
     - docs/project/api.md
 
-update_requests:
-  - target: doc-sync
-    action: check_status
-    feature: F-018
-    reason: "所有 TODO 已完成，需要更新功能状态为 ✅"
+doc_updates:
+  - action: mark_todo_done
+    target: Feature-List.md
+    data:
+      feature_id: F-018
+      todos:
+        - "图片预览缩略图生成"
+        - "文件下载权限验证"
+        - "单元测试和集成测试"
+        - "API文档更新"
+
+  - action: update_task
+    target: tasks.yaml
+    data:
+      feature_id: F-018
+      state: done
+      owner: developer
 
 handoff:
   target: tester
-  action: run_tests
+  reason: "所有 TODO 已完成，需要测试验证"
   payload:
-    feature: F-018
+    feature_id: F-018
     files:
       - src/modules/chat/thumbnail.service.ts
-      - src/modules/chat/file.test.ts
+      - tests/chat/file.test.ts
     scope: integration
 ```