source-kb 0.2.2__py3-none-any.whl

presets/java-spring/templates/subagent-error-handling.md

@@ -0,0 +1,91 @@
+# 任务：生成 {module_name} 模块的 error-handling.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 异常类名、错误码、HTTP 状态码必须从源码验证
+2. **异常层次必须完整** — 从基类到具体异常的继承链，不能只列叶子节点
+3. **错误码必须有映射** — 每个错误码对应的异常类、HTTP 状态码、用户提示信息
+4. **全局处理器必须写完整逻辑** — @ExceptionHandler 的匹配规则、处理步骤、返回格式
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/error-handling.md`
+
+## 需要读取的源码文件
+
+根据以下文件清单读取源码文件进行分析：
+
+{file_list}
+
+## 文件读取说明
+
+你需要：
+1. 逐个读取上述文件清单中的源码文件
+2. 分析文件内容，提取所需信息
+3. 基于原始源码生成文档，禁止编造
+4. 验证所有配置参数和数值
+
+## 内容组织
+
+### 1. 异常体系总览
+
+```markdown
+| 异常类 | 继承自 | 错误码 | HTTP 状态码 | 使用场景 |
+|--------|--------|--------|------------|---------|
+| BusinessException | RuntimeException | 动态 | 500 | 业务逻辑异常 |
+```
+
+### 2. 异常继承层次图
+
+ASCII 树形图展示异常类的继承关系：
+```
+RuntimeException
+├── BaseException
+│   ├── BusinessException
+│   ├── ValidationException
+│   └── AuthorizationException
+└── ...
+```
+
+### 3. 错误码体系
+
+- **错误码格式**：编码规则（如 模块前缀 + 4位数字）
+- **错误码清单**：
+
+```markdown
+| 错误码 | 含义 | 对应异常 | HTTP 状态码 | 用户提示 |
+|--------|------|---------|------------|---------|
+```
+
+### 4. 全局异常处理器（@ControllerAdvice）
+
+每个处理器方法必须包含：
+- **匹配异常类型**：@ExceptionHandler 捕获的异常类
+- **处理逻辑**：编号步骤（日志记录、错误码提取、响应构建）
+- **返回格式**：统一响应体结构（含示例 JSON）
+- **特殊处理**：参数校验异常、绑定异常、404 等框架异常的处理方式
+
+### 5. 异常使用规范
+
+- 何时抛 checked vs unchecked
+- 异常信息国际化策略（如有）
+- 异常与日志级别的对应关系
+- 敏感信息脱敏规则
+
+## 完成后自检清单
+
+- [ ] 异常继承层次图已画
+- [ ] 每个错误码有对应的异常类和 HTTP 状态码
+- [ ] 全局处理器有完整处理逻辑
+- [ ] 统一响应体格式有 JSON 示例

presets/java-spring/templates/subagent-external-integrations.md

@@ -0,0 +1,80 @@
+# 任务：生成 {module_name} 模块的 external-integrations.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — URL、配置项、认证方式、超时值必须从源码验证
+2. **每个集成必须完整** — 调用方式、目标地址、认证方式、超时配置、重试策略、异常处理
+3. **区分外部调用与内部 RPC** — 本模块通过 `@FeignClient` 字段注入调用外部服务归本文档；本模块自身定义的 `@FeignClient` 接口归 api-contracts.md
+4. **数值验证铁律** — 超时时间、重试次数、连接池参数 → 必须 Read 源码确认
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/external-integrations.md`
+
+## 需要读取的源码文件
+
+根据以下文件清单读取源码文件进行分析：
+
+{file_list}
+
+## 文件读取说明
+
+你需要：
+1. 逐个读取上述文件清单中的源码文件
+2. 分析文件内容，提取所需信息
+3. 基于原始源码生成文档，禁止编造
+4. 验证所有配置参数和数值
+
+## 内容组织
+
+### 1. 外部集成总览表
+
+```markdown
+| 序号 | 集成方 | 调用方式 | 目标地址/配置项 | 调用类 |
+|------|--------|---------|----------------|--------|
+| 1 | 支付网关 | RestTemplate | ${payment.gateway.url} | PaymentClient |
+```
+
+### 2. 逐集成详解（每个外部集成独立小节）
+
+每个外部集成必须包含：
+
+- **集成方**：外部服务名称
+- **调用方式**：RestTemplate / WebClient / OkHttpClient / FeignClient 注入 / HttpUtil / SDK
+- **目标地址**：URL 或配置项名（如 `${xxx.url}`）+ 默认值
+- **HTTP 方法**：GET / POST / PUT / DELETE
+- **请求格式**：Content-Type、请求体类名 + 关键字段
+- **响应格式**：响应体类名 + 关键字段、反序列化方式
+- **认证方式**：Token / 签名 / OAuth / 无认证，含 Token 获取逻辑
+- **超时配置**：连接超时 + 读取超时，来源（硬编码 / 配置项名及默认值）
+- **重试策略**（如有）：重试次数、重试条件、退避策略
+- **异常处理**：捕获哪些异常、失败后的降级/补偿逻辑
+- **调用位置**：哪些类的哪些方法发起调用
+
+### 3. HTTP 客户端配置
+
+- 连接池参数（maxTotal / maxPerRoute / keepAlive）
+- 全局超时配置
+- 拦截器 / 过滤器（日志、签名、Token 注入）
+
+### 4. 调用链路图
+
+ASCII 图展示本模块到各外部服务的调用关系，标注调用方式和关键路径。
+
+## 完成后自检清单
+
+- [ ] 每个外部集成有完整的调用方式、地址、认证、超时、异常处理
+- [ ] 已区分外部调用与本模块自身定义的 FeignClient 接口
+- [ ] 超时值、重试次数等数值从源码验证
+- [ ] 调用链路图已画

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

