@margay/ccl-core 1.5.1-alpha.5 → 1.5.1-alpha.6

package/docs/cli-installation.md

@@ -1,37 +1,36 @@
 # CLI installation and upgrades
 
-For `1.4.5-rc.10`, use Node.js `>=22.19.0`. This matches the declared minimum of
+For CCL 1.5.1, use Node.js `>=22.19.0`. This matches the declared minimum of
 the pinned `undici 8.0.2` runtime dependency; the earlier Node 20 declaration no
 longer applies. macOS Node/Bun verification does not imply Windows verification.
 
-Starting with `1.4.5-rc.10`, CCL declares `ccl` and `margay` as names for the same
-`dist/cli.js`. Both names must report the package version and provide the same
-options. The `1.4.5-rc.9` package declares only
-`margay`. Installing that existing version will not add `ccl`.
+Starting with `1.5.1-alpha.6`, `@margay/ccl-core` provides only `ccl`.
+Earlier releases from `1.4.5-rc.10` through `1.5.1-alpha.5` also provided a
+`margay` alias. The independent `@margay/cli` package will own `margay` on the
+1.8 cleanhouse line. Upgrade an old dual-entry CCL installation first, before
+installing that independent package. Scripts intended to run CCL should use `ccl`.
 
 ## Global and project installs
 
-For a terminal command available outside a project, install the desired released
-version globally:
+For a terminal command available outside a project, install the released version
+explicitly (the `latest` tag is not advanced by alpha releases):
 
 ```sh
-npm install --global @margay/ccl-core@latest
-margay --version
+npm install --global @margay/ccl-core@1.5.1-alpha.6
+ccl --version
 ```
 
-After installing a release with both entries, also run `ccl --version`. Both
-outputs must match the installed package's version. Global installation does not
-replace a CLI embedded in Margay Desktop or already loaded by a running process.
+The expected output is `1.5.1-alpha.6 (CCL)`. Global installation does not replace
+a CLI embedded in Margay Desktop or already loaded by a running process.
 
 Without `--global`, npm installs a project dependency. Run that copy explicitly:
 
 ```sh
-npm install @margay/ccl-core@latest
-./node_modules/.bin/margay --version
+npm install @margay/ccl-core@1.5.1-alpha.6
+./node_modules/.bin/ccl --version
 ```
 
-Releases with both entries also provide `./node_modules/.bin/ccl`. A successful
-project install does not upgrade commands elsewhere on the shell's PATH.
+A successful project install does not upgrade commands elsewhere on the shell's PATH.
 
 ## Migrating old custom launchers (macOS/Linux)
 
@@ -56,13 +55,14 @@ There are two distinct cases:
   resolved entry. Back up the specific obsolete CCL wrapper, or update an explicit
   alias/function to use the npm entry. Ensure the npm prefix's `bin` directory is
   on PATH. Refresh the shell command cache (`rehash` in zsh, `hash -r` in bash),
-  then verify both commands again from outside the source checkout.
+  then verify the intended command again from outside the source checkout.
 
 Keep each backup until the new commands work. To roll back a custom wrapper,
 restore its saved bytes at the original path after inspecting what currently
 occupies that path. For an npm-managed installation, install the previous exact
-version. Future npm upgrades manage both links once the custom wrappers have
-been migrated.
+version. Future npm upgrades manage the CCL link once its custom wrapper has been
+migrated. Do not reinstall a dual-entry CCL version over an independent Margay
+installation; its old alias would conflict with the other product.
 
 ## Checking a release tarball
 
@@ -75,7 +75,8 @@ node tests/package-cli-install.mjs /path/to/artifacts/candidate.tgz /path/to/pre
 
 The smoke test uses isolated install prefixes, HOME/configuration and cache. It
 checks fresh global and project installs, upgrade from the previous tarball,
