pm-doc-spec 项目管理文档规范化 Skill

> 本 Skill 自身按 GJB 0.3-2001《军用标准文件编制工作导则 第3部分：出版印刷规定》 的章条体例编写：章用阿拉伯数字 1、2、3… 连续编号，条用 x.y 挂靠章号，无跳号/重号；附录区分"规范性"与"资料性"并重新编号。以此作为"文档规范化"的体例示范。

1 范围

1.1 目的

把零散、命名不规范、散落在各项目目录中的原始文档，转换为可被检索、可追溯、可审计的规范资产：
- 原始文件只读不可变（复制到原始层 raw_dir，绝不改动原件）。
- 按统一命名规则生成规范名，落到归档层 archive_root（副本，可删可重建）。
- 元数据写入 SQLite 台账（t_archive / t_pending / t_dedup / t_project 等）。

1.2 适用

• 收到一份待归档的项目文档（docx / doc / pdf），需要规范化命名并入库。
• 需要统一项目的文档命名规则、阶段/类别/密级枚举。
• 处理人工闸口队列（t_pending 中的待确认项：日期冲突、版本复核、缺字段等）。
• 真实文档暴露了字典缺口（新项目代号、新文档类别），需反哺权威表。

1.3 不适用

• 涉密原始件（秘密/机密/绝密）不得进入本系统，须物理归档并按保密规定脱密前置。
• 检索 / 类比 / 审计等 L2 应用层为后续扩展，不在本 Skill 执行范围内。

2 规范性引用文件

• GJB 0.3-2001《军用标准文件编制工作导则 第3部分：出版印刷规定》——章条体例参照。
• references/rules.md —— 规则手册（R1–R7 全文、去重、涉密红线、人工闸口决策表）。
• references/dict.md —— 权威字典（五张表：阶段/类别/密级/命名/项目台账）。
• references/flow.md —— 执行步骤参考（与流水线一一对应）。
• references/learnings.md —— 自学习库（人工闭环沉淀的方法论案例与复发计数）。
• references/learning_loop.md —— 自学习闭环 SOP。
• references/doc_spec_full.md —— 字段详解与取值区间、运行流程（详细方案）。
• pm_v1/pipeline/process_real_doc.py —— 已用真实文档验证的流水线。
• pm_v1/config.py —— 存储路径配置（首次询问 + 对话可改）。
• pm_v1/registry/project_ctl.py —— 项目代号台账控制（R7 唯一事实源）。

3 术语和定义

下列术语适用于本文件。

• 原始层（raw_dir）：存放原件只读副本的证据层，默认 pm_v1/data/20_raw。原件绝不改动，仅复制。
• 规范名：按命名规则（见附录 A）生成的统一文件名，形如 项目代号_阶段代码_文档类别_成文日期_版本号_专业分系统_密级.扩展名。
• 归档层（archive_root）：存放规范名副本的目录，默认 pm_v1/data/30_archive；按 archive_root/<项目代号>/ 分项目归档。
• 台账：SQLite 数据库 pm_registry.db 中的元数据表集合（t_archive 归档记录、t_pending 人工闸口、t_dedup 去重、t_project 项目台账等）。
• 人工闸口：当字段不确定、涉密、受限、近重复、版本冲突时，文档不自动放行，落入 t_pending 待人员裁决的机制。
• 辅助打标：AI 基于规则匹配 + 字典 + 路径/文件名推断"建议值 + 置信度 + 待确认原因"，仅作辅助，不自动裁决。
• 项目代号（proj_code）：文档归属项目的唯一代号，由人工界定产生（R7），知识库不预置默认值。
• 去重：精确去重（sha256 完全一致）与近重复（difflib ratio() > 0.85）两道机制，防止覆盖与重复提交。
• 阶段代码：研制阶段枚举 S0–S7（预研/论证/方案/初样/正样/设计定型/生产定型/批产）。

4 总则

4.1 设计哲学：辅助打标 + 人员终审

• AI 做辅助推断，产出"建议值 + 置信度 + 待确认原因"。
• 凡不确定项一律进人工闸口 t_pending，AI 不自动放行；人员确认后由运维脚本物理落盘/重命名。
• "不自动裁决"是红线：多源冲突、日期缺失、版本冲突、涉密/受限，宁可推人工，不可静默选值。

