@antaif3ng/til-work

v0.6.0

Published

2 months ago

TIL Work — 运行在终端里的个人 AI 助手 (Personal AI assistant CLI powered by LLM)

Downloads

106

0High
0Medium
0Low

antaif3ng

cli agent ai assistant llm openai anthropic google terminal mcp

TIL work agent 工具

运行在终端里的个人 AI 助手，类似 Codex CLI / Claude Code。

TIL work 是一个基于大语言模型的命令行 Agent 工具。它可以直接操作你的文件系统、执行命令、编辑代码、搜索网页、截图、控制浏览器，并通过对话式交互帮你完成各种电脑任务。

核心能力

| 能力 | 说明 | |------|------| | 命令执行 | 在你的系统上直接运行 bash 命令 | | 文件管理 | 读取、创建、编辑、复制、移动、删除文件（支持读取图片） | | 代码编辑 | 精确替换代码片段（类似 sed，但更智能） | | 截图 | 截取全屏或窗口截图，返回给 LLM 进行视觉分析 | | Computer Use | 鼠标点击、键盘输入、滚动拖拽 + 自动截图反馈 | | 浏览器控制 | 页面导航、快照（ref 定位）、点击、输入、截图、JS 执行（agent-browser） | | 网页搜索 | 实时搜索互联网获取最新信息 | | MCP 扩展 | 通过 MCP 协议接入外部工具服务（stdio / HTTP） | | 记忆系统 | 跨对话记住上下文（MEMORY.md + AGENTS.md） | | 技能系统 | 内置技能 + 自定义 SKILL.md + 工作区包自动发现 | | 会话持久化 | 退出后可恢复上次对话（--resume / --continue） | | Context 压缩 | 长对话自动摘要压缩，防止 token 溢出 | | 安全拦截 | 自动检测并拦截 rm -rf、sudo 等危险命令 | | 多模型 | 支持 Anthropic、OpenAI、Google Gemini 及任意 OpenAI 兼容接口 |

交互体验

多行输入：行尾输入 \ 再回车、Ctrl+J 或 Alt+Enter 均可插入换行，Esc 取消多行输入
输入框 UI：带上下边框的输入区域，底部常驻显示当前工作目录和随机操作提示
Placeholder：空输入时显示换行快捷键提示，输入后自动消失
文件引用：输入 @ 后实时搜索文件，方向键选择，文件内容自动注入 LLM 上下文
命令菜单：输入 / 弹出命令列表，方向键循环选择，Enter 直接执行，Tab 补全

前置要求

Node.js >= 20.6.0（推荐 22+）
npm >= 9
至少一个 LLM API Key（Anthropic / OpenAI / Google / MiniMax / 智谱等 OpenAI 兼容接口）

node -v  # 需要 v20.6.0 或更高

安装

方式一：npm 全局安装（推荐）

npm install -g @antaif3ng/til-work

安装后使用 til 命令启动。

方式二：从源码安装

git clone https://github.com/antaif3ng/til-work.git
cd til-work
npm install
npm run build
npm link  # 注册 til 命令到全局

更新版本

npm update -g @antaif3ng/til-work

快速开始

1. 首次配置

til --setup

按提示输入模型 ID、API Key 和 Base URL。配置保存在 ~/.til/config.json。

你也可以通过环境变量配置：

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# OpenAI
export OPENAI_API_KEY=sk-xxxxx

# Google Gemini
export GOOGLE_API_KEY=AIza-xxxxx

# OpenAI 兼容接口（如 MiniMax、智谱、DeepSeek、Ollama 等）
export OPENAI_API_KEY=your-key
export OPENAI_BASE_URL=https://api.minimaxi.com/v1

2. 启动交互模式

til

输入 / 查看所有可用命令（支持方向键循环选择），输入 @ 引用文件内容（自动注入到上下文）。

支持多行输入：行尾输入 \ 再回车，或按 Ctrl+J / Alt+Enter 换行。

3. 单次执行模式

til "列出当前目录的所有 TypeScript 文件"
til -p "解释这个错误日志" < error.log
cat README.md | til "总结一下这个文件"