-both commands through PATH, matching executable/version/help, an unmanaged-file
+the `ccl` command through PATH, matching executable/version/help, removal of the
+old `margay` alias during upgrade, an unmanaged-file
 collision, backup migration and PATH shadowing. Dependency lifecycle scripts are
 disabled; this verifies CLI installation and startup, not native dependency or
 model behavior. It currently runs on POSIX; Windows `.cmd`/PowerShell launchers
@@ -86,7 +87,7 @@ require a Windows run. It cleans its temporary installations even on failure.
 Set an absolute, private configuration directory **before starting** each process:
 
 ```sh
-CCL_CONFIG_DIR=/absolute/path/to/isolated-config margay
+CCL_CONFIG_DIR=/absolute/path/to/isolated-config ccl
 ```
 
 `CCL_CONFIG_DIR` takes precedence over the compatible `CLAUDE_CONFIG_DIR` variable.
@@ -114,7 +115,7 @@ need to authenticate separately in its own directory.
 
 This describes the local #46 source change; use a candidate/release containing
 that change before relying on the new HOME-only behavior. The Margay website
-account vault uses its own configuration-scoped references, and `margay auth logout`
+account vault uses its own configuration-scoped references, and `ccl auth logout`
 targets that website account, not the old OAuth Keychain. These tests use an
 injected fake vault and OAuth receiver; they do not log out a real account.
 

package/docs/gateway-vision-capabilities.md

@@ -0,0 +1,38 @@
+# Gateway 视觉能力声明（CCL 1.5.1-alpha.6）
+
+CCL `1.5.1-alpha.6` 包含本文的动态能力消费实现；Gateway #28 的契约仍待网关确认与部署联合验证。`1.5.1-alpha.5` 修复了本地图片读取路径，但不包含本文的动态能力消费。
+
+## 返回形式
+
+模型目录 `GET /v1/models` 的每个 `data[i]` 可包含：
+
+```json
+{"id":"selected-model","capabilities":{"vision":true,"version":"catalog-v1"}}
+```
+
+`POST /v1/capabilities/resolve` 顶层 `capabilities` 绑定 `resolved_model`；每个 `eligible_candidates[i].capabilities` 只描述该候选，不能将首候选的值复制给其它候选。`vision` 必须为 JSON 布尔值；`version` 为非空、无控制字符且不超过 256 字符的不透明字符串。可选字段缺失或畸形不使整个路由失效。顶层与首候选布尔值冲突时，当前视觉声明为未知。
+
+实际推理响应使用同一次实际路由的响应头：
+
+```http
+X-Effective-Vision: true
+X-Margay-Served-Model: actual-model
+X-Margay-Served-Deployment: actual-deployment
+X-Margay-Capability-Version: deployment-v2
+```
+
+`X-Effective-Vision` 只接受 `true` 或 `false`；未知时省略。缺少或非法的视觉值、版本、实际模型或部署标识会使这次视觉观察成为未知。现有上下文窗口和最大输出响应头语义不变。
+
+## CLI 如何使用
+
+首请求优先使用当前路由解析声明，否则使用目录声明。实际响应会修正同一会话后续请求的视觉提示；缺失响应头会清除先前支持判断，不退回旧目录的 `true`。模型、账号、网关、路由与选模代际隔离；晚到请求不能覆盖更新的选择。没有路由 context 的旧网关按 main、视觉专员、compactor 等用途隔离声明。
+
+声明由固定枚举文本写入实际模型请求的 system，并进入 token 预算，不复制版本或凭据到提示中。支持声明不是图片已经送达或已经理解的证明；不支持时建议使用已有视觉专员，未知时保持不确定。这里不会自动切换主模型、移除图片或增加权限拦截。
+
+目录读取沿用 5 秒超时；失败后视觉查询按账号短暂退避 30 秒。旧网关无此接口或无字段时，普通对话仍可继续。视觉状态仅存在于当前进程内，不持久化旧能力判断。
+
+## 验证边界
+
+`gateway-vision-capabilities` 和 `gateway-vision-contract` 用例验证解析、隔离、晚到结果、预算及双协议专员；`gateway-vision-request` 验证实际 HTTP 请求与模型覆盖；`gateway-vision-cli` 用构建后的 CLI 验证 resolve → 会话 → 请求头/提示透传、后续响应修正、切换模型和旧网关/目录超时。
+
+受控字段代理连接真实模型的读图试验，分别验证主模型直接读图、主模型调用视觉专员和能力未知时的行为。代理注入的声明只证明客户端消费链，不能作为网关已经按本契约返回真实部署能力的证据。联合验收应使用部署后的网关重复这些场景，再确认发布版本。

