@cmkk/agentlink 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-11
+
+首次公开发布。
+
+### 新增
+
+- **核心命令**：`init` / `sync` / `clean` / `unlink` / `doctor`
+  - `init` 交互式问 3 个问题（位置 / asset 类型 / adapter），按答案生成带教学注释的 JSONC 配置；`--yes` 一键默认，非 TTY 自动降级，`--dry-run` 完全不写盘
+  - `sync` 自动检测 source（4 级链：`--source` → `AGENTLINK_SOURCE` → `cwd/.agents` → `~/.agents`），按 adapter 投影到目标根；自动清理悬空链接
+  - `doctor` 只读健康检查：adapter 可用性 / link plan / 撞名 / dangling / orphan
+  - `unlink` 递归扫描所有内置 adapter rootDir，移除指向 source 的所有 link（不受 config gate 限制）
+- **内置 adapter（v1）**：cursor（commands flatten、rules `.md → .mdc`）/ claude / codebuddy
+- **JSONC 配置**：`agentlink.config.json` 支持 `//`、`/* */` 注释与尾逗号；zod 严格闭世界 schema 校验
+- **配置文件就近发现**：cwd 上溯到 home 或 fs 根，与 git / eslint / tsconfig 对齐
+- **`--user / -u`**：把投影根从 cwd 改为 `$HOME`，便于把个人 source 链到 `~/.cursor / ~/.claude / ...`
+- **跨链接安全**：撞名检测（默认 warn + skip，`--strict` 升级为退出码 1）；`targetSubdir` 拒绝 `..` 与绝对路径
+- **退出码语义**：sync / clean / unlink / doctor 在任意 errored outcome 时设 `process.exitCode = 1`，便于 CI 集成
+
+### 工程
+
+- 102 vitest 测试，9 个测试文件，覆盖 source / config 解析、layout、linker、各命令
+- TypeScript strict + `exactOptionalPropertyTypes` + `noUncheckedIndexedAccess`
+- ESM-only，tsup 打包，dts 同步生成
+- Node ≥ 18
+
+[Unreleased]: https://github.com/rankangkang/dot-agents/compare/agentlink-v0.1.0...HEAD
+[0.1.0]: https://github.com/rankangkang/dot-agents/releases/tag/agentlink-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rankangkang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# @cmkk/agentlink
+
+> 一行 `npx`，把 `.agents/` 里的 skills / rules / commands 投影到 `.cursor`、`.claude`、`.codebuddy` 等多个 AI 工具目录。
+
+`agentlink` 让 `.agents/` 成为**单一可信源**，再通过逐 agent 的轻量 **adapter**（处理 `flatten`、`rename`、`include / exclude`）投影到各家工具——全程 `symlink`，不复制。
+
+## 为什么需要 agentlink
+
+`.agents/` 正在悄悄成为 AI 工具间的事实约定——Cursor、Codex 已经支持从 `.agents/skills/` 读取 `SKILL.md`，其他 agent 也在跟进。但在这个约定完全统一之前，**同时使用两个以上 AI 编码工具的人，都得在 `.cursor / .claude / .codebuddy / ...` 之间手动复制同一份 skill / rule / command**。而且各家工具还有自己的小约定：
+
+- Cursor 的 commands 目录不支持嵌套（必须扁平）
+- Cursor 的 rules 必须用 `.mdc` 后缀
+- Claude Code 从 `.claude/skills/<name>/SKILL.md` 递归读取
+- CodeBuddy 支持嵌套 commands
+
+`agentlink` 就是为了弥合这个差距：
+
+- **单一可信源** — 所有资产维护在一个 `.agents/` 目录（个人用 `~/.agents`，团队场景用项目内 `cwd/.agents`）。
+- **投影而非复制** — agentlink 在每个目标 agent 的目录下，为每个一级条目创建一个 symlink，并通过声明式 adapter 处理 agent 特有约定（flatten、`.mdc` 重命名、扁平 vs 嵌套）。
+- **与 [`skills.sh`][skills-sh] 互补** — `skills.sh` 负责把 skill 包**安装**（下载）到源目录；`agentlink` 负责把源目录**投影**到多个工具。两者解决的是同一工作流的不同环节：
+
+  ```bash
+  curl -fsSL skills.sh | sh -s install <pkg>   # 安装到 ~/.agents/skills/<pkg>
+  agentlink sync                                # 投影到 .cursor / .claude / ...
+  ```
+
+### 为什么是"逐项 symlink"而不是"整目录 symlink"
+
+最朴素的实现是 `ln -s .agents/skills .cursor/skills`——整目录一条链接，简单。但这样做会让目标目录变成**实际只读**：你没法再往 `.cursor/skills/scratch/` 里临时塞一个一次性的 skill 做实验，因为整个目录已经是源目录的别名。
+
+agentlink 改为**为每个一级条目单独创建一条 symlink**（或当 `flatten: true` 时，按文件粒度）。受管的 skill 与你手写的 skill 可以并存在同一目录里，`unlink` 也只会移除自己创建的那些链接——你的临时实验不会被波及。
+
+[skills-sh]: https://skills.sh
+
+## 快速上手
+
+```bash
+# 1. 在 ~/.agents 建脚手架（或加 --local 建在 ./.agents）
+npx @cmkk/agentlink init
+
+# 2. 把你的 skills/rules/commands 放进 ~/.agents/
+
+# 3. 进入任何含 .cursor/、.claude/ 或 .codebuddy/ 的项目
+cd ~/projects/some-app
+npx @cmkk/agentlink sync
+```
+
+## 命令
+
+```
+agentlink init [--local | --source <path>] [--force] [--yes]
+    交互式创建 .agents/ 脚手架。三个简短提问：
+        1) 放在哪里（~/.agents vs ./.agents）
+        2) 启用哪些资产类型（skills/rules/commands/...）
+        3) 投影到哪些 AI 工具（cursor/claude/codebuddy）
+    --yes / -y    全部用默认值，跳过交互（CI 友好）
+    --local       跳过位置选择，直接用 ./.agents
+    --source <p>  跳过位置选择，用指定路径（自定义路径会打印持久化提示）
+    --force       目标非空时仍然合并（默认会拒绝）
+    管道 / 脚本场景（stdin 非 TTY）自动降级为默认值。
+    生成的 agentlink.config.json 写在"未来 sync 会从哪跑"的位置
+    （--local 写 cwd，否则写 ~），不在 source 内部。
+
+agentlink sync [--source <path>] [--target <dir> | --user] [-n] [-f] [--strict]
+    刷新所有 symlink。source 按以下优先级解析：
+        --source flag → $AGENTLINK_SOURCE → ./.agents → ~/.agents
+    destination root 默认是 cwd；--user / -u 改为 $HOME（把 source
+    投影到 ~/.cursor / ~/.claude / ...），--target <dir> 指定任意项目根。
+    --dry-run / -n      预览将做什么，不动文件系统
+    --force  / -f       修复指向错误的 symlink
+    --strict            flatten 撞名时报错退出（默认仅警告）
+
+agentlink clean
+    清掉每个启用 adapter 目录下的悬空 symlink（指向已删除文件）。
+
+agentlink unlink
+    移除所有指向 source 的 symlink，用于从项目中彻底卸载 agentlink。
+
+agentlink doctor
+    只读健康检查：adapter 可用性、link plan 大小、撞名预警、
+    悬空链接、orphan 链接（之前 sync 留下、当前 plan 不再覆盖）。
+```
+
+`-q/--quiet` 与 `-v/--verbose` 对所有命令通用。
+
+## source 与 config 解析
+
+agentlink 把"**对什么数据操作**"（`.agents/` source）与"**怎么操作**"（`agentlink.config.json`）解耦：两者各有独立解析链，可以共享同一份 source 但每个项目用自己的 config 覆盖行为。
+
+### source 解析
+
+| # | 来源 | 说明 |
+|---|---|---|
+| 1 | `--source <path>` | 显式 flag |
+| 2 | `AGENTLINK_SOURCE` 环境变量 | 适合写在 shell rc |
+| 3 | `./.agents` | **本地优先** — 克隆的项目自带 `.agents/` 时压过个人全局 |
+| 4 | `~/.agents` | 个人推荐默认 |
+| 5 | _(报错)_ | 提示用户跑 `agentlink init` |
+
+### config 解析
+
+| # | 来源 | 说明 |
+|---|---|---|
+| 1 | `--config <path>` | 显式 flag |
+| 2 | `AGENTLINK_CONFIG` 环境变量 | |
+| 3 | 从 cwd 向上找最近的 `agentlink.config.json` | cwd 在 home 内时停在 home；cwd 在 home 外时走到 fs 根 |
+| 4 | `~/agentlink.config.json` | 全局兜底 |
+| 5 | _(默认值)_ | 没找到 = 视为空配置 `{}` |
+
+类似 git / eslint / tsconfig 的就近发现机制。
+
+## 配置文件
+
+配置文件可选——每个字段都是可选的且有合理默认值。格式是 **JSONC**（标准 JSON + `//` `/* */` 注释 + 尾逗号），所以 `agentlink init` 写出的种子文件自带注释，看一眼就能改，不必翻文档。
+
+严格的闭世界 schema（用 [zod] 校验）：adapter 名、asset 类型、顶层字段拼错都会被友好地拒绝。
+
+```jsonc
+{
+  // asset 类型白名单。默认：["skills", "rules", "commands"]
+  // 想启用 prompts / templates / agents 在这里加上即可
+  "include": ["skills", "rules", "commands"],
+
+  // asset 类型黑名单（永远压过 include）
+  "exclude": [],
+
+  // 各 adapter 的覆盖。值可以是 true / false / { layout: ... }
+  "adapters": {
+    "cursor": { "layout": { "commands": { "flatten": false } } },
+    "claude": true,
+    "codebuddy": false
+  }
+}
+```
+
+## 内置 adapter（v1）
+
+| 名称 | rootDir | Skills | Rules | Commands | Prompts |
+|---|---|---|---|---|---|
+| `cursor` | `.cursor/` | 嵌套 | 扁平，`.md` → `.mdc` | 扁平 | _跳过_ |
+| `claude` | `.claude/` | 嵌套 | 嵌套 | 嵌套 | _未配置_ |
+| `codebuddy` | `.codebuddy/` | 嵌套 | 嵌套 | 嵌套 | _未配置_ |
+
+agentlink **只会**在 destination 下已经存在对应 rootDir 时才动它。**绝不会**主动帮你创建 `.cursor/`——要启用某个 agent，要么让 agent 自己跑一遍，要么手动 `mkdir .cursor` 表态。
+
+需要新 agent？v1 仅内置上述三家；提 PR 加一个新 adapter 文件即可。
+
+## 投影示意
+
+```
+~/.agents/skills/brainstorming/SKILL.md        ─┐
+                                                ├─→  .cursor/skills/brainstorming/   (symlink)
+                                                ├─→  .claude/skills/brainstorming/   (symlink)
+                                                └─→  .codebuddy/skills/brainstorming/ (symlink)
+
+~/.agents/rules/coding.md                      ─→   .cursor/rules/coding.mdc        (ext 重命名)
+~/.agents/commands/git/commit.md               ─→   .cursor/commands/git__commit.md (flatten)
+                                                └→  .codebuddy/commands/git/commit.md (保留嵌套)
+```
+
+## 相比手写 symlink
+
+- 所有链接都是**相对路径**：source 和 destination 一起搬家不会断
+- `sync` 是**幂等的**：相同状态下重跑全部 `skipped`
+- `unlink` 只移除"自己拥有"的（指向当前 source 的）链接，目录里其他手写内容不动
+- `--dry-run` 精确告诉你"会做什么"，零写盘
+
+## 运行要求
+
+- Node 18+
+- 支持 symlink 的 POSIX 风格文件系统。Windows 上请在 WSL 内运行或开启开发者模式
+
+## 状态
+
+v1：skill / rule / command 链接、JSONC 配置、三个内置 adapter。
+
+不在 v1 范围（独立追踪）：
+
+- JS / TS 配置文件（`agentlink.config.{js,ts}`）
+- 用户自定义 adapter（通过配置）
+- `link <src> <dest>` 命令式接口
+- watch 模式
+
+## 许可证
+
+MIT.
+
+[zod]: https://zod.dev

package/bin/agentlink.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/cli.js').catch((err) => {
+  console.error('[agentlink] failed to start:', err);
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }