语义管理界面方案（第 1b 期）

状态：2026-10-08 第四版，用户已认可页面结构（更细的问题等有真实数据再看）；设计改动已并入设计文档，见第 8.3 节；2026-10-09 第 1b 期已按本方案实施，实施中改了四处，见下方「实施后修正」；2026-10-10、10-11 又按过流程决定 D1–D9、模板生成方案与关系提取规则改了页面，见下方「2026-10-11 同步」 · 上游：docs/alert-semantic-handoff.md 第 5 节第 1b 期、docs/ops-semantic-library.md 第 6 节（菜单）、docs/alert-semantic-design.md 第 4 节（数据模型） · 参照：aimp-platform packages/ui/src/views/code/（代码管理）、packages/ui/src/views/kb/（知识库管理）

本文定平台前端「语义管理」的页面结构和交互，供第 1b 期实施；第 8.2 节列出每个页面用到哪些 kb 接口（契约在设计文档第 7.7 节），第 8.3 节列出界面讨论带来的设计改动写在设计文档哪里。读者是确认方案的用户，以及第 1 期、第 1b 期的实施者。

示意图的数据来自共享算法包的虚构数据生成器（aimp-kb backend/app/semantic/alertalgo/synth.py，seed 7）：

生成器只产出一批约 2 小时的告警（2026-03-02 08:00:06 至 09:55:35，6 个监控系统）和一份语义库 JSON，库里 4 组模板规则已确认、1 组待确认。另外几个状态是把这份 JSON 改一处再重跑得到的，图注里写明改了什么：全部规则改成待确认（闸门流程第 4 步的状态）、加一组 L-DB 的规则。图中按设计补画、没有实测依据的内容标 示意：第二个运维语义库、L-DB 规则的提议本身、主机命名约定的待确认状态、谓词取值（算法包 1.0.0 还没有 predicate）、shared_version。第 1 期 kb 还没有接口，对象类型计数、候选与生效的划分、证据条数按设计规则从虚构数据推算，标 推算。

图 1 画整页，左侧是 224px 侧栏（aimpLayout.css 第 305 行 --aimp-sider-w）。其余各图只画内容区，宽 1216px，即 1440px 窗口减去侧栏。橙色虚线框是正文讨论的位置。

1. 要解决的问题

运维语义库由治理智能体写入规则，人确认后生效（设计第 4.1 节）。第 1b 期的界面要让下面三类操作在平台里完成：

1. 建库和配置：建运维语义库；配处理设置（时区、遮罩、范围过滤、监控系统取法等），保存即生效。
2. 确认规则：处理治理智能体提交的解析规则、列映射、语义约定、噪音、依赖候选，以及摄入时发现的冲突。确认前要能看到规则在样本上解析成什么、产出了哪些对象和关系、确认后会变什么。
3. 查看与排查：回答「这条告警为什么被解析成这样」「这台主机有哪些标识、上面运行哪些实例」「哪几个小时还没摄入」。

第 1b 期的闸门（交接第 5 节）是本地起平台和 kb，用虚构数据走通建库 → 上传 → 摄入 → 确认。治理智能体第 3 期才有，所以界面要自带三个设计里没写的入口：手工上传并摄入（4.12 节）、列映射编辑（4.10 节）、导入语义（4.3 节、第 5 节）。

2. 参照：平台里现有的两种做法

3. 结构决定

3.1 菜单与库的层级

数据上，运维语义库是容器：语义约定、谓词、待确认、告警主题都属于某一个库，一个企业可以建多个库（设计第 4.2 节）。界面要让这个层级看得见。

D 的好处：

• 库详情页标题就是库名，库内的东西都在它下面，层级看得见。
• 库 ID 在路径里，分享出去的链接指向确定的库，不需要切换器和「上次选的库」这套逻辑。
• 以后加指标主题，库详情多一个页签，菜单不变。
• 侧栏不用改：/sem/<库 ID>/… 以 /sem 开头，useShell.js 的 resolveSelection 取最长前缀，「语义管理」保持选中；isPathAllowed 同样按前缀放行。

