@maxiaochao/pi-toolkit 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-09-23 - v0.7.0
+
+- bundle the pi-worktree skill documenting the CLI for agents (the isolation loop, and which commands need an interactive terminal); fix pi-worktree: the .gitignore check tested a path form that never matched the directory-only .worktrees/ pattern, so the rule was re-appended on the first run in every repo and that self-inflicted edit then triggered the uncommitted-changes prompt
+
+## 2026-09-22 - v0.6.1
+
+- bundle the pdlog skill for decompressing Pudu .pdlog logs (with bundled ppmd binary)
+
 ## 2026-09-22 - v0.6.0
 
 - bundle the show-me skill for visual explanations (derived from humanlayer/skills, MIT), invoked explicitly with /skill:show-me

package/README.md

@@ -59,6 +59,8 @@ pi-worktree prune          # drop stale registrations for manually deleted dirs
 
 Typical loop: `pi-worktree start <name>` to start (Tab completes existing worktree names), commit inside Pi, `pi-worktree out` + `git merge <name>` to land the work, `pi-worktree remove <name>` to clean up. New branches are created from the branch you're currently on (or `HEAD` when detached), and the base commit is recorded in `branch.<name>.base` config so `info` can always tell you where the branch came from. Bash completion covers subcommands and existing worktree names (`pi-worktree feat<Tab>`).
 
+The bundled `pi-worktree` skill documents the CLI for agents: the `start`/`list`/`info`/`out`/`remove`/`prune` commands, the isolation loop from creating a worktree to landing the merge, and which of those commands need an interactive terminal (so an agent uses `start <name> -p "<task>"` for a headless nested run).
+
 The bundled `web-browser` skill provides reusable scripts for starting Chrome/Chromium with remote debugging, navigating tabs, evaluating JavaScript, emulating devices, taking screenshots, dismissing cookie dialogs, and inspecting browser logs. It auto-detects common Chrome/Chromium installations on macOS and Linux, including Windows Chrome when Pi runs under WSL; set `BROWSER_BIN` when the binary is elsewhere.
 
 The browser skill can be loaded explicitly with `/skill:web-browser`. Its scripts are available relative to the skill directory, for example:
@@ -81,6 +83,8 @@ Note: Chrome does not always write the `DevToolsActivePort` file (e.g. `--remote
 
 The bundled `show-me` skill (derived from [humanlayer/skills](https://github.com/humanlayer/skills), MIT) explains the current topic with the smallest visual that makes the point — pseudocode, call trees, component or file trees, diffs, Mermaid, or one focused HTML artifact. It is hidden from automatic skill selection, so invoke it explicitly with `/skill:show-me`.
 
+The bundled `pdlog` skill decompresses and reads Pudu `.pdlog` proprietary log files, which are binary gibberish when opened directly. It ships a self-contained `ppmd` decompressor (`skills/pdlog/tools/ppmd`, Linux x86-64) and triggers automatically on `.pdlog` files, Pudu logs, ppmd decompression, or logs that open as binary gibberish.
+
 ## Tiny Subagent
 
 The tiny subagent is a separate npm package. Install it independently when you want the `tiny_subagents` tool:

package/bin/pi-worktree

@@ -63,7 +63,11 @@ resolve_base() {
 }
 
 ensure_gitignore() {
-  if ! git check-ignore -q .worktrees 2>/dev/null; then
+  # The trailing slash is load-bearing: `.worktrees/` is a directory-only
+  # pattern, and git check-ignore cannot match it against a path that does not
+  # exist yet — so `.worktrees` would look unignored on every first run and the
+  # rule would be appended again.
+  if ! git check-ignore -q .worktrees/ 2>/dev/null; then
     printf '.worktrees/\n' >> .gitignore
     ok "added .worktrees/ to .gitignore"
   fi
@@ -233,12 +237,12 @@ cd_wt() {
   fi
 
   local dir; dir="$(wt_dir "$name")"
-  ensure_gitignore
 
   if [[ -d "$dir" ]]; then
     # Reuse: must be a registered worktree for this repo.
     # Skip the dirty-workspace prompt — the worktree already exists, nothing new to create.
     git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || die "$dir exists but is not a git worktree"
+    ensure_gitignore
     ok "reusing existing worktree $dir"
   else
     # Dirty workspace: uncommitted changes do NOT follow into the new worktree.
@@ -249,6 +253,9 @@ cd_wt() {
       [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
     fi
 
+    # After the check above, so the tool's own .gitignore edit is not reported
+    # as (and does not prompt about) the user's uncommitted work.
+    ensure_gitignore
     mkdir -p .worktrees
     # Reuse branch if it exists, else create it
     if git show-ref --verify --quiet "refs/heads/$name"; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [

package/skills/pdlog/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: pdlog
+description: 解压和查看 .pdlog 日志文件。触发：.pdlog 文件、普渡日志/Pudu 日志、日志打开是乱码或二进制、ppmd 解压
+---
+
+# pdlog
+
+`.pdlog` 是普渡专有压缩日志格式：`cat`/`head`/编辑器直接打开是二进制乱码——这是格式本身，不是文件损坏。先解压成纯文本再读。
+
+## 解压
+
+使用本 skill 目录的 `tools/ppmd`：
+
+```bash
+tools/ppmd -d input.pdlog output.log
+```
+
+- 只想预览不落盘：`tools/ppmd -d input.pdlog /dev/stdout | head -50`
+- 完成判据：`file output.log` 显示 text，`head` 能读到可读行。输出是二进制说明输入不是 pdlog，回到格式分叉。
+
+## 格式分叉
+
+- `.gz` 结尾：普通 gzip，用 `zcat`/`gunzip`，不经过 ppmd。
+- 拿不准：先 `file` 看类型。
+
+## 远端文件
+
+pdlog 在远端设备或机器上时，先取回本地（`adb pull` / `scp`），解压始终在本地跑。

package/skills/pi-worktree/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: pi-worktree
+description: Create, inspect, and clean up git worktrees with the pi-worktree CLI (start/list/info/remove/prune), which also launches Pi inside the worktree. Use when a task warrants isolation in its own worktree, or when the user asks to handle something the worktree way.
+---
+
+# pi-worktree
+
+`pi-worktree` wraps git worktree creation and Pi launch into one command. Worktrees live in `.worktrees/<name>` (added to `.gitignore`), each with a branch of the same name, branched from the branch you are on now (or `HEAD` when detached). The base commit is recorded in `branch.<name>.base` / `branch.<name>.baseRef` so `info` can always report where the branch came from.
+
+Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with bash completion for subcommands and existing worktree names.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `pi-worktree start <name> [pi args...]` | Create or reuse `.worktrees/<name>`, then launch Pi inside it. Already inside a linked worktree, it just launches Pi there. |
+| `pi-worktree start --base <ref> <name> [pi args...]` | Same, but branch from `<ref>` instead of the current branch. |
+| `pi-worktree list` | All worktrees; the main checkout is marked `(main checkout)`, stale registrations are flagged. |
+| `pi-worktree info <name>` | Clean/dirty status, branch and HEAD, base commit, ahead/behind `main`, unique commits. |
+| `pi-worktree out` | Open a shell in the main checkout (for merging). |
+| `pi-worktree remove <name>` | Remove the worktree and its branch; asks before discarding dirty files or unmerged commits. |
+| `pi-worktree prune` | Drop registrations whose directory was deleted by hand. |
+
+## Isolating a task
+
+1. **Survey** — `pi-worktree list`, plus `pi-worktree info <name>` when the name you want is already taken. Reuse is free; a removed worktree is gone for good, because `remove` deletes its branch.
+2. **Start** — `pi-worktree start <name>` (with `--base <ref>` when the work must not start from the current branch). Done when `list` shows the new worktree on its own branch.
+3. **Work** — inside the worktree: commit there, and check `pi-worktree info <name>` before claiming progress. `ahead: N commits since base` is the evidence.
+4. **Land** — `pi-worktree out`, then `git merge <name>` in the main checkout. Done when the worktree's unique commits are in the target branch.
+5. **Clean up** — `pi-worktree remove <name>`. A merged branch goes without prompting; anything unmerged asks once.
+
+## Driving it from an agent
+
+- `start` **execs `pi`** in the worktree, and `out` execs a shell. With no trailing Pi args both want an interactive terminal, so either run `start <name> -p "<task>"` for a headless nested run, or hand the bare `start <name>` to the user to run themselves.
+- `remove` asks before discarding dirty files or unmerged commits, and a non-interactive stdin (EOF) aborts safely. Answer explicitly when the removal is intended: `printf 'y\ny\n' | pi-worktree remove <name>`.
+- Your own working directory cannot change. "Isolate this in a worktree" therefore means launching a nested headless Pi in the worktree, or telling the user to run `pi-worktree start <name>`.