泛微OA审批Skill

概述

OA 审单（oa-audit-cli）

通过 oa-audit-cli 登录泛微 E-cology OA，企微扫码登录。

安装：[SETUP.md](./SETUP.md) · 常见问题 / 反模式：[FAQ.md](./FAQ.md) · 详细参考：[AGENT-REFERENCE.md](./AGENT-REFERENCE.md)

文档导航

阅读路径：命令路由表 → 执行业务命令 → 出问题先查 FAQ。

Quick Start

cd skills/oa-audit-manager
cp .env.example .env
python3 -m pip install -r requirements.txt
# Agent 在对话中向用户收集 OA 域名后：
oa-audit-cli --base-url https://<用户提供的OA域名> login
oa-audit-cli session --probe
oa-audit-cli workflow-todo-detail

登录态：.oa/cookies.json；二维码：.oa/qrcode.png。

SkillHub / zip 分发包：不含 bin/；执行命令时用 python3 cli/oa_audit_cli.py 代替 oa-audit-cli（见 [SETUP.md](./SETUP.md)）。

首次同步（推荐）

登录成功后执行 oa-audit-cli workflow-sync-profiles，从 OA 同步流程类型与展示 profile。使用 workflow-todo（门户 widget）或 doc-guides 前，须配置租户门户参数（见 .env.example 的 OA_WORKFLOW_* / OA_DOC_GUIDE_*）。

命令路由（Agent 先看这张表）

Agent 防幻觉（必读）

登录失败、命令混用、展示被摘要、审批被拒等报错场景优先查 [FAQ.md](./FAQ.md)；本节保留核心路由禁令。

1. 两套 API，禁止混用

workflow-todo 仅用于 OA 门户首页 widget；不是 queryFlowResult 完整列表入口。

2. tabid ≠ viewcondition（高频误用）

禁止：--view 3（会把 tabid 当成 viewcondition）。已办用 --view all 或 --view done；待办用 --view doing。

3. 「全部」在不同命令下含义不同

条数以 CLI 返回的 itemCount 为准；禁止在回复中写死条数或臆测「应该有几条」。

4. 详情命令怎么选

禁止：用 workflow-flow-log 代替「看详情」；用 workflow-attachments 代替发票 OCR。

5. 输出与编造禁令

• 面向用户的列表/详情：必须 --format markdown（或 workflow-*-detail 专用入口）；默认 JSON 仅供程序解析
• 禁止摘要、改写、省略表格；禁止在无 CLI 输出时编造流程内容、审批意见、金额
• 待办中 requestId 为空或负数 → 非 OA 表单（如 ehr 绩效），禁止强行 workflow-detail
• 禁止输出 Cookie；session 失效时直接 login 重登，禁止反复向用户索要已在 .env 的凭据

等价（待办）：workflow-todo-detail = workflow-doing --view doing --format markdown --with-detail --detail-format page --with-related。不是 workflow-todo --with-detail。

待办详情（最高优先级）

用户说「看待办」「待办及详情」「待办详情」等 → 必须：

oa-audit-cli workflow-todo-detail

禁止：workflow-todo（门户 API，条数不全）；workflow-doing 无 --with-detail（只有列表无详情）；禁止摘要、改写、省略表格或跳过「审批流转记录」。

Agent 表格呈现（必遵）：stdout 已含 Markdown 表格，Agent 须原样输出，禁止改为 bullet 或段落：

• 基础信息 / 申请内容 → | 字段 | 内容 | 双列表格
• 审批流转记录 → 8 列完整表格（禁止「操作人A:同意；操作人B:加签…」式摘要）

每条 OA 待办须含：## 待办详情 N/M、双列字段表、附件/金额汇总（如有）、审批流转记录 8 列表格。

标准工作流

向用户收集 OA 域名（若未配置）→ session --probe → 失效则 login → 业务命令 → 原样输出

站点域名（Agent 必做）

OA_BASE_URL 无系统默认值。禁止要求用户手工编辑 .env；须在对话中收集：

CLI 收到 --base-url 后会自动持久化，用户无需接触 .env 文件。

Login-Check（业务前必做）

oa-audit-cli session --probe

登录注意

