DeepWorkPlan Vim

DeepWorkPlan Vim là trình soạn thảo trên terminal cho Deep Work Plan: một cấu hình Neovim dành cho con người, và cho các agent lập trình, làm việc trong terminal. Kế hoạch, tài liệu và chỉ mục của mọi lệnh chỉ cách bạn một phím bấm.

Đây là một sản phẩm riêng, được cung cấp dưới dạng addon vim tùy chọn của Deep Work Plan v7 (v7.0.0). Deep Work Plan hoạt động với bất kỳ trình soạn thảo nào hoặc không cần trình soạn thảo, và trình soạn thảo này cũng không yêu cầu Deep Work Plan: bạn thêm nó vào máy một cách độc lập, và nó hoạt động như một trình soạn thảo dù có kế hoạch hay không. Trang này mô tả bản phát hành v0.5.0.

Vì sao cần trình soạn thảo trên terminal cho Deep Work Plan

Một Deep Work Plan là một thư mục Markdown dưới .dwp/plans/: một mục tiêu, các tác vụ nguyên tử, các cổng kiểm chứng và một nhật ký liên tục. Con người xem xét nó, agent thực thi nó, và cả hai thường làm việc đó từ terminal. Một trình soạn thảo được xây dựng cho công việc này giữ ba thứ ở gần: chính kế hoạch, tài liệu xung quanh nó, và các phím giúp bạn di chuyển giữa hai thứ đó.

DeepWorkPlan Vim chính là trình soạn thảo đó. Nó là một cấu hình Neovim được chọn lọc — máy chủ ngôn ngữ, tự động hoàn thành, linting, định dạng, tìm kiếm mờ, cây tệp và các giao diện màu được chọn lọc, tải theo nhu cầu — cùng vài giao diện giúp nó trở thành trình soạn thảo cho Deep Work Plan.

Tham quan: một chỉ mục lệnh không thể lỗi thời

Nhấn SPC h h (Space là phím leader), hoặc chạy :DwpCommands, và trình soạn thảo liệt kê mọi phím tắt nó có kèm mô tả một dòng. Danh sách được tạo từ các phím tắt đang hoạt động, nên một phím tắt được định nghĩa ở bất cứ đâu đều xuất hiện trong chỉ mục mà không cần đăng ký, và chỉ mục không thể lỗi thời.

Đó là toàn bộ chuyến tham quan: khởi chạy nvim, rồi nhấn Space, h, h.

Bạn nhận được gì

Năm tính năng, mỗi tính năng chỉ cách một phím bấm.

Kế hoạch mà không cần rời trình soạn thảo

SPC P, :DwpPlans, hoặc một cú nhấp vào đoạn trên thanh trạng thái sẽ mở thanh bên kế hoạch. Nó bao quát mọi thư mục .dwp/plans/ trong thư mục hiện tại và thư mục cấu hình Neovim của bạn, và nhóm các kế hoạch bắt đầu từ những kế hoạch cần chú ý nhất. Trong trình soạn thảo, các nhãn là Working, Needs attention, Ready, Not started và Done. Mỗi kế hoạch có một thanh tiến độ.

Nhấn Enter trên một kế hoạch để mở trình đọc: mục tiêu trong một câu, trạng thái và tiến độ, danh sách tác vụ với tác vụ hiện tại được đánh dấu, và các liên kết nhảy bằng ngôn ngữ dễ hiểu tới các tệp của chính kế hoạch. Thanh trạng thái hiển thị kế hoạch đang hoạt động theo thời gian thực, còn màn hình khởi động liệt kê ba kế hoạch đầu. Các giao diện này chỉ giải thích kế hoạch; chúng không bao giờ ghi vào .dwp/.

Để đọc ngay tại chỗ các tệp Markdown của một kế hoạch, SPC m p xem trước bộ đệm hiện tại trong trình duyệt và SPC m r kết xuất nó ngay trong bộ đệm. Cả hai chỉ hoạt động trong bộ đệm Markdown.

Cài đặt

Việc cài đặt gồm ba lệnh: tải tập lệnh về, đối chiếu nó với SHA-256 của tệp mà trang này cung cấp, rồi chạy nó. Trình cài đặt ghim chính bản phát hành của nó, nên nó cài chính xác v0.5.0, bản phát hành mà trang này mô tả, trừ khi bạn chọn một phiên bản khác.

curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
echo "4890c140528d6b8d19b6bbc4102051e0b9dce2e26f43a693bdeab2e1cd8e196b  install.sh" | shasum -a 256 -c && \
bash install.sh

Theo thứ tự, trình cài đặt:

