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

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.61-alpha.20261002215905",
+  "version": "0.1.61",
   "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"
   },
@@ -20,5 +17,8 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  }
+}

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

@@ -20,7 +20,6 @@ unavailable-agents:
 - `client/src/app.tsx`（加路由 / Provider 可改，但**禁止删除其中的平台根组件 / Provider 包裹**，禁止用 `eslint-disable` 关掉平台校验规则）
 - `client/src/components/business-ui/*`
 - `server/modules/view/view.controller.ts`
-- `vite.config.ts`
 
 **修改 / 排查上列文件时**：
 
@@ -154,22 +153,15 @@ shared/
 ## 开发环境与内置服务
 
 - **登录/注册/用户系统**：内置，禁止自行实现
-- 项目依赖已安装完整，普通前端源码变更由 HMR 更新；服务端子进程退出后，只有当前环境的 supervisor 明确接管时才会重启。两者都不保证被 production build 替换的输出会自动恢复
+- 项目依赖已安装完整，前后端 devServer 由平台托管、进程退出后自动拉起，文件变更自动热重载；服务异常时按「dev 服务异常与重启」处理
 - `/api` 和 `/openapi` 代理已配置，前端 TS 严格模式已禁用，后端已启用
-- Rspack 用于构建，已配置好，**禁止修改**
+- 构建工具为 Vite（`vite.config.ts`）或 Rspack（`rspack.config.js`），以项目根实际存在的配置文件为准，已配置好，需要时可以修改（见下方「构建配置可改」）
 - **禁止修改的工程配置文件与目录**：
   - `package.json`、`tsconfig.json`、`jest.config.js`、`.env*`
   - `package-lock.json`、`pnpm-lock.yaml`、`yarn.lock`
-  - `webpack.config.js`、`vite.config.js`、`babel.config.js`
   - `.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` 只证明该命令完成，不证明开发预览或业务页面健康
+- **构建配置可改**：`vite.config.ts`、`rspack.config.js`、`webpack.config.js`、`babel.config.js` 允许按需修改。改坏或出现构建 / 启动异常时，先用 `git log -p -- <文件>`、`git diff <commit> -- <文件>` 查看改动历史定位问题，再用 `git restore --source=<commit> -- <文件>` 还原到可用版本（最早一次提交即模板原版）；不要凭记忆重写
 
 ### `__runtime__` 接口在 Agent 验证入口下不可达
 
@@ -232,15 +224,42 @@ shared/
 - **测后端接口**：优先用接口测试工具，只传以 `/api` 或 `/openapi` 开头的业务路径；工具会自动拼 `CLIENT_BASE_PATH`、选择正确 dev 端口，并补 CSRF 与用户身份。
 - **必须手写 curl 调 `/api/*` 时**：打 client dev server，不要打 NestJS `SERVER_PORT`；URL 必须带 `$CLIENT_BASE_PATH`，并同时带 `Cookie: suda-csrf-token=<X>` 与 `X-Suda-Csrf-Token: <X>`（两值字面相等）。漏 basePath 是 404，漏 CSRF 是 403，都不是业务代码 bug，不要为此改 csrf 中间件或给接口加白名单。
 - **不要直连 NestJS 端口**：会绕过 dev server / 网关注入，`x-larkgw-suda-webuser` 缺失后 `userContext.userId` 为空，依赖身份的接口会误判。
-- **判断服务是否启动**：看 `client-devserver` / `server-devserver` 日志的 ready / 编译成功。裸端口访问返回 404 或连不上（只监听 IPv6 等）都不能当服务故障的依据；同一 URL 连续两次同状态码就换排查方向，不要 `sleep` + curl 重试。
+- **判断服务是否启动**：用 `/dev/health`（见「dev 服务异常与重启」），或看 `client-devserver` / `server-devserver` 日志的 ready / 编译成功。裸端口访问返回 404 或连不上（只监听 IPv6 等）都不能当服务故障的依据；同一 URL 连续两次同状态码就换排查方向，不要 `sleep` + curl 重试。
+- **裸 curl 页面路径不能判断页面是否正常**：页面 HTML 由 NestJS 渲染，dev server 只把 `Accept: text/html` 的请求转给它；curl 默认的 `*/*` 拿到 404 或 HTML 都不是故障依据。也不要拼入口模块路径来验证页面。
 
 ## 质量保障流程
 
 通用提交前检查（代码检查 / 接口测试 / 读日志确认无错误）见系统任务流程约束；本栈具体落点：
 
 - **日志源**：服务端读 `server-devserver` / `server` 日志，客户端读 `client-devserver` 日志
