@xcompiler/cli 0.2.2 → 0.2.3

package/docs/openrouter.md

@@ -0,0 +1,149 @@
+# OpenRouter Free Mode Guide
+
+XCompiler defaults to OpenRouter Free mode through an OpenAI-compatible `/v1` endpoint.
+The provider must declare `type: openai`; the provider name is only an identifier and is not used to infer the API protocol.
+
+Official references:
+
+- OpenRouter Quickstart: https://openrouter.ai/docs/quickstart
+- API reference: https://openrouter.ai/docs/api_reference/overview
+- Free model catalog: https://openrouter.ai/models?max_price=0
+- API keys: https://openrouter.ai/settings/keys
+
+## 1. Create Local Environment
+
+From a source checkout:
+
+```bash
+cp .env.example .env
+cp config.example.yaml config.yaml
+```
+
+From the published npm package:
+
+```bash
+npm install -g @xcompiler/cli
+cp "$(npm root -g)/@xcompiler/cli/.env.example" .env
+cp "$(npm root -g)/@xcompiler/cli/config.example.yaml" config.yaml
+```
+
+Edit `.env` locally:
+
+```bash
+OPENROUTER_API_KEY=<your-openrouter-api-key>
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+OPENROUTER_MODEL=openrouter/free
+```
+
+`.env` is ignored by git. Do not commit real API keys.
+`config.yaml` and `llm_scores.yaml` are local runtime files; keep them outside commits. The package ships `config.example.yaml` and `.env.example` only as templates.
+
+## 2. Configure XCompiler
+
+`config.example.yaml` already uses OpenRouter Free mode by default:
+
+```yaml
+llm:
+  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]
+      request_timeout_ms: 900000
+      stream_idle_timeout_ms: 300000
+  roles:
+    Planner:   [openrouter_free]
+    Architect: [openrouter_free]
+    Coder:     [openrouter_free]
+    Tester:    [openrouter_free]
+    Debugger:  [openrouter_free]
+  cluster_score_min: 0.2
+  cluster_score_max: 0.5
+```
+
+`type: openai` means XCompiler will use the OpenAI-compatible chat completions client. This is also the correct type for local `/v1` endpoints such as vLLM or mlx-server.
+`tags: [cluster]` marks the provider as an aggregated route. XCompiler scores those providers in a lower default band (`0.2..0.5`) so they behave as backups rather than replacing dedicated role models too early.
+OpenRouter requires `OPENROUTER_API_KEY`. Local OpenAI-compatible endpoints may leave `api_key` empty when they run without authentication.
+
+If an OpenAI-compatible request fails, XCompiler reports the provider, model, base URL, request mode, HTTP status/body when available, and a concrete hint such as setting `OPENROUTER_API_KEY`, changing `json_response_format`, checking quota/rate limits, or switching provider.
+
+## 3. Choose A Free Model
+
+OpenRouter free models normally use model ids ending with `:free`.
+Browse https://openrouter.ai/models?max_price=0, copy the model slug, and set:
+
+```yaml
+providers:
+  openrouter_coder:
+    type: openai
+    api_key: ${OPENROUTER_API_KEY}
+    base_url: https://openrouter.ai/api/v1
+    model: qwen/qwen3-coder:free
+  openrouter_free:
+    type: openai
+    api_key: ${OPENROUTER_API_KEY}
+    base_url: https://openrouter.ai/api/v1
+    model: openrouter/free
+    tags: [cluster]
+```
+
+If one free model returns quota, availability, or capability errors, pick another free model slug and rerun the task.
+
+## 4. Engineering Recommendation
+
+For real development runs, avoid relying on a single aggregated route as the only model. Use a role-specific primary model, then append `openrouter_free` as the last fallback for every role:
+
+```yaml
+roles:
+  Planner:   [openrouter_planner, openrouter_free]
+  Architect: [openrouter_architect, openrouter_free]
+  Coder:     [openrouter_coder, openrouter_free]
+  Tester:    [openrouter_tester, openrouter_free]
+  Debugger:  [openrouter_debugger, openrouter_free]
+```
+
+Keep the default cluster score band (`cluster_score_min: 0.2`, `cluster_score_max: 0.5`) when `openrouter/free` is a safety net. Raise `cluster_score_max` toward `1.0` only when you intentionally want the aggregated route to compete with dedicated models.
+
+## 5. Optional Local Backups
+
+Local OpenAI-compatible endpoints:
+
+```yaml
+local_openai:
+  type: openai
+  api_key: ${LOCAL_OPENAI_API_KEY}
+  base_url: ${LOCAL_OPENAI_BASE_URL}
+  model: ${LOCAL_OPENAI_MODEL}
+```
+
+For no-auth local servers, set `LOCAL_OPENAI_API_KEY=` or leave the provider `api_key` empty.
+
+Ollama native endpoints:
+
+```yaml
+ollama_code:
+  type: ollama
+  base_url: ${OLLAMA_BASE_URL}
+  model: ${OLLAMA_CODE_MODEL}
+  think: false
+```
+
+Add backups to `roles` or `fallbacks` only after the provider block is enabled.
+
+## 6. Validate
+
+```bash
+npm run typecheck
+npm test
+xcompiler doctor
+```
+
+For a direct endpoint check:
+
+```bash
+curl https://openrouter.ai/api/v1/models \
+  -H "Authorization: Bearer $OPENROUTER_API_KEY"
+```

