```

feat(learning): 添加技能学习候选者合成锁定机制

添加了 DraftSynthesisInProgress 和 DraftHasNoChanges 异常来处理并发场景，
确保同一技能学习候选者的合成过程不会重复执行。实现了 claim_learning_candidate_for_synthesis
方法来原子性地锁定候选者进行合成。

fix(web): 为技能草案创建端点添加适当的HTTP状态码

当草案没有变化或正在合成时，现在正确返回409状态码而不是内部错误。

feat(skills): 实现技能修订内容比较以检测无变化情况

添加了 _is_noop_revision 方法来比较基础技能和提议的修订，
如果内容没有实际变化则抛出 NoDraftChanges 异常。

refactor(process): 修复任务证据记录后根运行状态更新逻辑

将任务证据记录事件后的状态从 waiting 更改为 done，并设置 finished_at 时间戳。

feat(tools): 防止在同一运行中重复执行外部写入操作

为邮件发送、日历创建等外部写入工具添加去重机制，避免重复的外部操作。

test: 添加技能学习和工具执行的单元测试

增加测试用例验证并发草案合成、重复外部写入抑制和无变化修订检测等功能。
```

域名配置指引.md

@@ -1,5 +1,7 @@
 # Beaver Project 域名配置指引
 
+最后更新：2026-06-16。
+
 这份文档说明如何从本机测试域名 `localhost` 子域名切换到正式域名。
 
 核心结论：
@@ -9,6 +11,7 @@
 - `auth-portal` 和用户实例建议使用不同域名。
 - 正式环境建议用外层 Nginx、Caddy、Traefik 或云负载均衡监听 `80/443`。
 - `router-proxy` 必须收到原始 `Host` 头，才能按实例域名转发。
+- 正式实例入口推荐使用真实域名；不要用裸 IP 当实例基域名，除非你明确要走每实例直连端口模式。
 
 ## 1. 默认端口职责
 
@@ -18,6 +21,9 @@
 | `8088` | `router-proxy`，所有实例统一入口 | 可以，或由外层代理转发 |
 | `8090` | `deploy-control`，内部部署控制面 | 不建议 |
 | `19090` | `authz-service`，内部鉴权服务 | 不建议 |
+| `8787` | `external-connector` sidecar 管理/调试口 | 不建议 |
+| `9000/9001` | 本地 MinIO S3 API / Console | 不建议 |
+| `20000-29999` | app-instance 直连端口池，通常绑定 `127.0.0.1`，裸 IP 模式可能对外绑定 | 不建议 |
 
 正式部署时，通常由外层入口暴露 `80/443`，再转发到本机端口：
 
@@ -91,6 +97,8 @@ proxy_set_header X-Forwarded-Proto $scheme;
 
 否则 `router-proxy` 无法知道请求属于哪个实例。
 
+如果需要支持用户文件系统的大文件上传，外层代理还要允许足够大的 body。项目内 app-instance Nginx 当前是 `client_max_body_size 5g`，外层 Nginx/Caddy/负载均衡的限制不能比实际业务需求更小。
+
 ## 5. 项目内部要改哪些变量
 
 实例公网地址由 `deploy-control` 里的这些变量决定：
@@ -101,6 +109,7 @@ proxy_set_header X-Forwarded-Proto $scheme;
 | `DEPLOY_PUBLIC_BASE_DOMAIN` | 实例基域名，例如 `apps.example.com` |
 | `DEPLOY_PUBLIC_HOST_TEMPLATE` | Host 生成模板，默认 `{slug}.{base_domain}` |
 | `DEPLOY_PUBLIC_PORT` | 对外端口，`80` / `443` 会在生成 URL 时省略 |
+| `DEPLOY_DIRECT_PUBLIC_HOST_BIND_IP` | 仅裸 IP 基域名直连模式使用，控制实例宿主机端口绑定地址 |
 
 本机测试：
 
@@ -144,6 +153,20 @@ https://alice.apps.example.com
 
 前提是外层代理已经把 `*.apps.example.com:443` 转发到 `router-proxy:8088`。
 
+裸 IP 特例：
+
+```bash
+export BEAVER_BASE_DOMAIN=203.0.113.10
+```
+
+当 `DEPLOY_PUBLIC_BASE_DOMAIN` 是 IP 地址时，`deploy-control` 会进入直连端口模式：每个实例从 `20000-29999` 端口池分配一个宿主机端口，生成类似：
+
+```text
+http://203.0.113.10:20037
+```
+
+这不是 `router-proxy` 的 Host 路由入口，也无法得到 `https://alice.apps.example.com` 这类实例子域名。正式环境推荐使用 `apps.example.com` 这类真实域名和通配 DNS。
+
 ## 6. 什么时候 URL 里可以不带端口
 
 浏览器默认端口：
@@ -225,6 +248,8 @@ apps.example.com        -> 服务器 IP
 *.apps.example.com      -> 服务器 IP
 ```
 
+正常域名部署不依赖 `DEPLOY_DIRECT_PUBLIC_HOST_BIND_IP`；它只影响裸 IP 直连端口模式。生产入口应优先让外层代理监听 `80/443`，再转发到本机 `3081` 和 `8088`。
+
 ## 8. Nginx 外层代理示例
 
 示例只展示关键转发逻辑，证书路径和自动签发方式按你的环境调整。
@@ -261,6 +286,7 @@ server {
   ssl_certificate_key /etc/letsencrypt/live/apps.example.com/privkey.pem;
 
   location / {
+    client_max_body_size 5g;
     proxy_http_version 1.1;
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
@@ -309,14 +335,27 @@ portal.example.com  -> 3081
 *.apps.example.com  -> 8088
 ```
 
-### 不要公开 8090 和 19090
+### 不要公开内部端口
 
 `8090` 是部署控制面，`19090` 是内部 AuthZ 服务。它们应该只允许容器网络或可信内网访问。
 
+同理，本地 MinIO 的 `9000/9001`、`external-connector:8787` 和实例直连端口池 `20000-29999` 也不应该作为正式公网入口。正式入口通常只有：
+
+```text
+https://portal.example.com
+https://<slug>.apps.example.com
+```
+
+外层代理再把它们分别转发到本机 `3081` 和 `8088`。
+
 ### 修改 DEPLOY_PUBLIC_* 后旧实例不会自动改 URL
 
 这些变量影响新创建实例的 `public_url` 和 `instance_host`。旧实例已经写入注册表，需要重新创建或手动更新注册表和代理配置。
 
+### 裸 IP 不是通配子域名
+
+如果 `DEPLOY_PUBLIC_BASE_DOMAIN=203.0.113.10`，系统会生成 `http://203.0.113.10:<host_port>` 形式的直连地址，不会生成可用的 `alice.203.0.113.10` 子域名入口。要使用每用户子域名，必须准备真实域名并配置 `*.apps.example.com` 这类通配 DNS。
+
 ## 10. 本机测试不需要正式域名
 
 如果只是本机验证完整链路，继续使用：