@winspan/claude-forge 8.51.0 → 8.53.2

package/docs/design/skill-ai-upgrade-spec-20260518-1930.md

@@ -0,0 +1,297 @@
+# AI 辅助 official skill 升级 Spec
+
+## 目标
+
+为 `claude-forge` 新增 `cf skills upgrade` 命令，通过 AI 评估将外部开源 skill 仓库（addyosmani/agent-skills、obra/superpowers）的优质内容合并进 `src/skills/official/*.md`（永久内置 skill），而不是让它们在用户目录独立存在。整个流程默认 dry-run，用户审核 markdown 报告后执行 `--apply`。
+
+## 用户决策（已通过对话确认）
+
+| 决策点 | 确认值 |
+|--------|--------|
+| 候选源目录 | `~/.claude-forge/skill-candidates/<source-name>/` |
+| AI 评估使用 | `config.ai.model` + `config.ai.base_url` |
+| 覆盖目标 | `src/skills/official/*.md`（编译进 dist 的永久内置） |
+| 报告路径 | `~/.claude-forge/skill-upgrade-report.md` |
+| 默认行为 | dry-run（只生成报告） |
+| `--apply` 行为 | 读取报告中 action，备份后覆写源码 |
+| 备份路径 | `~/.claude-forge/backups/skills/<timestamp>/`（已有 FORGE_PATHS.backups('skills')） |
+
+## 数据流图
+
+```
+[cf skills upgrade]
+    │
+    ▼
+[1] pullCandidates()
+    ├─ git clone/pull ~/.claude-forge/skill-candidates/agent-skills/
+    └─ git clone/pull ~/.claude-forge/skill-candidates/superpowers/
+    │
+    ▼
+[2] scanCandidateFiles()
+    └─ 遍历 .md 文件，解析 frontmatter → CandidateSkill[]
+    │
+    ▼
+[3] matchToOfficial()       (per candidate)
+    └─ tag/keyword 模糊匹配 → MatchResult (official id | null)
+    │
+    ▼
+[4] evaluateWithAI()        (有 official 匹配时才调用)
+    └─ ClaudeProvider.complete() → UpgradeDecision (JSON)
+    │
+    ▼
+[5] generateReport()
+    └─ ~/.claude-forge/skill-upgrade-report.md
+    │
+    ▼ (用户审核)
+    │
+[cf skills upgrade --apply]
+    │
+    ▼
+[6] applyDecisions()
+    ├─ git status 工作树检查
+    ├─ backup src/skills/official/ → backups/skills/<ts>/
+    └─ 覆写 src/skills/official/<id>.md
+```
+
+## 模块设计
+
+### Module 1: `src/skills/upgrade-engine.ts`
+
+**职责**：编排全流程，不含 AI prompt 字符串逻辑。
+
+```ts
+export interface CandidateSkill {
+  id: string;
+  source: string;       // 'agent-skills' | 'superpowers'
+  filePath: string;
+  name: string;
+  description: string;
+  keywords: string[];
+  content: string;
+}
+
+export interface MatchResult {
+  officialId: string;
+  score: number;        // 0-100，关键词重叠率
+}
+
+export type UpgradeAction = 'upgrade' | 'merge' | 'skip';
+export interface UpgradeDecision {
+  action: UpgradeAction;
+  confidence: number;       // 0-100
+  reasoning: string;
+  merged_content: string | null;
+}
+
+export interface ReportEntry {
+  officialId: string;
+  candidateId: string;
+  candidateSource: string;
+  action: UpgradeAction | 'error' | 'needs_review';
+  confidence: number;
+  reasoning: string;
+  candidateFilePath: string;
+  merged_content: string | null;
+}
+
+export async function pullCandidates(
+  sources: Array<{ name: string; url: string }>,
+  candidatesDir: string,
+): Promise<CandidateSkill[]>
+
+export function matchToOfficial(
+  candidate: CandidateSkill,
+  officialSkills: OfficialSkill[],
+): MatchResult | null   // null = 无匹配（score < 30）
+
+export async function evaluateWithAI(
+  candidate: CandidateSkill,
+  official: OfficialSkill,
+  aiProvider: ClaudeProvider,
+): Promise<UpgradeDecision>
+
+export async function generateReport(
+  entries: ReportEntry[],
+  outputPath: string,
+  stats: { total: number; matched: number; unmatched: number },
+): Promise<void>
+
+export async function applyDecisions(
+  reportPath: string,
+  officialDir: string,
+  backupBaseDir: string,
+): Promise<{ applied: number; skipped: number; backupPath: string }>
+```
+
+**关键逻辑**：
+- `pullCandidates`：单源失败 try/catch 跳过
+- `matchToOfficial`：keywords + name token overlap，阈值 30 分（满分 100）
+- `evaluateWithAI`：`maxTokens: 1200, timeoutMs: 45000`；JSON 解析失败返回 skip + needs_review
+- `applyDecisions`：apply 前 `git status --porcelain` 检查工作树是否干净，脏的话 abort
+
+### Module 2: `src/skills/upgrade-prompt.ts`
+
+```ts
+export function buildEvaluationPrompt(
+  candidate: CandidateSkill,
+  official: OfficialSkill,
+): { system: string; user: string }
+```
+
+**System prompt 要点**：
+```
+你是 Claude Code skill 内容评估专家。
+评估维度：主题重叠度 / 内容质量 / 互补性
+返回严格 JSON（不含其他文本）：
+{"action":"upgrade|merge|skip","confidence":0-100,"reasoning":"...","merged_content":null或合并后完整md}
+
+决策标准：
+- skip：主题不重叠，或 official 已完整覆盖
+- upgrade：候选覆盖 official 全部要点且质量明显更高（+30% depth/breadth）
+- merge：主题相同但各有独特章节，合并后价值更高
+```
+
+**User prompt**：双 skill 内容各截 2000 字 + JSON 要求。
+
+### Module 3: 候选源拉取
+
+```ts
+const DEFAULT_SOURCES = [
+  { name: 'agent-skills', url: 'https://github.com/addyosmani/agent-skills.git' },
+  { name: 'superpowers',  url: 'https://github.com/obra/superpowers.git' },
+];
+```
+
+**扫描兼容**：
+- agent-skills 格式：`<name>/SKILL.md`（目录格式）
+- superpowers 格式：顶层 `*.md`（平铺）
+- 复用 `SkillRegistry.scan()` 的格式识别逻辑
+
+### Module 4: CLI 子命令
+
+```ts
+skills
+  .command('upgrade')
+  .description('AI-assisted upgrade of official skills (dry-run by default)')
+  .option('--apply', 'Apply decisions from the last report')
+  .option('--rollback <timestamp>', 'Rollback to a backup')
+  .option('--report <path>', 'Custom report path')
+  .action(async (options) => { await upgradeSkills(options); });
+```
+
+## AI 输出契约
+
+```ts
+type UpgradeDecision = {
+  action: 'upgrade' | 'merge' | 'skip';
+  confidence: number;        // 0-100 整数
+  reasoning: string;         // 简短中文 < 200 字
+  merged_content: string | null;
+  // merged_content 规则：
+  //   merge   → 完整合并后 .md（含 frontmatter）
+  //   upgrade → null（直接用候选原文）
+  //   skip    → null
+};
+```
+
+容错：`JSON.parse` 失败 → `action: skip, needs_review: true`，不阻断。
+
+## 报告格式
+
+```markdown
+# Skill Upgrade Report
+
+Generated: 2026-05-18 19:30 | Model: claude-opus-4-7
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Candidates scanned | 37 (23 agent-skills + 14 superpowers) |
+| Matched to official | 12 |
+| Action: upgrade | 5 |
+| Action: merge | 4 |
+| Action: skip | 3 |
+| Unmatched | 25 |
+
+## Per-Skill Decisions
+
+### official-db-schema-design
+- **Action**: upgrade
+- **Confidence**: 85%
+- **Candidate**: `agent-skills/database-design`
+- **Reasoning**: 候选增加"分库分表策略"和"迁移工具对比"...
+
+<!-- upgrade-entry: official-db-schema-design | <candidatePath> | upgrade -->
+```
+
+**机器可读标记**：HTML 注释 `<!-- upgrade-entry: <id> | <path> | <action> -->`；merge 用 `<!-- merged-content-begin -->...<!-- merged-content-end -->` 包裹合并内容。`--apply` 解析这些注释。
+
+## 备份机制
+
+```
+~/.claude-forge/backups/skills/
+  └── 20260518-1930/
+        ├── official-tdd.md
+        └── ... (所有 official .md 快照)
+```
+
+- 只在 `--apply` 触发备份
+- `--rollback <ts>` 还原
+- 复用 `FORGE_PATHS.backups('skills')`
+- 同 ts 已存在则追加 `-2`、`-3`
+
+## 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| git clone/pull 失败 | warn + 跳过该 source |
+| AI JSON 解析失败 | needs_review，继续 |
+| AI API 超时/5xx | retry 2 次失败 → error 标记 |
+| `--apply` 工作树脏 | abort，提示先 commit |
+| 候选无 frontmatter | 用文件名作 id，keywords=[] |
+| 同 ts 备份冲突 | 后缀 -2 -3 |
+
+## 改造范围
+
+| 文件 | 操作 | 行数估计 |
+|------|------|---------|
+| `src/skills/upgrade-engine.ts` | 新增 | ~200 |
+| `src/skills/upgrade-prompt.ts` | 新增 | ~60 |
+| `src/cli/commands/skills.ts` | 加 upgrade 子命令 + 函数 | +80 |
+| `src/core/constants.ts` | 加 `skillCandidates` 路径（可选）| +2 |
+
+**不改动**：dist/、daemon、web 路由、hook、SkillRegistry、official-skills.ts。
+
+## 测试策略
+
+| 测试文件 | 内容 |
+|---------|------|
+| `tests/unit/skills/upgrade-engine.test.ts` | mock ClaudeProvider.complete → 三条路径；applyDecisions dry-run 不写；备份目录创建 |
+| `tests/unit/skills/upgrade-prompt.test.ts` | system/user prompt 含必要字段；JSON 格式要求 |
+| `tests/unit/skills/upgrade-engine-parse.test.ts` | AI 非 JSON → needs_review；合法 JSON 正确解析 |
+
+集成测试可选：本地 mock .md 跑 dry-run 全流程。
+
+## 风险与回滚
+
+| 风险 | 缓解 |
+|------|------|
+| AI 误判覆盖好 skill | 默认 dry-run；apply 强制 backup；--rollback 还原 |
+| 覆写后 build 错 | apply 后提示 `npm run build` 验证 |
+| API 成本 | 仅 score>=30 调 AI；截 2000 字；预估 ~18K tokens / 12 matched |
+| 候选仓库结构变化 | 单源失败不阻断 |
+
+## 实施顺序
+
+1. **upgrade-prompt.ts**（纯函数，无依赖）
+2. **upgrade-engine.ts** — matchToOfficial → evaluateWithAI → pullCandidates → generateReport → applyDecisions
+3. **cli/commands/skills.ts** — 注册 upgrade 子命令
+4. （可选）`FORGE_PATHS.skillCandidates`
+5. 测试：upgrade-prompt → upgrade-engine（mock）→ CLI e2e
+
+## 命名遵循
+
+- 文件：kebab-case
+- 函数：动词开头 camelCase（`pullCandidates` / `matchToOfficial`）
+- 类型：PascalCase（`CandidateSkill` / `UpgradeDecision`）

