# sici

**Repository Path**: Friedrich_Liu/sici

## Basic Information

- **Project Name**: sici
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SICI 硅基文明

> 一部可以亲手操作的修炼手册。知识不是被讲述的——是被你亲手发现的。

交互式技术科普网站：用修仙叙事包装三大硬核主题，纯静态、零依赖、可离线部署。

| 宗门 | 目录 | 主题 | 章节 |
|------|------|------|------|
| 炼器阁 ⚔ | `semi/` | 半导体：从一粒沙到一枚芯片 | 29 章 |
| 天机门 ☯ | `cs/` | 计算机：从逻辑门到操作系统 | 26 章 |
| 蕴灵宗 ❉ | `ai/` | 人工智能：从感知机到 AGI | 26 章 |

## 技术栈

**无框架、无构建管线。** 手写 HTML/CSS/JS，原生 JS + `window.SICI` 命名空间（IIFE）。
第三方库全部本地化（three.js、GSAP + ScrollTrigger、lenis、KaTeX），无 CDN 依赖。

- 设计系统：`assets/css/tokens.css`（变量 + 明暗双主题）+ `base.css`
- 共享运行时：`assets/js/`（nav / scene-engine / boss / bg3d / chapter-scaffold / chapter-boot）
- 进度持久化：`localStorage`（键 `sici.progress`，主题 `sici.theme`）
- 缓存策略：手动 `?v=` 版本号（改 JS/CSS 后需 bump）

> 注意：`content/全局设计/技术栈规范.md` 中的 Astro 5 方案**已废止**（详见该文顶部横幅），当前以上述纯静态架构为准。

## 目录结构

```
├── index.html          # 山门 · 三宗总览
├── 404.html            # 虚空裂隙页（静态托管自动兜底）
├── semi/ cs/ ai/       # 三宗栏目
│   ├── index.html      #   修炼地图（按境界分组的章节树）
│   └── chXX/           #   章节：index.html + chXX.css + chXX.js
├── assets/             # 全站共享：css / js / img / fonts / lib / data
├── content/            # 创作源稿（517 篇 md：大纲、剧本、组件规格书）——不被页面直接引用
├── tools/              # Node 工具脚本（见下）
├── archive/            # 已弃用的 Astro 5 源码，勿在其中改生产代码
└── sici-health-check/  # 独立体检报告站
```

## 本地预览

纯静态，任意 HTTP 服务器即可（章节页用相对路径，需从仓库根目录起服）：

```bash
npm run dev            # 零依赖开发服务器，http://localhost:8002（含 404 兜底）
```

## 工程工具链（npm scripts）

> 运行时零构建——`package.json` 只服务于工程工具，不参与页面产物。

```bash
npm run dev            # 开发服务器（8002）
npm run validate       # 提交前验收：15 类静态检查
npm test               # HTTP 冒烟（需先 npm run dev）
npm run seo            # 全站 SEO 注入 + sitemap/robots（幂等）
npm run images         # 图片 WebP 化 + 引用重写（需 sharp，见下）
npm run build:chapters # 章节元数据：JSON → chapters-data.js
npm run gen:chapter    # 章节生成器：模板 + JSON → 三件套骨架（见下）
npm run lint:baseline  # 重新生成 V12–V14 增量清偿基线（清偿后重跑，只降不升）
npm run lint           # ESLint（0 错误为门槛，存量警告为基线）
npm run format         # Prettier 按需格式化（**/*.html 已排除，防全量重排）
```

- **ESLint**（flat config）：抓 bug 不抓风格。浏览器脚本 `no-undef` 为 error；`no-redeclare` 等存量 var 风格问题降级 warn 作基线，触碰文件时顺手清理。
- **Prettier**：只对新文件/新改动按需使用，存量 HTML（紧凑头部）不做全量重排。
- 图片优化依赖 sharp：`cd C:\Users\admin\.workbuddy\binaries\node\workspace && npm install sharp`，运行时设 `NODE_PATH` 指向该 workspace 的 `node_modules`。

