云奕学

一个以掌握证据为核心的本地 AI 技能学习平台。

一个本地优先、以可观察证据评估掌握程度的 AI 学习系统。它的目标不只是帮助用户“看完课程”，而是形成完整闭环：

诊断 → 学习 → 练习 → 项目 → 评估 → 复习 → 变现实验

当前项目仅供仓库所有者本人使用，首个技能为算法。项目仍处于早期开发阶段，请参阅下方的当前进度，不要将路线图中的能力视为已经实现。

项目目标

这个项目希望帮助用户：

系统学习一项技能，并找出真正的知识缺口；
通过解释、练习、迁移任务和真实作品证明掌握程度；
根据实际能力证据，评估就业、自由职业接单和产品化三条路径；
追踪知识与市场变化，在用户确认后更新学习安排；
保留来源、版本、评估和计划变更记录，使关键结论可以追溯。

系统不会因为用户看完内容或通过一次简单测验就宣称“完全掌握”，也不会把预测的工作机会或收入描述为确定结果。

首个技能：算法

算法技能包采用“共同主干 + 分支解锁”的结构：

先通过诊断确认 Python、C/C++ 和必要数学基础；
补牢数据结构与算法共同主干；
通过阶段评估后，逐步解锁以下方向：
- 工程应用；
- 求职面试；
- 算法竞赛；
- 算法理论。

实践以 C++ 为主，同时支持 Python，并比较两种语言的实现方式、标准库和性能差异。学习任务预计可拆分为每天约 2 小时的可调整安排，但最终计划必须基于真实诊断结果生成。

当前进度

能力	状态	说明
项目骨架	已完成	Next.js、FastAPI、SQLite、SQLAlchemy 2、Alembic
确定性本地检查	已通过（2026-07-29）	Node 24 下完整 `release-readiness` 通过，覆盖仓库治理、前后端质量、桌面/移动 E2E、契约漂移和敏感信息扫描
GitHub Actions 基线	已验证（2026-07-29）	4A 合并后的 `main` 工作流 16 项作业全部成功
技能包治理骨架	已完成	注册表、manifest、内容哈希、Schema 和依赖图检查
初版视觉方向	7A 方向已确认；7B 外壳已实现	方向 A“证据工作台”作为全局骨架，方向 B/C 分别作为专注内容和紧凑状态的局部模式；“静水深流”继续作为可修改基础，不构成最终品牌规范
算法技能包	4B 已合并；来源补丁待正式交付	保留 `0.1.0`、`0.2.0`、`0.2.1` 历史，以 `0.2.2` 修正 cppreference 来源类型并继续提供隔离双语言练习、受限 Runner 证据和延迟复测
确定性诊断访谈	最小闭环已完成	当前是固定问题序列，支持跳过、不确定、修正、恢复、超时结束和审计；真正按信息价值动态选题及提前停止仍待实现
AI 供应商档案	接口与本地实现	可保存 OpenAI、DeepSeek、Moonshot AI 和自定义端点档案；只有本地模拟可执行
学习计划与面板	受限预览已完成	可生成、修改、保存或否决来源支持的规划，保留变更审计
来源更新检查	有限闭环已完成	每日首次学习检查固定目录；失败不阻断学习，变化只生成待审候选
站内通知与邮件	7C 收件箱已实现	一级收件箱读取真实通知、受管分类、真实未读和标记已读；实际产生证据后新增受限变化通知，通知偏好和网站运行期间 SMTP 邮件继续保留
第四里程碑 4A	已合并并验证	PR #2 已合并到 `main@953d2d2`；共同主干入口覆盖学习、练习、追加纠错、六维受限证据和第 1、2、4、7、15 天复习
第五里程碑 5A	已合并并验证	PR #3 已合并到 `main@2f847c6`；用户目标选择、六维证据门禁、不可变策略/合成市场快照、三路径比较与审计已通过本地 `release-readiness`、PR CI `30434488897` 和合并后主线 CI `30523076260`
第五里程碑 5B	已合并并验证	PR #4 已合并到 `main@273c190`。已实现版本锁、完整变化检测、证据能力门禁、知情外发、来源冷却、价格表分组列解析、受控恢复及 `limited_background_v1`；后端固定 `indeterminate / no_change`。61 项后端、14 项前端、生产构建及桌面/移动 E2E 等本地门禁通过，PR CI `30523980823` 和合并后主线 CI `30524441148` 均为 19 项成功。真实调用仍只有修复前的一次，保守记账 ¥0.003597，未生成可采纳结论
隔离代码运行	4B 已合并并验证	PR #6 已合并到 `main@0efdb4d`，合并后 CI `30696741469` 共 21 项成功；Runner 纵向切片、离线门禁与真实 Docker 十项安全／资源限制矩阵均已通过
第五里程碑 5C	已合并并验证	PR #8 已合并到 `main@9928e23`，合并后 CI `30701908365` 共 21 项成功；就业优先实验、分级证据门禁、外部真人评审、用户手动作记录、隐私收入记录与学习回流已形成纵向切片；当前用户真实求职动作证据补齐暂时阻塞
第六里程碑 6A–6D	6D 已完成并合并	浏览器同源 API 修复精确提交 `c781fe1` 已部署，旧 `5b4af16` 保留为回滚点；真实库 47 表／54 行、策略 `1.1.0`、远程 Runner、身份、Tailnet HTTPS、备份、资源和自动回滚均已复验。项目所有者已完成真实手机确认、账单复核并取消剩余观察期；PR #19 已合并为 `main@d4f079c`。Headless 浏览器限制继续记录，真实 AI／来源／邮件、公开访问和扩容继续关闭
第七里程碑 7A–7F	已完成并合并	PR #18 已合并为 `main@90e16e2`；合并后 push CI `32806434805` 共 22 项成功。Windows 实际高对比度和连续两小时阅读疲劳为非阻断后续人工任务，未执行前不得写成已通过或声称 WCAG 合规认证
第八里程碑 8A–8G	8G 技术验收完成，入口待决定	`algorithm@0.3.0` 的 12 域、46 能力、34 单元、64 题和 22 个双语言 Runner 任务已完成第二评审、迁移回滚、真实 Runner 全量复验、隐私回归和完整门禁；后端 147 项、前端 44 项、生产构建及 E2E 26 项通过。远程来源实质复核仍未授权，默认入口保持 `0.2.2`，当前推荐继续关闭 `0.3.0` 并等待项目所有者最终决定

