决策记录（ADR）

记录技术选型与取舍。格式：编号 / 日期 / 议题 / 选项 / 结论 / 理由 / 影响。 结论变了不删旧条，新增一条并注明「替代 ADR-xxx」。

ADR-001｜知识库源码基准取 platform-ems-3-6-plain

• 日期：2026-10-15
• 议题：两份代码目录哪一份作为知识库的源码基准？
• 实测：
  • platform-ems-3-6/：264 个 .c 全部为加密二进制（file 判 data，首字节 340 250 221 347 330 362）
  • platform-ems-3-6-plain/：264 个 .c 全部为可读明文
  • 两者 git HEAD 相同：04e72700（V0.11.676）
• 结论：以 platform-ems-3-6-plain/ 为唯一基准。platform-ems-3-6/ 视为加密分发副本，不参与文档化。
• 影响：所有解析文档、索引 TSV、检索脚本、HTML 中的路径都指向 -plain。

ADR-002｜知识库统一落位根 docs/knowledge/

• 日期：2026-10-15
• 议题：已有 191 份解析在 platform-ems-3-6-plain/docs/代码解析/，是否迁移？
• 选项：
  • (a) 迁移到根 docs/knowledge/，单一副本
  • (b) 原地不动，根 docs/ 只放链接
  • (c) 两边各留一份镜像
• 结论：选 (a)（用户 Q2 确认）。
• 理由：用户明确要求「所有需求都记录在 docs 里」。单一副本避免两处漂移。
• 影响：迁移时必须修复索引与 README 里的相对链接；迁移后 platform-ems-3-6-plain/docs/代码解析/ 移除，避免双份。

ADR-003｜HMI 77 份界面文档本轮不纳入

• 日期：2026-10-15
• 议题：_excluded_hmi_ui_docs/ 的 77 份文档是否纳入知识库？
• 结论：本轮不纳入，之后单独补一批（用户 Q3）。
• 理由：先把 191 份应用层主体做扎实，界面文档作为独立批次。
• 影响：知识库初期规模 191 份；界面类问题（菜单操作、界面读数）暂时答不了，需在 skill 中显式声明此边界。

ADR-004｜网站采用子路径 /ems/ 方案，不改造现有站点

• 日期：2026-10-15
• 议题：线上已有「椰果的故障诊断 Agent」站点（/ + /test.html + /mcp + /healthz），新功能怎么落？
• 选项：(a) 改造现有站点；(b) 新开子路径 /ems/；(c) 另建独立站点
• 结论：选 (b)，新开 maxiao.xoato.com/ems/（用户 Q5）。
• 理由：现有站点与既有 /mcp 网关完全不受影响；回退只需删目录，风险最低。
• 影响：现有「故障诊断 Agent」保持原样；知识库浏览、功能→函数检索、故障速查、问答、架构讲解全部挂在 /ems/ 下。

ADR-005｜飞书智能体只走现有 aily → /mcp 链路

• 日期：2026-10-15
• 议题：飞书侧用 aily 还是新建自建应用机器人？
• 实测：线上 /test.html 自述链路为 飞书 aily → POST /mcp → Nginx → MCP 网关 → pi → DeepSeek，工具名 ask_fault_expert。
• 结论：只用现有 aily 链路（用户 Q6）。网页问答与飞书 aily 走同一个后端与同一个知识库。
• 理由：aily 已是飞书官方智能体平台且链路已在运行；一个后端即可同时满足「网页能问 + 飞书能答」，改造量与运维成本最小。
• 影响：不新建回调服务、不申请新应用权限；F 组任务的实质变成「把知识库能力接进现有 MCP 工具」。用户 Q7 答「有权限，需我给申请指引」——按此结论，多数权限无需新申请。

ADR-006｜大模型沿用 DeepSeek，接口做成可切换

• 日期：2026-10-15
• 结论：沿用 DeepSeek（用户 Q8）。
• 影响：网关模型配置不动；但实现时把模型调用参数抽成配置项，将来换模型只改配置。

ADR-007｜EMS 专家 Skill 按 skill-creator 跑完整评测闭环

• 日期：2026-10-15
• 结论：跑完整闭环——建测试用例集 → 跑一轮 → 看结果 → 改 → 再跑（用户 Q11）。
• 理由：skill 要在后续所有会话里稳定触发并答对，不评测等于没有质量保证。
• 影响：S 组需产出 evals/ 用例集与评测报告。

ADR-008｜知识库过程源码只读不改

• 日期：2026-10-15
• 结论：只读不改，一律不动 platform-ems-3-6-plain 下的任何 .c/.h（用户 Q13）。
• 理由：保持与上游 04e72700 的可对比基线。

ADR-009｜/ems/ 站点加口令保护