package/docs/implementation/daemon-skill-sync-changelog-20260518-2000.md

@@ -0,0 +1,22 @@
+# daemon skill 自动同步 Changelog
+
+**Date**: 2026-05-18 20:00
+**Status**: 完成
+
+## 背景
+类比 v8.51.1 hook-sync：npm 升级 dist/skills/official/ 但不会自动同步
+~/.claude/skills/ 本地副本，SkillRegistry 优先级 user > official 加载
+旧副本，导致 skill 残缺/功能错乱。
+
+## 改动
+- 新建 src/daemon/skill-sync.ts: syncSkills() sha256 比对自动同步
+- daemon/index.ts 启动时调用（紧挨 syncHooks）
+- 失败 logger.warn 不阻断
+
+## 测试
+- 5 case 单测全过
+- 现有测试不退化
+- tsc 0 errors
+
+## 已知问题
+- linkEventToTask pre-existing（sqlite-refactor-harness.test.ts）

package/docs/implementation/skill-ai-upgrade-changelog-20260518-1930.md

@@ -0,0 +1,49 @@
+# AI 辅助 skill 升级 Changelog
+
+**Date**: 2026-05-18 19:30
+**Spec**: docs/design/skill-ai-upgrade-spec-20260518-1930.md
+**Status**: 完成
+
+## 完成清单
+
+- [x] `src/skills/upgrade-prompt.ts` — buildEvaluationPrompt 纯函数
+- [x] `src/skills/upgrade-engine.ts` — 5 个 pipeline 函数 + 全部类型定义
+- [x] `src/cli/commands/skills.ts` — upgrade 子命令 + upgradeSkills() 函数
+- [x] `src/core/constants.ts` — 新增 skillCandidates / skillUpgradeReport 路径
+- [x] 单测 3 文件（44 个新测试用例全过）
+
+## 关键代码定位
+
+- `src/skills/upgrade-prompt.ts:14` — `buildEvaluationPrompt()` system/user prompt 构造
+- `src/skills/upgrade-engine.ts:105` — `pullCandidates()` git clone/pull + .md 扫描
+- `src/skills/upgrade-engine.ts:141` — `matchToOfficial()` Jaccard 关键词重叠评分（阈值 30/100）
+- `src/skills/upgrade-engine.ts:183` — `evaluateWithAI()` AI 调用 + JSON 容错解析
+- `src/skills/upgrade-engine.ts:237` — `generateReport()` markdown + HTML 注释机器标记
+- `src/skills/upgrade-engine.ts:284` — `applyDecisions()` git status 检查 + 备份 + 写文件
+- `src/cli/commands/skills.ts:126` — `upgradeSkills()` 全流程协调（dry-run / apply / rollback）
+
+## 测试结果
+
+- 新增测试: 44 passed（upgrade-prompt: 11, upgrade-engine: 22, upgrade-engine-parse: 11）
+- tsc: 0 errors
+- npm test: 614 passed / 615 total（1 pre-existing failure: linkEventToTask）
+- build: 成功
+
+## 实施决策
+
+1. **ClaudeProvider.complete() 接口**: 使用 `complete(prompt, options)` 形式，其中 `options.system` 传递 system prompt。经查 `src/core/ai/provider.ts` 确认签名。
+
+2. **require('node:fs') 用于同步读文件**: `parseCandidateFile` 使用同步 `readFileSync`，通过 `require('node:fs')` 调用（ESM 模块中已有 `import fs` 但需要同步读取）。
+
+3. **matchToOfficial 评分策略**: 采用 keyword overlap（权重 60%）+ name/description token overlap（权重 40%）的加权 Jaccard 相似度，而非简单字符串匹配。
+
+4. **evaluateWithAI markdown fence 剥离**: AI 模型有时会将 JSON 包裹在 `\`\`\`json` 代码块中，在 JSON.parse 前统一剥离。
+
+5. **applyDecisions git status**: 使用 `git status --porcelain <officialDir>` 检查工作树。若目标目录不在 git 仓库中（如测试用 tmp 目录），warn 并继续（不 abort）。
+
+6. **备份冲突后缀**: 对 `<YYYYMMDD-HHMM>` 时间戳已存在时，自动追加 `-2`、`-3` 等后缀，通过循环 `fs.access` 找到可用路径。
+
+## 已知问题
+
+- `linkEventToTask` 测试失败：pre-existing，与本次改动无关
+- 手测 deferred：网络环境未验证 git clone 实际可达性；dry-run 流程逻辑已通过 mock 测试覆盖

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winspan/claude-forge",
-  "version": "8.51.0",
+  "version": "8.53.2",
   "description": "SDLC intelligent orchestration engine for Claude Code",
   "main": "dist/cli/index.js",
   "type": "module",

