🐟 肥鱼 FatFish —— 使用说明书（v1.2.2）

肥鱼是一个住在黑色命令行窗口里的 AI 助手。 你打字问它，它回答；它还能帮你读写文件、上网查资料、跑命令、跑代码、看图片。

运行环境：Windows + Python 3.8 或更新。不用懂编程，照着下面做就行。

📖 本文件只讲怎么用。内部原理、参数表、开发笔记 → 《技术手册》（独立分支 manual，不随安装器分发）。 🥚 只想听八卦？直接跳到最后的 开发彩蛋。

一、五分钟上手

1. 装 Python

打开 https://www.python.org/downloads/，下载并安装 Python 3.8 或更新版本
⚠️ 安装界面最下面那个小方框一定要勾上：Add Python to PATH
装完重启电脑

怎么确认装好了：Win + R → 输入 cmd → 回车 → 输入 python --version。能显示版本号（如 Python 3.11.5）就成功了。

2. 装肥鱼

双击 FATPACKII.bat，等它自己跑完。它会依次：查 Python → 解包程序文件（覆盖前先备份）→ 建虚拟环境 → 装依赖（失败自动换清华镜像）→ 生成并打开 .env → 自检 → 问你要不要立刻启动。

🧪 需要无人值守安装（自动化）？先设两个环境变量：set FATFISH_SKIP_VENV=1、set FATFISH_NO_GUI=1。

3. 填 API Key（关键！）

上一步弹出的 .env，把这几行填好 —— = 两边不要有空格：

FATFISH_API_KEY=sk-你的DeepSeek密钥     # 必填：没它一句都聊不了
TAVILY_API_KEY=tvly-你的Tavily密钥      # 选填：没它不能联网

要哪个	去哪弄	长什么样
`FATFISH_API_KEY`（必填）	https://platform.deepseek.com/	`sk-` 开头
`TAVILY_API_KEY`（选填）	https://tavily.com/	`tvly-` 开头

只填第一个也能用，只是不能联网（联网功能会静默降级，不会崩）。申请步骤、以及 Key 泄露了怎么补救，见 第五章。

4. 启动

双击 fatfish1.2.2.bat。看到彩色的肥鱼横幅就成功了 🎉 （启动器自己的窗口会提示「按任意键关闭」，按一下关掉它，不影响主程序。）

✨ 默认只留一块窗口 —— 启动后控制台会自动让位，你眼前只有：

窗口	标题	干什么
对话窗口（主界面）	`🐟 肥鱼 · 对话`	平时就用它：成行对话流 + 多行打字 + 拖文件/图片 + 报批点按钮 + 回复边收边长

日志 / 状态 / 监控以分栏的形式长在这个窗口里（VS Code 式编辑器组），用「⚙ 布局」菜单切换 —— 不再是三个独立的黑窗口。

💡 控制台去哪了？ 程序起来 0.8 秒后自动把控制台窗口藏起来，只为「只弹一个窗口」。任何一步失败都保持原样（比如跑在 Windows Terminal 里、认不出窗口类名时 —— 宁可留着，也不误伤整个终端）。

想让它一直可见（排障）：.env 里写 FATFISH_CONSOLE=1

藏起来后想叫回来：敲 /console on（再藏回去 /console off）

硬崩溃时它会自动被请回来（CRASH-GUARD），不会让你对着空白桌面干等

💡 想回到「一堆黑窗口」的旧形态：.env 里写 FATFISH_MULTIWIN=1 重启即可。

🚨 规矩一：收工请敲 quit，别点 X

✅ 收工 → 在对话里敲 quit（窗口干净退场）

✅ 重启 → 点顶栏 ↻，或关掉对话窗口重新双击 fatfish1.2.2.bat

⚠️ 排障模式下控制台若还可见：它不是外壳，是整个进程组的宿主。点它的 X = 连带杀掉挂在上面的一切。嫌碍眼请最小化。

💡 不想用窗口？ .env 里写 FATFISH_WINDOW=0（不起对话窗口），或进去后 /window off；直接删掉 chat_window.py 也能跑（自动退化为纯控制台，不会报错）。

🪟 对话窗口长什么样（平时就用它）

