🚀 快速开始

安装 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），合并会被跳过并给出警告，以保护你本地的自定义内容不被覆盖。

其他业务线安装

其他业务线也可能维护了自己的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