# @share-crm/sharedev-cli 中文文档

规范地址：https://npmcn.com/package/%40share-crm/sharedev-cli/

版本：0\.0\.5-rc\.1
npm 元数据更新时间：2026-11-02T10:45:30.147Z
中文译文更新时间：2026-11-02T11:21:06.483Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40share-crm/sharedev-cli
原文对照：https://npmcn.com/package/%40share-crm/sharedev-cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.2 MB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：13 个
- 首次发布：2026-04-10T08:56:25.112Z
- 最新版本发布：2026-11-02T10:45:29.968Z
- 已发布版本数：64（近 12 个月 64 个）

## 中文简介

Sharedev命令行工具

## 安装

```sh
npm install @share-crm/sharedev-cli
```

也可以使用：`pnpm add @share-crm/sharedev-cli`、`yarn add @share-crm/sharedev-cli`、`bun add @share-crm/sharedev-cli`

## README

# sharedev CLI 技术方案

## 项目概览

`sharedev` 是一个基于 Node.js 的命令行工具，用于 APL 函数、PWC 组件和开发元数据的本地开发工作流。

-   命令入口：`sharedev`
-   业务命名空间：`apl`、`pwc`
-   构建工具：webpack + TypeScript
-   运行时：Node.js 18+

* * *

## 命令设计

### 命令树

```
sharedev
├── init                           # 项目初始化，生成目录、git 仓库、.gitignore 和 .sharedev/settings.json
├── apl
│   ├── list                       # 列出远端 APL 函数摘要
│   ├── info <apiName>             # 查询 APL 函数详情
│   ├── pull [apiName]             # 拉取单个或全部 APL 函数到本地
│   ├── diff [apiName]             # 对比本地与快照/远端版本
│   ├── push [apiName]             # 提交单个或全部本地变更到远端
│   ├── reset [apiName]            # 回滚本地文件到远端最新或指定版本
│   ├── compile [apiName]          # 编译检测本地源码
│   ├── analyze [apiName]          # 静态分析本地源码
│   ├── debug [apiName]            # 运行函数调试
│   └── create                     # 创建函数/类并写入本地源码
├── pwc
│   ├── pull <apiName>             # 拉取组件/插件到本地
│   ├── push <apiName>             # 提交本地变更
│   ├── publish <apiName>          # 发布
│   ├── dev <apiName>              # 本地开发模式（待规划）
│   └── create                     # 创建组件（预留）
├── dev-metadata
│   ├── search [query]             # 搜索对象元数据
│   ├── info [apiName]             # 查询对象详情
│   ├── download [apiName]         # 下载单个对象元数据 markdown
│   ├── download --all             # 批量下载对象元数据 markdown
│   └── namespace                  # 下载运行时命名空间元数据
└── skill                          # 预留
    ├── init                       # 下载 skill 到平台目录
    ├── pull/push/list/unset       # 预留命令位
```

### 全局参数

-   `--version` / `-v`：输出版本号
-   `--help` / `-h`：显示帮助信息

* * *

## APL 功能方案

### 本地工作区模型

```text
<settingsParent>/
├── package/
│   ├── fx/custom/apl/script/           # package_name 为空时的默认目录
│   │   └── <apiName>.<type>.groovy
│   └── <package_name as path>/         # package_name 中的 . 会被替换为 /
│       └── <apiName>.<type>.groovy
└── .sharedev/
    └── apl/
        └── .sharedev/
            ├── snapshot.json           # 已拉取/已提交版本的源码快照
            ├── versions.json           # 版本信息
            └── metadata.json           # 绑定对象、参数等元信息
```

### 当前已实现命令

-   `apl list`
    -   拉取远端函数列表
    -   仅保留 `lang === 0` 且 `is_control !== true` 的 Groovy 函数
    -   输出 `apiName/functionName/packageName/version`