package/docs/releases/1.5.1-alpha.6.md

@@ -0,0 +1,24 @@
+# 1.5.1-alpha.6
+
+本预发布版在 [1.5.1-alpha.5](1.5.1-alpha.5.md) 基础上接收并使用网关视觉能力声明。使用 `alpha` 标签分发，`latest` 不变。发布后安装指定版本：
+
+```sh
+npm install -g @margay/ccl-core@1.5.1-alpha.6
+ccl --version
+```
+
+## 视觉能力接入（#62，客户端交付）
+
+CCL 从模型目录和路由解析读取版本化视觉声明，再用实际推理响应头刷新后续请求。声明按网关、账号、模型、路由、用途和请求代际隔离，晚到响应不会覆盖新的选择。固定的支持、不支持或未知说明进入模型请求及 token 预算，不按模型名猜测，也不自动更换主模型。
+
+旧网关缺接口、字段缺失或声明非法时保持未知；普通对话继续。目录请求有 5 秒超时，视觉目录失败后退避 30 秒。首次模型校验与视觉目录查询可能分别等待，合计约 10 秒。能力支持不等于图片已送达或已被理解；本地图片校验和视觉专员延续上一版行为。
+
+字段及响应头的完整格式见[网关视觉契约](../gateway-vision-capabilities.md)。客户端已验证受控 HTTP 链路及连接真实模型的字段代理；网关真实部署仍须联合验收。本版不宣称网关 #28 已上线，也不据此关闭整体 #62。
+
+## 命令归属与兼容
+
+本包从此版起只提供 `ccl`，版本输出标识为 `CCL`。旧版 `margay` 别名退出本包；后续独立的 `@margay/cli` 提供 `margay`，属于 1.8 cleanhouse 产品线，不包含在本次安装中。
+
+已有双入口版本应先升级 CCL，再安装独立 Margay 包。不要用 `--force` 覆盖未知命令；先检查 `type -a ccl margay`，备份并调整自己创建的旧包装脚本。CCL 的原配置、凭据、会话与 SDK 包名保持不变。旧脚本调用 CCL 时应改用 `ccl`。
+
+SDK/桌面宿主需升级实际嵌入的 CLI 与 SDK；全局安装不会替换宿主内置版本。运行中的会话和 daemon 需正常退出后重启。回退可安装此前确切版本，但旧版双入口会与独立 Margay 命令冲突；两包并存时先处理命令归属，不覆盖另一产品。回退不会撤销已发生的业务操作。

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@margay/ccl-core",
-  "version": "1.5.1-alpha.5",
+  "version": "1.5.1-alpha.6",
   "description": "CCL agent runtime for Margay integration",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "bin": {
-    "ccl": "dist/cli.js",
-    "margay": "dist/cli.js"
+    "ccl": "dist/cli.js"
   },
   "files": [
     "dist/cli.js",
@@ -57,7 +56,9 @@
     "docs/releases/1.5.1-alpha.2.md",
     "docs/releases/1.5.1-alpha.3.md",
     "docs/releases/1.5.1-alpha.4.md",
-    "docs/releases/1.5.1-alpha.5.md"
+    "docs/releases/1.5.1-alpha.5.md",
+    "docs/releases/1.5.1-alpha.6.md",
+    "docs/gateway-vision-capabilities.md"
   ],
   "engines": {
     "node": ">=22.19.0"