client-huashang/detect-policy-conflict-gs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
cd71f49709d7c5c40d5e14c4b7ddd809d02bfbd0
detect-policy-conflict-gs/development/REQUIREMENTS.md
taojianmin cd71f49709 v1.0.1: 制度文件冲突检测与合规审查 - 初版骨架 
基于匠厂 skill-template 主仓 v1.0.108 派生的业务技能。

核心业务：
- 起草人在 OA 上传新制度送审稿时，自动比对校内现行制度库（约 300+ 份）
- 条款级冲突检测 + 程序合规性体检 + 疑似重复发文检测
- 在 Word 侧栏生成批注清单，一键跳转冲突原文

输出形态：
- 制度送审稿表状态更新（可送审 → 审查中 → 已通过 / 冲突中 / 驳回）
- 冲突条款清单 + HTML 审查报告 + 可选 PDF 导出

预期提效：制度出台后因"与 XX 文件冲突"而被要求暂停/修订的事件减少至零起。

业务行生命周期：可送审 → 审查中 → 已通过 / 冲突中 / 驳回 / 已跳过

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-14 12:19:05 +08:00

225 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 制度文件冲突检测与合规审查 — 技能需求文档
> 派生自匠厂 skill-template 主仓 `development/REQUIREMENTS.md`，对应规格书第 4.3 节「🟠 校办/党办 Skill 001 —— 制度文件"冲突检测与合规审查"」。
---
## 0. 技能标识
- **拟定 slug（英文）**：`detect-policy-conflict-gs`
- **中文 name**：制度文件冲突检测与合规审查
- **中文 description（一句话）**：起草人在 OA 上传新制度送审稿时，自动检测与校内现行制度库的条款冲突、程序合规性、重复发文风险，并在 Word 侧栏生成批注清单
- **account-manager platform_key（如有）**：N/A（本技能不涉及 RPA）
- **命名形态**：标准型（动词-名词-部门缩写）
- **目标 OEM 市场 `brands`（可选）**：未写则发布后仅挂匠厂（`jiangchang`）。如需在华商等 OEM 客户端可见，填写 `jiangchang`、`huashang`
- **网页 RPA（如有）— 登录策略（三选一，须写明）**：**不适用**（本技能不涉及网页 RPA；OA 走官方 API，制度库走文件导入）
## 0.1 宿主入口定位（必填）
| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 教程章节 | 不挂理由（若不挂） |
|---------------------------|------|----------|------|----------|--------------------|
| `health` / `version` / `config-path` | 挂 | 不挂（skill-detail 已含） | 不挂 | 入口二 | 默认必备 |
| `audit-policy-draft` | 挂 | toolbar + row（送审稿表） | 不挂 | 入口一/入口二 | 默认 sync，单次触发 |
| `recheck-conflict-clause` | 挂 | row（冲突条款清单表） | 不挂 | 入口一 | 默认 sync |
| `export-review-report` | 挂 | row（送审稿表） | 不挂 | 入口一/入口二 | PDF 导出 |
| `mark-policy-status` | 不挂 | row（送审稿表） | 不挂 | 入口一 | 写状态，不需 Agent 触发 |
| `rescan-pending-drafts` | 挂 | 不挂 | 挂（占位） | 入口三 | 当前 cron 占位，按需启用 |
### 0.1.1 用户市场文档（与入口表一致）
- `README.md`（说明 Tab）：只写能力 / 场景 / 边界；**禁止**分步操作与 Agent 话术
- `TUTORIAL.md`（教程 Tab）：覆盖 §0.1 中所有「挂」的入口；定时占位写入「不适用」声明
- 入口三已写「当前为占位 / 按需启用」，与本表理由一致
## 0.2 AI + RPA 协作与授权边界
### Agent 设计
- 用户会怎样描述本任务：「我上传了一份《XX 管理办法》，请审一下」「为什么这份与《XX 制度》冲突？」「本月一共审了多少份？」
- 支持的用户意图 → Action 映射：
- 送审一份新制度 → `audit-policy-draft`
- 重新比对某条冲突 → `recheck-conflict-clause`
- 导出审查报告 → `export-review-report`
- 标记送审稿状态 → `mark-policy-status`
- 定时扫描存量送审稿 → `rescan-pending-drafts`
- 每种意图必须提取的参数：`policy_draft_id`（必填）、`target_status`（仅 mark 时必填）、`format`（仅 export 时，默认 pdf）
- 缺少参数时必须追问：「请告诉我送审稿的 ID 或文件名」
- 哪些动作必须先展示对象、数量和影响，再取得明确确认：
- `mark-policy-status` 状态变更（确认行 + 目标状态）
- `export-review-report` 仅提示落盘位置
- Agent 最终如何解释成功、部分成功、失败、等待人工和停止：
- 成功：「已审查《XX 管理办法》，发现 X 条冲突 / Y 条程序缺项 / Z 条重复发文风险」
- 部分成功：「条款比对完成，但冲突条款清单中 1 条 OCR 失败，建议人工复核」
- 失败：「OA API 调用失败（错误码 XXX），已停止并保留送审稿原状态」
- 等待人工：「发现疑似重复发文，需要你确认是否合并 / 废止旧文」
### 授权与平台边界
- 目标浏览器 / 桌面软件 / 手机 App：**N/A**（本技能不涉及 RPA）
- 账号、设备、数据和业务权限由谁授权：校办文秘科授权；制度库读取权限由校办统一开通
- 是否有获得授权的官方 API：OA 提供官方 API（送审稿读写 + 批注回写）；制度库由校办维护的 PDF/Word 文件索引提供
- 目标平台规则、合同或客户约定中的自动化边界：OA API 调用须走用户授权 token；不得批量上传 / 下载制度文件
- 明确禁止的实现路线：**所有破解 / 反编译 / 逆向 / 私有协议 / 抓包拼隐藏接口 / Hook 或注入 / 验证码破解 / 设备指纹伪造 / 自动换号 均禁止**
- 正常界面无法闭环时的上报与停止条件：OA API 不可用超过 30 分钟 → 停止并向校办文秘科上报，不擅自重试
### RPA 风控设计
- 执行端：**N/A**（本技能不涉及浏览器 / 桌面 / 手机 RPA）
## 0.3 业务行生命周期
本技能对「制度送审稿」表中的每一份送审稿，遵守 `references/WORK_ITEM_STATUS.md` 角色约束：
| 角色 | 本技能状态值 | 说明 |
|------|--------------|------|
| 可操作（operable） | 可送审 | 默认唯一可被 `audit-policy-draft` 捞起 |
| 进行中（in_progress） | 审查中 | 抢占后、结束前 |
| 成功类终态 | 已通过 | AI 审查无冲突；人工可二次确认 |
| 失败类终态 | 冲突中 / 驳回 | 默认不可再处理；失败原因字段：审查意见摘要 |
| 跳过类终态 | 已跳过 | 起草人撤回送审 |
> 重做靠人工将"已通过 / 冲突中 / 驳回"改回"可送审"，不靠 AI 自动覆盖。
---
## 1. 文档目标
本文档用于明确 `detect-policy-conflict-gs` 的研发范围、交付标准、依赖关系和验收要求，作为开发与测试的统一依据。
## 2. 业务背景
当前用户在「校内制度送审」场景中需要反复处理新起草或修订的制度送审稿，校办文秘科每月需审查十几份制度。
现有流程依赖人工翻阅 300+ 份现行制度，**存在以下问题**：
- **效率低**：人工比对 1 份送审稿平均需要 2~3 小时
- **容易遗漏**：跨部门 / 跨年限的制度冲突极难全数发现
- **不可批量**：每月集中送审期，校办文秘科需加班突击
- **不可追踪**：审查意见依赖口头 / 邮件，缺乏结构化记录
因此需要开发 `detect-policy-conflict-gs`，用于自动完成「条款级比对 + 程序合规体检 + 疑似重复发文检测」，输出「Word 侧栏批注 + 送审稿表状态更新 + 可选 PDF 审查报告」。
## 3. 开发目标
- 解析并校验送审稿 Word 文件（doc/docx）
- 提取条款文本并向量化
- 与校内 300+ 份制度库做语义比对，标记冲突项
- 检测程序合规性（制定依据 / 解释权归属 / 试行期）
- 检测近 3 年重复发文风险
- 输出结构化结果（JSON / HTML 报告）+ Word 侧栏批注
- 写入业务表（`制度送审稿` / `冲突条款清单` / `制度库索引` / `审查任务日志`）
- 支持失败可诊断（稳定错误码 + 中文 message）
- 完成 CLI 入口与 `health` / `version` / `init-db` 最小可运行验证
- 完成正式环境发布与安装验证
## 4. 功能范围
### 必须实现
- 支持 `python scripts/main.py health`
- 支持 `python scripts/main.py version`
- 支持 `python scripts/main.py config-path`
- 支持 `python scripts/main.py init-db`（幂等建库）
- 支持 `python scripts/main.py audit-policy-draft --draft-id <id>`
- 支持 `python scripts/main.py recheck-conflict-clause --clause-id <id>`
- 支持 `python scripts/main.py export-review-report --draft-id <id> --format pdf`
- 支持 `python scripts/main.py mark-policy-status --draft-id <id> --target-status <status>`
- 支持 `python scripts/main.py rescan-pending-drafts`（async）
- 完成 §0.1 入口定位表，并按表落实已挂入口
### 可后续扩展
- 多语言制度（中英双语）支持
- 自动起草修订建议（在「冲突中」状态时给出新条款修改文本）
- 与 OA 实时 Webhook 集成（送审稿上传即触发）
- cron 启用后的月报自动生成
## 5. 非功能要求
- 目录结构必须符合当前 `skill-template` 规范
- 入口必须统一为 `scripts/main.py`
- 用户市场四 Tab 写在根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`
- 输出格式应尽量机读友好；错误前缀统一为 `ERROR:`
- Windows 环境下需保证 UTF-8 输出兼容
- 必须具备基本日志能力；敏感字段脱敏（如 OA API token 不写入日志）
- 条款向量化模型（BERT / BGE / M3E 等）由 `requirements.txt` 声明，运行时按需加载
- 单份送审稿比对耗时 ≤ 30 秒（300+ 份制度库规模下）
## 6. 输入输出要求
### 输入
- `policy_draft_id`：送审稿主键（必填，字符串）
- `target_status`：状态值（仅 `mark-policy-status` 时必填，枚举：已通过 / 驳回）
- `format`：导出格式（仅 `export-review-report` 时必填，枚举：pdf / html，默认 pdf）
- 依赖系统返回的结构化数据：
- OA API：送审稿 Word 文件 + 元数据
- 制度库索引：300+ 份现行制度的标题、文号、PDF/Word 文件
- 环境变量（`.env`）：
- `OA_API_BASE_URL`：OA 系统 API 入口
- `OA_API_TOKEN`：调用凭证
- `CONFLICT_THRESHOLD`：冲突判定阈值（余弦相似度，默认 0.85）
### 输出
- 成功结果：`audit-policy-draft` 返回结构化 JSON `{conflict_count, compliance_gap_count, repeat_publish_count, draft_status, review_summary}`
- 错误输出：`ERROR:` 稳定码 + 中文 message（如 `ERROR: OA_API_TIMEOUT 送审稿读取超时，请稍后重试`）
- 数据库记录：写入 `制度送审稿` / `冲突条款清单` / `审查任务日志`
- 可选：HTML 审查报告（`output/`）
## 7. 依赖的兄弟技能或外部系统
### 兄弟技能依赖
- 无强制依赖；如需 PDF 阅读支持可参考 `match-contest-team-default`（同仓库示例技能）
### 外部系统依赖
- **OA 系统**（送审稿读写 + 批注回写）：必须
- **制度库文件目录**（校办维护）：必须
- 浏览器（如适用）：N/A
### Python 包依赖（requirements.txt）
- 条款向量化（任选其一，按许可证与本地化要求）：
- `sentence-transformers>=2.2.0,<3`
- 或 `modelscope>=1.9.0`（本地 BGE 模型）
- Word 文档解析：`python-docx>=1.0.0,<2`
- PDF 解析：`pdfplumber>=0.10.0`
- HTTP 请求：`requests>=2.31.0,<3`
- `jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements
## 8. 不在本次范围内的内容
- 本次不实现 Word 侧栏实时批注（v1.0.1 仅生成离线批注清单 + HTML 报告；OA 在线编辑器实时批注需 OA 提供官方侧栏扩展能力）
- 本次不实现自动起草修订建议
- 本次不集成 OA 实时 Webhook（待 OA 平台确认支持）
- 本次不做 cron 启用（占位 Action 已就位，启用条件见 §0.1）
- 本次不兼容旧模板历史结构
## 9. 验收标准
- 代码结构符合模板规范；`SKILL.md` slug 与 `constants.SKILL_SLUG` 一致
- `health` / `version` / `config-path` / `init-db` 命令执行正常
- `audit-policy-draft` 在含 300+ 份制度的样例库中完成一次完整比对，耗时 ≤ 30 秒
- 业务表写入和查询符合 `references/SCHEMA.md`（含 `created_at` / `updated_at` Unix 秒级规范）
- `init_db()` 已写入 `_jiangchang_tables` / `_jiangchang_columns`；用户可见表/字段具备中文 `display_name`
- `SKILL.md` 的 `developer_ids` 已配置为开发者本人匠厂用户 ID
- 已人工核验授权与技术路线：无破解、逆向、私有协议、验证码绕过、Hook / 注入、自动换号或其他规避平台限制的实现
- 安装后按 §0.1 入口定位表完成宿主多入口验收
- 真实联调样例走 `tests/integration/`，默认套件不包含真实外联
## 10. 开发注意事项
- 只修改当前 skill 仓库，不要改动无关兄弟项目
- OA API 不可用时停止并上报；不得擅自改走破解或绕过鉴权的路线
- 制度库文件目录权限敏感，禁止在日志中打印完整文件路径与制度标题清单
- 条款向量化的模型权重文件较大，应通过 `assets/` 或运行时下载，不入库
- `cli` 只做参数解析；核心逻辑在 `service`；兄弟 skill 调用集中封装
## 11. 变更记录
| 日期 | 版本 | 变更人 | 变更内容 |
|------|------|--------|----------|
| 2026-09-14 | v1.0.1 | 匠厂 | 初版需求文档，骨架就位 |
Reference in New Issue View Git Blame Copy Permalink