Atramenti-Console 文档汇编

这是一份按原文件顺序进行的无删减整合文档。
目标：把原本分散的 11 份说明文档合并成一个总文档，方便连续阅读、检索、打印、继续扩写。
原则：不删减原文内容，只增加整合页头和每一章的来源标记。

注：本文保留 2026-04-17 的整合结构，但其中涉及 MCP / Skill 真源路径的现行口径已按当前项目状态刷新到 codex 能力根。

若后续继续重排、吸收来源稿或收口这份总册，先遵循 C:\Users\ASUS-KL\.codex\AGENTS.md 中的文档规则层；维护说明见 C:\Users\ASUS-KL\.codex\AGENTS.annotated.md，不要再从它外面套新的薄导航页或平行“新版总览”。

边界说明：本文是 Atramenti-Console 主题的整合阅读总册与结构说明，不承担项目总体 current-state 三件套职责；如果要判断“项目现在是什么状态、下一步做什么”，优先看 PROJECT-CONTEXT.md、SESSION-HANDOFF.md、plan.md。

原文件顺序

1. 00 - Atramenti-Console 索引.md
2. 01 - Atramenti-Console 总览.md
3. 02 - Atramenti-Console 目录索引.md
4. 03 - Atramenti-Console 架构与模块原理.md
5. 04 - Atramenti-Console 运行端口与部署拓扑.md
6. 05 - Atramenti-Console 插件、MCP、Skill 注册机制.md
7. 06 - Atramenti-Console Apps 与 Shared 索引.md
8. 07 - Atramenti-Console MCP 模块索引.md
9. 08 - Atramenti-Console Skills 与知识系统索引.md
10. 09 - Atramenti-Console 当前上下文知识与排查入口.md
11. 10 - Atramenti-Console Control Plane 说明.md

来源文件：00 - Atramenti-Console 索引.md

Atramenti-Console 索引

位置：E:\My Project\Atramenti-Console 文档用途：把这个项目的结构、入口、模块原理、注册机制、运行拓扑、当前上下文知识整理成 Obsidian 可持续维护的知识包。

建议阅读顺序

1. 01 - Atramenti-Console 总览
2. 03 - Atramenti-Console 架构与模块原理
3. 04 - Atramenti-Console 运行端口与部署拓扑
4. 05 - Atramenti-Console 插件、MCP、Skill 注册机制
5. 07 - Atramenti-Console MCP 模块索引
6. 09 - Atramenti-Console 当前上下文知识与排查入口

文档列表

• 01 - Atramenti-Console 总览：项目定位、目标、当前迁移状态、核心模块
• 02 - Atramenti-Console 目录索引：根目录到一级目录的结构解释
• 03 - Atramenti-Console 架构与模块原理：server.mjs / gateway.mjs / Next shell / legacy 页面 / 控制面关系
• 04 - Atramenti-Console 运行端口与部署拓扑：本地、云端、工作站、运行节点、端口与部署规则
• 05 - Atramenti-Console 插件、MCP、Skill 注册机制：统一注册、配置、派生、扫描规则
• 06 - Atramenti-Console Apps 与 Shared 索引：apps/* 与 shared/* 的职责说明
• 07 - Atramenti-Console MCP 模块索引：主要模块的入口、路由、职责、阅读路径
• 08 - Atramenti-Console Skills 与知识系统索引：skills 体系、统一来源、共享方式
• 09 - Atramenti-Console 当前上下文知识与排查入口：我当前已经稳定掌握的项目知识点与故障排查顺序
• 10 - Atramenti-Console Control Plane 说明：控制面注册表、服务器、agent、路由策略

一句话理解这个项目

Atramenti-Console 不是“一个单纯前端项目”，它本质上是：

• 一个独立运行的控制台宿主
• 一个把多模块页面迁进统一壳层的前端母模板
• 一个把插件、MCP、技能、控制面、云端部署、工作站执行能力串起来的工程总线
• 一个逐步替代旧散装 HTML/脚本/临时运维入口的统一收口仓库

当前最重要的结构性真源（不是 current-state 入口）

• 项目运行主入口：E:\My Project\Atramenti-Console\server.mjs
• 本地插件网关：E:\My Project\Atramenti-Console\gateway.mjs
• 前端母模板：E:\My Project\Atramenti-Console\apps\console-web
• 插件清单派生源：E:\My Project\Atramenti-Console\shared\plugin-manifest.js
• 独立运行配置：E:\My Project\Atramenti-Console\atramenti.config.json
• 控制面注册表：E:\My Project\Atramenti-Console\control-plane
• MCP 真源目录：E:\My Project\Atramenti-Console\codex\mcps
• Skill 真源目录：E:\My Project\Atramenti-Console\codex\skills

来源文件：01 - Atramenti-Console 总览.md

Atramenti-Console 总览

1. 项目定位

Atramenti-Console 是一个“独立运行的 OpenClaw 控制台宿主工程”。

它做的不是单一业务，而是把以下几类东西收口到同一个仓库里：

• 前端壳层与统一工作台
• 多个业务模块页面
• 模块 API / SSE / 后端服务
• MCP 服务与包装器
• Skill 体系
• 控制面注册表
• 本地 / 云端 / 工作站的运行与部署链

它当前已经明确承载的核心用户面模块有：

• 小说管理 novel-manager
• 部署中心 deploy-center
• 自我调试闭环 self-debug-closed-loop
• 系统总览 system-overview
• 运维观测 ops-observer
• 数据库 API database-api
• 经验中心 experience-manager
• 文件管理 / 模型中心 / 自动化中心 / Key Guard 等辅助模块

2. 它不是一个什么项目

它不是：

• 单纯 Next.js 前端站点
• 单纯 MCP 仓库
• 单纯技能仓库
• 单纯部署脚本集合

它是“前端壳 + 模块目录 + 控制面 + 云端运行协议 + 本地工作站桥接”的综合工程。

3. 当前工程阶段

从现有 README、模块说明和运行配置来看，项目处于“迁旧保新”的中间阶段：

• 已经引入统一前端母模板：apps/console-web
• 已有 native route：/、/system-overview、/novel
• 仍然保留不少 legacy HTML 页面与 plugin 页面
• server.mjs 负责把 native route 与 legacy route 收拢到一个宿主下
• gateway.mjs 仍是本地独立插件网关的基础骨架

换句话说：

当前不是彻底新架构，也不是彻底旧架构，而是“以统一壳层和统一注册机制为中心的过渡架构”。

4. 顶层工作模式

这个仓库同时服务三种运行面：

4.1 本地开发面

• 本地直接跑 server.mjs
• 本地可跑 gateway.mjs
• 本地 Codex / 技能 / MCP 配置读取这套源码
• 本地浏览器验证新壳与模块页面

4.2 云端控制面

• 主云端节点承载公开控制台、控制面和部署入口
• 云端不应直接作为“源码真源”修改点
• 应从源码根发布到 runtime root

4.3 工作站执行面

• Windows 工作站保留桌面绑定、浏览器绑定、本地文件绑定的执行能力
• 这部分通过 control-plane 被正式建模，不再只是隐式桥接

5. 当前最关键的几条原则

5.1 真源原则

• 模块元信息真源：各自 mcps/*/module.json
• 插件托管派生真源：shared/plugin-manifest.js
• 独立运行配置真源：atramenti.config.json
• 控制面真源：control-plane/registry + control-plane/policy
• 本地技能真源：skills/
• MCP 真源：mcps/

