企业官网建设流程全解析

• 人工智能
• AI Agent
• 网络安全
• 后端
• 前端

本文以 AiSOC 的 Product Hunt 发布资产（marketing/launch/product-hunt.md）为骨架，逐条落地它对外承诺的技术能力：一条命令把 200 条告警分诊成结论、一个可对外分享的公开回放链接、以及一套 MIT 许可的自托管路径。读完后你能准确判断这些承诺中哪些今天就能跑、哪些需要先解决发布阻塞，并能直接上手执行aisoc triage、把自有告警导出喂进确定性评分器、在完整栈里发布一次脱敏的事件回放。

发布文案的四条核心承诺

product-hunt.md 的正文并不长，但每句话都指向一个可以被源码验证的系统能力。原文的组织方式是 Name / Tagline / Description / Maker's first comment / Gallery / Topics / Links，其中真正有技术含量的是 Description 与 Maker's first comment。把其中的断言抽出来，可以得到这样一张对照表：

第一行是本文必须最先讲清楚的事实：发布文案本身在开头就写明了这个阻塞——aisoc在每次打 tag 时都会被构建和打包，但从未上传过；npx aisoc目前不 resolve，卡点是 npm 凭据而不是代码。文案给出了替代方案：要么先发布，要么把命令换成从克隆仓库构建的形式。任何引用这份文案的对外材料都不能跳过这一点。

60 秒楔子的真实执行链路

先解决"能不能跑"的问题

由于npx aisoc尚不可用，今天可复现的入口是从克隆开始构建：

pnpm --filter aisoc build && node packages/aisoc-lite/dist/cli.js triage --demo

packages/aisoc-lite/package.json中的bin指向dist/cli.js，engines.node要求>=20.0.0，运行时依赖只有picocolors一个——这一点与 packages/aisoc-lite/README.md 中"每个依赖都是一份负债"的表述一致。构建使用tsup，npm run smoke等价于node dist/cli.js triage --demo --no-telemetry，适合在 CI 里做冒烟检查。

等包真正发布之后，命令形态就回到文案中的npx aisoc triage --demo。

从 argv 到结论的五个环节

aisoc triage的调用链在 packages/aisoc-lite/src/cli.ts 里是一段手写的极简参数解析：以--开头的 token 作为 flag，若下一个 token 不以--开头则视为该 flag 的值，其余作为位置参数。这也解释了为什么--share既能当布尔开关，又能接一个输出路径：flags.share === true ? true : typeof flags.share === "string" ? flags.share : undefined。

进入runTriage之后，流程是固定的五步：

1. 解析数据源：resolveSource优先看--demo，其次--file（走 jsonl），最后才是--source，默认值为demo。允许的取值被硬编码为demo | jsonl | splunk | sentinel | elastic | crowdstrike，非法值直接抛错并列出全部合法项。
2. 加载并归一化：loadAlerts从内置 fixture 或本地文件读出记录，逐条经过normalizeRecord变成统一的Alert结构（见下一节）。
3. 批量评分：triageBatch(alerts, { deterministic: true })对每条告警调用scoreAlert，然后按true_positive → likely_true_positive → needs_review → likely_benign的顺序排序，同档内按置信度降序。这样终端表格天然把最该看的排在最前面。
4. 渲染：非--json模式下打印表格（默认最多 20 行，--max-rows可调）和一行可复制粘贴的 headline。
5. 可选副作用：--share写报告卡，遥测在显式开启时才可能发一次网络请求。

需要注意 headine 的统计口径：summarize把true_positive与likely_true_positive都计入truePositive，把likely_benign计入suppressed，噪声比例 = suppressed / total。README 示例中的12 TP, 171 FP suppressed (85.5% noise), 17 need review就是这条公式的输出。

输出形态与库调用

人读模式输出表格加 headline；--json输出完整TriageResult，包含verdicts[]与summary，其中每条 verdict 带有basis（人类可读的理由列表）与evidence（按贡献绝对值排序、截断到 3 条的加权因子）。这个结构同样可以直接当库用：

import { triageBatch, loadJsonl } from "aisoc"; const alerts = await loadJsonl("alerts.jsonl"); const { summary, verdicts } = triageBatch(alerts); console.log(summary.headline);

--llm精修成功后，结果对象的deterministic会被置为false，这是判断"这条结论是否只由确定性引擎产出"的唯一可靠标志。

确定性评分引擎：为什么同样的输入必然得到同样的输出

scoreAlert的设计约束被明确写在源码注释里：纯函数（无 I/O、不调 LLM）、有界（置信度夹在[0.05, 0.95]）、有理由（每次评分返回basis列表）。权重是可加的，最后统一 clamp：

