ai-optimize-master 0.0.0-stage → 0.3.2

package/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "ai-optimize-master",
+  "version": "0.3.2",
+  "description": "AI 优化大师 — audit duplicate, broken and stale AI-tool skills, propose improvements, archive reversibly.",
+  "author": {
+    "name": "2Origin",
+    "url": "https://github.com/dongsheng123132"
+  },
+  "homepage": "https://github.com/dongsheng123132/ai-optimize-master",
+  "repository": "https://github.com/dongsheng123132/ai-optimize-master",
+  "license": "MIT",
+  "keywords": [
+    "ai-optimize-master",
+    "deepseek-harness",
+    "skill-management",
+    "mcp",
+    "cleanup"
+  ],
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "AI 优化大师",
+    "shortDescription": "Audit duplicate, broken and stale AI-tool skills; propose improvements; clean up reversibly.",
+    "longDescription": "Scans the skill roots of every AI tool on this machine, reports byte-identical duplicates, diverged copies, dangling local references and unreadable roots, surfaces MCP declarations without executing any server, and proposes improvements as diffs. Cleanup is opt-in per skill: a hash-bound plan, a journal, and byte-exact undo.",
+    "developerName": "2Origin",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Audit",
+      "Reversible cleanup"
+    ],
+    "defaultPrompt": [
+      "扫描我的 AI 工具技能目录，告诉我哪些重复、断链、该升级。"
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "ai-optimize-master": {
+      "command": "node",
+      "args": [
+        "./mcp-server.mjs"
+      ],
+      "description": "Read-only AI tool asset inventory and planning. Apply/undo are intentionally not exposed over MCP."
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 火火的（深圳）科技有限公司 / 2Origin
+
+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

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# AI Optimize Master · know where every skill came from, review the change, restore the config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> For people who run Claude Code, Codex, Cursor, DSH, OpenClaw and Hermes side by side:
+> how many copies of that skill do you have? Which ones point at files that no longer
+> exist? How many places declare MCP servers?
+>
+> This version does one thing: **establish the facts, then clean up reversibly.**
+
+MIT licensed · no account · no network calls.
+
+## What it is
+
+One governance core with three surfaces:
+
+| Step | What it does | Writes to your disk? |
+|---|---|---|
+| `scan` | Inventories each AI tool's skill roots, duplicate definitions, dangling references, MCP declarations, tool versions | **Never** |
+| `plan` | Turns your explicit selections into a reviewable plan with a `planHash` | No |
+| `apply` | Executes low-risk archive steps only; requires the exact hash; journals each step | Move only, reversible |
+| `undo` | Restores from the journal in reverse order | Refuses to clobber later edits |
+
+## Three real scenarios
+
+1. **A Windows workstation with 14 AI tools × 28 skills each** (≈392 copies). `scan`
+   separates "same name, same content" from "same name, different content" and never
+   merges those into one conclusion.
+2. **A skill tells the agent to open `scripts/run.mjs`, but the file is gone.** `scan`
+   reports `skills.broken-references` with the exact missing paths.
+3. **Cleanup broke a tool.** `undo` restores from the journal; if you edited the file
+   after apply, it reports a conflict instead of overwriting.
+
+## First run (three commands)
+
+```bash
+npx ai-optimize-master scan     # read-only inventory
+npx ai-optimize-master evolve   # improvement proposals (diffs only)
+npx ai-optimize-master plan --select <skill> --out plan.json   # reviewable plan
+npx ai-optimize-master apply --plan plan.json --expect <planHash>  # requires the hash
+```
+
+As a DSH plugin, the tools are `dsh_optimizer_scan|plan|apply|undo`. The MCP surface
+(`node mcp-server.mjs`, stdio) exposes **only** `optimizer_scan` and `optimizer_plan`.
+
+## What it proves
+
+Verification is `npm test`, not prose. 23 contract tests:
+
+| Id | Defends against |
+|---|---|
+| O1 | "Just checking" mutating the machine |
+| O2 | An unreadable root being reported as clean |
+| O3 | A binary on PATH that crashes being reported as installed |
+| O4 | Apply without reading the plan (exit 4) |
+| O5 | A plan changed after review (exit 3) |
+| O6 | Journal completeness and byte-exact undo |
+| O7 | Admin steps silently skipped yet journaled |
+| O8 | Tests polluting the real machine |
+| O9 | `bytes/4` presented as a measured token count |
+| O10 | Plan hashes drifting with object key order |
+
+```bash
+npm test        # 16 tests
+npm run check   # structure, read-only scan, MCP write surface absent
+```
+
+## Before you start
+
+- **Does it delete?** No. `apply` moves directories into `$DSH_OPTIMIZER_HOME/archive/`.
+- **Does it edit MCP config?** No. MCP is read-only in v0.2.
+- **Does it upgrade Node or PowerShell?** No. Versions are advisory.
+- **Can I delete duplicates immediately?** Identical content only proves duplicate
+  definition, not that a copy is unused. Single-copy skills are `medium` risk and are
+  not executed by default.
+- **Cross-platform?** Yes. Extra Windows roots are declared through the
+  `DSH_OPTIMIZER_ROOTS` environment variable; no drive letters are guessed.
+- **Cost?** MIT, offline, no credentials.
+
+## Evidence
+
+- Source: this repository, `main`
+- Verification: `npm test` (16) and `npm run check`
+- Boundaries: [`SECURITY.md`](SECURITY.md)
+- Last reviewed: 2026-11-06
+
+## Recognised skill roots
+
+22 known locations are probed by default (DSH / agents / Claude / Codex / Cursor / OpenClaw / U-King / Hermes / OpenCode / Pi / Gemini / Qwen / Trae / Windsurf / Qoder / CodeBuddy / CommandCode / Grok / iFlow / Lingma / ZCode / the agents canonical source). Missing directories are skipped, never created and never reported as errors. Extra shared trees (e.g. a Windows workstation) are added with `DSH_OPTIMIZER_ROOTS`.
+
+## Support matrix
+
+| Capability | Windows | macOS | Linux |
+|---|---|---|---|
+| Skill inventory / duplicates / broken refs | ✅ | ✅ | ✅ |
+| Read-only MCP declaration inventory | ✅ | ✅ | ✅ |
+| Tool version probes (node/git/pwsh/claude/codex) | ✅ | ✅ | ✅ |
+| Reversible archive | ✅ | ✅ | ✅ |
+| Version upgrades / MCP uninstall | ❌ advisory only | ❌ advisory only | ❌ advisory only |
+| Starting MCP servers / executing skill scripts | ❌ out of scope | ❌ out of scope | ❌ out of scope |

package/README.zh-CN.md

@@ -0,0 +1,104 @@
+# AI 优化大师 · AI 工具越装越多，也能查清来源、审阅变更、恢复配置
+
+> 给同时装了 Claude Code、Codex、Cursor、DSH、OpenClaw、Hermes 的人：
+> 你的 skill 被复制了几份？哪些指向了不存在的脚本？MCP 配了几处？
+> 这一版只做一件事：**先把事实查清，再用可回滚的方式收干净。**
+
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## 它是什么
+
+一个 **DSH 插件 + CLI + 只读 MCP**，共用一套治理核心：
+
+| 动作 | 做什么 | 会不会改你的盘 |
+|---|---|---|
+| `scan` | 盘点每个 AI 工具的 skill 根、重复定义、断链引用、MCP 声明、工具版本 | **绝不写** |
+| `plan` | 把选中的 skill 变成一份带风险的方案，算出 `planHash` | 不改 |
+| `apply` | 只执行低风险归档，必须出示 `planHash`，每步写 journal | 只移动，可撤销 |
+| `undo` | 按 journal 逆序还原 | 有改动就报冲突，不覆盖 |
+
+## 三个真实场景
+
+1. **一台 Windows 工作站装了 14 个 AI 工具，每个都有 28 个 skill**——约 392 份副本。
+   `scan` 会把「同名同内容」和「同名不同内容」分开报，不合并结论。
+2. **某个 skill 让 AI 去读 `scripts/run.mjs`，但那个文件早就没了**——`scan` 报
+   `skills.broken-references`，并列出缺哪个文件。
+3. **清理完发现某个工具不能用了**——`undo` 从 journal 还原，遇到你后来改过的文件
+   会报冲突而不是覆盖。
+
+## 第一次使用（三步）
+
+```bash
+# 1. 只读体检（不会改动任何东西）
+npx ai-optimize-master scan
+
+# 2. 出一份方案（先看再决定）
+npx ai-optimize-master plan --select <skill名> --out plan.json
+
+# 3. 拿着方案哈希执行；没有哈希会被拒绝（退出码 4）
+npx ai-optimize-master apply --plan plan.json --expect <planHash>
+```
+
+安装到 DSH 作为插件：
+
+```bash
+# 插件清单在 .codex-plugin/plugin.json，MCP 面只读（scan/plan）
+node mcp-server.mjs    # stdio MCP，只有两个只读工具
+```
+
+## 它证明过什么
+
+本仓库的验收不靠自述，靠 `npm test` 的 23 条判据：
+
+| 判据 | 防的是什么 |
+|---|---|
+| O1 scan 全程零写盘 | 「检查一下」把机器改了 |
+| O2 没跑 ≠ 通过 | 读不到的目录被当成干净 |
+| O3 存在 ≠ 可用 | PATH 里有、一跑就崩，却被报成已安装 |
+| O4 无 `--expect` 必拒 | 没读方案就执行 |
+| O5 哈希过期必拒 | 方案被改过仍照跑 |
+| O6 journal 完备 + 逐字节还原 | 删了回不去 |
+| O7 管理员步骤不偷跑 | 没做却留下「做过」的痕迹 |
+| O8 沙箱隔离 | 测试污染真机 |
+| O9 估算必须带标签 | 把 `bytes/4` 当精确 token 数 |
+| O10 planHash 键序无关、值敏感 | 同一方案哈希漂移 |
+
+```bash
+npm test        # 16 项
+npm run check   # 结构 + 只读边界 + MCP 不暴露 apply
+```
+
+## 开始前你可能想知道
+
+- **它会删东西吗？** 不删。`apply` 只把目录移动到 `$DSH_OPTIMIZER_HOME/archive/`。
+- **它会改我的 MCP 配置吗？** 不会。v0.2 的 MCP 面只读，只报声明数量与条目名。
+- **它会帮我升级 Node / PowerShell 吗？** 不会。版本只做建议，不做自动升级。
+- **重复的 skill 能直接删吗？** 不能直接下结论。同名同内容只说明是重复定义，
+  不说明哪份没人用。方案里单副本 skill 是 `medium` 风险，默认不执行。
+- **Mac 和 Windows 都能跑吗？** 核心是跨平台的；Windows 上多出的工具根目录用
+  `DSH_OPTIMIZER_ROOTS` 显式声明，不猜盘符。
+- **免费吗？** MIT。没有账号、没有网络请求。
+
+## 本页依据
+
+- 源码：本仓库 `main`
+- 验收：`npm test`（16 项）与 `npm run check`
+- 安全边界：`SECURITY.md`
+- 最后核对：2026-11-06
+
+## 支持矩阵
+
+| 能力 | Windows | macOS | Linux |
+|---|---|---|---|
+| skill 根盘点 / 重复 / 断链 | ✅ | ✅ | ✅ |
+| MCP 声明只读盘点 | ✅ | ✅ | ✅ |
+| 工具版本探测（node/git/pwsh/claude/codex） | ✅ | ✅ | ✅ |
+| 可回滚归档 | ✅ | ✅ | ✅ |
+| 版本升级 / MCP 自动卸载 | ❌ 仅建议 | ❌ 仅建议 | ❌ 仅建议 |
+| 动态启动 MCP / 执行 skill 脚本 | ❌ 不做 | ❌ 不做 | ❌ 不做 |
+
+## 和 U-King「AI 优化大师」的关系
+
+同一个方向，两个入口，**共享同一套治理语义**（资产模型、方案、哈希门禁、journal、
+退出码）。U-King 侧已有环境体检与一键优化（可回滚）；本仓库负责跨工具资产盘点与
+清理。两边不互相重写执行器。

package/SECURITY.md

@@ -0,0 +1,89 @@
+# Security model
+
+## Scope
+
+`ai-optimize-master` inspects AI-tool asset directories and MCP configuration files on
+the machine where it runs. It does not phone home, does not upload inventory, and
+does not require credentials.
+
+## Surface boundaries
+
+| Surface | Read | Plan | Apply / Undo |
+|---|---|---|---|
+| CLI (`bin/ai-optimize-master.mjs`) | yes | yes | yes (local, with `--expect`) |
+| DSH plugin tools | yes | yes | yes (with `expect`) |
+| MCP server (`mcp-server.mjs`) | yes | yes | **no — deliberately absent** |
+
+The MCP surface exposes only `optimizer_scan` and `optimizer_plan`. A remote MCP
+caller must not be able to modify this machine; **apply and undo are intentionally
+not importable from `mcp-server.mjs`**. `scripts/check.mjs` fails the build if that
+boundary is broken.
+
+## What apply can do
+
+`apply` only performs `archive-skill` steps: it copies a skill directory into the
+optimizer's own archive root, verifies the copy, then removes the original from the
+tool's skill root.
+
+Hard constraints:
+
+- Every step is validated before any write: unknown `risk`/`allow` values, unknown
+  step kinds, and malformed previews are rejected with exit **1** instead of being
+  silently downgraded.
+- The source must live inside one of the plan's `authorizedRoots`, must not be a
+  symlink, and its real path must also stay inside a root (prefix checks alone do
+  not catch symlinked ancestors).
+- The archive target must not already exist. A previous archive is never merged
+  into; the step is blocked as `archive-target-exists`.
+- The caller must pass the exact `planHash` (`--expect`); otherwise the run exits
+  **4 (denied)**.
+- If the plan body no longer matches its hash, the run exits **3 (diverged)** and
+  doesn't touch anything.
+- Default `--allow low` executes only low-risk steps. A single-copy skill is
+  `medium` risk and is skipped unless explicitly allowed.
+- A step marked `requiresAdmin` is blocked when not elevated, and **no journal
+  entry is written** for a step that never ran.
+- The journal is written **before** the first destructive operation (intent) and
+  rewritten after every step, so a crash mid-run still leaves an accurate record.
+- The journal stores a full directory manifest (relative path, entry type, file
+  SHA-256, symlink target) for both the source and the archived copy. A single
+  `SKILL.md` hash is not treated as proof that the archive is complete.
+
+## What apply cannot do (v0.2)
+
+- It does not delete anything permanently: archive is a move into
+  `$DSH_OPTIMIZER_HOME/archive/`.
+- It does not modify MCP configuration files. MCP surfaces are read-only.
+- It does not install, upgrade, or downgrade Node, Git, or PowerShell. Version
+  findings are advisory only.
+- It does not start MCP servers or execute skill scripts. Dynamic probing of
+  unknown code is out of scope.
+
+## Undo semantics
+
+`undo` processes journal steps in reverse order and checks two things before
+restoring: the archived tree still matches its recorded manifest, and the original
+path is still free. If the user re-created the original path after apply, the step
+is reported as `conflict`/`target-occupied` and **is not overwritten**. An
+already-restored step is detected by manifest and reported as `already-restored`
+instead of failing.
+
+## Concurrent writes
+
+`archive` builds a manifest, copies to a staging directory, verifies the copy,
+renames it into place, re-checks the source manifest, and only then removes the
+source. This narrows the window in which a concurrently edited file could be lost,
+but it cannot eliminate it. When the source changes during the copy, the step is
+blocked as `source-changed-during-copy` and nothing is deleted.
+
+## Known limits, stated honestly
+
+- Duplicate detection compares `SKILL.md` content hashes. Identical content does
+  **not** prove a copy is unused, and divergence does not prove either copy is
+  stale.
+- An unreadable root is reported as `applicable: false` with a reason. It is never
+  reported as clean.
+- A binary that exists on PATH but exits non-zero is reported as **unusable**, not
+  as installed.
+- Archives are recoverable but not encrypted; treat `$DSH_OPTIMIZER_HOME` as
+  sensitive as the skills it contains.

package/bin/dsh-optimizer.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// CLI entry. Exit codes are part of the contract:
+//   0 success | 1 usage/runtime failure | 3 diverged | 4 denied
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join, resolve, dirname } from 'node:path'
+import { scan } from '../lib/scan.mjs'
+import { propose, compareScans } from '../lib/evolve.mjs'
+import { buildPlan, applyPlan, undoJournal } from '../lib/apply.mjs'
+import { home, expandHome } from '../lib/util.mjs'
+
+function usage() {
+  return `AI 优化大师 (ai-optimize-master) v0.3 — audit and reversibly clean AI tool assets
+
+Usage:
+  ai-optimize-master scan    [--json] [--save-baseline FILE] [--no-probes]
+  ai-optimize-master evolve  [--in FILE] [--baseline FILE] [--out FILE] [--json]
+  ai-optimize-master plan    [--select name]... [--root id]... [--in FILE] [--out FILE] [--json]
+  ai-optimize-master apply   --plan FILE --expect HASH [--allow low|medium|high] [--json]
+  ai-optimize-master undo    --journal FILE [--json]
+
+Exit codes: 0 ok · 1 usage/runtime error · 3 diverged · 4 denied
+
+Safety:
+  - scan is strictly read-only (the only file it writes is an explicit --save-baseline).
+  - evolve proposes improvements and diffs; it never edits a skill.
+  - plan never mutates anything.
+  - apply requires --expect with the exact plan hash and journals every change.
+  - Only skills that live inside a declared skill root can be archived.
+`
+}
+
+function parseArgs(argv) {
+  const args = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]
+    if (!token.startsWith('--')) { args._.push(token); continue }
+    const key = token.slice(2)
+    const next = argv[i + 1]
+    if (next === undefined || next.startsWith('--')) { args[key] = true; continue }
+    if (args[key] === undefined) args[key] = next
+    else (Array.isArray(args[key]) ? args[key] : (args[key] = [args[key]])).push(next)
+    i++
+  }
+  return args
+}
+
+function toList(value) {
+  if (value === undefined) return []
+  return Array.isArray(value) ? value : [value]
+}
+
+async function readJson(file) {
+  return JSON.parse(await readFile(expandHome(file), 'utf8'))
+}
+
+async function ensureDir(dir) {
+  await mkdir(dir, { recursive: true })
+}
+
+function journalWriter(root) {
+  return {
+    async write(doc) {
+      await ensureDir(root)
+      const file = join(root, `${doc.planHash}.json`)
+      await writeFile(file, JSON.stringify(doc, null, 2), 'utf8')
+      return file
+    }
+  }
+}
+
+async function cmdScan(args) {
+  const roots = toList(args.roots).flatMap(v => String(v).split(process.platform === 'win32' ? ';' : ':'))
+    .filter(Boolean)
+    .map(dir => ({ id: `extra:${dir.split(/[\\/]/).pop()}`, label: `Extra root ${dir}`, dir }))
+  const result = await scan({
+    roots: roots.length ? [...(await import('../lib/scan.mjs')).defaultRoots(), ...roots] : undefined,
+    probes: !args['no-probes']
+  })
+  if (args['save-baseline']) {
+    // The inspected trees are still untouched; this writes only the named file.
+    const target = expandHome(String(args['save-baseline']))
+    await mkdir(dirname(resolve(target)), { recursive: true })
+    await writeFile(target, JSON.stringify(result, null, 2), 'utf8')
+  }
+  if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  else process.stdout.write(renderScan(result))
+  return 0
+}
+
+async function cmdEvolve(args) {
+  const current = args.in ? await readJson(args.in) : await scan({ probes: false })
+  const report = await propose(current)
+  if (args.baseline) {
+    const baseline = await readJson(args.baseline)
+    report.changes = compareScans(baseline, current)
+  }
+  if (args.out) {
+    const target = expandHome(String(args.out))
+    await mkdir(dirname(resolve(target)), { recursive: true })
+    await writeFile(target, JSON.stringify(report, null, 2), 'utf8')
+  }
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    const lines = [`AI 优化大师 · evolve (proposals only, nothing was changed)`]
+    lines.push(`Proposals: ${report.proposals.length}  ${JSON.stringify(report.counts)}`)
+    for (const p of report.proposals.slice(0, 20)) {
+      lines.push(`  [${p.risk}] ${p.kind} · ${p.skill}: ${p.suggestion.slice(0, 90)}${p.suggestion.length > 90 ? '…' : ''}`)
+    }
+    if (report.proposals.length > 20) lines.push(`  … ${report.proposals.length - 20} more (use --json)`)
+    if (report.changes) {
+      lines.push('', `Changes since baseline: +${report.changes.added.length} / -${report.changes.resolved.length}`)
+    }
+    lines.push('', 'Nothing is applied by evolve. Review a diff, then edit the skill yourself or archive it.')
+    process.stdout.write(`${lines.join('\n')}\n`)
+  }
+  return 0
+}
+
+function renderScan(result) {
+  const lines = []
+  lines.push(`AI tool inventory (${result.platform}) — read-only`)
+  lines.push('')
+  for (const root of result.roots) {
+    if (!root.applicable) { lines.push(`  ${root.label}: ${root.notApplicableReason}`); continue }
+    lines.push(`  ${root.label.padEnd(28)} ${String(root.skillCount).padStart(3)} skills  ${root.dir}`)
+  }
+  const counts = result.findings.reduce((acc, f) => { acc[f.severity] = (acc[f.severity] ?? 0) + 1; return acc }, {})
+  lines.push('')
+  lines.push(`Findings: ${Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(' · ') || 'none'}`)
+  for (const f of result.findings.filter(f => f.severity !== 'info')) lines.push(`  [${f.severity}] ${f.title}`)
+  lines.push('')
+  lines.push(`Duplicates: ${result.duplicates.length} (identical ${result.duplicates.filter(d => d.classification === 'identical-copies').length})`)
+  lines.push(`MCP declarations: ${result.mcp.map(m => `${m.id}=${m.servers.length}`).join(' ') || 'none'}`)
+  return `${lines.join('\n')}\n`
+}
+
+async function cmdPlan(args) {
+  const scanResult = args.in ? await readJson(args.in) : await scan({ probes: false })
+  const names = toList(args.select)
+  const roots = toList(args.root)
+  const selections = names.map((name, index) => roots[index] ? { name, root: roots[index] } : name)
+  const plan = buildPlan(scanResult, { selections, home: home() })
+  const archiveRoot = plan.archiveRoot
+  if (args.out) {
+    await ensureDir(dirname(resolve(expandHome(args.out))))
+    await writeFile(expandHome(args.out), JSON.stringify(plan, null, 2), 'utf8')
+  }
+  if (args.json) process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`)
+  else {
+    const lines = [`Plan ${plan.planHash}`, `Archive root: ${archiveRoot}`, `Steps: ${plan.steps.length}`]
+    for (const step of plan.steps) lines.push(`  [${step.risk}] ${step.id}  ${step.preview.from} -> ${step.preview.to}`)
+    for (const skip of plan.skipped) lines.push(`  skipped ${skip.name}: ${skip.reason}`)
+    lines.push('', 'Apply with:', `  dsh-optimizer apply --plan <file> --expect ${plan.planHash}`)
+    process.stdout.write(`${lines.join('\n')}\n`)
+  }
+  return 0
+}
+
+async function cmdApply(args) {
+  if (!args.plan) { process.stderr.write('apply requires --plan\n'); return 1 }
+  const plan = await readJson(args.plan)
+  const journalRoot = join(home(), 'journal')
+  const result = await applyPlan(plan, {
+    expect: typeof args.expect === 'string' ? args.expect : null,
+    allow: typeof args.allow === 'string' ? args.allow : 'low',
+    journal: journalWriter(journalRoot),
+    isAdmin: typeof process.getuid === 'function' ? process.getuid() === 0 : false
+  })
+  if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  else {
+    for (const step of result.results ?? []) process.stdout.write(`${step.status.padEnd(8)} ${step.id}${step.blocked ? ` (${step.blocked})` : ''}\n`)
+    if (result.reason) process.stderr.write(`${result.reason}\n`)
+  }
+  return result.code
+}
+
+async function cmdUndo(args) {
+  if (!args.journal) { process.stderr.write('undo requires --journal\n'); return 1 }
+  const doc = await readJson(args.journal)
+  const result = await undoJournal(doc, { journal: journalWriter(join(home(), 'journal')) })
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  return result.code
+}
+
+const commands = { scan: cmdScan, evolve: cmdEvolve, plan: cmdPlan, apply: cmdApply, undo: cmdUndo }
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const command = argv[0]
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    process.stdout.write(usage())
+    return 0
+  }
+  const handler = commands[command]
+  if (!handler) { process.stderr.write(`unknown command: ${command}\n\n${usage()}`); return 1 }
+  try {
+    return await handler(parseArgs(argv.slice(1)))
+  } catch (error) {
+    process.stderr.write(`dsh-optimizer ${command} failed: ${error?.message ?? error}\n`)
+    return 1
+  }
+}
+
+process.exitCode = await main()

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: ai-optimize-master
+      name: ai-optimize-master

package/index.js

@@ -0,0 +1,90 @@
+// DSH plugin surface: three tools, all sharing one core.
+// scan  — strictly read-only inventory.
+// plan  — turns findings + explicit selections into a reviewable, hash-bound plan.
+// apply — executes a low-risk, reversible archive; requires the exact plan hash.
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { scan } from './lib/scan.mjs'
+import { buildPlan, applyPlan, undoJournal } from './lib/apply.mjs'
+import { home } from './lib/util.mjs'
+import { writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const name = 'ai-optimize-master'
+export const inject = ['tools']
+
+const renderJson = (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+
+const journal = {
+  async write(doc) {
+    const root = join(home(), 'journal')
+    await mkdir(root, { recursive: true })
+    const file = join(root, `${doc.planHash}.json`)
+    await writeFile(file, JSON.stringify(doc, null, 2), 'utf8')
+    return file
+  }
+}
+
+export function createDefinitions() {
+  return [
+    defineTool({
+      name: 'dsh_optimizer_scan',
+      description: 'Read-only inventory of AI tool skill roots, duplicate/broken skill definitions, MCP declarations, and tool versions. Never writes to any inspected directory. A tool that exists on PATH but fails to run is reported as unusable, not as installed.',
+      parameters: {
+        includeProbes: { type: 'boolean', description: 'Run the allowlisted version probes (node/git/pwsh/claude/codex). Default true.' }
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      async execute(args = {}) {
+        const result = await scan({ probes: args.includeProbes ?? true })
+        return { ...result, readOnly: true }
+      }
+    }),
+    defineTool({
+      name: 'dsh_optimizer_plan',
+      description: 'Build a reviewable plan from a scan. Selective: only explicitly selected skills become steps. Returns a planHash that apply requires. Does not modify anything.',
+      parameters: {
+        select: { type: 'array', description: 'Skill names to consider archiving.', items: { type: 'string' } },
+        root: { type: 'array', description: 'Optional root id per selection, in the same order.', items: { type: 'string' } }
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      async execute(args = {}) {
+        const scanResult = await scan({ probes: false })
+        const selected = (args.select ?? []).map((skillName, index) => (args.root?.[index]
+          ? { name: skillName, root: args.root[index] }
+          : skillName))
+        return buildPlan(scanResult, { selections: selected })
+      }
+    }),
+    defineTool({
+      name: 'dsh_optimizer_apply',
+      description: 'Apply a previously planned archive step set. Requires the exact planHash via expect; without it the call is denied. Journals every change so undo can restore byte-identical content. Only low-risk steps by default.',
+      parameters: {
+        plan: { type: 'json', required: true, description: 'The plan object returned by dsh_optimizer_plan.' },
+        expect: { type: 'string', required: true, description: 'The planHash being approved.' },
+        allow: { type: 'string', description: 'Maximum risk to execute: low|medium|high. Default low.' }
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      async execute(args) {
+        const result = await applyPlan(args.plan, {
+          expect: args.expect,
+          allow: args.allow ?? 'low',
+          journal,
+          isAdmin: false
+        })
+        if (result.code === 4) throw Object.assign(new Error('denied: apply requires the exact plan hash'), { code: 'DENIED' })
+        if (result.code === 3) throw Object.assign(new Error('diverged: plan hash does not match plan content'), { code: 'DIVERGED' })
+        return result
+      }
+    }),
+    defineTool({
+      name: 'dsh_optimizer_undo',
+      description: 'Undo an applied journal in reverse order. A step whose content changed after apply is reported as a conflict instead of being overwritten.',
+      parameters: {
+        journal: { type: 'json', required: true, description: 'The journal document returned by apply.' }
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      async execute(args) {
+        return undoJournal(args.journal, { journal })
+      }
+    })
+  ]
+}