teamai-cli 0.25.0 → 0.26.0-beta.1

package/{skills/team-wiki-codebase → skill-data/wiki}/scripts/scan_repo.py

@@ -1,14 +1,14 @@
 #!/usr/bin/env python3
 """
-scan_repo.py — 代码仓库结构扫描与统计工具
+scan_repo.py: repository structure scan and statistics tool
 
-用途: Phase 0 源材料采集阶段，快速扫描目标仓库/目录，输出：
-  1. 目录结构树（2层深度）
-  2. 代码统计（语言分布、文件数、总行数）
-  3. 关键文件发现（入口文件、配置文件、Proto/IDL、错误码定义）
-  4. 代码热点（文件行数 Top 20）
+Purpose: in the Phase 0 source material collection stage, quickly scan the target repository/directory and print:
+  1. Directory tree (2 levels deep)
+  2. Code statistics (language distribution, file count, total lines)
+  3. Key file discovery (entry files, config files, Proto/IDL, error code definitions)
+  4. Code hotspots (top 20 files by line count)
 
-使用方式:
+Usage:
   python3 scan_repo.py /path/to/repo
   python3 scan_repo.py /path/to/repo --depth 3 --top 30
 """
@@ -19,38 +19,38 @@ import argparse
 from pathlib import Path
 from collections import defaultdict, Counter
 
