@s_s/agent-kit 1.0.0

package/README.md

@@ -0,0 +1,317 @@
+# Agent Kit
+
+MCP Server / Skill 开发基础设施库。提供 agent 检测、prompt 注入、hook 安装和跨平台数据目录等通用能力，让多个 MCP/Skill 项目共享同一套 agent 适配层，避免重复实现。
+
+## 功能
+
+- **Agent 检测** — 通过文件系统特征或 MCP clientInfo 自动识别 agent 类型（OpenCode、Claude Code、OpenClaw、Codex）
+- **Prompt 注入** — 向 agent 配置文件（`AGENTS.md`、`CLAUDE.md`、manifests 等）注入自定义指令，支持幂等更新
+- **Intent-based Hook 系统** — 按意图声明，自动翻译为各 agent 原生格式，支持三层优先级和显式降级
+- **跨平台数据目录** — 自动适配 macOS / Linux / Windows，支持 global / project 两种作用域
+- **零运行时依赖** — 纯 TypeScript，零 dependencies
+- **工厂模式** — `createKit(name)` 返回绑定了工具名的函数集，支持解构，无全局状态
+
+## 安装
+
+```bash
+npm install @s_s/agent-kit
+```
+
+## 快速开始
+
+```typescript
+import { createKit, hooks, detectAgent } from '@s_s/agent-kit';
+
+// 1. 创建 kit 实例（支持解构）
+const { injectPrompt, installHooks, getDataDir } = createKit('my-mcp');
+
+// 2. 声明 hook 意图（全局 API，不绑定实例）
+hooks.inject({
+  perTurn: 'Remember to use my-mcp tools when relevant.',
+  sessionStart: 'Welcome! Check my-mcp for context.',
+  compaction: 'Preserve my-mcp context during compaction.',
+});
+
+hooks.beforeToolCall({
+  match: /^Bash/,
+  handler: (ctx) => {
+    if (ctx.args.command?.includes('rm -rf')) {
+      return { block: true, reason: 'Dangerous command blocked' };
+    }
+  },
+});
+
+// 3. 检测当前 agent
+const agent = await detectAgent();
+if (!agent) throw new Error('No supported agent detected');
+
+// 4. 注入 prompt 到 agent 配置文件
+await injectPrompt(agent, '## My MCP\nInstructions for the agent...');
+
+// 5. 安装 hooks（自动翻译为 agent 原生格式）
+const result = await installHooks(agent);
+console.log(`Hooks installed: ${result.filesWritten.join(', ')}`);
+console.log(`Warnings: ${result.warnings.join('\n')}`);
+
+// 6. 获取数据目录路径
+const dataDir = getDataDir(); // global scope
+const projectDir = getDataDir({ scope: 'project', projectRoot: '/path/to/project' });
+```
+
+## API
+
+### `createKit(name, options?)`
+
+创建一个绑定了工具名的 kit 实例。返回的对象包含所有需要工具名的函数。
+
+```typescript
+createKit(name: string, options?: KitOptions): Kit
+```
+
+| 参数                  | 类型                                    | 说明                             |
+| --------------------- | --------------------------------------- | -------------------------------- |
+| `name`                | `string`                                | 工具名称（必填）                 |
+| `options.dirs`        | `{ global?: string, project?: string }` | 自定义数据目录名                 |
+| `options.envOverride` | `string`                                | 覆盖全局数据目录路径的环境变量名 |
+
+`name` 是整个包的核心锚点：
+
+- Prompt 标记：`<!-- {name}:start -->` / `<!-- {name}:end -->`
+- Hook 目录 / 文件名前缀
+- 项目级数据目录：`.{name}`
+- 环境变量：`{NAME}_DATA_DIR`（默认，大写 + 下划线）
+
+返回的 Kit 对象包含以下方法：
+
+| 方法                                    | 说明                          |
+| --------------------------------------- | ----------------------------- |
+| `injectPrompt(agent, prompt, options?)` | 注入 prompt 到 agent 配置文件 |
+| `hasPromptInjected(agent, options?)`    | 检查 prompt 是否已注入        |
+| `installHooks(agent)`                   | 安装 hooks                    |
+| `uninstallHooks(agent)`                 | 卸载 hooks                    |
+| `hasHooksInstalled(agent)`              | 检查 hooks 是否已安装         |
+| `getDataDir(options?)`                  | 获取跨平台数据目录路径        |
+
+### Hook 系统
+
+Hook 系统分为两个阶段：**声明**和**安装**。
+
+1. **声明**：通过全局 `hooks.*` API 声明意图（`inject` / `beforeToolCall` / `afterToolCall` / `onSession` / `onPermission`），以及 `raw` / `extend` 两种高级注册方式
+2. **安装**：调用 `kit.installHooks(agent)` 时，从全局注册中心读取所有声明，翻译为目标 agent 的原生格式并写入磁盘
+
+详细的 API 说明、示例、三层优先级机制和降级行为，请参阅 **[Hook 使用指南](docs/hook-usage.md)**。各 agent 原生 hook 能力的完整横向对比，请参阅 **[Hook 横向对比](docs/hooks-comparison.md)**。
+
+### Kit 方法详情
+
+#### `kit.injectPrompt(agent, prompt, options?)`
+
+向 agent 配置文件注入提示内容。
+
+```typescript
+injectPrompt(agent: AgentType, prompt: string, options?: ScopeOptions): Promise<void>
+```
+
+- 首次调用：追加到文件末尾
+- 后续调用：替换已有标记块（幂等更新）
+- 自动创建目录和文件
+
+#### `kit.installHooks(agent)`
+
+为指定 agent 安装 hooks。从 hook 注册中心读取所有声明，翻译为原生格式，写入文件。
+
+```typescript
+installHooks(agent: AgentType): Promise<HookInstallResult>
+```
+
+返回值包含完整的降级信息：
+
+```typescript
+interface HookInstallResult {
+  success: boolean;
+  hookDir: string;
+  filesWritten: string[];
+  settingsUpdated: boolean;
+  notes: string[];
+  warnings: string[]; // 降级/冲突警告
+  skipped: SkippedIntent[]; // 被跳过的意图
+  error?: string;
+}
+```
+
+各 agent 的翻译方式：
+
+| Agent               | 生成内容                                                |
+| ------------------- | ------------------------------------------------------- |
+| claude-code / codex | Shell 脚本（多个原生 hook），自动注册到 `settings.json` |
+| openclaw            | `HOOK.md` + `handler.ts`（内部 hook + 插件 hook）       |
+| opencode            | 单个 TypeScript 插件文件（多个 hook 合并）              |
+
+#### `kit.uninstallHooks(agent)`
+
+清理已安装的 hook 文件和 settings.json 条目。
+
+```typescript
+uninstallHooks(agent: AgentType): Promise<{ success: boolean; removed: string[]; error?: string }>
+```
+
+#### `kit.getDataDir(options?)`
+
+获取跨平台数据目录路径。
+
+```typescript
+getDataDir(options?: ScopeOptions): string
+```
+
+| 作用域           | 路径                                                                                                         |
+| ---------------- | ------------------------------------------------------------------------------------------------------------ |
+| `global`（默认） | macOS: `~/Library/Application Support/{name}` / Linux: `~/.local/share/{name}` / Windows: `%APPDATA%/{name}` |
+| `project`        | `{projectRoot}/.{name}`                                                                                      |
+
+全局路径可通过环境变量覆盖（默认变量名：`{NAME}_DATA_DIR`）。
+
+### 独立函数
+
+以下函数不依赖 kit 实例，可直接使用。
+
+#### `detectAgent(cwd?)`
+
+通过文件系统特征检测当前环境中的 agent 类型。
+
+```typescript
+detectAgent(cwd?: string): Promise<AgentType | null>
+```
+
+按固定顺序检测：opencode → claude-code → openclaw → codex。返回第一个匹配的类型，或 `null`。
+
+#### `detectAgentFromClient(clientName)`
+
+将 MCP `clientInfo.name` 映射为 `AgentType`。
+
+```typescript
+detectAgentFromClient(clientName: string): AgentType | null
+```
+
+| clientName            | AgentType     |
+| --------------------- | ------------- |
+| `opencode`            | `opencode`    |
+| `claude-code`         | `claude-code` |
+| `openclaw-acp-client` | `openclaw`    |
+| `codex-mcp-client`    | `codex`       |
+
+#### `detectProjectRoot(cwd?)`
+
+检测项目根目录。
+
+```typescript
+detectProjectRoot(cwd?: string): Promise<string>
+```
+
+优先使用 `git rev-parse --show-toplevel`，失败则向上遍历查找标记文件（`.git`、`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`），都未找到则回退到 `cwd`。
+
+### 能力矩阵 API
+
+编程式查询各 agent 对各 intent 的支持程度。
+
+```typescript
+import { CAPABILITY_MATRIX, checkDegradation, isIntentFullyUnsupported } from '@s_s/agent-kit';
+
+// 查询特定能力
+CAPABILITY_MATRIX.opencode.beforeToolCall.block.level; // 'partial'
+
+// 检查某 intent 在某 agent 上的降级情况
+const warnings = checkDegradation('opencode', 'beforeToolCall');
+
+// 检查是否完全不支持
+isIntentFullyUnsupported('openclaw', 'onPermission'); // true
+```
+
+## 类型
+
+```typescript
+type AgentType = 'opencode' | 'claude-code' | 'openclaw' | 'codex';
+
+type StorageScope = 'global' | 'project';
+
+interface ScopeOptions {
+  scope?: StorageScope; // 默认 'global'
+  projectRoot?: string; // scope 为 'project' 时必填
+}
+
+interface KitOptions {
+  dirs?: { global?: string; project?: string };
+  envOverride?: string;
+}
+
+interface Kit {
+  readonly name: string;
+  injectPrompt(agent: AgentType, prompt: string, options?: ScopeOptions): Promise<void>;
+  hasPromptInjected(agent: AgentType, options?: ScopeOptions): Promise<boolean>;
+  installHooks(agent: AgentType): Promise<HookInstallResult>;
+  uninstallHooks(agent: AgentType): Promise<{ success: boolean; removed: string[]; error?: string }>;
+  hasHooksInstalled(agent: AgentType): Promise<boolean>;
+  getDataDir(options?: ScopeOptions): string;
+}
+
+interface HookInstallResult {
+  success: boolean;
+  hookDir: string;
+  filesWritten: string[];
+  settingsUpdated: boolean;
+  notes: string[];
+  warnings: string[];
+  skipped: SkippedIntent[];
+  error?: string;
+}
+
+interface SkippedIntent {
+  intent: string;
+  agent: string;
+  reason: string;
+}
+
+type SupportLevel = 'supported' | 'partial' | 'unsupported';
+```
+
+## 支持的 Agent
+
+| Agent       | 检测方式                | Prompt 目标文件 | Hook 形式                  |
+| ----------- | ----------------------- | --------------- | -------------------------- |
+| OpenCode    | `opencode.json`         | `AGENTS.md`     | TypeScript 插件            |
+| Claude Code | `.claude/settings.json` | `CLAUDE.md`     | Shell 脚本 + settings.json |
+| OpenClaw    | `.openclaw/`            | manifest        | `HOOK.md` + `handler.ts`   |
+| Codex       | `.codex/`               | `AGENTS.md`     | Shell 脚本 + settings.json |
+
+> 各 agent 的完整 hook 能力横向对比，请参阅 [docs/hooks-comparison.md](docs/hooks-comparison.md)。
+
+## 开发
+
+```bash
+git clone git@github.com:nousyn/agent-kit.git
+cd agent-kit
+npm install
+npm run build
+npm test
+```
+
+### 脚本
+
+| 命令                   | 说明               |
+| ---------------------- | ------------------ |
+| `npm run build`        | 编译 TypeScript    |
+| `npm run dev`          | 监听模式编译       |
+| `npm test`             | 运行测试（Vitest） |
+| `npm run test:watch`   | 监听模式测试       |
+| `npm run prettier:fix` | 格式化所有文件     |
+| `npm run release`      | 交互式发布流程     |
+
+### 发布
+
+```bash
+npm run release
+```
+
+交互式脚本，依次执行：git 检查 → 分支检查 → 版本选择 → 格式化 → 测试 → 构建 → 发布 → 推送。
+
+## 许可证
+
+MIT

