feat(ktuner): add deterministic kernel-tuning engine

.github/commitlint.config.json

@@ -17,6 +17,7 @@
         "memory",
         "anolisa",
         "skillfs",
+        "ktuner",
         "deps",
         "ci",
         "docs",

.github/workflows/ci.yaml

@@ -42,6 +42,11 @@ on:
         required: false
         type: boolean
         default: false
+      run_ktuner:
+        description: 'Force run ktuner tests (ignore change detection)'
+        required: false
+        type: boolean
+        default: false
       run_skillfs:
         description: 'Force run SkillFS tests (ignore change detection)'
         required: false
@@ -73,6 +78,7 @@ jobs:
       anolisa: ${{ steps.changes.outputs.anolisa }}
       skillfs: ${{ steps.changes.outputs.skillfs }}
       cosh_ng: ${{ steps.changes.outputs.cosh_ng }}
+      ktuner: ${{ steps.changes.outputs.ktuner }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -102,6 +108,7 @@ jobs:
           ANOLISA=false
           SKILLFS=false
           COSH_NG=false
+          KTUNER=false
 
           # Path-based detection
           if echo "$CHANGED" | grep -q "^src/copilot-shell/"; then
@@ -131,6 +138,9 @@ jobs:
           if echo "$CHANGED" | grep -q "^src/cosh-ng/"; then
             COSH_NG=true
           fi
+          if echo "$CHANGED" | grep -q "^src/ktuner/"; then
+            KTUNER=true
+          fi
 
           # Manual override via workflow_dispatch
           if [[ "${{ inputs.run_copilot_shell }}" == "true" ]]; then
@@ -160,6 +170,9 @@ jobs:
           if [[ "${{ inputs.run_cosh_ng }}" == "true" ]]; then
             COSH_NG=true
           fi
+          if [[ "${{ inputs.run_ktuner }}" == "true" ]]; then
+            KTUNER=true
+          fi
 
           echo "copilot_shell=$COPILOT_SHELL" >> $GITHUB_OUTPUT
           echo "agent_sec_core=$AGENT_SEC" >> $GITHUB_OUTPUT
@@ -170,6 +183,7 @@ jobs:
           echo "anolisa=$ANOLISA" >> $GITHUB_OUTPUT
           echo "skillfs=$SKILLFS" >> $GITHUB_OUTPUT
           echo "cosh_ng=$COSH_NG" >> $GITHUB_OUTPUT
+          echo "ktuner=$KTUNER" >> $GITHUB_OUTPUT
 
           echo "### Change Detection Results" >> $GITHUB_STEP_SUMMARY
           echo "| Component | Changed |" >> $GITHUB_STEP_SUMMARY
@@ -183,6 +197,7 @@ jobs:
           echo "| anolisa | $ANOLISA |" >> $GITHUB_STEP_SUMMARY
           echo "| SkillFS | $SKILLFS |" >> $GITHUB_STEP_SUMMARY
           echo "| cosh-ng | $COSH_NG |" >> $GITHUB_STEP_SUMMARY
+          echo "| ktuner | $KTUNER |" >> $GITHUB_STEP_SUMMARY
 
   # =========================================================================
   # Step 2: Build & Lint copilot-shell
@@ -960,3 +975,38 @@ jobs:
         run: |
           cd src/cosh-ng
           cargo test --workspace
+
+  # =========================================================================
+  # Step 12: Test ktuner (deterministic kernel-tuning engine)
+  # =========================================================================
+  test-ktuner:
+    name: Test ktuner
+    needs: detect-changes
+    if: needs.detect-changes.outputs.ktuner == 'true'
+    runs-on: [self-hosted, ubuntu]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: '1.89.0'
+          components: 'rustfmt, clippy'
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: src/ktuner
+
+      - name: Check formatting
+        run: |
+          cd src/ktuner
+          cargo fmt --all --check
+
+      - name: Lint
+        run: |
+          cd src/ktuner
+          cargo clippy --all-targets -- -D warnings
+
+      - name: Run tests
+        run: |
+          cd src/ktuner
+          cargo test

.github/workflows/prelint.yml

@@ -68,7 +68,7 @@ jobs:
                 `Examples: feat(cosh): add json output\n` +
                 `          fix(sec-core): handle sandbox escape\n` +
                 `Valid types: feat, fix, refactor, perf, docs, chore, test, ci, build, style, revert\n` +
-                `Valid scopes: cosh, sec-core, skill, sight, tokenless, ckpt, memory, anolisa, skillfs, deps, ci, docs, chore\n` +
+                `Valid scopes: cosh, sec-core, skill, sight, tokenless, ckpt, memory, anolisa, skillfs, ktuner, deps, ci, docs, chore\n` +
                 `See CONTRIBUTING.md or AGENT.md for details.`
               );
               return;
