zdh
12740c13b1
Deploy Wiki to Production / deploy (push) Has been cancelled
- 新增 KANBAN.md 项目看板（待办/进行中/已完成/问题/定期维护） - 新增 specs/ 需求规格目录 - 新增 sessions/ AI 编码会话沉淀目录 - 新增 prompts/ 已验证 Prompt 模板目录 - 更新 CLAUDE.md 增加项目管理工作流章节
226 lines
13 KiB
Markdown
226 lines
13 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概览
|
||
|
||
"一人公司开发团队知识库" — 独立开发者的技术沉淀与参考资源站。
|
||
|
||
所有文档以单页 HTML 形式发布，通过根目录 `index.html` 作为导航入口统一展示。
|
||
|
||
## 版本控制
|
||
|
||
代码托管在 **Gitea 私服**（非 GitHub），`.gitea/workflows/deploy.yml` 在 push 到 `main` 分支时自动 rsync 到 `/data/wiki/` 并 reload nginx。
|
||
|
||
`招标投标AI推广应用政策解读/` 子目录有独立的 `.git/`。手动部署也可通过 `/remote-sync` 调用 rsync 到 `39.100.114.100:/data`。
|
||
|
||
`.gitignore` 排除了 `.superpowers/`、`qModel/.git/`、嵌套子目录的独立 `.git/`、`**/logs/`、`.claude/skills/ui-ux-pro-max/`。
|
||
|
||
### 部署排除
|
||
|
||
`.gitea/workflows/deploy.yml` 在 rsync 到生产环境时排除以下内容：
|
||
- `.claude/`、`.gitea/`、`.gitignore`、`CLAUDE.md` — 开发工具与配置
|
||
- `*.pptx`、`*.xlsx` — 源材料/二进制文件
|
||
- `.git/` — 版本控制元数据
|
||
|
||
> ⚠️ **安全提醒**：`.claude/skills/remote-sync/SKILL.md` 包含硬编码 SSH 凭证，该文件不会被部署到生产环境，但存在于 git 仓库中。如需公开此仓库，应先清理凭证。
|
||
|
||
## 目录约定
|
||
|
||
每个子目录遵循 `{主题}/{类型}/` 的层级结构，类型包括 `报告/`、`代码/`、`笔记/` 等。新增主题目录时保持此约定。
|
||
|
||
**例外情况**：
|
||
- `AI核心技能原理说明.html`、`crmeb-mer-graph-report.html`、`szihl-soe-reform-report.html`、`张德海_简历.html` — 根目录的单文件报告/简历，不走子目录结构
|
||
- `mcp-services-guide/`、`深国际综合改革方案/` — 有独立 `index.html` 的自成一体子站，不遵循 `报告/` 子目录模式
|
||
- `交互式演示/` — 存放交互式前端 demo（如正四面体 3D 动画），非报告页
|
||
- `中医馆内部管理系统/报告/` 下有 `.md` 需求文档，是唯一在 `报告/` 目录下出现非 HTML 文件的情况（其他 `.md` 文件如 `研发型企业AI转型方案/section-*.md`、`政府审批流解决方案/*.md`、`YqBoot系统说明书/*.md` 位于主题根目录，属规划/源文件，不走报告页模板）
|
||
- `研发型企业AI转型方案/` — `.md` 分段规划文件 + `.pptx`/`.xlsx` 源材料位于主题根目录，HTML 报告在 `报告/` 子目录
|
||
- `政府审批流解决方案/` — `.md` 与 `.html` 并存于主题根目录（非 `报告/` 下）
|
||
- `YqBoot系统说明书/` — `.md` 与 `.html` 并存于主题根目录，另有 `screenshots/` 子目录
|
||
|
||
## 构建与开发
|
||
|
||
本项目是**纯静态 HTML/CSS/JS 文档站**，无构建步骤、无依赖管理、无测试框架。
|
||
|
||
- **查看页面**：直接在浏览器中打开 `index.html` 或任意 HTML 文件
|
||
- **新增文档**：创建 HTML 文件 → 更新 `index.html` 的 `wikiData` 数组（见下文）
|
||
- **部署到远端**：调用 `/remote-sync` 将指定目录增量同步到服务器
|
||
- **更新图谱**：修改代码后运行 `graphify-rs build --path . --output graphify-out --no-llm --update`
|
||
|
||
## 索引页（index.html）
|
||
|
||
`index.html` 是纯 HTML/CSS/JS 单文件 SPA，包含侧栏导航、搜索、暗色模式切换、移动端抽屉菜单。
|
||
|
||
### wikiData 数据结构
|
||
|
||
文档条目通过 `wikiData` 数组管理（在 `<script>` 标签内），按分类分组，每个分类是一个对象：
|
||
|
||
```js
|
||
{ dir: "分类名称", icon: "🔐", desc: "分类描述", color: "pink",
|
||
items: [
|
||
{ path: "相对路径/文件.html", title: "文档标题", desc: "文档描述", date: "2026-05-08" }
|
||
]}
|
||
```
|
||
|
||
**新增文档**：在对应分类的 `items` 数组中添加条目。如果分类不存在，新建一个分类对象。
|
||
|
||
**颜色映射**（`wikiData` 中 `color` 字段的语义约定，颜色值直接写在各分类条目中）：
|
||
- `pink` — 深度分析、政策解读、政务行业、企业AI转型
|
||
- `blue` — 工程指南、数据平台、医疗健康
|
||
- `mint` — 调研研究、商业分析、配送到家
|
||
- `lavender` — 参考资源、AI 工具、关于作者
|
||
- `orange` — 抖音话题、短视频脚本
|
||
|
||
新增分类时选择语义匹配的颜色，颜色样式通过 `card-badge` 类渲染。
|
||
|
||
### 页面特性
|
||
|
||
- 侧栏导航（桌面端）+ 抽屉导航（移动端 ≤768px）
|
||
- 实时搜索（按标题、描述、分类名匹配）
|
||
- 暗色/亮色模式切换（优先级：localStorage 键 `wiki-theme` → `prefers-color-scheme: dark` 系统偏好 → light 默认）
|
||
- 响应式布局：≤768px 隐藏侧栏，显示移动端 chip 筛选栏
|
||
|
||
### JS 运行时架构
|
||
|
||
`<script>` 块中的数据流与状态管理：
|
||
|
||
```
|
||
wikiData (声明式) → allItems (展开数组, 附加 section/icon) → 视图渲染
|
||
```
|
||
|
||
| 变量/函数 | 作用 |
|
||
|-----------|------|
|
||
| `wikiData` | 源数据：按分类分组的文档条目数组 |
|
||
| `allItems` | `wikiData` 展开后的扁平数组，每个条目附加 `section`（分类名）和 `icon` 属性 |
|
||
| `currentView` | 当前视图状态：`'all'` 或某个分类的 `dir` 值 |
|
||
| `searchQuery` | 搜索框绑定值，实时过滤 |
|
||
| `render()` | 分发函数：`currentView === 'all'` 时调用 `renderAllView(main)`，否则 `renderSectionView(main)` |
|
||
| `buildNav(targetEl)` | 构建侧栏/抽屉导航 HTML，绑定点击事件切换视图 |
|
||
| `buildChips()` | 构建移动端 chip 横向滚动筛选栏（分类 pill 按钮），点击切换 `currentView` |
|
||
| `setTheme(t)` | 主题切换：`document.documentElement.setAttribute('data-theme', t)` + `localStorage.setItem('wiki-theme', t)`。初始化优先级见「页面特性」 |
|
||
|
||
## 报告页模板
|
||
|
||
所有报告页（`{主题}/报告/*.html`）遵循统一的 HTML 模板结构：
|
||
1. `:root` 块复制 CSS 设计 Token（含品牌色、功能色、中性色、圆角、阴影等变量）
|
||
2. 固定 header-bar（sticky top，品牌标题渐变 `linear-gradient(135deg, #0078D4 0%, #2B88D8 100%)`）
|
||
3. 单列容器布局，`max-width: 1200px` 居中
|
||
4. Markdown 内容通过内联 HTML 渲染（表格、代码块、列表）
|
||
5. 语言属性 `lang="zh-CN"`
|
||
|
||
创建新报告页时，复制任意现有报告页的 `:root` 和 header 结构作为模板。**推荐使用物流网系列报告页**（如 `市属国企参与物流网建设调研报告/报告/`）作为模板，它们有最完整的侧栏目录实现。
|
||
|
||
> **关键模式**：报告页是独立打开的 HTML 文件（非 iframe 嵌入），每个页面必须在自己的 `<style>` 标签内定义完整的 `:root` CSS 变量块。不从 `index.html` 继承样式，变量块不可省略。
|
||
|
||
**报告页有两种变体**：
|
||
1. **基础版**（大多数报告）：固定 header-bar + 单列内容区，结构最简单
|
||
2. **侧栏导航版**（物流网系列报告）：左侧 260px 粘性导航菜单 + 右侧内容区，适合多章节长报告。标题带 `[章节名]` 便于搜索跳转
|
||
|
||
**🔴 每页必有**：`← 返回知识库` 链接 — 所有页面（含报告页、特殊布局页、简历页）顶部必须有此导航链接。路径规则：根级文件 `./index.html`，一级子目录 `../index.html`，二级子目录 `../../index.html`。
|
||
|
||
移动端（≤768px）侧栏导航版自动隐藏菜单，显示汉堡按钮触发抽屉导航。
|
||
|
||
**手机适配版**：部分报告有 `_mobile.html` 后缀的独立手机版（卡片式折叠布局 + 底部标签导航），如 `中医馆内部管理系统_需求分析对比报告_mobile.html`。
|
||
|
||
### 页面分类与样式差异
|
||
|
||
并非所有报告页都使用 Fluent 2 标准 Token。部分页面使用独立的色彩体系（详见 `.claude/design-tokens.md` §15.2）：
|
||
|
||
| 类别 | 特征 | 布局要求 | 涉及文件 |
|
||
|------|------|---------|---------|
|
||
| **标准报告页** | 使用 `var(--color-primary)` 等 Token | 顶栏 + 侧栏目录 + 主内容 | ~33 个 |
|
||
| **自定义样式页** | 独立色板（如 `--primary: #1a3a5c`） | 至少顶栏 + 返回链接 | ~7 个 |
|
||
| **特殊布局页** | Canvas/Reveal.js/简历 | 至少返回链接 | ~3 个 |
|
||
|
||
> ⚠️ 遇到自定义样式页时，**不要将其"修复"为 Fluent 2 标准模板**。这些页面刻意使用独立设计语言（如 `银行业Agent建设方案` 的深蓝+橙色金融风格、`深国际综合改革方案` 的暗红+金色政务风格）。
|
||
|
||
## UI 设计规范
|
||
|
||
所有页面遵循 `.claude/design-tokens.md` 中的 **Microsoft Fluent 2 / Windows 11** 设计规范（2026-06 从 Ant Design v5 迁移）。
|
||
|
||
> 📖 **`.claude/design-tokens.md` 是权威参考**。它包含完整的色彩阶梯、组件规范、字号表、间距表、材质/动效参数、z-index 层级、响应式断点，以及新页面创建检查清单。下文仅列出最常用的速查值，完整规范务必查阅该文件。
|
||
|
||
**快速参考**：
|
||
- **配色方案**：品牌色 `#0078D4`（Fluent 2 Communication Blue），功能色（成功 `#107C10`、警告 `#FF8C00`、错误 `#FF4D4F`）
|
||
- **字体规范**：基准字号 14px，行高 20px，字体族 `Segoe UI Variable Text` → `Segoe UI` → `PingFang SC` / `Microsoft YaHei` 回退；等宽字体 `Cascadia Code` → `Fira Code` → `SF Mono`
|
||
- **圆角体系**：`2px / 4px / 6px / 8px` 四级（Fluent 2 更方正）
|
||
- **间距体系**：旧版 8px 基准保留向后兼容，新版推荐 4px 基准的 `--fluent-spacing-*` 系列
|
||
- **阴影与层级**：Fluent 2 Elevation 体系（2/4/8/16/28/64 六级），对应 z-index 100–600
|
||
- **材质**：Acrylic（亚克力半透明模糊，导航栏用）、Mica（云母，标题栏用）、Smoke（烟雾遮罩，Modal 用）
|
||
- **动效**：标准缓动 `cubic-bezier(0.8, 0.0, 0.2, 1.0)`，时长 83ms–333ms 四级
|
||
- **主题**：`index.html` 支持亮色/暗色切换（`data-theme` 属性 + localStorage 键 `wiki-theme` + `prefers-color-scheme: dark` 系统偏好）；报告页统一亮色主题
|
||
|
||
创建新 HTML 页面时应直接复用 `:root` CSS 变量块，不要重新定义颜色值。完整规范详见 `.claude/design-tokens.md`。
|
||
|
||
### 新页面检查清单（详见 `.claude/design-tokens.md` §17.5）
|
||
|
||
新建报告页时必须逐项检查：
|
||
- [ ] 顶部固定导航栏（64px, sticky top:0）
|
||
- [ ] `← 返回知识库` 链接，href 按目录深度计算
|
||
- [ ] 左侧 260px 侧栏，含按 `<h2>` 标题生成的目录
|
||
- [ ] 所有 `<h2>` 有 `id` 锚点
|
||
- [ ] 使用 CSS 变量（`var(--color-primary)` 等）而非硬编码颜色
|
||
- [ ] 移动端（≤768px）隐藏侧栏，全宽布局
|
||
- [ ] `font-family` 引用 `var(--fluent-font-family-text)`
|
||
- [ ] 内容区 `max-width: 1200px` 居中
|
||
|
||
## Graphify 知识图谱
|
||
|
||
本项目已集成 graphify-rs 知识图谱。图谱输出位于 `graphify-out/` 目录，**按需生成**（当前不存在，需手动构建）。
|
||
|
||
首次构建：
|
||
```bash
|
||
graphify-rs build --path . --output graphify-out --no-llm
|
||
```
|
||
|
||
日常更新（修改代码后）：
|
||
```bash
|
||
graphify-rs build --path . --output graphify-out --no-llm --update
|
||
```
|
||
约 2-5s，AST-only 模式。
|
||
|
||
- 架构/代码库问题：如果 `graphify-out/` 存在，先读取 `graphify-out/GRAPH_REPORT.md` 了解核心节点和社区结构
|
||
- 如果 `graphify-out/wiki/index.md` 存在，优先导航该索引而非直接读取原始文件
|
||
- graphify-rs 使用手册参考 `graphify-rs使用手册/` 目录
|
||
|
||
## 项目级 Skills
|
||
|
||
`.claude/skills/` 下挂载了项目级技能：
|
||
|
||
| 技能 | 说明 | 触发方式 |
|
||
|------|------|---------|
|
||
| `remote-sync` | rsync 增量同步到远端服务器，自动排除 `node_modules`/`.git` 等 | `/remote-sync` 手动调用 |
|
||
| `deep-research` | 多阶段深度研究报告（P0-P7 pipeline）：Lead Agent 协调子代理并行调研 → 引用注册表 → 证据映射提纲 → 反审核 → 验证。支持通用研究与企业研究（六维框架+SWOT+风险矩阵）两种模式 | `/deep-research` 或触发词（"调研"、"深度研究"、"行业报告"等） |
|
||
| `ui-ux-pro-max` | UI/UX 设计与前端实现辅助 | 按需调用 |
|
||
|
||
`deep-research` 技能包含参考资料（`.claude/skills/deep-research/references/`）和调研笔记（`research-notes/`），执行深度研究时会用到。
|
||
|
||
## 项目管理（AI Coding 工作流）
|
||
|
||
本项目使用 **方案 B：Gitea + Markdown 项目仪表板** 进行 AI 编码项目管理。
|
||
|
||
### 核心文件
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `KANBAN.md` | 项目看板：待办/进行中/已完成/问题/定期维护，Claude Code 启动时自动读取 |
|
||
| `specs/` | 需求规格文档（喂给 AI 的输入源），每个功能模块一个 `.md` 文件 |
|
||
| `sessions/` | AI 编码会话沉淀：每次有价值的会话后记录关键结论、踩坑、审查要点 |
|
||
| `prompts/` | 已验证的可复用 Prompt 模式，从 `sessions/` 提炼而来 |
|
||
|
||
### 工作流
|
||
|
||
```
|
||
KANBAN.md 选取任务 → specs/ 写规格 → Claude Code 生成代码
|
||
→ 人工审查 → git commit → sessions/ 记录心得
|
||
→ prompts/ 提炼模式 → KANBAN.md 更新状态 → push 部署
|
||
```
|
||
|
||
### 任务状态标签
|
||
|
||
- `C-*` — 内容建设（新报告页、文章）
|
||
- `U-*` — UI/UX 改进（样式、布局、响应式）
|
||
- `I-*` — 基础设施（部署、升级、工具）
|
||
|
||
> ⚠️ `KANBAN.md` 是 AI 理解项目状态的入口。修改代码前，确保看板状态与实际一致。
|