命令参考

CLI 参数

til [options] [prompt]

选项:
  -p, --prompt <text>     单次执行模式
  -m, --model <model>     指定模型 ID
  --base-url <url>        覆盖 API 地址
  --tools <list>          指定启用的工具（逗号分隔）
  --skill <path>          加载技能文件或目录（可重复）
  --no-skills             禁用自动技能加载
  --continue              恢复当前目录下的最近一次会话
  --resume [sessionId]    恢复指定 ID 的会话
  --setup                 运行配置向导
  -h, --help              显示帮助
  -v, --version           显示版本

交互模式命令

在交互模式中输入 / 即可看到所有命令（支持方向键选择和自动补全）：

| 命令 | 说明 | |------|------| | /help | 显示帮助信息 | | /model | 查看/切换/管理模型（支持方向键选择） | | /model add <id> [baseUrl] [apiKey] | 添加模型配置 | | /model default <id> | 设置默认模型 | | /skills | 查看/管理技能 (reload/install/enable/disable/rm) | | /skill:<name> | 查看某个技能的详细内容 | | /mcp | 查看/管理 MCP 服务 (add/rm/reload) | | /memory | 查看当前记忆内容 | | /usage | 查看本次会话的 Token 用量 | | /sessions | 查看会话历史列表 | | /config | 查看当前配置 | | /config check | 测试当前 API 连接 | | /opencode | 启动 OpenCode 终端 AI 助手（自动安装，退出后显示会话恢复命令） | | /clear | 清空对话历史 | | /exit | 退出 |

内置工具

| 工具 | 类型 | 默认启用 | 说明 | |------|------|----------|------| | bash | 基础 | 是 | 执行 bash 命令（ls, grep, git, curl 等） | | read | 基础 | 是 | 读取文件内容（文本 + 图片 base64） | | write | 基础 | 是 | 创建或覆盖文件 | | edit | 基础 | 是 | 精确查找替换 | | file_manager | 文件 | 是 | 复制、移动、删除、列目录、获取信息 | | system_info | 系统 | 是 | OS、CPU、内存、网络、环境变量 | | web_search | 网络 | 是 | 搜索互联网获取实时信息 | | web_fetch | 网络 | 是 | 抓取网页内容转纯文本 | | screenshot | 视觉 | 是 | 截取全屏或窗口截图 | | computer | 桌面自动化 | 是 | 鼠标、键盘、滚动 + 自动截图反馈 | | browser | 浏览器 | 否 | agent-browser 浏览器自动化（内置，自动发现系统 Chrome） |

screenshot 工具

截取屏幕或窗口截图，返回 base64 图片供 LLM 视觉分析。

macOS 使用 screencapture（系统自带）
Linux 使用 gnome-screenshot / scrot / import（需安装其中一个）

computer 工具

对标 Anthropic Computer Use API，支持以下操作：

| Action | 说明 | |--------|------| | screenshot | 截屏 | | mouse_move | 移动鼠标 | | click | 点击 | | double_click | 双击 | | drag | 拖拽 | | type | 输入文本 | | key | 按键组合（如 cmd+c, ctrl+shift+t） | | scroll | 滚动 |

每个操作执行后自动截图，形成"操作 → 视觉反馈 → 下一步"循环。

依赖：

macOS: brew install cliclick
Linux: sudo apt install xdotool

browser 工具

基于 agent-browser 的浏览器自动化，已内置为依赖，自动发现系统中已安装的 Chrome。默认以可见窗口（headed）模式运行，可设置 headed=false 切换为无窗口模式。

推荐工作流（snapshot-ref 模式）：

open — 打开目标 URL
snapshot — 获取页面可访问性树 + 元素 ref（@e1、@e2 …）
使用 ref 交互（click @e1、fill @e2 "text"）
页面变化后重新 snapshot

支持操作：open、snapshot、screenshot、click、fill、type、eval、get_text、scroll、wait、press、select、hover、back、forward、close。

如果系统没有 Chrome，可运行 npx agent-browser install 下载，或设置 AGENT_BROWSER_EXECUTABLE_PATH 指向自定义浏览器。

