memind/docs/help-code02.md

Help Code02：Code Run / Page Data Dev 的 memindadm 运行时策略

文档版本：2026-07-23
状态：方案设计（未实施）
前置：help-code01.md（Aider 补充 Page Data 开发兜底）
关联：memindadm-goose-gateway-design.md

---

1. 为什么要做 Phase 1.5

Phase 1 用 env + VITE_ 构建期变量 控制 code run 与 page_data_dev autodetect。这在 dev/staging 可用，但对「用户经常页面失败、插入失败」的运营场景不够：

问题	env/VITE 的局限
改开关要 rebuild H5	VITE_* 打进 bundle，memindadm 点了不生效
改开关要 SSH 改 .env	103 Portal / worker 两套 env，易不一致
无法按用户即时灰度	白名单改 env 无审计、无 UI
与现有 adm 能力分裂	aider 能力已在 h5_capability_grants，策略却在 env

目标： 把 「谁、哪种 task、是否 page_data_dev autodetect」 迁入 memindadm；部署拓扑（worker 是否 spawn Aider）继续留 env。

---

2. 配置分层（硬边界）

flowchart TB
  subgraph adm ["memindadm 运行时策略（DB）"]
    P1[codeRun.enabled]
    P2[userAllowlist / roleAllowlist]
    P3[taskTypeAllowlist 含 page_data_dev]
    P4[pageDataDev.autodetect]
    P5[requireValidation]
    P6[generalCodeAutodetect]
  end

  subgraph env ["部署 env（不改或只读 override）"]
    E1[MEMIND_TOOL_GATEWAY_ENABLED]
    E2[AIDER_BIN / OPENHANDS_BIN]
    E3[worker 并发 / 超时 / guard]
    E4[MEMIND_AGENT_RUN_* 紧急 override]
  end

  subgraph cap ["已有用户能力（DB）"]
    C1[h5_capability_grants: aider/openhands]
    C2[h5_llm_executor_bindings]
  end

  adm --> Portal[agent-run-routes 校验]
  adm --> Auth["/auth/status → H5"]
  cap --> Portal
  env --> Worker[agent-run-worker]
  Portal --> Worker

2.1 进 memindadm 的项

原 env / VITE	adm 字段	说明
MEMIND_AGENT_CODE_RUNS_ENABLED	codeRun.enabled	后端是否接受 tool_mode=code
MEMIND_AGENT_CODE_RUNS_USER_IDS	codeRun.userAllowlist	空 = 不限制（enabled 时）
MEMIND_AGENT_CODE_RUN_TASK_TYPES	codeRun.taskTypeAllowlist	含 page_data_dev、h5_chat_code_task
MEMIND_AGENT_CODE_RUNS_REQUIRE_VALIDATION	codeRun.requireValidation	是否强制 receipt
VITE_AGENT_CODE_RUNS_ENABLED	codeRun.clientEnabled	H5 是否展示/走 code 路径
VITE_AGENT_CODE_RUNS_AUTODETECT	codeRun.generalAutodetect	通用代码语义 autodetect
VITE_AGENT_PAGE_DATA_DEV_AUTODETECT	pageDataDev.autodetect	Page Data 修 bug 专用 autodetect

2.2 继续留 env 的项

env	原因
MEMIND_TOOL_GATEWAY_ENABLED	worker 进程级；Portal 与 worker 故意不同值
MEMIND_TOOL_GATEWAY_DEFAULT_EXECUTOR	机器上装的是 aider 还是 openhands
MEMIND_AGENT_RUN_QUEUE_CONCURRENCY 等	SLO / guard / LaunchAgent
MEMIND_AGENT_CODE_RUNS_*（可选）	紧急 override：MEMIND_CODE_RUN_POLICY_SOURCE=env 时强制 env 优先

---

3. 数据模型

3.1 表：h5_agent_code_run_config

与 h5_skill_runtime_config、h5_image_make_admin_config 同模式：config_scope='global' 单行 JSON。

