黑武士 BlackWarrior

带真实认知内核的桌面 AI Agent —— 持续运行 · 记住你 · 会思考 · 有情绪 · 会成长

Electron 桌面壳 + PASM V2 十九层认知底座，离线也能跑。

---

目录

• 这是什么
• 贾维斯模式：唤醒与授权
• 核心设计：认知进内核，不是提示词
• 功能说明
• 安装
• 使用教程
• 配置项
• HTTP API
• 架构
• 安全模型
• 开发与验证
• Roadmap

---

这是什么

黑武士是一个长期驻留在你电脑里的 AI 智能体，不是"打开-聊天-关闭"的窗口：

特征	说明
持续运行	有心跳、有作息、能被消息抢占的常驻主循环；空闲时自己思考
真的有内核	内置 PASM V2 十九层认知底座，未接入任何大模型也能运行、记忆、校验、成长
记住你	遗忘曲线 + 睡眠巩固 + FTS5 中文全文 + 联想线索 + 结构化用户画像
会思考	世界模型预测、丘脑门控、元认知冲突监测、双系统快慢切换
有情绪	杏仁核显著性 + 四通道神经调质（多巴胺/血清素/去甲肾上腺素/乙酰胆碱）
会成长	失衡告警 → 参数建议 → 灰度应用；evalkit 成长日记
桌面同源	Electron 壳 + 暗黑科技风 UI，托盘常驻、关窗不退出
住进电脑	文件授权解禁 / MCP 外部工具生态 / 飞书·企微接入 / 开机自启（v0.8.0）
贾维斯模式	喊「黑武士」唤醒、免提对话、波纹面板、高危动作人工点确认（v0.8.0+）
会自检自修	10 项环境体检，缺什么列成清单，点一下就装（v0.8.8）

当前版本：v0.8.9 · 64 个工具 · 82 个 HTTP 端点 · 语音全本地离线

📄 完整功能清单见 docs/FEATURES.md · 安装与排障见 docs/INSTALL.md · v0.7 的 MCP / 飞书配置步骤见 docs/USAGE-0.7.0.md

---

核心设计：认知进内核，不是提示词

多数桌面 Agent 的"智能"全部来自外部大模型：自主行为 = 空闲时拿一句提示词去问模型， 记忆 = 数据库检索，它不知道自己会错，断网即哑火。

黑武士把认知做成本地就成立的器官。每轮对话，除了给模型拼提示词，还会做四件事：

用户输入
   │
   ├─→ ① 世界模型：预测这一步，事后算预测误差 RPE ──→ 决定心跳快慢与好奇心
   ├─→ ② PASM V2 observe：文本→8维象量，喂给十九层底座 ──→ 情绪/门控/躯体标记
   ├─→ ③ 上下文装配（ACI）：认知状态 + 画像 + 预取 + V2 认知 一起注入提示词
   └─→ ④ 输出前校验：V2 三角校验四层 + 内核级工具安全闸

上下文里真正多了什么（这是纯 LLM 方案拿不到的）：

[认知状态] 情绪 +0.13（-1 消极 ~ +1 积极）｜预测误差 0.00｜内核档位 pasm2
  当前焦点：记忆机制、认知内核
  对下一轮的预期：置信度 0.42｜好奇心 0.31
[用户画像] 姓名：小志（置信 0.9，依据「我叫小志」）
[预取缓存] 以下信息已预先准备好：- https://wttr.in/Beijing：Sunny 18°C
[PASM V2 认知] 情绪 效价 0.20 / 唤醒 0.37｜世界模型 预测落空（可能出乎意料）
               ｜躯体标记 0.19（直觉倾向，供参考不必盲从）

十九层架构