@@ -0,0 +1,122 @@
+# 任务：生成 {module_name} 模块的 index.md
+
+注意：本模块的所有其他文档已生成完毕。
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 版本号、端口、JVM 参数必须从 pom.xml/yaml/Dockerfile 提取
+2. **index 是导航页，不是内容页** — 只写摘要和统计数字，详细内容通过链接指向其他文档
+3. **文档导航只链接实际存在的文件** — 禁止链接未生成的文档
+4. **源码规模精确计算** — 从骨架 JSON 计算，禁止估算
+
+## 本文档的定位
+
+index.md 是模块的"首页"，帮助读者快速了解模块全貌并找到详细文档。它不应该重复其他文档的内容。
+
+## 输出约束
+
+- 确保中文内容完整无截断
+
+## 前序文档摘要（自动注入，用于生成导航和摘要）
+
+{prior_docs_context}
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/index.md`
+
+## 已生成的文档文件
+
+{generated_docs_files}
+
+## 必须包含的章节
+
+### 0. Front-matter 元数据（必须）
+
+文档开头用 YAML front-matter 标注模块元数据，为后续知识图谱和自动化检索做准备：
+
+```yaml
+---
+module_id: "{module_name}"
+module_type: "service | base-lib | api-contract"
+knowledge_graph:
+  belongs_to: "@system:{parent_system}"
+  depends_on:
+    - "@module:{dep1}"
+    - "@module:{dep2}"
+  provides:
+    - "@api:{api_path}"
+last_source_commit: ""
+---
+```
+
+- `module_type`：从 pom.xml 的 artifactId 后缀推断（-service/-common/-api）
+- `depends_on`：从 pom.xml 的内部依赖提取（同组织的 artifactId）
+- `provides`：从 Controller 的 @RequestMapping 基础路径提取（最多 5 个）
+- `last_source_commit`：留空（由增量更新流程填充）
+
+### 1. 基本信息表
+
+| 属性 | 值 |
+|------|-----|
+| artifactId | ... |
+| 当前版本 | ... |
+| 上下文路径 | ... |
+| 服务端口 | ... |
+| 基础包路径 | ... |
+| 数据库 | ... |
+| 核心中间件 | Redis / Kafka / ES（列出使用的） |
+
+从 pom.xml、application.yaml、Dockerfile 提取。找不到的省略，禁止编造。
+
+### 2. 模块定位（2-3 句话）
+
+模块在系统中的角色、核心能力。
+
+### 3. 源码规模
+
+| 指标 | 数值 |
+|------|------|
+| 源码文件数 | X |
+| 方法总数 | X |
+| Controller 数 | X |
+| 外部接口数 | X |
+| 内部接口数 | X |
+| Feign Client 数 | X |
+
+### 4. 核心业务流程速览
+
+表格：流程名 + 一句话描述 + 入口。不超过 10 行。
+
+### 5. 文档导航
+
+```markdown
+| 文档 | 说明 |
+|------|------|
+| [源码树分析](./source-tree-analysis.md) | 文件结构与分级描述 |
+| [架构设计](./architecture.md) | 分层架构与设计决策 |
+| ... | ... |
+```
+
+只链接「已生成的文档文件」中列出的文件。每个文档一句话说明。
+
+### 6. 快速检索指引
+
+告诉读者常见问题应该去哪个文档找答案：
+- "某个接口的参数是什么" → api-contracts.md
+- "某个缓存 Key 的 TTL" → caching.md
+- "某个业务流程的完整逻辑" → business-logic.md
+
+## 完成后自检清单
+
+- [ ] 基本信息从源码提取，无编造
+- [ ] 无接口完整列表（只有统计数字）
+- [ ] 无枚举值列表（只引用 enums-and-constants.md）
+- [ ] 无缓存策略详细表格（只引用 caching.md）
+- [ ] 文档导航只链接实际存在的文件

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

@@ -0,0 +1,97 @@
+# 任务：生成 {module_name} 模块的 messaging.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — Topic 名、GroupId、并发数、消息体结构必须从源码验证
+2. **消费者必须写完整消费逻辑** — 不是 5-10 行概述就结束，必须有编号步骤列表
+3. **ACK 时机必须明确** — 先 ACK 再处理 / 处理完再 ACK，⚠️ 标注消息丢失风险
+4. **数值验证铁律** — max-poll-records、并发数、超时配置 → 必须 Read 源码确认
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/messaging.md`
+
+## 需要读取的源码文件
+
+根据以下文件清单读取源码文件进行分析：
+
+{file_list}
+
+## 文件读取说明
+
+你需要：
+1. 逐个读取上述文件清单中的源码文件
+2. 分析文件内容，提取所需信息
+3. 基于原始源码生成文档，禁止编造
+4. 验证所有配置参数和数值
+
+## 内容组织
+
+### 1. 消息中间件配置总览
+- 集群/实例说明（集群名、用途、认证方式）
+- Producer 全局配置（acks/retries/batch-size 等）
+- Consumer 全局配置（group-id 命名规则/auto-offset-reset/enable-auto-commit 等）
+- 自定义 Consumer 配置组（max-poll-records/max-poll-interval-ms 等）
+
+> 适用于 Kafka、Pulsar、RabbitMQ、RocketMQ 等消息中间件。
+> 注意：不要重复 architecture.md 中的内容。本文档是消息队列的唯一详细文档。
+
+### 2. Topic/Queue 清单
+
+```markdown
+| Topic/Queue 配置 Key | 默认名称 | 生产者类 | 消费者类 | 消费者组 | 并发数 |
+```
+
+### 3. 消费者详细说明（每个消费者独立小节）
+
+每个消费者必须包含：
+- **Topic/Queue**：配置项名 + 默认值
+- **GroupId/Subscription**：配置项名 + 默认值
+- **ContainerFactory/Listener 容器**：容器名称
+- **Concurrency**：并发数
+- **内部线程池**（如有）：线程数、队列类型、队列容量
+- **消息体**：完整 JSON 示例（含所有字段）
+- **消息 Key / Header / Properties**
+- **完整消费逻辑**：编号步骤列表，从接收到处理完成的每一步，包含：
+  - ACK 时机
+  - 幂等校验逻辑
+  - 核心业务调用链
+  - 异常处理策略
+- **自动启动**：是否默认启动，启停控制方式
+- **错误处理**：消费失败后的行为（重试/死信/告警）
+
+### 4. 生产者详细说明（每个生产者独立小节）
+
+每个生产者必须包含：
+- 生产位置（类.方法）
+- 发送方式（同步/异步/异步带 Header）
+- 消息 Key 生成规则
+- 消息 Header/Properties 字段
+- 消息体类名 + 关键字段
+- 目标集群/实例
+
+### 5. 事件流转全景图
+ASCII 图展示所有 Topic/Queue 的生产→消费→下游的完整链路。
+
+### 6. 算法详解（有复杂消费逻辑时）
+- 算法步骤（编号列表）
+- 新旧算法对比（如有切换开关）
+- 边界条件处理
+
+## 完成后自检清单
+
+- [ ] 每个消费者有完整消费逻辑（编号步骤，不是概述）
+- [ ] ACK 时机已明确标注
+- [ ] 事件流转全景图已画
+- [ ] 数值从源码验证

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