只有一个库时也显示列表，不自动进库（用户 2026-10-08 确认）：建库、看各库的待确认数和基线天数都在列表上，自动跳转会让人找不到列表。

3.2 库内的组织

告警主题的 6 个视图里，「告警对象」排第一〔拟〕：进入告警主题先看到抽出了什么；负责治理的人日常从库内的「待确认」进去，用不到这个缺省页。

「告警对象」和「解析规则」看的是同一批数据的两面：解析规则从规则看产出，确认在这里做；告警对象从产出回看规则，回答「抽出来的对象和关系有哪些、来自哪些规则、和 CMDB 是否一致」。两边互相跳转。

3.3 在哪里确认

推荐 C。代码管理的业务解释是在列表里就地确认（ExplanationsPanel.jsx）；语义管理多一个汇总页，因为确认项分在 7 张表里。

4. 页面

4.1 运维语义库列表

列：名称（代号）、所属团队、主题、待确认数、最近摄入、基线天数、可见范围、状态。筛选：所属团队、状态、名称或代号搜索。点行或「进入」到库详情的概览与设置。

• 新建运维语义库对话框：代号（平台唯一，创建后不可改，规则同知识库代号）、名称、可见范围（缺省全部团队〔拟〕，设计第 4.2 节）、时区（缺省 +08:00）、主题（只有「告警」，勾选且不可取消）。建库同时建 tb_sem_topic 的告警行，建完直接进新库的概览与设置。
• 其他团队的库：名称旁标「只读」，不显示待确认数。
• 基线不满 7 个完整的天时标红：这时 RCA 不出依赖历史的判断（设计第 5.2 节）。
• 空状态：当前团队一个可见库都没有时显示「当前团队没有可见的运维语义库。一个企业一般建一个，告警、指标等主题都在同一个库里。」有新增权限时带「新建运维语义库」按钮。

4.2 库详情的框架

库详情页顶部固定三样：「← 运维语义库」返回链接；库名（代号）、所属团队标签、状态，别的团队的库再加「只读 · 属于 <团队>」；库内页签，「待确认」带数。页签切换改路径（3.2 节），刷新、分享都落在同一个页签上。告警主题页签下面再有一行按钮组切 6 个视图，「告警对象」视图右侧有「查对象或标识」搜索框。

4.3 概览与设置

内容从上到下：

1. 库信息：代号、名称、所属团队、可见范围、状态。按钮：编辑、停用。
2. 版本：shared_version，以及每个主题的 ruleset_version、algo_version。RCA 结果包和快照的 manifest.json 也记这三个数，结果对不上时拿来比。
3. 主题卡片：每个启用的主题一张。告警卡片给对象数（按生效、候选）、主机数、分组数（按规则状态）、最近一次摄入、基线天数、近 28 天的摄入覆盖。
4. 待确认合计：按种类的数，点进「待确认」页签。
5. 公共处理设置：时区、遮罩。告警自己的处理设置在告警主题的「设置」视图（4.13 节）。
6. 导入与导出：导出快照（设计第 7.5 节）；导入语义。

导入语义是本文新增的入口，有两个用处：第 1b 期闸门没有治理智能体，要靠它把 /tmp/aa/library.json 这种已有规则放进库（第 5 节）；设计第 2 节要求把 alerttx、rca_agent 里的客户写法迁到该客户的语义约定，也要一个导入入口。导入接受快照目录的打包或 library.json（算法包 --library 认的两种格式），分两种模式：「导入为待确认」（缺省，逐项进待确认页）和「导入并确认」（迁移已经审过的规则）。处理设置和对象类字段的默认推断不走确认（4.10 节），导入时直接覆盖，覆盖前列出新旧差异。

遮罩的时间差：样本在摄入时遮罩后入库（设计第 4.3 节），新加一条遮罩规则，之前入库的样本不受影响。推荐保存遮罩时让 kb 对已存样本再遮一遍：已遮罩的文本再遮只会多遮，不会还原原文。【待确认：用户、kb 第 1 期实施者】

4.4 待确认

