yinjianm
30c2f655e7
统一将节点编辑和批量修改的 group_ids、route_ids 序列化为字符串 ID，避免保存权限组后订阅侧无法命中节点 后端新增 whereGroupId 兼容历史字符串与数字 JSON 值， 并补齐 TUIC 版本、ALPN 选项及 AnyTLS 默认 Padding 配置 docs: 新增 HelloAGENTS 通用与工作流避坑指南
343 lines
10 KiB
Markdown
343 lines
10 KiB
Markdown
# 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 安全命令模板沉淀为项目级约定，减少路径和编码风险。
|