source-kb 0.2.2__py3-none-any.whl

presets/java-spring/preset.yaml

@@ -0,0 +1,341 @@
+# Java / Spring Boot Preset
+# 适用于 Spring Boot 微服务项目
+
+name: "Java / Spring Boot"
+language: "java"
+file_extensions: [".java"]
+test_patterns: ["/test/", "/tests/"]
+generated_patterns: ["/generated/", "/proto/", "/target/"]
+
+# ============================================================
+# 解析器配置
+# backend: auto | jqassistant | treesitter | regex
+#   auto（默认）：按可用性自动选择 jqassistant → treesitter → regex
+#   jqassistant：优先使用 jQAssistant 字节码分析，降级到 treesitter → regex
+#   treesitter：强制使用 tree-sitter AST 解析
+#   regex：强制使用 preset 自带正则解析器
+# ============================================================
+parser:
+  backend: "auto"
+  jqassistant:
+    store_dir: ".jqassistant/store"
+    rules_dir: ".jqassistant/rules"
+    classes_dir: null  # 自动检测 target/classes 或 build/classes/java/main
+
+# ============================================================
+# 构建配置（可选）
+# 启用后，在源码拉取阶段自动执行 Maven 编译，生成 .class 文件供 jQAssistant 使用。
+# 不启用时，jQAssistant 会自动降级到 tree-sitter。
+# ============================================================
+build:
+  enabled: false                    # 设为 true 启用自动构建
+  tool: "maven"                     # 构建工具：maven | gradle
+  command: "mvn compile -DskipTests -q"  # 构建命令
+  timeout: 300                      # 超时秒数
+  settings_file: null               # Maven settings.xml 路径（可选，如 "./settings.xml"）
+  profiles: []                      # 激活的 Maven profiles（可选）
+
+# ============================================================
+# 文件分类规则（唯一规则源，所有脚本从此读取）
+# 匹配优先级：class_type > class_annotations > method_annotations > field_types > patterns（兜底）
+# 排除机制：exclude_if 条件满足时跳过该分类
+# 优先级机制：同一 affects 目标下，高 priority 分类排斥低 priority 分类
+#
+# patterns 语法说明：
+#   - 以 * 开头的模式（如 "*.yml"）：glob 匹配，仅匹配文件名（不含路径）
+#   - 其他模式（如 "/service/"）：子串包含匹配，匹配完整路径（大小写不敏感）
+#   - 示例：
+#     "/controller/"  → 匹配 com/example/controller/OrderController.java ✓
+#     "*.yaml"        → 匹配 application.yaml ✓，但不匹配 src/main/resources/application.yaml 的路径部分
+#     "/api/"         → 匹配 com/example/api/v1/UserApi.java ✓
+# ============================================================
+file_classification:
+  enum:
+    class_type: "enum"
+    affects: ["enums-and-constants.md"]
+  controller:
+    class_annotations: ["@RestController", "@Controller"]
+    method_annotations: ["@RequestMapping", "@GetMapping", "@PostMapping", "@PutMapping", "@DeleteMapping", "@PatchMapping"]
+    patterns: ["/controller/", "/api/"]
+    affects: ["api-contracts.md", "business-logic.md"]
+  service:
+    class_annotations: ["@Service"]
+    patterns: ["/service/", "/biz/"]
+    affects: ["business-logic.md"]
+  config:
+    class_annotations: ["@Configuration"]
+    patterns: ["/config/"]
+    affects: ["architecture.md"]
+  model:
+    class_annotations: ["@Entity", "@Table", "@TableName", "@Data"]
+    exclude_if:
+      has_annotation: ["@Configuration", "@Service", "@Component", "@Aspect", "@RestController", "@Controller"]
+      path_contains: ["/config/", "/service/", "/aspect/", "/interceptor/"]
+    patterns: ["/domain/", "/entity/", "/dto/", "/vo/", "/param/", "/bo/", "/req/", "/resp/", "/request/", "/response/", "/model/", "/pojo/"]
+    affects: ["data-models.md"]
+  mapper:
+    class_annotations: ["@Mapper", "@Repository"]
+    patterns: ["/dao/", "/mapper/", "/repository/"]
+    exclude_if:
+      matched_by: ["cache"]
+    priority: 5
+    affects: ["database-access.md"]
+  kafka:
+    method_annotations: ["@KafkaListener", "@SendTo"]
+    patterns: ["/consumer/", "/producer/", "/listener/", "/mq/"]
+    affects: ["messaging.md", "business-logic.md"]
+  feign:
+    class_annotations: ["@FeignClient"]
+    annotation_has_url: false
+    url_annotation_name: "@FeignClient"
+    affects: ["api-contracts.md"]
+  feign-external:
+    class_annotations: ["@FeignClient"]
+    annotation_has_url: true
+    url_annotation_name: "@FeignClient"
+    affects: ["external-integrations.md"]
+  cache:
+    method_annotations: ["@Cacheable", "@CacheEvict", "@CachePut"]
+    field_types: ["RedisTemplate", "StringRedisTemplate", "RedissonClient", "ValueOperations", "HashOperations", "ListOperations", "SetOperations", "ZSetOperations", "RedisService", "RedisUtil", "RedisHelper", "CacheService", "CacheUtil", "RLock", "RBucket", "RMap"]
+    patterns: ["/redis/", "/cache/"]
+    priority: 10
+    affects: ["caching.md"]
+  scheduled:
+    class_annotations: ["@EnableScheduling"]
+    method_annotations: ["@Scheduled", "@XxlJob", "@QuartzJob"]
+    patterns: ["/job/", "/task/", "/schedule/", "/cron/"]
+    affects: ["scheduled-tasks.md"]
+  error-handling:
+    class_annotations: ["@ControllerAdvice", "@RestControllerAdvice"]
+    method_annotations: ["@ExceptionHandler"]
+    patterns: ["/exception/", "/error/"]
+    affects: ["error-handling.md"]
+  security:
+    class_annotations: ["@EnableWebSecurity", "@EnableGlobalMethodSecurity", "@EnableMethodSecurity"]
+    method_annotations: ["@PreAuthorize", "@Secured", "@RolesAllowed"]
+    patterns: ["/security/", "/auth/", "/filter/"]
+    affects: ["security.md"]
+  async-events:
+    method_annotations: ["@Async", "@EventListener", "@TransactionalEventListener"]
+    patterns: ["/event/", "/async/"]
+    exclude_if:
+      matched_by: ["kafka"]
+      path_contains: ["/consumer/", "/producer/", "/mq/"]
+    affects: ["async-and-events.md", "business-logic.md"]
+  aop:
+    class_annotations: ["@Aspect"]
+    method_annotations: ["@Around", "@Before", "@After", "@AfterReturning", "@AfterThrowing"]
+    patterns: ["/aspect/", "/interceptor/", "/aop/"]
+    affects: ["aop-and-interceptors.md"]
+  observability:
+    class_annotations: ["@Endpoint", "@RestControllerEndpoint"]
+    method_annotations: ["@Counted", "@Timed", "@Observed"]
+    field_types: ["MeterRegistry", "Counter", "Timer", "Gauge", "DistributionSummary"]
+    patterns: ["/monitor/", "/metrics/", "/health/", "/actuator/", "/observability/", "/tracing/"]
+    affects: ["observability.md"]
+  constant:
+    patterns: ["/constant/", "/constants/"]
+    affects: ["enums-and-constants.md"]
+  util:
+    patterns: ["/util/", "/utils/", "/helper/", "/helpers/", "/tool/", "/tools/"]
+    affects: ["utils.md"]
+  resource:
+    patterns: ["*.yml", "*.yaml", "*.properties", "*.xml", "pom.xml", "build.gradle"]
+    affects: ["architecture.md"]
+  structure:
+    patterns: ["*.java"]
+    affects: ["source-tree-analysis.md", "index.md"]
+    trigger: "add-delete-only"
+
+# ============================================================
+# 模块类型 → 跳过规则
+# ============================================================
+module_types:
+  service:
+    skip: []
+  api-contract:
+    skip: ["business-logic.md"]
+    detect_patterns: ["*-api", "*/api/"]
+  base-lib:
+    skip: ["api-contracts.md"]
+    detect_patterns: ["*-base", "*-common", "*-core"]
+  frontend:
+    skip: ["source-tree-analysis.md", "api-contracts.md"]
+    detect_patterns: ["*-web", "*-ui", "*-frontend"]
+  demo:
+    skip: ["*"]
+    detect_patterns: ["*-demo", "*-example", "*-sample", "*-third"]
+
+# ============================================================
+# 架构检查源
+# =========================================================
+architecture_sources:
+  dependencies: "pom.xml"
+  config_files:
+    - "src/main/resources/application.yml"
+    - "src/main/resources/application.yaml"
+    - "src/main/resources/bootstrap.yml"
+    - "src/main/resources/bootstrap.yaml"
+  annotation_patterns:
+    feign: "@FeignClient"
+    dubbo: "@DubboReference"
+    config: "@Configuration"
+    enable: "@Enable"
+
+# ============================================================
+# 自检关键注解
+# ============================================================
+key_annotations:
+  - "Transactional"
+  - "Override"
+  - "Async"
+  - "Scheduled"
+  - "KafkaListener"
+  - "XxlJob"
+  - "PostConstruct"
+  - "PreDestroy"
+  - "EventListener"
+  - "TransactionalEventListener"
+  - "Value"
+  - "RefreshScope"
+  - "SentinelResource"
+  - "Cacheable"
+  - "CacheEvict"
+  - "Retryable"
+  - "CircuitBreaker"
+  - "Aspect"
+  - "Around"
+  - "Before"
+  - "After"
+
+# ============================================================
+# 方法跳过规则（唯一规则源，coverage_check 等脚本从此读取）
+# ============================================================
+skip_method_names:
+  - "toString"
+  - "hashCode"
+  - "equals"
+  - "clone"
+  - "finalize"
+  - "canEqual"
+  - "builder"
+  - "of"
+  - "values"
+  - "valueOf"
+
+skip_method_prefixes_no_params:
+  - "get"
+  - "is"
+
+skip_method_prefixes_any:
+  - "set"
+
+# ============================================================
+# 覆盖率配置
+# ============================================================
+coverage_threshold: 0.8
+
+# ============================================================
+# 覆盖率统计排除路径（非业务文件，不计入覆盖率）
+# ============================================================
+coverage_skip_patterns:
+  - "/config/"
+  - "/util/"
+  - "/constant/"
+  - "/annotation/"
+  - "/exception/"
+  - "/test/"
+  - "/enums/"
+
+# ============================================================
+# 进度监控配置
+# ============================================================
+progress:
+  heavy_docs: ["business-logic", "architecture", "data-models"]
+  light_timeout_min: 5.0
+  heavy_timeout_min: 7.5
+  spawn_timeout:
+    default: 600            # 10 min，兜底
+    source-tree-analysis: 480  # 8 min，模板化程度高
+    enums-and-constants: 360   # 6 min，结构简单
+    data-models: 600        # 10 min
+    api-contracts: 480      # 8 min
+    architecture: 720       # 12 min，输入多（config+pom+yaml）
+    business-logic: 900     # 15 min，最复杂
+    messaging: 600              # 10 min
+    caching: 480         # 8 min
+    scheduled-tasks: 480    # 8 min
+    error-handling: 360     # 6 min，结构清晰
+    security: 480           # 8 min
+    async-and-events: 480   # 8 min，需追踪事件发布/订阅关系
+    aop-and-interceptors: 360  # 6 min，结构清晰
+    observability: 480      # 8 min，需扫描指标注解和配置
+    database-access: 600    # 10 min，SQL 映射分析
+    utils: 360              # 6 min
+    index: 360              # 6 min，依赖前序文档但自身简单
+
+# ============================================================
+# 文档章节校验规则（validate_output.py 使用）
+# must_have: 必须存在的章节关键词（缺失报 error）
+# should_have: 建议存在的章节关键词（缺失报 warning）
+# 每项可以是字符串或字符串列表（列表表示任一匹配即可）
+# ============================================================
+section_checks:
+  "business-logic.md":
+    must_have: []
+    should_have: [["并发控制", "分布式锁", "锁", "并发"]]
+  "architecture.md":
+    must_have: [["技术栈", "技术选型", "框架", "技术栈概览"]]
+    should_have: [["依赖", "Maven", "pom", "依赖清单", "核心依赖", "技术栈概览"], ["中间件", "Redis", "Kafka", "缓存", "中间件集成"], ["配置", "application", "配置管理", "配置项"]]
+  "data-models.md":
+    must_have: []
+    should_have: []
+  "index.md":
+    must_have: [["模块概览", "模块概述", "模块简介", "模块索引", "基本信息", "模块定位"]]
+    should_have: [["文档导航", "导航", "快速检索"], ["接口总览", "接口概览", "API", "核心业务流程", "业务流程速览"]]
+  "source-tree-analysis.md":
+    must_have: [["目录结构", "文件树", "源码结构", "文件结构", "包结构", "包结构总览"]]
+    should_have: []
+  "api-contracts.md":
+    must_have: []
+    should_have: [["接口汇总", "接口总览", "API 汇总", "API 总览"]]
+  "caching.md":
+    must_have: [["Key", "Cache", "缓存", "Key Pattern", "Cache Name"]]
+    should_have: [["TTL", "过期", "缓存策略"]]
+  "messaging.md":
+    must_have: [["Topic", "topic", "Queue", "queue"]]
+    should_have: [["消费", "Consumer", "生产", "Producer"]]
+  "database-access.md":
+    must_have: [["Mapper", "Repository", "DAO", "数据访问"]]
+    should_have: []
+  "scheduled-tasks.md":
+    must_have: [["任务列表", "定时任务", "Job 清单"]]
+    should_have: [["执行频率", "cron", "调度周期"], ["幂等", "重试", "容错"]]
+  "error-handling.md":
+    must_have: [["异常层次", "异常体系", "Exception"]]
+    should_have: [["错误码", "ErrorCode", "状态码"], ["全局处理", "ControllerAdvice", "统一异常"]]
+  "security.md":
+    must_have: [["认证", "鉴权", "Authentication"]]
+    should_have: [["权限模型", "RBAC", "角色"], ["过滤器", "Filter", "拦截"]]
+  "async-and-events.md":
+    must_have: [["异步方法", "@Async", "异步处理", "异步"]]
+    should_have: [["事件", "Event", "EventListener"], ["线程池", "ThreadPool", "Executor"]]
+  "aop-and-interceptors.md":
+    must_have: [["切面", "Aspect", "AOP"]]
+    should_have: [["切点", "Pointcut", "execution"], ["拦截器", "Interceptor", "HandlerInterceptor"]]
+  "external-integrations.md":
+    must_have: [["集成", "Feign", "外部", "调用"]]
+    should_have: []
+  "utils.md":
+    must_have: []
+    should_have: []
+
+# ============================================================
+# Audit configuration
+# ============================================================
+audit:
+  scale_thresholds:
+    single_agent_kb: 50        # Below this (KB): single-agent strategy
+    skeleton_kb: 80            # Below this (KB): single-agent+skeleton; above: multi-agent
+  max_tokens: 8192             # Max tokens for audit LLM call
+  doc_truncate_chars: 50000    # Truncate doc content beyond this for audit prompt