关键字匹配的对象是title + raw + JSON.stringify(iocs)拼接后的小写文本，因此原始事件正文里出现ransomware、mimikatz、cobalt strike、data breach等词会显著抬高分数，而phishing、malware、privilege escalation等属于次高档。

映射到结论的阈值在verdictBand中定义，与 packages/aisoc-lite/README.md 的表格完全一致：

两个细节值得单独说明。第一，recommendationFor使用了never类型的分支兜底，新增一档 verdict 时 TypeScript 会编译失败，而不是悄悄落到suppress。第二，当所有信号都没命中时，basis会补一条"no salient signals — defaulting to floor confidence"，因此即使最"空"的告警也会得到 0.05 而不是 0——系统永远不宣称绝对不可能，也不宣称绝对确定。

stages.ts的注释声明它是services/agents/app/confidence/scoring.py中score_triage的移植，权重与阈值需要与服务器逐字节一致，并由packages/aisoc-lite/src/verdict/stages.test.ts固定常量。这意味着 CLI 的结论应当落在完整栈在分诊阶段会给出的同一个 band 上。如果你要修改权重，必须先改 Python 侧再同步这里，否则这个"CLI 结论 = 服务端结论"的契约就被破坏了。

喂自己的告警：字段归一化与源适配的边界

--demo只是演示。真正有价值的路径是--file：

node packages/aisoc-lite/dist/cli.js triage --file alerts.jsonl --attention-only

