feat: plan agent v2, global chat mode, and user-mode v2 flag sync

- Add runtime/plan_agent_v2 package and shims; gateway/direct_loop/WS wiring

- Admin chat: interaction mode and specialist only in user menu; session API stores memory_mode and execution_mode only

- POST /admin/api/chat/user-mode mirrors plan_agent_version to AIA_EXPERT_PLAN_AGENT_V2_ENABLED (v2 to 1, v1 to 0)

- Composer cleanup (hidden mode select, no reasoning toggle in meta bar); tests and _local/system.env.example

Co-authored-by: Cursor <cursoragent@cursor.com>

_local/system.env.example

@@ -0,0 +1,353 @@
+# =============================================================================
+# 【仓库约定 — 必读】
+#
+# 1) 新增「进程环境变量」（代码里新出现 os.getenv / 读取 os.environ）时：
+#    - 必须在本文件登记：变量名、含义、典型取值、与前端/管理后台是否有关联。
+#    - 提交代码评审时一并更新本模板（复制为 _local/system.env 后本地填写真实值；system.env 勿提交）。
+#
+# 2) 加载时机：网关入口 modules/http/fastapi_app.py 会调用 load_system_env()，
+#    仅加载「_local/system.env」单一路径（platform/config/bootstrap_env.py）。
+#    已在操作系统 / 启动脚本里 export 的变量优先级更高（不会被文件覆盖）。
+#
+# 3) 与 SQLite app_setting / 管理后台的关系：
+#    - 多数运行参数可在「管理后台」写入数据库；具体优先级以代码为准（常见：后台优先，
+#      仅部分开关保留「环境变量优先」）。
+#    - 本节标注「仅存数据库」的项不要指望写在本 env 文件生效（除非代码明确读取 getenv）。
+#
+# 4) 布尔值约定：未特殊说明时，1/true/yes/on 表示开启；0/false/no/off 表示关闭。
+#
+# 用法：复制本文件为同目录 system.env，按需取消注释并填写。
+#     copy _local\system.env.example _local\system.env
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# 一、HTTP 网关监听（uvicorn / FastAPI）
+# -----------------------------------------------------------------------------
+# AIA_ASSISTANT_GATEWAY_HOST    监听地址，默认 0.0.0.0。
+# AIA_ASSISTANT_GATEWAY_PORT    监听端口，默认 8787。
+# 【前端】无专门开关；由部署/启动脚本决定。
+AIA_ASSISTANT_GATEWAY_HOST=0.0.0.0
+AIA_ASSISTANT_GATEWAY_PORT=8787
+
+# AIA_PREWARM_INTERVAL_SECONDS    后台预热任务周期（秒），默认 600，合法范围代码内 clamp。
+# 【前端】无。
+AIA_PREWARM_INTERVAL_SECONDS=600
+
+# -----------------------------------------------------------------------------
+# 二、数据目录、SQLite、密钥与语言（进程级）
+# -----------------------------------------------------------------------------
+# AIA_ASSISTANT_DB_PATH / OPS_ASSISTANT_DB_PATH    SQLite 库路径（二选一即可），相对路径相对仓库根。
+# 【前端】无直接开关；决定连接哪份数据库文件。
+AIA_ASSISTANT_DB_PATH=
+OPS_ASSISTANT_DB_PATH=
+
+# AIA_ASSISTANT_MASTER_KEY    用于加密迁移密钥等；不设则部分迁移不可用。
+# 【前端】管理后台「密钥迁移」相关界面会检测是否配置（提示文案）。
+AIA_ASSISTANT_MASTER_KEY=
+
+# AIA_ASSISTANT_PASSWORD / OPS_ASSISTANT_PASSWORD    管理后台登录密码（旧名 OPS_* 兼容）。
+# 【前端】登录表单；环境变量常用于自动化部署注入初始密码。
+AIA_ASSISTANT_PASSWORD=
+OPS_ASSISTANT_PASSWORD=
+
+# AIA_ASSISTANT_LANG    全局默认语言倾向（如 zh），具体会话可被覆盖。
+# 【前端】聊天语言一般由会话/UI 控制。
+AIA_ASSISTANT_LANG=
+
+# AIA_ASSISTANT_PREMERGE_BACKUP_KEEP / OPS_*    数据库预合并备份保留策略相关。
+# AIA_LEGACY_DB_FORCE_PREMERGE / OPS_*    是否强制走遗留库合并逻辑。
+AIA_ASSISTANT_PREMERGE_BACKUP_KEEP=
+OPS_ASSISTANT_PREMERGE_BACKUP_KEEP=
+AIA_LEGACY_DB_FORCE_PREMERGE=
+OPS_LEGACY_DB_FORCE_PREMERGE=
+
+# -----------------------------------------------------------------------------
+# 三、主配置文件路径（oclaw.json 与别名）
+# -----------------------------------------------------------------------------
+# AIA_OCLAW_CONFIG_PATH    主配置 JSON（agents、工作区等）；多处 gateway/direct_loop 读取。
+# OCLAW_CONFIG_PATH        别名，hooks_runtime / user_config_hooks / gateway server_methods 等。
+# 【前端】无单一开关；配置内容决定模型与工作区。
+AIA_OCLAW_CONFIG_PATH=
+OCLAW_CONFIG_PATH=
+
+# OCLAW_RUNTIME_CONFIG_JSON    内联 JSON 配置片段（调试/容器注入）。
+OCLAW_RUNTIME_CONFIG_JSON=
+
+# -----------------------------------------------------------------------------
+# 四、工作区与路径守护（工具可读目录）
+# -----------------------------------------------------------------------------
+# OCLAW_WORKSPACE    逻辑工作区根路径；多处注入 prompt / hooks。
+# OCLAW_STATE_DIR    Agent 状态目录，默认 .oclaw。
+# OCLAW_SHELL        子进程 shell 覆盖。
+# OCLAW_HOME         boot-md / command-logger 等与 OCLAW_STATE_DIR 二选一的别名路径。
+OCLAW_WORKSPACE=
+OCLAW_STATE_DIR=.oclaw
+OCLAW_SHELL=
+OCLAW_HOME=
+
+# AIA_WORKSPACE_ROOT / OPS_WORKSPACE_ROOT    路径守护主根覆盖。
+# AIA_WORKSPACE_EXTRA_ROOTS / OPS_*    额外允许访问的根，竖线或分隔符依代码。
+# 【前端】Admin「用户/会话」里「额外根路径」等与上述 env 合并（见 app.js 文案）。
+AIA_WORKSPACE_ROOT=
+OPS_WORKSPACE_ROOT=
+AIA_WORKSPACE_EXTRA_ROOTS=
+OPS_WORKSPACE_EXTRA_ROOTS=
+
+# AIA_MCP_FILESYSTEM_EXTRA_ROOTS / OPS_*    MCP 官方 filesystem 进程额外根路径。
+# 【前端】管理后台「网关/MCP」设置项可写库；与此 env 合并。
+AIA_MCP_FILESYSTEM_EXTRA_ROOTS=
+OPS_MCP_FILESYSTEM_EXTRA_ROOTS=
+
+# -----------------------------------------------------------------------------
+# 五、Expert Plan / Agent v2（专家模式计划态）
+# -----------------------------------------------------------------------------
+# AIA_EXPERT_PLAN_AGENT_V2_ENABLED    是否启用 expert 下的 plan_agent_v2 网关分支。
+#    取值 1/true/on：启用；留空或 0/false：否。
+#    优先级：SQLite app_setting 非空则优先于 env（见 runtime/plan_agent_v2/switch.py）。
+# 【前端】聊天 ⋯ 菜单里「Plan / Agent 版本」选 v2/v1 会通过 /admin/api/chat/user-mode 写入同一键（v2→1，v1→0）。
+#    首次在未写入库前仅 env 生效；一旦在菜单里保存过，以库为准。
+AIA_EXPERT_PLAN_AGENT_V2_ENABLED=0
+
+# 【仅存数据库 · 写在此处无效】AIA_EXPERT_PLAN_CONFIRM_STRATEGY（strict/auto/off）
+#    计划确认策略；由 Admin chat API 写入库；前端 chat.js「确认策略」菜单与会话同步。
+# 【仅存数据库 · 写在此处无效】AIA_EXPERT_PLAN_FILE_DIR    计划文件目录。
+# 【仅存数据库】会话级 execution_mode / confirm_strategy 走接口元数据与 chat_api，不靠 getenv。
+
+# -----------------------------------------------------------------------------
+# 六、LLM 提供商密钥与默认模型（环境兜底；正式账号多在 DB llm_profile）
+# -----------------------------------------------------------------------------
+OPENAI_API_KEY=
+OPENAI_BASE_URL=
+OPENAI_MODEL=
+OPENAI_EMBEDDING_MODEL=
+
+ANTHROPIC_API_KEY=
+ANTHROPIC_BASE_URL=
+ANTHROPIC_MODEL=
+
+GOOGLE_API_KEY=
+GEMINI_API_KEY=
+
+OLLAMA_BASE_URL=
+OPENAI_BASE_URL_OLLAMA=
+OLLAMA_MODEL=
+
+DASHSCOPE_API_KEY=
+DASHSCOPE_BASE_HTTP_API_URL=
+
+# AIA_ASSISTANT_MODE    全局助手模式字符串（与 chat_models 等协调）；测试里可用 OPS_ASSISTANT_MODE。
+AIA_ASSISTANT_MODE=
+
+# --- OpenAI 兼容「思考」字段 --- 
+AIA_LLM_THINKING_FORCE_DISABLED=
+AIA_LLM_THINKING_FORCE_ENABLED=
+AIA_LLM_THINKING_DISABLED=
+
+# --- Gemini SSE ---
+AIA_GEMINI_THINKING=
+AIA_GEMINI_THINKING_LEVEL=
+AIA_GEMINI_THINKING_BUDGET=
+
+# -----------------------------------------------------------------------------
+# 七、直连循环（direct_loop）：空回复、工具结果长度、trace
+# -----------------------------------------------------------------------------
+AIA_IMAGE_TOOL_RESULT_REPLAY_CAP_CHARS=
+AIA_VIDEO_TOOL_RESULT_REPLAY_CAP_CHARS=
+AIA_TOOL_WIRE_FROZEN_ON_STARTUP=
+AIA_TRACE_TOOL_EXPOSURE_PLAN=
+
+AIA_EMPTY_ASSISTANT_RETRY_MAX=
+AIA_EMPTY_ASSISTANT_RETRY_DELAY_MS=
+AIA_EMPTY_ASSISTANT_RETRY_TOTAL_TIMEOUT_MS=
+
+# 【管理后台】部分同名项可在运维设置里配置（如 AIA_SSE_QUEUE_MAXSIZE）；chat_api 读 env 作兜底。
+AIA_SSE_QUEUE_MAXSIZE=
+
+# -----------------------------------------------------------------------------
+# 八、工具清单 / MCP / 插件 / 高风险工具可见性
+# -----------------------------------------------------------------------------
+AIA_SKILL_TOOLCALL_ENABLED=
+AIA_PUBLIC_TOOLS_ALLOW_HIGH=
+AIA_ENABLE_MCP_TOOLS=1
+OPS_ENABLE_MCP_TOOLS=
+AIA_PLUGIN_TOOLS_ENABLED=1
+AIA_PLUGIN_TOOL_IDS=
+AIA_ENABLE_RUN_COMMAND=
+AIA_LOCAL_ADAPTER_STARTUP_SELF_CHECK=1
+
+# AIA_MCP_SPECIALISTS    允许使用 MCP 的专家角色列表，逗号分隔。
+AIA_MCP_SPECIALISTS=generalist,manager
+
+# AIA_MCP_ENV_ALLOWLIST    允许注入 MCP 子进程的环境变量名列表。
+# 【前端】管理后台可维护同名设置。
+AIA_MCP_ENV_ALLOWLIST=
+
+# AIA_MCP_SQLITE_COMMAND    表格附件走 MCP 时的 sqlite 命令路径覆盖。
+AIA_TABULAR_USE_MCP=
+AIA_TABULAR_SQL_TIMEOUT_MS=
+
+# -----------------------------------------------------------------------------
+# 九、工具运行时：上下文长度、日志、历史摘要
+# -----------------------------------------------------------------------------
+AIA_TOOL_LLM_MESSAGE_MAX_CHARS=
+AIA_TOOL_HISTORY_SUMMARY_AFTER_CALLS=
+AIA_TOOL_LOG_MAX_CHARS=
+
+# -----------------------------------------------------------------------------
+# 十、Skills 根目录与注入
+# -----------------------------------------------------------------------------
+AIA_SKILLS_ROOT=
+AIA_DISABLE_LEGACY_SKILLS_FALLBACK=
+AIA_SKILLS_PROMPT_IN_SYSTEM=
+AIA_SKILLS_PROMPT_MAX_CHARS=18000
+
+# AIA_SKILL_ROLE_BINDING_ENABLED / AIA_SKILL_ROLE_BINDING_MANAGER_INHERIT
+#    技能与角色绑定；env 优先于 store（见 runtime/skill_role_binding.py）。
+# 【前端】高级设置里可操作同名开关（app.js 文案引用）。
+AIA_SKILL_ROLE_BINDING_ENABLED=
+AIA_SKILL_ROLE_BINDING_MANAGER_INHERIT=
+
+# --- ClawHub ---
+AIA_CLAWHUB_SITE=
+AIA_CLAWHUB_REGISTRY=
+AIA_CLAWHUB_TOKEN=
+AIA_CLAWHUB_API_BASE=
+CLAWHUB_SITE=
+CLAWHUB_REGISTRY=
+CLAWHUB_TOKEN=
+
+# --- Cocoloop ---
+AIA_COCOLOOP_API_BASE=
+COCOLOOP_API_BASE=
+
+# -----------------------------------------------------------------------------
+# 十一、附件 ACL、体积上限
+# -----------------------------------------------------------------------------
+AIA_ATTACHMENT_ACL_STRICT=
+AIA_MAX_ATTACHMENT_BYTES=
+
+# -----------------------------------------------------------------------------
+# 十二、路由与运行时日志
+# -----------------------------------------------------------------------------
+AIA_OCLAW_ROUTER_MODE=
+AIA_RUNTIME_LOG_DIR=
+
+# -----------------------------------------------------------------------------
+# 十三、RAG / 记忆
+# -----------------------------------------------------------------------------
+AIA_RAG_MODE=
+AIA_RAG_EMBEDDING_MODE=
+AIA_MEMORY_EPISODIC_TTL_DAYS=
+MEMORY_EPISODIC_TTL_DAYS=
+
+# -----------------------------------------------------------------------------
+# 十四、WebSocket（/ws）
+# -----------------------------------------------------------------------------
+OCLAW_WS_REQUIRE_AUTH=1
+OCLAW_WS_ALLOWED_ORIGINS=
+OCLAW_WS_RATE_LIMIT_WINDOW_MS=60000
+OCLAW_WS_RATE_LIMIT_CONN_PER_WINDOW=120
+OCLAW_WS_RATE_LIMIT_IP_PER_WINDOW=240
+OCLAW_WS_RATE_LIMIT_USER_PER_WINDOW=360
+OCLAW_WS_SEND_QUEUE_MAX_MESSAGES=256
+OCLAW_WS_SEND_QUEUE_MAX_BYTES=
+OCLAW_WS_EVENT_REPLAY_MAX=256
+
+# -----------------------------------------------------------------------------
+# 十五、模型请求：工具 JSON、Replay 策略、Agent 消息回放
+# -----------------------------------------------------------------------------
+AIA_OPENAI_TOOLS_MAX_JSON_CHARS=
+AIA_SHRINK_OPENAI_TOOLS=
+AIA_SHRINK_OPENAI_TOOLS_MAX_JSON=
+
+AIA_REPLAY_POLICY_ENABLED=
+AIA_REPLAY_REPAIR_TOOL_PAIRING=
+AIA_TOOL_CALL_ID_MAX_LEN=
+
+AIA_REPLAY_TOOL_FULL_ROUNDS=
+AIA_REPLAY_REASONING_SIGNATURE_POLICY=
+
+# -----------------------------------------------------------------------------
+# 十六、图片 / 音视频工具（OpenAI、DashScope）
+# -----------------------------------------------------------------------------
+OPENAI_IMAGE_MODEL=
+OPENAI_AUDIO_TRANSCRIPTION_MODEL=
+
+AIA_IMAGE_MODEL=
+AIA_IMAGE_BASE_URL=
+AIA_IMAGE_API_KEY=
+AIA_IMAGE_CHAT_ENDPOINT=
+
+DASHSCOPE_IMAGE_N=
+DASHSCOPE_IMAGE_WATERMARK=
+DASHSCOPE_IMAGE_NEGATIVE_PROMPT=
+DASHSCOPE_IMAGE_PROMPT_EXTEND=
+DASHSCOPE_IMAGE_SIZE=
+DASHSCOPE_IMAGE_MODEL=
+
+AIA_IMAGE_RETRIES=
+AIA_IMAGE_RETRY_BACKOFF_SEC=
+AIA_IMAGE_STATUS_RETRIES=
+AIA_IMAGE_STATUS_RETRY_BACKOFF_SEC=
+
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_API_TOKEN=
+
+# -----------------------------------------------------------------------------
+# 十七、Web 搜索（official Bing/Google HTTP API）
+# -----------------------------------------------------------------------------
+OCLAW_WEB_SEARCH_OFFICIAL_API_KEY=
+OCLAW_WEB_SEARCH_OFFICIAL_API_ENDPOINT=
+OCLAW_WEB_SEARCH_BING_API_KEY=
+OCLAW_WEB_SEARCH_BING_API_ENDPOINT=
+OCLAW_WEB_SEARCH_GOOGLE_API_KEY=
+OCLAW_WEB_SEARCH_GOOGLE_CSE_ID=
+OCLAW_WEB_SEARCH_GOOGLE_API_ENDPOINT=
+
+# -----------------------------------------------------------------------------
+# 十八、微信 / 企业微信 长连接 Runner（interfaces/channels/wecom）
+# -----------------------------------------------------------------------------
+WECOM_LONGCONN_MODE=
+WECOM_LONGCONN_INTERVAL_SEC=
+WECOM_LONGCONN_WS_URL=
+WECOM_LONGCONN_PULL_URL=
+WECOM_LONGCONN_SEND_RETRY=
+WECOM_LONGCONN_MOCK_TEXT=
+WECOM_LONGCONN_DELIVER_OUTBOUND=
+WECOM_LONGCONN_USE_RESPONSE_URL=
+AIA_WECOM_LONGCONN_WORKERS=
+WECOM_LONGCONN_WORKERS=
+AIA_WECOM_LONGCONN_INBOUND_QUEUE_MAXSIZE=
+WECOM_LONGCONN_INBOUND_QUEUE_MAXSIZE=
+
+# -----------------------------------------------------------------------------
+# 十九、Wiki Worker、杂项、对外版本号
+# -----------------------------------------------------------------------------
+AIA_WIKI_WORKER_POLL_SECONDS=4
+AIA_WIKI_WORKER_ID=wiki-worker-main
+
+AIA_ILINK_BOT_TOKEN=
+
+OCLAW_VERSION=0.1
+
+# runtime/operations/main.py 启动时可写入：
+# AIA_ASSISTANT_GATEWAY_HOST / PORT（已由第一节覆盖）
+
+# -----------------------------------------------------------------------------
+# 二十、Skill 内第三方（示例：Tavily）
+# -----------------------------------------------------------------------------
+TAVILY_API_KEY=
+
+# -----------------------------------------------------------------------------
+# 二十一、下列 keys 常在「管理后台 → 网关/运维」中配置（SQLite），与 env 二选一或叠加
+#    若代码未 getenv，请使用后台保存；不要仅写在本文件。
+# -----------------------------------------------------------------------------
+# AIA_TURN_MAX_CONTEXT_MESSAGES / AIA_TURN_MAX_TOOL_ROUNDS / AIA_TURN_MAX_TOOL_WORKERS
+# AIA_OCLAW_MAX_ATTEMPTS
+# AIA_ENABLE_PLUGIN_TOOLS（注意与 AIA_PLUGIN_TOOLS_ENABLED 命名区分，以后台为准）
+# AIA_TOOL_CONTEXT_TRUNCATE_ENABLED
+# AIA_CHAT_SHOW_TTFT_DEBUG
+# AIA_SKILL_RUNTIME_ENABLED / AIA_SKILL_AUTO_INSTALL_ENABLED
+# AIA_OCLAW_RETRYABLE_ERROR_CODES / AIA_OCLAW_RETRY_CODES_STRICT_MODE
+# rag_mode、embedding 相关部分亦在后台 memory/RAG 页
+# 【前端】多数上述项在 Admin 设置表单中有对应勾选或输入框。