1. Kiểm tra hệ điều hành và trình quản lý gói của bạn, và cài git, curl và một trình thông dịch Lua nếu thiếu (không cài gì khi dùng --skip-packages).
2. Xác định phiên bản: bản phát hành của chính nó, hoặc bản mà --version yêu cầu.
3. Với --nvim X.Y.Z, cài bản phát hành Neovim đó vào ~/.local/opt, được xác minh theo SHA-256 mà Neovim công bố.
4. Hỏi trước khi chạm vào cấu hình Neovim hiện có. Khi không có terminal, nó dừng lại và không thay đổi gì, trừ khi --yes yêu cầu nó chuyển cấu hình đó sang một bên.
5. Sao chép (clone) kho mã vào ~/.config/nvim, hoặc cập nhật nếu nó đã ở đó.
6. Chạy lua install.lua của chính kho mã.
7. Cài các plugin ở chế độ headless rồi kiểm tra chúng, nên không cần thoát rồi mở lại. Với --strict, việc cài plugin thất bại hoặc không đầy đủ được coi là lỗi.

Tập lệnh được cung cấp ở đây là bản sao giống hệt từng byte của install.sh tại thẻ v0.5.0. Checksum của nó được cung cấp ngay bên cạnh, tại https://deepworkplan.com/vim/install.sh.sha256, nên bạn có thể xác minh tệp tải về bằng shasum -a 256 -c install.sh.sha256 (trên Linux, sha256sum -c install.sh.sha256). Để kiểm tra từ một nguồn thứ hai, hãy so sánh nó với dòng install.sh trong SHA256SUMS trên bản phát hành GitHub. Chạy bash install.sh --help để liệt kê mọi tùy chọn.

Chọn phiên bản

Theo mặc định, trình cài đặt cài bản phát hành của chính nó, v0.5.0. Để chọn phiên bản khác, hãy đặt DWP_VIM_VERSION hoặc truyền --version: cả hai đều làm cùng một việc, nên hãy dùng cách nào dễ đọc hơn, và cờ được ưu tiên hơn biến môi trường. Mỗi cách đều chấp nhận:

Sau khi tải về và kiểm tra checksum như trên:

# exact version
DWP_VIM_VERSION=0.5.0 bash install.sh
bash install.sh --version 0.5.0

# minimum floor: the newest stable release at or above 0.4.2
DWP_VIM_VERSION='>=0.4.2' bash install.sh

# latest stable release
bash install.sh --version latest

Hãy đặt mức tối thiểu trong dấu nháy, để shell không hiểu > là chuyển hướng. Phiên bản chỉ được phân giải thành các thẻ bản phát hành ổn định. Với một nhánh hoặc một commit, hãy đặt DWP_VIM_REF thay thế (DWP_VIM_REF=main đi theo main); một phiên bản và một ref mâu thuẫn nhau sẽ gây lỗi.

Container và CI

Trong một image hoặc một job CI, nơi không có terminal và thường không có quyền root, hãy tải về và xác minh tập lệnh, rồi chạy nó trong một bước với các cờ giúp kết quả có thể tái lập:

curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
curl -fsSL -o install.sh.sha256 https://deepworkplan.com/vim/install.sh.sha256 && \
sha256sum -c install.sh.sha256 && \
bash install.sh --version 0.5.0 --nvim 0.12.5 --skip-packages --strict

• --version 0.5.0 ghim bản phát hành của trình soạn thảo.
• --nvim 0.12.5 cài bản phát hành Neovim đó vào ~/.local/opt/nvim-v0.12.5, liên kết thành ~/.local/bin/nvim và được xác minh theo SHA-256 mà Neovim công bố (Linux và macOS).
• --skip-packages không cài gói hệ thống nào: image phải có sẵn git, curl và Lua.
• --strict thoát với mã khác 0 khi việc cài plugin ở chế độ headless thất bại hoặc để thiếu plugin.

Mỗi cờ đều có một biến môi trường tương ứng (DWP_VIM_VERSION, DWP_VIM_NVIM, DWP_VIM_SKIP_PACKAGES=1, DWP_VIM_STRICT=1). Chỉ thêm --yes khi image có thể đã chứa một cấu hình Neovim cần được chuyển sang một bên.

Yêu cầu và nền tảng

• Neovim 0.12 trở lên. Hãy tự cài, hoặc để trình cài đặt thêm một bản phát hành đã được xác minh bằng --nvim X.Y.Z (Linux và macOS).
• Lua: lua, lua5.4 hoặc luajit. Trình cài đặt sẽ thêm một cái nếu thiếu.
• macOS, Linux và WSL chạy trình cài đặt. Windows có cách cài thủ công được ghi trong README của kho mã: cài Neovim bằng winget, clone thẻ v0.5.0 vào %LOCALAPPDATA%\nvim, rồi chạy lua install.lua từ Git Bash.
• Cấp phép GPL-3.0: tự do sử dụng, nghiên cứu và sửa đổi.

Cập nhật, cố định phiên bản và gỡ cài đặt

