归所与 AI 集成指南

归所提供 CLI（命令行接口），让 AI 智能体可以通过终端命令直接管理文件整理规则。

工作原理

AI 智能体 → finalplace.exe CLI → IPC (Socket) → 归所 GUI → 执行操作

CLI 不独立工作，它通过本地 Socket 与运行中的归所 GUI 通信。AI 发送命令，归所执行，所有数据存储在本地。

前置条件

归所已安装并登录
归所 GUI 正在运行（AI 可以用 launch 命令自动启动）

怎么接入

配置命令路径

归所安装后不会自动注册到系统 PATH。AI 需要使用完整路径调用：

"C:\Program Files\FinalPlace\FinalPlace.exe"

验证连接

# 检查 CLI 是否可用
"C:\Program Files\FinalPlace\FinalPlace.exe" --help

# 启动 GUI（如尚未运行）
"C:\Program Files\FinalPlace\FinalPlace.exe" launch

快速开始

1. 启动 GUI

finalplace.exe launch

如果 GUI 未运行，会自动启动并等待就绪（最长 30 秒）。

2. 列出已有规则

finalplace.exe auto-rules list
finalplace.exe auto-rules list --enabled   # 仅已启用的规则

3. 创建一条规则

finalplace.exe auto-rules create \
  --name "整理下载图片" \
  --source "C:/Downloads" \
  --condition "ext:jpg,png,gif" \
  --action "move:C:/Pictures/{Year}/{Month}" \
  --enable

4. 预览效果（不实际修改）

finalplace.exe auto-rules preview --uuid <规则UUID> --path "C:/Downloads/photo.jpg"

5. 执行规则

finalplace.exe auto-rules execute --uuid <规则UUID> --path "C:/Downloads/photo.jpg" --confirm

AI 能做什么

分类	命令	说明
规则管理	`auto-rules list`	查看已有整理规则
	`auto-rules create`	让 AI 帮你创建规则
	`auto-rules update / delete`	修改或删除规则
	`auto-rules toggle`	开启/关闭某条规则
防护规则	`watchdog list`	查看系统防护规则
	`watchdog create`	让 AI 创建新的防护规则
模板管理	`condition-templates list`	查看条件模板
	`action-templates list`	查看动作模板
运行日志	`logs list`	查看历史整理记录
	`logs rollback`	回滚某个任务

安全机制

具体来说：

AI 说「我要整理文件」→ 归所先暂停，等你点「确认」
你可以看 AI 准备做什么 → 同意就确认，不同意就取消
delete 和 execute 操作需要 --confirm 标志，防止误操作

权限限制

在调用 auto-rules execute 时可以设置安全限制：

限制项	说明
`allow_overwrite`	是否允许覆盖同名文件
`allow_cross_volume`	是否允许跨盘移动
`allow_destructive`	是否允许删除操作
`allow_permanent_delete`	是否允许永久删除（不进回收站）

建议： 第一次用 AI 时把这些都关掉，只允许「移动到指定目录」。

本地运行，不上传文件

输出格式

所有命令输出 JSON：

// 成功
{"ok": true, "data": {...}}

// 失败
{"ok": false, "error": {"code": "ERROR_CODE", "message": "描述"}}

退出码：0 = 成功，1 = 失败。