VELA 公开版说明书

VELA 用工程控制论组织研究：目标、状态、反馈、验证、校正都必须落到文件、检查和版本历史里。

VELA 解决什么问题

VELA 不是替用户做研究，而是给研究过程建立可检查的操作层。

常见问题	VELA 怎么处理
材料散在聊天、PDF、网页、笔记、代码和草稿里	建立固定项目结构，把材料、证据、主张、方法、交付物分开。
Codex 每次都要重新解释上下文	用 `AGENTS.md`、handoff 和 `.vela/context.json` 保存可读上下文。
AI 总结被误当成证据	只有完成来源、访问时间、核验状态和支持关系的材料才能进入 `evidence/`。
工具越接越多，边界不清	用 route/profile 决定什么时候使用哪些 skill、插件和 MCP。
经验沉淀靠记忆，容易越界	记忆只作为候选线索；长期规则必须经过检查、测试和版本提交。

VELA 做的事	具体含义	用户得到什么
建项目秩序	生成固定目录、Codex 指令、交接模板和机器可读状态。	换对话、换协作者，也能看懂项目做到哪一步。
管工具边界	把 skill、插件、MCP、本地命令放进路线表和质量门。	工具按任务开启，不因为“能调用”就随意调用。
沉淀经验	日志、失败原因、修复动作进入候选改进。	环境可以演化，但长期规则必须经过验证和提交。

VELA 公开版包含研究路线、公开 skills、MCP/profile 模板、插件协作方式、schemas、validators、tests、envctl、记忆治理和项目文件夹规则。它不包含用户私有数据库、账号状态、浏览器登录态、cookies、密钥、缓存或与公开研究工作流无关的个人定制模块。

工程控制论骨架

VELA 把每个研究项目看成一个需要持续校正的系统：先定目标，再观察状态，收集反馈，通过验证门，最后小步校正。

控制论概念	在 VELA 里是什么意思	你会看到什么
目标	研究任务到底要完成什么	research question、阶段目标、交付物说明、handoff task
边界	哪些目录、材料、工具可以动，哪些不能动	`AGENTS.md`、handoff constraints、privacy boundaries
状态	项目当前处于什么阶段，有哪些材料、证据、阻塞和交付物	`.vela/context.json`、logs、counts、validator report
反馈	执行后产生的可检查信号	doctor 结果、schema error、lint error、测试结果、引用核验结果
控制器	决定走哪条路线、用哪些工具、何时停下检查	routing table、profiles、quality gates、envctl validators
执行器	真正做事的技能、脚本、插件、MCP 和本地工具	skills、MCP servers、Codex plugins、Python/Git/rg
扰动	可能让项目跑偏的因素	登录态、网络、权限、路径变动、工具缺失、未经核验的资料
稳定性	项目能否越做越清楚、越做越可交接	Git 提交、测试通过、日志完整、证据链可复核

落到实际操作上，就是先写清任务，再选择路线，再打开必要工具，执行后留下状态，然后用 schema、引用、证据、路径、权限和隐私扫描检查，最后只把通过检查的经验沉淀为长期规则。

总体结构

VELA 可以只用最小项目结构，也可以安装完整运行层。

模块	通俗解释	主要内容
VELA 源包	从 GitHub 下载或 clone 的 VELA 仓库	`package/`、`runtime/`、`schemas/`、`scripts/`、`docs/`、`tests/`
本机运行层	安装到用户自己 Codex 环境里的运行入口	`~/.vela`、`~/.codex/skills`、CLI、profiles、commands、安装回执
项目工作层	每个研究项目自己的文件结构	`materials/`、`evidence/`、`claims/`、`methods/`、`deliverables/`、`handoffs/`、`logs/`
工具接口层	按任务需要连接外部工具	Git、Python、ripgrep、原生 Browser/Chrome/Computer Use、按路线启用的 MCP、Codex plugins、Zotero、Obsidian
记忆与演化层	保存经验，但必须经过治理	logs、本地记忆候选、本地记忆状态报告、CodeGraph 索引、evolution backlog、validators

层	Windows 常见位置	macOS / Linux 常见位置	说明
源包	用户 clone 的 `vela/` 目录	用户 clone 的 `vela/` 目录	用 Git 更新，查看源码和文档。
运行层	`%USERPROFILE%\.vela`、`%USERPROFILE%\.codex`	`~/.vela`、`~/.codex`	安装 CLI、skills、profiles、commands 和 doctor 结果。
项目层	任意研究项目目录	任意研究项目目录	`vela init` 生成项目结构和 `.vela/context.json`。

