Decisions Log

Resley 的 ADR 风格决策日志。记录为什么，不只记录做了什么。新决策插在最前面；每条完整后不再动，除非结论被推翻（标 ⚠️ 超 ceded）。

2026-05-09: Wiki 项目族页全部合并为单页 — 镜像产品 monorepo 化

上下文：5-06 clawline 三 repo 合并为 clawline/platform monorepo 后，wiki 上还散着 5 个 clawline-*.md 子页（client-web / channel / gateway / thread-support / 等）；类似地 packhorizon 与 packhorizon-ai、shutiao-world 与 shutiao-pawpatrol-game-upgrade、agentic-bi 与 b2p-hackathon-planning + bibot-ops-record、nexora 与 6 个 nexora-* 子页都是「一个产品多页」结构，导致同一事实跨页重复（每次更新要扫 N 页才能改对）。

决定：5-09 一次性把 5 个项目族合并为单页：

projects/clawline.md（吸收 5 个 clawline-*）
projects/packhorizon.md（吸收 packhorizon-ai）
projects/shutiao-world.md（吸收 shutiao-pawpatrol-game-upgrade）
projects/agentic-bi.md（吸收 b2p-hackathon-planning + bibot-ops-record）
projects/nexora.md（吸收 6 个 nexora-* 项目页 — entities/nexora-*.md 仍保留）

每次合并都按 SKILL 流程：先把 tags/sources union、保留最早 created，body 中按子组件分 H2，自引用降级为「(本页)」纯文本，grep -rn '\[\[old-name' 验证为零，全 wiki 修 wikilink。

为什么：wiki 页面应镜像产品/项目实际结构 — 单一 monorepo 单页，多 product 多页。事实重复是「页面切分错」的成本；合并后改 1 页即可完成原本 N 页的工作。

踩坑：nexora-* 第一次合并 stream stalled mid tool-call（write_file 没执行），第二次还失败，最后采用「先用 execute_code 拼输入到 /tmp/nexora_merge_input.md，再让模型读这个临时文件做精修合并」的两段式才稳。结论：5+ 文件机械合并必须用 execute_code 处理 I/O，不要让 LLM 一次性 read+merge+write，子任务超时风险高。

相关：clawline、packhorizon、shutiao-world、agentic-bi、nexora。

2026-05-08: cspy 工程师指派放宽 — 不再按 `parentCustomerServiceId` 过滤

上下文：cspy 工单页指派下拉常空。原过滤逻辑要求 engineer.parentCustomerServiceId == ticket.conversation.botId（工程师必须挂在该工单客服 bot 下），对手动新建工单（triggerSource=manual、conversation.botId="__system_manual_bot__"）完全不适用 — 没有任何工程师挂在系统 manual bot 下。

决定（commit 8458b7c）：取消父子关系过滤，所有 role=engineer && active=true 都可被指派；多个客服 bot 共享同一池工程师。

为什么：原”客服 bot → 下属 engineer”父子模型对 AI 自动工单合理，但人工新建工单根本没真客服 bot 上下文。改简单过滤，避免空下拉，业务上一池工程师本来也共享。

2026-05-08: cspy admin Kuma snapshot 用 `unstable_cache(60s)` 旁路缓存，不优化冷启动

上下文：admin 跳页慢，性能 instrumentation 后定位真凶 = 顶部 Kuma 监控小卡每次跳页拉 Uptime Kuma /metrics socket.io 5–6s（68 monitors），其它所有 query 全 < 50ms。

决定：getKumaSnapshot 用 Next.js unstable_cache 包一层 60s revalidate；提供 revalidateKumaSnapshot() 给”刷新”按钮主动失效。冷启动 5s 接受不再深挖。

为什么：实测每 60s 仅 1 次 fresh，命中路径 < 1ms；socket.io 长连改造 ROI 远低于 cache。Cold-start 5s 可接受 — 用户看的是缓存值。

相关：wechat-bot-tickets 5-08 段、monitoring-and-cron Kuma 章节。

2026-05-08: Clawline `/api/messages/sync` 加显式 `scope` 参数防呆 + agentInbox 预热改 `(agent, chat)` 二维分桶

上下文：cobra 的 main agent 视图里出现来自 nexora-ops chat 的 5 条 outbound（22:55:50 同毫秒密集）。初判 thread 移除回归，深查后发现真因：/api/messages/sync 历史允许”传 agentId 不传 chatId” → 跨 chat 拉全频道历史；agentInbox.ts:491 预热也不带 chatId（500 条整 channel 预热进 cache），cobra/main 视图直接读出跨 chat 消息。

决定（commit 4754d6b + hotfix eea9659）：

A1 Gateway：/api/messages/sync 加 scope 必填参数，scope=chat 必须带 chatId（默认），scope=channel 才允许全频道（inbox 预热专用），缺 scope 返 400
A2 前端：useChatMessages / fetchOlderMessages 没 chatId 不发请求；agentInbox 预热结果按 (agent, chat) 二维分桶 seed cache
C：bindings.ts 重建（去 thread 化），channel.ts 重新挂 clawlineBindingsProvider
隐蔽问题：supabase env 短路检查放校验前面 → 没配 supabase 时防呆被绕过；SyncMessage 类型补 chat_id 字段（不然分桶取不到）

为什么：默认值兜底+隐式语义是历史 cross-chat 串扰的根因。scope 显式声明把”想拉什么”的语义抬到 API 表面，server 强校验，client 三处调用方按视图类型显式传，杜绝再隐式跨 chat。

踩坑：hotfix 1 eea9659 —— enabled = !!chatId 把 ChatRoom 首次进入（chatId 要等 WS connection.open 才回来）的拉历史给堵死了 → effectiveChatId = chatId || activeConn?.chatId 兜底。经验：dev 分支 push → 3 分钟自动部署 web.dev.dora.restry.cn（已让 Daddy 唠叨两次，记进 me.md）。

相关：clawline、clawline 5-08 段。

2026-05-08: 旧 `erp.xipugold.com` 服务器继续保留 — iOS 客户端”登录不进去”不是 Nexora 平台问题

