@xcompiler/cli 0.2.2 → 0.2.3

package/.env.example

@@ -0,0 +1,18 @@
+# OpenRouter Free mode（默认；OpenAI-compatible /v1 接口）
+# Free model catalog: https://openrouter.ai/models?max_price=0
+OPENROUTER_API_KEY=
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+OPENROUTER_MODEL=openrouter/free
+
+# Local OpenAI-compatible backup（默认在 config 中注释）
+# 本地无鉴权服务可留空 LOCAL_OPENAI_API_KEY。
+# LOCAL_OPENAI_API_KEY=
+# LOCAL_OPENAI_BASE_URL=http://127.0.0.1:8000/v1
+# LOCAL_OPENAI_MODEL=local-model
+
+# Ollama backup（默认在 config 中注释；弱服务器首次加载大模型可能需要数分钟）
+# OLLAMA_BASE_URL=http://localhost:11434
+# OLLAMA_REQUEST_TIMEOUT_MS=900000
+# OLLAMA_STREAM_IDLE_TIMEOUT_MS=300000
+# OLLAMA_DESIGN_MODEL=gemma4:31b-mlx
+# OLLAMA_CODE_MODEL=qwen3.6:35b-mlx

package/README.CN.md

@@ -17,8 +17,8 @@ XCompiler 把"写代码"这件事按"编译 → 执行"两阶段拆分，对标
 
 | 命令 | 定位 | 输入 | 输出 |
 |---|---|---|---|
-| **`xcompiler build`** | **AI 编译器** —— 把自然语言需求"翻译"成可执行的阶段步骤（plan） | 一段需求文本（`-i req.md` 或交互输入） | `plan.json`（拓扑有序的 Step DAG）+ `topic.md` + `plan.md` |
-| **`xcompiler run`** | **AI 执行器** —— 按拓扑顺序依次执行编译输出的阶段步骤 | `plan.json` | 可运行 Python/TypeScript 工程 + 绿色测试 + `docs/05-delivery.md` |
+| **`xcompiler build`** | **AI 编译器** —— 把自然语言需求"翻译"成阶段计划和当前阶段可执行步骤 | 一段需求文本（`-i req.md` 或交互输入） | `phasePlan.json` + `plan.P1.json`（当前阶段 Step DAG）+ `topic.md` + `plan.md` |
+| **`xcompiler run`** | **AI 执行器** —— 执行阶段计划中的当前阶段 | `phasePlan.json`（仍兼容历史 `plan.json`） | 可运行 Python/TypeScript 工程 + 绿色测试 + `docs/05-delivery.md` |
 
 > 类比：`xcompiler build` ≈ 编译器把 C 源码翻译成机器指令；`xcompiler run` ≈ CPU 顺次执行这些指令。
 > 区别：XCompiler 的"指令"是 V 模型阶段（REQUIREMENT / ARCH / CODE / TEST / REFACTOR / DELIVERY），"执行单元"是受沙盒约束的多 Agent 循环。
@@ -34,7 +34,7 @@ XCompiler 把软件工程的 **V 模型** 直接编码为 `xcompiler build` 的
 ```text
                   ┌────────── xcompiler build (AI 编译器) ──────────┐
                   │                                        │
-   需求 (NL) ───► Intake ──► Clarify ──► Decompose ──► plan.json
+   需求 (NL) ───► Intake ──► Clarify ──► PhasePlan ──► plan.P1.json
                                   │            │
                                   └─ Gate 1 ───┘ Gate 2  (人工双确认门)
 
@@ -106,7 +106,7 @@ XCompiler 把软件工程的 **V 模型** 直接编码为 `xcompiler build` 的
    │  LLM Router  │ │   Sandbox    │ │   Workspace      │
    │  chain +     │ │  subprocess  │ │   git + audit    │
    │  fallback    │ │  / docker    │ │   + .xcompiler/       │
-   │  (ollama,    │ │  venv 隔离    │ │   plan.json      │
+   │  (ollama,    │ │  venv 隔离    │ │ phasePlan/plan.Px │
    │   openai)    │ │              │ │                  │
    └──────────────┘ └──────────────┘ └──────────────────┘
 ```
