项目定位与目标

localharness 是一个本地化的智能体（agent）运行环境，面向"在本地起一个模型 + 在 REPL 中长期使用 + 跨会话沉淀记忆"的场景。它在用户进程内把模型 server、工具调用、记忆与检查点串成一个闭环，避免反复启动 vLLM/Transformers 后端或将状态外置到外部服务。

项目的核心定位包含三件事：

• 本地模型托管：通过 server.local_models 注册命名 checkpoint，配合 vllm serve 启动参数，运行时可在 REPL 中整体替换模型（v0.9.23 引入的全量模型切换能力）。
• REPL 作为一等公民：CLI 入口就是一个交互式会话，既能跑普通问答，也能在 turn 结束时自动做记忆管线处理。
• 持久化记忆层：通过语义原子（sem/）与查询时注入（ambient injection）构建长期可用的事实库。

资料来源：README.md:1-40, src/localharness/__init__.py:1-20

整体架构

整体可拆为四层，分别承担"模型进程、对话循环、记忆与工具、可观测"职责：

flowchart LR
    U[用户] --> R[REPL / CLI]
    R --> A[Agent Loop]
    A --> S[vLLM Server]
    A --> M[Memory Pipeline]
    M --> I[Ambient Injection]
    I --> A
    A --> R

资料来源：docs/reference-architectures/README.md:1-30, src/localharness/cli/app.py:1-40

安装与首次启动

推荐使用 uv 做 editable 安装，便于直接修改源码并立即生效：

uv sync
uv run localharness

安装元数据来自 pyproject.toml 中声明的版本号；命令行 banner 读取的是 distribution metadata，而不是 localharness.__version__。在 editable 模式下，源码更新后必须重新执行 uv sync，否则 banner 会停留在旧版本。

资料来源：pyproject.toml:1-30, src/localharness/__init__.py:1-15

REPL 内常用操作

启动后会进入交互式会话，常用指令包括：

• /model：列出已注册命名、本机存活、HF 缓存中的模型，选定后会重启 server 加载新 checkpoint（每次切换只对该 checkpoint 生效，避免 MoE/量化参数泄漏到兄弟模型）。
• 直接问答：模型若无需工具会被要求输出 CONFIRMED，确认上一次回复作为最终答案；该路径若摘要回退会回到 session.messages 的最后一条助手内容（issue #91）。
• Ctrl+C 退出：建议在回复渲染完成、turn 结束簿记（如 TurnCompleted、micro-pass、记忆管线）运行后再退出；立刻退出可能跳过当轮处理（issue #93）。

资料来源：src/localharness/cli/app.py:1-60, src/localharness/agent/loop.py:246-256

已知影响快速上手的若干问题

社区中已记录一些会影响首次体验或日常使用的边界情况，建议在快速上手时留意：

• Docker 模式下僵尸进程：若 launch: docker 启动 vLLM 失败，docker run --rm 客户端会变成未收割的 zombie，REPL 进程下的 wait() 缺失（issue #99）。
• 版本号陈旧：banner 不会随源码自动刷新，需要 uv sync（issue #97）。
• 首轮空记忆：没有任何已存在事实的 turn，因 injected-id 列表为空而不会写入 injection trace，覆盖率统计会出现盲区（issue #96）。
• 撤回/合并缺位：矛盾的语义原子各自拥有唯一 key，可能并存为 active（issue #95）；proposed 标签在真实 store 中长期未被命名/晋升（issue #90）。

资料来源：src/localharness/memory/discovery.py:286-290, src/localharness/agent/loop.py:246-256

小结

localharness 把"本地模型 + REPL + 持久化记忆"压缩成一个可独立运行的进程；上手路径很短（uv sync + uv run localharness），但要在生产式使用中获得稳定行为，需要同时关注 server 进程管理、turn 退出时机，以及记忆层的去重与覆盖统计。这些点恰好也是当前社区 issue 的集中处。

概述

localharness 的代理运行时围绕一个 单回合（turn） 调度循环展开，由 agent/loop.py 统一驱动消息累积、工具调用解析、回退渲染与回合终了记账。工具面分两条平行通路：内置工具经 tools/builtin/__init__.py 注册，MCP 工具经 tools/mcp.py 通过 Model Context Protocol 接入。权限策略集中于 agent/permissions.py，负责对每一次工具执行进行前置检查。orchestrator/router.py 提供 type-anytime 路由与分级（tier-2）分类，agent/subagent.py 实现子代理的派生与隔离。

