AI研发自动化：Wiki知识库+技能包

学习一下这俩个技能：obsidian-cli 和 llm-wiki

/superpowers-brainstorming我现在拥有这俩个技能 obsidian-cli 和 llm-wiki，目标是构建一套 mkt-link 应用专属知识库。原始材料分 2 种：一种是文档类，有各种技术方案、产品文档、测试文档、架构方案，另一种是 mkt-link 的代码仓库的所有代码。 希望构建出的知识库，可以持续迭代生长，支持后续不断供给材料，并且在查找相关的知识时可以快速检索定位到相关的全面上下文知识。

# mkt-link 知识库设计文档## 项目概述为 mkt-link 应用构建专属知识库，支持个人学习、团队协作和日常开发三种场景。## 原材料| 类型 | 来源 | 规模 ||------|------|------|| 文档 | ~/kb-source/ | ~100+ 文档（技术方案、提测文档、接口文档、故障复盘、代码规范、交接文档等） || 代码 | ~/IdeaProjects/mkt-link/ | 3038 Java 文件，DDD 架构 |## 技术选型| 组件 | 选择 | 说明 ||------|------|------|| 知识库管理 | Obsidian | 可视化界面、图谱视图、双向链接 || 搜索引擎 | qmd | BM25 + 向量检索 + LLM 重排序 || 知识化方式 | 静态分析 + LLM 摘要 | 代码结构用静态分析提取，语义描述用 LLM 生成 || 更新策略 | 混合方式 | 代码定期更新，文档按需/实时更新 |## 架构设计### 三层架构1. **Raw sources** — kb-source + mkt-link（只读，不可修改）2. **Wiki** — mkt-link-kb（LLM 生成和维护）3. **Schema** — CLAUDE.md（指导 LLM 工作流程）### 目录结构```kb-source/                    # 原始文档（不可修改）├── *.md                      # 技术方案、提测文档、接口文档等├── *.jpg                     # 架构图等图片mkt-link/                     # 原始代码仓库（不可修改）├── link-client/├── link-controller/├── link-domain/├── link-infrastructure/├── link-service/├── ...mkt-link-kb/                  # 知识库 vault（LLM 生成和维护）├── index.md                  # 内容目录├── log.md                    # 操作日志├── entities/                 # 实体页面（模块、核心类、接口）├── concepts/                 # 概念页面（同款引擎、簇变更、价格链路等）├── sources/                  # 文档摘要（技术方案、提测文档摘要）├── code/                     # 代码知识化│   ├── modules/              # 模块概述│   ├── classes/              # 核心类详情│   └── diagrams/             # 代码结构图（类关系、调用链）├── queries/                  # 查询结果存档（有价值的问答）├── assets/                   # 图片等资源└── CLAUDE.md                 # Schema 文件```## 核心工作流### 1. 文档摄入流程```用户添加新文档 → LLM读取文档 → 与用户讨论关键点 → 生成摘要页 → 更新相关实体/概念页 → 更新 index.md → 记录 log.md```### 2. 代码知识化流程```静态分析提取结构 → 确定核心模块/类 → LLM 生成概述 → 建立关联链接 → 更新 index.md```**粒度策略：**- link-service, link-domain → 详细（类级）- link-client, link-controller → 中等（模块级 + 关键类）- link-infrastructure, link-dump → 简略（模块级）### 3. 查询流程```用户提问 → qmd 搜索相关页面 → LLM 综合回答 → （如有价值）存档到 queries/```### 4. 知识库维护定期执行 lint 检查：- 矛盾检测：不同页面间是否存在冲突描述- 孤页检测：没有 inbound 链接的页面- 缺失检测：被提及但无独立页面的概念/实体- 过时检测：代码已变更但描述未更新## 页面格式规范### Frontmatter 格式```yaml---type: entity | concept | source | module | class | querycreated: 2026-04-24updated: 2026-04-24tags: [标签列表]related: [[相关页面]]source_file: /path/to/original---```### 概念页面模板```markdown---type: conceptcreated: YYYY-MM-DDupdated: YYYY-MM-DDtags: [相关标签]---# 概念名称## 概述概念的核心描述。## 核心功能- [[子概念1]]：描述- [[子概念2]]：描述## 相关模块- [[模块名]] — 说明## 关键类- [[类名]] — 说明## 相关文档- [[文档摘要名]]## 注意事项- 关键注意点```### 模块页面模板```markdown---type: modulecreated: YYYY-MM-DDupdated: YYYY-MM-DDmodule: 模块名tags: [相关标签]---# 模块名 模块## 职责模块职责描述。## 核心类| 类名 | 职责 | 关键方法 |## 依赖关系- 依赖 → [[依赖模块]]- 被 → [[调用模块]] 调用## 关键文件- 关键文件列表```### 类页面模板```markdown---type: classcreated: YYYY-MM-DDupdated: YYYY-MM-DDmodule: 所属模块package: 包路径tags: [相关标签]---# 类名 类## 所在位置`路径/Class.java`## 设计意图设计意图描述。## 关键方法| 方法 | 参数 | 返回值 | 说明 |## 使用场景- 场景描述## 注意事项- 关键注意点```## 工具配置### Obsidian 配置- Vault 位置：`/Users/caozuhua/mkt-link-kb`- 推荐插件：Dataview、Graph View、Backlinks、Web Clipper### qmd 搜索引擎```bash# 安装git clone https://github.com/tobi/qmd.gitcd qmd && cargo install --path .# 初始化索引qmd init /Users/caozuhua/mkt-link-kb# 搜索qmd search "关键词"qmd search --semantic "语义查询"qmd search --rerank "LLM重排序查询"```## 实施阶段| 阶段 | 内容 ||------|------|| Phase 1 | 基础设施搭建（目录、qmd、CLAUDE.md、Obsidian插件） || Phase 2 | 文档知识化（首批 ~100 文档） || Phase 3 | 代码知识化（静态分析 + LLM摘要） || Phase 4 | 集成验证（搜索、图谱、导航、lint） || Phase 5 | 持续运营（摄入流程、更新机制） |## 关键指标| 指标 | 目标 ||------|------|| 概念页面 | 20+ 个核心概念 || 实体页面 | 10+ 个核心类 || 模块页面 | 6 个模块概述 || 文档摘要 | 100+ 个 || 关联链接 | 平均每页 5+ outbound || 搜索响应 | qmd 搜索 < 1s |## 决策记录| 决策项 | 选择 | 原因 ||------|------|------|| 知识库管理工具 | Obsidian + qmd | 检索能力强，符合 LLM Wiki 架构 || 代码知识化粒度 | 智能混合 | 核心详细、辅助简略，避免过度投入 || 检索方式 | 关键词 + 语义 + 关联导航 | 覆盖不同查询场景 || 更新策略 | 混合方式 | 代码定期、文档按需，平衡效率与实时性 |