@@ -131,7 +131,7 @@ XCompiler 把软件工程的 **V 模型** 直接编码为 `xcompiler build` 的
 ```bash
 # 1. 安装依赖
 npm ci
-cp .env.example .env            # 填入 OLLAMA_BASE_URL 等
+cp .env.example .env            # 填入 OPENROUTER_API_KEY，默认走 OpenRouter Free provider
 cp config.example.yaml config.yaml
 
 # 2. 构建并安装为全局命令
@@ -144,17 +144,28 @@ echo "把 DBC 文件解析为 Excel 报表" > req.md
 xcompiler build -i req.md --yes
 
 # 4. 执行 plan
-xcompiler run /tmp/xcompiler-<时间戳>/plan.json
+xcompiler run /tmp/xcompiler-<时间戳>/phasePlan.json
 
 # 5. 之后从生成的工程文件恢复
 xcompiler load /tmp/xcompiler-<时间戳>/xcompiler-<时间戳>.xc
 ```
 
+如果你使用的是已发布的 npm 包，而不是直接在源码仓库中运行，请先从包内模板创建自己的本地配置：
+
+```bash
+npm install -g @xcompiler/cli
+cp "$(npm root -g)/@xcompiler/cli/config.example.yaml" config.yaml
+cp "$(npm root -g)/@xcompiler/cli/.env.example" .env
+# 然后编辑 .env，填入 OPENROUTER_API_KEY
+```
+
+`config.yaml` 和 `llm_scores.yaml` 都是用户本地运行态文件，故意不提交到仓库；npm 包只发布 `config.example.yaml` 和 `.env.example` 作为模板。
+
 开发模式（无需构建）：
 
 ```bash
 npm run dev -- build
-npm run dev -- run path/to/plan.json
+npm run dev -- run path/to/phasePlan.json
 ```
 
 基于已有工程做增量开发：
@@ -180,7 +191,7 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 | `xcompiler build` | `-i <file>` | 使用需求文件，跳过交互输入 |
 | `xcompiler build` | `-t <file>` | 复用已有 `topic.md`，跳过 Gate 1 |
 | `xcompiler build` | `--intent <greenfield\|feature\|refactor\|self>` | 选择新建、增量或隔离自举规划 |
-| `xcompiler build` | `--baseline-plan <file>` | 为增量规划显式指定已有 `plan.json` |
+| `xcompiler build` | `--baseline-plan <file>` | 为增量规划显式指定已有 `phasePlan.json` 或历史 `plan.json` |
 | `xcompiler build` / `xcompiler run` | `--project-file <file>` | 创建/更新指定的 `XXX.xc` 工程文件 |
 | `xcompiler build` | `--force` | 覆写 workspace 锁，强制重新生成 plan |
 | `xcompiler evolve` | `...` | 先编译增量 plan，再在同一 workspace 内立即执行 |
@@ -192,15 +203,19 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 | `xcompiler run` | `--force` | 等价于 `--reset` + 覆写锁 |
 | `xcompiler run` | `--from <stepId>` / `--phase <phase>` | 断点续跑 / 仅跑某阶段 |
 | `xcompiler run` | `--dry-run` | 仅打印拓扑顺序 |
-| `xcompiler ls` | — | 扫描 workspace 列出所有 plan 状态 |
+| `xcompiler ls` | — | 扫描 workspace 列出所有阶段计划状态 |
 | `xcompiler show <stepId>` | — | 查看单 Step 定义 / 产物 / 最近审计 |
 
 ---
 
 ## 默认运行时
 