@@ -79,7 +79,7 @@ jobs:
             if (scopeMatch) {
               const scope = scopeMatch[1].slice(1, -1);
               const validScopes = [
-                'cosh', 'sec-core', 'skill', 'sight', 'tokenless', 'ckpt', 'memory', 'anolisa', 'skillfs',
+                'cosh', 'sec-core', 'skill', 'sight', 'tokenless', 'ckpt', 'memory', 'anolisa', 'skillfs', 'ktuner',
                 'agent-sec-core', 'agentsight', 'os-skills', 'ws-ckpt', 'agent-memory', // legacy aliases
                 'deps', 'ci', 'docs', 'chore'
               ];
@@ -125,7 +125,7 @@ jobs:
             }
 
             // Valid scopes — short names preferred; legacy long names accepted for forward compatibility
-            const validScopes = ['cosh', 'sec-core', 'skill', 'sight', 'tokenless', 'ckpt', 'memory', 'anolisa', 'skillfs', 'agent-sec-core', 'agentsight', 'os-skills', 'ws-ckpt', 'agent-memory', 'ci', 'docs', 'deps'];
+            const validScopes = ['cosh', 'sec-core', 'skill', 'sight', 'tokenless', 'ckpt', 'memory', 'anolisa', 'skillfs', 'ktuner', 'agent-sec-core', 'agentsight', 'os-skills', 'ws-ckpt', 'agent-memory', 'ci', 'docs', 'deps'];
             const scopePattern = validScopes.join('|');
 
             // Valid branch patterns per development spec

AGENTS.md

@@ -17,8 +17,9 @@ This file provides context for AI coding assistants (Qoder, Claude, etc.) workin
 | **anolisa** | `src/anolisa/` | Rust | Linux + macOS (arm64) |
 | **SkillFS** (`skillfs`) | `src/skillfs/` | Rust / FUSE | Linux only |
 | **ws-ckpt** | `src/ws-ckpt/` | Rust + TypeScript | Linux only |
+| **ktuner** | `src/ktuner/` | Rust | Linux only |
 
-> `agent-sec-core`, `agentsight`, `tokenless`, `agent-memory`, and `skillfs` require Linux. Do **not** attempt to build them on macOS or Windows.
+> `agent-sec-core`, `agentsight`, `tokenless`, `agent-memory`, `skillfs`, and `ktuner` require Linux. Do **not** attempt to build them on macOS or Windows.
 
 ## 2. Development Commands
 
@@ -83,11 +84,17 @@ cargo fmt --all --check
 cargo clippy --workspace --all-targets -- -D warnings
 cargo test --workspace
 scripts/test.sh   # FUSE smoke test; skips itself if fuse3 or /dev/fuse is unavailable
