总账INFRA LEDGER · guiming
2026-07-22 构建快照投影 · 真源在仓
ABOUT · Harness 总览

系统与北极星策展快照

这套系统是什么、往哪去:Harness 平实重述、14 域、Skill 体系、provider 链、跨题元发现。

数据 as-of 2026-07-19

Harness 是什么

平实重述

Harness(驾驭具)是什么:context-infra 是套在 LLM 执行者外面的一层装备。大模型自己缺两样东西:一是干净充分的输入(它不知道此刻该看什么、该用什么工具),二是不可自评的输出误差信号(它判断不了自己做没做完、对不对)。Harness 用确定层(脚本、cron、hook、账本这些零熵机械件)和独立核验者(另一个不带立场的 agent)把这两样补出来。

一句更朴素的翻译:Harness 的意义是把用户从三个人肉角色里解放出来。系统缺哪段,用户就在人肉充当哪段:缺使用时刻的误差信号,用户当传感器(得自己盯着哪里不对);缺完成判定,用户当裁决者(得自己判断做完了没);缺队列消费机制,用户当调度器(得自己敲 prompt 开工)。北极星就是把这三个角色逐一交还给系统,让人只留在方向层:给方向,以及回答「确实不确定且细节非常关键」的问题。

五段闭环:

  1. 进(输入侧)
  2. 做(执行侧)
  3. 判(输出侧)
  4. 记(记录侧)
  5. 转(闭环侧)

判断任何一个新设计好不好,问一句就够:它让哪一段闭环更硬了?五段都不沾的设计,默认不做。

总纲七元原则:

  1. ["MP1 信任条件公理(生成根)","Harness 的存在就是制造并维持两个信任条件——目标清晰 + context 不饱和。这是全部语料里用户唯一明确称为「核心假设」的原则。"]
  2. ["MP2 判定权外移","执行者对自己的产出好/做完/完整没有裁决权;每个语义需求必须绑定确定层误差信号或独立第二核验者。"]
  3. ["MP3 需求原文是根锚","用户 prompt 逐字是全链根锚;转录/蒸馏/投影是派生物,不能反向充当源。"]
  4. ["MP4 熵控在源头","熵增长是 LLM 系统的运行常态;控制必须结构化、装在写入源头,不是下游打补丁。"]
  5. ["MP5 确定层 vs 语义层分工","可机械化的沉入确定层;语义判断永不冻结成确定工具。边界用比较性的三问测试判,双向越界都是缺陷。"]
  6. ["MP6 完成 = 真实效果被真实消费","实践是检验的最终标准:设计存在、流程走过、指标好看,都不构成完成。"]
  7. ["MP7 人只在方向层与关键不确定点","人的时间与认知带宽是系统的终局约束;整个闭环的输出面向方向判断与最小带宽收敛。"]

七条不是平列清单,是一个闭环:以需求原文为锚(MP3),在源头用结构控熵(MP4),由确定层制造可信任条件(MP1、MP5),条件之外一律外部核验(MP2),以真实消费定完成(MP6),最终只消耗人的方向判断与最小带宽(MP7)。

可用好用判据:可用=landed 四条件(真实运行证据/可路由入口注册/进 git HEAD/被下游真实消费)+确定层触发正确性五条(注册在位/真实触发/行为正确/异常不静默/不在错误对象上触发)。

  • U1 减负:能机械化的事不占 agent 注意力预算:hook 延迟 SLO(单 hook P95<1s);agent 手动履行的「本应确定层」义务清单收敛到零
  • U2 清晰:引导信号三属性:及时/显著/可操作:每 prompt 注入 skill 数封顶;FLAG 必带可定位反例
  • U3 聚焦:一次只给相关的,防洪泛:单次注入字符量上限;与当前任务无关的注入计为缺陷
  • U4 免记忆:agent 不需要记得系统状态,系统在正确时刻告诉它:跨 phase/跨 session 状态由确定层重放;同一文件被迫重读次数→0