-- **LLM**：本地 ollama（`gemma4:31b` Planner/Architect，`qwen3-coder:30b` Coder/Tester/Debugger）。
-  在 `config.yaml` 中 `fallbacks: [openai]` 让主链失败时自动回落 OpenAI 兼容 endpoint。
+- **LLM**：默认使用 OpenRouter Free mode，并在 `config.yaml` 中显式配置为 `type: openai` 的 OpenAI-compatible provider。
+  在 `.env` 中填写 `OPENROUTER_API_KEY`；`config.example.yaml` 已经指向 `https://openrouter.ai/api/v1`，并默认使用 `model: openrouter/free`，复制默认配置后即可先跑验证。
+  如果 key 缺失或无效，XCompiler 会报告失败的 provider、model、base URL、HTTP 状态/响应体，并明确提示设置 `OPENROUTER_API_KEY`。
+  工程化运行建议为每个角色配置专用首选模型，并把 `openrouter_free`（`model: openrouter/free`，`tags: [cluster]`）追加为每个角色链的最后兜底。
+  cluster provider 默认动态评分范围为 `0.2..0.5`，因此正常情况下排在专用模型之后，只有主模型失败或评分衰减后才会前移。
+  配置步骤和官方链接见 [docs/openrouter.md](docs/openrouter.md)。
 - **i18n**：在 `config.yaml` 顶层设置 `locale: en` 或 `locale: zh`，控制 CLI 与 prompt 语言。
 - **Sandbox**：默认 `subprocess`（在 `<workspace>/.sandbox/<project>/` 建独立 venv）；可切到 `docker` 走 bind-mount + 网络/资源限制。
 - **Audit**：每次运行生成 `<workspace>/.xcompiler/audit.jsonl` 与 `docs/process_log.md`，记录全部 LLM 输入输出、工具调用、Step 状态变更。
@@ -213,6 +228,7 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 |---|---|
 | [docs/XCompiler_design.md](docs/XCompiler_design.md) | 总体设计：V 模型阶段、Agent / Skill / Tool 抽象、Sandbox 与 Workspace |
 | [docs/implementation_plan.md](docs/implementation_plan.md) | M1 → M6 里程碑与落地步骤 |
+| [docs/openrouter.md](docs/openrouter.md) | OpenRouter Free mode 配置教程，含 `type: openai` provider 示例 |
 | [docs/deploy.md](docs/deploy.md) | 部署指南（本地 + Docker） |
 | [docs/plugin_api.md](docs/plugin_api.md) | 插件 API、生命周期 Hooks、执行顺序与失败策略 |
 | [docs/versioning.md](docs/versioning.md) | 核心版本、Plugin API 版本、同步命令与发版校验 |
@@ -228,6 +244,8 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 
 ## 运行期调优（`config.yaml → agent.*`）
 
+LLM 路由在 `config.yaml → llm.*` 中配置。推荐使用 `roles.<Role>` 数组表达每个角色的候选链，`scores.<provider>: 0` 表示禁用某个 provider；若希望 `openrouter/free` 作为 cluster 兜底更积极或更保守，可调 `cluster_score_min` / `cluster_score_max`。
+
 | 字段 | 默认 | 作用 |
 |---|---|---|
 | `max_rounds_per_step` | 6 | 单 Step 中 LLM 多轮对话上限 |
@@ -235,7 +253,7 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 | `max_debug_retries` | 3 | DEBUG 重试最大次数 |
 | `max_edit_lines_per_step` | `auto` | EditGuard 单 Step 累计写入行数；`auto` 按 phase/tools/outputs/prompt 上下文自适应，数字值表示固定硬上限 |
 | `max_write_chunk_bytes` | `auto` | `write_file` / `append_file` 单次 content 字节预算；`auto` 按 phase/context 自适应，复杂工程仍应按模块/函数/类边界拆分 |
-| `sandbox_limits.network` | `pypi-only` | docker 模式下；`off` 走 `--network none` |
+| `sandbox_limits.network` | `download-only` | 默认允许出站下载且不发布入站端口；`off` 走断网隔离 |
 
 ---
 

package/README.md

@@ -17,8 +17,8 @@ XCompiler splits "writing code" into two phases — **compile** and **execute**
 
 | Command | Role | Input | Output |
 |---|---|---|---|
