.task/feature-layered-python-env.md

@@ -0,0 +1,29 @@
+# feature/layered-python-env 任务卡
+
+状态：实施已落在独立 worktree，未推送、未合入；owner：weichen
+
+## 基线与授权
+
+- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main
+- R0：64a50cf（origin/main，Merge PR #569）
+- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-layered-python-env
+- 分支：feature/layered-python-env（父仓与 backend、frontend、documents 子仓同名）
+- 启动检查：/tmp/layered-python-env-precheck.json，退出码 2，结论 SHARED_WORKSPACE_BUSY。共享主检出有未提交 gitlink，且落后 origin/main 60 个提交。因此没有在共享检出写入，也没有运行 make task-start。
+- 授权：用户要求按已附方案实现全部分阶段，不改方案文件本身。不包含推送、合入或重启 8788。
+
+## 目标
+
+用不可变、按内容哈希命名的 Python 层，替换「每个工作区一个 venv」和「一个可变全局环境」。沙箱保持断网。安装只发生在宿主侧构建器。
+
+## 本工作区已落地
+
+- 提案：modules/documents/docs/proposals/2026-10-15-layered-python-env.md（documents 945db35），状态仍是待评审。
+- P0：解释器不再解析到被沙箱遮蔽的 linuxbrew 路径；PATH 固定；工具文案和提示词不再要求 pip install --user；svc.sh 在产物支持时调用 env ensure，并把环境根与当前基础层经环境变量交给 serve。
+- P1：execenv 环境根、托管解释器（独立 CPython，失败则一份系统 venv）、锁、层、wheelhouse、agent-system env ensure|lock|gc|doctor|rebase|python。
+- P2：schema v35 的 exec_env_requests / exec_env_bindings、python_env 工具、白名单自动批准、其余走审批卡、pip 垫片、按会话挂载。
+- P3：管理区「Python 环境」页，以及回收、重建基础层、上传 wheel 的管理接口。
+- 测试（SELF，本机）：execenv、tools、store、app、server、runmgr、config、cmd/agent-system 通过。含 sandbox 参数、离线解析、真实 bwrap、两个会话各一层，以及 housestyle.build 产出的 docx 通过结构自检。权威源仍是 CI，本次未推送。
+
+## 非目标
+
+不重启正在运行的 8788。不修改方案文件。不把项目角色加入审批人。

policy/architecture-baseline.json

@@ -4,6 +4,7 @@
 "backend/app backend/cardsvc",
 "backend/app backend/cmdbus",
 "backend/app backend/config",
+"backend/app backend/execenv",
 "backend/app backend/genui",
 "backend/app backend/hostapi",
 "backend/app backend/ingest",
@@ -64,6 +65,7 @@
 "backend/runtime backend/workflow",
 "backend/server backend/cardsvc",
 "backend/server backend/cmdbus",
+"backend/server backend/execenv",
 "backend/server backend/ingest",
 "backend/server backend/intentgate",
 "backend/server backend/plugins",
@@ -82,6 +84,7 @@
 "backend/squadadapter backend/quality",
 "backend/store backend/blobstore",
 "backend/surfacesvc backend/store",
+"backend/tools backend/execenv",
 "backend/tools backend/quality",
 "backend/wfcompile backend/tools",
 "backend/wfcompile backend/workflow",

scripts/svc.sh

@@ -3948,6 +3948,30 @@ agent_static_preflight() {
   return 0
 }
 
+# agent_exec_env_prepare：多个实例共用 runtime/envs。启动不下载解释器或 wheel，
+# 避免把 start 拖进网络安装（真实组合测试的启动上限是 120 秒）。
+# current 基础层已经存在时，经环境变量把根和依赖层交给 serve，不改写 exec=。
+# 首次建立基础层用：<二进制> env ensure --root "$RUNTIME/envs"
+agent_exec_env_prepare() {
+  local probe root id deps
+  probe="$("$ENV_BIN" env 2>&1 || true)"
+  case "$probe" in
+    *ensure*) ;;
+    *) return 0 ;;
+  esac
+  root="$RUNTIME/envs"
+  if [ ! -L "$root/current" ]; then
+    c_warn "[$ENV_NAME] Python 基础层未建立（$root）。启动继续；需要时运行：$ENV_BIN env ensure --root $root"
+    return 0
+  fi
+  id="$(basename "$(readlink "$root/current")")"
+  deps="$root/layers/$id/site-packages"
+  [ -d "$deps" ] || { c_warn "[$ENV_NAME] Python 基础层 $id 缺少 site-packages"; return 0; }
+  guard_env+=("AGENT_SYSTEM_EXEC_ENV_ROOT=$root")
+  guard_env+=("AGENT_SYSTEM_EXEC_DEPS_DIR=$deps")
+  c_info "[$ENV_NAME] Python 环境：$root （基础层 $id）"
+}
+
 agent_do_start() {
   mkdir -p "$ENV_DATA" "$ENV_DIR"
   check_port_free || return 1
@@ -4043,6 +4067,7 @@ agent_do_start() {
     guard_env+=("AGENT_SYSTEM_INSTANCE_ID=$AGENT_SYSTEM_INSTANCE_ID")
     guard_env+=("AGENT_SYSTEM_DBREF=${AGENT_SYSTEM_DBREF:-sqlite}")
   fi
+  agent_exec_env_prepare
   # 9>&-：显式关闭锁 fd——服务进程绝不能继承 .start.lock（长驻持有会令后续
   # 生命周期操作在锁上自锁死等；2026-10-11 自恢复任务实测发现）。
   svc_write_serve_env