其他用户安装后也会形成“源包 + 本机运行层 + 自己的研究项目层”。源包负责更新，运行层负责让 Codex 能调用，项目层保存用户自己的材料和交付物。

七层结构

七层结构把“我要做什么、用什么工具、依据什么材料、处于哪个阶段、留下什么记录、怎么检查、哪些规则能长期保留”拆开。

层级	一句话解释	典型内容	主要检查
01 任务与边界	先确定任务目标和可动范围	`AGENTS.md`、handoff、constraints、expected output	任务是否过宽，是否缺少验收标准
02 工具与接口	决定是否需要外部工具	Git、Python、rg、原生 Browser/Chrome/Computer Use、MCP、插件、Zotero、Obsidian	工具是否可用，是否需要登录或权限
03 上下文与证据	明确当前判断依据	materials、evidence、claims、methods、source notes	材料是否完成核验，证据是否能支撑主张
04 研究阶段	判断项目处于哪一步	研究设计、文献、全文、分析、写作、图表、投稿、复盘	是否跳过了必要阶段
05 运行日志	留下执行痕迹	logs、handoff render、doctor report、validation report	是否能复盘失败原因
06 可靠性检查	用规则检查项目是否可信	schema、validator、privacy scan、tests、quality gates	是否有结构、隐私、引用或证据风险
07 环境治理	决定哪些经验能长期留下	routing table、profiles、memory policy、evolution backlog、Git commit	是否通过检查、测试和人工确认

上一层问的问题	下一层负责回答
任务到底是什么？	任务与边界层写清目标、范围和验收标准。
需要哪些工具？	工具与接口层决定是否打开插件、MCP 或本地命令。
凭什么判断？	上下文与证据层区分材料、证据、主张和方法。
做到哪一步？	研究阶段层记录当前在设计、检索、分析、写作、投稿还是复盘。
结果可靠吗？	可靠性检查层运行 schema、测试、隐私扫描、引用核验和质量门。
经验能不能留下？	环境治理层决定是否进入长期规则、profile、skill 或文档。

安装与环境要求

Windows

git clone https://github.com/Marcus-AI4SS/VELA.git vela
cd vela
.\install.ps1 -BootstrapTools
.\vela.ps1 doctor

macOS

git clone https://github.com/Marcus-AI4SS/VELA.git vela
cd vela
sh ./install-macos.sh
~/.vela/bin/vela doctor

Linux / shell

git clone https://github.com/Marcus-AI4SS/VELA.git vela
cd vela
sh ./install.sh --bootstrap-tools
vela doctor

项目	Windows	macOS / Linux
安装入口	`install.ps1`、`vela.ps1`	`install-macos.sh` / `install.sh`、`~/.vela/bin/vela`
Shell	PowerShell 7 优先	zsh/bash
工具安装	可提示 winget 或手动安装	可提示 Homebrew 或手动安装
权限注意	PowerShell 执行策略、路径空格、Windows Defender	Gatekeeper、可执行权限、Homebrew 路径

组件	作用	状态说明
Git	clone、更新、回滚、提交、发布	推荐安装
Python 3.13+	运行 CLI、schema checks、validators	核心依赖
PowerShell 7 / POSIX shell	运行跨平台安装脚本	Windows/macOS/Linux 分开处理
ripgrep	快速搜索、路径审计、隐私扫描	推荐安装
MCP servers	学术检索、浏览器调试、社交证据和代码索引等接口	按任务启用
Codex plugins	GitHub、Superpowers、文档、表格、演示等增强层	按任务启用

依赖类型	代表项	VELA 怎么处理
核心依赖	Git、Python、shell、VELA CLI、schemas、validators	安装脚本和 `vela doctor` 会重点检查。
推荐依赖	ripgrep、GitHub CLI、Node.js、PowerShell 7、Homebrew/winget	缺失时提示，不伪装成已安装。
可选集成	Zotero、Obsidian、MCP servers、Codex plugins、外部记忆服务模式、CodeGraph	只提供 profile、doctor 检查、adoption review 和使用说明；外部记忆服务默认不安装、不常驻。

项目结构

my-research-project/
  AGENTS.md
  materials/
  evidence/
  claims/
  methods/
  deliverables/
  handoffs/
  logs/
  .codex/
  .vela/context.json

目录	用途
`materials/`	原始材料：PDF、网页、截图、数据、访谈、链接、笔记。
`evidence/`	已核验材料：有来源、访问时间、状态、权利或伦理说明。
`claims/`	候选主张、已支持主张、证据支持关系。
`methods/`	方法假设、编码规则、分析计划、复现说明。
`deliverables/`	报告、论文、图表、PPT、提交包、复盘。
`handoffs/`	给 Codex 或协作者的有边界任务说明。
`logs/`	运行记录、质量门、doctor、validation、修复记录。