-| **`xcompiler build`** | **AI Compiler** — translates natural-language requirements into executable phase-steps (a plan) | A requirement text (`-i req.md`, `-t topic.md`, or interactive) | `plan.json` (topologically ordered Step DAG) + `topic.md` + `plan.md` |
-| **`xcompiler run`** | **AI Executor** — runs the compiled phase-steps in topological order | `plan.json` | Runnable Python/TypeScript project + green tests + `docs/05-delivery.md` |
+| **`xcompiler build`** | **AI Compiler** — translates natural-language requirements into a phase plan and executable current-phase steps | A requirement text (`-i req.md`, `-t topic.md`, or interactive) | `phasePlan.json` + `plan.P1.json` (current phase Step DAG) + `topic.md` + `plan.md` |
+| **`xcompiler run`** | **AI Executor** — runs the current phase from the compiled phase plan | `phasePlan.json` (legacy `plan.json` remains readable) | Runnable Python/TypeScript project + green tests + `docs/05-delivery.md` |
 
 > Analogy: `xcompiler build` ≈ a compiler turning C source into machine instructions; `xcompiler run` ≈ the CPU executing those instructions.
 > Difference: XCompiler's "instructions" are V-model phases (REQUIREMENT / ARCH / CODE / TEST / REFACTOR / DELIVERY), and each "execution unit" is a sandbox-constrained multi-Agent loop.
@@ -34,7 +34,7 @@ XCompiler encodes the **V-model** of software engineering directly as the decomp
 ```text
                   ┌────────── xcompiler build (AI Compiler) ──────────┐
                   │                                          │
-   Requirement ──► Intake ──► Clarify ──► Decompose ──► plan.json
+   Requirement ──► Intake ──► Clarify ──► PhasePlan ──► plan.P1.json
         (NL)             │            │
                          └─ Gate 1 ───┘ Gate 2  (two human confirmation gates)
 
@@ -106,7 +106,7 @@ XCompiler encodes the **V-model** of software engineering directly as the decomp
             │  LLM Router  │ │   Sandbox    │ │   Workspace      │
    │  chain +     │ │  subprocess  │ │   git + audit    │
    │  fallback    │ │  / docker    │ │   + .xcompiler/       │
-   │  (ollama,    │ │  venv iso.   │ │   plan.json      │
+   │  (ollama,    │ │  venv iso.   │ │ phasePlan/plan.Px │
    │   openai)    │ │              │ │                  │
    └──────────────┘ └──────────────┘ └──────────────────┘
 ```
@@ -132,7 +132,7 @@ Layer responsibilities:
 ```bash
 # 1. Install dependencies
 npm ci
-cp .env.example .env            # fill OLLAMA_BASE_URL etc.
+cp .env.example .env            # fill OPENROUTER_API_KEY for the default OpenRouter Free provider
 cp config.example.yaml config.yaml
 
 # 2. Build and install as a global command
@@ -145,17 +145,28 @@ echo "Parse a DBC file into an Excel report" > req.md
 xcompiler build -i req.md --yes
 
 # 4. Execute the plan
-xcompiler run /tmp/xcompiler-<timestamp>/plan.json
+xcompiler run /tmp/xcompiler-<timestamp>/phasePlan.json
 
 # 5. Resume later from the generated project file
 xcompiler load /tmp/xcompiler-<timestamp>/xcompiler-<timestamp>.xc
 ```
 
+If you installed the published npm package instead of running from this source tree, create your own local config from the packaged templates first:
+
+```bash
+npm install -g @xcompiler/cli
+cp "$(npm root -g)/@xcompiler/cli/config.example.yaml" config.yaml
+cp "$(npm root -g)/@xcompiler/cli/.env.example" .env
+# then edit .env and set OPENROUTER_API_KEY
+```
+
+`config.yaml` and `llm_scores.yaml` are user/local runtime files. They are intentionally not committed; the npm package only ships `config.example.yaml` and `.env.example` as templates.
+
 Dev mode (no build step):
 
 ```bash
 npm run dev -- build
-npm run dev -- run path/to/plan.json
+npm run dev -- run path/to/phasePlan.json
 ```
 
 Incremental evolution on top of an existing workspace:
@@ -181,7 +192,7 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 | `xcompiler build` | `-i <file>` | Use a requirements file (non-interactive) |
 | `xcompiler build` | `-t <file>` | Reuse a previously clarified `topic.md` and skip Gate 1 |
 | `xcompiler build` | `--intent <greenfield\|feature\|refactor\|self>` | Choose greenfield, incremental, or isolated self-bootstrap planning |
