licell 0.10.12 → 0.12.0

package/README.en.md

@@ -168,7 +168,7 @@ Licell has three main state layers:
 | Type | Default location | Purpose |
 |------|------------------|---------|
 | Global auth | `~/.licell-cli/auth.json` | Alibaba Cloud credentials and default region |
-| Project state | `<project>/.licell/project.json` | app name, envs, network, deploy state |
+| Project state | `<project>/.licell/project.json` | app name, envs, network, deploy state; can also be a workspace file for multiple components in one repo |
 | MCP project config | `<project>/.mcp.json` | MCP discovery for Claude / Codex / Cursor |
 
 Compatibility notes:
@@ -176,6 +176,38 @@ Compatibility notes:
 - Licell still supports some legacy `~/.ali-cli/*` paths
 - current canonical global path is `~/.licell-cli/*`
 
+### Workspace / Monorepo
+
+If one repository contains multiple deployable directories (for example `apps/web` for a static site
+plus `apps/api` for an FC API), prefer a workspace-style root `.licell/project.json`:
+
+```json
+{
+  "defaultComponent": "api",
+  "components": {
+    "web": {
+      "path": "apps/web",
+      "appName": "demo-web",
+      "deployType": "static",
+      "dist": "dist",
+      "domain": "www.example.com"
+    },
+    "api": {
+      "path": "apps/api",
+      "appName": "demo-api",
+      "deployType": "api",
+      "runtime": "nodejs22",
+      "entry": "src/index.ts",
+      "target": "prod"
+    }
+  }
+}
+```
+
+- Running `licell deploy` inside `apps/web` resolves the `web` component automatically.
+- Running `licell deploy` inside `apps/api` resolves the `api` component automatically.
+- After a successful deploy, Licell now persists stable deploy intent back into the matched component (for example `domain`, `domainSuffix`, `entry`, `dist`, `target`, `enableCdn`, `enableSSL`, `useVpc`) instead of only writing a very small subset of fields.
+
 ## Team Auth Distribution
 
 When only a small set of people in a team directly hold high-privilege AK/SK credentials, it is often cleaner to separate “authorization” from “daily usage”:
@@ -258,6 +290,7 @@ If you want Claude Code, Codex, Cursor, or other agents to call Licell directly
 
 ```bash
 licell setup
+licell setup --agent codex
 licell setup --agent codex --global
 licell setup --agent claude --global
 ```
@@ -296,8 +329,13 @@ If you want the agent to have a richer task-oriented instruction surface inside
 ```bash
 licell skills init codex
 licell skills init claude
+licell skills init codex --global
 ```
 
+By default, `skills init` writes into the current project. Use `--global` only when you explicitly want user-level global skills.
+
+`licell setup` is the interactive wrapper, but it reuses the same underlying skills write flow.
+
 Skills, MCP, help, and docs are meant to stay aligned through the shared command model.
 
 ---

package/README.md

@@ -9,7 +9,7 @@ Licell 是一个面向阿里云的部署与运维 CLI，同时兼顾人类用户
 - 一个主入口：`deploy`
 - 一份项目状态：`.licell/project.json`
 - 一套可组合的资源原子命令：`fn` / `oss` / `dns` / `domain`
-- 一套面向 Agent 的统一表面：`--help` / `--output json` / `mcp` / `skills`
+- 一套面向 Agent 的统一表面：`catalog` / `--help` / `--output json` / `skills`
 
 默认地域为 `cn-hangzhou`。用于 Agent 自动化时，建议使用独立测试账号或独立地域，不要直接共用生产环境。团队协作下，推荐采用后文的“团队授权分发”模式。
 
@@ -20,17 +20,18 @@ Licell 是一个面向阿里云的部署与运维 CLI，同时兼顾人类用户
 如果你把 Vercel CLI 的“单主线体验”搬到阿里云，大致就是 Licell 想做的事情：
 
 - **人类友好**：`init -> deploy -> release -> rollback`
-- **Agent 友好**：命令自描述、结构化帮助、结构化输出、MCP、skills
+- **Agent 友好**：命令自描述、结构化帮助、结构化输出、catalog、skills
 - **架构清晰**：workflow 命令负责“得到结果”，原子命令负责“精确控制资源”
 
 Licell 当前覆盖的核心能力包括：
 
 - FC API 部署与发布
+- FC Task 部署、异步触发与任务追踪
 - OSS 静态站部署
 - 自定义域名、HTTPS、CDN、DNS
 - ACR / Docker 镜像部署
 - Serverless 数据库与缓存辅助能力
-- 面向 Agent 的 MCP / Skills / JSON 输出 / 文档共源生成
+- 面向 Agent 的 Skills / catalog / JSON 输出 / 文档共源生成
 
 ---
 