• 日期：2026-10-15
• 议题：知识库含敏感内容。
• 依据：现有解析文档已记录 hmi/key.c 的硬编码管理员/安装商口令、common/aes.h 的硬编码 PUBLIC_KEY、common/simple_encryption.c 的全机共用密钥。
• 结论：加口令保护（用户 Q15），只有内部人员可访问。
• 影响：W4/W5 需实现鉴权层；同时要保证飞书 aily 调用 /mcp 不受影响（它是机器调用，走密钥鉴权，不走页面口令）。

ADR-010｜退役 robot-communication-protocol skill

• 日期：2026-10-15
• 议题：新建 EMS 专家 skill，是否退役既有的法奥（FAIRINO）机器人通讯协议 skill？
• 结论：从技能清单中移除，移到 docs/archive/robot-communication-protocol/（用户 Q1 追问确认）。
• 理由：用户要求「去除法奥机器人相关，要一个全新的」。
• 不物理删除的原因：根目录 D:\V0.11.676拉取 无 .git，.agents/ 不受任何版本控制（git rev-parse 报 not a git repository），物理删除不可恢复。移出等价于「不再触发」，且可拾回。
• 执行结果：已移动，18 个文件完整保留。

ADR-011｜交付顺序：知识库优先，逐层向上

• 日期：2026-10-15
• 议题：Q14 —— 各交付物按什么顺序做？
• 选项：(a) 知识库优先逐层向上；(b) 先出可见成果（HTML+skill）再回头深挖；(c) 现场优先先出故障速查；(d) 网站先上知识库后补
• 结论：选 (a)（用户 Q14 确认），且无对外时间点压力。
• 顺序：
  1. 知识库底座（K1 基准哈希 → K2/K3 迁移 → K5 一致性校验 → K8 统一检索入口）
  2. 功能下钻到函数级（K6）
  3. 故障速查库（K7.1~K7.8）
  4. ems-expert skill（S1~S10，含评测闭环）
  5. skill-ems.html（H1~H5）
  6. /ems/ 网站（W2~W10）
  7. 飞书 aily 接入（F1~F7）
• 理由：
  • skill、HTML、网站、飞书四者共用同一份知识库，是四个投递口而非四件独立产品。知识库不扎实就建网站，等于盖完房子再打地基。
  • 用户的真实痛点「功能→函数」与「现场故障定位」都由知识库直接承载；后者现有资产完全空白，增量最大。
• 并行轨道：W1~W3（服务器盘点 + 全量备份 + 回滚脚本） 不占主线，SSH 凭据一到即插入执行。理由是它纯属降低风险，越早做完越敢改线上。

ADR-012｜知识库目录结构：代码解析/ 整树搬迁，故障速查/ 作同级兄弟

• 日期：2026-10-15
• 议题：迁到 docs/knowledge/ 后内部如何组织？
• 结论：

    docs/knowledge/
    ├── README.md       知识库总入口（新建）
    ├── 基准版本.md       K1：源码 commit / 版本号 / 哈希清单（新建）
    ├── 代码解析/        整树搬迁，内部结构不变
    │   ├── README.md
    │   ├── common/ data/ hmi/ logic/ midware/ net/ user/   （191 份逐文件解析）
    │   └── 索引/（功能索引 7 份 + 3 个 TSV + 工具/）
    └── 故障速查/        K7 新建，与 代码解析/ 同级

• 理由：整树搬迁 = 零链接修改。树内所有相对链接（README.md → common/aes.c.md、索引/README.md → ../midware/bms/bms.c.md）只要相对关系不变就继续有效。
• 已核实的副作用：索引/工具/查找.js 用 __dirname 相对寻址，搬家后自动可用；索引/工具/生成索引.js 写死 ROOT = 上 4 层，搬家后失效，必须重写路径解析（改为「文档镜像根」与「源码树根」分别解析，源码根支持 EMS_SRC 环境变量覆盖）。

ADR-013｜线上环境更换为 47.239.25.159 / xiao-ma.xoato.com

• 日期：2026-10-15
• 议题：用户提出「跟新我的公网ip：47.239.25.159，还有网址：xiao-ma.xoato.com」。
• 结论：接受环境更换。后续所有部署以新环境为目标。
• 本 ADR 替代什么：只替代 ADR-004 中的主机地址部分。

ADR-004 的核心决定「新功能挂 /ems/ 子路径、不改造既有「故障诊断 Agent」首页」仍然有效，未变更。

实测差异（2026-10-15，两份环境都实测过）

由此产生的重要后果

"承接之前的功能"这件事的性质变了。 原先的目标是「在既有站点上扩容」，现在新机是白板：

• nginx 站点、TLS 证书 → 从零部署
• /mcp 网关（agent-gateway 服务 + /etc/agent/agent.env + pi/DeepSeek 配置）→ 要么迁移，要么重建
• 飞书 aily 的指向 → 若要迁到新机则必须改，迁移期间飞书会中断

