source-kb 0.2.2__py3-none-any.whl

presets/generic/preset.yaml

@@ -0,0 +1,115 @@
+# Generic Preset — 通用降级预设
+# 不绑定任何语言，按文件扩展名和目录名做基础分类
+#
+# file_extensions 为空时，匹配所有非隐藏文件（排除 test/generated 目录）。
+# 如需限定语言，填入对应扩展名，如 [".py", ".pyi"] 或 [".go"]。
+
+name: "Generic"
+language: "any"
+file_extensions: []  # 空 = 所有非隐藏文件（排除 test_patterns 和 generated_patterns）
+test_patterns: ["/test/", "/tests/", "/__tests__/", "/spec/"]
+generated_patterns: ["/generated/", "/build/", "/dist/", "/node_modules/", "/target/", "/.git/"]
+
+file_classification:
+  source:
+    patterns: ["/src/", "/lib/", "/app/"]
+    affects: ["business-logic.md"]
+  api:
+    patterns: ["/api/", "/routes/", "/endpoints/", "/controllers/"]
+    affects: ["api-contracts.md", "business-logic.md"]
+  model:
+    patterns: ["/models/", "/entities/", "/schemas/", "/types/"]
+    affects: ["data-models.md"]
+  config:
+    patterns: ["/config/", "/configs/", "*.yml", "*.yaml", "*.toml", "*.json", "*.env"]
+    affects: ["architecture.md"]
+
+module_types:
+  service:
+    skip: []
+  library:
+    skip: ["api-contracts.md"]
+    detect_patterns: ["*-lib", "*-common", "*-shared", "*-utils"]
+  frontend:
+    skip: ["source-tree-analysis.md", "api-contracts.md"]
+    detect_patterns: ["*-web", "*-ui", "*-frontend", "*-app"]
+  demo:
+    skip: ["*"]
+    detect_patterns: ["*-example", "*-demo", "*-sample"]
+
+# 跳过的方法名（覆盖率校验时排除）
+skip_method_names:
+  - "toString"
+  - "hashCode"
+  - "equals"
+  - "clone"
+  - "finalize"
+  - "__init__"
+  - "__str__"
+  - "__repr__"
+  - "__eq__"
+  - "__hash__"
+
+# 跳过的方法前缀（无参时跳过）
+skip_method_prefixes_no_params:
+  - "get"
+  - "is"
+
+# 跳过的方法前缀（无论有无参数都跳过）
+skip_method_prefixes_any:
+  - "set"
+
+# Generic preset 不定义 architecture_sources 和 key_annotations
+# Agent 会根据实际文件内容自行判断
+
+# 覆盖率校验
+coverage_threshold: 0.8
+coverage_skip_patterns:
+  - "/test/"
+  - "/tests/"
+  - "/__tests__/"
+  - "/spec/"
+  - "/generated/"
+  - "/build/"
+  - "/dist/"
+  - "/node_modules/"
+
+# ============================================================
+# 进度监控配置
+# ============================================================
+progress:
+  heavy_docs: ["business-logic", "architecture", "data-models"]
+  light_timeout_min: 4.0
+  heavy_timeout_min: 6.0
+  spawn_timeout:
+    default: 480            # 8 min，兜底
+    source-tree-analysis: 360  # 6 min，模板化程度高
+    data-models: 480        # 8 min
+    api-contracts: 360      # 6 min
+    architecture: 600       # 10 min，输入多
+    business-logic: 720     # 12 min，最复杂
+    utils: 300              # 5 min
+    index: 300              # 5 min，依赖前序文档但自身简单
+
+# ============================================================
+# 文档章节校验规则（validate_output.py 使用）
+# ============================================================
+section_checks:
+  "business-logic.md":
+    must_have: []
+    should_have: [["错误处理", "异常处理", "错误码"]]
+  "architecture.md":
+    must_have: [["技术栈", "技术选型", "框架"]]
+    should_have: [["依赖", "依赖清单"], ["配置", "配置管理"]]
+  "data-models.md":
+    must_have: []
+    should_have: [["字段", "Field", "属性"]]
+  "index.md":
+    must_have: [["模块概览", "模块概述", "模块简介"]]
+    should_have: []
+  "source-tree-analysis.md":
+    must_have: [["目录结构", "文件树", "源码结构", "文件结构"]]
+    should_have: []
+  "api-contracts.md":
+    must_have: []
+    should_have: [["接口汇总", "接口总览", "API"]]

