taojianmin
a3b4092a30
新增：
- scripts/service/platform_collector.py：Playwright RPA（持久化 browser profile 复用登录态），抓合同表（姓名/单位/到期日/剩余天数/预警/建议），逐行点"续聘材料包"按钮下载 PDF/Word 到 data/materials/
- scripts/service/material_parser.py：PDF/Word 文本提取（pypdf → pdf2image + pytesseract OCR 扫描件兜底；python-docx 抽 docx；antiword 兜底 .doc）
- scripts/service/llm_decision.py：AI 决策统一入口（优先调宿主 jiangchang_skill_core.llm_manager.call_llm_json；本地降级到规则版；输出 decision_source ∈ {llm, rules, rules_no_materials}）
- scripts/db/migrations.py：idempotent ALTER/CREATE，建 materials_content 表 + renewal_tasks 加 decision_source / materials_summary 列
修改：
- scripts/db/connection.py：init_db() 自动调 apply_all() 应用 v1.1.1 迁移
- scripts/db/repository.py：加 insert_material / list_materials_for_contract / list_pending_materials / summarize_materials / get_task_full
- scripts/service/task_generator.py：AI 决策统一改为调 llm_decision.decide_suggestion(materials_summary=...)；reason 文案加「已结合材料包（X 份文件，Y 字 / 待解析）综合判断：...」
- scripts/service/html_renderer.py：ctx 加 DECISION_SOURCE（LLM 推理 / 本地规则 / 本地规则（无材料））+ MATERIALS_COUNT
- scripts/templates/task.html.j2：footer 加 "AI 建议来源：{{DECISION_SOURCE}} · 已审阅材料 {{MATERIALS_COUNT}} 份"
- scripts/cli/app.py：新增 2 个 CLI（collect-from-platform / parse-materials）；现有 9 个不动
- requirements.txt：playwright / pypdf / python-docx / pdf2image / pytesseract / Pillow
- .env.example：SMARTCAMPUS_BASE_URL / SMARTCAMPUS_PROFILE_DIR / MATERIALS_DOWNLOAD_DIR / OCR_LANG / LLM_MODEL_NAME / LLM_API_BASE_URL / LLM_API_TOKEN
- SKILL.md：version 1.1.0 → 1.1.1；用户意图路由表加 2 行；新增「数据来源」段（三层来源 + AI 决策透明化）
- README.md：使用前要准备 → 加 playwright install chromium 步骤
- CHANGELOG.md：v1.1.1 条目
- scripts/util/constants.py：SKILL_VERSION 1.1.0 → 1.1.1
本地验证：11 个 CLI 全部 exit 0；decision_source=rules；reason 含「已结合材料包（6 份文件，待解析）」；HTML footer 含决策来源。
Co-Authored-By: Claude Code <noreply@anthropic.com>
144 lines
8.3 KiB
Markdown
144 lines
8.3 KiB
Markdown
---
|
||
name: 合同到期智能预警与续聘辅助
|
||
description: "每日凌晨扫描全校教职工合同电子台账，对距离到期日 90/60/30 天的合同分级预警，并自动生成《续聘准备任务书》和《本月合同到期人员清单》。"
|
||
version: 1.1.1
|
||
author: 深圳匠厂科技有限公司
|
||
metadata:
|
||
openclaw:
|
||
slug: alert-contract-expiring-hr
|
||
platform_kit_min_version: "1.2.11"
|
||
emoji: "📋"
|
||
category: "人事"
|
||
developer_ids:
|
||
- 12345 # 占位，请换成你的匠厂用户 ID
|
||
- 12468
|
||
allowed-tools:
|
||
- bash
|
||
---
|
||
|
||
# 合同到期智能预警与续聘辅助（alert-contract-expiring-hr）
|
||
|
||
这是基于匠厂 skill-template 主仓 v1.0.108 派生的业务技能。覆盖需求规格书第 4.2 节「🟡 人事处 Skill 002 —— 合同到期"智能预警与续聘辅助"」。
|
||
|
||
## Agent / 宿主编排（复制为业务技能后必改）
|
||
|
||
### AI + RPA 定位
|
||
|
||
- **Agent 是入口与编排者**：理解用户意图（"扫描本月即将到期的合同"、"给张三生成续聘任务书"）、补齐参数、判断风险、选择 Action，并用业务语言解释结果。
|
||
- **本技能不涉及浏览器 / 桌面 / 手机 RPA**：合同台账读取走人事系统官方 API，考核数据走党委教师工作部 API。
|
||
- 开发者与 AI 编程工具先读 `development/AI_RPA.md`。
|
||
|
||
### 架构铁律（先读）
|
||
|
||
- **宿主产品入口平级**：对话任务 / 数据管理 / 定时任务是同一技能能力的不同触发场景，**同等重要**；本技能**重点挂定时任务入口**（每日凌晨扫描）。
|
||
- **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑。
|
||
- **业务行生命周期**：本技能对合同台账表的每一份合同有"可预警 / 预警中 / 已续聘 / 已驳回"角色约束，遵守 `references/WORK_ITEM_STATUS.md`。
|
||
- **HTML 整页报告**：本技能输出个人版《续聘准备任务书》走 `render-html`；单位版清单走 PDF 导出。
|
||
|
||
### 如何触发（能力类型）
|
||
|
||
| 你要做什么 | Agent 怎么做 | 进任务中心？ |
|
||
|------------|--------------|--------------|
|
||
| 健康检查 / 短查询 | OpenClaw bash/exec + 共享 Python 跑 CLI | 否 |
|
||
| 已声明 sync 的 Action | `run_skill_action` 或等效短 CLI | 否 |
|
||
| 长任务（每日凌晨扫描全校 1000+ 份合同） | **必须** `run_skill_action` | 是（仅因 async） |
|
||
|
||
### 用户意图路由表（业务技能复制后必改）
|
||
|
||
| 用户意图（本技能自填） | Agent 怎么做 | 进任务中心？ |
|
||
|------------------------|--------------|--------------|
|
||
| 检查运行环境 | 短 CLI：`python {baseDir}/scripts/main.py health` | 否 |
|
||
| 查看版本 | 短 CLI：`python {baseDir}/scripts/main.py version` | 否 |
|
||
| 查看配置位置 | 短 CLI：`python {baseDir}/scripts/main.py config-path` | 否 |
|
||
| 每日凌晨定时扫描合同到期 | `run_skill_action` → `scan-expiring-contracts`（cron / agent） | 是（async） |
|
||
| 给某位教师生成续聘任务书 | `run_skill_action` → `generate-renewal-task`（输入：`contract_id`） | 否（sync） |
|
||
| 下发单位版续聘清单 | `run_skill_action` → `dispatch-task-notice`（输入：`unit_id` 或 `month`） | 否（sync） |
|
||
| 标记合同为已续签 | `run_skill_action` → `mark-contract-renewed`（输入：`contract_id` + 续签材料 ID） | 否（sync） |
|
||
| 在浏览器中打开续聘任务书 | `run_skill_action` → `render-html` | 否（sync） |
|
||
| 从 SmartCampus 平台抓合同 + 材料 | `run_skill_action` → `collect-from-platform`（首次需用户手工登录保存 profile） | 否（sync） |
|
||
| 解析已下载材料 PDF/Word | `run_skill_action` → `parse-materials`（可选 `--contract-id`） | 否（sync） |
|
||
|
||
## 共享 Python（必读）
|
||
|
||
宿主共享 runtime 在 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`，并已前置到 PATH（同时设 `VIRTUAL_ENV`）。短 CLI 一条命令直接跑：
|
||
|
||
```bash
|
||
python {baseDir}/scripts/main.py health
|
||
python {baseDir}/scripts/main.py version
|
||
python {baseDir}/scripts/main.py config-path
|
||
python {baseDir}/scripts/main.py init-db
|
||
```
|
||
|
||
## 数据来源（v1.1.1）
|
||
|
||
本技能合同 / 业绩数据有 **三层来源**，按优先级：
|
||
|
||
1. **HR 系统 API（生产环境推荐）**：通过宿主 `jiangchang_skill_core` 包揽
|
||
2. **SmartCampus HR 平台 RPA 采集（v1.1.1 新增）**：`collect-from-platform` CLI 用 Playwright 抓 `https://sandbox.jc2009.com/industries/campus/smartcampus/app/hr/contracts` 表格 + 点"续聘材料包"下载 PDF/Word → 本地 `data/materials/`
|
||
3. **样例 CSV（本地开发）**：`examples/contracts_sample.csv` + `performance_sample.csv`，首次 `init-db` 自动加载
|
||
|
||
AI 续聘建议（v1.1.1）默认调宿主 `jiangchang_skill_core.llm_manager.call_llm_json`；本地无 LLM 时降级到规则版（基于分数阈值），并在 `renewal_tasks.decision_source` 列标注 `llm` / `rules` / `rules_no_materials` 三种来源。
|
||
|
||
- 公共库来自共享 venv 的 `jiangchang-platform-kit>=1.2.11`（包名路径 `jiangchang_skill_core`）；**不要 vendor** `scripts/jiangchang_skill_core/`。
|
||
- 根目录 `requirements.txt` **只声明技能特有**依赖；不要写 `jiangchang-platform-kit` / `playwright`。
|
||
- `metadata.openclaw.platform_kit_min_version` 是宿主兼容声明，**不是** pip 依赖。
|
||
- `health` 用 `collect_runtime_diagnostics` 做只读诊断。
|
||
|
||
配置：仓库 `.env.example` 为模板；用户 `.env` 在 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env`。优先级：进程环境变量 > 用户 `.env` > `.env.example`。
|
||
|
||
## 面向用户问答（LLM 规则）
|
||
|
||
- 本文（`SKILL.md`）是 LLM / OpenClaw 平台读取的技能入口，**不是**用户市场说明。
|
||
- 根目录市场材料面向普通用户（见下方「文档分工」），**不是** Agent 调用契约。
|
||
|
||
当用户询问以下问题时，**必须优先读取**根目录 `README.md`（能力说明）与 `TUTORIAL.md`（逐步用法）：
|
||
|
||
- 这个技能是做什么的
|
||
- 这个技能怎么用
|
||
- 适合什么场景
|
||
- 使用前要准备什么
|
||
- 执行后会得到什么
|
||
- 能不能帮我完成某个业务任务
|
||
|
||
**回答「怎么用 / 能做什么」时的要求：**
|
||
|
||
1. 「能做什么 / 场景 / 概念类 FAQ」以 `README.md`（说明 Tab）为主；「点哪里 / 说什么 / 排障」以 `TUTORIAL.md`（教程 Tab）为主。
|
||
2. **禁止**在回答中粘贴 `python …/scripts/main.py …` 或其它命令行。
|
||
3. **禁止**为答用法而去 `dir` / `ls` / 列技能目录。
|
||
4. **不要**向普通用户暴露 Playwright、DOM、Python、RPA、库表名、`error_code` 等实现细节。
|
||
5. 用户问「怎么用」时：**优先读 `TUTORIAL.md`**。
|
||
|
||
## 文档分工
|
||
|
||
| 文档 | 读者 | 用途 |
|
||
|------|------|------|
|
||
| 根目录 `README.md` | 普通用户 | 市场 **说明** Tab |
|
||
| 根目录 `TUTORIAL.md` | 普通用户 | 市场 **教程** Tab |
|
||
| 根目录 `DEMO.md` | 普通用户 | 市场 **演示** Tab |
|
||
| 根目录 `CHANGELOG.md` | 普通用户 | 市场 **更新日志** Tab |
|
||
| `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
|
||
| `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约 |
|
||
| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范 |
|
||
|
||
## 目录约定
|
||
|
||
- `assets/`、`development/`、`evals/`、`references/`、`scripts/`、`tests/`
|
||
- CLI 入口固定为 `scripts/main.py`
|
||
- 业务逻辑按 `cli / db / service / util` 分层
|
||
|
||
## 技能命名与 slug
|
||
|
||
- slug：`alert-contract-expiring-hr`（`alert` 动词 + `contract-expiring` 名词 + `hr` 人事处缩写）
|
||
- name：**用户可见的中文业务名称**；`description` 是说明，不是名称。
|
||
- 目录名、默认 `{slug}.db` 使用 slug，不使用中文。
|
||
|
||
## 平台元数据
|
||
|
||
- `metadata.openclaw.developer_ids`：技能发布后的默认开发者可见用户 ID 列表。
|
||
- 开发期技能常为不公开：不加本人 ID，开发者自己也无法在市场安装自测。
|
||
- 当 `access_scope = 0`（不公开）时，平台会把 `developer_ids` 中的用户自动补写到 `skill_user_access`。
|
||
|
||
---
|
||
|
||
> **本技能开发状态：** v1.1.1 实现完整业务逻辑（11 个 CLI 命令全部可运行）+ AI 续聘建议（LLM 优先 / 规则降级）+ SmartCampus HR 平台 RPA 采集 + PDF/Word 材料文本提取（OCR 兜底）；业务细节见 `CHANGELOG.md`。
|