diff --git a/docs/help-code01.md b/docs/help-code01.md new file mode 100644 index 0000000..e16d631 --- /dev/null +++ b/docs/help-code01.md @@ -0,0 +1,353 @@ +# Help Code01:Aider 补充 Page Data 简单系统开发方案 + +> 文档版本:2026-07-23 +> 状态:方案设计(未实施) +> 目标:用 **Aider** 在 Goose 主路径之外,补充 Page Data 简单系统在**开发/调试**阶段的修 bug 与测试回归;**不替代 Goose**,不替代 `page-data-collect` skill。 + +--- + +## 1. 背景与目标 + +### 1.1 现状 + +Memind 的 Page Data 主路径由 **Goose + `page-data-collect` skill + sandbox-fs MCP** 完成: + +```text +load_skill(page-data-collect) + → private_data_execute(建表) + → private_data_register_dataset(注册 dataset) + → write_file(survey.html + admin.html) + → private_data_bind_workspace_page(发布 + 策略) +``` + +**Aider / OpenHands** 当前仅在 `toolMode='code'` 的显式代码任务中作为外部执行器,**不参与** Page Data 创建与日常 H5 聊天。 + +### 1.2 痛点 + +简单 Page Data 系统(问卷、台账、小后台)在 Goose 搭完骨架后,开发阶段常见: + +- HTML 字段名与 dataset 列不一致 → insert 403 +- `page-data-client.js` 用法错误 +- policy 白名单未更新(bind 失败或漏列) +- admin 页读不到数据 +- 改完不确定是否回归通过 + +重新走聊天让 Goose 修,成本高、周期长。 + +### 1.3 目标 + +引入 **Aider 作为 L2 开发兜底**: + +| 阶段 | 执行者 | +|------|--------| +| **创建** | Goose + `page-data-collect`(不变) | +| **测试** | 现有 verify / scenario 脚本(不变) | +| **修 bug** | Aider(新增,仅 dev/staging) | +| **改表 / 重新 bind** | Goose 或运维脚本(Aider 不主责) | + +--- + +## 2. 设计原则 + +1. **不替代 Goose**:Page Data 首次建表、注册、bind 仍走 MCP 主路径。 +2. **测试驱动**:Aider 修复必须以 verify 脚本失败输出为依据,禁止无验收的盲改。 +3. **cwd 隔离**:用户 workspace 与 Memind 平台源码分开,不可混跑。 +4. **dev 优先**:生产环境默认不自动触发 Aider Page Data 修复;需白名单与 code run 灰度。 +5. **简单系统用 Aider**:复杂多文件改造才考虑 OpenHands,本方案默认 `executor=aider`。 + +--- + +## 3. 三层架构 + +```mermaid +flowchart LR + A[Goose page-data-collect] --> B[产物: HTML + PG表 + policy] + B --> C[npm verify / 场景脚本] + C -->|失败| D[Aider code run] + D --> E[改 workspace 内文件] + E --> C + C -->|通过| F[交付] +``` + +### 3.1 L0 — 创建(Goose,不变) + +- Skill:`skills/page-data-collect/SKILL.md` +- MCP:`mindspace-sandbox-mcp.mjs`(`private_data_*` + `write_file` / `edit_file`) +- 守卫:`mindspace-page-data-finish-guard.mjs`、交付 sync + +### 3.2 L1 — 测试(平台脚本,不变) + +| 命令 | 用途 | +|------|------| +| `npm run verify:page-data` | Page Data 平台单测与集成测 | +| `npm run verify:children-hobby-diet-survey` | 问卷链路产物验证(~5s) | +| `npm run test:scenario:john4-diet` | 全链路 E2E(含 Agent 聊天,~3–10min) | +| `npm run verify:page-data-delivery` | 绑定/delivery dry-run | +| `npm run repair:page-data-bindings` | 修复 workspace bind | + +参考:`.claude/skills/memind-page-data-survey-verify/SKILL.md` + +### 3.3 L2 — 修 bug(Aider,本方案新增) + +- 入口:`toolMode='code'`,`executor='aider'`,建议 `taskType='page_data_dev'` +- cwd:用户 workspace(`resolveWorkingDir(userId)`)或 Memind 仓库(平台开发) +- 输入:verify 失败输出 + 目标文件路径 + Page Data 约束摘要 +- 输出:修改后的 HTML / policy JSON;可选 receipt +- 验收:重跑 L1 verify 直至通过 + +--- + +## 4. Aider 能力边界 + +### 4.1 ✅ 适合修复 + +| 问题类型 | 可改路径 | +|----------|----------| +| HTML 字段与 dataset 列不一致 | `public/*-survey.html`、`public/*-admin.html` | +| `page-data-client.js` API 误用 | 同上 | +| policy insert/read 白名单错误 | `.mindspace/page-data-policies/{pageId}.json` | +| CSP / 脚本路径 / 同源约束 | `public/assets/`、`public/*.html` | +| 提交后 UI 无反馈 | HTML 内 JS | + +### 4.2 ⚠️ 需配合脚本或 Goose + +| 问题 | 推荐做法 | +|------|----------| +| PG 表缺列 | Goose 重新 `private_data_execute`,或运维 SQL | +| dataset 未注册 | `scripts/ensure-page-data-datasets.mjs` | +| bind 丢失 | `npm run repair:page-data-bindings` | +| 策略索引不同步 | `page-data-policy-index` 相关 repair | + +### 4.3 ❌ 不交给 Aider + +| 问题 | 原因 | +|------|------| +| 首次建表 + register + bind | 无 `private_data_*` MCP | +| 替代 Goose 做页面生成 | 缺 skill、finish sync、交付守卫 | +| 生产环境无人值守自动改码 | 风险高,需严格灰度 | + +--- + +## 5. 两种开发场景 + +### 5.1 场景 A:用户 workspace 里的 Page Data 小系统 + +**典型产物:** + +```text +MindSpace/{userId}/ + public/my-survey.html + public/my-admin.html + .mindspace/page-data-policies/{pageId}.json +``` + +**Aider 配置:** + +| 项 | 值 | +|----|-----| +| cwd | `MindSpace/{userId}/` | +| executor | `aider` | +| taskType | `page_data_dev`(建议新增)或 `page_edit_code_task` | +| validation | `expectedFiles`: 目标 `public/*.html` | + +**测试裁判:** 问卷专用 verify 或自定义 `scripts/verify-*.mjs` + +### 5.2 场景 B:Memind 平台 Page Data 模块开发 + +**典型修改:** + +- `page-data-service.mjs`、`page-data-public-service.mjs` +- `mindspace-page-data-finish-guard.mjs` +- `public/assets/page-data-client.js` + +**Aider 配置:** + +| 项 | 值 | +|----|-----| +| cwd | `/Users/john/Project/Memind`(或 CI checkout 路径) | +| executor | `aider` | +| taskType | `h5_chat_code_task` 或专用 `page_data_platform_dev` | +| validation | receipt + 单测通过 | + +**测试裁判:** `npm run verify:page-data` + +> **禁止**在同一次 Aider run 中混用场景 A 与 B 的 cwd。 + +--- + +## 6. 开发闭环操作手册 + +### 6.1 前置:本地开启 code run(仅 dev) + +```bash +# .env 示例(开发机) +MEMIND_AGENT_CODE_RUNS_ENABLED=1 +MEMIND_TOOL_GATEWAY_ENABLED=1 +MEMIND_TOOL_GATEWAY_DEFAULT_EXECUTOR=aider + +# 前端 build 时需注入(若走 H5 触发) +VITE_AGENT_CODE_RUNS_ENABLED=1 +VITE_AGENT_CODE_RUNS_USER_IDS= # 或留空表示全用户(仅 dev) +``` + +还需: + +- DB `h5_capability_grants`:目标用户 `aider=true` +- `h5_llm_executor_bindings`:aider 有 enabled 的 provider/model +- Portal 或 external worker 之一启用 Tool Gateway(本地 dev 可 Portal 直开) + +### 6.2 标准循环 + +```bash +# 1. 确认 Portal +curl -sf http://127.0.0.1:8081/auth/status + +# 2. Goose 已建好 Page Data 系统(聊天或 scenario) + +# 3. 跑验证 +npm run verify:children-hobby-diet-survey +# 或 +npm run verify:page-data + +# 4. 若失败 → 触发 Aider(H5 / agent-run / 独立脚本) +# instruction 必须包含完整 verify 失败输出 + +# 5. Aider 改完 → 回到步骤 3,直至全绿 +``` + +### 6.3 H5 触发话术示例 + +- 「问卷 submit 403,列 q4_diet_meals 不允许,请根据 verify 结果修 HTML 和 policy」 +- 「Page Data admin 页读不到数据,测试脚本报 policy read 未开启」 +- 「修 page-data 简单系统的 bug,不要改表,只改 public HTML」 + +### 6.4 Aider instruction 模板 + +```text +[Page Data 开发修复任务] + +工作目录: MindSpace/{userId}/ +taskType: page_data_dev + +验证失败输出(必须原样附上): + + +目标文件(仅可改这些): +- public/{survey}.html +- public/{admin}.html +- .mindspace/page-data-policies/{pageId}.json + +约束: +- 必须使用 /assets/page-data-client.js 公开 API +- 禁止 localStorage / sessionStorage / IndexedDB +- 禁止自建 Express 或独立后端 +- 列名必须与 dataset register 的 insert/read 白名单一致 +- 不要修改 Memind 平台源码 + +验收: +- 修改后应能通过: npm run verify:children-hobby-diet-survey +- 或: node scripts/verify-.mjs +``` + +--- + +## 7. 与现有 Memind 架构的集成点 + +### 7.1 现有组件(复用,不重写) + +| 组件 | 路径 | 角色 | +|------|------|------| +| Agent Run 队列 | `agent-run-gateway.mjs` | code run 调度 | +| Tool Gateway | `tool-gateway.mjs` | spawn Aider | +| Launch Plan | `llm-providers.mjs` | `aider --message ... --yes-always` | +| 前端 code 检测 | `src/utils/agentRunMode.ts` | `toolMode:'code'` | +| 能力门禁 | `capabilities.mjs` | code mode 才注入 aider | +| Page Data 路由 | `page-data-routes.mjs` | 运行时 API(Aider 不直接调,HTML 调) | + +### 7.2 建议新增(实施阶段) + +| 项 | 说明 | 优先级 | +|----|------|--------| +| `taskType: page_data_dev` | router / autodetect 识别「修 page data bug」 | P1 | +| chat-intent-router 规则 | 「修问卷/测试没过/page data bug」→ code run | P1 | +| `buildAgentRunTaskValidation` 扩展 | page_data_dev 的 expectedFiles + receipt | P2 | +| 独立 dev 脚本 | 仓库外或 `scripts/page-data-aider-dev-loop.mjs`:verify → aider → verify | P2 | +| 文档索引 | 在 `docs/regression-guards/` 或 AGENTS.md 加链接 | P3 | + +### 7.3 不建议的做法 + +- 用 Aider/OpenHands **替代** Goose 做 Page Data 创建 +- 用 `page-data-collect` skill 充当通用 code executor +- 生产默认全开 `MEMIND_AGENT_CODE_RUNS_ENABLED` 给所有用户 +- 无 verify 输出让 Aider 盲改 workspace + +--- + +## 8. 与 OpenHands / Cursor 的关系 + +| 引擎 | 本方案中的角色 | +|------|----------------| +| **Goose** | L0 创建(主路径,不变) | +| **Aider** | L2 简单 Page Data dev 修 bug(**本方案核心**) | +| **OpenHands** | 可选 L3:Aider 失败且涉及多文件/复杂 repo 时再 escalation | +| **Cursor SDK** | 非必需;仅 Memind 平台源码开发或 IDE 级工具时可选用 | + +OpenHands 任务类型保持现有 `repo_refactor,multi_file,complex_repo`;**不必**为 Page Data 简单 HTML bug 默认走 OpenHands。 + +--- + +## 9. 风险与运维 + +| 风险 | 缓解 | +|------|------| +| Aider 误改非目标文件 | validation `expectedFiles` + cwd 沙箱 + prompt 白名单 | +| 表结构问题被误当 HTML bug | verify 区分 `columns_not_allowed` vs `table_not_found`;后者回 Goose | +| code run 孤儿化导致 H5 loading | verify 脚本检查 orphan running;`--no-runs` 可选 | +| 生产误触发 | 生产 `MEMIND_AGENT_CODE_RUNS_ENABLED=0` 或严格 user allowlist | +| PG 连接失败 | fail closed(skill 已有);Aider 不得「先写 HTML 等 PG 恢复」 | + +--- + +## 10. 实施路线图 + +### Phase 0 — 文档与手动流程(当前) + +- [x] 本方案文档 `docs/help-code01.md` +- [ ] 开发者在本地手动:verify 失败 → 复制输出 → H5/code run 触发 Aider → 再 verify + +### Phase 1 — 最小 Memind 改动 + +- [ ] 新增 `page_data_dev` taskType +- [ ] `chat-intent-router` 增加 Page Data 修 bug 意图 +- [ ] `agentRunMode.ts` 可选 autodetect 模式(dev only) + +### Phase 2 — 自动化 dev loop + +- [ ] `scripts/page-data-aider-dev-loop.mjs`:读 verify 输出 → 调 Tool Gateway/Aider → 重跑 verify +- [ ] 接入 CI optional job(仅 staging) + +### Phase 3 — 可选 escalation + +- [ ] Aider 连续 N 次 verify 失败 → 升级 OpenHands(`taskType=page_data_dev_complex`) +- [ ] 运维面板展示 page_data_dev run 历史 + +--- + +## 11. 相关文档与命令速查 + +| 资源 | 路径 / 命令 | +|------|-------------| +| Page Data API 用法 | `docs/page-data-api-usage.md` | +| page-data-collect skill | `skills/page-data-collect/SKILL.md` | +| 问卷 verify skill | `.claude/skills/memind-page-data-survey-verify/SKILL.md` | +| Tool Gateway 架构 | `docs/architecture/memind-2-streaming-agent-runtime-plan.md` | +| Agent run worker | `docs/agent-run-worker-rollout-runbook.md` | +| `npm run verify:page-data` | Page Data 平台测试 | +| `npm run verify:children-hobby-diet-survey` | 问卷产物验证 | +| `npm run repair:page-data-bindings` | 修复 bind | + +--- + +## 12. 一句话总结 + +**Goose 负责把 Page Data 简单系统「建起来」;现有 verify 脚本负责「验对不对」;Aider 负责开发阶段「根据测试结果改 HTML/policy 修 bug」——三者串联,不替代 Goose 主路径。**