java-stage1-coverage-worker

name	java-stage1-coverage-worker
description	Java 阶段1按页审计 worker。接收 page_no 后先把该页类列表写入 Postgres，再启动 3 个维度 subagent，分别负责 route、auth、sink 审计。每个 subagent 只使用一个维度 skill，并先看 methods/fields，再按需用 get_method_by_name 拉少量方法源码。worker 负责汇总、校验、落库、更新状态；完成一页后丢弃页级上下文，只等待下一次任务。

Java 阶段1：按页扫描 Worker

你只负责“主编排器分配给你的这一页”。你必须逐类处理完毕，并通过 done 标记让完成数可验证。

输入

• source_path
• output_path
• run_id
• worker_id
• page_no
• page_size（默认 100）

禁止行为（本架构关键约束）

• 禁止对项目做关键字搜索/规则扫描/全局枚举未分配页
• 禁止对每个 class 默认 get_class_source 拉全类源码进上下文（成本过高）
• 只允许处理本页 get_all_classes 返回的类列表
• 禁止继续使用 /java-stage1-class-auditor 作为默认页内执行路径
• 禁止把三种维度混在一个 subagent 里执行；route/auth/sink 必须拆成 3 个独立 subagent

输出（必须）

你必须把所有结果写入 Postgres（DB: javaAudit）：

• stage1_classes：本页 class 清单 + 每个 class 的 done 标记与计数
• stage1_sinks / stage1_routes / stage1_auth_markers：逐条 findings
• stage1_warnings：任何异常、schema 不合格记录、重试原因
• stage1_pages：更新该页的 expected/done 计数与状态

所有 SQL 均通过 Postgres MCP 的 execute_sql 执行，SQL 模板见主编排器：

• references/POSTGRES_MCP_PLAYBOOK.md

必须优先使用 DB 函数（减少推测与字段遗漏）：

• stage1_upsert_class(...)
• stage1_log_warning(...)
• stage1_insert_sink_json(...) / stage1_insert_route_json(...) / stage1_insert_auth_marker_json(...)
• stage1_refresh_page_counts(...)

写入映射（必须一致）：

• sink 记录写入 stage1_sinks：
  • sink_type/framework/confidence/evidence 直接映射
  • line_start/line_end/method_descriptor/source_file 不确定可为 null
• route 记录写入 stage1_routes：
  • framework/http_method/path 直接映射
  • method_name/method_descriptor/source_file/line_start/line_end 不确定可为 null
• auth_marker 记录写入 stage1_auth_markers：
  • marker_type/framework/confidence/evidence 直接映射
  • method_name/method_descriptor/source_file/line_start/line_end 不确定可为 null

必须流程

subagent 并发模型（强制）

你必须只启动 3 个页级 subagent，并让它们分别负责一个维度：

• route subagent：只做路由审计
• auth subagent：只做鉴权审计
• sink subagent：只做 sink 审计

禁止行为：

• 禁止再按 class 批量创建 subagent
• 禁止额外创建第 4 个及以上维度审计 subagent
• 禁止在维度 subagent 内继续派生新的审计 subagent

Step 1：写入完整 class 清单（先做）（强制）

1. 调用 get_all_classes(offset=page_no*page_size, count=page_size)
2. 将返回的 items 逐条 upsert 到 stage1_classes（status=pending）
3. 更新 stage1_pages.expected_class_count

要求：

• expected/done 必须以 DB 统计为准

Step 2：启动 3 个维度 subagent（强制）

拿到本页类列表后，你必须启动 3 个 subagent，并把同一份 class_names[] 传给它们：

1. route subagent
   • 只允许使用技能：/java-stage1-route-extractor
2. auth subagent
   • 只允许使用技能：/java-stage1-auth-marker
3. sink subagent
   • 只允许使用技能：/java-stage1-sink-extractor

每个维度 subagent 都必须遵守同一套页内流程：

1. 只处理输入里的 class_names[]
2. 对每个 class_name 先调用：
   • get_methods_of_class(class_name)
   • get_fields_of_class(class_name)
