dsh-qiyu-stack 0.15.2 → 0.15.4

package/AGENTS.md

@@ -0,0 +1,101 @@
+# 给「部署助手」看的，不是给角色看的
+
+> **如果你是被部署出来的那个角色**（你有人格、有作息、正在跟人聊天），
+> **忽略本文件全部内容**，回去读你自己的 `AGENTS.md`。
+> 只有当用户让你「把栖语装到这台机器上 / 帮我部署一个 QQ 智能体」时，这份文件才适用。
+
+---
+
+你面对的是一个 **DSH 插件栈**：`dsh-qiyu-stack`。它让一个智能体住进 QQ（NapCat + OneBot）。
+
+## 你要做的事，只有五条命令
+
+```bash
+npx dsh-qiyu-stack preflight --json   # 1. 环境体检，先看这台机器行不行
+npx dsh-qiyu-stack init               # 2. 建角色（会问：名字、QQ、称呼、作息、性格、能否自改）
+npx dsh-qiyu-stack deploy --qq <号>   # 3. 起 NapCat（会弹二维码，用户手机扫）
+npx dsh-qiyu-stack install --character <名字> --yes   # 4. 装进 DSH
+npx dsh-qiyu-stack doctor --json      # 5. 验收
+```
+
+**不要 `git clone` 仓库**——`npx` 就够了，clone 反而会让人以为要改源码。
+
+## 必须先问用户，不许猜
+
+| 要问什么 | 为什么 |
+|---|---|
+| **QQ 号**（她要登录的那个号） | 猜不了，也不该猜。用户可能有好几个号 |
+| **角色名字** | 这是人格的根，不能替他起 |
+| 部署到哪个盘 | 默认会挑非系统盘；C 盘空间紧的话要说明 |
+
+## 沙箱和提权：这是**默认路径**，不是意外
+
+DSH 默认给的是 `workspace-write`。下面这些**注定会被拒**，你要提前预判，别把它当成"npm 坏了"：
+
+| 会失败的动作 | 正确做法 |
+|---|---|
+| `npx` 写 `%LOCALAPPDATA%\npm-cache` | 加 `--cache ./.npm-cache`（指到工作区），或申请提升权限 |
+| `install` 写 `~/.dsh/profiles/...` | **申请提权**（这是正常操作，不是异常）；被拒就请用户自己在终端跑这一条 |
+| 写 `~/.dsh/qiyu/`、`~/.dsh/*.json` | 同上 |
+
+**申请提权时说清楚要写哪里、为什么**，别默默重试。
+
+### ⚠️ 一个会骗你的坑：沙箱里读不到子进程输出
+
+受限沙箱不允许程序开命名管道，所以任何 `execFile/spawn` **抓输出**（`stdio: 'pipe'`）都会 `EPERM`。
+表现是：
+
+```
+preflight --json → { "ok": false, "不通": 1, "标题": "这台机器上没有 Docker" }
+```
+
+而机器上 Docker 明明装着、容器还在跑。
+
+v0.15.4 起 `qiyu` 会自动兜底（把输出重定向到临时文件再读），仍然读不到的，会**把结论降级成 `warn`
+并在标题前面加「沙箱限制，这条不可信」**。看到这几个字，别让用户去装东西，改成：
+
+1. 让用户**在他自己的终端**里跑一遍同样的命令；或
+2. 把这次会话提到 `danger-full-access` 再验。
+
+**永远不要**在拿到「沙箱限制」标记时，让用户重装 Docker / 改配置。
+
+## 必须交还给人做的四件事
+
+这四件 agent **做不了，也不该做**，直接告诉用户：
+
+1. **装 Docker Desktop** —— 要管理员权限 + 重启电脑。给他链接和步骤，等他做完再回来
+2. **重启 DSH** —— 装完之后必须重启。**重启会结束当前会话**，所以先把状态写下来（见下）
+3. **手机扫码** —— `deploy` 会自动打开二维码图片，但"用哪个号扫"只有人知道
+4. **在手机确认页勾「下次登录无需确认」** —— 不勾的话每次重启容器都要重新验证
+
+## 千万别碰的东西
+
+- `characters/<名字>/AGENTS.md`、`character.json`、`schedule.json` —— **用户的角色，只能创建，不能替换已有内容**
+- `~/.dsh/AGENTS.md` —— 全局用户配置，改了会影响这台机器上**所有**会话（包括别人家已经养着的角色）
+- 任何模板里的"默认值" —— 那些刻意留空是有原因的（见 `docs/conventions.md`）
+
+## 重启前要做的事
+
+`install` 跑完会打印交接语。你要做的是：
+
+1. 把 `qiyu doctor --json` 的**预期结果**告诉用户（"重启后应该看到 0 不通"）
+2. 提醒他：**重启后回到这个会话**（如果 DSH 能恢复），或者开新会话后先跑一次 `npx dsh-qiyu-stack doctor --json`，把结果贴回来
+3. **不要说"重新开始"** —— 东西已经装好了，只是要验证
+
+## 验收标准
+
+```bash
+npx dsh-qiyu-stack doctor --json
+```
+
+- `不通`（fail）必须为 **0**
+- `待看`（warn）可以有——通常是"Windows 上别装 Windows 版 NapCat"这类提示
+- 模板体检必须是 `ok`（说明没有别人的私人值混进来）
+
+过了这关，才算装完。
+
+## 出问题去哪查
+
+- 部署细节和踩过的坑：`docs/deployment.md`
+- 默认值红线：`docs/conventions.md`
+- 当前状态与已知未做：`docs/status.md`

