yinjianm
30c2f655e7
统一将节点编辑和批量修改的 group_ids、route_ids 序列化为字符串 ID，避免保存权限组后订阅侧无法命中节点 后端新增 whereGroupId 兼容历史字符串与数字 JSON 值， 并补齐 TUIC 版本、ALPN 选项及 AnyTLS 默认 Padding 配置 docs: 新增 HelloAGENTS 通用与工作流避坑指南
10 KiB
HelloAGENTS 工作流踩坑复盘
适用范围
本文记录本轮在 E:\code\php\Xboard-new 中调用 HelloAGENTS Standby 工作流时踩到的坑，适用于后续在 Windows + PowerShell + 已激活 .helloagents/ 项目中执行编码、验证、文档沉淀和收尾任务。
总原则
- 当前用户消息优先于旧状态文件。
- 代码和真实命令输出优先于记忆、文档和推断。
- 工具失败必须记录为验证结论或阻断项，不能静默跳过。
output_format=true时，只在最后一条收尾消息使用 HelloAGENTS 输出格式。- 涉及
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：
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，不要等到收尾。
下次规则
判断主线优先级固定为：
- 当前用户最新消息。
- 本轮确认的范围。
- 当前代码与验证证据。
- 活跃方案包。
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 成品时，默认使用：
docs/<topic>.md
除非用户明确要求放进 .helloagents/。
5. 容易把快速修复膨胀成完整方案包
表现
节点权限组和 TUIC 模板是明确小范围修复，容易因为项目已激活而误判为必须创建完整 plans/{feature}/。
根因
HelloAGENTS 有 T0-T3 交付分层，但不是所有激活项目任务都必须走完整方案包。明确、低风险、小范围、可验证的变更可按 T1 快速执行。
正确处理
- 先判断任务复杂度。
- 明确 bugfix 可以直接修，不用额外确认。
- 无独立方案包时，在
CHANGELOG.md标记“快速修改（无方案包）”。
下次规则
符合以下条件时走快速修改：
- 用户描述了具体故障或具体页面。
- 改动范围可限定在少量文件。
- 不涉及生产高风险操作。
- 可用本地构建或静态检查验证。
6. 记忆可辅助定位，但不能替代当前证据
表现
记忆中已有 Xboard-new、admin-frontend、public/assets/admin 子模块等经验，能快速提醒验证路径和历史坑。
风险
记忆可能过期。直接把记忆当作当前事实，会漏掉分支、远端、目录结构变化。
正确处理
- 先用记忆找关键词和历史坑。
- 再用当前命令验证：
git statusnpm run build- 子模块状态
- 目标文件实际内容
- 最终报告区分“已验证”和“记忆提示”。
下次规则
记忆只能回答“应该重点看哪里”，不能回答“当前一定是什么状态”。
7. public/assets/admin 是子模块，根仓状态不等于真实前端产物状态
表现
执行 npm run build 后，根仓只显示：
m public/assets/admin
这不是“没改到”，而是子模块内部产物发生变化。
额外坑
进入子模块执行 git status 时出现：
fatal: detected dubious ownership in repository at 'E:/code/php/Xboard-new/public/assets/admin'
正确处理
使用单次 scoped safe directory，不要默认改全局配置：
git -c safe.directory="E:/code/php/Xboard-new/public/assets/admin" -C "E:\code\php\Xboard-new\public\assets\admin" status --short --branch
下次规则
涉及管理端构建产物时必须给两层证据：
- 根仓：源码文件变更 +
m public/assets/admin。 - 子模块：产物文件状态或关键词检索结果。
8. Windows + PowerShell 下不能偷懒写命令
表现
当前环境是 PowerShell，路径包含盘符和反斜杠。命令如果不加引号，容易因为空格、中文或特殊字符导致路径错误。
正确处理
- 所有路径用双引号。
- 不用
cmd /c。 - 多路径操作拆成多条命令。
- 文件修改优先用
apply_patch，避免 shell 重定向和编码问题。
下次规则
推荐命令形态：
git -C "E:\code\php\Xboard-new" status --short
npm run build
不推荐：
cmd /c ...
9. 验证阻断要写清楚，不能把未跑的检查说成通过
表现
前端可执行：
npm run build
并已通过。
但 PHP 环境不可用：
php -v
返回 php 命令不存在。
正确处理
- 前端构建通过就只声明前端构建通过。
- PHP 语法检查 / PHPUnit 未执行，原因写成阻断。
- 不用“应该没问题”代替验证结果。
下次规则
验证结果分三类写：
- 通过：命令执行成功。
- 失败：命令执行但返回错误。
- 未执行：缺少运行时、凭据、服务或外部依赖。
10. 工具输出需要审查，不要被外部内容带节奏
表现
搜索、构建、Git 输出中会混入大量无关内容，例如 node_modules、编译产物、历史 bundle。
风险
直接根据长输出行动，容易误改生成文件或误判业务源码。
正确处理
- 优先限定路径：
admin-frontend/src/...app/....helloagents/...
- 避免全仓递归搜索进入
node_modules或大型 bundle。 - 对长输出只提取任务相关结论。
下次规则
检索优先使用：
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 输出格式。
本轮改进建议
- 项目初始化时补齐
scripts/turn-state.mjs，或在协议中定义缺失时的标准 fallback。 - 为
public/assets/admin子模块提供固定的本地 safe.directory 说明，减少每轮踩同一个 Git 安全检查。 - 在
.helloagents/verify.yaml中区分前端、后端、子模块验证命令，避免只剩单一npm run build。 - 给“快速修改（无方案包）”建立轻量记录模板，避免每次临时判断写法不一致。
- 将 Windows PowerShell 安全命令模板沉淀为项目级约定，减少路径和编码风险。