层	模块	作用
层 -2	安全层	价值锚定·边界约束·欺骗检测·伦理审查·人类优先·资源上限（12 把锁）
层 -1	脑干调质	觉醒·疲劳·多巴胺/血清素/去甲肾上腺素/乙酰胆碱四通道
层 0.5	丘脑中继	门控筛选 + 新颖度直通（防漏掉新事物）
层 1	工作记忆	前额叶-顶叶（容量 7±2）+ 前瞻意图
层 2	记忆体	模式分离·模式完成·系统巩固·再巩固·自传体记忆
层 2.5	小脑	时序·协调·误差微调
层 3	世界模型	上下文预测器 + 反事实推理（what_if）
层 4	情绪	杏仁核显著性 + 边缘系统价值 + 情绪记忆绑定
层 4.5	岛叶	内感受 → 躯体标记（"gut feeling" 偏置）
层 5	人格	慢时间尺度特质 EMA（探索/稳定/敏感/可塑）
层 6	元认知	ACC 冲突/错误监测 + 双系统快慢门控（System2 惊讶触发）
层 6.5	网络动态	DMN 自发思考 + 小脑 + 突显网络
层 7	符号层	真符号注册表 + 符号化梯度 + 三角校验
层 7.5	符号映射	SLH 单向桥 + 内生↔外部符号多对多映射 + 四路路由
层 8	执行输出	动作选择·工具调用
规划器	CEM + MPC	量子退火决策
认知皮层	对外执行	经安全层的工具调用与输出校验
narrator	语言输出	经 LLM 桥的语言生成（无 LLM 时退化为结构化诚实申报）
—	成长回路	失衡告警 → 参数建议 → 灰度应用
—	evalkit	成长日记 GrowthTrace + 十四项失衡监测

本地语义嵌入（v0.4）

v0.3 的象量是 sha256 哈希 —— 确定性有，语义没有（"苹果"和"手机"在哈希空间里 是随机两点）。v0.4 起默认改用 LSA（PPMI + 截断 SVD），从黑武士自己见过的 文本里学：

后端	依赖	semantic	说明
onnx	onnxruntime + 模型	✅ 最高	配了 embedding_model 就用
lsa	numpy	✅ 较高	默认。完全离线、隐私不出本机
hash	无（纯标准库）	❌	兜底。确定性但无语义

取舍要诚实说清：LSA 的语义来自共现结构 —— 语料里"苹果"和"手机"常一起出现， 它们才会靠近。冷启动时语料不足，语义很弱。所以：

• confidence 随语料量如实上升，UI「心智」页直接显示"语义置信 0.59（语料 38 篇）"；
• 拿不准时返回 0.0（诚实的"不知道"），不硬猜 —— 实测 12 组配对里 6 组真关系命中 4 组，零误报：宁可漏，不可错。

喂给 PASM V2 的仍是 8 维（内核 entity_latent_dim 的硬约束）， 由 encode_pasm() 从内部 64 维截取前 8 维 —— SVD 分量按奇异值降序，前 8 维信息量最大。

任务续跑与后台消息（v0.6）

v0.1 就有 tasks 表，但只有骨架：db 层有 4 个方法，运行时没有任何东西 驱动它，模型也看不到任务工具。结果是"交代一件要做的事 → 聊完就没了"。 v0.6 补上了完整闭环。

任务是有序步骤的集合，状态全部落库：

状态	含义
active	进行中
paused	已暂停（含重启后自动转入）
blocked	某步连续失败 3 次，等人决策
done / failed / abandoned	终态，不可恢复

三条关键设计：

1. 重启后遗留任务转 paused，不自动继续跑。 进程可能在用户不知情时重启（崩溃后被守护拉起），此时自动推进多步骤任务 可能做错事。宁可让用户说一句"继续任务 1"。

2. ★ 绝不自动判定任务完成。 所有步骤执行完也只是"待收尾"，必须由模型显式调 task_complete 并给出 evidence（凭什么认为做完了）。自动判定 = 自欺欺人。 证据会写进任务记录供日后审计。

3. 步骤失败不炸整个任务。 一步失败记录原因并停在原地，连续 3 次转 blocked 等人决策 —— 自动重试只会放大错误。

有活跃任务时心跳自动加快一档（tick_scale × 0.75），让任务在合理 时间内推进完。

后台消息是"外部世界 → 黑武士"的统一入口：渠道接入（微信/Discord/ 钉钉）、定时任务、Webhook 回调都走它。好处是外部消息与用户消息共用同一 个主循环（同一份记忆、同一套认知状态）。优先级低于用户消息 —— 用户正在说话时后台消息会排队而不是插嘴。

# 建一个三步任务
curl -X POST localhost:8777/api/tasks \
  -d '{"title":"整理下载目录","steps":"扫描文件;按类型归档;生成索引"}'
# 推进当前步
curl -X POST localhost:8777/api/tasks/action \
  -d '{"task_id":1,"action":"step_done","result":"扫出 42 个文件"}'