本库各主题的待确认项。一个页签一个种类，页签标题带待确认数。筛选：主题（全部、共享、告警）、状态（缺省待确认，可切已确认、已驳回、全部）。排序：漂移的解析规则排最前，其余按提交时间从早到晚。漂移表示已确认的规则在新数据上命中率下降，当前的 RCA 正在用它。

冲突只在生效的行之间算：两条已确认规则把同一个标识指向两个对象，或同一个实例挂在两台主机上。候选和生效说法不一致不算冲突，它会出现在相关解析规则的预览里，确认那条规则时处理。

4.5 语义约定

语义约定是客户环境的写法词典，回答「这个写法指什么」，不回答「从哪里取」。它解决两件事（ops-semantic-library 第 3.3 节）：

• 身份（标识规则）：同一个东西在客户环境里有几种写法，要知道它们指同一个对象。一台主机有业务网、管理网两个 IP；错误码 GW-E-1001-SETTLE 的最后一段是系统代号；SETTLE 就是清算系统；主机名 pay-app-01 里编码了系统。
• 词汇（术语）：客户环境自己的说法是什么意思。「通讯中断」属于「连接失败」；本环境的错误码长这样，归一化时整段保留。

和解析规则的分界：解析规则说位置（在某个模板的告警里，哪一列、哪段文字是什么），约定说含义（一个写法本身指什么，不管出现在哪）。判断标准：换一个模板、换一个主题（以后的指标标签、日志、链路）还成立的，是约定；不成立的，写进那个模板的解析规则。以 L-GWSET 为例：规则只说「目标取 errorCode= 后面那串，目标类型是错误码」；约定说「XX-E-数字-代号 的最后一段是系统代号」「SETTLE 是清算系统」。以后日志主题里出现同一个错误码，用同一条约定，不再确认一次。所以约定整库一份、各主题共用、必须人确认：录错一条，所有用它的解析都错。

约定里一半是对照表（系统别名、IP 规划的网段对、服务地址指向系统、近义词），一半是写法规律（主机命名、错误码格式、错误码指向系统）。写法规律要用正则表达，但它解析的是一个标识，不是一条告警。界面上一律先给「写法 → 指什么」，正则放进抽屉的「规则细节」。

标识规则是 CMDB 缺失时的替代：ops-semantic-library 第 3.2 节把主机命名、IP 规划列为纵向关系的推断来源，CMDB 是事实源。接入 CMDB 以后，IP 规划、系统别名这类约定拿 CMDB 核对，不一致时以 CMDB 为准。

列表列：种类、名称、写法 → 指什么（用本库出现过的真实写法举例）、谁用它、影响、状态。「影响」是这条约定在最近一批数据上改变了什么，kb 按「去掉这条重算一次」得到；为 0 的照样列出，看得出它现在没起作用。抽屉：写法 → 指什么的试算、谁用它、确认或撤销后的变化、依据、规则细节（正则、去前缀、大小写）、历史。人工新建约定有两个保存按钮：「保存为待确认」「保存并确认」。

图 4 的「影响」一列说明了三件事：

• 影响为 0 的约定也有用，但现在没起作用。主机命名和「支付系统」别名去掉以后结果完全不变：本库的系统取自 biz_sys 列，没有规则引用它们。确认这种约定不改变当下的结果，人可以据此决定先确认还是先放着。
• 约定会串起来用。GW-E-1001-SETTLE 对到清算系统要两条约定：「错误码指向系统」取出 SETTLE，「系统别名」把 SETTLE 对到清算系统。去掉任一条，这 10 条的调用目标都变成未解析；清算系统在这批数据里没有一条告警，只靠这条引用出现，也会从结果里消失。抽屉的「谁用它」要列出这条链。
• 试算能挡住看起来对的约定。命名规范 6 个主机名都匹配；逐行看对到的系统，才发现 4 个代号没登记别名，其中 edge 根本不是系统。处理办法有两个：改正则让系统代号只在 app、db 角色上取，或者确认后给 gw、order 补系统别名。

4.6 谓词