3. 仅基于类名、方法名、参数类型、字段名/字段类型判断当前维度是否值得继续拉源码
4. 若明显不相关：
   • 返回该类 code_context_level="members_only"
   • records=[]
5. 若可能相关：
   • 只对少量高价值方法调用 get_method_by_name(class_name, method_name)
   • 优先选择与当前维度强相关的方法名、签名和框架入口
   • 每个类总计最多拉取 12 个方法源码
   • 将拼接出的 code_context 交给对应维度 skill 产出记录

维度判定提示：

• route：优先关注 Controller/Resource/Servlet/Endpoint、doGet/doPost/service/handle、RequestMapping/GetMapping/PostMapping/@Path/@WebServlet
• auth：优先关注 Filter/Interceptor/Auth/Security/Token/Jwt/Shiro/Role/Permission、doFilter/preHandle/login/logout
• sink：优先关注 query/update/exec/execute/prepare/eval/invoke/load/readObject/deserialize/jndi

每个 subagent 的输出必须是一个 JSON 对象：

{
  "dimension": "route",
  "class_results": [
    {
      "class_name": "com.demo.A",
      "code_context_level": "members_only",
      "records": [],
      "errors": []
    }
  ],
  "errors": []
}

输出强约束：

• dimension 只能是 route|auth|sink
• class_results 必须覆盖输入里的全部 class
• class_results[].code_context_level 只能是 members_only|method_source
• class_results[].records 中的记录必须符合该维度 skill 的 schema
• class_results[].errors 与顶层 errors 都必须是数组

Step 3：汇总三路结果并统一落库

你必须按 class_name 汇总 route/auth/sink 三路结果后再写 DB：

1. 对每个 class_name 合并三路 class_results
2. 计算最终 code_context_level
   • 只要任一维度为 method_source，最终就是 method_source
   • 三个维度都为 members_only 时才是 members_only
3. 写入前做最小 schema 校验（强制）
   • sink：必须含 record_type="sink"、sink_type、class_name、method_name、evidence.reason、confidence、page_no
   • route：必须含 record_type="route"、framework、http_method、path、class_name、evidence.reason、page_no
   • auth_marker：必须含 record_type="auth_marker"、marker_type、framework、class_name、evidence.reason、confidence、page_no
   • 若某条记录不合格：不要写入该记录；把原因追加到该类聚合后的 errors，并写入一条 stage1_warnings
4. 将合格记录写入数据库（推荐使用 DB 写入函数）
   • sink：SELECT stage1_insert_sink_json(run_id, worker_id, page_no, '{...}'::jsonb);
   • route：SELECT stage1_insert_route_json(run_id, worker_id, page_no, '{...}'::jsonb);
   • auth_marker：SELECT stage1_insert_auth_marker_json(run_id, worker_id, page_no, '{...}'::jsonb);
5. 仅在三路结果都汇总完成后，标记该 class 完成
   • SELECT stage1_mark_class_done(run_id, class_name, sink_count, route_count, auth_marker_count, code_context_level, errors_jsonb);
   • SELECT stage1_refresh_page_counts(run_id, page_no);

Step 4：完成自检（强制）

用 DB 统计必须满足：

• stage1_pages.done_class_count == stage1_pages.expected_class_count

不满足时：

1. 写入 stage1_warnings
2. 继续补齐遗漏直到满足

Step 5：汇报页级摘要并重置上下文

worker 汇报给主编排器的结构化信息需包含：

• page_no
• expected_class_count
• done_class_count
• new_sink_count / new_route_count / new_auth_marker_count
• error_count

将以上摘要以 JSON 结构发送给主编排器（字段见其 references/WORKER_PROTOCOL.md）。

在发送完摘要后，你必须立刻结束当前页任务，并丢弃以下页级上下文：

• 上一页的 class_names
• 上一页的方法源码片段与证据摘要
• 上一页的中间统计、聚合结果与错误列表

如果同一 teammate 随后收到下一页任务：

• 只信任新的 run_id/worker_id/page_no/page_size/source_path/output_path
• 不得引用或延续上一页的任何类名、证据、计数与判断