未决事项（阻塞 W 组）

旧环境是否退役？ 三个方案待用户选择（详见 docs/output/服务器接入指引.md 第二节）：

• A. 旧机退役、全部搬新机 —— 需整套迁移，飞书短暂中断
• B. 两台并存、新机只承载 /ems/ —— 旧机不动，但要决定飞书指哪台
• C. 旧机转备份、新机为主 —— 折中，仍需迁网关

在用户答复前，不动任何一台机器。 另需用户提供新机 SSH 登录用户名（公钥安装步骤见接入指引第五节）。

ADR-014｜拒绝接收与使用阿里云控制台账号凭据，只走 SSH 密钥

• 日期：2026-10-15
• 议题：用户提供了阿里云控制台账号 + 密码（形式为「账号 mn****3683，密码与账号相同」），

意图应是让 AI 自行完成服务器接入。

• 结论：不接收、不保存、不使用。服务器接入一律走 SSH 公钥（见 ADR-013 与 output/服务器接入指引.md）。
• 不使用的理由：
  1. 权限远超需求。控制台主账号可改计费、删除全部 ECS、改域名解析、管理子账号与 AccessKey。

本项目实际只需要一台机器的 SSH 访问权。

1. 该凭据为弱口令：账号（手机号）与密码完全相同，且控制台是公网可达登录入口。
   1. 技术上也不可行：阿里云控制台登录通常需短信/扫码二次验证，无头浏览器走不通。
   2. 爆炸半径不对称：为省下"粘一次公钥"的两分钟，把整个云账号的控制权交出去，不划算。

• 已执行的处置：
  • 未把该凭据写入任何文件（已全工作区检索确认零命中，含台账、变更日志、ADR、代码注释）。
  • 已当面告知用户该凭据已进入本次对话记录（会话日志落在本机 ~/.kimi-code/sessions/ 下，

非本项目可控），并建议：立即改密码 + 开启 MFA + 若该密码在他处复用则一并更换。

• 在根 AGENTS.md 的安全章节补一条硬禁止，防止后续会话再走到这条路上。
• 仍然需要用户提供的：新机 47.239.25.159 的 SSH 登录用户名（root / ec2-user / admin）。

公钥安装步骤见 output/服务器接入指引.md 第五节 —— 全程无需用户交出任何密码。

ADR-015｜旧环境退役，整套迁往 47.239.25.159（方案 A）

• 日期：2026-10-15
• 议题：ADR-013 遗留的未决事项 —— 旧环境 8.133.19.10 如何处置？三选项 A/B/C 见 output/服务器接入指引.md。
• 结论：选 A —— 旧机退役，把既有功能整套迁到新机 47.239.25.159（用户答复「1.A」）。
• 迁移范围（旧机上的既有功能，一件都不能漏）：
  1. nginx 站点配置 + 站点根目录（「故障诊断 Agent」：index.html、test.html）
  2. agent-gateway systemd 服务单元及其依赖
  3. /etc/agent/agent.env（MCP_API_KEY、DeepSeek 配置等）
  4. /mcp 网关所依赖的运行时（含 pi，具体形态待盘点）
  5. TLS 证书 —— 不能复用，新域名 xiao-ma.xoato.com 必须重新签发
• 关键优势（本方案被选中的核心理由）：只要旧机不删除，回滚 = 改一条 DNS 解析。

因此迁移全程旧机保持原样、不做任何修改，直到新机端到端验证通过并观察满一个窗口期。

• 已知风险与前置：
  1. 新机 80/443 当前不通 —— 阿里云安全组需放行（须用户在控制台操作，我在机器内改不了）
  2. 飞书 aily 的指向要改 —— 这是用户侧操作，且迁移窗口内飞书问答会中断
  3. 新旧域名不同（maxiao → xiao-ma），证书、回调地址、任何写死域名的配置都要一并核对
• 执行顺序（不可颠倒）：
  1. 新机安全组放行 80/443（用户操作）
  2. 取得两台机器的 SSH 访问权
  3. 两台都先全量备份，并验证可回滚 ← 未完成前不动任何线上文件
  4. 盘点旧机（nginx conf / 站点根目录 / systemd 单元 / /etc/agent / 运行时）
  5. 新机装运行时并部署，用 curl --resolve 或 Host 头绕过 DNS 本地验证，此时 DNS 仍指向旧机，对外无感
  6. 签新域名证书、启用 HTTPS
  7. 切 DNS / 改飞书指向 —— 唯一的中断窗口
  8. 观察期后旧机退役
• 阻塞项：仍缺两台机器的 SSH 访问方式（新机需用户名；旧机从未取得）。

详见 output/服务器接入指引.md 与 output/迁移方案.md。