代理循环与回合终了

主循环位于 agent/loop.py，负责在每一回合累积消息、解析工具调用、调用权限闸口并产生最终答复。_format_completion_summary 在模型回退为 CONFIRMED 哨兵时，从 session.messages 中提取上一条助手内容作为兜底展示——但因读取的是全量多回合消息列表，存在误把前几回合的旧答复当作本回合答复的隐患。资料来源：src/localharness/agent/loop.py:246-256

回合记账路径依赖一个明确的"回合结束"事件 TurnCompleted 触发后置的内存与追踪写入；若用户在该事件触发前通过 Ctrl+C 立即退出 REPL（例如答复刚刚渲染），可让回合在未最终化前结束，导致内存管线处理、注入追踪写入与 TurnCompleted 事件整体丢失。资料来源：src/localharness/agent/loop.py:240-280

主循环还内置一层 "act-guard"：当模型本回合零工具调用时，提示"如确实无需工具，请回复 CONFIRMED"。该路径在裸 CONFIRMED 上与回退摘要共用同一管线，可能使元指令回声替换本应可见的真实答复。资料来源：src/localharness/agent/loop.py:200-260

工具系统：内置与 MCP

tools/builtin/__init__.py 维护一个内置工具注册表，提供 REPL 直接调用的基础能力集合。注册采用"名称→实现"映射，新增工具只需追加条目并保证签名与权限策略对接。资料来源：src/localharness/tools/builtin/__init__.py:1-80

tools/mcp.py 提供对外部 MCP 服务的桥接，把 MCP 暴露的工具声明合并进代理的工具列表，并以统一接口转发调用与回流结果。该模块通常负责处理连接生命周期、能力发现（capabilities discovery）以及错误重试等横切关注点。资料来源：src/localharness/tools/mcp.py:1-120

下表汇总了工具调用在不同路径下的关键差异：

权限控制

agent/permissions.py 在每次工具调用执行前进行决策：基于工具名、参数范围、会话上下文判断放行、拦截或要求确认。该模块通常以"工具白名单/黑名单"+"危险操作需确认"的分层策略实现，保证 agent 在获得工具能力的同时不脱离用户授权范围。资料来源：src/localharness/agent/permissions.py:1-120

写入路径上的"新颖性"判定（"First successful use of tool X"）在写闸门（write-gate）里被复用，但当前比对的是会话作用域状态而非持久化存储，导致同一工具在不同日期的"首次成功使用"会重复触发；最终由唯一活跃键约束以 upsert 方式静默合并并刷新更新时间戳。资料来源：src/localharness/agent/permissions.py:120-200

编排、路由与子代理

orchestrator/router.py 实现 type-anytime 路由，把入站消息按紧急度与语义分为多档（tier），其中 tier-2 通过独立的分类调用进行更精细的意图判定。该分类调用复用了代理自身的 LLM 客户端，受单飞（single-flight）推理信号量约束——而该信号量在流式生成期间持续持有，因此 tier-2 分类会被同一流阻塞，造成回合内饥饿与故障静默。资料来源：src/localharness/orchestrator/router.py:1-200

agent/subagent.py 负责子代理的派生、上下文裁剪与结果回收，使主代理能够把长链任务拆解为可并行或隔离执行的子任务。子代理通常继承受限的工具集与权限策略，避免子任务越权访问主代理范围之外的资源。资料来源：src/localharness/agent/subagent.py:1-160

已知问题与注意事项

• 僵尸 docker-run 客户端：managed vLLM server 启动失败时，docker run --rm 进程退出但未被 wait()，留下僵尸进程，绕过 fail-fast 路径。资料来源：src/localharness/agent/loop.py:280-340
• Act-guard 哨兵回声：无工具回合的 CONFIRMED 处理与回退摘要共用代码，可能把元指令回声作为可见答复呈现。资料来源：src/localharness/agent/loop.py:200-260
• 回合终了记账竞态：REPL 立即退出可能跳过 TurnCompleted 与回合终结微处理。资料来源：src/localharness/agent/loop.py:240-300
• tier-2 分类饥饿：单飞推理信号量在流式期间持续持有，导致 mid-turn 分类延迟与失败路径静默。资料来源：src/localharness/orchestrator/router.py:1-200
• 写入新颖性跨日重放：会话作用域的新颖性判定会在多日重复触发"首次使用"。资料来源：src/localharness/agent/permissions.py:120-200

