ops/ —— 运维与架构文档
本机（dlc · CachyOS）与 agent 舰队的运维、架构、故障修复文档。改 Hermes / 改服务器 / 排障之前先来这里查，不要凭记忆动手。
目录沿革：2026-10-06 仓库由
${DATA_ROOT}/ku/avault先上移到${DATA_ROOT}/avault，同日按机主要求再改名并落到${KNOWLEDGE_ROOT}——现在本地路径是${KNOWLEDGE_ROOT}。2026-10-02 仓库由hermes-vault改名为agent，同日再改名为avault。2026-09-19 曾把本机运维文档单独归到 vault 根的personal-ops/，后来合并回ops/——本库运维正文归在ops/；私密旧文档另在${AI_ARCHIVE_ROOT}/.private/personal-ops/。旧personal-ops/不能一律映射为ops/，须按文件性质确认去处。
统计：69 篇 Markdown（根级 50 篇 + 子目录 19 篇），另有脚本文件。2026-10-09 按实际文件计数。
上下文与舰队维护
-
Skill Atlas 私网预览：逐项技能初评网页、零新增费用约束、数据覆盖、部署与验证边界。
-
Awesome Skills 聚合评估：目录与技能包区别、来源/许可、重复与本机候选优先级。
-
共享技能库 GitHub 更新与归档：原生简述索引、上游版本、使用证据、兼容更新与回退。
-
上下文优化验收（2026-10-25）：三套记忆、harness 指导入口、技能去重与精简，含备份和未验证边界。
-
迁出的领域知识与待核实事项：保留 Ark、Alens、部署布局等经验，旧快照不作为当前状态。
先读这几篇（现行有效的高价值文档）
被日常噪声埋没、但实际每次都要查的：
| 文件 | 为什么重要 |
|---|---|
gateway-runtime-运维规则.md | Hermes 运维踩坑录，所有 agent 从真实错误里攒的规则。改 Hermes 前后必读 |
write-gate-principles.md（在 ../architecture/） | 多层记忆总纲 + Write Gate |
lessons/check-service-before-start.md | 启动服务前先查是否已在跑（踩过：重复拉起 agentmemory / iii engine） |
retrospects/20260812_killmode_proxy.md | 代理 killmode 复盘 |
kanban-orchestration-v0.05.md | 多 agent 编排的最新结论（v0.04 仅作历史） |
目录结构
根级 50 篇 —— 按主题分组
Hermes / Gateway 运行时（含历史故障修复记录；执行前核对当前 Hermes 版本）
| 文件 | 说明 |
|---|---|
gateway-runtime-运维规则.md | 运维踩坑录：Discord 平滑自重启、进程与连接验收、2026-10-26 修复交接 |
Hermes gateway 鲁棒性永久修复方案.md | watchdog 止血 + 根因修复路线 |
systemd user 方案.md | 用 systemd user unit 接管 gateway 启动，终结手动 --replace 的崩溃链 |
修复service bug.md | 关键教训：改 service 模板源头 hermes_cli/gateway.py，不要 patch 生成的 service 文件（会被覆盖） |
webhook-wake-mechanism.md | gateway 平滑重启入口与 webhook 历史说明（已撤回 nohup 建议） |
| hermes-fork-management.md | 固定候选、三实例加载核验，900k 别名负缓存、绑定账号 fallback 与启动器边界 |
| hermes-update-20261026.md | 2026-10-26 更新、回滚、Discord 远程重启及 900k 映射修复 |
selfcheck-soma-20261006.md | 全面自检（soma 视角）：P0 No LLM provider configured 根因+修复复验、四个误报撤回、技能库口径修正 |
system/selfcheck-soma.py | 上面那篇的可复跑脚本（10 节：主机/RSS/服务/错误窗口/网络/凭据/记忆栈/技能/磁盘/暴露面）。跑法 python3 -u <路径>，-u 必须加 |
full-selfcheck-20261006.md | 全面自检（alaya 视角）：主机资源、服务层、磁盘、暴露面。与上面两篇互补不重复 |
舰队 / 多 Agent 架构
| 文件 | 说明 |
|---|---|
multi-agent-system-version.md | 历史版本总账（v0.03 层级设计）；当前角色参见 ../agents/ 档案和实时配置 |
kanban-orchestration-v0.05.md / -v0.04.md | 编排方案，读 v0.05 |
agent-communication-architecture.md | 已弃用的 NATS 决策历史；当前监听与共享知识服务见 ../AGENT.md |
agent-role-framework-v3.md / -unified-researcher / -worker-team-manager | 角色定义（多版结论有冲突，以 v3 为准） |
alaya-service-stack.md / alaya-worker-team.md / alaya-team-soul.md / alaya-worker-team-providers.md | Alaya 侧服务栈与 worker team |
worker-leader-soul.md / manas-worker-team.md | 编排员 / Manas worker team |
manas-alignment-log.md / anchor-alignment-2026-07-20.md | 跨 agent 对齐日志 |
Anet · 加密通信
| 文件 | 说明 |
|---|---|
anet-encrypted-agent-fabric.md | Anet v0.5.2：传输无关的加密存储转发 fabric，自研 |
Anet 备用沟通协议.md | 备用沟通通道 |
anet-migration-complete.md | 迁移记录（配对记录 anet-wsl-manas-paired.md 已归档至 wsl-era-archive） |
gfw-resilient-communication.md | GFW 随时可能掐 Discord，LAN 内必须能通信 |
netcheck-gfw-detection.md | 每 5 分钟探 7 个域名，4 级分类 |
Provider / 免费模型 / Token 成本
| 文件 | 说明 |
|---|---|
| hermes-chatgpt-dual-account-models-guide.md | 双 ChatGPT 账号模型列表制作与更新：独立目录、候选预览、哈希计划、缓存应用和验收 |
| hermes-chatgpt-auth-maintenance.md | 双 ChatGPT 认证维护：故障类别、独·立账号边界、上游修·复与私有证据交接 |
free-provider-architecture-v1.md | 2026-07 免费渠道与 fallback 方案；较新实测策略见 ../agents/opencode/provider-free-only-and-go.md |
token-saving-architecture-v1.md | 额度耗尽时把非关键任务分发到免费模型 |
groq-free-provider-added.md | 2026-07 Groq 接入记录（2026-10-09 已移除正文凭证；当前额度未重验） |
记忆后端
| 文件 | 说明 |
|---|---|
decision-unified-memory-gbrain.md | 架构决策：三个并行记忆系统 → 统一到 gbrain |
gbrain-embedding-migration-20260621.md | Jina 余额不足 403 → 切 zeroentropyai:zembed-1 |
scope-recall-migration-20260623.md | 134 条记忆迁移记录 |
手机 / 远控
| 文件 | 说明 |
|---|---|
android-adb-phone-access.md | ADB 无线调试连接信息 |
phone-mcp-server.md | 手机 ADB 包装成 MCP（${LOCALIP}:5560/mcp，alaya-phone-mcp.service） |
phone-dual-channel-mcp.md | 双通道：LAN 优先 + Tailscale 备用 |
termux-ssh-phone-access.md | Termux SSH（Tailscale 8022） |
站点 / 发布
| 文件 | 说明 |
|---|---|
website-518964-20261025.md | 518964.xyz Cloudflare Pages 公网发布与运维 |
website-905527-20260829.md | 905527.xyz 站点档案（描述的是 WSL 时代形态，当前为 CachyOS，结构以实际为准） |
约束 / 禁区
| 文件 | 说明 |
|---|---|
restricted-yunlu-minganci-2026-08-14.md | 禁区文件清单：哪些文件发 API 会触发 400 Content Exists Risk |
⚠️ WSL 时代遗留（2026-10-03 已归档）
WSL / Windows 形态的运维文档已全部移出本库，归档至
${AI_ARCHIVE_ROOT}/wsl-era-archive/（含说明该目录的 README.md）。
| 已归档文件 | 过时点 |
|---|---|
wsl-windows-operations.md | WSL 操作 Windows 手册 |
windows端.md | ToolHost 方案 |
windows-dev-root-git-v1.md | Windows 开发根 D:\dev |
anet-wsl-manas-paired.md | WSL 内配对 |
注意区分：路径变了，服务没变。 迁移时所有服务完整迁移过来
（portal :88 / LAN :89–93 / gbrain / OpenViking 均在跑），
端口与路径均需核对 ../AGENT.md 的 2026-10-09 快照。${DATA_ROOT} 仍是有效挂载点；过期的是具体 WSL 时代路径，不能一概判废。
另：architecture/humon/humon-windows-device-continuity-v1.md
（跨 WSL 边界感知 Windows）属于与旧 WSL 环境绑定的历史方案 —— 它要解决的问题已不存在。
子目录
| 目录 | 内容 |
|---|---|
setup/ 7 篇 | 安装配置手册：discord-bot-setup / profile-setup / provider-api-keys / proxy-config / service-management / system-maintenance / knowledge-index |
system/ 4 篇 | ark-agentplan-models-20260918（Agent Plan 模型与输出上限对照）/ CoS-Chat-On-Steroids安装说明 / file-system-inventory-20260812 / 上游反馈-待提交（KDE 等上游 feature request 草稿） |
system-services/ 3 篇 + 脚本 | systemd 服务台账：humon-webui / hermes-memos-bridge / g4f-api / computer-use-vs-chrome-cdp（inventory-2026-07 已归档） |
lessons/ 1 篇 | 教训沉淀，一条一篇 |
retrospects/ 1 篇 | 故障复盘 |
memory-reflection/ 2 篇 | 记忆反思快照（2026-06-23） |
email/ 1 篇 | 邮箱清理方案.md |
legacy/ 空 | 历史占位 |
Discord/ 2 个脚本 | check_discord.py / check_python.bat |
ops/setup/共七份手册；部分开头有早期批量生成的重复段落。重复不构成有效性证据，具体命令仍须按当前配置核对。
邮箱管线脚本的路径（2026-10-02 已修）
~/.local/bin/mail-{plan,judge,rescue,audit,preflight} 输出路径写死，原先指向 personal-ops/email/——那目录已不存在（文件被隔离到 .private/），跑起来会 FileNotFoundError；更糟的是一旦手动建了目录，含真实第三方邮箱的明文清单会被写回发布面。
已修：5 个脚本的输出路径在当时改为 .private/personal-ops/email/，并加 os.makedirs(..., exist_ok=True)。旧脚本备份在 ~/.local/bin/mail-*.bak-privpath-*。
| 脚本 | 输出文件（2026-10-02 修改记录；当前脚本路径未重验） |
|---|---|
mail-plan | 邮箱清理清单.md（由 mail-judge 读取作输入） |
mail-judge | 邮箱清理清单.md |
mail-rescue | 待二次审阅.md |
mail-audit | 废纸篓审计.md |
mail-preflight | 删除前预检.md |
改文件名/位置时要同步改这些脚本。
发布注意（本站点会渲染 ops/）
ops/ 会被站点渲染；2026-10-09 源目录有 69 篇 Markdown，构建页面数未在本次重验。因此：
groq-free-provider-added.md的明文凭证已于 2026-10-09 从当前正文移除；内网和 private 仓库不能作为把凭证写入页面及索引的理由。本次未清理既有 Git 历史或站点构建产物，也未更改账号凭证。ops/Discord/bot.log、bot.py、bot.py.backup已在隔离清单里，不要再改动其位置，否则上次那次「同源拷贝漏隔离」会复现- 往
ops/放任何含凭据 / 邮箱 / 手机号 / 内网地址的文件之前，先确认.private/而不是ops/
相关目录
- 记忆机制 / 元规范 →
../meta/ - 架构设计 →
../architecture/ - 研究报告 →
../research/ - 已隔离的敏感文件（本目录被移走的那些）→
${AI_ARCHIVE_ROOT}/.private/ops/、${AI_ARCHIVE_ROOT}/.private/personal-ops/（不在本 vault）