上下文：dora/nexora-ops 频道反复报「囍铺手机 ERP 苹果手机登入不进去」，第一反应是 Nexora 新平台故障。完整排查后 iOS 旧版 APP 仍硬编码连老域名 erp.xipugold.com（120.25.173.234:7782），不走 kotlin-api.nexora.restry.cn；老服务正常。问题是老 admin 账号密码被改+老 APP hardcode 123456 明文+WebSocket 缺 role/version 参数。

决定：不动 nexora；老 ERP 服务器和 xipugold.com 域名继续维护，等 iOS 客户端发版换域名才能下线。

为什么：iOS 旧客户端版本仍在用户手机上，强行下线老服务等于线下批量电话。这种”双轨期”是项目搬迁的成本，已记入 nexora-xipu。

相关：nexora-xipu 5-08 段、nexora。

2026-05-07: Clawline 砍掉 thread / sub-channel 抽象（-4666 LOC）

上下文：四月围绕 thread 做了 TH-1..TH-8 + ralph/thread-discord-style 大量加固，但运营事实是没人真的用，反而把 reply-dispatcher / stream-state / 未读全部多绑一个维度，每次改路由都要顾两条 path；ghost-outbound 等可靠性 bug 的排查复杂度也被 thread 状态机放大。

决定（Daddy dora 频道 18:08-18:10「现在做减法 / thread 这个功能太累赘了」）：thread / sub-channel 概念从 client-web + channel + gateway 三处全删，schema threads / thread_messages 表 DROP TABLE（不做扁平化迁移），PRD 标 deprecated，e2e/threads 整组移除。

为什么：加错的抽象每一次维护都收税。先实现再观察的 PRD 容易让团队对未验证概念过度投入。下次类似抽象（sub-channel / 嵌套会话）应先纸面沙盘 + 用户访谈 1 周再写代码。

影响页面：clawline-thread-support（已标 ⚠️ 移除）、clawline、clawline、clawline。4 commits + 1 hotfix（CC 误删 fanOut 函数本体，ce3cf24 恢复）—— 200+ 行的删除 commit 必须人审 fanOut 这种被多处 import 的核心函数。

2026-05-07: 第二个 Mattermost 实例 `mm.cn.restry.cn`（Azure China），不做 federation

上下文：B2P 中国境内访问者走主站 mm.dora.restry.cn 出墙路径延迟高。在 Azure China subscription（MC_RG）起第二实例 mm.cn.restry.cn，Docker compose Mattermost + Postgres + 当地 caddy。

决定：双实例独立账号体系，不做 federation。Bot 在两边各注册一份，配置 MM_* 环境变量分实例区分。

为什么：Azure China ↔ 国际跨境数据 federation 涉及合规复杂度（数据本地化、跨境传输审批），收益（统一账号）远低于成本。Bot 双注册的边际成本可控。

配套坑：useraccesstokens 表里 id 是 token 主键、token 列才是真 bearer，早期错把 id 当 token 配进去 → 401。详见 mattermost-config 5-07 段。

2026-05-07: Nexora 项目代码统一推 GitHub + GitLab 双 remote（`nexora-loop`）

上下文：Restry/nexora-loop（cspy 工单系统演进体）原本只在 GitHub。Resley 决定内网 GitLab gitlab.nexora.restry.cn 也作为镜像 remote，便于「即将迁到另一台机器维护」时内网快速拉取。