@@ -71,15 +72,15 @@ Licell 最新架构里，命令不再只是“能执行”，还要“能自我
 
 同一套命令注册表会驱动：
 
+- CLI `catalog`
 - CLI `--help`
 - 结构化 help
-- MCP tool catalog
 - skills 脚手架
 - README 生成区块
 - Agent surface 文档
 - shell completion
 
-也就是说：**命令面变了，帮助、MCP、skills、文档会跟着一起收敛**。
+也就是说：**命令面变了，catalog、帮助、skills、文档会跟着一起收敛**。
 
 ---
 
@@ -149,6 +150,15 @@ licell init --runtime nodejs22
 licell deploy --type api --target preview
 ```
 
+### 给 Task 项目
+
+```bash
+licell login --region cn-hangzhou
+licell init --runtime nodejs22 --kind task
+licell deploy --type task --target preview
+licell task invoke <appName> --target preview --payload '{"job":"demo"}'
+```
+
 ### 给 Agent / 自动化调用方
 
 推荐固定顺序：
@@ -170,14 +180,45 @@ Licell 有三类核心状态：
 | 类型 | 默认位置 | 说明 |
 |------|----------|------|
 | 全局认证 | `~/.licell-cli/auth.json` | 阿里云凭证与默认 region |
-| 项目状态 | `<project>/.licell/project.json` | appName、环境变量、网络、部署状态 |
-| MCP 项目配置 | `<project>/.mcp.json` | 供 Claude / Codex / Cursor 发现 licell MCP server |
+| 项目状态 | `<project>/.licell/project.json` | appName、环境变量、网络、部署状态；也可在 repo 根切换为 workspace 形式管理多个 component |
 
 兼容性说明：
 
 - Licell 仍兼容历史上的 `~/.ali-cli/auth.json` 等旧路径
 - 当前主路径以 `~/.licell-cli/*` 为准
 
+### Workspace / Monorepo
+
+当同一个 repo 里有多个可部署目录（例如 `apps/web` 静态站 + `apps/api` FC API）时，
+推荐在 repo 根维护一份 workspace 形态的 `.licell/project.json`：
+
+```json
+{
+  "defaultComponent": "api",
+  "components": {
+    "web": {
+      "path": "apps/web",
+      "appName": "demo-web",
+      "deployType": "static",
+      "dist": "dist",
+      "domain": "www.example.com"
+    },
+    "api": {
+      "path": "apps/api",
+      "appName": "demo-api",
+      "deployType": "api",
+      "runtime": "nodejs22",
+      "entry": "src/index.ts",
+      "target": "prod"
+    }
+  }
+}
+```
+
+- 在 `apps/web` 目录执行 `licell deploy` 时，会自动解析到 `web` component。
+- 在 `apps/api` 目录执行 `licell deploy` 时，会自动解析到 `api` component。
+- deploy 成功后，Licell 会把稳定重跑所需的 deploy intent（如 `domain` / `domainSuffix` / `entry` / `dist` / `target` / `enableCdn` / `enableSSL` / `useVpc`）回写到对应 component，而不是只写少量字段。
+
 ## 团队授权分发（推荐）
 
 当团队中只有少数人直接持有高权限 AK/SK 时，可以把“授权”和“使用”分开：
@@ -235,7 +276,7 @@ licell domain app bind --help --output json
 
 ## 2) 结构化输出 `--output json`
 
-除 `licell mcp serve` 外，几乎所有命令都支持结构化 JSON 结果：
+几乎所有命令都支持结构化 JSON 结果：
 
 ```bash
 licell deploy --type api --output json
@@ -252,44 +293,21 @@ licell oss info my-bucket --output json
 - `retryable`
 - `provider.requestId`
 
-## 3) MCP
-
-如果你希望 Claude Code、Codex、Cursor 等 Agent 直接把 `licell` 当作工具调用，用 MCP 是最自然的方式。
+## 3) 命令目录 `catalog`
 
-### 推荐：先跑 setup
+如果你希望 Claude Code、Codex、Cursor 等 Agent 直接驱动 `licell`，推荐走这条固定链路：
 
 ```bash
-licell setup
-licell setup --agent codex --global
-licell setup --agent claude --global
-```
-
-### 项目内初始化 MCP
-
-```bash
-licell mcp init
-```
-
-默认会生成：
-
-```json
-{
-  "mcpServers": {
-    "licell": {
-      "command": "licell",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
+licell catalog --output json
+licell deploy --help --output json
+licell deploy --type api --output json
 ```
 
-### 手动启动 MCP server
-
-```bash
-licell mcp serve
-```
+含义分别是：
 
-注意：`mcp serve` 走的是 stdio JSON-RPC 协议，**不要**加 `--output json`。
+- `catalog`：发现稳定 command key、选项、schema 与 CLI record contract
+- `--help --output json`：读取单命令的参数、结果、推荐流程与下一步
+- `--output json`：真正执行命令，并消费 `event / result / error` records
 
 ## 4) Skills
 
@@ -298,9 +316,14 @@ licell mcp serve
 ```bash
 licell skills init codex
 licell skills init claude
+licell skills init codex --global
 ```
 
-Skills 与 MCP、help、README 共享同一套命令描述体系，所以更容易保持一致。
+默认会把 skills 写入当前项目；只有显式传 `--global` 时，才会写到用户级全局技能目录。
+
+`licell setup` 是交互式包装命令，底层仍然复用同一套 skills 写入逻辑。
+
+Skills 与 catalog、help、README 共享同一套命令描述体系，所以更容易保持一致。
 
 ---
 
@@ -350,20 +373,6 @@ licell deploy --type api --runtime nodejs22 --entry src/index.ts --domain api.yo
 - 默认不再把大体积 fallback runtime 打进代码包，避免放大 FC 上传体积
 - 如需额外打包 fallback runtime，可显式设置 `LICELL_FC_INCLUDE_RUNTIME_FALLBACK=1`
 
-<!-- BEGIN GENERATED:README_MCP_FC_API_WORKFLOW -->
-`licell mcp` 已提供这组 FC API 部署工作流工具（由共享 MCP 注册表自动生成）：
-
-| Tool | 对应 CLI | 用途 |
-|------|----------|------|
-| `licell_fc_deploy_spec` | `licell deploy spec` | 读取 FC API runtime 的 entry / handler / 资源约束，帮助 Agent 先理解限制与签名模板。 |
-| `licell_fc_deploy_check` | `licell deploy check` | 只读预检当前项目，提前发现 handler、入口文件或 Docker 环境问题，并给出可执行修复建议。 |
-| `licell_deploy` | `licell deploy` | 在前两步通过后执行正式部署，将当前项目发布到阿里云。 |
-
-- Workflow：标准 FC API 部署链路：先读取部署规格，再做本地预检，最后执行正式部署。
-
-- 建议顺序：`licell_fc_deploy_spec` → `licell_fc_deploy_check` → `licell_deploy`
-<!-- END GENERATED:README_MCP_FC_API_WORKFLOW -->
-
 ## 静态站部署（OSS）
 
 ```bash
@@ -430,58 +439,6 @@ licell rollback
 - **想要结果**：先用 `domain app/static` 或 `deploy`
 - **要精细控制**：再落到 `fn domain` / `oss domain` / `dns records`
 
-<!-- BEGIN GENERATED:README_MCP_DOMAIN_WORKFLOWS -->
-`licell mcp` 也提供共享的域名编排 workflow 工具：
-
-#### 应用域名绑定
-
-通过一个入口同时编排 DNS、FC custom domain 与可选 HTTPS。
-
-| Tool | 对应 CLI | 用途 |
-|------|----------|------|
-| `licell_domain_app_bind` | `licell domain app bind` | 为当前应用绑定自定义域名，编排 DNS、FC custom domain 与可选 HTTPS。 |
-
-- Workflow：应用域名接入链路：绑定 FC custom domain、对齐 DNS，并可选自动签发 HTTPS。
-
-- 建议顺序：`licell_domain_app_bind`
-
-#### 静态站点域名绑定
-
-通过一个入口同时编排 CDN、DNS 与可选 HTTPS。
-
-| Tool | 对应 CLI | 用途 |
-|------|----------|------|
-| `licell_domain_static_bind` | `licell domain static bind` | 为静态站点绑定自定义域名，编排 CDN、DNS 与可选 HTTPS。 |
-
-- Workflow：静态站点域名接入链路：把域名接到 CDN、对齐 DNS，并可选自动启用 HTTPS。
-
-- 建议顺序：`licell_domain_static_bind`
-
-#### 应用域名解绑
-
-通过一个入口下线应用域名，并清理 FC custom domain / DNS。
-
-| Tool | 对应 CLI | 用途 |
-|------|----------|------|
-| `licell_domain_app_unbind` | `licell domain app unbind` | 解绑当前应用域名，并清理 FC custom domain / DNS CNAME。 |
-
-- Workflow：应用域名下线链路：解绑 FC custom domain，并清理对应 DNS CNAME。
-
-- 建议顺序：`licell_domain_app_unbind`
-
-#### 静态站点域名解绑
-
-通过一个入口下线静态站点域名，并清理 CDN / DNS。
-
-| Tool | 对应 CLI | 用途 |
-|------|----------|------|
-| `licell_domain_static_unbind` | `licell domain static unbind` | 解绑静态站点域名，并清理 CDN domain / DNS CNAME。 |
-
-- Workflow：静态站点域名下线链路：移除 CDN domain，并清理对应 DNS CNAME。
-
-- 建议顺序：`licell_domain_static_unbind`
-<!-- END GENERATED:README_MCP_DOMAIN_WORKFLOWS -->
-
 ---
 
 ## 示例与教程
@@ -499,6 +456,8 @@ licell rollback
 - `examples/node22-express-api`
 - `examples/python313-flask-api`
 - `examples/docker-bun-hono-api`
+- `examples/node22-task-worker`
+- `examples/python313-task-worker`
 - `examples/static-oss-site`
 
 ---
@@ -546,14 +505,103 @@ licell e2e cleanup <runId>
 ## 命令速查
 
 <!-- BEGIN GENERATED:README_QUICK_REFERENCE -->
-> 本节由 licell CLI 注册表自动生成；命令变更会同步到 README / docs/reference/agent-surfaces.md / Skills / MCP / Shell Completion。
+> 本节由 licell CLI 注册表自动生成；命令变更会同步到 README / docs/reference/agent-surfaces.md / Skills / Shell Completion。
 
 ### Agent Contract
 
-- 原始 CLI JSON 流：过滤前缀 `@@LICELL_JSON@@`，再按 `kind=licell-cli-record` / `schemaVersion=1.0` / `type=event|result|error` 解析。
-- `licell <command> --help --output json`：先读取 `help.kind` / `help.schemaVersion`；当前为 `licell-help@1.0`。
-- `licell_command_catalog`：先读取 `kind` / `schemaVersion`；当前为 `licell-agent-command-catalog@1.0`。
-- MCP tools 的 `metadata.licell` 会显式声明 `schemas.help` / `schemas.commandCatalog`；当前为 `licell-help@1.0` / `licell-agent-command-catalog@1.0`。
+- 发现命令目录：`licell catalog --output json`。
+- 读取单命令契约：`licell <command> --help --output json`。
+- 真正执行命令：`licell <command> --output json`，并过滤 `@@LICELL_JSON@@` 前缀逐行解析。
+- 对 `type=event` 的 record，优先读取稳定字段 `stage` / `action` / `status` / `source` / `terminal`。
+- 对 `type=error` 的 record，优先读取 `nextActions[]` 获取首选补救步骤。
+
+#### Schema Contracts
+
+- 原始 CLI JSON 流会使用前缀 `@@LICELL_JSON@@` 输出逐行 JSON record；每条 record 当前都满足 `licell-cli-record@1.0`，再通过 `type=event|result|error` 区分记录类型。
+- `licell <command> --help --output json`：读取 `help.kind` / `help.schemaVersion`；当前为 `licell-help@1.0`。
+- `licell catalog --output json`：读取 `kind` / `schemaVersion`；当前为 `licell-agent-command-catalog@1.0`。
+- `licell catalog --output json` 还会显式声明 help schema 与 CLI record schema：`licell-help@1.0` / `licell-cli-record@1.0`。
+- Agent 优先读取 `nextActions[]` 作为稳定下一步入口；`recommendedFlow` / `decisionGuide` / `remediation[]` 作为补充语义层。
+- 命令自己的业务结果字段继续读取对应命令 help / catalog 里的 `result`；下面三组 contract 只描述公共 CLI record 包络。
+
+### CLI Event Record · licell-cli-record@1.0
+
+- CLI 流式事件 record；适合驱动 Agent 的进度感知、日志桥接和阶段判断。
+- `kind`：固定为 `licell-cli-record`。
+- `schemaVersion`：CLI record schema 版本；当前为 `1.0`。
+- `type`：固定为 `event`。
+- `ts`：事件发出时间（ISO 8601）。
+- `command`：当前命令 key，例如 `deploy`、`oss upload`。
+- `stage`：稳定阶段标识，例如 `deploy`、`deploy.api`、`auth.restore`。
+- `action`：稳定动作标识，例如 `run`、`execute`、`stdout`。
+- `status`：`start` / `ok` / `failed` / `skipped` / `info`。
+- `source`：`command` / `console` / `stream`。
+- `terminal`：该事件是否代表当前动作进入终态。
+- `ok`（可选）：仅在终态成功/失败事件中出现；`true` 表示成功，`false` 表示失败。
+- `message`（可选）：面向人类的补充消息。
+- `data`（可选）：附加结构化上下文对象。
+  - `stream`（可选）：当 `action=stdout|stderr` 时给出流类型。
+
+### CLI Result Record Envelope
+
+- CLI 成功结果 record；公共包络固定，命令自定义 payload 字段请继续读取对应命令 help/catalog 中的 `result`。
+- `kind`：固定为 `licell-cli-record`。
+- `schemaVersion`：CLI record schema 版本；当前为 `1.0`。
+- `type`：固定为 `result`。
+- `ts`：结果发出时间（ISO 8601）。
+- `command`：当前命令 key。
+- `stage`：命令阶段标识；通常与命令 key 或子阶段一致。
+- `ok`：固定为 `true`。
+
+### CLI Error Record
+
+- CLI 错误结果 record；同时提供兼容层 remediation/nextCommands 和首选的 nextActions。
+- `kind`：固定为 `licell-cli-record`。
+- `schemaVersion`：CLI record schema 版本；当前为 `1.0`。
+- `type`：固定为 `error`。
+- `ts`：错误发出时间（ISO 8601）。
+- `command`：当前命令 key。
+- `stage`：错误阶段，例如 `parse`、`runtime`、`deploy`。
+- `ok`：固定为 `false`。
+- `error`：稳定错误对象。
+  - `code`：稳定错误码，例如 `CLI_INVALID_INPUT`、`AUTH_MISSING_CREDENTIAL`。
+  - `category`：`auth` / `permission` / `input` / `network` / `quota` / `conflict` / `not_found` / `internal`。
+  - `message`：错误主消息。
+  - `retryable`：该错误是否适合直接重试。
+- `provider`（可选）：阿里云 provider 侧上下文。
+  - `service`（可选）：云产品名，例如 `fc`、`oss`、`alidns`。
+  - `action`（可选）：云 API 动作名。
+  - `code`（可选）：云侧原始错误码。
+  - `requestId`（可选）：云侧 requestId。
+  - `httpStatus`（可选）：云侧 HTTP 状态码。
+  - `endpoint`（可选）：命中的云 API endpoint。
+- `details`（可选）：额外结构化错误上下文。
+- `remediation[]`：兼容层修复建议数组。
+  - `type`：建议类型，例如 `note` / `command`。
+  - `title`：修复建议标题。
+  - `reason`：为什么建议这样做。
+  - `commandTemplate`：建议命令模板。
+  - `commandKey`（可选）：若可匹配 CLI 注册表，则给出稳定 command key。
+  - `commandDescription`（可选）：匹配到的命令说明。
+  - `phase`：修复阶段，例如 `inspect` / `mutate` / `verify`。
+  - `priority`：`primary` / `secondary`。
+  - `order`：稳定排序值。
+- `nextCommands[]`：兼容层命令建议数组。
+  - `commandTemplate`：建议命令模板。
+  - `commandKey`（可选）：若可匹配 CLI 注册表，则给出稳定 command key。
+  - `description`（可选）：命令建议说明。
+  - `intent`：命令意图，例如 `inspect` / `repair` / `bind`。
+  - `priority`：`primary` / `secondary`。
+- `nextActions[]`：推荐优先消费的统一下一步数组。
+  - `title`：下一步动作标题。
+  - `description`：为什么建议执行这一步。
+  - `commandTemplate`：建议命令模板。
+  - `commandKey`（可选）：若可匹配 CLI 注册表，则给出稳定 command key。
+  - `phase`：动作阶段，例如 `inspect` / `verify` / `mutate`。
+  - `priority`：`primary` / `secondary`。
+  - `source`：动作来源，例如 `error-remediation`。
+
+- Agent 侧做强约束解析时，先匹配 `kind`，再检查 `schemaVersion`；未知更高版本应走兼容分支或降级为文本解析。
 
 ### 命令总览
 
@@ -564,13 +612,20 @@ licell e2e cleanup <runId>
 | 命令 | 说明 | 关键选项 |
 |------|------|----------|
 | `licell login` | 配置阿里云凭证 | `--account-id`, `--ak`, `--sk` |
-| `licell auth export [passkey]` | 加密打包当前 licell 全局凭证状态到私有 OSS，并生成 restore token | `--bucket`, `--expires-hours` |
+| `licell auth export [passkey]` | 加密打包当前 licell 全局凭证状态到私有 OSS，并生成 restore token | `--bucket`, `--expires`, `--expires-hours` |
+| `licell auth inspect <token>` | 解析并查看 restore token 的内容与有效期 | — |
 | `licell auth repair` | 修复凭证权限（推荐：用超级 AK/SK 自动补齐 licell 最小权限并继续使用） | `--account-id`, `--ak`, `--sk` |
 | `licell auth restore <token> [passkey]` | 使用 restore token + passkey 一键恢复 licell 全局凭证状态 | `--yes` |
 | `licell logout` | 清除本地凭证 | — |
 | `licell whoami` | 查看当前登录身份 | — |
 | `licell switch` | 切换默认 region | `--region` |
-| `licell init` | 初始化 FC 项目（空目录生成脚手架，已有项目写入 licell 配置） | `--runtime`, `--app`, `--force` |
+| `licell init` | 初始化 FC 项目（空目录生成脚手架，已有项目写入 licell 配置） | `--runtime`, `--kind`, `--app` |
+| `licell bootstrap` | 把已确认的部署方案初始化到 `.licell/project.json` / `.licell/state.json` | `--component`, `--path`, `--type` |
+| `licell workspace discover` | 扫描 repo，给出候选 components 与部署提案 | — |
+| `licell workspace doctor` | 在 workspace / monorepo 根目录诊断全部或指定 component | `--component`, `--runtime`, `--entry` |
+| `licell workspace init` | 在 repo 根目录创建或更新 licell workspace component | `--component`, `--path`, `--type` |
+| `licell workspace list` | 列出当前 repo / workspace 中可部署的 components | `--component` |
+| `licell workspace migrate` | 把旧单项目 `.licell/project.json` 升级成兼容旧版的 workspace/component 格式 | `--component`, `--path`, `--default` |
 | `licell config domain [suffix]` | 查看或设置全局默认域名后缀 | `--unset` |
 
 #### Delivery Workflow
@@ -579,32 +634,43 @@ licell e2e cleanup <runId>
 
 - Agent 在 FC API 部署前，优先执行 `licell deploy spec` 与 `licell deploy check`。
 - 涉及删除或清理的命令通常需要显式传入 `--yes`。
+- 任务函数通过 `licell deploy --type task` 交付；部署成功后不返回固定 URL，而是继续用 `licell task invoke / info / list / stop` 完成调用与排查。
 
 | 命令 | 说明 | 关键选项 |
 |------|------|----------|
-| `licell deploy` | 一键极速打包部署 | `--type`, `--entry`, `--dist` |
+| `licell deploy` | 一键极速打包部署 | `--component`, `--type`, `--entry` |
 | `licell deploy check` | 本地预检 FC API 入口与 runtime 约束（建议 deploy 前执行） | `--runtime`, `--entry`, `--docker-daemon` |
+| `licell deploy plan` | 基于 `.licell/project.json` 生成部署计划（不执行云端变更） | `--component`, `--include`, `--exclude` |
 | `licell deploy spec [runtime]` | 查看 FC API 部署规格（给 Agent/开发者在 deploy 前对照） | `--all` |
-| `licell release list` | 查看函数版本列表 | `--limit` |
-| `licell release promote [versionId]` | 发布并切流到目标别名 | `--target` |
-| `licell release prune` | 清理历史函数版本（默认仅预览） | `--keep`, `--apply`, `--yes` |
-| `licell release rollback <versionId>` | 回滚到指定函数版本 | `--target` |
-| `licell logs` | 查看云端日志（默认实时流式） | `--once`, `--window`, `--lines` |
-| `licell fn info [name]` | 查看函数详情 | `--target` |
-| `licell fn invoke [name]` | 调用函数（同步） | `--target`, `--payload`, `--file` |
+| `licell task config [name]` | 查看任务函数的异步调用配置 | `--component`, `--target` |
+| `licell task info <taskId> [name]` | 查看单个异步任务详情 | `--component`, `--target` |
+| `licell task invoke [name]` | 异步调用任务函数 | `--component`, `--target`, `--payload` |
+| `licell task list [name]` | 查看任务函数的异步任务列表 | `--component`, `--target`, `--status` |
+| `licell task stop <taskId> [name]` | 停止正在运行的异步任务 | `--component`, `--target` |
+| `licell task config rm [name]` | 删除任务函数的异步调用配置 | `--component`, `--target`, `--yes` |
+| `licell task config set [name]` | 写入任务函数的异步调用配置 | `--component`, `--target`, `--enable` |
+| `licell release list` | 查看函数版本列表 | `--component`, `--limit` |
+| `licell release promote [versionId]` | 发布并切流到目标别名 | `--component`, `--target` |
+| `licell release prune` | 清理历史函数版本（默认仅预览） | `--component`, `--keep`, `--apply` |
+| `licell release rollback <versionId>` | 回滚到指定函数版本 | `--component`, `--target` |
+| `licell logs query [query]` | 按 SLS project/logstore/query 一次性检索日志 | `--project`, `--store`, `--region` |
+| `licell logs tail [query]` | 按 SLS project/logstore/query 持续跟随日志流 | `--project`, `--store`, `--region` |
+| `licell fn info [name]` | 查看函数详情 | `--component`, `--target` |
+| `licell fn invoke [name]` | 调用函数（同步） | `--component`, `--target`, `--payload` |
 | `licell fn list` | 查看函数列表 | `--limit`, `--prefix` |
-| `licell fn rm [name]` | 删除函数 | `--force`, `--yes` |
-| `licell fn domain bind <domain>` | 绑定或更新 FC 自定义域名（资源级，不默认改 DNS） | `--function`, `--target`, `--path` |
+| `licell fn logs [name]` | 查看函数日志（默认实时流式） | `--component`, `--once`, `--window` |
+| `licell fn rm [name]` | 删除函数 | `--component`, `--force`, `--yes` |
+| `licell fn domain bind <domain>` | 绑定或更新 FC 自定义域名（资源级，不默认改 DNS） | `--function`, `--component`, `--target` |
 | `licell fn domain info <domain>` | 查看 FC 自定义域名详情 | — |
 | `licell fn domain list` | 查看 FC 自定义域名列表 | `--limit`, `--prefix` |
 | `licell fn domain unbind <domain>` | 解绑 FC 自定义域名 | `--cleanup-dns`, `--yes` |
-| `licell env list` | 查看云端环境变量 | `--target`, `--show-values` |
-| `licell env pull` | 拉取云端环境变量 | `--target` |
-| `licell env rm <key>` | 删除云端环境变量（并同步本地 .licell/project.json） | `--yes` |
-| `licell env set <key> <value>` | 设置云端环境变量（并同步本地 .licell/project.json） | — |
-| `licell domain app bind <domain>` | 为当前应用编排 DNS、函数域名与可选 SSL | `--ssl`, `--ssl-force-renew`, `--target` |
+| `licell env list` | 查看云端环境变量 | `--component`, `--target`, `--show-values` |
+| `licell env pull` | 拉取云端环境变量 | `--component`, `--target` |
+| `licell env rm <key>` | 删除云端环境变量（并同步本地 .licell/project.json） | `--component`, `--yes` |
+| `licell env set <key> <value>` | 设置云端环境变量（并同步本地 .licell/project.json） | `--component` |
+| `licell domain app bind <domain>` | 为当前应用编排 DNS、函数域名与可选 SSL | `--component`, `--ssl`, `--ssl-force-renew` |
 | `licell domain app unbind <domain>` | 解绑当前应用域名，并清理 FC custom domain / DNS CNAME | `--yes` |
-| `licell domain static bind <domain>` | 为静态站点编排 CDN、DNS 与可选 HTTPS | `--bucket`, `--ssl`, `--ssl-force-renew` |
+| `licell domain static bind <domain>` | 为静态站点编排 CDN、DNS 与可选 HTTPS | `--component`, `--bucket`, `--ssl` |
 | `licell domain static unbind <domain>` | 解绑静态站点域名，并清理 CDN / DNS | `--yes` |
 | `licell dns records add <domain>` | 添加域名解析记录 | `--rr`, `--type`, `--value` |
 | `licell dns records list [domain]` | 查看域名解析记录 | `--limit` |
@@ -634,12 +700,14 @@ licell e2e cleanup <runId>
 | 命令 | 说明 | 关键选项 |
 |------|------|----------|
 | `licell db add` | 分配数据库实例 | `--type`, `--engine-version`, `--category` |
+| `licell db class [type]` | 查询数据库可用规格（给 Agent/开发者在 db add 前对照） | `--engine-version`, `--category`, `--storage-type` |
 | `licell db connect [instanceId]` | 输出数据库连接信息 | — |
 | `licell db info <instanceId>` | 查看数据库实例详情 | — |
 | `licell db list` | 查看数据库实例列表 | `--limit` |
 | `licell db public-access [instanceId]` | 开通数据库公网访问并添加当前 IP 到白名单 | `--ip` |
 | `licell db rm <instanceId>` | 删除数据库实例 | `--yes` |
-| `licell cache add` | 分配 Redis 缓存 | `--type`, `--instance`, `--password` |
+| `licell cache add` | 分配 Redis 缓存 | `--type`, `--mode`, `--instance` |
+| `licell cache class [mode]` | 查询缓存可用规格（给 Agent/开发者在 cache add 前对照） | `--zone`, `--limit` |
 | `licell cache connect [instanceId]` | 输出缓存连接信息 | — |
 | `licell cache info <instanceId>` | 查看缓存实例详情 | — |
 | `licell cache list` | 查看缓存实例列表 | `--limit` |
@@ -662,16 +730,18 @@ licell e2e cleanup <runId>
 
 面向 Agent、开发体验与 CLI 生命周期的自动化命令。
 
-- `licell skills init` 与 `licell mcp` 都基于同一套 CLI 命令目录生成外部表面。
+- `licell skills init`、`licell catalog`、`licell completion` 都基于同一套 CLI 命令目录生成外部表面。
 - `licell completion` 的候选命令同样来自共享命令目录。
 
 | 命令 | 说明 | 关键选项 |
 |------|------|----------|
-| `licell mcp` | MCP：让 Agent 通过 licell 执行部署/发布/运维（默认先初始化，再启动 stdio server） | `--project-root`, `--server-name` |
-| `licell mcp init` | 写入/更新项目内 `.mcp.json` 配置 | `--project-root`, `--server-name` |
-| `licell mcp serve` | 以 stdio 方式启动 licell MCP server | `--project-root` |
-| `licell skills init [agent]` | 为 AI Agent 生成 licell skills（claude / codex） | `--project-root`, `--force` |
-| `licell setup` | 安装后引导：配置 AI Agent Skills 和 MCP | `--agent`, `--global`, `--project-root` |
+| `licell doctor` | 诊断本机 licell 登录态、云端权限/目标资源/域名入口、项目配置与部署前置条件 | `--component`, `--all-components`, `--runtime` |
+| `licell catalog` | 输出共享 CLI 命令目录，供 Agent / 自动化发现命令、选项和结构化契约 | `--root-command`, `--command-key` |
+| `licell ci init github` | 生成 GitHub Actions 的 deploy-only workflow（只调用 licell，不负责编译） | `--apply`, `--force`, `--workflow` |
+| `licell ci init gitlab` | 生成 GitLab CI 的 deploy-only pipeline（只调用 licell，不负责编译） | `--apply`, `--force`, `--pipeline` |
+| `licell skills init [agent]` | 为 AI Agent 生成 licell skills（claude / codex） | `--global`, `--project-root`, `--force` |
+| `licell setup` | 安装后引导：交互式配置 AI Agent skills | `--agent`, `--global`, `--project-root` |
+| `licell state show` | 查看当前 repo 的 `.licell/state.json` | `--component` |
 | `licell completion [shell]` | 输出 shell 补全脚本（bash/zsh） | `--engine` |
 | `licell upgrade` | 按当前安装来源升级 licell | `--channel`, `--target-version`, `--repo` |
 | `licell e2e cleanup [runId]` | 清理指定 E2E run 产生的资源 | `--manifest`, `--keep-workspace`, `--yes` |
@@ -680,6 +750,18 @@ licell e2e cleanup <runId>
 
 ### 常用工作流片段
 
+**Task 函数工作流**
+
+```bash
+licell deploy --type task --runtime nodejs22 --entry src/task.ts --target preview --output json
+licell task config <appName> --target preview --output json
+licell task invoke <appName> --target preview --payload '{"job":"demo"}' --output json
+licell task info <taskId> <appName> --target preview --output json
+licell task list <appName> --target preview --status Running --output json
+```
+
+说明：`deploy --type task` 成功后不会返回固定 URL；请读取结果里的 `invokeCommand`，或继续执行 `licell task invoke` / `task info` / `task list` 完成任务闭环。
+
 **Shell 补全（bash / zsh）**
 
 ```bash
@@ -705,7 +787,7 @@ licell e2e list
 licell e2e cleanup <runId>
 ```
 
-说明：`licell e2e run --suite full` 现在会额外覆盖 DNS add/rm、OSS bucket/object CRUD、OSS 原生域名 token/bind/unbind、`domain app bind/unbind`、`deploy --type static --domain ...` 与 `domain static bind/unbind`。如需连同云上资源一起收口，建议配合 `--cleanup`。
+说明：默认 smoke 套件会覆盖 API deploy/invoke 与 task deploy/config/invoke/list/info/stop；`licell e2e run --suite full` 会在此基础上额外覆盖 DNS add/rm、OSS bucket/object CRUD、OSS 原生域名 token/bind/unbind、`domain app bind/unbind`、`deploy --type static --domain ...` 与 `domain static bind/unbind`。如需连同云上资源一起收口，建议配合 `--cleanup`。
 
 **删除 / 清理说明**
 
@@ -729,8 +811,8 @@ licell deploy --type api --target preview
 ### 我希望 Agent 自动、安全地部署
 
 ```bash
-licell setup --agent codex --global
-licell mcp init
+licell setup --agent codex
+licell catalog --output json
 licell deploy spec nodejs22 --output json
 licell deploy check --runtime nodejs22 --entry src/index.ts --output json
 licell deploy --type api --runtime nodejs22 --entry src/index.ts --target preview --output json
@@ -763,4 +845,4 @@ licell e2e run --suite full --cleanup
 - workflow 优先
 - 原子命令兜底
 - 命令自描述
-- MCP / skills / docs 共源收敛
+- catalog / skills / docs 共源收敛