# AGENTS.md — DeepSeek Harness（DSH）工作指引

> 📌 **本文件是 DSH 环境的项目指引**（替代/并存 Claude Code 的 `CLAUDE.md` 与 Codex 的根 `AGENTS.md`）。
> 用户在 DSH（DeepSeek Harness）里处理本仓库时，以此文件为准。数据目录 `.claude/memory/class/` 与 Claude Code **完全共用**，切换工具不迁移数据。

## 项目概述

**穹狼科创 · 课评生成与课堂反馈管理系统**。给编程课老师（橙子）用的 AI 课评系统：
输入课堂情况 → 自动按班级风格生成约 200 字个性化家长信课评 → 自动质检 → 自动归档（个人课评 / 周汇总 / 班级总结 / 汇总网页 / 画像更新）。

覆盖课程：**CSP**（C++信奥）、**AIAGENT**（AI创意编程）、**Kitten**（图形化）、**GESP 暑假集训**、**AIAGENT 小龙虾夏令营**、**穹狼传奇**、**体验课**（新生转化）。

---

## 🚀 快速使用（三句话）

| 用户说 | 触发技能 | 干什么 |
|--------|---------|--------|
| 「写课评」「生成课评」 | `class-feedback-generate` | 交互问答 → 自动生成 → 质检 → 归档（全程自动） |
| 「检查第X课」「检查 X月X日 到 X月X日」 | `class-feedback-check` | 课次/日期双模式检查 + API出勤与本地课评交叉核对 |
| 「质检这份课评」「用课评质检系统检查」 | `class-feedback-qa` | 证据审计 + 100分制评分 + 7硬伤否决 + 家长视角 + 终稿修订 |

技能定义在 `.dsh/skills/<skill>/SKILL.md`，**写课评前必须加载** `class-feedback-generate`，质检自动联动 `class-feedback-qa`。

---

## 🔄 写课评标准工作流（DSH 执行方式）

> DSH 没有 Claude Code 的 `.claude/agents/` subagent 调度机制，4 个阶段由**主智能体按技能指令直接执行**；需要多视角并行时可自选用 `subagent` 工具模拟（如证据审计员 + 质量评审员 + 家长视角分组并行）。

```
┌─────────────┐   ┌─────────────┐   ┌───────────────┐   ┌─────────────┐
│ 准备阶段      │ → │ 生成阶段      │ → │ 质检+修订阶段   │ → │ 保存归档阶段  │
└─────────────┘   └─────────────┘   └───────────────┘   └─────────────┘
```

### 第1阶段 · 准备
1. 用 `ask_user_question` 交互确认：班级 / 课次 / 日期（CSP00/CSP04 问 OJ token；AIAGENT03 问作品文件夹路径）
2. 录音转写 `.docx`（`D:\03-下载` 最新文件）→ **python-docx 提取为 UTF-8 txt 再 Read**（避免乱码），AI 分析"发言人N"对应学生
3. 匹配课程计划提取 5 个知识点（不得编造）：
   - CSP00/CSP04 → `.claude/lesson/CSP/CSP03/课程计划.md`（沿用 CSP 教案）
   - AIAGENT03 → `.claude/lesson/AIAGENT/AIAGENT-03/2026秋季课程计划.md`（2026秋季·班型三：萌宠快速版/秘密聊天室/你画我猜/卡牌对战 22课）
   - 体验课 → `.claude/lesson/体验课/`
4. 逐个读取学生画像 `.claude/memory/class/[班级]/[姓名]/profile.md`
5. **GESP/CSP 必查 OJ 数据**：`python scripts/get_student_oj.py --homework-id <作业ID> --student "<姓名>"`
6. **AIAGENT 班必看作品文件夹**，用中文描述创意/技术点/亮点

### 第2阶段 · 生成
- 读班级风格指南 `.claude/rules/[课程].md` 与模板 `.claude/templates/[课程].md`
- 每人约 200 字家长信：固定开头（5 知识点）+ 课评反馈 + 教师签名（橙子）
- 质量自检：字数 180-350 / 禁用词 / 三要素结构 / Emoji 3-5 个 / 去姓直呼 / 具体化 / 可执行建议 / 纵向对比 / 专业知识点

### 第3阶段 · 质检+修订（自动，无需用户确认）
- 加载 `class-feedback-qa`：证据审计 → 100分制评分 → 7 硬伤一票否决 → 5 家长视角 → 终稿修订
- **三档放行**：≥85 且无硬伤→保存原稿；70-84→保存修订稿；<70 或硬伤→保存修订稿
- 核心原则：事实以证据审计为准；不做横向比较；术语家长能懂（CE/WA/AC 要解释）；老师是最终决策者

### 第4阶段 · 保存归档（自动）
| 产物 | 路径 |
|------|------|
| 个人课评 | `.claude/memory/class/[班级]/[姓名]/feedback/YYYYMMDD_课程编号-课次.md` |
| 周汇总 | `output/课评汇总/202X年第X周课评汇总.md`（**新课评放最前**） |
| 班级总结 | `.claude/memory/class/[班级]/summaries/YYYYMMDD_课程编号-课次_班级反馈.md` |
| 汇总网页 | `output/课评汇总/第X周课评汇总/第X课-课程名称-班级.html`（放入对应周文件夹，登记到该周 `总览.html`；已存在则跳过不覆盖；规范见 `output/课评汇总/README.md`） |
| 画像更新 | 只记录新发现/明显变化，格式 `**YYYY-MM-DD 第N课观察**：` |

