v1.0.1: 制度文件冲突检测与合规审查 - 初版骨架
基于匠厂 skill-template 主仓 v1.0.108 派生的业务技能。 核心业务： - 起草人在 OA 上传新制度送审稿时，自动比对校内现行制度库（约 300+ 份） - 条款级冲突检测 + 程序合规性体检 + 疑似重复发文检测 - 在 Word 侧栏生成批注清单，一键跳转冲突原文 输出形态： - 制度送审稿表状态更新（可送审 → 审查中 → 已通过 / 冲突中 / 驳回） - 冲突条款清单 + HTML 审查报告 + 可选 PDF 导出 预期提效：制度出台后因"与 XX 文件冲突"而被要求暂停/修订的事件减少至零起。 业务行生命周期：可送审 → 审查中 → 已通过 / 冲突中 / 驳回 / 已跳过 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
14
development/README.md
Normal file
14
development/README.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# development
|
||||
|
||||
> 本技能 `development/` 目录的开发规范与教程，**派生自匠厂 skill-template 主仓**。
|
||||
>
|
||||
> **使用方式：** 主仓 `skill-template-main/skill-template/development/` 已沉淀完整的开发教程、需求模板、验收清单、日志规范、产品入口契约、共享仓目录等公共内容；本目录仅放本技能特有的说明文件，公共开发规范**请回主仓查阅**。
|
||||
>
|
||||
> 主仓入口对应关系：
|
||||
> - `REQUIREMENTS.md`（本目录）= 主仓 `REQUIREMENTS.md` 模板的本技能实例
|
||||
> - 主仓其他文件（`DEVELOPMENT.md` / `PRODUCT_SURFACES.md` / `CHECKLIST.md` / `RPA*.md` / `AI_RPA.md` / `LOGGING.md` / `CONFIG.md` / `NAMING.md` / `POLICY_MATRIX.md` / `TESTING.md` / `RUNTIME.md` / `SKILL_ACTION_RUNTIME.md` / `SHARED_REPOS.md` / `ACCOUNT_MANAGER.md` / `ADAPTER.md` / `TUTORIAL_SURFACES.md`）请查阅主仓原版
|
||||
|
||||
## 本目录文件清单
|
||||
|
||||
- `README.md`：本文件
|
||||
- `REQUIREMENTS.md`：本技能需求文档（v1.0.1 已就位）
|
||||
224
development/REQUIREMENTS.md
Normal file
224
development/REQUIREMENTS.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 制度文件冲突检测与合规审查 — 技能需求文档
|
||||
|
||||
> 派生自匠厂 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
Block a user