ZFCC 工作台构建器

概述

把四个已建成工作台（专家证人／仲裁／法条检索／律师管理）沉淀出的工程流程（现已合并入统一内部库「ZFCC工作台」），固化为一套可复用的施工手册：立项骨架 → 内容回填 → 构建升级 → 质检 → 多环境适配 → 发布归档。本技能只装可复用的工程与治理流程，不装一次性内容（具体法条、文书正文、模板正文留在各自知识库）。

先读 references/deliverable-paradigm.md 明确"要交付成什么样"，再按下面的阶段推进。

何时使用

工作台与视角路由

先判断「做哪台、以什么身份」，再进对应流程；双视角工作台必须显式路由，禁止混用。

六条铁律

施工中不可违背，否则工作台在受限环境会打不开或泄漏内部信息：

1. 单文件离线：CSS/JS 全部内联，零外部依赖。logo 用内联 SVG 或 base64；字体用系统字体栈（-apple-system, "Microsoft YaHei", sans-serif）。任何 http(s):// 外链在离线/受限 WebView 中都会失效。
2. 唯一锚点注入：升级一律用 scripts/build_patch.py 以唯一字符串锚点打补丁产出新文件，绝不在成品上手工大改。锚点必须唯一——JS 文案极易撞锚点，打补丁后要复查。
3. 每轮升级必过自检：scripts/structural_check.py + scripts/selfcheck_jsdom.js 双通过（0 JS 错误且逐功能验证）才可发布。
4. 先传后改：平台对重名上传会自动追加时间戳，故"覆盖同名正本"须先上传、后重命名旧版归档；upload_file.py --rename 也无法绕过重名检测。
5. 攒批、一次成型：同一轮的零散微调攒到一起，一次性产出后对外发布，避免连发多个中间版本。
6. 来源可溯、不编造：法条/判例/裁判观点一律取自知识库原文（fetch 取 media_id），核对时效；确无权威来源的不收录并如实说明。检索类工作台须附合规声明。

轻量模式（Lite Path）

小台 / 单人工具无需走全六阶段，三步即可：

1. 起骨架：复制 assets/workbench-skeleton.html，改页头品牌 + 页签 + 内容。
2. 回填：内容直接内联（fetch 取原文，zh/en 成对）。
3. 过门：structural_check.py（结构/配平/favicon/打印/ARIA）+ selfcheck_jsdom.js（0 错误）通过即交付。

适用：单/少页签、无模板库、无多法域矩阵的小工具。需模板库 / 多法域 / 发布订阅库时走完整六阶段。轻量模式同样受「六条铁律 + 红线」约束。

工作流程

Phase 0 · 立项与骨架

明确四件事并让知府大人确认：维度（法域/卷/主题）、模块清单、语言（英/中/双语）、知识库归属（内部正本库 + 是否对订阅库发布）。

> 知识库归属（2026-10-24 平台升级后）：四个工作台合并入统一内部正本库「ZFCC工作台」（kb_id 见内部运维文档，不对外披露），按工作台分 4 个顶层 folder（仲裁员 / 专家证人 / 法条检索 / 律师）；对外发布走订阅库（双轨·脱敏，不并入内部大库）。技能自身存档库为「ZFCC技能库」，其目录镜像 skill 结构（references / scripts / assets / 历史版本 / 技能待优化清单）。原三源库已合并清空，仅剩空文件夹壳，规范引用一律指向「ZFCC工作台」。

• 用 assets/workbench-skeleton.html 起骨架——它已内置品牌页头、语言切换、页签、页脚、弹窗与手动复制区。
• 设计模块矩阵（模块 × 法域/卷）：编号须自洽——行号连续，跨法域的通用模块（模板库/工具箱）不参与编号（这是专家证人台升级时踩过的坑）。
• 确认门 ①：矩阵与命名请知府大人确认后，再进入内容回填。

Phase 1 · 内容回填

• 所有素材（研究稿、正文、模板）先落盘到 /sandbox/workspace/，再进 HTML。
• 内容取自知识库原文（fetch media_id），页内标注来源与数据时间。
• 量大时可派子代理并行回填，但主线内容由主 Agent 把关。

Phase 2 · 构建与升级

