@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/report-craft/scripts/project_facts.py

@@ -0,0 +1,580 @@
+#!/usr/bin/env python3
+# 项目事实清单：扫一遍代码库，给「可研 / 概要设计 / 项目总结 / 结题报告」这类文档取证。只用标准库。
+#
+# 为什么要有它：写项目自己的报告时，模型最容易做的是凭印象报数——「微服务若干个」「代码约十万行」
+# 「支持数十种模型」。评审一问来源就露馅，前后章节报的数还对不上。这里把能从代码里数出来的事实一次数清，
+# 每条都带来源路径，正文引用时写得出「据 huicai-backend/pom.xml」。
+#
+# 纪律：
+#   · 只出计数、名称、版本、端口和来源路径；**配置值一律不读出**（application.yml 里常有默认口令、密钥），
+#     端口与服务名走白名单键；compose 只取服务名、镜像、端口映射，环境变量一个字都不出；
+#   · 同步副本只算一次：多端工程常把同一份核心代码拷到几个子工程里，按内容哈希去重，
+#     否则代码行数会被重复计入好几倍；
+#   · 人名不出：git 只报提交数、起止日期与贡献者**人数**。
+#
+# 用法：python project_facts.py <根目录>          最后一行输出 JSON（含 markdown 事实表与模块树 spec）。
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+
+SKIP_DIRS = {
+    '.git', '.svn', '.hg', 'node_modules', 'target', 'dist', 'build', 'out', '.next', '.nuxt', 'coverage',
+    '.venv', 'venv', 'env', '__pycache__', '.idea', '.vscode', '.gradle', 'vendor', '.cache', '.turbo',
+    '.parcel-cache', '.huicai', '.pytest_cache', '.mypy_cache', 'bower_components', '.terraform', 'Pods',
+    'release', 'releases', '.output', 'tmp', '.tmp', 'logs',
+}
+LANGS = {
+    '.java': 'Java', '.kt': 'Kotlin', '.kts': 'Kotlin', '.scala': 'Scala', '.groovy': 'Groovy',
+    '.js': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript', '.jsx': 'JavaScript',
+    '.ts': 'TypeScript', '.tsx': 'TypeScript', '.mts': 'TypeScript', '.vue': 'Vue', '.svelte': 'Svelte',
+    '.py': 'Python', '.go': 'Go', '.rs': 'Rust', '.cs': 'C#', '.c': 'C/C++', '.cc': 'C/C++', '.cpp': 'C/C++',
+    '.h': 'C/C++', '.hpp': 'C/C++', '.swift': 'Swift', '.m': 'Objective-C', '.php': 'PHP', '.rb': 'Ruby',
+    '.dart': 'Dart', '.lua': 'Lua', '.sql': 'SQL', '.sh': 'Shell', '.bash': 'Shell', '.ps1': 'PowerShell',
+    '.css': 'CSS/样式', '.scss': 'CSS/样式', '.less': 'CSS/样式', '.html': 'HTML',
+}
+MAX_FILE = 2 * 1024 * 1024
+MAX_FILES = 120000
+
+TEST_PATH = re.compile(r'(^|/)(test|tests|__tests__|spec|e2e)(/|$)', re.I)
+TEST_NAME = re.compile(r'(Tests?\.(java|kt|cs)$|\.(test|spec)\.[cm]?[jt]sx?$|^test_.*\.py$|_test\.(py|go)$)')
+CASE_PAT = {
+    'Java': re.compile(r'@(Test|ParameterizedTest)\b'), 'Kotlin': re.compile(r'@Test\b'),
+    'JavaScript': re.compile(r'^\s*(?:it|test)(?:\.each\([^)]*\))?\s*\(', re.M),
+    'TypeScript': re.compile(r'^\s*(?:it|test)(?:\.each\([^)]*\))?\s*\(', re.M),
+    'Python': re.compile(r'^\s*(?:async\s+)?def\s+test_\w*\s*\(', re.M), 'Go': re.compile(r'^func\s+Test\w*\(', re.M),
+    'C#': re.compile(r'\[(Fact|Theory|Test|TestMethod)\b'),
+}
+JAVA_MAP = re.compile(r'@(Get|Post|Put|Delete|Patch)Mapping\b|@RequestMapping\s*\([^)]*method\s*=')
+JS_ROUTE = re.compile(r'\b(?:app|router|server|fastify)\.(?:get|post|put|delete|patch)\s*\(\s*[\'"`]/')
+PY_ROUTE = re.compile(r'@\w+\.(?:get|post|put|delete|patch|route)\s*\(\s*[\'"]/')
+CREATE_TABLE = re.compile(r'\bcreate\s+(?:unlogged\s+|temporary\s+|temp\s+)?table\s+(?:if\s+not\s+exists\s+)?'
+                          r'((?:[`"\[]?\w+[`"\]]?\.)?[`"\[]?\w+[`"\]]?)', re.I)
+ROUTE_PATH = re.compile(r'\bpath\s*:\s*[\'"`]')
+
+FRAMEWORKS_JS = {
+    'vue': 'Vue', 'react': 'React', 'electron': 'Electron', 'vite': 'Vite', 'element-plus': 'Element Plus',
+    'ant-design-vue': 'Ant Design Vue', 'antd': 'Ant Design', 'express': 'Express', 'koa': 'Koa',
+    'fastify': 'Fastify', 'typescript': 'TypeScript', 'pinia': 'Pinia', 'vuex': 'Vuex', 'vue-router': 'Vue Router',
+    'echarts': 'ECharts', 'three': 'three.js', 'axios': 'Axios', 'webpack': 'webpack', 'next': 'Next.js',
+    'nuxt': 'Nuxt', '@nestjs/core': 'NestJS', 'playwright': 'Playwright', 'jest': 'Jest', 'vitest': 'Vitest',
+    'tailwindcss': 'Tailwind CSS', 'monaco-editor': 'Monaco Editor', 'xterm': 'xterm.js', '@xterm/xterm': 'xterm.js',
+    'node-pty': 'node-pty', 'electron-builder': 'electron-builder', 'socket.io': 'Socket.IO', 'openai': 'OpenAI SDK',
+    '@modelcontextprotocol/sdk': 'MCP SDK', 'better-sqlite3': 'SQLite', 'markdown-it': 'markdown-it',
+    'ink': 'Ink（终端界面）', 'commander': 'commander', 'yargs': 'yargs',
+}
+FRAMEWORKS_JAVA = {
+    'spring-cloud-starter-gateway': 'Spring Cloud Gateway', 'spring-cloud-starter-openfeign': 'OpenFeign',
+    'spring-cloud-starter-alibaba-nacos-discovery': 'Nacos 注册中心', 'spring-cloud-starter-alibaba-nacos-config': 'Nacos 配置中心',
+    'spring-cloud-starter-alibaba-sentinel': 'Sentinel', 'mybatis-plus-spring-boot3-starter': 'MyBatis-Plus',
+    'mybatis-plus-boot-starter': 'MyBatis-Plus', 'spring-boot-starter-data-redis': 'Redis',
+    'postgresql': 'PostgreSQL', 'mysql-connector-j': 'MySQL', 'mysql-connector-java': 'MySQL',
+    'shardingsphere-jdbc-core': 'ShardingSphere', 'shardingsphere-jdbc': 'ShardingSphere',
+    'spring-kafka': 'Kafka', 'rocketmq-spring-boot-starter': 'RocketMQ', 'spring-boot-starter-amqp': 'RabbitMQ',
+    'elasticsearch-java': 'Elasticsearch', 'minio': 'MinIO', 'seata-spring-boot-starter': 'Seata',
+    'knife4j-openapi3-jakarta-spring-boot-starter': 'Knife4j', 'springdoc-openapi-starter-webmvc-ui': 'springdoc',
+    'spring-boot-starter-security': 'Spring Security', 'jjwt-api': 'JWT', 'spring-boot-starter-webflux': 'WebFlux',
+    'spring-ai-core': 'Spring AI', 'langchain4j': 'LangChain4j', 'pgvector': 'pgvector',
+    'spring-boot-starter-actuator': 'Actuator', 'micrometer-registry-prometheus': 'Prometheus',
+    'caffeine': 'Caffeine', 'redisson-spring-boot-starter': 'Redisson', 'xxl-job-core': 'XXL-JOB',
+}
+
+
+def rel(root, p):
+    return os.path.relpath(p, root).replace(os.sep, '/')
+
+
+def read_text(p, limit=MAX_FILE):
+    try:
+        if os.path.getsize(p) > limit:
+            return None
+        with open(p, 'rb') as f:
+            raw = f.read()
+        if b'\0' in raw[:4096]:
+            return None
+        return raw.decode('utf-8', errors='replace')
+    except OSError:
+        return None
+
+
+def walk(root):
+    n = 0
+    for d, dirs, files in os.walk(root):
+        dirs[:] = sorted(x for x in dirs if x not in SKIP_DIRS and not x.startswith('.')
+                         and not (x == 'node' and d.replace(os.sep, '/').endswith('/resources')))
+        for f in sorted(files):
+            n += 1
+            if n > MAX_FILES:
+                return
+            yield os.path.join(d, f)
+
+
+# ── 小型 YAML 读取：只取白名单键，绝不整体解析输出 ────────────────────────────
+def yaml_scalars(text, wanted):
+    out, stack = {}, []
+    for raw in text.splitlines():
+        s = raw.strip()
+        if s == '---':
+            stack = []
+            continue
+        if not s or s.startswith('#') or s.startswith('- '):
+            continue
+        line = re.sub(r'\s+#.*$', '', raw.rstrip())
+        m = re.match(r'^(\s*)([\w.\-]+)\s*:\s*(.*)$', line)
+        if not m:
+            continue
+        indent, key, val = len(m.group(1)), m.group(2), m.group(3).strip()
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+        path = '.'.join([k for _, k in stack] + [key])
+        if val in ('', '|', '>', '|-', '>-'):
+            stack.append((indent, key))
+        elif path in wanted and path not in out:
+            out[path] = val.strip('\'"')
+    return out
+
+
+def placeholder_default(v):
+    """${SERVER_PORT:37005} → 37005（环境变量占位取默认值）；没有默认值返回原样。"""
+    m = re.fullmatch(r'\$\{[^:}]+:([^}]*)\}', v or '')
+    return m.group(1) if m else v
+
+
+def compose_services(text):
+    """docker-compose：只取服务名、镜像、端口映射。环境变量、卷、命令一律不读。"""
+    out, in_services, svc_indent, cur, in_ports = [], False, None, None, False
+    for raw in text.splitlines():
+        if not raw.strip() or raw.strip().startswith('#'):
+            continue
+        indent = len(raw) - len(raw.lstrip(' '))
+        s = raw.strip()
+        if indent == 0:
+            in_services = s.startswith('services:')
+            cur, in_ports = None, False
+            continue
+        if not in_services:
+            continue
+        if svc_indent is None:
+            svc_indent = indent
+        if indent == svc_indent and re.match(r'^[\w.\-]+\s*:\s*$', s):
+            cur = {'name': s.rstrip(':').strip(), 'image': '', 'ports': []}
+            out.append(cur)
+            in_ports = False
+            continue
+        if cur is None:
+            continue
+        if indent > svc_indent:
+            m = re.match(r'^image\s*:\s*(.+)$', s)
+            if m:
+                cur['image'] = m.group(1).strip().strip('\'"')
+                in_ports = False
+                continue
+            if re.match(r'^ports\s*:\s*$', s):
+                in_ports = True
+                continue
+            if in_ports and s.startswith('- '):
+                cur['ports'].append(s[2:].strip().strip('\'"'))
+                continue
+            if re.match(r'^[\w.\-]+\s*:', s):
+                in_ports = False
+    return out
+
+
+def pom_info(p, root):
+    text = read_text(p)
+    if text is None:
+        return None
+    try:
+        t = ET.fromstring(text)
+    except ET.ParseError:
+        return None
+    ns = ''
+    m = re.match(r'\{(.*)\}', t.tag)
+    if m:
+        ns = '{' + m.group(1) + '}'
+
+    def g(el, path):
+        x = el.find('/'.join(ns + seg for seg in path.split('/')))
+        return x.text.strip() if x is not None and x.text else ''
+    info = {
+        'path': rel(root, os.path.dirname(p)) or '.', 'kind': 'maven', 'source': rel(root, p),
+        'artifactId': g(t, 'artifactId'), 'name': g(t, 'name'), 'description': g(t, 'description'),
+        'version': g(t, 'version') or g(t, 'parent/version'),
+        'parent': g(t, 'parent/artifactId'), 'parent_version': g(t, 'parent/version'),
+    }
+    props = t.find(ns + 'properties')
+    pv = {}
+    if props is not None:
+        for c in props:
+            k = c.tag.replace(ns, '')
+            if k in ('java.version', 'maven.compiler.source', 'spring-cloud.version', 'spring-cloud-alibaba.version',
+                     'spring-boot.version', 'mybatis-plus.version', 'kotlin.version'):
+                pv[k] = (c.text or '').strip()
+    info['properties'] = pv
+    mods = []
+    for mm in re.finditer(r'<module>\s*([^<\s]+)\s*</module>[ \t]*(?:<!--\s*(.*?)\s*-->)?', text):
+        mods.append({'module': mm.group(1), 'comment': (mm.group(2) or '').strip()})
+    info['modules'] = mods
+    deps = set()
+    for dep in t.iter(ns + 'dependency'):
+        a = dep.find(ns + 'artifactId')
+        if a is not None and a.text:
+            deps.add(a.text.strip())
+    info['frameworks'] = sorted({FRAMEWORKS_JAVA[d] for d in deps if d in FRAMEWORKS_JAVA})
+    return info
+
+
+def pkg_info(p, root):
+    text = read_text(p)
+    try:
+        j = json.loads(text or '')
+    except ValueError:
+        return None
+    deps = {}
+    for k in ('dependencies', 'devDependencies', 'peerDependencies'):
+        deps.update(j.get(k) or {})
+    fw = {}
+    for name, label in FRAMEWORKS_JS.items():
+        if name in deps:
+            fw[label] = re.sub(r'^[\^~>=<\s]+', '', str(deps[name]))
+    eng = (j.get('engines') or {}).get('node')
+    return {'path': rel(root, os.path.dirname(p)) or '.', 'kind': 'npm', 'source': rel(root, p),
+            'name': j.get('name', ''), 'version': j.get('version', ''), 'description': j.get('description', ''),
+            'frameworks': fw, 'node': eng or '', 'bin': sorted((j.get('bin') or {}).keys()) if isinstance(j.get('bin'), dict) else []}
+
+
+def gradle_info(p, root):
+    text = read_text(p) or ''
+    plugins = sorted(set(re.findall(r'id\s*\(?\s*["\']([\w.\-]+)["\']\s*\)?(?:\s*version\s*["\']([\w.\-]+)["\'])?', text)))
+    kv = re.search(r'kotlin\s*\(\s*["\']jvm["\']\s*\)\s*version\s*["\']([\w.\-]+)', text)
+    ver = re.search(r'^\s*version\s*=\s*["\']([^"\']+)', text, re.M)
+    grp = re.search(r'^\s*group\s*=\s*["\']([^"\']+)', text, re.M)
+    return {'path': rel(root, os.path.dirname(p)) or '.', 'kind': 'gradle', 'source': rel(root, p),
+            'name': os.path.basename(os.path.dirname(p)), 'version': ver.group(1) if ver else '',
+            'group': grp.group(1) if grp else '', 'description': '',
+            'frameworks': {pid: v for pid, v in plugins}, 'kotlin': kv.group(1) if kv else ''}
+
+
+def git_stats(repo):
+    def run(*args):
+        try:
+            r = subprocess.run(['git', '-C', repo] + list(args), capture_output=True, text=True, timeout=20)
+            return r.stdout.strip() if r.returncode == 0 else ''
+        except (OSError, subprocess.TimeoutExpired):
+            return ''
+    commits = run('rev-list', '--count', 'HEAD')
+    if not commits:
+        return None
+    first = run('log', '--reverse', '--format=%ad', '--date=short')
+    first = first.splitlines()[0] if first else ''
+    authors = run('log', '--format=%ae')
+    return {'commits': int(commits), 'first_commit': first, 'last_commit': run('log', '-1', '--format=%ad', '--date=short'),
+            'contributors': len(set(a.lower() for a in authors.splitlines() if a.strip())),
+            'tags': len([x for x in run('tag').splitlines() if x.strip()])}
+
+
+def md_title(p):
+    text = read_text(p, 512 * 1024) or ''
+    for line in text.splitlines()[:40]:
+        m = re.match(r'^#\s+(.+?)\s*#*\s*$', line)
+        if m:
+            return m.group(1).strip()
+    return os.path.splitext(os.path.basename(p))[0]
+
+
+def scan(root):
+    root = os.path.abspath(root)
+    if not os.path.isdir(root):
+        raise ValueError(f'目录不存在：{root}')
+    lang = {}
+    test = {'files': 0, 'loc': 0, 'cases': 0, 'by_lang': {}}
+    dup = {'files': 0, 'loc': 0}
+    seen = {}
+    api = {'total': 0, 'controllers': 0, 'by_module': {}}
+    fe = {'routes': 0, 'views': 0, 'by_project': {}}
+    tables, sql_files = {}, 0
+    manifests, services, composes, docs = [], [], [], []
+    files_seen = 0
+    truncated = False
+
+    top_of = lambda rp: rp.split('/')[0] if '/' in rp else '.'
+
+    for p in walk(root):
+        files_seen += 1
+        rp = rel(root, p)
+        base = os.path.basename(p)
+        ext = os.path.splitext(base)[1].lower()
+        # 清单文件
+        if base == 'pom.xml':
+            i = pom_info(p, root)
+            if i:
+                manifests.append(i)
+        elif base == 'package.json':
+            i = pkg_info(p, root)
+            if i:
+                manifests.append(i)
+        elif base in ('build.gradle', 'build.gradle.kts'):
+            manifests.append(gradle_info(p, root))
+        elif re.fullmatch(r'(docker-)?compose(\.[\w-]+)?\.ya?ml|docker-compose(\.[\w-]+)?\.ya?ml', base):
+            t = read_text(p) or ''
+            sv = compose_services(t)
+            if sv:
+                composes.append({'file': rp, 'services': sv})
+        elif re.fullmatch(r'(application|bootstrap)(-[\w]+)?\.(ya?ml|properties)', base) and '/src/main/resources/' in '/' + rp:
+            t = read_text(p) or ''
+            if base.endswith('.properties'):
+                kv = dict(re.findall(r'^\s*(server\.port|spring\.application\.name)\s*[=:]\s*(\S+)', t, re.M))
+            else:
+                kv = yaml_scalars(t, {'server.port', 'spring.application.name'})
+            if kv:
+                services.append({'name': placeholder_default(kv.get('spring.application.name', '')),
+                                 'port': placeholder_default(kv.get('server.port', '')), 'source': rp,
+                                 'profile': (re.search(r'-(\w+)\.', base) or [None, ''])[1]})
+        if ext == '.md':
+            if re.search(r'(^|/)docs?(/|$)', rp, re.I) or '/' not in rp:
+                docs.append({'path': rp, 'title': md_title(p)})
+            continue
+        L = LANGS.get(ext)
+        if not L:
+            continue
+        if base.endswith(('.min.js', '.min.css', '.bundle.js')) or base in ('package-lock.json',):
+            continue
+        text = read_text(p)
+        if text is None:
+            continue
+        loc = sum(1 for line in text.splitlines() if line.strip())
+        if loc and len(text) / max(1, text.count('\n') + 1) > 400:   # 平均每行 400+ 字符：压缩/生成物
+            continue
+        h = hashlib.md5(text.encode('utf-8', errors='replace')).hexdigest()
+        if h in seen:                                     # 同步副本、拷贝：只算一次
+            dup['files'] += 1
+            dup['loc'] += loc
+            continue
+        seen[h] = rp
+        st = lang.setdefault(L, {'files': 0, 'loc': 0})
+        st['files'] += 1
+        st['loc'] += loc
+        is_test = bool(TEST_PATH.search(rp) or TEST_NAME.search(base))
+        if is_test:
+            test['files'] += 1
+            test['loc'] += loc
+            pat = CASE_PAT.get(L)
+            if pat:
+                c = len(pat.findall(text))
+                test['cases'] += c
+                test['by_lang'][L] = test['by_lang'].get(L, 0) + c
+            continue
+        mod = top_of(rp)
+        if L == 'Java':
+            if '@RestController' in text or re.search(r'@Controller\b', text):
+                api['controllers'] += 1
+                n = len(JAVA_MAP.findall(text))
+                if n:
+                    key = rp.split('/src/')[0] if '/src/' in rp else mod
+                    api['total'] += n
+                    api['by_module'][key] = api['by_module'].get(key, 0) + n
+        elif L in ('JavaScript', 'TypeScript', 'Python'):
+            n = len((PY_ROUTE if L == 'Python' else JS_ROUTE).findall(text))
+            if n:
+                api['total'] += n
+                api['by_module'][mod] = api['by_module'].get(mod, 0) + n
+        if L in ('JavaScript', 'TypeScript') and re.search(r'(^|/)(router|routes)(/|\.)', rp):
+            n = len(ROUTE_PATH.findall(text))
+            if n and ('createRouter' in text or 'VueRouter' in text or 'createBrowserRouter' in text or 'routes' in text):
+                fe['routes'] += n
+                fe['by_project'].setdefault(mod, {'routes': 0, 'views': 0})['routes'] += n
+        if ext in ('.vue', '.tsx', '.jsx') and re.search(r'(^|/)(views|pages)/', rp):
+            fe['views'] += 1
+            fe['by_project'].setdefault(mod, {'routes': 0, 'views': 0})['views'] += 1
+        if L == 'SQL':
+            sql_files += 1
+            for mt in CREATE_TABLE.finditer(text):
+                name = re.sub(r'[`"\[\]]', '', mt.group(1)).split('.')[-1].lower()
+                tables.setdefault(name, rp)
+    if files_seen >= MAX_FILES:
+        truncated = True
+
+    # git：根目录与一、二级子目录里的仓库
+    repos = []
+    cands = [root] + [os.path.join(root, d) for d in sorted(os.listdir(root)) if os.path.isdir(os.path.join(root, d))]
+    for c in cands:
+        if os.path.exists(os.path.join(c, '.git')):
+            s = git_stats(c)
+            if s:
+                s['repo'] = rel(root, c) or '.'
+                repos.append(s)
+
+    return {'root': root, 'files_scanned': files_seen, 'truncated': truncated, 'lang': lang, 'test': test, 'dup': dup,
+            'api': api, 'frontend': fe, 'tables': tables, 'sql_files': sql_files, 'manifests': manifests,
+            'services': services, 'compose': composes, 'docs': docs, 'git': repos}
+
+
+def build(root):
+    S = scan(root)
+    warnings = []
+    by_lang = sorted(({'lang': k, 'files': v['files'], 'loc': v['loc']} for k, v in S['lang'].items()),
+                     key=lambda x: -x['loc'])
+    total_loc = sum(x['loc'] for x in by_lang)
+    prod_loc = total_loc - S['test']['loc']
+    poms = [m for m in S['manifests'] if m['kind'] == 'maven']
+    parents = [m for m in poms if m['modules']]
+    modules = []
+    for par in parents:
+        for mm in par['modules']:
+            child = next((c for c in poms if c['path'] == (par['path'] + '/' + mm['module'] if par['path'] != '.' else mm['module'])), None)
+            desc = mm['comment'] or (child or {}).get('description') or (child or {}).get('name') or ''
+            modules.append({'parent': par['path'], 'module': mm['module'], 'description': desc,
+                            'frameworks': (child or {}).get('frameworks', []),
+                            'source': (child or par)['source']})
+    # 同一服务名可能有 application.yml 与 application-dev.yml 等多份，取不带 profile 的那份
+    svc = {}
+    for s in S['services']:
+        k = s['name'] or s['source']
+        if k not in svc or not s['profile']:
+            svc[k] = s
+    services = sorted(svc.values(), key=lambda s: (s['port'] or 'zzzz', s['name']))
+    top_subprojects, by_path = [], {}
+    for m in S['manifests']:
+        depth = 0 if m['path'] == '.' else m['path'].count('/') + 1
+        if depth > 1 or (m['kind'] == 'maven' and m.get('parent') and any(
+                p['path'] != m['path'] and m['path'].startswith(p['path'] + '/') for p in parents)):
+            continue
+        if m['path'] in by_path:                          # 同一目录既有 build.gradle 又有 package.json：合并
+            t = by_path[m['path']]
+            t['kind'] = t['kind'] + '+' + m['kind']
+            t['source'] = t['source'] + '、' + m['source']
+            t['description'] = t.get('description') or m.get('description', '')
+            fw = dict(t['frameworks']) if isinstance(t['frameworks'], dict) else {k: '' for k in t['frameworks']}
+            fw.update(m['frameworks'] if isinstance(m['frameworks'], dict) else {k: '' for k in m['frameworks']})
+            t['frameworks'] = fw
+            t['node'] = t.get('node') or m.get('node', '')
+            continue
+        m = dict(m)
+        by_path[m['path']] = m
+        top_subprojects.append(m)
+
+    # ── markdown 事实表（每条带来源）──
+    rows = []
+
+    def add(k, v, src):
+        rows.append(f'| {k} | {v} | {src} |')
+    if top_subprojects:
+        add('子工程', f'{len(top_subprojects)} 个：' + '、'.join(f'{m["path"]}（{m["kind"]}）' for m in top_subprojects),
+            '各子工程的 pom.xml / package.json / build.gradle')
+    if modules:
+        add('后端模块（Maven）', f'{len(modules)} 个：' + '、'.join(x['module'] for x in modules),
+            '、'.join(sorted({p['source'] for p in parents})))
+    if services:
+        add('可独立部署的服务（含端口）', f'{len(services)} 个：' + '、'.join(
+            f'{s["name"] or "?"}{("（" + s["port"] + "）") if s["port"] else ""}' for s in services),
+            '各服务 src/main/resources/application.yml（只读 server.port 与 spring.application.name）')
+    for par in parents:
+        fw = []
+        if par.get('parent') == 'spring-boot-starter-parent' and par.get('parent_version'):
+            fw.append(f'Spring Boot {par["parent_version"]}')
+        pv = par.get('properties') or {}
+        for k, lab in (('spring-cloud.version', 'Spring Cloud'), ('spring-cloud-alibaba.version', 'Spring Cloud Alibaba'),
+                       ('java.version', 'Java')):
+            if pv.get(k):
+                fw.append(f'{lab} {pv[k]}')
+        if fw:
+            add(f'后端技术栈（{par["path"]}）', '、'.join(fw), par['source'])
+    java_fw = sorted({f for m in poms for f in m.get('frameworks', [])})
+    if java_fw:
+        add('后端中间件与组件', '、'.join(java_fw), '各模块 pom.xml 依赖')
+    for m in top_subprojects:
+        if m['kind'] == 'maven' or not m['frameworks']:
+            continue
+        items = [f'{k} {v}'.strip() for k, v in list(m['frameworks'].items())[:8]]
+        if m.get('node'):
+            items.insert(0, f'Node.js {m["node"]}')
+        add(f'{m["path"]} 技术栈', '、'.join(items), m['source'])
+    add('代码规模（非空行，去重后）', f'{total_loc:,} 行，其中业务代码 {prod_loc:,} 行、测试代码 {S["test"]["loc"]:,} 行',
+        f'扫描 {S["files_scanned"]:,} 个文件')
+    add('主要语言', '、'.join(f'{x["lang"]} {x["loc"]:,} 行' for x in by_lang[:6]), '按扩展名统计')
+    if S['dup']['files']:
+        add('同步副本（未重复计入）', f'{S["dup"]["files"]:,} 个文件 / {S["dup"]["loc"]:,} 行', '内容哈希完全相同的文件')
+    if S['api']['total']:
+        add('HTTP 接口', f'约 {S["api"]["total"]:,} 个（{S["api"]["controllers"]} 个控制器）',
+            '按 @Get/Post/Put/Delete/PatchMapping 与路由注册语句计数')
+    if S['frontend']['routes'] or S['frontend']['views']:
+        add('前端页面', f'路由约 {S["frontend"]["routes"]} 条、页面组件 {S["frontend"]["views"]} 个', 'router/ 与 views|pages/ 目录')
+    if S['tables']:
+        add('数据库表', f'{len(S["tables"])} 张（{S["sql_files"]} 个 SQL 文件）', 'CREATE TABLE 语句去重')
+    if S['test']['files']:
+        add('自动化测试', f'{S["test"]["files"]:,} 个测试文件、约 {S["test"]["cases"]:,} 个用例', '测试目录与 *Test / *.test.* / test_*.py')
+    if S['compose']:
+        n = sum(len(c['services']) for c in S['compose'])
+        add('容器编排', f'{len(S["compose"])} 个 compose 文件、{n} 个服务定义', '、'.join(c['file'] for c in S['compose'][:4])
+            + ('…' if len(S['compose']) > 4 else ''))
+    for g in S['git']:
+        add(f'版本库 {g["repo"]}', f'{g["commits"]:,} 次提交（{g["first_commit"]} 至 {g["last_commit"]}），{g["contributors"]} 位贡献者',
+            'git log')
+    if S['docs']:
+        add('项目文档', f'{len(S["docs"])} 篇 Markdown', 'docs/ 目录与根目录')
+    md = '| 事实 | 数值 | 来源 |\n|---|---|---|\n' + '\n'.join(rows)
+
+    def short(desc, cap=18):
+        d = (desc or '').strip()
+        if ' - ' in d:
+            d = d.split(' - ')[-1]
+        d = re.split(r'[：:；;。，,（(]|——|—', d)[0].strip()
+        return d if len(d) <= cap else d[:cap - 1] + '…'
+
+    # ── 模块树（交给 render_diagram 的 tree 图型）──
+    name = os.path.basename(S['root'])
+    root_desc = next((p['description'] for p in parents if p['path'] == '.' and p['description']), '')
+    children = []
+    for m in top_subprojects:
+        if m['path'] == '.':
+            continue
+        node = {'name': m['path'], 'desc': short(m.get('description'))}
+        subs = [x for x in modules if x['parent'] == m['path']]
+        if subs:
+            node['children'] = [{'name': x['module'], 'desc': short(x['description'])} for x in subs]
+        children.append(node)
+    if not children and modules:
+        children = [{'name': x['module'], 'desc': short(x['description'])} for x in modules]
+    # 自左向右 + 不画标题块：这份 spec 多半要进 Word，从上往下画的宽树插进 A4 字只剩 3 磅
+    tree = {'type': 'tree', 'title': f'{name} 模块组成', 'direction': 'LR', 'header': False,
+            'root': {'name': name, 'desc': short(root_desc, 24), 'children': children}} \
+        if children else None
+
+    if S['truncated']:
+        warnings.append(f'文件数超过 {MAX_FILES:,}，只统计了前 {MAX_FILES:,} 个：代码规模偏小，引用时注明「不少于」')
+    if not S['git']:
+        warnings.append('没有找到 git 仓库：研发周期、提交次数等过程数据要从别处取证')
+    if not top_subprojects:
+        warnings.append('没有识别到 pom.xml / package.json / build.gradle：技术栈要人工确认')
+
+    return {
+        'ok': True, 'root': S['root'], 'files_scanned': S['files_scanned'],
+        'code': {'total_loc': total_loc, 'prod_loc': prod_loc, 'test_loc': S['test']['loc'], 'by_language': by_lang,
+                 'duplicates': S['dup']},
+        'subprojects': [{k: v for k, v in m.items() if k in ('path', 'kind', 'name', 'version', 'description', 'frameworks', 'source')}
+                        for m in top_subprojects],
+        'maven_modules': modules, 'services': services, 'compose': S['compose'][:12],
+        'api': S['api'], 'frontend': S['frontend'],
+        'database': {'tables': len(S['tables']), 'sql_files': S['sql_files'], 'names': sorted(S['tables'])[:300]},
+        'tests': S['test'], 'git': S['git'],
+        'docs': {'count': len(S['docs']), 'items': S['docs'][:150]},
+        'markdown': md, 'diagram_tree': tree, 'warnings': warnings,
+    }
+
+
+def main(argv):
+    root = argv[1] if len(argv) > 1 else '.'
+    try:
+        res = build(root)
+    except Exception as e:                                  # 如实上报
+        res = {'ok': False, 'error': f'{type(e).__name__}: {e}'}
+    print(json.dumps(res, ensure_ascii=False))
+    return 0 if res.get('ok') else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))