@ngockhoale/ukit 1.2.1 → 1.3.0

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.1",
+  "version": "1.3.0",
   "agent": "claude-code",
   "compact": {
     "enabled": true,
@@ -9,10 +9,9 @@
     "codexContext": {
       "enabled": true,
       "autoCompact": true,
-      "budgetTokens": 60000,
+      "budgetTokens": 100000,
       "compactTarget": 150,
       "compactTargetUnit": "lines",
-      "decisionModelEnv": "UKIT_SMALL_TASK_MODEL",
       "decisionAgent": "ukit-small-task-maintainer",
       "mode": "soft-handoff",
       "preserve": [
@@ -32,7 +31,6 @@
     },
     "agentContext": {
       "enabled": true,
-      "decisionModelEnv": "UKIT_SMALL_TASK_MODEL",
       "decisionAgent": "ukit-small-task-maintainer",
       "executionMode": "sidecar-parallel",
       "mustNotBlockMainTask": true,
@@ -88,6 +86,17 @@
     "maxRetries": 1,
     "confidenceThreshold": 50
   },
+  "safePatch": {
+    "enabled": true,
+    "strictSharedRisk": true,
+    "largeFileLineThreshold": 800,
+    "largeFileByteThreshold": 200000,
+    "backupEnabled": true,
+    "backupRetentionDays": 30,
+    "deltaMaxChangedLines": 120,
+    "deltaMaxHunks": 3,
+    "deltaMaxDiffCells": 2000000
+  },
   "subagents": {
     "enabled": true,
     "smallTaskModel": "unic-lite",
@@ -147,5 +156,145 @@
       "mustNotBlockMainTask": true,
       "maxSidecarWaitMs": 0
     }
+  },
+  "_help": {
+    "README": {
+      "muc_dich": "Đây là file cấu hình runtime duy nhất của UKit, khi install sẽ nằm ở .ukit/storage/config.json. Không dùng .env để chỉnh UKit nữa.",
+      "ai_nen_sua": "Người dùng bình thường vẫn chỉ cần nhớ `ukit install`. Maintainer hoặc power user mới cần sửa file JSON này để chỉnh cách UKit tự điều phối AI.",
+      "cach_sua": "Chỉ sửa value, không đổi tên key. Đây là JSON chuẩn: string phải dùng dấu nháy kép, có dấu phẩy giữa các field, không dùng // comment.",
+      "nguyen_tac_chat_luong": "Luôn theo UKit CoDev: chất lượng > an toàn > tốc độ > tiết kiệm token. Không chỉnh cho nhanh nếu làm AI trả lời kém hơn.",
+      "sau_khi_sua": "Sau khi sửa file này, nên mở session AI mới. Nếu muốn refresh template trong repo thì chạy lại `ukit install`."
+    },
+    "cac_chinh_sua_thuong_gap": {
+      "doi_model_noi_bo": {
+        "field": "subagents.smallTaskModel",
+        "mac_dinh": "unic-lite",
+        "y_nghia": "Model nội bộ chạy sidecar cho các quyết định nhỏ/an toàn của UKit. Không thay thế model chính đang làm task của user.",
+        "vi_du": "Đổi subagents.smallTaskModel sang tên model khác nếu unic-lite không dùng được hoặc bạn muốn model nội bộ khác."
+      },
+      "compact_codex_khi_gan_150k_token": {
+        "field": "compact.codexContext.budgetTokens",
+        "mac_dinh": 100000,
+        "co_the_tang_len": 150000,
+        "khuyen_nghi": "100000 là mức cân bằng: đủ context cho chất lượng nhưng tránh để phiên chạy tới 150k-180k token dễ gặp lỗi connection/capacity.",
+        "y_nghia": "Ngưỡng token context của Codex Desktop trước khi UKit chuẩn bị compact/handoff. Ví dụ 100000 nghĩa là gần 100k token thì compact."
+      },
+      "doi_do_dai_ban_tom_tat_codex": {
+        "field": "compact.codexContext.compactTarget",
+        "mac_dinh": 150,
+        "khoang_goi_y": [
+          120,
+          170
+        ],
+        "y_nghia": "Độ dài bản handoff sau compact, tính bằng dòng, không phải token. Không set 150000 ở đây."
+      },
+      "tat_auto_compact_codex": {
+        "field": "compact.codexContext.autoCompact",
+        "mac_dinh": true,
+        "y_nghia": "Chỉ set false khi đang debug hành vi compact của UKit."
+      }
+    },
+    "version": "Phiên bản config runtime đi kèm package UKit.",
+    "agent": "Adapter mặc định của workspace. Thường giữ nguyên theo lúc install.",
+    "compact": {
+      "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
+      "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
+      "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",
+      "askBeforeDrop": "Giữ thái độ thận trọng trước khi bỏ context quan trọng. Nếu rủi ro thì hand back cho main model.",
+      "agentContext": {
+        "enabled": "Bật policy compact context theo từng agent.",
+        "decisionAgent": "Agent nội bộ hỗ trợ quyết định compact/handoff trong trường hợp an toàn.",
+        "executionMode": "sidecar-parallel nghĩa là lane quyết định compact chạy song song với task chính.",
+        "mustNotBlockMainTask": "Nếu true, sidecar nội bộ không được dừng/thay thế/làm chậm task chính của user.",
+        "targets": {
+          "claude": {
+            "autoCompact": "Giữ compact lane của Claude bật.",
+            "mode": "precompact-reinject nghĩa là Claude được bơm context quan trọng trước/sau compact.",
+            "preserveExistingHooks": "Nên giữ true để không gỡ PreCompact/reinject của Claude."
+          },
+          "opencode": {
+            "autoCompact": "Giữ compact lane của OpenCode bật.",
+            "mode": "native-auto-prune nghĩa là OpenCode dùng compaction.auto/prune native.",
+            "preserveExistingCompaction": "Nên giữ true để không gỡ compact native của OpenCode."
+          },
+          "codex": {
+            "autoCompact": "Bật policy soft handoff compact cho Codex Desktop.",
+            "mode": "soft-handoff nghĩa là UKit tạo/dùng state tóm tắt, không can thiệp trực tiếp vào internals của app Codex.",
+            "compactTarget": "Độ dài bản handoff sau compact, tính bằng dòng.",
+            "compactTargetUnit": "Đơn vị của compactTarget. Nên giữ là lines.",
+            "compactTargetRecommendedRange": "Khoảng số dòng khuyến nghị cho bản handoff.",
+            "compactTargetMax": "Số dòng tối đa cho bản handoff, tránh lỡ tay set quá dài."
+          }
+        }
+      },
+      "codexContext": {
+        "enabled": "Bật policy soft context handoff cho Codex Desktop.",
+        "autoCompact": "Cho phép UKit tự quyết định compact/handoff khi context Codex dài.",
+        "budgetTokens": "Ngưỡng token context của Codex Desktop trước khi compact. Mặc định 100000 để cân bằng chất lượng và giảm lỗi capacity/connection. Có thể tăng 150000 nếu cần, nhưng không nên để quá dài.",
+        "compactTarget": "Độ dài bản handoff sau compact, tính bằng dòng, không phải token. Mặc định 150; nên 120-150; tối đa 170.",
+        "compactTargetUnit": "Đơn vị của compactTarget. Nên giữ là lines.",
+        "compactTargetRecommendedRange": "Khoảng số dòng khuyến nghị. Nên ở trong khoảng này nếu không có lý do đặc biệt.",
+        "compactTargetMax": "Số dòng tối đa cho bản handoff. Chặn trường hợp lỡ set 150000 dòng.",
+        "decisionAgent": "Agent nội bộ dùng cho quyết định compact an toàn.",
+        "mode": "soft-handoff nghĩa là UKit tóm tắt state để tiếp tục thay vì replay toàn bộ transcript.",
+        "preserve": "Những thứ bắt buộc phải giữ khi compact: mục tiêu, rule, file đang làm, quyết định, lỗi chưa xử lý, bằng chứng verify, bước tiếp theo."
+      }
+    },
+    "tokenPipeline": {
+      "inputCompression": "Nén/tái sử dụng input context khi an toàn.",
+      "outputCompression": "Tóm tắt output command ồn nhưng vẫn giữ recovery hint.",
+      "promptCache": "Dùng cache prompt/context compact để giảm lặp lại."
+    },
+    "router": {
+      "enabled": "Bật task routing nội bộ.",
+      "defaultModel": "Model hint cân bằng cho công việc bình thường. Adapter/provider có thể map khác.",
+      "advisorModel": "Model hint mạnh hơn cho planning/reasoning khó khi được bật.",
+      "advisorEnabled": "Cho phép advisor-style planning cho task phức tạp.",
+      "maxAdvisorCalls": "Giới hạn số lần gọi advisor để không lãng phí."
+    },
+    "memory": {
+      "enabled": "Bật memory local của UKit.",
+      "autoCapture": "Cho phép UKit lưu decision/rule bền vững khi an toàn.",
+      "progressiveRetrieval": "Lấy memory liên quan nhỏ trước, chỉ mở rộng khi cần.",
+      "maxInjectionTokens": "Số token memory tối đa được inject vào context.",
+      "archiveAfterDays": "Sau bao nhiêu ngày memory có thể được archive/compact.",
+      "maxSessions": "Số session memory gần đây giữ active.",
+      "redactSecrets": "Cố tránh lưu secret vào memory."
+    },
+    "validation": {
+      "enabled": "Bật kiểm tra output nhẹ.",
+      "autoRetry": "Cho phép retry an toàn một lần khi validation thấy lỗi rõ.",
+      "maxRetries": "Số lần retry tối đa.",
+      "confidenceThreshold": "Ngưỡng confidence tối thiểu trước khi báo thận trọng."
+    },
+    "subagents": {
+      "enabled": "Cho phép UKit dùng các lane subagent nội bộ khi hữu ích.",
+      "smallTaskModel": "Model sidecar nội bộ cho quyết định nhỏ/an toàn của UKit. Đổi key này nếu muốn đổi model nội bộ.",
+      "smallTaskAgent": "Tên agent nội bộ phụ trách quyết định nhỏ không block task chính.",
+      "smallTaskUseCases": "Các loại việc an toàn sidecar có thể xử lý: dọn task, compact decision, phân loại, triage, queue maintenance, workspace maintenance.",
+      "keepMainModelFor": "Các việc rủi ro phải giữ ở main model: security, code risky, release, data-loss, architecture, deep reasoning.",
+      "decisionPolicy": {
+        "nonBlocking": "Sidecar nội bộ không được block task chính của user.",
+        "endUserInvisible": "Không biến orchestration nội bộ thành thứ end user phải học.",
+        "handBackOnRisk": "Nếu sidecar thấy rủi ro thì trả lại main model quyết định.",
+        "executionMode": "sidecar-parallel nghĩa là việc nội bộ có thể chạy riêng/song song với task chính.",
+        "mustNotBlockMainTask": "True nghĩa là sidecar không được dừng/thay thế/làm chậm task chính.",
+        "maxSidecarWaitMs": "0 nghĩa là không chờ sidecar trước khi tiếp tục task chính.",
+        "optimizeOrder": "Thứ tự ưu tiên khi ra quyết định nội bộ.",
+        "decisions": "Nhóm quyết định sidecar được phép hỗ trợ.",
+        "stepBudgets": "Gợi ý số bước planning tối đa theo độ lớn task trước khi reassess."
+      }
+    },
+    "safePatch": {
+      "enabled": "Bật Safe Patch Protocol: UKit âm thầm chặn patch stale/ambiguous trên file rủi ro và giữ an toàn encoding khi helper nội bộ sửa file.",
+      "strictSharedRisk": "Nếu true, file runtime/shared-risk như .claude/hooks hoặc .claude/ukit sẽ bị guard chặt hơn; người dùng vẫn không cần nhớ command mới.",
+      "largeFileLineThreshold": "Số dòng từ đó file được xem là lớn và cần anchor/spec guard kỹ hơn.",
+      "largeFileByteThreshold": "Kích thước byte từ đó file được xem là lớn/rủi ro khi agent edit.",
+      "backupEnabled": "Nếu true, UKit tạo rollback bytes dưới .ukit/storage/backups cho edit rủi ro.",
+      "backupRetentionDays": "Số ngày giữ backup rollback cũ trong .ukit/storage/backups; UKit chỉ tự xoá folder backup có tên ngày hợp lệ YYYY-MM-DD.",
+      "deltaMaxChangedLines": "Ngân sách dòng đổi mặc định cho kiểm tra delta sau này.",
+      "deltaMaxHunks": "Ngân sách hunk đổi mặc định cho kiểm tra delta sau này.",
+      "deltaMaxDiffCells": "Giới hạn cell LCS khi tính delta; quá ngưỡng này UKit dùng fallback tuyến tính để tránh chậm trên file rất lớn."
+    }
   }
 }

package/templates/.claude/ukit/.env.example

@@ -1,17 +0,0 @@
-# UKit optional local runtime overrides.
-# Copy to .claude/ukit/.env only if you need machine-local overrides.
-# This is internal orchestration config; normal teammates still only need `ukit install`.
-
-# Lightweight model for the internal UKit small-task maintainer subagent.
-# Used for safe UKit decisions such as task cleanup, compact decisions,
-# doc summarization, classification, auto-triage, and queue maintenance.
-# It follows UKit CoDev principles: quality > speed > token savings.
-# Risky/shared/security/release/data-loss/architecture work must keep the main model.
-UKIT_SMALL_TASK_MODEL=unic-lite
-
-# Codex Desktop soft auto-compact handoff budget.
-# Target is compact handoff length (lines), not full app context tokens.
-# 120-150 is preferred; 170 lines is the hard max for this lane.
-UKIT_CODEX_AUTO_COMPACT=true
-UKIT_CODEX_CONTEXT_BUDGET=60000
-UKIT_CODEX_COMPACT_TARGET=150