-| `xcompiler build` | `--baseline-plan <file>` | Point incremental planning at an explicit existing `plan.json` |
+| `xcompiler build` | `--baseline-plan <file>` | Point incremental planning at an explicit existing `phasePlan.json` or legacy `plan.json` |
 | `xcompiler build` / `xcompiler run` | `--project-file <file>` | Create/update a specific `XXX.xc` project file |
 | `xcompiler build` | `--force` | Override the workspace lock and regenerate the plan |
 | `xcompiler evolve` | `...` | Compile an incremental plan, then immediately execute it in the same workspace |
@@ -193,15 +204,19 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 | `xcompiler run` | `--force` | Equivalent to `--reset` + override lock |
 | `xcompiler run` | `--from <stepId>` / `--phase <phase>` | Resume / run only one phase |
 | `xcompiler run` | `--dry-run` | Print topology only |
-| `xcompiler ls` | — | Scan workspace and list every plan's status |
+| `xcompiler ls` | — | Scan workspace and list every phase plan's status |
 | `xcompiler show <stepId>` | — | Inspect a single Step (definition / outputs / recent audit) |
 
 ---
 
 ## Default runtime
 
-- **LLM**: local ollama (`gemma4:31b` for Planner / Architect, `qwen3-coder:30b` for Coder / Tester / Debugger).
-  Set `fallbacks: [openai]` in `config.yaml` to fall back to an OpenAI-compatible endpoint when the primary chain fails.
+- **LLM**: OpenRouter Free mode by default, configured as an explicit `type: openai` OpenAI-compatible provider.
+  Put `OPENROUTER_API_KEY` in `.env`; `config.example.yaml` already points to `https://openrouter.ai/api/v1` and uses `model: openrouter/free`, so the copied default config is enough for a first validation run.
+  If the key is missing or invalid, XCompiler reports the failing provider, model, base URL, HTTP status/body, and an explicit hint to set `OPENROUTER_API_KEY`.
+  For production-like engineering runs, give each role a dedicated first-choice model and append `openrouter_free` (`model: openrouter/free`, `tags: [cluster]`) as the last fallback in every role chain.
+  Cluster providers default to the lower dynamic score band `0.2..0.5`, so they remain backups unless the dedicated models fail or their scores decay.
+  See [docs/openrouter.md](docs/openrouter.md) for the setup guide and official OpenRouter links.
 - **i18n**: set top-level `locale: en` or `locale: zh` in `config.yaml` to control CLI and prompt language.
 - **Sandbox**: `subprocess` by default (creates an isolated venv at `<workspace>/.sandbox/<project>/`); switch to `docker` for bind-mount + network / resource limits.
 - **Audit**: every run writes `<workspace>/.xcompiler/audit.jsonl` and `docs/process_log.md`, recording all LLM I/O, tool calls and Step state transitions.
@@ -215,6 +230,7 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 |---|---|
 | [docs/XCompiler_design.md](docs/XCompiler_design.md) | Overall design: V-model phases, Agent / Skill / Tool abstractions, Sandbox & Workspace |
 | [docs/implementation_plan.md](docs/implementation_plan.md) | M1 → M6 milestones and landing steps |
+| [docs/openrouter.md](docs/openrouter.md) | OpenRouter Free-mode setup with `type: openai` provider config |
 | [docs/deploy.md](docs/deploy.md) | Deployment guide (local + Docker) |
 | [docs/plugin_api.md](docs/plugin_api.md) | Typed plugin API, lifecycle hooks, ordering and failure policy |
 | [docs/versioning.md](docs/versioning.md) | Core and Plugin API version sources, sync commands and release checks |
@@ -230,6 +246,8 @@ xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 
 ## Runtime tuning (`config.yaml → agent.*`)
 
+LLM routing is configured under `config.yaml → llm.*`. Use `roles.<Role>` arrays for role-specific chains, set `scores.<provider>: 0` to disable a provider, and tune cluster fallback score bounds with `cluster_score_min` / `cluster_score_max` when you want `openrouter/free` to be more or less aggressive as a backup.
+
 | Field | Default | Effect |
 |---|---|---|
 | `max_rounds_per_step` | 6 | Upper bound on LLM dialogue rounds within a single Step |

package/config.example.yaml

