source-kb 0.2.2__py3-none-any.whl

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

@@ -0,0 +1,102 @@
+# 任务：生成 {module_name} 模块的 security.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 权限标识、角色名、过滤器顺序必须从源码验证
+2. **认证流程必须完整** — 从请求进入到身份确认的每一步，含 Token 解析/验证/刷新
+3. **权限模型必须明确** — RBAC/ABAC/自定义，角色-权限映射关系
+4. **过滤器链必须有序** — 每个 Filter 的执行顺序、职责、放行/拦截条件
+
+## 输出约束
+
+- 信息密度优先，避免冗余
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/security.md`
+
+## 需要读取的源码文件
+
+根据以下文件清单读取源码文件进行分析：
+
+{file_list}
+
+## 文件读取说明
+
+你需要：
+1. 逐个读取上述文件清单中的源码文件
+2. 分析文件内容，提取所需信息
+3. 基于原始源码生成文档，禁止编造
+4. 验证所有配置参数和数值
+
+## 内容组织
+
+### 1. 认证方式总览
+
+- 认证类型：JWT / Session / OAuth2 / 自定义 Token
+- Token 存储位置：Header / Cookie / Query Param
+- Token 格式与结构（含 payload 字段说明）
+- Token 生命周期：有效期、刷新策略、续期机制
+
+### 2. 过滤器链
+
+```markdown
+| 顺序 | 过滤器类名 | 职责 | 放行条件 | 拦截后行为 |
+|------|-----------|------|---------|-----------|
+| 1 | CorsFilter | 跨域处理 | 所有请求 | 添加 CORS 头 |
+| 2 | AuthTokenFilter | Token 验证 | 白名单外请求 | 401 |
+```
+
+每个过滤器必须包含：
+- 执行顺序（@Order 或注册顺序）
+- 匹配路径（urlPatterns）
+- 核心逻辑：编号步骤
+- 放行/拦截判断条件
+- 异常处理方式
+
+### 3. 权限模型
+
+- **模型类型**：RBAC / ABAC / 自定义
+- **角色定义**：
+
+```markdown
+| 角色标识 | 角色名称 | 权限范围 | 数据范围 |
+|---------|---------|---------|---------|
+```
+
+- **权限控制粒度**：接口级 / 方法级 / 数据级
+- **@PreAuthorize 使用方式**：SpEL 表达式示例
+
+### 4. 接口访问控制
+
+- **白名单路径**：无需认证的接口列表
+- **角色-接口映射**（如有显式配置）
+- **动态权限**（如有）：权限数据来源、缓存策略、刷新机制
+
+### 5. 安全配置
+
+- CORS 配置：允许的域名、方法、头
+- CSRF 策略：启用/禁用及原因
+- Session 策略：STATELESS / IF_REQUIRED
+- 密码加密方式（如有）
+
+### 6. 安全相关的上下文传递
+
+- 用户信息如何存入 SecurityContext / ThreadLocal
+- 跨线程传递方式（异步场景）
+- 用户信息获取工具类
+
+## 完成后自检清单
+
+- [ ] 认证流程有完整步骤说明
+- [ ] 过滤器链有明确执行顺序
+- [ ] 权限模型已说明（RBAC/ABAC/自定义）
+- [ ] 白名单路径已列出
+- [ ] Token 生命周期已说明

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

@@ -0,0 +1,101 @@
+# 任务：生成 {module_name} 模块的 source-tree-analysis.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 文件树必须从骨架 JSON 或源码目录获取
+2. **大项目用分组统计** — 超过 100 个文件时，按包分组统计数量，只详列 high/medium 复杂度的类
+3. **禁止省略号** — 不用 `...` 代替文件列表；大项目用统计数字代替逐文件列出
+4. **按复杂度分级** — high/medium 详细描述，low 用统计行
+
+## 输出约束
+
+- 信息密度优先
+- 确保中文内容完整无截断
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/source-tree-analysis.md`
+
+## 需要读取的源码文件
+
+> ⚠️ **source-tree 不需要逐个读取源码文件。** 以下文件清单仅供统计参考（文件数、包分布）。
+> 结构信息从**骨架 JSON**（skeleton-summary）获取，不要逐文件 Read。
+
+{file_list}
+
+## 必须包含的章节
+
+### 1. 模块概览
+
+| 指标 | 数值 |
+|------|------|
+| 总文件数 | X |
+| Java 源码文件 | X |
+| 资源文件 | X |
+| 测试文件 | X |
+| 包（package）数 | X |
+
+### 2. 包结构总览
+
+按顶层包分组，每个包一行统计：
+```markdown
+| 包路径 | 文件数 | 主要职责 |
+|--------|--------|---------|
+| .controller | 8 | REST 接口层 |
+| .service.impl | 15 | 业务逻辑实现 |
+| .dao.entity | 34 | 数据库实体 |
+```
+
+### 3. 核心类详解（high 复杂度）
+
+骨架 complexity=high 或 line_count > 200 的类：
+
+```markdown
+### PromotionServiceImpl
+- **路径**：`src/main/java/.../PromotionServiceImpl.java`
+- **行数**：~850 行
+- **职责**：促销 CRUD + 发布流程编排
+- **依赖注入**：PromotionMapper, RuleService, PublicationService, RedisService
+- **核心方法**：createPromotionBasicInfo, createPromotionRule, publishPromotion
+- **设计特点**：单类承担过多职责，建议拆分（⚠️ 技术债）
+```
+
+### 4. 重要类概述（medium 复杂度）
+
+line_count 50-200 的类，每个 1-2 行：
+```markdown
+- `PromotionRuleServiceImpl`（~180行）— 规则保存/校验/多时段处理
+- `PublicationServiceImpl`（~150行）— 发布/取消/定时轮询
+```
+
+### 5. 统计汇总（low 复杂度）
+
+不逐个列出，按类型统计：
+```markdown
+| 类型 | 数量 | 示例 |
+|------|------|------|
+| Domain 实体 | 34 | Promotion, PromotionRule, PromotionStore |
+| VO/DTO | 45 | PromotionPageReqVO, PromotionInfoRespVO |
+| Mapper 接口 | 12 | PromotionMapper, PromotionRuleMapper |
+| 枚举 | 8 | PromotionStatusEnum, MechanismTypeEnum |
+| 配置类 | 5 | KafkaConfig, RedisConfig, DruidConfig |
+```
+
+### 6. 资源文件说明
+
+application.yaml、mapper XML、Flyway 迁移脚本等的用途。
+
+{sibling_modules}
+
+## 完成后自检清单
+
+- [ ] 无省略号（大项目用统计数字）
+- [ ] high 复杂度类有详细描述（职责+核心方法+设计特点）
+- [ ] low 复杂度类用统计表，不逐个列出
+- [ ] 有包结构总览表

