安装依赖：uv sync --frozen（Python 3.12+）。命令统一用 uv run python -m <pkg> 形式：本机实测 uv run pytest --version 报 uv trampoline failed to canonicalize script path（exit 1），uv run python -m pytest --version 才通。
- 聚焦检查（改完先跑，秒级）：
uv run python -m pytest tests/test_<对应模块>.py -q -p no:cacheprovider - 全量测试（约 11 分钟）：
uv run python -m pytest -q - lint / 格式：
uv run python -m ruff check <files>、uv run python -m ruff format <files> - 类型检查：
uv run python -m mypy --follow-imports=silent <files>— 全量基线有 519 个存量错误（.qoder/mypy-baseline.txt），故只查变更文件、CI 里非阻塞 - MCP handler 契约（126 项断言，入口是
main()而不是test_*，pytest 永远收集不到它）：uv run python tests/okf_regression_test.py。CI 的 test job 已显式运行，但因 6 条断言落后于产品变更（当前 120 通过 / 6 失败）而暂为continue-on-error。 ⚠️ 不要直接跑tests/smoke_test_mcp.py：它把本仓真实路径传给analyze_repo，而codewiki/mcp/tools/analysis.py:57-64已把 output_dir 收敛为repo_path的纯函数（忽略调用方覆盖），运行它会写入真实repowiki/并在analysis.py:74触发session_ff_onlygit 操作。
本项目已使用 CodeWiki 生成 LLM Wiki 文档，位于 repowiki/ 目录。
入口文件：
repowiki/wiki/overview.md— 仓库级架构总览（含 Mermaid 架构图）repowiki/wiki/index.md— 文档目录与知识笔记索引repowiki/schema.yaml— 项目文档约定（命名规范、必填章节等）
- 编码前：
query_wiki搜模块文档，了解架构约定和依赖关系 - 做决策时：
query_wiki搜已有decision笔记，避免重复讨论 - 完成重要决策后：
ingest_note归档；被用户纠正/吐槽时：反思→起草→征求确认后归档（三步流程与归档示例见get_prompt(name="ingest-note")） - 定期维护：
lint_wiki检查文档是否过时
- 引用
query_wiki检索结果 → 标注（依据：<file>），与返回的file字段完全一致； - 引用代码事实 → 标注
<代码文件>:<行号>，行号以实际读取为准； - 依据来自本次代码核对 → 明说来源。
通过 query_wiki 检索并实际使用了某条结果时，在最终回复末尾附带：
<!-- codewiki:referenced-docs: ["notes/pitfall-xxx.md", "wiki/modules/yyy.md"] -->
路径与 query_wiki 返回的 file 字段完全一致。声明过的文档获得采纳计数、检索排序提升；零采纳高频笔记会被 lint_wiki 的 low_adoption 检查标记。只声明真正用到的——漏报可容忍，误报不可容忍。
触发信号（任一）：多步骤调试定位根因、多方案讨论后做出选择、代码行为与文档/命名不一致、用户补充隐性项目知识、调研收敛到明确结论、发现可复用模式。
四问过滤（全部通过才记录）： 下次对话还能用到？其他 Agent/新同事能直接受益？query_wiki 确认未覆盖？属于"事实/决策/模式/教训"而非临时状态？
路由表： 技术选型→ingest_note(note_type="decision")；踩坑→pitfall；经验教训→lesson；架构发现→architecture；临时绕过（含恢复条件）→workaround；多方案对比→write_doc_file(page_type="comparison")；调研存档→write_doc_file(page_type="query")。
执行细节（结构化模板、查重、确认流程）见 get_prompt(name="ingest-note")。不要记录：本次任务临时变量/路径/参数、个人偏好、代码注释或 README 已写明的信息、未经验证的猜测。
所有产出使用中文——Wiki 文档、笔记、代码注释、commit message、给用户的回复，除非用户明确要求其他语言。检索到的历史文档若为其他语言，新产出仍按本规则。
Matt Pocock 工程技能（v1.3.1，27 个）装在共享库 ~/.agents/skills/；标了 disable-model-invocation 的那些（grill-me、to-spec、to-tickets、handoff、retro、implement 等）只能 /斜杠 手动调用，不会自动命中。
对外来件与分诊队列走本仓库的 GitHub Issues（gh CLI）；会话内部拆出的实现工单落 .scratch/<feature>/issues/，不进公开仓库。判据与两套约定见 docs/agents/issue-tracker.md。
五个规范角色：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。映射见 docs/agents/triage-labels.md。
单上下文布局：根 CONTEXT.md（术语表事实源，GLOSSARY.md 是指向它的符号链接）+ docs/adr/。消费规则与写回口径见 docs/agents/domain.md。
对话经验蒸馏进知识飞轮的实现入口与设计约束（Mode A/B/C、raw 暂存区语义、distilled_file 侧通道），见 repowiki/wiki/team-memory-fusion.md。
跨会话延续长线工作上下文。任务记忆是任务范围内的进度知识，与 Wiki 笔记（跨任务的通用经验）互补。
会话开始时（必须执行）：若本会话已收到 SessionStart hook 注入的任务关联指引，按其执行（弹框规则、补蒸馏、收尾采集以注入为准）；未收到注入时，按 get_prompt(name="task-workflow") 的「会话开始：关联任务」一节执行——用宿主原生结构化提问工具弹一次任务关联框（CodeBuddy 系 ask_followup_question：一框列全所有进行中任务 + 新建 + 跳过；Qoder 系 AskUserQuestion：单题 options 硬上限 4、硬下限 2，取最近的 3 个任务 + 跳过（选项位有富余时补「新建任务」），其余任务写进问题正文、由「其他」自由输入承接），绑定后 get_task_context 拉取上下文。
完整工作流（补蒸馏、会话中采集、收尾、检索、存储布局与实现约束）见 MCP prompt：get_prompt(name="task-workflow") —— 按需获取。
与批处理（收尾采集 → 下轮蒸馏）互补：停顿点即写即沉淀，任务记忆与草稿笔记下一轮 get_task_context 即可见，不必等蒸馏。
① 自然停顿点判据（命中任一即沉淀；每轮回复收尾前自查，不要依赖「想起来」）：
- 任务里程碑达成；
- 关键技术决策落定，或澄清/纠偏了产品机制、代码事实等关键认知；
- 用户话题明显转向；
- 收尾轮（强制兜底，必做）——无论会话中是否命中前三条，收尾轮必须做一次沉淀自查：本会话是否有未沉淀的进展/决策？有则按下方两条路径补写。
不做字面每轮沉淀：任务记忆追加无去重，每轮都写会灌爆记忆并反复触发 40 条/24KB 压缩阈值——只在停顿点沉淀。宿主 IDE 自带的工作记忆（如 .codebuddy/memory/）与本协议的任务记忆是独立通道，写了前者不豁免后者。
两条写入路径（均当轮落盘，下一轮 get_task_context 即取；禁止手写文件）：
- 任务记忆：
add_task_memory(task_id=<绑定的任务id>, content="本段进展/决策/下一步")直写——无需确认。写入标准：只记会改变下一步行动的进展/决策/约束；推翻旧记忆时传supersedes=<旧条目id>，不要追加平行副本；近重复写入会被拒绝（difflib > 0.85），改用 supersedes 或合并改写后重试； - 通用经验：
ingest_note(status="draft", ...)落草稿——确认闸门保留：草稿笔记须经confirm_note确认后才进入全局检索语料，不得跳过确认。草稿落盘即可被下一轮get_task_context的related_notes以status: draft展示、能确认、能参与冲突检测。