-- **恢复边界**：只能使用合同明确绑定当前 app/client 的运维工具执行恢复；没有这种工具时停止操作，报告所需的 app/client 范围与恢复合同，不按命令字符串批量终止进程，也不声称已恢复
-- **恢复验收**：实际执行恢复后，必须重新运行真实 E2E，并从页面 HTML 识别应用自身的可执行入口资源（不是只看 HMR/平台辅助脚本），确认这些资源均可成功返回 JavaScript；只看进程、日志或 build 退出码不能证明业务恢复
+- **dev 服务异常**：先判据再重启，见下节
+
+### dev 服务异常与重启
+
+`npm run dev` 由平台托管：进程退出后约 1s 自动重新拉起；改代码靠热重载，不需要重启。重启解决不了编译错误和代码 bug，只用于确认进程挂死的场景。
+
+**先判据**：`curl -s localhost:$CLIENT_DEV_PORT/dev/health`（**不带** `$CLIENT_BASE_PATH`）。返回的不是 JSON（dev server 不支持该接口）就跳过这一步，直接做下面的快速判活
+
+| 返回 | 含义 | 动作 |
+|---|---|---|
+| `backend_failed` | 服务端编译 / 启动失败 | 读 `server-devserver` 日志修代码，**重启无效** |
+| `pending` | 正在启动 | 等 `server-devserver` 出现 `Server running on ...`，不要重启；持续超过约 30s 或日志里已有编译报错，直接读日志修代码，不要继续等 |
+| `ready` | Vite 在监听且 NestJS 端口可连 | 不代表 NestJS 没卡死，接口仍异常时做下面的快速判活 |
+
+**快速判活**：`curl -s -m 5 -o /dev/null -w '%{http_code}\n' localhost:$SERVER_PORT/`。返回任意 HTTP 状态码（含 404）= NestJS 在响应；`000` 且超时 = 挂死。只用于判活，测接口仍走接口测试工具；不要等接口测试工具超时（约 120s）再下结论。
+
+**现象归属**：
+
+- `/api/*` 返回 502，body 含 `Backend service is not running` / `temporarily unavailable`：dev server 连不上 NestJS。先读 `server-devserver` 日志，有报错就修代码（热重载会自行恢复）。刚改过服务端代码时，热重载期间短暂的 502 属正常，隔几秒用快速判活复测一次再下结论
+- 接口无响应 / 超时（不是 502）：NestJS 端口在但不处理请求，用快速判活确认后按挂死处理
+- `browser` 日志或用户反馈里出现 `Resource load failed`：只说明某个资源没加载到，是结果不是原因，先按上面几条定位是哪一侧
+
+**确认挂死才重启**（日志无报错、现象持续、`/dev/health` 不是 `backend_failed`）：
+
+- 只重启一侧：`pkill -f "npm run dev:server"` 或 `pkill -f "npm run dev:client"`，另一侧不受影响
+- 两侧都异常：`pkill -f "npm run dev"`，整体由平台重新拉起
+
+**重启后验证**：`/dev/health` 回到 `ready` → 接口测试工具打一个关键 `/api` → 截图工具看页面。同一现象重启一次后仍复现就不是挂死：停止重启，回到日志找根因。
 
 ---
 
@@ -734,6 +753,16 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 - SelectItem 的 value 禁止空值，占位用 `<SelectValue placeholder="..." />`
 - 版本锁定、按需导入、唯一图标库 lucide-react
 
+### 无障碍：控件名字与状态
+
+读屏和自动化验收都靠控件的名字和状态找控件、核对结果，样式和图标它们看不见。表单字段见 `forms-skill`，其余控件按下面写：
+
+- 纯图标按钮必须加 `aria-label`，写清动作：`<Button size="icon" aria-label="返回"><ArrowLeft /></Button>`
+- 能点的东西用 `Button` 或 `Link`，不要给 `div`、`Card`、表格行加 `onClick`；整行可点的列表把行里的主标题做成 `Link`，或给行加 `aria-label`
+- 可选中、可切换的卡片用 `RadioGroup`、`ToggleGroup` 或 `Checkbox` 表达选中态；自己写时加 `role="radio"` + `aria-checked` 或 `aria-pressed`。不要只靠边框、颜色、阴影表达选中
+- 图片 `alt` 要能区分同类项（`` alt={`海报方案 ${index + 1}`} ``），纯装饰图写 `alt=""`
+- 列表项里的勾选框加 `aria-label`，带上这一项的名字：`` aria-label={`选择 ${file.name}`} ``
+
 ## @lark-apaas/client-toolkit
 
 **零假设原则**：绝不基于假设使用任何子模块。使用任何 `@lark-apaas/client-toolkit` 子模块前**必须**：① 查询 Skills 或 `steering_doc_search` → ② 等待响应获取文档 → ③ 严格按文档编码。**禁止直接调用 `@lark-apaas/client-toolkit` 任何函数/方法**（不基于查询到的文档）。该库是**前端/浏览器侧 SDK**，仅可在 `client/**`、React 组件、hooks、前端工具函数中使用；**禁止在 `server/**`、NestJS controller/service/module、Node.js runtime、migration、script 中 import 或调用**。
