CLAUDE.md — we-need-ds 开发规范

Claude Code / cc-haha 双宿主插件：在 DeepSeek-V4-Pro 系模型上动态模拟 DeepSeek Harness (DSH) 极简模式，稳定触发 "We need..." 深度思维链。完整工程史见 docs/ENGINEERING_REPORT.md（权威，先读）。

项目目的

不关闭任何 MCP，通过本地代理在"判定轮"把请求体裁剪成 DSH 官方极简形态（单行人格 + Bash/Edit 两件套），"执行轮"全量放行，从而在 Claude Code / cc-haha 中逼近 DSH 极简模式的效果。非目标模型（Claude/GPT/Gemini/Qwen 等）字节级原样透传。

架构速览

双轨分治:
  cc-haha GUI 轨  → 单服务商接管 providers.json activeId 本体 → :20329
  Claude Code CLI 轨 → hooks (SessionStart/UserPromptSubmit/SessionEnd) 驱动 → :20329
  proxy.js   代理网关: 轮次判定 + DSH 塑形 + keyMap 路由 + 三道超时门 + 重试
  lib/state.js  状态机: 接管/两段式释放/副本体系/文件锁/原子写/账本迁移
  lib/ctl.js    on/off/status/doctor/boot/restart
  hooks/*.js    仅官方 CC 生效 (cc-haha sidecar 不执行插件 hooks)
  skills/       cc-haha 下唯一可用的指令入口 (commands 斜杠指令在 cc-haha 不可用)

• 代理端口 20329，仅绑 127.0.0.1
• 账本 ~/.claude/we-need-ds/runtime-state.json（跨插件版本持久化；插件目录内禁止写状态——${CLAUDE_PLUGIN_ROOT} 随更新变路径）
• 接管 = 本体 baseUrl→代理 + 建 wnd-copy-<id> 直连副本（逃生口兼冗余账本）；释放 = 两段式（还原验证通过才删副本）
• 任何失败路径 → 立即还原直连防死锁；还原可逆，账本 enabled 时下条消息钩子自动重接管

常用命令

node test_full.js          # 主测试套件，隔离运行 (tmp 目录 + 端口 21329)，须全绿
node test_consume.js       # 消费方视角请求形态测试
node test_stress.js        # 并发/极端场景压力审查 (隔离端口 21340/21341/21342)
node lib/ctl.js on|off|status|doctor|boot|restart

测试禁止触碰生产 daemon (:20329)、生产 ~/.claude/cc-haha/providers.json 与生产账本。隔离三环境变量：WE_NEED_DS_TEST_PORT / WE_NEED_DS_PROVIDERS_PATH / WE_NEED_DS_DATA_DIR（test_full.js 与 test_consume.js 已内置）。

宿主适配规范（开发铁律）

官方 Claude Code（来源: code.claude.com/docs/en/plugins-reference）：

• 组件目录（skills/commands/agents/hooks 等）必须放插件根目录，严禁放 .claude-plugin/（只放 plugin.json）
• plugin.json 唯一必填字段 name；author 必须是对象 {name, url}
• hooks.json 三层嵌套：hooks → 事件名 → {matcher, hooks:[...]} → handler 数组（我们 hooks/hooks.json 已是此格式，勿改平）
• ${CLAUDE_PLUGIN_ROOT} = 安装缓存绝对路径，只读；${CLAUDE_PLUGIN_DATA} = ~/.claude/plugins/data/<id>/，可持久写
• skills/commands/agents/*.md 的 frontmatter：--- 必须是文件第一行

cc-haha（来源: NanmiCoder/cc-haha src/utils/plugins/）：

• 官方机制同构：安装即复制到 ~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/，${CLAUDE_PLUGIN_ROOT} 指向该缓存路径
• sidecar 常驻 HTTP server，剥 /proxy/providers/<activeId>/ 前缀转发到 provider.baseUrl，不执行插件 hooks → cc-haha 轨的接管只能靠手动 on/boot + daemon 常驻
• 代理收到请求不含"当前激活哪个 provider"信息 → 只能按 API Key 路由（keyMap），接管锚定 activeId
• cc-haha 下 commands 斜杠指令不可用，skills 可用 → 所有用户入口走 skills/
• 9router 的 /v1/messages 非流式返回 OpenAI 格式 → 协议判定必须路径优先于 body 特征（formatFromRequestPath）
• 600s 流超时是 sidecar 客户端硬编码行为，插件无法解除；裁剪只提高收敛概率

设计边界（用户已明确否决/确立，勿再提）

1. 不做任何系统级注册（无 Startup 文件夹、无计划任务、无开机自启）——用户明确否决；重启后恢复由用户显式 on/boot
2. 失败即还原、还原可逆：绝不把 provider 留在"指向死代理"状态；502 显式失败优于静默错发
3. 非 DS 模型零侵入：不碰人格、不碰 tools、不碰 thinking
4. 判定轮保留历史已调用工具（collectUsedToolNames），防模型续写引用未声明工具导致协议校验失败
5. 流式响应豁免 body 超时门（推理模型首 token 可合法慢到几十秒）；首字节后不重试，中途断开对客户端透明 destroy
6. 无可信还原来源的孤儿不瞎猜还原，保持原样并列警告

代码风格

• 无构建步骤、无第三方依赖，纯 Node.js 内置模块（http/https/fs/path/os）
• 编辑 D:\projects\ 下任何文件不加注释
• 面向 Windows（taskkill/netstat）但逻辑保持跨平台可读
• 文档/README/CHANGELOG 与 semver（plugin.json）同步更新；机制版本号（v5/v5.1）与 semver 是两条独立编号线

已知坑（改代码前必看，详见报告第 6/9 节）

• 测试曾污染生产 config.json → 一切测试走隔离环境变量，动生产文件前先备份
• 残留测试进程会引发 EADDRINUSE 假失败 → 假失败先查残留进程，别急着改代码
• 账本散落在版本化 cache 路径导致升级"失忆" → 已由 migrateLegacyFiles 迁移；新数据一律写 ~/.claude/we-need-ds/
• 端口变更场景：真实上游恰好等于旧代理端口时，靠 proxyPorts 集合（config.port ∪ 账本 proxyUrl）区分，勿用单端口判断
• 上游解析优先级固定：config.targetBaseUrl > keyMap[apiKey] > 账本 defaultUpstream > env ANTHROPIC_UPSTREAM_BASE_URL > 502