Skip to content

Commit 548757b

Browse files
fishxcodefishxcode
committed
Bootstrap fishxcode-cli with Bun+TS, i18n docs, adapters, tests and lint
0 parents  commit 548757b

63 files changed

Lines changed: 2580 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/index.json‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
{
2+
"generated_at": "2026-03-08T12:31:46Z",
3+
"project": {
4+
"name": "fishxcode-cli",
5+
"version": "0.1.0",
6+
"root": ".",
7+
"language": "TypeScript",
8+
"runtime": ["bun>=1.1.0", "node>=18"],
9+
"entry": "src/index.ts",
10+
"bin": ["fishx", "fishxcode"],
11+
"build_output": "dist/index.js"
12+
},
13+
"scan_summary": {
14+
"total_source_files": 20,
15+
"scanned_files": 20,
16+
"coverage_percent": 100,
17+
"truncated": false,
18+
"ignored_dirs": ["node_modules", "dist", ".DS_Store", "coverage", "bun.lock", "bun.lockb"]
19+
},
20+
"modules": [
21+
{
22+
"id": "src/commands",
23+
"path": "src/commands",
24+
"language": "TypeScript",
25+
"entry": "src/index.ts",
26+
"doc": "src/commands/CLAUDE.md",
27+
"files": [
28+
"src/commands/balance.ts",
29+
"src/commands/doctor.ts",
30+
"src/commands/login.ts",
31+
"src/commands/reset.ts",
32+
"src/commands/setup.ts",
33+
"src/commands/tools.ts"
34+
],
35+
"commands": ["login", "logout", "whoami", "setup", "doctor", "tools", "reset", "balance"],
36+
"coverage": {
37+
"has_entry": true,
38+
"has_interface_doc": true,
39+
"has_tests": false,
40+
"has_data_model": false
41+
},
42+
"gaps": ["缺命令层单元测试", "balance 命令为占位未实现"]
43+
},
44+
{
45+
"id": "src/lib",
46+
"path": "src/lib",
47+
"language": "TypeScript",
48+
"entry": "src/lib/config.ts",
49+
"doc": "src/lib/CLAUDE.md",
50+
"files": [
51+
"src/lib/config.ts",
52+
"src/lib/constants.ts",
53+
"src/lib/prompt.ts",
54+
"src/lib/tools.ts"
55+
],
56+
"exports": {
57+
"constants": ["APP_NAME", "API_BASE", "API_BASE_OPENAI", "CONFIG_DIRNAME"],
58+
"config": ["loadConfig", "saveConfig", "clearConfig", "getApiKey", "maskKey", "AppConfig"],
59+
"prompt": ["ask"],
60+
"tools": ["SUPPORTED_TOOLS", "getImplementedAdapter", "ToolInfo"]
61+
},
62+
"coverage": {
63+
"has_entry": true,
64+
"has_interface_doc": true,
65+
"has_tests": true,
66+
"has_data_model": true
67+
},
68+
"gaps": ["loadConfig/saveConfig/clearConfig/getApiKey 无测试", "ask() 无测试"]
69+
},
70+
{
71+
"id": "src/tools",
72+
"path": "src/tools",
73+
"language": "TypeScript",
74+
"entry": "src/tools/index.ts",
75+
"doc": "src/tools/CLAUDE.md",
76+
"files": [
77+
"src/tools/types.ts",
78+
"src/tools/utils.ts",
79+
"src/tools/index.ts",
80+
"src/tools/claude-code.ts",
81+
"src/tools/codex.ts",
82+
"src/tools/aider.ts",
83+
"src/tools/continue.ts",
84+
"src/tools/opencode.ts",
85+
"src/tools/openclaw.ts"
86+
],
87+
"adapters": [
88+
{
89+
"id": "claude-code",
90+
"config_file": "~/.claude/settings.json",
91+
"hot": true
92+
},
93+
{
94+
"id": "codex",
95+
"config_file": "~/.codex/config.toml",
96+
"hot": false
97+
},
98+
{
99+
"id": "aider",
100+
"config_file": "~/.aider.conf.yml",
101+
"hot": false
102+
},
103+
{
104+
"id": "continue",
105+
"config_file": "~/.continue/config.yaml or config.json",
106+
"hot": true
107+
},
108+
{
109+
"id": "opencode",
110+
"config_file": "~/.config/opencode/opencode.json (multi-candidate)",
111+
"hot": false
112+
},
113+
{
114+
"id": "openclaw",
115+
"config_file": "~/.openclaw/openclaw.json",
116+
"hot": false
117+
}
118+
],
119+
"coverage": {
120+
"has_entry": true,
121+
"has_interface_doc": true,
122+
"has_tests": true,
123+
"has_data_model": true
124+
},
125+
"gaps": ["configure/reset/checkInstalled/isConfigured 均无测试", "cursor 适配器未实现"]
126+
},
127+
{
128+
"id": "test",
129+
"path": "test",
130+
"language": "TypeScript",
131+
"doc": "test/CLAUDE.md",
132+
"files": ["test/config.test.ts", "test/utils.test.ts"],
133+
"test_suites": 2,
134+
"test_cases": 3,
135+
"coverage": {
136+
"has_entry": true,
137+
"has_interface_doc": true,
138+
"has_tests": true,
139+
"has_data_model": false
140+
},
141+
"gaps": ["命令层、适配器层无测试覆盖"]
142+
}
143+
],
144+
"ci": {
145+
"ci_workflow": ".github/workflows/ci.yml",
146+
"release_workflow": ".github/workflows/release.yml",
147+
"ci_steps": ["typecheck", "bun test", "bun build"],
148+
"release_trigger": ["push tags v*", "workflow_dispatch"],
149+
"publish_registry": "https://registry.npmjs.org"
150+
},
151+
"gaps_summary": [
152+
"命令层（src/commands/）无单元测试",
153+
"适配器层 configure/reset 无集成测试",
154+
"balance 命令未接入服务端 API",
155+
"cursor 工具适配器未实现",
156+
"无 ESLint/Biome 等 Lint 配置"
157+
],
158+
"next_scan_priority": [
159+
"test/（补充适配器集成测试后重新扫描）",
160+
"src/commands/balance.ts（功能实现后更新文档）"
161+
]
162+
}