Base Tooling 14 域

工具按知识边界的分组

git_tooling

Git 安全与自动提交体系:三档危险操作守卫(记录/safety tag/HUMAN_GATE)、session-ref 层隔离(不建物理 worktree)、事故取证与 BUG_TRACKER 链。

todo_system

任务系统:todo intake 需求入口(逐字原文+执行序+requirement record 同一条脊柱)、todo add 一次性杂务、双向同步。

ddp_design_doc_protocol

需求-设计文档协议:需求↔意义↔设计↔状态四环链,报告必须锚设计需求。

runtime_phase_skill_trace

phase 运行时+skill 注入+trace 三层统一机制:phase 驱动器续命推进、skill 声明随派发注入 worker、执行留痕。

provider_routing_self_invocation

LLM 单一出口与 fallback:11 档家族-通道降级链、自调用引擎(同一二进制经环境变量指向不同订阅)、额度 scope 记账与恢复探测。

orchestrator_dispatch_mode

编排者派发模式:session_dispatch 确定层派发、worker 纪律(anti-slack 六条)、通道对账防静默降级。

quality_gate_framework

质量门框架:__GATE_COUNT__ 个 gate 注册的清单与挂载点,unified_gate 统一入口。

final_report

终报规范:收口三件套、诚实边界声明、claim 上限词表(bounded/validated)。

guardian_daemon

守护体系:guardian_health 监控 cron missed-run、scoreboard 计数、mismatch 落账。

evolvable_workflow

可演进工作流:版本演进 SOP(何时打版、打什么版)、skill 更新机制。

cross_platform_hook_bridge

跨平台 hook 桥:Claude Code 全套 hook 迁移到 Codex 与 OpenCode 并 live。

cross_cutting

跨切关注点:错误追踪、回执互认等被多域共享的底层机制。

error_trace_feedback

错误追踪反馈:error_ledger 到 requirement 的硬闸,失败必须入账。

file_system_architecture

文件系统架构:单一文件原则(一类信息一个真源)、WORKSPACE 路由表、fa-3 schema。

Skill 体系

道术双册 · 全量见 <a href="skills.html">技能库</a>

Skill 是 agent 可复用的流程与最佳实践,按两个正交维度组织(总数与道/术计数见本页标题,构建期从 dao_shu_matrix 真源 yaml 实测解析,不写死)。类型维度:API(工具用法)/Workflow(多步流程)/BestPractice(最佳实践)/Draft(草稿)。道术维度:=方法引导层,产出是判断、方法、纪律,告诉系统怎么顶层思考;=技术实现层,产出是具体产物与操作结果,限定场景怎么做。

路由机制:每次 session 启动时注入路由纪律(_DAO_ROUTING.md),按任务特征匹配该读的道 skill;运行时 route_on_prompt hook 按 prompt 内容做精准匹配注入(r012 注入 v3 终裁:树状 INDEX 全量可见保全面性,道级正文按协调+判断精准注入保洁净,永禁 top-K 兜底,术级只注入 description)。注入 v3 实测载荷 1340B,是旧全文制的约 1%。

Provider 链

单一出口 + 自动级联

LLM 调用的单一出口是 router,按 11 档降级链自动级联:上一档失败(额度尽/限流/错误)自动尝试下一档,无需人工介入。链序本身也是决策产物(Kimi 经用户指示降级到 GLM 与 Cursor 之后)。当前链(与仓根 STATE.md GENERATED 区同指纹):

codex-oc:high glm-oc:high claude-zai:high grok-cursor:high composer-cursor:medium kimi-oc:medium claude-kimi:medium glm-ollama:high kimi-ollama:medium codex:xhigh claude:high

跨题元发现(5)

八份 dossier 综合出的结构性模式

① 提炼强、落地零 系统很会把隐性直觉提炼成显性文档,但从"文档存在"到"文档改变系统行为"的最后一段几乎完全空转。