┌──────────────────────────────────────────────────────────────┐
│ 🐟 肥鱼 · 对话        deepseek-flash      😊  🧹  📌  🖼  📎  ↻ │ ← 顶栏
├──────────────────────────────────────────────────────────────┤
│ ⚙ 布局 ▾                                        对话 ｜ 日志   │ ← 布局栏
├──────────────────────────────────────────────────────────────┤
│  我 › 帮我看看 README 有多少行                                 │
│  🐟 一共 575 行，分 13 章……                                   │ ← 对话区
│  · 已读取 README.md（575 行）                                 │   成行排列
│                                                              │
├──────────────────────────────────────────────────────────────┤ ← 1px 白线
│  🌐 联网：待命                                     - 等待 0.3s │ ← 状态条
│  😊 表情                                                      │ ← 工具栏
│  ┌──────────────────────────────────────┐   ┌──────────┐      │
│  │ 在这里打字…（Shift+Enter 换行）        │   │   发送    │      │ ← 输入区
│  └──────────────────────────────────────┘   └──────────┘      │
│  就绪                                 ✎ 签名是一种态度，我想…   │ ← 底栏
└──────────────────────────────────────────────────────────────┘

位置	是什么
顶栏	模型名 + 6 个按钮：😊 表情 · 🧹 清空对话 · 📌 置顶 · 🖼 粘贴剪贴板图片 · 📎 选文件 · ↻ 一键重启
布局栏	「⚙ 布局 ▾」—— 悬停（或 `Ctrl+L`）弹出浮层：布局预设、向右/向下分屏、拆成独立窗口、显示/隐藏各面板
「对话」页	消息成行排列（没有气泡/头像/昵称行）：`我 ›` 是你的话、`🐟` 是肥鱼的回复、`·` 是系统提示。可滚轮、可选中复制
「日志」页	真控制台（不再是文本控件）：自带滚动条、原样彩色、可框选复制 —— 刷屏也不卡。想看命令到底打印了什么就来这页
报批确认条	只在需要你批准时弹出来（位置在输入区上方）：点按钮，或直接敲 `y` / `a` / `n`
状态条	左边 = 联网状态，右边 = 等待转圈 → 一眼分清「在跑」还是「卡死」
输入区	多行输入框；Enter 发送、Shift+Enter 换行（Ctrl/Alt+Enter 也行）
底栏右侧	个性签名，每收到一条回复就换一句（句子在 `signatures/` 里，你可以自己改）

三种附件方式：① 把文件 / 图片直接拖进窗口；② 点顶栏 📎 选文件；③ 截图后按 🖼 或 Ctrl+V 直接贴图。

✍️ 右下角那句「个性签名」可以自己加：句子都在 signatures/ 文件夹的 .txt 里（一行一句），改完保存即可 —— 不用重启，下次换签名时自动读到新的。想清空就把行删掉。现在有 89 句，分五类：经典 / 鱼味 / 技术味 / 唐事录（真实翻车）/ 打回记录（被审查员拦下的）。

🎨 窗口配色与命令提示符完全一致（同一套调色板），字也一样大 —— 所以两边来回看不会跳戏。字体字号能改：.env 里写 FATFISH_UI_FONT=微软雅黑、FATFISH_UI_SIZE=13（默认 Consolas 12pt）。

5. 改完 Key 不想重启？

在肥鱼里敲 /reload，看到「已重新加载 .env」就生效了。

二、怎么跟它说话

两个地方都能说话，说给的是同一个「肥鱼」（同一份记忆、同一套工具）：

在哪说	怎么打字	适合
🪟 对话窗口（推荐）	下方输入框打字，Enter 发送、Shift+Enter 换行	日常主力：能拖文件、贴图、点报批按钮
🖥 运行窗口（控制台）	提示符后面直接敲，回车发送	应急；对话窗口关了也照样能用

控制台的提示符还会告诉你当前联网状态：

🌐~🔍 你 ▸
│ │  └─ 联网动作：🔍 搜索 / 📄 抓正文 / 🎯 自动
│ └──── Tavily 模式：🔍 search / 📄 extract / 🎯 auto / 🧩 both
└────── 联网开关：🌐+ 强制开 / 🌐- 关 / 🌐~ 关键词自动 / 🌐🤖 AI 判断

