Buckets:
AnonymousSpottedToad/human_verified_bucket / codebase /python /shangyankeji_super-dev /super_dev /knowledge_tracker.py
| """ | |
| 知识引用追踪器 | |
| 记录 pipeline 执行过程中引用了哪些知识文件,生成知识引用报告。 | |
| 让知识库从「静态仓库」变成「可追溯治理资产」。 | |
| 用法: | |
| tracker = KnowledgeTracker(knowledge_dir="knowledge") | |
| tracker.track_reference("knowledge/security/01-standards/web-security-complete.md", | |
| phase="backend", usage_type="constraint", relevance_score=0.95) | |
| report = tracker.generate_report("myapp", "run-001") | |
| tracker.save_report(report, output_dir="output") | |
| """ | |
| from __future__ import annotations | |
| import json | |
| import re | |
| import uuid | |
| from dataclasses import dataclass, field | |
| from datetime import datetime, timezone | |
| from pathlib import Path | |
| from typing import Any | |
| # --------------------------------------------------------------------------- | |
| # Data classes | |
| # --------------------------------------------------------------------------- | |
| class KnowledgeReference: | |
| """单条知识引用记录""" | |
| knowledge_file: str | |
| """知识文件路径(相对于项目根目录)""" | |
| phase: str | |
| """引用阶段: research / docs / spec / frontend / backend / quality / delivery""" | |
| usage_type: str | |
| """使用类型: constraint(硬约束) / guidance(指导) / reference(参考)""" | |
| matched_tags: list[str] = field(default_factory=list) | |
| """匹配的标签""" | |
| relevance_score: float = 1.0 | |
| """相关性分数 0‑1""" | |
| excerpt: str = "" | |
| """引用的关键内容摘要""" | |
| timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat()) | |
| """引用时间戳""" | |
| def to_dict(self) -> dict[str, Any]: | |
| return { | |
| "knowledge_file": self.knowledge_file, | |
| "phase": self.phase, | |
| "usage_type": self.usage_type, | |
| "matched_tags": self.matched_tags, | |
| "relevance_score": self.relevance_score, | |
| "excerpt": self.excerpt, | |
| "timestamp": self.timestamp, | |
| } | |
| class KnowledgeTrackingReport: | |
| """知识引用报告""" | |
| project_name: str | |
| pipeline_run_id: str | |
| timestamp: str | |
| total_knowledge_files: int | |
| """知识库总文件数""" | |
| referenced_files: int | |
| """引用的文件数(去重)""" | |
| hit_rate: float | |
| """命中率 = referenced_files / total_knowledge_files""" | |
| references: list[KnowledgeReference] | |
| """所有引用记录""" | |
| unreferenced_domains: list[str] | |
| """未引用的领域""" | |
| coverage_by_domain: dict[str, dict[str, Any]] = field(default_factory=dict) | |
| """按领域的覆盖率统计""" | |
| # ------------------------------------------------------------------ | |
| # 输出 | |
| # ------------------------------------------------------------------ | |
| def to_markdown(self) -> str: | |
| """生成 Markdown 格式的知识引用报告""" | |
| lines: list[str] = [ | |
| "# 知识引用追踪报告", | |
| "", | |
| f"- **项目**: {self.project_name}", | |
| f"- **Pipeline Run ID**: {self.pipeline_run_id}", | |
| f"- **生成时间**: {self.timestamp}", | |
| "", | |
| "## 总览", | |
| "", | |
| "| 指标 | 值 |", | |
| "|------|------|", | |
| f"| 知识库总文件数 | {self.total_knowledge_files} |", | |
| f"| 引用文件数 | {self.referenced_files} |", | |
| f"| 命中率 | {self.hit_rate:.1%} |", | |
| f"| 总引用次数 | {len(self.references)} |", | |
| "", | |
| ] | |
| # 按阶段统计 | |
| phase_counts: dict[str, int] = {} | |
| for ref in self.references: | |
| phase_counts[ref.phase] = phase_counts.get(ref.phase, 0) + 1 | |
| if phase_counts: | |
| lines.append("## 按阶段引用统计") | |
| lines.append("") | |
| lines.append("| 阶段 | 引用次数 |") | |
| lines.append("|------|----------|") | |
| for phase, count in sorted(phase_counts.items()): | |
| lines.append(f"| {phase} | {count} |") | |
| lines.append("") | |
| # 按使用类型统计 | |
| type_counts: dict[str, int] = {} | |
| for ref in self.references: | |
| type_counts[ref.usage_type] = type_counts.get(ref.usage_type, 0) + 1 | |
| if type_counts: | |
| lines.append("## 按使用类型统计") | |
| lines.append("") | |
| lines.append("| 类型 | 引用次数 |") | |
| lines.append("|------|----------|") | |
| for utype, count in sorted(type_counts.items()): | |
| lines.append(f"| {utype} | {count} |") | |
| lines.append("") | |
| # 领域覆盖率 | |
| if self.coverage_by_domain: | |
| lines.append("## 领域覆盖率") | |
| lines.append("") | |
| lines.append("| 领域 | 总文件 | 引用文件 | 覆盖率 |") | |
| lines.append("|------|--------|----------|--------|") | |
| for domain in sorted(self.coverage_by_domain): | |
| info = self.coverage_by_domain[domain] | |
| lines.append( | |
| f"| {domain} | {info['total']} | {info['referenced']} | {info['rate']:.0%} |" | |
| ) | |
| lines.append("") | |
| # 未引用领域 | |
| if self.unreferenced_domains: | |
| lines.append("## 未引用领域") | |
| lines.append("") | |
| for domain in sorted(self.unreferenced_domains): | |
| lines.append(f"- {domain}") | |
| lines.append("") | |
| # 引用明细 | |
| if self.references: | |
| lines.append("## 引用明细") | |
| lines.append("") | |
| for i, ref in enumerate(self.references, 1): | |
| lines.append(f"### {i}. {ref.knowledge_file}") | |
| lines.append("") | |
| lines.append(f"- **阶段**: {ref.phase}") | |
| lines.append(f"- **类型**: {ref.usage_type}") | |
| lines.append(f"- **相关性**: {ref.relevance_score:.2f}") | |
| if ref.matched_tags: | |
| lines.append(f"- **标签**: {', '.join(ref.matched_tags)}") | |
| if ref.excerpt: | |
| lines.append(f"- **摘要**: {ref.excerpt}") | |
| lines.append("") | |
| return "\n".join(lines) | |
| def to_json(self) -> dict[str, Any]: | |
| """导出 JSON 格式""" | |
| return { | |
| "project_name": self.project_name, | |
| "pipeline_run_id": self.pipeline_run_id, | |
| "timestamp": self.timestamp, | |
| "summary": { | |
| "total_knowledge_files": self.total_knowledge_files, | |
| "referenced_files": self.referenced_files, | |
| "hit_rate": round(self.hit_rate, 4), | |
| "total_references": len(self.references), | |
| }, | |
| "coverage_by_domain": self.coverage_by_domain, | |
| "unreferenced_domains": self.unreferenced_domains, | |
| "references": [ref.to_dict() for ref in self.references], | |
| } | |
| # --------------------------------------------------------------------------- | |
| # 知识文件索引条目 | |
| # --------------------------------------------------------------------------- | |
| class _KnowledgeIndexEntry: | |
| """内部索引条目""" | |
| path: str | |
| """相对路径""" | |
| domain: str | |
| """所属领域(顶层目录名)""" | |
| category: str | |
| """子类别(如 01-standards, 02-playbooks 等)""" | |
| title: str | |
| """从文件名或首行提取的标题""" | |
| tags: list[str] | |
| """从文件名与内容提取的标签""" | |
| # --------------------------------------------------------------------------- | |
| # 有效的阶段和使用类型常量 | |
| # --------------------------------------------------------------------------- | |
| VALID_PHASES = frozenset( | |
| { | |
| "research", | |
| "docs", | |
| "spec", | |
| "frontend", | |
| "backend", | |
| "quality", | |
| "delivery", | |
| } | |
| ) | |
| VALID_USAGE_TYPES = frozenset( | |
| { | |
| "constraint", | |
| "guidance", | |
| "reference", | |
| } | |
| ) | |
| # 领域 -> 相关阶段映射(用于 find_relevant_knowledge 过滤) | |
| _DOMAIN_PHASE_AFFINITY: dict[str, list[str]] = { | |
| "product": ["research", "docs", "spec"], | |
| "design": ["research", "docs", "frontend"], | |
| "architecture": ["docs", "spec", "backend"], | |
| "development": ["docs", "spec", "frontend", "backend"], | |
| "testing": ["quality"], | |
| "security": ["docs", "backend", "quality"], | |
| "cicd": ["quality", "delivery"], | |
| "operations": ["quality", "delivery"], | |
| "data": ["docs", "backend", "quality"], | |
| "data-engineering": ["docs", "backend", "quality"], | |
| "incident": ["quality", "delivery"], | |
| "ai": ["research", "docs", "quality", "delivery"], | |
| "00-governance": ["research", "docs", "spec", "quality", "delivery"], | |
| "frontend": ["frontend", "docs"], | |
| "backend": ["backend", "docs"], | |
| "cloud-native": ["backend", "delivery"], | |
| "devops": ["delivery", "quality"], | |
| "blockchain": ["backend", "spec"], | |
| "edge-iot": ["backend", "spec"], | |
| "industries": ["research", "docs"], | |
| "low-code": ["frontend", "spec"], | |
| "mobile": ["frontend", "spec"], | |
| "quantum": ["research", "spec"], | |
| } | |
| # --------------------------------------------------------------------------- | |
| # KnowledgeTracker | |
| # --------------------------------------------------------------------------- | |
| class KnowledgeTracker: | |
| """知识引用追踪器 | |
| 在 pipeline 执行过程中记录每一次对 knowledge/ 文件的引用, | |
| 最终生成可审计的知识引用报告(Markdown + JSON)。 | |
| Example:: | |
| tracker = KnowledgeTracker("knowledge") | |
| tracker.track_reference( | |
| "knowledge/security/01-standards/web-security-complete.md", | |
| phase="backend", | |
| usage_type="constraint", | |
| relevance_score=0.95, | |
| excerpt="OWASP Top-10 检查清单", | |
| ) | |
| report = tracker.generate_report("myapp", "run-001") | |
| tracker.save_report(report) | |
| """ | |
| def __init__(self, knowledge_dir: str = "knowledge") -> None: | |
| self.knowledge_dir = Path(knowledge_dir) | |
| self.references: list[KnowledgeReference] = [] | |
| self._knowledge_index: dict[str, _KnowledgeIndexEntry] = self._build_index() | |
| # ------------------------------------------------------------------ | |
| # 索引构建 | |
| # ------------------------------------------------------------------ | |
| def _build_index(self) -> dict[str, _KnowledgeIndexEntry]: | |
| """构建知识文件索引(路径 -> 索引条目) | |
| 遍历 knowledge_dir 下所有 .md / .txt / .yml / .yaml 文件, | |
| 提取领域、子类别、标题和标签。 | |
| """ | |
| index: dict[str, _KnowledgeIndexEntry] = {} | |
| if not self.knowledge_dir.exists(): | |
| return index | |
| suffixes = {".md", ".txt", ".yml", ".yaml"} | |
| for filepath in sorted(self.knowledge_dir.rglob("*")): | |
| if not filepath.is_file() or filepath.suffix.lower() not in suffixes: | |
| continue | |
| rel_path = str(filepath) | |
| parts = filepath.relative_to(self.knowledge_dir).parts | |
| domain = parts[0] if len(parts) > 1 else "" | |
| category = parts[1] if len(parts) > 2 else "" | |
| title = self._extract_title(filepath) | |
| tags = self._extract_tags(filepath, domain, category) | |
| index[rel_path] = _KnowledgeIndexEntry( | |
| path=rel_path, | |
| domain=domain, | |
| category=category, | |
| title=title, | |
| tags=tags, | |
| ) | |
| return index | |
| def _extract_title(filepath: Path) -> str: | |
| """从文件首行(# 标题)或文件名提取标题""" | |
| try: | |
| with open(filepath, encoding="utf-8", errors="ignore") as fh: | |
| for line in fh: | |
| line = line.strip() | |
| if line.startswith("#"): | |
| return line.lstrip("#").strip() | |
| if line: | |
| return line[:120] | |
| break | |
| except OSError: | |
| pass | |
| # fallback: 文件名 | |
| return filepath.stem.replace("-", " ").replace("_", " ").title() | |
| def _extract_tags(filepath: Path, domain: str, category: str) -> list[str]: | |
| """从文件名和上下文提取标签""" | |
| tags: list[str] = [] | |
| if domain: | |
| tags.append(domain) | |
| if category: | |
| # 去掉前缀编号 (01-standards -> standards) | |
| clean_cat = re.sub(r"^\d+-", "", category) | |
| if clean_cat: | |
| tags.append(clean_cat) | |
| # 文件名中的关键词 | |
| stem = filepath.stem.lower() | |
| for sep in ("-", "_"): | |
| parts = stem.split(sep) | |
| tags.extend(p for p in parts if len(p) > 2 and p not in ("complete", "md")) | |
| return list(dict.fromkeys(tags)) # 去重保序 | |
| # ------------------------------------------------------------------ | |
| # 引用追踪 | |
| # ------------------------------------------------------------------ | |
| def track_reference( | |
| self, | |
| knowledge_file: str, | |
| phase: str, | |
| usage_type: str, | |
| relevance_score: float = 1.0, | |
| excerpt: str = "", | |
| matched_tags: list[str] | None = None, | |
| ) -> KnowledgeReference: | |
| """记录一次知识引用 | |
| Args: | |
| knowledge_file: 知识文件路径 | |
| phase: 引用阶段(research/docs/spec/frontend/backend/quality/delivery) | |
| usage_type: 使用类型(constraint/guidance/reference) | |
| relevance_score: 相关性分数 0‑1 | |
| excerpt: 引用内容摘要 | |
| matched_tags: 匹配的标签(可选,自动推断) | |
| Returns: | |
| 创建的 KnowledgeReference 实例 | |
| Raises: | |
| ValueError: 当 phase 或 usage_type 不合法时 | |
| """ | |
| if phase not in VALID_PHASES: | |
| raise ValueError(f"Invalid phase '{phase}'. Must be one of: {sorted(VALID_PHASES)}") | |
| if usage_type not in VALID_USAGE_TYPES: | |
| raise ValueError( | |
| f"Invalid usage_type '{usage_type}'. Must be one of: {sorted(VALID_USAGE_TYPES)}" | |
| ) | |
| relevance_score = max(0.0, min(1.0, relevance_score)) | |
| # 自动推断标签 | |
| if matched_tags is None: | |
| entry = self._knowledge_index.get(knowledge_file) | |
| matched_tags = list(entry.tags) if entry else [] | |
| ref = KnowledgeReference( | |
| knowledge_file=knowledge_file, | |
| phase=phase, | |
| usage_type=usage_type, | |
| matched_tags=matched_tags, | |
| relevance_score=relevance_score, | |
| excerpt=excerpt, | |
| ) | |
| self.references.append(ref) | |
| return ref | |
| # ------------------------------------------------------------------ | |
| # 知识查找 | |
| # ------------------------------------------------------------------ | |
| def find_relevant_knowledge( | |
| self, | |
| query: str, | |
| phase: str, | |
| top_k: int = 5, | |
| ) -> list[dict[str, Any]]: | |
| """根据查询和阶段查找相关知识(供 pipeline 使用) | |
| 使用简单的关键词匹配 + 领域-阶段亲和度过滤。 | |
| Args: | |
| query: 搜索查询文本 | |
| phase: 当前 pipeline 阶段 | |
| top_k: 最多返回条数 | |
| Returns: | |
| 包含 path, title, domain, score, tags 的字典列表,按 score 降序排列 | |
| """ | |
| if not self._knowledge_index: | |
| return [] | |
| query_lower = query.lower() | |
| query_tokens = set(re.split(r"\W+", query_lower)) - {"", "the", "and", "for", "with", "a"} | |
| scored: list[tuple[float, str, _KnowledgeIndexEntry]] = [] | |
| for path, entry in self._knowledge_index.items(): | |
| score = 0.0 | |
| # 1. 关键词匹配(标签 + 标题) | |
| entry_tokens = set(t.lower() for t in entry.tags) | |
| entry_tokens.update(re.split(r"\W+", entry.title.lower())) | |
| overlap = query_tokens & entry_tokens | |
| if overlap: | |
| score += len(overlap) / max(len(query_tokens), 1) * 0.6 | |
| # 2. 领域-阶段亲和度 | |
| affinity_phases = _DOMAIN_PHASE_AFFINITY.get(entry.domain, []) | |
| if phase in affinity_phases: | |
| score += 0.3 | |
| # 3. 子串匹配 bonus | |
| for token in query_tokens: | |
| if len(token) > 3 and token in entry.path.lower(): | |
| score += 0.1 | |
| break | |
| if score > 0: | |
| scored.append((score, path, entry)) | |
| scored.sort(key=lambda x: x[0], reverse=True) | |
| results: list[dict[str, Any]] = [] | |
| for score, path, entry in scored[:top_k]: | |
| results.append( | |
| { | |
| "path": path, | |
| "title": entry.title, | |
| "domain": entry.domain, | |
| "category": entry.category, | |
| "score": round(min(score, 1.0), 4), | |
| "tags": entry.tags, | |
| } | |
| ) | |
| return results | |
| # ------------------------------------------------------------------ | |
| # 报告生成 | |
| # ------------------------------------------------------------------ | |
| def generate_report( | |
| self, | |
| project_name: str, | |
| run_id: str | None = None, | |
| ) -> KnowledgeTrackingReport: | |
| """生成知识引用报告 | |
| Args: | |
| project_name: 项目名称 | |
| run_id: Pipeline 运行 ID(不提供则自动生成) | |
| Returns: | |
| KnowledgeTrackingReport 实例 | |
| """ | |
| if run_id is None: | |
| run_id = f"run-{uuid.uuid4().hex[:8]}" | |
| total_files = len(self._knowledge_index) | |
| referenced_paths = {ref.knowledge_file for ref in self.references} | |
| referenced_count = len(referenced_paths) | |
| hit_rate = referenced_count / total_files if total_files > 0 else 0.0 | |
| # 领域覆盖率 | |
| coverage = self.get_knowledge_coverage() | |
| # 未引用领域 | |
| unreferenced_domains = [ | |
| domain for domain, info in coverage.items() if info["referenced"] == 0 | |
| ] | |
| return KnowledgeTrackingReport( | |
| project_name=project_name, | |
| pipeline_run_id=run_id, | |
| timestamp=datetime.now(timezone.utc).isoformat(), | |
| total_knowledge_files=total_files, | |
| referenced_files=referenced_count, | |
| hit_rate=hit_rate, | |
| references=list(self.references), | |
| unreferenced_domains=unreferenced_domains, | |
| coverage_by_domain=coverage, | |
| ) | |
| def save_report( | |
| self, | |
| report: KnowledgeTrackingReport, | |
| output_dir: str = "output", | |
| ) -> tuple[Path, Path]: | |
| """保存报告到文件 | |
| Markdown 报告存到 output/ 根目录, | |
| JSON 存到 output/metrics-history/ 用于趋势分析。 | |
| Args: | |
| report: 报告实例 | |
| output_dir: 输出目录 | |
| Returns: | |
| (markdown_path, json_path) 两个文件路径 | |
| """ | |
| output_path = Path(output_dir) | |
| output_path.mkdir(parents=True, exist_ok=True) | |
| metrics_dir = output_path / "metrics-history" | |
| metrics_dir.mkdir(parents=True, exist_ok=True) | |
| ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") | |
| base_name = f"{report.project_name}-knowledge-tracking" | |
| # Markdown | |
| md_path = output_path / f"{base_name}.md" | |
| md_path.write_text(report.to_markdown(), encoding="utf-8") | |
| # JSON (带时间戳用于趋势分析) | |
| json_path = metrics_dir / f"{base_name}-{ts}.json" | |
| json_path.write_text( | |
| json.dumps(report.to_json(), ensure_ascii=False, indent=2), | |
| encoding="utf-8", | |
| ) | |
| return md_path, json_path | |
| # ------------------------------------------------------------------ | |
| # 覆盖率统计 | |
| # ------------------------------------------------------------------ | |
| def get_knowledge_coverage(self) -> dict[str, dict[str, Any]]: | |
| """获取知识覆盖率统计(按领域) | |
| Returns: | |
| 形如 ``{ "security": {"total": 15, "referenced": 8, "rate": 0.53} }`` 的字典 | |
| """ | |
| domain_total: dict[str, int] = {} | |
| domain_files: dict[str, set[str]] = {} | |
| for path, entry in self._knowledge_index.items(): | |
| d = entry.domain or "(root)" | |
| domain_total[d] = domain_total.get(d, 0) + 1 | |
| if d not in domain_files: | |
| domain_files[d] = set() | |
| referenced_paths = {ref.knowledge_file for ref in self.references} | |
| for path, entry in self._knowledge_index.items(): | |
| d = entry.domain or "(root)" | |
| if path in referenced_paths: | |
| domain_files[d].add(path) | |
| result: dict[str, dict[str, Any]] = {} | |
| for domain in sorted(domain_total): | |
| total = domain_total[domain] | |
| referenced = len(domain_files.get(domain, set())) | |
| result[domain] = { | |
| "total": total, | |
| "referenced": referenced, | |
| "rate": round(referenced / total, 4) if total > 0 else 0.0, | |
| } | |
| return result | |
| # ------------------------------------------------------------------ | |
| # 辅助方法 | |
| # ------------------------------------------------------------------ | |
| def get_all_domains(self) -> list[str]: | |
| """获取所有知识领域名称""" | |
| domains: set[str] = set() | |
| for entry in self._knowledge_index.values(): | |
| if entry.domain: | |
| domains.add(entry.domain) | |
| return sorted(domains) | |
| def get_reference_count(self) -> int: | |
| """获取当前引用总数""" | |
| return len(self.references) | |
| def clear(self) -> None: | |
| """清空所有引用记录(保留索引)""" | |
| self.references.clear() | |
Xet Storage Details
- Size:
- 22 kB
- Xet hash:
- 4c466b2bee941dc9ee798293dd4b287e7f45cd80404d90272d4a62829aad9471
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.