‎.github/workflows/ci.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
validate:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v4
14+
15+
- name: Setup Bun
16+
uses: oven-sh/setup-bun@v2
17+
with:
18+
bun-version: latest
19+
20+
- name: Install dependencies
21+
run: bun install
22+
23+
- name: Type check
24+
run: bun run typecheck
25+
26+
- name: Unit tests
27+
run: bun test
28+
29+
- name: Build
30+
run: bun run build

‎.github/workflows/release.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Release
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
tags:
7+
- "v*"
8+
9+
jobs:
10+
publish:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: read
14+
id-token: write
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v4
18+
19+
- name: Setup Bun
20+
uses: oven-sh/setup-bun@v2
21+
with:
22+
bun-version: latest
23+
24+
- name: Setup Node
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: 22
28+
registry-url: https://registry.npmjs.org
29+
30+
- name: Install dependencies
31+
run: bun install
32+
33+
- name: Verify
34+
run: bun run check
35+
36+
- name: Publish npm package
37+
run: npm publish --access public --provenance
38+
env:
39+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules
2+
bun.lock
3+
bun.lockb
4+
dist
5+
.DS_Store
6+
coverage

‎CLAUDE.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# FishXCode CLI — 根级 AI 上下文
2+
3+
## 项目愿景
4+
5+
FishXCode CLI（命令行工具名：`fishx` / `fishxcode`）是一个帮助开发者一键将 AI 编码工具接入 FishXCode API 代理服务的命令行工具。通过统一的适配器机制，用户无需手动修改各工具配置文件，即可完成 claude-code、aider、codex、continue.dev、opencode、openclaw 等主流 AI 编码工具的 API 来源切换。
6+
7+
- 官网：https://fishxcode.com
8+
- 仓库：https://github.com/fishxcode/fishxcode-cli
9+
- 版本：0.1.0
10+
- 许可：MIT
11+
12+
---
13+
14+
## 架构总览
15+
16+
- **运行时**：Bun >= 1.1.0，Node.js >= 18（兼容）
17+
- **语言**：TypeScript（ES2022，模块系统：NodeNext）
18+
- **打包**：`bun build` 单文件输出到 `dist/index.js`，注册为全局二进制 `fishx` / `fishxcode`
19+
- **依赖**：`commander`（CLI 框架）、`picocolors`（终端色彩），无其他运行时依赖
20+
- **配置存储**：用户主目录下的 `~/.fishxcode/config.json`
21+
- **适配器模式**：每个 AI 工具对应一个 `ToolAdapter` 实现，统一接口为 `checkInstalled / isConfigured / configure / reset`
22+
23+
```text
24+
用户输入 fishx <command>
25+
└─> src/index.ts (Commander 注册入口)
26+
├─> src/commands/ (6 个命令处理器)
27+
│ ├─> src/lib/ (config、constants、prompt、tools 共享库)
28+
│ └─> src/tools/ (6 个工具适配器 + 类型 + 工具函数)
29+
└─> 写入各工具在用户 HOME 下的配置文件
30+
```
31+
32+
---
33+
34+
## 模块结构图
35+
36+
```mermaid
37+
graph TD
38+
A["(根) fishxcode/cli"] --> B["src/"]
39+
B --> C["src/commands/"]
40+
B --> D["src/lib/"]
41+
B --> E["src/tools/"]
42+
A --> F["test/"]
43+
A --> G[".github/workflows/"]
44+
45+
click C "./src/commands/CLAUDE.md" "查看 commands 模块文档"
46+
click D "./src/lib/CLAUDE.md" "查看 lib 模块文档"
47+
click E "./src/tools/CLAUDE.md" "查看 tools 模块文档"
48+
click F "./test/CLAUDE.md" "查看 test 模块文档"
49+
```
50+
51+
---
52+
53+
## 模块索引
54+
55+
| 模块路径 | 职责简述 |
56+
| --- | --- |
57+
| [src/commands/](./src/commands/CLAUDE.md) | CLI 命令实现：login/logout/whoami/setup/doctor/tools/reset/balance |
58+
| [src/lib/](./src/lib/CLAUDE.md) | 共享库：配置读写、常量定义、交互式提示、工具信息列表 |
59+
| [src/tools/](./src/tools/CLAUDE.md) | 6 个 AI 工具适配器 + ToolAdapter 类型定义 + 工具函数 |
60+
| [test/](./test/CLAUDE.md) | 单元测试：config.maskKey、tools.parseJsonc |
61+
62+
---
63+
64+
## 运行与开发
65+
66+
```bash
67+
# 安装依赖
68+
bun install
69+
70+
# 本地开发运行（无需构建）
71+
bun run dev # 等价于 bun run src/index.ts
72+
73+
# 类型检查
74+
bun run typecheck
75+
76+
# 单元测试
77+
bun test
78+
79+
# 构建生产包
80+
bun run build # 输出到 dist/index.js
81+
82+
# 发布前全量检查（typecheck + test + build）
83+
bun run check
84+
85+
# 全局安装后使用
86+
fishx login
87+
fishx setup
88+
fishx doctor
89+
fishx tools
90+
fishx balance
91+
fishx reset
92+
fishx logout
93+
fishx whoami
94+
```
95+
96+
### 环境变量
97+
98+
| 变量名 | 说明 |
99+
| --- | --- |
100+
| `FISHXCODE_API_KEY` | 可替代 login 持久化配置的 API Key |
101+
102+
---
103+
104+
## 测试策略
105+
106+
- 测试框架：**Bun 内置 test**（`bun:test`），无外部测试库
107+
- 测试文件位于 `test/` 目录，文件名后缀 `*.test.ts`
108+
- 当前测试覆盖：
109+
- `test/config.test.ts`：`maskKey` 函数（短 key / 正常 key）
110+
- `test/utils.test.ts`：`parseJsonc` 函数（行注释、块注释）
111+
- 运行：`bun test`
112+
- CI 中自动执行（见 `.github/workflows/ci.yml`）
113+
114+
**缺口**：命令层、适配器层暂无测试覆盖，`configure` / `reset` 等核心流程依赖文件系统，建议后续补充集成测试。
115+
116+
---
117+
118+
## 编码规范
119+
120+
- 严格 TypeScript（`"strict": true`），`noEmit` 模式下通过 `tsc` 类型检查
121+
- 模块系统：ESM（`"type": "module"`），导入时显式加 `.js` 后缀
122+
- 无 Lint 工具配置（ESLint/Biome），依赖 TypeScript 严格模式兜底
123+
- 每个工具适配器独立一个文件，统一实现 `ToolAdapter` 接口
124+
- 配置块用标记注释（如 `# fishxcode-cli managed`）隔离，支持幂等写入与清理
125+
126+
---
127+
128+
## AI 使用指引
129+
130+
- **入口文件**：`src/index.ts`（Commander 注册所有命令）
131+
- **新增命令**：在 `src/commands/` 添加文件，在 `src/index.ts` 注册
132+
- **新增工具适配器**：实现 `ToolAdapter` 接口（见 `src/tools/types.ts`），在 `src/tools/index.ts` 注册，在 `src/lib/tools.ts` 的 `SUPPORTED_TOOLS` 中添加条目
133+
- **配置路径约定**：适配器写入 `~/<tool_config_dir>/`，不写入项目目录
134+
- **幂等性**：`configure` 须保证重复执行结果一致，`reset` 须仅清除本工具写入的字段
135+
- **不要修改**：`dist/` 目录（构建产物，gitignore 已忽略）
136+
137+
---
138+
139+
## 变更记录 (Changelog)
140+
141+
| 时间 | 类型 | 内容 |
142+
| --- | --- | --- |
143+
| 2026-03-08 12:31:46 | 初始化 | 首次生成 AI 上下文文档（根级 + 4 个模块级 CLAUDE.md，.claude/index.json） |

0 commit comments

Comments
 (0)