package/src/cli/commands/skills.ts

@@ -2,11 +2,24 @@ import fs from 'fs';
 import path from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
+import { promises as fsPromises } from 'node:fs';
 import type { Command } from 'commander';
 import { loadOfficialSkills } from '../../skills/official-skills.js';
 import { SkillRegistry } from '../../skills/registry.js';
 import { skillInvoke } from '../../skills/tools/skill-invoke.js';
 import { skillList } from '../../skills/tools/skill-list.js';
+import {
+  pullCandidates,
+  matchToOfficial,
+  evaluateWithAI,
+  generateReport,
+  applyDecisions,
+  DEFAULT_SOURCES,
+} from '../../skills/upgrade-engine.js';
+import type { ReportEntry } from '../../skills/upgrade-engine.js';
+import { ConfigManager } from '../../core/config.js';
+import { ClaudeProvider } from '../../core/ai/provider.js';
+import { FORGE_PATHS } from '../../core/constants.js';
 
 const SKILLS_DIR = path.join(homedir(), '.claude', 'skills');
 
@@ -98,6 +111,126 @@ async function invokeSkill(skillId: string, options: InvokeOptions): Promise<voi
   }
 }
 
+interface UpgradeOptions {
+  apply?: boolean;
+  rollback?: string;
+  report?: string;
+}
+
+/**
+ * Coordinate the full skill upgrade pipeline.
+ * Default: dry-run — generates a report without writing to src/.
+ * --apply: read report and apply decisions.
+ * --rollback <ts>: restore official skills from a backup timestamp.
+ */
+async function upgradeSkills(options: UpgradeOptions): Promise<void> {
+  const reportPath = options.report ?? FORGE_PATHS.skillUpgradeReport();
+  const officialDir = resolveBuiltinDir();
+  const backupBaseDir = FORGE_PATHS.backups('skills');
+  const candidatesDir = FORGE_PATHS.skillCandidates();
+
+  // ── Rollback mode ────────────────────────────────────────────────────────
+  if (options.rollback) {
+    const backupPath = path.join(backupBaseDir, options.rollback);
+    try {
+      await fsPromises.access(backupPath);
+    } catch {
+      console.error(`Backup not found: ${backupPath}`);
+      process.exit(1);
+    }
+    const files = await fsPromises.readdir(backupPath);
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      await fsPromises.copyFile(path.join(backupPath, file), path.join(officialDir, file));
+    }
+    console.log(`Rolled back ${files.filter(f => f.endsWith('.md')).length} files from ${backupPath}`);
+    console.log('Run `npm run build` to rebuild with restored skills.');
+    return;
+  }
+
+  // ── Apply mode ───────────────────────────────────────────────────────────
+  if (options.apply) {
+    try {
+      await fsPromises.access(reportPath);
+    } catch {
+      console.error(`Report not found: ${reportPath}`);
+      console.error('Run `cf skills upgrade` first to generate a report.');
+      process.exit(1);
+    }
+    console.log(`Applying decisions from ${reportPath}...`);
+    const result = await applyDecisions(reportPath, officialDir, backupBaseDir);
+    console.log(`\nApply complete:`);
+    console.log(`  Applied : ${result.applied}`);
+    console.log(`  Skipped : ${result.skipped}`);
+    console.log(`  Backup  : ${result.backupPath}`);
+    console.log('\nRun `npm run build` to rebuild with updated skills.');
+    return;
+  }
+
+  // ── Dry-run (report generation) mode ────────────────────────────────────
+  console.log('Fetching candidate skills...');
+  const candidates = await pullCandidates(DEFAULT_SOURCES, candidatesDir);
+  console.log(`  Found ${candidates.length} candidate skills`);
+
+  const officialSkills = loadOfficialSkills(officialDir);
+  console.log(`  Loaded ${officialSkills.length} official skills`);
+
+  // Set up AI provider
+  const config = new ConfigManager().get();
+  if (!config.ai.api_key) {
+    console.error('No AI API key configured. Run `cf menu` to set it up.');
+    process.exit(1);
+  }
+  const aiProvider = new ClaudeProvider(config.ai.api_key, config.ai.model, config.ai.base_url);
+
+  let matched = 0;
+  let unmatched = 0;
+  const entries: ReportEntry[] = [];
+
+  console.log('\nEvaluating candidates...');
+
+  for (const candidate of candidates) {
+    const matchResult = matchToOfficial(candidate, officialSkills);
+    if (!matchResult) {
+      unmatched++;
+      continue;
+    }
+
+    matched++;
+    const official = officialSkills.find((o) => o.name === matchResult.officialId);
+    if (!official) continue;
+
+    process.stdout.write(`  ${candidate.id} → ${official.name} (score ${matchResult.score})... `);
+
+    const decision = await evaluateWithAI(candidate, official, aiProvider);
+    const action = (decision as { needs_review?: boolean }).needs_review
+      ? 'needs_review'
+      : decision.action;
+
+    process.stdout.write(`${action}\n`);
+
+    entries.push({
+      officialId: official.name,
+      candidateId: candidate.id,
+      candidateSource: candidate.source,
+      action,
+      confidence: decision.confidence,
+      reasoning: decision.reasoning,
+      candidateFilePath: candidate.filePath,
+      merged_content: decision.merged_content,
+    });
+  }
+
+  const stats = { total: candidates.length, matched, unmatched };
+  await generateReport(entries, reportPath, stats);
+
+  console.log(`\nReport generated: ${reportPath}`);
+  console.log(`Summary: ${matched} matched, ${unmatched} unmatched (of ${candidates.length} total)`);
+  console.log('\nReview the report, then run:');
+  console.log('  cf skills upgrade --apply   (to apply decisions)');
+}
+
+
 function registerSkillSubcommands(skills: Command): void {
   skills
     .command('sync')
@@ -124,6 +257,16 @@ function registerSkillSubcommands(skills: Command): void {
     .action(async (skillId: string, options: InvokeOptions) => {
       await invokeSkill(skillId, options);
     });
+
+  skills
+    .command('upgrade')
+    .description('AI-assisted upgrade of official skills (dry-run by default)')
+    .option('--apply', 'Apply decisions from the last report')
+    .option('--rollback <timestamp>', 'Rollback to a backup (e.g. 20260518-1930)')
+    .option('--report <path>', 'Custom report path')
+    .action(async (options: UpgradeOptions) => {
+      await upgradeSkills(options);
+    });
 }
 
 export function register(program: Command): void {

package/src/core/constants.ts

@@ -28,6 +28,11 @@ export const FORGE_PATHS = {
   // ── Patchable targets ───────────────────────────────────
   routingYaml:  () => join(FORGE_HOME, 'routing.yaml'),
   backups:      (kind: 'skills' | 'routing') => join(FORGE_HOME, 'backups', kind),
+  skillCandidates: (source?: string) =>
+    source
+      ? join(FORGE_HOME, 'skill-candidates', source)
+      : join(FORGE_HOME, 'skill-candidates'),
+  skillUpgradeReport: () => join(FORGE_HOME, 'skill-upgrade-report.md'),
 } as const;
 
 /**

package/src/daemon/hook-sync.ts

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync, copyFileSync, chmodSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FORGE_PATHS } from '../core/constants.js';
+import { logger } from '../core/utils/logger.js';
+
+// All hook files to sync (5 hooks + shared lib)
+const HOOK_FILES = [
+  'pre-tool-use.sh',
+  'post-tool-use.sh',
+  'user-prompt-submit.sh',
+  'notification.sh',
+  'stop.sh',
+  'hook-lib.sh',
+];
+
+function sha256(content: Buffer): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function getSourceHooksDir(): string {
+  // Compiled: dist/daemon/hook-sync.js → dist/hooks
+  // Dev (vitest): src/daemon/hook-sync.ts → src/hooks
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
+}
+
+export interface SyncResult {
+  copied: number;
+  checked: number;
+  skipped: number;
+}
+
+/**
+ * Sync hooks from the package source (dist/hooks) to ~/.claude-forge/hooks/.
+ * Uses SHA-256 comparison to skip identical files.
+ *
+ * Accepts optional overrides for source/target dirs — used in unit tests.
+ * Any failure logs a warning and continues; never throws.
+ */
+export function syncHooks(opts?: { sourceDir?: string; targetDir?: string }): SyncResult {
+  const result: SyncResult = { copied: 0, checked: 0, skipped: 0 };
+  const sourceDir = opts?.sourceDir ?? getSourceHooksDir();
+  const targetDir = opts?.targetDir ?? FORGE_PATHS.hooks();
+
+  if (!existsSync(sourceDir)) {
+    logger.warn(`[HookSync] source hooks dir not found at ${sourceDir}, skipping`);
+    return result;
+  }
+
+  if (!existsSync(targetDir)) {
+    // User has not run `claude-forge init` yet — skip silently
+    logger.debug(`[HookSync] target dir not found: ${targetDir} (user may not have run \`claude-forge init\`)`);
+    return result;
+  }
+
+  for (const file of HOOK_FILES) {
+    const src = join(sourceDir, file);
+    const dest = join(targetDir, file);
+
+    if (!existsSync(src)) {
+      result.skipped++;
+      continue;
+    }
+
+    result.checked++;
+
+    try {
+      const srcContent = readFileSync(src);
+      if (existsSync(dest)) {
+        const destContent = readFileSync(dest);
+        if (sha256(srcContent) === sha256(destContent)) {
+          continue; // identical — no copy needed
+        }
+      }
+
+      copyFileSync(src, dest);
+      chmodSync(dest, 0o755);
+      result.copied++;
+      logger.info(`[HookSync] updated ${file}`);
+    } catch (err) {
+      logger.warn(`[HookSync] failed to sync ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  if (result.copied > 0) {
+    logger.info(`[HookSync] synced ${result.copied}/${result.checked} hook files`);
+  }
+
+  return result;
+}

package/src/daemon/index.ts

@@ -34,6 +34,8 @@ import { ConventionExtractor } from '../claudemd/convention-extractor.js';
 import { UserPromptHandler } from './handlers/user-prompt.js';
 import { PostToolUseHandler } from './handlers/post-tool-use.js';
 import { StopHandler } from './handlers/stop.js';
+import { syncHooks } from './hook-sync.js';
+import { syncSkills } from './skill-sync.js';
 import { replayQueue } from '../core/queue/index.js';
 import { DEFAULTS } from '../core/constants.js';
 import type { ForgeEvent } from '../core/types.js';
@@ -74,6 +76,24 @@ export async function startDaemon(foreground: boolean = false, options: DaemonOp
   const storage = new SQLiteStorage(dbPath);
   logger.info(`Storage initialized: ${dbPath}`);
 
+  // ── 3.5. Auto-sync hooks ────────────────────────────────────────────────
+  // npm upgrade 不会自动更新 ~/.claude-forge/hooks/，每次 daemon 启动
+  // 用 SHA-256 比对源 dist/hooks 与本地副本，不一致则覆盖。
+  try {
+    syncHooks();
+  } catch (err) {
+    logger.warn(`[HookSync] unexpected error: ${err}`);
+  }
+
+  // ── 3.6. Auto-sync official skills ─────────────────────────────────────
+  // npm upgrade 不会自动更新 ~/.claude/skills/，每次 daemon 启动
+  // 用 SHA-256 比对 dist/skills/official 与本地副本，不一致则覆盖。
+  try {
+    syncSkills();
+  } catch (err) {
+    logger.warn(`[SkillSync] unexpected error: ${err}`);
+  }
+
   // ── 4. AI Provider ─────────────────────────────────────────────────────────
   const apiKey = config.ai.api_key || process.env.ANTHROPIC_API_KEY || '';
   if (!apiKey) {
@@ -86,7 +106,7 @@ export async function startDaemon(foreground: boolean = false, options: DaemonOp
 
   // ── 5. Initialize services ─────────────────────────────────────────────────
   const skillApiKey = config.skill_matching?.api_key || apiKey;
-  const skillRegistry = new SkillRegistry(skillApiKey);
+  const skillRegistry = new SkillRegistry(skillApiKey, config.ai.model, config.ai.base_url);
   const invocationGuard = new InvocationGuard();
   if (skillApiKey) {
     logger.info('[Skills] Registry loaded with semantic matching support');