列表列：域、谓词键、名称、适用对象类型、量化格式、状态、引用（已确认解析规则里用到它的组数）。首版 12 个谓词照 ops-semantic-library 第 3.5 节，第 1 期迁移时以已确认状态写入每个新建的库：这份清单由用户在该文档里确认（目前待确认），不在界面上逐条确认，所以闸门流程的待确认页里没有这 12 条。

• 新增：人填写域、谓词键、名称、适用对象类型（从对象类型表多选）、量化格式。保存后进「待确认」的谓词一类。治理智能体不能新增谓词，选不出时只能写 unclassified。
• 停用：被引用的谓词不能删除，只能停用。停用后治理智能体不能再选它，已确认的解析规则保留原值，列表显示「引用 N（已停用）」。
• unclassified 是保留值，不是表里的一行。
• 确认、停用都让 shared_version 加 1。

谓词页签不画示意图：只有一张表和一个新增对话框，和语义约定的列表同一个形态。

4.7 告警主题 · 告警对象

告警对象是告警主题最重要的产出：RCA 的语义切片、lookup 查上下游都用它，以后的 CMDB 对账也按它做。有些问题只能从对象这一侧回答：库里一共有多少台主机、某个系统下有哪些对象、哪些对象还只是候选、哪些对象没有任何监控系统覆盖（没有 observed_by）。所以它单独成一个视图，并且是告警主题的缺省视图。

视图里用按钮组再切三样：

• 对象：列对象键、类型、所在主机、系统、状态（生效、候选）、来源分组、告警数、末次。筛选：类型（带计数的标签）、状态（缺省不含作废）、系统、监控系统，以及「查对象或标识」搜索框（按对象键或任一标识：主机名、IP、系统代号）。系统、监控系统、站点也是对象（设计第 4.7 节），缺省只显示告警直接针对的对象，其余点类型标签看。
• 关系：列类型、源、目标、状态、来源、证据条数、首末次。筛选：纵向或横向、关系类型、状态、来源。依赖候选（等人确认的 depends_on）和冲突也在这里能看到，点开是和待确认页同一个抽屉。
• 未解析目标：告警内容里提到、但对不上任何对象的目标，各分组汇总在一起。列文本、类型、条数、首末次、所在分组。动作三个：「新建约定」（预填为服务地址指向系统或系统别名）、「列为引用停用词」（写进告警设置的 ref_stopwords，即时生效）、「忽略」。不提供把目标直接挂到某个对象上：标识的来源只有列映射、规则、约定、建议四种（设计第 4.7 节 basis），人工挂接没有对应的来源。解析规则抽屉里仍按本组列出。

页面固定一行说明：「这里的对象和关系是从告警推出来的。对象和纵向关系以 CMDB 为准，横向关系以链路为准。」（ops-semantic-library 第 3.2 节）。

点对象行或任何预览里的对象键，打开对象抽屉：标识、关系（出、入）、1–2 跳邻居，每一行带状态和全部来源，点来源跳到那条解析规则或约定。一个对象由多条规则共同产出，抽屉是看它全貌的地方：pay-app-01 的主机名来自列映射，第二个 IP 来自 IP 规划约定，挂在它上面的实例来自 A-HEAP，报告调用它失败的关系来自 L-GWPAY、L-ORDPAY。

CMDB 对账以后放在这里。统一对象和对照表属于以后的对象主题，不归告警主题（ops-semantic-library 第 3.1 节），告警对象视图显示的是每个告警对象的对账结果，是联表展示：列表加「CMDB」列和筛选（已匹配、人已确认、冲突、未登记）；对象抽屉加「CMDB 对账」一块；筛「未登记」即「CMDB 未登记」清单，可以导出交给客户做 CMDB 治理。第 1b 期界面上不画这一列，免得出现一列永远是「未接入」。

4.8 告警主题 · 解析规则

一行一个分组。每组的解析规则由三部分合成：从列映射默认推断继承的字段、本模板自己的规则（设计里模板语义的 fields、classify、relations）、引用到的语义约定。列表直接给出每组「对象从哪取、是什么类型、主机从哪取、推出什么纵向关系、横向关系怎么取」，不用点开就能对比各模板。