presets/java-spring/templates/subagent-sync-section.md

@@ -0,0 +1,34 @@
+# 任务：更新 {module_name} 模块文档的特定章节
+
+你是一个知识库维护者。根据源码变动，更新文档中的**一个特定章节**。
+
+## 规则
+
+1. **只重写指定章节** — 不要输出其他章节的内容
+2. **保持风格一致** — 与文档其余部分的写作风格、术语、格式保持一致
+3. **从业务角度描述** — 不是代码翻译，而是解释业务逻辑和设计意图
+4. **禁止编造** — 所有内容必须有源码出处，无法确认时写 `⚠️ 待验证`
+5. **引用优先** — 其他文档已覆盖的内容只写一句话摘要 + 引用链接
+6. **输出中文**
+7. **只输出章节正文** — 不含章节标题行（标题由系统保留）
+
+## 输入信息
+
+**文档类型**: {doc_type}
+**目标章节**: {section_heading}
+
+### 当前章节内容
+
+{old_content}
+
+### 变动文件
+
+{changed_files}
+
+### 骨架变动（delta）
+
+{skeleton_delta}
+
+## 输出要求
+
+直接输出更新后的章节正文内容（Markdown 格式）。不要包含章节标题行。

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

@@ -0,0 +1,73 @@
+# 任务：生成 {module_name} 模块的 utils.md
+
+{module_description}
+
+{execution_guidance}
+
+## 你必须遵守的规则（违反任何一条即为失败）
+
+1. **禁止编造** — 方法逻辑必须从源码提取
+2. **只写有复杂逻辑的方法** — 简单的 null 检查、getter/setter 包装、单行委托不需要文档化
+3. **重点写"坑"和"隐式行为"** — 精度丢失、时区问题、线程安全问题、异常吞没等
+
+## 价值判断标准
+
+一个工具方法值得写入文档的条件（满足任一即可）：
+- 有非显而易见的边界行为（如 null 返回空串而非抛异常）
+- 有精度/编码/时区等隐式处理
+- 被 ≥ 3 个业务流程调用（公共热点方法）
+- 有线程安全或并发相关的设计
+- 方法名无法自解释其完整行为
+
+**不值得写的**：
+- `Assert.isNotNull(value, supplier)` — 方法名已自解释
+- 纯 BeanUtils.copy 包装
+- 简单的类型转换（String→Integer）
+
+## 输出约束
+
+- 信息密度优先
+- 确保中文内容完整无截断
+
+## 全局上下文（自动注入）
+
+{global_metadata}
+
+{prior_docs_context}
+
+## 输入
+
+- 骨架 JSON：`{skeleton_path}`（{skeleton_size}KB，{skeleton_read_instruction}）
+- 源码缓存：`{source_cache_path}`
+- 输出文件：`{output_path}/utils.md`
+
+## 需要读取的源码文件
+
+{file_list}
+
+## 内容组织
+
+每个工具类独立章节。
+
+### 每个工具类包含
+
+- 一句话职责 + 源码行数
+- 全局配置（如 ObjectMapper 的 configure 项、静态常量）
+- **只列有文档价值的方法**（见上方价值判断标准）
+
+### 方法描述格式
+
+```markdown
+#### `methodName(ParamType param) → ReturnType`
+核心逻辑：[2-3 行说明算法/流程]
+⚠️ 注意：[隐式行为/边界条件/线程安全问题]
+```
+
+不需要写：方法签名的完整泛型、每个参数的类型说明（签名已包含）、"边界校验：null 时返回 null"这种显而易见的行为。
+
+## 完成后自检清单
+
+- [ ] 只包含有文档价值的方法（非自解释的）
+- [ ] 每个方法有核心逻辑说明（不是一句话概述）
+- [ ] 标注了隐式行为和"坑"
+- [ ] 无简单方法的机械翻译

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