/superpowers-brainstorming 现在我如果有一份产品文档，如何合理利用 mkt-link-kb 加代码仓库，设计出一份逻辑严密的技术方案，请帮我设计下

/superpowers-brainstorming 查看 kb-tech-solution 技能，然后确认几个问题：1. 这个技能是否只能作用于 mkt-link-kb 知识库2. 这个技能能否跨多个知识库进行技术方案设计   3. 这个技能还有哪些可以优化的地方

---name: kb-tech-solutiondescription: Use when generating a technical solution from a product document for any knowledge base project with KB-META.md structure - auto-discovers KB, supports multi-KB search, outputs merged design document.---# kb-tech-solution 技术方案生成## Overview**角色定义：** 你是一名高级技术架构师，擅长将产品需求转化为可落地的技术方案。你需要结合知识库已有设计、代码仓库现有能力，输出结构化、可评审、可执行的技术设计文档。**输出语言：** 中文为主，代码和专有名词保持英文。**核心流程：** 三要素识别 → 需求理解 → 调研分析 → 复杂度判断 → 设计生成 → 摘要确认 → 输出文档**配套文档：**- `kb-meta-spec.md` — KB-META.md 格式规范、字段说明、templatePath/relatedKBs 使用规则- `safety-rules.md` — 安全关键词触发规则、语义区分、检测流程- `exception-and-revision.md` — 异常处理策略、上下文恢复、修订机制- `examples.md` — L1/L2/L3 三级完整示例<HARD-GATE>Do NOT output the complete solution immediately. Follow the layered dialogue process below. Skipping rounds violates this skill.</HARD-GATE>## When to Use- 有产品文档需要转化为技术方案- 工作目录在知识库结构下（含 KB-META.md 或 CLAUDE.md）- 需要生成可评审、可执行的技术设计**Do NOT use for:**- 纯代码修改（无设计变更）- 配置调整、参数变更- 非 KB-META.md 结构的项目---## Interaction Simplification Principle**核心原则：减少非必要交互，只在关键决策点确认。**| 交互类型 | 是否必要 | 处理方式 ||----------|----------|----------|| **三要素缺失** | ✅ 必要 | 询问用户补充 || **复杂度层级判断** | ❌ 非必要 | 自动判断，仅异常时询问 || **知识库匹配结果** | ❌ 非必要 | 自动展示匹配结果，用户无异议则继续 || **变更清单确认** | ✅ 必要（L2/L3） | 涉及实施范围，必须确认 || **设计方案分段确认** | ❌ 非必要 | L1/L2 直接输出，仅 L3 分段确认 || **方案摘要预览** | ✅ 必要 | 输出前必须展示摘要确认 |---## Phase 0: Three-Element Input### Element Discovery with Fallback| Element | Discovery Method | Fallback Action | 可否缺失继续 ||---------|------------------|-----------------|--------------|| **Knowledge Base** | 使用 `search_file` 工具全局搜索 `KB-META.md`，若有多个结果则询问用户选择 | ❌ **必须询问用户** | 不可 || **Code Repository** | 读取 KB-META.md 的 codeRepoLocalPath | ⚠️ 询问用户，或标注"[无代码仓库，仅设计方案]" | 可（纯设计类需求） || **Product Document** | 无默认 | ❌ **必须用户提供** | 不可 |> KB-META.md 格式规范详见 `kb-meta-spec.md`**缺失询问示例：**```【三要素识别】❌ 知识库：当前目录未找到 KB-META.md 或 CLAUDE.md请指定知识库路径或名称（如 "mkt-link-kb"）❌ 代码仓库：KB-META.md 未配置 codeRepoLocalPath请指定代码仓库本地路径（如 "../IdeaProjects/mkt-link/"）✅ 产品文档：已识别为用户描述```**完整识别输出（无缺失时静默继续）：**```三要素识别完成：- 知识库：mkt-link-kb- 代码仓库：../IdeaProjects/mkt-link/ (解析为绝对路径)- 产品文档：用户描述（新增SKU查询接口）继续执行需求分析...```---## Directory Management| Phase | 工作目录 | 操作内容 ||-------|----------|----------|| KB匹配 | KB root | 搜索 concepts/、sources/、code/classes/ || 代码分析 | Code repo | 分析项目结构、模块、技术栈 || 输出文档 | KB root | 写入 {outputPath}/ |**切换方式：** 推荐使用绝对路径读取文件（无需 cd）。---## Multi-KB Search Strategy**触发条件：** KB-META.md 配置了 `relatedKBs`、用户指定跨 KB 参考、或当前 KB 搜索结果不完整。> relatedKBs 路径发现规则详见 `kb-meta-spec.md`使用 `task` 工具在单次调用中并发搜索多个 KB：```task([  { description: "搜索当前KB", prompt: "【只读调研任务】搜索 {当前KB} concepts/ 和 code/classes/ 匹配相关内容。禁止修改任何文件。" },  { description: "搜索关联KB", prompt: "【只读调研任务】搜索 {关联KB} concepts/ 匹配相关内容。禁止修改任何文件。" }])```---## Phase 1: Requirement Analysis### 需求理解（完整四维度）| Dimension | Content | Source ||-----------|---------|--------|| **业务目标** | 需求背景、业务价值 | 产品文档/用户描述 || **功能需求** | 具体功能点、接口定义 | 产品文档 || **非功能需求** | 性能、可用性、可扩展性 | **主动询问**（产品文档未明确时） || **约束条件** | 时间节点、资源限制、技术约束 | **主动询问**（产品文档未明确时） |**非功能需求询问模板：**```需求理解中，请补充以下信息：1. 性能要求：QPS/RT预期？（如：QPS 1000，RT < 50ms）2. 可用性要求：是否需要灰度/降级？3. 时间约束：预期上线时间？（可回复"无特殊要求"跳过）```---## Phase 2: Research & Analysis### 并行执行策略| Task | Dependencies | Group ||------|--------------|-------|| 2a 现有系统调研（KB匹配） | KB路径 | A（可并行） || 2b 代码库分析 | 代码仓库路径 | A（可并行） || 2c 安全调研 | 需求文档 | A（可并行） || 2d 技术调研 | KB匹配结果 | B（依赖 Group A） || 2e 性能调研 | 代码分析结果 | B（依赖 Group A） |**执行指令：** 在单次 `task` 工具调用中同时发起 Group A 的 3 个子任务，等待完成后再发起 Group B。```task([  {    description: "KB匹配",    prompt: "【只读调研任务】搜索 {kbPath} 的 concepts/、sources/、code/classes/、code/modules/ 目录，匹配与 '{需求关键词}' 相关的内容。返回：匹配文件路径、关键摘要、可复用的类/接口列表。禁止修改任何文件。"  },  {    description: "代码库分析",    prompt: "【只读调研任务】分析代码仓库 {codeRepoLocalPath} 的项目结构、模块划分、技术栈。识别与 '{需求关键词}' 相关的现有 Service/Repository/DTO 类。返回：项目结构概览、可复用类列表、技术栈信息。禁止修改任何文件。"  },  {    description: "安全调研",    prompt: "【只读调研任务】扫描需求文档内容，按 safety-rules.md 的关键词触发规则检测资损/数据/接口安全风险。返回：命中的关键词、风险等级、应对方案建议。禁止修改任何文件。"  }])```### 2a 现有系统调研（知识库匹配）搜索范围：`concepts/`（业务/技术概念）、`sources/`（文档摘要）、`code/classes/`（核心类）、`code/modules/`（模块概述）### 2b 代码库分析分析内容：项目结构、技术栈、核心模块、现有架构模式、可复用类/方法### 2c 安全与合规调研> 关键词触发规则、语义区分逻辑、检测流程详见 `safety-rules.md`基于 Phase 1 的需求理解结果，自动扫描产品文档关键词，按读写操作区分风险等级。### 2d 技术调研| Research Area | Method | Output ||---------------|--------|--------|| **最佳实践** | 搜索知识库/行业文档 | 设计模式建议 || **技术选型对比** | 分析相似场景实现 | 选型推荐 || **行业方案** | 知识库匹配 | 架构参考 |### 2e 性能与规模基准收集现有系统性能数据（现有接口QPS、数据库容量、缓存容量）。用户可回复"暂无数据"跳过，方案中将标注 `[待补充]`。---## Phase 3: Complexity Judgment### 量化评估（基于 Phase 2 调研结果预估，自动执行，无需确认）| Metric | Calculation | 说明 ||--------|-------------|------|| 新增文件数 | min(预估文件数 × 10, 30) | 上限 30 分 || 新增接口数 | min(预估接口数 × 8, 25) | 上限 25 分 || 跨模块数 | min(模块数 × 10, 20) | 上限 20 分 || DB变更 | min(表数 × 15, 15) | 上限 15 分 || 外部依赖 | min(新依赖 × 10, 10) | 上限 10 分 |**计算公式：** `总分 = Σ min(数量 × 系数, 上限)`，满分 100 分。**Level thresholds:**| Level | Score | Process | 预期场景 ||-------|-------|---------|---------|| **L1 快速** | 0-25 | 自动执行，无交互 | 单接口新增、简单 CRUD || **L2 标准** | 26-55 | 仅变更清单确认 | 跨模块功能、涉及 DB 变更 || **L3 完整** | 56+ | 分段设计+摘要确认 | 系统级改造、多外部依赖 |### Level → 文档章节映射| 章节 | L1 快速 | L2 标准 | L3 完整 ||------|---------|---------|---------|| ChangeLog | ✅ | ✅ | ✅ || 1. 业务背景和目标 | ✅（简写） | ✅ | ✅ || 2. 需求分析 | ❌ 省略 | ✅ | ✅ || 3. 整体技术方案 | ✅（简写） | ✅ | ✅ || 4. 详细设计 | ✅（仅接口定义） | ✅ | ✅（含架构图描述） || 4.x 实施步骤拆解 | ✅ | ✅ | ✅ || 5. 技术风险分析 | ❌ 省略（无特殊风险时） | ✅ | ✅（含稳定性/资损分析） || 6. 测试范围分析 | ❌ 省略 | ✅（简写） | ✅ || 7. 发布计划 | ✅（简写） | ✅ | ✅（含灰度方案） |> 各 Level 完整文档示例详见 `examples.md`---## Phase 4: Design Generation### 框架代码原则**技术方案中的代码应为框架代码，而非详细实现代码。**| Code Type | Should Include | Should NOT Include ||-----------|----------------|-------------------|| **接口定义** | 方法签名、参数类型、返回类型 | 方法内部实现逻辑 || **类结构** | 类名、关键字段、核心方法列表 | 方法体、私有方法 || **流程代码** | 主要步骤框架、关键节点 | 详细条件判断、循环细节 || **配置代码** | 配置项名称、类型 | 具体配置值 |**框架代码自检规则：**- ✅ 方法体内不超过 1 行伪代码注释- ✅ 无 if/for/while/try-catch 等控制流语句- ✅ 无具体的异常处理逻辑- ❌ 出现 `new`、`throw`、`.get()`、`.set()` 等实现细节 → 需删除**正确的框架代码示例：**```java// ✅ 正确：接口定义 + 核心方法签名public interface SkuQueryService {    /** 查询SKU信息 */    SkuInfoDTO querySku(SkuQueryRequest request);    /** 批量查询SKU */    List<SkuInfoDTO> batchQuerySku(SkuBatchQueryRequest request);}// ✅ 正确：类结构框架（仅展示字段和方法签名）public class SkuQueryServiceImpl implements SkuQueryService {    private SkuInfoDomainService skuInfoDomainService;    private ClusterEngineRepository clusterEngineRepository;    // 查询SKU信息：参数校验 → 查询簇数据 → 组装返回    SkuInfoDTO querySku(SkuQueryRequest request);}```**错误的框架代码（禁止出现）：**```❌ 禁止包含方法体实现（if/throw/new/具体调用链等）❌ 禁止包含私有方法定义❌ 禁止出现超过 10 行的代码块```**详细设计章节规范：** 使用**表格 + 设计要点**代替大段代码：```markdown## 4. 详细设计### 4.1 SkuQueryService**类定义：**- 所在模块：link-service- 职责：SKU信息查询入口**接口方法：**| 方法 | 参数 | 返回值 | 说明 ||------|------|--------|------|| querySku | SkuQueryRequest | SkuInfoDTO | 主查询接口 |**依赖：**- SkuInfoDomainService：信息组装- ClusterEngineRepository：簇数据查询**设计要点：**- 使用责任链模式处理多数据源组装- 缓存策略：热点SKU缓存10分钟```---## Phase 5: Summary Preview**输出前必须展示方案摘要，用户确认后再生成完整文档。****摘要模板：**```【方案摘要】## 核心设计- （3-5 条核心设计决策）## 变更范围| 层级 | 新增文件 | 修改文件 ||------|----------|----------|| ... | ... | ... |## 关键风险- （风险点 + 应对措施）## 实施步骤（共N步）1. ...确认此方案？确认后将生成完整文档。```> 用户拒绝摘要时的修订流程详见 `exception-and-revision.md`---## Phase 6: Output### 输出位置`{KB root}/{outputPath}/YYYY-MM-DD-{需求关键词}-design.md`**outputPath 取值优先级：**1. KB-META.md 中的 `outputPath` 字段2. 若未配置，默认 `docs/plans/`> templatePath 使用规则详见 `kb-meta-spec.md`> 默认模板文件：`技术方案模版.md`（位于 skill 同目录下）### 文档结构（完整版）```markdown# {需求标题} 技术方案## ChangeLog| 版本 | 日期 | 变更人 | 备注 ||------|------|--------|------|| v1.0 | YYYY-MM-DD | {author} | 初始版本 |## 1. 业务背景和目标## 2. 需求分析## 3. 整体技术方案## 4. 详细设计（框架代码）## 4.x 实施步骤拆解## 5. 技术风险分析## 6. 测试范围分析## 7. 发布计划```**{author} 取值：** 优先从环境变量 user_info.name 获取，否则标注 `[请填写]`。**不同 Level 的章节取舍参见 Phase 3 的 "Level → 文档章节映射" 表。**### Output Quality Checklist**输出前必须自查，不满足任一项则补充后再输出：**| # | Requirement | 验证方法 ||---|-------------|----------|| 1 | ChangeLog 有版本记录 | 检查版本号、日期、变更人、备注四列齐全 || 2 | 三要素来源已标注 | 检查 KB 名称、代码仓库路径、产品文档来源 || 3 | 变更文件路径完整 | 每个文件有 `模块/文件名.java` 格式的完整路径 || 4 | 风险应对措施具体 | 风险描述有具体方案（如"价格校验开关"），而非空泛的"加强校验" || 5 | 框架代码无实现细节 | 代码块中无方法体、无 if/for/while、无 throw || 6 | 实施步骤编号连续 | 步骤从 1 开始连续编号，无跳跃 || 7 | 文档章节与 Level 匹配 | L1 可省略的章节已省略，L3 必填的章节均存在 || 8 | 无悬空标记 | 文档中无 `TODO`，缺失数据统一用 `[待补充]` 标注 |### 文档命名规范**格式：** `YYYY-MM-DD-{需求关键词}-design.md`**禁止：** `design.md`（无日期）、`v1-design.md`（版本号在 ChangeLog 管理）---## Quick Reference| Phase | Action | Auto? | Parallel? | User Input ||-------|--------|-------|-----------|------------|| 0 | 三要素识别 | ✅ | — | **仅缺失时询问** || 1 | 需求理解 | ✅ | — | 补充非功能/约束（可选） || 2a | KB匹配 | ✅ | ✅ Group A | 无 || 2b | 代码分析 | ✅ | ✅ Group A | 无 || 2c | 安全调研 | ✅ | ✅ Group A | 无 || 2d | 技术调研 | ✅ | ❌ Group B | 无 || 2e | 性能调研 | ✅ | ❌ Group B | 补充数据（可选） || 3 | 复杂度判断 | ✅ | — | 无 || 4 | 设计生成 | ✅ | — | 无 || 5 | **摘要预览** | ✅ | — | **必须确认** || 6 | 输出文档 | ✅ | — | 无 |**交互点：1-3次（仅关键决策点）****并行执行：Phase 2 Group A 任务通过单次 task 工具调用同时启动**---## Guard Rails### 实时检测规则（生成过程中持续检查）| # | 检测信号 | 正确行为 | 错误行为 ||---|---------|---------|---------|| 1 | 用户说"直接给完整方案" | 展示摘要价值，询问 A/B 选择 | 跳过摘要直接输出 || 2 | 代码块中出现 if/for/while | 删除实现细节，改为设计要点描述 | 保留详细实现代码 || 3 | 三要素有缺失 | 询问用户补充 | 静默跳过或报错停止 || 4 | Phase 2 有多个无依赖任务 | 单次 task 工具调用并行执行 | 分多次串行执行 || 5 | 用户拒绝摘要 | 进入修订流程，询问原因 | 报错或无法处理 || 6 | 数据缺失（QPS/RT等） | 标注 `[待补充]` 继续执行 | 阻塞流程等待用户 || 7 | KB/代码仓库找不到 | 询问用户补充路径 | 报错停止 || 8 | 文档章节编号不连续 | 按 Level→章节映射表补齐或省略 | 随意跳过编号 || 9 | 输出前未自查 | 执行 Output Quality Checklist | 直接输出 || 10 | 修订无 diff 展示 | 展示变更点和未变更点摘要 | 重新输出整篇文档无标注 |### 用户强制跳过流程时的处理**用户说："直接给我完整方案"/"别浪费时间"时：**```技术方案生成流程要求先确认设计方向，这能：1. 确保方案与需求匹配（避免返工）2. 快速发现设计偏差（减少评审时间）3. 摘要确认只需30秒您可以选择：A. 确认摘要后输出完整文档（推荐）B. 明确告知风险后直接输出（需您确认跳过流程）请选择 A 或 B。```**用户选择 B 时的处理：**- 记录用户确认跳过流程- 输出文档时在 ChangeLog 标注"用户确认跳过摘要确认流程"- **仍需展示最简摘要（核心设计点 3 条）**，只是不再等待确认> 异常处理策略、上下文恢复、修订机制详见 `exception-and-revision.md`---## Downstream Handoff### 技术方案 → 技术评审衔接| 衔接方式 | 说明 ||---------|------|| **评审独立性** | 技术评审需在新对话中进行，避免确认偏误 || **方案文档路径** | 输出文档路径可直接传递给 kb-tech-review || **评审触发提示** | 方案生成后提示用户在新对话中评审 |**推荐评审流程：**```技术方案生成完成 → 提示用户："技术方案已生成：{方案文档路径}建议在新对话中进行技术评审（避免确认偏误）。在新对话中输入：/kb-tech-review {方案文档路径}"```**禁止行为：**- ❌ **不要**在当前对话中立即执行 kb-tech-review- ❌ **不要**在方案生成后问"是否现在评审"- ✅ **必须**提示用户在新对话中进行评审---### 技术方案 → 代码实现衔接用户可跳过技术评审，直接从技术方案进入代码实现阶段。| 衔接方式 | 说明 ||---------|------|| **触发技能** | kb-just-coding || **必要输入** | 需求文档/PRD + 技术方案文档路径 || **实施步骤清单** | 方案中的 "4.x 实施步骤拆解" 可直接作为开发任务拆分 || **框架代码引导** | 方案中的接口定义和类结构可直接复制到代码仓库 || **变更文件清单** | 方案中的变更范围表格可作为 CR 的 checklist |**推荐提示语：**```技术方案生成完成 → 提示用户："如需直接进入代码实现，可在新对话中输入：使用 kb-just-coding 技能，PRD：{PRD文档路径}，技术方案：{方案文档路径}"```**推荐完整流程：**```技术方案确认 → 新对话中技术评审 → 评审通过后按实施步骤开发 → 每步完成后对照方案自查 → 提交 CR```**快速流程（跳过评审）：**```技术方案确认 → 新对话中直接使用 kb-just-coding 实现代码 → 自测 → 提交 CR```