哲学提炼七阶段全走完,总纲引文机械核验 94-100%,但 HARNESS_DESIGN_PHILOSOPHY.md 从未 commit、北极星 mtime 停在 07-08、cron 三行 07-20 已装 live、12 题未裁。

承接方向 → D4 决策披露 + D3 State 机制:把"交付但未消费"本身可视化,台账与 State 都内建回访防冻结。

② GENERATED 机制正式治理层零落地 "单一真源 + GENERATED 派生区"是仓库 06-03 就写进 WORKSPACE 的道层原则,但正式治理文件从未真正落地过一次 GENERATED 区。

provider 信息被复制到 18 份文件且已漂移:真源 11 档链 vs 三份文档停在 9 档零 Cursor;真源 Codex 300K vs 两处文档仍写 272K。

承接方向 → D1 Provider SSOT:方案 A(生成器读 conf → 注入 GENERATED 区 + gate diff 拦漂移)是单一文件原则首次正式落地(本次复盘 S1 已实跑落地,详见「执行方案」页)。

③ 表格跟手 · 图形必过时 资产能否随上游变更保持新鲜,由其生成方式决定,与内容重要性无关。

同一上游事件(07-18 provider 链大改)下:tools/INDEX.md 与 CRONTAB.md 当日同步准确;SYSTEM_MAP.md 停在 07-09、架构图仍画旧四步链。区别在 index 式增量 append 能跟手,图形需整体重画无触发点就冻结。

承接方向 → D3 State 机制:能机械派生的做 GENERATED,不能的降级为「快照 + 时间戳 + 陈旧告警」或给回访钩子。

④ 缺决策视角,非问题视角 登记簿的真实缺口不是漏了问题,而是只有问题域、缺决策域视角。

OPEN_PROBLEMS.md 07-17 才建档(晚于 r012 收口),建档是被动响应式,全文零条来自 r002-r012 的决策历史——那十次 run 的决策唯一入口是逐个读 FINAL_REPORT。

承接方向 → D4:决策台账(本站「决策台账」页)已补台账层,D4 补「新 run 收口自动加行」接线 + 网站呈现。

⑤ 状态面滞后修复面 "todo / crontab / 登记簿"这类"声称反映当前状态"的 live 面,在代码修复完成后不会自动跟进,形成"代码 FIXED、状态面 pending"的分叉。

BUG-021/022/023 在 BUG_TRACKER 均 FIXED 但 todo show T3793 仍 pending;reconcile cron 前置修复已落地但 live 仍 PAUSED(自 06-22)。两个独立悬案各给一手实例,构成模式。

承接方向 → D3:State 面并排显示「代码态 vs 登记态」分叉,喂用户关 todo / 恢复 cron 的决策,不越权自动改。

反复出现的工具面

Base Tooling 是支撑上面全部机制的工具集,当前 tools/INDEX.md 权威表注册 __TOOL_COUNT__ 个工具(build 期实时点表行数,非散文快照——SYSTEM_MAP 旧写「235」已过时)。上面 14 个域就是这些工具按知识边界的分组。几个在本站内容里反复出现的工具面:

路径职责
tools/llm_runtime/provider 控制面:providers.conf(链真源)、provider_info.py(llm info 查询)、provider_docs_render.py(GENERATED 渲染)、check_provider_docs_sync.py(防漂移 gate)、健康巡检。
tools/git/git 工具族:git_guard.sh(危险操作守卫)、commit_wrapper/stop_hook(自动提交)、BUG_TRACKER.md(三条 FIXED 登记)、main_index_reconcile.sh(幽灵 staged 回收器,cron 07-19 已恢复 live)。
tools/state_mechanism/State 机制 v0:parse_providers.py(链解析+语义指纹,D1/D3 共享)、gen_provider_chain.py、staleness_probe.py(探针)。
tools/skill_router_hook/注入路由:route_on_prompt.py(deliver-then-persist 修复对象)、route_hint.py(新根 Layer A)。
tools/session_dispatch/确定层派发:worker 纪律注入、通道钉链、receipt 对账。