andrielfn/annotai

Annotai 是一个专为 Phoenix/LiveView 应用开发的开发者注释小部件（dev-only annotation widget）。你只需点击运行页面上的一个元素并留下备注，它就会连同所有 AI 编码智能体（AI coding agent）处理所需的信息（包括 CSS 选择器、`phx-*` 属性以及渲染该元素的 HEEx `file:line`）直接发送给智能体。 ## 功能 - **元素注释。** 点击页面上的任意元素并留下备注。Annotai 会找出它在代码中的具体位置。 - **文本注释。** 选择一段文本并对其进行注释。 - **图片附件。** 将截图粘贴或拖拽到备注中。 - **源码位置。** 每条备注都附带了渲染该元素的 HEEx `file:line`，因此智能体可以直接打开正确的文件。 - **进程内 MCP server。** 智能体通过 MCP 与 Annotai 通信。无需额外运行任何程序。它直接驻留在你正在运行的 Phoenix 应用内部。 - **深色与浅色模式。** 该小部件会跟随你的系统主题。 - **Phoenix 感知。** 它会直接读取 `phx-*` 属性和 LiveView 的 HEEx 注释。 - **仅限开发环境。** 它作为单一 plug 挂载在 `:dev` 环境下，绝不会进入生产环境。 ## 安装说明 将 Annotai 添加到 `mix.exs` 的开发依赖（dev deps）中： ``` def deps do [ {:annotai, "~> 0.1", only: :dev} ] end ``` 然后将 plug 添加到你的 endpoint 中，置于 `if code_reloading? do` 代码块之前： ``` # lib/my_app_web/endpoint.ex if Mix.env() == :dev do plug Annotai end ``` 并开启 source mapping 配置，以便 Annotai 能够找到对应的 `file:line`： ``` # config/dev.exs config :phoenix_live_view, debug_heex_annotations: true, debug_attributes: true ``` 使用 [Igniter](https://hexdocs.pm/igniter)？安装程序会自动为你完成这两个步骤： ``` mix igniter.install annotai ``` ## 连接你的智能体 Annotai 提供了一个 MCP endpoint，你的智能体只需注册一次即可。将 `4000` 替换为你的开发服务器端口。 ### Claude Code ``` claude mcp add --transport http annotai http://localhost:4000/annotai/mcp ``` ### Codex Codex 在其配置文件中注册 HTTP server。将以下内容添加到 `~/.codex/config.toml` 中： ``` [mcp_servers.annotai] url = "http://localhost:4000/annotai/mcp" ``` 启动你的应用，该小部件就会出现在右下角。你所注释的任何内容都会通过以下工具传递给智能体： | 工具 | 用途 | | --- | --- | | `annotai_get_pending` | 列出等待智能体处理的注释。 | | `annotai_get_annotation` | 获取单条注释，包括其回复线程。 | | `annotai_acknowledge` | 标记为“我已看到并正在处理”。 | | `annotai_resolve` | 标记为已解决（可选择附上更改摘要）。 | | `annotai_dismiss` | 拒绝一条注释，并说明理由。 | | `annotai_reply` | 在注释的线程中添加消息。 | | `annotai_watch_annotations` | 等待新注释，实现免手动干预的循环。 | 状态转换受到保护，因此注释不会被重复解决或拒绝，你也不会陷入奇怪的状态中。 ### 技能 Annotai 提供了一个技能，可引导你的智能体完成整个循环：在编辑前确认备注、打开确切的 `file:line`、进行更改、验证更改，最后附上简短摘要将其解决。它适用于任何智能体，位于 [`skills/fix-annotations/SKILL.md`](skills/fix-annotations/SKILL.md)。 对于 Claude Code，将其放入 `.claude/skills/fix-annotations/`（当前项目）或 `~/.claude/skills/fix-annotations/`（全局），开启一个全新会话并输入 `/fix-annotations`： ``` mkdir -p .claude/skills/fix-annotations curl -fsSL https://raw.githubusercontent.com/andrielfn/annotai/main/skills/fix-annotations/SKILL.md \ -o .claude/skills/fix-annotations/SKILL.md ``` 其他智能体（如 Codex、Cursor 等）可以通过各自的规则设置读取同一个文件。 ## 位置 该小部件位于右下角。如果其他开发工具已经占据了该位置（例如 LiveDebugger 的按钮就在同一位置），你可以使用 `:position` 将 Annotai 移开： ``` # config/dev.exs config :annotai, position: [bottom: 20, right: 220] ``` 这些键是 CSS insets，就像 `position: fixed` 一样：`:top`、`:bottom`、`:left` 和 `:right` 分别代表距离相应边缘的距离。整数值表示像素，字符串则按原样传递（如 `"2rem"`）。最多设置 `:top`/`:bottom` 中的一个，以及 `:left`/`:right` 中的一个；如果省略某个轴，则保持其 20px 的默认值。 小部件锚定的角落由你指定的边缘共同决定，其面板也会从该角落展开： ``` config :annotai, position: [bottom: 20, left: 20] # bottom-left corner config :annotai, position: [top: 20, right: 20] # top-right corner config :annotai, position: [bottom: 20, right: 220] # bottom-right, slid left of another widget ``` 无效的值将被忽略并输出日志警告，同时使用默认位置。 ## 持久化 注释保存在内存中，应用重启时会被清除。这对于快速的开发循环来说没问题，但重启会导致你尚未处理的注释丢失。如果你希望它们能保留下来，可以开启本地快照： ``` # config/dev.exs config :annotai, persistence: true ``` 这会将快照写入 `.annotai/annotations.ets`，因此请将该文件添加到你的 `.gitignore` 中。想要移动存储位置，或者限制已解决历史记录的保留时间？可以改为传递以下选项： ``` config :annotai, persistence: [ path: ".annotai/annotations.ets", ttl: {14, :day} ] ``` - `path` 是快照的存放位置，相对于应用的工作目录。 - `ttl` 是保留**已解决或已拒绝**备注的时间，超过此时间后将进行清理。默认值 `:infinity` 会保留所有记录。无论时间多长，未解决的备注永远不会被清理。接受 `{n, :second | :minute | :hour | :day}` 格式的值。 快照会在每次更改后稍作延迟写入（它们会被打包在一起），并在启动时读取。它是纯 ETS 快照数据，而不是数据库，因此无需进行迁移，也没有 schema 需要处理。保留的历史记录仅存放在你的机器上，绝不会发送给智能体。它的工具只能看到那些仍需处理的备注。 ## 禁用 Annotai 默认开启。要彻底关闭它（不显示小部件，也不注册 `/annotai/*` 路由），请切换此配置项： ``` # config/dev.exs config :annotai, enabled: false ``` 或者通过环境变量控制： ``` # config/dev.exs config :annotai, enabled: System.get_env("DISABLE_ANNOTAI") != "true" ``` 然后运行 `DISABLE_ANNOTAI=true mix phx.server`，Annotai 就不会产生任何干扰了。

标签：AI编程助手, Elixir, LiveView, MCP, Phoenix, SOC Prime, 代码注解, 开发工具, 自定义脚本