配置

配置文件位于 ~/.til/config.json：

{
  "model": "MiniMax-M2.5",
  "apiKey": "sk-xxxxx",
  "baseUrl": "https://api.minimaxi.com/v1",
  "models": {
    "MiniMax-M2.5": {
      "provider": "openai-compatible",
      "contextWindow": 128000
    },
    "gpt-4o": {
      "provider": "openai",
      "apiKey": "sk-openai-xxxxx"
    }
  },
  "providers": {},
  "mcpServers": {},
  "compaction": {
    "thresholdRatio": 0.7,
    "keepRecentTokens": 4000,
    "reserveTokens": 8000
  }
}

配置字段

| 字段 | 说明 | |------|------| | model | 默认模型 ID | | apiKey | 全局 API Key（所有模型的默认值） | | baseUrl | 全局 Base URL（所有模型的默认值） | | models | 各模型的单独配置（provider、apiKey、baseUrl、contextWindow 等） | | providers | Provider 级别配置（apiKey、baseUrl、headers） | | mcpServers | MCP 服务器配置 | | disabledSkills | 已禁用的技能名称列表 | | defaultTools | 默认启用的工具列表 |

模型管理

# 配置向导
til --setup

# 交互模式中管理
/model                     # 查看已配置模型
/model <id>                # 切换模型
/model add <id> [url] [key]  # 添加模型
/model default <id>        # 设置默认
/model rm <id>             # 删除配置
/config check              # 测试 API 连接

支持的模型

TIL 支持任何 OpenAI 兼容接口。模型 provider 根据 ID 前缀自动检测：

| ID 前缀 | Provider | 示例 | |----------|----------|------| | claude* | anthropic | claude-sonnet-4-20250514 | | gpt* / o3* / o1* | openai | gpt-4o, o3-mini | | gemini* | google | gemini-2.5-pro-preview-06-05 | | 其他 | openai-compatible | MiniMax-M2.5, deepseek-chat, glm-5 |

MCP 扩展

TIL 支持通过 MCP (Model Context Protocol) 接入外部工具服务。

配置 MCP 服务器

在 ~/.til/config.json 中添加：

