Metadata-Version: 2.4
Name: edukan
Version: 0.6.0
Summary: 終端機優先的 kan.bn 教育工具：學生用 CLI 更新進度並反思，教授監控全班思考參與度。
Keywords: kanban,kan.bn,education,cli,reflection,assessment
Author: fred1357944
Author-email: fred1357944 <fred1357944@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: anthropic>=0.105.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pydantic-settings>=2.14.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: streamlit>=1.58.0
Requires-Dist: typer>=0.26.4
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# EduKan

終端機優先的 [kan.bn](https://kan.bn) 教育工具。學生用 CLI 更新進度並**留下思考痕跡**；教授監控全班的**思考參與度**並做出有證據的形成性回饋與評分。

> 核心理念：學生在卡片上寫的 comment 與描述修改，組成一份「思考語料」——它**既是學生成長的學習產物，也是教授打分的證據**。「把卡片拖到 Done」不等於「有思考」。

## 設計：兩層分開

- **Tier 1 參與度（雷達，不算分）**：最近活躍、思考活躍天數、進度燈號 🟢🟡🟠🔴⚪，只用來路由教授的注意力。
- **Tier 2 思考深度（打分依據）**：教授（或 Claude 輔助）親讀思考語料，依公開方向的 rubric 評估。

## 安裝

```bash
uv tool install edukan      # 推薦（或 pipx install edukan / pip install edukan）
```

## 學生快速上手

```bash
edukan login                       # 貼上 kan.bn API key（kan_xxx）
edukan use-board <你的 board id>   # 設定一次

edukan card update <cid> --list Complete   # 移到完成欄 → 邀請你寫一句反思
edukan comment add <cid> "我發現原本的假設在 X 不成立，所以改成…"
edukan me                          # 私人鏡子：只看自己的思考軌跡（無排名/分數/他人）
```

詳見 [`docs/student-sop.md`](docs/student-sop.md)。

## 教授快速上手

```bash
edukan login
edukan admin summary --cohort 2026-spring --roster roster.yaml   # 全班 triage 雷達
edukan admin student 王小明 --cohort 2026-spring --roster roster.yaml   # 讀某生思考語料
```

`roster.yaml`（班級名冊，支援 cohort/學期、封存）：

```yaml
workspace: <workspacePublicId>
cohorts:
  2026-spring:
    done_lists: ["Complete", "Done"]
    students:
      - name: 王小明
        email: xiaoming@example.com
        board: <boardPublicId>      # 在 kan.bn 網頁手動建好後填入
```

## AI 計費與訂閱界線（重要）

EduKan 的 AI 輔助有兩條路：

- `--assist claude-code`：外呼**你本機已登入的 `claude` CLI**（`claude -p`），跑在你的 Claude Code
  訂閱底下、零 API 費。**界線**：EduKan 只是 `subprocess` 呼叫你真實的 `claude` 二進位，
  **不代理/不擷取你的 OAuth token，也不在 prompt 冒充任何第三方 app**。這是合規的本機自用方式。
- `--assist claude`：用 `ANTHROPIC_API_KEY` 打 Anthropic API（按 token 計費）。**託管/自動化/多老師**
  服務請走這條（伺服器端不能、也不應借任何人的個人訂閱）。

> 一句話：claude-code 給「教授本機自用」；API key 給「託管或自動化」。

## 過程證據（D2/D7，反監控設計）

`edukan admin timeline <學生>` 把每張卡的活動時間軸（建立/留言/描述修改/移動）與反思並列，
並給一個**非評斷的類別**（與時間軸相符／單次工作階段／集中一次寫成）。這是**對話引子，不是指控、
不自動扣分、不做 AI 文字偵測**——AI 代寫的反思難以對上多天多卡的真實工作節奏，但不一致也可能有
無辜原因（線下工作、先想後做），所以一律由教授判讀、用來開啟對話。

## 開發

```bash
uv sync
uv run pytest                 # 單元 + 契約測試
EDUKAN_LIVE=1 uv run pytest tests/test_smoke_live.py   # 對真實 kan.bn 的唯讀煙霧測試
```

設計文件見 `docs/plans/`。授權：MIT。