决定：本地 origin 配双 push URL（GitHub + GitLab/nexora-vendor/nexora-loop），单条 git push 同时推两边。GitLab 凭据（root PAT、SSH 端口 2222、有效期 2027-05-07）入库 vault gitlab-nexora/* namespace。

为什么：GitHub 是事实标准但内网拉取慢/被墙概率；GitLab 内网是冗余 + 备援；双 push 比 cron 镜像更简单（无延迟、无中间状态）。gitlab-nexora/* 命名空间约定让后续 nexora-loop 系列项目（cspy / wechat-bot-tickets / 其他）共用同一套凭据，不要跨 namespace 复用 PAT。

踩坑：Hermes 安全扫描器把 [email protected] 字面替换 mangle 了 git remote URL，需手工 unmask 重设。经验：vault add/show 涉及 git@host 字面时先 base64 包一层。

相关：wechat-bot-tickets 5-07 段、nexora、gitlab-nexora/ROOT_PAT (severity=high) vault 条目。

2026-05-07: Hermes Bot 直接接入 Mattermost = 1 bot 1 channel；OpenClaw agent 走 Clawline，不复用 MM bot

上下文：Daddy 想让 13 个 OpenClaw agent（main / nexora-ops / nexora-mazu …）都能在 Mattermost 里直接 @ 聊。但 Hermes Gateway 一次只支持一个 Mattermost bot 账号绑定。

决定：分层 —

Hermes Bot = hermes MM bot，单实例只服务 Hermes Agent 自身（不映射 OpenClaw agents）
OpenClaw agent 走 Clawline channel/插件，复用既有 channels.mattermost.accounts.<bot> 矩阵；MM 这边各 agent 已有对应 bot（13 个 nexora 系列），不再为每个 agent 跑一份 Hermes
不在 Hermes 层做 fanout/proxy 的尝试 —— 协议复杂度（多 bot session 隔离、message routing）和现有 Clawline 已经做的事完全重叠

为什么：跨产品的 agent 路由属于 Clawline/OpenClaw 的范畴，Hermes 的定位是「单用户 CLI/IDE agent」。在 Hermes 里硬塞多 bot 会模糊产品边界，也让 wx-gateway / Mattermost 双向桥越来越像消息中间件。

2026-05-07: claw-bot 内网机器单独走密码 + 复用 OpenClaw（不接 Hermes）

上下文：内网 192.168.1.235 (claw-bot/CLAW 用户) 跑 OpenClaw v2026.4.1，systemd 进入 restart 循环 185 次，根因是 schema 把 allowPrivateNetwork: true 顶层字段挪进 network.dangerouslyAllowPrivateNetwork 子对象，14 处旧 config 校验失败。SSH 用户名 claw + 密码 `1qaz2wsx（首字符是反引号）。

决定：① 用 openclaw doctor --fix 一把 codemod 迁移 schema，systemctl --user restart openclaw-gateway 立刻恢复；② 不在 claw-bot 装 Hermes，保留它作为「纯 OpenClaw 节点」；③ ssh-copy-id 拷密钥免密 + ~/.ssh/config 加 alias，不再每次输密码。

为什么：claw-bot 是内网的 OpenClaw 节点，不需要 Hermes 的 messaging 接入；分散 agent runtime 反而增加部署成本。schema codemod 走官方 doctor 比手工 sed 14 处稳。

经验：升 OpenClaw 前先 openclaw doctor dry-run 看 schema diff；183+ restart loop 而 systemd 没退出 backoff 是因为 RestartSec=2s + StartLimitBurst 设得太宽松，生产建议 StartLimitBurst=5 让进程及时停摆而不是黑屏循环。详见 openclaw-config。

2026-05-07: OWL 节点 systemd 指向 `~/.local` 用户级 OpenClaw 而非 `/usr/lib`

上下文：OWL npm install -g openclaw 后版本不一致 — /usr/lib/node_modules/openclaw 是 v2026.4.5 (npm public)，~/.local/lib/node_modules/openclaw 是 v2026.5.6（用户目录新装）。systemd 默认跑 /usr/lib，但 TUI 客户端用 ~/.local，client 发 chat.send 带 sessionId 字段 → gateway v2026.4.5 schema 不认 → invalid chat.send params: at root: unexpected property 'sessionId'。

决定：systemd unit 指向 ~/.local/lib/node_modules/openclaw v2026.5.6，不要 sudo（根本不需要 root，npm user prefix 已生效）。Config “last written by newer version” 警告同时消失。

为什么：双重 npm install 是 OpenClaw 部署常见 footgun（npm global vs user prefix）。统一到用户目录避免 root/user 双轨；后续 npm i -g openclaw 也只更新一份。sudo 的本能反应是错的 —— 现代 npm + user prefix 不需要 root，sudo 反而会污染 /usr/lib 让两个版本冲突。

踩坑：v2026.5.6 beta 安装包本身缺 sidecar 文件（dist/extensions/{acpx,discord}/runtime-api.js missing bundled runtime），是 npm beta channel 打包 bug，不是本地问题；后续补装即可。

2026-05-06: Clawline 三个 repo 合并为 `clawline/platform` monorepo

上下文：之前 clawline/{channel, client-web, gateway} 三个独立 repo 各自 watch + deploy，互相依赖（gateway 改了 admin、client-web 跟着发版、channel 推 OWL/WOLF），多 PR 难协调，本地 dev 需要起三个 watcher。

决定（Levis dora 频道 14:0x）：合并到 clawline/platform monorepo，结构 apps/{channel,client-web,gateway}，pnpm workspace。旧三个 repo 标 deprecated 并本地删除，watch + auto-deploy 改为只盯 platform:dev 一个 SHA，触发时一次性顺序部署三个 app（client-web build → channel tar 推 OWL/WOLF → gateway admin build + relay 部署）。

为什么：

一个 PR 跨三个 app 的变更不再需要三次 push + 三次 review
watch 状态文件从 3 个 SHA 简化为 1 个
pnpm workspace 让共享类型/utility 直接 workspace:* 引用
当日实际跑通：feat: import channel/client-web/gateway into monorepo (phase 1) + 后续 chore + fix(client-web): scroll history load，cron 3 分钟检测 1b23c4f 自动部署成功

影响页面：clawline、clawline、clawline、monitoring-and-cron watch 段。

2026-05-06: Cron LLM 报告必须贴脚本完整 stdout，不要让 LLM 摘要（lewaymacmini push-sessions 假成功事件）

上下文：hermes-sessions-push cron（每天 04:30）连续两天报「推了 N 条」，但其实 push-sessions.sh 第 8 行 DATE=${1:-$(date -d yesterday +%Y-%m-%d)} 在 macOS BSD date 上失败（不认 -d），set -e 不会因 $() 失败触发，DATE=空 → 走 [ ! -f ] 分支输出 “no sessions” exit 0。cron prompt 让 LLM 一行汇报「推了多少条」，LLM 没看清脚本输出就编了「推了 1 条」。两天 0 条真实推送都被报成成功。

决定：所有调用脚本的 cron prompt 一律要求贴脚本完整 stdout（不摘要），由人或后续 agent 根据原始输出判断成败。「LLM 帮你看一眼」=「LLM 替你脑补」。

配套修复：push-sessions.sh 用 date -v-1d +%Y-%m-%d（macOS BSD 语法），见 hermes-agent-setup 5-06 段、monitoring-and-cron Hermes session push 段。

为什么：cron 的报告是闭环的最后一道、且无人监督——一次「LLM 自由发挥」就让 raw 数据缺失静默两天。脚本输出便宜，LLM 摘要有真实 hallucination 成本。

2026-05-03: 多机 Hermes 数据归集 — 那两台远程机器主动 POST 到本机 ingest endpoint（方案 2）

上下文：当前 wiki compactor 数据源只覆盖本机 (eagle) ~/.hermes/sessions/ + Clawline。Resley 还有另外两台跑 Hermes 的远程机器，每天的 session 没进 wiki。Discord 11:31 起讨论怎么把它们的活动也拉过来。

候选方案：

本机 SSH 拉日志：cron rsync 那两台的 ~/.hermes/sessions/ 到本机
机器主动推：那两台各跑 cron，把当日 session 摘要 POST 到本机
共享 wiki：三台都指向同一个 ~/wiki/（git 或 NFS）

决定（11:42-11:44）：方案 2 — 那两台机器自己跑 cron，把 session 摘要 POST 到本机的 HTTP ingest endpoint（带 token），落到 ~/wiki/raw/hermes-sessions-<host>/<date>.jsonl。

为什么：

反向 SSH 要在本机维护两台机器的 SSH 凭据 + 网络可达性；推模式下本机只暴露一个 token-protected endpoint，远端凭借 token 访问，权限边界更窄
共享 wiki 三台同写一个目录会撞 raw/ 文件 + git 冲突，且 NFS/同步延迟会让 compactor 看到半截文件
推模式下每台机器 schema 自治（与本机 hermes_ingest 输出一致即可），新增第 4/5 台只是再发一个 token

待办（Resley 需提供）：

那两台机器的 hostname（区分来源用，用作 hermes-sessions-<host>/ 目录名）
本机对外域名/IP（那两台能访问到的）

后续：搭好后 daily compactor 的输入源从 hermes-sessions/ 单目录扩展为 hermes-sessions*/，glob 已就位。见 hermes-agent-setup、本任务 cron prompt 已含远程目录扫描。

