Server Operation & Maintenance Manual

• 适用范围：云端控制机 / Windows 本机工作区执行 / 备用运行机 fallback / Golutra 技术吸纳分析
• 版本标识：Naikaku Manual Series / Rev. 4.1

第 0 章 区域导航与资料入口

0.1 这本手册现在兼任 服务器体系 总入口

这本总手册现在不仅负责技术说明，也兼任 服务器体系 的主导航文档。

边界说明：本文只承担服务器体系专题的总入口，不承担项目总体 current-state 三件套职责；若要判断项目现在的总体状态，优先看 PROJECT-CONTEXT.md、SESSION-HANDOFF.md、plan.md。

这样做的原因是：

• 导航要和高信息量文档合一
• 不再单独制造薄弱的 首页.md / 目录.md
• 进入这个区域后，直接落到真正有内容的总文档，而不是再跳一层空页

0.2 当前推荐阅读入口

• 想看当前 live 运维口径、机器角色、前端入口、真源映射 -> 优先看后文“服务器资产与角色规划总表”中的 一、结论速览 到 十一、服务器配置映射表 / 真源表
• 想看这轮最新的前端 / 域名 / API 映射与漂移判断 -> 优先看 五、已部署网页前端 / 域名清单 与 十一、服务器配置映射表 / 真源表
• 想看完整体系定义、角色分工、协议、状态机、示例 -> 再看正文第 0~18 章与附录吸收材料
• 想快速定位接口、字段、JSON、错误码 -> 见附录 C
• 想从基础概念和机器分工开始补课 -> 见附录 B
• 想看技术研判、模块拆解与 MCP / Skill 分析 -> 见附录 D
• 想逐章对照原体系设计并看实施提醒 -> 见附录 E
• 想看服务器资产、机器档案、数据库接入与原始记录 -> 见附录 F
• 想按服务器 / 模块 / 真源入口快速跳转 -> 服务器手册伴随仪表盘.md
• 想看 MCP 清单与安装记录 -> MCP 清单总表.md
• 想看 Atramenti-Console 相关补充说明 -> ..\codex-knowledge\60-reference\atramenti-console-doc-index.md

0.3 当前区域结构

agent/
├─ Server Operation & Maintenance Manual.md  <- 唯一主文档 / Markdown 真源
├─ 服务器手册伴随仪表盘.md                <- 浏览层 / 快速入口 / 嵌入 Bases
├─ 服务器手册伴随视图.base                <- Bases 交互视图
├─ MCP 清单总表.md
└─ ../codex-knowledge/60-reference/atramenti-console-doc-index.md

0.4 放置原则

这个区域以后按下面规则持续维护：

• 总手册作为唯一主文档持续吸收同主题衍生稿
• 伴随仪表盘只做浏览层与聚合入口，不复制服务器事实，不替代主手册或 repo 真源
• 被主文档吸收的教学稿、速查稿、拆解稿、批注稿不再独立并行维护
• md / pdf / images / html / css 仍按导出链路管理，但 Markdown 真源统一收敛到主文档
• MCP 管理方法与清单单独收敛到 MCP 清单总表.md，不要再把 MCP 教程/安装记录塞回本手册正文
• 不再额外保留重复解释用的根目录首页、分叉手册或平行版本

0.5 本次整合后的组成方式

• 当前运维说明书主干：后文“服务器资产与角色规划总表”中的 一、结论速览、二、当前环境总表、三、机器详细档案、五、已部署网页前端 / 域名清单、十一、服务器配置映射表 / 真源表
• 正文第 0~18 章：体系定义、角色分工、协议、状态机、API、SOP、源码解析（偏体系/教学/吸收材料）
• 附录 A：名词表
• 附录 B：服务器体系教学导读
• 附录 C：接口与字段速查
• 附录 D：技术拆解与研判
• 附录 E：逐章批注与实施说明
• 附录 F：服务器资产与角色规划总表
• 伴随仪表盘：按服务器、按业务模块、按真源入口浏览主手册与相关配套文档

目录

• 第 0 章 使用索引与阅读导航
  • 0.1 阅读方式
  • 0.2 检索索引页
  • 0.3 图表索引
  • 0.4 接口索引
  • 0.5 关键术语索引
• 第 1 章 项目定义
  • 1.1 Naikaku 是什么
  • 1.2 一句话目标
  • 1.3 与 Golutra 的关系
  • 1.4 非目标
• 第 2 章 来源、作者与项目说明
  • 2.1 上游项目来源
  • 2.2 上游作者信息
  • 2.3 建议的项目来源声明模板
• 第 3 章 Naikaku 相对 Golutra 的创新点
  • 3.1 继承点
  • 3.2 创新点
    • 控制机中心化
    • SSH 多服务器协同体系
    • 本机工作区优先执行
    • 离线自动回退
    • 任务对象化
    • Runner 协议化
    • 可审计工程闭环
• 第 4 章 机器结构与角色分工
  • 4.1 控制机：124.220.233.126
  • 4.2 主执行机：Windows 本机
  • 4.3 备用执行机：121.196.202.114
  • 4.4 补位机：111.228.6.224
• 第 5 章 工作区模型
  • 5.1 工作区类型
    • 主工作区 primary
    • 镜像工作区 mirror
    • 公共工作区 shared
  • 5.2 任务工作区策略
    • local_only
    • prefer_local
    • cloud_ok
  • 5.3 工作区注册字段
• 第 6 章 AI 员工岗位设计
  • 6.1 岗位与执行器映射
  • 6.2 岗位设计原则
• 第 7 章 任务对象规范
  • 7.1 核心字段
  • 7.2 任务状态机
  • 7.3 状态转换原则
• 第 8 章 Runner 协议手册
  • 8.1 Runner 核心标识
  • 8.2 注册协议
    • 注册时机
    • 注册请求体
    • 注册响应体
  • 8.3 心跳协议
    • 心跳字段
    • 心跳频率建议
  • 8.4 拉任务与 ACK
  • 8.5 日志流协议
  • 8.6 Artifact 规范
  • 8.7 fallback 规则
  • 8.8 标准错误码
• 第 9 章 完整 JSON 示例
  • 9.1 Runner 注册请求
  • 9.2 心跳请求
  • 9.3 拉任务响应
  • 9.4 ACK / 日志 / 最终结果
  • 9.5 fallback 重新分配示例
• 第 10 章 状态机与接口时序索引页
  • 10.1 任务状态机
  • 10.2 注册时序
  • 10.3 心跳时序
  • 10.4 派单时序
  • 10.5 回传时序
  • 10.6 fallback 时序
• 第 11 章 模块调用关系图
  • 11.1 总体调用结构
  • 11.2 聊天到终端执行链路
• 第 12 章 124 控制机 API 规范
  • 12.1 推荐接口清单
  • 12.2 API 原则
• 第 13 章 Windows 主执行机 SOP
  • 13.1 启动前检查
  • 13.2 任务执行流程
  • 13.3 停机流程
  • 13.4 本机异常处理
• 第 14 章 Golutra 源码解析摘要
  • 14.1 技术栈总览
  • 14.2 顶层目录职责
  • 14.3 前端主模块
  • 14.4 后端主模块
  • 14.5 关键执行链路
  • 14.6 对 Naikaku 的启示
• 第 15 章 字段字典表
  • 15.1 按模块归类
    • Runner 模块
    • Workspace 模块
    • Task 模块
    • Result / Log 模块
  • 15.2 按字母序索引
• 第 16 章 错误码与恢复动作对照表
• 第 17 章 如何正确输出文档
  • 17.1 输出原则
  • 17.2 正确流程
  • 17.3 禁止事项
• 第 18 章 结论
• 附录 A 名词表
• 附录 B 服务器体系教学导读
• 附录 C 接口与字段速查
• 附录 D 技术拆解与研判
• 附录 E 逐章批注与实施说明
• 附录 F 服务器资产与角色规划总表

第 0 章 使用索引与阅读导航

0.1 阅读方式

本手册当前分成两层阅读方式：

• 如果你要做当前部署、排障、服务映射、域名/端口核对，优先读后文“服务器资产与角色规划总表”中的当前运维章节；
• 如果你要补体系背景、协议定义、教学材料、历史吸收内容，再按正文第 0~18 章与附录顺序阅读。

0.2 检索索引页

0.3 图表索引

0.4 接口索引

0.5 关键术语索引

第 1 章 项目定义

1.1 Naikaku 是什么

Naikaku 是一个面向多服务器协同、云端控制、本机优先执行的 AI 员工平台。它继承 Golutra 在多成员协作、工作区组织与终端执行方面的优势，并把这些能力吸纳进你自己的服务器体系中，形成更适合 SSH 多机协同、本机代码优先修改、离线自动回退和长期运维的开源项目。

1.2 一句话目标

让云端 AI 员工常驻在 124，接到任务后优先修改本机 E:\My Project 的真实代码；若本机不在线，则自动切换到备用工作区继续执行，并把状态、日志、结果统一回传到 Naikaku 面板。

1.3 与 Golutra 的关系

Naikaku 不是凭空重新发明，而是：

• 吸纳 Golutra 的核心技术思路
• 解析 Golutra 的源码结构与执行链路
• 保留其有价值的协作壳、成员语义、终端引擎思想
• 在此基础上加入你自己的服务器体系、任务对象、runner 协议、主工作区优先策略和 fallback 机制

Naikaku 可以明确表述为：

一个基于 Golutra 技术吸纳与扩展而产生的开源项目。

1.4 非目标

当前阶段的 Naikaku 不是：

• 完全脱离 Golutra 思想的全新范式产品
• 纯 provider-native 的托管式大模型平台
• 只做聊天 UI 的网页壳
• 用聊天消息取代任务系统本身

第 2 章 来源、作者与项目说明

2.1 上游项目来源

Naikaku 当前吸纳的核心上游项目为：

• 项目名：golutra
• 仓库地址：https://github.com/golutra/golutra
• 官方站点：https://www.golutra.com/
• 仓库定位：多成员协作 + CLI 终端编排 + 项目工作区桌面应用

2.2 上游作者信息

根据仓库 README，目前公开说明的作者为：

• 作者：seekskyworld
• GitHub：https://github.com/seekskyworld

2.3 建议的项目来源声明模板

建议在 Naikaku 的公开 README 或文档前言中使用类似表述：

Naikaku is an open-source project developed by absorbing and extending technical ideas from Golutra. It preserves valuable concepts such as workspace-oriented collaboration, member-driven execution, and terminal-based orchestration, while introducing a new control-plane architecture, runner protocol, multi-server SSH coordination, and local-workspace-first execution strategy.

中文建议：

Naikaku 是一个基于 Golutra 技术吸纳与扩展而形成的开源项目。它保留了工作区协作、成员驱动执行、终端编排等有价值的设计理念，并在此基础上加入了控制面架构、runner 协议、多服务器 SSH 协同和本机工作区优先执行策略。

第 3 章 Naikaku 相对 Golutra 的创新点

3.1 继承点

Naikaku 直接吸纳了 Golutra 的以下核心思路：

• workspace 作为核心组织单位
• member 作为执行身份载体
• conversation 作为任务触发入口
• terminal session 作为执行器承载方式
• 多 CLI 的统一协作壳设计

3.2 创新点

控制机中心化

把 124.220.233.126 明确设为控制机，而不是仅作为部署宿主，形成稳定控制面。

SSH 多服务器协同体系

将 Naikaku 纳入你的 SSH 多服务器协同体系，允许控制机调度本机、运行机和备用机。

本机工作区优先执行

引入主工作区优先策略，使系统优先修改 E:\My Project 的真实代码，而不是随意在云端镜像目录工作。

离线自动回退

当本机不在线时，自动切换到备用工作区继续执行，而不是让任务丢失。

任务对象化

从“聊天驱动执行”升级到“任务对象驱动执行”，便于审计、重试、排队与生命周期管理。

Runner 协议化

把执行机抽象为 runner，并定义注册、心跳、拉任务、ACK、日志回传、终态回传与 fallback 规则。

可审计工程闭环

不只显示聊天结果，还记录日志、产物、状态变更、错误码和 fallback 轨迹。

第 4 章 机器结构与角色分工

_ 图 4-1 Naikaku 多服务器控制 / 执行 / fallback 部署结构图 _

4.1 控制机：124.220.233.126

职责：

• Naikaku 云端入口
• 成员与任务管理
• runner 注册与心跳管理
• 调度决策
• 日志与结果汇总

4.2 主执行机：Windows 本机

职责：

• 挂载真实工作区 E:\My Project
• 执行高优先级代码任务
• 回传日志、结果与差异

4.3 备用执行机：121.196.202.114

职责：

• 挂载镜像工作区
• 接管本机离线时的任务
• 跑长任务、批量任务与脚本任务

4.4 补位机：111.228.6.224

职责：

• 提供补位执行能力
• 托管公共工作区
• 作为兜底执行位

第 5 章 工作区模型

5.1 工作区类型

主工作区 primary

• 位置：Windows 本机 E:\My Project
• 含义：最真实、最权威的开发目录
• 优先级：最高

