AIDEV CLI

一个不自带模型、不替代 Codex / Cursor / VS Code Agent 的全局开发工作流桥接工具。

AIDEV 只做两类事情：

1. 通过 Agent Skills symlink 给开发平台临时装载统一开发 SOP。
2. 通过 aidev context / aidev verify 提供项目上下文与确定性验证。

它不会修改平台 User Rules、AGENTS.md、平台 settings，也不会往业务项目写 .aidev、.cursor、.vscode 等配置。

1. 安装与本地开发

pnpm install
pnpm build
npm link

确认：

aidev --version
aidev doctor

发布 npm 后则可以直接：

npm install -g yeah-aidev

发布前请把 package.json 中的包名改成你实际拥有的 npm scope / package name。

2. 推荐使用方式

默认：共享 Agent Skills 挂载

aidev on

会挂载到：

~/.agents/skills/

AIDEV 创建的是 symlink，实际 Skill 内容保存在：

~/.aidev/skills/

完成工作后：

aidev off

Cursor 专用挂载

aidev on cursor

挂载到：

~/.cursor/skills/

卸载：

aidev off cursor

VS Code 专用挂载

aidev on vscode

挂载到：

~/.copilot/skills/

卸载：

aidev off vscode

Codex

aidev on codex

Codex 映射到共享挂载：

~/.agents/skills/

因此启用期间，其他同样读取该共享目录的 Agent 也可能看到这些 Skill。

一键关闭全部挂载

aidev off all

同步最新 Skill

升级 npm 包（例如 npm install -g yeah-aidev@latest）后，运行下面命令，把当前安装包内的最新 Skill 覆盖同步到本地 ~/.aidev/skills/：

aidev sync

由于挂载均为指向 ~/.aidev/skills/ 的 symlink，同步后现有挂载会自动指向最新内容，无需重新执行 aidev on。

3. 为什么不会污染原始 Agent 配置

AIDEV 的安全原则：

• 不写 ~/.codex/AGENTS.md
• 不写 ~/.codex/config.toml
• 不写 Cursor User Rules
• 不写 VS Code Personal Instructions
• 不写任何项目内规则文件
• 不覆盖任何已经存在的 Skill 路径
• 只通过 symlink 临时暴露 AIDEV Skill

aidev off 删除链接时还会进行三重校验：

1. 该路径必须记录在 ~/.aidev/state.json 中；
2. 当前路径必须仍然是 symlink；
3. symlink 必须仍然准确指向对应的 ~/.aidev/skills/...。

任意一项不满足，AIDEV 都不会删除该路径。

如果某个目标路径原来已经存在，例如：

~/.cursor/skills/aidev-fix

且不是 AIDEV 自己管理的链接，则：

aidev on cursor

会直接终止，并保证本次激活不会创建其他链接。

4. 避免 Skill 重复发现

不要同时使用：

shared + cursor
shared + vscode

AIDEV 会主动阻止这种状态。

如果当前使用平台专用挂载，想切换共享模式：

aidev off all
aidev on

如果当前使用共享模式，想只对 Cursor 生效：

aidev off
aidev on cursor

5. 日常 Agent 工作流

启用：

aidev on

然后正常打开自己的开发平台，不需要通过 AIDEV 启动 Agent：

Codex / Cursor / VS Code
          │
          ▼
   平台自己的 Agent
          │
          ├── 发现 AIDEV Skills
          │
          ├── aidev context
          │
          └── aidev verify

例如直接告诉 Agent：

修复搜索条件变化后分页没有恢复第一页的问题。

当对应 Skill 被使用时，它会遵循 root-cause / minimal-change / verify 等工作流。

6. 内置 Skills

aidev-dev

普通功能开发：先理解现有实现、最小修改、完成后验证。

aidev-fix

Bug 修复：先明确 Expected / Actual，再基于证据确认 Root Cause，最后验证。

aidev-debug

问题排查：Hypothesis -> Evidence -> Root Cause -> Fix。

aidev-review

Code Review：重点关注 correctness / regression / error handling / type safety / security / tests，避免无意义 Style 噪音。

