Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,8 @@ The Superpowers plugin is disabled for this repository. Do not invoke or follow

## Useful Source Anchors

- [docs/session-sharing.md](docs/session-sharing.md): 会话邀请、只读/可交互权限、访客提问和对端工具。

- [src/apps/tui/commands/builtin_commands.cpp](src/apps/tui/commands/builtin_commands.cpp): slash command registration and command help.
- [src/adapters/tool/tool_executor.cpp](src/adapters/tool/tool_executor.cpp): tool registry behavior, tool result message formatting, and compact call previews.
- [src/engine/agent/event_payload/tool_event_payload.cpp](src/engine/agent/event_payload/tool_event_payload.cpp): web serialization of tool progress and summaries.
Expand Down
9 changes: 9 additions & 0 deletions assets/acecode.desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
[Desktop Entry]
Type=Application
Name=ACECode
Exec=acecode-desktop --open-invite %u
TryExec=acecode-desktop
Icon=acecode
Terminal=false
Categories=Development;
MimeType=x-scheme-handler/acecode;
4 changes: 4 additions & 0 deletions cmake/acecode_desktop.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ if(NOT ACECODE_BUILD_DESKTOP)
return()
endif()

if(UNIX AND NOT APPLE)
install(FILES "${CMAKE_SOURCE_DIR}/assets/acecode.desktop" DESTINATION share/applications)
endif()

include(FetchContent)

if(ACECODE_DEEPIN)
Expand Down
2 changes: 2 additions & 0 deletions cmake/acecode_layer_libraries.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,8 @@ elseif(UNIX AND NOT APPLE)
endif()

acecode_collect_group_sources(_domain domain)
# domain/share is owned by acecode_domain; host/session_share and host/peers are
# collected by acecode_host below, keeping transport out of the domain layer.
acecode_add_layer_library(acecode_domain domain ${_domain})
target_link_libraries(acecode_domain PUBLIC acecode_base_core
PRIVATE unofficial::sqlite3::sqlite3)
Expand Down
8 changes: 8 additions & 0 deletions cmake/macos/ACECodeDesktopInfo.plist.in
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key><string>ACECode Invitation</string>
<key>CFBundleURLSchemes</key><array><string>acecode</string></array>
<key>CFBundleTypeRole</key><string>Viewer</string>
</dict>
</array>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>
<key>CFBundleDisplayName</key>
Expand Down
49 changes: 49 additions & 0 deletions docs/daemon-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -6767,3 +6767,52 @@ Runtime-generated names use underscore separators. Existing hyphen-named data re
会话模型(元数据 `model_activated_at_ms`;旧记录按最后用户消息兼容)。
摘要模型已选择但无效不静默回退。`MODEL_UNAVAILABLE`、`TIMEOUT`、
`GENERATION_FAILED`、`INVALID_RESPONSE` 均保留旧结果。推断不创建会话、不调用工具。


## 会话分享与对端

完整说明见 [会话分享](session-sharing.md)。主人和本机对端管理接口沿用 daemon 鉴权;访客只使用 `X-ACECode-Share` 请求头,不能将分享码当作 daemon token。分享凭据不放在 HTTP 或 WebSocket URL 中。

### 主人接口

| 方法与路径 | 请求 / 返回 |
| --- | --- |
| `POST /api/sessions/:id/shares` | `{mode: "read_only" / "interactive", visibility: "conversation" / "tools", expires_in: 秒}`;201 返回记录及 `link`。默认可交互、只看对话、86400 秒;有效期 60–2592000 秒 |
| `GET /api/shares` | `{shares: [...]}`;有效记录可再次复制链接,带 `active`、`revoked`、`expires_at` |
| `DELETE /api/shares/:share_id` | 撤销凭据,立即关闭该分享现有访客连接 |
| `GET /api/shares/:share_id/asks` | `{asks: [...]}`,脱敏后的时间、访客名、问题、答案和取消状态,最多 200 条 |
| `GET /api/config/desktop-clipboard` | `{ok, enabled}` |
| `PUT /api/config/desktop-clipboard` | `{enabled: boolean}`,按现有配置事务即时保存 |

`mode` 决定能否聊天,`visibility` 决定工具内容是否可见,两者独立。dangerous 模式拒绝创建;无法由 daemon 加载的 TUI 主会话不可分享。分享数据不进入 `config.json`。

局域网转发在远程 Web 开启或存在有效分享时运行。仅开启分享时,经转发进入的完整 token 也被拒绝。`web.remote_port=0` 优先尝试 12400,再尝试 daemon 相邻端口,最后由系统分配;链接记录实际监听端口。显式固定端口的已有语义保持不变。

### 访客接口

| 方法与路径 | 行为 |
| --- | --- |
| `POST /api/share/v1/hello` | 版本、主人、会话标题、对端身份、内容档位、提问权限、剩余额度及 `resets_at` |
| `GET /api/share/v1/messages?limit=100&before=cursor` | 投影后的 `messages`、`before`、`has_older`;使用既有历史游标格式,每页最多 200 条 |
| `GET /api/share/v1/turns?cursor=...` | 既有 ThreadService 的有界回合摘要,标记外部不可信来源 |
| `GET /api/share/v1/attachments/:id/blob` | 仅返回被分享会话中允许显示的图片;不提供文件浏览能力 |

访客接口从凭据解析只读授权对象,只访问其中的会话 ID;凭据缺失、无效、撤销、过期均不返回内容。会话未加载时后台恢复。访客 HTTP 不接受浏览器 Origin,接收方必须由自己的 daemon 代连。

`WS /ws/share/v1` 同样使用请求头鉴权。只接受 `subscribe`、`unsubscribe`、`ping`、`ask_start {question, name}` 和 `ask_stop`。返回 `hello`、`changed`、已脱敏 `token`、`progress`、`ask_delta {text, reset}`、`ask_done {answer, cancelled, error, remaining, resets_at}`、`error`、`pong`。其它消息不能影响主会话。

只读分享的 `ask_start` 返回 `read_only`,不调用模型或工具、不扣额度。可交互分享每码并发 1 次、UTC 每日 30 次;额度错误为 `question_busy` 或 `daily_limit`,后者携带恢复时间。提问使用分享者会话模型、独立的只读工具循环,无转发主会话能力,不写主会话历史。

### 本机对端接口

| 方法与路径 | 行为 |
| --- | --- |
| `POST /api/peers/connect` | `{link}`;仅在前端确认后调用,解码、逐个地址握手并保存,返回对端公共信息 |
| `GET /api/peers` | `{peers: [...]}`,只回显凭据末四位 |
| `DELETE /api/peers/:id` | 删除已保存对端并关闭本机中继连接 |
| `GET /api/peers/:id/messages?before=cursor` | 本机 daemon 代读历史 |
| `GET /api/peers/:id/attachments/:attachment_id/blob` | 本机 daemon 代读图片,校验 MIME 类型并禁止内容嗅探 |

`WS /ws/peers/:id` 使用本机 daemon 的常规鉴权,转发以上访客协议,不接受主会话输入、审批或中止消息。网页不加载对端页面或脚本,完整分享凭据保留在 daemon 存储。已保存对端跨工作区共用;同一身份、同一会话的新邀请更新已有记录。

跨机器图片经过本机接口,远程 `visual` 代码块只显示源码。私有/链路本地/唯一本地地址及单段主机名优先直连,不受系统或手动代理影响。
2 changes: 1 addition & 1 deletion docs/design/interface-icons.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ node scripts/preview_web_icons.mjs --output=icon-gallery.html

## 范围

当前共有 109 个注册名称:86 个既有公开资源、22 个从组件抽出的符号和独立的 Expert 图标。MCP 服务器统一使用插头;专家入口使用人头轮廓加齿轮,均为空心描线;模型与推理仍使用 Brain。`interfaceIcons.test.js` 核对注册与公开文件一一对应、无固定色、线宽、真实组件渲染、ARIA、面板状态及文件类型独立渲染。
当前共有 123 个注册名称。MCP 服务器统一使用插头;专家入口使用人头轮廓加齿轮,均为空心描线;模型与推理仍使用 Brain。分享操作使用 Share(开口方框加穿出的上箭头,方框与 ChatBubble 同宽),已分享会话的状态标记使用 Antenna(发射信号的天线,侧栏按 18 px 显示,与同一行其它图标一致)。`interfaceIcons.test.js` 核对注册与公开文件一一对应、无固定色、线宽、真实组件渲染、ARIA、面板状态及文件类型独立渲染。