{
  "mcpServers": {
    "web-search": {
      "type": "http",
      "url": "https://open.bigmodel.cn/api/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    },
    "minimax": {
      "command": "uvx",
      "args": ["minimax-coding-plan-mcp"],
      "env": {
        "MINIMAX_API_KEY": "your_minimax_api_key"
      }
    }
  }
}

注意：浏览器自动化已通过内置 browser 工具提供（基于 agent-browser），无需再配置 Playwright MCP。MCP 主要用于接入需要 API key 的外部服务。

支持两种传输方式：

stdio：本地进程通过 stdin/stdout 通信
streamable_http / sse：远程 HTTP 服务

交互式 MCP 管理

在交互模式中直接添加、删除和重载 MCP 服务：

/mcp                                         # 查看所有 MCP 服务状态
/mcp add playwright --stdio npx @playwright/mcp --headless    # 添加 stdio 类型
/mcp add web-search --url https://api.example.com/mcp         # 添加 HTTP 类型
/mcp add api --url https://api.example.com/mcp -H Authorization:Bearer\ sk-xxx  # 带 header
/mcp add api --url https://api.example.com/mcp -H Authorization:Bearer\ sk-xxx -H X-Project:demo  # 多个 header
/mcp add project-db --stdio npx @mcp/postgres --project       # 添加到项目级配置
/mcp rm playwright                           # 删除服务
/mcp reload                                  # 重载所有服务（热重载）
/extensions                                  # 查看所有扩展信息

项目级 MCP 配置

除全局 ~/.til/config.json 外，还支持项目级配置 <项目>/.til/config.json。项目级配置的同名服务覆盖全局配置。

// .til/config.json（项目级）
{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

内置技能

TIL 内置 8 个实用技能，安装即用：

| 技能 | 说明 | |------|------| | summarize | 使用 summarize CLI 摘要网页、PDF、YouTube 等 | | find-skills | 从开源社区发现和安装新技能 | | self-improvement | 自动记录错误、学习和修正，持续改进 | | skill-creator | 创建新技能的指南和最佳实践 | | agent-browser | agent-browser 浏览器自动化工作流和最佳实践 | | excel-xlsx | 创建、检查和编辑 Excel 工作簿（公式、日期、类型、格式、兼容性） | | word-docx | 创建、检查和编辑 Word 文档（样式、编号、修订、表格、兼容性） | | nano-pdf | 使用自然语言指令编辑 PDF 文件 |

技能管理

/skills                         # 列出所有已加载技能（显示来源和状态）
/skill:summarize                # 查看 summarize 技能详情
/skills reload                  # 重新扫描并加载技能（热重载）
/skills install steipete/nano-pdf   # 从远程安装技能（npx skills add）
/skills disable excel-xlsx      # 暂时禁用技能（不删文件）
/skills enable excel-xlsx       # 重新启用技能
/skills rm my-old-skill         # 从磁盘删除用户/项目技能（内置技能不可删除）

自定义技能

将 SKILL.md 放入以下目录即可自动加载（按优先级排列）：

| 路径 | 作用 | |------|------| | ~/.til/skills/<name>/SKILL.md | 全局技能 | | .til/skills/<name>/SKILL.md | 项目级技能 | | <cwd>/<pkg>/skills/<name>/SKILL.md | 工作区包技能（自动发现） | | --skill <path> | CLI 指定 |

同名的用户技能会覆盖内置技能。

工作区包自动发现

TIL 会自动扫描当前工作目录下的一级子目录，如果子目录中包含 skills/ 文件夹，其中的技能会被自动加载。这意味着你可以将 agent 技能包直接放在项目中，无需额外配置：

my-project/
├── my-agent/    # agent 技能包
│   ├── agent.yaml
│   └── skills/
│       ├── xx-skillA/
│       │   └── SKILL.md
│       ├── bb-skillB/
│       │   └── SKILL.md
│       └── ...
├── another-agent-pack/            # 另一个技能包
│   └── skills/
│       └── ...
└── .til/
    └── config.json

以上目录结构中 my-agent/skills/ 和 another-agent-pack/skills/ 下的技能都会被自动发现和加载，会话重启（--continue / --resume）后依然生效。

自动发现会跳过 node_modules、.git、dist、build、coverage 等常见无关目录。

技能文件格式：

---
name: my-skill
description: "简要描述技能的功能和触发条件"
---

# 技能标题

具体的指令内容...

记忆系统

TIL 使用双层记忆系统：

对话历史（短期记忆）

当前会话内的完整消息历史，存储在 ~/.til/sessions/ 目录（JSONL 格式）。

MEMORY.md（长期记忆）

由 AI 自动判断写入，跨会话持久化：

| 文件 | 作用 | |------|------| | ~/.til/MEMORY.md | 全局记忆（偏好、通用模式） | | .til/MEMORY.md | 项目记忆（架构决策、进行中的工作） |

AI 会在以下情况主动记录：用户偏好、项目架构、问题修复模式、重要决策等。

AGENTS.md（项目上下文）

手动维护的项目指令：

| 文件 | 作用 | |------|------| | ~/.til/AGENTS.md | 全局指令 | | <项目>/AGENTS.md | 项目指令 |

也兼容 CLAUDE.md 文件名。

会话持久化

每次对话自动保存，退出时显示恢复命令。

til --continue          # 恢复最近的会话
til --resume abc12345   # 恢复指定会话
/sessions               # 交互模式中查看会话列表

Context 压缩

当长对话接近模型上下文窗口上限时自动触发：

当已用 token 超过阈值（默认 70%）时压缩
保留最近对话，将历史部分生成摘要
溢出时自动压缩后重试

实时显示使用率：

  in:12.3k out:1.2k  ctx:35%

in 输入 token · out 输出 token · ctx 上下文占用率

安全拦截

内置危险命令检测：递归删除、提权操作、磁盘格式化、权限修改等。执行前会要求确认。

常见问题

提示"未配置模型"

til --setup   # 运行配置向导

提示 No API key found

export OPENAI_API_KEY=your-key   # 环境变量
til --setup                      # 或配置向导

如何使用国内 LLM（MiniMax / 智谱 / DeepSeek 等）

til --setup
# 模型: MiniMax-M2.5（或 deepseek-chat, glm-5 等）
# API Key: 你的 key
# Base URL: https://api.minimaxi.com/v1（或对应平台的 URL）

如何使用本地模型（Ollama）

ollama serve
til --setup
# Base URL: http://localhost:11434/v1
# Model ID: llama3.1:8b

API 连接失败怎么排查

/config check   # 显示当前配置并测试 API 连接

如何启用浏览器工具

browser 工具基于 agent-browser，已内置为依赖。只需在配置中将 browser 加入 defaultTools：

{
  "defaultTools": ["bash", "read", "write", "edit", "system_info", "file_manager", "web_search", "web_fetch", "screenshot", "computer", "browser"]
}

agent-browser 会自动发现系统中的 Chrome。如果没有 Chrome，运行 npx agent-browser install 下载。

开发

git clone https://github.com/antaif3ng/til-work.git
cd til-work
npm install
npm run dev     # 监听模式编译
npm run build   # 一次性编译
npm start       # 运行
npm test        # 运行测试

项目结构

til-cli/
├── src/
│   ├── main.ts              # CLI 入口 & 配置向导
│   ├── version.ts           # 版本号管理
│   ├── core/
│   │   ├── agent.ts         # 双层循环 Agent 引擎
│   │   ├── llm.ts           # LLM 提供商抽象（Anthropic/OpenAI/Google）
│   │   ├── config.ts        # 配置管理 & 模型解析
│   │   ├── session.ts       # 会话包装（工具 + 系统提示）
│   │   ├── session-manager.ts  # 会话持久化（JSONL）
│   │   ├── types.ts         # 核心类型（含 ImageContent）
│   │   ├── compaction.ts    # Context 压缩 & 溢出检测
│   │   ├── pricing.ts       # Token 用量格式化
│   │   ├── tool-permissions.ts  # 危险命令拦截
│   │   ├── markdown.ts      # 终端 Markdown 渲染
│   │   ├── memory.ts        # 记忆系统
│   │   ├── skills.ts        # 技能系统（内置 + 用户 + 项目 + 工作区包）
│   │   └── system-prompt.ts # 系统提示词组装
│   ├── modes/
│   │   ├── interactive.ts   # 交互 REPL 模式
│   │   └── oneshot.ts       # 单次执行模式
│   ├── tools/               # 内置工具
│   │   ├── bash.ts          # Shell 命令执行
│   │   ├── read.ts          # 文件读取（含图片 base64）
│   │   ├── write.ts         # 文件写入
│   │   ├── edit.ts          # 精确替换
│   │   ├── file-manager.ts  # 文件操作
│   │   ├── system-info.ts   # 系统信息
│   │   ├── web-search.ts    # 网页搜索
│   │   ├── web-fetch.ts     # 网页抓取
│   │   ├── screenshot.ts    # 截图
│   │   ├── computer.ts      # Computer Use（鼠标/键盘/截图）
│   │   └── browser.ts       # 浏览器控制（agent-browser CLI）
│   ├── extensions/          # 扩展系统
│   │   ├── types.ts         # 扩展/MCP 类型定义
│   │   ├── loader.ts        # 扩展加载器
│   │   ├── runner.ts        # 扩展运行器
│   │   └── builtin/mcp.ts   # MCP 客户端（stdio + HTTP）
│   └── utils/               # 工具函数
├── skills/                  # 内置技能
│   ├── summarize/
│   ├── find-skills/
│   ├── self-improving-agent/
│   ├── skill-creator/
│   ├── agent-browser/
│   ├── excel-xlsx/
│   ├── word-docx/
│   └── nano-pdf/
├── tests/                   # 单元测试
├── package.json
├── tsconfig.json
└── vitest.config.ts

许可证

MIT