claw-code 源码分析：爆款开源之后——Star 曲线与长期维护之间，工程上该建立哪些「反幻觉」机制？

语境 ：README 置顶 Star History 与「最快破 5 万 star」叙事，与 Porting Status / 免责声明 / PARITY 缺口 并存。本文从 claw-code 既有实践 出发，归纳可复用的 反幻觉 （anti-hallucination）工程机制：让仓库对外说法、对内门禁与真实能力 可对账。

---

1. 为何需要「反幻觉」：注意力 ≠ 完成度

爆款会带来三类 认知扭曲：

1. 访客：把 star 数当成「生产就绪、功能等价、官方背书」。
2. 贡献者：假设主分支即权威实现，忽略 Python port / Rust product 的分工。
3. 维护者 ：在 README、推文式横幅里写 时间敏感承诺 （例如「今日合并」），过期后变成 文档幻觉。

claw-code 在显眼位置同时放置 celebration（星标曲线） 与 未完成声明，本身就是一种张力管理：

<p align="center">
  <strong>⭐ The fastest repo in history to surpass 50K stars, reaching the milestone in just 2 hours after publication ⭐</strong>
</p>

<p align="center">
  <a href="https://star-history.com/#instructkr/claw-code&Date">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=instructkr/claw-code&type=Date&theme=dark" />
      ...
    </picture>
  </a>
</p>

## Porting Status

The main source tree is now Python-first.

- `src/` contains the active Python porting workspace
- `tests/` verifies the current Python workspace
- the exposed snapshot is no longer part of the tracked repository state

The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.

反幻觉第一课 ：高流量入口必须 同屏 出现 能力边界（未完成、非等价替换），否则星标曲线会替代事实。

---

2. 机制一：法律与品牌边界（防「被代表」幻觉）

文末 Ownership / Affiliation Disclaimer 把「我们不是谁」写死，降低 star 带来的误关联风险：

## Ownership / Affiliation Disclaimer

- This repository does **not** claim ownership of the original Claw Code source material.
- This repository is **not affiliated with, endorsed by, or maintained by the original authors**.

Rust 子文档强调 clean-room、inspired、非逐行拷贝 （见 rust/README.md，result/18.md 已引）。
工程要点 ：这类段落应 短、置顶或置底固定节，并在 PR 模板中提醒「勿暗示官方关系」。

---

3. 机制二：可执行门禁（防「我说测过」幻觉）

3.1 Python：unittest discover 为契约

README Quickstart 与 WorkspaceSetup.test_command 对齐（result/26.md）：绿/红不依赖口头描述。

3.2 Rust：CI + CONTRIBUTING 显式清单

CI 在 main 的 push/PR 上跑 cargo check、cargo test、release build，且 Ubuntu + macOS 矩阵，避免「本机能跑」幻觉：

# 1:36:rust/.github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  rust:
    name: ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os:
          - ubuntu-latest
          - macos-latest
    ...
      - name: Run cargo check
        run: cargo check --workspace

      - name: Run cargo test
        run: cargo test --workspace

      - name: Run release build
        run: cargo build --release

rust/CONTRIBUTING.md 要求 PR 前 fmt / clippy -D warnings / check / test，把「合并门槛」写成命令：

## Test and verify

Run the full Rust verification set before you open a pull request:

```bash
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo check --workspace
cargo test --workspace

If you change behavior, add or update the relevant tests in the same pull request.

反幻觉要点 ：维护者宣称「稳定」时，应能指向 与工作流 YAML 一致的绿色 run；缺 CI 的爆款库最易产生集体幻觉。

---

4. 机制三：能力账本（防「已对齐」幻觉）

4.1 PARITY.md：显式列缺口

执行摘要直接写 not feature-parity 与最大 gaps，避免 star 读者以为 Rust 已克隆 TS 全栈：

## Executive summary

The Rust port has a good foundation for:
- Anthropic API/OAuth basics
- local conversation/session state
- a core tool loop
- MCP stdio/bootstrap support
- CLAW.md discovery
- a small but usable built-in tool set

It is **not feature-parity** with the TypeScript CLI.

Largest gaps:
- **plugins** are effectively absent in Rust
- **hooks** are parsed but not executed in Rust
...

4.2 parity-audit：数据可对账、缺输入不装完成

无本地 archive 时明确 无法对比 ；有 archive 时单测才收紧（result/26.md）。这是 条件真值，不是永远绿的虚假宣传。

4.3 README「Current Parity Checkpoint」

承认 更近但仍非运行时等价 （README 后续章节），与 star 叙事形成 纵向对照。

---

5. 机制四：词汇与数据契约（防「已实现」幻觉）

• Mirrored* 执行路径、hooks 占位包 （PORTING_NOTE）------用户可见输出不说「原版 hooks 已落地」。
• reference_data 快照 ------命令/工具 条目规模 可测，语义 parity 另议。
• .omx/ 忽略、diff 排除 （result/27.md）------不把 ephemeral 编排状态误认为产品变更。

---

6. 机制五：时间敏感声明的治理（防「README 过期」幻觉）

README 顶栏 [!IMPORTANT] 含 分支与时间预期 （例如 Rust 合并节奏）。此类块 极易过期 ；过期后读者仍信，即 维护者制造的文档幻觉。

工程建议（本仓库可增强，亦适用于其他爆款项目）：

• 用 版本化 CHANGELOG / Release 替代「今日/明天」式语言。
• 或用 issue/里程碑链接 替代绝对时间。
• CI 增加 链接巡检（可选）或定期 issue「 scrub README callouts」。

---

7. 小结：反幻觉机制清单（可照单扩展）

目标	推荐机制	claw-code 中的锚点
防 完成度 幻觉	首页并列「未完成/非 1:1」与 star 展示	Porting Status、Current Parity Checkpoint
防 法律/背书 幻觉	固定免责声明 + clean-room 表述	README Ownership 节、rust README
防 质量 幻觉	CI + 贡献指南命令一字不差	rust/.github/workflows/ci.yml、CONTRIBUTING.md
防 功能对等 幻觉	缺口文档 + 可运行 audit	PARITY.md、parity-audit、条件单测
防 数据 幻觉	快照与命名诚实	reference_data、Mirrored、占位子系统
防 过程 幻觉	排除本地垃圾目录、可复现命令	.gitignore、diff exclude .omx
防 时效 幻觉	少写绝对时间，多链接事实源	审视顶栏 IMPORTANT 类 callout

一句话 ：Star 曲线量的是 注意力 ；长期维护要的是 可证伪陈述 + 可复跑门禁 + 显式缺口账本 。claw-code 已嵌入多条此类机制；爆款之后真正的工程功课，是让 横幅与 YAML 同寿 ，让 新访客的默认印象 落在「能证明什么」而不是「有多红」。

---