最常见的五种玩法（不用记语法，说人话就行，它自己决定调哪个工具）：

想干什么	你可以这么说
📄 读	`读一下 README.md` ／ `@某个文件.py`（也可以直接把文件拖进对话窗口）／ `/readr 某目录`
✍️ 写	`把 config.py 里的 timeout 改成 30`（它会先读、再改，改前自动备份）
🖼️ 看图	把图片拖进对话窗口，或 `@图片.png`
💻 跑	`跑一下这个脚本看报什么错` ／ `列出当前目录` ／ `装个 requests 库`
🔍 查	`搜一下今天有什么 AI 新闻`（需要 Tavily key）
⏰ 后台长任务	`后台跑一下全量扫描` → 立刻返回 `job_id`，跑完自动播报；`/jobs` 看进度，`/kill <id>` 中止

💡 它每次回答后面都会跟一个 ⏱️ 本轮 12.4s（这次干活花了多久）；你下次开口时还会显示 ⏱️ 停留 8.2s（你走神/倒水花了多久）。/timer off 可以关掉。

三、命令速查

文件与目录

输入	作用
`@路径`	把文件内容读进上下文（等同于拖文件进来）
`/read 路径...`	读一个或多个文件（只读一层）；`/file`、`/open` 完全同义
`/readr 文件夹`	递归读完整个目录树
`/ws ls [路径]`	列目录（默认递归 3 层）
`/ws read <路径>`	读文件
`/ws search <关键词>`	全文搜索（最多 500 处命中）
`/ws where`	看当前工作台根目录在哪
`/ws cd <路径>`	切换工作台根目录（移出作业区需你批准）
`/ws reset`	恢复默认工作台
`/ws forget [路径]`	清除「读过凭证」（全部或单个）
`/ws write \| append \| rm \| mkdir ...`	直接写 / 追加 / 删 / 建目录（平时不用手敲，模型会调）

路径里有空格，用双引号包起来：/read "我的文件夹/某个文件.py"。

联网

输入	作用
`/net on` / `/net off`	每次都搜 / 从不搜
`/net auto`	关键词规则判断（出厂默认）
`/net ai`	第二位 AI 判断该不该搜，并改写检索词（推荐）
`/net`	查看当前模式
`/tavily search \| extract \| auto \| both`	锁定检索方式：只搜 / 只抓正文 / 自动 / 先搜再抓
`/search <问题>`	强制联网搜一次（无视所有判断）

对话窗口与界面

输入	作用
`/window`	对话窗口状态
`/window on` / `/window off`	开关对话窗口（关掉后控制台照旧能用）
`/window test`	弹一条测试确认条 —— 验证报批交互最直接的办法
`/stream` / `/stream off` / `/stream think off`	流式状态 / 退回整段输出 / 不显示思考链
`/status`（可写 `/st`）	运行状态一览（模型 / 联网 / 工作台 / 核验 / 放行 / 计时）
`/layout`	看当前布局（编辑器组）
`/layout preset <名>`	套用布局预设
`/layout split \| detach \| dock \| reset`	分屏 / 拆成独立窗口 / 停靠回来 / 复位
`/console`	控制台窗口状态（GUI-First 默认藏着它）
`/console on` / `/console off`	唤回 / 隐藏控制台窗口

报批、核验与计时

输入	作用
`/auto`	一键放行状态
`/auto on` / `/auto off`	开关「一键放行」功能
`/auto now`	立刻放行本轮剩余读写（不用等报批出现）
`/verify ...`（可写 `/vfy`）	双人核验：`on` / `off` / `all` / `strict` / `model` / `answer` / `retries` / `supplements` / `fail` / `mirror` / `ping`
`/timer` / `/timer on` / `/timer off`	查看 / 开关「本轮耗时、停留时长」

后台任务

输入	作用
`/jobs`（`/bg` 同入口）	后台任务一览（id / 状态 / 已跑时长 / 输出体积）
`/job <id>`	增量查看某个后台任务的输出
`/kill <id>`	中止后台任务（连同子进程一起杀）

参数与其它

