dsh-agents-group

配置

字段	默认	说明
accessMode	authenticated	standalone 仅用于本机调试
publicOrigin	空	认证模式必填，HTTP(S) origin，不带路径
routePrefix	/agents	群组根前缀；各 Agent 是它的子路径
authRecheckMs	1000	认证复核间隔
agents..enabled	true	是否装载该 Agent
agents..models.allow / .deny	空	模型白名单，留空＝不过滤

业务凭据走群组级 runtimeConfig 文件（AGENTS_GROUP_CONFIG 指向），不进 Git、不进镜像。

关于模型白名单这个代价

宿主的模型目录是全局扁平的，没有 scope 机制：provider 一旦注册，全进程可见。所以 「只让某个 Agent 看到某些模型」只能在群组侧过滤，白名单由我们自己维护，宿主新增 provider 时不会自动生效。

业务存储配置与迁移

博客的业务数据（草稿、写作任务、操作记录、审计、附件记录、译文留档）只存在 PostgreSQL 一种后端（Q4 口径）。索引库——会话、对话请求与结果、协作映射——仍是各自的 blog.sqlite， 与业务存储无关。

缺配置或运行中连不上都算「blog 未就绪」，不算群组装载失败：页面、目录条目、参与者照常 注册，群组探针照常在线，博客的业务端点以稳定错误码拒绝（PG 不可达是 503 + storage_unreachable）， /agents/blog/ready 正文写明原因与配置方法。绝不静默回退 SQLite。

PostgreSQL 配置（三路来源，按优先级）

1. 环境变量 AGENTS_GROUP_PG_DSN：直接给连接串（开发/测试最方便）。
2. 环境变量 AGENTS_GROUP_PG_CONFIG 指向的私有配置文件。
3. 都没设时的缺省路径：/plugins/agents-group/env.conf（存在才读）。

文件两种写法都认：一行 AGENTS_GROUP_PG_DSN=postgresql://…，或 {"dsn":"postgresql://…"}。 站点部署推荐把 dsn 直接写在群组配置的顶层——DSH_PLUGIN_CONFIG.agents-group 里与各 Agent 小节并列（模板见 config/group.example.json）——构建时派生成上面第 3 路的文件，DSH 同时把 它挂载给群组装配，一份文件满足两条读取路径。凭据只走环境变量与私有配置，绝不写进 cordis 配置或 plugin.json。每组独立数据库与独立运行账号，库内表按插件前缀平铺（博客用 blog_ 前缀），将来其他 Agent 迁入各管各的表与版本行。

初始化结构

生产库由 private-deploy/db/create.mjs 按 private-deploy/db/0001_init.sql 一次建出 （15 张表 + 20 个显式 CREATE INDEX，含约束隐式共 39 个），版本行写进 dsh_schema_versions 的四行（butler / blog / closedoff / runtime = 1）。插件启动只核验版本，缺表或版本不符即 拒绝读写，不自动建表、不自动改版本。

⚠️ 本包内的 agents/blog/migrations/postgres/0001_init.sql 是上一代 DDL（owner + data TEXT 旧列 + blog_schema_version 版本表），不再被生产使用，只为随包保留的迁移工具而留。 别拿它当权威：生产形状以 private-deploy/db/0001_init.sql 为准。测试也必须按后者建 schema， 否则"实现与生产 DDL 漂移"在测试里永远发现不了（agents/blog/tests/pg-smoke.test.ts 已经改成读它）。

存量迁移（SQLite → PostgreSQL）

拆库前 blog.sqlite 里的业务 5 表与译文库 reasoning-translations.sqlite 用一次性工具 dist/migrate-blog-storage.mjs 迁移（pg 驱动已打进产物，归档内可直接 node 运行）：

node dist/migrate-blog-storage.mjs --blog  [--translations ] \
  --dsn  [--dry-run] [--clear-source --backup ]

### PostgreSQL 配置（三路来源，按优先级）

1. 环境变量 `AGENTS_GROUP_PG_DSN`：直接给连接串（开发/测试最方便）。
2. 环境变量 `AGENTS_GROUP_PG_CONFIG` 指向的私有配置文件。
3. 都没设时的缺省路径：`/plugins/agents-group/env.conf`（存在才读）。

文件两种写法都认：一行 `AGENTS_GROUP_PG_DSN=postgresql://…`，或 `{"dsn":"postgresql://…"}`。
站点部署推荐把 dsn 直接写在群组配置的顶层——`DSH_PLUGIN_CONFIG.agents-group` 里与各 Agent
小节并列（模板见 `config/group.example.json`）——构建时派生成上面第 3 路的文件，DSH 同时把
它挂载给群组装配，一份文件满足两条读取路径。凭据只走环境变量与私有配置，**绝不写进 cordis
配置或 `plugin.json`**。每组独立数据库与独立运行账号，库内表按插件前缀平铺（博客用 `blog_`
前缀），将来其他 Agent 迁入各管各的表与版本行。