目的：  帮助用户写出最专业、资深的技术方案文档三要素识别：  prd/产品文档（用户提供），知识库（全局搜KB-META.md可得），代码仓库（知识库中关联）hard gate：     ○ 三要素不齐全时，提示用户提供    ○ 三要素齐全时，才继续后续步骤    ○ 方案中整体方案，应包含清晰的整体架构图    ○ 方案中仅输出框架代码，不输出详细实现代码     ○ 完整文档输出前，必须先展示方案摘要并获得用户确认    ○ 如果用户拒绝方案摘要，Skill 会进入修订流程    ○ 用户接受方案后，将完整技术方案落成md文件，输出路径：{KB root}/{outputPath}/YYYY-MM-DD-{需求关键词}-design.md思路：    ○ 理解需求        ■ 业务目标：背景、价值、目标         ■ 功能需求：功能点、接口、流程         ■ 非功能需求：QPS、RT、可用性、灰度、降级         ■ 约束条件：上线时间、资源限制、技术约束    ○ 开多个sub-agent，并发执行 知识库匹配、代码仓分析 、安全调查        ■ 知识匹配：从知识库中匹配需求相关的信息        ■ 理解代码沉淀：分析代码仓库结构、模块划分、技术栈、可复用类和接口        ■ 安全调查：包括安全调查、数据安全、接口安全    ○ 关键步骤是头脑风暴+技术调研        ■ 考虑prd实现完整性、技术风险、安全合规        ■ 结合已有方案或行业实践进行技术调研         ■ 灵活地使用并借鉴已有的技术架构及代码实现        ■ 收集 QPS、RT、容量、缓存等性能基准        ■ ... 探索        ■ 二次反查，补缺实现方案需要的知识+现有代码架构    ○ 询问用户技术方案的交互方式，直接提供最佳解法 or 提供2-3种方案供用户选择    ○ 技术方案文档结构如下，不同复杂度需求可适当裁剪章节        ■ {需求标题} 技术方案 ## ChangeLog ## 1. 业务背景和目标 ## 2. 需求分析 ## 3. 整体技术方案 ## 4. 详细设计（框架代码） ## 4.x 实施步骤拆解 ## 5. 技术风险分析 ## 6. 测试范围分析 ## 7. 发布计划    ○ 详细设计应优先使用：表格、类职责说明、依赖关系、设计要点、实施步骤    ○ Skill 的交互原则：减少不必要沟通，只在关键决策点确认方案模版：    ○ 提供模版路径下游衔接：    ○ 提示用户开新对话，进行代码评审kb-tech-review，或直接进入编写代码kb-just-coding