输入	作用
`/set`（`/settings`）	参数中心：查看 / 修改 / 还原 / 持久化（见第十一章）
`/set <项> <值>` / `/set save`	改一项（本次运行生效）/ 写进 `.env` 持久化
`/set profile <名>`	套用预设方案：`cheap` / `strict` / `fast` / `manual` / `offline` / `debug` / `default`
`/model` / `/model <名>`	查看 / 临时切换主模型（仅本次会话）
`/qq` / `/qq on` / `/qq off`	QQ 跟随模式状态 / 开 / 关（见第十章）
`/clear`	清空聊天记录
`/reload`	重新读 `.env`
`/help`	显示帮助
`exit` / `quit` / `退出`	退出肥鱼

全部命令的表格式清单也可以随时 /help 调出。

四、报批与放行：它动你的东西之前会问你

默认只拦「有副作用」的动作：写文件、删文件、跑命令、跑代码要你点头；读文件、列目录、搜索不打扰你。

弹窗时按	效果
`y`	只批准这一批
`a` 或 `1`	批准这一批，并且本轮剩余动作都不再问（敏感文件例外）
`n`	拒绝（它不会自己重试）

一键放行只在本轮有效 —— 你一发下一条命令就自动收回，不会出现「忘了关」而长期裸奔的情况。放行不等于关掉保护：路径沙箱、读过凭证、自动备份、逐条日志审计全都照旧生效。

三条要记住的规矩：

改一个已存在的文件前，它必须先读过。 你（或别的程序）中途改了文件 → 凭证自动失效 → 它会重新读一遍。这是防「基于过期印象乱改文件」的安全设计，不是 bug。
敏感文件永远特殊对待：.env、密钥、id_rsa、凭据文件…… 连读都要你批准，且永远不参与自动放行。
想彻底免打扰（不建议）：.env 里写 AUTO_APPROVE_DEFAULT=1，等于每轮一开就处于放行态。

五、API Key 怎么申请

肥鱼靠两个 Key 才能干活：DeepSeek Key（必填） 和 Tavily Key（选填）。

5.1 DeepSeek Key（必填，负责「聊天大脑」）

它是干嘛的：肥鱼回答你、写代码、思考，全靠它。没有它，肥鱼一句话都说不出来。

打开官网：https://platform.deepseek.com/
注册账号：手机号或邮箱注册 → 收验证码 → 填进去
实名认证（部分功能需要）：登录后进「个人中心」，按提示完成
充值（重要 ⚠️）：API 是按用量付费的，不是免费的。进「充值」充一点（比如 10 元能用很久）。💡 新账号有时送免费额度，够试玩
创建 API Key：左侧菜单 「API Keys」 → 点「创建 API Key」→ 起个名字（比如 fatfish）→ 确定后会弹出一长串以 sk- 开头的字符
⚠️ 立刻复制保存！ 它只显示这一次！关掉页面就再也看不到了

填进 .env（注意 = 两边不要有空格）：

FATFISH_API_KEY=<把复制到的密钥粘在这里>

5.2 Tavily Key（选填，负责「联网搜索」）

不填也能用肥鱼，只是不能联网，遇到"最新"类问题会答不上来。

打开官网：https://tavily.com/
注册账号：点右上角「Sign Up」，可用 Microsoft 账号一键登录，也可邮箱注册
领取免费额度：注册后送每月免费搜索次数（个人用基本够）
获取 API Key：登录后进「Dashboard」→ 找「API Keys」→ 复制 tvly- 开头那串
同样立刻保存

TAVILY_API_KEY=<把复制到的密钥粘在这里>

💡 肥鱼用的是 Tavily 做联网搜索（代码里写死的）。腾讯云、火山引擎、阿里云等也提供搜索 API，但肥鱼不支持那些，认准 Tavily 官网。

5.3 Key 泄露了怎么办？

API Key 就像你家的银行卡密码。一旦被坏人拿到，他就能用你的钱刷 API。

什么情况算"泄露"？

场景	危险吗
把 `.env` 截图发到群里 / 发到网上	🔴 危险，等于把密码发出去
把 `.env` 上传到 GitHub / Gitee	🔴 极度危险，机器人几秒就能扫到
Key 不小心写进了要分享的代码	🔴 危险
电脑被人用过、或中了病毒	🟡 建议直接换
只是自己电脑上放着，没给别人看过	🟢 安全

