docs: make Chinese README the default

README.md

@@ -1,14 +1,20 @@
+<!-- WEHUB_ZH_README -->
+> [!NOTE]
+> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
+> [English](./README.en.md) · [原始项目](https://github.com/OthmanAdi/planning-with-files) · [上游 README](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/README.md)  
+> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
+
 <div align="center">
 <img src="media/v3-banner.png" alt="planning-with-files" width="100%">
 </div>
 
 # Planning with Files
 
-> 📣 **New in [v3.0.0](https://github.com/OthmanAdi/planning-with-files/releases/tag/v3.0.0):** opt-in autonomous and gated modes for long-running agent runs, with a completion gate that holds the agent until the plan is actually done. Existing setups change nothing.
+> 📣 **[v3.0.0](https://github.com/OthmanAdi/planning-with-files/releases/tag/v3.0.0):** 新增**：为长时间运行的 agent 提供可选的自主模式与门控模式，并配有完成门控，在计划真正完成前会拦住 agent。现有配置无需任何改动。
 
-> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
+> **像 Manus 一样工作** — 这家 AI agent 公司已被 Meta 以 **20 亿美元** 收购。
 >
-> **planning-with-files** is a persistent file-based planning skill for **AI coding agents**. It keeps `task_plan.md`, `findings.md`, and `progress.md` on disk so the agent survives **context loss**, `/clear`, and crashes, with an opt-in completion gate that holds the agent until the plan is actually done. It installs across 60+ agents via the SKILL.md standard.
+> **planning-with-files** 是面向 **AI coding agents** 的持久化、基于文件的规划 skill。它将 `task_plan.md`、`findings.md` 和 `progress.md` 保存在磁盘上，使 agent 能够在 **上下文丢失**、`/clear` 和崩溃后继续工作，并提供可选的完成门控，在计划真正完成前会拦住 agent。通过 SKILL.md 标准可安装到 60+ 个 agent 上。
 
 [![Benchmark](https://img.shields.io/badge/Benchmark-96.7%25_pass_rate_(v2.21.0%2C_sonnet--4--6)-brightgreen)](docs/evals.md)
 [![A/B Verified](https://img.shields.io/badge/A%2FB_Blind-3%2F3_wins-brightgreen)](docs/evals.md)
@@ -24,128 +30,128 @@
 [![Closed PRs](https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed)
 
 <details>
-<summary><strong>💬 A Note from the Author</strong></summary>
+<summary><strong>💬 作者的话</strong></summary>
 
-To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.
+感谢每一位 star、fork 并分享这个 skill 的人。这个项目在不到 24 小时内就火了，社区的支持令人难以置信。
 
-If this skill helps you work smarter, that's all I wanted.
+如果这个 skill 能帮你更高效地工作，那就是我想要的全部。
 
 </details>
 
 <details>
-<summary><strong>🌍 What the community shipped</strong></summary>
+<summary><strong>🌍 社区已交付成果</strong></summary>
 
-### Forks & Extensions
+### 分支与扩展
 
-| Fork | Author | What They Built |
+| 分支 | 作者 | 他们做了什么 |
 |------|--------|-----------------|
-| [devis](https://github.com/st01cs/devis) | [@st01cs](https://github.com/st01cs) | Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation |
-| [multi-manus-planning](https://github.com/kmichels/multi-manus-planning) | [@kmichels](https://github.com/kmichels) | Multi-project support, SessionStart git sync |
-| [plan-cascade](https://github.com/Taoidle/plan-cascade) | [@Taoidle](https://github.com/Taoidle) | Multi-level task orchestration, parallel execution, multi-agent collaboration |
-| [agentfund-skill](https://github.com/RioTheGreat-ai/agentfund-skill) | [@RioTheGreat-ai](https://github.com/RioTheGreat-ai) | Crowdfunding for AI agents with milestone-based escrow on Base |
-| [openclaw-github-repo-commander](https://github.com/wd041216-bit/openclaw-github-repo-commander) | [@wd041216-bit](https://github.com/wd041216-bit) | 7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw |
+| [devis](https://github.com/st01cs/devis) | [@st01cs](https://github.com/st01cs) | 访谈优先工作流、`/devis:intv` 与 `/devis:impl` 命令、保证激活 |
+| [multi-manus-planning](https://github.com/kmichels/multi-manus-planning) | [@kmichels](https://github.com/kmichels) | 多项目支持、SessionStart git 同步 |
+| [plan-cascade](https://github.com/Taoidle/plan-cascade) | [@Taoidle](https://github.com/Taoidle) | 多级任务编排、并行执行、多智能体协作 |
+| [agentfund-skill](https://github.com/RioTheGreat-ai/agentfund-skill) | [@RioTheGreat-ai](https://github.com/RioTheGreat-ai) | 面向 AI agents 的众筹，基于 Base 上的里程碑托管 |
+| [openclaw-github-repo-commander](https://github.com/wd041216-bit/openclaw-github-repo-commander) | [@wd041216-bit](https://github.com/wd041216-bit) | 面向 OpenClaw 的 7 阶段 GitHub 仓库审计、优化与清理工作流 |
 
-### Used in the Wild
+### 实际应用
 
-| Project | What It Is |
+| 项目 | 是什么 |
 |---------|-----------|
-| [lincolnwan/Planning-with-files-copilot-agent](https://github.com/lincolnwan/Planning-with-files-copilot-agent) | Entire Copilot agent repo built around the planning-with-files skill |
-| [cooragent/ClarityFinance](https://github.com/cooragent/ClarityFinance) | AI finance agent framework — Planning-with-Files approach directly credited |
-| [oeftimie/vv-claude-harness](https://github.com/oeftimie/vv-claude-harness) | Claude Code harness built on Manus-style persistent markdown planning |
-| [jessepwj/CCteam-creator](https://github.com/jessepwj/CCteam-creator) | Multi-agent team orchestration skill using file-based planning |
+| [lincolnwan/Planning-with-files-copilot-agent](https://github.com/lincolnwan/Planning-with-files-copilot-agent) | 整个 Copilot agent 仓库围绕 planning-with-files skill 构建 |
+| [cooragent/ClarityFinance](https://github.com/cooragent/ClarityFinance) | AI 金融 agent 框架 — 直接致谢 Planning-with-Files 方法 |
+| [oeftimie/vv-claude-harness](https://github.com/oeftimie/vv-claude-harness) | 基于 Manus 风格持久化 markdown 规划的 Claude Code harness |
+| [jessepwj/CCteam-creator](https://github.com/jessepwj/CCteam-creator) | 使用基于文件规划的多智能体团队编排 skill |
 
-### Skill Registries & Hubs
+### Skill 注册表与中心
 
-| Registry | What It Is |
+| 注册表 | 是什么 |
 |----------|-----------|
-| [buzhangsan/skill-manager](https://github.com/buzhangsan/skill-manager) | Bilingual (EN/中文) skill hub indexing 31,000+ Claude Code skills — planning-with-files installable one-click. |
+| [buzhangsan/skill-manager](https://github.com/buzhangsan/skill-manager) | 双语（EN/中文）skill 中心，索引 31,000+ Claude Code skills — planning-with-files 可一键安装。 |
 
-*Built something? [Open an issue](https://github.com/OthmanAdi/planning-with-files/issues) to get listed!*
+*做了什么？[提个 issue](https://github.com/OthmanAdi/planning-with-files/issues) 即可上榜！*
 
 </details>
 
 <details>
-<summary><strong>🤝 Contributors</strong></summary>
+<summary><strong>🤝 贡献者</strong></summary>
 
-See the full list of everyone who made this project better in [CONTRIBUTORS.md](./CONTRIBUTORS.md).
+完整贡献者名单见 [CONTRIBUTORS.md](./CONTRIBUTORS.md)。
 
 </details>
 
 <details>
-<summary><strong>📦 Releases & Session Recovery</strong></summary>
+<summary><strong>📦 版本发布与会话恢复</strong></summary>
 
-### Current Version: v3.4.1
+### 当前版本：v3.4.1
 
-| Version | Highlights |
+| 版本 | 亮点 |
 |---------|------------|
-| **v3.4.1** | **Codex hooks now run on Windows (closes #201, reported by @mahdiit).** The `.codex/hooks.json` commands were POSIX only, so on Windows the native command interpreter choked on `python3` (the Store alias), `2>/dev/null`, and the `\|\| true` success guard whose `true` is not a Windows command, and every hook reported `hook exited with code 1`. Each hook now carries a per-hook `commandWindows` override (the POSIX `command` is untouched, so macOS and Linux are unchanged) that routes through a new `pwf-hook.cmd` launcher (real Python via `py -3`, falling back to `python`, never the Store `python3` alias) and, for the three shell hooks, a new `run_sh.py` front door. `codex_hook_adapter` resolves the Git for Windows `sh.exe` by anchoring on `git.exe`, so the shell scripts run even when Git's `usr\bin` is off PATH. Codex hook suites green (17 tests) plus new cross-platform and Windows-only coverage. |
-| **v3.4.0** | **`PLANNING_DISABLED=1` per-invocation opt-out for one-shot sessions (closes #195, reported by @marcmuon).** One-shot `codex exec` runs (CI review bots, read-only research agents, nested orchestrators) that merely shared a cwd with an incomplete plan were hijacked: plan context injected, the actual output redirected into `progress.md`, a fabricated completed phase appended to `task_plan.md`. All Codex hook entry points, the Python adapter route, and the canonical dispatchers (`inject-plan.sh`, `gate-stop.sh`, `check-complete.sh`/`.ps1`) now exit before reading the plan when `PLANNING_DISABLED=1` is set; PreToolUse keeps emitting its allow decision so tool calls proceed. The guard ships in every distributed copy including the five language variants. Also corrected `docs/codex.md`'s stale claim that the Stop hook blocks (non-blocking since v3.1.0). Suite at 200 passed. |
-| **v3.3.0** | **Pi extension hooks now wait for explicit user approval via `/plan-execute`** (PR #193 by @Dikshj, closes #190, requested by @lazyst). The Pi extension previously activated all hooks as soon as `task_plan.md` existed, so plan injection, pre-tool recitation, post-write reminders, and auto-continue could start while the user was still reviewing a draft plan. The extension now stays passive with a status line until the active plan is approved with `/plan-execute`; approval is scoped to the current session and plan path, resets on session lifecycle events, and `/plan-execute reset` returns to passive review. A plan with a tampered SHA-256 attestation cannot be approved. Suite at 188 passed plus 21 Pi extension vitest tests. |
-| **v3.2.0** | **Repository health audit: session-catchup.py was non-functional on Windows, plus the "0/0 phases" false status (closes #191, addresses #103, closes #188).** `session-catchup.py`, the mechanism behind "resume after `/clear`," never sanitized Windows-style paths correctly and had no explicit encoding on three reads, so it silently did nothing on Windows with no error. `inject-plan.sh`'s containment guard also silently dropped plan injection and tamper detection under 8.3 short-name or `/tmp`-aliased paths. Both fixed. Separately, `check-complete.sh`/`.ps1` and three IDE-specific Stop hooks reported a false "0/0 phases complete" for any `task_plan.md` without `### Phase` headings (#191, reported by @mixian939); fixed everywhere the pattern appeared, canonical scripts included. The `--template analytics` flag (v2.29.0) was silently falling back to default templates in every installed skill package; the analytics templates now actually ship where `init-session.sh` reads them. Merged PR #187 (@Stephen-abc: Windows test-encoding fixes, stale install-path docs) and PR #192 (@igorcosta: Autohand Code setup docs). Added `SECURITY.md` and enabled private vulnerability reporting (@AvitalAviv). Corrected `AGENTS.md`'s contributor-PR-merge guidance, which told agents to squash-merge in a way that reassigns authorship. Suite at 186 passed, 5 skipped, 0 failed. |
-| **v3.1.3** | **Hotfix: SKILL.md frontmatter was invalid YAML in v3.1.2.** The v3.1.2 description refresh added a colon, and the English SKILL.md keep `description` unquoted, so YAML rejected the frontmatter ("mapping values are not allowed here"), which could break skill loading and the model-triggering description. v3.1.3 quotes the description (matching the already-quoted translated variants; the parsed value is identical) across the canonical file and the seven English IDE variants, and adds `tests/test_skill_frontmatter_valid.py` to validate every SKILL.md frontmatter as YAML. Suite at 184 passed. |
-| **v3.1.2** | **Session-catchup command works outside the plugin runtime, `.hermes` parity, refreshed skill description** (PR #186 by @shunfeng8421 closes #185, reported by @xwang118). The documented Restore Context command used `${CLAUDE_PLUGIN_ROOT}`, which the plugin runtime sets only inside hook execution, so a skill-only install (`npx skills add`, Codex, Cursor) running it in a shell got an empty variable and a broken `/scripts/...` path. Now `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"` on the canonical file, `.codebuddy`, and the five language variants; the `.hermes` variant got the same fallback for `$HERMES_HOME`. The eight English SKILL.md descriptions were refreshed to lead with planning for AI coding agents and context-loss survival, with the `Use when` trigger and translated variants unchanged. Documentation only; suite at 180 passed. |
-| **v3.1.1** | **Codex verification command checks the canonical `hooks` feature flag** (PR #184 by @Fat-Jan). The `docs/codex.md` verify block ran `codex features list \| rg '^codex_hooks\s'`, but Codex moved its canonical feature key from `codex_hooks` to `hooks` in 0.129.0 (openai/codex#20522). The alias still resolves in config, yet `codex features list` prints only `hooks`, so the old pattern matched nothing on current Codex and routed correctly configured users to the upgrade path. The command now greps `^(hooks\|codex_hooks)\s` and the troubleshooting sentence covers both names, matching the `hooks = true` guidance carried in the file since v2.39.0. Documentation only; suite at 180 passed. |
-| **v3.1.0** | **Codex Stop hook no longer blocks on an incomplete plan, native Codex PreCompact parity, Pi extension test suite, and accurate SHA-cache docs** (PR #180 by @2023Anita closes #178, PR #181 by @GongYuanCaiJi, PR #175 and PR #174 by @mvanhorn close #163 and #164). The `.codex` Stop adapter dropped the `{"decision":"block"}` path that pushed Codex agents to auto-continue unfinished phases; it now emits an advisory progress-sync reminder only, matching the v3 principle that an incomplete plan alone never blocks a stop. The native `.codex/hooks.json` route gained the PreCompact hook (`pre-compact.sh`) it was missing relative to the canonical SKILL.md, dormant on runtimes that never fire the event. The Pi extension gained a TypeScript integration suite covering all eight lifecycle handlers, the four runtime modes, and the attestation gate. `docs/perf-notes.md` documents the attestation SHA cache, corrected to the v3 `$XDG_CACHE_HOME/pwf-sha` location. Suite at 180 passed. |
-| **v3.0.0** | **Autonomous and gated modes for long-running agentic runs, structured run ledger, opt-in completion gate** (no breaking changes: with no mode marker the hooks produce byte-identical v2.43 output). `init-session --autonomous` drops the per-tool-call plan re-injection for strong models and keeps the turn-start injection; `--gated` adds a deliberate Stop-hook completion gate that blocks only when five conditions hold (gated mode, an `in_progress` phase, `stop_hook_active` false, block count under the cap, ledger progressed since the last block), so an incomplete plan alone never traps a session. New append-only JSONL run ledger (`ledger-append`, `ledger-summary`, `phase-status`, sh + ps1) replaces the raw `progress.md` tail in v3 modes with a fixed-shape summary. Attestation is default-on in v3 modes and unattested plan bodies are refused at injection. Per-session nonce delimiters, SHA cache moved to `$XDG_CACHE_HOME/pwf-sha`, realpath containment in the plan-dir resolver. Hook scalars replaced by thin dispatchers (`inject-plan.sh`, `gate-stop.sh`) shipped in both `scripts/` locations. New `templates/task_plan_autonomous.md` with `DependsOn`/`Owner`/`AcceptanceCheck` fields, v2-to-v3 migration guide in `MIGRATION.md`, host capability tiers documented (hard block, follow-up inject, notify only). Suite at 178 passed plus location-parity and gate/ledger/init-mode/containment tests. |
-| **v2.43.0** | **CONTRIBUTING.md + OpenCode docs fix + `.continue`/`.gemini`/`.kiro` variant sync to parity** (PR #171 by @Skulli485, issue #172 by @luyanfeng, issues #159/#160/#161): first `CONTRIBUTING.md` at repo root, auto-surfaced by GitHub in the PR creation flow. `docs/opencode.md` Quick Install switched from \`git clone\` to \`npx skills add\` after the manual-install block was found referencing a doubled path (`planning-with-files/planning-with-files/SKILL.md`). Three historically lagging IDE SKILL.md variants brought to v2.43.0 parity: `.continue` from v2.34.0 (9 versions behind), `.gemini` from v2.34.0 (9 versions behind), `.kiro` from v2.32.0-kiro (11 versions behind), preserving IDE-specific frontmatter, hook shapes, and Kiro Agent Skill layout. |
-| **v2.42.0** | **POSIX `init-session.sh` portability + plugin-vs-skill install transparency + Topic Handoff docs** (PR #169 and PR #170 by @carterusedulm2-maker): `init-session.sh` and its 7 mirrors swap the `[[ ]]` bashism for POSIX `[ ]` so `tests/test_init_session_slug.py` runs cleanly under `dash` (Ubuntu) when the test invokes the script via `sh` rather than the `bash` shebang. Canonical SKILL.md gains an install-scope clarification: `/plugin install` ships the `commands/` folder with `/plan-goal` and `/plan-loop`, but `npx skills add` (and ClawHub) do not. A manual fallback procedure for both wrappers is documented inline so skill-only sessions can produce the same effect by invoking Claude Code's native `/goal` and `/loop` primitives directly. `docs/quickstart.md` and `docs/workflow.md` add an optional Topic Handoff Pattern for very long-running operational topics (`handoffs/<topic>.md` alongside `progress.md`). |
-| **v2.41.0** | **Windows exec-bit test skip + attestation-locking docs** (PR #167 by @gauravvojha, Issue #166; PR #168 by @CleanDev-Fix, Issue #165): `test_script_permissions.py` now skips on Windows with a class-level `pytest.mark.skipif(sys.platform == "win32")` since NTFS does not store POSIX executable bits; the 2 pre-existing Windows exec-bit failures (present since v2.34.1) are resolved. New dedicated `docs/attestation-locking.md` page documents the `attest-plan.sh` write path, the atomic temp-rename guarantee, the optional `flock` advisory lock, and the recommended slug-mode workflow for parallel sessions. |
-| **v2.40.1** | **Pi adapter SKILL.md sync gap + npm scope correction** (PR #158 by @TomXPRIME): the `.pi` SKILL.md lagged the canonical Claude Code copy after v2.39.0; v2.40.1 backports Rule 7 (Continue After Completion), the Security Boundary section, the expanded Scripts section covering `set-active-plan.sh`/`resolve-plan-dir.sh`/`attest-plan.sh` plus the parallel task workflow, and the "Write web content to task_plan.md" anti-pattern row. The Pi npm package is renamed from the unscoped `pi-planning-with-files` to `@tomxprime/planning-with-files`, matching the package author's namespace; install docs updated accordingly. Author, repository, license, and bugs URLs preserved. |
-| **v2.40.0** | **Slug-mode resolution fixes + perf cache + KV-cache hygiene + Pi false-positive fix** (9 items from the v2.40 R&D experiment): hook resolution order inverted so slug-mode wins over legacy root, `.active_plan` target dir + content validated against a safe-identifier regex, `check-complete.sh` honors `$PLAN_ID` and `.active_plan`, Pi extension `isDangerousBashCommand` swapped to a word-boundary regex array so benign `git push origin <branch>` no longer fires the warning, mtime-keyed SHA-256 cache cuts attestation-hook latency on Windows Git Bash, `progress.md` tail timestamps normalized for KV-cache prefix stability, `resolve-plan-dir.sh` mtime resolution made portable across GNU/BSD/macOS/Alpine/Git Bash with python+perl fallbacks, `attest-plan.sh` uses atomic temp-rename with optional `flock` to close the concurrent-writer race. 130 pass / 2 pre-existing Windows exec-bit fails, +20 new tests. |
-| **v2.39.0** | **Pi Coding Agent full hook parity extension + Codex hooks flag fix** (PR #157 by @TomXPRIME, Issue #154 by @DLI1996): the `.pi` adapter ships a bundled TypeScript extension mapping eight Pi lifecycle events to the same behavior the skill provides on Claude Code, with a four-mode system (`auto`/`parity`/`cache-safe`/`notify`) that auto-detects DeepSeek and keeps the KV-cache prefix stable. Pi runtime reads the same `.attestation` file the canonical v2.37 `attest-plan.sh` writes, so attesting once locks the plan across both runtimes. Four slash commands (`/plan-status`, `/plan-attest`, `/plan-goal`, `/plan-loop`) mirror their Claude Code counterparts. Separately, `docs/codex.md` swaps from `codex_hooks = true` to `hooks = true` to match the current OpenAI canonical key, with an alias note so users on older configs are not pushed to migrate. |
-| **v2.38.1** | **Description field garbled in Claude Code skill picker** (surfaced via Discussion #153 by @bmyury): hook commands embedded `'---BEGIN PLAN DATA---'` plan-injection delimiters; Claude Code's skill-discovery loader split frontmatter on the first `---` and read the truncated value as the description. Swapped to `===BEGIN PLAN DATA===` / `===END PLAN DATA===` across canonical SKILL.md, all five language variants, the `.codebuddy/.codex/.cursor` adapter mirrors, and `clawhub-upload`. Hook execution and tamper attestation never affected; only the displayed metadata. |
-| **v2.38.0** | **Claude Code turn-loop integration + OpenCode SQLite fix**: new PreCompact hook fires on `/compact` and autoCompact, surfaces a reminder to flush progress before compaction completes and prints the active Plan-SHA256 when attested. New `/plan-goal` slash command composes with Claude Code's `/goal` (v2.1.139, May 12 2026): derives a termination condition from the active plan. New `/plan-loop` composes with `/loop` (v2.1.72+): default 10-minute tick re-reads planning files and runs check-complete. New `templates/loop.md` for the bare `/loop` planning-aware default. Session-catchup rewritten for OpenCode's SQLite migration. Codex gets a `PermissionRequest` adapter that surfaces plan context at permission prompts. |
-| **v2.37.0** | **Hash attestation + parity bumper** (closes #150, #151): `/plan-attest` locks `task_plan.md` with a SHA-256; hooks block injection on tamper. `scripts/bump-version.py` + parity test kill the "missed one variant" regression class behind v2.34.1, v2.36.0, v2.36.2, and v2.36.3. (thanks @oaabahussain!) |
-| **v2.36.3** | **Parallel planning scripts now ship in the skill**: `resolve-plan-dir.sh` and `set-active-plan.sh` were missing from the installed skill in v2.36.0; now in canonical + all IDE mirrors + SKILL.md docs updated |
-| **v2.36.2** | **Canonical script sync** (PR #149): `skills/planning-with-files/scripts/init-session.sh` was missing slug mode from v2.36.0; now synced with IDE mirrors + regression test. (thanks @voidborne-d!) |
-| **v2.36.1** | **Security hardening**: Stop hook cache search removed, ExecutionPolicy Bypass changed to RemoteSigned, prompt injection delimiters added. (Gen Agent Trust Hub FAIL resolved) |
-| **v2.36.0** | **Parallel plan isolation + Codex session isolation** (closes #146, #148): `init-session.sh` slug mode, `set-active-plan.sh`, `resolve-plan-dir.sh`, all Codex hooks route through resolver, session attachment gating. **Hermes docs** (closes #147): integration notes added to `docs/hermes.md`. 34 new tests. (thanks @githubYiheng, @09ashishkapoor, @shawnli1874!) |
-| **v2.35.1** | **Shebang portability fix**: changed `/bin/bash` to `/usr/bin/env bash` in hook scripts, fixing compatibility on NixOS and other systems where bash is not at `/bin/bash`. (thanks @Emin017!) |
-| **v2.35.0** | **Hermes adapter + NLPM audit hardening**: Hermes platform 17 support (thanks @bailob!), NLPM audit fixed Python PATH resolution, session-catchup injection cap, Pi PowerShell syntax (thanks @xiaolai!) |
-| **v2.34.1** | **Stop hook Windows portability fix** (closes #133): `export SD=` failed in Windows Git Bash hook context; fallback path was wrong for plugin cache structure. Fixed across all 13 SKILL.md variants. (thanks @nazeshinjite!) |
-| **v2.34.0** | **Codex hooks fully restored** (closes #132): `.codex/hooks.json` + lifecycle scripts back — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop. Tessl CI for SKILL.md quality reviews. Exec bit fix. 4 missing contributors added. (thanks @Leon-Algo, @popey!) |
-| **v2.33.0** | **Multi-language expansion**: Arabic, German, and Spanish skill variants added (thanks to community contributors!) |
-| **v2.32.0** | Codex session catchup rewrite (thanks @ebrevdo!), Loaditout A-grade security badge, Stop hook Git Bash fix |
-| **v2.31.0** | Codex hooks.json integration with full lifecycle hooks (thanks @Leon-Algo!) |
-| **v2.30.1** | Fix: Codex script executable bits restored (thanks @Leon-Algo!) |
-| **v2.30.0** | `CLAUDE_SKILL_DIR` variable, IDE configs moved to per-IDE branches, plugin.json bumped from 2.23.0 |
-| **v2.29.0** | Analytics workflow template: `--template analytics` flag for data exploration sessions (thanks @mvanhorn!) |
-| **v2.28.0** | Traditional Chinese (zh-TW) skill variant (thanks @waynelee2048!) |
-| **v2.26.2** | Fix: `---` in hook commands broke YAML frontmatter parsing, hooks now register correctly |
-| **v2.26.1** | Fix: session catchup after `/clear`, path sanitization on Windows + content injection (thanks @tony-stark-eth!) |
-| **v2.26.0** | IDE audit: Factory hooks, Copilot errorOccurred hook, Gemini hooks, bug fixes |
-| **v2.18.2** | Mastra Code hooks fix (hooks.json + docs accuracy) |
-| **v2.18.1** | Copilot garbled characters complete fix |
-| **v2.18.0** | BoxLite sandbox runtime integration |
-| **v2.17.0** | Mastra Code support + all IDE SKILL.md spec fixes |
-| **v2.16.1** | Copilot garbled characters fix: PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!) |
-| **v2.16.0** | GitHub Copilot hooks support (thanks @lincolnwan!) |
-| **v2.27.0** | Kiro Agent Skill layout (thanks @EListenX!) |
-| **v2.15.1** | Session catchup false-positive fix (thanks @gydx6!) |
-| **v2.15.0** | `/plan:status` command, OpenCode compatibility fix |
-| **v2.14.0** | Pi Agent support, OpenClaw docs update, Codex path fix |
-| **v2.11.0** | `/plan` command for easier autocomplete |
-| **v2.10.0** | Kiro steering files support |
-| **v2.7.0** | Gemini CLI support |
-| **v2.2.0** | Session recovery, Windows PowerShell, OS-aware hooks |
+| **v3.4.1** | **Codex hooks 现可在 Windows 上运行（closes #201，由 @mahdiit 报告）。** `.codex/hooks.json` 命令此前仅为 POSIX，因此在 Windows 上原生命令解释器会卡在 `python3`（Store 别名）、`2>/dev/null`，以及 `\|\| true` 成功守卫（其 `true` 不是 Windows 命令）上，导致每个 hook 都报告 `hook exited with code 1`。每个 hook 现带有按 hook 的 `commandWindows` 覆盖（POSIX 的 `command` 保持不动，因此 macOS 与 Linux 不变），经新的 `pwf-hook.cmd` 启动器路由（通过 `py -3` 使用真正的 Python，回退到 `python`，绝不用 Store 的 `python3` 别名）；对三个 shell hooks，还有新的 `run_sh.py` 入口。`codex_hook_adapter` 通过锚定 `git.exe` 解析 Git for Windows 的 `sh.exe`，因此即使 Git 的 `usr\bin` 不在 PATH 上，shell 脚本也能运行。Codex hook 套件全绿（17 个测试），并新增跨平台与仅 Windows 覆盖。 |
+| **v3.4.0** | **`PLANNING_DISABLED=1` 按次调用的一次性会话退出开关（closes #195，由 @marcmuon 报告）。** 一次性的 `codex exec` 运行（CI 评审机器人、只读研究 agents、嵌套编排器）若仅与未完成计划共享 cwd，会被劫持：注入计划上下文、将实际输出重定向到 `progress.md`、向 `task_plan.md` 追加伪造的已完成阶段。所有 Codex hook 入口、Python 适配器路由以及规范调度器（`inject-plan.sh`、`gate-stop.sh`、`check-complete.sh`/`.ps1`）在设置 `PLANNING_DISABLED=1` 时，现在会在读取计划前退出；PreToolUse 仍发出 allow 决策，使工具调用可继续。该守卫随每个分发副本提供，包括五个语言变体。还修正了 `docs/codex.md` 中关于 Stop hook 会阻塞的过时说法（自 v3.1.0 起已不阻塞）。套件 200 通过。 |
+| **v3.3.0** | **Pi 扩展 hooks 现通过 `/plan-execute` 等待用户明确批准**（PR #193 by @Dikshj，closes #190，由 @lazyst 请求）。Pi 扩展此前只要存在 `task_plan.md` 就会激活全部 hooks，因此在用户仍在审阅草稿计划时，计划注入、工具前复述、写入后提醒与自动继续就可能开始。扩展现保持被动并显示状态行，直到用 `/plan-execute` 批准当前活动计划；批准范围限定于当前会话与计划路径，在会话生命周期事件上重置，且 `/plan-execute reset` 会回到被动审阅。带有被篡改 SHA-256 证明的计划无法批准。套件 188 通过，外加 21 个 Pi 扩展 vitest 测试。 |
+| **v3.2.0** | **仓库健康审计：session-catchup.py 在 Windows 上不可用，以及「0/0 phases」误报状态（closes #191，addresses #103，closes #188）。** `session-catchup.py`（「在 `/clear` 后恢复」背后的机制）从未正确清理 Windows 风格路径，且三次读取没有显式编码，因此在 Windows 上静默无作为且不报错。`inject-plan.sh` 的包含守卫在 8.3 短名或 `/tmp` 别名路径下也会静默丢弃计划注入与篡改检测。两处均已修复。另外，`check-complete.sh`/`.ps1` 与三个 IDE 专用 Stop hooks 对任何没有 `### Phase` 标题的 `task_plan.md` 误报「0/0 phases complete」（#191，由 @mixian939 报告）；凡出现该模式处均已修复，包括规范脚本。`--template analytics` 标志（v2.29.0）在每个已安装 skill 包中都静默回退到默认模板；分析模板现真正随包发布到 `init-session.sh` 读取的位置。合并 PR #187（@Stephen-abc：Windows 测试编码修复、过时安装路径文档）与 PR #192（@igorcosta：Autohand Code 设置文档）。新增 `SECURITY.md` 并启用私有漏洞报告（@AvitalAviv）。修正 `AGENTS.md` 中贡献者 PR 合并指引，原先会引导 agents 以会改写作者归属的方式 squash-merge。套件 186 通过、5 跳过、0 失败。 |
+| **v3.1.3** | **热修复：v3.1.2 中 SKILL.md frontmatter 为无效 YAML。** v3.1.2 的 description 刷新加入了冒号，而英文 SKILL.md 仍将 `description` 保持未加引号，YAML 因此拒绝 frontmatter（"mapping values are not allowed here"），可能破坏 skill 加载与模型触发描述。v3.1.3 在规范文件与七个英文 IDE 变体中为 description 加引号（与已加引号的翻译变体一致；解析值相同），并增加 `tests/test_skill_frontmatter_valid.py` 以将每个 SKILL.md frontmatter 校验为 YAML。套件 184 通过。 |
+| **v3.1.2** | **Session-catchup 命令可在插件运行时之外工作、`.hermes` 对齐、刷新 skill 描述**（PR #186 by @shunfeng8421 closes #185，由 @xwang118 报告）。文档中的 Restore Context 命令使用了 `${CLAUDE_PLUGIN_ROOT}`，而插件运行时仅在 hook 执行内设置该变量，因此仅 skill 安装（`npx skills add`、Codex、Cursor）在 shell 中运行时得到空变量与损坏的 `/scripts/...` 路径。现对规范文件、`.codebuddy` 以及五个语言变体使用 `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"`；`.hermes` 变体对 `$HERMES_HOME` 采用了相同回退。八个英文 SKILL.md 描述已刷新，以面向 AI coding agents 的规划与上下文丢失存活为首要说明，`Use when` 触发与翻译变体未变。仅文档；套件 180 通过。 |
+| **v3.1.1** | **Codex 校验命令检查规范的 `hooks` 功能标志**（PR #184 by @Fat-Jan）。`docs/codex.md` 校验块运行 `codex features list \| rg '^codex_hooks\s'`，但 Codex 在 0.129.0 中将规范功能键从 `codex_hooks` 改为 `hooks`（openai/codex#20522）。别名在配置中仍可解析，但 `codex features list` 只打印 `hooks`，因此旧模式在当前 Codex 上匹配不到任何内容，并把已正确配置的用户导向升级路径。该命令现 grep `^(hooks\|codex_hooks)\s`，故障排除句子覆盖两个名称，与文件自 v2.39.0 起携带的 `hooks = true` 指引一致。仅文档；套件 180 通过。 |
+| **v3.1.0** | **Codex Stop hook 不再因未完成计划而阻塞、原生 Codex PreCompact 对齐、Pi 扩展测试套件，以及准确的 SHA-cache 文档**（PR #180 by @2023Anita closes #178，PR #181 by @GongYuanCaiJi，PR #175 与 PR #174 by @mvanhorn close #163 与 #164）。`.codex` 的 Stop 适配器去掉了推动 Codex agents 自动继续未完成阶段的 `{"decision":"block"}` 路径；现仅发出建议性进度同步提醒，符合 v3 原则：仅因未完成计划从不阻塞 stop。原生 `.codex/hooks.json` 路由补上了相对规范 SKILL.md 缺失的 PreCompact hook（`pre-compact.sh`），在从不触发该事件的运行时上保持休眠。Pi 扩展获得 TypeScript 集成套件，覆盖全部八个生命周期处理器、四种运行时模式与证明门控。`docs/perf-notes.md` 记录证明 SHA 缓存，并更正为 v3 的 `$XDG_CACHE_HOME/pwf-sha` 位置。套件 180 通过。 |
+| **v3.0.0** | **面向长时间运行 agentic 运行的自主模式与门控模式、结构化运行账本、可选完成门控**（无破坏性变更：无模式标记时 hooks 产生与 v2.43 字节级相同的输出）。`init-session --autonomous` 对强模型取消按工具调用的计划再注入，保留回合开始注入；`--gated` 增加刻意的 Stop-hook 完成门控，仅在五个条件同时成立时阻塞（门控模式、存在 `in_progress` 阶段、`stop_hook_active` 为 false、阻塞次数未达上限、自上次阻塞以来账本有进展），因此仅未完成计划不会困住会话。新的仅追加 JSONL 运行账本（`ledger-append`、`ledger-summary`、`phase-status`，sh + ps1）在 v3 模式中以固定形状摘要取代原始 `progress.md` 尾部。v3 模式默认开启证明，未证明的计划体在注入时被拒绝。每会话 nonce 分隔符，SHA 缓存移至 `$XDG_CACHE_HOME/pwf-sha`，plan-dir 解析器中的 realpath 包含检查。Hook 标量由薄调度器取代（`inject-plan.sh`、`gate-stop.sh`），在两个 `scripts/` 位置均随附。新的 `templates/task_plan_autonomous.md` 含 `DependsOn`/`Owner`/`AcceptanceCheck` 字段，`MIGRATION.md` 中的 v2 到 v3 迁移指南，主机能力分层已文档化（硬阻塞、跟进注入、仅通知）。套件 178 通过，外加位置对齐与门控/账本/init-mode/包含测试。 |
+| **v2.43.0** | **CONTRIBUTING.md + OpenCode 文档修复 + `.continue`/`.gemini`/`.kiro` 变体同步至对齐**（PR #171 by @Skulli485，issue #172 by @luyanfeng，issues #159/#160/#161）：仓库根目录首次出现 `CONTRIBUTING.md`，由 GitHub 在 PR 创建流程中自动展示。发现手动安装块引用了加倍路径（`planning-with-files/planning-with-files/SKILL.md`）后，`docs/opencode.md` 快速安装从 \`git clone\` 改为 \`npx skills add\`。三个长期落后的 IDE SKILL.md 变体提升到 v2.43.0 对齐：`.continue` 自 v2.34.0（落后 9 个版本）、`.gemini` 自 v2.34.0（落后 9 个版本）、`.kiro` 自 v2.32.0-kiro（落后 11 个版本），保留 IDE 专用 frontmatter、hook 形态与 Kiro Agent Skill 布局。 |
+| **v2.42.0** | **POSIX `init-session.sh` 可移植性 + 插件与 skill 安装透明度 + Topic Handoff 文档**（PR #169 与 PR #170 by @carterusedulm2-maker）：`init-session.sh` 及其 7 个镜像将 `[[ ]]` bash 特有写法换为 POSIX 的 `[ ]`，以便测试通过 `sh`（而非 `bash` shebang）调用脚本时，`tests/test_init_session_slug.py` 在 `dash`（Ubuntu）下干净运行。规范 SKILL.md 增加安装范围说明：`/plugin install` 随附带有 `/plan-goal` 与 `/plan-loop` 的 `commands/` 文件夹，但 `npx skills add`（以及 ClawHub）不会。两种包装器的手动回退步骤均内联文档化，使仅 skill 会话可通过直接调用 Claude Code 原生的 `/goal` 与 `/loop` 原语产生相同效果。`docs/quickstart.md` 与 `docs/workflow.md` 增加可选的 Topic Handoff Pattern，用于超长运行的运维主题（`handoffs/<topic>.md` 与 `progress.md` 并列）。 |
+| **v2.41.0** | **Windows exec-bit 测试跳过 + 证明锁定文档**（PR #167 by @gauravvojha，Issue #166；PR #168 by @CleanDev-Fix，Issue #165）：`test_script_permissions.py` 现于 Windows 上以类级 `pytest.mark.skipif(sys.platform == "win32")` 跳过，因为 NTFS 不存储 POSIX 可执行位；自 v2.34.1 起存在的 2 个既有 Windows exec-bit 失败已解决。新的专用 `docs/attestation-locking.md` 页面记录 `attest-plan.sh` 写入路径、原子 temp-rename 保证、可选的 `flock` 建议锁，以及并行会话推荐的 slug-mode 工作流。 |
+| **v2.40.1** | **Pi 适配器 SKILL.md 同步缺口 + npm scope 修正**（PR #158 by @TomXPRIME）：v2.39.0 之后 `.pi` 的 SKILL.md 落后于规范 Claude Code 副本；v2.40.1 回移植 Rule 7（完成后继续）、Security Boundary 章节、覆盖 `set-active-plan.sh`/`resolve-plan-dir.sh`/`attest-plan.sh` 与并行任务工作流的扩展 Scripts 章节，以及「将网页内容写入 task_plan.md」反模式行。Pi npm 包从无 scope 的 `pi-planning-with-files` 重命名为 `@tomxprime/planning-with-files`，与包作者命名空间一致；安装文档相应更新。作者、仓库、许可证与 bugs URL 均保留。 |
+| **v2.40.0** | **Slug-mode 解析修复 + 性能缓存 + KV-cache 卫生 + Pi 误报修复**（来自 v2.40 研发实验的 9 项）：hook 解析顺序反转，使 slug-mode 优先于遗留 root；`.active_plan` 的目标目录与内容对照安全标识符正则校验；`check-complete.sh` 遵循 `$PLAN_ID` 与 `.active_plan`；Pi 扩展的 `isDangerousBashCommand` 改为词边界正则数组，使无害的 `git push origin <branch>` 不再触发警告；按 mtime 键控的 SHA-256 缓存降低 Windows Git Bash 上证明 hook 延迟；`progress.md` 尾部时间戳规范化以稳定 KV-cache 前缀；`resolve-plan-dir.sh` 的 mtime 解析在 GNU/BSD/macOS/Alpine/Git Bash 上可移植，并带 python+perl 回退；`attest-plan.sh` 使用原子 temp-rename 与可选的 `flock` 关闭并发写入竞态。130 通过 / 2 个既有 Windows exec-bit 失败，+20 个新测试。 |
+| **v2.39.0** | **Pi Coding Agent 完整 hook 对齐扩展 + Codex hooks 标志修复**（PR #157 by @TomXPRIME，Issue #154 by @DLI1996）：`.pi` 适配器附带 TypeScript 扩展，将八个 Pi 生命周期事件映射为 skill 在 Claude Code 上提供的相同行为，并有四模式系统（`auto`/`parity`/`cache-safe`/`notify`），可自动检测 DeepSeek 并保持 KV-cache 前缀稳定。Pi 运行时读取规范 v2.37 `attest-plan.sh` 写入的同一 `.attestation` 文件，因此证明一次即可在两个运行时锁定计划。四个斜杠命令（`/plan-status`、`/plan-attest`、`/plan-goal`、`/plan-loop`）镜像其 Claude Code 对应项。另外，`docs/codex.md` 从 `codex_hooks = true` 换为 `hooks = true` 以匹配当前 OpenAI 规范键，并附别名说明，避免将旧配置用户推去迁移。 |
+| **v2.38.1** | **Claude Code skill 选择器中 description 字段乱码**（经 Discussion #153 by @bmyury 暴露）：hook 命令嵌入了 `'---BEGIN PLAN DATA---'` 计划注入分隔符；Claude Code 的 skill 发现加载器在第一个 `---` 处切分 frontmatter，并将截断值读为 description。在规范 SKILL.md、全部五个语言变体、`.codebuddy/.codex/.cursor` 适配器镜像与 `clawhub-upload` 中改为 `===BEGIN PLAN DATA===` / `===END PLAN DATA===`。Hook 执行与篡改证明从未受影响；仅显示的元数据。 |
+| **v2.38.0** | **Claude Code 回合循环集成 + OpenCode SQLite 修复**：新的 PreCompact hook 在 `/compact` 与 autoCompact 时触发，在压缩完成前提示刷新进度，并在已证明时打印活动的 Plan-SHA256。新的 `/plan-goal` 斜杠命令与 Claude Code 的 `/goal`（v2.1.139，2026 年 5 月 12 日）组合：从活动计划推导终止条件。新的 `/plan-loop` 与 `/loop`（v2.1.72+）组合：默认 10 分钟 tick 重新读取规划文件并运行 check-complete。新的 `templates/loop.md` 作为裸 `/loop` 的规划感知默认。Session-catchup 为 OpenCode 的 SQLite 迁移重写。Codex 获得 `PermissionRequest` 适配器，在权限提示处展示计划上下文。 |
+| **v2.37.0** | **哈希证明 + 对齐提升器**（closes #150, #151）：`/plan-attest` 用 SHA-256 锁定 `task_plan.md`；hooks 在篡改时阻止注入。`scripts/bump-version.py` + 对齐测试消灭了 v2.34.1、v2.36.0、v2.36.2 与 v2.36.3 背后的「漏掉一个变体」回归类。（感谢 @oaabahussain！） |
+| **v2.36.3** | **并行规划脚本现随 skill 发布**：v2.36.0 安装的 skill 中缺失 `resolve-plan-dir.sh` 与 `set-active-plan.sh`；现已纳入规范 + 全部 IDE 镜像，并更新 SKILL.md 文档 |
+| **v2.36.2** | **规范脚本同步**（PR #149）：`skills/planning-with-files/scripts/init-session.sh` 缺失 v2.36.0 的 slug mode；现已与 IDE 镜像同步 + 回归测试。（感谢 @voidborne-d！） |
+| **v2.36.1** | **安全加固**：移除 Stop hook 缓存搜索，ExecutionPolicy Bypass 改为 RemoteSigned，增加 prompt injection 分隔符。（Gen Agent Trust Hub FAIL 已解决） |
+| **v2.36.0** | **并行计划隔离 + Codex 会话隔离**（closes #146, #148）：`init-session.sh` slug mode、`set-active-plan.sh`、`resolve-plan-dir.sh`，全部 Codex hooks 经 resolver 路由，会话附着门控。**Hermes 文档**（closes #147）：集成说明加入 `docs/hermes.md`。34 个新测试。（感谢 @githubYiheng、@09ashishkapoor、@shawnli1874！） |
+| **v2.35.1** | **Shebang 可移植性修复**：hook 脚本中将 `/bin/bash` 改为 `/usr/bin/env bash`，修复 NixOS 及其他 bash 不在 `/bin/bash` 的系统上的兼容性。（感谢 @Emin017！） |
+| **v2.35.0** | **Hermes 适配器 + NLPM 审计加固**：Hermes platform 17 支持（感谢 @bailob！），NLPM 审计修复 Python PATH 解析、session-catchup 注入上限、Pi PowerShell 语法（感谢 @xiaolai！） |
+| **v2.34.1** | **Stop hook Windows 可移植性修复**（closes #133）：`export SD=` 在 Windows Git Bash hook 上下文中失败；插件缓存结构下的回退路径错误。已在全部 13 个 SKILL.md 变体中修复。（感谢 @nazeshinjite！） |
+| **v2.34.0** | **Codex hooks 全面恢复**（closes #132）：`.codex/hooks.json` + 生命周期脚本回归 — SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop。Tessl CI 用于 SKILL.md 质量评审。Exec bit 修复。补上 4 位缺失贡献者。（感谢 @Leon-Algo、@popey！） |
+| **v2.33.0** | **多语言扩展**：新增阿拉伯语、德语与西班牙语 skill 变体（感谢社区贡献者！） |
+| **v2.32.0** | Codex session catchup 重写（感谢 @ebrevdo！）、Loaditout A 级安全徽章、Stop hook Git Bash 修复 |
+| **v2.31.0** | Codex hooks.json 集成完整生命周期 hooks（感谢 @Leon-Algo！） |
+| **v2.30.1** | 修复：恢复 Codex 脚本可执行位（感谢 @Leon-Algo！） |
+| **v2.30.0** | `CLAUDE_SKILL_DIR` 变量，IDE 配置迁至按 IDE 的分支，plugin.json 从 2.23.0 升级 |
+| **v2.29.0** | 分析工作流模板：用于数据探索会话的 `--template analytics` 标志（感谢 @mvanhorn！） |
+| **v2.28.0** | 繁体中文（zh-TW）skill 变体（感谢 @waynelee2048！） |
+| **v2.26.2** | 修复：hook 命令中的 `---` 破坏 YAML frontmatter 解析，hooks 现可正确注册 |
+| **v2.26.1** | 修复：`/clear` 后的 session catchup、Windows 路径清理 + 内容注入（感谢 @tony-stark-eth！） |
+| **v2.26.0** | IDE 审计：Factory hooks、Copilot errorOccurred hook、Gemini hooks、缺陷修复 |
+| **v2.18.2** | Mastra Code hooks 修复（hooks.json + 文档准确性） |
+| **v2.18.1** | Copilot 乱码完整修复 |
+| **v2.18.0** | BoxLite sandbox 运行时集成 |
+| **v2.17.0** | Mastra Code 支持 + 全部 IDE SKILL.md 规范修复 |
+| **v2.16.1** | Copilot 乱码修复：PS1 UTF-8 编码 + bash ensure_ascii（感谢 @Hexiaopi！） |
+| **v2.16.0** | GitHub Copilot hooks 支持（感谢 @lincolnwan！） |
+| **v2.27.0** | Kiro Agent Skill 布局（感谢 @EListenX！） |
+| **v2.15.1** | Session catchup 误报修复（感谢 @gydx6！） |
+| **v2.15.0** | `/plan:status` 命令、OpenCode 兼容性修复 |
+| **v2.14.0** | Pi Agent 支持、OpenClaw 文档更新、Codex 路径修复 |
+| **v2.11.0** | 便于自动补全的 `/plan` 命令 |
+| **v2.10.0** | Kiro steering files 支持 |
+| **v2.7.0** | Gemini CLI 支持 |
+| **v2.2.0** | 会话恢复、Windows PowerShell、感知操作系统的 hooks |
 
-[View all releases](https://github.com/OthmanAdi/planning-with-files/releases) · [CHANGELOG](CHANGELOG.md)
+[查看全部版本发布](https://github.com/OthmanAdi/planning-with-files/releases) · [CHANGELOG](CHANGELOG.md)
 
-> Parallel plan isolation (`.planning/YYYY-MM-DD-slug/` directories) and Codex session isolation shipped in v2.36.0. The `experimental/isolated-planning` branch was the earlier prototype; master is now the canonical location.
+> v2.36.0 已发布并行计划隔离（`.planning/YYYY-MM-DD-slug/` 目录）与 Codex 会话隔离。`experimental/isolated-planning` 分支是更早的原型；master 现为规范主分支。
 
 ---
 
-### Session Recovery
+### 会话恢复
 
-When your context fills up and you run `/clear`, this skill **automatically recovers** your previous session.
+当你的上下文写满并运行 `/clear` 时，此 skill 会**自动恢复**你之前的会话。
 
-**How it works:**
-1. Checks for previous session data in the active IDE's session store (`~/.claude/projects/` for Claude Code, `~/.codex/sessions/` for Codex)
-2. Finds when planning files were last updated
-3. Extracts conversation that happened after (potentially lost context)
-4. Shows a catchup report so you can sync
+**工作原理：**
+1. 在当前 IDE 的会话存储中检查是否有先前会话数据（Claude Code 为 `~/.claude/projects/`，Codex 为 `~/.codex/sessions/`）
+2. 查找规划文件最后一次更新的时间
+3. 提取此后发生的对话（可能已丢失的上下文）
+4. 显示追赶报告，便于你同步状态
 
-**Pro tip:** Disable auto-compact to maximize context before clearing:
+**专业提示：** 在清空上下文前禁用 auto-compact，以尽可能保留更多上下文：
 ```json
 { "autoCompact": false }
 ```
@@ -153,58 +159,58 @@ When your context fills up and you run `/clear`, this skill **automatically reco
 </details>
 
 <details>
-<summary><strong>🛠️ Supported IDEs (18+ Platforms)</strong></summary>
+<summary><strong>🛠️ 支持的 IDE（18+ 平台）</strong></summary>
 
-#### Enhanced Support (hooks + lifecycle automation)
+#### 增强支持（hooks + 生命周期自动化）
 
-These IDEs have dedicated hook configurations that automatically re-read your plan before tool use, remind you to update progress, and verify completion before stopping:
+这些 IDE 配有专用 hook 配置，可在使用工具前自动重读你的计划、提醒你更新进度，并在停止前验证是否完成：
 
-| IDE | Installation Guide | Integration |
+| IDE | 安装指南 | 集成方式 |
 |-----|-------------------|-------------|
-| Claude Code | [Installation](docs/installation.md) | Plugin + SKILL.md + Hooks |
-| Cursor | [Cursor Setup](docs/cursor.md) | Skills + [hooks.json](https://cursor.com/docs/hooks) |
-| GitHub Copilot | [Copilot Setup](docs/copilot.md) | [Hooks](https://docs.github.com/en/copilot/reference/hooks-configuration) (incl. errorOccurred) |
-| Mastra Code | [Mastra Setup](docs/mastra.md) | Skills + [Hooks](https://mastra.ai/docs/mastra-code/configuration) |
-| Gemini CLI | [Gemini Setup](docs/gemini.md) | Skills + [Hooks](https://geminicli.com/docs/hooks/) |
-| Kiro | [Kiro Setup](docs/kiro.md) | [Agent Skills](https://kiro.dev/docs/skills/) |
-| Codex | [Codex Setup](docs/codex.md) | [Skills + Hooks](https://developers.openai.com/codex/skills) |
-| Hermes Agent | [Hermes Setup](docs/hermes.md) | Skill + Project Plugin |
-| CodeBuddy | [CodeBuddy Setup](docs/codebuddy.md) | [Skills + Hooks](https://www.codebuddy.ai/docs/cli/skills) |
-| FactoryAI Droid | [Factory Setup](docs/factory.md) | [Skills + Hooks](https://docs.factory.ai/cli/configuration/skills) |
-| OpenCode | [OpenCode Setup](docs/opencode.md) | Skills + Custom session storage |
+| Claude Code | [安装](docs/installation.md) | Plugin + SKILL.md + Hooks |
+| Cursor | [Cursor 配置](docs/cursor.md) | Skills + [hooks.json](https://cursor.com/docs/hooks) |
+| GitHub Copilot | [Copilot 配置](docs/copilot.md) | [Hooks](https://docs.github.com/en/copilot/reference/hooks-configuration)（含 errorOccurred）|
+| Mastra Code | [Mastra 配置](docs/mastra.md) | Skills + [Hooks](https://mastra.ai/docs/mastra-code/configuration) |
+| Gemini CLI | [Gemini 配置](docs/gemini.md) | Skills + [Hooks](https://geminicli.com/docs/hooks/) |
+| Kiro | [Kiro 配置](docs/kiro.md) | [Agent Skills](https://kiro.dev/docs/skills/) |
+| Codex | [Codex 配置](docs/codex.md) | [Skills + Hooks](https://developers.openai.com/codex/skills) |
+| Hermes Agent | [Hermes 配置](docs/hermes.md) | Skill + Project Plugin |
+| CodeBuddy | [CodeBuddy 配置](docs/codebuddy.md) | [Skills + Hooks](https://www.codebuddy.ai/docs/cli/skills) |
+| FactoryAI Droid | [Factory 配置](docs/factory.md) | [Skills + Hooks](https://docs.factory.ai/cli/configuration/skills) |
+| OpenCode | [OpenCode 配置](docs/opencode.md) | Skills + Custom session storage |
 
-#### Standard Agent Skills Support
+#### 标准 Agent Skills 支持
 
-These IDEs implement the [Agent Skills](https://agentskills.io) open specification. Install with `npx skills add` — the installer places the skill in each IDE's discovery path automatically:
+这些 IDE 实现了 [Agent Skills](https://agentskills.io) 开放规范。使用 `npx skills add` 安装——安装器会自动将 skill 放入各 IDE 的发现路径：
 
-| IDE | Installation Guide | Skill Discovery Path |
+| IDE | 安装指南 | Skill 发现路径 |
 |-----|-------------------|---------------------|
-| Continue | [Continue Setup](docs/continue.md) | `.continue/skills/` + [.prompt files](https://docs.continue.dev/customize/deep-dives/prompts) |
-| Pi Agent | [Pi Agent Setup](docs/pi-agent.md) | `.pi/skills/` ([npm package](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)) |
-| OpenClaw | [OpenClaw Setup](docs/openclaw.md) | `.openclaw/skills/` ([docs](https://docs.openclaw.ai/tools/skills)) |
-| Autohand Code | [Autohand Code Setup](docs/autohand.md) | `~/.autohand/skills/` or `.autohand/skills/` |
-| Antigravity | [Antigravity Setup](docs/antigravity.md) | `.agent/skills/` ([docs](https://codelabs.developers.google.com/getting-started-with-antigravity-skills)) |
-| Kilocode | [Kilocode Setup](docs/kilocode.md) | `.kilocode/skills/` ([docs](https://kilo.ai/docs/agent-behavior/skills)) |
-| AdaL CLI (Sylph AI) | [AdaL Setup](docs/adal.md) | `.adal/skills/` ([docs](https://docs.sylph.ai/features/plugins-and-skills)) |
+| Continue | [Continue 配置](docs/continue.md) | `.continue/skills/` + [.prompt files](https://docs.continue.dev/customize/deep-dives/prompts) |
+| Pi Agent | [Pi Agent 配置](docs/pi-agent.md) | `.pi/skills/`（[npm package](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)) |
+| OpenClaw | [OpenClaw 配置](docs/openclaw.md) | `.openclaw/skills/`（[docs](https://docs.openclaw.ai/tools/skills)) |
+| Autohand Code | [Autohand Code 配置](docs/autohand.md) | `~/.autohand/skills/` 或 `.autohand/skills/` |
+| Antigravity | [Antigravity 配置](docs/antigravity.md) | `.agent/skills/`（[docs](https://codelabs.developers.google.com/getting-started-with-antigravity-skills)) |
+| Kilocode | [Kilocode 配置](docs/kilocode.md) | `.kilocode/skills/`（[docs](https://kilo.ai/docs/agent-behavior/skills)) |
+| AdaL CLI (Sylph AI) | [AdaL 配置](docs/adal.md) | `.adal/skills/`（[docs](https://docs.sylph.ai/features/plugins-and-skills)) |
 
-> **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) branch.
+> **注意：** 如果你的 IDE 使用旧版 Rules 系统而非 Skills，请参阅 [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) 分支。
 
 </details>
 
 <details>
-<summary><strong>🧱 Sandbox Runtimes (1 Platform)</strong></summary>
+<summary><strong>🧱 沙箱运行时（1 个平台）</strong></summary>
 
-| Runtime | Status | Guide | Notes |
+| 运行时 | 状态 | 指南 | 说明 |
 |---------|--------|-------|-------|
-| BoxLite | ✅ Documented | [BoxLite Setup](docs/boxlite.md) | Run Claude Code + planning-with-files inside hardware-isolated micro-VMs |
+| BoxLite | ✅ 已文档化 | [BoxLite 配置](docs/boxlite.md) | 在硬件隔离的微 VM 中运行 Claude Code + planning-with-files |
 
-> **Note:** BoxLite is a sandbox runtime, not an IDE. Skills load via [ClaudeBox](https://github.com/boxlite-ai/claudebox) — BoxLite’s official Claude Code integration layer.
+> **注意：** BoxLite 是沙箱运行时，而非 IDE。Skills 通过 [ClaudeBox](https://github.com/boxlite-ai/claudebox) 加载——BoxLite 官方的 Claude Code 集成层。
 
 </details>
 
 ---
 
-A Claude Code plugin that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.
+一款 Claude Code 插件，可将你的工作流改造为使用持久化 Markdown 文件进行规划、进度跟踪和知识存储——正是这一模式让 Manus 价值数十亿美元。
 
 [![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/plugins)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-green)](https://code.claude.com/docs/en/skills)
@@ -220,14 +226,14 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
 [![Hermes](https://img.shields.io/badge/Hermes-Agent_Skill-5C7CFA)](docs/hermes.md)
 [![BoxLite](https://img.shields.io/badge/BoxLite-Sandbox-6C3483)](https://boxlite.ai)
 
-## Quick Install
+## 快速安装
 
 ```bash
 npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
 ```
 
 <details>
-<summary><strong>🌐 Available in 5 other languages</strong></summary>
+<summary><strong>🌐 另有 5 种语言版本</strong></summary>
 
 **🇸🇦 العربية / Arabic**
 ```bash
@@ -256,12 +262,12 @@ npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g
 
 </details>
 
-Works with Claude Code, Cursor, Codex, Gemini CLI, Autohand Code, and 40+ agents supporting the [Agent Skills](https://agentskills.io) spec.
+适用于 Claude Code、Cursor、Codex、Gemini CLI、Autohand Code，以及 40+ 个支持 [Agent Skills](https://agentskills.io) 规范的 agent。
 
 <details>
-<summary><strong>🔧 Claude Code Plugin (Advanced Features)</strong></summary>
+<summary><strong>🔧 Claude Code Plugin（高级功能）</strong></summary>
 
-For Claude Code-specific features like `/plan` autocomplete commands:
+如需 `/plan` 自动补全命令等 Claude Code 专属功能：
 
 ```
 /plugin marketplace add OthmanAdi/planning-with-files
@@ -270,47 +276,47 @@ For Claude Code-specific features like `/plan` autocomplete commands:
 
 </details>
 
-That's it! Now use one of these commands in Claude Code:
+就这么简单！现在在 Claude Code 中使用以下任一命令：
 
-| Command | Autocomplete | Description |
+| 命令 | 自动补全 | 说明 |
 |---------|--------------|-------------|
-| `/planning-with-files:plan` | Type `/plan` | Start planning session (v2.11.0+) |
-| `/planning-with-files:status` | Type `/plan:status` | Show planning progress at a glance (v2.15.0+) |
-| `/planning-with-files:start` | Type `/planning` | Original start command |
+| `/planning-with-files:plan` | 输入 `/plan` | 开始规划会话（v2.11.0+）|
+| `/planning-with-files:status` | 输入 `/plan:status` | 一目了然查看规划进度（v2.15.0+）|
+| `/planning-with-files:start` | 输入 `/planning` | 原始启动命令 |
 
-**Alternative:** If you want `/planning-with-files` (without prefix), copy skills to your local folder:
+**替代方案：** 如需 `/planning-with-files`（无前缀），请将 skills 复制到本地文件夹：
 
-**macOS/Linux:**
+**macOS/Linux：**
 ```bash
 cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
 ```
 
-**Windows (PowerShell):**
+**Windows（PowerShell）：**
 ```powershell
 Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"
 ```
 
-See [docs/installation.md](docs/installation.md) for all installation methods.
+所有安装方式请参阅 [docs/installation.md](docs/installation.md)。
 
-## Why This Skill?
+## 为什么选择这个 Skill？
 
-On December 29, 2025, [Meta acquired Manus for $2 billion](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering**.
+2025 年 12 月 29 日，[Meta 以 20 亿美元收购 Manus](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). 短短 8 个月内，Manus 从上线到营收超过 1 亿美元。他们的秘诀？**上下文工程（Context engineering）**。
 
-> "Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."
+> "Markdown 是我磁盘上的「工作记忆」。由于我会迭代处理信息，且活跃上下文有限，Markdown 文件充当笔记草稿、进度检查点，以及最终交付物的构建块。"
 > — Manus AI
 
-## The Problem
+## 问题所在
 
-Claude Code (and most AI agents) suffer from:
+Claude Code（以及大多数 AI 智能体）存在以下问题：
 
-- **Volatile memory** — TodoWrite tool disappears on context reset
-- **Goal drift** — After 50+ tool calls, original goals get forgotten
-- **Hidden errors** — Failures aren't tracked, so the same mistakes repeat
-- **Context stuffing** — Everything crammed into context instead of stored
+- **记忆易失** — 上下文重置后 TodoWrite 工具会消失
+- **目标漂移** — 经过 50 次以上工具调用后，原始目标会被遗忘
+- **错误被隐藏** — 失败未被记录，导致同样错误反复发生
+- **上下文塞满** — 所有内容塞进上下文，而非持久化存储
 
-## The Solution: 3-File Pattern
+## 解决方案：三文件模式
 
-For every complex task, create THREE files:
+对于每个复杂任务，创建三个文件：
 
 ```
 task_plan.md      → Track phases and progress
@@ -318,7 +324,7 @@ findings.md       → Store research and findings
 progress.md       → Session log and test results
 ```
 
-### The Core Principle
+### 核心原则
 
 ```
 Context Window = RAM (volatile, limited)
@@ -327,71 +333,71 @@ Filesystem = Disk (persistent, unlimited)
 → Anything important gets written to disk.
 ```
 
-## The Manus Principles
+## Manus 原则
 
-| Principle | Implementation |
+| 原则 | 实现方式 |
 |-----------|----------------|
-| Filesystem as memory | Store in files, not context |
-| Attention manipulation | Re-read plan before decisions (hooks) |
-| Error persistence | Log failures in plan file |
-| Goal tracking | Checkboxes show progress |
-| Completion verification | Stop hook checks all phases |
+| 文件系统即记忆 | 存入文件，而非上下文 |
+| 注意力操控（Attention manipulation） | 重大决策前重读计划（hooks） |
+| 错误持久化 | 在计划文件中记录失败 |
+| 目标追踪 | 复选框展示进度 |
+| 完成验证 | Stop hook 检查所有阶段 |
 
-## Usage
+## 使用方法
 
-Once installed, the AI agent will:
+安装后，AI 智能体将：
 
-1. **Ask for your task** if no description is provided
-2. **Create `task_plan.md`, `findings.md`, and `progress.md`** in your project directory
-3. **Re-read plan** before major decisions (via PreToolUse hook in legacy mode; autonomous mode injects at session start and phase transitions instead, dropping the per-tool-call tax on strong models)
-4. **Remind you** to update status after file writes (via PostToolUse hook)
-5. **Store findings** in `findings.md` instead of stuffing context
-6. **Log errors** for future reference
-7. **Verify completion** before stopping (via Stop hook)
+1. 若未提供任务描述，**询问你的任务**
+2. 在项目目录中**创建 `task_plan.md`、`findings.md` 和 `progress.md`**
+3. 重大决策前**重读计划**（传统模式下通过 PreToolUse hook；自主模式则在会话开始与阶段切换时注入，避免强模型承担每次工具调用的额外开销）
+4. 文件写入后**提醒你**更新状态（通过 PostToolUse hook）
+5. 将发现**存入** `findings.md`，而非塞进上下文
+6. **记录错误**供日后参考
+7. 停止前**验证完成**（通过 Stop hook）
 
-Invoke with:
-- `/planning-with-files:plan` - Type `/plan` to find in autocomplete (v2.11.0+)
-- `/planning-with-files:start` - Type `/planning` to find in autocomplete
-- `/planning-with-files` - Only if you copied skills to `~/.claude/skills/`
+调用方式：
+- `/planning-with-files:plan` — 输入 `/plan` 在自动补全中查找（v2.11.0+）
+- `/planning-with-files:start` — 输入 `/planning` 在自动补全中查找
+- `/planning-with-files` — 仅当你将 skills 复制到 `~/.claude/skills/` 时
 
-See [docs/quickstart.md](docs/quickstart.md) for the full 5-step guide.
+完整五步指南请参阅 [docs/quickstart.md](docs/quickstart.md)。
 
-## Benchmark Results
+## 基准测试结果
 
-> **Methodology note:** the 96.7% figure comes from the v2.21.0 evaluation run on `claude-sonnet-4-6` (2026-03-06). It measures file-pattern fidelity (does the agent create and maintain the 3-file structure), not goal-drift over long autonomous runs. Newer models and the autonomous-mode work are not yet covered by this number. Full methodology, dataset, and assertion list: [docs/evals.md](docs/evals.md).
+> **方法论说明：** 96.7% 这一数字来自在 `claude-sonnet-4-6` 上运行的 v2.21.0 评估（2026-03-06）。它衡量的是文件模式保真度（智能体是否创建并维护三文件结构），而非长程自主运行中的目标漂移。较新模型及自主模式相关工作尚未纳入该数字。完整方法论、数据集与断言列表：[docs/evals.md](docs/evals.md)。
 
-Formally evaluated using Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) framework (v2.22.0), model `claude-sonnet-4-6`, 2026-03-06. 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.
+使用 Anthropic 的 [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) 框架（v2.22.0）正式评估，模型 `claude-sonnet-4-6`，2026-03-06。10 个并行子智能体，5 种任务类型，30 条可客观验证的断言，3 次盲测 A/B 对比。
 
-| Test | with_skill | without_skill |
+| 测试项 | 使用 skill | 未使用 skill |
 |------|-----------|---------------|
-| Pass rate (30 assertions) | **96.7%** (29/30) | 6.7% (2/30) |
-| 3-file pattern followed | 5/5 evals | 0/5 evals |
-| Blind A/B wins | **3/3 (100%)** | 0/3 |
-| Avg rubric score | **10.0/10** | 6.8/10 |
+| 通过率（30 条断言） | **96.7%** (29/30) | 6.7% (2/30) |
+| 遵循三文件模式 | 5/5 evals | 0/5 evals |
+| 盲测 A/B 胜出 | **3/3 (100%)** | 0/3 |
+| 平均评分量表得分 | **10.0/10** | 6.8/10 |
 
-[Full methodology and results](docs/evals.md) · [Technical write-up](docs/article.md)
+[完整方法论与结果](docs/evals.md) · [技术详解](docs/article.md)
 
-## Key Rules
+## 关键规则
 
-1. **Create Plan First** — Never start without `task_plan.md`
-2. **The 2-Action Rule** — Save findings after every 2 view/browser operations
-3. **Log ALL Errors** — They help avoid repetition
-4. **Never Repeat Failures** — Track attempts, mutate approach
+1. **先建计划** — 没有 `task_plan.md` 绝不开始
+2. **两步操作规则** — 每进行 2 次 view/browser 操作后保存发现
+3. **记录所有错误** — 有助于避免重复犯错
+4. **绝不重复失败** — 追踪尝试次数，调整方法
 
-## When to Use
+## 适用场景
 
-**Use this pattern for:**
-- Multi-step tasks (3+ steps)
-- Research tasks
-- Building/creating projects
-- Tasks spanning many tool calls
+**适用于：**
+- 多步骤任务（3 步以上）
+- 研究类任务
+- 构建/创建项目
+- 跨越大量工具调用的任务
 
-**Skip for:**
-- Simple questions
-- Single-file edits
-- Quick lookups
+**不适用于：**
+- 简单问答
+- 单文件编辑
+- 快速查询
 
-## File Structure
+## 文件结构
 
 ```
 planning-with-files/
@@ -487,51 +493,51 @@ planning-with-files/
 └── README.md
 ```
 
-## FAQ
+## 常见问题
 
-### How do I stop my coding agent from losing its plan after /clear or a crash?
+### 如何在 /clear 或崩溃后避免编程智能体丢失计划？
 
-The plan lives on disk in `task_plan.md`, `findings.md`, and `progress.md`, not only in the context window. At the start of each turn the `UserPromptSubmit` hook re-injects the active plan, and after a `/clear` or a new session the skill re-reads the files from disk (session recovery), so the agent recovers its goals and progress automatically.
+计划保存在磁盘上的 `task_plan.md`、`findings.md` 和 `progress.md` 中，而不仅存在于上下文窗口。每轮开始时，`UserPromptSubmit` hook 会重新注入当前计划；在 `/clear` 或新会话之后，该 skill 会从磁盘重读文件（会话恢复），从而让智能体自动恢复目标与进度。
 
-### What is the difference between planning-with-files and an agent memory tool?
+### planning-with-files 与智能体记忆（agent memory）工具有何区别？
 
-Agent memory tools (vector stores, knowledge graphs) help an agent recall facts from past sessions. planning-with-files manages active execution state: the phases, status, dependencies, and completion check for the task the agent is working on right now. The problem it solves is planning continuity, not retrieval, and the two are complementary.
+智能体记忆工具（如向量存储、知识图谱）帮助智能体回忆过往会话中的事实。planning-with-files 管理的是活跃执行状态：当前任务所处的阶段、状态、依赖关系以及完成检查。它解决的是规划连续性（planning continuity）问题，而非检索（retrieval），二者互为补充。
 
-### How does this prevent context rot?
+### 它如何防止上下文腐化（context rot）？
 
-Context rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected at the start of each turn from disk, the goals and phase status stay in the model's attention window as the conversation grows. This is an implementation of what Anthropic calls structured note-taking: write durable state to files outside the window, then read it back in when needed.
+上下文腐化是指上下文窗口逐渐被填满、较早的指令被挤出时产生的漂移。由于在每一轮对话开始时都会从磁盘重新注入计划，随着对话增长，目标与阶段状态仍能留在模型的注意力窗口中。这实现了 Anthropic 所称的结构化笔记（structured note-taking）：将持久状态写入窗口外的文件，需要时再读回。
 
-### Which coding agents does this work with?
+### 支持哪些编程智能体？
 
-Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, CodeBuddy, Factory, Mastra, and 60+ others via the SKILL.md open standard. Installation is one command; see [Quick Install](#quick-install) above.
+支持 Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot、Kiro、OpenCode、Continue、Pi、CodeBuddy、Factory、Mastra，以及通过 SKILL.md 开放标准支持的 60+ 其他工具。安装只需一条命令；见上文 [Quick Install](#quick-install)。
 
-## Documentation
+## 文档
 
-All platform setup guides and documentation are in the [docs/](./docs/) folder.
+所有平台的安装指南与文档均在 [docs/](./docs/) 文件夹中。
 
 
-## Acknowledgments
+## 致谢
 
-- **Manus AI** — For pioneering context engineering patterns
-- **Anthropic** — For Claude Code, Agent Skills, and the Plugin system
-- **Lance Martin** — For the detailed Manus architecture analysis
-- Based on [Context Engineering for AI Agents](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
+- **Manus AI** — 率先探索上下文工程（context engineering）模式
+- **Anthropic** — 提供 Claude Code、Agent Skills 与插件系统
+- **Lance Martin** — 提供详尽的 Manus 架构分析
+- 基于 [Context Engineering for AI Agents](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
 
-## Contributing
+## 贡献
 
-Contributions welcome! Please:
-1. Fork the repository
-2. Create a feature branch
-3. Submit a pull request
+欢迎贡献！请：
+1. Fork 本仓库
+2. 创建功能分支
+3. 提交 Pull Request
 
-## License
+## 许可证
 
-MIT License — feel free to use, modify, and distribute.
+MIT License — 可自由使用、修改与分发。
 
 ---
 
-**Author:** [Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)
+**作者：** [Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)
 
-## Star History
+## Star 历史
 
 <a href="https://repostars.dev/?repos=OthmanAdi%2Fplanning-with-files&theme=copper"><img src="https://repostars.dev/api/embed?repo=OthmanAdi%2Fplanning-with-files&theme=copper" width="100%" alt="Star History Chart" /></a>