package/build/create-kit.d.ts

@@ -0,0 +1,16 @@
+import type { Kit, KitOptions } from './types.js';
+/**
+ * Create a kit instance bound to the given tool name.
+ *
+ * The returned object contains all kit functions (injectPrompt, installHooks,
+ * getDataDir, etc.) with the tool name captured in a closure — no global state.
+ *
+ * Supports destructuring:
+ * ```ts
+ * const { injectPrompt, installHooks } = createKit('my-mcp');
+ * ```
+ *
+ * @param name - Tool name. Used for prompt markers, hook directories, data directories, etc.
+ * @param options - Optional configuration (dirs, envOverride).
+ */
+export declare function createKit(name: string, options?: KitOptions): Kit;

package/build/create-kit.js

@@ -0,0 +1,54 @@
+import { injectPrompt, hasPromptInjected } from './prompt.js';
+import { installHooks, uninstallHooks, hasHooksInstalled } from './hooks.js';
+import { getDataDir } from './platform.js';
+/**
+ * Create a kit instance bound to the given tool name.
+ *
+ * The returned object contains all kit functions (injectPrompt, installHooks,
+ * getDataDir, etc.) with the tool name captured in a closure — no global state.
+ *
+ * Supports destructuring:
+ * ```ts
+ * const { injectPrompt, installHooks } = createKit('my-mcp');
+ * ```
+ *
+ * @param name - Tool name. Used for prompt markers, hook directories, data directories, etc.
+ * @param options - Optional configuration (dirs, envOverride).
+ */
+export function createKit(name, options) {
+    if (!name || !name.trim()) {
+        throw new Error('createKit: name is required and cannot be empty.');
+    }
+    const config = {
+        name,
+        dirs: options?.dirs,
+        envOverride: options?.envOverride,
+    };
+    return {
+        get name() {
+            return name;
+        },
+        injectPrompt(agent, prompt, scopeOptions) {
+            if (!prompt || !prompt.trim()) {
+                throw new Error('injectPrompt: prompt is required and cannot be empty.');
+            }
+            return injectPrompt(name, prompt, agent, scopeOptions);
+        },
+        hasPromptInjected(agent, scopeOptions) {
+            return hasPromptInjected(name, agent, scopeOptions);
+        },
+        installHooks(agent) {
+            return installHooks(name, agent);
+        },
+        uninstallHooks(agent) {
+            return uninstallHooks(name, agent);
+        },
+        hasHooksInstalled(agent) {
+            return hasHooksInstalled(name, agent);
+        },
+        getDataDir(scopeOptions) {
+            return getDataDir(config, scopeOptions);
+        },
+    };
+}
+//# sourceMappingURL=create-kit.js.map