-   `apl info <apiName> [--bind <bindingObjectApiName>]`
    -   查询单个函数详情
    -   终端输出摘要和参数列表
-   `apl pull <apiName>` / `apl pull --all`
    -   单个或批量拉取远端源码
    -   写入本地 `.groovy` 文件
    -   同步更新 snapshot / versions / metadata
-   `apl diff <apiName> [--remote latest|<version>]`
    -   默认对比本地文件和 snapshot
    -   支持对比远端 latest 或指定版本
    -   输出 unified diff 和增删行统计
-   `apl push [apiName] --remark <comment> [--force]`
    -   `apiName` 存在时只提交单个函数；省略时提交所有已跟踪且有本地变更的函数
    -   提交前执行远端版本冲突检查、analyze、compile
    -   成功后回写本地源码和 snapshot
-   `apl reset <apiName> [--remote latest|<version>]`
    -   使用远端 latest 或指定版本覆盖本地文件
    -   同步更新 snapshot
-   `apl analyze <apiName>`
    -   基于本地源码和远端元信息执行静态分析
    -   输出 JSON 结果
-   `apl compile <apiName>`
    -   基于本地源码和远端元信息执行编译检查
-   `apl debug <apiName> [--data-id <id>] [--param <name=value>]...`
    -   读取本地源码进行调试
    -   绑定对象 data id 和函数参数支持 CLI 传参，也支持交互补齐
    -   输出调试摘要和原始结果
-   `apl create`
    -   支持创建 `function` / `class`
    -   支持通过命令参数或交互输入补齐 apiName、functionName、namespace、package、returnType、bind、remark、templateId
    -   先在远端创建，再将生成后的源码写入本地并写入 snapshot

### 主要流程

**pull**：按单个或批量方式获取远端函数详情 → 写入本地 `.groovy` 文件 → 记录 snapshot / versions / metadata

**push**：读取本地 tracked 文件 → 与 snapshot 比较变更 → 校验远端版本冲突 → analyze / compile → 提交更新 → 更新本地源码和 snapshot

**diff**：按 `apiName` 定位本地 tracked 文件 → 基于 snapshot 或远端版本生成 unified diff

**reset**：获取远端 latest 或指定版本 → 覆盖本地源码并更新 snapshot

**compile / analyze**：读取本地 tracked 源码并拼接远端元信息 → 调用远端编译或分析接口

**debug**：CLI 参数优先，缺失时通过交互补齐绑定对象 data id 和函数参数 → 构造 payload 调用远端调试接口

**create**：先加载 namespace / returnType / binding object 元数据 → 构造模板 → 远端创建 → 本地写入源码和 snapshot

### 模块职责

| 模块 | 职责 |
| --- | --- |
| `apl.service.ts` | 远端接口封装：列表、详情、版本查询、create、push、compile、analyze、debug |
| `apl.workspace.ts` | 本地源码路径解析、tracked 文件发现、snapshot / metadata 管理 |
| `apl.command.ts` | CLI 参数校验、交互补齐、命令编排、diff 输出 |

* * *

## Dev Metadata 功能方案

### 本地输出模型

```text
<settingsDir>/docs/dev-metadata/
├── objects/
│   ├── objects.md                    # 全量对象索引（download --all 时生成）
│   └── <apiName>.md                  # 单个对象详情文档
└── namespaces/
    └── namespaces.json               # 运行时命名空间原始结果
```

说明：

-   未显式传 `--output` 时，输出目录默认位于 `.sharedev/docs/dev-metadata/`
-   传入 `--output` 时，相对路径基于命令执行时的 `workingDir/cwd` 解析

### 当前已实现命令

-   `dev-metadata search [query]`
    -   调用对象列表接口
    -   本地按 `api_name / display_name / display_name_r` 过滤和排序
    -   输出标准化 JSON 摘要
-   `dev-metadata info [apiName]`
    -   先按 apiName 直接查询详情
    -   直查失败时回退到列表搜索候选项
    -   候选项多于 1 个时，交互选择目标对象
    -   输出对象摘要、字段列表和 layout 摘要