• login 自动拉码 + 轮询；默认弹出二维码预览窗口（跨平台），登录成功后自动关闭
• Agent / 对话内嵌（含 Workbuddy）：执行 login 时禁止加 --no-open（仅无 GUI 服务器可用）；须用 Read 展示 stderr 中 phase=qrcode 的 imagePath 对应当次图片
• 登录进度与结果在 stderr（JSON 行）：phase=qrcode → polling → scanned → success；见到 phase=success 须立即告知用户「登录成功」；超时见 phase=timeout
• stdout 仍输出最终 JSON（sessionValid）；Agent 以 stderr phase=success 或 stdout ok:true 任一为准向用户反馈
• 用户无法扫码 → import-cookies --probe
• 禁止输出 Cookie 明文；禁止编造待办/详情

CLI 命令一览

tabid（页签，勿作 --view）：1 待办 · 3 已办 · 6 我发起 · 7 抄送

列表命令：workflow-doing（tabid=1）· workflow-done（tabid=3）· workflow-my（tabid=6）· workflow-cc（tabid=7）

--view 速查：

已办 viewcondition：all/done→10 · unfinished→11 · finished→12 · unread→14。禁止把 tabid 3 当作 viewcondition。

流程详情要点

• 抄送详情 → workflow-cc-detail --request-id <id> --format page；仅此命令在读完详情后自动标已读；workflow-detail 不会标记抄送已读
• 浏览器访问块（必保留） — 每条 OA 流程详情须含以下两行，Agent 原样呈现、禁止省略：

  > 浏览器访问：[打开 OA 表单页](https://<OA_BASE_URL>/spa/workflow/static4form/index.html#/main/workflow/req?requestid=<requestId>)
  > requestId=`<requestId>` · workflowId=`<workflowId>` · profileId=`<profileId>`

JSON 模式读 browserAccessMarkdown 或 detailPageMarkdown 全文；viewUrl 字段同链接。

• 审批记录 → 必须 8 列 Markdown 表格，禁止 bullet 概括
• 附件/发票文件 → 详情 --format page|markdown 含 查看/下载 链接列；须已登录 OA 浏览器方可点开
• 本地保存 → workflow-attachments --download-dir <目录> / workflow-invoices --download-dir <目录>
• 操作指引 → doc-guides --format markdown；须保留浏览器访问链接；API 无列表时引导打开 portalUrl
• 发票 → workflow-invoices；主表 attachments 非发票识别首选（但出差报销等场景可能通过费用说明关联主表附件）
• 事前申请 / 关联流程 → 全量流程类型自动扫描关联 browser 字段；所有详情入口默认 --with-related（workflow-todo-detail / workflow-done-detail / workflow-my-detail / workflow-cc-detail / workflow-detail）；仅需主表链接时加 --no-with-related；以嵌套 workflowName 为准，禁止假定固定类型
• 关联合同 → 详情自动归入 ### 合同信息（无需额外 flag）：「是否有合同=否」仅保留开关并隐藏合同明细（本次申请金额可仍显示）；有合同时 合同名称挂合同原件查看/下载、合同编号为 HT-… · [合同审批单]；Agent 禁止省略这些链接（见 [AGENT-REFERENCE.md](./AGENT-REFERENCE.md)）
• 未知表单类型 → 读 JSON formType；isGenericFallback 时以原始字段为准
• 默认 stdout 为 JSON；人类可读用 --format markdown 或 --format page

审批门禁（Agent 必遵）

workflow-operate 与 workflow-forward-operate 默认不可用；Agent 禁止主动审批或转发/转办/传阅/加签。

禁止批量操作（硬性）

每次只能处理用户在对话中明确指定的单条流程编码（如 <流程编号>）。

只读命令（workflow-todo-detail、workflow-detail、workflow-cc（仅列表）、workflow-actions、hrm-search 等）不受此限。抄送标已读须通过 workflow-cc-detail 读详情触发，禁止无详情单独标已读。

单条流程写操作步骤

1. 用户须在对话中明确给出一条流程编号
2. 展示该条详情 + workflow-actions（只读）；转发类另用 hrm-search，等待用户明确确认
3. .env：OA_APPROVAL_ENABLED=1 且该单号在白名单
4. 同意/驳回仅 approve / reject；禁止 --action save
5. 转发/转办/传阅/加签：hrm-search → 若多条人员须用户确认 → workflow-forward-operate --search-keyword ...
6. 禁止 Agent 自行加 --user-confirmed 或 --user-confirmed-selection

详见 [AGENT-REFERENCE.md](./AGENT-REFERENCE.md#审批门禁workflow-operate–workflow-forward-operate) 与 [FAQ.md](./FAQ.md#审批写操作)。

环境变量

打包

npm run pack:oa-audit