团队 / 贡献规范（CLAUDE.md 摘录）

在仓库里改代码前必读。以下为 CLAUDE.md 关键内容摘录，完整版见仓库根：CLAUDE.md（托管在仓库里）。

---

🚫 绝对红线：git stash 禁用

本项目任何情况下都不允许 git stash（含 push / pop / apply / drop / create / store）。 零例外。

原因记录：本仓库 git stash（尤其 pop/apply）曾反复把工作树破坏到 Claude 无法修复：

• 覆盖 electron/node_modules/electron/path.txt 为 macOS 的 Electron.app 路径 → Windows 下 npm run electron:dev ENOENT；
• 静默还原工作树源码（如 src/models/rewriter.py 丢失）→ bridge 预热崩溃。

替代：

• 对比 master：git diff <SHA> -- <path>
• 可逆实验：直接编辑后改回 / 开分支
• 暂存临时文件：cp 到 workspace/tmp/

安装 / 运行 / 测试三连

# 装环境
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 后端独跑（hypercorn + HTTP/2, 127.0.0.1:18711）
.venv/Scripts/python -m src.bridge.run

# 测试（须真 SQLite，不要 mock 仓库）
FAMILIARS_DB_PATH=:memory: pytest -q

不要用 uvicorn src.bridge.app:app --reload —— 丢 HTTP/2 且会在 worker 线程 race 初始化 CUDA，Windows WDDM 下崩溃。

三大 agent 接线提醒

• 管理者（agent 0）：每轮注入「框架文档 + 日志索引」（render_framework_index）+「Bridge API 目录」（bridge_api_surface）+ 4 个专用工具（list/read_framework_doc、list/read_log）。
• 新增文档/日志要同步更新 src/utils/framework_tools.py 的 KNOWN_LOGS 与索引生成器。

本仓库的自愈机制

• 路径漂移自动对齐：启动时把对话路径前缀自动改写（记录到 workspace/.paths_aliases.json）；外部目录改名用 python -m src.tools.paths_migrate <old> <new> --record（先 --dry-run）。
• HKDF info 是 b"familiars-secrets-v1"：轮换会失效所有 SECRET.json，须同时做迁移。

---

完整版（含环境变量表、架构摘要、跳转表）：仓库根 CLAUDE.md