wiki/CLAUDE.md

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> 标签内），按分类分组，每个分类是一个对象：

{ 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/ 目录，按需生成（当前不存在，需手动构建）。

首次构建：

graphify-rs build --path . --output graphify-out --no-llm

日常更新（修改代码后）：

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 理解项目状态的入口。修改代码前，确保看板状态与实际一致。