系统定位与模块划分

记忆系统位于 src/localharness/memory/ 包下,主要职责包括:

• 提供一个可事务化的本地持久层,跨回合保存 sem/(语义原子)、ep/(情景痕迹)、fact/(高阶事实)等记录。资料来源：src/localharness/memory/sqlite.py:1-120
• 在写入前由预测式写入门控做新颖度、置信度与上下文的过滤,避免噪声淹没存储。资料来源：src/localharness/memory/predictive_write_gate.py:1-80
• 通过发现模块从已有原子聚类中抽取"候选标签",并由合并模块定期压缩重复/陈旧项。资料来源：src/localharness/memory/discovery.py:1-60,src/localharness/memory/consolidation.py:1-60
• 由挖掘模块把对话与工具结果中的高置信事实降维成语义原子。资料来源：src/localharness/memory/mining.py:1-60
• 在分级层管理 L0(原始痕迹)、L1(原子)、L2(标签/概念)之间的提升路径。资料来源：src/localharness/memory/hierarchy.py:1-60

SQLite 持久化层

sqlite.py 把记忆表示为带唯一性约束的行,通过原子键 key(形如 <scope>:<bucket>:<hash>)实现 upsert 语义。典型写入序列包括:

1. 读取或新建一条原子行,主键由 (bucket, key) 构成。
2. 在同事务内更新 last_seen_ts、support_count、status 等元数据。
3. 通过 evidence_links 表登记该原子在哪些回合/工具调用中出现过。

唯一性约束带来一个可观察的副作用:两条相互矛盾的事实只要哈希键不同,会同时保持 active 状态。社区在 #95 中记录到此问题——例如"vLLM 监听 8000 端口"与"vLLM 监听 8081 端口"在 sem/ 桶里拥有不同的 key,因此谁也不会被对方"挤掉",从而并存于活动集合。资料来源：src/localharness/memory/sqlite.py:120-260,#95

预测式写入门控

predictive_write_gate.py 位于"挖掘→持久化"之间,典型职责为:

• 基于当前会话上下文判断是否首次出现某工具/某事实,若是则标记为 novel 以提高写入优先级。
• 检查置信度阈值,并返回 allow / suppress / demote 三种决定之一。
• 抑制重复噪声,避免同一事实在多回合反复写盘造成 support_count 虚增。

社区已知问题 #89 揭示了会话范围检查的局限:写入门控以会话级状态做新颖度比较,而非查询持久化存储,导致同一工具的"首次成功使用"会在不同日期反复触发;唯一性约束虽然阻止了重复行的真正插入,但会无声地 upsert 并刷新元数据。资料来源：src/localharness/memory/predictive_write_gate.py:80-180,#89

发现、合并与生命周期

发现模块负责把语义原子聚类为标签候选;每个候选自诞生起处于 proposed 状态,等待被模型命名并在足够证据下被提升为 promoted。

社区问题 #90 报告"proposed 候选停留 6 天以上仍未被命名/提升",问题 #94 指出发现流水线对未变化的原子簇无条件刷新 last_accrual_ts,导致陈旧性剪枝永远无法生效——候选因此进入永久 limbo。资料来源：src/localharness/memory/discovery.py:200-320,#90,#94

合并模块 consolidation.py 周期性地压缩近似原子、清理过期情景,并通过 mining.py 抽取出新的高层事实,以维持存储紧凑与查询高效;分级层 hierarchy.py 决定哪些 L1 原子应晋升为 L2 标签或概念节点。资料来源：src/localharness/memory/consolidation.py:60-180,src/localharness/memory/mining.py:80-200,src/localharness/memory/hierarchy.py:60-180

与回合生命周期的耦合

写入门控的运行点位于回合结束或工具结果归并阶段。若 REPL 在答案渲染后被立即中断(Ctrl+C 即退),回合结束的微型 pass 与记忆流水线都不会运行。社区 #93 描述了此风险:在该回合中可能产生"未持久化的工具结果"或"未触发的写入门控评估"。资料来源：#93

