@aipt/cli 0.1.18 → 0.1.23

package/README.md

@@ -1,12 +1,51 @@
 # @aipt/cli
 
-业务项目首次运行 `corepack pnpm dlx @aipt/cli@latest bootstrap --project /absolute/project --apply`。它安装并锁定精确 `dyyto`、`idp`、`idpctl` 版本，从同一 Agent Policy 派生 Codex、Claude Code、Cursor 与 Antigravity 薄适配器。随后使用 `dyyto context`、`dyyto doctor`；详细规范通过 `dyyto docs show --id engineering-workflow` 读取，不复制到业务项目。
+Dyyto Engineering Platform 的正式命令行 Composition Root。CLI 负责工程能力发现、Plan、Apply、Verify、升级、恢复和移除；不承担部署控制面或在线 Portal。
 
-`dyyto integrations --project <project>` 输出 Package、公共导入、代码资产、所有权、Lock/Evidence 和未纳管依赖；增加 `--json` 可保存完整审计清单。
+## 0. 首次使用：先初始化 Sources 本地环境
+
+在安装工程工具链前，先初始化统一 pnpm Store、IDP Config Dir、业务 Config 根和 GitOps Root：
+
+```bash
+corepack pnpm dlx @aipt/idp-setup@0.1.1 init \
+  --root /Users/dyyto/Desktop/works/sources
+
+source /Users/dyyto/Desktop/works/sources/config/idp/generated/sources.env
+idp-setup doctor --root /Users/dyyto/Desktop/works/sources
+```
+
+该步骤设置 `IDP_CONFIG_DIR`、`APP_CONFIG_DIR`、`IDP_GITOPS_ROOT`、`PNPM_STORE_DIR` 和 `DYYTO_WORKBENCH_MODE`，但不创建 Secret。业务应用仍在各自的 `$APP_CONFIG_DIR/<workspace>/<application>/<environment>` 下独立管理配置。
+
+随后对要开发或改造的 Workspace/项目执行一次 Bootstrap：
+
+```bash
+corepack pnpm dlx @aipt/cli@latest bootstrap \
+  --project /absolute/workspace-or-project \
+  --apply
+
+dyyto context --project /absolute/workspace-or-project
+dyyto doctor --project /absolute/workspace-or-project
+```
+
+Bootstrap 安装并锁定精确 `dyyto`、`idp`、`idpctl` 版本，并生成 Codex、Claude Code、Cursor 与 Antigravity 的薄 Agent 入口。安装完成后只使用 npm package 声明的 bin：
+
+```bash
+dyyto --version --json
+idp --version --json
+idpctl --version --json
+```
+
+禁止绕过这些正式 bin 直接运行各仓库的源码入口。
+
+## 1. 所有场景通用的工程闭环
+
+```text
+Catalog → Plan → Review → Apply → Verify → Evidence
+```
 
-Dyyto Engineering Platform 的正式命令行 Composition Root。
+`dyyto integrations --project <project>` 输出 Package、公共导入、代码资产、所有权、Lock/Evidence 和未纳管依赖；增加 `--json` 可保存完整审计清单。
 
-CLI 是无服务入口，不包含 Portal 或在线 AI Runtime。人类与 vibe coding 代理通过同一个只读目录发现能力：
+人类与 vibe coding 代理通过同一个只读目录发现能力：
 
 ```bash
 dyyto catalog search --query typescript --kind capability --json
@@ -16,6 +55,10 @@ dyyto mcp serve
 
 MCP 使用 stdin/stdout JSON-RPC，公开 `dyyto_catalog_search` 与 `dyyto_catalog_show`，不监听端口、不读取业务数据、不执行 Catalog 中的代码。
 
+## 2. 独立项目流程
+
+适用于单独的 npm Library、React Component Library 或 Next.js Application。首次创建使用正式模板；旧项目使用 `bootstrap` 后由开发工作台或显式 `retrofit plan/apply` 纳管。
+
 首个正式工程模板：
 
 ```bash
@@ -71,6 +114,24 @@ dyyto verify --project ./my-app
 
 当前已实现稳定的 help、version、human/JSON renderer、错误退出码，以及正式 `create/plan/add feature/upgrade/apply/verify/inspect/recover`。领域规划、文件写入、验证提交与恢复必须委托给 `@aipt/platform-kernel`，不得在 CLI 内复制规则。
 
+## 3. 已有项目改造流程
+
+```bash
+dyyto bootstrap --project /absolute/legacy-project --apply
+dyyto retrofit plan --project /absolute/legacy-project \
+  --profile workspace-node-application \
+  --capability foundation.workspace-node-application@1.1.0
+dyyto retrofit apply --project /absolute/legacy-project \
+  --profile workspace-node-application \
+  --capability foundation.workspace-node-application@1.1.0 \
+  --approve <planId>
+dyyto doctor --project /absolute/legacy-project
+```
+
+Retrofit 只新增 Manifest，不静默替换业务源码和 `package.json`。
+
+## 4. 项目 Feature 与运行配置流程
+
 向已采用 Profile 的项目添加工程能力：
 
 ```bash
@@ -110,11 +171,15 @@ dyyto verify --project ./my-workspace
 
 升级 Plan 同时管理 Manifest 和 Release assets；用户修改产生 conflict，目标 Verify 成功前继续保留旧 Lock。
 
+## 5. Workspace 流程
+
+Workspace Root 统一管理 `apps/*`、`packages/*` 和共享锁；每个 Unit 仍有独立 Manifest、Lock 与 Evidence。
+
 工作区内运行：
 
 ```bash
-pnpm dyyto -- --help
-pnpm dyyto -- --version --json
+dyyto --help
+dyyto --version --json
 ```
 
 本地打包并在独立目录安装：
@@ -126,6 +191,8 @@ corepack pnpm add --ignore-scripts /absolute/path/to/aipt-cli-<version>.tgz
 
 发布包是自包含 CLI bundle，内置经过 integrity 校验的 Capability Catalog，不依赖 Dyyto workspace link。
 
+## 6. Package 流程
+
 创建独立 npm 包：
 
 ```bash
@@ -161,6 +228,8 @@ dyyto add package \
 
 Root 和 Unit 各自审批 Plan、提交 Evidence/Lock；依赖只需在 workspace root 安装一次，Unit 不生成嵌套 workspace。
 
+## 7. Application 流程
+
 新增可运行 Node Application：
 
 ```bash
@@ -186,6 +255,21 @@ dyyto add application \
 
 Web Application 锁定 React 19、Vite 8 和 TypeScript 6 的精确版本。Verify 会执行 typecheck、jsdom 组件测试、production build 与随机回环端口 preview smoke；人工验收使用 Unit 的 `dev` script。
 
+## 8. 交付与部署流程
+
+本地 Application 配置先通过 `idpctl app config-init` 物化到 `$APP_CONFIG_DIR`，然后再生成和应用部署 Plan：
+
+```bash
+idpctl app config-init \
+  --project /absolute/workspace/apps/api \
+  --workspace-root /absolute/workspace \
+  --environment local
+
+idp local app plan --project /absolute/workspace/apps/api --environment local
+idp local app apply --project /absolute/workspace/apps/api --environment local --approve <planId>
+idp local app verify --project /absolute/workspace/apps/api --environment local
+```
+
 Artifact Delivery：
 
 ```bash