镜像工作区 mirror

• 位置：121
• 含义：当本机不可用时承接任务的备用目录
• 优先级：第二

公共工作区 shared

• 位置：121 或 111
• 含义：不依赖本机真实文件的任务目录
• 优先级：第三

5.2 任务工作区策略

local_only

• 仅允许在主工作区执行
• 本机离线时，任务状态进入 waiting_local
• 不允许 fallback

prefer_local

• 优先主工作区
• 主工作区离线时可自动切到 mirror
• 再失败时可按策略尝试 shared

cloud_ok

• 可直接在 mirror 或 shared 工作区执行
• 适用于分析、文档、扫描、脚本和低耦合编码任务

5.3 工作区注册字段

第 6 章 AI 员工岗位设计

6.1 岗位与执行器映射

6.2 岗位设计原则

• 控制层岗位负责决策，不直接承担所有执行
• 执行层岗位尽量与具体 CLI 能力绑定
• 高风险动作可通过 reviewer / deployer 增加控制环节

第 7 章 任务对象规范

7.1 核心字段

7.2 任务状态机

标准状态建议为：

• queued
• assigned
• running
• streaming
• waiting_local
• fallback_pending
• succeeded
• failed
• cancelled
• blocked

7.3 状态转换原则

• 所有状态更新必须幂等
• 已终态任务不允许被低优先级状态覆盖
• running -> fallback_pending -> assigned -> running 是合法回退链路
• local_only 任务在本机离线时只能进入 waiting_local

第 8 章 Runner 协议手册

8.1 Runner 核心标识

8.2 注册协议

注册时机

• 首次启动
• 版本更新后首次启动
• 机器重启后恢复运行
• 控制机显式要求重新注册

注册请求体

{
  "runnerId": "win-main-001",
  "runnerName": "Windows Main Runner",
  "machineRole": "primary-executor",
  "host": "NEVERLETMEGO",
  "os": "windows-11",
  "version": "0.1.0",
  "capabilities": ["codex", "claude", "gemini", "shell"],
  "maxConcurrentTasks": 2,
  "workspaces": [
    {
      "workspaceId": "ws-my-project-primary",
      "name": "My Project",
      "path": "E:\\My Project",
      "kind": "primary",
      "priority": 100,
      "writable": true,
      "healthy": true
    }
  ]
}

注册响应体

{
  "accepted": true,
  "runnerLeaseSec": 60,
  "heartbeatIntervalSec": 15,
  "serverTime": "2026-04-17T10:00:00Z"
}

8.3 心跳协议

心跳字段

心跳频率建议

• 正常：15 秒
• 高负载：10 秒
• draining：10 秒
• 连续 3 次心跳缺失视为离线

8.4 拉任务与 ACK

• 推荐模式：长轮询拉取，后续可切换到 SSE / WS
• 接单后必须先 ACK，再正式进入执行
• ACK 至少包含：taskId、runnerId、workspaceId、acceptedAt、leaseSec

8.5 日志流协议

规则：

• sequence 必须单调递增
• 控制机按 taskId + sequence 去重
• 单条日志过大时必须拆片

8.6 Artifact 规范

建议 artifact 类型：

• patch
• diff-summary
• test-report
• build-log
• screenshot
• notes

字段至少包含：type、name、path、size、checksum

8.7 fallback 规则

• local_only 不允许 fallback
• prefer_local 优先主工作区，失败后可依次退到 mirror、shared
• fallback 前必须释放旧锁
• fallback 后必须重新 ACK
• traceId 不变

8.8 标准错误码

• WORKSPACE_NOT_FOUND
• WORKSPACE_UNHEALTHY
• EXECUTOR_MISSING
• TASK_TIMEOUT
• GIT_DIRTY_BLOCKED
• LOCK_CONFLICT
• LOCAL_ONLY_OFFLINE
• RUNNER_DRAINING
• RUNNER_OFFLINE
• ARTIFACT_UPLOAD_FAILED
• LOG_STREAM_BROKEN
• AUTH_INVALID

第 9 章 完整 JSON 示例

9.1 Runner 注册请求

{
  "traceId": "trace_register_win_main_001",
  "runnerId": "win-main-001",
  "runnerName": "Windows Main Runner",
  "machineRole": "primary-executor",
  "host": "NEVERLETMEGO",
  "os": "windows-11-23h2",
  "version": "0.1.0",
  "capabilities": ["codex", "claude", "gemini", "shell"],
  "maxConcurrentTasks": 2,
  "workspaces": [
    {
      "workspaceId": "ws-my-project-primary",
      "name": "My Project",
      "path": "E:\\My Project",
      "kind": "primary",
      "priority": 100,
      "repoHints": ["Atramenti box", "Atramenti-Console", "MyBlog"],
      "writable": true,
      "healthy": true
    }
  ]
}

9.2 心跳请求

{
  "traceId": "trace_heartbeat_win_main_001_100015",
  "runnerId": "win-main-001",
  "sentAt": "2026-04-17T10:00:15Z",
  "status": "online",
  "activeTaskCount": 1,
  "queueDepth": 0,
  "currentTaskIds": ["task_20260417_001"],
  "workspaceHealth": [
    {
      "workspaceId": "ws-my-project-primary",
      "healthy": true,
      "writable": true,
      "freeDiskGb": 128.4,
      "gitAccessible": true
    }
  ],
  "systemLoad": {
    "cpuPercent": 22,
    "memoryPercent": 61,
    "diskPercent": 48
  }
}

9.3 拉任务响应

{
  "traceId": "trace_pull_win_main_001_100020",
  "tasks": [
    {
      "taskId": "task_20260417_001",
      "traceId": "trace_task_20260417_001",
      "projectId": "proj_naikaku_cloud",
      "workspacePolicy": "prefer_local",
      "preferredWorkspaceId": "ws-my-project-primary",
      "preferredRunnerId": "win-main-001",
      "title": "修复 runner 心跳重连问题",
      "instruction": "定位 runner 在网络抖动后无法恢复心跳的原因，修复并补充重试退避。",
      "roleHint": "codex-engineer",
      "executorHint": "codex",
      "priority": "high",
      "timeoutSec": 1800,
      "fallbackAllowed": true,
      "repoRef": "Atramenti box",
      "targetPath": "golutra",
      "requiresApproval": false,
      "createdBy": "dispatcher-124",
      "createdAt": "2026-04-17T10:00:18Z",
      "metadata": {
        "branch": "main",
        "allowDirtyWorkspace": false
      }
    }
  ]
}

9.4 ACK / 日志 / 最终结果

{
  "traceId": "trace_ack_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "workspaceId": "ws-my-project-primary",
  "acceptedAt": "2026-04-17T10:00:21Z",
  "leaseSec": 1800,
  "executor": "codex"
}

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "sequence": 17,
  "stream": "stdout",
  "content": "[step] retry policy patched, running local verification...",
  "emittedAt": "2026-04-17T10:03:18Z"
}

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "finalStatus": "succeeded",
  "summary": "已修复心跳重连逻辑，加入指数退避和状态恢复保护。",
  "startedAt": "2026-04-17T10:01:00Z",
  "finishedAt": "2026-04-17T10:12:00Z",
  "artifacts": [
    {
      "type": "patch",
      "name": "runner-heartbeat.patch",
      "path": "artifacts/task_20260417_001/runner-heartbeat.patch",
      "size": 18244,
      "checksum": "sha256:abc123"
    },
    {
      "type": "test-report",
      "name": "runner-heartbeat-test.txt",
      "path": "artifacts/task_20260417_001/runner-heartbeat-test.txt",
      "size": 4210,
      "checksum": "sha256:def456"
    }
  ],
  "stats": {
    "logLines": 320,
    "filesChanged": 3,
    "durationSec": 660
  }
}

9.5 fallback 重新分配示例

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "fromRunnerId": "win-main-001",
  "toRunnerId": "aliyun-backup-001",
  "fromWorkspaceId": "ws-my-project-primary",
  "toWorkspaceId": "ws-my-project-mirror-121",
  "reason": "RUNNER_OFFLINE",
  "fallbackAt": "2026-04-17T10:06:30Z",
  "attempt": 1
}

第 10 章 状态机与接口时序索引页

10.1 任务状态机

_ 图 10-1 任务对象状态机：从排队、执行到 fallback 与终态闭环 _

10.2 注册时序

_ 图 10-2 Runner 注册、租约确认与工作区同步时序 _

10.3 心跳时序

_ 图 10-3 心跳刷新可用性，并在拉任务阶段完成任务 ACK _

10.4 派单时序

10.5 回传时序

_ 图 10-4 状态分片、日志分片与终态结果的审计式回传链路 _

10.6 fallback 时序

_ 图 10-5 Windows 主执行机掉线后，控制机切换到 121 mirror runner 的 fallback 链路 _

第 11 章 模块调用关系图

11.1 总体调用结构

_ 图 11-1 Golutra 原版的前端、ui_gateway、message_service、orchestration、terminal_engine、runtime 调用关系图 _

11.2 聊天到终端执行链路

_ 图 11-2 聊天消息从 UI 进入桥接层、编排层并最终落到 PTY runtime 的执行链路 _

第 12 章 124 控制机 API 规范

12.1 推荐接口清单

12.2 API 原则

• 所有请求带 traceId
• 所有写接口幂等
• 所有时间字段统一 UTC ISO8601
• 所有回调支持重试
• 所有终态写入必须审计

第 13 章 Windows 主执行机 SOP

13.1 启动前检查

1. runner 进程未重复启动
2. E:\My Project 存在且可访问
3. codex、claude、gemini、qwen、git 等可调用
4. 临时目录与日志目录可写
5. 系统时间正常

13.2 任务执行流程

拉取任务 -> 判断本机可执行 -> 申请执行锁 -> 切换工作区 -> 检查 git 状态 -> 启动执行器 -> 回传日志与状态 -> 生成 artifact -> 回传终态 -> 释放锁

13.3 停机流程

draining -> 停止接单 -> 等待当前任务完成或迁移 -> 回传最终心跳 -> 安全退出

13.4 本机异常处理

• 工作区不存在：回传 WORKSPACE_NOT_FOUND
• git 脏状态不允许：回传 GIT_DIRTY_BLOCKED
• 执行器缺失：回传 EXECUTOR_MISSING
• 本机即将关机：先进入 draining

第 14 章 Golutra 源码解析摘要

14.1 技术栈总览

仓库是 Vue 3 + TypeScript + Pinia + Vite 前端，叠加 Rust + Tauri 后端宿主的桌面应用，不是单一网页项目，而是“前端壳 + Tauri 网关 + 终端引擎 + 消息存储 + 编排层”的组合体。

14.2 顶层目录职责

14.3 前端主模块

14.4 后端主模块

14.5 关键执行链路

• 邀请成员链路：邀请弹窗 -> 写入 terminalType / terminalCommand -> 保存项目成员 -> 可选自动拉起终端
• 派单链路：聊天输入 -> chatBridge -> ui_gateway -> message_service / orchestration -> terminal_engine -> runtime -> 输出事件回流前端
• 会话链路：terminal_create -> PTY -> poller / snapshot / status -> 事件回流 UI

14.6 对 Naikaku 的启示

Golutra 的协作层和成员语义可以继续沿用；Naikaku 真正需要补的是 runner 注册、任务对象、工作区路由和 fallback 机制，而不是继续魔改首页。

第 15 章 字段字典表

15.1 按模块归类

Runner 模块

Workspace 模块

Task 模块

Result / Log 模块

15.2 按字母序索引

第 16 章 错误码与恢复动作对照表

第 17 章 如何正确输出文档

17.1 输出原则

• 永远保留 Markdown 源文件
• 先生成完整可访问的 HTML，再打印 PDF
• 在 PDF 成功打印前，不删除 HTML、CSS 和其他中间资源
• 图示优先使用稳定的静态文本图或已验证可导出的图形格式
• 文档标题、封面标题、文件名必须保持一致

17.2 正确流程

1. 编写和更新 Markdown 源文件
2. 准备样式文件 CSS
3. 用 Pandoc 生成 HTML
4. 确认 HTML 文件真实存在且可打开
5. 用浏览器 headless 打印成 PDF
6. 人工抽查 PDF 是否正常
7. 仅在确认成功后清理中间文件
8. 最终至少保留 MD + PDF 两份

17.3 禁止事项

• 不允许只留 PDF，不留 Markdown
• 不允许在未验证 PDF 正常前删掉 HTML
• 不允许在图示报错时硬导出成最终版
• 不允许文件名仍沿用旧项目名造成混淆

第 18 章 结论

Naikaku 不是简单换名，而是把 Golutra 的核心技术吸纳进你自己的控制机、多服务器 SSH 协同和本机工作区执行体系后，形成一个更适合你长期演进的开源项目。

后续这本手册必须同时保留：

• Server Operation & Maintenance Manual.md
• Server Operation & Maintenance Manual.pdf