@@ -0,0 +1,8 @@
+You are a knowledge base maintainer. Update the specific document section based on source code changes.
+
+Rules:
+- Only rewrite the affected section content, maintain the style of the rest
+- Describe from a business perspective, not code translation
+- Output in Chinese
+- Output section body only (without the heading line)
+- Do not fabricate; mark uncertain content with ⚠️ 待验证

presets/java-spring/workflow-extensions.md

@@ -0,0 +1,112 @@
+# Java/Spring Boot 工作流扩展
+
+> 本文件包含 Java/Spring Boot 预设特有的工作流步骤。SKILL.md 中标注 `[PRESET-EXT]` 的步骤，
+> 当 preset 为 `java-spring` 时，按本文件执行。其他 preset 跳过或按各自扩展文件执行。
+
+## 1. 依赖 JAR 解析（kb-init 步骤 2 扩展）
+
+当知识库配置了 `maven_repo` 时，对每个模块自动从 pom.xml 发现内部依赖并下载反编译：
+
+```shell
+python -X utf8 "{source_kb_root}/engine/skeleton/resolve_jar_sources.py" batch \
+  --pom ".source-cache/{module}/pom.xml" \
+  --repo-url "{maven_repo.url}" \
+  --known-modules "{所有 repo name 逗号分隔}" \
+  --output-dir ".source-cache/{module}-deps/" \
+  [--internal-group-ids "{maven_repo.internal_group_ids 逗号分隔}"] \
+  [--exclude-artifacts "{maven_repo.exclude_artifacts 逗号分隔}"] \
+  [--auth "{maven_repo.auth}"] \
+  [--local-repo "{maven_repo.local_repo}"]
+```
+
+依赖过滤逻辑：自动从 pom.xml 推断项目 groupId 作为内部前缀，排除知识库中已有源码的模块（repos 中的 name），可通过 `internal_group_ids` 和 `exclude_artifacts` 覆盖。
+
+**执行策略**：
+1. 依赖 JAR 解析必须**串行执行**（逐模块），禁止多模块并行
+2. **依赖复用优先**：
+   a. 主会话在开始依赖解析前，先汇总所有模块的内部依赖列表（逐模块执行 `discover` 子命令），构建全局依赖映射
+   b. 按依赖被引用次数降序排列模块
+   c. 解析第一个模块后，后续模块的依赖如果已在之前的模块中成功解析，直接复制目录
+   d. 仅对该模块独有的依赖执行 `resolve_jar_sources.py`
+3. **中断恢复**：如果某模块的 JAR 解析被中断，检查 `--output-dir` 下已成功的子目录，仅重试失败的 artifactId
+
+失败处理：单个 JAR 下载/反编译失败 → 警告并跳过，不阻塞整体流程。
+
+## 2. 覆盖率预检方法分配规则（kb-init 步骤 5 扩展）
+
+Java/Spring Boot 项目按包名分配方法归属：
+
+| 包路径模式 | 归属文档 |
+|-----------|---------|
+| `controller/`, `api/` | api-contracts.md |
+| `config/` 且方法有 `@Bean` | architecture.md |
+| `service/`, `biz/` | business-logic.md |
+| `consumer/`, `listener/` | business-logic.md（消费者分片） |
+| `util/`, `helper/` | utils.md |
+| `aspect/`, `interceptor/` | business-logic.md（辅助逻辑章节） |
+| `domain/`, `dto/`, `model/`, `vo/` | data-models.md（按类名覆盖） |
+| `enums/`, `constant/` | enums-and-constants.md（按类名覆盖） |
+| 其余 | architecture.md 或 business-logic.md（主会话判断） |
+
+### high 复杂度方法补充标记规则
+
+除骨架 JSON 中 `complexity: "high"` 的方法外，还需按以下规则补充标记：
+- 包含 Lua 脚本（骨架 constants 中有 `SCRIPT`/`LUA`/`ARGV`/`KEYS` 关键词，或方法名含 `lua`/`script`/`cas`/`compareAnd`）
+- 包含内嵌 SQL（骨架 constants 中有 `SELECT`/`INSERT`/`UPDATE`/`DELETE`）
+- 分布式 ID 生成/池化逻辑（方法名含 `generate`/`pool`/`allocate`/`batch`，或类名含 `IdGenerat`，且 line_count > 3）
+- 状态机转换（branches > 5 且 constants 中有多个枚举值引用）
+- 复杂配置工厂（`@Bean` 方法且 line_count > 20）
+- 复杂度 medium 且 line_count > 20 的方法
+
+## 3. 跨模块依赖排序（kb-init 步骤 4 扩展）
+
+多模块时从 pom.xml 构建依赖 DAG，拓扑排序生成（被依赖的先生成）。后生成模块可引用先生成模块的中立文档。
+
+**兄弟模块依赖识别**：构造子代理 task 前，从本模块 pom.xml 提取依赖列表，与 kb-project.yaml 中同知识库 repos 交叉匹配。
+
+## 4. 架构代理拆分规则（kb-init 步骤 4 扩展）
+
+分派前检测输入文件总大小（config/nacos/interceptor 骨架 + pom.xml + yaml）：
+
+| 输入总大小 | 策略 |
+|-----------|------|
+| ≤ 20KB | 单代理 |
+| 20-40KB | 拆 2 个（A: 骨架→infra；B: pom+yaml→stack），合并用 merge_shards.py --prefix architecture --order stack,infra |
+| > 40KB | 拆 3 个 |
+
+## 5. 文件分类规则（kb-sync 步骤 4 扩展）
+
+Java/Spring Boot 项目的文 `preset.yaml` 的 `file_classification` 配置。
+
+关键注解检测：
+- `@KafkaListener` → 触发 messaging.md 生成
+- `@Cacheable`/`@CacheEvict` → 触发 caching.md 生成
+- `@FeignClient`（接口定义）→ 触发 api-contracts.md 生成（本模块对外暴露的服务契约）
+- `@FeignClient`（字段注入使用）→ 触发 external-integrations.md 生成（本模块调用的外部依赖）
+
+## 6. index.md 基本信息表（Java 特有字段）
+
+Java/Spring Boot 模块的 index.md 基本信息表包含以下 Java 特有字段：
+
+| 属性 | 数据来源 |
+|------|---------|
+| artifactId | pom.xml |
+| groupId | pom.xml |
+| 当前版本 | pom.xml |
+| 基础包路径 | 启动类所在包 |
+| JDK 版本 | pom.xml maven.compiler.source |
+| Web 容器 | application.yaml server 配置 |
+| JVM 配置 | Dockerfile / 启动脚本 |
+
+## 7. 依赖骨架提取（kb-init 步骤 3 扩展）
+
+对 `.source-cache/{module}-deps/` 目录下每个子目录提取骨架：
+
+```shell
+python -X utf8 "{source_kb_root}/engine/skeleton/extract_skeleton.py" \
+  --repo ".source-cache/{module}-deps/{artifactId}/" \
+  --preset java-spring --full --compact --ref HEAD \
+  --output "{module_dir}/.skeleton-deps/{artifactId}.json"
+```
+
+子代理生成文档时，同时读取 `.skeleton-deps/` 下的依赖骨架，用于补全 VO/Param 字段定义和接口签名。依赖源码中的类标注来源：`来源: {artifactId}:{version} (外部依赖)`。