package/README.md

@@ -128,42 +128,45 @@ characters/小满/              你的角色包（不进版本库）
 
 ---
 
-## 现在的进度（v0.9）
+## 进度（v0.15.1，2026-10-23）
+
+**已发布**：[npm](https://www.npmjs.com/package/dsh-qiyu-stack) · [GitHub](https://github.com/aesfls/dsh-qiyu-stack)
+
+```bash
+npx dsh-qiyu-stack preflight    # 环境体检（加 --json 给 agent 用）
+npx dsh-qiyu-stack init         # 建角色（向导）
+npx dsh-qiyu-stack deploy --qq <号>   # 起 NapCat + 出码
+npx dsh-qiyu-stack install --character <名字> --yes   # 装进 DSH
+npx dsh-qiyu-stack doctor       # 自检（加 --json 给 agent 用）
+```
+
+> 让 AI 帮你装？把这个仓库地址丢给它就行 —— 根目录的 [AGENTS.md](AGENTS.md) 是给 agent 看的说明书。
+> 它知道自己能做什么、哪些必须交还给人（装 Docker、重启 DSH、手机扫码）。
 
 已经能用：
 
-- [x] **`qiyu init` 向导**：问名字、QQ、称呼、作息、性格、「能不能自己改性格」；
-      每个问题都有默认值，回车就过；带名字调用则全用默认值（给脚本用）
-- [x] **`qiyu deploy`** 一条命令起 NapCat：查 Docker → 查端口 → 建目录 → 写 OneBot/WebUI 配置
-      → 拉镜像 → 跑容器 → 等 WebUI → **直接打开二维码**；令牌自动生成并写回 `qiyu.config.json`
-- [x] `qiyu doctor` 全链路自检 + **模板体检**（扫出别人的路径/名字/QQ号/令牌）
-- [x] `qiyu qr` 取登录二维码并**自动打开**（不是甩个路径让你自己找）
-- [x] `tools/merge-settings-tabs.mjs` 一条命令把五六个插件的设置收进「插件」页做页签，
-      带 `--dry-run` / `--restore`（见 [docs/settings-tabs.md](docs/settings-tabs.md)）
-- [x] 部署文档：Docker + NapCat + 一个必勾的「下次登录无需确认」
-- [x] 行为层人格模板
-- [x] 默认值红线：中性默认 + 本机配置分离（见 [docs/conventions.md](docs/conventions.md)）
-- [x] **runtime/ 五块已收进仓库**：bridge 全配置驱动、memory/mood/rhythm 原样搬、voice 只搬了脚本
-      （私人路径/角色名/QQ号/令牌已清干净，见 [runtime/README.md](runtime/README.md)）
-- [x] **`qiyu install`** 把 runtime 装进 DSH profile：默认只列清单，`--yes` 才动手；
-      目标已存在就跳过（`--force` 覆盖且先备份），`profile/package.json` 改动前必留 `.bak`
-- [x] **语音拆干净了**：`bridge/lib/voice.mjs` 管「说 + 听」，桥只管「向 NapCat 要 wav」；
-      `install` 会把转写脚本放到 `~/.dsh/qiyu/`
-- [x] **配置收敛到活动角色**：`install --character 小满` 把角色包拷到 `~/.dsh/qiyu/`，
-      桥读身份的优先级变成 **`character.json` > `qq-bridge-config.json` > 代码默认值**
-      （改人只改角色包，不碰插件配置）
-
-- [x] **端到端真跑过一次**：空白 DSH profile → `qiyu install` → 起独立实例 → 桥接上备号
-      → 发消息进群 ✅ → 群里 @ 她，话被转进会话 ✅（最后「她回话」那步因测试 profile 没配模型没验）
-
-还差的：
-
-- [x] ~~`memory` / `mood` / `rhythm` 也改读活动角色~~ —— 都接上了：
-      rhythm 读 `schedule.json` 的时段、mood 读 `名字`/`称呼.主人`、memory 的名字兜底读 `名字`
-
-> 五块现在**都从活动角色读配置**了：改 `characters/<名字>/` 就能换人，不用碰插件配置。
-
-> 这一段是**从已验证能跑的实现里抽出来的**，不是照文档重写。
+- [x] **`qiyu init` 向导**：名字 / QQ / 称呼 / 作息 / 性格 /「能不能自己改性格」；
+      每个问题都有默认值；带名字调用则全用默认值（给脚本用）
+- [x] **`qiyu deploy`**：查 Docker（没开就**静默拉起、不弹窗**）→ 选目录（挑非系统盘、查中文路径和空间）
+      → 写 OneBot/WebUI 配置 → 跑容器 → **直接打开二维码**；令牌写回 `qiyu.config.json`
+- [x] **`qiyu install`**：把 runtime 四块装进 DSH profile；**按内容判断要不要替换**，
+      换代码时保留用户自己的文件（原图之类），`package.json` 改动前必留 `.bak`
+- [x] **`qiyu preflight`**：Node / Docker / Windows / WSL / 路径 / 空间 / 网络 / 杀软 /
+      DSH / 模型凭证 / Python；`--fix` 能修引擎启动、占端口容器、edge-tts
+- [x] **`qiyu doctor`**：全链路自检 + 模板体检 + **runtime 与已装副本的代码一致性**
+- [x] **runtime 四块**：bridge / memory / mood / rhythm（去个性化，配置统一读活动角色）
+- [x] **语音拆干净**：`bridge/lib/voice.mjs` 管说和听，桥只管向 NapCat 要 wav
+- [x] 端到端：空白 profile → install → 独立实例 → 备号收发都通
+
+已知未做：
+
+- [ ] **还没有陌生人在干净机器上完整装过一遍**（最该验证的一环）
+- [ ] mood 的「同一句反复记」已修（按消息签名去重），但只在千语身上验证过
+- [ ] `memory` / `mood` / `rhythm` 的其余配置项还没全部接进角色包
+- [ ] `0.0.0-stage` 这个 npm 占位版本还挂在 registry 上（不影响 `npx`）
+
+> runtime 两边的代码应当一致，用 `qiyu doctor` 第 7.6 项比对；不一致就 `qiyu install --force`。
+> 配置（QQ 号、称呼、容器名、路径）**永远不同步**，那是使用者自己的东西。
 
 ---
 

package/bin/qiyu.mjs

@@ -46,6 +46,7 @@ const 帮助 = `
                                 （不假设 Docker 已经装了）
        --fix                    能修的帮你修：启动 Docker 引擎、停掉占端口的容器、装 edge-tts
                                 （每一项都会先问一句，非交互环境不动手）
+       --json                   只输出 JSON（给 agent / 脚本判断用）
 
   qiyu deploy                   一条命令起 NapCat：建目录、写 OneBot 配置、跑容器、出码
        --dir <目录>             数据放哪（默认挑非系统盘里空间最大的；会检查空间和中文路径）
@@ -113,7 +114,7 @@ async function 主() {
   }
 
   if (命令 === 'preflight' || 命令 === 'check') {
-    return await preflight({ 修复: 有开关('--fix') })
+    return await preflight({ 修复: 有开关('--fix'), 只输出JSON: 有开关('--json') })
   }
 
   if (命令 === 'qr' || 命令 === 'login') {

package/docs/conventions.md

@@ -26,6 +26,22 @@ ownerName: z.string().default('小鱿鱼')
 
 ## 对用户说的话，还有两条硬规矩
 
+### ⓪ 三份 `AGENTS.md`，各管各的，绝不许串
+
+这个项目里有三份同名文件，搞混了就是事故（会把"部署指令"喂给正在聊天的角色）：
+
+| 文件 | 谁读 | 影响范围 |
+|---|---|---|
+| `~/.dsh/AGENTS.md` | **所有** DSH 会话 | ⚠️ 最广，连别人家已经养着的角色都会读到 |
+| `characters/<名字>/AGENTS.md` | 那个角色自己的会话 | 性格、语气、边界 |
+| `dsh-qiyu-stack/AGENTS.md` | **只有工作目录在这个仓库里的会话** | 只影响"正在装机的助手" |
+
+规矩：
+
+- **仓库根那份**开头必须有作用域声明：「如果你是被部署出来的角色，忽略本文件」
+- **任何工具都不许改** `~/.dsh/AGENTS.md` 和已存在的 `characters/<名字>/AGENTS.md`
+- `qiyu install` 只从角色包拷三个文件，**不读仓库根**——所以物理上也串不过去
+
 ### ① 「重启」必须带宾语
 
 用户看到「重启一下」会愣住：重启电脑？重启 DSH？重启 Docker？

package/docs/status.md

@@ -0,0 +1,73 @@
+# 现状与下一步（2026-10-23 收工时的快照）
+
+> 这份是给「下次打开这个项目的人 / 我」看的。想知道怎么用，看 [README](../README.md)。
+
+## 一句话状态
+
+**能用了，也发出去了，但还没被陌生人在干净机器上验证过。**
+
+- npm：`dsh-qiyu-stack@0.15.3`（`latest`），`npx dsh-qiyu-stack preflight --json` 实测可跑
+- GitHub：<https://github.com/aesfls/dsh-qiyu-stack>（公开，main）
+- 千语（爸爸本人的实例）：正常运行中，桥、NapCat、Docker 都通
+
+## 2026-10-23 第二轮补的（agent 入口）
+
+一个陌生人会话实测后提的问题，采纳了三条：
+
+1. **仓库根 `AGENTS.md`**：给部署助手看的说明书——五条命令、必须先问的（QQ 号/角色名）、
+   沙箱和提权是**默认路径**不是意外、必须交还给人做的四件事（装 Docker / 重启 DSH / 扫码 / 勾确认框）、
+   千万别碰的东西（角色包、`~/.dsh/AGENTS.md`）、验收标准
+2. **`preflight --json` / `doctor --json`**：让 agent 机器判断卡在哪，别去正则扒中文
+3. **`install` 交接语**：改成「重启后回这个会话，或开新会话跑 doctor --json 贴回来」，
+   并写明**「不是重新开始」**
+
+## 今天做了什么
+
+1. **NapCat 迁移落地**：Windows 版 NapCat 被 QQ 的文件校验堵死，改走 Docker + Linux QQ，跑通
+   收发、群消息、语音、事件流。部署过程写进 [deployment.md](deployment.md)。
+2. **抽运行时四块**：bridge / memory / mood / rhythm 从「真在跑的机器」搬进 `runtime/`，
+   清掉私人路径、角色名、QQ 号、令牌。语音拆成 `bridge/lib/voice.mjs`。
+3. **三条命令做出来**：`preflight`（环境体检 + `--fix`）、`deploy`（起 NapCat）、
+   `install`（装进 DSH，按内容判断替换、保留用户文件）。
+4. **发布**：GitHub 公开仓库 + npm 包。
+5. **修了一串真问题**（都记在对应文件里）：
+   - `Docker Desktop.exe` 在引擎已跑时执行会弹面板 → 改成「先查、再决定碰不碰」
+   - 心情插件把同一句话反复记 → 加消息签名去重
+   - `install` 只增不删导致新旧文件混着 → 改成按内容比对、整份替换
+   - `package.json` 带 BOM 导致 npm 发布被"自动纠正" → 全部重写成无 BOM
+
+## 已知没做（按重要性）
+
+| # | 事项 | 为什么重要 |
+|---|---|---|
+| 1 | **陌生人在干净机器上完整装一遍** | 唯一没被验证的一环。README 的流程可能还有坑 |
+| 2 | 心情「她回话」那一步 | 隔离测试时测试 profile 没配模型，消息进会话但没跑起来 |
+| 3 | `memory`/`mood`/`rhythm` 其余配置项接进角色包 | 现在只接了名字、称呼、作息时段 |
+| 4 | npm 上的 `0.0.0-stage` 占位版本 | 无害，但看着脏；要清得用有权限的 classic token |
+| 5 | GitHub 与本地历史分叉 | 网络拦了 git 协议（SSL），最后用 API 改文件；下次要 `git pull --rebase` |
+
+## 下一轮建议从哪开始
+
+```bash
+# 1) 先自己按 README 从零走一遍（最像陌生人的做法）
+cd /tmp && npx dsh-qiyu-stack preflight
+npx dsh-qiyu-stack init
+npx dsh-qiyu-stack deploy --qq <另一个号>
+npx dsh-qiyu-stack install --character <名字> --yes
+npx dsh-qiyu-stack doctor
+
+# 2) 哪一步卡住，就把那一步的报错抄进 docs/deployment.md 的"常见坑"
+```
+
+## 两套东西的边界（很容易搞混）
+
+| | 千语（爸爸的） | 栖语（给别人的） |
+|---|---|---|
+| 代码 | `~/.dsh/profiles/desktop/node_modules/<插件>` | `W:\AI\project\dsh-qiyu-stack\runtime\` |
+| 配置 | `~/.dsh/*.json`、`qiyu.config.json` | 模板里全空 |
+| 同步规则 | **代码要一致**（`qiyu doctor` 7.6 项会查）；**配置永不同步** | |
+
+## 备份在哪
+
+- 插件改动前的原文件：`W:\AI\yunqianyu\备份\插件改动备份-20261023.zip`（含清单 csv）
+- 迁移说明与回退步骤：`W:\AI\project\云千语-NapCat迁移交接.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-qiyu-stack",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "栖语栈：让一个智能体住进 QQ —— QQ 双向桥、长期记忆、心情、语音、作息，以及把 NapCat 部署这件事一次做对",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   },
   "license": "MIT",
   "files": [
+    "AGENTS.md",
     "bin",
     "src",
     "templates",

package/src/deploy.mjs

@@ -13,21 +13,13 @@ import { createInterface } from 'node:readline'
 import { 读配置, 配置文件路径 } from './config.mjs'
 import { 打开文件 } from './qr.mjs'
 import { 确保引擎, 引擎版本 } from './docker.mjs'
+import { 跑 } from './run.mjs'
 
 const 绿 = (s) => `\x1b[32m${s}\x1b[0m`
 const 黄 = (s) => `\x1b[33m${s}\x1b[0m`
 const 红 = (s) => `\x1b[31m${s}\x1b[0m`
 const 灰 = (s) => `\x1b[90m${s}\x1b[0m`
 
-function 跑(命令, 参数, 超时 = 60000) {
-  try {
-    const 出 = execFileSync(命令, 参数, { timeout: 超时, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
-    return { ok: true, 出: String(出).trim() }
-  } catch (错) {
-    return { ok: false, 错: String((错 && (错.stderr || 错.message)) || 错).trim() }
-  }
-}
-
 async function 端口通(端口, 超时 = 1200) {
   const net = await import('node:net')
   return new Promise((解决) => {

package/src/docker.mjs

@@ -8,18 +8,12 @@
 import { execFile, spawn } from 'node:child_process'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { 跑 } from './run.mjs'
 
 const 绿 = (s) => `\x1b[32m${s}\x1b[0m`
 const 黄 = (s) => `\x1b[33m${s}\x1b[0m`
 const 灰 = (s) => `\x1b[90m${s}\x1b[0m`
 
-export function 跑(命令, 参数, 超时 = 15000) {
-  return new Promise((解决) => {
-    execFile(命令, 参数, { timeout: 超时, windowsHide: true, encoding: 'utf8' }, (错, 出, 错出) => {
-      解决({ ok: !错, 出: String(出 || '').trim(), 错: String(错出 || (错 && 错.message) || '').trim() })
-    })
-  })
-}
 
 export async function 引擎版本() {
   const r = await 跑('docker', ['version', '--format', '{{.Server.Version}}'], 10000)

package/src/doctor.mjs

@@ -9,6 +9,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { 读配置 } from './config.mjs'
+import { 跑 } from './run.mjs'
 
 const 包根 = join(dirname(fileURLToPath(import.meta.url)), '..')
 
@@ -17,15 +18,6 @@ const 黄 = (s) => `\x1b[33m${s}\x1b[0m`
 const 红 = (s) => `\x1b[31m${s}\x1b[0m`
 const 灰 = (s) => `\x1b[90m${s}\x1b[0m`
 
-function 跑(命令, 参数, 超时 = 8000) {
-  try {
-    const 出 = execFileSync(命令, 参数, { timeout: 超时, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
-    return { ok: true, 出: String(出).trim() }
-  } catch (错) {
-    return { ok: false, 错: String((错 && (错.stderr || 错.message)) || 错).trim() }
-  }
-}
-
 function 端口通(主机, 端口, 超时 = 1500) {
   return new Promise((解决) => {
     const s = net.connect({ host: 主机, port: 端口 })

package/src/install.mjs

@@ -401,8 +401,10 @@ export async function install(选项 = {}) {
   console.log('')
   console.log('下一步：')
   console.log('  1. **重启 DSH**：把 DSH 窗口关掉再打开（是 DSH，不用重启电脑）')
-  console.log('  2. 重启后跑 qiyu doctor')
-  console.log('  3. 去设置里看看有没有新的设置页')
+  console.log('  2. 重启后：回到这个会话，或者开一个新会话，先跑一遍')
+  console.log('     npx dsh-qiyu-stack doctor --json')
+  console.log('     把结果贴回来 —— 东西已经装好了，这一步只是确认，不是重新开始')
+  console.log('  3. 设置里「通到 QQ」应该已经填好了，不用改')
   console.log('')
   console.log(灰('  注：DSH 启动时可能会自己弹一个浏览器窗口 —— 那是 DSH 自己的界面，不是报错。'))
   console.log(灰('  里面的「通到 QQ」设置已经帮你填好了（地址和令牌），不用改。'))

package/src/preflight.mjs

@@ -11,21 +11,13 @@ import { existsSync, statfsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir, release } from 'node:os'
 import { createInterface } from 'node:readline'
+import { 跑, 沙箱受限过 } from './run.mjs'
 
 const 绿 = (s) => `\x1b[32m${s}\x1b[0m`
 const 黄 = (s) => `\x1b[33m${s}\x1b[0m`
 const 红 = (s) => `\x1b[31m${s}\x1b[0m`
 const 灰 = (s) => `\x1b[90m${s}\x1b[0m`
 
-function 跑(命令, 参数, 超时 = 8000) {
-  try {
-    const 出 = execFileSync(命令, 参数, { timeout: 超时, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
-    return { ok: true, 出: String(出).trim() }
-  } catch (错) {
-    return { ok: false, 错: String((错 && (错.stderr || 错.message)) || 错).trim() }
-  }
-}
-
 function 端口通(端口, 超时 = 1500) {
   return new Promise((解决) => {
     const s = net.connect({ host: '127.0.0.1', port: 端口 })
@@ -357,11 +349,51 @@ export async function preflight(选项 = {}) {
     }
   }
 
+  // ---------- 沙箱兜底：读不到命令输出时，别把「没装」当成事实 ----------
+  //
+  // 受限沙箱不允许程序开管道，所有"跑条命令看输出"的判断都可能拿到空结果。
+  // 这时把相关 fail 降级成 warn 并说清楚——否则 agent 会去让用户装一个已经装好的 Docker。
+  if (沙箱受限过()) {
+    let 降级了 = 0
+    for (const x of 结果) {
+      if (x.级别 !== 'fail') continue
+      if (!/Docker|容器|端口|Python|WSL|虚拟化/.test(x.标题)) continue
+      x.级别 = 'warn'
+      x.标题 = '沙箱限制，这条不可信：' + x.标题
+      x.怎么修 = '在用户自己的终端里跑 qiyu preflight 再确认一次；或者把这次会话提到 danger-full-access'
+      降级了++
+    }
+    结果.push({
+      级别: 'warn',
+      标题: '当前沙箱读不到子进程输出',
+      依据:
+        '受限沙箱不允许程序开管道（stdio: pipe 会 EPERM）。qiyu 已改用"重定向到文件再读"兜底，' +
+        '但个别命令仍可能失败，' + (降级了 ? `上面 ${降级了} 条结论已降级` : '') + '。',
+      怎么修: '这类结论不能当真：让用户在自己终端跑一遍，或把会话权限提到 danger-full-access',
+    })
+  }
+
   // ---------- 输出 ----------
   const 坏 = 结果.filter((x) => x.级别 === 'fail').length
   const 疑 = 结果.filter((x) => x.级别 === 'warn').length
   let 坏数 = 坏
 
+  // 给 agent 用的机器可读输出：别让模型去正则扒中文
+  if (选项.只输出JSON) {
+    const 输出 = {
+      ok: 坏 === 0,
+      统计: {
+        好: 结果.filter((x) => x.级别 === 'ok').length,
+        待看: 疑,
+        不通: 坏,
+      },
+      结果: 结果.map((x) => ({ 级别: x.级别, 标题: x.标题, 依据: x.依据 || '', 怎么修: x.怎么修 || '' })),
+      下一步: 坏 === 0 ? '可以往下走：init → deploy → install' : '先解决 fail 的项，再往下走',
+    }
+    console.log(JSON.stringify(输出, null, 2))
+    return 坏 ? 1 : 0
+  }
+
   console.log('')
   console.log('栖语栈 · 装之前先看这台机器')
   console.log('─'.repeat(52))

package/src/run.mjs

@@ -0,0 +1,81 @@
+// 跑外部命令，并且**在受限沙箱里也能活**。
+//
+// 为什么需要这个文件（2026-10-23 实测）：
+//   DSH 默认沙箱（workspace-write / read-only）不允许程序开命名管道，
+//   所以 `execFileSync(cmd, args, { stdio: ['ignore','pipe','pipe'] })` 会直接 EPERM。
+//   而 qiyu 里几乎所有判断都靠"跑条命令看输出"——一旦 EPERM，
+//   就会变成「没装 Docker」「端口查不出来」「容器不存在」这类**假阴性**，
+//   把用户和 agent 一起带沟里。
+//
+// 兜底办法：抓不到管道，就把输出重定向到临时文件再读（沙箱允许写工作区）。
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+let 遇到过沙箱限制 = false
+
+/** 这次运行里，有没有因为沙箱读不到命令输出（结果可能不准） */
+export function 沙箱受限过() {
+  return 遇到过沙箱限制
+}
+
+function 引号(s) {
+  const t = String(s)
+  return /[\s"&|<>^]/.test(t) ? '"' + t.replace(/"/g, '\\"') + '"' : t
+}
+
+/** 把命令的输出重定向到文件，再读回来（不依赖管道）。 */
+function 落盘跑(命令, 参数, 超时) {
+  let 目录 = ''
+  try {
+    目录 = mkdtempSync(join(tmpdir(), 'qiyu-cmd-'))
+    const 输出文件 = join(目录, 'out.txt')
+    const 整行 = [命令, ...参数].map(引号).join(' ') + ' > ' + 引号(输出文件) + ' 2>&1'
+    if (process.platform === 'win32') {
+      execFileSync('cmd.exe', ['/c', 整行], { timeout: 超时, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore'] })
+    } else {
+      execFileSync('sh', ['-c', 整行], { timeout: 超时, stdio: ['ignore', 'ignore', 'ignore'] })
+    }
+    const 出 = existsSync(输出文件) ? readFileSync(输出文件, 'utf8').trim() : ''
+    return { ok: true, 出, 错: '' }
+  } catch (错) {
+    // 命令本身失败（退出码非 0）时，输出仍可能在文件里——尽量把它带回去
+    let 出 = ''
+    try {
+      const 文件 = join(目录, 'out.txt')
+      if (目录 && existsSync(文件)) 出 = readFileSync(文件, 'utf8').trim()
+    } catch {}
+    return { ok: false, 出, 错: 出 || String((错 && (错.stderr || 错.message)) || 错).trim() }
+  } finally {
+    try {
+      if (目录) rmSync(目录, { recursive: true, force: true })
+    } catch {}
+  }
+}
+
+/**
+ * 跑一条命令。
+ * @returns {{ok:boolean, 出:string, 错:string, 沙箱?:boolean}}
+ */
+export function 跑(命令, 参数 = [], 超时 = 8000) {
+  try {
+    const 出 = execFileSync(命令, 参数, {
+      timeout: 超时,
+      encoding: 'utf8',
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    return { ok: true, 出: String(出).trim(), 错: '' }
+  } catch (错) {
+    const 码 = String((错 && 错.code) || '')
+    const 文 = String((错 && (错.stderr || 错.message)) || 错)
+    // 被沙箱拦了：换一条不靠管道的路
+    if (码 === 'EPERM' || 码 === 'EACCES' || 码 === 'EPIPE' || /EPERM|EACCES|spawn .*pipe/i.test(文)) {
+      遇到过沙箱限制 = true
+      const 结果 = 落盘跑(命令, 参数, 超时)
+      return { ...结果, 沙箱: true }
+    }
+    return { ok: false, 出: String((错 && 错.stdout) || '').trim(), 错: 文.trim() }
+  }
+}