memind/docs/help-code01.md

# Help Code01：Aider 补充 Page Data 简单系统开发方案

> 文档版本：2026-07-23<br>
> 状态：方案设计（未实施）<br>
> 目标：用 **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

> **Phase 1（当前）：** env + VITE，适合本机 dev。<br>
> **Phase 1.5（目标）：** memindadm 配置 + `/auth/status` 下发，见 [help-code02.md](./help-code02.md)。

```bash
# .env 示例（开发机，Phase 1）
MEMIND_AGENT_CODE_RUNS_ENABLED=1
MEMIND_TOOL_GATEWAY_ENABLED=1
MEMIND_TOOL_GATEWAY_DEFAULT_EXECUTOR=aider

VITE_AGENT_CODE_RUNS_ENABLED=1
VITE_AGENT_PAGE_DATA_DEV_AUTODETECT=1
VITE_AGENT_CODE_RUNS_USER_IDS=<dev-user-uuid>   # 或留空表示全用户（仅 dev）
# 可选：MEMIND_AGENT_CODE_RUN_TASK_TYPES=page_data_dev,h5_chat_code_task,...
```

还需：

- 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

验证失败输出（必须原样附上）:
<paste verify script stderr/stdout>

目标文件（仅可改这些）:
- 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-<your-scenario>.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 改动

- [x] 新增 `page_data_dev` taskType
- [x] `chat-intent-router` 增加 Page Data 修 bug 意图
- [x] `agentRunMode.ts` 可选 autodetect 模式（dev only，`VITE_AGENT_PAGE_DATA_DEV_AUTODETECT`）

### Phase 1.5 — memindadm 运行时策略（推荐下一步）

> 详细设计见 **[help-code02.md](./help-code02.md)**。

- [x] `h5_agent_code_run_config` 表 + `agent-code-run-admin-config.mjs`
- [x] memindadm API：`/admin-api/agent-code-run/config`、`/runtime`（UI 表单待做）
- [x] `/auth/status` 下发 `agentCodeRun`，H5 不再依赖 `VITE_*` rebuild
- [x] `agent-run-routes.mjs` 从 DB 读策略（env 仅紧急 override）
- [x] Worker 拓扑（`MEMIND_TOOL_GATEWAY_ENABLED`）继续留 env
- [x] `scripts/migrate-agent-code-run-config-from-env.mjs`

**为何需要 Phase 1.5：** Phase 1 的 env/VITE 适合 dev；要解决「用户经常失败」的运营灰度，必须在 memindadm 按用户/任务类型动态开关，且 H5 需运行时生效。

### Phase 2 — 自动化 dev loop

- [x] `scripts/page-data-aider-dev-loop.mjs`：读 verify 输出 → 调 Tool Gateway/Aider → 重跑 verify
- [x] `npm run dev:page-data-aider-loop` 快捷入口
- [ ] 接入 CI optional job（仅 staging）
- [x] `npm run ci:page-data-dev-loop-smoke`（dry-run 烟测，可挂 CI optional job）

### Phase 3 — 可选 escalation

- [x] Aider 连续 N 次 verify 失败 → 升级 OpenHands（`taskType=page_data_dev_complex`，`--escalate-after`）
- [x] 运维面板展示 page_data_dev run 历史（`/admin-api/agent-code-run/runs` + Ops UI）

---

## 11. 相关文档与命令速查

| 资源 | 路径 / 命令 |
|------|-------------|
| **adm 运行时策略（Phase 1.5）** | `docs/help-code02.md` |
| 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 主路径。**