Configure & operateCấu hình & vận hành
Already installed? This is where you tune how the harness feels: how much it pauses for you (autonomy), how hard each guard pushes back (policy), and which branches are protected. Every change is a human-edited YAML file and a git-visible diff — nothing is hidden in a binary or a database. Not installed yet? Start on the Install page.Đã cài rồi? Đây là chỗ chỉnh cảm giác của harness: dừng cho bạn bao nhiêu (tự chủ), đẩy lại mạnh cỡ nào ở mỗi guard (policy), và nhánh nào được bảo vệ. Mọi thay đổi là một file YAML người-sửa và một diff git thấy được — không gì giấu trong binary hay database. Chưa cài? Bắt đầu ở trang Cài đặt.
Pick an autonomy levelChọn mức tự chủ
Set HARNESS_AUTONOMY to control how often hs:cook pauses for a human. No level self-ships — push / pr / ship / deploy always go through the artifact gate, and the trace records fully even at god.Đặt HARNESS_AUTONOMY để điều khiển hs:cook dừng cho người bao lâu một lần. Không mức nào tự ship — push / pr / ship / deploy luôn qua gate artifact, và trace ghi đầy đủ kể cả ở god.
| LevelMức | PausesDừng | Use whenDùng khi |
|---|---|---|
default | at 2 checkpoints: plan approval + shipở 2 chốt: duyệt plan + ship | most work — supervised but not naggingphần lớn việc — có giám sát mà không phiền |
ask_all | after every phasesau mỗi phase | high-risk change you want to watch closelythay đổi rủi ro cao muốn theo sát |
god | never (trace still records fully)không bao giờ (trace vẫn ghi đầy đủ) | unattended runs — pairs with /hs:goal·/hs:loopchạy không giám sát — đi kèm /hs:goal·/hs:loop |
god removes the pauses, not the gates — the difference between "fast" and "unsafe".Tự chủ đổi khi nào bạn bị hỏi, không bao giờ đổi cái gì bị ép. god bỏ các điểm dừng, không bỏ gate — khác biệt giữa "nhanh" và "không an toàn".Set the guard policyĐặt chính sách guard
guard-policy.yaml gives every guard one posture — off / warn / block — resolved from a preset plus per-guard overrides. Edit it by hand or with guard_config.py (which also writes a who/when audit line).guard-policy.yaml cho mỗi guard một thế — off / warn / block — phân giải từ một preset cộng overrides theo-guard. Sửa tay hoặc bằng guard_config.py (cũng ghi một dòng audit ai/khi-nào).
| preset | safety | enforcement | advisory |
|---|---|---|---|
strict | block | block | warn |
balanced (default) | block | block | warn |
lenient | block | warn | off |
solo | block | block | off |
Notice safety stays block in every preset: that's the floor. Nudges aren't a preset category — they toggle per-hook in harness-hooks.yaml — and since v6.2.0 that is two layers, not one: the shipped registry, plus a per-project overlay that merges over it (see below).Để ý safety luôn block ở mọi preset: đó là cái sàn. Nudge không phải nhóm preset — chúng bật/tắt theo-hook trong harness-hooks.yaml — và từ v6.2.0 đó là hai tầng chứ không phải một: sổ đã ship, cộng một tầng phủ per-project gộp lên trên (xem bên dưới).
Safety floors & break-glassSàn an toàn & break-glass
Safety guards — host-safety, secret-read, write_guard, force-push, the merge gate — have a FLOOR of block. A preset can never lower a floor. An overrides: entry can, but that's a break-glass: guard_config still honors it, warns on stderr, and tags the audit line break_glass.Guard an toàn — host-safety, secret-read, write_guard, force-push, merge gate — có SÀN là block. Preset không bao giờ hạ được sàn. Một mục overrides: thì có thể, nhưng đó là break-glass: guard_config vẫn thực hiện, cảnh báo trên stderr, và đánh dấu dòng audit break_glass.
Not tunable hereKhông chỉnh được ở đây
Some invariants are always-on — turning them off would corrupt state, so they're not in the policy file at all: input-validation grammars, path containment, config-loader validation, plan-approval role consistency, and the CI bug-class invariants.Một số bất biến luôn-bật — tắt chúng sẽ làm hỏng trạng thái, nên không nằm trong file policy: grammar kiểm-tra-đầu-vào, khoanh đường-dẫn, validate config-loader, nhất quán vai trò duyệt-plan, và các bất biến bug-class của CI.
Turn one hook on or off, for this project onlyBật/tắt MỘT hook, chỉ cho dự án này
A shared-bin install serves the same harness-hooks.yaml to every project, so a project that wanted one nudge on used to edit the file every other project reads. Since v6.2.0 there is a per-project overlay that merges over the shipped registry — a hook the overlay never mentions keeps exactly the state it shipped with.Một bản cài shared-bin phục vụ CÙNG một harness-hooks.yaml cho mọi dự án, nên dự án nào muốn bật một nudge trước đây phải sửa chính file mà mọi dự án khác cùng đọc. Từ v6.2.0 có một tầng phủ per-project GỘP lên sổ đã ship — hook nào tầng phủ không nhắc tới thì giữ nguyên trạng thái đã ship.
hs-cli hooksBare, it reports every known hook: its resolved posture (on/off), whether it is advisory or blocking, its tier, and — the column that matters when two layers disagree — which layer decided it (shipped, project, or guard-policy). Write to the project layer with --off <csv> / --on <csv>; it touches only <data-root>/harness-hooks.yaml and never the shared file. A name the guard-policy plane owns is refused without --force.Chạy trần, nó báo mọi hook đã biết: tư thế đã giải (on/off), advisory hay blocking, hạng của nó, và — cột đáng giá nhất khi hai tầng bất đồng — tầng nào đã quyết (shipped, project, hay guard-policy). Ghi vào tầng dự án bằng --off <csv> / --on <csv>; nó chỉ đụng <data-root>/harness-hooks.yaml, không bao giờ đụng file dùng chung. Tên thuộc quyền mặt guard-policy bị từ chối nếu thiếu --force.
HARNESS_* env in settings.local.json.Cố ý chỉ MỘT trục. Tầng này phủ đúng việc bật/tắt từng hook, không gì khác. Chính sách guard và stage cùng ngôn ngữ output vẫn bin-global — một dự án không thể tự nới làn của chính nó từ một thư mục nó ghi được. Muốn cấu hình per-project cho những thứ đó thì đi qua một biến HARNESS_* tường minh trong settings.local.json.Protect a branchBảo vệ một nhánh
List a branch in protected-branches.yaml and a push to it is treated as a merge — the transport twin of the pr stage. The pre-push hook then demands the same merge-grade artifacts a reviewed PR would. The merge gate is itself a FLOOR guard.Liệt kê một nhánh trong protected-branches.yaml và push lên nó được xử như một merge — bản sao vận-chuyển của stage pr. Pre-push hook khi đó đòi cùng bộ artifact cấp-merge như một PR đã review. Merge gate tự nó là một FLOOR guard.
| BehaviorHành vi | On a protected refTrên ref được bảo vệ |
|---|---|
| Pattern syntaxCú pháp mẫu | fnmatch — * spans /, so release/* covers release/1.2fnmatch — * trải qua /, nên release/* bao release/1.2 |
| Plain pushPush thường | requires the three merge-grade artifactsđòi ba artifact cấp-merge |
| Force-push / delete / non-ffForce-push / xóa / non-ff | refused outrighttừ chối thẳng |
| Empty / missing listDanh sách trống / thiếu | protects nothing — a fresh repo pushes freely (additive)không bảo vệ gì — repo mới push thoải mái (cộng dồn) |
Ships with an empty list — nothing is protected until you add entries (additive). See the glossary for non-fast-forward and merge gate, or the cheatsheet for the stage → artifact table.Ship kèm danh sách rỗng — chưa bảo vệ gì cho tới khi bạn thêm mục (cộng dồn). Xem glossary cho non-fast-forward và merge gate, hoặc tra cứu nhanh cho bảng stage → artifact.
Personal-first: local gates advise, hard guarantees don't need CIPersonal-first: gate local advisory, bảo đảm cứng không cần CI
The harness operates personal-first: local gates are advisory (no block — you decide) to minimize friction while you're coding and tracing. What actually stays block everywhere, with no CI required, is the path-keyed write floors (destructive-to-protected-branch + secret-read), and the artifact-forgery check. If your repo wants the presence gate hard-enforced on every push or PR too, that's an optional CI workflow (receipts-gate.yml) you can wire into your own CI — it doesn't ship as a requirement.Harness hoạt động personal-first: gate local là advisory (không chặn — bạn quyết) để giảm ma-sát khi code và trace. Cái thật sự luôn block ở mọi nơi, không cần CI, là các sàn ghi theo đường-dẫn (phá nhánh bảo vệ + đọc secret), và check chống-giả-mạo artifact. Nếu repo bạn muốn ép cứng presence gate trên mọi push hoặc PR nữa, đó là một workflow CI tùy chọn (receipts-gate.yml) bạn có thể gắn vào CI của mình — nó không đi kèm như một yêu cầu bắt buộc.
block with no CI required. Wire the optional receipts-gate CI workflow into your own repo if you also want plan + test pass + code review hard-checked before every merge. Your device is yours; the cage and the floors are protected either way.Personal-first hạ ma-sát local, không an toàn. Gate local advisory cho phép lặp không phải giơ tay; agent mọi sàn ghi theo đường-dẫn vẫn block mà không cần CI. Gắn workflow CI receipts-gate (tùy chọn) vào CI của repo bạn nếu bạn cũng muốn ép cứng plan + test pass + code review trước mỗi lần merge. Thiết bị của bạn là của bạn; cage và các floor vẫn được bảo vệ dù thế nào.FAQHỏi đáp
Will installing touch files I didn't expect?Cài đặt có đụng file tôi không ngờ không?
--dry-run first — it plans every write and changes nothing. The real run is idempotent, and --uninstall reverses the settings + pre-push edits (it leaves harness/ in place; delete that folder to remove it fully).Chạy --dry-run trước — nó lập kế hoạch mọi lần ghi và không đổi gì. Lần chạy thật là idempotent, và --uninstall đảo ngược chỉnh settings + pre-push (để harness/ nguyên; xóa thư mục đó để gỡ hẳn).Is god autonomy dangerous?god có nguy hiểm không?
god run still cannot push without the artifacts, and the trace records every phase. It's "no questions asked", not "no rules applied".Nó bỏ các điểm dừng, không bỏ gate. Một lần chạy god vẫn không push được khi thiếu artifact, và trace ghi mọi phase. Đó là "không hỏi gì", không phải "không luật nào".Why YAML for config and JSON for data?Vì sao config dùng YAML còn dữ liệu dùng JSON?
How do I see every guard and its current mode?Xem mọi guard và mode hiện tại thế nào?
python3 harness/plugins/hs/skills/setup/scripts/guard_config.py show lists every valid guard id with its resolved mode, so you know exactly what an override would change.python3 harness/plugins/hs/skills/setup/scripts/guard_config.py show liệt kê mọi guard id hợp lệ với mode đã phân giải, để bạn biết chính xác một override sẽ đổi gì.In solo mode, can I turn off the reminder lines too?Ở solo, tắt luôn các dòng nhắc được không?
set-preset solo keeps a one-line soft-stage reminder so a frictionless push still leaves a visible "ran ungated" note (notify). For a fully silent run, set soft_stage_advisory: false in stage-policy.yaml. Either way the gate still traces every decision — silencing silences the nudge, not the audit.Được — tùy bạn. set-preset solo giữ một dòng nhắc soft-stage để push không-ma-sát vẫn để lại ghi chú "chạy không gate" thấy được (notify). Muốn im hẳn thì đặt soft_stage_advisory: false trong stage-policy.yaml. Kiểu nào gate cũng vẫn trace mọi quyết định — tắt tiếng tắt lời nhắc, không tắt audit.Does solo mode let the AI agent bypass the guards?Solo có cho agent AI vượt guard không?
enforcement stays block, so floor_bash_guard (the Bash lane, full-floor coverage for every actor) and write_guard (the Write/Edit lane, scoped to a narrower GUARD_LIST) keep blocking a subagent. The solo preset itself keeps both the safety and enforcement columns at block; the only way to lower one guard is guard_config.py set, and lowering a safety floor that way is a logged break-glass (stderr warning + a break_glass trace line), never a silent change.Không. Solo chỉ nới luồng của người. Guard enforcement vẫn block, nên floor_bash_guard (lane Bash, phủ đủ sàn cho mọi actor) và write_guard (lane Write/Edit, chỉ phủ danh sách GUARD_LIST hẹp hơn) vẫn chặn subagent. Bản thân preset solo giữ cả cột safety lẫn enforcement ở block; cách duy nhất để hạ một guard là guard_config.py set, và hạ một safety floor theo cách đó là break-glass có ghi lại (cảnh báo stderr + dòng trace break_glass), không bao giờ âm thầm.