5.2 源码根与运行根分离

控制面文档里已经明确：

• 不要把 /srv/atramenti-console 当源码真源
• 正确做法是：从 srcRoot 构建，再发布到 runtimeRoot

5.3 页面迁移原则

• 新页面尽量进入 apps/console-web
• 模块入口信息不手写在前端组件里，而是从模块元信息扫描得到
• 旧 HTML 页面仍可通过宿主代理/桥接存在，但不应再扩散为长期真源

6. 当前比较关键的模块分组

6.1 面向人直接操作的模块

• novel-manager
• deploy-center
• self-debug-closed-loop
• system-overview
• ops-observer
• vscode-key-guard
• database-api
• experience-manager

6.2 基础设施/工具型 MCP 模块

• ripgrep-search
• repo-inspector
• standards-guard
• orchestration-pipeline
• output-guard
• context-store
• database-ops-mcp（db-readonly 兼容层）
• playwright-browser
• log-diagnose

6.3 共享层

• shared/：独立宿主的派生逻辑、导航、控制面读取、配置读取
• mcps/shared/：扩展体系里的共享导航真源
• control-plane/：服务器与 agent 的统一注册与执行策略

7. 一句话抓总

如果只记一句：

Atramenti-Console = “统一壳层 + 模块真源目录 + 控制面 + 云端运行/工作站桥接 + MCP/Skill 能力仓” 的总控仓库。

来源文件：02 - Atramenti-Console 目录索引.md

Atramenti-Console 目录索引

根目录：E:\My Project\Atramenti-Console

1. 根目录一级结构

apps

承载前端应用层。

当前主要有：

• console-web：新的统一前端母模板，Next.js 16 + React 19 + TS + Tailwind v4
• database-api：数据库 API 相关应用资料目录，目前更偏文档/状态映射

control-plane

项目级控制面。统一维护：

• 服务器注册表
• agent 注册表
• 部署目标映射
• 执行路由策略
• 提升门槛/promotion gate

cookies-accounts

账号、cookie、平台登录相关的运行态/辅助数据目录。通常与平台自动化、发布链相关。

data

仓库级共享运行数据或快照数据。

extensions

偏扩展开发说明、规则性文档，不是主要业务模块真源。

mcps

本仓库最重要的能力目录之一。

这里面包含：

• 业务模块
• MCP wrapper
• 工具型服务
• 共享扩展资源
• 运行验收脚本与产物

projects

项目级工作区或历史/派生目录。

scripts

仓库级脚本，用于构建、部署、同步、诊断、辅助维护。

shared

独立宿主共享层。包括：

• plugin-manifest.js
• standalone-config.js
• nav-registry.js
• control-plane.js
• 独立 home / nav HTML

skills

本地 Codex 技能真源目录。当前已经是比较大的统一技能仓。

workspace

工作区、实验区、临时协作区。

2. 根目录关键文件

package.json

工作区脚本和总依赖入口。关键点：

• pnpm@9.15.9
• Node >=20
• dev 跑 server.mjs
• gateway:dev 跑 gateway.mjs
• ci 走 turbo run lint typecheck build
• 有 deploy:cloud:* 和 agent:* 系列脚本

pnpm-workspace.yaml

声明 workspace 包范围：

