AI 协会 · AI 提效项目看板

公司内部 AI 协会面向同事的只读型展示看板：项目推进、积分计算依据与会员最终积分排行。降本价值分析只保留在独立 Excel 价值表中，不进入网站。 页面为标签页布局，积分榜直接内置于首页：

页签	内容	深链接
总览（首页）	赛季横幅 + 积分榜（Top 3 领奖台 + 完整榜单） + 关键数据 KPI	/#overview
项目看板	状态分布 + 筛选器 + 项目明细表（公开基础积分、难度系数和最终积分）	/#projects
规则	五步流程 + 积分对照表与部门难度系数说明 + 四条积分规则	/#rules

• 纯静态站点：HTML + CSS + 原生 JS，零运行时依赖，零外部 CDN
• 数据与展示完全分离：页面只读取 data/dashboard.json
• 亮色科技蓝主题（淡蓝底 + 白玻璃卡片 + 品牌蓝主色），支持桌面 / 大屏 / 手机
• 标签导航支持鼠标、触摸以及键盘左右方向键循环切换；Home / End 可直达首尾标签
• 手机端将项目明细和积分榜自动转换为卡片布局，不依赖横向拖动表格
• 标签页支持 #hash 深链接；旧的 /#leaderboard 自动兼容映射到首页
• 不含登录、数据库、在线审批等任何业务交互

快速开始

由于浏览器安全限制（CORS），不能直接双击打开 index.html，需要起一个静态服务器：

cd 本目录
python3 -m http.server 8000
# 打开 http://localhost:8000

任何静态服务器都可以，例如 npx serve、caddy file-server 等。

目录结构

/
├── index.html                  # 页面骨架（四个标签页，积分榜在首页 + 内联 SVG 图标库）
├── assets/
│   ├── css/style.css           # 全部样式，主题令牌集中在文件顶部 :root
│   └── js/main.js              # 标签页控制器 + 读取 JSON 渲染 KPI/项目表/排行榜
├── data/
│   └── dashboard.json          # 唯一的业务数据源
├── workspace/                  # ★ 日常只维护这里的业务文件
│   ├── AI项目一期-*.xlsx       #    项目主表：项目、申报人、初始承接人与评分参数
│   ├── AI项目一期-月度价值表.xlsx # 可选独立产物；不参与网站更新
│   ├── AI协会群成员.csv        #    可选成员名册；通常无需频繁更新
│   └── 协会人员与项目积分台账.xlsx # 日常维护承接、结项和结果系数
├── templates/                  # ★ 职能人员直接填写的 Excel / Word 标准模板
│   ├── AI协会项目维护台账模板.xlsx
│   ├── AI协会项目申报及状态更新模板.docx
│   └── README.md               #    无代码使用说明
├── tools/
│   └── generate_dashboard.py   # 演示数据生成器（内置 28 条示例项目）
├── skills/
│   └── ai-dashboard-sync/      # ★ Excel/Word → 数据同步并发布线上 的 Agent 技能
│       ├── SKILL.md            #    技能说明书（Agent 按此执行）
│       ├── agents/openai.yaml  #    Agent 界面名称、简介与默认说法
│       ├── deploy.json         #    线上地址 + 共享密码（敏感：泄漏后按 README 换密码）
│       ├── scripts/
│       │   ├── prepare_ledgers.py # 项目表 + 旧台账 → 标准台账模型
│       │   ├── build_ledgers.mjs # 生成人员/项目积分台账 Excel
│       │   ├── prepare_value_model.py # 证据化降本换算与阻断校验
│       │   ├── build_value_workbook.mjs # 生成单页月度价值表
│       │   ├── publish_from_ledger.py # 只从项目表+台账更新网站
│       │   ├── update_board.py #    日常唯一入口：预检 → 发布 → 线上复核
│       │   ├── prepare_word_intake.py # 自由排版 Word 的模型兜底准备
│       │   └── sync_dashboard.py #  底层解析、对账与上传引擎
│       ├── references/         #    字段、积分、状态与故障解释
│       └── server/             #    服务端组件（已部署到 VPS，存档于此）
│           ├── score_upload.lua    #    上传接口：校验 + 原子写入 + .bak
│           ├── score-api.conf      #    nginx location 片段
│           └── board-sync-mirror.sh #   /root 规范目录镜像脚本（cron）
└── README.md

当前推荐维护方式：新一期初始化，之后只维护台账

新一期集中收集项目时，生成项目表和 workspace/协会人员与项目积分台账.xlsx。项目表分开记录“申报人”与“承接人”；项目和积分按承接人归属。