2026-05-02: 收银台订单同步 ERP — 加对账机制 + 失败日志（MZSC-62）

上下文：cobra 让 nexora-ops 排查”订单 C260429122215259577 没推到 ERP”。深入排查发现根因不是单笔丢失，而是结构问题：商城 app/controller/... cashier_pay() 函数被注释（return true 直接返回），收银台订单根本没进 shop_order_push_log 队列；而该队列的写入与订单”已支付”状态更新不在同一事务里 → 任何中间失败都会让订单永久消失，且无任何告警。

决定（写入 Plane Issue MZSC-62 / 妈祖商城项目 High，未上手改）：

定时对账任务 —— 每 5-10 分钟扫”已支付收银台订单 vs shop_order_push_log”，发现缺漏自动补队列
失败日志表 —— 推送失败必须写明确字段（订单号 / 失败原因 / 时间），可查可重放
事务化写入 —— 推送队列写入与订单状态更新放同事务，杜绝半成功

为什么：单纯改 cashier_pay() 治标不治本——这种”先改字段再写日志”的两步操作模式遍布商城代码，下次又会丢。对账 + 失败日志 + 事务三层兜底是结构性方案。先提 Issue 不上手是因为生产代码改动需 Daddy/cobra 评审，nexora-ops 只负责暴露问题。

详见 nexora-ops 05-02 段、nexora-mazu 05-02 段。

2026-05-01: 阿里云 OSS 三层防御 — 预存余额 + 余额预警 + 上传降级

上下文：五一假期 13:04 兴化福礼商城 www.mazugift.com 图片上传报”请求上传接口出现异常”，根因是阿里云 OSS 账户 UserDisable（欠费停服）。Daddy 充值后立即恢复，但暴露上传链路对 OSS 强依赖——OSS 一挂，整个上传接口对用户报错。

决定（节后 5 月 6 日落实，nexora-ops HEARTBEAT 提醒）：

P0 预存余额或开通自动续费 —— 根治欠费断服，5 分钟搞定
P1 开通阿里云余额预警 —— 提前告警，给充值留 buffer
P2 代码改造：uploadoss() 失败降级返回本地 URL —— 上传链路即使 OSS 挂也不再报错，影响降为”图片只在本地、未同步 OSS”

为什么：单纯充值不解决”下次又欠费”问题；单做预警仍依赖人响应。三层叠加：钱→告警→代码兜底，节后统一推动。

详见 nexora-mazu 05-01 段、holiday-incidents 待建（如 5/1-5/5 还有事件再创建）。

2026-04-30: 三个客服 Bot 全面收紧 — 不准动手 + 工单 + 纯文本 + 工时

上下文：早上 Daddy 让 mazu-cs “把网页首页一个标题改成红色”，它直接动手改了。这是越权——客服没资格改代码。dora 当场命 clawline 把三个 CS（mazu / xipu / nexora）AGENTS.md 全面收紧。

决定（对 mazu-cs / xipu-cs / nexora-cs 一致）：

🚫 严禁操作：禁止改代码 / 网页 / 配置 / 数据库；禁止 exec / git；管理员要求也必须走工单 — “你是客服不是开发者”
📋 工单机制：技术问题写 memory/tickets-YYYY-MM-DD.md，不再 ping main（最初草稿写”通知 main 处理”，下午 Daddy 改为只记录）
📨 结构化升级：触发条件命中时回复最开头输出 [ESCALATE] + [ANALYSIS: 表面诉求 / 根因 / 已确认 / 缺失 / 建议方向 / 紧急程度] 两段标记（用户看不到），再写正文。规则源在 AGENTS.md（行为规范），MEMORY.md 内重复版本删除（MEMORY 只放知识不放规则）
📝 禁止 markdown 输出：微信里 markdown 渲染不出来，纯文本 + emoji
🕗 工作时间 08:00 – 22:00，非工作时段不主动发
🧹 MEMORY 大清理：删服务器 IP / 端口 / 表前缀 / 数据库规模 / 技术栈，仅留产品名 + 业务描述
🔧 mazu-cs SOUL 升级机制冲突：旧条 “上报 main 代理” 与新工单冲突，统一改成 “升级走工单”
🔁 生效方式：cobra 选 reset 所有 session（mazu 116 / nexora-cs 8 / xipu 1）—— 比单纯重启 Gateway 彻底；接受历史对话上下文丢失代价
🧪 意外发现：上午 dora 实际之前已经加过相同的 escalate 规则（MEMORY.md 里那份），但 main 这边记忆/历史中没找到 — 推测是直接跟 mazu-cs 私聊时口头加的，没经 main，这导致同一规则被加了两遍

为什么：客服越权动手 = 单点故障；规则集中在 AGENTS.md = single source of truth；纯文本 = 微信渠道兼容；工时 = 不打扰客户。这是 multi-agent-architecture CS 子层的成文规约。

2026-04-30: 妈祖生产服务器交给 nexora-ops，走宝塔 API 而非 SSH

上下文：04-29 妈祖商城关停事件暴露”客服没权限拉起容器、Daddy 是单点 SSH 持有者”问题。Cobra 把妈祖服务器（47.96.90.171）面板凭据交给 nexora-ops，但只给宝塔 API（无 SSH）。

决定：

nexora-ops 通过宝塔 API key + 面板 URL 接管，凭据落 TOOLS.md，名 mazu
装 aapanel 技能 btpanel / btpanel-phpsite 走标准接口
接受API 白名单只放监控类的限制：CPU / 内存 / 磁盘 / 站点 / 服务可读，防火墙 / SSH / Fail2ban 等加固类必须 cobra 手动登面板做（API 返”指定参数无效”被拦）
接入 Uptime Kuma 7 个监控项（5 站点 HTTP + Nginx 80 + MySQL 3306），全部前缀 [妈祖生产服务器]
五一假期（4/30 ~ 5/5）专项：写 HEARTBEAT.md 每心跳巡检，阈值 CPU>80% / 内存>85% / 磁盘>90% / 负载>6，异常立即 push Daddy；事件归档 memory/2026-05-holiday-incidents.md，假期结束自动撤销