+
+# ktuner (Linux only, per-component)
+cd src/ktuner
+cargo fmt --all --check
+cargo clippy --all-targets -- -D warnings
+cargo test
 ```
 
 ## 3. Rust Common Conventions
 
-> Applies to all Rust components: `anolisa`, `agentsight`, `tokenless`, `agent-memory`, `skillfs`.
+> Applies to all Rust components: `anolisa`, `agentsight`, `tokenless`, `agent-memory`, `skillfs`, `ktuner`.
 
 ### 3.1 Comment Guidelines
 
@@ -259,6 +266,7 @@ When generating commits, detect the active tool and fill in the actual version.
 | `src/agent-memory/` | `memory` |
 | `src/anolisa/` | `anolisa` |
 | `src/skillfs/` | `skillfs` |
+| `src/ktuner/` | `ktuner` |
 | `.github/workflows/` | `ci` |
 | `docs/` | `docs` |
 | `**/package*.json`, `Cargo.lock`, `*.toml` (dep bumps) | `deps` |

README.md

@@ -19,6 +19,7 @@ system built for AI Agent workloads.
 | [Agent Memory](src/agent-memory/) | CMA-style persistent filesystem memory for AI agents, served over MCP — sandboxed file tools, SQLite FTS5 BM25 index, optional git versioning and tar.gz snapshots. Linux only. |
 | [OS Skills](src/os-skills/) | Curated skill library for system administration, monitoring, security, DevOps, and cloud integration. |
 | [SkillFS](src/skillfs/) | FUSE-backed virtual filesystem for local agent skills and view-based `SKILL.md` exposure. Linux only. |
+| [ktuner](src/ktuner/) | Deterministic kernel-tuning engine for AI agents — evaluates 207 rules against the running system and outputs structured JSON tuning recommendations. Linux only. |
 
 See each component's README for detailed documentation.
 

docs/user-guide/en/README.md

@@ -37,6 +37,7 @@ ANOLISA provides a complete server-side runtime for AI Agent workloads. Componen
 | [anolisa CLI](user-entrypoint/anolisa-cli.md) | anolisa | Unified CLI for component management |
 | [Copilot Shell](user-entrypoint/copilot-shell.md) | cosh | AI terminal assistant and command gateway |
 | [OS Skills](user-entrypoint/os-skills.md) | os-skills | System management and DevOps skills |
+| [ktuner](user-entrypoint/ktuner.md) | ktuner | Deterministic kernel-parameter tuning engine |
 
 ### Agent Observability (`agent-observability/`)
 

docs/user-guide/en/user-entrypoint/ktuner.md

@@ -0,0 +1,93 @@
+# ktuner
+
+ktuner is a deterministic kernel-tuning engine for AI agents. It evaluates 207 rules against the running system and outputs structured JSON recommendations, so an agent (or a human) can diagnose, apply, and roll back kernel parameter changes safely.
+
+---
+
+## Overview
+
+ktuner is a rule engine, not an LLM: every recommendation comes from a hard-coded rule reading `/proc/sys` and `/sys`, so results are reproducible and explainable. It covers network, memory, I/O, CPU, and security parameters, scores the current system, and predicts the score after tuning.
+
+It is designed to be driven by cosh and other ANOLISA-compatible agents as a tool, but the CLI is equally usable by hand.
+
+---
+
+## Installation
+
+ktuner ships with the ANOLISA source tree under `src/ktuner/`. Build it from source:
+
+```bash
+cd src/ktuner
+cargo build --release
+# binary at target/release/ktuner
+```
+
+Add `target/release/` to your `PATH`, or run the binary directly as `./target/release/ktuner` — the examples below assume `ktuner` is on your `PATH`.
+
+> Packaged distribution (`anolisa install ktuner` / RPM) is still being planned with the maintainers; until then, build from source.
+
+---
+
+## Quick Start
+
+```bash
+# Diagnose — read-only, no root required
+ktuner check                   # score + all recommendations
+ktuner check --category net    # limit to one category
+ktuner check --conservative    # high-confidence recommendations only
+
+# Preview changes without applying (dry-run)
+sudo ktuner tune --dry-run
+
+# Apply recommendations (requires root)
+sudo ktuner tune               # apply all
+sudo ktuner tune --conservative
+
+# Fix a single parameter
+sudo ktuner fix vm.swappiness
+
+# Explain why a parameter should change
+ktuner why net.core.somaxconn
+
+# Undo all changes ktuner made
+sudo ktuner rollback
+```
+
+All output is JSON on stdout; errors are JSON on stderr. Exit codes: `0` success, `1` check found recommendations (not an error), `2` error.
+
+---
+
+## Permission Boundary
+
+| Command | Root | Effect |
+|---------|------|--------|
+| `check`, `why` | No | Read-only diagnosis; never writes the kernel |
+| `tune --dry-run` | No | Previews changes, writes nothing |
+| `tune`, `fix`, `rollback` | Yes (`sudo`) | Writes `/proc/sys`; refuses to run if not root |
+
+Safety guarantees:
+
+- **Code-execution deny-list**: parameters that can lead to code execution (`kernel.core_pattern`, `kernel.modprobe`, `kernel.hotplug`, and similar) are unconditionally blocked from every write path. Matching is on the resolved filesystem path, so spelling variants cannot bypass it.
+- **Rollback safety**: applied changes are recorded; a partial rollback failure never discards the remaining original values.
+- **No autonomous root**: ktuner errors out unless run as root. When invoked through cosh, the sandbox guard and permission prompt ensure a human approves before any `sudo ktuner tune` runs.
+
+---
+
+## Usage with cosh
+
+cosh discovers ktuner automatically via its skill definition (`src/os-skills/system-admin/ktuner/`), so no wiring is needed — ask in natural language:
+
+```
+> "Check whether this machine's kernel parameters can be improved"
+> "Optimize the kernel for a database workload"
+```
+
+A cosh first-run auto-check — a one-line `ktuner check` report shown at initial login — is landing in a separate PR. Until then, invoke `ktuner check` through the skill as above. cosh never applies changes on its own.
+
+---
+
+## See Also
+
+- [Copilot Shell](copilot-shell/QUICKSTART.md)
+- [OS Skills](os-skills.md)
+- Full reference: `src/ktuner/README.md`

docs/user-guide/zh/README.md

@@ -37,6 +37,7 @@ ANOLISA 为 AI Agent 提供完整的服务端运行时能力。通过 `anolisa`
 | [anolisa CLI](user-entrypoint/anolisa-cli.md) | anolisa | 统一 CLI 组件管理 |
 | [Copilot Shell](user-entrypoint/copilot-shell.md) | cosh | AI 终端助手与命令网关 |
 | [OS 技能库](user-entrypoint/os-skills.md) | os-skills | 系统管理与 DevOps 技能 |
+| [ktuner](user-entrypoint/ktuner.md) | ktuner | 确定性内核参数调优引擎 |
 
 ### 可观测性 `agent-observability/`
 

docs/user-guide/zh/user-entrypoint/ktuner.md

@@ -0,0 +1,93 @@
+# ktuner
+
+ktuner 是面向 AI Agent 的确定性内核调优引擎。它对运行中的系统评估 207 条规则，输出结构化 JSON 建议，让 Agent（或用户）能安全地诊断、应用、回滚内核参数改动。
+
+---
+
+## 概述
+
+ktuner 是规则引擎，不是 LLM：每条建议都来自读取 `/proc/sys` 和 `/sys` 的硬编码规则，因此结果可复现、可解释。它覆盖网络、内存、I/O、CPU、安全类参数，对当前系统打分，并预测调优后的分数。
+
+它设计为被 cosh 及其他 ANOLISA 兼容 Agent 作为工具调用，但命令行同样可以手动使用。
+
+---
+
+## 安装
+
+ktuner 随 ANOLISA 源码树发布，位于 `src/ktuner/`。从源码构建：
+
+```bash
+cd src/ktuner
+cargo build --release
+# 二进制在 target/release/ktuner
+```
+
+将 `target/release/` 加入 `PATH`，或直接运行 `./target/release/ktuner`——下面的示例假设 `ktuner` 已在 `PATH` 中。
+
+> 打包分发方式（`anolisa install ktuner` / RPM）仍在与维护者规划中；在此之前请从源码构建。
+
+---
+
+## 快速开始
+
+```bash
+# 诊断 —— 只读，无需 root
+ktuner check                   # 分数 + 所有建议
+ktuner check --category net    # 仅某一类别
+ktuner check --conservative    # 仅高置信度建议
+
+# 预览改动但不应用（dry-run）
+sudo ktuner tune --dry-run
+
+# 应用建议（需要 root）
+sudo ktuner tune               # 应用全部
+sudo ktuner tune --conservative
+
+# 修复单个参数
+sudo ktuner fix vm.swappiness
+
+# 解释某个参数为何应该改
+ktuner why net.core.somaxconn
+
+# 撤销 ktuner 做的所有改动
+sudo ktuner rollback
+```
+
+所有输出为 stdout 上的 JSON，错误为 stderr 上的 JSON。退出码：`0` 成功、`1` check 发现可改进项（非错误）、`2` 错误。
+
+---
+
+## 权限边界
+
+| 命令 | Root | 作用 |
+|------|------|------|
+| `check`、`why` | 否 | 只读诊断；绝不写内核 |
+| `tune --dry-run` | 否 | 预览改动，不写入 |
+| `tune`、`fix`、`rollback` | 是（`sudo`） | 写 `/proc/sys`；非 root 直接报错 |
+
+安全保证：
+
+- **代码执行 deny-list**：可能导致代码执行的参数（`kernel.core_pattern`、`kernel.modprobe`、`kernel.hotplug` 等）在所有写入路径上被无条件阻止。匹配基于解析后的文件系统路径，因此拼写变体无法绕过。
+- **回滚安全**：已应用的改动会被记录；部分回滚失败时绝不丢弃其余参数的原始值。
+- **无自主 root**：ktuner 非 root 运行时一律报错。通过 cosh 调用时，沙箱守卫与权限提示确保任何 `sudo ktuner tune` 都经人工批准才执行。
+
+---
+
+## 配合 cosh 使用
+
+cosh 通过 skill 定义（`src/os-skills/system-admin/ktuner/`）自动发现 ktuner，无需接线——用自然语言提问即可：
+
+```
+> “看看这台机器的内核参数能不能优化”
+> “按数据库负载优化内核”
+```
+
+cosh 首次运行自动检查——首次登录时展示一行 `ktuner check` 报告——将在独立 PR 中落地。在此之前，请按上文通过 skill 调用 `ktuner check`。cosh 绝不自行应用改动。
+
+---
+
+## 参见
+
+- [Copilot Shell](copilot-shell/QUICKSTART.md)
+- [OS Skills](os-skills.md)
+- 完整参考：`src/ktuner/README.md`

src/ktuner/.gitignore

@@ -0,0 +1 @@
+/target/