• 根目录
• apps/*
• mcps/*
• mcps/feishu-center/integrations/*

turbo.json

多包任务编排，当前主要有：

• build
• lint
• typecheck

server.mjs

独立宿主入口。负责：

• 启动 Atramenti Console
• 托管/代理 native route
• 代理 legacy 模块页面/API
• 按插件清单加载页面与模块

gateway.mjs

本地插件网关入口。负责：

• HTTP 服务
• 插件加载
• 模块路由注册
• 健康检查
• 环境根路径注入

atramenti.config.json

独立运行配置真源。当前包含：

• 浏览器运行默认参数
• enabled plugin entries
• 每个插件的单独配置（如 standalone、provider 等）

RUNTIME-TOPOLOGY.md

当前运行拓扑与分工说明：

• 上海主云端节点
• 杭州运行节点
• Windows 工作站
• MCP 远程包装与执行分布

3. mcps/ 一级模块索引

当前有三类内容：

3.1 业务/管理模块

• novel-manager
• deploy-center
• self-debug-closed-loop
• experience
• database-api
• ops-observer
• qwen3-tts
• file-manager
• automation
• ai-model-hub
• aghub-bridge
• superset-bridge
• vscode-key-guard
• system-overview
• feishu-center

3.2 工具型 / MCP wrapper

• ripgrep-search
• repo-inspector
• standards-guard
• orchestration-pipeline
• playwright-browser
• context-store
• database-ops-mcp（db-readonly 兼容层）
• log-diagnose
• output-guard
• prompt-compressor
• cloud-repo-mcp
• dev-quality-mcp

3.3 共享与模板

• _shared
• _templates
• shared
• core
• plugins
• kernel

4. skills/ 一级结构理解

技能目录非常大，但可以按用途分：

• 自我调试与前端验证：self-debug-closed-loop、frontend-evidence、readiness-wait-gate
• Agent 提升与长期闭环：agent-improvement-ops
• MCP / 插件 / skill 构建：mcp-server-patterns、create-skill、create-subagent
• 研究与搜索：deep-research、search-first、qmd
• GSD 系列项目管理技能：gsd-*
• 运维与云端：tencentcloud-ops、gateway-restart-safe
• 验收/发布：module-acceptance、release-preflight

5. 当前最值得优先建立脑图的目录

如果要最快理解整个仓库，优先看：

1. server.mjs
2. gateway.mjs
3. shared/
4. apps/console-web/README.md
5. control-plane/README.md
6. mcps/novel-manager/README.md
7. mcps/self-debug-closed-loop/README.md
8. RUNTIME-TOPOLOGY.md

来源文件：03 - Atramenti-Console 架构与模块原理.md

Atramenti-Console 架构与模块原理

1. 总体架构

这个仓库的架构可以拆成 5 层：

1. 宿主层：server.mjs
2. 网关层：gateway.mjs
3. 前端壳层：apps/console-web
4. 模块层：mcps/*
5. 控制面与共享能力层：control-plane/ + shared/ + skills/

2. server.mjs 的角色

server.mjs 是 Atramenti-Console 的独立宿主入口。

它当前不是“只提供静态页面”，而是做这些事：

• 启动独立控制台 HTTP 服务
• 代理部分 native route 到 apps/console-web
• 代理 legacy 模块页面/API
• 读取共享插件清单
• 按配置加载插件页面
• 在需要时自动拉起 apps/console-web 的 Next 进程

2.1 当前已迁入 native 的路径

从现有代码与 README 看，当前迁入的 native route 主要是：

• /
• /system-overview
• /novel

说明：

• /novel 已迁到新壳层，但它的数据仍有明显 legacy 后端成分
• /novel 首屏依赖 dashboard snapshot，增量依赖 SSE
• 所以它是“新壳 + 旧后端聚合”的典型过渡页

3. gateway.mjs 的角色

gateway.mjs 是本地独立插件网关。

它更像“插件加载器 + 路由注册器 + 本地环境桥”。

它负责：

• 建立 HTTP 服务
• 加载已启用插件
• 注册模块路由
• 提供 /health
• 注入多个运行时根路径环境变量

3.1 它注入的环境根信息很重要

从现有代码看，gateway.mjs 会设置类似这些根：

• OPENCLAW_PROJECT_ROOT
• OPENCLAW_WORKSPACE_ROOT
• OPENCLAW_RUNTIME_ROOT
• NOVEL_MANAGER_WORKSPACE_ROOT
• NOVEL_MANAGER_ROOT

这说明它不仅是网关，也是“路径真源协调器”。

4. 新前端壳层 apps/console-web

这是当前前端架构里最重要的新基座。

4.1 它的定位

不是某个业务页，而是：

• 统一壳层
• 统一模块工作台模板
• 统一 UI 组件层
• 后续模块迁移的母模板

4.2 当前技术栈

• Next.js 16
• React 19
• TypeScript
• Tailwind CSS v4
• Radix UI
• CVA

4.3 它的真源原则

• 模块来源不写死在前端组件里
• 模块入口从 mcps/*/module.json 扫描
• 侧栏 / 首页 / native/legacy 状态共用同一份模块注册数据
• 页面优先组合组件，不再散写整页 HTML/CSS

4.4 核心代码位置

• 模块扫描真源：apps/console-web/lib/module-registry.ts
• 壳层真源：apps/console-web/components/console/app-shell.tsx
• 业务积木层：apps/console-web/components/console/*
• 小说工作台：apps/console-web/components/novel-manager/novel-dashboard.tsx

5. 模块层 mcps/*

这个仓库的模块层并不统一只有一种形态，而是多种形态并存：

5.1 业务模块型

例子：

• novel-manager
• deploy-center
• self-debug-closed-loop
• database-api
• ops-observer

典型特点：

• 有 module.json
• 有页面入口
• 有 API 前缀
• 常带 plugin 入口
• 可能还带独立 app/backend/core/frontend 分层

5.2 工具型 MCP wrapper

例子：

• ripgrep-search
• repo-inspector
• standards-guard
• orchestration-pipeline

典型特点：

• 偏 server.mjs / wrapper 入口
• 提供 tool 级能力
• 适合本地 stdio 或未来远程 HTTP MCP

5.3 共享/模板型

例子：

• mcps/shared
• mcps/_shared
• mcps/_templates
• mcps/core

这些不是直接给最终用户看的业务页，而是模块体系的底座。

6. novel-manager 的模块原理

novel-manager 是当前最复杂、最工程化的业务模块。

6.1 它的职责链

它要把这条链路收口：

• 作品
• 章节
• 正文
• 审核
• 待发布
• 自动发布
• 平台确认
• 前端可视化

6.2 它内部的分层

• frontend/：小说管理页面源码
• app/：HTTP / API / SSE / dashboard 聚合入口
• backend/：服务层
• core/fanqie/：平台发布与平台运行时能力
• core/workflow/：规则、调度、状态机
• core/manuscript/：生成、润色、审核、记忆、风格
• tools/：验收与平台工具

6.3 它的核心闭环

1. 页面通过 API/SSE 读 dashboard
2. app/index.ts 聚合后端状态
3. backend/services/novel-service.ts 与 core/* 提供数据/动作
4. SmartScheduler 驱动调度
5. PublishOrchestrator 统一发布编排
6. FanqiePublisher 执行发文
7. PublishResultService 回写并确认平台真源

6.4 这说明什么

novel-manager 不是普通 CRUD 页面，而是一个“状态机 + 调度器 + 平台自动化 + 编辑器”的复合系统。

7. self-debug-closed-loop 的模块原理

这个模块的重点不是页面本身，而是“统一能力目录与闭环协议”。

它负责：

• 扫描 skills/ 与 mcps/
• 过滤掉不适合共享的目录
• 构建统一 catalog snapshot
• 暴露给 agent / 管理员读写
• 给共享技能/MCP 提供可视化查看与维护入口

本质上它是：

本仓库内部“能力目录”的管理面板。

8. 控制面与运行节点的关系

control-plane/ 不是运行代码本体，而是：

• 服务器库存
• agent 库存
• 部署目标映射
• 执行路由规则
• 提升门槛

也就是说：

• server.mjs / gateway.mjs 解决“怎么跑”
• control-plane/ 解决“应该在哪跑、以谁为真源、路由到哪里”

9. 真正的架构关键

这个项目的关键不在某个单文件，而在三组“统一”：

9.1 统一壳层

• apps/console-web
• server.mjs

9.2 统一模块真源

• mcps/*/module.json
• shared/plugin-manifest.js