presets/java-spring/audit_dimensions.md

@@ -0,0 +1,228 @@
+# Java / Spring Boot 检查维度
+
+> 语言特定的自检维度，配合 `doc-quality-standard.md` 和 `doc-coverage-shared.md` 使用。
+
+## source-tree-analysis.md
+
+修复标准见 `doc-quality-standard.md` 5.7 节（完整文件树 + 每文件详解格式 + 内容深度基准）。
+
+1. 文件完整性 — 文档列出的每个文件在源码中存在
+2. 目录结构 — 目录层级、包名与实际一致
+3. 文件职责描述 — 描述与类的实际功能匹配（检查类注释、接口、继承）
+4. 文件数统计 — 文档中的计数与实际一致
+5. 新增/删除文件 — 源码变动在文档中反映
+
+## index.md
+
+修复标准见 `doc-quality-standard.md` 5.8 节（基本信息表 + 接口总览表 + 缓存策略概览表 + 文档导航 + 内容深度基准）。
+
+1. 链接有效性 — 所有 `[text](file.md)` 链接指向存在的文件
+2. 文件数/统计 — 引用的数量与实际一致
+3. 模块描述 — 概述与模块实际功能匹配
+4. 文档完整性 — 所有 .md 文件都在 index.md 中有链接
+
+## architecture.md
+
+对比源：`pom.xml`、`application.yml`/`bootstrap.yml`、`@Configuration`/`@EnableXxx` 类。
+
+1. 技术栈版本 — Spring Boot、MyBatis、中间件版本与 pom.xml 一致
+2. 依赖清单 — 无遗漏的关键依赖
+3. 分层结构 — Controller → Service → Mapper 分层与实际包结构一致
+4. 中间件配置 — Redis、Kafka、ES 等配置与 yml 一致
+5. 组件关系 — Feign、Dubbo 调用关系与 `@FeignClient`/`@DubboReference` 一致
+6. 配置项 — Nacos/yml 中的关键配置项在文档中有记录
+
+## data-models.md
+
+对比源：`domain/`、`entity/`、`dto/`、`vo/`、`param/`、`mapper/` 目录。
+
+1. 实体完整性 — 每个 Domain/Entity 类在文档中有记录
+2. 字段一致性 — 字段名、类型与源码一致（含泛型）
+3. 注解准确性 — `@TableName`、`@Column`、`@TableField`、`@JsonProperty` 与源码一致
+4. 表名映射 — 文档中的表名与 `@TableName`/`@Entity` 一致
+5. DTO/VO 覆盖 — 请求/响应 DTO、VO、Param 类在文档中有记录
+6. 枚举值 — 枚举类的所有值完整列出
+7. 继承/实现 — 继承关系、实现的接口与源码一致
+
+## api-contracts.md
+
+对比源：`controller/` 和 `api/` 目录。
+
+1. 接口完整性 — 每个 Controller/Feign 方法在文档中有记录
+2. URL 路径 — `@RequestMapping`/`@GetMapping` 等路径与文档一致
+3. HTTP 方法 — GET/POST/PUT/DELETE 与源码一致
+4. 请求参数 — `@RequestParam`、`@PathVariable`、`@RequestBody` 的参数名、类型一致
+5. 响应类型 — 返回值类型（含泛型）与文档一致
+6. 错误码 — 方法中抛出的异常/错误码在文档中有记录
+7. Feign 降级 — `@FeignClient` 的 fallback/fallbackFactory 与文档一致
+8. 权限注解 — `@PreAuthorize`、`@RequiresPermissions` 与文档一致
+
+## business-logic.md
+
+按 `doc-quality-standard.md` 第 5 节 10 项维度，额外关注以下 Java 特定注解：
+
+| 注解 | 检查点 |
+|------|--------|
+| `@Transactional` | 传播级别、回滚规则、只读标记 |
+| `@Async` | 线程池配置、返回类型 |
+| `@Scheduled`/`@XxlJob` | cron 表达式、执行频率 |
+| `@KafkaListener` | topic、groupId、并发数 |
+| `@Cacheable`/`@CacheEvict` | 缓存名、key 表达式、TTL |
+| `@SentinelResource` | 资源名、降级策略 |
+| `@Retryable`/`@CircuitBreaker` | 重试次数、熔断条件 |
+| `@Value` | 配置项 key、默认值 |
+
+额外检查维度（引用完整性与去重合规）：
+
+11. **引用完整性** — business-logic.md 中所有 `](./xxx.md` 和 `](../xxx/` 链接指向存在的文件，锚点对应的章节标题存在
+12. **去重合规** — 以下内容不应在 business-logic.md 中展开（应为引用链接，见 `doc-quality-standard.md` 5.1.1 节）：
+    - 缓存 Key 拼接规则/TTL/CAS 流程（归属 caching.md）
+    - 消息队列消息体 JSON 示例/完整消费逻辑（归属 messaging.md）
+    - DTO/VO/Entity 完整字段表（归属 data-models.md）
+    - 接口完整参数表/响应结构（归属 api-contracts.md）
+    - 检测方式：在 business-logic.md 中搜索以下模式，命中 > 3 次视为重复：
+      - `| 字段 | 类型 |`（字段表格头）
+      - Redis Key 常量（如 `POINT_ACCOUNT_BASE`、`crm:point:account:`）
+      - `max-poll-records`、`batch-size` 等中间件配置参数
+
+## 可选文档
+
+### 可选文档触发条件
+
+扫描源码时，命中以下模式则对应文档变为必需：
+
+| 文档 | 触发模式（任一命中即触发） |
+|------|------------------------|
+| messaging.md | `@KafkaListener`、`kafkaTemplate`、`KafkaProducer`、`@StreamListener`、`implements ConsumerSeekAware`、`@PulsarListener`、`@RabbitListener`、`@RocketMQMessageListener` |
+| caching.md | `RedisTemplate`、`StringRedisTemplate`、`RedisService`、`@Cacheable`、`@CacheEvict`、`redissonClient`、`RLock`、`MemcachedClient`、`CaffeineCacheManager` |
+| external-integrations.md | `RestTemplate`、`WebClient`、`OkHttpClient`、`HttpUtil`、`@FeignClient` 字段注入（本模块调用外部服务；排除本模块自身定义的 `@FeignClient` 接口，那些归 api-contracts.md） |
+
+检测命令示例：
+```shell
+# ⚠️ 推荐使用 extract_file_list 代替 grep（更精确，自动排除测试文件）：
+# python -X utf8 engine/skeleton/extract_file_list.py --skeleton {skeleton} --preset java-spring --doc-type kafka --source-cache {repo} --output /dev/null
+
+# 如果使用 grep，必须排除测试目录（避免 JUnit @Before/@After 误报为 AOP）：
+# 检测 Kafka 使用
+git -C {repo} grep -l "KafkaListener\|kafkaTemplate\|KafkaProducer" {ref} -- "src/main/**/*.java"
+
+# 检测 Redis 使用
+git -C {repo} grep -l "RedisTemplate\|StringRedisTemplate\|@Cacheable\|redissonClient" {ref} -- "src/main/**/*.java"
+
+# 检测外部 HTTP 调用
+git -C {repo} grep -l "RestTemplate\|WebClient\|OkHttpClient" {ref} -- "src/main/**/*.java"
+
+# 检测 AOP（注意：必须用 @Aspect 而非 @Before/@After，后者会误报 JUnit 注解）
+git -C {repo} grep -l "@Aspect\|@Pointcut" {ref} -- "src/main/**/*.java"
+```
+
+### messaging.md
+
+1. Topic/Queue 完整性 — 所有消息生产/消费的 topic/queue 有记录
+2. 消息体结构 — 生产者发送的对象类型与文档一致
+3. 消费者分组 — groupId/subscription 与源码一致
+4. 生产/消费关系 — 哪个类生产、哪个类消费与源码一致
+
+### caching.md
+
+1. Key/Cache 完整性 — 所有缓存操作的 key pattern/cache name 有记录
+2. TTL — 过期时间与源码一致
+3. 数据类型 — 数据结构类型与源码一致
+
+### external-integrations.md
+
+1. 集成方完整性 — 所有外部 HTTP/SDK 调用有记录
+2. 接口地址 — URL/配置项与源码一致
+3. 认证方式 — Token/签名/OAuth 与源码一致
+
+### enums-and-constants.md
+
+对比源：`enum/`、`constant/`、`enums/` 目录及散布在各包中的枚举/常量类。
+
+1. 枚举完整性 — 每个枚举类在文档中有记录
+2. 枚举值准确性 — 所有枚举值完整列出，无遗漏
+3. 常量值正确性 — 常量的实际值与文档一致（数值验证）
+4. 使用上下文 — 枚举/常量的业务含义与源码注释/使用场景一致
+5. 静态方法覆盖 — 枚举类的静态方法（业务规则载体）在文档中有记录
+
+### database-access.md
+
+对比源：`mapper/`、`dao/`、`repository/` 目录，MyBatis XML 映射文件。
+
+1. Mapper 完整性 — 每个 Mapper/DAO 接口在文档中有记录
+2. SQL 语义准确性 — 查询方法的 WHERE 条件、JOIN 关系、排序规则与源码/XML 一致
+3. 事务边界 — `@Transactional` 的传播行为、隔离级别、回滚条件与源码一致
+4. 分页参数 — 分页实现方式（PageHelper/MyBatis-Plus）及参数与源码一致
+5. 批量操作 — 批量大小、超时时间与源码配置一致
+6. 表名映射 — 操作的表名与实际 SQL/注解一致
+
+### scheduled-tasks.md
+
+对比源：`@Scheduled`、`@XxlJob`、`@EnableScheduling` 相关类。
+
+1. 任务完整性 — 所有定时任务/Job 在文档中有记录
+2. Cron 表达式 — 调度表达式与源码/配置一致
+3. 执行频率 — 文档描述的频率与 cron/fixedRate/fixedDelay 一致
+4. 幂等性说明 — 幂等保证机制（分布式锁/状态机/版本号）与源码一致
+5. 异常处理 — 任务失败后的行为（重试/告警/跳过）与源码一致
+6. 分片策略 — XxlJob 分片参数、路由策略与配置一致
+
+### error-handling.md
+
+对比源：`@ControllerAdvice`、`@ExceptionHandler`、自定义异常类。
+
+1. 异常类完整性 — 所有自定义异常类在文档中有记录
+2. 异常层次结构 — 从基类到具体异常的继承链与源码一致
+3. 错误码映射 — 错误码 → 异常类 → HTTP 状态码的映射与源码一致
+4. 全局处理器逻辑 — `@ExceptionHandler` 的匹配规则、处理步骤、返回格式与源码一致
+5. 用户提示信息 — 错误码对应的用户可见消息与源码一致
+
+### security.md
+
+对比源：`SecurityConfig`、`Filter`、`@PreAuthorize`、Token 处理类。
+
+1. 认证流程完整性 — 从请求进入到身份确认的每一步与源码一致
+2. Token 机制 — 解析/验证/刷新逻辑与源码一致
+3. 权限模型 — RBAC/ABAC 角色-权限映射与源码/配置一致
+4. 过滤器链顺序 — Filter 执行顺序、职责、放行/拦截条件与源码一致
+5. 权限标识 — `@PreAuthorize`、`@RequiresPermissions` 的权限字符串与源码一致
+
+### aop-and-interceptors.md
+
+对比源：`@Aspect` 类、`HandlerInterceptor` 实现、`WebMvcConfigurer`。
+
+1. 切面完整性 — 所有 `@Aspect` 类在文档中有记录
+2. 切点表达式 — execution/annotation/within 表达式与源码一致
+3. 执行顺序 — `@Order` 值或 `Ordered.getOrder()` 与源码一致
+4. 拦截器链 — 注册顺序、匹配路径与 `WebMvcConfigurer` 配置一致
+5. 通知类型 — @Before/@After/@Around 的逻辑与源码一致
+
+### observability.md
+
+对比源：Micrometer 指标注册、日志配置、健康检查端点。
+
+1. 指标完整性 — 所有自定义 Counter/Timer/Gauge 在文档中有记录
+2. 指标名称 — metric name 与源码中 `MeterRegistry` 注册的一致
+3. 告警阈值 — 阈值配置与源码/配置文件一致
+4. 日志配置 — 日志级别、格式、输出目标与 logback/log4j 配置一致
+5. 健康检查 — 自定义 HealthIndicator 与源码一致
+
+### async-and-events.md
+
+对比源：`@Async` 方法、`@EventListener`、`ApplicationEvent` 子类、线程池配置。
+
+1. 线程池配置 — 核心线程数、最大线程数、队列容量与源码一致
+2. 异步方法完整性 — 所有 `@Async` 方法在文档中有记录
+3. 事件发布/订阅 — 发布者、订阅者、事件体结构与源码一致
+4. 异步失败处理 — 异常后的行为（吞掉/日志/回调/补偿）与源码一致
+5. 事件执行时机 — `@TransactionalEventListener` 的 phase 与源码一致
+
+### utils.md
+
+对比源：`util/`、`utils/`、`helper/`、`common/` 目录。
+
+1. 工具类完整性 — 有复杂逻辑的工具方法在文档中有记录
+2. 方法签名准确性 — 参数类型、返回类型与源码一致
+3. 边界行为 — null 处理、精度丢失、时区问题等隐式行为与源码一致
+4. 线程安全性 — 并发相关设计（如有）与源码一致
+5. 使用上下文 — 高频调用方法的典型调用场景与实际使用一致