CREATE TABLE IF NOT EXISTS h5_agent_code_run_config (
  config_scope VARCHAR(32) PRIMARY KEY,
  config_json JSON NOT NULL,
  updated_by CHAR(36) NULL,
  updated_at BIGINT NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

3.2 默认 JSON Schema

{
  "codeRun": {
    "enabled": false,
    "clientEnabled": false,
    "generalAutodetect": false,
    "requireValidation": true,
    "userAllowlist": [],
    "taskTypeAllowlist": [
      "page_data_dev",
      "h5_chat_code_task",
      "page_edit_code_task"
    ]
  },
  "pageDataDev": {
    "autodetect": false
  },
  "meta": {
    "notes": ""
  }
}

3.3 生效优先级（与 Memory V2 adm 一致）

参考 memory-v2-admin-config.mjs 的 FIELD_SPECS + env override 模式：

1. 若 MEMIND_CODE_RUN_POLICY_SOURCE=env → 仅读 env（紧急回滚）
2. 否则读 h5_agent_code_run_config（admin-db）
3. 若表为空且 MEMIND_AGENT_CODE_RUNS_ENABLED=1 → source=env-migration（兼容旧部署）
4. 否则 default（全 false，fail closed）

3.4 用户级能力（不重复造表）

以下 仍用现有表，adm「Code Run 策略」页只读展示 + 链到用户能力编辑：

• h5_capability_grants：aider / openhands
• h5_llm_executor_bindings：Aider 模型绑定
• h5_user_policies：code_delegate_executor、code_task_routing

完整放行条件（与 today 相同，只是策略来源改为 DB）：

codeRun.enabled (adm)
  AND user ∈ allowlist（若配置）
  AND taskType ∈ taskTypeAllowlist
  AND capabilities.aider（用户 grant）
  AND executor binding 可用
  AND（若 requireValidation）message 含 validation metadata
  AND toolGateway.enabled（env，worker 侧）

---

4. 服务模块：agent-code-run-admin-config.mjs

建议新建，API 对齐 skill-runtime-admin-config.mjs：

方法	用途
getAdminConfig()	memindadm 编辑页
updateAdminConfig(patch, { updatedBy })	保存 + 审计
getRuntimeState()	adm 运行时预览
getEffectivePolicy({ userId })	Portal 校验用
getPublicClientPolicy({ userId })	/auth/status 下发 H5

4.1 getEffectivePolicy 返回示例

{
  "source": "admin-db",
  "updatedAt": 1753276800000,
  "enabled": true,
  "userAllowed": true,
  "taskTypes": ["page_data_dev", "h5_chat_code_task", "page_edit_code_task"],
  "requireValidation": true,
  "pageDataDevAutodetect": true,
  "generalAutodetect": false
}

4.2 getPublicClientPolicy 返回示例（按用户过滤后）

{
  "codeRun": {
    "enabled": true,
    "pageDataDevAutodetect": true,
    "generalAutodetect": false
  }
}

未登录或用户不在 allowlist 时：codeRun.enabled=false（或不返回该块）。

---

5. HTTP API

5.1 memindadm（admin-routes.mjs）

方法	路径	说明
GET	/api/admin/agent-code-run/config	读配置 + source + updatedBy
PUT/PATCH	/api/admin/agent-code-run/config	更新
GET	/api/admin/agent-code-run/runtime	有效策略 + env 覆盖状态 + worker 只读摘要

Worker 摘要可代理现有 /api/runtime/status 的 toolRuntime.codeRunPolicy 与 queue（只读，不在 adm 改 worker env）。

5.2 Portal 用户面

扩展 GET /auth/status（已登录用户）：

{
  "authenticated": true,
  "user": { "...": "..." },
  "capabilities": { "aider": true, "...": "..." },
  "skillRuntime": { "...": "..." },
  "agentCodeRun": {
    "enabled": true,
    "pageDataDevAutodetect": true,
    "generalAutodetect": false
  }
}

扩展 POST /api/agent/runs 校验： 从 getEffectivePolicy(userId) 读，不再只读 process.env.MEMIND_AGENT_CODE_RUNS_*。

5.3 只读运维

GET /api/runtime/status 增加：

{
  "toolRuntime": {
    "codeRunPolicy": {
      "source": "admin-db",
      "enabled": true,
      "userAllowlist": [],
      "taskTypeAllowlist": ["page_data_dev", "..."],
      "requireValidation": true,
      "pageDataDevAutodetect": true,
      "envOverrideActive": false
    }
  }
}

---

6. 前端改造（去掉 VITE_ 硬依赖）

6.1 src/utils/agentRunMode.ts

// 优先级：runtime policy（/auth/status）> VITE_（dev fallback）

let runtimePolicy: AgentCodeRunClientPolicy | null = null;

export function applyAgentCodeRunClientPolicy(policy: AgentCodeRunClientPolicy | null) {
  runtimePolicy = policy;
}

function clientCodeRunsEnabled(): boolean {
  if (runtimePolicy?.codeRun?.enabled != null) return runtimePolicy.codeRun.enabled;
  return agentCodeRunsEnabled; // VITE fallback
}

function clientPageDataDevAutodetect(): boolean {
  if (runtimePolicy?.codeRun?.pageDataDevAutodetect != null) {
    return runtimePolicy.codeRun.pageDataDevAutodetect;
  }
  return agentPageDataDevAutodetectEnabled;
}

6.2 注入时机

在现有 /auth/status 加载处（如 src/api/client.ts 或 auth hook）：

const status = await fetchAuthStatus();
applyAgentCodeRunClientPolicy(status.agentCodeRun ?? null);

效果： memindadm 打开 pageDataDev.autodetect 后，用户刷新页面即生效，无需 rebuild H5。

---

7. memindadm UI（Ops 后台）

建议菜单位置：系统 / Agent 运行时 → Code Run & Page Data Dev

控件	类型	说明
Code Run 总开关	toggle	codeRun.enabled
H5 客户端启用	toggle	codeRun.clientEnabled
Page Data Dev Autodetect	toggle	pageDataDev.autodetect
通用 Code Autodetect	toggle	codeRun.generalAutodetect（默认关）
强制 Validation	toggle	codeRun.requireValidation
用户白名单	multi-select UUID	空 = 全部（enabled 时）
Task Types	checkbox list	至少含 page_data_dev
当前 Worker 状态	read-only	来自 /runtime/status
Env Override 警告	banner	MEMIND_CODE_RUN_POLICY_SOURCE=env 时显示

保存时： 写 updated_by + updated_at；可选写 admin audit log（与 image-make 一致）。

---

8. 迁移与兼容

8.1 首次上线

1. 建表 h5_agent_code_run_config，默认全 false
2. 部署 agent-code-run-admin-config.mjs + admin API
3. 迁移脚本（可选）：若 env 已开启，import 到 DB 并提示改 POLICY_SOURCE=admin

node scripts/migrate-agent-code-run-config-from-env.mjs --dry-run
node scripts/migrate-agent-code-run-config-from-env.mjs --apply

8.2 回滚

场景	操作
adm 配错了	memindadm 关 codeRun.enabled
紧急全站关闭	MEMIND_CODE_RUN_POLICY_SOURCE=env + unset MEMIND_AGENT_CODE_RUNS_ENABLED
worker 异常	LaunchAgent 停 worker（现有 runbook），与 adm 无关

8.3 与 help-code01 Phase 的关系

Phase	内容	配置来源
Phase 1 ✅	page_data_dev 意图 + autodetect 逻辑	env/VITE
Phase 1.5	adm 运行时策略 + /auth/status	DB + adm UI
Phase 2	verify → Aider dev loop 脚本	脚本 + adm 开关

---

9. 实施清单（Phase 1.5）

• agent-code-run-admin-config.mjs + 单测
• admin-routes.mjs：/agent-code-run/config、/runtime
• server.mjs：/auth/status 增加 agentCodeRun
• agent-run-routes.mjs：改用 getEffectivePolicy(userId)
• agentRunMode.ts：runtime policy 优先于 VITE_
• Ops UI 页面（表单 + JSON 高级编辑：/ops/admin/agent-code-run）
• migrate-agent-code-run-config-from-env.mjs
• 更新 docs/agent-run-worker-rollout-runbook.md
• .env.example 增加 MEMIND_CODE_RUN_POLICY_SOURCE
• verify：agent-code-run-admin-config.test.mjs + 扩展 chat-agent-run-gate.test.mjs

---

10. 安全与审计

1. 仅 admin 可写 — 复用 requireAdmin
2. 默认 fail closed — 新环境 adm 配置为空 = 全关
3. 双闸门保留 — adm 开 + 用户 aider grant + worker gateway env
4. 审计字段 — updated_by、updated_at；重要变更写 admin audit
5. 生产建议 — 先 userAllowlist 小范围开 page_data_dev，再扩 generalAutodetect

---

11. 相关文件索引

类型	路径
方案总览	docs/help-code01.md
Goose 网关规划	docs/memindadm-goose-gateway-design.md
可复用 adm 模式	skill-runtime-admin-config.mjs
env↔adm 映射先例	memory-v2-admin-config.mjs
后端 code run 门禁	agent-run-routes.mjs
前端 autodetect	src/utils/agentRunMode.ts
运行时只读	server.mjs → runtimeCodeRunPolicyStatus()
Worker runbook	docs/agent-run-worker-rollout-runbook.md

---

12. 一句话总结

memindadm 管「策略」（谁、哪种 task、是否 page_data_dev）；env 管「部署」（worker 是否 spawn Aider）；H5 从 /auth/status 读运行时策略，不再依赖 rebuild VITE_。