• 新建：基于骨架内联全部内容；zh/en 两份对称（body.lang-zh / body.lang-en，逐条 .zh/.en 成对）。
• 升级：复制旧版为基线，用 scripts/build_patch.py 打补丁：
  bash python3 scripts/build_patch.py --in v4.5.html --out v4.6.html --patch patches.json
patches.json 每项 {"anchor","replace","count","mode"}；脚本先核验锚点出现次数与 count 一致再替换，防误注入。
• 重大改版（增删模块／四通道引擎注入／全文改名／bulk 变换等，锚点补丁难覆盖）：可写构建脚本（如 scripts/build_v2.py）一次成型——内部仍按唯一锚点＋计数校验做替换（复用 build_patch 的 replace/count 语义），bulk 操作（剥 data-page-node-id、内嵌 base64/JSON 等）用受控 regex／定点注入。补丁型微调用 build_patch.py；重构型大改用构建脚本。殊途同归：产出后一律必过 Phase 3 双检（structural_check + selfcheck_jsdom 0 错）方可放行。
• 版本号 +1（_v主.次），旧版文件保留待归档。

Phase 3 · 质检（必过门）

python3 scripts/structural_check.py out.html      # 结构：zh/en 配平、标签平衡、表单键覆盖、无 TODO、模板编号唯一（实体口径）、版本号一致
#   ↑「版本号六处一致」的适用条件见 references/error-playbook.md §4.1：有 WORKBENCH.version 的台比六处；
#     无 JS 版本对象的台只比文件名/title/页头 .ver/页脚 zh/en 五处，缺 WORKBENCH 不报 FAIL（记 SKIP 并说明口径）
NODE_PATH=/tmp/node_modules node scripts/selfcheck_jsdom.js out.html   # 运行时：0 错误 + 功能验证
node scripts/checks/js_syntax_check.js out.html   # JS 语法：内联 <script> 逐段 node --check（#9 必过）
node scripts/checks/brand_check.js out.html        # 品牌六件 MUST（缺一不得发布）
node scripts/checks/bilingual_check.js out.html --strict   # 双语格式同步（MUST·必过，格式走通用选择器）
node scripts/checks/dead_css_check.js out.html     # 废弃选择器残留（重构后旧类；--strict 严格、--json 出清单）
node scripts/checks/i18n_check.js out.html --strict # 双语内容反向排除（MUST·双语台）：五类维度扫 CJK 残留
node scripts/checks/csv_check.js out.html          # CSV 契约（BOM/CRLF/引号/注入防护/数值裸输出）
node scripts/checks/export_all.js out.html         # 全量导出探针（逐模板证明都能导出 + key 分流）

