#dsh-console 本地接口后端（MoonBit）

• 只读（GET，纯只读）：runtime / profiles / logs / processes / instances / dsh-releases —— 形状与已退役的 Node 版中间件（../server/，见 git 0448ba4 可取回）逐字段一致，这一层一个字段都不动 （dsh-releases 是这一轮新加的：并发问 GitHub / npm / 国内镜像三个源，规格见 ../design/dsh-release-sources.md；三个源全没答上来也回 200，每个源各自的原因写在读数的 sources 里）
• 写（第三批新增）：POST /api/local/action（十个动作）、GET/PUT /api/local/settings、 GET /api/local/console（运行时登记与归档的只读出口） —— 契约见 ../design/write-api-contract.md

• 默认只监听 127.0.0.1:5390（自测隔离可用 DSH_CONSOLE_BACKEND_HOST / DSH_CONSOLE_BACKEND_PORT 覆盖）
• 一个进程一个端口：同一个端口既答 /api/local/*，也服务前端构建产物 dist/ （静态根可用 DSH_CONSOLE_DIST 指定）
• 只读接口只答 GET（其它方法 405）；写动作只走 POST /api/local/action，且必须带 X-DSH-Console: 1
• 前端走的是同源相对路径 /api/local/...，所以「接入」不需要改 base URL

#依赖

版本为什么不取最新：本机 ~/.moon 挂在只读文件系统上，moon update 无法刷新注册表索引， 索引停留在 2026-10-08，其中可见的最新版本是 moonback 0.8.6 / async 0.22.4（0.8.7 与 0.22.5 尚未进索引）。 只能在这两个版本上开发。要升级，需要一个可写的 MOON_HOME，见下面「构建」一节的说明。

#构建

./scripts/gen-build-info.sh          # 前端 build.sh 也会自己调一次

cd dsh-console/backend
moon check
moon build --target native

cd dsh-console/backend
MOON_HOME="$PWD/.sandbox/moonhome" moon check
MOON_HOME="$PWD/.sandbox/moonhome" moon build --target native

#运行

cd dsh-console/backend
./_build/native/debug/build/dsh-console-backend.exe
# 或者：moon run --target native .
# 自测换端口（不占用 5390）：
DSH_CONSOLE_BACKEND_PORT=5391 ./_build/native/debug/build/dsh-console-backend.exe
# 显式指定前端构建产物（默认从可执行文件位置上溯找 dist/）：
DSH_CONSOLE_DIST=/path/to/dsh-console/dist ./_build/native/debug/build/dsh-console-backend.exe

GET http://127.0.0.1:5390/                                   # dist/index.html
GET http://127.0.0.1:5390/assets/index-xxxxxxxx.js           # 构建产物，MIME 按后缀
GET http://127.0.0.1:5390/api/local/runtime
GET http://127.0.0.1:5390/api/local/profiles
GET http://127.0.0.1:5390/api/local/logs?source=host&tail=200
GET http://127.0.0.1:5390/api/local/processes
GET http://127.0.0.1:5390/api/local/instances
GET http://127.0.0.1:5390/api/local/settings
GET http://127.0.0.1:5390/api/local/console

curl -X POST http://127.0.0.1:5390/api/local/action \
  -H 'Content-Type: application/json' -H 'X-DSH-Console: 1' \
  -d '{"action":"start-instance","params":{"profile":"web"}}'

curl -X PUT http://127.0.0.1:5390/api/local/settings \
  -H 'Content-Type: application/json' -H 'X-DSH-Console: 1' \
  -d '{"values":{"instance.basePort":8500,"logs.defaultTail":50}}'

#静态服务：一个进程一个端口接管前端

1. DSH_CONSOLE_DIST：显式指定的目录必须含 index.html 与静态资源（assets/ 目录，或同层有 .js / .css 文件）； 设了但目录不对就直接算失败，不偷偷回退到第 2 步，原因写进启动日志与响应体（显式指的路径是错的，就该看得见）
2. 否则从 /proc/self/exe 的真实路径往上找（最多 8 层）：先看 <层>/dist，再看这一层本身， 命中条件同上（index.html 加静态资源）。每一层的候选顺序：<层>/frontend/dist → <层>/dist → 这一层本身——新栈优先，旧产物没删之前不会一直供着过期页面。不硬编码任何绝对路径，覆盖 backend/_build/native/<profile>/build/<exe> 与二进制被放进 dist/ 两种部署方式

#已实现的接口

#GET /api/local/runtime

• installed_dsh_candidates() —— 这台机器上装了哪几份：shim 解开的那份 + 各全局根下扫到的全部， 按真实路径去重。同一个真目录在 pnpm 的布局里有两种写法（<槽>/<哈希>/node_modules/@deepseek-ai/dsh 是软链，真身在 <槽>/<哈希>/node_modules/.pnpm/@deepseek-ai+dsh@<版本>_<哈希>/…）， 字符串比会把同一份数成两份，所以按 realpath 判。 老布局（global/5/node_modules/.pnpm/…）不靠走 .pnpm 覆盖：pnpm 会在 <槽>/node_modules/@deepseek-ai/dsh 摆软链过去，读 package.json 顺着软链就读到了。 不按条目名去 .pnpm 里扫 dsh：那里还有别的全局包顺便装进来的依赖副本（本机就有一份 0.2.1-rc.2 只存在于某个槽的 .pnpm 里，pnpm 从没把它摆在 node_modules/@deepseek-ai 下）—— 那种副本算不算「装了一份」可疑，而且版本更高时会被自动挑挑中，等于拿用户没装过的版本起实例。
• resolve_dsh_selection() —— 生效的是哪一份：有指定（dsh-pin.json）且那一份还在就用它， 否则走原来的自动挑（与在跑实例同一份 → 同版本里最高 → 最高）。 指定的目录没了 / package.json 版本与记录对不上 → 回落自动挑并如实标 pin-missing， dshPinNote 里写清「你指定过哪一版、现在按哪一版」，不报错、也不偷偷改记录。

1. 删掉 nodeVersion。后端不跑 Node，硬编码 "v26.11.1" 就是编数据。 现在如实报告后端自己：backendRuntime = moonbit/native、backendVersion、backendPackageName。
2. consoleVersion 不再是编译期常量，且不再绑定前端的实现方式：
   • 优先：从 /proc/self/exe 的真实路径往上找含 VERSION 的目录（产品根），读那个文件的版本；
   • 兜底（换栈过渡期）：没有 VERSION 时，按 DSH_CONSOLE_DIR / DSH_CONSOLE_ROOT / DSH_CONSOLE_HOME 环境变量，或上溯找同时含 package.json 与 src/ 的目录，读它 package.json 的 version；
   • 任何一步失败都给 null，并把用的是哪条路写进 consoleVersionSource，不编。

   为什么加 VERSION：后端原先靠前端 package.json 读版本，而前端已经换栈成 MoonBit （不再是 Vue 那套 package.json + src/）。绑定前端实现方式的话，删掉旧前端那一刻 这个读数就会静默失效、关于页变成「未知」。

#GET /api/local/profiles

• bundles.declared：package.json 里 dsh.profile.bundles 的长度
• installed / installedInProfile / installedHoisted：按 bundle 是否落在 profile 自己的 node_modules、还是 profiles/node_modules（提升）统计
• missing：两处都没有的 bundle 名
• patch.lines：cordis.patch.yml 去掉末尾单个换行后的行数；文件不存在时 {exists:false, lines:0}
• lock：pnpm-lock.yaml 的存在性与 mtime（ISO8601，毫秒 3 位）；不存在给 {exists:false, mtime:null}
• note / noteSource（第二轮新增的加字段，旧消费者忽略即可）：备注正文与来源。 备注放在 <profile 目录>/.dsh-note.txt，读到给原文 + "文件"；没有这个文件给 "" + "默认"； 有文件读不动给 "" + "默认（<路径> 读取失败：…）"（与设置的 sources 同一套口径，读不到就说读不到）
• lastStart / lastStartSource（第十六轮新增的加字段，旧消费者忽略即可）： 这只 profile 最近一次启动的结局，读自审计流水 audit.jsonl 里最近一条启动记录 （action 为 start-instance 或 restart-instance，后者见 design-fixes §27.1）， 形状是 { action, ok, at, code, message, home }。 ok:false 表示最近一次是失败的：它就是「失败之后没有成功过」的判据 （真有过一次成功，那一次就是最近那一条）。一条记录都没有时给 null + 一句来源说明； lastStartSource 写明取的是哪一条（含 action 名）、按什么对上的（params.home 等于 这只 profile 的 home / 控制台的 home / 那一笔没带 home 时按 profile 名）。 「最近」的判据是这些行里 at 最大的那一条，不按 home 槽先筛一遍： 同一只 profile 的记录会落在「带 home」与「不带 home」两个槽里。 归属在 profiles/profiles.mbt 的 last_start_of：别的 home 里的同名记录不算这一只的。 restart-instance 的审计行由 actions/action.mbt 的 audit_params_for 补上 params.profile / params.home（请求体里只有 pid 或 port），失败那一笔才认得出是谁。
• dirMtimeMs / dirMtimeSource（第五轮新增的加字段，旧消费者忽略即可）：profile 目录的 mtime （Unix 毫秒，数字；读不到给 null + 原因）。卡片第六格「最近改动」与列表排序都用它。 口径是「最近改动」，不是「创建时间」：多数文件系统上可靠的创建时间拿不到 （ctime 会在 chmod / 改名时变，birth time 不通用），目录 mtime 是能拿到且不会骗人的那个值； 派生会写进新目录，所以刚派生出来的 profile 一定是 mtime 最新、排在最前面的那一个。 这一层不动 profiles 数组的顺序：数组仍按 profile 名升序，降序排序是消费者按 dirMtimeMs 做的事

#GET /api/local/logs?source=...&tail=...

• host：ISO 时间 + [插件@版本] + 正文 拆出 time（只留时间部分）与 text；拆不出的整行原样保留
• audit：JSONL 压成一行文本（tool · verdict/outcome · [reviewMode] · 命令短片段）， 命令超 72 字符截断；不倒原始 JSON
• 级别判定按非字母数字切词后比对（error/failed/failure/exception 归 error； warn/warning 归 warn）。不用词边界：下划线算词字符， code=PI_AI_ERROR 这种真实错误行会整片漏标
• 单行正文超 400 字符只做展示裁剪并加省略号

1. 候选 = 该实例 DSH_HOME 的 logs/ 目录下（含至多 3 层子目录）.log / .jsonl / .txt 普通文件
2. 排序层级（数字小的在前）：

   层级	是什么
   0	这条实例自己的日志，且有内容
   1	host.log，且有内容
   2	别的文件，且有内容
   3	这条实例自己的日志，但空
   4	host.log，但空
   5	别的文件，且空

3. 同层级按 mtime 降序，mtime 相同按路径升序（结果稳定可复现）
4. 「这条实例自己的日志」= 运行登记里这条实例的 logPath；登记里没有就按控制台的命名约定 console-<profile>-<port>.log 拼一个。两个都拿不到（外部起的实例）就没有这一档

#GET /api/local/processes

• 匹配：可执行名精确为 dsh（.js / .mjs / .cjs）或路径段含 @deepseek-ai/dsh/
• --port 不再是必需条件：有就读出来，没有记 null，不因此丢掉进程
• profile 取 --profile / --profile=x；dshHome 取 /proc/<pid>/environ 的 DSH_HOME
• startedAt 由 /proc/<pid>/stat 第 22 字段（starttime）+ /proc/uptime 换算
• 读不到的字段一律 null，不编

#GET /api/local/instances

• 读 /proc/net/tcp 与 /proc/net/tcp6，筛 st=0A（LISTEN）且本地地址是 loopback （127.0.0.1 / ::1 / ::ffff:127.0.0.1，/proc/net 里按小端十六进制写）的端口
• 去重、升序、候选上限取设置 probe.maxCandidates（缺省 40）（超了截断并在响应里说明）
• 对每个候选端口发一次 GET http://127.0.0.1:<端口>/：超时取设置 probe.timeoutMs（缺省 500ms）、不跟随重定向、 只读前 8KB 响应体
• 并发取设置 probe.concurrency（缺省 8，与 Node 版 PROBE_CONCURRENCY 同数），响应里回的就是生效值： 结果顺序仍按端口升序——@async.all 按下标收集，谁先回来不影响排序。 真实并发 = min(8, 候选数)。40 个黑洞端口实测：串行 17.1s → 8 路 2.52s
• 两条签名判据（命中的 id 回显在响应里）：
  • dsh-auth-401：HTTP 401 且体含 dsh web authentication required
  • dsh-boot-global：体含 __DSH_BOOT__
  • 绝不用「含 DSH 字样」当判据：本控制台自己的页面标题就带 DSH，那样会把自己列成实例
• 响应带元信息：candidates / candidateCount / candidateLimit / truncated / truncatedNote / probe（method、redirect、timeoutMs、concurrency、probed、reached、hits）/ perFile / signatures / processSupplement

1. /proc/net/tcp(6) 那行的第 9 列 socket inode（解析端口时一并带回，见 ListenSocket）
2. 扫 /proc/<pid>/fd/* 的链接目标，找 socket:[<inode>] → 得到 PID （全工程唯一一处 C 代码 json/fd_link.c：一次 readlink(2)，MoonBit 的 fs 层有 realpath、没有它）
3. /proc/<pid>/cmdline 读 --profile；/proc/<pid>/environ 读 DSH_HOME， 没有就看 fd 表里 …/.dsh/… 路径的前缀，都没有才落默认 $HOME/.dsh（来源写进 dshHomeSource）
4. 入口路径里 node_modules/@deepseek-ai/dsh 这一段的 package.json → version（软链入口先 realpath）
5. /proc/<pid>/stat 第 22 字段 + /proc/uptime → startedAt / uptimeSeconds

1. 探测仍按端口做，probeResults 一个都不少（那是全局事实，不是实例行）；
2. 成行前按 pid 归并：主端口 = 该 pid 名下签名命中 dsh 判据的那个；一个都没命中时取端口号最小的；
3. 同 pid 的其余端口收进该行的 alsoPorts：[{ port, httpStatus, signatureId, note }] （note 是一句人话，例如「同一个进程的另一个监听端口，不是 dsh 的网页入口：这一次探测回的是 HTTP 404」）；
4. state / stateReason 只按主端口算；
5. 没有 pid 的条目（进程 join 不上）不参与归并：那时「这两个端口是不是同一只进程」没有证据， 硬凑成一行就是把猜的当事实。按端口点停止 / 重启的老路径仍然认 alsoPorts 里的端口。

1. runtime.json 里这条实例登记的 logPath（先按 pid 对，再按端口对；不按 profile 找， 同名 profile 的历史登记可能指着一份别的日志）
2. 按控制台命名约定拼出来的实例日志 console-<profile>-<port>.log（先该实例自己的 DSH_HOME， 再 dsh 默认的 ~/.dsh）
3. dsh 日志目录下的有界扫描：最近改动的 20 份 .log，每份只读尾部 200 行，找提到 :<端口>/?token= 的行

• 端口必须与该实例一致：匹配串就是 :<该实例的端口>/?token=，所以不会把别的实例的令牌 贴上来；host 取该实例自己的 url（http://127.0.0.1:<端口>/）
• 令牌原值不进审计：audit.jsonl 里只有动作与 profile（实测 grep 令牌 → 0 命中）， webUrlSource 里也只写文件与段落，不带令牌
• 每次现算、不缓存：token 每次启动都会变，同一个 instances 请求里现读现拼； 同一个日志文件里有多条横幅时取最后那条（追加写，越靠后越是当前这次启动的）
• 读不到就说读不到：外部实例（手动起的，例如 3080）没有这份日志，令牌打在启动它的终端里 —— 回 null + 「外部实例：令牌在启动它的终端里……」，不给一个点了 401 的链接
• 有界读，够不着也不猜：自己那份日志先读尾部 256KB；没命中且窗口没盖到文件开头时补读开头 64KB，只有「开头 + 尾部」能盖住整份文件才采信开头那一段 —— 中间有缺口时开头那个令牌可能 已经被后一次启动换掉了，宁可回 null 并写明「中间 N 字节没读」
• 第 3 步扫来的令牌先实测一次握手：跨文件扫到的横幅可能是同一个端口更早那次运行的，早被换掉了。 采信之前对 127.0.0.1:<端口> 发一次 GET /?token=<串>（2s 超时，只看状态码）：401、探测不到、 超时都不采用，回 null 并写明「实测握手仍是 401，不采用」；不是 401 才采用，webUrlSource 里 带上实测到的状态码。第 1、2 步读的是该实例自己那份追加写的日志、取的是最后一条横幅，不做这一步
• 这一层仍然是纯只读：只做 file_size / read_at / readdir / mtime 与注册表读取， 不写盘、不建进程

• archive-profile 的「正在跑的不许归档」把 fault 条目也算在跑（它确实占着那个端口）； 判据与起实例同一条：(home, 名字) —— 别的 home 里同名的那只是另一只，不挡这一份 （改前只比名字：W1 归档被 W2 在 $W2_PORT 上跑的同名实例挡回，实测过）
• stop-instance / restart-instance 按 port 找目标时，fault 条目也能找到 pid（改前是 not-found）
• probe.hits 仍是签名命中数：fault 条目不计入，条目总数看 instances 长度

#响应外壳与状态码

{"ok":true,"readOnly":true,"readAt":"2026-10-14T10:56:27.361Z","data":{}}

{"ok":false,"readOnly":true,"error":{"code":"...","message":"..."}}

{"ok":true,"readOnly":false,"readAt":"2026-10-15T07:17:44.588Z","data":{"action":"start-instance","outcome":{}}}
{"ok":false,"readOnly":false,"readAt":"…","error":{"code":"conflict","message":"profile web-dev 已经在跑（PID 278412，端口 8400）…"}}

#可写层（第四批，本轮）

#写动作只有一个入口

POST /api/local/action
Headers（必须）: X-DSH-Console: 1 ；Origin 只能缺省或本机回环（http://127.0.0.1 / http://localhost / http://[::1]）
Body: { "action": "<动作名>", "params": { ... } }   delete-profile 硬删时另带 "confirm":"DELETE"

busy / install-failed / install-incomplete 是补包那一轮（第九轮）加的三个码： 同一只 profile 已经有一个补包在跑（busy，409）、包管理器退出码非 0 或超时（install-failed）、 装完了按 dsh.profile.bundles 重算仍缺（install-incomplete）。后两条的 message 都带日志路径。

后来又拆/加了三个（都在补包这一族，message 都带日志路径或直接说清原因）：

• packages-not-found（500）：跑完仍缺包，且 install 日志里有 registry 说「没这个包」的证据 （ERR_PNPM_FETCH_404 / 404 Not Found / E404）。message 列出缺的包名并说「得改 package.json」—— 这一档重试多少次都没用，下一步是改声明，不是再点一次。
• no-package-manager（500）：开跑之前就拦下——这只 profile 选中的包管理器不在 PATH 上。 不拦的话要等满 120 秒超时，而等下去也不会有转机。
• unsupported-manager（500）：这只 profile 是 Yarn PnP（目录里有 .pnp.cjs），包不在 node_modules 里， 控制台不代跑，说明里让用它自己的 yarn。

补包用哪个包管理器：先认 package.json 的 packageManager 字段（pnpm@9.1.0 → pnpm）， 再按 lock 文件（pnpm-lock.yaml → pnpm、package-lock.json → npm），都没有按 pnpm。

dsh-not-installed 是版本切换那一轮加的第八个码（原契约七码之外）。为什么单开一条： 那是调用方点了一个不是安装的目录，不是读写失败 —— message 里把「这台机器上装着哪几份」都列出来了， 归进 io-error 会把人引去查磁盘。

#十四个动作

#搬家之后重算软链接（relink，第九轮 §48）

• 相对链接：用「旧链接所在目录 + 链接文本」算出它原本指向的绝对目标，再用「新链接所在目录」重算相对 路径写回；
• 绝对链接原样保留（它们不随目录变）；
• 目标不存在就跳过并记一条（原本就坏的不修、也不弄得更坏）；
• .pnpm 整棵不进去（pnpm 自己的链接农场，装一次会重建），遍历有条数上限；
• fork 的复制本身不拷软链（copy_tree 只复制普通文件与目录），所以它那一步是「按源目录解析出的绝对 目标，在副本里重新摆一条」；回执的 skipped 里不再出现已经带过来的那些。

#派生出的新 profile 怎么认得出（第五轮）

1. 列表排序口径 = 最近改动。profiles 数组本身仍按名字升序（只读层的形状不动）， 已停止那一组由消费者按 dirMtimeMs 降序排，读不到的排最后、按名字升序兜底。 用"最近改动"而不是"创建时间"：可靠的创建时间在多数文件系统上拿不到（ctime 会因 chmod / 改名而变， birth time 不通用）；而派生一定会写这个目录，所以刚派生出来的一定是 mtime 最新的那个。
2. 备注就是它的出生证明。派生时往 <新 profile 目录>/.dsh-note.txt 写：

   从 <源 profile> 派生 · <本地时间>
   <源 profile 原有的备注，原样接在后面>

   为什么覆盖源备注而不是留着不管：派生是整目录拷贝，源 profile 的备注会跟着拷过来， 而那条备注讲的是源的事（"这个是干啥用的"），留在新 profile 里会误导 —— 所以第一行必须是它的来历， 源的那段原文退居第二行起、继续留着供参考。总长按备注上限 2000 字符截断 （第一行短，真正被截掉的只会是尾部）。 备注写失败不算派生失败：目录已经拷好了，为一个备注把整次派生报成失败是假报 —— outcome 里 noteFile.written=false + noteFile.error 写清原因，顶层 note 也照实说。
3. 提示要说清结果落在哪：outcome 里有 newName / noteFile{path,text,written,error} / dirMtimeMs / listPosition，顶层 note 一句话讲完"新 profile 叫什么、它在列表最上面、 备注里写着从哪来、拷了多少文件"。使用者问的"那我点这个按钮呢是否有效"就靠这一句回答。

1. 端口 ≠ 可服务。服务先 bind、路由后挂载，中间那几百毫秒 GET / 回的是 404。 只等端口会让只读的 instances 接口在这一刻认不出刚起的实例。所以等的是 dsh web 签名（401 + dsh web authentication required，或页里有 __DSH_BOOT__）。
2. 僵尸进程的 kill(pid,0) 也成功。判活不能只看 kill(pid,0)，还要看 /proc/<pid>/stat 的状态位， Z 按死处理；否则停止动作会一直报「SIGKILL 之后仍然在」。
3. 判死之后还得 wait 一次。Z 被判成死，但「死了又没被 wait」的子进程仍然挂在控制台名下 （ps -o pid,stat,cmd --ppid <控制台pid> 里一堆 Z），控制台退出才被回收 —— 长跑的控制台每失败一次攒一个。 收尾的 reap_after_failure 因此在每条「子进程已经不在」的分支上都补了一次 wait_pid （只对已经死掉的 pid 调，不会阻塞；不是自己的子进程时报 ECHILD，吞掉）。

#端口占用的裁判是 bind，不是 /proc/net/tcp

• 找空闲口（从 instance.basePort 往后扫）只认 LISTEN：/proc/net/tcp(6) 状态列等于 0A 的才算 「有人在听」。TIME-WAIT(06)、FIN-WAIT、CLOSE-WAIT、CLOSE 都是连接关掉之后的残留， 那段时间端口上没有任何东西在听，监听侧带 SO_REUSEADDR（node 的 server.listen 默认带） 就 bind 得上 —— 把它们算成「被占用」，等于白扔掉空着的口。
• 显式指定的端口（起实例带 port、重启沿用老端口）在这里不预判：/proc 那张表判不出 「有没有人在听」（见上一条），预判只会猜错。真正的裁判是这一次 bind：起不来就报 进程写下的原话，形如 Error: listen EADDRINUSE: address already in use 127.0.0.1:8400 （errno 名与端口都在里面），不再由控制台替内核编一句「/proc/net/tcp 里有这条记录」。

#哪些 profile 能起成常驻实例

• 命中「参数被拒」：给一句人话 + 证据 + pid / 日志路径 + 后续建议， 不把日志尾巴当正文丢出去：

  {"ok":false,"readOnly":false,"readAt":"2026-10-15T07:40:00.000Z","error":{
    "code":"spawn-failed",
    "message":"profile headless 的 app 不接受服务参数（--no-open），它不是服务型 profile，起不成常驻实例。子进程已经退出（pid 4321，日志 /home/u/.dsh/logs/console-headless-8400.log）。日志里写着：error: unknown option '--no-open'。要跑这种 profile，按它自己的用法跑一次（dsh --profile headless …），别拿它起常驻实例"}}

• 命中「这次 bind 没成」（日志里有 EADDRINUSE / EADDRNOTAVAIL 这类 errno 名， 或 address already in use 这种原话；EACCES 只在跟 listen / bind 挨着时才算 —— 单独一句 permission denied 可能来自文件操作，不往 bind 上归因）：错误码仍是契约里的 conflict（409），message 把原话贴出来，并说清它来自这次 bind、不是我们按 /proc/net/tcp 猜的：

  {"ok":false,"readOnly":false,"readAt":"2026-10-16T12:16:00.000Z","error":{
    "code":"conflict",
    "message":"端口 8450 起不来：这次 bind 没成，进程写下的原话是「Error: listen EADDRINUSE: address already in use 127.0.0.1:8450」。这句话来自这次 bind（errno 与端口都在里面），不是我们按 /proc/net/tcp 猜的。换一个端口，或先腾出这个端口（profile iso，pid 21034，日志 …/logs/console-iso-8450.log，子进程已经退出）"}}

• 没命中（启动就崩、bundle 解析不了、profile 自身有毛病等）：维持原来的形状 —— 实例没起来（pid …，日志 …）：<收尾说明>；日志尾部：…，尾部的口径同样是本次启动新写出来的那几行。 那时日志尾巴就是最好的证据，如实贴出来比套一句结论有用。 实测负例（bundles 里挂一个不存在的包）：message 如实给出 dsh: cannot resolve profile bundle …，没有被误判成「服务参数被拒」。

#open-path：只认枚举目标，不接受路径

{"action":"open-path","params":{"profile":"web","kind":"dir"}}

• kind 缺省 "dir"：目标是 <profilesRoot>/<名>；"config" 则是它下面的 cordis.patch.yml。 别的取值 bad-params。
• params 里出现 profile / kind 之外的键一律 bad-params。这是有意的：塞一个 path 进来会被拒， 而不是被默默忽略——忽略掉的话，「塞了 path 也成功」看起来就像那条路径生效了。
• 白名单 + 落点两道校验与 set-profile-note 同款：名字只允许字母数字与 ._-、不以点开头、不是 . / ..， 拼出来的路径还得确认带 profilesRoot/ 前缀。
• 交给桌面的方式是 xdg-open 直接 exec：目标路径是 argv 里的一项，没有 shell、没有任何字符串插值， 带空格 / 引号 / $ 的路径也只是这一项的字面量。spawn 之后不等它干活。

#process.detach 的两种语义

• true：spawn_orphan，完全脱离控制台。控制台正常退出、被 SIGTERM、被 SIGKILL，它都活着 （实测：控制台 SIGKILL 之后实例仍在听端口，GET / 仍回 401）。
• false：实例挂在控制台主任务组上（@process.spawn(group, …, no_wait=true)， cancel_handler = graceful_cancel(timeout=stopGraceMs)）。控制台退出时由运行时的结构化并发收掉它 （实测：控制台 SIGTERM 之后实例消失）。

为什么不是「app.serve 之后写收尾代码」：moonbitlang/async 在全局取消信号之后会把信号重新抬起来交给 默认处理，实测控制台退出码 143，serve 之后的语句一句都跑不到。因此 detach=false 只能挂在任务组上。

#设置（每一项都接到真实行为上）

#运行时登记、归档与审计

#audit.jsonl 怎么滚动（阈值与保留条数写死在这里）

1. 把「说明条 + 保留的最近 2000 条」写成归档文件 .archive/audit-<UTC 时间戳>.jsonl，写完关句柄；同名不覆盖，撞名顺延 -1、-2……
2. rename 主文件到同一个归档名：这一步之后完整旧流水在归档里，可读
3. 再把同样的内容写成主文件（临时文件 + rename 就位）

• 原子：三步都是「同目录临时文件 + rename」，没有半截文件；模型上唯一可见的中间态是「主文件短暂不存在」（第 2 与第 3 步之间），读侧 audit_read_path 遇到就回退读最近的归档 —— 滚动不会让审计突然读不到
• 并发：整个过程持进程内互斥锁 audit_write_lock。不加锁时一笔滚动的两次 rename 会把另一笔刚追加的行落到被搬走的旧 inode 上（实测阈值 1 字节 + 100 条并发会丢行）。跨进程（同时跑两个后端）不在射程内，也不在契约里
• 失败不连坐：滚动失败只把原因回给调用方拼进响应 note，不让动作失败（store/audit.mbt 全链 noraise）
• 令牌原值仍然不进审计（下面「令牌原值不进审计」那条不因滚动而放松）
• 自测/运维可以临时改这三个数：DSH_CONSOLE_AUDIT_MAX_BYTES / DSH_CONSOLE_AUDIT_RETAIN_LINES / DSH_CONSOLE_AUDIT_ARCHIVE_KEEP（非法值一律按上面的缺省）

#前端怎么拿到登记与归档

GET /api/local/console → { ok, readOnly:true, readAt, data:{
  stateDir, settingsPath, runtimePath, archivePath, auditPath, orderPath, trashDir,
  deleteToTrash, deleteToTrashSource,
  runtime:[{ pid, port, home, profile, startedAt, logPath, detached, alive }],
  archive:[{ profile, archivedAt }],
  order:["port:3080", "profile:web", ...],
  lastStarted:[{ id, at, source }],
  notes:[] } }

#读写分层与写盘边界

#只读层（一个字段都没动）

• 全部读访问集中在 json/fsio.mbt、json/env.mbt、json/tailread.mbt、json/version.mbt： @fs.read_file、@fs.exists、@fs.kind、@fs.readdir、@fs.mtime、@fs.realpath、 @fs.open(ReadOnly) + File::read_at、@fs.file_size（只 stat 大小），以及 read_link （readlink(2)，只读链接目标）与 list_dir_result。json/ 里没有任何写 / 建 / 删 / 改名 / 建进程调用（自测 grep 0 命中， 见下面「自测怎么核对」）
• 凭据类文件（.credentials.yaml / .env / .npmrc）在 read_text_file / read_some_at 里按 basename 硬拦： 只判断存在，绝不读内容
• 环境变量来自 /proc/self/environ，是本进程自己的环境
• 静态服务（dist_static/）只调 @json.exists / @json.is_dir / @json.exe_path / @json.env_value， 真正读文件的是 moonback unstable_static 的 @fs.kind 与 @fs.open(ReadOnly)
• 只读接口里的唯一网络动作是对 127.0.0.1 候选端口发一次 GET（写死回环地址、写死 GET、读完即断）

#写层：写盘只落在这些路径

#FFI

• json/fd_link.c：readlink(2)（只读，端口 → inode → PID 那条 join 用）
• json/local_time.c：localtime_r(3) 两次（一次取本地 UTC 偏移、一次取时区缩写）。派生备注第一行要写 "本地时间"，而核心库与本工程的依赖里没有时区换算，UTC 顶替会写出一个与使用者那块表对不上的时间。 只读时间，不写盘、不建进程、不碰文件；取不到返回哨兵值，MoonBit 侧按"读不到"处理（写明原因，不拿 UTC 冒充）
• fsx/proc_signal.c：kill(2) / kill(pid,0) / getpid(2)。停止实例要「先 SIGTERM、宽限后 SIGKILL」， 判活要 kill(pid,0)，而 @process 只能操作自己 spawn 出来的句柄，对任意 PID 没有原语， 本工程也不想为此去 spawn /bin/kill。三个函数都不写盘、不建进程、不读文件。
• 本地时间只走上面 json/local_time.c 那一次 localtime_r，没有为它去 spawn date。

#自测怎么核对

cd dsh-console/backend
# 写调用点与建进程处只在三个文件里：fsx/writeio.mbt、actions/instance.mbt、actions/open_path.mbt
grep -rn '@fs\.write_file\|@fs\.mkdir\|@fs\.rename\|@fs\.remove\|@fs\.rmdir\|@process\.spawn\|spawn_orphan' --include=*.mbt . | grep -v .mooncakes | grep -v _build
# 只读层干净（无输出）
grep -rn 'write_file\|mkdir\|rename\|remove\|rmdir\|spawn' json/*.mbt json/*.c

#已知差异（与 Node 版）

1. 探测走 socket 直连，不走 @http 客户端。 实测：moonbitlang/async/http 的 @http.Client(uri, headers~) 在服务进程里 （moonback handler 的协程上下文）构造就抛 ResolveHostnameError("Name or service not known")； 同一条调用在 handler 里内联执行是成功的，在独立程序里也是成功的，原因未定位。 因此探测改用已验证可用的 Tcp::connect(Addr::parse("127.0.0.1:<端口>")) 加一个极简 HTTP/1.1 客户端（localapi/rawhttp.mbt：支持 Content-Length 定长 / chunked 分块 / 读到 EOF）。 对外行为不变：GET、500ms 超时、不跟随重定向、只读前 8KB。
2. 探测并发已与 Node 对齐：两边都是 8 路，probe.concurrency 如实回 8， 候选上限 40、单个 500ms 的口径没动。40 个「接受连接但不回 HTTP」的黑洞端口实测： 串行（改前）17.1s，8 路（改后）2.52s。
3. processSupplement.scanned / processes.scanned 可能比 Node 小：两边都读同一个 /proc， 但本后端的沙箱有 PID 命名空间隔离（/proc 里只能看到自己那几个进程），Node 版跑在宿主命名空间里。 口径相同，差异来自运行环境。
4. probeMs 是每次实测的毫秒数，天然会波动。
5. platform 里的架构与内核版本：Node 用 os.arch() / os.release()； MoonBit 标准库只给 OS 族（moonbitlang/async 的 Platform），架构是编译期常量 x64， 内核版本读 /proc/sys/kernel/osrelease。本机实测值与 Node 完全一致。
6. readAt 时间戳格式与 Node 的 toISOString() 一致（UTC、毫秒 3 位、Z 结尾）， 只有时钟读数本身的差异。
7. 响应头字段名是小写：线上发出的是 x-local-api: read-only / cache-control: no-store， Node 版是 X-Local-Api / Cache-Control。这是 moonback 的行为，不是本工程的选择： moonback.MutHeaders::set 存的名字大小写会保留，但 Headers::iter（真正写线的那一步）在小写化， 用一页临时程序实测确认过（set("X-Local-Api", ...) 迭代出来是 x-local-api），当前没有任何 API 能绕开。 HTTP 字段名按 RFC 9110 大小写不敏感，任何标准客户端（含 curl、fetch）取值都一致。

#接入前端时要注意的一件事（「关于」页）

• 语义变了：Node 版那一行说的是跑服务的 Node 运行时；这个后端不跑 Node， 同一行的正确含义是后端自己的运行时与版本。
• 建议把这一行拆成/改成：
  • 「后端运行时」→ backendRuntime + backendVersion（例如 moonbit/native 0.1.0）；
  • 想保留「Node 版本」这一行，就必须从别处取（前端自己拿不到宿主 Node 版本）， 最省事的做法是直接删掉这一行，或改成显示 dshVersion / consoleVersion。
• consoleVersion 现在可能是 null（读不到前端 package.json 时），展示上要能兜住； consoleVersionSource 写明了来源或失败原因，调试时可以直接显示。

#目录结构

backend/
├── moon.mod                    # 模块定义、依赖、native 目标
├── moon.pkg.json               # 主包（可执行入口）
├── main.mbt                    # 起服务、中间件顺序（API 闸门 → 静态 → 路由）、监听地址解析
├── json/                       # 共用基础层（本工程唯一的只读文件 IO 入口）
│   ├── encode.mbt              # 有序 JSON 编码 + ISO8601 格式化 + ISO 时间取时分秒
│   ├── text.mbt                # 字符串/字节工具、级别切词、错误类型
│   ├── fsio.mbt                # 只读文件访问入口（含定向读 read_some_at、read_link）
│   ├── fd_link.c               # 唯一一处 C：readlink(2) 的 FFI 桥（一次系统调用）
│   ├── tailread.mbt            # 反向分块读文件尾部
│   ├── version.mbt             # 后端自身版本 + 前端 package.json 的运行时读取
│   ├── env.mbt                 # /proc/self/environ、HOME 解析
│   └── value.mbt               # core Json 的只读取值
├── localapi/
│   ├── api.mbt                 # 路由分发、查询参数、错误码、方法名、API 优先闸门
│   ├── respond.mbt             # 响应外壳与响应头
│   ├── probe.mbt               # 单端口只读探测 + 批量并发探测（保序；超时与并发由设置给）
│   └── rawhttp.mbt             # 极简 HTTP/1.1 客户端（回环探测专用）
├── fsx/                        # 写侧基础层（全工程唯一的写入口）
│   ├── writeio.mbt             # 原子写 / 追加 / 建目录 / 改名 / 删树 / 复制树 / 发信号
│   └── proc_signal.c           # 唯一另一处 C：kill(2) / kill(pid,0) / getpid(2)
├── store/                      # 状态文件（$XDG_STATE_HOME/dsh-console）
│   ├── state.mbt               # 状态目录与 JSON 文件读取（坏文件给原因）
│   ├── settings.mbt            # 十项设置的键、缺省、取值范围、原子落盘
│   ├── registry.mbt            # runtime.json：控制台起过的实例
│   ├── archive.mbt             # archive.json：归档记录（(home, 名字) 为身份）
│   ├── trash_origins.mbt       # trash-origins.json：回收站条目各自从哪个 home 删的
│   ├── order.mbt               # order.json：手动顺序（行 id 带 home）
│   ├── dshpin.mbt              # dsh-pin.json：用哪一版 dsh 起实例的指定记录
│   ├── laststarted.mbt         # 「上次启动」表（行 id 同一套）
│   └── audit.mbt               # audit.jsonl：动作审计（超阈值滚动 + 归档 + 读侧回退）
├── actions/                    # 可写层（唯一入口 POST /api/local/action）
│   ├── guard.mbt               # X-DSH-Console + Origin 守卫
│   ├── respond.mbt             # 写侧响应外壳与错误码 → 状态码
│   ├── action.mbt              # 动作分发、参数解析、审计、GET /api/local/console
│   ├── instance.mbt            # 起 / 停 / 重启、端口分配、签名等就绪、进程判活
│   ├── dsh_version.mbt         # pin-dsh / unpin-dsh：指定用哪一版 dsh 起实例
│   ├── profile_fs.mbt          # 派生 / 重命名 / 删除（回收站或硬删）
│   ├── settings_api.mbt        # GET / PUT /api/local/settings
│   └── console_api.mbt         # GET /api/local/console
├── dist_static/
│   └── dist_static.mbt         # 静态根解析、dist 静态中间件、SPA 回退、解析失败时的 503
├── runtime/runtime.mbt         # GET /api/local/runtime
├── profiles/profiles.mbt       # GET /api/local/profiles
├── logs/logs.mbt               # GET /api/local/logs
├── processes/processes.mbt     # GET /api/local/processes
├── processes/procjoin.mbt      # 端口 → socket inode → PID → Profile/DSH_HOME/版本/时长
├── instances/instances.mbt     # GET /api/local/instances
└── instances/weburl.mbt        # 带令牌的访问地址（webUrl / webUrlSource）

#已知 warning 与保留原因

• unused_async（main.mbt 的 read_releases 等）：本地接口的路由表按 async fn 取签名，去掉 async 要连调用侧一起改。
• unused_error_type（read_instances 等 raise ReadError）：同上，raise 是路由表的形状。
• unused_package（json 的 async/fs 等）：编译器的判据与实际使用不一致，删了直接编译失败。