初始化后，日常只维护积分台账中的承接人、项目状态、积分结项和结果系数。每次台账修改后，再明确请 Agent “更新网站”。价值表是可选的独立产物，不参与网站更新，也不会被自动生成。直到下一期项目开始，才重新生成项目表与台账。

当前业务口径

• 项目推进状态只有 实施中 / 等待承接。承接人留空必须是“等待承接”，填写承接人必须是“实施中”。
• 申报人与承接人可以不同；项目和积分按承接人归属。
• 推进状态不等于完成状态，不能因为项目“实施中”就计入积分。
• 项目只有在积分台账中明确标记“已完成”并填写结果系数后，最终积分才会入账。
• 最终积分公式为：基础积分 × 难度系数 × 结果系数。结果系数允许小于 100%，用于项目最终效果不及预期时折减。
• 同事版项目看板同时展示基础积分、难度系数和最终积分，保证结项后的实际积分可以对账。
• 价值分析、季度降本和成本拆分不进入网站或 data/dashboard.json，只维护在独立 Excel 价值表中。
• 只选“已完成”但不填结果系数会阻止生成，避免默认按满分误记。
• 未完成项目的最终积分固定为 0；人员积分榜只汇总最终积分。
• 人员积分台账不展示角色和部门，直接列出每个人的承接项目与已经产生最终积分的项目；项目最终积分台账也不展示部门列。

兼容维护方式（Excel / Word 发布链路）

方式 A：让 AI Agent 干活（兼容旧模板）

维护人员继续用 Excel / Word 维护台账，然后把文件拖进装了本技能的 Agent，只需说：

"把这份《项目积分表.xlsx》同步到看板并发布"

Agent 会按照 skills/ai-dashboard-sync/SKILL.md 自动完成：识别附件 → 提取清洗 → 积分与排行榜对账 → 写入标准数据 → 发布 VPS → 线上哈希复核。任何错误都会在发布前停止，并精确到 Excel sheet/行号。

工程内已提供可直接复制使用的标准样板：

• templates/AI协会项目维护台账模板.xlsx：适合集中维护多个项目，内置状态下拉、积分校验和填写说明；
• templates/AI协会项目申报及状态更新模板.docx：适合一项目一文档，项目编号可选，无编号时按稳定项目名称更新；
• templates/README.md：给职能人员看的无代码操作说明。

日常维护不需手动运行命令。管理员需要排查时，唯一入口是：

python3 skills/ai-dashboard-sync/scripts/update_board.py "项目积分表.xlsx"

批量 Word 文件夹也使用同一入口：

python3 skills/ai-dashboard-sync/scripts/update_board.py "项目申报文件夹"

• 默认就是“预检通过后发布”，不需要记 --upload；只检查时加 --preview。
• 只提供 Word 时，会先取线上全量数据，按项目编号或唯一名称更新/追加，不会覆盖掉其他项目。
• Word 可不填项目 ID：有 ID 按 ID 更新；无 ID 按唯一项目名称对齐；新名称自动生成稳定 AUTO-... 内部编号；同名歧义会阻止发布。
• 可直接传入『一项目一 Word』的整个文件夹；会递归扫描每份 .docx，任何一份失败都阻止整批发布。
• Word 无固定模板时，先自动识别表格/竖表/段落字段；仍无法确定时由小模型从纯文本提取，每个字段必须附原文证据。
• 发布前会重新打开原 Word 并校验文本哈希，避免模型猜测、丢文档或在提取后原文被换掉。
• 未指定文件时，入口只扫描当前目录，自动选最新 Excel 主表和比它更新的 Word。
• 地址和发布凭据已预置，维护人员无需登录服务器、接触 JSON 或知道密码。
• 发布链路有四道校验：本地源校验 → 上传前结构总校验 → 服务端 Lua 二次校验 → 上传后 SHA-256 比对；内容没变化时自动跳过上传。
• 无第三方库时自动降级为纯 Python 标准库解析，裸 python3 也能跑； 建议维护者机器安装 pip3 install openpyxl python-docx 以获得最佳兼容性。

方式 B：演示数据生成器

tools/generate_dashboard.py 内置一套与网站一致的示例数据，用于开发与演示：

python3 tools/generate_dashboard.py

旧模板数据约定

• 旧模板的内部 status 仍兼容：待预评审 / 实施中 / 待验收 / 已完成；当前 workspace 生成的页面只展示 实施中 / 等待承接
• expected_gain 在前端展示为“项目价值”，可填写提效、降本、质量提升或风险降低等价值说明
• project_info 为项目详细摘要，不进入表格列；鼠标悬停或键盘聚焦项目行时通过浮层展示
• pre_score 为 4~10 的评估积分；未评估为 null，前端显示“待评估”
• effective_score 为最终积分；workspace 模式下仅在完成且有结果系数时按公式计算，否则为 0
• is_candidate 标记 Top 16 激励候选边界（前端据此渲染分割线）