presets/java-spring/audit_dimensions.yaml

@@ -0,0 +1,203 @@
+# Audit dimensions configuration for java-spring preset
+# Loaded by AuditDocsStep to determine check criteria per doc type.
+# Each dimension defines: name, description, severity, required.
+#
+# severity: error | warning | info
+# required: true → failure is an error; false → failure is a warning
+
+version: "1.0"
+
+dimensions:
+  source-tree-analysis:
+    - name: file_completeness
+      description: "骨架中所有文件是否在文档中列出"
+      severity: error
+      required: true
+    - name: directory_structure
+      description: "是否按 controller/service/dao/config 等分层组织"
+      severity: warning
+      required: false
+    - name: file_responsibility
+      description: "每文件是否有一句话功能说明"
+      severity: warning
+      required: true
+    - name: new_deleted_files
+      description: "源码有但文档无/文档有但源码无"
+      severity: error
+      required: true
+
+  data-models:
+    - name: entity_completeness
+      description: "所有实体类是否在文档中列出"
+      severity: error
+      required: true
+    - name: field_consistency
+      description: "字段名、类型、说明是否与源码一致"
+      severity: error
+      required: true
+    - name: annotation_accuracy
+      description: "@TableName/@Column 等注解是否准确"
+      severity: warning
+      required: false
+    - name: dto_vo_coverage
+      description: "DTO/VO 类是否覆盖"
+      severity: warning
+      required: true
+    - name: enum_values
+      description: "枚举值是否完整准确"
+      severity: error
+      required: true
+    - name: inheritance
+      description: "继承关系是否标注"
+      severity: info
+      required: false
+
+  api-contracts:
+    - name: interface_completeness
+      description: "所有接口是否列出"
+      severity: error
+      required: true
+    - name: url_path
+      description: "URL 路径是否准确"
+      severity: error
+      required: true
+    - name: http_method
+      description: "HTTP 方法是否正确"
+      severity: error
+      required: true
+    - name: request_params
+      description: "请求参数是否与源码一致"
+      severity: error
+      required: true
+    - name: response_type
+      description: "响应类型是否准确"
+      severity: warning
+      required: true
+    - name: error_codes
+      description: "错误码是否列出"
+      severity: warning
+      required: false
+
+  business-logic:
+    - name: method_purpose
+      description: "方法用途描述是否准确"
+      severity: error
+      required: true
+    - name: core_logic_flow
+      description: "核心逻辑流程是否完整"
+      severity: error
+      required: true
+    - name: branch_conditions
+      description: "分支条件是否完整描述"
+      severity: warning
+      required: true
+    - name: exception_handling
+      description: "异常处理是否标注"
+      severity: warning
+      required: false
+    - name: reference_integrity
+      description: "跨文档引用链接是否有效"
+      severity: warning
+      required: true
+    - name: dedup_compliance
+      description: "是否有与其他文档重复的内容"
+      severity: info
+      required: false
+
+  architecture:
+    - name: tech_stack_versions
+      description: "框架版本是否与 pom.xml 一致"
+      severity: error
+      required: true
+    - name: middleware_config
+      description: "中间件配置是否有具体 key/topic/index"
+      severity: warning
+      required: true
+    - name: layer_structure
+      description: "分层架构描述是否准确"
+      severity: warning
+      required: false
+    - name: config_items
+      description: "关键配置项是否列出"
+      severity: warning
+      required: false
+
+  caching:
+    - name: key_completeness
+      description: "所有 Redis Key 是否列出"
+      severity: error
+      required: true
+    - name: ttl_accuracy
+      description: "TTL 值是否与源码一致"
+      severity: error
+      required: true
+    - name: operation_type
+      description: "操作类型（读/写/删）是否标注"
+      severity: warning
+      required: false
+
+  messaging:
+    - name: topic_completeness
+      description: "所有 Topic 是否列出"
+      severity: error
+      required: true
+    - name: consumer_producer
+      description: "消费者/生产者是否标注"
+      severity: warning
+      required: true
+    - name: message_format
+      description: "消息体格式是否描述"
+      severity: warning
+      required: false
+
+  database-access:
+    - name: mapper_completeness
+      description: "所有 Mapper/Repository 是否列出"
+      severity: error
+      required: true
+    - name: sql_accuracy
+      description: "SQL 操作描述是否准确"
+      severity: warning
+      required: true
+    - name: transaction_boundary
+      description: "事务边界是否标注"
+      severity: warning
+      required: false
+
+  enums-and-constants:
+    - name: enum_completeness
+      description: "所有枚举类是否列出"
+      severity: error
+      required: true
+    - name: value_accuracy
+      description: "枚举值是否与源码一致"
+      severity: error
+      required: true
+    - name: constant_coverage
+      description: "关键常量是否覆盖"
+      severity: warning
+      required: false
+
+  external-integrations:
+    - name: service_completeness
+      description: "所有外部服务调用是否列出"
+      severity: error
+      required: true
+    - name: url_accuracy
+      description: "调用地址/接口是否准确"
+      severity: error
+      required: true
+    - name: error_handling
+      description: "异常处理/降级策略是否描述"
+      severity: warning
+      required: false
+
+  utils:
+    - name: class_completeness
+      description: "工具类是否列出"
+      severity: warning
+      required: true
+    - name: method_purpose
+      description: "方法用途是否描述"
+      severity: warning
+      required: false