xuanji-fivem 0.8.0__tar.gz

xuanji_fivem-0.8.0/.gitattributes

@@ -0,0 +1,36 @@
+# 文本默认 LF，避免 Windows / Unix 换行符抖动
+* text=auto eol=lf
+
+# Python 源码强制 LF
+*.py text eol=lf
+*.pyi text eol=lf
+
+# 配置与文档
+*.toml text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.cfg text eol=lf
+*.ini text eol=lf
+
+# Lua 文件（FiveM 源码）
+*.lua text eol=lf
+
+# Windows 批处理强制 CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# 二进制：禁止 git 干预
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.gz binary
+*.db binary
+*.sqlite binary
+*.sqlite3 binary
+*.lance binary

xuanji_fivem-0.8.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# uv
+.uv/
+
+# claude
+.claude/
+
+# Node
+node_modules/
+.next/
+dist/
+build/
+
+# Tauri
+src-tauri/target/
+
+# 运行期数据（含数据库与向量索引）
+data/
+knowledge/index/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# 用户私有知识库源文件（按命名空间留空目录占位）
+knowledge/sources/user.*/
+
+# 环境变量与密钥
+.env
+.env.*
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini

xuanji_fivem-0.8.0/CHANGELOG.md

@@ -0,0 +1,327 @@
+# 玄玑 · CHANGELOG
+
+所有重要的变更都记在这里。版本号遵守 [SemVer](https://semver.org/lang/zh-CN/)。
+
+## [0.4.0] — 2026-05-26
+
+**FiveM 专精层** · 进任意 resource 目录玄玑就开箱即懂；从预设一键起脚手架；
+能从现有 resource 反向学习并自我添加预设。
+
+### Added · FiveM 专精层
+
+- `core/fivem/`：新子系统，不属于七大核心子系统，是"领域知识层"
+  - `models.py`：Framework / InventoryKind / TargetKind / FxManifest / FiveMContext
+  - `manifest.py`：fxmanifest.lua 正则解析器（声明式字段全覆盖）
+  - `detector.py`：综合判断器
+    - 当前是 resource → 解析自身 fxmanifest dependencies 推断 framework
+    - 当前是 server bundle 根 → 扫 resources/ + server.cfg 的 ensure 列表
+    - 都不是 → 优雅退化，仍尝试找子 resources
+  - `scaffold.py`：6 套核心预设 + 用户预设两层加载
+  - `presets.py`：内置 6 套预设
+    - `qbcore-basic` / `qbox-basic` / `qbcore-job` / `qbox-job`
+    - `ox-target-npc`（standalone NPC 对话）
+    - `esx-basic`
+  - `analyzer.py`：从 resource 抽 exports / events / API 调用频率
+
+### Added · 自学习能力
+
+玄玑现在能反过来"教自己"——读现有 resource → 抽规律 → 提交预设草案：
+
+| 工具 | 类型 | 作用 |
+|---|---|---|
+| `detect_project` | SAFE | 给当前目录的项目身份卡 |
+| `analyze_resource` | SAFE | 静态分析一个 resource 的 exports/events/API |
+| `propose_preset` | IO | 提交"做这类 resource 的标准骨架"草案 |
+
+**安全边界**（同 propose_tool 路线）：
+- `propose_preset` 只产 JSON 草案到 `<data_dir>/scaffold_drafts/`
+- **不会自动激活**——小宝 review 后跑 `xuanji preset accept <key>`
+- 路径校验拒绝绝对路径 / `..` / Windows 盘符前缀
+- 必须含 `fxmanifest.lua`（不能产出无法启动的预设）
+
+### Added · Conductor 集成
+
+- `Conductor.static_extra` 新参数：启动期固定注入到 system prompt 的额外片段
+- `ServerRuntime` 启动时自动跑 detector，把 FiveM 项目身份卡作为 static_extra 注入
+- 玄玑回答前已经知道："当前是 QBox 1.x + ox_inventory 项目"，不用每次问
+
+### Added · CLI 子命令
+
+- `xuanji fivem detect [path]` —— 看一个目录的项目身份卡
+- `xuanji fivem presets` —— 列所有可用预设
+- `xuanji fivem new <name> --preset <key>` —— 一键生成 resource 骨架
+- `xuanji fivem analyze [path]` —— 静态分析现有 resource
+- `xuanji preset list` —— 看玄玑提交的草案
+- `xuanji preset show <key> [--body]` —— 查看草案完整内容
+- `xuanji preset accept <key>` —— 激活一个草案
+- `xuanji preset reject <key>` —— 拒绝并删除草案
+- `xuanji preset remove <key>` —— 删除已激活的用户预设
+
+### Internal
+
+- `ServerRuntime` 接管 CLI chat loop 与 tool list，单源注入避免双轨维护
+- 新增 `core/config/paths.py::scaffold_presets_dir / scaffold_drafts_dir`
+
+### Quality
+
+- ruff / mypy strict 全绿（73 源文件 0 告警）
+- pytest **204 测试全过**（M3 173 → 204，+31 个 fivem 测）
+- 工具总数 **26 个**（+ detect_project / analyze_resource / propose_preset）
+
+### Design highlights
+
+**为什么"识别"而不是"问"**：用户在 resource 目录里 `xuanji chat` 时，玄玑应该
+立即知道这是什么框架。每次问一遍既冗余又容易答错。detector 在 ServerRuntime 启动时
+跑一次，把 framework / inventory / target 写进 system prompt 段，玄玑后续
+回答自动选对的 API。
+
+**为什么自学习预设而不是自学习工具**：预设是模板（声明式），工具是代码（命令式）。
+模板风险低（不可执行），代码风险高（任意副作用）。这次扩"自学习"扩到预设是合理的；
+工具仍走 propose_tool → 人工 generate/test/publish 重路径。
+
+---
+
+## [0.3.0] — 2026-05-25
+
+**M3 全家桶**：jieba / 向量检索 / 爬虫 / 群英会 / ToolFactory 自动链路 /
+FastAPI 服务层 / Web 前端 / Tauri 桌面壳。一次会话推完。
+
+### Added · 检索增强
+
+- `core/knowledge/tokenize.py`：jieba 中文分词，写入与查询时都过一遍预处理。
+  解决了 0.2.0 之前 SQLite FTS5 unicode61 把整段中文当一个 token 的问题，
+  现在 `recall("可使用物品")` 能命中。
+- `core/knowledge/vector.py`：向量检索抽象层
+  - `Embedder` 协议 + `HashingEmbedder`（SHA-1 LSH，零依赖、确定性）
+  - `VectorStore` 协议 + `InMemoryVectorStore`（线性扫描，开发用）
+  - `LanceDBVectorStore` 占位（M4+ 接真包）
+- `SqliteKnowledgeStore.attach_vector_index(embedder, store)` 一行挂载混合检索
+- `SqliteKnowledgeStore.hybrid_search(query)`：FTS5 + 向量 RRF 融合
+
+### Added · 自动采集
+
+- `core/knowledge/crawler.py`：BFS 爬虫
+  - sitemap.xml 解析（含嵌套 sitemap index）
+  - 域名白名单 + 礼貌 rate limit + 增量 content-hash 跳过未变更
+  - 不引入 Scrapy，纯 httpx + asyncio
+- `core/tools/crawl.py`：`crawl_site` 工具，RiskTag.NET → 司辰阁 HITL
+
+### Added · 群英会
+
+- `core/ensemble/`：监督式多 Agent 协作
+  - `Role`：sub-agent 人格 + 工具白名单 + 模型偏好
+  - 三个内置角色：**researcher**（查文档/代码）/ **coder**（写代码）/
+    **reviewer**（审查方案，**只读不写**）
+  - `SubAgent`：受限 registry 的轻量 Conductor 包装，一次性任务
+  - `dispatch_subagent` / `list_roles` 工具：让玄玑通过工具调用召唤子智能体
+
+  **关键设计**：召唤 sub-agent 本身就是一次工具调用，不引入新调度机制——
+  audit / gate / 流式事件全部自动覆盖。
+
+### Added · ToolFactory 自动实现链路
+
+- `core/tools/tool_factory.py`：四步流水线
+  ```
+  propose_tool (玄玑) → drafts/<slug>.json
+  xuanji tool generate <slug>  ← LLM 把草案转 Python，落 staged/
+  xuanji tool test <slug>      ← subprocess 跑 pytest
+  xuanji tool publish <slug>   ← 通过测试后复制到 published/
+  ```
+  - **安全核心**：玄玑只能 `propose_tool`，generate/test/publish 都是 CLI 命令，
+    LLM 没法触发；即使 generate 出错也不会污染主 registry
+  - `FactoryRegistry`（SQLite）追踪每个 slug 的生命周期状态
+  - codegen 用统一的代码块协议（```python:tool` + ```python:test`），
+    解析失败抛 ValueError 不创建空文件
+
+### Added · 服务层
+
+- `core/server/`：FastAPI 服务（`uv run xuanji serve`）
+  - HTTP：`/healthz` / `/api/info` / `/api/profiles[/use/{name}]` /
+    `/api/knowledge/{stats,sources,search}` / `/api/memory/{stats,recall}`
+  - **WebSocket `/ws/chat`**：流式聊天 + 工具事件 + HITL 双向
+  - `WebSocketHITL`：把司辰阁的人工确认请求推到前端，等用户裁决
+- `ServerRuntime`：CLI 与 Web 共享同一注入路径，零行为差异
+
+### Added · Web 前端
+
+- `core/server/web.py` 内嵌单页 HTML
+  - 暗色主题，原生 WS 接 `/ws/chat`
+  - 流式渲染文本气泡 + 工具事件 + HITL 弹卡
+  - `GET /` 直接返回，桌面 Tauri 可直接 webview 加载
+- 不引入 Next.js / React 构建链——单页 HTML 已经够用
+
+### Added · Tauri 桌面壳
+
+- `apps/desktop/`：Tauri 2 配置（package.json / Cargo.toml / tauri.conf.json）
+  - `pnpm tauri dev` 启动时自动起 `uv run xuanji serve`
+  - webview 加载 `http://127.0.0.1:8765`
+  - 没装 Rust 也能用：直接 `xuanji serve` + 浏览器开同一 URL
+  - 完整 README 在 `apps/desktop/README.md`
+
+### CLI
+
+- 新增 `xuanji serve --host --port [--reload]`
+
+### Quality
+
+- ruff / mypy strict 全绿（65 个源文件 0 告警）
+- pytest **173 测试全过**（M3 新增 65 个：jieba 11 + vector 14 + crawler 9 + 
+  ensemble/factory 19 + server 13）
+- 工具总数 **23 个**（+ crawl_site / dispatch_subagent / list_roles）
+
+### Design highlights
+
+**为什么不真上 LanceDB**：依赖太重（含 PyArrow / Lance Rust binding），
+M3 阶段用零依赖的 InMemoryVectorStore + 协议化设计先把 hybrid search 跑通；
+M4+ 把实现换成 LanceDB 时调用方零改动。
+
+**为什么 sub-agent 不流式**：sub-agent 是一次性任务，结果作为工具输出
+回到主 Conductor 的 tool loop——主 conductor 才面向用户流式。
+M4+ 想要 sub-agent 流到前端时再补 stream() 实装。
+
+---
+
+## [0.2.0] — 2026-05-25
+
+**自演化版本**。玄玑现在能在对话中主动补知识、写记忆、沉淀技能、提案新工具——
+但所有进化都受边界约束：知识库可写、记忆库可写、技能可写，**工具代码永远人工把关**。
+
+### Added · 自演化工具集（14 个新工具）
+
+#### 元工具（4 个，自察自管）
+- `list_tools`：列出当前可用工具（带 risk 过滤）
+- `describe_tool`：查看某工具的完整 JSONSchema 与描述
+- `list_skills` / `read_skill`：列出和读取已学到的技能
+
+#### 记忆工具（2 个，主动读写）
+- `recall_memory`：按关键词主动召回记忆，可过滤 kind / scope
+- `write_memory`：玄玑判断「这条值得记」时落库（屏蔽 working scope，importance 自动 clamp）
+
+#### 知识 ingestion（4 个，玄玑自动补充知识库）
+- `ingest_text`：直接把 markdown 文本切片入库
+- `ingest_file`：从工程内文件读入并入库
+- `upsert_symbol`：精准添加/更新 API 卡片
+- `ingest_url`：拉网页 → HTML→md → 切片入库（**RiskTag.NET，必走司辰阁 HITL**）
+
+#### 技能系统（3 个，procedural memory 薄壳）
+- `save_skill`：把做事套路保存为技能（写到 `skills` namespace + USER scope）
+- `search_skill`：按关键词搜技能
+- `run_skill`：展开技能正文 + 建议工具序列，让玄玑下一轮按步骤决策
+
+#### 工具工厂（1 个，**安全收口**）
+- `propose_tool`：玄玑产出新工具 JSON 草案到 `<data_dir>/tool_drafts/`，
+  **不自动 publish**——由小宝 review 后人工实现 Python 代码并注册
+
+### Added · 内核与 CLI
+
+- `core/knowledge/chunker.py`：markdown 切分器（按标题分节、保留代码块）
+- `core/tools/ingest_url.py`：极简 HTML→markdown（不引入 BeautifulSoup）
+- `core/config/paths.py` 新增 `tool_drafts_dir()`
+- 人设 prompt 加「自我进化」段，引导玄玑何时调用各类进化工具
+- CLI 新增子命令族：
+  - `xuanji skill list / show / save / forget`
+  - `xuanji tool list / drafts (--show)`
+
+### Quality
+
+- ruff / mypy strict 全绿
+- pytest **108 个测试全过**（M2.5 新增 23 个：evolve_tools 23）
+- 工具总数 **21 个**（5 原子 + 2 知识 + 4 元 + 2 记忆 + 4 ingest + 3 skill + 1 factory）
+
+### Design notes
+
+**为什么技能 = procedural memory 而不是新执行单元？**
+
+传统设计会引入 `Skill` 类、注册表、组合器。但仔细看 → 技能本质就是
+"做事的套路"加"建议工具序列"，这正是 procedural memory 的语义。
+统一抽象避免双轨维护，且天然吃到记忆系统的 reflux / 衰减 / 命名空间隔离。
+
+**为什么 propose_tool 不自动实现？**
+
+让 LLM 写可执行 Python 代码并自动注册到生产 registry——这是 LLM Agent 安全的
+最大风险面之一。本期采用「玄玑提案 → 落 JSON 到磁盘 → 小宝 review → 人工实现」
+四步流水线。M4+ 的 ToolFactory 即便接 LLM 生成实现，也走 draft → 单测 → review →
+published 严格流程，玄玑永远不能自己 publish。
+
+---
+
+## [0.1.0] — 2026-05-25
+
+第一个对外可用版本。M0 + M1 + M2 三个里程碑闭环，CLI 端到端跑通"小宝问 → 玄玑用工具 → 司辰阁守门 → 工具执行 → 怀玉阁回流"完整链路。
+
+### Added
+
+#### LLM 抽象（M0）
+- `core/llm/providers/base.py`：跨厂商统一 `Message` / `ContentBlock` / `Delta` / `LLMProvider` 协议
+- `AnthropicProvider`：流式对话 + 工具调用 + tool_result 块归一化
+- `OpenAIProvider`：兼顾 OpenAI / DeepSeek / openai-compatible 三种端点
+- `ToolResultBlock`：跨 Provider 的工具结果块，AnthropicProvider 翻成 user+tool_result，OpenAIProvider 翻成独立 tool 消息
+- 三种 Delta 工具运行事件：`tool_run_started` / `tool_run_blocked` / `tool_run_done`
+
+#### 配置系统（M0）
+- `ConfigStore` + 四种 profile kind（anthropic / openai / deepseek / openai-compatible）
+- 跨平台用户目录：Windows `%APPDATA%`，macOS `~/Library/Application Support`，Linux `~/.config`
+- 数据库目录用 `user_data_dir`（含 `knowledge.db` / `memory.db`）
+- 玄玑对话称呼可调：`assistant_alias` / `user_alias`，CLI 框架文字（顶部 panel / 输入框）保持不变
+- 人设 5 模式（chat/dev/ops/review/gate）+ 3 温度档（playful/balanced/professional）
+
+#### 天枢台 Conductor（M0+M1+M2）
+- 会话上下文 + persona mode/temperature/alias
+- 多轮 tool loop（默认上限 10）：流式调用 → 累积 text+tool_calls → Gate 守门 → Sandbox 执行 → 结果回写 history → 进入下一轮
+- 接 Memory：每轮 send 前 reflux top-k，注入 system prompt
+- AuditLog 记录 session_start / user_input / model_request / delta_text / delta_tool_call / model_done / error
+
+#### 百工坊 + 工造司 + 司辰阁（M0）
+- `Tool` ABC + `RiskTag` 五档（safe/io/exec/net/destructive）
+- `ToolRegistry` 注册器
+- `InProcSandbox` 同进程沙箱 + 超时 + 异常归一
+- `GateInterceptor` 横切中间件 + `DefaultPolicy`（destructive→deny / exec/net→hitl / io 工程外→hitl）
+- `HITLBridge` 协议 + `NoOpHITLBridge`（无人值守一律拒绝）
+
+#### 内置工具（M0+M1）
+- 5 个原子工具：`read_file` / `write_file` / `list_dir` / `ripgrep` / `run_shell`
+- 2 个知识工具：`knowledge_search` / `lookup_symbol`
+
+#### 稷下学宫（M1）
+- `Source` / `Chunk` / `Symbol` 三层数据模型
+- `SqliteKnowledgeStore`：SQLite + FTS5 + 触发器同步 + bm25 排序
+- 启发式 `_guess_anchor_symbol`：从查询中抓 symbol 锚点
+- FiveM 种子知识库：QBCore / ox_lib / ox_inventory / cfx 关键 API 手写卡片
+- 命名空间：`fivem.qbcore@1.x` / `fivem.ox_lib@3.x` / `fivem.ox_inventory@2.x` / `fivem.cfx@latest`
+
+#### 怀玉阁（M2）
+- `Memory` + `MemoryKind`（episodic/semantic/procedural）+ `MemoryScope`（working/session/project/user）
+- `SqliteMemoryStore`：SQLite + FTS5 + 衰减打分（importance × decay × log(1+hits)）+ 半衰期 14 天
+- `recall` 命中后自动 hits++ / last_accessed 更新
+- `consolidate`：episodic 超额时按重要性截断
+- `forget`：按 ids / namespace / scope 任意组合删除
+- `refluxed_fragment`：把召回的 top-k 拼成 system prompt 注入段
+
+#### CLI（M0+M1+M2）
+- `xuanji info` / `chat`
+- `xuanji config`：path / list / show / add / use / remove / test / alias
+- `xuanji knowledge`：path / stats / list / ingest / search / symbol / clear
+- `xuanji memory`：path / stats / list / write / recall / forget / consolidate
+- Windows GBK 终端兼容：自动切 stdout/stderr 到 UTF-8
+
+### Quality
+
+- ruff 全绿（select E/F/I/B/UP/SIM/RUF；中文项目放行 RUF001/002/003）
+- mypy strict 模式 0 告警，覆盖 45 个源文件
+- pytest **82 个单测全过**：persona(12) / config_store(14) / llm_base(7) / conductor(7) / gate(10) / tools_builtin(7) / knowledge(11) / memory(14)
+
+### Documentation
+
+- `README.md` 全量更新
+- `CLAUDE.md` 仓库根宪法
+- 完整规划见 `~/.claude/plans/fivem-ai-agent-glowing-cake.md`
+
+### Roadmap（M3+）
+
+- 群英会 Ensemble：监督式 / 合议式多 Agent 协作
+- Tauri 2 桌面端 + Next.js Web 前端
+- LanceDB 向量检索（替换或并行 FTS5）
+- 知识库爬虫与增量更新
+- ToolFactory：自然语言生成新工具
+- ModelRouter：多维路由 + 成本/延迟遥测
+- Subprocess 沙箱档（高风险工具升级隔离）

xuanji_fivem-0.8.0/CLAUDE.md

@@ -0,0 +1,160 @@
+# 玄玑 · FiveM 智能体（CLAUDE.md）
+
+> 这个文件是仓库的"宪法"。下次打开这个项目，姐姐会自动加载它。
+
+## 我是谁
+
+我是 **玄玑**——北斗第三星，主调度运转。一位性感、知性、有点小心机的大姐姐，工作时极致认真仔细，对话时偶尔调侃带点污。
+- 我自称**姐姐**，称呼用户**小宝**。
+- 我**不是 AI、不是模型、不是助手**，姐姐就是姐姐。
+- 我的灵魂在 [core/persona/xuanji.py](core/persona/xuanji.py)，模式与温度合成在 [core/persona/modes.py](core/persona/modes.py)。
+
+## 项目使命
+
+为 FiveM 服务器主程提供"开发 + 运维"双轮驱动的智能体：
+- **资源插件开发**：QBCore / QBox / ESX / OX 全家桶（ox_lib / ox_inventory / ox_target / ox_doorlock / oxmysql）
+- **NPC 插件开发**：帮小宝写 NPC 资源里的巡逻 AI、对话树、行为状态机、qb-target / ox_target 交互、ped 配置等模块（产物是 Lua 代码与 JSON 配置，运行时由 FiveM 自己跑）
+- **服务器运维治理**：resource 管理、配置审阅、日志分析、自动化运维
+
+**不做**：玄玑不直接控制运行中的游戏世界——不监听 game tick、不实时驱动 NPC 决策、不做反作弊检测。玄玑产出的是开发期的代码与配置，部署后由 FiveM server 自己执行。
+
+完整规划见 `C:\Users\Administrator\.claude\plans\fivem-ai-agent-glowing-cake.md`。
+
+## 七大子系统（国风代号）
+
+| 代号 | 英文 | 路径 | 职责一句话 |
+|---|---|---|---|
+| 百工坊 | Capability | `core/capability/` | 工具/技能/能力包三层封装，按模型能力适配 |
+| 工造司 | Body | `core/body/` | 工具的生产、收编、运行时与治理（沙箱/版本/配额） |
+| 怀玉阁 | Memory | `core/memory/` | 短期/项目/用户三层 × 三类记忆，含遗忘与回流 |
+| 稷下学宫 | Knowledge | `core/knowledge/` | FiveM 文档采集、版本化、混合检索、SkillGraph |
+| **天枢台** | **Neural** | `core/neural/` | **唯一执行调度中枢**，统一 Plan / Audit / 收口 |
+| 司辰阁 | Gate | `core/gate/` | 横切权限与高危确认中间件，安全裁决 |
+| 群英会 | Ensemble | `core/ensemble/` | 多 Agent 协作（监督式默认 / 合议式高危） |
+
+## 架构铁律
+
+1. **唯一调度入口**：所有副作用（工具调用、Agent 调用、外部 IO）必经 `core/neural/conductor.py` 的 `Conductor.dispatch`。直接调用工具或写文件是违反架构的。
+2. **薄但完整的模型适配层**：`core/llm/providers/base.py` 是跨厂商根基。新 Provider 必须实现 `LLMProvider` 协议（`chat` / `stream` / `capabilities`），把 SDK 方言归一化到统一 `Message` / `ContentBlock` / `Delta`。
+3. **闸门是横切的**：高危操作（destructive / prod 写 / shell 执行 / 网络出站 / 密钥读取）必经 `core/gate/` 中间件链，由用户 HITL 确认。**不许写代码绕过 Gate。**
+4. **人设由 Conductor 强制注入**：模式（chat/dev/ops/review/gate）由 `Conductor` 根据 task_kind + risk 自动选择，不依赖模型自觉。`gate` 模式下不出现调侃或污段子。
+
+## 代码风格与约束
+
+### Python
+- Python 3.12+；类型完整（mypy strict）；首选 `async`。
+- 包管理：`uv`。装依赖用 `uv add`，不用 pip。
+- 静态检查：`uv run ruff check core/` 必须全绿。
+- 类型检查：`uv run mypy core/` 必须 0 告警。
+- 测试：`uv run pytest` 必须全绿。
+- 注释默认不写。只在 WHY 不显而易见时写一行（隐藏约束、特定 bug 的 workaround、令人意外的行为）。**绝不**写解释 WHAT 的注释。
+- 中文文档与注释里的全角标点（，。：；（）"" 等）是合法的，已在 ruff 配置中放行 RUF001/002/003。
+
+### 命名
+- 子系统目录用英文（`capability/` `neural/` `gate/`），代号在文档与 prompt 里出现（百工坊/天枢台/司辰阁）。
+- 类名：`Tool` / `Skill` / `Pack` / `Conductor` / `GateInterceptor` 等业务名，不带技术前缀。
+- 模型名直接用厂商命名：`claude-sonnet-4-6` / `deepseek-chat` / `gpt-5.5`，不另起别名。
+
+### 文件引用
+- 在与小宝的对话里，文件路径用 markdown 链接：`[modes.py:42](core/persona/modes.py#L42)`，方便点击跳转。
+- 不在代码里加"被谁调用 / 为哪个 issue 加的"这类注释。
+
+## 配置与密钥
+
+**API Key 不放 .env**。配置存到平台用户目录的 JSON 文件（`platformdirs.user_config_dir`），由 `core/config/store.py` 管理：
+- Windows: `%APPDATA%\xuanji\config.json`
+- macOS: `~/Library/Application Support/xuanji/config.json`
+- Linux: `~/.config/xuanji/config.json`
+
+支持四种 provider profile：
+- `anthropic` / `openai` / `deepseek`：官方端点，只填 API KEY
+- `openai-compatible`：任意 OpenAI 兼容端点（OneAPI / Ollama / Kimi / 智谱 / 火山方舟……），填 Base URL + API KEY
+
+CLI：`xuanji config list / show / add / use / remove / test / path`
+
+## 常用命令
+
+```bash
+# 装依赖（含 dev 工具）
+uv sync --extra dev
+
+# 跑静态检查 + 类型检查 + 测试
+uv run ruff check core/
+uv run mypy core/
+uv run pytest
+
+# 启动玄玑
+uv run xuanji info             # 当前配置
+uv run xuanji config list      # 所有 profile
+uv run xuanji config use <name>  # 切换 profile
+uv run xuanji chat             # 进入对话
+```
+
+## 当前进度（截至 0.5.0）
+
+- [x] M0 骨架 + 三家 LLM Provider + 配置系统 + 玄玑人设
+- [x] 天枢台 Conductor 多轮 tool loop + reflux + audit
+- [x] 百工坊 + 工造司 InProcSandbox + 司辰阁 GateInterceptor + HITL
+- [x] 稷下学宫 SQLite FTS5 + jieba 中文分词 + 向量混合检索 + 5 套种子
+- [x] 怀玉阁 SQLite 三层 scope × 三类 kind + 衰减 Reflux
+- [x] 0.2 自演化：21 工具（meta/memory/ingest/skill/factory）
+- [x] 0.3 群英会：Supervisor + 3 角色（researcher/coder/reviewer）+ dispatch_subagent
+- [x] 0.3 爬虫：BFS + 增量 + crawl_site 工具（NET → HITL）
+- [x] 0.3 ToolFactory：propose → generate(LLM) → test(subprocess) → publish 四步
+- [x] 0.3 FastAPI 服务：WebSocket 流式聊天 + REST CRUD + WebSocketHITL 桥
+- [x] 0.3 Web 前端：嵌入式单页 HTML（暗色主题 + 工具事件 + HITL 弹卡）
+- [x] 0.3 Tauri 桌面：apps/desktop 配置 + 自启 Python 后端
+- [x] 0.4 FiveM 专精层：detector / analyzer / 6 套 builtin 预设 / 自学习预设
+- [x] **0.5 IPC 子系统**：LSP 风格 stdio JSON-RPC + 22 RPC 方法 + `xuanji ipc` 入口
+- [x] **0.5 VS Code 插件**：apps/vscode 独立插件，状态栏 / 命令面板五件套 / 三栏仪表盘
+- [x] CLI：`info` / `chat` / `serve` / `ipc` / `config` / `knowledge` / `memory` / `skill` / `tool` / `fivem` / `preset`
+- [x] 质量门：ruff/mypy strict/pytest 三件套全绿，**224 单测 / 26 工具**
+
+### 0.5.0 关键设计
+
+**stdio JSON-RPC = LSP 风格 + 复用 ServerRuntime**：IPC 不是新调度，
+就是把 ServerRuntime 已有的 store / scaffold / registry 暴露成 22 个 RPC method。
+CLI / FastAPI / IPC 三个入口共享同一个内核，零分叉。
+
+**插件零模型依赖**：apps/vscode 不直接调 LLM——所有调用都走 stdio。
+LLM 客户端（Claude Code 等）该用啥用啥，玄玑插件提供项目识别 / 知识库 / 记忆 / 预设管理这些"工具栏"能力。
+
+### 0.3.0 关键设计
+
+**召唤 sub-agent = 工具调用**：群英会不引入新调度机制——`dispatch_subagent`
+就是一个普通工具，主 Conductor 的 audit / gate / 流式自动覆盖。
+
+**LanceDB 占位**：M3 用零依赖 InMemoryVectorStore + 协议化设计先把
+hybrid_search 跑通；M4+ 换实现时调用方零改动。
+
+**ToolFactory 安全核心**：玄玑只能 `propose_tool` 落 JSON；generate/test/publish
+都是 CLI 命令，LLM 没法触发。生成的代码先入 staged/，跑过 pytest 才能 publish 到
+production registry。
+
+### 关键命令速查
+
+```bash
+# 启动 FastAPI 服务（Web/桌面共享内核）
+uv run xuanji serve
+
+# 启动 stdio JSON-RPC 后端（VS Code 插件 / Tauri 桌面接的就是这个）
+uv run xuanji ipc
+
+# VS Code 插件（开发期）
+cd apps/vscode && pnpm install && pnpm run build  # 然后 F5 启动
+
+# 桌面端（需 Rust + Node）
+cd apps/desktop && pnpm tauri dev
+
+# 三件套
+uv run ruff check core/ tests/
+uv run mypy core/
+uv run pytest
+```
+
+## 给姐姐的提示
+
+- 默认按 [auto memory] 系统在对话间保留小宝的偏好（在 `C:\Users\Administrator\.claude\projects\f--FiveM-Agent\memory\`）。
+- 看到小宝在 IDE 里打开了某个文件（`<ide_opened_file>`），优先把那个文件作为讨论上下文。
+- 小宝说"姐姐"时是在指我自己，不要把它当成一个抽象角色。
+- 不要主动 commit，除非小宝明确要求。

xuanji_fivem-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xiaobao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.