@zhuoyuezs/ml-platform 0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,189 @@
+# ML Platform 开发指南
+
+本文定义 `@zhuoyuezs/ml-platform` 的 npm v2 架构、实施状态和完成标准。
+
+## 1. 已确定的架构决策
+
+- npm 是 CLI 与 Skill 的唯一正式分发和安装边界。
+- 不支持裸 Skill 目录或 ZIP 作为正式交付渠道。
+- Business CLI 与 Skill 是并列组件；CLI 不属于 Skill。
+- Skill 直接调用正式命令 `ml-platform`，不嵌入 CLI runtime。
+- 正式 npm 包只有 `@zhuoyuezs/ml-platform`，正式 bin 只有 `ml-platform`。
+- `business-client-js/` 是 CLI 唯一源码，`skills/feature-management/` 是 Skill 唯一源码。
+- `npx @zhuoyuezs/ml-platform@<version> install` 是统一安装入口。
+- npm `postinstall` 不得修改 Agent Skills 目录。
+- Python business client 只保留为迁移 oracle，不进入 release。
+- Codex CLI 不重新打包；当前只支持唯一自研 Host。
+
+## 2. 源码与归档
+
+源码：
+
+```text
+business-client-js/
+skills/feature-management/
+npm/ml-platform/
+npm/scripts/build_ml_platform_release.py
+agent_poc/codex-host/
+```
+
+归档：
+
+```text
+package/
+├── package.json
+├── scripts/
+│   ├── main.js
+│   └── lib.js
+├── runtime/business-client/
+├── skills/feature-management/
+├── release.json
+├── checksums.json
+├── README.md
+└── DEVELOPMENT.md
+```
+
+严格 `files` allowlist 必须排除 `node_modules`、测试 oracle、旧 wheel、Skill runtime、旧 wrapper、
+Host 副本、日志、会话数据、attic、凭证和实验文件。
+
+## 3. Step-by-step 实施计划
+
+每一步单独实现、补测试并验收；上一阶段未通过时不进入下一阶段。
+
+### Step 1：完成 business-client-js 迁移（已完成）
+
+- 补齐全部 Python CLI 命令和参数契约；
+- 对齐 JSON stdout、stderr 和退出码；
+- 补齐数值参数、子命令 help、路径展开和 HTTP 错误测试；
+- 扩大 Catalog normalization differential tests；
+- 完成 Job、Artifact、inference 和 Operator upload 负向测试；
+- 删除正式运行路径中的旧产品名兼容；
+- 独立执行 `npm pack --dry-run`、clean install 和 CLI smoke test。
+
+完成标准：Python 只剩 oracle 作用，正式 CLI 不需要 Python、`uv` 或第三方 npm runtime 依赖。
+
+### Step 2：重建纯 feature-management Skill（已完成）
+
+- 保留 `SKILL.md`、`agents/`、`references/` 和 `assets/catalog-template/`；
+- 删除 `runtime/business-client-js/`、`assets/wheels/`、Skill installer 和 CLI launcher；
+- 所有命令示例改为直接调用 `ml-platform`；
+- 明确 CLI 是外部 prerequisite，并提供 `ml-platform --help` 自省路径；
+- 更新 `agents/openai.yaml`；
+- 在隔离临时目录把已验收的本地 business CLI 暴露为 `ml-platform`，不依赖最终 npm 安装器；
+- 运行 Skill 结构校验和真实任务 forward tests。
+
+完成标准：Skill tree 中没有 business CLI 或安装逻辑，Agent 在存在匹配 CLI 时能完成只读工作流。
+
+### Step 3：固定 npm v2 安装契约（已完成）
+
+只有 Step 1 和 Step 2 都完成后，才开始 npm dispatcher/installer：
+
+- 定义 `release.json` v2 和 `checksums.json` 覆盖范围；
+- 确定 `runtime/business-client` 与 `skills/feature-management` 并列目录；
+- 定义 `ml-platform` 安装管理命令和业务命令的无歧义分发；
+- 定义 `npx ... install` 如何建立持久 CLI，禁止引用一次性 npx cache；
+- 定义 CLI home、shim、PATH 检查和跨平台失败行为；
+- 定义 ownership、安装记录、upgrade、downgrade 和 rollback；
+- 先写聚焦测试，再修改当前安装器。
+
+完成标准：测试能够证明新安装器在删除 npx cache 和新 shell 环境中仍可解析 `ml-platform`。
+
+### Step 4：重构 release builder（已完成）
+
+- 从 `business-client-js` 复制唯一 client tree 到 `runtime/business-client`；
+- 从 canonical Skill 复制纯 Skill 到 `skills/feature-management`；
+- 生成 release v2 和 checksums；
+- 拒绝多份 client、Skill runtime、旧 wheel 和未知文件；
+- 执行 npm package allowlist 和可重现 digest 检查；
+- 不修改 canonical source 或 `dist/package` 之外的生成目录。
+
+完成标准：最终 npm archive 只有一份 CLI tree，Skill tree 与 canonical source 字节级一致。
+
+### Step 5：重构顶层 CLI 与安装器（已完成）
+
+- `install/upgrade/status/doctor` 进入 installer；
+- 全部业务命令进入同一 business client；
+- 未知命令和参数返回结构化非零错误；
+- 安装事务支持 staging、lock、ownership 和 rollback；
+- `status` 报告 CLI release、Skill revision、scope 和路径；
+- `doctor` 校验 package、CLI、Skill、record、PATH 和可选 API health；
+- 禁止隐式降级和覆盖非本包管理的 Skill。
+
+完成标准：install、幂等、upgrade、downgrade、rollback、篡改和锁竞争测试全部通过。
+
+### Step 6：Agent Host（当前不在范围内）
+
+当前阶段不修改或打包 Agent Host。`@zhuoyuezs/ml-platform` builder 只产出 Skill + CLI 主包；Host
+需要后续明确需求后再单独设计和验收。
+
+### Step 7：Skill + CLI 端到端发布验收（已完成）
+
+- `git diff --check -- npm business-client-js skills/feature-management agent_poc/codex-host`；
+- JS business-client tests；
+- Python oracle tests；
+- Skill validator 和 forward tests；
+- npm installer tests；
+- release builder；
+- `npm pack --dry-run`；
+- `.tgz.sha256`；
+- clean npx install，删除 npx cache 后重测；
+- `status`、`doctor` 和只读业务命令；
+- Codex project/user scope 和显式 Skills 目录；
+- 最终归档敏感文件和重复 client 检查。
+
+完成标准：同一个不可变 `.tgz` 通过全部验收。仍不执行 npmjs 或其他外部发布。
+
+## 4. package.json
+
+```json
+{
+  "name": "@zhuoyuezs/ml-platform",
+  "version": "0.1.0",
+  "bin": {
+    "ml-platform": "scripts/main.js"
+  },
+  "files": [
+    "scripts",
+    "runtime",
+    "skills",
+    "release.json",
+    "checksums.json",
+    "README.md",
+    "DEVELOPMENT.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}
+```
+
+不得配置用于安装 Skills 的 `postinstall`。
+
+## 5. Release v2 约束
+
+release manifest 必须记录：
+
+- ML Platform release version；
+- source commit；
+- CLI name、version、path、entrypoint 和 tree digest；
+- Skill revision、path、CLI compatibility range 和 tree digest；
+- Agent adapters；
+- Node.js 要求和 API compatibility contract；
+- 不参与组件 digest 的生成时间。
+
+`checksums.json` 覆盖 `runtime/` 和 `skills/` 全部文件，按路径排序并使用 canonical JSON。
+
+## 6. 安全与发布限制
+
+- 不将凭证写入 npm 包、Skill、安装记录或测试 fixture；
+- 不在安装时访问或修改 ML Platform Registry；
+- 远程验收只执行获批的只读命令；
+- 不发布模型训练、模型服务、Kubernetes 或平台服务端；
+- 正式 npm 发布必须从 builder 生成的 `dist/package/` 执行 `npm publish --access public`；
+- 不执行 GitHub Release 或其他未授权的外部发布；
+- candidate 验证后不得用相同版本重新构建不同内容。