Để cập nhật, hãy chạy trình cài đặt của một bản phát hành mới hơn, hoặc chạy bash install.sh --version latest. Chạy lại sẽ chuyển bản checkout DeepWorkPlan Vim hiện có sang bản phát hành được chọn, giữ nguyên các nhánh của bạn và không bao giờ đặt lại các chỉnh sửa cục bộ: khi các thay đổi hoặc commit cục bộ có thể bị mất, nó dừng lại và không thay đổi gì.

Để ghim một bản phát hành, hãy dùng --version (xem Chọn phiên bản); với một nhánh hoặc một commit, hãy đặt DWP_VIM_REF. Nên ưu tiên dùng bản phát hành: các bản phát hành trước v0.4.0 không có các thao tác kiểu VS Code, trình duyệt kế hoạch, trình xem Markdown hay trình cài đặt này.

# pin a specific release, here the previous one
curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
curl -fsSL -o install.sh.sha256 https://deepworkplan.com/vim/install.sh.sha256 && \
shasum -a 256 -c install.sh.sha256 && \
bash install.sh --version 0.4.2

Để gỡ cài đặt, chạy lua delete.lua từ thư mục cấu hình. Nó xóa cấu hình, plugin, dữ liệu Mason, bộ nhớ đệm và trạng thái, cùng bản sao phông chữ mà trình cài đặt đã tạo, và giữ nguyên tệp thực thi Neovim cùng các gói hệ thống của bạn.

cd ~/.config/nvim && lua delete.lua

Câu hỏi

Nó có ghi đè cấu hình Neovim của tôi không?

Không, nếu bạn chưa chấp thuận. Khi gặp một cấu hình không phải DeepWorkPlan Vim, lần chạy tương tác sẽ hỏi trước khi chuyển nó tới ~/.config/previous-deepworkplan-vim. Khi không có terminal, nó dừng lại và không thay đổi gì, trừ khi bạn truyền --yes để chuyển nó sang một bên mà không cần giám sát. Khi đường dẫn sao lưu đó đã tồn tại, nó luôn dừng lại và không thay đổi gì.

Nó có chạy trên Windows không?

Trình cài đặt không chạy trên Windows. Hãy dùng cách thủ công trong README của kho mã, hoặc chạy trình cài đặt bên trong WSL.

Tôi có cần Deep Work Plan để dùng nó không?

Không. Trước hết nó là một trình soạn thảo. Nó không cài đặt cũng không yêu cầu skill Deep Work Plan; trình duyệt kế hoạch chỉ đơn giản là chưa có gì để liệt kê cho tới khi có thư mục .dwp/plans/.

Addon vim của v7 dùng nó như thế nào?

Deep Work Plan v7 đề xuất trình soạn thảo này dưới dạng addon vim tùy chọn trong quá trình onboarding. Addon phát hiện bản cài đặt hiện có ở chế độ chỉ đọc, thông qua tệp addon/surface.json của trình soạn thảo, và chỉ đề xuất bản cài đặt được ghim phiên bản, đã xác minh checksum khi có sự đồng ý của bạn. Nó không bao giờ ghi đè cấu hình Neovim hiện có khi chưa được phê duyệt rõ ràng, và không bao giờ là bắt buộc.

Các agent lập trình dùng nó như thế nào?

Nó được xây dựng cho con người và cho các agent lập trình sống trong terminal. Các phím tắt của nó được cố định bằng kiểm thử hợp đồng, nên trí nhớ cơ bắp, và kỳ vọng của agent, vẫn còn qua các lần cập nhật.

Tôi nhận được phiên bản nào?

Trình cài đặt cài bản phát hành mà nó thuộc về — hiện là v0.5.0 — trừ khi bạn chọn phiên bản khác bằng --version hoặc DWP_VIM_VERSION: một phiên bản chính xác, một mức tối thiểu >= hoặc latest. DWP_VIM_REF nhận một nhánh hoặc một commit; DWP_VIM_REF=main đi theo main. Trang này mô tả bản phát hành v0.5.0, bản có đủ mọi tính năng được liệt kê ở đây.

Nó theo giấy phép nào và đến từ đâu?

GPL-3.0. Nó được phát triển từ mu-vim của Andrés M Prieto, và phần ghi công được giữ trong kho mã.

Mã nguồn và giấy phép

Mã nguồn nằm trong kho mã DeepWorkPlan Vim. Kho này công khai và theo giấy phép GPL-3.0, được phát triển từ mu-vim.

Các mục kit liên quan

• Devcontainer — môi trường phát triển tái lập được (addon đầu tiên)
• Dailybot — báo cáo vòng đời kế hoạch nhìn thấy được cho cả nhóm (addon thứ hai)
• AI Diff Reviewer — đánh giá cục bộ trong các Final Review của kế hoạch (addon thứ năm)
• Herdr — giao một tác vụ cho một agent ngang hàng trong một pane Herdr (v7)
• Agentkit — một lệnh cho mọi agent lập trình trên terminal, và ủy thác headless (v7)