列与行为：

• 纵向（类型相关）只列随对象类型变的那一种：实例 → runs_on，线路 → terminates_at，容器 → hosted_by。belongs_to（系统）、observed_by（监控系统）、located_in（站点）每组都有，列表不重复，抽屉里列全。
• 规则四种：已确认、待确认、默认推断（没有规则，或规则被驳回）、漂移（已确认，但新数据上命中率下降，旁边显示「命中率 98% → 61%」这类变化，取自 tb_sem_alert_field_hits）。
• 标记：已确认的噪音、处理设置判为范围外、变体级范围外、未解析目标数。范围外只打标记不删除（数据标准 M3），这些分组照常列出。
• 点行打开解析规则抽屉，和待确认页是同一个（图 3）。抽屉分两部分：
  • 规则：一行一项（对象、对象类型、主机与 IP、系统与应用、纵向关系、横向关系、分类、说明），每行注明来自哪一层：列映射默认（灰色）、本模板、语义约定、推出。确认本规则即确认它继承的灰色部分：人在预览里看到了这些字段在本模板上的实际取值。
  • 预览：样本逐条（每条的对象、主机、系统、横向目标与解析结果、校验）；这一组的累积产出（按生效、候选分开，带证据条数，对象可点开对象抽屉）；确认后的变化。另有「样本」「变体」「统计」「历史」四个页签：遮罩后的原始各列，每组最早 3 条、最近 10 条、每个变体至少 1 条（设计第 4.3 节〔拟〕）；变体的骨架、条数、范围标记；近 35 天每天条数与字段命中率；各版本与撤销。

编辑、驳回、撤销

• 谓词必填。治理智能体选不出谓词时写 unclassified，由人确认时补（ops-semantic-library 第 3.5 节）。谓词是 unclassified 时「确认」置灰，提示「先选谓词」。
• 样本有失败时仍可确认，但要填说明，写进 decision_note。
• 编辑后确认：对象、对象类型、主机、分类做成表单；对象取法、横向关系、变体标记、致命条件用 JSON 编辑框，旁边列出六种写法（设计第 4.4 节）。改继承的灰色项，等于在本模板写一条覆盖。改完点「试算」，预览三块按改过的版本重算。保存的版本 edited=true。
• 驳回必须写原因，写进 decision_note。驳回后这一组继续按默认推断产出候选。
• 撤销已确认的版本在「历史」页签。撤销前列出会转回候选或作废的行数，并提示 ruleset_version 加 1。

确认会改对象键时：I-ORD 的例子

L-DB 确认前后对象键不变，确认只是把候选转成生效。有的规则会改掉默认推断出的对象。闸门流程第 4 步（第 5 节）全部规则还是待确认，实测默认推断产出了两个错的候选：

• I-ORD 的 host_name 列是 10.0.2.31:3306:orders，默认推断把它当成一台主机。
• N-LOSS 是专线 LINE-0007 的告警，默认推断把对象取成了网络设备 edge-rt-01。

图 8 是确认 I-ORD 之前它的抽屉。

4.9 候选与生效

用户 2026-10-08 确认：没有确认规则的分组也写入对象和关系，用状态区分。本节定这个状态怎么变，告警对象视图、解析规则预览、对象抽屉里的「候选」「生效」都按它显示。