@@ -0,0 +1,106 @@
+locale: zh  # CLI / prompt 语言：en 或 zh
+
+llm:
+  # Default: OpenRouter Free mode through an OpenAI-compatible /v1 endpoint.
+  # Uses OpenRouter's free-route alias by default.
+  default: openrouter_free
+  providers:
+    openrouter_free:
+      type: openai
+      api_key: ${OPENROUTER_API_KEY}
+      base_url: https://openrouter.ai/api/v1
+      model: openrouter/free
+      tags: [cluster]
+      # If a provider rejects json_object, set: json_response_format: json_schema
+      request_timeout_ms: 900000
+      stream_idle_timeout_ms: 300000
+
+    # Backup: local OpenAI-compatible endpoint, e.g. mlx-server or vLLM.
+    # Local/no-auth servers may leave api_key empty; cloud providers usually require one.
+    # local_openai:
+    #   type: openai
+    #   api_key: ${LOCAL_OPENAI_API_KEY}
+    #   base_url: ${LOCAL_OPENAI_BASE_URL}
+    #   model: ${LOCAL_OPENAI_MODEL}
+    #   request_timeout_ms: 900000
+    #   stream_idle_timeout_ms: 300000
+
+    # Backup: local Ollama models.
+    # ollama_design:
+    #   type: ollama
+    #   base_url: ${OLLAMA_BASE_URL}
+    #   model: ${OLLAMA_DESIGN_MODEL}
+    #   request_timeout_ms: 900000
+    #   stream_idle_timeout_ms: 300000
+    #   think: false
+    # ollama_code:
+    #   type: ollama
+    #   base_url: ${OLLAMA_BASE_URL}
+    #   model: ${OLLAMA_CODE_MODEL}
+    #   request_timeout_ms: 900000
+    #   stream_idle_timeout_ms: 300000
+    #   think: false
+
+  # 角色 → provider 数组（兼容单字符串）。
+  # 数组里的 provider 按 ScoreStore 评分降序使用；用户手动设置 score=0 时跳过该 provider。
+  # 默认只启用 OpenRouter；如需本地备选，取消 providers 中对应块注释并加入各角色数组。
+  roles:
+    Planner:   [openrouter_free]
+    Architect: [openrouter_free]
+    Coder:     [openrouter_free]
+    Tester:    [openrouter_free]
+    Debugger:  [openrouter_free]
+
+  # 评分快照（preflight 与运行时自动维护，落盘到同目录的 llm_scores.yaml）。
+  # 这里可以手工写初值；空 = 全部默认 1.0；显式写 0 表示用户禁用。
+  # tags: [cluster] 的聚合/路由 provider 默认动态评分范围为 0.2～0.5；
+  # 可按需调整上下限（min 最低 0.1，max 最高 1.0）。
+  cluster_score_min: 0.2
+  cluster_score_max: 0.5
+  scores: {}
+
+  # 全局 fallback 链：默认不启用本地备选；如已取消 provider 注释，可设为 [local_openai] 或 [local_openai, ollama_code]。
+  fallbacks: []
+  role_fallbacks: {}
+
+agent:
+  # python | typescript
+  language: python
+  max_steps: 50
+  max_debug_retries: 3
+  # Debugger 滑动窗口的硬上限：LLM 持续健康输出时窗口可扩到该值；
+  # 出现解析失败/重复 actions/无进展时窗口快速收缩，连续 2 次低质量直接放弃。
+  # 默认 = max(max_debug_retries * 4, 10)
+  # max_debug_retries_cap: 12
+  # EditGuard 单 Step 累计行数预算。auto 会按 phase/tools/outputs/prompt 上下文自适应；
+  # 如需固定硬上限，可设为数字，例如 400。
+  # max_edit_lines_per_step: auto
+  # write_file / append_file 单次 content 字节预算。auto 会按 phase/tools/outputs/context 自适应；
+  # 大型工程仍应拆成模块/函数/类边界增量写入，而不是单次写巨型文件。
+  # max_write_chunk_bytes: auto
+  # subprocess | docker
+  # subprocess (默认)：在嬿主机 venv 内直接 spawn，快但无隔离
+  # docker: 使用系统 docker daemon，bind-mount 工程目录到容器；debug 时直接修改工程代码即生效
+  sandbox: subprocess
+  sandbox_limits:
+    cpu: 1
+    memory_mb: 1024
+    wall_seconds: 60
+    # off | download-only (default) | full
+    #   download-only — outbound HTTP/HTTPS allowed, no inbound port publishing
+    #   pypi-only     — legacy value, rejected because Docker cannot enforce a domain allowlist
+    #   full          — also publishes `expose_ports` to 127.0.0.1 for testing
+    #                   Python / Node network apps from the host side
+    network: download-only
+    # When network=full, container ports listed here are published on
+    # 127.0.0.1:<port> so host-side tests can reach the running app.
+    # expose_ports: [8000]
+  sandbox_docker:
+    # Default image is chosen from agent.language:
+    #   python     -> python:3.11-slim
+    #   typescript -> node:20-slim
+    image: python:3.11-slim
+    workdir: /workspace
+    pull: false
+    docker_bin: docker
+    extra_run_args: []