当前 Web 页面提供算法诊断、规划、学习执行和目标准备度的本地受限流程。规划、确定性练习和 5A 准备度比较由本地规则处理；自由文本和代码文本只做结构校验，不能据此判断内容正确，也不代表算法技能包已经激活、用户已经掌握相关能力或已经具备真实交付资格。

第四里程碑的详细边界见 docs/architecture/learning-execution.md，第五里程碑目标见 docs/architecture/monetization-and-continuous-update.md，后续门禁和实施事项见根目录 TODO.md。

GitHub 同类开源项目、能力差距、采用门禁和建议复核频率见 docs/research/github-open-source-gap-analysis.md。

参考 xingkongliang/skills-manager 并按本项目隐私与授权边界适配的 GitHub Issues 流程见 docs/research/github-issues-workflow.md。

依据该差距基线制定的第八里程碑方案和已完成 8A 规格见 docs/architecture/milestone-8-learning-core.md。精确能力图与机器校验对象见 docs/architecture/milestone-8a-learning-core-spec.md。 8E 的本地档案、隐私导出和影子评估验证见 docs/architecture/milestone-8e-validation.md。 8F 的 Issues 治理、脱敏诊断和本地发布准备验证见 docs/architecture/milestone-8f-validation.md。 8G 的第二评审、迁移回滚、真实 Runner 和完整门禁证据见 docs/architecture/milestone-8g-validation.md。

新窗口读取项目现状时，先查看 docs/project-status.md，再读取 AGENTS.md 和 TODO.md；状态入口不替代项目约束和用户授权。

架构概览

flowchart LR
    Web["云奕学 Web<br/>Next.js"] -->|OpenAPI contract| API["FastAPI API<br/>启动与编排边界"]
    API --> DB[("SQLite<br/>SQLAlchemy 2 + Alembic")]
    API --> Credentials["Windows 凭据管理器<br/>SMTP 与 AI 密钥"]
    API --> Registry["内置技能包注册表"]
    Registry --> Packs["版本化技能包"]
    Packs --> Sources["受监测来源目录<br/>元数据与审查候选"]
    Contracts["contracts/<br/>API · Skill Pack · Runner"] --> Web
    Contracts --> API
    Contracts --> Runner["隔离 Runner<br/>本地实机验证完成"]

