# @arcshape/cli 中文文档

规范地址：https://npmcn.com/package/%40arcshape/cli/

版本：0\.4\.0
npm 元数据更新时间：2026-10-31T05:46:08.870Z
中文译文更新时间：2026-11-06T17:54:45.878Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40arcshape/cli
原文对照：https://npmcn.com/package/%40arcshape/cli/?lang=original
项目主页：https://github.com/juangcarmona/arcshape#readme
源码仓库：https://github.com/juangcarmona/arcshape

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

- 包体积（解压后）：4.1 MB，330 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：11 个
- 首次发布：2026-10-17T08:38:57.079Z
- 最新版本发布：2026-10-31T05:46:08.486Z
- 近 30 天下载量：3699（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

ArcShape用于创建和维护arc42架构文档的工具.

## 安装

```sh
npm install @arcshape/cli
```

也可以使用：`pnpm add @arcshape/cli`、`yarn add @arcshape/cli`、`bun add @arcshape/cli`

## README

# 弧形状

ArcShape是一个npm-install可定义的CLI,以及用于创建和维护Markdown架构文档的单独管理的代理技能包 [弧形42](https://arc42.org/)其生成的读者网站是为技术和非技术读者设计的.

浏览 [ArcShape 建筑网站](https://juangcarmona.github.io/arcshape/)。 。 。 .

## 开始吧

在项目寄存器中安装 ArcShape , 并带有 Node.js 22 或 更新并运行 :

```sh
npm install --save-dev @arcshape/cli
npx arcshape init
```

`arcshape init` 创建 `docs/architecture/` 带有导航读取器和十二个 `NN-slug/README.md` 弧形42节。 额外的Markdown文件可以活在自有的段目录中,并作为辅助材料提供. 遗产平地 `NN-slug.md` 迁移时布局仍然可以读取。 然后提供检测到的代理供应商和能力。 选择 `--no-agents` 只有CLI的设置。 在非交互式弹壳上,说明选择和确认:

```sh
npx arcshape init --providers codex,claude --dry-run
npx arcshape init --providers codex,claude --yes
npx arcshape init --no-agents --yes
```

默认安装范围是当前寄存器. 使用 `--scope user` 将安装在您的家目录中. `--providers` 接受 `codex`, (中文(简体) ), `claude`, (中文(简体) ), `cursor`, (中文(简体) ), `windsurf`, (中文(简体) ), `gemini`, (中文(简体) ), `opencode`,以及 `copilot`· ; `--capabilities` 接受逗号分隔名称,例如 `arc-adr,arc-c4`没有 `--capabilities`,所有4种技能都被选中. 被检测的提供者是建议,从未被默默选中.

每个峡谷 `SKILL.md` 遵循便携式代理技能格式。 提供者中性技能生活在 `.agents/skills/` 用于Codex,Cursor,Windsurf/Cascade,双子座CLI,OpenCode,和GitHub副驾驶. Claude 代码使用 `.claude/skills/`。 。 。 . `arcshape agents detect` 报告来自 `PATH` 和薄弱的提供方专用仓库标记; 共享 `.agents/skills/` 目录含糊不清,无法识别代理。 一些提供者发现了共享和克洛德的根,因此选择克洛德和一个共享路径提供者可能会两次暴露出同样的技能. Windsurf文档目前重定向到 Devin 桌面文档; ArcShape 使用已记录的共享技能路径,并将该提供者的相容性视为临时.

设置后管理能力 `arcshape agents detect`, (中文(简体) ), `arcshape agents list`, (中文(简体) ), `arcshape agents install`, (中文(简体) ), `arcshape agents update`,以及 `arcshape agents uninstall`。 。 。 . `install` 将选中的提供者和能力添加到当前管理的集中; 它不会删除先前的选择 . `update` 刷新管理集,以及 `uninstall` 删除所有未修改的管理文件 。 例如:

```sh
npx arcshape agents install --providers codex,claude --capabilities arc-adr,arc-c4 --dry-run
npx arcshape agents install --providers codex,claude --capabilities arc-adr,arc-c4 --yes
npx arcshape agents update --yes
npx arcshape agents uninstall --yes
```

ArcShape 记录拥有文件散列 `.arcshape/agent-capabilities.json` (或 `~/.arcshape/agent-capabilities.json` 用户范围)。 更新只替换未修改的文件 ArcShape 管理; 未安装只删除未修改的管理文件 。 已编辑和未跟踪的文件得到保存和报告,冲突产生非零退出状态. 在确认的代理能力操作中,提供了包版0.1.1中准确的未变的助理文件取出;所编辑的遗留文件仍未被更改. Npm包装代理能力船并安装下线. ArcShape不安装市场插件,不联系代理服务,也不执行能力脚本.

CLI 提供寄存器设置(`init`(b) 临时证据全程簿记(`session`), arc42 Markdown结构,本地链接和可选产品元件引用验证(`validate`), Obsidian 和 Collection 同步(`sync`),以及自成一体的读者网站(`site build`) (中文(简体) ). 单独安装的技能包括倒向工程、arc42作者、ADRs、C4图表和文档连接.

验证arc42结构和本地链接. 添加 `--citations` 当寄存器在 `docs/product/model`数字 :

```sh
npx arcshape validate --links --citations
```

引用验证使用存储器安装 `@prodshape/cli`;当产品形状模型出现时安装. 没有模型,引用验证报告为跳过. Stale 引用显示为警告, 而未解决引用或缺失的本地 CLI 失败验证 .

开始本地分析会话, 并要求其下一轮设定范围的证据 :

```sh
npx arcshape session start
npx arcshape session next
```

将峡谷马克德复制到 Obsidian 金库:

```sh
npx arcshape sync obsidian --vault ~/Documents/ObsidianVault --include docs/architecture/09-architecture-decisions --dry-run
npx arcshape sync obsidian --vault ~/Documents/ObsidianVault --include docs/architecture/09-architecture-decisions
```

同步存储了导出注释旁的本地列表, 仅在副本仍然匹配上一个 ArcShape 版本时更新副本, 并将本地编辑报告为冲突 .

要将架构作为一个索引发布,每个弧度42节各有1个子页,选择一个相会母页,并在环境变量中设置证书. 先预览页面计划 :

```sh
CONFLUENCE_EMAIL=you@example.com CONFLUENCE_API_TOKEN=... \
  npx arcshape sync confluence \
  --base-url https://example.atlassian.net/wiki \
  --space-id 12345 --parent-id 123456 --title-prefix MyProject \
  --include docs/architecture/09-architecture-decisions --dry-run
```

删除 `--dry-run` 以创建或更新页面。 ArcShape 记录了本地基线 : `.arcshape/confluence-sync/`; 后在远程编辑上停止运行到管理页面. 单页目标,使用 `--page-id <id>` 改为 `--space-id` 财务报告和审定财务报表 `--parent-id`。 。 。 .

会话工具盘点文件而不通过编程语言进行选择,并尊重root和嵌入 `.gitignore` 规则,包括否定。 它记录人类或AI工作流程的分类和笔记;它不将发现本身读入建筑主张.

## 项目基础

-   经核准的产品定义载于 `docs/product/model` 并使用 [产品形状](https://github.com/juangcarmona/productshape)。 。 。 .
-   建筑文件将生活在 `docs/architecture` 跟踪 [弧形42](https://arc42.org/)。 。 。 .
-   [打开Spec](https://github.com/Fission-AI/OpenSpec) 用于临时交付规划,而不是作为产品或建筑真相的来源.
-   读取 [工程生命周期](https://npmcn.com/package/%40arcshape/cli/docs/engineering-lifecycle.md) 准备、审查和合并预期.

## 开发设置

所需经费: [节点.js](https://nodejs.org/) 22个或较新的 [无](https://www.npmjs.com/)。 。 。 .

```sh
npm ci
```

被钉住 [产品形状](https://github.com/juangcarmona/productshape) 财务报告和审定财务报表 [打开Spec](https://github.com/Fission-AI/OpenSpec) 国家领导才能作为地方发展依赖而安装。 使用 `npx prodshape <command>` 或运行它们的软件包脚本;不需要全局安装.

追踪到的Codex 克劳德, [产品形状](https://github.com/juangcarmona/productshape),以及 [打开Spec](https://github.com/Fission-AI/OpenSpec) 这一发展储存库已经存在一体化。 仅在有意重生成或刷新相应集成文件时运行 :

```sh
npm run product:init
npm run openspec:init
```

初始质量基准在 [工程生命周期](https://npmcn.com/package/%40arcshape/cli/docs/engineering-lifecycle.md)。 。 。 . `npm run build` 编译寄存器帮助脚本;不是ArcShape CLI构建.

## 捐款

开始于 [捐款指南](https://npmcn.com/package/%40arcshape/cli/CONTRIBUTING.md). 对于非三角工作,在规划实施前开放或完善GitHub问题.

发行准备,第一个npm出版,以及后来值得信赖的出版都记录在 [重放弧形状](https://npmcn.com/package/%40arcshape/cli/docs/releasing.md)。 。 。 .

## 许可证

ArcShape根据以下规定获得许可证: [Apache 许可证,2.0版本](https://npmcn.com/package/%40arcshape/cli/LICENSE),该许可证用于: [产品形状](https://github.com/juangcarmona/productshape)。 。 。 .

## 常见问题

### @arcshape/cli 是什么？

ArcShape用于创建和维护arc42架构文档的工具\.

### 如何安装 @arcshape/cli？

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

### @arcshape/cli 支持 TypeScript 吗？

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

### @arcshape/cli 支持 ESM 还是 CommonJS？

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

### @arcshape/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @arcshape/cli 可以商用吗？

@arcshape/cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @arcshape/cli 的下载量有多少？

根据 npm 官方下载统计，@arcshape/cli 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,699 次，日均约 123 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arcshape/cli 还在维护吗？

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