luckerr 0.41.0

package/README.md

@@ -0,0 +1,267 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="Luckerr" width="640"/>
+</p>
+
+<p align="center">
+  <strong>English</strong>
+  &nbsp;·&nbsp;
+  <a href="./README.zh-CN.md">简体中文</a>
+  &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/DeepSeek-Luckerr/">Website</a>
+  &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/DeepSeek-Luckerr/configuration.html">Guide</a>
+  &nbsp;·&nbsp;
+  <a href="./docs/ARCHITECTURE.md">Architecture</a>
+  &nbsp;·&nbsp;
+  <a href="./benchmarks/">Benchmarks</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/luckerr"><img src="https://img.shields.io/npm/v/luckerr.svg?style=flat-square&color=cb3837&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
+  <a href="https://github.com/esengine/luckerr/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esengine/luckerr/ci.yml?style=flat-square&label=ci&labelColor=161b22&logo=githubactions&logoColor=white" alt="CI"/></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/luckerr.svg?style=flat-square&color=8b949e&labelColor=161b22" alt="license"/></a>
+  <a href="https://www.npmjs.com/package/luckerr"><img src="https://img.shields.io/npm/dm/luckerr.svg?style=flat-square&color=3fb950&labelColor=161b22&label=downloads" alt="downloads"/></a>
+  <a href="./package.json"><img src="https://img.shields.io/node/v/luckerr.svg?style=flat-square&color=5fa04e&labelColor=161b22&logo=nodedotjs&logoColor=white" alt="node"/></a>
+  <a href="https://github.com/esengine/luckerr/stargazers"><img src="https://img.shields.io/github/stars/esengine/luckerr.svg?style=flat-square&color=dbab09&labelColor=161b22&logo=github&logoColor=white" alt="GitHub stars"/></a>
+  <a href="https://github.com/esengine/luckerr/graphs/contributors"><img src="https://img.shields.io/github/contributors/esengine/luckerr.svg?style=flat-square&color=bc8cff&labelColor=161b22&logo=github&logoColor=white" alt="contributors"/></a>
+  <a href="https://github.com/esengine/luckerr/discussions"><img src="https://img.shields.io/github/discussions/esengine/luckerr.svg?style=flat-square&color=58a6ff&labelColor=161b22&logo=github&logoColor=white" alt="Discussions"/></a>
+</p>
+
+<p align="center">
+  <a href="https://oosmetrics.com/repo/esengine/luckerr"><img src="https://api.oosmetrics.com/api/v1/badge/achievement/9e931d80-2050-4b10-902e-44970cc133ad.svg" alt="oosmetrics — Top 2 in Agents by velocity"/></a>
+  <a href="https://oosmetrics.com/repo/esengine/luckerr"><img src="https://api.oosmetrics.com/api/v1/badge/achievement/556d94b3-61b7-486b-baf2-888b9327deab.svg" alt="oosmetrics — Top 3 in LLMs by velocity"/></a>
+  <a href="https://oosmetrics.com/repo/esengine/luckerr"><img src="https://api.oosmetrics.com/api/v1/badge/achievement/0f457d4c-efca-4d15-ad2b-139691ff342c.svg" alt="oosmetrics — Top 3 in CLI by velocity"/></a>
+</p>
+
+<br/>
+
+<h3 align="center">A DeepSeek-native AI coding agent for your terminal.</h3>
+<p align="center">Engineered around prefix-cache stability — so token costs stay low across long sessions, and you can leave it running.</p>
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/hero-terminal.svg" alt="Luckerr code mode — assistant proposes a SEARCH/REPLACE edit; nothing on disk until /apply" width="860"/>
+</p>
+
+<br/>
+
+> [!TIP]
+> **Cache stability isn't a feature you turn on; it's an invariant the loop is designed around.** That's the whole reason Luckerr is DeepSeek-only — every layer is tuned to the byte-stable prefix-cache mechanic.
+
+> [!NOTE]
+> **Real user, single day (2026-05-01):** 435M input tokens, **99.82% cache hit**, ~$12 instead of the ~$61 the same workload would cost with no cache on `v4-flash` — see the [case study](./benchmarks/real-world-cache/README.md). DeepSeek provides the cacheable bytes; the four mechanisms in [Pillar 1](./docs/ARCHITECTURE.md#pillar-1--cache-first-loop) are how Luckerr keeps them cacheable across long sessions.
+
+<br/>
+
+## Install
+
+Requires Node ≥ 22. Works on macOS · Linux · Windows (PowerShell · Git Bash · Windows Terminal).
+
+Install Luckerr globally if you want the `luckerr` command available on your `PATH`:
+
+```bash
+npm install -g luckerr
+luckerr code my-project   # paste a DeepSeek API key on first run; persists after
+```
+
+Or run it once without installing globally:
+
+```bash
+cd my-project
+npx luckerr code          # always uses the latest package by default
+```
+
+Grab a [DeepSeek API key →](https://platform.deepseek.com/api_keys) · `luckerr code --help` for flags.
+
+If you use Luckerr daily, global install is the simplest path. If you just want to try it, use `npx`.
+
+| Command | When |
+|---|---|
+| `luckerr code [dir]` | The coding agent. **Start here.** |
+| `luckerr chat` | Plain chat — no filesystem or shell tools. |
+| `luckerr run "task"` | One-shot, streams to stdout. Good for pipes. |
+| `luckerr doctor` | Health check: Node, API key, MCP wiring. |
+| `luckerr update` | Upgrade Luckerr itself. |
+
+Other subcommands (`replay` · `diff` · `events` · `stats` · `index` · `mcp` · `prune-sessions`) are in `luckerr --help` and the [CLI reference](https://esengine.github.io/DeepSeek-Luckerr/#cli).
+
+### Desktop client (prerelease)
+
+A native Tauri client for users who want a GUI over the same loop. Multi-tab, the right-panel shows files the agent has read or edited this session, the same cost / cache / token meters live at the bottom. Same DeepSeek API key, same `~/.luckerr` config — the desktop bundles its own Node runtime, no separate `npm install` step.
+
+Download platform installers from [GitHub Releases](https://github.com/esengine/DeepSeek-Luckerr/releases). The desktop ships as a **prerelease**: the loop and protocol are the same as the CLI, but the UI is still being polished and the installers aren't code-signed yet.
+
+- **macOS** — first launch hits Gatekeeper. One-time fix: `xattr -dr com.apple.quarantine /Applications/Luckerr.app` (or right-click → Open → confirm).
+- **Windows** — SmartScreen warns "Unknown publisher". Click **More info → Run anyway**.
+- **Linux** — `.deb` and `.AppImage` ship plain, no extra step.
+
+The CLI remains the canonical surface. Anything that lands in the CLI is also available from the desktop's composer.
+
+<details>
+<summary><strong>Working in another folder · chat vs. code · author a skill</strong></summary>
+
+**Working in a different folder.** Luckerr scopes filesystem tools to the launch directory; pass `--dir` to retarget. Mid-session switching isn't supported by design (memory paths would tangle with stale roots) — quit and relaunch.
+
+```bash
+npx luckerr code --dir /path/to/project
+```
+
+**Picking `chat` vs `code`.** `code` is the default and the only mode with filesystem / shell tools and SEARCH/REPLACE review. `chat` is the lighter, tools-off shell — reach for it when you want a thinking partner with MCP attached but no disk access.
+
+| What you get | `code` | `chat` |
+|---|---|---|
+| Filesystem tools + `edit_file` | ✓ | — |
+| SEARCH/REPLACE → `/apply` review | ✓ | — |
+| Shell tool (gated) | ✓ | — |
+| Plan mode · `/todo` · `/skill new` · `/mcp add` | ✓ | — |
+| Memory (`remember` / `recall_memory`) | project + global | global only |
+| MCP servers from config · web search · `ask_choice` | ✓ | ✓ |
+| Coding system prompt | ✓ | generic |
+| Session scope | per-directory | shared default |
+
+**Author your first skill.** No remote registry — write them directly. Edit the file (`description:` frontmatter + body), then `/skill list`. Add `runAs: subagent` to spawn an isolated subagent loop instead of inlining the body.
+
+```bash
+/skill new my-skill              # <project>/.luckerr/skills/my-skill.md
+/skill new my-skill --global     # ~/.luckerr/skills for cross-project use
+```
+
+</details>
+
+<br/>
+
+## Configuration
+
+One JSON file at `~/.luckerr/config.json` plus per-project overrides under `<project>/.luckerr/`. The full bilingual reference — every key, every slash command, the on-disk shape of skills/memory/hooks — lives at:
+
+> 📘 **[Configuration Guide](https://esengine.github.io/DeepSeek-Luckerr/configuration.html)** · [中文](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh)
+
+| Topic | Quick read |
+|---|---|
+| [MCP servers](https://esengine.github.io/DeepSeek-Luckerr/configuration.html#mcp) | stdio · SSE · Streamable HTTP. One spec format works for both `config.json` and `--mcp`. |
+| [Skills](https://esengine.github.io/DeepSeek-Luckerr/configuration.html#skills) | Markdown playbooks the model can invoke. `inline` or `subagent` mode. |
+| [Memory](https://esengine.github.io/DeepSeek-Luckerr/configuration.html#memory) | User-private knowledge pinned into the prefix. `user` / `feedback` / `project` / `reference` types. |
+| [Hooks](https://esengine.github.io/DeepSeek-Luckerr/configuration.html#hooks) | Shell commands on lifecycle events. `PreToolUse` (gating) · `PostToolUse` · `UserPromptSubmit` · `Stop`. |
+| [Permissions](https://esengine.github.io/DeepSeek-Luckerr/configuration.html#permissions) | Per-workspace shell allowlist. Exact-prefix match. |
+| [Web search](https://esengine.github.io/DeepSeek-Luckerr/configuration.html#search) | Mojeek by default; switch to self-hosted SearXNG with `/search-engine`. |
+| [Semantic index](https://esengine.github.io/DeepSeek-Luckerr/configuration.html#index) | `luckerr index` — local Ollama or any OpenAI-compatible embedding endpoint. |
+
+> **Model & preset persistence:** your last model or preset choice (via `/model`, `/preset`, or the model picker) is saved to `config.json` and restored on relaunch. `--model` / `--preset` CLI flags still override for one-off runs.
+
+<br/>
+
+## What makes Luckerr different
+
+The loop is organized around three pillars. Each one solves a problem generic agent frameworks don't even see — because they were designed for a different cache mechanic.
+
+<sub align="center">
+
+Click through to the full architecture writeup → [Pillar 1 — Cache-first loop](./docs/ARCHITECTURE.md#pillar-1--cache-first-loop) · [Pillar 2 — Tool-call repair](./docs/ARCHITECTURE.md#pillar-2--tool-call-repair) · [Pillar 3 — Cost control](./docs/ARCHITECTURE.md#pillar-3--cost-control-v06)
+
+</sub>
+
+<br/>
+
+## Capabilities
+
+<p align="center">
+  <img src="docs/assets/feature-grid.svg" alt="Luckerr capabilities — cell-diff renderer, MCP, plan mode, permissions, dashboard, persistent sessions, hooks/skills/memory, semantic search, auto-checkpoints, /effort knob, transcript replay, event log" width="880"/>
+</p>
+
+<br/>
+
+## How it compares
+
+|                                   | Luckerr         | Claude Code       | Cursor              | Aider              |
+|-----------------------------------|------------------|-------------------|---------------------|--------------------|
+| Backend                           | DeepSeek         | Anthropic         | OpenAI / Anthropic  | any (OpenRouter)   |
+| License                           | **MIT**          | closed            | closed              | Apache 2           |
+| Cost profile                      | **low per task** | premium           | subscription + use  | varies             |
+| DeepSeek prefix-cache             | **engineered**   | not applicable    | not applicable      | incidental         |
+| Embedded web dashboard            | yes              | —                 | n/a (IDE)           | —                  |
+| Configurable web search engine    | `/search-engine` | —             | —                   | —                  |
+| Persistent per-workspace sessions | yes              | partial           | n/a                 | —                  |
+| Plan mode · MCP · hooks · skills  | yes              | yes               | yes                 | partial            |
+| Web search (Mojeek + SearXNG)      | yes              | yes               | yes                 | yes                |
+| Open community development        | yes              | —                 | —                   | yes                |
+
+For live cache-hit rates, costs, and methodology, see [`benchmarks/`](./benchmarks/) — the numbers move with model pricing, so they live with the harness, not in the README.
+
+<br/>
+
+## Documentation
+
+- [**Architecture**](./docs/ARCHITECTURE.md) — three pillars: cache-first loop, tool-call repair, cost control
+- [**CLI Reference**](./docs/CLI-REFERENCE.md) — every shell subcommand, every slash command, every keybinding
+- [**Benchmarks**](./benchmarks/) — τ-bench-lite harness, transcripts, cost methodology
+- [**Website**](https://esengine.github.io/DeepSeek-Luckerr/) — getting started, dashboard mockup, TUI mockup
+- [**Contributing**](./CONTRIBUTING.md) — comment policy, error-handling rules, library-over-hand-rolled
+- [**Code of Conduct**](./CODE_OF_CONDUCT.md) · [**Security policy**](./SECURITY.md)
+
+<br/>
+
+## Community
+
+> [!NOTE]
+> Luckerr is open source and community-developed. The contributors wall below isn't decoration — every avatar is a real PR that shipped.
+
+Scoped starter tickets — each with background, code pointers, acceptance criteria, and hints — live under the [`good first issue`](https://github.com/esengine/luckerr/labels/good%20first%20issue) label. Pick anything open.
+
+**Open Discussions — opinions wanted:**
+
+- [#20 · CLI / TUI design](https://github.com/esengine/luckerr/discussions/20) — what's broken, what's missing, what would you change?
+- [#21 · Dashboard design](https://github.com/esengine/luckerr/discussions/21) — react against the [proposed mockup](https://esengine.github.io/DeepSeek-Luckerr/design/agent-dashboard.html)
+- [#22 · Future feature wishlist](https://github.com/esengine/luckerr/discussions/22) — what would you build into Luckerr next?
+
+**Already using Luckerr and willing to help others discover it?** Publish blog posts, articles, screenshots, talks, or videos to [**Show and tell**](https://github.com/esengine/luckerr/discussions/categories/show-and-tell). The project has no marketing budget — community word of mouth is how new users find it. Sustained advocates earn the badge below, displayed next to the contributors wall once awarded:
+
+<p align="center">
+  <a href="https://github.com/esengine/luckerr/discussions/categories/show-and-tell">
+    <img src="https://img.shields.io/badge/LUCKERR-📣%20ADVOCATE-c4b5fd?style=for-the-badge&labelColor=0d1117" alt="Luckerr Advocate badge — earned by sustained advocates"/>
+  </a>
+</p>
+
+**Before your first PR**: read [`CONTRIBUTING.md`](./CONTRIBUTING.md) — short, strict rules (comments, errors, libraries-over-hand-rolled). `tests/comment-policy.test.ts` enforces the comment ones; `npm run verify` is the pre-push gate. By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). Security issues → [SECURITY.md](./SECURITY.md).
+
+<p align="center">
+  <a href="https://github.com/esengine/luckerr/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=esengine/DeepSeek-Luckerr&max=100&columns=12" alt="Contributors to esengine/DeepSeek-Luckerr" width="860"/>
+  </a>
+</p>
+
+<br/>
+
+## Non-goals
+
+> [!IMPORTANT]
+> Luckerr is opinionated. Some things it deliberately *doesn't* do — listed here so you can pick the right tool for your work.
+
+- **Multi-provider flexibility.** DeepSeek-only on purpose. Coupling to one backend is the feature, not a limitation.
+- **IDE integration.** Terminal-first. The diff lives in `git diff`, the file tree in `ls`. The dashboard is a companion, not a Cursor replacement.
+- **Hardest-leaderboard reasoning.** Claude Opus still wins some benchmarks. DeepSeek is competitive on coding; if your work is "solve this PhD proof" rather than "fix this auth bug," start with Claude.
+- **Air-gapped / fully-free.** Luckerr needs a paid DeepSeek API key. For air-gapped or zero-cost runs see Aider + Ollama or [Continue](https://continue.dev).
+
+<br/>
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=esengine%2FDeepSeek-Luckerr&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=esengine/DeepSeek-Luckerr&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=esengine/DeepSeek-Luckerr&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=esengine/DeepSeek-Luckerr&type=date&legend=top-left" />
+ </picture>
+</a>
+
+<br/>
+
+---
+
+<p align="center">
+  <sub>MIT — see <a href="./LICENSE">LICENSE</a></sub>
+  <br/>
+  <sub>Built by the community at <a href="https://github.com/esengine/luckerr/graphs/contributors">esengine/luckerr</a></sub>
+  <br/>
+  <sub>Special thanks to <a href="https://xhslink.com/m/80ngts127cA">AIGC Link</a> for the promotions on XiaoHongShu.</sub>
+</p>

package/README.zh-CN.md

@@ -0,0 +1,237 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="Luckerr" width="640"/>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a>
+  &nbsp;·&nbsp;
+  <strong>简体中文</strong>
+  &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/DeepSeek-Luckerr/">官方网站</a>
+  &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh">配置指南</a>
+  &nbsp;·&nbsp;
+  <a href="./docs/ARCHITECTURE.md">架构文档</a>
+  &nbsp;·&nbsp;
+  <a href="./benchmarks/">基准测试</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/luckerr"><img src="https://img.shields.io/npm/v/luckerr.svg?style=flat-square&color=cb3837&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
+  <a href="https://github.com/esengine/luckerr/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esengine/luckerr/ci.yml?style=flat-square&label=ci&labelColor=161b22&logo=githubactions&logoColor=white" alt="CI"/></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/luckerr.svg?style=flat-square&color=8b949e&labelColor=161b22" alt="license"/></a>
+  <a href="https://www.npmjs.com/package/luckerr"><img src="https://img.shields.io/npm/dm/luckerr.svg?style=flat-square&color=3fb950&labelColor=161b22&label=downloads" alt="downloads"/></a>
+  <a href="./package.json"><img src="https://img.shields.io/node/v/luckerr.svg?style=flat-square&color=5fa04e&labelColor=161b22&logo=nodedotjs&logoColor=white" alt="node"/></a>
+  <a href="https://github.com/esengine/luckerr/stargazers"><img src="https://img.shields.io/github/stars/esengine/luckerr.svg?style=flat-square&color=dbab09&labelColor=161b22&logo=github&logoColor=white" alt="GitHub stars"/></a>
+  <a href="https://github.com/esengine/luckerr/graphs/contributors"><img src="https://img.shields.io/github/contributors/esengine/luckerr.svg?style=flat-square&color=bc8cff&labelColor=161b22&logo=github&logoColor=white" alt="contributors"/></a>
+  <a href="https://github.com/esengine/luckerr/discussions"><img src="https://img.shields.io/github/discussions/esengine/luckerr.svg?style=flat-square&color=58a6ff&labelColor=161b22&logo=github&logoColor=white" alt="Discussions"/></a>
+</p>
+
+<p align="center">
+  <a href="https://oosmetrics.com/repo/esengine/luckerr"><img src="https://api.oosmetrics.com/api/v1/badge/achievement/9e931d80-2050-4b10-902e-44970cc133ad.svg" alt="oosmetrics — Agents 速度榜 Top 2"/></a>
+  <a href="https://oosmetrics.com/repo/esengine/luckerr"><img src="https://api.oosmetrics.com/api/v1/badge/achievement/556d94b3-61b7-486b-baf2-888b9327deab.svg" alt="oosmetrics — LLMs 速度榜 Top 3"/></a>
+  <a href="https://oosmetrics.com/repo/esengine/luckerr"><img src="https://api.oosmetrics.com/api/v1/badge/achievement/0f457d4c-efca-4d15-ad2b-139691ff342c.svg" alt="oosmetrics — CLI 速度榜 Top 3"/></a>
+</p>
+
+<br/>
+
+<h3 align="center">DeepSeek 原生的终端 AI 编程代理。</h3>
+<p align="center">围绕前缀缓存稳定性设计 —— 长会话下 token 成本始终低位运行，可以一直开着。</p>
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/hero-terminal.zh-CN.svg" alt="Luckerr code 模式预览 — 助手提出 SEARCH/REPLACE 编辑，未 /apply 不落盘" width="860"/>
+</p>
+
+<br/>
+
+> [!TIP]
+> **缓存稳定不是开关，而是循环要围绕设计的不变量。** 这就是 Luckerr 只支持 DeepSeek 的根本原因 —— 每一层都为 DeepSeek 字节稳定的前缀缓存机制调过。
+
+<br/>
+
+## 安装
+
+```bash
+cd my-project
+npx luckerr code   # 首次运行粘贴 DeepSeek API Key，之后会记住
+```
+
+要求 Node ≥ 22。在 macOS · Linux · Windows（PowerShell · Git Bash · Windows Terminal）都跑得顺。[去拿 DeepSeek API Key →](https://platform.deepseek.com/api_keys) · 完整 flag 看 `luckerr code --help`。
+
+`npx` 是推荐路径 —— 不用全局安装，每次都拿最新版。如果你天天用、想把 `luckerr` 装到 `PATH`，跑一次 `luckerr update`。
+
+| 命令 | 何时用 |
+|---|---|
+| `luckerr code [dir]` | 编码 agent。**先用这个。** |
+| `luckerr chat` | 纯聊天 —— 不挂文件系统 / shell 工具。 |
+| `luckerr run "task"` | 一次性，结果流到 stdout。适合 shell 管道。 |
+| `luckerr doctor` | 体检：Node 版本、API Key、MCP 接线。 |
+| `luckerr update` | 升级 Luckerr 本身。 |
+
+其他子命令（`replay` · `diff` · `events` · `stats` · `index` · `mcp` · `prune-sessions`）在 `luckerr --help` 和 [CLI 参考](https://esengine.github.io/DeepSeek-Luckerr/#cli)。
+
+<details>
+<summary><strong>切换工作区 · chat vs. code · 写第一个 Skill</strong></summary>
+
+**切换工作区。** Luckerr 把文件系统工具作用域绑定在启动目录，传 `--dir` 可以指别处。中途切换是有意不支持的（消息日志和 memory 路径会和旧根目录混在一起）—— 退出再启动。
+
+```bash
+npx luckerr code --dir /path/to/project
+```
+
+**`chat` 还是 `code`？** `code` 是默认入口、唯一带文件系统 / shell 工具和 SEARCH/REPLACE 审阅的模式。`chat` 是更轻量的纯对话壳——想要一个挂着 MCP 但没有磁盘权限的“思路助手”时用它。
+
+| 你拿到什么 | `code` | `chat` |
+|---|---|---|
+| 文件系统工具 + `edit_file` | ✓ | — |
+| SEARCH/REPLACE → `/apply` 审阅 | ✓ | — |
+| Shell 工具（带 gate） | ✓ | — |
+| Plan 模式 · `/todo` · `/skill new` · `/mcp add` | ✓ | — |
+| Memory（`remember` / `recall_memory`） | 项目 + 全局 | 仅全局 |
+| 配置里的 MCP · web 搜索 · `ask_choice` | ✓ | ✓ |
+| 编码导向系统提示词 | ✓ | 通用 |
+| Session 作用域 | 按目录 | 共享默认 |
+
+**写第一个 Skill。** 暂无在线市场——自己写。编辑文件（`description:` frontmatter + 正文），然后 `/skill list` 就能看到。frontmatter 加 `runAs: subagent` 会以隔离 subagent 跑，而不是把正文内联进父 prompt。
+
+```bash
+/skill new my-skill              # <project>/.luckerr/skills/my-skill.md
+/skill new my-skill --global     # ~/.luckerr/skills，跨项目共用
+```
+
+</details>
+
+<br/>
+
+## 配置
+
+一个全局 JSON 文件 `~/.luckerr/config.json`，加上项目级 `<project>/.luckerr/` 下的覆盖。完整的双语参考 —— 每一个 key、每一条斜杠命令、skills / memory / hooks 在磁盘上的形状 —— 都在这里：
+
+> 📘 **[配置指南](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh)** · [English](https://esengine.github.io/DeepSeek-Luckerr/configuration.html)
+
+| 主题 | 速读 |
+|---|---|
+| [MCP 服务器](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh#mcp) | stdio · SSE · Streamable HTTP。`config.json` 和 `--mcp` 共用同一种 spec 格式。 |
+| [Skills](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh#skills) | 模型可以调用的 markdown 剧本。`inline` 或 `subagent` 两种模式。 |
+| [Memory](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh#memory) | 用户私有的知识，钉进前缀。`user` / `feedback` / `project` / `reference` 四类。 |
+| [Hooks](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh#hooks) | 生命周期事件触发的 shell 命令。`PreToolUse`（拦截）· `PostToolUse` · `UserPromptSubmit` · `Stop`。 |
+| [权限](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh#permissions) | 按工作区的 shell 白名单，精确前缀匹配。 |
+| [Web 搜索](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh#search) | 默认 Mojeek；用 `/search-engine` 可切到自托管的 SearXNG。 |
+| [语义索引](https://esengine.github.io/DeepSeek-Luckerr/configuration.html?lang=zh#index) | `luckerr index` —— 本地 Ollama，或任何 OpenAI 兼容的 embedding 接口。 |
+
+> **模型与预设持久化：** 你上一次选择的模型或预设（通过 `/model`、`/preset` 或模型选择器）会保存到 `config.json`，重启后自动恢复。`--model` / `--preset` 命令行参数仍然可以覆盖，用于一次性运行。
+
+<br/>
+
+## Luckerr 的不同之处
+
+整个循环围绕三根支柱组织。每一根解决的都是通用 agent 框架根本看不见的问题 —— 因为它们是为另一种缓存机制设计的。
+
+<sub align="center">
+
+各支柱完整说明 → [Pillar 1 — 缓存优先循环](./docs/ARCHITECTURE.md#pillar-1--cache-first-loop) · [Pillar 2 — 工具调用修复](./docs/ARCHITECTURE.md#pillar-2--tool-call-repair) · [Pillar 3 — 成本控制](./docs/ARCHITECTURE.md#pillar-3--cost-control-v06)
+
+</sub>
+
+<br/>
+
+## 能力一览
+
+<p align="center">
+  <img src="docs/assets/feature-grid.zh-CN.svg" alt="Luckerr 能力一览 — cell-diff 渲染器、MCP、计划模式、权限、仪表盘、持久化会话、Hooks/Skills/Memory、语义检索、自动 checkpoint、/effort 旋钮、transcript 重放、事件日志" width="880"/>
+</p>
+
+<br/>
+
+## 横向对比
+
+|                            | Luckerr          | Claude Code       | Cursor              | Aider              |
+|----------------------------|-------------------|-------------------|---------------------|--------------------|
+| 后端                       | DeepSeek          | Anthropic         | OpenAI / Anthropic  | 任意（OpenRouter） |
+| 协议                       | **MIT**           | 闭源              | 闭源                | Apache 2           |
+| 单任务成本                 | **低**            | 高                | 订阅 + 用量         | 不一               |
+| DeepSeek 前缀缓存          | **专门工程化**    | 不适用            | 不适用              | 偶发命中           |
+| 内嵌 web 仪表盘            | 支持              | —                 | 不适用 (IDE)        | —                  |
+| 持久化的工作区会话         | 支持              | 部分              | 不适用              | —                  |
+| 计划模式 · MCP · Hooks     | 支持              | 支持              | 支持                | 部分               |
+| 开放社区共建               | 支持              | —                 | —                   | 支持               |
+
+实测缓存命中率、成本、方法论看 [`benchmarks/`](./benchmarks/) —— 这些数会随模型定价变化，所以归在 harness 里，不进 README。
+
+<br/>
+
+## 文档
+
+- [**架构**](./docs/ARCHITECTURE.md) —— 四大支柱、缓存优先循环、思维提取、脚手架
+- [**CLI 参考**](./docs/CLI-REFERENCE.md) —— 每个 shell 子命令、每个 slash 命令、每个快捷键
+- [**基准测试**](./benchmarks/) —— τ-bench-lite harness、transcript、成本方法论
+- [**官方网站**](https://esengine.github.io/DeepSeek-Luckerr/) —— 入门、Dashboard 设计稿、TUI 设计稿
+- [**贡献指南**](./CONTRIBUTING.md) —— 注释规则、错误处理、用现成库不手写
+- [**行为准则**](./CODE_OF_CONDUCT.md) · [**安全策略**](./SECURITY.md)
+
+<br/>
+
+## 社区
+
+> [!NOTE]
+> Luckerr 是开源、社区共建的项目。下面贡献者墙不是装饰 —— 每一个头像都对应一次真实合并的 PR。
+
+给新手准备的入门 issue —— 每个都带背景说明、代码定位、验收标准、提示 —— 全部挂在 [`good first issue`](https://github.com/esengine/luckerr/labels/good%20first%20issue) 标签下。挑任意一个还没人认领的就行。
+
+**正在征集意见的 Discussions：**
+
+- [#20 · CLI / TUI 设计](https://github.com/esengine/luckerr/discussions/20) —— 哪里坏了、哪里少东西、哪里你会怎么改？
+- [#21 · Dashboard 设计](https://github.com/esengine/luckerr/discussions/21) —— 对着[设计稿](https://esengine.github.io/DeepSeek-Luckerr/design/agent-dashboard.html)拍砖
+- [#22 · 未来功能愿望单](https://github.com/esengine/luckerr/discussions/22) —— 你希望 Luckerr 长出什么功能？
+
+**正在使用 Luckerr，愿意让更多人了解它？** 欢迎将相关博客、文章、截图、演讲或视频发布到 [**Show and tell**](https://github.com/esengine/luckerr/discussions/categories/show-and-tell)。项目没有营销预算，新用户主要通过社区口碑找到这里。持续参与传播的用户将获得下方这枚徽章，颁发后会展示在贡献者墙旁：
+
+<p align="center">
+  <a href="https://github.com/esengine/luckerr/discussions/categories/show-and-tell">
+    <img src="https://img.shields.io/badge/LUCKERR-📣%20ADVOCATE-c4b5fd?style=for-the-badge&labelColor=0d1117" alt="Luckerr Advocate 徽章 —— 授予持续参与传播的用户"/>
+  </a>
+</p>
+
+**第一次提 PR 之前**：先读 [`CONTRIBUTING.md`](./CONTRIBUTING.md) —— 短小、严格的项目规则（注释、错误处理、用现成库不手写）。`tests/comment-policy.test.ts` 静态强制执行注释那部分，`npm run verify` 是 push 前的闸。参与本项目即同意 [行为准则](./CODE_OF_CONDUCT.md)。安全相关问题请走 [SECURITY.md](./SECURITY.md)。
+
+<p align="center">
+  <a href="https://github.com/esengine/luckerr/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=esengine/DeepSeek-Luckerr&max=100&columns=12" alt="esengine/DeepSeek-Luckerr 贡献者" width="860"/>
+  </a>
+</p>
+
+<br/>
+
+## 不做的事
+
+> [!IMPORTANT]
+> Luckerr 是有立场的。有些事它故意 *不做* —— 列在这里方便你为自己的工作挑对工具。
+
+- **多供应商灵活性。** 故意只做 DeepSeek。绑死一个后端是 feature，不是限制。
+- **IDE 集成。** 终端优先。diff 在 `git diff`，文件树在 `ls`。仪表盘是 TUI 的伴生，不是 Cursor 的替代。
+- **追最难的 reasoning 榜单。** Claude Opus 在某些榜单上还是赢家。DeepSeek 在编程任务上有竞争力；如果你的工作是"解一个 PhD 级证明"而不是"修个 auth bug"，先用 Claude。
+- **完全离线 / 永远免费。** Luckerr 需要付费的 DeepSeek API Key。要离线 / 零成本，看 Aider + Ollama 或 [Continue](https://continue.dev)。
+
+<br/>
+
+## Star 趋势
+
+<a href="https://www.star-history.com/?repos=esengine%2FDeepSeek-Luckerr&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=esengine/DeepSeek-Luckerr&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=esengine/DeepSeek-Luckerr&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=esengine/DeepSeek-Luckerr&type=date&legend=top-left" />
+ </picture>
+</a>
+
+<br/>
+
+---
+
+<p align="center">
+  <sub>MIT —— 见 <a href="./LICENSE">LICENSE</a></sub>
+  <br/>
+  <sub>由 <a href="https://github.com/esengine/luckerr/graphs/contributors">esengine/luckerr</a> 社区共建</sub>
+</p>