CampusClaw Studio 个人 AI 应用平台

10.21 个人项目阶段验收。包含学科答疑、写作工坊、学习规划三款 AI 应用，以及提示词模板、知识库检索、内置/上传 Skill、独立 MCP 工具服务和完整请求轨迹。

**Git 仓库地址：https://gitlink.org.cn/muku/websoft-hw1021.git **

启动

需要 Python 3.10+（含 SQLite FTS5）。应用仅使用标准库，不需要安装依赖。

python scripts/init_env.py
python run.py

访问 http://127.0.0.1:8080 。A 班教师 teacher_a，学生 student_a1；B 班教师 teacher_b，密码均为 Demo123!。教师可维护配置、上传知识/技能和连接 MCP，学生可运行本班应用与查看自己的轨迹。

默认同时启动应用 8080、独立子进程 MCP 服务 8091 和离线模型协议演示器 8092。端口占用时可设置 MCP_PORT、MCP_URL、DEMO_MODEL_PORT、LLM_BASE_URL，应用端口使用 --port。不要将开发服务直接暴露到公网。

默认 LLM_MODE=demo 是确定性的离线协议演示器，不是真实 LLM。它通过真实 HTTP 收发 Chat Completions 格式报文，完成可重复的模板、RAG、技能和工具调用验证。界面与报告均标明模式。切换真实 LLM 后同一 Gateway 和编排代码继续工作。

真实模型配置

只修改本机 .env：

LLM_MODE=remote
LLM_BASE_URL=https://实际模型网关/v1
LLM_MODEL=支持工具调用的实际模型名
LLM_API_KEY=实际密钥

模型须支持 messages、tools、tool_choice、tool_calls 及 role=tool。示例请求采用非流式 Chat Completions。远程模式不启动本地模型演示器；本次交付不包含真实模型密钥，也不宣称已完成真实远程模型联调。

知识检索默认沿用本地 2048 维词法哈希向量和 SQLite FTS5，可按 .env.example 配置远程嵌入与 Qdrant。切换索引模型或后端须换新的 DATA_DIR。

五项验收怎么复现

提示词与访问参数：进入提示词模板修改内容，保存应用中的语气和格式，运行应用。到运行轨迹查看渲染后 system 消息、model/temperature/max_tokens/stream/messages 及接口原始响应。
知识库内容是否全部传递：绑定指定材料后提问。平台先按班级和材料过滤，再混合检索取前四条。轨迹的 retrieval.hits 和 KNOWLEDGE_EVIDENCE 可逐条对应；未命中文本不会整库传送。
Skill 是否全部传递：只发送绑定技能的名称/描述目录，按 triggers 词法命中选择最多一条。命中技能的完整 SKILL.md 作为 ACTIVE_SKILL 加入 system；未命中技能正文不加载。
Skill 的执行逻辑：记录路由、加载全文、限制工具候选集、模型提出调用、宿主执行及工具结果回传。Skill 是声明式 Markdown 行为约束，不执行上传文件中的 Python 或 Shell。
MCP 接入后的参数：在 MCP 页面连接 campus-tools，回到学科答疑输入“把 1500 米换算成千米”。第一轮请求含发现结果转换的函数 schema；模型返回 tool_calls；宿主校验参数并发送 tools/call；第二轮 messages 含 assistant.tool_calls 和 role=tool 结果，最终返回 1.5 km 的工具数据。

用户端访问应用采用 Bearer JWT；LLM_API_KEY、MCP_AUTH_TOKEN 在服务端使用，轨迹不包含这些凭证。运行轨迹包含用户问题与资料片段，是用户自己的验收数据，不应当作无敏感信息的公共日志发布。

Skill 上传约定

示例见 skills/review-coach.md。支持最大 32 KiB UTF-8 .md 文件，frontmatter 支持四个单行字段：name、description、triggers（逗号分隔）、tools（逗号分隔 tool_name@server-name）。这是为课程实现的受限解析格式，不宣称支持所有 YAML 或通用 Skill 规范。

技能上传后需要在应用编排中勾选并保存。路由候选仅来自该应用绑定，按关键词命中数取最高分，同分按绑定顺序，零命中不选择。选中技能的工具集与应用工具集取交集，实现最小权限；无技能命中时使用应用绑定工具集。

MCP 与工具

mcp-server/server.py 实现 MCP 2025-06-18 的 Streamable HTTP JSON 响应子集，入口 /mcp，支持 initialize、notifications/initialized、tools/list、tools/call。无状态服务不分配 Session ID；客户端支持服务端返回 Session ID 和 JSON/SSE 响应。自建服务暴露 formula_hint、unit_convert 两个只读工具。

工具参数按本项目使用的 JSON Schema 子集进行宿主与服务端双重校验。服务器登记地址必须位于服务端 MCP_ALLOWED_URLS 中。连接失败或断开时清空清单；不影响基础回答。默认最多 3 轮工具往返和累计 5 次执行，达到上限后停止调用。工具文本中明显指令模式会被丢弃，输出截断为 6000 字符；该规则不能替代权限控制，也不能保证防住所有提示词注入。

测试与验收证据

python -m unittest discover -s tests -v
python scripts/verify_acceptance.py

验收脚本使用临时数据库和随机端口，实际启动模型 HTTP 服务、独立 MCP 子进程和应用 HTTP 服务，导出 evidence/ 下五项核心记录及补充记录。它会保存真实 JSON 请求/响应和自动断言结果，不会读取 .env 中的真实 API Key。运行截图在 screenshots/，提交报告在 docs/。

接口描述位于 /openapi.json。主要接口：/api/apps、/api/templates、/api/materials、/api/skills、/api/mcp/servers、/api/run、/api/traces、/api/tool-records。除登录、健康检查、静态页面和 OpenAPI 外均需 JWT。

Docker Compose

python scripts/init_env.py
docker compose up --build

API 与自建 MCP 为独立容器，共享环境变量中的 MCP_AUTH_TOKEN；MCP 端口不发布到宿主。数据保存在 studio-data 卷。Compose 配置随项目提供，是否实际运行过请以 evidence/verification-summary.json 为准。

app/                 JWT、知识检索、平台编排、Gateway、MCP 客户端
static/              多应用与资源管理、轨迹查看页面
mcp-server/          独立工具服务
skills/              可上传 Skill 示例
examples/            自编 A/B 班资料
tests/               单元和真实 HTTP 集成测试
scripts/             初始化与一键验收
evidence/            可核对的请求响应记录
screenshots/         浏览器验收截图
docs/                Word 与 PDF 阶段验收报告
openspec/            本次变更说明与验收场景