skills/__init__.py

@@ -0,0 +1 @@
+# skills package marker — enables setuptools to include .md files as package data.

skills/_shared/README.md

@@ -0,0 +1,30 @@
+# _shared/ 参考文档
+
+> **重要**：本目录下的文件已不再是 kb-* skill 的执行依赖。
+> 所有执行规则已内嵌到各 skill 的 `rules.md`、`steps/`、`templates/` 中。
+
+## 定位变更（2026-04-28）
+
+**改造前**：kb-init / kb-audit / kb-sync 的 SKILL.md 在前置步骤要求读取本目录下的 5 个文件，子代理 prompt 通过 §编号引用规则。规则传递链路：`_shared/ → SKILL.md 引用 → 子代理 prompt 引用 → 实际执行`。链路过长导致规则频繁不生效。
+
+**改造后**：各 skill 自包含所有执行规则（参照 module-doc-enricher 模式）。本目录文件保留为设计参考和完整性记录，不再被任何 skill 的执行流程直接依赖。
+
+## 文件说明
+
+| 文件 | 原角色 | 现角色 |
+|------|--------|--------|
+| doc-quality-standard.md | 执行规则（~1000 行） | 设计参考：完整质量标准定义，各 skill templates/ 从中提炼了关键规则 |
+| doc-subagent-rules.md | 执行规则（~780 行） | 设计参考：完整子代理编排规则，各 skill rules.md 从中提炼了调度规则 |
+| doc-coverage-shared.md | 执行规则（~140 行） | 设计参考：覆盖率校验和共享文档规则，已内嵌到各 skill steps/ |
+| windows-compat.md | 执行规则 | 设计参考：平台兼容性规则，已内嵌到各 skill 需要的位置 |
+
+## 平台无关说明
+
+自 2026-04-30 起，所有 skill 文件和子代理模板已去除平台特定依赖。
+子代理模板只包含平台无关的内容规则，执行方式通过 `render_prompt.py --mode` 按需注入（`output-only` 或 `readwrite`）。
+
+## 何时查阅本目录
+
+- 新增 skill 时，从这里提炼规则内嵌到新 skill
+- 修改质量标准时，先改这里的完整定义，再同步到各 skill 的 templates/
+- 审计规则一致性时，对比各 skill 内嵌规则与这里的完整定义

