fix(admin-frontend): 修复节点权限组保存与协议默认值

统一将节点编辑和批量修改的 group_ids、route_ids 序列化为字符串 ID，避免保存权限组后订阅侧无法命中节点后端新增 whereGroupId 兼容历史字符串与数字 JSON 值，并补齐 TUIC 版本、ALPN 选项及 AnyTLS 默认 Padding 配置 docs: 新增 HelloAGENTS 通用与工作流避坑指南
2026-04-27 23:03:57 +08:00
parent c64badfc23
commit 30c2f655e7
16 changed files with 1096 additions and 33 deletions
@@ -0,0 +1,342 @@
+# HelloAGENTS 工作流踩坑复盘
+
+## 适用范围
+
+本文记录本轮在 `E:\code\php\Xboard-new` 中调用 HelloAGENTS Standby 工作流时踩到的坑，适用于后续在 Windows + PowerShell + 已激活 `.helloagents/` 项目中执行编码、验证、文档沉淀和收尾任务。
+
+## 总原则
+
+1. 当前用户消息优先于旧状态文件。
+2. 代码和真实命令输出优先于记忆、文档和推断。
+3. 工具失败必须记录为验证结论或阻断项，不能静默跳过。
+4. `output_format=true` 时，只在最后一条收尾消息使用 HelloAGENTS 输出格式。
+5. 涉及 `public/assets/admin` 时，必须同时看根仓和子模块状态。
+
+## 坑点清单
+
+### 1. `scripts/turn-state.mjs` 被协议要求，但项目中不存在
+
+**表现**
+
+- 收尾协议要求先执行 `scripts/turn-state.mjs write`。
+- 实际执行 `node "scripts\turn-state.mjs" write kind=complete role=main` 时失败：
+  - `Cannot find module 'E:\code\php\Xboard-new\scripts\turn-state.mjs'`
+- 仓库根目录也没有 `scripts/` 目录。
+
+**根因**
+
+HelloAGENTS 协议假设存在统一的 turn-state 脚本，但当前项目和全局运行目录没有提供该脚本。
+
+**正确处理**
+
+- 收尾前按协议尝试一次。
+- 若脚本不存在，明确记录失败原因。
+- 不要反复重试同一个不存在的路径。
+- 不要因为脚本失败而伪装成 turn-state 已写入。
+- 用项目状态文件 `.helloagents/sessions/master/default/STATE.md` 补充记录当前任务状态。
+
+**下次规则**
+
+如果仓库仍没有 `scripts/turn-state.mjs`：
+
+```powershell
+node "scripts\turn-state.mjs" write kind=complete role=main
+```
+
+失败后只记录一次：
+
+> turn-state 脚本缺失，无法写入运行态信号；已更新 `.helloagents/.../STATE.md` 作为恢复状态。
+
+### 2. 旧 `STATE.md` 容易把新任务带偏
+
+**表现**
+
+进入本轮时，状态文件仍记录上一个“用户管理高级筛选活跃状态”任务，而用户实际要求是修复节点 TUIC 和权限组问题。
+
+**根因**
+
+`.helloagents/sessions/master/default/STATE.md` 是恢复参考，不是当前任务真相源。若直接按旧状态续作，会进入错误业务线。
+
+**正确处理**
+
+- 先读当前用户消息。
+- 再看活跃方案包、代码、验证证据。
+- 最后才用 `STATE.md` 补上下文。
+- 确认是新任务后，立即重写 `STATE.md`，不要等到收尾。
+
+**下次规则**
+
+判断主线优先级固定为：
+
+1. 当前用户最新消息。
+2. 本轮确认的范围。
+3. 当前代码与验证证据。
+4. 活跃方案包。
+5. `STATE.md`。
+
+### 3. 输出格式只能用于最后一条消息
+
+**表现**
+
+配置中 `output_format=true`，但工具执行前、执行中、阻塞说明都不能使用 HelloAGENTS 外层格式。
+
+**根因**
+
+输出格式只允许用于本轮最终收尾消息。中间消息如果套格式，会让运行时误判任务完成或等待输入。
+
+**正确处理**
+
+- 中间状态用自然语言或工具计划，不使用 `{图标}【HelloAGENTS】`。
+- 确认不再调用工具后，再使用最终格式。
+- 如果使用了记忆引用，记忆引用块必须放在最终回复最末尾。
+
+**下次规则**
+
+只在满足以下条件时使用 HelloAGENTS 输出格式：
+
+- 不再调用工具。
+- 不再继续执行。
+- 已完成或已明确阻塞。
+- 已尝试写 turn-state，或明确记录脚本缺失。
+
+### 4. `.helloagents/` 不是随便放文件的目录
+
+**表现**
+
+用户要求“提炼成一个 md 文档”，直觉上可以放到 `.helloagents/`，但协议要求 `.helloagents/` 内文件创建和更新必须遵循模板。
+
+**根因**
+
+`.helloagents/` 是运行态和知识库目录，部分文件有固定模板和生命周期；随意新增文档可能破坏流程约定。
+
+**正确处理**
+
+- 临时复盘、交付文档优先放到 `docs/`。
+- 只有状态、方案、知识库、归档等 HelloAGENTS 定义文件才放入 `.helloagents/`。
+- 更新 `.helloagents/CHANGELOG.md`、`modules/*.md` 时保持既有格式。
+
+**下次规则**
+
+用户要普通 Markdown 成品时，默认使用：
+
+```text
+docs/<topic>.md
+```
+
+除非用户明确要求放进 `.helloagents/`。
+
+### 5. 容易把快速修复膨胀成完整方案包
+
+**表现**
+
+节点权限组和 TUIC 模板是明确小范围修复，容易因为项目已激活而误判为必须创建完整 `plans/{feature}/`。
+
+**根因**
+
+HelloAGENTS 有 T0-T3 交付分层，但不是所有激活项目任务都必须走完整方案包。明确、低风险、小范围、可验证的变更可按 T1 快速执行。
+
+**正确处理**
+
+- 先判断任务复杂度。
+- 明确 bugfix 可以直接修，不用额外确认。
+- 无独立方案包时，在 `CHANGELOG.md` 标记“快速修改（无方案包）”。
+
+**下次规则**
+
+符合以下条件时走快速修改：
+
+- 用户描述了具体故障或具体页面。
+- 改动范围可限定在少量文件。
+- 不涉及生产高风险操作。
+- 可用本地构建或静态检查验证。
+
+### 6. 记忆可辅助定位，但不能替代当前证据
+
+**表现**
+
+记忆中已有 Xboard-new、`admin-frontend`、`public/assets/admin` 子模块等经验，能快速提醒验证路径和历史坑。
+
+**风险**
+
+记忆可能过期。直接把记忆当作当前事实，会漏掉分支、远端、目录结构变化。
+
+**正确处理**
+
+- 先用记忆找关键词和历史坑。
+- 再用当前命令验证：
+  - `git status`
+  - `npm run build`
+  - 子模块状态
+  - 目标文件实际内容
+- 最终报告区分“已验证”和“记忆提示”。
+
+**下次规则**
+
+记忆只能回答“应该重点看哪里”，不能回答“当前一定是什么状态”。
+
+### 7. `public/assets/admin` 是子模块，根仓状态不等于真实前端产物状态
+
+**表现**
+
+执行 `npm run build` 后，根仓只显示：
+
+```text
+m public/assets/admin
+```
+
+这不是“没改到”，而是子模块内部产物发生变化。
+
+**额外坑**
+
+进入子模块执行 `git status` 时出现：
+
+```text
+fatal: detected dubious ownership in repository at 'E:/code/php/Xboard-new/public/assets/admin'
+```
+
+**正确处理**
+
+使用单次 scoped safe directory，不要默认改全局配置：
+
+```powershell
+git -c safe.directory="E:/code/php/Xboard-new/public/assets/admin" -C "E:\code\php\Xboard-new\public\assets\admin" status --short --branch
+```
+
+**下次规则**
+
+涉及管理端构建产物时必须给两层证据：
+
+1. 根仓：源码文件变更 + `m public/assets/admin`。
+2. 子模块：产物文件状态或关键词检索结果。
+
+### 8. Windows + PowerShell 下不能偷懒写命令
+
+**表现**
+
+当前环境是 PowerShell，路径包含盘符和反斜杠。命令如果不加引号，容易因为空格、中文或特殊字符导致路径错误。
+
+**正确处理**
+
+- 所有路径用双引号。
+- 不用 `cmd /c`。
+- 多路径操作拆成多条命令。
+- 文件修改优先用 `apply_patch`，避免 shell 重定向和编码问题。
+
+**下次规则**
+
+推荐命令形态：
+
+```powershell
+git -C "E:\code\php\Xboard-new" status --short
+npm run build
+```
+
+不推荐：
+
+```powershell
+cmd /c ...
+```
+
+### 9. 验证阻断要写清楚，不能把未跑的检查说成通过
+
+**表现**
+
+前端可执行：
+
+```powershell
+npm run build
+```
+
+并已通过。
+
+但 PHP 环境不可用：
+
+```powershell
+php -v
+```
+
+返回 `php` 命令不存在。
+
+**正确处理**
+
+- 前端构建通过就只声明前端构建通过。
+- PHP 语法检查 / PHPUnit 未执行，原因写成阻断。
+- 不用“应该没问题”代替验证结果。
+
+**下次规则**
+
+验证结果分三类写：
+
+- 通过：命令执行成功。
+- 失败：命令执行但返回错误。
+- 未执行：缺少运行时、凭据、服务或外部依赖。
+
+### 10. 工具输出需要审查，不要被外部内容带节奏
+
+**表现**
+
+搜索、构建、Git 输出中会混入大量无关内容，例如 `node_modules`、编译产物、历史 bundle。
+
+**风险**
+
+直接根据长输出行动，容易误改生成文件或误判业务源码。
+
+**正确处理**
+
+- 优先限定路径：
+  - `admin-frontend/src/...`
+  - `app/...`
+  - `.helloagents/...`
+- 避免全仓递归搜索进入 `node_modules` 或大型 bundle。
+- 对长输出只提取任务相关结论。
+
+**下次规则**
+
+检索优先使用：
+
+```powershell
+rg -n --glob "*.php" --glob "!vendor/**" "keyword" "E:\code\php\Xboard-new\app"
+```
+
+而不是不加过滤地全仓搜索。
+
+## 标准执行清单
+
+### 开始任务
+
+- [ ] 判断用户最新消息是否是新任务。
+- [ ] 若项目已激活，读取当前 `STATE.md`，但不让旧状态覆盖新需求。
+- [ ] 判断交付层级：快速修复、完整方案、只读分析或高风险操作。
+- [ ] 若需要记忆，先快速检索，再用当前文件验证。
+
+### 执行中
+
+- [ ] 路径全部加双引号。
+- [ ] 修改源码优先用 `apply_patch`。
+- [ ] 不把普通文档随意放入 `.helloagents/`。
+- [ ] 涉及 UI 时遵守当前 Apple 风格设计契约。
+- [ ] 涉及 `public/assets/admin` 时记住它是子模块。
+
+### 验证
+
+- [ ] 能跑的命令必须跑。
+- [ ] 不能跑的命令写明原因。
+- [ ] `npm run build` 只证明前端构建通过。
+- [ ] PHP 缺失时不能声称后端 PHPUnit 或语法检查通过。
+- [ ] `git diff --check` 可作为基础格式检查。
+
+### 收尾
+
+- [ ] 更新 `STATE.md` 到下一轮可恢复状态。
+- [ ] 有必要时更新 `CHANGELOG.md` 和模块知识。
+- [ ] 尝试执行 `scripts/turn-state.mjs write`。
+- [ ] 若 turn-state 脚本缺失，明确说明。
+- [ ] 最后一条回复才使用 HelloAGENTS 输出格式。
+
+## 本轮改进建议
+
+1. 项目初始化时补齐 `scripts/turn-state.mjs`，或在协议中定义缺失时的标准 fallback。
+2. 为 `public/assets/admin` 子模块提供固定的本地 safe.directory 说明，减少每轮踩同一个 Git 安全检查。
+3. 在 `.helloagents/verify.yaml` 中区分前端、后端、子模块验证命令，避免只剩单一 `npm run build`。
+4. 给“快速修改（无方案包）”建立轻量记录模板，避免每次临时判断写法不一致。
+5. 将 Windows PowerShell 安全命令模板沉淀为项目级约定，减少路径和编码风险。