安装 Excel/Word 同步 Skill（给 AI Agent 用）

本工程自带标准 Agent Skills（SKILL.md）规范 的技能包，可装到不同 harness 中：

ZCode

# 用户级（所有项目可用）
mkdir -p ~/.zcode/skills
cp -R skills/ai-dashboard-sync ~/.zcode/skills/

# 或软链，随工程更新自动同步
ln -s "$(pwd)/skills/ai-dashboard-sync" ~/.zcode/skills/ai-dashboard-sync

重启会话后，对 Agent 说"把这份 Excel 同步到看板"即可触发。

Codex CLI

# 若你的 Codex 版本支持 skills（~/.codex/skills/）
mkdir -p ~/.codex/skills
cp -R skills/ai-dashboard-sync ~/.codex/skills/

若版本不支持 skills 目录，把 SKILL.md 的内容并入仓库根目录的 AGENTS.md （或在对话中让 Codex "阅读 skills/ai-dashboard-sync/SKILL.md 并按其执行"）。

WorkBuddy 等其他 Agent 工具

• 支持 Agent Skills / 插件导入的工具：在"技能管理"中导入 skills/ai-dashboard-sync 文件夹（以 SKILL.md 为入口）；

• 仅支持自定义指令的工具：把 SKILL.md 正文粘贴进系统提示 / 项目说明；

• 任何能执行 shell 的 Agent 都可以直接调用脚本：

  python3 skills/ai-dashboard-sync/scripts/update_board.py --help
  

验证安装

装好后让 Agent 执行 --help，能打印参数说明即安装成功； 再用一份样例 Excel 让 Agent “只检查、不发布”，或管理员执行 update_board.py --preview 样例.xlsx 验证完整预检链路。

部署到 VPS（当前线上架构）

线上已部署于 board.kj2ai.top/score（1Panel + OpenResty 容器），架构如下：

VPS (root)
├── /root/ai-score-board/                     # ★ 规范源目录（网页文件 + 数据）
│   ├── index.html  assets/  data/dashboard.json
├── /opt/1panel/www/sites/board.kj2ai.top/
│   ├── index/score/                          # 服务副本（OpenResty 容器挂载可见）
│   │   └── index.html  assets/  data/dashboard.json[.bak]
│   └── proxy/
│       ├── score.conf            # location /score/ 静态托管（no-store）
│       ├── score-api.conf        # POST /score/api/dashboard 上传接口
│       └── score_upload.lua      # 密码校验 + Lua 数据校验 + 原子写入
└── /usr/local/bin/board-sync-mirror.sh       # cron 每分钟：服务副本 → /root 规范目录

• 访问入口：https://board.kj2ai.top/score/（HTTP 自动跳 HTTPS，/score 308 补斜杠）。
• 数据更新：skill 的 update_board.py 预检通过后自动发布 → 接口校验后写入服务副本 → 前端即时生效 → cron 把新数据镜像回 /root/ai-score-board/data/。无需人工登录服务器。
• 更新网页文件（改了 index/assets 时）：以 /root/ai-score-board 为源， 复制到服务副本后 docker exec 1Panel-openresty-xfK2 nginx -s reload。
• 修改上传密码：改 proxy/score_upload.lua 里的 TOKEN，reload OpenResty， 同时更新技能包 deploy.json 的 token。旧密码立即作废。
• 回滚：服务副本旁保留 dashboard.json.bak（上一版），覆盖回去即可。
• 注意：1Panel 若在界面上重建/改写该站点配置，proxy/*.conf 的自定义规则需确认仍在。

若要迁移到其他 VPS/路径，参考要点：静态站无后端，任意 Nginx/Caddy 托管 index.html + assets/ + data/ 即可；上传接口依赖 OpenResty 的 content_by_lua_file； deploy.json 中的两个 URL 改成新域名即可。

自定义主题

配色全部集中在 assets/css/style.css 顶部的 :root 设计令牌里：

变量	用途
--bg / --bg-2	页面底色（当前为淡蓝）
--blue / --cyan	品牌蓝主色与青色辅助
--blue / --slate	实施中 / 等待承接状态语义色
--gold	榜首金色
--glass / --line	玻璃卡片底与描边

明确不做

登录注册、管理员后台、在线申报 / 审批 / 评分 / 验收、评论点赞、通知、数据库、API Server 等。 本站永远只做"展示"，业务流程在线下与 Excel/Word 中完成。