@lark-apaas/coding-steering 0.1.60 → 0.1.61-alpha.20261002215905

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.60",
+  "version": "0.1.61-alpha.20261002215905",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"
   },
@@ -17,8 +20,5 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT",
-  "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
-  }
-}
+  "license": "MIT"
+}

package/steering/nestjs-react-fullstack/skills/coding-guide/SKILL.md

@@ -154,7 +154,7 @@ shared/
 ## 开发环境与内置服务
 
 - **登录/注册/用户系统**：内置，禁止自行实现
-- 项目依赖已安装完整，前后端 devServer 已启动并自动重启（无需怀疑），文件变更自动热重载
+- 项目依赖已安装完整，普通前端源码变更由 HMR 更新；服务端子进程退出后，只有当前环境的 supervisor 明确接管时才会重启。两者都不保证被 production build 替换的输出会自动恢复
 - `/api` 和 `/openapi` 代理已配置，前端 TS 严格模式已禁用，后端已启用
 - Rspack 用于构建，已配置好，**禁止修改**
 - **禁止修改的工程配置文件与目录**：
@@ -164,6 +164,13 @@ shared/
   - `.eslintrc.js`、`.prettierrc`
   - `node_modules/`、`.git/`、`dist/`、`build/`
 
+### 开发预览与 production build
+
+- `npm run build`、`npm run build:prod`、`npm run build:client` 及等价 production 入口会生成或替换生产输出，不是普通提交或发布前的默认自检。默认按改动范围运行代码检查、接口测试并读取相关日志，不在开发预览工作区执行本地 production build
+- 只有明确需要 production 产物时才允许构建，并且必须满足其一：构建入口支持预览输出保护和显式隔离 `outDir`，且确认解析后的目录不是当前预览服务目录；或在没有活动预览的独立工作副本中构建
+- 旧版 SDK、脚本不支持输出保护时，不得在活动预览工作区运行 production 入口；无法确认隔离目录或独立副本没有活动预览时，停止并报告缺少的隔离条件
+- build 命令 `exit=0` 只证明该命令完成，不证明开发预览或业务页面健康
+
 ### `__runtime__` 接口在 Agent 验证入口下不可达
 
 **判据**：请求路径含 `__runtime__`，或不以 `/api` / `/openapi` 开头——在 Agent 这里一定拿不到正常响应。不必重试，也不要换请求方法再试。
@@ -232,7 +239,8 @@ shared/
 通用提交前检查（代码检查 / 接口测试 / 读日志确认无错误）见系统任务流程约束；本栈具体落点：
 
 - **日志源**：服务端读 `server-devserver` / `server` 日志，客户端读 `client-devserver` 日志
-- **dev 服务无响应**：`pkill -f "npm run dev"` 触发重启
+- **恢复边界**：只能使用合同明确绑定当前 app/client 的运维工具执行恢复；没有这种工具时停止操作，报告所需的 app/client 范围与恢复合同，不按命令字符串批量终止进程，也不声称已恢复
+- **恢复验收**：实际执行恢复后，必须重新运行真实 E2E，并从页面 HTML 识别应用自身的可执行入口资源（不是只看 HMR/平台辅助脚本），确认这些资源均可成功返回 JavaScript；只看进程、日志或 build 退出码不能证明业务恢复
 
 ---
 

package/steering/nestjs-react-fullstack/skills/devops-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devops-guide
-description: "Use when user needs build, deploy, run, troubleshoot, or operate a miaoda fullstack app. IMPORTANT: Only activate this skill when the user explicitly asks about deployment, build failures, or service operations. Do NOT proactively trigger this skill during normal code development — reading devops skills to troubleshoot preemptively disrupts the development workflow. Only use when: build fails, deploy fails, service crashes, or user explicitly asks about ops issues. 触发词：devops, 构建, 部署, 运维, 日志, 启动失败, 编译失败, 服务异常, read_logs, pkill, ps, pstree"
+description: "Use when user needs build, deploy, run, troubleshoot, or operate a miaoda fullstack app. IMPORTANT: Only activate this skill when the user explicitly asks about deployment, build failures, or service operations. Do NOT proactively trigger this skill during normal code development — reading devops skills to troubleshoot preemptively disrupts the development workflow. Only use when: build fails, deploy fails, service crashes, or user explicitly asks about ops issues. 触发词：devops, 构建, 部署, 运维, 日志, 启动失败, 编译失败, 服务异常, read_logs, ps, pstree"
 steering: true
 steering-topic: devops
 match-template-name: nestjs-react-fullstack
@@ -17,9 +17,9 @@ control-by-feature-ab: true
 
 | 场景 | 必做动作 | 结果标准 |
 |------|----------|----------|
-| 修改代码后自检 | 先跑代码检查工具 | 无语法错误、无类型错误、无明显构建错误 |
+| 修改代码后自检 | 按改动范围跑代码检查 | 对应语法、类型与样式检查通过 |
 | 修改服务端代码 | 补跑接口测试 | 每个新增接口都能验证通过 |