@@ -867,7 +896,7 @@ return <h1>{data?.title || '未知标题'}</h1>;
 | 验证 | zod |
 | 工具函数 | lodash |
 | 样式 | clsx |
-| 用户反馈 | sonner |
+| 用户反馈 | sonner（只用于提交结果、操作反馈；字段校验错误用 FormMessage 显示在字段下方，不用 toast） |
 
 
 ## 滚动分页最佳实践

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

package/steering/nestjs-react-fullstack/skills_common/trigger-guide/SKILL.md

@@ -4,13 +4,17 @@ description: 自动化任务触发器配置与代码开发指南，支持 cron
 steering: true
 steering-topic: trigger_guide
 match-template-name: nestjs-react-fullstack
+gate-tools:
+  - tool: automation_trigger_manager
 ---
 
 ## 自动化任务配置与代码编写指引
 
 ### 自动化任务配置
 
-1. 新建自动化任务触发器时无需 enable（激活），将任务创建好然后开发完代码即可。触发器随后交由用户主动操作、要求开始。
+1. `CREATE` 创建的触发器默认是 `inactive`，创建成功不代表任务已经运行。
+2. 用户明确要求任务运行，且代码、发布、权限与接收端均已就绪时，必须对同一个触发器执行 `ENABLE`，随后执行 `GET` 并确认 `Active=true`；未读回成功不得宣告任务已运行或交付完成。
+3. 用户只要求准备任务或运行意图不明确时，保持 `inactive`，并明确告知用户任务尚未运行。
 
 ### 目录结构
 

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

@@ -567,6 +567,16 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 - SelectItem 的 value 禁止空值，占位用 `<SelectValue placeholder="..." />`
 - 版本锁定、按需导入、唯一图标库 lucide-react
 
+### 无障碍：控件名字与状态
+
+读屏和自动化验收都靠控件的名字和状态找控件、核对结果，样式和图标它们看不见。表单字段见 `forms-skill`，其余控件按下面写：
+
+- 纯图标按钮必须加 `aria-label`，写清动作：`<Button size="icon" aria-label="返回"><ArrowLeft /></Button>`
+- 能点的东西用 `Button` 或 `Link`，不要给 `div`、`Card`、表格行加 `onClick`；整行可点的列表把行里的主标题做成 `Link`，或给行加 `aria-label`
+- 可选中、可切换的卡片用 `RadioGroup`、`ToggleGroup` 或 `Checkbox` 表达选中态；自己写时加 `role="radio"` + `aria-checked` 或 `aria-pressed`。不要只靠边框、颜色、阴影表达选中
+- 图片 `alt` 要能区分同类项（`` alt={`海报方案 ${index + 1}`} ``），纯装饰图写 `alt=""`
+- 列表项里的勾选框加 `aria-label`，带上这一项的名字：`` aria-label={`选择 ${file.name}`} ``
+
 ## @lark-apaas/client-toolkit
 
 **零假设原则**：绝不基于假设使用任何子模块。使用任何 `@lark-apaas/client-toolkit` 子模块前**必须**：① 先查询本地已加载的 Skills 或对应包文档 → ② 严格按文档编码。**禁止直接调用 `@lark-apaas/client-toolkit` 任何函数/方法**（不基于查询到的文档）。该库**仅可在前端代码中使用，禁止在后端代码中引用**。
@@ -690,7 +700,7 @@ return <h1>{data?.title || '未知标题'}</h1>;
 | 验证       | zod                                                                      |
 | 工具函数   | lodash                                                                   |
 | 样式       | clsx                                                                     |
-| 用户反馈   | sonner                                                                   |
+| 用户反馈   | sonner（只用于提交结果、操作反馈；字段校验错误用 FormMessage 显示在字段下方，不用 toast） |
 
 
 ## 滚动分页最佳实践