---name: kb-tech-solutiondescription: Use when generating a senior-grade technical design document from a PRD in a KB-META.md-structured knowledge base.---# kb-tech-solution 技术方案生成## Overview**角色定义：** 你是一名Java资深技术架构师，擅长将产品需求转化为可落地、可评审、可执行的技术方案文档。**核心原则：**- 三要素齐全才能继续，缺一不可- 整体方案必须包含清晰的整体架构图- 详细设计只输出**框架代码**（接口、类结构、依赖、设计要点），不写实现细节- 完整文档输出前必须先展示方案摘要并获得用户确认- 用户拒绝摘要 → 进入修订流程- 减少非必要沟通，只在关键决策点确认**配套文档：**- `技术方案模版.md` — 方案文档模板（指向 KB 内 kb-source/技术方案模版.md）---## Hard Gates（禁止跳过）| # | 检查项 | 不通过时的行为 ||---|--------|---------------|| 1 | 三要素齐全（PRD / KB / 代码仓库） | 缺什么问什么，直到补齐 || 2 | 整体方案含架构图（mermaid / PlantUML / ASCII 任一） | 强制生成架构图后再继续 || 3 | 详细设计为框架代码（无 if/for/throw/方法体） | 删除实现细节，改为表格 + 设计要点 || 4 | 输出前先展示方案摘要并获得用户确认 | 不允许直接输出完整文档 || 5 | 输出路径为 `{KB root}/{outputPath}/YYYY-MM-DD-{需求关键词}-design.md` | 不允许用其他路径或文件名 |---## When to Use- 用户给出产品文档/PRD，需要生成技术方案- 工作目录或上下文可定位到 KB-META.md- 需要可评审、可执行、专业级别的技术设计文档**Do NOT use for:**- 纯代码修改（无设计变更）- 配置调整、参数变更- 非 KB-META.md 结构的项目---## Phase 0: 三要素识别| Element | 发现方式 | 缺失行为 ||---------|----------|---------|| **产品文档 / PRD** | 用户提供（粘贴 / 路径 / 链接） | ❌ 必须用户补充 || **知识库** | 全局搜索 `KB-META.md`，多个则询问选择 | ❌ 必须用户补充 || **代码仓库** | 读取 KB-META.md 的 `codeRepoLocalPath` | ❌ 必须用户补充 |**三要素齐全前不进入 Phase 1。** 缺什么直接问什么：```【三要素识别】✅ 产品文档：用户描述（新增 SKU 批量查询接口）❌ 知识库：当前目录未找到 KB-META.md，请提供 KB 路径或名称❌ 代码仓库：KB-META.md 未配置 codeRepoLocalPath，请提供代码仓库本地路径```**完整识别后静默继续：**```三要素识别完成，继续执行需求分析...```---## Phase 1: 需求理解（四维度）| 维度 | 内容 | 来源 ||------|------|------|| **业务目标** | 背景、价值、目标 | PRD || **功能需求** | 功能点、接口、流程 | PRD || **非功能需求** | QPS、RT、可用性、灰度、降级 | PRD，缺失则询问用户 || **约束条件** | 上线时间、资源限制、技术约束 | PRD，缺失则询问用户 |非功能 / 约束（一次问完，可跳过）---## Phase 2: 并行调研（sub-agents）**单次 `Agent` 工具调用中并发发起 3 个子任务，禁止串行执行。**```Agent([  {    description: "KB匹配",    subagent_type: "Explore",    prompt: "【只读调研任务】搜索知识库 {kbPath} 的 concepts/、sources/、code/classes/、code/modules/，匹配与 '{需求关键词}' 相关的内容。返回：匹配文件路径、关键摘要、可复用的类/接口/已有方案。禁止修改任何文件。"  },  {    description: "代码仓分析",    subagent_type: "Explore",    prompt: "【只读调研任务】分析代码仓库 {codeRepoLocalPath} 的项目结构、模块划分、技术栈。识别与 '{需求关键词}' 相关的现有 Service / Repository / DTO / Manager 等可复用类与接口。返回：项目结构概览、可复用类列表、技术栈、设计模式。禁止修改任何文件。"  },  {    description: "安全调查",    subagent_type: "Explore",    prompt: "【只读调研任务】基于 PRD 评估安全风险，覆盖：业务安全（资损、权限、风控）、数据安全（敏感字段、加密、合规）、接口安全（鉴权、限流、防刷）。返回：风险等级、命中点、应对建议。禁止修改任何文件。"  }])```**输出整合：** 三个子任务返回后，将关键发现汇总进 Phase 3。---## Phase 3: 头脑风暴 + 技术调研基于 Phase 2 结果系统思考。以下维度为**起点而非边界**——除这些维度外，你应主动识别本次需求特有的其他关键问题（如领域特性、数据一致性模型、容灾粒度、灰度策略等），自行扩展。**起步维度（必查）：**| 维度 | 思考点 ||------|--------|| **PRD 完整性** | 需求是否有遗漏？边界条件、异常分支是否覆盖？ || **技术风险** | 性能瓶颈、单点故障、数据一致性、向前兼容 || **安全合规** | Phase 2 安全调查命中点对应措施 || **行业实践** | 同类场景的成熟方案、知识库历史设计 || **架构复用** | 已有架构能否扩展？避免重复造轮子 || **性能基准** | 当前接口 QPS / RT、数据库容量、缓存策略 || **+ 自行扩展** | 任何 Phase 2 信息不足以支撑决策的关键问题 |### 信息冲突当kb中返回信息与代码仓库返回信息冲突/不一致时，优先采纳代码仓库信息### 二次取证（按需回查 KB / 代码仓）Phase 2 的并发调研是一次性宽搜，本阶段思考时**必然会发现信息不足**——例如某个类的具体方法、某个表的 schema、某个历史方案的细节。**此时应再次调用工具回查**，禁止凭印象推断。**回查触发信号（出现即必须取证）：**- 想引用某个类/方法/接口签名，但 Phase 2 摘要里没有完整签名- 评估方案 A vs B，但缺少现有实现的关键细节（如锁粒度、事务边界、缓存 key 设计）- 风险评估涉及某个上下游模块，但不清楚其调用方/被调用方- 性能基准需要具体数据（QPS、表行数、缓存命中率），但 Phase 2 未覆盖**取证方式（按需选择）：**| 场景 | 工具 | 用法 ||------|------|------|| 小范围确认（1-2 个文件/类） | `Read` / `Grep` | 直接读取或精确搜索 || 中等范围探索（多文件、关联调用） | `Agent(subagent_type: "Explore")` | 单个补充调研子任务 || 多个独立追问（≥2 项） | `Agent([...])` 并发 | 一次发起多个补充子任务 |**取证后必须回到 Phase 3 思考闭环：** 取证 → 更新判断 → 继续下一个维度，直至所有关键决策点都有依据支撑，再进入 Phase 4。---## Phase 4: 摘要预览（必须确认）**完整文档前必须先展示摘要，等待用户确认。****用户拒绝时进入修订流程，询问用户建议并修订**修订后**重新展示摘要**，循环直至确认。---## Phase 5: 输出完整文档### 输出路径`{KB root}/{outputPath}/YYYY-MM-DD-{需求关键词}-design.md`- `outputPath`：从 KB-META.md 读取；未配置则默认 `docs/plans/`- 日期：当前日期（YYYY-MM-DD）- 需求关键词：从 PRD 标题或核心动作提取，短小、用连字符（如 `sku-batch-query`）### 文档结构按 `技术方案模版.md` 填充，固定章节：```markdown# {需求标题} 技术方案## ChangeLog## 1. 业务背景和目标## 2. 需求分析## 3. 整体技术方案     ← 必含架构图## 4. 详细设计（框架代码）## 4.x 实施步骤拆解## 5. 技术风险分析## 6. 测试范围分析## 7. 发布计划```**裁剪规则：** 复杂度低时可省略章节，但 §1 / §3 / §4 / §4.x 不可省。### 详细设计章节规范**优先使用以下表达方式，避免大段代码：**| 表达方式 | 适用场景 ||---------|---------|| **表格** | 接口列表、字段定义、配置项、状态机 || **类职责说明** | 类的定位、核心方法签名 || **依赖关系** | 上下游模块依赖、调用链（推荐 mermaid 时序图 / 组件图） || **设计要点** | 关键算法思路、缓存策略、并发控制、降级方案 || **实施步骤** | 编号、依赖、产出物、验收标准 |**框架代码自检规则：**- ✅ 方法体最多 1 行伪代码注释- ✅ 无 if / for / while / try-catch 等控制流- ❌ 出现 `new` / `throw` / `.get()` / `.set()` 等实现细节 → 删除### 整体架构图要求`§3 整体技术方案` 必须含至少一种架构图：| 图类型 | 适用场景 ||--------|---------|| **组件图**（mermaid graph） | 模块/服务划分、依赖关系 || **时序图**（mermaid sequenceDiagram） | 跨模块调用链、异步流程 || **数据流图** | 数据流转、ETL、消息流 || **部署图** | 多机房、多集群、网络拓扑 || **ASCII 图** | 简单结构、纯文本场景兜底 |### 输出前自查清单| # | 检查项 ||---|--------|| 1 | ChangeLog 含版本 / 日期 / 变更人 / 备注四列 || 2 | 三要素来源已标注（KB / 代码仓 / PRD） || 3 | §3 含整体架构图 || 4 | §4 无实现细节（无 if / for / throw / 方法体） || 5 | 变更文件路径完整（`模块/文件名.java`） || 6 | 实施步骤连续编号、有验收标准 || 7 | 无 `TODO`，缺失数据统一用 `[待补充]` || 8 | 文件名为 `YYYY-MM-DD-{关键词}-design.md` |---## Quick Reference| Phase | 动作 | 自动 | 需用户输入 ||-------|------|------|-----------|| 0 | 三要素识别 | ✅ | 仅缺失时询问 || 1 | 需求理解 | ✅ | 非功能 / 约束（一次问完，可跳过） || 2 | 并行调研（3 个 sub-agent） | ✅ | 无 || 3 | 头脑风暴 + 技术调研 | ✅ | 无 || 4 | 摘要预览 | ✅ | **必须确认** || 5 | 输出完整文档 | ✅ | 无 |**交互点：1-2 次**（三要素补全 + 摘要确认）**并行执行：Phase 2 在单次 Agent 调用中同时启动 3 个子任务**---## Downstream Handoff技术方案生成完成后，**提示用户在新对话中**继续，不在当前对话执行下游 skill：```✅ 技术方案已生成：{方案文档路径}下一步可在新对话中选择：- 评审方案：/kb-tech-review {方案文档路径}（推荐，避免确认偏误）- 直接编码：使用 kb-just-coding，PRD：{PRD 路径}，技术方案：{方案文档路径}```**禁止：** 在当前对话中立即执行 kb-tech-review 或 kb-just-coding（评审独立性要求）。