package/README.md

@@ -0,0 +1,103 @@
+# ML Platform
+
+`@zhuoyuezs/ml-platform` 通过一个 npm 产品提供 JavaScript business CLI 和
+`feature-management` Agent Skill。
+
+正式包名和命令固定为：
+
+```text
+package: @zhuoyuezs/ml-platform
+bin:     ml-platform
+```
+
+> 当前状态：`0.1.0` release candidate 已实现 release v2 的外部 CLI + 纯 Skill 架构，并通过
+> 干净安装、cache 删除、`status`、`doctor` 和摘要验证。当前范围仅包含 Skill + CLI，不打包
+> Agent Host。正式发布必须从 `dist/package/` 执行 `npm publish`。
+
+## 组件关系
+
+```text
+开发人员 / CI
+  -> ml-platform CLI
+  -> ML Platform API
+
+Codex / ml-platform-host
+  -> feature-management Skill
+  -> ml-platform CLI
+  -> ML Platform API
+```
+
+- CLI 可以独立运行，不依赖 Skill。
+- Skill 负责工作流程、业务契约和安全边界，直接调用 `ml-platform`。
+- npm release 同时固定 CLI version 和 Skill revision。
+- Skill 不再携带 business CLI、Python wheel、bootstrap 或安装器。
+- Codex CLI 和唯一自研 Host 是并行入口，都不进入本 npm 包。
+
+## 包结构
+
+```text
+@zhuoyuezs/ml-platform/
+├── package.json
+├── scripts/
+├── runtime/business-client/
+├── skills/feature-management/
+├── release.json
+├── checksums.json
+├── README.md
+└── DEVELOPMENT.md
+```
+
+归档中只有 `runtime/business-client/` 一份 business CLI。`skills/feature-management/` 是纯
+Skill，与 CLI 并列。
+
+## 安装体验
+
+参考飞书 CLI，正式入口使用显式版本化 npx 命令：
+
+```bash
+npx @zhuoyuezs/ml-platform@<version> install \
+  --agent codex \
+  --scope project \
+  --project-dir /absolute/path/to/project
+```
+
+安装命令必须建立可持续使用的 `ml-platform` 命令，再把纯 Skill 安装到目标 Agent 目录。它不能
+依赖一次性 npx cache，也不能通过 npm `postinstall` 修改用户 Skills。
+
+默认 runtime 位于 `~/.local/share/ml-platform/current/`，shim 位于
+`~/.local/bin/ml-platform`。安装结果中的 `path_ready` 和 `path_setup` 会说明是否还需把 bin
+目录加入 PATH。隔离测试可显式传入 `--state-dir` 和 `--bin-dir`。
+
+安装后：
+
+```bash
+ml-platform version
+ml-platform status --agent codex --scope project --project-dir /absolute/path/to/project
+ml-platform doctor --agent codex --scope project --project-dir /absolute/path/to/project
+
+ml-platform configure --api-url http://<approved-host>:<port>
+ml-platform health
+```
+
+## Canonical Source
+
+```text
+business-client-js/                 JavaScript CLI 唯一源码
+skills/feature-management/          Skill 唯一源码
+npm/ml-platform/                    npm dispatcher 与 installer 唯一源码
+npm/scripts/build_ml_platform_release.py
+agent_poc/codex-host/               唯一自研 Host
+```
+
+不要修改 `dist/`、临时安装目录或 Agent Skills 安装副本。Python `business-client/` 只保留为迁移
+oracle，不进入 npm release。
+
+## 当前开发状态
+
+1. `business-client-js` parity 与纯 `feature-management` Skill 已完成并独立验收。
+2. npm v2 builder、dispatcher、持久 installer、ownership、digest 与回滚已完成。
+3. 新的本地 `.tgz`、`.tgz.sha256` 和 Codex project clean install smoke 已通过。
+4. Agent Host 当前不在本包构建范围内；后续需明确需求后单独推进。
+
+完整约束见 [DEVELOPMENT.md](DEVELOPMENT.md) 和
+[`npm/docs/AGENT_SKILL_CLI_PACKAGING_ARCHITECTURE.md`](../docs/AGENT_SKILL_CLI_PACKAGING_ARCHITECTURE.md)。

