Wing CLI

面向 AI 编程工作流的项目元数据管理工具。在项目内建立并维护一套统一、可校验、可扩展的 Agent 协作元数据：根/局部 AGENTS.md、领域文档、ADR、文档 frontmatter、OpenSpec 基础结构检查等。

前身为 Agent Meta CLI（@bossmissing/agent-meta）。包内同时提供 wing 与 meta 两个命令别名；配置文件新名为 wing.config.yaml，旧项目的 agent-meta.config.yaml 继续可读，wing upgrade 会自动迁移改名。

完整需求见 docs/prd.md。

安装

pnpm add -D @bossmissing/wing
pnpm exec wing init

本仓库内开发：

pnpm install
pnpm dev -- init          # tsx 直接运行
pnpm build                # 编译到 dist/
pnpm test                 # Vitest

命令

| 命令 | 用途 | | --- | --- | | wing init | 初始化 Agent Meta 基础结构（--yes 非交互，--type，--language，--with-mcp <pack>，--with-deploy <target>，--dry-run）。技术栈约定按语言生成到 docs/engineering/tech-stack.md（Go 默认 gin + gorm + DDD）；测试约定按项目形态拼装到 docs/engineering/testing.md（小程序默认 miniprogram-automator + jest）。monorepo 会扫描 workspace 子包记入 project.subprojects，小程序子包额外生成局部 AGENTS.md | | wing new-domain <name> | 创建领域文档目录与局部 AGENTS.md（--title --owner --with-state-machine --with-glossary --no-local-agents --force --dry-run） | | wing new-adr <slug> | 自动编号创建 ADR（--title --owner --status --path --dry-run） | | wing check | 确定性元数据校验（--strict --docs --adr --agents --openspec --json） | | wing audit | 治理分析报告，不阻塞、不改文件（--agents --docs --risk --json） | | wing sync | 重建 docs/domain / docs/adr 索引，调用 openspec update（--indexes --openspec --dry-run） | | wing new-change <name> | 创建 OpenSpec 兼容变更目录（--domain --schema --dry-run），高风险领域自动附带 risk-review.md | | wing add deploy <target> / wing add mcp <pack> | 给已 init 的项目事后追加工具包：安装逻辑与 init 相同（增量、已有文件不动），并把 pack 规则幂等地追加进现有 AGENTS.md 的 ## Working Rules 章节（--dry-run） | | wing upgrade | 升级老项目到当前 CLI 版本：增量补齐新版本新增的文件（已有文件绝不覆盖）、刷新已安装的 pack skills（CLI 资产，直接覆盖到最新）、刷新 project.subprojects 检测缓存、对生成文档做漂移报告（如检测到 react 子包但 tech-stack.md 缺 React 章节时给出提示，不自动改动用户文档）（--dry-run） | | wing doctor | 检查运行环境：Node、包管理器、配置、路径、Git Hook、OpenSpec（--json） | | wing review | 定期仓库 review checklist：文档 / 代码 / 测试 / 安全，能机器判定的项实时给出 ✓/✗。文档按明确范围枚举（产品 / 架构 / 接口 / 领域 / ADR / 工程规范 / Runbooks / Agent 规则 / OpenSpec），附真实文件清单；--pick-docs 交互式让人类确认本轮整理哪些（--json） | | wing preflight | 上线前 checklist：自动跑 wing check --strict，人工项含"人类已 review 代码"；--confirm 逐项要求人类确认，未全部确认退出码 1（--json） | | wing config list / set | 查看与修改 wing.config.yaml | | wing config hooks lefthook | 生成/合并 lefthook.yml，在 pre-commit 运行 wing check（--dry-run） |

退出码

| 退出码 | 含义 | | --- | --- | | 0 | 无 error（warning 不阻塞；--strict 除外） | | 1 | 存在校验 error | | 2 | 命令参数错误 | | 3 | 配置文件无法解析 | | 4 | 文件系统 IO 错误 | | 5 | 模板缺失或损坏 |

典型流程

wing init --yes

wing new-domain withdrawal \
  --title "提现与打款" \
  --owner payments \
  --with-state-machine

wing new-adr withdrawal-idempotency \
  --title "提现打款采用业务幂等键" \
  --owner payments

wing check --strict

硬限制（Hard Constraints）

硬限制是不可违反的约束（安全、数据一致性、API 契约、性能预算、兼容性、合规）；没有显式声明的限制，AI 会当成可协商的。声明位置只有两处：

• 领域级：docs/domain/<domain>/rules.md 的 ## 硬限制（不可违反） 章节
• 项目级：docs/engineering/constraints.md

工具链全生命周期支持：wing init 生成容器与 AGENTS.md 规则；wing new-change --domain <d> 把该领域已声明的硬限制原文打印进上下文；wing check 对高风险领域校验硬限制非空（HIGH_RISK_DOMAIN_MISSING_HARD_CONSTRAINTS，warning 级，--strict 下阻塞）；wing review 实测声明完整性并提醒排查漂移；wing preflight 上线前列出全部硬限制声明文件供人工核对。