-   `dev-metadata download <apiName>`
    -   下载单个对象详情并写成 markdown
-   `dev-metadata download --all`
    -   拉取对象列表并逐个下载详情
    -   输出每个对象的 markdown 文件
    -   同时生成 `objects.md` 索引
-   `dev-metadata namespace [--output <dir>]`
    -   调用运行时 namespace 接口
    -   以原始 JSON 形式写入 `namespaces.json`

### 主要流程

**search**：拉取对象列表 → 本地过滤 / 排序 → 输出 JSON 摘要

**info**：优先直查对象详情 → 失败时回退候选搜索与交互选择 → 输出终端可读摘要

**download**：拉取对象详情 → 渲染 markdown → 写入对象文档目录

**download --all**：拉取对象列表 → 逐个请求详情并落盘 → 生成对象索引

**namespace**：调用运行时 namespace 元数据接口 → 原样写入 JSON 文件

### 模块职责

| 模块 | 职责 |
| --- | --- |
| `dev-metadata.service.ts` | 对象列表、对象详情、运行时 namespace 接口封装，以及搜索过滤 / 排序 |
| `dev-metadata.workspace.ts` | 输出目录解析、对象 markdown 渲染、索引和 namespace 文件写入 |
| `dev-metadata.command.ts` | search / info / download / namespace 命令编排与交互 |

* * *

## PWC 功能方案

### 本地目录模型

```
<workspace>/
├── pwc-components/<apiName>/           # type=component 时
│   ├── mateXml.xml
│   ├── source/
│   ├── static/
│   ├── fileTree/
│   └── .sharedev-meta.json
└── pwc-plugins/<apiName>/             # type=plugin 时
    ├── mateXml.xml
    ├── source/
    ├── static/
    ├── fileTree/
    └── .sharedev-meta.json
```

### 主要流程

**pull**：按 `apiName` 拉取完整数据 → 写入 `mateXml.xml`、source、static、fileTree → 生成 `.sharedev-meta.json`

**push**：扫描本地文件 → 排除 `mateXml.xml` → 按类型组装 sourceFiles/images/fileTree → 调用 `updateCodeSource`

**publish**：复用 push 逻辑

### 模块职责

| 模块 | 职责 |
| --- | --- |
| `pwc.service.ts` | 远端接口封装：fetchCode、downloadFile、uploadFile、updateCodeSource |
| `pwc.workspace.ts` | 本地目录初始化、mateXml 读写、entryFileName 解析 |
| `pwc.publish.ts` | 文件装配、类型归类、发布编排 |

* * *

## 配置方案

配置文件固定为 `.sharedev/settings.json`，内容：

```json
{
  "certificate": "<token>",
  "domain": "https://www.fxiaoke.com/"
}
```

`config.ts` 提供：

-   `findSettings()`：从当前工作目录向上查找配置文件
-   `loadSettings()`：读取并校验配置
-   `getSettings()`：单例式配置访问

配置文件缺失时立即报错退出，不发请求。

* * *

## 公共基础服务

### loggerService (`src/core/logger.ts`)

统一管理所有终端输出，基于 `chalk`：

| 方法 | 用途 |
| --- | --- |
| `info/success/warn/error(message)` | 带 `[sharedev]` 前缀的可读日志 |
| `debug(message)` | 仅在 `--verbose` 下输出 |
| `printJson(data)` | 输出纯 JSON（供 list/analyze/debug 等命令） |
| `printRaw(text)` | 不加前缀原样输出（用于 diff） |
| `startLoading(message)` | 启动 loading |
| `updateLoading(message)` | 更新 loading 文案 |
| `stopLoading()` | 停止 loading |

退化策略：非 TTY 或 `--verbose` 下，loading 退化为稳定文本，避免控制字符污染日志。