9.3 统一执行/部署认知

• control-plane/*
• RUNTIME-TOPOLOGY.md

10. 最实用的理解图

可以直接把项目理解成这条链：

skills/mcps/control-plane 提供能力和规则 -> server.mjs / gateway.mjs 负责加载和路由 -> apps/console-web 提供统一前端壳 -> mcps/* 提供实际模块能力 -> 云端/工作站节点负责真实执行与验证

来源文件：04 - Atramenti-Console 运行端口与部署拓扑.md

Atramenti-Console 运行端口与部署拓扑

1. 三个主要节点

根据 RUNTIME-TOPOLOGY.md 和 control-plane 注册表，当前项目是三节点结构：

1.1 上海主云端节点

• 服务器：124.220.233.126
• 角色：console、control-plane
• SSH 用户：ubuntu
• 源码根：/home/ubuntu/atramenti-console-src
• 运行根：/srv/atramenti-console
• 备份根：/home/ubuntu/atramenti-console-backups
• 服务：atramenti-console.service

用途：

• 公开控制台入口
• 控制面承载
• 部署验证面
• 对外可访问 UI/API

1.2 杭州运行节点

• 服务器：121.196.202.114
• 角色：runtime、mcp-offload、worker
• 运行根：/srv/mcp-runtime
• MCP bundle 根：/srv/mcp-runtime/apps/codex-portable-mcps
• 镜像工作区：/srv/mcp-runtime/work

用途：

• 运行重型 MCP / worker 任务
• 提供 mirrored workspace 执行面

当前阻塞：

• 22 端口 TCP 可连，但 SSH banner 超时
• 所以它还不能被当成完全可靠的主 worker

1.3 Windows 本地工作站

• 主机名：NEVERLETMEGO
• 角色：windows-workstation、local-file-executor、desktop-bound
• Codex 根：C:\Users\ASUS-KL\.codex
• OpenClaw 根：C:\Users\ASUS-KL\.openclaw
• 本地工具运行根：E:\My Project\Atramenti-Console\.runtime\deploy\local-tools

用途：

• 真实桌面浏览器动作
• 本地文件操作
• 编辑器绑定动作
• 本地配置读写

2. 主要端口与地址

2.1 Atramenti Console 宿主

• 默认本地端口：5101
• 启动脚本：pnpm run dev
• 入口文件：server.mjs

典型访问地址：

• http://127.0.0.1:5101/
• http://127.0.0.1:5101/system-overview/
• http://127.0.0.1:5101/novel/

2.2 本地 gateway

• 默认端口：5000
• 启动脚本：pnpm run gateway:dev
• 入口文件：gateway.mjs

2.3 console-web 内部 Next 代理端口

从 server.mjs 现有设计可知，内部 Next 前端还有一个单独的代理端口，默认是：

• 3202

它由宿主自动拉起/代理，平时用户不一定直接访问。

2.4 控制面健康地址

主云端节点已登记：

• 正式公网入口：https://console.tengokukk.com/
• 公网 summary：https://console.tengokukk.com/api/console/summary
• 本地 summary：http://127.0.0.1:5101/api/console/summary

3. 部署的正确认知

3.1 不要把运行目录当源码真源

控制面文档已经明确：

• /srv/atramenti-console 是 runtime root
• 不是 source of truth

正确流程是：

1. 在源码根修改
2. 构建/打包
3. 发布到运行根
4. 验证服务与页面

3.2 运行节点职责分工

• 124：控制面、公开 UI、管理节点
• 121：重型 runtime / worker / offload
• Windows：桌面绑定、本地文件绑定、浏览器动作

3.3 远程 MCP 的包装方式

本地 Codex 的 remote-offloaded MCP 通过：

• C:\Users\ASUS-KL\.codex\remote-mcp.ps1
• C:\Users\ASUS-KL\.codex\remote-mcp.cmd

SSH 到运行节点并启动：

• node <mcp>/server.mjs

4. 技能与 MCP 的实际存放/消费关系

4.1 Skill 真源

• 真正可编辑的本地 skill 源：E:\My Project\Atramenti-Console\codex\skills
• C:\Users\ASUS-KL\.codex\skills 是指向它的 junction/消费入口

4.2 MCP 真源

• 源码真源：E:\My Project\Atramenti-Console\codex\mcps
• 远程运行 bundle：/srv/mcp-runtime/apps/codex-portable-mcps

4.3 镜像工作区

运行节点工作区：

• /srv/mcp-runtime/work/Atramenti-Console
• /srv/mcp-runtime/work/Atramenti-OpeClaw

原则：

• 搜索/探测型 MCP 优先指向云端镜像工作区
• 不直接依赖本地 Windows 路径

5. 工作站本地桥

Windows 本地执行能力依赖：

• 本地 SSH listener：127.0.0.1:22222
• reverse tunnel supervisor：C:\Users\ASUS-KL\.openclaw\aliyun-reverse-ssh.ps1
• node supervisor：C:\Users\ASUS-KL\.openclaw\node-supervisor.ps1

这些让控制面能把“必须发生在真实工作站上的动作”正式分发到本地，而不是假装所有事情都能在云端完成。

6. 当前实际部署判断标准

如果要判断“是否适合部署/是否部署成功”，不能只看：

• HTTP 200
• 进程活着
• systemd running

还要看：

• 页面是否正确渲染
• 路由是否能进入目标模块
• 新壳与 legacy 是否没断
• 关键 SSE / API 是否正常
• 用户可见结果是否对

这和项目里的 self-debug-closed-loop 原则是一致的。

来源文件：05 - Atramenti-Console 插件、MCP、Skill 注册机制.md

Atramenti-Console 插件、MCP、Skill 注册机制

1. 先说结论

这个项目不是靠单一注册文件完成所有事情，而是“多层注册、逐层派生”：

1. 模块自身元信息：mcps/*/module.json
2. 宿主托管清单：shared/plugin-manifest.js
3. 独立运行开关与模块配置：atramenti.config.json
4. 控制面服务器/agent/部署规则：control-plane/*
5. Codex 侧 MCP 启用：C:\Users\ASUS-KL\.codex\config.toml
6. Skill 真源与消费：skills/ -> C:\Users\ASUS-KL\.codex\skills

2. 模块注册：module.json

每个可进入系统壳层的模块，原则上都有自己的：

• mcps/<module>/module.json

它承担的角色：

• 模块元信息真源
• 路由/壳层信息来源
• 系统总览扫描来源
• 模块地图与自动发现来源

在 apps/console-web 里，模块注册读取逻辑已明确从 mcps/*/module.json 扫描。