泄露了怎么补救？（三步）

立刻去平台删掉旧 Key（最关键，越快越好）
- DeepSeek：https://platform.deepseek.com/ → API Keys → 找到那个 → 删除
- Tavily：https://tavily.com/ → Dashboard → API Keys → 删除
创建一个新 Key，立刻复制保存
把新 Key 填回 .env，如果肥鱼在跑就输入 /reload

好习惯：.env 只放自己电脑上 / 分享截图前打码 / 用 git 就确保 .gitignore 有 .env / 怀疑就换 / 别充太多钱。

🧠 一句话记住：Key 一旦离开你的电脑，就当它已经泄露，立刻删掉重建。

六、工作台：它能动哪些文件

工作台 = 肥鱼能自由读写的那个文件夹，默认是程序所在的根目录（FATHFISHI.py / .bat 那个文件夹）。
所有路径都被限制在工作台内，越界直接报错。想让它动外面的文件，得先用 /ws cd 切过去，并且经你批准。
根一级文件每次被改前，自动全量备份到 _backup/，命名 原文件名.年月日_时分秒_微秒.bak。备份失败就中止本次操作（宁可不改，也不丢原文件）。子目录里的文件不受此规则保护。
建议：日常产出（脚本、临时数据、实验产物）写在 workspace/ 子目录，根目录保持整洁。
它自己的归档：

内容	位置
聊天日志	`logs/年/月/日/chat_HHMMSS.log`
跑命令 / 跑代码的输出	`logs/年/月/日/exec_*.out`
自动存盘的代码	`generated_code/年/月/日/`
跑 Python 的临时脚本	`.fatfish_tmp/`（跑完自动删）

📌 _backup/ 会越堆越多。建议偶尔按「每个文件只留最近几份」清一次（按文件名里的时间戳排序）。

七、联网与换模型

联网：需要一个 Tavily key（见第五章）。模式随时可切：

/net ai      第二位 AI 判断要不要搜（推荐：省 token，也不会搜回无关内容）
/net auto    关键词规则（出厂默认）
/net on      每次都搜          /net off   从不搜
/search <问题>   强制搜一次（跳过一切判断）

换模型 / 换服务商：只改 .env 三行，然后在肥鱼里敲 /reload —— 代码零改动。

FATFISH_API_KEY=sk-xxxxxxxxxxxxxxxx
FATFISH_BASE_URL=https://api.deepseek.com    # 任何 OpenAI 兼容服务都行
FATFISH_MODEL=deepseek-flash

旧写法 DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL / DEEPSEEK_MODEL 仍然兼容（作为回退）。
临时换一次模型：/model <模型名>（只影响本次会话）。
判断某个模型名是否存在，以 /models 接口或官方文档为准；报「模型不存在」就改 FATFISH_MODEL 再 /reload。
完整 .env 配置项清单（50+ 项）见《技术手册》第十八章。

八、出问题了怎么办（急救包）