保留原样的内容:ACECode/供应商品牌 Logo、原生应用/托盘资源、Seti 字体与文件类型映射、PPTX 文件类型图标、统计图和动态百分比仪表。操作用 Document/Folder/OpenFile 属于功能图标,仍使用本规范。

Expand Down
9 changes: 7 additions & 2 deletions docs/desktop-shell/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,8 +271,13 @@ All four are additive; no existing daemon invocations change behavior.

### 8.6 Deep links (`acecode://`)

- Out of scope for v1. Stub the protocol handler registration so we can
ship it later without re-touching installer logic.
- `acecode://connect/<payload>` opens a session invitation confirmation. No
network request is made until the user confirms. Windows uses a per-user
protocol registration and the existing second-instance open-request handoff.
- `DesktopInviteController` owns invitation delivery, clipboard deduplication
and notification activation. macOS receives URL Apple events; Linux registers
a desktop entry and uses a per-user Unix datagram wakeup. Platform and real
network acceptance remains tracked in `add-acecode-invite-links`.

---

Expand Down
9 changes: 9 additions & 0 deletions docs/desktop-shell/multi-workspace.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,15 @@ daemon slot 已启动,并向 daemon `POST /api/workspaces` 注册 cwd,返回同

## 关键文件

邀请桥接由 [invite_controller.cpp](../../src/apps/desktop/invite_controller.cpp) 管理:

- `aceDesktop_getInviteClipboardPreference()` 读取当前原生识别开关。
- `aceDesktop_applyInviteClipboardPreference(enabled)` 应用已由 daemon 保存的开关,不另写配置文件。
- `aceDesktop_markInviteSeen(link)` 抑制应用自己复制的邀请。
- `acecode:open-invite` 事件携带 `{link}`;页面未就绪时在内存中排队。
- `--open-invite` 与工作区/会话打开请求互斥,第二实例交接后退出。


| 路径 | 作用 |
|---|---|
| `src/base/workspace/workspace_registry.{hpp,cpp}` | 扫盘 / 读写 `workspace.json` / 默认命名 |
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
54 changes: 54 additions & 0 deletions docs/session-sharing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# 会话分享

在会话标题栏「属性」左侧点击分享图标,选择链接权限、可见内容和有效期,再生成链接。

| 链接权限 | 访客能力 |
| --- | --- |
| 只读 | 查看历史、图片和实时进展,没有聊天入口 |
| 可交互 | 在查看之外进行独立提问;使用分享者的模型和受限只读工具 |

「只看对话 / 含工具输出」独立于链接权限。默认可交互、只看对话、一天过期。复制邀请包含主人名、会话标题和链接;复制链接只复制 URL。存在有效分享的会话在侧栏显示发射天线图标。侧栏快捷菜单中的「分享与连接」管理有效分享、提问记录和已保存对端。

## 连接与权限

链接格式为 `acecode://connect/<base64url>`,载荷是 UTF-8 JSON 加四字节大端 CRC32,不带 Base64 填充,最长 1024 字符。CRC32 只检测损坏;链接是访问凭据,编码不提供加密。第一版使用明文 HTTP/WebSocket,仅适用于可信局域网,不提供公网穿透或 TLS。

JSON 短键:`v` 版本、`n` 主人、`t` 会话标题、`a` 候选地址、`p` 端口、`c` 分享凭据、`e` Unix 秒过期时间。未知字段忽略,未知主版本拒绝。凭据由 16 位十六进制分享标识、点和 32 个 Base64URL 字符组成;随机 secret 为 192 位。