package/checksums.json

@@ -0,0 +1,110 @@
+{
+  "files": [
+    {
+      "path": "runtime/business-client/README.md",
+      "sha256": "sha256:165a2bd2bb51b61e0967b0b75fb51840b18e825fcf3198c7eee73cc74565ae5d",
+      "size_bytes": 637
+    },
+    {
+      "path": "runtime/business-client/package-lock.json",
+      "sha256": "sha256:d35849fa8c24520e4a33e18aa0366fb8d453a5df55516b45e9561db5e18cbedd",
+      "size_bytes": 381
+    },
+    {
+      "path": "runtime/business-client/package.json",
+      "sha256": "sha256:990c111ce4d345c660ec1136b81ac71f161217abf7716358d64bc8e1ac979c15",
+      "size_bytes": 426
+    },
+    {
+      "path": "runtime/business-client/src/catalog.js",
+      "sha256": "sha256:33b5da9f4b7fc200b1c5cee38d18fcec56bb2b2b022a473d8f8f47441ea2fb7b",
+      "size_bytes": 51193
+    },
+    {
+      "path": "runtime/business-client/src/cli.js",
+      "sha256": "sha256:0e344399795bb0c7804c057b6063f7e6d3720a7f4fe0cf8400fa362d62d03f56",
+      "size_bytes": 15765
+    },
+    {
+      "path": "runtime/business-client/src/config.js",
+      "sha256": "sha256:81022c2fc2a21cac8a12fd2c93b5defa18665a4d4a583a86e9eb54587650f47b",
+      "size_bytes": 1960
+    },
+    {
+      "path": "runtime/business-client/src/http.js",
+      "sha256": "sha256:0744596f8ae0beb60f317c06eccd87f3d5d0dc0ccba15668432a7a47c692aec9",
+      "size_bytes": 9450
+    },
+    {
+      "path": "skills/feature-management/SKILL.md",
+      "sha256": "sha256:5a5c935296b245a0f480dce967d122ff1085d543831b8ce6077e4959f658f5e4",
+      "size_bytes": 17823
+    },
+    {
+      "path": "skills/feature-management/agents/openai.yaml",
+      "sha256": "sha256:a4c69cb062dc52749f0c0c96ad2d16f91f83ecedb44f78dcf662ef220273f24d",
+      "size_bytes": 325
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/catalog.json",
+      "sha256": "sha256:b2bf887040479082d8f09e5d1027b5a98c7a02b14a784dbb170c29568f14304d",
+      "size_bytes": 606
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/datasets/example_temperature_training.v1.json",
+      "sha256": "sha256:c4b4c811cd7dc90ba014e3be0b38fdc357bc83c224e5df614ab9168ce7fbcc0c",
+      "size_bytes": 562
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/feature_sets/example_temperature_core.v1.json",
+      "sha256": "sha256:bca7e24927d8aef2fc7f48df327bf56a25c77591332b97b0d2a548708126ec88",
+      "size_bytes": 315
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/features/example_temperature_mean_5m.v1.json",
+      "sha256": "sha256:36eb3878125e337bf2afced7b363c56833266a529ce311fffd8f8b146f361739",
+      "size_bytes": 572
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/operator_package/pyproject.toml",
+      "sha256": "sha256:df8b4087cb20ecd86736fc69d013a665e7c3dfa7dab80ffbc23279158dae5451",
+      "size_bytes": 295
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/operator_package/src/business_feature_operator_template/__init__.py",
+      "sha256": "sha256:46a572cbd603299cb18692548480462208ec7b2696ba4f2fd90e1b15697e1a4b",
+      "size_bytes": 1366
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/operator_package/tests/test_operator.py",
+      "sha256": "sha256:b758f343225365cf8361ae6c7a7e130502d339cc4ffe2be13d75c728ce9ec71a",
+      "size_bytes": 1842
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/operators/example_temperature_features.v1.json",
+      "sha256": "sha256:5d188372b2c7721c95bd91bdaa871368fca1ce5d43965db22494ee8c895fa516",
+      "size_bytes": 916
+    },
+    {
+      "path": "skills/feature-management/assets/catalog-template/parameters/example_temperature.v1.json",
+      "sha256": "sha256:df65f46f67b320d7edf940c8f11d153f0869ecfc52fc4336f31358f6ecc7783d",
+      "size_bytes": 1451
+    },
+    {
+      "path": "skills/feature-management/references/commands.md",
+      "sha256": "sha256:4840af5c181ee3b9596548686f2eca2ca7a4acfcd6adcd9afa01f447187ea659",
+      "size_bytes": 8812
+    },
+    {
+      "path": "skills/feature-management/references/contracts.md",
+      "sha256": "sha256:b15cf8e0379c9ac2d0ecbc70a63635472da91956c3917318593cd5dc1f93695a",
+      "size_bytes": 26166
+    },
+    {
+      "path": "skills/feature-management/references/operator-authoring.md",
+      "sha256": "sha256:c2afb155a1c3379935f70fe0b68c1918a58a790ee470bea2b7516f54502c6ca0",
+      "size_bytes": 5510
+    }
+  ],
+  "schema_version": "data_platform.ml_platform_checksums/v1"
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@zhuoyuezs/ml-platform",
+  "version": "0.1.0",
+  "description": "ML 数据平台 business CLI 与 Agent Skills 管理工具",
+  "bin": {
+    "ml-platform": "scripts/main.js"
+  },
+  "files": [
+    "scripts",
+    "runtime",
+    "skills",
+    "release-policy.json",
+    "release.json",
+    "checksums.json",
+    "README.md",
+    "DEVELOPMENT.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/release-policy.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": "data_platform.ml_platform_release_policy/v1",
+  "forbidden_directories": [
+    ".git",
+    "__pycache__",
+    "attic",
+    "dist",
+    "node_modules",
+    "runtime",
+    "sessions",
+    "tmp"
+  ],
+  "forbidden_files": [
+    ".DS_Store",
+    ".env",
+    ".netrc",
+    ".npmrc",
+    "credentials.json",
+    "runtime.json",
+    "token.json"
+  ],
+  "forbidden_suffixes": [
+    ".key",
+    ".log",
+    ".pem",
+    ".pyc",
+    ".sqlite",
+    ".sqlite3",
+    ".whl"
+  ]
+}

package/release.json

@@ -0,0 +1,42 @@
+{
+  "agent_adapters": [
+    "codex-user",
+    "codex-project",
+    "explicit-skills-dir"
+  ],
+  "api_compatibility": {
+    "contract": "current-unversioned",
+    "health_check_required": true,
+    "note": "The deployed API does not yet expose a machine-readable API version."
+  },
+  "cli": {
+    "entrypoint": "src/cli.js",
+    "name": "ml-platform",
+    "path": "runtime/business-client",
+    "sha256": "sha256:6a43efb51ba1f878b11537d63e79c04cb798e7f456cb29f87fd0aac742794fdd",
+    "version": "0.5.0"
+  },
+  "policy_sha256": "sha256:fe4d32b6b7b955061a93731eb25eca1727af6c2b9db79339b5e1fd55f6a2ada4",
+  "public_schema_versions": [
+    "ml_data_platform.catalog/v1",
+    "ml_data_platform.parameter/v1",
+    "ml_data_platform.operator/v1",
+    "ml_data_platform.feature/v1",
+    "ml_data_platform.feature_set/v1",
+    "ml_data_platform.dataset_manifest/v1"
+  ],
+  "release_version": "0.1.0",
+  "runtime_requirements": {
+    "node": ">=18"
+  },
+  "schema_version": "data_platform.ml_platform_release/v2",
+  "skills": {
+    "feature-management": {
+      "path": "skills/feature-management",
+      "requires_cli": ">=0.5.0 <0.6.0",
+      "revision": "0.1.0",
+      "sha256": "sha256:f7c2ba836338602f6f01ebec18b595a366f5dd1bcbfcb58e249cda5c10bd61dd"
+    }
+  },
+  "source_commit": "0a124d08d6d35f07b6bd90bb37fd81ff0f698ab7"
+}

package/runtime/business-client/README.md

@@ -0,0 +1,14 @@
+# Business Client JS
+
+`business-client/` 的 JavaScript 迁移实现。Python client 目前仅作为迁移期 parity oracle；
+本目录是业务 CLI 的唯一 JavaScript 实现源码，Skill 通过外部 `ml-platform` 命令调用它，
+不复制或内嵌本目录的 runtime。
+
+```bash
+npm test --prefix business-client-js
+node business-client-js/src/cli.js --help
+```
+
+当前包保持 `private: true`，用于独立开发、测试和迁移验证，不作为第二个正式 npm 产品发布。
+正式 npm 封装阶段会把这份源码作为 `@zhuoyuezs/ml-platform` 的唯一 CLI runtime，并继续只暴露
+`ml-platform` 命令。

package/runtime/business-client/package-lock.json

@@ -0,0 +1,19 @@
+{
+  "name": "@zhuoyuezs/ml-platform-business-client",
+  "version": "0.5.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@zhuoyuezs/ml-platform-business-client",
+      "version": "0.5.0",
+      "license": "UNLICENSED",
+      "bin": {
+        "ml-platform": "src/cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

package/runtime/business-client/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@zhuoyuezs/ml-platform-business-client",
+  "version": "0.5.0",
+  "private": true,
+  "description": "JavaScript parity implementation of the ML Platform business client",
+  "bin": {
+    "ml-platform": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "dependencies": {}
+}