现象	原因 & 解决
双击 bat 一闪就没了	没装 Python，或装时没勾 PATH。重装 Python 并勾上 `Add Python to PATH`
提示 `python 不是内部或外部命令`	同上：Python 没进 PATH
提示「提取内嵌数据失败，安装器可能已损坏」	安装器的 `##PYBEGIN##` 标记或载荷被破坏了（被编辑器保存过、被截断）。重新拿一份完整安装器，或本地重跑 `python make_fatpack.py`
`start cmd /k fatfish_runtime.bat` 报找不到文件	安装器没内嵌启动链文件。从完整目录补齐 `fatfish_runtime.bat` / `fatfish_lang.bat` / `launch.py` / `fatfish_watcher.py`，或重跑一遍安装器
能启动，但一聊天就报错	`.env` 里的 `FATFISH_API_KEY` 没填对（旧名 `DEEPSEEK_API_KEY` 同样可用），检查有没有多余空格
报「模型不存在」	改 `.env` 的 `FATFISH_MODEL`（模型名以官方文档 / `/models` 接口为准），改完 `/reload`
说不能联网	没填 `TAVILY_API_KEY`，或 key 过期（401）
提示「未读过该文件，请先 ws_read」	安全设计，不是 bug。让它先读（会弹批准框，你按 `y`）
提示「文件已被外部改动，凭证失效」	你（或别的程序）改过这个文件，凭证自动作废，重新读一次即可
提示「路径越界」	你让它读写工作台以外的路径。用 `/ws cd` 切到那个目录（移出默认作业区需批准）
读写操作弹 `y/N` 提示	正常流程。输入 `y` 放行、`n` 拒绝（拒绝后它不会重试）
监控器窗口一直没动静	它只显示「子程序输出」。不让它跑命令 / 跑代码，就不会有内容
关掉主窗口后，监控器还在倒计时	设计如此：最多再 drain 3 秒 + 30 秒倒计时，按任意键可立刻退
提示「工具调用轮次达到上限」	单轮超过 512 次工具调用，属失控保护。把需求拆开重说一遍即可
提示「回复被 max_tokens 截断」	回复太长被截。让它拆成几段继续，或调大 `MAX_REPLY_TOKENS`
依赖安装失败	安装器会自动换清华镜像重试；还不行手动跑：`python -m pip install openai python-dotenv requests`
窗口中文乱码	bat 里已设 `chcp 65001`；若仍乱码，换一个较新的 Windows 终端
改了 `.env` 不想重启	输入 `/reload`

九、注意事项

🚨 控制台可见时（排障模式）别点它的 X，也别在对话窗口右上角乱关 —— 控制台是整个进程组的宿主，点 X 会连带杀掉挂在上面的一切。收工请敲 quit，重启请点 ↻。
🔑 .env 是明文密钥：别截图发人、别上传网盘。/ .gitignore 已经帮你挡住 git，但这个防护仅对 git 有效。
🐍 venv/ 是可选的：没有也能跑（自动用全局 Python）。
🪟 监控器窗口没有标题（已知小缺陷），别和别的窗口搞混 —— 它的内容是「子程序输出的镜子」，你不跑命令它就不动。
📝 主程序文件名是 FATHFISHI.py —— 命名规则：FAT + 大版本字母 + FISH + 小版本罗马数字 （当前 = H 版 · 小版 I）。改名前请同步启动器与安装器（两边都按字面写死）。
🐢 回复被截断？让它拆成几段继续，或调大 MAX_REPLY_TOKENS。
🧮 提示「工具调用轮次达到上限」= 单轮超过 512 次工具调用，属于失控保护，重新说一遍需求即可。
🌏 多语言：启动器会探测系统语言，中文系统给中文界面，其他一律回退纯英文。

十、QQ 跟随模式（可选，进阶）

让命令行里这个肥鱼上 QQ：同一个进程、同一份记忆、同一套工具、同一道闸门。

它由旁路进程 qq_bridge/（NapCat + OneBot，默认监听 5700 端口）把 QQ 消息喂进主程序；
群里 @ 它 → 正常回合，回复发回群里；没 @ 它 → 默认也在听（直通模式，它可以自己决定说不说）；
权限分档：白名单里的「主人」读写免密；非主人读写要密码，且只在指定群工作；
开关：/qq on / /qq off（重启肥鱼后需重新开）。
更多子命令：/qq help（status / reset / readpw / media 等）。

⚠️ 两条禁忌：① 只在一个实例里开 /qq on（同时跑两个会抢消息、可能重复回复）； ② 改代码后要重启，改桥接的 config.json 要重启桥接。完整原理见《技术手册》与 qq_bridge/README.md。

十一、常用设置

所有旋钮集中在 /set：查看、修改、还原、持久化。

/set                 看常用项          /set all        看全部（含进阶项）
/set <项>            看单项            /set <项> <值>   改（本次运行生效）
/set diff            只看改过的        /set reset [项]  还原
/set save            写进 .env（持久化，只写改过的项）
/set profile <名>    套预设：cheap(省钱) / strict(严格) / fast(快速) / manual(手动) / offline(离线) / debug(调试) / default

几个最常用的：