4.2 涉密与合规原则

• 涉密原始件（秘密/机密/绝密）不进入电子检索系统，按保密规定物理归档；脱密前置（辅助 + 人员终审）后，按脱密后密级入库。
• 内部/受限材料处理环境须在可信区；不送公网 API、不用公有云 OCR。

4.3 onboarding 原则（首次使用）

• 配置存储路径：首次调用由 agent 询问"原始层目录(raw_dir)"与"归档根目录(archive_root)"，写入 pm_v1/config.json，标记 first_run_done；之后可随时对话变更。
• 创建基础项目台账：团队首次调用须先创建本团队基础项目（代号/名称/类型/当前阶段/密级基调/匹配关键词），写入 t_project。台账为空或仅样例时，处理文档前要求先建项目。

5 处理流程

主流程为八步主线（5.2–5.9）；5.1 为仅首次或对话触发的 onboarding 前置。

5.1 首次配置与 onboarding（仅首次 / 对话触发）

• 配置存储路径：询问 raw_dir、archive_root，写入 pm_v1/config.json；后续可 config.py set 变更。
• 创建基础项目台账：要求用户创建若干基础项目，project_ctl.py add 写入 t_project。
• 非首次且配置已存在 → 跳过本步，直接进入 5.2。

5.2 原始层不可变副本

• 复制原件到 raw_dir/<原名>，原件绝不改动；既存副本则跳过（幂等）。

5.3 入库解析（intake）

• docx：python-docx 取段落 + 表格文本、核心属性。
• doc：olefile 读 WordDocument 流，UTF-16LE 解码抽取可读片段（密级/日期/标题足够），不标 need_ocr（无需 LibreOffice）。
• pdf：pypdf 文本层；无文本层 → need_ocr。
• 计算 sha256；与已入库文本做近重复比对（difflib ratio）。

5.4 头表提取（文档自带权威标签）

• 兼容两种格式：单格"密级：内部/版本：A/0"；两列 key-value"密级|公开"。
• 取 classification / stage_marker / version（仅取本行首个 token，防拼段误读）。
• 若 classification ∈ {秘密,机密,绝密} → 脱密前置拦截，中断并提示。

5.5 辅助推断字段（含 R7 项目代号人工界定）

• 项目代号（R7）：推断的代号已在 t_project 台账 → 直接复用；不在台账 → 不自动赋码，反馈人工并依据代号规范（大写字母+数字+连字符、≤16 字符、避免中文/空格）推荐一个代号（取标题/正文/路径中稳定最短标识或型号，如 HTA100/03DYT/USV），请求人工确认后写入台账；确认前 reason=new_project。
• 分系统：路径/文件名关键词（热控/电控/伺服控制板/HTA100…）。
• 阶段：报告性质（R1）或头表阶段标记映射。
• 文档类别：文件名关键词（立项报告/方案设计报告/问题闭环报告/用户手册…）。
• 密级：头表标签，缺失按 R5→公开。
• 日期、版本：见 5.6、5.7。

5.6 成文日期裁决（R2 / R3 / R6）

• 文件名 8 位 → 采用（权威）。
• 否则 _finalize_dates：内容来自封面/首页、签字页、计划进度部分（段落级 + 表格级）。
• 完全无内容日期 → R6 用文件最后修改日期补录（标注非权威）。
• 多源年份不一致 → date_conflict（R3），推人工，列全部候选，不自动选。
• 文件修改时间与内容年份不一致 → 追加交叉校验提示（mtime 非成文日期）。
• 无内容日期且无 mtime → doc_date_missing。

5.7 版本号与同主题比对（R4）

• 同（项目·阶段·类别）无归档 → V1.0；已有归档 → 最大版本 +0.1。
• 同主题比对（防覆盖、判最新）：
• 相似度 ≥0.95 → re_submit_suspect（疑似重复提交）。
• 相似度 <0.95 → version_review（疑似新版本，附差异行）。

5.8 人工闸口判定