为什么：① 项目代理 ≠ 单点 SSH 持有者，运维代理才该有面板权 ② API 白名单虽限但够日常监控 ③ 加固类风险高，仍走人工 — 安全 - 自动化的合理边界 ④ 假期值守应该是临时机制，避免长期心跳挤占主线对话。

2026-04-29: 妈祖商城临时关停（Daddy 命令，无故障公告）

上下文：cobra 在 nexora 频道直接”把妈祖商城先关了”，nexora-mazu 立即停掉 mazugift-php 容器。35 分钟后用户经 H5 入口提工单 cmok…oswu 问”妈祖访问地址是多少”，客服侧才感知到外部影响。

决定：

关停由项目代理（nexora-mazu）执行，不公告、不开维护页（H5 直接 502）
客服 mazu-cs 没有自助拉起容器的权限 → 只能转告”需要 SSH 权限的同事”
紧急停服走”代理 → 容器”的最短链路，恢复回”Daddy 显式指令”

为什么：商城此时无在线交易压力（多次 02-04 月被 502/磁盘/MySQL 问题打断），临时停掉成本低；运维权限隔离是有意的（防止客服误操作生产）。下次恢复需要 Daddy 显式说”启动 mazugift”。

2026-04-29: Copilot Proxy 微信扫码取消 bind 屏，自动建 key + 30 万送 + 反薅全开

上下文：04-28 的微信扫码登录走”扫完先绑定一个已有 key”两步流程，对新用户不友好。Daddy 在 Discord 下午开门见山”全要全开”拍板：扫完直接给 key、送 30 万、营销三件套并行、反薅默认开。

决定：

自动建 key：finalize 落库时为该 openid 自动 issue sk-proxy-wx-… key，重复扫码连原 key；source 标 wx_signup
30 万 token 永不重置：free_quota=300000、不写 reset_at，防止每月白嫖
去重维度：openid（unionid 在 spec 第二轮被 Daddy 撤回，理由”那个可以不干”，简化实现）
营销 A + B + C 全要：用完即升 banner / 邀请返利（双方各 +5 万） / 公众号侧”回复’更多额度‘“引导
反薅默认全开：同 IP 24h ≤ 3 个新 openid 注册（黑名单 + log），每 key 60 RPM，单 key 1h 烧 30% 配额告警
实施：派 Claude Code background 同时改 proxy 仓库与 wx-gateway 公众号侧 → 当天无回执，状态见 copilot-proxy Open loops

为什么 30 万 + 永不重置而不是月度配额：保持”免费档是一次性试用”语义，配合升级 banner 形成转付费漏斗；月度重置会让薅羊毛账号永远滚下去。

2026-04-29: 永久暂停 Miss E 英语学习 cron

上下文：Miss E 已经从 04-21 起就处于 pause 状态，04-29 学生 dora stop all cron of english learing（typo 但意图明确），Miss E 把暂停升级为”永久”并停掉所有相关 cron job。

决定：miss-e 不再推日课、不再提醒、不再发选择题。student_profile.json 标 permanent pause from 2026-04-29，课程档案保留供未来恢复，但不主动发起。

为什么：连续多周低频回复 + Daddy 主动叫停 → 当前阶段对英语学习无需求，自动推送变成噪声而非提醒，关掉比降频更诚实。

2026-04-28: Copilot Proxy 默认登录改为微信扫码，API key 退为 fallback

上下文：copilot-proxy 此前只有 Logto admin SSO + API key 登录，消费方都得手输 sk-proxy-…。Resley 接 wx-gateway 统一网关后，让 user dashboard 默认走微信扫码，API key 退到 fallback tab。首次扫码用户必须绑定一个已有 API key 才能进 dashboard，避免开新账号绕过配额。

决定：

User dashboard 登录页默认 Tab = 微信扫码（SSE poll），API Key 是次选 Tab
后端 wx env 三件套（WX_GATEWAY_BASE / WX_GATEWAY_APP_NAME / WX_GATEWAY_SECRET）任缺时禁用微信但不崩，自动隐藏微信 Tab → graceful fallback
首次扫码生成 wx_pending session，必须 POST /user/bind-key 绑定已有 key 才 promote 为正常 session（同一 cookie，不重新登录）
HMAC-SHA256 timing-safe + 5 min 时间窗 + idempotent upsert，secret 永不出现在前端

为什么不一次性发 key 给新扫码用户：保持”key 是稀缺资源”的语义，避免被微信扫码绕过 Logto 审批。

2026-04-28: Copilot Proxy 根路径 `/` 切给用户，admin 移到 `/_admin`

上下文：随着 stock-dashboard 等下游接入，proxy 的”用户”开始多于”管理员”。Logto admin 占据根路径 / 反而让接入者第一眼看到一个登录提示与他们无关。

决定：

GET / 与 /index.html 返回 user dashboard（API key / 微信登录）
admin 全套搬到 /_admin 隐藏路径（/_admin /_admin/ /_admin/index.html）
/user /user/index.html 兼容保留（老链接不挂）
/callback 仍走 admin HTML（Logto SPA client-side handle，回调后跳 /_admin），Logto 控制台 redirect URI 配置无需改动
接入示例与 README 路由速查同步

2026-04-28: Hermes session_reset 闲置阈值 1 天 → 3 天

上下文：原来每天凌晨 4 点 session_reset 检查会话空闲超 1 天就清空上下文，但 Resley 反映很多对话只是夜间停顿、第二天还想接着聊，被清得太凶。

决定：

~/.hermes/config.yaml 中 idle_minutes: 1440 → 4320（=72 小时 / 3 天）
凌晨 4 点的 at_hour 不变，只放宽阈值
比”改成每 3 天才触发”更稳：每天检查，避免 cron miss

2026-04-28: 妈祖商城 H5 端走 `/h5/` 子路径，根路径继续 PHP 后台

上下文：pyerp_shop_wx（uni-app）用 npm run build:h5 编译出来的 H5 站底部 tabbar 样式严重错乱（uni-app scoped CSS 标签选择器 image[data-v-x] 在 H5 端 miss，因为 H5 把 <image> 渲染为 <uni-image>），且 H5 与小程序差异较大。Resley 拍板”目前主要在小程序上使用，H5 暂时不弄了”。