必装项（每次 init 强制安装，不可选）

wing init 会无条件安装下面三项——不受任何 flag 或交互选择影响，任何 Wing 管理的仓库都会带上；wing upgrade 会把它们刷新/补装到当前版本：

| 必装项 | 安装内容 | 作用 | | --- | --- | --- | | wing-cli skill | .claude/skills/wing-cli/ + 一条 AGENTS.md 规则 | 教 agent 在本仓库如何用 wing：收尾前 wing check、用 wing new-domain / new-adr / new-change 脚手架而非手搓、改动后 wing sync 重建索引、把 docs/engineering/constraints.md 与各领域 rules.md 硬限制当作事实来源 | | superpowers 插件 | .claude/settings.json（marketplace + enabledPlugins，已有值不覆盖）+ 一条 AGENTS.md 规则 | Claude Code planning/TDD/debugging 插件（obra/superpowers）；默认不用 brainstorming，除非人类明确要求 | | OpenSpec | 调用 openspec init --tools claude --force，生成 openspec/（config + specs + changes）与 .claude/commands/opsx/、openspec 相关 skills | 规格驱动的变更流程；需本机已装 OpenSpec CLI，缺失时告警跳过（可后续 wing sync） |

可选 MCP 工具包

wing init 可选安装工具包（交互式多选，或 --with-mcp <pack>[,<pack>] 非交互指定）。安装内容全部是项目级的，与"默认不使用全局工具"的 AGENTS.md 规则配套：

• .mcp.json — 项目级 MCP server 配置（合并写入，绝不覆盖已有条目）
• .claude/settings.json — Claude Code 插件配置（marketplace + enabledPlugins，已有值绝不覆盖）
• .claude/skills/ — 配套 skills（已存在的文件跳过）
• AGENTS.md — pack 附带的使用规则（仅注入新生成的 AGENTS.md）

当前可用的 pack：

| Pack | 安装内容 | 附带 | | --- | --- | --- | | ironbank | MCP：https://test-ib-mcp.hillinsight.tech/mcp | skills：ironbank-mcp-reference / ironbank-citations / ironbank-docs-research / ironbank-note-links；AGENTS.md 规则：文档与 bug 记录在 IronBank，遇到 hillinsight://ib_note?... 深链用 MCP 解析，引用笔记时输出同格式链接 | | playwright | MCP：npx @playwright/mcp@latest（microsoft/playwright-mcp，浏览器自动化） | — | | dev-env | skills：dev-env（本地环境约定：项目进程本机启动，redis/mysql/mq 等中间件用 docker compose 启动，compose 只声明中间件） | AGENTS.md 规则：中间件依赖走 Docker，绝不本机全局安装 |

wing init --yes --with-mcp ironbank,playwright

安装后请提交 .mcp.json、.claude/settings.json 和 .claude/skills/，团队成员即可获得相同的工具配置。

部署 skill

wing init 时可选择部署方式（交互式单选，或 --with-deploy <target> 非交互指定），安装对应的部署 skill 到 .claude/skills/，并在新生成的 AGENTS.md 里注入部署规则：

| Target | 部署方式 | Skill 要点 | | --- | --- | --- | | cloudflare | 本地 wrangler CLI 部署 Workers / Pages | 部署前跑 build+test；secrets 用 wrangler secret put；部署后 curl 验证 + wrangler tail 排错 | | ansible | Ansible playbook 部署云主机（ECS/EC2/VPS） | deploy/ansible/ 目录约定；Windows 或无 ansible 时用 Docker 运行 ansible-playbook；先 --check 干跑再实跑 | | github-actions | GitHub Actions workflow CI/CD | build+test 通过才部署；gh secret set 管理 secrets；gh run watch 监控 | | none | 暂时不集成部署（默认） | — |

wing init --yes --with-deploy cloudflare

模板覆盖

在项目内创建 templates/wing/<name>.tmpl 可覆盖内置模板（仅支持 {{variable}} 替换）：

templates/wing/adr.md.tmpl
templates/wing/domain-readme.md.tmpl
templates/wing/domain-rules.md.tmpl
templates/wing/domain-state-machine.md.tmpl
templates/wing/domain-agents.md.tmpl
templates/wing/agents.md.tmpl

可用变量：{{project_name}} {{project_type}} {{date}} {{owner}} {{domain_name}} {{domain_title}} {{adr_number}} {{slug}} {{status}}。

CI 集成

- run: pnpm exec wing check --strict

Git Hook（lefthook）— 由 wing config hooks lefthook 自动生成或合并：

pre-commit:
  commands:
    meta-check:
      run: pnpm exec wing check

环境自检：

wing doctor          # Node / 包管理器 / 配置 / 路径 / Git Hook / OpenSpec
wing doctor --json