project-as-newspaper

name

project-as-newspaper

description

Turn any codebase into a teaching-style, visual learning website — left sidebar navigates module→chapter, the body is an editorial/textbook reading of every source file (role, annotated code, design rationale, connections, self-test), nothing missed. Use when the user wants to learn/study/onboard a codebase, generate source-code documentation as an interactive site, or "read the whole project file by file". Project-agnostic and portable across agents.

把任意代码库变成一个教导式、可视化的交互学习网站(逐文件精读、编辑杂志/教科书排版、带学习进度、一个文件不漏)。

本 skill 是一个自包含、跨 agent、跨项目的工具包:核心是"与 agent 无关的契约 + 纯 Python 脚本 + 静态前端模板"。完整流程与所有命令见同目录 INSTRUCTIONS.md —— 先读它。

每章必须在读完文件后总结出教学化 title,不能照抄目录名;每章还必须写 styleFingerprint,说明本章独特讲解组织方式。正文要根据代码真实结构展开,不能像模板批量套出来。

先和用户确认(若未给出)

• ROOT(要学的仓库根)、PROJECT(项目名)、BLURB(一句话简介)。
• 范围:全部源码 / 某些目录 / 某语言;是否含测试。规模大时建议先 --include 圈核心目录。

通用执行步骤(所有支持 skills 的 agent)

设 TUTOR=<本 skill 文件夹绝对路径>、WORK=$ROOT/.project-as-newspaper、PARTS=$WORK/out/chapters。如果运行环境能提供当前 skill 目录,直接用该目录;否则先定位包含本 SKILL.md 的文件夹。

1. 分章:python3 $TUTOR/scripts/build_chapters.py --root "$ROOT" --out "$WORK/chapters.json" --max-files 14 --no-tests。cat 一眼确认分章合理。
2. 生成教学内容:mkdir -p "$PARTS",然后逐章读取 chapters.json,用 scripts/fill_prompt.py 或等价替换生成该章 prompt。如果当前 agent 支持 subagent/并行代理,必须默认每章派一个 subagent 并行生成;只有环境没有 subagent 能力时,才由当前 agent 顺序逐章生成。每章产物都写到 "$PARTS/<id>.json"。
3. 装配+校验:python3 $TUTOR/scripts/assemble.py --chapters "$WORK/chapters.json" --parts "$PARTS" --out "$WORK/out/site" --project "$PROJECT"。 若退出码非 0、提示缺失章节/文件/结构错误 → 只补跑对应章节,再装配。循环直到零遗漏。 同时查看 $WORK/out/site/data/coverage_report.json,它会列出每章原目录标题、生成标题、文件数、质量检查状态和失败原因。
4. 铺前端:python3 $TUTOR/scripts/scaffold_site.py --out "$WORK/out/site" --project "$PROJECT"。
5. 打开:cd "$WORK/out/site" && python3 -m http.server 8080,告诉用户访问 http://localhost:8080(必要时提示强刷 Cmd+Shift+R)。

默认并行策略(subagent / Workflow)

若环境支持 subagent 并行编排,必须优先每章派一个 subagent:每个 subagent 使用同一份章节 prompt,完整读完该章文件,写出 $PARTS/<id>.json。顺序循环只是没有 subagent 能力时的 fallback。

Codex 中若有 subagent/multi-agent 工具可用,触发本 skill 即视为用户授权按章节并行派发;不要因为普通任务默认少用 delegation 而退回顺序执行。每个 subagent 的任务必须自包含,只写自己的 $PARTS/<id>.json,不要修改其它章节产物。

若环境还支持 Workflow JS 运行时(phase/log/parallel/agent/StructuredOutput),可用 gen_workflow.py 生成并行脚本来自动派发这些 subagent:

python3 "$TUTOR/scripts/gen_workflow.py" --chapters "$WORK/chapters.json" \
  --out "$WORK/wf.js" --project "$PROJECT" --blurb "$BLURB" --parts "$PARTS"

再运行生成的 workflow 脚本。补跑时用 --only ch03,ch07。如果 agent 只支持 subagent、不支持该 JS 运行时,不要跑 wf.js;直接按章节清单手动/程序化派发 subagent 即可。

规模与成本

每章一个 agent、完整读完该章文件,几百文件的项目会派几十个 agent、消耗较多 token。开跑前给用户一个量级预估;大仓库优先 --include 聚焦或调大 --max-files。

给其它 agent

任意支持 skills 的 agent 都按"通用执行步骤"运行;支持 subagent 的必须优先并行派发,没有并行编排能力时才顺序逐章生成,其余脚本与数据契约完全一致。