此外,环境注入追踪(ambient injection trace)仅在注入 ID 列表非空时记录一行,导致首回合或新存储的"未注入"事件被静默丢失(#96)。这会影响按回合统计的覆盖率指标,提示在评估记忆效果时需额外注意。资料来源：#96

受管服务器生命周期

启动模式

localharness 的受管服务器由 src/localharness/provider/server.py 持有抽象，支持 launch: docker 与本地子进程两种形态。docker 模式会以 docker run --rm 启动 vLLM 镜像，并把宿主机端口、模型缓存目录与 VLLM_* 环境变量透传给容器；本地模式则直接以 vllm serve 作为子进程接管 资料来源：src/localharness/provider/server.py:1-120。

自 v0.9.23 起，server.local_models 字段允许在配置中按"名称 → 检查点 + 私有参数"的方式注册多个本地模型，每个注册项可以携带仅对该检查点生效的 vllm serve 参数（如 MoE 专属后端标志或与检查点严格耦合的量化标志）资料来源：src/localharness/cli/model_cmd.py:1-200。这样既避免了无关标志在不同检查点之间泄漏，也使 /model 列表能够并列展示注册名、当前活动模型与 HF 缓存内可发现的模型。

进程模型与 PID 查询

server_pid() 接口返回受管后端的当前 PID，供 REPL 健康检查与 /model swap 等命令在切换前判定目标进程是否仍然存活。该返回值在 docker 模式下是宿主机上 docker run --rm 客户端进程的 PID，而不是容器内 vLLM 自身的 PID——这一点对理解下文的故障模式至关重要 资料来源：src/localharness/provider/server.py:120-180。

REPL 内热切换

/model 命令由 src/localharness/cli/model_cmd.py 实现：先列出三类候选（注册名、当前活动、HF 缓存内候选），再由用户挑选并触发 src/localharness/cli/model_ops.py 中的停止→启动序列。停止逻辑对 docker 模式使用 docker stop/docker rm，对本地模式向子进程发送 SIGTERM 并 wait()；启动逻辑则使用新检查点对应的私有参数重建调用 资料来源：src/localharness/cli/model_ops.py:1-160。

flowchart LR
    A[/model 命令] --> B[model_cmd 列出候选]
    B --> C{用户选择}
    C --> D[model_ops 停止旧后端]
    D --> E[清理 docker 客户端 / 子进程]
    E --> F[用新参数重建启动]
    F --> G[轮询健康端点]
    G --> H[切换完成]

后端检测与基准编排

后端探测

src/localharness/provider/detector.py 负责在 REPL 启动或 /model 触发时探测本机可用推理后端：解析 vllm --version、检查 Docker 守护进程可达性、枚举 HF 缓存目录下的检查点，并将结果缓存到会话级 ProviderInventory。该缓存会在显式 /model refresh 或配置文件变更时失效 资料来源：src/localharness/provider/detector.py:1-140。

基准编排入口

src/localharness/bench/orchestrator.py 暴露基准运行编排能力：接受任务集、并发度与采样参数，按需调用受管服务器端点、收集延迟/吞吐指标，并将结果写入可追溯的输出目录。orchestrator 复用 provider/server.py 的客户端，不直接 spawn 进程，因此与受管后端的生命周期保持一致 资料来源：src/localharness/bench/orchestrator.py:1-180。

已知故障模式

僵尸 `docker run --rm` 客户端（Issue #99）

当 launch: docker 的 vLLM 服务在启动阶段崩溃——例如 --quantization 与检查点不匹配——容器侧的 vLLM 退出，但宿主机侧的 docker run --rm 客户端进程没有被任何代码 wait()，从而成为挂在 REPL 进程下的僵尸。server_pid() 仍然返回该僵尸 PID，使"死进程立即失败"的快速失败语义被绕过 资料来源：src/localharness/provider/server.py:180-240。建议在停止路径上显式对客户端 PID 调用 os.waitpid()，或改用 docker run --init/tini 让 init 进程接管回收。

版本横幅读取陈旧元数据（Issue #97）

CLI 与启动横幅读取的是已安装发行版的分发元数据，而非 localharness.__version__。在 editable 安装下，git pull 之后源码已更新但 dist-info 未变，导致横幅始终显示旧版本号 资料来源：src/localharness/cli/repl.py:1-120。运行 uv sync 或 pip install -e . --no-deps --force-reinstall 可临时缓解；长期方案是横幅直接读取运行时模块属性。

健康检查与切换的耦合

/model swap 的"停止 → 启动"序列依赖健康端点轮询来判断旧后端已就绪退出。若旧后端处于上述僵尸态，轮询将一直成功（端口仍被旧容器占用），新启动会因为端口冲突而失败，并被报告为"启动失败"而非"旧后端未释放" 资料来源：src/localharness/cli/model_ops.py:160-260。运维侧应以 server_pid() 的存活状态作为前置条件，而非仅看端口探测。

与单飞行推理门控的相互影响（Issue #92）

tier-2 输入分类复用了智能体自身的 LLM 客户端，而该客户端被一个跨整个流式响应持续持有的 single-flight 信号量串行化。当受管服务器刚刚完成启动、首个请求尚在排队时，分类调用会被同步阻塞，导致 tier-2 路径呈现"无声卡死" 资料来源：src/localharness/agent/loop.py:240-320。在基准场景下这会扭曲首 token 延迟（TTFT）测量结果，应在编排时记录并剔除这一窗口。

排查建议速查

掌握上述生命周期边界与故障模式后，开发者可以更可靠地扩展 server.local_models 语义、为新后端（如 llama.cpp server）撰写平行启动路径，并在基准实验中规避首请求偏差。

Pitfall Log / 踩坑日志

项目：ahwurm/localharness

摘要：发现 39 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Version banner reads stale install metadata on editable installs — shows old version after ev...。

1. 安装坑 · 失败模式：installation: Version banner reads stale install metadata on editable installs — shows old version after ev...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Version banner reads stale install metadata on editable installs — shows old version after every source update
• 对用户的影响：Developers may fail before the first successful local run: Version banner reads stale install metadata on editable installs — shows old version after every source update
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/97 | Version banner reads stale install metadata on editable installs — shows old version after every source update

2. 安装坑 · 来源证据：Discovery candidate tags never progress past 'proposed' — naming/promotion unobserved for 6+ days

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Discovery candidate tags never progress past 'proposed' — naming/promotion unobserved for 6+ days
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/90 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Discovery candidates can enter permanent limbo: evidence re-accrual on unchanged clusters defeats staleness pruning

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Discovery candidates can enter permanent limbo: evidence re-accrual on unchanged clusters defeats staleness pruning
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/94 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Exiting the REPL immediately after an answer skips that turn's end-of-turn bookkeeping

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Exiting the REPL immediately after an answer skips that turn's end-of-turn bookkeeping
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/93 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：Version banner reads stale install metadata on editable installs — shows old version after every source update

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Version banner reads stale install metadata on editable installs — shows old version after every source update
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/97 | 来源类型 github_issue 暴露的待验证使用条件。

6. 安装坑 · 来源证据：Zombie docker-run client defeats the managed server's dead-process fail-fast

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Zombie docker-run client defeats the managed server's dead-process fail-fast
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/99 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

7. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/ahwurm/localharness | host_targets=claude, chatgpt, claude_code

8. 配置坑 · 失败模式：configuration: Zombie docker-run client defeats the managed server's dead-process fail-fast

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Zombie docker-run client defeats the managed server's dead-process fail-fast
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Zombie docker-run client defeats the managed server's dead-process fail-fast
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/99 | Zombie docker-run client defeats the managed server's dead-process fail-fast

9. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ahwurm/localharness | README/documentation is current enough for a first validation pass.

10. 运行坑 · 失败模式：runtime: Mid-turn tier-2 input classification is starved by the single-flight inference gate, and its...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: Mid-turn tier-2 input classification is starved by the single-flight inference gate, and its failure path is silent
• 对用户的影响：Developers may hit a documented source-backed failure mode: Mid-turn tier-2 input classification is starved by the single-flight inference gate, and its failure path is silent
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/92 | Mid-turn tier-2 input classification is starved by the single-flight inference gate, and its failure path is silent

11. 运行坑 · 来源证据：Agent loop accepts a tool-less reply that announces further work as the turn's final answer

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Agent loop accepts a tool-less reply that announces further work as the turn's final answer
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/84 | 来源类型 github_issue 暴露的待验证使用条件。

12. 运行坑 · 来源证据：Contradictory sem/ atoms coexist as active — mined facts never supersede on contradiction

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Contradictory sem/ atoms coexist as active — mined facts never supersede on contradiction
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/95 | 来源类型 github_issue 暴露的待验证使用条件。

13. 运行坑 · 来源证据：Messages typed into the input box leave no permanent record in the terminal transcript

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Messages typed into the input box leave no permanent record in the terminal transcript
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/85 | 来源类型 github_issue 暴露的待验证使用条件。

14. 运行坑 · 来源证据：Mid-turn tier-2 input classification is starved by the single-flight inference gate, and its failure path is silent

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Mid-turn tier-2 input classification is starved by the single-flight inference gate, and its failure path is silent
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/92 | 来源类型 github_issue 暴露的待验证使用条件。

15. 运行坑 · 来源证据：Mint-time classification can assign BOTH L1 buckets to one atom

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Mint-time classification can assign BOTH L1 buckets to one atom
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/88 | 来源类型 github_issue 暴露的待验证使用条件。

16. 运行坑 · 来源证据：Turn summary fallback can resurface a PRIOR turn's reply when the model answers with only the confirmation sentinel

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Turn summary fallback can resurface a PRIOR turn's reply when the model answers with only the confirmation sentinel
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/91 | 来源类型 github_issue 暴露的待验证使用条件。

17. 运行坑 · 来源证据：Turns with an empty memory shelf are never recorded in injection traces

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Turns with an empty memory shelf are never recorded in injection traces
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/96 | 来源类型 github_issue 暴露的待验证使用条件。

18. 运行坑 · 来源证据：Working indicator renders in the input box's bottom border, crowding queue count and decision flash

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Working indicator renders in the input box's bottom border, crowding queue count and decision flash
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/86 | 来源类型 github_issue 暴露的待验证使用条件。

19. 运行坑 · 来源证据：Write-gate novelty capture re-claims 'first successful use' of the same tool across days

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Write-gate novelty capture re-claims 'first successful use' of the same tool across days
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。

20. 运行坑 · 来源证据：remember()-saved memories are never tagged at write time; backfill runs so late in consolidation that user activity sta…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：remember()-saved memories are never tagged at write time; backfill runs so late in consolidation that user activity starves it
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/87 | 来源类型 github_issue 暴露的待验证使用条件。

21. 维护坑 · 来源证据：Act-guard sentinel echo replaces the user-visible answer with the CONFIRMED meta-line

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Act-guard sentinel echo replaces the user-visible answer with the CONFIRMED meta-line
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ahwurm/localharness/issues/98 | 来源类型 github_issue 暴露的待验证使用条件。

22. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ahwurm/localharness | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ahwurm/localharness | no_demo; severity=medium

24. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ahwurm/localharness | no_demo; severity=medium

25. 能力坑 · 失败模式：capability: Agent loop accepts a tool-less reply that announces further work as the turn's final answer

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Agent loop accepts a tool-less reply that announces further work as the turn's final answer
• 对用户的影响：Developers may hit a documented source-backed failure mode: Agent loop accepts a tool-less reply that announces further work as the turn's final answer
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/84 | Agent loop accepts a tool-less reply that announces further work as the turn's final answer

26. 能力坑 · 失败模式：capability: Contradictory sem/ atoms coexist as active — mined facts never supersede on contradiction

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Contradictory sem/ atoms coexist as active — mined facts never supersede on contradiction
• 对用户的影响：Developers may hit a documented source-backed failure mode: Contradictory sem/ atoms coexist as active — mined facts never supersede on contradiction
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/95 | Contradictory sem/ atoms coexist as active — mined facts never supersede on contradiction

27. 能力坑 · 失败模式：capability: Discovery candidate tags never progress past 'proposed' — naming/promotion unobserved for 6+...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Discovery candidate tags never progress past 'proposed' — naming/promotion unobserved for 6+ days
• 对用户的影响：Developers may hit a documented source-backed failure mode: Discovery candidate tags never progress past 'proposed' — naming/promotion unobserved for 6+ days
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/90 | Discovery candidate tags never progress past 'proposed' — naming/promotion unobserved for 6+ days

28. 能力坑 · 失败模式：capability: Messages typed into the input box leave no permanent record in the terminal transcript

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Messages typed into the input box leave no permanent record in the terminal transcript
• 对用户的影响：Developers may hit a documented source-backed failure mode: Messages typed into the input box leave no permanent record in the terminal transcript
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/85 | Messages typed into the input box leave no permanent record in the terminal transcript

29. 能力坑 · 失败模式：capability: Mint-time classification can assign BOTH L1 buckets to one atom

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Mint-time classification can assign BOTH L1 buckets to one atom
• 对用户的影响：Developers may hit a documented source-backed failure mode: Mint-time classification can assign BOTH L1 buckets to one atom
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/88 | Mint-time classification can assign BOTH L1 buckets to one atom

30. 能力坑 · 失败模式：capability: Turn summary fallback can resurface a PRIOR turn's reply when the model answers with only the...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Turn summary fallback can resurface a PRIOR turn's reply when the model answers with only the confirmation sentinel
• 对用户的影响：Developers may hit a documented source-backed failure mode: Turn summary fallback can resurface a PRIOR turn's reply when the model answers with only the confirmation sentinel
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/91 | Turn summary fallback can resurface a PRIOR turn's reply when the model answers with only the confirmation sentinel

31. 能力坑 · 失败模式：capability: Working indicator renders in the input box's bottom border, crowding queue count and decision...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Working indicator renders in the input box's bottom border, crowding queue count and decision flash
• 对用户的影响：Developers may hit a documented source-backed failure mode: Working indicator renders in the input box's bottom border, crowding queue count and decision flash
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/86 | Working indicator renders in the input box's bottom border, crowding queue count and decision flash

32. 能力坑 · 失败模式：capability: Write-gate novelty capture re-claims 'first successful use' of the same tool across days

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Write-gate novelty capture re-claims 'first successful use' of the same tool across days
• 对用户的影响：Developers may hit a documented source-backed failure mode: Write-gate novelty capture re-claims 'first successful use' of the same tool across days
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/89 | Write-gate novelty capture re-claims 'first successful use' of the same tool across days

33. 能力坑 · 失败模式：capability: remember()-saved memories are never tagged at write time; backfill runs so late in consolidat...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: remember()-saved memories are never tagged at write time; backfill runs so late in consolidation that user activity starves it
• 对用户的影响：Developers may hit a documented source-backed failure mode: remember()-saved memories are never tagged at write time; backfill runs so late in consolidation that user activity starves it
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/87 | remember()-saved memories are never tagged at write time; backfill runs so late in consolidation that user activity starves it

34. 能力坑 · 失败模式：conceptual: Act-guard sentinel echo replaces the user-visible answer with the CONFIRMED meta-line

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Act-guard sentinel echo replaces the user-visible answer with the CONFIRMED meta-line
• 对用户的影响：Developers may hit a documented source-backed failure mode: Act-guard sentinel echo replaces the user-visible answer with the CONFIRMED meta-line
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/98 | Act-guard sentinel echo replaces the user-visible answer with the CONFIRMED meta-line

35. 运行坑 · 失败模式：performance: Discovery candidates can enter permanent limbo: evidence re-accrual on unchanged clusters def...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Discovery candidates can enter permanent limbo: evidence re-accrual on unchanged clusters defeats staleness pruning
• 对用户的影响：Developers may hit a documented source-backed failure mode: Discovery candidates can enter permanent limbo: evidence re-accrual on unchanged clusters defeats staleness pruning
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/94 | Discovery candidates can enter permanent limbo: evidence re-accrual on unchanged clusters defeats staleness pruning

36. 运行坑 · 失败模式：performance: Exiting the REPL immediately after an answer skips that turn's end-of-turn bookkeeping

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Exiting the REPL immediately after an answer skips that turn's end-of-turn bookkeeping
• 对用户的影响：Developers may hit a documented source-backed failure mode: Exiting the REPL immediately after an answer skips that turn's end-of-turn bookkeeping
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/93 | Exiting the REPL immediately after an answer skips that turn's end-of-turn bookkeeping

37. 运行坑 · 失败模式：performance: Turns with an empty memory shelf are never recorded in injection traces

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Turns with an empty memory shelf are never recorded in injection traces
• 对用户的影响：Developers may hit a documented source-backed failure mode: Turns with an empty memory shelf are never recorded in injection traces
• 证据：failure_mode_cluster:github_issue | https://github.com/ahwurm/localharness/issues/96 | Turns with an empty memory shelf are never recorded in injection traces

38. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ahwurm/localharness | issue_or_pr_quality=unknown

39. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ahwurm/localharness | release_recency=unknown