1. 摄入只用已确认的规则。有已确认规则的分组按规则产出；没有的（含规则待确认、被驳回）按列映射的默认推断和通用抽取产出。待确认的规则不参与摄入，只在预览里试算。这样驳回一条规则时，库里没有它留下的东西要清。
2. 每一行记全部来源。对象、标识、关系各记「哪个分组、哪一版规则」或「哪条约定」产出了它。pay-app-01 的主机名同时来自 B-PCPU（已确认）和 B-CPU、B-OOM（默认推断），三个来源都记。
3. 状态按来源算。有一个来源是已确认的规则或约定 → 生效；只有默认推断的来源 → 候选；来源都没了 → 作废。状态是算出来的，不是逐行确认的，设计第 4.7 节「确认放在规则这一级」不变。关系的状态和它两端对象的状态分开算：I-ORD 确认后 runs_on 生效，它指向的 order-db-01 只由 I-LIC 的默认推断产出，仍是候选（图 5）。
4. 确认一条规则：本组的已确认规则记为它产出的那些行的来源，这些行转生效；本组不再是规则不产出的那些行的来源，那些行按第 3 条重算，没有别的来源就作废。作废的对象键不复用。
5. 撤销一条已确认规则：本组不再是这些行的已确认来源，按第 3 条重算；同一行还有别的已确认来源时保持生效，否则作废。本组按默认推断的新产出要等下一次摄入才出现（第 1 条：只有摄入产出行），撤销时可同样选择重新摄入近 7 天。
6. 统计不迁移。统计挂在（分组，对象）上，原始告警不入库（设计第 5.1 节），对象键变了没法按新键重算。确认时可选「用保留的上传文件重新摄入近 7 天」：摄入用的上传文件成功后保留 7 天〔拟〕（设计第 7.6 节）。对象键不变时这个选项置灰。
7. 快照不含候选〔拟〕，同快照现在不含 suggested、pending 的做法（设计第 7.5 节）。analyze 处理时用候选，结果包里标出「候选」。
8. 预览的范围：「确认后的变化」只能在存着的样本和最近一批保留的上传文件上试算，不覆盖全部历史。抽屉里写明这一点。

4.10 告警主题 · 列映射

用户 2026-10-08 确认按列的性质分两层：

两层都需要。分组本身要用模板号、内容、时间、监控系统，分组之前还没有模板，这几列没法按模板配。实测不带语义库处理 /tmp/aa/alerts.csv：算法包内置的常见列名认得 msg、occur_time（alertalgo/fields.py 第 65、78–79 行），认不出 tpl_id、source、mark、biz_sys；没有监控系统和模板号，130 条全部按相似度聚类，分成 15 组（配了映射和监控系统取法是 13 组），分组键对不上导入的规则。

• 一个监控系统一组映射，第一组是「语义库默认」。上半部分按组编辑、按组确认；数据库里仍是每个标准字段一行。
• 每行：标准字段、写法（六种，下拉）、原始列、变换（时间格式、去掉 IP 前缀、strip_own）、试算值（取最近一条样本）。下半部分多一列「被模板覆盖」，列出哪些分组的规则改写了这个字段。
• 改下半部分的默认推断，只影响没有已确认解析规则的分组：确认解析规则时，kb 把当时继承的默认推断固定进那一版〔拟〕（设计第 4.4 节），之后改默认推断不会悄悄改变已确认分组的行为。保存时提示「已确认的 N 个分组不受影响」。
• 必需字段检查：content、happenedFirst，以及 objectId、host、ip 至少一个（数据标准第 3.2 节；后三个在下半部分）。缺必需字段时「确认」置灰。未映射的字段列在表下，写明缺了做不了什么（文案同数据标准第 3.1 节）。
• 右侧「列体检」：摄入时按监控系统统计的各列填充率（设计第 4.3a 节）。低于 100% 的格子标红，提示这一列在该监控系统里要靠模板规则补取或按监控系统覆盖。

4.11 告警主题 · 噪音

噪音标注是对一个分组的已确认说明：这类告警长期存在、已知、可以不展开。它带一个行为范围：每小时最多多少条、涉及对象最多多少个、不能带哪些标签。RCA 预处理时，范围内的告警归入「背景」，只计数、不展开、不删除；超出范围就照常展开（设计第 4.4 节）。

为什么要它。简报把信号分成注意力、背景、无标签三类（数据标准第 5.2 节）。告警产品打了「高频」「周期」标签的，本来就进背景；没打标签的例行告警落进「无标签」，和真正要看的混在一起。6/11 那份真实数据 1140 条里有 545 条没带任何标签（交接第 5 节），这部分只能靠噪音标注进背景。