工作流入口

先看任务路线，再看 skill 名称。一条路线可以组合多个 skill、插件和 MCP。

用户任务 -> route 判断 -> skill 组合 -> 插件/MCP 按需开启 -> schema/validator 检查 -> logs/handoff/context 更新

任务	路线	主要能力	边界
不确定该走哪条研究路线	`general-research`	研究设计、引用核验、基础导出	用于初始分流，不替代具体路线
检查 VELA、skills、profiles、MCP、插件和配置	`stack-governance`	运行层治理、外部能力审查	管环境，不管具体研究结论
安装、修复、更新运行层	`environment-ops`	runtime 检查、profile 应用、配置漂移检查	不静默改用户级配置
项目文件夹混乱	`project-folder-hygiene`	文件盘点、临时文件分类、交接前整理	不静默删除原始材料、数据、PDF、证据
文献证据总控	`evidence-based-literature-workflow`	结构性阅读、证据核验、引用支撑	发现文献不等于正式引用
文献综述和研究版图	`literature-review`	主题检索、引用扩展、综述表	综述写作前仍需引用核验
全文获取	`reference-fulltext-acquisition`	DOI/OA 查询、PDF 获取、缺失清单	只处理合法可访问全文
单篇论文评审	`single-paper-review`	贡献、方法、证据、写作问题评估	不能用未核验文献做正式引用
量化实证、文本、网络、计算社科	`empirical-quant` / `text-corpus` / `network-analysis` / `computational-social-science`	研究设计、数据发现、模型、语料、网络、复现	工具只是执行器，证据和复现包才是交付依据
科研图、结果表和汇报	`research-figure-design` / `research-presentation`	机制图、概念图、数据图、PPT、网页演示	不能编造数据或统计标注
正文写作、审稿回复、投稿包	`writing-export` / `social-science-submission-package`	写作、引用捕获、审稿回复、DOCX/LaTeX、版本冻结	写作质量检查不能改变事实
平台材料和数字痕迹案例	`social-platform-case`	浏览器可见材料、来源台账、平台伦理	不打包需要平台账号和登录态的专用后端

Skills、插件和 MCP

42 个 active skills

覆盖总控、文献与审稿、计算社科与分析、写作与导出、图表与演示、运行时 helper、知识沉淀与平台材料。

插件层

原生 Browser、Chrome、Computer Use、GitHub、Superpowers、Zotero、Scite、Google Drive、Documents、Presentations、Spreadsheets 等按任务启用。

MCP 层

OpenAlex、Semantic Scholar、Google Scholar、paper-search、Chrome DevTools、CodeGraph 等是传感器和接口，不是事实源；普通网页、本机桌面和登录态浏览器优先用原生 Browser、Chrome 和 Computer Use；Zotero 走官方插件，不作为默认 MCP。

层	代表项	边界
Skills	`research-autopilot`、`citation-verifier`、`quant-analysis`、`manuscript-writing-studio`、`project-folder-hygiene`	具体任务能力，必须受路线和质量门约束。
插件	`github`、`superpowers`、`hugging-face`、`scite`、`documents`、`presentations`	增强层，不能替代 VELA 源规则、schema、validator 和 Git 提交。
MCP	`openalex-mcp`、`semantic-scholar-mcp`、`google-scholar-mcp`、`paper-search-mcp`、`chrome-devtools`、`codegraph`	只在任务需要时打开；工具返回结果仍需进入证据或检查链。平台账号、cookies 或登录态相关后端不随公开包发布。

Skill 角色	说明	例子
入口	接收用户任务，判断任务路线。	`research-autopilot`
主控	组织多步流程、分配子任务、决定检查点。	`evidence-based-literature-workflow`、`research-team-orchestrator`、`vela-runtime-manager`
执行	完成具体研究动作。	`citation-verifier`、`quant-analysis`、`text-analysis`、`research-figure-studio`
helper	支持定位、清理、浏览器操作、运行环境判断。	`project-folder-hygiene`、`skill-vetter`、`local-cloud-router`、`playwright`