3. 宿主插件清单：shared/plugin-manifest.js

这是当前独立宿主最核心的“托管派生清单”。

它集中定义了：

• id
• localName
• pluginEntry
• routeBase
• frontendRoot
• entryFile
• openclawPath

3.1 它解决什么问题

• 哪些模块可由宿主托管
• 每个模块的路由前缀是什么
• legacy 页面根目录在哪里
• OpenClaw allow/load path 应该怎么自动派生

3.2 它提供的关键派生能力

• buildAppPages(repoRoot)：构建页面根索引
• getOpenClawAllowList()：派生 allow list
• getOpenClawLoadPaths()：派生 load paths
• getStandaloneManagedPlugins()：输出独立宿主管理的插件集合

这意味着：

atramenti.config.json 不再手工长期维护 plugins.allow / plugins.load.paths，而是由 manifest 派生。

4. 独立运行配置：atramenti.config.json

这个文件主要负责“开关”和“模块配置”，而不是替代 manifest。

当前里面可见的信息包括：

• 浏览器默认配置
• enabled plugins entries
• 某些模块的 standalone 配置
• 某些模块的 provider 配置

4.1 它当前启用的核心模块

• qwen3-tts
• novel-manager
• deploy-center
• self-debug-closed-loop
• vscode-key-guard
• experience-manager
• automation-hub
• ai-model-hub
• file-manager
• ops-observer
• aghub-bridge
• superset-bridge
• database-api

5. 顶部导航与壳层入口扫描：shared/nav-registry.js

这个文件会扫描 mcps/*/module.json，提取：

• top nav 项
• shell entry
• route prefix
• api prefix
• icon/group/summary/homepage 等壳层元信息

5.1 它说明了什么

说明项目现在正在把“壳层导航”从手写常量，转成“模块元信息驱动”。

这件事非常关键，因为它决定：

• 新增模块时先改元信息，不是先改前端死代码
• 导航、模块首页、系统总览、迁移状态可以共源

6. 控制面注册：control-plane/*

这一层不是页面层注册，而是部署/执行注册。

6.1 registry/servers.json

定义物理/运行节点：

• cloud-shanghai-01
• cloud-hangzhou-01
• windows-workstation-01

6.2 registry/agents.json

定义共享能力消费者：

• codex-local-primary
• windows-local-executor
• cloud-console-runtime
• cloud-runtime-worker

6.3 policy/*

定义：

• deploy target 映射
• execution routing
• promotion gate

这层回答的是：

• 哪个任务该去哪里执行
• 哪个部署目标对应哪台机器
• 哪些节点消费哪些 shared capability sources

7. Skill 注册机制

7.1 真源

• E:\My Project\Atramenti-Console\codex\skills

7.2 消费入口

• C:\Users\ASUS-KL\.codex\skills

目前通过 junction/共享方式消费，所以：

• 维护时改仓库里的 skill 即可
• 本地 Codex 实际拿到的是同一套源

7.3 特殊点

self-debug-closed-loop 模块还会扫描技能目录并生成 catalog snapshot，所以 skill 不只是“本地模型提示词”，也成了“平台能力目录的一部分”。

8. MCP 注册机制

MCP 维度有两层：

8.1 源码层

• 真源在 mcps/*

8.2 Codex 运行层

• 由 C:\Users\ASUS-KL\.codex\config.toml 决定启用哪些 MCP
• 远程 offload 型 MCP 通过 remote-mcp.ps1/.cmd 包装到云端运行

8.3 远程 bundle 层

• 运行 bundle 在 /srv/mcp-runtime/apps/codex-portable-mcps

所以 MCP 不是单点注册，而是：

• 仓库中定义
• Codex 中启用
• 必要时在云端 bundle 中运行

9. 当前最实用的理解方式

如果你要追一个模块“为什么会出现在页面里 / 出现在控制台里 / 被 agent 用到”，按这个顺序查：

1. mcps/<module>/module.json
2. shared/plugin-manifest.js
3. atramenti.config.json
4. shared/nav-registry.js
5. control-plane/registry/*.json
6. C:\Users\ASUS-KL\.codex\config.toml

来源文件：06 - Atramenti-Console Apps 与 Shared 索引.md

Atramenti-Console Apps 与 Shared 索引

1. apps/console-web

这是当前新的统一前端母模板。

技术栈

• Next.js 16
• React 19
• TypeScript
• Tailwind CSS v4
• Radix UI primitives
• class-variance-authority

目录要点

• app/：Next app router 页面
• components/console/：控制台业务积木
• components/ui/：基础 UI 原件
• components/novel-manager/：小说管理新壳组件
• components/system-overview/：系统总览组件
• lib/console-api.ts：控制台 API 调用
• lib/module-registry.ts：扫描 mcps/*/module.json