谁写。kb 用统计找候选：基线窗内至少 6 天在相近小时出现的「周期或慢性」分组（设计第 5.3 节）；治理智能体按基线写出行为范围和一段描述；人确认。智能体只能描述频率和内容，判断不了「可以不管」。确认噪音要有频率以外的依据（设计第 4.4 节），所以确认时「依据」由人填，必填，写已知问题、工单号或计划任务；智能体写的只作为「描述」显示。新库没有 7 天基线时没有候选：要么先回补 28 天，要么头一周没有。

和另外两样不同。「范围外」是处理设置，表示不归这里管，配了即生效（4.13 节）；「计划内」是解析规则给变体打的标记，如 N-LOSS 的计划内关闭。

列表列：分组、行为范围、依据、描述、基线天数、来源、状态、最近一批命中。抽屉：行为范围逐项对照最近一批的实际值、有无这条标注的效果对比、近 7 天每天条数、描述（智能体）、依据（人填）。行为范围按整组判：任一项超出，整组照常展开，原来的对象也一起展开。

4.12 告警主题 · 任务

列出摄入和治理任务（tb_sem_job）：类型、状态、输入文件、条数、时间段、触发者、开始与结束时间、结果摘要。顶部是近 28 天的摄入覆盖条，同图 2。「上传并摄入」是第 1b 期新增的入口，第 3 期以后治理智能体走工具做同样的事（设计第 6.2 节）。确认规则时选了「重新摄入近 7 天」，这里多出一条触发者为「确认 <分组> 的规则」的摄入任务。

上传与摄入的异常路径：

摄入时间段缺省按告警时间向外取整点（08:00:06–09:55:35 取成 08:00–10:00），覆盖记录按这个时间段写。只按告警的最早最晚时间记，09:55 之后没有告警的那几分钟就不知道是没告警还是没摄入。

4.13 告警主题 · 设置

告警的处理设置存在 tb_sem_topic.settings（设计第 3.6 节），保存即生效，从下一次摄入起作用。每项一个小表单；条件类的项带「试算」，显示按最近一批数据有多少条命中。

条件里的字段先找原始列，再找标准字段（settings.py 文件头），所以表单的字段下拉先列原始列。

template_mode 从 auto 改成 skeleton 会换掉全部分组键，已有分组的规则和统计接不上。保存前弹窗说明这一后果，要求输入库代号确认。2026-10-09 已定：递增分组代次，旧分组退休，旧规则、统计留作追溯，不参与当前解析和基线。

5. 闸门流程：建库 → 上传 → 摄入 → 确认

用虚构数据在本机走一遍。顺序有讲究：列映射、语义约定、处理设置影响摄入时的解析，要在摄入前生效；解析规则的确认要看样本预览，要在摄入后做。

第 4、5 步的对象数、主机数、错的候选，是把 library.json 的规则全部改成待确认、和不改，各跑一次算法包得到的。第 2 步要求导入时按分组键建分组行（没有样本、状态为新），规则挂在上面，摄入后样本和统计补上。如果 kb 只能把规则挂在已存在的分组上，第 2 步拆成两次：先导入设置、映射、约定，摄入后再导入解析规则和噪音。【待确认：kb 第 1 期实施者】

6. 权限与可见性

规则沿用 docs/kb-code-team-permissions.md 第 2.2 节，权限挂在 kb 矩阵行下（设计第 1.1 节）。

• 其他团队的库：列表里名称旁标「只读」、不显示待确认数；库详情标题旁显示「只读 · 属于 <团队>」，不渲染写按钮，同代码管理按 canManage 渲染的做法。kb 在库的返回里带 canEdit、canDelete。
• 治理智能体只写待确认（设计第 8 节第 9 条），界面上它的提交显示「治理智能体」和会话 ID。
• 经平台 KB 代理的 POST 一律按 kb:write 签（packages/server/src/routes/kb-proxy/proxy.ts 第 110–112 行）。各个「试算」接口是 POST，只读用户调不了；本方案只给有编辑权限的人显示试算，代理不用改。

7. 关键取舍