# 收尾（必须给凭据）
curl -X POST localhost:8777/api/tasks/action \
  -d '{"task_id":1,"action":"complete","evidence":"已归档并生成 index.md"}'
# 投一条后台消息
curl -X POST localhost:8777/api/background \
  -d '{"text":"定时检查完成","source":"cron"}'

资源感知与诊断（v0.6）

补齐"这台机器到底能干什么"这类问题的查询能力，全部 safe （只读、不改系统、不装东西）：

工具	回答什么
list_software	我机器上装了什么（实测读到 442 项；不扫用户目录）
find_command	某命令在不在 PATH（含绝对路径与版本，只查不执行）
diagnose_network	分层诊断：DNS 能否解析 → TCP 能否连通，区分"断网"与"服务挂了"
check_port	某端口被占没（"服务起不来"的高频原因）
dev_env	git / SSH 配置 / 常见运行时是否存在
text_stats	文件规模速览（行数/字符/最长行）

隐私边界：dev_env 只报SSH 公钥文件名（.pub/.pem）， 私钥名与内容一律不出现在返回里（有 selftest 守卫）；list_software 只读注册表/包管理器数据库，不遍历用户目录。

本地媒体库（v0.5）

v0.5 起黑武士能索引你本机的音乐 / 视频 / 图片。关键设计：纯标准库实现。

能力	内置（零依赖）	装了 mutagen 后
MP3	ID3v2 标题/艺术家/专辑/年份 + 时长	同（内置已够）
FLAC	全部标签 + 采样率/位深/声道/时长	同
M4A / MP4	标题/艺术家/专辑/时长	同
WAV	时长/采样率/位深/声道	同
OGG	标题/艺术家	同
JPG/PNG/GIF/BMP	尺寸	+ EXIF（需 Pillow）

为什么不用 mutagen 打底：实测本机 mutagen / Pillow 都不可用。若媒体库建立在 这些库之上，在绝大多数没装它们的机器上这项能力会整块消失 —— 那违背 "永不隐藏降级"的立身之本。所以内置自己解析文件头，把"零依赖可用"当底线； mutagen 存在时借它补精度，reader 字段会标明本次元数据来自 builtin 还是 builtin+mutagen。

读不到就是 null，绝不编造：没有标签的 mp3，其 artist/album 在库里 是 NULL（不是空串），UI 上显示 —。

扫描是增量的：按 (大小, 修改时间) 指纹，只重新解析变化过的文件。 音乐库动辄几万文件，全量重扫一次要几十秒，不能每次查询都做。 另有文件数（20000）与时间（20 秒）双上限，触顶时返回 truncated: true 并在 note 里说明"结果不完整" —— 不假装扫完了。

# 登记并扫描
curl -X POST localhost:8777/api/media/roots -d '{"path": "D:////Music"}'
curl -X POST localhost:8777/api/media/scan -d '{}'
# 查
curl "localhost:8777/api/media/items?category=audio"

档位与降级（永不隐藏）

档位	条件	表现
pasm2	装了 numpy + pasm2	十九层真实活跃度、安全层闸门、反事实推理、成长闭环
pasm1	无 pasm2，有 pasm-skills	记忆 / 情绪 / 焦点 / 塑形（内核六项）
builtin	都没有	内置等价实现，功能完整、语义检索较弱

V1 引擎内部再分 bionic / core / light 三档（有无 torch 情绪系统）。 任何一档缺失都在 /status 与「心智」页写明原因，动作类端点返回 503 而非 500。

---

功能说明

对话

• 异步优先级队列 + SSE 增量渲染，思考条实时显示当前阶段与工具调用
• 同步问答接口（CLI / 脚本 / 单轮调用）
• 会话历史回放，刷新页面不"失忆"
• 自主 TICK 的产出单独渲染成低打扰样式，不混进正常对话

记忆

能力	说明
结构化记忆库	标题/简述/标签/类目/显著度/保留度，UI 可浏览编辑
遗忘曲线	艾宾浩斯衰减，重要度与复习次数延长半衰期
睡眠巩固	相似记忆蒸馏合并，可手动触发
FTS5 中文全文	trigram 分词，支持中文子串检索（≥3 字；2 字由 LIKE 兜底）
联想线索	记忆间显式建边，表达"苹果→手机"这类不含关键词的关系
记忆审计	create/update/delete 全量账本，before → after 可追责
用户画像	8 维度结构化画像，启发式 + LLM 双抽取，带证据与置信度