4B 的 Windows 安装入口为 tools/setup_runner_windows.ps1。它会先验证固件虚拟化、 D 盘 NTFS 和空间，不满足时不改动系统；下载文件与 WSL 数据写入 D:\CloudStudy，Docker Desktop 程序按官方推荐的个人模式安装。重启并启动 Docker Desktop 后，使用 tools/provision_runner_images.ps1 按已核验摘要下载并验证 GCC 15.2.0 与 Python 3.14.3，再运行 pnpm check:runner-live 验证 C++/Python 执行、禁网、只读根文件系统、进程限制、无仓库挂载与 Docker Socket、超时、输出上限、内存上限和容器清理。两个安装脚本都不会下载或运行学习者提交；真实隔离矩阵只运行仓库自带探针。

FastAPI 启动时会验证仓库内置技能包的一致性。注册表缺失、manifest 校验失败、内容哈希不符或依赖图无效时，应用必须拒绝启动。

技能包中的评分器、自定义校验脚本和用户代码不得直接进入 FastAPI 进程。未来需要执行代码时，只能通过版本化、资源受限的隔离 Runner 协议调用。

技术栈

Web

Node.js 24 LTS
Next.js 16
React 19
TypeScript
pnpm 11
ESLint
Vitest
Playwright

API 与数据

Python 3.14.3
FastAPI
SQLAlchemy 2
Alembic
SQLite
uv
Ruff、mypy、pytest

工程治理

JSON Schema
OpenAPI 与生成的 TypeScript 契约
GitHub Actions
技能包注册表、内容摘要和依赖图校验

仓库结构

.
├── apps/
│   ├── api/                    # FastAPI、SQLAlchemy、Alembic 与后端测试
│   └── web/                    # Next.js Web 应用
├── contracts/
│   ├── api/                    # 由 FastAPI 生成的 OpenAPI 契约
│   ├── readiness/              # 目标、准备度、合成市场快照与比较 Schema
│   ├── runner/                 # 隔离 Runner 协议 Schema
│   └── skill-pack/             # 注册表与 manifest Schema
├── docs/
│   └── architecture/           # 已确认的架构设计
├── readiness/                  # 5A 本地策略与显著标记的合成夹具
├── skill-packs/
│   ├── registry.yaml           # 内置技能包注册表
│   └── algorithm/              # 算法技能包草稿
├── tools/                      # 仓库检查和契约生成工具
├── AGENTS.md                   # 项目级产品与工程约束
├── package.json                # 本地与 CI 的统一命令入口
├── pnpm-lock.yaml              # JavaScript 依赖锁
└── pnpm-workspace.yaml

本地运行

环境要求

Node.js 24 LTS
pnpm 11
Python 3.14.3
uv 0.11.x

项目和 CI 固定使用 Node.js 24 LTS。后端暂时固定 Python 3.14.3；如果必要依赖无法支持 Python 3.14，项目会停止并报告，不会静默降低 Python 版本。

安装依赖

在仓库根目录执行：

pnpm install --frozen-lockfile
uv sync --project apps/api --locked

pnpm 只允许锁定依赖 sharp 和 unrs-resolver 执行安装脚本，其他依赖脚本不会被默认放行。

启动开发服务

分别打开两个终端：

pnpm dev:api

pnpm dev:web

本地验证阶段没有账号登录。请勿将开发服务直接暴露到不受信任的网络。

主要页面：

/：聚合现有可确定的当前任务、完成标准、复习、阻断和最近变化；
/diagnostic：本地确定性诊断访谈；
/learning：规划预览、每日来源检查、变化候选和学习执行；站内通知已统一到收件箱；
/inbox：真实站内通知、受管分类、未读状态和标记已读；
/readiness：用户目标选择、六维证据准备度与本地合成三路径比较；
/settings：通知邮件偏好和 AI 供应商档案。

真实邮件默认关闭。启用后由正在运行的 API 进程处理 SMTP 队列；网站和 API 停止时不会在后台定时发送。SMTP 密码和 AI API 密钥保存在 Windows 凭据管理器，SQLite 只记录凭据引用。

质量检查

运行完整的发布就绪基线：

pnpm release-readiness

该命令和 GitHub Actions 使用相同的本地子命令，包括：

