架构设计

AutoPku 采用"主入口 + 模块化 Sub-skills"的分层架构，通过运行时抽象层屏蔽不同 AI 平台的差异，实现一套代码多平台运行。

整体架构

AutoPku/ ├── skill.md # 主入口：意图识别 + 任务路由 ├── sub-skills/ │ ├── runtime/ # AI 环境抽象层 │ │ ├── _detect.md │ │ ├── create-agent.md │ │ ├── claude-team.md │ │ ├── codex-subagent.md │ │ └── kimi-team.md │ ├── tools/ # 可复用工具 │ │ ├── pku3b-setup.md │ │ ├── data-parser.md │ │ ├── pdf-reader.md │ │ └── agent-helpers.md │ └── tasks/ # 任务执行流 │ ├── sync-notices.md │ ├── do-homework.md │ └── write-notes.md └── docs/ # 文档站点

执行架构

1. 环境检测（_detect.md）

系统启动时，通过读取环境变量自动判断当前所在的 AI 运行时：

python 
if os.environ.get("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"):
    RUNTIME = "claude"
elif os.environ.get("CODEX") == "1":
    RUNTIME = "codex"
elif os.environ.get("KIMI_CODE_CLI") == "1" or shutil.which("kimi"):
    RUNTIME = "kimi"
else:
    RUNTIME = "serial"

检测结果被缓存，后续所有 Agent 创建操作均依据 RUNTIME 的值选择对应语法。

2. 任务路由（skill.md）

主入口 skill.md 负责接收用户的自然语言输入，通过关键词和意图匹配将请求路由到对应的 task sub-skill：

  • "看看有什么新通知" → tasks/sync-notices.md
  • "帮我把作业做了" → tasks/do-homework.md
  • "整理一下这节课的笔记" → tasks/write-notes.md

3. Agent 创建（create-agent.md）

runtime/create-agent.md 提供统一的跨平台 Agent 创建接口。不同运行时的底层语法差异被封装在这一层，task 开发者只需调用统一接口即可创建 Coordinator、Parser、Solver 等角色。

Agent Team 单课程结构

对于每门课程的任务，系统会动态构建一个 Agent Team，各角色分工如下：

Course Agent Team/ ├── coordinator # 调度中枢，分配任务、汇总结果 ├── pdf_parser # 解析 PDF 题目，提取文本与结构 ├── solver # 解答题目，生成答案内容 ├── writer # 将答案整理为规范 Markdown ├── renderer # Markdown → PDF 渲染（含 LaTeX） └── portal_submitter # 提交至教学网，等待用户最终确认

数据流图

以"完成作业"任务为例，数据在各 Agent 间的流转路径如下：

  1. 用户输入：自然语言描述需求（如"做完高数作业"）
  2. 主入口路由：skill.md 识别意图，触发 tasks/do-homework.md
  3. 环境检测：runtime/_detect.md 确定当前平台语法
  4. 获取作业：通过 pku3b CLI 下载作业 PDF 附件
  5. PDF 解析：pdf_parser 提取题目文本与结构
  6. 题目解答：solver 基于解析内容生成答案
  7. 文档整理：writer 将答案组织为 Markdown 格式
  8. PDF 渲染：renderer 将 Markdown 转换为 PDF 文件
  9. 用户确认：展示答案预览，等待用户确认或修改
  10. 作业提交：portal_submitter 将最终文件提交至教学网
⚠️ 安全规则

以下行为在 AutoPku 架构中被严格禁止：

  • 任何涉及密码的输入或传输均不得回显或记录到日志
  • 作业提交操作前必须展示预览并等待用户显式确认（Y/n）
  • Agent 不得在未授权情况下修改或删除用户本地文件
  • 教学网敏感操作（提交、退课等）必须保留人工审核节点