决定：

H5 编译产物保留在 ~/repos/pyerp_shop_php/h5/ 静态目录，URL https://mazugift.nexora.restry.cn/h5/
根路径 / 维持现状（PHP 后台 302 跳登录），不把 H5 提到根路径
后续若需要修：组件标签选择器 → class 选择器（已在 dp-tabbar 改过示例）
不再在 H5 端投入精力，等小程序端版本稳定后再回看

详见 nexora-mazu 04-28 段。

2026-04-27: Nexora 全项目部署规范 — 凭证一律走环境变量，禁止硬编码

上下文：cobra 排查 mazugift dev 全站 500 时发现 config.php 把数据库地址 / 用户 / 密码 / 库名全部硬编码，并曾经被改成局域网 IP 192.168.3.22（容器内根本连不上）→ 整站 500。Daddy 借这个事故要求出公告统一规范。

决定：所有 nexora 项目（pyerp / mazu / xipu / laiya / small / docs / ops 等）部署时：

数据库密码、API Key、Token 等身份凭证严禁硬编码到代码中
通过 .env 文件或环境变量注入；.env 必须加入 .gitignore，不入仓
代码中只用 getenv() / 类似机制读取，不出现明文凭证
Docker 部署统一通过 docker-compose.yml 的 env_file 或 environment 注入
现有项目逐项排查改造（mazugift config.php 已 04-27 改完，commit 30d0844）

理由：硬编码凭证除了带来”换环境就 500”风险（mazugift 案例），还让审计和轮换密码极其困难；走环境变量是 12-factor 标准。同步配套项目目录都要 git 化（mazugift 项目目录之前压根没有 git repo，cobra git init 后才能提交）。

相关：nexora-mazu 04-27 段、nexora-pyerp 04-27 段。源：clawline nexora/cobra 04-27 10:54-11:00 一系列消息。

2026-04-25: Wiki / cron 任务统一走 Copilot 订阅 = 边际成本 0 — 不额外接 GPT-5.x 付费 provider

上下文：Resley 在微信问「llm wiki 整理这个任务调了哪些模型，费用大不大」，并在 main 频道核对 GPT-5.2 / GPT-4.1 实际使用量。审计结果：6 个 wiki/日报相关 cron + 当前 Hermes session 全部用 claude-opus-4.7 via provider=copilot，是 GitHub Copilot 订阅 fixed-cost；GPT-5.2 / GPT-5.2-codex / azure-foundry/gpt-4.1 在 openclaw.json 注册但实际调用次数为 0（唯一用 GPT-4.1 的是 housework skill 的子 agent 摘要步骤）。

选项：

给 wiki / 日报 cron 单独配 Anthropic 官方 Opus 4.7（ $15/$ 75 per M token，估算 $5-15/天）以摆脱 Copilot 限流风险
保持现状：Copilot 订阅按月固定 $10-39，cron 跑多少次不额外花钱
切到便宜的 GPT-5.x（Azure Foundry）做 ingest，Opus 留给交互

决定：2 — 维持 Copilot 订阅作为唯一 LLM 通道。同步清理 openclaw.json 中没人用的 gpt-5.2 / gpt-5.2-codex / azure-foundry/gpt-4.1 注册项减少 noise（保留 github-copilot/gpt-4.1 因 housework skill 显式依赖）。

理由：定时任务 cost predictable + Anthropic 直连按 token 计费会被 wiki ingest（每天数千 token）打到 ¥30+/天；Copilot 限流可以通过 cooldown stagger / 多 token 解决（见同日 infra-alert-check 事故），不值得为了规避它单独养第二条付费链路。

后续：infra-alert-check 04-25 13:59 4 个 Copilot token 全 cooldown 暴露所有任务挤在一条订阅的脆弱性 — 见 model-provider-config 04-25 事故段。如果再发生需要补 fallback。

附澄清：dora 早先把「GPT-5.4 是 5.2 超集」误算作 GPT-5.2 调用，被 ottor / nexora 推翻，以调用次数为 0 为准（5.4 ≠ 5.2，注册 ≠ 使用）。

2026-04-24: 股神新开仓风控 — MV 百分比 → 市场分档绝对金额 cap

上下文：04-21 21:59 00700.HK real 账户清仓 @520 后 portfolio.shares=0（但 initial_shares=100），04-24 09:48 LLM 决策给 00700 新仓 100 股被 execute_decision.py 旧规则 shares × price > portfolio_MV × 10% 拒（34 万 RMB 组合 × 10% ÷ 491 ≈ 70 股 cap）。Resley 质疑：“以前买过不识别吗”—— 硬风控 held==0 分支不看历史，400+ 港币高价股在小组合下 10% 试探仓根本探不动。

选项：

加 ever_held / last_cost_basis 语义让风控区分”再入场 vs 全新仓”走 20% cap
手动把 00700 补回 portfolio 绕过
业界常用：改”单新仓绝对金额”按市场分档 cap

决定：3 — _validate_alert_payload 加 ticker/market 参数，NEW_POSITION_MAX_NOTIONAL = {HK: 50_000 HKD, CN: 30_000 CNY, US: 5_000 USD}（Resley 选”中性”档）。超限错误信息带 max_shares≈N 提示让 LLM 自动合规重试。

理由：百分比 cap 对小组合 + 高价股有结构性缺陷（cap 跟着组合缩水）；绝对金额 cap 是业内标准做法，语义直观、与市场/标的价位无关、LLM 容易理解。清仓/再入场的历史语义相对少见，塞绝对金额 cap 一步到位。

后续：见 trading-sim 04-24 里程碑。4 用例回归通过（00700 100 股@491=49.1k ✅ / 150 股@491=73.65k ❌ / 招行 1000@39.7=39.7k ❌ / 700@39.7=27.79k ✅）；下次 analyst cron (10:02) 自动生效。

2026-04-24: Prism Commander Dashboard 去股票化 — 股神内容收敛到 stock-dashboard 唯一入口