项	默认	作用
`net_mode`	`ai`	联网判断方式（`on` / `off` / `auto` / `ai`）
`show_timer`	`on`	是否显示「本轮耗时 / 停留时长」
`show_wait_anim`	`on`	是否显示等待转圈
`auto_approve_scope`	`all`	一键放行范围：`none` 全拦 / `writes` 只放写入 / `all` 含删除执行
`approve_scope`	`writes`	人工报批范围：`writes` 只拦写 / `all` 连只读也拦
`verify_mode`	`auto`	双人核验范围：`off` / `auto` / `all`
`max_history`	`500`	保留多少条历史消息

所有开关类命令（/net、/verify、/timer、/auto）改的都是同一批设置，两边始终同步。完整的项清单与 preset 细节见《技术手册》第十七章。

十二、极简速查（懒人版）

1. 装 Python（勾 Add to PATH）
2. 双击 FATPACKII.bat
3. 去 platform.deepseek.com 申请 DeepSeek Key（sk- 开头）
   （想联网就再去 tavily.com 申请 Tavily Key，tvly- 开头）
4. 把 Key 填进自动打开的 .env 文件（= 两边不留空格）
5. 双击 fatfish1.2.2.bat
6. 会弹出**一个对话窗口**（控制台自动让位）—— 日志 / 状态 / 监控都在它里面
7. 开始打字聊天 🐟

就这几步，猪都会了。祝你玩得开心！ 🎉 That's it — even a pig can do it. Have fun! 🎉

十三、几句世界观（可选读）

🧿 双人核验：肥鱼想动有副作用的东西之前，会先把方案交给**第二位 AI（审查员）**复核；审查员不放行，它就得「补充说明」或「换方案」重来。设置里有开关（/verify off 可关）。
🔐 两道闸门：审查员 AI 一道 + 你点头一道。核验通过 ≠ 直接执行，你还是最后一道。
🧩 想了解这些机制怎么实现的、以及所有参数、启动链路、安装器原理 —— 见《技术手册》。

附录：开发彩蛋

正文为了让文档干净，把不少「当时到底怎么翻车的」细节都抽走了。它们其实是这份文档里最值钱的部分 —— 想弄明白「代码为什么非要那么写」的人，直接看这里。

🥚 彩蛋 1：一个转义字符把安装流程搞崩了

安装器生成器的模板原本用普通三引号字符串写。模板里那句临时文件路径 %TEMP%\fatfish_extract_... 中的 \f 被 Python 当成换页符（0x0C）解释，路径实际变成了「盘符 + 换页符 + atfish_extract_...」， PowerShell 当场报 Illegal characters in path，安装在第 2 步就断了。

修法：模板一律写成原始字符串。一行之差，找了半天。

🥚 彩蛋 2：cmd 把一行汉字「劈成两半」去执行

原以为 bat 里放中文无妨，实测报出这种错：

'显式指定' is not recognized as an internal or external command
'<半个汉字>新获取一份完整的' is not recognized as an internal or external command

原因：cmd 解析批处理按字节偏移续读文件；文件里有多字节 UTF-8 字符时偏移会漂移，于是它从一行的中间开始读，把半截 REM 注释当成命令执行（两个单引号之间就是被劈开的半个汉字）。

修法：bat 外壳一律纯 ASCII 英文，中文只放在载荷脚本里（载荷由 PowerShell 以 -Encoding UTF8 显式读写，完全不经 cmd 解析）。这就是为什么安装器提示全是英文，而解包完打印出来的清单反而是中文。

🥚 彩蛋 3：分隔标记到底几个字符？

那个用作分界的标记（写在安装器正文中间的那一串）实际是 11 个字符，可旧代码里按 +12 去截 —— 多算了 1 个。结果它顺手吃掉了标记后面的第一个换行符， 恰好无害，于是这个 bug 一直没人发现。新版改成按实际长度注入，而且长度是算出来的、不是硬编码，将来改标记名也不会错位。

顺带一提：这个标记在代码里是拆成两小段拼出来的 —— 为了让那行代码本身不含完整标记，否则「找最后一个标记」的逻辑会先搜到自己。

🥚 彩蛋 4：给肥鱼窗口「验明正身」

记录运行窗口 PID 的那个小文件，最早是靠「窗口标题反查」实现的 —— 先把窗口标题改成一个随机串，再用 PowerShell 按标题找自己。在传统 cmd 窗口下没问题，但在 Windows Terminal 里，cmd.exe 没有自己的顶层窗口，标题其实属于终端宿主程序，于是反查抓到的是终端的 PID，外部工具照着它操作，甚至会误伤整个终端窗口（历史日志里确实抓到过）。