系统协议、剪贴板和输入框粘贴统一进入确认框,显示主人、标题和地址。确认之前不进行网络请求。取消粘贴识别后,原文回到输入框原光标位置。

Windows 安装器及绿色版启动时按当前用户注册协议,无需提权;已有的另一个有效安装不会被覆盖,卸载只移除自己的关联。第二实例用现有的 open-request 交接文件传递邀请。macOS 在应用信息中声明协议并接收 URL 事件;Linux 通过 `.desktop` 和 `xdg-mime` 注册,第二实例通过每用户 Unix socket 唤醒主窗口。

访问私有、链路本地、IPv6 唯一本地地址及单段电脑名时强制直连。候选地址依次尝试,每个地址连接最多三秒,电脑名优先、物理网卡其次、虚拟网卡最后。自动监听端口依次尝试 12400、daemon 相邻端口、系统分配端口;显式 `web.remote_port` 保持固定端口语义。

## 访客提问

提问在分享者机器上执行,复用侧边对话的流式循环。可用工具只有当前会话本来允许的只读文件、搜索和 LSP 工具。额外禁止 `.env*`、私钥、证书、`.npmrc`、`.netrc`、`.git-credentials` 等路径;搜索结果也经过过滤。访客不能转发消息给主会话、改文件、执行 shell、审批或中止主任务。

问题不写入主会话历史、不占用主会话忙碌状态。每个分享码同时最多一个提问,默认每天 30 次,按 UTC 日期重置,响应带下一次恢复时间。检查在调用模型之前进行;只读链接的提问不会消耗额度。

历史、实时输出和答案都经过脱敏。为避免密钥跨流式片段泄露,未完整的文本行及 PEM 块先缓冲,再脱敏发送。脱敏规则不能识别所有可能的秘密,分享者仍应选择适当的内容档位。

## 存储与撤销

- `<data_dir>/shares/shares.json` 保存分享记录、secret、权限、过期时间及日额度,采用 JSON 文件事务。
- `<data_dir>/shares/<share_id>.asks.jsonl` 保存已脱敏提问记录,每条分享最多 200 条。
- `<data_dir>/peers.json` 保存已确认的对端,所有工作区共用。前端列表只获得凭据末四位。

撤销先使凭据失效并关闭现有连接。只要存在有效分享,局域网转发可以独立于远程 Web 开关运行;远程 Web 关闭时,经转发进入的完整 daemon token 也无法访问管理接口。最后一条分享失效且远程 Web 未开时停止转发。

接收方网页只访问自己的 daemon。对方的网页、脚本、样式不被加载;可执行 `visual` 块显示源码,Markdown 外部图片不自动请求,允许的会话图片经本机鉴权接口读取。

## 剪贴板

Windows 使用剪贴板变化通知,后台或托盘状态下先显示通知,点击后再确认;macOS 只在窗口激活时检查。在读取前尊重禁止监视、禁止历史和平台隐私设置,只检查前 8 KiB;普通文本不落盘、不记录、不外发。同一邀请每个进程只提示一次;应用自己复制的邀请不会提示自己连接。

设置 → 常规的「识别剪贴板中的会话邀请」即时保存,默认开启。关闭后仍可主动打开协议链接或粘贴到输入框。macOS 的 URL 模式探测是否识别自定义协议仍需真机验证,验证状态见 OpenSpec 任务清单。

## AI 工具

`list_peers` 列出已保存对端,`read_peer_session` 读取有界回合摘要,`ask_peer_session` 向可交互对端提问。后两者只接受 `peer_id`,不能自行指定网络地址或分享码。工具在 TUI、daemon、headless 启动期固定注册;所有结果明确标记 `external_untrusted`,不应把返回文本当作操作指令。

若访客让自己的 AI 调用提问工具,访客自己的模型调用和分享者回答问题的模型调用分别消耗各自额度。

接口见 [daemon API](daemon-api.md)。实现边界为 `domain/share`、`host/session_share`、`host/peers` 和 Web 独立访客路由。
2 changes: 2 additions & 0 deletions openspec/changes/add-acecode-invite-links/.openspec.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-14
Loading
Loading