presets/java-spring/templates/README.md

@@ -0,0 +1,34 @@
+# Java Spring Preset Templates
+
+This directory contains sub-agent prompt templates specific to the `java-spring` preset.
+
+## Template naming convention
+
+Each template is referenced by the `template` field in `doc_types.yaml`:
+
+```yaml
+doc_types:
+  caching:
+    template: "subagent-caching.md"    # → presets/java-spring/templates/subagent-caching.md
+```
+
+## Template search order
+
+When rendering a prompt, the system searches for templates in this order:
+
+1. `presets/{preset}/templates/{template_name}` — preset-specific (this directory)
+2. `skill/kb-init/templates/{template_name}` — generic fallback
+3. `skills/kb-init/templates/{template_name}` — legacy fallback
+
+## Shared components
+
+Templates can reference shared execution guidance via the `{execution_guidance}` placeholder,
+which is resolved from:
+- `skill/kb-init/templates/core/readwrite.md` (Agent mode)
+- `skill/kb-init/templates/core/output-only.md` (CLI mode)
+
+## Adding a new doc_type
+
+1. Add entry to `doc_types.yaml` with `template: "subagent-{name}.md"`
+2. Create `presets/java-spring/templates/subagent-{name}.md`
+3. No code changes needed — the system discovers templates from config

presets/java-spring/templates/audit-system.md

@@ -0,0 +1,15 @@
+You are a knowledge base quality auditor. Compare document content against the source code skeleton and identify inconsistencies.
+
+Output format: JSON array, each element contains:
+- dimension: audit dimension name
+- status: "pass" or "fail"
+- detail: issue description (required when status=fail)
+- fix: suggested fix content (optional)
+
+Audit dimensions:
+- completeness: classes/methods/fields in skeleton covered in document
+- accuracy: document descriptions match source code
+- freshness: no outdated content (source deleted/renamed but doc not updated)
+- reference_integrity: cross-document reference links are valid
+
+Output JSON only, no other text.

presets/java-spring/templates/subagent-aop.md

@@ -0,0 +1,105 @@
+# 任务：生成 {module_name} 模块的 aop-and-interceptors.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 切点表达式、执行顺序、拦截路径必须从源码验证
+2. **切面执行顺序必须明确** — @Order 值或实现 Ordered 接口的 getOrder() 返回值
+3. **切点表达式必须完整** — execution/annotation/within 的完整表达式，不能只写"拦截 Service 层"
+4. **拦截器链必须有序** — 每个拦截器的注册顺序、匹配路径、preHandle/postHandle 逻辑
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/aop-and-interceptors.md`
+
+## 需要读取的源码文件
+
+根据以下文件清单读取源码文件进行分析：
+
+{file_list}
+
+## 文件读取说明
+
+你需要：
+1. 逐个读取上述文件清单中的源码文件
+2. 分析文件内容，提取所需信息
+3. 基于原始源码生成文档，禁止编造
+4. 验证所有配置参数和数值
+
+## 内容组织
+
+### 1. 切面总览
+
+```markdown
+| 序号 | 切面类 | @Order | 切面类型 | 职责 | 影响范围 |
+|------|--------|--------|---------|------|---------|
+| 1 | LogAspect | 1 | @Around | 接口日志 | Controller 层 |
+```
+
+### 2. 逐切面详解（每个切面独立小节）
+
+每个切面必须包含：
+
+- **切面类名**：完整类名
+- **执行顺序**：@Order 值（数值越小越先执行）
+- **切面类型**：@Around / @Before / @After / @AfterReturning / @AfterThrowing
+- **切点表达式**：完整 @Pointcut 定义
+  ```java
+  @Pointcut("execution(* com.example.controller..*.*(..))")
+  ```
+- **通知逻辑**：编号步骤，从进入到退出的每一步
+  - @Around：proceed 前后分别做什么
+  - @Before：前置校验/日志/上下文设置
+  - @After：清理/日志
+  - @AfterReturning：结果处理/缓存写入
+  - @AfterThrowing：异常记录/告警/补偿
+- **注入依赖**：切面中使用的 Service/Repository
+- **性能影响**：是否有耗时操作（远程调用、IO）
+- **条件控制**（如有）：开关配置、环境限制
+
+### 3. 拦截器链（HandlerInterceptor）
+
+```markdown
+| 顺序 | 拦截器类 | 匹配路径 | 排除路径 | 职责 |
+|------|---------|---------|---------|------|
+```
+
+每个拦截器必须包含：
+- **注册方式**：WebMvcConfigurer.addInterceptors 中的注册代码
+- **匹配路径**：addPathPatterns
+- **排除路径**：excludePathPatterns
+- **preHandle 逻辑**：编号步骤 + 返回 true/false 的条件
+- **postHandle 逻辑**（如有）
+- **afterCompletion 逻辑**（如有）
+
+### 4. 切面执行顺序图
+
+ASCII 图展示请求经过各切面/拦截器的完整链路：
+```
+Request → Filter → Interceptor.preHandle → Aspect(@Around-before)
+       → Controller → Aspect(@Around-after) → Interceptor.postHandle → Response
+```
+
+### 5. 自定义注解驱动的切面（如有）
+
+- 注解定义（@Target, @Retention）
+- 切面如何匹配该注解
+- 使用示例
+
+## 完成后自检清单
+
+- [ ] 每个切面有完整切点表达式
+- [ ] 执行顺序（@Order）已标注
+- [ 径已列出
+- [ ] 切面执行顺序图已画
+- [ ] 数值从源码验证

presets/java-spring/templates/subagent-api.md

@@ -0,0 +1,63 @@
+# 任务：生成 {module_name} 模块的 api-contracts.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 接口路径、参数、响应结构必须从源码提取
+2. **每个接口必须完整** — HTTP 方法+路径、请求参数表、响应类型、错误码、Sentinel 资源名
+3. **VO 字段来源规则** — 本模块有定义→写类名+关键字段摘要（3-5 个）+ 引用 data-models.md；外部 JAR→标注来源
+4. **只写接口契约，不写业务逻辑** — 业务流程归 business-logic.md
+
+## 本文档不覆盖的内容
+
+- 接口背后的业务逻辑和调用链（归 business-logic.md）
+- VO/DTO 的完整字段定义（归 data-models.md）
+- 枚举值的完整列表（归 enums-and-constants.md，本文档只引用）
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/api-contracts.md`
+
+## 需要读取的源码文件
+
+{file_list}
+
+## 内容组织
+
+按 Controller 分大章节（外部接口 / 内部接口），每个接口独立小节。
+
+### 每个接口必须包含
+
+| # | 内容 | 必需 |
+|---|------|------|
+| 1 | HTTP 方法 + 路径 | ✅ |
+| 2 | 请求参数表（参数名、位置、类型、必填、校验规则） | ✅ |
+| 3 | 响应类型 + 关键字段摘要（3-5 个），引用 data-models.md | ✅ |
+| 4 | 错误码（该接口可能返回的错误码 + 触发条件） | ✅ |
+| 5 | Sentinel 资源名 / 限流配置 | 有则写 |
+| 6 | 响应 JSON 示例 | 复杂接口写，简单 CRUD 不需要 |
+
+### 文档末尾
+
+1. **统一响应结构**：`Result<T>` 的 JSON 示例 + 字段说明
+2. **接口总览表**：所有接口的 HTTP 方法、URL、说明、类型（外部/内部）
+
+> 注意：错误码完整列表归 enums-and-constants.md，本文档只在每个接口下列出该接口特有的错误码。
+> 枚举值定义归 enums-and-constants.md，本文档不重复。
+
+## 完成后自检清单
+
+- [ ] 每个接口有完整的请求参数和响应类型
+- [ ] VO 字段用摘要 + 引用，未完整展开
+- [ ] 无枚举值定义章节（已归 enums-and-constants.md）
+- [ ] 末尾有统一响应结构和接口总览表

