编译 · 测试 · 开发教程

语言：中文 | English

面向想要本地运行、修改或贡献 FSAR 的开发者。

1. 环境准备

依赖	版本	说明
Python	3.12+	项目声明最低 3.11，但 Computer Use 依赖 `cua` 要求 `>=3.12,<3.14`，所以实际请用 3.12 或 3.13
Node.js	18+	构建前端 UI

按平台用包管理器安装即可：

# macOS (Homebrew)
brew install python@3.12 node
# Debian / Ubuntu
sudo apt install python3.12 python3.12-venv nodejs
# Windows: 从 python.org / nodejs.org 下载安装器

2. 获取代码并安装依赖

git clone https://github.com/sildo466/FSAR.git
cd FSAR
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

虚拟环境可选创建——也可以直接把依赖装进系统 Python。

后端（Python）与前端（React）是两个独立产物，没有单一的 "build" 步骤。

3. 启动

平台	命令
Windows	`start.bat`
Linux / macOS	`./start.sh`（或 `make dev`）

启动脚本会：

首次运行自动 npm install 并 npm run build 构建前端（之后跳过安装、秒级重建）；
启动后端（src.server.ws_server），监听 http://127.0.0.1:8765；
打开浏览器；若未自动打开，手动访问上面的地址。

make 常用目标（见 Makefile）：

目标	作用
`make dev`	运行 `start.sh`（完整启动器）
`make build`	仅构建前端
`make stop`	停止运行中的后端
`make test`	运行 `pytest tests/ -x -q`
`make clean`	清理构建产物与缓存

终端 TUI（无浏览器）

fsar                # 或 python -m src.cli.tui;需 pip install -e .

全屏 Textual TUI,与 WebUI 共用同一套 ~/.fsar/ 数据、内置工具与安全闸门。底部状态栏实时显示模式与上下文用量,启动时打印角色卡 / 档位 / 模型 / CWD 摘要;CWD 默认绑定为沙盒(显式配置过的沙盒不会被覆盖)。斜杠命令:/model /character /user /tier /effort /compact /new /resume /permissions /use <skill>;/exit 退出。python main.py 保留为遗留 REPL。

停止

平台	命令
Windows	`taskkill /FI "WINDOWTITLE eq FSAR Backend*" /T /F`
Linux / macOS	`pkill -f "src.server.ws_server"`

macOS 额外步骤（仅 Computer Use 需要）

打开 系统设置 → 隐私与安全性 → 辅助功能，授权你的终端与 Python。仅在使用桌面操作工具（cu_screenshot/cu_click/cu_type/cu_keypress）时需要。

4. 前端开发

前端是 React + TypeScript（Vite），位于 frontend/；构建产物由后端在浏览器中于 127.0.0.1:8765 提供。

cd frontend
npm install
npm run build        # 产物供后端静态托管

frontend/src/ — React 界面：components/chat（聊天）、components/onboarding（首次使用向导）、clients/（WebSocket 与 HTTP 客户端）。
frontend/src-tauri/ — 仓库里的一个 Tauri 壳（Rust），但不构建也不使用；界面在浏览器中运行。
组件测试用 Vitest/Testing Library（*.test.tsx）。

只有修改 TS/React 代码时才需要重新构建前端。

5. 测试

测试套件设计为离线运行：不联网、不连真实 MCP 服务器、不调真实 LLM。tests/server/conftest.py 通过桩替换引擎副作用，强制服务端测试离线。

# 完整套件（含 live-MCP / e2e 用例）
pytest tests/ -q

# CI 使用的离线单元门（也是改动安全代码后最该跑的子集）
pytest tests/sandbox tests/security tests/skills tests/utils tests/server -q

# 单个文件 / 单个用例
pytest tests/sandbox/test_hardline.py -q
pytest tests/sandbox/test_paths.py::test_normalize_nfkc -q

测试目录组织：

tests/
  sandbox/    hardline、路径归一化、敏感路径、工作区门禁
  security/   WebSocket 鉴权
  skills/     技能运行时、出口控制、密钥、审阅门禁
  utils/      LLM 工厂出口
  server/     HTTP/WS 端点（离线桩）

约定：

新功能 / 修复 bug 要附带测试。
任何改动 src/sandbox/ 或 src/security/ 的 PR，必须在 tests/sandbox/ 或 tests/security/ 同时覆盖"放行"与"拦截"两条路径。
新测试保持离线；确需真实服务的用例要加守卫，确保离线门常绿。

6. 持续集成

.github/workflows/ci.yml 在 push / PR 时：

ubuntu-latest + Python 3.12（cua 要求 >=3.12,<3.14）；
pip install -r requirements.txt；
运行离线单元门 pytest tests/sandbox tests/security tests/skills tests/utils tests/server -q。

依赖范围里有上限约束（如 mcp>=1.0,<2、google-genai>=0.3,<2），避免 CI 拉到与代码不兼容的新大版本。升级依赖时请同步更新这些上限并跑一遍测试。

7. 代码规范

Python 3.12+，跟随上下文的类型标注。
注释与标识符用英文；注释要少，只解释非显而易见的意图。
不要写 "fix bug"、"xxx 修改" 之类的注释——历史属于 git 与 CHANGELOG。
没有强制格式化工具；与相邻代码保持一致即是规则。
改动要外科手术式：只动该动的，不在同一提交里重构/重排无关代码。
运行时配置走 fsar.yaml（见配置详解），不要硬编码用户路径或密钥。

8. 数据与运行目录

一切关于用户的记忆都在 ~/.fsar/：

~/.fsar/config/        yaml 配置
~/.fsar/data/
  memory.db            对话、决策、用户画像、经验
  chroma/              语义嵌入
  llm_cache.db        供应商 prompt 缓存记账
  tts_cache.db         TTS 音频缓存
  logs/                滚动日志 + audit.log（审计）

删除 ~/.fsar/ 即彻底重置。

9. 提交与协作

使用 Conventional Commits：feat(social): ...、fix(security): ...、docs: ...。
主题大的改动先开 issue 讨论方向；小修复可直接 PR。
PR 保持单一关注点，说明"改了什么 / 为什么"，并关联 issue。
报告安全漏洞不要用公开 issue/PR，请走 SECURITY.md 的私密流程。

入门

配置与开发

模块参考

核心运行时

记忆与数据

安全与执行

界面与扩展