7. 项目上下文

在任何项目目录：

aidev context

示例：

# AIDEV PROJECT CONTEXT

Project: admin-web
Root: /Users/me/work/admin-web
Technologies: Node.js, TypeScript, React, Vite
Package manager: pnpm
Git branch: main
Pre-existing working tree changes: 2

Verification commands:
  lint: pnpm run lint
  typecheck: pnpm run typecheck
  test: pnpm run test
  build: pnpm run build

JSON：

aidev context --json

查看更简洁的项目分析：

aidev analyze
aidev analyze --json

8. 自动验证

aidev verify

当前 Node.js 项目会优先从 package.json 自动寻找：

lint
check:lint

typecheck
type-check
check:types
check:typescript

test
test:unit

build
compile

执行顺序：

lint
  ↓
typecheck
  ↓
test
  ↓
build

默认 fail-fast。

如果希望一个失败后继续跑其他检测：

aidev verify --all

TypeScript 项目如果没有 typecheck script，但存在本地：

node_modules/.bin/tsc

AIDEV 会使用当前项目包管理器执行：

pnpm exec tsc --noEmit
npm exec -- tsc --noEmit
yarn exec tsc --noEmit
bun x tsc --noEmit

AIDEV 不会为了 typecheck 自动下载 TypeScript。

如果一个项目没有检测到任何确定性验证命令：

aidev verify

返回 exit code 2，而不是假装验证成功。

9. 支持的 Node 包管理器

自动识别：

pnpm
npm
yarn
bun

优先读取 package.json#packageManager，其次读取 lockfile。

10. 状态检查

aidev status

示例：

AIDEV Status

Home: ~/.aidev
Mounts:
  ✓ shared  aidev-dev      active
  ✓ shared  aidev-fix      active
  ✓ shared  aidev-debug    active
  ✓ shared  aidev-review   active

Managed platform config files: 0
Managed project files: 0

JSON：

aidev status --json

11. Doctor

aidev doctor

检查：

• bundled skills 是否存在
• ~/.aidev Skill Source 是否存在
• 当前 mount 是否完整
• git / codex / cursor / code 是否在 PATH
• 当前项目技术栈与验证命令

12. 全局目录

~/.aidev/
├── skills/
│   ├── aidev-dev/
│   ├── aidev-fix/
│   ├── aidev-debug/
│   └── aidev-review/
└── state.json

平台目录中只存在临时 symlink，例如：

~/.agents/skills/aidev-fix
  -> ~/.aidev/skills/aidev-fix

13. 环境变量

自定义 AIDEV 数据目录

AIDEV_HOME=/path/to/aidev aidev status

自定义用户 Home

主要用于测试或完全隔离的 Profile：

AIDEV_USER_HOME=/tmp/test-home aidev on

verify 超时

默认单个检查最长 10 分钟。

可以覆盖：

AIDEV_VERIFY_TIMEOUT_MS=1800000 aidev verify

14. 卸载

先卸载所有挂载：

aidev off all

确认：

aidev status

然后卸载 CLI：

npm uninstall -g yeah-aidev

如果你不再需要自己的 AIDEV Skill 数据，可以最后手动删除：

rm -rf ~/.aidev

AIDEV CLI 自己不会在 off 时删除 ~/.aidev，因为这是它自己的持久数据源，不属于平台污染。

15. 开发测试

pnpm install
pnpm build
pnpm test

测试覆盖：

• shared on/off 可逆
• on 重复执行幂等
• 已有目标路径冲突时零修改退出
• symlink target 被外部修改后绝不误删
• shared 与 platform-specific mount 互斥
• off all
• Node 项目分析
• 自动 verify

16. 当前范围

这一版刻意不做：

• 模型调用
• Agent Runtime
• MCP
• User Rules 修改
• AGENTS.md 注入
• 项目配置注入
• Knowledge / RAG
• 自动 commit / push / publish / deploy

AIDEV 的职责保持为：

Agent Skills 装载层
+
项目上下文层
+
确定性验证层