MCP 启动策略	含义
原生优先	Browser、Chrome、Computer Use 先处理普通网页、登录态浏览器和本机可视操作。
默认不全开	新任务不会预启动所有 stdio MCP，避免慢启动和无关工具污染。
按路线开启	文献任务优先学术检索和官方 Zotero 插件；网页材料先用原生 Browser/Chrome；代码审查才用 CodeGraph。
先说明再调用	工具调用前应知道它解决什么问题、读取什么数据、会不会写文件。
输出要落地	有价值的结果应进入 materials、evidence、logs 或 handoff。

记忆管理

VELA 的记忆不是全量聊天仓库。它让系统记住稳定偏好、常见路线、失败原因和项目经验，同时防止临时判断变成全局规则。

记忆层	存什么	默认去向	能否自动升级为长期规则
临时会话记忆	本轮任务路径、失败命令、网页状态、短期上下文	过期丢弃	不能
项目记忆	项目事实、阶段、材料边界、证据链	项目文件或长期笔记	不能
私有偏好	用户协作偏好、语言偏好、入口提示	用户本机记忆	不能
流程记忆	可复用流程、工具顺序、质量清单	skill 或文档候选	必须检查
控制记忆	影响总路由、权限、验证逻辑的底层规则	governance kernel 候选	必须严格检查

硬边界：不默认导入完整聊天记录；不默认做 LLM 压缩和自动上下文注入；不把 secrets、tokens、cookies、账号细节或验证码状态写入记忆；不让外部记忆服务或 CodeGraph 成为源规则。

记忆落点	保存什么	什么时候看
项目文件	项目事实、证据、阶段、方法、交付物。	继续项目、交接项目、复盘项目。
运行日志	命令、检查、失败、修复、handoff、validator 报告。	排错、回滚、审计。
本地记忆状态报告	用户确认过的偏好、常见路径、重复经验候选。	新会话只获得可审计线索，不自动改规则。
线程记忆 intake 报告	已完成任务里的简短摘要、证据指针、复用步骤、风险说明和建议落点。	通过 `thread_memory_intake_report.v1` 校验；不导入完整聊天、凭据、浏览器状态或私有文件。
演化待办	候选规则、候选 skill、候选 schema、候选自动化。	周期性治理和版本提交。

自动化与自我演化

VELA 的自动化像巡检和对账系统：发现问题、写报告、生成候选改进，然后通过检查和提交进入长期规则。

命令或能力	用途	边界
`vela doctor`	检查本机工具、运行层和可选集成状态	只检查和提示，不冒充安装成功
`vela runtime install`	安装或更新 VELA 运行层	不复制用户私有数据
`vela validate`	检查项目结构、schema、context 和质量门	不替用户做研究判断
`vela privacy scan`	查找隐私、路径、账号、密钥、缓存等风险	发现风险后由用户确认处理
`envctl route explain`	解释任务应该走哪条路线	只给路线建议，不替代用户确认
`envctl validate stack`	检查技能、插件、MCP、配置一致性	不静默改用户配置
`envctl memory reconcile`	对账记忆、规则和运行态状态	候选记忆必须经过复核

巡检类型	目的	输出
环境巡检	查工具缺口、profile 漂移、MCP 状态、schema 变化、运行层安装状态。	doctor report、stack validation report。
项目巡检	查目录结构、证据链、handoff、隐私风险、交付物完整性。	validation report、privacy report、context repair。
演化巡检	查哪些经验可复用，哪些规则冲突，哪些旧入口应 retired。	evolution backlog、route conflict report、candidate patch。

常用命令

目的	命令
查看 VELA CLI	`vela --help`
检查环境	`vela doctor`
初始化项目	`vela init <project>`
创建 handoff	`vela handoff new --template claim-check`
检查 handoff	`vela handoff lint handoffs/H001.yaml`
修复项目 context	`vela validate <project> --repair-context`
隐私扫描	`vela privacy scan <project>`
解释路线	`python -m skills.scripts.envctl route explain "你的任务" --summary`
七层检查	`python -m skills.scripts.envctl validate environment-layers --summary`
记忆对账	`python -m skills.scripts.envctl memory reconcile --summary`

最小使用路径

clone 或下载 VELA。
按系统运行安装脚本。
运行 vela doctor 看工具缺口。
用 vela init <project> 初始化研究项目。
把原始材料放入 materials/，核验后提升到 evidence/。
用 handoff 给 Codex 准备小任务，再运行 validate 和 privacy scan。

VELA 不做什么

不替用户判断研究结论是否成立。
不把未核验材料升级为证据。
不默认执行 codex exec。
不复制 cookies、tokens、密钥、验证码状态、浏览器缓存。
不默认安装或启动所有 MCP。
不把非公开个人定制模块作为公开研究工作流的一部分。

VELA 研究工作流环境