loadJsonl容忍三种文件形态：以[开头的 JSON 数组、包含alerts键的对象（取obj.alerts）、以及标准的行分隔 JSON（每行一个对象）。读入后每条记录都交给normalizeRecord，用一组候选字段名做"最佳努力"映射，因此 Splunk、Sentinel、Elastic ECS、CrowdStrike 的原生导出通常不需要写映射文件：

两个强制转换逻辑会直接影响评分结果。coerceRisk认为大于 1 的数值是按 0–100 打分的，会除以 100 并夹到[0,1]；也就是说如果某厂商的confidence字段本来就是 0–1，但恰好写成1，它会被当作 1.0 而不是 100 分制。coerceSeverity除了接受标准五档，还接受informational/none/notice → info、warning/warn/moderate → medium、severe/urgent → critical，以及数值映射（≥9 critical、≥7 high、≥4 medium、≥1 low）。

一个最小可用记录可以只有六个字段：

{"id": "A-1", "title": "PowerShell spawned by Word", "severity": "high", "risk_score": 0.7, "techniques": ["T1059.001"], "src_ip": "10.0.0.5"}

按权重表可以手算出这条告警的置信度：risk0.7 * 0.6 = 0.42，命中 high 关键字（powershell不在词表内，但malware/exploit等也不在，取决于标题文本），1 个 MITRE 技术+0.04，1 个 IOC 字段+0.05，合计落在needs_review或likely_true_positive区间。这种可手算性正是确定性引擎的调试优势。

源适配的现实边界必须说清楚：splunk、sentinel、elastic、crowdstrike四个取值虽然出现在--source的合法列表里，但 packages/aisoc-lite/src/sources.ts 中这四个分支会直接抛错，提示"live 源需要凭据"，并建议改用--demo或导出为 JSONL。也就是说文案里"自动识别常见字段拼写"指的是对导出文件的字段猜测，而不是直接连 SIEM。这一点在对外介绍时不应含糊。

可选 LLM 中间带：只精修模糊区，Key 永不经过服务端

--llm的定位非常克制。确定性引擎永远是地板且永远先跑；只有在用户自己设置了ANTHROPIC_API_KEY或OPENAI_API_KEY并显式加--llm时，才会对被判定为needs_review的那部分告警做一次精修。源码注释和 README 反复强调同一个设计：Key 从用户环境读取、直连厂商 API、不经过任何 AiSOC 服务器。

--llm Refine the ambiguous middle with YOUR own LLM key (never proxied)

实现细节上有几处值得注意：

• Provider 探测顺序是 Anthropic 优先于 OpenAI；模型可用AISOC_LLM_MODEL覆盖，默认分别是claude-3-5-haiku-latest与gpt-4o-mini。
• OpenAI 路径支持OPENAI_BASE_URL，因此可以指向自建网关；请求带temperature: 0.1与response_format: { type: "json_object" }，Anthropic 路径带max_tokens: 1500。
• System prompt 要求模型只返回紧凑 JSON，并明确"保守优先，宁可needs_review也不要猜"。
• 解析时只截取第一个{到最后一个}，把置信度夹到[0.05, 0.95]；解析失败返回空数组而不是抛异常。
• 整个精修过程被 try/catch 包住：provider 报错时打印黄色警告并退回确定性结论，绝不因为 LLM 不可用而导致分诊失败。
• 每条被改写的 verdict 会在basis末尾追加(LLM band refined this verdict)，保留可追溯性。

这段设计直接对应文案里"hosted-LLM evidence is pseudonymized by default"的上一层含义：CLI 场景下数据只发给你自己选择的模型厂商，AiSOC 项目本身不参与数据路径。

报告卡、遥测与数据边界

--share [path]会写出两个文件：一个 Markdown 和一个自包含 SVG。默认基名aisoc-report-card.md，扩展名会自动补齐，SVG 与 Markdown 同名。渲染被委托给共享包@aisoc/report-card（同一套渲染器也用于噪声调优看板和 Web 的 OG 图），构建时打进 CLI，保证npx仍是单文件产物。

隐私设计的硬约束写在 packages/aisoc-lite/src/share.ts：卡片只含聚合计数与 verdict band 元数据，绝不含告警标题、IOC、主机名或用户名。toCardData只取total / escalate / review / suppress / noisePercent / elapsedSeconds / deterministic七个值加上kind: "triage"，从类型层面就没有泄漏通道。因此这张卡可以直接发出去，不需要脱敏评审。

遥测更加保守，packages/aisoc-lite/TELEMETRY.md 给出了完整契约：

优先级从高到低：--no-telemetry→--telemetry→AISOC_TELEMETRY=0→AISOC_TELEMETRY=1→ 默认关闭。发送内容只有event / version / source / total / truePositive / needsReview / suppressed / deterministic / elapsedMs，且telemetry.test.ts会断言告警内容不可能出现在载荷里。

最容易被误解的一点是"发到哪里"：项目没有默认端点，也不运营收集器。只开--telemetry而不设AISOC_TELEMETRY_ENDPOINT，不会发生任何网络调用；设了端点才会以 2 秒超时 POST 一次，失败静默忽略，永不拖慢 CLI。文档还保留了一段诚实的修订说明：过去默认指向一个已不存在的托管收集器，导致用户同意发送的数据被丢弃，这被认为比不收集更糟，因此改成必须显式指定目的地。

规则翻译：零 Key 的确定性字段重映射

aisoc translate支持 Sigma / SPL / KQL / ES|QL / YARA-L2 / UDM 六种格式，--from默认sigma，--to接受逗号分隔的目标列表，不指定则输出其余全部。规则可来自位置参数、--file或标准输入：

cat rule.yml | node packages/aisoc-lite/dist/cli.js translate --from sigma --to spl,kql

packages/aisoc-lite/src/verdict/translate.ts 说明了它的真实性质：这是服务端translation.py中字段映射回退路径的 TypeScript 移植，是有意为之的最佳努力字段重映射，不是完整的 Sigma AST 编译器。字段映射表与服务器逐字节一致，例如：

YARA-L2 与 UDM 走同一套 Chronicle 风格路径（principal.process.file.full_path、target.user.userid等）。因为这是确定性重映射，复杂条件、聚合、时间窗语义不会被自动等价转换，产出的规则必须人工复核——把它当作"迁移起点生成器"而不是"翻译正确性保证"。文案中提到的另一个免费浏览器工具（ATT&CK 覆盖评分卡）在 apps/web/src/app/(tools)/tools/page.tsx/tools/page.tsx) 有入口，评分逻辑位于 Web 端的 detections/coverage 相关组件中，属于完整栈能力而非 CLI 范围。

Investigation Ledger：把"为什么这么判"变成可查询的数据

这是文案里最有分量的一句："Every agent step (prompt, tool call, evidence, rationale) is stored in an Investigation Ledger and replayable." 它不是抽象承诺，而是三张有明确约束的表。

services/api/migrations/008_investigation_ledger.sql 定义了：

investigation_runs—— 一次调查一行。关键列包括tenant_id、case_id（外部案件引用，可以是 UUID 或人类可读 ID）、alert_summary、raw_alert（JSONB）、model_used、status（running|completed|failed）、error、total_tokens、total_cost_usd、iterations、started_at、completed_at。索引覆盖(tenant_id, started_at DESC)、case_id、status。

investigation_events—— 一个 agent 步骤一行，append-only。seq在单次 run 内单调递增并由UNIQUE (run_id, seq)强制；kind枚举了步骤类型：recon|forensic|responder|reporter|report|error|tool_call|llm_call|llm_prompt|llm_response|evidence_cited|decision_reason；另有agent、summary、payload（JSONB）、input_hash、output_hash、duration_ms。不可变性由数据库触发器保证：