原独立文档《服务器体系教学手册》《多服务器智能体接口与字段速查手册》《多服务器智能体体系技术拆解报告》《多服务器智能体体系逐章批注版》《服务器资产与角色规划总表》现已全部吸收进本手册附录，不再作为并行真源继续维护。

附录 A 名词表

• Naikaku：你基于 Golutra 技术吸纳与扩展形成的开源项目
• Golutra：上游参考技术项目
• runner：常驻执行桥
• primary：主工作区
• mirror：镜像工作区
• shared：公共工作区
• fallback：主路径不可用时自动切换到备用路径
• traceId：贯穿一次任务调用链的追踪 ID
• ACK：执行机确认接单

附录 B 服务器体系教学导读（整合自《服务器体系教学手册》）

注：上面的 Cloudflare 是干什么的.md 仅为被吸收源文件的历史记录；该薄索引页已于 2026-04-19 删除，相关正文现统一保留在本手册第 3 章。

第一章：先建立整体世界观

1. 你现在这套体系到底是什么

你现在不是只有“一台服务器”或者“一个网站”，而是在逐步搭一套完整的运行体系，里面至少包含这几层：

• 你的 Windows 本机：开发、审核、人工接管、本地资源入口；
• 主控制机：负责控制台、调度、统一 API、状态中心；
• 主运行机：负责 worker、长任务、批处理、模型调用执行；
• 弹性算力机：负责按需扩容、临时高负载任务；
• 备用实验机：负责试验、跳板、低优先级备援；
• 外层网络入口：负责域名、流量、安全、访问控制；
• 基础连接能力：SSH、密钥、隧道、systemd、数据库接入。

所以这整套体系，本质上不是“几台机器”，而是：

一套分层的控制、执行、连接、安全、部署系统。

2. 这份手册的学习顺序

这份手册建议按这个顺序看：

1. 先搞懂机器分工；
2. 再搞懂 Cloudflare 和内网反代；
3. 再搞懂 SSH 和密钥信任；
4. 再搞懂 Linux 上的 systemd；
5. 最后回到你的实际机器架构和部署思路。

如果跳着看，也建议至少先看完：

• 第二章：你的机器结构
• 第三章：Cloudflare / 内网反代
• 第四章：SSH / 免密
• 第五章：systemd

第二章：你的服务器和机器是怎么分工的

1. 当前最合理的三层结构

Windows 工作站 NEVERLETMEGO
        |
        v
124.220.233.126（主控制机）
   |            |             |
   v            v             v
121.196.202.114（主运行机） 221.5.60.2:10043（弹性算力机） 111.228.6.224（备用实验机）

这张图非常重要，因为它决定了以后你整理文档、部署服务、分配任务时的思路。

2. 每台机器的角色

Windows 工作站

定位：

• 开发
• 审核
• 手动接管
• 本地文件/浏览器/IDE 入口

特点：

• 人在这里干预；
• 适合做操作台；
• 不适合长期承载核心常驻服务。

主控制机：124.220.233.126

定位：

• 控制台
• 调度入口
• 统一 API
• 状态中心
• 日志汇总
• 审计与面板入口

这台机器更像你的“总控大脑”。

主运行机：121.196.202.114

定位：

• worker
• 长任务
• 队列消费
• 批处理
• 爬虫/抓取
• 模型执行

这台机器更像你的“主执行手臂”。

弹性算力机：221.5.60.2:10043

定位：

• 按需扩容
• 临时重任务
• 高峰期算力补位
• 可开可停的执行位

它适合做临时增援，不适合做唯一控制中心。

备用实验机：111.228.6.224

定位：

• 实验
• 跳板
• 灾备辅助
• 低优先级备援

它更像“实验室和备用点”。

3. 为什么要这样分层

因为如果不分层，你后面会很快进入混乱：

• 控制和执行混在一起；
• 哪台机器是入口说不清；
• 日志、状态、数据库、部署都散掉；
• 故障时不知道该查哪台。

所以你后续的一切文档、部署、自动化，都应遵守一个基本原则：

控制机负责指挥，运行机负责干活，弹性机负责补位，实验机负责试错，本机负责人工接管。

第三章：Cloudflare、内网反代、云服务器到底是什么关系

1. 先纠正常见误解

很多人会把这些词混在一起：

• Cloudflare
• 内网反代
• 云服务器
• 远程控制
• 外网访问

但这几个东西不是一回事。

云服务器是什么

云服务器是真正运行程序的机器。

比如：

• 阿里云 ECS
• 腾讯云 CVM
• 你的控制机 / 运行机 / 弹性算力机

这些才是真正“跑代码、跑服务、跑数据库、跑 worker”的地方。

内网反代是什么

内网反代本质上是：

让外部能够访问你本地内网里的服务，但不直接暴露你的真实内网地址。

最简单理解：

• 你本地电脑上跑着服务；
• 外面本来访问不到；
• 通过隧道 / 反代，你给它接出一个公网入口；
• 外面访问这个入口，实际流量被送回你本地。

Cloudflare 是什么

Cloudflare 不是你的服务器。

它更准确的定位是：

域名与服务器之间的流量中转层、安全层、DNS 管理层、Tunnel 层。

它能做：

• 域名解析；
• 免费 HTTPS；
• 隐藏源站真实 IP；
• 防火墙和访问规则；
• CDN 和流量中转；
• Cloudflare Tunnel。

2. 一句话讲清三者关系

最简单的关系是：

域名 / 外部访问
  -> Cloudflare
      -> Tunnel / 反代入口
          -> 本地电脑或云服务器上的真实服务

也可以换一种更通俗的话：

• 服务器：房子本体；
• Cloudflare：门卫 + 门禁 + 快递转发台；
• 内网反代：从外面通到你家里的隐形通道。

3. 内网反代到底有什么用

内网反代最常见、最真实的用途是：

• 让你在外面访问家里的面板；
• 让云端程序调用你本地服务；
• 给本地 API 提供一个公网入口；
• 不用直接暴露家庭公网 IP；
• 不用路由器手工开一堆端口。

它能做什么

• 让外部访问本地 Atramenti-Console；
• 让云端 AI 调用本地 OpenClaw；
• 做 webhook 回调；
• 做轻量远程控制入口。

它不能做什么

• 不能让已经关机的电脑继续工作；
• 不能替代云服务器；
• 不能代替真正的远程开机。

一句话记忆：

内网反代只是搭桥，不是把机器搬到云上。

4. Cloudflare 能不能控制你的服务器

不能。

Cloudflare 只能控制它那一层的规则，比如：

• 哪些 IP 能访问；
• 哪些地区能访问；
• 某些路径要不要拦；
• 是否启用缓存和 HTTPS；
• Tunnel 是否启用。

它不能：

• 登录你的服务器；
• 修改你服务器文件；
• 修改系统防火墙；
• 控制你电脑；
• 执行你的命令。

一句话：

Cloudflare 管门和流量，不管房子内部。

第四章：SSH、免密、密钥信任到底是怎么回事

1. SSH 是做什么的

SSH 就是远程登录和远程执行命令的基础通道。

你平时说“连服务器”，本质上通常就是：

• 用 SSH 登录到 Linux 服务器；
• 远程执行命令；
• 看日志；
• 部署代码；
• 改配置；
• 复制文件。

2. SSH 为什么总让人觉得绕

因为大家经常把这几个概念混起来：

• SSH 本身的连接；
• SSH 密钥；
• 免密登录；
• authorized_keys；
• 双向信任；
• 隧道和 SSH 服务本身。

要学明白 SSH，最重要的是抓住一句话：

SSH 网络连接可以双向通信，但免密信任是严格单向的。

3. 什么叫单向信任

假设有两台机器：A 和 B。

A 免密登录 B

本质操作是：

• 把 A 的公钥，写入 B 的 authorized_keys

这意味着：

• B 信任 A；
• A 可以免密登录 B；
• 但不代表 B 自动也能登录 A。

如果 B 也想免密登录 A

还必须反过来再做一遍：

• 把 B 的公钥，写入 A 的 authorized_keys

所以：

双向免密 = 两次独立配置，不存在一次配置自动双向互通。

4. 最通俗的比喻

• 公钥 = 门禁卡
• authorized_keys = 门禁白名单

如果你把 A 的门禁卡登记在 B 的白名单里，表示：

• A 能进 B
• 不表示 B 也能进 A

如果你要 B 也能进 A，A 也得登记 B 的门禁卡。

5. Windows 这边记录过的授权信息

当时已经记录过一条要写入 Windows authorized_keys 的公钥：

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILKMAnYszLx27pSOhju9jg0FhPW4lFn3mClOEAu2ApSz ubuntu@VM-0-12-ubuntu

目标路径：

• C:\Users\ASUS-KL\.ssh\authorized_keys

如果目录不存在，可先建立：

New-Item -ItemType Directory -Path "$env:USERPROFILE\.ssh" -Force
New-Item -ItemType File -Path "$env:USERPROFILE\.ssh\authorized_keys" -Force

6. SSH 服务和 SSH 隧道不是一回事

这个点特别容易混。

SSH 服务

指的是：

• sshd
• 服务器上真正提供 SSH 登录能力的系统服务

SSH 隧道 / 穿透工具

指的是：

• frp
• ngrok
• cloudflared
• 反向隧道命令

这些是额外用来“打洞”或“做通道”的工具。

所以：

• sshd 自启，不代表隧道自动自启；
• 隧道要不要自启，需要单独配置。

第五章：systemd 是什么，为什么它这么重要

1. systemd 的定位

在 Linux 里，systemd 可以简单理解成：

系统服务管理器 + 开机自启管理器 + 进程守护器。

它相当于 Windows 这几样东西的组合：

• 服务管理器；
• 计划任务；
• 进程保活工具。

2. 对你有什么现实意义

在你的服务器体系里，systemd 非常适合托管这些东西：

• 控制台服务；
• API 服务；
• worker；
• 调度器；
• Tunnel 进程；
• 常驻脚本。

它能帮你做：

• 开机自启；
• 崩溃自动拉起；
• 统一启停；
• 查看状态；
• 跟系统日志打通。

3. 最常用的 systemctl 命令

systemctl start <service>
systemctl stop <service>
systemctl restart <service>
systemctl status <service>
systemctl enable <service>
systemctl disable <service>

4. sshd 开机后要不要手动再启动

通常不需要。

只要 sshd 已配置为开机自启，服务器启动后它就会自动运行。

常用检查：

systemctl is-enabled sshd

常用设置：

sudo systemctl start sshd
sudo systemctl enable sshd

如果你只是改了配置文件，比如 sshd_config，那才需要额外 restart 一次服务使配置生效。

5. systemd 和 supervisor 怎么选

统一口径建议是：

• Windows：计划任务 + supervisor 更常见；
• Linux：优先 systemd 原生托管；
• 除非有明确理由，否则 Linux 端不必再额外叠一层 supervisor。

一句话：

Windows 常靠计划任务 + supervisor，Linux 通常直接靠 systemd。

第六章：把前面的概念落回你的实际机器

1. 当前机器总表

主控制机：124.220.233.126

已知信息：

• 主机名：VM-0-12-ubuntu
• 内网 IP：10.0.0.12
• 系统：Ubuntu 24.04.4 LTS
• CPU：4 核
• 内存：约 3.6 GiB
• 远端目录：/srv/atramenti-console
• 服务：atramenti-console.service
• 外网入口：https://console.tengokukk.com/（直连探测入口仍可用：http://124.220.233.126:5101）

角色：

• 控制台
• 统一 API
• 调度器
• 状态中心
• 审计入口

主运行机：121.196.202.114

已知信息：

• 云归属高概率为阿里云 ECS；
• 在 known_hosts 里有历史连接痕迹；
• 当前 SSH 超时；
• 系统、用户、目录、服务仍待补齐。

角色：

• worker
• 长任务
• 批处理
• 队列消费
• 模型执行

弹性算力机：221.5.60.2:10043

已知信息：

• 实例标识：wummlp
• GPU：Virtual 高性能推理卡 - 24GB
• CPU：18 核
• 内存：32 GB
• 用户目录：/root/workspace
• 应用目录：/root/workspace/ai-office
• 已知服务：office-web、ai-office-worker

角色：

• 按需算力
• 高峰补位
• 临时重任务

备用实验机：111.228.6.224

已知信息：

• SSH 别名：jd-lavm-beijing / jd-lavm-yp7m9xmd5l
• 系统：Ubuntu 24.04.2 LTS
• CPU：2 核
• 内存：约 1.9 GiB
• 角色偏实验、跳板、备援

2. 推荐职责分工

推荐以后统一按这个思路写文档和部署：

• 124.220.233.126：总控大脑
• 121.196.202.114：主执行手臂
• 221.5.60.2:10043：按需增援部队
• 111.228.6.224：实验室和备用点
• Windows：人工驾驶舱

3. 推荐调用链

Windows 工作站
  -> 124.220.233.126（控制机）
      -> 121.196.202.114（主运行机）
      -> 221.5.60.2:10043（弹性算力机）
      -> 111.228.6.224（备用实验机）

原则：

