Doc Prep Filter

目标

先过滤，再交接。

当输入里同时包含需求文档、Issue、Confluence、Jira、聊天记录、页面截图或设计图时，先把内容拆进四个桶：

constraints
pageCopy
sensitive
outOfScope

只有有效内容允许流入后续任务输入。

契约来源

如果当前工作区存在 ../spec-analysis-playbook/schema.md，则：

review-spec.md 的结构以该文件为准
reviewGate 的状态语义以该文件为准
runtime-spec.yaml 与 review-spec.md 的字段映射以该文件为准

本 Skill 只负责：

四分桶定义
runtime-spec.yaml 的兼容结构
runtime 校验与输出扫描

何时使用

在以下场景优先使用本 skill：

用户要求先读取需求文档、Confluence、Jira、聊天记录或截图，再提炼可执行内容
用户要求在拆开发任务、写实现方案、调用其他 Agent 或 Skill 之前，先过滤规则、文案、敏感信息和非本端范围
用户要求把原始材料整理成 review-spec.md 和 runtime-spec.yaml，供后续任务继续消费

核心原则

第一输出必须先给 review-spec.md，确认后再压缩出 runtime-spec.yaml。
任何输入句子都必须先归桶，再决定是否允许进入后续任务。
只有 pageCopy 允许进入：
- 页面文案提炼
- 页面结构草案
- 前端实现输入
- 其他 Agent 或 Skill 的 runtime 输入
constraints、sensitive、outOfScope 不得直接出现在后续任务的可见文案或实现内容中。
无法明确归桶时，默认严格阻断，先提问。

输入源规则

文档与图片都可以提供上下文。
涉及页面文案冲突时，文档优先，图片只作参考。
图片不能绕过四分桶流程。
图片里看到的文案如果未被文档确认，也必须先进入分类，不得直接落到页面。

四分桶定义

`constraints`

放“约束 AI 如何做”的规则，例如：

仅允许选择一个对比包
不要扩展这个字段范围
这里只能保留一个按钮

`pageCopy`

放“本来就应该给最终用户看到”的文案，例如：

页面标题
说明文案
表单标签
错误提示

`sensitive`

放任何不能进入页面或代码可见输出的敏感信息，例如：

secret
token
API key
测试环境 key
环境地址
联调参数

`outOfScope`

放不属于当前页面/前端发挥范围的内容，例如：

由后端处理
服务端校验逻辑
内部流程说明

标准工作流

第一步：先建立 `review-spec.md`

先产出审阅态 Markdown，而不是直接写页面或代码。

要求：

审阅态以“人看得快”为第一目标
可以保留来源、判定理由、冲突说明
只要有歧义，就先停在 review 阶段，不进入 runtime
如果当前工作区存在 ../spec-analysis-playbook/schema.md，按其 review-spec.md 契约执行

第二步：review 后压缩成 `runtime-spec.yaml`

确认后，再生成给后续 Agent 和脚本使用的精简版 YAML：

constraints:
  - "仅允许选择一个对比包"
pageCopy:
  page.title: "选择对比包"
sensitive:
  - "sk-xxxx"
outOfScope:
  - "由后端进行处理，这里不是前端的发挥内容"

要求：

顶层只允许这 4 个键
constraints、sensitive、outOfScope 用字符串列表
pageCopy 用 target: text 的映射
runtime 只保留执行必需信息，不保留 source、reason、owner
pageCopy 当前是兼容名，语义上表示“允许下传的用户可见文案”

第三步：校验 runtime spec

如果可以运行本地脚本，优先执行：

node "<skill-dir>/scripts/validate-spec.mjs" "<runtime-spec-path>"

校验失败时，不要继续构建开发任务；先修正 spec。

第四步：把 runtime spec 交给下游任务

继续拆开发任务、写实现方案、调用其他 Agent/Skill 或生成前端代码时：

只能使用 pageCopy
可以参考 constraints 约束任务边界和实现方向
不得把 constraints 原文写到页面、方案或任务描述里
不得把 sensitive 原文或变体带入任何后续输出
不得把 outOfScope 写成前端文案、前端 TODO 或错误的任务范围

第五步：扫描最终输出

如果可以运行本地脚本，优先执行：

node "<skill-dir>/scripts/scan-output.mjs" --spec "<runtime-spec-path>" --input "<output-path>"

若脚本报告阻断项，先移除风险内容，再交给下游任务继续。

默认提问规则

遇到以下情况必须先提问：

一句话同时像约束又像页面文案
图片文案与文档文案冲突
某段内容像环境配置，但不确定是否允许公开展示
某段内容提到后端职责，但又看起来像页面说明

不要在这些场景下自行猜测。

禁止事项

不要跳过 review-spec.md 和 runtime-spec.yaml 直接开始拆任务或产出代码
不要把需求备注、评审意见、开发者说明直接当成下游任务输入
不要把 secret、token、key、环境地址、联调参数带进后续方案、任务描述或示例代码
不要把“由后端处理”“这里只是约束规则”之类句子直接变成页面文案或实现要求

输出格式建议

当用户要求先清洗输入、再继续后续任务时，按这个顺序输出：

review-spec.md
runtime-spec.yaml
简短结论：哪些内容可进入后续任务，哪些被阻断
再交给其他 Agent、Skill 或实现步骤继续处理

关于 review-spec.md 的完整 section、reviewGate 规则和 review/runtime 映射，请直接参考 ../spec-analysis-playbook/schema.md，不要在这里重新定义第二套契约。

失败回退

如果当前环境不能运行脚本：

仍然必须先生成 review-spec.md 和 runtime-spec.yaml
按本 skill 的规则手动自检
明确告诉用户此次未执行脚本校验

参考文件

详细判定规则见 reference.md
正反例见 examples.md
安装与复用见 README.md

doc-prep-filter