CREATE TRIGGER trg_inv_events_immutable BEFORE UPDATE OR DELETE ON investigation_events FOR EACH ROW EXECUTE FUNCTION inv_events_immutable();

触发器函数直接RAISE EXCEPTION，任何 UPDATE/DELETE 都会失败。

investigation_artifacts—— 大对象：llm_prompt|llm_response|tool_input|tool_output|report_md|report_html，content内联存储（截断到安全大小）或blob_ref指向对象存储，并强制记录sha256与size_bytes。

三张表都ENABLE并FORCE ROW LEVEL SECURITY，策略统一为tenant_id = current_tenant_id() OR current_tenant_id() IS NULL。这带来一个部署层面的注意点：OR current_tenant_id() IS NULL是给后台/迁移上下文留的口子，若运行时连接没有正确设置租户上下文，RLS 形同虚设。仓库中有专门的检查脚本（如 scripts/check_rls_policy_shape.py、scripts/check_runtime_db_role.py）来约束这类形状。

写入侧在 services/agents/app/investigator/ledger.py，有两个工程决策值得学习：一是 agents 服务只用asyncpg裸连而不引入 SQLAlchemy，只为三张表不值得拖入整个 ORM；二是所有写入都是 best-effort——数据库不可达时记日志并继续，因为 agent 的首要职责是调查而不是记账，且实时流不受影响。但源码同时区分了两类失败：缺少DATABASE_URL不是错误（no-op 返回False），真实数据库错误则抛LedgerPersistError供调用方重试或进入死信队列，避免"静默丢失结果"。

读取侧的 REST 面在 services/api/app/api/v1/endpoints/investigations.py，提供 run 列表、run 摘要、分页事件时间线、完整有序回放、可拖拽的 timeline（带决策溯源注解与跨尝试 diff）、单步explain（某一步的 prompt、response、证据与下游影响）、关闭 run 并生成摘要产物、摘要 PDF 导出，以及 artifact 二进制读取。

公开回放：从私有账本到脱敏分享链接

文案里"you can even publish a redacted replay as a public link"对应一套五步流程，全部在 services/api/app/api/v1/endpoints/replay.py 中：

1. POST /ledger/{run_id}/publish/preview（需cases:read）—— 构建脱敏快照并连同 alias map 一起返回，让发布者在确认前逐项核对"哪些会被隐藏"。这是发布前的 diff 环节。
2. POST /ledger/{run_id}/publish（需cases:write）—— 必须带confirm: true，否则 400 并提示先看 preview。服务端会重新构建快照，绝不信任客户端传来的预览结果；随后写入不可变的published_replays行并返回 slug 与 URL。
3. GET /r/{slug}—— 完全公开、无鉴权，返回脱敏快照供回放页渲染，并尽力递增浏览计数。
4. DELETE /ledger/publish/{slug}（需cases:write）—— 按租户范围下架。
5. GET /ledger/{run_id}/published（需cases:read）—— 列出某次 run 的所有已发布回放。

源码里有一处值得单独指出的修复：分享链接的 base URL 被写成函数_public_base()而不是模块常量。注释解释了原因——曾经它在 import 时被烘成常量并硬编码了某个部署的域名，导致每个自托管实例都对外发出指向别人控制台的链接。这个案例说明"多租户/自托管系统里，任何带域名的常量都应该是每次调用解析的配置"。

slug 生成用secrets.token_urlsafe(8)去掉-/_后截前 12 字符，最多重试 6 次，失败返回 503 而不是返回一个可能冲突的短链。title_override上限 200 字符；日志通过内联_sanitize剥掉 CR/LF 并截断 64 字符，防止日志注入。

脱敏到底脱掉了什么

services/api/app/services/replay_redaction.py 定义了脱敏边界，它不是"全删"，而是有取舍的：

• 复用 vendored 的Pseudonymizer，把内网 IP、邮箱、文件路径、密钥、内部主机名、用户名替换为不透明 token；
• 外部域名/IP 等公开 IOC 被有意保留，因为它们是回放的可分享威胁情报价值，而不是客户 PII；
• 只有脱敏后的快照会被持久化，alias map 仅存在于 preview 响应中，永不落库。

快照结构固定为schemaVersion: 1，字段包括caseId、title、verdict、model、elapsedMs、stepCount、toolCallCount、llmCallCount、evidenceSourceCount、techniques、steps[]、evidenceCards[]、attackGraph。其中attackGraph是刻意极简的确定性图：一个 alert 节点，按顺序串起最多 10 个 technique 节点，边标签固定为leads_to。注释说明了理由——技术编号是公开分类法，这张图足够支撑回放页的"图生长"动画，但不暴露任何实体数据。

