scripts/data_building/refresh_route_docs.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import os
from pathlib import Path
import json
from datetime import datetime

ROOT = Path(os.environ.get("ENHANCED_REPLICA_ROUTE_ROOT", r"F:\codex开发\研究\研究成果\实验路线\20260408_SOTA路线重构"))
DATASET = ROOT / 'dataset'


def ls_lines(dir_path: Path):
    lines = []
    for p in sorted(dir_path.iterdir(), key=lambda x: (x.is_file(), x.name.lower())):
        if p.name == 'README.md':
            continue
        t = '目录' if p.is_dir() else '文件'
        lines.append(f'- `{p.name}`（{t}）')
    return '\n'.join(lines) if lines else '- （当前无其他内容）'


def write_md(dir_path: Path, content: str):
    dir_path.mkdir(parents=True, exist_ok=True)
    (dir_path / 'README.md').write_text(content.strip() + '\n', encoding='utf-8')


def main():
    now = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    archive_desc = (
        "- `候选原始归档/`：历史候选资料归档。"
        if (ROOT / '候选原始归档').exists()
        else "- `候选原始归档/`：当前不存在（不影响主线实验）。"
    )

    write_md(ROOT, f"""
# 20260408_SOTA路线重构

最后更新：{now}

## 目录说明
- `dataset/`：统一 schema 的可直接实验数据。
- `env/`：Conda 环境与安装说明（本地4060/A100通用）。
- `runs/`：实验输出目录（按 EID/run_name 组织）。
- `复现/`：方法和路线文档。
{archive_desc}
- `__pycache__/`：Python 缓存目录（自动生成）。
- `脚本/`：数据处理与实验脚本。

## README 自动更新命令
```powershell
python F:\\codex开发\\研究\\研究成果\\实验路线\\20260408_SOTA路线重构\\脚本\\数据处理\\refresh_route_readmes.py
```

## 当前内容
{ls_lines(ROOT)}
""")

    pycache = ROOT / '__pycache__'
    if pycache.exists():
        write_md(pycache, f"""
# __pycache__

Python 运行时自动生成的缓存目录，删了会自动再生成。

## 当前内容
{ls_lines(pycache)}
""")

    script_root = ROOT / '脚本'
    if script_root.exists():
        write_md(script_root, f"""
# 脚本目录

- `数据处理/`：清洗与构建脚本。
- `跑实验用/`：训练、评估、推理脚本。
- `跑实验用_传统对照/`：TF-IDF、SVM 等传统机器学习对照脚本。

## README 自动更新脚本
- `数据处理/refresh_route_readmes.py`

## 当前内容
{ls_lines(script_root)}
""")
        for sub in [script_root / '数据处理', script_root / '跑实验用', script_root / '跑实验用_传统对照']:
            if sub.exists():
                if sub.name == '数据处理':
                    write_md(sub, f"""
# {sub.name}

## 说明
- 放数据清洗、构建、审计脚本。
- 每次目录内容变化后，运行 `refresh_route_readmes.py` 更新 README。

## 当前内容
{ls_lines(sub)}
""")
                elif sub.name == '跑实验用_传统对照':
                    write_md(sub, f"""
# {sub.name}

## 说明
- 放传统机器学习对照实验脚本，不替代主线 E00-E11。

## 当前内容
{ls_lines(sub)}
""")
                else:
                    write_md(sub, f"""
# {sub.name}

## 说明
- 放训练、评估、推理、对比实验脚本。

## 当前内容
{ls_lines(sub)}
""")

    replay = ROOT / '复现'
    if replay.exists():
        write_md(replay, f"""
# 复现文档

## 当前内容
{ls_lines(replay)}
""")

    archive = ROOT / '候选原始归档'
    if archive.exists():
        write_md(archive, f"""
# 候选原始归档

历史留档目录，不作为当前主线训练输入。

## 当前内容
{ls_lines(archive)}
""")
        for p in sorted([x for x in archive.iterdir() if x.is_dir()]):
            write_md(p, f"""
# {p.name}

归档快照目录。

## 当前内容
{ls_lines(p)}
""")

    if DATASET.exists():
        write_md(DATASET, f"""
# dataset

统一可用数据目录（主 schema）。

## 当前内容
{ls_lines(DATASET)}
""")

        for p in sorted([x for x in DATASET.iterdir() if x.is_dir()]):
            write_md(p, f"""
# {p.name}

## 当前内容
{ls_lines(p)}
""")

        for ds in sorted(DATASET.rglob('DS*_v1')):
            if not ds.is_dir():
                continue
            mf = ds / 'manifest.json'
            if mf.exists():
                m = json.loads(mf.read_text(encoding='utf-8'))
                write_md(ds, f"""
# {m.get('dataset_id', ds.name)}

## 规模
- 总样本：{m.get('record_count_total', 0)}
- split：{m.get('record_count_by_split', {})}
- label（human=0, ai=1）：{m.get('record_count_by_label', {})}

## 当前内容
{ls_lines(ds)}
""")
            else:
                write_md(ds, f"""
# {ds.name}

## 当前内容
{ls_lines(ds)}
""")

    env_dir = ROOT / 'env'
    if env_dir.exists():
        write_md(env_dir, f"""
# env

## 说明
- 放环境定义与安装说明。

## 当前内容
{ls_lines(env_dir)}
""")

    runs_dir = ROOT / 'runs'
    if runs_dir.exists():
        write_md(runs_dir, f"""
# runs

## 说明
- 实验运行产物目录。
- 路径约定：`runs/<EID>/<run_name>/`

## 当前内容
{ls_lines(runs_dir)}
""")

    print('Readme refresh done.')


if __name__ == '__main__':
    main()