-| 准备交付前 | 读取最新日志 | 最新改动后无错误日志 |
+| 准备交付前 | 读取最新日志，不默认跑本地 production build | 最新改动后无错误日志 |
 | 用户反馈编译失败 | 查 lint/typecheck + devServer 日志 | 定位到具体文件、具体报错 |
 | 用户反馈服务无响应 | 查日志 + 查进程状态 | 确认是代码报错还是 dev 进程卡死 |
 
@@ -27,11 +27,9 @@ control-by-feature-ab: true
 
 ### A. 代码改完后的质量保障
 
-按固定顺序执行：
-
-1. 运行代码检查工具，优先发现语法、类型、样式问题。
+1. 按改动范围运行代码检查，优先发现语法、类型、样式问题。
 2. 若改了服务端代码，执行接口测试，覆盖新增接口。
-3. 最后读取日志，确认最新改动没有引入错误日志。
+3. 最后读取相关日志，确认最新改动没有引入错误日志。
 
 ### B. 编译失败 / 服务启动失败 / 页面异常
 
@@ -56,37 +54,22 @@ control-by-feature-ab: true
 - **不要基于旧日志下结论**，要读取最新日志。
 - 日志为空不代表没问题，先确认对应服务是否真的在运行。
 
-## Step 3：devServer 无响应时的 SOP
-
-若你发现代码已经修改，但 dev 日志长时间不更新，优先怀疑 dev 进程失活。
-
-### 检查顺序
-
-1. 用 `ps` / `pgrep` / `pstree` 确认 `dev:server`、`dev:client` 相关进程是否存在。
-2. 若进程存在但日志不更新，先把现象记录为结论，不要直接重启环境。
-3. 只有调用方明确要求时，才执行 `pkill -f "dev:server"` 或 `pkill -f "dev:client"`。
-
-### 推荐命令
+## Step 3：区分更新与恢复机制
 
-```bash
-ps -ef | grep "dev:server"
-ps -ef | grep "dev:client"
-pgrep -af "dev:server"
-pgrep -af "dev:client"
-pstree -p <pid>
-pkill -f "dev:server"
-pkill -f "dev:client"
-```
+- **源码 HMR**：只处理开发服务支持的源码热更新，不修复被 production build 替换的输出。
+- **child-exit supervisor**：只有当前环境明确提供 supervisor 合同时，子进程退出后才可能被拉起；以新的进程状态和日志确认，不能预设必然重启。
+- **输出替换**：production 输出覆盖开发预览内容不属于 HMR 或 child-exit，不能等待自动恢复。
 
-### 判断标准
+需要恢复时：
 
-- 有进程、日志持续刷新：devServer 正常，继续排查代码问题。
-- 有进程、日志不刷新：高概率卡死，先报告现象和证据。
-- 没进程：说明服务未拉起，先看最近一次 devServer 错误日志。
+1. 先读取最新日志、真实页面、页面中的应用入口资源，并确认当前 app/client 范围。
+2. 只有已文档化的运维工具合同明确绑定当前 app/client 时，才用它执行恢复。
+3. 没有这样的工具合同就停止，准确报告当前状态，以及继续操作所缺的 app/client 范围或恢复合同；不要按命令字符串批量终止进程，不要声称已恢复。
+4. 实际恢复后重新读取日志，运行真实 E2E，并确认页面 HTML 中应用自身的可执行入口资源均成功返回 JavaScript；进程存在、日志刷新或命令 `exit=0` 都不能替代业务验收。
 
 ## Step 4：构建 / 部署 / 运维排查框架
 
-按照 **现象 → 根因 → 方案** 输出。
+按照 **现象 → 根因 → 方案** 输出。production build 的入口范围、默认检查、隔离输出与旧版 fail-safe 边界，以 always-loaded `coding-guide` 的“开发预览与 production build”为唯一权威规则。
 
 ### 常见现象映射
 
@@ -96,7 +79,7 @@ pkill -f "dev:client"
 | 后端启动失败 | Nest 模块注册错误、配置错误、运行时异常 | 查 `server-devserver` 和 `server` |
 | 页面白屏 | 前端编译错误、运行时异常、接口异常 | 查 `client-devserver`，必要时补 `browser` |
 | 接口 500 | 服务端业务异常 | 查 `server` / `trace`，补接口测试 |
-| 热更新失效 | dev 进程卡死 | 查进程状态，不要默认重启 |
+| 热更新失效 | HMR 错误、子进程状态或输出被替换 | 分别核对日志、进程合同与页面入口，不默认重启 |
 
 ## 交付要求
 
@@ -114,6 +97,6 @@ pkill -f "dev:client"
 | 改完代码直接说“没问题” | 先跑代码检查，再读日志 |
 | 服务端改动后不测接口 | 必须验证新增接口 |
 | 只看 `server` 不看 `server-devserver` | 服务端至少看两个日志源 |
-| 发现无响应就直接 `pkill` | 先用 `ps` / `pgrep` / `pstree` 定位，再报告结论 |
-| `pkill` 后不复读日志 | 只有明确要求重启时才执行，并再次读日志确认 |
+| 发现无响应就按命令名结束进程 | 先定位 app/client；只有文档化的 scoped 工具才能执行恢复 |
+| 恢复后只看日志或退出码 | 重新运行真实 E2E，并验证应用入口资源 |
 | 只给结论不给证据 | 必须给日志或检查结果作为依据 |