🚀 快速开始

安装 AI 开发助手时，先打开终端并进入项目根目录。然后根据所使用的 IDE，按照下方对应的操作步骤执行。

⚠️ 安装说明：当前采用复制覆盖的方式进行安装和更新。如果项目中已存在 AGENTS.md 等全局配置文件，安装或更新过程中将直接覆盖这些文件。建议提前备份相关内容，或确认文件差异后再执行操作。

node版本要求：node >= 18

安装AI助手

执行命令后，根据提示选择使用的 IDE，回车确认即可将当前仓库的 Skills、Rules 等配置同步到项目根目录。

npx @kyfe/ai-tools@latest init

更新AI助手

npx @kyfe/ai-tools@latest update

自定义配置（Sidecar 机制）

安装或更新时，部分文件支持通过 sidecar 文件保留你的自定义内容，避免被远端模板覆盖。sidecar 文件使用 .local 后缀命名，与主文件物理隔离，不会污染最终生成的文件。

AGENTS.md

在项目根目录创建 AGENTS.local.md，写入你的自定义规则。执行 update 时，该文件内容会自动追加到 AGENTS.md 末尾。

# AGENTS.md（远端模板生成，不要手动编辑）
...远端规则...

# 以下来自 AGENTS.local.md（自动追加）
...你的自定义规则...

openspec/config.yaml

在 openspec/ 目录下创建 config.local.yaml，按字段声明自定义内容。默认合并策略：

| 字段 | 策略 | 说明 | |------|------|------| | schema | overwrite | sidecar 有值则覆盖远端 | | context | appendText | 远端与 sidecar 文本拼接 | | rules.proposal | appendArray | 远端与 sidecar 数组合并 | | rules.design | appendArray | 同上 | | rules.tasks | appendArray | 同上 | | rules.spec | appendArray | 同上 | | rules.implementation | appendArray | 同上 |

config.local.yaml 示例：

schema: https://example.com/my-schema/v2
context: 项目特定上下文说明
rules:
  proposal:
    - 自定义 proposal 规则 1
    - 自定义 proposal 规则 2

_merge 元字段：按字段覆盖默认策略

如果默认策略不满足需求，可以在 config.local.yaml 顶层添加 _merge 字段，为任意字段声明策略（overwrite / appendText / appendArray / skip）。_merge 只存在于 sidecar，不会出现在最终的 config.yaml 中。

# 覆盖默认策略：让 context 也使用 overwrite 而非 appendText
_merge:
  context: overwrite
  rules.proposal: skip   # 跳过 proposal 合并，只保留远端

context: 我的上下文（覆盖远端）
rules:
  design:
    - 自定义 design 规则

未在 _merge 或默认策略中声明的字段会被 skip（保留远端，忽略 sidecar 值）。

冲突保护

如果远端仓库中也存在同名的 sidecar 文件（如 AGENTS.local.md 或 config.local.yaml），合并会被跳过并给出警告，以保护你本地的自定义内容不被覆盖。

项目级配置（.airc.yaml）

在项目根目录放置 .airc.yaml，可以覆盖默认的 openspec 模板来源路径。当前只支持 openspec_dir 字段，其他字段保留给未来扩展。

openspec_dir

字符串，相对仓库根的路径，可带前导 /。当模板仓库将不同业务线的 openspec 配置分别放在 openspec/taro-miniui/、openspec/xxx/ 等子目录时，通过此字段指定使用哪个子目录。

支持两种 YAML 格式：

嵌套格式（推荐） — 将 openspec 相关配置放在 openspec 命名空间下：

# .airc.yaml
openspec:
  openspec_dir: /openspec/taro-miniui

顶层格式（向后兼容）：

# .airc.yaml
openspec_dir: /openspec/taro-miniui

等同于：

openspec_dir: openspec/taro-miniui