package/build/create-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-kit.js","sourceRoot":"","sources":["../src/create-kit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAAoB;IACxD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAsB;QAC9B,IAAI;QACJ,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,WAAW,EAAE,OAAO,EAAE,WAAW;KACpC,CAAC;IAEF,OAAO;QACH,IAAI,IAAI;YACJ,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,YAAY,CAAC,KAAgB,EAAE,MAAc,EAAE,YAA2B;YACtE,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC7E,CAAC;YACD,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAC3D,CAAC;QAED,iBAAiB,CAAC,KAAgB,EAAE,YAA2B;YAC3D,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QACxD,CAAC;QAED,YAAY,CAAC,KAAgB;YACzB,OAAO,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QAED,cAAc,CAAC,KAAgB;YAC3B,OAAO,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;QAED,iBAAiB,CAAC,KAAgB;YAC9B,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;QAED,UAAU,CAAC,YAA2B;YAClC,OAAO,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC5C,CAAC;KACJ,CAAC;AACN,CAAC"}

package/build/detect.d.ts

@@ -0,0 +1,13 @@
+import type { AgentType } from './types.js';
+/**
+ * Detect which agent is present by checking characteristic files.
+ *
+ * Independent function — does not require register().
+ */
+export declare function detectAgent(cwd?: string): Promise<AgentType | null>;
+/**
+ * Map an MCP clientInfo.name to AgentType.
+ *
+ * Independent function — does not require register().
+ */
+export declare function detectAgentFromClient(clientName: string): AgentType | null;