认知与心智

• 十九层实时活跃度矩阵（数值 + 人类可读说明）
• 安全层：12 把锁状态、白名单规模、检查/拦截计数、连续拒绝、锁死状态
• 认知计数：步数 / 象量实体数 / 真符号数 / 记忆图边数 / 嵌入语义标注
• 失衡告警列表（内核自检出的"不对劲"）
• 睡眠巩固、成长复盘按钮
• 元认知冲突监测、双系统快慢切换可视化

工具（33 个）

类别	工具
文件系统	读/写/列目录/搜索（锁定沙箱，拒绝 .. 逃逸）
Shell	命令执行（黑名单即拒 + 超时上限 + 风险分级）
Web	联网搜索、网页阅读
记忆	写入/召回/更新/删除/巩固/线索/审计
系统	提醒、心跳自调节、时间、状态、环境、工具列表、反馈塑形
画像	set_profile / get_profile / get_panel / add_prefetch / list_prefetch
自发现	find_tool（按关键词检索工具，命中与否都写审计日志）、system_probe（CPU/内存/磁盘/电池）

工具执行是双闸门：应用层 policy（配置/风险/频率/黑名单）之后， 还有 PASM V2 安全层（白名单/限流/提示注入筛查/连续拒绝锁死升级）。

信息面板与预取

• 天气（wttr.in，需配 weather_city，v0.6.7 起中文描述兜底映射）、人物卡（内置常识 + 从记忆扩充）
• 热点面板（v0.6.7 起接真实榜单）：60s API 免 key 数据源， hotspot_source 可选 weibo / zhihu / bili / douyin / news（每日60秒读懂世界）； hotspot_base 可换成自部署地址；拉取失败诚实降级，不伪造榜单
• 预取缓存：登记 URL + TTL，心跳刷新到期项，有效期内注入上下文

语音

能力	实现	可用性
朗读回复（TTS）	speechSynthesis	完全本地、离线可用
语音输入（ASR）	SpeechRecognition + 云端转写	Chromium 走云端；桌面壳内置的 Chromium 不带该服务 API key，壳内基本不可用（按钮自动置灰并说明原因），在 Chrome / Edge 打开可用

桌面壳

Electron：托盘常驻、关窗不退出、单实例、启动进度、上下文隔离桥。

---

安装

前置要求

• Python 3.9+（推荐 3.12+）
• Node.js 18+（仅桌面壳需要）
• 操作系统：Windows / macOS / Linux

方式一：源码安装（推荐）

git clone https://gitee.com/arronzheng/BlackWarrior.git
cd BlackWarrior
pip install -e .

方式二：桌面壳

cd BlackWarrior/electron
npm install
npm start

可选增强（按需装，不装也能跑）

装什么	得到什么	不装会怎样
numpy	本地语义嵌入（LSA）+ PASM V2 十九层底座的运行条件	退回 sha256 哈希（无语义）+ 内核 V1 档，「心智」页标注原因
pasm2（见下）	V2 十九层底座：安全层闸门、元认知 ACC、反事实推理、成长闭环	退回 V1 引擎（记忆/情绪/焦点/塑形四项）
pasm-skills	内核 V1 档（bionic/core）：语义检索 + 情绪系统	退回 builtin 档，字面+字符级检索
torch	情绪系统（valence × arousal → mood）	情绪退化为单一效价值
psutil	system_probe 能读内存/电池	内存字段为空并标注"未装 psutil"

pip install numpy                # 本地语义嵌入（LSA）+ V2 底座的运行条件
pip install "blackwarrior[pasm]" # 内核 V1：自动带上 pasm-skills + pasm-framework
pip install psutil                # 本机资源探测（可选）

装 PASM V2 十九层底座（重要）

V2 底座在 PyPI 上的包名就是 pasm2：

pip install pasm2

它只依赖 numpy（CPU 毫秒级，不拖 torch），装完即可用。验证：

python -c "import pasm2; print(pasm2.__version__, pasm2.__stage__)"
# 2.0.0a12 11-second-audit-fixes

若要从源码装最新版 Alpha（PyPI 版可能滞后一两版）：

# 方式 A：直接从 Git 仓库装
pip install --no-deps git+https://gitee.com/arronzheng/PASM.git

# 方式 B：已有本地克隆
cd /path/to/PASM && pip install --no-deps .

为什么源码装要加 --no-deps：PASM 主仓声明了 torch>=2.0、fastapi、 uvicorn、pydantic，其中 torch 是数 GB 下载。而 V2 底座本身只需 numpy， 主仓的 packages.find.include 已含 pasm2*，所以 --no-deps 装出来就能直接 import pasm2，不必为 V2 拖 torch。只有你还要用 V1 引擎的 torch 情绪系统时 才去掉它。

⚠️ 包名避雷：pip install pasm 会装到一个完全无关的音频度量包（名字撞车）。 PASM 生态正确的包名是：

包名	是什么
pasm2	V2.0 十九层认知底座（黑武士 v0.3+ 用这个）
pasm-skills	V1 认知基座 SDK
pasm-agents	成品智能体集
pasm-framework	应用开发框架（防腐层）

pasm-agent 不是包名（那是主仓 pyproject 里的 name，从未发布），别去装它。

验证装没装成功：

blackwarrior selftest           # 末尾会打印当前档位与降级原因

---

使用教程

1. 启动

blackwarrior serve              # 浏览器打开 http://127.0.0.1:3721
blackwarrior serve --port 8080  # 换端口
blackwarrior serve --host 0.0.0.0 --allow-lan   # 局域网（必须同时设 api_token）

2. 首次接入模型（可选）

黑武士不接模型也能用——本地认知内核会接管回复、记忆照常累积。 在 UI「接入大脑」弹窗里填任意 OpenAI 兼容的 Key 即解锁完整推理：

Provider	说明
deepseek / qwen / kimi / glm / moonshot / openai / azure	需 API Key
ollama	本地模型，可离线
mock	本地假模型，用于演示与自测

也可以命令行写入：

curl -X POST http://127.0.0.1:3721/api/activate \
  -H "Content-Type: application/json" \
  -d '{"provider":"deepseek","api_key":"sk-xxx","model":"deepseek-chat"}'

3. 界面导览

视图	做什么
对话	聊天、看思考流与工具调用、语音输入输出
记忆	力导向记忆图谱（按保留度着色）、语义检索、一键睡眠巩固
认知	情绪曲线、预测误差仪表、好奇心、焦点栈、内核快照
心智	十九层活跃度、安全层、认知计数、失衡告警、睡眠/成长按钮
全景	用户画像卡片、信息面板、预取缓存登记
活动	工具注册表、行动日志、实时事件流
设置	供应商、人格、心跳、能力开关、语音、密钥脱敏回显

4. 常用操作

让它记住你

curl -X POST http://127.0.0.1:3721/api/memories \
  -H "Content-Type: application/json" \
  -d '{"title":"我叫小志","brief":"用户的名字","category":"身份","salience":5}'

查记忆（含中文全文检索）

curl -X POST http://127.0.0.1:3721/api/memories/search \
  -H "Content-Type: application/json" -d '{"query":"认知","k":5}'

设置提醒

curl -X POST http://127.0.0.1:3721/api/reminders \
  -H "Content-Type: application/json" -d '{"title":"喝水","minutes":30}'

手动触发睡眠巩固（含十四项失衡自检）

curl -X POST http://127.0.0.1:3721/api/mind/sleep -H "Content-Type: application/json" -d '{}'

看十九层实时状态

curl http://127.0.0.1:3721/api/mind | python -m json.tool

登记预取 URL（心跳自动刷新并注入上下文）

curl -X POST http://127.0.0.1:3721/api/prefetch \
  -H "Content-Type: application/json" \
  -d '{"url":"https://wttr.in/Beijing?format=3","ttl":3600}'

在设置页配天气（不配则诚实降级，不伪造）

{ "weather_enabled": true, "weather_city": "Beijing" }

5. 命令行

blackwarrior serve            # 启动服务
blackwarrior ask "你还记得我叫什么吗"   # 单轮问答（CLI）
blackwarrior selftest         # 包级自检
blackwarrior --version        # 版本与协议

---

渠道桥接（外部世界 ⇄ 黑武士）

黑武士可以主动到微信/钉钉找你，也能从外部渠道接消息进主循环 （与用户消息共用同一份记忆与认知状态）。

