144 lines
8.6 KiB
Markdown
144 lines
8.6 KiB
Markdown
# 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 移植适配*
|