package/dist/acp/index.d.ts

@@ -129,6 +129,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
         refactor: "refactor";
         self: "self";
     }>>;
+    phaseId: z.ZodDefault<z.ZodString>;
     projectType: z.ZodDefault<z.ZodEnum<{
         application: "application";
         library: "library";
@@ -222,6 +223,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
     version: "1";
     language: "python" | "typescript";
     intent: "greenfield" | "feature" | "refactor" | "self";
+    phaseId: string;
     projectType: "application" | "library" | "mixed";
     requirementDigest: string;
     globalPrompt: string;
@@ -278,6 +280,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
     version: "1";
     language: "python" | "typescript";
     intent: "greenfield" | "feature" | "refactor" | "self";
+    phaseId: string;
     projectType: "application" | "library" | "mixed";
     requirementDigest: string;
     globalPrompt: string;
@@ -362,6 +365,12 @@ interface ChatOptions {
      * 空输出、model token loop 等“表面成功但语义不可用”场景。
      */
     validate?: (text: string) => void;
+    /**
+     * Whether a provider response should increase its dynamic score.
+     * Step/workflow executors should disable this and score quality through
+     * their own validation instead of treating "returned text" as task success.
+     */
+    scoreSuccess?: boolean;
     /**
      * 调用者可传入回调，与 LLM 输出一同拿到实际产出该响应的 provider 名。
      * 主要用于追溯：在 FallbackClient 中服务于响应的是链中某一个后选 provider，
@@ -515,7 +524,7 @@ interface Sandbox {
     /**
      * 运行工程入口程序。
      *  - Python：`python <args>`（自动选用 venv 内解释器）。
-     *  - TypeScript：`npx tsx <args>`。
+     *  - TypeScript：默认 `npx tsx <entry>`；当 args 以 `npm`/`npx`/`node`/`tsx`/`tsc` 开头时执行对应项目命令。
      */
     runProgram(args: string[], extra?: ExecExtra): Promise<ExecResult>;
     /**
@@ -577,6 +586,8 @@ interface ToolContext {
     language?: Language;
     /** 当前 Step 的 write_file / append_file 单次 content 字节预算。 */
     writeChunkBytes?: number;
+    /** run_tests 未提供有效过滤参数时使用的当前阶段默认测试范围。 */
+    defaultTestArgs?: string[];
     /** Optional protocol/UI permission hook for sensitive tool operations. */
     requestPermission?: ToolPermissionRequester;
     /** Optional protocol/UI event hook for tool calls and file changes. */
@@ -653,6 +664,8 @@ interface HookContextMap {
     'compile.finish': {
         plan: Plan;
         planPath: string;
+        phasePlanPath?: string;
+        currentPlanPath?: string;
     };
     'run.before': {
         plan: Plan;
@@ -868,7 +881,7 @@ interface CompileOptions {
      * 已澄清的 topic.md 直接输入：跳过 intake / clarify / Addenda / Gate 1，把该文件
      * 内容当作冻结后的项目选题书，直接进入 decompose。常用于：
      *   - 用户上次已澄清并保留了 topic.md，重新跑 decompose 不想再问一遍
-     *   - 离线编辑了 topic.md 想直接拿来出 plan.json
+     *   - 离线编辑了 topic.md 想直接拿来出 phasePlan.json 与当前阶段计划
      * 与 --input 互斥；同时给则 --topic 优先并打印警告。
      */
     topicFile?: string;