修法（重定向法）：换一句带重定向的命令跑 PowerShell，让它报出「自己的父进程 PID」—— 重定向由 cmd 自己处理文件句柄，PowerShell 是本窗口直接启动的，所以父进程就是运行窗口本体。降级链：Get-CimInstance → Get-WmiObject → 窗口标题反查（仅传统终端有效）→ 写 0。

🥚 彩蛋 5：监控器一口气回放了四万行

监控器是「子程序输出的镜子」，做法是 tail 输出文件。但它早期不看时间，冷启动时会把当天、甚至更早的执行输出从头整份刷一遍 —— 跑久了的机器上，一次性回放量能到几万行，屏幕瞬间被历史输出淹没，也是监控器日志膨胀的主因。

修法：给它加一个启动基线 —— 启动时先把已存在的输出文件记到当前长度，之后只滚基线之后的新增内容。修好后，同样场景回放 0 行。

🥚 彩蛋 6：`.hex` 转写文件的兴衰

曾经有 3 个 .hex 文件，是三个 .bat 的逐字节十六进制转写 （每行 16 字节、第 8 字节后加一个空格分栏、小写、CRLF 结尾；40 65 63 68 6f 就是 @echo）。它们被当成「保真备份」一直躺在目录里，直到被逐项核实：

全项目搜索，命中的地方没有一处是「读取」（唯一的代码动作是写出）；
安装器内嵌清单里根本没有它们；
每个字节在原 .bat 里都找得到 —— 信息量 100% 冗余。

换句话说，它是一把没有配钥匙的备用锁。还原其实只要一行 binascii.unhexlify(去掉空白(内容))，但既然没有任何程序会去执行它，留着就只是占地方。于是连生成器里的相关代码（常量、hexdump() 函数、生成循环）一起清掉了。

🥚 彩蛋 7：怎么证明「一键放行」真的只放行一轮？

单元测试只能证明按键识别对，证明不了端到端行为。于是做了个「真进程实验」：注入一个假的 openai 模块，让它一口气发两轮工具调用 —— 第 1 轮在弹窗上按 a，看第 2 轮是否真的免问；再发一条新命令，看放行态是否真的复位。结论：第 2 轮免问 ✅、新命令后恢复逐个报批 ✅。

🥚 彩蛋 8：备份区是怎么「爆仓」的

备份规则是「根一级文件每次被改前都全量留档」，改得越勤堆得越快 —— 一晚上就能堆出一大堆同名副本。建议按「每个文件只留最近几份」定期清一轮。所以文档里索性不写死备份数量 —— 因为它秒级变化，写什么都是错的。

📌 Key 怎么申请、怎么填、填错了咋办，看 「十四、API Key 怎么申请？」 📌 真正要跑的核心只有 4 个：FATPACKII.bat（装）、 fatfish1.2.2.bat（启）、.env（配）、FATHFISHI.py（本体）。

Name		Name	Last commit message	Last commit date
fatfish_core		fatfish_core
signatures		signatures
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
FATHFISHI.py		FATHFISHI.py
README.md		README.md
boot_report.py		boot_report.py
chat_window.py		chat_window.py
common.py		common.py
conlog.py		conlog.py
exec_tools.py		exec_tools.py
fatfish1.2.2.bat		fatfish1.2.2.bat
fatfish_lang.bat		fatfish_lang.bat
fatfish_runtime.bat		fatfish_runtime.bat
fatfish_watcher.py		fatfish_watcher.py
file_tools.py		file_tools.py
launch.py		launch.py
loghost.py		loghost.py
make_fatpack.py		make_fatpack.py
net_tools.py		net_tools.py
settings.py		settings.py
status_console.py		status_console.py
stream_core.py		stream_core.py
ui_core.py		ui_core.py
verify_tools.py		verify_tools.py
workspace.py		workspace.py
技术手册.md		技术手册.md
部署记录_20261002.md		部署记录_20261002.md

Latest commit

History

Folders and files

Repository files navigation