• auto = proj_code存在 ∧ 置信度≥0.6 ∧ ¬need_ocr ∧ 密级≠受限 ∧ 近重复≤0.85 ∧ 无 extra_reasons。
• auto → t_archive 状态 archived。
• 否则 → t_archive 状态 pending + t_pending 记录（reason / suggested 字段 JSON）。
• 无论归档/待确认，均写入 archive_name（建议规范名），保证台账与磁盘一致。

5.9 落账与报告（按项目代号归档）

• 已确认项目 → archive_root/<proj_code>/<建议名>；新项目待确认 → 先暂存 archive_root/__pending__/<建议名>，人员确认并登记项目后重新归档转正到 archive_root/<proj_code>/。
• 更新 t_archive.archive_path、去重表 t_dedup；本次成功归档时，将同 sha256 的旧 pending 行置 superseded。
• 生成 reports/normalize_<原名>.md：字段来源表、日期多源核查、版本比对、R7 新项目待确认块、备注与待确认项。

6 规则要求

> 以下为规则概要；完整正文与实例见 references/rules.md。规则优先级高于任何局部推断；与用户决策冲突时以用户最新口径为准。

• R1 阶段按报告性质归档：立项报告→S1、方案设计报告→S2、问题闭环报告→S5、用户/产品手册→S6；头表"阶段标记"可覆盖；正文称项目已处更后阶段仅作备注不自动改。
• R2 成文日期内容提取优先于元数据：文件名 8 位 → 否则多源采集（封面/首页、签字页、计划进度部分，含表格级扫描）。
• R3 多源年份冲突 → 推人工：封面/首页、签字页、计划进度部分、文件修改时间之间年份不一致时，一律 date_conflict，禁止静默选值；文件修改时间仅作交叉校验，永远不是成文日期。
• R4 版本忽略封面版本 + 默认规则 + 同主题比对：首版 V1.0；同（项目·阶段·类别）已归档则递增；相似度 ≥0.95 判疑似重复提交，否则判疑似新版本，差异交人工判最新。
• R5 密级未标注 → 公开：头表无密级标签时默认 公开（仅对未标注生效）；受限 仍须人员确认；秘密/机密/绝密 属涉密原始件，脱密前置拦截，不入检索库。
• R6 日期缺失 → 文件最后修改日期补录：文档内容（文件名/正文/签字页/计划进度）全无日期时，使用文件最后修改日期补录为成文日期，明确标注"非文档权威内容、仅供索引"；仅当无法取得文件修改时间才落 doc_date_missing 推人工。
• R7 项目代号由人工界定产生（含 onboarding 与新建项目检测）：项目代号(proj_code)由人工界定，AI 不自动生成，知识库不预置默认代号（现有样例仅演示）；团队首次调用须先初始化基础项目台账；解析后推断代号不在台账 → 反馈人工、按代号规范推荐代号、请求确认（reason=new_project），确认前不自动归档。

7 人工闸口决策

强制进 t_pending 的原因（完整表见 references/rules.md）：

8 权威字典

唯一事实源，references/dict.md 五张表：
- 表1 研制阶段枚举 S0–S7；
- 表2 文档类别枚举（方案设计报告/技术要求/立项报告/问题闭环报告/用户手册等）；
- 表3 密级枚举（仅脱密后：公开/内部/受限）；
- 表4 命名规则（字段顺序与分隔符，见附录 A）；
- 表5 项目台账（由团队 onboarding 人工创建，样例代号仅演示、非默认，见 R7）。

其余 Skill / 脚本一律只读字典，新增枚举须经人员确认后由 registry 统一变更。

9 配置与执行

优先使用自带运行器（自动定位工作区内的 pm_v1 流水线）：

python scripts/normalize_doc.py "<原始文档绝对路径>"

或直接调用已验证流水线：

cd pm_v1/pipeline && python process_real_doc.py "<原始文档绝对路径>"

处理报告输出到配置的报告目录（默认 pm_v1/reports/normalize_<原名>.md），台账写入 pm_v1/data/pm_registry.db。

配置管理（首次询问 + 对话可改）：