当前 native route

• /
• /system-overview
• /novel

当前意义

它是后续前端统一迁移的真正母模板，不只是一个 demo 项目。

2. apps/database-api

当前更像数据库 API 相关应用材料/状态映射区，主要不是完整前端应用。

可把它理解为 database-api 模块在 apps 侧的补充资料位。

3. shared/

这是独立宿主的共享层，不要和 mcps/shared/ 混淆。

核心文件

• plugin-manifest.js：宿主托管插件清单真源
• standalone-config.js：读取 atramenti.config.json
• nav-registry.js：扫描模块元信息并生成壳层导航数据
• control-plane.js：读取控制面注册表与策略
• FRONTEND_SHELL_README.md：独立壳相关说明
• standalone-home.html：独立首页模板
• nav-bar-standalone.html：独立导航 HTML

它的职责

• 连接“静态配置”与“运行派生”
• 为 server.mjs 提供插件和导航的中间层
• 统一读取控制面信息，避免宿主层直接手搓路径

4. mcps/shared/

这是扩展体系内部的共享导航真源。

核心用途：

• 统一导航栏 HTML 真源
• 服务端注入工具
• 前端导航行为脚本
• 共享诊断页面

它和 shared/ 的区别

• shared/：Atramenti-Console 独立宿主共享层
• mcps/shared/：扩展模块体系内部共享资源层

5. 这两层为什么容易混

因为它们都叫 shared，但服务对象不同：

• 一个偏宿主编排
• 一个偏扩展 UI 真源

实际排查时不要混用。

6. 最实用的排查顺序

页面为什么没进入新壳

查：

1. apps/console-web/lib/module-registry.ts
2. shared/plugin-manifest.js
3. server.mjs

顶部导航为什么不对

查：

1. shared/nav-registry.js
2. mcps/*/module.json
3. mcps/shared/*

独立运行配置为什么没生效

查：

1. shared/standalone-config.js
2. atramenti.config.json

来源文件：07 - Atramenti-Console MCP 模块索引.md

Atramenti-Console MCP 模块索引

1. 当前主要有 module.json 的业务模块

2. 当前最关键模块说明

novel-manager

定位：小说生产与发布闭环。

关键入口：

• mcps/novel-manager/app/index.ts
• mcps/novel-manager/backend/services/novel-service.ts
• mcps/novel-manager/core/workflow/scheduler/SmartScheduler.ts
• mcps/novel-manager/core/fanqie/publishing/*
• mcps/novel-manager/frontend/pages/novel/index.html

关键理解：

• 这是状态机 + 调度器 + 发布自动化 + 编辑工作台的复合系统
• 不是简单前端模块

deploy-center

定位：开发期远端部署链路的统一真源。

承载：

• 本机文件监听
• 归档/上传
• 远端覆盖
• 网关重启
• 云端健康检查
• 本地自连辅助工具
• 页面状态聚合

self-debug-closed-loop

定位：共享技能/MCP 目录管理与可视化闭环模块。

承载：

• 扫描 skills/ 与 mcps/
• 生成 catalog.snapshot.json
• 暴露 agent/admin 管理接口
• 统一收口共享能力目录

database-api

定位：统一数据库服务边界。

承载：

• schema 浏览
• 受控资源访问
• stats / 审计 / 状态机统计
• 经验记录等云端治理资源

ops-observer

定位：低耦合运维观测页。

承载：

• 服务状态聚合
• 端口信息
• Netdata 概览桥接

system-overview

定位：项目级结构总览模块。

承载：

• 模块地图
• 真源地图
• 运行状态概览
• 架构详情聚合

3. 工具型 MCP/wrapper 索引

ripgrep-search

• 用途：快速代码/文本搜索 MCP
• 适合：本地 stdio MCP、未来远程 HTTP MCP

repo-inspector

• 用途：仓库/目录探测 wrapper
• 适合：验收与存在性检查

standards-guard

• 用途：标准门禁 MCP
• 默认动作：在目标仓库执行 npm run check

orchestration-pipeline

• 用途：Roo orchestration pipeline 包装器
• 提供：运行 pipeline 与 relay audit 验证工具

playwright-browser

• 用途：浏览器能力 MCP wrapper

context-store / database-ops-mcp / output-guard / prompt-compressor / log-diagnose

• 当前多为包装器/基线 MCP
• 其中数据库检查链路的 canonical 名称已切到 database-ops-mcp，db-readonly 仅保留兼容层
• 负责把特定能力通过统一 MCP 形态接入系统

4. 共享/内核型目录

mcps/core

跨模块共享数据库、配置、底层能力。

mcps/shared

共享导航真源。

mcps/_shared

MCP wrapper 的共用脚手架，例如 probe server。

mcps/kernel

更偏底层/测试/运行相关的内核区。

5. 如果要读一个模块，建议最少看四样东西

1. module.json
2. README.md
3. 入口文件（plugin/index.ts 或 app/index.ts 或 server.mjs）
4. 页面/API 主入口

来源文件：08 - Atramenti-Console Skills 与知识系统索引.md

Atramenti-Console Skills 与知识系统索引

1. Skill 真源位置

• 真源：E:\My Project\Atramenti-Console\codex\skills
• 本地 Codex 消费入口：C:\Users\ASUS-KL\.codex\skills

这意味着当前 skill 已经基本实现“仓库统一维护，本地直接消费”。

2. 技能体系的实际作用

这个仓库里的 skills 不是随手堆的 prompt 片段，而是项目运行方式的一部分。

它们承担：

• 固化稳定工作流
• 给 agent 注入项目级约束
• 定义验收闭环
• 管理研究/部署/前端验证/故障排查方法
• 逐步形成长期能力目录

3. 当前技能的大致分层

3.1 可见结果验证/自我调试

• self-debug-closed-loop
• frontend-evidence
• readiness-wait-gate
• closed-loop-ops
• regression-snapshot

这是最关键的一组，因为它们直接影响“页面修复是否算完成”。

3.2 Agent 能力提升与长期闭环

• agent-improvement-ops
• module-acceptance
• release-preflight
• api-validation-matrix

这组偏“能力进化与验证基础设施”。

3.3 MCP/插件/技能开发

• mcp-server-patterns
• create-skill
• create-subagent
• plugin-creator
• skill-creator
• skill-installer

3.4 研究与知识检索

• deep-research
• search-first
• qmd
• experience-manager

3.5 运维与云端

• tencentcloud-ops
• gateway-restart-safe
• incident-triage
• windows-safe-exec

3.6 GSD 项目管理体系

• gsd-* 全家桶

这一组是大型项目规划/执行/审计/文档/验证流程。

4. 当前最重要的几个技能

self-debug-closed-loop

这是当前项目最硬性的用户可见验证协议。

核心要求：

1. 验证运行态
2. 验证可见结果
3. 留下至少一个证据
4. 给出 verified / unverified / failed

它的意义是：

• 不允许拿 HTTP 200 当页面修复完成
• 不允许拿“服务启动了”替代“界面正确了”

agent-improvement-ops

用于评估和推进长期自我提升栈，包括：

• eval harness
• telemetry foundation
• 自调试/长反馈回路
• 云端安装/共享模块

search-first

要求先搜现成轮子、模式、仓库方案，再决定是否自己造。

deep-research

用于需要证据链的深入研究，强调本地记忆优先，再扩展官方文档/GitHub/web。

5. Skill 与 MCP 的关系

在这个仓库里，skill 与 MCP 不是分离世界：

• Skill 负责方法论、工作流、执行约束
• MCP 负责可调用工具能力
• self-debug-closed-loop 模块把这两者都纳入统一目录快照与可视化管理

6. 为什么这个技能系统很重要

因为当前项目已经不是单人手工维护小仓库，而是“多 agent / 多节点 / 多模块”协同体系。

没有 skill 体系，就会出现：

• 每次都重新解释工作流
• 页面验证标准漂移
• 部署/调试动作不一致
• 长期经验无法沉淀

7. 当前知识系统的几个专题真源

• 代码与模块真源：mcps/
• 技能真源：skills/
• 控制面真源：control-plane/
• 经验/记忆治理：experience-manager + qmd
• 可视化目录：self-debug-closed-loop

来源文件：09 - Atramenti-Console 当前上下文知识与排查入口.md

Atramenti-Console 当前上下文知识与排查入口

1. 我当前已经明确掌握的项目知识点

1.1 项目当前是“迁旧保新”的过渡架构

不是完全旧站，也不是完全新壳。

当前明确已经迁入新壳的 native route：

• /
• /system-overview
• /novel

其中 /novel 仍依赖 legacy 后端的 snapshot + SSE。

1.2 页面宿主与本地网关是两层

• server.mjs：独立 console 宿主
• gateway.mjs：本地插件网关

这两个不能混为一个进程概念。

1.3 独立宿主管理的插件清单不是散落配置，而是集中在 shared/plugin-manifest.js

atramenti.config.json 主要负责启用和模块配置，不是模块路径托管真源。

1.4 模块壳层导航正在转向 module.json 驱动

shared/nav-registry.js 会扫描 mcps/*/module.json 提取：