### requestService (`src/core/request.ts`)

基于 `axios` 封装，统一注入 `domain` 和 `certificate`，提供 `get/post/request` 方法。

* * *

## 构建方案

-   源码入口：`src/cli.ts`
-   webpack 配置：`build/webpack/webpack.{common,dev,prod}.cjs`
-   构建产物：`dist/sharedev.js`
-   发布入口：`bin/cli.mjs`（加载 `dist/sharedev.js`，含 shebang）

第三方依赖（axios、chalk、commander、ora、@clack/prompts 等）全部打入 bundle，不依赖外部 node\_modules。

* * *

## 本地调试方式

### 步骤一：安装依赖并构建

```bash
cd packages/share-dev-cli
npm install
npm run build
```

### 步骤二：全局链接

```bash
# 在 packages/share-dev-cli 目录下执行
npm link
```

执行后，`sharedev` 命令会被注册为全局可执行命令，指向当前构建产物 `dist/sharedev.js`。

> **注意**：如果 `npm link` 报 `ENOTEMPTY` 错误，说明全局 node\_modules 中已存在该包的旧目录，npm 无法原子替换。手动删除后重试即可：
> 
> ```bash
> rm -rf /Users/wujing/.nvm/versions/node/v23.6.0/lib/node_modules/@share-crm/sharedev-cli
> npm link
> ```
> 
> 若使用其他 Node 版本，将路径中的 `v23.6.0` 替换为实际版本号（可通过 `node -v` 查看）。

> 调试结束后可执行 `npm unlink -g sharedev` 解除链接。

### 步骤三：在测试目录中执行命令

进入任意含有 `.sharedev/settings.json` 的测试目录，运行命令：

```bash
sharedev --help
sharedev apl list
sharedev apl pull <apiName>
sharedev pwc pull <apiName> --type component
sharedev pwc dev <filePath>
```

每次修改源码后，重新执行 `npm run build`（或保持 `npm run dev` 在后台运行），无需重复 `npm link`。

* * *

## 实施计划

### 第一期（最小可用）

1.  项目骨架：package.json、tsconfig、webpack 构建配置
2.  CLI 入口：`sharedev apl`、`sharedev pwc` 命令注册
3.  `.sharedev/settings.json` 查找与校验
4.  loggerService 和 requestService 基础实现
5.  APL pull / push 基础能力
6.  PWC pull / push 基础能力

### 第二期

1.  APL diff / reset / compile / analyze / debug
2.  APL 批量 push
3.  PWC publish
4.  dev-metadata search / info / download / namespace

### 第三期

1.  APL / PWC create 的更多模板与能力
2.  watch 模式
3.  更完整的冲突处理

* * *

## 风险与注意事项

1.  **VS Code 扩展能力不可直接迁移**：CLI 中用 Node 文件系统 API、终端交互、本地快照替代 VS Code API
2.  **配置是前置条件**：`.sharedev/settings.json` 缺失时不能继续执行，不能带空配置发请求
3.  **不要暴露 certificate**：`certificate` 字段不能明文打印到日志
4.  **APL 和 PWC 抽象层次不同**：APL 是单文件函数，PWC 是多目录组件，工作区模型不共用

## 常见问题

### @share-crm/sharedev-cli 是什么？

Sharedev命令行工具

### 如何安装 @share-crm/sharedev-cli？

在项目目录运行 npm install @share-crm/sharedev-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sharedev，可以用 npx sharedev 直接运行。

### @share-crm/sharedev-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/share-crm\_\_sharedev-cli 是否存在。

### @share-crm/sharedev-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @share-crm/sharedev-cli 可以商用吗？

@share-crm/sharedev-cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @share-crm/sharedev-cli 还在维护吗？

最新版本 0\.0\.5-rc\.1 发布于 2026/11/02（1 天前）；至今共发布 64 个版本，其中过去 12 个月发布了 64 个；首次发布于 2026/04/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。