Markdown 与仓库结构检查；
技能包注册表、manifest、内容哈希和依赖图检查；
来源目录权威性、可追溯性与 HTTPS 边界检查；
规划单元来源关联与可观察完成标准检查；
5A 合成市场快照、准备度策略与零外部调用边界检查；
JSON Schema 与 OpenAPI 契约检查；
Ruff 格式检查和 lint；
mypy 严格类型检查；
pytest 后端测试；
ESLint、TypeScript 和 Vitest 前端检查；
Next.js 生产构建；
Chromium 桌面与移动视口端到端流程；
前后端契约无漂移检查；
敏感信息基线扫描。

单独运行某项检查时，可查看根目录 package.json 中的 check:* 命令。

数据、隐私与安全边界

当前诊断和规划预览只使用本地确定性适配器，不会向外部 AI API 发送数据；
外部发送采用两层授权：全局开关默认关闭，创建每次外部 AI 对话时还必须单独确认；
关闭全局开关会阻止外部 AI 会话继续发送，并明确保留原会话配置，不会静默切换供应商或模型；
SMTP 和 AI API 密钥保存在 Windows 凭据管理器中，SQLite 只保存凭据引用和非敏感元数据；
后端不得向前端返回密钥原文，也不得把密钥写入日志；
来源远程检查失败不会阻止学习，但界面和站内通知会说明失败、最近成功时间及风险；
检测到远程变化只会生成候选记录，不能自动弃用技能包或改写计划；
当前多专家规划仅综合可追溯的公开成果，不模拟专家本人或暗示其认可；
外部内容、AI 输出、用户输入和第三方技能包都视为不可信输入；
无效的未来第三方技能包只能进入不可执行的只读隔离区；
用户代码只允许通过 4B 锁定的本地隔离 Runner 协议执行；FastAPI 不直接执行用户代码、技能包评分器或自定义校验脚本。
5A 只读取应用内已持久化证据和仓库受管策略/合成夹具，不访问市场 API、远程网页、外部 AI、任意用户路径，也不创建真实实验。

开发路线

路线图表示当前方向，不是交付时间承诺。

