achievement-qztc

课程目标达成情况分析表生成工具 v5.3（仅供QZTC内部使用）。Generator+Reviewer双模式，支持Pipeline一键生成+审查。权重和目标配置均从模板动态读取。

Security Scan

The skill appears to implement the described generator/reviewer workflow and does not request external credentials or network access, but there are internal inconsistencies (hardcoded template path vs. config loader) and brittle assumptions that merit caution before use.

Purpose & Capability

The code (generator + reviewer) matches the stated purpose of producing and checking course-achievement documents. However, there is an inconsistent template configuration: achievement_generator.py uses a hardcoded TEMPLATE_DIR ('/Users/qztcm09/...'), while config_loader.py provides a config.env mechanism and a different default (~/.openclaw/workspace). This discrepancy is unexpected and suggests sloppy configuration handling rather than malicious intent.

Instruction Scope

SKILL.md instructions and CLI usage correspond to the included scripts. The runtime instructions only describe reading local Excel and template files and writing/inspecting .docx output; the code follows that scope and does not attempt network calls or reading unrelated system secrets.

Install Mechanism

No install spec (instruction-only) and the package uses only local Python code and standard/third-party libraries (pandas, python-docx, lxml). No remote downloads or installers are included.

Credentials

The skill requests no environment variables or credentials, which is appropriate. But config_loader will create a local config.env file in the skill directory if it does not exist and then exit, and the generator uses a hardcoded absolute TEMPLATE_DIR path. These behaviors could cause accidental filesystem writes or unexpected template selection; they are disproportionate to the documented simple CLI expectation.

Persistence & Privilege

The skill is not always-enabled and does not request elevated privileges. It writes a config.env in its own directory when missing (config persistence limited to the skill). It does not modify other skills or system-wide agent settings.

What to consider before installing

What to consider before installing/using this skill: - Functionality and privacy: This skill reads Excel files with student grades and writes .docx reports. If you will process real student data, run it locally on a trusted machine and ensure you comply with privacy rules. - Configuration mismatch: The generator has TEMPLATE_DIR hardcoded to '/Users/qztcm09/Documents/QZTC/教学文档模版', but config_loader expects a config.env to set TEMPLATE_DIR (defaulting to ~/.openclaw/workspace). Before running, either edit the script to use config_loader.get_template_dir(...) or create a config.env with TEMPLATE_DIR pointing to your templates. The current mismatch may cause it to fail to find templates or use the wrong one. - config.env creation: If config.env is missing, config_loader.py will create one in the skill directory and then exit (it instructs you to edit the file and re-run). Expect that file to appear; review its contents and update TEMPLATE_DIR and OUTPUT_DIR as needed. - Brittle assumptions: The code assumes specific table indices (e.g., tables[7], particular row numbers) and a large detail table (rows >= 50). If your templates/docx structure differs, the generator/reviewer may fail or give false negatives. Inspect your template to ensure it matches the expected structure. - No network / no secrets requested: There are no network endpoints or credential/environment-variable requests in the code, which reduces exfiltration risk. Still, review the code if you have high security requirements. - Recommended actions: (1) Inspect and, if necessary, correct TEMPLATE_DIR usage so the generator uses config_loader.get_template_dir(). (2) Test on sample/non-sensitive data first. (3) Confirm templates match the assumed structure (tables and rows). (4) Run in an isolated environment if you are unsure. If you want a higher-confidence assessment, provide logs of a test run, the actual template files it will use, or confirm whether the hardcoded TEMPLATE_DIR is intentional. Those details would clarify whether the mismatch is benign (leftover dev path) or an operational problem.

课程目标达成情况分析表生成工具 v5.3

🎯 设计模式: Generator + Reviewer + Pipeline 📁 代码文件: achievement_generator.py 🔍 审查脚本: scripts/review_document.py 📖 公式参考: references/grading-formula.md

---

🚀 快速开始

Pipeline 一键执行（推荐）

# 生成 + 审查（自动执行）
python3 achievement_generator.py --pipeline "C#程序设计-23级软工.xls"

# 或分步执行
python3 achievement_generator.py "C#程序设计-23级软工.xls"
python3 scripts/review_document.py "C#程序设计-23级软工-课程目标达成情况分析表.docx"

单独使用

# 生成文档
python3 achievement_generator.py <Excel文件>

# 审查文档
python3 scripts/review_document.py <输出文件.docx>

---

📁 目录结构

achievement-qztc/
├── SKILL.md                      # 本文件
├── achievement_generator.py       # 主生成器（Generator模式）
├── scripts/
│   └── review_document.py        # 质量审查（Reviewer模式）v2.0
└── references/
    └── grading-formula.md        # 评分公式（Tool Wrapper）

---

🔄 Pipeline 工作流

┌─────────────────────────────────────────────────────────────┐
│  STEP 1: 生成 (Generator)                                  │
│  python3 achievement_generator.py <Excel>                    │
│       ↓                                                    │
│  ✅ CHECKPOINT 1: 文件生成成功？                             │
│       ↓                                                    │
│  STEP 2: 审查 (Reviewer)                                   │
│  python3 scripts/review_document.py <输出.docx>             │
│       ↓                                                    │
│  ✅ CHECKPOINT 2: 所有检查项通过？                          │
│       ↓                                                     │
│  STEP 3: 交付                                              │
└─────────────────────────────────────────────────────────────┘

---

📊 表格与图表

组件	说明	数据源
表7	汇总表	各目标平均达成度 + 实际得分
表8	明细表	每学生得分/达成度 + 平均行
Chart1-4	散点图	每学生各目标达成度
Chart5	柱状图	各目标平均达成度百分比
分析段落	文本	avg/max/min/pct_80/pct_60

---

🔧 审查检查项（Reviewer模式）

检查项	说明
✅ text_replacement	所有占位符已替换
✅ summary_table	汇总表数据完整
✅ detail_table	明细表正确
✅ charts	图表数据合理
✅ analysis_paragraphs	分析段落正常

---

📐 评分公式

# 权重和目标配置均从模板表7动态读取（不再硬编码）
# read_weights_and_config_from_template(doc) →
#   weights: 表7 Row 2 的 col3/col4/col5
#   target_config: 表7 各目标理论满分行 (Row 4/7/10/13) 的 col3/col4/col5
#   total = col3×权重.col3 + col4×权重.col4 + col5×权重.col5

# 达成度 = 目标得分 / 理论满分（total）

---

⚠️ 重要笔记

表8平均行结构

序号 | 学号 | 姓名 | 目标1得分 | 目标1达成值 | 目标2得分 | 目标2达成值 | ...
平均 | 平均 | 平均 | 得分平均  | 达成度平均  | 得分平均  | 达成度平均  | ...

图表数据

• Chart1-4: 每学生达成度（0-1范围）
• Chart5: 各目标平均达成度百分比（0-100范围）

---

📦 依赖

import pandas as pd
from docx import Document
import zipfile
from lxml import etree

---

🔄 更新日志

版本	日期	内容
v5.0	2026-03-28	Pipeline一键执行 + Reviewer v2.0 + references/
v4.4	2026-03-28	修复表8平均行、Chart5、Charts1-4数据
v4.3	2026-03-28	表7实际得分 + chart5
v4.0	2026-03-27	动态表格查找、CLI

---

v5.2 - 2026-04-09 - 权重和目标配置从模板表7动态读取 v5.0 - 2026-03-28 - Generator + Reviewer + Pipeline