amcli — 命令行下的 ArchiMate 模型工具是做什么的？

一个单一的二进制文件，可直接读取和编辑 ArchiMate 模型文件。无需 GUI、无需 JVM、无需服务器。

切勿使用 Read 或 cat 来读取 .archimate 文件。 这些文件可能达到数兆字节的 XML。您有任何问题，只需一个 amcli 命令即可解决，而手动编辑 XML 会破坏模型。

安装

在执行其他操作之前，请先运行以下命令：

amcli --version

如果打印出版本号，即可继续下一节。如果没有：

在 sh 能运行的任何地方 — macOS、Linux、WSL、Git Bash — 请使用此技能附带的安装程序。它位于该文件旁边，通常是 ~/.agents/skills/amcli，对于项目安装则是 ./.agents/skills/amcli：

AMCLI=$(sh ~/.agents/skills/amcli/scripts/install.sh)

它会在标准输出上打印二进制文件的绝对路径，除此之外不输出任何内容。在当前会话的剩余部分使用 $AMCLI。 新安装的二进制文件通常不会在当前 shell 的 PATH 中，因此即使安装成功，直接输入 amcli 仍然会报 "command not found" 错误——这是最常见的错误原因。

原生 Windows PowerShell，如果没有 sh，请使用 PowerShell 版本。它遵循相同的约定：

$AMCLI = & ~\.agents\skills\amcli\scripts\install.ps1

两种安装程序都不会请求权限、不会提升权限，也不会编辑 shell 配置文件。如果没有匹配平台的预编译二进制文件，它会使用 cargo 自行编译。不要从 URL 通过管道执行——它们已经在磁盘上。

查找模型

amcli 会自动查找模型：优先使用 -m PATH，其次是 $AMCLI_MODEL 环境变量，最后是从工作目录向上查找最近的 *.archimate 文件。如果找到多个，则退出码为 4 并列出它们——此时请使用 -m 指定。

工作循环

所有架构问题都从这里开始。不要先翻阅源代码。

amcli stats                       # 这个模型有多大？包含什么内容？
amcli search <term>               # 查找概念，获取其 id
amcli get <id-or-name>            # 查看它是什么，以及它关联的所有内容
amcli trace <id-or-name> -n 2     # 查看邻居关系
# 只有现在才阅读源代码，并且只读模型指向的那些文件

标志含义明确

-t 概念类型   -r 关系类型   -f 文件夹   -D 方向(out|in|both)
-n 深度       -l 限制数量   -m 模型    -F 输出格式   -o 输出文件

主体是位置参数，永远不是标志：

amcli element  add ApplicationComponent "Refund Service" -f /Application
amcli relation add Serving "Refund Service" "Checkout Service"

输出与 token 节约

默认输出是制表符分隔的记录，每行一条——读取成本低，且易于使用 cut -f2。计数和提示信息输出到 stderr。仅当需要嵌套结构（例如 get 内部的关系 ID）时才添加 -F json。

amcli query 'layer=Application' --count    # 始终“首先”询问数量
amcli search auth -l 10 --fields id,name   # 投影缩小字段
amcli list --fields -documentation         # 或者去掉某个字段

切勿对不熟悉的模型执行未过滤的 list。请先运行 amcli stats。

寻址概念

id:5dde26f7                      一个 id——始终明确，始终优先使用
"Payment API"                   精确名称
ApplicationComponent:"Payment"  带有类型的限定名称
"*Payment*"                     通配符

过滤表达式，作为一个参数引用：

amcli query 'type=ApplicationComponent and name~payment'
amcli query 'prop:owner=team-a and not folder^=/Technology'
amcli query 'layer=Application and deg>10'
amcli query 'out:Access~Customer'    # 查找所有访问匹配项的内容

运算符：= 精确匹配 · ~ 包含 · ^= 前缀匹配 · =~ 正则 · != · > < 用于 deg。字段：id name type layer folder doc deg view prop:KEY in:RelType out:RelType。

退出码——根据退出码分支，不要解析消息

0 成功   2 用法错误   3 未找到   4 歧义   5 无效   6 冲突
7 IO 错误   8 不支持

如果退出码为 3，响应会列出最接近的名称——使用其中一个重试，不要重新运行搜索。如果退出码为 4，则会列出候选，每个都带有可以立即粘贴使用的 id: 选择器。切勿通过猜测来解决歧义；请使用 id 重新运行。

图查询

amcli path "Web App" "Customer Database"   # 它们如何连接？
amcli impact id:5dde26f7 -D in             # 如果此内容更改，会破坏什么？
amcli neighbors id:5dde26f7 -r Serving     # 仅限 Serving 关系
amcli descendants "Payments Capability"    # 组合树
amcli cycles                               # 依赖循环

编辑

amcli element  add ApplicationComponent "Refund Service" --doc "…"
amcli element  rename id:c40a19b7 "Refunds Service"
amcli relation add Access "Refunds Service" "Refund Record" --access rw
amcli prop set id:c40a19b7 owner team-payments
amcli element  delete id:c40a19b7 -y

每次写入操作都会先根据 ArchiMate 关系矩阵进行检查，如果标准禁止该关系，则拒绝（退出码 5）——并且拒绝信息会列出在这两种类型之间允许的关系，因此请阅读它，而不是再次猜测。

默认情况下，删除操作在会导致级联删除时拒绝，并且拒绝信息就是影响报告。确认后添加 -y。

不确定时使用 --dry-run。当您在前面轮次中读取了模型、现在进行写入时，请使用 --expect-checksum：

CS=$(amcli info -F json -q | jq -r '.[0].checksum')
amcli element rename id:x "New" --expect-checksum "$CS"    # 如果模型已修改则退出码为 6

对于超过两次编辑的情况，请使用一个原子批处理而不是一系列操作。

amcli apply - <<'EOF'
{"op":"element.add","type":"ApplicationComponent","name":"Refund Service","ref":"r","if_absent":true}
{"op":"element.add","type":"DataObject","name":"Refund Record","ref":"rec","if_absent":true}
{"op":"relation.add","type":"Access","source":"ref:r","target":"ref:rec","access":"rw","if_absent":true}
EOF

ref 命名某行的结果，以便后续行可以引用该结果（即使在 id 尚未存在时）。if_absent 使批处理可以安全地重新运行。如果任何一行失败，则不会写入任何内容，文件保持字节不变。

完成任何编辑之前

amcli validate

退出码 5 表示模型存在错误。每个错误发现都会指明文件中的行号，并附带一个 fix 命令。amcli validate --fix 仅应用那些可推导而非可选择的修复——例如孤立的图表对象和过时的视图镜像——绝不会删除任何人的建模内容。

视图与图表

amcli view list
amcli view auto "Refund Flow" --from "Refund Service" -n 2 --layout layered
amcli view render "Refund Flow" -o refund.svg
amcli export mermaid                       # 为聊天快速生成内联图表

view render 绘制模型实际存储的几何形状。export mermaid 和 export dot 会重新布局，因此它们适合快速查看，不适合再现某人的图表。

深入了解

命令	适用场景
`amcli skill commands`	需要上面未列出的子命令或标志——它打印完整的命令树，并从您实际运行的二进制文件中读取，因此永远不会过时
`amcli <command> --help`	需要详细了解一个命令的标志
`references/types.md`	需要确切的 ArchiMate 3.2 类型名称，或了解两种类型之间哪些关系是合法的
`references/batch.md`	正在编写超过大约十个操作的批处理

amcli — 命令行下的 ArchiMate 模型工具