@@ -0,0 +1,88 @@
+# 任务：生成 {module_name} 模块的 data-models.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 所有字段必须有源码出处
+2. **核心实体完整字段表，辅助实体精简** — 核心 Domain 实体（有 @TableName 的）必须完整字段表；VO/DTO/Param 只写关键字段（5-10 个）+ 总字段数
+3. **按业务域分组，不按技术类型** — 用业务域名（如"促销申请相关模型"）而非"§1. Domain 领域实体"
+4. **继承关系是高价值信息** — 必须画出继承/组合关系图
+
+## 本文档不覆盖的内容
+
+- 枚举定义（归 enums-and-constants.md）
+- 常量定义（归 enums-and-constants.md）
+- 字段的业务含义和使用场景（归 business-logic.md）
+
+## 输出约束
+
+- 信息密度优先
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/data-models.md`
+
+## 需要读取的源码文件
+
+{file_list}
+
+## 内容组织
+
+{{#if is_shard}}
+### 分片模式说明
+你负责的业务域：{shard_info}
+- 章节标题用业务域名（如"## 促销申请相关模型"），不用通用的"Domain 领域实体"
+- 不需要生成总览表（由合并步骤统一生成）
+{{/if}}
+
+### 核心 Domain 实体（有 @TableName 的）
+
+每个实体必须包含：
+- 类名 + `@TableName` 注解值（表名）
+- **完整字段表**：字段名、类型、说明、注解/约束
+- 索引信息（如能从注解推断）
+
+### VO/DTO/Param（接口模型）
+
+精简格式：
+```markdown
+### XxxReqVO（促销创建请求）
+继承：BasePageParam | 字段数：18 | 校验组：SeqGroup
+
+**关键字段**：promotionName(String, @NotBlank), promotionType(Integer, @NotNull), 
+startTime(Date), endTime(Date), channelList(List<Integer>)
+
+**完整字段**：详见源码 `com.xxx.XxxReqVO`
+```
+
+### 模型关系图（每个业务域一个）
+
+ASCII 图展示实体间的关系：
+```
+Promotion (主表)
+├── 1:N → PromotionRule (规则)
+├── 1:N → PromotionStore (门店)
+├── 1:1 → PromotionEffectivePeriod (时段)
+└── N:1 → PromotionTemplate (模板)
+```
+
+### 外部依赖类
+
+{sibling_modules}
+
+- 同知识库兄弟模块：类名 + 一句话职责 + 引用链接
+- 外部 JAR：类名 + 关键字段（本模块实际使用的）+ 来源标注
+
+## 完成后自检清单
+
+- [ ] 核心 Domain 实体有完整字段表
+- [ ] VO/DTO 用精简格式，只列关键字段
+- [ ] 有模型关系图
+- [ ] 无枚举/常量定义（已归 enums-and-constants.md）
+- [ ] 章节按业务域组织（分片模式下）

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

@@ -0,0 +1,91 @@
+# 任务：生成 {module_name} 模块的 observability.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 所有监控指标、告警规则、日志配置必须从源码/配置文件提取
+2. **数值验证铁律** — 告警阈值、采集间隔、日志级别 → 必须 Read 源码确认
+3. **只写已实现的** — 不写"建议增加"的监控，只记录源码中已存在的可观测性设施
+4. **禁止越权** — 不创建其他文档文件
+
+## 本文档不覆盖的内容
+
+- 业务逻辑流程（归 business-logic.md）
+- 中间件连接配置（归 architecture.md）
+- 错误码定义（归 enums-and-constants.md）
+
+## 输出约束
+
+- 信息密度优先
+- 确保中文内容完整无截断
+
+## 输入
+
+- 源码缓存目录：`{source_cache_path}`
+- 输出文件：`{output_path}/observability.md`
+
+## 需要读取的源码文件
+
+{file_list}
+
+## 必须包含的章节
+
+### 1. 可观测性概览
+
+| 维度 | 实现方式 | 关键组件 |
+|------|---------|---------|
+| Metrics | Micrometer / Prometheus / 自定义 | 采集端点 |
+| Logging | Logback / Log4j2 / SLF4J | 日志框架 |
+| Tracing | Sleuth / OpenTelemetry / SkyWalking | 链路追踪 |
+| Health | Actuator / 自定义 | 健康检查端点 |
+
+### 2. 自定义监控指标（有 @Counted/@Timed/MeterRegistry 时必须）
+
+从源码中的 Micrometer 注解和 MeterRegistry 调用提取：
+
+| 指标名 | 类型 | 标签 | 来源类.方法 | 业务含义 |
+|--------|------|------|------------|---------|
+| | Counter/Gauge/Timer/Summary | | | |
+
+### 3. 日志规范
+
+从 logback.xml / log4j2.xml / application.yaml 提取：
+
+- **日志格式**：Pattern Layout 配置
+- **日志级别**：各包的级别配置
+- **日志文件**：输出目标（console/file/ELK）
+- **关键业务日志**：源码中带有结构化字段的 log 调用（如 `log.info("order.created", kv("orderId", id))`）
+
+### 4. 健康检查（有 Actuator 或自定义 HealthIndicator 时必须）
+
+| 端点 | 检查内容 | 超时 | 降级行为 |
+|------|---------|------|---------|
+| /actuator/health | | | |
+
+### 5. 告警规则（有 Sentinel Dashboard / Prometheus Rules / 代码中的阈值判断时写）
+
+| 告警名 | 条件 | 阈值 | 级别 | 通知方式 |
+|--------|------|------|------|---------|
+
+### 6. 链路追踪（有 Sleuth/OpenTelemetry/SkyWalking 时写）
+
+- Span 命名规则
+- 自定义 Tag/Baggage
+- 采样率配置
+
+### 7. 运维端点汇总
+
+| 端点路径 | 用途 | 认证要求 |
+|---------|------|---------|
+| /actuator/info | 应用信息 | |
+| /actuator/metrics | 指标查询 | |
+
+## 完成后自检清单
+
+- [ ] 所有指标名从源码提取，非编造
+- [ ] 告警阈值有具体数值
+- [ ] 日志配置从配置文件提取
+- [ ] 无"建议增加"类内容

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

@@ -0,0 +1,81 @@
+# 任务：生成 {module_name} 模块的 scheduled-tasks.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — cron 表达式、线程池配置、任务参数必须从源码验证
+2. **数值验证铁律** — 执行频率、超时时间、重试次数、分片数 → 必须 Read 源码确认
+3. **幂等性必须说明** — 每个任务是否幂等、如何保证幂等（分布式锁/状态机/版本号）
+4. **异常处理必须明确** — 任务失败后的行为：重试/告警/跳过/人工介入
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/scheduled-tasks.md`
+
+## 需要读取的源码文件
+
+根据以下文件清单读取源码文件进行分析：
+
+{file_list}
+
+## 文件读取说明
+
+你需要：
+1. 逐个读取上述文件清单中的源码文件
+2. 分析文件内容，提取所需信息
+3. 基于原始源码生成文档，禁止编造
+4. 验证所有配置参数和数值
+
+## 内容组织
+
+### 1. 任务总览表
+
+```markdown
+| 序号 | 任务名 | 调度方式 | 执行频率 | 所在类 | 幂等保证 |
+|------|--------|---------|---------|--------|---------|
+| 1 | syncPromotion | @Scheduled | 每5分钟 | PromotionSyncJob | 分布式锁 |
+```
+
+### 2. 逐任务详解（每个任务独立小节）
+
+每个定时任务必须包含：
+
+- **任务标识**：方法名 / XxlJob handler 名 / Quartz JobDetail 名
+- **调度方式**：@Scheduled / @XxlJob / Quartz / 自定义调度器
+- **执行频率**：cron 表达式 + 人类可读描述（如 `0 */5 * * * ?` = 每5分钟）
+- **触发条件**（如有）：是否有开关控制、环境限制
+- **执行逻辑**：编号步骤列表，从触发到完成的每一步
+- **数据范围**：处理哪些数据、分页/分片策略
+- **幂等保证**：分布式锁（锁名/超时）/ 状态机 / 版本号 / 天然幂等
+- **超时处理**：任务执行超时后的行为
+- **异常处理**：失败重试策略、告警方式、降级方案
+- **依赖关系**：依赖的外部服务、数据库、缓存
+- **并发控制**：是否允许并行执行、分片策略
+
+### 3. 调度框架配置
+
+- 线程池配置（核心线程数、最大线程数）
+- XxlJob 执行器配置（如使用）
+- 分布式锁实现方式
+
+### 4. 任务依赖关系图（如有多个任务存在先后依赖）
+
+ASCII 图展示任务间的执行顺序和数据流转。
+
+## 完成后自检清单
+
+- [ ] 每个任务有完整执行逻辑（编号步骤）
+- [ ] cron 表达式已标注人类可读描述
+- [ ] 幂等保证方式已说明
+- [ ] 异常处理策略已明确
+- [ ] 数值从源码验证