内容
# AI 助手 - 知识工作者的 AI 助手
一款由 Claude、Skills 和 MCP（模型上下文协议）驱动的智能 AI 助手，帮助知识工作者进行定期自动监控和交互式查询。
与以下 MCP 服务器配合使用：
- [DCI MCP Server](https://github.com/redhat-community-ai-tools/dci-mcp-server) 用于 DCI 和 Jira
- [Second Brain](https://github.com/flepied/second-brain-agent) 用于个人笔记
- 任何其他兼容 MCP 的服务器
与以下技能配合使用：
- [pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md)
- [markdown-converter](https://github.com/intellectronica/agent-skills/blob/main/skills/markdown-converter/SKILL.md)
- 任何其他 [技能](https://skills.sh/)
## 功能
- 🤖 **AI 驱动**：Claude Sonnet 4.5 实现智能分析
- 🔌 **MCP 集成**：连接任意 MCP 服务器以获取工具和数据
- 📊 **监控**：自动定时检查，智能通知
- ⏰ **定时操作**：一次性未来操作，带通知
- 💬 **交互模式**：丰富的终端用户界面，支持流式响应和历史记录
- 🧠 **知识图谱**：跟踪实体和变化的时间数据库
- 📝 **报告生成**：创建和管理 Markdown 报告
- ⚡ **热重载**：调度更改立即生效
- 🚀 **代理技能**：按照 [agentskills.io](https://agentskills.io/) 规范安装专用技能
- 🔄 **AWL 工作流**：使用条件语句、循环和变量传播编写多步骤代理工作流
## 快速入门
### 前提条件
选择一种身份验证方法：
- **Vertex AI**（谷歌云）：企业/公司 Claude 访问权限
- **直接 API**（Anthropic）：个人使用，免费层
### 安装
首先，安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)（如果尚未安装）：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
然后安装 ai-assist：
```bash
git clone https://github.com/fredericlepied/ai-assist
cd ai-assist
uv sync
```
### 配置
```bash
cp .env.example .env
# 使用您的凭证编辑 .env
```
**Vertex AI**（谷歌云）：
```bash
export ANTHROPIC_VERTEX_PROJECT_ID='your-gcp-project-id'
gcloud auth application-default login
```
**直接 API**（Anthropic - 免费层可用）：
```bash
export ANTHROPIC_API_KEY='sk-ant-...' # 从 console.anthropic.com 获取
```
📖 **Vertex AI 设置：** 参见 [VERTEX_AI_SETUP.md](VERTEX_AI_SETUP.md)
**个性化**（可选）：
自定义助手的个性和沟通风格：
```bash
uv run ai-assist /identity-init # 创建模板
uv run ai-assist /identity-show # 查看当前设置
```
编辑 `~/.ai-assist/identity.yaml` 以配置：
- 您的姓名、角色和组织
- 助手昵称和个性
- 通信偏好（正式程度、详细程度、表情符号使用）
- 更好的协助工作环境
📖 **完整身份指南：** 参见 [docs/IDENTITY.md](docs/IDENTITY.md)
**日志记录**（可选）：
控制调试和监控的日志详细程度：
```bash
# 文件日志级别（默认：INFO）
export AI_ASSIST_LOG_LEVEL=DEBUG
# 控制台日志级别（默认：WARNING）
export AI_ASSIST_CONSOLE_LOG_LEVEL=INFO
```
日志写入到：`~/.ai-assist/logs/ai-assist-YYYY-MM-DD.log`
📖 **日志指南：** 参见 [docs/LOGGING.md](docs/LOGGING.md)
## 使用
### 交互模式
使用丰富的终端用户界面与助手聊天：
```bash
uv run ai-assist /interactive
# 或简单地
uv run ai-assist
```
**功能：**
- 🎨 丰富的 Markdown 格式，支持语法高亮
- 📝 多行编辑（Esc-Enter 换行）
- 📚 命令历史，支持搜索（Ctrl-R）
- ⌨️ 命令补全
- ⚡ 流式实时响应
- 🛑 使用 Escape 键取消流式传输
- 🧠 知识图谱持久存储对话记忆
- 💾 每晚自我反思，从对话中提取知识
**内置命令：**
- `/status` - 显示统计信息
- `/history` - 最近的监控历史
- `/clear` - 清除对话记忆
- `/clear-cache` - 清除响应缓存
- `/kg-save [on|off]` - 切换知识图谱自动保存
- `@no-kg <query>` - 禁止为单个查询注入 KG 上下文
- `/kg-viz` - 在浏览器中可视化知识图谱
- `/awl-viz [script.awl]` - 在浏览器中将 AWL 工作流可视化为交互式流程图
- `/prompts` - 列出可用的 MCP 提示及其参数
- `/prompt-info <server/prompt>` - 显示详细的提示信息
- `/skill/install <source>@<branch>` - 安装代理技能
- `/skill/uninstall <name>` - 卸载代理技能
- `/skill/list` - 列出已安装的代理技能
- `/skill/search <query>` - 搜索 ClawHub 和 skills.sh 注册表
- `/skill/add_env <skill> <VAR>` - 为技能的脚本允许环境变量
- `/skill/remove_env <skill> <VAR>` - 从技能中删除允许的环境变量
- `/skill/list_env [skill]` - 显示技能的允许环境变量
- `/plan <task>` - 在执行前计划任务（探索 → 批准 → 执行）
- `/mcp/restart <server>` - 重启 MCP 服务器（获取二进制更新）
- `/help` - 显示帮助
- `/exit` 或 `/quit` - 退出
**安全性：
当命令不在允许列表中时，助手会提示确认：
```
Allow? [y/N/a(lways)]
```
- **y** - 允许一次
- **N** - 拒绝（默认）
- **a(lways)** - 允许并永久添加到允许列表
**示例查询：**
```
最近失败的 DCI 作业是什么？
显示 CILAB 项目中的关键 Jira 票
查找过去一周内失败的 OpenShift 4.19 作业
```
### MCP 提示
直接使用斜杠命令执行 MCP 服务器提示：
```bash
# 在交互模式下
/dci/rca # 运行 dci 服务器上的 RCA 提示
/prompts # 列出所有可用的提示
```
MCP 提示可以交互式地请求参数，并自动执行，带有流式结果。
### 代理技能
按照 [agentskills.io](https://agentskills.io) 规范安装专用技能：
```bash
# 在交互模式下
/skill/install anthropics/skills/skills/pdf@main # 从 GitHub 安装 PDF 技能
/skill/install /path/to/my-skill@main # 安装本地技能
/skill/list # 列出已安装的技能
/skill/uninstall pdf # 卸载技能
/skill/search pdf # 搜索 ClawHub 和 skills.sh
```
**什么是代理技能？**
- 遵循 agentskills.io 标准的 Claude 专用指令
- 自动加载到系统中（无需激活）
- 可以包括脚本、引用和资产
📖 **创建个人技能：** 参见 [docs/PERSONAL_SKILLS.md](docs/PERSONAL_SKILLS.md)
- 跨会话持久化
**示例技能：**
- PDF 处理（提取文本、填充表单、合并）
- DOCX 操作
- 自定义工作流自动化
- 领域特定专业知识
**创建自己的技能：**
```bash
mkdir -p my-skill
cat > my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: 我的自定义技能
---
# 我的技能指令
当用户询问 X 时，请执行 Y...
EOF
uv run ai-assist
You> /skill/install /path/to/my-skill@main
```
📖 **技能规范：** 参见 [agentskills.io/specification](https://agentskills.io/specification)
#### 脚本执行（高级）
技能可以包括 `scripts/` 目录中的可执行脚本。**默认情况下，出于安全考虑，脚本执行是禁用的。**
**启用脚本执行：**
```bash
export AI_ASSIST_ALLOW_SCRIPT_EXECUTION=true
uv run ai-assist
```
**安全要求：**
- 技能必须在 SKILL.md 中声明权限：
```yaml
allowed-tools: "internal__execute_skill_script"
```
- 脚本在沙盒环境中运行：
- 无权访问 API 密钥或机密（环境过滤）
- 通过 `/skill/add_env` 进行技能环境变量允许列表（持久存储在 `~/.ai-assist/skill_env.json` 中）
- 30 秒超时限制
- 输出限制为 20KB
- 禁止目录遍历
- 不可能发生 shell 注入
**带有脚本的示例技能：**
```markdown
---
name: pdf-tools
description: PDF 处理实用程序
compatibility: 需要 python3、python3-pypdf
allowed-tools: "internal__execute_skill_script"
---
# PDF 工具
运行 `scripts/check_fillable_fields.py` 以检测表单字段。
```
📋 **安全详情：** 参见 [SECURITY.md](SECURITY.md) 获取完整的安全模型
#### 上下文窗口
Claude 4.6+ 模型（Opus 4.6、Opus 4.7、Sonnet 4.6）具有本地 1M token 上下文窗口 - 无需选择加入或额外配置。
#### 自适应上下文限制
截断限制会根据上下文窗口自动缩放。默认情况下，每个消息限制为上下文窗口的 5%，所有消息限制为 60%。
您可以通过环境变量调整这些百分比：
```bash
export AI_ASSIST_MESSAGE_LIMIT_PCT=5 # 每条消息的最大 %（1-20，默认：5）
export AI_ASSIST_TOTAL_MESSAGES_PCT=60 # 所有消息的最大 %（20-80，默认：60）
export AI_ASSIST_RESERVE_PCT=25 # 系统提示 + 输出的保留 %（10-40，默认：25）
```
### 监控模式
运行具有自动检查的定期监控：
```bash
uv run ai-assist /monitor
```
- 从 `~/.ai-assist/event-event-schedules.json` 运行操作
- 自动保存发现到知识图谱
- 当计划或操作更改时热重载（FileWatchdog）
- 在重要更新时发送通知
- 优雅地处理笔记本电脑暂停（赶上错过的运行）
- **执行计划的一次性操作**（事件驱动，无轮询）
**通过交互模式创建监视器：**
```bash
uv run ai-assist
You: 创建一个每 5 分钟检查一次失败的 DCI 作业的监视器
```
**为定期任务启用通知：**
在 `event-event-schedules.json` 中的任何操作中添加 `notify` 和 `notification_channels`：
```json
{
"version": "2.0",
"actions": [
{
"name": "critical-failures",
"prompt": "检查关键的 DCI 故障",
"trigger": {"type": "interval", "every": "1h"},
"notify": true,
"notification_channels": ["desktop", "file"]
},
{
"name": "daily-summary",
"prompt": "总结昨天的 DCI 作业",
"trigger": {"type": "schedule", "at": "9:00", "days": "weekdays"},
"notify": true,
"notification_channels": ["console"]
}
]
}
```
当 `notify` 为 true 时，您将通过以下方式接收任务完成通知：
- **desktop**：系统通知（Linux 上的 notify-send）
- **file**：追加到 `~/.ai-assist/notifications.log`
- **console**：在 `/monitor` 输出中显示
- 交互模式在 TUI 中自动显示来自任何通道的通知
- 最近的通知（最近 15 分钟）被注入交互式代理的上下文中，以便您可以提出后续问题
### 事件驱动操作
通过 MQTT、D-Bus 或文件系统更改对外部事件做出反应。`~/.ai-assist/event-event-schedules.json` 中的操作使用统一的 **trigger + prompt** 模型。D-Bus 触发器支持每个触发器的总线选择（`system` 或 `session`）。
**示例：USB 设备监控**
```json
{
"event_sources": { "dbus": {} },
"actions": [
{
"name": "USB 文件系统已挂载",
"trigger": {
"type": "dbus",
"interface": "org.freedesktop.DBus.Properties",
"signal": "PropertiesChanged",
"bus": "system",
"payload_contains": "MountPoints"
},
"prompt": "已挂载一个 USB 文件系统。描述该设备。",
"notify": true,
"notification_channels": ["desktop", "console", "file"]
}
]
}
```
**示例：解锁屏幕时的“欢迎回来”简报**
```json
{
"actions": [
{
"name": "屏幕锁定",
"trigger": {
"type": "dbus",
"interface": "org.gnome.ScreenSaver",
"signal": "ActiveChanged",
"bus": "session",
"payload_contains": "True"
},
"prompt": "保存当前时间戳到屏幕锁定时间报告。",
},
{
"name": "欢迎回来简报",
"trigger": {
"type": "dbus",
"interface": "org.gnome.ScreenSaver",
"signal": "ActiveChanged",
"bus": "session",
"payload_contains": "False"
},
"prompt": "用户刚刚解锁了屏幕。读取屏幕锁定时间报告，检查最近的通知，并总结用户离开了多长时间以及发生了什么。",
"notify": true,
"notification_channels": ["desktop", "console", "file"]
}
]
}
```
**示例：对目录中的新文件做出反应**
```json
{
"event_sources": { "file": {} },
"actions": [
{
"name": "新 PDF 下载",
"trigger": { "type": "file", "path": "~/Downloads/*.pdf" },
"prompt": "刚刚下载了一个 PDF。总结一下。",
"notify": true,
"notification_channels": ["desktop", "console"]
}
]
}
```
文件触发器支持确切的路径 (`/etc/app/config.json`)、目录 (`~/Downloads` - 任何文件更改）和 glob 模式 (`~/Downloads/*.pdf`)。
**触发器类型**：`interval`、`schedule`、`interval_range`、`once`、`mqtt`、`dbus`、`file`
**事件过滤**：`payload_contains` 和 `payload_regex` 在执行前过滤事件。突发信号会被 debounce（3 秒窗口）。
**可选依赖项**：`pip install ai-assist[mqtt]` 用于 MQTT，`pip install ai-assist[dbus]` 用于 D-Bus。文件监视使用 `watchdog` 库（默认包含）。
代理还可以创建/更新/删除运行时内置工具的操作（`internal__create_action`、`internal__list_actions` 等）。
### 计划操作
安排一次性未来操作，自动执行并带有通知：
```bash
uv run ai-assist /interactive
You: 2 小时后提醒我检查作业状态 job-456
```
代理将：
- 将操作安排在 2 小时后执行
- 在到期时自动执行（通过 `/monitor` 进程）
- 完成时发送桌面通知 + 文件日志
**支持的时间格式：**
- `in X hours/minutes/days` - 相对时间
- `tomorrow at 9am` - 第二天特定时间
- `next monday 10:00` - 特定日期和时间
**通知渠道：**
- **desktop**：系统通知（Linux 上的 notify-send）
- **file**：追加到 `~/.ai-assist/notifications.log`
- **console**：在 `/monitor` 输出中显示
- **TUI**：在交互模式下自动显示（监视通知日志）
- 交互模式在 TUI 中自动显示来自任何通道的通知
**代理决策：**
代理智能决定如何执行计划操作：
- “提醒我看电视” → 简单通知（无需代理查询）
- “告诉我我的 Gmail 邮箱里有什么” → 通过代理查询，通知结果
- “检查失败的作业并保存报告” → 通过代理查询，保存到报告
**查看计划操作：**
```bash
cat ~/.ai-assist/scheduled-actions.json
```
**查看通知历史：**
```bash
tail -f ~/.ai-assist/notifications.log
```
**管理计划操作：**
已完成且失败的操作，旧版本（> 7 天）会自动存档到 `~/.ai-assist/scheduled-actions-archive.jsonl`。
```bash
# 手动清理
uv run ai-assist /cleanup-actions
# 查看存档
cat ~/.ai-assist/scheduled-actions-archive.jsonl | jq
```
**文件结构：**
- `scheduled-actions.json` - 活动和最近（≤ 7 天）的操作
- `scheduled-actions-archive.jsonl` - 历史操作（> 7 天旧）
**⚠️ 重要：** `/monitor` 进程必须运行，计划操作才能执行：
```bash
uv run ai-assist /monitor # 在后台保持运行
# 或安装为持久的 systemd 用户服务：
ai-assist /service install # 默认实例 (~/.ai-assist)
ai-assist /service install ~/.iris # 附加实例
```
**注意：** systemd 用户服务仅在您登录时运行。要在启动时启动服务：
```bash
sudo loginctl enable-linger $USER
```
参见 [docs/MULTI_INSTANCE.md#systemd-services](docs/MULTI_INSTANCE.md#systemd-services) 获取详细信息。
#### 沙箱实例（容器隔离）
在隔离的 podman-compose 堆栈中，以每个服务凭证隔离的方式运行 ai-assist。
每个 MCP 服务器都在自己的容器中运行，只看到自己的机密：
```bash
# 构建容器镜像
make sandbox-build # 基础 + dci-mcp-server
make sandbox-build-dev # 开发配置文件（添加 Go、Ansible、uv、shellcheck、yamllint）
# 创建和配置实例
ai-assist /sandbox init my-agent # 所有功能，基础镜像
ai-assist /sandbox init my-agent --features=ssh,git # 仅 ssh 和 git
ai-assist /sandbox init my-agent --image=ai-assist-dev # 使用开发镜像和额外工具
cp ~/.ai-assist-instances/my-agent/.env.example ~/.ai-assist-instances/my-agent/.env
# 使用凭证编辑 .env，编辑 sandbox/.ai-assist/identity.yaml
# 在沙箱中运行查询、AWL 脚本或监控
ai-assist /sandbox run my-agent /query "今天有什么失败？"
ai-assist /sandbox run my-agent /run workflow.awl
ai-assist /sandbox run my-agent /monitor
# 管理实例
ai-assist /sandbox list
ai-assist /sandbox stop my-agent
ai-assist /sandbox delete my-agent
```
# 安装为持久的 systemd 服务（运行 /monitor）
ai-assist /sandbox service my-agent install
ai-assist /sandbox service my-agent status
ai-assist /sandbox service my-agent logs -f
ai-assist /sandbox service my-agent stop
ai-assist /sandbox service my-agent remove
## 可用功能
可用功能：`ssh`（代理转发），`gpg`（提交签名），`git`（gitconfig），`gh`（GitHub CLI），`dci`（DCI MCP 服务器），`dbus`（会话总线）。
Vertex AI（gcloud）始终包含。默认：所有功能启用。
## 镜像配置文件
镜像配置文件允许为每个工作负载使用不同的工具链。基础镜像（`ai-assist-sandbox`）仅具有运行时 essentials。
`sandbox/profiles/`中的自定义配置文件扩展了它 - 例如，`ai-assist-dev`添加了 Go、Ansible、Python 开发工具、shellcheck 和 yamllint。
## 实例目录布局
```
~/.ai-assist-instances/my-agent/
compose.yaml # host-only: 堆栈定义
.env # host-only: 凭证（从不挂载）
sandbox/ # 绑定挂载到 ai-assist 容器
.ai-assist/ # 配置、状态、日志、KG
reports/ # 输出报告
workspace/ # 代理工作区
```
## MCP 服务器
MCP 服务器通过 SSE 传输连接，而不是 stdio。在 `mcp_servers.yaml` 中配置 URL：
```yaml
servers:
dci:
url: "http://dci-mcp-server:8001/sse"
```
## 实例根目录
实例根目录可通过 `AI_ASSIST_INSTANCES_DIR` 配置（默认：`~/.ai-assist-instances`）。
## MCP 提示在任务中
直接从定期任务执行 MCP 提示，以实现一致的自动化工作流：
### 自然语言（Traditional）
```json
{
"tasks": [
{
"name": "系统检查",
"prompt": "查找过去 24 小时内的故障",
"interval": "1h"
}
]
}
```
### MCP 提示（新）
```json
{
"tasks": [
{
"name": "每日 RCA 报告",
"prompt": "mcp://dci/rca",
"prompt_arguments": {
"days": "1",
"status": "failure"
},
"interval": "8:00 on weekdays"
}
]
}
```
### 格式
`mcp://server_name/prompt_name`
### 优点
- 直接执行 - 无需解释
- 一致的结果 - 相同的提示，相同的输出
- 参数支持 - 传递结构化数据
- 更少的令牌使用 - 无翻译层
### 通过交互模式创建
```bash
uv run ai-assist /interactive
# 自然语言任务
You: 创建一个每小时检查一次故障的任务
# MCP 提示任务（具体说明格式）
You: 创建一个名为“Weekly Report”的任务，运行 mcp://tpci/weekly_report
参数“for”设置为“Semih”，在星期一 10:45
```
## 发现
```bash
uv run ai-assist /interactive
# 列出所有提示及其参数
/prompts
# 查看特定提示的详细信息（参数、描述、示例)
/prompt-info tpci/weekly_report
```
## 单次查询
```bash
uv run ai-assist /query "今天哪些 DCI 作业失败次数最多？"
```
## AWL 工作流
使用 AWL（Agent Workflow Language）脚本运行多步骤代理工作流：
```bash
uv run ai-assist /run workflow.awl
uv run ai-assist /run workflow.awl project=CILAB days=7
```
初始变量可以作为 `key=value` 参数传递，并在脚本中作为 `${key}` 使用。
AWL 脚本定义意图驱动的工作流，代理自主选择工具：
```
@start
@task find_handlers @no-kg model=haiku
目标：查找存储库中定义的 HTTP 处理程序。
Expose: handlers
@end
@if len(handlers) > 0
@loop handlers as handler limit=5 collect=summaries(handler_summary)
@task inspect_handler @no-history model=sonnet
目标：了解 ${handler} 的作用。
Expose: handler_summary
@end
@end
@end
@end
```
任务参数：
- `@no-kg`，`@no-history`，`@continue-on-failure` — 上下文和错误处理提示
- `max_tool_calls=N` — 覆盖工具调用预算（默认：100）
- `max_time=N` — 覆盖超时时间（秒）（默认：600）
- `model=<name>` — 为此任务使用不同的模型；支持别名（`haiku`，`sonnet`，`opus`）或完整名称；加载时验证
循环支持 `collect=<var>` 以跨迭代累积结果（map-reduce 模式）。使用 `collect=<var>(<fields>)` 仅捕获特定字段。
## 可用工具
### 内置工具
#### 报告管理
- `write_report` - 创建/覆盖 markdown 报告
- `append_to_report` - 将内容添加到报告
- `read_report` - 读取报告内容
- `list_reports` - 列出所有报告
- `delete_report` - 删除报告
报告存储在 `~/ai-reports/`（可通过 `AI_ASSIST_REPORTS_DIR` 配置）。
#### 操作管理
- `create_action` - 创建定期或事件驱动的操作
- `list_actions` - 列出所有操作
- `update_action` - 更新操作属性
- `delete_action` - 删除操作
- `enable_action` - 启用/禁用操作
- `get_action_status` - 获取操作执行状态
操作存储在 `~/.ai-assist/event-event-schedules.json` 中，支持热加载。
#### 规划
- `think` - 复杂多步骤任务的规划和推理草稿
#### JSON 处理（需要安装 `jq`）
- `json_query` - 使用 jq 过滤器表达式查询或转换 JSON 文件
- `__jq_filter` 参数 - 在任何工具调用上应用 jq 过滤器（无需文件）
#### 文件系统工具
- `read_file` - 读取文件，支持行范围
- `write_file` - 将内容写入文件（创建父目录）
- `edit_file` - 文件中进行外科手术式的字符串替换（精确匹配，必须唯一）
- `search_in_file` - 文件中正则表达式搜索
- `create_directory` - 创建目录
- `list_directory` - 列出目录内容
- `execute_command` - 执行 bash 命令
### MCP 服务器工具
所有来自配置的 MCP 服务器的工具都自动可用。在 `~/.ai-assist/mcp_servers.yaml` 中配置服务器：
```yaml
servers:
dci:
command: "uvx"
args: ["--from", "dci-mcp-server", "dci-mcp-server"]
env:
DCI_CLIENT_ID: "${DCI_CLIENT_ID}"
DCI_API_SECRET: "${DCI_API_SECRET}"
```
## 状态管理
`~/.ai-assist/` 中存储的持久状态：
```
~/.ai-assist/
├── state/ # 监视器状态和缓存
├── knowledge_graph.db # 时序数据库（SQLite）
├── event-schedules.json # 监视器/任务定义
├── mcp_servers.yaml # MCP 服务器配置
├── allowed_commands.json # 永久允许的命令
├── skill_env.json # 按技能划分的环境变量允许列表
└── interactive_history.txt # 命令历史
```
## 项目结构
```
ai-assist/
├── ai_assist/ # 主包
│ ├── main.py # CLI 入口点
│ ├── agent.py # 具有工具执行的 MCP 代理
│ ├── think_tool.py # 规划/推理草稿工具
│ ├── monitors.py # 监视任务
│ ├── state.py # 状态管理和缓存
│ ├── knowledge_graph.py # 时序知识图谱
│ ├── awl_ast.py # AWL AST 节点定义
│ ├── awl_parser.py # AWL 工作流语言解析器
│ ├── awl_expressions.py # AWL 表达式求值器
│ ├── awl_runtime.py # AWL 工作流执行引擎
│ ├── awl_visualization.py # AWL 工作流流程图可视化
│ └── filesystem_tools.py # 文件系统操作
├── emacs/ # AWL 文件的 Emacs 主模式
├── tests/ # 测试套件
├── .env.example # 示例环境变量
├── VERTEX_AI_SETUP.md # Vertex AI 故障排除
├── SECURITY.md # 安全模型
├── CONTRIBUTING.md # 开发设置
└── AGENTS.md # 开发理念
```
## 文档
- **[docs/AWL_SPECIFICATIONS.md](docs/AWL_SPECIFICATIONS.md)** - AWL（Agent Workflow Language）规范
- **[docs/PERSONAL_SKILLS.md](docs/PERSONAL_SKILLS.md)** - 创建和管理个人代理技能
- **[docs/IDENTITY.md](docs/IDENTITY.md)** - 完整指南：`identity.yaml` 配置
- **[docs/LOGGING.md](docs/LOGGING.md)** - 日志记录配置和故障排除
- **[docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md)** - 运行多个 ai-assist 实例
- **[VERTEX_AI_SETUP.md](VERTEX_AI_SETUP.md)** - Vertex AI 配置和故障排除
- **[SECURITY.md](SECURITY.md)** - 技能脚本执行的安全模型
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - 开发设置与 pre-commit 钩子
- **[AGENTS.md](AGENTS.md)** - 开发理念（TDD/DRY/Tracer Bullet）
- **[presentation/](presentation/)** - 项目演示文稿幻灯片（LaTeX/Beamer）
## 开发
### 自动重载
配置文件在监视器和交互模式下自动被监视和重载：
- **`mcp_servers.yaml`** - 重新连接到更改的 MCP 服务器
- **`identity.yaml`** - 更新身份和系统
- **`installed-skills.json`** - 重新加载代理技能
- **`event-schedules.json`** - 重新启动监视器和任务（仅监视器模式）
更改立即生效，无需手动重启。
### 代码自动重载（开发模式）
使用 `--dev` 标志启用代码更改时的自动进程重启：
```bash
# 监视器模式，代码监视
uv run ai-assist --dev /monitor
# 交互模式，代码监视
uv run ai-assist --dev /interactive
```
这在开发过程中非常有用，可以立即看到代码更改的效果。
## 需求
- Python 3.12+
- Anthropic API 访问（Vertex AI 或直接 API）
- MCP 服务器（可选但推荐）
- `jq`（可选，启用 `internal__json_query` 工具进行高效 JSON 处理）
## 许可证
参见 LICENSE 文件获取详细信息。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器