• 外部统一入口尽量收敛到控制机；
• 状态真源尽量收敛到控制机；
• 重执行尽量放运行机；
• 峰值任务尽量放弹性机；
• 试验任务放备用机；
• 本机只做人类操作入口和资源源头。

第七章：数据库和数据底座也属于服务器体系

这部分不能因为它“不是硬件”就忽略。

1. 当前记录过的 MySQL 接入信息

在当前资料里，已经确认过：

• E:\My Project\Atramenti-Console\codex\mcps\database-api 复用了共享配置；
• 配置来源包括：
  • E:\My Project\Atramenti-Console\codex\mcps\core\config.ts:199
  • E:\My Project\Atramenti-Console\codex\mcps\core\database\manager.ts:29
  • E:\My Project\Atramenti-Console\codex\mcps\database-api\README.md:33

默认连接信息曾记录为：

• host: 124.220.245.121
• port: 22295
• user: openclaw
• database: cloudbase-4glvyyq9f61b19cd

2. 为什么这也要写进服务器体系

因为在真实运维里，服务器体系不只是：

• IP
• CPU
• 内存
• 磁盘

还包括：

• 数据库入口
• 配置来源
• 默认连接目标
• 服务依赖
• 权限和建库计划

如果这些不记进体系文档，后面交接和排查会断线。

第八章：以后整理这类文档时应该怎么做

1. 核心原则

以后整理这种“服务器体系”文档，目标不是把材料删薄，而是把材料分层。

也就是说：

• 要有正式版；
• 要有原始记录；
• 要有概念讲解；
• 要有待核实信息；
• 要有下一步动作；
• 要能作为教学材料继续往下扩展。

2. 哪些内容不能因为看起来重复就删掉

不能随手删的包括：

• 历史版本的机器信息；
• 待确认项；
• 不同时间点的判断差异；
• SSH、隧道、systemd、服务、日志、数据库这些基础设施信息；
• 原始探测过程；
• 得出结论的依据。

3. 推荐的文档结构

后续继续扩展时，建议采用：

• 教学主文档：讲概念和结构；
• 资产总表：讲当前统一口径；
• 原始记录归档：留现场痕迹；
• 数据库接入文档：讲数据层；
• 部署规范文档：讲怎么部署；
• 节点调度文档：讲怎么互相调用。

第九章：一句话总复盘

如果用最短的话总结你现在这套东西：

• 你的本机是人工驾驶舱；
• 控制机是总控大脑；
• 运行机是主执行手臂；
• 弹性机是按需增援部队；
• 备用机是实验室；
• Cloudflare 是门卫和流量入口；
• 内网反代是把本地服务接到外面的桥；
• SSH 是远程连接通道；
• 密钥信任是单向白名单；
• systemd 是 Linux 的服务管家；
• 数据库接入也是服务器体系的一部分。

如果以后你继续扩这份手册，最值得补的下一章通常是：

1. 部署链路教学
2. 节点调度与回传协议
3. 控制机 / 运行机标准目录规范
4. Cloudflare Tunnel 实战部署
5. SSH 双向免密实战
6. systemd 服务模板大全

附录 C 接口与字段速查（整合自《多服务器智能体接口与字段速查手册》）

一、速查总览

1.1 核心对象

1.2 接口索引

1.3 工作区策略索引

二、状态与时序速查

2.1 任务状态机

_ 速查图 1：任务对象状态机 _

2.2 注册时序

_ 速查图 2：Runner 注册与工作区同步时序 _

2.3 心跳 / 派单 / ACK 时序

_ 速查图 3：心跳刷新、拉任务与 ACK 连续链路 _

2.4 状态 / 日志 / finalize 回传时序

_ 速查图 4：状态、日志、终态结果回传链路 _

2.5 fallback 时序

_ 速查图 5：主执行机掉线后的 fallback 迁移链路 _

三、API Reference

3.1 全局原则

• 所有请求必须带 traceId
• 所有写接口按幂等设计
• 所有时间字段统一 UTC ISO8601
• 所有终态写入必须审计
• 所有需要重试的接口必须可安全重复提交

3.2 POST /api/runners/register

作用

注册 runner 身份、能力与初始工作区视图，并建立租约。

建议请求核心字段

建议响应关注点

• accepted
• leaseSec
• nextHeartbeatAfterSec
• 若失败，返回原因与重试建议

3.3 POST /api/runners/heartbeat

作用

刷新 runner 在线状态、系统负载、任务占用和工作区健康视图。

建议请求核心字段

3.4 POST /api/runners/workspaces/sync

作用

对工作区注册信息做补充或刷新，控制机据此维护调度可见性。

关注点

• workspaceId 稳定
• path 为真实绝对路径
• kind 为 primary / mirror / shared
• healthy / writable 作为调度约束

3.5 GET /api/tasks/pull

作用

给 runner 拉取当前可执行任务列表。

关注点

• 控制机应考虑 runner 能力、工作区、锁状态和策略
• 返回可为 0 个任务，不等同于错误
• 建议返回任务时附带必要的执行约束，避免 runner 二次猜测

3.6 POST /api/tasks/ack

作用

runner 对拉到的任务进行正式确认，锁定任务归属。

关键字段

3.7 POST /api/tasks/status

作用

回传任务状态转移，例如 queued -> running、running -> fallback_pending 等。

建议字段

• taskId
• traceId
• runnerId
• status
• reason
• emittedAt

3.8 POST /api/tasks/logs

作用

以分片方式追加过程日志。

关键规则

• sequence 单调递增
• 按 taskId + sequence 去重
• 大日志必须拆分
• stream 支持 stdout / stderr / system

3.9 POST /api/tasks/finalize

作用

提交最终状态、摘要、产物和统计信息。

关键字段

3.10 POST /api/tasks/cancel

作用

由控制面主动要求停止任务。实现时要区分：

• 取消请求已发出
• 任务是否已响应取消
• 是否需要清理锁与终态审计

3.11 查询接口

GET /api/tasks/{taskId}

适合用来查看：

• 当前状态
• 所属 runner / workspace
• 过程日志摘要
• 最终结果
• fallback 历史

GET /api/runners/{runnerId}

适合用来查看：

• 在线状态
• 当前负载
• 当前任务列表
• 工作区视图与健康状态

四、JSON 样例速查

4.1 Runner 注册请求

{
  "traceId": "trace_register_win_main_001",
  "runnerId": "win-main-001",
  "runnerName": "Windows Main Runner",
  "machineRole": "primary-executor",
  "host": "NEVERLETMEGO",
  "os": "windows-11-23h2",
  "version": "0.1.0",
  "capabilities": ["codex", "claude", "gemini", "shell"],
  "maxConcurrentTasks": 2,
  "workspaces": [
    {
      "workspaceId": "ws-my-project-primary",
      "name": "My Project",
      "path": "E:\\My Project",
      "kind": "primary",
      "priority": 100,
      "writable": true,
      "healthy": true
    }
  ]
}

4.2 心跳请求

{
  "traceId": "trace_heartbeat_win_main_001_100015",
  "runnerId": "win-main-001",
  "sentAt": "2026-04-17T10:00:15Z",
  "status": "online",
  "activeTaskCount": 1,
  "queueDepth": 0,
  "currentTaskIds": ["task_20260417_001"],
  "workspaceHealth": [
    {
      "workspaceId": "ws-my-project-primary",
      "healthy": true,
      "writable": true,
      "freeDiskGb": 128.4,
      "gitAccessible": true
    }
  ],
  "systemLoad": {
    "cpuPercent": 22,
    "memoryPercent": 61,
    "diskPercent": 48
  }
}

4.3 拉任务响应

{
  "traceId": "trace_pull_win_main_001_100020",
  "tasks": [
    {
      "taskId": "task_20260417_001",
      "traceId": "trace_task_20260417_001",
      "projectId": "proj_naikaku_cloud",
      "workspacePolicy": "prefer_local",
      "preferredWorkspaceId": "ws-my-project-primary",
      "preferredRunnerId": "win-main-001",
      "title": "修复 runner 心跳重连问题",
      "instruction": "定位 runner 在网络抖动后无法恢复心跳的原因，修复并补充重试退避。",
      "roleHint": "codex-engineer",
      "executorHint": "codex",
      "priority": "high",
      "timeoutSec": 1800,
      "fallbackAllowed": true,
      "repoRef": "Atramenti box",
      "targetPath": "golutra"
    }
  ]
}

4.4 ACK 请求

{
  "traceId": "trace_ack_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "workspaceId": "ws-my-project-primary",
  "acceptedAt": "2026-04-17T10:00:21Z",
  "leaseSec": 1800,
  "executor": "codex"
}

4.5 日志分片请求

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "sequence": 17,
  "stream": "stdout",
  "content": "[step] retry policy patched, running local verification...",
  "emittedAt": "2026-04-17T10:03:18Z"
}

4.6 最终结果请求

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "finalStatus": "succeeded",
  "summary": "已修复心跳重连逻辑，加入指数退避和状态恢复保护。",
  "startedAt": "2026-04-17T10:01:00Z",
  "finishedAt": "2026-04-17T10:12:00Z",
  "artifacts": [
    {
      "type": "patch",
      "name": "runner-heartbeat.patch",
      "path": "artifacts/task_20260417_001/runner-heartbeat.patch",
      "size": 18244,
      "checksum": "sha256:abc123"
    },
    {
      "type": "test-report",
      "name": "runner-heartbeat-test.txt",
      "path": "artifacts/task_20260417_001/runner-heartbeat-test.txt",
      "size": 4210,
      "checksum": "sha256:def456"
    }
  ],
  "stats": {
    "logLines": 320,
    "filesChanged": 3,
    "durationSec": 660
  }
}

4.7 fallback 重分配请求

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "fromRunnerId": "win-main-001",
  "toRunnerId": "aliyun-backup-001",
  "fromWorkspaceId": "ws-my-project-primary",
  "toWorkspaceId": "ws-my-project-mirror-121",
  "reason": "RUNNER_OFFLINE",
  "fallbackAt": "2026-04-17T10:06:30Z",
  "attempt": 1
}

五、字段 Reference

5.1 Runner 字段

5.2 Workspace 字段

5.3 Task 字段

5.4 Log / Result 字段

5.5 按问题反查字段

六、错误码 Reference

6.1 错误码总表

6.2 按恢复策略归类

常见可 fallback

• WORKSPACE_UNHEALTHY
• EXECUTOR_MISSING
• RUNNER_DRAINING
• RUNNER_OFFLINE

常见不可 fallback

• LOCK_CONFLICT
• LOCAL_ONLY_OFFLINE
• AUTH_INVALID

取决于策略

• WORKSPACE_NOT_FOUND
• TASK_TIMEOUT

七、实现检查清单

7.1 控制机实现检查

• 是否有 runner 注册租约
• 是否按工作区健康与策略做调度
• 是否区分 pull 和 ack
• 是否对 status/logs/finalize 做幂等处理
• 是否记录 fallback 迁移链
• 是否能审计终态与 artifacts

7.2 Runner 实现检查

• 是否启动前校验执行器可用性
• 是否按固定频率 heartbeat
• 是否 pull 后先 ack 再执行
• 是否日志分片带 sequence
• 是否 finalize 带摘要、产物和统计
• 是否在 fallback 前释放旧锁

7.3 文档与联调检查

• 是否保留 JSON 示例的真实版本
• 是否保留字段字典与错误码表
• 是否对关键时序图持续更新
• 是否保留 Markdown 源和 PDF 成品

八、一页式总结

8.1 如果你只记 10 件事

1. traceId 是全链路锚点
2. ack 才是正式接单
3. workspacePolicy 决定任务去哪执行
4. primary / mirror / shared 是不同语义，不只是不同目录
5. sequence 决定日志补传与去重能力
6. finalize 不只是结束，还要带摘要、产物、统计
7. fallback 要保留原 trace，不要生成平行幽灵任务
8. RUNNER_OFFLINE 与 RUNNER_DRAINING 是调度事件，不只是机器状态
9. GIT_DIRTY_BLOCKED 体现真实工作区保护
10. 文档维护必须保留 MD + PDF

8.2 一句话定位

这份速查手册的作用，是把《Server Operation & Maintenance Manual》中最容易在实现、联调、排障时反复翻找的 API、字段、样例 JSON、状态图和错误码集中压缩成一份 reference 文档。

附录 D 技术拆解与研判（整合自《多服务器智能体体系技术拆解报告》）

一、先给结论

1.1 这份手册描述的到底是什么系统

这不是一个“单纯网页 + 聊天框”的项目说明，而是一套明显的 多服务器控制面 + Runner 执行面 + 本机工作区优先 + fallback 回退 的智能体协同体系。它继承了 Golutra 的成员协作、终端编排与工作区语义，又把这些能力重新组织成 Naikaku 的多机执行架构。

1.2 这份手册里最关键的技术结论

• 前端技术栈明确写出：Vue 3、TypeScript、Pinia、Vite
• 桌面宿主与后端明确写出：Rust、Tauri
• 执行层明确出现：PTY、进程 runtime、终端会话、快照、状态事件
• 协同层明确出现：控制机、Runner 注册、心跳、拉任务、ACK、日志回传、最终结果回传、fallback
• 文档工具链明确出现：Markdown 源文件、CSS、Pandoc、浏览器 headless 打印 PDF
• 图示资产经文件头可确认：示例图是 PlantUML 导出的 SVG

1.3 关于 MCP / Skill 的一句话判断

这份手册的运行时架构本身不是 MCP 原生架构，它描述的是 CLI / Runner / 控制面 体系；但它的文档生产链路与当前环境中的 plantuml-diagrams、md-to-office、markdown-to-pdf 非常匹配。

二、证据矩阵：哪些是手册明写的，哪些是可推断的

三、这份手册里明确使用了什么技术

3.1 产品架构层技术

手册中反复出现的系统级技术思想包括：

• 控制机中心化：把 124 作为统一 control plane
• SSH 多服务器协同：执行机不止一台，而是主执行机、备用机、补位机协同
• 本机工作区优先：真实代码目录优先于云端镜像目录
• 任务对象化：不只靠聊天消息，而是显式 task object 驱动执行
• Runner 协议化：执行节点被抽象为 runner，并有独立协议
• 可审计闭环：不仅有结果，还有状态、日志、错误码、artifact 与 fallback 轨迹

3.2 前端技术栈

第 14.1 节把前端技术栈写得很清楚：

• Vue 3
• TypeScript
• Pinia
• Vite

这说明前端不是传统服务端模板页，而是一个带状态管理和构建工具链的现代前端壳层。

3.3 桌面宿主与后端技术

手册明确指出它不是单一网页项目，而是：

• Rust
• Tauri

也就是说，这个系统更接近 桌面应用外壳 + 本地/宿主端运行能力，而不是仅靠浏览器页面跑逻辑。

3.4 终端与执行运行时技术

运行时层出现的核心技术要素包括：

• PTY
• process runtime
• terminal session
• snapshot
• status event
• log stream

这类关键词说明它不是单纯调用 HTTP API 的 agent，而是把真实终端会话作为执行载体。

3.5 协议与工程治理技术

手册还明确用了这些工程协议与治理要素：

• traceId 贯穿调用链
• UTC ISO8601 时间格式
• 写接口幂等
• 审计式终态写入
• 错误码体系
• artifact 元数据
• fallback 重新分配链路

这些内容已经非常像一套完整的控制平面协议，而不是口头规则。

四、部署结构与多服务器协同模型

4.1 部署示例图

_ 示例图 A：源手册中的多服务器控制 / 执行 / fallback 部署结构图 _

4.2 这张图说明了什么

从这张图里可以直接读出：

• 有一个明确的 124 控制机 负责控制面
• 有一个 Windows 主执行机 负责真实工作区代码修改
• 有一个 121 mirror runner 负责备用镜像工作区执行
• 还有 111 shared runner 作为补位执行位
• 所有任务、日志、结果、产物都会回流控制面做统一审计

4.3 这里体现的核心技术点

• control plane / data plane 分离
• 执行位分层：primary / mirror / shared
• 本机代码优先
• 掉线后的 fallback 派发
• 任务产物闭环

五、模块结构：这套系统有哪些核心模块

5.1 Golutra 原版总模块关系图

_ 示例图 B：Golutra 原版模块调用关系图 _

5.2 从图中可见的核心模块

图中直接出现的模块有：

• Frontend
• Bridge / Store
• ui_gateway
• message_service
• orchestration
• terminal_engine
• runtime
• project storage

这说明它不是单体模块，而是一条非常清晰的“UI -> 网关 -> 消息/编排 -> 终端引擎 -> 运行时”的链路。

5.3 前端主模块

5.4 后端主模块

5.5 聊天到终端执行链路图

_ 示例图 C：聊天消息到终端执行的链路图 _

5.6 这条链路的意义

这张图解释了为什么手册里的系统不是“聊天 UI”这么简单：

1. ChatInput 只是入口
2. chatBridge 负责桥接
3. ui_gateway 把调用送到宿主层
4. message_service 负责消息与会话数据
5. orchestration 负责决定派给谁
6. terminal_engine 负责确保终端会话与状态采集
7. runtime 才是真正的 PTY / 进程执行层

六、协议层：Runner、Task、Workspace、Result/Log

6.1 任务状态机图

_ 示例图 D：任务对象状态机图 _

6.2 注册与工作区同步时序

_ 示例图 E：Runner 注册、租约确认与工作区同步时序 _

6.3 心跳、拉任务、ACK 连续链路

_ 示例图 F：心跳刷新可用性，并在拉任务阶段完成任务 ACK _

6.4 状态 / 日志 / 终态回传链路

_ 示例图 G：状态分片、日志分片与终态结果的审计式回传链路 _

6.5 fallback 回退时序

_ 示例图 H：Windows 主执行机掉线后切换到 mirror runner 的 fallback 链路 _

6.6 这套协议层到底定义了什么

手册实际上定义了四类核心对象：

Runner 模块

• 执行机身份：runnerId、runnerName、machineRole
• 机器状态：status、queueDepth、activeTaskCount
• 执行能力：capabilities、maxConcurrentTasks

Workspace 模块

• 工作区身份：workspaceId、name
• 工作区定位：path、kind
• 路由信息：hostRunnerId、priority
• 可执行性：writable、healthy

Task 模块

• 唯一性与追踪：taskId、traceId
• 派发目标：preferredWorkspaceId、preferredRunnerId
• 执行意图：title、instruction、roleHint、executorHint
• 约束与策略：priority、timeoutSec、fallbackAllowed

Result / Log 模块

• 日志序列：sequence、stream、content
• 结果闭环：finalStatus、summary
• 产物与统计：artifacts、stats

七、API：控制面真正暴露了什么接口

7.1 接口清单

7.2 API 原则

手册对接口风格也定了明确规则：

• 所有请求带 traceId
• 所有写接口幂等
• 所有时间字段统一 UTC ISO8601
• 所有回调支持重试
• 所有终态写入必须审计

这说明它不是“能跑就行”的内部接口，而是按可重试、可审计、可追踪来设计的。

八、AI 岗位、执行器与工具入口

8.1 岗位与执行器映射

8.2 这说明它更像什么系统

这说明该体系本质上是：

• 一个有 岗位语义 的智能体平台
• 一个能把不同 CLI / 模型能力接到统一任务协议上的系统
• 一个把 模型能力 和 执行器能力 分开的架构

8.3 手册里直接出现的可调用工具线索

Windows 主执行机 SOP 里还明确提到启动前检查需要：

• codex
• claude
• gemini
• qwen
• git

也就是说，这套体系默认就把多个 CLI 工具视作运行时依赖，而不只是单模型单入口。

九、JSON 示例：手册本身给了哪些可落地样例

9.1 Runner 注册请求示例

{
  "traceId": "trace_register_win_main_001",
  "runnerId": "win-main-001",
  "runnerName": "Windows Main Runner",
  "machineRole": "primary-executor",
  "host": "NEVERLETMEGO",
  "os": "windows-11-23h2",
  "version": "0.1.0",
  "capabilities": ["codex", "claude", "gemini", "shell"],
  "maxConcurrentTasks": 2
}

这个示例说明：Runner 不是匿名 worker，而是有版本、主机、角色、能力集合的正式注册对象。

9.2 心跳请求示例

{
  "traceId": "trace_heartbeat_win_main_001_100015",
  "runnerId": "win-main-001",
  "sentAt": "2026-04-17T10:00:15Z",
  "status": "online",
  "activeTaskCount": 1,
  "queueDepth": 0,
  "currentTaskIds": ["task_20260417_001"],
  "systemLoad": {
    "cpuPercent": 22,
    "memoryPercent": 61,
    "diskPercent": 48
  }
}

这个示例说明：心跳不是只报“我还活着”，而是附带负载、任务占用和工作区健康信息。

9.3 拉任务响应示例

{
  "traceId": "trace_pull_win_main_001_100020",
  "tasks": [
    {
      "taskId": "task_20260417_001",
      "workspacePolicy": "prefer_local",
      "preferredWorkspaceId": "ws-my-project-primary",
      "preferredRunnerId": "win-main-001",
      "roleHint": "codex-engineer",
      "executorHint": "codex",
      "priority": "high",
      "fallbackAllowed": true,
      "repoRef": "Atramenti box"
    }
  ]
}

这个示例说明：任务里已经把“岗位”、“执行器”、“工作区策略”、“回退权限”编码进协议了。

9.4 ACK 与最终结果示例

{
  "traceId": "trace_ack_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "workspaceId": "ws-my-project-primary",
  "acceptedAt": "2026-04-17T10:00:21Z",
  "leaseSec": 1800,
  "executor": "codex"
}

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "runnerId": "win-main-001",
  "finalStatus": "succeeded",
  "summary": "已修复心跳重连逻辑，加入指数退避和状态恢复保护。",
  "artifacts": [
    { "type": "patch", "name": "runner-heartbeat.patch" },
    { "type": "test-report", "name": "runner-heartbeat-test.txt" }
  ]
}

这说明系统把结果输出拆成了“接单确认、过程日志、终态摘要、产物列表”几个层次。

9.5 fallback 重分配示例

{
  "traceId": "trace_task_20260417_001",
  "taskId": "task_20260417_001",
  "fromRunnerId": "win-main-001",
  "toRunnerId": "aliyun-backup-001",
  "fromWorkspaceId": "ws-my-project-primary",
  "toWorkspaceId": "ws-my-project-mirror-121",
  "reason": "RUNNER_OFFLINE",
  "fallbackAt": "2026-04-17T10:06:30Z",
  "attempt": 1
}

这说明 fallback 并不是口头补救，而是协议内一等公民。

十、错误码体系：它已经具备工程运行手册的味道

10.1 典型错误码示例

10.2 这说明了什么

一份架构手册能把错误码、控制机动作、Runner 动作、fallback 许可写到这种粒度，说明这已经不是概念 PPT，而是接近可执行的系统手册。

十一、这份文档本身用了什么“文档技术”

11.1 源文件结构证据

分析对象同目录下同时存在：