• top nav
• shell entry
• routePrefix
• apiPrefix
• icon/group/summary/homepage

1.5 技能真源和仓库已经统一

• skill 真源：E:\My Project\Atramenti-Console\codex\skills
• Codex 消费入口：C:\Users\ASUS-KL\.codex\skills

所以这套仓库本身已经是本地 agent 能力源之一。

1.6 控制面已经显式建模了三节点

• 上海主云端节点：控制台/控制面
• 杭州运行节点：worker/offload
• Windows 工作站：本地文件与桌面绑定执行

1.7 novel-manager 是当前最复杂的模块

它包含：

• dashboard snapshot + SSE
• 状态机
• 调度器
• 自动发布
• 平台确认
• 编辑工作台

后续只要涉及小说生产/发布/平台确认问题，都应该优先从它的调度与状态机链思考，不要当普通页面看。

1.8 self-debug-closed-loop 是能力目录而不只是页面

它不仅是页面，也是：

• skill/MCP 扫描器
• catalog snapshot 构建器
• agent/admin 管理入口

1.9 部署认知已经切到“源码根 -> 运行根”

不要把 /srv/atramenti-console 当真源；它只是 runtime root。

2. 遇到问题时的排查入口

2.1 页面不对/页面没进新壳

先查：

1. server.mjs
2. apps/console-web/lib/module-registry.ts
3. shared/plugin-manifest.js
4. shared/nav-registry.js
5. 对应模块的 module.json

2.2 独立运行配置不生效

先查：

1. atramenti.config.json
2. shared/standalone-config.js
3. server.mjs / gateway.mjs 的读取点

2.3 模块没出现在侧栏/首页

先查：

1. mcps/<module>/module.json
2. shared/nav-registry.js
3. apps/console-web/lib/module-registry.ts

2.4 云端部署后表现不一致

先查：

1. control-plane/registry/servers.json
2. control-plane/policy/deploy-targets.json
3. RUNTIME-TOPOLOGY.md
4. 实际运行根 vs 源码根是否混用

2.5 MCP 能力本地可用但云端不可用

先查：

1. mcps/<name>/server.mjs
2. C:\Users\ASUS-KL\.codex\config.toml
3. C:\Users\ASUS-KL\.codex\remote-mcp.ps1
4. /srv/mcp-runtime/apps/codex-portable-mcps
5. 121 节点 SSH 健康

2.6 技能改了但 agent 没拿到

先查：

1. E:\My Project\Atramenti-Console\codex\skills
2. C:\Users\ASUS-KL\.codex\skills
3. self-debug-closed-loop 的 catalog snapshot 是否已刷新

2.7 小说管理异常

优先顺序：

1. mcps/novel-manager/app/index.ts
2. mcps/novel-manager/backend/services/novel-service.ts
3. mcps/novel-manager/core/workflow/policy/*
4. mcps/novel-manager/core/workflow/state-machine/*
5. mcps/novel-manager/core/fanqie/publishing/*
6. mcps/novel-manager/frontend/pages/novel/index.html

3. 当前几个最值得记住的“别搞反”

• 不要把 shared/ 和 mcps/shared/ 混为一谈
• 不要把 server.mjs 和 gateway.mjs 当成同一层
• 不要把 atramenti.config.json 当成插件清单真源
• 不要把云端 runtime root 当源码真源
• 不要把 novel-manager 当简单前端页面模块

4. 后续建议补充的知识文档

后面如果继续扩这个知识库，建议再单独写：

• novel-manager 深入架构图
• deploy-center 云端部署链路图
• self-debug-closed-loop 目录快照与 agent 注入协议
• control-plane 的 execution-routing 解读
• apps/console-web 的组件迁移规则

来源文件：10 - Atramenti-Console Control Plane 说明.md

Atramenti-Console Control Plane 说明

编辑说明（2026-04-19）：本节保留原 Control Plane 说明结构，但其中“当前已登记服务器”等 live 结论已被后续 control-plane 真源扩展。现行服务器清单、deploy target 与 execution-routing 应以 control-plane/registry/servers.json、control-plane/policy/deploy-targets.json、control-plane/policy/execution-routing.json 以及 docs/agent/Server Operation & Maintenance Manual.md 为准。

1. 定位

control-plane/ 是项目级控制面，不是页面代码本体，也不是部署脚本目录。

它的职责是把这些信息统一建模：

• 服务器库存
• agent 库存
• 部署目标
• 执行路由
• promotion gate

2. 目录结构

• registry/servers.json
• registry/agents.json
• policy/deploy-targets.json
• policy/execution-routing.json
• policy/promotion-gates.json

3. 当前已登记服务器

当前 2026-04-19 的 repo 真源补充结论：

• 静态 registry 现在已覆盖 cloud-shanghai-01、cloud-hangzhou-01、cloud-beijing-lab-01、smoothcloud-wummlp-01、windows-workstation-01、cloud-session-host-01
• 当前 deploy-targets.json 只有一个正式 deploy target：console-dev -> cloud-shanghai-01
• 当前 execution-routing.json 的 dispatcher 在 124，default target 在 121，global fallback 只有 Windows；111 与 221 已登记为服务器资产，但尚未进入 execution-routing 规则

cloud-shanghai-01

• 主云端控制台节点
• 对外 UI/API 入口
• srcRoot：/home/ubuntu/atramenti-console-src
• runtimeRoot：/srv/atramenti-console
• backupRoot：/home/ubuntu/atramenti-console-backups
• 服务：atramenti-console.service

cloud-hangzhou-01

• 运行/worker 节点
• 目标：承担 MCP offload 与重型任务
• 当前状态（2026-04-19 复核）：root@121.196.202.114 可登录，ubuntu 认证失败；worker 服务名已写入 registry，但当前均 inactive

cloud-beijing-lab-01

• 轻量实验 / 跳板 / 备援节点
• SSH 别名：jd-lavm-beijing、jd-lavm-yp7m9xmd5l
• 当前已进入静态 registry，但尚未进入 execution-routing

smoothcloud-wummlp-01

• 弹性 GPU / burst 资产
• 当前已写入静态 registry：SSH 端口 10043、应用根目录 /root/workspace/ai-office、已知服务 office-web / ai-office-worker
• 当前仍依赖平台认证与网关路径，尚未进入 execution-routing

windows-workstation-01

• 本地工作站执行节点
• 负责本地文件、配置、浏览器、桌面绑定动作
• 这说明项目已经显式承认：不是所有任务都适合在云端执行
• 当前仍是 local-file / local-config / desktop-bound 的策略目标节点，但运行态 tunnel / bridge 目前是 degraded

cloud-session-host-01

• 当前会话承载宿主资产
• 已进入静态 registry，但为 disabled 的 session-host 条目
• 不参与当前 deploy target 或 execution-routing

4. 当前已登记 agent

codex-local-primary

本地 Codex 主消费端，消费这些共享能力源：

• skills
• mcps
• control-plane/registry
• self-debug-closed-loop

windows-local-executor

工作站执行器，消费：

• skills
• mcps
• control-plane/registry
• control-plane/policy
• self-debug-closed-loop

cloud-console-runtime

云端控制台运行时，消费：

• control-plane/registry
• control-plane/policy
• self-debug-closed-loop

cloud-runtime-worker

云端 worker，消费：

• control-plane/registry
• control-plane/policy

5. 它真正解决的问题

5.1 统一服务器库存

以后新增节点，不应该散落在脚本里，而应先进入 servers.json。

5.2 统一执行路由

不是所有事都发去云端；有些事情必须发去 Windows 工作站。

5.3 统一部署目标

应用目标应该绑定某个 server，而不是脚本里硬编码 host/path。

5.4 统一 promotion gate

让“什么情况下允许推进”不只靠口头约定。

6. 当前最重要的一条规则

控制面 README 里已经写死：

不要把 /srv/atramenti-console 当 source of truth。应该从 source root 构建，再发布到 runtime root。

这条规则是整个部署纪律的核心。

7. 和宿主层/模块层的关系

• server.mjs / gateway.mjs：负责运行与加载
• mcps/*：负责具体模块能力
• control-plane/*：负责“谁来跑、在哪跑、如何路由、如何提升”的编排规则

8. 实操上怎么用它

如果要接入新服务器或新 agent，推荐顺序：

1. 增加 registry/servers.json 记录
2. 增加/修改 registry/agents.json
3. 更新 policy/deploy-targets.json
4. 更新 policy/execution-routing.json
5. 必要时补 promotion-gates.json
6. 再让 deploy-center 或运行时读取这些新规则

9. 为什么这个目录对后续很重要

因为随着项目越来越像“多 agent + 多节点 + 多模块”的系统，没有控制面，所有执行目标都会重新散落回：

• 脚本常量
• 人脑记忆
• 临时 shell 命令
• 不可追踪的运维习惯

而 control-plane 的作用，就是把这些从“习惯”变成“显式结构”。