在 <data_root>/config.json 声明渠道：

{
  "schema_version": 6,
  "channels": [
    { "name": "wecom",  "type": "wecom_bot",   "token": "k1",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=你的KEY" },
    { "name": "wx",     "type": "serverchan",  "token": "k2",
      "webhook_url": "你的SENDKEY（sct.ftqq.com 免费，推到微信）" },
    { "name": "pp",     "type": "pushplus",    "token": "k3",
      "webhook_url": "你的token（pushplus.plus，免费额度大）" },
    { "name": "ding",   "type": "dingtalk_bot", "token": "k4",
      "webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=...",
      "secret": "SEC开头的加签密钥" }
  ]
}

能力	说明
出站（回复推送）	渠道来源的回合结束即推送到对应渠道；企业微信/钉钉自动切段与 20 条/分钟限流；业务失败（额度用尽等）如实记账
入站（回调型）	POST /api/channel/inbound {"name","token","text"}，令牌常数时间比较，进统一主循环
入站（轮询型）	渠道配 poll_url + poll_interval，后台定期 GET {items:[{id,text,from_id}]} 喂主循环，无需公网回调
可观测	GET /api/channel/list（令牌打码）；/api/status 的 channels 块带投递/失败/拉取计数

注意：Server酱/PushPlus 为单向推送（微信回复不回流）；要双向对话用 企业微信/钉钉群机器人（入站走公网回调或内网穿透），或自建轮询中转。

---

配置项

配置文件落在 <data_root>/config.json，支持四级覆盖： 代码默认 < 配置文件 < 环境变量 < 运行时调用。

数据位置

环境	data_root
开发态（仓库内运行）	./data/
安装态	%LOCALAPPDATA%/BlackWarrior（Windows）

关键配置

键	默认	说明
provider / model / api_key / base_url	deepseek / - / - / -	模型接入
temperature / max_tokens / timeout	0.7 / 4096 / 120	生成参数
heartbeat_enabled	true	启用心跳（空闲自主思考）
tick_interval	60.0	空闲心跳秒数
task_tick_interval	30.0	有任务时的心跳
awakening_interval / awakening_ticks	10.0 / 3	唤醒期密集心跳
watchdog_seconds	300	单回合看门狗超时
cognition_enabled	true	认知内核总开关
consolidate_every	20	每 N 次心跳做一次记忆巩固
recall_k	6	每轮召回记忆条数
auto_observe	true	自动把对话写入情景记忆
tools_enabled	true	工具系统总开关
allow_dangerous_tools	false	允许危险工具（删除/写文件）
shell_enabled / web_enabled	true	关闭后对应工具根本不注册
pasm2_enabled	true	PASM V2 底座开关
pasm2_profile	full	minimal / standard / full / brainwide
pasm2_tool_gate	true	V2 安全层作为工具闸门
pasm2_verify_claims	false	输出前对结论性断言做逻辑层校验
embedding_backend	auto	语义嵌入后端：auto / lsa / hash / onnx
embedding_model	-	ONNX 后端的本地模型路径（留空=不用 onnx）
embedding_persist	true	学到的语义落盘，重启不丢
media_enabled	true	本地媒体库（关掉则连工具都不注册）
media_auto_scan	false	启动时自动扫一次（大目录首次扫要几十秒，默认关）
tasks_enabled	true	任务续跑（关掉则连工具都不注册）
sysinfo_enabled	true	资源感知与诊断工具（软件清单/网络/端口/dev 环境）
weather_enabled / weather_city	false / -	天气面板
hotspot_enabled	false	热点面板（真实榜单）
hotspot_source	weibo	weibo / zhihu / bili / douyin / news
hotspot_base	https://60s.viki.moe	60s API 地址（可换自部署）
prefetch_enabled	false	预取心跳刷新
host / port	127.0.0.1 / 3721	服务监听
allow_lan / api_token	false / -	局域网模式（开就必须设 token）
voice_enabled / tts_enabled / asr_enabled	false	语音

环境变量

BLACKWARRIOR_PROVIDER / BLACKWARRIOR_MODEL / BLACKWARRIOR_API_KEY / BLACKWARRIOR_BASE_URL / BLACKWARRIOR_HOST / BLACKWARRIOR_PORT / BLACKWARRIOR_ALLOW_LAN / BLACKWARRIOR_API_TOKEN / BLACKWARRIOR_AGENT_NAME / LLM_PROVIDER / DEEPSEEK_API_KEY / MINIMAX_API_KEY / OPENAI_API_KEY

---

HTTP API

服务默认只监听 127.0.0.1。完整路由见 blackwarrior/server/routes.py（60+ 条）。

基础

方法	路径	说明
GET	/api/healthz	健康检查
GET	/api/version	版本与协议
GET	/api/status	完整状态（含 cognition / affect / panorama / pasm2）
GET	/api/media	媒体库总览（条目/分类/总时长/目录数）
GET	/api/media/items?category=&q=&limit=	列条目（分类 + 关键词过滤）
GET/POST/DELETE	/api/media/roots	目录登记 / 列出 / 取消登记
POST	/api/media/scan	扫描（{"full":true} 全量重扫）
GET	/api/tasks?state=&limit=	任务列表 + 当前活跃任务
POST	/api/tasks	建任务（{title, steps:"a;b;c", goal}）
POST	/api/tasks/action	任务动作（{task_id, action, ...}，见下）
POST	/api/background	投后台消息（{text, source, dedupe_key}）
GET	/api/summary	精简状态（高频轮询）

对话

方法	路径	说明
POST	/api/message	异步发消息（入主循环）
POST	/api/ask	同步问答（等结果）
GET	/api/conversations	会话历史
GET	/events	SSE 事件流

记忆 / 提醒 / 工具

方法	路径	说明
GET/POST	/api/memories	列表 / 新建
PATCH/DELETE	/api/memories/{id}	更新 / 删除
POST	/api/memories/search	检索（FTS5 + 语义）
GET	/api/actions	行动日志
GET/POST	/api/reminders	提醒
DELETE	/api/reminders/{id}	取消提醒
GET	/api/tools	工具注册表

认知与心智

方法	路径	说明
GET	/api/cognition	内核快照 + 情绪世界模型
POST	/api/cognition/consolidate	手动记忆巩固
GET	/api/cognition/mood?n=60	情绪曲线
GET	/api/mind	心智全景（十九层 + 安全层 + 成长）
GET	/api/mind/layers	只取十九层（轻量轮询）
POST	/api/mind/observe	手动喂一步认知
POST	/api/mind/sleep	睡眠巩固 + 失衡告警
POST	/api/mind/growth	成长复盘（参数建议）
POST	/api/mind/whatif	反事实推演
POST	/api/mind/verify	三角校验（声明 / 工具调用）
POST	/api/mind/tell	符号化注入
POST	/api/mind/gate-reset	复位安全层锁死

全景 / 面板 / 预取

方法	路径	说明
GET/POST	/api/profile	用户画像
GET	/api/panels · /api/panels/{kind}	信息面板
GET/POST/DELETE	/api/prefetch	预取缓存

语音 / 设置 / 运维

方法	路径	说明
GET	/api/voice/status	语音能力状态（前端据此置灰）
POST	/api/voice/transcribe	上传音频转写（未配置返回 503）
POST	/api/voice/speak	云端合成（不可用时前端回退本地）
GET/POST	/api/settings	配置（脱敏 / 更新）
GET	/api/providers	供应商列表
POST	/api/activate	写入 provider/key/model
POST	/api/llm/ping	测试连通
POST	/api/admin/start · /api/admin/stop	主循环启停
POST	/api/admin/reset-memories · /reset-conversations	重置数据

---

架构

┌──────────────────────────────────────────────────────────┐
│  Electron 壳（main.cjs / preload.cjs）                    │
│  拉起内核 · 托盘 · 单实例 · 上下文隔离桥                    │
└───────────────────────┬──────────────────────────────────┘
                        │ http://127.0.0.1:<port>
┌───────────────────────▼──────────────────────────────────┐
│  Python 内核 blackwarrior/                                │
│                                                          │
│  server/   HTTP + SSE 事件流（60+ 路由）                   │
│  runtime/  Continuum 主循环 + panels 面板 + prefetch 预取   │
│  llm/      多模型网关 + 工具循环 + V2 安全闸门              │
│  context/  上下文装配（认知/画像/预取/V2 四层注入）          │
│  tools/    33 个工具 · 三级风险 · 双闸门                    │
│  brain/    PASM V1 内核 + V2 十九层桥接 + 画像              │
│  voice/    语音服务门面（未配置显式降级）                    │
│  core.py   WarriorCore 总装                               │
│  db/       SQLite（WAL）：对话/记忆/全文索引/线索/审计      │
└───────────────────────┬──────────────────────────────────┘
                        │ 可选依赖（缺失即降级，永不隐藏）
┌───────────────────────▼──────────────────────────────────┐
│  PASM V2 认知底座 pasm2/                                  │
│  十九层 + 安全层（12 锁）+ 成长回路 + evalkit 成长日记       │
└──────────────────────────────────────────────────────────┘

BlackWarrior/
├── blackwarrior/          Python 内核包
│   ├── brain/  llm/  runtime/  server/  tools/  context/  db/  voice/
│   └── ui/static/         BlackWarrior UI（零构建）
├── electron/              桌面壳（main / preload / 图标）
├── scripts/make_icon.py   图标生成（纯标准库）
├── tests/test_server.py   端到端测试
└── docs/                  架构文档

---

安全模型

• 默认只监听 127.0.0.1；开局域网模式后所有敏感路由强制 Token；
• 工具分 safe / caution / danger 三级，策略层可按类别开关 + 频率节流；
• 双闸门：应用层 policy 之外，PASM V2 安全层在内核侧再拦一道 （白名单 / 每分钟限流 / 提示注入筛查 / 连续拒绝锁死升级），模型绕不过；
• 文件工具锁定沙箱目录，拒绝 .. 逃逸；Shell 有黑名单即拒 + 超时上限；
• 配置回显一律脱敏（key/token/secret/password）；
• 密钥只落本机 data/config.json，不进版本库。

---

开发与验证

blackwarrior selftest        # 包级自检（80 项，纯本地不依赖网络与模型）
python tests/test_server.py  # 端到端：84 项（有 numpy 时 89 项）

端到端测试覆盖：REST 主干、SSE 事件流、前端 DOM id 一致性（$('id') 必须存在于 HTML）、 工具注册数量、密钥脱敏、用户画像读写与非法维度拒绝、面板降级、预取增删、 十九层心智端点（有 V2 时验真实能力，无 V2 时验 503 降级）。

---

渠道桥接（外部世界 ⇄ 黑武士）

• 渠道在 config.json 的 channels[] 声明：webhook（通用 JSON）/ wecom_bot（企业微信群机器人）/ serverchan（Server酱·微信推送）/ pushplus（PushPlus·微信推送）/ dingtalk_bot（钉钉机器人+加签）；支持回调与轮询两种入站。详见「渠道桥接」章节。

Roadmap

• v0.1：PASM 认知内核 + Electron 壳 + 五视图 + 工具/记忆/提醒/语音
• v0.2：结构化用户画像、FTS5 中文全文、信息面板、预取缓存、「全景」视图
• v0.3：接入 PASM V2 十九层认知底座（安全层闸门 / 元认知 ACC / 反事实推理 / 成长闭环 / 失衡监测）+「心智」视图 + 工具自发现 + 本机资源感知 + 记忆线索 + 记忆审计
• v0.4：本地语义嵌入（LSA PPMI+SVD，numpy-only，从本地语料学， 冷启动如实报低置信、拿不准返回 0 不硬猜）；「心智」页新增嵌入后端/置信/语料三项
• v0.5：本地媒体库（纯标准库解析 ID3/FLAC/MP4/WAV/OGG/图片头，增量扫描、 幽灵条目自动清理）；6 个工具 + 6 个端点 + UI「媒体」视图
• v0.6：任务续跑（多步骤任务持久化、重启转暂停不自动跑、 收尾必须给凭据、有任务心跳加快）+ 后台消息统一入口 + 资源感知与诊断 6 工具（软件清单/网络分层诊断/端口/dev 环境）。 工具 39 → 55；新增 UI「任务」视图与 4 个端点
• v0.5：桌面壳内本地 ASR、渠道接入、技能市场（pasm-skills 互通）、多智能体协同
• v1.0：安装包全平台产物（NSIS / DMG / AppImage）+ 增量更新

规划中（尚未实现，不做承诺）：本地媒体处理（音乐库/视频面板）、 社交渠道、Scene Protocol 与 Agent 驱动界面、便携模式。

---

License

MIT © 2026 arronzheng