@adep/cli 0.0.1 → 0.0.3

package/README.md

@@ -26,14 +26,26 @@
 
    - [`adep dev`](#adep-dev)
 
+   - [`adep serve`](#adep-serve)
+
    - [`adep deploy`](#adep-deploy)
 
+   - [`adep projects`](#adep-projects)
+
+   - [`adep functions`](#adep-functions)
+
+   - [`adep mcp`](#adep-mcp)
+
+   - [`adep doctor`](#adep-doctor)
+
    - [`adep db`](#adep-db)
 
    - [`adep storage`](#adep-storage)
 
    - [`adep hosting`](#adep-hosting)
 
+   - [`adep export`](#adep-export)
+
    - [`adep widget`](#adep-widget)
 
 4. [配置](#配置)
@@ -159,6 +171,19 @@ adep dev -p 3000              # 指定端口
 ...
 ```
 
+### `adep serve`
+
+开发态服务器：把函数（`/api/{fn}`）、`/healthz`、静态托管与组件预览合并到一个进程里常驻，**默认只绑回环地址，是本地开发服务器而非生产服务器**。自托管部署包内用它指向包内 `web/` 站点。
+
+```bash
+adep serve                       # 默认 127.0.0.1:8787（PORT / HOST 环境变量可覆盖）
+adep serve -p 9000               # 指定端口
+adep serve --static web          # 指定静态托管目录（缺省 public/）
+```
+
+- 缺省值优先级为「命令行旗标 > 环境变量（`PORT` / `HOST` / `ADEP_SERVE_STATIC_DIR`）> 内置缺省」，容器编排注入的 `PORT` / `HOST` 不会被命令行缺省盖掉。
+- 绑定非回环地址时给出对外暴露警告（它不带生产级加固）。
+
 ### `adep deploy`
 
 增量部署：扫描本地 `functions/` 计算内容哈希 → 调平台 `/api/v1/deploy/diff` 拿差异清单 → 仅上传变更函数 → 发布 → 输出访问域名。
@@ -172,12 +197,75 @@ adep deploy -p my-app            # 显式指定目标 slug
 
 - **幂等**：内容与已发布版本一致时输出 `no changes`，不产生新版本。
 
-- 成功输出每个函数的名字 / 版本 / 访问地址：
+- 成功输出每个函数的名字 / 版本 / 访问地址，末尾给一行汇总：
 
 ```bash
 hello  v1  https://my-app.platform.example.com/hello
+✓ 1 functions deployed in 3.2s
+```
+
+> 汇总只在**真的产生新版本**时写 `deployed`；全部复用时写
+> `✓ no changes · N functions up to date in Ts`，不把幂等说成重新发布。
+
+### `adep projects`
+
+项目子命令组：创建 / 列出 / 查看。子域地址由平台回显（`projectBaseUrl`），CLI 不自行拼域名。
+
+```bash
+adep projects create game-arcade            # → ✓ Project created · https://game-arcade.adep.top
+adep projects create game-arcade -n 游戏厅  # 展示名与 slug 分开
+adep projects list                          # slug \t name \t url
+adep projects info game-arcade              # id \t slug \t name \t url
+```
+
+- `--name` 缺省取 slug：一行命令即可建项目。
+- 目标 slug 已占用 → 平台返回 `PROJECT_SLUG_TAKEN`，CLI 原样透传并退出码 1。
+- 未登录 / 会话失效 → 打印错误后附带 `提示：先执行 adep login`。
+
+### `adep functions`
+
+云函数子命令组：部署（可指定目录）/ 列出 / 查日志。
+
+```bash
+adep functions deploy ./handlers            # 覆盖 adep.config.ts 的 functionsDir
+adep functions deploy                       # 等价于 adep deploy
+adep functions list -p my-app               # name \t 访问地址
+adep functions logs hello -p my-app --tail 50
+```
+
+- `deploy` 与 `adep deploy` 共用同一执行体，输出逐字一致（两个入口各写一遍迟早只有一处有汇总行）。
+- 日志缓冲在平台进程内（环形），**未执行过的函数为空**——命令会如实说明而非报错。
+
+### `adep mcp`
+
+MCP Tool 子命令组：把云函数发布为项目 MCP Tool / 取消发布 / 列出。发布后外部 Agent 即可通过项目 `/mcp` 端点调用你的后端能力（只消费平台既有的 `POST|DELETE /api/v1/functions/:id/mcp-publish` 与 `tools/list`，CLI 不重实现发布逻辑）。
+
+```bash
+adep mcp publish --function stock                    # → ✓ MCP tool published · stock
+adep mcp publish --function stock --name get-stock   # 以别名注册（tools/list 里出现 get-stock）
+adep mcp publish --function query-database --description "查询库存"  # 覆盖面向 Agent 的描述
+adep mcp unpublish --function stock                  # 取消发布（别名发布过则加 --name get-stock）
+adep mcp list                                        # 打印端点地址 + 已发布 tool（name \t description）
+```
+
+- `--function` 是**函数名**，`--name` 是可选的**注册 Tool 名**（缺省取函数名）；目标项目缺省取 `adep.config.ts` 的 `name`，也可用 `-p <slug>` 指定。
+- 服务端错误原样透出：函数入参无法映射为 JSON Schema 时返回 `MCP_SCHEMA_UNSERIALIZABLE` 并以退出码 1 结束（CLI 不改写、不兜底，原因由服务端指出）。
+- `mcp list` 读的是**项目 `/mcp` 端点的 `tools/list`**（与外部 Agent 同一条路径）：项目 MCP 鉴权模式为 `public` 时可直接读取；为 `api-key` 时未带 Key 会返回 `MCP_UNAUTHORIZED`。
+- `unpublish` 默认按函数名移除；若曾以别名发布，需加 `--name <tool>` 指向该别名。取消一个不存在的工具会如实说明、不报成功也不报错。
+
+### `adep doctor`
+
+环境自检：凭据状态、平台可达性、离线可用范围与本地模拟运行时的能力边界。
+
+```bash
+adep doctor
+adep doctor --json    # { server, credentials, network, serverHealth, offlineCommands, boundaries }
 ```
 
+- 已登录时体检的是**凭据里记录的那个平台**（`login --server` 可指到任意环境），未登录才回退 `ADEP_SERVER` 缺省。
+- 平台可达性 = 对 `GET /api/v1/health` 的一次真实探测；拿到任何 HTTP 应答都算可达。
+- 凭据文件权限宽于 `0600` 会给告警；命令本身**不因体检结论失败**（它是诊断，不是门）。
+
 ### `adep db`
 
 项目数据库维护子命令组：启动 / 状态 / 停止 / SQL 执行 / 快照 / 时间点回滚。项目参数缺省取 `adep.config.ts` 的 `name`（也可用 `-p` 显式指定）。
@@ -236,6 +324,19 @@ adep hosting config --enabled true --spa true    # 更新托管开关 / SPA 回
 
 - **pull**：只拉公开站点文件，private 侧载的托管配置（`site/.hosting.json`）不会进站点目录。
 
+### `adep export`
+
+导出自托管部署包：触发平台长任务 → 轮询进度 → 下载 zip → 按 manifest 逐项自检，产出一个「解压即可运行」的可部署包（含应用定义、`adep.config.ts`、Docker 产物与静态站点）。
+
+```bash
+adep export                          # 目标项目取 adep.config.ts 的 name
+adep export -p my-app --with-data    # 显式指定项目并包含数据库行数据（缺省仅 schema）
+adep export --out ./dist-export      # 指定输出目录（缺省 ./exports）
+```
+
+- `--with-data` 附带行数据，`--with-source` 附带函数源码（平台缺省已含，显式给出不改变默认）。
+- `--json` 输出单个结果信封；导出失败（长任务未产出 / 自检不过）以退出码 1 + `EXPORT_FAILED` 结束，不静默给半截产物。
+
 ### `adep widget`
 
 微前端组件（widget）的子命令组：脚手架 / 本地沙箱 / 发布。
@@ -290,15 +391,14 @@ export ADEP_HOME=~/.adep
 
 ### `adep.config.ts`
 
-`adep init` 生成的项目标识文件，CLI 的 `dev` / `deploy` 按此识别项目：
+`adep init` 生成的项目标识文件，CLI 的 `dev` / `deploy` 按此识别项目（CLI 直接 import 后读 `default` 的字段，无需任何辅助包）：
 
 ```ts
-import { defineConfig } from 'adep/config'
-
-export default defineConfig({
+// adep 项目配置：CLI（dev / deploy）按 default export 读取（name / functionsDir）。
+export default {
   name: 'my-app', // 项目名（deploy 的默认 slug）
   template: 'function', // 模板：empty | function
-})
+}
 ```
 
 ---