package/build/detect.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { AGENT_REGISTRY, CLIENT_NAME_MAP } from './types.js';
+/**
+ * Detect which agent is present by checking characteristic files.
+ *
+ * Independent function — does not require register().
+ */
+export async function detectAgent(cwd) {
+    const startDir = cwd ?? process.cwd();
+    const home = os.homedir();
+    for (const [agentType, entry] of Object.entries(AGENT_REGISTRY)) {
+        const paths = entry.detectionPaths(startDir, home);
+        for (const p of paths) {
+            try {
+                await fs.access(p);
+                return agentType;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Map an MCP clientInfo.name to AgentType.
+ *
+ * Independent function — does not require register().
+ */
+export function detectAgentFromClient(clientName) {
+    return CLIENT_NAME_MAP[clientName] ?? null;
+}
+//# sourceMappingURL=detect.js.map

package/build/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAY;IAC1C,MAAM,QAAQ,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACtC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAE1B,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACnD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACpB,IAAI,CAAC;gBACD,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBACnB,OAAO,SAAsB,CAAC;YAClC,CAAC;YAAC,MAAM,CAAC;gBACL,SAAS;YACb,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkB;IACpD,OAAO,eAAe,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;AAC/C,CAAC"}

package/build/hook-capabilities.d.ts

@@ -0,0 +1,87 @@
+import type { AgentType } from './types.js';
+import type { IntentType } from './hook-types.js';
+/** How well an agent supports a particular intent sub-capability. */
+export type SupportLevel = 'supported' | 'partial' | 'unsupported';
+/**
+ * Capability entry describing support for a specific intent sub-capability on a specific agent.
+ */
+export interface CapabilityEntry {
+    level: SupportLevel;
+    /** Human-readable note explaining partial/unsupported status. */
+    note?: string;
+}
+/**
+ * Sub-capabilities per intent type.
+ */
+export interface IntentCapabilities {
+    inject: {
+        perTurn: CapabilityEntry;
+        sessionStart: CapabilityEntry;
+        compaction: CapabilityEntry;
+        sessionEnd: CapabilityEntry;
+    };
+    beforeToolCall: {
+        intercept: CapabilityEntry;
+        block: CapabilityEntry;
+        modifyArgs: CapabilityEntry;
+        matcher: CapabilityEntry;
+    };
+    afterToolCall: {
+        observe: CapabilityEntry;
+        matcher: CapabilityEntry;
+    };
+    onSession: {
+        start: CapabilityEntry;
+        end: CapabilityEntry;
+    };
+    onPermission: {
+        decide: CapabilityEntry;
+        matcher: CapabilityEntry;
+    };
+}
+/**
+ * The capability matrix: intent sub-capability × agent → support level.
+ *
+ * This is the single source of truth for what each agent can and cannot do
+ * with each intent type. Used by installHooks() to generate precise warnings.
+ */
+export declare const CAPABILITY_MATRIX: Record<AgentType, IntentCapabilities>;
+/**
+ * A degradation warning for a specific intent on a specific agent.
+ */
+export interface DegradationWarning {
+    agent: AgentType;
+    intent: IntentType;
+    capability: string;
+    level: SupportLevel;
+    message: string;
+}
+/**
+ * Check all sub-capabilities for a given intent type on a given agent.
+ * Returns warnings for any partial or unsupported sub-capabilities.
+ *
+ * Only checks sub-capabilities that the intent actually uses.
+ * For example, if an inject intent has no `compaction` field, the compaction
+ * capability is not checked.
+ */
+export declare function checkDegradation(agent: AgentType, intentType: IntentType, usedCapabilities?: string[]): DegradationWarning[];
+/**
+ * Check degradation for all registered intents on a specific agent.
+ * Analyzes which sub-capabilities each intent actually uses and only
+ * warns about those.
+ */
+export declare function checkAllDegradation(agent: AgentType, intentTypes: IntentType[]): DegradationWarning[];
+/**
+ * Check if a specific intent type is fully unsupported on an agent.
+ * Returns true only if ALL sub-capabilities are unsupported.
+ */
+export declare function isIntentFullyUnsupported(agent: AgentType, intentType: IntentType): boolean;
+/**
+ * Detect conflicts between intent-generated hooks and raw hooks.
+ *
+ * @param agent - The target agent.
+ * @param intentNativeHooks - Set of native hook names generated by intents.
+ * @param rawNativeHooks - Set of native hook names registered via hooks.raw().
+ * @returns Warning messages for each conflict.
+ */
+export declare function detectConflicts(agent: AgentType, intentNativeHooks: Set<string>, rawNativeHooks: Set<string>): string[];