Week02｜作业｜资产清单、四类契约 v1 与采集计划

把 Week02 收成一套能进入 Week03 的输入准入包

这次作业不是把实验再抄一遍，而是把 Week02 的结果整理成一套真正能承接 Week03 ingest 的工程交付物。

你要交的不是“课堂答案”，而是：

  • 哪些输入资产值得接入
  • 每类输入必须带什么 metadata
  • 哪些字段涉及高风险 PII
  • 哪些 JSON contract 才能作为运行时 gate
  • 这次 ingest 到底接哪一批 source，怎么验证它至少最小可运行

回看实验页 返回 Week02 总览

1. 作业目标

这次作业要把 Week02 的工件压成一套输入准入包。

你最终交出来的内容，必须回答下面 5 个问题：

  1. 哪些资产可以进入系统
  2. 每类输入至少要带什么 metadata
  3. 哪些字段属于高风险 PII，应该如何处理
  4. 哪些 JSON contract 才构成真正的运行时 gate
  5. 你的 manifest 和 ingest strategy 如何接到 Week03
Important这次作业和实验的区别

实验页解决的是：你能不能把 Week02 的闭环跑起来。

作业页解决的是：你能不能把这套闭环整理成一份可提交、可审查、可进入 Week03 的正式工程包。

1.5 这份作业在整门课里的真实价值

这份作业不是 Week02 的结课文件，而是 Week03 的入口准入包。

  • Week03 的 ingest admission 会继续消费你在这里定义的 contract 和 manifest。
  • Week08 的 retrieval、citation 和 response contract 会继续消费你今天定义的 metadata 与 evidence。
  • Week10 的 tool boundary、Week14 的 release / lineage / rollback，也都会建立在这套输入边界之上。

换句话说，评审方不是在收文件，而是在收一套可以被后续系统继续消费的工程输入。

2. 参考投入时间

如果你只是阅读作业要求并理解交付结构，大约需要 20–30 分钟；如果你要把蓝图、四类 contract、manifest、ingest strategy 和提交说明真正收成一套可审查的输入准入包，并完成验证，建议预留 4–6 小时。

3. 你要提交什么

本次作业所有交付物，都应保留在 repo 的真实路径下。

A. 资产盘点

  • docs/blueprints/week02/asset_inventory_v1.csv

B. metadata / PII 设计

  • docs/blueprints/week02/metadata_minimums_v1.md
  • docs/blueprints/week02/pii_policy_matrix_v1.csv

C. 四类数据契约

  • contracts/data/ticket_contract.json
  • contracts/data/doc_asset_contract.json
  • contracts/data/audio_asset_contract.json
  • contracts/data/video_asset_contract.json

D. 采集计划 / manifest

  • data/seed_manifests/manifest_week02_practice_v1.json
  • docs/blueprints/week02/ingest_strategy_v1.md

E. 提交说明

  • docs/blueprints/week02/submission_readme.md

4. 标准提交树

docs/
  blueprints/
    week02/
      asset_inventory_v1.csv
      metadata_minimums_v1.md
      pii_policy_matrix_v1.csv
      ingest_strategy_v1.md
      submission_readme.md
contracts/
  data/
    ticket_contract.json
    doc_asset_contract.json
    audio_asset_contract.json
    video_asset_contract.json
data/
  seed_manifests/
    manifest_week02_practice_v1.json

5. 提交工件总表

类别 文件路径 这份工件回答什么
资产盘点 docs/blueprints/week02/asset_inventory_v1.csv 哪些输入值得接入
metadata 标准 docs/blueprints/week02/metadata_minimums_v1.md 每类输入至少要带什么字段
PII 规则 docs/blueprints/week02/pii_policy_matrix_v1.csv 哪些字段能进模型、哪些必须拦截
ticket contract contracts/data/ticket_contract.json 工单输入如何被 gate
document contract contracts/data/doc_asset_contract.json 文档输入如何被 gate
audio contract contracts/data/audio_asset_contract.json 音频输入如何被 gate
video contract contracts/data/video_asset_contract.json 视频输入如何被 gate
practice manifest data/seed_manifests/manifest_week02_practice_v1.json 这次 ingest 到底接哪一批 source
ingest strategy docs/blueprints/week02/ingest_strategy_v1.md full / incremental / replay 如何选择
提交说明 docs/blueprints/week02/submission_readme.md 你改了什么、为什么这么改、如何验证

6. 最低完成标准

这次作业的最低通过线有 4 条：

  1. 至少覆盖四类输入中的两类，推荐四类都覆盖
  2. 四类 contract 必须都经过检查，不允许只交一类
  3. 至少提供 1 个可工作的 manifest_week02_practice_v1.json
  4. 必须给出 1 次 contract tests 与 1 次 seed loader dry-run 的验证说明

如果你只交了 Markdown 总结，没有改 repo 中真实的 contract / manifest / blueprint 路径，这次作业不能算完成。

7. 评分 Rubric

维度 权重 重点看什么
资产盘点质量 20 有没有从资源目录升级为输入地图
metadata / PII 设计 25 是否形成字段 × 动作 × 风险矩阵
四类 contract 完整性 35 是否具备 schema + semantics + policy + quality 思维
manifest / 采集计划质量 10 是否具备运行时意图
submission_readme.md 说明力 10 能否体现你的判断

8. 优秀 / 合格 / 不合格 分别长什么样

档位 特征
优秀 有完整判断链，能解释 trade-off，能看出 Week03 可直接承接
合格 工件齐全，路径正确，能跑通最小验证
不合格 只交说明文档，不改真实 repo 工件

9. 推荐验证方式

本次作业默认统一走 Docker devbox，不要求本机裸跑。

验证命令 1：contract tests

docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  pytest tests/contract/ -v

验证命令 2：seed loader dry-run

docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python -m pipelines.ingestion.seed_loader --manifest-dir data/seed_manifests

你需要在 docs/blueprints/week02/submission_readme.md 里明确记录：

  • 你执行了什么命令
  • 命令是否成功
  • 如果失败，你做了什么修正

10. 审阅者会按什么顺序看你的作业

  1. 先看 docs/blueprints/week02/submission_readme.md
  2. 再看 docs/blueprints/week02/asset_inventory_v1.csv
  3. 再看 docs/blueprints/week02/metadata_minimums_v1.md 与 docs/blueprints/week02/pii_policy_matrix_v1.csv
  4. 再看四类 contract
  5. 最后看 manifest_week02_practice_v1.json 和验证结果

11. 评审人最看重的 5 件事

评审重点 为什么它重要
路径是否 repo-aligned 课程工件必须能直接进入项目现实
metadata / PII 是否有判断 不是抄字段表，而是真的理解边界
contract 是否具备 gate 意义 能不能拦截运行时风险，而不是只描述结构
manifest 是否能接到 Week03 不是“随便写一个 JSON”，而是批次入口
验证记录是否真实 没有运行证据，这套工件就还只是纸面设计

12. 最容易丢分的 8 个点

丢分点 为什么会被扣分
只交 Markdown，不改 repo 中真实 contract / manifest 说明没有把课程结论压进工程结构
仍然使用 YAML contract / YAML manifest 作为主交付格式 与当前项目现实冲突
资产清单只有资源名，没有 owner / access / update / risk 还停留在资源罗列层
PII 只写等级，不给字段级动作矩阵 没有形成可执行边界
contract 只有 schema，没有 semantics / quality / policy 不是 gate，只是字段表
采集计划只有“每天跑一次” 没有声明 full / incremental / replay 的业务语义
没有提交验证结果 无法证明最小闭环成立
submission_readme.md 只写流水账 审阅者看不出你的判断

13. 一个可直接改写的 submission_readme.md 模板

# Week02 Submission README

## 1. 本次覆盖的输入资产
- 业务线：
- 资产类型：
- 为什么这些资产进入本次范围：

## 2. 关键 metadata 设计
- shared core：
- ticket 特有字段：
- document 特有字段：
- audio 特有字段：
- video 特有字段：

## 3. 高风险 PII 与边界判断
- 哪些字段被归为 restricted / sensitive：
- 哪些动作必须拦截：
- 哪些场景允许 warn / quarantine：

## 4. Data Contract 设计说明
- 哪些 contract 被修正：
- 哪些字段属于 shape：
- 哪些字段属于 semantics / evidence / policy / quality：
- 哪类变更会被视为 breaking：

## 5. Manifest / ingest strategy 说明
- 本次 manifest 对应哪些 source：
- 使用了哪些 load mode：
- 为什么这样设计：

## 6. 验证记录
- contract tests 命令：
- contract tests 结果：
- seed loader dry-run 命令：
- seed loader dry-run 结果：

## 7. 失败与修正
- 我故意注入了什么失败：
- 它在哪个阶段暴露：
- 我怎么修：

## 8. 进入 Week03 前，我的最终判断
- 已具备的 ingest baseline：
- 仍需 Week03 解决的运行时能力：

14. 推荐验证方式之外，还可以怎么加分

以下内容可以作为加分项，但不是最低要求：

  • 再补 1 个 manifest
  • 在 tests/contract/fixtures/week02/ 里增加更多反例
  • 清楚说明一个 breaking change 会如何影响 Week03 ingest
  • 再加 1 张你自己的输入控制面闭环图

15. 验收方式

验收重点不是“你有没有听懂课”，而是你有没有把 Week02 的工件真正整理成一个可以被项目消费的输入准入包。

最低通过线

更强的完成度

16. 这页和实验页怎么衔接

实验页解决的是：

  • 你能不能把 Week02 的输入控制面跑起来

作业页解决的是：

  • 你能不能把这套工件整理成一个正式提交包

所以这页不再重复实验步骤，而是把实验结果收口成：

  • 蓝图
  • contract
  • manifest
  • ingest strategy
  • 提交说明
  • 验证记录

这些东西，就是你进入 Week03 之前的真实工程基线。

17. 交作业前的 10 项自检