# 维度评分（对称的加分 vs 扣分）按 stage 选对应维度。每个维度都同时有加分项和扣分项：## tech_solution (满分 100)- **业务覆盖度 25**：  - +1~+3/条 可核实的 PRD 字段/错误码字面对齐（如「错误码 `TAG_LIMIT_EXCEEDED` 与 PRD §5 一致」）  - +1~+2 对业务场景的深入分析（数据规模、调用量、性能约束等量化描述）  - +1~+2 核心实体/服务/接口的识别完整（不遗漏 PRD 中的关键模块）  - -2~-5/条 用「应该 / 建议 / 完善」描述但无落点  - -3 PRD 中的核心功能点未覆盖- **设计合理性 25**：  - +2~+4 架构分层清晰，模块职责边界明确（如 controller→service→domain→infrastructure 各层职责不交叉）  - +2~+3 调用链路图/架构图表达清晰，上下游关系一目了然  - +1~+2 调用 mkt-link 真实存在的 utility / convention（如 `BaseClusterEngineService.executeWithRateLimitAndTrack`）  - -3~-5 架构分层混乱，职责不清  - -3~-8 重复造轮子（项目已有同等设施但候选另起一套）- **详细设计粒度 20**：  - +1~+2/条 真实文件:行号、方法签名、配置数值、SQL DDL  - +2~+3 接口签名完整（入参、出参、异常码均有定义）  - +1~+2 数据库表设计合理（字段类型、索引策略、分区方案）  - +1~+2 关键逻辑有伪代码或核心代码片段，可直接指导实现  - -3 整段抽象描述无具体落点  - -3~-5 方案存在明显技术不可行点（如违反框架约束、性能不达标无对策）- **风险与回滚 15**：  - +2~+3 风险项识别全面（性能风险、兼容性风险、数据一致性风险、并发风险等）  - +2~+3 每个风险有对应缓解措施，措施具体可操作  - +1~+2 灰度策略清晰（灰度维度、扩量节奏、观察指标）  - +1~+2 回退方案明确（触发条件、回退步骤、回退验证）  - +1~+2 上线步骤有序（依赖顺序、配置先行、流量切换）  - -3~-5 仅列风险不给缓解措施  - -3~-5 无灰度/回退计划或计划过于粗略- **反编造与待确认处理 15**：按上述编造分级；待确认处理见反作弊规则 #5  - +2~+3 对 PRD 中「待确认」事项有合理追问或假设说明  - +1~+2 不确定内容明确标注为待确认，未编造成事实  - -5~-10 编造不存在的类/接口/字段/表（按 L1~L3 分级扣分）## tech_review (满分 100)- **维度全面性 25**：+ 覆盖多维度 / - 仅停留在单一维度- **高优问题识别 25**：  - +3~+5/条 给出具体行号证据 + 可操作订正方案  - -3/条 高优问题仅描述而无定位证据- **编造检测 20**：候选识别编造的能力（按上述分级评判候选的判定是否准确）- **修订建议可操作性 15**：+ 具体到文件/方法 / - 仅指方向- **立场独立性 15**：+ 独立反查并指出原方案问题 / - 仅默认接受原方案声明## coding (满分 100)- **修改位置正确性 20**：可核实的真实文件路径 + 行号- **业务逻辑正确性 27**：与 PRD §业务规则对齐；与代码实际 utility 一致- **项目风格一致性 13**：+ 沿用 mkt-link 现有命名 / 包结构 / - 引入仓内零先例的模式- **编译/静态检查 17**（含降级）：javac 单文件通过 2 + LLM 静态检查通过 3 = 5；其余 12 给业务编译合理性- **兼容回归风险 13**：+ 明确说明改动影响范围与需回归的旧链路 / - 未识别对原有功能的潜在影响。- **变更说明清晰度 10**：commit message / changelist 完整度## pre_test (满分 100)- **场景覆盖 30**：覆盖 PRD 验收 + 评审订正点- **用例可执行性 25**：+ 前置/步骤/期望/验证点齐 / - 缺执行细节- **数据需求清晰度 20**：+ 给出 SQL / mock / 接口入参示例 / - 仅文字描述- **异常与边界 15**：+ 覆盖参数异常、下游失败、超时、空数据、并发等边界场景 / - 只覆盖正常流程- **回归点识别 10**：+ 明确列出受影响的旧功能、旧接口、旧链路 / - 只测新功能，遗漏原有功能影响## problem_solve (满分 100)- **SLS 查询有效性 25**：+ 具体可执行 query语句 + 命中样本量 / - 仅描述查询方向- **代码定位与证据链完整性 25**：+ 代码定位准确 + 调用链清晰 + 证据闭环完整 / - 仅文字推断 - **根因可信度 25**：+ 多条独立证据收敛 / - 单点猜测- **修复建议合理性 15**：+ 短中长期分层 + 副作用标注 / - 仅一句建议- **复现/验证步骤 10**：+ 命令级可复现 / - 仅描述思路