python pm_v1/config.py show                              # 查看当前配置
python pm_v1/config.py set raw_dir "D:/pm/20_raw"        # 改原始层目录
python pm_v1/config.py set archive_root "D:/pm/30_archive" # 改归档根目录

项目台账（R7 登记/查询）：

python pm_v1/registry/project_ctl.py list                                # 列出已登记项目
python pm_v1/registry/project_ctl.py match --name "某文件名.docx"         # 试解析项目代号
python pm_v1/registry/project_ctl.py add --code <代号> --name <名称> --keywords <逗号分隔关键词> --type <类型> --base_class <密级基调>

10 安全与合规红线

• 涉密原始件（秘密/机密/绝密）不进入电子检索系统，按保密规定物理归档；脱密前置（pm-sanitize 辅助 + 人员终审）后，按脱密后密级入库。
• 内部/受限材料处理环境整体须在可信区；不送公网 API、不用公有云 OCR。
• 原始文件只复制不移动、不重命名；物理重命名由运维脚本在人员确认后执行。

11 自学习机制（闭环优化）

设计目标：规则覆盖不到的问题，经人工介入成功完成后，沉淀为可复用方法论；同类复发则升级为新规则或优化旧规则。 治理红线：AI 只做"辅助推断 + 方法论总结 + 记账"，升级为正式规则须人员确认，不得静默固化。

• 触发：人工在 t_pending 成功裁决且 R1–R7 未明确覆盖，或 AI 建议值被人员推翻/修正，或解析出现规则外技术坑。
• 闭环七步：捕获 → 判是否规则外 → 提炼方法论 → 查重 → 落库 → 升级判定 → 人员确认固化。完整 SOP 见 references/learning_loop.md。
• 学习库 references/learnings.md：每条含 category / trigger / reason / decision / methodology / applies_when / related_rule / status / recurrence 等字段；已用真实历史播种 4 条。
• 辅助脚本 scripts/learn.py：list / next-id / bump(复发+1，达阈值提示升级) / promote(升级为 Rn，写 rules.md 并标记 promoted，支持 --dry-run)。
• 升级门槛：复发计数 ≥3（或人员显式要求固化）且方法论稳定不与 R1–R7 冲突；编号从 R8 起顺延（R7 已为用户直接指令的正式规则）；若实为修正旧规则则改写该条不新增编号。升级须人员确认。

附录 A（规范性） 字段与命名规则

• 字段顺序：项目代号_阶段代码_文档类别_成文日期_版本号_专业分系统_密级.扩展名
• 分隔符：下划线 _（避免与代号内连字符 FQN-360 冲突）。
• 日期格式：%Y%m%d（8 位）；版本格式：V{major}.{minor}（如 V1.0、V1.2）。
• 必填：项目代号 / 阶段代码 / 文档类别 / 成文日期（缺失即进闸口）；subsys 可选（无则省略该段），密级为末位字段便于权限过滤。
• 示例：FQN-360_S2_方案设计报告_20260811_V1.2_光机结构_内部.docx
• 各字段类型、取值区间、缺省来源与闸口原因详见 references/doc_spec_full.md。

附录 B（资料性） 修订记录

• v1.0（初版）：合并原 pm-registry / pm-intake / pm-archive 三个子 Skill；沉淀并固化 R1–R6、冲突处理、去重阈值、涉密拦截、人工闸口决策表（经真实文档验证）。
• v1.1：新增 R7 项目代号由人工界定（含 onboarding 与新建项目检测）；新增自学习闭环机制（learnings.md + learning_loop.md + learn.py，同类复发达阈值升级为 Rn）；修正关键坑位（文件修改时间绝不静默充当成文日期、.doc 用 olefile 直解、头表拼段只取本行首 token、Unix 时间戳统一规整 YYYYMMDD）。
• v1.2（本轮）：按 GJB 0.3-2001 章条体例规整本文件——补"规范性引用文件""术语和定义"两章；章条编号统一为阿拉伯数字章 + x.y 条；将原"v1 自查"历史叙述重构为附录 B 修订记录；补全 R7 概要于第 6 章使 SKILL 本体自洽；修正 flow.md 步骤重复编号；dict.md / rules.md 增加 GJB 体例参照说明。