• Server Operation & Maintenance Manual.md
• Server Operation & Maintenance Manual.pdf
• Server Operation & Maintenance Manual.images/*.svg

这说明它本身就是按“Markdown 源 + 图集 + PDF 成品”的方式维护的。

11.2 图示技术证据

图集中的 SVG 文件头带有：

<?plantuml 1.2026.1?>

这可以高置信证明：

• 图示不是截图拼贴
• 图示是文本可维护的 SVG
• 图示工具链是 PlantUML 方向

11.3 导出技术证据

第 17.2 节明确给了导出流程：

1. 编写和更新 Markdown 源文件
2. 准备样式文件 CSS
3. 用 Pandoc 生成 HTML
4. 确认 HTML 文件真实存在且可打开
5. 用浏览器 headless 打印成 PDF
6. 人工抽查 PDF 是否正常

这说明该手册的文档生产不是“一键黑盒导出”，而是 Markdown -> HTML -> 浏览器打印 PDF 的受控链路。

十二、MCP / Skill 研判：哪些是能确认的，哪些只是适配建议

12.1 可以确认的结论

可以确认 1：图示工具链与 plantuml-diagrams 高度匹配

因为图资产就是 PlantUML SVG，所以在当前环境里，最匹配的能力是：

• plantuml-diagrams

它适合继续维护：

• 模块调用关系图
• 时序图
• 状态机图
• 协议链路图

可以确认 2：导出工具链与 md-to-office / markdown-to-pdf 高度匹配

手册要求：

• 保留 Markdown
• 用 Pandoc 生成 HTML
• 再 headless 打印 PDF

所以在当前环境里，对应最匹配的 Skill 是：

• md-to-office
• markdown-to-pdf

其中：

• md-to-office 更偏 Pandoc 通用导出
• markdown-to-pdf 更偏 Markdown 到 PDF 的稳定打印链路

12.2 不能直接下结论的部分

不能确认 1：运行时用了 MCP 作为主架构

手册的运行时关键词是：

• runner
• CLI
• Shell
• Codex
• Claude
• Gemini
• qwen
• PTY
• Tauri

而不是：

• MCP server mesh
• tool registry
• MCP transport orchestration

所以更准确的说法是：

这套系统是 多执行器 / 多 CLI / Runner 控制面 架构，不是“以 MCP 为第一公民”的运行时架构。

不能确认 2：drawio-diagrams 被用来生成这些图

因为现有图资产明显是 PlantUML SVG，不是 draw.io 导出风格，所以不能把 drawio-diagrams 算作这份手册的已确认工具。

不能确认 3：fetch-mcp / markitdown-mcp 被源手册直接使用

这两类 MCP 更适合：

• 网页资料抓取
• PDF / Word / PPT 转 Markdown

而当前这份手册本身更像从架构设计和代码理解直接写出来的手册，不像“外部文档汇编稿”。

12.3 如果要继续维护这类手册，推荐的 MCP / Skill 组合

十三、这份手册体现出的“系统本质”

综合全文，这份手册描述的是一套：

• 以 工作区 为中心组织执行上下文
• 以 任务对象 为中心组织执行生命周期
• 以 Runner 协议 为中心组织多机协同
• 以 CLI 执行器 为中心组织模型与工具能力
• 以 审计闭环 为中心组织结果、日志、产物与错误恢复

因此，如果只把它理解成“一个聊天壳”或者“一个简单 AI 面板”，会严重低估它。

十四、最终判断

14.1 技术层面

这份手册明确覆盖了：

• Vue 3 + TypeScript + Pinia + Vite
• Rust + Tauri
• PTY / process runtime
• 控制机 API
• 多服务器 SSH 协同
• Runner 协议
• fallback 与错误恢复
• 审计式结果回传

14.2 模块层面

这份手册明确覆盖了：

• 前端模块：src/app、workspace、chat、terminal、shared、stores
• 后端模块：ui_gateway、message_service、orchestration、terminal_engine、runtime、platform、contracts/ports
• 数据模块：Runner、Workspace、Task、Result / Log
• 岗位模块：dispatcher、reviewer、deployer、codex-engineer、claude-researcher、gemini-tooling、shell-worker

14.3 MCP / Skill 层面

最准确的结论是：

• 运行时架构：不是 MCP-first，而是 Runner + CLI-first
• 图示维护：高度匹配 plantuml-diagrams
• 文档导出：高度匹配 md-to-office / markdown-to-pdf
• 资料扩展：后续可再叠加 fetch-mcp / markitdown-mcp

14.4 一句话总结

这份《Server Operation & Maintenance Manual》本质上是在描述一套“桌面壳 + Tauri 网关 + PTY 终端运行时 + 多 Runner 控制面 + 工作区优先策略 + fallback 协议 + 审计闭环”的多服务器智能体系统；其文档生产方式则是“Markdown + PlantUML SVG + Pandoc + headless PDF 打印”的工程化文档链路。

附录 E 逐章批注与实施说明（整合自《多服务器智能体体系逐章批注版》）

一、怎么使用这份批注版

1.1 阅读建议

• 如果你第一次接触这个体系，先看第 0~4 章，理解系统目标、角色和部署结构
• 如果你要开始实现 Runner 或控制机，重点看第 5~12 章
• 如果你要对接 CLI 执行器或本机工作区，重点看第 6、8、13、16 章
• 如果你要做二次开发或继承 Golutra，重点看第 11、14 章
• 如果你要继续维护文档本身，重点看第 17 章

1.2 本版的批注结构

每章默认包含四类说明：

• 原章作用：原章在整本手册中的任务
• 逐条解释：按原章节逐项解释它在说什么
• 实施提示：如果你真要做实现，应优先抓什么
• 边界提醒：哪些地方不能过度解读

二、第 0 章 使用索引与阅读导航：批注

2.1 原章作用

第 0 章不是“可有可无的目录页”，而是告诉你：这本手册是按 概念 -> 结构 -> 协议 -> 示例 -> 图示 -> API -> SOP -> 源码解析 -> 索引 组织的。它决定了整本手册的阅读路径。

2.2 0.1 阅读方式：批注

• 原文强调顺序阅读，说明这本手册不是松散条目，而是带推导关系的
• 先讲“定义”，再讲“角色、协议、JSON、时序”，说明作者希望先统一词汇，再谈实现
• 对实施人员来说，这一章相当于“路线图”；对排障人员来说，它相当于“定位入口”

2.3 0.2 检索索引页：批注

• 这一节把问题分成“部署与角色”“Runner 协议”“Golutra 解析”“实施与排障”四类
• 这说明作者已经把读者分成不同任务角色：架构理解者、协议实现者、源码阅读者、运维排障者
• 也说明这本手册设计时考虑了“查阅型使用场景”，不是纯展示型文档

2.4 0.3 图表索引 / 0.4 接口索引 / 0.5 术语索引：批注

• 图表索引意味着图不是装饰，而是核心信息载体
• 接口索引意味着 API 是控制面契约，不是后补内容
• 术语索引意味着 runner、fallback、traceId、orchestration 这些词必须统一语义

实施提示：如果你后续继续扩写该体系，优先维护索引页，因为索引页是把手册从“文章”提升为“参考系统”的关键步骤。

三、第 1 章 项目定义：批注

3.1 原章作用

这一章负责定边界：Naikaku 到底是什么，不是什么，和 Golutra 的关系又是什么。没有这一章，后面所有技术细节都会失焦。

3.2 1.1 Naikaku 是什么：批注

• 这里把 Naikaku 定义成 多服务器协同、云端控制、本机优先执行 的 AI 员工平台
• 关键词不是“聊天”，而是“协同、控制、本机优先、自动回退”
• 也就是说，它的目标是 执行系统，不是单纯会话系统

3.3 1.2 一句话目标：批注

这句“一句话目标”实际上把系统核心策略讲完了：

1. 云端控制机常驻
2. 优先修改 E:\My Project 的真实代码
3. 本机不在线时切换到备用工作区
4. 所有状态、日志、结果统一回传到面板

这 4 点可以视作整个 Naikaku 的产品铁律。

3.4 1.3 与 Golutra 的关系：批注

• 原手册没有把 Naikaku 说成“完全原创”，而是明确说是 技术吸纳与扩展
• 这是一个很重要的项目定位：继承思想，但不局限于原实现
• 文档上这么写，既减少历史割裂，也避免对外叙述失真

3.5 1.4 非目标：批注

“非目标”比“目标”更能防止系统漂移。这一节其实是在防三种误读：

• 把它误会成单页面聊天工具
• 把它误会成完全 provider-native 的托管模型平台
• 把它误会成只要 UI 改漂亮就行的壳层项目

四、第 2 章 来源、作者与项目说明：批注

4.1 原章作用

这一章解决的是合法性、来源说明和对外叙述问题。对于一个从上游技术吸纳演化出来的项目，这是必须有的。

4.2 2.1 上游项目来源：批注

• 写明 golutra 仓库和官网，意味着技术血缘被显式保留
• 这对内部维护也有好处：以后可以回溯概念出处和模块原型

4.3 2.2 上游作者信息：批注

• 作者信息不是八卦信息，而是知识来源锚点
• 后续如果要继续比对设计语义，可以直接回到原作者公开材料

4.4 2.3 来源声明模板：批注

这段模板非常关键，因为它把继承点和创新点一起写进去了：

• 保留 workspace-oriented collaboration
• 保留 member-driven execution
• 保留 terminal-based orchestration
• 新增 control-plane architecture
• 新增 runner protocol
• 新增 multi-server SSH coordination
• 新增 local-workspace-first strategy

这几项几乎就是 Naikaku 的“项目说明书摘要”。

五、第 3 章 Naikaku 相对 Golutra 的创新点：批注

5.1 原章作用

这一章是整本手册的“价值主张”。如果第 1 章回答“它是什么”，第 3 章回答的就是“它为什么值得单独存在”。

5.2 3.1 继承点：批注

继承点列出的其实是 Golutra 最有价值的几个抽象：

• workspace 作为组织单元
• member 作为执行身份
• conversation 作为任务入口
• terminal session 作为执行承载
• 多 CLI 统一协作壳

这些抽象说明原项目真正有价值的不是视觉界面，而是“协作组织方式”。

5.3 3.2 创新点逐条解释

控制机中心化：批注

把 124 提升为控制面，意味着系统第一次明确区分：谁负责管理，谁负责执行。这样能把调度、注册、审计、展示集中到一个稳定位置。

SSH 多服务器协同体系：批注

这一步是把单机/单桌面壳思路，升级为多机可调度体系。执行节点从“本地终端”变成“多台可调度 runner”。

本机工作区优先执行：批注

这是 Naikaku 最有个性的设计之一：优先改真实代码目录，而不是优先云端副本。这样做更符合你现在的实际开发习惯。

离线自动回退：批注

这说明系统把“本机不在线”视为常见场景，而不是异常边角。fallback 是主流程的分支，不是事后补救。

任务对象化：批注

从聊天驱动升级到任务对象驱动以后，系统才有了：

• 队列
• 超时
• 重试
• 审计
• 回退
• 产物

这一步是工程化分水岭。

Runner 协议化：批注

Runner 被抽象成正式节点后，控制机和执行机之间才有稳定契约，而不是“某台机器上正好有个脚本在跑”。

可审计工程闭环：批注

这一点意味着系统真正关心的是：不仅做了什么，还要知道是谁做的、在哪做的、做到了什么程度、失败时怎么恢复。

_ 批注示例图 1：第 3 章的创新点最终都落在这张部署结构图里 _

六、第 4 章 机器结构与角色分工：批注

6.1 原章作用

这一章把“概念”变成“机器角色”。从这里开始，手册开始进入可部署层。

6.2 4.1 控制机：124.220.233.126：批注

控制机的职责包含：

• 云端入口
• 成员与任务管理
• runner 注册与心跳管理
• 调度决策
• 日志与结果汇总

这说明控制机更像 control plane / scheduler / audit hub 的组合。

6.3 4.2 主执行机：Windows 本机：批注

主执行机承担的是“真实代码改动”的责任，因此它的关键不是算力，而是：

• 挂载真实工作区
• 可调用 Codex / Claude / Gemini / Shell 等执行器
• 可写、可验证、可回传结果

6.4 4.3 备用执行机：121.196.202.114：批注

备用机的真正价值在于“连续性”，不是“同样重要的主开发机”。它是为了保证：

• 本机掉线时任务不断
• 长任务不压主执行机
• 脚本型任务可以并行消化

6.5 4.4 补位机：111.228.6.224：批注

补位机更偏 shared runner，用来承接：

• 公共工作区任务
• 非本地依赖型任务
• 高峰期补位执行

6.6 本章的实施重点

• 机器分工必须稳定，不要让每台机器都既是 control plane 又是 fallback 又是 artifact store
• 主执行机、备用机、补位机的职责不能混写，否则 fallback 策略会变得不可预测

七、第 5 章 工作区模型：批注

7.1 原章作用

这一章定义的是“任务到底在哪个目录执行”，这比“在哪台机器执行”还关键。

7.2 5.1 工作区类型：批注

主工作区 primary

• 代表真实开发目录
• 优先级最高
• 适合高耦合修改、真实验证和正式改动

镜像工作区 mirror

• 代表备用目录
• 用于本机离线或需要转移负载时承接执行
• 要求和主工作区保持足够近似

公共工作区 shared

• 代表不依赖本机真实代码状态的工作目录
• 适合扫描、文档、分析、脚本和低耦合任务

7.3 5.2 任务工作区策略：批注

local_only

• 最严格
• 没有本机就不能干
• 适合必须依赖真实本地环境的任务

prefer_local

• 最平衡
• 有本机就优先本机，没有再 fallback
• 这是实际开发里最实用的默认策略

cloud_ok

• 最灵活
• 可以直接在 mirror/shared 执行
• 适合资料整理、批处理、脚本分析、非核心改动

7.4 5.3 工作区注册字段：批注

工作区字段其实回答了四个问题：

• 你是谁：workspaceId、name
• 你在哪：path
• 你属于谁：hostRunnerId
• 你能不能用：writable、healthy

实施提示：如果后续真落库，workspaceId 不要用临时路径字符串代替，应保持稳定 ID，与目录地址解耦。

八、第 6 章 AI 员工岗位设计：批注

8.1 原章作用

这一章把“模型”变成“岗位”，把“CLI”变成“执行器”。这是系统人格化与工程化结合的地方。

8.2 6.1 岗位与执行器映射：批注

• dispatcher 不是执行器，而是决策角色
• reviewer 负责兜风险，不一定直接改代码
• deployer 负责发布与回滚
• codex-engineer、claude-researcher、gemini-tooling 分别承担不同风格的工作
• shell-worker 负责最底层的脚本与系统动作

这说明系统希望把“谁擅长什么”内建到协议里，而不是每次靠 prompt 临时猜。

8.3 6.2 岗位设计原则：批注

这一节实际是在说三条组织原则：

1. 决策层和执行层分离
2. 执行层尽量绑定到明确 CLI 能力
3. 高风险动作要有 reviewer / deployer 这类控制环节

8.4 本章的实施重点

• roleHint 和 executorHint 必须同时存在，前者代表业务角色，后者代表技术载体
• 不能把所有工作都压给一个“万能 agent”，那会破坏本章设计初衷

九、第 7 章 任务对象规范：批注

9.1 原章作用

这一章是整本手册的核心之一，因为系统最终是围绕 Task 来流转的。

9.2 7.1 核心字段：批注

任务字段可以分成五组：

• 追踪组：taskId、traceId
• 目标组：projectId、repoRef、targetPath
• 路由组：workspacePolicy、preferredWorkspaceId、preferredRunnerId
• 执行组：title、instruction、roleHint、executorHint
• 控制组：priority、timeoutSec、fallbackAllowed、requiresApproval

9.3 7.2 任务状态机：批注

_ 批注示例图 2：任务状态机说明任务从排队到终态的闭环 _

• 状态机的意义不是画图好看，而是确保每种状态都有语义
• 一旦有 fallback，状态图就不能只用 queued / running / done 三段式糊弄过去
• 任务状态应该能解释“为什么失败”“是否还能重试”“是否已经切换执行位”

9.4 7.3 状态转换原则：批注

这部分虽然原文不长，但非常关键：

• 状态变化必须可追踪
• 终态必须可审计
• fallback 后要保留原 trace
• 锁和归属不能混乱

十、第 8 章 Runner 协议手册：批注

10.1 原章作用

第 8 章把控制机和执行机之间的契约讲清楚，是整个控制面的协议总章。

10.2 8.1 Runner 核心标识：批注

Runner 不是“哪台机器的一次临时启动”，而是稳定节点，因此需要：

• 稳定 ID
• 展示名
• 主机信息
• 版本信息
• 能力列表
• 并发能力

10.3 8.2 注册协议：批注

注册时机

注册时机决定控制机何时信任某 runner 可用；如果没有注册租约，后续的 heartbeat/pull/ack 都没有基础。

注册请求体

注册请求体里最重要的不是机器名，而是：

• runner 能力集
• 并发上限
• 附带的工作区视图

注册响应体

响应里最重要的不是“成功”两个字，而是：

• 是否 accepted
• lease 期限
• 下一次心跳间隔建议

10.4 8.3 心跳协议：批注

心跳除了告诉控制机“我还活着”，还应该告诉它：

• 我现在忙不忙
• 我手上有哪些 task
• 工作区健康不健康
• 机器负载是否还能接活

10.5 8.4 拉任务与 ACK：批注

• pull 是领取候选任务
• ack 才是锁定任务归属
• 这两个动作分离，能避免“看见任务就算接单”的竞态问题

10.6 8.5 日志流协议：批注

日志流的关键设计点有三个：

• sequence 必须递增
• 大日志必须拆片
• 控制机按 taskId + sequence 去重

这意味着日志协议已经具备最基本的“可补传”能力。

10.7 8.6 Artifact 规范：批注

Artifact 是工程闭环的一部分，而不是附件。之所以列 patch、test-report、build-log、screenshot、notes，是在告诉你：执行结果不只是一句“done”。

10.8 8.7 fallback 规则：批注

fallback 前必须释放旧锁、fallback 后必须重新 ACK、traceId 保持不变——这三条就是防止任务在多 runner 之间“幽灵执行”的关键规则。

10.9 8.8 标准错误码：批注

错误码单独列在 Runner 协议章结尾，说明作者的思路很清楚：错误恢复是协议的一部分，不是运维附录。

十一、第 9 章 完整 JSON 示例：批注

11.1 原章作用

第 8 章告诉你规则，第 9 章给你样例。它的功能是让协议从“概念”进入“可以照着写”。

11.2 9.1 Runner 注册请求：批注

这个 JSON 样例说明注册时不仅要报 runner 身份，还要把工作区视图一起上交控制机。

11.3 9.2 心跳请求：批注

心跳里包含：

• 在线状态
• 正在执行的任务列表
• 系统负载
• 工作区健康信息

这使得调度器可以做更细粒度决策，而不是盲目 round-robin。

11.4 9.3 拉任务响应：批注

拉任务返回的数据已经把执行意图编码得很完整：

• 做什么：title、instruction
• 谁来做：roleHint、executorHint
• 在哪做：preferredWorkspaceId、preferredRunnerId
• 如何退：fallbackAllowed

11.5 9.4 ACK / 日志 / 最终结果：批注

这一组样例等于把执行链拆成三段：

1. ACK 锁定归属
2. 日志持续上报过程
3. 最终结果提交摘要与 artifacts

11.6 9.5 fallback 重新分配示例：批注

这个样例最重要的是：fallback 不是把 task 复制一份，而是记录 from -> to 的明确迁移链。

十二、第 10 章 状态机与接口时序索引页：批注

12.1 原章作用

第 10 章让“协议文字”变成“执行流图”。对于多机协同系统，图往往比文字更能暴露时序问题。

12.2 10.1 任务状态机：批注

状态机图相当于整套 task lifecycle 的地图，没有它就很难统一“何时失败”“何时可 fallback”“何时算终态”。

12.3 10.2 注册时序：批注

_ 批注示例图 3：注册、租约确认与工作区同步时序 _

这张图说明：注册和工作区同步不是同一步，但属于一个连续初始化过程。

12.4 10.3 心跳时序 / 10.4 派单时序：批注

_ 批注示例图 4：心跳、拉任务、ACK 连续链路 _

把 heartbeat、pull、ack 合在一张图里，其实是一种很好的文档决策，因为这三者在真实系统里就是连续发生的。

12.5 10.5 回传时序：批注

_ 批注示例图 5：状态、日志与终态回传链路 _

这张图强调：状态、日志、终态不是一个接口，而是三段式回传机制。

12.6 10.6 fallback 时序：批注

_ 批注示例图 6：主执行机掉线后的 fallback 链路 _

fallback 时序图的价值在于把“主机掉线后应该谁先做什么”说清楚，避免大家只会说“那就切换一下”。

十三、第 11 章 模块调用关系图：批注

13.1 原章作用

这一章解释 Golutra 现有模块是怎么连起来的，它是你继承上游设计时最重要的源码结构入口。

13.2 11.1 总体调用结构：批注

_ 批注示例图 7：原版模块调用关系图 _

这张图告诉你：

• 前端并不直接调用 runtime
• 中间要经过 bridge/store、ui_gateway、message_service、orchestration、terminal_engine
• 数据与事件在前后端之间是有层次地流动的

13.3 11.2 聊天到终端执行链路：批注

_ 批注示例图 8：聊天消息到终端执行链路 _

这条链路说明：聊天只是输入源，真正的执行路径要经过桥接、编排、终端引擎和 PTY runtime。

十四、第 12 章 124 控制机 API 规范：批注

14.1 原章作用

这章是“控制面外部契约”总表，任何 runner、调度器、控制端页面都要尊重这里的接口定义。

14.2 12.1 推荐接口清单：批注

这组接口其实就是控制面的最小 API 面：

• 注册类：register
• 维持类：heartbeat
• 路由类：workspaces/sync、pull
• 锁定类：ack
• 回传类：status、logs、finalize
• 控制类：cancel
• 查询类：GET task/runner

14.3 12.2 API 原则：批注

• traceId 解决链路追踪
• 幂等写接口解决重试安全
• UTC 时间解决跨机一致性
• 审计式终态解决事后追溯

实施提示：如果要先做 MVP，也不要跳过 traceId、幂等和终态审计，这三项属于最难补的基础约束。

十五、第 13 章 Windows 主执行机 SOP：批注

15.1 原章作用

这一章是把“架构设计”压到“运维动作”层。它非常像值班手册。

15.2 13.1 启动前检查：批注

启动前检查之所以把 codex、claude、gemini、qwen、git 都列出来，是因为这台机器不是普通 CI worker，而是 多执行器统一入口。

15.3 13.2 任务执行流程：批注

这条流程最值得注意的是中间几步：

• 判断本机可执行
• 申请执行锁
• 切换工作区
• 检查 git 状态
• 生成 artifact

这些步骤说明系统非常强调“现场一致性”和“执行痕迹保留”。

15.4 13.3 停机流程：批注

draining 是一个很成熟的概念，它意味着停机前先停止接新活，再处理迁移/完成现有任务，而不是直接杀进程。

15.5 13.4 本机异常处理：批注

这些异常覆盖得很实用：

• 工作区不存在
• git 脏状态
• 执行器缺失
• 即将关机

这说明作者知道真问题都发生在这些地方，而不是只写理论 happy path。

十六、第 14 章 Golutra 源码解析摘要：批注

16.1 原章作用

这是从体系设计回到源码落位的一章，用来告诉你“这些概念在原项目里大概对应哪里”。

16.2 14.1 技术栈总览：批注

手册明确写出：

• 前端：Vue 3 + TypeScript + Pinia + Vite
• 后端宿主：Rust + Tauri

这说明它不是纯 Web App，而是桌面壳 + 本地宿主能力的组合。

16.3 14.2 顶层目录职责：批注

• src：前端 UI 和交互
• src-tauri/src：Rust 后端与平台能力
• docs：说明资料
• scripts：辅助脚本
• dist：构建产物

这是一个相当清晰的目录切分，适合二次演化。

16.4 14.3 前端主模块：批注

这里最值得注意的是 src/features/terminal 和 src/stores：

• 前者说明终端不是外挂，是主功能区
• 后者说明 orchestrator 状态会跨多个模块流动

16.5 14.4 后端主模块：批注

ui_gateway -> message_service / orchestration -> terminal_engine -> runtime 这条链路几乎就是系统的后端骨架。

16.6 14.5 关键执行链路：批注

这一节把“邀请成员”“派单”“会话”三条主线说出来了，对应的是：

• 成员配置入口
• 聊天到执行的业务主线
• 终端会话生命周期主线

16.7 14.6 对 Naikaku 的启示：批注

这句“真正需要补的是 runner 注册、任务对象、工作区路由和 fallback 机制，而不是继续魔改首页”可以看作整本手册最重要的工程判断之一。

十七、第 15 章 字段字典表：批注

17.1 原章作用

这一章让协议从“样例 JSON”变成“字段参考体系”。它是后续 reference 手册的基础材料。

17.2 15.1 按模块归类：批注

Runner 模块

Runner 字段解决的是“节点身份 + 节点能力 + 节点负载”。

Workspace 模块

Workspace 字段解决的是“执行目录身份 + 所属 runner + 健康可写性”。

Task 模块

Task 字段解决的是“执行意图 + 路由约束 + 生命周期控制”。

Result / Log 模块

Result / Log 字段解决的是“过程留痕 + 终态闭环 + 产物汇总”。

17.3 15.2 按字母序索引：批注

按字母序索引的价值在于：当你只记得一个字段名，而忘了它属于哪个对象时，可以快速回溯。

十八、第 16 章 错误码与恢复动作对照表：批注

18.1 原章作用

这章是运行手册的核心之一，因为它定义了“错误发生后控制机和 runner 各做什么”。

18.2 逐类错误的批注

• WORKSPACE_NOT_FOUND：说明路由对了，但目录现场不存在
• WORKSPACE_UNHEALTHY：说明目录还在，但状态不可靠
• EXECUTOR_MISSING：说明任务能派到这里，但执行器不匹配
• TASK_TIMEOUT：说明不是路由问题，是执行时长控制问题
• GIT_DIRTY_BLOCKED：说明系统显式保护脏工作区，不允许乱写
• LOCK_CONFLICT：说明已经考虑到并发写冲突
• RUNNER_OFFLINE / RUNNER_DRAINING：说明 runner 生命周期被纳入调度决策
• ARTIFACT_UPLOAD_FAILED / LOG_STREAM_BROKEN：说明结果与日志被当成正式数据通道维护

18.3 本章实施重点

错误码不应该只做成字符串常量，还应当绑定：

• 是否允许 fallback
• 控制机默认动作
• runner 默认动作
• 是否需要人工介入

十九、第 17 章 如何正确输出文档：批注

19.1 原章作用

这一章其实是在讲“如何长期维护工程型文档”。对这本手册自身来说，它是一条元规则。

19.2 17.1 输出原则：批注

• 永远保留 Markdown，意味着源文件优先
• 先 HTML 再 PDF，意味着把浏览器排版视为打印前验证层
• 不提前删中间产物，意味着文档链路本身也需要可回退

19.3 17.2 正确流程：批注

这套流程对应的是非常稳的导出链：

1. 写 Markdown
2. 准备 CSS
3. Pandoc 生成 HTML
4. 确认 HTML 真能打开
5. 浏览器 headless 打印 PDF
6. 抽查 PDF
7. 再清理中间文件
8. 至少保留 MD + PDF

19.4 17.3 禁止事项：批注

禁止事项比流程更值钱，因为它们定义了失败模式：

• 只留 PDF 不留 Markdown -> 以后不可维护
• 未验证 PDF 就删 HTML -> 以后不可复盘
• 图示报错还硬导出 -> 以后信息会失真
• 文件名仍沿旧项目名 -> 以后资产会混淆

二十、第 18 章 结论：批注

20.1 原章作用

这一章把全书判断压缩成一句话：Naikaku 不是简单换名，而是把 Golutra 的核心技术吸纳进新的多服务器执行体系。

20.2 结论批注

这句话有三层含义：

• 它承认上游技术来源
• 它强调你做的是控制面与执行体系重构，不是 UI 换皮
• 它要求后续继续以工程手册方式维护

二十一、附录 A 名词表：批注

21.1 原章作用

附录虽然短，但它负责把词汇冻结下来。对多角色协作系统来说，这非常重要。

21.2 关键词批注

• runner：不是脚本，不是模型，而是正式执行节点
• primary / mirror / shared：不是路径别名，而是不同执行优先级语义
• fallback：不是人工手动切换，而是协议内定义的回退机制
• traceId：不是日志字段点缀，而是全链路关联键
• ACK：不是普通回执，而是任务归属确认动作

二十二、整本手册的总评

22.1 这本手册最强的地方

• 有清晰的控制面思维
• 有多服务器执行语义
• 有任务对象和 Runner 协议
• 有错误码与恢复动作
• 有图、表、JSON、SOP、源码解析的完整组合

22.2 这本手册还可以继续增强的地方

• 可以把控制机内部的 Scheduler / Audit Store 再展开一章
• 可以把 artifact 存储与上传协议单列一章
• 可以把鉴权与 token 机制单列一章
• 可以把 Runner 实现侧状态机补成更细的 reference 图

22.3 一句话评价

这不是一份“介绍型手册”，而是一份已经接近“可落地控制面规范 + 执行节点协议 + 工程运维说明”的体系化文档；逐章批注后，它更适合作为后续实施和扩写的长期母本。

附录 F 服务器资产与角色规划总表（整合自《服务器资产与角色规划总表》）

一、结论速览

当前最合理的三层结构：

Windows 工作站 NEVERLETMEGO
        |
        v
124.220.233.126（主控制机）
   |            |             |
   v            v             v
121.196.202.114（主运行机） 221.5.60.2:10043（弹性算力机） 111.228.6.224（备用实验机）

角色结论：

• 124.220.233.126：主控制机，适合放控制台、调度、统一 API、状态中心。
• 121.196.202.114：主运行机，适合放 worker、批处理、长任务执行。
• 221.5.60.2:10043：Smoothcloud 弹性算力机，适合按需启停的高负载任务。
• 111.228.6.224：备用实验机/跳板机，适合测试、实验、低优先级备援。
• 140.143.229.144：当前对话承载机，不建议纳入长期业务主拓扑。
• Windows 工作站：开发、审核、手动接管、本地资源入口。

注：上面是“资产 / 角色定位”视图，不等于当前 control-plane/policy/execution-routing.json 的实际调度路由。按当前 control-plane 真源，dispatcher 在 124，默认执行仍是 121，全局 fallback 只有 Windows；111 与 221 已进入 servers.json，但尚未写入当前 execution-routing 规则。

二、当前环境总表

当前 deploy target 覆盖结论：

• control-plane/policy/deploy-targets.json 当前只有一个正式 deploy target：console-dev -> cloud-shanghai-01
• 也就是说，当前只有 124 被正式写成部署目标；170、121、221、111、Windows 工作站与 140 目前都没有独立 deploy target 条目

三、机器详细档案

1. 主控制机：124.220.233.126

124 控制机整机卡死快速恢复 SOP（2026-04-22 新增）

适用症状：

• mortis.tengokukk.com、console.tengokukk.com、http://124.220.233.126:5101 同时超时或长期无首字节。
• Resolve-DnsName 正常，22/80/443 的 TCP 仍能建立，但：
  • SSH 卡在 banner exchange，拿不到 SSH-2.0-...
  • curl -vk https://... 卡在 TLS 握手前后
  • curl -I http://... 已发出请求但 0 bytes received
• 同步出现时，优先按 124 的实例级卡死或宿主挂起处理，而不是先归因为某个前端页面、try_files、SPA fallback 或单一路由 404。

不要先下的结论：

• 在 HTTP 首字节都没回来前，不要先判断是 /mortis/* 路由、rewrite、location、Next.js 页面或前端构建问题。
• 在 SSH 只完成 TCP 建连、但 banner 不返回时，不要先把问题归为单纯 nginx 配置漂移。

推荐恢复顺序：

1. 先做分层确认，保留证据：
   • Resolve-DnsName mortis.tengokukk.com -Type A
   • curl -vkI --connect-timeout 8 --max-time 20 https://mortis.tengokukk.com/
   • curl -vI --connect-timeout 8 --max-time 20 http://mortis.tengokukk.com/
   • ssh -vv -o ConnectTimeout=8 ubuntu@124.220.233.126
2. 立即查询云侧真值，不再只围着 SSH 打转：
   • control-plane/scripts/observe-lighthouse-instance.ps1 -ServerId cloud-shanghai-01
   • 或 tccli lighthouse DescribeInstances --region ap-shanghai
3. 如果命中“TCP 通，但 SSH banner / TLS / HTTP 都卡死”的组合，且 cloud.instanceId=lhins-jqpgc12e 未变，就直接走云侧重启：
   • tccli lighthouse RebootInstances --region ap-shanghai --cli-unfold-argument --InstanceIds lhins-jqpgc12e
4. 轮询到实例恢复 RUNNING 且 LatestOperationState=SUCCESS 后，再恢复 SSH/站点验证：
   • 先看 SSH banner 是否恢复
   • 再看 https://mortis.tengokukk.com/ 是否恢复 307 -> /mortis/issues
   • 再看 https://mortis.tengokukk.com/mortis/issues、/mortis/autopilots 是否返回 200
5. SSH 恢复后补运行态确认：
   • systemctl is-active nginx
   • systemctl is-active docker
   • systemctl is-active multica-daemon.service
   • cd /srv/multica && sudo docker compose -f docker-compose.selfhost.yml ps

恢复判定：

• 云侧：InstanceState=RUNNING、LatestOperationState=SUCCESS
• SSH：能重新拿到 SSH-2.0-OpenSSH_... banner
• Mortis：根路径 307 到 /mortis/issues，目标页面返回 200
• 浏览器：/mortis/issues 与 /mortis/autopilots 实际可渲染

额外说明：

• 本次 2026-04-22 恢复中，atramenti-console.service 可以是 inactive，但只要 nginx、docker、multica-daemon.service 与 /srv/multica 栈正常，Mortis 站点仍可恢复对外服务；不要把该 service 的 inactive 误判成 Mortis 恢复失败。
• 若 RebootInstances 长时间停在 REBOOTING / OPERATING，继续保存 RequestId、轮询实例状态；一旦恢复到 RUNNING / SUCCESS，优先立即验证 SSH banner 与公开站点，而不是先深入应用日志。

124 控制机整机卡死 observer 自动恢复补强（2026-04-22 新增）

当前这条 SOP 不再只停留在“人工观察后手动重启”。control-plane/scripts/observe-lighthouse-instance.ps1 已补成可探测“实例表面仍是 RUNNING，但宿主机级别已基本挂死”的 observer：

• SSH 探针：
  • -ProbeSshBanner 会先测 22/TCP，再判断是否真的读到 SSH-2.0-* banner。
  • 若 TCP 已连通但 banner 迟迟不返回，记为一条 hang signal，而不是误判成“SSH 端口正常”。
• HTTP/TLS 探针：
  • -ProbeHealthEndpoints 会检查 publicConsoleRoot、publicConsoleSummary、publicConsoleSummaryDirect。
  • 探针会区分“TCP 已通但无 HTTP 响应”和“真的拿到 status code”；前者才计入 hang signal。
• likely hang 判定：
  • 当前实现不是单探针触发自动重启，而是至少命中 2 条 hang signal 才把 likelyHang=true。
  • 这条阈值是故意保守的：此前出现过单个 summary 端点偶发 timeout，但其它入口健康的情况；不能因为一个 probe 抖动就自动重启整机。
• 自动恢复入口：
  • 当 observer 运行在 -AutoRecoverOnHang 模式下，且实例当前仍处于 RUNNING 且最近云侧操作不是进行中时，会直接调用：
    • tccli lighthouse RebootInstances --region ap-shanghai --cli-unfold-argument --InstanceIds lhins-jqpgc12e
  • 默认带 -RecoveryCooldownMinutes 45，避免短时间重复重启；处于 cooldown 时，状态文件会写出 recoveryAction.skippedBecause=cooldown-active。
• 演练 / dry-run 入口：
  • 可用 -WhatIfRecovery 只记录“本来会触发恢复”，但不真正发起 RebootInstances。
  • 这适合在改阈值、加新探针或首次部署 observer 后做烟雾验证。

当前 canonical 执行入口：

& 'E:\My Project\Atramenti-Console\control-plane\scripts\observe-lighthouse-instance.ps1' `
  -RepoRoot 'E:\My Project\Atramenti-Console' `
  -ServerId cloud-shanghai-01 `
  -ProbeSshBanner `
  -ProbeHealthEndpoints `
  -AutoRecoverOnHang `
  -RecoveryCooldownMinutes 45

当前 canonical 计划任务入口：

• 注册脚本：control-plane/scripts/register-lighthouse-observer-task.ps1
• 计划任务名：Atramenti-CloudShanghai-01-LighthouseObserver
• 当前 live 注册参数：-NotifyOnStateChange -ProbeSshBanner -ProbeHealthEndpoints -AutoRecoverOnHang -RecoveryCooldownMinutes 45
• 当前 live task action：direct pwsh.exe -NoProfile -ExecutionPolicy Bypass -File control-plane/scripts/observe-lighthouse-instance.ps1 ...
• .cmd wrapper：已退场；Atramenti-CloudShanghai-01-LighthouseObserver 不再经过 %LOCALAPPDATA%\Atramenti-Console\scheduled-tasks\*.cmd 或 cmd.exe /c

验收口径：

• 正常态：.runtime/control-plane/cloud-observer/cloud-shanghai-01.status.json 应显示 observedStatus=healthy、likelyHang=false，并能看到 SSH banner 与 3 个 health probe 成功返回。
• 异常态：若再次出现“TCP 通但 SSH banner / HTTP 首字节都不回来”的组合，observer 应先把 hangSignals 写清楚，再决定是否进入 recoveryAction。
• 自动恢复态：一旦真实触发 RebootInstances，状态文件与 mortis-ops 告警应同时留下 requestId 与 signals，便于回溯是否误判。

2. 主运行机：121.196.202.114

3. 弹性算力机：221.5.60.2:10043（Smoothcloud / wummlp）

4. 备用实验机：111.228.6.224

5. 美西边缘机：170.106.179.226（Tencent Lighthouse / Silicon Valley）

6. 当前对话服务器：140.143.229.144

7. Windows 工作站：NEVERLETMEGO

6.1 Mortis / multica daemon / codex / openclaw 的本机链路说明

6.1.1 角色分工

在 NEVERLETMEGO 这条链上，推荐统一按下面口径理解：

• Mortis：控制面。负责展示项目、issue、run、runtime，以及把任务派发给在线 runtime。
• multica daemon：本机接单层。持续连接 https://mortis.tengokukk.com，认领任务、拉起 provider、回传状态/消息/结果。
• codex：本机 coding provider，适合文件修改、命令执行、最小 proof 之类任务。
• openclaw：本机另一条 provider 通道，适合复用 OpenClaw 本地能力与插件链。

可以把这条链简化记成：

Mortis 页面/控制台
  -> multica daemon（本机常驻接单进程）
      -> codex / openclaw（本机实际执行者）
          -> 本机文件、命令、工作目录
              -> 执行结果回传 Mortis

6.1.2 本机当前关键路径

当前 NEVERLETMEGO 上与这条链直接相关的关键路径如下：

6.1.3 当前 live 运行状态（2026-04-19）

本轮已验证：

• 本机 daemon 正在运行，状态可通过 multica daemon status --output json 看到；
• 当前挂到 Mortis 的本机 runtime 为：
  • Codex (NEVERLETMEGO)：a33ec2ef-6d85-4d34-9be9-bced2519e97a
  • Openclaw (NEVERLETMEGO)：288d44e6-05aa-489b-9ea1-3a6c6c451246
• 本机 daemon id 为 019da583-05f2-7927-95b6-5798e1e0dd77
• 当前已验证成功的一次本机 codex 实跑，是通过 daemon 以 CODEX_HOME=C:\Users\ASUS-KL\.codex-apikey 启动后完成的

6.1.4 最小排查命令

后续如果你怀疑“Mortis 页面有任务，但本机没动”，先看下面三类检查：

multica daemon status --output json

看 daemon 是否 running，以及是否仍挂着 codex / openclaw 两个 provider。

Get-Content 'C:\Users\ASUS-KL\.multica\daemon.log' -Tail 200

看 daemon 是否真正 picked task、provider 是否启动、是否有 status=completed 或错误。

Get-Content 'E:\My Project\.atramenti-demo\codex-local-proof.json'

看本机 proof 文件是否真实存在、内容是否更新。

6.1.5 本轮实证：MOR-1 失败，MOR-2 成功

这一轮已经把“本机 runtime 在线”与“本机 runtime 真的执行过任务”区分开，并补了闭环证据：

• MOR-1 / 23f12d73-4a3b-4cb5-8e6c-f406d8bb69ba
  • daemon 已成功 claim 任务；
  • 但 codex 侧因默认 profile C:\Users\ASUS-KL\.codex 命中 API key 并发上限而失败；
  • 这说明“runtime online”不等于“任务一定能执行成功”。
• MOR-2 / cea49965-243e-45cb-8a97-af134b12343e
  • 把 daemon 切到 CODEX_HOME=C:\Users\ASUS-KL\.codex-apikey 后重试成功；
  • run id：75d951b1-65d3-4807-9808-bb5884665f8a
  • 结果：成功写入 E:\My Project\.atramenti-demo\codex-local-proof.json