kdna-skills

> [aikdna.com](https://aikdna.com) — 官方网站 > > [](https://www.npmjs.com/package/@aikdna/kdna-cli) # KDNA 技能 **一个加载器。多个领域。** 本仓库提供适配器技能，允许 AI 代理加载 KDNA 判断资产。它不将 KDNA 转换为技能 — 而是赋予代理发现和加载 `.kdna` 文件的能力。 `kdna-loader` 技能是 KDNA 工具链的官方代理适配器。它教导 AI 代理何时以及如何加载 `.kdna` 判断资产 — 以及何时跳过。支持的放置位置在 [`docs/agent-support-matrix.json`](docs/agent-support-matrix.json) 中跟踪：**OpenCode, Codex, Claude Code, Cursor**，通过手动兼容技能放置提供 **GitHub Copilot 兼容代理**。 **KDNA 塑造判断，而不是工具权限。** KDNA 不会覆盖系统或安全策略。运行时跟踪词汇记录显式状态值（version_incompatible, failed_to_parse, failed_to_decrypt, signature_invalid, blocked_by_runtime_policy），以便加载器无法在产生垃圾时悄悄成功。参见 KDNA Core 跟踪词汇。 需要 `@aikdna/kdna-cli` CLI： ```bash npm i -g @aikdna/kdna-cli ``` 当前已验证的注册表基准线是 `@aikdna/kdna-cli@0.35.0`，具有确切的运行时依赖项 `@aikdna/kdna-core@0.20.0`。该 CLI 和本仓库适配器捆绑的加载器都使用官方的 `inspect` → `plan-load` → `load` 边界。未版本化的安装命令跟踪 npm 的当前 `latest` CLI 版本。 ## 工作原理 | 什么 | 在哪里 | |---|---| | **kdna-loader** （单个技能） | 手动安装到您的代理中。教导代理 KDNA 发现和应用的协议。 | | **KDNA 资产** （数据） | 本地 `.kdna` KDNA 资产容器。通过本地路径或 MCP `kdna.available-local` 发现它们；按需加载每个任务。 | | **kdna CLI** （工具） | `kdna inspect`，`kdna validate`，`kdna plan-load`，`kdna load`。当前 KDNA 资产容器的运行时控制平面。 | 对于大多数代理请求，加载器使用保守的单主键路径。需要显式多资产组合的应用程序应使用 CLI 消费运行时并保留其跟踪和审查控制；加载器不会静默加载每个可用的资产。 ## 支持的代理 `kdna setup` 在目标代理自动检测时，将 `kdna-loader` 安装到以下路径： | 代理 | 技能路径 | 指南 | |-------|-----------|-------| | **Codex** | `~/.codex/skills/kdna-loader/` | [设置指南 →](integrations/codex/) | | **Claude Code** | `~/.claude/skills/kdna-loader/` | [设置指南 →](integrations/claude-code/) | | **OpenCode** | `~/.agents/skills/kdna-loader/` | [设置指南 →](integrations/opencode/) | | **Cursor** | `~/.cursor/skills/kdna-loader/` | [设置指南 →](integrations/cursor/) | | **GitHub Copilot** | `~/.agents/skills/kdna-loader/` | [设置指南 →](integrations/copilot/) | 所有代理都可以共享相同的本地 KDNA 包存储：`~/.kdna/packages/`。也支持显式文件路径和 MCP `kdna.available-local` 根目录。 ## MCP 服务器 本仓库还包含一个最小的 MCP 适配器，位于 [`mcp-server/`](./mcp-server)。当代理运行时支持 MCP 并且应该通过稳定工具访问 KDNA 而不是直接读取 KDNA 内部时，请使用它。 暴露的工具： - `kdna.inspect` - `kdna.verify` - `kdna.plan-load` - `kdna.load` - `kdna.available-local` - `kdna.match` ## 快速安装 ```bash npm i -g @aikdna/kdna-cli ``` ## 尝试演示资产 ```bash kdna demo judgment ./judgment kdna pack ./judgment ./judgment.kdna kdna validate ./judgment.kdna --runtime kdna plan-load ./judgment.kdna --json kdna load ./judgment.kdna --profile=compact --as=json ``` ## 安装后 ### 加载 `.kdna` 资产 代理根据任务自动决定是否应用 KDNA。当领域匹配时，它会静默加载 — 应用公理，使用首选术语，尊重边界，并运行自检。用户看到更好的判断，而不是 KDNA 内部。 ### 使用另一个 `.kdna` 文件 ```bash kdna validate ./your-domain.kdna kdna plan-load ./your-domain.kdna kdna load ./your-domain.kdna --profile=compact --as=json ``` ### 创建您自己的 KDNA 人类、代理、工具和混合工作流可以在使用官方 KDNA 工具链或兼容的 SDK 时创建 `.kdna` 资产。公共测试版创作路径是： ```bash npm i -g @aikdna/kdna-studio-cli @aikdna/kdna-cli kdna-studio create my_domain --name @yourscope/my_domain kdna-studio card add my_domain axiom --field one_sentence="..." kdna-studio export my_domain --out ./my_domain.kdna kdna validate ./my_domain.kdna kdna plan-load ./my_domain.kdna kdna load ./my_domain.kdna --profile=compact --as=json ``` 发布者可以在需要时通过创作工具添加审查证据和出处记录。它们不是 KDNA 格式有效性的要求。 ## kdna-loader 工作原理（8 部分协议） 1. **决定** 是否应用 KDNA（跳过格式化、查找、代码执行） 2. **发现** 本地领域通过 CLI 或 MCP 本地库存 3. **评估** 每个领域的适合度（检查 `applies_when` / `does_not_apply_when`） 4. **选择** 0 或 1 个领域（从不静默混合多个） 5. **计划** 通过 `kdna plan-load <file.kdna>` 6. **加载** 仅当 Core/CLI 报告 `can_load_now=true` 时，然后从 `kdna load <file.kdna> --profile=compact --as=json` 消耗运行时胶囊 7. **应用** 静默 — 从公理推理，从不引用 KDNA 给用户 8. **尊重** 边界 — 用户意图 > 证据 > 安全 > 技能 参见 [docs/KDNA_LOADER_CONTRACT.md](docs/KDNA_LOADER_CONTRACT.md)。 ## 手动安装 ```bash # Codex mkdir -p ~/.codex/skills/kdna-loader cp kdna-loader/SKILL.md ~/.codex/skills/kdna-loader/SKILL.md # Claude Code mkdir -p ~/.claude/skills/kdna-loader cp kdna-loader/SKILL.md ~/.claude/skills/kdna-loader/SKILL.md # OpenCode mkdir -p ~/.agents/skills/kdna-loader cp kdna-loader/SKILL.md ~/.agents/skills/kdna-loader/SKILL.md # Cursor mkdir -p ~/.cursor/skills/kdna-loader cp kdna-loader/SKILL.md ~/.cursor/skills/kdna-loader/SKILL.md # GitHub Copilot 兼容代理 mkdir -p ~/.agents/skills/kdna-loader cp kdna-loader/SKILL.md ~/.agents/skills/kdna-loader/SKILL.md ``` ## 许可证 Apache-2.0 [中文](./README.zh.md)