presets/java-spring/templates/subagent-architecture.md

@@ -0,0 +1,111 @@
+# 任务：生成 {module_name} 模块的 architecture.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 所有内容必须有源码出处，无法确认时写 `⚠️ 待验证`
+2. **数值验证铁律** — 线程池参数、连接池参数、超时配置 → 必须 Read 源码确认
+3. **写架构决策，不写配置清单** — 重点是"为什么这样设计"和"组件如何协作"，不是配置项的机械罗列
+4. **中间件只写策略概述** — Redis/Kafka/ES 的详细配置归各专项文档，本文档只写架构层面的策略选择和集成方式
+5. **禁止越权** — 不创建其他文档文件
+
+## 本文档不覆盖的内容
+
+- 缓存 Key 的完整定义和 TTL（归 caching.md）
+- 消息队列 Topic/Consumer 的详细配置（归 messaging.md）
+- Feign 接口的方法级细节（归 external-integrations.md）
+- 业务逻辑流程（归 business-logic.md）
+- pom.xml 依赖的完整列表（低价值，直接看 pom.xml）
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 源码缓存目录：`{source_cache_path}`
+- 输出文件：`{output_path}/architecture.md`
+
+## 需要读取的源码文件
+
+{file_list}
+
+## 必须包含的章节
+
+### 1. 整体架构（必须）
+ASCII 分层架构图（从 HTTP 入口到数据存储），标注每层核心类名和关键中间件。
+
+### 2. 技术栈概览（必须）
+表格：核心框架和中间件的版本号。只列关键组件（10-15 项），不需要列出所有 Maven 依赖。
+
+### 3. 分层职责（必须）
+每层 2-3 行说明职责、核心类、关键注解。不需要列出每个类。
+
+### 4. 架构模式与设计决策（必须，本文档最重要的章节）
+
+从源码提炼设计选择，每个决策用以下格式：
+
+```markdown
+#### 💡 [决策名称]
+- **选择**：采用了什么方案
+- **原因**：为什么这样选（从代码结构/注释/配置推断）
+- **权衡**：有什么代价或风险
+```
+
+常见的设计决策维度：
+- 状态机设计（状态流转图 + 转换条件）
+- 幂等策略（接口级/业务级/消费者级）
+- 并发模型（线程池配置 + 异步边界）
+- 数据一致性方案（最终一致/强一致/补偿）
+- 缓存策略选择（Cache-Aside/Write-Through/Write-Behind）
+
+### 5. 中间件集成概述（必须）
+
+每种中间件 3-5 行概述集成方式和策略选择，详细内容引用专项文档：
+
+- **Redis**：使用方式（缓存/分布式锁/消息）、客户端类型、连接池概况 → `详见 [caching.md](./caching.md)`
+- **Kafka**：集群数量、生产/消费模式概述 → `详见 [messaging.md](./messaging.md)`
+- **数据库**：连接池类型、读写分离策略、ORM 框架
+- **ES**（有则写）：索引策略、同步方式
+
+### 6. 配置管理（必须）
+
+只列动态配置（Nacos 热更新的配置项），静态配置不需要列出：
+
+| 配置项 | 类型 | 默认值 | 说明 | 热更新 |
+|--------|------|--------|------|--------|
+
+### 7. 线程模型（有自定义线程池时必须）
+
+| 线程池 Bean | 核心/最大 | 队列类型/容量 | 拒绝策略 | 用途 |
+|------------|----------|-------------|---------|------|
+
+⚠️ 标注无界队列的 OOM 风险。
+
+### 8. 部署架构（有 Dockerfile 时写）
+Docker 基础镜像、JVM 参数、健康检查。2-3 行即可。
+
+### 9. 韧性设计（有 Sentinel/Hystrix/Resilience4j 时必须）
+
+从源码中的限流/熔断/降级注解和配置提取：
+
+| 维度 | 策略 | 配置来源 | 关键参数 |
+|------|------|---------|---------|
+| 限流 | Sentinel QPS / 线程数 | @SentinelResource / dashboard | 阈值、降级方法 |
+| 熔断 | 异常比例 / 慢调用比例 | 配置中心 / 代码 | 时间窗口、恢复策略 |
+| 降级 | fallback 方法 | @SentinelResource / @HystrixCommand | 降级逻辑摘要 |
+| 重试 | Spring Retry / 自定义 | @Retryable / 代码 | 次数、间隔、退避策略 |
+
+⚠️ 只列出源码中实际存在的韧性机制，不要编造。无相关注解/配置则跳过本章节。
+
+## 完成后自检清单
+
+- [ ] 有分层架构图
+- [ ] 架构模式与设计决策章节有实质内容（不是空话）
+- [ ] 中间件只写策略概述 + 引用链接，未展开配置细节
+- [ ] 无 pom.xml 依赖完整列表
+- [ ] 所有数值从源码验证