CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

青浦区营商智能助手前端。Vue 3 + TypeScript + Vite，面向企业的政策匹配与办事指引：用户自然语言提问，助手检索政策知识库，以「开场概述 + 政策卡片 + 综合说明 + 参考资料」的形式给出有原文依据的回答；涉及具体企业时先引导用户确认公司主体，再结合工商信息作答。

关键事实（避免误判）：

对话走新接口 POST /api/chat（SSE）。前端不直接渲染新协议，而是经适配层 src/components/api-chat-coordinator.ts 翻译成既有渲染组件可识别的内容标记。详见下方「Core Systems」与根 README 的「对话接口的关键约束」。
没有 3D 虚拟人渲染。three 仅用于粒子背景（business-assistant-particle.ts）； src/three-libs/asr 用于语音识别；src/three-libs/metamaker 是一份未被引用的 SDK 包。
没有状态管理库（无 Vuex / Pinia）。对话状态在 useBusinessAssistantChat 内，会话与消息持久化到 localStorage。
接口契约见 docs/reference/（现行 api-chat.md；legacy/API.md 仅为交接快照）。

Common Commands

# Development
npm run dev                    # Start dev server on port 8083 (HTTPS, self-signed)
npm run preview                # Preview production build

# Building
npm run build                  # Production build
npm run build:test             # Test environment build
npm run build:qingpu           # Qingpu environment build
npm run zip                    # Create ZIP for Qingpu deployment

# Testing
npm run test                   # Run Jest tests

# Linting (use VSCode or external tools)
# ESLint config at .eslintrc.js

Architecture

Main Entry

src/main.ts - Application entry point, creates Vue app
src/App.vue - Root component, renders the 招商助手
src/components/BusinessAssistant.vue - 只做 PC / 移动端切换，不是主壳
src/components/BusinessAssistantPC.vue / BusinessAssistantMobile.vue - 真正的页面主壳（输入区、消息列表、滚动与打字机联动都在这里）

Key Directories

src/components/Chat/ - 消息渲染与政策卡片（BusinessRecord、PolicyMatch、QuestionCard…）
src/components/Common/ - 通用 UI 组件（MediaViewer、ScrollList、Toast…）
src/components/business-assistant/ - 对话编排（useBusinessAssistantChat、上传、滚动等）
src/network/api/ - 接口封装：chat-sessions.ts、enterprise.ts、 assistant-statistics.ts、card/（没有 chat / faq / finance / group / human / project 这些文件）
src/types/ - TypeScript 类型定义
src/utils/ - 工具（runtime-config、stream-xml-filter、scope-record-rows…）
src/three-libs/asr/ - 语音识别（Three.js 相关代码只在这里和粒子背景中用到）

注意：没有 src/hooks/ 目录。

Core Systems

对话协议适配（现行）: src/components/api-chat-coordinator.ts —— 新接口 POST /api/chat 的客户端。把 SSE 事件翻译成 <scope> /  / <ref_links> / <question-cards> 等标记，交给既有渲染组件；渲染层不感知新协议。
旧协议实现（保留未用，勿改）: src/components/stream-message-coordinator.ts。 没有 stream-message-coordinator-v2.ts 这个文件。
State Management: 无状态管理库（无 Vuex / Pinia）；状态在组合式函数 + localStorage
UI Library: Ant Design Vue 4.x
Three.js: 0.143.0（粒子背景 + 语音识别相关，非 3D 虚拟人）

Build Configuration

Vite build config: vite.config.ts
Environment files: .env.development, .env.production, .env.test, .env.qingpu
Uses unplugin-vue-components for auto-importing Ant Design Vue components

CI/CD

仓库内没有 .gitlab-ci.yml 等流水线配置文件；构建入口就是上面的 npm scripts。若存在服务端流水线（GitLab / Gitea 后台配置），其规则请在服务端查看，不要以旧描述为准。

API Proxies (dev mode)

/api/* → http://aixq.shqp.gov.cn
/chat-api/* → http://192.168.2.23:8000（新对话接口；rewrite 去掉 /chat-api 前缀，最终请求 …/api/chat。仅 dev server 生效，生产需 nginx 等价转发）
/asr/* → https://human-screen-v3.metamaker.cn
/stream/* → https://flv-enc.metamaker.cn

Notes

Uses @ alias for src/ in imports
Three.js has special alias to three/build/three.cjs
SCSS API set to "modern-compiler" in vite.config.ts
No ESLint run in CI (build only)

Harness 工作流（必须遵守）

本仓库用 harness/ 目录管理长时开发的状态。这些文件不会自动维护——你必须按下面的要求读和写。 详见 harness/README.md。

每轮开工时

pwd 确认在仓库根目录
读取 harness/claude-progress.md（当前已验证状态 + 上一轮记录）
读取 harness/feature_list.json（功能清单与状态）
git log --oneline -5 查看最近提交（若仓库尚无提交，跳过即可）
运行 bash harness/init.sh
然后只选择一个未完成功能，围绕它工作，直到它验证通过、或被明确记录为 blocked

规则

每次改动完成后立刻更新记录，不要攒到会话结束。 一轮会话常含多次改动，攒到最后必然漏记、并让已写下的描述过期（真实发生过：一次改动没记，记录里还留着后来被推翻的旧结论）。改动完当场追加 session 记录 / 更新功能状态。
同一时间只能有一个 in_progress 功能
没有可运行证据（构建或测试的实际输出）时，不要声称完成
不要通过重写功能清单来隐藏未完成的工作
不要为了让状态好看而删除或削弱验证步骤
仓库内文件是唯一事实来源——不要把结论只留在聊天里

完成门槛

只有在要求的验证成功、且结果被记录进 harness/feature_list.json 的 evidence 与 harness/claude-progress.md 之后，功能状态才可以切到 passing。

结束前

更新 harness/claude-progress.md（追加一条 session 记录）
更新 harness/feature_list.json 的状态与证据
记录仍然损坏或未验证的内容
过一遍 harness/clean-state-checklist.md
给下一轮会话留下干净的重启路径

本项目的额外约束

界面样式必须与原版一致。 新协议能力通过 src/components/api-chat-coordinator.ts 翻译成既有渲染组件能识别的内容标记（<scope> /  / <ref_links> / <question-cards>），不要新建带自有样式的 UI 组件。
既有 UI 的可选项、文案、筛选逻辑不要擅自改动——确需变更先取得确认。
src/components/stream-message-coordinator.ts 是保留的旧协议实现，当前未被使用，不要改动。
需要确认"原来是怎么做的"时，diff 备份目录 F:\yysk\AI_zhaoshang\备份\zhaoshang-llm （早于所有改动），不要凭记忆断言。

接口文档在哪

改任何聊天相关代码之前，先读 docs/reference/api-chat.md（现行契约） 与 docs/reference/api-chat-fields-zh.md（字段中英对照）。索引见 docs/reference/README.md。
docs/reference/legacy/API.md 是交接时根据当时的源码生成的快照，不是规格、不会更新。 不要照着它实现新功能（现行契约看 api-chat.md）， 也不要拿它当"原来行为是什么"的判据——它是二手整理可能失真；判断原行为请直接 diff 备份目录里的源码。

CLAUDE.md 7.7 KB История Исходник