上下文：04-22 Phase 3 股神内容已从旧 Astro 站 prism-dashboard (https://dash.eagle.openclaws.co.uk) 回滚过一次（src/pages/stock/ / stock.ts / better-sqlite3 删除），但首屏 Portfolio 持仓大卡 + “项目近况”里的”持仓系统”卡片 + data.ts 内 Portfolio 数据源还留着，Resley 04-24 明确「wiki 功能里整理的股票信息可以去掉，界面上也不需要特意整理」。

选项：

只删 Portfolio 首屏大卡，保留”项目近况”项目卡做元信息
两处全删，data.ts 相关 API/类型定义一并移除

决定：2 — 派 Claude Code 清理 Portfolio · 持仓 首屏大卡 + 项目近况”持仓系统”卡 + getPortfolio/PortfolioItem/PortfolioData/PORTFOLIO_API，build + 线上生效。

理由：prism-dashboard 定位是个人知识决策平台（项目/决策/timeline/blocked），股票细节属于 stock-dashboard (stock.eagle) 专属职责，两站职能分离；留着 Portfolio 卡就是信息冗余且会跟交易系统迭代脱节。

后续：见 trading-sim。注意 open-loops.md 里”Blocked”中招行 placeholder 来自 wiki 源（不是 dashboard 硬编码），如也要清需改 wiki。

附：Resley 对 prism-dashboard 的产品优化头脑风暴（04-24，未落地）：① Top-1 Focus 首屏「今日做 X」+ 晚间回访沉淀 log；② Quick Capture（微信/Discord @Prism → open-loops）；③ 外部信号聚合卡（Clawline 未读 / GitLab MR / Plane issue）；④ 决策状态机 decided→building→shipped→stale + >7d 升红；⑤ 未读/新增 ● 标记；⑥ 项目健康度 🟢🟡🔴 + next-action。建议优先做 ①+⑤（同屏成本低）。

2026-04-23: 港股行情 Yahoo → 腾讯主源 + Yahoo fallback

上下文：04-21 已知腾讯 00700.HK Yahoo 报价失效遗留 TODO。04-23 开盘小米 1810.HK 也卡在昨收 31.80 不动（Yahoo regularMarketPrice meta 不更新、intraday bars 缺失），用户看到 dashboard 显示 17 小时前数据直接质疑”怎么这么不靠谱”。

选项：

改报价超时/重试参数硬撑 Yahoo
加 Yahoo 健康探针 + 失败自动切备源
港股全量切腾讯 qt.gtimg.cn 主源，Yahoo 退为 fallback

决定：3 — 腾讯 r_hk01810 / r_hk00700 实时正确、延迟 3 秒、字段映射稳定（3=current, 4=prev_close，踩过 pct=0/prev_close=30.94 映射错误）。Yahoo 保留为备份，A 股继续用新浪。

理由：Yahoo 港股开盘卡昨收是长期性故障（多日重现），探针切换仍有失败窗口；腾讯数据源在 CN 网络内比 Yahoo 稳定得多；用户对”17 小时前”零容忍。

后续：见 trading-sim 04-23 里程碑。cron 同日顺势优化：analyst-* 偏移到 :32/:47/:02/:17（原 */15 9-15 首跑 9:00 市场未开 skip），market-snapshot 从 */5 改 */3。

2026-04-23: 客服代理按项目拆分 — 通用 nexora-cs + 妈祖 mazu-cs + 囍铺 xipu-cs

上下文：04-21 建的 nexora-cs 承载了 8 大产品线全部客服咨询；品牌/业务差异大（妈祖 3 小程序礼品 vs 囍铺珠宝 ERP），MEMORY.md / SOUL.md 不断膨胀；客户问具体问题时代理要先分支判断品牌再回答，容易混。

选项：

继续单一 nexora-cs，按品牌条件分支
按项目拆分：通用兜底 + 妈祖专属 + 囍铺专属（兼顾徕雅）
每个 ERP / 商城都独立一个客服代理（4 ERP + 2 商城 = 6 个）

决定：2 — 04-23 新建 nexora-mazu-cs 🏮（妈祖 3 小程序 + 商城）和 nexora-xipu-cs 💍（囍铺 Web/App/销售 App，兼顾徕雅）；nexora-cs 保留跨项目/未归类问题。

理由：妈祖和囍铺是业务量最大的两条线（Plane 上 MZSC 61 条 + XIBU 5 条），拆出来可独立维护 SOUL/MEMORY；其他小业务（仙游/鸿星/黄金回收）暂不拆避免代理爆炸。每个专属代理独立 ~/.openclaw/workspace-xxx-cs/ 目录 + 独立 issues 日志。

后续：nexora-cs、nexora-mazu-cs、nexora-xipu-cs。当日首日工单：妈祖”服务器欠费小程序进不去”（充值恢复）、囍铺代收徕雅轮播图 MP4 需求。

2026-04-22: 股神 v4 — LLM 从关键路径移到旁路润色

上下文：v3 架构把 LLM 放在决策关键路径（分析 cron 直接调 LLM 产 decision），导致：调用失败 / 超时就断链；多个 cron 间决策不一致；没心跳没过期守卫，数据陈旧也推送。

选项：

继续 LLM 在关键路径，加重试兜底
脚本为事实源 + LLM 完全剔除
脚本为事实源 + LLM 仅旁路润色 reason 文案

决定：3 — analyze_v2.py 直写 ticker_analysis / alerts，硬护栏在脚本里（单日 buy/sell ≤3、价格 ±5% 等）；reason-polish 每 15 min 跑 LLM 改写 reason，失败无害；全链路加 cron_heartbeat + latest_*(max_age) 过期守卫。

理由：关键路径纯脚本 → 确定性 / 幂等 / 零依赖；LLM 只负责文案，价值高而故障代价低；每条 cron 结束写心跳让 health-check 可观察。

后续：见 trading-sim。Round 3 验收完成 85%，P1/P2 清单待处理。

2026-04-22: 股神站点单点化 — 旧 Astro `prism-dashboard` 回滚，统一到 Next.js `stock-dashboard`

上下文：04-22 之前 Phase 3 在 ~/projects/prism-dashboard/（Astro）里写了一份股神模块（stock 页面 + src/lib/stock.ts + better-sqlite3 依赖）。同时 stock-dashboard（Next.js，stock.eagle）也在维护一份更完整的实现。

选项：

保留两个站点双写
回滚 Astro，单点 Next.js
回滚 Next.js，单点 Astro

决定：2 — Astro Phase 3 股神内容全量回滚（新文件删光，global.css 股神段清理，better-sqlite3 依赖移除），stock.eagle Next.js 成为唯一股神站。

理由：Next.js 站的 LLM 决策详情 / ActionTimeline / Session Badge 已走 Round 3 深度审计；两个前端两个 DB 路径会分裂状态；成本上 Astro 站可复用给别的 Prism 面板。

后续：见 trading-sim。

2026-04-22: Hermes 网关维持单实例单账号，多微信走多开 `HERMES_HOME`

上下文：Resley 问能否把 Hermes 绑定到多个微信号。

选项：

改 hermes-agent/weixin.py 支持多账号并发 poll
每个微信号起一个独立 Hermes 实例（独立 HERMES_HOME / .env / 日志）
不做，保持一号

决定：2 — 多开 Hermes 实例（HERMES_HOME=~/.hermes-wx2 hermes gateway setup/start），互不干扰；不改 adapter。

理由：改 adapter 工作量大且耦合；多开路径零风险、调试隔离、彻底解耦；适合”一个号一个用途”（如主号个人 + 另一号专做 PM 代理 / 群专用）。

后续：见 hermes-agent-setup。

2026-04-18: Nexora 5 套 PHP ERP 统一迁移 ERPNext

上下文：莆阳网络 5 个老 PHP ERP（pyerp / xipu / xylferp / hxerp / hjhs）代码质量 3/10，PHP 7.4 EOL，贵金属子系统完成度 <30%，沉没成本接近零。2026-04-18 各项目代理出深度体检报告。

选项：

在老系统上继续二开
自研全新 ERP
迁移到 ERPNext（Frappe 框架）+ 写 nexora_jewelry Custom App
买商业 ERP

决定：3 — ERPNext + nexora_jewelry Custom App 统一平台；妈祖/莱雅保留 CRMEB；Casdoor 做 SSO。

理由：真开源免费、Python 生态、可二开、国内可达；比自研快、比商业便宜、比老系统可维护。符合”真开源 > 商业、本土化 > 国际”偏好。

后续：见 nexora。4 门栈确定 = Python (ERPNext) + PHP (CRMEB 保留) + TS (uni-app 小程序) + Go (Casdoor)。

2026-04-20: 废弃 git.xipugold.com，Nexora 内部 GitLab 成为唯一源

上下文：历史双 remote 镜像方案（xipugold.com → 本地）维护成本高，数据源不一致风险大。

选项：

继续双 remote 单向镜像
只留 xipugold.com
切到内部 GitLab（gitlab.nexora.restry.cn / 192.168.1.235:3000）为唯一真相源

决定：3 — 所有项目代理切到内部 GitLab，xipugold.com 彻底废弃。

理由：内网可控、CI runner 就近、分支保护由 nexora-ops 统一维护；避免”哪边是对的”的歧义。

后续：见 nexora-gitlab-sync。所有代理需写入 MEMORY.md 长期记忆。

2026-04-12: 从 OpenClaw 迁到 Hermes Agent，确立 Prism 身份

上下文：OpenClaw 作平台继续维护，但个人 AI Agent 主体需要一个更轻、CLI-first、可装 Discord + 微信的载体。

选项：

继续用 OpenClaw bot 作为个人主体
自己写一个
用 Nous Research 的 Hermes Agent

决定：3 — Hermes Agent 装本机，Discord 名 Resley / 微信 Michael / 统一人格 Prism。

理由：一行脚本安装、跨平台、社区活跃、可装技能（skills）、native MCP；自写不划算。

后续：见 hermes-agent-setup、openclaw-vs-hermes、prism-multi-agent-config。

2026-04-06: 自建 Copilot→Anthropic 代理（不买 Anthropic API）

上下文：Claude API 官方定价贵，但本人有 GitHub Copilot Enterprise（可代理调 Claude）。

选项：

直接买 Anthropic API Key
用国内中转（eaips 等）
自建代理，把 Copilot 协议转成 Anthropic 格式

决定：3 — github-copilot-anthropic-proxy，端口 4819，域名 api.eagle.openclaws.co.uk。2026-04-19 升级为多模型 + 多用户 + 配额计费小型分发平台。

理由：成本接近零、可控、顺带给别的 bot 用；折腾一次长期受益。符合”真开源 / 自建优先”。

后续：见 copilot-anthropic-proxy、eaips-provider-migration。

2026-04-07: Wiki 架构按 Karpathy 分层（raw + wiki + compactor）

上下文：聊天记录积累到 ~8MB，RAG 效果差，LLM 需要的是”结构化碎片 + 链接”而不是原始长文本。

选项：

上 RAG / 向量检索
让 LLM 每次从原始聊天读
Karpathy LLM Wiki 模式：raw（原始不可变）+ wiki（LLM 编译的结构化 md）+ compactor（cron 定期合并）

决定：3。

理由：检索成本低（直接 read md）、人类可编辑、Obsidian 原生支持；跟”外置大脑”的长期目标更一致。

后续：见 llm-wiki。凌晨 3:00 CST cron clawline-wiki-ingest 自动摄入。

2026-04-07: Quartz 作为 Wiki 静态站发布

上下文：wiki 要能在手机 / 外网浏览，Obsidian 只能本地。

选项：

Obsidian Publish（付费）
Docusaurus / VitePress
Quartz 4（专为 Obsidian 风 wiki 设计）

决定：3 — Quartz，Caddy HTTPS 反代。

理由：原生支持 [[wikilinks]] 和 frontmatter、开源免费、graph view、全文搜索现成。

后续：rebuild_index.py 需集成热度算分（第一次写完被 rebuild 覆盖了）。见 llm-wiki。

2026-04-11: Prism 多 Agent 架构（5 个独立 agent + 路由）

上下文：单 agent 处理不了同时跑的股票监控 / Clawline 消费 / 微信 / Discord / 研究。

选项：

单 agent 多 session
多实例 + 消息路由

决定：2 — 5 个 agent（main / research / fries / …）+ Clawline 路由。

理由：隔离上下文、独立失败、可并行；跟”PM 派工”模式天然契合。

后续：见 prism-multi-agent-config、multi-agent-architecture。

🔮 Dora's Wiki

探索

Decisions Log (ADR)