前导 / 会被自动规范化（path.join 行为），两种写法结果一致。当同时存在嵌套与顶层格式时，优先使用嵌套格式。

生效范围与行为

• init / update 时生效：openspec 复制项会从 <repoRoot>/<openspec_dir> 读取，而非默认的 <repoRoot>/openspec。
• 与 GitLab tree URL 共存：即使传入 tree URL 让 sourceRoot 指向仓库子目录，openspec 仍从 <repoRoot>/<openspec_dir> 读取，其他复制项继续走 sourceRoot。
• add 命令的业务逻辑不受 openspec_dir 影响（技能仍从 <sourceRoot>/skills/<skillName> 读取）。
• 配置的 openspec_dir 路径在仓库中不存在时，openspec 复制项会被跳过并记录在 skipped 列表（与其他缺失源的行为一致）。

错误处理

• .airc.yaml 不存在 → 沿用默认配置。
• .airc.yaml 存在但缺少 openspec_dir（或为空字符串） → 回退默认 openspec。
• .airc.yaml YAML 语法错误 → 所有命令（包括 add）在启动期失败 fast，打印文件路径与解析错误。
• openspec_dir 类型非字符串（如数字、列表） → 启动期失败 fast。
• openspec 命名空间存在但非 object（如标量、数组） → 启动期失败 fast。

下线清单（.aicli/retired.yaml）

模板仓库删除或重命名某个 skills/<name>、rules/<file> 后，用户本地的对应目录会一直残留——复制是「覆盖」语义，不会清理已消失的路径。维护者只需在模板仓库根放置 .aicli/retired.yaml 声明下线，用户下次 init / update 时 CLI 会照单删除本地对应路径。

# .aicli/retired.yaml（模板仓库根）
version: 1
items:
  - path: skills/openspec-explore
    scope: ide
    reason: 已合并进 skills/openspec-propose
  - path: docs/legacy.md
    scope: global

字段

| 字段 | 必填 | 说明 | |---|---|---| | path | 是 | 相对作用域根的路径，可指向文件或目录（目录整体删除，含其中所有文件） | | scope | 是 | ide → 相对 IDE 目录（如 .codebuddy）；global → 相对项目根。不设默认值 | | reason | 否 | 仅用于人工阅读 |

生效范围与行为

• 只在 init / update 时生效，且在复制之前执行（先删后拷）。
• 自愈：清单中的路径在模板仓库中仍存在（上游已复活或清单忘记清理）→ 跳过删除，复制阶段照常写入。
• 幂等：本地路径已不存在 → 跳过，不报错。
• 被删除的路径会在命令结束时列出（已下线 N 个路径：...）。

安全边界

以下情况会 fail fast（本次同步终止，且不会删除任何文件）：

• path 缺失 / 非字符串 / 为空
• 绝对路径，或包含 .. 段
• 解析后逃逸出作用域根，或等于作用域根本身
• 首段不在受管目标集合内（由 globalCopies / ide.copies 的 to 推导，如 skills、rules、docs）——因此 src/、node_modules/ 永远不会被命中

错误处理

| 情况 | 行为 | |---|---| | 清单不存在 / 空文档 / 仅注释 | 无下线，正常继续 | | YAML 语法错误 | fail fast，打印文件路径与解析原因 | | 顶层非对象 / items 非数组 | fail fast | | 条目结构非法（缺 path、scope 非法） | fail fast |

该清单是控制面文件：不在任何复制项的 from 中，因此不会被复制到你的项目，只随临时克隆目录被读取后销毁。

其他业务线安装

其他业务线也可能维护了自己的skill、或rules。当前cli也支持使用其他仓库地址进行相同文件覆盖同步。

// 增量同步其他仓库的skill、或rules
npx @kyfe/ai-tools@latest init [email protected]:erp-frontend/tms-ai-kits.git

// 更新
npx @kyfe/ai-tools@latest update [email protected]:erp-frontend/tms-ai-kits.git