175 lines
14 KiB
Markdown
175 lines
14 KiB
Markdown
---
|
||
name: 高校人事请假考勤
|
||
description: "针对高校教职工请假申请，按学校政策自动核算扣薪、判定审批层级并更新考勤记录，输出审批单与扣薪报告"
|
||
version: 1.0.3
|
||
author: 深圳匠厂科技有限公司
|
||
metadata:
|
||
openclaw:
|
||
slug: process-leave-attendance-default
|
||
platform_kit_min_version: "1.2.11"
|
||
emoji: "📋"
|
||
category: "人事"
|
||
developer_ids:
|
||
- 79017
|
||
brands:
|
||
- jiangchang
|
||
- huashang
|
||
allowed-tools:
|
||
- bash
|
||
---
|
||
|
||
# 高校人事请假考勤
|
||
|
||
面向高校人事管理与院系考勤：在本地维护教职工、请假政策与考勤日历，按规则自动核算扣薪金额、判定审批层级、更新考勤与假期余额，并输出审批单与扣薪 HTML 报告。V1 **不依赖 llm-manager**；默认无外站 RPA。
|
||
|
||
## Agent / 宿主编排
|
||
|
||
### AI + RPA 定位
|
||
|
||
- **Agent 是入口与编排者**：理解用户意图、补齐参数、判断风险、选择 Action，并用业务语言解释结果。
|
||
- **RPA 是确定性执行器**：只按已验证步骤操作授权范围内的浏览器、桌面软件或手机；不得破解、逆向、调用未授权私有协议或绕过验证码、安全验证和平台限制。
|
||
- 遇到验证码、人脸、U盾、频控、账号风险或权限不足时，转人工或安全停止，禁止自动硬闯、换号或无限重试。
|
||
- 开发者与 AI 编程工具先读 `development/AI_RPA.md`；三端界面代码必须先读 `development/RPA_ELEMENT_LOCATING.md` 并完成真实拾取与 element map，再按浏览器/桌面/手机选读 `RPA_BROWSER.md` / `RPA_DESKTOP.md` / `RPA_MOBILE.md`；浏览器账号、Profile、多账号和租约另读 `development/ACCOUNT_MANAGER.md`。
|
||
|
||
### 架构铁律（先读）
|
||
|
||
- **宿主产品入口平级**：对话任务 / 数据管理 / 定时任务是同一技能能力的不同触发场景，**同等重要**；挂哪些由本技能 UX 定义（入口定位表），详见 `development/PRODUCT_SURFACES.md`。以后宿主若增加新入口，仍是「新触发场景 + 同一内核」。
|
||
- **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。
|
||
- **数据管理**：既是 **UI 执行面**（点按钮走与对话相同的闭环），也是数据与过程可见；不是「只读库」。
|
||
- **`placements`**：只决定 Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail）。其中 `row` 表示**行级入口**（宿主可呈现为操作列、行右键、行内「⋯」等；技能配什么就显示什么，无独立菜单 DSL）。数据管理技能按钮顺序见 `actions` **数组相对顺序**（详见 `references/ACTIONS.md`），无独立 sortOrder。
|
||
- **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
|
||
- **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action **仍必须**显式写 `sync` 或 `async`。
|
||
- **`policy`（可选）**：需要按用户/角色控制数据管理按钮或行列时，在 `actions.json` 顶层启用 Data Policy，由技能 `policy` CLI 输出 Snapshot；**未启用 = 与今日一致（L0）**。详见 `references/POLICY.md`。用户/角色数据源（飞书/库/API）属技能内部，宿主不托管。
|
||
- **`cellPresentation`（可选）**：需要数据管理「某格特殊标色/强调」时启用；技能按当前数据写入呈现（语义 tone），宿主映射主题样式；**未启用 = P0 无标色**。用途不限（超时、预警、驳回等）。详见 `references/CELL_PRESENTATION.md`。
|
||
- **业务行生命周期（有处理队列时）**：对某一行做生成/触达/私信等处理时，默认只操作「可操作」角色状态；开始抢占「进行中」；结束回写成功或失败（失败带原因）；重做靠人工改回可操作。状态名由本技能自定。详见 `references/WORK_ITEM_STATUS.md`。
|
||
- **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；文件型特殊报告才另做 `export-*`（落 `output/`）；**HTML 整页报告**写 `html/` 并用固定 Action id `render-html`（见 `references/ACTIONS.md`）。
|
||
- **准备 vs 执行（适用则拆）**：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。
|
||
|
||
### 如何触发（能力类型）
|
||
|
||
| 你要做什么 | Agent 怎么做 | 进任务中心？ |
|
||
|------------|--------------|--------------|
|
||
| 短查询 / 只读 / 秒级（`health` / `version` / `stats` / `list` / `get` 等） | OpenClaw bash/exec + **共享 Python** 跑 CLI（见下方「共享 Python」） | 否（CLI 当场结束） |
|
||
| 已在 `actions.json` 声明且 `executionProfile: "sync"` 的能力 | 可用 `run_skill_action`，或同等效果的短 CLI（同一内核） | 否 |
|
||
| 长耗时 / RPA / 浏览器 / 需要进度或取消；或 `executionProfile: "async"` | **必须** `run_skill_action`（先 `list_skill_actions` / `get_skill_action`） | **是**（仅因为该 Action 是 async） |
|
||
| 用户只问用法 / 能做什么 | 读根目录 `README.md`；逐步操作再读 `TUTORIAL.md`；**不要**为答用法去列目录或默认打开 `references/` | — |
|
||
|
||
### 用户意图路由表
|
||
|
||
| 用户意图 | Agent 怎么做 | 进任务中心？ |
|
||
|------------------------|--------------|--------------|
|
||
| 导入教职工 | 短 CLI：`import-employees --file …` 或 Action `import-employees` | 否 |
|
||
| 请假核算 | 短 CLI：`calculate-leave --employee-id … --leave-type … --start-date … --end-date …` 或 Action `calculate-leave` | 否 |
|
||
| 生成请假报告 | 短 CLI：`render-html` 或 Action `render-html` | 否 |
|
||
| 健康 / 版本 / 初始化库 | `health` / `version` / `init-db` | 否 |
|
||
|
||
本技能全部为 sync，无长任务 / RPA；细节分流见 `references/CLI.md`。
|
||
|
||
**硬规则：**
|
||
|
||
1. **禁止**对长任务使用 `exec`/`bash` 跑 `…/scripts/main.py run`（或等价业务命令）再 `process poll` 干等。
|
||
2. **禁止**用 `uv run python …` 跑技能脚本（会建临时环境，缺 `jiangchang_skill_core`）。
|
||
3. **禁止** Agent 自行 `pip install`。
|
||
4. **入口按定位表挂载**：本技能入口见 `assets/actions.json` 与 `development/REQUIREMENTS.md`；全部为 sync Action，无 async / RPA。
|
||
5. **一个业务能力一个 Action**，用多个 `placements` 挂入口；底层仍是同一 `scripts/main.py` CLI。
|
||
6. 是否进任务中心**只**看该 Action 的 `executionProfile`，与数据管理 / 定时 / Agent 入口无关。
|
||
7. **处理业务行**时遵守状态角色契约（可操作 / 进行中 / 终态）；禁止对已成功/失败/跳过默认重复处理。详见 `references/WORK_ITEM_STATUS.md`。
|
||
|
||
Agent 执行契约细节：`references/CLI.md`、`references/ACTIONS.md`、`references/SCHEMA.md`、按需 `references/POLICY.md` / `references/WORK_ITEM_STATUS.md`（不要把 `development/` 当 Agent 主读路径）。
|
||
|
||
## 共享 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
|
||
python {baseDir}/scripts/main.py import-employees --file 示例教职工.json
|
||
python {baseDir}/scripts/main.py calculate-leave --employee-id 1 --leave-type 病假 --start-date 2026-09-10 --end-date 2026-09-25 --has-certificate
|
||
python {baseDir}/scripts/main.py render-html
|
||
```
|
||
|
||
教职工库目录：`{skill_data}/input/教职工库/`（内置示例在 `assets/samples/`，初始化时同步）。
|
||
|
||
- 公共库来自共享 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）为主。说明 Tab **不应**含分步操作；若 README 仍有旧式步骤，以教程为准并提示开发者按 `development/TUTORIAL_SURFACES.md` 修正。
|
||
2. **禁止**在回答中粘贴 `python …/scripts/main.py …` 或其它命令行（除非用户明确索要命令，或自称技术人员/开发者）。
|
||
3. **禁止**为答用法而去 `dir` / `ls` / 列技能目录，或默认打开 `references/`、`development/`；仅当用户明确问命令、参数、集成或排错时再读 `references/`。
|
||
4. **不要**向普通用户暴露 Playwright、DOM、Python、RPA、库表名、`error_code` 等实现细节，除非用户明确询问技术实现。
|
||
5. 用户问「怎么用」时：**优先读 `TUTORIAL.md`**；不要只根据 README 臆造按钮路径。
|
||
|
||
**文档读取边界：**
|
||
|
||
- **不要**把 `SKILL.md`、`references/`、`development/` 中的技术细节直接作为用户回答。
|
||
- **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/`；`development/` 主要给开发者 / 编码助手，对话 Agent **不必**默认打开。
|
||
- 若市场材料与 `SKILL.md` / `references` 表述冲突：对用户展示以 `README.md` / `TUTORIAL.md` 为准；对执行契约以 `SKILL.md` / `references` 为准。
|
||
- 用户未问技术实现时，**不要**讨论 slug 命名规则；开发者问命名或 slug 时，读取 `development/NAMING.md`。
|
||
|
||
## 文档分工
|
||
|
||
| 文档 | 读者 | 用途 |
|
||
|------|------|------|
|
||
| 根目录 `README.md` | 普通用户 | 市场 **说明** Tab（`readme_md`）：能力/场景/边界；**非教程** |
|
||
| 根目录 `TUTORIAL.md` | 普通用户 | 市场 **教程** Tab（`tutorial_md`）：分入口操作；结构见 `development/TUTORIAL_SURFACES.md` |
|
||
| 根目录 `DEMO.md` | 普通用户 | 市场 **演示** Tab（`demo_video_url` + `demo_md`） |
|
||
| 根目录 `CHANGELOG.md` | 普通用户 | 市场 **更新日志** Tab（按版本小节 → `changelog`） |
|
||
| `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
|
||
| `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约（Agent 主读） |
|
||
| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范；**产品入口**见 `development/PRODUCT_SURFACES.md`；**用户文档契约**见 `development/TUTORIAL_SURFACES.md` |
|
||
|
||
## 目录约定
|
||
|
||
复制后建议保留：
|
||
|
||
- `assets/`、`development/`、`evals/`、`references/`、`scripts/`、`tests/`
|
||
- CLI 入口固定为 `scripts/main.py`
|
||
- 业务逻辑按 `cli / db / service / util` 分层
|
||
|
||
## 定制入口
|
||
|
||
1. 从本模板创建新业务技能时，**不得保留模板 `.git`**；优先使用 [`tools/scaffold_skill.ps1`](tools/scaffold_skill.ps1)（见 [`tools/README.md`](tools/README.md)）。
|
||
2. 业务技能仓库中**不得**存在 `.openclaw-skill-template`（仅 template 源仓库保留）。
|
||
3. 复制目录为你的新 skill 仓库，全局替换 `process-leave-attendance-default` 等占位词。
|
||
4. 按 `development/DEVELOPMENT.md` 完成开发与文档定制；开发前先读 `development/PRODUCT_SURFACES.md` 并填写入口定位表。
|
||
5. 用户市场四 Tab 材料写入根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`。
|
||
6. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
|
||
7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`。
|
||
|
||
## 技能命名与 slug
|
||
|
||
- 标准格式：`{verb}-{noun-phrase}-{platform}`（详见 `development/NAMING.md`）。
|
||
- slug / repo / 目录 / `SKILL_SLUG` / DB 文件名：**英文** kebab-case；`name`、`description`、根 `README.md`：**中文**。
|
||
- 复制为新业务技能前**必须**阅读 `development/NAMING.md`。
|
||
- `name`（frontmatter）：**用户可见的中文业务名称**；`description` 是说明，不是名称。
|
||
- `metadata.openclaw.slug`：**英文 kebab-case** 机器标识；目录名、默认 `{slug}.db` 使用 slug，不使用中文。
|
||
- 复制后全局替换 `process-leave-attendance-default` 与 `process_leave_attendance_default`（脚手架会自动处理）；正式技能不得保留英文占位 `name` 或 slug。
|
||
|
||
## 平台元数据
|
||
|
||
- `metadata.openclaw.developer_ids`：`[12500]`
|
||
- 当 `access_scope = 0`（不公开）时，平台会把 `developer_ids` 中的用户自动补写到 `skill_user_access`。
|