pirl-framework-cli 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +70 -42
- package/LICENSE +21 -21
- package/README.md +49 -226
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,50 +1,78 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
3
|
+
All notable changes to this project are documented in this file. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [1.0.1] - 2026-10-25
|
|
8
|
+
|
|
9
|
+
Documentation and tests only: the CLI and the bundled framework (fw-1.1.0) are the same as in 1.0.0.
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- A [user guide](docs/user-guide.md) with the details of using PIRL: commands, keyboard shortcuts, `@`
|
|
14
|
+
attachments, how a run works, usage limits, settings, framework updates and where data is stored.
|
|
15
|
+
- Uninstallation steps in the README.
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- The README is now in English and introduces the product: highlights, requirements, installation, quick start,
|
|
20
|
+
documentation links, uninstallation and development.
|
|
21
|
+
- The changelog is now in English.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- The test suite no longer times out on slower Windows computers, where it stopped `npm test` and so
|
|
26
|
+
`npm publish`.
|
|
27
|
+
|
|
28
|
+
## [1.0.0] - 2026-10-25
|
|
29
|
+
|
|
30
|
+
First release, published on npm as `pirl-framework-cli`. Provider: Claude Code 2.1.281 or later. Bundled framework:
|
|
31
|
+
fw-1.1.0.
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- A terminal UI started with `pirl` in a Git repository, which becomes the target repository.
|
|
36
|
+
- `/pirl-plan`, `/pirl-implement` and `/pirl-review` run a PIRL layer through your Claude Code. Each role runs as
|
|
37
|
+
its own subagent, with permissions set per layer.
|
|
38
|
+
- Text typed without a `/` is a question, a standalone task or framework maintenance. When it asks for a layer,
|
|
39
|
+
the run suggests the matching command instead of running it.
|
|
40
|
+
- Questions during a run: pick an answer with the arrow keys, type its number, or write your own.
|
|
41
|
+
- `/resume` lists the runs of the repository that can continue and resumes the one you choose, even after the
|
|
42
|
+
TUI was closed.
|
|
43
|
+
- After each run, PIRL runs the framework's validator and checks the self-evaluation record. After Implement, it
|
|
44
|
+
checks that the changed files are within the Plan's allowed paths.
|
|
45
|
+
- Framework improvements made by a run are tested with the framework's own tests before PIRL offers to commit
|
|
46
|
+
them to the Hub; an improvement that fails the tests cannot be committed.
|
|
26
47
|
- `/framework`:
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
-
|
|
39
|
-
|
|
40
|
-
-
|
|
48
|
+
- update to the framework bundled with the CLI through a draft, with a three-way merge;
|
|
49
|
+
- resolve conflicts by keeping your version, taking the new one, letting the agent merge them, or editing by
|
|
50
|
+
hand;
|
|
51
|
+
- run the framework's tests before applying an update;
|
|
52
|
+
- undo the last update;
|
|
53
|
+
- view differences from the original, restore single files, and browse the history of improvements.
|
|
54
|
+
- `/plans` and `/records`: open a Plan, a review report or a record to see its details.
|
|
55
|
+
- Attach files and folders with `@`: paths of the repository are suggested as you type. Small text files are sent
|
|
56
|
+
with their content; large files and folders are sent as paths or file lists. On Windows, network (UNC) and
|
|
57
|
+
device paths are never read, except on the share that holds the repository or the home directory.
|
|
58
|
+
- Run progress: a spinner, a clock and what each role is doing; the full log of each run in `~/.pirl/logs/`.
|
|
59
|
+
- Token usage by kind (cache reads, cache writes, output, new input), including the roles', with its equivalent at
|
|
60
|
+
API list prices.
|
|
61
|
+
- 5-hour and weekly usage limits in the side panel, with percentage bars and reset times.
|
|
62
|
+
- Mouse wheel scrolling of the chat and panels, while dragging still selects text as usual.
|
|
63
|
+
- `/settings`: coordinator model (Sonnet by default), role model, reasoning effort for every role, parallel roles,
|
|
64
|
+
color scheme, light or dark background, glyphs, motion and mouse mode.
|
|
65
|
+
- `/doctor`, `/copy`, `/clear`, `/help` and `/exit`; paste with Ctrl+V; new lines with Shift+Enter, Ctrl+J or `\`
|
|
66
|
+
then Enter.
|
|
67
|
+
- A responsive layout from 40 columns, and support for Vietnamese input methods.
|
|
41
68
|
|
|
42
69
|
### Framework fw-1.1.0
|
|
43
70
|
|
|
44
|
-
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
(`"C:\Users\..."`)
|
|
71
|
+
- The details of self-evaluation moved to `self-evaluation.instructions.md`, with a JSON template for records. No
|
|
72
|
+
rule changed.
|
|
73
|
+
- Plans, reports and records use the computer's time zone instead of a fixed UTC+7.
|
|
74
|
+
- The validator reads quoted frontmatter strings literally. Before, a Windows path in `target_repo`
|
|
75
|
+
(`"C:\Users\..."`) was rejected, and the `\n` in `"D:\new-app"` became a line break.
|
|
49
76
|
|
|
77
|
+
[1.0.1]: https://github.com/tdmadc107/PIRL-CLI/releases/tag/v1.0.1
|
|
50
78
|
[1.0.0]: https://github.com/tdmadc107/PIRL-CLI/releases/tag/v1.0.0
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 tdmadc107
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 tdmadc107
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,266 +1,89 @@
|
|
|
1
|
-
# PIRL
|
|
1
|
+
# PIRL CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/pirl-framework-cli)
|
|
4
|
+
[](https://github.com/tdmadc107/PIRL-CLI/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
bằng agent CLI mà bạn đã cài và tự đăng nhập bằng subscription của mình. Bản 1.0 dùng Claude Code.
|
|
7
|
-
PIRL CLI không có màn hình đăng nhập riêng, không đọc, lưu hay chuyển tiếp credential của provider.
|
|
7
|
+
**Plan, implement and review code changes with a team of AI agents, from your terminal.**
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
PIRL CLI runs the [PIRL framework](pirl-framework/README.md) through the AI agent CLI you already use. Describe
|
|
10
|
+
the work, and PIRL turns it into a Plan, implements it and reviews the result, with specialist agent roles at
|
|
11
|
+
each step and the framework's own checks after each run.
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
PIRL CLI has no login of its own: it uses your agent CLI under your subscription and never reads, stores or
|
|
14
|
+
forwards its credentials.
|
|
12
15
|
|
|
13
|
-
|
|
16
|
+
## Highlights
|
|
14
17
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
| `/resume`, `/plans`, `/records`, `/copy`, `/help`, `/doctor`, `/settings`, `/clear`, `/exit` | Dùng được |
|
|
20
|
-
| Linux, macOS, Windows | Test tự động chạy trên cả ba (CI). Chạy thật với Claude Code mới thử trên Linux |
|
|
21
|
-
| Codex CLI, Gemini CLI, Copilot CLI | Chưa hỗ trợ (giai đoạn 4 của bản đề xuất) |
|
|
18
|
+
- **Plan → Implement → Review** as three commands, each handled by specialist agent roles.
|
|
19
|
+
- **Checked results**: every run is validated by the framework's tools before you see it as done.
|
|
20
|
+
- **Your repository stays yours**: runs never commit, push or switch branches.
|
|
21
|
+
- **A framework that improves itself**, with every change tested and left to your approval.
|
|
22
22
|
|
|
23
|
-
##
|
|
23
|
+
## Requirements
|
|
24
24
|
|
|
25
|
-
- Node.js 22
|
|
25
|
+
- Node.js 22 or later
|
|
26
26
|
- Git
|
|
27
|
-
- Python 3.9
|
|
28
|
-
- Claude Code 2.1.281
|
|
27
|
+
- Python 3.9 or later
|
|
28
|
+
- [Claude Code](https://code.claude.com/docs) 2.1.281 or later, installed and signed in
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
Support for Codex CLI, Gemini CLI and Copilot CLI is planned.
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
## Installation
|
|
33
33
|
|
|
34
34
|
```bash
|
|
35
35
|
npm install -g pirl-framework-cli
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
Cập nhật: `npm install -g pirl-framework-cli@latest`. Bản CLI mới không tự ghi gì vào framework của bạn. Nếu bản mới
|
|
41
|
-
kèm framework mới, header hiện "Có framework mới"; mở `/framework` để cập nhật khi bạn muốn.
|
|
42
|
-
|
|
43
|
-
Từ mã nguồn:
|
|
38
|
+
Verify the installation:
|
|
44
39
|
|
|
45
40
|
```bash
|
|
46
|
-
|
|
47
|
-
cd PIRL-CLI
|
|
48
|
-
npm run setup # cài thư viện, build, đóng gói và cài lệnh `pirl` cho toàn máy
|
|
41
|
+
pirl --version
|
|
49
42
|
```
|
|
50
43
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
Gỡ: `npm uninstall -g pirl-framework-cli`. Hub và cài đặt ở `~/.pirl` vẫn giữ lại; xoá tay nếu không cần.
|
|
54
|
-
|
|
55
|
-
Trên PowerShell, nếu gõ `pirl` báo "running scripts is disabled on this system", chạy
|
|
56
|
-
`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` một lần, hoặc gõ `pirl.cmd` thay cho `pirl`.
|
|
44
|
+
## Quick start
|
|
57
45
|
|
|
58
|
-
|
|
46
|
+
Start PIRL in the Git repository you want to work on:
|
|
59
47
|
|
|
60
48
|
```bash
|
|
61
|
-
cd
|
|
49
|
+
cd path/to/your-project
|
|
62
50
|
pirl
|
|
63
51
|
```
|
|
64
52
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
| Phím | Tác dụng |
|
|
68
|
-
| --- | --- |
|
|
69
|
-
| Enter | Gửi |
|
|
70
|
-
| Shift+Enter | Xuống dòng trong ô nhập. Cũng được: `\` rồi Enter, Ctrl+J, Alt+Enter |
|
|
71
|
-
| Ctrl+V | Dán từ clipboard (phím dán của terminal, chuột phải cũng được) |
|
|
72
|
-
| Tab | Hoàn thành tên lệnh đang chọn |
|
|
73
|
-
| ↑ / ↓ | Chọn lệnh gợi ý hoặc đáp án khi run hỏi; ngoài ra cuộn khung chat (khi chuột là "Bôi đen tự do", mặc định) hoặc xem lại nội dung đã gửi |
|
|
74
|
-
| Ctrl+P / Ctrl+N | Xem lại nội dung đã gửi |
|
|
75
|
-
| `@` | Đính kèm file hoặc thư mục (Tab/Enter chọn, Esc ẩn danh sách) |
|
|
76
|
-
| PgUp / PgDn, con lăn chuột | Cuộn khung chat hoặc bảng đang mở |
|
|
77
|
-
| Esc | Xoá ô nhập, đóng bảng đang mở, hoặc dừng run đang chạy |
|
|
78
|
-
| Ctrl+C | Dừng run đang chạy; khi không có run thì thoát |
|
|
79
|
-
|
|
80
|
-
Shift+Enter cần terminal báo được phím bổ trợ (giao thức bàn phím kitty): Windows Terminal 1.25 trở lên,
|
|
81
|
-
kitty, WezTerm, Ghostty, iTerm2. Với Windows Terminal bản cũ hơn, dùng Ctrl+J, hoặc thêm vào `settings.json`
|
|
82
|
-
một phím tắt `{"command": {"action": "sendInput", "input": "\n"}, "keys": "shift+enter"}`.
|
|
83
|
-
|
|
84
|
-
Copy: kéo chuột để bôi đen như mọi nội dung trong terminal; `/copy` copy nguyên câu trả lời gần nhất của PIRL.
|
|
85
|
-
Con lăn chuột cuộn hội thoại: terminal gửi con lăn thành phím ↑/↓, nên ↑/↓ cuộn hội thoại và Ctrl+P/Ctrl+N gọi
|
|
86
|
-
lại lệnh đã gõ. Cách này cần terminal có alternate scroll (Windows Terminal, VS Code, iTerm2, Terminal của macOS,
|
|
87
|
-
GNOME Terminal, kitty, WezTerm). Nếu con lăn không cuộn, chọn "Chuột: Con lăn của PIRL" trong `/settings`: con
|
|
88
|
-
lăn chạy trên mọi terminal, nhưng bôi đen phải giữ Shift khi kéo.
|
|
89
|
-
|
|
90
|
-
### Đính kèm file hoặc thư mục bằng `@`
|
|
91
|
-
|
|
92
|
-
Gõ `@` trong ô nhập để chọn file hoặc thư mục của target repo (ngoài git repo thì của thư mục đang đứng). Danh
|
|
93
|
-
sách lọc theo chữ bạn gõ tiếp và bỏ qua những gì `.gitignore` loại ra. Tab hoặc Enter trên một thư mục sẽ mở
|
|
94
|
-
thư mục đó để chọn tiếp. Thư mục đang mở luôn nằm đầu danh sách; Enter trên nó đính kèm cả thư mục. Esc ẩn danh
|
|
95
|
-
sách mà giữ nguyên chữ đã gõ. Gõ tay cũng được: `@src/orders/cancel.ts`, `@docs/`, `@~/specs/api.md`,
|
|
96
|
-
`@"thư mục có dấu cách/file.md"`.
|
|
97
|
-
|
|
98
|
-
Khi gửi, mỗi `@` trỏ tới một đường dẫn có thật được gửi kèm request. Dùng được cho mọi lệnh layer lẫn câu hỏi:
|
|
99
|
-
|
|
100
|
-
- file văn bản đến 100 KB: gửi kèm toàn bộ nội dung, tổng tối đa 300 KB một lần gửi;
|
|
101
|
-
- file lớn hơn, hoặc ảnh, PDF: gửi đường dẫn để agent tự đọc bằng Read;
|
|
102
|
-
- thư mục: gửi danh sách file (tối đa 300), agent đọc file nào cần.
|
|
103
|
-
|
|
104
|
-
Coordinator được dặn chuyển các đường dẫn này cho role liên quan, vì role không thấy tin nhắn gốc. Thư mục nằm
|
|
105
|
-
ngoài target repo được cấp quyền đọc cho run đó. Một `@` không trỏ tới đường dẫn nào, như `dev@shop.vn`, giữ
|
|
106
|
-
nguyên là chữ. Nội dung gửi kèm tính vào token vào của run.
|
|
107
|
-
|
|
108
|
-
Trên Windows, PIRL không đọc đường dẫn mạng hay thiết bị (`\\máy\thư-mục`, `//máy/thư-mục`, `\\?\…`) trong `@`,
|
|
109
|
-
trừ khi chính repo hoặc thư mục home nằm trên share đó: chỉ cần đọc thử, Windows đã kết nối tới máy kia và gửi
|
|
110
|
-
thông tin đăng nhập NTLM của bạn, mà `@` có thể nằm lẫn trong một đoạn văn bản dán vào.
|
|
111
|
-
|
|
112
|
-
### Một run diễn ra thế nào
|
|
113
|
-
|
|
114
|
-
1. `/pirl-plan <request>` (tương tự `/pirl-implement`, `/pirl-review`) chạy coordinator bằng Claude Code
|
|
115
|
-
của bạn, ở chế độ không tương tác. Mỗi role là một subagent riêng, chỉ có công cụ đúng với việc của role.
|
|
116
|
-
2. Khung chat hiện từng role đang làm gì. Khi thiếu quyết định của bạn, run dừng phần phụ thuộc và hỏi:
|
|
117
|
-
chọn bằng ↑↓ rồi Enter, gõ số, hoặc nhập câu trả lời khác.
|
|
118
|
-
3. Khi coordinator xong, PIRL CLI tự chạy validator của framework và kiểm tra record tự đánh giá. Sai thì
|
|
119
|
-
gửi coordinator sửa lại (tối đa 2 lần). Sau Implement, CLI kiểm tra file thay đổi có nằm trong
|
|
120
|
-
Allowed paths của Plan không.
|
|
121
|
-
4. Nếu run đã sửa file framework (tự cải tiến), CLI hỏi: commit vào Hub, giữ chưa commit, hay bỏ.
|
|
122
|
-
Trước khi hỏi, CLI chạy test của framework trên các file đã sửa; test lỗi thì không commit được, nên bỏ.
|
|
123
|
-
5. CLI gợi ý layer tiếp theo dưới dạng lệnh để bạn tự gõ; không tự mở layer nào.
|
|
124
|
-
|
|
125
|
-
Run không bao giờ commit, push hay đổi nhánh trong repo của bạn. Lệnh nằm ngoài quyền của run bị từ chối
|
|
126
|
-
("Đã chặn N lệnh ngoài quyền của run"). Đây là luật quyền đang hoạt động, không phải lỗi: run vẫn tiếp tục,
|
|
127
|
-
và run block liệt kê đúng lệnh bị chặn. Esc hoặc Ctrl+C dừng run; bấm Ctrl+C lần nữa để thoát ngay.
|
|
128
|
-
`/resume` mở danh sách các run còn chạy tiếp được của repo (đã dừng, lỗi, hoặc đang chờ trả lời), mới nhất
|
|
129
|
-
trước; chọn run bằng ↑↓ rồi Enter. Run chạy tiếp đúng session Claude Code của nó, kể cả sau khi đóng TUI.
|
|
130
|
-
|
|
131
|
-
Trong lúc run chạy, spinner và đồng hồ cho biết run còn đang làm; run block hiện từng role đang làm gì. Nhật ký
|
|
132
|
-
đầy đủ của mỗi run ghi vào `~/.pirl/logs/` (TUI không hiện nhật ký; nhật ký không tốn token). Nếu terminal
|
|
133
|
-
chậm, tắt "Hiệu ứng chuyển động" trong `/settings`.
|
|
134
|
-
|
|
135
|
-
`/plans` liệt kê Plan và report Review của repo; `/records` liệt kê record tự đánh giá. Chọn một mục rồi Enter
|
|
136
|
-
để xem chi tiết: nội dung Plan hoặc report; với record là kết quả, các role, vấn đề tìm thấy và cải tiến đã làm.
|
|
137
|
-
|
|
138
|
-
### Token và hạn mức
|
|
139
|
-
|
|
140
|
-
Mỗi run gọi Claude Code nhiều lần (coordinator và các role), và mọi lần gọi đều tính vào hạn mức
|
|
141
|
-
subscription của bạn. Bảng bên phải có mục "Hạn mức": phần trăm đã dùng của hạn mức 5 giờ và hạn mức tuần, kèm
|
|
142
|
-
giờ đặt lại. Số liệu lấy từ `/usage` của Claude Code lúc mở TUI (lệnh này không gọi model) và được cập nhật
|
|
143
|
-
sau mỗi run. Khi cửa sổ hẹp không có bảng bên phải, hạn mức hiện ở thanh trạng thái. Khi run xong, run block
|
|
144
|
-
hiện:
|
|
53
|
+
Then describe the work as a Plan:
|
|
145
54
|
|
|
146
|
-
|
|
147
|
-
-
|
|
148
|
-
|
|
149
|
-
mức trước khi run bắt đầu.
|
|
150
|
-
|
|
151
|
-
Phần lớn token là token đọc cache. Mỗi request gửi lại toàn bộ ngữ cảnh, nhưng phần đã có trong cache chỉ
|
|
152
|
-
tính 5% giá token đầu vào (Sonnet 5.5, Opus 5.5). Chi phí thật nằm ở token ghi cache (file đã đọc, kết quả
|
|
153
|
-
lệnh), token ra (gồm phần suy luận) và model được chọn.
|
|
154
|
-
|
|
155
|
-
Anthropic không công bố công thức đổi token ra phần trăm hạn mức. Cách ước lượng sát nhất là quy đổi theo
|
|
156
|
-
giá API, rồi so với phần trăm hạn mức mà run đã dùng. Sau vài run, bạn sẽ biết 1% hạn mức của gói mình
|
|
157
|
-
ứng với khoảng bao nhiêu đô la quy đổi.
|
|
158
|
-
|
|
159
|
-
`/settings` chỉnh các mục sau:
|
|
160
|
-
|
|
161
|
-
- model của coordinator: mặc định Sonnet. Theo giá API, Opus đắt gấp khoảng 2 lần, Fable gấp khoảng 5 lần.
|
|
162
|
-
- model của các role: mặc định giống coordinator.
|
|
163
|
-
- mức suy luận (effort), áp dụng cho coordinator và mọi role. Mặc định của Claude Code là medium. Claude Code
|
|
164
|
-
chuyển mức này thành một con số nội bộ, khác nhau theo model và phiên bản. Ví dụ Sonnet nhận low 4, medium 5,
|
|
165
|
-
high 10, xhigh 30; Opus nhận low 5, high 15, xhigh 40. Con số đó không phải thang điểm: model trả lời "10"
|
|
166
|
-
nghĩa là Sonnet đang chạy mức high.
|
|
167
|
-
- chuột: bôi đen tự do (mặc định), con lăn của PIRL, hoặc tắt.
|
|
168
|
-
- số role chạy song song.
|
|
169
|
-
|
|
170
|
-
PIRL CLI chỉ cấp cho run các công cụ nó dùng và không nạp MCP server của bạn. Nhờ vậy mỗi request gửi ít
|
|
171
|
-
ngữ cảnh hơn.
|
|
172
|
-
|
|
173
|
-
### Cập nhật framework: `/framework`
|
|
174
|
-
|
|
175
|
-
Mỗi bản CLI kèm một phiên bản framework gốc. Hub giữ hai nhánh: `upstream` là các bản gốc, `main` là bản gốc
|
|
176
|
-
cộng các cải tiến của bạn; các layer chạy trên `main`. `/framework` có các mục:
|
|
177
|
-
|
|
178
|
-
- **Cập nhật lên fw-x.y.z** (khi bản đi kèm CLI mới hơn):
|
|
179
|
-
1. CLI gộp bản mới vào một bản nháp của `main`; `main` chưa đổi gì.
|
|
180
|
-
2. File chỉ một bên sửa được nhận tự động.
|
|
181
|
-
3. Với mỗi file mà cả bản gốc mới lẫn cải tiến của bạn cùng sửa một đoạn, TUI hiện hai bên đã đổi gì, kèm
|
|
182
|
-
cải tiến nào và record nào đã tạo ra thay đổi của bạn. Bạn chọn: giữ bản của bạn, lấy bản gốc mới, để
|
|
183
|
-
agent gộp hai bản (bạn xem bản gộp rồi mới dùng), hoặc tự sửa trong bản nháp.
|
|
184
|
-
4. CLI chạy test của framework trên bản nháp. PASS thì `main` chuyển sang bản nháp; lỗi thì bản nháp bị bỏ
|
|
185
|
-
và Hub giữ nguyên.
|
|
186
|
-
- **Hoàn tác lần cập nhật lên fw-x.y.z**: đưa `main` về đúng như trước lần cập nhật đó.
|
|
187
|
-
- **Xem cải tiến cục bộ**: danh sách file khác bản gốc và diff từng file. Nhấn `r` để khôi phục file về bản
|
|
188
|
-
gốc (một commit mới; lịch sử vẫn giữ).
|
|
189
|
-
- **Lịch sử cải tiến**: các commit trên `main`, kèm record và nguồn (auditor, sửa tay, khôi phục, cập nhật).
|
|
190
|
-
- **File chưa commit**: commit hoặc bỏ trước khi cập nhật hay khôi phục.
|
|
191
|
-
|
|
192
|
-
`/framework` không thay đổi Hub khi đang có run, vì run đã ghim phiên bản framework.
|
|
193
|
-
|
|
194
|
-
### Dữ liệu nằm ở đâu
|
|
195
|
-
|
|
196
|
-
Lần chạy đầu tiên, PIRL CLI tạo Hub tại `~/.pirl/hub` (Windows: `%USERPROFILE%\.pirl\hub`): một git repo
|
|
197
|
-
cục bộ, không có remote, chứa framework đi kèm CLI.
|
|
198
|
-
|
|
199
|
-
| Dữ liệu | Vị trí |
|
|
200
|
-
| --- | --- |
|
|
201
|
-
| Plan và report Review (`/plans`) | Gốc Hub, mỗi Plan package một thư mục `<request-slug>_<YYYYMMDD-HHmmss>/`. `/plans` chỉ hiện các package có `target_repo` là repo đang mở |
|
|
202
|
-
| Record tự đánh giá (`/records`) | `~/.pirl/hub/.agents/evals/records/<layer>/`, lọc theo repo đang mở |
|
|
203
|
-
| Cài đặt | `~/.pirl/config.json` |
|
|
204
|
-
| Run cho `/resume` | `~/.pirl/sessions/<repo>/`, mỗi run một file, giữ 20 run gần nhất mỗi repo (chỉ lưu session id của Claude Code, không lưu credential) |
|
|
205
|
-
| Bản nháp khi đang cập nhật framework | `~/.pirl/hub-update/` (tự xoá khi cập nhật xong hoặc huỷ) |
|
|
206
|
-
| Nhật ký đầy đủ của từng run | `~/.pirl/logs/` |
|
|
55
|
+
```text
|
|
56
|
+
/pirl-plan Send customers an email when their order is cancelled
|
|
57
|
+
```
|
|
207
58
|
|
|
208
|
-
|
|
209
|
-
không bị commit ở đâu cả. Biến môi trường `PIRL_HOME` đổi thư mục `~/.pirl`.
|
|
59
|
+
PIRL suggests the next step when the Plan is ready. Type `/help` in PIRL for all commands and shortcuts.
|
|
210
60
|
|
|
211
|
-
|
|
61
|
+
## Documentation
|
|
212
62
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
63
|
+
- [User guide](docs/user-guide.md): commands, shortcuts, attaching files, settings, usage limits and framework
|
|
64
|
+
updates
|
|
65
|
+
- [PIRL framework](pirl-framework/README.md): the layers, roles and self-improvement behind PIRL
|
|
66
|
+
- [Changelog](CHANGELOG.md)
|
|
216
67
|
|
|
217
|
-
##
|
|
68
|
+
## Uninstallation
|
|
218
69
|
|
|
219
70
|
```bash
|
|
220
|
-
npm
|
|
221
|
-
npm test # toàn bộ test (Vitest)
|
|
222
|
-
npm run typecheck
|
|
223
|
-
python -B -m unittest discover -s pirl-framework/.agents/evals/tests -p "test_*.py" # test của framework
|
|
224
|
-
npm run pack:check # đóng gói như khi phát hành, cài vào thư mục tạm, chạy pirl --version và --help
|
|
71
|
+
npm uninstall -g pirl-framework-cli
|
|
225
72
|
```
|
|
226
73
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
### Phát hành
|
|
231
|
-
|
|
232
|
-
1. Cập nhật `version` trong `package.json` và mục mới trong `CHANGELOG.md`. Nếu framework đổi, tăng
|
|
233
|
-
`pirl.frameworkVersion`: Hub của người dùng so bản này với nhánh `upstream` để báo có framework mới.
|
|
234
|
-
2. Merge vào `main`, đợi CI xanh.
|
|
235
|
-
3. Tạo tag `v<version>` (ví dụ `git tag v1.0.0 && git push origin v1.0.0`). Workflow
|
|
236
|
-
`.github/workflows/release.yml` kiểm tra tag khớp `package.json`, chạy `pack:check`, đăng lên npm và tạo
|
|
237
|
-
GitHub release. Provenance chỉ được ký khi repo public. Workflow cần secret `NPM_TOKEN` (granular access
|
|
238
|
-
token của npm có quyền publish) trong Settings → Secrets and variables → Actions của repo. Một phiên bản
|
|
239
|
-
đã đăng thủ công (`npm publish` từ máy) thì workflow bỏ qua bước đăng, chỉ tạo GitHub release.
|
|
74
|
+
Your Hub, settings and run history stay in `~/.pirl` (`%USERPROFILE%\.pirl` on Windows). Delete that folder to
|
|
75
|
+
remove them as well.
|
|
240
76
|
|
|
241
|
-
|
|
242
|
-
dependency của Vitest.
|
|
77
|
+
## Development
|
|
243
78
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
bin/ điểm vào: pirl.ts đặt chế độ production rồi nạp main.tsx (tham số, target repo, Hub, TUI)
|
|
251
|
-
core/ chạy tiến trình, đường dẫn, cấu hình, xác định target repo
|
|
252
|
-
hub/ Hub git (nhánh upstream/main), framework đi kèm, cập nhật/hoàn tác/khôi phục (/framework)
|
|
253
|
-
providers/ nhận diện provider (Claude Code)
|
|
254
|
-
engine/ chạy layer: adapter Claude Code, quyền theo layer, subagent theo role,
|
|
255
|
-
giao thức với coordinator, kiểm tra sau run, dữ liệu Hub, lưu run cho /resume
|
|
256
|
-
doctor/ kiểm tra môi trường
|
|
257
|
-
commands/ danh sách lệnh và xử lý từng lệnh
|
|
258
|
-
ui/ TUI: theme, bố cục co giãn, ô nhập, run block, các bảng, App
|
|
259
|
-
test/ test logic và test giao diện ở nhiều kích cỡ cửa sổ
|
|
260
|
-
pirl-framework/ mã nguồn PIRL framework
|
|
261
|
-
docs/ bản đề xuất thiết kế
|
|
79
|
+
```bash
|
|
80
|
+
git clone https://github.com/tdmadc107/PIRL-CLI.git
|
|
81
|
+
cd PIRL-CLI
|
|
82
|
+
npm ci
|
|
83
|
+
npm run dev # run from source
|
|
84
|
+
npm test # run the tests
|
|
262
85
|
```
|
|
263
86
|
|
|
264
|
-
##
|
|
87
|
+
## License
|
|
265
88
|
|
|
266
|
-
[MIT](LICENSE)
|
|
89
|
+
[MIT](LICENSE)
|
package/package.json
CHANGED