Twiceshy

twiceshy

一朝被蛇咬，十年怕井绳。

一项可自托管的服务，会在大模型编码 Agent 做出决策时，向其提供来之不易的工程经验——问题、走过的弯路、根本原因和经验证的修复方案，让它们不再依靠自动驾驶般的惯性重复已知错误。记录由 Git 管理并保留来源信息；自动检索设有相关性门槛，匹配度不足时可以不返回任何结果。

托管版 Alpha

托管实例运行于 twiceshy.app——提供自助令牌和远程 MCP 端点 https://api.twiceshy.app/。外部贡献必须先签署 CLA 才能合并 （ADR-0002）。

工作原理（已锁定的架构）

• **事实来源：**由 Git 管理的 Markdown 经验记录（YAML frontmatter + 叙述内容）——格式见 docs/SCHEMA.md。语料库是独立的版本化数据产品（twiceshy-corpus， ADR-0021）；引擎附带一份小型、冻结的测试固件（internal/testcorpus/）。
• **索引：**一个可随时重建的派生 SQLite 文件（FTS5，以及用于拉取检索的缓存纯 Go 稠密向量）。
• **检索：**指纹精确匹配 → BM25 → 稠密检索（RRF），按堆栈指纹过滤，k≤3 的硬上限，并设置相关性门槛——低于门槛时，不会注入任何内容。
• **通道：**推送（Claude Code 钩子 → 陷阱卡片）、拉取（通过可流式传输的 HTTP 提供 MCP 工具）、索引（生成的一句话摘要）。
• **信任：**Agent 提议的记录会被隔离；晋升条件 = 沙箱验证从失败转为通过 + 人工审查 PR。新增记录本身就是一个拉取请求。
• **维护任务：**后台作业，负责去重、检查过时情况、重新执行复现步骤（记忆的 CI）、衰减和抽象。

完整原理说明：docs/research/EXPERIENCE_SERVICE_RESEARCH.md 和 docs/adr/ADR-0001-architecture.md。

状态

核心服务已作为托管版 Alpha 提供。当前已发布功能的权威快照和现行路线图，请参见 docs/NEXT_FEATURES.md；部署和运维详情见 docs/DEPLOY-public-alpha.md。

开发

make ci    # lint + race tests + coverage floor — what CI runs

请先阅读 docs/CONVENTIONS.md 和 docs/CONTEXT.md。

许可证

AGPL-3.0-only。贡献和语料库许可说明： docs/adr/ADR-0002-licensing-strategy.md。