feat: 统一两端界面并扩展受权限约束的AI助手

This commit is contained in:
LoveChengke committed 2026-11-07 16:27:38 +08:00
1 parent 79a31ebe9d
commit 0b35a58f07
141 files changed
+7999 -2213

No files matched your search

+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@classhelper/shared",
"version": "1.4.3",
"version": "1.4.4",
"private": true,
"description": "ClassHelper - 三端共享的类型、常量与工具函数",
"type": "module",
+54
View File
@@ -0,0 +1,54 @@
export interface AiAttachment {
id: string;
name: string;
size: number;
sha256: string;
}
export interface AiOperation {
action: string;
target?: Record<string, string>;
params?: Record<string, unknown>;
query?: Record<string, unknown>;
attachmentId?: string;
}
export interface AiCapability {
action: string;
label: string;
kind: 'read' | 'write';
dangerous: boolean;
schema: Record<string, unknown>;
sensitiveFields: string[];
}
export interface AiExecutionRequest {
method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
path: string;
query: Record<string, unknown>;
body: Record<string, unknown>;
attachmentId?: string;
sha256?: string;
}
export interface AiPlanStep extends AiOperation {
id: string;
label: string;
status: 'draft' | 'prepared' | 'confirmed' | 'running' | 'succeeded' | 'failed' | 'blocked';
summary: string;
dangerous: boolean;
sensitiveFields: string[];
before?: unknown;
preview?: unknown;
result?: unknown;
error?: string;
request?: AiExecutionRequest;
}
export interface AiConversationRequest {
text: string;
classId?: string;
messages?: { role: 'user' | 'assistant'; content: string }[];
attachments?: AiAttachment[];
}
export interface AiConversationResult {
planId: string | null;
message: string;
steps: AiPlanStep[];
results: { action: string; label: string; data: unknown }[];
}
+84
View File
@@ -0,0 +1,84 @@
/**
* 课表 YAML 导入格式的公共契约。
*
* 这里放「复制给大模型的提示词」与「可导入的示例 YAML」两份文本:
* - Web 导入弹窗直接展示、复制、下载它们;
* - 服务端隔离验收也解析同一份示例,保证提示词描述的格式与实际解析器永远一致。
*
* 字段语义(与服务端 `class-plan-yaml.service.ts` 对应):
* - `version`:固定 1,可省略;
* - `subjects`:科目列表,`simplified_name` 会成为课程简称,`room` 会写进课次地点;
* - `schedules`:课表列表,`enable_day` 1=周一 … 7=周日,`weeks` 取 all/odd/even;
* - 同一天的单周与双周拆成两条 schedules,同一天同一 weeks 只能有一条。
*/
/** 课表 YAML 示例:覆盖每周课表、同一天单周/双周拆分、科目教室。 */
export const CLASS_PLAN_YAML_SAMPLE = `version: 1
subjects:
- name: 语文
simplified_name: 语
teacher: ''
room: ''
- name: 数学
simplified_name: 数
- name: 英语
simplified_name: 英
room: 教学楼 201
schedules:
- name: 周一
enable_day: 1
weeks: all
classes:
- subject: 语文
start_time: '080000'
end_time: '084500'
- subject: 数学
start_time: '08:55:00'
end_time: '09:40:00'
- subject: 英语
start_time: '10:00:00'
end_time: '10:45:00'
- name: 周二 单周
enable_day: 2
weeks: odd
classes:
- subject: 英语
start_time: '08:00:00'
end_time: '08:45:00'
- subject: 数学
start_time: '08:55:00'
end_time: '09:40:00'
- name: 周二 双周
enable_day: 2
weeks: even
classes:
- subject: 语文
start_time: '08:00:00'
end_time: '08:45:00'
- subject: 数学
start_time: '08:55:00'
end_time: '09:40:00'
`;
/** 可直接复制给大模型的提示词(后面追加自己的课表内容一起发送)。 */
export const CLASS_PLAN_YAML_AI_PROMPT = `你是一个课表整理助手。请把我提供的课表整理成 ClassHelper「课表档案」可导入的 YAML。只输出 YAML 本身,不要解释,不要使用 Markdown 代码围栏,不要写注释。
格式要求(必须严格遵守):
1. 顶层只有 version、subjects、schedules 三个字段,其中 version 固定为 1。
2. subjects 是科目列表,每项字段:
- name:科目全称,必填,例如 语文;
- simplified_name:可选,课程简称,建议 1~2 个字;
- teacher:可选,教师名,仅作备注、不参与课程授权,没有就写空字符串;
- room:可选,默认教室,会作为每节课的上课地点导入。
3. schedules 是课表列表,每项字段:
- name:课表名称,例如 周一、周二 单周、周五 双周;
- enable_day:必填,1=周一、2=周二、3=周三、4=周四、5=周五、6=周六、7=周日;
- weeks:选填,all=每周(默认)、odd=单周、even=双周;同一天既有单周又有双周时拆成两条;
- classes:必填,按开始时间从早到晚排列,每项:
- subject:科目名,要与 subjects 里的 name 对应;空课写空字符串 '';
- start_time、end_time:24 小时制六位字符串 HHMMSS,例如 '080000';也支持 HH:mm / HH:mm:ss。秒必须为 00,结束必须晚于开始。
4. 同一天、同一 weeks 只能有一条 schedules;没有课的星期不要写。
5. 不需要把课间、早读等没有科目的时段都写出来;需要占位时空课写 '' 即可。
示例(仅示意格式,请替换成我的真实课表):
${CLASS_PLAN_YAML_SAMPLE}`;
+1 -1
View File
@@ -600,7 +600,7 @@ export const STORAGE_KEYS = {
/**
* 新手引导「已看过」标记(Web 管理端 localStorage)。
* 值为引导版本号:改版引导内容后版本 +1,看过旧版的老用户会再收到一次新版引导。
* EXE 客户端不用这个键 —— 它的引导状态在主进程配置(`onboardingDone`)里。
* EXE 客户端的引导版本保存在主进程配置 `onboardingVersion`。
*/
onboarding: 'classhelper.onboarding',
} as const;
+2
View File
@@ -7,7 +7,9 @@ export * from './motion.js';
export * from './permissions.js';
export * from './utils.js';
export * from './class-plan.js';
export * from './class-plan-yaml.js';
export * from './island-layout.js';
export type * from './types.js';
export * from './courseware.js';
export * from './lifecycle.js';
export type * from './ai.js';
+33 -10
View File
@@ -1,3 +1,4 @@
import type { AiConversationRequest } from './ai.js';
import type { CoursewareTransfer } from './courseware.js';
import type {
ClientUpdateProgressDto,
@@ -641,6 +642,33 @@ export interface ClassPlanImportResultDto {
weekEnd: number;
}
/* ------------------------------------------------------------------ 课表 YAML 导入 */
/** YAML 课表预览里的单节课:与 ClassIsland JSON 预览一致,额外带上课地点。 */
export interface ClassPlanYamlEntryDto extends ClassPlanEntryDto {
/** 由科目 room 带入的课次地点(可为空) */
location?: string;
}
/**
* 课表 YAML 预览结果。
*
* 字段故意与 `ClassPlanPreviewDto` 对齐,Web 导入弹窗可以复用同一套表格与错误展示;
* `format` 用于页面提示当前识别到的是 YAML 而不是 ClassIsland JSON。
*/
export interface ClassPlanYamlPreviewDto extends Omit<ClassPlanPreviewDto, 'entries'> {
format: 'yaml';
entries: ClassPlanYamlEntryDto[];
/** 归一化后要写入的课表数量(同一天的单周/双周会各算一张) */
planCount: number;
}
/** 课表 YAML 导入结果:在通用导入结果上补充解析阶段的提示。 */
export interface ClassPlanYamlImportResultDto extends ClassPlanImportResultDto {
/** YAML 解析与完整档案导入过程中的提示(不阻断导入) */
warnings: string[];
}
/* ------------------------------------------------------------------ 作业 */
export interface HomeworkDto {
@@ -1802,16 +1830,11 @@ export interface UpdateAiSettingsRequest {
systemPromptExtra?: string;
}
/** 助手能执行的动作(都是既有发布入口的封装,绝不直接写库) */
/** 旧响应的兼容动作;完整能力目录使用 AiCapability。 */
export type AiActionKind = 'create_homework' | 'create_notification' | 'call_student' | 'unknown';
/** `POST /api/ai/interpret`:只解析、不落库;确认后由前端调既有端点 */
export interface AiInterpretRequest {
/** 老师原话,例如「给高一二班布置作业,把卷子写完」 */
text: string;
/** 有上下文班级时一并给出(助手据此缩小候选) */
classId?: string;
}
/** AI 对话请求;写操作仅生成待确认计划。 */
export type AiInterpretRequest = AiConversationRequest;
/** 助手解析出的一次动作(params 用与手动入口**同一份 zod 校验**后再返回) */
export interface AiInterpretResult {
@@ -1828,9 +1851,9 @@ export interface AiInterpretResult {
};
/** 模型自评置信度 0~1(低于 0.5 时界面提示"请仔细核对") */
confidence: number;
/** 一律为 true:助手的结果必须由老师确认后才落库 */
/** 写入计划需要确认,纯查询为 false。 */
needConfirm: boolean;
/** 模型原始回复(仅在开发者模式下回传,便于排查格式问题) */
/** 兼容字段;服务端不回传模型原文。 */
rawReply?: string | null;
}