几个构建细节：verdict 优先从事件 payload 中反向找最后一个verdict字段，找不到则回落为 run 的status；elapsedMs由completed_at - started_at计算并对类型异常兜底为 0；toolCallCount数kind == "tool_call"的事件，llmCallCount数llm_call与llm_response，evidenceSourceCount数evidence_cited。

发布后published_replays表虽然是公开读取，但更新视图计数是唯一被允许的写操作——这与 ledger 事件表的不可变触发器是同一套思路：可审计的东西一旦写下就不该被改。

自托管、数据驻留与aisoc up

文案的最后一段承诺是"MIT-licensed and self-hostable — your data never leaves your perimeter"。这句话在仓库里可以拆成三层证据：

第一层是许可与安装。LICENSE 为 MIT，install.sh / install.ps1 提供脚本化安装，docker-compose.yml 与 docker-compose.prod.yml 给出完整栈形态，infra/helm 与 infra/terraform 覆盖集群与云资源编排。

第二层是 CLI 的aisoc up。packages/aisoc-lite/src/commands/up.ts 会先把docker compose做到临时目录再启动，因此不需要克隆仓库；文案里的"~3.5 分钟"对应这条较重路径。它有两个安全设计：--ref被正则^[A-Za-z0-9._/-]+$严格限制，只能在本仓库 raw 路径内选择分支/tag/SHA，无法把 URL 改写到任意主机；Docker 不可用时直接失败并引导到triage --demo，而不是尝试用别的方式起容器。

第三层是模型路径。文案说"hosted-LLM evidence is pseudonymized by default; a local-model path is fully air-gapped"。就 CLI 而言，确定性引擎从不联网，--llm才是唯一出网点且直连你自己选的厂商；完整栈的模型路由与本地模型能力在 infra/litellm 与 agents 服务的模型配置中，仓库另有 scripts/check_llm_model_routing.py、scripts/check_default_egress.py 这类脚本约束默认出网行为。自托管时建议先跑这些门禁，再对外声明"数据不出边界"。

发布前必须过的检查清单

把这份发布文案真正发出去之前，以下事项按优先级排列：

1. 先解决 npm 发布。aisoc从未上传过，npx aisoc不 resolve。release.yml每个 tag 都会构建打包，但可信发布需要在包设置页配置，而从未发布过的包没有设置页——首次上传必须用 token，这是账号操作而非代码改动。在此之前，所有对外文案都应使用从克隆构建的形式。
2. 确认文案与 CLI 实际能力一致。--source splunk|sentinel|elastic|crowdstrike目前会抛"需要凭据"错误，只能走 JSONL 导出；如果文案暗示"直接连 SIEM"，就属于过度承诺。
3. 确认回放链接的 base URL 配置正确。自托管实例必须设置CONSOLE_PUBLIC_BASE_URL，否则/r/<slug>会指向错误域名——这正是_public_base()那次修复要防的问题。
4. 确认遥测没被误解。默认关闭、没有默认端点、开--telemetry但不设AISOC_TELEMETRY_ENDPOINT不会有任何网络请求。对外解释时应主动说明，而不是让人以为"默认在收集"。
5. 区分测量与合成。文案提到"it's honest about what's a real measurement vs. a synthetic self-consistency check"，对应仓库里的一批诚实性门禁，例如 scripts/check_failure_is_not_a_verdict.py、scripts/check_alert_reduction_claims.py、scripts/check_claim_gate_matrix.py 与 docs/audit/CLAIM_TO_GATE_MATRIX.md。任何新增的对外数字都应先落到这张矩阵里，再出现在发布文案中。
6. 区分 demo 规模与生产规模。200 条告警、0.1 秒是内置 fixture 的确定性演示，不代表你的环境吞吐；性能相关结论请引用 docs/perf 下的实测结果与 scripts/check_perf_results.py 的门禁口径。

小结

这份 Product Hunt 文案的价值不在于形容词，而在于它每一句都指向了可验证的代码：triage是一条从 argv 解析到确定性评分的完整链路，权重与阈值被测试钉死；Investigation Ledger 是三张受 RLS 与不可变触发器保护的表；公开回放是一套"预览 diff → 服务端重建 → 不可变落库 → 公开只读"的流程，脱敏规则明确区分内部标识与公开 IOC。唯一需要反复强调的是它自己写在最前面的那句提醒：npx aisoc今天还跑不起来，在那之前请用从克隆构建的命令，并如实告知读者。

• 人工智能
• AI Agent
• 网络安全
• 后端
• 前端