AGENTS.md

Tech Stack

• Frontend: Vue 3 + TypeScript + Vite 8
• Desktop: Electron 43 (main: electron/, renderer: src/)
• State: Pinia stores in src/stores/
• Styling: Sass, scoped SCSS in Vue SFC
• Engine: Bun runtime in engine/ (独立 CLI 子项目, read-only)
• AI SDK: @anthropic-ai/sdk, openai

Architecture

三栏布局: Sidebar → ChatPanel → InfoPanel, 面板宽度由 splitLayout store 管理.

Engine 抽象: EngineFactory (electron/engine/engines/) 按类型创建引擎实例 (ClaudeCodeEngine, PiEngine). engineGateway 是统一调用入口 — 三个 adapter (claudeCodeIPC.ts / h5Server.ts / imServer.ts) 的引擎派发全部委托到此. 详见 docs/adr/0004-engine-gateway-deep-module.md.

Chat Session 生命周期: chatSession store 管理会话列表 → sessionProcess (Electron) 管理 CLI 子进程 → turn store (src/stores/turn/) 处理流式响应与工具事件.

IPC 通信: Electron main ↔ renderer, 通过 preload.ts 的 contextBridge 暴露安全 API.

Code Style

• TypeScript 严格模式; @/ → src/, @electron/ → electron/
• 组件 PascalCase (ChatPanel.vue), composables use 前缀, stores 驼峰
• Vue SFC: <script setup lang="ts"> + scoped SCSS
• Conventional Commits (feat/fix/style/refactor)
• 使用精确类型, 避免 any

Testing

单一 runner: Vitest (npm run test). 权威划分见 vitest.config.ts 的 include:

• tests/**/*.test.ts — 单元与集成测试
• src/**/*.test.ts — 与源码同处的单元测试
• electron/**/*.test.ts — 主进程测试 (放在 electron/<dir>/__tests__/ 下或直接同处, 两种都不被漏掉)

新测试优先与被测源码同处 (src/x/__tests__/ 或 electron/x/__tests__/); tests/ 保留给跨模块的集成与场景测试。三条 pattern 刻意保持宽, 不要改成枚举子目录 —— 见 docs/adr/0011-tests-must-cross-the-seam.md。

主进程测试在文件首行声明 // @vitest-environment node。

规则: 测试文件必须 import 它被测的模块。若某模块在测试里 import 不进来, 就修那个缝 (注入依赖、把模块级读取挪到 getter 之后), 不要把手抄的实现放进测试里 —— 那种测试对模块是否可用零敏感。详见 docs/adr/0011-tests-must-cross-the-seam.md。

覆盖率: npm run test:coverage (scope 与分路径阈值均在 vitest.config.ts). 阈值是棘轮 —— 只允许上调, 且必须与补测同一批提交; 想下调需在 PR 里说明理由. 语句率会被 mount-only 的测试刷高, 看分支/函数率判断覆盖是否真实。

CI: .github/workflows/test.yml 在 PR 与 push 到 main 时运行 npm run test:coverage 并上传 coverage/ 报告。

Rules

• 原型 HTML UI 生成在 docs/prototypes/
• 所有实现考虑 i18n (src/i18n/locales/zh-CN/, en-US/ 下的同名域模块)

src/ 目录分类规则

• lib/ — 领域逻辑: 有状态的、与业务概念耦合的模块 (e.g. targetClassifier.ts, tool-registry.ts, design/templates.ts)
• utils/ — 纯工具函数: 无状态、无副作用、可独立测试 (e.g. debounce.ts, uuid.ts, normalizePath.ts)
• shared/ — 跨 main/renderer 共享的基础设施: IPC channel 定义、类型桥接 (e.g. channelMap.ts, preloadBridge.ts)
• types/ — 类型声明文件 (.d.ts) 和纯类型导出
• components/common/ — 跨特性共享的 Vue 组件和指令

原生表单控件（select / option）必须跟随主题

Chromium 的原生下拉弹层不继承祖先的 color-scheme（Windows 上必现）。暗色主题里只给 select 本身设背景色，会得到「浅色弹层 + 主题浅色文字」，选项几乎不可读。这不是某个页面没适配，而是每个新写的 <select> 都会踩的坑。

• 全局规则在 src/styles/global.scss：select 按主题声明 color-scheme（light 默认，[data-theme='dark'] / [data-theme='anthropic-dark'] 为 dark），option / optgroup 显式使用 --bg-elevated / --text-primary。
• 新增 <select> 直接复用这套规则，不要再给 option 写硬编码浅色背景，也不要只依赖祖先主题。
• 新增暗色主题时，必须同步补 [data-theme='<name>'] select { color-scheme: dark; }。
• 验证方式：在暗色主题下真正展开下拉弹层（不是只看收起态），确认选项背景与文字都跟随主题；仅截图收起态不算验证。

Guardrails

• engine/ 为独立子项目, 视为只读
• 构建产物 (dist/, dist-electron/, release/) 视为只读
• 敏感文件 (.env, API keys) 不提交
• 仅实现请求的功能, 不添加额外抽象或配置项

Verification

每次代码修改后依次执行, 全部通过才算完成:

npm run test:changed  # 只跑受改动影响的测试 (vitest --changed, 基于 import 依赖图)
npm run build         # vue-tsc --noEmit + vite build (已含类型检查)

默认只跑 test:changed —— 无论改动大小, 包括收尾时, 都不要求跑全量 npm run test。全量仅在以下情况运行:

• 用户明确要求全量测试
• 改动命中 forceRerunTriggers (vitest.config.ts、package.json 依赖变更) —— 此时 test:changed 自身会升级为全量, 无需额外操作
• test:changed 显示 0 个受影响测试, 且改动疑似通过动态 import / 运行时路径影响其他模块

提交前的全量兜底交给 CI (.github/workflows/test.yml 会跑 test:coverage), 本地不重复跑。

任一失败则修复后重新执行.

Agent skills

• Issue tracker: GitHub Issues (hjdspace/SpaceCode), via gh CLI → docs/agents/issue-tracker.md
• Triage labels: needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix → docs/agents/triage-labels.md
• Domain docs: CONTEXT.md + docs/adr/ → docs/agents/domain.md