---

## 📁 关键路径速查

| 资源 | 路径 |
|------|------|
| 学生画像（必看） | `.claude/memory/class/[班级]/[姓名]/profile.md` |
| 班级规范 | `.claude/memory/class/CLAUDE.md` |
| 风格指南 | `.claude/rules/CSP.md` / `AIAGENT.md` / `KITTEN.md` / `体验课.md` |
| OJ 数据规则 | `.claude/rules/oj_data.md`（CSP/GESP 先看） |
| 课评模板 | `.claude/templates/CSP.md` / `AIAGENT.md` / `KITTEN.md` / `课评汇总网页.html` |
| 教案/课程计划 | `.claude/lesson/`（按课程子目录） |
| 课评质量标准 | `.claude/docs/课评质量标准.md` |
| 质检角色细则 | `.claude/agents/<角色>/agent.md`（DSH 里读取后按标准执行） |
| OJ 作业包 ID | `config/hw_dict.json` |
| OJ 凭据 | `.env`（不入库） |

---

## 🏫 班级目录清单（以 `.claude/memory/class/` 实际为准，2026秋季新学期）

```
AIAGENT03橙子周五1700   AIAGENT03橙子周六1900   AIAGENT03橙子周日0845   AIAGENT03橙子周日1400
CSP00橙子周五1900       CSP04橙子周六0830       CSP04橙子周六1400       CSP01橙子周六1610
体验课/  补课/  代课-黄榆斐/  Kitten02橙子代课/  （特殊目录）
归档/  （历史班级：GESP集训×3、AIAGENT小龙虾×2、穹狼传奇、CSP03周日1030、K4周日1900；停课学生：杨林轩/杨翊弘/林俊宇/谭锦程等）
```

> 学生名单/停课/转班等动态信息：**以 `CLAUDE.md` 最新版本 + 实际目录为准**，写课前先核对。
> 📌 **2026秋季学期起**：AI 编程课程由 AICODE 更名为 **AIAGENT**（编号 AIAGENT03）；原 CSP03 升为 CSP04；原周五1900 K4班转为 CSP00（2课时）。

---

## 📛 命名规范（硬性）

- 课程编号：C++ 班 `CSP`、AI 班 `AIAGENT`、GESP 集训 `GESP01`、K4 班 `K4`；**禁用** `AI`/`C++` 缩写
- 文件名：`YYYYMMDD_课程编号-课次.md`，日期必须与校宝 `teaching_date` 一致
- 请假：`...-课次(请假).md`；未到：`...-课次(未到).md`
- 补课：正常文件名，保存在**补课班级**的 `补课/[姓名]/feedback/` 下

---

## 🔄 与 Claude Code 的差异（重要）

| 项 | Claude Code | DSH（本环境） |
|----|------------|--------------|
| 流水线执行 | `.claude/agents/` 9+ subagent 调度 | 主智能体按技能直接执行，可用 `subagent` 模拟并行 |
| 交互询问 | `AskUserQuestion` | `ask_user_question` |
| 质检 | 9 agent 并行 | 按 `class-feedback-qa` 技能逐项执行 |
| 周汇总路径 | `E:/cc/3笔记/`（旧） | `output/课评汇总/`（仓库内） |
| 录音目录 | `D:\下载` | `D:\03-下载`（技能内约定） |

---

## 🛠️ 常用脚本

| 脚本 | 用途 |
|------|------|
| `python scripts/get_student_oj.py --homework-id <ID> --student "<姓名>"` | 单学生 OJ 做题数据（GESP/CSP 课评必用） |
| `node scripts/check-api-vs-local.js <开始日期> <结束日期>` | API 出勤 vs 本地课评核对（检查技能用） |
| `scripts/split_feedback_v2.py` / `update_feedback_with_oj.py` | 课评拆分 / 批量补 OJ 数据 |
| `scripts/fetch_gesp_*.py` / `update_gesp_oj.py` | GESP OJ 数据拉取与更新 |

---

## ⚠️ 注意事项

1. **docx 乱码**：录音 `.docx` 必须先用 python-docx 提取为 UTF-8 txt，再用 Read 工具读；用完删临时 txt
2. **不编造**：知识点取自教案、学生表现取自录音/作品/OJ 数据，绝不虚构
3. **OJ 必查**：GESP/CSP 课评没有 OJ 数据 = 不完整
4. **AIAGENT 必看作品**：课评必须包含作品创意中文描述
5. **网页不覆盖**：`output/课评汇总/*.html` 已存在则跳过，避免覆盖老师手改内容
6. 本文件与 `.dsh/skills/*/SKILL.md` 若与 `.claude/` 原版冲突，**以技能 SKILL.md 为准**；原版更新后可对照同步

---

*穹狼科创 · ClassFeedback DSH 版指引 · 由 .claude/skills 移植适配*