-# 关键文件匹配模式
+# Key file match patterns
 KEY_FILE_PATTERNS = {
-    "入口文件": [
+    "Entry files": [
         "main.py", "main.go", "app.py", "app.ts", "app.js",
         "server.py", "server.go", "wsgi.py", "manage.py",
         "cmd/*/main.go", "index.ts", "index.js",
     ],
-    "路由/Handler": [
+    "Routes/Handlers": [
         "*handler*", "*router*", "*controller*", "*dispatch*",
         "*route*", "*api.*", "*endpoint*",
     ],
-    "配置文件": [
+    "Config files": [
         "*.yaml", "*.yml", "*.toml", "*.ini", "*.conf",
         "*config*", "*.env", "*.env.*",
     ],
     "Proto/IDL": [
         "*.proto", "*.thrift", "*.graphql", "*schema*",
     ],
-    "数据库/模型": [
+    "Database/Models": [
         "*model*", "*dao*", "*repository*", "*migration*",
         "*schema*", "*.sql", "*db*",
     ],
-    "常量/错误码": [
+    "Constants/Error codes": [
         "*const*", "*constant*", "*error*", "*code*",
         "*enum*", "*define*", "*exception*",
     ],
-    "测试文件": [
+    "Test files": [
         "*_test.*", "test_*", "*.spec.*", "*_spec.*",
     ],
 }
 
-# 语言扩展名映射
+# Language extension map
 LANG_MAP = {
     ".py": "Python", ".go": "Go", ".js": "JavaScript", ".ts": "TypeScript",
     ".java": "Java", ".rs": "Rust", ".rb": "Ruby", ".php": "PHP",
@@ -61,7 +61,7 @@ LANG_MAP = {
     ".json": "JSON", ".xml": "XML", ".md": "Markdown",
 }
 
-# 忽略目录
+# Ignored directories
 IGNORE_DIRS = {
     ".git", ".svn", "node_modules", "__pycache__", ".tox", ".mypy_cache",
     "venv", ".venv", "env", ".env", "vendor", "dist", "build",
@@ -85,28 +85,28 @@ def count_lines(filepath: Path) -> int:
 
 
 def match_pattern(filename: str, pattern: str) -> bool:
-    """简单的通配符匹配"""
+    """Simple wildcard match"""
     import fnmatch
     return fnmatch.fnmatch(filename.lower(), pattern.lower())
 
 
 def scan_repository(repo_path: Path, depth: int = 2, top_n: int = 20):
-    """扫描仓库，返回统计结果"""
+    """Scan the repository and return the statistics"""
 
     all_files = []
-    lang_stats = Counter()       # 语言 -> (文件数, 行数)
+    lang_stats = Counter()       # language -> (file count, line count)
     lang_lines = Counter()
     key_files = defaultdict(list)
     dir_tree = []
 
-    # 遍历文件
+    # Walk the files
     for root, dirs, files in os.walk(repo_path):
         rel_root = Path(root).relative_to(repo_path)
 
-        # 忽略目录
+        # Skip ignored directories
         dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.endswith(".egg-info")]
 
-        # 目录树（限制深度）
+        # Directory tree (depth-limited)
         level = len(rel_root.parts)
         if level <= depth:
             indent = "  " * level
@@ -124,13 +124,13 @@ def scan_repository(repo_path: Path, depth: int = 2, top_n: int = 20):
 
             all_files.append((rel_path, ext, lines))
 
-            # 语言统计
+            # Language statistics
             lang = LANG_MAP.get(ext)
             if lang:
                 lang_stats[lang] += 1
                 lang_lines[lang] += lines
 
-            # 关键文件匹配
+            # Key file matching
             for category, patterns in KEY_FILE_PATTERNS.items():
                 for pattern in patterns:
                     if match_pattern(fname, pattern):
@@ -141,35 +141,35 @@ def scan_repository(repo_path: Path, depth: int = 2, top_n: int = 20):
 
 
 def print_report(repo_path: Path, all_files, lang_stats, lang_lines, key_files, dir_tree, top_n: int):
-    """输出扫描报告"""
+    """Print the scan report"""
 
     total_files = len(all_files)
     total_lines = sum(f[2] for f in all_files)
 
     print("=" * 70)
-    print(f"  代码仓库扫描报告: {repo_path.name}")
-    print(f"  路径: {repo_path}")
+    print(f"  Repository scan report: {repo_path.name}")
+    print(f"  Path: {repo_path}")
     print("=" * 70)
 
-    # 1. 基本统计
-    print(f"\n## 1. 基本统计\n")
-    print(f"| 指标 | 数值 |")
+    # 1. Basic statistics
+    print(f"\n## 1. Basic statistics\n")
+    print(f"| Metric | Value |")
     print(f"|------|------|")
-    print(f"| 总文件数 | {total_files} |")
-    print(f"| 总代码行数 | {total_lines:,} |")
-    print(f"| 语言种类 | {len(lang_stats)} |")
+    print(f"| Total files | {total_files} |")
+    print(f"| Total lines of code | {total_lines:,} |")
+    print(f"| Languages | {len(lang_stats)} |")
 
-    # 2. 语言分布
-    print(f"\n## 2. 语言分布\n")
-    print(f"| 语言 | 文件数 | 代码行数 | 占比 |")
+    # 2. Language distribution
+    print(f"\n## 2. Language distribution\n")
+    print(f"| Language | Files | Lines | Share |")
     print(f"|------|--------|---------|------|")
     for lang, count in lang_stats.most_common(15):
         lines = lang_lines[lang]
         pct = f"{lines / total_lines * 100:.1f}%" if total_lines > 0 else "0%"
         print(f"| {lang} | {count} | {lines:,} | {pct} |")
 
-    # 3. 目录结构
-    print(f"\n## 3. 目录结构（前 30 行）\n")
+    # 3. Directory structure
+    print(f"\n## 3. Directory structure (first 30 lines)\n")
     print("```")
     for line in dir_tree[:30]:
         print(line)
@@ -177,41 +177,41 @@ def print_report(repo_path: Path, all_files, lang_stats, lang_lines, key_files,
         print(f"  ... ({len(dir_tree) - 30} more directories)")
     print("```")
 
-    # 4. 关键文件发现
-    print(f"\n## 4. 关键文件发现\n")
+    # 4. Key file discovery
+    print(f"\n## 4. Key file discovery\n")
     for category, files in key_files.items():
         if files:
-            print(f"\n### {category} ({len(files)} 个)\n")
-            # 去重并排序
+            print(f"\n### {category} ({len(files)} files)\n")
+            # Deduplicate and sort
             seen = set()
             for fpath, lines in sorted(files, key=lambda x: -x[1])[:10]:
                 if fpath not in seen:
                     seen.add(fpath)
-                    print(f"- `{fpath}` ({lines:,} 行)")
+                    print(f"- `{fpath}` ({lines:,} lines)")
 
-    # 5. 代码热点
-    print(f"\n## 5. 代码热点 (Top {top_n})\n")
-    print(f"| 排名 | 文件 | 行数 |")
+    # 5. Code hotspots
+    print(f"\n## 5. Code hotspots (Top {top_n})\n")
+    print(f"| Rank | File | Lines |")
     print(f"|------|------|------|")
     sorted_files = sorted(all_files, key=lambda x: -x[2])
     for i, (fpath, ext, lines) in enumerate(sorted_files[:top_n], 1):
         print(f"| {i} | `{fpath}` | {lines:,} |")
 
     print(f"\n{'=' * 70}")
-    print(f"  扫描完成。共 {total_files} 个文件，{total_lines:,} 行代码。")
+    print(f"  Scan complete. {total_files} files, {total_lines:,} lines of code.")
     print(f"{'=' * 70}")
 
 
 def main():
-    parser = argparse.ArgumentParser(description="代码仓库结构扫描与统计工具")
-    parser.add_argument("repo_path", help="要扫描的仓库/目录路径")
-    parser.add_argument("--depth", type=int, default=2, help="目录树深度 (默认 2)")
-    parser.add_argument("--top", type=int, default=20, help="代码热点 Top N (默认 20)")
+    parser = argparse.ArgumentParser(description="Repository structure scan and statistics tool")
+    parser.add_argument("repo_path", help="Path of the repository/directory to scan")
+    parser.add_argument("--depth", type=int, default=2, help="Directory tree depth (default 2)")
+    parser.add_argument("--top", type=int, default=20, help="Code hotspots top N (default 20)")
     args = parser.parse_args()
 
     repo_path = Path(args.repo_path).resolve()
     if not repo_path.is_dir():
-        print(f"错误: {repo_path} 不是有效目录", file=sys.stderr)
+        print(f"Error: {repo_path} is not a valid directory", file=sys.stderr)
         sys.exit(1)
 
     all_files, lang_stats, lang_lines, key_files, dir_tree = scan_repository(

package/{skills/team-wiki-codebase → skill-data/wiki}/scripts/validate_kb.py

@@ -1,15 +1,15 @@
 #!/usr/bin/env python3
 """
-validate_kb.py — 知识库质量校验工具
+validate_kb.py: knowledge base quality validation tool
 
-用途: Phase 4 质量评估阶段，自动校验已生成知识库的：
-  1. 链接完整性（检测死链接）
-  2. search-anchor 覆盖率
-  3. AI 快速理解表覆盖率
-  4. 双向链接完整性
-  5. README 索引收录率
+Purpose: in the Phase 4 quality assessment stage, automatically check the generated knowledge base for:
+  1. Link integrity (dead link detection)
+  2. search-anchor coverage
+  3. AI Quick Reference table coverage
+  4. Bidirectional link integrity
+  5. README index coverage
 
-使用方式:
+Usage:
   python3 validate_kb.py /path/to/knowledge-base-dir
   python3 validate_kb.py /path/to/knowledge-base-dir --verbose
 """
@@ -21,18 +21,24 @@ import argparse
 from pathlib import Path
 from collections import defaultdict
 
-# Markdown 链接正则: [text](path) 或 [text](path#anchor)
+# Markdown link regex: [text](path) or [text](path#anchor)
 LINK_PATTERN = re.compile(r'\[([^\]]*)\]\(([^)]+)\)')
-# search-anchor 正则
+# search-anchor regex
 ANCHOR_PATTERN = re.compile(r'<!--\s*search-anchor\s*:(.*?)-->', re.DOTALL)
-# AI 快速理解表正则
-AI_TABLE_PATTERN = re.compile(r'##\s*🤖\s*AI\s*快速理解', re.IGNORECASE)
-# 双向链接: 链接回主架构/技术架构文档
-BACK_LINK_PATTERN = re.compile(r'\[📘.*(?:主架构|技术架构)|在整体架构中的位置', re.IGNORECASE)
+# AI Quick Reference table regex. Matches both the current English heading and the
+# legacy Chinese heading so knowledge bases built with earlier releases still validate.
+# Legacy knowledge bases carry the Chinese heading; matched by code point so the source stays ASCII-only.
+AI_TABLE_PATTERN = re.compile(r'##\s*🤖\s*AI\s*(?:Quick\s*Reference|\u5feb\u901f\u7406\u89e3)', re.IGNORECASE)
+# Bidirectional link: a link back to the main / technical architecture document.
+# Bilingual for the same reason as AI_TABLE_PATTERN.
+BACK_LINK_PATTERN = re.compile(
+    r'\[📘.*(?:Technical\s*Architecture|\u4e3b\u67b6\u6784|\u6280\u672f\u67b6\u6784)|Position in the overall architecture|\u5728\u6574\u4f53\u67b6\u6784\u4e2d\u7684\u4f4d\u7f6e',
+    re.IGNORECASE,
+)
 
 
 def find_md_files(kb_dir: Path) -> list:
-    """查找所有 .md 文件"""
+    """Find all .md files"""
     md_files = []
     for root, dirs, files in os.walk(kb_dir):
         dirs[:] = [d for d in dirs if not d.startswith('.')]
@@ -43,27 +49,27 @@ def find_md_files(kb_dir: Path) -> list:
 
 
 def check_links(md_file: Path, kb_dir: Path) -> list:
-    """检查文件中的链接是否有效"""
+    """Check that the links in the file resolve"""
     broken = []
     try:
         content = md_file.read_text(encoding='utf-8', errors='ignore')
     except OSError:
-        return [("READ_ERROR", str(md_file), "无法读取文件")]
+        return [("READ_ERROR", str(md_file), "cannot read file")]
 
     for match in LINK_PATTERN.finditer(content):
         link_text = match.group(1)
         link_target = match.group(2)
 
-        # 跳过外部链接和锚点链接
+        # Skip external links and anchor-only links
         if link_target.startswith(('http://', 'https://', 'mailto:', '#')):
             continue
 
-        # 分离路径和锚点
+        # Split path and anchor
         path_part = link_target.split('#')[0]
         if not path_part:
             continue
 
-        # 解析相对路径
+        # Resolve the relative path
         target_path = (md_file.parent / path_part).resolve()
         if not target_path.exists():
             rel = str(md_file.relative_to(kb_dir))
@@ -73,7 +79,7 @@ def check_links(md_file: Path, kb_dir: Path) -> list:
 
 
 def check_anchor(md_file: Path) -> bool:
-    """检查文件是否包含 search-anchor"""
+    """Check whether the file contains a search-anchor"""
     try:
         content = md_file.read_text(encoding='utf-8', errors='ignore')
         return bool(ANCHOR_PATTERN.search(content))
@@ -82,7 +88,7 @@ def check_anchor(md_file: Path) -> bool:
 
 
 def check_ai_table(md_file: Path) -> bool:
-    """检查文件是否包含 AI 快速理解表"""
+    """Check whether the file contains the AI Quick Reference table"""
     try:
         content = md_file.read_text(encoding='utf-8', errors='ignore')
         return bool(AI_TABLE_PATTERN.search(content))
@@ -91,7 +97,7 @@ def check_ai_table(md_file: Path) -> bool:
 
 
 def check_back_link(md_file: Path) -> bool:
-    """检查组件文档是否有链接回主架构文档"""
+    """Check whether the component document links back to the main architecture document"""
     try:
         content = md_file.read_text(encoding='utf-8', errors='ignore')
         return bool(BACK_LINK_PATTERN.search(content))
@@ -100,7 +106,7 @@ def check_back_link(md_file: Path) -> bool:
 
 
 def check_readme_coverage(kb_dir: Path, md_files: list) -> tuple:
-    """检查 README 是否收录了所有 .md 文件"""
+    """Check whether the README indexes every .md file"""
     readme_path = kb_dir / "README.md"
     if not readme_path.exists():
         return [], md_files
@@ -112,7 +118,7 @@ def check_readme_coverage(kb_dir: Path, md_files: list) -> tuple:
     for f in md_files:
         if f.name == "README.md":
             continue
-        # 检查 README 中是否提到了这个文件
+        # Check whether the README mentions this file
         fname_no_ext = f.stem
         if fname_no_ext in readme_content or f.name in readme_content:
             covered.append(f)
@@ -123,106 +129,106 @@ def check_readme_coverage(kb_dir: Path, md_files: list) -> tuple:
 
 
 def main():
-    parser = argparse.ArgumentParser(description="知识库质量校验工具")
-    parser.add_argument("kb_dir", help="知识库目录路径")
-    parser.add_argument("--verbose", "-v", action="store_true", help="输出详细信息")
+    parser = argparse.ArgumentParser(description="Knowledge base quality validation tool")
+    parser.add_argument("kb_dir", help="Path of the knowledge base directory")
+    parser.add_argument("--verbose", "-v", action="store_true", help="Print details")
     args = parser.parse_args()
 
     kb_dir = Path(args.kb_dir).resolve()
     if not kb_dir.is_dir():
-        print(f"错误: {kb_dir} 不是有效目录", file=sys.stderr)
+        print(f"Error: {kb_dir} is not a valid directory", file=sys.stderr)
         sys.exit(1)
 
     md_files = find_md_files(kb_dir)
     if not md_files:
-        print(f"警告: {kb_dir} 中未找到任何 .md 文件")
+        print(f"Warning: no .md files found in {kb_dir}")
         sys.exit(0)
 
-    # 过滤出组件设计文档（以数字编号开头的文件）
+    # Filter the component design documents (files starting with a number)
     component_docs = [f for f in md_files if re.match(r'^\d+_', f.name)]
 
     print("=" * 70)
-    print(f"  知识库质量校验报告")
-    print(f"  目录: {kb_dir}")
-    print(f"  文件数: {len(md_files)} 个 .md 文件 (其中 {len(component_docs)} 个组件文档)")
+    print(f"  Knowledge base quality validation report")
+    print(f"  Directory: {kb_dir}")
+    print(f"  Files: {len(md_files)} .md files ({len(component_docs)} component documents)")
     print("=" * 70)
 
     total_score = 0
     max_score = 0
 
-    # 1. 链接完整性
-    print(f"\n## 1. 链接完整性检查\n")
+    # 1. Link integrity
+    print(f"\n## 1. Link integrity check\n")
     all_broken = []
     for f in md_files:
         broken = check_links(f, kb_dir)
         all_broken.extend(broken)
 
     if all_broken:
-        print(f"❌ 发现 {len(all_broken)} 个死链接:")
+        print(f"❌ Found {len(all_broken)} dead links:")
         for src, target, text in all_broken[:20]:
             print(f"   {src} → [{text}]({target})")
         if len(all_broken) > 20:
-            print(f"   ... 还有 {len(all_broken) - 20} 个")
+            print(f"   ... and {len(all_broken) - 20} more")
     else:
-        print(f"✅ 所有链接有效 (检查了 {len(md_files)} 个文件)")
+        print(f"✅ All links valid ({len(md_files)} files checked)")
         total_score += 20
     max_score += 20
 
-    # 2. search-anchor 覆盖率
-    print(f"\n## 2. Search-Anchor 覆盖率\n")
+    # 2. search-anchor coverage
+    print(f"\n## 2. Search-Anchor coverage\n")
     has_anchor = sum(1 for f in md_files if check_anchor(f))
     anchor_pct = has_anchor / len(md_files) * 100 if md_files else 0
-    print(f"{'✅' if anchor_pct >= 80 else '⚠️'} {has_anchor}/{len(md_files)} 个文件有 search-anchor ({anchor_pct:.0f}%)")
+    print(f"{'✅' if anchor_pct >= 80 else '⚠️'} {has_anchor}/{len(md_files)} files have a search-anchor ({anchor_pct:.0f}%)")
     if args.verbose:
         for f in md_files:
             if not check_anchor(f):
-                print(f"   缺失: {f.relative_to(kb_dir)}")
+                print(f"   Missing: {f.relative_to(kb_dir)}")
     if anchor_pct >= 80:
         total_score += 20
     elif anchor_pct >= 50:
         total_score += 10
     max_score += 20
 
-    # 3. AI 快速理解表覆盖率（仅检查组件文档）
-    print(f"\n## 3. AI 快速理解表覆盖率 (组件文档)\n")
+    # 3. AI Quick Reference table coverage (component documents only)
+    print(f"\n## 3. AI Quick Reference table coverage (component documents)\n")
     if component_docs:
         has_ai_table = sum(1 for f in component_docs if check_ai_table(f))
         ai_pct = has_ai_table / len(component_docs) * 100
-        print(f"{'✅' if ai_pct >= 90 else '⚠️'} {has_ai_table}/{len(component_docs)} 个组件文档有 AI 快速理解表 ({ai_pct:.0f}%)")
+        print(f"{'✅' if ai_pct >= 90 else '⚠️'} {has_ai_table}/{len(component_docs)} component documents have an AI Quick Reference table ({ai_pct:.0f}%)")
         if args.verbose:
             for f in component_docs:
                 if not check_ai_table(f):
-                    print(f"   缺失: {f.relative_to(kb_dir)}")
+                    print(f"   Missing: {f.relative_to(kb_dir)}")
         if ai_pct >= 90:
             total_score += 20
         elif ai_pct >= 60:
             total_score += 10
     else:
-        print("⚠️ 未发现编号开头的组件文档")
+        print("⚠️ No numbered component documents found")
     max_score += 20
 
-    # 4. 双向链接检查（组件文档是否链接回主架构）
-    print(f"\n## 4. 双向链接检查 (组件→主架构)\n")
+    # 4. Bidirectional link check (component documents link back to the main architecture)
+    print(f"\n## 4. Bidirectional link check (component → main architecture)\n")
     if component_docs:
         has_back = sum(1 for f in component_docs if check_back_link(f))
         back_pct = has_back / len(component_docs) * 100
-        print(f"{'✅' if back_pct >= 90 else '⚠️'} {has_back}/{len(component_docs)} 个组件文档有回链到主架构 ({back_pct:.0f}%)")
+        print(f"{'✅' if back_pct >= 90 else '⚠️'} {has_back}/{len(component_docs)} component documents link back to the main architecture ({back_pct:.0f}%)")
         if back_pct >= 90:
             total_score += 20
         elif back_pct >= 60:
             total_score += 10
     else:
-        print("⚠️ 未发现编号开头的组件文档")
+        print("⚠️ No numbered component documents found")
     max_score += 20
 
-    # 5. README 索引覆盖率
-    print(f"\n## 5. README 索引覆盖率\n")
+    # 5. README index coverage
+    print(f"\n## 5. README index coverage\n")
     covered, uncovered = check_readme_coverage(kb_dir, md_files)
     if (kb_dir / "README.md").exists():
         cover_pct = len(covered) / (len(covered) + len(uncovered)) * 100 if (covered or uncovered) else 100
-        print(f"{'✅' if cover_pct >= 90 else '⚠️'} README 收录了 {len(covered)}/{len(covered)+len(uncovered)} 个文档 ({cover_pct:.0f}%)")
+        print(f"{'✅' if cover_pct >= 90 else '⚠️'} README indexes {len(covered)}/{len(covered)+len(uncovered)} documents ({cover_pct:.0f}%)")
         if uncovered and args.verbose:
-            print("   未收录:")
+            print("   Not indexed:")
             for f in uncovered[:10]:
                 print(f"     {f.relative_to(kb_dir)}")
         if cover_pct >= 90:
@@ -230,19 +236,19 @@ def main():
         elif cover_pct >= 60:
             total_score += 10
     else:
-        print("❌ 未找到 README.md")
+        print("❌ README.md not found")
     max_score += 20
 
-    # 总结
+    # Summary
     final_pct = total_score / max_score * 100 if max_score else 0
     print(f"\n{'=' * 70}")
-    print(f"  综合评分: {total_score}/{max_score} ({final_pct:.0f}%)")
+    print(f"  Overall score: {total_score}/{max_score} ({final_pct:.0f}%)")
     if final_pct >= 90:
-        print(f"  评级: ✅ 优秀 — 知识库质量达标")
+        print(f"  Rating: ✅ Excellent. The knowledge base meets the quality bar")
     elif final_pct >= 70:
-        print(f"  评级: ⚠️ 良好 — 建议修复上述问题")
+        print(f"  Rating: ⚠️ Good. Fixing the issues above is recommended")
     else:
-        print(f"  评级: ❌ 需改进 — 存在较多质量问题")
+        print(f"  Rating: ❌ Needs improvement. There are many quality issues")
     print(f"{'=' * 70}")