Skip to content

Commit 716f665

Browse files
fishxcodefishxcode
committed
docs: fix markdownlint MD040/MD060 warnings in all CLAUDE.md files
- replace |---|---| separators with | --- | --- | in all 6 CLAUDE.md files - add language specifier to unlabeled fenced code blocks (```text)
1 parent 67360bb commit 716f665

17 files changed

Lines changed: 1865 additions & 371 deletions

File tree

‎.claude/index.json‎

Lines changed: 91 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"generated_at": "2026-03-08T12:31:46Z",
2+
"generated_at": "2026-03-08T13:16:14Z",
33
"project": {
44
"name": "fishxcode-cli",
55
"version": "0.1.0",
@@ -11,11 +11,20 @@
1111
"build_output": "dist/index.js"
1212
},
1313
"scan_summary": {
14-
"total_source_files": 20,
15-
"scanned_files": 20,
14+
"total_source_files": 47,
15+
"scanned_files": 47,
1616
"coverage_percent": 100,
1717
"truncated": false,
18-
"ignored_dirs": ["node_modules", "dist", ".DS_Store", "coverage", "bun.lock", "bun.lockb"]
18+
"ignored_dirs": [
19+
"node_modules",
20+
"dist",
21+
".DS_Store",
22+
"coverage",
23+
"bun.lock",
24+
"bun.lockb",
25+
"docs/.vitepress/dist",
26+
"docs/.vitepress/cache"
27+
]
1928
},
2029
"modules": [
2130
{
@@ -139,6 +148,65 @@
139148
"has_data_model": false
140149
},
141150
"gaps": ["命令层、适配器层无测试覆盖"]
151+
},
152+
{
153+
"id": "docs",
154+
"path": "docs",
155+
"language": "TypeScript + Markdown + Vue",
156+
"doc": "docs/CLAUDE.md",
157+
"files": [
158+
"docs/.vitepress/config.mts",
159+
"docs/.vitepress/theme/index.ts",
160+
"docs/.vitepress/theme/NotFound.vue",
161+
"docs/.vitepress/theme/components/BackToTop.vue",
162+
"docs/.vitepress/theme/style.css",
163+
"docs/.vitepress/theme/dark-mode.css",
164+
"docs/public/logo.svg",
165+
"docs/zh-CN/index.md",
166+
"docs/zh-CN/quick-start.md",
167+
"docs/zh-CN/commands.md",
168+
"docs/zh-CN/tools.md",
169+
"docs/zh-CN/release.md",
170+
"docs/en/index.md",
171+
"docs/en/quick-start.md",
172+
"docs/en/commands.md",
173+
"docs/en/tools.md",
174+
"docs/en/release.md",
175+
"docs/fr/index.md",
176+
"docs/fr/quick-start.md",
177+
"docs/fr/commands.md",
178+
"docs/fr/tools.md",
179+
"docs/fr/release.md",
180+
"docs/es/index.md",
181+
"docs/es/quick-start.md",
182+
"docs/es/commands.md",
183+
"docs/es/tools.md",
184+
"docs/es/release.md",
185+
"docs/pt/index.md",
186+
"docs/pt/quick-start.md",
187+
"docs/pt/commands.md",
188+
"docs/pt/tools.md",
189+
"docs/pt/release.md"
190+
],
191+
"site": "https://cli.fishxcode.com",
192+
"engine": "vitepress@^1.6.4",
193+
"source_dir": "docs/",
194+
"output_dir": "docs/.vitepress/dist",
195+
"deploy": "vercel",
196+
"locales": ["zh-CN (root)", "en", "fr", "es", "pt"],
197+
"rewrites": { "zh-CN/:path": ":path" },
198+
"theme": "custom (warm gold + rose-pink, dark mode)",
199+
"plugins": ["@vite-pwa/vitepress", "vitepress-plugin-group-icons", "medium-zoom"],
200+
"scripts": ["docs:dev", "docs:build", "docs:preview"],
201+
"config": "docs/.vitepress/config.mts",
202+
"theme_dir": "docs/.vitepress/theme/",
203+
"coverage": {
204+
"has_entry": true,
205+
"has_interface_doc": true,
206+
"has_tests": false,
207+
"has_data_model": false
208+
},
209+
"gaps": ["文档内容页面无自动化测试（链接检查、内容校验）"]
142210
}
143211
],
144212
"ci": {
@@ -148,29 +216,32 @@
148216
"release_trigger": ["push tags v*", "workflow_dispatch"],
149217
"publish_registry": "https://registry.npmjs.org"
150218
},
151-
"docs": {
152-
"site": "https://cli.fishxcode.com",
153-
"engine": "vitepress@^1.6.4",
154-
"source_dir": "docs/",
155-
"output_dir": "docs/.vitepress/dist",
156-
"deploy": "vercel",
157-
"locales": ["zh-CN (root)", "en", "fr", "es", "pt"],
158-
"rewrites": { "zh-CN/:path": ":path" },
159-
"theme": "custom (warm gold + rose-pink, dark mode)",
160-
"plugins": ["@vite-pwa/vitepress", "vitepress-plugin-group-icons", "medium-zoom"],
161-
"scripts": ["docs:dev", "docs:build", "docs:preview"],
162-
"config": "docs/.vitepress/config.mts",
163-
"theme_dir": "docs/.vitepress/theme/"
219+
"tooling": {
220+
"lint": "biome (@biomejs/biome ^1.9.4)",
221+
"format": "biome",
222+
"lint_command": "bun run lint",
223+
"format_command": "bun run format"
164224
},
165225
"gaps_summary": [
166226
"命令层（src/commands/）无单元测试",
167227
"适配器层 configure/reset 无集成测试",
168228
"balance 命令未接入服务端 API",
169-
"cursor 工具适配器未实现"
229+
"cursor 工具适配器未实现",
230+
"docs 文档内容无链接/内容自动化校验"
170231
],
171232
"next_scan_priority": [
172233
"test/（补充适配器集成测试后重新扫描）",
173234
"src/commands/balance.ts（balance 功能实现后更新文档）",
174-
"docs/（VitePress 文档内容扩充后重新扫描）"
175-
]
235+
"docs/（各语言内容扩充后重新扫描）"
236+
],
237+
"incremental_update": {
238+
"previous_scan": "2026-03-08T12:31:46Z",
239+
"this_scan": "2026-03-08T13:16:14Z",
240+
"changes": [
241+
"新增 docs/ 模块（VitePress 文档站，5 语言）",
242+
"新建 docs/CLAUDE.md",
243+
"更新根级 CLAUDE.md：加入 docs/ 模块索引、Mermaid 图、docs:* 命令、VITEPRESS_BASE 环境变量、修正 Biome lint/format 信息",
244+
"更新 .claude/index.json：加入 docs 模块、tooling 字段、修正总文件数"
245+
]
246+
}
176247
}

‎.github/workflows/deploy.yml‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
name: Deploy
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
packages: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
# ──────────────────────────────────────────────────────────────────────────
20+
# 1. 构建 VitePress → GitHub Pages
21+
#
22+
# VITEPRESS_BASE 优先级：
23+
# 1. repo 变量 vars.VITEPRESS_BASE（Settings > Variables > Actions）
24+
# 2. 兜底自动使用 /<仓库名>/ (e.g. /fishxcode/)
25+
#
26+
# 如果已绑定自定义域名 doc.fishxcode.com，在 repo Variables 设置：
27+
# VITEPRESS_BASE = /
28+
# ──────────────────────────────────────────────────────────────────────────
29+
build-pages:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v4
33+
with:
34+
fetch-depth: 0
35+
36+
- uses: pnpm/action-setup@v4
37+
with:
38+
version: 9
39+
40+
- uses: actions/setup-node@v4
41+
with:
42+
node-version: 22
43+
cache: pnpm
44+
45+
- uses: actions/cache@v4
46+
with:
47+
path: .vitepress/cache
48+
key: vitepress-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('**/*.md', '.vitepress/config.mts') }}
49+
restore-keys: |
50+
vitepress-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
51+
vitepress-${{ runner.os }}-
52+
53+
- run: pnpm install --frozen-lockfile
54+
55+
- name: Build (GitHub Pages)
56+
run: pnpm build
57+
env:
58+
VITEPRESS_BASE: ${{ vars.VITEPRESS_BASE || format('/{0}/', github.event.repository.name) }}
59+
60+
- uses: actions/upload-pages-artifact@v3
61+
with:
62+
path: .vitepress/dist
63+
64+
# ──────────────────────────────────────────────────────────────────────────
65+
# 2. 部署到 GitHub Pages
66+
# ──────────────────────────────────────────────────────────────────────────
67+
deploy-pages:
68+
needs: build-pages
69+
runs-on: ubuntu-latest
70+
environment:
71+
name: github-pages
72+
url: ${{ steps.deployment.outputs.page_url }}
73+
steps:
74+
- id: deployment
75+
uses: actions/deploy-pages@v4
76+
77+
# ──────────────────────────────────────────────────────────────────────────
78+
# 3. 构建并推送 Docker 镜像
79+
#
80+
# Docker 始终以 VITEPRESS_BASE=/ 构建，因为 nginx 从根路径服务。
81+
# 借助 pnpm + VitePress + Docker 层三重缓存，二次构建极快。
82+
# ──────────────────────────────────────────────────────────────────────────
83+
docker:
84+
runs-on: ubuntu-latest
85+
env:
86+
REGISTRY: ghcr.io
87+
IMAGE_NAME: ${{ github.repository }}
88+
steps:
89+
- uses: actions/checkout@v4
90+
with:
91+
fetch-depth: 0
92+
93+
- uses: pnpm/action-setup@v4
94+
with:
95+
version: 9
96+
97+
- uses: actions/setup-node@v4
98+
with:
99+
node-version: 22
100+
cache: pnpm
101+
102+
# 复用与 build-pages 相同的 VitePress 缓存 key
103+
- uses: actions/cache@v4
104+
with:
105+
path: .vitepress/cache
106+
key: vitepress-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('**/*.md', '.vitepress/config.mts') }}
107+
restore-keys: |
108+
vitepress-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
109+
vitepress-${{ runner.os }}-
110+
111+
- run: pnpm install --frozen-lockfile
112+
113+
- name: Build (Docker, base=/)
114+
run: pnpm build
115+
env:
116+
VITEPRESS_BASE: /
117+
118+
- uses: docker/setup-buildx-action@v3
119+
120+
- uses: docker/login-action@v3
121+
with:
122+
registry: ${{ env.REGISTRY }}
123+
username: ${{ github.actor }}
124+
password: ${{ secrets.GITHUB_TOKEN }}
125+
126+
- uses: docker/metadata-action@v5
127+
id: meta
128+
with:
129+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
130+
tags: |
131+
type=raw,value=latest
132+
type=sha,prefix=sha-,format=short
133+
134+
- uses: docker/build-push-action@v6
135+
with:
136+
context: .
137+
file: ./Dockerfile
138+
push: true
139+
tags: ${{ steps.meta.outputs.tags }}
140+
labels: ${{ steps.meta.outputs.labels }}
141+
platforms: linux/amd64,linux/arm64
142+
cache-from: type=gha
143+
cache-to: type=gha,mode=max

‎CLAUDE.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,15 @@ graph TD
4141
B --> E["src/tools/"]
4242
A --> F["test/"]
4343
A --> G[".github/workflows/"]
44+
A --> H["docs/"]
45+
H --> I["docs/.vitepress/"]
46+
H --> J["docs/zh-CN/ | en/ | fr/ | es/ | pt/"]
4447
4548
click C "./src/commands/CLAUDE.md" "查看 commands 模块文档"
4649
click D "./src/lib/CLAUDE.md" "查看 lib 模块文档"
4750
click E "./src/tools/CLAUDE.md" "查看 tools 模块文档"
4851
click F "./test/CLAUDE.md" "查看 test 模块文档"
52+
click H "./docs/CLAUDE.md" "查看 docs 模块文档"
4953
```
5054

5155
---
@@ -58,6 +62,7 @@ graph TD
5862
| [src/lib/](./src/lib/CLAUDE.md) | 共享库：配置读写、常量定义、交互式提示、工具信息列表 |
5963
| [src/tools/](./src/tools/CLAUDE.md) | 6 个 AI 工具适配器 + ToolAdapter 类型定义 + 工具函数 |
6064
| [test/](./test/CLAUDE.md) | 单元测试：config.maskKey、tools.parseJsonc |
65+
| [docs/](./docs/CLAUDE.md) | VitePress 文档站：5 语言内容 + 自定义主题，部署到 cli.fishxcode.com |
6166

6267
---
6368

@@ -82,6 +87,11 @@ bun run build # 输出到 dist/index.js
8287
# 发布前全量检查（typecheck + test + build）
8388
bun run check
8489

90+
# 文档站开发
91+
bun run docs:dev # 本地热更新预览
92+
bun run docs:build # 构建文档站（输出到 docs/.vitepress/dist/）
93+
bun run docs:preview # 预览构建结果
94+
8595
# 全局安装后使用
8696
fishx login
8797
fishx setup
@@ -98,6 +108,7 @@ fishx whoami
98108
| 变量名 | 说明 |
99109
| --- | --- |
100110
| `FISHXCODE_API_KEY` | 可替代 login 持久化配置的 API Key |
111+
| `VITEPRESS_BASE` | 文档站部署 base 路径（默认 `/`，Vercel 部署无需设置） |
101112

102113
---
103114

@@ -119,7 +130,7 @@ fishx whoami
119130

120131
- 严格 TypeScript（`"strict": true`），`noEmit` 模式下通过 `tsc` 类型检查
121132
- 模块系统：ESM（`"type": "module"`），导入时显式加 `.js` 后缀
122-
- 无 Lint 工具配置（ESLint/Biome），依赖 TypeScript 严格模式兜底
133+
- 代码格式化与 Lint 工具：**Biome**（`@biomejs/biome ^1.9.4`），运行 `bun run lint` 检查，`bun run format` 自动格式化
123134
- 每个工具适配器独立一个文件，统一实现 `ToolAdapter` 接口
124135
- 配置块用标记注释（如 `# fishxcode-cli managed`）隔离，支持幂等写入与清理
125136

@@ -132,12 +143,14 @@ fishx whoami
132143
- **新增工具适配器**：实现 `ToolAdapter` 接口（见 `src/tools/types.ts`），在 `src/tools/index.ts` 注册，在 `src/lib/tools.ts` 的 `SUPPORTED_TOOLS` 中添加条目
133144
- **配置路径约定**：适配器写入 `~/<tool_config_dir>/`，不写入项目目录
134145
- **幂等性**：`configure` 须保证重复执行结果一致，`reset` 须仅清除本工具写入的字段
135-
- **不要修改**：`dist/` 目录（构建产物，gitignore 已忽略）
146+
- **新增文档页面**：在对应语言目录（如 `docs/zh-CN/`）添加 Markdown 文件，并在 `docs/.vitepress/config.mts` 对应 locale 的 `sidebar` 中注册
147+
- **不要修改**：`dist/` 目录（构建产物，gitignore 已忽略）、`docs/.vitepress/dist/`（文档站构建产物）、`docs/.vitepress/cache/`（构建缓存）
136148

137149
---
138150

139151
## 变更记录 (Changelog)
140152

141153
| 时间 | 类型 | 内容 |
142154
| --- | --- | --- |
155+
| 2026-03-08 13:16:14 | 增量更新 | 新增 docs/ 模块入口（VitePress 文档站），更新 Mermaid 结构图与模块索引；修正编码规范（补充 Biome lint/format 信息）；补充 docs:dev/build/preview 命令和 VITEPRESS_BASE 环境变量 |
143156
| 2026-03-08 12:31:46 | 初始化 | 首次生成 AI 上下文文档（根级 + 4 个模块级 CLAUDE.md，.claude/index.json） |

‎biome.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,13 @@
2222
"indentWidth": 2
2323
},
2424
"files": {
25-
"ignore": ["dist", "node_modules"]
25+
"ignore": [
26+
"dist",
27+
"node_modules",
28+
"docs/.vitepress",
29+
"docs/.vitepress/**",
30+
"docs/.vitepress/cache/**",
31+
"docs/.vitepress/dist/**"
32+
]
2633
}
2734
}

0 commit comments

Comments
 (0)