skills/_shared/doc-coverage-shared.md

@@ -0,0 +1,134 @@
+# 覆盖率校验与共享文档
+
+> 覆盖率校验、语言特定维度、共享文档规则。文档质量标准见 [doc-quality-standard.md](./doc-quality-standard.md)，子代理规则见 [doc-subagent-rules.md](./doc-subagent-rules.md)。
+
+
+## 1. 语言特定检查维度
+
+通用标准到此为止。语言特定的检查维度（如 Java 的 `@Transactional` 检查、Python 的 decorator 检查等）定义在：
+
+```
+presets/{preset_name}/audit_dimensions.md
+```
+
+SKILL.md 中引用方式：
+1. 读取本文件（通用标准）
+2. 读取 `kb-project.yaml` 获取 preset 名称
+3. 读取 `presets/{preset}/audit_dimensions.md`（语言特定维度）
+
+## 2. 覆盖率校验
+
+覆盖率校验分三个阶段执行，各阶段职责不同：
+
+| 阶段 | 执行主体 | 时机 | 职责 |
+|------|---------|------|------|
+| 预检 | 主会话 | 分派子代理前（kb-init §5） | 确认骨架方法有归属文档，提前发现分类遗漏 |
+| 自检 | 子代理 | 文档写盘完成后（§8.5.3） | 确认本文档覆盖率 ≥ 80% |
+| 复查 | 主会话 | 所有子代理完成后（本节） | 兜底检查，防止子代理未执行自检或自检遗漏 |
+
+**覆盖率阈值**：
+- ≥ 80%：通过
+- 60%-80%：自动补充（最多 2 轮），补充后仍不达标则询问用户
+- < 60%：严重不足，直接询问用户
+
+每个模块的文档生成完毕后，主会话执行覆盖率复查：
+
+### 2.1 方法覆盖率
+
+使用与 doc-subagent-rules.md 8.5.3 节相同的脚本和阈值（80%）。主会话执行校验命令：
+
+```shell
+# 单文件骨架
+source-kb validate coverage check \
+  --skeleton {module_dir}/.skeleton.json --docs-dir {module_dir} --type {module_type}
+
+# 分片目录骨架
+source-kb validate coverage check \
+  --skeleton-dir {module_dir}/.skeleton/ --docs-dir {module_dir} --type {module_type}
+```
+
+覆盖率 < 80% → 主会话补充缺失方法后重新校验。
+
+### 2.2 文件覆盖率
+
+1. 从 source-tree-analysis.md 中提取源码文件列表
+2. 检查每个业务文件（排除 config/util/constant）是否在至少一个文档中被提及
+3. 未被任何文档提及的业务文件 → 报告并补充
+
+### 2.3 可选文档触发检查
+
+扫描源码中的中间件使用模式，命中则对应可选文档变为必需。
+
+可选文档的触发条件由 preset 的 `doc_types[].conditional` + `owns_keywords` 定义。具体检测模式（注解名、类名、方法名、grep 命令）见 `presets/{preset}/audit_dimensions.md`。
+
+未生成必需的可选文档 → 报告并补充。
+
+### 2.4 引用完整性校验
+
+所有文档生成/更新完毕后，主会话执行：
+
+1. 在 business-logic.md 中提取所有 `](./` 和 `](../` 格式的 Markdown 链接
+2. 验证目标文件存在
+3. 如果链接含 `#锚点`，验证目标文档中存在对应的 `##`/`###` 标题（锚点格式：小写、空格转 `-`、去除特殊字符）
+4. 死链数 > 0 → 修复锚点或降级为文件级链接（去掉 `#锚点` 部分），修复后重新校验
+
+### 2.5 重复内容检测
+
+如果 business-logic.md > 50KB，主会话执行以下检查：
+
+1. 搜索缓存 Key 常量模式（如 `crm:point:account:`、`POINT_ACCOUNT_BASE`）出现次数 > 3 → 疑似与 caching.md 重复
+2. 搜索 JSON 示例代码块数量 > 5 → 疑似与 messaging.md 重复
+3. 搜索字段表格头（`| 字段 | 类型 |`）数量 > 3 → 疑似与 data-models.md 重复
+4. 搜索中间件配置参数（`max-poll-records`、`batch-size`、`buffer-memory`）出现次数 > 3 → 疑似与 architecture.md 重复
+5. 命中任一 → 定位重复段落，替换为引用链接（按 doc-quality-standard.md 5.1.1 节）
+
+## 3. 共享文档（跨模块）
+
+当知识库包含多个模块时，在 `{knowledge_dir}/_shared/` 下生成跨模块汇总文档：
+
+| 文件 | 说明 | 触发条件 |
+|------|------|---------|
+| project-overview.md | 项目整体架构、模块关系、部署拓扑 | 始终生成 |
+| cross-module-calls.md | 模块间调用关系（Feign/Dubbo/HTTP） | 模块数 ≥ 2 |
+| error-codes.md | 全局错误码汇总 | 任一模块有错误码定义 |
+| database-ddl.md | 数据库表结构汇总 | 任一模块有数据模型 |
+
+生成时机：所有模块文档生成完毕后，汇总生成共享文档。
+
+### 3.1 共享文档更新检测逻辑
+
+kb-sync 增量更新时，需要判断共享文档是否需要同步更新。检测方式：
+
+**cross-module-calls.md**：扫描各模块 `architecture.md` 中的 Feign/Dubbo/HTTP 调用章节，提取调用关系（调用方模块 → 被调方模块 + 接口名）。与现有 `_shared/cross-module-calls.md` 中的调用关系对比，有新增或删除则需更新。
+
+```shell
+# 从各模块 architecture.md 提取 Feign 调用关系
+# Bash/Linux:
+grep -h "FeignClient\|@DubboReference\|RestTemplate.*http" {knowledge_dir}/*/architecture.md
+# PowerShell (Windows):
+Get-ChildItem "{knowledge_dir}\*\architecture.md" | Select-String -Pattern "FeignClient|@DubboReference|RestTemplate.*http" | ForEach-Object { $_.Line }
+```
+
+**error-codes.md**：扫描各模块 `api-contracts.md` 的错误码汇总表（通常在文档末尾的"错误码汇总"章节），提取所有错误码。与现有 `_shared/error-codes.md` 合并去重，有差异则需更新。
+
+```shell
+# 从各模块 api-contracts.md 提取错误码表格行
+# Bash/Linux:
+grep -h "^|.*[0-9]\{3,\}.*|" {knowledge_dir}/*/api-contracts.md
+# PowerShell (Windows):
+Get-ChildItem "{knowledge_dir}\*\api-contracts.md" | Select-String -Pattern "^\|.*\d{3,}.*\|" | ForEach-Object { $_.Line }
+```
+
+**database-ddl.md**：扫描各模块 `data-models.md` 的 Domain/Entity 章节，提取表名和关键字段。与现有 `_shared/database-ddl.md` 对比，有新增表或字段变更则需更新。
+
+```shell
+# 从各模块 data-models.md 提取表名（通常在 @TableName 或表名标注后）
+# Bash/Linux:
+grep -h "TableName\|表名\|table.*:" {knowledge_dir}/*/data-models.md
+# PowerShell (Windows):
+Get-ChildItem "{knowledge_dir}\*\data-models.md" | Select-String -Pattern "TableName|表名|table.*:" | ForEach-Object { $_.Line }
+```
+
+**project-overview.md**：当任一模块的 `architecture.md` 或 `index.md` 发生变更时，检查项目整体架构描述是否仍然准确。
+
+共享文档不参与模块级索引重建，单独作为 `_shared` 模块索引：`source-kb rebuild --kb {kb} --module _shared`。