# 制度文件冲突检测与合规审查 — 技能需求文档

> 派生自匠厂 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 | 匠厂 | 初版需求文档，骨架就位 |