team-week

# /team-week ## 用法 ``` /team-week week_XX ``` ## 目标 **直接执行完整的 6 阶段流水线**，把 week_XX 从零产出为完整章包，并通过 release 校验： ```bash python3 scripts/validate_week.py --week week_XX --mode release ``` ## 全局约束（贯穿所有阶段） - 交付遵循 `CLAUDE.md` + `shared/style_guide.md` - **所有写正文的 subagent 必须先读 `shared/writing_exemplars.md` + `shared/characters.yml`** - **ANCHORS.yml 由阶段 6（收敛阶段）统一管理**：其他阶段如有 anchor 建议，在输出中标注即可，不直接写 ANCHORS.yml - **一致性处理由 Lead agent 直接执行**（不再调用独立 subagent）：阶段 6b 的术语同步、格式检查、ANCHORS 整理由 Lead agent 直接完成 ### 写作质量红线（四维评分体系） - student-qa 四维评分总分必须 >= 18/20 - 叙事流畅度 >= 3 / 趣味性 >= 3 / 知识覆盖 >= 3 / 认知负荷 >= 3 - 任一维度 <= 2 = 阻塞项 - 禁止每节都用相同的子标题模式 - 每章必须有贯穿案例（渐进式小项目）+ PyHelper 超级线推进 - 循环角色（小北/阿码/老潘）每章至少出场 2 次 - 新概念数不超预算，回顾桥数量达标 - 禁止连续 6+ 条 bullet list；小结不能全部用 bullet list - **AI 小专栏必须 2 个，分别在前段和中段**（禁止全堆章末）；Lead agent 在 Stage 2.5 预先搜索素材写入 `.research_cache.md`，prose-polisher 优先读取缓存，不足时用自身的 **WebSearch** 补充搜索。**绝对禁止编造参考链接**——搜索失败时写 `<!-- TODO -->` 占位 - **章首导入必须包含引言格言 + 时代脉搏段落**（详见 `shared/style_guide.md`） - **所有写作元数据必须用 HTML 注释包裹**，不能出现在渲染正文中 - **写作前必须使用 Context7 MCP 查证本章技术点的当前最佳实践** --- ## 流水线阶段（严格按顺序执行） ``` 阶段 0（日期校准） → 阶段 1（规划） → 阶段 2（写作） → 阶段 2.5（联网研究） → 阶段 3（润色） → 阶段 4（并行产出） → 阶段 5（三维度QA） → 阶段 6（收敛） ``` ### 阶段 0：日期校准（流水线启动时立即执行） 生成 `shared/current_date.txt`，供后续所有 agent 读取当前日期： ```bash date '+%Y-%m-%d' > shared/current_date.txt echo "当前日期已写入 shared/current_date.txt: $(cat shared/current_date.txt)" ``` **为什么需要这一步**：时代脉搏、AI 小专栏、参考链接的访问日期都需要使用当前年份。如果不显式注入日期，agent 可能使用训练数据中的旧年份。 **校验**：确认 `shared/current_date.txt` 存在且内容为当天日期。 --- ### 阶段 1：规划（前置：阶段 0 完成） 调用 subagent `syllabus-planner`： - 产出章节结构（小节标题 + 每节学习目标 + Bloom 层次） - 设计本章贯穿案例（渐进式小项目） - 规划 2 个 AI 小专栏的位置和主题（第 1 个在前段，第 2 个在中段；含建议搜索词） - 做认知负荷检查：新概念数在预算内，回顾桥设计达标 - 规划 PyHelper 超级线推进 - 规划循环角色出场位置 - **规划章首导入**：选择引言格言、草拟时代脉搏段落方向 - 产出写入 `chapters/week_XX/CHAPTER.md`（大纲阶段） - **所有规划元数据必须用 `<!-- ... -->` HTML 注释包裹**（Bloom 标注、概念预算表、AI 专栏规划、角色出场规划、章节结构骨架等，不能渲染为正文） **校验**：无需校验（规划阶段，ASSIGNMENT 等文件不存在是正常的） ### 阶段 1.5：Context7 技术查证（前置：阶段 1 完成） 在写正文之前，使用 **Context7 MCP** 查证本章涉及的 Python 官方文档和 API 最佳实践： 1. 从阶段 1 的规划中提取本章涉及的 Python 特性、标准库模块、第三方库 2. 调用 `resolve-library-id` 定位相关库（如 `python`、`pytest`、`argparse` 等） 3. 调用 `query-docs` 查询具体的最佳实践和 API 用法 4. 将查证结果作为上下文传递给阶段 2 的 chapter-writer **搜索工具分工说明**： - **Context7**：仅用于查证 Python/库的官方文档 API 用法和最佳实践 - **Exa Code Context** (`mcp__exa__get_code_context_exa`)：用于搜索真实项目中的代码示例和社区实践 - 两者互补：Context7 提供官方标准，Exa 提供社区真实用法 **校验**：无需校验 ### 阶段 2：写作（前置：阶段 1.5 完成） 调用 subagent `chapter-writer`： - **必须先读 `shared/writing_exemplars.md` + `shared/characters.yml`** - **必须写章首导入**：在章标题之后、学习目标之前，写入引言格言 + 时代脉搏段落（200-300 字）。详见 `shared/style_guide.md` 的"章首导入"章节 - **必须基于阶段 1.5 的 Context7 查证结果**确保代码示例使用当前 Python 最佳实践 - 以贯穿案例为主线，用"场景 → 困惑 → 解法 → 深化"的叙事弧线写每一节 - 使用循环角色增强代入感，每章至少 2 次出场 - 写回顾桥：在新场景中自然引用前几周概念 - 写 PyHelper 进度小节 - 严禁所有节使用相同子标题模式；严禁 bullet list 堆砌做小结 - **所有写作元数据必须用 `<!-- ... -->` 注释包裹**，不能出现在渲染正文中 **校验**： ```bash python3 scripts/validate_week.py --week week_XX --mode drafting ``` ### 阶段 2.5：联网研究收集（前置：阶段 2 完成，Lead agent 亲自执行） **由 Lead agent 直接执行**（不委派给 subagent），因为 Lead 拥有全部搜索工具。 目的：为阶段 3 的 prose-polisher 提供真实的搜索数据和参考链接，避免 AI 小专栏使用 TODO 占位。 1. **读取阶段 1 的 AI 小专栏规划**：从 CHAPTER.md 的 HTML 注释中提取 2 个侧栏的主题和建议搜索词 2. **读取 `shared/current_date.txt`** 获取当前日期，搜索关键词中包含当前年份 3. **执行搜索**（每个侧栏 2-3 次搜索）： ``` # 优先级 1: 内置 WebSearch（最可靠，无外部依赖） WebSearch("GitHub Copilot adoption statistics 2026") WebSearch("Python popularity TIOBE index 2026") # 优先级 2: Exa MCP（AI 增强搜索，适合深度研究） mcp__exa__web_search_exa({ "query": "GitHub Copilot adoption statistics 2026", "numResults": 5, "type": "auto" }) mcp__exa__company_research_exa({ "companyName": "OpenAI", "numResults": 3 }) # 优先级 3: perplexity MCP（如可用） mcp__perplexity__perplexity_search({ "query": "vibe coding trend AI programming 2026", "recency": "year", "response_format": "json" }) ``` 4. **收集时代脉搏素材**：搜索与本章主题相关的最新 AI/技术事件 5. **将搜索结果写入缓存文件** `chapters/week_XX/.research_cache.md`： ```markdown # Week XX 研究缓存 生成日期：YYYY-MM-DD ## 时代脉搏素材 ### 搜索词: "..." - 事实: ... (来源: https://真实URL) ## AI 小专栏 #1: {主题} ### 搜索词: "..." - 数据点: ... (来源: https://真实URL) - 引用: "..." (来源: https://真实URL) ## AI 小专栏 #2: {主题} ### 搜索词: "..." - 数据点: ... (来源: https://真实URL) ``` **校验**：确认 `.research_cache.md` 存在且至少包含 2 个侧栏的搜索数据。 --- ### 阶段 3：润色（前置：阶段 2.5 完成） 调用 subagent `prose-polisher`： - **必须先读 `shared/writing_exemplars.md` + `shared/characters.yml`** - 执行诊断清单 + 趣味性诊断清单，判断改写级别 - 检查角色一致性（对照 `shared/characters.yml`） - 可做结构性重组 - **必须插入 2 个 AI 时代小专栏**（按阶段 1 规划的位置和主题）： - **优先读取 `chapters/week_XX/.research_cache.md`** 中的搜索数据和参考链接 - 如果缓存数据不足，**可以补充搜索**（WebSearch/Exa MCP），并将新结果**追加写入缓存文件** - 用 **WebFetch** 验证关键 URL 是否可访问 - **绝对禁止编造 URL**——搜索失败时才写 `<!-- TODO -->` 占位 **校验**： ```bash python3 scripts/validate_week.py --week week_XX --mode drafting ``` ### 阶段 4：并行产出（前置：阶段 3 完成，以下三个可并行） 同时调用以下 3 个 subagent（**可以并行**）： 1. **`example-engineer`**：产出 `examples/` + PyHelper 示例代码 + 讲解段落 2. **`test-designer`**：产出 `tests/` pytest 用例矩阵 3. **`exercise-factory`**：产出 `ASSIGNMENT.md` + `RUBRIC.md` + AI 协作练习 **校验**（三个全部完成后执行）： ```bash python3 scripts/validate_week.py --week week_XX --mode idle ``` ### 阶段 5：三维度 QA（前置：阶段 4 全部完成） 执行**三维度质量审查**，确保章包在发布前通过所有检查。 #### 5a. 并行审读（同时执行） **调用 `consistency-editor`**： - 对齐 `shared/style_guide.md` - 同步 `TERMS.yml` -> `shared/glossary.yml` - 检查循环角色使用一致性（对照 `shared/characters.yml`） - 修复 `ANCHORS.yml` 问题 - 运行 `validate_week.py --mode idle` **调用 `technical-reviewer`**（与 consistency-editor 并行）： - 审读 `CHAPTER.md`：概念定义准确性、代码示例正确性 - 审读 `examples/`：Python 代码规范（PEP 8）、边界情况处理 - 审读 `ASSIGNMENT.md` + `RUBRIC.md`：题意清晰度、评分覆盖 - 审读 `starter_code/solution.py`：答案正确性 - 输出问题清单（按 S1-S4 严重级别分类） #### 5b. 学生视角 QA **调用 `student-qa`**： - **只读审读**，返回四维评分 + 问题清单（通过 tool result 返回，不写文件） - 四维评分：叙事流畅度 / 趣味性 / 知识覆盖 / 认知负荷（各 1-5 分） - 总分 >= 18/20 才能通过 **重要**：student-qa 是只读角色（tools: [Read, Grep, Glob]，无 Write 权限），**不要让它写 QA_REPORT.md**。它应该通过返回消息输出评分和清单。 **校验**：无（QA 是只读角色） ### 阶段 6：收敛（前置：阶段 5 完成，序列执行） #### 6a. 修订回路 根据三维度 QA 结果执行修订： | 问题类型 | 处理方式 | 回传给谁 | |---------|---------|---------| | **S1 致命问题** | 必须修复 | `error-fixer` 或相关 subagent | | **S2 重要问题** | 必须修复 | `prose-polisher` | | **S3 一般问题** | 必须修复 | `prose-polisher` | | **S4 润色问题** | 必须修复 | `prose-polisher` | | **四维总分 < 18** | 结构性重写 | `chapter-writer` | | **四维总分 >= 18** | 轻量修订 | `prose-polisher` | **修订规则**： - **S1-S4 问题必须全部清零**才能 release - 无论评分高低，每轮 QA 后都需根据反馈进行一轮修订 - **硬性上限：最多迭代 3 轮**。如果 3 轮后仍有未清零问题或总分 < 18： 1. 在 QA_REPORT.md 记录当前状态和未解决问题 2. 标注 `<!-- 需人工介入 -->` 3. 继续推进到 6b（不再回传修订） #### 6b. 一致性处理 + 落盘 QA_REPORT + Release 校验 **一致性处理（由 Lead agent 直接执行）**： 1. **术语同步**：检查 `TERMS.yml` → `shared/glossary.yml`，如有缺失则同步 2. **ANCHORS.yml 整理**：确保锚点 ID 周内唯一，claim/evidence/verification 齐全 3. **角色一致性**：快速检查循环角色使用是否符合 `shared/characters.yml` 人设 4. **格式统一**：检查标题层级、代码块语言标签、列表格式等 **落盘 QA_REPORT（由 Lead agent 直接写入）**： ```markdown # QA Report: week_XX ## 总体状态 - [ ] 一致性检查通过 - [ ] 技术审读通过（S1-S4 问题已清零） - [ ] 学生视角评分 >= 18/20 ## 四维评分 | 维度 | 分数 | 说明 | |------|------|------| | 叙事流畅度 | X/5 | ... | | 趣味性 | X/5 | ... | | 知识覆盖 | X/5 | ... | | 认知负荷 | X/5 | ... | | **总分** | **X/20** | | ## 技术审读问题 ### S1 致命问题（必须修复） - [x] {已修复的问题} ### S2 重要问题（强烈建议修复） - [x] {已修复的问题} ## 一致性问题 - [x] {已修复的问题} ## 学生视角阻塞项 - [x] {已修复的问题} ## 建议项 - [ ] {可选改进建议} ``` **注意**：QA_REPORT.md 是在阶段 6b 由 Lead agent 写入的，不是在阶段 5 由各 QA subagent 写入的。 - 调用 subagent `error-fixer`（如果校验有报错）：逐条修复再验证 - 最终 release 校验： ```bash python3 scripts/validate_week.py --week week_XX --mode release ``` --- ## 校验模式速查 | 阶段 | 校验模式 | 说明 | |------|---------|------| | 阶段 1（规划） | 无 | ASSIGNMENT 等文件不存在是正常的 | | 阶段 2-3（写作/润色） | `--mode drafting` | 只检查 CHAPTER.md + TERMS.yml（如果存在）| | 阶段 4（产出） | `--mode idle` | 所有文件检查，无 pytest | | 阶段 5（QA） | 无 | QA 是只读角色 | | 阶段 6（收敛） | `--mode release` | 完整发布级校验（含 pytest + pedagogical 检查）| ## 收敛规则 - **S1-S4 问题必须全部清零**才能 release - **四维评分总分必须 >= 18/20** 才能 release（或 3 轮修订后人工豁免） - QA_REPORT 的"阻塞项"必须清零（不允许 `- [ ]`）才能 release - 不要为了"写完"牺牲可运行/可验证：tests/anchors/terms 要能对上