02 / Tự cải thiện
Tự cải thiện: eval, trace và adapter
Soot dựa vào bằng chứng nào để tốt lên: eval, trace và token, soot improve, adapter, duyệt và hoàn tác.
Một Soot chạy thật sẽ sai theo những cách mà lúc viết mission chưa ai nghĩ tới. Soot tự cải thiện dựa trên bằng chứng chứ không dựa vào cảm giác: mỗi lỗi thành một eval case, mỗi lần chạy để lại trace có token, mỗi thay đổi chỉ được giữ khi đo lại thấy tốt hơn, và mọi thay đổi đã áp dụng đều hoàn tác được. Đây là trụ "bạn vẫn là người quyết định, Soot cải thiện theo bằng chứng" trong định vị của Soot (AGENTS.md, BRANDING.md §21).
Mọi thứ ở đây đã chạy được trong code (trừ phần "Chưa có" ở cuối). Nguyên tắc chung: không có gì tự áp dụng. Soot chỉ tạo đề xuất kèm số đo, người quyết định. Chỉ có một ngoại lệ, và người phải tự bật nó: bản tinh chỉnh adapter được tự dùng khi improve.auto_deploy có trong soot.json và phần kiểm tra giữ riêng cho thấy nó tốt hơn. Soot theo dõi bản đó và tự hoàn tác nếu làm việc tệ đi (Tự dùng bản tinh chỉnh). Thay đổi authored (chặng 1, chặng 3) thì không bao giờ tự áp dụng.
Mô hình tổng thể
run thật / run eval
│ ghi
▼
┌─────────────────────┐ "Không đúng ý" ┌──────────────────┐
│ trace + token │ ───────────────────► │ eval case │
│ (traces.db) │ soot eval case from │ soots/<id>/evals │
└─────────────────────┘ └────────┬─────────┘
▲ │ chạy qua conversation API
│ nhãn điểm, token ▼
│ ┌──────────────────┐
└───────────────────────────────── │ soot eval │ điểm, token, adapter digest
└────────┬─────────┘
│ case trượt
▼
0 Chẩn đoán ─► 1 Sửa authored ─► 2 Tinh chỉnh adapter ─► 3 Gộp vào authored
rule, miễn phí proposer + gate soot train (gate) luật bền → mission
diff chờ duyệt deploy khi người chọn diff chờ duyệt
│ │ │
└────── Áp dụng / Dùng bản này (người) ─────┘
│
biên nhận ─► --revertHai lớp harness của một Soot, và ai sửa lớp nào:
| Lớp | Nằm ở | Ai ghi | Sửa bằng |
|---|---|---|---|
Authored: soul, mission, skill, packs, execution, mô tả tool | soots/<id>/, packs/ | Người, hoặc proposer authored (chặng 1, 3) | Diff, review như code |
| Adapter: guidance và skill học được | soots/<id>/adapter/ | soot train (chặng 2) | Version, deploy / remove |
| Eval case: bài thi | soots/<id>/evals/, evals/ | Người, hoặc soot eval case from <run> | Không bao giờ do proposer sửa |
Adapter chỉ thêm vào authored, không sửa nó. Authored chữa gốc, adapter chỉ thêm chữ. Vì vậy thứ tự luôn là authored trước, adapter sau.
Khái niệm
Eval case. Một input cố định kèm cổng cứng (state, called, not_called, order, max_tool_calls, reply_includes…) và tùy chọn một judge. Chạy qua conversation API của runtime đang chạy, đúng đường soot run đi. Không có model loop riêng, không mock tool. Danh sách cổng đầy đủ: soot schema eval.
Trace. Bản ghi một run: header (Soot, origin, model, adapter digest, config revision), từng lượt model với token, từng tool call (ok, lỗi, bị chặn, lặp lại), kích thước context mỗi lượt, và các nhãn gắn sau. Trace là bằng chứng mà cả eval, chẩn đoán lẫn training đọc.
Weighted tokens. Đơn vị chung để so chi phí: input ×1 + cache write 5 phút ×1.25 + cache write 1 giờ ×2 + cache read ×0.1 + output ×5. Budget, soot usage, báo cáo eval và training đều dùng đơn vị này. Riêng việc so sánh candidate, training dùng token so sánh được (mọi token prompt ×1, output ×5) để cache lạnh của candidate không bị phạt oan.
Cần gạt (lever). Một thứ có thể sửa để chữa lỗi: wiring (groups, packs), bề mặt tool, mô tả tool, mô tả skill, mission, execution, hoặc adapter. Chẩn đoán xếp mỗi case trượt vào đúng một cần gạt.
Adapter. Thư mục soots/<id>/adapter/ gồm adapter.json (manifest của operator: phần nào được học, giới hạn byte), ADAPTER.md (nối vào cuối mission dưới ## Learned guidance), skills/*/SKILL.md, CARD.md (provenance). Mọi trace ghi digest của adapter đang chạy.
Proposer. Thứ đề xuất sửa đổi. Hoặc là một Soot trên cùng runtime (nên dùng model mạnh nhất), hoặc một chương trình của operator ({"program": [...]}: material vào stdin, proposal ra stdout), hoặc một coding agent làm theo skill soot-hillclimb.
Gate. Quy tắc nhận hay loại một thay đổi sau khi rollout lại các case. Đúng trước, rẻ token sau: token không bao giờ mua lại được độ đúng.
Held-out. Case val, test và pinned. Proposer không bao giờ thấy chúng; chúng quyết định nhận hay loại.
Evals: khóa hành vi
Case ở đâu, ID ra sao
Mỗi Soot giữ case của chính nó trong soots/<id>/evals/**/*.eval.json (soot spawn tạo sẵn smoke.eval.json). Case trải qua nhiều Soot nằm ở evals/ cạnh deployment.json. ID = ID Soot + đường dẫn file bỏ .eval.json + id của case (notes/smoke/answers); index.eval.json lấy tên thư mục. ID trùng là lỗi duplicate_eval. iterations: 3 nhân một case thành ba lần chạy để đo độ ổn định của model không tất định.
soot eval # mọi case
soot eval --tag smoke # theo tag
soot eval --soot ops # mọi case của một Soot
soot eval notes/delete/refuses # một case hoặc cả nhánh
soot eval --json > base.json && soot eval --baseline base.jsonExit 0 khi mọi case pass; 1 khi có failed (cổng không đạt) hoặc error (không có run để chấm: bị từ chối, hết giờ, mất kết nối, judge hỏng). Flag: soot eval --help.
Eval không gây hại
Mỗi case chạy trong một conversation origin `eval`:
- Memory cô lập. Soot không đọc và không ghi memory user/workspace; eval không dạy Soot điều gì về bạn và kết quả không phụ thuộc lần chạy trước. Knowledge gap và feedback từ eval không đi tới team.
- Dry run mặc định (
"effects": "dry_run"). Toolwrite/repaircủa pack chỉ chạy hooktool.preflight; Soot nhậndry run: …kèm bản xem trước hoặc lời từ chối. Tool host có hiệu ứng (write,bash,http_request…) cũng trảdry run:. Tool đọc chạy thật. Nhờ đócalled/ordervẫn khóa được quyết định gọi tool ghi mà chạy lại bao nhiêu lần cũng an toàn."effects": "live"cho phép chạy thật để kiểm end-to-end trên dữ liệu thử. - Không vào Cần bạn. Conversation
evalkhông hiện ở Cần bạn (xem bằngsoot attention list --include-evals); dọn bằngsoot conversations close --origin eval. - Chỉ đọc public events (
tool.started,tool.failed): tên tool và thứ tự, không bao giờ arguments hay output. - Cần operator token, và tốn model call thật. Nên chạy trên workspace dev.
Judge
Dành cho chất lượng không viết được thành cổng cứng. Judge là một Soot bình thường (ví dụ grader, không tool) chạy trong conversation riêng; câu trả lời đang chấm được rào bằng fence ngẫu nhiên và gửi như dữ liệu, verdict chỉ đọc từ dòng đầu (PASS hoặc FAIL: <lý do>). Judge hỏng không phải case fail: case thành error, không bị gắn nhãn trượt (để không làm bẩn dữ liệu train và chẩn đoán). Ưu tiên cổng cứng, dùng judge ít.
Điểm, token, nhãn
Report có score (trung bình tỉ lệ check đạt của mỗi case, mịn hơn pass/fail) và weighted_tokens cho cả bộ và từng case. Với --label (mặc định) mỗi run được gắn nhãn source: eval (tên = case ID, điểm, pass, check thất bại) vào trace, nên soot traces export --labeled lấy được dataset và soot usage --origin eval thấy chi phí của suite. --baseline so hai report: improved, regressed, new, missing. Một bước hillclimb đạt khi case đích improved và không gì regressed.
--adapter <dir|none> chạy case với một adapter ứng viên mà không deploy (overlay cố định lúc tạo conversation, runtime kiểm lại digest). Đó là cách đo adapter trên tập held-out và là cơ chế rollout của soot train.
Kho case: rẻ hơn chạy train
Eval là tài sản chính; thuật toán chỉ tốt bằng bộ case. Vì vậy tạo case phải rẻ.
- Từ run thật. Trên Nest, nút Không đúng ý ở một câu trả lời tạo case từ run đó. Trên CLI:
soot eval case from <run> --not-called spawn_subagent --reply-excludes "sẽ sửa" --pinned. Lệnh đọc tin nhắn từ trace (cầntraces.content: full, hoặc truyền--send), nối case vàosoots/<soot>/evals/captured.eval.jsonvới tagfrom-run. Run giữa một conversation thành case nhiều turn (các turn đầu chỉ kiểm state). Review file như code. - Tự chia tập. Thứ tự ưu tiên:
pinned>"split"trong case > tagtrain/val/test> hash của<soot>/<id case>(60% train, 20% val, 20% test, ổn định giữa các lần chạy; đổi tên hay chuyển file không đổi tập). Val dưới 8 case thìsoot trainvàsoot improve --diagnosecảnh báo. - `pinned: true` đánh dấu luật chính sách ("không hứa hoàn tiền", "tiền đã trừ phải chuyển người"). Case pinned luôn thuộc val và test, không vào material của proposer, và candidate làm trượt một case pinned mà bản cha đã đạt bị loại bất kể điểm.
- Không lộ đề thi.
soot traces exportmặc định bỏ run của case val, test, pinned hay case đã bị xóa (fail closed: xóa case không biến nó thành dữ liệu train).
Replay: đo trên cuộc trò chuyện đã ghi
soot eval replay --soot le-tan --cases cases.jsonl --report replay.json chạy một Soot trên các cuộc trò chuyện thật đã ghi (ví dụ export hỗ trợ khách), mỗi case là một conversation eval dry run, tool đọc có fixture khớp thì trả fixture. Report tính escalation_recall, over_escalation, forbidden_calls, unsourced_numbers, run_error_rate, p95_first_reply_ms, cost_usd; mỗi run cũng được gắn nhãn vào trace. Exit 0 nghĩa là replay chạy xong; cổng nhận hay loại là việc của bên đọc report. Hợp đồng đầy đủ và fixture: contracts/eval-replay.md.
Traces và token: bằng chứng
Mỗi run được ghi thành một trace ngay từ lúc bắt đầu. Ghi trace không thêm model call, không đổi hành vi, và một lần ghi lỗi không làm hỏng run. Dữ liệu ở traces.db cạnh state của runtime, đọc qua API operator.
soot traces list --since 24h
soot traces show <run>
soot traces label <run> --score 0.8 --passed --feedback "đúng nhưng dài"
soot traces export --format chat --passed --out sft.jsonl
soot usage --since 7dGiữ nội dung gì
traces.content trong deployment:
| Giá trị | Giữ gì |
|---|---|
shape (mặc định) | Token, thời gian, tên tool, trạng thái, kích thước, hash tham số. Không có text. |
full | Thêm input, output, tham số, kết quả tool, đã redact secret và cắt ngắn. |
off | Chỉ ledger token theo ngày. |
Hai quy tắc đè lên cấu hình: run của khách public luôn là shape; run origin: eval luôn là full (trừ off) vì đó là fixture của operator và training cần nội dung. Retention xóa trace cũ trước, rồi rút gọn trace lớn mà không bỏ số liệu.
Trace có gì
Header (Soot, origin, model, adapter digest), token (input, output, cache_read, cache_write, reasoning, weighted), context mỗi lượt, từng lượt, từng tool call (ok|error|blocked|invalid, repeat), compaction và nhãn. Một run dài chia nhiều slice vẫn là một trace. Nếu process chết giữa run, lần khởi động sau runtime chốt nó thành failed / runtime_interrupted, giữ số liệu đã ghi; mỗi token vào ledger đúng một lần. Chi tiết: soot traces show <run>, internal/feature/traces/types.go.
Budget
execution.max_run_tokens và execution.daily_tokens (weighted tokens, đặt ở deployment hoặc từng Soot). Ngân sách được kiểm tra lúc nhận run: run mới của Soot đã hết ngân sách ngày bị từ chối token_budget_exhausted (ngân sách ngày của đội cũng vậy, team_budget_exhausted). Run đã được nhận thì làm cho xong: vượt ngân sách (của run, của ngày, của đội hay budget_tokens của thư), nó nhận một lời nhắc chốt việc, và chỉ bị dừng ở gấp đôi ngân sách (BudgetOverrun), bằng một lượt kết thúc không tool với stop reason budget_exhausted. Phần vượt tính vào ngày, nên run sau bị chặn. max_cost và max_model_calls của job vẫn là trần chính xác. Run origin: eval vào ledger (eval_weighted_tokens) nhưng không trừ daily_tokens, nên cải thiện ban đêm không làm hết ngân sách chat thật; chúng bị giới hạn bằng budget của train/improve.
soot usage: audit token
Đọc trace trong một cửa sổ và in khuôn token-audit: tách input / cache / output, cache hit (lượt đầu và lượt sau), background mỗi lượt (instructions, skill, schema tool, phần system prompt runtime tự thêm), carry (kết quả tool lớn bị mang qua các lượt sau), friction (tool lỗi, bị chặn, gọi lặp, dừng vì budget) và danh sách proposals xếp theo saving ÷ risk, mỗi dòng nêu đúng setting cần đổi. --json cho automation. Gợi ý của soot usage đi vào chẩn đoán chặng 0 như cần gạt chặng 1. Đây là đầu vào đo token; nó không tự đổi gì.
Outcomes
Outcomes (đơn vị việc xong mà pack khai báo, tính kèm chi phí) hiện chưa là đầu vào của vòng cải thiện trong code: improve và train không đọc chúng. Nest hiển thị báo cáo tự cải thiện cạnh outcomes (mục Kết quả), nhưng nối "outcome tụt thì mở case" mới là hướng đi (workspace.md).
Cải thiện: pipeline bốn chặng
soot improve <soot> và nút Cải thiện ở tab của Soot trong Nest chạy cùng một pipeline. Chặng 0 miễn phí, chặng 1 và 3 sinh diff chờ duyệt, chặng 2 sinh version adapter.
Chặng 0: Chẩn đoán (rule, không model)
soot improve ops --diagnose xếp mỗi case trượt vào một cần gạt, từ tín hiệu trong trace và soot info. Chỉ tính eval run của adapter đang deploy; judge lỗi không tính là trượt; case nhiều turn trượt khi bất kỳ turn nào trượt.
| Tín hiệu trong trace | Cần gạt | Chặng |
|---|---|---|
| Tool trả "not found", thành viên group không gọi được theo tên | Wiring: groups, default_groups, packs | 1 |
Gọi tool ngoài việc của Soot (spawn_subagent, learn, memory_edit, ask), bề mặt tool lớn | Bề mặt tool: packs (pack so với pack:read), execution | 1 |
| Tool lỗi tham số, gọi lặp | Mô tả/tham số tool (pack bên thứ ba: đề xuất cho chủ pack) | 1 |
| Đọc sai skill hoặc đọc nhiều skill | Mô tả skill | 1 |
Trượt case pinned, trả lời trái luật | Mission/skill | 1 |
| Dừng vì giới hạn lượt/budget, bị hỏi lại | execution, hợp đồng runtime | 1 |
| Đúng tool, đúng luật; sai chi tiết hoặc tốn token | Adapter | 2 |
| Kỳ vọng của case mâu thuẫn hoặc sai | Sửa case | Người |
Lý do có chặng này: bộ eval hỗ trợ khách Lohi baseline chỉ đạt 2/12 case. Training lên adapter "tăng điểm" nhưng phần lớn là nhiễu, vì gốc là wiring (một group làm mất toàn bộ tool của pack). Gỡ group đó bằng sửa authored đưa lên 13/14. Một adapter không chữa được lỗi wiring, và một val nhỏ chấp nhận cả nhiễu. Vì vậy chẩn đoán đọc cả kết quả tool ("not found"), không chỉ tên tool.
Chặng 1: Sửa authored (proposer mạnh, cần duyệt)
soot improve ops --propose --proposer <soot-mạnh>:
- Proposer đọc toàn bộ phần authored, kết quả chẩn đoán và trace các case trượt, rồi đề xuất một cần gạt mỗi vòng (tối đa 3 vòng) dưới dạng patch. Định dạng thường
LEVER:/RATIONALE:/=== EDIT <tệp>với--- FIND/--- REPLACE, hoặc một object JSON;REFER <pack>: …cho pack của bên thứ ba. Proposer không được bịa dữ kiện (giờ mở cửa, giá, tên) mà file và case không nêu. - Mỗi patch được dựng thành một workspace thử và rollout trên mọi case train + val (có
iterations) bằng một runtimesoot serve --trial: runtime tạm thời chỉ trả lời conversation API, không chạy schedule hay improve định kỳ của bản sao. - Gate: patch bị loại nếu làm trượt case
pinned, hoặc không tăng điểm. Quyết định được đo hai lần (rollout lại bản sửa mà gate sắp nhận, vì một lần rollout của model không tất định có thể chỉ là may);--no-confirmbỏ bước này, rẻ hơn nhưng nhiễu hơn. - Bản sửa bị case
pinnedchặn được giữ lại một vòng: có khi nó làm lộ lỗi mà nó đang che, vòng sau kéo cần gạt mission trên nền bản sửa đó và hai thay đổi được gate như một. - Cuối cùng chấm tập
test(được giữ lại đến đây), ghi.soot/improve/<soot>/proposal/{proposal.json,changes.diff}. Đó là diff chờ duyệt.
Phạm vi sửa: soots/<id>/ (mission, soul, packs, execution, skill riêng) và pack local trong packs/. Không bao giờ sửa evals/ (chấm điểm, không phải cần gạt), adapter/ (của chặng 2) hay bin/. Pack vendored hoặc từ Forge không bao giờ bị sửa tại chỗ.
soot improve ops --status xem kết quả; --apply là hành động của người: ghi đề xuất đã duyệt (hoặc nút Áp dụng trong Nest). Ngân sách --budget / improve.budget tính bằng weighted tokens.
Chặng 2: Tinh chỉnh adapter (soot train)
Chỉ mở khi chẩn đoán không còn case thuộc chặng 1 và không còn diff authored chờ duyệt (--tune, khóa sau chặng 1; operator ép được, kết quả mang nhãn cảnh báo). soot train cũng chạy độc lập:
soot adapter init ops # soots/ops/adapter/ rỗng
soot train init nightly --soot ops # train/nightly.train.json
soot train nightly # tiến hóa adapter, checkpoint mỗi bước
soot adapter diff none .soot/train/nightly/versions/v0005
soot eval --adapter .soot/train/nightly/versions/v0005 --tag test
soot adapter deploy .soot/train/nightly/versions/v0005
soot adapter remove opsMỗi bước: lấy mẫu minibatch từ train, dựng learning material (adapter hiện tại và giới hạn, đoạn mission authored, danh sách skill authored, case train trượt kèm hình dạng tool call, tối đa 5 case đạt, dữ liệu token từng case và từng tool, 5 bước gần nhất), proposer trả rationale + guidance + skills, runtime check (nằm trong manifest, là edit có giới hạn max_edit_bytes, sai thì repair tối đa 2 lần), rollout candidate trên cùng minibatch, thuật toán quyết định.
algorithm | Giữ candidate khi | Hợp với |
|---|---|---|
continual | objective minibatch không giảm; không cần val | Rẻ nhất, học liên tục |
gate (mặc định) | minibatch không giảm và objective val tăng quá min_gain | Mặc định an toàn |
pareto | objective minibatch tăng; cha rút từ frontier theo số case val mà nó tốt nhất | Nhiều kiểu case |
compress | điểm không giảm và token mỗi case giảm | Sau khi đã đạt điểm: cắt token |
Hai mục tiêu, đúng trước tiết kiệm. Điểm giảm quá score_tolerance thì loại, dù tiết kiệm bao nhiêu token. Còn lại phải tăng objective = score − token_weight × (token/case ÷ token/case ban đầu) (token_weight mặc định 0.1): cùng điểm mà ít token hơn là tiến bộ.
Chống overfit và chống học luật sai:
- Proposer chỉ thấy train; val quyết định; test chỉ chấm một lần ở cuối (cho
none, adapter ban đầu và best). - Case
pinnedkhông vào material; candidate trượt nó bị loại. Khi không có val (continual, compress), runtime vẫn chấm riêng các case pinned cho bản cha và candidate. - Lịch sử bước proposer thấy chỉ có loại quyết định, không có điểm val hay ID case pinned.
- Material nêu hợp đồng runtime (câu trả lời cuối phải có
STATUS: DONE; adapter dạy dòng cuối khác sẽ bị hỏi lại và nhân đôi token), danh sách skill authored, và luật "adapter không bao giờ đi ngược authored". Luật này có vì một adapter từng học cấmread_skillvà hứa "sẽ sửa" chương lỗi, trái mission. Khóa chính sách bằng casepinned, và luôn reviewsoot adapter difftrước khi deploy.
State nằm ở .soot/train/<name>/ (state.json, index.jsonl, report.md, versions/vNNNN/, material/), không vào bundle. Dừng ở budget.steps, budget.tokens (rollout cộng proposer) hoặc budget.rollouts; Ctrl-C giữ nguyên state, --resume làm lại bước dở. soot train status <name> in report.
Chặng 3: Gộp vào authored
soot improve ops --graduate: luật adapter đứng vững qua nhiều version được proposer authored viết lại vào mission/skill (diff chờ duyệt), rồi adapter bắt đầu lại từ rỗng. Adapter vì thế luôn ngắn và luật đã chứng minh trở thành config thật. Hai dòng được coi là một luật khi chung ít nhất nửa số từ và phủ định cùng những điều (không, chưa, cấm, never…), nên "never promise refunds" không bị coi là cùng luật với "always promise refunds". Bước kiểm tra mâu thuẫn đối chiếu luật với mission/skill; có mâu thuẫn thì dừng ở conflicts, không tạo diff.
Model nào cho vai nào
| Vai trò | Model |
|---|---|
| Chẩn đoán | Không model (rule) |
| Proposer authored (chặng 1, 3) và kiểm tra mâu thuẫn | Mạnh nhất workspace có |
| Proposer adapter (chặng 2) | Trung bình trở lên |
| Rollout (chạy case) | Luôn là model của Soot: đo bằng model khác là đo sai thứ |
Proposer chỉ chiếm chừng một phần mười chi phí (phần lớn là rollout), nên muốn rẻ thì giảm rollout, không hạ cấp proposer. Chọn proposer bằng --proposer, hoặc proposer.soot trong file train.
Ai kích hoạt gì
| Ai | Cách | Giới hạn | ||||
|---|---|---|---|---|---|---|
| Người (CLI) | soot improve …, soot train …, soot adapter deploy/remove, soot eval case from | Là bên duy nhất áp dụng và hoàn tác | ||||
| Người (Nest) | Tab Cải thiện của Soot: Chẩn đoán → Sửa cấu hình → Tinh chỉnh → Gộp, nút Áp dụng / Bỏ / Hoàn tác, Không đúng ý trên câu trả lời | Qua POST /v1/improve (operator) | ||||
| Lead (Đầu mối của workspace) | soot manage có hai lệnh: improve.status (đọc, kèm tín hiệu, số bài nháp và bản tự dùng) và improve.run (lần chạy tự động soot improve <soot> --auto, trigger lead, budget mặc định 500000, tối đa 2000000) | Không áp dụng, không bỏ, không đặt lịch, không nhận bài nháp. Từ chối khi không có case (no_eval_cases), đang chạy (improve_running) hay đã có đề xuất chờ (improve_pending) | ||||
| Lead, cả workspace | improve.ru | status | apply | revert | history với scope: "workspace" (cùng job với soot improve --flows), improve.drafts.accept cho bài nháp có nguồn flow:<id>` | Budget trên 500000 là tiền: improve.run bị giữ, Lead gọi manage_gated, người duyệt thẻ ở Cần bạn. Mọi thứ khác Lead tự áp dụng và tự hoàn tác; xem contracts/lead.md |
| Soot (hội thoại) | Tool save_skill của pack soot: lưu một cách làm nó vừa tìm ra (các bước và code trong khối fenced) thành skills/<tên>/SKILL.md trong thư mục của chính nó, cạnh soot.json và các skill người viết | Mỗi lần lưu chờ người duyệt đúng nội dung skill ở Cần duyệt (approval: operator; operator có thể bỏ qua approval.policy). File mang dòng saved-by: save_skill: Soot chỉ thay skill nó đã lưu, không đụng skill người viết (xóa dòng đó là skill thành của người), skill của pack hay adapter. Tối đa 16 skill đã lưu, mỗi skill 16 KB; Soot deploy từ repo bị từ chối. Validate, khôi phục khi lỗi, có biên nhận (skill_save), soot improve <soot> --revert hoàn tác. Áp dụng khi runtime nạp lại lúc rảnh | ||||
| Lịch | "improve" trong soot.json; runtime chạy soot improve <soot> --scheduled | Chỉ tạo đề xuất; adapter chỉ tự dùng khi có auto_deploy | ||||
| Watch (runtime tự đọc trace) | "improve": {"watch": {…}}; khi một tín hiệu vượt ngưỡng, runtime chạy soot improve <soot> --auto --trigger watch | Cùng giới hạn với lịch; nghỉ cooldown giữa hai lần; không chạy khi lịch tạm dừng, đang có job, có đề xuất chờ hoặc đang theo dõi một bản tự dùng |
Lịch cải thiện (tùy chọn, mỗi Soot một lịch, chỉ operator đặt):
"improve": {"every": "24h", "at": "03:00", "timezone": "Asia/Ho_Chi_Minh",
"budget": 500000, "min_failing": 1}Mỗi lần chạy: chạy eval toàn bộ; dưới min_failing thì healthy; còn đề xuất chưa xem thì waiting_review (không đè); còn lỗi cấu hình thì chặng 1; không thì chặng 2. every từ 6h; budget bắt buộc và gồm cả eval lẫn sửa; lần lỡ không chạy bù; không chồng lên job đang chạy. Ngõ cụt không bị chạy lại: mỗi lần ghi fingerprint (nội dung các tệp trong phạm vi sửa, case eval, proposer); nếu lần trước kết thúc no_change và fingerprint chưa đổi thì lần này không tốn gì.
Một Soot chỉ có một job cải thiện tại một thời điểm: propose, tune, graduate, scheduled, auto, apply, revert và adapter deploy/remove cùng giữ khóa .soot/improve/<soot>/job.lock; lệnh thứ hai bị từ chối improve_running (HTTP 409). Trong cùng một tiến trình, khóa cho phép lấy lại: lần chạy tự động đang giữ khóa vẫn gọi được soot adapter deploy.
soot improve <soot> --auto là đúng lần chạy của lịch nhưng bắt đầu ngay, do người (--trigger manual), Lead (lead) hoặc watch (watch, kèm --signal) gọi. Soot chưa có lịch thì dùng --budget (mặc định 500000). Khi người hoặc Lead hỏi, Soot bỏ qua lối tắt "chưa có gì thay đổi": họ hỏi tức là muốn đo lại.
Theo dõi tín hiệu
Lịch chạy theo giờ, còn watch chạy theo bằng chứng. Mỗi check, runtime đọc trace của các lần chạy thật trong window (bỏ run eval, dry run và run đang chạy) mà không gọi model, không tốn token:
| Tín hiệu | Đo gì | Ngưỡng mặc định |
|---|---|---|
failed_rate | Tỷ lệ run hỏng: failed, hết budget token, bị ngắt (huỷ do người thì không tính) | trên 20% |
tool_error_rate | Tỷ lệ lần gọi tool bị lỗi hoặc bị chặn | trên 20% |
memory_writes_per_run | Số lần gọi learn / memory_edit trên mỗi run. Soot cứ phải ghi chú cho mình tức là nó đang sửa cách làm từng lần một, thứ đáng sửa tận gốc trong cấu hình | trên 1 |
pass_rate | Tỷ lệ case đạt ở lần eval gần nhất trên adapter đang dùng | dưới 80% |
"improve": {"every": "24h", "budget": 500000,
"watch": {"window": "24h", "check": "1h", "cooldown": "24h", "min_runs": 20,
"failed_rate": 0.2, "tool_error_rate": 0.2,
"memory_writes_per_run": 1, "pass_rate": 0.8, "draft_cases": 3}}Mọi trường đều tuỳ chọn; ngưỡng 0 tắt tín hiệu đó. Ba tỷ lệ đầu chỉ được xét khi có ít nhất min_runs run (vài run lẻ chỉ là nhiễu). pass_rate đo trên bộ eval nên không cần số run. Có tín hiệu vượt ngưỡng thì runtime chạy lần tự động, signal ghi các tín hiệu đó dạng tên=giá trị/ngưỡng nối bằng dấu phẩy (ví dụ failed_rate=0.35/0.2) để Nest tự diễn đạt. Lần chạy đó vẫn đo bộ eval trước: nếu bộ eval không bắt được điều watch thấy, nó kết thúc healthy và nói vậy, kèm lời nhắc nhận các bài nháp bên dưới. Lần watch sau, nếu chưa có gì thay đổi (cùng fingerprint: tệp authored, các case, proposer), nó không đo lại mà ghi unchanged với basis: "healthy", không tốn token. Chỉ watch bỏ qua kiểu này; lịch vẫn đo theo nhịp của nó, còn người hay Lead hỏi thì luôn đo lại. Nhận một bài nháp là đổi bộ case, nên lần watch kế tiếp đo lại. check ít nhất 15 phút, cooldown ít nhất 6 giờ và tính cả lần chạy của lịch.
soot improve <soot> --signals (hay GET /v1/improve/{soot}/signals) in đúng những con số watch đọc. Lần đọc gần nhất, kèm việc watch đã làm hay lý do chưa làm, nằm ở .soot/improve/<soot>/watch.json và trong signals của GET /v1/improve. Lý do chưa làm có hai dạng: held là câu tiếng Anh cho log, hold là mã cho màn hình (guarding, paused, cooldown, busy, review, no_cases, failed), kèm hold_until khi biết lúc nào hết.
Trong Nest, tab Cải thiện có khối Tự phát hiện vấn đề. Công tắc lưu improve.watch qua cùng soot.improve với lịch: bật khi chưa có lịch thì bật luôn Tự cải thiện (mỗi ngày 03:00, ngân sách mặc định), tắt thì bỏ watch và auto_deploy nhưng giữ lịch. Khối hiện bốn chỉ số so với ngưỡng (Vượt ngưỡng, Ổn, Chưa đủ dữ liệu, Đã tắt), số run đã đọc, lần đọc cuối, lý do chưa chạy, số bài nháp đang chờ kèm nút mở Cần bạn, và ô Tự dùng bản tinh chỉnh (auto_deploy).
Bài kiểm tra nháp
Watch cũng soạn case từ những run hỏng, mới nhất trước, tối đa draft_cases mỗi lần đọc và không quá 20 bài chờ. Bài nháp dùng cùng cách soạn với nút Không đúng ý: tin nhắn của run làm send, điều kiện là run phải xong, và nếu có tool lỗi thì không được có tool lỗi. Bài nháp nằm ở .soot/improve/<soot>/drafts/, hiện trong Cần bạn (Nhận vào bộ kiểm tra / Bỏ) và trong soot improve <soot> --drafts [--accept <id> | --discard <id>].
Thẻ trong Cần bạn nói bằng lời: tin nhắn, câu Soot đã trả lời (lưu cùng bài nháp, tối đa 2000 ký tự), bài đạt khi nào, và lời nhắc khi bài chỉ kiểm tra "làm xong, không lỗi" mà chưa xét nội dung câu trả lời. Dữ liệu gốc của bài nằm trong mục thu gọn. Các trường này đi trong payload của mục (send, earlier, reply, checks, loose, problem, run).
Trước khi người nhận, bài nháp không được đo, không dùng để huấn luyện, cũng không chặn thay đổi nào. Bộ eval là đề thi, và Soot không tự ra đề cho mình. Nhận rồi thì bài vào captured.eval.json như mọi case khác, và chia train/val/test theo hash như thường. Watch không soạn lại một run đã soạn, cũng không soạn hai bài cho cùng một tin nhắn. Run không có nội dung (traces.content không phải full, hoặc khách vãng lai) không soạn được.
Tự dùng bản tinh chỉnh
"improve": {"every": "24h", "budget": 500000,
"auto_deploy": {"min_gain": 0.05, "min_test_cases": 5, "hold": "72h"}}Khi có auto_deploy, lần chạy tự động (của lịch, watch hay Lead) huấn luyện xong chặng 2 thì tự deploy bản tốt nhất, nếu qua đủ các cổng sau:
- Huấn luyện đã xong và có điểm trên phần kiểm tra giữ riêng (test). Bản tốt nhất không phải
v0000và chưa được dùng. - Phần test có ít nhất
min_test_casescase, và điểm tăng ít nhấtmin_gainso với adapter đang dùng. - Mọi case
pinnedđều đạt trên phần test. - Bản này chưa từng bị hoàn tác vì làm Soot tệ hơn, và không có bản tự dùng nào khác còn đang được theo dõi.
Deploy đi qua đúng soot adapter deploy, nên có biên nhận và hoàn tác được. Sau đó, trong hold, watch so Soot với lúc trước khi đổi: bộ eval đạt ít hơn lần eval lúc deploy, hoặc tỷ lệ run hỏng kể từ deploy vượt cả ngưỡng failed_rate lẫn tỷ lệ trước deploy. Gặp một trong hai, watch hoàn tác bằng biên nhận (qua soot check như mọi lần hoàn tác) và ghi digest vào danh sách không tự dùng lại. Hết hold mà không tệ hơn thì bản được giữ. Trong hold, watch không chạy thêm lần cải thiện nào, để mỗi lúc chỉ có một thay đổi được đo.
Cần bạn báo bản vừa tự dùng (Giữ / Hoàn tác), bản watch đã hoàn tác, hoặc lần hoàn tác không làm được vì có tệp bị sửa sau đó (khi ấy người tự hoàn tác trong tab Cải thiện). Người tự hoàn tác thì bản đó cũng không được tự dùng lại. Thẻ có các con số để so: bài thi riêng trước và sau, bộ eval đạt và tỷ lệ run hỏng lúc deploy so với lần đọc gần nhất của watch (suite_now, failed_now; "chưa đo" khi chưa có eval trên bản mới hoặc chưa đủ run), và hạn theo dõi. Khi watch hoàn tác, worse ghi tín hiệu nào tệ đi, từ bao nhiêu đến bao nhiêu. Thẻ gọi Soot bằng tên người đặt (không phải id). Một lần tự hoàn tác thành công là thông báo (info): không có gì hỏng và không liên quan ngân sách; chỉ revert_failed là error. Trạng thái nằm ở .soot/improve/<soot>/auto_deploy.json: watching, kept, reverted, undone, revert_failed. Watch và câu trả lời của người (Giữ, Đã hiểu, Hoàn tác) ghi tệp này dưới cùng một khóa và đọc lại trước khi ghi: người đã giữ thì watch không ghi đè, cũng không hoàn tác. Thay đổi authored không bao giờ đi đường này.
Cải thiện cả workspace từ flow
Pipeline bốn chặng ở trên cải thiện một Soot từ eval của nó. Chỗ hỏng của một nhóm Soot thường nằm giữa các đội hoặc ở cấu hình đội (một quan hệ thiếu field, một giới hạn mỗi lượt quá nhỏ, một quy trình không có đường kết thúc, một đội không biết điều ai cũng tưởng nó biết). Flow (plans/team-flows.md) là bài kiểm của cả workspace, nên có một vòng riêng cải thiện workspace từ flow: soot improve --flows. Gói internal/feature/improve/wsimprove, dùng lại improve.Gate (cùng cổng với vòng Soot: val không giảm, train+val tăng quá MinGain, không flow pinned nào đang đạt lại trượt), improve.Snapshot/Revert (biên nhận, hoàn tác chống trôi file) và khoá job .soot/improve/workspace/.
Vòng chạy: đo train+val k lần trên bản sao workspace (mỗi lần thử là một runtime nháp), chẩn đoán (soot flow diagnose), áp mọi sửa không model thành một vòng (đo lại; nếu chỉ nâng một giới hạn thì lập kế hoạch lại từ chính lần đo của ứng viên, tối đa 3 lượt, rồi qua cổng một lần), sau đó các vòng của proposer, mỗi vòng kéo một cần gạt, rồi một lần xác nhận và flow test. Ngân sách mặc định 500000 token quy đổi; vượt là tiền.
| Tầng chẩn đoán | Cần gạt | Ai |
|---|---|---|
| ontology | thêm field bị từ chối (field của hàng đợi, field của quan hệ đọc), thêm quan hệ hoặc động từ còn thiếu, thêm lần chuyển kết thúc chỉ khi chẩn đoán nêu tên nó; không bao giờ gỡ gates | không model |
| budget | execution.max_run_tokens/max_tool_calls/max_turns của Soot = đỉnh đo được ×1.5, trong execution.daily_tokens của Soot đó | không model |
budget vượt daily_tokens, ngân sách ngày của đội/host, tầng model đắt hơn, tool trả tiền, ngân sách cải thiện quá 500000, gỡ gates | tiền: không bao giờ tự áp, thành đề xuất để người quyết | người |
| đội | một fact trong team memory (nguồn improve, nêu điều gì đúng và vì sao, không phải quy trình đánh số, tối đa 400 ký tự) hoặc mô tả đội | proposer (model) |
| Soot | bài nháp eval từ run lệch đầu tiên, nguồn flow:<id flow>, qua cơ chế nháp sẵn có (soot improve <soot> --drafts); không bao giờ được đo trước khi người nhận | người nhận nháp |
| pack | chỉ referral cho chủ pack | - |
| thế giới | chỉ báo cáo | - |
| nhiễu | không làm gì | - |
Team memory là trạng thái của runtime, không phải tệp, nên một fact của ứng viên được gieo vào mỗi runtime nháp qua flows.Options.Memory; khi áp, fact đi vào runtime thật qua POST /v1/workspace/memory (thẻ source:improve) và biên nhận giữ id của nó để hoàn tác quên đúng fact đó. Biên nhận gồm biên nhận tệp của vòng Soot và các fact đã dạy.
Kết quả là một diff, các fact, các đề xuất tiền và các bài nháp, chờ duyệt (--propose, --status). --apply ghi mọi thứ trừ tiền, rồi chạy lại val+pinned; nếu tỉ lệ đạt thấp hơn mức nền đã ghi lúc đo, tự hoàn tác theo biên nhận và ghi lý do (--history, --revert <biên nhận>). --auto là --propose rồi --apply. Workspace nguồn-sở-hữu không bao giờ bị áp trên host với tệp thuộc nguồn: --pull --into <repo> ghi phần đó vào bản checkout. API: POST /v1/improve/flows (mode propose|auto), GET /v1/improve/flows, POST /v1/improve/flows/apply, POST /v1/improve/flows/revert, GET /v1/improve/flows/history; job là chính CLI.
Duyệt và hoàn tác
Đề xuất chờ duyệt hiện ở Cần bạn (Áp dụng / Bỏ) và trong tab Cải thiện, kèm diff, điểm trước/sau và chi phí. Chỉ người áp dụng.
Mọi thay đổi đã áp dụng (--apply, gộp, soot adapter deploy, soot adapter remove) để lại biên nhận ở .soot/improve/<soot>/history/<id>/: hash từng tệp trước/sau và bản sao nội dung trước. Ghi tệp lỗi giữa chừng thì mọi tệp được trả lại; deploy adapter không qua validate thì adapter cũ được khôi phục.
soot improve ops --history # mới nhất trước
soot improve ops --revert # hoàn tác thay đổi mới nhất chưa hoàn tác
soot improve ops --revert --id <id>Hoàn tác khôi phục, không merge và trọn vẹn hoặc không gì cả: nếu một tệp đã bị sửa sau thay đổi đó, lệnh từ chối (improve_revert_drifted, HTTP 409) và không ghi gì; sau khi ghi, workspace phải qua soot check, nếu không mọi tệp được trả về như trước (improve_revert_invalid). Hoàn tác deploy adapter đưa về đúng adapter trước đó, không chỉ về "không adapter". Áp dụng, hoàn tác và deploy/remove đều đặt yêu cầu nạp lại một lần trên runtime đang chạy (POST /v1/improve/{soot}/reload), để lần chạy định kỳ sau đo cấu hình mới.
Soot thuộc repo (agent as code)
Soot của một source (agents.md) được định nghĩa trong repo, deploy thay cả lát, nên máy chủ không bao giờ ghi thẳng vào lát (sẽ thành drift). Quy tắc: repo luôn thắng.
GitHub repo ──release──▶ VM: sources.d/shop/… (deploy thay cả lát)
VM: .soot/adapters/seller/ (bản tinh chỉnh học trên VM)
◀──soot improve seller --pull── đề xuất + bản tinh chỉnh, để review/commit--applybị từ chối (improve_source_owned): đề xuất chặng 1 và gộp chặng 3 đi vào repo bằngsoot improve <soot> --pull --into <checkout>(--exportxem trước), rồi commit và release như mọi thay đổi code. Nest đổi nút Áp dụng thành Đưa vào repo.soot adapter deployghi vào.soot/adapters/<soot>/cùnghost.jsonghi adapter repo đang ship lúc deploy (over). Bản này chỉ áp khi repo vẫn ship đúng adapter đó. Trạng tháihost_adapter.state:active,in_repo,superseded,conflict; bản không áp được không bao giờ làm hỏng lần nạp.- Khi release mang thay đổi tới máy chủ, mọi thứ tự khép lại: đề xuất mà cây đã chứa đủ chuyển
in_repo.
Báo cáo: Soot đã tự cải thiện được gì
Báo cáo dựng thuần từ tệp đã có (state*.json, scheduled.jsonl, biên nhận, đề xuất đang chờ). GET /v1/improve trả mỗi Soot: pending, blocked (vì sao lần chạy mới nhất không đổi gì), applied / reverted, spent (weighted tokens 30 ngày), runs (tối đa 20), schedule, next, cases. Mỗi Soot còn có signals (lần đọc gần nhất của watch), drafts (số bài nháp chờ) và auto_deploy. Mỗi run có trigger (manual, scheduled, lead, watch kèm signal), stage, outcome (proposed, applied, discarded, in_repo, no_change, unchanged, healthy, waiting_review, budget, tuned, deployed kèm deployed, failed…), passed_before / passed_after, spent, levers. GET /v1/improve/{soot} thêm report, history, watch, drafts và auto_deploy. Nest hiện ở Kết quả › Tự cải thiện và trong tab Cải thiện; Lead trả lời cùng số liệu qua improve.status (kể cả brief buổi sáng).
Đầu vào cho coding agent: hillclimb
Hillclimb là dạng proposer thứ hai của chặng 1: coding agent (Claude Code, Cursor, Codex…) sửa trực tiếp source. soot spawn ghi vòng lặp này thành skill soot-hillclimb ở .agents/skills/ và .claude/skills/ của workspace:
soot check --strict --jsonvàsoot info --json: config hợp lệ, Soot thấy đúng tool và skill.- Viết case tái hiện hành vi sai;
soot eval <id>phải thấy nó fail. soot eval --json > base.json, rồi sửa một thứ.soot eval --baseline base.json: case đích improved, không gì regressed; rồisoot eval --tag smoke.- Giữ case trong
soots/<id>/evals/làm bằng chứng cải tiến còn đứng vững.
So với soot train: hillclimb sửa được mọi phần authored và bắt đầu từ một lỗi cụ thể, nhưng thủ công và không có held-out; soot train chỉ thêm hướng dẫn vào adapter, bắt đầu từ cả bộ case và có val/test mà proposer không thấy.
Ranh giới và những điều cố ý không làm
| Việc | Lý do |
|---|---|
| Không có model loop riêng cho eval | Mọi rollout đi qua conversation API, đúng đường chạy thật; thứ được đo là Soot, skill, tool và model thật |
Không tự áp dụng thay đổi authored; adapter chỉ khi người bật auto_deploy | Người là bên quyết định; mọi áp dụng có biên nhận và hoàn tác, bản tự dùng được theo dõi và tự hoàn tác khi tệ hơn |
| Bài nháp của watch không được đo trước khi người nhận | Bộ eval là đề thi; Soot không tự ra đề để chấm chính nó |
| Không đưa val, test, pinned vào material của proposer | Để training không đổi chính sách hay học thuộc đề để lấy điểm |
Không sửa evals/ trong lúc cải thiện | Case chấm điểm, không phải cần gạt |
| Không sửa pack vendored/Forge tại chỗ | Đề xuất thành PR hoặc issue cho chủ pack |
| Không rollout bằng model khác model của Soot cho kết quả cuối | Adapter học trên model rẻ có thể không chuyển sang model thật |
| Không để token quyết định thay độ đúng | Điểm giảm là loại, kể cả khi rẻ hơn |
| Lead không áp dụng, không bỏ, không đặt lịch, không nhận bài nháp | Chỉ operator hoặc người có quyền |
| Ai | Sở hữu |
|---|---|
| Core (runtime) | Eval runner, trace store, trường improve, pipeline và job lock, biên nhận, API /v1/improve, /v1/traces, /v1/usage |
| Pack | Tool có tool.preflight (để eval thấy tool sẽ từ chối gì mà không gây hiệu ứng); eval và skill đi kèm pack khi Forge phát hành |
| Host / sản phẩm | Case eval của sản phẩm, chính sách pinned, lịch và budget cải thiện |
| Nest | Hiển thị và thao tác: tab Cải thiện, Không đúng ý, Cần bạn, Kết quả; không có logic cải thiện riêng (surfaces.md) |
Chưa có / hạn chế
- Outcomes chưa là đầu vào tự động của vòng cải thiện (xem trên).
- Watch chỉ so bộ eval trên bản tự dùng khi đã có lần eval chạy trên bản đó (lần chạy kế tiếp của lịch hay watch, hoặc
soot eval); trước lúc ấy nó chỉ dựa vào tỷ lệ run hỏng. - Watch đọc tối đa 5000 run trong mỗi
window. - Chẩn đoán chỉ xếp theo rule; model chỉ diễn giải tùy chọn, không phân loại.
- Val nhỏ (dưới chừng 8 case) cho điểm nhiễu; chỉ cảnh báo, chưa chặn.
- Adapter học bằng một model rẻ chưa được bảo đảm chuyển sang model thật; bài test cuối phải chạy trên model mà Soot dùng.
- Cải thiện tự đo pass rate theo thời gian được hiển thị, nhưng chưa có cổng tự chặn release khi pass rate tụt (cổng là việc của bên đọc report, như replay).
Nội dung được xem lại: 12.11.2026