• JS 语法校验为必检步：多轮 patch 后正则易出现双反斜杠（\\[）→ Invalid regular expression: missing /，structural/selfcheck 不一定直接指认，必须由 js_syntax_check.js 拦截。
• 首次用 jsdom 前：npm install jsdom（沙箱每轮重置，需重装）。
• 任一不通过 → 修复后重跑；通过才进入发布。
• 可选解析器版：scripts/structural_check_parse.py（html.parser 保底、html5lib 可选）做标签配对/嵌套检查，弥补正则对 JS 字符串中 < 的误判；html5lib 缺失自动降级。
• selfcheck_jsdom.js 会逐项验证：页签切换、语言切换、检索/筛选、表单弹窗、查看弹窗、手动复制、localStorage 持久化。
• 受限环境专项必测：模拟 navigator.clipboard / execCommand('copy') 失败 → 手动复制区（#manualMask）弹出并填入文本；二维码缩略图 #qrThumb 点击 → #qrModal 打开（见 multi-env-channels.md）。选择器自动探测（兼容不同类名如 .panel/[id^=tab-]），Not implemented 类 jsdom 告警（如 scrollTo）不计入 JS 错误。

Phase 4 · 多环境适配

见 references/multi-env-channels.md。三环境（桌面浏览器 / WorkBuddy / IMA）+ 四取用通道，按环境能力逐级降级。新增功能后必须回到三个环境验证一遍。

Phase 5 · 发布与归档

见 references/publish-governance.md（版本命名/历史夹/脱敏/对外口径）与 references/kb-archiving.md（文件夹编号/重名处理/live media_id）。
- 内部正本与对外 ZFCC_ 件双轨，内容一致、脱敏口径不同。
- 先传后改；旧版加「（历史版本 vX.Y）」移历史夹。
- 确认门 ②：对外发布前请知府大人确认。
- 交付说明五要素：路径 / 已验项 / 未验项(missing evidence) / 离线边界 / 版本号（见 references/evidence-ledger.md）；未实测项不得写作「已验证」。

⛔ 确认门（三处，必须停下等确认）

铁规：输出确认项的那一轮回复必须停止，禁止同轮继续生成、写入或发布（参照 ima-ppt 确认门做法）；用户明确说「不用确认 / 直接做」方可跳过，但仍须在回复中输出确认项供事后查看。

工作台红线清单（不可逾越）

设计与施工纪律（借鉴 ima-ppt）

A. 设计语言先决（开工定调，禁止随手写）

动工前先定 Visual Anchor 风格，从下列选一（或自提）：庄重徽章型 / 瑞士极简 / 编辑杂志 / 禅意留白 / 奢侈精工。

• 配色（60-30-10 法则）：60% 背景 / 30% 正文 / 10% 强调；蓝金、藏青+香槟金等体系化配色，全台统一。
• 字体：系统字体栈（-apple-system, "Microsoft YaHei", sans-serif）；标题/正文分字号与字重，不用外链字体。
• 版式：相邻页签 / 分区布局交替变化，避免单调；每屏 10 秒内可抓核心（Clarity）。

B. 多文件命名与防覆盖纪律

• 有模块体系时以「模块-序号」为主（如 M1-01／C6-01），文件名 <编号>_<中文名>_<English>.<ext>，编号贯穿四处（模板库表/面板/本地文件/KB 条目）；前缀_XX 仅作兜底，避免被误判违规改名。
• 多文件（模板 / 文档矩阵）统一 前缀_XX.ext（下划线+两位数字），可按序号稳定排序与组装。
• 新增 / 插入 / 删除 / 移动文件：先写临时名 → 倒序重编号 → 再改名占位；禁止正序重编号（会连锁覆盖）。有脚本优先用脚本。
• 编辑只改要求部分、其余保持；改前先读 2–3 个既有样本提取当前规范，防风格漂移。

C. 规模上限

• 单文件 2MB+ 属正常（内嵌模板 / 预渲染），不是缺陷。
• 模板 / 页签数量与内嵌体积设上限，超限拆分为多工作台或多文件，勿硬塞单文件。
• 参照 ima-ppt：同类批量转换单批 ≤100 单位，超则拆目录分批。

施工坑速查（开工必读）

高频翻车点（完整版见 references/build-pitfalls.md）：

1. 不用 file_edit 改大脚本（>30KB 会静默不写盘/尾部残片）→ python 定点替换 + assert 计数。
2. CSS 类名不带反斜杠（\b 是 CSS 十六进制转义，选择器会坏）；JS 字符串换行写 \\n；锚点匹配前先 repr() 看层数。
3. 内嵌 JSON 的 < 全转 \u003c；form:"key" 需无引号登记表（TPLMAP）才能过键覆盖检查。
4. jsdom 每轮重装；复杂断言写成 .js 文件；init 用「立即执行 + 幂等」；只有「语言切换」断言能证明脚本真的跑了。
5. 视觉缺陷 jsdom 测不出：列宽/行高靠结构断言（同表行数列数一致、单格行 colspan=总列数）+ 人工复核。
6. KB 不收 zip；upload_file 输出是文本（grep upload success）；移动用 move_knowledge（同库 + dst_folder_id，分批 ≤10）后 rename。

视觉 QA 与图示（发布前复核）

A. 视觉 QA 清单（jsdom 测不出，发布前必人工过一遍）

> 自动化：scripts/visual_audit.js（Playwright 截图桌面+移动视口 + axe WCAG，可选；缺 Playwright 自动 SKIP，须把 browser visual review 记入 missing evidence）。

B. 图表与外挂图示（可选，仍守零外链）

• 需架构图 / 流程图 / 时序图时，用官方 diagram-generator（Mermaid / drawio / Excalidraw）生成，导出内联 SVG 或 base64 嵌入 HTML；禁止外链图片。
• Mermaid 优先（文本可版本化、易改）；drawio 适合复杂架构图。
• 图示放页内「模块说明 / 结构」处，标注来源与更新日。

资源目录

• scripts/（可直接执行，无需加载；分类分层见 scripts/README.md——engine/pipeline/legacy 为只读镜像、权威在根）
• build_patch.py —— 唯一锚点补丁注入器
• selfcheck_jsdom.js —— 运行时自检（0 错误 + 功能验证）
• structural_check.py —— 结构自检（配平/平衡/键覆盖/TODO）
• publish_promote.py —— 上传 → 归档（先传后改）引导器
• re_extract.py —— 填空引擎构建链①·源文件单元格换行合并
• fill_preproc.py —— 填空引擎构建链②·占位标准化→fill
• build_v2.py —— 填空引擎构建链③·JS 渲染/生成（表单填写通道）
• fix3.py —— 填空引擎构建链④·脱敏
• vformcheck.js —— 填空引擎构建链⑤·表单填写通道校验（jsdom）
• checks/print_check.js —— 打印专项（@media print / 容器层级隐藏 / 弹窗级打印+持久状态类）
• checks/copy_check.js —— 复制专项（helper / #manualMask 行为 / selectRaw）
• checks/qr_check.js —— 二维码专项（#qrThumb→弹窗→大图 src 继承）
• checks/export_check.js —— 导出专项（xlsx / docx 双容器各测一份（按 key 取首个、不支持时经 openForm 兜底）→ 批注四件套 / rIdVml / openpyxl 无公式 / 批注三分法·语种一致·原文条数=data-f·修正标记）
• checks/js_syntax_check.js —— JS 语法专项（内联 <script> 逐段 node --check，拦正则双反斜杠坑）
• checks/table_check.js —— 表格编辑器专项（列宽可调 / 行高示意列 / 增删行 / 打印 DOM 级移除 / resize:none / 表头可编辑；静态无表时自动 openForm 动态补扫，仍无则记 missing evidence）
• checks/data_check.js —— 数据层专项（先判台型：检索/参考型（无记录增删改/导入入口/审计）→ 豁免 SKIP；业务台账型 → 严判 persist 兜底 / JSON 备份 / schema / 导入校验 / 审计 / 容量边界；轻量持久化型记 WARN）
• checks/brand_check.js —— 品牌六件 MUST（徽章四字两行 / 双语分段 / LOGO 内联 / 二维码通道 / 页眉品牌块 / 页脚品牌介绍固定文案 / 免责+版权）
• checks/bilingual_check.js —— 双语格式同步（单语 .zh/.en 上的外观属性 = 违规；显隐规则只准 display/visibility/opacity；--strict FAIL、--runtime 用 jsdom 比对计算样式）
• checks/i18n_check.js —— 双语内容反向排除（切 EN 后除两项白名单外不得有 CJK；TreeWalker 文本节点 + placeholder/title/aria-label/value/option 五类；自动打开弹窗；--strict FAIL）
• checks/csv_check.js —— CSV 契约（BOM / CRLF / 引号包裹 / 公式注入防护 / 数值裸输出 / 负数不误伤 / 无脏值）
• checks/export_all.js —— 全量导出探针（遍历全部模板逐个 probe：字节量 / 扩展名 / 文件名日期 / 生成时间 / key 分流校验）
• checks/dead_css_check.js —— 废弃 CSS 残留（选择器 0 命中且类名仅存在于 CSS 定义处 → 废弃；自动 openForm 动态复核；不自动剥离，出清单人工删）
• references/（按需读取；每条标注 = 读取时机 / 约 token / 必读性）
• build-pitfalls.md —— 构建与工具坑（开工必读，~3k）
• evidence-ledger.md —— 验证凭据台账（交付必读，~0.6k）
• deliverable-paradigm.md —— 交付范式（立项/交付读，~1k）
• structure-and-nav.md —— 结构与内容组织（结构设计读，~1.3k）
• multi-env-channels.md —— 四通道与环境降级（适配读，~1.3k）
• publish-governance.md —— 版本与发布治理（发布读，~0.9k）
• publish-adapters.md —— 发布适配器 local/kb/manual（发布读，~0.6k）
• form-fill-engine.md —— 模板库填空引擎（做填空读，~1.6k）
• table-fill.md —— 表格填空引擎规范（做填空读，~0.5k）
• export-engine.md —— 填写结果原格式导出（xlsx/docx 保格式·公式批注 comments/VML·原文优先·引用校验·批注三分法·CSV 三件套 BOM/CRLF/公式注入防护·零库 ZIP+OOXML·LibreOffice 抽查，做导出读，~4.5k）
• data-workbench-paradigm.md —— 台账型工作台范式（数据模型·持久化·备份与导入校验·审计·时限引擎·完整性评分·迁移边界，做台账型读，~2.5k）
• regime-onboarding.md —— 合同体系纳入 SOP（十步：定位原文→确认条款位置→提取参数→认定逾期性质→节点建模→模板判据→六处联动→三类计数断言→文档归档→常见坑；新增体系必读，~3k）
• kb-archiving.md —— 知识库归档规范（归档读，~1.1k）
• error-playbook.md —— 错误手册（遇错必查，~1k）
• skill-optimization-queue.md —— 待优化清单 SOP（汇总清单读，~0.7k）
• i18n-audit.md —— 双语内容审计·反向排除法（五类维度 + 弹窗 + 数据层双语 + 常见坑；双语台必读，~1.5k）
• compute-engine.md —— 计算引擎型范式（三重验证法 + 回归基线 + 典型坑：LF 越界/SS-FF 松弛/日期口径；含计算必读，~1.4k）
• link-ledger.md —— 外部链接台账（状态五分法 / 403≠有效 / 实测脚本 / 交付三数，~1.1k）
• print-pdf.md —— 打印版 PDF 生成链与局限（LibreOffice 忽略列宽 / 交付口径，~1k）
• dual-version-reconciling.md —— 双版本数据源（学习轴 vs 导航轴 + 映射表，~0.7k）
• assets/
• workbench-skeleton.html —— 品牌骨架（双击可用，已被自检脚本约定选择器对齐）
• brand-pieces.md —— 品牌片段库（favicon / 页眉 / 页脚 / 二维码四件，直接复制）
• ui-snippets.md —— 渲染组件片段（E 转义 / heading / btn / badge / empty / table / stat / 事件委托）
• doc-kit.md —— 交付文档四件套骨架（使用说明 / 验收说明 / 依据核验笔记 / 模板目录）
• ZFCC_Logo_160.png / ZFCC_QR_480.png —— 品牌件压缩成品（LOGO 16KB、二维码 46KB，直接内联）
• subagent-i18n-contract.md —— 子代理·双语翻译产出契约（JSON 结构 / 同序同长 / 术语照抄 / 无 CJK 校验）
• subagent-extract-contract.md —— 子代理·内容抽取产出契约（schema / 防编造红线 / 大文件禁用 file_edit）
• eval/（L2 技能门，评测集 v0.1）
• README.md —— 评测集（20 用例：静态 S01–S05 / 行为 E01–E14 / 端到端 E2E-01，含通过线与已知缺口表）
• baseline.md / results/ / cases/ —— 基线、运行留痕、样例素材
• E2E-01-runbook.md —— 季度全链路评测运行手册（含记录表与判定标准）

规范速查

1. 主交付＝单文件离线 HTML（内联·零外链·双击即用）＋文档矩阵包（分册/手册·模板·指南·总览）；对外件加 ZFCC_ 前缀置订阅库根目录。
2. 结构＝页头品牌＋中英切换＋页签导航＋双维导航（法域/卷×专业/主题）＋对照矩阵＋模板库表＋来源页＋页脚；矩阵编号自洽；来源与时间页内标注。
3. 构建＝唯一锚点补丁；质检＝jsdom 0 错误 + 结构校验。
4. 取用＝四通道按环境降级：内嵌直出 → 页内「查看」→ 表单填写（填空引擎：占位标准化＋勾选/加行/跨列合并＋占位替换生成，见 form-fill-engine.md）→ 手动复制区＋全选。
5. 版本＝_v主.次；当前版无标记、旧版标「（历史版本 vX.Y）」移历史夹；攒批一次成型。
6. 归档＝文件夹统一编号；重名先传后改；编辑前查 live media_id。
7. 合规＝取自 KB 原文、核对时效、不编造、检索台附免责声明。

命名与视角规则（系列化 · 知府大人 2026-10-14 确认，永久有效）

1. 工作台名称系列化：法律类工作台统一用「法律工作台-XXX / Legal Workbench — XXX」系列命名（如「法律工作台-仲裁员」「法律工作台-专家证人」「法律工作台-律师管理」）。文件名下划线形 Legal_Workbench_XXX。不同专业（仲裁员/律师/专家证人…）各建一台，勿混装。
2. 保留双视角（仲裁类工作台）：仲裁工作台一律保留双视角 🛠 担任仲裁员 ｜ ⚔️ 选任·管理·质疑仲裁员。理由——知府大人兼 CLO（代理时处原告/被告相对方 → 需 ⚔️ 选任/管理/质疑仲裁员），同时具仲裁员资格（→ 🛠 担任仲裁员），故两视角都在高频使用，不得删减为单视角。
3. 依此「法律工作台-仲裁员」由原「仲裁案件工作台」改造而来：去除「律师管理」模块（另立「法律工作台-律师管理」台）、聚焦仲裁员主题、升 v2.0.0（结构性改版＝主版本+1）。

工作流示例

示例 1 · 新建一个双卷工作台
1. Phase 0：定维度（中国卷/国际卷）、模块、双语 → 确认矩阵。
2. 复制骨架，改页头品牌，按双卷铺页签与矩阵。
3. Phase 1：从知识库 fetch 正文与模板，落盘再内联。
4. Phase 2：内联全部内容，zh/en 成对。
5. Phase 3：structural_check.py 报"en 缺 3 条" → 补齐后 selfcheck_jsdom.js 通过。
6. Phase 5：publish_promote.py 上传内部正本；旧版归档；生成对外 ZFCC_ 件。

示例 2 · 升级既有工作台 vX.Y → vX.(Y+1)
1. Phase 2：build_patch.py --in vX.Y.html --out vX.Y+1.html --patch patches.json；若报"anchor not found（0≠1）"，说明锚点撞车或已打过，改写锚点。
2. Phase 3：jsdom 报 1 个 JS 错误 → 定位后重打补丁 → 0 错误。
3. Phase 5：publish_promote.py --file vX.Y+1.html --kb-id <内部库> --folder-id <工作台夹>；把旧版重命名为（历史版本 vX.Y）并移入历史夹；同步对外发布件。

维护约定（技能自更新 · 方案 C）

本技能由实际工作台升级过程喂养成长，不自造需求。约定如下：

• 就地捕获：任何工作台会话施工中发现本技能缺口时，只记录、不即改本体——避免打断升版主线，也避免碎片化改动。
• 集中落地：由 Agent 在每次工作台升级收尾主动输出「技能缺口清单」，经用户一句确认（"落地" / "攒着"）后，在任一会话集中修改（技能位于共享工作区，无需专属会话）。
• 四件套收尾：改 → 双检（selfcheck_jsdom.js / structural_check.py）→ 评测（eval/README.md 冒烟集；改脚本/SKILL 跑全量）→ ima_skill_create 重注册 → 同步知识库技能存档子夹。固定命令（禁止手搓 cp/ln）：
  bash bash /sandbox/workspace/skills/zfcc-workbench-builder/scripts/sync_to_rootskills.sh && ima_skill_create -d /sandbox/workspace/skills/zfcc-workbench-builder
• 攒批、一次成型：小缺口先攒，到阶段节点集中改一次，避免工具版本碎片化。
• 生效范围：注册更新对新加载生效；仍在运行的旧会话需重新加载技能方能用上新版。
• 防遗漏：跨会话维护一份「待优化清单」，任何会话发现的点都汇总进去。
• 落地单点（2026-10-18 定，红线）：只有「261014 工作台开发管理」（zfcc-workbench-builder）会话可修改 skill 本体；各工作台会话（专家证人 / 仲裁员 / 法条检索 / 律师）只产出并上传清单，不碰 skill 文件。理由：多会话并发改 skill 会互相覆盖——2026-10-18 律师台"已落地"的 #1–#6 被并发覆盖丢失，本次须重落。

> 为什么：技能是"施工工具"，应与工作台一起演进；集中改动 + 规范收尾，才能保证每次工作台会话加载到的技能版本一致且可用。