简介这份PDF是田纳西大学数字人文研究生证书课程使用的作品集评估量表Rubric1面向修读数字人文方向的研究生、课程助教与指导教师用于解决作品集如何组织、按什么维度评审才算达标的问题。量表围绕公共网站展示、项目多样性、技术应用与创新、内容质量、呈现与交流五类指标展开逐项给出从“不可接受/不完整”到“优秀”的四级评分描述并要求学生为每门数字人文课程提交代表性项目注明个人或协作分工同时说明图像与文献的引用出处。资源包含1个PDF文件约109KB轻量便于打印或随课程材料分发英文原文保留评审说明、评分体系与自检条款可直接用作评估表或作品集自评清单。目前已有82人学习下载适合需要对照官方标准打磨作品集、准备年终展示论坛的研究生与教师参考。1. 数字人文作品集 Rubric1 的核心逻辑一份评分表如何决定证书申请结果见过太多人把数字人文作品集当成“项目成果的 PDF 合订本”结果在 Rubric1 的评分表上栽了跟头。一个做晚清报刊文本挖掘的朋友把三年积累的 Python 脚本、GIS 地图、词频可视化全部导出成静态图片塞进一份两百页的文档自认为内容饱满。对照 Rubric1 逐项自评后技术实现和可复现性两个维度连及格线都没碰到。问题不在他做了什么项目而在评分表关心的不是“你做了多少”而是“别人能不能看懂、能不能验证、能不能接着用”。Rubric1 是一份把“数字方法”和“人文论证”两条评价线拆成可操作条目的评分工具。它不看项目规模也不在意用了多少热门工具逐项检查的是问题意识是否从人文材料中生长出来、技术选型是否支撑了论证、数据和代码是否可追溯、文档能否让第三方独立复现。田纳西大学数字人文研究生证书课程把这份作品集当作结业门槛意味着评审同时站在学术导师和工程验收两个位置上审视你的材料。不管你是否申请这个证书项目只要你在做数字人文方向的作品集或项目文档Rubric1 的结构都值得当成需求规格来读。后面几章从评分维度拆解入手落到自动化自检脚本和构建流程让评分表上的每一条都能对应到你仓库里的某个文件、某段代码或者某条提交记录。2. 拆解 Rubric1 的评分维度把“人文技术”翻译成可检查的工程指标把评分表当需求文档读第一步是找出它的维度分布和权重倾向。Rubric1 的条目通常围绕六个锚点展开每个锚点下面再分若干可观察的行为描述。这些描述不是空泛的形容词而是可以对应到具体文件、命令和目录结构的检查项。2.1 Rubric1 的六个评分锚点与权重分布根据常见的 DH 作品集评审框架和 Rubric1 的条目结构评分维度大致可以归为六类。不同版本在权重上有差异但核心锚点相对稳定。评分锚点检查内容典型权重对应产出物问题意识与人文论证研究问题是否从材料中产生数字方法是否服务于论证25%项目说明、研究日志技术实现深度工具选择理由、代码复杂度、数据处理链路20%源码仓库、技术笔记数据管理与规范数据来源、格式标准、元数据、许可协议15%data/ 目录、datapackage.json可复现性环境配置、依赖锁定、构建脚本15%Dockerfile、requirements.txt文档与呈现README、使用说明、界面可读性15%README.md、静态站点批判性反思对方法局限、伦理问题、失败尝试的讨论10%reflection.md、issue 记录这张表里最容易踩坑的是权重分布。很多人把 80% 的精力砸在“技术实现深度”上写了几千行代码但问题意识和反思两块加起来 35% 的分数几乎空着。评审看到的是一个技术演示不是一个数字人文项目。注意不同年份的 Rubric1 可能在权重上有微调建议拿到最新版 PDF 后先做一次权重对照把每一项的分值抄到项目管理的看板里。2.2 从评分描述到可检查项把每条 rubric 翻译成布尔判定评分表上的描述往往是“作品展现了清晰的论证逻辑”这种句子。要让它可检查得往下翻译一层。我一般会把每条描述改写成一个可以用“是/否”回答的问题再绑定到一个文件路径或命令的输出。下面这张对照表是把 Rubric1 中“可复现性”维度的三条描述拆开后的结果原始评分描述可检查问题检查方式项目提供了完整的环境配置说明仓库根目录是否存在 README 或 INSTALL且包含依赖安装命令test -f README.md依赖版本被锁定是否存在 requirements.txt、package-lock.json 或 environment.ymlfind . -maxdepth 2 -name *.lock -o -name requirements.txt第三方能按文档独立运行在干净容器里执行构建脚本是否无报错docker build -t portfolio-test . docker run --rm portfolio-test这种翻译方式的好处是你可以把它写进一个检查脚本每次提交前自动跑一遍。人工逐条对照评分表容易漏项脚本不会。2.3 权重最高的“问题意识”维度怎么落地成文件问题意识这一块看起来最“软”但它在 Rubric1 里权重最高而且完全可以用工程化的方式组织材料。我通常会在仓库里建一个narrative/目录里面放三样东西研究问题的来源说明、材料选择理由、数字方法介入的逻辑。narrative/ ├── 01-research-question.md # 问题从哪份档案、哪个现象中产生 ├── 02-source-selection.md # 为什么选这批材料排除了什么 └── 03-method-rationale.md # 为什么用这个词频工具而不是那个逻辑说明这三个文件分别回答评审在“问题意识”维度下最常追问的三个问题。第一个文件说明问题不是凭空来的第二个文件展示你对材料边界的判断第三个文件证明技术选型是论证驱动的而不是技术驱动的。参数上没有硬性要求但每份文件建议控制在 800 到 1500 字太长评审不会细看太短显得敷衍。3. 用 Python 对作品集做 Rubric1 自动化自评文件结构、元数据与代码质量三路扫描人工逐条对照评分表容易漏我一般会写一个自评脚本把 Rubric1 里可自动化的检查项跑一遍。脚本不替代人工判断但能确保文件结构、元数据完整性和基本代码质量不出低级问题。3.1 用 pathlib 扫描作品集目录结构并匹配评分表条目第一路扫描做的是目录结构和文件存在性检查。把 Rubric1 里“文档与呈现”“数据管理”两个维度的基础要求写成一个配置字典脚本遍历仓库后输出缺失项。from pathlib import Path import json # 把 Rubric1 中可自动检查的条目写成配置 RUBRIC_CHECKS { readme: {path: README.md, weight: 3, desc: 项目总说明}, data_dir: {path: data, weight: 3, desc: 原始数据与处理后数据}, license: {path: LICENSE, weight: 1, desc: 数据与代码许可}, narrative: {path: narrative, weight: 4, desc: 问题意识与论证文档}, notebooks: {path: notebooks, weight: 2, desc: 分析过程记录}, reflection: {path: reflection.md, weight: 3, desc: 批判性反思}, } def scan_portfolio(root: str) - dict: root_path Path(root) results {} for key, check in RUBRIC_CHECKS.items(): target root_path / check[path] results[key] { exists: target.exists(), is_dir: target.is_dir() if target.exists() else False, weight: check[weight], desc: check[desc], } return results if __name__ __main__: report scan_portfolio(.) missing [k for k, v in report.items() if not v[exists]] total sum(v[weight] for v in report.values() if v[exists]) max_total sum(v[weight] for v in report.values()) print(json.dumps(report, indent2, ensure_asciiFalse)) print(f\n基础项得分: {total}/{max_total}) if missing: print(f缺失项: {, .join(missing)})逻辑说明RUBRIC_CHECKS字典把评分表里可自动检查的条目映射到文件路径上weight字段是该项在自评体系里的相对重要性。scan_portfolio函数遍历根目录用pathlib检查每个目标是否存在。输出分两部分完整报告和缺失项摘要。参数说明root参数指向作品集仓库的根目录默认当前目录。如果你把作品集分成多个子模块可以把RUBRIC_CHECKS里的path改成相对子目录的路径。权重值不需要和 Rubric1 完全一致它只用于自评排序帮你判断先补哪个缺失项。3.2 元数据规范校验从 README 到数据字典的字段完整性第二路扫描检查文档内容的质量不只是“文件在不在”而是“文件里有没有关键信息”。我一般会检查 README 是否包含项目描述、安装步骤、数据来源和使用示例这四个段落。import re REQUIRED_SECTIONS { 项目描述: r##\s*(项目描述|Project Description|Overview), 安装步骤: r##\s*(安装|Installation|Setup|Getting Started), 数据来源: r##\s*(数据|Data|Dataset), 使用示例: r##\s*(使用|Usage|Example), } def check_readme_sections(readme_path: str) - dict: text Path(readme_path).read_text(encodingutf-8) result {} for name, pattern in REQUIRED_SECTIONS.items(): result[name] bool(re.search(pattern, text, re.IGNORECASE)) return result def check_data_dict(data_dir: str) - list: 检查 data/ 目录下是否有数据字典或元数据文件 data_path Path(data_dir) meta_files list(data_path.glob(*.json)) list(data_path.glob(*datapackage*)) return [str(f) for f in meta_files]逻辑说明REQUIRED_SECTIONS用正则匹配 README 里的二级标题覆盖 Rubric1 对“文档与呈现”维度的最低要求。check_data_dict检查data/目录下是否有 JSON 格式的元数据或 datapackage 描述文件对应“数据管理与规范”维度。参数说明正则里的re.IGNORECASE让匹配不区分大小写因为有些 README 写英文标题。如果你的项目数据以 CSV 为主建议在data/下放一个datapackage.json字段参考 Frictionless Data 规范至少包含name、resources、licenses三个顶层字段。3.3 代码质量静态扫描与 Rubric1 技术分项的映射第三路用radon和pylint做基础代码质量检查输出圈复杂度和未使用变量等指标。这些指标不直接对应 Rubric1 的评分锚点但能帮你判断“技术实现深度”维度里代码部分是否站得住。# 安装静态检查工具 pip install radon pylint # 输出所有 Python 文件的圈复杂度按复杂度排序 radon cc -s -a notebooks/ src/ --total-average # 检查代码规范问题只看错误和警告 pylint notebooks/ src/ --disableall --enableE,W --output-formattext逻辑说明radon cc输出每个函数的圈复杂度-s显示复杂度评分-a显示平均值。圈复杂度超过 10 的函数在评审眼里是“可读性风险”建议拆成更小的函数。pylint只打开错误和警告级别忽略风格建议避免输出太长。参数说明--total-average会在最后输出整体平均复杂度我一般把目标定在 5 以下。如果你的 notebook 里有很多探索性代码可以把notebooks/排除在radon检查之外只对src/做严格检查。注意静态检查的结果不要直接贴进作品集正文而是用来指导修改。评审看到的是修改后的代码不是检查报告。3.4 把三路扫描结果汇总成一份自评报告三路扫描跑完后把结果合并成一个 Markdown 报告按 Rubric1 的维度分组呈现。报告里只列缺失项和改进建议通过项用一行统计带过。扫描路径检查项数量通过缺失/警告对应 Rubric1 锚点目录结构642文档与呈现、数据管理文档内容431问题意识、文档与呈现代码质量动态动态动态技术实现深度这样一份报告放在仓库的docs/self-assessment.md里提交前跑一次能避免大部分低级失分。更重要的是它让评审看到你对自己的项目有系统性的检查习惯。4. 从本地 notebook 到可评审的作品集Git 历史、静态站点与数据持久化的工程链路自评脚本解决的是“有没有”的问题这一章解决“能不能被第三方独立跑起来、能不能被长期引用”的问题。Rubric1 里可复现性和数据管理两个维度加起来占 30%需要一套完整的构建和发布链路来支撑。4.1 用 Git 提交历史构建“过程性评分”的证据链Rubric1 的“问题意识与人文论证”维度里有一条隐含要求评审希望看到项目是怎么一步步演化的而不是一个突然出现的成品。Git 提交历史是展示过程的最好材料但前提是提交信息有结构。# 查看提交历史的时间分布和提交信息 git log --oneline --since6 months ago --prettyformat:%ad %s --dateshort # 按目录统计提交频次看哪些部分迭代最多 git log --name-only --prettyformat: | sort | uniq -c | sort -rn | head -20逻辑说明第一条命令输出近半年的提交记录日期加提交信息方便你检查迭代节奏是否合理。第二条统计每个文件被修改的次数修改频次高的文件通常是项目核心可以在 README 里重点说明。参数说明--since的时间范围根据你的项目周期调整。如果项目只做了三个月改成--since3 months ago。--dateshort输出YYYY-MM-DD格式避免时区和格式混乱。我一般会在提交信息里用feat:、fix:、docs:、refactor:这几个前缀区分提交类型。评审如果看 Git 历史能快速理解每个阶段的重点。如果评审不看这些前缀也不影响项目本身。4.2 用静态站点把 notebook 和数据展示转成可浏览的评审入口评审不会去克隆你的仓库再跑 Jupyter。我一般会用一个静态站点生成器把 notebook 导出成 HTML加一个首页说明部署到静态托管上把链接放进 README 顶部。工具选型上Jekyll 和 Astro 都行我用 Astro 多一些因为构建速度快。# 用 nbconvert 把 notebook 导出为 HTML jupyter nbconvert --to html \ --output-dir dist/notebooks \ --template classic \ notebooks/*.ipynb # 用 Astro 建一个最小站点骨架 npm create astrolatest portfolio-site -- --template minimal cd portfolio-site npm install逻辑说明jupyter nbconvert把 notebook 转成独立 HTML--output-dir指定输出目录。--template classic保留输出单元格和代码适合评审阅读。Astro 的 minimal 模板生成一个空站点把导出的 HTML 放进public/notebooks/目录首页用 Markdown 写项目概述和导航。参数说明--template可以换成lab获得更接近 JupyterLab 的样式但classic的打印效果更好。如果你的 notebook 里有交互组件比如 Plotly需要额外安装nbconvert[webpdf]或用--to webpdf导出 PDF 版本作为补充。注意导出的 HTML 里可能包含本地文件路径或临时变量提交前用grep -r /Users/ dist/检查一遍把个人路径替换成相对路径。4.3 数据持久化从 CSV 到 Parquet 加数据字典的规范化处理Rubric1 的“数据管理”维度要求数据可追溯、格式规范、有元数据。我一般会把原始数据和处理后数据分开存放原始数据只读处理后数据用 Parquet 格式保存附带一个 JSON 数据字典。import pandas as pd import json from pathlib import Path # 读取原始 CSV不做任何修改 raw pd.read_csv(data/raw/corpus.csv, encodingutf-8) # 基础清洗后保存为 Parquet cleaned raw.dropna(subset[text, date]).copy() cleaned[date] pd.to_datetime(cleaned[date]) cleaned.to_parquet(data/processed/corpus.parquet, indexFalse) # 生成数据字典 data_dict { name: late-qing-corpus, resources: [ { path: data/processed/corpus.parquet, schema: { fields: [ {name: text, type: string, description: 正文文本}, {name: date, type: date, description: 出版日期}, {name: source, type: string, description: 来源档案编号}, ] }, } ], licenses: [{name: CC-BY-4.0, path: https://creativecommons.org/licenses/by/4.0/}], } Path(data/datapackage.json).write_text( json.dumps(data_dict, indent2, ensure_asciiFalse), encodingutf-8 )逻辑说明raw数据只读所有清洗操作在新变量上进行。Parquet 格式比 CSV 小读取快而且保留数据类型。data_dict按 Frictionless Data 的 datapackage 结构组织包含资源路径、字段描述和许可协议。参数说明dropna的subset指定只删除text和date为空的行。to_parquet的indexFalse避免把 pandas 索引写进文件。数据字典里的licenses字段必须填Rubric1 对数据许可有明确要求缺这项会扣分。4.4 用 Docker 把环境配置固化成可验证的构建单元可复现性维度的最高要求是“第三方能在干净环境里跑通”。我一般会写一个 Dockerfile把 Python 版本、依赖安装和数据下载步骤全部固化。FROM python:3.11-slim WORKDIR /app # 先复制依赖文件利用 Docker 层缓存 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制项目文件 COPY . . # 运行自评脚本作为构建检查 RUN python scripts/self_assessment.py --fail-on-missing CMD [jupyter, nbconvert, --to, html, --output-dir, dist/, notebooks/analysis.ipynb]逻辑说明基础镜像用python:3.11-slim体积小且版本明确。先复制requirements.txt再安装依赖这样修改代码时不会重复安装依赖。RUN python scripts/self_assessment.py --fail-on-missing把自评脚本接入构建流程缺文件时构建失败。参数说明--no-cache-dir避免 pip 缓存增加镜像体积。--fail-on-missing是自评脚本的自定义参数检测到缺失项时返回非零退出码。如果你的项目需要下载外部数据在COPY . .之后加一个RUN python scripts/download_data.py确保构建过程包含数据获取步骤。5. 提交前的 Rubric1 反查模拟评审打分与高频扣分点的修复清单作品集改到最后一轮最容易出问题的不是技术实现而是评审打开材料后的前五分钟体验。这一章用一个模拟打分的流程把 Rubric1 的评分表反过来当检查清单用。5.1 用评分表做反向检查从评审视角走一遍材料我一般会请一个不了解项目的朋友给他 Rubric1 的评分表和作品集链接让他按顺序走一遍先看首页说明再打开一个 notebook再翻到反思文档最后尝试按 README 跑一遍命令。记录他在哪一步卡住、哪一步问问题、哪一步直接跳过。这个过程的输出是一份“评审路径记录”把卡住的位置和对应的评分维度标出来。常见的结果是首页缺少项目一句话说明、notebook 输出单元格太多、README 的安装命令没有指定 Python 版本、反思文档写成了技术总结而不是方法讨论。注意模拟评审的人选最好是同专业但不同技术背景的纯技术背景的人容易忽略人文论证的问题纯人文背景的人容易忽略环境配置的细节。5.2 高频扣分点修复文档缺失、链接腐烂与数据不可获取根据我见过的作品集以下五类问题出现频率最高修复成本也最低。高频扣分点对应 Rubric1 锚点修复方式检查命令README 缺少项目一句话说明文档与呈现在标题下加一行引用说明项目做什么、用什么数据head -5 README.mdnotebook 输出未清理技术实现深度提交前执行jupyter nbconvert --clear-output --inplace notebooks/*.ipynbgrep -c execution_count notebooks/*.ipynb外部链接失效数据管理与规范用lychee或linkchecker扫描 README 和文档中的 URLlychee --verbose README.md narrative/*.md数据文件未附许可数据管理与规范在data/下加LICENSE或在datapackage.json里填licenses字段test -f data/LICENSE反思文档写成技术总结批判性反思重写为“我原本想做什么、实际遇到了什么限制、如果重做会改什么”三段式人工检查# 批量清理 notebook 输出 jupyter nbconvert --clear-output --inplace notebooks/*.ipynb # 用 lychee 检查所有 Markdown 文件中的链接 lychee --verbose --no-progress README.md narrative/*.md docs/*.md # 检查 data/ 目录下是否有许可文件 find data/ -maxdepth 1 -iname *license* -o -iname *copying*逻辑说明--clear-output清空 notebook 的执行计数和输出避免提交几百 KB 的冗余数据。lychee扫描所有链接并报告失效 URL--no-progress关闭进度条让输出更干净。find命令检查数据目录下的许可文件匹配license或copying两种常见命名。参数说明--inplace直接修改原文件建议在 Git 提交前执行这样改动可以单独提交一条chore: clear notebook outputs。lychee的--verbose输出每个链接的检查结果如果链接太多可以只检查 README。find的-maxdepth 1避免递归到子目录。5.3 把反查结果写成一份提交说明最后一轮修改完成后我一般会在仓库根目录加一个submission-notes.md记录这一轮改了什么、为什么改、哪些问题已知但未解决。这份文件不是 Rubric1 的硬性要求但它向评审传递一个信号你对作品集的质量有主动管理意识。文件结构建议三段本轮修改摘要、已知限制、后续计划。每段三五句话不要写成又一篇反思文档。已知限制那一段尤其重要Rubric1 的批判性反思维度鼓励你主动暴露问题而不是等评审来发现。把限制写清楚反而比假装项目完美得分更高。本文还有配套的精品资源点击获取