package/docs/versioning.md

@@ -24,10 +24,22 @@ npm run version:sync
 
 # 设置下一个核心版本并同步全部位置
 npm run version:set -- 0.1.4
+
+# 准备一次本地发版（不 push）
+npm run release:local -- v0.1.4
 ```
 
 核心版本遵循 SemVer。发布 tag 必须是 `v<package version>`，例如 `v0.1.3`；Release workflow 会在测试和打包前强制校验，版本不一致时停止发布。二进制分发包内包含 `VERSION` 文件，CLI 的 `--version` 也读取同一个生成常量。
 
+`release:local` 会要求工作区干净，然后同步 `package.json`、`package-lock.json` 与 `src/version.ts`，执行本地发版门禁（`version:check`、`npm audit --omit=dev`、`typecheck`、`lint`、`test`、`build`、`npm pack --dry-run`），提交 `chore: release <tag>`，并创建本地 annotated tag。它不会 push；完成后手工执行：
+
+```bash
+git push origin <branch>
+git push origin <tag>
+```
+
+如果上一次本地 tag 创建错了但还没有推送远端，可使用 `npm run release:local -- v0.1.4 --replace-local-tag` 删除并重建本地 tag；该选项不会删除远端 tag。离线环境可加 `--skip-audit` 跳过本地 `npm audit`，但 GitHub Release workflow 仍会执行审计。
+
 Plugin API 版本独立于核心版本，只在插件公共接口出现不兼容修改时递增整数主版本。插件自身使用 SemVer，并在 manifest 中强制声明 `apiVersion` 和 `minXCompilerVersion`；详细规则见 [plugin_api.md](plugin_api.md)。
 
 审计内容默认使用 `redacted` 模式遮蔽 API key、token、密码等凭据。需要最小化留存时设置 `XC_AUDIT_CONTENT_MODE=metadata`（只保留长度和 SHA-256）；只有在受控环境确实需要完整回放时才使用 `full`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcompiler/cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "XCompiler — AI Software Factory: V-model driven, multi-LLM orchestrated software development agent.",
   "license": "Apache-2.0",
   "type": "module",
@@ -40,7 +40,10 @@
     "dist/plugins",
     "dist/runtime",
     "dist/acp",
+    "config.example.yaml",
+    ".env.example",
     "docs/acp.md",
+    "docs/openrouter.md",
     "docs/plugin_api.md",
     "docs/self_bootstrap.md",
     "docs/versioning.md",
@@ -52,6 +55,7 @@
     "version:check": "node scripts/version.mjs check",
     "version:sync": "node scripts/version.mjs sync",
     "version:set": "node scripts/version.mjs set",
+    "release:local": "bash scripts/release-local.sh",
     "prepack": "npm run version:check",
     "prebuild": "npm run version:check",
     "build": "tsup",