• 一项菜单，列表 → 库详情，换来库的层级看得见、链接指向确定的库、加主题不改菜单。代价是只有一个库时每次多点一次；告警主题里是库内页签加主题内按钮组两层切换。
• 告警对象和解析规则两个视图看同一批数据，换来既能从规则看产出（确认用），也能从对象看来源（使用、核对、以后对账用）。代价是同一行在两处出现，状态和来源必须取自同一个接口口径，不能两边各算。
• 没有确认规则的分组也写入，标候选，换来新模板在治理前也有对象和关系可查，RCA 能用。代价是多一个状态，查询、快照都要按状态过滤；错的候选会占对象键，作废后键不复用；每一行要记全部来源。
• 抽屉多处复用（解析规则、对象、约定的抽屉在待确认、各视图、预览里打开都是同一个），换来入口不同、行为一致。代价是抽屉都要能单独打开，kb 要能按 ID 取单项。
• 规则编辑只有对象、类型、主机、分类做成表单，其余用 JSON，换来第 1b 期不用为六种写法各做一套表单。代价是改取法的人要读得懂写法，靠试算兜底。
• 菜单不加待确认徽标，与代码管理一致。代价是积压要进页面才看得到；库列表的待确认列部分弥补。
• 批量确认只放给对象键不变的解析规则，换来事实类条目（约定、噪音、依赖、冲突）和会改对象键的规则每条都有人看过。代价是治理智能体一次提交几十条约定时，人要逐条点。

8. 影响面

8.1 aimp-platform

平台 KB 代理把 /api/v1/kb/* 原样转给 kb（kb-proxy/proxy.ts 第 30–33 行），新接口不用改代理。侧栏、useShell.js 的选中和放行逻辑按前缀匹配，/sem/<库 ID>/… 不用改（3.1 节）。

8.2 界面需要 kb 第 1 期提供的接口

接口契约只在一处维护：docs/alert-semantic-design.md 第 7.7 节（路径、参数、返回的要点、签名动作）。本节只列每个页面用到哪几组。

上传预检（图 11 对话框里的条数、时间、必需字段、已覆盖小时）由 kb 在上传后返回，不在浏览器里解析 CSV：原始告警一条记录可能跨多行（虚构数据里 5 条正文带换行），浏览器按行切会算错条数。

8.3 设计文档的对应改动（2026-10-08 已并入）

界面讨论中定下的设计改动已经写进设计文档，不要再按本节重做一遍。对应关系：

9. 未决问题

2026-10-09：第 1 期方案已由用户统一批准。来源使用独立表；无样本先建分组；冲突按来源版本持久裁决；模板模式按代次隔离；保存遮罩重遮样本和展示副本；首期仅停用库；analyze 进入任务列表但不写摄入统计。具体接口以告警设计第 7.7 节为准。

已定（用户 2026-10-08）：

• 字段按列的性质分两层；没有确认规则的分组也写入，用状态区分。
• 菜单一项「语义管理」，运维语义库列表 → 库详情；只有一个库时也显示列表。
• 告警主题里单独设「告警对象」，含对象、关系、未解析目标，留出 CMDB 对账的位置。
• 语义约定以「写法 → 指什么」呈现，列出谁用它和影响，正则作为细节；噪音确认时由人填依据，智能体写的只作描述。

进展（2026-10-09）：第 1 期接口与第 1b 期界面都已实施，第 5 节闸门已用浏览器端到端走通；下一步是第 2 期（平台与 agent-base 的工具族），见 docs/alert-semantic-handoff.md 第 5 节。以下是原写的下一步，留作记录：kb 第 1 期按设计文档实现，接口按设计第 7.7 节；第 1b 期等第 1 期接口可用后开工，按第 5 节验收。第 9 节第 3–15 条里标「用户」的事项，同步列在 docs/alert-semantic-handoff.md 第 3 节第二张表和第 4 节，开工到相关部分时先向用户确认。示意图的数据可以重现：synth 用 seed 7 重新生成，alerts.csv、library.json 的 sha256 与本文所用的相同（2026-10-08 实测，alerts.csv 为 2f08473bd36a…），不依赖保留 /tmp/aa。