## 内容工作流

1. 创作：`content/` 下按「大纲 → 交互剧本 → 组件规格书」流程产出 md 源稿（规范见 `content/全局设计/`）
2. 生成骨架：`npm run gen:chapter -- <semi|cs|ai> <chXX> --title "标题"` 生成三件套骨架（HTML/CSS/JS 均带 `sici-gen:locked` 标记，受 V15 漂移检测守护；删标记即转纯手写）
3. 转写：人工/AI 将剧本填充进骨架（删除标记行后可自由手改）
4. 元数据：**只改 `assets/data/*-chapters.json`**（唯一事实源），再跑 `npm run build:chapters` 生成 `assets/js/chapters-data.js`（生成物，禁手改）；validate.js V11 会阻断不同步提交
5. 验收：对照 `工作流与验收标准_v2.2` 的 F1-F7 前端标准 + `npm run validate` + `npm test`

## SEO 与图片基建

- `node tools/inject-seo.js` — 全站注入 canonical / Open Graph / Twitter Card，并生成 `sitemap.xml` 与 `robots.txt`（幂等，新增章节后重跑一次）
- `node tools/optimize-images.js` — 图片优化：`assets/img/*.jpg` → WebP（1920px 收敛 + q82，幂等；`--force` 强制重转），并重写章节页 `<img>` 引用。原始 jpg 保留供 og:image 使用
  - 依赖 sharp：`cd C:\Users\admin\.workbuddy\binaries\node\workspace && npm install sharp`，运行时设 `NODE_PATH` 指向该 workspace 的 `node_modules`
- 站点域名常量在这两个脚本顶部 `SITE_URL`（当前为计划域名 `https://sici.com`）

## 提交前自动验收

已配置 Git pre-commit hook（`.husky/pre-commit`，随仓库分发），每次 `git commit` 自动执行：

1. `npx lint-staged` — 对暂存 JS 跑 ESLint --fix
2. `node tools/validate.js` — 15 项静态检查（0 error 门槛）

任一步骤失败即阻止提交。跳过验收：`git commit --no-verify`（不推荐）。

### V12–V14 基线增量清偿

CSS 卫生检查（未定义变量 / 重复选择器 / 硬编码色）以 `tools/lint-baseline.json` 记录的当前违规数为基线：

- **存量违规不阻断**——只统计为债务（当前 1369 处 / 74 文件）
- **触碰文件违规只降不升**——被 `git diff` 检出的文件，违规数超过基线即 ERROR
- 清偿存量后重跑 `npm run lint:baseline` 刷新基线（棘轮机制：基线本身只降不升）

### 远程 CI（Gitee Go）

`.workflow/quality-gate.yml`：master 分支 push / PR 自动执行 `npm install → validate → eslint`，把验收门槛从本地习俗升级为远端强制。

## 已知技术债（按优先级）

1. ~~81 个章节页模板同构重复~~（`tools/gen-chapter.js` 生成器已落地：新章走模板生成 + V15 漂移守护；存量 81 章渐进迁移——触碰时删除手写骨架部分改走生成器）
2. CSS 存量债务：V12 幽灵变量 74 处 / V13 重复选择器 47 处 / V14 硬编码色 1248 处——增量清偿中（见上）
3. 无数据埋点
4. ~~图片 45MB 未优化~~（已 WebP 化：62.5MB→23.5MB）；~~无 CI/CD~~（husky pre-commit + Gitee Go 已落地）；~~元数据双份维护~~（已单源化，V11 机检防漂移）；~~无代码规范工具链~~（ESLint/Prettier 已落地）

## 协作约定

- master 主分支；提交信息遵循 `type: 描述`（feat/fix/refactor…）
- 勿提交：`node_modules/`、`dist/`、`.trae/`（见 `.gitignore`）
- 提交前 hook 自动验收；跳过用 `--no-verify`
- 需求与产品决策见 `content/全局设计/产品需求文档_PRD_v1.0.md`