工程基线
- 项目骨架；
- 本地确定性检查；
- GitHub Actions；
- 远程 CI 验证。
算法诊断访谈最小闭环
- 已完成会话、可纠正回答、分支、跳过、不确定、恢复和审计记录；
- 已完成本地确定性适配器、模型锁定和两层外部 AI 权限门禁；
- 待确认真实供应商模型清单后，再接入 OpenAI、DeepSeek 和 Moonshot AI；
- 算法技能包通过正式内容审核前，诊断结果只作为草稿预览。
学习规划、来源和面板
- 已完成可修改、保存或否决的本地规划预览；
- 已完成固定来源目录、每日元数据检查、失败提示和变化候选；
- 已完成站内通知及网站运行期间的可选真实邮件；
- 已完成 AI 供应商档案接口与本地模拟，真实模型调用仍未启用；
- 正式计划、自动内容迁移和完整技能包激活仍需后续确认。
练习、项目和掌握评估
- 4A 共同主干入口受限纵向切片已通过 PR #2 合并并完成 main 远程验证；
- 已保留 algorithm@0.1.0、0.2.0、0.2.1 历史引用，并新增 0.2.2 作为来源元数据修复草稿；
- 已建立不可变学习锁、追加式尝试、六维证据、纠错和第 1、2、4、7、15 天复习；
- 代码在 4A 历史版本中只作为不可信文本保存，不执行，也不调用外部 AI；
- 4B 已单独授权；代码只允许进入本地断网、非 root、只读根文件系统的受限 Runner，本机十项真实安全与资源限制验收已经通过。
变现实验与持续更新
- 5A 已完成用户目标选择、本地确定性准备度、合成市场证据、三路径比较和追加式决定审计，并通过完整本地验证；
- 考试、纯学习和其他非变现目标不会被强制进入就业或变现比较；
- 5B 已完成受控真实市场研究代码：只允许 deepseek-v4-flash，锁定来源与预算快照，付费调用采用原子抢占、调用前 token 上限和审计历史；首次真实调用因内容结构无效停止，当前受限协议由后端固定 indeterminate / no_change，再次付费验证受 30 天间隔和逐次确认约束；
- 5C 已按就业优先边界实施本地实验纵向切片；只有当前用户取得 90 天内的操作 verified、保持 retained、迁移与作品受管真人评审，并绑定 7 天内同一精确技能版本的已接受市场研究后，才能记录其在产品外手动完成的求职动作；
- 产品不会自动投递、联系、发布或交易；收入只允许可选本地记录，默认隐藏且不能反推掌握程度；
- 不保证工作、订单或收入。
互联网部署评估
- 6A 已正式交付；6B 已在现有新加坡单实例完成 Tailnet-only 合成数据私有预发布；
- 6C 真实数据库加密副本迁移和反向恢复已通过，不替换唯一真实库，也不迁入云端；
- 远程 Runner 的独立 Broker 已按策略 1.1.0 持久启用并通过激活与独立复测两轮云端十项矩阵；FastAPI 仍无 Docker 权限，项目容器残留为零；
- 浏览器同源 API 修复精确提交 c781fe1 已受控部署，旧 5b4af16 保持可回滚；最终浏览器脚本不再包含 127.0.0.1:8000，Tailnet 首页、学习、证据、设置和三条同源 API 均返回 200；Headless 浏览器仍受 Tailscale Serve 限制，真实手机复验和账单实耗待确认；不公开网站、不扩容、不自动增加费用。
前端体验与信息架构重设计
- 7A 已在独立 worktree 中完成审计、候选核验和方向稿，方向 A 作为全局骨架，B/C 作为局部页面模式；
- 7B 已以零新增依赖实现统一外壳：默认首页为“今日”，一级区域为今日、学习、证据、目标与行动、收件箱和设置；
- 收件箱与设置同级；桌面使用统一左侧导航，移动端使用“今日、学习、证据、收件箱、更多”底部导航；
- 7C 已以零新增依赖接入真实今日聚合和一级收件箱；学习提交只有在实际创建对应能力范围证据时才生成变化通知，且不会据此声称整门技能掌握；
- 7D 在独立分支重组学习页任务层级，并建立只读取最新学习执行真实记录的六维证据中心；等级、记录、待办与外部真人评审分开显示，不伪装为全历史聚合；
- 7E 在独立分支以零新增依赖建立语义设计令牌和共享反馈组件，统一全站焦点、表单、状态、空态、加载、表格和响应式基线，并以桌面／移动 E2E 验证 AA 令牌对比度、200% 文本缩放与减少动效；完整本地 release-readiness 已通过；
- 7F 在独立 codex/milestone-7f 分支进行全站体验验收，只允许小范围前端修复，不得修改后端、6B 工作区、服务器或部署状态；屏幕阅读器实际听感和连续两小时疲劳验证不得由自动化检查代替；
- Leonxlnx/taste-skill、Shadcn/UI、Radix Themes、Tremor、Cal.com、Outline、Magic UI 等仅作只读方法参考，未安装、执行或复制；7F 已授权但仍在验收中。

项目约束与设计文档

开始修改前请先阅读：

这些文档定义了产品边界、内容可信度、掌握评估、技能包治理、安全隔离和开发顺序。CI 基线未通过前，不得提前实现自适应访谈等业务功能。

许可证

项目所有者拥有版权的项目代码和文档采用 PolyForm Noncommercial License 1.0.0：

允许许可证规定范围内的个人学习、研究、实验、修改和非商业分发；
不允许未经授权的商业使用；
这是一份 source-available 非商业软件许可证，不是 MIT License，也不是 OSI 认可的开源许可证；
第三方依赖、工具和引用内容继续适用各自的许可证与条款。

请以 LICENSE.md 中的完整英文条款为准。

Name		Name	Last commit message	Last commit date
.github		.github
apps		apps
contracts		contracts
deployment		deployment
docs		docs
governance		governance
readiness		readiness
runtimes		runtimes
skill-packs		skill-packs
tools		tools
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.node-version		.node-version
.python-version		.python-version
AGENTS.md		AGENTS.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
待修复.md		待修复.md

Navigation Menu

Repository files navigation

云奕学

项目目标

首个技能：算法

当前进度

架构概览

技术栈

Web

API 与数据

工程治理

仓库结构

本地运行

环境要求

安装依赖

启动开发服务

质量检查

数据、隐私与安全边界

开发路线

项目约束与设计文档

许可证

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

云奕学

项目目标

首个技能：算法

当前进度

架构概览

技术栈

Web

API 与数据

工程治理

仓库结构

本地运行

环境要求

安装依赖

启动开发服务

质量检查

数据、隐私与安全边界

开发路线

项目约束与设计文档

许可证

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages