odai-dsh-agent 0.2.22 → 0.2.23

package/preset/odai/skills/odai/references/verification.md

@@ -1,24 +1,24 @@
-# 验证与完成
-
-需要设计验收、判断完成、继续旧任务或在环境受限时收口时读取。
-
-## 建立验收
-
-- 先确认验收对应用户已对齐的真实结果，而非模型自行选择的根因、手段或交付物；再把明确结果、限制、具体对象、输入、位置和不可接受结果映射成可观察证据，证据证明为目标所必需的条件也纳入。
-- 只验证相关属性和主要回归风险。测试、构建、静态检查、diff、截图、日志和人工观察各自只证明实际覆盖的内容，不能互相冒充。
-- 项目已指定某项事实的权威筛选、查询、命令、样本或来源时，按该入口核验；相似字段、近似范围、替代命令或其他来源不能冒充同一对象与含义。
-- 验证强度由失败代价、影响范围、不确定性和已有证据覆盖共同决定；用户可见、工具可用或追求完整本身不构成升级理由。较轻证据已覆盖目标与主要风险时即采用；只有关键属性仍无法判定，或出现失败、冲突与新风险时，才升级到更接近真实场景的验证。
-- 验收先写要证明的属性，不把模型自行选择的命令、工具或流程升级成成功条件；只有用户或权威约定明确点名时，指定方法本身才属于契约。指定验证器因当前启动入口或依赖不可用而失败时，先核对现有环境能否用兼容入口运行同一验证器；仍不可用才采用真正覆盖同一属性的其他证据，并明确它没有证明原验证器已通过，不把自写近似检查称为等价。证据仍缺失就如实标明。
-
-## 判断完成
-
-- 用户已对齐的真实结果已经成立，明确要求均有结果，主要风险有相称证据，才算完成。局部未知只阻断依赖它的部分，其余继续交付。
-- 声明、配置和注释只证明“写了什么”；局部观测只证明观测范围；真实调用或使用链才证明端到端结果。
-- 两个或更多写入批次共同组成一个交付物时，组件完成不具有传递性。主流程只在唯一组合状态上核对实际改动范围、共享契约、依赖顺序和完整验收；各批次分别通过或分别受审不能替代组合证据。
-- 组合时出现的冲突解决或兼容性编辑属于新的获授权写入，须有自己的范围和验收。用户要求独立复核，或组合跨越重大安全、数据、并发、兼容、迁移或公共契约边界时，对组合状态进行独立复核。
-- 改动落地但关键场景未验证时，明确区分已实施、已验证与未验证，不用“应该、看起来、理论上”表达成功。
-- 实际结果或用户反馈与原判断不符时，将其视为新证据，修正结论、验收或后续做法，并让受影响的旧证据与完成判断失效；不把已说过的话当成必须维护的立场。
-- 版本、候选、阶段、提交、发布或迁移状态属于可验证结果。先核对机器可读事实源、当前产物与真实事件；前一状态未实际结束时更新同一状态，不创建后继值或把当前候选写成历史。确需迁移时，核对权威载体与用户文档指向同一当前值，历史记录按事实保留但不与现役状态争夺所有权。
-- 证据足够就停止；每次追加验证前须有尚未闭合、且结果会改变完成判断的具体属性。同一证据范围已通过且没有新失败、冲突、变更或风险时，不重复验证；不能因安心、工具可用、发现范围外问题或追求完整无限提高完成门，也不能因疲劳或流程完成降低验收。
-
-继续旧任务时，先从用户原话、当前产物、主状态、diff 和真实运行结果恢复目标与进度；跳过已有有效证据的完成项，不沿用无证据的旧完成标签。
+# 验证与完成
+
+需要设计验收、判断完成、继续旧任务或在环境受限时收口时读取。
+
+## 建立验收
+
+- 先确认验收对应用户已对齐的真实结果，而非模型自行选择的根因、手段或交付物；再把明确结果、限制、具体对象、输入、位置和不可接受结果映射成可观察证据，证据证明为目标所必需的条件也纳入。
+- 只验证相关属性和主要回归风险。测试、构建、静态检查、diff、截图、日志和人工观察各自只证明实际覆盖的内容，不能互相冒充。
+- 项目已指定某项事实的权威筛选、查询、命令、样本或来源时，按该入口核验；相似字段、近似范围、替代命令或其他来源不能冒充同一对象与含义。
+- 验证强度由失败代价、影响范围、不确定性和已有证据覆盖共同决定；用户可见、工具可用或追求完整本身不构成升级理由。较轻证据已覆盖目标与主要风险时即采用；只有关键属性仍无法判定，或出现失败、冲突与新风险时，才升级到更接近真实场景的验证。
+- 验收先写要证明的属性，不把模型自行选择的命令、工具或流程升级成成功条件；只有用户或权威约定明确点名时，指定方法本身才属于契约。指定验证器因当前启动入口或依赖不可用而失败时，先核对现有环境能否用兼容入口运行同一验证器；仍不可用才采用真正覆盖同一属性的其他证据，并明确它没有证明原验证器已通过，不把自写近似检查称为等价。证据仍缺失就如实标明。
+
+## 判断完成
+
+- 用户已对齐的真实结果已经成立，明确要求均有结果，主要风险有相称证据，才算完成。局部未知只阻断依赖它的部分，其余继续交付。
+- 声明、配置和注释只证明“写了什么”；局部观测只证明观测范围；真实调用或使用链才证明端到端结果。
+- 两个或更多写入批次共同组成一个交付物时，组件完成不具有传递性。主流程只在唯一组合状态上核对实际改动范围、共享契约、依赖顺序和完整验收；各批次分别通过或分别受审不能替代组合证据。
+- 组合时出现的冲突解决或兼容性编辑属于新的获授权写入，须有自己的范围和验收。用户要求独立复核，或组合跨越重大安全、数据、并发、兼容、迁移或公共契约边界时，对组合状态进行独立复核。
+- 改动落地但关键场景未验证时，明确区分已实施、已验证与未验证，不用“应该、看起来、理论上”表达成功。
+- 实际结果或用户反馈与原判断不符时，将其视为新证据，修正结论、验收或后续做法，并让受影响的旧证据与完成判断失效；不把已说过的话当成必须维护的立场。
+- 版本、候选、阶段、提交、发布或迁移状态属于可验证结果。先核对机器可读事实源、当前产物与真实事件；前一状态未实际结束时更新同一状态，不创建后继值或把当前候选写成历史。确需迁移时，核对权威载体与用户文档指向同一当前值，历史记录按事实保留但不与现役状态争夺所有权。
+- 证据足够就停止；每次追加验证前须有尚未闭合、且结果会改变完成判断的具体属性。同一证据范围已通过且没有新失败、冲突、变更或风险时，不重复验证；不能因安心、工具可用、发现范围外问题或追求完整无限提高完成门，也不能因疲劳或流程完成降低验收。
+
+继续旧任务时，先从用户原话、当前产物、主状态、diff 和真实运行结果恢复目标与进度；跳过已有有效证据的完成项，不沿用无证据的旧完成标签。

package/preset/odai/skills/odai/scripts/build-hooks.mjs

@@ -1,273 +1,273 @@
-#!/usr/bin/env node
-
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  writeFileSync,
-} from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const runtimeSource = path.join(skillRoot, "scripts", "odai-hook.mjs");
-const policySource = path.join(skillRoot, "assets", "hooks-policy.example.json");
-const supportedHosts = ["codex", "claude", "copilot", "gemini", "grok", "kimi"];
-
-const args = parseArgs(process.argv.slice(2));
-if (args.help) {
-  printHelp();
-  process.exit(0);
-}
-if (!args.out) fail("缺少 --out <directory>");
-if (!args.host) fail("缺少 --host <codex|claude|copilot|gemini|grok|kimi|all>");
-
-const hosts = args.host === "all" ? supportedHosts : [args.host];
-for (const host of hosts) {
-  if (!supportedHosts.includes(host)) fail(`不支持的 host：${host}`);
-}
-
-const outputRoot = path.resolve(args.out);
-mkdirSync(outputRoot, { recursive: true });
-for (const host of hosts) {
-  const target = path.join(outputRoot, host);
-  assertEmpty(target);
-  mkdirSync(target, { recursive: true });
-  buildAdapter(host, target);
-  console.log(`${host}: ${target}`);
-}
-
-function buildAdapter(host, target) {
-  const metadata = {
-    version: 1,
-    host,
-    policyPath: "<project>/.odai/hooks.json",
-    defaultBehavior: "No policy file means no-op.",
-    generatedFrom: "skills/odai/scripts/build-hooks.mjs",
-    capabilities: host === "grok" ? ["pre-tool"] : ["pre-tool", "stop-check"],
-  };
-
-  if (host === "copilot") {
-    copy(target, ".odai/hooks/odai-hook.mjs", runtimeSource);
-    copy(target, ".odai/hooks.example.json", policySource);
-    writeJson(target, ".github/hooks/odai.json", copilotHooks());
-    metadata.format = "project-overlay";
-    metadata.install = "Merge this directory into the repository root, review .github/hooks/odai.json, then create .odai/hooks.json from the example.";
-  } else {
-    copy(target, "scripts/odai-hook.mjs", runtimeSource);
-    copy(target, "examples/hooks.json", policySource);
-
-    if (host === "codex") {
-      writeJson(target, ".codex-plugin/plugin.json", codexPluginManifest());
-      writeJson(target, "hooks/hooks.json", groupedHooks("${PLUGIN_ROOT}", host, "PreToolUse", "Stop"));
-      metadata.format = "codex-plugin";
-      metadata.install = "Install or link this directory as a Codex plugin, review and trust its hooks, then create <project>/.odai/hooks.json.";
-    } else if (host === "claude") {
-      writeJson(target, ".claude-plugin/plugin.json", pluginManifest("Claude Code"));
-      writeJson(target, "hooks/hooks.json", groupedHooks("${CLAUDE_PLUGIN_ROOT}", host, "PreToolUse", "Stop"));
-      metadata.format = "claude-plugin";
-      metadata.install = "Install this directory as a Claude Code plugin, then create <project>/.odai/hooks.json.";
-    } else if (host === "grok") {
-      writeJson(target, ".claude-plugin/plugin.json", pluginManifest("Grok Build"));
-      writeJson(target, "hooks/hooks.json", groupedHooks("${GROK_PLUGIN_ROOT}", host, "PreToolUse", null));
-      metadata.format = "grok-plugin-using-claude-compatible-manifest";
-      metadata.install = "Install this directory with Grok Build's plugin manager, trust the hook, then create <project>/.odai/hooks.json.";
-      metadata.note = "Grok Build exposes PreToolUse as the blocking boundary; this adapter intentionally has no Stop verifier.";
-    } else if (host === "gemini") {
-      writeJson(target, "gemini-extension.json", {
-        name: "odai-hooks",
-        version: "0.1.0",
-        description: "Optional deterministic boundaries for odai.",
-      });
-      writeJson(target, "hooks/hooks.json", groupedHooks("${extensionPath}", host, "BeforeTool", "AfterAgent"));
-      metadata.format = "gemini-extension";
-      metadata.install = "Link or install this directory as a Gemini CLI extension, then create <project>/.odai/hooks.json.";
-    } else if (host === "kimi") {
-      writeJson(target, "kimi.plugin.json", kimiManifest());
-      metadata.format = "kimi-plugin";
-      metadata.install = "Run /plugins install <this-directory> in Kimi Code CLI, enable it, then create <project>/.odai/hooks.json.";
-    }
-  }
-
-  writeJson(target, "ADAPTER.json", metadata);
-}
-
-function groupedHooks(rootVariable, host, preEvent, stopEvent) {
-  const commandRoot = `${rootVariable}/scripts/odai-hook.mjs`;
-  const preHandler = {
-    type: "command",
-    command: `node "${commandRoot}" pre-tool --host ${host}`,
-    timeout: 5,
-  };
-  const stopHandler = {
-    type: "command",
-    command: `node "${commandRoot}" stop --host ${host}`,
-    timeout: 600,
-  };
-  if (host === "gemini") {
-    preHandler.name = "odai-write-boundary";
-    stopHandler.name = "odai-acceptance-check";
-  }
-  const hooks = {
-    [preEvent]: [
-      {
-        matcher: writeMatcher(host),
-        hooks: [preHandler],
-      },
-    ],
-  };
-  if (stopEvent) {
-    hooks[stopEvent] = [
-      {
-        matcher: "*",
-        hooks: [stopHandler],
-      },
-    ];
-  }
-  const result = { hooks };
-  if (host !== "gemini") {
-    result.description = "Optional odai boundaries. Inactive unless the project defines .odai/hooks.json.";
-  }
-  return result;
-}
-
-function copilotHooks() {
-  const command = "node .odai/hooks/odai-hook.mjs";
-  return {
-    version: 1,
-    hooks: {
-      preToolUse: [
-        {
-          type: "command",
-          matcher: writeMatcher("copilot"),
-          command: `${command} pre-tool --host copilot`,
-          cwd: ".",
-          timeoutSec: 5,
-        },
-      ],
-      agentStop: [
-        {
-          type: "command",
-          command: `${command} stop --host copilot`,
-          cwd: ".",
-          timeoutSec: 600,
-        },
-      ],
-    },
-  };
-}
-
-function kimiManifest() {
-  return {
-    name: "odai-hooks",
-    version: "0.1.0",
-    description: "Optional deterministic boundaries for odai.",
-    interface: {
-      displayName: "odai Hooks",
-      shortDescription: "Protect explicit read-only paths and run declared acceptance checks.",
-    },
-    hooks: [
-      {
-        event: "PreToolUse",
-        matcher: writeMatcher("kimi"),
-        command: "node ./scripts/odai-hook.mjs pre-tool --host kimi",
-        timeout: 5,
-      },
-      {
-        event: "Stop",
-        command: "node ./scripts/odai-hook.mjs stop --host kimi",
-        timeout: 600,
-      },
-    ],
-  };
-}
-
-function pluginManifest(hostName) {
-  return {
-    name: "odai-hooks",
-    version: "0.1.0",
-    description: `Optional deterministic odai boundaries for ${hostName}.`,
-  };
-}
-
-function codexPluginManifest() {
-  return {
-    id: "odai-hooks",
-    name: "odai-hooks",
-    version: "0.1.0",
-    description: "Optional deterministic boundaries for odai.",
-    author: {
-      name: "orzi",
-      url: "https://github.com/orziz",
-    },
-    homepage: "https://github.com/orziz/odai",
-    repository: "https://github.com/orziz/odai",
-    license: "MIT",
-    keywords: ["odai", "hooks", "guardrails"],
-    interface: {
-      displayName: "odai Hooks",
-      shortDescription: "Protect explicit read-only paths and run declared checks.",
-      longDescription: "Optional deterministic hook guardrails for projects that use odai.",
-      developerName: "orzi",
-      category: "Developer Tools",
-      capabilities: ["PreToolUse guard", "Stop acceptance check"],
-      websiteURL: "https://github.com/orziz/odai",
-      brandColor: "#1F6FEB",
-      defaultPrompt: "Use odai with the project's explicit hook boundaries.",
-    },
-  };
-}
-
-function writeMatcher(host) {
-  if (host === "copilot") return "create|edit|str_replace_editor|apply_patch";
-  if (host === "gemini") return "write_file|replace|apply_patch|edit|create";
-  return "Edit|Write|apply_patch|create|edit|write_file|str_replace_editor";
-}
-
-function writeJson(root, relativePath, value) {
-  const target = path.join(root, relativePath);
-  mkdirSync(path.dirname(target), { recursive: true });
-  writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-}
-
-function copy(root, relativePath, source) {
-  const target = path.join(root, relativePath);
-  mkdirSync(path.dirname(target), { recursive: true });
-  copyFileSync(source, target);
-}
-
-function assertEmpty(target) {
-  if (!existsSync(target)) return;
-  if (readdirSync(target).length > 0) fail(`输出目录非空，拒绝覆盖：${target}`);
-}
-
-function parseArgs(argv) {
-  const result = { host: "", out: "", help: false };
-  for (let index = 0; index < argv.length; index += 1) {
-    const value = argv[index];
-    if (value === "--help" || value === "-h") result.help = true;
-    else if (value === "--host") result.host = argv[++index] || "";
-    else if (value === "--out") result.out = argv[++index] || "";
-    else fail(`未知参数：${value}`);
-  }
-  return result;
-}
-
-function printHelp() {
-  console.log(`Build optional odai hook adapters.
-
-Usage:
-  node skills/odai/scripts/build-hooks.mjs --host <host|all> --out <directory>
-
-Hosts:
-  ${supportedHosts.join(", ")}
-
-The builder never installs hooks or edits a target project. Each generated
-adapter is inactive until that project defines .odai/hooks.json.`);
-}
-
-function fail(message) {
-  console.error(message);
-  process.exit(1);
-}
+#!/usr/bin/env node
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const runtimeSource = path.join(skillRoot, "scripts", "odai-hook.mjs");
+const policySource = path.join(skillRoot, "assets", "hooks-policy.example.json");
+const supportedHosts = ["codex", "claude", "copilot", "gemini", "grok", "kimi"];
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  printHelp();
+  process.exit(0);
+}
+if (!args.out) fail("缺少 --out <directory>");
+if (!args.host) fail("缺少 --host <codex|claude|copilot|gemini|grok|kimi|all>");
+
+const hosts = args.host === "all" ? supportedHosts : [args.host];
+for (const host of hosts) {
+  if (!supportedHosts.includes(host)) fail(`不支持的 host：${host}`);
+}
+
+const outputRoot = path.resolve(args.out);
+mkdirSync(outputRoot, { recursive: true });
+for (const host of hosts) {
+  const target = path.join(outputRoot, host);
+  assertEmpty(target);
+  mkdirSync(target, { recursive: true });
+  buildAdapter(host, target);
+  console.log(`${host}: ${target}`);
+}
+
+function buildAdapter(host, target) {
+  const metadata = {
+    version: 1,
+    host,
+    policyPath: "<project>/.odai/hooks.json",
+    defaultBehavior: "No policy file means no-op.",
+    generatedFrom: "skills/odai/scripts/build-hooks.mjs",
+    capabilities: host === "grok" ? ["pre-tool"] : ["pre-tool", "stop-check"],
+  };
+
+  if (host === "copilot") {
+    copy(target, ".odai/hooks/odai-hook.mjs", runtimeSource);
+    copy(target, ".odai/hooks.example.json", policySource);
+    writeJson(target, ".github/hooks/odai.json", copilotHooks());
+    metadata.format = "project-overlay";
+    metadata.install = "Merge this directory into the repository root, review .github/hooks/odai.json, then create .odai/hooks.json from the example.";
+  } else {
+    copy(target, "scripts/odai-hook.mjs", runtimeSource);
+    copy(target, "examples/hooks.json", policySource);
+
+    if (host === "codex") {
+      writeJson(target, ".codex-plugin/plugin.json", codexPluginManifest());
+      writeJson(target, "hooks/hooks.json", groupedHooks("${PLUGIN_ROOT}", host, "PreToolUse", "Stop"));
+      metadata.format = "codex-plugin";
+      metadata.install = "Install or link this directory as a Codex plugin, review and trust its hooks, then create <project>/.odai/hooks.json.";
+    } else if (host === "claude") {
+      writeJson(target, ".claude-plugin/plugin.json", pluginManifest("Claude Code"));
+      writeJson(target, "hooks/hooks.json", groupedHooks("${CLAUDE_PLUGIN_ROOT}", host, "PreToolUse", "Stop"));
+      metadata.format = "claude-plugin";
+      metadata.install = "Install this directory as a Claude Code plugin, then create <project>/.odai/hooks.json.";
+    } else if (host === "grok") {
+      writeJson(target, ".claude-plugin/plugin.json", pluginManifest("Grok Build"));
+      writeJson(target, "hooks/hooks.json", groupedHooks("${GROK_PLUGIN_ROOT}", host, "PreToolUse", null));
+      metadata.format = "grok-plugin-using-claude-compatible-manifest";
+      metadata.install = "Install this directory with Grok Build's plugin manager, trust the hook, then create <project>/.odai/hooks.json.";
+      metadata.note = "Grok Build exposes PreToolUse as the blocking boundary; this adapter intentionally has no Stop verifier.";
+    } else if (host === "gemini") {
+      writeJson(target, "gemini-extension.json", {
+        name: "odai-hooks",
+        version: "0.1.0",
+        description: "Optional deterministic boundaries for odai.",
+      });
+      writeJson(target, "hooks/hooks.json", groupedHooks("${extensionPath}", host, "BeforeTool", "AfterAgent"));
+      metadata.format = "gemini-extension";
+      metadata.install = "Link or install this directory as a Gemini CLI extension, then create <project>/.odai/hooks.json.";
+    } else if (host === "kimi") {
+      writeJson(target, "kimi.plugin.json", kimiManifest());
+      metadata.format = "kimi-plugin";
+      metadata.install = "Run /plugins install <this-directory> in Kimi Code CLI, enable it, then create <project>/.odai/hooks.json.";
+    }
+  }
+
+  writeJson(target, "ADAPTER.json", metadata);
+}
+
+function groupedHooks(rootVariable, host, preEvent, stopEvent) {
+  const commandRoot = `${rootVariable}/scripts/odai-hook.mjs`;
+  const preHandler = {
+    type: "command",
+    command: `node "${commandRoot}" pre-tool --host ${host}`,
+    timeout: 5,
+  };
+  const stopHandler = {
+    type: "command",
+    command: `node "${commandRoot}" stop --host ${host}`,
+    timeout: 600,
+  };
+  if (host === "gemini") {
+    preHandler.name = "odai-write-boundary";
+    stopHandler.name = "odai-acceptance-check";
+  }
+  const hooks = {
+    [preEvent]: [
+      {
+        matcher: writeMatcher(host),
+        hooks: [preHandler],
+      },
+    ],
+  };
+  if (stopEvent) {
+    hooks[stopEvent] = [
+      {
+        matcher: "*",
+        hooks: [stopHandler],
+      },
+    ];
+  }
+  const result = { hooks };
+  if (host !== "gemini") {
+    result.description = "Optional odai boundaries. Inactive unless the project defines .odai/hooks.json.";
+  }
+  return result;
+}
+
+function copilotHooks() {
+  const command = "node .odai/hooks/odai-hook.mjs";
+  return {
+    version: 1,
+    hooks: {
+      preToolUse: [
+        {
+          type: "command",
+          matcher: writeMatcher("copilot"),
+          command: `${command} pre-tool --host copilot`,
+          cwd: ".",
+          timeoutSec: 5,
+        },
+      ],
+      agentStop: [
+        {
+          type: "command",
+          command: `${command} stop --host copilot`,
+          cwd: ".",
+          timeoutSec: 600,
+        },
+      ],
+    },
+  };
+}
+
+function kimiManifest() {
+  return {
+    name: "odai-hooks",
+    version: "0.1.0",
+    description: "Optional deterministic boundaries for odai.",
+    interface: {
+      displayName: "odai Hooks",
+      shortDescription: "Protect explicit read-only paths and run declared acceptance checks.",
+    },
+    hooks: [
+      {
+        event: "PreToolUse",
+        matcher: writeMatcher("kimi"),
+        command: "node ./scripts/odai-hook.mjs pre-tool --host kimi",
+        timeout: 5,
+      },
+      {
+        event: "Stop",
+        command: "node ./scripts/odai-hook.mjs stop --host kimi",
+        timeout: 600,
+      },
+    ],
+  };
+}
+
+function pluginManifest(hostName) {
+  return {
+    name: "odai-hooks",
+    version: "0.1.0",
+    description: `Optional deterministic odai boundaries for ${hostName}.`,
+  };
+}
+
+function codexPluginManifest() {
+  return {
+    id: "odai-hooks",
+    name: "odai-hooks",
+    version: "0.1.0",
+    description: "Optional deterministic boundaries for odai.",
+    author: {
+      name: "orzi",
+      url: "https://github.com/orziz",
+    },
+    homepage: "https://github.com/orziz/odai",
+    repository: "https://github.com/orziz/odai",
+    license: "MIT",
+    keywords: ["odai", "hooks", "guardrails"],
+    interface: {
+      displayName: "odai Hooks",
+      shortDescription: "Protect explicit read-only paths and run declared checks.",
+      longDescription: "Optional deterministic hook guardrails for projects that use odai.",
+      developerName: "orzi",
+      category: "Developer Tools",
+      capabilities: ["PreToolUse guard", "Stop acceptance check"],
+      websiteURL: "https://github.com/orziz/odai",
+      brandColor: "#1F6FEB",
+      defaultPrompt: "Use odai with the project's explicit hook boundaries.",
+    },
+  };
+}
+
+function writeMatcher(host) {
+  if (host === "copilot") return "create|edit|str_replace_editor|apply_patch";
+  if (host === "gemini") return "write_file|replace|apply_patch|edit|create";
+  return "Edit|Write|apply_patch|create|edit|write_file|str_replace_editor";
+}
+
+function writeJson(root, relativePath, value) {
+  const target = path.join(root, relativePath);
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function copy(root, relativePath, source) {
+  const target = path.join(root, relativePath);
+  mkdirSync(path.dirname(target), { recursive: true });
+  copyFileSync(source, target);
+}
+
+function assertEmpty(target) {
+  if (!existsSync(target)) return;
+  if (readdirSync(target).length > 0) fail(`输出目录非空，拒绝覆盖：${target}`);
+}
+
+function parseArgs(argv) {
+  const result = { host: "", out: "", help: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--help" || value === "-h") result.help = true;
+    else if (value === "--host") result.host = argv[++index] || "";
+    else if (value === "--out") result.out = argv[++index] || "";
+    else fail(`未知参数：${value}`);
+  }
+  return result;
+}
+
+function printHelp() {
+  console.log(`Build optional odai hook adapters.
+
+Usage:
+  node skills/odai/scripts/build-hooks.mjs --host <host|all> --out <directory>
+
+Hosts:
+  ${supportedHosts.join(", ")}
+
+The builder never installs hooks or edits a target project. Each generated
+adapter is inactive until that project defines .odai/hooks.json.`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}