StockAI
CLAUDE.md14 starsChanged 3 months agoMITView on GitHub
Three-layer architecture: UI → Tauri Core (Rust) → Sidecar (Bun) shared/ 目录是跨层唯一来源:types/(DTO 类型,按上下文分文件 + barrel,一律 from '../shared/types')、actions.ts(Sidecar CLI 动作清单,三层布线的单一来源)、market.ts(detectMarket 函数)、constants.ts(默认大师列表等)。前端与 Sidecar 各自 re-export,不得在各层重复定义。 新增 Sidecar 能力只需三处:shared/actions.ts 加一条 + sidecar/cli-handlers/ 对应领域文件实现 handler + sidecar/index.ts 的 DISPATCH 加一行——Rust(泛化 invoke_sidecar)与 src/lib/ipc.ts 的调用管道无需改动。 详细架构说明见 .claude/rules/architecture.md(需要时 Read 该文件)。
In this repository4 other files it gives its agents.
- add-providerSkill
- new-master-agentSkill
- new-strategySkill
- release-notesSkill
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 72
Code comments: All inline logic comments must be written in Simplified Chinese.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Commands
# Install dependencies
bun install
# Start development environment (Tauri + Vite)
bun tauri dev
# Build for production
bun tauri build
# 一键跑全部单元测试(聚合 vitest + sidecar bun test,自带超时不依赖 GNU `timeout`)
bun run test
# 同上但额外跑 sidecar 集成测试(需要网络)
bun run test:integration
# 只跑集成测试——即每日「数据源冒烟监控」CI 任务跑的那一套
bun run test:integration:only
# 单独跑前端 vitest
bunx vitest run
# Run a single frontend test file
bunx vitest run src/hooks/useAnalysis.test.ts
# 单独跑 sidecar 单元测试
cd sidecar && bun test
# Run a single Sidecar test file
cd sidecar && bun test exchange.test.ts
# 单跑某个 Sidecar 集成测试 (需要网络, 较慢, 可能 flaky)
# `./` 前缀不可省:不带前缀时 bun test 把它当过滤器,而文件名不含 .test/.spec,匹配 0 个文件
cd sidecar && bun test ./scraper.integration.ts
# Rust tests
cd src-tauri && cargo test
# Build Sidecar binary (cross-platform, via build-script)
BUN_TARGET=bun-darwin-arm64 OUTFILE=src-tauri/bin/stockai-backend-aarch64-apple-darwin bun sidecar/build-script.ts
# Verify sidecar bundle integrity
bun scripts/verify-bundle.ts src-tauri/bin/stockai-backend-aarch64-apple-darwin
# Integration smoke test
bun scripts/smoke-test.ts
# 前端 E2E 冒烟:起 vite + 真浏览器,断言 K 线确实画出来了(改 PriceChart 后必跑)
bun run test:e2e
# 代码格式化(biome,仅源码 ts/tsx);--check 版只校验不写盘(pre-push 门禁用)
bun run format
bun run format:checkArchitecture
Three-layer architecture: UI → Tauri Core (Rust) → Sidecar (Bun)
shared/ 目录是跨层唯一来源:types/(DTO 类型,按上下文分文件 + barrel,一律 from '../shared/types')、actions.ts(Sidecar CLI 动作清单,三层布线的单一来源)、market.ts(detectMarket 函数)、constants.ts(默认大师列表等)。前端与 Sidecar 各自 re-export,不得在各层重复定义。
新增 Sidecar 能力只需三处:shared/actions.ts 加一条 + sidecar/cli-handlers/ 对应领域文件实现 handler + sidecar/index.ts 的 DISPATCH 加一行——Rust(泛化 invoke_sidecar)与 src/lib/ipc.ts 的调用管道无需改动。
详细架构说明见 .claude/rules/architecture.md(需要时 Read 该文件)。
Key Conventions
- Code comments: All inline logic comments must be written in Simplified Chinese.
- Component size: UI component files must stay under 200 lines; extract complex logic into hooks.
- Test decoupling: 解析逻辑放在
sidecar/parsers/目录(exchange.ts/html.ts),与网络层分离,离线测试见parsers/*.test.ts。抓取链路统一暴露fetchImpl注入点(KlineSourceDeps/SearchDeps/QuantDeps同形),默认套件必须离线可跑;真网络断言放*.integration.ts(只在bun run test:integration跑,文件由 glob 自动发现、无需登记)。离线 fixture 对上游改版是结构性失明的(fixture 永不变,故永远绿),所以每个外部数据源都要在*.integration.ts里有一条形状断言,由每日 CI 任务.github/workflows/datasource-smoke.yml兜底;断形状不断数值,且结果非空是必断项——本层多处容错把失败吞成{}/null,只断「没抛异常」等于没监控。 - 图表的第二块结构性失明:vitest 跑在 happy-dom 上、没有 canvas,
PriceChart.test.tsx把 lightweight-charts 整个 mock 掉了——图表画不画得出来在默认套件里断不到。补位的是bun run test:e2e(scripts/e2e-smoke.ts):起 vite + 真浏览器,读回 canvas 像素断言 K 线实体色覆盖 ≥ 20 条像素行。行数而非像素数是关键:空图表照样画网格和坐标轴,现价水平线也是涨跌色且横跨整幅宽度,只有实体会沿价格轴铺开几十行。动src/components/PriceChart/后必跑这条。 - Outbound HTTP: 一律经
sidecar/http.ts的fetchWithPolicy(url, policy),UA 与超时的唯一来源是sidecar/config.ts的HTTP_DEFAULTS。不要在数据源模块另写 UA 字面量或AbortSignal.timeout(...)。 - Frontend async hooks: 「按 symbol 取数」复用
useSymbolFetch,「按 symbol 缓存异步结果」复用useSymbolScopedAsync(含竞态守卫 + LRI 限容),不要再手搓一份。 - Adding a K-line / quote source: 在
sidecar/kline/index.ts的KLINE_SOURCES[市场]或QUOTE_SOURCES[市场]数组追加一行即可(依次尝试、首个成功即返回),不必改控制流。两张表分开且顺序不同是刻意的:K 线要复权(故美股 Yahoo 优先),报价只看可达性(故美股腾讯/新浪优先,Yahoo 兜底)。理由写在表上方的注释里,改顺序前先读。 - Adding a scrape strategy: 实现
sidecar/strategies/base.ts的ScrapeStrategy,然后在sidecar/strategies/registry.ts的StrategyRegistry.strategies追加一行。能跳过 Chromium 的策略尽量排前。 - Adding an AI provider: 兼容 OpenAI 协议时,在
shared/constants.ts的PROVIDER_PROFILES加默认值(sidecar/config.ts仅 re-export,勿在此加)+providers/registry.ts的PROVIDER_FACTORIES追加一行;协议不兼容时在sidecar/providers/实现AIProvider接口(sidecar/ai.ts)。最后同步shared/types/provider.ts的ProviderType。 - i18n: 多语言通过
Language类型(shared/types)传递;前端用useLanguage()hook 获取翻译函数;src/i18n/zh.json是翻译 key 的 TypeScript 类型来源(编译期校验),新增 UI 文字须先在此文件加 key。 - Sidecar stderr is for debug logging; stdout must only contain the final JSON output.
- 构建期依赖,勿当死依赖删、也勿独立升:
chromium-bidi在全仓源码里零引用,但bun build --compile会静态解析playwright-core/lib/coreBundle.js里的require("chromium-bidi/..."),缺它则 sidecar 编译直接失败。源码级引用扫描看不见node_modules内的预打包产物——删依赖前请以「干净 node_modules 下bun run sidecar:build能否通过」为准,而不是只看 import 引用数。版本同样不由我们做主:coreBundle 硬编码的是chromium-bidi/lib/cjs/...,而该目录自 16.0.0 起已不存在(16 挪到lib/、17 的 gn migration 挪到out/Default/gen/src/),升任何 ≥16 的版本都会让编译报Could not resolve(PR #6 实测三平台全挂)。故 package.json 精确锁15.0.0、dependabot 忽略>=16(15.x 内的更新仍放行);只能跟着playwright-core一起动——升级它之后对照新的coreBundle.js里的 require 路径再定版本。 - Formatting: biome 统一格式(单引号 / 2 空格 / lineWidth 100,配置见
biome.json,仅 formatter 不开 linter)。改完跑bun run format;用 Claude Code 时.claude/hooks/会在编辑时自动 format + 跑相关测试 + 拦截硬编码 API key。
Workflow
- Claude Skills:
/new-master-agent(引导新增投资大师 Agent)、/add-provider(引导新增 AI Provider)、/new-strategy(引导新增抓取策略)、/release-notes(生成双语 Release Notes 并写入docs/release-notes/)。.mcp.json已提交,重启 Claude Code 后 context7 MCP 生效(对话中说use context7查实时库文档);sqlite-historyMCP 的 db 路径写死为 macOS 的~/Library/Application Support/com.hyh.stockai/,仅 macOS 可用,Linux/Windows 贡献者可忽略该 server。 - 提交前流程:非纯文档改动 commit 前先跑
agent-skills:code-simplification→agent-skills:code-review-and-quality(有问题修完再回简化)。维护者本地由全局 hook(~/.claude/hooks/commit-gate.sh)强制——拦未声明审查的代码提交,审查后用REVIEWED=1 git commit ...放行,纯文档自动豁免。 - Pre-push 钩子 (
lefthook.yml) 并行跑tsc --noEmit、cargo check、bun run format:check(biome 格式门禁)。 - 开发期若想跳过 Tauri 外壳直接调 Sidecar,可运行
bun scripts/sidecar-bridge.ts(:3001 HTTP 端点)。浏览器 dev 模式下src/lib/ipc.ts自动走该桥接器,bridge 未启动时退回 mock 数据并console.warn一次。
Release Checklist
完整发版流程(含双语 Release Notes 模板)见 .claude/rules/release-checklist.md(发版时 Read 该文件)。
版本号需同步 4 处:src-tauri/tauri.conf.json / src-tauri/Cargo.toml / package.json / src-tauri/Cargo.lock,一键同步:bun run bump-version <x.y.z> --write(前三个改文本,Cargo.lock 由脚本调 cargo update --workspace --offline 重锁)。
.claude/ 目录
| 路径 | 内容 |
rules/architecture.md | 三层架构契约(需要时 Read) |
rules/release-checklist.md | 发版全流程 + 双语 Release Notes 模板(发版时 Read) |
skills/ | 四个引导技能:/add-provider、/new-master-agent、/new-strategy、/release-notes |
agents/ | 五个专职 Agent,按需单独调用,不自动起团队 |
hooks/ | pre-edit.sh(门禁文件提醒 + 硬编码 API key 拦截)、post-edit.sh(stdout 纯净 / rustfmt / biome / tsc / 相关测试) |
五个 Agent:四个审查维度 —— layer-boundary-reviewer(架构边界)、api-key-security-reviewer(key 传递链)、code-quality-reviewer(逻辑 bug 与项目硬约束)、i18n-consistency-reviewer(三语一致性);外加 release-manager(发版门禁编排)。
各 Agent 的清单彼此不重叠,可并行调用后自行汇总;日常单点改动直接处理即可,不必起 Agent。
- Zod 安全覆盖:
overrides.zod要求 ≥4.6.7,修复 GHSA-mrhx-c7xc-m3w5。chromium-bidi@15.0.0仍为 Playwright 编译所需版本;patches/里的 Bun 补丁将 CJS/ESM 错误读取从 Zod 3 的errors改为两代都支持的issues。升级或移除补丁后须跑sidecar/bidi-compat.test.ts、Sidecar 编译和浏览器冒烟,不能只看 audit 通过。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

